@openparachute/vault 0.5.2-rc.3 → 0.5.2-rc.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.5.2-rc.3",
+  "version": "0.5.2-rc.4",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",
@@ -22,7 +22,6 @@
     "test:core": "cd core && node --experimental-vm-modules node_modules/vitest/dist/cli.js run",
     "typecheck": "tsc --noEmit",
     "build:spa": "cd web/ui && bun install --frozen-lockfile && bun run build",
-    "postinstall": "if [ -d web/ui ]; then bun run build:spa; fi",
     "prepack": "bun run build:spa"
   },
   "dependencies": {

package/src/cli.ts

@@ -57,8 +57,10 @@ import {
   buildMcpEntryPlan,
   chooseHubOrigin,
   chooseMcpUrl,
+  detectHubPresence,
   detectInstallContext,
   mintHubJwt,
+  noOperatorTokenGuidance,
   readOperatorToken,
   removeMcpConfig,
   resolveInstallTarget,
@@ -548,6 +550,11 @@ async function cmdInit(args: string[] = []) {
   // 8. Summary
   const port = globalConfig.port || DEFAULT_PORT;
   const mcpUrl = `http://127.0.0.1:${port}/vault/${defaultVault}/mcp`;
+  // Probe whether a hub is present so the summary's "opted into a token but
+  // none minted" copy reflects reality: under a hub the vault is reachable via
+  // browser OAuth even with no header-auth token (#445). Only matters for the
+  // !apiKey branches; cheap + best-effort (never throws).
+  const hubPresent = !apiKey ? await detectHubPresence() : true;
   const lines = buildInitSummaryLines({
     addMcp,
     addToken,
@@ -558,6 +565,7 @@ async function cmdInit(args: string[] = []) {
     mcpUrl,
     vaultName: defaultVault,
     noTokenGuidance: credentialGuidance,
+    hubPresent,
   });
   for (const line of lines) console.log(line);
 }
@@ -3369,15 +3377,25 @@ interface VaultCredential {
 async function mintBootstrapCredential(
   name: string,
   verb: "read" | "write" = "read",
+  /**
+   * Test seam — injectable hub-presence probe. Defaults to the live
+   * `detectHubPresence` (loopback `/health` + configured-origin check). Lets
+   * tests drive both branches of the no-operator-token copy without a real hub.
+   */
+  detectHub: typeof detectHubPresence = detectHubPresence,
 ): Promise<VaultCredential> {
   const operatorToken = readOperatorToken();
   if (!operatorToken) {
+    // No operator.token. Two very different worlds, identical symptom:
+    //   (a) Hub running on a fresh box — the token isn't minted until the
+    //       admin wizard creates the first admin user (hub init Step 1.5 is a
+    //       no-op until then). NOTHING to do here; the old "install the hub …"
+    //       copy is circular (this very flow was spawned *by* the hub). #445.
+    //   (b) Genuinely standalone — no hub at all. The original guidance holds.
+    const hubPresent = await detectHub();
     return {
       token: null,
-      guidance:
-        "No token issued — no hub operator token at ~/.parachute/operator.token. " +
-        "Install the hub (`bun add -g @openparachute/hub` + `parachute init`) and re-run, " +
-        "or set VAULT_AUTH_TOKEN for an operator-channel bearer.",
+      guidance: noOperatorTokenGuidance(hubPresent),
     };
   }
   const port = readGlobalConfig().port || DEFAULT_PORT;

package/src/init-summary.test.ts

@@ -175,19 +175,62 @@ describe("buildInitSummaryLines", () => {
 
   // Explicit opt-in but no hub reachable to mint (vault#282 Stage 2 path,
   // reached only when the operator passes --token without a hub).
-  describe("MCP=N + token=Y but no hub (opt-in mint failed)", () => {
+  describe("MCP=N + token=Y but no hub (opt-in mint failed, standalone)", () => {
     const out = buildInitSummaryLines({
       ...baseInput,
       addMcp: false,
       addToken: true,
       apiKey: undefined,
       noTokenGuidance: "No token issued — hub unreachable.",
+      hubPresent: false,
     }).join("\n");
 
     test("surfaces the no-token-issued guidance + recovery", () => {
       expect(out).toContain("No token issued");
       expect(out).toContain("parachute-vault mcp-install");
     });
+
+    test("standalone framing — points at bringing a hub up / VAULT_AUTH_TOKEN", () => {
+      expect(out).toContain("Once a hub is running");
+      expect(out).toContain("VAULT_AUTH_TOKEN");
+    });
+
+    test("does NOT claim the vault is reachable (no hub present)", () => {
+      expect(out).not.toContain("Your vault is still reachable");
+    });
+  });
+
+  // #445: opted into a token, none minted, but a HUB IS PRESENT. The vault is
+  // reachable via the hub's browser OAuth flow even with no header-auth token,
+  // so the standalone "isn't reachable" framing would be false here.
+  describe("MCP=N + token=Y, no token minted, but hub present (#445)", () => {
+    const out = buildInitSummaryLines({
+      ...baseInput,
+      addMcp: false,
+      addToken: true,
+      apiKey: undefined,
+      noTokenGuidance: "No token yet — the hub's admin wizard mints it.",
+      hubPresent: true,
+    }).join("\n");
+
+    test("affirms the vault is still reachable via the hub's OAuth flow", () => {
+      expect(out).toContain("Your vault is still reachable");
+      expect(out).toContain("sign-in (OAuth)");
+    });
+
+    test("frames a header-auth token as optional (scripts / non-OAuth clients)", () => {
+      expect(out).toContain("only needed for scripts");
+      expect(out).toContain("parachute-vault mcp-install");
+    });
+
+    test("does NOT print the standalone 'Once a hub is running' / VAULT_AUTH_TOKEN copy", () => {
+      expect(out).not.toContain("Once a hub is running");
+      expect(out).not.toContain("VAULT_AUTH_TOKEN");
+    });
+
+    test("never claims the vault isn't reachable by any client", () => {
+      expect(out).not.toContain("isn't reachable by any client");
+    });
   });
 
   test("always prints Config: and Server: lines", () => {

package/src/init-summary.ts

@@ -26,6 +26,15 @@ export type InitSummaryInput = {
    * undefined, so they know why and how to make the vault reachable.
    */
   noTokenGuidance?: string | undefined;
+  /**
+   * Whether a hub is present on this host (live `/health` probe or a
+   * configured hub origin — see `detectHubPresence`). Branches the
+   * opted-into-a-token-but-none-minted copy: under a hub the vault is reachable
+   * via the hub's browser OAuth flow even with no header-auth token, so the
+   * old "your vault isn't reachable by any client" framing is false. #445.
+   * Undefined → treat as the conservative standalone case.
+   */
+  hubPresent?: boolean | undefined;
 };
 
 /**
@@ -45,7 +54,7 @@ export type InitSummaryInput = {
  *   !addMcp, !addToken          → OAuth-first: add Claude Code later
  */
 export function buildInitSummaryLines(input: InitSummaryInput): string[] {
-  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl, vaultName, noTokenGuidance } = input;
+  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl, vaultName, noTokenGuidance, hubPresent } = input;
   const lines: string[] = [];
   lines.push("");
   lines.push("---");
@@ -75,20 +84,35 @@ export function buildInitSummaryLines(input: InitSummaryInput): string[] {
     lines.push(`  - Paste into your other MCP client's config, or use as Authorization: Bearer <token>`);
     lines.push(`  - Won't be shown again — save it now.`);
   } else if (!addMcp && addToken && !apiKey) {
-    // Explicitly opted into a token but no hub was reachable to mint one
-    // (vault#282 Stage 2 — vault no longer mints local pvt_* tokens). Surface
-    // why and the recovery paths.
+    // Explicitly opted into a token but none was minted (vault#282 Stage 2 —
+    // vault no longer mints local pvt_* tokens). Surface why + recovery.
     lines.push("");
     lines.push(
       noTokenGuidance ??
         "No token issued — no hub was reachable to mint a hub JWT.",
     );
-    lines.push(
-      "  Once a hub is running, run `parachute-vault mcp-install` to mint + wire a token,",
-    );
-    lines.push(
-      "  or set VAULT_AUTH_TOKEN for an operator-channel bearer.",
-    );
+    if (hubPresent) {
+      // A hub IS present — the vault is already reachable via the hub's
+      // browser OAuth flow / web UI. A header-auth token is optional, only for
+      // non-OAuth clients + scripts. The "isn't reachable" framing is false
+      // here (#445).
+      lines.push(
+        "  Your vault is still reachable — clients connect through the hub's browser",
+      );
+      lines.push(
+        "  sign-in (OAuth); a header-auth token is only needed for scripts / non-OAuth",
+      );
+      lines.push(
+        "  clients. Run `parachute-vault mcp-install` to mint + wire one when you want it.",
+      );
+    } else {
+      lines.push(
+        "  Once a hub is running, run `parachute-vault mcp-install` to mint + wire a token,",
+      );
+      lines.push(
+        "  or set VAULT_AUTH_TOKEN for an operator-channel bearer.",
+      );
+    }
   } else if (!addMcp && !addToken) {
     // OAuth-first, but the operator skipped wiring Claude Code too.
     lines.push("");

package/src/mcp-install.test.ts

@@ -23,7 +23,9 @@ import {
   buildMcpEntryPlan,
   chooseHubOrigin,
   chooseMcpUrl,
+  detectHubPresence,
   mintHubJwt,
+  noOperatorTokenGuidance,
   readOperatorToken,
   removeMcpConfig,
   resolveInstallTarget,
@@ -315,6 +317,97 @@ describe("readOperatorToken", () => {
   });
 });
 
+describe("detectHubPresence", () => {
+  let origHome: string | undefined;
+  let tmpHome: string;
+
+  beforeEach(() => {
+    origHome = process.env.PARACHUTE_HOME;
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "vault-hub-presence-"));
+    process.env.PARACHUTE_HOME = tmpHome;
+  });
+
+  afterEach(() => {
+    if (origHome === undefined) delete process.env.PARACHUTE_HOME;
+    else process.env.PARACHUTE_HOME = origHome;
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  test("a configured non-loopback hub origin counts as present (no probe)", async () => {
+    let probed = false;
+    const mockFetch: typeof fetch = async () => {
+      probed = true;
+      return new Response(null, { status: 500 });
+    };
+    const present = await detectHubPresence({
+      env: { PARACHUTE_HUB_ORIGIN: "https://hub.example" },
+      fetchImpl: mockFetch,
+    });
+    expect(present).toBe(true);
+    expect(probed).toBe(false); // configured origin short-circuits the probe
+  });
+
+  test("loopback + healthy hub (2xx /health) → present", async () => {
+    const calls: string[] = [];
+    const mockFetch: typeof fetch = async (url) => {
+      calls.push(String(url));
+      return new Response("ok", { status: 200 });
+    };
+    const present = await detectHubPresence({ env: {}, fetchImpl: mockFetch });
+    expect(present).toBe(true);
+    expect(calls).toHaveLength(1);
+    // Probes the hub's fixed loopback port (1939), not vault's listen port.
+    expect(calls[0]).toBe("http://127.0.0.1:1939/health");
+  });
+
+  test("loopback + no hub answering (fetch throws) → absent", async () => {
+    const mockFetch: typeof fetch = async () => {
+      throw new Error("ECONNREFUSED");
+    };
+    const present = await detectHubPresence({ env: {}, fetchImpl: mockFetch });
+    expect(present).toBe(false);
+  });
+
+  test("loopback + hub answers non-2xx → absent", async () => {
+    const mockFetch: typeof fetch = async () => new Response("nope", { status: 503 });
+    const present = await detectHubPresence({ env: {}, fetchImpl: mockFetch });
+    expect(present).toBe(false);
+  });
+
+  test("$PARACHUTE_HUB_PORT overrides the probed port (deterministic for tests)", async () => {
+    const calls: string[] = [];
+    const mockFetch: typeof fetch = async (url) => {
+      calls.push(String(url));
+      return new Response("ok", { status: 200 });
+    };
+    const present = await detectHubPresence({
+      env: { PARACHUTE_HUB_PORT: "59399" },
+      fetchImpl: mockFetch,
+    });
+    expect(present).toBe(true);
+    expect(calls[0]).toBe("http://127.0.0.1:59399/health");
+  });
+});
+
+describe("noOperatorTokenGuidance (#445)", () => {
+  test("hub present → non-circular 'finish in the wizard' copy", () => {
+    const msg = noOperatorTokenGuidance(true);
+    // Does NOT tell the operator to install the hub (circular — this flow ran
+    // *under* the hub).
+    expect(msg).not.toContain("Install the hub");
+    expect(msg).not.toContain("bun add -g @openparachute/hub");
+    expect(msg).toContain("admin wizard mints");
+    expect(msg).toContain("Nothing to do here");
+  });
+
+  test("hub absent → keeps the standalone install-the-hub advice", () => {
+    const msg = noOperatorTokenGuidance(false);
+    expect(msg).toContain("Install the hub");
+    expect(msg).toContain("bun add -g @openparachute/hub");
+    expect(msg).toContain("VAULT_AUTH_TOKEN");
+  });
+});
+
 describe("resolveInstallTarget", () => {
   test("user scope → ~/.claude.json", () => {
     const res = resolveInstallTarget("user");

package/src/mcp-install.ts

@@ -216,6 +216,105 @@ export function readOperatorToken(env: NodeJS.ProcessEnv = process.env): string
   }
 }
 
+// ---------------------------------------------------------------------------
+// Hub-presence probe
+// ---------------------------------------------------------------------------
+
+/**
+ * Default loopback port the hub binds. Mirrors `hub-jwt.ts`'s
+ * `DEFAULT_HUB_LOOPBACK` (`http://127.0.0.1:1939`). When no hub origin is
+ * configured (the common fresh-box case), this is where a co-located hub
+ * answers.
+ */
+export const DEFAULT_HUB_LOOPBACK_PORT = 1939;
+
+/**
+ * Best-effort: is a hub actually present on this host *right now*?
+ *
+ * This is distinct from {@link InstallContext.hubReachable}, which only asks
+ * "is a non-loopback hub *origin* configured?" (env / expose-state). On a fresh
+ * box the hub is installed and running on loopback, but no origin is configured
+ * and the operator token isn't minted yet (hub mints it only when the first
+ * admin user is created in the web wizard). The stale standalone-era copy
+ * ("install the hub …") fires off `operatorTokenPresent === false` and so
+ * misreads that fresh-box state as "no hub". This probe lets the copy branch on
+ * whether a hub is genuinely absent vs. merely not-yet-bootstrapped.
+ *
+ * Signals, cheapest-first:
+ *   1. A configured non-loopback hub origin (`PARACHUTE_HUB_ORIGIN` /
+ *      expose-state) → a hub origin exists, treat as present without a probe.
+ *   2. A live `GET http://127.0.0.1:<hubPort>/health` returning a 2xx. The
+ *      hub binds its own fixed loopback port (1939 by default), independent of
+ *      the vault's listen port — so the probe always targets the hub port, not
+ *      `chooseHubOrigin`'s vault-loopback fallback. Short timeout; any error →
+ *      not present.
+ *
+ * `port` is the hub's loopback port (defaults to `$PARACHUTE_HUB_PORT`, else
+ * 1939). `fetchImpl` is an injectable test seam; `timeoutMs` keeps a dead port
+ * from stalling init. Never throws — returns `false` on any failure.
+ */
+export async function detectHubPresence(opts: {
+  port?: number;
+  env?: { PARACHUTE_HUB_ORIGIN?: string | undefined; PARACHUTE_HUB_PORT?: string | undefined };
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+} = {}): Promise<boolean> {
+  const env =
+    opts.env ?? (process.env as { PARACHUTE_HUB_ORIGIN?: string; PARACHUTE_HUB_PORT?: string });
+  // Port precedence: explicit arg → `$PARACHUTE_HUB_PORT` → 1939. The env
+  // override keeps the probe deterministic for tests + non-default-port hubs,
+  // so it never accidentally hits an unrelated hub on the host's 1939.
+  const envPort = env.PARACHUTE_HUB_PORT ? Number(env.PARACHUTE_HUB_PORT) : undefined;
+  const hubPort =
+    opts.port ?? (envPort !== undefined && Number.isFinite(envPort) ? envPort : DEFAULT_HUB_LOOPBACK_PORT);
+  // 1. A configured hub origin (env / expose-state) is itself a present-hub
+  //    signal — no need to probe. We pass `hubPort` purely as the loopback
+  //    fallback arg; its only role here is the source discriminator.
+  const configured = chooseHubOrigin(hubPort, env);
+  // A stale expose-state can false-positive here — acceptable: this only
+  // selects guidance copy, never gates behavior.
+  if (configured.source !== "loopback") return true;
+
+  // 2. Live health probe against the hub's fixed loopback port.
+  const origin = `http://127.0.0.1:${hubPort}`;
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const timeoutMs = opts.timeoutMs ?? 800;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(`${origin}/health`, { signal: controller.signal });
+    return res.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Pick the operator-facing guidance for the "no operator.token present" case,
+ * branched on whether a hub is genuinely absent vs. merely not-yet-bootstrapped
+ * (#445). Extracted as a pure function so the copy is unit-testable without
+ * importing cli.ts (which dispatches on import).
+ *
+ *   hubPresent === true  → a hub is running; the operator token just hasn't
+ *                          been minted yet (it's minted when the first admin
+ *                          user is created in the hub's web wizard). The old
+ *                          "install the hub …" advice is circular here — this
+ *                          flow was spawned *by* the hub. Tell them there's
+ *                          nothing to do and to finish in the wizard.
+ *   hubPresent === false → genuinely standalone. Keep the original advice.
+ */
+export function noOperatorTokenGuidance(hubPresent: boolean): string {
+  return hubPresent
+    ? "No token yet — the hub's admin wizard mints the operator token when you " +
+        "create the first admin user. Nothing to do here; finish setup in the wizard, " +
+        "then run `parachute-vault mcp-install` if you want a header-auth token for scripts."
+    : "No token issued — no hub operator token at ~/.parachute/operator.token. " +
+        "Install the hub (`bun add -g @openparachute/hub` + `parachute init`) and re-run, " +
+        "or set VAULT_AUTH_TOKEN for an operator-channel bearer.";
+}
+
 // ---------------------------------------------------------------------------
 // Hub mint-token client
 // ---------------------------------------------------------------------------

package/src/vault-create.test.ts

@@ -236,16 +236,23 @@ describe("vault create — OAuth-first auth (vault#442)", () => {
   test("--mint (no hub reachable) opts in but mints scope-narrow read, never admin", () => {
     // In this sandbox there's no hub/operator.token, so the mint can't complete
     // — but the request is scope-narrow read by default and must NEVER ask for
-    // admin. We assert the create still succeeds and the guidance points at the
-    // mint-token recovery (the scope requested is read, per mintBootstrapCredential).
+    // an admin grant. We assert the create still succeeds and the guidance is
+    // the standalone path (the scope requested is read, per
+    // mintBootstrapCredential).
+    //
+    // Point the hub-presence probe at a guaranteed-closed port so the test is
+    // deterministic regardless of whether a real hub happens to be running on
+    // the dev box's 1939 (#445 added a live `/health` probe to branch the
+    // no-operator-token copy).
     const { exitCode, stdout } = runCli(
       ["create", "wantmint", "--mint", "--json"],
-      { PARACHUTE_HOME: home },
+      { PARACHUTE_HOME: home, PARACHUTE_HUB_PORT: "59399" },
     );
     expect(exitCode).toBe(0);
     const payload = JSON.parse(stdout.trim());
-    // No hub here → no token, but the guidance is the standalone mint path, not
-    // an admin grant.
+    // No hub here → no token, and the standalone guidance asks for NO admin
+    // grant (the #445 hub-present "admin wizard" copy is gated out by the dead
+    // probe port above).
     expect(payload.token).toBe("");
     expect(payload.token_guidance).not.toContain("admin");
   });