webmcp-codegen 0.2.0 → 0.3.0

package/dist/chunk-TGOJ3HUE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/generators/js.ts","../src/generators/js-templates.ts"],"sourcesContent":["/**\n * The `js` generator, named after what lands in your repo: plain JavaScript/\n * TypeScript files that call the spec's imperative API\n * (`document.modelContext.registerTool`).\n *\n * Output layout for `js({ outDir: \"./src/webmcp\" })`:\n *\n *   src/webmcp/\n *   ├── runtime.webmcp.ts          ← fully generated, never edit\n *   ├── index.ts                   ← fully generated, registers everything\n *   ├── get-order-status.webmcp.ts ← generated contract + YOUR execute()\n *   └── ...\n *\n * Each per-tool file has two regions, divided by marker comments:\n *\n *   generated region   schema, input type, tool definition, register()\n *   ── end generated ── everything below survives regeneration\n *   your region        execute(), scaffolded once, then owned by you\n *\n * This file contains only the *file mechanics*: which files exist, and how to\n * update them without destroying hand-written code. The text of the generated\n * code itself lives in js-templates.ts, keeping \"what the output looks like\"\n * separate from \"how files get written\" is what keeps both readable.\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport type { GeneratedFile, ReviewedTool, ToolGenerator } from \"../types.js\";\nimport {\n  barrelSource,\n  generatedRegion,\n  ownedRegionScaffold,\n  runtimeSource,\n} from \"./js-templates.js\";\n\nexport interface JsGeneratorOptions {\n  /** Where the tool files go, relative to the project root. */\n  outDir: string;\n}\n\n/**\n * The marker lines that split a per-tool file in two. They are the merge\n * contract: we may rewrite everything up to and including GENERATED_END,\n * and we must never touch anything after it. js-templates.ts imports these\n * so the marker text is defined in exactly one place.\n */\nexport const GENERATED_START = \"// ─── webmcp-codegen: generated. Do not edit this region. ───\";\nexport const GENERATED_END =\n  \"// ─── webmcp-codegen: end generated. Your code below survives regeneration. ───\";\n\n/** Create the `js` generator for the config's `generate` array. */\nexport function js(options: JsGeneratorOptions): ToolGenerator {\n  return {\n    kind: \"js\",\n    outDir: options.outDir,\n    async generate(tools, cwd) {\n      const outDir = join(cwd, options.outDir);\n      const files: GeneratedFile[] = [];\n\n      // The runtime and the barrel are regenerated wholesale every run;\n      // their headers say \"do not edit\", and we mean it.\n      files.push(await plainFile(join(outDir, \"runtime.webmcp.ts\"), runtimeSource()));\n      files.push(await plainFile(join(outDir, \"index.ts\"), barrelSource(tools)));\n\n      for (const tool of tools) {\n        files.push(await toolFile(tool, outDir));\n      }\n      return files;\n    },\n  };\n}\n\n/** A fully-generated file: create if missing, overwrite if changed, skip if same. */\nasync function plainFile(path: string, contents: string): Promise<GeneratedFile> {\n  try {\n    const existing = await readFile(path, \"utf8\");\n    return { path, contents, action: existing === contents ? \"unchanged\" : \"update\" };\n  } catch {\n    return { path, contents, action: \"create\" };\n  }\n}\n\n/**\n * Build (or merge) one per-tool file. The only I/O here is reading the\n * existing file to check for a hand-written region worth keeping.\n */\nasync function toolFile(tool: ReviewedTool, outDir: string): Promise<GeneratedFile> {\n  const path = join(outDir, `${tool.name}.webmcp.ts`);\n  const head = generatedRegion(tool);\n\n  let existing: string | undefined;\n  try {\n    existing = await readFile(path, \"utf8\");\n  } catch {\n    // No file yet: brand new tool, so we also lay down the execute() scaffold.\n    return { path, contents: `${head}\\n${ownedRegionScaffold(tool)}`, action: \"create\" };\n  }\n\n  const markerIndex = existing.indexOf(GENERATED_END);\n  if (markerIndex === -1) {\n    // Someone removed the markers or hand-wrote this path from scratch.\n    // Never clobber their work: report a conflict and let the pipeline put\n    // our version in a `.new` sibling for a human to merge.\n    return { path, contents: existing, action: \"unchanged\", conflict: `${path}.new` };\n  }\n\n  // Keep everything the developer wrote below the marker, word for word.\n  const preservedTail = existing.slice(markerIndex + GENERATED_END.length);\n  const contents = head + preservedTail;\n  return { path, contents, action: contents === existing ? \"unchanged\" : \"update\" };\n}\n","/**\n * The text of the code the `js` generator writes.\n *\n * Heads up before reading on: every function here returns *TypeScript source\n * code as a string*. When you see `export const ...` inside quotes, that's\n * the output a user's repo will contain, not this module's own logic.\n * Building output from arrays of lines (rather than nested template strings)\n * keeps the quoting readable; the only escaping left is for code samples\n * inside the generated comments.\n *\n * Three kinds of output are built here:\n *   - generatedRegion()      the per-tool contract (regenerated freely)\n *   - ownedRegionScaffold()  the execute() body (written once, then owned)\n *   - runtimeSource() / barrelSource()   fully-generated support files\n *\n * The contract the output fulfills: read tools work out of the box (a real\n * request to the endpoint), mutation tools start disabled with the working\n * code generated but commented out, and the user-confirmation step for\n * mutations lives in the generated region so it cannot be edited away.\n */\n\nimport { jsonSchemaToTs, pascalCase } from \"../schema.js\";\nimport type { ReviewedTool } from \"../types.js\";\nimport { GENERATED_END, GENERATED_START } from \"./js.js\";\n\n/**\n * Everything above the end-marker of a per-tool file: the parts that must\n * track the API contract exactly: name, description, schema, input type,\n * hints, and the register() wrapper.\n */\nexport function generatedRegion(tool: ReviewedTool): string {\n  const pascal = pascalCase(tool.name);\n  const camel = lowercaseFirst(pascal);\n  const schemaJson = JSON.stringify(tool.inputSchema, null, 2);\n  const inputType = jsonSchemaToTs(tool.inputSchema, undefined);\n  const mutates = tool.riskTier !== \"safe-read\";\n\n  // The imports cover what this file's regions use: the generated register()\n  // and the owned execute() scaffold. A developer who replaces the scaffold\n  // with their own API client can trim the imports they stop using.\n  const runtimeImports = [\n    \"getModelContext\",\n    ...(mutates ? [\"requestUserConfirmation\"] : []),\n    \"callApi\",\n    \"toolResult\",\n    ...(tool.enabledByDefault ? [] : [\"toolDisabled\"]),\n  ].join(\", \");\n\n  const registerBody = mutates\n    ? [\n        `  await modelContext.registerTool(`,\n        `    {`,\n        `      ...${camel}Tool,`,\n        `      execute: async (input) => {`,\n        `        // This tool changes things, so the user is always asked first. The`,\n        `        // confirmation lives in the generated region: it cannot be edited away.`,\n        `        const confirmed = await requestUserConfirmation(`,\n        `          ${JSON.stringify(`Allow the agent to: ${tool.description}`)},`,\n        `        );`,\n        `        if (!confirmed) {`,\n        `          return {`,\n        `            content: [{ type: \"text\", text: \"The user declined this action.\" }],`,\n        `            isError: true,`,\n        `          };`,\n        `        }`,\n        `        // The browser has already validated the agent's input against the schema.`,\n        `        return execute${pascal}(input as ${tool.inputTypeName});`,\n        `      },`,\n        `    },`,\n        `    { signal },`,\n        `  );`,\n      ]\n    : [\n        `  await modelContext.registerTool(`,\n        `    {`,\n        `      ...${camel}Tool,`,\n        `      // The browser has already validated the agent's input against the schema.`,\n        `      execute: (input) => execute${pascal}(input as ${tool.inputTypeName}),`,\n        `    },`,\n        `    { signal },`,\n        `  );`,\n      ];\n\n  return [\n    `import { ${runtimeImports} } from \"./runtime.webmcp\";`,\n    ``,\n    GENERATED_START,\n    `/**`,\n    ` * ${tool.description}`,\n    ` *`,\n    ` * Source: ${tool.source.ref} (${tool.source.kind}). Risk: ${tool.riskTier}.`,\n    ` * Starts ${tool.enabledByDefault ? \"enabled\" : \"disabled\"} (see execute${pascal} below).`,\n    ` * Regenerate with: npx webmcp-codegen generate`,\n    ` */`,\n    ``,\n    `/** The exact contract advertised to the agent. Derived from the API spec. Do not hand-edit. */`,\n    `export const ${camel}InputSchema = ${schemaJson};`,\n    ``,\n    `/** What \\`execute\\` receives. The browser validates agent input against the schema above. */`,\n    `export type ${tool.inputTypeName} = ${inputType};`,\n    ``,\n    `/** Safety hints computed by webmcp-codegen. Informational metadata for hosts and UIs. */`,\n    `export const ${camel}Hints = ${JSON.stringify(tool.hints)} as const;`,\n    ``,\n    `/** The tool definition, minus \\`execute\\` (which is yours, below the marker). */`,\n    `export const ${camel}Tool = {`,\n    `  name: ${JSON.stringify(tool.name)},`,\n    `  description: ${JSON.stringify(tool.description)},`,\n    `  inputSchema: ${camel}InputSchema,`,\n    `};`,\n    ``,\n    `/**`,\n    ` * Register this tool with WebMCP. Call it once on page load, or use`,\n    ` * registerAllTools() from the generated index.ts.`,\n    ` *`,\n    ` * Pass an AbortSignal to unregister later: controller.abort().`,\n    ` */`,\n    `export async function register${pascal}(signal?: AbortSignal): Promise<void> {`,\n    `  const modelContext = getModelContext();`,\n    ...registerBody,\n    `}`,\n    ``,\n    GENERATED_END,\n  ].join(\"\\n\");\n}\n\n/**\n * The scaffold below the marker, written exactly once (when the file is\n * first created). After that the developer owns it and regeneration never\n * touches it. That promise is the whole reason the marker split exists.\n *\n * The scaffold is real code, not a TODO: the spec knows the method, the\n * path, and which fields go where, so the default implementation actually\n * calls the endpoint from the page, with the signed-in user's session.\n * Reads are born working; mutations are born disabled (the working code is\n * right there, commented out, one deliberate edit away from live).\n */\nexport function ownedRegionScaffold(tool: ReviewedTool): string {\n  const pascal = pascalCase(tool.name);\n  const call = requestCall(tool);\n  const lines: string[] = [\n    ``,\n    `/**`,\n    ` * What actually happens when the agent calls \"${tool.name}\".`,\n    ` *`,\n    ` * Default implementation: calls ${tool.source.ref} from this page, with the`,\n    ` * signed-in user's session. Replace it with your app's own API client`,\n    ` * whenever you like; the contract above never changes.`,\n  ];\n\n  if (tool.serverUrl) {\n    lines.push(\n      ` *`,\n      ` * Your spec lists the API at ${tool.serverUrl}. If the app and the API`,\n      ` * are on different hosts, pass the full URL to callApi instead.`,\n    );\n  }\n\n  if (tool.riskTier !== \"safe-read\") {\n    lines.push(\n      ` *`,\n      ` * This tool is ${tool.riskTier}: it ${\n        tool.riskTier === \"destructive-confirm\" ? \"cannot easily be undone\" : \"changes things\"\n      }.`,\n      ` * The user is asked to confirm every call (built into the generated region).`,\n    );\n  }\n  lines.push(` */`);\n\n  if (tool.piiInOutput.length > 0) {\n    lines.push(\n      `//`,\n      `// ⚠ webmcp-codegen flagged these response fields as likely PII: ${tool.piiInOutput.join(\", \")}.`,\n      `// Everything you return reaches the agent. Leave those fields out of what you`,\n      `// return unless the agent genuinely needs them, and say so in a comment if you keep them.`,\n    );\n  }\n\n  if (tool.enabledByDefault) {\n    lines.push(\n      `export async function execute${pascal}(input: ${tool.inputTypeName}) {`,\n      `  ${call}`,\n      `  return toolResult(data);`,\n      `}`,\n    );\n  } else {\n    lines.push(\n      `export async function execute${pascal}(input: ${tool.inputTypeName}) {`,\n      `  // This tool starts disabled: it ${\n        tool.endpointRole === \"endpoint\"\n          ? \"changes things\"\n          : `wraps an ${tool.endpointRole} endpoint`\n      }. Agents can see it, and calling it tells`,\n      `  // them it is disabled. To enable it, delete the line below and uncomment the code.`,\n      `  return toolDisabled(\"${tool.name}.webmcp.ts\");`,\n      ``,\n      `  // ${call}`,\n      `  // return toolResult(data);`,\n      `}`,\n    );\n  }\n\n  return lines.join(\"\\n\");\n}\n\n/**\n * The one working request line inside a scaffold, built from what the spec\n * knows: the path template becomes a template literal, query params become\n * the search string, body fields become the JSON body.\n *\n *   \"/pets/{id}\" + DELETE  →  const data = await callApi(`/pets/${input.id}`, { method: \"DELETE\" });\n *\n * When the source carries no route information, we fall back to an honest\n * TODO instead of inventing a URL.\n */\nfunction requestCall(tool: ReviewedTool): string {\n  if (!tool.httpMethod || !tool.pathTemplate || !tool.paramLocations) {\n    return `const data = null; // TODO: call your app's existing code here.`;\n  }\n\n  const { path: pathParams, query: queryParams, body: bodyParams } = tool.paramLocations;\n\n  // \"/pets/{id}\" → `/pets/${input.id}`. Params the schema knows by name.\n  let pathExpr = `\\`${tool.pathTemplate.replace(/\\{([^}]+)\\}/g, (_m, param: string) => `\\${${inputRef(param)}}`)}\\``;\n  if (pathParams.length === 0) pathExpr = JSON.stringify(tool.pathTemplate);\n\n  const options: string[] = [`method: ${JSON.stringify(tool.httpMethod)}`];\n  if (queryParams.length > 0) {\n    const entries = queryParams.map((name) => `${safeKey(name)}: ${inputRef(name)}`).join(\", \");\n    options.push(`query: { ${entries} }`);\n  }\n  if (bodyParams.length > 0) {\n    if (bodyParams.length === 1 && bodyParams[0] === \"body\") {\n      // A non-object request body arrives as a single \"body\" field.\n      options.push(`body: input.body`);\n    } else {\n      const entries = bodyParams.map((name) => `${safeKey(name)}: ${inputRef(name)}`).join(\", \");\n      options.push(`body: { ${entries} }`);\n    }\n  }\n\n  return `const data = await callApi(${pathExpr}, { ${options.join(\", \")} });`;\n}\n\n/**\n * How generated code reads a field off `input`. Dot access for identifier\n * names (\"input.limit\"), bracket access for the rest (\"input[\"pet-id\"]\").\n */\nfunction inputRef(name: string): string {\n  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name)\n    ? `input.${name}`\n    : `input[${JSON.stringify(name)}]`;\n}\n\n/** Quote an object key only when it needs it. */\nfunction safeKey(name: string): string {\n  return /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(name) ? name : JSON.stringify(name);\n}\n\n/**\n * The shared runtime: the minimal WebMCP browser types plus the helpers the\n * generated files use. Kept tiny on purpose: this is the only browser\n * coupling in the output.\n */\nexport function runtimeSource(): string {\n  return `/**\n * Generated by webmcp-codegen. This file is fully regenerated on every run.\n * Do not edit by hand; your changes will be lost.\n */\n\n/** The result shape tools return (same as MCP tool results). */\nexport interface WebMcpToolResult {\n  content: { type: \"text\"; text: string }[];\n  isError?: boolean;\n  [key: string]: unknown;\n}\n\n/** A tool as the browser runtime understands it. */\nexport interface WebMcpToolDefinition {\n  name: string;\n  description: string;\n  inputSchema?: Record<string, unknown>;\n  execute: (input: Record<string, unknown>) => unknown | Promise<unknown>;\n}\n\n/** The slice of the WebMCP draft spec the generated code uses. */\nexport interface ModelContext {\n  registerTool(\n    tool: WebMcpToolDefinition,\n    options?: { signal?: AbortSignal },\n  ): Promise<void>;\n}\n\n/**\n * Access the page's WebMCP model context, with a helpful error when the\n * browser doesn't have one (rather than an undefined-callsite mystery).\n */\nexport function getModelContext(): ModelContext {\n  const modelContext = (document as unknown as { modelContext?: ModelContext }).modelContext;\n  if (!modelContext) {\n    throw new Error(\n      \"WebMCP is not available in this browser. \" +\n        \"Enable chrome://flags/#enable-webmcp-testing (Chrome 146+), \" +\n        \"or add the WebMCP polyfill to your app.\",\n    );\n  }\n  return modelContext;\n}\n\n/**\n * Call your API from the page. Same origin by default (pass a full URL when\n * the API lives on another host), always with the signed-in user's session\n * cookies. Throws on HTTP errors; returns the parsed JSON body, or raw text\n * when the response is not JSON.\n */\nexport async function callApi(\n  path: string,\n  options: { method?: string; query?: Record<string, unknown>; body?: unknown } = {},\n): Promise<unknown> {\n  const url = new URL(path, window.location.origin);\n  for (const [key, value] of Object.entries(options.query ?? {})) {\n    if (value !== undefined && value !== null) url.searchParams.set(key, String(value));\n  }\n  const response = await fetch(url, {\n    method: options.method ?? \"GET\",\n    credentials: \"include\",\n    headers: options.body !== undefined ? { \"content-type\": \"application/json\" } : undefined,\n    body: options.body !== undefined ? JSON.stringify(options.body) : undefined,\n  });\n  if (!response.ok) {\n    throw new Error(\"Request failed: \" + response.status + \" \" + response.statusText);\n  }\n  if (response.status === 204) return null;\n  const text = await response.text();\n  try {\n    return JSON.parse(text);\n  } catch {\n    return text;\n  }\n}\n\n/** Wrap a result in the MCP shape, so tool bodies stay one line. */\nexport function toolResult(data: unknown): WebMcpToolResult {\n  return {\n    content: [\n      { type: \"text\", text: typeof data === \"string\" ? data : JSON.stringify(data, null, 2) },\n    ],\n  };\n}\n\n/**\n * What a disabled tool tells the agent. The tool stays visible (so the agent\n * knows it exists and can ask the human to enable it) but does nothing.\n */\nexport function toolDisabled(fileName: string): WebMcpToolResult {\n  return {\n    content: [\n      {\n        type: \"text\",\n        text:\n          \"This tool is currently disabled by the app developer. Ask them to enable it \" +\n          \"(uncomment the implementation in \" + fileName + \").\",\n      },\n    ],\n    isError: true,\n  };\n}\n\n/**\n * Default \"agent proposes, human confirms\" gate for write/destructive tools.\n * Deliberately minimal (window.confirm). Replace it with your app's own\n * dialog when you outgrow it. The point is that the user always gets a say.\n */\nexport function requestUserConfirmation(message: string): Promise<boolean> {\n  return Promise.resolve(window.confirm(message));\n}\n`;\n}\n\n/** The barrel: one import that registers every generated tool. */\nexport function barrelSource(tools: ReviewedTool[]): string {\n  const imports = tools\n    .map((tool) => `import { register${pascalCase(tool.name)} } from \"./${tool.name}.webmcp\";`)\n    .join(\"\\n\");\n  const names = tools.map((tool) => `register${pascalCase(tool.name)}`).join(\",\\n  \");\n\n  return `/**\n * Generated by webmcp-codegen. This file is fully regenerated on every run.\n * Import registerAllTools() once at app startup:\n *\n *   import { registerAllTools } from \"./webmcp\";\n *   await registerAllTools();\n */\n\n${imports}\n\nconst registrations = [\n  ${names}\n];\n\n/**\n * Register every generated tool with WebMCP. One tool failing (for example\n * because the page's Permissions-Policy disables tools) never takes the\n * others down with it. The failure is logged and registration continues.\n */\nexport async function registerAllTools(signal?: AbortSignal): Promise<void> {\n  for (const register of registrations) {\n    try {\n      await register(signal);\n    } catch (error) {\n      console.warn(\"[webmcp-codegen] a tool failed to register:\", error);\n    }\n  }\n}\n`;\n}\n\n/** \"GetOrderStatus\" → \"getOrderStatus\" (for the generated const names). */\nfunction lowercaseFirst(pascal: string): string {\n  return pascal.charAt(0).toLowerCase() + pascal.slice(1);\n}\n"],"mappings":"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","names":[]}

package/dist/cli.js

@@ -1,81 +1,181 @@
 #!/usr/bin/env node
 import {
-  CONFIG_FILE_NAMES,
-  loadConfig,
-  runGenerate
-} from "./chunk-R3DEBBQ3.js";
-import {
-  js
-} from "./chunk-GDJDVR4E.js";
+  findSpecs,
+  loadDataFile,
+  resolveSetup,
+  saveDataFile
+} from "./chunk-JVBVTHZ7.js";
 import {
-  openapi
-} from "./chunk-WYGVTIGI.js";
-import "./chunk-BIKKPCRT.js";
-import "./chunk-5L4KN6F4.js";
+  runGenerate
+} from "./chunk-MJQ5B6HB.js";
+import "./chunk-TGOJ3HUE.js";
+import "./chunk-3LTHWIAP.js";
+import "./chunk-FWSATV7C.js";
+import "./chunk-KSQMJERY.js";
 
 // src/cli.ts
 import { existsSync, watch } from "fs";
-import { writeFile } from "fs/promises";
-import { basename, join as join2, relative as relative2 } from "path";
+import { writeFile as writeFile2 } from "fs/promises";
+import { join as join2, relative as relative2 } from "path";
+import "readline/promises";
 import { parseArgs } from "util";
 
-// src/detect.ts
-import { readdir } from "fs/promises";
-import { join, relative } from "path";
-var SPEC_FILE_PATTERN = /^(openapi|swagger|api)\.(ya?ml|json)$/i;
-var IGNORED_DIRS = /* @__PURE__ */ new Set([
-  "node_modules",
-  ".git",
-  ".turbo",
-  ".next",
-  "dist",
-  "build",
-  "coverage"
-]);
-var MAX_DEPTH = 5;
-async function findSpecs(cwd) {
-  const found = [];
-  async function walk(dir, depth) {
-    if (depth > MAX_DEPTH) return;
-    let entries;
-    try {
-      entries = await readdir(dir, { withFileTypes: true });
-    } catch {
-      return;
+// src/wire.ts
+import { readFile, writeFile } from "fs/promises";
+import { dirname, join, relative } from "path";
+async function planWiring(cwd, app, outDir) {
+  switch (app.framework) {
+    case "next":
+      return planNextWiring(cwd, app, outDir);
+    case "vite-react":
+      return planViteWiring(cwd, app, outDir);
+    default:
+      return null;
+  }
+}
+async function applyWiring(plan) {
+  for (const edit of plan.edits) {
+    await writeFile(edit.path, edit.contents, "utf8");
+  }
+}
+async function planNextWiring(cwd, app, outDir) {
+  const layoutCandidates = [
+    join(cwd, app.dir, "src/app/layout.tsx"),
+    join(cwd, app.dir, "src/app/layout.jsx"),
+    join(cwd, app.dir, "app/layout.tsx"),
+    join(cwd, app.dir, "app/layout.jsx")
+  ];
+  const layoutPath = await firstExisting(layoutCandidates);
+  if (!layoutPath) return null;
+  const registerPath = join(cwd, outDir, "register.tsx");
+  const layout = await readFile(layoutPath, "utf8");
+  if (layout.includes("WebMCPRegister")) return { edits: [], alreadyWired: true };
+  const importPath = withoutExtension(relative(dirname(layoutPath), registerPath));
+  const edits = [
+    {
+      path: registerPath,
+      action: "create",
+      contents: nextRegisterComponent(),
+      summary: `created ${relative(cwd, registerPath)} (a client component that registers your tools on page load)`
     }
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        if (!IGNORED_DIRS.has(entry.name)) await walk(join(dir, entry.name), depth + 1);
-      } else if (SPEC_FILE_PATTERN.test(entry.name)) {
-        found.push({ path: join(dir, entry.name), depth });
+  ];
+  const withImport = insertAfterLastImport(
+    layout,
+    `import { WebMCPRegister } from "${importPath}";`
+  );
+  if (!withImport) return null;
+  const withComponent = withImport.replace(
+    /<body([^>]*)>\s*/,
+    "<body$1>\n        <WebMCPRegister />\n        "
+  );
+  if (withComponent === withImport) return null;
+  edits.push({
+    path: layoutPath,
+    action: "modify",
+    contents: withComponent,
+    summary: `added 2 lines to ${relative(cwd, layoutPath)} (an import and <WebMCPRegister /> inside <body>)`
+  });
+  return { edits };
+}
+function nextRegisterComponent() {
+  return `"use client";
+
+import { useEffect } from "react";
+import { registerAllTools } from "./index";
+
+/**
+ * Registers the generated WebMCP tools once, on page load.
+ * Generated by webmcp-codegen. Safe to move; keep it mounted near the root.
+ */
+export function WebMCPRegister() {
+  useEffect(() => {
+    void registerAllTools();
+  }, []);
+  return null;
+}
+`;
+}
+async function planViteWiring(cwd, app, outDir) {
+  const entryCandidates = [
+    join(cwd, app.dir, "src/main.tsx"),
+    join(cwd, app.dir, "src/main.jsx"),
+    join(cwd, app.dir, "src/index.tsx"),
+    join(cwd, app.dir, "src/index.jsx")
+  ];
+  const entryPath = await firstExisting(entryCandidates);
+  if (!entryPath) return null;
+  const entry = await readFile(entryPath, "utf8");
+  if (entry.includes("registerAllTools")) return { edits: [], alreadyWired: true };
+  const importPath = withoutExtension(relative(dirname(entryPath), join(cwd, outDir, "index")));
+  const withWiring = insertAfterLastImport(
+    entry,
+    `import { registerAllTools } from "${importPath}";
+
+void registerAllTools();`
+  );
+  if (!withWiring) return null;
+  return {
+    edits: [
+      {
+        path: entryPath,
+        action: "modify",
+        contents: withWiring,
+        summary: `added 2 lines to ${relative(cwd, entryPath)} (an import and a registerAllTools() call)`
       }
+    ]
+  };
+}
+function insertAfterLastImport(source, line) {
+  const lines = source.split("\n");
+  let lastImport = -1;
+  for (let index = 0; index < lines.length; index += 1) {
+    if (/^import\s/.test(lines[index])) lastImport = index;
+  }
+  if (lastImport === -1) return null;
+  lines.splice(lastImport + 1, 0, line);
+  return lines.join("\n");
+}
+function withoutExtension(path) {
+  const bare = path.replace(/\.(tsx?|jsx?)$/, "").replace(/\/index$/, "");
+  return bare.startsWith(".") ? bare : `./${bare}`;
+}
+async function firstExisting(paths) {
+  for (const path of paths) {
+    try {
+      await readFile(path, "utf8");
+      return path;
+    } catch {
     }
   }
-  await walk(cwd, 0);
-  return found.sort((a, b) => a.depth - b.depth).map((entry) => relative(cwd, entry.path));
+  return void 0;
 }
 
 // src/cli.ts
-var HELP = `webmcp-codegen \u2014 generate WebMCP tools from the API contracts you already have
+var HELP = `webmcp-codegen: generate WebMCP tools from the API contracts you already have
 
 Fastest start (no install, no config):
   npx webmcp-codegen generate --dry-run   Detect your spec, preview the tools
-  npx webmcp-codegen generate             Write the tool files
+  npx webmcp-codegen generate             Write the tool files, wire them up
 
 Commands:
   init                         Write a codegen.config.mjs for full control
   generate                     Generate (or update) your WebMCP tools
   generate --watch             Re-generate when files change
+  dev                          Open the tools dashboard (list, edit, try tools)
 
 Flags for generate:
   --spec PATH    Which OpenAPI spec to use (auto-detected when omitted)
-  --out DIR      Where the tool files go (default: ./src/webmcp)
+  --out DIR      Where the tool files go (default: your web app's src/webmcp)
   --dry-run      Preview what would be written, write nothing
   --skip-audit   Skip the safety report
   --force        Write files even when the audit reports errors
   --config PATH  Use a config file at PATH
+
+Flags for dev:
+  --port N       Dashboard port (default: 4700)
 `;
 var CONFIG_FILE = "codegen.config.mjs";
+var MAX_LISTED_TOOLS = 15;
 async function main() {
   const { positionals, values } = parseArgs({
     allowPositionals: true,
@@ -87,6 +187,7 @@ async function main() {
       config: { type: "string" },
       spec: { type: "string" },
       out: { type: "string" },
+      port: { type: "string" },
       help: { type: "boolean", default: false }
     }
   });
@@ -98,6 +199,8 @@ async function main() {
   switch (command) {
     case "init":
       return init();
+    case "dev":
+      return dev(Number.parseInt(values.port ?? "4700", 10));
     case "generate":
       return generate({
         dryRun: values["dry-run"],
@@ -119,12 +222,12 @@ async function init() {
   const cwd = process.cwd();
   const configPath = join2(cwd, CONFIG_FILE);
   if (existsSync(configPath)) {
-    console.error(`${CONFIG_FILE} already exists \u2014 nothing to do.`);
+    console.error(`${CONFIG_FILE} already exists. Nothing to do.`);
     return 1;
   }
   const specs = await findSpecs(cwd);
   const specPath = specs.length > 0 ? `./${specs[0]}` : "./openapi.yaml";
-  await writeFile(
+  await writeFile2(
     configPath,
     `import { defineConfig } from "webmcp-codegen";
 import { openapi } from "webmcp-codegen/sources";
@@ -145,7 +248,7 @@ export default defineConfig({
   console.log("Installed the package? A config file needs it:");
   console.log("  npm install -D webmcp-codegen\n");
   if (specs.length > 0) {
-    console.log(`Found ${specs[0]} \u2014 wrote ${CONFIG_FILE}.`);
+    console.log(`Found ${specs[0]}. Wrote ${CONFIG_FILE}.`);
     console.log("\nNext: npx webmcp-codegen generate --dry-run");
   } else {
     console.log(`No OpenAPI spec found, so ${CONFIG_FILE} points at ./openapi.yaml.`);
@@ -163,63 +266,58 @@ async function generate(flags) {
   const result = await runOnce(cwd, flags);
   return result.blocked ? 1 : 0;
 }
-async function resolveConfig(cwd, flags) {
-  const hasConfigFile = flags.configPath ? existsSync(join2(cwd, flags.configPath)) : CONFIG_FILE_NAMES.some((name) => existsSync(join2(cwd, name)));
-  if (hasConfigFile) {
-    const { config, path } = await loadConfig(cwd, flags.configPath);
-    if (flags.spec || flags.out) {
-      console.warn(`Note: --spec/--out are ignored \u2014 ${basename(path)} is in charge here.`);
-    }
-    return { config, label: basename(path) };
-  }
-  if (flags.configPath) {
-    throw new Error(`No config file at "${flags.configPath}".`);
-  }
-  const spec = flags.spec ?? await detectSpec(cwd);
-  const outDir = flags.out ?? "./src/webmcp";
-  return {
-    config: { sources: [openapi({ spec })], generate: [js({ outDir })] },
-    label: flags.spec ? `--spec ${spec}` : `detected ${spec}`
-  };
-}
-async function detectSpec(cwd) {
-  const specs = await findSpecs(cwd);
-  if (specs.length === 0) {
-    throw new Error(
-      "No OpenAPI spec found in this project.\nPoint at one:  npx webmcp-codegen generate --spec path/to/openapi.json"
-    );
-  }
-  if (specs.length > 1) {
-    const list = specs.map((spec) => `  - ${spec}`).join("\n");
-    throw new Error(
-      `Found ${specs.length} API specs:
-${list}
-
-Pick one:  npx webmcp-codegen generate --spec ${specs[0]}`
-    );
-  }
-  console.log(`Detected ${specs[0]} (override with --spec)
-`);
-  return specs[0];
-}
 async function runOnce(cwd, flags) {
-  const { config, label } = await resolveConfig(cwd, flags);
-  const result = await runGenerate(config, {
+  const setup = await resolveSetup(cwd, flags);
+  const data = await loadDataFile(cwd);
+  const result = await runGenerate(setup.config, {
     cwd,
     dryRun: flags.dryRun,
     skipAudit: flags.skipAudit,
-    force: flags.force
+    force: flags.force,
+    overrides: data.overrides
   });
-  printReport(result, flags, label, cwd);
+  let wiring = null;
+  if (!result.blocked && setup.app) {
+    const outDir = findOutDir(setup.config);
+    if (outDir) {
+      wiring = await planWiring(cwd, setup.app, outDir);
+      if (wiring && wiring.edits.length > 0 && !flags.dryRun && result.wrote) {
+        await applyWiring(wiring);
+      }
+    }
+  }
+  if (!setup.fromConfigFile && !flags.dryRun && result.wrote) {
+    await saveDataFile(cwd, setup.remember);
+  }
+  printReport(result, flags, setup, wiring, cwd);
   return result;
 }
-function printReport(result, flags, configName, cwd) {
-  const { tools, findings, files, blocked } = result;
+function findOutDir(config) {
+  return config.generate[0]?.outDir;
+}
+function printReport(result, flags, setup, wiring, cwd) {
+  const { tools, skipped, findings, files, notes, blocked } = result;
   console.log(`
-webmcp-codegen (${configName}) \u2014 ${tools.length} tool(s)
-`);
-  for (const tool of tools) {
-    console.log(`  ${tool.name}  [${tool.riskTier}]  \u2190 ${tool.source.ref}`);
+webmcp-codegen (${setup.label}): ${tools.length} tool(s)`);
+  for (const note of notes) {
+    console.log(`
+  note: ${note}`);
+  }
+  if (skipped.length > 0) {
+    console.log(`
+  ${skipped.length} endpoint(s) skipped:`);
+    for (const entry of skipped) {
+      console.log(`    ${entry.ref}: ${entry.reason}`);
+    }
+  }
+  console.log("");
+  const listed = tools.slice(0, MAX_LISTED_TOOLS);
+  for (const tool of listed) {
+    const state = tool.enabledByDefault ? "" : "  starts disabled";
+    console.log(`  ${tool.name}  [${tool.sideEffect}]${state}  \u2190 ${tool.source.ref}`);
+  }
+  if (tools.length > listed.length) {
+    console.log(`  \u2026and ${tools.length - listed.length} more`);
   }
   if (findings.length > 0) {
     console.log("");
@@ -237,23 +335,86 @@ webmcp-codegen (${configName}) \u2014 ${tools.length} tool(s)
       console.log(`  ${shown}: ${relative2(cwd, file.path)}`);
     }
   }
+  if (wiring) {
+    if (wiring.alreadyWired) {
+      console.log("\n  registration: already wired into your app");
+    } else if (wiring.edits.length > 0) {
+      console.log(flags.dryRun ? "\n  registration (would do):" : "\n  registration:");
+      for (const edit of wiring.edits) {
+        console.log(`    ${edit.summary}`);
+      }
+      if (!flags.dryRun) {
+        console.log("    undo: delete the added lines (nothing else was touched)");
+      }
+    }
+  } else if (!blocked && setup.app) {
+    console.log("\n  registration: could not find your app's entry file, so add this by hand:");
+    console.log('    import { registerAllTools } from "<path-to>/src/webmcp";');
+    console.log("    void registerAllTools();");
+  }
   if (blocked) {
     console.log(
       "\nGeneration blocked by audit errors. Fix them, or re-run with --force to write anyway."
     );
-  } else if (flags.dryRun) {
-    console.log("\nDry run \u2014 nothing written. Re-run without --dry-run to write these files.");
+    return;
+  }
+  if (flags.dryRun) {
+    console.log("\nDry run: nothing written. Re-run without --dry-run to write these files.");
+    return;
+  }
+  printNextSteps(result);
+}
+function printNextSteps(result) {
+  const enabled = result.tools.filter((tool) => tool.enabledByDefault);
+  const disabled = result.tools.filter((tool) => !tool.enabledByDefault);
+  const parts = [];
+  if (enabled.length > 0) parts.push(`${enabled.length} read tool(s) work out of the box`);
+  if (disabled.length > 0) {
+    parts.push(`${disabled.length} tool(s) start disabled (open the file and uncomment to enable)`);
+  }
+  console.log(`
+Done. ${parts.join("; ")}.`);
+  const suggestion = pickSuggestedTool(result.tools);
+  console.log("\nTry it:");
+  console.log("  1. Start your app and open it in Chrome.");
+  console.log("  2. Turn on chrome://flags/#enable-webmcp-testing and reload the page.");
+  if (suggestion) {
+    console.log(`  3. Ask the agent: "${suggestion}"`);
   } else {
-    console.log("\nDone. Fill in each execute() below the marker, then registerAllTools().");
+    console.log("  3. Ask the agent to use one of your tools.");
   }
 }
+function pickSuggestedTool(tools) {
+  const reads = tools.filter((tool2) => tool2.enabledByDefault && tool2.endpointRole === "endpoint");
+  if (reads.length === 0) return void 0;
+  const tool = reads.find((candidate) => /^(list|get|search|find|fetch|recent)-/.test(candidate.name)) ?? reads[0];
+  if (!tool) return void 0;
+  const description = tool.description.trim().replace(/\.$/, "");
+  const looksTemplated = /^(GET|POST|PUT|PATCH|DELETE)\s/.test(description);
+  const phrase = looksTemplated ? tool.name.replace(/-/g, " ") : description.charAt(0).toLowerCase() + description.slice(1);
+  return phrase;
+}
+async function dev(port) {
+  const { startDevServer } = await import("./server-OR4IMRQ5.js");
+  const server = await startDevServer({ cwd: process.cwd(), port });
+  console.log(`
+webmcp-codegen dashboard: http://localhost:${port}`);
+  console.log("List, describe, enable, and try your tools. Ctrl+C to stop.\n");
+  await new Promise((resolveExit) => {
+    process.on("SIGINT", () => {
+      server.close();
+      resolveExit();
+    });
+  });
+  return 0;
+}
 async function watchLoop(cwd, flags) {
   await runOnce(cwd, { ...flags, dryRun: false });
   console.log("\nWatching for changes\u2026 (Ctrl+C to stop)");
   let timer;
   watch(cwd, { recursive: true }, (_event, filename) => {
     if (!filename) return;
-    if (/node_modules|\.git|\/dist|\/src\/webmcp/.test(filename)) return;
+    if (/node_modules|\.git|\/dist|\/src\/webmcp|\.webmcp-codegen\.json/.test(filename)) return;
     if (!/\.(ya?ml|json|ts|tsx|mts|mjs)$/.test(filename)) return;
     clearTimeout(timer);
     timer = setTimeout(() => {