@graphit/cli 0.2.270 → 0.2.306

package/scripts/generate-tool-manifest.mjs

@@ -0,0 +1,613 @@
+#!/usr/bin/env node
+// Generates the platform agent's tool surface from the CLI Commander tree.
+//
+// Project #275: the in-app agent's vocabulary IS the CLI's vocabulary. One
+// Commander walk (commander-walk.mjs) feeds both the SKILL.md command table and
+// the two artifacts written here, so the surfaces cannot drift.
+//
+//   node scripts/generate-tool-manifest.mjs           # write the artifacts
+//   node scripts/generate-tool-manifest.mjs --check   # exit 1 if they are stale
+//   node scripts/generate-tool-manifest.mjs --stdout  # print the manifest only
+//
+// Requires a prior `npm run build` (it imports the compiled registrars).
+//
+// Everything this file refuses to do is deliberate:
+//   - it never invents or rewrites a description. A thin one is enriched at the
+//     source in cli/src/commands/*.ts, where --help improves too.
+//   - it never emits `additionalProperties` (Gemini rejects schemas carrying it).
+//   - it never emits an org/user identity parameter. Tenancy is bound from the
+//     authenticated session at construction, never from a model-supplied value.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildProgram, cliRoot, collectVerbs } from "./commander-walk.mjs";
+
+const checkOnly = process.argv.includes("--check");
+const toStdout = process.argv.includes("--stdout");
+
+// Overridable so the drift tests can drive a mutated policy source without
+// touching the committed one. Never set outside tests.
+const policyPath =
+  process.env.GRAPHIT_VERB_POLICY_PATH ?? join(cliRoot, "scripts", "verb-policy-source.json");
+const outDir = join(
+  cliRoot, "..", "back", "app", "services", "graphit_agent",
+  "platform_agent", "tools", "generated",
+);
+const manifestPath = join(outDir, "tool-manifest.json");
+const policyOutPath = join(outDir, "verb-policy.json");
+
+// ---------------------------------------------------------------- constraints
+
+/** #178's tool window holds only while a noun stays comprehensible. `kb` sits at
+ *  this ceiling today; the prescribed response when it fires is to split the
+ *  noun by lifecycle (read vs authoring), never to reach for `oneOf`. */
+const MAX_ACTIONS_PER_NOUN = 25;
+
+/** Project #275 US-3.4: tool docs are always-on, so each is charged to every turn. */
+const MAX_TOOL_DOC_CHARS = 2000;
+
+const MUTATION_CLASSES = new Set([
+  "none", "kb", "canvas", "dashboard", "data_source", "governance",
+]);
+const SURFACES = new Set(["both", "cli_only", "app_only"]);
+
+/** Project #275 SEC-2: identity is bound from the session, never routed through
+ *  a schema the model fills in. Matched against the derived parameter name. */
+const TENANT_PARAM_DENYLIST = [
+  /^org(_?id)?$/, /^organization(_?id)?$/, /^user(_?id)?$/, /^tenant(_?id)?$/,
+  /^account_?id$/, /^org_role$/, /^actor(_?id)?$/, /^principal$/, /^impersonate/,
+  /^on_behalf_of/, /^as_user/,
+];
+
+/** PE-DENY-001: internal issue/feature/project numbers never reach a prompt.
+ *  `#NNN` has to stand alone - a hex colour like #4DB6AC is not a reference. */
+const INTERNAL_REF = /(?:^|[^0-9A-Za-z_])#\d+(?![0-9A-Za-z_])/;
+
+/** PE-DENY-002: a description teaches the shape of a secret, never a value.
+ *  Deliberately narrow - long high-entropy tokens and the recognisable key
+ *  prefixes - so a legitimate example like `--key <path>` stays legal. */
+const CREDENTIAL_SHAPED =
+  /\b(?:sk|pk|ghp|gho|ghs|ghu|xox[abprs])[-_][A-Za-z0-9]{16,}|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|eyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}/;
+
+/** A value option whose placeholder is one of these is a number, not a string.
+ *  Purely mechanical - no guessing from the description. */
+const NUMERIC_PLACEHOLDERS = new Set(["n", "days", "seconds", "ms", "rows", "bytes"]);
+
+/** Types an `app_params` entry may declare. Deliberately the scalar set the
+ *  Commander walk itself produces: an in-app parameter is a per-surface
+ *  mechanics difference, not a licence to invent a richer schema than the CLI's. */
+const APP_PARAM_TYPES = new Set(["string", "integer", "boolean"]);
+
+const errors = [];
+const fail = (msg) => errors.push(msg);
+
+/** Nothing is written while a single gate is unsatisfied. */
+function exitOnErrors() {
+  if (!errors.length) return;
+  console.error("Tool manifest generation failed:");
+  for (const e of errors) console.error(`  - ${e}`);
+  process.exit(1);
+}
+
+// ------------------------------------------------------------------- helpers
+
+/** CLI flag or positional arg -> JSON Schema property name. Mechanical and
+ *  reversible: lowercase, `-` becomes `_`, camelCase splits on the hump. */
+function paramName(raw) {
+  return raw
+    .replace(/^--/, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/-/g, "_")
+    .toLowerCase();
+}
+
+function valuePlaceholder(flags) {
+  const m = flags.match(/[<[]([^>\]]+)[>\]]\s*$/);
+  return m ? m[1].replace(/\.\.\.$/, "") : null;
+}
+
+function optionSchema(opt) {
+  if (!opt.takesValue) return { type: "boolean" };
+  const placeholder = valuePlaceholder(opt.flags);
+  const numeric =
+    (placeholder && NUMERIC_PLACEHOLDERS.has(placeholder)) ||
+    (typeof opt.defaultValue === "string" && /^\d+$/.test(opt.defaultValue));
+  const scalar = { type: numeric ? "integer" : "string" };
+  // Commander marks `--flag <v...>` variadic, but a repeatable option built from
+  // a custom collector (`(val, prev) => [...prev, val]`) is not variadic - its
+  // array default is the only signal, and without this it ships as a scalar the
+  // model can only pass once.
+  const repeatable = opt.variadic || Array.isArray(opt.defaultValue);
+  return repeatable ? { type: "array", items: scalar } : scalar;
+}
+
+function argSchema(arg) {
+  return arg.variadic
+    ? { type: "array", items: { type: "string" } }
+    : { type: "string" };
+}
+
+/** First sentence of a description, for the action one-liners in the tool doc. */
+function firstSentence(text) {
+  const clean = String(text ?? "").replace(/\s+/g, " ").trim();
+  const stop = clean.search(/\.(\s|$)/);
+  return (stop === -1 ? clean : clean.slice(0, stop)).trim();
+}
+
+/**
+ * True when a summary only restates the action name it would sit beside
+ * ("create metric" / "Create a new metric").
+ *
+ * The doc drops those, and only those. This is suppression of a tautology, not
+ * a rewrite: any summary carrying a word the action name does not already have
+ * survives verbatim ("Create a new relationship (JOIN between tables)" stays).
+ */
+function restatesActionName(summary, action) {
+  const normalize = (s) =>
+    String(s)
+      .toLowerCase()
+      .replace(/\b(a|an|the|new)\b/g, "")
+      .replace(/[^a-z0-9]/g, "");
+  return normalize(summary) === normalize(action);
+}
+
+/** The one place emitted JSON is formatted. Determinism comes from the order
+ *  keys are BUILT (walk order, then explicit sorts), not from re-sorting here. */
+function formatJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+// ---------------------------------------------------------------------- walk
+
+const program = await buildProgram();
+const verbs = collectVerbs(program);
+
+if (!existsSync(policyPath)) {
+  throw new Error(`verb-policy-source.json not found at ${policyPath}`);
+}
+const policySource = JSON.parse(readFileSync(policyPath, "utf-8"));
+const declaredNouns = policySource.nouns ?? {};
+const policyRows = policySource.verbs ?? {};
+const identityExemptions = policySource.identity_param_exemptions ?? {};
+
+/** A noun is the Commander group unless a verb row re-homes it (used when one
+ *  group's actions do not fit a single tool - see the ceiling below). */
+const nounOf = (verb) => policyRows[verb.command]?.noun || verb.group;
+
+// -------------------------------------------------- completeness, both ways
+
+const commanderKeys = new Set(verbs.map((v) => v.command));
+
+for (const verb of verbs) {
+  const row = policyRows[verb.command];
+  if (!row) {
+    fail(
+      `no policy row for \`${verb.command}\` - add one to scripts/verb-policy-source.json. ` +
+      `A verb kept out of the app needs surface != "both" and a reason.`,
+    );
+    continue;
+  }
+  if (!SURFACES.has(row.surface)) {
+    fail(`\`${verb.command}\`: surface "${row.surface}" is not one of ${[...SURFACES].join(", ")}`);
+  }
+  if (!MUTATION_CLASSES.has(row.mutation_class)) {
+    fail(`\`${verb.command}\`: mutation_class "${row.mutation_class}" is not one of ${[...MUTATION_CLASSES].join(", ")}`);
+  }
+  for (const field of ["is_read_only", "requires_approval", "silent_retry_exempt"]) {
+    if (typeof row[field] !== "boolean") {
+      fail(`\`${verb.command}\`: ${field} must be a boolean`);
+    }
+  }
+  if (row.surface !== "both" && !String(row.reason ?? "").trim()) {
+    fail(`\`${verb.command}\`: surface is "${row.surface}" but no reason is given - absence is never silent`);
+  }
+  if (row.is_read_only && row.mutation_class !== "none") {
+    fail(`\`${verb.command}\`: is_read_only with mutation_class "${row.mutation_class}"`);
+  }
+  if (row.is_read_only && row.requires_approval) {
+    fail(`\`${verb.command}\`: a read-only verb must never prompt for approval`);
+  }
+
+  // `app_params` - a parameter the app has and the CLI does not. The policy
+  // source already decides what a verb MEANS in the app (approval, mutation
+  // class, whether it is there at all); this is the same decision applied to a
+  // verb's inputs, for the case where the two surfaces genuinely differ in
+  // mechanics rather than in capability. Every entry carries a written reason,
+  // for the reason absence does: an asymmetry nobody wrote down is one nobody
+  // reviewed.
+  const appParams = row.app_params ?? {};
+  if (Object.keys(appParams).length && row.surface !== "both") {
+    fail(
+      `\`${verb.command}\`: app_params is set but surface is "${row.surface}" - ` +
+      `a parameter for a surface this verb is not on`,
+    );
+  }
+  for (const [name, spec] of Object.entries(appParams)) {
+    if (!APP_PARAM_TYPES.has(spec?.type)) {
+      fail(
+        `\`${verb.command}\` app_params.${name}: type "${spec?.type}" is not one of ` +
+        `${[...APP_PARAM_TYPES].join(", ")}`,
+      );
+    }
+    if (!String(spec?.reason ?? "").trim()) {
+      fail(
+        `\`${verb.command}\` app_params.${name}: no reason given - a parameter the CLI ` +
+        `does not have is never silent`,
+      );
+    }
+    if (name !== paramName(name)) {
+      fail(
+        `\`${verb.command}\` app_params.${name}: name is already the property name here, ` +
+        `so write it as the walk would derive it ("${paramName(name)}")`,
+      );
+    }
+  }
+}
+
+for (const key of Object.keys(policyRows)) {
+  if (!commanderKeys.has(key)) {
+    fail(`policy row \`${key}\` names a verb the CLI no longer has - remove it or restore the command`);
+  }
+}
+
+// Noun coverage: every in-app verb resolves to a declared noun, and every
+// declared noun has at least one in-app verb.
+const inAppNouns = new Set(
+  verbs.filter((v) => policyRows[v.command]?.surface === "both").map(nounOf),
+);
+for (const noun of inAppNouns) {
+  if (!(noun in declaredNouns)) {
+    fail(`noun "${noun}" has in-app verbs but is not declared under "nouns"`);
+  }
+}
+for (const noun of Object.keys(declaredNouns)) {
+  if (!inAppNouns.has(noun)) {
+    fail(`noun "${noun}" is declared but has no verb with surface "both"`);
+  }
+}
+
+// A cli_only verb has nothing to be re-homed into - a `noun` there is a
+// leftover from a split that would silently do nothing.
+for (const [command, row] of Object.entries(policyRows)) {
+  if (row.noun && row.surface !== "both") {
+    fail(`policy row \`${command}\`: "noun" is set but surface is "${row.surface}"`);
+  }
+}
+
+// Identity-parameter exemptions are a checked-in, reviewed fixture: an entry
+// only ever appears as a deliberate edit carrying a written justification.
+for (const [command, params] of Object.entries(identityExemptions)) {
+  if (!commanderKeys.has(command)) {
+    fail(`identity_param_exemptions names \`${command}\`, which the CLI no longer has`);
+    continue;
+  }
+  for (const [param, reason] of Object.entries(params)) {
+    if (!String(reason ?? "").trim()) {
+      fail(`identity_param_exemptions \`${command}\`.${param} has no justification`);
+    }
+  }
+}
+
+exitOnErrors();
+
+// ------------------------------------------------------------ build the tools
+
+/** A single verb becomes one action: its name is the CLI path below the noun,
+ *  verbatim ("create metric", "update-html"). A noun that is itself invocable
+ *  (`query`, `status`) names its one action after itself. */
+function actionName(verb) {
+  return verb.action || verb.group;
+}
+
+const tools = [];
+const exclusions = [];
+
+for (const noun of Object.keys(declaredNouns)) {
+  const nounVerbs = verbs.filter(
+    (v) => nounOf(v) === noun && policyRows[v.command].surface === "both",
+  );
+
+  const actions = [];
+  // name -> { schema, descriptions: Map<description, Set<action>>, forms: Map<action, form> }
+  //
+  // `forms` is per-action, not per-parameter: one property name can be a
+  // positional on one action and a flag on another (`name` is `<name>` on
+  // `update metric` and `--name` on `create metric`). Collapsing that to a
+  // single record told the adapter the wrong CLI form for 12 pairs.
+  const params = new Map();
+
+  const addParam = (name, schema, description, action, command, form) => {
+    if (
+      TENANT_PARAM_DENYLIST.some((re) => re.test(name)) &&
+      !identityExemptions[command]?.[name]
+    ) {
+      fail(
+        `\`${noun} ${action}\`: parameter "${name}" looks like caller identity. ` +
+        `Tenancy is bound from the authenticated session, never from a model-supplied argument. ` +
+        `If it genuinely filters within the caller's own org, add a justified entry to ` +
+        `identity_param_exemptions in verb-policy-source.json.`,
+      );
+      return;
+    }
+    if (!String(description ?? "").trim()) {
+      fail(
+        `\`${noun} ${action}\`: parameter "${name}" has no description. ` +
+        `Write one at the source in cli/src/commands/ - the generator will not invent it.`,
+      );
+      return;
+    }
+    if (!params.has(name)) {
+      params.set(name, { schema, descriptions: new Map(), forms: new Map() });
+    }
+    const entry = params.get(name);
+    if (JSON.stringify(entry.schema) !== JSON.stringify(schema)) {
+      fail(
+        `\`${noun}\`: parameter "${name}" is ${JSON.stringify(entry.schema)} for one action and ` +
+        `${JSON.stringify(schema)} for \`${action}\`. Reconcile the flag types at the source.`,
+      );
+    }
+    if (!entry.descriptions.has(description)) entry.descriptions.set(description, new Set());
+    entry.descriptions.get(description).add(action);
+    entry.forms.set(action, form);
+  };
+
+  for (const verb of nounVerbs) {
+    const action = actionName(verb);
+    const required = [];
+    const optional = [];
+
+    for (const arg of verb.args) {
+      const name = paramName(arg.name);
+      addParam(name, argSchema(arg), arg.description, action, verb.command, {
+        cli_token: arg.variadic ? `${arg.name}...` : arg.name,
+        positional: true,
+        required: arg.required,
+        variadic: arg.variadic,
+      });
+      (arg.required ? required : optional).push(name);
+    }
+    for (const opt of verb.options) {
+      const name = paramName(opt.long || opt.flags);
+      addParam(name, optionSchema(opt), opt.description, action, verb.command, {
+        cli_flag: opt.long || opt.flags,
+        positional: false,
+        // `.requiredOption()`. The CLI rejects the command without it, so the
+        // model must be told it is required or it will omit it.
+        required: opt.mandatory,
+        variadic: opt.variadic || Array.isArray(opt.defaultValue),
+        negated: opt.negated,
+        default: opt.defaultValue ?? null,
+      });
+      (opt.mandatory ? required : optional).push(name);
+    }
+    // After the CLI's own, so the doc reads `R id,content` rather than
+    // interleaving an in-app parameter into the command's argument order.
+    for (const [name, spec] of Object.entries(policyRows[verb.command].app_params ?? {})) {
+      if (required.includes(name) || optional.includes(name)) {
+        fail(
+          `\`${noun} ${action}\`: app_params declares "${name}", which this verb already ` +
+          `has as a flag or argument. An in-app parameter may not shadow a real one.`,
+        );
+        continue;
+      }
+      // Through `addParam` like every other parameter, so an in-app one is held
+      // to the same rules: the tenant denylist still refuses caller identity, a
+      // missing description still fails, and a type that disagrees with another
+      // action's parameter of the same name is still a conflict.
+      addParam(name, { type: spec.type }, spec.description, action, verb.command, {
+        app_only: true,
+        required: Boolean(spec.required),
+      });
+      (spec.required ? required : optional).push(name);
+    }
+
+    actions.push({
+      name: action,
+      command: verb.command,
+      summary: firstSentence(verb.description),
+      required: [...new Set(required)],
+      optional: [...new Set(optional)].filter((p) => !required.includes(p)),
+    });
+  }
+
+  if (actions.length > MAX_ACTIONS_PER_NOUN) {
+    fail(
+      `noun "${noun}" has ${actions.length} actions, over the ceiling of ${MAX_ACTIONS_PER_NOUN}. ` +
+      `Split it by lifecycle (read vs authoring) - do not reach for oneOf.`,
+    );
+  }
+
+  // Merge each parameter's descriptions. Identical across actions -> one line.
+  // Genuinely different -> the action names that own each meaning, prefixed.
+  // Concatenation only; no sentence is rewritten.
+  const properties = {
+    action: {
+      type: "string",
+      enum: actions.map((a) => a.name),
+      description: `Which ${noun} operation to run. Every other parameter belongs to exactly one action - the tool description lists which.`,
+    },
+  };
+  const paramIndex = {};
+  for (const [name, entry] of [...params.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const variants = [...entry.descriptions.entries()];
+    const description =
+      variants.length === 1
+        ? variants[0][0]
+        : variants
+            .map(([desc, acts]) => `${[...acts].sort().join("/")}: ${desc}`)
+            .join(" | ");
+    properties[name] = { ...entry.schema, description };
+    // Sorted so a re-ordered walk cannot change the emitted bytes.
+    paramIndex[name] = {
+      actions: [...entry.forms.keys()].sort(),
+      forms: Object.fromEntries([...entry.forms.entries()].sort(([a], [b]) => a.localeCompare(b))),
+    };
+  }
+
+  // The always-on tool doc. `R` / `o` keep it inside the budget while still
+  // naming every action's own parameter subset (per-action, not one merged bag).
+  const docLines = [
+    `${declaredNouns[noun]}. Set \`action\`, then only that action's parameters (R = required, o = optional).`,
+  ];
+  for (const a of actions) {
+    const parts = [];
+    if (a.required.length) parts.push(`R ${a.required.join(",")}`);
+    if (a.optional.length) parts.push(`o ${a.optional.join(",")}`);
+    const summary = restatesActionName(a.summary, a.name) ? "" : ` ${a.summary}`;
+    docLines.push(`${a.name}:${summary}${parts.length ? ` [${parts.join("; ")}]` : ""}`);
+  }
+  const description = docLines.join("\n");
+
+  if (description.length > MAX_TOOL_DOC_CHARS) {
+    fail(
+      `noun "${noun}" tool doc is ${description.length} chars, over the ${MAX_TOOL_DOC_CHARS} ceiling. ` +
+      `Shorten the verbs' first sentences at the source, or split the noun by lifecycle.`,
+    );
+  }
+
+  tools.push({
+    name: noun,
+    summary: declaredNouns[noun],
+    description,
+    actions,
+    parameters: { type: "object", properties, required: ["action"] },
+    param_index: paramIndex,
+  });
+}
+
+for (const verb of verbs) {
+  const row = policyRows[verb.command];
+  if (row.surface === "both") continue;
+  exclusions.push({
+    command: verb.command,
+    group: verb.group,
+    action: actionName(verb),
+    surface: row.surface,
+    reason: row.reason,
+  });
+}
+
+// ------------------------------------------------------------- emitted policy
+
+const emittedPolicy = {};
+for (const verb of verbs) {
+  const row = policyRows[verb.command];
+  if (row.surface !== "both") continue;
+  emittedPolicy[`${nounOf(verb)}:${actionName(verb)}`] = {
+    tool: nounOf(verb),
+    action: actionName(verb),
+    command: verb.command,
+    surface: row.surface,
+    is_read_only: row.is_read_only,
+    mutation_class: row.mutation_class,
+    requires_approval: row.requires_approval,
+    silent_retry_exempt: row.silent_retry_exempt,
+  };
+}
+
+// ------------------------------------------------------------- hygiene sweeps
+
+const GENERATED_WARNING =
+  "GENERATED FILE - do not hand-edit. Regenerate with: npm --prefix cli run gen:commands";
+
+const manifest = {
+  $warning: GENERATED_WARNING,
+  $source: "cli Commander tree + cli/scripts/verb-policy-source.json",
+  $param_naming:
+    "Property name = the CLI long flag or positional argument, lowercased with '-' and camelCase humps turned into '_'. param_index carries the CLI token back.",
+  $app_params:
+    "A param_index form marked \"app_only\" has no CLI counterpart: it is declared in verb-policy-source.json with a written reason, for a verb whose two surfaces differ in mechanics rather than in capability.",
+  tools,
+  exclusions,
+};
+const policyArtifact = {
+  $warning: GENERATED_WARNING,
+  $source: "cli/scripts/verb-policy-source.json, validated against the Commander tree",
+  $key: "\"<tool>:<action>\" - the same pair the runtime keys mutation class, approval and retry on",
+  verbs: emittedPolicy,
+};
+
+// PE-DENY-001 / PE-DENY-002: no internal reference number or credential reaches a
+// prompt. Sweeps only what the model actually sees - tool docs, summaries and
+// the parameter schema. Exclusion reasons and param_index metadata are read by
+// humans in review and never sent to a model.
+const modelFacing = JSON.stringify(
+  tools.map((t) => ({
+    summary: t.summary,
+    description: t.description,
+    parameters: t.parameters,
+    actions: t.actions.map((a) => a.summary),
+  })),
+);
+const internalHit = modelFacing.match(INTERNAL_REF);
+if (internalHit) {
+  const at = modelFacing.indexOf(internalHit[0]);
+  fail(
+    `emitted tool text carries an internal reference number (PE-DENY-001): ` +
+    `...${modelFacing.slice(Math.max(0, at - 60), at + 60)}...`,
+  );
+}
+const credentialHit = modelFacing.match(CREDENTIAL_SHAPED);
+if (credentialHit) {
+  fail(
+    `emitted tool text looks like it carries a credential (PE-DENY-002): ` +
+    `"${credentialHit[0].slice(0, 40)}...". Descriptions teach shapes, never values.`,
+  );
+}
+
+// Schema shape. Both of these are invariants over what the emitters may produce,
+// not gates that today's emitters can trip: nothing here builds an object-typed
+// property or an additionalProperties key. They exist so that adding a param
+// type later cannot silently ship a declaration Gemini rejects outright
+// (additionalProperties) or fails on with MALFORMED_FUNCTION_CALL (untyped
+// object). The reachable version of this check lives in the CLI test suite.
+for (const tool of tools) {
+  if (JSON.stringify(tool.parameters).includes("additionalProperties")) {
+    fail(`\`${tool.name}\`: emitted schema contains additionalProperties`);
+  }
+  for (const [name, schema] of Object.entries(tool.parameters.properties)) {
+    const inner = schema.type === "array" ? schema.items : schema;
+    if (inner?.type === "object") {
+      fail(`\`${tool.name}\`: parameter "${name}" is an untyped object`);
+    }
+  }
+}
+
+exitOnErrors();
+
+// --------------------------------------------------------------------- write
+
+const nextManifest = formatJson(manifest);
+const nextPolicy = formatJson(policyArtifact);
+
+if (toStdout) {
+  // No process.exit() after this write: on a pipe, exiting before stdout
+  // drains truncates the output, and the determinism check compares whole files.
+  process.stdout.write(nextManifest);
+} else {
+  if (!existsSync(outDir)) {
+    throw new Error(
+      `generated package not found at ${outDir} - the platform_agent tools package must exist before artifacts are written`,
+    );
+  }
+
+  const current = {
+    manifest: existsSync(manifestPath) ? readFileSync(manifestPath, "utf-8").replace(/\r\n/g, "\n") : "",
+    policy: existsSync(policyOutPath) ? readFileSync(policyOutPath, "utf-8").replace(/\r\n/g, "\n") : "",
+  };
+
+  if (current.manifest === nextManifest && current.policy === nextPolicy) {
+    console.error("Tool manifest and verb policy are in sync.");
+  } else if (checkOnly) {
+    console.error(
+      "Generated tool manifest / verb policy is stale - run: npm --prefix cli run gen:commands",
+    );
+    process.exit(1);
+  } else {
+    writeFileSync(manifestPath, nextManifest, "utf-8");
+    writeFileSync(policyOutPath, nextPolicy, "utf-8");
+    console.error(
+      `Wrote ${tools.length} tools (${Object.keys(emittedPolicy).length} actions) and ${exclusions.length} exclusions to ${outDir}`,
+    );
+  }
+}