@nanobpm/nano-workforce 0.158.1 → 0.159.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.158.1",
+  "version": "0.159.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -49,6 +49,8 @@
     "layout:check": "node --experimental-strip-types scripts/layout-bpmn.ts --check",
     "sync:nav": "node --experimental-strip-types scripts/sync-nav.ts",
     "sync:nav:check": "node --experimental-strip-types scripts/sync-nav.ts --check",
+    "gen:mcp-bodies": "node --experimental-strip-types scripts/inline-mcp-bodies.ts",
+    "check:mcp-bodies": "node --experimental-strip-types scripts/inline-mcp-bodies.ts --check",
     "dev": "urban dev",
     "pretest": "urban gen",
     "test": "node --experimental-strip-types --test",
@@ -73,7 +75,8 @@
     "conventional-changelog-conventionalcommits": "^8.0.0",
     "linkedom": "^0.18.13",
     "semantic-release": "^25.0.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "yaml": "^2.9.0"
   },
   "overrides": {
     "@semantic-release/npm": "^13.1.5"

package/scripts/inline-mcp-bodies.ts

@@ -0,0 +1,316 @@
+// Single source of truth for the projected MCP tool INPUT schemas (epic nano-workforce#605, S0).
+//
+// The Urban runtime projects this app's `openapi.yaml` into MCP tools (ADR 0067) — there is
+// intentionally ZERO MCP server code in nwf. The projector (`@nanobpm/urban`
+// `collectOperations` → `toolInputSchema`) copies each operation's request-body schema VERBATIM
+// into the tool's `inputSchema.properties.body`; it does NOT resolve `$ref`s. So a request body
+// authored as `schema: { $ref: "#/components/schemas/DeliveryGraph" }` projects as an opaque
+// `body: { "$ref": … }` a standard MCP client cannot resolve — and, unable to see it is an object,
+// the client stringifies the argument and the door rejects it (`expected object, got string`).
+// The upstream fix (a projector that bundles refs into self-contained schemas) is tracked in
+// nano-ide#501 (P0 #502 self-contained schemas, P1 #503 faithful object-body transport, P2 #504
+// real-spec conformance guard); THIS script is the nwf-side mitigation that keeps the surface
+// callable today: it authors each projected request body as a self-contained, `$ref`-free
+// `type: object` schema INLINE in `openapi.yaml`.
+//
+// Derivation over duplication (AGENTS.md): the `components.schemas` remain the single source of
+// truth. This script DERIVES the inline body by fully dereferencing that component (merging
+// `allOf`, inlining `oneOf` variants, dropping `discriminator` ref-mappings) and splicing the
+// result into the operation's `requestBody` between sentinel markers, in place, without
+// reformatting the rest of the hand-maintained file. Re-run it whenever a source component
+// changes:
+//
+//   node --experimental-strip-types scripts/inline-mcp-bodies.ts          # write openapi.yaml
+//   node --experimental-strip-types scripts/inline-mcp-bodies.ts --check  # verify (CI)
+//
+// The convention every projected request-body operation MUST follow (and every later slice that
+// adds one inherits): author the body as a SINGLE top-level `$ref` to a `components.schemas` entry,
+// yielding a `type: object` with inline `properties`, NO `$ref` in the projected schema, and a
+// description that carries the contract; the graph doors (`compileDeliveryGraph`/
+// `previewDeliveryGraph`) additionally carry a worked `example` (enforced by
+// `test/mcp-tool-schemas.test.ts`). `test/mcp-tool-schemas.test.ts` is the runtime drift guard — it
+// runs the REAL urban projector over the spec and fails if any projected tool body reintroduces a
+// `$ref` or loses its explicit type.
+//
+// Drift detection survives inlining: the generated `# BEGIN` sentinel records the source component
+// (`source=#/components/schemas/…`), so on every subsequent run the generator re-derives the inline
+// body from the CURRENT component — even though the operation's `schema:` no longer carries a
+// `$ref` — and `--check` fails if a source component changed but its inline body was not
+// regenerated. (Without the recorded source the check would be a permanent false green: once the
+// `$ref` is inlined there is nothing left to re-derive from.)
+//
+// Mirrors the repo's other derive/verify pairs (layout-bpmn --check, sync-nav --check,
+// check-contracts / reconcile-contracts).
+import { readFileSync, writeFileSync } from "node:fs";
+import process from "node:process";
+// `yaml` (eemeli) is the SAME parser `@nanobpm/urban` uses to read this spec at runtime
+// (openapi/spec.ts), so a round-trip here matches what the projector sees.
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+const SPEC_PATH = `${ROOT}openapi.yaml`;
+
+const BEGIN_PREFIX = "# BEGIN generated:mcp-body";
+const BEGIN_TAIL = "(scripts/inline-mcp-bodies.ts — do not hand-edit)";
+const END = "# END generated:mcp-body";
+
+/** The `# BEGIN` sentinel for a block, embedding the source component so a later run can re-derive. */
+function beginMarker(sourceRef: string): string {
+  return `${BEGIN_PREFIX} source=${sourceRef} ${BEGIN_TAIL}`;
+}
+
+type Schema = Record<string, unknown>;
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+const HTTP_METHODS = ["get", "put", "post", "delete", "patch"] as const;
+
+/**
+ * Fully dereference a schema against `components.schemas`, producing a `$ref`-free equivalent:
+ *  - a `$ref` is replaced by the (recursively dereferenced) target component;
+ *  - an `allOf` is MERGED into one object (union of `properties`/`required`) so a node variant
+ *    like `DeliveryNodeAgent` (allOf [DeliveryNodeCommon, {inline}]) becomes one flat `type: object`;
+ *  - `oneOf`/`anyOf` members are dereferenced but kept as a union;
+ *  - `discriminator` is dropped (its `mapping` values are `#/components/...` pointers that would
+ *    dangle once inlined, and MCP clients do not need it);
+ *  - every other keyword is copied through, recursing into `properties`/`items`/arrays.
+ * Cycles (none today) are guarded by the visited-name set.
+ */
+function deref(node: unknown, comps: Record<string, unknown>, seen: ReadonlySet<string>): unknown {
+  if (Array.isArray(node)) return node.map((n) => deref(n, comps, seen));
+  if (!isRecord(node)) return node;
+
+  if (typeof node.$ref === "string") {
+    const m = node.$ref.match(/^#\/components\/schemas\/(.+)$/);
+    if (!m) throw new Error(`non-local $ref cannot be inlined: ${node.$ref}`);
+    const name = m[1];
+    if (seen.has(name)) throw new Error(`cyclic $ref: ${name}`);
+    const target = comps[name];
+    if (!target) throw new Error(`dangling $ref: ${node.$ref}`);
+    return deref(target, comps, new Set(seen).add(name));
+  }
+
+  if (Array.isArray(node.allOf)) {
+    const props: Record<string, unknown> = {};
+    const required: string[] = [];
+    const merged: Schema = { type: "object", properties: props, required };
+    let additionalProperties: unknown;
+    for (const part of node.allOf) {
+      const d = deref(part, comps, seen);
+      if (!isRecord(d)) continue;
+      if (isRecord(d.properties)) Object.assign(props, d.properties);
+      if (Array.isArray(d.required)) {
+        for (const r of d.required) if (typeof r === "string") required.push(r);
+      }
+      if ("additionalProperties" in d) additionalProperties = d.additionalProperties;
+      if (typeof d.type === "string") merged.type = d.type;
+    }
+    // Sibling keywords authored alongside `allOf` (e.g. `description`) win over the merged parts.
+    for (const [k, v] of Object.entries(node)) {
+      if (k === "allOf") continue;
+      merged[k] = deref(v, comps, seen);
+    }
+    if (required.length === 0) delete merged.required;
+    else merged.required = [...new Set(required)];
+    if (additionalProperties !== undefined && !("additionalProperties" in node)) {
+      merged.additionalProperties = additionalProperties;
+    }
+    return merged;
+  }
+
+  const out: Schema = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (k === "discriminator") continue;
+    out[k] = deref(v, comps, seen);
+  }
+  return out;
+}
+
+/** Does this (raw, un-dereferenced) schema contain a `$ref` anywhere? */
+function hasRef(node: unknown): boolean {
+  if (Array.isArray(node)) return node.some(hasRef);
+  if (!isRecord(node)) return false;
+  if (typeof node.$ref === "string") return true;
+  return Object.values(node).some(hasRef);
+}
+
+/** `false` iff the operation is `x-mcp`-excluded (operator-only door). */
+function isProjected(op: Record<string, unknown>): boolean {
+  const x = op["x-mcp"];
+  if (x === false) return false;
+  if (isRecord(x) && x.exclude === true) return false;
+  return true;
+}
+
+interface Target {
+  operationId: string;
+  sourceRef: string;
+  inline: Schema;
+}
+
+/**
+ * Recover `operationId -> source component $ref` from the `# BEGIN … source=…` sentinels already in
+ * the raw text. This is what lets `--check` keep detecting drift AFTER the `$ref` has been inlined:
+ * the operation's parsed `schema:` no longer carries a `$ref`, but the recorded source does, so the
+ * generator can re-derive the block from the current component. Scans by operation region (the same
+ * indentation-free `operationId:` split `spliceSchema` uses) so a block is attributed to its owner.
+ */
+function recordedSources(text: string): Map<string, string> {
+  const out = new Map<string, string>();
+  const opRe = /^ *operationId: (\S+)/gm;
+  const ops: Array<{ id: string; at: number }> = [];
+  for (let m = opRe.exec(text); m !== null; m = opRe.exec(text)) {
+    ops.push({ id: m[1], at: m.index });
+  }
+  for (let i = 0; i < ops.length; i++) {
+    const end = i + 1 < ops.length ? ops[i + 1].at : text.length;
+    const region = text.slice(ops[i].at, end);
+    const bm = region.match(/# BEGIN generated:mcp-body source=(\S+)/);
+    if (bm) out.set(ops[i].id, bm[1]);
+  }
+  return out;
+}
+
+/**
+ * Collect the projected request-body operations to (re)generate. A body is a managed target when it
+ * is authored as a single top-level `$ref` (first authoring) OR already carries a generated block
+ * whose source component was recorded in its sentinel (subsequent runs). Either way the inline body
+ * is DERIVED from the CURRENT `components.schemas`, so a source-component change is always re-derived
+ * (and caught by `--check`). A projected body that leaks a NON-top-level `$ref` violates the
+ * single-top-level-`$ref` convention and is rejected loudly rather than silently half-inlined.
+ */
+function collectTargets(doc: Record<string, unknown>, recorded: Map<string, string>): Target[] {
+  const comps: Record<string, unknown> =
+    isRecord(doc.components) && isRecord(doc.components.schemas) ? doc.components.schemas : {};
+  const paths = isRecord(doc.paths) ? doc.paths : {};
+  const targets: Target[] = [];
+  for (const item of Object.values(paths)) {
+    if (!isRecord(item)) continue;
+    for (const method of HTTP_METHODS) {
+      const op = item[method];
+      if (!isRecord(op) || typeof op.operationId !== "string") continue;
+      if (!isProjected(op)) continue;
+      const body = isRecord(op.requestBody) ? op.requestBody : undefined;
+      const jsonNode =
+        body && isRecord(body.content) && isRecord(body.content["application/json"])
+          ? body.content["application/json"]
+          : undefined;
+      const json = isRecord(jsonNode) ? jsonNode.schema : undefined;
+      if (!isRecord(json)) continue;
+      let sourceRef: string | undefined;
+      if (typeof json.$ref === "string") {
+        sourceRef = json.$ref;
+      } else if (recorded.has(op.operationId)) {
+        sourceRef = recorded.get(op.operationId);
+      } else {
+        if (hasRef(json)) {
+          throw new Error(
+            `${op.operationId}: projected request body must be authored as a single top-level ` +
+              "`$ref` to a components.schemas entry (found a nested `$ref`) — see the MCP schema " +
+              "convention in openapi.yaml.",
+          );
+        }
+        continue;
+      }
+      if (sourceRef === undefined) continue;
+      const derefed = deref({ $ref: sourceRef }, comps, new Set());
+      const inline: Schema = isRecord(derefed) ? derefed : {};
+      if (typeof inline.type !== "string") {
+        // A `oneOf`/`anyOf` body root has no single `type`; every projected body IS an object, so
+        // pin the explicit `type: object` the MCP contract requires alongside the variant union.
+        inline.type = "object";
+      }
+      targets.push({ operationId: op.operationId, sourceRef, inline });
+    }
+  }
+  targets.sort((a, b) => a.operationId.localeCompare(b.operationId));
+  return targets;
+}
+
+/** Render an inline schema as a YAML block indented to `pad` spaces, wrapped in the sentinels. */
+function renderBlock(inline: Schema, pad: string, sourceRef: string): string {
+  const dumped = stringifyYaml(inline, { indent: 2, lineWidth: 0, singleQuote: true });
+  const body = dumped
+    .replace(/\n$/, "")
+    .split("\n")
+    .map((line) => (line.length ? pad + line : line))
+    .join("\n");
+  return `${pad}${beginMarker(sourceRef)}\n${body}\n${pad}${END}`;
+}
+
+/**
+ * Replace the `requestBody` → `application/json` → `schema:` value of `operationId` in the raw
+ * text with `block`, in place. Returns the new text. Boundaries are found by indentation, the same
+ * span technique `scripts/sync-nav.ts` uses, so nothing else in the file is reformatted.
+ */
+function spliceSchema(text: string, operationId: string, inline: Schema, sourceRef: string): string {
+  const opMarker = `operationId: ${operationId}\n`;
+  const opAt = text.indexOf(opMarker);
+  if (opAt < 0) throw new Error(`operationId not found in text: ${operationId}`);
+  // Bound the search to this operation (up to the next operationId).
+  const nextOp = text.indexOf("operationId: ", opAt + opMarker.length);
+  const region = nextOp < 0 ? text.slice(opAt) : text.slice(opAt, nextOp);
+  const rbRel = region.indexOf("requestBody:");
+  if (rbRel < 0) throw new Error(`requestBody not found for ${operationId}`);
+  // First `schema:` after requestBody is the request body schema.
+  const schemaRel = region.indexOf("schema:", rbRel);
+  if (schemaRel < 0) throw new Error(`request schema not found for ${operationId}`);
+  const schemaAbs = opAt + schemaRel;
+  const lineStart = text.lastIndexOf("\n", schemaAbs) + 1;
+  const schemaIndent = schemaAbs - lineStart; // columns before `schema:`
+  const pad = " ".repeat(schemaIndent + 2); // schema value is nested one level deeper
+  // The schema value spans from the end of the `schema:` line to the first following line whose
+  // indent is <= the `schema:` line's indent (a sibling/closing key), skipping blank lines.
+  const afterSchemaLine = text.indexOf("\n", schemaAbs) + 1;
+  const lines = text.slice(afterSchemaLine).split("\n");
+  let consumed = 0;
+  for (const line of lines) {
+    if (line.trim() === "") {
+      consumed += line.length + 1;
+      continue;
+    }
+    const indent = line.length - line.trimStart().length;
+    if (indent <= schemaIndent) break;
+    consumed += line.length + 1;
+  }
+  const valueEnd = afterSchemaLine + consumed;
+  const block = renderBlock(inline, pad, sourceRef);
+  return `${text.slice(0, afterSchemaLine)}${block}\n${text.slice(valueEnd)}`;
+}
+
+function generate(text: string): string {
+  const parsed = parseYaml(text);
+  const doc: Record<string, unknown> = isRecord(parsed) ? parsed : {};
+  const targets = collectTargets(doc, recordedSources(text));
+  let out = text;
+  for (const t of targets) out = spliceSchema(out, t.operationId, t.inline, t.sourceRef);
+  return out;
+}
+
+function main(): void {
+  const check = process.argv.includes("--check");
+  const original = readFileSync(SPEC_PATH, "utf8");
+  const next = generate(original);
+  if (check) {
+    if (next !== original) {
+      process.stderr.write(
+        "openapi.yaml projected MCP request bodies are STALE.\n" +
+          "A source component schema changed but its inline `body` was not regenerated.\n" +
+          "Run: npm run gen:mcp-bodies (node --experimental-strip-types scripts/inline-mcp-bodies.ts)\n",
+      );
+      process.exit(1);
+    }
+    process.stdout.write("openapi.yaml projected MCP request bodies are up to date.\n");
+    return;
+  }
+  if (next !== original) {
+    writeFileSync(SPEC_PATH, next);
+    process.stdout.write("openapi.yaml projected MCP request bodies regenerated.\n");
+  } else {
+    process.stdout.write("openapi.yaml projected MCP request bodies already up to date.\n");
+  }
+}
+
+main();

package/test/mcp-tool-schemas.test.ts

@@ -0,0 +1,127 @@
+// Drift guard for the projected MCP tool INPUT schemas (epic nano-workforce#605, S0).
+//
+// The Urban runtime projects `openapi.yaml` into MCP tools (ADR 0067) and copies each operation's
+// request-body schema VERBATIM into the tool's `inputSchema.properties.body` — it does NOT resolve
+// `$ref`s. A leaked `$ref` is therefore unresolvable in a standard MCP client, and, unable to see
+// the body is an object, the client stringifies the argument and the door rejects it
+// (`expected object, got string`). This test drives the REAL projector (`collectOperations` from
+// `@nanobpm/urban`, plus the runtime's own `toolInputSchema` shape) over the checked-in spec and
+// fails the build if any projected tool body reintroduces a `$ref`, loses its explicit `type`, or a
+// graph door drops its worked example. It is the runtime counterpart to
+// `scripts/inline-mcp-bodies.ts --check` (which guards the derive step); together they keep the
+// convention every later slice inherits: `type: object`, inline `properties`, no `$ref`, an example.
+//
+// Extension seam: a sibling slice adding a projected request-body operation to `openapi.yaml` needs
+// no change here — this walks EVERY projected operation. A new graph door should be added to
+// GRAPH_DOORS so its example is required too.
+import { test } from "node:test";
+import { assert } from "#test-assert";
+import { readFileSync } from "node:fs";
+import { collectOperations, type OperationInfo, parseSpec } from "@nanobpm/urban/toolkit";
+
+const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+// Parse the spec exactly as the runtime does (`@nanobpm/urban/toolkit` `parseSpec`), so this guard
+// sees precisely the document the MCP projector projects.
+const SPEC = parseSpec(readFileSync(`${ROOT}openapi.yaml`, "utf8"));
+
+/** Graph doors that MUST carry at least one worked example (epic #605 acceptance). */
+const GRAPH_DOORS = new Set(["compileDeliveryGraph", "previewDeliveryGraph"]);
+
+/** The client-visible tool `inputSchema`, reproduced exactly from the runtime's `toolInputSchema`
+ *  (mcp.ts) — path/query params plus the request body copied verbatim under `body`. */
+function toolInputSchema(op: OperationInfo): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const required: string[] = [];
+  for (const p of op.parameters) {
+    if (p.in === "path" || p.in === "query") {
+      properties[p.name] = p.schema ?? {};
+      if (p.required) required.push(p.name);
+    }
+  }
+  if (op.requestBodySchema) {
+    properties.body = op.requestBodySchema;
+    if (op.requestBodyRequired) required.push("body");
+  }
+  const schema: Record<string, unknown> = { type: "object", properties };
+  if (required.length > 0) schema.required = required;
+  return schema;
+}
+
+/** Every `$ref` string reachable in a schema, with a JSON-path for the failure message. */
+function findRefs(node: unknown, path: string, out: string[]): void {
+  if (Array.isArray(node)) {
+    node.forEach((n, i) => findRefs(n, `${path}[${i}]`, out));
+    return;
+  }
+  if (typeof node !== "object" || node === null) return;
+  for (const [k, v] of Object.entries(node)) {
+    if (k === "$ref" && typeof v === "string") out.push(`${path}.$ref -> ${v}`);
+    else findRefs(v, `${path}.${k}`, out);
+  }
+}
+
+const isRecord = (v: unknown): v is Record<string, unknown> =>
+  typeof v === "object" && v !== null && !Array.isArray(v);
+
+/** The projected operations whose tool carries a request body (the object-body tools). */
+function projectedBodyOps(): OperationInfo[] {
+  return collectOperations(SPEC).filter((op) => !op.mcpExcluded && op.requestBodySchema);
+}
+
+test("every projected object-body tool schema is $ref-free (self-contained)", () => {
+  const ops = projectedBodyOps();
+  assert(ops.length >= 10, `expected the full projected object-body surface, saw ${ops.length}`);
+  for (const op of ops) {
+    const refs: string[] = [];
+    findRefs(toolInputSchema(op).properties, `${op.operationId}.properties`, refs);
+    assert(
+      refs.length === 0,
+      `${op.operationId}: projected tool schema leaks $ref(s) a standard MCP client cannot ` +
+        `resolve — inline the component(s) (run npm run gen:mcp-bodies): ${refs.join(", ")}`,
+    );
+  }
+});
+
+test("every projected object-body tool declares an explicit body type: object", () => {
+  for (const op of projectedBodyOps()) {
+    const body = op.requestBodySchema as Record<string, unknown>;
+    // A `oneOf`/`anyOf` body still carries an explicit `type: object` (the generator pins it) so a
+    // client knows to pass an object, not a string.
+    assert(
+      body.type === "object",
+      `${op.operationId}: request body must declare an explicit \`type: object\` (saw ` +
+        `type=${JSON.stringify(body.type)})`,
+    );
+    assert(
+      isRecord(body.properties) || Array.isArray(body.oneOf) || Array.isArray(body.anyOf),
+      `${op.operationId}: request body must expose inline \`properties\` (or a \`oneOf\`/\`anyOf\` ` +
+        "of object variants) so the shape is discoverable from the tool surface",
+    );
+  }
+});
+
+test("each graph door carries at least one worked example", () => {
+  const byId = new Map(projectedBodyOps().map((op) => [op.operationId, op]));
+  for (const door of GRAPH_DOORS) {
+    const op = byId.get(door);
+    assert(op, `expected graph door ${door} to be a projected object-body tool`);
+    const body = op!.requestBodySchema as Record<string, unknown>;
+    const hasExample =
+      "example" in body ||
+      "examples" in body ||
+      (isRecord(body.properties) &&
+        Object.values(body.properties).some((p) => isRecord(p) && "example" in p));
+    assert(hasExample, `${door}: request body must embed a worked \`example\` (§9.5 canonical graph)`);
+  }
+});
+
+test("operator-only delivery-graph doors stay withheld from the MCP tool surface", () => {
+  const excluded = new Set(
+    collectOperations(SPEC)
+      .filter((op) => op.mcpExcluded)
+      .map((op) => op.operationId),
+  );
+  for (const door of ["stageDeliveryGraph", "dispatchDeliveryGraph", "dismissProposal"]) {
+    assert(excluded.has(door), `${door} must remain x-mcp-excluded (operator-only dispatch gate)`);
+  }
+});