src/portal-library.ts

Functions

Imports

It imports src/doc-reads.ts, src/env.ts, src/http.ts, src/limits.ts, src/ops-feed.ts, src/ops-types/views.ts, src/portal-auth.ts. Imported by src/routes.ts.

Source

1import type { Env } from "./env";
2import { documentEdges, readDocument, searchDocuments } from "./doc-reads";
3import { MAX_NAMESPACE, MAX_QUERY, MAX_ROWS, pathProblem, SEARCH_ROWS } from "./limits";
4import { OPS_RETURN_TO } from "./ops-feed";
5import type { LibraryEntry, LibraryShelf, PortalLibrary } from "./ops-types/views";
6import { portalGate } from "./portal-auth";
7import { jsonResponse as json } from "./http";
8
9// The Portal's Library: GET /portal/api/library, read-only, over the knowledge store
10// (search, decisions, rulings, research, links to jobs). Writing stays in chat and with drivers.
11// Search, one document and its edges go through src/doc-reads.ts, the readers behind
12// capsid_find_docs and capsid_read_doc, so the Library and chat cannot disagree. A route,
13// not a tool, so no grant is checked here (one enforcement point, test/route-gates.test.ts): it
14// answers to portalGate, and src/scope.ts lists it among the routes gated some other way.
15// It writes nothing, not even the conventions-read row: that row records an agent
16// loading the rules, and the Portal is the administrator reading them.
17
18export const PORTAL_LIBRARY_PATH = "/portal/api/library";
19
20// The marks around a matched word in a search's snippet: control characters no document
21// holds, so brackets in the text (a Markdown link) are never taken for a match.
22const LIBRARY_MARK_OPEN = "\u0002";
23const LIBRARY_MARK_CLOSE = "\u0003";
24
25/** Which shelf a row belongs on: a decision record first, then by its folder. */
26function shelfOf(row: Pick<LibraryEntry, "type" | "path">): LibraryShelf {
27  if (row.type === "decision") return "decisions";
28  return row.path.startsWith("rulings/") ? "rulings" : "research";
29}
30
31function param(url: URL, name: string): string | null {
32  const raw = url.searchParams.get(name)?.trim();
33  return raw ? raw : null;
34}
35
36/** GET /portal/api/library: the shelves, ?q= a search, or ?ns=&path= one document. */
37export async function handlePortalLibrary(request: Request, env: Env, now: Date = new Date()): Promise<Response> {
38  const gate = await portalGate(request, env, now, OPS_RETURN_TO);
39  if (!gate.ok) return gate.response;
40  const url = new URL(request.url);
41  const generated = now.toISOString();
42  const q = param(url, "q");
43  const ns = param(url, "ns");
44  const path = param(url, "path");
45
46  if (ns !== null || path !== null) {
47    if (ns === null || path === null) return json({ error: "A document is named by both ns and path." }, 400);
48    if (ns.length > MAX_NAMESPACE) return json({ error: `ns is longer than ${MAX_NAMESPACE} characters.` }, 400);
49    const problem = pathProblem(path);
50    if (problem) return json({ error: `${problem}.` }, 400);
51    const [row, edges] = await Promise.all([readDocument(env.DB, ns, path), documentEdges(env.DB, ns, path)]);
52    if (!row) return json({ error: `No document ${ns}/${path}.` }, 404);
53    const { id: _id, ...doc } = row;
54    const body: PortalLibrary = { kind: "document", generated, doc, ...edges };
55    return json(body);
56  }
57
58  if (q !== null) {
59    if (q.length > MAX_QUERY) return json({ error: `The search is longer than ${MAX_QUERY} characters.` }, 400);
60    let rows: Awaited<ReturnType<typeof searchDocuments>>;
61    try {
62      rows = await searchDocuments(env.DB, q, { namespace: null, type: null, allowed: null, marks: { open: LIBRARY_MARK_OPEN, close: LIBRARY_MARK_CLOSE } });
63    } catch (err) {
64      // A query FTS5 refuses is retried as a quoted phrase, which it always accepts, so a
65      // second refusal is the store failing, not the caller's input.
66      return json({ error: `The search could not run: ${err instanceof Error ? err.message : String(err)}` }, 500);
67    }
68    const truncated = rows.length > SEARCH_ROWS;
69    const body: PortalLibrary = {
70      kind: "search",
71      generated,
72      query: q,
73      rows: rows.slice(0, SEARCH_ROWS).map(({ id: _id, ...r }) => r),
74      truncated,
75    };
76    return json(body);
77  }
78
79  // The shelves, one statement over every namespace, written inline so the query-plan
80  // walk reads it. ORDER BY namespace, path walks the (namespace, path) unique
81  // index, so the read stops at the LIMIT and never bare-scans documents
82  // (test-integration/query-plans.test.ts). archive/ is history, not a shelf.
83  const { results } = await env.DB.prepare(
84    `SELECT namespace, path, title, type, status, updated_at
85     FROM documents
86     WHERE (type = 'decision' OR path GLOB 'rulings/*' OR path GLOB 'research/*') AND path NOT GLOB 'archive/*'
87     ORDER BY namespace, path
88     LIMIT ?1`
89  )
90    .bind(MAX_ROWS + 1)
91    .all<LibraryEntry>();
92  const shelves: Record<LibraryShelf, LibraryEntry[]> = { decisions: [], rulings: [], research: [] };
93  for (const row of results.slice(0, MAX_ROWS)) shelves[shelfOf(row)].push(row);
94  const body: PortalLibrary = { kind: "shelves", generated, shelves, truncated: results.length > MAX_ROWS };
95  return json(body);
96}