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

package/src/api-hub-upgrade.ts

@@ -67,6 +67,34 @@ export const HUB_UPGRADE_REQUIRED_SCOPE = "parachute:host:admin";
  */
 const IN_FLIGHT_PHASES = new Set<HubUpgradeStatus["phase"]>(["pending", "running", "restarting"]);
 
+/**
+ * #506: TTL for the 409 in-flight guard. The status file is single-slot, and a
+ * helper that CRASHES (OOM, killed mid-rewrite, host reboot) never reaches a
+ * terminal phase — leaving the slot stuck in `pending`/`running`/`restarting`
+ * FOREVER and 409-deadlocking every future upgrade. So: an in-flight slot whose
+ * `started_at` is older than this bound is treated as ABANDONED and the new
+ * request proceeds (overwriting the stale slot).
+ *
+ * 15 minutes — comfortably past the longest expected in-place upgrade (an
+ * `npm view` + `bun add -g` rewrite + restart is seconds-to-low-minutes even on
+ * a slow box / cold cache). A live upgrade finishing under the bound is never
+ * mistaken for abandoned; a crashed one frees the slot within 15 min instead of
+ * never. (A missing/garbage `started_at` is treated as stale → not 409, so a
+ * malformed file can't deadlock either.)
+ */
+const IN_FLIGHT_TTL_MS = 15 * 60 * 1000;
+
+/**
+ * Is an in-flight slot still FRESH (within the TTL), so a second POST must be
+ * rejected 409? An unparseable / missing `started_at` is treated as stale
+ * (not fresh) so a malformed file frees the slot rather than deadlocking it.
+ */
+function isInFlightFresh(existing: HubUpgradeStatus, now: Date): boolean {
+  const startedMs = Date.parse(existing.started_at);
+  if (Number.isNaN(startedMs)) return false;
+  return now.getTime() - startedMs < IN_FLIGHT_TTL_MS;
+}
+
 export interface SpawnHelperArgs {
   operationId: string;
   channel: "rc" | "latest";
@@ -213,7 +241,9 @@ export async function handleHubUpgrade(req: Request, deps: ApiHubUpgradeDeps): P
   const parsed = await parseBody(req);
   if (parsed instanceof Response) return parsed;
 
-  // ── 409 in-flight guard ────────────────────────────────────────────────────
+  const now = (deps.now ?? (() => new Date()))();
+
+  // ── 409 in-flight guard (TTL-bounded) ──────────────────────────────────────
   // The status file is single-slot (one hub, one upgrade). If a prior upgrade
   // is still in a non-terminal phase (pending/running/restarting), starting a
   // SECOND would overwrite its operation_id — and a still-running first helper
@@ -222,9 +252,15 @@ export async function handleHubUpgrade(req: Request, deps: ApiHubUpgradeDeps): P
   // server-side too (a second tab, a stale page, a scripted POST). Reject with
   // 409 unless the slot is free (no file) or the prior op reached a terminal
   // phase (failed / redeploy-required / succeeded).
+  //
+  // #506: BUT a non-terminal slot is only a real block while it's FRESH. A
+  // helper that crashed (OOM / killed / host reboot) leaves the slot stuck
+  // in-flight forever and would 409-deadlock every future upgrade. So an
+  // in-flight slot older than IN_FLIGHT_TTL_MS is treated as ABANDONED and the
+  // request proceeds (the seeded status below overwrites the stale slot).
   const readStatus = deps.readStatus ?? readHubUpgradeStatus;
   const existing = readStatus(deps.configDir);
-  if (existing && IN_FLIGHT_PHASES.has(existing.phase)) {
+  if (existing && IN_FLIGHT_PHASES.has(existing.phase) && isInFlightFresh(existing, now)) {
     return jsonError(
       409,
       "upgrade_in_flight",
@@ -234,7 +270,6 @@ export async function handleHubUpgrade(req: Request, deps: ApiHubUpgradeDeps): P
 
   const hubSrcDir = deps.hubSrcDir ?? dirname(fileURLToPath(import.meta.url));
   const env = deps.env ?? process.env;
-  const now = (deps.now ?? (() => new Date()))();
 
   const currentVersion = (deps.currentVersion ?? (() => defaultCurrentVersion(hubSrcDir)))();
   // Auto-detect the channel from the current version when not explicitly set —

package/src/api-me.ts

@@ -14,7 +14,12 @@
  * Response shape:
  *
  *   { hasSession: false }
- *   { hasSession: true, user: { id, displayName }, csrf: "<token>" }
+ *   { hasSession: true, user: { id, displayName }, csrf: "<token>",
+ *     two_factor_enabled: boolean }
+ *
+ * `two_factor_enabled` (hub#85) lets the SPA's "My account" page render the
+ * 2FA status without a separate read. It reflects `users.totp_secret` being
+ * set for the signed-in user.
  *
  * `displayName` is the user's `username` today — there's no separate
  * display-name field on the User shape. Surfaced under a different key
@@ -39,6 +44,7 @@
 import type { Database } from "bun:sqlite";
 import { ensureCsrfToken } from "./csrf.ts";
 import { findActiveSession } from "./sessions.ts";
+import { isTotpEnrolled } from "./two-factor-store.ts";
 import { getUserById } from "./users.ts";
 
 export interface ApiMeDeps {
@@ -59,7 +65,9 @@ interface SignedInUser {
  * that mixes states — e.g. `{ hasSession: false, user: staleUser }`
  * fails at the type-check, not just at code-review.
  */
-type ApiMeResponse = { hasSession: false } | { hasSession: true; user: SignedInUser; csrf: string };
+type ApiMeResponse =
+  | { hasSession: false }
+  | { hasSession: true; user: SignedInUser; csrf: string; two_factor_enabled: boolean };
 
 export function handleApiMe(req: Request, deps: ApiMeDeps): Response {
   if (req.method !== "GET") {
@@ -99,6 +107,7 @@ export function handleApiMe(req: Request, deps: ApiMeDeps): Response {
       displayName: user.username,
     },
     csrf: csrf.token,
+    two_factor_enabled: isTotpEnrolled(deps.db, user.id),
   };
   return new Response(JSON.stringify(body), { status: 200, headers });
 }

package/src/api-modules.ts

@@ -42,6 +42,9 @@
  */
 
 import type { Database } from "bun:sqlite";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { compareVersions } from "./commands/upgrade.ts";
 import { validateHostAdminToken } from "./host-admin-token-validation.ts";
 import {
   type ModuleInstallChannel,
@@ -178,6 +181,40 @@ export interface ApiModulesDeps {
    * (hub#342 — drives the admin SPA Modules page's "Open" button).
    */
   readModuleManifest?: (installDir: string) => Promise<ModuleManifest | null>;
+  /**
+   * Read the LIVE installed version of a module from its install dir's
+   * `package.json` `version` (hub#243). The services.json `version` field is a
+   * CACHE the module writes on its own boot — on the bun-linked dev path it
+   * goes stale the moment the checkout is rebuilt to a newer version without a
+   * restart that re-stamps services.json. The admin Modules view reads
+   * `installed_version` straight from that cache, so it can show a stale version
+   * (the live symptom: services.json said 0.5.4-rc.15 while the linked checkout
+   * was already 0.6.4-rc.15). When this resolves a version, it WINS over the
+   * services.json cache for the `installed_version` field so the operator sees
+   * what's actually on disk. Returns null on any failure (no install dir,
+   * missing/unreadable package.json, no version) → fall back to the
+   * services.json cache, which is the only source for a not-yet-booted module.
+   *
+   * Production reads `<installDir>/package.json`; tests inject a fake.
+   */
+  readInstalledVersion?: (installDir: string) => string | null;
+}
+
+/**
+ * Default `readInstalledVersion`. Reads `<installDir>/package.json`'s `version`
+ * — the authoritative live version of a module's code on disk, which the
+ * bun-linked dev path keeps current while the services.json cache can lag
+ * (hub#243). Returns null on any failure so the caller falls back to the
+ * services.json `version`.
+ */
+export function defaultReadInstalledVersion(installDir: string): string | null {
+  try {
+    const raw = readFileSync(join(installDir, "package.json"), "utf8");
+    const parsed = JSON.parse(raw) as { version?: unknown };
+    return typeof parsed.version === "string" && parsed.version.length > 0 ? parsed.version : null;
+  } catch {
+    return null;
+  }
 }
 
 /**
@@ -239,6 +276,24 @@ interface ModuleWireShape {
   installed: boolean;
   installed_version: string | null;
   latest_version: string | null;
+  /**
+   * Whether the channel-resolved `latest_version` is a REAL upgrade — i.e.
+   * STRICTLY NEWER than `installed_version` under semver ordering (hub#243).
+   * Computed server-side via `compareVersions` so the rc/prerelease ordering is
+   * correct and there's ONE tested source of truth (the SPA used to derive this
+   * client-side with a string `!==`, which framed a *downgrade* as an upgrade:
+   * an rc operator on `0.6.4-rc.15` was offered an "upgrade" to the older
+   * `@latest` `0.6.3` purely because the two strings differed).
+   *
+   * `false` when: not installed · no `latest_version` (probe failed) · target ≤
+   * installed (same or older — incl. the rc→older-stable downgrade) · either
+   * version is unparseable (`compareVersions` returns null → fail-closed: don't
+   * offer a move we can't verify is forward). `true` ONLY when the target
+   * parses AND sorts strictly above installed — so `0.6.4-rc.15` → stable
+   * `0.6.4` IS an upgrade (stable > its own rc per semver §11.4.3), but
+   * `0.6.4-rc.15` → `0.6.3` is NOT.
+   */
+  upgrade_available: boolean;
   supervisor_status: ModuleState["status"] | null;
   pid: number | null;
   /**
@@ -451,6 +506,8 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
   // Lenient read so a single bad row written by a buggy module install
   // (e.g. app@0.2.0-rc.4) doesn't take down /api/modules — see hub#406.
   const manifest = readManifestLenient(deps.manifestPath);
+  // Live on-disk version reader (hub#243) — see `defaultReadInstalledVersion`.
+  const readInstalledVersion = deps.readInstalledVersion ?? defaultReadInstalledVersion;
   const installedByShort = new Map<
     string,
     {
@@ -476,6 +533,18 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       uis?: Record<string, UiSubUnit>;
       mountPath?: string;
     } = { version: entry.version };
+    // Prefer the LIVE on-disk version over the services.json cache when we can
+    // read it (hub#243). `entry.version` is a cache the module stamps on its own
+    // boot; on the bun-linked dev path it lags after a rebuild-without-restart,
+    // so the admin view shows a stale "current" (the live symptom: cache said
+    // 0.5.4-rc.15 while the linked checkout was already 0.6.4-rc.15). The
+    // module's `<installDir>/package.json` `version` is authoritative for the
+    // code actually on disk. Falls back to the cache when there's no installDir
+    // or the package.json can't be read (e.g. a not-yet-booted seed row).
+    if (entry.installDir !== undefined) {
+      const live = readInstalledVersion(entry.installDir);
+      if (live !== null) value.version = live;
+    }
     if (entry.installDir !== undefined) value.installDir = entry.installDir;
     if (entry.uis !== undefined) value.uis = entry.uis;
     // First non-`.parachute` path is the module's user-facing mount
@@ -622,6 +691,10 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
       installed: installed !== undefined,
       installed_version: installed?.version ?? null,
       latest_version: latestByShort.get(short) ?? null,
+      upgrade_available: isUpgradeAvailable(
+        installed?.version ?? null,
+        latestByShort.get(short) ?? null,
+      ),
       supervisor_status: state?.status ?? null,
       pid: state?.pid ?? null,
       supervisor_start_error: state?.startError ?? null,
@@ -644,6 +717,9 @@ export async function handleApiModules(req: Request, deps: ApiModulesDeps): Prom
 
   // Every supervised module's run-state — curated AND non-curated (hub#539).
   // Built from the same supervisor.list() snapshot already in `stateByShort`.
+  // `installed_version` here inherits the live-on-disk override already applied
+  // to `installedByShort[].version` in the manifest loop above (hub#243), so the
+  // `supervised` array reports the same corrected version as the `modules` rows.
   const supervised: SupervisedSnapshotWire[] = Array.from(stateByShort.values()).map((s) => ({
     short: s.short,
     installed: installedByShort.has(s.short),
@@ -842,6 +918,35 @@ function toUisWireShape(uis: Record<string, UiSubUnit> | undefined): UiSubUnitWi
   }));
 }
 
+/**
+ * Whether `latest` is a REAL upgrade over `installed` — strictly newer under
+ * semver ordering (hub#243). The single tested source of truth for the
+ * "upgrade available?" decision, shared by the wire shape's `upgrade_available`
+ * field and (transitively) the admin SPA's Upgrade button.
+ *
+ * Returns `false` unless BOTH versions parse AND `latest` sorts strictly above
+ * `installed`:
+ *   - no installed version (not installed) → false.
+ *   - no latest version (probe failed / unknown package) → false.
+ *   - `compareVersions` can't parse either side → false (FAIL-CLOSED: never
+ *     offer a move we can't prove is forward).
+ *   - target ≤ installed → false. This is the load-bearing downgrade guard:
+ *     an rc operator on `0.6.4-rc.15` whose channel resolves `latest_version`
+ *     to the OLDER `@latest` `0.6.3` is NOT offered an "upgrade" (the live bug
+ *     — a downgrade framed as an upgrade by the old string `!==`).
+ *
+ * Reuses `commands/upgrade.ts:compareVersions`, the same comparator the CLI
+ * `parachute upgrade` downgrade guard uses, so the SPA offer and the CLI guard
+ * can't disagree about rc/prerelease ordering. Note `0.6.4-rc.15` → stable
+ * `0.6.4` IS strictly-newer (stable > its own rc per semver §11.4.3), so a real
+ * rc→its-stable promotion still surfaces as an upgrade.
+ */
+export function isUpgradeAvailable(installed: string | null, latest: string | null): boolean {
+  if (installed === null || latest === null) return false;
+  const cmp = compareVersions(latest, installed);
+  return cmp !== null && cmp > 0;
+}
+
 /**
  * Reset the in-memory `latest_version` cache. Tests call this between
  * runs to prevent state leakage across test cases; production never

package/src/api-settings-root-redirect.ts

@@ -0,0 +1,188 @@
+/**
+ * `GET|PUT /api/settings/root-redirect` — operator-settable target for the
+ * bare-`/` 302.
+ *
+ * The hub's root (`/`) redirects to `/admin` by default. This endpoint lets an
+ * operator point it at a surface instead (e.g. a custom-domain hub fronting a
+ * team reading-room surface) without redeploying. The stored value resolves
+ * tier-1 in `resolveRootRedirect` (hub-settings.ts):
+ *
+ *   1. hub_settings.root_redirect (this endpoint writes here)
+ *   2. PARACHUTE_HUB_ROOT_REDIRECT env
+ *   3. `/admin` default (unchanged behavior)
+ *
+ * The endpoint surfaces both the stored value *and* the resolved value + source
+ * so the SPA can render "current: /surface/x (from env)" while the input shows
+ * the empty stored row — same separation rationale as `/api/settings/hub-origin`.
+ *
+ * OPEN-REDIRECT SAFETY is the highest-stakes part: the resolved value lands in a
+ * `Location:` header, so an off-origin value would be a textbook open redirect.
+ * PUT validation (and the read-time resolver) require a SAME-ORIGIN relative
+ * path via `isSafeRedirectPath` — must start with a single `/`, never `//` /
+ * `/\` / a scheme, no control chars / whitespace, and must not resolve back to
+ * `/` (redirect loop). Anything else is rejected (PUT 400 / resolver fallback to
+ * `/admin`).
+ *
+ * Bearer-gated on `parachute:host:admin`, mirroring `handleApiSettingsHubOrigin`
+ * — same Bearer parsing, scope-check posture, and error vocabulary.
+ */
+
+import type { Database } from "bun:sqlite";
+import {
+  type RootRedirectSource,
+  getRootRedirect,
+  isSafeRedirectPath,
+  resolveRootRedirectDetailed,
+  setRootRedirect,
+} from "./hub-settings.ts";
+import { validateAccessToken } from "./jwt-sign.ts";
+
+/** Scope required on the bearer token to call either endpoint. */
+export const API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE = "parachute:host:admin";
+
+export interface ApiSettingsRootRedirectDeps {
+  db: Database;
+  /** Issuer the bearer token must validate against (the hub's resolved issuer). */
+  issuer: string;
+  /**
+   * Env seam for the resolver's env layer. Defaults to `process.env`. Threaded
+   * so the dispatcher (and tests) can resolve `PARACHUTE_HUB_ROOT_REDIRECT`
+   * deterministically.
+   */
+  env?: NodeJS.ProcessEnv;
+}
+
+interface GetResponseBody {
+  /** Raw stored value from hub_settings.root_redirect, or null. */
+  root_redirect: string | null;
+  /** Resolved target applied to the bare-`/` 302 (precedence-aware, guarded). */
+  resolved: string;
+  /** Which precedence layer the resolved value came from. */
+  source: RootRedirectSource;
+}
+
+interface PutResponseBody {
+  /** Echo of the now-stored value (null if cleared). */
+  root_redirect: string | null;
+}
+
+/**
+ * Validation outcome. The "normalized" branch is what gets passed to
+ * setRootRedirect — string (a safe path) or null (clear the row).
+ */
+type ValidateOutcome = { ok: true; normalized: string | null } | { ok: false; description: string };
+
+/**
+ * Validate the body's `root_redirect` field. Accepts:
+ *   - `null` (or empty string) → clear the stored value, revert to env/default.
+ *   - A safe SAME-ORIGIN relative path per `isSafeRedirectPath`.
+ * Everything else → 400 with an operator-friendly description.
+ */
+export function validateRootRedirect(value: unknown): ValidateOutcome {
+  if (value === null) return { ok: true, normalized: null };
+  if (typeof value !== "string") {
+    return {
+      ok: false,
+      description: `root_redirect must be a string or null (got ${typeof value})`,
+    };
+  }
+  // Empty string is the canonical "clear" shape — store as null (mirrors
+  // setHubOrigin's footgun guard; an empty Location would be meaningless).
+  if (value.length === 0) return { ok: true, normalized: null };
+  if (!isSafeRedirectPath(value)) {
+    return {
+      ok: false,
+      description:
+        "root_redirect must be a same-origin relative path (start with a single `/`, no `//`/`/\\`/scheme, no whitespace, and not `/` itself)",
+    };
+  }
+  return { ok: true, normalized: value };
+}
+
+export async function handleApiSettingsRootRedirect(
+  req: Request,
+  deps: ApiSettingsRootRedirectDeps,
+): Promise<Response> {
+  if (req.method !== "GET" && req.method !== "PUT") {
+    return jsonError(405, "method_not_allowed", "use GET or PUT");
+  }
+
+  // Bearer presence + parsing — identical shape to api-settings-hub-origin
+  // for consistency across hub-internal admin endpoints.
+  const auth = req.headers.get("authorization");
+  if (!auth || !auth.startsWith("Bearer ")) {
+    return jsonError(401, "unauthenticated", "Authorization: Bearer <token> required");
+  }
+  const bearer = auth.slice("Bearer ".length).trim();
+  if (!bearer) {
+    return jsonError(401, "unauthenticated", "empty bearer token");
+  }
+
+  // Bearer validation + scope check.
+  try {
+    const validated = await validateAccessToken(deps.db, bearer, deps.issuer);
+    if (typeof validated.payload.sub !== "string" || validated.payload.sub.length === 0) {
+      return jsonError(401, "unauthenticated", "bearer token has no sub claim");
+    }
+    const scopes =
+      typeof validated.payload.scope === "string"
+        ? validated.payload.scope.split(/\s+/).filter((s) => s.length > 0)
+        : [];
+    if (!scopes.includes(API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE)) {
+      return jsonError(
+        403,
+        "insufficient_scope",
+        `bearer token lacks ${API_SETTINGS_ROOT_REDIRECT_REQUIRED_SCOPE}`,
+      );
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return jsonError(401, "unauthenticated", `bearer token invalid — ${msg}`);
+  }
+
+  if (req.method === "GET") {
+    const resolved = resolveRootRedirectDetailed(deps.db, { env: deps.env });
+    const body: GetResponseBody = {
+      root_redirect: getRootRedirect(deps.db),
+      resolved: resolved.value,
+      source: resolved.source,
+    };
+    return new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }
+
+  // PUT — parse + validate body.
+  let parsed: unknown;
+  try {
+    parsed = await req.json();
+  } catch {
+    return jsonError(400, "invalid_request", "request body must be JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return jsonError(400, "invalid_request", "request body must be a JSON object");
+  }
+  if (!("root_redirect" in parsed)) {
+    return jsonError(400, "invalid_request", "request body must include a `root_redirect` field");
+  }
+  const result = validateRootRedirect((parsed as { root_redirect: unknown }).root_redirect);
+  if (!result.ok) {
+    return jsonError(400, "invalid_root_redirect", result.description);
+  }
+
+  setRootRedirect(deps.db, result.normalized);
+
+  const body: PutResponseBody = { root_redirect: result.normalized };
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function jsonError(status: number, code: string, description: string): Response {
+  return new Response(JSON.stringify({ error: code, error_description: description }), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}

package/src/cli.ts

@@ -22,6 +22,7 @@ import type { setup } from "./commands/setup.ts";
 import type { upgrade } from "./commands/upgrade.ts";
 import { ExposeStateError } from "./expose-state.ts";
 import {
+  doctorHelp,
   exposeHelp,
   initHelp,
   installHelp,
@@ -420,17 +421,37 @@ async function main(argv: string[]): Promise<number> {
         );
         return 1;
       }
-      const noBrowser = channelExtract.rest.includes("--no-browser");
-      const noExposePrompt = channelExtract.rest.includes("--no-expose-prompt");
-      const cliWizard = channelExtract.rest.includes("--cli-wizard");
-      const browserWizard = channelExtract.rest.includes("--browser-wizard");
+      // #478 Part 2: --vault-name <name> creates the first vault in one shot.
+      const vaultNameExtract = extractNamedFlag(channelExtract.rest, "--vault-name");
+      if (vaultNameExtract.error) {
+        console.error(`parachute init: ${vaultNameExtract.error}`);
+        return 1;
+      }
+      let validatedVaultName: string | undefined;
+      if (vaultNameExtract.value !== undefined) {
+        if (vaultNameExtract.value.trim() === "") {
+          console.error("parachute init: --vault-name must not be empty.");
+          return 1;
+        }
+        const { validateVaultName: vvn } = await import("./vault-name.ts");
+        const vr = vvn(vaultNameExtract.value);
+        if (!vr.ok) {
+          console.error(`parachute init: invalid --vault-name: ${vr.error}`);
+          return 1;
+        }
+        validatedVaultName = vr.name;
+      }
+      const noBrowser = vaultNameExtract.rest.includes("--no-browser");
+      const noExposePrompt = vaultNameExtract.rest.includes("--no-expose-prompt");
+      const cliWizard = vaultNameExtract.rest.includes("--cli-wizard");
+      const browserWizard = vaultNameExtract.rest.includes("--browser-wizard");
       const known = new Set([
         "--no-browser",
         "--no-expose-prompt",
         "--cli-wizard",
         "--browser-wizard",
       ]);
-      const unknown = channelExtract.rest.find((a) => !known.has(a));
+      const unknown = vaultNameExtract.rest.find((a) => !known.has(a));
       if (unknown !== undefined) {
         console.error(`parachute init: unknown argument "${unknown}"`);
         console.error(
@@ -438,6 +459,7 @@ async function main(argv: string[]): Promise<number> {
             "                     [--expose none|tailnet|cloudflare]\n" +
             "                     [--channel rc|latest]\n" +
             "                     [--hub-origin <url>]\n" +
+            "                     [--vault-name <name>]\n" +
             "                     [--cli-wizard | --browser-wizard]",
         );
         return 1;
@@ -456,6 +478,7 @@ async function main(argv: string[]): Promise<number> {
       if (channelExtract.value === "rc" || channelExtract.value === "latest") {
         initOpts.channel = channelExtract.value;
       }
+      if (validatedVaultName !== undefined) initOpts.vaultName = validatedVaultName;
       if (cliWizard) initOpts.wizardChoice = "cli";
       else if (browserWizard) initOpts.wizardChoice = "browser";
       const mod = await loadCommand("init", () => import("./commands/init.ts"));
@@ -552,6 +575,34 @@ async function main(argv: string[]): Promise<number> {
         return await mod.status({ supervisor: {} });
       }
 
+    case "doctor": {
+      if (isHelpFlag(rest[0])) {
+        console.log(doctorHelp());
+        return 0;
+      }
+      const json = rest.includes("--json");
+      const fix = rest.includes("--fix");
+      const yes = rest.includes("--yes") || rest.includes("-y");
+      const known = new Set(["--json", "--fix", "--yes", "-y"]);
+      const unknown = rest.find((a) => !known.has(a));
+      if (unknown !== undefined) {
+        console.error(`parachute doctor: unknown argument "${unknown}"`);
+        console.error("usage: parachute doctor [--json] [--fix [--yes]]");
+        return 1;
+      }
+      if (json && fix) {
+        console.error("parachute doctor: --json and --fix are mutually exclusive");
+        return 1;
+      }
+      if (yes && !fix) {
+        console.error("parachute doctor: --yes has no effect without --fix");
+        return 1;
+      }
+      const mod = await loadCommand("doctor", () => import("./commands/doctor.ts"));
+      if (!mod) return 1;
+      return await mod.doctor({ json, fix, yes });
+    }
+
     case "expose": {
       const hubExtract = extractHubOrigin(rest);
       if (hubExtract.error) {