@openparachute/hub 0.6.3 → 0.6.4-rc.10

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": {
@@ -418,11 +449,14 @@ async function main(argv: string[]): Promise<number> {
         return 1;
       }
       const noStart = keyExtract.rest.includes("--no-start");
-      const installArgs = keyExtract.rest.filter((a) => a !== "--no-start");
+      const interactive = keyExtract.rest.includes("--interactive");
+      const installArgs = keyExtract.rest.filter(
+        (a) => a !== "--no-start" && a !== "--interactive",
+      );
       const service = installArgs[0];
       if (!service) {
         console.error(
-          "usage: parachute install <service|all> [--channel rc|latest] [--tag <name>] [--no-start]",
+          "usage: parachute install <service|all> [--channel rc|latest] [--tag <name>] [--no-start] [--interactive]",
         );
         console.error(
           "       parachute install scribe [--scribe-provider <name>] [--scribe-key <key>]",
@@ -436,18 +470,21 @@ async function main(argv: string[]): Promise<number> {
         installOpts.channel = channelExtract.value;
       }
       if (noStart) installOpts.noStart = true;
+      if (interactive) installOpts.interactive = 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 +496,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 +626,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 +726,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 +736,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 +746,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 +799,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 +816,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 +834,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 +871,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 +892,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 +911,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 +925,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 +946,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/cloudflare/detect.ts

@@ -109,7 +109,7 @@ export function cloudflaredInstallHint(
  * artifact (registry recipe is undefined) — the caller then uses the generic
  * pointer. Keeps the arch→suffix mapping in exactly one place (the registry).
  */
-function cloudflaredLinuxDownloadUrl(arch: NodeJS.Architecture): string | undefined {
+export function cloudflaredLinuxDownloadUrl(arch: NodeJS.Architecture): string | undefined {
   const recipe = lookupDep("cloudflared")?.install.linuxBinaryUrl?.(arch);
   if (!recipe) return undefined;
   const urlLine = recipe

package/src/cloudflare/state.ts

@@ -45,6 +45,15 @@ export interface CloudflaredTunnelRecord {
 export interface CloudflaredState {
   version: 2;
   tunnels: Record<string, CloudflaredTunnelRecord>;
+  /**
+   * A hostname the operator typed in the interactive Cloudflare flow that
+   * hasn't been routed yet (hub#567). Persisted as soon as it validates so a
+   * mid-chain failure (cloudflared missing, login, tunnel/DNS error) doesn't
+   * discard it — the next interactive run pre-fills the hostname prompt with
+   * it. Cleared once routing succeeds (the tunnel record then carries the live
+   * hostname). Optional + free-floating from the per-tunnel records.
+   */
+  pendingHostname?: string;
 }
 
 export class CloudflaredStateError extends Error {
@@ -91,11 +100,21 @@ function validate(raw: unknown, path: string): CloudflaredState {
     throw new CloudflaredStateError(`${path}: root must be an object`);
   }
   const r = raw as Record<string, unknown>;
+  // hub#567: an optional top-level `pendingHostname` (a typed-but-not-yet-routed
+  // hostname). Non-string / empty values read as absent so older state files
+  // keep validating.
+  const pendingHostname =
+    typeof r.pendingHostname === "string" && r.pendingHostname.length > 0
+      ? r.pendingHostname
+      : undefined;
+  const withPending = (state: CloudflaredState): CloudflaredState =>
+    pendingHostname ? { ...state, pendingHostname } : state;
+
   if (r.version === 1) {
     // v1 — single record at top level. Migrate by wrapping it under its
     // tunnelName. Disk isn't rewritten until the next write.
     const record = validateRecord(r, path);
-    return { version: 2, tunnels: { [record.tunnelName]: record } };
+    return withPending({ version: 2, tunnels: { [record.tunnelName]: record } });
   }
   if (r.version !== 2) {
     throw new CloudflaredStateError(`${path}: unsupported version ${String(r.version)}`);
@@ -113,7 +132,7 @@ function validate(raw: unknown, path: string): CloudflaredState {
     }
     tunnels[key] = record;
   }
-  return { version: 2, tunnels };
+  return withPending({ version: 2, tunnels });
 }
 
 export function readCloudflaredState(
@@ -161,13 +180,88 @@ export function withTunnelRecord(
   record: CloudflaredTunnelRecord,
 ): CloudflaredState {
   const tunnels = { ...(state?.tunnels ?? {}), [record.tunnelName]: record };
-  return { version: 2, tunnels };
+  // Preserve any pending hostname (hub#567); the caller clears it explicitly
+  // via `clearPendingHostname` once routing fully succeeds.
+  return state?.pendingHostname
+    ? { version: 2, tunnels, pendingHostname: state.pendingHostname }
+    : { version: 2, tunnels };
+}
+
+/**
+ * Pure: set the pending (typed-but-not-routed) hostname on the state (hub#567).
+ * Seeds an empty v2 state when none exists yet.
+ */
+export function withPendingHostname(
+  state: CloudflaredState | undefined,
+  hostname: string,
+): CloudflaredState {
+  return { version: 2, tunnels: state?.tunnels ?? {}, pendingHostname: hostname };
+}
+
+/**
+ * Pure: drop the pending hostname (hub#567). Returns undefined when the result
+ * would carry no tunnels either, so the caller can `clearCloudflaredState`
+ * rather than write an empty file.
+ */
+export function withoutPendingHostname(
+  state: CloudflaredState | undefined,
+): CloudflaredState | undefined {
+  if (!state) return undefined;
+  if (Object.keys(state.tunnels).length === 0) return undefined;
+  return { version: 2, tunnels: state.tunnels };
+}
+
+/**
+ * Read the pending hostname from the on-disk state (hub#567). Returns undefined
+ * when there's no state file or no pending hostname. Swallows read/parse errors
+ * (a corrupt state file must not abort the prompt — we just don't pre-fill).
+ */
+export function readPendingHostname(path: string = CLOUDFLARED_STATE_PATH): string | undefined {
+  try {
+    return readCloudflaredState(path)?.pendingHostname;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Persist a typed-but-not-yet-routed hostname (hub#567), preserving existing
+ * tunnel records. Best-effort: a write failure must not abort the expose flow.
+ */
+export function writePendingHostname(
+  hostname: string,
+  path: string = CLOUDFLARED_STATE_PATH,
+): void {
+  try {
+    const state = readCloudflaredState(path);
+    writeCloudflaredState(withPendingHostname(state, hostname), path);
+  } catch {
+    // Non-fatal — persistence is a convenience, not a correctness requirement.
+  }
+}
+
+/**
+ * Clear the pending hostname once routing succeeds (hub#567). If no tunnel
+ * records remain, removes the state file entirely. Best-effort.
+ */
+export function clearPendingHostname(path: string = CLOUDFLARED_STATE_PATH): void {
+  try {
+    const state = readCloudflaredState(path);
+    if (!state?.pendingHostname) return;
+    const next = withoutPendingHostname(state);
+    if (next) writeCloudflaredState(next, path);
+    else clearCloudflaredState(path);
+  } catch {
+    // Non-fatal.
+  }
 }
 
 /**
- * Pure: drop the named tunnel from state. Returns undefined when the result
- * would be empty so callers can `clearCloudflaredState` instead of writing
- * an empty file.
+ * Pure: drop the named tunnel from state. Returns undefined when NO tunnels AND
+ * no pending hostname remain, so callers can `clearCloudflaredState` instead of
+ * writing an empty file. A pending hostname (hub#567) is carried forward — both
+ * when other tunnels survive and when it's the only thing left — so removing a
+ * tunnel never discards a typed-but-not-routed hostname awaiting retry.
  */
 export function withoutTunnelRecord(
   state: CloudflaredState | undefined,
@@ -175,8 +269,10 @@ export function withoutTunnelRecord(
 ): CloudflaredState | undefined {
   if (!state) return undefined;
   const { [tunnelName]: _dropped, ...rest } = state.tunnels;
-  if (Object.keys(rest).length === 0) return undefined;
-  return { version: 2, tunnels: rest };
+  if (Object.keys(rest).length === 0 && !state.pendingHostname) return undefined;
+  return state.pendingHostname
+    ? { version: 2, tunnels: rest, pendingHostname: state.pendingHostname }
+    : { version: 2, tunnels: rest };
 }
 
 /** All tunnel records, in name-sorted order so output is deterministic. */

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;