@openparachute/vault 0.3.3 → 0.4.3

package/core/src/vault-projection.ts

@@ -0,0 +1,309 @@
+/**
+ * Vault projection — computes a comprehensive description of the vault
+ * (tags-with-schemas + effective inheritance + indexed-field catalog +
+ * query hints) shared by two consumers:
+ *
+ *   - `vault-info` MCP tool — returns the full projection as a JSON object
+ *     so an agent can request a refresh mid-session.
+ *   - `getServerInstruction` (MCP `initialize` response) — renders the
+ *     same projection as a terse markdown brief sent once at connect.
+ *
+ * The projection lives outside the per-note path: it describes what kinds
+ * of notes and queries are available, not the contents. Nothing here
+ * depends on auth/scopes — both consumers compose this with vault config
+ * (name/description) and any policy-driven framing on top.
+ *
+ * See vault#271 for design notes.
+ */
+
+import { Database } from "bun:sqlite";
+import {
+  loadSchemaConfig,
+  resolveNoteSchemas,
+  walkAncestors,
+  type ResolvedSchemas,
+  type SchemaField,
+} from "./schema-defaults.ts";
+import { listIndexedFields } from "./indexed-fields.ts";
+import {
+  listTagRecords,
+  type TagFieldSchema,
+  type TagRecord,
+} from "./tag-schemas.ts";
+import { DEFAULT_TAG_NAME } from "./tag-hierarchy.ts";
+import * as noteOps from "./notes.ts";
+import type { VaultStats } from "./types.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface ProjectionTag {
+  name: string;
+  description: string | null;
+  /** Direct parents declared in `tags.parent_names` (verbatim, no walk). */
+  parents: string[];
+  /**
+   * Walk-order ancestor closure (parents → grandparents → …) including the
+   * implicit `_default` universal parent when present, with the tag itself
+   * excluded. Empty when the tag has no parents and no `_default` exists.
+   */
+  effective_parents: string[];
+  /**
+   * Own field declarations (verbatim from `tags.fields`). Carries the full
+   * `TagFieldSchema` shape — `type` (string), optional `description`,
+   * `enum`, `indexed`. Width matches the on-disk row.
+   */
+  fields: Record<string, TagFieldSchema> | null;
+  /**
+   * Merged field map = own ∪ inherited (first-in-walk wins, matching
+   * `resolveNoteSchemas`). Uses the `SchemaField` view returned by the
+   * resolver (narrower `type` enum). Empty when no ancestor — including
+   * the tag itself — declared anything.
+   */
+  effective_fields: Record<string, SchemaField>;
+  relationships: TagRecord["relationships"] | null;
+}
+
+export interface ProjectionIndexedField {
+  name: string;
+  /** User-facing field type ("string" | "integer" | "boolean") drawn from the first declarer. */
+  type: string;
+  tags: string[];
+}
+
+export interface VaultProjection {
+  tags: ProjectionTag[];
+  indexed_fields: ProjectionIndexedField[];
+  query_hints: string[];
+  /** Included when the caller requests stats; omitted otherwise. */
+  stats?: VaultStats;
+}
+
+// ---------------------------------------------------------------------------
+// Inheritance helpers (built on the #272 resolver)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a single tag's effective inheritance.
+ *
+ * Built on top of `resolveNoteSchemas({ tags: [tag] })` so the walk order
+ * and conflict precedence match the runtime validator exactly. Returns:
+ *
+ *   - `effective_parents`: walk-order ancestor list with the tag itself
+ *     excluded. Includes `_default` when a `_default` row exists, regardless
+ *     of whether the tag declares it (universal-parent semantics).
+ *   - `effective_fields`: merged field map (first-in-walk wins). When no
+ *     ancestor contributes, this equals the tag's own `fields`.
+ */
+export function resolveTagInheritance(
+  resolved: ResolvedSchemas,
+  tag: string,
+): { effective_parents: string[]; effective_fields: Record<string, SchemaField> } {
+  const resolution = resolveNoteSchemas(resolved, { tags: [tag] });
+
+  // resolveNoteSchemas returns effectiveTags (only fields-contributing tags).
+  // We need the full walk for effective_parents — replay using the same
+  // resolver helper so walk-order semantics stay in lockstep with #270.
+  const visited = new Set<string>();
+  const order: string[] = [];
+  walkAncestors(tag, resolved, visited, order);
+  if (resolved.allTags.has(DEFAULT_TAG_NAME) && !visited.has(DEFAULT_TAG_NAME)) {
+    walkAncestors(DEFAULT_TAG_NAME, resolved, visited, order);
+  }
+  const effective_parents = order.filter((t) => t !== tag);
+
+  const effective_fields: Record<string, SchemaField> = {};
+  for (const [field, { spec }] of resolution.mergedFields) {
+    effective_fields[field] = spec;
+  }
+
+  return { effective_parents, effective_fields };
+}
+
+// ---------------------------------------------------------------------------
+// Projection
+// ---------------------------------------------------------------------------
+
+/**
+ * Static query-hint catalog. Sent verbatim in both vault-info JSON and the
+ * connect-time markdown projection so an agent can self-orient without
+ * reading source. Edit here when query semantics change.
+ */
+export const QUERY_HINTS: readonly string[] = [
+  "query-notes { tag: \"X\" } — all notes with tag X (includes descendants per inheritance)",
+  "query-notes { tag: \"X\", metadata: { field: { op: value } } } — operator queries on indexed fields (eq/ne/gt/gte/lt/lte/in/not_in/exists)",
+  "query-notes { search: \"...\" } — full-text search across content",
+  "query-notes { near: { id: \"...\" }, depth: 2 } — graph neighborhood within N hops",
+  "query-notes { id: \"<note-id-or-path>\" } — fetch a single note by ID or path",
+] as const;
+
+/**
+ * Build the comprehensive vault projection. Pure read; no caches mutated.
+ *
+ * Shape rules:
+ *
+ *   - `tags`: only tags carrying their own `description` or `fields`. A
+ *     hierarchy-only tag (parent_names but no own schema) is omitted from
+ *     the catalog — its semantics live in whichever ancestor contributes
+ *     fields. `effective_fields` still surfaces the merged spec when the
+ *     tag *does* appear (because it has its own description/fields).
+ *
+ *   - `indexed_fields`: one entry per row in the `indexed_fields` table.
+ *     The user-facing `type` is drawn from the first declarer's spec —
+ *     declarers must agree on type (enforced at write time) so picking the
+ *     first is unambiguous. `tags` lists every declarer, sorted.
+ *
+ *   - `stats`: included when `opts.includeStats === true`. Uses the
+ *     existing `getVaultStats` shape unchanged — camelCase keys, full
+ *     monthly distribution.
+ */
+export function buildVaultProjection(
+  db: Database,
+  opts?: { includeStats?: boolean },
+): VaultProjection {
+  const resolved = loadSchemaConfig(db);
+  const records = listTagRecords(db);
+
+  const tags: ProjectionTag[] = [];
+  for (const r of records) {
+    const hasOwnSchema =
+      (r.description !== undefined && r.description !== null) ||
+      (r.fields !== undefined && r.fields !== null && Object.keys(r.fields).length > 0);
+    if (!hasOwnSchema) continue;
+
+    const { effective_parents, effective_fields } = resolveTagInheritance(resolved, r.tag);
+
+    tags.push({
+      name: r.tag,
+      description: r.description ?? null,
+      parents: r.parent_names ?? [],
+      effective_parents,
+      fields: r.fields ?? null,
+      effective_fields,
+      relationships: r.relationships ?? null,
+    });
+  }
+
+  const indexedRows = listIndexedFields(db);
+  const indexed_fields: ProjectionIndexedField[] = indexedRows.map((row) => {
+    const declarers = [...row.declarerTags].sort();
+    // Recover the user-facing type from the first declarer's spec. Falls
+    // back to a sqlite-derived label if the declarer's row is gone (race;
+    // shouldn't happen because release drops the indexed_fields row, but
+    // robust against drift).
+    let userType = sqliteToUserType(row.sqliteType);
+    for (const t of declarers) {
+      const fields = resolved.tagToFields.get(t);
+      const declared = fields?.[row.field]?.type;
+      if (typeof declared === "string" && declared.length > 0) {
+        userType = declared;
+        break;
+      }
+    }
+    return { name: row.field, type: userType, tags: declarers };
+  });
+
+  const projection: VaultProjection = {
+    tags,
+    indexed_fields,
+    query_hints: [...QUERY_HINTS],
+  };
+
+  if (opts?.includeStats) {
+    projection.stats = noteOps.getVaultStats(db);
+  }
+
+  return projection;
+}
+
+function sqliteToUserType(t: string): string {
+  if (t === "TEXT") return "string";
+  if (t === "INTEGER") return "integer";
+  return t.toLowerCase();
+}
+
+// ---------------------------------------------------------------------------
+// Markdown rendering — for getServerInstruction
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a vault projection as a terse markdown brief for the MCP
+ * `initialize` response. Keep dense — agents see this once at connect, and
+ * the goal is "everything an agent needs to start using the vault sensibly,
+ * with explicit pointers for refresh."
+ *
+ * Token budget guideline: ~600 tokens for a small vault (Aaron's, ~4 tags-
+ * with-schemas) and under ~5K tokens at 50 tags-with-schemas. Listing all
+ * tags-with-schemas inline is the default; cap heuristics can be added if
+ * a real test shape demands it.
+ */
+export function projectionToMarkdown(args: {
+  vaultName: string;
+  description?: string | null;
+  projection: VaultProjection;
+}): string {
+  const { vaultName, description, projection } = args;
+  const stats = projection.stats;
+
+  const lines: string[] = [];
+  lines.push(`You are connected to Parachute Vault "${vaultName}".`);
+  if (description && description.trim().length > 0) {
+    lines.push("");
+    lines.push(description.trim());
+  }
+
+  lines.push("");
+  lines.push("## Quick orientation (call `vault-info` for full schema)");
+  lines.push("");
+
+  if (stats) {
+    // Two distinct counts surface here so an agent doesn't conflate
+    // them (vault#274): `tagCount` is "tags ANY note uses" — driven by
+    // note_tags rows. `projection.tags.length` is "tags carrying a
+    // schema declaration" — strictly smaller and the relevant denominator
+    // for the schema-bearing list a few lines down. Showing only one
+    // hid the gap (e.g., 100 tags but only 5 with schemas read as
+    // "100 tags with schemas").
+    const noteCount = stats.totalNotes;
+    const tagCount = stats.tagCount;
+    const withSchemas = projection.tags.length;
+    const noteLabel = noteCount === 1 ? "note" : "notes";
+    const tagLabel = tagCount === 1 ? "tag" : "tags";
+    const tagSuffix = withSchemas > 0 ? `, ${withSchemas} with schemas` : "";
+    lines.push(`- ${noteCount} ${noteLabel}, ${tagCount} ${tagLabel} total${tagSuffix}`);
+  } else {
+    lines.push(`- (call \`vault-info { include_stats: true }\` for note/tag counts)`);
+  }
+
+  if (projection.tags.length === 0) {
+    lines.push(`- No tag schemas declared yet — every note is freeform.`);
+  } else {
+    const names = projection.tags.map((t) => t.name).join(", ");
+    lines.push(`- ${projection.tags.length} tag${projection.tags.length === 1 ? "" : "s"} with schemas: ${names}`);
+  }
+
+  if (projection.indexed_fields.length > 0) {
+    lines.push(`- Indexed metadata fields (queryable with operators):`);
+    for (const f of projection.indexed_fields) {
+      const declarers = f.tags.map((t) => `#${t}`).join(", ");
+      lines.push(`  - ${f.name} (${f.type}; from ${declarers})`);
+    }
+  } else {
+    lines.push(`- No indexed metadata fields.`);
+  }
+
+  lines.push("");
+  lines.push("## Querying");
+  lines.push("");
+  for (const hint of projection.query_hints) {
+    lines.push(`- \`${hint}\``);
+  }
+
+  lines.push("");
+  lines.push("## Refreshing context");
+  lines.push("");
+  lines.push("If schema or tags change during this session, call `vault-info` to refresh the full projection. Call `list-tags { include_schema: true }` for tag-only details.");
+
+  return lines.join("\n");
+}

package/core/src/wikilinks.ts

@@ -44,7 +44,7 @@ export function parseWikilinks(content: string): ParsedWikilink[] {
 
   while ((match = regex.exec(stripped)) !== null) {
     const embed = match[1] === "!";
-    const inner = match[2];
+    const inner = match[2]!;
 
     // Split on | for display text: [[target|display]]
     const pipeIdx = inner.indexOf("|");
@@ -133,7 +133,7 @@ export function resolveWikilink(db: Database, target: string): string | null {
       )
   `).all(target, `%/${target}`) as { id: string }[];
 
-  if (basename.length === 1) return basename[0].id;
+  if (basename.length === 1) return basename[0]!.id;
 
   // Ambiguous or no match
   return null;
@@ -171,7 +171,7 @@ export function resolveWikilinkDetailed(db: Database, target: string): WikilinkR
   `).all(target, `%/${target}`) as { id: string; path: string }[];
 
   if (basename.length === 1) {
-    return { resolved: true, note_id: basename[0].id, path: basename[0].path, candidates: [] };
+    return { resolved: true, note_id: basename[0]!.id, path: basename[0]!.path, candidates: [] };
   }
 
   if (basename.length > 1) {

package/package.json

@@ -1,20 +1,30 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.3.3",
+  "version": "0.4.3",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",
   "bin": {
     "parachute-vault": "src/cli.ts"
   },
+  "files": [
+    "src",
+    "core/src",
+    "core/package.json",
+    ".parachute",
+    "tsconfig.json"
+  ],
   "scripts": {
     "start": "bun src/server.ts",
     "cli": "bun src/cli.ts",
-    "test": "bun test src/",
-    "test:core": "cd core && node --experimental-vm-modules node_modules/vitest/dist/cli.js run"
+    "test": "bun test ./src/",
+    "test:core": "cd core && node --experimental-vm-modules node_modules/vitest/dist/cli.js run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
+    "@openparachute/scope-guard": "^0.2.0",
+    "jose": "^6.2.2",
     "otpauth": "^9.5.0",
     "qrcode-terminal": "^0.12.0"
   },

package/src/admin-spa.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Tests for the admin SPA static-file mount (`src/admin-spa.ts`).
+ *
+ * The routing layer's responsibility is just "dispatch /admin/* to the SPA";
+ * this file tests the SPA-serving behavior itself with a tmp dist dir so
+ * the assertions don't depend on `bun run build` having been run in
+ * `web/ui/`. The integration check (admin path → SPA dispatch) lives in
+ * `routing.test.ts`.
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { isAdminSpaPath, serveAdminSpa } from "./admin-spa.ts";
+
+const fixtureDir = join(tmpdir(), `vault-admin-spa-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+
+beforeAll(() => {
+  mkdirSync(join(fixtureDir, "assets"), { recursive: true });
+  writeFileSync(join(fixtureDir, "index.html"), "<!doctype html><html><body>shell</body></html>");
+  writeFileSync(join(fixtureDir, "assets", "index-abc.js"), "console.log('bundle');");
+  writeFileSync(join(fixtureDir, "assets", "index-abc.css"), "body { color: red; }");
+});
+
+afterAll(() => {
+  rmSync(fixtureDir, { recursive: true, force: true });
+});
+
+describe("isAdminSpaPath", () => {
+  test("matches /vault/<name>/admin and /vault/<name>/admin/...", () => {
+    expect(isAdminSpaPath("/vault/work/admin")).toBe(true);
+    expect(isAdminSpaPath("/vault/work/admin/")).toBe(true);
+    expect(isAdminSpaPath("/vault/work/admin/tokens")).toBe(true);
+    expect(isAdminSpaPath("/vault/boulder/admin/assets/index.js")).toBe(true);
+    // Vault names with URL-safe punctuation should still match — the regex
+    // captures up to the next "/" so dashes / dots / digits all pass.
+    expect(isAdminSpaPath("/vault/my-vault.2/admin")).toBe(true);
+  });
+
+  test("does not match adjacent paths under the same vault", () => {
+    expect(isAdminSpaPath("/vault/work")).toBe(false);
+    expect(isAdminSpaPath("/vault/work/")).toBe(false);
+    expect(isAdminSpaPath("/vault/work/api/notes")).toBe(false);
+    expect(isAdminSpaPath("/vault/work/tokens")).toBe(false);
+    // Bare `admin-foo` suffix must not trigger — only the SPA mount itself.
+    expect(isAdminSpaPath("/vault/work/admin-foo")).toBe(false);
+    expect(isAdminSpaPath("/vault/work/administrative")).toBe(false);
+  });
+
+  test("does not match origin-rooted /admin (legacy mount retired)", () => {
+    expect(isAdminSpaPath("/admin")).toBe(false);
+    expect(isAdminSpaPath("/admin/")).toBe(false);
+    expect(isAdminSpaPath("/admin/tokens")).toBe(false);
+  });
+
+  test("does not match unrelated paths", () => {
+    expect(isAdminSpaPath("/")).toBe(false);
+    expect(isAdminSpaPath("/vaults")).toBe(false);
+    expect(isAdminSpaPath("/auth/status")).toBe(false);
+  });
+});
+
+describe("serveAdminSpa", () => {
+  test("503 when the dist dir is absent (unbuilt)", async () => {
+    const res = await serveAdminSpa("/nonexistent/dist/dir", "/vault/work/admin/");
+    expect(res.status).toBe(503);
+    const body = await res.text();
+    expect(body).toContain("not found");
+    expect(body).toContain("bun run build");
+  });
+
+  test("bare /vault/<name>/admin redirects to trailing-slash form (301)", async () => {
+    // Vite's relative asset URLs (./assets/...) resolve against the
+    // *directory* of the current document — without a trailing slash,
+    // /vault/foo/admin's directory is /vault/foo/ and assets 404 against
+    // the per-vault auth wall. Hub's resolveManagementUrl generates the
+    // bare form, so this redirect is the load-bearing canonicalization.
+    const res = await serveAdminSpa(fixtureDir, "/vault/work/admin");
+    expect(res.status).toBe(301);
+    expect(res.headers.get("Location")).toBe("/vault/work/admin/");
+  });
+
+  test("/vault/<name>/admin/ returns the SPA index", async () => {
+    const res = await serveAdminSpa(fixtureDir, "/vault/work/admin/");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    expect(await res.text()).toContain("shell");
+  });
+
+  test("client-routed path (no extension) falls through to index.html", async () => {
+    const res = await serveAdminSpa(fixtureDir, "/vault/work/admin/tokens");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    expect(await res.text()).toContain("shell");
+  });
+
+  test("real asset path returns the asset with the right content-type", async () => {
+    const jsRes = await serveAdminSpa(fixtureDir, "/vault/work/admin/assets/index-abc.js");
+    expect(jsRes.status).toBe(200);
+    expect(jsRes.headers.get("content-type")).toContain("application/javascript");
+    expect(await jsRes.text()).toContain("console.log");
+
+    const cssRes = await serveAdminSpa(fixtureDir, "/vault/work/admin/assets/index-abc.css");
+    expect(cssRes.status).toBe(200);
+    expect(cssRes.headers.get("content-type")).toContain("text/css");
+  });
+
+  test("vault names with URL-safe punctuation strip cleanly", async () => {
+    const res = await serveAdminSpa(fixtureDir, "/vault/my-vault.2/admin/assets/index-abc.js");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("application/javascript");
+  });
+
+  test("typo'd asset path falls through to index.html (not a 404)", async () => {
+    const res = await serveAdminSpa(fixtureDir, "/vault/work/admin/assets/missing-xyz.js");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+  });
+
+  test("path traversal (..) cannot escape dist dir", async () => {
+    // Triggers the asset-shape filter (.. is rejected) so this falls through
+    // to the SPA shell rather than reading something outside dist/.
+    const res = await serveAdminSpa(fixtureDir, "/vault/work/admin/../../etc/passwd");
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    const body = await res.text();
+    expect(body).toContain("shell");
+    expect(body).not.toContain("root:");
+  });
+});
+
+describe("hub <-> vault managementUrl contract", () => {
+  // Browsers drop the URL fragment when following a 301 (RFC 7231 SHOULD
+  // preserve, but Chrome/Firefox/Safari are inconsistent in practice). The
+  // hub-issued JWT travels in `#token=...`, so a redirected click loses the
+  // token and the SPA boots unauthenticated. Hub's resolveManagementUrl joins
+  // the per-vault module URL with module.json's `managementUrl` verbatim — if
+  // it ends with "/" the canonical click target is `/vault/<name>/admin/`
+  // (no redirect, fragment preserved). Without the trailing slash hub emits
+  // `/vault/<name>/admin`, the server 301s, and the fragment is gone.
+  test("module.json managementUrl ends with '/' so hub emits the no-redirect form", () => {
+    const moduleJson = JSON.parse(
+      readFileSync(join(import.meta.dir, "..", ".parachute", "module.json"), "utf8"),
+    );
+    expect(moduleJson.managementUrl).toMatch(/\/$/);
+  });
+
+  test("the canonical hub-emitted URL serves the SPA shell directly (no 301)", async () => {
+    // Mirror hub's resolveManagementUrl shape: per-vault module URL +
+    // managementUrl. With managementUrl="/admin/" the result is
+    // /vault/<name>/admin/ — which serveAdminSpa returns as 200, not 301.
+    const moduleJson = JSON.parse(
+      readFileSync(join(import.meta.dir, "..", ".parachute", "module.json"), "utf8"),
+    );
+    const canonical = `/vault/work${moduleJson.managementUrl}`;
+    const res = await serveAdminSpa(fixtureDir, canonical);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("Location")).toBeNull();
+  });
+});