@docsworth/cli 0.0.0-stage → 0.2.0

package/dist/core/github.js

@@ -0,0 +1,234 @@
+// Minimal GitHub REST client over fetch. Deliberately small: every call the server makes
+// is listed here, which keeps the write path reviewable and lets tests inject a fake.
+import { insecureUrl, urlForError } from "./url.js";
+export class GitHubError extends Error {
+    status;
+    method;
+    path;
+    headers;
+    /** GitHub's rate limits: a 429, or a 403 that says so (primary or secondary limit). */
+    rateLimited;
+    /** Seconds GitHub asked to wait (`retry-after`, or until `x-ratelimit-reset`), if it said. */
+    retryAfter;
+    constructor(
+    /** The HTTP status; 0 when GitHub didn't answer (a network error or a timeout). */
+    status, method, path, message, 
+    /** Response headers, e.g. `x-github-sso` on a 403 from an SSO-enforcing org. */
+    headers = null, now = Date.now()) {
+        const limited = status === 429 ||
+            // GitHub's secondary limits come as a 403 (or 429) with `retry-after`, its primary
+            // limit with `x-ratelimit-remaining: 0`; the message says so too.
+            (status === 403 && (headers?.get("x-ratelimit-remaining") === "0" || Boolean(headers?.has("retry-after")) || /rate limit/i.test(message)));
+        const after = Number(headers?.get("retry-after"));
+        const reset = Number(headers?.get("x-ratelimit-reset"));
+        const wait = Number.isFinite(after) && headers?.has("retry-after") ? after : limited && Number.isFinite(reset) && reset > 0 ? Math.max(0, Math.ceil(reset - now / 1000)) : null;
+        super(`GitHub ${method} ${path} → ${status || "no answer"}: ${message}${limited ? ` (rate limited${wait !== null ? `; retry in ${wait} s` : ""})` : ""}`);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.headers = headers;
+        this.rateLimited = limited;
+        this.retryAfter = wait;
+    }
+}
+// Reads are retried on what passes (no answer, a 5xx, a rate limit GitHub says lifts
+// within a few seconds); writes never are, since a retried POST could open a second PR.
+const ATTEMPTS = 3;
+const BACKOFF_MS = [500, 1500];
+const MAX_WAIT_S = 10;
+const TIMEOUT_MS = 30_000;
+export class GitHubClient {
+    token;
+    fetch;
+    baseUrl;
+    sleep;
+    now;
+    timeoutMs;
+    constructor(token, opts = {}) {
+        this.token = token;
+        this.fetch = opts.fetch ?? ((url, init) => fetch(url, init));
+        this.baseUrl = (opts.baseUrl ?? "https://api.github.com").replace(/\/$/, "");
+        this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.now = opts.now ?? Date.now;
+        this.timeoutMs = opts.timeoutMs ?? TIMEOUT_MS;
+        // Also reached from DOCSWORTH_GITHUB_API_URL, which no config schema sees.
+        const why = insecureUrl(this.baseUrl);
+        if (why)
+            throw new Error(`the GitHub API URL (${urlForError(this.baseUrl)}) ${why}`);
+    }
+    async request(method, path, body, accept = "application/vnd.github+json") {
+        const read = method === "GET" || method === "HEAD";
+        // Serialized once, outside the retry: a body that can't be (a fault here) throws as is.
+        const payload = body === undefined ? undefined : JSON.stringify(body);
+        for (let attempt = 1;; attempt++) {
+            let res;
+            let text;
+            try {
+                res = await this.fetch(`${this.baseUrl}${path}`, {
+                    method,
+                    headers: {
+                        authorization: `Bearer ${this.token}`,
+                        accept,
+                        "x-github-api-version": "2022-11-28",
+                        "user-agent": "docsworth",
+                        ...(body === undefined ? {} : { "content-type": "application/json" }),
+                    },
+                    body: payload,
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+                text = await res.text();
+            }
+            catch (cause) {
+                // No answer: the connection failed (fetch's TypeError, or undici's "terminated" when
+                // it drops while the body is read), or nothing came within the timeout. Anything
+                // else is a fault here, not GitHub's, and isn't retried.
+                const timedOut = cause instanceof Error && (cause.name === "TimeoutError" || cause.name === "AbortError");
+                if (!timedOut && !(cause instanceof TypeError))
+                    throw cause;
+                const err = new GitHubError(0, method, path, timedOut ? `no answer within ${this.timeoutMs / 1000} s` : `network error (${cause.message})`, null, this.now());
+                if (read && attempt < ATTEMPTS) {
+                    await this.sleep(BACKOFF_MS[attempt - 1]);
+                    continue;
+                }
+                throw err;
+            }
+            if (!res.ok) {
+                let message = text.slice(0, 300);
+                try {
+                    message = JSON.parse(text).message ?? message;
+                }
+                catch {
+                    /* non-JSON error body */
+                }
+                const err = new GitHubError(res.status, method, path, message, res.headers, this.now());
+                // A 5xx is retried on the backoff. A rate limit only when GitHub says it lifts
+                // within 10 s: without a time, retrying soon prolongs it (GitHub asks for a minute).
+                const wait = err.rateLimited ? (err.retryAfter !== null && err.retryAfter <= MAX_WAIT_S ? err.retryAfter * 1000 : null) : res.status >= 500 ? BACKOFF_MS[attempt - 1] : null;
+                if (read && wait !== null && attempt < ATTEMPTS) {
+                    await this.sleep(wait);
+                    continue;
+                }
+                throw err;
+            }
+            return { data: (text ? JSON.parse(text) : null), headers: res.headers };
+        }
+    }
+    async get(path) {
+        return (await this.request("GET", path)).data;
+    }
+    /** Follow `Link: rel="next"` pagination; `onHeaders` sees every page's headers. */
+    async paginate(path, onHeaders) {
+        const out = [];
+        let next = `${path}${path.includes("?") ? "&" : "?"}per_page=100`;
+        while (next) {
+            const { data, headers } = await this.request("GET", next);
+            onHeaders?.(headers);
+            out.push(...data);
+            const link = /<([^>]+)>;\s*rel="next"/.exec(headers.get("link") ?? "");
+            next = link ? link[1].replace(this.baseUrl, "") : null;
+        }
+        return out;
+    }
+    getUser() {
+        return this.get("/user");
+    }
+    getRepo(repo) {
+        return this.get(`/repos/${repo}`);
+    }
+    /**
+     * The caller's teams, and the ids of orgs GitHub left out because the token isn't
+     * authorized for their SAML SSO (`x-github-sso: partial-results; organizations=…`).
+     */
+    async listMyTeams() {
+        const withheld = new Set();
+        const teams = await this.paginate("/user/teams", (h) => {
+            for (const id of parseSsoHeader(h.get("x-github-sso")).organizations)
+                withheld.add(id);
+        });
+        return { teams, ssoWithheldOrgIds: [...withheld] };
+    }
+    /** Logins of a team's members (needs read:org, or members:read on a fine-grained token). */
+    async listTeamMembers(org, team) {
+        return (await this.paginate(`/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(team)}/members`)).map((m) => m.login);
+    }
+    /**
+     * Does a team have write access to a repo? GitHub ignores a CODEOWNERS team without it.
+     * true/false when GitHub shows the permission; null on a 404, which GitHub gives both
+     * for "no access" and for a team this caller can't see, so it proves nothing.
+     */
+    async teamCanPush(org, team, repo) {
+        try {
+            const { data } = await this.request("GET", `/orgs/${encodeURIComponent(org)}/teams/${encodeURIComponent(team)}/repos/${repo}`, undefined, "application/vnd.github.v3.repository+json");
+            return Boolean(data?.permissions?.push);
+        }
+        catch (err) {
+            if (err instanceof GitHubError && err.status === 404)
+                return null;
+            throw err;
+        }
+    }
+    /** A user's permission on a repo: admin, maintain, write, triage, read or none. */
+    async getUserPermission(repo, login) {
+        return (await this.get(`/repos/${repo}/collaborators/${encodeURIComponent(login)}/permission`)).permission;
+    }
+    /** Ruleset rules that apply to a branch (readable with read access). */
+    getBranchRules(repo, branch) {
+        return this.get(`/repos/${repo}/rules/branches/${encodePath(branch)}`);
+    }
+    /** A ruleset, with `bypass_actors` when this token may see them (admins). */
+    getRuleset(repo, id) {
+        return this.get(`/repos/${repo}/rulesets/${id}`);
+    }
+    /** Classic branch protection (GitHub answers 403/404 to callers without admin). */
+    getBranchProtection(repo, branch) {
+        return this.get(`/repos/${repo}/branches/${encodePath(branch)}/protection`);
+    }
+    getFile(repo, path, ref) {
+        return this.get(`/repos/${repo}/contents/${encodePath(path)}?ref=${encodeURIComponent(ref)}`);
+    }
+    async getBranchSha(repo, branch) {
+        return (await this.get(`/repos/${repo}/git/ref/heads/${encodePath(branch)}`)).object.sha;
+    }
+    async createBranch(repo, branch, sha) {
+        await this.request("POST", `/repos/${repo}/git/refs`, { ref: `refs/heads/${branch}`, sha });
+    }
+    async deleteBranch(repo, branch) {
+        await this.request("DELETE", `/repos/${repo}/git/refs/heads/${encodePath(branch)}`);
+    }
+    /** Always pass `branch`: omitting it makes GitHub write to the default branch. */
+    async putFile(repo, path, args) {
+        await this.request("PUT", `/repos/${repo}/contents/${encodePath(path)}`, {
+            message: args.message,
+            content: Buffer.from(args.content, "utf8").toString("base64"),
+            sha: args.sha,
+            branch: args.branch,
+        });
+    }
+    /** An open PR from `branch` into `base` in the same repo, if one exists. */
+    async findPull(repo, branch, base) {
+        const owner = repo.split("/")[0];
+        const q = `head=${encodeURIComponent(`${owner}:${branch}`)}&base=${encodeURIComponent(base)}&state=open`;
+        return (await this.get(`/repos/${repo}/pulls?${q}`))[0] ?? null;
+    }
+    async createPull(repo, args) {
+        return (await this.request("POST", `/repos/${repo}/pulls`, args)).data;
+    }
+}
+/** `required; url=https://…` or `partial-results; organizations=1,2`. */
+export function parseSsoHeader(value) {
+    if (!value)
+        return { required: false, url: null, organizations: [] };
+    const parts = value.split(";").map((p) => p.trim());
+    const field = (k) => parts.find((p) => p.startsWith(`${k}=`))?.slice(k.length + 1) ?? null;
+    return {
+        required: parts[0] === "required",
+        url: field("url"),
+        organizations: (field("organizations") ?? "").split(",").map((s) => s.trim()).filter(Boolean),
+    };
+}
+function encodePath(p) {
+    return p.split("/").map(encodeURIComponent).join("/");
+}
+export function decodeContent(file) {
+    return Buffer.from(file.content, file.encoding === "base64" ? "base64" : "utf8").toString("utf8");
+}

package/dist/core/host.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Everything Docsworth pro may use of core, and nothing else. Pro imports core only through
+ * this file, which a test holds to the list below: pro is another package, and this is the
+ * one entry point the CLI exports to it.
+ *
+ * HOST_API is the contract's version. Pro declares the version it was built for, and the
+ * CLI refuses a pro built for another, with a message naming both, rather than failing
+ * somewhere inside a command. The check is equality, so raise it whenever the contract
+ * changes at all: a name here added, removed or changed in meaning, or what the CLI and
+ * pro expect of each other (ProCommands, CommandContext, pro's entry points).
+ * 2: pro's commands behind ProCommands, and the names they use (pro-split step 2).
+ * 3: buildNewPage, NEW_PAGE_PREFIX and slugify: promote builds its page with core's builder,
+ *    which draft_page shares.
+ */
+import type { AuditActor, AuditLog, AuditSink } from "./audit-log.js";
+import type { Config } from "./config.js";
+import type { Coverage } from "./coverage.js";
+import type { MirrorPage } from "./mirror-view.js";
+import type { Repo } from "./repo.js";
+import type { PageType } from "./schema.js";
+export declare const HOST_API = 3;
+export { canSee, type Identity, visiblePages } from "./acl.js";
+export { type AuditActor, type AuditEvent, type AuditLog, type AuditSink, actorOf, resolveAuditDir, writeAll } from "./audit-log.js";
+export { matchRule, resolveTeamOwner } from "./codeowners.js";
+export { type Config, CONFIG_PATH, ConfigError } from "./config.js";
+export { computeCoverage, type Coverage, type CoverageRow } from "./coverage.js";
+export { formatDate, parseDuration, subtractDuration, utcToday } from "./duration.js";
+export { isUserError, UserError } from "./errors.js";
+export { splitFrontmatter } from "./frontmatter.js";
+export { pageStatus } from "./gate.js";
+export { type FetchLike, type GitHubClient, GitHubError } from "./github.js";
+export { IdentityProvider, LOCAL_IDENTITY, resolveToken } from "./identity.js";
+export { INSTRUCTIONS, readDescription, searchDescription } from "./mcp/text.js";
+export { buildNewPage, NEW_PAGE_PREFIX, slugify } from "./new-page.js";
+export { canonicalDir, loadMirror, lstatExists, MIRROR_SOURCES, type MirrorPage, type MirrorSource, mirrorRecordPath, ownedFiles, ownedSpaceFiles, readOwned, sha256, } from "./mirror-view.js";
+export { isPage, type Page, parsePage, type Repo, resolveLink } from "./repo.js";
+export { ACL_INTERNAL, type PageType } from "./schema.js";
+export { SearchIndex, snippet, tokenize } from "./search.js";
+export { KnowledgeService, ToolError } from "./service.js";
+export { listStale, type StaleEntry } from "./stale.js";
+export { insecureUrl, urlForError } from "./url.js";
+export { openPagePr, type PrResult } from "./writes.js";
+/** A source of mirrored pages (Confluence, Notion): pro's connectors implement it. */
+export interface Connector {
+    readonly source: MirrorPage["source"];
+    readonly space: string;
+    pages(): AsyncIterable<MirrorPage>;
+    /** Pages the token can see but which carry read restrictions (never mirrored). */
+    readonly skippedRestricted: string[];
+    readonly requestCount: number;
+}
+/** The systems the benchmark compares. */
+export type SystemName = "diy" | "ungated" | "gated";
+/** What a pro command gets from the CLI that runs it. */
+export interface CommandContext {
+    /** "Now" for every SLA computation (`--as-of` pins it). */
+    now(): Date;
+    repoAt(dir: string | undefined): Repo;
+    /** Who ran a local command, for audit events with no GitHub identity. */
+    cliActor(): AuditActor;
+    /** The repo's audit log: the core file sink, plus pro's HTTP sink if configured. */
+    openAuditLog(root: string, config: Config): Promise<AuditLog | null>;
+    /** The change happened but its outcome isn't in a required log: say so, exit 3. */
+    auditDegraded(err: unknown, what: string): void;
+    /** An environment variable the command can't run without (a ConfigError if unset). */
+    requireEnv(name: string): string;
+}
+/**
+ * Pro's commands. The CLI defines each one (its name, arguments, options and help, so help
+ * reads the same without pro) and calls these for what it does.
+ */
+export interface ProCommands {
+    /** `coverage --html`: the dashboard for coverage the CLI computed. */
+    coverageHtml(ctx: CommandContext, coverage: Coverage, repo: Repo, file: string): Promise<void>;
+    digest(ctx: CommandContext, dir: string, opts: {
+        team?: string;
+        send?: boolean;
+        json?: boolean;
+    }): Promise<void>;
+    compile(ctx: CommandContext, dir: string, opts: {
+        out?: string;
+        check?: boolean;
+        markStale?: boolean;
+        dryRun?: boolean;
+        includeRestricted?: boolean;
+    }): Promise<void>;
+    mirror(ctx: CommandContext, dir: string, opts: {
+        source?: string;
+    }): Promise<void>;
+    mirrorPurge(ctx: CommandContext, dir: string, opts: {
+        source?: string;
+    }): Promise<void>;
+    promote(ctx: CommandContext, mirrorId: string, dir: string, opts: {
+        ownerTeam: string;
+        type: PageType;
+        id?: string;
+        dir?: string;
+        dryRun?: boolean;
+    }): Promise<void>;
+    benchRun(ctx: CommandContext, dir: string, opts: {
+        questions?: string;
+        out?: string;
+        systems?: string;
+        model: string;
+        limit?: number;
+        concurrency: number;
+        label: string;
+    }): Promise<void>;
+    benchScore(ctx: CommandContext, dir: string): Promise<void>;
+    audit(ctx: CommandContext, dir: string, opts: {
+        bench?: string;
+        out: string;
+        title: string;
+    }): Promise<void>;
+    accessReview(ctx: CommandContext, dir: string, opts: {
+        members?: boolean;
+        format: string;
+    }): Promise<void>;
+    usageReport(ctx: CommandContext, dir: string, opts: {
+        since: string;
+        auditDir?: string;
+    }): Promise<void>;
+    /** The HTTP audit sink, if `audit_http` is configured (null if it isn't). */
+    httpSinkFromRepo(root: string): Promise<AuditSink | null>;
+}

package/dist/core/host.js

@@ -0,0 +1,22 @@
+export const HOST_API = 3;
+export { canSee, visiblePages } from "./acl.js";
+export { actorOf, resolveAuditDir, writeAll } from "./audit-log.js";
+export { matchRule, resolveTeamOwner } from "./codeowners.js";
+export { CONFIG_PATH, ConfigError } from "./config.js";
+export { computeCoverage } from "./coverage.js";
+export { formatDate, parseDuration, subtractDuration, utcToday } from "./duration.js";
+export { isUserError, UserError } from "./errors.js";
+export { splitFrontmatter } from "./frontmatter.js";
+export { pageStatus } from "./gate.js";
+export { GitHubError } from "./github.js";
+export { IdentityProvider, LOCAL_IDENTITY, resolveToken } from "./identity.js";
+export { INSTRUCTIONS, readDescription, searchDescription } from "./mcp/text.js";
+export { buildNewPage, NEW_PAGE_PREFIX, slugify } from "./new-page.js";
+export { canonicalDir, loadMirror, lstatExists, MIRROR_SOURCES, mirrorRecordPath, ownedFiles, ownedSpaceFiles, readOwned, sha256, } from "./mirror-view.js";
+export { isPage, parsePage, resolveLink } from "./repo.js";
+export { ACL_INTERNAL } from "./schema.js";
+export { SearchIndex, snippet, tokenize } from "./search.js";
+export { KnowledgeService, ToolError } from "./service.js";
+export { listStale } from "./stale.js";
+export { insecureUrl, urlForError } from "./url.js";
+export { openPagePr } from "./writes.js";

package/dist/core/identity.d.ts

@@ -0,0 +1,39 @@
+import type { Identity } from "./acl.js";
+import { UserError } from "./errors.js";
+import type { Config } from "./config.js";
+import { GitHubClient } from "./github.js";
+export declare class IdentityError extends UserError {
+}
+/** GITHUB_TOKEN → GH_TOKEN → `gh auth token`, so the 5-minute quickstart needs no setup. */
+export declare function resolveToken(env?: NodeJS.ProcessEnv): string | null;
+export declare const LOCAL_IDENTITY: Identity;
+/**
+ * GitHub App installation tokens (`ghs_`) act for an app, not a person, so they can't
+ * carry anyone's team ACLs or attribute an audit event. Personal tokens (classic or
+ * fine-grained), OAuth tokens (`gh auth token`) and GitHub App *user* tokens are fine.
+ */
+export declare function refuseInstallationToken(token: string): void;
+/**
+ * Resolves and caches the caller's identity.
+ *
+ *  - github.repo set + token: identity from GitHub, cached for 5 minutes. Failure is
+ *    fatal (fail closed): a silent fallback would hide that ACLs are not being checked.
+ *  - github.repo set, no token: refuse. GitHub is the ACL authority for this repo.
+ *  - no github.repo: local-only repo; filesystem access is the authority, so the caller
+ *    sees `internal` pages, never team pages, and cannot write.
+ */
+export declare class IdentityProvider {
+    private readonly config;
+    readonly github: GitHubClient | null;
+    private readonly clock;
+    private readonly log;
+    private cached;
+    /** policy.identity_cache_seconds: the window in which a removed member can still read. */
+    private readonly ttlMs;
+    constructor(config: Config, github: GitHubClient | null, clock?: () => number, log?: (msg: string) => void);
+    static fromEnv(config: Config, env?: NodeJS.ProcessEnv, clientOpts?: ConstructorParameters<typeof GitHubClient>[1]): IdentityProvider;
+    /** Cached identity for reads. */
+    get(): Promise<Identity>;
+    /** Re-resolve from GitHub now (writes always do this). */
+    fresh(): Promise<Identity>;
+}

package/dist/core/identity.js

@@ -0,0 +1,127 @@
+import { spawnSync } from "node:child_process";
+import { UserError } from "./errors.js";
+import { GitHubClient, GitHubError, parseSsoHeader } from "./github.js";
+export class IdentityError extends UserError {
+}
+/** GITHUB_TOKEN → GH_TOKEN → `gh auth token`, so the 5-minute quickstart needs no setup. */
+export function resolveToken(env = process.env) {
+    const fromEnv = env.GITHUB_TOKEN || env.GH_TOKEN;
+    if (fromEnv)
+        return fromEnv.trim();
+    if (env.DOCSWORTH_NO_GH_CLI)
+        return null;
+    const gh = spawnSync("gh", ["auth", "token"], { encoding: "utf8", timeout: 5000 });
+    const token = gh.status === 0 ? gh.stdout.trim() : "";
+    return token || null;
+}
+export const LOCAL_IDENTITY = { mode: "local", login: null, teams: new Set(), repoAccess: true, canWrite: false };
+/**
+ * GitHub App installation tokens (`ghs_`) act for an app, not a person, so they can't
+ * carry anyone's team ACLs or attribute an audit event. Personal tokens (classic or
+ * fine-grained), OAuth tokens (`gh auth token`) and GitHub App *user* tokens are fine.
+ */
+export function refuseInstallationToken(token) {
+    if (token.startsWith("ghs_"))
+        throw new IdentityError("this is a GitHub App installation token, which acts for no person; use your own token (`gh auth token`, a personal access token, or a GitHub App user token)");
+}
+/**
+ * Resolves and caches the caller's identity.
+ *
+ *  - github.repo set + token: identity from GitHub, cached for 5 minutes. Failure is
+ *    fatal (fail closed): a silent fallback would hide that ACLs are not being checked.
+ *  - github.repo set, no token: refuse. GitHub is the ACL authority for this repo.
+ *  - no github.repo: local-only repo; filesystem access is the authority, so the caller
+ *    sees `internal` pages, never team pages, and cannot write.
+ */
+export class IdentityProvider {
+    config;
+    github;
+    clock;
+    log;
+    cached = null;
+    /** policy.identity_cache_seconds: the window in which a removed member can still read. */
+    ttlMs;
+    constructor(config, github, clock = Date.now, log = (m) => process.stderr.write(`docsworth: ${m}\n`)) {
+        this.config = config;
+        this.github = github;
+        this.clock = clock;
+        this.log = log;
+        this.ttlMs = config.policy.identity_cache_seconds * 1000;
+        if (config.github.repo && !github) {
+            throw new IdentityError(`github.repo is ${config.github.repo}, so a GitHub token is required (set GITHUB_TOKEN or run \`gh auth login\`)`);
+        }
+    }
+    static fromEnv(config, env = process.env, clientOpts = {}) {
+        const token = config.github.repo ? resolveToken(env) : null;
+        if (token)
+            refuseInstallationToken(token);
+        const baseUrl = env.DOCSWORTH_GITHUB_API_URL || config.github.api_url;
+        return new IdentityProvider(config, token ? new GitHubClient(token, { baseUrl, ...clientOpts }) : null);
+    }
+    /** Cached identity for reads. */
+    async get() {
+        if (!this.github)
+            return LOCAL_IDENTITY;
+        if (this.cached && this.clock() - this.cached.at < this.ttlMs)
+            return this.cached.identity;
+        return this.fresh();
+    }
+    /** Re-resolve from GitHub now (writes always do this). */
+    async fresh() {
+        if (!this.github)
+            return LOCAL_IDENTITY;
+        const repo = this.config.github.repo;
+        try {
+            const [user, info] = await Promise.all([this.github.getUser(), this.github.getRepo(repo)]);
+            let teams = [];
+            try {
+                const mine = await this.github.listMyTeams();
+                teams = mine.teams.filter((t) => t.organization.login.toLowerCase() === this.config.github.org).map((t) => t.slug.toLowerCase());
+                const org = this.config.github.org;
+                // GitHub leaves out teams of orgs whose SSO this token isn't authorized for. Say so
+                // only when that is the configured org (known when it owns the repo).
+                const ownerIsOrg = info.owner?.login.toLowerCase() === org;
+                if (mine.ssoWithheldOrgIds.length && (!ownerIsOrg || mine.ssoWithheldOrgIds.includes(String(info.owner.id))))
+                    this.log(ownerIsOrg
+                        ? `this token isn't authorized for ${org}'s SAML SSO, so GitHub withheld its teams; team-ACL pages stay hidden until you authorize it`
+                        : `GitHub withheld teams of org id(s) ${mine.ssoWithheldOrgIds.join(", ")} (SAML SSO not authorized for this token); if one is ${org}, team-ACL pages stay hidden`);
+            }
+            catch (err) {
+                // A rate limit isn't a missing scope: an identity with no teams would hide team
+                // pages for the whole cache window and blame the token.
+                if (!(err instanceof GitHubError) || err.status !== 403 || err.rateLimited)
+                    throw err;
+                // SSO first: a 403 that carries `x-github-sso: required` isn't a missing scope.
+                // Rethrown, it fails closed below with the authorization link.
+                if (parseSsoHeader(err.headers?.get("x-github-sso") ?? null).required)
+                    throw err;
+                this.log("token lacks read:org; team-ACL pages will stay hidden");
+            }
+            const identity = {
+                mode: "github",
+                login: user.login,
+                teams: new Set(teams),
+                repoAccess: true,
+                canWrite: Boolean(info.permissions?.push),
+            };
+            this.cached = { identity, at: this.clock() };
+            return identity;
+        }
+        catch (err) {
+            this.cached = null;
+            const sso = err instanceof GitHubError ? parseSsoHeader(err.headers?.get("x-github-sso") ?? null) : null;
+            if (sso?.required)
+                throw new IdentityError(`this token isn't authorized for ${this.config.github.org}'s SAML single sign-on${sso.url ? `; authorize it at ${sso.url} (the link expires in an hour)` : ""}, or use a fine-grained or GitHub App token`);
+            // A rate limit is a 403 too, and isn't "no access": say what it is and when it lifts.
+            if (err instanceof GitHubError && err.rateLimited)
+                throw new IdentityError(`GitHub's rate limit for this token is reached${err.retryAfter !== null ? `; it lifts in ${Math.ceil(err.retryAfter / 60)} min` : ""}, so access can't be checked until then`);
+            if (err instanceof GitHubError && err.status === 403 && /not accessible by integration/i.test(err.message) && err.path === "/user")
+                throw new IdentityError("this token can't identify a person (GitHub App installation token?); use your own token");
+            if (err instanceof GitHubError && (err.status === 404 || err.status === 403))
+                throw new IdentityError(`no access to ${repo} with this token (GitHub said ${err.status})`);
+            if (err instanceof GitHubError && err.status === 401)
+                throw new IdentityError("GitHub rejected the token (401)");
+            throw new IdentityError(`could not resolve identity from GitHub: ${err.message}`);
+        }
+    }
+}

package/dist/core/init.d.ts

@@ -0,0 +1,25 @@
+import { UserError } from "./errors.js";
+export interface InitOptions {
+    org: string;
+    team: string;
+    repo?: string;
+    ci?: boolean;
+    now: Date;
+    /** The package the CI workflow runs; defaults to PUBLISHED_PACKAGE (tests pass one). */
+    package?: string;
+}
+export declare class InitError extends UserError {
+}
+export interface InitResult {
+    created: string[];
+    skipped: string[];
+    hints: string[];
+}
+/** owner/name from the origin remote, if it is a GitHub URL. */
+export declare function githubRemote(root: string): {
+    owner: string;
+    name: string;
+} | null;
+/** `.knowledge/.gitignore`: local state that must never be committed. */
+export declare const LOCAL_STATE_GITIGNORE = "# Written by Docsworth at runtime; never commit these.\nusage.jsonl\nmirror/\ncache/\naudit/\n";
+export declare function initRepo(root: string, opts: InitOptions): InitResult;

package/dist/core/init.js

@@ -0,0 +1,86 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CODEOWNERS_LOCATIONS } from "./codeowners.js";
+import { formatDate, utcToday } from "./duration.js";
+import { UserError } from "./errors.js";
+import { ownedPackage, PUBLISHED_PACKAGE } from "./version.js";
+export class InitError extends UserError {
+}
+/** owner/name from the origin remote, if it is a GitHub URL. */
+export function githubRemote(root) {
+    const r = spawnSync("git", ["-C", root, "remote", "get-url", "origin"], { encoding: "utf8" });
+    const m = /github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?\s*$/.exec(r.stdout ?? "");
+    return m ? { owner: m[1], name: m[2] } : null;
+}
+function page(fm, body) {
+    return `---\n${Object.entries(fm).map(([k, v]) => `${k}: ${v}`).join("\n")}\n---\n${body}`;
+}
+/** `.knowledge/.gitignore`: local state that must never be committed. */
+export const LOCAL_STATE_GITIGNORE = "# Written by Docsworth at runtime; never commit these.\nusage.jsonl\nmirror/\ncache/\naudit/\n";
+export function initRepo(root, opts) {
+    // Before anything is written: a workflow naming a package we don't own would run a
+    // stranger's code in the customer's CI, with a token that can push.
+    const pkg = opts.package ?? PUBLISHED_PACKAGE;
+    if (opts.ci && !ownedPackage(pkg))
+        throw new InitError(`--ci would run \`${pkg}\`, which isn't a plain npm package and range we own (\`@scope/name@^1.2\`)`);
+    const today = formatDate(utcToday(opts.now));
+    const res = { created: [], skipped: [], hints: [] };
+    const write = (rel, content) => {
+        const abs = join(root, rel);
+        if (existsSync(abs))
+            return void res.skipped.push(rel);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, content);
+        res.created.push(rel);
+    };
+    const base = { owner_team: opts.team, status: "canonical", last_verified: today };
+    write(".knowledge/config.yaml", [
+        "# Docsworth configuration. See docs/format-spec.md in the Docsworth repo.",
+        "format: 1",
+        "knowledge_root: knowledge",
+        "github:",
+        `  org: ${opts.org.toLowerCase()}`,
+        opts.repo ? `  repo: ${opts.repo}` : "  # repo: owner/name   # set to make GitHub the ACL authority and enable PR tools",
+        "sla:",
+        "  due_soon_days: 14",
+        "usage_log: true",
+        "skills:",
+        "  out_dir: skills",
+        "",
+    ].join("\n"));
+    // Runtime state the CLI and server write next to the config. None of it belongs in git:
+    // the usage log names pages people read, the mirror holds copies of the old wiki.
+    write(".knowledge/.gitignore", LOCAL_STATE_GITIGNORE);
+    const existingCodeowners = CODEOWNERS_LOCATIONS.find((l) => existsSync(join(root, l)));
+    if (existingCodeowners) {
+        res.skipped.push(existingCodeowners);
+        if (!/^\/?knowledge\//m.test(readFileSync(join(root, existingCodeowners), "utf8")))
+            res.hints.push(`add \`/knowledge/ @${opts.org}/${opts.team}\` to ${existingCodeowners}; every knowledge page needs exactly one owning team`);
+    }
+    else {
+        write("CODEOWNERS", `# Knowledge ownership: exactly one team per path (enforced by \`docsworth lint\`).\n/knowledge/ @${opts.org}/${opts.team}\n`);
+    }
+    write("knowledge/index.md", page({ title: "Engineering knowledge", id: "index", type: "guide", ...base, review_every: "90d", description: "Root map of this knowledge base. Agents read this first." }, "# Engineering knowledge\n\nStart here. Each page has one owning team and a review date; agents only cite pages that are canonical and inside their review window.\n\n## Guides\n- [Writing and verifying pages](guides/writing-pages.md)\n\nSee also the [glossary](glossary.md).\n"));
+    write("knowledge/glossary.md", page({ title: "Glossary", id: "glossary", type: "guide", ...base, review_every: "180d", description: "Acronyms and codenames." }, "# Glossary\n\n- **Canonical**: a page agents may cite, once it is verified within its review period.\n"));
+    write("knowledge/guides/writing-pages.md", page({ title: "Writing and verifying pages", id: "guide-writing-pages", type: "guide", ...base, review_every: "180d", description: "How to add, change and verify pages in this knowledge base." }, [
+        "# Writing and verifying pages",
+        "",
+        "## Adding a page",
+        "1. Create a markdown file under `knowledge/` with the frontmatter fields `title`, `id`, `type`, `status`, `owner_team`, `last_verified` and `review_every`.",
+        "2. Runbooks go in `knowledge/runbooks/` with the sections *When to use*, *Steps*, *Checks* and *Rollback*, so they compile into agent skills.",
+        "3. Run `docsworth lint .` and open a pull request; the owning team in CODEOWNERS reviews it.",
+        "",
+        "## Keeping pages citable",
+        "- A page is citable while `status: canonical` and today is on or before `last_verified + review_every`.",
+        "- To re-verify, ask Claude Code to `verify` the page (owners only), or edit `last_verified` in a PR.",
+        "- `docsworth stale .` lists overdue and unowned pages.",
+        "",
+    ].join("\n")));
+    if (opts.ci) {
+        const template = join(dirname(fileURLToPath(import.meta.url)), "../../templates/github/knowledge.yml");
+        write(".github/workflows/knowledge.yml", readFileSync(template, "utf8").replaceAll("__DOCSWORTH_PACKAGE__", pkg));
+    }
+    return res;
+}