@openparachute/hub 0.6.2 → 0.6.3-rc.2

package/src/api-modules.ts

@@ -42,8 +42,13 @@ import { FIRST_PARTY_FALLBACKS, KNOWN_MODULES } from "./service-spec.ts";
 // still required) and the latter for vault/scribe/runner (post-FALLBACK
 // retirement, hub#310). The local helper hides the split from the rest of
 // this file.
-import { type UiSubUnit, type UiSubUnitStatus, readManifest, readManifestLenient } from "./services-manifest.ts";
-import type { ModuleState, Supervisor } from "./supervisor.ts";
+import {
+  type UiSubUnit,
+  type UiSubUnitStatus,
+  readManifest,
+  readManifestLenient,
+} from "./services-manifest.ts";
+import type { ModuleStartError, ModuleState, Supervisor } from "./supervisor.ts";
 
 /**
  * Resolve a curated module to the display + install bootstrap data the
@@ -174,6 +179,16 @@ interface ModuleWireShape {
   latest_version: string | null;
   supervisor_status: ModuleState["status"] | null;
   pid: number | null;
+  /**
+   * Structured supervisor start-failure detail (§6.5 / §6.4), when the
+   * supervisor recorded one for this module — a preflight `MissingDependencyError`
+   * or the alive-but-never-bound shape (hub#487). Mirrors the services.json
+   * `lastStartError` the detached path persists, so `parachute status` and the
+   * SPA keep the SAME friendly missing-dependency surface (#188) whether a
+   * module was started via the supervisor or the detached path. Null when the
+   * module started cleanly (or the hub is in pidfile/CLI mode with no supervisor).
+   */
+  supervisor_start_error: ModuleStartError | null;
   /**
    * The path on disk where the module is installed, if known. Surfaces
    * the BUN_INSTALL or bun-link install location for operator debug —
@@ -477,6 +492,7 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       latest_version: latestByShort.get(short) ?? null,
       supervisor_status: state?.status ?? null,
       pid: state?.pid ?? null,
+      supervisor_start_error: state?.startError ?? null,
       install_dir: installed?.installDir ?? null,
       uis: toUisWireShape(installed?.uis),
       management_url: managementUrlByShort.get(short) ?? null,

package/src/cli.ts

@@ -14,6 +14,7 @@ import { exposePublic, exposeTailnet } from "./commands/expose.ts";
 import { init } from "./commands/init.ts";
 import { install } from "./commands/install.ts";
 import { logs, restart, start, stop } from "./commands/lifecycle.ts";
+import { cutoverToSupervised, teardownHubUnit } from "./commands/migrate-cutover.ts";
 import { migrate } from "./commands/migrate.ts";
 import { serve } from "./commands/serve.ts";
 import { setup } from "./commands/setup.ts";
@@ -454,7 +455,11 @@ async function main(argv: string[]): Promise<number> {
         console.log(statusHelp());
         return 0;
       }
-      return await status();
+      // Pass an empty `supervisor` block so `status` takes the Phase 3c
+      // dual-dispatch: on a box with a hub unit installed it reads the platform
+      // manager + the running supervisor; on a legacy detached box it falls back
+      // to the pidfile readout (design §6.4). Tests drive the seams directly.
+      return await status({ supervisor: {} });
 
     case "expose": {
       const hubExtract = extractHubOrigin(rest);
@@ -528,7 +533,14 @@ async function main(argv: string[]): Promise<number> {
         const { exposeCloudflareUp, exposeCloudflareOff } = await import(
           "./commands/expose-cloudflare.ts"
         );
-        const cfOpts = flagExtract.tunnelName ? { tunnelName: flagExtract.tunnelName } : {};
+        // `supervisor: {}` opts into the Phase 4 dual-dispatch (design §4.3): on
+        // a box with a hub unit installed, ensure the unit + drive the running
+        // supervisor for the post-expose vault restart, and leave the hub running
+        // on `off`; on a legacy detached box (no unit), the unchanged path.
+        const cfOpts = {
+          supervisor: {},
+          ...(flagExtract.tunnelName ? { tunnelName: flagExtract.tunnelName } : {}),
+        };
         if (action === "off") {
           return await exposeCloudflareOff(cfOpts);
         }
@@ -540,7 +552,14 @@ async function main(argv: string[]): Promise<number> {
           // doesn't block on an invisible prompt.
           if (isTtyInteractive()) {
             const { exposePublicInteractive } = await import("./commands/expose-interactive.ts");
-            return await exposePublicInteractive({ preselect: "cloudflare" });
+            // Thread `supervisor: {}` into BOTH provider opts so the interactive
+            // path takes the Phase 4 unit-arm on a unit-managed box regardless of
+            // which provider the operator picks (design §4.3).
+            return await exposePublicInteractive({
+              preselect: "cloudflare",
+              exposeOpts: { supervisor: {} },
+              cloudflareOpts: { supervisor: {} },
+            });
           }
           console.error("parachute expose public --cloudflare: --domain <hostname> is required.");
           console.error("Example: parachute expose public --cloudflare --domain vault.example.com");
@@ -557,7 +576,14 @@ async function main(argv: string[]): Promise<number> {
         return await exposeCloudflareUp(flagExtract.domain, cfOpts);
       }
 
-      const exposeOpts = hubExtract.hubOrigin ? { hubOrigin: hubExtract.hubOrigin } : {};
+      // `supervisor: {}` opts into the Phase 4 dual-dispatch (design §4.3): on a
+      // box with a hub unit installed, ensure the unit (not a detached spawn) +
+      // drive the running supervisor for the post-expose vault restart, and leave
+      // the hub running on `off`; on a legacy detached box, the unchanged path.
+      const exposeOpts = {
+        supervisor: {},
+        ...(hubExtract.hubOrigin ? { hubOrigin: hubExtract.hubOrigin } : {}),
+      };
 
       // `--tailnet` is the explicit Tailscale Funnel pin — bypass both the
       // interactive picker and the non-TTY auto-pick. Goes straight to
@@ -572,7 +598,9 @@ async function main(argv: string[]): Promise<number> {
       // hands back to the flag-driven entry points.
       if (layer === "public" && action === "up" && isTtyInteractive()) {
         const { exposePublicInteractive } = await import("./commands/expose-interactive.ts");
-        return await exposePublicInteractive({ exposeOpts });
+        // `exposeOpts` already carries `supervisor: {}`; thread it into the
+        // Cloudflare branch too so the unit-arm applies regardless of pick.
+        return await exposePublicInteractive({ exposeOpts, cloudflareOpts: { supervisor: {} } });
       }
 
       // Non-TTY auto-pick: detect which provider is configured and run it.
@@ -591,7 +619,12 @@ async function main(argv: string[]): Promise<number> {
       // guessing intent.
       if (layer === "public" && action === "up" && !flagExtract.skipProviderCheck) {
         const { exposePublicAutoPick } = await import("./commands/expose-public-auto.ts");
-        return await exposePublicAutoPick({ tailscaleOpts: exposeOpts });
+        // `tailscaleOpts` carries `supervisor: {}`; thread it into the Cloudflare
+        // branch too so the Phase 4 unit-arm applies regardless of auto-pick.
+        return await exposePublicAutoPick({
+          tailscaleOpts: exposeOpts,
+          cloudflareOpts: { supervisor: {} },
+        });
       }
 
       // `expose public off` (no `--cloudflare`) auto-detects which provider is
@@ -600,7 +633,16 @@ async function main(argv: string[]): Promise<number> {
       // remember which provider they brought up last.
       if (layer === "public" && action === "off") {
         const { runExposePublicOffAutoDetect } = await import("./commands/expose-off-auto.ts");
-        return await runExposePublicOffAutoDetect({ tailscaleOffOpts: exposeOpts });
+        // `tailscaleOffOpts` carries `supervisor: {}`; thread it into the
+        // Cloudflare teardown leg too so the Phase 4 supervisor resolution is
+        // consistent across both providers on the auto-detect path (matching
+        // the explicit `--cloudflare off` branch above). Harmless today
+        // (exposeCloudflareOff has no stopHub call) but keeps `supervisor: {}`
+        // threaded everywhere.
+        return await runExposePublicOffAutoDetect({
+          tailscaleOffOpts: exposeOpts,
+          cloudflareOffOpts: { supervisor: {} },
+        });
       }
 
       // `--skip-provider-check` fallthrough: pin to today's Tailscale-Funnel
@@ -624,7 +666,17 @@ async function main(argv: string[]): Promise<number> {
         console.error(`parachute start: ${hubExtract.error}`);
         return 1;
       }
-      const startOpts = hubExtract.hubOrigin ? { hubOrigin: hubExtract.hubOrigin } : {};
+      // `supervisor: {}` opts into the Phase 3b dual-dispatch: on a box with a
+      // hub unit installed, drive the running supervisor; on a legacy detached
+      // box (no unit), fall through to the unchanged detached path (design §3.3).
+      // `migrateOffer: { enabled: true }` arms the §7.5 detect-and-offer on the
+      // detached arm (offers the supervised cutover when a prior detached
+      // install is found; never auto-migrates).
+      const startOpts = {
+        supervisor: {},
+        migrateOffer: { enabled: true },
+        ...(hubExtract.hubOrigin ? { hubOrigin: hubExtract.hubOrigin } : {}),
+      };
       return await start(hubExtract.rest[0], startOpts);
     }
 
@@ -633,7 +685,7 @@ async function main(argv: string[]): Promise<number> {
         console.log(stopHelp());
         return 0;
       }
-      return await stop(rest[0]);
+      return await stop(rest[0], { supervisor: {}, migrateOffer: { enabled: true } });
     }
 
     case "restart": {
@@ -641,7 +693,7 @@ async function main(argv: string[]): Promise<number> {
         console.log(restartHelp());
         return 0;
       }
-      return await restart(rest[0]);
+      return await restart(rest[0], { supervisor: {}, migrateOffer: { enabled: true } });
     }
 
     case "upgrade": {
@@ -682,7 +734,11 @@ async function main(argv: string[]): Promise<number> {
         );
         return 1;
       }
-      const upgradeOpts: Parameters<typeof upgrade>[1] = {};
+      // `supervisor: {}` opts into the Phase 4 dual-dispatch (design §5): on a
+      // box with a hub unit installed, `upgrade hub` rewrites the binary then
+      // restarts the UNIT via the platform manager (children re-boot from
+      // services.json); on a legacy detached box, the unchanged restart path.
+      const upgradeOpts: Parameters<typeof upgrade>[1] = { supervisor: {} };
       if (tagExtract.tag) upgradeOpts.tag = tagExtract.tag;
       if (channelExtract.value === "rc" || channelExtract.value === "latest") {
         upgradeOpts.channel = channelExtract.value;
@@ -711,6 +767,33 @@ async function main(argv: string[]): Promise<number> {
         console.log(migrateHelp());
         return 0;
       }
+      // §7.4 teardown — remove the hub unit (the cutover rollback path).
+      if (rest.includes("--teardown")) {
+        const teardownUnknown = rest.find((a) => a !== "--teardown");
+        if (teardownUnknown !== undefined) {
+          console.error(`parachute migrate: unknown argument "${teardownUnknown}"`);
+          console.error("usage: parachute migrate --teardown");
+          return 1;
+        }
+        teardownHubUnit();
+        return 0;
+      }
+      // §7.1 detached→supervised cutover. Opt-in surface (the archive sweep
+      // below stays the bare `migrate` default — the cutover is destructive-
+      // adjacent and must be asked for, not implicit).
+      if (rest.includes("--to-supervised")) {
+        const cutoverUnknown = rest.find((a) => a !== "--to-supervised");
+        if (cutoverUnknown !== undefined) {
+          console.error(`parachute migrate: unknown argument "${cutoverUnknown}"`);
+          console.error("usage: parachute migrate --to-supervised");
+          return 1;
+        }
+        const result = await cutoverToSupervised();
+        for (const line of result.messages) console.log(line);
+        // "already-migrated" / "migrated" are success; every other outcome is a
+        // recoverable failure that should exit non-zero so scripts can retry.
+        return result.outcome === "migrated" || result.outcome === "already-migrated" ? 0 : 1;
+      }
       const dryRun = rest.includes("--dry-run");
       const list = rest.includes("--list");
       const yes = rest.includes("--yes") || rest.includes("-y");
@@ -719,7 +802,9 @@ async function main(argv: string[]): Promise<number> {
       );
       if (unknown !== undefined) {
         console.error(`parachute migrate: unknown argument "${unknown}"`);
-        console.error("usage: parachute migrate [--list] [--dry-run] [--yes]");
+        console.error(
+          "usage: parachute migrate [--list] [--dry-run] [--yes] [--to-supervised] [--teardown]",
+        );
         return 1;
       }
       return await migrate({ dryRun, list, yes });