docspack 0.0.1 → 0.1.0

package/src/cli.ts

@@ -0,0 +1,883 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { posix } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { defaultStorePath, Store, silenceSqliteWarning } from "./db.js";
+import { discoverPackages } from "./discovery.js";
+import { type DoctorReport, runDoctor } from "./doctor.js";
+import { DocspackError } from "./errors.js";
+import { renderTree } from "./init/write.js";
+import { previewPackage } from "./preview.js";
+import { DEFAULT_LIMIT, DEFAULT_MAX_TOKENS, queryDocs, renderAnswer } from "./search.js";
+import { AGENTS_SNIPPET, FEEDBACK_SNIPPET } from "./snippet.js";
+import { syncProject } from "./sync.js";
+import { verifyProject } from "./verify.js";
+
+// The MCP SDK costs ~200ms to load and the Markdown converter ~60ms. Neither is needed to
+// answer a query, so the commands that need them import them at the point of use. Every
+// `docspack ask` pays for what it uses and nothing else.
+
+const OPTIONS = {
+  help: { type: "boolean", short: "h" },
+  version: { type: "boolean", short: "v" },
+  json: { type: "boolean" },
+  quiet: { type: "boolean", short: "q" },
+  cwd: { type: "string" },
+  store: { type: "string" },
+  force: { type: "boolean" },
+  package: { type: "string", short: "p" },
+  limit: { type: "string" },
+  "max-tokens": { type: "string" },
+  all: { type: "boolean" },
+  from: { type: "string" },
+  openapi: { type: "string" },
+  out: { type: "string" },
+  name: { type: "string" },
+  "pkg-version": { type: "string" },
+  pages: { type: "string" },
+  mirror: { type: "string" },
+  mode: { type: "string" },
+  template: { type: "string" },
+  community: { type: "boolean" },
+  workflow: { type: "boolean" },
+  "no-workflow": { type: "boolean" },
+  "no-build": { type: "boolean" },
+  yes: { type: "boolean", short: "y" },
+  "dry-run": { type: "boolean" },
+  strict: { type: "boolean" },
+  "package-dir": { type: "string" },
+  chunk: { type: "string" },
+  kind: { type: "string" },
+  evidence: { type: "string" },
+  expected: { type: "string" },
+  actual: { type: "string" },
+  repro: { type: "string" },
+} as const;
+
+const HELP = `docspack — local, version-locked documentation for AI agents
+
+Usage
+  docspack <command> [options]
+
+Commands
+  sync                 Index the docs packages this project depends on
+  ask <question>       Answer from the local index — the command to give an agent
+  search <query>       Same index, formatted for a human reading the terminal
+  list                 Show this project's docs packages and their index state
+  verify               Check the docs still describe the code you installed
+  feedback <sub>       Record documentation problems: add, list, submit, remove
+  mcp                  Serve the index over MCP instead, as a long-lived process
+  sources              List curated sources that \`docspack build\` can fetch
+
+Authoring
+  init                 Scaffold a documentation package, then build and check it
+  build [source]       Generate the .llms/ payload for publishing
+  doctor               Check a package the way the indexer and a reviewer would
+  preview <query>      Answer a query from the local package, as an agent would
+
+How it works
+  Documentation ships as npm packages named @vendor/docspack or
+  @docspack-community/<name>. Add them to package.json, run \`docspack sync\`, and
+  every chunk is indexed into a shared SQLite database with FTS5. Agents query
+  that index locally: no network, no scraping, always the installed version.
+
+Giving an agent access
+  Any agent with a shell can run \`docspack ask\`, so one line in AGENTS.md or
+  CLAUDE.md is the whole setup — no server, no per-agent configuration, and
+  nothing resident when nobody is asking:
+
+${AGENTS_SNIPPET.map((line) => `    ${line}`).join("\n")}
+
+  Add the block below as well if you want the agent to record documentation
+  problems it runs into. It writes to a local file; nothing is sent:
+
+${FEEDBACK_SNIPPET.map((line) => `    ${line}`).join("\n")}
+
+  \`docspack mcp\` serves the same index over the Model Context Protocol for
+  clients that prefer a tool definition. Both return identical text.
+
+Recording documentation problems
+  \`docspack feedback add\` writes a finding to .docspack/feedback.jsonl in this
+  project. Nothing is transmitted: docspack contains no code that can send a
+  report anywhere, and it never will.
+
+    docspack feedback add --chunk @acme/docspack@1.4.0/api-auth \\
+      --kind drift --evidence "client.setKey is not exported; setApiKey is"
+
+  A finding has to be falsifiable. \`drift\` must name the identifier that
+  drifted. \`incorrect\` and \`missing\` must carry --expected, --actual and
+  --repro, so a claim that cannot show its work cannot be recorded at all.
+  Recording the same problem again increments a counter instead of adding a
+  second entry.
+
+  \`docspack feedback submit\` prints a prefilled GitHub issue URL for every
+  finding whose vendor asked to receive it, and routes nothing anywhere else.
+  A vendor opts in from their own package.json:
+
+    "docspack": {
+      "feedback": {
+        "github": "acme/sdk",
+        "labels": ["documentation"],
+        "accepts": ["drift"]
+      }
+    }
+
+  No \`feedback\` block means no channel and no route. \`accepts\` narrows which
+  kinds reach them. A human opens the link, reads it, and files it.
+
+Options
+  -y, --yes          init: skip prompts and use flags plus detected defaults
+  --dry-run          init: print the file tree and write nothing
+  --mirror <id|url>  init: bootstrap from a published llms.txt
+  --community        init: scaffold under @docspack-community
+  --no-workflow      init: skip the release workflow
+  --no-build         init: scaffold only
+  --template <t>     init: full (default) or minimal
+  --strict           doctor: treat warnings as failures
+  --package-dir <d>  doctor, preview, verify: the package to inspect (default: .)
+  --chunk <id>       feedback add: the chunk the problem is in
+  --kind <k>         feedback add: drift, incorrect or missing
+  --evidence <text>  feedback add: the claim, in one line
+  --expected <text>  feedback add: what the documentation led you to expect
+  --actual <text>    feedback add: what happened instead
+  --repro <code>     feedback add: code that demonstrates it
+  --force            sync: re-index packages already in the store; init: overwrite files
+  -p, --package <s>  search: only packages whose name contains this text
+  --limit <n>        search: maximum chunks to return (default ${DEFAULT_LIMIT})
+  --max-tokens <n>   search: token ceiling for the result set (default ${DEFAULT_MAX_TOKENS})
+  --all              search: the whole store, not just this project;
+                     feedback remove: every recorded finding
+  --from <dir>       build: directory of Markdown to package
+  --openapi <file>   build: OpenAPI JSON to package, one chunk per operation
+  --name <name>      build: package name, e.g. @acme/docspack
+  --pkg-version <v>  build: package version
+  --out <dir>        build: output directory (default: the current directory)
+  --pages <n>        build: maximum documents to fetch from a remote source
+  --store <path>     Use a different index (default: ${defaultStorePath()})
+  --cwd <dir>        Run in a different directory
+  --json             Machine-readable output
+  -q, --quiet        Only print errors
+  -h, --help         Show this help
+  -v, --version      Show the version
+
+Examples
+  npx docspack sync
+  npx docspack ask "how do I verify a webhook signature"
+  npx docspack search "webhook signature" --package stripe
+  npx docspack init
+  npx docspack init --name @acme/docspack --from ./docs --yes
+  npx docspack doctor --strict
+  npx docspack preview "how do I authenticate"
+  npx docspack verify
+  npx docspack feedback list
+  npx docspack feedback submit
+`;
+
+type Values = {
+  [K in keyof typeof OPTIONS]?: (typeof OPTIONS)[K]["type"] extends "boolean" ? boolean : string;
+};
+
+const color = process.env.NO_COLOR === undefined && process.stdout.isTTY === true;
+const paint = (code: string, text: string): string =>
+  color ? `\u001b[${code}m${text}\u001b[0m` : text;
+const bold = (text: string): string => paint("1", text);
+const dim = (text: string): string => paint("2", text);
+const green = (text: string): string => paint("32", text);
+const yellow = (text: string): string => paint("33", text);
+const red = (text: string): string => paint("31", text);
+
+function version(): string {
+  const url = new URL("../package.json", import.meta.url);
+  const parsed: unknown = JSON.parse(readFileSync(fileURLToPath(url), "utf8"));
+  const value = (parsed as { version?: unknown }).version;
+  return typeof value === "string" ? value : "0.0.0";
+}
+
+function integer(raw: string | undefined, flag: string): number | undefined {
+  if (raw === undefined) return undefined;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) {
+    throw new DocspackError(`${flag} expects a non-negative integer, got "${raw}"`);
+  }
+  return value;
+}
+
+function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+/** First few lines of prose from a chunk, skipping blanks and provenance comments. */
+function preview(content: string, lines: number): string[] {
+  return content
+    .split("\n")
+    .filter((line) => line.trim().length > 0 && !line.trimStart().startsWith("<!--"))
+    .slice(0, lines);
+}
+
+function reportDoctor(report: DoctorReport, quiet: boolean): void {
+  for (const finding of report.findings) {
+    const mark =
+      finding.severity === "error"
+        ? red("error")
+        : finding.severity === "warn"
+          ? yellow("warn")
+          : dim("info");
+    const where = finding.where === undefined ? "" : dim(` ${finding.where}`);
+    process.stderr.write(`${mark}  ${finding.message}${where}\n`);
+    if (finding.fix !== undefined) process.stderr.write(`       ${dim(finding.fix)}\n`);
+  }
+  if (quiet) return;
+
+  if (report.ok) {
+    const notes = report.findings.length > 0 ? ` (${plural(report.findings.length, "note")})` : "";
+    process.stdout.write(
+      `${green("ok")} ${plural(report.chunks, "chunk")}, ~${report.tokens} tokens${notes}\n`,
+    );
+  } else {
+    process.stderr.write(`${red("failed")} the package is not ready to publish\n`);
+  }
+}
+
+function openStore(values: Values): Store {
+  return Store.open(values.store ?? defaultStorePath());
+}
+
+async function main(argv: readonly string[]): Promise<number> {
+  let values: Values;
+  let positionals: string[];
+  try {
+    const parsed = parseArgs({ args: [...argv], options: OPTIONS, allowPositionals: true });
+    values = parsed.values;
+    positionals = parsed.positionals;
+  } catch (error) {
+    process.stderr.write(
+      `${red("error")} ${error instanceof Error ? error.message : String(error)}\n\n`,
+    );
+    process.stderr.write(HELP);
+    return 2;
+  }
+
+  if (values.version === true) {
+    process.stdout.write(`${version()}\n`);
+    return 0;
+  }
+
+  const [command = "help", ...rest] = positionals;
+  if (values.help === true || command === "help") {
+    process.stdout.write(HELP);
+    return 0;
+  }
+
+  const cwd = values.cwd ?? process.cwd();
+  const quiet = values.quiet === true;
+  const json = values.json === true;
+
+  switch (command) {
+    case "sync": {
+      const store = openStore(values);
+      try {
+        const result = await syncProject({
+          cwd,
+          store,
+          ...(values.force === true ? { force: true } : {}),
+          ...(quiet || json
+            ? {}
+            : {
+                onProgress: (message: string): void => {
+                  process.stderr.write(`${dim(message)}\n`);
+                },
+              }),
+        });
+
+        if (json) {
+          process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+          return result.packages.length === 0 && result.problems.length > 0 ? 1 : 0;
+        }
+
+        for (const pkg of result.packages) {
+          const mark = pkg.status === "indexed" ? green("+") : dim("=");
+          const trust = pkg.trusted ? "" : ` ${yellow("(community)")}`;
+          process.stdout.write(
+            `${mark} ${bold(pkg.id)}  ${pkg.chunks} chunks  ${dim(pkg.status)}${trust}\n`,
+          );
+        }
+        for (const problem of result.problems) {
+          process.stderr.write(`${yellow("!")} ${problem}\n`);
+        }
+        if (result.packages.length === 0 && !quiet) {
+          process.stdout.write(
+            "No documentation packages found. Add one, for example:\n  pnpm add -D @docspack-community/<name>\n",
+          );
+        } else if (!quiet) {
+          process.stdout.write(
+            [
+              "",
+              "Give an agent access with one line in AGENTS.md or CLAUDE.md:",
+              ...AGENTS_SNIPPET.map((line) => dim(`  ${line}`)),
+              "",
+              "Add this too if you want the agent to record documentation problems:",
+              ...FEEDBACK_SNIPPET.map((line) => dim(`  ${line}`)),
+              "",
+            ].join("\n"),
+          );
+        }
+        return 0;
+      } finally {
+        store.close();
+      }
+    }
+
+    case "ask": {
+      const question = rest.join(" ");
+      if (question.length === 0) {
+        throw new DocspackError('Usage: docspack ask "<question>"');
+      }
+
+      const store = openStore(values);
+      try {
+        const result = await queryDocs({
+          cwd,
+          store,
+          query: question,
+          ...(values.package === undefined ? {} : { packageFilter: values.package }),
+          ...(() => {
+            const limit = integer(values.limit, "--limit");
+            return limit === undefined ? {} : { limit };
+          })(),
+          ...(() => {
+            const maxTokens = integer(values["max-tokens"], "--max-tokens");
+            return maxTokens === undefined ? {} : { maxTokens };
+          })(),
+          ...(values.all === true ? { scoped: false } : {}),
+        });
+
+        if (json) {
+          process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        } else {
+          // Exactly what the MCP tool returns, so both interfaces answer identically.
+          process.stdout.write(`${renderAnswer(result, question)}\n`);
+        }
+        // Answering "nothing matched" is a successful answer, not a failed command.
+        return 0;
+      } finally {
+        store.close();
+      }
+    }
+
+    case "search": {
+      const query = rest.join(" ");
+      if (query.length === 0) throw new DocspackError("Usage: docspack search <query>");
+
+      const store = openStore(values);
+      try {
+        const result = await queryDocs({
+          cwd,
+          store,
+          query,
+          ...(values.package === undefined ? {} : { packageFilter: values.package }),
+          ...(() => {
+            const limit = integer(values.limit, "--limit");
+            return limit === undefined ? {} : { limit };
+          })(),
+          ...(() => {
+            const maxTokens = integer(values["max-tokens"], "--max-tokens");
+            return maxTokens === undefined ? {} : { maxTokens };
+          })(),
+          ...(values.all === true ? { scoped: false } : {}),
+        });
+
+        if (json) {
+          process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+          return 0;
+        }
+        if (result.hits.length === 0) {
+          process.stdout.write(`No local documentation matched "${query}".\n`);
+          return 1;
+        }
+
+        for (const hit of result.hits) {
+          const trust = hit.trusted ? "" : ` ${yellow("(community)")}`;
+          process.stdout.write(
+            `${bold(hit.chunkId)}${trust}  ${dim(`${hit.tokens} tokens · ${hit.filePath}`)}\n`,
+          );
+          for (const line of preview(hit.content, 4)) {
+            process.stdout.write(`  ${line}\n`);
+          }
+          process.stdout.write("\n");
+        }
+        process.stdout.write(
+          dim(`${result.tokens} tokens across ${plural(result.hits.length, "chunk")}\n`),
+        );
+        return 0;
+      } finally {
+        store.close();
+      }
+    }
+
+    case "list": {
+      const store = openStore(values);
+      try {
+        const { packages, problems } = await discoverPackages(cwd);
+        const rows = packages.map((pkg) => ({
+          id: pkg.id,
+          name: pkg.name,
+          version: pkg.version,
+          chunks: pkg.manifest.chunks.length,
+          trusted: pkg.trusted,
+          indexed: store.hasPackage(pkg.id),
+        }));
+
+        if (json) {
+          process.stdout.write(`${JSON.stringify({ packages: rows, problems }, null, 2)}\n`);
+          return 0;
+        }
+        if (rows.length === 0) {
+          process.stdout.write("This project has no documentation packages.\n");
+        }
+        for (const row of rows) {
+          const state = row.indexed ? green("indexed") : yellow("not indexed");
+          const trust = row.trusted ? "" : ` ${yellow("(community)")}`;
+          process.stdout.write(`${bold(row.id)}  ${row.chunks} chunks  ${state}${trust}\n`);
+        }
+        for (const problem of problems) process.stderr.write(`${yellow("!")} ${problem}\n`);
+        return 0;
+      } finally {
+        store.close();
+      }
+    }
+
+    case "verify": {
+      const report = await verifyProject({
+        cwd,
+        ...(values["package-dir"] === undefined ? {} : { packageDir: values["package-dir"] }),
+      });
+
+      if (json) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        return report.ok ? 0 : 1;
+      }
+
+      if (report.packages.length === 0) {
+        process.stdout.write("This project has no documentation packages.\n");
+        return 0;
+      }
+
+      for (const pkg of report.packages) {
+        if (pkg.status === "skipped") {
+          if (!quiet)
+            process.stdout.write(`${dim("-")} ${bold(pkg.id)}  ${dim(pkg.reason ?? "")}\n`);
+          continue;
+        }
+
+        const mark = pkg.findings.length === 0 ? green("ok") : red("drift");
+        process.stdout.write(
+          `${mark} ${bold(pkg.id)} ${dim(`documents ${pkg.documents ?? ""} · ${plural(pkg.checked, "name")} checked, ${pkg.matched} declared`)}\n`,
+        );
+        for (const finding of pkg.findings) {
+          process.stderr.write(
+            `  ${yellow(finding.entity)} is not declared; did the API become ${bold(finding.suggestion)}?\n`,
+          );
+          process.stderr.write(`  ${dim(`${finding.chunkId} · ${finding.file}`)}\n`);
+        }
+      }
+
+      if (!report.ok && !quiet) {
+        process.stderr.write(
+          `\n${dim("These are local findings. Fix the documentation, or report them to the\nmaintainer yourself — docspack never sends anything anywhere.")}\n`,
+        );
+      }
+      return report.ok ? 0 : 1;
+    }
+
+    case "feedback": {
+      const { addFinding, feedbackPath, readFeedback, removeFindings } = await import(
+        "./feedback.js"
+      );
+      const [sub = "list", ...args] = rest;
+
+      switch (sub) {
+        case "add": {
+          if (values.chunk === undefined || values.evidence === undefined) {
+            throw new DocspackError(
+              'Usage: docspack feedback add --chunk <id> --kind <k> --evidence "<claim>"',
+              { hint: "See `docspack --help` for what each kind requires." },
+            );
+          }
+
+          const { finding, repeat } = await addFinding({
+            cwd,
+            chunkId: values.chunk,
+            kind: values.kind ?? "drift",
+            evidence: values.evidence,
+            ...(values.expected === undefined ? {} : { expected: values.expected }),
+            ...(values.actual === undefined ? {} : { actual: values.actual }),
+            ...(values.repro === undefined ? {} : { repro: values.repro }),
+          });
+
+          if (json) {
+            process.stdout.write(`${JSON.stringify({ finding, repeat }, null, 2)}\n`);
+            return 0;
+          }
+          if (!quiet) {
+            process.stdout.write(
+              repeat
+                ? `${dim("=")} ${bold(finding.fingerprint)}  already recorded, now ${finding.seen}×\n`
+                : `${green("+")} ${bold(finding.fingerprint)}  recorded in ${feedbackPath(cwd)}\n`,
+            );
+            process.stdout.write(dim("Nothing was sent. Review with `docspack feedback list`.\n"));
+          }
+          return 0;
+        }
+
+        case "list": {
+          const findings = await readFeedback(cwd);
+
+          if (json) {
+            process.stdout.write(`${JSON.stringify(findings, null, 2)}\n`);
+            return 0;
+          }
+          if (findings.length === 0) {
+            process.stdout.write("No documentation problems recorded in this project.\n");
+            return 0;
+          }
+
+          for (const finding of findings) {
+            const repeats = finding.seen > 1 ? `  ${yellow(`seen ${finding.seen}×`)}` : "";
+            process.stdout.write(
+              `${bold(finding.fingerprint)}  ${finding.kind}  ${dim(finding.chunkId)}${repeats}\n`,
+            );
+            process.stdout.write(`  ${finding.evidence}\n`);
+            if (finding.repro !== undefined) {
+              process.stdout.write(`  ${dim(`repro: ${finding.repro.split("\n")[0] ?? ""}`)}\n`);
+            }
+          }
+          if (!quiet) {
+            process.stdout.write(
+              dim(
+                `\n${plural(findings.length, "finding")} in ${feedbackPath(cwd)}, none of it sent anywhere.\n`,
+              ),
+            );
+          }
+          return 0;
+        }
+
+        case "submit": {
+          const { prepareSubmission } = await import("./submit.js");
+          const report = await prepareSubmission({
+            cwd,
+            docspackVersion: version(),
+            ...(values.package === undefined ? {} : { packageFilter: values.package }),
+          });
+
+          if (json) {
+            process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+            return 0;
+          }
+          if (report.routed.length === 0 && report.blocked.length === 0) {
+            process.stdout.write("No documentation problems recorded in this project.\n");
+            return 0;
+          }
+
+          for (const { packageId: id, channel } of report.channels) {
+            process.stdout.write(
+              `${bold(id)} accepts documentation problems at ${channel.github}\n`,
+            );
+            if (channel.policy !== undefined) {
+              process.stdout.write(`  ${yellow("Read first:")} ${channel.policy}\n`);
+            }
+          }
+
+          for (const finding of report.routed) {
+            process.stdout.write(`\n${dim("─".repeat(72))}\n`);
+            process.stdout.write(`${bold(finding.fingerprint)}  ${dim(finding.chunkId)}\n\n`);
+            process.stdout.write(`${finding.title}\n\n${finding.body}\n\n`);
+            if (finding.labels.length > 0) {
+              process.stdout.write(dim(`Labels: ${finding.labels.join(", ")}\n`));
+            }
+            if (finding.containsCode) {
+              process.stdout.write(
+                `${yellow("!")} This report quotes your reproduction. Check it for anything private before filing.\n`,
+              );
+            }
+            process.stdout.write(
+              finding.url === undefined
+                ? dim("Too long for a prefilled link — open a blank issue and paste the above.\n")
+                : `${green("Open:")} ${finding.url}\n`,
+            );
+          }
+
+          if (report.blocked.length > 0) {
+            process.stdout.write(`\n${bold("Not routed")}\n`);
+            for (const finding of report.blocked) {
+              const why =
+                finding.reason === "no-channel"
+                  ? "the package declares no feedback channel"
+                  : `the vendor accepts only: ${(finding.accepts ?? []).join(", ")}`;
+              process.stdout.write(
+                `  ${finding.fingerprint}  ${finding.kind}  ${dim(finding.chunkId)}\n    ${dim(why)}\n`,
+              );
+            }
+          }
+
+          if (!quiet) {
+            process.stdout.write(
+              [
+                "",
+                dim("Nothing has been sent. docspack has no code that can send a report. Open a"),
+                dim(
+                  "link, read what is prefilled, edit it, and file it under your own name — then",
+                ),
+                dim("`docspack feedback remove <fingerprint>` to clear it from this list."),
+                "",
+              ].join("\n"),
+            );
+          }
+          return 0;
+        }
+
+        case "remove": {
+          const removed = await removeFindings({
+            cwd,
+            ...(values.all === true ? { all: true } : { fingerprints: args }),
+          });
+
+          if (json) {
+            process.stdout.write(`${JSON.stringify({ removed }, null, 2)}\n`);
+            return 0;
+          }
+          process.stdout.write(`${green("-")} removed ${plural(removed, "finding")}\n`);
+          return 0;
+        }
+
+        default:
+          throw new DocspackError(`Unknown feedback subcommand "${sub}"`, {
+            hint: "Use add, list, submit or remove.",
+          });
+      }
+    }
+
+    case "mcp": {
+      // stdout is the protocol channel from here on.
+      const { startMcpServer } = await import("./mcp.js");
+      const store = openStore(values);
+      await startMcpServer({
+        cwd,
+        store,
+        version: version(),
+        storePath: values.store ?? defaultStorePath(),
+      });
+      return 0;
+    }
+
+    case "build": {
+      const { buildPackage } = await import("./build.js");
+      const result = await buildPackage({
+        out: values.out ?? cwd,
+        ...(rest[0] === undefined ? {} : { source: rest[0] }),
+        ...(values.from === undefined ? {} : { from: values.from }),
+        ...(values.openapi === undefined ? {} : { openapi: values.openapi }),
+        ...(values.name === undefined ? {} : { name: values.name }),
+        ...(values["pkg-version"] === undefined ? {} : { version: values["pkg-version"] }),
+        ...(() => {
+          const pages = integer(values.pages, "--pages");
+          return pages === undefined ? {} : { pages };
+        })(),
+        ...(quiet || json
+          ? {}
+          : {
+              onProgress: (message: string): void => {
+                process.stderr.write(`${dim(message)}\n`);
+              },
+            }),
+      });
+
+      if (json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+      }
+      process.stdout.write(
+        `${green("+")} ${bold(`${result.name}@${result.version}`)}  ${result.chunks} chunks  ${dim(`~${result.tokens} tokens`)}\n`,
+      );
+      for (const warning of result.warnings) process.stderr.write(`${yellow("!")} ${warning}\n`);
+      if (!quiet) {
+        process.stdout.write(
+          `\nWrote ${result.dir}/.llms and ${result.dir}/llms.txt.\nPublish with \`npm publish\`, then add it to a project and run \`docspack sync\`.\n`,
+        );
+      }
+      return 0;
+    }
+
+    case "init": {
+      const { runInit } = await import("./init/run.js");
+      const result = await runInit({
+        cwd,
+        docspackVersion: version(),
+        ...(rest[0] === undefined ? {} : { name: rest[0] }),
+        ...(values.name === undefined ? {} : { name: values.name }),
+        ...(values["pkg-version"] === undefined ? {} : { version: values["pkg-version"] }),
+        ...(values.out === undefined ? {} : { out: values.out }),
+        ...(values.from === undefined ? {} : { from: values.from }),
+        ...(values.openapi === undefined ? {} : { openapi: values.openapi }),
+        ...(values.mirror === undefined ? {} : { mirror: values.mirror }),
+        ...(values.mode === undefined ? {} : { mode: values.mode as "standalone" | "in-repo" }),
+        ...(values.template === undefined
+          ? {}
+          : { template: values.template as "full" | "minimal" }),
+        ...(values.community === true ? { community: true } : {}),
+        workflow: values["no-workflow"] === true ? false : values.workflow !== false,
+        ...(values.yes === true || json ? { yes: true } : {}),
+        ...(values["dry-run"] === true ? { dryRun: true } : {}),
+        ...(values.force === true ? { force: true } : {}),
+        ...(values["no-build"] === true ? { build: false } : {}),
+        ...(quiet || json
+          ? {}
+          : {
+              onProgress: (message: string): void => {
+                process.stderr.write(`${dim(message)}\n`);
+              },
+            }),
+      });
+
+      if (json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return result.cancelled ? 1 : 0;
+      }
+      if (result.cancelled) {
+        process.stdout.write("Nothing was written.\n");
+        return 1;
+      }
+
+      process.stdout.write(`${renderTree(result.plan, result.written)}\n`);
+      const skipped = result.written.filter((file) => file.status === "skipped");
+      if (skipped.length > 0) {
+        process.stderr.write(
+          `${yellow("!")} ${skipped.length} file(s) already existed and were kept. Re-run with --force to replace them.\n`,
+        );
+      }
+      if (values["dry-run"] === true) {
+        process.stdout.write(dim("\n--dry-run: nothing was written.\n"));
+        return 0;
+      }
+
+      if (result.build !== undefined) {
+        process.stdout.write(
+          `\n${green("+")} ${bold(`${result.build.name}@${result.build.version}`)}  ${result.build.chunks} chunks  ${dim(`~${result.build.tokens} tokens`)}\n`,
+        );
+      }
+      if (result.doctor !== undefined) reportDoctor(result.doctor, quiet);
+
+      const source =
+        result.plan.input.kind === "seeded"
+          ? `${result.plan.dir}/docs/`
+          : result.plan.input.kind === "mirror"
+            ? result.plan.input.value
+            : posix.normalize(posix.join(result.plan.dir, result.plan.input.value));
+
+      process.stdout.write(
+        [
+          "",
+          "Next:",
+          `  $EDITOR ${source}${" ".repeat(Math.max(1, 24 - source.length))}write the documentation`,
+          `  cd ${result.plan.dir} && npx docspack build   regenerate the payload`,
+          '  npx docspack preview "…"            see what an agent would receive',
+          "  npm publish                         when doctor is happy",
+          "",
+        ].join("\n"),
+      );
+      return 0;
+    }
+
+    case "doctor": {
+      const dir = values["package-dir"] ?? cwd;
+      const report = await runDoctor({
+        dir,
+        ...(values.strict === true ? { strict: true } : {}),
+      });
+
+      if (json) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        return report.ok ? 0 : 1;
+      }
+      reportDoctor(report, quiet);
+      return report.ok ? 0 : 1;
+    }
+
+    case "preview": {
+      const query = rest.join(" ");
+      if (query.length === 0) throw new DocspackError("Usage: docspack preview <query>");
+
+      const result = await previewPackage({
+        dir: values["package-dir"] ?? cwd,
+        query,
+        ...(() => {
+          const limit = integer(values.limit, "--limit");
+          return limit === undefined ? {} : { limit };
+        })(),
+        ...(() => {
+          const maxTokens = integer(values["max-tokens"], "--max-tokens");
+          return maxTokens === undefined ? {} : { maxTokens };
+        })(),
+      });
+
+      if (json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        return 0;
+      }
+      if (result.hits.length === 0) {
+        process.stdout.write(
+          `Nothing in this package matched "${query}" (${result.indexed} chunks indexed).\n`,
+        );
+        return 1;
+      }
+      for (const hit of result.hits) {
+        process.stdout.write(
+          `${bold(hit.chunkId)}  ${dim(`${hit.tokens} tokens · ${hit.filePath}`)}\n`,
+        );
+        for (const line of preview(hit.content, 4)) process.stdout.write(`  ${line}\n`);
+        process.stdout.write("\n");
+      }
+      process.stdout.write(
+        dim(
+          `${result.tokens} tokens across ${plural(result.hits.length, "chunk")} — what an agent would receive\n`,
+        ),
+      );
+      return 0;
+    }
+
+    case "sources": {
+      const { entries: registryEntries } = await import("@docspack/registry");
+      if (json) {
+        process.stdout.write(`${JSON.stringify(registryEntries, null, 2)}\n`);
+        return 0;
+      }
+      for (const entry of registryEntries) {
+        process.stdout.write(`${bold(entry.id)}  ${entry.name}\n  ${dim(entry.description)}\n`);
+      }
+      return 0;
+    }
+
+    default:
+      process.stderr.write(`${red("error")} unknown command "${command}"\n\n`);
+      process.stderr.write(HELP);
+      return 2;
+  }
+}
+
+silenceSqliteWarning();
+
+main(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error: unknown) => {
+    if (error instanceof DocspackError) {
+      process.stderr.write(`${red("error")} ${error.message}\n`);
+      if (error.hint !== undefined) process.stderr.write(`${error.hint}\n`);
+    } else {
+      process.stderr.write(
+        `${red("error")} ${error instanceof Error ? error.stack : String(error)}\n`,
+      );
+    }
+    process.exitCode = 1;
+  });