docspack 0.0.1 → 0.1.1

package/src/init/run.ts

@@ -0,0 +1,142 @@
+import { join } from "node:path";
+import { type BuildResult, buildPackage } from "../build.js";
+import { type DoctorReport, runDoctor } from "../doctor.js";
+import { Prompter } from "../prompt.js";
+import { type Detected, detectProject } from "./detect.js";
+import { type InitOptions, type InitPlan, planInit, proposePackageName } from "./plan.js";
+import { applyPlan, type WrittenFile } from "./write.js";
+
+export interface RunInitOptions extends InitOptions {
+  readonly cwd: string;
+  /** Skip every prompt and use flags plus detected defaults. */
+  readonly yes?: boolean;
+  readonly dryRun?: boolean;
+  readonly force?: boolean;
+  /** Run the first build after scaffolding. Defaults to true. */
+  readonly build?: boolean;
+  readonly prompter?: Prompter;
+  readonly onProgress?: (message: string) => void;
+}
+
+export interface InitResult {
+  readonly detected: Detected;
+  readonly plan: InitPlan;
+  readonly written: readonly WrittenFile[];
+  readonly build?: BuildResult;
+  readonly doctor?: DoctorReport;
+  readonly cancelled: boolean;
+}
+
+/** detect → propose → confirm → write → build → doctor. */
+export async function runInit(options: RunInitOptions): Promise<InitResult> {
+  const detected = await detectProject(options.cwd);
+  const prompter = options.prompter ?? new Prompter();
+  const interactive = options.yes !== true && prompter.interactive;
+
+  const answers = interactive ? await ask(prompter, options, detected) : options;
+  const plan = planInit(answers, detected);
+
+  if (interactive) {
+    prompter.note("");
+    for (const note of plan.notes) prompter.note(`  · ${note}`);
+    prompter.note("");
+    if (!(await prompter.confirm(`Write ${plan.files.length} files to ${plan.dir}/?`))) {
+      prompter.close();
+      return { detected, plan, written: [], cancelled: true };
+    }
+    prompter.close();
+  }
+
+  const written = await applyPlan(options.cwd, plan, {
+    ...(options.force === undefined ? {} : { force: options.force }),
+    ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+  });
+
+  if (options.dryRun === true || options.build === false) {
+    return { detected, plan, written, cancelled: false };
+  }
+
+  const dir = join(options.cwd, plan.dir);
+  const built = await buildPackage({
+    out: dir,
+    ...(options.onProgress === undefined ? {} : { onProgress: options.onProgress }),
+  });
+  const doctor = await runDoctor({ dir });
+
+  return { detected, plan, written, build: built, doctor, cancelled: false };
+}
+
+async function ask(
+  prompter: Prompter,
+  options: RunInitOptions,
+  detected: Detected,
+): Promise<InitOptions> {
+  const community = options.community === true;
+  const proposed =
+    options.name ??
+    (detected.libraryName === undefined ? undefined : proposePackageName(detected, community));
+
+  if (detected.libraryName !== undefined) {
+    const where = [
+      `${detected.libraryName}${detected.libraryVersion === undefined ? "" : `@${detected.libraryVersion}`}`,
+      detected.docsDir === undefined
+        ? undefined
+        : `${detected.docsDir}/ (${detected.docsFiles} files)`,
+      detected.openapi,
+    ].filter((part): part is string => part !== undefined);
+    prompter.note(`Detected  ${where.join(" · ")}\n`);
+  }
+
+  const name = await prompter.text("Package name", proposed ?? "@acme/docspack");
+  const version = await prompter.text(
+    "Version",
+    options.version ?? detected.libraryVersion ?? "0.1.0",
+  );
+
+  const input = await selectInput(prompter, options, detected);
+  const out = await prompter.text("Directory", options.out ?? "docspack");
+  const workflow = await prompter.confirm("Add the release workflow?", options.workflow !== false);
+
+  return {
+    ...options,
+    name,
+    version,
+    out,
+    workflow,
+    ...input,
+  };
+}
+
+async function selectInput(
+  prompter: Prompter,
+  options: RunInitOptions,
+  detected: Detected,
+): Promise<Pick<InitOptions, "from" | "openapi" | "mirror">> {
+  if (options.from !== undefined) return { from: options.from };
+  if (options.openapi !== undefined) return { openapi: options.openapi };
+  if (options.mirror !== undefined) return { mirror: options.mirror };
+
+  const choices: {
+    value: Pick<InitOptions, "from" | "openapi" | "mirror">;
+    label: string;
+    hint?: string;
+  }[] = [];
+  if (detected.docsDir !== undefined) {
+    choices.push({
+      value: { from: detected.docsDir },
+      label: `${detected.docsDir}/`,
+      hint: `${detected.docsFiles} Markdown files`,
+    });
+  }
+  if (detected.openapi !== undefined) {
+    choices.push({
+      value: { openapi: detected.openapi },
+      label: detected.openapi,
+      hint: "one chunk per operation",
+    });
+  }
+  choices.push({ value: {}, label: "start from templates", hint: "seeds docs/ with three files" });
+
+  if (choices.length === 1) return {};
+  return prompter.select("Documentation source", choices);
+}

package/src/init/templates.ts

@@ -0,0 +1,200 @@
+import { CONFIG_KEY } from "../config.js";
+import { AGENTS_SNIPPET, FEEDBACK_SNIPPET } from "../snippet.js";
+import { LLMS_DIR } from "../spec.js";
+
+export interface PackageJsonInput {
+  readonly name: string;
+  readonly version: string;
+  readonly libraryName?: string;
+  readonly repository?: string;
+  readonly license?: string;
+  readonly build: Record<string, string | number>;
+  readonly docspackVersion: string;
+}
+
+/** Marker the doctor looks for, so a half-filled template cannot be published as documentation. */
+export const PLACEHOLDER = "TODO:";
+
+export function packageJson(input: PackageJsonInput): string {
+  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: string, libraryName: string | undefined): string {
+  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(): string {
+  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: string): { path: string; contents: string }[] {
+  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: string, buildArgs: string): string {
+  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 }}
+`;
+}

package/src/init/write.ts

@@ -0,0 +1,83 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, relative, resolve, sep } from "node:path";
+import { DocspackError } from "../errors.js";
+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 async function applyPlan(
+  cwd: string,
+  plan: InitPlan,
+  options: ApplyOptions = {},
+): Promise<WrittenFile[]> {
+  const root = resolve(cwd, plan.dir);
+  const results: WrittenFile[] = [];
+
+  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: InitPlan, written?: readonly WrittenFile[]): string {
+  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: string): Promise<string | undefined> {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}

package/src/kinds.ts

@@ -0,0 +1,17 @@
+/**
+ * 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"] as const;
+
+export type FindingKind = (typeof KINDS)[number];
+
+export function isFindingKind(value: unknown): value is FindingKind {
+  return typeof value === "string" && (KINDS as readonly string[]).includes(value);
+}

package/src/llms-txt.ts

@@ -0,0 +1,116 @@
+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[];
+}
+
+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: string): LlmsTxtDocument {
+  const lines = text.replace(/^/, "").replace(/\r\n/g, "\n").split("\n");
+
+  let title: string | undefined;
+  const summaryLines: string[] = [];
+  let summaryClosed = false;
+  let inFence = false;
+  let heading = PREAMBLE;
+
+  const sections = new Map<string, LlmsTxtLink[]>();
+  const links: LlmsTxtLink[] = [];
+
+  const push = (link: LlmsTxtLink): void => {
+    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: LlmsTxtDocument): readonly LlmsTxtLink[] {
+  const seen = new Set<string>();
+  const result: LlmsTxtLink[] = [];
+  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;
+}