docspack 0.0.1 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 docspack contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,179 @@
+<div align="center">
+
+<a href="https://docspack.dev"><img src="https://docspack.dev/logo.png" width="72" height="72" alt="docspack" /></a>
+
+# docspack
+
+Local, version-locked documentation packages for AI agents, indexed in SQLite and served over MCP.
+
+[![npm](https://img.shields.io/npm/v/docspack.svg)](https://www.npmjs.com/package/docspack)
+[![downloads](https://img.shields.io/npm/dm/docspack.svg)](https://www.npmjs.com/package/docspack)
+[![license](https://img.shields.io/npm/l/docspack.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/docspack.svg)](https://nodejs.org)
+[![types](https://img.shields.io/badge/types-TypeScript%20strict-blue.svg)](https://www.typescriptlang.org)
+[![status](https://img.shields.io/badge/status-experimental-orange.svg)](https://github.com/docspack/docspack/releases)
+
+[Website](https://docspack.dev) ·
+[Documentation](https://docspack.dev/llms.txt) ·
+[GitHub](https://github.com/docspack/docspack) ·
+[Releases](https://github.com/docspack/docspack/releases)
+
+</div>
+
+---
+
+> **Publishing documentation for your own library?** You want `docspack init`, which
+> scaffolds a documentation package. This README is mostly about consuming them.
+
+> **Just want your agent to read the docs?** Three lines: install a docs package, run
+> `docspack sync`, and paste one sentence into `AGENTS.md`. Jump to [Quick start](#quick-start).
+
+## Overview
+
+An AI coding agent answers from one of three places: its training data, which is frozen at
+some past version; a docs site it fetches, which is whatever the vendor publishes today; or
+nothing at all. None of those is the version in your lockfile.
+
+docspack closes that gap by making documentation an ordinary npm dependency. A documentation
+package (`@stripe/docspack`, `@docspack-community/jira`) holds Markdown split into chunks plus
+a manifest describing them, and its version tracks the library's. `docspack sync` indexes the
+ones this project depends on into one SQLite database per machine, and `docspack ask` answers
+from that index — offline, bounded, and matched to what you actually installed.
+
+The mental model: **publish → sync → ask.**
+
+## Features
+
+- **Version-locked** — answers come from the docs package resolved in your lockfile, never a
+  newer or older one. The index may hold five versions of a library; a project sees only its own.
+- **Offline by construction** — `sync`, `ask`, `search` and `list` make no network requests.
+  They read `node_modules` and a local SQLite file.
+- **Bounded responses** — 3 chunks and 3,000 tokens by default, counted from the manifest
+  before content is returned, so a query cannot overrun its budget.
+- **No server, no resident context** — every agent already has a shell. One line in `AGENTS.md`
+  is the whole setup, and nothing runs when nobody is asking.
+- **MCP when you want it** — `docspack mcp` serves the same index over the Model Context
+  Protocol, returning identical text, for clients that prefer a declared tool.
+- **No native modules** — the index uses `node:sqlite` from the standard library.
+
+## Installation
+
+```sh
+npm  install -D docspack
+pnpm add     -D docspack
+yarn add     -D docspack
+```
+
+Requires Node 22.5 or newer.
+
+## Quick start
+
+```sh
+# 1. Add a documentation package, the same way you add any dependency
+pnpm add -D @acme/docspack
+
+# 2. Index every docs package this project depends on
+npx docspack sync
+
+# 3. Ask it something
+npx docspack ask "how do I verify a webhook signature"
+```
+
+Then give the agent access by pasting these two lines into `AGENTS.md` or `CLAUDE.md`:
+
+```
+Run `docspack ask "<question>"` for documentation on this project's
+dependencies. It answers from the installed versions.
+```
+
+That is the entire integration. No server to start, no per-client configuration.
+
+<details>
+<summary>Using MCP instead</summary>
+
+```sh
+claude mcp add docspack -- npx -y docspack mcp
+```
+
+The server exposes `query_local_docs` (`query`, optional `packageFilter`), returns the
+best-ranked chunks and caps a response at 3,000 tokens. It also exposes `record_docs_problem`,
+the equivalent of `docspack feedback add` — it appends to a local file and cannot send
+anything anywhere.
+
+</details>
+
+## Commands
+
+Reading:
+
+```
+docspack sync                Index the docs packages this project depends on
+docspack ask <question>      Answer from the local index — the command to give an agent
+docspack search <query>      Same index, formatted for a human reading the terminal
+docspack list                Show this project's docs packages and their index state
+docspack verify              Check the docs still describe the code you installed
+docspack feedback <sub>      Record documentation problems: add, list, submit, remove
+docspack mcp                 Serve the index over MCP instead, as a long-lived process
+docspack sources             List curated sources that `docspack build` can fetch
+```
+
+Authoring:
+
+```
+docspack init                Scaffold a documentation package, then build and check it
+docspack build [source]      Generate the .llms/ payload for publishing
+docspack doctor              Check a package the way the indexer and a reviewer would
+docspack preview <query>     Answer a query from the local package, as an agent would
+```
+
+Run `docspack --help` for every flag.
+
+## Authoring a documentation package
+
+```sh
+npx docspack init                                  # scaffold, build and check in one step
+npx docspack build --from ./docs                   # Markdown, split at headings
+npx docspack build --openapi ./openapi.json        # one chunk per operation
+npx docspack build stripe                          # from a project's public llms.txt
+```
+
+`build` writes `.llms/manifest.json`, `.llms/chunks/*.md` and an `llms.txt` table of contents,
+ready for `npm publish`. `docspack doctor --strict` checks the result the way the indexer and
+a reviewer would.
+
+Manifests validate against <https://docspack.dev/schema/v1.json>.
+
+## Recording documentation problems
+
+An agent holds the documentation, the installed library and a failing program at the same
+moment — a signal that today evaporates. `docspack feedback add` captures it locally:
+
+```sh
+npx docspack feedback add --chunk @acme/docspack@1.4.0/api-auth \
+  --kind drift --evidence "client.setKey is not exported; setApiKey is"
+```
+
+Claims must be falsifiable. `drift` must name the identifier; `incorrect` and `missing` must
+carry `--expected`, `--actual` and `--repro`. There is deliberately no kind for "this page is
+confusing".
+
+**Nothing is transmitted, and nothing can be** — docspack contains no code that sends a report
+anywhere. `docspack feedback submit` prints a prefilled GitHub issue URL for vendors who opted
+in from their own `package.json`, and a human decides whether to open it.
+
+## Status
+
+Pre-1.0 and versioned accordingly: minor releases may change behaviour. The package
+specification is the part most worth depending on, and it is documented at
+<https://docspack.dev/schema/v1.json>.
+
+## Related packages
+
+| Package | Description |
+| --- | --- |
+| [`@docspack/registry`](https://www.npmjs.com/package/@docspack/registry) | Curated llms.txt sources for bootstrapping docs packages. |
+| [`@docspack/docspack`](https://www.npmjs.com/package/@docspack/docspack) | docspack's own documentation, shipped as a docs package. |
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/docspack.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Launcher for the compiled CLI.
+ *
+ * `bin` cannot point straight at `dist/cli.js`: a package manager links bin files during
+ * install, which in this repository happens before anything is compiled. pnpm finds no
+ * `dist/cli.js`, warns, and silently skips the link — so every later `docspack …` fails with
+ * "command not found", including the one that builds this package's own documentation.
+ *
+ * This file is committed, so the link always succeeds. `dist/` only has to exist by the time
+ * someone actually runs the command.
+ */
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const cli = new URL("../dist/cli.js", import.meta.url);
+
+if (existsSync(fileURLToPath(cli))) {
+  await import(cli.href);
+} else {
+  process.stderr.write(
+    "docspack is not built: dist/cli.js is missing.\nRun `pnpm turbo build --filter docspack` and try again.\n",
+  );
+  process.exitCode = 1;
+}

package/dist/build.d.ts

@@ -0,0 +1,31 @@
+import { HttpClient } from "./http.js";
+export interface BuildOptions {
+    /** Directory the docs package is written to. */
+    readonly out: string;
+    readonly name?: string;
+    readonly version?: string;
+    /** Directory of Markdown files to package. */
+    readonly from?: string;
+    /** OpenAPI document (JSON) to package, one chunk per operation. */
+    readonly openapi?: string;
+    /** Registry id or llms.txt URL to fetch and package. */
+    readonly source?: string;
+    readonly pages?: number;
+    readonly maxChunkTokens?: number;
+    readonly http?: HttpClient;
+    readonly onProgress?: (message: string) => void;
+}
+export interface BuildResult {
+    readonly name: string;
+    readonly version: string;
+    readonly dir: string;
+    readonly chunks: number;
+    readonly tokens: number;
+    readonly warnings: readonly string[];
+}
+/**
+ * Generates a docs package: `.llms/manifest.json`, `.llms/chunks/*.md` and an `llms.txt` table of
+ * contents, ready to publish to npm as `@vendor/docspack`.
+ */
+export declare function buildPackage(input: BuildOptions): Promise<BuildResult>;
+//# sourceMappingURL=build.d.ts.map

package/dist/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../src/build.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAWvC,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAkBD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAsD5E"}