@openparachute/hub 0.6.2 → 0.6.3-rc.2

package/src/commands/migrate.ts

@@ -3,6 +3,12 @@ import { join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { CONFIG_DIR, SERVICES_MANIFEST_PATH } from "../config.ts";
 import { HUB_SVC } from "../hub-control.ts";
+import {
+  type HubUnitDeps,
+  type HubUnitState,
+  defaultHubUnitDeps,
+  queryHubUnitState,
+} from "../hub-unit.ts";
 import { type AliveFn, defaultAlive, processState } from "../process-state.ts";
 import { knownServices, shortNameForManifest } from "../service-spec.ts";
 import { readManifestLenient } from "../services-manifest.ts";
@@ -335,6 +341,31 @@ export async function defaultPrompt(question: string): Promise<string> {
   return answer;
 }
 
+/**
+ * Hub-unit-state query seam for the archive guard (§7.3). Production uses the
+ * real `queryHubUnitState` over `defaultHubUnitDeps`; tests inject a stub so the
+ * unit-managed-hub-detected-as-running path is exercised without a live
+ * systemctl/launchctl. Returns the platform manager's view of the hub unit.
+ */
+export type HubUnitStateQuery = (deps: HubUnitDeps) => { state: HubUnitState };
+
+/**
+ * The §7.3 archive-guard fix: a hub unit is "running, leave it alone" when the
+ * platform manager reports it `active` or `activating`. `failed` / `inactive` /
+ * `no-unit` / `no-manager` / `unknown` are NOT treated as running — those mean
+ * the unit isn't actively holding state at this moment.
+ *
+ * Deliberately conservative on `unknown`: an unparseable manager response is
+ * NOT a license to archive (that would re-introduce the silent fail-open), but
+ * it's also not a clear "running" signal — so we fall through to the pidfile
+ * check (which catches a detached-era hub) rather than blanket-refusing on a
+ * transient manager hiccup. `active`/`activating` is the unambiguous unit-up
+ * signal that the pidfile-only guard missed.
+ */
+function hubUnitReportsRunning(state: HubUnitState): boolean {
+  return state === "active" || state === "activating";
+}
+
 /**
  * Probe whether any managed service (or the hub) is currently running.
  * Returns the list of short names that are live; an empty list means the
@@ -343,15 +374,42 @@ export async function defaultPrompt(question: string): Promise<string> {
  * Reads services.json leniently so a malformed entry doesn't block the
  * pre-flight (better to surface "running: vault" + a corrupt-entry warning
  * elsewhere than to refuse migration on an unrelated parsing problem).
+ *
+ * §7.3 archive-guard fix: the hub liveness check is BOTH the pidfile
+ * (`processState(HUB_SVC)`, the detached-era signal) AND the platform manager
+ * (`queryHubUnitState`, the unit-era signal). A unit-managed hub writes NO
+ * pidfile, so `processState(HUB_SVC)` reports it not-running and the
+ * refuse-while-running guard would silently FAIL OPEN — `migrate` could archive
+ * `~/.parachute` out from under a live unit-managed hub. Querying the manager
+ * too closes that hole: an `active`/`activating` hub unit is correctly detected
+ * as running and the guard holds.
  */
 export function listRunningServices(
   configDir: string,
   manifestPath: string,
   alive: AliveFn,
+  hubUnitState: HubUnitStateQuery = queryHubUnitState,
+  hubUnitDeps: HubUnitDeps = defaultHubUnitDeps,
 ): string[] {
   const running: string[] = [];
+  // Detached-era signal: the hub pidfile.
   const hubState = processState(HUB_SVC, configDir, alive);
-  if (hubState.status === "running") running.push(HUB_SVC);
+  let hubRunning = hubState.status === "running";
+  // Unit-era signal (§7.3): the platform manager. A unit-managed hub has no
+  // pidfile, so without this it would fail open. Never throws — `queryHubUnitState`
+  // degrades to `unknown` on a manager hiccup; we only escalate to "running" on
+  // an unambiguous active/activating.
+  if (!hubRunning) {
+    try {
+      const unit = hubUnitState(hubUnitDeps);
+      if (hubUnitReportsRunning(unit.state)) hubRunning = true;
+    } catch {
+      // A manager-query failure must not crash the guard — fall through. The
+      // pidfile check already ran; treat an unqueryable manager as "no extra
+      // signal," neither forcing-running nor opening the gate.
+    }
+  }
+  if (hubRunning) running.push(HUB_SVC);
   let manifest: ReturnType<typeof readManifestLenient>;
   try {
     manifest = readManifestLenient(manifestPath);
@@ -385,6 +443,15 @@ export interface MigrateOpts {
    * non-interactive guard without manipulating real fds.
    */
   isTty?: boolean;
+  /**
+   * Test seam: the §7.3 platform-manager hub-unit-state query used by the
+   * archive guard. Production uses `queryHubUnitState`; tests inject a stub to
+   * exercise the unit-managed-hub-detected-as-running path without a live
+   * systemctl/launchctl.
+   */
+  hubUnitState?: HubUnitStateQuery;
+  /** Test seam: the hub-unit deps passed to `hubUnitState` (default production). */
+  hubUnitDeps?: HubUnitDeps;
 }
 
 export async function migrate(opts: MigrateOpts = {}): Promise<number> {
@@ -397,6 +464,8 @@ export async function migrate(opts: MigrateOpts = {}): Promise<number> {
   const yes = opts.yes ?? false;
   const alive = opts.alive ?? defaultAlive;
   const isTty = opts.isTty ?? Boolean(process.stdin.isTTY);
+  const hubUnitState = opts.hubUnitState ?? queryHubUnitState;
+  const hubUnitDeps = opts.hubUnitDeps ?? defaultHubUnitDeps;
 
   // Refuse-while-running: archiving a path a live daemon owns can corrupt
   // its state. Print the runners and bail before we read the directory.
@@ -404,7 +473,7 @@ export async function migrate(opts: MigrateOpts = {}): Promise<number> {
   // operator may explicitly want to see what would move while things are
   // up.
   if (!dryRun) {
-    const running = listRunningServices(configDir, manifestPath, alive);
+    const running = listRunningServices(configDir, manifestPath, alive, hubUnitState, hubUnitDeps);
     if (running.length > 0) {
       log("parachute migrate: services are currently running — refusing to sweep:");
       for (const short of running) log(`  - ${short}`);

package/src/commands/serve-boot.ts

@@ -47,6 +47,62 @@ export interface BootedModule {
   readonly reason?: string;
 }
 
+export interface SpawnReqShape {
+  short: string;
+  cmd: readonly string[];
+  cwd?: string;
+  env?: Record<string, string>;
+}
+
+export interface BuildSpawnRequestOpts {
+  /** Config dir ($PARACHUTE_HOME). Used to read the module's per-service `.env`. */
+  readonly configDir: string;
+  /** Canonical hub origin → child env `PARACHUTE_HUB_ORIGIN`. Skipped when absent. */
+  readonly hubOrigin?: string;
+  /**
+   * Extra env merged on top of the derived env (PORT / .env / HUB_ORIGIN).
+   * Wins over all of them. Used by the API `start` handler's test seam +
+   * first-boot vault-name pass-through (`spawnEnv`). Empty/absent on the
+   * boot path.
+   */
+  readonly extraEnv?: Record<string, string>;
+}
+
+/**
+ * Build the `Supervisor.start` request for a single module, identically on
+ * both the serve-boot path and the `POST /api/modules/:short/start` handler.
+ *
+ * Env layering (later wins):
+ *   1. `PORT` from the services.json `entry.port` — overrides hub's own PORT
+ *      so supervised children honor their canonical port assignment
+ *      (hub#356/#357).
+ *   2. per-service `.env` at `<configDir>/<short>/.env` — operator-configured
+ *      values (e.g. scribe provider keys) override the bare PORT.
+ *   3. `PARACHUTE_HUB_ORIGIN` = `opts.hubOrigin` — anchors the child's `iss`
+ *      expectation to the value hub mints with (hub#365).
+ *   4. `opts.extraEnv` — test seam / first-boot pass-through; wins last.
+ *
+ * `cwd` is set to `entry.installDir` when present (third-party modules ship
+ * relative startCmds that need it; first-party fallbacks use absolute / PATH
+ * binaries so cwd is a no-op there).
+ */
+export function buildModuleSpawnRequest(
+  short: string,
+  entry: ServiceEntry,
+  cmd: readonly string[],
+  opts: BuildSpawnRequestOpts,
+): SpawnReqShape {
+  const fileEnv = readEnvFileValues(join(opts.configDir, short, ".env"));
+  const env: Record<string, string> = { PORT: String(entry.port), ...fileEnv };
+  if (opts.hubOrigin) env[HUB_ORIGIN_ENV] = opts.hubOrigin;
+  if (opts.extraEnv) Object.assign(env, opts.extraEnv);
+
+  const req: SpawnReqShape = { short, cmd };
+  if (entry.installDir) req.cwd = entry.installDir;
+  if (Object.keys(env).length > 0) req.env = env;
+  return req;
+}
+
 /**
  * Walk services.json, spawn every manageable module via the
  * supervisor. Returns a per-module decision log so the caller can
@@ -92,32 +148,22 @@ export async function bootSupervisedModules(
       continue;
     }
 
-    // PORT override (hub#357 — third spawn site missed by hub#356).
-    // Without this, modules that read process.env.PORT (vault, scribe)
-    // inherit hub's PORT from Bun.spawn's env: process.env default and
-    // crash EADDRINUSE on hub's port. Container deploy was still broken
-    // after #356 because this BOOT path runs on hub startup before the
-    // supervisor's other spawn paths see any traffic. fileEnv wins on
-    // collision so per-service .env can still override.
-    const fileEnv = readEnvFileValues(join(opts.configDir, short, ".env"));
-    const env: Record<string, string> = { PORT: String(entry.port), ...fileEnv };
-    if (opts.hubOrigin) env[HUB_ORIGIN_ENV] = opts.hubOrigin;
-
-    const req: {
-      short: string;
-      cmd: readonly string[];
-      cwd?: string;
-      env?: Record<string, string>;
-    } = {
-      short,
-      cmd,
-    };
-    // Third-party modules ship clean relative startCmds — cwd:
-    // installDir makes them resolve. First-party fallbacks use
-    // absolute / PATH binaries so cwd is a no-op there.
-    if (entry.installDir) req.cwd = entry.installDir;
-    if (Object.keys(env).length > 0) req.env = env;
+    // PORT override (hub#357 — third spawn site missed by hub#356), per-service
+    // .env merge, and PARACHUTE_HUB_ORIGIN propagation (hub#365) all live in the
+    // shared `buildModuleSpawnRequest` so the `POST /api/modules/:short/start`
+    // handler builds an identical request (design 2026-06-01 §3.3).
+    const req = buildModuleSpawnRequest(short, entry, cmd, {
+      configDir: opts.configDir,
+      ...(opts.hubOrigin !== undefined ? { hubOrigin: opts.hubOrigin } : {}),
+    });
 
+    // Serial await, not Promise.all: `supervisor.start` now carries a bounded
+    // post-spawn port-readiness gate (DEFAULT_START_READY_MS), so boot latency
+    // is the SUM of each slow-binding module's gate wait before `Bun.serve`
+    // comes up. Intentional — sequential boot keeps the start-error/install-card
+    // surface ordered and avoids a thundering-herd of port probes. Don't switch
+    // to `Promise.all` without accounting for the gate (it'd overlap the waits
+    // but also fire N concurrent readiness probes mid-boot).
     await supervisor.start(req);
     log(`[supervisor] ${short}: started (cmd=${cmd.join(" ")}).`);
     results.push({ short, entryName: entry.name, status: "started" });