docspack 0.0.1 → 0.1.0

package/dist/init/templates.js

@@ -0,0 +1,181 @@
+import { CONFIG_KEY } from "../config.js";
+import { AGENTS_SNIPPET, FEEDBACK_SNIPPET } from "../snippet.js";
+import { LLMS_DIR } from "../spec.js";
+/** Marker the doctor looks for, so a half-filled template cannot be published as documentation. */
+export const PLACEHOLDER = "TODO:";
+export function packageJson(input) {
+    const subject = input.libraryName ?? input.name;
+    return `${JSON.stringify({
+        name: input.name,
+        version: input.version,
+        description: `Documentation for ${subject}, for use with docspack.`,
+        keywords: ["docspack", "documentation", "ai", "agents", "mcp"],
+        ...(input.repository === undefined
+            ? {}
+            : { repository: { type: "git", url: `git+${input.repository}.git` } }),
+        ...(input.license === undefined ? {} : { license: input.license }),
+        // Without .llms the published package installs fine and indexes nothing.
+        files: [LLMS_DIR, "llms.txt"],
+        publishConfig: { access: "public" },
+        // `documents` names the library, which is what `docspack verify` checks the docs against.
+        [CONFIG_KEY]: {
+            ...(input.libraryName === undefined ? {} : { documents: input.libraryName }),
+            ...input.build,
+        },
+        scripts: {
+            build: "docspack build",
+            // Rebuilds and validates on every publish, so a stale payload cannot reach the registry.
+            prepublishOnly: "docspack build && docspack doctor --strict",
+        },
+        devDependencies: { docspack: `^${input.docspackVersion}` },
+    }, null, 2)}\n`;
+}
+export function readme(name, libraryName) {
+    const subject = libraryName ?? "this library";
+    return `# ${name}
+
+Documentation for ${subject}, packaged for [docspack](https://github.com/docspack/docspack)
+so AI coding agents can read it locally, at the version you installed.
+
+\`\`\`bash
+npm i -D ${name}
+npx docspack sync
+npx docspack ask "how do I authenticate"
+\`\`\`
+
+Give an agent access with one line in AGENTS.md or CLAUDE.md:
+
+\`\`\`md
+${AGENTS_SNIPPET.join("\n")}
+\`\`\`
+
+No server needed. \`docspack mcp\` serves the same index over MCP for clients that prefer a
+declared tool; both return identical text, scoped to the version this project depends on.
+
+Add this as well if you want the agent to record documentation problems it hits:
+
+\`\`\`md
+${FEEDBACK_SNIPPET.join("\n")}
+\`\`\`
+
+## What is in here
+
+\`${LLMS_DIR}/\` holds the machine-readable payload: a manifest and one Markdown file per
+chunk. \`llms.txt\` is the table of contents. Both are generated — see the repository this
+package is built from to change the source documentation.
+`;
+}
+export function gitignore() {
+    return `# Generated by \`docspack build\`. Rebuilt on publish by prepublishOnly.
+${LLMS_DIR}/
+llms.txt
+`;
+}
+/**
+ * Three seeds that map onto how retrieval works: one chunk should answer one question. The
+ * guidance in them is what `docspack doctor` checks, so following it keeps the package clean.
+ */
+export function docSeeds(subject) {
+    return [
+        {
+            path: "docs/01-overview.md",
+            contents: `# ${subject} overview
+
+${PLACEHOLDER} one paragraph on what ${subject} is and the problem it solves. Write plainly:
+no marketing adjectives, no "in this guide". Every sentence should carry a fact, because the
+index matches on the words someone would type.
+
+## Mental model
+
+${PLACEHOLDER} the two or three concepts a reader needs before anything else makes sense.
+Name them the way your API names them, in \`inline code\` — those names are indexed.
+
+## When to use it
+
+${PLACEHOLDER} what ${subject} is for, and what it is not for. Keep sentences under 40 words:
+one claim each retrieves better than two joined by a conjunction.
+`,
+        },
+        {
+            path: "docs/02-getting-started.md",
+            contents: `# Getting started with ${subject}
+
+## Installation
+
+${PLACEHOLDER} the install command, and any peer requirement.
+
+## Configuration
+
+${PLACEHOLDER} the minimum configuration needed to make a first call. Put option names in
+\`inline code\` — docspack indexes those as entities, which is how an agent finds them.
+Show the call rather than describing it; a chunk with no code is hard to act on.
+
+## Your first call
+
+${PLACEHOLDER} a complete, runnable example. Short and real beats long and abstract.
+`,
+        },
+        {
+            path: "docs/03-api.md",
+            contents: `# ${subject} API
+
+Give each operation its own \`##\` heading: docspack splits chunks at that level, and one
+chunk that answers one question retrieves far better than one that answers five.
+
+## ${PLACEHOLDER} first operation
+
+${PLACEHOLDER} what it does, its parameters, what it returns, and one example.
+
+## ${PLACEHOLDER} second operation
+
+${PLACEHOLDER} same shape as above.
+`,
+        },
+    ];
+}
+export function workflow(name, buildArgs) {
+    return `# Publishes ${name} on every release, so the documentation version always
+# matches the library version. Needs an NPM_TOKEN secret with publish rights.
+
+name: Publish documentation package
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Version to publish
+        required: true
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org
+
+      - name: Resolve the version
+        id: version
+        run: echo "value=\${{ inputs.version || github.event.release.tag_name }}" >> "$GITHUB_OUTPUT"
+
+      - name: Generate the documentation package
+        run: npx docspack build${buildArgs} --pkg-version "\${{ steps.version.outputs.value }}"
+
+      - name: Validate before publishing
+        run: npx docspack doctor --strict
+
+      - name: Publish to npm
+        run: npm publish --access public --provenance
+        env:
+          NODE_AUTH_TOKEN: \${{ secrets.NPM_TOKEN }}
+`;
+}
+//# sourceMappingURL=templates.js.map

package/dist/init/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/init/templates.ts"],"names":[],"mappings":"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"}

package/dist/init/write.d.ts

@@ -0,0 +1,20 @@
+import type { InitPlan } from "./plan.js";
+export type WriteStatus = "created" | "overwritten" | "unchanged" | "skipped";
+export interface WrittenFile {
+    readonly path: string;
+    readonly status: WriteStatus;
+}
+export interface ApplyOptions {
+    /** Overwrite files that already exist and differ. */
+    readonly force?: boolean;
+    /** Report what would happen without touching the disk. */
+    readonly dryRun?: boolean;
+}
+/**
+ * Writes a plan. Existing files are left alone unless they are identical or `--force` is set, so
+ * re-running `init` in a real project never destroys work.
+ */
+export declare function applyPlan(cwd: string, plan: InitPlan, options?: ApplyOptions): Promise<WrittenFile[]>;
+/** Renders a plan as the tree `--dry-run` and the confirmation step print. */
+export declare function renderTree(plan: InitPlan, written?: readonly WrittenFile[]): string;
+//# sourceMappingURL=write.d.ts.map

package/dist/init/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../src/init/write.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;AAE9E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,EAAE,CAAC,CA6BxB;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,GAAG,MAAM,CAcnF"}

package/dist/init/write.js

@@ -0,0 +1,56 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+import { DocspackError } from "../errors.js";
+/**
+ * Writes a plan. Existing files are left alone unless they are identical or `--force` is set, so
+ * re-running `init` in a real project never destroys work.
+ */
+export async function applyPlan(cwd, plan, options = {}) {
+    const root = resolve(cwd, plan.dir);
+    const results = [];
+    for (const file of plan.files) {
+        const target = resolve(root, file.path);
+        const inside = relative(root, target);
+        if (inside.length === 0 || inside.startsWith("..") || inside.startsWith(`..${sep}`)) {
+            throw new DocspackError(`Refusing to write "${file.path}" outside of ${plan.dir}`);
+        }
+        const existing = await read(target);
+        if (existing === file.contents) {
+            results.push({ path: file.path, status: "unchanged" });
+            continue;
+        }
+        if (existing !== undefined && options.force !== true) {
+            results.push({ path: file.path, status: "skipped" });
+            continue;
+        }
+        if (options.dryRun !== true) {
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, file.contents, "utf8");
+        }
+        results.push({ path: file.path, status: existing === undefined ? "created" : "overwritten" });
+    }
+    return results;
+}
+/** Renders a plan as the tree `--dry-run` and the confirmation step print. */
+export function renderTree(plan, written) {
+    const status = new Map(written?.map((file) => [file.path, file.status]));
+    const paths = [...plan.files].map((file) => file.path).sort();
+    const lines = [`${plan.dir}/`];
+    paths.forEach((path, index) => {
+        const marker = index === paths.length - 1 ? "└──" : "├──";
+        const state = status.get(path);
+        lines.push(`${marker} ${path}${state === undefined || state === "created" ? "" : `  (${state})`}`);
+    });
+    return lines.join("\n");
+}
+async function read(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+//# sourceMappingURL=write.js.map

package/dist/init/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/init/write.ts"],"names":[],"mappings":"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"}

package/dist/kinds.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The kinds of documentation problem docspack records.
+ *
+ * `drift` is Tier A: a name the documentation uses that the library does not declare, which is
+ * a fact about two files and needs no model to establish. The other two are Tier B, where a
+ * reader exercised judgment and therefore has to show its work.
+ *
+ * There is deliberately no kind for "this page is confusing". Unfalsifiable claims are
+ * infinitely generatable and of no use to a maintainer.
+ */
+export declare const KINDS: readonly ["drift", "incorrect", "missing"];
+export type FindingKind = (typeof KINDS)[number];
+export declare function isFindingKind(value: unknown): value is FindingKind;
+//# sourceMappingURL=kinds.d.ts.map

package/dist/kinds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds.d.ts","sourceRoot":"","sources":["../src/kinds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,KAAK,4CAA6C,CAAC;AAEhE,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjD,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE"}

package/dist/kinds.js

@@ -0,0 +1,15 @@
+/**
+ * The kinds of documentation problem docspack records.
+ *
+ * `drift` is Tier A: a name the documentation uses that the library does not declare, which is
+ * a fact about two files and needs no model to establish. The other two are Tier B, where a
+ * reader exercised judgment and therefore has to show its work.
+ *
+ * There is deliberately no kind for "this page is confusing". Unfalsifiable claims are
+ * infinitely generatable and of no use to a maintainer.
+ */
+export const KINDS = ["drift", "incorrect", "missing"];
+export function isFindingKind(value) {
+    return typeof value === "string" && KINDS.includes(value);
+}
+//# sourceMappingURL=kinds.js.map

package/dist/kinds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kinds.js","sourceRoot":"","sources":["../src/kinds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,CAAU,CAAC;AAIhE,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,KAA2B,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACnF,CAAC"}

package/dist/llms-txt.d.ts

@@ -0,0 +1,25 @@
+export interface LlmsTxtLink {
+    readonly title: string;
+    readonly url: string;
+    readonly notes?: string;
+}
+export interface LlmsTxtSection {
+    readonly heading: string;
+    readonly links: readonly LlmsTxtLink[];
+}
+export interface LlmsTxtDocument {
+    readonly title?: string;
+    readonly summary?: string;
+    readonly sections: readonly LlmsTxtSection[];
+    /** Every link in document order, across all sections. */
+    readonly links: readonly LlmsTxtLink[];
+}
+/**
+ * Parses the llms.txt format (https://llmstxt.org). The parser is deliberately tolerant: real
+ * files in the wild omit the H1, start at an H2, put the blockquote before the title, and nest
+ * link items several levels deep.
+ */
+export declare function parseLlmsTxt(text: string): LlmsTxtDocument;
+/** Absolute http(s) links, de-duplicated, in document order. */
+export declare function fetchableLinks(document: LlmsTxtDocument): readonly LlmsTxtLink[];
+//# sourceMappingURL=llms-txt.d.ts.map

package/dist/llms-txt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-txt.d.ts","sourceRoot":"","sources":["../src/llms-txt.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAC;IAC7C,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CACxC;AAWD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAoE1D;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,SAAS,WAAW,EAAE,CAWhF"}

package/dist/llms-txt.js

@@ -0,0 +1,94 @@
+const H1 = /^#\s+(.+?)\s*$/;
+const H2 = /^##\s+(.+?)\s*$/;
+const QUOTE = /^>\s?(.*)$/;
+const LIST_LINK = /^\s*[-*+]\s+\[([^\]]*)\]\(([^)]+)\)\s*(?::\s*(.*))?$/;
+const FENCE = /^\s*(?:```|~~~)/;
+/** Links before the first `##` heading land in this section. */
+const PREAMBLE = "";
+/**
+ * Parses the llms.txt format (https://llmstxt.org). The parser is deliberately tolerant: real
+ * files in the wild omit the H1, start at an H2, put the blockquote before the title, and nest
+ * link items several levels deep.
+ */
+export function parseLlmsTxt(text) {
+    const lines = text.replace(/^/, "").replace(/\r\n/g, "\n").split("\n");
+    let title;
+    const summaryLines = [];
+    let summaryClosed = false;
+    let inFence = false;
+    let heading = PREAMBLE;
+    const sections = new Map();
+    const links = [];
+    const push = (link) => {
+        const bucket = sections.get(heading);
+        if (bucket === undefined)
+            sections.set(heading, [link]);
+        else
+            bucket.push(link);
+        links.push(link);
+    };
+    for (const line of lines) {
+        if (FENCE.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const h2 = H2.exec(line);
+        if (h2?.[1] !== undefined) {
+            heading = h2[1];
+            summaryClosed = true;
+            if (!sections.has(heading))
+                sections.set(heading, []);
+            continue;
+        }
+        const h1 = H1.exec(line);
+        if (h1?.[1] !== undefined) {
+            title ??= h1[1];
+            continue;
+        }
+        const quote = QUOTE.exec(line);
+        if (quote?.[1] !== undefined) {
+            if (!summaryClosed)
+                summaryLines.push(quote[1].trim());
+            continue;
+        }
+        if (summaryLines.length > 0 && line.trim().length === 0)
+            summaryClosed = true;
+        const item = LIST_LINK.exec(line);
+        if (item?.[1] !== undefined && item[2] !== undefined) {
+            const url = item[2].trim().split(/\s+/)[0];
+            if (url === undefined || url.length === 0)
+                continue;
+            const notes = item[3]?.trim();
+            push({
+                title: item[1].trim(),
+                url,
+                ...(notes === undefined || notes.length === 0 ? {} : { notes }),
+            });
+        }
+    }
+    const summary = summaryLines.join(" ").trim();
+    return {
+        ...(title === undefined ? {} : { title }),
+        ...(summary.length === 0 ? {} : { summary }),
+        sections: [...sections].map(([name, sectionLinks]) => ({ heading: name, links: sectionLinks })),
+        links,
+    };
+}
+/** Absolute http(s) links, de-duplicated, in document order. */
+export function fetchableLinks(document) {
+    const seen = new Set();
+    const result = [];
+    for (const link of document.links) {
+        if (!/^https?:\/\//i.test(link.url))
+            continue;
+        const key = link.url.split("#")[0] ?? link.url;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(link);
+    }
+    return result;
+}
+//# sourceMappingURL=llms-txt.js.map

package/dist/llms-txt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-txt.js","sourceRoot":"","sources":["../src/llms-txt.ts"],"names":[],"mappings":"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"}

package/dist/mcp.d.ts

@@ -0,0 +1,15 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Store } from "./db.js";
+export interface McpOptions {
+    readonly cwd: string;
+    readonly store: Store;
+    readonly version: string;
+    /** Only used in the startup banner; defaults to the standard location. */
+    readonly storePath?: string;
+    readonly limit?: number;
+    readonly maxTokens?: number;
+}
+export declare function createMcpServer(options: McpOptions): McpServer;
+/** Runs the server over stdio. stdout carries the protocol, so nothing else may be written to it. */
+export declare function startMcpServer(options: McpOptions): Promise<void>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAGpE,OAAO,EAAoB,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAMvD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AA4BD,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,SAAS,CA6I9D;AAED,qGAAqG;AACrG,wBAAsB,cAAc,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvE"}

package/dist/mcp.js

@@ -0,0 +1,158 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { defaultStorePath } from "./db.js";
+import { DocspackError } from "./errors.js";
+import { addFinding, feedbackPath } from "./feedback.js";
+import { KINDS } from "./kinds.js";
+import { DEFAULT_LIMIT, DEFAULT_MAX_TOKENS, queryDocs, renderAnswer } from "./search.js";
+const DESCRIPTION = [
+    "Search the documentation of this project's installed dependencies.",
+    "Returns Markdown excerpts from local, version-matched documentation packages.",
+    "Prefer this over recalling API details from memory: the local copy matches the",
+    "exact dependency versions in this project.",
+].join(" ");
+/**
+ * A tool description is the only thing shaping how a model uses it, so this one carries the
+ * same rules `addFinding` enforces. Saying plainly that the record stops at a human matters
+ * most: a model that thinks it is filing an issue behaves differently from one that knows it
+ * is appending to a file someone will read.
+ */
+const RECORD_DESCRIPTION = [
+    "Record a problem in this project's local documentation, after you have hit it.",
+    "Use it when documentation contradicts the installed package: a name it uses that",
+    "the package does not export (drift), a statement or example that is wrong",
+    "(incorrect), or a precondition it omits that made the code fail (missing).",
+    "The record is appended to a local file for a human to review. Nothing is sent",
+    "anywhere, no issue is filed, and no maintainer is contacted by this tool.",
+    "Only record claims that could be shown false. Do not record opinions about",
+    "style, clarity or completeness; there is no kind for them and they will be",
+    "rejected. incorrect and missing must carry expected, actual and repro, so",
+    "record them only after actually running something.",
+].join(" ");
+export function createMcpServer(options) {
+    const server = new McpServer({ name: "docspack", version: options.version }, {
+        instructions: "docspack exposes the documentation of this project's dependencies as a local, " +
+            "version-accurate search index. Use query_local_docs before answering questions " +
+            "about a dependency's API. If that documentation turns out to be wrong, " +
+            "record_docs_problem writes the problem to a local file for a human to review; " +
+            "it does not contact anyone.",
+    });
+    server.registerTool("query_local_docs", {
+        title: "Query local documentation",
+        description: DESCRIPTION,
+        inputSchema: {
+            query: z.string().min(1).describe("Words to search for, e.g. 'webhook signature'"),
+            packageFilter: z
+                .string()
+                .optional()
+                .describe("Restrict to packages whose name contains this text, e.g. 'stripe'"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ query, packageFilter }) => {
+        try {
+            const result = await queryDocs({
+                cwd: options.cwd,
+                store: options.store,
+                query,
+                ...(packageFilter === undefined ? {} : { packageFilter }),
+                limit: options.limit ?? DEFAULT_LIMIT,
+                maxTokens: options.maxTokens ?? DEFAULT_MAX_TOKENS,
+            });
+            return { content: [{ type: "text", text: renderAnswer(result, query) }] };
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `docspack could not run that query: ${error instanceof Error ? error.message : String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("record_docs_problem", {
+        title: "Record a documentation problem",
+        description: RECORD_DESCRIPTION,
+        inputSchema: {
+            chunkId: z
+                .string()
+                .min(1)
+                .describe("The chunk the problem is in, exactly as query_local_docs printed it above the answer, e.g. '@acme/docspack@1.4.0/api-auth'"),
+            kind: z
+                .enum(KINDS)
+                .describe("drift: a name the docs use that the package does not export. incorrect: a statement or example that is wrong. missing: an omitted precondition that made the code fail."),
+            evidence: z
+                .string()
+                .min(1)
+                .describe("The claim in one line, naming what is wrong, e.g. 'client.setKey is not exported; setApiKey is'"),
+            expected: z
+                .string()
+                .optional()
+                .describe("What the documentation led you to expect. Required unless kind is drift."),
+            actual: z
+                .string()
+                .optional()
+                .describe("What happened instead. Required unless kind is drift."),
+            repro: z
+                .string()
+                .optional()
+                .describe("Code that demonstrates the problem. Required unless kind is drift. It is stored verbatim, so do not include secrets."),
+        },
+        // Recording is a write, and a repeat bumps a counter, so it is not idempotent either.
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async ({ chunkId, kind, evidence, expected, actual, repro }) => {
+        try {
+            // Every rule lives in addFinding, so this tool cannot be a looser way in than the CLI.
+            const { finding, repeat } = await addFinding({
+                cwd: options.cwd,
+                chunkId,
+                kind,
+                evidence,
+                ...(expected === undefined ? {} : { expected }),
+                ...(actual === undefined ? {} : { actual }),
+                ...(repro === undefined ? {} : { repro }),
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: [
+                            repeat
+                                ? `This problem was already recorded; it has now been seen ${finding.seen} times.`
+                                : `Recorded ${finding.fingerprint} in ${feedbackPath(options.cwd)}.`,
+                            "Nothing was sent. A human reviews the file and decides whether to report it.",
+                        ].join(" "),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            // Saying which field is missing is what lets a model correct itself and retry, so the
+            // hint is passed through. It is written for the CLI, where the fields are flags; here
+            // they are parameters, so the dashes come off.
+            const hint = error instanceof DocspackError ? error.hint : undefined;
+            const message = error instanceof Error ? error.message : String(error);
+            const text = hint === undefined ? `Not recorded: ${message}` : `Not recorded: ${message}. ${hint}`;
+            return {
+                content: [{ type: "text", text: text.replace(/--(?=[a-z])/g, "") }],
+                isError: true,
+            };
+        }
+    });
+    return server;
+}
+/** Runs the server over stdio. stdout carries the protocol, so nothing else may be written to it. */
+export async function startMcpServer(options) {
+    const server = createMcpServer(options);
+    process.stderr.write(`docspack mcp: serving ${options.storePath ?? defaultStorePath()} for ${options.cwd}\n`);
+    await server.connect(new StdioServerTransport());
+}
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/preview.d.ts

@@ -0,0 +1,18 @@
+import { type QueryHit } from "./search.js";
+export interface PreviewOptions {
+    readonly dir: string;
+    readonly query: string;
+    readonly limit?: number;
+    readonly maxTokens?: number;
+}
+export interface PreviewResult {
+    readonly hits: readonly QueryHit[];
+    readonly tokens: number;
+    readonly indexed: number;
+}
+/**
+ * Answers a query from a package on disk, through the same ranking and token budget an agent
+ * gets. Nothing is published, installed, or written to the global store.
+ */
+export declare function previewPackage(options: PreviewOptions): Promise<PreviewResult>;
+//# sourceMappingURL=preview.d.ts.map