@openparachute/vault 0.4.4-rc.12 → 0.4.5

package/src/routes.ts

@@ -13,7 +13,7 @@
 
 import type { Store, Note } from "../core/src/types.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
-import { toNoteIndex, filterMetadata, MAX_BATCH_SIZE } from "../core/src/notes.ts";
+import { toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
 import { attachValidationStatus } from "../core/src/mcp.ts";
 import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
@@ -75,6 +75,25 @@ function parseQueryList(url: URL, key: string): string[] | undefined {
   return val ? val.split(",") : undefined;
 }
 
+/**
+ * Parse the extension query parameter (vault#328). Two accepted shapes:
+ *   - `?extension=csv` (single value → string)
+ *   - `?extension=csv&extension=yaml` OR `?extension=csv,yaml`
+ *     (repeated or comma-list → array)
+ * Returns undefined when absent so the queryNotes filter is skipped.
+ * Validation lives at the engine layer — bad strings result in zero
+ * matches rather than 400, mirroring how `path` works.
+ */
+function parseExtensionFilter(url: URL): string | string[] | undefined {
+  const all = url.searchParams.getAll("extension");
+  if (all.length === 0) return undefined;
+  // Flatten comma-lists inside each param.
+  const flat = all.flatMap((v) => v.split(",")).map((s) => s.trim()).filter((s) => s.length > 0);
+  if (flat.length === 0) return undefined;
+  if (flat.length === 1) return flat[0]!;
+  return flat;
+}
+
 function parseInt10(val: string | null): number | undefined {
   if (!val) return undefined;
   const n = parseInt(val, 10);
@@ -373,11 +392,21 @@ function parseExpandParams(
 
 
 /**
- * Resolve a note by ID or path. Tries ID first, then case-insensitive path.
+ * Resolve a note by ID or path. Tries ID first, then case-insensitive
+ * path. A trailing `.<ext>` matching the extension pattern is parsed
+ * as `(path, extension)` to disambiguate notes sharing a path
+ * differing only by extension (vault#330 S1). When the path is
+ * ambiguous and no extension hint is supplied, `getNoteByPath` throws
+ * `AmbiguousPathError` — REST handlers catch it and return 409.
  */
 async function resolveNote(store: Store, idOrPath: string): Promise<Note | null> {
   const byId = await store.getNote(idOrPath);
   if (byId) return byId;
+  const extMatch = idOrPath.match(/^(.*)\.([a-z0-9]{1,16})$/i);
+  if (extMatch) {
+    const explicit = await store.getNoteByPath(extMatch[1]!, extMatch[2]!);
+    if (explicit) return explicit;
+  }
   return await store.getNoteByPath(idOrPath);
 }
 
@@ -398,12 +427,49 @@ class NotFoundError extends Error {
 // Notes — GET/POST/PATCH/DELETE /api/notes[/:idOrPath]
 // ---------------------------------------------------------------------------
 
+/**
+ * Convert a thrown `AmbiguousPathError` (vault#330 S1) into a structured
+ * 409 JSON response. Shared by every handler that calls `resolveNote`
+ * with a user-supplied path — handleNotes, handleFindPath,
+ * handleViewNote. Returns null when the error isn't an
+ * AmbiguousPathError so the caller can re-throw / fall through.
+ */
+function ambiguousPathResponse(e: any): Response | null {
+  if (!e || e.code !== "AMBIGUOUS_PATH") return null;
+  return json(
+    {
+      error_type: "ambiguous_path",
+      error: "ambiguous_path",
+      path: e.path,
+      candidates: e.candidates,
+      message: e.message,
+    },
+    409,
+  );
+}
+
 export async function handleNotes(
   req: Request,
   store: Store,
   subpath: string,
   vault?: string,
   tagScope: TagScopeCtx = NO_TAG_SCOPE,
+): Promise<Response> {
+  try {
+    return await handleNotesInner(req, store, subpath, vault, tagScope);
+  } catch (e: any) {
+    const ambig = ambiguousPathResponse(e);
+    if (ambig) return ambig;
+    throw e;
+  }
+}
+
+async function handleNotesInner(
+  req: Request,
+  store: Store,
+  subpath: string,
+  vault?: string,
+  tagScope: TagScopeCtx = NO_TAG_SCOPE,
 ): Promise<Response> {
   const url = new URL(req.url);
   const method = req.method;
@@ -508,6 +574,12 @@ export async function handleNotes(
           hasLinks: parseBoolOrUndef(parseQuery(url, "has_links")),
           path: parseQuery(url, "path") ?? undefined,
           pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
+          // Extension filter (vault#328). Accepts repeated `extension=`
+          // params for the array form: `?extension=csv&extension=yaml`.
+          // `parseQueryList` already returns undefined when no params
+          // are present, so the filter is silently skipped on a plain
+          // GET without the extension query.
+          extension: parseExtensionFilter(url),
           metadata: bracket.metadata,
           // Date-range precedence chain (highest to lowest):
           //   1. Bracket-style `meta[created_at][gte]=…` (canonical).
@@ -636,35 +708,10 @@ export async function handleNotes(
         );
       }
 
-      // Empty-note pre-validation (#213): walk the batch first and reject the
-      // whole request if any item would be content+path empty. This makes
-      // mixed batches atomic for the empty-note case — no caller gets a
-      // half-applied batch where the prefix landed and the empty entry
-      // surfaced the 400. Mirrors the Store-level invariant exactly.
-      for (let i = 0; i < items.length; i++) {
-        const item = items[i];
-        const content = (item?.content ?? "").toString();
-        const rawPath = item?.path;
-        const pathEmpty = rawPath === undefined || rawPath === null
-          || (typeof rawPath === "string" && rawPath.trim() === "");
-        if (!content.trim() && pathEmpty) {
-          return json(
-            {
-              error_type: "empty_note",
-              error: "EmptyNoteError",
-              message: `empty_note: a note must have either content or a path (item index ${i})`,
-              item_index: i,
-            },
-            400,
-          );
-        }
-      }
-
       // Tag-scope pre-validation: every new note in the batch must carry at
-      // least one tag inside the token's allowlist. Same atomic-batch
-      // discipline as the empty-note check — reject the whole request before
-      // any DB write so a tag-scoped token can't accidentally land a partial
-      // batch with an in-scope prefix.
+      // least one tag inside the token's allowlist. Reject the whole request
+      // before any DB write so a tag-scoped token can't accidentally land a
+      // partial batch with an in-scope prefix.
       if (tagScope.allowed) {
         for (let i = 0; i < items.length; i++) {
           if (!tagsWithinScope(items[i]?.tags, tagScope.allowed, tagScope.raw)) {
@@ -685,12 +732,19 @@ export async function handleNotes(
       if (batched) db.exec("BEGIN");
       try {
         for (const item of items) {
+          // Validate extension before reaching the Store (vault#328).
+          // Thrown inside the BEGIN block — outer catch rolls the batch
+          // back, same shape as the path-conflict path.
+          const extension = item.extension !== undefined
+            ? validateExtension(item.extension)
+            : undefined;
           const note = await store.createNote(item.content ?? "", {
             id: item.id,
             path: item.path,
             tags: item.tags,
             metadata: item.metadata,
             created_at: item.createdAt ?? item.created_at,
+            ...(extension !== undefined ? { extension } : {}),
           });
 
           // Create explicit links
@@ -713,14 +767,9 @@ export async function handleNotes(
             409,
           );
         }
-        if (e && e.code === "EMPTY_NOTE") {
+        if (e && e.code === "INVALID_EXTENSION") {
           return json(
-            {
-              error_type: "empty_note",
-              error: "EmptyNoteError",
-              message: e.message,
-              item_index: e.item_index ?? null,
-            },
+            { error_type: "invalid_extension", error: "invalid_extension", extension: e.extension, reason: e.reason, message: e.message },
             400,
           );
         }
@@ -881,18 +930,43 @@ export async function handleNotes(
           }
           const idLooksLikePath = idOrPathStr.includes("/") || !/^[A-Za-z0-9_-]+$/.test(idOrPathStr);
           const explicitPath = typeof body.path === "string" ? body.path as string : undefined;
+          // Validate extension before reaching the Store (vault#328).
+          const createExt = body.extension !== undefined
+            ? validateExtension(body.extension)
+            : undefined;
           const createOpts: Parameters<Store["createNote"]>[1] = {
             ...(idLooksLikePath ? { path: explicitPath ?? idOrPathStr } : { id: idOrPathStr, ...(explicitPath !== undefined ? { path: explicitPath } : {}) }),
             ...(tagsArr.length > 0 ? { tags: tagsArr } : {}),
             ...(body.metadata !== undefined ? { metadata: body.metadata as Record<string, unknown> } : {}),
             ...(body.created_at !== undefined ? { created_at: body.created_at as string } : {}),
             ...(body.createdAt !== undefined ? { created_at: body.createdAt as string } : {}),
+            ...(createExt !== undefined ? { extension: createExt } : {}),
           };
           const content = (body.content as string | undefined) ?? "";
           const created = await store.createNote(content, createOpts);
           if (tagsArr.length > 0) {
             await applySchemaDefaults(store, db, [created.id], tagsArr);
           }
+          // vault#321 F2 — apply `links.add` on the create branch.
+          // MCP's create-on-missing branch already did this
+          // (`core/src/mcp.ts` if_missing=create block); the REST side
+          // was missing it, producing a cross-surface inconsistency
+          // operators (Gitcoin's drift sync) would trip on. Mirror the
+          // MCP recipe exactly:
+          //   - `links.add` IS applied — drift sync can declare typed
+          //     links at upsert time and have them materialize.
+          //   - `links.remove` is ignored (nothing to remove on a
+          //     fresh note).
+          //   - Missing target notes skip silently (mirrors MCP).
+          const linksAdd = (body.links as any)?.add as { target: string; relationship: string; metadata?: Record<string, unknown> }[] | undefined;
+          if (linksAdd) {
+            for (const link of linksAdd) {
+              const target = await resolveNote(store, link.target);
+              if (target) {
+                await store.createLink(created.id, target.id, link.relationship, link.metadata);
+              }
+            }
+          }
           const final = await store.getNote(created.id);
           if (!final) return json({ error: "Note disappeared" }, 500);
           const validated = attachValidationStatus(store, db, final);
@@ -1035,6 +1109,11 @@ export async function handleNotes(
         if (body.prepend !== undefined) updates.prepend = body.prepend;
       }
       if (body.path !== undefined) updates.path = body.path;
+      if (body.extension !== undefined) {
+        // Validate up front (vault#328). Throws ExtensionValidationError
+        // which the outer catch converts to a 400.
+        updates.extension = validateExtension(body.extension);
+      }
       if (body.metadata !== undefined) {
         const existing = (note.metadata as Record<string, unknown>) ?? {};
         updates.metadata = { ...existing, ...body.metadata };
@@ -1124,17 +1203,9 @@ export async function handleNotes(
           409,
         );
       }
-      // Empty-note guard from the Store boundary (#213) — the proposed update
-      // would clear both content AND path. Surface as 400 so callers can fix
-      // the request without retrying.
-      if (e && e.code === "EMPTY_NOTE") {
+      if (e && e.code === "INVALID_EXTENSION") {
         return json(
-          {
-            error_type: "empty_note",
-            error: "EmptyNoteError",
-            message: e.message,
-            note_id: e.note_id ?? null,
-          },
+          { error_type: "invalid_extension", error: "invalid_extension", extension: e.extension, reason: e.reason, message: e.message },
           400,
         );
       }
@@ -1478,6 +1549,11 @@ export async function handleFindPath(
     return json(result);
   } catch (e: any) {
     if (e instanceof NotFoundError) return json({ error: e.message }, 404);
+    // vault#331 N1 — surface AmbiguousPathError from resolveNote as 409
+    // mirroring the handleNotes path. Without this, an ambiguous source/
+    // target path on /api/find-path bubbled to a server-level 500.
+    const ambig = ambiguousPathResponse(e);
+    if (ambig) return ambig;
     throw e;
   }
 }
@@ -1670,7 +1746,19 @@ export async function handleViewNote(
   options: { authenticated?: boolean; publishedTag?: string } = {},
 ): Promise<Response> {
   const { authenticated = false, publishedTag = "publish" } = options;
-  const note = await resolveNote(store, idOrPath);
+  let note: Note | null;
+  try {
+    note = await resolveNote(store, idOrPath);
+  } catch (e: any) {
+    // vault#331 N1 — surface AmbiguousPathError as 409. The HTML view
+    // route doesn't otherwise return JSON, but the structured body is
+    // the right shape for the API contract; a human reader hitting
+    // this URL gets the JSON inline (rare — the bare path form is
+    // mostly an API consumer's mistake).
+    const ambig = ambiguousPathResponse(e);
+    if (ambig) return ambig;
+    throw e;
+  }
   if (!note) {
     return new Response("Not Found", { status: 404, headers: { "Content-Type": "text/plain" } });
   }