@graphit/cli 0.2.270 → 0.2.306

package/scripts/commander-walk.mjs

@@ -0,0 +1,154 @@
+// The one Commander walk. Both generators consume it - the SKILL.md command
+// table (generate-commands-doc.mjs) and the platform-agent tool manifest
+// (generate-tool-manifest.mjs) - so a command, flag or description can never
+// mean two different things on the two surfaces.
+//
+// Project #275: the in-app agent's tool vocabulary IS the CLI vocabulary. A
+// second walk would be a second source of truth, which is the drift this
+// project exists to remove.
+//
+// Everything below `collectVerbs` operates on the walk's own plain records, not
+// on Commander objects. A field this file does not capture is a field neither
+// generator can see - `mandatory` was dropped once and published 36 required
+// flags as optional, so add to the record rather than reaching past it.
+
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { Command } from "commander";
+
+export const cliRoot =
+  process.env.GRAPHIT_CLI_ROOT ??
+  join(fileURLToPath(new URL(".", import.meta.url)), "..");
+
+// Mirrors index.ts registration order; groups not listed are appended alphabetically.
+export const GROUP_ORDER = [
+  "auth", "status", "kb", "query", "metadata", "ds", "dashboard",
+  "connector", "governance", "team", "plugin", "setup",
+];
+
+/**
+ * Assemble a throwaway program by importing only the dist/ registrars.
+ *
+ * NEVER import dist/index.js - module load fires the update banner,
+ * program.parse(), and a network update check.
+ */
+export async function buildProgram() {
+  const distCommandsDir = join(cliRoot, "dist", "commands");
+  if (!existsSync(distCommandsDir)) {
+    throw new Error(
+      `dist/commands not found at ${distCommandsDir} - run "npm run build" first`,
+    );
+  }
+  const program = new Command();
+  program.name("graphit");
+  const files = readdirSync(distCommandsDir)
+    .filter((f) => f.endsWith(".js"))
+    .sort(); // deterministic import order
+  for (const file of files) {
+    const mod = await import(pathToFileURL(join(distCommandsDir, file)).href);
+    for (const [name, value] of Object.entries(mod)) {
+      if (typeof value === "function" && /^register/.test(name)) {
+        value(program);
+      }
+    }
+  }
+  return program;
+}
+
+/** `<id> [ids...]` from the walk's structured arguments. */
+export function formatArgs(args) {
+  return args
+    .map((arg) => {
+      const name = arg.name + (arg.variadic ? "..." : "");
+      return arg.required ? `<${name}>` : `[${name}]`;
+    })
+    .join(" ");
+}
+
+/** `--limit --verified` from the walk's structured options. */
+export function formatFlags(options) {
+  return options.map((opt) => opt.long || opt.flags).filter(Boolean).join(" ");
+}
+
+export function orderGroups(names) {
+  return [...names].sort((a, b) => {
+    const ia = GROUP_ORDER.indexOf(a);
+    const ib = GROUP_ORDER.indexOf(b);
+    if (ia === -1 && ib === -1) return a.localeCompare(b);
+    if (ia === -1) return 1;
+    if (ib === -1) return -1;
+    return ia - ib;
+  });
+}
+
+// Hidden options (hideHelp) are unpublished by definition - deprecated or
+// internal flags must not be taught to agents on either surface.
+const visibleOptions = (cmd) => (cmd.options ?? []).filter((opt) => !opt.hidden);
+
+// A command earns its own row if it is a leaf OR it has its own args/options
+// (e.g. `query <sql>` both takes an arg and has the `metadata` sibling group).
+const hasOwnInvocation = (cmd) =>
+  (cmd.registeredArguments ?? []).length > 0 || (cmd.options ?? []).length > 0;
+
+/**
+ * Every invocable command in the tree, in group order then registration order.
+ *
+ * `action` is the path below the group ("create metric", "update-html", "" for
+ * a group that is itself invocable such as `query` or `status`).
+ */
+export function collectVerbs(program) {
+  const verbs = [];
+
+  const visit = (cmd, group, path) => {
+    const subs = cmd.commands ?? [];
+    if (subs.length === 0 || hasOwnInvocation(cmd)) {
+      verbs.push({
+        group,
+        action: path.slice(group.length).trim(),
+        command: path,
+        description: cmd.description() ?? "",
+        args: (cmd.registeredArguments ?? []).map((arg) => ({
+          name: arg.name(),
+          description: arg.description ?? "",
+          required: Boolean(arg.required),
+          variadic: Boolean(arg.variadic),
+        })),
+        options: visibleOptions(cmd).map((opt) => ({
+          flags: opt.flags,
+          long: opt.long ?? "",
+          short: opt.short ?? "",
+          description: opt.description ?? "",
+          // A value-taking option renders as `--limit <n>`; a boolean switch has
+          // no placeholder. Commander exposes both as `required`/`optional` on
+          // the option's ARGUMENT, never on the option itself - `mandatory` is
+          // the separate flag meaning ".requiredOption(), the CLI rejects the
+          // command without it".
+          takesValue: Boolean(opt.required || opt.optional),
+          valueOptional: Boolean(opt.optional),
+          mandatory: Boolean(opt.mandatory),
+          negated: Boolean(opt.negate),
+          variadic: Boolean(opt.variadic),
+          defaultValue: opt.defaultValue,
+          choices: opt.argChoices ?? null,
+        })),
+      });
+    }
+    for (const sub of subs) {
+      visit(sub, group, `${path} ${sub.name()}`.trim());
+    }
+  };
+
+  for (const name of orderGroups(program.commands.map((c) => c.name()))) {
+    const top = program.commands.find((c) => c.name() === name);
+    visit(top, name, name);
+  }
+  return verbs;
+}
+
+/** Group name -> its top-level `.description()`. */
+export function collectGroupDescriptions(program) {
+  const out = new Map();
+  for (const top of program.commands) out.set(top.name(), top.description() ?? "");
+  return out;
+}

package/scripts/generate-commands-doc.mjs

@@ -9,123 +9,54 @@
 //
 // Requires a prior `npm run build` (it imports the compiled registrars from dist/).
 
-import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { Command } from "commander";
+import {
+  buildProgram,
+  cliRoot,
+  collectGroupDescriptions,
+  collectVerbs,
+  formatArgs,
+  formatFlags,
+} from "./commander-walk.mjs";
 
 const checkOnly = process.argv.includes("--check");
 const toStdout = process.argv.includes("--stdout");
 
-const cliRoot =
-  process.env.GRAPHIT_CLI_ROOT ??
-  join(fileURLToPath(new URL(".", import.meta.url)), "..");
-const distCommandsDir = join(cliRoot, "dist", "commands");
 const skillPath = join(cliRoot, "skills", "graphit", "SKILL.md");
 
 const START = "<!-- COMMANDS:START -->";
 const END = "<!-- COMMANDS:END -->";
 
-// Mirrors index.ts registration order; groups not listed are appended alphabetically.
-const GROUP_ORDER = [
-  "auth", "status", "kb", "query", "metadata", "ds", "dashboard",
-  "connector", "governance", "team", "plugin", "setup",
-];
-
-// Assemble a throwaway program by importing only the dist/ registrars (never
-// dist/index.js - that fires the update banner + program.parse() at load).
-async function buildProgram() {
-  if (!existsSync(distCommandsDir)) {
-    throw new Error(
-      `dist/commands not found at ${distCommandsDir} - run "npm run build" first`,
-    );
-  }
-  const program = new Command();
-  program.name("graphit");
-  const files = readdirSync(distCommandsDir)
-    .filter((f) => f.endsWith(".js"))
-    .sort(); // deterministic import order
-  for (const file of files) {
-    const mod = await import(pathToFileURL(join(distCommandsDir, file)).href);
-    for (const [name, value] of Object.entries(mod)) {
-      if (typeof value === "function" && /^register/.test(name)) {
-        value(program);
-      }
-    }
-  }
-  return program;
-}
-
 function esc(text) {
   return String(text ?? "").replace(/\r?\n/g, " ").replace(/\|/g, "\\|").trim();
 }
 
-function formatArgs(cmd) {
-  return (cmd.registeredArguments ?? [])
-    .map((arg) => {
-      const name = arg.name() + (arg.variadic ? "..." : "");
-      return arg.required ? `<${name}>` : `[${name}]`;
-    })
-    .join(" ");
-}
-
-function formatFlags(cmd) {
-  return (cmd.options ?? [])
-    // Hidden options (hideHelp) are unpublished by definition - deprecated or
-    // internal flags must not be taught to agents via the command table.
-    .filter((opt) => !opt.hidden)
-    .map((opt) => opt.long ?? opt.flags)
-    .filter(Boolean)
-    .join(" ");
-}
-
-// A command earns its own row if it is a leaf OR it has its own args/options
-// (e.g. `query <sql>` both takes an arg and has the `metadata` sibling group).
-function hasOwnInvocation(cmd) {
-  return (
-    (cmd.registeredArguments ?? []).length > 0 ||
-    (cmd.options ?? []).length > 0
-  );
-}
-
-function collectRows(cmd, path, rows) {
-  const subs = cmd.commands ?? [];
-  if (subs.length === 0 || hasOwnInvocation(cmd)) {
-    rows.push({
-      command: `${path}${formatArgs(cmd) ? ` ${formatArgs(cmd)}` : ""}`,
-      description: cmd.description(),
-      flags: formatFlags(cmd),
-    });
-  }
-  for (const sub of subs) {
-    collectRows(sub, `${path} ${sub.name()}`.trim(), rows);
-  }
-}
-
-function orderGroups(names) {
-  return [...names].sort((a, b) => {
-    const ia = GROUP_ORDER.indexOf(a);
-    const ib = GROUP_ORDER.indexOf(b);
-    if (ia === -1 && ib === -1) return a.localeCompare(b);
-    if (ia === -1) return 1;
-    if (ib === -1) return -1;
-    return ia - ib;
-  });
-}
-
 function renderBlock(program) {
+  const groupDescriptions = collectGroupDescriptions(program);
   const groups = new Map();
-  for (const top of program.commands) {
-    const rows = [];
-    collectRows(top, top.name(), rows);
-    groups.set(top.name(), { description: top.description(), rows });
+  // collectVerbs already returns groups in GROUP_ORDER, so insertion order here
+  // is the render order - no second sort.
+  for (const verb of collectVerbs(program)) {
+    if (!groups.has(verb.group)) {
+      groups.set(verb.group, {
+        description: groupDescriptions.get(verb.group),
+        rows: [],
+      });
+    }
+    const args = formatArgs(verb.args);
+    groups.get(verb.group).rows.push({
+      command: `${verb.command}${args ? ` ${args}` : ""}`,
+      description: verb.description,
+      flags: formatFlags(verb.options),
+    });
   }
   const lines = [
     "",
     "_Generated from the CLI by `npm run gen:commands` - do not hand-edit between the markers. Run `graphit <cmd> --help` for exact flag values and descriptions._",
     "",
   ];
-  for (const name of orderGroups(groups.keys())) {
+  for (const name of groups.keys()) {
     const { description, rows } = groups.get(name);
     lines.push(`**${name}**${description ? ` - ${esc(description)}` : ""}`);
     for (const row of rows) {