docspack 1.1.0 → 1.3.0

package/dist/sync.js

@@ -1,6 +1,8 @@
 import { readFile } from "node:fs/promises";
+import { relative } from "node:path";
 import { readArtifact } from "./artifact.js";
-import { discoverLibraries, discoverPackages } from "./discovery.js";
+import { COMMAND_ENTITY, commandChunks } from "./commands.js";
+import { discoverCommandLines, discoverLibraries, discoverPackages, } from "./discovery.js";
 import { chunkId, estimateTokens, resolveChunkFile } from "./spec.js";
 /**
  * Indexes every documentation package this project depends on. Packages already present in the
@@ -46,8 +48,104 @@ export async function syncProject(options) {
     }
     if (options.artifacts !== false)
         synced.push(...(await syncArtifacts(options)));
+    synced.push(...(await syncCommandLines(options, problems)));
     return { packages: synced, problems };
 }
+/**
+ * Indexes the command-line interface each installed library describes in its own `package.json`
+ * (`"cmdspec"`, `packages/cmdspec/SPEC.md` §13): one chunk per command, ranked like documentation
+ * and addressed by command path, for exactly the version installed.
+ *
+ * Not tied to `--no-artifacts`. That flag skips the declarations, which are many and machine-made;
+ * a CLI's description is one document its authors wrote, and leaving it out would make `ask` report
+ * the package as installed but not indexed on every question.
+ */
+async function syncCommandLines(options, problems) {
+    const commandLines = await discoverCommandLines(options.cwd);
+    if (commandLines.length === 0)
+        return [];
+    const synced = [];
+    for (const cli of commandLines) {
+        if (options.force !== true && options.store.hasPackage(cli.id)) {
+            synced.push({
+                id: cli.id,
+                name: cli.name,
+                version: cli.version,
+                chunks: options.store.countChunks(cli.id),
+                tokens: 0,
+                status: "cached",
+                trusted: true,
+                kind: "cli",
+            });
+            continue;
+        }
+        options.onProgress?.(`reading ${cli.id}`);
+        const { chunks, symbols } = await readCommandLine(cli, problems);
+        if (chunks.length === 0)
+            continue;
+        options.store.indexPackage({ id: cli.id, name: cli.name, version: cli.version, kind: "cli" }, chunks, symbols);
+        synced.push({
+            id: cli.id,
+            name: cli.name,
+            version: cli.version,
+            chunks: chunks.length,
+            tokens: chunks.reduce((total, chunk) => total + chunk.tokens, 0),
+            status: "indexed",
+            trusted: true,
+            kind: "cli",
+        });
+    }
+    return synced;
+}
+/**
+ * A library's CLI descriptions as chunks, and its command paths as names pointing at them.
+ *
+ * A description that is invalid, or that describes another version than the one installed, is
+ * reported and skipped: indexing it would answer with a command line the installed program does
+ * not accept, which is the one failure this tool exists to prevent.
+ */
+async function readCommandLine(cli, problems) {
+    const { readFile: readDocument } = await import("@docspack/cmdspec/read");
+    const chunks = [];
+    const symbols = new Map();
+    const taken = new Set();
+    for (const path of cli.documents) {
+        const where = relative(cli.dir, path);
+        let document;
+        try {
+            ({ document } = await readDocument(path));
+        }
+        catch (error) {
+            problems.push(`${cli.name}: ${where} ${error instanceof Error ? error.message : String(error)}`);
+            continue;
+        }
+        if (document.info.version !== cli.version) {
+            problems.push(`${cli.name}: ${where} describes version ${document.info.version}, but ${cli.version} is installed — not indexed`);
+            continue;
+        }
+        for (const chunk of commandChunks(document)) {
+            // Two executables in one package each have an overview called `cli`.
+            let id = chunk.id;
+            for (let suffix = 2; taken.has(id); suffix += 1)
+                id = `${chunk.id}-${suffix}`;
+            taken.add(id);
+            const content = `# ${chunk.title}\n\n${chunk.text}`;
+            const full = chunkId(cli.id, id);
+            chunks.push({
+                chunkId: full,
+                filePath: chunk.path === undefined ? where : `${where}#${chunk.path}`,
+                tokens: estimateTokens(content),
+                content,
+                tags: [...chunk.tags, ...chunk.entities],
+            });
+            for (const entity of chunk.entities) {
+                if (entity.startsWith(COMMAND_ENTITY))
+                    symbols.set(entity, full);
+            }
+        }
+    }
+    return { chunks, symbols };
+}
 /**
  * Indexes each installed library's exported declarations.
  *

package/dist/sync.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docspack",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Local, version-locked documentation packages for AI agents, indexed in SQLite and served over MCP.",
   "keywords": [
     "ai",
@@ -26,13 +26,15 @@
   "bin": {
     "docspack": "./bin/docspack.js"
   },
+  "cmdspec": "./dist/cmdspec.json",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
-    }
+    },
+    "./cmdspec.json": "./dist/cmdspec.json"
   },
   "files": [
     "bin",
@@ -45,8 +47,9 @@
     "node": ">=22.5.0"
   },
   "dependencies": {
-    "@docspack/lapis": "^0.2.0",
-    "@docspack/openapi": "^0.2.0",
+    "@docspack/cmdspec": "^0.1.0",
+    "@docspack/lapis": "^0.3.0",
+    "@docspack/openapi": "^0.2.1",
     "@docspack/registry": "^0.1.1",
     "@modelcontextprotocol/sdk": "1.30.0",
     "turndown": "7.2.4",
@@ -60,7 +63,7 @@
     "vitest": "4.1.10"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && node bin/docspack.js --cmdspec > dist/cmdspec.json",
     "check-types": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
     "test": "vitest run"
   }

package/src/build.ts

@@ -12,6 +12,7 @@ import {
   operationTitle,
 } from "@docspack/openapi";
 import { findEntry } from "@docspack/registry";
+import { commandChunks, commandFindings } from "./commands.js";
 import { readBuildConfig } from "./config.js";
 import { cleanDocument } from "./document.js";
 import { DocspackError } from "./errors.js";
@@ -41,6 +42,11 @@ export interface BuildOptions {
   readonly from?: string;
   /** OpenAPI document (JSON) to package, one chunk per operation. */
   readonly openapi?: string;
+  /**
+   * A command-line interface's description — cmdspec, or OpenCLI or Usage, converted — to package,
+   * one chunk per command.
+   */
+  readonly cmdspec?: string;
   /** Registry id or llms.txt URL to fetch and package. */
   readonly source?: string;
   /**
@@ -188,7 +194,10 @@ export async function buildPackage(input: BuildOptions): Promise<BuildResult> {
 async function withConfig(options: BuildOptions): Promise<BuildOptions> {
   const config = await readBuildConfig(options.out);
   const hasInput =
-    options.from !== undefined || options.openapi !== undefined || options.source !== undefined;
+    options.from !== undefined ||
+    options.openapi !== undefined ||
+    options.cmdspec !== undefined ||
+    options.source !== undefined;
 
   return {
     ...options,
@@ -199,6 +208,7 @@ async function withConfig(options: BuildOptions): Promise<BuildOptions> {
           // thinks about them; flags stay relative to the working directory.
           ...(config.from === undefined ? {} : { from: join(options.out, config.from) }),
           ...(config.openapi === undefined ? {} : { openapi: join(options.out, config.openapi) }),
+          ...(config.cmdspec === undefined ? {} : { cmdspec: join(options.out, config.cmdspec) }),
           ...(config.source === undefined ? {} : { source: config.source }),
         }),
     ...(options.maxChunkTokens === undefined && config.maxChunkTokens !== undefined
@@ -366,20 +376,34 @@ async function readStdin(): Promise<string> {
  */
 async function collect(options: BuildOptions, warnings: string[]): Promise<SourceDocument[]> {
   if (options.source !== undefined) {
-    if (options.from !== undefined || options.openapi !== undefined || options.json !== undefined) {
-      throw new DocspackError("A source cannot be combined with --from, --openapi or --from-json", {
-        hint: "A mirror is a whole documentation set on its own.",
-      });
+    if (
+      options.from !== undefined ||
+      options.openapi !== undefined ||
+      options.cmdspec !== undefined ||
+      options.json !== undefined
+    ) {
+      throw new DocspackError(
+        "A source cannot be combined with --from, --openapi, --cmdspec or --from-json",
+        {
+          hint: "A mirror is a whole documentation set on its own.",
+        },
+      );
     }
     return collectFromSource(options, warnings);
   }
 
   const documents: SourceDocument[] = [];
   if (options.openapi !== undefined) documents.push(...(await collectFromOpenApi(options.openapi)));
+  if (options.cmdspec !== undefined) {
+    documents.push(...(await collectFromCmdspec(options.cmdspec, warnings)));
+  }
   if (options.json !== undefined) documents.push(...(await collectFromJson(options.json)));
   // The default `docs/` directory is only read when nothing else was named: a build given only an
-  // OpenAPI document or a set of records should not fail on a `docs/` directory that does not exist.
-  if (options.from !== undefined || (options.openapi === undefined && options.json === undefined)) {
+  // API or CLI description, or a set of records, should not fail on a `docs/` directory that does
+  // not exist.
+  const named =
+    options.openapi !== undefined || options.cmdspec !== undefined || options.json !== undefined;
+  if (options.from !== undefined || !named) {
     documents.push(...(await collectFromDirectory(options.from ?? join(options.out, "docs"))));
   }
   return documents;
@@ -540,6 +564,61 @@ async function collectFromOpenApi(file: string): Promise<SourceDocument[]> {
   return documents;
 }
 
+/**
+ * One chunk per command, plus an overview listing them.
+ *
+ * Each command's chunk is `@docspack/cmdspec`'s digest — what a help page says, plus what it
+ * leaves out: types and defaults, where a value comes from, what the command changes, what it
+ * prints and what its exit status means — with the command's own prose before it, where the ranker
+ * reads it. The path is recorded as an entity, `$ git remote add`, so a question naming the command
+ * pins the chunk (`commands.ts`).
+ *
+ * The description must be valid. A package built from an invalid one would answer with a command
+ * line its program rejects, so the build stops and lists every problem instead.
+ */
+async function collectFromCmdspec(file: string, warnings: string[]): Promise<SourceDocument[]> {
+  const { convertText, readSource } = await import("@docspack/cmdspec/read");
+  const { validate } = await import("@docspack/cmdspec/validate");
+  const { CmdspecError } = await import("@docspack/cmdspec");
+  let document: Awaited<ReturnType<typeof convertText>>["document"];
+  try {
+    ({ document } = await convertText(await readSource(file), { where: file }));
+  } catch (error) {
+    if (error instanceof CmdspecError) {
+      throw new DocspackError(error.message, {
+        ...(error.hint === undefined ? {} : { hint: error.hint }),
+        cause: error,
+      });
+    }
+    throw error;
+  }
+
+  const result = validate(document);
+  if (!result.valid) {
+    throw new DocspackError(
+      `${file} is not a valid CLI description (${result.problems.length} problem${result.problems.length === 1 ? "" : "s"})`,
+      {
+        hint: [
+          ...result.problems.slice(0, 12).map((problem) => `${problem.at}: ${problem.message}`),
+          ...(result.problems.length > 12 ? [`…and ${result.problems.length - 12} more`] : []),
+          "Run `npx @docspack/cmdspec validate` on it for the full list.",
+        ].join("\n"),
+      },
+    );
+  }
+  warnings.push(...commandFindings(document).map((finding) => `${file}: ${finding.message}`));
+
+  return commandChunks(document).map((chunk) => ({
+    id: chunk.id,
+    title: chunk.title,
+    origin: chunk.path === undefined ? file : `${file}#${chunk.path}`,
+    text: chunk.text,
+    atomic: true,
+    tags: chunk.tags,
+    entities: chunk.entities,
+  }));
+}
+
 /** The reader's failures, re-reported as the CLI's own error so the hint survives. */
 async function readOpenApi(file: string): Promise<ApiDocument> {
   try {