@docsworth/cli 0.0.0-stage → 0.3.0

package/dist/core/repo.d.ts

@@ -0,0 +1,46 @@
+import { type Codeowners } from "./codeowners.js";
+import { type Config } from "./config.js";
+import { type FieldIssue, type Frontmatter } from "./schema.js";
+export interface Page extends Frontmatter {
+    /** Repo-relative posix path, e.g. `knowledge/runbooks/deploy.md`. */
+    path: string;
+    body: string;
+    headings: string[];
+    /** Relative markdown link targets as written (anchors stripped). */
+    links: string[];
+    sha256: string;
+    unknownFields: string[];
+    /** Its frontmatter `slug`, if a string: where a docs site serves it (`siteRoute`). Not in the format; read for redaction and lint. */
+    slug?: string;
+}
+export interface InvalidPage {
+    path: string;
+    /** The `id` field if present and a string, so lint can still report duplicates. */
+    id?: string;
+    /** The `slug` field if a string: redaction hides the route it gives the page too. */
+    slug?: string;
+    issues: FieldIssue[];
+}
+export interface Repo {
+    root: string;
+    config: Config;
+    codeowners: Codeowners;
+    pages: Page[];
+    invalid: InvalidPage[];
+    byId: Map<string, Page>;
+    byPath: Map<string, Page>;
+}
+/** Relative link targets (inline and reference definitions), without query or fragment. */
+export declare function extractLinks(body: string): string[];
+export declare function extractHeadings(body: string): string[];
+/** Resolve a relative link from a page to a repo-relative posix path. */
+export declare function resolveLink(fromPath: string, target: string): string;
+export declare function parsePage(path: string, text: string): Page | InvalidPage;
+export declare function isPage(p: Page | InvalidPage): p is Page;
+/**
+ * Load a knowledge repo from disk. Pages with invalid frontmatter are kept out of
+ * `pages` (nothing downstream may serve them) and reported in `invalid` for the linter.
+ */
+export declare function loadRepo(root: string, config?: Config): Repo;
+/** Latest mtime under the knowledge dir; the MCP server uses it to detect edits. */
+export declare function knowledgeMtime(root: string, config: Config): number;

package/dist/core/repo.js

@@ -0,0 +1,118 @@
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, posix, relative, sep } from "node:path";
+import { loadCodeowners } from "./codeowners.js";
+import { loadConfig } from "./config.js";
+import { splitFrontmatter } from "./frontmatter.js";
+import { validateFrontmatter } from "./schema.js";
+// Linear without bounds on what a link may hold (main had none, and lint reads every link):
+// each span stops where the next of its kind could start. Link text stops at a `[`, so `[a`
+// repeated can't make each `[` scan on (to the end of the page: 1.1 s for 64 KB); the
+// destination is matched once, in a lookahead, and never given back character by
+// character (`[a](` repeated retried every length); an angle destination stops at `<`
+// (CommonMark), a plain one at `[`. A title runs to its own closer; one in parentheses
+// holds no unescaped `(` (CommonMark), so it stops there too. Only a definition's label is
+// bounded, at CommonMark's 999 characters.
+const TITLE = String.raw `(?:\s+(?:"[^"]*"|'[^']*'|\((?:[^()\\]|\\.)*\)))?`;
+const LINK_RE = new RegExp(String.raw `!?\[[^\][]*\]\(\s*(?=(<[^<>\n]*>|[^)\s[]+))\1${TITLE}\s*\)`, "g");
+const REF_DEF_RE = new RegExp(String.raw `^ {0,3}\[[^\][\n]{1,999}\]:[ \t]*(?=(<[^<>\n]*>|\S+))\1${TITLE}[ \t]*$`, "gm");
+const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i;
+/** Relative link targets (inline and reference definitions), without query or fragment. */
+export function extractLinks(body) {
+    const out = [];
+    for (const m of [...body.matchAll(LINK_RE), ...body.matchAll(REF_DEF_RE)]) {
+        const target = m[1].replace(/^<|>$/g, "");
+        if (EXTERNAL.test(target))
+            continue;
+        const path = target.split(/[?#]/)[0];
+        if (path)
+            out.push(path);
+    }
+    return out;
+}
+export function extractHeadings(body) {
+    return body
+        .split(/\r?\n/)
+        .filter((l) => /^#{1,6}\s/.test(l))
+        .map((l) => l.replace(/^#{1,6}\s+/, "").trim());
+}
+/** Resolve a relative link from a page to a repo-relative posix path. */
+export function resolveLink(fromPath, target) {
+    let t = target;
+    try {
+        t = decodeURI(target);
+    }
+    catch {
+        /* malformed escape: resolve as written */
+    }
+    return t.startsWith("/") ? posix.normalize(t.slice(1)) : posix.normalize(posix.join(posix.dirname(fromPath), t));
+}
+function walkMarkdown(dir) {
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries.flatMap((e) => {
+        const abs = join(dir, e.name);
+        if (e.isDirectory())
+            return e.name.startsWith(".") ? [] : walkMarkdown(abs);
+        return e.isFile() && e.name.endsWith(".md") ? [abs] : [];
+    });
+}
+export function parsePage(path, text) {
+    const doc = splitFrontmatter(text);
+    if (!doc.data)
+        return { path, issues: [{ field: "(frontmatter)", message: doc.error ?? "missing frontmatter" }] };
+    const rawId = typeof doc.data.id === "string" ? doc.data.id : undefined;
+    const slug = typeof doc.data.slug === "string" ? { slug: doc.data.slug } : {};
+    const v = validateFrontmatter(doc.data);
+    if (!v.ok)
+        return { path, id: rawId, ...slug, issues: v.issues };
+    return {
+        ...v.value,
+        ...slug,
+        path,
+        body: doc.body,
+        headings: extractHeadings(doc.body),
+        links: extractLinks(doc.body),
+        sha256: createHash("sha256").update(text).digest("hex"),
+        unknownFields: v.unknownFields,
+    };
+}
+export function isPage(p) {
+    return p.sha256 !== undefined;
+}
+/**
+ * Load a knowledge repo from disk. Pages with invalid frontmatter are kept out of
+ * `pages` (nothing downstream may serve them) and reported in `invalid` for the linter.
+ */
+export function loadRepo(root, config = loadConfig(root)) {
+    const knowledgeDir = join(root, config.knowledge_root);
+    const pages = [];
+    const invalid = [];
+    for (const abs of walkMarkdown(knowledgeDir).sort()) {
+        const path = relative(root, abs).split(sep).join("/");
+        const parsed = parsePage(path, readFileSync(abs, "utf8"));
+        (isPage(parsed) ? pages : invalid).push(parsed);
+    }
+    const byId = new Map();
+    for (const p of pages)
+        if (!byId.has(p.id))
+            byId.set(p.id, p);
+    return {
+        root,
+        config,
+        codeowners: loadCodeowners(root),
+        pages,
+        invalid,
+        byId,
+        byPath: new Map(pages.map((p) => [p.path, p])),
+    };
+}
+/** Latest mtime under the knowledge dir; the MCP server uses it to detect edits. */
+export function knowledgeMtime(root, config) {
+    return walkMarkdown(join(root, config.knowledge_root)).reduce((max, f) => Math.max(max, statSync(f).mtimeMs), 0);
+}

package/dist/core/schema.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+export declare const PAGE_TYPES: readonly ["runbook", "adr", "service", "guide", "policy"];
+export declare const STATUSES: readonly ["canonical", "draft", "deprecated"];
+export declare const REQUIRED_FIELDS: readonly ["title", "id", "type", "status", "owner_team", "last_verified", "review_every"];
+export declare const OPTIONAL_FIELDS: readonly ["supersedes", "applies_to", "acl", "description"];
+/** Default ACL: anyone with read access to the knowledge repo. */
+export declare const ACL_INTERNAL = "internal";
+/** A team slug, or `internal` (owner_team, acl). */
+export declare const SLUG_RE: RegExp;
+/** A page id: lowercase letters, digits and dashes. */
+export declare const ID_RE: RegExp;
+export declare const FrontmatterSchema: z.ZodObject<{
+    title: z.ZodString;
+    id: z.ZodString;
+    type: z.ZodEnum<{
+        adr: "adr";
+        guide: "guide";
+        policy: "policy";
+        runbook: "runbook";
+        service: "service";
+    }>;
+    status: z.ZodEnum<{
+        canonical: "canonical";
+        deprecated: "deprecated";
+        draft: "draft";
+    }>;
+    owner_team: z.ZodString;
+    last_verified: z.ZodString;
+    review_every: z.ZodString;
+    supersedes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    applies_to: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    acl: z.ZodDefault<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Frontmatter = z.infer<typeof FrontmatterSchema>;
+export type PageType = (typeof PAGE_TYPES)[number];
+export type PageStatus = (typeof STATUSES)[number];
+export interface FieldIssue {
+    field: string;
+    message: string;
+}
+/** Validate raw frontmatter, returning issues keyed by field for the linter. */
+export declare function validateFrontmatter(data: Record<string, unknown>): {
+    ok: true;
+    value: Frontmatter;
+    unknownFields: string[];
+} | {
+    ok: false;
+    issues: FieldIssue[];
+};

package/dist/core/schema.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { DURATION_RE, parseDate } from "./duration.js";
+// The frontmatter contract from docs/format-spec.md (format: 1).
+export const PAGE_TYPES = ["runbook", "adr", "service", "guide", "policy"];
+export const STATUSES = ["canonical", "draft", "deprecated"];
+export const REQUIRED_FIELDS = [
+    "title",
+    "id",
+    "type",
+    "status",
+    "owner_team",
+    "last_verified",
+    "review_every",
+];
+export const OPTIONAL_FIELDS = ["supersedes", "applies_to", "acl", "description"];
+/** Default ACL: anyone with read access to the knowledge repo. */
+export const ACL_INTERNAL = "internal";
+/** A team slug, or `internal` (owner_team, acl). */
+export const SLUG_RE = /^[a-z0-9][a-z0-9_-]*$/;
+/** A page id: lowercase letters, digits and dashes. */
+export const ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+export const FrontmatterSchema = z.object({
+    title: z.string().trim().min(1),
+    id: z.string().regex(ID_RE, "lowercase letters, digits and dashes"),
+    type: z.enum(PAGE_TYPES),
+    status: z.enum(STATUSES),
+    // A bare team slug; the org comes from config (github.org). Never `@user`.
+    owner_team: z.string().regex(SLUG_RE, "a team slug like `platform` (no @, no org)"),
+    last_verified: z
+        .string()
+        .refine((s) => parseDate(s) !== null, "a real calendar date as YYYY-MM-DD"),
+    review_every: z.string().regex(DURATION_RE, "a period like 30d, 12w, 6m or 1y"),
+    supersedes: z.array(z.string().regex(ID_RE)).optional(),
+    applies_to: z.array(z.string().min(1)).optional(),
+    acl: z.string().regex(SLUG_RE, "`internal` or a team slug").default(ACL_INTERNAL),
+    description: z.string().optional(),
+});
+/** Validate raw frontmatter, returning issues keyed by field for the linter. */
+export function validateFrontmatter(data) {
+    const result = FrontmatterSchema.safeParse(data);
+    const known = new Set([...REQUIRED_FIELDS, ...OPTIONAL_FIELDS]);
+    const unknownFields = Object.keys(data).filter((k) => !known.has(k));
+    if (result.success)
+        return { ok: true, value: result.data, unknownFields };
+    const issues = result.error.issues.map((issue) => {
+        const field = String(issue.path[0] ?? "(root)");
+        const missing = data[field] === undefined;
+        return { field, message: missing ? `missing required field \`${field}\`` : `\`${field}\`: ${issue.message}` };
+    });
+    return { ok: false, issues };
+}

package/dist/core/search.d.ts

@@ -0,0 +1,32 @@
+export interface SearchDoc {
+    title: string;
+    headings?: string[];
+    description?: string;
+    body: string;
+    /** Extra exact-ish tokens such as ids or service names. */
+    keywords?: string[];
+}
+export interface Hit {
+    index: number;
+    score: number;
+}
+export declare function tokenize(text: string): string[];
+export declare class SearchIndex {
+    private postings;
+    private lengths;
+    private avgLength;
+    constructor(docs: SearchDoc[]);
+    get size(): number;
+    /** Top hits for a query; `accept` filters candidates before ranking (ACL, filters). */
+    search(query: string, limit: number, accept?: (index: number) => boolean): Hit[];
+}
+/**
+ * A page's markdown as a reader sees it, to cut snippets from: its words, code as written,
+ * an image as its label, a table's cells (`a | b`); no markup, link targets or raw HTML.
+ * It reads the tree the web app renders from (`parseGfm`), so a snippet cut from it holds
+ * exactly the words the page shows, and never ends inside markup (search's
+ * `snippets: "text"`).
+ */
+export declare function plainText(markdown: string): string;
+/** A ~maxLen window of `body` around the densest run of query terms. */
+export declare function snippet(body: string, query: string, maxLen?: number): string;

package/dist/core/search.js

@@ -0,0 +1,132 @@
+// In-memory BM25 (BM25F-lite: per-field boosts folded into term frequency).
+// The plan says "BM25 first, embeddings later"; this keeps search dependency-free and
+// fast enough for 5,000 pages (scripts/bench-search.ts holds it to p95 < 500 ms).
+import { isTableCell, parseGfm, textIn } from "./gfm.js";
+const STOPWORDS = new Set("a an and are as at be by can do does for from has have how i if in into is it its of on or our should that the their then there this to was we what when where which who why will with you your".split(" "));
+const BOOST = { title: 3, keywords: 3, headings: 2, description: 2, body: 1 };
+const K1 = 1.2;
+const B = 0.75;
+export function tokenize(text) {
+    return (text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [])
+        .filter((t) => !STOPWORDS.has(t))
+        .map(stem);
+}
+/** Deliberately light stemming: plural and common verb suffixes only. */
+function stem(t) {
+    if (t.length > 5 && t.endsWith("ing"))
+        return t.slice(0, -3);
+    if (t.length > 4 && t.endsWith("ies"))
+        return `${t.slice(0, -3)}y`;
+    if (t.length > 4 && t.endsWith("ed"))
+        return t.slice(0, -2);
+    if (t.length > 3 && t.endsWith("s") && !t.endsWith("ss"))
+        return t.slice(0, -1);
+    return t;
+}
+export class SearchIndex {
+    postings = new Map();
+    lengths = [];
+    avgLength = 0;
+    constructor(docs) {
+        docs.forEach((doc, i) => {
+            const tf = new Map();
+            const add = (text, boost) => {
+                for (const t of tokenize(text ?? ""))
+                    tf.set(t, (tf.get(t) ?? 0) + boost);
+            };
+            add(doc.title, BOOST.title);
+            add(doc.keywords?.join(" "), BOOST.keywords);
+            add(doc.headings?.join(" "), BOOST.headings);
+            add(doc.description, BOOST.description);
+            add(doc.body, BOOST.body);
+            let len = 0;
+            for (const [term, f] of tf) {
+                len += f;
+                let list = this.postings.get(term);
+                if (!list)
+                    this.postings.set(term, (list = []));
+                list.push({ doc: i, tf: f });
+            }
+            this.lengths.push(len);
+        });
+        this.avgLength = this.lengths.reduce((a, b) => a + b, 0) / Math.max(1, this.lengths.length);
+    }
+    get size() {
+        return this.lengths.length;
+    }
+    /** Top hits for a query; `accept` filters candidates before ranking (ACL, filters). */
+    search(query, limit, accept = () => true) {
+        const n = this.lengths.length;
+        const scores = new Map();
+        for (const term of new Set(tokenize(query))) {
+            const list = this.postings.get(term);
+            if (!list)
+                continue;
+            const idf = Math.log(1 + (n - list.length + 0.5) / (list.length + 0.5));
+            for (const { doc, tf } of list) {
+                const norm = tf + K1 * (1 - B + (B * this.lengths[doc]) / this.avgLength);
+                scores.set(doc, (scores.get(doc) ?? 0) + idf * ((tf * (K1 + 1)) / norm));
+            }
+        }
+        return [...scores.entries()]
+            .filter(([doc]) => accept(doc))
+            .map(([index, score]) => ({ index, score: Math.round(score * 1000) / 1000 }))
+            .sort((a, b) => b.score - a.score || a.index - b.index)
+            .slice(0, limit);
+    }
+}
+// Blocks whose text a reader sees apart from what's next to them.
+const BLOCKS = new Set(["paragraph", "heading", "item", "block_quote", "code_block", "custom_block", "thematic_break"]);
+/**
+ * A page's markdown as a reader sees it, to cut snippets from: its words, code as written,
+ * an image as its label, a table's cells (`a | b`); no markup, link targets or raw HTML.
+ * It reads the tree the web app renders from (`parseGfm`), so a snippet cut from it holds
+ * exactly the words the page shows, and never ends inside markup (search's
+ * `snippets: "text"`).
+ */
+export function plainText(markdown) {
+    let out = "";
+    const walker = parseGfm(markdown).walker();
+    for (let e = walker.next(); e; e = walker.next()) {
+        const n = e.node;
+        if (!e.entering)
+            continue;
+        if (n.type === "text" || n.type === "code")
+            out += n.literal ?? "";
+        else if (n.type === "code_block")
+            out += ` ${n.literal ?? ""} `;
+        else if (isTableCell(n))
+            out += n.prev ? " | " : " ";
+        // As the web app labels an image (packages/ui/src/markdown.ts): `image: ` and its words,
+        // or its address when it has none, once; what's inside it (an image too) isn't shown.
+        else if (n.type === "image") {
+            out += `image: ${textIn(n) || n.destination || ""}`;
+            walker.resumeAt(n, false);
+        }
+        else if (n.type === "softbreak" || n.type === "linebreak" || BLOCKS.has(n.type))
+            out += " ";
+    }
+    return out.replace(/\s+/g, " ").trim();
+}
+/** A ~maxLen window of `body` around the densest run of query terms. */
+export function snippet(body, query, maxLen = 240) {
+    const text = body.replace(/\s+/g, " ").trim();
+    if (text.length <= maxLen)
+        return text;
+    const terms = new Set(tokenize(query));
+    const words = text.split(" ");
+    let best = 0;
+    let bestScore = -1;
+    const window = 30;
+    for (let i = 0; i < words.length; i += 5) {
+        const score = words.slice(i, i + window).filter((w) => terms.has(tokenize(w)[0] ?? "")).length;
+        if (score > bestScore)
+            [best, bestScore] = [i, score];
+    }
+    // Start a few words before the first match in the winning window, so the matches
+    // themselves land inside the visible length.
+    const firstMatch = words.findIndex((w, i) => i >= best && terms.has(tokenize(w)[0] ?? ""));
+    const start = firstMatch === -1 ? best : Math.max(0, firstMatch - 4);
+    const out = words.slice(start).join(" ").slice(0, maxLen);
+    return `${start > 0 ? "…" : ""}${out}${out.length >= maxLen ? "…" : ""}`;
+}

package/dist/core/serve/auth.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage } from "node:http";
+/** A Chromium extension id: 32 letters a to p. */
+export declare const EXTENSION_ID: RegExp;
+export interface AccessRules {
+    port: number;
+    token: string;
+    /** Extension ids allowed to call /mcp from `chrome-extension://<id>`. */
+    extensions: ReadonlySet<string>;
+}
+export type Verdict = {
+    ok: true; /** The origin to answer with CORS headers, for an allowed extension. */
+    cors?: string;
+} | {
+    ok: false;
+    status: 401 | 403;
+    message: string;
+};
+/** Host and Origin, checked on every request, static files included. */
+export declare function checkOrigin(req: IncomingMessage, rules: AccessRules): Verdict;
+/** The bearer token, checked on every /mcp request after checkOrigin. */
+export declare function checkToken(req: IncomingMessage, rules: AccessRules): Verdict;
+/** CORS headers for an allowed extension origin, on preflights and on responses. */
+export declare function corsHeaders(origin: string): Record<string, string>;

package/dist/core/serve/auth.js

@@ -0,0 +1,38 @@
+import { tokenMatches } from "./token.js";
+// Who may talk to `docsworth serve`. It listens on 127.0.0.1 only, and on top of that
+// every request must name this server as its Host (a DNS-rebound page names its own),
+// and a browser request's Origin must be this server or an extension the user allowed.
+// /mcp also needs the bearer token. There are no cookies: nothing a browser attaches on
+// its own can authorize a request, so another site can't make one on the user's behalf.
+/** A Chromium extension id: 32 letters a to p. */
+export const EXTENSION_ID = /^[a-p]{32}$/;
+const own = (port) => [`http://127.0.0.1:${port}`, `http://localhost:${port}`];
+/** Host and Origin, checked on every request, static files included. */
+export function checkOrigin(req, rules) {
+    const host = req.headers.host;
+    if (host !== `127.0.0.1:${rules.port}` && host !== `localhost:${rules.port}`)
+        return { ok: false, status: 403, message: "this server answers only to 127.0.0.1 and localhost on its own port" };
+    const origin = req.headers.origin;
+    if (origin === undefined || own(rules.port).includes(origin))
+        return { ok: true };
+    const ext = /^chrome-extension:\/\/([a-p]{32})$/.exec(origin)?.[1];
+    if (ext && rules.extensions.has(ext))
+        return { ok: true, cors: origin };
+    return { ok: false, status: 403, message: "requests from this origin are not allowed; an extension must be allowed with --allow-extension" };
+}
+/** The bearer token, checked on every /mcp request after checkOrigin. */
+export function checkToken(req, rules) {
+    const m = /^Bearer (\S+)$/.exec(req.headers.authorization ?? "");
+    return tokenMatches(rules.token, m?.[1]) ? { ok: true } : { ok: false, status: 401, message: "a valid bearer token is required" };
+}
+/** CORS headers for an allowed extension origin, on preflights and on responses. */
+export function corsHeaders(origin) {
+    return {
+        "access-control-allow-origin": origin,
+        "access-control-allow-methods": "GET, POST, DELETE",
+        "access-control-allow-headers": "authorization, content-type, accept, mcp-session-id, mcp-protocol-version, last-event-id",
+        "access-control-expose-headers": "mcp-session-id",
+        "access-control-max-age": "600",
+        vary: "Origin",
+    };
+}

package/dist/core/serve/server.d.ts

@@ -0,0 +1,21 @@
+import { type Server } from "node:http";
+import { SessionTable, type SessionOptions } from "./sessions.js";
+export declare const DEFAULT_PORT = 4747;
+/** Sent on every response, the static app's included. */
+export declare const SECURITY_HEADERS: Readonly<Record<string, string>>;
+export interface ServeOptions extends SessionOptions {
+    port: number;
+    token: string;
+    extensions: ReadonlySet<string>;
+    /** The built web app (dist/web), or null to serve /mcp only. */
+    webRoot: string | null;
+}
+export interface Serving {
+    server: Server;
+    sessions: SessionTable;
+    port: number;
+    /** The URL to open, with the token in the fragment (never sent to the server). */
+    url: string;
+    close(): Promise<void>;
+}
+export declare function startServer(opts: ServeOptions): Promise<Serving>;

package/dist/core/serve/server.js

@@ -0,0 +1,138 @@
+import { createReadStream, statSync } from "node:fs";
+import { createServer } from "node:http";
+import { extname, join, resolve, sep } from "node:path";
+import { checkOrigin, checkToken, corsHeaders } from "./auth.js";
+import { SessionTable } from "./sessions.js";
+// `docsworth serve`: the knowledge repo over MCP (Streamable HTTP) at /mcp, for the web app
+// and the browser extension, plus the web app's static files at /. Bound to 127.0.0.1
+// only. Every response carries the security headers; /mcp also needs the bearer token.
+// The static files hold no data: everything the app shows comes through /mcp, under the
+// same ACL, gate, policy, taint check and audit log as an agent's stdio session.
+export const DEFAULT_PORT = 4747;
+/** Sent on every response, the static app's included. */
+export const SECURITY_HEADERS = {
+    "content-security-policy": "default-src 'self'; img-src 'self' data:; connect-src 'self'; base-uri 'none'; object-src 'none'; form-action 'none'; frame-ancestors 'none'",
+    "referrer-policy": "no-referrer",
+    "x-content-type-options": "nosniff",
+};
+const TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".json": "application/json",
+    ".woff2": "font/woff2",
+};
+function refuse(res, v, extra = {}) {
+    const auth = v.status === 401 ? { "www-authenticate": 'Bearer realm="docsworth"' } : {};
+    res.writeHead(v.status, { ...SECURITY_HEADERS, ...extra, ...auth, "content-type": "application/json" });
+    res.end(JSON.stringify({ error: { code: v.status === 401 ? "unauthorized" : "forbidden", message: v.message } }));
+}
+/** A file under `webRoot` for a URL path, or the app's index for a client-side route. */
+function staticFile(webRoot, pathname) {
+    let rel;
+    try {
+        rel = decodeURIComponent(pathname);
+    }
+    catch {
+        return null;
+    }
+    if (rel.includes("\0"))
+        return null;
+    const root = resolve(webRoot);
+    const file = resolve(root, `.${rel.endsWith("/") ? `${rel}index.html` : rel}`);
+    if (file !== root && !file.startsWith(root + sep))
+        return null; // never outside the app
+    try {
+        if (statSync(file).isFile())
+            return file;
+    }
+    catch {
+        /* not a file: maybe a client-side route */
+    }
+    // A path without an extension is one of the app's routes (/p/<id>, /graph): its index.
+    return extname(rel) === "" ? join(root, "index.html") : null;
+}
+function serveStatic(webRoot, req, res, pathname) {
+    if (req.method !== "GET" && req.method !== "HEAD") {
+        res.writeHead(405, { ...SECURITY_HEADERS, allow: "GET, HEAD" }).end();
+        return;
+    }
+    const file = webRoot ? staticFile(webRoot, pathname) : null;
+    let size = 0;
+    try {
+        size = file ? statSync(file).size : 0;
+    }
+    catch {
+        /* index.html missing: the app isn't built */
+    }
+    if (!file || (!size && file.endsWith("index.html"))) {
+        const body = webRoot ? "Not found.\n" : "The web app isn't built into this install; /mcp is served.\n";
+        res.writeHead(404, { ...SECURITY_HEADERS, "content-type": "text/plain; charset=utf-8" }).end(body);
+        return;
+    }
+    res.writeHead(200, {
+        ...SECURITY_HEADERS,
+        "content-type": TYPES[extname(file)] ?? "application/octet-stream",
+        "content-length": String(size),
+        // Hashed asset names can be cached; the index must not be, or a new build wouldn't load.
+        "cache-control": file.endsWith("index.html") ? "no-store" : "max-age=31536000, immutable",
+    });
+    if (req.method === "HEAD")
+        res.end();
+    else
+        createReadStream(file).pipe(res);
+}
+export async function startServer(opts) {
+    const sessions = new SessionTable(opts);
+    let rules = { port: opts.port, token: opts.token, extensions: opts.extensions };
+    const server = createServer((req, res) => {
+        const origin = checkOrigin(req, rules);
+        if (!origin.ok)
+            return refuse(res, origin);
+        const pathname = new URL(req.url ?? "/", "http://localhost").pathname;
+        if (pathname !== "/mcp")
+            return serveStatic(opts.webRoot, req, res, pathname);
+        const cors = origin.cors ? corsHeaders(origin.cors) : {};
+        // A preflight can't carry the token; Host and Origin were checked above.
+        if (req.method === "OPTIONS") {
+            res.writeHead(204, { ...SECURITY_HEADERS, ...cors }).end();
+            return;
+        }
+        const auth = checkToken(req, rules);
+        if (!auth.ok)
+            return refuse(res, auth, cors);
+        // Merged into whatever the transport writes.
+        for (const [k, v] of Object.entries({ ...SECURITY_HEADERS, ...cors, vary: "Origin" }))
+            res.setHeader(k, v);
+        sessions.handle(req, res).catch((err) => {
+            opts.log?.(`request failed: ${err.message}`);
+            if (!res.headersSent)
+                res.writeHead(500, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: { code: "internal", message: "internal error" } }));
+        });
+    });
+    await new Promise((done, fail) => {
+        server.once("error", fail);
+        server.listen(opts.port, "127.0.0.1", () => done());
+    });
+    // With port 0 (tests), the Host check needs the port the OS picked.
+    const port = server.address().port;
+    rules = { ...rules, port };
+    return {
+        server,
+        sessions,
+        port,
+        url: `http://127.0.0.1:${port}/#t=${opts.token}`,
+        async close() {
+            await sessions.close();
+            // Stop listening, then drop what is still open (a tab's event stream, a call still
+            // arriving): close() alone waits for every connection to finish, so Ctrl-C would hang.
+            const closed = new Promise((done) => server.close(() => done()));
+            server.closeAllConnections();
+            await closed;
+        },
+    };
+}