@docsworth/cli 0.0.0-stage → 0.3.0

package/dist/core/service.d.ts

@@ -0,0 +1,473 @@
+import { type Identity } from "./acl.js";
+import { type MirrorPage } from "./mirror-view.js";
+import { type NewPageType } from "./new-page.js";
+import { type Policy } from "./policy.js";
+import type { GitHubClient } from "./github.js";
+import { type Page, type Repo } from "./repo.js";
+import { type PageType } from "./schema.js";
+import { SearchIndex } from "./search.js";
+import { type StaleEntry } from "./stale.js";
+import { type Edit } from "./writes.js";
+export type ToolErrorCode = "not_found" | "forbidden" | "invalid" | "unavailable";
+export declare class ToolError extends Error {
+    readonly code: ToolErrorCode;
+    constructor(code: ToolErrorCode, message: string);
+}
+/** What the service needs from identity resolution (IdentityProvider, or a test fake). */
+export interface IdentitySource {
+    get(): Promise<Identity>;
+    fresh(): Promise<Identity>;
+    readonly github: GitHubClient | null;
+}
+export interface PageSummary {
+    id: string;
+    title: string;
+    path: string;
+    type: PageType;
+    status: Page["status"];
+    owner_team: string;
+    last_verified: string;
+    due: string | null;
+    sla_state: string;
+    citable: boolean;
+}
+export interface SearchResult extends PageSummary {
+    snippet: string;
+    score: number;
+    /** Present only with include_stale: why this page is not citable. */
+    gate?: string;
+}
+/** A mirrored wiki page that matched: context for the agent, never a citation. */
+export interface MirroredHit {
+    id: string;
+    title: string;
+    source: string;
+    source_url: string;
+    owner_team: string | null;
+    last_edited: string;
+    citable: false;
+    snippet: string;
+}
+export interface Excluded {
+    id: string;
+    title: string;
+    owner_team: string;
+    reason: string;
+}
+/**
+ * The six knowledge tools as plain functions. The MCP server is a thin wrapper, and the
+ * ACL matrix test exercises this class directly, so there is one code path to audit.
+ *
+ * Invariant: every page a method touches comes from `visiblePages(repo, identity)`.
+ * Unknown ids and ids the caller cannot see raise the same not_found error.
+ */
+/** How long after starting a watcher to reload once anyway. A write 500 ms after a restart
+ *  was always reported (20 of 20); this leaves room on a loaded machine. */
+export declare const WATCH_SETTLE_MS = 2000;
+/** A draft_page body's limit, and how many fresh names it tries before giving up. */
+export declare const DRAFT_MAX_CHARS: number;
+export declare const DRAFT_NAME_ATTEMPTS = 3;
+/** At most this many mirrored pages per search: context, not a second result list. */
+export declare const MIRROR_LIMIT = 3;
+type MirrorView = {
+    pages: MirrorPage[];
+    origin: MirrorPage[];
+    hidden: MirrorPage[];
+    index: SearchIndex;
+};
+type Snapshot = {
+    commit: string | null;
+    dirty: boolean | null;
+    content_sha256: string;
+};
+/**
+ * One load of the repo: the pages, their search index and the served mirror. Never changed
+ * after it is built, except two caches filled on first use: the mirror's views (one per
+ * audience) and the snapshot. A reload builds a new one, so a call that took this one keeps
+ * a consistent view.
+ */
+interface Loaded {
+    readonly repo: Repo;
+    readonly index: SearchIndex;
+    readonly mirror: MirrorPage[];
+    /** Keyed by audience (repo access and teams), so services with any identity can share it. */
+    readonly mirrorViews: Map<string, MirrorView>;
+    /** mtimes of the non-page inputs (config, CODEOWNERS) it was built from. */
+    readonly inputs: string;
+    snap: Snapshot | null;
+}
+/**
+ * Loads the repo and keeps it until something changes, for one service or, in `docsworth
+ * serve`, for every session's service: one copy of the pages and their index however many
+ * tabs are open (a 3,000-page repo took about 50 MB per copy). It owns the one file watcher.
+ * What belongs to a session (its taint, its cached default branch) stays on the service.
+ */
+export declare class RepoLoader {
+    private readonly root;
+    private loaded;
+    private dirty;
+    /** watch() was asked for, and close() hasn't stopped it. */
+    private watching;
+    private watcher;
+    private settle;
+    /** The directory being watched, or to be once it exists (tests read it). */
+    watchedDir: string | null;
+    /** How many times the repo was loaded (tests). */
+    loads: number;
+    /** Called after each load: serve moves its idle sessions onto it, so no old load is kept. */
+    onLoad: (() => void) | null;
+    constructor(root: string);
+    /** The current load: the same object until a change is seen, then a new one, built once. */
+    current(): Loaded;
+    /** The newest load, without looking for changes. */
+    latest(): Loaded | null;
+    /** Has a change been seen that the next call will load (tests). */
+    get pending(): boolean;
+    private load;
+    /** Config and CODEOWNERS live outside the watched knowledge root; stat them per call. */
+    private inputsStamp;
+    /** Load again on the next call. */
+    invalidate(): void;
+    /** Mark the load stale on any change under the knowledge root. */
+    watch(): void;
+    /** Watch `repo`'s knowledge root, in place of whatever was watched before. */
+    private follow;
+    close(): void;
+    private stop;
+}
+export declare class KnowledgeService {
+    private readonly root;
+    private readonly identity;
+    private readonly now;
+    private readonly loader;
+    /** A loader this service made is its own to close; a shared one belongs to its owner. */
+    private readonly ownsLoader;
+    private loaded;
+    private repo;
+    private index;
+    private defaultBranch;
+    /** Mirrored pages, when mirror.serve is on; one search index per audience (views). */
+    private mirror;
+    private mirrorViews;
+    /** Team ACLs whose content this session has seen (write-path taint check). */
+    private readonly tainted;
+    /** The random end of a drafted page's id and file name (replaced in tests). */
+    private draftSuffix;
+    /** `loader`: a load shared with other services (`docsworth serve`'s sessions); else its own. */
+    constructor(root: string, identity: IdentitySource, now?: () => Date, loader?: RepoLoader);
+    /** Load the repo again now. */
+    reload(): void;
+    /**
+     * Point at the loader's newest load, letting go of an older one. Only while no call of
+     * this service is running: `docsworth serve` calls it for a session with no request in
+     * flight, so an idle tab doesn't keep a whole old copy of the repo alive.
+     */
+    release(): void;
+    /** Take a new load, and drop what this service cached from the last one. */
+    private adopt;
+    /** The watched directory and a pending reload live on the loader (tests read them here). */
+    private get watchedDir();
+    private get dirty();
+    /**
+     * The mirrored pages `who` may see, each with links to the ones they can't see
+     * redacted (and to repo pages they can't see: a wiki page can link to one by its URL),
+     * and a search index over exactly that view: ranking, snippets and counts never draw on
+     * a page outside it. One per audience (the caller's teams), rebuilt on reload.
+     */
+    private mirrorView;
+    /** Reload on the next call. */
+    invalidate(): void;
+    /** Mark the index dirty on any change under the knowledge root. */
+    watch(): void;
+    /** Stops this service's own watcher; a shared loader's is its owner's to stop. */
+    close(): void;
+    private current;
+    /**
+     * The knowledge actually being served: the checkout's HEAD and whether the served files
+     * differ from it, plus a hash of the loaded config, ownership and pages. Refreshed after
+     * every reload, so an audit event names the snapshot its answer came from.
+     */
+    snapshot(): Snapshot;
+    /** Every page id, team and applies_to tag the repo uses: what an audited argument may record. */
+    knownValues(): {
+        ids: Set<string>;
+        teams: Set<string>;
+        tags: Set<string>;
+    };
+    /** Whether mirrored pages are served (mirror.serve). */
+    mirrorServed(): boolean;
+    /** The org policy in force now (config is re-read when it changes). */
+    policy(): Policy;
+    get org(): string;
+    /** Policy gate, checked on every call, before any page is resolved. */
+    private permit;
+    private summary;
+    private resolve;
+    /** Any restricted page represented in a response (content, snippet or just its title)
+     *  taints the session for the write-path check. */
+    private taint;
+    private noteRead;
+    search(args: {
+        query: string;
+        type?: PageType;
+        owner_team?: string;
+        applies_to?: string;
+        include_stale?: boolean;
+        limit?: number;
+        /** "text": snippets cut from the page as a reader sees it (the web app); else markdown. */
+        snippets?: "markdown" | "text";
+    }): Promise<{
+        results: SearchResult[];
+        excluded: Excluded[];
+        mirrored?: MirroredHit[];
+        note?: string;
+        snippets?: "text";
+    }>;
+    read(args: {
+        id: string;
+    }): Promise<{
+        id: string;
+        title: string;
+        path: string;
+        type: PageType;
+        status: Page["status"];
+        owner_team: string;
+        last_verified: string;
+        due: string | null;
+        sla_state: string;
+        citable: boolean;
+        review_every: string;
+        acl: string;
+        supersedes: string[];
+        applies_to: string[];
+        flags: string[];
+        gate_reason?: string | undefined;
+        content: string;
+    } | {
+        id: string;
+        title: string;
+        source: "confluence" | "notion";
+        space: string;
+        source_url: string;
+        owner_team: string | null;
+        last_edited: string;
+        acl: string;
+        citable: boolean;
+        flags: string[];
+        gate_reason: string;
+        content: string;
+    }>;
+    /** read() for `tool`: the same view; only an agent's `read` goes in the usage log. */
+    private readAs;
+    /**
+     * `readAs`, with what it read: the page, the caller and the repo, from the one look at the
+     * repo after the only await. A caller that builds more of its answer from these (ui_page's
+     * links) answers from that same look, as `read` does: a reload after it can't mix in.
+     */
+    private readWith;
+    /** A repo page's text as `who` may see it: links to pages, or mirrored pages, they can't see redacted. */
+    private pageText;
+    /** A mirrored page, as context: never citable. Hidden and unknown ids read the same. */
+    private readMirror;
+    list(args?: {
+        path?: string;
+        type?: PageType;
+    }): Promise<{
+        type: "adr" | "guide" | "policy" | "runbook" | "service";
+        pages: PageSummary[];
+        path?: undefined;
+        index?: undefined;
+        dirs?: undefined;
+    } | {
+        type?: undefined;
+        path: string;
+        index: PageSummary | null;
+        pages: PageSummary[];
+        dirs: string[];
+    }>;
+    stale(args?: {
+        owner_team?: string;
+    }): Promise<{
+        pages: StaleEntry[];
+    }>;
+    /** Who is served and whether writes would work, for the app's header and settings. */
+    uiCapabilities(opts?: {
+        pro?: string[];
+    }): Promise<{
+        mode: "github" | "local";
+        login: string | null;
+        org: string;
+        repo: string | null;
+        writes: boolean;
+        write_tools: string[];
+        teams: string[];
+        writes_off?: string | undefined;
+        pro: string[];
+    }>;
+    /**
+     * Counts over the caller's visible pages, by team, with what is due soon and what is stale.
+     * `list_limit` keeps a big repo's overview short: the first of each list, the most pressing
+     * first, with `due_soon_total` and `stale_total`. Only the pages returned are named, so only
+     * those taint the session; the counts above the lists name no page.
+     */
+    uiOverview(args?: {
+        list_limit?: number;
+    }): Promise<{
+        as_of: string;
+        totals: {
+            pages: number;
+            citable: number;
+            overdue: number;
+            due_soon: number;
+            draft: number;
+            deprecated: number;
+        };
+        teams: {
+            pages: number;
+            citable: number;
+            overdue: number;
+            due_soon: number;
+            team: string;
+        }[];
+        due_soon: PageSummary[];
+        stale: StaleEntry[];
+        due_soon_total: number;
+        stale_total: number;
+        skipped_files: number;
+    }>;
+    /**
+     * A page as `read` shows it, with `links`: the repo path and id of each visible page it
+     * links to, so the app can route those links. Taints the session with the page and those.
+     */
+    uiPage(args: {
+        id: string;
+    }): Promise<{
+        id: string;
+        title: string;
+        source: "confluence" | "notion";
+        space: string;
+        source_url: string;
+        owner_team: string | null;
+        last_edited: string;
+        acl: string;
+        citable: boolean;
+        flags: string[];
+        gate_reason: string;
+        content: string;
+        links: {};
+    } | {
+        id: string;
+        title: string;
+        path: string;
+        type: PageType;
+        status: Page["status"];
+        owner_team: string;
+        last_verified: string;
+        due: string | null;
+        sla_state: string;
+        citable: boolean;
+        review_every: string;
+        acl: string;
+        supersedes: string[];
+        applies_to: string[];
+        flags: string[];
+        gate_reason?: string | undefined;
+        content: string;
+        links: {
+            [k: string]: string;
+        };
+    }>;
+    /**
+     * Visible pages and the links between them. A link to a page the caller can't see is no
+     * edge; `has_restricted_links` says a page has one, exactly as its `read` text shows a
+     * placeholder for it, so the graph reveals nothing `read` doesn't.
+     *
+     * `max_nodes` keeps a big repo drawable: past it, the most-linked pages (links between
+     * visible pages only; ties by id) and the links among them. `total` says how many it
+     * chose from, and `teams` how many visible pages each team has, a count that names no
+     * page. Only the returned pages are named, so only those taint the session.
+     */
+    uiGraph(args?: {
+        owner_team?: string;
+        max_nodes?: number;
+    }): Promise<{
+        nodes: {
+            id: string;
+            title: string;
+            path: string;
+            type: PageType;
+            status: Page["status"];
+            owner_team: string;
+            last_verified: string;
+            due: string | null;
+            sla_state: string;
+            citable: boolean;
+            has_restricted_links: boolean;
+        }[];
+        edges: {
+            from: string;
+            to: string;
+        }[];
+        total: number;
+        teams: {
+            team: string;
+            pages: number;
+        }[];
+    }>;
+    /** What every write needs first: the policy, a live identity, a GitHub repo. */
+    private writeIdentity;
+    private pushContext;
+    /** Common preamble for writes to a page: live identity, visibility, a GitHub repo. */
+    private writeContext;
+    /** The same for a write that creates a page: no id to resolve. */
+    private newWriteContext;
+    /** The taint check: a session that saw team-only pages writes only into pages with that audience. */
+    private refuseLeak;
+    proposeEdit(args: {
+        id: string;
+        edits?: Edit[];
+        body?: string;
+        content?: string;
+        append?: string;
+        reason: string;
+        draft?: boolean;
+        polish?: boolean;
+    }): Promise<{
+        pr_url: string;
+        pr_number: number;
+        branch: string;
+    }>;
+    /**
+     * A new page, as a draft PR. The server picks its id and file name, each ending in 12
+     * random hex digits: a caller-chosen name could be aimed at a hidden page, and "already
+     * exists" would then say it is there. The title still sets the slug, so CODEOWNERS
+     * rules that match file names (`runbooks/payments-*`) still apply.
+     */
+    draftPage(args: {
+        type: NewPageType;
+        title: string;
+        owner_team: string;
+        acl?: string;
+        dir?: string;
+        description?: string;
+        body: string;
+        source_url?: string;
+        reason: string;
+        draft?: boolean;
+    }): Promise<{
+        id: string;
+        path: string;
+        pr_url: string;
+        pr_number: number;
+        branch: string;
+    }>;
+    verify(args: {
+        id: string;
+    }): Promise<{
+        pr_url: string;
+        pr_number: number;
+        branch: string;
+        last_verified: string;
+    }>;
+}
+export {};