@openparachute/hub 0.7.4-rc.6 → 0.7.4-rc.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.4-rc.6",
+  "version": "0.7.4-rc.8",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@node-rs/argon2": "^2.0.2",
-    "@openparachute/depcheck": "0.1.0",
+    "@openparachute/depcheck": "0.1.1",
     "jose": "^6.2.2",
     "otpauth": "^9.5.0",
     "qrcode": "^1.5.4"

package/src/__tests__/init.test.ts

@@ -2218,5 +2218,158 @@ describe("resolveInitChannel (hub#694 bug 2)", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// #478 Part 2 — `parachute init --vault-name <name>` creates the first vault
+// ---------------------------------------------------------------------------
+
+describe("init --vault-name (#478 Part 2)", () => {
+  /** Minimal stub that satisfies every init seam except the ones under test. */
+  function baseOpts(
+    h: Harness,
+    overrides: Parameters<typeof init>[0] = {},
+  ): Parameters<typeof init>[0] {
+    return {
+      configDir: h.configDir,
+      manifestPath: h.manifestPath,
+      log: () => {},
+      alive: () => false,
+      ensureHubVersion: async () => ({
+        outcome: "match" as const,
+        installedVersion: "test",
+        messages: [],
+      }),
+      ensureHub: async () => {
+        writeHubPort(1939, h.configDir);
+        return { pid: 0, port: 1939, started: true };
+      },
+      readExposeStateFn: () => undefined,
+      isTty: false,
+      platform: "linux" as const,
+      installVaultModuleImpl: noopVaultInstall,
+      noBrowser: true,
+      noExposePrompt: true,
+      noWizardPrompt: true,
+      ...overrides,
+    };
+  }
+
+  test("(a) with vaultName set: invokes createFirstVaultImpl with the name", async () => {
+    const h = makeHarness();
+    try {
+      const createCalls: string[] = [];
+      const logs: string[] = [];
+      const code = await init(
+        baseOpts(h, {
+          vaultName: "myvault",
+          log: (l) => logs.push(l),
+          createFirstVaultImpl: async (name) => {
+            createCalls.push(name);
+            return 0;
+          },
+        }),
+      );
+      expect(code).toBe(0);
+      expect(createCalls).toEqual(["myvault"]);
+      expect(logs.join("\n")).toContain('Creating vault "myvault"');
+      expect(logs.join("\n")).toContain('Vault "myvault" created');
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("(b) without vaultName: does NOT invoke createFirstVaultImpl", async () => {
+    const h = makeHarness();
+    try {
+      let createCalled = false;
+      const code = await init(
+        baseOpts(h, {
+          // no vaultName set
+          createFirstVaultImpl: async () => {
+            createCalled = true;
+            return 0;
+          },
+        }),
+      );
+      expect(code).toBe(0);
+      expect(createCalled).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("(c) invalid vault name via the CLI seam: validateVaultName rejects it", () => {
+    // The CLI validates before calling init; test the validator directly
+    // so the unit test doesn't need to drive argv parsing. The validator
+    // is the same one the CLI uses (imported in cli.ts).
+    const { validateVaultName } = require("../vault-name.ts");
+    const result = validateVaultName("My Vault!");
+    expect(result.ok).toBe(false);
+    expect(result.error).toMatch(/lowercase alphanumeric/);
+  });
+
+  test("(d) a seeded services.json vault MODULE row does NOT suppress the create", async () => {
+    // REGRESSION (the rc.7 verification bug): Step 0.5's `install("vault",
+    // { noCreate: true })` seeds a `parachute-vault` services.json row via
+    // `spec.seedEntry` on EVERY fresh install. The OLD Step 1.6 keyed
+    // idempotency off that row, so on the exact fresh-box path this feature
+    // targets it saw the row + silently no-op'd the create — the headline
+    // feature never fired. The row marks "module installed", not "instance
+    // exists". Idempotency must live in `parachute-vault create`'s own exit
+    // (which errors "already exists" on a real re-run), NOT a row precheck.
+    // So: a seeded module row must NOT prevent the create from being attempted.
+    const h = makeHarness();
+    try {
+      // Seed services.json with the module row (as Step 0.5 always does).
+      seedVault(h.manifestPath);
+      const createCalls: string[] = [];
+      const logs: string[] = [];
+      const code = await init(
+        baseOpts(h, {
+          vaultName: "myvault",
+          log: (l) => logs.push(l),
+          createFirstVaultImpl: async (name) => {
+            createCalls.push(name);
+            return 0;
+          },
+        }),
+      );
+      expect(code).toBe(0);
+      // The create WAS attempted despite the seeded module row.
+      expect(createCalls).toEqual(["myvault"]);
+      expect(logs.join("\n")).toContain('Creating vault "myvault"');
+      expect(logs.join("\n")).toContain('Vault "myvault" created');
+      // No "already configured / ignored" no-op message.
+      expect(logs.join("\n")).not.toContain("already configured");
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("non-zero exit from create (e.g. vault already exists): warns but init still exits 0", async () => {
+    // A non-zero exit covers both "vault already exists" (a benign re-run, where
+    // `parachute-vault create` errors + exits 1) and a genuine creation failure.
+    // Either way init is non-fatal — the operator can re-run / check status.
+    const h = makeHarness();
+    try {
+      const logs: string[] = [];
+      const code = await init(
+        baseOpts(h, {
+          vaultName: "myvault",
+          log: (l) => logs.push(l),
+          createFirstVaultImpl: async () => 1,
+        }),
+      );
+      // Init is non-fatal on create failure — operator can retry.
+      expect(code).toBe(0);
+      const joined = logs.join("\n");
+      expect(joined).toContain("exited 1");
+      expect(joined).toContain("may already exist, or creation failed");
+      expect(joined).toContain("parachute vault create myvault");
+    } finally {
+      h.cleanup();
+    }
+  });
+});
+
 // Type alias used only inside this test file for the heuristic test.
 type ExposeChoice = "none" | "tailnet" | "cloudflare";

package/src/__tests__/setup-wizard.test.ts

@@ -3267,7 +3267,7 @@ describe("typed vault name (hub#267)", () => {
     }
   });
 
-  test("vault POST with empty name falls back to 'default' + omits the env override", async () => {
+  test("vault POST with empty name falls back to 'default' + ALWAYS passes PARACHUTE_VAULT_NAME (#478 Part 2)", async () => {
     const db = openHubDb(hubDbPath(h.dir));
     try {
       const user = await createUser(db, "owner", "pw");
@@ -3330,12 +3330,12 @@ describe("typed vault name (hub#267)", () => {
       await new Promise((r) => setTimeout(r, 50));
       const vaultSpawn = spawnRequests.find((s) => s.short === "vault");
       expect(vaultSpawn).toBeDefined();
-      // No PARACHUTE_VAULT_NAME override on the default-name path (vault's
-      // resolveFirstBootVaultName already defaults to "default" when the
-      // env var is absent). PORT is set by the supervisor (hub#356) for
-      // every supervised child regardless — assert the empty-name path
-      // doesn't add PARACHUTE_VAULT_NAME.
-      expect(vaultSpawn?.env?.PARACHUTE_VAULT_NAME).toBeUndefined();
+      // #478 Part 2: wizard ALWAYS passes PARACHUTE_VAULT_NAME so vault's
+      // first-boot knows which vault to create once silent auto-create is
+      // removed. Even for the default name, the env var must be set to
+      // "default" — not omitted. PORT is set by the supervisor (hub#356)
+      // for every supervised child regardless.
+      expect(vaultSpawn?.env?.PARACHUTE_VAULT_NAME).toBe("default");
       expect(vaultSpawn?.env?.PORT).toBe("1940");
     } finally {
       db.close();

package/src/cli.ts

@@ -420,17 +420,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 +458,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 +477,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"));

package/src/commands/init.ts

@@ -52,6 +52,7 @@ import { issueOperatorToken, readOperatorTokenFile } from "../operator-token.ts"
 import { type AliveFn, defaultAlive, processState } from "../process-state.ts";
 import { findService, readManifestLenient } from "../services-manifest.ts";
 import { listUsers } from "../users.ts";
+import { validateVaultName } from "../vault-name.ts";
 import { type InstallOpts, install as defaultInstall } from "./install.ts";
 
 /** The three options the exposure prompt offers — also the `--expose` flag's domain. */
@@ -202,6 +203,44 @@ export interface InitOpts {
    * already known so there's no question to ask).
    */
   noWizardPrompt?: boolean;
+  /**
+   * Vault name to create as part of `parachute init --vault-name <name>`
+   * (#478 Part 2). When set, init creates the first vault via
+   * `createFirstVaultImpl` immediately after Step 1.5 (operator-token
+   * guarantee), before the admin-URL resolution. Validated with
+   * `validateVaultName` in the CLI before reaching here.
+   *
+   * Idempotency lives in `parachute-vault create`, NOT in a services.json
+   * precheck: `create <name>` exits 0 + creates when `<name>` is new, and
+   * exits non-zero ("Vault \"<name>\" already exists.") on a re-run. We
+   * therefore ALWAYS attempt the create when this field is set and treat a
+   * non-zero exit as non-fatal (warn + continue). A services.json
+   * `parachute-vault` row is the MODULE-installed marker (Step 0.5 seeds it
+   * via `spec.seedEntry` on EVERY fresh install), not an instance marker —
+   * keying idempotency off it would silently no-op the create on the exact
+   * fresh-box path this feature targets.
+   *
+   * Without this field (the default), init makes NO vault — the wizard
+   * owns Create/Import/Skip as before. The --no-browser / scripted path
+   * remains vault-free unless --vault-name is explicitly passed.
+   */
+  vaultName?: string;
+  /**
+   * Test seam: injectable impl for the `--vault-name` create step (#478
+   * Part 2). This IS the whole create implementation — tests swap the
+   * entire function for a stub that records the call without touching a
+   * live vault binary. It takes the vault name plus a ctx carrying a
+   * runner shim, and returns an exit code (0 = success).
+   *
+   * The production default (`defaultCreateFirstVault`) uses that runner to
+   * shell out `["parachute-vault", "create", name]`, following the `Runner`
+   * type pattern established across every command that shells out:
+   * `readonly string[] => Promise<number>`.
+   */
+  createFirstVaultImpl?: (
+    name: string,
+    ctx: { runner: (cmd: readonly string[]) => Promise<number> },
+  ) => Promise<number>;
   /**
    * Canonical public hub origin (the OAuth issuer / `iss` claim). Persisted to
    * `hub_settings.hub_origin` BEFORE the hub unit starts + modules spawn, so
@@ -599,6 +638,38 @@ async function defaultFetchBootstrapToken(loopbackUrl: string): Promise<string |
   }
 }
 
+/**
+ * Default runner shim for the `--vault-name` create step (#478 Part 2).
+ * Shells out `parachute-vault create <name>` via Bun.spawn, inheriting
+ * the operator's full env (so PARACHUTE_HOME, PATH, etc. pass through).
+ *
+ * This is the same pattern every other command that shells out uses — a
+ * `Runner` (`readonly string[] => Promise<number>`) so tests can inject a
+ * stub without touching the real vault binary.
+ */
+async function defaultRunner(cmd: readonly string[]): Promise<number> {
+  const proc = Bun.spawn([...cmd], {
+    stdio: ["inherit", "inherit", "inherit"],
+    env: process.env,
+  });
+  return await proc.exited;
+}
+
+/**
+ * Default impl for the `--vault-name` first-vault create step (#478 Part 2).
+ * Invokes `parachute-vault create <name>` via the injectable runner. The
+ * `parachute-vault` binary must already be on PATH (guaranteed by Step 0.5's
+ * vault-module install). Exit code is forwarded directly — callers log the
+ * outcome and continue (a non-zero create doesn't abort init; the operator
+ * can re-run `parachute vault create <name>` or use the wizard to retry).
+ */
+async function defaultCreateFirstVault(
+  name: string,
+  ctx: { runner: (cmd: readonly string[]) => Promise<number> },
+): Promise<number> {
+  return await ctx.runner(["parachute-vault", "create", name]);
+}
+
 /**
  * Prompt for the wizard-choice question (hub#168 Cut 4). Returns the
  * picked option, or `undefined` if the operator quit. Default is
@@ -735,6 +806,7 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   const runCliWizardImpl = opts.runCliWizardImpl ?? defaultRunCliWizard;
   const fetchBootstrapTokenImpl = opts.fetchBootstrapTokenImpl ?? defaultFetchBootstrapToken;
   const setHubOriginImpl = opts.setHubOriginImpl ?? defaultSetHubOrigin;
+  const createFirstVaultImpl = opts.createFirstVaultImpl ?? defaultCreateFirstVault;
 
   log("Parachute init — getting your hub set up.");
   log("");
@@ -885,6 +957,42 @@ export async function init(opts: InitOpts = {}): Promise<number> {
   // to the wizard regardless.
   await guaranteeOperatorToken({ configDir, hubPort, log });
 
+  // Step 1.6 (#478 Part 2): if `--vault-name <name>` was given, create the
+  // first vault now — after the hub is up (Step 1) and the operator token is
+  // guaranteed (Step 1.5). The vault module was installed at Step 0.5, so
+  // `parachute-vault` is on PATH.
+  //
+  // We ALWAYS attempt the create when `--vault-name` is set. Idempotency lives
+  // in `parachute-vault create` itself, NOT in a services.json precheck:
+  //   - `create <name>` exits 0 + creates the vault when `<name>` is new.
+  //   - `create <name>` exits non-zero ("Vault \"<name>\" already exists.") when
+  //     that exact name already exists (a benign re-run).
+  //
+  // We DON'T precheck the services.json `parachute-vault` row: Step 0.5's
+  // `install("vault", { noCreate: true })` seeds that row via `spec.seedEntry`
+  // on EVERY fresh install (the module-installed marker — see install.ts's
+  // InstallOpts doc), so on the exact fresh-box path this feature targets the
+  // row is ALWAYS present and a row-keyed precheck would silently no-op the
+  // create. The row marks "module installed", not "instance exists" — only the
+  // create command's own exit reliably distinguishes the two.
+  //
+  // A non-zero exit is non-fatal: warn + continue. It could mean the vault
+  // already exists (a fine re-run) OR a genuine creation failure — init's
+  // contract is hub up → wizard regardless, so we never abort here. The
+  // operator can check `parachute status` / re-run `parachute vault create`.
+  if (opts.vaultName !== undefined) {
+    log(`Creating vault "${opts.vaultName}"…`);
+    const createCode = await createFirstVaultImpl(opts.vaultName, { runner: defaultRunner });
+    if (createCode === 0) {
+      log(`✓ Vault "${opts.vaultName}" created.`);
+    } else {
+      log(
+        `⚠ \`parachute-vault create ${opts.vaultName}\` exited ${createCode} — the vault may already exist, or creation failed. Check \`parachute status\` / re-run \`parachute vault create ${opts.vaultName}\`.`,
+      );
+    }
+    log("");
+  }
+
   // Step 2: exposure chain. Skipped when already exposed, in non-TTY,
   // or when --no-expose-prompt was passed. `--expose <choice>` jumps
   // straight to the corresponding chain without asking.

package/src/help.ts

@@ -134,6 +134,7 @@ Usage:
                  [--expose none|tailnet|cloudflare]
                  [--channel rc|latest]
                  [--hub-origin <url>]
+                 [--vault-name <name>]
                  [--cli-wizard | --browser-wizard]
 
 What it does:
@@ -178,6 +179,14 @@ Flags:
                             accepting it in one pass. For reverse-proxy /
                             Caddy-direct boxes that bind loopback but are reached
                             over a public HTTPS URL (e.g. https://<ip>.sslip.io).
+  --vault-name <name>       create the first vault in one shot (#478 Part 2).
+                            Runs \`parachute-vault create <name>\` after the hub
+                            is up. Non-fatal on re-run — \`create\` exits
+                            non-zero if the vault already exists, and that's
+                            tolerated. Must be a valid vault name: lowercase
+                            alphanumeric + hyphens/underscores, 2–32 chars.
+                            Without this flag, the wizard owns vault creation
+                            (the default experience is unchanged).
   --cli-wizard              skip the "browser or CLI?" prompt and walk the wizard
                             in this terminal (hub#168 Cut 4)
   --browser-wizard          skip the prompt and open the browser wizard directly
@@ -190,7 +199,9 @@ Examples:
   parachute init --expose tailnet             # CI/scripted: chain straight into Tailscale
   parachute init --no-browser                 # don't shell out to open / xdg-open
   parachute init --cli-wizard                 # walk the wizard in this terminal (hub#168)
-  parachute init --channel rc                  # rc box: install the vault module from @rc
+  parachute init --channel rc                 # rc box: install the vault module from @rc
+  parachute init --vault-name default --no-browser
+                                              # CI/scripted: hub + first vault in one pass
 `;
 }
 

package/src/setup-wizard.ts

@@ -2344,19 +2344,19 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
   if (registry) {
     // hub#267: thread the typed name through `PARACHUTE_VAULT_NAME` so
     // vault's first-boot path (vault#342) names the created vault
-    // accordingly. Skip the env override when the operator left the
-    // field blank — vault's `resolveFirstBootVaultName` defaults to
-    // `default` on absent env vars, so this preserves the prior
-    // behaviour for the empty-input case.
+    // accordingly.
     //
-    // If the operator typed "default" explicitly, treat the same as
-    // blank — vault's first-boot defaults to "default" anyway, so
-    // skipping the env override is correct (the comparison below
-    // catches both blank-trimmed-to-DEFAULT and typed-"default").
-    const spawnEnv: Record<string, string> = {};
-    if (vaultName !== DEFAULT_VAULT_NAME) {
-      spawnEnv.PARACHUTE_VAULT_NAME = vaultName;
-    }
+    // #478 Part 2: ALWAYS set `PARACHUTE_VAULT_NAME`, even when the name
+    // is "default". Once vault removes its silent auto-create-on-missing-env
+    // behavior, vault's first-boot will require the env var to know which
+    // vault to create — a missing `PARACHUTE_VAULT_NAME` will mean "no vault
+    // to create" rather than "create one named default". Passing it
+    // explicitly for every path (including the default) is correct and safe:
+    // vault's `resolveFirstBootVaultName` accepts "default" as a valid name
+    // and behaves identically to the prior implicit default.
+    const spawnEnv: Record<string, string> = {
+      PARACHUTE_VAULT_NAME: vaultName,
+    };
     // Capture importParams + deps in the runInstall promise chain — when
     // mode === "import", run the vault-side `/.parachute/mirror/import`
     // POST as a follow-up step once the supervised vault has come up
@@ -2377,7 +2377,7 @@ export async function handleSetupVaultPost(req: Request, deps: SetupWizardDeps):
       registry,
       ...(deps.run ? { run: deps.run } : {}),
       ...(deps.isLinked ? { isLinked: deps.isLinked } : {}),
-      ...(Object.keys(spawnEnv).length > 0 ? { spawnEnv } : {}),
+      spawnEnv,
     })
       .then(async () => {
         if (!importToRun) return;