kampodine 0.4.0 → 0.6.0

package/scripts/config.sh

@@ -0,0 +1,247 @@
+#!/usr/bin/env bash
+# config.sh — per-instance profiles in ~/.kampodine/config.json.
+#
+# FLAT by owner decision: every profile carries host/sshKey/proxyHost/group
+# — NO inheritance between profiles (the schema only LEAVES ROOM for a
+# future "defaults" block; nothing reads one). `group` is cosmetic: it feeds
+# the `config list --group` filter and nothing else. The file NEVER holds
+# secrets — sshKey is a PATH; hosts are addresses; that is the whole schema.
+# (The init-system auto-detection may add an "init" field per profile —
+# written by common.sh's init_detect, never by hand.)
+#
+# File contract: dir 0700, file 0600, atomic writes (same-dir tmp + mv).
+# jq is required for every subcommand here (safe JSON read + rewrite).
+#
+# Usage:
+#   kampodine config init --name <name> --host <user@ip> --ssh-key <path> [--proxy-host <host>] [--group <g>] [--set-default] [--force]
+#   kampodine config list [--group <g>]
+#   kampodine config show [--profile <name>]
+#   kampodine config set-default <name>
+#   kampodine config remove <name> [--force]
+#
+# The FIRST profile automatically becomes the default; later profiles need
+# --set-default (or `config set-default`) to take it. An explicit --profile
+# flag or KAMPODINE_PROFILE env beats the default everywhere.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=common.sh
+source "$HERE/common.sh"
+
+say() { printf '\033[1;35m[config]\033[0m %s\n' "$*"; }
+die() { printf '\033[1;31m[config] FAIL:\033[0m %s\n' "$*" >&2; exit 1; }
+usage() {
+  local code="${1:-0}"
+  printf 'Usage:\n'
+  grep '^#   kampodine config' "$0" | sed 's/^#   //'
+  cat <<'EOF'
+
+Per-instance profiles (~/.kampodine/config.json, dir 0700 / file 0600).
+FLAT — no inheritance; `group` is a cosmetic list filter. sshKey is stored
+as a PATH only; secrets never live in the config. Resolution everywhere:
+explicit flag > KAMPODINE_PROFILE env > defaultProfile > legacy env.
+jq is required (safe JSON rewrites). The first profile auto-becomes the
+default; removing the LAST profile requires --force.
+
+Examples:
+  kampodine config init --name prod --host root@84.13.128.216 --ssh-key ~/.ssh/id_ed25519-esellar --proxy-host 84-13-128-216.sslip.io --set-default
+  kampodine config init --name staging --host root@203.0.113.8 --ssh-key ~/.ssh/id_ed25519 --group preview
+  kampodine config list                 # all profiles (default marked *)
+  kampodine config list --group main    # cosmetic group filter
+  kampodine config show --profile prod
+  kampodine config set-default staging
+  kampodine config remove staging
+  kampodine deploy --profile prod       # profiles feed every subcommand
+EOF
+  exit "$code"
+}
+
+# config_atomic_write <json> — 0700 dir / 0600 file, same-dir tmp + mv.
+config_atomic_write() {
+  local json="$1" f tmp
+  f="$(config_file)"
+  tmp="$f.tmp.$$"
+  umask 077
+  printf '%s\n' "$json" > "$tmp" || die "cannot write $tmp"
+  chmod 600 "$tmp" && mv -f "$tmp" "$f" || die "atomic install failed (tmp left at: $tmp)"
+}
+
+# expand_tilde <path> -> $HOME-spelled-out form (config stores absolute paths).
+expand_tilde() {
+  case "$1" in
+    "~") printf '%s' "$HOME" ;;
+    "~"/*) printf '%s%s' "$HOME" "${1#\~}" ;;
+    *) printf '%s' "$1" ;;
+  esac
+}
+
+# reject_config_value <value> <what> — no whitespace/quote/backslash: the
+# config is hand-greppable and jq-round-trippable; nothing legit needs them.
+reject_config_value() {
+  local value="$1" what="$2"
+  [[ -n "$value" ]] || die "$what must not be empty"
+  case "$value" in
+    *[[:space:]\"\\]*)
+      die "$what must not contain whitespace, quotes, or backslashes (got it with — value not echoed)"
+      ;;
+  esac
+}
+
+CMD="${1:-}"
+case "$CMD" in
+  init|list|show|set-default|remove) shift ;;
+  -h|--help|help) usage 0 ;;
+  "") usage 2 ;;
+  *)
+    printf 'kampodine config: unknown subcommand: %s\n\n' "$CMD" >&2
+    usage 2
+    ;;
+esac
+
+NAME="" HOST_ARG="" KEY_ARG="" PROXY_ARG="" GROUP_ARG="" SET_DEFAULT=0 FORCE=0
+PROFILE_ARG=""
+POSITIONAL=()
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --name) NAME="$2"; shift 2 ;;
+    --host) HOST_ARG="$2"; shift 2 ;;
+    --ssh-key) KEY_ARG="$2"; shift 2 ;;
+    --proxy-host) PROXY_ARG="$2"; shift 2 ;;
+    --group) GROUP_ARG="$2"; shift 2 ;;
+    --profile) PROFILE_ARG="$2"; shift 2 ;;
+    --set-default) SET_DEFAULT=1; shift ;;
+    --force) FORCE=1; shift ;;
+    -h|--help) usage 0 ;;
+    --) shift; POSITIONAL+=("$@"); break ;;
+    *) POSITIONAL+=("$1"); shift ;;
+  esac
+done
+
+require_jq() {
+  command -v jq >/dev/null 2>&1 \
+    || die "jq not found — brew install jq (config.sh rewrites JSON safely)"
+}
+
+case "$CMD" in
+  init)
+    [[ -n "$NAME" ]] || die "--name is required (--help)"
+    is_profile_name "$NAME" || die "invalid --name '$NAME' — use [A-Za-z0-9][A-Za-z0-9_-]* (max 64)"
+    f="$(config_file)"
+    if [[ -f "$f" ]] && [[ "$(jq -r --arg n "$NAME" '.profiles // {} | has($n)' "$f" 2>/dev/null || echo false)" == "true" ]] && [[ $FORCE -ne 1 ]]; then
+      die "profile '$NAME' already exists — pass --force to overwrite (re-init also refreshes fields; the cached init field is kept unless you change host/ssh-key)"
+    fi
+    reject_config_value "$HOST_ARG" "--host"
+    reject_config_value "$KEY_ARG" "--ssh-key"
+    [[ -z "$PROXY_ARG" ]] || reject_config_value "$PROXY_ARG" "--proxy-host"
+    [[ -z "$GROUP_ARG" ]] || reject_config_value "$GROUP_ARG" "--group"
+    KEY_ABS="$(expand_tilde "$KEY_ARG")"
+    require_jq
+    if [[ ! -f "$KEY_ABS" ]]; then
+      say "note: ssh key file does not exist (yet): $KEY_ABS — stored as a path, deploy will fail until it does"
+    fi
+    if [[ -f "$f" ]]; then
+      # upsert + default rules: explicit --set-default wins; a config without
+      # any default (fresh defaultProfile, or cleared by a --force remove)
+      # adopts this profile.
+      new="$(jq --arg n "$NAME" --arg h "$HOST_ARG" --arg k "$KEY_ABS" --arg p "$PROXY_ARG" --arg g "$GROUP_ARG" --arg sd "$SET_DEFAULT" '
+        .profiles[$n] = {host: $h, sshKey: $k, proxyHost: $p, group: $g}
+        | if $sd == "1" or (.defaultProfile // "") == "" then .defaultProfile = $n else . end
+      ' "$f")"
+      config_atomic_write "$new"
+    else
+      new="$(jq -n --arg n "$NAME" --arg h "$HOST_ARG" --arg k "$KEY_ABS" --arg p "$PROXY_ARG" --arg g "$GROUP_ARG" '
+        {defaultProfile: $n, profiles: {($n): {host: $h, sshKey: $k, proxyHost: $p, group: $g}}}
+      ')"
+      config_atomic_write "$new"
+    fi
+    default="$(config_default_profile)"
+    say "saved profile '$NAME' -> $f (0600)$([ "$default" == "$NAME" ] && printf ' — default' || true)"
+    [[ $SET_DEFAULT -eq 1 ]] || say "make default later: kampodine config set-default $NAME"
+    ;;
+
+  list)
+    require_jq
+    f="$(config_file)"
+    [[ -f "$f" ]] || die "no kampodine config yet — create one: kampodine config init --name <name> --host root@<ip> (--help)"
+    default="$(config_default_profile)"
+    printf '%-12s %-10s %-8s %-26s %-30s %-26s\n' "NAME" "GROUP" "INIT" "HOST" "SSH-KEY (path)" "PROXY-HOST"
+    rows="$(jq -r --arg g "$GROUP_ARG" '
+      .profiles // {} | to_entries[]
+      | select($g == "" or ((.value.group // "") == $g))
+      | [.key,
+         (if (.value.group // "") == "" then "-" else .value.group end),
+         (if (.value.init // "") == "" then "-" else .value.init end),
+         (if (.value.host // "") == "" then "-" else .value.host end),
+         (if (.value.sshKey // "") == "" then "-" else .value.sshKey end),
+         (if (.value.proxyHost // "") == "" then "-" else .value.proxyHost end)]
+      | @tsv' "$f")"
+    if [[ -z "$rows" ]]; then
+      say "(no profiles${GROUP_ARG:+ in group '$GROUP_ARG'})"
+      exit 0
+    fi
+    while IFS=$'\t' read -r name group init host key proxy; do
+      marker=""
+      [[ "$name" == "$default" ]] && marker="  * default"
+      printf '%-12s %-10s %-8s %-26s %-30s %-26s%s\n' \
+        "$name" "$group" "$init" "$host" "$key" "$proxy" "$marker"
+    done <<<"$rows"
+    ;;
+
+  show)
+    require_jq
+    f="$(config_file)"
+    [[ -f "$f" ]] || die "no kampodine config yet — create one: kampodine config init --name <name> --host root@<ip> (--help)"
+    name="${PROFILE_ARG:-$(config_default_profile)}"
+    [[ -n "$name" ]] || die "no default profile — pass --profile <name> (known: $(config_profile_names | paste -sd' ' -))"
+    host="$(profile_field "$name" host)" || die "unknown profile '$name' — known: $(config_profile_names | paste -sd' ' -)"
+    say "profile: $name$([ "$name" == "$(config_default_profile)" ] && printf ' (default)' || true)"
+    printf 'host      : %s\n' "$host"
+    printf 'sshKey    : %s   # path only — secrets never live in the config\n' "$(profile_field "$name" sshKey)"
+    printf 'proxyHost : %s\n' "$(profile_field "$name" proxyHost)"
+    printf 'group     : %s\n' "$(profile_field "$name" group)"
+    cached_init="$(profile_field "$name" init)"
+    [[ -z "$cached_init" ]] || printf 'init      : %s   # cached by host auto-detection\n' "$cached_init"
+    ;;
+
+  set-default)
+    target="${POSITIONAL[0]:-}"
+    [[ -n "$target" ]] || die "usage: kampodine config set-default <name>"
+    require_jq
+    f="$(config_file)"
+    [[ -f "$f" ]] || die "no kampodine config yet — create one: kampodine config init --name <name> --host root@<ip> (--help)"
+    profile_field "$target" host >/dev/null \
+      || die "unknown profile '$target' — known: $(config_profile_names | paste -sd' ' -)"
+    new="$(jq --arg n "$target" '.defaultProfile = $n' "$f")"
+    config_atomic_write "$new"
+    say "default profile: $target"
+    ;;
+
+  remove)
+    target="${POSITIONAL[0]:-}"
+    [[ -n "$target" ]] || die "usage: kampodine config remove <name> [--force]"
+    require_jq
+    f="$(config_file)"
+    [[ -f "$f" ]] || die "no kampodine config at $f — nothing to remove"
+    profile_field "$target" host >/dev/null \
+      || die "unknown profile '$target' — known: $(config_profile_names | paste -sd' ' -)"
+    count="$(jq '.profiles // {} | length' "$f")"
+    if [[ "$count" -eq 1 && $FORCE -ne 1 ]]; then
+      die "refusing to remove the last profile ('$target') — pass --force if you really mean it"
+    fi
+    new="$(jq --arg n "$target" '
+      .profiles |= del(.[$n])
+      | if .defaultProfile == $n
+        then .defaultProfile = ((.profiles | keys | sort) | .[0] // "")
+        else . end
+    ' "$f")"
+    config_atomic_write "$new"
+    remaining="$(jq -r '.profiles // {} | keys | length' "$f")"
+    say "removed profile '$target' ($remaining remaining)"
+    new_default="$(config_default_profile)"
+    if [[ "$target" == "$new_default" || -z "$new_default" ]]; then
+      :
+    else
+      say "default profile is now: $new_default"
+    fi
+    ;;
+esac

package/scripts/deploy-lifecycle.sh

@@ -0,0 +1,266 @@
+#!/usr/bin/env bash
+# deploy-lifecycle.sh — deployment lifecycle ops for the target VM, reached
+# as `kampodine deploy <subcommand>` (deploy.sh delegates before any build
+# preflight, so these work outside the app repo, offline, and without podman
+# on the deploy machine). Read-mostly by design: nothing here builds or
+# streams images.
+#
+# The local deployment ledger (~/.kampodine/deployments.jsonl, appended by
+# EVERY deploy/rollback) is the deployment HISTORY; the VM's sha-tagged
+# images are the deployable REALITY. `deploy list` merges both, marks the
+# running tag, and prints the total — no more counting `podman images` by
+# hand after an outage.
+#
+# Usage:
+#   kampodine deploy list [--host root@<ip>] [--profile <name>] [--ssh-key <path>]
+#   kampodine deploy prune [--host root@<ip>] [--profile <name>] [--keep N] [--dry-run]
+#   kampodine deploy logs [--host root@<ip>] [--profile <name>] [--lines N]
+#   kampodine deploy restart [--host root@<ip>] [--profile <name>]
+#   kampodine deploy shell [--host root@<ip>] [--profile <name>] [exec -- <cmd>...]
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=common.sh
+source "$HERE/common.sh"
+
+IMAGE="127.0.0.1:5000/kampodine-api"
+CONTAINER="kampodine-api"
+DISK_PATH="/var/lib/containers"
+
+KAMPODINE_HOST="${KAMPODINE_HOST:-}"
+# SSH key resolution — same ladder as deploy.sh:
+#   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
+if [ -n "${KAMPODINE_SSH_KEY:-}" ]; then
+    SSH_KEY="$KAMPODINE_SSH_KEY"
+else
+    SSH_KEY=""
+fi
+
+SUB="${1:-}"
+say() { printf '\033[1;35m[deploy %s]\033[0m %s\n' "$SUB" "$*"; }
+warn() { printf '\033[1;33m[deploy %s] WARNING:\033[0m %s\n' "$SUB" "$*" >&2; }
+die() { printf '\033[1;31m[deploy %s] FAIL:\033[0m %s\n' "$SUB" "$*" >&2; exit 1; }
+usage() {
+  local code="${1:-0}"
+  printf 'Usage:\n'
+  grep '^#   kampodine deploy' "$0" | sed 's/^#   //'
+  cat <<'EOF'
+
+Lifecycle subcommands are --host-aware with the SAME resolution as deploy:
+--host | --profile <name> | KAMPODINE_PROFILE | config defaultProfile |
+KAMPODINE_HOST; --ssh-key | profile sshKey | KAMPODINE_SSH_KEY | ssh-agent /
+~/.ssh/config.
+
+  list     deployment history: the VM's sha-tagged images (running one marked)
+           merged with the local ledger (~/.kampodine/deployments.jsonl —
+           every deploy/rollback appends {ts, host, sha, tag, result,
+           duration_ms, subject}; shas/tags/hosts only, NEVER secrets) with a
+           "Total deployments" footer. VM unreachable degrades to a
+           ledger-only view.
+  prune    reclaim VM disk: removes OLD sha-tagged deploy images. ALWAYS kept:
+           the currently-running image, ts-rollback, and the newest --keep N
+           (default 2). --dry-run prints the exact podman rmi commands and
+           removes nothing; images in use by running containers are refused.
+  logs     tail the running api container's logs (podman logs --tail).
+  restart  restart the api service via rc-service (deploy's restart path:
+           supervise-daemon re-runs the whole podman run against :latest).
+  shell    interactive sh inside the running api container; flags must come
+           before `exec -- <cmd>...` for one-shot commands.
+
+Examples:
+  kampodine deploy list --host root@203.0.113.10
+  kampodine deploy prune --host root@203.0.113.10 --dry-run
+  kampodine deploy prune --host root@203.0.113.10 --keep 3
+  kampodine deploy logs --host root@203.0.113.10 --lines 200
+  kampodine deploy restart --host root@203.0.113.10
+  kampodine deploy shell --host root@203.0.113.10
+  kampodine deploy shell --host root@203.0.113.10 exec -- df -h /var/lib/containers
+EOF
+  exit "$code"
+}
+
+case "$SUB" in
+  list|prune|logs|restart|shell) shift ;;
+  -h|--help|help) usage 0 ;;
+  "") usage 2 ;;
+  *)
+    printf 'kampodine deploy: unknown lifecycle subcommand: %s\n\n' "$SUB" >&2
+    usage 2
+    ;;
+esac
+
+# shell exec: `deploy shell exec -- <cmd>...` — capture the command before the
+# shared flag loop (flags for shell must come BEFORE `exec`).
+SHELL_EXEC=()
+if [[ "$SUB" == "shell" && "${1:-}" == "exec" ]]; then
+  shift
+  [[ "${1:-}" == "--" ]] || die "shell exec requires -- before the command: kampodine deploy shell exec -- <cmd>..."
+  shift
+  [[ $# -gt 0 ]] || die "shell exec -- requires a command"
+  SHELL_EXEC=("$@")
+  set --
+fi
+
+KEEP="2"
+DRY_RUN=0
+LINES="100"
+PROFILE_FLAG=""
+HOST_FLAG=""
+KEY_FLAG=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --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 ;;
+    --keep) KEEP="$2"; shift 2 ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    --lines) LINES="$2"; shift 2 ;;
+    -h|--help) usage 0 ;;
+    --) shift; break ;;
+    *) die "unknown argument: $1 (--help)" ;;
+  esac
+done
+
+case "$SUB" in
+  prune) [[ "$KEEP" =~ ^[0-9]+$ ]] || die "--keep must be a non-negative integer (got: $KEEP)" ;;
+  logs) [[ "$LINES" =~ ^[1-9][0-9]*$ ]] || die "--lines must be a positive integer (got: $LINES)" ;;
+esac
+
+# 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.
+# 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
+
+require_host() {
+  [[ -n "$KAMPODINE_HOST" ]] || die "target required: --host root@<ip>, --profile <name>, KAMPODINE_PROFILE, config defaultProfile, or KAMPODINE_HOST=root@<ip> (resolution matches deploy.sh)"
+}
+
+# fetch_image_listing -> "tag|CreatedAt|Size" lines for sha-tagged deploy
+# images; returns 1 only when the VM itself is unreachable (podman's own
+# "no images" exits 0 — a reachable VM with zero images is not an error).
+fetch_image_listing() {
+  local raw
+  raw="$(vm "podman images --format '{{.Tag}}|{{.CreatedAt}}|{{.Size}}' $IMAGE 2>/dev/null")" || return 1
+  printf '%s\n' "$raw" | grep -E '^[0-9a-f]{7,40}\|' || true
+}
+
+fetch_running_images() {
+  vm "podman ps --format '{{.Image}}' 2>/dev/null" || return 1
+}
+
+# sh_quote_args <args...> -> the args POSIX-single-quoted for safe composition
+# into one remote sh command string (busybox-safe: '\'' escaping only).
+sh_quote_args() {
+  local out="" arg
+  for arg in "$@"; do
+    arg="${arg//\'/\'\\\'\'}"
+    out+="'$arg' "
+  done
+  printf '%s' "${out% }"
+}
+
+case "$SUB" in
+  list)
+    require_host
+    say "deployment history for $KAMPODINE_HOST (ledger: $(ledger_file))"
+    images="$(fetch_image_listing)" || images=""
+    running="$(fetch_running_images)" || running=""
+    if [[ -z "$images" && -z "$running" ]]; then
+      if ! vm "podman images >/dev/null 2>&1"; then
+        warn "cannot reach VM $KAMPODINE_HOST — showing ledger-only history (no VM truth)"
+      fi
+    fi
+    ledger_lines="$(ledger_entries "$KAMPODINE_HOST")"
+    rows="$(render_deploy_list "$images" "$running" "$ledger_lines")"
+    printf '%-9s %-17s %-9s %-9s %s\n' "TAG" "CREATED" "STATE" "RESULT" "SUBJECT"
+    if [[ -n "$rows" ]]; then
+      printf '%s\n' "$rows"
+    else
+      say "(no deployments recorded yet — the ledger fills as you deploy)"
+    fi
+    count="$(printf '%s\n' "$rows" | grep -c . || true)"
+    ledger_total_line "${count:-0}" "on $KAMPODINE_HOST"
+    ;;
+
+  prune)
+    require_host
+    images="$(fetch_image_listing)" || die "cannot list images on $KAMPODINE_HOST (ssh failed — refusing to prune blind)"
+    running="$(fetch_running_images)" || running=""
+    removals="$(prune_select "$images" "$running" "$KEEP")" || die "prune selection failed"
+    if [[ -z "$removals" ]]; then
+      say "nothing to prune (keep set: running + ts-rollback + newest $KEEP)"
+      exit 0
+    fi
+    reclaim="$(sum_sizes_human "$(printf '%s\n' "$removals" | cut -d'|' -f2)")"
+    plan_n="$(printf '%s\n' "$removals" | grep -c . || true)"
+    say "plan: ${plan_n} image(s), ${reclaim} reclaimed (keep: running + ts-rollback + newest $KEEP)"
+    while IFS= read -r line; do
+      [[ -n "$line" ]] || continue
+      tag="${line%%|*}"
+      say "  podman rmi $IMAGE:$tag   # ${line#*|}"
+    done <<<"$removals"
+    if [[ "$DRY_RUN" -eq 1 ]]; then
+      say "dry-run: nothing removed — re-run without --dry-run to apply"
+      exit 0
+    fi
+    while IFS= read -r line; do
+      [[ -n "$line" ]] || continue
+      tag="${line%%|*}"
+      say "removing $IMAGE:$tag"
+      vm "podman rmi $IMAGE:$tag" || die "podman rmi $IMAGE:$tag failed (in use? remove manually after checking podman ps)"
+    done <<<"$removals"
+    disk_pct="$(disk_pct_from_df "$(vm "df -P $DISK_PATH 2>/dev/null" || true)")"
+    if [[ -n "$disk_pct" ]]; then
+      say "VM disk after prune: ${disk_pct}% used on $DISK_PATH"
+      if [[ "$disk_pct" -gt 90 ]]; then
+        warn "disk still above 90% — investigate before the next deploy"
+      fi
+    fi
+    ;;
+
+  logs)
+    require_host
+    say "tailing $CONTAINER on $KAMPODINE_HOST (last $LINES lines)"
+    vm "podman logs --tail $LINES $CONTAINER"
+    ;;
+
+  restart)
+    require_host
+    init_detect vm >/dev/null 2>&1 || true
+    RESTART_CMD="$(svc_action "$CONTAINER" restart)" \
+      || die "neither rc-service nor systemctl found on $KAMPODINE_HOST — cannot restart (host init auto-detection detected neither; groundwork supports openrc + systemd)"
+    say "$RESTART_CMD (deploy's restart path: supervise-daemon on Alpine re-runs podman run on :latest)"
+    vm "$RESTART_CMD"
+    STATUS_CMD="$(svc_action "$CONTAINER" status 2>/dev/null || true)"
+    if [[ -n "$STATUS_CMD" ]]; then
+      say "service status:"
+      vm "$STATUS_CMD" || say "status command failed — check: kampodine deploy logs"
+    fi
+    say "done — verify: kampodine deploy logs --lines 50"
+    ;;
+
+  shell)
+    require_host
+    if [[ ${#SHELL_EXEC[@]} -gt 0 ]]; then
+      vm "podman exec $CONTAINER $(sh_quote_args "${SHELL_EXEC[@]}")"
+    else
+      say "interactive sh in $CONTAINER on $KAMPODINE_HOST (exit to leave)"
+      say "one-shot instead: kampodine deploy shell exec -- <cmd>"
+      ssh "${SSH_ARGS[@]}" -t "$KAMPODINE_HOST" "podman exec -it $CONTAINER sh"
+    fi
+    ;;
+esac