@autoview/cli 0.1.0

package/src/agent/emitMcpServer.ts

@@ -0,0 +1,178 @@
+import { OpenApi } from "@typia/interface";
+
+import { buildToolSurface, coverToolSurface } from "./toolSurface";
+
+/**
+ * Emit a runnable MCP (Model Context Protocol) server from an OpenAPI document —
+ * the agent-facing counterpart of the generated frontend. The server exposes the
+ * shaped tool surface (read/write annotations + producer hints) and, on a tool
+ * call, executes the real API over HTTP against the configured backend.
+ *
+ * Returns a flat `path → content` project map (server + package.json + README),
+ * the same shape the frontend scaffold returns, so the CLI writes it the same
+ * way. Deterministic: same document → same server.
+ */
+export function emitMcpServer(
+  document: OpenApi.IDocument,
+  options: { backend: string | null; title?: string } = { backend: null },
+): Record<string, string> {
+  const tools = buildToolSurface(document);
+  const coverage = coverToolSurface(tools);
+  const appName = (options.title ?? document.info?.title ?? "API").trim() || "API";
+  // Only the fields the server needs at runtime (keep the bundle lean).
+  const runtimeTools = tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+    annotations: t.annotations,
+    operation: t.operation,
+  }));
+
+  return {
+    "server.mjs": renderServer(appName, options.backend, runtimeTools),
+    "package.json": renderPackageJson(appName),
+    "README.md": renderReadme(appName, options.backend, coverage),
+  };
+}
+
+function renderServer(
+  appName: string,
+  backend: string | null,
+  tools: unknown[],
+): string {
+  return `#!/usr/bin/env node
+// MCP server generated by AutoView from the OpenAPI document of "${appName}".
+// Exposes the API as agent-callable tools and executes calls against the live
+// backend. Configure the backend with API_HOST / API_TOKEN env vars.
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const TOOLS = ${JSON.stringify(tools, null, 2)};
+
+const BASE = (process.env.API_HOST ?? ${JSON.stringify(backend ?? "")}).replace(/\\/$/, "");
+const AUTH = process.env.API_TOKEN ?? "";
+
+if (BASE.length === 0) {
+  console.error("Set API_HOST to the backend base URL (e.g. https://api.example.com).");
+  process.exit(1);
+}
+
+const server = new Server(
+  { name: ${JSON.stringify(appName + " (AutoView MCP)")}, version: "1.0.0" },
+  { capabilities: { tools: {} } },
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+    annotations: t.annotations,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const tool = TOOLS.find((t) => t.name === req.params.name);
+  if (tool === undefined) {
+    return { content: [{ type: "text", text: "Unknown tool: " + req.params.name }], isError: true };
+  }
+  const args = req.params.arguments ?? {};
+  let path = tool.operation.path;
+  for (const p of tool.operation.pathParams) {
+    path = path.replace("{" + p + "}", encodeURIComponent(String(args[p] ?? "")));
+  }
+  const url = new URL(BASE + path);
+  if (tool.operation.hasQuery && args.query && typeof args.query === "object") {
+    for (const [k, v] of Object.entries(args.query)) {
+      if (v !== undefined && v !== null) url.searchParams.set(k, String(v));
+    }
+  }
+  const method = tool.operation.method;
+  try {
+    const res = await fetch(url, {
+      method,
+      headers: { "content-type": "application/json", ...(AUTH ? { authorization: AUTH } : {}) },
+      body: ["GET", "HEAD", "DELETE"].includes(method) ? undefined : JSON.stringify(args.body ?? {}),
+    });
+    const text = await res.text();
+    return { content: [{ type: "text", text: text.length > 0 ? text : "(empty) status " + res.status }], isError: !res.ok };
+  } catch (err) {
+    return { content: [{ type: "text", text: "Request failed: " + (err && err.message ? err.message : String(err)) }], isError: true };
+  }
+});
+
+await server.connect(new StdioServerTransport());
+console.error(${JSON.stringify(appName)} + " MCP server ready (" + TOOLS.length + " tools) → " + BASE);
+`;
+}
+
+function renderPackageJson(appName: string): string {
+  const slug = appName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "api";
+  return JSON.stringify(
+    {
+      name: `${slug}-mcp`,
+      version: "1.0.0",
+      private: true,
+      type: "module",
+      bin: { [`${slug}-mcp`]: "./server.mjs" },
+      scripts: { start: "node server.mjs" },
+      dependencies: { "@modelcontextprotocol/sdk": "^1.0.0" },
+    },
+    null,
+    2,
+  );
+}
+
+function renderReadme(
+  appName: string,
+  backend: string | null,
+  coverage: ReturnType<typeof coverToolSurface>,
+): string {
+  return [
+    `# ${appName} — MCP server`,
+    "",
+    "Generated by AutoView. Exposes the API as agent-callable tools (read/write",
+    "annotated, with producer hints) and executes calls against the live backend.",
+    "",
+    "## Run",
+    "",
+    "```bash",
+    "npm install",
+    `API_HOST=${backend ?? "https://api.example.com"} \\`,
+    '  API_TOKEN="Bearer <token>" \\',
+    "  npm start",
+    "```",
+    "",
+    "## Wire into an agent (Claude Desktop / Cursor / Claude Code)",
+    "",
+    "```json",
+    JSON.stringify(
+      {
+        mcpServers: {
+          [appName.toLowerCase().replace(/[^a-z0-9]+/g, "-")]: {
+            command: "node",
+            args: ["server.mjs"],
+            env: { API_HOST: backend ?? "https://api.example.com", API_TOKEN: "Bearer <token>" },
+          },
+        },
+      },
+      null,
+      2,
+    ),
+    "```",
+    "",
+    "## Surface",
+    "",
+    `- **${coverage.tools}** tools (${coverage.readTools} read, ${coverage.writeTools} write)`,
+    `- **${coverage.resolvedInputs}/${coverage.referenceInputs}** id inputs have a declared producer (navigable)`,
+    coverage.orphanInputs > 0
+      ? `- ⚠️ **${coverage.orphanInputs}** id inputs have NO producer in the API — an agent cannot obtain them from any tool (an API-design gap; see \`--report\`).`
+      : "- ✅ every id input is obtainable from another tool (fully navigable).",
+    "",
+  ].join("\n");
+}

package/src/agent/emitReport.ts

@@ -0,0 +1,117 @@
+import { OpenApi } from "@typia/interface";
+
+import { unsupportedOperations } from "../utils/toEndpoints";
+import { analyzeConsumability } from "./toolSurface";
+
+/**
+ * Consumability report — the deterministic, LLM-free verdict on whether an API
+ * can actually be driven as a product (by an agent or a generated UI).
+ *
+ * Unlike a contract test (which checks each endpoint in isolation), this checks
+ * the API as a *navigable graph*: every id input a tool needs should be
+ * obtainable from another tool. It is honest about its own limits — an id whose
+ * producing endpoint returns an un-introspectable inline schema is reported as
+ * "undetermined", not as a defect, so the report never falsely accuses an API.
+ *
+ * Returns Markdown. Pure and deterministic.
+ */
+export function emitConsumabilityReport(document: OpenApi.IDocument): string {
+  const title = (document.info?.title ?? "API").trim() || "API";
+  const a = analyzeConsumability(document);
+  // Judgeable id inputs = those we can rule on: obtainable (resolved + nested)
+  // vs a genuine gap (orphan). userInput/untraceable are not entity-id gaps.
+  const obtainable = a.resolved + a.nested;
+  const denom = obtainable + a.orphan.length;
+  const navigable = denom > 0 ? Math.round((100 * obtainable) / denom) : 100;
+  const dropped = unsupportedOperations(document);
+
+  const lines: string[] = [
+    `# Consumability report — ${title}`,
+    "",
+    "Can this API be driven as a product? Checked deterministically (no LLM) by",
+    "projecting the spec into an agent tool surface and verifying the call graph —",
+    "every id a tool needs should be obtainable from another tool.",
+    "",
+    "## Summary",
+    "",
+    `- **${a.tools}** operations (${a.readTools} read, ${a.writeTools} write); **${a.referenceInputs}** id inputs.`,
+    `- ✅ **${a.resolved}** inputs resolved — a list/search tool produces the id, and the surface tells the agent which one.`,
+    a.nested > 0
+      ? `- ✅ **${a.nested}** obtainable nested — the id appears inside a parent read's response (e.g. \`order\` → \`goods[].id\`); navigable, just not via a dedicated list tool.`
+      : null,
+    a.orphan.length === 0
+      ? "- ✅ **0** genuine orphan inputs."
+      : `- ⚠️ **${a.orphan.length}** orphan inputs — a required id NO endpoint can supply (design gap).`,
+    a.untraceable.length > 0
+      ? `- ❔ **${a.untraceable.length}** undetermined — the resource is read but no id could be traced in its (often inline) response; navigability not provable either way.`
+      : null,
+    a.userInputs.length > 0
+      ? `- 👤 **${a.userInputs.length}** caller-supplied keys (\`*_name\` / \`*_key\` / \`scope\` …) — not entity ids, so a missing producer is expected, not a gap.`
+      : null,
+    `- **Navigability (of judgeable inputs): ${navigable}%** (${obtainable}/${denom}).`,
+    dropped.length > 0
+      ? `- **${dropped.length}** operation(s) could not be exposed at all (unsupported shape).`
+      : null,
+    "",
+  ].filter((l): l is string => l !== null);
+
+  if (a.orphan.length > 0) {
+    lines.push(
+      "## ⚠️ Orphan inputs (genuine design gaps)",
+      "",
+      "These tools require an id, but **no endpoint reads that resource** — nothing",
+      "in the API can supply the value. An agent or UI cannot call them without an",
+      "out-of-band id. Usually a missing list/detail endpoint, or an id named",
+      "inconsistently with its resource.",
+      "",
+    );
+    for (const o of a.orphan.slice(0, 50)) {
+      lines.push(`- \`${o.tool}\` needs \`${o.param}\` (a \`${o.resource}\` id) — no endpoint produces it.`);
+    }
+    if (a.orphan.length > 50) lines.push(`- …and ${a.orphan.length - 50} more.`);
+    lines.push("");
+  }
+
+  if (a.untraceable.length > 0) {
+    lines.push(
+      "## ❔ Undetermined inputs",
+      "",
+      "The resource has a read endpoint, but its response is an inline schema this",
+      "analysis does not model, so the producer link could not be traced. Not a",
+      "reported defect — likely fine, just not machine-verified here.",
+      "",
+      `- ${a.untraceable.length} inputs across ${new Set(a.untraceable.map((u) => u.resource)).size} resources (e.g. ${[...new Set(a.untraceable.slice(0, 5).map((u) => u.resource))].join(", ")}).`,
+      "",
+    );
+  }
+
+  if (a.userInputs.length > 0) {
+    lines.push(
+      "## 👤 Caller-supplied keys",
+      "",
+      "These path params are human-known keys (a name, a `scope`, a `template_key`),",
+      "not entity ids chained from another endpoint. The caller already knows the",
+      "value, so the absence of a producing tool is by design — not a gap.",
+      "",
+      `- ${a.userInputs.length} inputs across ${new Set(a.userInputs.map((u) => u.param)).size} key(s) (e.g. ${[...new Set(a.userInputs.slice(0, 6).map((u) => `\`${u.param}\``))].join(", ")}).`,
+      "",
+    );
+  }
+
+  if (dropped.length > 0) {
+    lines.push("## Unexposed operations", "");
+    for (const d of dropped.slice(0, 20)) lines.push(`- \`${d.method} ${d.path}\` — ${d.reason}`);
+    if (dropped.length > 20) lines.push(`- …and ${dropped.length - 20} more.`);
+    lines.push("");
+  }
+
+  lines.push(
+    "## Verdict",
+    "",
+    a.orphan.length === 0
+      ? "✅ No genuine consumability gaps found — every id a tool needs is obtainable from the API (within what could be analyzed)."
+      : `⚠️ ${a.orphan.length} input(s) cannot be supplied by the API. Add the missing list/detail endpoints (or align id field names) so every id is obtainable, then re-run.`,
+    "",
+  );
+  return lines.join("\n");
+}

package/src/agent/toolSurface.test.ts

@@ -0,0 +1,243 @@
+import { OpenApiConverter } from "@typia/utils";
+import { describe, expect, it } from "vitest";
+
+import { analyzeConsumability, buildToolSurface, coverToolSurface } from "./toolSurface";
+
+function doc(paths: Record<string, unknown>, schemas: Record<string, unknown> = {}) {
+  return OpenApiConverter.upgradeDocument({
+    openapi: "3.0.0",
+    info: { title: "t", version: "1.0.0" },
+    paths,
+    components: { schemas },
+  } as never);
+}
+
+const ok = { 200: { description: "ok" } };
+const listResp = (item: string) => ({
+  200: {
+    description: "ok",
+    content: { "application/json": { schema: { type: "array", items: { $ref: `#/components/schemas/${item}` } } } },
+  },
+});
+const objResp = (name: string) => ({
+  200: { description: "ok", content: { "application/json": { schema: { $ref: `#/components/schemas/${name}` } } } },
+});
+const param = (n: string) => ({ name: n, in: "path", required: true, schema: { type: "string" } });
+
+const fixture = doc(
+  {
+    "/sales": {
+      get: { operationId: "index", summary: "List sales.", responses: listResp("Sale") },
+      post: { operationId: "create", summary: "Create a sale.", requestBody: { content: { "application/json": { schema: { $ref: "#/components/schemas/Sale" } } } }, responses: ok },
+    },
+    "/sales/{saleId}": {
+      get: { operationId: "at", summary: "Get a sale.", parameters: [param("saleId")], responses: objResp("Sale") },
+      delete: { operationId: "erase", summary: "Delete a sale.", parameters: [param("saleId")], responses: ok },
+    },
+    "/sales/{saleId}/questions": {
+      get: { operationId: "index", summary: "List questions on a sale.", parameters: [param("saleId")], responses: listResp("Question") },
+    },
+  },
+  {
+    Sale: { type: "object", properties: { id: { type: "string" }, title: { type: "string" } }, required: ["id"] },
+    Question: { type: "object", properties: { id: { type: "string" }, body: { type: "string" } }, required: ["id"] },
+  },
+);
+
+describe("buildToolSurface", () => {
+  const tools = buildToolSurface(fixture);
+  // nestia accessors are method-derived: `/sales` GET → sales.get, POST →
+  // sales.post, `/sales/{saleId}` DELETE → sales.eraseBySaleid, etc.
+  const list = tools.find((t) => t.name === "sales.get")!;
+  const create = tools.find((t) => t.name === "sales.post")!;
+  const erase = tools.find((t) => t.name === "sales.eraseBySaleid")!;
+  const questions = tools.find((t) => t.name === "sales.questions.getBySaleid")!;
+
+  it("tags read vs write (and destructive) so an agent can tell them apart", () => {
+    expect(list.annotations.readOnlyHint).toBe(true);
+    expect(list.description).toContain("[READ]");
+    expect(create.annotations.readOnlyHint).toBe(false);
+    expect(create.description).toContain("[WRITE");
+    expect(erase.annotations.destructiveHint).toBe(true);
+  });
+
+  it("declares the producer chain for an id input (not left for the agent to guess)", () => {
+    // the questions list needs a saleId — it comes from the sales list's id
+    expect(questions.producers).toEqual([
+      { param: "saleId", tool: "sales.get", field: "id" },
+    ]);
+    expect(questions.inputSchema.required).toContain("saleId");
+    expect(questions.inputSchema.properties.saleId).toMatchObject({ type: "string" });
+    expect((questions.inputSchema.properties.saleId as { description: string }).description).toContain("sales.get");
+  });
+
+  it("a create tool carries a body input", () => {
+    expect(create.inputSchema.required).toContain("body");
+    expect(create.operation.hasBody).toBe(true);
+  });
+
+  it("coverage reports the navigable fraction (producer-resolved inputs)", () => {
+    const cov = coverToolSurface(tools);
+    expect(cov.tools).toBe(tools.length);
+    expect(cov.readTools + cov.writeTools).toBe(tools.length);
+    // every path param here is resolvable (sales + questions both trace to sales.index)
+    expect(cov.resolvedInputs).toBe(cov.referenceInputs);
+    expect(cov.orphanInputs).toBe(0);
+  });
+
+  it("is deterministic", () => {
+    expect(buildToolSurface(fixture)).toEqual(buildToolSurface(fixture));
+  });
+});
+
+describe("analyzeConsumability", () => {
+  it("splits id inputs into resolved vs genuine orphan (no reader)", () => {
+    const d = doc(
+      {
+        // sales are listed → questions' saleId is resolvable
+        "/sales": { get: { operationId: "index", responses: listResp("Sale") } },
+        "/sales/{saleId}/questions": { get: { operationId: "index", parameters: [param("saleId")], responses: listResp("Question") } },
+        // imports are NEVER read → importId is a genuine orphan (nothing produces it)
+        "/imports/{importId}/process": { post: { operationId: "process", parameters: [param("importId")], responses: ok } },
+      },
+      {
+        Sale: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+        Question: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+      },
+    );
+    const a = analyzeConsumability(d);
+    expect(a.resolved).toBeGreaterThanOrEqual(1); // saleId
+    expect(a.orphan.some((o) => o.param === "importId")).toBe(true); // genuine gap
+    expect(a.orphan.some((o) => o.param === "saleId")).toBe(false);
+  });
+
+  it("resolves an id obtainable nested inside a parent's response (not an orphan)", () => {
+    // `goods` has NO dedicated list/detail endpoint, but an order's detail
+    // returns `goods: Good[]` — so a goodId IS obtainable (nested), not orphan.
+    const d = doc(
+      {
+        "/orders": { get: { operationId: "index", responses: listResp("Order") } },
+        "/orders/{orderId}": { get: { operationId: "at", parameters: [param("orderId")], responses: objResp("Order") } },
+        "/orders/{orderId}/goods/{goodId}/cancel": {
+          post: { operationId: "cancel", parameters: [param("orderId"), param("goodId")], responses: ok },
+        },
+      },
+      {
+        Order: {
+          type: "object",
+          properties: { id: { type: "string" }, goods: { type: "array", items: { $ref: "#/components/schemas/Good" } } },
+          required: ["id"],
+        },
+        Good: { type: "object", properties: { id: { type: "string" }, name: { type: "string" } }, required: ["id"] },
+      },
+    );
+    const a = analyzeConsumability(d);
+    expect(a.orphan.some((o) => o.param === "goodId")).toBe(false);
+    expect(a.orphan).toHaveLength(0);
+  });
+
+  it("separates a caller-supplied key from a genuine id orphan", () => {
+    // Neither resource is read. But `template_key` is a human-known key (caller
+    // supplies it), whereas `widget_id` is an entity id nothing produces — only
+    // the latter is a real consumability gap.
+    const d = doc(
+      {
+        "/templates/{template_key}/apply": { post: { operationId: "apply", parameters: [param("template_key")], responses: ok } },
+        "/widgets/{widget_id}/process": { post: { operationId: "process", parameters: [param("widget_id")], responses: ok } },
+      },
+      {},
+    );
+    const a = analyzeConsumability(d);
+    expect(a.orphan.map((o) => o.param)).toEqual(["widget_id"]);
+    expect(a.userInputs.map((u) => u.param)).toEqual(["template_key"]);
+  });
+
+  it("resolves a producer from a resource-named collection wrapper (`{ namespaces: [...] }`)", () => {
+    // a list whose response wraps the array under the resource name (not `data`),
+    // with the id as `uuid` — the producer hint must point at it with field uuid.
+    const d = doc(
+      {
+        "/namespaces": { get: { operationId: "index", responses: { 200: { description: "ok", content: { "application/json": { schema: { type: "object", properties: { namespaces: { type: "array", items: { $ref: "#/components/schemas/Namespace" } } } } } } } } } },
+        "/namespaces/{namespaceId}/process": { post: { operationId: "process", parameters: [param("namespaceId")], responses: ok } },
+      },
+      { Namespace: { type: "object", properties: { uuid: { type: "string" }, label: { type: "string" } }, required: ["uuid"] } },
+    );
+    const a = analyzeConsumability(d);
+    expect(a.orphan).toHaveLength(0);
+    const proc = buildToolSurface(d).find((t) => t.name.includes("process"))!;
+    const hint = proc.producers.find((p) => p.param === "namespaceId");
+    expect(hint).toBeDefined();
+    expect(hint!.field).toBe("uuid"); // the real id field, not a guessed "id"
+  });
+
+  it("does not treat a detail read as a producer of its own id (no circular resolve)", () => {
+    // a resource with ONLY a detail read (no list/search). Its id cannot be
+    // produced — calling the detail already needs it. So it is undetermined,
+    // never `resolved`, and the surface gives no (circular) producer hint.
+    const d = doc(
+      { "/widgets/{widgetId}": { get: { operationId: "at", parameters: [param("widgetId")], responses: objResp("Widget") } } },
+      { Widget: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+    );
+    const a = analyzeConsumability(d);
+    expect(a.resolved).toBe(0);
+    const detail = buildToolSurface(d).find((t) => t.name === "widgets.getByWidgetid")!;
+    expect(detail.producers).toEqual([]);
+  });
+
+  it("does not treat an id-scoped sub-view as a producer of its parent resource", () => {
+    // `/files/{fileId}/trash` classifies under `files` and returns a File id, but
+    // it NEEDS fileId — it cannot enumerate files, so it must not be files' producer.
+    const d = doc(
+      {
+        "/files/{fileId}": { get: { operationId: "at", parameters: [param("fileId")], responses: objResp("File") } },
+        "/files/{fileId}/trash": { get: { operationId: "trash", parameters: [param("fileId")], responses: objResp("File") } },
+      },
+      { File: { type: "object", properties: { id: { type: "string" } }, required: ["id"] } },
+    );
+    const trash = buildToolSurface(d).find((t) => t.name.includes("trash"))!;
+    expect(trash.producers).toEqual([]); // no circular self-producer hint
+  });
+
+  it("the report's resolved count equals the tool surface's producer hints (consistency)", () => {
+    const d = doc(
+      {
+        "/sales": { get: { operationId: "index", responses: listResp("Sale") } },
+        "/sales/{saleId}": { get: { operationId: "at", parameters: [param("saleId")], responses: objResp("Sale") } },
+        "/sales/{saleId}/questions": { get: { operationId: "qi", parameters: [param("saleId")], responses: listResp("Question") } },
+        "/sales/{saleId}/questions/{questionId}": { get: { operationId: "qa", parameters: [param("saleId"), param("questionId")], responses: objResp("Question") } },
+      },
+      {
+        Sale: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+        Question: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+      },
+    );
+    const hints = new Set<string>();
+    for (const t of buildToolSurface(d)) for (const p of t.producers) hints.add(`${t.name}|${p.param}`);
+    const a = analyzeConsumability(d);
+    // the surface hints every navigable input — direct producers + nested ones
+    expect(hints.size).toBe(a.resolved + a.nested);
+  });
+
+  it("hands the agent a nested producer hint with the array path", () => {
+    // goodId lives in an order's `goods[]` — the tool that needs it should be
+    // told to read it from the order detail's response at `goods[].id`.
+    const d = doc(
+      {
+        "/orders": { get: { operationId: "index", responses: listResp("Order") } },
+        "/orders/{orderId}": { get: { operationId: "at", parameters: [param("orderId")], responses: objResp("Order") } },
+        "/orders/{orderId}/goods/{goodId}/cancel": {
+          post: { operationId: "cancel", parameters: [param("orderId"), param("goodId")], responses: ok },
+        },
+      },
+      {
+        Order: { type: "object", properties: { id: { type: "string" }, goods: { type: "array", items: { $ref: "#/components/schemas/Good" } } }, required: ["id"] },
+        Good: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+      },
+    );
+    const cancel = buildToolSurface(d).find((t) => t.name.includes("cancel"))!;
+    const goodHint = cancel.producers.find((p) => p.param === "goodId");
+    expect(goodHint).toBeDefined();
+    expect(goodHint!.field).toBe("goods[].id"); // the nested path to the id
+    expect(goodHint!.tool).toContain("orders"); // produced by an orders read
+  });
+});