@openparachute/hub 0.7.4-rc.1 → 0.7.4-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.4-rc.1",
+  "version": "0.7.4-rc.2",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {

package/src/__tests__/status-supervisor.test.ts

@@ -80,6 +80,12 @@ interface SupervisorArmOpts {
   hubHealthy: boolean;
   moduleStates?: ModuleStatesResult;
   fetchModuleStatesImpl?: () => Promise<ModuleStatesResult>;
+  /**
+   * Inject the unauthenticated module-liveness probe (#700). Defaults to "every
+   * module is down" so the degraded-read tests don't accidentally hit the
+   * network; specific tests override to mark a module live.
+   */
+  probeModuleHealth?: (port: number, health: string) => Promise<boolean>;
 }
 
 /** Drive `status` through the supervisor arm with fully stubbed seams. */
@@ -96,6 +102,7 @@ function supervisorOpts(configDir: string, path: string, o: SupervisorArmOpts) {
       fetchModuleStates:
         o.fetchModuleStatesImpl ??
         (async () => o.moduleStates ?? { supervisorAvailable: true, modules: [] }),
+      probeModuleHealth: o.probeModuleHealth ?? (async () => false),
       openDb: fakeOpenDb as unknown as (configDir: string) => import("bun:sqlite").Database,
     },
   };
@@ -377,7 +384,7 @@ describe("status — Phase 3c supervisor arm: module rows", () => {
     }
   });
 
-  test("no operator token → graceful degrade (manifest rows + actionable hint), no 401 crash", async () => {
+  test("no operator token (fresh box, no admin) → note targets set-password, NOT rotate-operator (#700)", async () => {
     const { path, configDir, cleanup } = makeTempPath();
     try {
       upsertService(
@@ -392,15 +399,121 @@ describe("status — Phase 3c supervisor arm: module rows", () => {
           fetchModuleStatesImpl: async () => {
             throw new NoOperatorTokenError();
           },
+          // No probe-live module here → row stays inactive (exit 0).
+          probeModuleHealth: async () => false,
         }),
         print: (l) => lines.push(l),
       });
       // We could not read run-state, but didn't crash. The module row falls back
-      // to `inactive` (no supervisor snapshot) — a stopped row is exit 0.
+      // to `inactive` (no supervisor snapshot, probe down) — a stopped row is exit 0.
       expect(code).toBe(0);
       const out = lines.join("\n");
       expect(out).toMatch(/parachute-vault/);
-      expect(out).toMatch(/run `parachute auth rotate-operator`/);
+      // #700: a fresh box has no admin, so rotate-operator would itself error.
+      // The note must point at set-password and must NOT be the bare
+      // rotate-operator guidance.
+      expect(out).toMatch(/parachute auth set-password/);
+      expect(out).not.toMatch(/run `parachute auth rotate-operator` to mint an operator token/);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\binactive\b/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("no operator token + module answers /health probe → LIVE (active), not inactive (#700)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        { name: "parachute-vault", port: 1940, paths: ["/"], health: "/health", version: "0.6.2" },
+        path,
+      );
+      const probed: Array<{ port: number; health: string }> = [];
+      const lines: string[] = [];
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          fetchModuleStatesImpl: async () => {
+            throw new NoOperatorTokenError();
+          },
+          // vault is genuinely up — its /health answers (2xx or 401 → live).
+          probeModuleHealth: async (port, health) => {
+            probed.push({ port, health });
+            return true;
+          },
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      // The probe targeted the module's own port + health path from the manifest.
+      expect(probed).toEqual([{ port: 1940, health: "/health" }]);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\bactive\b/);
+      expect(vaultLine).not.toMatch(/\binactive\b/);
+      const out = lines.join("\n");
+      // The row is labelled as probe-derived so the operator knows it's thin.
+      expect(out).toMatch(/live via unauthenticated health probe/);
+      // The degraded-read hint still appears (why PID/uptime are absent).
+      expect(out).toMatch(/parachute auth set-password/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("degraded read + module probe FAILS → row stays inactive (#700)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        { name: "parachute-vault", port: 1940, paths: ["/"], health: "/health", version: "0.6.2" },
+        path,
+      );
+      const lines: string[] = [];
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          fetchModuleStatesImpl: async () => {
+            throw new NoOperatorTokenError();
+          },
+          probeModuleHealth: async () => false,
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\binactive\b/);
+      const out = lines.join("\n");
+      expect(out).not.toMatch(/live via unauthenticated health probe/);
+    } finally {
+      cleanup();
+    }
+  });
+
+  test("a throwing module probe never crashes status — row degrades to inactive (#700)", async () => {
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        { name: "parachute-vault", port: 1940, paths: ["/"], health: "/health", version: "0.6.2" },
+        path,
+      );
+      const lines: string[] = [];
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          fetchModuleStatesImpl: async () => {
+            throw new NoOperatorTokenError();
+          },
+          probeModuleHealth: async () => {
+            throw new Error("probe exploded");
+          },
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\binactive\b/);
     } finally {
       cleanup();
     }
@@ -433,6 +546,42 @@ describe("status — Phase 3c supervisor arm: module rows", () => {
     }
   });
 
+  test("expired operator token + module answers /health probe → LIVE (active) (#700)", async () => {
+    // Symmetry with the no-token case: the unauthenticated probe fallback fires
+    // on ANY degraded read where the hub is up + run-state is missing, so an
+    // expired-token box still shows a genuinely-serving module as `active`.
+    const { path, configDir, cleanup } = makeTempPath();
+    try {
+      upsertService(
+        { name: "parachute-vault", port: 1940, paths: ["/"], health: "/health", version: "0.6.2" },
+        path,
+      );
+      const lines: string[] = [];
+      const code = await status({
+        ...supervisorOpts(configDir, path, {
+          managerState: { state: "active" },
+          hubHealthy: true,
+          fetchModuleStatesImpl: async () => {
+            throw new OperatorTokenExpiredError(
+              "token expired — run `parachute auth rotate-operator`",
+            );
+          },
+          probeModuleHealth: async () => true,
+        }),
+        print: (l) => lines.push(l),
+      });
+      expect(code).toBe(0);
+      const vaultLine = lines.find((l) => l.includes("parachute-vault"));
+      expect(vaultLine).toMatch(/\bactive\b/);
+      const out = lines.join("\n");
+      expect(out).toMatch(/live via unauthenticated health probe/);
+      // The expired-token degraded-read hint still points at rotate-operator.
+      expect(out).toMatch(/rotate-operator/);
+    } finally {
+      cleanup();
+    }
+  });
+
   test("API error reading module states → degrade with the message, no crash", async () => {
     const { path, configDir, cleanup } = makeTempPath();
     try {

package/src/commands/status.ts

@@ -19,8 +19,8 @@ import {
 } from "../install-source.ts";
 import {
   type DriveModuleOpDeps,
-  type ModuleStatesResult,
   type ModuleStateSnapshot,
+  type ModuleStatesResult,
   NoOperatorTokenError,
   OperatorTokenExpiredError,
   fetchModuleStates as fetchModuleStatesImpl,
@@ -71,6 +71,17 @@ export interface StatusOpts {
     probeHubHealth?: (port: number) => Promise<boolean>;
     /** Read the running supervisor's module states (§6.4 module rows). */
     fetchModuleStates?: (deps: DriveModuleOpDeps) => Promise<ModuleStatesResult>;
+    /**
+     * Unauthenticated module-liveness probe (#700). Used ONLY on the degraded
+     * path where the supervisor run-state read couldn't run (no/expired/invalid
+     * operator token, or any API error) but the hub itself is up: probes a
+     * module's own `/health` directly on its loopback port. Treats 2xx AND 401
+     * as live (mirrors the "auth-gated health = healthy" rule, #423: a module
+     * that answers 401 is authenticated-but-alive, not down). Bounded; never
+     * throws. Production reuses the same bounded fetch shape as the hub probe;
+     * tests inject so they don't hit the network.
+     */
+    probeModuleHealth?: (port: number, health: string) => Promise<boolean>;
     /**
      * Open the hub DB used to validate/auto-rotate the operator token in
      * `fetchModuleStates`. Production opens `<configDir>/hub.db`; tests inject a
@@ -162,6 +173,15 @@ interface StatusRow {
    * Printed on a continuation line like the other notes.
    */
   managerNote?: string;
+  /**
+   * Set on a module row whose STATE was derived from an unauthenticated
+   * `/health` probe rather than the supervisor's run-state (#700) — the
+   * degraded-read fallback (no/expired operator token, or an API error) where
+   * the module is genuinely serving. Tells the operator the row is live-but-
+   * thin: no PID/uptime/structured run-state until they sign in. Printed on a
+   * continuation line like the other notes.
+   */
+  probeNote?: string;
 }
 
 /**
@@ -319,6 +339,7 @@ function renderRows(rows: StatusRow[], print: (line: string) => void): void {
       print(`  ! probe: ${row.healthDetail}`);
     }
     if (row.managerNote) print(`  ! ${row.managerNote}`);
+    if (row.probeNote) print(`  → ${row.probeNote}`);
     if (row.driftWarning) print(`  ! ${row.driftWarning}`);
     if (row.staleNote) print(`  ! ${row.staleNote}`);
     if (row.startErrorNote) print(`  ! ${row.startErrorNote}`);
@@ -336,12 +357,33 @@ function renderRows(rows: StatusRow[], print: (line: string) => void): void {
 // in Phase 5b.
 // ---------------------------------------------------------------------------
 
+/**
+ * Default unauthenticated module-liveness probe (#700). A bounded `fetch` to the
+ * module's own `http://127.0.0.1:<port><health>`. Treats 2xx AND 401 as live —
+ * an auth-gated `/health` that answers 401 is authenticated-but-alive, not down
+ * (the "auth-gated health = healthy" rule, #423). Any other status / network
+ * error / timeout → false. 1.5s timeout, mirroring hub-unit's `defaultProbeHealth`.
+ */
+async function defaultProbeModuleHealth(port: number, health: string): Promise<boolean> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}${health}`, {
+      signal: AbortSignal.timeout(1500),
+      // Loopback-only target, but never chase a redirect off-box (defensive).
+      redirect: "manual",
+    });
+    return res.ok || res.status === 401;
+  } catch {
+    return false;
+  }
+}
+
 /** Resolved supervisor-path seams (see `StatusOpts.supervisor`). */
 interface ResolvedStatusSupervisor {
   hubUnitDeps: HubUnitDeps;
   queryHubUnitState: (deps: HubUnitDeps) => HubUnitStateResult;
   probeHubHealth: (port: number) => Promise<boolean>;
   fetchModuleStates: (deps: DriveModuleOpDeps) => Promise<ModuleStatesResult>;
+  probeModuleHealth: (port: number, health: string) => Promise<boolean>;
   openDb: (configDir: string) => Database;
   baseUrl: string | undefined;
 }
@@ -357,6 +399,7 @@ function resolveStatusSupervisor(opts: StatusOpts["supervisor"]): ResolvedStatus
     queryHubUnitState: opts?.queryHubUnitState ?? queryHubUnitStateImpl,
     probeHubHealth: opts?.probeHubHealth ?? hubUnitDeps.probeHealth,
     fetchModuleStates: opts?.fetchModuleStates ?? fetchModuleStatesImpl,
+    probeModuleHealth: opts?.probeModuleHealth ?? defaultProbeModuleHealth,
     openDb: opts?.openDb ?? ((configDir) => openHubDb(hubDbPath(configDir))),
     baseUrl: opts?.baseUrl,
   };
@@ -471,10 +514,17 @@ async function buildSupervisorRows(args: BuildSupervisorRowsArgs): Promise<Statu
         ...(sup.baseUrl !== undefined ? { baseUrl: sup.baseUrl } : {}),
       });
     } catch (err) {
-      if (err instanceof NoOperatorTokenError || err instanceof OperatorTokenExpiredError) {
-        // No / expired operator token: we can't read module run-state, but the
-        // hub is up. Show the manifest-derived rows with an actionable note —
-        // do NOT 401-crash status (§6.4 graceful degradation).
+      if (err instanceof NoOperatorTokenError) {
+        // No operator token AND none can be minted yet — on a fresh box the
+        // first admin doesn't exist, so `rotate-operator` would itself hard-error
+        // ("no hub users yet"). Point at `set-password` (create the first admin),
+        // the actual unblocking step. We still can't read run-state, but the hub
+        // is up — degrade gracefully (§6.4), do NOT 401-crash status (#700).
+        moduleReadNote =
+          "couldn't read live module state — run `parachute auth set-password` to create the first admin (then `parachute auth rotate-operator`)";
+      } else if (err instanceof OperatorTokenExpiredError) {
+        // Token exists but is stale: an admin already exists, so re-minting works.
+        // Keep the rotate-operator guidance.
         moduleReadNote =
           "couldn't read live module state — run `parachute auth rotate-operator` to mint an operator token";
       } else {
@@ -500,6 +550,26 @@ async function buildSupervisorRows(args: BuildSupervisorRowsArgs): Promise<Statu
     if (m.short && !stateByShort.has(m.short)) stateByShort.set(m.short, m);
   }
 
+  // Unauthenticated-liveness fallback (#700). On the degraded path — the hub is
+  // up but we couldn't read supervisor run-state (no/expired operator token, or
+  // an API error) — probe each module's own `/health` directly so a module that
+  // is genuinely serving reads LIVE instead of being mapped null→`inactive`
+  // (which falsely told fresh-box operators a working install was broken). Keyed
+  // by the unique `entry.name`; probed concurrently, bounded, never throws.
+  const probeAlive = new Map<string, boolean>();
+  if (hubHealthy && !states) {
+    await Promise.all(
+      manifest.services.map(async (entry) => {
+        try {
+          const alive = await sup.probeModuleHealth(entry.port, entry.health);
+          if (alive) probeAlive.set(entry.name, true);
+        } catch {
+          // Probe must never crash status — absent from the map = treated as down.
+        }
+      }),
+    );
+  }
+
   const rows: StatusRow[] = manifest.services.map((entry) => {
     const base = manifestRowBase(entry, installSourceDeps);
     const snap = base.short ? stateByShort.get(base.short) : undefined;
@@ -526,6 +596,39 @@ async function buildSupervisorRows(args: BuildSupervisorRowsArgs): Promise<Statu
       };
     }
 
+    // Degraded read, but the module answered an unauthenticated `/health` probe
+    // (#700): show it LIVE instead of null→`inactive`. We can't surface PID/
+    // uptime/structured run-state (those need the operator token), so keep the
+    // degraded `moduleReadNote` AND add a probe-derived continuation note so the
+    // operator understands the row is from a liveness probe, not full supervisor
+    // state. `skipped: true` keeps a working install at exit 0.
+    if (!snap && probeAlive.get(entry.name)) {
+      const row: StatusRow = {
+        service: entry.name,
+        port: String(entry.port),
+        version: entry.version,
+        stateLabel: "active",
+        pidLabel: "-",
+        uptimeLabel: "-",
+        healthDetail: "-",
+        latencyLabel: "-",
+        sourceLabel: base.sourceLabel,
+        url: base.url,
+        healthy: true,
+        skipped: true,
+      };
+      row.probeNote = "live via unauthenticated health probe — sign in for full supervisor state";
+      if (base.driftWarning) row.driftWarning = base.driftWarning;
+      if (base.staleNote) row.staleNote = base.staleNote;
+      if (base.manifestStartErrorNote) row.startErrorNote = base.manifestStartErrorNote;
+      // Surface the degraded-read note ONCE (first module row), same as below.
+      if (moduleReadNote) {
+        row.managerNote = moduleReadNote;
+        moduleReadNote = undefined;
+      }
+      return row;
+    }
+
     const { stateLabel, healthy, skipped } = mapSupervisorStatus(snap?.supervisor_status ?? null);
     // Prefer the supervisor's structured start-error (live), else the persisted
     // services.json note — same friendly surface either way (#188).