webmcp-codegen 0.2.0 → 0.3.0

package/dist/{chunk-R3DEBBQ3.js → chunk-MJQ5B6HB.js}

@@ -1,9 +1,10 @@
 import {
-  dedupeNames
-} from "./chunk-BIKKPCRT.js";
+  dedupeNames,
+  stripVersionPrefix
+} from "./chunk-FWSATV7C.js";
 import {
   pascalCase
-} from "./chunk-5L4KN6F4.js";
+} from "./chunk-KSQMJERY.js";
 
 // src/config.ts
 import { access } from "fs/promises";
@@ -50,6 +51,26 @@ import { dirname } from "path";
 
 // src/safety.ts
 var DESTRUCTIVE_WORDS = /\b(cancel|delete|remove|destroy|deactivate|refund|revoke|purge|close)\b/i;
+var READING_POST_WORDS = /* @__PURE__ */ new Set([
+  "search",
+  "query",
+  "list",
+  "find",
+  "filter",
+  "estimate",
+  "preview",
+  "validate",
+  "check",
+  "lookup",
+  "autocomplete",
+  "suggest"
+]);
+function nameSaysRead(toolName) {
+  return toolName.split("-").some((segment) => READING_POST_WORDS.has(segment));
+}
+var WEBHOOK_PATTERN = /\bwebhooks?\b/i;
+var AUTH_PATTERN = /\b(auth|signin|sign-in|login|log-in|logout|log-out|oauth|password|credential|session)s?\b/i;
+var ADMIN_PATTERN = /\badmin\b/i;
 var DEFAULT_PII_FIELDS = [
   "password",
   "ssn",
@@ -76,6 +97,8 @@ function classifySideEffect(tool) {
     case "DELETE":
       return "destructive";
     case "POST":
+      if (nameSaysRead(tool.name)) return "read";
+      return DESTRUCTIVE_WORDS.test(tool.name) || DESTRUCTIVE_WORDS.test(tool.source.ref) ? "destructive" : "write";
     case "PUT":
     case "PATCH":
       return DESTRUCTIVE_WORDS.test(tool.name) || DESTRUCTIVE_WORDS.test(tool.source.ref) ? "destructive" : "write";
@@ -83,6 +106,13 @@ function classifySideEffect(tool) {
       return "unknown";
   }
 }
+function endpointRoleFor(tool) {
+  const haystack = `${tool.name} ${tool.source.ref}`;
+  if (WEBHOOK_PATTERN.test(haystack)) return "webhook";
+  if (AUTH_PATTERN.test(haystack)) return "auth";
+  if (ADMIN_PATTERN.test(haystack)) return "admin";
+  return "endpoint";
+}
 function hintsFor(tool, sideEffect) {
   const method = tool.httpMethod;
   return {
@@ -119,20 +149,39 @@ function findPiiFields(schema, extraFields = [], prefix = "") {
 }
 function reviewTools(candidates, safety = {}) {
   const excluded = (safety.exclude ?? []).map((pattern) => pattern.toLowerCase());
-  return candidates.filter(
-    (tool) => !excluded.some(
+  const skipped = [];
+  const tools = [];
+  for (const tool of candidates) {
+    const excludedBy = excluded.find(
       (pattern) => tool.name.toLowerCase().includes(pattern) || tool.source.ref.toLowerCase().includes(pattern)
-    )
-  ).map((tool) => {
+    );
+    if (excludedBy) {
+      skipped.push({ ref: tool.source.ref, reason: `excluded by config ("${excludedBy}")` });
+      continue;
+    }
+    const endpointRole = endpointRoleFor(tool);
+    if (endpointRole === "webhook") {
+      skipped.push({
+        ref: tool.source.ref,
+        reason: "a webhook receives server callbacks; an agent has nothing to call"
+      });
+      continue;
+    }
     const sideEffect = classifySideEffect(tool);
-    return {
+    tools.push({
       ...tool,
       sideEffect,
+      endpointRole,
       riskTier: riskTierFor(sideEffect),
       hints: hintsFor(tool, sideEffect),
+      // Reads work out of the box. Mutations, auth, and admin endpoints start
+      // disabled: the working code is generated but commented out, so enabling
+      // one is a deliberate edit, never an accident.
+      enabledByDefault: sideEffect === "read" && endpointRole === "endpoint",
       piiInOutput: findPiiFields(tool.outputSchema, safety.piiFields)
-    };
-  });
+    });
+  }
+  return { tools, skipped };
 }
 function auditTools(tools, renames = []) {
   const findings = [];
@@ -148,7 +197,7 @@ function auditTools(tools, renames = []) {
       findings.push({
         level: "error",
         tool: tool.name,
-        message: "No description. Agents pick tools by description \u2014 this tool is invisible."
+        message: "No description. Agents pick tools by description. This tool is invisible."
       });
       continue;
     }
@@ -156,7 +205,7 @@ function auditTools(tools, renames = []) {
       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.`
+        message: `Description is just "${tool.description}" (no summary in the source). Write one sentence about what it does and why. It goes straight into the agent's prompt.`
       });
     }
     if (AGENT_INSTRUCTION_PATTERN.test(tool.description)) {
@@ -170,21 +219,42 @@ function auditTools(tools, renames = []) {
       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.`
+        message: `The name suggests something destructive but ${tool.httpMethod} is a safe verb. Check the spec: 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.`
+        message: `Response may expose ${tool.piiInOutput.join(", ")}. These fields reach the agent. 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."
+        message: "This mutating tool wraps an authenticated endpoint. It runs with the page's session, so make sure your server-side authorization checks apply to tool calls too."
+      });
+    }
+    if (tool.endpointRole === "auth") {
+      findings.push({
+        level: "warning",
+        tool: tool.name,
+        message: "This looks like a sign-in or session endpoint. It is generated disabled: agents should not drive authentication. Enable it by hand only if you are sure."
+      });
+    }
+    if (tool.endpointRole === "admin") {
+      findings.push({
+        level: "warning",
+        tool: tool.name,
+        message: "Admin endpoint. It is generated disabled: exposing admin operations to agents should be a deliberate decision, reviewed endpoint by endpoint."
+      });
+    }
+    if (tool.httpMethod === "POST" && tool.sideEffect === "read") {
+      findings.push({
+        level: "warning",
+        tool: tool.name,
+        message: "A POST treated as a read (the name says search/query-style). If it actually changes state, disable it: a mislabeled read skips the user-confirmation step."
       });
     }
   }
@@ -193,18 +263,38 @@ function auditTools(tools, renames = []) {
 
 // src/pipeline.ts
 async function runGenerate(config, options) {
+  const notes = [];
   const candidates = (await Promise.all(config.sources.map((source) => source.collect()))).flat();
-  const { names, renames } = dedupeNames(candidates);
-  const named = candidates.map((candidate, index) => {
+  const stripped = stripVersionPrefix(candidates);
+  if (stripped.note) notes.push(stripped.note);
+  const versioned = candidates.map((candidate, index) => ({
+    ...candidate,
+    name: stripped.names[index] ?? candidate.name
+  }));
+  const { names, renames } = dedupeNames(versioned);
+  const named = versioned.map((candidate, index) => {
     const name = names[index] ?? candidate.name;
     return { ...candidate, name, inputTypeName: `${pascalCase(name)}Input` };
   });
-  const tools = reviewTools(named, config.safety);
+  const { tools, skipped } = reviewTools(named, config.safety);
+  if (options.overrides) {
+    for (const tool of tools) {
+      const override = options.overrides[tool.name];
+      if (!override) continue;
+      if (typeof override.description === "string" && override.description.trim()) {
+        tool.description = override.description.trim();
+        tool.descriptionSource = "openapi-summary";
+      }
+      if (typeof override.enabled === "boolean") {
+        tool.enabledByDefault = override.enabled;
+      }
+    }
+  }
   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 };
+    return { tools, skipped, findings, files: [], notes, blocked, wrote: false };
   }
   const files = [];
   for (const generator of config.generate) {
@@ -220,7 +310,7 @@ async function runGenerate(config, options) {
     }
     wrote = true;
   }
-  return { tools, findings, files, blocked, wrote };
+  return { tools, skipped, findings, files, notes, blocked, wrote };
 }
 function conflictContents(file) {
   return `// webmcp-codegen could not regenerate ${file.path} because its generated
@@ -235,4 +325,4 @@ export {
   loadConfig,
   runGenerate
 };
-//# sourceMappingURL=chunk-R3DEBBQ3.js.map
+//# sourceMappingURL=chunk-MJQ5B6HB.js.map

package/dist/chunk-MJQ5B6HB.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\nexport const 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: a 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, stripVersionPrefix } from \"./naming.js\";\nimport { auditTools, reviewTools } from \"./safety.js\";\nimport { pascalCase } from \"./schema.js\";\nimport type {\n  AuditFinding,\n  CodegenConfig,\n  GeneratedFile,\n  ReviewedTool,\n  SkippedEndpoint,\n  ToolOverrides,\n} 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   * Hand-authored tweaks from .webmcp-codegen.json (usually written by the\n   * dev dashboard). Applied after the safety review so they survive\n   * regeneration.\n   */\n  overrides?: ToolOverrides;\n}\n\nexport interface GenerateResult {\n  tools: ReviewedTool[];\n  /** Endpoints deliberately not generated (webhooks, config exclusions). */\n  skipped: SkippedEndpoint[];\n  findings: AuditFinding[];\n  files: GeneratedFile[];\n  /** Human-facing pipeline notes, e.g. \"stripped the shared v1 prefix\". */\n  notes: string[];\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  const notes: string[] = [];\n\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 names. First drop a shared API version prefix (\"get-v1-x\"\n  //    → \"get-x\") when nearly every name carries it, then dedupe what remains.\n  //    Strip before dedupe: stripping can create collisions, dedupe resolves them.\n  const stripped = stripVersionPrefix(candidates);\n  if (stripped.note) notes.push(stripped.note);\n  const versioned = candidates.map((candidate, index) => ({\n    ...candidate,\n    name: stripped.names[index] ?? candidate.name,\n  }));\n  const { names, renames } = dedupeNames(versioned);\n  const named = versioned.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 endpoint roles and config exclusions. Webhooks never come back.\n  const { tools, skipped } = reviewTools(named, config.safety);\n\n  // 4. Hand-authored overrides (dashboard edits) win over derived defaults.\n  if (options.overrides) {\n    for (const tool of tools) {\n      const override = options.overrides[tool.name];\n      if (!override) continue;\n      if (typeof override.description === \"string\" && override.description.trim()) {\n        tool.description = override.description.trim();\n        // A hand-written description is no longer a template; stop warning about it.\n        tool.descriptionSource = \"openapi-summary\";\n      }\n      if (typeof override.enabled === \"boolean\") {\n        tool.enabledByDefault = override.enabled;\n      }\n    }\n  }\n\n  // 5. 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, skipped, findings, files: [], notes, blocked, wrote: false };\n  }\n\n  // 6. 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, skipped, findings, files, notes, 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  EndpointRole,\n  JsonSchema,\n  ReviewedTool,\n  RiskTier,\n  SafetyOptions,\n  SideEffect,\n  SkippedEndpoint,\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 * Words that mark a POST as a read in disguise. Plenty of real APIs search\n * with POST because the filter object is too big for a query string\n * (`POST /search`, `POST /estimate`). These get read treatment: enabled by\n * default, readOnlyHint set.\n *\n * Matched per dash-separated segment, so both route-derived names\n * (\"post-search\") and operationId-derived names (\"search-assets\") qualify,\n * while \"blacklist-items\" does not.\n */\nconst READING_POST_WORDS = new Set([\n  \"search\",\n  \"query\",\n  \"list\",\n  \"find\",\n  \"filter\",\n  \"estimate\",\n  \"preview\",\n  \"validate\",\n  \"check\",\n  \"lookup\",\n  \"autocomplete\",\n  \"suggest\",\n]);\n\n/** True when the tool's name contains a reading word as a whole segment. */\nfunction nameSaysRead(toolName: string): boolean {\n  return toolName.split(\"-\").some((segment) => READING_POST_WORDS.has(segment));\n}\n\n/** Endpoints that receive server callbacks. An agent has nothing to call. */\nconst WEBHOOK_PATTERN = /\\bwebhooks?\\b/i;\n\n/** Sign-in, session, and credential endpoints. Agents should not drive auth. */\nconst AUTH_PATTERN =\n  /\\b(auth|signin|sign-in|login|log-in|logout|log-out|oauth|password|credential|session)s?\\b/i;\n\n/** Admin endpoints. Exposing them to agents is a deliberate decision. */\nconst ADMIN_PATTERN = /\\badmin\\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. That is 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      // A POST whose name is a reading word (\"search-assets\", \"post-search\")\n      // is a read wearing a write verb. Treat it as one.\n      if (nameSaysRead(tool.name)) return \"read\";\n      return DESTRUCTIVE_WORDS.test(tool.name) || DESTRUCTIVE_WORDS.test(tool.source.ref)\n        ? \"destructive\"\n        : \"write\";\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/**\n * What kind of endpoint this tool wraps. Checked against the route and the\n * name: \"/v1/admin/users\" and \"admin-feature-access-approve\" both catch it.\n */\nexport function endpointRoleFor(tool: CandidateTool): EndpointRole {\n  const haystack = `${tool.name} ${tool.source.ref}`;\n  if (WEBHOOK_PATTERN.test(haystack)) return \"webhook\";\n  if (AUTH_PATTERN.test(haystack)) return \"auth\";\n  if (ADMIN_PATTERN.test(haystack)) return \"admin\";\n  return \"endpoint\";\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/**\n * Run the full review: classify, hint, PII-scan, decide the starting state.\n * Pure, no I/O.\n *\n * Returns the surviving tools plus the endpoints we deliberately skipped\n * (webhooks today), so the report can say what was left out and why.\n */\nexport function reviewTools(\n  candidates: CandidateTool[],\n  safety: SafetyOptions = {},\n): { tools: ReviewedTool[]; skipped: SkippedEndpoint[] } {\n  const excluded = (safety.exclude ?? []).map((pattern) => pattern.toLowerCase());\n  const skipped: SkippedEndpoint[] = [];\n  const tools: ReviewedTool[] = [];\n\n  for (const tool of candidates) {\n    const excludedBy = excluded.find(\n      (pattern) =>\n        tool.name.toLowerCase().includes(pattern) ||\n        tool.source.ref.toLowerCase().includes(pattern),\n    );\n    if (excludedBy) {\n      skipped.push({ ref: tool.source.ref, reason: `excluded by config (\"${excludedBy}\")` });\n      continue;\n    }\n\n    const endpointRole = endpointRoleFor(tool);\n    if (endpointRole === \"webhook\") {\n      skipped.push({\n        ref: tool.source.ref,\n        reason: \"a webhook receives server callbacks; an agent has nothing to call\",\n      });\n      continue;\n    }\n\n    const sideEffect = classifySideEffect(tool);\n    tools.push({\n      ...tool,\n      sideEffect,\n      endpointRole,\n      riskTier: riskTierFor(sideEffect),\n      hints: hintsFor(tool, sideEffect),\n      // Reads work out of the box. Mutations, auth, and admin endpoints start\n      // disabled: the working code is generated but commented out, so enabling\n      // one is a deliberate edit, never an accident.\n      enabledByDefault: sideEffect === \"read\" && endpointRole === \"endpoint\",\n      piiInOutput: findPiiFields(tool.outputSchema, safety.piiFields),\n    });\n  }\n\n  return { tools, skipped };\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, so \" +\n          \"make sure your server-side authorization checks apply to tool calls too.\",\n      });\n    }\n\n    if (tool.endpointRole === \"auth\") {\n      findings.push({\n        level: \"warning\",\n        tool: tool.name,\n        message:\n          \"This looks like a sign-in or session endpoint. It is generated disabled: \" +\n          \"agents should not drive authentication. Enable it by hand only if you are sure.\",\n      });\n    }\n\n    if (tool.endpointRole === \"admin\") {\n      findings.push({\n        level: \"warning\",\n        tool: tool.name,\n        message:\n          \"Admin endpoint. It is generated disabled: exposing admin operations to agents \" +\n          \"should be a deliberate decision, reviewed endpoint by endpoint.\",\n      });\n    }\n\n    if (tool.httpMethod === \"POST\" && tool.sideEffect === \"read\") {\n      findings.push({\n        level: \"warning\",\n        tool: tool.name,\n        message:\n          \"A POST treated as a read (the name says search/query-style). If it actually \" +\n          \"changes state, disable it: a mislabeled read skips the user-confirmation step.\",\n      });\n    }\n  }\n\n  return findings;\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-TGOJ3HUE.js

@@ -0,0 +1,382 @@
+import {
+  jsonSchemaToTs,
+  pascalCase
+} from "./chunk-KSQMJERY.js";
+
+// src/generators/js.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+
+// src/generators/js-templates.ts
+function generatedRegion(tool) {
+  const pascal = pascalCase(tool.name);
+  const camel = lowercaseFirst(pascal);
+  const schemaJson = JSON.stringify(tool.inputSchema, null, 2);
+  const inputType = jsonSchemaToTs(tool.inputSchema, void 0);
+  const mutates = tool.riskTier !== "safe-read";
+  const runtimeImports = [
+    "getModelContext",
+    ...mutates ? ["requestUserConfirmation"] : [],
+    "callApi",
+    "toolResult",
+    ...tool.enabledByDefault ? [] : ["toolDisabled"]
+  ].join(", ");
+  const registerBody = mutates ? [
+    `  await modelContext.registerTool(`,
+    `    {`,
+    `      ...${camel}Tool,`,
+    `      execute: async (input) => {`,
+    `        // This tool changes things, so the user is always asked first. The`,
+    `        // confirmation lives in the generated region: it cannot be edited away.`,
+    `        const confirmed = await requestUserConfirmation(`,
+    `          ${JSON.stringify(`Allow the agent to: ${tool.description}`)},`,
+    `        );`,
+    `        if (!confirmed) {`,
+    `          return {`,
+    `            content: [{ type: "text", text: "The user declined this action." }],`,
+    `            isError: true,`,
+    `          };`,
+    `        }`,
+    `        // The browser has already validated the agent's input against the schema.`,
+    `        return execute${pascal}(input as ${tool.inputTypeName});`,
+    `      },`,
+    `    },`,
+    `    { signal },`,
+    `  );`
+  ] : [
+    `  await modelContext.registerTool(`,
+    `    {`,
+    `      ...${camel}Tool,`,
+    `      // The browser has already validated the agent's input against the schema.`,
+    `      execute: (input) => execute${pascal}(input as ${tool.inputTypeName}),`,
+    `    },`,
+    `    { signal },`,
+    `  );`
+  ];
+  return [
+    `import { ${runtimeImports} } from "./runtime.webmcp";`,
+    ``,
+    GENERATED_START,
+    `/**`,
+    ` * ${tool.description}`,
+    ` *`,
+    ` * Source: ${tool.source.ref} (${tool.source.kind}). Risk: ${tool.riskTier}.`,
+    ` * Starts ${tool.enabledByDefault ? "enabled" : "disabled"} (see execute${pascal} below).`,
+    ` * Regenerate with: npx webmcp-codegen generate`,
+    ` */`,
+    ``,
+    `/** The exact contract advertised to the agent. Derived from the API spec. Do not hand-edit. */`,
+    `export const ${camel}InputSchema = ${schemaJson};`,
+    ``,
+    `/** What \`execute\` receives. The browser validates agent input against the schema above. */`,
+    `export type ${tool.inputTypeName} = ${inputType};`,
+    ``,
+    `/** Safety hints computed by webmcp-codegen. Informational metadata for hosts and UIs. */`,
+    `export const ${camel}Hints = ${JSON.stringify(tool.hints)} as const;`,
+    ``,
+    `/** The tool definition, minus \`execute\` (which is yours, below the marker). */`,
+    `export const ${camel}Tool = {`,
+    `  name: ${JSON.stringify(tool.name)},`,
+    `  description: ${JSON.stringify(tool.description)},`,
+    `  inputSchema: ${camel}InputSchema,`,
+    `};`,
+    ``,
+    `/**`,
+    ` * Register this tool with WebMCP. Call it once on page load, or use`,
+    ` * registerAllTools() from the generated index.ts.`,
+    ` *`,
+    ` * Pass an AbortSignal to unregister later: controller.abort().`,
+    ` */`,
+    `export async function register${pascal}(signal?: AbortSignal): Promise<void> {`,
+    `  const modelContext = getModelContext();`,
+    ...registerBody,
+    `}`,
+    ``,
+    GENERATED_END
+  ].join("\n");
+}
+function ownedRegionScaffold(tool) {
+  const pascal = pascalCase(tool.name);
+  const call = requestCall(tool);
+  const lines = [
+    ``,
+    `/**`,
+    ` * What actually happens when the agent calls "${tool.name}".`,
+    ` *`,
+    ` * Default implementation: calls ${tool.source.ref} from this page, with the`,
+    ` * signed-in user's session. Replace it with your app's own API client`,
+    ` * whenever you like; the contract above never changes.`
+  ];
+  if (tool.serverUrl) {
+    lines.push(
+      ` *`,
+      ` * Your spec lists the API at ${tool.serverUrl}. If the app and the API`,
+      ` * are on different hosts, pass the full URL to callApi instead.`
+    );
+  }
+  if (tool.riskTier !== "safe-read") {
+    lines.push(
+      ` *`,
+      ` * This tool is ${tool.riskTier}: it ${tool.riskTier === "destructive-confirm" ? "cannot easily be undone" : "changes things"}.`,
+      ` * The user is asked to confirm every call (built into the generated region).`
+    );
+  }
+  lines.push(` */`);
+  if (tool.piiInOutput.length > 0) {
+    lines.push(
+      `//`,
+      `// \u26A0 webmcp-codegen flagged these response fields as likely PII: ${tool.piiInOutput.join(", ")}.`,
+      `// Everything you return reaches the agent. Leave those fields out of what you`,
+      `// return unless the agent genuinely needs them, and say so in a comment if you keep them.`
+    );
+  }
+  if (tool.enabledByDefault) {
+    lines.push(
+      `export async function execute${pascal}(input: ${tool.inputTypeName}) {`,
+      `  ${call}`,
+      `  return toolResult(data);`,
+      `}`
+    );
+  } else {
+    lines.push(
+      `export async function execute${pascal}(input: ${tool.inputTypeName}) {`,
+      `  // This tool starts disabled: it ${tool.endpointRole === "endpoint" ? "changes things" : `wraps an ${tool.endpointRole} endpoint`}. Agents can see it, and calling it tells`,
+      `  // them it is disabled. To enable it, delete the line below and uncomment the code.`,
+      `  return toolDisabled("${tool.name}.webmcp.ts");`,
+      ``,
+      `  // ${call}`,
+      `  // return toolResult(data);`,
+      `}`
+    );
+  }
+  return lines.join("\n");
+}
+function requestCall(tool) {
+  if (!tool.httpMethod || !tool.pathTemplate || !tool.paramLocations) {
+    return `const data = null; // TODO: call your app's existing code here.`;
+  }
+  const { path: pathParams, query: queryParams, body: bodyParams } = tool.paramLocations;
+  let pathExpr = `\`${tool.pathTemplate.replace(/\{([^}]+)\}/g, (_m, param) => `\${${inputRef(param)}}`)}\``;
+  if (pathParams.length === 0) pathExpr = JSON.stringify(tool.pathTemplate);
+  const options = [`method: ${JSON.stringify(tool.httpMethod)}`];
+  if (queryParams.length > 0) {
+    const entries = queryParams.map((name) => `${safeKey(name)}: ${inputRef(name)}`).join(", ");
+    options.push(`query: { ${entries} }`);
+  }
+  if (bodyParams.length > 0) {
+    if (bodyParams.length === 1 && bodyParams[0] === "body") {
+      options.push(`body: input.body`);
+    } else {
+      const entries = bodyParams.map((name) => `${safeKey(name)}: ${inputRef(name)}`).join(", ");
+      options.push(`body: { ${entries} }`);
+    }
+  }
+  return `const data = await callApi(${pathExpr}, { ${options.join(", ")} });`;
+}
+function inputRef(name) {
+  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? `input.${name}` : `input[${JSON.stringify(name)}]`;
+}
+function safeKey(name) {
+  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+}
+function runtimeSource() {
+  return `/**
+ * Generated by webmcp-codegen. This file is fully regenerated on every run.
+ * Do not edit by hand; your changes will be lost.
+ */
+
+/** The result shape tools return (same as MCP tool results). */
+export interface WebMcpToolResult {
+  content: { type: "text"; text: string }[];
+  isError?: boolean;
+  [key: string]: unknown;
+}
+
+/** A tool as the browser runtime understands it. */
+export interface WebMcpToolDefinition {
+  name: string;
+  description: string;
+  inputSchema?: Record<string, unknown>;
+  execute: (input: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+
+/** The slice of the WebMCP draft spec the generated code uses. */
+export interface ModelContext {
+  registerTool(
+    tool: WebMcpToolDefinition,
+    options?: { signal?: AbortSignal },
+  ): Promise<void>;
+}
+
+/**
+ * Access the page's WebMCP model context, with a helpful error when the
+ * browser doesn't have one (rather than an undefined-callsite mystery).
+ */
+export function getModelContext(): ModelContext {
+  const modelContext = (document as unknown as { modelContext?: ModelContext }).modelContext;
+  if (!modelContext) {
+    throw new Error(
+      "WebMCP is not available in this browser. " +
+        "Enable chrome://flags/#enable-webmcp-testing (Chrome 146+), " +
+        "or add the WebMCP polyfill to your app.",
+    );
+  }
+  return modelContext;
+}
+
+/**
+ * Call your API from the page. Same origin by default (pass a full URL when
+ * the API lives on another host), always with the signed-in user's session
+ * cookies. Throws on HTTP errors; returns the parsed JSON body, or raw text
+ * when the response is not JSON.
+ */
+export async function callApi(
+  path: string,
+  options: { method?: string; query?: Record<string, unknown>; body?: unknown } = {},
+): Promise<unknown> {
+  const url = new URL(path, window.location.origin);
+  for (const [key, value] of Object.entries(options.query ?? {})) {
+    if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+  }
+  const response = await fetch(url, {
+    method: options.method ?? "GET",
+    credentials: "include",
+    headers: options.body !== undefined ? { "content-type": "application/json" } : undefined,
+    body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+  });
+  if (!response.ok) {
+    throw new Error("Request failed: " + response.status + " " + response.statusText);
+  }
+  if (response.status === 204) return null;
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+/** Wrap a result in the MCP shape, so tool bodies stay one line. */
+export function toolResult(data: unknown): WebMcpToolResult {
+  return {
+    content: [
+      { type: "text", text: typeof data === "string" ? data : JSON.stringify(data, null, 2) },
+    ],
+  };
+}
+
+/**
+ * What a disabled tool tells the agent. The tool stays visible (so the agent
+ * knows it exists and can ask the human to enable it) but does nothing.
+ */
+export function toolDisabled(fileName: string): WebMcpToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text:
+          "This tool is currently disabled by the app developer. Ask them to enable it " +
+          "(uncomment the implementation in " + fileName + ").",
+      },
+    ],
+    isError: true,
+  };
+}
+
+/**
+ * Default "agent proposes, human confirms" gate for write/destructive tools.
+ * Deliberately minimal (window.confirm). Replace it with your app's own
+ * dialog when you outgrow it. The point is that the user always gets a say.
+ */
+export function requestUserConfirmation(message: string): Promise<boolean> {
+  return Promise.resolve(window.confirm(message));
+}
+`;
+}
+function barrelSource(tools) {
+  const imports = tools.map((tool) => `import { register${pascalCase(tool.name)} } from "./${tool.name}.webmcp";`).join("\n");
+  const names = tools.map((tool) => `register${pascalCase(tool.name)}`).join(",\n  ");
+  return `/**
+ * Generated by webmcp-codegen. This file is fully regenerated on every run.
+ * Import registerAllTools() once at app startup:
+ *
+ *   import { registerAllTools } from "./webmcp";
+ *   await registerAllTools();
+ */
+
+${imports}
+
+const registrations = [
+  ${names}
+];
+
+/**
+ * Register every generated tool with WebMCP. One tool failing (for example
+ * because the page's Permissions-Policy disables tools) never takes the
+ * others down with it. The failure is logged and registration continues.
+ */
+export async function registerAllTools(signal?: AbortSignal): Promise<void> {
+  for (const register of registrations) {
+    try {
+      await register(signal);
+    } catch (error) {
+      console.warn("[webmcp-codegen] a tool failed to register:", error);
+    }
+  }
+}
+`;
+}
+function lowercaseFirst(pascal) {
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+
+// src/generators/js.ts
+var GENERATED_START = "// \u2500\u2500\u2500 webmcp-codegen: generated. Do not edit this region. \u2500\u2500\u2500";
+var GENERATED_END = "// \u2500\u2500\u2500 webmcp-codegen: end generated. Your code below survives regeneration. \u2500\u2500\u2500";
+function js(options) {
+  return {
+    kind: "js",
+    outDir: options.outDir,
+    async generate(tools, cwd) {
+      const outDir = join(cwd, options.outDir);
+      const files = [];
+      files.push(await plainFile(join(outDir, "runtime.webmcp.ts"), runtimeSource()));
+      files.push(await plainFile(join(outDir, "index.ts"), barrelSource(tools)));
+      for (const tool of tools) {
+        files.push(await toolFile(tool, outDir));
+      }
+      return files;
+    }
+  };
+}
+async function plainFile(path, contents) {
+  try {
+    const existing = await readFile(path, "utf8");
+    return { path, contents, action: existing === contents ? "unchanged" : "update" };
+  } catch {
+    return { path, contents, action: "create" };
+  }
+}
+async function toolFile(tool, outDir) {
+  const path = join(outDir, `${tool.name}.webmcp.ts`);
+  const head = generatedRegion(tool);
+  let existing;
+  try {
+    existing = await readFile(path, "utf8");
+  } catch {
+    return { path, contents: `${head}
+${ownedRegionScaffold(tool)}`, action: "create" };
+  }
+  const markerIndex = existing.indexOf(GENERATED_END);
+  if (markerIndex === -1) {
+    return { path, contents: existing, action: "unchanged", conflict: `${path}.new` };
+  }
+  const preservedTail = existing.slice(markerIndex + GENERATED_END.length);
+  const contents = head + preservedTail;
+  return { path, contents, action: contents === existing ? "unchanged" : "update" };
+}
+
+export {
+  js
+};
+//# sourceMappingURL=chunk-TGOJ3HUE.js.map