@openparachute/vault 0.4.3 → 0.4.4-rc.12

package/src/routes.ts

@@ -14,6 +14,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 { attachValidationStatus } from "../core/src/mcp.ts";
 import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
 import {
@@ -733,7 +734,13 @@ export async function handleNotes(
         }
       }
 
-      return json(body.notes ? created : created[0], 201);
+      // Attach `validation_status` so HTTP create-note matches the MCP
+      // surface (vault#287). Mirrors the MCP create-note attach site at
+      // `core/src/mcp.ts:451`. `attachValidationStatus` returns the note
+      // unchanged when no tag declares fields, so vaults without any tag
+      // schemas see no behavior change.
+      const final = created.map((n) => attachValidationStatus(store, db, n));
+      return json(body.notes ? final : final[0], 201);
     }
 
     return json({ error: "Method not allowed" }, 405);
@@ -847,15 +854,64 @@ export async function handleNotes(
   // PATCH /notes/:idOrPath — update (content, path, metadata, tags, links)
   if (method === "PATCH") {
     try {
+      // Body is parsed up front so the `if_missing: "create"` branch
+      // (vault#309) can fire when the note doesn't exist. Pre-#309
+      // shape parsed the body only after the not-found check.
+      const body = await req.json() as any;
       const note = await resolveNote(store, idOrPath);
-      if (!note) throw new NotFoundError(`Note not found: "${idOrPath}"`);
+      if (!note) {
+        // vault#309 — `if_missing: "create"` turns this PATCH into a
+        // create using the same payload. POST /notes is the canonical
+        // create surface, but supporting it inline on PATCH lets sync
+        // loops use one endpoint for both branches. Returns the
+        // created note with `created: true` and HTTP 200 (not 201 —
+        // the response shape is "the note as it now exists," same
+        // contract as the update path; `created: true` carries the
+        // signal).
+        if (body.if_missing === "create") {
+          const idOrPathStr = idOrPath;
+          // Tag-scope check on the create branch: the prospective
+          // tag set must still satisfy scope. Compute from body.tags
+          // (create-shape: an array, not the {add,remove} dict).
+          const tagsArr = Array.isArray(body.tags)
+            ? body.tags as string[]
+            : Array.isArray(body.tags?.add) ? body.tags.add as string[] : [];
+          if (tagScope.allowed && !tagsWithinScope(tagsArr, tagScope.allowed, tagScope.raw)) {
+            return tagScopeForbidden(tagScope.raw ?? []);
+          }
+          const idLooksLikePath = idOrPathStr.includes("/") || !/^[A-Za-z0-9_-]+$/.test(idOrPathStr);
+          const explicitPath = typeof body.path === "string" ? body.path as string : 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 } : {}),
+          };
+          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);
+          }
+          const final = await store.getNote(created.id);
+          if (!final) return json({ error: "Note disappeared" }, 500);
+          const validated = attachValidationStatus(store, db, final);
+          const includeContentResp = body.include_content !== false;
+          if (includeContentResp) return json({ ...validated, created: true });
+          const lean: any = toNoteIndex(validated);
+          const vs = (validated as any).validation_status;
+          if (vs !== undefined) lean.validation_status = vs;
+          lean.created = true;
+          return json(lean);
+        }
+        throw new NotFoundError(`Note not found: "${idOrPath}"`);
+      }
       // Tag-scope: existing note must be in scope. Mirror the read-side
       // 404-not-403 stance — a token can't see (and therefore can't
       // discover-then-modify) notes outside its allowlist.
       if (!noteWithinTagScope(note, tagScope.allowed, tagScope.raw)) {
         throw new NotFoundError(`Note not found: "${idOrPath}"`);
       }
-      const body = await req.json() as any;
       // Tag-scope: post-update tag set must still satisfy scope. Compute
       // the prospective tag set (existing − removed + added) and reject
       // before any write if it would drift outside the allowlist. This
@@ -1019,11 +1075,25 @@ export async function handleNotes(
       // Response shape: full Note (back-compat default) or lean NoteIndex
       // (vault#285 friction point 2.response — opt-out for callers making
       // frequent small edits to large notes). Mirror the MCP `update-note`
-      // `include_content` knob exactly.
+      // `include_content` knob exactly, *and* `validation_status` attachment
+      // (vault#287) so HTTP and MCP consumers see the same schema-validation
+      // signal. Recipe matches `core/src/mcp.ts:751` — attach to the full
+      // Note first, then carry the field across the lean conversion (since
+      // `toNoteIndex` drops unknown fields).
       const updatedNote = await store.getNote(note.id);
       if (updatedNote === null) return json({ error: "Note disappeared" }, 404);
+      const validated = attachValidationStatus(store, db, updatedNote);
       const includeContentResp = body.include_content !== false;
-      return json(includeContentResp ? updatedNote : toNoteIndex(updatedNote));
+      // `created: false` is appended to every update-path response so
+      // sync-loop callers using `if_missing: "create"` can distinguish
+      // the two branches without a separate query (vault#309). The
+      // create-branch response above carries `created: true`.
+      if (includeContentResp) return json({ ...validated, created: false });
+      const lean: any = toNoteIndex(validated);
+      const vs = (validated as any).validation_status;
+      if (vs !== undefined) lean.validation_status = vs;
+      lean.created = false;
+      return json(lean);
     } catch (e: any) {
       if (e instanceof NotFoundError) return json({ error: e.message }, 404);
       // Duck-type on `code` rather than `instanceof ConflictError`: this

package/src/vault.test.ts

@@ -2783,6 +2783,221 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     expect(body.id).toBe("big");
     expect(body.path).toBe("big");
   });
+
+  // vault#287 — HTTP must match MCP on validation_status attachment.
+  // Pre-#287 fix: MCP `update-note` attached validation_status; HTTP
+  // PATCH didn't. HTTP consumers using schema-validated vaults had no
+  // way to see schema warnings without re-reading + replaying validation
+  // client-side. These tests pin the symmetry on both response shapes
+  // (`include_content: true` and `false`) and confirm the no-schema
+  // case still returns no validation_status (advisory only — never
+  // forced onto vaults that don't declare fields).
+
+  test("PATCH attaches validation_status with enum_mismatch warning when tag schema is violated", async () => {
+    await store.upsertTagSchema("task287patch", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+    });
+    const note = await store.createNote("body", {
+      id: "p287a",
+      tags: ["task287patch"],
+      metadata: { priority: "high" },
+    });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/p287a", {
+        metadata: { priority: "ULTRA" },
+        if_updated_at: note.updatedAt,
+      }),
+      store,
+      "/p287a",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    // The write still lands — validation is advisory.
+    expect(body.metadata.priority).toBe("ULTRA");
+    // …but the response carries the warning so the HTTP caller knows.
+    expect(body.validation_status).toBeTruthy();
+    expect(body.validation_status.schemas).toContain("task287patch");
+    expect(body.validation_status.warnings.length).toBeGreaterThan(0);
+    expect(body.validation_status.warnings[0].reason).toBe("enum_mismatch");
+    expect(body.validation_status.warnings[0].field).toBe("priority");
+  });
+
+  test("PATCH preserves validation_status on the lean (include_content: false) response", async () => {
+    await store.upsertTagSchema("task287lean", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+    });
+    const note = await store.createNote("body", {
+      id: "p287b",
+      tags: ["task287lean"],
+      metadata: { priority: "high" },
+    });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/p287b", {
+        metadata: { priority: "ULTRA" },
+        include_content: false,
+        if_updated_at: note.updatedAt,
+      }),
+      store,
+      "/p287b",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    // Lean shape: no `content`, has `byteSize` + `preview`.
+    expect(body.content).toBeUndefined();
+    expect(typeof body.byteSize).toBe("number");
+    // …and validation_status survives the lean conversion.
+    expect(body.validation_status).toBeTruthy();
+    expect(body.validation_status.warnings[0].reason).toBe("enum_mismatch");
+  });
+
+  test("PATCH omits validation_status when no tag on the note declares fields", async () => {
+    // No tag schemas configured for this note — the response should look
+    // exactly like the pre-#287 shape (no validation_status). The behavior-
+    // unchanged guarantee for callers that don't use tag schemas.
+    await store.createNote("body", { id: "p287c", tags: ["plain"] });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/p287c", { content: "updated", force: true }),
+      store,
+      "/p287c",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.content).toBe("updated");
+    expect(body.validation_status).toBeUndefined();
+  });
+});
+
+describe("HTTP POST /notes — validation_status attachment (vault#287)", async () => {
+  // Mirror of the PATCH cases for create. The MCP create-note path
+  // attaches validation_status; HTTP POST must match (vault#287).
+
+  test("POST attaches validation_status with type_mismatch warning", async () => {
+    await store.upsertTagSchema("task287post", {
+      fields: { done: { type: "boolean" } },
+    });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        content: "x",
+        tags: ["task287post"],
+        metadata: { done: "yes" }, // wrong type
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.id).toBeTruthy();
+    expect(body.validation_status).toBeTruthy();
+    expect(body.validation_status.warnings[0].reason).toBe("type_mismatch");
+    expect(body.validation_status.warnings[0].field).toBe("done");
+  });
+
+  test("POST batch attaches validation_status per-note", async () => {
+    await store.upsertTagSchema("task287batch", {
+      fields: { priority: { type: "string", enum: ["high", "low"] } },
+    });
+    const res = await handleNotes(
+      mkReq("POST", "/notes", {
+        notes: [
+          { content: "good", tags: ["task287batch"], metadata: { priority: "high" } },
+          { content: "bad", tags: ["task287batch"], metadata: { priority: "ULTRA" } },
+        ],
+      }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any[];
+    expect(body).toHaveLength(2);
+    expect(body[0].validation_status.warnings).toEqual([]);
+    expect(body[1].validation_status.warnings[0].reason).toBe("enum_mismatch");
+  });
+
+  test("POST omits validation_status when no tag declares fields (back-compat)", async () => {
+    const res = await handleNotes(
+      mkReq("POST", "/notes", { content: "no schema here", tags: ["plain287"] }),
+      store,
+      "",
+    );
+    expect(res.status).toBe(201);
+    const body = await res.json() as any;
+    expect(body.id).toBeTruthy();
+    expect(body.validation_status).toBeUndefined();
+  });
+});
+
+// vault#309 — HTTP PATCH /notes/:id with if_missing: "create" mirrors
+// the MCP update-note path. Sync loops (Gitcoin Brain et al) use this
+// for idempotent upsert without a separate query-first round trip.
+
+describe("HTTP PATCH /notes/:idOrPath if_missing=create (vault#309)", async () => {
+  test("missing note + if_missing=create creates and returns created: true", async () => {
+    const res = await handleNotes(
+      mkReq("PATCH", `/notes/${encodeURIComponent("Inbox/m309a")}`, {
+        content: "agenda body",
+        tags: ["meeting309"],
+        metadata: { priority: "high" },
+        if_missing: "create",
+      }),
+      store,
+      `/${encodeURIComponent("Inbox/m309a")}`,
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.created).toBe(true);
+    expect(body.path).toBe("Inbox/m309a");
+    expect(body.content).toBe("agenda body");
+    expect(body.tags).toContain("meeting309");
+    expect(body.metadata.priority).toBe("high");
+    // And the row landed.
+    expect(await store.getNoteByPath("Inbox/m309a")).not.toBeNull();
+  });
+
+  test("existing note + if_missing=create updates and returns created: false", async () => {
+    await store.createNote("original", { path: "m309b", metadata: { v: 1 } });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/m309b", {
+        content: "updated body",
+        metadata: { v: 2 },
+        if_missing: "create",
+        force: true,
+      }),
+      store,
+      "/m309b",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.created).toBe(false);
+    expect(body.content).toBe("updated body");
+    expect(body.metadata.v).toBe(2);
+  });
+
+  test("missing note without if_missing returns 404 (back-compat)", async () => {
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/m309c-nope", {
+        content: "x",
+        force: true,
+      }),
+      store,
+      "/m309c-nope",
+    );
+    expect(res.status).toBe(404);
+  });
+
+  test("regular update path now also carries created: false (response shape extended)", async () => {
+    await store.createNote("body", { path: "m309d" });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/m309d", {
+        content: "new body",
+        force: true,
+      }),
+      store,
+      "/m309d",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.created).toBe(false);
+  });
 });
 
 describe("HTTP /tags", async () => {