@openparachute/hub 0.7.4-rc.5 → 0.7.4-rc.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/hub",
-  "version": "0.7.4-rc.5",
+  "version": "0.7.4-rc.7",
   "description": "parachute — the local hub for the Parachute ecosystem (discovery, ports, lifecycle, soon OAuth).",
   "license": "AGPL-3.0",
   "publishConfig": {
@@ -11,15 +11,8 @@
   "bin": {
     "parachute": "src/cli.ts"
   },
-  "workspaces": [
-    "packages/*"
-  ],
-  "files": [
-    "src",
-    "web/ui/dist",
-    "README.md",
-    "LICENSE"
-  ],
+  "workspaces": ["packages/*"],
+  "files": ["src", "web/ui/dist", "README.md", "LICENSE"],
   "repository": {
     "type": "git",
     "url": "https://github.com/ParachuteComputer/parachute-hub.git"

package/src/__tests__/admin-vaults.test.ts

@@ -2,7 +2,13 @@ import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { HOST_ADMIN_SCOPE, type RunResult, handleCreateVault } from "../admin-vaults.ts";
+import {
+  HOST_ADMIN_SCOPE,
+  type RunResult,
+  handleCreateVault,
+  listVaultInstanceNames,
+  provisionVault,
+} from "../admin-vaults.ts";
 import { hubDbPath, openHubDb } from "../hub-db.ts";
 import { signAccessToken } from "../jwt-sign.ts";
 import { upsertService, writeManifest } from "../services-manifest.ts";
@@ -1304,3 +1310,160 @@ describe("DELETE /vaults/<name> — the identity cascade", () => {
     }
   });
 });
+
+// ===========================================================================
+// #478 — empty-paths vault rows must not resolve to phantom "default"
+// ===========================================================================
+
+describe("#478 — empty-paths vault row tolerance", () => {
+  test("findExistingVault: empty-paths vault row does NOT match 'default'", () => {
+    // A vault module registered in services.json with paths:[] is "installed
+    // but no servable vault instance". Hub must skip it — never synthesize a
+    // phantom "default" — so provisionVault can proceed to a real create.
+    const h = makeHarness();
+    try {
+      // Write a services.json with a parachute-vault entry carrying paths:[].
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: 1940,
+              paths: [],
+              health: "/health",
+              version: "0.5.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      // Calling provisionVault("default") internally calls findExistingVault.
+      // We verify the behaviour indirectly via listVaultInstanceNames (exported
+      // for this test) and via provisionVault's created:true path below.
+      const names = listVaultInstanceNames(h.manifestPath);
+      expect(names.has("default")).toBe(false);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("listVaultInstanceNames: empty-paths vault row is omitted from the Set", () => {
+    const h = makeHarness();
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: 1940,
+              paths: [],
+              health: "/health",
+              version: "0.5.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const names = listVaultInstanceNames(h.manifestPath);
+      expect(names.size).toBe(0);
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("provisionVault: empty-paths row → created:true (proceeds to orchestrate, not false 'already exists')", async () => {
+    // Core regression test for #478: before the fix, an empty-paths row
+    // resolved to phantom "default" → findExistingVault returned non-null →
+    // provisionVault short-circuited to created:false with "already exists".
+    // After the fix: findExistingVault returns null → orchestrate runs →
+    // created:true.
+    const h = makeHarness();
+    try {
+      const db = openHubDb(hubDbPath(h.dir));
+      try {
+        rotateSigningKey(db);
+        // Seed an empty-paths vault row (what vault's self-register emits at
+        // zero vaults, per the #478 contract).
+        writeManifest(
+          {
+            services: [
+              {
+                name: "parachute-vault",
+                port: 1940,
+                paths: [],
+                health: "/health",
+                version: "0.5.0",
+              },
+            ],
+          },
+          h.manifestPath,
+        );
+
+        const calls: Array<readonly string[]> = [];
+        const runCommand = async (cmd: readonly string[]): Promise<RunResult> => {
+          calls.push(cmd);
+          // Simulate vault CLI writing the real path into services.json after
+          // a successful create. Because vault IS already registered (paths:[]),
+          // orchestrate picks the `parachute-vault create --json` branch and
+          // expects JSON stdout.
+          upsertService(
+            {
+              name: "parachute-vault",
+              port: 1940,
+              paths: ["/vault/default"],
+              health: "/health",
+              version: "0.5.0",
+            },
+            h.manifestPath,
+          );
+          return { exitCode: 0, stdout: vaultCreateJson("default"), stderr: "" };
+        };
+
+        const result = await provisionVault("default", {
+          issuer: ISSUER,
+          manifestPath: h.manifestPath,
+          runCommand,
+        });
+
+        // Must have proceeded to orchestrate and returned created:true.
+        expect(result.ok).toBe(true);
+        if (!result.ok) return; // narrow for TS
+        expect(result.created).toBe(true);
+        // The orchestration command ran (not short-circuited).
+        expect(calls.length).toBeGreaterThan(0);
+      } finally {
+        db.close();
+      }
+    } finally {
+      h.cleanup();
+    }
+  });
+
+  test("listVaultInstanceNames: real paths still enumerate correctly (empty-paths does not break them)", () => {
+    // Sanity: mixing an empty-paths row with a real-paths row — the real
+    // paths are still found, the empty one is still skipped.
+    const h = makeHarness();
+    try {
+      writeManifest(
+        {
+          services: [
+            {
+              name: "parachute-vault",
+              port: 1940,
+              paths: ["/vault/default", "/vault/work"],
+              health: "/health",
+              version: "0.5.0",
+            },
+          ],
+        },
+        h.manifestPath,
+      );
+      const names = listVaultInstanceNames(h.manifestPath);
+      expect(names.has("default")).toBe(true);
+      expect(names.has("work")).toBe(true);
+      expect(names.size).toBe(2);
+    } finally {
+      h.cleanup();
+    }
+  });
+});

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/__tests__/vault-names.test.ts

@@ -68,11 +68,16 @@ describe("listVaultNames", () => {
     expect(listVaultNames(manifest)).toEqual(["personal", "work"]);
   });
 
-  test("entry with no paths falls back to the manifest-suffix name (hub#143)", () => {
+  test("#478: bare empty-paths `parachute-vault` row yields NO name (no phantom 'default')", () => {
+    // What vault's self-register emits at zero vaults: the row stays present
+    // (installed-detection) but advertises no `/vault/<name>` path. It must not
+    // leak a selectable/assignable "default" before any vault exists. Mirrors
+    // the empty-paths skip in admin-vaults.ts (findExistingVault /
+    // listVaultInstanceNames).
     const manifest: ServicesManifest = {
       services: [
         {
-          name: "parachute-vault-archived",
+          name: "parachute-vault",
           port: 1940,
           paths: [],
           health: "/h",
@@ -80,7 +85,31 @@ describe("listVaultNames", () => {
         },
       ],
     };
-    expect(listVaultNames(manifest)).toEqual(["archived"]);
+    expect(listVaultNames(manifest)).toEqual([]);
+  });
+
+  test("#478: empty-paths row is skipped; real-paths vault rows are unchanged (positive control)", () => {
+    // An empty-paths row alongside a real-paths row: the real instance still
+    // resolves, the empty one contributes nothing.
+    const manifest: ServicesManifest = {
+      services: [
+        {
+          name: "parachute-vault",
+          port: 1940,
+          paths: [],
+          health: "/h",
+          version: "0.1.0",
+        },
+        {
+          name: "parachute-vault-work",
+          port: 1941,
+          paths: ["/vault/work"],
+          health: "/h",
+          version: "0.1.0",
+        },
+      ],
+    };
+    expect(listVaultNames(manifest)).toEqual(["work"]);
   });
 
   test("deduplicates collisions across single-entry + per-vault shapes", () => {

package/src/admin-vaults.ts

@@ -207,15 +207,11 @@ function findExistingVault(
   } catch {
     return null;
   }
-  const target = `/vault/${name}`;
   for (const svc of manifest.services) {
     if (!isVaultEntry(svc)) continue;
-    if (svc.paths.length === 0) {
-      if (vaultInstanceNameFor(svc.name, undefined) === name) {
-        return { url: target, version: svc.version, path: target };
-      }
-      continue;
-    }
+    // #478: an empty-paths vault row means "installed but no servable vault
+    // instance" — skip it entirely so it never resolves to a phantom "default".
+    if (svc.paths.length === 0) continue;
     for (const path of svc.paths) {
       if (vaultInstanceNameFor(svc.name, path) === name) {
         return { url: path, version: svc.version, path };
@@ -607,7 +603,7 @@ function emptyCascadeSummary(): CascadeSummary {
 }
 
 /** Every vault instance name currently registered in services.json. */
-function listVaultInstanceNames(manifestPath: string): Set<string> {
+export function listVaultInstanceNames(manifestPath: string): Set<string> {
   const names = new Set<string>();
   let manifest: ReturnType<typeof readManifest>;
   try {
@@ -617,10 +613,9 @@ function listVaultInstanceNames(manifestPath: string): Set<string> {
   }
   for (const svc of manifest.services) {
     if (!isVaultEntry(svc)) continue;
-    if (svc.paths.length === 0) {
-      names.add(vaultInstanceNameFor(svc.name, undefined));
-      continue;
-    }
+    // #478: an empty-paths vault row means "installed but no servable vault
+    // instance" — skip it so no phantom "default" is synthesized.
+    if (svc.paths.length === 0) continue;
     for (const path of svc.paths) names.add(vaultInstanceNameFor(svc.name, path));
   }
   return names;

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;

package/src/vault-names.ts

@@ -23,8 +23,17 @@
  * Walks both manifest shapes: single-entry-multi-path (`parachute-vault`
  * with `paths: ["/vault/work", "/vault/personal"]`) and per-vault entries
  * (`parachute-vault-work`) by delegating each (name, path) pair to
- * `vaultInstanceNameFor`. Entries with no paths still resolve to a name via
- * the helper's manifest-suffix fallback (hub#143).
+ * `vaultInstanceNameFor`.
+ *
+ * #478: an empty-paths vault row (e.g. `parachute-vault` with `paths: []`,
+ * which vault's self-register emits at zero vaults) is "installed but no
+ * servable vault instance" and is SKIPPED entirely — it must not synthesize a
+ * name (the bare `parachute-vault` would otherwise resolve to a phantom
+ * "default"). This mirrors the empty-paths `continue` in `admin-vaults.ts`'s
+ * `findExistingVault`/`listVaultInstanceNames`, so every read path agrees: a
+ * vault instance is named only by a real `/vault/<name>` mount path. This
+ * supersedes the prior hub#143 manifest-suffix fallback for path-less entries
+ * — a registered vault carries its mount path once a vault exists.
  */
 import { type ServicesManifest, readManifestLenient } from "./services-manifest.ts";
 import { isVaultEntry, vaultInstanceNameFor } from "./well-known.ts";
@@ -39,8 +48,10 @@ export function listVaultNames(manifest: ServicesManifest): string[] {
   const names = new Set<string>();
   for (const svc of manifest.services) {
     if (!isVaultEntry(svc)) continue;
-    const paths = svc.paths.length > 0 ? svc.paths : [undefined];
-    for (const path of paths) {
+    // #478: an empty-paths vault row means "installed but no servable vault
+    // instance" — skip it so it never synthesizes a phantom "default".
+    if (svc.paths.length === 0) continue;
+    for (const path of svc.paths) {
       names.add(vaultInstanceNameFor(svc.name, path));
     }
   }