@docsworth/cli 0.0.0-stage → 0.3.0

package/dist/core/config.d.ts

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { UserError } from "./errors.js";
+export declare const CONFIG_PATH = ".knowledge/config.yaml";
+/** The MCP tools a policy can name (kept here so config doesn't import the server). */
+export declare const POLICY_TOOLS: readonly ["search", "read", "list", "stale", "propose_edit", "verify", "draft_page"];
+declare const MirrorSourceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"confluence">;
+    name: z.ZodDefault<z.ZodString>;
+    base_url: z.ZodString;
+    spaces: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        acl: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"notion">;
+    name: z.ZodDefault<z.ZodString>;
+    root_page_ids: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    acl: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>], "kind">;
+export declare const ConfigSchema: z.ZodObject<{
+    format: z.ZodDefault<z.ZodLiteral<1>>;
+    knowledge_root: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    static_dirs: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>>;
+    site_url: z.ZodOptional<z.ZodString>;
+    github: z.ZodObject<{
+        org: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+        repo: z.ZodOptional<z.ZodString>;
+        default_branch: z.ZodOptional<z.ZodString>;
+        api_url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    sla: z.ZodDefault<z.ZodObject<{
+        due_soon_days: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    usage_log: z.ZodDefault<z.ZodBoolean>;
+    audit_log: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        dir: z.ZodOptional<z.ZodString>;
+        include_queries: z.ZodDefault<z.ZodBoolean>;
+        required: z.ZodDefault<z.ZodBoolean>;
+        retention_days: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    skills: z.ZodDefault<z.ZodObject<{
+        out_dir: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    frontmatter: z.ZodDefault<z.ZodObject<{
+        extra_fields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    mirror: z.ZodDefault<z.ZodObject<{
+        out_dir: z.ZodDefault<z.ZodString>;
+        sources: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"confluence">;
+            name: z.ZodDefault<z.ZodString>;
+            base_url: z.ZodString;
+            spaces: z.ZodArray<z.ZodObject<{
+                key: z.ZodString;
+                acl: z.ZodDefault<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"notion">;
+            name: z.ZodDefault<z.ZodString>;
+            root_page_ids: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            acl: z.ZodDefault<z.ZodString>;
+        }, z.core.$strip>], "kind">>>;
+        serve: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    policy: z.ZodDefault<z.ZodObject<{
+        admins: z.ZodOptional<z.ZodString>;
+        tools: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+            draft_page: "draft_page";
+            list: "list";
+            propose_edit: "propose_edit";
+            read: "read";
+            search: "search";
+            stale: "stale";
+            verify: "verify";
+        }> & z.core.$partial, z.ZodObject<{
+            teams: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>>>;
+        writes: z.ZodDefault<z.ZodEnum<{
+            disabled: "disabled";
+            enabled: "enabled";
+        }>>;
+        require_human_approval: z.ZodDefault<z.ZodBoolean>;
+        include_stale: z.ZodDefault<z.ZodEnum<{
+            allowed: "allowed";
+            denied: "denied";
+        }>>;
+        identity_cache_seconds: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    digest: z.ZodDefault<z.ZodObject<{
+        slack_webhook_env: z.ZodDefault<z.ZodString>;
+        team_webhooks: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>;
+    audit_http: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>;
+export type Config = z.infer<typeof ConfigSchema>;
+export type MirrorSourceConfig = z.infer<typeof MirrorSourceSchema>;
+export declare class ConfigError extends UserError {
+}
+export declare function loadConfig(repoRoot: string): Config;
+export {};

package/dist/core/config.js

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { z } from "zod";
+import { UserError } from "./errors.js";
+import { insecureUrl } from "./url.js";
+export const CONFIG_PATH = ".knowledge/config.yaml";
+/** The MCP tools a policy can name (kept here so config doesn't import the server). */
+export const POLICY_TOOLS = ["search", "read", "list", "stale", "propose_edit", "verify", "draft_page"];
+const TeamSlug = z.string().regex(/^[a-z0-9][a-z0-9_-]*$/, "a lowercase team slug like `platform`");
+const MirrorSourceSchema = z.discriminatedUnion("kind", [
+    z.object({
+        kind: z.literal("confluence"),
+        name: z.string().default("confluence"),
+        base_url: z.string().url().superRefine((u, ctx) => {
+            const why = insecureUrl(u);
+            if (why)
+                ctx.addIssue({ code: "custom", message: `base_url ${why}` });
+        }),
+        spaces: z.array(z.object({ key: z.string().min(1), acl: z.string().default("internal") })).min(1),
+    }),
+    z.object({
+        kind: z.literal("notion"),
+        name: z.string().default("notion"),
+        root_page_ids: z.array(z.string()).default([]),
+        acl: z.string().default("internal"),
+    }),
+]);
+/**
+ * A directory in the repo, in one spelling: `knowledge/`, `./knowledge` and `knowledge//` are
+ * `knowledge`, since paths join to it and a trailing slash would double. It's named relative to
+ * the repo, which redaction and CODEOWNERS paths are built on: the repo itself (`.`, or `/`,
+ * which a join makes the same), a directory above it, an absolute path and a Windows separator
+ * are refused. So are git's own directory (a ref named `x.md` is a file adopt would write) and
+ * Docsworth's state.
+ */
+function repoDir(what) {
+    return z
+        .string()
+        .transform((s) => posix.normalize(s).replace(/(.)\/+$/, "$1"))
+        .refine((s) => s !== "." && s !== ".." && !s.startsWith("../") && !s.startsWith("/") && !/^[A-Za-z]:/.test(s) && !s.includes("\\"), `${what} is a directory in the repo, named relative to it: not the repo itself (.), not above it (..), not absolute; such as \`knowledge\``)
+        .refine((s) => !s.split("/").some((seg) => seg.toLowerCase() === ".git") && !/^\.knowledge(\/|$)/i.test(s), `${what} can't be in git's own directory (.git) or Docsworth's (.knowledge)`);
+}
+export const ConfigSchema = z.object({
+    format: z.literal(1).default(1),
+    knowledge_root: repoDir("the knowledge root").default("knowledge"),
+    /**
+     * Directories a docs site serves at its root (Docusaurus's `static/`): lint reads a
+     * root-relative attachment link (`/img/x.png`) from them too.
+     */
+    static_dirs: z.array(repoDir("a static directory")).default([]),
+    /**
+     * Where the team's docs site serves the pages, as `https://docs.example.com/docs/`.
+     * Redaction reads a link to a URL under it as the route it names.
+     */
+    site_url: z
+        .string()
+        .url()
+        .superRefine((u, ctx) => {
+        // `.url()` has reported a value that isn't one; this runs all the same.
+        const at = URL.canParse(u) ? new URL(u) : undefined;
+        if (!at)
+            return;
+        if (at.protocol !== "https:" && at.protocol !== "http:")
+            ctx.addIssue({ code: "custom", message: "site_url must be an http or https URL" });
+        else if (at.username || at.password || at.search || at.hash)
+            ctx.addIssue({ code: "custom", message: "site_url is an origin and a path, with no credentials, query or fragment" });
+    })
+        .optional(),
+    github: z.object({
+        /** Team owners resolve to @<org>/<team>. Required even for local-only repos. */
+        org: z.string().min(1).transform((s) => s.toLowerCase()),
+        /** owner/name. When set, GitHub is the ACL authority and a token is required. */
+        repo: z
+            .string()
+            .regex(/^[\w.-]+\/[\w.-]+$/, "owner/name")
+            .optional(),
+        default_branch: z.string().optional(),
+        /** REST API base for GitHub Enterprise Server, e.g. https://ghe.example.com/api/v3. */
+        api_url: z
+            .string()
+            .url()
+            .superRefine((u, ctx) => {
+            const why = insecureUrl(u);
+            if (why)
+                ctx.addIssue({ code: "custom", message: `github.api_url ${why}` });
+        })
+            .optional(),
+    }),
+    sla: z.object({ due_soon_days: z.number().int().min(0).default(14) }).default({ due_soon_days: 14 }),
+    /** Append page-id-only read events to .knowledge/usage.jsonl (feeds the digest). */
+    usage_log: z.boolean().default(false),
+    /** The attributed audit log (src/core/audit-log.ts). Off unless enabled. */
+    audit_log: z
+        .object({
+        enabled: z.boolean().default(false),
+        /** Default: a state directory outside the checkout. Inside it, git must ignore it. */
+        dir: z.string().min(1).optional(),
+        /** Record search query text. Off: queries can carry sensitive text. */
+        include_queries: z.boolean().default(false),
+        /** Fail a tool call (closed) when its event can't be written. */
+        required: z.boolean().default(false),
+        retention_days: z.number().int().min(1).default(365),
+    })
+        .strict() // `requred: true` must fail, not quietly make the log optional
+        // "Required" with nothing enabled would quietly mean no audit log at all.
+        .refine((a) => !a.required || a.enabled, { message: "audit_log.required needs audit_log.enabled: true (otherwise nothing is audited)" })
+        .default({ enabled: false, include_queries: false, required: false, retention_days: 365 }),
+    skills: z.object({ out_dir: z.string().default("skills") }).default({ out_dir: "skills" }),
+    /** Keys a site generator keeps in frontmatter (Docusaurus's `sidebar_position`, say): lint doesn't warn on them. */
+    frontmatter: z
+        .object({ extra_fields: z.array(z.string().min(1)).default([]) })
+        // `extra_field:` must fail, not quietly leave every key warned on.
+        .strict()
+        .default({ extra_fields: [] }),
+    mirror: z
+        .object({
+        out_dir: z.string().default(".knowledge/mirror"),
+        sources: z.array(MirrorSourceSchema).default([]),
+        /** Serve mirrored pages to agents as non-citable context (v0.2 L2). Off by default. */
+        serve: z.boolean().default(false),
+    })
+        .default({ out_dir: ".knowledge/mirror", sources: [], serve: false }),
+    /** Org policy and roles (src/core/policy.ts). Every default keeps v0.1 behaviour. */
+    policy: z
+        .object({
+        /** The team that must own .knowledge/config.yaml and CODEOWNERS in CODEOWNERS (lint). */
+        admins: TeamSlug.optional(),
+        /** Per-tool allowlists. An empty list disables the tool for everyone. */
+        tools: z.partialRecord(z.enum(POLICY_TOOLS), z.object({ teams: z.array(TeamSlug) }).strict()).default({}),
+        /** `disabled`: propose_edit and verify are not offered at all. */
+        writes: z.enum(["enabled", "disabled"]).default("enabled"),
+        /** Mark write tools so Claude Code asks a human on every call (defence in depth). */
+        require_human_approval: z.boolean().default(false),
+        /** `denied`: search never returns gated pages inline, even with include_stale. */
+        include_stale: z.enum(["allowed", "denied"]).default("allowed"),
+        /** How long team membership is cached for reads: the deprovisioning window. */
+        identity_cache_seconds: z.number().int().min(30).max(3600).default(300),
+    })
+        // A typo here must be an error, not a silently ignored key: `write: disabled`
+        // would otherwise leave writes on.
+        .strict()
+        .default({ tools: {}, writes: "enabled", require_human_approval: false, include_stale: "allowed", identity_cache_seconds: 300 }),
+    digest: z
+        .object({
+        /** Env var holding the shared Slack incoming-webhook URL. */
+        slack_webhook_env: z.string().default("SLACK_WEBHOOK_URL"),
+        /**
+         * Per-team webhook env vars. Each MUST point at that team's own private channel:
+         * restricted page titles are posted there by name. Shared channels go through
+         * slack_webhook_env, where restricted pages are only counted.
+         */
+        team_webhooks: z.record(z.string(), z.string()).default({}),
+    })
+        .default({ slack_webhook_env: "SLACK_WEBHOOK_URL", team_webhooks: {} }),
+    /** Pro: the audit collector. Docsworth pro parses it; core only reserves the key. */
+    audit_http: z.unknown().optional(),
+})
+    // Every top-level key is known, so a misspelled block (`polciy:`, `audit_lgo:`) is an
+    // error rather than a silently dropped one that would leave writes on or auditing off.
+    .strict();
+export class ConfigError extends UserError {
+}
+export function loadConfig(repoRoot) {
+    const abs = join(repoRoot, CONFIG_PATH);
+    if (!existsSync(abs))
+        throw new ConfigError(`no ${CONFIG_PATH} in ${repoRoot} (run \`docsworth init\`)`);
+    const raw = parseYaml(readFileSync(abs, "utf8"), { schema: "core" });
+    const result = ConfigSchema.safeParse(raw ?? {});
+    if (!result.success) {
+        const detail = result.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ");
+        throw new ConfigError(`invalid ${CONFIG_PATH}: ${detail}`);
+    }
+    return result.data;
+}

package/dist/core/coverage.d.ts

@@ -0,0 +1,25 @@
+import type { Repo } from "./repo.js";
+export interface CoverageRow {
+    team: string;
+    pages: number;
+    owned: number;
+    owned_pct: number;
+    /** Pages subject to review: everything except deprecated pages. */
+    reviewable: number;
+    within_sla: number;
+    within_sla_pct: number;
+}
+export interface Coverage {
+    as_of: string;
+    total: CoverageRow;
+    teams: CoverageRow[];
+}
+/** Team bucket for pages whose frontmatter is too broken to name an owner. */
+export declare const UNASSIGNED = "(unassigned)";
+/**
+ * Ownership coverage (§4.3): % of pages team-owned and % verified within SLA, per team.
+ * Invalid pages count as neither owned nor verified, so a broken page lowers coverage
+ * instead of disappearing from it.
+ */
+export declare function computeCoverage(repo: Repo, now: Date): Coverage;
+export declare function formatCoverage(c: Coverage): string;

package/dist/core/coverage.js

@@ -0,0 +1,41 @@
+import { pageStatus } from "./gate.js";
+import { withinSla } from "./sla.js";
+/** Team bucket for pages whose frontmatter is too broken to name an owner. */
+export const UNASSIGNED = "(unassigned)";
+const pct = (n, d) => (d === 0 ? 100 : Math.round((n / d) * 1000) / 10);
+function row(team, items) {
+    const owned = items.filter((i) => i.owned).length;
+    const reviewable = items.filter((i) => i.reviewable).length;
+    const within = items.filter((i) => i.reviewable && i.within).length;
+    return {
+        team,
+        pages: items.length,
+        owned,
+        owned_pct: pct(owned, items.length),
+        reviewable,
+        within_sla: within,
+        within_sla_pct: pct(within, reviewable),
+    };
+}
+/**
+ * Ownership coverage (§4.3): % of pages team-owned and % verified within SLA, per team.
+ * Invalid pages count as neither owned nor verified, so a broken page lowers coverage
+ * instead of disappearing from it.
+ */
+export function computeCoverage(repo, now) {
+    const byTeam = new Map();
+    const add = (team, item) => byTeam.set(team, [...(byTeam.get(team) ?? []), item]);
+    for (const page of repo.pages) {
+        const s = pageStatus(page, repo, now);
+        add(page.owner_team, { owned: s.owned, reviewable: page.status !== "deprecated", within: withinSla(s.sla.state) });
+    }
+    for (const _ of repo.invalid)
+        add(UNASSIGNED, { owned: false, reviewable: true, within: false });
+    const teams = [...byTeam.entries()].map(([team, items]) => row(team, items)).sort((a, b) => a.team.localeCompare(b.team));
+    return { as_of: now.toISOString().slice(0, 10), total: row("total", [...byTeam.values()].flat()), teams };
+}
+export function formatCoverage(c) {
+    const header = "team            pages  owned          within SLA";
+    const fmt = (r) => `${r.team.padEnd(15)} ${String(r.pages).padStart(5)}  ${`${r.owned}/${r.pages}`.padStart(6)} ${`${r.owned_pct}%`.padStart(6)}  ${`${r.within_sla}/${r.reviewable}`.padStart(6)} ${`${r.within_sla_pct}%`.padStart(6)}`;
+    return [`Ownership coverage as of ${c.as_of}`, header, ...c.teams.map(fmt), fmt(c.total)].join("\n");
+}

package/dist/core/duration.d.ts

@@ -0,0 +1,20 @@
+export type DurationUnit = "d" | "w" | "m" | "y";
+export interface Duration {
+    n: number;
+    unit: DurationUnit;
+}
+export declare const DURATION_RE: RegExp;
+export declare function parseDuration(s: unknown): Duration | null;
+/** Parse `YYYY-MM-DD` to UTC midnight; rejects impossible dates like 2026-02-30. */
+export declare function parseDate(s: unknown): Date | null;
+export declare function formatDate(d: Date): string;
+/** The UTC calendar day containing `now`. */
+export declare function utcToday(now: Date): Date;
+/**
+ * Add a duration. Days and weeks are fixed; months and years are calendar units
+ * clamped to the end of the target month (Jan 31 + 1m = Feb 28/29).
+ */
+export declare function addDuration(date: Date, dur: Duration): Date;
+/** Go back by a duration, clamping the same way (Mar 31 − 1m = Feb 28/29). */
+export declare function subtractDuration(date: Date, dur: Duration): Date;
+export declare function daysBetween(from: Date, to: Date): number;

package/dist/core/duration.js

@@ -0,0 +1,60 @@
+// Date-only calendar arithmetic for review SLAs.
+//
+// All dates are UTC midnight `Date`s produced by `parseDate`, so a page verified on
+// 2026-10-15 is due on the same calendar day for every reader regardless of timezone.
+export const DURATION_RE = /^([1-9]\d{0,3})([dwmy])$/;
+const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const DAY_MS = 86_400_000;
+export function parseDuration(s) {
+    if (typeof s !== "string")
+        return null;
+    const m = DURATION_RE.exec(s.trim());
+    return m ? { n: Number(m[1]), unit: m[2] } : null;
+}
+/** Parse `YYYY-MM-DD` to UTC midnight; rejects impossible dates like 2026-02-30. */
+export function parseDate(s) {
+    if (typeof s !== "string")
+        return null;
+    const m = DATE_RE.exec(s.trim());
+    if (!m)
+        return null;
+    const [y, mo, d] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const date = new Date(Date.UTC(y, mo - 1, d));
+    const roundTrips = date.getUTCFullYear() === y && date.getUTCMonth() === mo - 1 && date.getUTCDate() === d;
+    return roundTrips ? date : null;
+}
+export function formatDate(d) {
+    return d.toISOString().slice(0, 10);
+}
+/** The UTC calendar day containing `now`. */
+export function utcToday(now) {
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));
+}
+/**
+ * Add a duration. Days and weeks are fixed; months and years are calendar units
+ * clamped to the end of the target month (Jan 31 + 1m = Feb 28/29).
+ */
+export function addDuration(date, dur) {
+    if (dur.unit === "d" || dur.unit === "w") {
+        return new Date(date.getTime() + dur.n * (dur.unit === "w" ? 7 : 1) * DAY_MS);
+    }
+    const months = dur.unit === "y" ? dur.n * 12 : dur.n;
+    const y = date.getUTCFullYear();
+    const targetMonth = date.getUTCMonth() + months;
+    const lastDayOfTarget = new Date(Date.UTC(y, targetMonth + 1, 0)).getUTCDate();
+    return new Date(Date.UTC(y, targetMonth, Math.min(date.getUTCDate(), lastDayOfTarget)));
+}
+/** Go back by a duration, clamping the same way (Mar 31 − 1m = Feb 28/29). */
+export function subtractDuration(date, dur) {
+    if (dur.unit === "d" || dur.unit === "w") {
+        return new Date(date.getTime() - dur.n * (dur.unit === "w" ? 7 : 1) * DAY_MS);
+    }
+    const months = dur.unit === "y" ? dur.n * 12 : dur.n;
+    const y = date.getUTCFullYear();
+    const targetMonth = date.getUTCMonth() - months;
+    const lastDayOfTarget = new Date(Date.UTC(y, targetMonth + 1, 0)).getUTCDate();
+    return new Date(Date.UTC(y, targetMonth, Math.min(date.getUTCDate(), lastDayOfTarget)));
+}
+export function daysBetween(from, to) {
+    return Math.round((to.getTime() - from.getTime()) / DAY_MS);
+}

package/dist/core/edits.d.ts

@@ -0,0 +1,13 @@
+export interface Edit {
+    /** Start offset in the original text. */
+    start: number;
+    /** End offset (exclusive) in the original text. */
+    end: number;
+    insert: string;
+}
+/**
+ * `text` with each edit applied at its original offsets, rebuilt in one pass after sorting the
+ * edits (O(E log E) plus the text, not once per edit). Edits must not overlap; ones at the same
+ * offset apply in the order given.
+ */
+export declare function applyEdits(text: string, edits: readonly Edit[]): string;

package/dist/core/edits.js

@@ -0,0 +1,20 @@
+// Replacing ranges of a text by their original offsets: every rewrite `adopt` and `verify`
+// make goes through here, so one edit never shifts another's place.
+/**
+ * `text` with each edit applied at its original offsets, rebuilt in one pass after sorting the
+ * edits (O(E log E) plus the text, not once per edit). Edits must not overlap; ones at the same
+ * offset apply in the order given.
+ */
+export function applyEdits(text, edits) {
+    const sorted = edits.map((e, i) => ({ e, i })).sort((a, b) => a.e.start - b.e.start || a.e.end - b.e.end || a.i - b.i);
+    const parts = [];
+    let at = 0;
+    for (const { e } of sorted) {
+        if (e.start < at)
+            throw new Error(`edits overlap at offset ${e.start}`);
+        parts.push(text.slice(at, e.start), e.insert);
+        at = e.end;
+    }
+    parts.push(text.slice(at));
+    return parts.join("");
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * An error the person running the CLI can act on: it prints as its message alone and exits
+ * 2, rather than as a stack. It's recognized by a brand, not by its class, so the CLI tells
+ * Docsworth pro's errors apart without importing pro: pro is another package, and its errors
+ * may extend another copy of this class.
+ */
+export declare class UserError extends Error {
+    readonly userError: true;
+}
+/** Whether `err` is a UserError, from this copy of core or any other. */
+export declare function isUserError(err: unknown): err is Error;

package/dist/core/errors.js

@@ -0,0 +1,13 @@
+/**
+ * An error the person running the CLI can act on: it prints as its message alone and exits
+ * 2, rather than as a stack. It's recognized by a brand, not by its class, so the CLI tells
+ * Docsworth pro's errors apart without importing pro: pro is another package, and its errors
+ * may extend another copy of this class.
+ */
+export class UserError extends Error {
+    userError = true;
+}
+/** Whether `err` is a UserError, from this copy of core or any other. */
+export function isUserError(err) {
+    return err instanceof Error && err.userError === true;
+}

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,29 @@
+export interface SplitDoc {
+    /** Parsed frontmatter mapping, or null when absent/unparseable (see `error`). */
+    data: Record<string, unknown> | null;
+    body: string;
+    error?: string;
+}
+export declare const FRONTMATTER_MAX: number;
+/**
+ * Split `---` frontmatter from a markdown file and parse it as YAML.
+ *
+ * The YAML "core" schema is used on purpose: under YAML 1.1 rules `2026-10-15` would
+ * become a Date and `review_every: 90d` could be coerced oddly. Here every scalar that
+ * isn't a plain number/bool/null stays a string, so dates round-trip exactly.
+ */
+export declare function splitFrontmatter(text: string): SplitDoc;
+export interface FrontmatterSpan {
+    /** Where the YAML starts: just after the opening `---` line. */
+    start: number;
+    /** Where it ends, before the closing `---` line's own line break. */
+    end: number;
+    /** Where the body starts, after the closing `---` line. */
+    bodyStart: number;
+    /** The opening line's line ending. */
+    eol: "\n" | "\r\n";
+}
+/** Where a page's frontmatter sits in `text`, by offset; null without a terminated block. */
+export declare function frontmatterSpan(text: string): FrontmatterSpan | null;
+/** Serialize frontmatter + body back to a markdown file (used by writes and promote). */
+export declare function joinFrontmatter(yaml: string, body: string): string;

package/dist/core/frontmatter.js

@@ -0,0 +1,49 @@
+import { parse as parseYaml } from "yaml";
+const OPEN = /^---\r?\n/;
+export const FRONTMATTER_MAX = 16 * 1024;
+const CLOSE = /\r?\n---[ \t]*(\r?\n|$)/;
+/**
+ * Split `---` frontmatter from a markdown file and parse it as YAML.
+ *
+ * The YAML "core" schema is used on purpose: under YAML 1.1 rules `2026-10-15` would
+ * become a Date and `review_every: 90d` could be coerced oddly. Here every scalar that
+ * isn't a plain number/bool/null stays a string, so dates round-trip exactly.
+ */
+export function splitFrontmatter(text) {
+    if (!OPEN.test(text))
+        return { data: null, body: text, error: "missing frontmatter block" };
+    const span = frontmatterSpan(text);
+    if (!span)
+        return { data: null, body: text, error: "unterminated frontmatter block" };
+    const yamlSrc = text.slice(span.start, span.end);
+    const body = text.slice(span.bodyStart);
+    // A page's frontmatter is a few hundred bytes; YAML parsing slows past linear on
+    // hostile input (64 KB of `}&`: 650 ms, paid on every reload).
+    if (Buffer.byteLength(yamlSrc, "utf8") > FRONTMATTER_MAX)
+        return { data: null, body, error: `frontmatter is over ${FRONTMATTER_MAX / 1024} KB` };
+    try {
+        const data = parseYaml(yamlSrc, { schema: "core" });
+        if (data === null || typeof data !== "object" || Array.isArray(data)) {
+            return { data: null, body, error: "frontmatter is not a mapping" };
+        }
+        return { data: data, body };
+    }
+    catch (err) {
+        return { data: null, body, error: `invalid YAML: ${err.message.split("\n")[0]}` };
+    }
+}
+/** Where a page's frontmatter sits in `text`, by offset; null without a terminated block. */
+export function frontmatterSpan(text) {
+    const open = OPEN.exec(text);
+    if (!open)
+        return null;
+    const start = open[0].length;
+    const close = CLOSE.exec(text.slice(start));
+    if (!close)
+        return null;
+    return { start, end: start + close.index, bodyStart: start + close.index + close[0].length, eol: open[0].length === 5 ? "\r\n" : "\n" };
+}
+/** Serialize frontmatter + body back to a markdown file (used by writes and promote). */
+export function joinFrontmatter(yaml, body) {
+    return `---\n${yaml.trimEnd()}\n---\n${body.startsWith("\n") ? body : `\n${body}`}`;
+}

package/dist/core/gate.d.ts

@@ -0,0 +1,17 @@
+import type { Page, Repo } from "./repo.js";
+import { type Sla } from "./sla.js";
+export interface PageStatus {
+    sla: Sla;
+    /** CODEOWNERS resolves to exactly one team of the org, and it equals owner_team. */
+    owned: boolean;
+    ownership_problem?: string;
+    /** May an agent cite this page? canonical + within SLA + owned. Not configurable. */
+    citable: boolean;
+    /** Why it is not citable, phrased for an agent's answer ("excluded: …"). */
+    gate_reason?: string;
+}
+/**
+ * The citation gate. Hard-coded on purpose (spec R11): no config may widen it, because
+ * a gate a team can switch off is the "rebuild Confluence with vectors" failure mode.
+ */
+export declare function pageStatus(page: Page, repo: Repo, now: Date): PageStatus;

package/dist/core/gate.js

@@ -0,0 +1,25 @@
+import { describeOwnershipProblem, resolveTeamOwner } from "./codeowners.js";
+import { computeSla, withinSla } from "./sla.js";
+/**
+ * The citation gate. Hard-coded on purpose (spec R11): no config may widen it, because
+ * a gate a team can switch off is the "rebuild Confluence with vectors" failure mode.
+ */
+export function pageStatus(page, repo, now) {
+    const sla = computeSla(page.last_verified, page.review_every, now, repo.config.sla.due_soon_days);
+    const own = resolveTeamOwner(repo.codeowners, page.path, repo.config.github.org);
+    const owned = own.ok && own.team === page.owner_team.toLowerCase();
+    const ownership_problem = own.ok
+        ? owned
+            ? undefined
+            : `owner_team is \`${page.owner_team}\` but CODEOWNERS assigns @${repo.config.github.org}/${own.team}`
+        : describeOwnershipProblem(own.problem, repo.config.github.org);
+    let gate_reason;
+    if (page.status !== "canonical")
+        gate_reason = `status is ${page.status}`;
+    else if (!withinSla(sla.state))
+        gate_reason =
+            sla.state === "overdue" ? `past review date (due ${sla.due}), owned by ${page.owner_team}` : "never verified";
+    else if (!owned)
+        gate_reason = `ownership unresolved: ${ownership_problem}`;
+    return { sla, owned, ownership_problem, citable: gate_reason === undefined, gate_reason };
+}

package/dist/core/gfm.d.ts

@@ -0,0 +1,13 @@
+import { Node } from "commonmark";
+/**
+ * commonmark.js's tree for `markdown`, with GFM tables as tables (see above). The placeholder
+ * is never a link or an image, whatever a page writes around it: a definition for it, a
+ * `(target)` or `[label]` right after the link redaction replaced, or a link around it. A
+ * link or image labelled "restricted page" becomes the placeholder's text, and one whose
+ * label holds the placeholder becomes its label's text.
+ */
+export declare function parseGfm(markdown: string): Node;
+/** The text and code inside `node`: a link's or image's label, as the reader sees it. */
+export declare function textIn(node: Node): string;
+/** A table cell (`th` or `td`) in a tree from `parseGfm`; its children are the cell's content. */
+export declare function isTableCell(node: Node): boolean;