@openparachute/vault 0.4.4-rc.12 → 0.4.5

package/core/src/schema.ts

@@ -2,17 +2,25 @@ import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
 import { rebuildIndexes } from "./indexed-fields.js";
 
-export const SCHEMA_VERSION = 17;
+export const SCHEMA_VERSION = 18;
 
 export const SCHEMA_SQL = `
--- Notes: the universal record
+-- Notes: the universal record.
+--
+-- extension (v18, vault#328) carries the file suffix the note should
+-- exhibit when serialized to disk — "md" by default, "csv"/"yaml"/"json"/
+-- "mdx"/etc. for non-markdown notes. Stored extension-less in the path
+-- column; on-disk uniqueness key is (path, extension). See
+-- core/src/portable-md.ts:supportsInlineFrontmatter for the
+-- frontmatter-vs-sidecar split.
 CREATE TABLE IF NOT EXISTS notes (
   id TEXT PRIMARY KEY,
   content TEXT DEFAULT '',
   path TEXT,
   metadata TEXT DEFAULT '{}',
   created_at TEXT NOT NULL,
-  updated_at TEXT
+  updated_at TEXT,
+  extension TEXT NOT NULL DEFAULT 'md'
 );
 
 -- Tags: first-class identity carrying schema, hierarchy, and typed-link
@@ -266,6 +274,11 @@ export function initSchema(db: Database): void {
   // as `tags.fields` if needed. See vault#267.
   migrateToV17(db);
 
+  // Migrate v17 → v18: add `notes.extension TEXT NOT NULL DEFAULT 'md'`.
+  // Backward-compat by construction — every existing row defaults to "md"
+  // (markdown), unchanged in meaning. See vault#328.
+  migrateToV18(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -793,6 +806,51 @@ function migrateToV17(db: Database): void {
   }
 }
 
+/**
+ * Migrate v17 → v18: add `notes.extension TEXT NOT NULL DEFAULT 'md'`
+ * (vault#328) AND widen the path-uniqueness index from `(path)` to
+ * `(path, extension)` so two notes can share a path differing only by
+ * extension (`Recipes/pasta` with both .md and .csv variants).
+ *
+ * Backward-compat by construction — every existing row defaults to "md",
+ * so the new composite-index uniqueness collapses to the v5
+ * "(path WHERE NOT NULL) is unique" behavior on existing data. Wrapped
+ * in BEGIN IMMEDIATE / COMMIT / ROLLBACK per the v14+ pattern.
+ */
+function migrateToV18(db: Database): void {
+  if (!hasTable(db, "notes")) return;
+
+  // Two responsibilities (column add + index swap) — both idempotent
+  // individually. Wrap in one transaction so an upgrading v17 vault
+  // ends up at exactly v17 or v18, never partial.
+  const needsColumn = !hasColumn(db, "notes", "extension");
+  const indexes = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type='index' AND name IN ('idx_notes_path_unique', 'idx_notes_path_ext_unique')",
+  ).all() as { name: string }[];
+  const hasOldUnique = indexes.some((r) => r.name === "idx_notes_path_unique");
+  const hasNewUnique = indexes.some((r) => r.name === "idx_notes_path_ext_unique");
+  if (!needsColumn && hasNewUnique && !hasOldUnique) return;
+
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    if (needsColumn) {
+      db.exec("ALTER TABLE notes ADD COLUMN extension TEXT NOT NULL DEFAULT 'md'");
+    }
+    if (hasOldUnique) {
+      db.exec("DROP INDEX idx_notes_path_unique");
+    }
+    if (!hasNewUnique) {
+      db.exec(
+        "CREATE UNIQUE INDEX idx_notes_path_ext_unique ON notes(path, extension) WHERE path IS NOT NULL",
+      );
+    }
+    db.exec("COMMIT");
+  } catch (err) {
+    db.exec("ROLLBACK");
+    throw err;
+  }
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;

package/core/src/store.ts

@@ -92,7 +92,7 @@ export class BunSqliteStore implements Store {
 
   // ---- Notes ----
 
-  async createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Promise<Note> {
+  async createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note> {
     const note = noteOps.createNote(this.db, content, opts);
 
     if (content) {
@@ -113,8 +113,8 @@ export class BunSqliteStore implements Store {
     return noteOps.getNote(this.db, id);
   }
 
-  async getNoteByPath(path: string): Promise<Note | null> {
-    return noteOps.getNoteByPath(this.db, path);
+  async getNoteByPath(path: string, extension?: string): Promise<Note | null> {
+    return noteOps.getNoteByPath(this.db, path, extension);
   }
 
   async getNotes(ids: string[]): Promise<Note[]> {
@@ -128,6 +128,7 @@ export class BunSqliteStore implements Store {
       append?: string;
       prepend?: string;
       path?: string;
+      extension?: string;
       metadata?: Record<string, unknown>;
       created_at?: string;
       skipUpdatedAt?: boolean;
@@ -498,7 +499,7 @@ export class BunSqliteStore implements Store {
    * `syncAllWikilinks`, so adding the cache rebuild there is the natural
    * place.)
    */
-  async createNoteRaw(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Promise<Note> {
+  async createNoteRaw(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note> {
     return noteOps.createNote(this.db, content, opts);
   }
 

package/core/src/types.ts

@@ -10,6 +10,14 @@ export interface Note {
   id: string;
   content: string;
   path?: string;
+  /**
+   * File extension (sans dot). Defaults to `"md"`. Controls the
+   * serialized file suffix on export — `.md`/`.mdx` carry frontmatter
+   * inline; `.csv`/`.yaml`/`.json`/etc. carry their metadata in a
+   * sidecar at `.parachute/notes-meta/<id>.yaml`. See vault#328 +
+   * `core/src/portable-md.ts:supportsInlineFrontmatter`.
+   */
+  extension?: string;
   metadata?: Record<string, unknown>;
   createdAt: string; // ISO-8601
   updatedAt?: string;
@@ -64,6 +72,13 @@ export interface QueryOpts {
   hasLinks?: boolean;
   path?: string;        // exact path match (case-insensitive)
   pathPrefix?: string;  // e.g., "Projects/Parachute" matches "Projects/Parachute/README"
+  /**
+   * Filter by file extension. Pass a single extension (e.g. `"csv"`) or
+   * an array (e.g. `["csv", "yaml", "json"]`). Extension is compared
+   * lower-case. Notes default to `"md"` so `extension: "md"` matches
+   * the existing markdown corpus. See vault#328.
+   */
+  extension?: string | string[];
   // Restrict results to a specific set of note IDs. The MCP `near` query uses
   // this to push graph-neighborhood scoping into the SQL WHERE clause so that
   // LIMIT and ORDER BY apply to the filtered set, not the whole notes table.
@@ -107,6 +122,7 @@ export interface QueryOpts {
 export interface NoteSummary {
   id: string;
   path?: string;
+  extension?: string;
   metadata?: Record<string, unknown>;
   createdAt: string;
   updatedAt?: string;
@@ -120,6 +136,7 @@ export interface NoteSummary {
 export interface NoteIndex {
   id: string;
   path?: string;
+  extension?: string;
   createdAt: string;
   updatedAt?: string;
   tags?: string[];
@@ -138,11 +155,18 @@ export interface HydratedLink extends Link {
 
 export interface Store {
   // Notes
-  createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string }): Promise<Note>;
+  createNote(content: string, opts?: { id?: string; path?: string; tags?: string[]; metadata?: Record<string, unknown>; created_at?: string; extension?: string }): Promise<Note>;
   getNote(id: string): Promise<Note | null>;
-  getNoteByPath(path: string): Promise<Note | null>;
+  /**
+   * Look up a note by path. Pass `extension` to disambiguate when
+   * multiple notes share a path differing only by extension (post-
+   * vault#328). When omitted and >1 row matches, throws
+   * `AmbiguousPathError` instead of silently picking one. See
+   * vault#330 S1.
+   */
+  getNoteByPath(path: string, extension?: string): Promise<Note | null>;
   getNotes(ids: string[]): Promise<Note[]>;
-  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; if_updated_at?: string }): Promise<Note>;
+  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; extension?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; if_updated_at?: string }): Promise<Note>;
   /**
    * Set a note's `created_at` and `updated_at` explicitly. Import-only:
    * used by the portable-md round-trip path to restore timestamps from

package/core/src/wikilinks.ts

@@ -110,19 +110,57 @@ function stripCode(content: string): string {
  * Resolve a wikilink target to a note ID.
  *
  * Resolution order:
- * 1. Exact path match (case-insensitive)
- * 2. Basename match — target matches the last segment of a path
- *    (e.g., "README" matches "Projects/Parachute/README")
- *    Only if there's exactly one match (ambiguous = unresolved)
+ * 1. **Explicit-extension target**: `[[Foo.csv]]` matches the note with
+ *    `path: "Foo"` AND `extension: "csv"` (vault#328). Lets a reader
+ *    disambiguate when multiple notes share a path differing only by
+ *    extension. The trailing `.<ext>` must match a known
+ *    alphanumeric pattern (1–16 chars) — otherwise the dot is treated
+ *    as part of the path string and falls through to the existing
+ *    rules.
+ * 2. Exact path match (case-insensitive) — multiple matches resolve to
+ *    a single note when only ONE extension is in play; if `Foo.md` and
+ *    `Foo.csv` both exist, the link refuses to resolve and the caller
+ *    sees an unresolved-wikilink entry (vault#328 ambiguity policy).
+ * 3. Basename match — target matches the last segment of a path
+ *    (e.g., "README" matches "Projects/Parachute/README"). Same
+ *    cross-extension ambiguity policy as #2.
  */
 export function resolveWikilink(db: Database, target: string): string | null {
-  // 1. Exact match (case-insensitive)
+  // 1. Explicit extension form: `[[path.ext]]` where `.ext` is a
+  // pattern-matching tail (lowercase alphanumeric, 1–16 chars).
+  // Mirrors EXTENSION_PATTERN in core/src/notes.ts so the wikilink
+  // parser and the API surface share the same notion of "this looks
+  // like an extension."
+  const extMatch = target.match(/^(.*)\.([a-z0-9]{1,16})$/i);
+  if (extMatch) {
+    const pathPart = extMatch[1]!;
+    const extPart = extMatch[2]!.toLowerCase();
+    const explicit = db.prepare(
+      "SELECT id FROM notes WHERE path = ? COLLATE NOCASE AND LOWER(extension) = ?",
+    ).get(pathPart, extPart) as { id: string } | undefined;
+    if (explicit) return explicit.id;
+    // No match for explicit (path, ext) — fall through to the looser
+    // rules so a literal note named `Recipe.v2` (where `v2` isn't an
+    // extension on a real note) can still resolve under exact-path
+    // match.
+  }
+
+  // 2. Exact match (case-insensitive). When multiple notes share a path
+  // (post-vault#328 this happens when `Foo.md` and `Foo.csv` both
+  // exist, since path is stored extension-less), refuse to resolve.
   const exact = db.prepare(
     "SELECT id FROM notes WHERE path = ? COLLATE NOCASE",
-  ).get(target) as { id: string } | undefined;
-  if (exact) return exact.id;
+  ).all(target) as { id: string }[];
+  if (exact.length === 1) return exact[0]!.id;
+  if (exact.length > 1) {
+    // Ambiguous — refuse-and-require-explicit-extension policy
+    // (vault#328). Returning null routes through the existing
+    // unresolved-wikilinks workflow, so the reader (or the indexer)
+    // sees the conflict.
+    return null;
+  }
 
-  // 2. Basename match — last path segment equals target
+  // 3. Basename match — last path segment equals target.
   // e.g., target "README" matches path "Projects/Parachute/README"
   const basename = db.prepare(`
     SELECT id FROM notes
@@ -150,17 +188,39 @@ export interface WikilinkResolution {
 
 /**
  * Resolve a wikilink target with full detail — single match, ambiguous, or unresolved.
+ * Mirrors `resolveWikilink`'s resolution order, including the explicit-
+ * extension form `[[Foo.csv]]` introduced by vault#328.
  */
 export function resolveWikilinkDetailed(db: Database, target: string): WikilinkResolution {
-  // 1. Exact match (case-insensitive)
+  // 1. Explicit-extension form: `[[path.ext]]`.
+  const extMatch = target.match(/^(.*)\.([a-z0-9]{1,16})$/i);
+  if (extMatch) {
+    const pathPart = extMatch[1]!;
+    const extPart = extMatch[2]!.toLowerCase();
+    const explicit = db.prepare(
+      "SELECT id, path FROM notes WHERE path = ? COLLATE NOCASE AND LOWER(extension) = ?",
+    ).get(pathPart, extPart) as { id: string; path: string } | undefined;
+    if (explicit) {
+      return { resolved: true, note_id: explicit.id, path: explicit.path, candidates: [] };
+    }
+  }
+
+  // 2. Exact path match (case-insensitive). Multiple matches → ambiguous.
   const exact = db.prepare(
-    "SELECT id, path FROM notes WHERE path = ? COLLATE NOCASE",
-  ).get(target) as { id: string; path: string } | undefined;
-  if (exact) {
-    return { resolved: true, note_id: exact.id, path: exact.path, candidates: [] };
+    "SELECT id, path, extension FROM notes WHERE path = ? COLLATE NOCASE",
+  ).all(target) as { id: string; path: string; extension: string }[];
+  if (exact.length === 1) {
+    return { resolved: true, note_id: exact[0]!.id, path: exact[0]!.path, candidates: [] };
+  }
+  if (exact.length > 1) {
+    return {
+      resolved: false,
+      ambiguous: true,
+      candidates: exact.map((r) => ({ note_id: r.id, path: r.path })),
+    };
   }
 
-  // 2. Basename match
+  // 3. Basename match
   const basename = db.prepare(`
     SELECT id, path FROM notes
     WHERE path IS NOT NULL

package/package.json

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

package/src/cli.ts

@@ -2558,6 +2558,23 @@ async function cmdImport(args: string[]) {
     process.exit(1);
   }
 
+  // Daemon-busy guard (vault#323): the import opens its own bun:sqlite
+  // connection, but a running daemon already holds the writer lock. The
+  // first createNote then trips SQLITE_BUSY mid-stream and leaves a
+  // partially-replayed vault. Refuse with a clear error rather than
+  // attempt-and-fail. WAL/concurrent-writer is a separate follow-up.
+  const globalConfig = readGlobalConfig();
+  const port = globalConfig.port || DEFAULT_PORT;
+  const health = await checkHealth(port);
+  if (health.status === "healthy" || health.status === "unhealthy") {
+    console.error(
+      `error: vault daemon is running on port ${port}; stop it first with:\n` +
+        `  parachute stop vault\n` +
+        `the import requires exclusive write access to the SQLite database.`,
+    );
+    process.exit(1);
+  }
+
   // Autodetect: portable-md export → `.parachute/vault.yaml` present.
   const isPortableMd = existsSync(join(fullPath, ".parachute", "vault.yaml"));
 

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

@@ -0,0 +1,109 @@
+/**
+ * Integration test for vault#323: `parachute-vault import` refuses to run
+ * when a daemon is bound to the configured port. The import opens its
+ * own bun:sqlite connection; concurrent writers would otherwise trip
+ * SQLITE_BUSY mid-replay and leave a partially-imported vault.
+ *
+ * Pre-flights checkHealth(port) before any DB write; "healthy" or
+ * "unhealthy" (port bound, any HTTP response) means the daemon owns the
+ * writer lock, so we exit 1 with a clear error pointing at
+ * `parachute stop vault`.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { resolve } from "path";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+const CLI = resolve(import.meta.dir, "cli.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 };
+}
+
+let home: string;
+let srcDir: string;
+
+beforeEach(() => {
+  home = mkdtempSync(join(tmpdir(), "import-daemon-busy-"));
+  srcDir = mkdtempSync(join(tmpdir(), "import-daemon-busy-src-"));
+  // Minimal portable-md export shape so autodetect picks the portable path.
+  mkdirSync(join(srcDir, ".parachute"), { recursive: true });
+  writeFileSync(
+    join(srcDir, ".parachute", "vault.yaml"),
+    "name: default\nexport_format_version: 1\n",
+  );
+  // Minimal vault tree so the "vault not found" guard doesn't short-circuit.
+  // PARACHUTE_HOME → <root>/vault/{config.yaml, data/<name>/vault.yaml}.
+  mkdirSync(join(home, "vault", "data", "default"), { recursive: true });
+  writeFileSync(
+    join(home, "vault", "data", "default", "vault.yaml"),
+    "name: default\n",
+  );
+});
+
+afterEach(() => {
+  rmSync(home, { recursive: true, force: true });
+  rmSync(srcDir, { recursive: true, force: true });
+});
+
+describe("import daemon-busy guard (vault#323)", () => {
+  test("refuses with clear error + exit 1 when a server is bound to the configured port", async () => {
+    // Stand up a stub server that responds on /health so checkHealth
+    // returns either `healthy` or `unhealthy` — both signal that the
+    // port is owned by something. Either case triggers the guard.
+    // Bind to 127.0.0.1 explicitly so the subprocess's checkHealth
+    // (which probes 127.0.0.1:<port>) hits the same interface.
+    const server = Bun.serve({
+      port: 0,
+      hostname: "127.0.0.1",
+      fetch: () => new Response(JSON.stringify({ status: "ok" })),
+    });
+    try {
+      mkdirSync(join(home, "vault"), { recursive: true });
+      writeFileSync(join(home, "vault", "config.yaml"), `port: ${server.port}\n`);
+      const res = await runCli(
+        ["import", srcDir, "--vault", "default", "--yes"],
+        { PARACHUTE_HOME: home },
+      );
+      expect(res.exitCode).toBe(1);
+      expect(res.stderr).toMatch(/vault daemon is running on port/);
+      expect(res.stderr).toMatch(/parachute stop vault/);
+    } finally {
+      server.stop(true);
+    }
+  });
+
+  test("proceeds past the guard when nothing is listening on the configured port", async () => {
+    // Pick a port nothing's bound to. The daemon-busy message must NOT
+    // surface — that's the regression we're pinning.
+    const freePort = 1; // privileged, nothing should be listening here from this process
+    mkdirSync(join(home, "vault"), { recursive: true });
+    writeFileSync(join(home, "vault", "config.yaml"), `port: ${freePort}\n`);
+    const res = await runCli(
+      ["import", srcDir, "--vault", "default", "--yes"],
+      { PARACHUTE_HOME: home },
+    );
+    expect(res.stderr).not.toMatch(/vault daemon is running on port/);
+  });
+});

package/src/published.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect } from "bun:test";
+import { Database } from "bun:sqlite";
 import { handleViewNote } from "./routes.ts";
+import { SqliteStore } from "../core/src/store.ts";
 
 // Redirect URL builder — mirrors the logic in server.ts
 function buildRedirectUrl(reqUrl: string, noteId: string, prefix = ""): string {
@@ -211,4 +213,19 @@ describe("handleViewNote", async () => {
     const resp = await handleViewNote(store, "n1", { publishedTag: "public" });
     expect(resp.status).toBe(404);
   });
+
+  it("returns 409 ambiguous_path when bare path resolves to multiple notes (vault#331 N1)", async () => {
+    // Real SqliteStore so the v18 composite (path, extension) uniqueness
+    // index lets two notes coexist at the same path with different
+    // extensions — the scenario AmbiguousPathError is built for.
+    const store = new SqliteStore(new Database(":memory:"));
+    await store.createNote("# md", { id: "vn-md", path: "Foo", tags: ["publish"] });
+    await store.createNote("a,b\n1,2", { id: "vn-csv", path: "Foo", extension: "csv", tags: ["publish"] });
+    const resp = await handleViewNote(store, "Foo", { authenticated: true });
+    expect(resp.status).toBe(409);
+    const body = await resp.json() as any;
+    expect(body.error_type).toBe("ambiguous_path");
+    expect(body.path).toBe("Foo");
+    expect(body.candidates).toHaveLength(2);
+  });
 });