@docsworth/cli 0.0.0-stage → 0.3.0

package/dist/cli.js

@@ -0,0 +1,458 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { userInfo } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command, InvalidArgumentError } from "commander";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { adoptRepo } from "./core/adopt.js";
+import { actorOf, createAuditLog, stateDir } from "./core/audit-log.js";
+import { CONFIG_PATH, ConfigError, loadConfig } from "./core/config.js";
+import { computeCoverage, formatCoverage } from "./core/coverage.js";
+import { parseDate } from "./core/duration.js";
+import { IdentityProvider } from "./core/identity.js";
+import { githubRemote, initRepo } from "./core/init.js";
+import { formatDiagnostics, lintRepo } from "./core/lint.js";
+import { auditTransport } from "./core/mcp/audit-transport.js";
+import { createMcpServer } from "./core/mcp/server.js";
+import { policySummary } from "./core/policy.js";
+import { loadRepo } from "./core/repo.js";
+import { EXTENSION_ID } from "./core/serve/auth.js";
+import { DEFAULT_PORT, startServer } from "./core/serve/server.js";
+import { loadToken } from "./core/serve/token.js";
+import { KnowledgeService } from "./core/service.js";
+import { listStale } from "./core/stale.js";
+import { printable, printableJson } from "./core/printable.js";
+import { verifyPages } from "./core/verify-pages.js";
+import { PACKAGE_VERSION } from "./core/version.js";
+import { existsSync, readFileSync } from "node:fs";
+import { parse as parseYaml } from "yaml";
+// Pro loads lazily through `pro()` below; the CLI knows it only by core's contract.
+import { isUserError } from "./core/errors.js";
+import { HOST_API } from "./core/host.js";
+const program = new Command()
+    .name("docsworth")
+    .description("Agent-ready knowledge: team-owned pages, review SLAs, a citation gate for agents.")
+    .version(PACKAGE_VERSION)
+    .option("--as-of <date>", "evaluate SLAs as of YYYY-MM-DD instead of today", (v) => {
+    if (!parseDate(v))
+        throw new InvalidArgumentError("expected YYYY-MM-DD");
+    return v;
+});
+/** "Now" for every SLA computation; --as-of pins it for reproducible reports. */
+export function now() {
+    const asOf = program.opts().asOf;
+    return asOf ? parseDate(asOf) : new Date();
+}
+const repoAt = (dir) => loadRepo(resolve(dir ?? "."));
+/**
+ * The change happened but its outcome isn't in a required log: say so, and exit 3 (done,
+ * audit degraded) so automation can tell it from success (0) and failure (2).
+ */
+export const EXIT_AUDIT_DEGRADED = 3;
+function auditDegraded(err, what) {
+    console.error(`docsworth: ${err.message} (${what}; exit ${EXIT_AUDIT_DEGRADED}: the audit outcome wasn't recorded)`);
+    process.exitCode = EXIT_AUDIT_DEGRADED;
+}
+/** Who ran a local CLI command, for audit events that have no GitHub identity. */
+const cliActor = () => ({ login: userInfo().username, mode: "local", teams: [] });
+/**
+ * Docsworth pro is its own package (LICENSE.md in it), installed beside this one: globally
+ * next to the global CLI, or in the same project. The CLI finds it by name, like any
+ * dependency, and knows it only by core's contract (src/core/host.ts).
+ */
+const PRO_PACKAGE = "@docsworth-pro/pro";
+/** True when pro isn't installed at all. A file missing *inside* an installed pro is a real error. */
+function isMissingPro(err) {
+    if (err?.code !== "ERR_MODULE_NOT_FOUND")
+        return false;
+    try {
+        import.meta.resolve(`${PRO_PACKAGE}/package.json`);
+        return false; // pro is there, so what's missing is inside it
+    }
+    catch (e) {
+        return e.code === "ERR_MODULE_NOT_FOUND";
+    }
+}
+/** "Pro isn't installed." Only pro() throws it; it prints like any ConfigError. */
+class ProMissing extends ConfigError {
+}
+/** Pro is installed but can't be used: it doesn't load, or it was built for another CLI. */
+class ProUnusable extends ConfigError {
+}
+/**
+ * Whether pro can be used, decided once: missing, unusable (why), or ok. Pro declares the
+ * version of core's contract it was built for (src/core/host.ts, HOST_API); one built for
+ * another is refused here, by name, rather than failing somewhere inside a command.
+ */
+let proState;
+const proStatus = () => (proState ??= import(`${PRO_PACKAGE}/host-api`).then(({ PRO_HOST_API }) => PRO_HOST_API === HOST_API ? { ok: true } : { unusable: `it was built for host API ${String(PRO_HOST_API)}, and this CLI has ${HOST_API}; install versions that match` }, (err) => (isMissingPro(err) ? { missing: true } : { unusable: `it doesn't load: ${err.message}` })));
+/**
+ * Pro is a separate package, so the core CLI runs without it and a pro command says what's
+ * missing. Once pro is known to be usable, a failure loading a module of it is pro's own: a
+ * file missing inside it is a real error, reported as it is.
+ */
+async function pro(feature, load) {
+    const state = await proStatus();
+    if ("missing" in state)
+        throw new ProMissing(`${feature} is part of Docsworth pro, which isn't installed`);
+    if ("unusable" in state)
+        throw new ProUnusable(`${feature} needs Docsworth pro, which is installed but can't be used: ${state.unusable}`);
+    return load();
+}
+/** Pro's commands (src/core/host.ts, ProCommands), once pro is known to be usable. */
+const proCommands = (feature) => pro(feature, async () => (await import(`${PRO_PACKAGE}/commands`)).commands);
+/**
+ * Without pro, an audit_http block can't be fully validated, so only the plainly optional
+ * shape counts as optional: an object naming its `url_env`, with `required` absent or false.
+ * Anything else (required, malformed `required`, a non-object, no `url_env`) is treated as
+ * required, which fails closed as httpSinkFromRepo does for a required or invalid block.
+ */
+function isOptionalSink(block) {
+    // A non-object has no url_env string, so the url_env test below already rejects it.
+    const { url_env, required } = Object(block);
+    return typeof url_env === "string" && url_env.length > 0 && (required === undefined || required === false);
+}
+/**
+ * The pro HTTP audit sink, if `audit_http` is configured. Without pro the sink can't be set
+ * up, which is handled as httpSinkFromRepo handles any sink that can't start: fatal when
+ * required, otherwise a warning and no sink.
+ */
+async function httpSink(root) {
+    const file = join(root, CONFIG_PATH);
+    const raw = existsSync(file) ? parseYaml(readFileSync(file, "utf8"), { schema: "core" }) : null;
+    const block = raw?.audit_http;
+    if (block === undefined || block === null)
+        return null;
+    let commands;
+    try {
+        commands = await proCommands("audit_http");
+    }
+    catch (err) {
+        if (!(err instanceof ProMissing) || !isOptionalSink(block))
+            throw err;
+        process.stderr.write(`docsworth: audit collector disabled for this run: ${err.message}\n`);
+        return null;
+    }
+    return commands.httpSinkFromRepo(root);
+}
+/** The audit log for this repo: the core file sink plus the pro HTTP sink, if configured. */
+async function openAuditLog(root, config) {
+    const http = await httpSink(root);
+    return createAuditLog(root, config, http ? [http] : [], { now });
+}
+/** What pro's commands get from this CLI (src/core/host.ts, CommandContext). */
+const ctx = { now, repoAt, cliActor, openAuditLog, auditDegraded, requireEnv };
+program
+    .command("init")
+    .description("scaffold a knowledge repo here: config, CODEOWNERS, root map and a writing guide (never overwrites)")
+    .argument("[dir]", "repo root", ".")
+    .option("--org <org>", "GitHub org owning the teams (default: from the origin remote)")
+    .option("--team <team>", "team that owns knowledge/ to start with", "docs")
+    .option("--repo <owner/name>", "GitHub repo; enables GitHub ACLs and PR tools (default: from the origin remote)")
+    .option("--local", "do not set github.repo even if a GitHub remote exists")
+    .option("--ci", "also add .github/workflows/knowledge.yml")
+    .action((dir, opts) => {
+    const root = resolve(dir);
+    const remote = githubRemote(root);
+    const org = opts.org ?? remote?.owner;
+    if (!org)
+        throw new ConfigError("no GitHub remote found; pass --org <org>");
+    const repo = opts.local ? undefined : (opts.repo ?? (remote ? `${remote.owner}/${remote.name}` : undefined));
+    const r = initRepo(root, { org, team: opts.team, repo, ci: opts.ci, now: now() });
+    for (const f of r.created)
+        console.log(`created  ${f}`);
+    for (const f of r.skipped)
+        console.log(`exists   ${f}`);
+    for (const h of r.hints)
+        console.log(`hint     ${h}`);
+    console.log(`\nNext: docsworth lint ${dir === "." ? "." : dir}, then install the Claude Code plugin (see README).`);
+});
+program
+    .command("lint")
+    .description("validate frontmatter, CODEOWNERS ownership and links; exits 1 on errors")
+    .argument("[dir]", "knowledge repo root", ".")
+    .option("--json", "machine-readable output")
+    .action((dir, opts) => {
+    const result = lintRepo(repoAt(dir), now());
+    console.log(opts.json ? printableJson(result) : formatDiagnostics(result));
+    process.exitCode = result.errors > 0 ? 1 : 0;
+});
+program
+    .command("adopt")
+    .description("give existing markdown pages the frontmatter Docsworth needs, as drafts, and turn route links into .md links (working tree only)")
+    .argument("[dir]", "knowledge repo root", ".")
+    .option("--team <team>", "owning team for pages CODEOWNERS gives no single team")
+    .option("--review-every <period>", "review period for pages without one", "90d")
+    .option("--dry-run", "report what would change; write nothing")
+    .option("--json", "machine-readable output")
+    .action((dir, opts) => {
+    const r = adoptRepo(resolve(dir), { now: now(), team: opts.team, reviewEvery: opts.reviewEvery, dryRun: opts.dryRun });
+    if (opts.json)
+        return console.log(printableJson(r));
+    // Paths, links, keys and reasons quote what pages hold: printed escaped.
+    const say = (line) => console.log(printable(line));
+    for (const l of r.left)
+        say(`left       ${l.path}: ${l.reason}`);
+    for (const l of r.linksLeft)
+        say(`link left  ${l.path}: \`${l.link}\` ${l.why}`);
+    if (r.extraFields.length)
+        say(`config     frontmatter.extra_fields gains ${r.extraFields.join(", ")}`);
+    for (const h of r.hints)
+        say(`hint       ${h}`);
+    const n = (count, what) => `${count} ${what}${count === 1 ? "" : "s"}`;
+    console.log(`\n${r.dryRun ? "Would adopt" : "Adopted"} ${n(r.adopted.length, "page")} (${r.unchanged.length} unchanged, ${r.left.length} left); ` +
+        `${r.linksRewritten} ${r.linksRewritten === 1 ? "link" : "links"} rewritten, ${r.linksLeft.length} left.`);
+    console.log(r.dryRun
+        ? "Dry run: nothing written."
+        : `Nothing is committed. Review the diff, run \`docsworth lint ${dir}\`, and open a pull request: adopted pages are drafts, cited once their team runs \`docsworth verify\`.`);
+});
+program
+    .command("verify")
+    .description("verify pages: each draft or canonical page under the paths becomes canonical, verified today (working tree only)")
+    .argument("<paths...>", "pages, or directories of them")
+    .option("--dir <dir>", "knowledge repo root", ".")
+    .option("--dry-run", "report what would change; write nothing")
+    .option("--json", "machine-readable output")
+    .action((paths, opts) => {
+    // Paths are the shell's, relative to where it runs, whatever --dir says.
+    const r = verifyPages(resolve(opts.dir), paths.map((p) => resolve(p)), { now: now(), dryRun: opts.dryRun });
+    if (opts.json)
+        return console.log(printableJson(r));
+    for (const l of r.left)
+        console.log(printable(`left  ${l.path}: ${l.reason}`));
+    console.log(`\n${r.dryRun ? "Would verify" : "Verified"} ${r.verified.length} page${r.verified.length === 1 ? "" : "s"} (${r.unchanged.length} already verified today, ${r.left.length} left).`);
+    console.log(r.dryRun ? "Dry run: nothing written." : "Nothing is committed: open a pull request, which the owning team reviews.");
+});
+program
+    .command("stale")
+    .description("pages past their review SLA or without a team owner")
+    .argument("[dir]", "knowledge repo root", ".")
+    .option("--owner-team <team>", "only this team's pages")
+    .option("--json", "machine-readable output")
+    .action((dir, opts) => {
+    const repo = repoAt(dir);
+    const stale = listStale(repo.pages, repo, now(), opts.ownerTeam);
+    if (opts.json)
+        return console.log(JSON.stringify(stale, null, 2));
+    for (const s of stale)
+        console.log(`${s.reason.padEnd(10)} ${s.id.padEnd(30)} @${s.owner_team.padEnd(10)} ${s.detail}`);
+    console.log(`${stale.length} stale or unowned pages`);
+});
+program
+    .command("coverage")
+    .description("ownership coverage: % of pages team-owned and % verified within SLA, by team")
+    .argument("[dir]", "knowledge repo root", ".")
+    .option("--json", "machine-readable output")
+    .option("--html <file>", "also write a static dashboard")
+    .action(async (dir, opts) => {
+    const repo = repoAt(dir);
+    const c = computeCoverage(repo, now());
+    console.log(opts.json ? JSON.stringify(c, null, 2) : formatCoverage(c));
+    if (opts.html)
+        await (await proCommands("coverage --html")).coverageHtml(ctx, c, repo, opts.html);
+});
+program
+    .command("digest")
+    .description("weekly owner digest per team: due, overdue, most read by agents; prints unless --send")
+    .argument("[dir]", "knowledge repo root", ".")
+    .option("--team <team>", "only this team")
+    .option("--send", "post to Slack (webhook from digest.slack_webhook_env / team_webhooks)")
+    .option("--json", "machine-readable output")
+    .action(async (dir, opts) => (await proCommands("digest")).digest(ctx, dir, opts));
+program
+    .command("compile")
+    .description("compile canonical runbooks into SKILL.md files")
+    .argument("[dir]", "knowledge repo root", ".")
+    .option("--out <dir>", "output directory (default: skills.out_dir from config)")
+    .option("--check", "exit 1 if compiled skills drifted from their source pages")
+    .option("--mark-stale", "with --check: mark drifted skills stale in place")
+    .option("--dry-run", "report what would compile without writing")
+    .option("--include-restricted", "also compile runbooks whose acl is not internal")
+    .action(async (dir, opts) => (await proCommands("compile")).compile(ctx, dir, opts));
+program
+    .command("mcp")
+    .description("serve the knowledge repo to agents over MCP (stdio)")
+    .argument("[dir]", "knowledge repo root (default: DOCSWORTH_KNOWLEDGE_DIR, else the current directory)")
+    .action(async (dir) => {
+    // The plugin launcher passes the repo in the environment: on Windows its command line
+    // goes through cmd.exe, which would split a path at a space.
+    const root = resolve(dir ?? (process.env.DOCSWORTH_KNOWLEDGE_DIR || "."));
+    const config = loadConfig(root);
+    const identity = IdentityProvider.fromEnv(config);
+    // Fail closed: in GitHub mode, prove the caller's identity before serving anything.
+    const who = await identity.fresh();
+    const audit = await openAuditLog(root, config);
+    // A required audit log that can't record the start refuses to serve at all.
+    await audit?.emit({ kind: "server_start", actor: actorOf(who), detail: { config_sha256: configHash(root), mode: who.mode, policy: policySummary(config.policy) } });
+    const service = new KnowledgeService(root, identity, now);
+    service.watch();
+    const stdio = new StdioServerTransport();
+    const transport = audit ? auditTransport(stdio, audit, () => identity.get(), {
+        includeQueries: config.audit_log.include_queries,
+        initialActor: actorOf(who),
+        known: () => service.knownValues(),
+        snapshot: () => service.snapshot(),
+    }) : stdio;
+    // The fs watcher keeps the event loop alive. When the client goes away, close it and
+    // let in-flight responses drain; the process then exits on its own.
+    process.stdin.once("end", () => {
+        service.close();
+        // The same details as server_start, for the config in force at the end; a stop the
+        // log can't take is said on stderr rather than lost silently.
+        void audit
+            ?.emit({ kind: "server_stop", actor: actorOf(who), snapshot: service.snapshot(), detail: { config_sha256: configHash(root), mode: who.mode, policy: policySummary(service.policy()) } })
+            .catch((err) => process.stderr.write(`docsworth: couldn't record server_stop: ${err.message}\n`))
+            .then(() => audit.flush());
+    });
+    await createMcpServer(service, { who, whoami: () => identity.get() }).connect(transport);
+    process.stderr.write(`docsworth: serving ${root} (${who.mode}${who.login ? ` as ${who.login}` : ""}) over stdio\n`);
+});
+program
+    .command("serve")
+    .description("serve the knowledge repo to the Docsworth web app and browser extension (MCP over HTTP, on 127.0.0.1 only)")
+    .argument("[dir]", "knowledge repo root (default: DOCSWORTH_KNOWLEDGE_DIR, else the current directory)")
+    .option("--port <n>", "port on 127.0.0.1", (v) => {
+    const n = Number(v);
+    if (!Number.isInteger(n) || n < 0 || n > 65535)
+        throw new InvalidArgumentError("expected a port number");
+    return n;
+}, DEFAULT_PORT)
+    .option("--allow-extension <id>", "let this browser extension (its 32-letter id) call the server; repeatable", (v, prev) => {
+    if (!EXTENSION_ID.test(v))
+        throw new InvalidArgumentError("expected an extension id: 32 letters a to p");
+    return [...prev, v];
+}, [])
+    .option("--rotate-token", "replace the access token first (pair the extension again afterwards)")
+    .option("--print-token", "print the access token, for pairing the extension, and exit")
+    .action(async (dir, opts) => {
+    const root = resolve(dir ?? (process.env.DOCSWORTH_KNOWLEDGE_DIR || "."));
+    const config = loadConfig(root);
+    // In this user's state directory, outside the repo: it can't be committed.
+    const tokenDir = stateDir(root);
+    if (opts.printToken) {
+        console.log(loadToken(tokenDir, { rotate: opts.rotateToken }));
+        return;
+    }
+    const identity = IdentityProvider.fromEnv(config);
+    // Fail closed, as `mcp` does: in GitHub mode, prove the identity before listening.
+    const who = await identity.fresh();
+    const audit = await openAuditLog(root, config);
+    await audit?.emit({ kind: "server_start", actor: actorOf(who), detail: { config_sha256: configHash(root), mode: who.mode, policy: policySummary(config.policy), transport: "http" } });
+    const token = loadToken(tokenDir, { rotate: opts.rotateToken });
+    // The built web app sits next to the built CLI (dist/web); from source there is none.
+    const web = join(dirname(fileURLToPath(import.meta.url)), "web");
+    const serving = await startServer({
+        root,
+        identity,
+        who,
+        audit,
+        includeQueries: config.audit_log.include_queries,
+        now,
+        port: opts.port,
+        token,
+        extensions: new Set(opts.allowExtension),
+        webRoot: existsSync(join(web, "index.html")) ? web : null,
+    }).catch((err) => {
+        if (err.code === "EADDRINUSE")
+            throw new ConfigError(`port ${opts.port} is in use; pick another with --port`);
+        throw err;
+    });
+    // The URL carries the token in its fragment, which the browser never sends to a server.
+    process.stderr.write(`docsworth: serving ${root} (${who.mode}${who.login ? ` as ${who.login}` : ""}) at ${serving.url}\n`);
+    const stop = async () => {
+        await serving.close();
+        await audit
+            ?.emit({ kind: "server_stop", actor: actorOf(who), detail: { config_sha256: configHash(root), mode: who.mode, policy: policySummary(config.policy), transport: "http" } })
+            .catch((err) => process.stderr.write(`docsworth: couldn't record server_stop: ${err.message}\n`));
+        await audit?.flush();
+        process.exit(0);
+    };
+    for (const s of ["SIGINT", "SIGTERM"])
+        process.once(s, () => void stop());
+});
+function configHash(root) {
+    return createHash("sha256").update(readFileSync(join(root, ".knowledge/config.yaml"))).digest("hex");
+}
+function requireEnv(name) {
+    const v = process.env[name];
+    if (!v)
+        throw new ConfigError(`${name} is not set (see .env.example)`);
+    return v;
+}
+program
+    .command("mirror")
+    .description("read-only mirror of Confluence/Notion into .knowledge/mirror, scored for freshness and ownership")
+    .argument("[dir]", "knowledge repo root", ".")
+    .option("--source <name>", "only the source with this name")
+    .action(async (dir, opts) => (await proCommands("mirror")).mirror(ctx, dir, opts));
+program
+    .command("mirror-purge")
+    .description("delete the local mirror cache (all sources, or one); idempotent and audited")
+    .argument("[dir]", "knowledge repo root", ".")
+    .option("--source <kind>", "only this source, as in mirror ids: confluence or notion")
+    .action(async (dir, opts) => (await proCommands("mirror-purge")).mirrorPurge(ctx, dir, opts));
+program
+    .command("promote")
+    .description("open a PR copying a mirrored page into knowledge/ with frontmatter pre-filled")
+    .argument("<mirror-id>", "e.g. mirror:confluence:ENG:12345")
+    .argument("[dir]", "knowledge repo root", ".")
+    .requiredOption("--owner-team <team>", "team that will own the page (must match CODEOWNERS for its path)")
+    .option("--type <type>", "runbook | service | guide | policy", "runbook")
+    .option("--id <id>", "page id (default: derived from the title)")
+    .option("--dir <dir>", "directory under the knowledge root")
+    .option("--dry-run", "print the page instead of opening a PR")
+    .action(async (mirrorId, dir, opts) => (await proCommands("promote")).promote(ctx, mirrorId, dir, opts));
+const bench = program.command("bench").description("citation-accuracy benchmark: diy vs ungated vs gated");
+bench
+    .command("run")
+    .description("answer a question set with Claude under each configuration (spends API credits)")
+    .argument("[dir]", "knowledge repo root", ".")
+    .option("--questions <file>", "questions YAML (default: <dir>/questions.yaml)")
+    .option("--out <dir>", "results directory (default: bench-results/<date>)")
+    .option("--systems <list>", "comma-separated subset of diy,ungated,gated (default: all)")
+    .option("--model <model>", "Claude model", process.env.DOCSWORTH_BENCH_MODEL || "claude-opus-5-5")
+    .option("--limit <n>", "only the first n questions", (v) => Number(v))
+    .option("--concurrency <n>", "parallel runs", (v) => Number(v), 4)
+    .option("--label <text>", "what this run is", "harness validation only")
+    .action(async (dir, opts) => (await proCommands("bench")).benchRun(ctx, dir, opts));
+bench
+    .command("score")
+    .description("owner-graded answer correctness from a filled-in grading.csv")
+    .argument("<results-dir>")
+    .action(async (dir) => (await proCommands("bench")).benchScore(ctx, dir));
+program
+    .command("audit")
+    .description("audit report: ownership coverage, stale and overlapping pages, DIY accuracy score")
+    .argument("[dir]", "knowledge repo root", ".")
+    .option("--bench <results-dir>", "include a bench run's metrics")
+    .option("--out <dir>", "write audit.md and audit.html here", ".")
+    .option("--title <text>", "report title", "Knowledge readiness audit")
+    .action(async (dir, opts) => (await proCommands("audit")).audit(ctx, dir, opts));
+program
+    .command("access-review")
+    .description("who can see, verify and approve what: per page, per team, and with --members per person")
+    .argument("[dir]", "knowledge repo root", ".")
+    .option("--members", "list each team's members through GitHub (your token decides what you see)")
+    .option("--format <md|csv>", "markdown report, or CSV of pages (or people, with --members)", "md")
+    .action(async (dir, opts) => (await proCommands("access-review")).accessReview(ctx, dir, opts));
+program
+    .command("usage-report")
+    .description("what agents asked for, from the audit log: by tool and team, outcomes, top and excluded pages")
+    .argument("[dir]", "knowledge repo root", ".")
+    .option("--since <period>", "how far back, e.g. 7d, 4w, 3m", "30d")
+    .option("--audit-dir <dir>", "read audit files from here instead of the configured directory")
+    .action(async (dir, opts) => (await proCommands("usage-report")).usageReport(ctx, dir, opts));
+export { program };
+const isMain = process.argv[1] && /(?:cli\.(?:ts|js)|docsworth)$/.test(process.argv[1]);
+if (isMain) {
+    program.parseAsync().catch(async (err) => {
+        if (isUserError(err)) {
+            // A message can quote a path or a value a page holds: printed escaped.
+            console.error(`docsworth: ${printable(err.message)}`);
+            // Exit 3 if the failure also left a change its required audit log doesn't show.
+            process.exit(process.exitCode === EXIT_AUDIT_DEGRADED ? EXIT_AUDIT_DEGRADED : 2);
+        }
+        throw err;
+    });
+}

package/dist/core/acl.d.ts

@@ -0,0 +1,37 @@
+import type { MirrorPage } from "./mirror-view.js";
+import type { Page, Repo } from "./repo.js";
+/**
+ * Who is calling. In GitHub mode this comes from the caller's own token, so GitHub's
+ * permissions are the ACL; in local mode (no github.repo) the filesystem is.
+ */
+export interface Identity {
+    mode: "github" | "local";
+    login: string | null;
+    /** Team slugs (lowercase) in the configured org. */
+    teams: ReadonlySet<string>;
+    repoAccess: boolean;
+    /** Push access to the knowledge repo: required to open PRs from a branch. */
+    canWrite: boolean;
+}
+export declare function canSee(page: Pick<Page, "acl">, who: Identity): boolean;
+/** The ONLY way tools obtain pages. Everything downstream works on this filtered list. */
+export declare function visiblePages(repo: Repo, who: Identity): Page[];
+/** The mirrored pages `who` may see: the same rule as pages, on each space's `acl`. */
+export declare function visibleMirror(mirror: readonly MirrorPage[], who: Identity): MirrorPage[];
+export declare const RESTRICTED = "[restricted page]";
+/**
+ * Rewrite every link to a page the caller cannot see, so a visible page (say the root
+ * index) never reveals a hidden page's title or path: inline links and images, angle
+ * destinations, reference-style links (full, collapsed and shortcut) with their
+ * definitions, and HTML anchors.
+ */
+export declare function redactLinks(body: string, fromPath: string, repo: Repo, who: Identity): string;
+/** One pass of the sweep for `who` on page `fromPath`: `liberal`, every route naming nothing fails closed, a link or not. */
+export declare function redactionSweep(fromPath: string, repo: Repo, who: Identity, gone?: Set<string>): (text: string, liberal: boolean) => string;
+/**
+ * `sweep` run until it changes nothing. Replacing a line can change what the rest means (a
+ * fence gone, code is markdown, and its links are links), so a pass can leave work for the
+ * next. Past `passes`, one last `liberal` pass, where every route naming nothing fails
+ * closed, ends it.
+ */
+export declare function untilStable(text: string, sweep: (text: string, liberal: boolean) => string, passes?: number): string;

package/dist/core/acl.js

@@ -0,0 +1,136 @@
+import { ACL_INTERNAL } from "./schema.js";
+import { definitionsIn, destinationHides, linkPaths, normalLabel, namingLines, pageNames, replaceLines } from "./references.js";
+export function canSee(page, who) {
+    if (!who.repoAccess)
+        return false;
+    const acl = page.acl.toLowerCase();
+    return acl === ACL_INTERNAL || who.teams.has(acl);
+}
+/** The ONLY way tools obtain pages. Everything downstream works on this filtered list. */
+export function visiblePages(repo, who) {
+    return repo.pages.filter((p) => canSee(p, who));
+}
+/** The mirrored pages `who` may see: the same rule as pages, on each space's `acl`. */
+export function visibleMirror(mirror, who) {
+    return mirror.filter((m) => canSee(m, who));
+}
+export const RESTRICTED = "[restricted page]";
+// Every span is bounded, and link text stops at a `[` (nested brackets are the sweep's):
+// otherwise `[a` repeated (no `]`) made each `[` scan on, 1 s for 64 KB unbounded and
+// still 270 ms on CI bounded. Longer link text or titles are left to the sweep after.
+const TITLE = String.raw `(?:\s+(?:"[^"]{0,999}"|'[^']{0,999}'|\([^)]{0,999}\)))?`;
+// The destination is matched once, in a lookahead, and never given back character by
+// character: `[a](` repeated made each one retry 2,000 lengths. And it stops where it
+// can't go on: an angle one at `<` (CommonMark), a plain one at `[` (rare in a real
+// destination; the sweep after still reads one).
+const INLINE = new RegExp(String.raw `!?\[([^\][]{0,999})\]\(\s*(?=(<[^<>\n]{0,999}>|[^)\s[]{1,2000}))\2${TITLE}\s*\)`, "g");
+const REF_DEF = new RegExp(String.raw `^ {0,3}\[([^\][\n]{1,999})\]:[ \t]*(?=(<[^<>\n]{0,999}>|\S{1,2000}))\2${TITLE}[ \t]*$`, "gm");
+// An anchor's opening tag, and its quoted href. Read in two steps, linear: one regex for
+// the whole anchor backtracked between its parts (16 KB of `<a href="x">` took 1.7 s).
+const A_OPEN = /<a\b[^<>]{0,999}>/gi;
+// On one line: a value broken across lines (behind quote markers, say) is the sweep's.
+const A_HREF = /\bhref\s*=\s*(?:"([^"\n]*)"|'([^'\n]*)')/i;
+const A_CLOSE = /<\/a\s*>/i;
+/**
+ * Is a link destination a page the caller may not see? Read as the URL it becomes:
+ * escapes, character references and percent-encoding decoded, `\\` as `/`, query and
+ * fragment cut, relative or root-relative. A URL counts when it ends with a hidden page's
+ * path. Anything under the knowledge root that is not a loadable page fails closed: an
+ * invalid page has no trustworthy ACL.
+ */
+function hidesPage(dest, fromPath, repo, who, html = false, links) {
+    return destinationHides(dest, fromPath, namesFor(repo, who), html, links);
+}
+/**
+ * Rewrite every link to a page the caller cannot see, so a visible page (say the root
+ * index) never reveals a hidden page's title or path: inline links and images, angle
+ * destinations, reference-style links (full, collapsed and shortcut) with their
+ * definitions, and HTML anchors.
+ */
+export function redactLinks(body, fromPath, repo, who) {
+    // A route naming nothing fails closed where CommonMark reads a link (references.ts).
+    const links = linkPaths(body);
+    const hidden = (dest) => hidesPage(dest, fromPath, repo, who, false, links);
+    // Reference definitions first: remember which labels point at hidden pages.
+    const hiddenLabels = new Set();
+    // Only the definition CommonMark puts in effect for a label (code review, round 9): a
+    // `]:` inside a paragraph defines nothing, and is left for the sweep.
+    const defs = definitionsIn(body);
+    let out = body.replace(REF_DEF, (whole, label, dest) => {
+        if (!hidden(dest))
+            return whole;
+        const inEffect = defs?.get(normalLabel(label));
+        if (defs && (inEffect === undefined || !hidden(inEffect)))
+            return whole;
+        hiddenLabels.add(label.trim().toLowerCase());
+        return "";
+    });
+    if (hiddenLabels.size) {
+        // [text][label], [label][] and the shortcut form [label].
+        out = out.replace(/\[([^\][]{0,999})\]\[([^\][]{0,999})\]/g, (whole, text, label) => hiddenLabels.has((label || text).trim().toLowerCase()) ? RESTRICTED : whole);
+        // Not a label right after a `]`: that's a full reference whose text the form above
+        // couldn't read (it holds brackets: merge gate, PR 53, round 3), and the label alone
+        // would leave its text. The sweep takes those lines whole.
+        out = out.replace(/(?<!\])\[([^\][]{1,999})\](?![(\[:])/g, (whole, label) => (hiddenLabels.has(label.trim().toLowerCase()) ? RESTRICTED : whole));
+    }
+    out = out.replace(INLINE, (whole, _text, dest) => (hidden(dest) ? RESTRICTED : whole));
+    out = redactAnchors(out, (href) => hidesPage(href, fromPath, repo, who, true));
+    // The passes above keep the rest of a line, but read only the common forms. The sweep
+    // after them fails closed: a line that still names a hidden page, in any form a reader
+    // resolves, goes whole (references.ts).
+    // The labels the first pass took the definitions of: the sweep takes their references,
+    // which the forms above miss (`[ref]:` that can't start a definition is one).
+    return untilStable(out, redactionSweep(fromPath, repo, who, new Set(hiddenLabels)));
+}
+/** One pass of the sweep for `who` on page `fromPath`: `liberal`, every route naming nothing fails closed, a link or not. */
+export function redactionSweep(fromPath, repo, who, gone = new Set()) {
+    const names = namesFor(repo, who);
+    // `gone`: the labels the first pass took the definitions of, whose references each pass
+    // takes too.
+    return (text, liberal) => replaceLines(text, namingLines(text, fromPath, names, 0, [], liberal, gone), RESTRICTED);
+}
+/**
+ * `sweep` run until it changes nothing. Replacing a line can change what the rest means (a
+ * fence gone, code is markdown, and its links are links), so a pass can leave work for the
+ * next. Past `passes`, one last `liberal` pass, where every route naming nothing fails
+ * closed, ends it.
+ */
+export function untilStable(text, sweep, passes = 3) {
+    for (let pass = 1;; pass++) {
+        const next = sweep(text, pass > passes);
+        if (next === text || pass > passes)
+            return next;
+        text = next;
+    }
+}
+/** Each `<a href="…">…</a>` whose href is hidden, as the placeholder (its `</a>` within 4,000 characters). */
+function redactAnchors(text, hidden) {
+    let out = "";
+    let at = 0;
+    for (const m of text.matchAll(A_OPEN)) {
+        if (m.index < at)
+            continue;
+        const href = A_HREF.exec(m[0]);
+        if (!href || !hidden(href[1] ?? href[2]))
+            continue;
+        const after = m.index + m[0].length;
+        const close = A_CLOSE.exec(text.slice(after, after + 4000));
+        if (!close)
+            continue; // the sweep after still reads the tag
+        out += text.slice(at, m.index) + RESTRICTED;
+        at = after + close.index + close[0].length;
+    }
+    return out + text.slice(at);
+}
+// Per repo (a reload makes a new one) and per audience: the teams decide what's hidden.
+const NAMES = new WeakMap();
+function namesFor(repo, who) {
+    const key = `${who.repoAccess}:${[...who.teams].sort().join(",")}`;
+    let byAudience = NAMES.get(repo);
+    if (!byAudience)
+        NAMES.set(repo, (byAudience = new Map()));
+    let names = byAudience.get(key);
+    if (!names)
+        byAudience.set(key, (names = pageNames(repo, (p) => !canSee(p, who))));
+    return names;
+}