run

#!/usr/bin/env bash
#
# usage: ./run command [argument ...]
#
# Commands for Skip development.
#

set -o nounset
set -o pipefail
set -o errexit

# Change the current directory to the project root.
PROJECT_ROOT=${0%/*}
if [[ $0 != $PROJECT_ROOT && $PROJECT_ROOT != "" ]]; then
  cd "$PROJECT_ROOT"
fi
readonly PROJECT_ROOT=$(pwd)

################################################################################
# Development Commands

function dev {
  #@ Run the dev server (serve-path /@halos-org/skip/)
  #@ Category: Development
  npm run dev
}

################################################################################
# Build Commands

function build {
  #@ Build the production webapp bundle (output -> public/)
  #@ Category: Build
  npm run build:prod
}

function build-dev {
  #@ Build the development webapp bundle (output -> public/)
  #@ Category: Build
  npm run build:dev
}

################################################################################
# Deploy Commands

function deploy-halos {
  #@ Build locally and install onto a HaLOS device's Signal K as a durable dependency
  #@ Category: Deploy
  local target="${1:-}"
  if [[ -z "$target" ]]; then
    echo "Usage: ./run deploy-halos <target_host>"
    echo ""
    echo "Builds the production bundle locally, then installs it into the target"
    echo "device's Signal K data volume as a declared file: dependency. Because the"
    echo "dependency is declared, a later 'npm install' (e.g. adding another plugin)"
    echo "no longer prunes it -- unlike a bare copy into node_modules, which it does."
    echo ""
    echo "Pass 'local' when running on the device itself; a hostname deploys over"
    echo "ssh (needs ssh access + passwordless sudo on the target). The build runs"
    echo "on the machine you invoke this from -- keep that a dev/build host."
    echo ""
    echo "Examples:"
    echo "  ./run deploy-halos local         # on the device itself"
    echo "  ./run deploy-halos halpi.hurma   # from a dev machine, over ssh"
    return 1
  fi

  local pkg slug data sysdir dest
  pkg=$(node -p "require('./package.json').name")   # e.g. @halos-org/skip
  slug="${pkg##*/}"                                  # e.g. skip
  data="/var/lib/container-apps/marine-signalk-server-container/data/data"
  sysdir="${data}/system-plugins/${slug}"

  # 'local'/'localhost' runs every step on this box; any other target goes over
  # ssh. `runner` executes a bash script (fed via stdin heredoc) in either place.
  local -a runner
  if [[ "$target" == local || "$target" == localhost ]]; then
    dest=""; runner=(bash -s --)
  else
    dest="${target}:"; runner=(ssh "$target" bash -s --)
  fi

  echo "==> Building production bundle (locally)..."
  build

  echo "==> Preparing ${dest}${sysdir} (backing up any existing install)..."
  "${runner[@]}" "$sysdir" "$data" <<'PREP'
set -o errexit -o nounset -o pipefail
sysdir="$1"; data="$2"
# Refuse a host that has no Signal K container app rather than creating the hierarchy under it.
# The sudo below would otherwise turn a mistyped hostname into a root-owned tree holding a full
# copy of the build, failing only later when the remote step cannot write node_modules.
if [ ! -d "$data" ]; then
  echo "No Signal K container-app data directory at $data." >&2
  echo "Is this a HaLOS device with the Signal K app installed?" >&2
  exit 1
fi
# system-plugins/ belongs to the container-app framework, which creates it as root on a device
# that ships plugins there (signalk-halpi), and the skip/ leaf under it may be root-owned too.
# mkdir -p returns 0 for a directory that already exists whatever its ownership, so writability
# is the thing to test. Hand it to the invoking user so the rsync that follows needs no privilege.
if ! mkdir -p "$sysdir" 2>/dev/null || [ ! -w "$sysdir" ]; then
  sudo mkdir -p "$sysdir"
  sudo chown -R "$(id -u):$(id -g)" "$sysdir"
fi
if [ -n "$(ls -A "$sysdir" 2>/dev/null)" ]; then
  tar -czf "$HOME/$(basename "$sysdir")-predeploy-$(date +%F-%H%M%S).tar.gz" \
    -C "$(dirname "$sysdir")" "$(basename "$sysdir")"
fi
PREP

  # Ship the package's runtime payload: the webapp (public/) and its manifest
  # (package.json). This is a webapp-only package -- the Freeboard-SK plugin lives
  # in the separate @halos-org/skip-freeboard-panel package with its own deploy.
  echo "==> Syncing build to ${target}..."
  rsync -rlpt --delete public/ "${dest}${sysdir}/public/"
  rsync -lpt package.json "${dest}${sysdir}/package.json"

  # The hashed entry bundle names this exact build. It is what the device has to serve
  # for the deploy to have landed; the package being registered and the URL answering
  # 200 are both true of the build it replaced.
  # The assignment has to be the `if` condition: as a bare statement, errexit exits the script on a
  # grep that matches nothing, and the diagnostic below never prints.
  local entry
  if ! entry=$(grep -o 'main-[A-Za-z0-9]*\.js' public/index.html | head -1) || [[ -z "$entry" ]]; then
    echo "No main-<hash>.js in public/index.html; is the build complete?" >&2
    return 1
  fi

  echo "==> Linking, registering the dependency, and (re)starting Signal K if needed..."
  local rc=0
  "${runner[@]}" "$pkg" "$slug" "$data" "$entry" <<'REMOTE' || rc=$?
set -o errexit -o nounset -o pipefail
pkg="$1"; slug="$2"; data="$3"; entry="$4"

# Traefik base URL + device CA (HTTPS, port 4430). Never the container's :3000 --
# host networking only exposes that incidentally; all access goes via Traefik.
ca=/usr/local/share/ca-certificates/halos-ca.crt
domain=$(hostname -d 2>/dev/null || true)
[ -z "$domain" ] && domain=$(awk '/^search/{print $2; exit}' /etc/resolv.conf 2>/dev/null)
base="https://$(hostname)${domain:+.$domain}:4430"

# Does the device serve THIS build? Every weaker check passes for the build being
# replaced: the package stays registered, /skServer/webapps keeps listing it, and the
# URL keeps answering 200. Only the hashed entry bundle distinguishes them.
# Returns 2 when the check itself could not run, so an unreachable app is never reported as a
# stale one. Capturing the body rather than piping into grep also keeps pipefail out of it.
serves_this_build() {
  local body
  body=$(curl -sf --max-time 10 --cacert "$ca" "${base}/${pkg}/" 2>/dev/null) || return 2
  printf '%s' "$body" | grep -qF "$entry"
}

# Link into node_modules exactly as npm does for a file: dependency (scope-aware).
# Remove any existing entry first: when the package is already present as a real
# directory (e.g. an app-store `npm install`), `ln -sfn <target> <dir>` would create
# the link *inside* it (node_modules/<pkg>/<slug>) instead of replacing it, silently
# leaving the old build served.
scope="${pkg%/*}"
link="${data}/node_modules/${pkg}"
rm -rf "$link"
if [ "$scope" != "$pkg" ]; then
  mkdir -p "${data}/node_modules/${scope}"
  ln -s "../../system-plugins/${slug}" "$link"
else
  ln -s "../system-plugins/${slug}" "$link"
fi

# Declare it in package.json so npm treats it as owned and never prunes it.
python3 - "$data" "$pkg" "$slug" <<'PY'
import json, sys
data, pkg, slug = sys.argv[1:4]
path = data + "/package.json"
cfg = json.load(open(path))
deps = cfg.setdefault("dependencies", {})
want = "file:system-plugins/" + slug
if deps.get(pkg) != want:
    deps[pkg] = want
    with open(path, "w") as f:
        json.dump(cfg, f, indent=2)
        f.write("\n")
    print("  registered", pkg, "->", want)
else:
    print(" ", pkg, "already registered")
PY

# Remove a stale bundled plugin/ tree from a prior (pre-webapp-only) deploy.
rm -rf "${data}/system-plugins/${slug}/plugin"

# A content-only update often needs no restart: the webapp mount is registered once at
# server start, but express.static reads public/ from disk per request. Often is not a
# check, so ask the device rather than assuming. Restart through systemd, never docker
# directly -- the unit owns the provision/prestart step and the dependency ordering.
if serves_this_build; then
  echo "  ${pkg} is already serving this build (${entry})"
else
  echo "  ${pkg} is not serving ${entry}; restarting Signal K..."
  sudo systemctl restart marine-signalk-server-container.service
  echo "  waiting for Signal K at ${base} ..."
  for _ in $(seq 1 25); do
    if curl -sf --max-time 10 --cacert "$ca" "${base}/skServer/webapps" >/dev/null 2>&1; then break; fi
    sleep 3
  done
  verdict=0
  serves_this_build || verdict=$?
  if [ "$verdict" -eq 2 ]; then
    echo "  FAIL: ${base}/${pkg}/ could not be fetched after a restart; the deploy is unverified." >&2
    exit 1
  elif [ "$verdict" -ne 0 ]; then
    echo "  FAIL: ${base}/${pkg}/ does not reference ${entry} after a restart." >&2
    echo "        The device is serving a different build than the one just synced." >&2
    exit 1
  fi
fi

# The index naming the bundle is not the same as the bundle being fetchable.
code=$(curl -s -o /dev/null -w '%{http_code}' --max-time 10 --cacert "$ca" "${base}/${pkg}/${entry}" || true)
if [ "$code" != 200 ]; then
  echo "  FAIL: ${base}/${pkg}/${entry} -> HTTP ${code}" >&2
  exit 1
fi
echo "  OK: ${base}/${pkg}/ serves ${entry}"
REMOTE

  if [[ $rc -ne 0 ]]; then
    echo "" >&2
    echo "Deploy FAILED on ${target} (see the error above)." >&2
    return "$rc"
  fi

  echo ""
  echo "Deployed ${pkg} to ${target}, verified serving ${entry}."
  echo "Note: this ships the webapp only. The Freeboard-SK panel is the separate"
  echo "@halos-org/skip-freeboard-panel package -- deploy it too if this device needs"
  echo "the Freeboard toolbar button."
}

################################################################################
# Test Commands

function test {
  #@ Run the unit suite headless (CI mode)
  #@ Category: Test
  npm run test:headless
}

function test-watch {
  #@ Run the unit suite in interactive watch mode
  #@ Category: Test
  npm run test:interactive
}

################################################################################
# Quality Commands

function lint {
  #@ Run ESLint
  #@ Category: Quality
  npm run lint
}

function snc {
  #@ Type-check all sources under strictNullChecks
  #@ Category: Quality
  npm run snc
}

function ci {
  #@ Run all CI checks (lint, snc, tests)
  #@ Category: Quality
  npm run ci
}

################################################################################
# Version Management Commands

function bumpversion {
  #@ Bump version using bumpversion tool (patch|minor|major)
  #@ Category: Version
  local BUMP_TYPE="${1:-}"

  if [[ -z "$BUMP_TYPE" ]]; then
    echo "Error: version bump type required"
    echo "Usage: ./run bumpversion [patch|minor|major]"
    exit 1
  fi

  if [[ ! "$BUMP_TYPE" =~ ^(patch|minor|major)$ ]]; then
    echo "Error: invalid bump type '$BUMP_TYPE'"
    echo "Usage: ./run bumpversion [patch|minor|major]"
    exit 1
  fi

  if ! command -v bumpversion &> /dev/null; then
    echo "Error: bumpversion not installed"
    echo "Install with: uv tool install bump2version"
    exit 1
  fi

  echo "Bumping $BUMP_TYPE version..."
  command bumpversion "$BUMP_TYPE"
  echo "Version bumped and committed successfully"
  echo "New version: $(cat VERSION)"
  echo "Push with: git push"
}

################################################################################
# Help System

function help {
  #@ Show this help message
  #@ Category: Core
  echo "Skip - Development Commands"
  echo "==========================="
  echo ""
  echo "Available commands:"
  echo ""

  # Extract function definitions and their help comments
  awk '/^function / {
    fname = $2
    sub(/[({].*/, "", fname)
    getline
    if ($0 ~ /#@/) {
      desc = $0
      sub(/.*#@ /, "", desc)
      sub(/ *$/, "", desc)
      getline
      if ($0 ~ /#@ Category:/) {
        cat = $0
        sub(/.*Category: /, "", cat)
        sub(/ *$/, "", cat)
        if (!seen[cat]++) categories[++cat_count] = cat
        commands[cat, ++cmd_count[cat]] = fname
        descriptions[cat, cmd_count[cat]] = desc
      }
    }
  }
  END {
    for (i = 1; i <= cat_count; i++) {
      cat = categories[i]
      print "\n" cat ":"
      for (j = 1; j <= cmd_count[cat]; j++) {
        printf "  %-25s %s\n", commands[cat, j], descriptions[cat, j]
      }
    }
  }' "$0"

  echo ""
  echo "Usage: ./run <command> [arguments...]"
  echo ""
}

################################################################################
# Commands end.

TIMEFORMAT=$'\nTask completed in %3lR'
time "${@:-help}"