@openparachute/vault 0.4.6-rc.3 → 0.4.6

package/src/export-watch.ts

@@ -0,0 +1,255 @@
+/**
+ * Helpers for `parachute-vault export --watch` and `--git-commit`.
+ *
+ * Split out from `cli.ts` so the template renderer and git-shell helpers are
+ * unit-testable without spawning the full CLI. The CLI imports and wires
+ * these into `cmdExport`'s watch loop; tests import them directly.
+ *
+ * No new deps — `git` is shelled out via `Bun.spawn`. Watch detection is
+ * polling: every `intervalSeconds`, run an incremental export with the
+ * cursor captured at the *start* of the previous cycle. Vault writes are
+ * HTTP-mediated and don't surface to filesystem watchers (the bun:sqlite DB
+ * is opaque), so polling on `updated_at >= cursor` is the simplest robust
+ * detection. See `parachute-patterns/cookbook/vault-portable-export.md`.
+ */
+
+// ---------------------------------------------------------------------------
+// Commit message templating
+// ---------------------------------------------------------------------------
+
+/** Variables exposed to `--git-message-template`. */
+export interface CommitTemplateVars {
+  /** ISO-formatted UTC timestamp captured at commit time. */
+  date: string;
+  /** Count of notes changed since the previous export cursor. */
+  notes_changed: number;
+  /**
+   * First changed note's title (or path / id fallback) since the previous
+   * cursor — useful for single-note commits. Empty when nothing matched or
+   * on the initial export (where "first changed" is ambiguous).
+   */
+  first_note_title: string;
+  /** Source vault name. */
+  vault_name: string;
+}
+
+/**
+ * Substitute `{{var}}` tokens in `template`. Recognized vars:
+ *
+ *   `{{date}}` `{{notes_changed}}` `{{plural}}` `{{first_note_title}}` `{{vault_name}}`
+ *
+ * `{{plural}}` is `""` when `notes_changed === 1`, else `"s"` — so
+ * `"{{notes_changed}} note{{plural}}"` reads naturally for both 1 and N
+ * without the operator writing their own conditional.
+ *
+ * Unknown tokens pass through untouched (so a typo in the template is
+ * visible in the commit message rather than silently dropped).
+ */
+export function renderCommitMessage(template: string, vars: CommitTemplateVars): string {
+  return template
+    .replace(/\{\{date\}\}/g, vars.date)
+    .replace(/\{\{notes_changed\}\}/g, String(vars.notes_changed))
+    .replace(/\{\{plural\}\}/g, vars.notes_changed === 1 ? "" : "s")
+    .replace(/\{\{first_note_title\}\}/g, vars.first_note_title)
+    .replace(/\{\{vault_name\}\}/g, vars.vault_name);
+}
+
+/** Default commit message template. Reads as "export: <iso> (N note[s])". */
+export const DEFAULT_COMMIT_TEMPLATE =
+  "export: {{date}} ({{notes_changed}} note{{plural}})";
+
+// ---------------------------------------------------------------------------
+// Git shell helpers (Bun.spawn — no new dep)
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true if `dir` is inside a git working tree.
+ *
+ * Implementation: `git rev-parse --is-inside-work-tree`, exit code 0 = yes.
+ * No reliance on `.git/` existing as a directory (handles worktrees + bare
+ * submodule layouts uniformly).
+ */
+export async function isGitRepo(dir: string): Promise<boolean> {
+  const proc = Bun.spawn(["git", "rev-parse", "--is-inside-work-tree"], {
+    cwd: dir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  return exitCode === 0;
+}
+
+/** List the paths git currently has staged (cached). One per line. */
+export async function listStagedFiles(repoDir: string): Promise<string[]> {
+  const proc = Bun.spawn(["git", "diff", "--cached", "--name-only"], {
+    cwd: repoDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  await proc.exited;
+  const out = new TextDecoder().decode(await new Response(proc.stdout).arrayBuffer());
+  return out
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+}
+
+/** Run `git add -A` in `repoDir`. Returns true on success. */
+export async function gitAddAll(repoDir: string): Promise<{ ok: boolean; stderr: string }> {
+  const proc = Bun.spawn(["git", "add", "-A"], {
+    cwd: repoDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  const stderr = new TextDecoder().decode(await new Response(proc.stderr).arrayBuffer());
+  return { ok: exitCode === 0, stderr: stderr.trim() };
+}
+
+/** Run `git commit -m <message>` in `repoDir`. Returns true on success. */
+export async function gitCommit(
+  repoDir: string,
+  message: string,
+): Promise<{ ok: boolean; stderr: string }> {
+  const proc = Bun.spawn(["git", "commit", "-m", message], {
+    cwd: repoDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  const stderr = new TextDecoder().decode(await new Response(proc.stderr).arrayBuffer());
+  return { ok: exitCode === 0, stderr: stderr.trim() };
+}
+
+/** Run `git push` in `repoDir`. Returns true on success. */
+export async function gitPush(
+  repoDir: string,
+): Promise<{ ok: boolean; stderr: string }> {
+  const proc = Bun.spawn(["git", "push"], {
+    cwd: repoDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  const stderr = new TextDecoder().decode(await new Response(proc.stderr).arrayBuffer());
+  return { ok: exitCode === 0, stderr: stderr.trim() };
+}
+
+/**
+ * Unstage everything in `repoDir` (no-op if nothing staged).
+ *
+ * Uses bare `git reset` (no `HEAD`, no path args) so the call works on a
+ * fresh repo with no commits yet — an operator who runs `--git-commit`
+ * against a `git init`'d empty repo and lands in the `.parachute/`-only
+ * skip path on the first cycle would otherwise leave staging dirty.
+ * Both `git reset HEAD -- .` and `git restore --staged .` require a
+ * resolvable HEAD; bare `git reset` falls back cleanly when none exists.
+ * See vault#346 reviewer note.
+ */
+export async function gitUnstageAll(repoDir: string): Promise<void> {
+  const proc = Bun.spawn(["git", "reset"], {
+    cwd: repoDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  await proc.exited;
+}
+
+// ---------------------------------------------------------------------------
+// Cycle-level helpers: commit-or-skip decision + execution
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide whether the currently-staged set warrants a commit, given the
+ * `notes_changed` reported by the export cycle.
+ *
+ * Skip rules:
+ *   - Empty staging → skip (nothing to commit).
+ *   - `notes_changed === 0` AND every staged path lives under `.parachute/`
+ *     → skip. This filters the pure `vault.yaml` `exported_at` churn that
+ *     would otherwise produce a commit per watch interval forever.
+ *
+ * Otherwise → commit.
+ *
+ * Note: a vault rename (vault.yaml `name` field changes) also follows the
+ * skip path. Metadata-only changes don't commit by design — the operator
+ * who renames a vault and wants that in the git mirror history can either
+ * touch a note or run a one-shot `git commit --allow-empty -m "rename vault"`
+ * by hand.
+ */
+export function shouldCommit(stagedFiles: string[], notesChanged: number): {
+  commit: boolean;
+  reason: "ok" | "empty" | "parachute_meta_only";
+} {
+  if (stagedFiles.length === 0) return { commit: false, reason: "empty" };
+  if (notesChanged === 0 && stagedFiles.every((f) => f.startsWith(".parachute/"))) {
+    return { commit: false, reason: "parachute_meta_only" };
+  }
+  return { commit: true, reason: "ok" };
+}
+
+/**
+ * Stage → decide → commit → optionally push. Logs status to stdout/stderr.
+ * Returns whether a commit landed.
+ */
+export async function runGitCommitCycle(opts: {
+  repoDir: string;
+  template: string;
+  notesChanged: number;
+  vaultName: string;
+  firstNoteTitle: string;
+  push: boolean;
+  /** Override for tests — defaults to `new Date().toISOString()`. */
+  now?: () => string;
+}): Promise<{ committed: boolean; message?: string }> {
+  const now = opts.now ?? (() => new Date().toISOString());
+
+  const add = await gitAddAll(opts.repoDir);
+  if (!add.ok) {
+    console.error(`[git-commit] git add failed: ${add.stderr}`);
+    return { committed: false };
+  }
+
+  const staged = await listStagedFiles(opts.repoDir);
+  const decision = shouldCommit(staged, opts.notesChanged);
+  if (!decision.commit) {
+    if (decision.reason === "empty") {
+      console.log(`[git-commit] no changes; skipping commit`);
+    } else if (decision.reason === "parachute_meta_only") {
+      // Unstage so the next cycle starts clean and the operator's
+      // `git status` reflects the skip-decision.
+      await gitUnstageAll(opts.repoDir);
+      console.log(
+        `[git-commit] no note changes (only .parachute/ metadata); skipping commit`,
+      );
+    }
+    return { committed: false };
+  }
+
+  const message = renderCommitMessage(opts.template, {
+    date: now(),
+    notes_changed: opts.notesChanged,
+    first_note_title: opts.firstNoteTitle,
+    vault_name: opts.vaultName,
+  });
+
+  const commit = await gitCommit(opts.repoDir, message);
+  if (!commit.ok) {
+    console.error(`[git-commit] git commit failed: ${commit.stderr}`);
+    return { committed: false };
+  }
+  console.log(`[git-commit] ${message}`);
+
+  if (opts.push) {
+    const pushResult = await gitPush(opts.repoDir);
+    if (!pushResult.ok) {
+      // Non-fatal — a network blip shouldn't kill a watch loop. Warn and
+      // move on; the next successful commit's push will catch up history.
+      console.warn(`[git-commit] git push failed (non-fatal): ${pushResult.stderr}`);
+    } else {
+      console.log(`[git-commit] pushed`);
+    }
+  }
+
+  return { committed: true, message };
+}

package/src/mcp-config.test.ts

@@ -0,0 +1,260 @@
+/**
+ * Tests for `parachute-vault mcp-config <vault-name>` — the JSON synthesizer
+ * for `claude -p --mcp-config '<json>'` runners. Three concerns:
+ *
+ *   1. Pure helper: `buildMcpConfigJson` — shape correctness for both literal
+ *      and `--env-vars` template modes.
+ *   2. CLI flag parsing: required vault arg, --token / PARACHUTE_VAULT_TOKEN
+ *      precedence, --base-url override, --env-vars short-circuit (no vault
+ *      lookup, no bearer required).
+ *   3. End-to-end stdout — verify pipe-to-jq usability (valid JSON, exact
+ *      shape claude consumes).
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { buildMcpConfigJson } from "./mcp-install.ts";
+
+const CLI = path.resolve(import.meta.dir, "cli.ts");
+
+function runCli(
+  args: string[],
+  parachuteHome: string,
+  extraEnv: Record<string, string | undefined> = {},
+  cwd?: string,
+): { exitCode: number; stdout: string; stderr: string } {
+  const proc = Bun.spawnSync({
+    cmd: ["bun", CLI, ...args],
+    cwd: cwd ?? parachuteHome,
+    env: {
+      ...process.env,
+      PARACHUTE_HOME: parachuteHome,
+      HOME: parachuteHome,
+      ...extraEnv,
+    },
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  return {
+    exitCode: proc.exitCode ?? -1,
+    stdout: new TextDecoder().decode(proc.stdout),
+    stderr: new TextDecoder().decode(proc.stderr),
+  };
+}
+
+function setupBareVault(parachuteHome: string, name: string): void {
+  const vaultsDir = path.join(parachuteHome, "vault", "data");
+  fs.mkdirSync(path.join(vaultsDir, name), { recursive: true });
+  fs.writeFileSync(
+    path.join(vaultsDir, name, "vault.yaml"),
+    `name: ${name}\napi_keys: []\n`,
+  );
+  const globalPath = path.join(parachuteHome, "vault", "config.yaml");
+  if (!fs.existsSync(globalPath)) {
+    fs.mkdirSync(path.dirname(globalPath), { recursive: true });
+    fs.writeFileSync(globalPath, `default_vault: ${name}\nport: 1940\n`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Unit: buildMcpConfigJson
+// ---------------------------------------------------------------------------
+
+describe("buildMcpConfigJson", () => {
+  test("literal mode embeds the bearer and URL verbatim", () => {
+    const json = buildMcpConfigJson({
+      vaultName: "gitcoin",
+      baseUrl: "http://127.0.0.1:1940",
+      bearer: "pvt_abc123",
+    });
+    const parsed = JSON.parse(json);
+    expect(parsed.mcpServers["parachute-vault-gitcoin"]).toEqual({
+      type: "http",
+      url: "http://127.0.0.1:1940/vault/gitcoin/mcp",
+      headers: { Authorization: "Bearer pvt_abc123" },
+    });
+  });
+
+  test("env-var mode emits placeholders that survive JSON parsing", () => {
+    const json = buildMcpConfigJson({
+      vaultName: "gitcoin",
+      baseUrl: "",
+      bearer: "",
+      useEnvVars: true,
+    });
+    // The placeholders must come through verbatim — `${...}` is a normal
+    // string value to JSON, and that's what shell expansion later acts on.
+    const parsed = JSON.parse(json);
+    expect(parsed.mcpServers["parachute-vault-gitcoin"].url).toBe(
+      "${PARACHUTE_HUB_URL}/vault/gitcoin/mcp",
+    );
+    expect(parsed.mcpServers["parachute-vault-gitcoin"].headers.Authorization).toBe(
+      "Bearer ${PARACHUTE_VAULT_TOKEN}",
+    );
+  });
+
+  test("strips trailing slash from baseUrl (no double slashes in the path)", () => {
+    const json = buildMcpConfigJson({
+      vaultName: "default",
+      baseUrl: "https://hub.example.com/",
+      bearer: "t",
+    });
+    const parsed = JSON.parse(json);
+    expect(parsed.mcpServers["parachute-vault-default"].url).toBe(
+      "https://hub.example.com/vault/default/mcp",
+    );
+  });
+
+  test("entry key always uses parachute-vault-<name> (multi-vault-ready)", () => {
+    const json = buildMcpConfigJson({
+      vaultName: "work",
+      baseUrl: "http://127.0.0.1:1940",
+      bearer: "t",
+    });
+    const parsed = JSON.parse(json);
+    expect(Object.keys(parsed.mcpServers)).toEqual(["parachute-vault-work"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// CLI end-to-end
+// ---------------------------------------------------------------------------
+
+describe("mcp-config CLI", () => {
+  let tmp: string;
+  beforeEach(() => {
+    tmp = fs.mkdtempSync(path.join(os.tmpdir(), "vault-mcp-config-"));
+  });
+  afterEach(() => {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  });
+
+  test("emits well-formed JSON to stdout with --token", () => {
+    setupBareVault(tmp, "gitcoin");
+    const res = runCli(
+      ["mcp-config", "gitcoin", "--token", "pvt_test123"],
+      tmp,
+    );
+    expect(res.exitCode).toBe(0);
+    const parsed = JSON.parse(res.stdout);
+    expect(parsed.mcpServers["parachute-vault-gitcoin"].type).toBe("http");
+    expect(parsed.mcpServers["parachute-vault-gitcoin"].headers.Authorization).toBe(
+      "Bearer pvt_test123",
+    );
+    expect(parsed.mcpServers["parachute-vault-gitcoin"].url).toContain(
+      "/vault/gitcoin/mcp",
+    );
+  });
+
+  test("reads PARACHUTE_VAULT_TOKEN env var when --token absent", () => {
+    setupBareVault(tmp, "gitcoin");
+    const res = runCli(
+      ["mcp-config", "gitcoin"],
+      tmp,
+      { PARACHUTE_VAULT_TOKEN: "pvt_envvar" },
+    );
+    expect(res.exitCode).toBe(0);
+    const parsed = JSON.parse(res.stdout);
+    expect(parsed.mcpServers["parachute-vault-gitcoin"].headers.Authorization).toBe(
+      "Bearer pvt_envvar",
+    );
+  });
+
+  test("--token wins over PARACHUTE_VAULT_TOKEN when both are present", () => {
+    setupBareVault(tmp, "gitcoin");
+    const res = runCli(
+      ["mcp-config", "gitcoin", "--token", "from-flag"],
+      tmp,
+      { PARACHUTE_VAULT_TOKEN: "from-env" },
+    );
+    expect(res.exitCode).toBe(0);
+    const parsed = JSON.parse(res.stdout);
+    expect(parsed.mcpServers["parachute-vault-gitcoin"].headers.Authorization).toBe(
+      "Bearer from-flag",
+    );
+  });
+
+  test("exits 1 with a clear error when no token is supplied", () => {
+    setupBareVault(tmp, "gitcoin");
+    // Explicitly unset PARACHUTE_VAULT_TOKEN (test env may have it).
+    const res = runCli(
+      ["mcp-config", "gitcoin"],
+      tmp,
+      { PARACHUTE_VAULT_TOKEN: "" },
+    );
+    expect(res.exitCode).toBe(1);
+    expect(res.stderr).toMatch(/No bearer token/);
+    expect(res.stderr).toMatch(/--token/);
+    expect(res.stderr).toMatch(/PARACHUTE_VAULT_TOKEN/);
+    // The error message points operators at the workaround paths so they
+    // can recover without re-reading the docs.
+    expect(res.stderr).toMatch(/parachute-vault tokens create/);
+    expect(res.stderr).toMatch(/--env-vars/);
+  });
+
+  test("exits 1 when the vault doesn't exist (literal mode)", () => {
+    setupBareVault(tmp, "default");
+    const res = runCli(
+      ["mcp-config", "ghost", "--token", "t"],
+      tmp,
+    );
+    expect(res.exitCode).toBe(1);
+    expect(res.stderr).toMatch(/Vault "ghost" not found/);
+  });
+
+  test("--env-vars short-circuits — no vault lookup, no token required", () => {
+    // Deliberately no setupBareVault: --env-vars mode emits the template
+    // shape without resolving anything. Operators commit the template from
+    // machines that may not have the target vault.
+    const res = runCli(
+      ["mcp-config", "gitcoin", "--env-vars"],
+      tmp,
+      { PARACHUTE_VAULT_TOKEN: "" },
+    );
+    expect(res.exitCode).toBe(0);
+    const parsed = JSON.parse(res.stdout);
+    expect(parsed.mcpServers["parachute-vault-gitcoin"].url).toBe(
+      "${PARACHUTE_HUB_URL}/vault/gitcoin/mcp",
+    );
+    expect(parsed.mcpServers["parachute-vault-gitcoin"].headers.Authorization).toBe(
+      "Bearer ${PARACHUTE_VAULT_TOKEN}",
+    );
+  });
+
+  test("--base-url overrides the auto-detected origin", () => {
+    setupBareVault(tmp, "gitcoin");
+    const res = runCli(
+      [
+        "mcp-config",
+        "gitcoin",
+        "--token",
+        "t",
+        "--base-url",
+        "https://hub.taildf9ce2.ts.net",
+      ],
+      tmp,
+    );
+    expect(res.exitCode).toBe(0);
+    const parsed = JSON.parse(res.stdout);
+    expect(parsed.mcpServers["parachute-vault-gitcoin"].url).toBe(
+      "https://hub.taildf9ce2.ts.net/vault/gitcoin/mcp",
+    );
+  });
+
+  test("missing vault-name arg prints usage and exits 1", () => {
+    const res = runCli(["mcp-config"], tmp);
+    expect(res.exitCode).toBe(1);
+    expect(res.stderr).toMatch(/Usage:/);
+    expect(res.stderr).toMatch(/mcp-config <vault-name>/);
+  });
+
+  test("flag passed in place of vault-name (e.g. --help) is rejected", () => {
+    // Guards against `parachute-vault mcp-config --token foo` being
+    // silently misparsed as vault-name="--token".
+    const res = runCli(["mcp-config", "--help"], tmp);
+    expect(res.exitCode).toBe(1);
+    expect(res.stderr).toMatch(/Usage:/);
+  });
+});

package/src/mcp-install.test.ts

@@ -580,6 +580,10 @@ describe("mcp-install end-to-end", () => {
     // scoped to this directory (and how to widen if they wanted global).
     expect(res.stdout).toMatch(/this directory only/);
     expect(res.stdout).toMatch(/--install-scope user/);
+    // Headless-flow heads-up: local-scope entries don't propagate to
+    // claude -p subprocesses; operators wiring up runners need to know.
+    expect(res.stdout).toMatch(/Headless flows/);
+    expect(res.stdout).toMatch(/claude -p/);
   });
 
   test("--install-scope project writes <cwd>/.mcp.json instead of ~/.claude.json", () => {
@@ -798,6 +802,62 @@ describe("mcp-install end-to-end", () => {
     expect(bearer).toMatch(/^Bearer pvt_/);
   });
 
+  test("--dry-run describes the write without touching disk or hitting the hub", () => {
+    // Aaron hit this when probing `mcp-install --help`: the bare CLI
+    // dispatch was creating an empty `projects[<cwd>]` slot in
+    // ~/.claude.json as a side effect of writing the install. --dry-run
+    // is the deliberate "tell me what you'd do" path.
+    setupBareVault(tmp, "default");
+    const res = runCli(
+      ["mcp-install", "--install-scope", "user", "--token", "should-not-be-used", "--dry-run"],
+      tmp,
+    );
+    expect(res.exitCode).toBe(0);
+    // No claude.json should exist: the install was inhibited.
+    expect(fs.existsSync(path.join(tmp, ".claude.json"))).toBe(false);
+    // The dry-run output names target file, entry key, URL, and how to apply.
+    expect(res.stdout).toMatch(/\[dry-run\]/);
+    expect(res.stdout).toMatch(/Target file:/);
+    expect(res.stdout).toMatch(/Entry key:\s+parachute-vault/);
+    expect(res.stdout).toMatch(/MCP URL:/);
+    expect(res.stdout).toMatch(/Re-run without --dry-run to apply\./);
+  });
+
+  test("--dry-run works for a vault that doesn't exist yet (probe shape)", () => {
+    // The dry-run contract is "no side effects, including failures on
+    // state the caller is asking about." A future-vault probe — would
+    // installing for this not-yet-created vault land where I expect? —
+    // is a legitimate pre-create check, not an error. The
+    // vault-existence guard runs only on the real-install path.
+    setupBareVault(tmp, "default");
+    const res = runCli(
+      ["mcp-install", "--vault", "future-vault", "--token", "t", "--dry-run"],
+      tmp,
+    );
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toMatch(/\[dry-run\]/);
+    // Output names the absent vault explicitly so the operator can tell
+    // the dry-run worked against the right target.
+    expect(res.stdout).toMatch(/Vault:\s+future-vault/);
+    expect(res.stdout).toMatch(/does not exist yet/);
+    expect(res.stdout).toMatch(/Entry key:\s+parachute-vault-future-vault/);
+    // No claude.json written — dry-run still didn't touch disk.
+    expect(fs.existsSync(path.join(tmp, ".claude.json"))).toBe(false);
+  });
+
+  test("--dry-run with --mint skips the hub round-trip and operator-token check", () => {
+    // The whole point of --dry-run is "no side effects" — that includes
+    // the hub-mint network call. A naive implementation might still try
+    // to read operator.token and fail before the dry-run print fires.
+    setupBareVault(tmp, "default");
+    // Deliberately no operator.token file present, no PARACHUTE_HUB_ORIGIN.
+    const res = runCli(["mcp-install", "--dry-run"], tmp, { PARACHUTE_HUB_ORIGIN: "" });
+    expect(res.exitCode).toBe(0);
+    expect(res.stdout).toMatch(/\[dry-run\]/);
+    expect(res.stderr).not.toMatch(/No operator token found/);
+    expect(res.stderr).not.toMatch(/No hub origin configured/);
+  });
+
   test("subsequent --token install on top of an existing entry overwrites the bearer (user scope)", () => {
     setupBareVault(tmp, "default");
     runCli(["mcp-install", "--install-scope", "user", "--token", "first"], tmp);

package/src/mcp-install.ts

@@ -334,6 +334,67 @@ export async function mintHubJwt(opts: MintHubJwtOpts): Promise<MintedHubJwt | M
   };
 }
 
+// ---------------------------------------------------------------------------
+// `mcp-config` — emit the JSON shape `claude -p --mcp-config '<json>'` expects
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the JSON config shape consumed by `claude -p --mcp-config '<json>'`.
+ *
+ * Two emission modes:
+ *
+ *   - **literal** (`useEnvVars: false`): the URL and bearer are inlined. The
+ *     emitted JSON is ready to splice into a runner via shell substitution
+ *     (`--mcp-config "$(parachute-vault mcp-config <name>)"`). Treat the
+ *     output as secret — it carries a usable bearer.
+ *
+ *   - **env-var template** (`useEnvVars: true`): the URL becomes
+ *     `${PARACHUTE_HUB_URL}/vault/<name>/mcp` and the Authorization value
+ *     becomes `Bearer ${PARACHUTE_VAULT_TOKEN}`. Shape-only; safe to commit.
+ *     Consumers must expand the placeholders at runtime (most shells do this
+ *     under double-quoted interpolation; `claude -p` itself does not).
+ *
+ * The `entryKey` rule mirrors `buildMcpEntryPlan`: vault-explicit installs
+ * key as `parachute-vault-<name>` so multi-vault runners can mount more than
+ * one vault under distinct slots. (The default install — singular
+ * `parachute-vault` — is reserved for the local-scope MCP entry; `mcp-config`
+ * always pins the per-vault key, since this is the script-spawning shape
+ * where you usually do name the vault.)
+ *
+ * Always emits stable JSON with two-space indent so the output is diff-able
+ * across runs.
+ */
+export interface BuildMcpConfigJsonOpts {
+  vaultName: string;
+  /** Base URL (without `/vault/<name>/mcp`). Ignored when `useEnvVars` is true. */
+  baseUrl: string;
+  /** Bearer to embed verbatim. Ignored when `useEnvVars` is true. */
+  bearer: string;
+  /** Emit `${PARACHUTE_HUB_URL}` / `${PARACHUTE_VAULT_TOKEN}` placeholders instead of inlined values. */
+  useEnvVars?: boolean;
+}
+
+export function buildMcpConfigJson(opts: BuildMcpConfigJsonOpts): string {
+  const { vaultName, baseUrl, bearer, useEnvVars } = opts;
+  const entryKey = `parachute-vault-${vaultName}`;
+  const url = useEnvVars
+    ? `\${PARACHUTE_HUB_URL}/vault/${vaultName}/mcp`
+    : `${baseUrl.replace(/\/$/, "")}/vault/${vaultName}/mcp`;
+  const authValue = useEnvVars
+    ? "Bearer ${PARACHUTE_VAULT_TOKEN}"
+    : `Bearer ${bearer}`;
+  const config = {
+    mcpServers: {
+      [entryKey]: {
+        type: "http",
+        url,
+        headers: { Authorization: authValue },
+      },
+    },
+  };
+  return JSON.stringify(config, null, 2);
+}
+
 // ---------------------------------------------------------------------------
 // Install target resolver
 // ---------------------------------------------------------------------------