@openparachute/vault 0.3.1 → 0.3.3

package/README.md

@@ -2,7 +2,9 @@
 
 **Parachute Vault is a self-hosted knowledge graph that any AI can read and write, over the open [MCP](https://modelcontextprotocol.io) protocol.** Your notes, tags, links, and attachments live on your machine — in plain SQLite databases under `~/.parachute/`, not in a vendor's cloud.
 
-Works with Claude, ChatGPT, Gemini, or any future MCP-capable AI. Switch tools without losing your knowledge. No vendor lock-in, no re-import step when the next model lands. One command to install; one OAuth consent to connect each AI client.
+Today it works with **Claude Code, Codex, Goose, OpenCode, and any other local MCP client** — same endpoint, your vault. Claude Code auto-wires on install; for the rest, point them at `http://127.0.0.1:1940/vault/default/mcp`.
+
+Web AI connectors — **claude.ai**, **ChatGPT**, and **Gemini** — are coming in the next few weeks. Switch tools, keep your knowledge. No vendor lock-in, no re-import step when the next model lands.
 
 ## Quick start
 
@@ -20,7 +22,7 @@ bun install
 bun src/cli.ts vault init
 ```
 
-`vault init` creates a vault, generates an API key, starts a background daemon (launchd on Mac, systemd on Linux), and configures Claude Code's MCP — all in one command. Your API key is printed once at init; save it for connecting from other tools.
+`vault init` creates a vault, generates an API key, starts a background daemon (launchd on Mac, systemd on Linux), and configures Claude Code's MCP — all in one command. Start a new Claude Code session and your vault's tools show up. For other local MCP clients (Codex, Goose, OpenCode, Cursor, Zed, Cline, your own agent), point them at `http://127.0.0.1:1940/vault/default/mcp` — the API key is printed once at init; save it for anything that isn't Claude Code.
 
 For remote access from Claude Desktop or mobile apps, see [Deployment](#deployment) below.
 
@@ -88,11 +90,13 @@ The daemon binds `0.0.0.0:1940` (or whatever you set in `PORT`) and serves REST,
 
 ### Your API token
 
-The `pvt_...` token printed at init is the one baked into `~/.claude.json`. It's not stored anywhere retrievable — save it if you need it for `curl`, cron, or any other script. Lost it? Just mint a new one: `parachute-vault tokens create`. Tokens are SHA-256 hashed at rest in each vault's `vault.db`.
+`vault init` asks two explicit questions: (1) install vault as an MCP server in `~/.claude.json`? (2) also surface the API token so you can paste it into other MCP clients (Codex, Goose, OpenCode, Cursor, Zed, Cline), scripts, or `curl`? Both default yes. Pass `--mcp` / `--no-mcp` and `--token` / `--no-token` for non-interactive installs.
+
+If you said yes to (2), the `pvt_...` token is printed prominently at the end — it's the same token baked into `~/.claude.json` (if you also said yes to (1)). It's not stored anywhere retrievable — save it if you need it for `curl`, cron, or any other script. Lost it? Just mint a new one: `parachute-vault tokens create`. Tokens are SHA-256 hashed at rest in each vault's `vault.db`.
 
-### Owner password prompt
+### Owner password (for OAuth, coming soon)
 
-Init pauses for one interactive prompt: "Set an owner password for OAuth consent?" The password is what the consent page asks for when Claude Desktop / Parachute Daily / any browser-OAuth client connects. You can skip it and set it later with `parachute-vault set-password`; without it, the consent page falls back to pasting a vault token. See [Connecting a client → Owner password](#owner-password-needed-for-oauth).
+`vault init` doesn't prompt for an owner password — the password is only needed for OAuth consent, which is what browser-based clients (claude.ai, ChatGPT, Claude Desktop) use, and those paths are coming in the next few weeks. When you're ready to expose the vault publicly, set one with `parachute-vault set-password` (and optionally `parachute-vault 2fa enroll`). See [Connecting a client → Owner password](#owner-password-needed-for-oauth).
 
 ## Connecting a client
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/cli.ts

@@ -49,6 +49,7 @@ import type { VaultConfig } from "./config.ts";
 import { DATA_DIR } from "./config.ts";
 import { installAgent, uninstallAgent, isAgentLoaded, restartAgent } from "./launchd.ts";
 import { chooseMcpUrl } from "./mcp-install.ts";
+import { buildInitSummaryLines } from "./init-summary.ts";
 import {
   runBackup,
   readLastBackup,
@@ -225,8 +226,14 @@ async function cmdInit(args: string[] = []) {
   // --no-mcp skips it without prompting. If both passed, --no-mcp wins
   // (safer default). Neither → prompt in a TTY, default-yes in a
   // non-TTY for back-compat with existing piped install scripts.
+  //
+  // --token / --no-token follow the same pattern for whether the API
+  // token is surfaced to the user at the end of init (for pasting into
+  // other MCP clients, scripts, or curl).
   const flagMcpOn = args.includes("--mcp");
   const flagMcpOff = args.includes("--no-mcp");
+  const flagTokenOn = args.includes("--token");
+  const flagTokenOff = args.includes("--no-token");
 
   const isMac = process.platform === "darwin";
   const isLinux = process.platform === "linux";
@@ -325,9 +332,16 @@ async function cmdInit(args: string[] = []) {
     console.log();
   }
 
-  // 5b. Offer to set an owner password for OAuth consent, unless one is already set.
+  // 5b. Owner password is only needed for OAuth consent (browser-based
+  // clients like claude.ai / ChatGPT / Claude Desktop). Those paths are
+  // coming in the next few weeks; until then, skip the prompt. Users who
+  // want to expose the vault publicly today can set one manually via
+  // `parachute-vault set-password`.
   if (!hasOwnerPassword()) {
-    await promptForOwnerPassword("Set an owner password for OAuth consent?");
+    console.log();
+    console.log("Public exposure + web-AI connectors (claude.ai, ChatGPT, etc.) are coming soon.");
+    console.log("  When you're ready to expose this vault publicly, run:");
+    console.log("    parachute-vault set-password    # required for OAuth consent");
   }
 
   // 6. Install daemon (platform-aware). Idempotent — safe to re-run after
@@ -361,11 +375,43 @@ async function cmdInit(args: string[] = []) {
   } else if (flagMcpOn) {
     addMcp = true;
   } else if (process.stdin.isTTY) {
-    addMcp = await confirm("Add Vault MCP to Claude Code (~/.claude.json)?", true);
+    addMcp = await confirm("Install Vault as an MCP server in Claude Code (~/.claude.json)?", true);
   } else {
     addMcp = true; // non-interactive: preserve the installable-via-pipe default
   }
 
+  // 7b. Surface an API token for other clients? (Codex, Goose, OpenCode,
+  // Cursor, Zed, Cline, scripts, curl.) Same flag/TTY precedence as MCP.
+  // Note: a token is always minted when addMcp is true (it gets baked into
+  // the ~/.claude.json entry); this prompt controls whether that token is
+  // printed prominently at the end so the user can paste it elsewhere.
+  let addToken: boolean;
+  if (flagTokenOff) {
+    addToken = false;
+  } else if (flagTokenOn) {
+    addToken = true;
+  } else if (process.stdin.isTTY) {
+    addToken = await confirm(
+      "Generate an API token for other MCP clients (Codex, Goose, OpenCode, Cursor, Zed, Cline), scripts, or curl?",
+      true,
+    );
+  } else {
+    addToken = true; // non-interactive: default-yes matches addMcp default
+  }
+
+  // Mint a token if we need one (for the claude.json entry and/or for
+  // prominent display) and don't already have one from vault creation.
+  // Re-runs of init that opt in will mint a fresh token — old tokens
+  // continue to work; the user can `tokens revoke` the unused ones.
+  const defaultVault = globalConfig.default_vault || "default";
+  const needToken = addMcp || addToken;
+  if (needToken && !apiKey) {
+    const store = getVaultStore(defaultVault);
+    const { fullToken } = generateToken();
+    createToken(store.db, fullToken, { label: "init", permission: "full" });
+    apiKey = fullToken;
+  }
+
   if (addMcp) {
     installMcpConfig(apiKey);
     console.log(`  MCP server added to ~/.claude.json`);
@@ -375,30 +421,21 @@ async function cmdInit(args: string[] = []) {
   }
 
   // 8. Summary
-  console.log("\n---");
   const port = globalConfig.port || DEFAULT_PORT;
-  if (apiKey) {
-    console.log(`\nYour API token: ${apiKey}`);
-    console.log("  Use this in Claude Desktop, curl, or any client.");
-    console.log("  Pass via: Authorization: Bearer <token>");
-    console.log("  Or via:   X-API-Key: <token>");
-    console.log("\nSave this — it will not be shown again.");
-  }
-
-  console.log(`\nConfig:   ${CONFIG_DIR}`);
-  console.log(`Server:   http://${bindHost}:${port}`);
-
-  console.log(`\nUsage examples:`);
-  console.log(`  curl http://localhost:${port}/health`);
-  if (apiKey) {
-    console.log(`  curl -H "Authorization: Bearer ${apiKey}" http://localhost:${port}/api/notes`);
-  }
-
-  console.log(`\nNext steps:`);
-  console.log(`  parachute-vault status            check everything is running`);
-  console.log(`  parachute-vault config             view/edit configuration`);
+  const mcpUrl = `http://127.0.0.1:${port}/vault/${defaultVault}/mcp`;
+  const lines = buildInitSummaryLines({
+    addMcp,
+    addToken,
+    apiKey,
+    configDir: CONFIG_DIR,
+    bindHost,
+    port,
+    mcpUrl,
+  });
+  for (const line of lines) console.log(line);
 }
 
+
 async function promptForOwnerPassword(purpose: string): Promise<boolean> {
   console.log(`\n${purpose}`);
   console.log("  Used on the OAuth consent page to authorize third-party clients");
@@ -2066,7 +2103,11 @@ data, and debugging.
 ── Standard use ───────────────────────────────────────────────────────
 
 Setup:
-  parachute-vault init [--mcp | --no-mcp]  Set up everything (one command, idempotent)
+  parachute-vault init [--mcp|--no-mcp] [--token|--no-token]
+                                           Set up everything (one command, idempotent).
+                                           --mcp/--no-mcp controls the Claude Code MCP entry;
+                                           --token/--no-token controls whether an API token is
+                                           printed for pasting into other MCP clients / scripts.
   parachute-vault doctor                   Diagnose install/config issues
   parachute-vault uninstall [--wipe] [--yes]
                                            Remove daemon + MCP entry; --wipe also removes vaults, .env,

package/src/init-summary.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Tests for `buildInitSummaryLines` — the post-install summary printed at the
+ * end of `vault init`. The summary branches on the (addMcp, addToken) decision
+ * matrix; these tests cover all four cells plus the token surfacing /
+ * Bearer-example rules.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { buildInitSummaryLines } from "./init-summary.ts";
+
+const baseInput = {
+  configDir: "/tmp/parachute",
+  bindHost: "127.0.0.1",
+  port: 1940,
+  mcpUrl: "http://127.0.0.1:1940/vault/default/mcp",
+};
+
+function lines(addMcp: boolean, addToken: boolean, apiKey: string | undefined) {
+  return buildInitSummaryLines({ ...baseInput, addMcp, addToken, apiKey });
+}
+
+describe("buildInitSummaryLines", () => {
+  describe("MCP=Y + token=Y (most common)", () => {
+    const out = lines(true, true, "pvt_abc123").join("\n");
+
+    test("prints token prominently", () => {
+      expect(out).toContain("Your API token: pvt_abc123");
+    });
+
+    test("notes token is baked into ~/.claude.json", () => {
+      expect(out).toContain("Baked into ~/.claude.json for Claude Code");
+    });
+
+    test("includes save-it-now warning", () => {
+      expect(out).toContain("Won't be shown again — save it now.");
+    });
+
+    test("includes Bearer curl example", () => {
+      expect(out).toContain(
+        'curl -H "Authorization: Bearer pvt_abc123" http://localhost:1940/api/notes',
+      );
+    });
+
+    test("Next steps mentions starting a Claude Code session", () => {
+      expect(out).toContain("Start a new Claude Code session");
+    });
+  });
+
+  describe("MCP=Y + token=N (MCP wired, token not surfaced)", () => {
+    const out = lines(true, false, "pvt_secret").join("\n");
+
+    test("does not print the token prominently", () => {
+      expect(out).not.toContain("pvt_secret");
+    });
+
+    test("does not include the 'Baked into' bullet", () => {
+      expect(out).not.toContain("Baked into ~/.claude.json");
+    });
+
+    test("includes the tokens-create-later hint", () => {
+      expect(out).toContain("Token in ~/.claude.json");
+      expect(out).toContain("parachute vault tokens create");
+    });
+
+    test("omits the Bearer curl example", () => {
+      expect(out).not.toContain("Authorization: Bearer");
+    });
+
+    test("still shows the Claude-Code-session next step", () => {
+      expect(out).toContain("Start a new Claude Code session");
+    });
+  });
+
+  describe("MCP=N + token=Y (token only)", () => {
+    const out = lines(false, true, "pvt_xyz").join("\n");
+
+    test("prints token prominently", () => {
+      expect(out).toContain("Your API token: pvt_xyz");
+    });
+
+    test("omits the 'Baked into' bullet (no claude.json entry written)", () => {
+      expect(out).not.toContain("Baked into ~/.claude.json");
+    });
+
+    test("includes Bearer curl example", () => {
+      expect(out).toContain('Authorization: Bearer pvt_xyz');
+    });
+
+    test("Next steps points at any local MCP client", () => {
+      expect(out).toContain("Point any local MCP client");
+      expect(out).toContain("http://127.0.0.1:1940/vault/default/mcp");
+    });
+
+    test("Next steps offers mcp-install as a way back", () => {
+      expect(out).toContain("parachute-vault mcp-install");
+    });
+  });
+
+  describe("MCP=N + token=N (unreachable)", () => {
+    const out = lines(false, false, undefined).join("\n");
+
+    test("warns the vault is unreachable", () => {
+      expect(out).toContain("your vault isn't reachable by any client");
+    });
+
+    test("points to both recovery paths", () => {
+      expect(out).toContain("parachute-vault mcp-install");
+      expect(out).toContain("parachute vault tokens create");
+    });
+
+    test("does not print any token", () => {
+      expect(out).not.toContain("Your API token:");
+      expect(out).not.toMatch(/pvt_/);
+    });
+
+    test("omits the Bearer curl example", () => {
+      expect(out).not.toContain("Authorization: Bearer");
+    });
+  });
+
+  test("always prints Config: and Server: lines", () => {
+    for (const [addMcp, addToken] of [
+      [true, true],
+      [true, false],
+      [false, true],
+      [false, false],
+    ] as const) {
+      const out = lines(addMcp, addToken, addMcp || addToken ? "pvt_k" : undefined).join("\n");
+      expect(out).toContain("Config:   /tmp/parachute");
+      expect(out).toContain("Server:   http://127.0.0.1:1940");
+    }
+  });
+});

package/src/init-summary.ts

@@ -0,0 +1,90 @@
+/**
+ * Pure helper for `vault init`'s post-install summary. Extracted from cli.ts
+ * so the (addMcp, addToken) decision-matrix branches can be unit-tested
+ * without side-effects from importing the CLI entrypoint.
+ */
+
+export type InitSummaryInput = {
+  addMcp: boolean;
+  addToken: boolean;
+  apiKey: string | undefined;
+  configDir: string;
+  bindHost: string;
+  port: number;
+  mcpUrl: string;
+};
+
+/**
+ * Build the post-install summary lines for `vault init`, branched on the
+ * (addMcp, addToken) decision matrix:
+ *
+ *   Y, Y → token baked into claude.json + printed prominently
+ *   Y, N → token baked into claude.json, hint about `tokens create`
+ *   N, Y → token printed prominently, no claude.json entry
+ *   N, N → warning: vault unreachable; both recovery paths listed
+ */
+export function buildInitSummaryLines(input: InitSummaryInput): string[] {
+  const { addMcp, addToken, apiKey, configDir, bindHost, port, mcpUrl } = input;
+  const lines: string[] = [];
+  lines.push("");
+  lines.push("---");
+
+  if (addMcp && addToken && apiKey) {
+    lines.push("");
+    lines.push(`Your API token: ${apiKey}`);
+    lines.push(`  - Baked into ~/.claude.json for Claude Code ✓`);
+    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) {
+    lines.push("");
+    lines.push(
+      "Token in ~/.claude.json; run `parachute vault tokens create` later if you need one for other clients.",
+    );
+  } else if (!addMcp && addToken && apiKey) {
+    lines.push("");
+    lines.push(`Your API token: ${apiKey}`);
+    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) {
+    lines.push("");
+    lines.push(
+      "You've skipped both MCP install and token generation — your vault isn't reachable by any client.",
+    );
+    lines.push(
+      "  Add Claude Code later with `parachute-vault mcp-install`, or mint a token with `parachute vault tokens create`.",
+    );
+  }
+
+  lines.push("");
+  lines.push(`Config:   ${configDir}`);
+  lines.push(`Server:   http://${bindHost}:${port}`);
+
+  lines.push("");
+  lines.push(`Usage examples:`);
+  lines.push(`  curl http://localhost:${port}/health`);
+  if (addToken && apiKey) {
+    lines.push(`  curl -H "Authorization: Bearer ${apiKey}" http://localhost:${port}/api/notes`);
+  }
+
+  lines.push("");
+  lines.push(`Next steps:`);
+  if (addMcp) {
+    lines.push(`  - Start a new Claude Code session — your Vault is already wired in. Try:`);
+    lines.push(`      claude "Help me set up my parachute vault"`);
+    lines.push(`  - Or point any other local MCP client (Codex, Goose, OpenCode, Cursor,`);
+    lines.push(`    Zed, Cline, your own agent) at:`);
+    lines.push(`      ${mcpUrl}`);
+  } else if (addToken) {
+    lines.push(`  - Point any local MCP client (Codex, Goose, OpenCode, Cursor, Zed,`);
+    lines.push(`    Cline, your own agent) at:`);
+    lines.push(`      ${mcpUrl}`);
+    lines.push(`  - Or add Claude Code back anytime:  parachute-vault mcp-install`);
+  } else {
+    lines.push(`  - Add Claude Code:  parachute-vault mcp-install`);
+    lines.push(`  - Mint a token:     parachute vault tokens create`);
+  }
+  lines.push(`  - Check status:     parachute-vault status`);
+  lines.push(`  - Edit config:      parachute-vault config`);
+
+  return lines;
+}

package/src/prompt.ts

@@ -74,36 +74,52 @@ export async function askPassword(question: string): Promise<string> {
       }
     };
 
+    // Batch visible output per data event. On Bun 1.2.x, per-char writes
+    // can appear in bursts (keystrokes echoing late or out of order);
+    // coalescing to a single write per data event keeps the visible
+    // stream in lock-step with the captured input.
     const onData = (data: string) => {
       try {
+        let toWrite = "";
+        let done = false;
+        let aborted = false;
         for (const ch of data) {
           // Enter — done
           if (ch === "\r" || ch === "\n") {
-            process.stdout.write("\n");
-            cleanup();
-            resolve(buf);
-            return;
+            done = true;
+            break;
           }
           // Ctrl-C — abort
           if (ch === "\u0003") {
-            process.stdout.write("\n");
-            cleanup();
-            process.exit(130);
+            aborted = true;
+            break;
           }
           // Backspace / DEL
           if (ch === "\u0008" || ch === "\u007f") {
             if (buf.length > 0) {
               buf = buf.slice(0, -1);
-              process.stdout.write("\b \b");
+              toWrite += "\b \b";
             }
             continue;
           }
           // Printable
           if (ch >= " ") {
             buf += ch;
-            process.stdout.write("*");
+            toWrite += "*";
           }
         }
+        if (toWrite) process.stdout.write(toWrite);
+        if (done) {
+          process.stdout.write("\n");
+          cleanup();
+          resolve(buf);
+          return;
+        }
+        if (aborted) {
+          process.stdout.write("\n");
+          cleanup();
+          process.exit(130);
+        }
       } catch (err) {
         cleanup();
         reject(err);