@openparachute/hub 0.6.2 → 0.6.3-rc.2

package/src/commands/upgrade.ts

@@ -51,6 +51,12 @@ import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { HUB_PACKAGE, HUB_SVC } from "../hub-control.ts";
+import {
+  type HubUnitDeps,
+  type HubUnitManagerOpResult,
+  defaultHubUnitDeps,
+  restartHubUnit as restartHubUnitImpl,
+} from "../hub-unit.ts";
 import { ModuleManifestError } from "../module-manifest.ts";
 import {
   type ServiceSpec,
@@ -201,6 +207,25 @@ export interface UpgradeOpts {
    * flaky probe never blocks a legitimate upgrade.
    */
   resolveChannelVersion?: (pkg: string, channel: string) => Promise<string | null>;
+  /**
+   * Supervisor-path seams (design §5) — the ONLY runtime as of Phase 5b.
+   * `upgrade hub` rewrites the binary as usual then RESTARTS THE UNIT via the
+   * platform manager (`restartHubUnit` — systemctl restart / launchctl kickstart
+   * -k): the manager tears down the old hub (children die), starts the new
+   * binary, which re-boots every module from services.json. NEVER a PID-signal
+   * restart (launchd KeepAlive / systemd Restart=always would fight). Module-
+   * target restarts drive the running Supervisor (lifecycle's own dispatch, fed
+   * a `supervisor` block here). The detached restart arm was retired in Phase 5b.
+   *
+   * Production CLI dispatch passes `supervisor: {}`; tests inject the seams they
+   * want to assert.
+   */
+  supervisor?: {
+    /** Deps for the `restartHubUnit` manager op. */
+    hubUnitDeps?: HubUnitDeps;
+    /** Restart the hub unit via the platform manager (never a PID signal, §5). */
+    restartHubUnit?: (deps: HubUnitDeps) => HubUnitManagerOpResult;
+  };
 }
 
 interface ResolvedTarget {
@@ -226,6 +251,8 @@ interface Resolved {
   channelOverride: "rc" | "latest" | undefined;
   allowDowngrade: boolean;
   resolveChannelVersion: (pkg: string, channel: string) => Promise<string | null>;
+  hubUnitDeps: HubUnitDeps;
+  restartHubUnit: (deps: HubUnitDeps) => HubUnitManagerOpResult;
 }
 
 function bunGlobalPrefixes(): string[] {
@@ -258,6 +285,20 @@ function resolve(opts: UpgradeOpts): Resolved {
     allowDowngrade: opts.allowDowngrade ?? false,
     resolveChannelVersion:
       opts.resolveChannelVersion ?? ((pkg, channel) => npmViewVersion(pkg, channel, runner)),
+    // Supervisor seams (the only runtime as of Phase 5b). Production passes
+    // `supervisor: {}`; tests inject the seams they want to assert.
+    ...resolveUpgradeSupervisor(opts.supervisor),
+  };
+}
+
+/** Resolve the supervisor seams for the upgrade path. */
+function resolveUpgradeSupervisor(opts: UpgradeOpts["supervisor"]): {
+  hubUnitDeps: HubUnitDeps;
+  restartHubUnit: (deps: HubUnitDeps) => HubUnitManagerOpResult;
+} {
+  return {
+    hubUnitDeps: opts?.hubUnitDeps ?? defaultHubUnitDeps,
+    restartHubUnit: opts?.restartHubUnit ?? restartHubUnitImpl,
   };
 }
 
@@ -422,6 +463,13 @@ async function resolveTargets(
   // Sweep mode: hub first, then everything in services.json. Hub-first means a
   // dispatcher upgrade can't be undermined mid-sweep by a service upgrade that
   // restarts hub for reasons unrelated to its own code change.
+  //
+  // Phase 4 note (design §5 item 4): on a unit-managed box, restarting the hub
+  // unit re-boots ALL modules from services.json. So the hub-first sweep already
+  // boots every module onto current code when the hub binary upgrades; each
+  // module target then upgrades its package + `supervisor.restart`s it
+  // individually (idempotent — a no-op restart if its code didn't change). The
+  // hub-first invariant still holds.
   const targets: ResolvedTarget[] = [hubTarget()];
   for (const entry of manifest.services) {
     const short = shortNameForManifest(entry.name);
@@ -515,6 +563,56 @@ function readPackageVersion(pkgJsonPath: string): string | null {
   }
 }
 
+/**
+ * Restart an upgraded target after its binary/package was rewritten (design §5).
+ * Supervised path only (Phase 5b — the detached restart arm is retired):
+ *   - HUB target → restart the hub UNIT via the platform manager
+ *     (`restartHubUnit` — systemctl restart / launchctl kickstart -k). The
+ *     manager tears down the old hub (children die), starts the new binary,
+ *     which re-boots every module from services.json. NEVER a PID-signal restart
+ *     (launchd KeepAlive / systemd Restart=always would fight). The command
+ *     returns once the restart is dispatched; it does not need to outlive the
+ *     old hub.
+ *   - MODULE target → drive the running Supervisor by handing `lifecycle.restart`
+ *     the SAME opts a bare `parachute restart <svc>` threads: `supervisor: {}`
+ *     (so the real `isHubUnitInstalled` probe — not a forced override — decides)
+ *     plus `migrateOffer: { enabled: true }`. Its dispatch then routes to
+ *     `supervisor.restart` with the 404-fallthrough. The hub unit was already
+ *     restarted hub-first in the sweep, so it's up to answer.
+ *
+ * A box with no hub unit takes the actionable migrate path: the hub-target
+ * `restartHubUnit` returns `no-unit` (messages surfaced, non-zero), and the
+ * module-target `lifecycle.restart` — driven with `supervisor: {}` +
+ * `migrateOffer` — runs `requireSupervisedOrOffer`'s real probe, then the §7.5
+ * auto-offer / actionable "run `parachute migrate --to-supervised`" error,
+ * rather than a bare connection-refused from `driveModuleOp`.
+ */
+async function restartTarget(target: ResolvedTarget, r: Resolved): Promise<number> {
+  if (target.short === HUB_SVC) {
+    const res = r.restartHubUnit(r.hubUnitDeps);
+    for (const m of res.messages) r.log(m);
+    if (res.outcome === "ok") {
+      r.log(`${target.short}: restarted the hub unit (all modules re-booted).`);
+      return 0;
+    }
+    return 1;
+  }
+  // Module target: route through lifecycle's supervisor arm with the SAME opts a
+  // bare `parachute restart <svc>` threads — `supervisor: {}` (let the real
+  // `isHubUnitInstalled` probe decide; do NOT force `unitInstalled: true` and
+  // bypass it) plus `migrateOffer: { enabled: true }`. On a supervised box this
+  // drives `supervisor.restart` over the loopback module-ops API; on a no-unit
+  // box it gets the §7.5 auto-offer / actionable migrate error instead of a bare
+  // connection-refused. `hubUnitDeps` threads through so the real probe + manager
+  // ops use the resolved deps (production defaults; tests inject the seams).
+  return await r.restartFn(target.short, {
+    manifestPath: r.manifestPath,
+    configDir: r.configDir,
+    supervisor: { hubUnitDeps: r.hubUnitDeps },
+    migrateOffer: { enabled: true },
+  });
+}
+
 async function upgradeLinked(
   target: ResolvedTarget,
   sourceDir: string,
@@ -573,7 +671,7 @@ async function upgradeLinked(
   }
 
   r.log(`${target.short}: ${before.sha.slice(0, 7)} → ${after.sha.slice(0, 7)}; restarting…`);
-  return await r.restartFn(target.short, { manifestPath: r.manifestPath, configDir: r.configDir });
+  return await restartTarget(target, r);
 }
 
 /**
@@ -642,7 +740,7 @@ async function upgradeNpm(target: ResolvedTarget, sourceDir: string, r: Resolved
   }
 
   r.log(`${target.short}: ${beforeVersion ?? "?"} → ${afterVersion ?? "?"}; restarting…`);
-  return await r.restartFn(target.short, { manifestPath: r.manifestPath, configDir: r.configDir });
+  return await restartTarget(target, r);
 }
 
 async function upgradeOne(target: ResolvedTarget, r: Resolved): Promise<number> {

package/src/help.ts

@@ -16,15 +16,16 @@ Usage:
   parachute setup                   interactive walk-through: install services + configure
   parachute install <service>       install and register a service
                                     services: ${services}
-  parachute status                  show installed services, process state, health
-  parachute start   [service]       start all services (or one) in the background
-  parachute stop    [service]       stop all services (or one) — SIGTERM then SIGKILL
-  parachute restart [service]       stop + start
+  parachute status                  show installed services, run state, health
+  parachute start   [service]       start a module via the supervisor (or ensure the hub is up)
+  parachute stop    [service]       stop a module via the supervisor (or stop the hub unit)
+  parachute restart [service]       restart a module via the supervisor (or restart the hub unit)
   parachute upgrade [service]       pull / re-install + restart (skips if no changes)
   parachute logs <service> [-f]     print service logs; -f to tail
   parachute expose tailnet [off]    HTTPS across your tailnet (supported)
   parachute expose public  [off]    HTTPS on the public internet (exploratory)
-  parachute serve                   run hub HTTP server foregrounded (for containers)
+  parachute serve                   run the hub + supervisor foregrounded (the runtime)
+  parachute migrate --to-supervised move a legacy detached install to the managed hub
   parachute migrate [--dry-run]     archive legacy files at ecosystem root
   parachute auth <cmd>              identity (set password, manage 2FA)
   parachute vault <args...>         vault-specific ops (tokens, 2fa, config, init,
@@ -123,7 +124,9 @@ What it does:
   get you to that wizard.
 
   Idempotent — every re-run is safe:
-    1. If the hub isn't running, start it.
+    1. Install + start the hub as a managed unit (launchd on a Mac,
+       systemd on a Linux VM) so it survives reboots; no-op if it's
+       already up.
     2. If the hub isn't already exposed, in a terminal, offer to set up
        exposure (Tailscale Funnel, Cloudflare Tunnel, or stay loopback).
        The default highlights "no thanks" on laptops and Cloudflare on
@@ -273,11 +276,17 @@ Usage:
   parachute status
 
 What it does:
-  Reads ~/.parachute/services.json. For each registered service:
-    - checks PID file at ~/.parachute/<svc>/run/<svc>.pid
-    - probes http://localhost:<port><health> (skipped for known-stopped processes)
+  Reads ~/.parachute/services.json. For each registered module:
+    - reads its run state from the running hub's supervisor (supervisor.list())
+    - probes http://localhost:<port><health> (skipped for known-stopped modules)
     - classifies the install source as bun-linked (local checkout) or npm
 
+  The hub gets its own row, derived from the platform process manager
+  (launchd \`launchctl print\` / systemd \`systemctl is-active\`, or
+  "container runtime (managed)" on Render / Fly) — the supervisor runs the
+  modules, but the manager runs the hub. The hub row appears even with zero
+  modules installed.
+
   The STATE column rolls process state + probe result into one of four
   canonical labels (per parachute-patterns/patterns/design-system.md §6):
     active    supervised, running, last probe ok
@@ -293,10 +302,10 @@ What it does:
   HEALTH (ok / down / http <code>). Workstream F collapsed them onto the
   single STATE column the SPA + well-known doc also speak.
 
-  Stopped services render as STATE=inactive and don't count toward the
+  Stopped modules render as STATE=inactive and don't count toward the
   exit code — they're an expected state after fresh install before
-  \`parachute start\`. Running or externally-managed services that fail
-  health checks render as STATE=failing and exit 1.
+  \`parachute start\`. Supervised modules that fail health checks render
+  as STATE=failing and exit 1.
 
   A "STALE: services.json cached … live package.json …" continuation line
   appears under a row when a bun-linked service has been rebuilt but the
@@ -409,39 +418,41 @@ Cloudflare tunnel requirements (--cloudflare):
 }
 
 export function startHelp(): string {
-  return `parachute start — spawn services in the background
+  return `parachute start — start a module via the running hub's supervisor
 
 Usage:
-  parachute start                   start every installed service
-  parachute start <service>         start just that one
-  parachute start hub               start the internal hub (port 1939)
+  parachute start                   ensure the hub is up (boots every module)
+  parachute start <service>         start just that one module
+  parachute start hub               ensure the hub unit is up
 
 What it does:
-  For each target service, spawns its start command detached, redirects
-  stdout+stderr to ~/.parachute/<service>/logs/<service>.log, and records
-  the child PID at ~/.parachute/<service>/run/<service>.pid.
-
-  Idempotent: if the service is already running, no-op.
-  If a stale PID file exists (process died without cleanup), it's cleared
-  and the service starts fresh.
-
-  \`parachute start hub\` brings up the internal hub directly (normally
-  spawned implicitly by \`parachute expose\`). Useful when restarting a
-  hub that crashed without an active expose layer.
+  \`parachute serve\` is the one runtime — the hub foreground with an
+  in-process supervisor that runs each module as an attached child. These
+  verbs are clients of that running hub:
+
+  - \`parachute start <service>\` ensures the hub unit is up, then asks its
+    supervisor to start that one module (over the loopback module-ops API,
+    authenticated with your operator token). No per-module daemon is
+    spawned — the supervisor owns the module process.
+  - \`parachute start\` (no service) ensures the hub unit is up. The hub
+    boots every installed module on start, so this brings the whole stack
+    up. On a box with no hub unit yet, it offers to run
+    \`parachute migrate --to-supervised\` (which installs + starts the unit).
+  - \`parachute start hub\` is the same "ensure the hub unit is up."
+
+  Idempotent: starting an already-running module is a no-op.
 
 Flags:
-  --hub-origin <url>    override PARACHUTE_HUB_ORIGIN passed to services
+  --hub-origin <url>    override the hub origin used as the operator token's
+                        \`iss\` validator on the loopback module-ops call
                         (default: current expose-state hub origin, else loopback).
-                        For \`start hub\`, also doubles as the hub's --issuer.
 
 Examples:
   parachute start                   bring everything up
-  parachute start vault             just vault
-  parachute start hub               just the internal hub
+  parachute start vault             just vault, via the supervisor
   parachute logs vault              watch what just started
 
-Start commands by service:
-  hub       bun <cli>/hub-server.ts --port <picked> ...
+Module start commands (run by the supervisor under \`serve\`):
   vault     parachute-vault serve
   scribe    parachute-scribe serve
   app       parachute-app serve
@@ -451,39 +462,45 @@ Start commands by service:
 }
 
 export function stopHelp(): string {
-  return `parachute stop — stop running services cleanly
+  return `parachute stop — stop a module (or the hub) cleanly
 
 Usage:
-  parachute stop                    stop every installed service
-  parachute stop <service>          stop just that one
-  parachute stop hub                stop the internal hub
+  parachute stop                    stop the hub unit (modules stop with it)
+  parachute stop <service>          stop just that one module
+  parachute stop hub                stop the hub unit
 
 What it does:
-  Sends SIGTERM, waits up to 10s for a clean exit, then escalates to
-  SIGKILL if the process is still alive. Removes the PID file on success.
-
-  No-op if the service wasn't running.
-
-  Bare \`parachute stop\` (no service) does NOT stop the hub — that's
-  managed by the active expose layer (or \`parachute stop hub\` directly).
+  - \`parachute stop <service>\` asks the running hub's supervisor to stop
+    that one module (SIGTERM to the module's process group, then SIGKILL if
+    it doesn't exit). No-op if it wasn't running.
+  - \`parachute stop\` (no service) and \`parachute stop hub\` stop the hub
+    UNIT through the platform process manager (\`launchctl bootout\` /
+    \`systemctl stop\`) — never a raw PID signal, which launchd's KeepAlive
+    would just undo. Modules are attached children and stop with the hub.
 
 Examples:
-  parachute stop                    stop everything before sleep
-  parachute stop vault              just vault
-  parachute stop hub                just the internal hub
+  parachute stop vault              just vault, via the supervisor
+  parachute stop                    stop the whole stack (the hub unit)
 `;
 }
 
 export function restartHelp(): string {
-  return `parachute restart — stop then start
+  return `parachute restart — restart a module (or the hub)
 
 Usage:
-  parachute restart                 restart every installed service
-  parachute restart <service>       restart just that one
-  parachute restart hub             restart the internal hub
+  parachute restart                 restart the hub unit (re-boots every module)
+  parachute restart <service>       restart just that one module
+  parachute restart hub             restart the hub unit
 
 What it does:
-  Equivalent to \`parachute stop <svc> && parachute start <svc>\`.
+  - \`parachute restart <service>\` asks the running hub's supervisor to
+    restart that one module. If the module isn't currently supervised
+    (e.g. it crashed out of its restart budget), this falls through to a
+    fresh \`start\` so the verb is total over module state.
+  - \`parachute restart\` (no service) and \`parachute restart hub\` restart
+    the hub UNIT via the platform manager (\`launchctl kickstart -k\` /
+    \`systemctl restart\`), which re-boots every module — it is NOT a
+    fan-out of per-module restarts.
 `;
 }
 
@@ -523,6 +540,13 @@ What it does:
   package.json version unchanged after bun add -g), the restart is skipped.
   Re-running on an up-to-date install is a fast no-op.
 
+  The "restart" step matches the supervised model: upgrading a MODULE
+  restarts it via the running hub's supervisor; \`parachute upgrade hub\`
+  rewrites the binary on disk, then restarts the hub UNIT through the
+  platform manager (\`launchctl kickstart -k\` / \`systemctl restart\`), which
+  re-boots every module onto the new code. From the admin SPA (the no-CLI
+  Render / Fly path) the same hub-upgrade runs via POST /api/hub/upgrade.
+
 Channel detection (hub#332):
   Pre-1.0 governance ships two channels — \`@rc\` (the development chain) and
   \`@latest\` (explicitly-promoted stable). \`parachute upgrade\` reads the
@@ -556,16 +580,23 @@ If no log file exists yet, prints a hint to \`parachute start <service>\`.
 }
 
 export function serveHelp(): string {
-  return `parachute serve — run the hub HTTP server foregrounded
+  return `parachute serve — run the hub + supervisor foregrounded (the runtime)
 
 Usage:
   parachute serve
 
-The container shape. The on-box CLI flow (\`parachute expose\`) spawns the
-hub-server detached and tracks it via pidfile; \`parachute serve\` is the
-inverse — the hub IS the foreground process, lives as long as its
-supervisor wants it to, and exits on signal. Built for Docker / Render /
-systemd, but works fine for a foregrounded local debug too.
+This is the one runtime everywhere. The hub IS the foreground process: it
+runs the HTTP server on port 1939 AND an in-process supervisor that spawns
+every installed module as an attached child, multiplexes their logs into
+its own stdout, and crash-restarts them on a budget. It runs until it gets
+a signal, then SIGTERMs its children and exits.
+
+You don't normally invoke \`serve\` by hand — \`parachute init\` (or
+\`parachute migrate --to-supervised\`) installs it as a managed unit so your
+platform's process manager keeps it alive across crashes and reboots:
+launchd on a Mac, systemd on a Linux VM, the container runtime's CMD on
+Render / Fly. Run it directly only for a foregrounded local debug, or on an
+init-less host that can't host a unit.
 
 Environment:
   PORT                              bind port (default 1939). Render injects
@@ -598,12 +629,14 @@ Examples:
 }
 
 export function migrateHelp(): string {
-  return `parachute migrate — archive known-legacy files at the ecosystem root
+  return `parachute migrate — archive legacy root files, or cut over to the supervised model
 
 Usage:
   parachute migrate [--list] [--dry-run] [--yes]
+  parachute migrate --to-supervised
+  parachute migrate --teardown
 
-What it does:
+What it does (the default archive sweep):
   Scans ~/.parachute/ for files and directories that match the
   known-legacy allowlist (daily.db*, server.yaml, channel.log/err,
   channel.start.sh, top-level logs/, tokens.db*, and the legacy lens/
@@ -619,9 +652,11 @@ What it does:
   Dotfiles at the root (.env, .DS_Store, prior .archive-* dirs) are
   never touched.
 
-Safety:
+Archive-sweep safety:
   - Refuses to sweep while any service is running — stop them first
-    (\`parachute stop\`) or preview with \`--list\`.
+    (\`parachute stop\`) or preview with \`--list\`. A hub running under a
+    process-manager unit (the supervised model) is detected as running
+    via the platform manager too, not just its pidfile.
   - SQLite-shape files (\`*.db\`, \`*.db-wal\`, \`*.db-shm\`) get a
     \`[live-db]\` label and pull an extra confirmation; wal/shm
     consistency depends on all three moving together.
@@ -629,14 +664,39 @@ Safety:
     \`[unknown — skipping]\`, with skipped items printed last.
   - In a non-TTY shell (CI / piped), refuses without \`--yes\`.
 
+--to-supervised (detached → supervised cutover):
+  Migrate a legacy detached install (independent \`parachute start\`-spawned
+  daemons) to the supervised model: the hub runs as \`parachute serve\`
+  under your platform's process manager (launchd on macOS, systemd on
+  Linux), survives reboots, and supervises modules as children. The
+  cutover is idempotent + re-runnable, and ordered so it never races the
+  canonical hub port: it writes the unit file WITHOUT starting it, stops
+  the detached hub + modules, sweeps any process still bound to a declared
+  port, verifies the ports are free, THEN starts the unit and verifies the
+  hub is healthy. If anything fails partway it leaves the box recoverable
+  (unit written but not started) and you can simply re-run it. A box with
+  no service manager (a container / init-less host) can't host a unit —
+  run \`parachute serve\` in the foreground there instead.
+
+--teardown (cutover rollback):
+  Remove the hub process-manager unit. Idempotent + best-effort. Use it to
+  roll back a cutover: the unit is removed and you fall back to running the
+  hub with \`parachute serve\` (or re-run \`--to-supervised\` to reinstall it).
+  Run this BEFORE \`bun remove -g @openparachute/hub\` so a removed package
+  doesn't leave a unit pointing at a deleted binary.
+
 Flags:
-  --list        print the plan; make no changes (friendly preview)
-  --dry-run     synonym for --list (kept for back-compat)
-  --yes, -y     skip the confirmation prompt; required in non-TTY shells
+  --list           print the plan; make no changes (friendly preview)
+  --dry-run        synonym for --list (kept for back-compat)
+  --yes, -y        skip the confirmation prompt; required in non-TTY shells
+  --to-supervised  cut over a detached install to the supervised model
+  --teardown       remove the hub unit (cutover rollback)
 
 Examples:
-  parachute migrate --list          see what would move, without touching anything
-  parachute migrate                 interactive sweep (prompts before acting)
-  parachute migrate --yes           sweep without prompting
+  parachute migrate --list            see what would move, without touching anything
+  parachute migrate                   interactive sweep (prompts before acting)
+  parachute migrate --yes             sweep without prompting
+  parachute migrate --to-supervised   move to the supervised (serve-under-manager) model
+  parachute migrate --teardown        remove the hub unit (roll back the cutover)
 `;
 }