src/portfolio-docs.ts

Functions

Imports

It imports no other module of this repo. Imported by src/scope.ts, src/tools/docs-read.ts.

Source

1// The portfolio documents every namespace driver may READ in capsid, and nothing else
2// there.
3//
4// Every repo's CLAUDE.md tells a session to follow capsid/conventions.md and Dustin's
5// rulings, but a driver minted for one namespace was refused all of
6// them, so it worked from its repo's CLAUDE.md and the job bodies alone. This is the
7// one statement of what crosses that boundary. checkScope (src/scope.ts) admits a read
8// of a path matched here, the list, glob and search handlers drop every other capsid
9// row for such a caller, and the session start names the documents that exist. Nothing else in
10// capsid (research, policy, jobs, reports, episodics) is reachable, and no write is.
11//
12// test/portfolio-docs.test.ts pins this constant.
13export const PORTFOLIO_DOCS = {
14  namespace: "capsid",
15  // Exact paths. conventions.md is the one rules file.
16  documents: ["conventions.md", "core.md"],
17  // An archived decisions volume: the prefix, then a volume number, then ".md". The
18  // old decisions log is history kept under archive/; new rulings go in rulings/.
19  volumes: ["archive/decisions-vol-"],
20  // One document directly inside the folder, no deeper. One ruling per file.
21  folders: ["rulings/"],
22  // The tool actions that may reach capsid for such a caller, as tool.action. Each
23  // requires only the read grant (TOOL_GRANTS). A document's versions and links stay
24  // out: a version list or an edge can name a capsid path that is not on this list.
25  tools: ["capsid_read_doc.read", "capsid_find_docs.list", "capsid_find_docs.glob", "capsid_find_docs.search"],
26} as const;
27
28// A path is matched against this before anything else: lowercase letters, digits, dot,
29// dash, underscore and slash only. So a percent-encoding, a backslash, a space or a
30// capital letter cannot reach a comparison, whatever the database or a later decoder
31// would make of it. Stored paths are case-sensitive, and every portfolio path is
32// lowercase.
33const SAFE_PATH = /^[a-z0-9][a-z0-9._/-]*$/;
34const VOLUME = /^[1-9][0-9]{0,3}\.md$/;
35const FOLDER_ENTRY = /^[a-z0-9][a-z0-9._-]*\.md$/;
36
37/** Whether a capsid path is one of the portfolio documents. */
38export function isPortfolioPath(path: string): boolean {
39  if (typeof path !== "string" || !SAFE_PATH.test(path)) return false;
40  // No traversal and no empty segment, even though nothing here resolves a path: the
41  // test is on the string, and "rulings/../policy/gates.md" must not read as rulings/.
42  if (path.includes("..") || path.includes("//") || path.endsWith("/")) return false;
43  if ((PORTFOLIO_DOCS.documents as readonly string[]).includes(path)) return true;
44  for (const prefix of PORTFOLIO_DOCS.volumes) {
45    if (path.startsWith(prefix) && VOLUME.test(path.slice(prefix.length))) return true;
46  }
47  for (const folder of PORTFOLIO_DOCS.folders) {
48    if (path.startsWith(folder) && FOLDER_ENTRY.test(path.slice(folder.length))) return true;
49  }
50  return false;
51}
52
53/** Whether a tool action may reach the portfolio documents for a caller outside capsid. */
54export function isPortfolioTool(tool: string, action: string | undefined): boolean {
55  return action !== undefined && (PORTFOLIO_DOCS.tools as readonly string[]).includes(`${tool}.${action}`);
56}
57
58/** The allowlist as a reader sees it, for a refusal and for brief. */
59export function describePortfolioDocs(): string[] {
60  return [
61    ...PORTFOLIO_DOCS.documents,
62    ...PORTFOLIO_DOCS.volumes.map((v) => `${v}<n>.md`),
63    ...PORTFOLIO_DOCS.folders.map((f) => `${f}<name>.md`),
64  ];
65}
66
67export interface PortfolioRow {
68  namespace: string;
69  path: string;
70  title: string | null;
71  type: string | null;
72  status: string | null;
73  tags: string | null;
74  created_at: string;
75  updated_at: string;
76}
77
78/** The portfolio documents that exist, metadata only, ordered by path. The query
79 *  narrows by the exact paths and a GLOB per volume prefix and folder; isPortfolioPath
80 *  then decides, so the GLOB's looser match (a nested rulings path, a non-numeric
81 *  volume) never reaches a caller. */
82export async function portfolioDocuments(db: D1Database): Promise<PortfolioRow[]> {
83  const globs = [...PORTFOLIO_DOCS.volumes, ...PORTFOLIO_DOCS.folders].map((p) => `${p}*`);
84  const { results } = await db
85    .prepare(
86      `SELECT namespace, path, title, type, status, tags, created_at, updated_at
87       FROM documents
88       WHERE namespace = ?1
89         AND (path IN (SELECT value FROM json_each(?2)) OR EXISTS (SELECT 1 FROM json_each(?3) AS g WHERE documents.path GLOB g.value))
90       ORDER BY path`
91    )
92    .bind(PORTFOLIO_DOCS.namespace, JSON.stringify(PORTFOLIO_DOCS.documents), JSON.stringify(globs))
93    .all<PortfolioRow>();
94  return results.filter((r) => isPortfolioPath(r.path));
95}