@napster-corp/webmcp-toolkit 1.0.0

package/tools/generate-capabilities.mjs

@@ -0,0 +1,266 @@
+// generate-capabilities.mjs — orchestrator for keeping a host app's WebMCP
+// tools file (`src/webmcp/tools.ts`) in sync with its code via an autonomous
+// coding agent.
+//
+// Engine-agnostic: this file builds the prompt (from this package's skills),
+// detects the tools file, loads env, then hands off to a pluggable RUNNER that
+// actually drives an agent. Pick the engine with:
+//
+//   WEBMCP_TOOLKIT_ENGINE=anthropic   (default — Claude Agent SDK, needs ANTHROPIC_API_KEY)
+//   WEBMCP_TOOLKIT_ENGINE=copilot     (GitHub Copilot CLI, needs a Copilot subscription)
+//
+// A runner is `tools/runners/<engine>.mjs` exporting:
+//   export async function runAgent({ prompt, cwd, capabilitiesPath }): Promise<string>
+//
+// Whatever the engine, the contract is the same: analyze the app, edit ONLY the
+// tools file, leave the change uncommitted for review.
+
+import { readFile } from "node:fs/promises";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, "..");
+
+const DEFAULT_ENGINE = "anthropic";
+
+// Pluggable engines. Static map (not arbitrary path import) so an unknown
+// engine fails with a clear message instead of a module-not-found.
+const ENGINES = {
+  anthropic: () => import("./runners/anthropic.mjs"),
+  copilot: () => import("./runners/copilot.mjs"),
+};
+
+// The prompt is itself a skill (`sync-webmcp-tools`) that lives in the skills
+// folder like every other one — a single artifact whether this automation runs
+// it or it is followed directly in chat. The task skill defers methodology to
+// the two skills below, which we inline (not via any engine's skill
+// auto-discovery) so the run is self-contained on any engine.
+const TASK_SKILL = "skills/sync-webmcp-tools/SKILL.md";
+const METHODOLOGY_SKILLS = [
+  "skills/plan-capabilities-and-state/SKILL.md",
+  "skills/setup-edge-mcp/SKILL.md",
+];
+
+// Dirs we never descend into while discovering where WebMCP lives.
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", "dist", "build", "out", ".next", ".turbo",
+  ".cache", "coverage", ".vercel", ".svelte-kit", ".output",
+]);
+// Default location used ONLY for a first-time setup where nothing exists yet.
+const DEFAULT_TOOLS_FILE = "src/webmcp/tools.ts";
+
+// Credentials a runner might need. Plain Node scripts don't read `.env.local`
+// the way Next.js does, so the hook/manual run wouldn't otherwise see a key kept
+// there. Load these from the app's `.env.local` / `.env` if not already in the
+// environment (an exported value always wins — e.g. a CI secret).
+const ENV_KEYS = ["ANTHROPIC_API_KEY", "GITHUB_TOKEN", "GH_TOKEN", "COPILOT_TOKEN"];
+
+function loadEnvVars(targetDir) {
+  for (const name of [".env.local", ".env"]) {
+    const p = join(targetDir, name);
+    if (!existsSync(p)) continue;
+    const text = readFileSync(p, "utf8");
+    for (const key of ENV_KEYS) {
+      if (process.env[key]) continue;
+      const m = text.match(new RegExp(`^\\s*${key}\\s*=\\s*(.+?)\\s*$`, "m"));
+      if (!m) continue;
+      let v = m[1].trim();
+      if (/^(".*"|'.*')$/.test(v)) v = v.slice(1, -1);
+      process.env[key] = v;
+    }
+  }
+}
+
+// Walk the project (skipping build/dependency dirs) and discover where WebMCP
+// actually lives — no hardcoded path convention. Collects every directory named
+// `webmcp` and every source file, so we can locate the module by its folder or,
+// failing that, by which file imports the toolkit.
+function scanProject(targetDir, depth = 0, acc = { webmcpDirs: [], sources: [] }) {
+  if (depth > 12) return acc;
+  let entries;
+  try {
+    entries = readdirSync(targetDir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const e of entries) {
+    if (e.name.startsWith(".") && e.isDirectory()) continue;
+    const full = join(targetDir, e.name);
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      if (e.name === "webmcp") acc.webmcpDirs.push(full);
+      scanProject(full, depth + 1, acc);
+    } else if (e.isFile() && /\.(ts|tsx|js|jsx|mjs|cjs)$/.test(e.name)) {
+      acc.sources.push(full);
+    }
+  }
+  return acc;
+}
+
+// Resolve the tools file WITHOUT specifying a path: discover it from the
+// project. Order: explicit override → the `webmcp` module folder (wherever it
+// sits, even if tools.ts was deleted) → the file that actually wires up the
+// toolkit → a first-time default.
+function detectToolsFile(targetDir, override) {
+  if (override) return override;
+  const root = resolve(targetDir);
+
+  const { webmcpDirs, sources } = scanProject(root);
+
+  // 1. A directory named `webmcp` anywhere in the project. Prefer the
+  //    shallowest. Targets <dir>/tools.ts — works even if the file was
+  //    deleted (the folder still has index.ts / resources.ts).
+  if (webmcpDirs.length) {
+    webmcpDirs.sort((a, b) => a.split(sep).length - b.split(sep).length);
+    return relative(root, join(webmcpDirs[0], "tools.ts"));
+  }
+
+  // 2. No conventional folder — find where the toolkit is actually registered
+  //    (imports `@napster-corp/webmcp-toolkit` AND calls registerTool /
+  //    registerStatefulTool) and use that file's directory.
+  for (const file of sources) {
+    let text;
+    try {
+      text = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    if (
+      text.includes("@napster-corp/webmcp-toolkit") &&
+      /register(Stateful)?Tool\s*\(/.test(text)
+    ) {
+      return relative(root, join(dirname(file), "tools.ts"));
+    }
+  }
+
+  // 3. Nothing set up yet — first-time location (the agent creates it here).
+  return DEFAULT_TOOLS_FILE;
+}
+
+// Strip a leading YAML frontmatter block so the task skill's instruction body
+// leads the prompt (the `---name---` header is noise to the runner agent).
+function stripFrontmatter(md) {
+  return md.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, "").trimStart();
+}
+
+// Assemble the runner prompt: the `sync-webmcp-tools` task skill, followed by the
+// methodology skills inlined so the run is self-contained on any engine (the
+// runner agent has no skill auto-discovery). The prompt is UNIVERSAL — it lives
+// entirely in the skills folder and names no app-specific path; where the tools
+// file lives is the methodology skills' job. (The CLI still detects a path
+// separately, but only to diff the result for its summary — see detectToolsFile
+// / summarizeChange.)
+async function buildPrompt() {
+  const taskMd = await readFile(join(PACKAGE_ROOT, TASK_SKILL), "utf8");
+  const task = stripFrontmatter(taskMd);
+  const methodology = (
+    await Promise.all(
+      METHODOLOGY_SKILLS.map(async (rel) => {
+        const text = await readFile(join(PACKAGE_ROOT, rel), "utf8").catch(() => null);
+        return text ? `<skill path="${rel}">\n${text}\n</skill>` : null;
+      }),
+    )
+  )
+    .filter(Boolean)
+    .join("\n\n");
+  return `${task}\n\n## Methodology skills (inlined — your source of truth)\n\n${methodology}`;
+}
+
+async function loadRunner(engine) {
+  const load = ENGINES[engine];
+  if (!load) {
+    throw new Error(
+      `Unknown engine "${engine}". Use one of: ${Object.keys(ENGINES).join(", ")} ` +
+        "(set WEBMCP_TOOLKIT_ENGINE or pass --engine).",
+    );
+  }
+  return load();
+}
+
+// The tool names registered in a file (`name: '…'` inside registerTool /
+// registerStatefulTool).
+function toolNames(src) {
+  if (!src) return [];
+  return [...src.matchAll(/name:\s*['"]([^'"]+)['"]/g)].map((m) => m[1]);
+}
+
+// Deterministic, engine-agnostic summary of what the run actually did to the
+// file — printed regardless of what the agent narrated (so Anthropic and Copilot
+// give the same feedback, and a no-op is reported as such).
+function summarizeChange(toolsPath, before, after) {
+  const rule = "──────────────────────────────────────────────";
+  const out = [`\n[webmcp-toolkit] result ${rule}`];
+
+  if (before === after) {
+    out.push(
+      after === null
+        ? `[webmcp-toolkit] ${toolsPath}: not written (the engine produced no file).`
+        : `[webmcp-toolkit] ${toolsPath}: no changes — already in sync.`,
+    );
+    return out.join("\n");
+  }
+
+  const beforeNames = new Set(toolNames(before));
+  const afterNames = toolNames(after);
+  const afterSet = new Set(afterNames);
+  const added = afterNames.filter((n) => !beforeNames.has(n));
+  const removed = [...beforeNames].filter((n) => !afterSet.has(n));
+
+  if (before === null) {
+    out.push(
+      `[webmcp-toolkit] ${toolsPath}: created — ${afterNames.length} tools` +
+        (afterNames.length ? ` (${afterNames.join(", ")})` : ""),
+    );
+    return out.join("\n");
+  }
+  if (after === null) {
+    out.push(`[webmcp-toolkit] ${toolsPath}: removed (no tools file written).`);
+    return out.join("\n");
+  }
+
+  const beforeLines = before.split("\n").length;
+  const afterLines = after.split("\n").length;
+  out.push(`[webmcp-toolkit] ${toolsPath}: ${beforeLines} → ${afterLines} lines`);
+  if (added.length) out.push(`[webmcp-toolkit]   + added   (${added.length}): ${added.join(", ")}`);
+  if (removed.length) out.push(`[webmcp-toolkit]   - removed (${removed.length}): ${removed.join(", ")}`);
+  if (!added.length && !removed.length) {
+    out.push(`[webmcp-toolkit]   ~ updated in place (same names; descriptions/args/execute changed)`);
+  }
+  out.push(`[webmcp-toolkit]   total: ${afterNames.length} tools`);
+  return out.join("\n");
+}
+
+/**
+ * Run the generation. Returns the runner's final summary text.
+ * @param {{ targetDir?: string, file?: string, engine?: string }} [opts]
+ */
+export async function generateCapabilities(opts = {}) {
+  const targetDir = resolve(opts.targetDir ?? process.cwd());
+  loadEnvVars(targetDir);
+  const toolsPath = detectToolsFile(targetDir, opts.file);
+  const engine = (opts.engine ?? process.env.WEBMCP_TOOLKIT_ENGINE ?? DEFAULT_ENGINE).toLowerCase();
+
+  process.stderr.write(
+    `[webmcp-toolkit] engine: ${engine}\n` +
+      `[webmcp-toolkit] target: ${targetDir}\n` +
+      `[webmcp-toolkit] file:   ${toolsPath}\n`,
+  );
+
+  // Universal prompt assembled from the task skill + methodology skills (see
+  // buildPrompt). `toolsPath` is used only below to diff the result for the
+  // deterministic summary, never injected into the prompt.
+  const prompt = await buildPrompt();
+
+  const absPath = join(targetDir, toolsPath);
+  const before = existsSync(absPath) ? readFileSync(absPath, "utf8") : null;
+
+  const runner = await loadRunner(engine);
+  const result = await runner.runAgent({ prompt, cwd: targetDir, capabilitiesPath: toolsPath });
+
+  // Report what actually changed on disk — same feedback for every engine.
+  const after = existsSync(absPath) ? readFileSync(absPath, "utf8") : null;
+  process.stdout.write(summarizeChange(toolsPath, before, after) + "\n");
+  return result;
+}

package/tools/install-hook.mjs

@@ -0,0 +1,81 @@
+// install-hook.mjs — installs the WebMCP Toolkit post-commit hook into the host repo.
+//
+// The hook is opt-in per commit: it only regenerates capabilities when the
+// commit message contains the `[webmcp-toolkit]` marker (see hooks/post-commit). This
+// keeps every other commit fast and free.
+//
+// Idempotent: re-running replaces the managed block, and it composes with an
+// existing post-commit hook by appending a clearly-delimited section rather
+// than clobbering it.
+
+import { execFileSync } from "node:child_process";
+import { readFile, writeFile, chmod, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, "..");
+
+const BEGIN = "# >>> webmcp-toolkit post-commit >>>";
+const END = "# <<< webmcp-toolkit post-commit <<<";
+
+function gitHooksDir(cwd) {
+  // Respect core.hooksPath if the repo overrides it; else .git/hooks.
+  try {
+    const custom = execFileSync("git", ["config", "--get", "core.hooksPath"], {
+      cwd,
+      encoding: "utf8",
+    }).trim();
+    if (custom) return resolve(cwd, custom);
+  } catch {
+    /* not set */
+  }
+  const gitDir = execFileSync("git", ["rev-parse", "--git-path", "hooks"], {
+    cwd,
+    encoding: "utf8",
+  }).trim();
+  return resolve(cwd, gitDir);
+}
+
+export async function installHook(opts = {}) {
+  const cwd = resolve(opts.targetDir ?? process.cwd());
+
+  // Confirm we're in a git repo.
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "ignore" });
+  } catch {
+    throw new Error(`Not a git repository: ${cwd}`);
+  }
+
+  const hooksDir = gitHooksDir(cwd);
+  await mkdir(hooksDir, { recursive: true });
+  const hookPath = join(hooksDir, "post-commit");
+
+  const managed = await readFile(join(PACKAGE_ROOT, "hooks/post-commit"), "utf8");
+  const block = `${BEGIN}\n${managed.trim()}\n${END}\n`;
+
+  let existing = existsSync(hookPath) ? await readFile(hookPath, "utf8") : "";
+
+  if (existing.includes(BEGIN)) {
+    // Replace the managed block in place.
+    existing = existing.replace(
+      new RegExp(`${escapeRe(BEGIN)}[\\s\\S]*?${escapeRe(END)}\\n?`),
+      block,
+    );
+  } else if (existing.trim()) {
+    // Append to an existing hook, keeping its shebang at the top.
+    existing = `${existing.replace(/\n*$/, "")}\n\n${block}`;
+  } else {
+    existing = `#!/bin/sh\n\n${block}`;
+  }
+
+  await writeFile(hookPath, existing, "utf8");
+  await chmod(hookPath, 0o755);
+
+  return hookPath;
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/tools/runners/anthropic.mjs

@@ -0,0 +1,75 @@
+// runners/anthropic.mjs — drives the Claude Agent SDK (@anthropic-ai/claude-agent-sdk).
+//
+// Auth: ANTHROPIC_API_KEY (local dev, or a CI secret).
+// Dependency: @anthropic-ai/claude-agent-sdk (optional peer of @napster-corp/webmcp-toolkit).
+//
+// ⚠️ The query() options below are from the @anthropic-ai/claude-agent-sdk
+// README — verify field names against your installed version if you upgrade.
+
+// Always use the latest, most capable model for code analysis.
+const MODEL = "claude-opus-4-8";
+
+export async function runAgent({ prompt, cwd }) {
+  if (!process.env.ANTHROPIC_API_KEY) {
+    throw new Error(
+      "ANTHROPIC_API_KEY is not set. Put it in the app's .env.local, export it, " +
+        "or provide it as a CI secret.",
+    );
+  }
+
+  let query;
+  try {
+    ({ query } = await import("@anthropic-ai/claude-agent-sdk"));
+  } catch {
+    throw new Error(
+      "Missing dependency `@anthropic-ai/claude-agent-sdk`.\n" +
+        "Install it where you run generation:\n" +
+        "  npm install --save-dev @anthropic-ai/claude-agent-sdk",
+    );
+  }
+
+  let finalText = "";
+  for await (const message of query({
+    prompt,
+    options: {
+      model: MODEL,
+      // Whitelist the read/search/edit tools the task needs…
+      allowedTools: ["Read", "Grep", "Glob", "Edit", "Write"],
+      // …and HARD-block shell/network/subagents. (Required: bypassPermissions
+      // auto-allows anything not explicitly disallowed, so allowedTools alone
+      // is not a hard boundary — disallowedTools is.)
+      disallowedTools: ["Bash", "WebSearch", "WebFetch", "Task", "KillShell"],
+      // Autonomous: don't prompt for permission (no TTY in a hook/CI).
+      permissionMode: "bypassPermissions",
+      // Analyze the host app; honor its CLAUDE.md / .claude conventions.
+      cwd,
+      settingSources: ["project"],
+      // Bound the run so a hook can't hang indefinitely.
+      maxTurns: 40,
+    },
+  })) {
+    if (message.type === "assistant") {
+      for (const block of message.message?.content ?? []) {
+        if (block.type === "text" && block.text) {
+          process.stdout.write(block.text);
+          finalText = block.text;
+        } else if (block.type === "tool_use") {
+          process.stderr.write(
+            `\n[webmcp-toolkit] ${block.name} ${describeTool(block.input)}\n`,
+          );
+        }
+      }
+    } else if (message.type === "result") {
+      if (message.subtype && message.subtype !== "success") {
+        throw new Error(`Agent run ended: ${message.subtype}`);
+      }
+    }
+  }
+  process.stdout.write("\n");
+  return finalText;
+}
+
+function describeTool(input) {
+  if (!input || typeof input !== "object") return "";
+  return input.file_path ?? input.path ?? input.pattern ?? "";
+}

package/tools/runners/copilot.mjs

@@ -0,0 +1,63 @@
+// runners/copilot.mjs — drives the GitHub Copilot CLI (agentic mode) instead of
+// the Claude Agent SDK. Same contract: run the prompt in `cwd`, edit only the
+// capabilities file, leave it uncommitted.
+//
+// Auth: your GitHub Copilot subscription (`copilot` to sign in). NO Anthropic key.
+// Install: npm i -g @github/copilot  (the agentic CLI, not the `gh copilot` ext).
+//
+// Invocation (verified against `copilot --help`):
+//   copilot <flags> -p "<prompt>"
+// `--allow-all-tools` is REQUIRED for non-interactive runs, so it's the default.
+// The prompt is passed as the value of the prompt flag and kept ADJACENT to it,
+// so other flags are never swallowed as the prompt.
+//
+// Env overrides:
+//   WEBMCP_TOOLKIT_COPILOT_BIN          path to the CLI            (default: "copilot")
+//   WEBMCP_TOOLKIT_COPILOT_ARGS         flags placed BEFORE -p     (default: "--allow-all-tools")
+//                                 e.g. to scope tools:
+//                                 "--allow-all-tools --available-tools str_replace,view"
+//   WEBMCP_TOOLKIT_COPILOT_PROMPT_FLAG  the prompt flag            (default: "-p")
+
+import { spawn } from "node:child_process";
+
+export async function runAgent({ prompt, cwd }) {
+  const bin = process.env.WEBMCP_TOOLKIT_COPILOT_BIN || "copilot";
+  const promptFlag = process.env.WEBMCP_TOOLKIT_COPILOT_PROMPT_FLAG || "-p";
+  const extra = (process.env.WEBMCP_TOOLKIT_COPILOT_ARGS ?? "--allow-all-tools")
+    .split(" ")
+    .filter(Boolean);
+
+  // Prompt is ONE argv entry (no shell), as the value immediately after the
+  // prompt flag: `copilot <extra…> -p "<prompt>"`.
+  const args = [...extra, promptFlag, prompt];
+
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(bin, args, {
+      cwd,
+      stdio: ["ignore", "inherit", "inherit"], // stream Copilot's output through
+      env: process.env,
+    });
+
+    child.on("error", (err) => {
+      if (err.code === "ENOENT") {
+        reject(
+          new Error(
+            `GitHub Copilot CLI ("${bin}") not found on PATH.\n` +
+              "Install it and sign in (a Copilot subscription is required):\n" +
+              "  npm i -g @github/copilot   # then run `copilot` once to sign in\n" +
+              "Or point WEBMCP_TOOLKIT_COPILOT_BIN at the binary.",
+          ),
+        );
+      } else {
+        reject(err);
+      }
+    });
+
+    // Note: the Copilot CLI can exit 0 even on policy/auth errors — its output
+    // (streamed above) is the source of truth. We surface non-zero codes only.
+    child.on("close", (code) => {
+      if (code === 0) resolvePromise("");
+      else reject(new Error(`Copilot CLI exited with code ${code}.`));
+    });
+  });
+}