@takazudo/zudo-doc 0.1.0

package/dist/integrations/claude-resources/generate.js

@@ -0,0 +1,404 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { escapeForMdx } from "./escape-for-mdx.js";
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+function cleanDir(dir) {
+  if (!fs.existsSync(dir)) return;
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+function parseFrontmatter(content) {
+  try {
+    return matter(content);
+  } catch {
+    return null;
+  }
+}
+function escapeTitle(s) {
+  return s.replace(/"/g, '\\"');
+}
+function listFiles(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true }).filter((d) => d.isFile()).map((d) => d.name).sort();
+}
+function writeCategoryMeta(outputDir, label, position, description, noPage = true) {
+  const meta = { label, position, description };
+  if (noPage) meta.noPage = true;
+  fs.writeFileSync(
+    path.join(outputDir, "_category_.json"),
+    JSON.stringify(meta, null, 2) + "\n"
+  );
+}
+function findClaudeMdFiles(dir, excludeDirs) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  for (const item of fs.readdirSync(dir)) {
+    if (item === "node_modules") continue;
+    if (item.startsWith(".")) continue;
+    const itemPath = path.join(dir, item);
+    if (excludeDirs.some((d) => itemPath.startsWith(d))) continue;
+    let stat;
+    try {
+      stat = fs.lstatSync(itemPath);
+    } catch {
+      continue;
+    }
+    if (stat.isDirectory()) {
+      results.push(...findClaudeMdFiles(itemPath, excludeDirs));
+    } else if (stat.isFile() && item === "CLAUDE.md") {
+      results.push(itemPath);
+    }
+  }
+  return results;
+}
+function generateClaudemdDocs(config) {
+  const projectRoot = config.projectRoot ?? path.dirname(config.claudeDir);
+  const outputDir = path.join(config.docsDir, "claude-md");
+  cleanDir(outputDir);
+  const excludeDirs = [
+    path.join(projectRoot, ".git"),
+    path.join(projectRoot, "node_modules"),
+    path.join(projectRoot, "worktrees"),
+    path.join(projectRoot, "dist"),
+    path.join(projectRoot, "out"),
+    path.join(projectRoot, "public"),
+    path.join(projectRoot, "__inbox"),
+    path.join(projectRoot, "test-results"),
+    path.join(projectRoot, "e2e", "fixtures"),
+    path.join(config.docsDir)
+  ];
+  const files = findClaudeMdFiles(projectRoot, excludeDirs);
+  if (files.length === 0) return [];
+  ensureDir(outputDir);
+  const items = [];
+  for (const filePath of files) {
+    const content = fs.readFileSync(filePath, "utf8");
+    const relPath = path.relative(projectRoot, filePath);
+    const displayPath = `/${relPath}`;
+    const dirPart = path.dirname(relPath);
+    const slug = dirPart === "." ? "root" : dirPart.replace(/\//g, "--");
+    items.push({ displayPath, slug, relPath });
+    const pos = items.length + 1;
+    const mdx = `---
+title: "${escapeTitle(displayPath)}"
+description: "CLAUDE.md at ${escapeTitle(displayPath)}"
+sidebar_position: ${pos}
+sidebar_label: "${escapeTitle(relPath)}"
+generated: true
+---
+
+**Path:** \`${relPath}\`
+
+${escapeForMdx(content.trim())}
+`;
+    fs.writeFileSync(path.join(outputDir, `${slug}.mdx`), mdx);
+  }
+  items.sort((a, b) => {
+    if (a.slug === "root") return -1;
+    if (b.slug === "root") return 1;
+    return a.displayPath.localeCompare(b.displayPath);
+  });
+  writeCategoryMeta(outputDir, "CLAUDE.md", 900, "Project-specific instructions");
+  return items;
+}
+function generateCommandsDocs(config) {
+  const commandsDir = path.join(config.claudeDir, "commands");
+  const outputDir = path.join(config.docsDir, "claude-commands");
+  cleanDir(outputDir);
+  if (!fs.existsSync(commandsDir)) return [];
+  const files = fs.readdirSync(commandsDir).filter((f) => f.endsWith(".md"));
+  if (files.length === 0) return [];
+  ensureDir(outputDir);
+  const items = [];
+  for (const file of files) {
+    const content = fs.readFileSync(path.join(commandsDir, file), "utf8");
+    const parsed = parseFrontmatter(content);
+    if (!parsed) continue;
+    const name = file.replace(/\.md$/, "");
+    const description = parsed.data.description || "";
+    items.push({ name, description });
+    const mdx = `---
+title: "${escapeTitle(name)}"
+description: "${escapeTitle(description)}"
+sidebar_label: "${escapeTitle(name)}"
+generated: true
+---
+
+${escapeForMdx(parsed.content.trim())}
+`;
+    fs.writeFileSync(path.join(outputDir, `${name}.mdx`), mdx);
+  }
+  items.sort((a, b) => a.name.localeCompare(b.name));
+  writeCategoryMeta(outputDir, "Commands", 901, "Custom slash commands");
+  return items;
+}
+function getSkillFileTree(skillDir, subDirs) {
+  const lines = [`${skillDir}/`];
+  const entries = [{ isDir: false, name: "SKILL.md" }];
+  for (const sub of subDirs) {
+    entries.push({ isDir: true, name: sub.name, children: sub.files });
+  }
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const isLast = i === entries.length - 1;
+    const prefix = isLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+    if (!entry.isDir) {
+      lines.push(`${prefix}${entry.name}`);
+    } else {
+      lines.push(`${prefix}${entry.name}/`);
+      for (let j = 0; j < entry.children.length; j++) {
+        const child = entry.children[j];
+        const childIsLast = j === entry.children.length - 1;
+        const continuation = isLast ? "    " : "\u2502   ";
+        const childPrefix = childIsLast ? "\u2514\u2500\u2500 " : "\u251C\u2500\u2500 ";
+        lines.push(`${continuation}${childPrefix}${child}`);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function getScriptDescription(filePath) {
+  try {
+    const topLines = fs.readFileSync(filePath, "utf8").split("\n", 2);
+    const commentLine = topLines[0].startsWith("#!") ? topLines[1] || "" : topLines[0];
+    const match = commentLine.match(/^(?:#|\/\/)\s*(.+)/);
+    return match ? ` \u2014 ${match[1]}` : "";
+  } catch {
+    return "";
+  }
+}
+function getSkillReferences(skillsDir, skillDir) {
+  const refsDir = path.join(skillsDir, skillDir, "references");
+  if (!fs.existsSync(refsDir)) return [];
+  return fs.readdirSync(refsDir).filter((f) => f.endsWith(".md")).map((f) => {
+    const content = fs.readFileSync(path.join(refsDir, f), "utf8");
+    const name = f.replace(/\.md$/, "");
+    const h1Match = content.match(/^#\s+(.+)$/m);
+    const title = h1Match ? h1Match[1] : name;
+    return { name, title, content };
+  }).sort((a, b) => a.name.localeCompare(b.name));
+}
+function generateSkillsDocs(config) {
+  const skillsDir = path.join(config.claudeDir, "skills");
+  const outputDir = path.join(config.docsDir, "claude-skills");
+  cleanDir(outputDir);
+  if (!fs.existsSync(skillsDir)) return [];
+  const dirs = fs.readdirSync(skillsDir).filter((d) => {
+    const skillPath = path.join(skillsDir, d);
+    return fs.statSync(skillPath).isDirectory() && fs.existsSync(path.join(skillPath, "SKILL.md"));
+  });
+  if (dirs.length === 0) return [];
+  ensureDir(outputDir);
+  const items = [];
+  for (const dir of dirs) {
+    const content = fs.readFileSync(
+      path.join(skillsDir, dir, "SKILL.md"),
+      "utf8"
+    );
+    const parsed = parseFrontmatter(content);
+    if (!parsed) continue;
+    const name = parsed.data.name || dir;
+    const description = parsed.data.description || "";
+    const references = getSkillReferences(skillsDir, dir);
+    items.push({ name, dir, description, references });
+    const scriptFiles = listFiles(path.join(skillsDir, dir, "scripts"));
+    const assetFiles = listFiles(path.join(skillsDir, dir, "assets"));
+    const refFiles = references.map((r) => `${r.name}.md`);
+    const subDirs = [];
+    if (scriptFiles.length > 0) subDirs.push({ name: "scripts", files: scriptFiles });
+    if (refFiles.length > 0) subDirs.push({ name: "references", files: refFiles });
+    if (assetFiles.length > 0) subDirs.push({ name: "assets", files: assetFiles });
+    let fileStructureSection = "";
+    if (subDirs.length > 0) {
+      const tree = `\`\`\`
+${getSkillFileTree(dir, subDirs)}
+\`\`\``;
+      const links = [];
+      for (const ref of references) {
+        links.push(`- [references/${ref.name}.md](./ref-${ref.name})`);
+      }
+      for (const f of scriptFiles.filter((s) => s.endsWith(".md"))) {
+        const slug = f.replace(/\.md$/, "");
+        links.push(`- [scripts/${f}](./script-${slug})`);
+      }
+      for (const f of assetFiles.filter((a) => a.endsWith(".md"))) {
+        const slug = f.replace(/\.md$/, "");
+        links.push(`- [assets/${f}](./asset-${slug})`);
+      }
+      const linkList = links.length > 0 ? `
+
+${links.join("\n")}` : "";
+      fileStructureSection = `## File Structure
+
+${tree}${linkList}`;
+    }
+    const shortDesc = description.length > 200 ? description.substring(0, 200) + "..." : description;
+    let skillBody = parsed.content.trim();
+    skillBody = skillBody.replace(/\]\(references\/([^)]+)\.md\)/g, "](./ref-$1)").replace(/\]\(scripts\/([^)]+)\.md\)/g, "](./script-$1)").replace(/\]\(assets\/([^)]+)\.md\)/g, "](./asset-$1)");
+    const body = [
+      fileStructureSection,
+      escapeForMdx(skillBody)
+    ].filter(Boolean).join("\n\n");
+    const mdx = `---
+title: "${escapeTitle(name)}"
+description: "${escapeTitle(shortDesc)}"
+sidebar_label: "${escapeTitle(name)}"
+generated: true
+---
+
+${body}`;
+    fs.writeFileSync(path.join(outputDir, `${dir}.mdx`), mdx);
+    const skillSlugBase = `claude-skills/${dir}`;
+    for (const ref of references) {
+      const subSlug = `${skillSlugBase}/ref-${ref.name}`;
+      const refMdx = `---
+title: "${escapeTitle(ref.title)}"
+slug: "${subSlug}"
+unlisted: true
+generated: true
+---
+
+${escapeForMdx(ref.content.trim())}
+`;
+      fs.writeFileSync(path.join(outputDir, `${dir}--ref-${ref.name}.mdx`), refMdx);
+    }
+    for (const f of scriptFiles.filter((s) => s.endsWith(".md"))) {
+      const slug = f.replace(/\.md$/, "");
+      const subSlug = `${skillSlugBase}/script-${slug}`;
+      const raw = fs.readFileSync(
+        path.join(skillsDir, dir, "scripts", f),
+        "utf8"
+      );
+      const h1Match = raw.match(/^#\s+(.+)$/m);
+      const title = h1Match ? h1Match[1] : slug;
+      fs.writeFileSync(
+        path.join(outputDir, `${dir}--script-${slug}.mdx`),
+        `---
+title: "${escapeTitle(title)}"
+slug: "${subSlug}"
+unlisted: true
+generated: true
+---
+
+${escapeForMdx(raw.trim())}
+`
+      );
+    }
+    for (const f of assetFiles.filter((a) => a.endsWith(".md"))) {
+      const slug = f.replace(/\.md$/, "");
+      const subSlug = `${skillSlugBase}/asset-${slug}`;
+      const raw = fs.readFileSync(
+        path.join(skillsDir, dir, "assets", f),
+        "utf8"
+      );
+      const h1Match = raw.match(/^#\s+(.+)$/m);
+      const title = h1Match ? h1Match[1] : slug;
+      fs.writeFileSync(
+        path.join(outputDir, `${dir}--asset-${slug}.mdx`),
+        `---
+title: "${escapeTitle(title)}"
+slug: "${subSlug}"
+unlisted: true
+generated: true
+---
+
+${escapeForMdx(raw.trim())}
+`
+      );
+    }
+  }
+  items.sort((a, b) => a.name.localeCompare(b.name));
+  writeCategoryMeta(outputDir, "Skills", 902, "Skill packages");
+  return items;
+}
+function generateAgentsDocs(config) {
+  const agentsDir = path.join(config.claudeDir, "agents");
+  const outputDir = path.join(config.docsDir, "claude-agents");
+  cleanDir(outputDir);
+  if (!fs.existsSync(agentsDir)) return [];
+  const files = fs.readdirSync(agentsDir).filter((f) => f.endsWith(".md"));
+  if (files.length === 0) return [];
+  ensureDir(outputDir);
+  const items = [];
+  for (const file of files) {
+    const content = fs.readFileSync(path.join(agentsDir, file), "utf8");
+    const parsed = parseFrontmatter(content);
+    if (!parsed) continue;
+    const name = parsed.data.name || file.replace(/\.md$/, "");
+    const description = parsed.data.description || "";
+    const model = parsed.data.model || "";
+    const fileSlug = file.replace(/\.md$/, "");
+    items.push({ name, file: fileSlug, description, model });
+    const modelBadge = model ? `**Model:** \`${model}\`
+` : "";
+    const mdx = `---
+title: "${escapeTitle(name)}"
+description: "${escapeTitle(description)}"
+sidebar_label: "${escapeTitle(name)}"
+generated: true
+---
+
+${modelBadge}
+${escapeForMdx(parsed.content.trim())}
+`;
+    fs.writeFileSync(path.join(outputDir, `${fileSlug}.mdx`), mdx);
+  }
+  items.sort((a, b) => a.name.localeCompare(b.name));
+  writeCategoryMeta(outputDir, "Agents", 903, "Custom subagents");
+  return items;
+}
+function generateOverviewIndex(config, {
+  hasCommands,
+  hasSkills,
+  hasAgents,
+  hasClaudemd
+}) {
+  const outputDir = path.join(config.docsDir, "claude");
+  cleanDir(outputDir);
+  ensureDir(outputDir);
+  const categorySlugs = [];
+  if (hasClaudemd) categorySlugs.push("claude-md");
+  if (hasSkills) categorySlugs.push("claude-skills");
+  if (hasAgents) categorySlugs.push("claude-agents");
+  if (hasCommands) categorySlugs.push("claude-commands");
+  const categoriesAttr = JSON.stringify(categorySlugs);
+  const index = `---
+title: "Claude"
+description: "Claude Code configuration reference."
+sidebar_position: 899
+generated: true
+---
+
+Claude Code configuration reference.
+
+## Resources
+
+<CategoryNav categories={${categoriesAttr}} />
+`;
+  fs.writeFileSync(path.join(outputDir, "index.mdx"), index);
+}
+function generateClaudeResourcesDocs(config) {
+  const claudemds = generateClaudemdDocs(config);
+  const commands = generateCommandsDocs(config);
+  const skills = generateSkillsDocs(config);
+  const agents = generateAgentsDocs(config);
+  generateOverviewIndex(config, {
+    hasClaudemd: claudemds.length > 0,
+    hasCommands: commands.length > 0,
+    hasSkills: skills.length > 0,
+    hasAgents: agents.length > 0
+  });
+  return {
+    claudemd: claudemds.length,
+    commands: commands.length,
+    skills: skills.length,
+    agents: agents.length
+  };
+}
+export {
+  generateClaudeResourcesDocs
+};

package/dist/integrations/claude-resources/index.d.ts

@@ -0,0 +1,46 @@
+import { generateClaudeResourcesDocs } from './generate.js';
+export { ClaudeResourcesConfig } from './generate.js';
+
+interface ZfbPluginConfig {
+    name: string;
+    options?: Record<string, unknown>;
+}
+declare const CLAUDE_RESOURCES_PLUGIN_NAME = "@takazudo/zudo-doc-claude-resources";
+/** Options accepted by both the plugin entry and the imperative runner. */
+interface ClaudeResourcesPluginOptions {
+    /**
+     * Path to the project's `.claude/` directory holding `commands/`,
+     * `skills/`, `agents/`. Resolved against `projectRoot` when relative.
+     */
+    claudeDir: string;
+    /**
+     * Project root used both as the search root for `CLAUDE.md` discovery
+     * and to anchor relative paths. Defaults to `process.cwd()`.
+     */
+    projectRoot?: string;
+    /**
+     * Output directory for generated MDX pages, resolved against
+     * `projectRoot` when relative. Defaults to `src/content/docs` to
+     * match the existing Astro integration's behaviour.
+     */
+    docsDir?: string;
+}
+/**
+ * Declarative plugin entry for `zfb.config.ts`. Returns the
+ * `{ name, options }` shape that zfb's plugins array consumes.
+ *
+ * v0 note: zfb does not yet invoke plugin lifecycles, so registering the
+ * plugin alone does not run generation today. Pair it with a call to
+ * `runClaudeResourcesPreStep` from a `prebuild`-style script until the
+ * lifecycle hook lands. The plugin entry itself is forward-compatible.
+ */
+declare function claudeResourcesPlugin(options: ClaudeResourcesPluginOptions): ZfbPluginConfig;
+/**
+ * Imperative pre-step runner. Resolves relative paths against
+ * `projectRoot` (defaults to `process.cwd()`) and invokes the underlying
+ * generator. Output is byte-equivalent to the Astro integration when
+ * given the same inputs.
+ */
+declare function runClaudeResourcesPreStep(options: ClaudeResourcesPluginOptions): ReturnType<typeof generateClaudeResourcesDocs>;
+
+export { CLAUDE_RESOURCES_PLUGIN_NAME, type ClaudeResourcesPluginOptions, type ZfbPluginConfig, claudeResourcesPlugin, generateClaudeResourcesDocs, runClaudeResourcesPreStep };

package/dist/integrations/claude-resources/index.js

@@ -0,0 +1,24 @@
+import path from "node:path";
+import {
+  generateClaudeResourcesDocs
+} from "./generate.js";
+const CLAUDE_RESOURCES_PLUGIN_NAME = "@takazudo/zudo-doc-claude-resources";
+function claudeResourcesPlugin(options) {
+  return {
+    name: CLAUDE_RESOURCES_PLUGIN_NAME,
+    options: { ...options }
+  };
+}
+function runClaudeResourcesPreStep(options) {
+  const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
+  const claudeDir = path.isAbsolute(options.claudeDir) ? options.claudeDir : path.resolve(projectRoot, options.claudeDir);
+  const docsDirInput = options.docsDir ?? "src/content/docs";
+  const docsDir = path.isAbsolute(docsDirInput) ? docsDirInput : path.resolve(projectRoot, docsDirInput);
+  return generateClaudeResourcesDocs({ claudeDir, projectRoot, docsDir });
+}
+export {
+  CLAUDE_RESOURCES_PLUGIN_NAME,
+  claudeResourcesPlugin,
+  generateClaudeResourcesDocs,
+  runClaudeResourcesPreStep
+};

package/dist/integrations/doc-history/index.d.ts

@@ -0,0 +1,137 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+export { DocHistoryMetaEntry, DocHistoryMetaLocaleConfig, DocHistoryMetaManifest, DocHistoryMetaVersionConfig, RunDocHistoryMetaOptions, runDocHistoryMetaStep } from './pre-build.js';
+
+/** A single non-default locale entry; mirrors `settings.locales[*]`. */
+interface DocHistoryLocaleConfig {
+    /** Absolute or project-relative directory holding this locale's MDX content. */
+    dir: string;
+}
+/** Build-time + dev-time options for the doc-history integration. */
+interface DocHistoryOptions {
+    /** Default-locale content directory (e.g. `src/content/docs`). */
+    docsDir: string;
+    /** Optional non-default locales, keyed by locale code (e.g. `{ ja: { dir: "src/content/docs-ja" } }`). */
+    locales?: Record<string, DocHistoryLocaleConfig>;
+    /**
+     * Port the standalone `@takazudo/zudo-doc-history-server` listens on.
+     * Defaults to `4322` to match the server's CLI default. Only used by
+     * the dev proxy.
+     */
+    serverPort?: number;
+    /**
+     * Maximum number of git history entries to record per file. Defaults
+     * to `50`, matching `@takazudo/zudo-doc-history-server`'s CLI default.
+     * Only used by the post-build hook.
+     */
+    maxEntries?: number;
+}
+/** zfb v0 plugin descriptor — mirrors `PluginConfig` in `zfb/config`. */
+interface DocHistoryPluginDescriptor {
+    /** Stable plugin id used by the future zfb plugin runtime to dispatch hooks. */
+    name: "doc-history";
+    /** Options forwarded verbatim into the zfb config; must be JSON-serialisable. */
+    options: DocHistoryOptions;
+}
+/** Default doc-history-server port — matches `@takazudo/zudo-doc-history-server`. */
+declare const DEFAULT_SERVER_PORT = 4322;
+/** Default git history depth — matches `@takazudo/zudo-doc-history-server`. */
+declare const DEFAULT_MAX_ENTRIES = 50;
+/** Public route prefix the dev middleware and the standalone server agree on. */
+declare const DOC_HISTORY_ROUTE_PREFIX = "/doc-history/";
+/** Subdirectory within the build output that receives the generated JSON files. */
+declare const DOC_HISTORY_OUTPUT_DIRNAME = "doc-history";
+/** CLI bin name exposed by `@takazudo/zudo-doc-history-server` for inline generation. */
+declare const DOC_HISTORY_GENERATE_BIN = "doc-history-generate";
+/**
+ * Build the zfb config-side descriptor. Add the return value to the
+ * `plugins: [...]` array in `zfb.config.ts`.
+ *
+ * The shape is intentionally limited to `{ name, options }` because
+ * that is the only thing today's zfb config loader consumes (see the
+ * Rust `PluginConfig` struct in zfb's `config.rs`). Runtime wiring is
+ * done through the sibling helpers in this module.
+ */
+declare function docHistoryPlugin(options: DocHistoryOptions): DocHistoryPluginDescriptor;
+/** Connect-style middleware signature — works as a Vite plugin middleware. */
+type ConnectMiddleware = (req: IncomingMessage, res: ServerResponse, next: (err?: unknown) => void) => void;
+/** Minimal logger surface used by the middleware on proxy failure. */
+interface MiddlewareLogger {
+    warn(msg: string): void;
+}
+/**
+ * Connect-style middleware that proxies any URL containing
+ * `/doc-history/` to the standalone `@takazudo/zudo-doc-history-server`.
+ * Behaviour matches the legacy Astro integration byte-for-byte:
+ *
+ *   - request URLs without the `/doc-history/` segment fall through
+ *     to `next()` unchanged,
+ *   - the path slice from `/doc-history/` onward is preserved (so a
+ *     site `base` prefix like `/docs/doc-history/foo.json` still
+ *     reaches the right server route),
+ *   - a successful upstream response copies status + content-type and
+ *     streams the body as text,
+ *   - on upstream failure the proxy returns `502 application/json`
+ *     with a stable error envelope so the client island can render a
+ *     graceful empty state.
+ */
+declare function createDocHistoryDevMiddleware(options: DocHistoryOptions, logger?: MiddlewareLogger): ConnectMiddleware;
+/** Minimal logger surface used by the post-build hook. */
+interface PostBuildLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+}
+/** Invocation context for the post-build hook. */
+interface PostBuildContext {
+    /** Absolute path to the build output directory (zfb `outDir`). */
+    outDir: string;
+    /** Optional logger; falls back to silent no-ops when omitted. */
+    logger?: PostBuildLogger;
+}
+/**
+ * Post-build hook. Spawns the `doc-history-generate` CLI from
+ * `@takazudo/zudo-doc-history-server` to write per-page git history JSON
+ * files into `<outDir>/doc-history/`.
+ *
+ * Returns early when `SKIP_DOC_HISTORY=1` is set in the environment;
+ * the CI `build-history` job uses that flag because it generates the
+ * same output as a separate parallel artifact. Local `pnpm build`
+ * runs leave the flag unset so the inline path is taken.
+ *
+ * The CLI is spawned through the platform shell so that the
+ * `node_modules/.bin/doc-history-generate` symlink (created by pnpm /
+ * npm at install time) resolves naturally. Output is inherited so
+ * progress and warnings surface in the user's terminal exactly as
+ * they do in CI.
+ */
+declare function runDocHistoryPostBuild(options: DocHistoryOptions, ctx: PostBuildContext): Promise<void>;
+/**
+ * Build the argv passed to `doc-history-generate`. Exposed for unit
+ * tests; the CLI surface is documented in
+ * `packages/doc-history-server/src/args.ts`.
+ */
+declare function buildGenerateCliArgs(options: DocHistoryOptions, outDir: string): string[];
+/**
+ * Resolve the absolute path of the `doc-history-generate` script
+ * shipped by `@takazudo/zudo-doc-history-server`.
+ *
+ * Reading `bin` out of the dependency's `package.json` and joining it
+ * to that file's directory avoids two pitfalls:
+ *
+ *   1. **Shell injection.** Spawning the CLI as
+ *      `spawn(node, [absoluteCliPath, ...flagArgs], { shell: false })`
+ *      means CLI flag values (which may include user-controlled
+ *      content directory paths) are never interpolated into a shell
+ *      command line.
+ *   2. **PATH ambiguity.** Resolving via `node_modules/.bin` only
+ *      works when that directory is on `PATH`, which depends on how
+ *      the build is invoked. Reading the package's own `bin` map
+ *      eliminates the dependency on shell PATH lookup.
+ *
+ * `package.json` is reachable via `require.resolve` regardless of
+ * the package's `exports` field (the spec carves out `./package.json`
+ * unconditionally), so this is safe even if the package later
+ * tightens its exports surface.
+ */
+declare function resolveDocHistoryGenerateBin(): string;
+
+export { type ConnectMiddleware, DEFAULT_MAX_ENTRIES, DEFAULT_SERVER_PORT, DOC_HISTORY_GENERATE_BIN, DOC_HISTORY_OUTPUT_DIRNAME, DOC_HISTORY_ROUTE_PREFIX, type DocHistoryLocaleConfig, type DocHistoryOptions, type DocHistoryPluginDescriptor, type MiddlewareLogger, type PostBuildContext, type PostBuildLogger, buildGenerateCliArgs, createDocHistoryDevMiddleware, docHistoryPlugin, resolveDocHistoryGenerateBin, runDocHistoryPostBuild };