@openparachute/vault 0.6.0 → 0.6.2-rc.1

package/src/routes.ts

@@ -15,6 +15,12 @@ import type { Store, Note, QueryOpts } from "../core/src/types.ts";
 import { TAG_EXPAND_MODES, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
 import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
+import {
+  parseContentRange,
+  applyContentRange,
+  contentRangeRequiresContent,
+  type ContentRange,
+} from "../core/src/content-range.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";
@@ -103,6 +109,37 @@ function parseQueryList(url: URL, key: string): string[] | undefined {
   return val ? val.split(",") : undefined;
 }
 
+/**
+ * Parse `?content_offset=` / `?content_length=` (content range — bounded
+ * reads for large notes; unit is UTF-8 bytes, see core/src/content-range.ts
+ * for the codepoint-boundary slicing rules). Returns `{ range: null }` when
+ * neither param is present (response byte-identical to the no-pagination
+ * shape), or `{ error }` (400 INVALID_QUERY) on invalid values or when the
+ * response shape excludes content — range params on a content-less shape
+ * error loudly rather than silently no-op, same policy as `?expand=`.
+ */
+function parseContentRangeQuery(
+  url: URL,
+  includeContent: boolean,
+): { range: ContentRange | null; error?: Response } {
+  try {
+    const range = parseContentRange(
+      parseQuery(url, "content_offset") ?? undefined,
+      parseQuery(url, "content_length") ?? undefined,
+    );
+    if (range && !includeContent) throw contentRangeRequiresContent();
+    return { range };
+  } catch (e: any) {
+    // Duck-type on `name` — core is a separate module, so `instanceof`
+    // is fragile across bundling boundaries (same note as the QueryError
+    // handling in the structured-query path below).
+    if (e && e.name === "QueryError") {
+      return { range: null, error: json({ error: e.message, code: e.code ?? "INVALID_QUERY" }, 400) };
+    }
+    throw e;
+  }
+}
+
 /**
  * Parse the extension query parameter (vault#328). Two accepted shapes:
  *   - `?extension=csv` (single value → string)
@@ -706,12 +743,18 @@ async function handleNotesInner(
           return json({ error: "Note not found", id }, 404);
         }
         const includeContent = parseBool(parseQuery(url, "include_content"), true);
+        const contentRange = parseContentRangeQuery(url, includeContent);
+        if (contentRange.error) return contentRange.error;
         let result: any = includeContent ? { ...note } : toNoteIndex(note);
         const expand = parseExpandParams(url, db, tagScope);
         if (expand && includeContent && typeof result.content === "string") {
           expand.ctx.expanded.add(note.id);
           result.content = expandContent(result.content, expand.ctx, expand.depth);
         }
+        // Content range applies to the FINAL returned content (post-
+        // expansion) — the window the client pages through is the same
+        // document it would have received unpaged.
+        if (contentRange.range && includeContent) applyContentRange(result, contentRange.range);
         result = filterMetadata(result, parseIncludeMetadata(url));
         if (parseBool(parseQuery(url, "include_links"), false)) {
           // Tag-scope: drop links whose neighbor is out of scope so the
@@ -769,6 +812,8 @@ async function handleNotesInner(
         // returns 200 [] (consistent with "no matches"), not 403.
         const results = filterNotesByTagScope(rawResults, tagScope.allowed, tagScope.raw);
         const includeContent = parseBool(parseQuery(url, "include_content"), false);
+        const contentRange = parseContentRangeQuery(url, includeContent);
+        if (contentRange.error) return contentRange.error;
         const inclMeta = parseIncludeMetadata(url);
         let output: any[] = includeContent ? results.map((n) => ({ ...n })) : results.map(toNoteIndex);
         const expand = parseExpandParams(url, db, tagScope);
@@ -780,6 +825,10 @@ async function handleNotesInner(
             }
           }
         }
+        // Content range — per-note, post-expansion (see core/src/content-range.ts).
+        if (contentRange.range && includeContent) {
+          for (const n of output) applyContentRange(n, contentRange.range);
+        }
         if (inclMeta !== undefined && inclMeta !== true) {
           output = output.map((n: any) => filterMetadata(n, inclMeta));
         }
@@ -910,6 +959,8 @@ async function handleNotesInner(
       results = filterNotesByTagScope(results, tagScope.allowed, tagScope.raw);
 
       const includeContent = parseBool(parseQuery(url, "include_content"), false);
+      const contentRange = parseContentRangeQuery(url, includeContent);
+      if (contentRange.error) return contentRange.error;
       const includeLinks = parseBool(parseQuery(url, "include_links"), false);
       const includeAttachments = parseBool(parseQuery(url, "include_attachments"), false);
       const includeLinkCount = parseBool(parseQuery(url, "include_link_count"), false);
@@ -924,6 +975,10 @@ async function handleNotesInner(
           }
         }
       }
+      // Content range — per-note, post-expansion (see core/src/content-range.ts).
+      if (contentRange.range && includeContent) {
+        for (const n of output) applyContentRange(n, contentRange.range);
+      }
       if (inclMeta !== undefined && inclMeta !== true) {
         output = output.map((n: any) => filterMetadata(n, inclMeta));
       }
@@ -952,8 +1007,9 @@ async function handleNotesInner(
         const nodes = output.map((n: any) => ({ id: n.id, path: n.path ?? null, tags: n.tags ?? [] }));
         const edges: { source: string; target: string; relationship: string }[] = [];
         if (includeLinks) {
+          const linksByNote = linkOps.getLinksHydratedForNotes(db, results.map((n) => n.id));
           for (const n of results) {
-            for (const link of linkOps.getLinksHydrated(db, n.id)) {
+            for (const link of linksByNote.get(n.id) ?? []) {
               // Only include edges where source is this note and target is in the result set
               if (link.sourceId === n.id && resultIds.has(link.targetId)) {
                 edges.push({ source: link.sourceId, target: link.targetId, relationship: link.relationship });
@@ -965,13 +1021,19 @@ async function handleNotesInner(
       }
 
       if (includeLinks || includeAttachments) {
+        // Whole-page link hydration in a constant number of queries — the
+        // per-note variant cost (1 link query + 1 summary query + N tag
+        // queries) × page size. 2026-06-10 perf measurements.
+        const linksByNote = includeLinks
+          ? linkOps.getLinksHydratedForNotes(db, output.map((n: any) => n.id))
+          : null;
         const enrichedOut: any[] = [];
         for (const n of output) {
           const enriched: any = { ...n };
-          if (includeLinks) {
+          if (linksByNote) {
             // Tag-scope: strip out-of-scope-neighbor links (no-op unscoped).
             enriched.links = filterHydratedLinksByTagScope(
-              linkOps.getLinksHydrated(db, n.id),
+              linksByNote.get(n.id) ?? [],
               tagScope.allowed,
               tagScope.raw,
             );
@@ -1252,12 +1314,16 @@ async function handleNotesInner(
       return json({ error: "Not found" }, 404);
     }
     const includeContent = parseBool(parseQuery(url, "include_content"), true);
+    const contentRange = parseContentRangeQuery(url, includeContent);
+    if (contentRange.error) return contentRange.error;
     let result: any = includeContent ? { ...note } : toNoteIndex(note);
     const expand = parseExpandParams(url, db, tagScope);
     if (expand && includeContent && typeof result.content === "string") {
       expand.ctx.expanded.add(note.id);
       result.content = expandContent(result.content, expand.ctx, expand.depth);
     }
+    // Content range applies to the FINAL returned content (post-expansion).
+    if (contentRange.range && includeContent) applyContentRange(result, contentRange.range);
     result = filterMetadata(result, parseIncludeMetadata(url));
     if (parseBool(parseQuery(url, "include_links"), false)) {
       // Tag-scope: drop out-of-scope-neighbor links (no-op unscoped).

package/src/routing.ts

@@ -87,6 +87,7 @@ import {
   handleAuthGet,
   handleAuthGithubCreateRepo,
   handleAuthGithubDeviceCode,
+  handleAuthGithubInstallations,
   handleAuthGithubPoll,
   handleAuthGithubRepos,
   handleAuthGithubSelectRepo,
@@ -735,6 +736,13 @@ export async function route(
       if (req.method === "POST") return handleAuthGithubPoll(req, manager);
       return Response.json({ error: "Method not allowed" }, { status: 405 });
     }
+    if (subpath === "/.parachute/mirror/auth/github/installations") {
+      // Install state (vault#480) — which app, installed-anywhere?, install
+      // link, per-account installations. Explicitly-network (probes GitHub);
+      // the offline status read stays on GET /.parachute/mirror/auth.
+      if (req.method === "GET") return handleAuthGithubInstallations(manager);
+      return Response.json({ error: "Method not allowed" }, { status: 405 });
+    }
     if (subpath === "/.parachute/mirror/auth/github/repos") {
       if (req.method === "GET") return handleAuthGithubRepos(manager);
       return Response.json({ error: "Method not allowed" }, { status: 405 });

package/src/vault.test.ts

@@ -4543,6 +4543,62 @@ describe("HTTP PATCH /notes/:idOrPath if_missing=create (vault#309)", async () =
     expect(body.metadata.v).toBe(2);
   });
 
+  // Cross-repo guard for the parachute-agent #agent/thread upsert seam: a single-threaded
+  // thread note lives at a SLASH path (e.g. "Threads/<channel>/<name>") and the agent
+  // module addresses it as ONE URL segment via encodeURIComponent (so `/`→`%2F`). The
+  // full round-trip it relies on — GET an existing note by the encoded-slash path
+  // (readThreadNote read-back) then PATCH-update it by the same encoded-slash path
+  // (if_missing:create upsert, turn 2) — must resolve to the decoded path, or the agent's
+  // turn_count/usage aggregates silently reset every turn. This proves the route resolves
+  // the encoded slash on GET + PATCH-update of an EXISTING note (4505 above only covers
+  // create). See parachute-agent#110.
+  test("encoded-slash path round-trips: GET read-back + PATCH-update resolve a %2F path (the #agent/thread upsert seam)", async () => {
+    const enc = encodeURIComponent("Threads/eng/eng");
+    expect(enc).toBe("Threads%2Feng%2Feng"); // no literal slash — one URL segment.
+
+    // Turn 1 — PATCH if_missing:create by the encoded-slash path → CREATES.
+    const create = await handleNotes(
+      mkReq("PATCH", `/notes/${enc}`, {
+        content: "## Summary\n\nturn 1",
+        tags: ["#agent/thread"],
+        metadata: { turn_count: "1", status: "ok" },
+        if_missing: "create",
+        force: true,
+      }),
+      store,
+      `/${enc}`,
+    );
+    expect(create.status).toBe(200);
+    expect((await create.json() as any).created).toBe(true);
+
+    // Read-back — GET by the SAME encoded-slash path resolves the created note (NOT 404).
+    const get = await handleNotes(mkReq("GET", `/notes/${enc}`), store, `/${enc}`);
+    expect(get.status).toBe(200);
+    const got = await get.json() as any;
+    expect(got.path).toBe("Threads/eng/eng");
+    expect(got.metadata.turn_count).toBe("1");
+
+    // Turn 2 — PATCH if_missing:create by the SAME encoded-slash path → UPDATES in place.
+    const update = await handleNotes(
+      mkReq("PATCH", `/notes/${enc}`, {
+        content: "## Summary\n\nturn 2",
+        metadata: { turn_count: "2", status: "ok" },
+        if_missing: "create",
+        force: true,
+      }),
+      store,
+      `/${enc}`,
+    );
+    expect(update.status).toBe(200);
+    expect((await update.json() as any).created).toBe(false); // updated, NOT a second note.
+
+    // Exactly ONE note at the decoded path, updated (the upsert worked end-to-end).
+    const final = await store.getNoteByPath("Threads/eng/eng");
+    expect(final).not.toBeNull();
+    expect(String(final!.metadata.turn_count)).toBe("2");
+    expect(final!.content).toContain("turn 2");
+  });
+
   test("missing note without if_missing returns 404 (back-compat)", async () => {
     const res = await handleNotes(
       mkReq("PATCH", "/notes/m309c-nope", {