@yansirplus/cli 0.5.17

package/dist/generate/generate-agent-docs.mjs

@@ -0,0 +1,435 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import {
+  checkProjectionSink,
+  defineProjectionSpec,
+  runProjectionSink,
+} from "../lib/projection-sink.mjs";
+import { collectAgentDocsModel } from "../lib/agent-docs-model.mjs";
+import { buildCapabilityRouteProjection } from "../lib/capability-routes.mjs";
+
+const root = process.cwd();
+const check = process.argv.includes("--check");
+const failures = [];
+
+const abs = (file) => path.join(root, file);
+const exists = (file) => fs.existsSync(abs(file));
+const read = (file) => fs.readFileSync(abs(file), "utf8");
+
+const generatedNotice = (source) =>
+  `<!-- generated by packages/cli/src/generate/generate-agent-docs.mjs; edit ${source} -->`;
+
+const agentDocsSourceFacts = {
+  kind: "source-set",
+  ref: "docs.generate-agent-docs.source-facts",
+  sources: [
+    { kind: "directory", ref: "docs/agent/*.source.json" },
+    { kind: "file", ref: "docs/surface.json" },
+    { kind: "directory", ref: "packages/*/package.json" },
+    { kind: "tsdoc", ref: "exported @agentosPrimitive tags" },
+  ],
+};
+
+const fileProjection = (file) =>
+  defineProjectionSpec({
+    id: `docs.generate-agent-docs:${file}`,
+    version: 1,
+    source: agentDocsSourceFacts,
+    project: (expected, ctx) => ctx.ok(expected),
+  });
+
+const fileSink = (file) => {
+  const target = abs(file);
+  return {
+    id: file,
+    read: () =>
+      fs.existsSync(target)
+        ? { _tag: "found", output: fs.readFileSync(target, "utf8") }
+        : { _tag: "missing" },
+    write: (output) => {
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, output);
+    },
+    equals: (actual, expected) => actual === expected,
+  };
+};
+
+const formatGeneratedText = (file, text) => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-docs-"));
+  const tmpFile = path.join(tmpDir, path.basename(file));
+  try {
+    fs.writeFileSync(tmpFile, `${text.replace(/\s+$/u, "")}\n`);
+    const result = spawnSync("vp", ["fmt", tmpFile, "--write"], {
+      cwd: root,
+      encoding: "utf8",
+    });
+    if (result.status !== 0) {
+      failures.push(
+        `${file} failed generated formatting: ${result.stderr || result.stdout || result.status}`,
+      );
+      return `${text.replace(/\s+$/u, "")}\n`;
+    }
+    return fs.readFileSync(tmpFile, "utf8");
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+};
+
+const write = async (file, text) => {
+  const expected = formatGeneratedText(file, text);
+  const spec = fileProjection(file);
+  const sink = fileSink(file);
+  if (check) {
+    const result = await checkProjectionSink(spec, expected, sink);
+    if (result._tag === "projection_failed") {
+      failures.push(`${file} projection failed: ${result.result.reason}`);
+    } else if (result._tag === "stale") {
+      failures.push(`${file} is stale`);
+    }
+    return;
+  }
+  const result = await runProjectionSink(spec, expected, sink);
+  if (result._tag === "projection_failed") {
+    failures.push(`${file} projection failed: ${result.result.reason}`);
+  }
+};
+
+const writeJson = async (file, value) => write(file, JSON.stringify(value, null, 2));
+
+const replaceGeneratedBlock = async ({ file, startMarker, endMarker, block, insertBefore }) => {
+  const current = exists(file) ? read(file) : "";
+  const startIndex = current.indexOf(startMarker);
+  const endIndex = current.indexOf(endMarker);
+  const normalizedBlock = block.replace(/\s+$/u, "");
+  let next;
+
+  if ((startIndex === -1) !== (endIndex === -1)) {
+    failures.push(`${file} has incomplete generated block markers`);
+    return;
+  }
+
+  if (startIndex >= 0 && endIndex > startIndex) {
+    const endLineIndex = current.indexOf("\n", endIndex);
+    let afterIndex = endLineIndex === -1 ? current.length : endLineIndex + 1;
+    while (current[afterIndex] === "\n") afterIndex += 1;
+    next = `${current.slice(0, startIndex)}${normalizedBlock}\n\n${current.slice(afterIndex)}`;
+  } else {
+    const insertIndex = current.indexOf(insertBefore);
+    if (insertIndex < 0) {
+      failures.push(`${file} missing insertion anchor ${insertBefore}`);
+      return;
+    }
+    next = `${current.slice(0, insertIndex)}${normalizedBlock}\n\n${current.slice(insertIndex)}`;
+  }
+
+  await write(file, next);
+};
+
+const relativeLink = (fromFile, targetFile) => {
+  const fromDir = path.posix.dirname(fromFile);
+  const target = path.posix.relative(fromDir, targetFile);
+  return target.length === 0 ? path.posix.basename(targetFile) : target;
+};
+
+const mdLink = (fromFile, label, targetFile) => `[${label}](${relativeLink(fromFile, targetFile)})`;
+
+const table = (headers, rows) => {
+  const widths = headers.map((header, index) =>
+    Math.max(header.length, ...rows.map((row) => row[index].length)),
+  );
+  const line = (row) =>
+    `| ${row.map((cell, index) => `${cell}${" ".repeat(Math.max(0, widths[index] - cell.length))}`).join(" | ")} |`;
+  return [
+    line(headers),
+    `| ${widths.map((width) => "-".repeat(width)).join(" | ")} |`,
+    ...rows.map(line),
+  ].join("\n");
+};
+
+const model = collectAgentDocsModel(root);
+failures.push(...model.failures);
+
+const {
+  recipesSource,
+  capabilityRulesSource,
+  invariantsSource,
+  primitives,
+  errors,
+  invariantMatrix,
+  rootScripts,
+  namespaceModel,
+} = model;
+const boundaryRuleSource = JSON.parse(read("docs/agent/boundary-rules.source.json"));
+const boundaryRuleCommands = Object.fromEntries(
+  (Array.isArray(boundaryRuleSource.rules) ? boundaryRuleSource.rules : []).map((rule) => [
+    rule.id,
+    `agentos check guard ${rule.id}`,
+  ]),
+);
+
+const capabilityProjection = buildCapabilityRouteProjection({
+  source: capabilityRulesSource,
+  recipes: recipesSource.recipes,
+  primitives,
+  invariants: invariantsSource.invariants,
+  rootScripts: { ...rootScripts, ...boundaryRuleCommands },
+  namespaceOwners: namespaceModel.owners,
+});
+failures.push(...capabilityProjection.failures);
+
+const primitivesJson = {
+  generatedBy: "packages/cli/src/generate/generate-agent-docs.mjs",
+  source: [
+    "exported TSDoc @agentosPrimitive tags",
+    "docs/agent/invariants.source.json",
+    "docs/agent/primitive-evidence.source.json",
+  ],
+  primitives,
+};
+
+const recipesJson = {
+  generatedBy: "packages/cli/src/generate/generate-agent-docs.mjs",
+  source: "docs/agent/recipes.source.json",
+  recipes: recipesSource.recipes,
+};
+
+const errorsJson = {
+  generatedBy: "packages/cli/src/generate/generate-agent-docs.mjs",
+  source: ["packages/**/*.ts agent_os.* tags", "docs/agent/error-metadata.source.json"],
+  errors,
+};
+
+const invariantMatrixJson = {
+  generatedBy: "packages/cli/src/generate/generate-agent-docs.mjs",
+  source: [
+    "docs/agent/invariants.source.json",
+    "exported TSDoc @agentosInvariant tags",
+    "docs/agent/error-metadata.source.json",
+  ],
+  invariants: invariantMatrix,
+};
+
+const decisionGraphJson = {
+  generatedBy: "packages/cli/src/generate/generate-agent-docs.mjs",
+  source: [
+    "docs/agent/capability-rules.source.json",
+    "docs/agent/recipes.source.json",
+    "exported TSDoc @agentosPrimitive tags",
+    "BoundaryContract/event namespace declarations",
+    "docs/agent/boundary-rules.source.json",
+  ],
+  routes: capabilityProjection.routes,
+  coverage: capabilityProjection.coverage,
+};
+
+const startHere = [
+  generatedNotice("docs/agent/*.source.json and exported TSDoc @agentosPrimitive tags"),
+  "",
+  "# Start Here",
+  "",
+  "Agent-facing docs are generated projections. Source facts live in `docs/agent/*.source.json`, `docs/surface.json`, package manifests, and exported TSDoc annotation tags.",
+  "",
+  "## Navigation",
+  "",
+  table(
+    ["Surface", "Generated File"],
+    [
+      [
+        "Recipes",
+        mdLink("docs/start-here.md", "docs/agent/recipes.json", "docs/agent/recipes.json"),
+      ],
+      [
+        "Primitives",
+        mdLink("docs/start-here.md", "docs/agent/primitives.md", "docs/agent/primitives.md"),
+      ],
+      [
+        "Decision Graph",
+        mdLink(
+          "docs/start-here.md",
+          "docs/agent/decision-graph.md",
+          "docs/agent/decision-graph.md",
+        ),
+      ],
+      ["Errors", mdLink("docs/start-here.md", "docs/agent/errors.md", "docs/agent/errors.md")],
+      [
+        "Invariant Matrix",
+        mdLink(
+          "docs/start-here.md",
+          "docs/agent/invariant-matrix.md",
+          "docs/agent/invariant-matrix.md",
+        ),
+      ],
+    ],
+  ),
+  "",
+  "## Recipes",
+  "",
+  table(
+    ["Recipe", "Tutorial", "Primary Primitives"],
+    recipesSource.recipes.map((recipe) => [
+      `\`${recipe.id}\``,
+      mdLink("docs/start-here.md", recipe.title, recipe.tutorial),
+      recipe.primitives.map((primitive) => `\`${primitive}\``).join(", "),
+    ]),
+  ),
+  "",
+].join("\n");
+
+const agentNavigationStart = "<!-- agent-docs-navigation:start -->";
+const agentNavigationEnd = "<!-- agent-docs-navigation:end -->";
+const agentNavigation = [
+  agentNavigationStart,
+  generatedNotice("docs/agent/*.source.json and exported TSDoc @agentosPrimitive tags"),
+  "## Agent Navigation Index",
+  "",
+  "Start at [docs/start-here.md](docs/start-here.md). It is the generated route from intent to primitive, invariant, error, docs, and tests.",
+  "",
+  table(
+    ["Intent", "Route"],
+    [
+      ["Start route", "[docs/start-here.md](docs/start-here.md)"],
+      ["Primitive catalog", "[docs/agent/primitives.md](docs/agent/primitives.md)"],
+      ["Decision graph", "[docs/agent/decision-graph.md](docs/agent/decision-graph.md)"],
+      ["Error catalog", "[docs/agent/errors.md](docs/agent/errors.md)"],
+      ["Invariant matrix", "[docs/agent/invariant-matrix.md](docs/agent/invariant-matrix.md)"],
+      ...recipesSource.recipes.map((recipe) => [
+        recipe.title,
+        `[${recipe.tutorial}](${recipe.tutorial})`,
+      ]),
+    ],
+  ),
+  agentNavigationEnd,
+].join("\n");
+
+const primitivesMd = [
+  generatedNotice(
+    "exported TSDoc @agentosPrimitive tags and docs/agent/primitive-evidence.source.json",
+  ),
+  "",
+  "# Agent Primitives",
+  "",
+  table(
+    ["Primitive", "Kind", "Export", "Invariant", "Docs", "Test Evidence"],
+    primitives.map((primitive) => [
+      `\`${primitive.id}\``,
+      `\`${primitive.capabilityKind}\``,
+      `\`${primitive.package}:${primitive.symbol}\``,
+      primitive.invariants.map((invariant) => `\`${invariant}\``).join(", "),
+      mdLink("docs/agent/primitives.md", path.posix.basename(primitive.docs), primitive.docs),
+      primitive.testEvidence.tests === undefined
+        ? `no test: ${primitive.testEvidence.noTestReason}`
+        : primitive.testEvidence.tests
+            .map((test) => mdLink("docs/agent/primitives.md", path.posix.basename(test), test))
+            .join(", "),
+    ]),
+  ),
+  "",
+].join("\n");
+
+const errorsMd = [
+  generatedNotice("packages/**/*.ts agent_os.* tags and docs/agent/error-metadata.source.json"),
+  "",
+  "# Agent Error Catalog",
+  "",
+  table(
+    ["Error", "Invariant", "Docs", "Fix"],
+    errors.map((error) => [
+      `\`${error.tag}\``,
+      error.invariants.map((invariant) => `\`${invariant}\``).join(", "),
+      mdLink("docs/agent/errors.md", path.posix.basename(error.docs), error.docs),
+      error.fix,
+    ]),
+  ),
+  "",
+].join("\n");
+
+const decisionGraphMd = [
+  generatedNotice(
+    "docs/agent/capability-rules.source.json, docs/agent/recipes.source.json, exported TSDoc @agentosPrimitive tags, BoundaryContract/event namespace declarations, and docs/agent/boundary-rules.source.json",
+  ),
+  "",
+  "# Agent Decision Graph",
+  "",
+  "This is the generated owner compiler from natural-language intent to allowed substrate motion. Source rules name intent and constraints only; owner and package fields are generated.",
+  "",
+  table(
+    ["Primitive", "Kind", "Intents", "Source Fact Owners", "Allowed Packages", "Gates"],
+    capabilityProjection.routes.map((route) => [
+      `\`${route.primitive}\``,
+      `\`${route.coordinationCapabilityKind}\``,
+      route.intents.join("; "),
+      route.sourceFactOwners
+        .map((entry) => `\`${String(entry.prefix)}\` -> \`${String(entry.owner)}\``)
+        .join(", "),
+      route.allowedPrimitivePackages.map((pkg) => `\`${String(pkg)}\``).join(", "),
+      route.gates.map((gate) => `\`${gate}\``).join(", "),
+    ]),
+  ),
+  "",
+  "## Coverage",
+  "",
+  table(
+    ["Recipe", "Status"],
+    capabilityProjection.coverage.recipes.map((recipe) => [
+      `\`${recipe.id}\``,
+      recipe.routePrimitives.length > 0
+        ? recipe.routePrimitives.map((primitive) => `\`${primitive}\``).join(", ")
+        : `no route: ${recipe.noRouteReason}`,
+    ]),
+  ),
+  "",
+].join("\n");
+
+const invariantMatrixMd = [
+  generatedNotice(
+    "docs/agent/invariants.source.json, exported TSDoc @agentosInvariant tags, and docs/agent/error-metadata.source.json",
+  ),
+  "",
+  "# Agent Invariant Matrix",
+  "",
+  table(
+    ["Invariant", "Primitives", "Errors", "Docs", "Tests"],
+    invariantMatrix.map((row) => [
+      `\`${row.invariant}\``,
+      row.primitives.map((primitive) => `\`${primitive}\``).join(", "),
+      row.errors.map((error) => `\`${error}\``).join(", "),
+      row.docs
+        .map((doc) => mdLink("docs/agent/invariant-matrix.md", path.posix.basename(doc), doc))
+        .join(", "),
+      row.tests.map((test) => `\`${test}\``).join(", "),
+    ]),
+  ),
+  "",
+].join("\n");
+
+if (failures.length === 0) {
+  await writeJson("docs/agent/recipes.json", recipesJson);
+  await writeJson("docs/agent/primitives.json", primitivesJson);
+  await write("docs/agent/primitives.md", primitivesMd);
+  await writeJson("docs/agent/decision-graph.json", decisionGraphJson);
+  await write("docs/agent/decision-graph.md", decisionGraphMd);
+  await writeJson("docs/agent/errors.json", errorsJson);
+  await write("docs/agent/errors.md", errorsMd);
+  await writeJson("docs/agent/invariant-matrix.json", invariantMatrixJson);
+  await write("docs/agent/invariant-matrix.md", invariantMatrixMd);
+  await write("docs/start-here.md", startHere);
+  await replaceGeneratedBlock({
+    file: "AGENTS.md",
+    startMarker: agentNavigationStart,
+    endMarker: agentNavigationEnd,
+    block: agentNavigation,
+    insertBefore: "## BoundaryContract Checklist",
+  });
+}
+
+if (failures.length > 0) {
+  console.error(failures.join("\n"));
+  process.exit(1);
+}
+
+console.log(
+  `generated agent docs: ${recipesSource.recipes.length} recipes, ${primitives.length} primitives, ${errors.length} errors`,
+);