Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust
4.7 KB
Raw Blame
/**
 * Generate the method-to-tool table in README.md and docs/arguments.md from
 * src/coverage.ts, the table the drift test reads.
 *
 *   npm run docs:generate   rewrite both
 *   npm run docs:check      fail when the committed copies are stale
 */

import { readFile, writeFile } from "node:fs/promises";
import { fileURLToPath } from "node:url";

import { camelCase, TOOL_COVERAGE } from "../src/coverage.js";

const root = new URL("../../", import.meta.url);
const readmePath = fileURLToPath(new URL("README.md", root));
const argumentsPath = fileURLToPath(new URL("docs/arguments.md", root));
const START = "<!-- generated:methods:start -->";
const END = "<!-- generated:methods:end -->";

/** Routes outside MCP: the read-only API and the admin entry point. */
const HTTP_ROWS: readonly [string, string][] = [
  ["identity", "`GET /identity`"],
  ["capabilities", "`initialize`, `tools/list`, `GET /identity`, `GET /api/v1/workspaces`"],
  ["api.workspaces", "`GET /api/v1/workspaces`"],
  ["api.projects", "`GET /api/v1/projects`"],
  ["api.pages", "`GET /api/v1/workspaces/{w}/projects/{p}/pages`"],
  ["api.page", "`GET /api/v1/workspaces/{w}/projects/{p}/pages/{path}`"],
  ["api.recent", "`GET /api/v1/workspaces/{w}/projects/{p}/recent?updated_since=`"],
  ["api.search", "`GET` or `POST /api/v1/search`"],
  ["api.briefing", "`GET /api/v1/workspaces/{w}/projects/{p}/briefing`"],
  ["api.handoffs", "`GET /api/v1/workspaces/{w}/projects/{p}/handoffs`"],
  ["api.sessions", "`GET /api/v1/workspaces/{w}/projects/{p}/sessions`"],
  ["api.observations", "`GET /api/v1/workspaces/{w}/projects/{p}/sessions/{id}/observations`"],
  ["AdminClient.checkpoints", "`GET /admin/checkpoints`"],
  ["AdminClient.restorePage", "`POST /admin/restore-page`"],
  ["AdminClient.purgeSession", "`POST /admin/purge-session`"],
  ["AdminClient.purgeProject", "`POST /admin/purge-project`"],
];

function methodTable(): string {
  const lines = ["| SDK method | Server call |", "|---|---|"];
  const rows: [string, string][] = [];
  for (const [tool, entry] of Object.entries(TOOL_COVERAGE)) {
    if (entry.status !== "wrapped") continue;
    for (const method of entry.methods) rows.push([method, `\`${tool}\``]);
  }
  const merged = new Map<string, string[]>();
  for (const [method, call] of [...rows, ...HTTP_ROWS]) {
    merged.set(method, [...(merged.get(method) ?? []), call]);
  }
  for (const [method, calls] of merged) lines.push(`| \`${method}\` | ${calls.join(", ")} |`);
  lines.push("", "Not wrapped (call them with `callTool`):", "");
  for (const [tool, entry] of Object.entries(TOOL_COVERAGE)) {
    if (entry.status === "not_exposed") lines.push(`- \`${tool}\`: ${entry.reason}`);
  }
  return lines.join("\n");
}

function argumentsDoc(): string {
  const lines = [
    "# Argument names",
    "",
    "<!-- Generated by `npm run docs:generate` from src/coverage.ts. Do not edit by hand. -->",
    "",
    "SDK arguments are the server's wire names in camelCase. `workspace` and",
    "`project` travel inside `scope`; `messages.send` takes `to` and `from` scopes",
    "for the `to_*` and `from_*` pairs.",
    "",
  ];
  for (const [tool, entry] of Object.entries(TOOL_COVERAGE)) {
    if (entry.status !== "wrapped") continue;
    lines.push(`## \`${tool}\``, "", `Methods: ${entry.methods.map((m) => `\`${m}\``).join(", ")}`, "");
    lines.push("| Wire name | SDK name |", "|---|---|");
    for (const wire of entry.sends) lines.push(`| \`${wire}\` | \`${camelCase(wire)}\` |`);
    lines.push("");
  }
  return lines.join("\n");
}

function withTable(readme: string): string {
  const start = readme.indexOf(START);
  const end = readme.indexOf(END);
  if (start === -1 || end === -1 || end < start) {
    throw new Error(`README.md lacks the ${START} / ${END} markers`);
  }
  return `${readme.slice(0, start + START.length)}\n${methodTable()}\n${readme.slice(end)}`;
}

const mode = process.argv[2];
const readme = await readFile(readmePath, "utf8");
const wantReadme = withTable(readme);
const wantArguments = argumentsDoc();

if (mode === "--write") {
  await writeFile(readmePath, wantReadme);
  await writeFile(argumentsPath, wantArguments);
  console.log("wrote README.md method table and docs/arguments.md");
} else if (mode === "--check") {
  const stale: string[] = [];
  if (readme !== wantReadme) stale.push("README.md method table");
  const current = await readFile(argumentsPath, "utf8").catch(() => "");
  if (current !== wantArguments) stale.push("docs/arguments.md");
  if (stale.length > 0) {
    console.error(`stale generated docs: ${stale.join(", ")}; run \`npm run docs:generate\``);
    process.exit(1);
  }
  console.log("generated docs are current");
} else {
  console.error("usage: generate-docs.js --write|--check");
  process.exit(2);
}