api-emulator 0.6.0 → 0.7.0

package/dist/index.js

@@ -6,6 +6,11 @@ import { Command } from "commander";
 import { isAbsolute, resolve } from "path";
 
 // src/plugin-manifest.ts
+function formatPluginFidelity(fidelity) {
+  if (!fidelity) return "unrated";
+  if (typeof fidelity === "string") return fidelity;
+  return fidelity.level;
+}
 function readPluginManifest(mod) {
   return mod.manifest ?? {};
 }
@@ -25,20 +30,21 @@ function validatePluginManifest(manifest, pluginName) {
 async function loadExternalPluginModule(specifier) {
   const modulePath = specifier.startsWith(".") || isAbsolute(specifier) ? resolve(specifier) : specifier;
   const mod = await import(modulePath);
-  const plugin = mod.plugin ?? mod.default;
-  if (!plugin || typeof plugin.register !== "function" || typeof plugin.name !== "string") {
+  const plugin2 = mod.plugin ?? mod.default;
+  if (!plugin2 || typeof plugin2.register !== "function" || typeof plugin2.name !== "string") {
     throw new Error(`Plugin "${specifier}" must export a ServicePlugin (as "plugin" or default export)`);
   }
-  const name = plugin.name;
+  const name = plugin2.name;
   const manifest = validatePluginManifest(readPluginManifest(mod), name);
   return {
     name,
     label: manifest.label,
     endpoints: manifest.endpoints,
+    fidelity: formatPluginFidelity(manifest.fidelity),
     manifest,
     async load() {
       return {
-        plugin,
+        plugin: plugin2,
         seedFromConfig: mod.seedFromConfig
       };
     },
@@ -118,6 +124,7 @@ import pc from "picocolors";
 
 // src/portless.ts
 import { execSync, spawnSync } from "child_process";
+import { Socket } from "net";
 import { createInterface } from "readline";
 function isInteractive() {
   return Boolean(process.stdin.isTTY) && !process.env.CI;
@@ -127,32 +134,60 @@ function hasPortless() {
   return result.status === 0;
 }
 function promptYesNo(question) {
-  return new Promise((resolve7) => {
+  return new Promise((resolve9) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     rl.question(question, (answer) => {
       rl.close();
       const normalized = answer.trim().toLowerCase();
-      resolve7(normalized === "" || normalized === "y" || normalized === "yes");
+      resolve9(normalized === "" || normalized === "y" || normalized === "yes");
     });
   });
 }
-function isProxyRunning() {
-  const result = spawnSync("portless", ["list"], { stdio: "ignore" });
-  return result.status === 0;
+function portlessUrl(name) {
+  const result = spawnSync("portless", ["get", name], { encoding: "utf-8" });
+  if (result.status !== 0) return null;
+  const url = result.stdout.trim();
+  return url.length > 0 ? url : null;
 }
+async function canConnect(port) {
+  return new Promise((resolve9) => {
+    const socket = new Socket();
+    const done = (ok) => {
+      socket.destroy();
+      resolve9(ok);
+    };
+    socket.setTimeout(500);
+    socket.once("connect", () => done(true));
+    socket.once("error", () => done(false));
+    socket.once("timeout", () => done(false));
+    socket.connect(port, "127.0.0.1");
+  });
+}
+async function isProxyRunning() {
+  const url = portlessUrl("api-emulator-probe");
+  if (!url) return false;
+  try {
+    const parsed = new URL(url);
+    const port = parsed.port ? Number(parsed.port) : parsed.protocol === "http:" ? 80 : 443;
+    return await canConnect(port);
+  } catch {
+    return false;
+  }
+}
+var portlessInstallCommand = "bun add --global portless";
 async function ensurePortless() {
   if (!hasPortless()) {
     if (!isInteractive()) {
-      console.error("portless is required but not installed. Run: npm i -g portless");
+      console.error(`portless is required but not installed. Run: ${portlessInstallCommand}`);
       process.exit(1);
     }
-    const yes = await promptYesNo("portless is not installed. Install it now? (npm i -g portless) [Y/n] ");
+    const yes = await promptYesNo(`portless is not installed. Install it now? (${portlessInstallCommand}) [Y/n] `);
     if (!yes) {
       console.error("Cannot continue without portless.");
       process.exit(1);
     }
     try {
-      execSync("npm i -g portless", { stdio: "inherit" });
+      execSync(portlessInstallCommand, { stdio: "inherit" });
     } catch {
       console.error("Failed to install portless.");
       process.exit(1);
@@ -162,7 +197,7 @@ async function ensurePortless() {
       process.exit(1);
     }
   }
-  if (!isProxyRunning()) {
+  if (!await isProxyRunning()) {
     console.error("portless proxy is not running. Start it with: portless proxy start");
     process.exit(1);
   }
@@ -191,7 +226,7 @@ function removeAliases(aliases) {
   }
 }
 function portlessBaseUrl(serviceName) {
-  return `https://${serviceName}.api-emulator.localhost`;
+  return portlessUrl(`${serviceName}.api-emulator`) ?? `https://${serviceName}.api-emulator.localhost`;
 }
 
 // src/base-url.ts
@@ -206,9 +241,9 @@ function resolveBaseUrl(opts) {
   if (envBaseUrl) {
     return envBaseUrl.replace(/\{service\}/g, opts.service);
   }
-  const portlessUrl = process.env.PORTLESS_URL;
-  if (portlessUrl) {
-    return portlessUrl.replace(/\{service\}/g, opts.service);
+  const portlessUrl2 = process.env.PORTLESS_URL;
+  if (portlessUrl2) {
+    return portlessUrl2.replace(/\{service\}/g, opts.service);
   }
   return `http://localhost:${opts.port}`;
 }
@@ -279,18 +314,36 @@ function createServiceRuntime(options) {
       seed();
     },
     close() {
-      return new Promise((resolve7, reject) => {
+      return new Promise((resolve9, reject) => {
         httpServer.close((err) => {
           if (err) reject(err);
-          else resolve7();
+          else resolve9();
         });
       });
     }
   };
 }
 
+// src/cli-notifier.ts
+import { spawn } from "child_process";
+import { platform } from "os";
+function escapeAppleScript(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function appleScriptNotification({ title, message }) {
+  return `display notification "${escapeAppleScript(message)}" with title "${escapeAppleScript(title)}"`;
+}
+function notifyIfRequested(options) {
+  if (!options.enabled || platform() !== "darwin") return;
+  const child = spawn("/usr/bin/osascript", ["-e", appleScriptNotification(options)], {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+}
+
 // src/commands/start.ts
-var pkg = { version: "0.6.0" };
+var pkg = { version: "0.7.0" };
 function loadSeedConfig(seedPath) {
   if (seedPath) {
     const fullPath = resolve3(seedPath);
@@ -378,17 +431,17 @@ async function startCommand(options) {
     if (options.portless) {
       portlessAliases.push({ name: `${svc}.api-emulator`, port });
     }
-    const seedBaseUrl = typeof svcSeedConfig?.baseUrl === "string" && svcSeedConfig.baseUrl.length > 0 ? svcSeedConfig.baseUrl : void 0;
-    const effectiveBaseUrl = options.portless ? portlessBaseUrl(svc) : options.baseUrl;
-    const baseUrl = resolveBaseUrl({ service: svc, port, baseUrl: effectiveBaseUrl, seedBaseUrl });
-    prepared.push({ svc, pluginModule, loadedPlugin, svcSeedConfig, port, baseUrl });
+    prepared.push({ svc, pluginModule, loadedPlugin, svcSeedConfig, port });
   }
   if (portlessAliases.length > 0) {
     registerAliases(portlessAliases);
   }
   const serviceUrls = [];
   const runningServices = [];
-  for (const { svc, pluginModule, loadedPlugin, svcSeedConfig, port, baseUrl } of prepared) {
+  for (const { svc, pluginModule, loadedPlugin, svcSeedConfig, port } of prepared) {
+    const seedBaseUrl = typeof svcSeedConfig?.baseUrl === "string" && svcSeedConfig.baseUrl.length > 0 ? svcSeedConfig.baseUrl : void 0;
+    const effectiveBaseUrl = options.portless ? portlessBaseUrl(svc) : options.baseUrl;
+    const baseUrl = resolveBaseUrl({ service: svc, port, baseUrl: effectiveBaseUrl, seedBaseUrl });
     serviceUrls.push({ name: svc, url: baseUrl });
     const running = createServiceRuntime({
       service: svc,
@@ -402,6 +455,11 @@ async function startCommand(options) {
     runningServices.push(running);
   }
   printBanner(serviceUrls, tokens, configSource);
+  notifyIfRequested({
+    enabled: options.notify,
+    title: "api-emulator",
+    message: `Server started with ${serviceUrls.length} service${serviceUrls.length === 1 ? "" : "s"}`
+  });
   const shutdown = () => {
     console.log(`
 ${pc.dim("Shutting down...")}`);
@@ -446,13 +504,143 @@ function printBanner(services, tokens, configSource) {
 }
 
 // src/commands/init.ts
-import { writeFileSync as writeFileSync2, existsSync as existsSync3 } from "fs";
-import { resolve as resolve4 } from "path";
+import { writeFileSync as writeFileSync3, existsSync as existsSync4 } from "fs";
+import { homedir } from "os";
+import { resolve as resolve5 } from "path";
 import { stringify as yamlStringify } from "yaml";
+
+// src/generated-manifest.ts
+import { createHash } from "crypto";
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { dirname, resolve as resolve4 } from "path";
+var GENERATED_MANIFEST_FILE = ".api-emulator/manifest.json";
+function checksum(content) {
+  return createHash("sha256").update(content).digest("hex");
+}
+function readGeneratedManifest(cwd = process.cwd()) {
+  const path = resolve4(cwd, GENERATED_MANIFEST_FILE);
+  if (!existsSync3(path)) return { version: 1, files: {} };
+  const parsed = JSON.parse(readFileSync3(path, "utf-8"));
+  if (parsed.version !== 1 || typeof parsed.files !== "object" || parsed.files === null) {
+    throw new Error(`Invalid ${GENERATED_MANIFEST_FILE}`);
+  }
+  return parsed;
+}
+function writeGeneratedManifest(manifest, cwd = process.cwd()) {
+  const path = resolve4(cwd, GENERATED_MANIFEST_FILE);
+  mkdirSync(dirname(path), { recursive: true });
+  const files = Object.fromEntries(Object.entries(manifest.files).sort(([a], [b]) => a.localeCompare(b)));
+  writeFileSync2(path, `${JSON.stringify({ version: 1, files }, null, 2)}
+`, "utf-8");
+}
+function writeGeneratedFile(relativePath, content, options) {
+  const cwd = options.cwd ?? process.cwd();
+  const path = resolve4(cwd, relativePath);
+  const manifest = readGeneratedManifest(cwd);
+  const existing = manifest.files[relativePath];
+  if (existsSync3(path)) {
+    const current = readFileSync3(path, "utf-8");
+    if (current === content) {
+      manifest.files[relativePath] = { checksum: checksum(content), source: options.source };
+      writeGeneratedManifest(manifest, cwd);
+      return;
+    }
+    if (!options.yes && (!existing || existing.checksum !== checksum(current))) {
+      throw new Error(`Refusing to overwrite user-edited file: ${relativePath}. Re-run with --yes to overwrite.`);
+    }
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync2(path, content, "utf-8");
+  manifest.files[relativePath] = { checksum: checksum(content), source: options.source };
+  writeGeneratedManifest(manifest, cwd);
+}
+
+// src/commands/init.ts
+var AGENT_SKILL_DIRS = {
+  agents: ".agents/skills",
+  claude: ".claude/skills",
+  codex: ".codex/skills",
+  cursor: ".cursor/skills",
+  factory: ".agents/skills",
+  global: `${homedir()}/.agents/skills`,
+  "user-agents": `${homedir()}/.agents/skills`,
+  windsurf: ".windsurf/skills"
+};
+function parseAgentTargets(input, nonInteractive) {
+  const values = input?.split(",").map((value) => value.trim()).filter(Boolean) ?? [];
+  if (values.length > 0) return values;
+  return nonInteractive ? ["agents"] : ["agents"];
+}
+function pluginAuthoringSkill() {
+  return `---
+name: api-emulator-plugin-authoring
+description: Create, validate, and install api-emulator provider plugins.
+---
+
+# API Emulator Plugin Authoring
+
+Use this skill when adding or validating a provider plugin for api-emulator.
+
+## Workflow
+
+1. Create a provider clone scaffold with \`npx -p api-emulator api clone create <provider>\`.
+2. Add provider-shaped routes, deterministic seed state, and manifest fidelity metadata.
+3. Run \`npx -p api-emulator api validate-plugin <provider>\`.
+4. Run the relevant smoke or test command before calling the plugin done.
+
+## Safety
+
+- Never call production APIs from smoke tests.
+- Use dummy credentials and temporary CLI homes.
+- Prefer documented base URL overrides before patching SDKs or CLIs.
+`;
+}
+function runtimeSkill() {
+  return `---
+name: api-emulator-runtime
+description: Run api-emulator locally with configured provider plugins.
+---
+
+# API Emulator Runtime
+
+Use this skill when running local API replacements for development or tests.
+
+## Commands
+
+- \`npx -p api-emulator api list\`
+- \`npx -p api-emulator api init\`
+- \`npx -p api-emulator api install <plugin>\`
+- \`npx -p api-emulator api clone create <provider>\`
+- \`npx -p api-emulator api --service <service>\`
+
+Keep seed data deterministic and reset emulator state between tests.
+`;
+}
+function installAgentSkills(options) {
+  for (const target of parseAgentTargets(options.agents, options.nonInteractive)) {
+    const dir = AGENT_SKILL_DIRS[target];
+    if (!dir) {
+      throw new Error(`Unknown agent target: ${target}. Available: ${Object.keys(AGENT_SKILL_DIRS).join(", ")}`);
+    }
+    writeGeneratedFile(`${dir}/api-emulator-plugin-authoring/SKILL.md`, pluginAuthoringSkill(), {
+      source: "api init",
+      yes: options.yes
+    });
+    writeGeneratedFile(`${dir}/api-emulator-runtime/SKILL.md`, runtimeSkill(), {
+      source: "api init",
+      yes: options.yes
+    });
+  }
+}
 async function initCommand(options) {
+  if (options.agents || options.skillsOnly) {
+    installAgentSkills(options);
+    console.log("Installed api-emulator agent skills");
+  }
+  if (options.skillsOnly) return;
   const filename = "api-emulator.config.yaml";
-  const fullPath = resolve4(filename);
-  if (existsSync3(fullPath)) {
+  const fullPath = resolve5(filename);
+  if (existsSync4(fullPath)) {
     console.error(`Config file already exists: ${filename}`);
     process.exit(1);
   }
@@ -474,7 +662,7 @@ async function initCommand(options) {
     config = { ...DEFAULT_TOKENS, ...pluginModule.initConfig };
   }
   const content = yamlStringify(config);
-  writeFileSync2(fullPath, content, "utf-8");
+  writeFileSync3(fullPath, content, "utf-8");
   console.log(`Created ${filename}`);
   console.log(`
 Run 'npx -p api-emulator api' to start the emulator.`);
@@ -488,18 +676,19 @@ async function listCommand(options = {}) {
   for (const pluginModule of Object.values(pluginModules)) {
     console.log(`  ${pluginModule.name.padEnd(10)}${pluginModule.label}`);
     console.log(`            Endpoints: ${pluginModule.endpoints}`);
+    console.log(`            Fidelity: ${pluginModule.fidelity}`);
     console.log();
   }
 }
 
 // src/commands/install.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { existsSync as existsSync5 } from "fs";
-import { resolve as resolve6 } from "path";
+import { existsSync as existsSync6 } from "fs";
+import { resolve as resolve7 } from "path";
 
 // src/plugin-source-registry.ts
-import { existsSync as existsSync4, readdirSync, readFileSync as readFileSync3, statSync } from "fs";
-import { dirname, join, resolve as resolve5 } from "path";
+import { existsSync as existsSync5, readdirSync, readFileSync as readFileSync4, statSync } from "fs";
+import { dirname as dirname2, join, resolve as resolve6 } from "path";
 var PLUGIN_SOURCES = {
   cloudflare: {
     name: "cloudflare",
@@ -517,17 +706,17 @@ var PACKAGE_ENTRY_DIRS = ["api-emulator", "trading-emulator"];
 function candidateCatalogRoots(cwd = process.cwd()) {
   const envRoots = process.env.API_EMULATOR_PLUGIN_CATALOGS?.split(",").map((value) => value.trim()).filter(Boolean) ?? [];
   const roots = [...envRoots];
-  let current = resolve5(cwd);
+  let current = resolve6(cwd);
   for (; ; ) {
     for (const dir of DEFAULT_CATALOG_DIRS) {
       roots.push(join(current, dir));
-      roots.push(join(dirname(current), dir));
+      roots.push(join(dirname2(current), dir));
     }
-    const parent = dirname(current);
+    const parent = dirname2(current);
     if (parent === current) break;
     current = parent;
   }
-  return [...new Set(roots.map((root) => resolve5(root)))];
+  return [...new Set(roots.map((root) => resolve6(root)))];
 }
 function sourceIdForRoot(root) {
   const base = root.split(/[\\/]/).pop() ?? "local";
@@ -536,29 +725,29 @@ function sourceIdForRoot(root) {
   return base;
 }
 function packageEntrySpecifier(packageRoot, pkg3) {
-  if (typeof pkg3.exports === "string") return resolve5(packageRoot, pkg3.exports);
+  if (typeof pkg3.exports === "string") return resolve6(packageRoot, pkg3.exports);
   if (typeof pkg3.exports === "object" && pkg3.exports !== null && "." in pkg3.exports && typeof pkg3.exports["."] === "string") {
-    return resolve5(packageRoot, pkg3.exports["."]);
+    return resolve6(packageRoot, pkg3.exports["."]);
   }
   if (typeof pkg3.exports === "object" && pkg3.exports !== null && "." in pkg3.exports && typeof pkg3.exports["."] === "object" && pkg3.exports["."] !== null && "import" in pkg3.exports["."] && typeof pkg3.exports["."].import === "string") {
-    return resolve5(packageRoot, pkg3.exports["."].import);
+    return resolve6(packageRoot, pkg3.exports["."].import);
   }
-  if (typeof pkg3.main === "string") return resolve5(packageRoot, pkg3.main);
+  if (typeof pkg3.main === "string") return resolve6(packageRoot, pkg3.main);
   return packageRoot;
 }
 function discoverManifest(root, sourceId) {
   const sources = [];
   for (const manifestFile of CATALOG_MANIFEST_FILES) {
     const manifestPath = join(root, manifestFile);
-    if (!existsSync4(manifestPath)) continue;
-    const manifest = JSON.parse(readFileSync3(manifestPath, "utf-8"));
+    if (!existsSync5(manifestPath)) continue;
+    const manifest = JSON.parse(readFileSync4(manifestPath, "utf-8"));
     for (const [name, entry] of Object.entries(manifest.plugins ?? {})) {
       sources.push({
         name,
         sourceId,
         kind: entry.kind ?? (entry.packageName ? "package" : "file"),
         packageName: entry.packageName,
-        specifier: entry.specifier.startsWith(".") ? resolve5(root, entry.specifier) : entry.specifier,
+        specifier: entry.specifier.startsWith(".") ? resolve6(root, entry.specifier) : entry.specifier,
         description: entry.description ?? `${name} plugin from ${sourceId} catalog`
       });
     }
@@ -566,31 +755,18 @@ function discoverManifest(root, sourceId) {
   return sources;
 }
 function discoverCatalog(root) {
-  if (!existsSync4(root) || !statSync(root).isDirectory()) return [];
+  if (!existsSync5(root) || !statSync(root).isDirectory()) return [];
   const sourceId = sourceIdForRoot(root);
   const sources = discoverManifest(root, sourceId);
   for (const entry of readdirSync(root, { withFileTypes: true })) {
     if (!entry.isDirectory() || !entry.name.startsWith("@")) continue;
     const name = entry.name.slice(1);
     const pluginRoot = join(root, entry.name);
-    for (const entryFile of PLUGIN_ENTRY_FILES) {
-      const specifier = join(pluginRoot, entryFile);
-      if (existsSync4(specifier)) {
-        sources.push({
-          name,
-          sourceId,
-          kind: "file",
-          specifier,
-          description: `${name} plugin from ${sourceId} catalog`
-        });
-        break;
-      }
-    }
     for (const entryDir of PACKAGE_ENTRY_DIRS) {
       const packageRoot = join(pluginRoot, entryDir);
       const packageJsonPath = join(packageRoot, "package.json");
-      if (!existsSync4(packageJsonPath)) continue;
-      const pkg3 = JSON.parse(readFileSync3(packageJsonPath, "utf-8"));
+      if (!existsSync5(packageJsonPath)) continue;
+      const pkg3 = JSON.parse(readFileSync4(packageJsonPath, "utf-8"));
       sources.push({
         name,
         sourceId,
@@ -602,6 +778,19 @@ function discoverCatalog(root) {
       });
       break;
     }
+    for (const entryFile of PLUGIN_ENTRY_FILES) {
+      const specifier = join(pluginRoot, entryFile);
+      if (existsSync5(specifier)) {
+        sources.push({
+          name,
+          sourceId,
+          kind: "file",
+          specifier,
+          description: `${name} plugin from ${sourceId} catalog`
+        });
+        break;
+      }
+    }
   }
   return sources;
 }
@@ -620,9 +809,9 @@ function resolvePluginSource(name) {
 
 // src/commands/install.ts
 function detectPackageManager() {
-  if (existsSync5(resolve6("bun.lock")) || existsSync5(resolve6("bun.lockb"))) return "bun";
-  if (existsSync5(resolve6("pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync5(resolve6("yarn.lock"))) return "yarn";
+  if (existsSync6(resolve7("bun.lock")) || existsSync6(resolve7("bun.lockb"))) return "bun";
+  if (existsSync6(resolve7("pnpm-lock.yaml"))) return "pnpm";
+  if (existsSync6(resolve7("yarn.lock"))) return "yarn";
   return "npm";
 }
 function installPackage(packageManager, packageName) {
@@ -660,12 +849,188 @@ async function installCommand(name, options = {}) {
   console.log(`Recorded plugin in ${PLUGIN_LOCK_FILE}`);
 }
 
+// src/commands/validate-plugin.ts
+import { existsSync as existsSync7, mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { basename, extname, isAbsolute as isAbsolute2, join as join2, resolve as resolve8 } from "path";
+import { spawnSync as spawnSync3 } from "child_process";
+function resolveSource(input) {
+  const source = resolvePluginSource(input);
+  if (source) return source;
+  const specifier = input.startsWith(".") || isAbsolute2(input) ? resolve8(input) : input;
+  return {
+    name: basename(input).replace(/\.[^.]+$/, ""),
+    sourceId: "specifier",
+    kind: "file",
+    specifier,
+    description: `${input} plugin specifier`
+  };
+}
+function assertLocalFile(path) {
+  if ((path.startsWith(".") || isAbsolute2(path)) && !existsSync7(resolve8(path))) {
+    throw new Error(`Plugin entry does not exist: ${path}`);
+  }
+}
+function canBuild(specifier) {
+  return [".ts", ".tsx", ".js", ".mjs"].includes(extname(specifier));
+}
+function buildEntry(specifier) {
+  if (!canBuild(specifier)) return;
+  const outdir = mkdtempSync(join2(tmpdir(), "api-emulator-plugin-validate-"));
+  try {
+    const result = spawnSync3("bun", ["build", specifier, "--packages", "external", "--outdir", outdir], {
+      stdio: "pipe",
+      encoding: "utf-8"
+    });
+    if (result.error) {
+      if (result.error.code === "ENOENT") {
+        console.log("  build: skipped (bun not found)");
+        return;
+      }
+      throw result.error;
+    }
+    if (result.status !== 0) {
+      throw new Error((result.stderr || result.stdout || "Plugin build failed").trim());
+    }
+    console.log("  build: ok");
+  } finally {
+    rmSync(outdir, { recursive: true, force: true });
+  }
+}
+async function loadPlugin(specifier, expectedName) {
+  const module = await loadExternalPluginModule(specifier);
+  if (module.name !== expectedName) {
+    throw new Error(`Plugin exported name "${module.name}" does not match requested plugin "${expectedName}"`);
+  }
+  await module.load();
+  console.log("  load: ok");
+}
+async function validatePluginCommand(input, options = {}) {
+  const source = resolveSource(input);
+  console.log(`Validating ${source.name} from ${source.sourceId}`);
+  console.log(`  specifier: ${source.specifier}`);
+  if (source.packageName) console.log(`  package: ${source.packageName}`);
+  assertLocalFile(source.specifier);
+  console.log("  entry: ok");
+  if (!options.skipBuild) {
+    buildEntry(source.specifier);
+  }
+  if (options.skipLoad) {
+    console.log("  load: skipped");
+  } else {
+    await loadPlugin(source.specifier, source.name);
+  }
+  console.log(`Plugin ${source.name} is valid`);
+}
+
+// src/commands/plugin.ts
+import { existsSync as existsSync8, readFileSync as readFileSync5 } from "fs";
+import { join as join3 } from "path";
+function normalizePluginName(input) {
+  const name = input.trim().replace(/^@/, "");
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+    throw new Error("Plugin names must use lowercase letters, numbers, and hyphens");
+  }
+  return name;
+}
+function pluginEntry(name, fidelity) {
+  return `export const manifest = {
+  name: "${name}",
+  label: "${name} API emulator",
+  endpoints: "GET /health",
+  fidelity: {
+    level: "${fidelity}",
+    endpoints: ["GET /health"],
+    seedableResources: [],
+    smoke: "not-started",
+  },
+  initConfig: {
+    ${JSON.stringify(name)}: {},
+  },
+};
+
+export const plugin = {
+  name: "${name}",
+  register(app) {
+    app.get("/health", (c) => c.json({ ok: true, service: "${name}" }));
+  },
+};
+`;
+}
+function catalogContent(name, specifier, description) {
+  const catalogPath = "api-emulator.catalog.json";
+  const catalog = existsSync8(catalogPath) ? JSON.parse(readFileSync5(catalogPath, "utf-8")) : {};
+  catalog.plugins ??= {};
+  catalog.plugins[name] = {
+    kind: "file",
+    specifier,
+    description
+  };
+  return `${JSON.stringify(catalog, null, 2)}
+`;
+}
+async function pluginCreateCommand(input, options = {}) {
+  const name = normalizePluginName(input);
+  const pluginDir = options.dir ?? `@${name}`;
+  const entryPath = join3(pluginDir, "api-emulator.mjs");
+  const catalogSpecifier = `./${entryPath}`;
+  writeGeneratedFile(entryPath, pluginEntry(name, options.fidelity ?? "stub"), {
+    source: "api clone create",
+    yes: options.yes
+  });
+  writeGeneratedFile(
+    "api-emulator.catalog.json",
+    catalogContent(name, catalogSpecifier, `${name} API emulator plugin`),
+    {
+      source: "api clone create",
+      yes: options.yes
+    }
+  );
+  console.log(`Created ${entryPath}`);
+  console.log(`Recorded ${name} in api-emulator.catalog.json`);
+  console.log(`Run 'npx -p api-emulator api validate-plugin ${name}' to check the clone.`);
+}
+
 // src/index.ts
-var pkg2 = { version: "0.6.0" };
+var pkg2 = { version: "0.7.0" };
 var defaultPort = process.env.API_EMULATOR_PORT ?? process.env.PORT ?? "4000";
 var program = new Command();
-program.name("api").description("Local API emulators you can run, share, and extend with plugins").version(pkg2.version);
-program.command("start", { isDefault: true }).description("Start the emulator server").option("-p, --port <port>", "Base port", defaultPort).option("-s, --service <services>", "Comma-separated services to enable").option("--seed <file>", "Path to seed config file").option("--base-url <url>", "Override advertised base URL (supports {service} template)").option("--portless", "Serve over HTTPS via portless (auto-registers aliases)").option("--plugin <plugins>", "Comma-separated external plugin paths or package names").action(async (opts) => {
+program.name("api").description("Local API emulators you can run, share, and extend with plugins").version(pkg2.version).option("--notify", "Show a macOS notification for useful command milestones");
+function notifyOption(command) {
+  return command.option("--notify", "Show a macOS notification for useful command milestones");
+}
+function wantsNotify(command, opts) {
+  return Boolean(opts.notify ?? command.optsWithGlobals().notify);
+}
+function wantsStartNotify(opts) {
+  return opts.notify !== false;
+}
+function formatDuration(ms) {
+  if (ms < 1e3) return `${ms}ms`;
+  return `${(ms / 1e3).toFixed(1)}s`;
+}
+async function runCommandWithNotification(label, enabled, fn) {
+  const startedAt = Date.now();
+  try {
+    await fn();
+    notifyIfRequested({
+      enabled,
+      title: "api-emulator",
+      message: `${label} finished in ${formatDuration(Date.now() - startedAt)}`
+    });
+  } catch (err) {
+    notifyIfRequested({
+      enabled,
+      title: "api-emulator",
+      message: `${label} failed after ${formatDuration(Date.now() - startedAt)}`
+    });
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+notifyOption(
+  program.command("start", { isDefault: true }).description("Start the emulator server").option("-p, --port <port>", "Base port", defaultPort).option("-s, --service <services>", "Comma-separated services to enable").option("--seed <file>", "Path to seed config file").option("--base-url <url>", "Override advertised base URL (supports {service} template)").option("--portless", "Serve over HTTPS via portless (auto-registers aliases)").option("--plugin <plugins>", "Comma-separated external plugin paths or package names").option("--no-notify", "Disable the macOS notification when the emulator server is ready")
+).action(async (opts) => {
   const port = parseInt(opts.port, 10);
   if (Number.isNaN(port) || port < 1 || port > 65535) {
     console.error(`Invalid port: ${opts.port}`);
@@ -677,24 +1042,62 @@ program.command("start", { isDefault: true }).description("Start the emulator se
     seed: opts.seed,
     baseUrl: opts.baseUrl,
     portless: opts.portless,
-    plugin: opts.plugin
+    plugin: opts.plugin,
+    notify: wantsStartNotify(opts)
   });
 });
-program.command("init").description("Generate a starter config file").option("-s, --service <service>", "Service to generate config for", "all").option("--plugin <plugins>", "Comma-separated external plugin paths or package names").action(async (opts) => {
-  await initCommand({ service: opts.service, plugin: opts.plugin });
+notifyOption(
+  program.command("init").description("Generate a starter config file").option("-s, --service <service>", "Service to generate config for", "all").option("--plugin <plugins>", "Comma-separated external plugin paths or package names").option("--agents <targets>", "Install agent skills for agents,user-agents,claude,codex,cursor,windsurf").option("--skills-only", "Only install agent skills").option("--yes", "Overwrite generated files that changed").option("--non-interactive", "Use defaults suitable for agents and CI")
+).action(async (opts, command) => {
+  await runCommandWithNotification("init", wantsNotify(command, opts), async () => {
+    await initCommand({
+      service: opts.service,
+      plugin: opts.plugin,
+      agents: opts.agents,
+      skillsOnly: opts.skillsOnly,
+      yes: opts.yes,
+      nonInteractive: opts.nonInteractive
+    });
+  });
 });
+function addPluginCreateCommand(command) {
+  notifyOption(
+    command.command("create <name>").description("Scaffold a provider clone").option("--dir <dir>", "Directory to create the clone in").option("--fidelity <level>", "Initial fidelity level", "stub").option("--yes", "Overwrite generated files that changed")
+  ).action(async (name, opts, actionCommand) => {
+    await runCommandWithNotification("plugin create", wantsNotify(actionCommand, opts), async () => {
+      await pluginCreateCommand(name, {
+        dir: opts.dir,
+        fidelity: opts.fidelity,
+        yes: opts.yes
+      });
+    });
+  });
+}
+var plugin = program.command("plugin").description("Create and manage provider plugins");
+addPluginCreateCommand(plugin);
+var clone = program.command("clone").description("Create and manage provider clones");
+addPluginCreateCommand(clone);
 program.command("list").alias("list-services").description("List available services").option("--plugin <plugins>", "Comma-separated external plugin paths or package names").action(async (opts) => {
   await listCommand({ plugin: opts.plugin });
 });
-program.command("install <plugin>").description("Install a provider plugin by name").option("--package-manager <name>", "Package manager to use").option("--no-package-manager", "Only record the plugin in api-emulator.lock").action(async (plugin, opts) => {
-  try {
-    await installCommand(plugin, {
+notifyOption(
+  program.command("install <plugin>").description("Install a provider plugin by name").option("--package-manager <name>", "Package manager to use").option("--no-package-manager", "Only record the plugin in api-emulator.lock")
+).action(async (plugin2, opts, command) => {
+  await runCommandWithNotification("install", wantsNotify(command, opts), async () => {
+    await installCommand(plugin2, {
       packageManager: opts.packageManager === false ? false : opts.packageManager
     });
-  } catch (err) {
-    console.error(err instanceof Error ? err.message : err);
-    process.exit(1);
-  }
+  });
+});
+notifyOption(
+  program.command("validate-plugin <plugin>").description("Validate a provider plugin by name, path, or package").option("--skip-build", "Skip entrypoint build validation").option("--skip-load", "Skip runtime module loading validation")
+).action(async (plugin2, opts, command) => {
+  await runCommandWithNotification("validate-plugin", wantsNotify(command, opts), async () => {
+    await validatePluginCommand(plugin2, {
+      skipBuild: opts.skipBuild,
+      skipLoad: opts.skipLoad
+    });
+  });
 });
 program.parse();
 //# sourceMappingURL=index.js.map