@openparachute/vault 0.6.4-rc.5 → 0.6.4-rc.6

package/package.json

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

package/src/import-daemon-busy.test.ts

@@ -15,30 +15,21 @@ import { resolve } from "path";
 import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
+import { runSubprocess } from "./test-support/spawn.ts";
 
 const CLI = resolve(import.meta.dir, "cli.ts");
 
+// Async spawn — the daemon-busy probe inside the CLI fetches the test
+// process's stub server, so the parent event loop must keep servicing
+// requests while the child runs. `Bun.spawnSync` blocks the event loop and
+// the in-test server can't answer, which makes every probe time out into
+// the "not listening" branch (vault#324). `runSubprocess` is the shared
+// safe primitive (vault#325 Part 1) — see src/test-support/spawn.ts.
 async function runCli(
   args: string[],
   env: Record<string, string>,
 ): Promise<{ exitCode: number; stdout: string; stderr: string }> {
-  // Async spawn — the daemon-busy probe inside the CLI fetches the test
-  // process's stub server, so the parent event loop must keep servicing
-  // requests while the child runs. Bun.spawnSync blocks the event loop
-  // and the in-test server can't answer, which makes every probe time
-  // out into the "not listening" branch.
-  const proc = Bun.spawn({
-    cmd: ["bun", CLI, ...args],
-    stdout: "pipe",
-    stderr: "pipe",
-    env: { ...process.env, ...env },
-  });
-  const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
-  ]);
-  return { exitCode: exitCode ?? -1, stdout, stderr };
+  return runSubprocess({ cmd: ["bun", CLI, ...args], env });
 }
 
 let home: string;

package/src/scale.bench.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Opt-in scale smoke (vault#325 Part 3).
+ *
+ * Guards the synthetic scale harness against bit-rot WITHOUT slowing the
+ * default `bun test` gate. The real benchmark lives in
+ * `scripts/scale-bench.ts` (10k / 50k / 100k); this is a fast, tiny-size
+ * functional smoke of the same hot-path code so a green CI run still
+ * proves the harness paths execute end-to-end.
+ *
+ * SKIPPED BY DEFAULT. To run it:
+ *
+ *   VAULT_SCALE_BENCH=1 bun test ./src/scale.bench.test.ts
+ *
+ * For real timings + the documented ceiling, run the standalone harness:
+ *
+ *   bun scripts/scale-bench.ts          # 10000 50000 100000
+ *
+ * See docs/SCALE.md.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunSqliteStore } from "../core/src/store.ts";
+import { generateMcpTools } from "../core/src/mcp.ts";
+import { exportVaultToDir } from "../core/src/portable-md.ts";
+import type { BulkNoteInput } from "../core/src/notes.ts";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+const ENABLED = process.env.VAULT_SCALE_BENCH === "1";
+
+// `describe.skipIf` keeps the suite registered (so it shows in the test list)
+// but contributes zero runtime to the default gate. Size is intentionally
+// tiny — this is a functional smoke, not a timing run.
+describe.skipIf(!ENABLED)("scale harness smoke (opt-in: VAULT_SCALE_BENCH=1)", () => {
+  test("seed + hot-path queries + export run at small N", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "vault-scale-smoke-"));
+    const db = new Database(join(dir, "smoke.db"));
+    const store = new BunSqliteStore(db);
+    try {
+      const N = 500;
+
+      // Declare the indexed field via the update-tag tool (the owner of the
+      // indexed_fields lifecycle — mirrors scripts/scale-bench.ts).
+      const tools = generateMcpTools(store);
+      const updateTag = tools.find((t) => t.name === "update-tag");
+      expect(updateTag).toBeDefined();
+      await updateTag!.execute({
+        tag: "work",
+        fields: { status: { type: "string", indexed: true } },
+      });
+
+      const inputs: BulkNoteInput[] = Array.from({ length: N }, (_, i) => ({
+        id: `note-${i}`,
+        path: `notes/note-${i}`,
+        content: `# Note ${i}\n\nconsectetur body ${i}`,
+        tags: i % 3 === 0 ? ["work", "work/meeting"] : ["health"],
+        metadata: { status: i % 2 === 0 ? "active" : "done", seq: i },
+      }));
+      await store.createNotes(inputs);
+
+      // Hot paths — same shapes the standalone harness times.
+      expect((await store.queryNotes({ tags: ["health"], limit: 50 })).length).toBeGreaterThan(0);
+      expect(
+        (await store.queryNotes({ metadata: { status: { eq: "active" } }, limit: 50 })).length,
+      ).toBeGreaterThan(0);
+      expect((await store.queryNotes({ orderBy: "status", limit: 50 })).length).toBe(50);
+      expect((await store.searchNotes("consectetur", { limit: 50 })).length).toBeGreaterThan(0);
+
+      const stats = await exportVaultToDir(store, {
+        outDir: join(dir, "export"),
+        vaultName: "smoke",
+        exportedAt: "2026-01-01T00:00:00Z",
+      });
+      expect(stats.notes).toBe(N);
+    } finally {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/test-support/spawn.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared subprocess helper for tests (vault#325 Part 1).
+ *
+ * THE RULE — never `Bun.spawnSync` in a test that keeps an in-process
+ * `Bun.serve` listening for the child to probe.
+ *
+ * `Bun.spawnSync` blocks the parent's event loop until the child exits.
+ * If the child makes an HTTP request back to a server the *same test
+ * process* is hosting (e.g. the CLI's daemon-busy pre-flight fetching a
+ * stub `/health`), the parent can't answer — the child's request times
+ * out into the "nothing listening" branch and the assertion silently
+ * tests the wrong path (the guard never fires, or fails for a non-obvious
+ * reason). This bit the daemon-busy import guard; the fix landed in
+ * vault#324 (`src/import-daemon-busy.test.ts`) and this helper is the
+ * institutional-memory follow-up so future subprocess tests reach for the
+ * safe primitive by default.
+ *
+ * `runSubprocess` uses async `Bun.spawn` + `await proc.exited`, so the
+ * parent's event loop keeps servicing requests while the child runs.
+ *
+ * NOTE on what's *fine*: `Bun.spawnSync` is safe in tests that don't run
+ * an in-test server the child talks to over HTTP — e.g. shelling out to
+ * `git` to build a fixture repo (`mirror-*.test.ts`), or a `Bun.serve`
+ * that merely *holds a port* so the child's `lsof`/availability probe
+ * sees it occupied (`doctor.test.ts`). The deadlock is specifically
+ * "child fetches the parent test process's server." When in doubt, use
+ * this helper — it's never wrong, only sometimes unnecessary.
+ */
+
+export interface RunSubprocessResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface RunSubprocessOptions {
+  cmd: string[];
+  cwd?: string;
+  /** Extra env merged over `process.env`. `undefined` values delete the key. */
+  env?: Record<string, string | undefined>;
+  /** Optional bytes piped to the child's stdin. */
+  stdin?: string;
+}
+
+/**
+ * Run a subprocess WITHOUT blocking the event loop.
+ *
+ * Drop-in for the `Bun.spawnSync({ cmd, env, stdout, stderr })` pattern
+ * that recurs across the CLI integration tests, but built on async
+ * `Bun.spawn` so an in-process `Bun.serve` the child probes can still
+ * answer. Returns once the child has exited, with decoded stdout/stderr.
+ */
+export async function runSubprocess(
+  opts: RunSubprocessOptions,
+): Promise<RunSubprocessResult> {
+  const env: Record<string, string> = { ...(process.env as Record<string, string>) };
+  if (opts.env) {
+    for (const [k, v] of Object.entries(opts.env)) {
+      if (v === undefined) delete env[k];
+      else env[k] = v;
+    }
+  }
+
+  const proc = Bun.spawn({
+    cmd: opts.cmd,
+    cwd: opts.cwd,
+    env,
+    stdin: opts.stdin === undefined ? undefined : "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (opts.stdin !== undefined) {
+    proc.stdin!.write(opts.stdin);
+    await proc.stdin!.end();
+  }
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  return { exitCode: exitCode ?? -1, stdout, stderr };
+}

package/src/vault.test.ts

@@ -1393,6 +1393,99 @@ describe("scoped MCP wrapper", async () => {
     closeAllStores();
   });
 
+  // -- Q6 through the MCP TRANSPORT (vault#325 Part 2) --------------------
+  //
+  // The two tests above call `tool.execute()` directly — that exercises the
+  // tag-scope WRAPPER but bypasses `handleScopedMcp`: the JSON-RPC transport,
+  // the `hasScopeForVault` tool-visibility gate, and the tools/call dispatch.
+  // The HTTP-layer twin lives in `routing.test.ts` (Q6 read-path). What was
+  // missing — and what this pins — is the orphan-sub-tag fail-open driven
+  // through the actual MCP `tools/call` path a real client hits. Same fixture
+  // as the HTTP test (`#health/food` with no `_tags/health/food` schema,
+  // token allowlisted for `health`), different transport.
+
+  test("MCP query-notes (tools/call) sees orphan sub-tag via string-form root (vault#325 Part 2)", async () => {
+    const { handleScopedMcp } = await import("./mcp-http.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `mcp-orphan-query-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    // No `_tags/health/food` schema — this is the orphan case. The hierarchy
+    // is implicit, so authorization must fall back to the string-form root.
+    const orphan = await store.createNote("orphan", { tags: ["health/food"] });
+
+    const auth = {
+      permission: "read" as const,
+      scopes: ["vault:read"],
+      legacyDerived: false,
+      scoped_tags: ["health"],
+    };
+
+    // The URL is inert here — handleScopedMcp hands it to the SDK
+    // transport, which only reads the body; the `vaultName` route wiring
+    // is exercised by routing.test.ts, not this transport-level test. The
+    // `accept` header is load-bearing: `enableJsonResponse` returns JSON
+    // only when text/event-stream is also acceptable, else it streams SSE.
+    const callReq = (id: number, name: string, args: Record<string, unknown>) =>
+      new Request(`http://localhost:1940/vault/${vaultName}/mcp`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json, text/event-stream",
+        },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id,
+          method: "tools/call",
+          params: { name, arguments: args },
+        }),
+      });
+
+    // Fetch the orphan by id through the MCP transport with a token scoped
+    // to ["health"]. The orphan is tagged `health/food` (no schema) → the
+    // string-form fallback resolves the root `health` → in allowlist → the
+    // note must come back rather than 404/forbidden.
+    const res = await handleScopedMcp(callReq(1, "query-notes", { id: orphan.id }), vaultName, auth as any);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as any;
+    // tools/call returns content[].text with the JSON-stringified tool result.
+    expect(body.result?.isError).toBeFalsy();
+    const text: string = body.result.content[0].text;
+    const parsed = JSON.parse(text);
+    expect(parsed.id).toBe(orphan.id);
+    expect(parsed.tags).toContain("health/food");
+
+    // Control: a token scoped to a DIFFERENT root must NOT see the orphan
+    // through the same transport — proves the green result above is the
+    // fail-open fallback firing, not scoping being inert.
+    const denied = {
+      permission: "read" as const,
+      scopes: ["vault:read"],
+      legacyDerived: false,
+      scoped_tags: ["work"],
+    };
+    const resDenied = await handleScopedMcp(
+      callReq(2, "query-notes", { id: orphan.id }),
+      vaultName,
+      denied as any,
+    );
+    expect(resDenied.status).toBe(200);
+    const deniedBody = (await resDenied.json()) as any;
+    const deniedText: string = deniedBody.result.content[0].text;
+    const deniedParsed = JSON.parse(deniedText);
+    // Out-of-scope single-note fetch fails closed: the wrapper replaces the
+    // note body with `{ error: "Note not found" }` (no content/tags leak).
+    // This proves the `health`-scoped green result above is the fail-open
+    // string-form fallback firing, not the wrapper being a no-op.
+    expect(deniedParsed.error).toBe("Note not found");
+    expect(deniedParsed.content).toBeUndefined();
+    expect(deniedParsed.tags).toBeUndefined();
+
+    closeAllStores();
+  });
+
   // -- Q5: MCP delete-tag dependency check -------------------------------
 
   test("MCP delete-tag returns tag_in_use_by_tokens when a vestigial tag-scoped token row references the tag", async () => {