webmcp-codegen 0.0.1 → 0.1.0

package/README.md

@@ -1,22 +1,82 @@
 # webmcp-codegen
 
-Generate safe, typed, human-reviewed [WebMCP](https://github.com/webmachinelearning/webmcp) tools from the API contracts you already have — OpenAPI specs, tRPC routers, Zod schemas — instead of hand-writing `registerTool()` calls for every action.
+Generate safe, typed, human-reviewed [WebMCP](https://github.com/webmachinelearning/webmcp) tools from the API contracts you already have — instead of hand-writing `registerTool()` calls for every action.
 
 > Generate the tool. Review the tool. You own the tool.
 
-**Status: under active development.** This package is published as a placeholder to claim the name; the CLI and adapters are being built in the open. Design document: [`notes/webmcp-codegen-design.md`](https://github.com/SouravInsights/groundstate/blob/main/notes/webmcp-codegen-design.md).
-
-## What it will do
+## Quick start
 
 ```bash
-npx webmcp-codegen init       # detect your API layer, scaffold config
-npx webmcp-codegen generate   # generate reviewed, safety-classified tool files
+npm install -D webmcp-codegen
+
+npx webmcp-codegen init       # detects your OpenAPI spec, writes codegen.config.mjs
+npx webmcp-codegen generate   # generates reviewed tool files into ./src/webmcp
+```
+
+Then implement each `execute()` (below the marker — it's yours, regeneration never touches it) and register everything at app startup:
+
+```ts
+import { registerAllTools } from "./webmcp";
+
+await registerAllTools();
 ```
 
-- Real TypeScript files in your repo — readable, editable, no runtime magic
-- Schemas derived from your existing types, never hand-typed twice
-- Automatic risk classification (`readOnlyHint`, `destructiveHint`), PII field detection, and an audit pass built for CI
-- Regeneration that never clobbers your hand-written logic
+## What you get
+
+For every operation in your spec, one file like `get-order-status.webmcp.ts`:
+
+```ts
+// ─── webmcp-codegen: generated — do not edit this region ───
+export const getOrderStatusInputSchema = { /* derived from your spec */ };
+export type GetOrderStatusInput = { orderId: string };
+export const getOrderStatusTool = { name: "get-order-status", /* ... */ };
+export async function registerGetOrderStatus(signal?: AbortSignal) { /* ... */ }
+// ─── webmcp-codegen: end generated — your code below survives regeneration ───
+
+export async function executeGetOrderStatus(input: GetOrderStatusInput) {
+  // You own this. Regeneration never touches it.
+}
+```
+
+- **Real files in your repo** — readable, editable, no runtime magic
+- **Schemas derived from your spec**, never hand-typed twice; `$ref`s fully resolved
+- **Safety classification on every tool** — read/write/destructive from the HTTP verb and naming heuristics, with `readOnlyHint`/`destructiveHint`/`idempotentHint` computed for you
+- **An audit pass built into `generate`** — PII-in-response warnings, agent-instructing description linting, auth-boundary checks; errors block generation (like `npm audit`, with exit codes for CI)
+- **Regeneration never clobbers your code** — contracts regenerate, your `execute()` survives; hand-edited generated regions produce a `.new` file instead of a conflict
+
+## CLI
+
+| Command | What it does |
+|---|---|
+| `webmcp-codegen init` | Detect your spec, write `codegen.config.mjs` |
+| `webmcp-codegen generate` | Generate/update tool files (audit runs by default) |
+| `generate --dry-run` | Preview everything, write nothing |
+| `generate --watch` | Re-generate when source files change |
+| `generate --force` | Write files even when the audit reports errors |
+| `generate --skip-audit` | Skip the audit pass |
+
+## Config
+
+```js
+// codegen.config.mjs
+import { defineConfig } from "webmcp-codegen";
+import { openapi } from "webmcp-codegen/sources";
+import { js } from "webmcp-codegen/generators";
+
+export default defineConfig({
+  sources: [openapi({ spec: "./openapi.yaml" })],
+  generate: [js({ outDir: "./src/webmcp" })],
+  safety: {
+    piiFields: ["internalId"],  // extend the built-in PII heuristics
+    exclude: ["internal"],      // skip tools by name or route substring
+  },
+});
+```
+
+## Requirements
+
+- Node.js ≥ 20
+- To *use* the generated tools in a browser: Chrome 146+ with `#enable-webmcp-testing` (or the WebMCP polyfill)
 
 ## License
 

package/dist/chunk-5L4KN6F4.js

@@ -0,0 +1,109 @@
+// src/schema.ts
+function resolveLocalRef(spec, ref) {
+  if (!ref.startsWith("#/")) {
+    throw new Error(
+      `Cannot resolve external $ref "${ref}". Only local refs (starting with "#/") are supported \u2014 bundle the spec first if it is split across files.`
+    );
+  }
+  let node = spec;
+  for (const segment of ref.slice(2).split("/")) {
+    const key = segment.replace(/~1/g, "/").replace(/~0/g, "~");
+    if (node === null || typeof node !== "object" || !(key in node)) {
+      throw new Error(`$ref "${ref}" does not point at anything in this spec (missing "${key}").`);
+    }
+    node = node[key];
+  }
+  return node;
+}
+function deref(schema, spec) {
+  const ref = schema.$ref;
+  if (typeof ref !== "string") return schema;
+  const target = resolveLocalRef(spec, ref);
+  const { $ref: _ignored, ...siblings } = schema;
+  return { ...target, ...siblings };
+}
+function deepDeref(schema, spec, ancestorRefs = /* @__PURE__ */ new Set()) {
+  const ref = schema.$ref;
+  if (typeof ref === "string") {
+    if (ancestorRefs.has(ref)) {
+      return {
+        type: "object",
+        description: `Recursive reference to ${ref} (resolved once to keep the schema finite).`
+      };
+    }
+    const target = resolveLocalRef(spec, ref);
+    return deepDeref(target, spec, new Set(ancestorRefs).add(ref));
+  }
+  const out = { ...schema };
+  if (out.properties) {
+    out.properties = Object.fromEntries(
+      Object.entries(out.properties).map(([key, value]) => [
+        key,
+        deepDeref(value, spec, ancestorRefs)
+      ])
+    );
+  }
+  if (out.items) out.items = deepDeref(out.items, spec, ancestorRefs);
+  for (const unionKeyword of ["anyOf", "oneOf", "allOf"]) {
+    const variants = out[unionKeyword];
+    if (variants) {
+      out[unionKeyword] = variants.map((variant) => deepDeref(variant, spec, ancestorRefs));
+    }
+  }
+  return out;
+}
+function jsonSchemaToTs(schema, spec) {
+  const node = deref(schema, spec);
+  if (node.enum && Array.isArray(node.enum)) {
+    return node.enum.map((value) => JSON.stringify(value)).join(" | ");
+  }
+  if (node.anyOf || node.oneOf) {
+    const variants = node.anyOf ?? node.oneOf;
+    return variants.map((variant) => jsonSchemaToTs(variant, spec)).join(" | ");
+  }
+  if (node.allOf) {
+    return node.allOf.map((part) => jsonSchemaToTs(part, spec)).join(" & ");
+  }
+  switch (node.type) {
+    case "string":
+      return "string";
+    case "number":
+    case "integer":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "null":
+      return "null";
+    case "array": {
+      const items = node.items ? jsonSchemaToTs(node.items, spec) : "unknown";
+      return items.includes("|") ? `Array<${items}>` : `${items}[]`;
+    }
+    case "object":
+    case void 0: {
+      const properties = node.properties;
+      if (!properties || Object.keys(properties).length === 0) {
+        return "Record<string, unknown>";
+      }
+      const required = new Set(node.required ?? []);
+      const fields = Object.entries(properties).map(([key, fieldSchema]) => {
+        const optional = required.has(key) ? "" : "?";
+        const nullable = fieldSchema.nullable ? " | null" : "";
+        return `${JSON.stringify(key)}${optional}: ${jsonSchemaToTs(fieldSchema, spec)}${nullable}`;
+      });
+      return `{ ${fields.join("; ")} }`;
+    }
+    default:
+      return "unknown /* TODO: webmcp-codegen could not express this schema \u2014 tighten it by hand */";
+  }
+}
+function pascalCase(name) {
+  return name.split(/[-_]/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+
+export {
+  deref,
+  deepDeref,
+  jsonSchemaToTs,
+  pascalCase
+};
+//# sourceMappingURL=chunk-5L4KN6F4.js.map

package/dist/chunk-5L4KN6F4.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts"],"sourcesContent":["/**\n * JSON Schema helpers: resolving `$ref` pointers and turning a schema into\n * TypeScript source text for the generated input types.\n *\n * Scope, deliberately small:\n * - Only *local* refs (`#/components/schemas/...`) are resolved. External\n *   refs (other files or URLs) produce a clear error instead of a silent\n *   wrong answer. This covers the overwhelming majority of hand-written and\n *   framework-emitted OpenAPI specs.\n * - The TypeScript printer covers the shapes REST APIs actually use:\n *   objects with required/optional fields, arrays, enums, primitives, and\n *   `anyOf`/`oneOf` unions. Anything more exotic becomes `unknown` with a\n *   TODO comment rather than a plausible-looking lie.\n */\n\nimport type { JsonSchema } from \"./types.js\";\n\n/**\n * Resolve a local `$ref` like \"#/components/schemas/Order\" against the\n * parsed spec document. Throws a clear error for external refs.\n */\nexport function resolveLocalRef(spec: unknown, ref: string): unknown {\n  if (!ref.startsWith(\"#/\")) {\n    throw new Error(\n      `Cannot resolve external $ref \"${ref}\". ` +\n        `Only local refs (starting with \"#/\") are supported — bundle the spec first if it is split across files.`,\n    );\n  }\n  let node: unknown = spec;\n  for (const segment of ref.slice(2).split(\"/\")) {\n    // JSON Pointer escapes: \"~1\" is \"/\", \"~0\" is \"~\"\n    const key = segment.replace(/~1/g, \"/\").replace(/~0/g, \"~\");\n    if (node === null || typeof node !== \"object\" || !(key in node)) {\n      throw new Error(`$ref \"${ref}\" does not point at anything in this spec (missing \"${key}\").`);\n    }\n    node = (node as Record<string, unknown>)[key];\n  }\n  return node;\n}\n\n/**\n * If `schema` is a `$ref`, resolve it (one level — recursion happens as the\n * caller walks the tree). Sibling keywords next to `$ref` are merged over\n * the resolved schema, which is what OpenAPI 3.1 semantics require.\n */\nexport function deref(schema: JsonSchema, spec: unknown): JsonSchema {\n  const ref = schema.$ref;\n  if (typeof ref !== \"string\") return schema;\n  const target = resolveLocalRef(spec, ref) as JsonSchema;\n  const { $ref: _ignored, ...siblings } = schema;\n  return { ...target, ...siblings };\n}\n\n/**\n * Resolve `$ref`s at every depth, so the generated `inputSchema` is a\n * self-contained JSON Schema — the browser has no idea what\n * \"#/components/schemas/Order\" means, so refs must not survive codegen.\n *\n * Recursive models (Order → LineItem → Order) would loop forever, so a ref\n * that points back to one of its own ancestors resolves to a plain object\n * with a note instead. The tool schema stays finite and honest.\n */\nexport function deepDeref(\n  schema: JsonSchema,\n  spec: unknown,\n  ancestorRefs: Set<string> = new Set(),\n): JsonSchema {\n  const ref = schema.$ref;\n  if (typeof ref === \"string\") {\n    if (ancestorRefs.has(ref)) {\n      return {\n        type: \"object\",\n        description: `Recursive reference to ${ref} (resolved once to keep the schema finite).`,\n      };\n    }\n    const target = resolveLocalRef(spec, ref) as JsonSchema;\n    return deepDeref(target, spec, new Set(ancestorRefs).add(ref));\n  }\n\n  const out: JsonSchema = { ...schema };\n  if (out.properties) {\n    out.properties = Object.fromEntries(\n      Object.entries(out.properties).map(([key, value]) => [\n        key,\n        deepDeref(value, spec, ancestorRefs),\n      ]),\n    );\n  }\n  if (out.items) out.items = deepDeref(out.items, spec, ancestorRefs);\n  for (const unionKeyword of [\"anyOf\", \"oneOf\", \"allOf\"] as const) {\n    const variants = out[unionKeyword];\n    if (variants) {\n      out[unionKeyword] = variants.map((variant) => deepDeref(variant, spec, ancestorRefs));\n    }\n  }\n  return out;\n}\n\n/**\n * Print a JSON Schema as TypeScript type source, e.g. for the generated\n * `GetOrderStatusInput` interface. `spec` is the root document, needed to\n * resolve any `$ref`s encountered along the way.\n */\nexport function jsonSchemaToTs(schema: JsonSchema, spec: unknown): string {\n  const node = deref(schema, spec);\n\n  if (node.enum && Array.isArray(node.enum)) {\n    return node.enum.map((value) => JSON.stringify(value)).join(\" | \");\n  }\n\n  if (node.anyOf || node.oneOf) {\n    const variants = (node.anyOf ?? node.oneOf) as JsonSchema[];\n    return variants.map((variant) => jsonSchemaToTs(variant, spec)).join(\" | \");\n  }\n\n  if (node.allOf) {\n    return node.allOf.map((part) => jsonSchemaToTs(part, spec)).join(\" & \");\n  }\n\n  switch (node.type) {\n    case \"string\":\n      return \"string\";\n    case \"number\":\n    case \"integer\":\n      return \"number\";\n    case \"boolean\":\n      return \"boolean\";\n    case \"null\":\n      return \"null\";\n    case \"array\": {\n      const items = node.items ? jsonSchemaToTs(node.items, spec) : \"unknown\";\n      // Wrap unions so `string | number[]` doesn't silently change meaning.\n      return items.includes(\"|\") ? `Array<${items}>` : `${items}[]`;\n    }\n    case \"object\":\n    case undefined: {\n      // Schemas without an explicit \"type\" but with \"properties\" are objects.\n      const properties = node.properties;\n      if (!properties || Object.keys(properties).length === 0) {\n        return \"Record<string, unknown>\";\n      }\n      const required = new Set(node.required ?? []);\n      const fields = Object.entries(properties).map(([key, fieldSchema]) => {\n        const optional = required.has(key) ? \"\" : \"?\";\n        const nullable = fieldSchema.nullable ? \" | null\" : \"\";\n        return `${JSON.stringify(key)}${optional}: ${jsonSchemaToTs(fieldSchema, spec)}${nullable}`;\n      });\n      return `{ ${fields.join(\"; \")} }`;\n    }\n    default:\n      return \"unknown /* TODO: webmcp-codegen could not express this schema — tighten it by hand */\";\n  }\n}\n\n/** \"get-order-status\" → \"GetOrderStatus\" (for generated type names). */\nexport function pascalCase(name: string): string {\n  return name\n    .split(/[-_]/)\n    .filter(Boolean)\n    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))\n    .join(\"\");\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-BIKKPCRT.js

@@ -0,0 +1,39 @@
+// src/naming.ts
+function toToolName(raw) {
+  const name = raw.replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[{}/_\s.]+/g, "-").replace(/[^a-zA-Z0-9-]/g, "").toLowerCase().replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+  const prefixed = /^[a-zA-Z]/.test(name) ? name : `tool-${name}`;
+  return prefixed || "unnamed-tool";
+}
+function nameFromRoute(method, path) {
+  return toToolName(`${method.toLowerCase()} ${path}`);
+}
+function dedupeNames(candidates) {
+  const seen = /* @__PURE__ */ new Set();
+  const names = [];
+  const renames = [];
+  for (const candidate of candidates) {
+    let name = candidate.name;
+    if (seen.has(name) && candidate.httpMethod) {
+      name = `${name}-${candidate.httpMethod.toLowerCase()}`;
+    }
+    let counter = 2;
+    const base = name;
+    while (seen.has(name)) {
+      name = `${base}-${counter}`;
+      counter += 1;
+    }
+    if (name !== candidate.name) {
+      renames.push({ from: candidate.name, to: name });
+    }
+    seen.add(name);
+    names.push(name);
+  }
+  return { names, renames };
+}
+
+export {
+  toToolName,
+  nameFromRoute,
+  dedupeNames
+};
+//# sourceMappingURL=chunk-BIKKPCRT.js.map

package/dist/chunk-BIKKPCRT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/naming.ts"],"sourcesContent":["/**\n * Tool naming.\n *\n * Tool names are the vocabulary an agent reasons over, so we make them\n * boring and predictable: kebab-case, derived from the operationId when the\n * source has one, and always matching the character set the WebMCP runtime\n * accepts (the same rule the groundstate core registry enforces).\n */\n\n/** The character set the WebMCP runtime accepts for tool names. */\nexport const TOOL_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_-]*$/;\n\n/**\n * Turn an operationId or route into a valid, readable tool name.\n *\n * Examples:\n *   \"getOrderStatus\"      → \"get-order-status\"\n *   \"GET /orders/{id}\"    → \"get-orders-id\"\n *   \"list_pets\"           → \"list-pets\"\n */\nexport function toToolName(raw: string): string {\n  const name = raw\n    // Split acronym boundaries first: \"getHTTPStatus\" → \"get-HTTPStatus\"\n    .replace(/([A-Z]+)([A-Z][a-z])/g, \"$1-$2\")\n    // Then camelCase and PascalCase boundaries: \"getOrder\" → \"get-Order\"\n    .replace(/([a-z0-9])([A-Z])/g, \"$1-$2\")\n    // Path placeholders and separators become dashes: \"/orders/{id}\" → \"-orders-id\"\n    .replace(/[{}/_\\s.]+/g, \"-\")\n    // Anything left that isn't a letter, digit or dash is dropped\n    .replace(/[^a-zA-Z0-9-]/g, \"\")\n    .toLowerCase()\n    // Collapse and trim dashes\n    .replace(/-+/g, \"-\")\n    .replace(/^-+|-+$/g, \"\");\n\n  // A name must start with a letter. If it doesn't (e.g. it came from a bare\n  // numeric path), give it a neutral prefix rather than failing.\n  const prefixed = /^[a-zA-Z]/.test(name) ? name : `tool-${name}`;\n  return prefixed || \"unnamed-tool\";\n}\n\n/**\n * Build the fallback name for an operation that has no operationId:\n * the HTTP method plus the path, e.g. GET /orders/{id} → \"get-orders-id\".\n */\nexport function nameFromRoute(method: string, path: string): string {\n  return toToolName(`${method.toLowerCase()} ${path}`);\n}\n\n/**\n * Make every name unique. When two operations slugify to the same name we\n * append the HTTP method (\"get-order-status-post\" would be worse); when that\n * still collides we append a counter. Returns the final names plus a list of\n * renames so the audit report can show them.\n */\nexport function dedupeNames(candidates: { name: string; httpMethod?: string }[]): {\n  names: string[];\n  renames: { from: string; to: string }[];\n} {\n  const seen = new Set<string>();\n  const names: string[] = [];\n  const renames: { from: string; to: string }[] = [];\n\n  for (const candidate of candidates) {\n    let name = candidate.name;\n    if (seen.has(name) && candidate.httpMethod) {\n      name = `${name}-${candidate.httpMethod.toLowerCase()}`;\n    }\n    let counter = 2;\n    const base = name;\n    while (seen.has(name)) {\n      name = `${base}-${counter}`;\n      counter += 1;\n    }\n    if (name !== candidate.name) {\n      renames.push({ from: candidate.name, to: name });\n    }\n    seen.add(name);\n    names.push(name);\n  }\n\n  return { names, renames };\n}\n"],"mappings":";AAoBO,SAAS,WAAW,KAAqB;AAC9C,QAAM,OAAO,IAEV,QAAQ,yBAAyB,OAAO,EAExC,QAAQ,sBAAsB,OAAO,EAErC,QAAQ,eAAe,GAAG,EAE1B,QAAQ,kBAAkB,EAAE,EAC5B,YAAY,EAEZ,QAAQ,OAAO,GAAG,EAClB,QAAQ,YAAY,EAAE;AAIzB,QAAM,WAAW,YAAY,KAAK,IAAI,IAAI,OAAO,QAAQ,IAAI;AAC7D,SAAO,YAAY;AACrB;AAMO,SAAS,cAAc,QAAgB,MAAsB;AAClE,SAAO,WAAW,GAAG,OAAO,YAAY,CAAC,IAAI,IAAI,EAAE;AACrD;AAQO,SAAS,YAAY,YAG1B;AACA,QAAM,OAAO,oBAAI,IAAY;AAC7B,QAAM,QAAkB,CAAC;AACzB,QAAM,UAA0C,CAAC;AAEjD,aAAW,aAAa,YAAY;AAClC,QAAI,OAAO,UAAU;AACrB,QAAI,KAAK,IAAI,IAAI,KAAK,UAAU,YAAY;AAC1C,aAAO,GAAG,IAAI,IAAI,UAAU,WAAW,YAAY,CAAC;AAAA,IACtD;AACA,QAAI,UAAU;AACd,UAAM,OAAO;AACb,WAAO,KAAK,IAAI,IAAI,GAAG;AACrB,aAAO,GAAG,IAAI,IAAI,OAAO;AACzB,iBAAW;AAAA,IACb;AACA,QAAI,SAAS,UAAU,MAAM;AAC3B,cAAQ,KAAK,EAAE,MAAM,UAAU,MAAM,IAAI,KAAK,CAAC;AAAA,IACjD;AACA,SAAK,IAAI,IAAI;AACb,UAAM,KAAK,IAAI;AAAA,EACjB;AAEA,SAAO,EAAE,OAAO,QAAQ;AAC1B;","names":[]}

package/dist/chunk-NFZ5FMDO.js

@@ -0,0 +1,237 @@
+import {
+  dedupeNames
+} from "./chunk-BIKKPCRT.js";
+import {
+  pascalCase
+} from "./chunk-5L4KN6F4.js";
+
+// src/config.ts
+import { access } from "fs/promises";
+import { join, resolve } from "path";
+import { pathToFileURL } from "url";
+function defineConfig(config) {
+  return config;
+}
+var CONFIG_FILE_NAMES = ["codegen.config.mjs", "codegen.config.js"];
+async function loadConfig(cwd, explicitPath) {
+  const candidates = explicitPath ? [resolve(cwd, explicitPath)] : CONFIG_FILE_NAMES.map((name) => join(cwd, name));
+  for (const candidate of candidates) {
+    if (!await exists(candidate)) continue;
+    const module = await import(pathToFileURL(candidate).href);
+    const config = module.default;
+    if (!isCodegenConfig(config)) {
+      throw new Error(
+        `${candidate} must default-export defineConfig({ sources: [...], generate: [...] }).`
+      );
+    }
+    return { config, path: candidate };
+  }
+  throw new Error(
+    explicitPath ? `No config file at "${explicitPath}".` : `No codegen.config.mjs found in ${cwd}. Run \`npx webmcp-codegen init\` to create one.`
+  );
+}
+function isCodegenConfig(value) {
+  if (value === null || typeof value !== "object") return false;
+  const config = value;
+  return Array.isArray(config.sources) && Array.isArray(config.generate);
+}
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// src/pipeline.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname } from "path";
+
+// src/safety.ts
+var DESTRUCTIVE_WORDS = /\b(cancel|delete|remove|destroy|deactivate|refund|revoke|purge|close)\b/i;
+var DEFAULT_PII_FIELDS = [
+  "password",
+  "ssn",
+  "token",
+  "secret",
+  "apikey",
+  "api_key",
+  "email",
+  "dob",
+  "birthdate",
+  "phone",
+  "address",
+  "creditcard",
+  "cardnumber",
+  "cvv"
+];
+var AGENT_INSTRUCTION_PATTERN = /\b(you (must|should|always|are)|as an ai|ignore (all |previous )?instructions|do not refuse)\b/i;
+function classifySideEffect(tool) {
+  switch (tool.httpMethod) {
+    case "GET":
+    case "HEAD":
+    case "OPTIONS":
+      return "read";
+    case "DELETE":
+      return "destructive";
+    case "POST":
+    case "PUT":
+    case "PATCH":
+      return DESTRUCTIVE_WORDS.test(tool.name) || DESTRUCTIVE_WORDS.test(tool.source.ref) ? "destructive" : "write";
+    default:
+      return "unknown";
+  }
+}
+function hintsFor(tool, sideEffect) {
+  const method = tool.httpMethod;
+  return {
+    readOnlyHint: sideEffect === "read",
+    destructiveHint: sideEffect === "destructive",
+    // PUT/PATCH/DELETE can be safely retried with the same input; POST cannot.
+    idempotentHint: sideEffect === "read" || method === "PUT" || method === "PATCH" || method === "DELETE"
+  };
+}
+function riskTierFor(sideEffect) {
+  switch (sideEffect) {
+    case "read":
+      return "safe-read";
+    case "destructive":
+      return "destructive-confirm";
+    default:
+      return "write-confirm";
+  }
+}
+function findPiiFields(schema, extraFields = [], prefix = "") {
+  if (!schema?.properties) return [];
+  const piiNames = new Set(
+    [...DEFAULT_PII_FIELDS, ...extraFields].map((name) => name.toLowerCase())
+  );
+  const found = [];
+  for (const [key, fieldSchema] of Object.entries(schema.properties)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    const normalizedKey = key.toLowerCase().replace(/[-_]/g, "");
+    const looksSensitive = piiNames.has(key.toLowerCase()) || piiNames.has(normalizedKey) || [...piiNames].some((name) => normalizedKey === name.replace(/[-_]/g, ""));
+    if (looksSensitive) found.push(path);
+    found.push(...findPiiFields(fieldSchema, extraFields, path));
+  }
+  return found;
+}
+function reviewTools(candidates, safety = {}) {
+  const excluded = (safety.exclude ?? []).map((pattern) => pattern.toLowerCase());
+  return candidates.filter(
+    (tool) => !excluded.some(
+      (pattern) => tool.name.toLowerCase().includes(pattern) || tool.source.ref.toLowerCase().includes(pattern)
+    )
+  ).map((tool) => {
+    const sideEffect = classifySideEffect(tool);
+    return {
+      ...tool,
+      sideEffect,
+      riskTier: riskTierFor(sideEffect),
+      hints: hintsFor(tool, sideEffect),
+      piiInOutput: findPiiFields(tool.outputSchema, safety.piiFields)
+    };
+  });
+}
+function auditTools(tools, renames = []) {
+  const findings = [];
+  for (const rename of renames) {
+    findings.push({
+      level: "warning",
+      tool: rename.to,
+      message: `Renamed "${rename.from}" \u2192 "${rename.to}" to keep tool names unique.`
+    });
+  }
+  for (const tool of tools) {
+    if (!tool.description || tool.description.trim().length === 0) {
+      findings.push({
+        level: "error",
+        tool: tool.name,
+        message: "No description. Agents pick tools by description \u2014 this tool is invisible."
+      });
+      continue;
+    }
+    if (tool.descriptionSource === "generated-template") {
+      findings.push({
+        level: "warning",
+        tool: tool.name,
+        message: `Description is just "${tool.description}" (no summary in the source). Write one sentence about what it does and why \u2014 it goes straight into the agent's prompt.`
+      });
+    }
+    if (AGENT_INSTRUCTION_PATTERN.test(tool.description)) {
+      findings.push({
+        level: "warning",
+        tool: tool.name,
+        message: "The description reads like instructions to the agent, not a description of the tool. Describe what the tool does; never try to steer the agent from here."
+      });
+    }
+    if (tool.riskTier === "safe-read" && DESTRUCTIVE_WORDS.test(tool.name)) {
+      findings.push({
+        level: "error",
+        tool: tool.name,
+        message: `The name suggests something destructive but ${tool.httpMethod} is a safe verb. Check the spec \u2014 a GET named like a delete is either mislabeled or a design smell.`
+      });
+    }
+    if (tool.piiInOutput.length > 0) {
+      findings.push({
+        level: "warning",
+        tool: tool.name,
+        message: `Response may expose ${tool.piiInOutput.join(", ")}. These fields reach the agent \u2014 exclude them in execute() unless they are truly needed.`
+      });
+    }
+    if (tool.requiresAuth && tool.riskTier !== "safe-read") {
+      findings.push({
+        level: "warning",
+        tool: tool.name,
+        message: "This mutating tool wraps an authenticated endpoint. It runs with the page's session \u2014 make sure your server-side authorization checks apply to tool calls too."
+      });
+    }
+  }
+  return findings;
+}
+
+// src/pipeline.ts
+async function runGenerate(config, options) {
+  const candidates = (await Promise.all(config.sources.map((source) => source.collect()))).flat();
+  const { names, renames } = dedupeNames(candidates);
+  const named = candidates.map((candidate, index) => {
+    const name = names[index] ?? candidate.name;
+    return { ...candidate, name, inputTypeName: `${pascalCase(name)}Input` };
+  });
+  const tools = reviewTools(named, config.safety);
+  const findings = options.skipAudit ? [] : auditTools(tools, renames);
+  const errors = findings.filter((finding) => finding.level === "error");
+  const blocked = errors.length > 0 && !options.force && !options.skipAudit;
+  if (blocked) {
+    return { tools, findings, files: [], blocked, wrote: false };
+  }
+  const files = [];
+  for (const generator of config.generate) {
+    files.push(...await generator.generate(tools, options.cwd));
+  }
+  let wrote = false;
+  if (!options.dryRun) {
+    for (const file of files) {
+      if (file.action === "unchanged" && !file.conflict) continue;
+      const target = file.conflict ?? file.path;
+      await mkdir(dirname(target), { recursive: true });
+      await writeFile(target, file.conflict ? conflictContents(file) : file.contents);
+    }
+    wrote = true;
+  }
+  return { tools, findings, files, blocked, wrote };
+}
+function conflictContents(file) {
+  return `// webmcp-codegen could not regenerate ${file.path} because its generated
+// region was edited by hand. Review this version, then merge it manually.
+
+` + file.contents;
+}
+
+export {
+  defineConfig,
+  loadConfig,
+  runGenerate
+};
+//# sourceMappingURL=chunk-NFZ5FMDO.js.map

package/dist/chunk-NFZ5FMDO.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts","../src/pipeline.ts","../src/safety.ts"],"sourcesContent":["/**\n * Config: `defineConfig` for authoring, `loadConfig` for the CLI.\n *\n * Config files are plain JavaScript (`codegen.config.mjs`) so the CLI can\n * load them with a plain dynamic import — no TypeScript loader, no build\n * step, no extra dependencies. If you want types while authoring, that is\n * what `defineConfig` is for:\n *\n *   import { defineConfig } from \"webmcp-codegen\";\n *   export default defineConfig({ ... });\n */\n\nimport { access } from \"node:fs/promises\";\nimport { join, resolve } from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport type { CodegenConfig } from \"./types.js\";\n\n/** Identity function whose only job is type-checking the config object. */\nexport function defineConfig(config: CodegenConfig): CodegenConfig {\n  return config;\n}\n\nconst CONFIG_FILE_NAMES = [\"codegen.config.mjs\", \"codegen.config.js\"];\n\n/**\n * Find and load the config file. Resolving relative to `cwd` keeps the CLI\n * usable from any directory, the same way `eslint -c` behaves.\n */\nexport async function loadConfig(\n  cwd: string,\n  explicitPath?: string,\n): Promise<{ config: CodegenConfig; path: string }> {\n  const candidates = explicitPath\n    ? [resolve(cwd, explicitPath)]\n    : CONFIG_FILE_NAMES.map((name) => join(cwd, name));\n\n  for (const candidate of candidates) {\n    if (!(await exists(candidate))) continue;\n    const module = (await import(pathToFileURL(candidate).href)) as { default?: unknown };\n    const config = module.default;\n    if (!isCodegenConfig(config)) {\n      throw new Error(\n        `${candidate} must default-export defineConfig({ sources: [...], generate: [...] }).`,\n      );\n    }\n    return { config, path: candidate };\n  }\n\n  throw new Error(\n    explicitPath\n      ? `No config file at \"${explicitPath}\".`\n      : `No codegen.config.mjs found in ${cwd}. Run \\`npx webmcp-codegen init\\` to create one.`,\n  );\n}\n\n/** The lightest possible shape check — clear error beats deep validation. */\nfunction isCodegenConfig(value: unknown): value is CodegenConfig {\n  if (value === null || typeof value !== \"object\") return false;\n  const config = value as Record<string, unknown>;\n  return Array.isArray(config.sources) && Array.isArray(config.generate);\n}\n\nasync function exists(path: string): Promise<boolean> {\n  try {\n    await access(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n","/**\n * The pipeline: sources → normalize → safety review → audit → write.\n *\n * This module is the only place the stages meet. It owns no opinions of its\n * own — naming, safety, and file formats all live in their own modules — it\n * just runs them in order and produces one honest report of what happened\n * (or what *would* happen, when called with `write: false`).\n */\n\nimport { mkdir, writeFile } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\nimport { dedupeNames } from \"./naming.js\";\nimport { auditTools, reviewTools } from \"./safety.js\";\nimport { pascalCase } from \"./schema.js\";\nimport type { AuditFinding, CodegenConfig, GeneratedFile, ReviewedTool } from \"./types.js\";\n\nexport interface GenerateOptions {\n  /** Project root. Everything (config, spec paths, outDir) resolves from here. */\n  cwd: string;\n  /** Preview mode: compute everything, write nothing. */\n  dryRun?: boolean;\n  /** Skip the audit pass entirely (classification still runs — output needs it). */\n  skipAudit?: boolean;\n  /** Write even when the audit found errors. The report still shows them. */\n  force?: boolean;\n}\n\nexport interface GenerateResult {\n  tools: ReviewedTool[];\n  findings: AuditFinding[];\n  files: GeneratedFile[];\n  /** True when audit errors stopped any file from being written. */\n  blocked: boolean;\n  /** True when this run actually wrote files (false for dry runs and blocks). */\n  wrote: boolean;\n}\n\nexport async function runGenerate(\n  config: CodegenConfig,\n  options: GenerateOptions,\n): Promise<GenerateResult> {\n  // 1. Collect candidate tools from every configured source.\n  const candidates = (await Promise.all(config.sources.map((source) => source.collect()))).flat();\n\n  // 2. Normalize: make names unique before anything downstream sees them.\n  //    The input type name is derived from the *final* name so they never drift.\n  const { names, renames } = dedupeNames(candidates);\n  const named = candidates.map((candidate, index) => {\n    const name = names[index] ?? candidate.name;\n    return { ...candidate, name, inputTypeName: `${pascalCase(name)}Input` };\n  });\n\n  // 3. Safety review: classify side effects, compute hints, scan for PII,\n  //    apply config exclusions.\n  const tools = reviewTools(named, config.safety);\n\n  // 4. Audit. Errors block the write unless --force (or --skip-audit) was passed.\n  const findings = options.skipAudit ? [] : auditTools(tools, renames);\n  const errors = findings.filter((finding) => finding.level === \"error\");\n  const blocked = errors.length > 0 && !options.force && !options.skipAudit;\n\n  if (blocked) {\n    return { tools, findings, files: [], blocked, wrote: false };\n  }\n\n  // 5. Generate the files, then write them (unless this is a dry run).\n  const files: GeneratedFile[] = [];\n  for (const generator of config.generate) {\n    files.push(...(await generator.generate(tools, options.cwd)));\n  }\n\n  let wrote = false;\n  if (!options.dryRun) {\n    for (const file of files) {\n      if (file.action === \"unchanged\" && !file.conflict) continue;\n      // A conflict means a human edited the generated region by hand:\n      // leave their file alone and put our version in a `.new` sibling.\n      const target = file.conflict ?? file.path;\n      await mkdir(dirname(target), { recursive: true });\n      await writeFile(target, file.conflict ? conflictContents(file) : file.contents);\n    }\n    wrote = true;\n  }\n\n  return { tools, findings, files, blocked, wrote };\n}\n\n/**\n * When a hand-edited file blocks regeneration, the `.new` file explains\n * itself at the top so nobody mistakes it for something to import.\n */\nfunction conflictContents(file: GeneratedFile): string {\n  return (\n    `// webmcp-codegen could not regenerate ${file.path} because its generated\\n` +\n    `// region was edited by hand. Review this version, then merge it manually.\\n\\n` +\n    file.contents\n  );\n}\n","/**\n * The safety layer.\n *\n * Nothing gets written to disk until every candidate tool has been through\n * here. This layer does three jobs:\n *\n *   1. Classify — what does calling this tool do to the world?\n *      (read / write / destructive, from the HTTP verb plus name heuristics)\n *   2. Hint     — derive the WebMCP tool hints (readOnlyHint etc.) from that\n *   3. Audit    — lint the result and report problems in plain language\n *\n * Every rule is a heuristic with an escape hatch: the generated code carries\n * the classification in plain sight, and the developer owns the final file.\n */\n\nimport type {\n  AuditFinding,\n  CandidateTool,\n  JsonSchema,\n  ReviewedTool,\n  RiskTier,\n  SafetyOptions,\n  SideEffect,\n  ToolHints,\n} from \"./types.js\";\n\n/**\n * Words that signal \"this changes something the user can't easily undo\",\n * even when the HTTP verb looks innocent. `POST /orders/{id}/cancel` is the\n * classic case: a POST that behaves like a DELETE.\n */\nconst DESTRUCTIVE_WORDS =\n  /\\b(cancel|delete|remove|destroy|deactivate|refund|revoke|purge|close)\\b/i;\n\n/**\n * Field names that usually hold personal data or secrets. Matched against\n * the last segment of a field path, case-insensitively. Teams extend this\n * list via `safety.piiFields` in the config.\n */\nconst DEFAULT_PII_FIELDS = [\n  \"password\",\n  \"ssn\",\n  \"token\",\n  \"secret\",\n  \"apikey\",\n  \"api_key\",\n  \"email\",\n  \"dob\",\n  \"birthdate\",\n  \"phone\",\n  \"address\",\n  \"creditcard\",\n  \"cardnumber\",\n  \"cvv\",\n];\n\n/**\n * Phrases that suggest a description is trying to *instruct the agent*\n * instead of describing the tool — a known prompt-injection smell.\n */\nconst AGENT_INSTRUCTION_PATTERN =\n  /\\b(you (must|should|always|are)|as an ai|ignore (all |previous )?instructions|do not refuse)\\b/i;\n\n/** Step 1: classify what calling the tool does. */\nexport function classifySideEffect(tool: CandidateTool): SideEffect {\n  switch (tool.httpMethod) {\n    case \"GET\":\n    case \"HEAD\":\n    case \"OPTIONS\":\n      // A safe verb whose name says otherwise is suspicious — audit flags it.\n      return \"read\";\n    case \"DELETE\":\n      return \"destructive\";\n    case \"POST\":\n    case \"PUT\":\n    case \"PATCH\":\n      // Upgrade nominally-\"write\" verbs when the name says it can't be undone.\n      return DESTRUCTIVE_WORDS.test(tool.name) || DESTRUCTIVE_WORDS.test(tool.source.ref)\n        ? \"destructive\"\n        : \"write\";\n    default:\n      return \"unknown\";\n  }\n}\n\n/** Step 2: derive the WebMCP hints from the classification. */\nexport function hintsFor(tool: CandidateTool, sideEffect: SideEffect): ToolHints {\n  const method = tool.httpMethod;\n  return {\n    readOnlyHint: sideEffect === \"read\",\n    destructiveHint: sideEffect === \"destructive\",\n    // PUT/PATCH/DELETE can be safely retried with the same input; POST cannot.\n    idempotentHint:\n      sideEffect === \"read\" || method === \"PUT\" || method === \"PATCH\" || method === \"DELETE\",\n  };\n}\n\nexport function riskTierFor(sideEffect: SideEffect): RiskTier {\n  switch (sideEffect) {\n    case \"read\":\n      return \"safe-read\";\n    case \"destructive\":\n      return \"destructive-confirm\";\n    default:\n      return \"write-confirm\";\n  }\n}\n\n/**\n * Walk a schema and return the paths of fields that look like PII or\n * secrets, e.g. \"user.email\". Only *output* schemas are scanned: the\n * security-relevant direction is data leaving the page and reaching the agent.\n */\nexport function findPiiFields(\n  schema: JsonSchema | undefined,\n  extraFields: string[] = [],\n  prefix = \"\",\n): string[] {\n  if (!schema?.properties) return [];\n  const piiNames = new Set(\n    [...DEFAULT_PII_FIELDS, ...extraFields].map((name) => name.toLowerCase()),\n  );\n  const found: string[] = [];\n\n  for (const [key, fieldSchema] of Object.entries(schema.properties)) {\n    const path = prefix ? `${prefix}.${key}` : key;\n    const normalizedKey = key.toLowerCase().replace(/[-_]/g, \"\");\n    const looksSensitive =\n      piiNames.has(key.toLowerCase()) ||\n      piiNames.has(normalizedKey) ||\n      [...piiNames].some((name) => normalizedKey === name.replace(/[-_]/g, \"\"));\n    if (looksSensitive) found.push(path);\n    // Recurse into nested objects (\"user\": { \"email\": ... }).\n    found.push(...findPiiFields(fieldSchema, extraFields, path));\n  }\n  return found;\n}\n\n/** Run the full review: classify, hint, PII-scan. Pure — no I/O. */\nexport function reviewTools(\n  candidates: CandidateTool[],\n  safety: SafetyOptions = {},\n): ReviewedTool[] {\n  const excluded = (safety.exclude ?? []).map((pattern) => pattern.toLowerCase());\n\n  return candidates\n    .filter(\n      (tool) =>\n        !excluded.some(\n          (pattern) =>\n            tool.name.toLowerCase().includes(pattern) ||\n            tool.source.ref.toLowerCase().includes(pattern),\n        ),\n    )\n    .map((tool) => {\n      const sideEffect = classifySideEffect(tool);\n      return {\n        ...tool,\n        sideEffect,\n        riskTier: riskTierFor(sideEffect),\n        hints: hintsFor(tool, sideEffect),\n        piiInOutput: findPiiFields(tool.outputSchema, safety.piiFields),\n      };\n    });\n}\n\n/**\n * Step 3: audit the reviewed tools and report in plain language.\n * Errors block file writing (unless --force); warnings never do. This is\n * meant to run in CI like `npm audit` — exit codes, not vibes.\n */\nexport function auditTools(\n  tools: ReviewedTool[],\n  renames: { from: string; to: string }[] = [],\n): AuditFinding[] {\n  const findings: AuditFinding[] = [];\n\n  for (const rename of renames) {\n    findings.push({\n      level: \"warning\",\n      tool: rename.to,\n      message: `Renamed \"${rename.from}\" → \"${rename.to}\" to keep tool names unique.`,\n    });\n  }\n\n  for (const tool of tools) {\n    if (!tool.description || tool.description.trim().length === 0) {\n      findings.push({\n        level: \"error\",\n        tool: tool.name,\n        message: \"No description. Agents pick tools by description — this tool is invisible.\",\n      });\n      continue;\n    }\n\n    if (tool.descriptionSource === \"generated-template\") {\n      findings.push({\n        level: \"warning\",\n        tool: tool.name,\n        message:\n          `Description is just \"${tool.description}\" (no summary in the source). ` +\n          \"Write one sentence about what it does and why — it goes straight into the agent's prompt.\",\n      });\n    }\n\n    if (AGENT_INSTRUCTION_PATTERN.test(tool.description)) {\n      findings.push({\n        level: \"warning\",\n        tool: tool.name,\n        message:\n          \"The description reads like instructions to the agent, not a description of the tool. \" +\n          \"Describe what the tool does; never try to steer the agent from here.\",\n      });\n    }\n\n    if (tool.riskTier === \"safe-read\" && DESTRUCTIVE_WORDS.test(tool.name)) {\n      findings.push({\n        level: \"error\",\n        tool: tool.name,\n        message:\n          `The name suggests something destructive but ${tool.httpMethod} is a safe verb. ` +\n          \"Check the spec — a GET named like a delete is either mislabeled or a design smell.\",\n      });\n    }\n\n    if (tool.piiInOutput.length > 0) {\n      findings.push({\n        level: \"warning\",\n        tool: tool.name,\n        message:\n          `Response may expose ${tool.piiInOutput.join(\", \")}. ` +\n          \"These fields reach the agent — exclude them in execute() unless they are truly needed.\",\n      });\n    }\n\n    if (tool.requiresAuth && tool.riskTier !== \"safe-read\") {\n      findings.push({\n        level: \"warning\",\n        tool: tool.name,\n        message:\n          \"This mutating tool wraps an authenticated endpoint. It runs with the page's session — \" +\n          \"make sure your server-side authorization checks apply to tool calls too.\",\n      });\n    }\n  }\n\n  return findings;\n}\n"],"mappings":"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","names":[]}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node