@openparachute/vault 0.4.4-rc.14 → 0.4.5

package/core/src/core.test.ts

@@ -322,6 +322,142 @@ describe("updated_at backfill on init", async () => {
   });
 });
 
+// ---- Extension (vault#328 Phase 1: DB + Store) ----
+//
+// Three pinned behaviors:
+//   1. Migrations and inserts default to "md" — every existing row keeps
+//      its meaning after the v17 → v18 ALTER TABLE.
+//   2. Explicit extension on createNote persists end-to-end.
+//   3. queryNotes filters by extension (single string + array shapes).
+
+describe("notes.extension (vault#328)", async () => {
+  it("defaults to 'md' when not specified on createNote", async () => {
+    const note = await store.createNote("hello world");
+    expect(note.extension).toBe("md");
+    const fetched = await store.getNote(note.id);
+    expect(fetched!.extension).toBe("md");
+  });
+
+  it("persists explicit extension on createNote", async () => {
+    const note = await store.createNote("month,income\n2026-01,12000", {
+      path: "Tabular/budget",
+      extension: "csv",
+    });
+    expect(note.extension).toBe("csv");
+    const fetched = await store.getNote(note.id);
+    expect(fetched!.extension).toBe("csv");
+  });
+
+  it("backfills 'md' on existing rows after v17 → v18 migration", () => {
+    // Build a v17-shape vault by hand: create the notes table WITHOUT the
+    // `extension` column, insert a row, then run initSchema and assert
+    // the migration backfills "md".
+    const raw = new Database(":memory:");
+    raw.exec(`
+      CREATE TABLE notes (
+        id TEXT PRIMARY KEY,
+        content TEXT DEFAULT '',
+        path TEXT,
+        metadata TEXT DEFAULT '{}',
+        created_at TEXT NOT NULL,
+        updated_at TEXT
+      )
+    `);
+    raw.prepare(
+      "INSERT INTO notes (id, content, created_at, updated_at) VALUES (?, ?, ?, ?)",
+    ).run("legacy", "old content", "2024-01-01T00:00:00.000Z", "2024-01-01T00:00:00.000Z");
+
+    initSchema(raw); // applies v18 ALTER TABLE
+
+    const row = raw.prepare("SELECT extension FROM notes WHERE id = ?").get("legacy") as {
+      extension: string;
+    };
+    expect(row.extension).toBe("md");
+  });
+
+  it("updateNote changes extension on existing note", async () => {
+    const note = await store.createNote("hello", { path: "Foo" });
+    expect(note.extension).toBe("md");
+    const updated = await store.updateNote(note.id, { extension: "mdx" });
+    expect(updated.extension).toBe("mdx");
+    const fetched = await store.getNote(note.id);
+    expect(fetched!.extension).toBe("mdx");
+  });
+
+  it("queryNotes filters by extension (single string)", async () => {
+    await store.createNote("md note A", { path: "a", extension: "md" });
+    await store.createNote("csv note", { path: "b", extension: "csv" });
+    await store.createNote("md note B", { path: "c" }); // default md
+    const csv = await store.queryNotes({ extension: "csv" });
+    expect(csv).toHaveLength(1);
+    expect(csv[0]!.path).toBe("b");
+    const md = await store.queryNotes({ extension: "md" });
+    expect(md).toHaveLength(2);
+    expect(md.map((n) => n.path).sort()).toEqual(["a", "c"]);
+  });
+
+  it("queryNotes filters by extension (array — IN clause)", async () => {
+    await store.createNote("md note", { path: "a" });
+    await store.createNote("csv note", { path: "b", extension: "csv" });
+    await store.createNote("yaml note", { path: "c", extension: "yaml" });
+    await store.createNote("json note", { path: "d", extension: "json" });
+    const results = await store.queryNotes({ extension: ["csv", "yaml", "json"] });
+    expect(results).toHaveLength(3);
+    const paths = results.map((n) => n.path).sort();
+    expect(paths).toEqual(["b", "c", "d"]);
+  });
+
+  it("queryNotes extension filter is case-insensitive", async () => {
+    await store.createNote("csv note", { path: "b", extension: "csv" });
+    // Caller-supplied case shouldn't matter — stored as "csv", looked up as "CSV".
+    const results = await store.queryNotes({ extension: "CSV" });
+    expect(results).toHaveLength(1);
+  });
+
+  it("updateNote extension-only collision throws PathConflictError (vault#329 F1)", async () => {
+    // Two notes share `Foo` differing only by extension — legal under
+    // v18's composite (path, extension) uniqueness. Flip the md note's
+    // extension to "csv": that would collide with the existing csv
+    // row. The catch in updateNote must surface PATH_CONFLICT (not a
+    // raw SQLiteError) since the composite index fires UNIQUE on
+    // extension-only updates just like it does on path-only updates.
+    const md = await store.createNote("# md note", { path: "Foo", id: "foo-md" });
+    await store.createNote("a,b\n1,2", { path: "Foo", extension: "csv", id: "foo-csv" });
+    expect(
+      store.updateNote(md.id, { extension: "csv" }),
+    ).rejects.toMatchObject({ code: "PATH_CONFLICT", path: "Foo" });
+  });
+
+  it("getNoteByPath throws AmbiguousPathError when path matches multiple extensions (vault#330 S1)", async () => {
+    await store.createNote("# md", { path: "Foo", id: "foo-md" });
+    await store.createNote("a,b\n1,2", { path: "Foo", extension: "csv", id: "foo-csv" });
+    expect(store.getNoteByPath("Foo")).rejects.toMatchObject({
+      code: "AMBIGUOUS_PATH",
+      path: "Foo",
+    });
+  });
+
+  it("getNoteByPath returns the right note when extension is passed (vault#330 S1)", async () => {
+    await store.createNote("# md", { path: "Foo", id: "foo-md" });
+    await store.createNote("a,b\n1,2", { path: "Foo", extension: "csv", id: "foo-csv" });
+    const md = await store.getNoteByPath("Foo", "md");
+    const csv = await store.getNoteByPath("Foo", "csv");
+    expect(md!.id).toBe("foo-md");
+    expect(csv!.id).toBe("foo-csv");
+  });
+
+  it("getNoteByPath returns single match unchanged when no ambiguity (vault#330 S1 back-compat)", async () => {
+    await store.createNote("# only", { path: "Foo", id: "only" });
+    const note = await store.getNoteByPath("Foo");
+    expect(note!.id).toBe("only");
+  });
+
+  it("getNoteByPath returns null for unknown path (vault#330 S1 back-compat)", async () => {
+    const note = await store.getNoteByPath("DoesNotExist");
+    expect(note).toBeNull();
+  });
+});
+
 // ---- Tags ----
 
 describe("tags", async () => {
@@ -1589,6 +1725,91 @@ describe("MCP tools", async () => {
     expect(result[1].tags).toContain("doc");
   });
 
+  it("create-note accepts extension field (vault#328)", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const result = await createNote.execute({
+      content: "month,income\n2026-01,12000",
+      path: "Tabular/budget",
+      extension: "csv",
+    }) as any;
+    expect(result.extension).toBe("csv");
+  });
+
+  it("create-note defaults extension to 'md' when omitted (vault#328)", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const result = await createNote.execute({ content: "plain markdown" }) as any;
+    expect(result.extension).toBe("md");
+  });
+
+  it("create-note rejects invalid extension (uppercase, dot, reserved) (vault#328)", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    // Uppercase
+    expect(createNote.execute({ content: "x", extension: "CSV" })).rejects.toThrow(/invalid extension/);
+    // Dot
+    expect(createNote.execute({ content: "x", extension: "csv.bak" })).rejects.toThrow(/invalid extension/);
+    // Slash
+    expect(createNote.execute({ content: "x", extension: "foo/bar" })).rejects.toThrow(/invalid extension/);
+    // Reserved "parachute" prefix (lowercase — the pattern check passes,
+    // so the reserved-prefix guard is what fires).
+    expect(createNote.execute({ content: "x", extension: "parachute" })).rejects.toThrow(/reserved/);
+    expect(createNote.execute({ content: "x", extension: "parachutex" })).rejects.toThrow(/reserved/);
+    // Too long (>16)
+    expect(createNote.execute({ content: "x", extension: "a".repeat(17) })).rejects.toThrow(/invalid extension/);
+    // Empty
+    expect(createNote.execute({ content: "x", extension: "" })).rejects.toThrow(/non-empty/);
+  });
+
+  it("update-note changes extension (vault#328)", async () => {
+    const note = await store.createNote("hi", { path: "Foo" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({ id: note.id, extension: "mdx", force: true }) as any;
+    expect(result.extension).toBe("mdx");
+  });
+
+  it("update-note validates extension on update branch (vault#328)", async () => {
+    const note = await store.createNote("hi", { path: "Foo" });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    expect(
+      updateNote.execute({ id: note.id, extension: "BAD", force: true }),
+    ).rejects.toThrow(/invalid extension/);
+  });
+
+  it("update-note if_missing=create honors extension (vault#328)", async () => {
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    const result = await updateNote.execute({
+      id: "Tabular/new-budget",
+      content: "month,total\n2026-02,9000",
+      extension: "csv",
+      if_missing: "create",
+    }) as any;
+    expect(result.created).toBe(true);
+    expect(result.extension).toBe("csv");
+  });
+
+  it("query-notes filters by extension (vault#328)", async () => {
+    await store.createNote("md note", { path: "a" });
+    await store.createNote("csv note", { path: "b", extension: "csv" });
+    await store.createNote("yaml note", { path: "c", extension: "yaml" });
+    const tools = generateMcpTools(store);
+    const queryNotes = tools.find((t) => t.name === "query-notes")!;
+
+    // Single extension
+    const csv = await queryNotes.execute({ extension: "csv", include_content: true }) as any[];
+    expect(csv).toHaveLength(1);
+    expect(csv[0].path).toBe("b");
+
+    // Array shape
+    const both = await queryNotes.execute({ extension: ["csv", "yaml"], include_content: true }) as any[];
+    expect(both).toHaveLength(2);
+    expect(both.map((n) => n.path).sort()).toEqual(["b", "c"]);
+  });
+
   it("create-note with links resolves targets by path", async () => {
     const tools = generateMcpTools(store);
     const createNote = tools.find((t) => t.name === "create-note")!;

package/core/src/mcp.ts

@@ -1,7 +1,7 @@
 import { Database } from "bun:sqlite";
 import type { Store, Note } from "./types.js";
 import * as noteOps from "./notes.js";
-import { filterMetadata, MAX_BATCH_SIZE } from "./notes.js";
+import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -26,14 +26,33 @@ export interface McpToolDef {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve a note identifier — tries ID first, then case-insensitive path match.
- * Works everywhere a note reference is accepted.
+ * Resolve a note identifier — tries ID first, then case-insensitive
+ * path match. Works everywhere a note reference is accepted.
+ *
+ * Path-with-extension form (vault#330 S1): a trailing `.<ext>` matching
+ * the extension pattern (`/^[a-z0-9]{1,16}$/i`) is parsed as
+ * `(path, extension)` to disambiguate notes that share a path
+ * differing only by extension. Mirrors the wikilink ambiguity policy
+ * from vault#328.
+ *
+ * On ambiguous path with no extension hint, `getNoteByPath` throws
+ * `AmbiguousPathError` — `resolveNote` propagates it so MCP / REST
+ * handlers can surface a clear 4xx rather than picking arbitrarily.
  */
 function resolveNote(db: Database, idOrPath: string): Note | null {
   // Try ID match first (fast, indexed)
   const byId = noteOps.getNote(db, idOrPath);
   if (byId) return byId;
-  // Fallback to path match
+  // Path-with-extension form: `Tabular/budget.csv` → (path="Tabular/
+  // budget", extension="csv"). Only kicks in when the suffix looks
+  // like an extension AND a `(path, ext)` row exists. Fall through to
+  // the no-extension lookup if not (so `Recipe.v2` where `v2` isn't a
+  // real extension still finds Recipe.v2 by exact-path).
+  const extMatch = idOrPath.match(/^(.*)\.([a-z0-9]{1,16})$/i);
+  if (extMatch) {
+    const explicit = noteOps.getNoteByPath(db, extMatch[1]!, extMatch[2]!);
+    if (explicit) return explicit;
+  }
   return noteOps.getNoteByPath(db, idOrPath);
 }
 
@@ -133,6 +152,13 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           has_links: { type: "boolean", description: "Presence filter: true = only notes with at least one inbound or outbound link; false = only orphaned notes (no links in either direction)." },
           path: { type: "string", description: "Exact path match (case-insensitive)" },
           path_prefix: { type: "string", description: "Path prefix match (e.g., 'Projects/')" },
+          extension: {
+            oneOf: [
+              { type: "string" },
+              { type: "array", items: { type: "string" } },
+            ],
+            description: "Filter by file extension (vault#328). Pass a single extension (e.g. \"csv\") or an array (e.g. [\"csv\", \"yaml\", \"json\"]). Notes default to \"md\"; case-insensitive match.",
+          },
           search: { type: "string", description: "Full-text search query" },
           metadata: {
             type: "object",
@@ -264,6 +290,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             hasLinks: params.has_links as boolean | undefined,
             path: params.path as string | undefined,
             pathPrefix: params.path_prefix as string | undefined,
+            extension: params.extension as string | string[] | undefined,
             // Push the near-scope into the SQL WHERE so that LIMIT and ORDER
             // BY apply to the neighborhood. Without this, queryNotes would
             // fetch the first `limit` notes by created_at and then post-
@@ -339,6 +366,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
           // Single note fields
           content: { type: "string", description: "Note content (markdown). Wikilinks like [[Target]] auto-resolve." },
           path: { type: "string", description: "Note path (e.g., 'Projects/README')" },
+          extension: { type: "string", description: "File extension (vault#328). Default \"md\". Use \"csv\"/\"yaml\"/\"json\"/\"mdx\"/etc. for non-markdown notes. Lowercase alphanumeric, 1–16 chars; no '.' or '/'. The \"parachute\" prefix is reserved." },
           metadata: { type: "object", description: "Metadata fields" },
           tags: { type: "array", items: { type: "string" }, description: "Tags to apply" },
           links: {
@@ -362,6 +390,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               properties: {
                 content: { type: "string" },
                 path: { type: "string" },
+                extension: { type: "string", description: "File extension (vault#328). See top-level docs." },
                 metadata: { type: "object" },
                 tags: { type: "array", items: { type: "string" } },
                 links: { type: "array" },
@@ -392,11 +421,19 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
         if (batched) db.exec("BEGIN");
         try {
           for (const item of items) {
+            // Validate extension up front (vault#328). Throwing here while
+            // we're inside the BEGIN block on a batch rolls back the
+            // transaction in the outer catch — the same behavior as a
+            // path conflict mid-batch.
+            const extension = item.extension !== undefined
+              ? validateExtension(item.extension)
+              : undefined;
             const note = await store.createNote(item.content as string ?? "", {
               path: item.path as string | undefined,
               tags: item.tags as string[] | undefined,
               metadata: item.metadata as Record<string, unknown> | undefined,
               created_at: item.created_at as string | undefined,
+              ...(extension !== undefined ? { extension } : {}),
             });
 
             // Create explicit links (not wikilinks — those are automatic)
@@ -467,6 +504,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             description: "Find-and-replace one occurrence. Errors if `old_text` is not found or matches multiple locations. Mutually exclusive with `content` and `append`/`prepend`.",
           },
           path: { type: "string", description: "New path" },
+          extension: { type: "string", description: "Change the note's file extension (vault#328). Allowed but caller-owned — you're responsible for content validity if you switch a non-empty note's extension. Lowercase alphanumeric, 1–16 chars; \"parachute\" prefix reserved." },
           metadata: { type: "object", description: "Metadata to merge (keys are merged, not replaced wholesale)" },
           created_at: { type: "string", description: "New created_at timestamp" },
           if_updated_at: { type: "string", description: "Optimistic concurrency check: the updated_at value you last read. Rejects with a conflict error if the note has been modified since. Required unless `force: true` is set or the call is `append`/`prepend`-only." },
@@ -531,6 +569,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
                   required: ["old_text", "new_text"],
                 },
                 path: { type: "string" },
+                extension: { type: "string", description: "Change the note's file extension (vault#328). See top-level docs." },
                 metadata: { type: "object" },
                 created_at: { type: "string" },
                 if_updated_at: { type: "string", description: "Optimistic concurrency check for this item; rejects with a conflict error if the note has been modified since. Required unless `force: true` is set on this item or the item is `append`/`prepend`-only." },
@@ -617,6 +656,11 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
               // caller's intent.
               const idLooksLikePath = idOrPath.includes("/") || !/^[A-Za-z0-9_-]+$/.test(idOrPath);
               const explicitPath = typeof item.path === "string" ? item.path as string : undefined;
+              // Validate extension before reaching the Store — same
+              // contract as the create-note tool.
+              const createExt = item.extension !== undefined
+                ? validateExtension(item.extension)
+                : undefined;
               const createOpts: Parameters<Store["createNote"]>[1] = {
                 ...(idLooksLikePath ? { path: explicitPath ?? idOrPath } : { id: idOrPath, ...(explicitPath !== undefined ? { path: explicitPath } : {}) }),
                 ...(item.tags && Array.isArray((item.tags as any).add)
@@ -626,6 +670,7 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
                     : {}),
                 ...(item.metadata !== undefined ? { metadata: item.metadata as Record<string, unknown> } : {}),
                 ...(item.created_at !== undefined ? { created_at: item.created_at as string } : {}),
+                ...(createExt !== undefined ? { extension: createExt } : {}),
               };
               const content = (item.content as string | undefined) ?? "";
               const created = await store.createNote(content, createOpts);
@@ -755,6 +800,9 @@ Link expansion: pass \`expand_links: true\` to inline [[wikilinks]] from returne
             if (item.prepend !== undefined) updates.prepend = item.prepend;
           }
           if (item.path !== undefined) updates.path = item.path;
+          if (item.extension !== undefined) {
+            updates.extension = validateExtension(item.extension);
+          }
           if (item.metadata !== undefined) {
             // Merge metadata (don't replace wholesale)
             const existing = (note.metadata as Record<string, unknown>) ?? {};
@@ -1233,8 +1281,10 @@ function normalizeTags(tag: unknown): string[] | undefined {
 }
 
 // Re-exported for backward compat; defined in notes.ts alongside the
-// conditional-UPDATE implementation that raises it.
-export { ConflictError, PathConflictError, MAX_BATCH_SIZE } from "./notes.js";
+// conditional-UPDATE implementation that raises it. AmbiguousPathError
+// joins the set (vault#331 N2) so external callers can `instanceof`
+// it without crossing module boundaries.
+export { ConflictError, PathConflictError, AmbiguousPathError, MAX_BATCH_SIZE } from "./notes.js";
 
 /**
  * Thrown by the `update-note` MCP tool (and the REST PATCH handler) when a