kampodine 0.4.0 → 0.6.0

package/scripts/deploy.sh

@@ -20,11 +20,26 @@
 #   kampodine deploy --version <sha7>     # stream an existing local build
 #   kampodine deploy --rollback [<sha7>]  # default: previous
 #   kampodine deploy --host root@<ip> ... # target VM override
+#   kampodine deploy --profile <name> ... # per-instance profile (config.json)
 #   kampodine deploy --dockerfile apps/api-go/Dockerfile.cutover  # Go api image
+#   kampodine deploy list|prune|logs|restart|shell  # lifecycle ops (each has --help)
 #   --skip-smoke      # skip the public smoke (behind a not-yet-switched proxy)
 #   --refresh-config  # ansible container-service refresh BEFORE restart
+#   --require-disk <pct>  # fail closed when VM disk usage >= pct (default: warn above 90)
 set -euo pipefail
 
+HERE="$(cd "$(dirname "$0")" && pwd)"
+# Lifecycle subcommands (list/prune/logs/restart/shell) are read-mostly
+# VM/ledger ops — they never build or stream, must work OUTSIDE the app repo,
+# and must not pay the deploy preflight (git/podman). Delegate first.
+case "${1:-}" in
+  list|prune|logs|restart|shell)
+    exec bash "$HERE/deploy-lifecycle.sh" "$@"
+    ;;
+esac
+# shellcheck source=common.sh
+source "$HERE/common.sh"
+
 REPO_ROOT="$(git rev-parse --show-toplevel)"
 KAMPODINE_HOST="${KAMPODINE_HOST:-}"
 PROXY_HOST="${PROXY_HOST:-app.example.com}"
@@ -32,15 +47,21 @@ ENV_FILE_REMOTE="/etc/kampodine/env"
 DEPLOYED_SHA_FILE="/etc/kampodine/deployed-sha"
 ENV_CLEAR_KEYS='^(NODE_ENV|PORT|LIBSQL_TENANT_DIR|LIBSQL_API_MOUNT|STATIC_SPA_MOUNT)='
 IMAGE="127.0.0.1:5000/kampodine-api"
+DISK_PATH="/var/lib/containers"
 
 MODE="deploy"
 VERSION=""
 SKIP_SMOKE=0
 REFRESH_CONFIG=0
+REQUIRE_DISK=""
+PROFILE_FLAG=""
+HOST_FLAG=""
+KEY_FLAG=""
 # SSH key resolution — GENERIC, no hardcoded personal paths:
 #   1. --ssh-key flag           (explicit, per-invocation)
-#   2. KAMPODINE_SSH_KEY env    (project-level: direnv / .envrc / export)
-#   3. empty → ssh-agent and/or the operator's ~/.ssh/config Host block
+#   2. profile sshKey           (--profile | KAMPODINE_PROFILE | defaultProfile)
+#   3. KAMPODINE_SSH_KEY env    (legacy: direnv / .envrc / export)
+#   4. empty → ssh-agent and/or the operator's ~/.ssh/config Host block
 #      (the POSIX way: per-host IdentityFile belongs in ssh config, not here)
 if [ -n "${KAMPODINE_SSH_KEY:-}" ]; then
     SSH_KEY="$KAMPODINE_SSH_KEY"
@@ -57,7 +78,7 @@ die() { printf '\033[1;31m[deploy] FAIL:\033[0m %s\n' "$*" >&2; exit 1; }
 usage() {
   cat <<'EOF'
 Usage:
-  kampodine deploy [--host root@<ip>] [--version <sha7>] [--rollback [<sha7>]]
+  kampodine deploy [--host root@<ip>] [--profile <name>] [--version <sha7>] [--rollback [<sha7>]]
                    [--dockerfile <path>] [--ssh-key <path>] [--skip-smoke] [--refresh-config]
 
 Examples:
@@ -65,16 +86,19 @@ EOF
   grep '^#   kampodine deploy' "$0" | sed 's/^#   //'
   cat <<'EOF'
 
-Host/key resolution: --host | KAMPODINE_HOST; --ssh-key | KAMPODINE_SSH_KEY |
-KAMPODINE_SSH_KEY | ssh-agent / ~/.ssh/config.
+Host/key resolution: --host | --profile <name> | KAMPODINE_PROFILE |
+config defaultProfile | KAMPODINE_HOST; --ssh-key | profile sshKey |
+KAMPODINE_SSH_KEY | ssh-agent / ~/.ssh/config. Profiles:
+kampodine config init --name prod --host root@<ip> --ssh-key <path>.
 EOF
   exit 0
 }
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --host) KAMPODINE_HOST="$2"; shift 2 ;;
-    --ssh-key) SSH_KEY="$2"; shift 2 ;;
+    --host) HOST_FLAG="$2"; KAMPODINE_HOST="$2"; shift 2 ;;
+    --ssh-key) KEY_FLAG="$2"; SSH_KEY="$2"; shift 2 ;;
+    --profile) PROFILE_FLAG="$2"; shift 2 ;;
     --version) VERSION="$2"; MODE="version"; shift 2 ;;
     --rollback)
       MODE="rollback"
@@ -82,13 +106,21 @@ while [[ $# -gt 0 ]]; do
       ;;
     --skip-smoke) SKIP_SMOKE=1; shift ;;
     --refresh-config) REFRESH_CONFIG=1; shift ;;
+    --require-disk) REQUIRE_DISK="$2"; shift 2 ;;
     --dockerfile) DOCKERFILE="$2"; shift 2 ;;
     -h|--help) usage ;;
     *) die "unknown argument: $1 (--help)" ;;
   esac
 done
 [[ "$VERSION" != *..* && "$VERSION" =~ ^[0-9a-f]{4,40}$|^$ ]] || die "--version must be a git sha fragment"
-[ -n "$KAMPODINE_HOST" ] || die "set KAMPODINE_HOST=root@<vm-ip> (or a ~/.ssh/config Host alias via --host)"
+[[ -z "$REQUIRE_DISK" || "$REQUIRE_DISK" =~ ^[0-9]+$ && "$REQUIRE_DISK" -le 100 ]] || die "--require-disk must be a percentage 0-100 (got: $REQUIRE_DISK)"
+# profile resolution (flag > KAMPODINE_PROFILE > defaultProfile); an explicit
+# --host/--ssh-key flag always beats the profile, the profile beats the
+# legacy env; proxyHost from the profile REPLACES the PROXY_HOST env
+profile_resolve "$PROFILE_FLAG" "$HOST_FLAG" "$KEY_FLAG"
+SSH_KEY="${KEY_FLAG:-${KAMPODINE_SSH_KEY:-}}"
+PROXY_HOST="${PROFILE_PROXY_HOST:-${PROXY_HOST:-app.example.com}}"
+[ -n "$KAMPODINE_HOST" ] || die "target required: --host root@<vm-ip>, --profile <name>, KAMPODINE_PROFILE, config defaultProfile, or KAMPODINE_HOST=root@<vm-ip>"
 
 SSH_ARGS=(-o ConnectTimeout=10 -o BatchMode=yes)
 [[ -n "$SSH_KEY" ]] && SSH_ARGS+=(-i "$SSH_KEY")
@@ -102,6 +134,67 @@ if [[ "$(uname -s)" == "Darwin" ]]; then
   export SSH_AUTH_SOCK
 fi
 
+# --- host init detection (first connect): openrc vs systemd + http client ----
+# Groundwork for non-Alpine targets; on Alpine the verdict is openrc and every
+# svc_action output is byte-identical to the historical strings. The verdict
+# is cached in the active profile entry ("init" field) when one resolves.
+init_detect vm >/dev/null 2>&1 || true
+
+# --- deployment ledger: every run appends to ~/.kampodine/deployments.jsonl ---
+# --- {ts, host, sha, tag, result, duration_ms, subject} — shas/tags/hosts  ----
+# --- only, NEVER secrets. The EXIT trap records failures + prints the footer --
+# --- so EVERY deploy run ends with the total deployments count.                --
+DEPLOY_START_SECONDS="$SECONDS"
+DEPLOY_RECORDING=0
+DEPLOY_APPENDED=0
+DEPLOY_RESULT="success"
+ENV_TMP=""
+deploy_on_exit() {
+  local rc=$?
+  [[ -n "$ENV_TMP" ]] && rm -f "$ENV_TMP" 2>/dev/null
+  if [[ "$DEPLOY_RECORDING" -eq 1 && "$DEPLOY_APPENDED" -ne 1 ]]; then
+    # never made it to the append: this run FAILED
+    ledger_append "$KAMPODINE_HOST" "$VER" "$VER" "failed" \
+      $(( (SECONDS - DEPLOY_START_SECONDS) * 1000 )) "" || true
+    DEPLOY_RESULT="failed"
+  fi
+  if [[ "$DEPLOY_RECORDING" -eq 1 ]]; then
+    if [[ "$DEPLOY_RESULT" == "failed" ]]; then
+      say "Total deployments: $(ledger_count "$KAMPODINE_HOST") · FAILED — attempted tag: $VER (not activated)"
+    else
+      say "Total deployments: $(ledger_count "$KAMPODINE_HOST") · current tag: $VER"
+    fi
+  fi
+  exit "$rc"
+}
+trap deploy_on_exit EXIT
+
+# --- disk guard (2026-10-08 incident class: old sha-tagged deploy images ------
+# --- silently filled the VM disk until sqlite writes failed with I/O errors). -
+# --- Read-only VM df; LOUD warning above 90%; --require-disk <pct> fails closed
+# --- BEFORE the build. phase = gate (pre-deploy, may fail) | report (warn-only)
+vm_disk_check() {
+  local phase="${1:-report}" df_out pct verdict
+  df_out="$(vm "df -P $DISK_PATH 2>/dev/null" || true)"
+  pct="$(disk_pct_from_df "$df_out")"
+  verdict="$(disk_verdict "$pct" "$REQUIRE_DISK")"
+  case "$verdict" in
+    fail)
+      die "VM disk at ${pct}% (>= --require-disk ${REQUIRE_DISK}%) — free space first: kampodine deploy prune --dry-run"
+      ;;
+    warn)
+      say "WARNING: VM disk $DISK_PATH at ${pct}% — old sha-tagged deploy images pile up (~1GB each)"
+      say "WARNING: reclaim space: kampodine deploy prune --dry-run (this deploy continues)"
+      ;;
+    unknown)
+      if [[ "$phase" == "gate" && -n "$REQUIRE_DISK" ]]; then
+        die "cannot read VM disk usage (df $DISK_PATH) — --require-disk is fail-closed"
+      fi
+      [[ "$phase" == "gate" ]] && say "disk usage unknown (df unreadable) — continuing"
+      ;;
+  esac
+}
+
 # --- preflight -----------------------------------------------------------------
 cd "$REPO_ROOT"
 if [[ "$MODE" == "deploy" ]]; then
@@ -109,10 +202,15 @@ if [[ "$MODE" == "deploy" ]]; then
 fi
 command -v podman >/dev/null 2>&1 || die "podman not found on the Mac (podman machine must run: podman machine start)"
 podman info >/dev/null 2>&1 || die "podman machine not reachable (podman machine start)"
+# disk gate: BEFORE the build — failing fast beats streaming 1GB into a full disk
+vm_disk_check gate
 # version mode: stream an EXISTING local build (no rebuild, no clean-tree gate —
 # the build already happened when that sha was HEAD)
 [[ "$MODE" == "version" ]] && VER="${VERSION:-$(git rev-parse --short HEAD)}"
 [[ "$MODE" != "version" ]] && VER="$(git rev-parse --short HEAD)"
+# from here on, every outcome is recorded in the ledger (success via the
+# append at the end; anything else via the EXIT trap)
+DEPLOY_RECORDING=1
 
 # --- build (deploy mode always builds HEAD — cached layers keep it minutes) ----
 if [[ "$MODE" == "deploy" ]]; then
@@ -141,7 +239,7 @@ vm "podman tag $IMAGE:$VER $IMAGE:latest" || die "stream retag failed"
 # --- env file from varlock (schema-only from HEAD; secrets from pass) ----------
 say "generating $ENV_FILE_REMOTE from varlock (schema-only from HEAD; secrets resolve from pass — no plaintext secret files)…"
 ENV_TMP="$(mktemp /tmp/kampodine-env.XXXXXX)"
-trap 'rm -f "$ENV_TMP"' EXIT
+# (the EXIT trap — deploy_on_exit — removes $ENV_TMP on every exit path)
 # Schema-only resolution: extract the COMMITTED schema into a scratch dir
 # inside the repo (plugin resolution needs node_modules; local
 # .env/.env.local never enter the pipeline — varlock sees only the extracted
@@ -169,17 +267,20 @@ if [[ $REFRESH_CONFIG -eq 1 ]]; then
     || die "ansible playbook failed"
 fi
 
-say "rc-service kampodine-api restart (supervise-daemon: stop-old/start-new podman run on the retagged :latest)…"
-vm "rc-service kampodine-api restart" || die "kampodine-api restart failed (rc-service kampodine-api status)"
+RESTART_CMD="$(svc_action kampodine-api restart)" \
+  || die "neither rc-service nor systemctl found on $KAMPODINE_HOST — cannot restart the service (host init auto-detection failed)"
+STATUS_CMD="$(svc_action kampodine-api status 2>/dev/null || true)"
+say "$RESTART_CMD (supervise-daemon on Alpine: stop-old/start-new podman run on the retagged :latest)…"
+vm "$RESTART_CMD" || die "kampodine-api restart failed (${STATUS_CMD:-check the service})"
 
-say "health probe (host-side wget /api/auth/ok + served-sha — works for node AND scratch images)…"
+say "health probe (host-side fetch of /api/auth/ok + served-sha — busybox wget default, curl fallback on GNU-only hosts)…"
 HEALTH_OK=0
 for _ in $(seq 1 30); do
-  # wget runs on the VM (busybox, -p 8080:8080 publish); the served-sha
-  # grep runs LOCALLY — remote grep quoting is fragile (busybox BRE
-  # (busybox BRE alternation + nested quotes → permanent false-negative).
-  # grep -E keeps the alternation portable across BSD/GNU/busybox.
-  if vm "wget -qO- -T 3 http://127.0.0.1:8080/api/auth/ok 2>/dev/null" \
+  # the fetch runs on the VM (busybox wget by default; curl when the host has
+  # none — remote_http_cmd in common.sh); the served-sha grep runs LOCALLY —
+  # remote grep quoting is fragile (busybox BRE alternation + nested quotes →
+  # permanent false-negative). grep -E keeps the alternation portable.
+  if vm "$(remote_http_cmd "http://127.0.0.1:8080/api/auth/ok")" \
       | grep -qE "\"(git|build)\":\"$VER"; then
     HEALTH_OK=1
     break
@@ -188,7 +289,7 @@ for _ in $(seq 1 30); do
 done
 if [[ $HEALTH_OK -ne 1 ]]; then
   vm "podman logs --tail 30 kampodine-api 2>&1" || true
-  vm "rc-service kampodine-api status 2>&1" || true
+  vm "$(svc_action kampodine-api status 2>/dev/null || echo 'true') 2>&1" || true
   PREV_HINT="$(vm "test -f $DEPLOYED_SHA_FILE && cat $DEPLOYED_SHA_FILE" 2>/dev/null || true)"
   die "container never became healthy — rollback: kampodine deploy --rollback${PREV_HINT:+ $PREV_HINT}"
 fi
@@ -219,4 +320,21 @@ vm "podman image prune -f >/dev/null 2>&1 || true"
 # busybox head lacks -n -N — tail -n +4 after a newest-first sort keeps 3 tags.
 vm "podman images --format '{{.Tag}} {{.CreatedAt}}' $IMAGE 2>/dev/null | grep -E '^[0-9a-f]{7,40} ' | sort -k2,2r | tail -n +4 | awk '{print \$1}' | while read -r old; do podman rmi \"$IMAGE:\$old\" >/dev/null 2>&1 || true; done" || true
 [[ "$MODE" == "rollback" ]] || vm "echo $VER > $DEPLOYED_SHA_FILE" || true
+
+# --- post-deploy disk report (warn-only — the deploy already succeeded) --------
+vm_disk_check report
+
+# --- deployment ledger append: this run made it all the way through ------------
+DEPLOY_RESULT="success"
+[[ "$MODE" == "rollback" ]] && DEPLOY_RESULT="rollback"
+if [[ "$MODE" == "rollback" ]]; then
+  # the subject of a rollback is the ORIGINAL deploy's subject — the ledger
+  # knows it; git HEAD would be the wrong commit's message
+  SUBJECT="$(ledger_subject_for_tag "$KAMPODINE_HOST" "$VER")"
+else
+  SUBJECT="$(git -C "$REPO_ROOT" log -1 --pretty=%s 2>/dev/null || true)"
+fi
+ledger_append "$KAMPODINE_HOST" "$VER" "$VER" "$DEPLOY_RESULT" \
+  $(( (SECONDS - DEPLOY_START_SECONDS) * 1000 )) "$SUBJECT" || true
+DEPLOY_APPENDED=1
 say "done (version: $VER). instant rollback: kampodine deploy --rollback"

package/scripts/dns.sh

@@ -23,9 +23,21 @@
 #   (all: optional --zone <id-or-name>; --instance-principal for instance auth)
 set -euo pipefail
 
+# NOTE: no $(dirname) here — some hermetic test PATHs strip coreutils;
+# parameter expansion keeps HERE resolution dependency-free.
+HERE="${BASH_SOURCE[0]%/*}"
+# shellcheck source=common.sh
+source "$HERE/common.sh"
+
+# NOTE on --profile: dns.sh follows the OCI auth convention — PROFILE below is
+# the OCI CONFIG profile (OCI_PROFILE). The kampodine INSTANCE profile flag
+# (--profile <name>) is parsed into PROFILE_FLAG and validated via
+# profile_resolve (uniform resolution across every subcommand); dns consumes
+# no instance host/sshKey fields.
 PROFILE="${OCI_PROFILE:-default}"
 COMPARTMENT_NAME="${OCI_COMPARTMENT:-kampodine}"
 AUTH_ARGS=()
+PROFILE_FLAG=""
 
 say() { printf '\033[1;34m[dns]\033[0m %s\n' "$*"; }
 die() { printf '\033[1;31m[dns] FAIL:\033[0m %s\n' "$*" >&2; exit 1; }
@@ -100,12 +112,17 @@ while [[ $# -gt 0 ]]; do
     --type) RTYPE="$2"; shift 2 ;;
     --value) VALUE="$2"; shift 2 ;;
     --ttl) TTL="$2"; shift 2 ;;
+    --profile) PROFILE_FLAG="$2"; shift 2 ;;
     --instance-principal) AUTH_ARGS=(--auth instance_principal); shift ;;
     -h|--help) usage 0 ;;
     *) die "unknown argument: $1 (--help)" ;;
   esac
 done
 
+# validate the kampodine instance profile when selected (uniform resolution);
+# dns consumes none of its host/sshKey fields
+profile_resolve "$PROFILE_FLAG" "" ""
+
 need_provider() {
   command -v oci >/dev/null 2>&1 \
     || die "oci CLI not found — brew install oci-cli (https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/cliinstall.htm), then: oci setup config"

package/scripts/env.sh

@@ -13,16 +13,20 @@
 #   ssh-agent (the POSIX default; per-host IdentityFile belongs in ssh config)
 #
 # Usage:
-#   kampodine env list [--host <user@ip>]              # KEY + fingerprint table (NEVER values)
-#   kampodine env push --file <local-env-file> [...]   # upload: 0600 temp + atomic mv + restart hint
-#   kampodine env pull [--out <file>] [...]            # raw payload to stdout/--out (0600); masked summary follows it
-#   kampodine env fingerprint [--file <f>]             # preview the masking for a LOCAL file / stdin (never values)
+#   kampodine env list [--host <user@ip>] [--profile <name>]            # KEY + fingerprint table (NEVER values)
+#   kampodine env push --file <local-env-file> [...] [--profile <name>] # upload: 0600 temp + atomic mv + restart hint
+#   kampodine env pull [--out <file>] [...] [--profile <name>]          # raw payload to stdout/--out (0600); masked summary follows it
+#   kampodine env fingerprint [--file <f>]                              # preview the masking for a LOCAL file / stdin (never values)
 #
 # push sends the file VERBATIM (what you push is what lands). deploy's env
 # step additionally drops rc-script-owned CLEAR keys — keep those out of the
 # file you push unless you mean to own them here.
 set -euo pipefail
 
+HERE="${BASH_SOURCE[0]%/*}"
+# shellcheck source=common.sh
+source "$HERE/common.sh"
+
 ENV_FILE_REMOTE="${KAMPODINE_ENV_REMOTE:-/etc/kampodine/env}"
 ENV_TMP_BASE="$(dirname "$ENV_FILE_REMOTE")"
 
@@ -47,8 +51,9 @@ usage() {
 
 Fingerprints NEVER leak values: every line is KEY + value length + first 2 chars.
 Raw values move only in push's upload stream and pull's stdout/--out payload.
-Host/key resolution matches deploy.sh: --host | KAMPODINE_HOST; --ssh-key |
-KAMPODINE_SSH_KEY | ssh-agent / ~/.ssh/config.
+Host/key resolution matches deploy.sh: --host | --profile <name> |
+KAMPODINE_PROFILE | config defaultProfile | KAMPODINE_HOST; --ssh-key |
+profile sshKey | KAMPODINE_SSH_KEY | ssh-agent / ~/.ssh/config.
 
 Examples:
   kampodine env list --host root@203.0.113.10
@@ -70,10 +75,14 @@ esac
 
 FILE=""
 OUT=""
+PROFILE_FLAG=""
+HOST_FLAG=""
+KEY_FLAG=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --host) KAMPODINE_HOST="$2"; shift 2 ;;
-    --ssh-key) SSH_KEY="$2"; shift 2 ;;
+    --host) HOST_FLAG="$2"; KAMPODINE_HOST="$2"; shift 2 ;;
+    --ssh-key) KEY_FLAG="$2"; SSH_KEY="$2"; shift 2 ;;
+    --profile) PROFILE_FLAG="$2"; shift 2 ;;
     --file) FILE="$2"; shift 2 ;;
     --out) OUT="$2"; shift 2 ;;
     -h|--help) usage ;;
@@ -81,6 +90,11 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+# profile resolution (flag > KAMPODINE_PROFILE > defaultProfile); an explicit
+# --host/--ssh-key flag always beats the profile
+profile_resolve "$PROFILE_FLAG" "$HOST_FLAG" "$KEY_FLAG"
+SSH_KEY="${KEY_FLAG:-${KAMPODINE_SSH_KEY:-}}"
+
 SSH_ARGS=(-o ConnectTimeout=10 -o BatchMode=yes)
 [[ -n "$SSH_KEY" ]] && SSH_ARGS+=(-i "$SSH_KEY")
 # $1 is a composed remote command — client-side expansion is the design.
@@ -94,7 +108,7 @@ if [[ "$(uname -s)" == "Darwin" ]]; then
 fi
 
 require_host() {
-  [[ -n "$KAMPODINE_HOST" ]] || die "target required: --host root@<ip> or KAMPODINE_HOST=root@<ip> (resolution matches deploy.sh)"
+  [[ -n "$KAMPODINE_HOST" ]] || die "target required: --host root@<ip>, --profile <name>, KAMPODINE_PROFILE, config defaultProfile, or KAMPODINE_HOST=root@<ip> (resolution matches deploy.sh)"
 }
 
 # env_fp_lines — env content on stdin -> fingerprint table on stdout.

package/scripts/image-import.sh

@@ -36,6 +36,7 @@ COMPARTMENT_NAME="${OCI_COMPARTMENT:-kampodine}"
 PROFILE="${OCI_PROFILE:-default}"
 FROM_PASS=0
 KEEP_OBJECT=0
+PROFILE_FLAG=""
 
 say() { printf '[import] %s\n' "$*"; }
 die() { printf '[import][FAIL] %s\n' "$*" >&2; exit 1; }
@@ -57,6 +58,7 @@ while [[ $# -gt 0 ]]; do
     --bucket) BUCKET="$2"; shift 2 ;;
     --name-prefix) NAME_PREFIX="$2"; shift 2 ;;
     --compartment) COMPARTMENT_NAME="$2"; shift 2 ;;
+    --profile) PROFILE_FLAG="$2"; shift 2 ;;
     --from-pass) FROM_PASS=1; shift ;;
     --keep-object) KEEP_OBJECT=1; shift ;;
     -h|--help) usage ;;
@@ -64,6 +66,13 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+# validate the kampodine instance profile when selected (uniform resolution);
+# image-import consumes none of its host/sshKey fields (OCI-only surface)
+HERE="${BASH_SOURCE[0]%/*}"
+# shellcheck source=common.sh
+source "$HERE/common.sh"
+profile_resolve "$PROFILE_FLAG" "" ""
+
 command -v oci >/dev/null 2>&1 || die "oci CLI not found — brew install oci-cli, then: oci setup config (infra/oci/README.md § CLI setup)"
 [[ -n "${OCI_COMPARTMENT:-}" ]] || die "set OCI_COMPARTMENT=<compartment name or ocid> — no default: compartments are account-specific"
 command -v pass >/dev/null 2>&1 || true

package/scripts/metrics.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# metrics.sh — ONE-SHOT VM snapshot over SSH (no continuous monitoring —
+# Beszel owns that; this is the CLI triage view). One SSH round-trip per
+# snapshot: load + CPUs, memory, disk WITH an images/data/other breakdown,
+# per-container CPU/MEM (podman stats), uptime, top-5 processes by RSS.
+#
+# The remote command is busybox-safe (cat/echo/nproc/df/du/podman/ps/sort/
+# head — see METRICS_REMOTE_CMD in common.sh); all parsing/rendering happens
+# client-side (metrics_* helpers in common.sh — the SAME snapshot folds into
+# `status --verbose`). Disk threshold reuses the deploy gate's verdict logic
+# (disk_verdict): --warn-disk <pct> (default 90) exits 1 when usage >= pct.
+#
+# Usage:
+#   kampodine metrics [--profile <name>] [--host <user@ip>] [--ssh-key <path>]
+#                     [--warn-disk <pct>] [--watch <sec>] [--count <n>]
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=common.sh
+source "$HERE/common.sh"
+
+KAMPODINE_HOST="${KAMPODINE_HOST:-}"
+if [ -n "${KAMPODINE_SSH_KEY:-}" ]; then
+    SSH_KEY="$KAMPODINE_SSH_KEY"
+else
+    SSH_KEY=""
+fi
+PROFILE_FLAG=""
+HOST_FLAG=""
+KEY_FLAG=""
+WARN_DISK="90"
+WATCH=""
+COUNT=""
+
+say() { printf '\033[1;36m[metrics]\033[0m %s\n' "$*"; }
+die() { printf '\033[1;31m[metrics] FAIL:\033[0m %s\n' "$*" >&2; exit 1; }
+usage() {
+  local code="${1:-0}"
+  printf 'Usage:\n'
+  grep '^#   kampodine metrics' "$0" | sed 's/^#   //'
+  cat <<'EOF'
+
+One SSH round-trip per snapshot; busybox-safe remote commands; rendering is
+client-side. NO continuous monitoring (Beszel owns that) — one-shot CLI view;
+--watch N re-snapshots every N seconds (Ctrl-C ends), --count M bounds the
+iterations. --warn-disk <pct> (default 90) exits 1 when root disk usage is at
+or above the threshold — the SAME verdict logic as deploy's fail-closed gate.
+Host resolution: --host | --profile <name> | KAMPODINE_PROFILE |
+config defaultProfile | KAMPODINE_HOST.
+
+Examples:
+  kampodine metrics                              # profile/host from config or env
+  kampodine metrics --host root@203.0.113.10     # explicit target
+  kampodine metrics --profile prod               # per-instance profile
+  kampodine metrics --warn-disk 85               # exit 1 at >= 85% (default 90)
+  kampodine metrics --watch 10 --count 6         # snapshot every 10s, 6 times
+  kampodine status --verbose                     # the same snapshot inside status
+EOF
+  exit "$code"
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --profile) PROFILE_FLAG="$2"; shift 2 ;;
+    --host) HOST_FLAG="$2"; KAMPODINE_HOST="$2"; shift 2 ;;
+    --ssh-key) KEY_FLAG="$2"; SSH_KEY="$2"; shift 2 ;;
+    --warn-disk) WARN_DISK="$2"; shift 2 ;;
+    --watch) WATCH="$2"; shift 2 ;;
+    --count) COUNT="$2"; shift 2 ;;
+    -h|--help) usage 0 ;;
+    *) die "unknown argument: $1 (--help)" ;;
+  esac
+done
+
+# profile resolution (flag > KAMPODINE_PROFILE > defaultProfile); an explicit
+# --host/--ssh-key always beats the profile
+profile_resolve "$PROFILE_FLAG" "$HOST_FLAG" "$KEY_FLAG"
+SSH_KEY="${KEY_FLAG:-${KAMPODINE_SSH_KEY:-}}"
+
+[[ "$WARN_DISK" =~ ^[0-9]+$ && "$WARN_DISK" -ge 1 && "$WARN_DISK" -le 100 ]] \
+  || die "--warn-disk must be a percentage 1-100 (got: $WARN_DISK)"
+[[ -z "$WATCH" || "$WATCH" =~ ^[1-9][0-9]*$ ]] || die "--watch must be a positive-integer number of seconds (got: $WATCH)"
+[[ -z "$COUNT" || "$COUNT" =~ ^[1-9][0-9]*$ ]] || die "--count must be a positive integer (got: $COUNT)"
+[[ -n "$KAMPODINE_HOST" ]] || die "target required: --host root@<ip>, --profile <name>, KAMPODINE_PROFILE, config defaultProfile, or KAMPODINE_HOST=root@<ip>"
+
+SSH_ARGS=(-o ConnectTimeout=10 -o BatchMode=yes)
+[[ -n "$SSH_KEY" ]] && SSH_ARGS+=(-i "$SSH_KEY")
+# $1 is a composed remote command — client-side expansion is the design.
+# shellcheck disable=SC2029
+vm() { ssh "${SSH_ARGS[@]}" "$KAMPODINE_HOST" "$1"; }
+
+# --- macOS ssh-agent quirk (first run from a fresh machine) -------------------
+if [[ "$(uname -s)" == "Darwin" ]]; then
+  SSH_AUTH_SOCK="$(launchctl getenv SSH_AUTH_SOCK 2>/dev/null || true)"
+  export SSH_AUTH_SOCK
+fi
+
+snapshot() {
+  local raw pct verdict
+  raw="$(vm "$METRICS_REMOTE_CMD")" || die "cannot reach VM $KAMPODINE_HOST (ssh failed) — nothing to report"
+  say "== metrics ($KAMPODINE_HOST) =="
+  metrics_render "$raw"
+  pct="$(disk_pct_from_df "$M_DISK")"
+  verdict="$(disk_verdict "$pct" "$WARN_DISK")"
+  case "$verdict" in
+    fail)
+      printf 'WARNING: root disk at %s%% (>= --warn-disk %s%%) — free space first: kampodine deploy prune --dry-run\n' \
+        "${pct:-?}" "$WARN_DISK"
+      return 1
+      ;;
+    warn)
+      printf 'WARNING: root disk above 90%% (%s%%) — old sha-tagged deploy images pile up; reclaim: kampodine deploy prune --dry-run\n' "$pct"
+      ;;
+  esac
+  return 0
+}
+
+n=0
+while :; do
+  n=$(( n + 1 ))
+  if ! snapshot; then
+    exit 1
+  fi
+  [[ -n "$COUNT" && "$n" -ge "$COUNT" ]] && exit 0
+  [[ -z "$WATCH" ]] && exit 0
+  sleep "$WATCH"
+done

package/scripts/migrate.sh

@@ -9,13 +9,16 @@
 # are COLLECTED (files are independent; one bad tenant must not block the others)
 # and the script exits 1 if any failed — the deploy's smoke gate catches a red migration.
 # Runs ON the VM from the repo checkout (also fine locally against .tmp data):
-#   kampodine migrate [--allow-running]
+#   kampodine migrate [--allow-running] [--profile <name>]
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="${REPO_ROOT:-$(cd "${SCRIPT_DIR}/../../.." && pwd)}"
 TENANT_DIR="${TENANT_DIR:-/data/tenants}"
 SERVICE="${SERVICE:-kampodine-api}"
+HERE="$SCRIPT_DIR"
+# shellcheck source=common.sh
+source "$HERE/common.sh"
 
 log() { printf '[migrate-all] %s\n' "$*"; }
 fail() { printf '[migrate-all][FAIL] %s\n' "$*" >&2; exit 1; }
@@ -37,13 +40,25 @@ EOF
 }
 
 ALLOW_RUNNING=0
+PROFILE_FLAG=""
+PENDING_PROFILE=0
 for arg in "$@"; do
+  if [[ "$PENDING_PROFILE" -eq 1 ]]; then
+    PROFILE_FLAG="$arg"
+    PENDING_PROFILE=0
+    continue
+  fi
   case "$arg" in
     --allow-running) ALLOW_RUNNING=1 ;;
-    -h|--help) usage ;;
+    --profile) PENDING_PROFILE=1 ;;
+    --help|-h) usage ;;
     *) fail "unknown argument: $arg (--help)" ;;
   esac
 done
+[[ "$PENDING_PROFILE" -eq 0 ]] || fail "--profile requires a value"
+# profile selection is validated for uniformity — migrate consumes no
+# host/sshKey fields (it runs ON the VM from the repo checkout)
+profile_resolve "$PROFILE_FLAG" "" ""
 
 [[ -f "${REPO_ROOT}/apps/api/scripts/libsql-migrate/migrate-db.ts" ]] \
   || fail "repo root not found at ${REPO_ROOT} (set REPO_ROOT=... if the checkout lives elsewhere)"
@@ -51,11 +66,30 @@ command -v pnpm >/dev/null 2>&1 || fail "pnpm not found in PATH"
 [[ -d "$TENANT_DIR" ]] || fail "tenant dir ${TENANT_DIR} does not exist"
 
 # Writing schema while the API serves traffic risks SQLITE_BUSY on a single-writer
-# engine — the service must be stopped first (rc-service kampodine-api stop). Override exists
+# engine — the service must be stopped first (rc-service ${SERVICE} stop). Override exists
 # for deliberate local use.
-if systemctl is-active --quiet "$SERVICE" 2>/dev/null; then
+#
+# Init-aware detection (fixes the DEAD guard, 2026-10-08): this script runs ON
+# the VM, whose init is OpenRC (Alpine ships no systemd) — a bare `systemctl
+# is-active` always failed there, so the stop-first guard NEVER fired and
+# migrations could run under the serving API. Mirror common.sh's detection
+# order: rc-service (openrc) first, then systemctl (systemd hosts). On a host
+# with neither (local dev machines), state is unknowable — proceed with a
+# loud warning rather than blocking local runs.
+service_running() {
+  if command -v rc-service >/dev/null 2>&1; then
+    rc-service "$SERVICE" status >/dev/null 2>&1
+  elif command -v systemctl >/dev/null 2>&1; then
+    systemctl is-active --quiet "$SERVICE"
+  else
+    log "service state unknown (neither rc-service nor systemctl found) — assuming ${SERVICE} is not running"
+    return 1
+  fi
+}
+
+if service_running; then
   if [[ $ALLOW_RUNNING -ne 1 ]]; then
-    fail "${SERVICE} is running — stop it first (rc-service kampodine-api stop) or pass --allow-running"
+    fail "${SERVICE} is running — stop it first (rc-service ${SERVICE} stop) or pass --allow-running"
   fi
   log "WARNING: migrating while ${SERVICE} is running (--allow-running)"
 fi