@openparachute/hub 0.6.3 → 0.6.4-rc.2

package/src/cli.ts

@@ -9,19 +9,16 @@
 import { MissingDependencyError } from "@openparachute/depcheck";
 import pkg from "../package.json" with { type: "json" };
 import { CloudflaredStateError } from "./cloudflare/state.ts";
-import { auth } from "./commands/auth.ts";
-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";
-import { status } from "./commands/status.ts";
-import { upgrade } from "./commands/upgrade.ts";
-import { dispatchVault } from "./commands/vault.ts";
-import { runSetupWizardCommand } from "./commands/wizard.ts";
+// Command-implementation modules are loaded LAZILY inside their switch arms (see
+// `loadCommand` + each `case`), so a module that throws at eval-time is isolated
+// to its own command instead of aborting the whole CLI at top-level import. The
+// `import type`s below are erased at compile time (they trigger no module
+// evaluation) and exist only so the arms can reference each command's options
+// type for `Parameters<typeof …>`.
+import type { init } from "./commands/init.ts";
+import type { install } from "./commands/install.ts";
+import type { setup } from "./commands/setup.ts";
+import type { upgrade } from "./commands/upgrade.ts";
 import { ExposeStateError } from "./expose-state.ts";
 import {
   exposeHelp,
@@ -273,6 +270,34 @@ function extractExposeProviderFlags(args: string[]): {
   return out;
 }
 
+/**
+ * Lazy-load a command-implementation module, isolating an eval-time throw to the
+ * command that asked for it.
+ *
+ * `cli.ts` used to eagerly `import` every command module at top-level. That made
+ * a single broken module (e.g. a half-built `migrate-cutover.ts` with a
+ * ReferenceError at eval) abort the *entire* CLI load — even `parachute --help`
+ * — because top-level import evaluation runs before `run()`'s try/catch is ever
+ * reached. Loading each module lazily inside its switch arm (the same pattern
+ * the expose subcommands already use, e.g. `await import("./commands/expose-
+ * cloudflare.ts")`) means an import rejection touches only its own command.
+ *
+ * On rejection we print `parachute <cmd>: failed to load (<err>)` and return
+ * `undefined`; the arm turns that into exit code 1. This keeps a broken module
+ * from surfacing as an unhandled promise rejection (which the top-level
+ * `run()` boundary doesn't shape — it wraps execution, not import).
+ */
+async function loadCommand<T>(cmd: string, importer: () => Promise<T>): Promise<T | undefined> {
+  try {
+    return await importer();
+  } catch (err) {
+    console.error(
+      `parachute ${cmd}: failed to load (${err instanceof Error ? err.message : String(err)})`,
+    );
+    return undefined;
+  }
+}
+
 async function main(argv: string[]): Promise<number> {
   const [command, ...rest] = argv;
 
@@ -309,7 +334,9 @@ async function main(argv: string[]): Promise<number> {
       const setupOpts: Parameters<typeof setup>[0] = {};
       if (tagExtract.tag) setupOpts.tag = tagExtract.tag;
       if (noStart) setupOpts.noStart = true;
-      return await setup(setupOpts);
+      const mod = await loadCommand("setup", () => import("./commands/setup.ts"));
+      if (!mod) return 1;
+      return await mod.setup(setupOpts);
     }
 
     case "setup-wizard": {
@@ -323,7 +350,9 @@ async function main(argv: string[]): Promise<number> {
         console.log(setupWizardHelp());
         return 0;
       }
-      return await runSetupWizardCommand(rest);
+      const mod = await loadCommand("setup-wizard", () => import("./commands/wizard.ts"));
+      if (!mod) return 1;
+      return await mod.runSetupWizardCommand(rest);
     }
 
     case "init": {
@@ -379,7 +408,9 @@ async function main(argv: string[]): Promise<number> {
       }
       if (cliWizard) initOpts.wizardChoice = "cli";
       else if (browserWizard) initOpts.wizardChoice = "browser";
-      return await init(initOpts);
+      const mod = await loadCommand("init", () => import("./commands/init.ts"));
+      if (!mod) return 1;
+      return await mod.init(initOpts);
     }
 
     case "install": {
@@ -438,16 +469,18 @@ async function main(argv: string[]): Promise<number> {
       if (noStart) installOpts.noStart = true;
       if (providerExtract.value) installOpts.scribeProvider = providerExtract.value;
       if (keyExtract.value) installOpts.scribeKey = keyExtract.value;
+      const mod = await loadCommand("install", () => import("./commands/install.ts"));
+      if (!mod) return 1;
       if (service === "all") {
         // Bootstrap the whole ecosystem to one dist-tag — the RC-testing payload.
         // Bail on first failure so a broken channel doesn't mask a working tag.
         for (const svc of knownServices()) {
-          const code = await install(svc, installOpts);
+          const code = await mod.install(svc, installOpts);
           if (code !== 0) return code;
         }
         return 0;
       }
-      return await install(service, installOpts);
+      return await mod.install(service, installOpts);
     }
 
     case "status":
@@ -459,7 +492,11 @@ async function main(argv: string[]): Promise<number> {
       // 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: {} });
+      {
+        const mod = await loadCommand("status", () => import("./commands/status.ts"));
+        if (!mod) return 1;
+        return await mod.status({ supervisor: {} });
+      }
 
     case "expose": {
       const hubExtract = extractHubOrigin(rest);
@@ -585,6 +622,14 @@ async function main(argv: string[]): Promise<number> {
         ...(hubExtract.hubOrigin ? { hubOrigin: hubExtract.hubOrigin } : {}),
       };
 
+      // Lazy-load the Tailscale-Funnel entry points the same way the Cloudflare /
+      // interactive / auto-pick paths above load theirs. Reaching here means we're
+      // past the early Cloudflare returns, so `exposePublic` / `exposeTailnet` are
+      // about to be needed by one of the branches below.
+      const exposeMod = await loadCommand("expose", () => import("./commands/expose.ts"));
+      if (!exposeMod) return 1;
+      const { exposePublic, exposeTailnet } = exposeMod;
+
       // `--tailnet` is the explicit Tailscale Funnel pin — bypass both the
       // interactive picker and the non-TTY auto-pick. Goes straight to
       // exposePublic so today's Funnel flow keeps working unchanged.
@@ -677,7 +722,9 @@ async function main(argv: string[]): Promise<number> {
         migrateOffer: { enabled: true },
         ...(hubExtract.hubOrigin ? { hubOrigin: hubExtract.hubOrigin } : {}),
       };
-      return await start(hubExtract.rest[0], startOpts);
+      const mod = await loadCommand("start", () => import("./commands/lifecycle.ts"));
+      if (!mod) return 1;
+      return await mod.start(hubExtract.rest[0], startOpts);
     }
 
     case "stop": {
@@ -685,7 +732,9 @@ async function main(argv: string[]): Promise<number> {
         console.log(stopHelp());
         return 0;
       }
-      return await stop(rest[0], { supervisor: {}, migrateOffer: { enabled: true } });
+      const mod = await loadCommand("stop", () => import("./commands/lifecycle.ts"));
+      if (!mod) return 1;
+      return await mod.stop(rest[0], { supervisor: {}, migrateOffer: { enabled: true } });
     }
 
     case "restart": {
@@ -693,7 +742,9 @@ async function main(argv: string[]): Promise<number> {
         console.log(restartHelp());
         return 0;
       }
-      return await restart(rest[0], { supervisor: {}, migrateOffer: { enabled: true } });
+      const mod = await loadCommand("restart", () => import("./commands/lifecycle.ts"));
+      if (!mod) return 1;
+      return await mod.restart(rest[0], { supervisor: {}, migrateOffer: { enabled: true } });
     }
 
     case "upgrade": {
@@ -744,7 +795,9 @@ async function main(argv: string[]): Promise<number> {
         upgradeOpts.channel = channelExtract.value;
       }
       if (allowDowngrade) upgradeOpts.allowDowngrade = true;
-      return await upgrade(remaining[0], upgradeOpts);
+      const mod = await loadCommand("upgrade", () => import("./commands/upgrade.ts"));
+      if (!mod) return 1;
+      return await mod.upgrade(remaining[0], upgradeOpts);
     }
 
     case "logs": {
@@ -759,7 +812,9 @@ async function main(argv: string[]): Promise<number> {
         return 1;
       }
       const follow = rest.includes("-f") || rest.includes("--follow");
-      return await logs(svc, { follow });
+      const mod = await loadCommand("logs", () => import("./commands/lifecycle.ts"));
+      if (!mod) return 1;
+      return await mod.logs(svc, { follow });
     }
 
     case "migrate": {
@@ -775,7 +830,31 @@ async function main(argv: string[]): Promise<number> {
           console.error("usage: parachute migrate --teardown");
           return 1;
         }
-        teardownHubUnit();
+        const mod = await loadCommand("migrate", () => import("./commands/migrate-cutover.ts"));
+        if (!mod) return 1;
+        // teardownHubUnit logs the human-facing lines itself (the success
+        // guidance, or "nothing to tear down"). hub#534: the CLI must still
+        // own the EXIT CODE + surface any failure detail the function's
+        // false-branch doesn't print — pre-fix it ignored `removed` + `messages`
+        // and always exited 0, so a non-removal looked like success to a script.
+        const result = mod.teardownHubUnit();
+        if (result.removed) return 0;
+        // removed === false: either a clean no-op (nothing was installed —
+        // `messages` empty) or a real failure (the removal carried a reason in
+        // `messages` the internal log didn't surface). The no-op is informational
+        // (exit 0); a failure with detail is an error (print it, exit 1).
+        //
+        // DELIBERATE double-print on the failure path (not a bug): the function's
+        // own log() already wrote a human-readable summary ("Hub-unit teardown did
+        // not complete: …") to STDOUT; here we re-emit the raw reason(s) to STDERR.
+        // The split is intentional — a person reading the terminal sees the framed
+        // summary, while a script that captures `2>` gets the machine-parseable
+        // reason alongside the non-zero exit. Mirrors the streams convention the
+        // rest of the CLI uses (human guidance on stdout, error detail on stderr).
+        if (result.messages.length > 0) {
+          for (const line of result.messages) console.error(line);
+          return 1;
+        }
         return 0;
       }
       // §7.1 detached→supervised cutover. Opt-in surface (the archive sweep
@@ -788,7 +867,9 @@ async function main(argv: string[]): Promise<number> {
           console.error("usage: parachute migrate --to-supervised");
           return 1;
         }
-        const result = await cutoverToSupervised();
+        const mod = await loadCommand("migrate", () => import("./commands/migrate-cutover.ts"));
+        if (!mod) return 1;
+        const result = await mod.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.
@@ -807,7 +888,9 @@ async function main(argv: string[]): Promise<number> {
         );
         return 1;
       }
-      return await migrate({ dryRun, list, yes });
+      const mod = await loadCommand("migrate", () => import("./commands/migrate.ts"));
+      if (!mod) return 1;
+      return await mod.migrate({ dryRun, list, yes });
     }
 
     case "serve": {
@@ -824,7 +907,9 @@ async function main(argv: string[]): Promise<number> {
       // event loop alive until SIGINT/SIGTERM, at which point we stop the
       // server cleanly and exit. Container supervisor (tini, Render, Docker)
       // reaps us once the event loop drains.
-      const { stop: stopServer } = await serve();
+      const mod = await loadCommand("serve", () => import("./commands/serve.ts"));
+      if (!mod) return 1;
+      const { stop: stopServer } = await mod.serve();
       await new Promise<void>((resolve) => {
         const handler = async () => {
           await stopServer();
@@ -836,14 +921,19 @@ async function main(argv: string[]): Promise<number> {
       return 0;
     }
 
-    case "auth":
-      return await auth(rest);
+    case "auth": {
+      const mod = await loadCommand("auth", () => import("./commands/auth.ts"));
+      if (!mod) return 1;
+      return await mod.auth(rest);
+    }
 
     case "vault": {
+      const mod = await loadCommand("vault", () => import("./commands/vault.ts"));
+      if (!mod) return 1;
       // `parachute vault` with no args forwards --help to parachute-vault so
       // users see the actual vault surface, not a CLI-side stub. Anything
       // after `vault` (including --help) is passed through verbatim.
-      if (rest.length === 0) return await dispatchVault(["--help"]);
+      if (rest.length === 0) return await mod.dispatchVault(["--help"]);
 
       // Everything under `vault` forwards transparently to `parachute-vault`.
       // `vault tokens create` used to route through a guided interactive
@@ -852,7 +942,7 @@ async function main(argv: string[]): Promise<number> {
       // hub-issued JWTs; mint them with `parachute auth mint-token` or the
       // admin SPA Connect card. We forward verbatim so the operator sees
       // vault's own migration error rather than a hub-side stub.
-      return await dispatchVault(rest);
+      return await mod.dispatchVault(rest);
     }
 
     default:

package/src/commands/expose-2fa-warning.ts

@@ -6,12 +6,15 @@
  * is the second wall.
  *
  * 2FA at the hub login layer is real as of hub#473: "password +
- * something-you-have." This warning recommends `parachute auth 2fa enroll`
- * (which now gates hub `/login` for real) when the operator hasn't enrolled.
+ * something-you-have." This prints a STRONG RECOMMENDATION to enroll — via the
+ * browser at `/account/2fa` or `parachute auth 2fa enroll` (which now gates hub
+ * `/login` for real) — when the operator hasn't enrolled.
  *
- * Why this is a warning, not a hard gate: hard-gating would surprise operators
- * mid-flow — they ran `parachute expose public` to expose, not to be told
- * "set up 2FA first." A loud, contextual warning + a clear remediation is the
+ * Why this is a recommendation, not a hard gate (Aaron's explicit call, 2026-06:
+ * "I don't think we need to require 2FA for public expose but we should strongly
+ * recommend it"): hard-gating would surprise operators mid-flow — they ran
+ * `parachute expose public` to expose, not to be told "set up 2FA first." A
+ * clear, friendly, contextual recommendation + an obvious remediation is the
  * right shape; the operator decides whether to act now or later. The tunnel is
  * up regardless.
  *
@@ -68,16 +71,17 @@ export function printPublic2FAWarning(opts: Public2FAWarningOpts): boolean {
     return false;
   }
   log("");
-  log("⚠ /login is now reachable on the public internet");
-  log(`  (${opts.publicUrl}/login). Anyone who guesses your password is in.`);
+  log("→ Strongly recommended: turn on two-factor authentication.");
+  log("  Your login page is now reachable from the public internet");
+  log(`  (${opts.publicUrl}/login) — anyone online can reach it, so your`);
+  log("  password is the only wall. A second factor (a one-time code from");
+  log("  your authenticator app) materially raises the bar:");
   log("");
-  log("  Turn on two-factor authentication — it adds a second wall (a one-time");
-  log("  code from your authenticator app) on top of your password:");
+  log(`    ${opts.publicUrl}/account/2fa     # scan a QR code in your browser`);
+  log("    parachute auth 2fa enroll         # or enroll from the terminal");
   log("");
-  log("    parachute auth 2fa enroll");
-  log("");
-  log("  (Or set it up in the browser at /account/2fa for a scannable QR code.)");
-  log("  Either way, also make sure your owner password is a strong one:");
+  log("  It's a recommendation, not a requirement — your hub is up either way.");
+  log("  While you're at it, make sure your owner password is a strong one:");
   log("");
   log("    parachute auth set-password");
   return true;

package/src/commands/migrate-cutover.ts

@@ -86,6 +86,7 @@ import { type PortListeningFn, defaultPortListening } from "../port-probe.ts";
 import { type AliveFn, clearPid, readPid } from "../process-state.ts";
 import { shortNameForManifest } from "../service-spec.ts";
 import { type ServiceEntry, readManifestLenient } from "../services-manifest.ts";
+import { enrichedUnitPath } from "../spawn-path.ts";
 import {
   type DisableStaleModuleUnitsOpts,
   type DisableStaleModuleUnitsResult,
@@ -232,14 +233,14 @@ export interface WriteUnitResult {
  * and `installManagedUnit(start:false)` — daemon-reload / write-the-plist but
  * NEVER enable --now / bootstrap. The §7.1 step-2 race-avoider.
  */
-function defaultUnitPath(bunInstall: string): string {
-  return `${bunInstall}/bin:/usr/local/bin:/usr/bin:/bin`;
-}
-
 export function defaultWriteUnitWithoutStarting(opts: WriteUnitOpts): WriteUnitResult {
   const { deps } = opts;
   const bunInstall = `${deps.homeDir()}/.bun`;
-  const path = defaultUnitPath(bunInstall);
+  // Shared with the init-bringup path (hub-unit.ts) so the two unit-generation
+  // sites can't drift — enriches the unit PATH with operator-tool dirs
+  // (`$HOME/.local/bin`, brew bin) so a migrated launchd/systemd hub can find
+  // scribe's `parakeet-mlx` + `ffmpeg`. See `spawn-path.ts`.
+  const path = enrichedUnitPath(bunInstall, deps.homeDir(), deps.platform);
   const logPath = `${opts.parachuteHome}/hub/logs/hub.log`;
   let unit: ManagedUnit;
   try {
@@ -878,6 +879,12 @@ export function teardownHubUnit(opts: TeardownOpts = {}): { removed: boolean; me
     log("The supervised hub unit is gone. To run the hub now, either:");
     log("  - `parachute serve` (foreground), or");
     log("  - `parachute migrate --to-supervised` to reinstall the unit.");
+  } else if (res.messages.length > 0) {
+    // removed === false WITH detail: a real removal failure, not a clean
+    // no-op. Surface the reason rather than the misleading "nothing was
+    // installed" line (hub#534 — the CLI also maps this to a non-zero exit).
+    log("Hub-unit teardown did not complete:");
+    for (const m of res.messages) log(`  ${m}`);
   } else {
     log("No hub unit was installed — nothing to tear down.");
   }

package/src/commands/serve-boot.ts

@@ -27,6 +27,7 @@ import {
   shortNameForManifest,
 } from "../service-spec.ts";
 import { type ServiceEntry, readManifestLenient } from "../services-manifest.ts";
+import { enrichedPath } from "../spawn-path.ts";
 import type { Supervisor } from "../supervisor.ts";
 
 export interface BootOpts {
@@ -75,9 +76,14 @@ export interface BuildSpawnRequestOpts {
  * 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).
+ *      (hub#356/#357). This is authoritative and is NOT overridable by a
+ *      `.env` `PORT` (see below) — services.json is the single source of truth
+ *      for the port (scribe#41 4-tier ladder; hub#206).
  *   2. per-service `.env` at `<configDir>/<short>/.env` — operator-configured
- *      values (e.g. scribe provider keys) override the bare PORT.
+ *      values (e.g. scribe provider keys) merge on top. A `PORT` key here is
+ *      dropped: a stale pre-#206 `.env` `PORT` must not shadow `entry.port`
+ *      (hub#537 — a leftover scribe `PORT=1944` ≠ services.json `1943` leaked
+ *      into the injected PORT and broke the supervisor's readiness probe).
  *   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.
@@ -93,7 +99,31 @@ export function buildModuleSpawnRequest(
   opts: BuildSpawnRequestOpts,
 ): SpawnReqShape {
   const fileEnv = readEnvFileValues(join(opts.configDir, short, ".env"));
-  const env: Record<string, string> = { PORT: String(entry.port), ...fileEnv };
+  // Drop a `PORT` from the per-service .env: services.json `entry.port` is the
+  // canonical port and must win (scribe#41 ladder; hub#206). A stale pre-#206
+  // `.env` PORT (e.g. scribe's `1944` vs services.json `1943`) would otherwise
+  // leak into the injected PORT and the supervisor's readiness probe would
+  // check the wrong port → false `started_but_unbound` (hub#537). The module's
+  // own resolvePort ladder already prefers services.json, so this keeps the
+  // injected PORT + probe in agreement with what the child actually binds.
+  const { PORT: _staleEnvPort, ...fileEnvSansPort } = fileEnv;
+  // PATH enrichment (hub launchd-PATH regression): the hub unit bakes a minimal
+  // PATH and `Bun.spawn` defaults to empty env, so without this the child only
+  // ever sees the unit's PATH — which omits `$HOME/.local/bin` (scribe's
+  // `parakeet-mlx`) + the Homebrew bin (`ffmpeg`), killing transcription on
+  // canonical installs. `enrichedPath` appends those dirs (when they exist) to
+  // the inherited PATH; inherited entries keep their order. A per-service `.env`
+  // PATH (operator intent) still wins via the spread below. See `spawn-path.ts`.
+  // The API-start path builds its own env — see `api-modules-ops.ts`
+  // `spawnSupervised`, which calls `enrichedPath()` too (keep the two in sync).
+  // `process.env.PATH` may ALREADY be enriched by serve startup (serve.ts);
+  // re-enriching here is a harmless no-op — `enrichedPath` is idempotent
+  // (dedupe + append-only), so double-enrichment can't duplicate or reorder.
+  const env: Record<string, string> = {
+    PATH: enrichedPath(),
+    PORT: String(entry.port),
+    ...fileEnvSansPort,
+  };
   if (opts.hubOrigin) env[HUB_ORIGIN_ENV] = opts.hubOrigin;
   if (opts.extraEnv) Object.assign(env, opts.extraEnv);