@docsworth/cli 0.0.0-stage → 0.2.0

package/dist/core/serve/sessions.js

@@ -0,0 +1,130 @@
+import { randomUUID } from "node:crypto";
+import { watch } from "node:fs";
+import { join } from "node:path";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { actorOf } from "../audit-log.js";
+import { auditTransport } from "../mcp/audit-transport.js";
+import { createMcpServer } from "../mcp/server.js";
+import { KnowledgeService, WATCH_SETTLE_MS } from "../service.js";
+export const MAX_SESSIONS = 16;
+export const SESSION_IDLE_MS = 30 * 60_000;
+function json(res, status, body) {
+    res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
+}
+export class SessionTable {
+    opts;
+    sessions = new Map();
+    /** Sessions being set up: counted against the cap before they have an id. */
+    starting = 0;
+    watcher = null;
+    sweeper;
+    max;
+    idleMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.max = opts.maxSessions ?? MAX_SESSIONS;
+        this.idleMs = opts.idleMs ?? SESSION_IDLE_MS;
+        // One watcher for every session: a change marks each service dirty, and each reloads
+        // lazily on its next call, never in the middle of a write that is still landing.
+        // It watches pages only. The config and CODEOWNERS (the policy, admins, owners) sit
+        // outside the knowledge root, and every call already stats them: KnowledgeService's
+        // current() reloads when inputsStamp() changes. So a tightened policy applies to an
+        // open session's next call (test/serve.test.ts, "applies a tightened policy").
+        this.watcher = watch(join(opts.root, opts.knowledgeRoot), { recursive: true }, () => this.invalidate());
+        const settle = setTimeout(() => this.invalidate(), WATCH_SETTLE_MS); // see KnowledgeService.watch
+        settle.unref();
+        this.sweeper = setInterval(() => void this.sweep(), Math.min(60_000, this.idleMs));
+        this.sweeper.unref();
+    }
+    get size() {
+        return this.sessions.size;
+    }
+    /** The services of live sessions (tests). */
+    services() {
+        return [...this.sessions.values()].map((s) => s.service);
+    }
+    invalidate() {
+        for (const s of this.sessions.values())
+            s.service.invalidate();
+    }
+    async handle(req, res) {
+        const sid = req.headers["mcp-session-id"];
+        if (sid !== undefined) {
+            const session = typeof sid === "string" ? this.sessions.get(sid) : undefined;
+            if (!session)
+                return json(res, 404, { error: { code: "not_found", message: "no such session; it may have expired: start a new one" } });
+            session.active++;
+            try {
+                return await session.http.handleRequest(req, res);
+            }
+            finally {
+                session.active--;
+                session.lastUsed = Date.now();
+            }
+        }
+        if (req.method !== "POST")
+            return json(res, 400, { error: { code: "invalid", message: "start a session with an initialize request" } });
+        // Checked and counted before the first await, so concurrent starts can't pass the cap.
+        if (this.sessions.size + this.starting >= this.max)
+            return json(res, 503, { error: { code: "unavailable", message: `this server already has ${this.max} sessions open; close a tab or wait for idle ones to expire` } });
+        this.starting++;
+        try {
+            const session = await this.open();
+            try {
+                await session.http.handleRequest(req, res);
+            }
+            finally {
+                // Busy from birth: the session joins the table while this request is still
+                // being answered, so a sweep in between must not take it.
+                session.active--;
+                session.lastUsed = Date.now();
+            }
+            // A first request that wasn't an initialize gets the SDK's error and no session.
+            if (!session.http.sessionId)
+                await session.server.close();
+        }
+        finally {
+            this.starting--;
+        }
+    }
+    async open() {
+        const o = this.opts;
+        const service = new KnowledgeService(o.root, o.identity, o.now);
+        const http = new StreamableHTTPServerTransport({
+            sessionIdGenerator: randomUUID,
+            enableJsonResponse: true,
+            onsessioninitialized: (id) => void this.sessions.set(id, session),
+        });
+        const transport = o.audit
+            ? auditTransport(http, o.audit, () => o.identity.get(), {
+                includeQueries: o.includeQueries,
+                initialActor: actorOf(o.who),
+                known: () => service.knownValues(),
+                snapshot: () => service.snapshot(),
+                log: o.log,
+            })
+            : http;
+        // On the wrapper, not on `http`: the audit transport takes over the inner onclose.
+        // Set before connect, which chains the server's own handler after this one.
+        transport.onclose = () => {
+            if (http.sessionId)
+                this.sessions.delete(http.sessionId);
+            service.close();
+        };
+        const server = createMcpServer(service, { who: o.who, whoami: () => o.identity.get(), surface: "http" });
+        const session = { http, server, service, lastUsed: Date.now(), active: 1 };
+        await server.connect(transport);
+        return session;
+    }
+    /** Close sessions idle longer than the limit, never one with a request in flight. */
+    async sweep(now = Date.now()) {
+        const idle = [...this.sessions.values()].filter((s) => s.active === 0 && now - s.lastUsed > this.idleMs);
+        await Promise.all(idle.map((s) => s.server.close()));
+    }
+    async close() {
+        clearInterval(this.sweeper);
+        this.watcher?.close();
+        this.watcher = null;
+        await Promise.all([...this.sessions.values()].map((s) => s.server.close()));
+    }
+}

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

@@ -0,0 +1,10 @@
+import { UserError } from "../errors.js";
+export declare const TOKEN_FILE = "serve-token";
+export declare class TokenError extends UserError {
+}
+/** The serve token kept in `dir`, created on first use, or replaced with `rotate`. */
+export declare function loadToken(dir: string, opts?: {
+    rotate?: boolean;
+}): string;
+/** Constant-time comparison of a presented token with the expected one. */
+export declare function tokenMatches(expected: string, presented: string | undefined): boolean;

package/dist/core/serve/token.js

@@ -0,0 +1,96 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { chmodSync, closeSync, constants, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
+import { join } from "node:path";
+import { UserError } from "../errors.js";
+// The bearer token `docsworth serve` checks on every /mcp request. It persists in this
+// user's state directory (outside the repo, never committable), so a paired browser
+// extension keeps working across restarts; `--rotate-token` replaces it. The file is
+// handled like the audit log's: a 0700 directory that isn't a symlink, a 0600 file opened
+// without following links, and writes that are atomic.
+export const TOKEN_FILE = "serve-token";
+const TOKEN_SHAPE = /^[A-Za-z0-9_-]{43}$/; // 32 random bytes, base64url
+export class TokenError extends UserError {
+}
+function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const st = lstatSync(dir);
+    if (st.isSymbolicLink() || !st.isDirectory())
+        throw new TokenError(`${dir} is a symlink or not a directory; refusing to keep the serve token there`);
+    if ((st.mode & 0o077) !== 0)
+        chmodSync(dir, 0o700);
+}
+/** The token in `file`, or null if there is none yet. */
+function readToken(file) {
+    let fd;
+    try {
+        fd = openSync(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        if (code === "ELOOP")
+            throw new TokenError(`${file} is a symlink; refusing to read the serve token through it`);
+        throw err;
+    }
+    try {
+        const st = fstatSync(fd);
+        if (!st.isFile())
+            throw new TokenError(`${file} is not a regular file; refusing to use it as the serve token`);
+        // A token others could read is a token others have: refuse it rather than quietly fix it.
+        if ((st.mode & 0o077) !== 0)
+            throw new TokenError(`${file} can be read by other users; run \`docsworth serve --rotate-token\` to replace it`);
+        const token = readFileSync(fd, "utf8").trim();
+        if (!TOKEN_SHAPE.test(token))
+            throw new TokenError(`${file} doesn't hold a serve token; run \`docsworth serve --rotate-token\``);
+        return token;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+/**
+ * Write a new token to `file` through a fresh 0600 file in the same directory. When the
+ * token is first created, the new file is linked into place, so of two servers starting
+ * at once only one token wins and both read it; a rotation renames over the old one.
+ */
+function writeToken(dir, file, replace) {
+    const tmp = join(dir, `.${TOKEN_FILE}.${process.pid}.${randomBytes(4).toString("hex")}`);
+    const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        writeSync(fd, `${randomBytes(32).toString("base64url")}\n`);
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (replace)
+        return renameSync(tmp, file); // replaces a symlink itself, never its target
+    try {
+        linkSync(tmp, file);
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err; // another start won
+    }
+    finally {
+        unlinkSync(tmp);
+    }
+}
+/** The serve token kept in `dir`, created on first use, or replaced with `rotate`. */
+export function loadToken(dir, opts = {}) {
+    ensureDir(dir);
+    const file = join(dir, TOKEN_FILE);
+    if (opts.rotate)
+        writeToken(dir, file, true);
+    else if (readToken(file) === null)
+        writeToken(dir, file, false);
+    return readToken(file);
+}
+/** Constant-time comparison of a presented token with the expected one. */
+export function tokenMatches(expected, presented) {
+    if (typeof presented !== "string")
+        return false;
+    const a = Buffer.from(expected);
+    const b = Buffer.from(presented);
+    return a.length === b.length && timingSafeEqual(a, b);
+}

package/dist/core/service.d.ts

@@ -0,0 +1,375 @@
+import { type Identity } from "./acl.js";
+import { type NewPageType } from "./new-page.js";
+import { type Policy } from "./policy.js";
+import type { GitHubClient } from "./github.js";
+import { type Page } from "./repo.js";
+import { type PageType } from "./schema.js";
+import { type StaleEntry } from "./stale.js";
+import { type Edit } from "./writes.js";
+export type ToolErrorCode = "not_found" | "forbidden" | "invalid" | "unavailable";
+export declare class ToolError extends Error {
+    readonly code: ToolErrorCode;
+    constructor(code: ToolErrorCode, message: string);
+}
+/** What the service needs from identity resolution (IdentityProvider, or a test fake). */
+export interface IdentitySource {
+    get(): Promise<Identity>;
+    fresh(): Promise<Identity>;
+    readonly github: GitHubClient | null;
+}
+export interface PageSummary {
+    id: string;
+    title: string;
+    path: string;
+    type: PageType;
+    status: Page["status"];
+    owner_team: string;
+    last_verified: string;
+    due: string | null;
+    sla_state: string;
+    citable: boolean;
+}
+export interface SearchResult extends PageSummary {
+    snippet: string;
+    score: number;
+    /** Present only with include_stale: why this page is not citable. */
+    gate?: string;
+}
+/** A mirrored wiki page that matched: context for the agent, never a citation. */
+export interface MirroredHit {
+    id: string;
+    title: string;
+    source: string;
+    source_url: string;
+    owner_team: string | null;
+    last_edited: string;
+    citable: false;
+    snippet: string;
+}
+export interface Excluded {
+    id: string;
+    title: string;
+    owner_team: string;
+    reason: string;
+}
+/**
+ * The six knowledge tools as plain functions. The MCP server is a thin wrapper, and the
+ * ACL matrix test exercises this class directly, so there is one code path to audit.
+ *
+ * Invariant: every page a method touches comes from `visiblePages(repo, identity)`.
+ * Unknown ids and ids the caller cannot see raise the same not_found error.
+ */
+/** How long after starting a watcher to reload once anyway. A write 500 ms after a restart
+ *  was always reported (20 of 20); this leaves room on a loaded machine. */
+export declare const WATCH_SETTLE_MS = 2000;
+/** A draft_page body's limit, and how many fresh names it tries before giving up. */
+export declare const DRAFT_MAX_CHARS: number;
+export declare const DRAFT_NAME_ATTEMPTS = 3;
+/** At most this many mirrored pages per search: context, not a second result list. */
+export declare const MIRROR_LIMIT = 3;
+export declare class KnowledgeService {
+    private readonly root;
+    private readonly identity;
+    private readonly now;
+    private repo;
+    private index;
+    private dirty;
+    /** mtimes of the non-page inputs (config, CODEOWNERS) the loaded repo was built from. */
+    private inputs;
+    private watcher;
+    private watchedDir;
+    private settle;
+    private defaultBranch;
+    /** Mirrored pages, when mirror.serve is on; one search index per audience (views). */
+    private mirror;
+    private readonly mirrorViews;
+    /** Team ACLs whose content this session has seen (write-path taint check). */
+    private readonly tainted;
+    /** The random end of a drafted page's id and file name (replaced in tests). */
+    private draftSuffix;
+    constructor(root: string, identity: IdentitySource, now?: () => Date);
+    reload(): void;
+    /** Config and CODEOWNERS live outside the watched knowledge root; stat them per call. */
+    private inputsStamp;
+    /**
+     * The mirrored pages `who` may see, each with links to the ones they can't see
+     * redacted (and to repo pages they can't see: a wiki page can link to one by its URL),
+     * and a search index over exactly that view: ranking, snippets and counts never draw on
+     * a page outside it. One per audience (the caller's teams), rebuilt on reload.
+     */
+    private mirrorView;
+    /** Reload on the next call. `docsworth serve` runs one watcher for all its sessions' services. */
+    invalidate(): void;
+    /** Mark the index dirty on any change under the knowledge root. */
+    watch(): void;
+    close(): void;
+    private current;
+    private snap;
+    /**
+     * The knowledge actually being served: the checkout's HEAD and whether the served files
+     * differ from it, plus a hash of the loaded config, ownership and pages. Refreshed after
+     * every reload, so an audit event names the snapshot its answer came from.
+     */
+    snapshot(): {
+        commit: string | null;
+        dirty: boolean | null;
+        content_sha256: string;
+    };
+    /** Every page id, team and applies_to tag the repo uses: what an audited argument may record. */
+    knownValues(): {
+        ids: Set<string>;
+        teams: Set<string>;
+        tags: Set<string>;
+    };
+    /** Whether mirrored pages are served (mirror.serve). */
+    mirrorServed(): boolean;
+    /** The org policy in force now (config is re-read when it changes). */
+    policy(): Policy;
+    get org(): string;
+    /** Policy gate, checked on every call, before any page is resolved. */
+    private permit;
+    private summary;
+    private resolve;
+    /** Any restricted page represented in a response (content, snippet or just its title)
+     *  taints the session for the write-path check. */
+    private taint;
+    private noteRead;
+    search(args: {
+        query: string;
+        type?: PageType;
+        owner_team?: string;
+        applies_to?: string;
+        include_stale?: boolean;
+        limit?: number;
+    }): Promise<{
+        results: SearchResult[];
+        excluded: Excluded[];
+        mirrored?: MirroredHit[];
+        note?: string;
+    }>;
+    read(args: {
+        id: string;
+    }): Promise<{
+        id: string;
+        title: string;
+        path: string;
+        type: PageType;
+        status: Page["status"];
+        owner_team: string;
+        last_verified: string;
+        due: string | null;
+        sla_state: string;
+        citable: boolean;
+        review_every: string;
+        acl: string;
+        supersedes: string[];
+        applies_to: string[];
+        flags: string[];
+        gate_reason?: string | undefined;
+        content: string;
+    } | {
+        id: string;
+        title: string;
+        source: "confluence" | "notion";
+        space: string;
+        source_url: string;
+        owner_team: string | null;
+        last_edited: string;
+        acl: string;
+        citable: boolean;
+        flags: string[];
+        gate_reason: string;
+        content: string;
+    }>;
+    /** read() for `tool`: the same view; only an agent's `read` goes in the usage log. */
+    private readAs;
+    /**
+     * `readAs`, with what it read: the page, the caller and the repo, from the one look at the
+     * repo after the only await. A caller that builds more of its answer from these (ui_page's
+     * links) answers from that same look, as `read` does: a reload after it can't mix in.
+     */
+    private readWith;
+    /** A repo page's text as `who` may see it: links to pages, or mirrored pages, they can't see redacted. */
+    private pageText;
+    /** A mirrored page, as context: never citable. Hidden and unknown ids read the same. */
+    private readMirror;
+    list(args?: {
+        path?: string;
+        type?: PageType;
+    }): Promise<{
+        type: "adr" | "guide" | "policy" | "runbook" | "service";
+        pages: PageSummary[];
+        path?: undefined;
+        index?: undefined;
+        dirs?: undefined;
+    } | {
+        type?: undefined;
+        path: string;
+        index: PageSummary | null;
+        pages: PageSummary[];
+        dirs: string[];
+    }>;
+    stale(args?: {
+        owner_team?: string;
+    }): Promise<{
+        pages: StaleEntry[];
+    }>;
+    /** Who is served and whether writes would work, for the app's header and settings. */
+    uiCapabilities(opts?: {
+        pro?: string[];
+    }): Promise<{
+        mode: "github" | "local";
+        login: string | null;
+        org: string;
+        repo: string | null;
+        writes: boolean;
+        write_tools: string[];
+        teams: string[];
+        writes_off?: string | undefined;
+        pro: string[];
+    }>;
+    /** Counts over the caller's visible pages, by team, with what is due soon and what is stale. */
+    uiOverview(): Promise<{
+        as_of: string;
+        totals: {
+            pages: number;
+            citable: number;
+            overdue: number;
+            due_soon: number;
+            draft: number;
+            deprecated: number;
+        };
+        teams: {
+            pages: number;
+            citable: number;
+            overdue: number;
+            due_soon: number;
+            team: string;
+        }[];
+        due_soon: PageSummary[];
+        stale: StaleEntry[];
+    }>;
+    /**
+     * A page as `read` shows it, with `links`: the repo path and id of each visible page it
+     * links to, so the app can route those links. Taints the session with the page and those.
+     */
+    uiPage(args: {
+        id: string;
+    }): Promise<{
+        id: string;
+        title: string;
+        source: "confluence" | "notion";
+        space: string;
+        source_url: string;
+        owner_team: string | null;
+        last_edited: string;
+        acl: string;
+        citable: boolean;
+        flags: string[];
+        gate_reason: string;
+        content: string;
+        links: {};
+    } | {
+        id: string;
+        title: string;
+        path: string;
+        type: PageType;
+        status: Page["status"];
+        owner_team: string;
+        last_verified: string;
+        due: string | null;
+        sla_state: string;
+        citable: boolean;
+        review_every: string;
+        acl: string;
+        supersedes: string[];
+        applies_to: string[];
+        flags: string[];
+        gate_reason?: string | undefined;
+        content: string;
+        links: {
+            [k: string]: string;
+        };
+    }>;
+    /**
+     * Visible pages and the links between them. A link to a page the caller can't see is no
+     * edge; `has_restricted_links` says a page has one, exactly as its `read` text shows a
+     * placeholder for it, so the graph reveals nothing `read` doesn't.
+     */
+    uiGraph(args?: {
+        owner_team?: string;
+    }): Promise<{
+        nodes: {
+            id: string;
+            title: string;
+            path: string;
+            type: PageType;
+            status: Page["status"];
+            owner_team: string;
+            last_verified: string;
+            due: string | null;
+            sla_state: string;
+            citable: boolean;
+            has_restricted_links: boolean;
+        }[];
+        edges: {
+            from: string;
+            to: string;
+        }[];
+    }>;
+    /** What every write needs first: the policy, a live identity, a GitHub repo. */
+    private writeIdentity;
+    private pushContext;
+    /** Common preamble for writes to a page: live identity, visibility, a GitHub repo. */
+    private writeContext;
+    /** The same for a write that creates a page: no id to resolve. */
+    private newWriteContext;
+    /** The taint check: a session that saw team-only pages writes only into pages with that audience. */
+    private refuseLeak;
+    proposeEdit(args: {
+        id: string;
+        edits?: Edit[];
+        body?: string;
+        content?: string;
+        append?: string;
+        reason: string;
+        draft?: boolean;
+        polish?: boolean;
+    }): Promise<{
+        pr_url: string;
+        pr_number: number;
+        branch: string;
+    }>;
+    /**
+     * A new page, as a draft PR. The server picks its id and file name, each ending in 12
+     * random hex digits: a caller-chosen name could be aimed at a hidden page, and "already
+     * exists" would then say it is there. The title still sets the slug, so CODEOWNERS
+     * rules that match file names (`runbooks/payments-*`) still apply.
+     */
+    draftPage(args: {
+        type: NewPageType;
+        title: string;
+        owner_team: string;
+        acl?: string;
+        dir?: string;
+        description?: string;
+        body: string;
+        source_url?: string;
+        reason: string;
+        draft?: boolean;
+    }): Promise<{
+        id: string;
+        path: string;
+        pr_url: string;
+        pr_number: number;
+        branch: string;
+    }>;
+    verify(args: {
+        id: string;
+    }): Promise<{
+        pr_url: string;
+        pr_number: number;
+        branch: string;
+        last_verified: string;
+    }>;
+}