api-emulator 0.5.1 → 0.6.0

package/dist/index.js

@@ -4,6 +4,24 @@ import { Command } from "commander";
 
 // src/external-plugin-adapter.ts
 import { isAbsolute, resolve } from "path";
+
+// src/plugin-manifest.ts
+function readPluginManifest(mod) {
+  return mod.manifest ?? {};
+}
+function validatePluginManifest(manifest, pluginName) {
+  if (manifest.name && manifest.name !== pluginName) {
+    throw new Error(`Plugin manifest name "${manifest.name}" does not match plugin name "${pluginName}"`);
+  }
+  return {
+    ...manifest,
+    label: manifest.label ?? `${pluginName} (external plugin)`,
+    endpoints: manifest.endpoints ?? "",
+    initConfig: manifest.initConfig ?? {}
+  };
+}
+
+// src/external-plugin-adapter.ts
 async function loadExternalPluginModule(specifier) {
   const modulePath = specifier.startsWith(".") || isAbsolute(specifier) ? resolve(specifier) : specifier;
   const mod = await import(modulePath);
@@ -12,10 +30,12 @@ async function loadExternalPluginModule(specifier) {
     throw new Error(`Plugin "${specifier}" must export a ServicePlugin (as "plugin" or default export)`);
   }
   const name = plugin.name;
+  const manifest = validatePluginManifest(readPluginManifest(mod), name);
   return {
     name,
-    label: mod.label ?? `${name} (external plugin)`,
-    endpoints: mod.endpoints ?? "",
+    label: manifest.label,
+    endpoints: manifest.endpoints,
+    manifest,
     async load() {
       return {
         plugin,
@@ -23,439 +43,39 @@ async function loadExternalPluginModule(specifier) {
       };
     },
     defaultFallback: mod.defaultFallback ?? (() => ({ login: "admin", id: 1, scopes: [] })),
-    initConfig: mod.initConfig ?? {}
+    initConfig: manifest.initConfig
   };
 }
 
-// src/default-plugin-catalog.ts
-var DEFAULT_PLUGIN_NAME_LIST = [
-  "vercel",
-  "github",
-  "google",
-  "slack",
-  "apple",
-  "microsoft",
-  "okta",
-  "aws",
-  "resend",
-  "stripe",
-  "mongoatlas",
-  "clerk"
-];
-var DEFAULT_PLUGIN_NAMES = DEFAULT_PLUGIN_NAME_LIST;
-var DEFAULT_PLUGIN_REGISTRY = {
-  vercel: {
-    name: "vercel",
-    label: "Vercel REST API emulator",
-    endpoints: "projects, deployments, domains, env vars, users, teams, file uploads, protection bypass",
-    async load() {
-      const mod = await import("@emulators/vercel");
-      return { plugin: mod.vercelPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback(cfg) {
-      const firstLogin = cfg?.users?.[0]?.username ?? "admin";
-      return { login: firstLogin, id: 1, scopes: [] };
-    },
-    initConfig: {
-      vercel: {
-        users: [{ username: "developer", name: "Developer", email: "dev@example.com" }],
-        teams: [{ slug: "my-team", name: "My Team" }],
-        projects: [{ name: "my-app", team: "my-team", framework: "nextjs" }],
-        integrations: [
-          {
-            client_id: "oac_example_client_id",
-            client_secret: "example_client_secret",
-            name: "My Vercel App",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/vercel"]
-          }
-        ]
-      }
-    }
-  },
-  github: {
-    name: "github",
-    label: "GitHub REST API emulator",
-    endpoints: "users, repos, issues, PRs, comments, reviews, labels, milestones, branches, git data, orgs, teams, releases, webhooks, search, actions, checks, rate limit",
-    async load() {
-      const mod = await import("@emulators/github");
-      return {
-        plugin: mod.githubPlugin,
-        seedFromConfig: mod.seedFromConfig,
-        createAppKeyResolver(store) {
-          return (appId) => {
-            try {
-              const gh = mod.getGitHubStore(store);
-              const ghApp = gh.apps.all().find((a) => a.app_id === appId);
-              if (!ghApp) return null;
-              return { privateKey: ghApp.private_key, slug: ghApp.slug, name: ghApp.name };
-            } catch {
-              return null;
-            }
-          };
-        }
-      };
-    },
-    defaultFallback(cfg) {
-      const firstLogin = cfg?.users?.[0]?.login ?? "admin";
-      return { login: firstLogin, id: 1, scopes: ["repo", "user", "admin:org", "admin:repo_hook"] };
-    },
-    initConfig: {
-      github: {
-        users: [
-          {
-            login: "octocat",
-            name: "The Octocat",
-            email: "octocat@github.com",
-            bio: "I am the Octocat",
-            company: "GitHub",
-            location: "San Francisco"
-          }
-        ],
-        orgs: [{ login: "my-org", name: "My Organization", description: "A test organization" }],
-        repos: [
-          {
-            owner: "octocat",
-            name: "hello-world",
-            description: "My first repository",
-            language: "JavaScript",
-            topics: ["hello", "world"],
-            auto_init: true
-          },
-          {
-            owner: "my-org",
-            name: "org-repo",
-            description: "An organization repository",
-            language: "TypeScript",
-            auto_init: true
-          }
-        ],
-        oauth_apps: [
-          {
-            client_id: "Iv1.example_client_id",
-            client_secret: "example_client_secret",
-            name: "My App",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/github"]
-          }
-        ]
-      }
-    }
-  },
-  google: {
-    name: "google",
-    label: "Google OAuth 2.0 / OpenID Connect + Gmail, Calendar, and Drive emulator",
-    endpoints: "OAuth authorize, token exchange, userinfo, OIDC discovery, token revocation, Gmail messages/drafts/threads/labels/history/settings, Calendar lists/events/freebusy, Drive files/uploads",
-    async load() {
-      const mod = await import("@emulators/google");
-      return { plugin: mod.googlePlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback(cfg) {
-      const firstEmail = cfg?.users?.[0]?.email ?? "testuser@gmail.com";
-      return { login: firstEmail, id: 1, scopes: ["openid", "email", "profile"] };
-    },
-    initConfig: {
-      google: {
-        users: [
-          {
-            email: "testuser@example.com",
-            name: "Test User",
-            picture: "https://lh3.googleusercontent.com/a/default-user",
-            email_verified: true
-          }
-        ],
-        oauth_clients: [
-          {
-            client_id: "example-client-id.apps.googleusercontent.com",
-            client_secret: "GOCSPX-example_secret",
-            name: "Code App (Google)",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/google"]
-          }
-        ],
-        labels: [
-          {
-            id: "Label_ops",
-            user_email: "testuser@example.com",
-            name: "Ops/Review",
-            color_background: "#DDEEFF",
-            color_text: "#111111"
-          }
-        ],
-        messages: [
-          {
-            id: "msg_welcome",
-            user_email: "testuser@example.com",
-            from: "welcome@example.com",
-            to: "testuser@example.com",
-            subject: "Welcome to the Gmail emulator",
-            body_text: "You can now test Gmail, Calendar, and Drive flows locally.",
-            label_ids: ["INBOX", "UNREAD", "CATEGORY_UPDATES"],
-            date: "2025-01-04T10:00:00.000Z"
-          }
-        ],
-        calendars: [
-          {
-            id: "primary",
-            user_email: "testuser@example.com",
-            summary: "testuser@example.com",
-            primary: true,
-            selected: true,
-            time_zone: "UTC"
-          }
-        ],
-        calendar_events: [
-          {
-            id: "evt_kickoff",
-            user_email: "testuser@example.com",
-            calendar_id: "primary",
-            summary: "Project Kickoff",
-            start_date_time: "2025-01-10T09:00:00.000Z",
-            end_date_time: "2025-01-10T09:30:00.000Z"
-          }
-        ],
-        drive_items: [
-          {
-            id: "drv_docs",
-            user_email: "testuser@example.com",
-            name: "Docs",
-            mime_type: "application/vnd.google-apps.folder",
-            parent_ids: ["root"]
-          }
-        ]
-      }
-    }
-  },
-  slack: {
-    name: "slack",
-    label: "Slack API emulator",
-    endpoints: "auth, chat, conversations, users, reactions, team, OAuth, incoming webhooks",
-    async load() {
-      const mod = await import("@emulators/slack");
-      return { plugin: mod.slackPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback() {
-      return { login: "U000000001", id: 1, scopes: ["chat:write", "channels:read", "users:read", "reactions:write"] };
-    },
-    initConfig: {
-      slack: {
-        team: { name: "My Workspace", domain: "my-workspace" },
-        users: [{ name: "developer", real_name: "Developer", email: "dev@example.com" }],
-        channels: [
-          { name: "general", topic: "General discussion" },
-          { name: "random", topic: "Random stuff" }
-        ],
-        bots: [{ name: "my-bot" }],
-        oauth_apps: [
-          {
-            client_id: "12345.67890",
-            client_secret: "example_client_secret",
-            name: "My Slack App",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/slack"]
-          }
-        ]
-      }
-    }
-  },
-  apple: {
-    name: "apple",
-    label: "Apple Sign In / OAuth emulator",
-    endpoints: "OAuth authorize, token exchange, JWKS",
-    async load() {
-      const mod = await import("@emulators/apple");
-      return { plugin: mod.applePlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback(cfg) {
-      const firstEmail = cfg?.users?.[0]?.email ?? "testuser@icloud.com";
-      return { login: firstEmail, id: 1, scopes: ["openid", "email", "name"] };
-    },
-    initConfig: {
-      apple: {
-        users: [{ email: "testuser@icloud.com", name: "Test User" }],
-        oauth_clients: [
-          {
-            client_id: "com.example.app",
-            team_id: "TEAM001",
-            name: "My Apple App",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/apple"]
-          }
-        ]
-      }
-    }
-  },
-  microsoft: {
-    name: "microsoft",
-    label: "Microsoft Entra ID OAuth 2.0 / OpenID Connect emulator",
-    endpoints: "OAuth authorize, token exchange, userinfo, OIDC discovery, Graph /me, logout, token revocation",
-    async load() {
-      const mod = await import("@emulators/microsoft");
-      return { plugin: mod.microsoftPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback(cfg) {
-      const firstEmail = cfg?.users?.[0]?.email ?? "testuser@outlook.com";
-      return { login: firstEmail, id: 1, scopes: ["openid", "email", "profile", "User.Read"] };
-    },
-    initConfig: {
-      microsoft: {
-        users: [{ email: "testuser@outlook.com", name: "Test User" }],
-        oauth_clients: [
-          {
-            client_id: "example-client-id",
-            client_secret: "example-client-secret",
-            name: "My Microsoft App",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/microsoft-entra-id"]
-          }
-        ]
-      }
-    }
-  },
-  okta: {
-    name: "okta",
-    label: "Okta OAuth 2.0 / OpenID Connect + management API emulator",
-    endpoints: "OIDC discovery, JWKS, OAuth authorize/token/userinfo/introspect/revoke/logout, users, groups, apps, authorization servers",
-    async load() {
-      const mod = await import("@emulators/okta");
-      return { plugin: mod.oktaPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback(cfg) {
-      const firstLogin = cfg?.users?.[0]?.login ?? cfg?.users?.[0]?.email ?? "testuser@okta.local";
-      return { login: firstLogin, id: 1, scopes: ["openid", "profile", "email", "groups"] };
-    },
-    initConfig: {
-      okta: {
-        users: [{ login: "testuser@okta.local", email: "testuser@okta.local", first_name: "Test", last_name: "User" }],
-        groups: [{ name: "Everyone", description: "All users", type: "BUILT_IN", okta_id: "00g_everyone" }],
-        authorization_servers: [{ id: "default", name: "default", audiences: ["api://default"] }],
-        oauth_clients: [
-          {
-            client_id: "okta-test-client",
-            client_secret: "okta-test-secret",
-            name: "Sample OIDC Client",
-            redirect_uris: ["http://localhost:3000/callback"],
-            auth_server_id: "default"
-          }
-        ]
-      }
-    }
-  },
-  aws: {
-    name: "aws",
-    label: "AWS cloud service emulator",
-    endpoints: "S3 (buckets, objects), SQS (queues, messages), IAM (users, roles, access keys), STS (assume role, caller identity)",
-    async load() {
-      const mod = await import("@emulators/aws");
-      return { plugin: mod.awsPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback() {
-      return { login: "admin", id: 1, scopes: ["s3:*", "sqs:*", "iam:*", "sts:*"] };
-    },
-    initConfig: {
-      aws: {
-        region: "us-east-1",
-        s3: { buckets: [{ name: "my-app-bucket" }, { name: "my-app-uploads" }] },
-        sqs: { queues: [{ name: "my-app-events" }, { name: "my-app-dlq" }] },
-        iam: {
-          users: [{ user_name: "developer", create_access_key: true }],
-          roles: [{ role_name: "lambda-execution-role", description: "Role for Lambda function execution" }]
-        }
-      }
-    }
-  },
-  resend: {
-    name: "resend",
-    label: "Resend email API emulator",
-    endpoints: "emails, domains, contacts, API keys, inbox UI",
-    async load() {
-      const mod = await import("@emulators/resend");
-      return { plugin: mod.resendPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback() {
-      return { login: "re_test_admin", id: 1, scopes: [] };
-    },
-    initConfig: {
-      resend: {
-        domains: [{ name: "example.com", region: "us-east-1" }],
-        contacts: [{ email: "test@example.com", first_name: "Test", last_name: "User" }]
-      }
-    }
-  },
-  stripe: {
-    name: "stripe",
-    label: "Stripe payments emulator",
-    endpoints: "customers, payment methods, customer sessions, payment intents, charges, products, prices, checkout sessions, webhooks",
-    async load() {
-      const mod = await import("@emulators/stripe");
-      return { plugin: mod.stripePlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback() {
-      return { login: "sk_test_admin", id: 1, scopes: [] };
-    },
-    initConfig: {
-      stripe: {
-        customers: [{ email: "test@example.com", name: "Test Customer" }],
-        products: [{ name: "Pro Plan", description: "Monthly pro subscription" }],
-        prices: [{ product_name: "Pro Plan", currency: "usd", unit_amount: 2e3 }]
-      }
-    }
-  },
-  mongoatlas: {
-    name: "mongoatlas",
-    label: "MongoDB Atlas service emulator",
-    endpoints: "Atlas Admin API v2 (projects, clusters, database users, databases, collections), Atlas Data API v1 (findOne, find, insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany, aggregate)",
-    async load() {
-      const mod = await import("@emulators/mongoatlas");
-      return { plugin: mod.mongoatlasPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback() {
-      return { login: "admin", id: 1, scopes: [] };
-    },
-    initConfig: {
-      mongoatlas: {
-        projects: [{ name: "Project0" }],
-        clusters: [{ name: "Cluster0", project: "Project0" }],
-        database_users: [{ username: "admin", project: "Project0" }],
-        databases: [{ cluster: "Cluster0", name: "test", collections: ["items"] }]
-      }
-    }
-  },
-  clerk: {
-    name: "clerk",
-    label: "Clerk authentication and user management emulator",
-    endpoints: "OIDC discovery, JWKS, OAuth authorize/token/userinfo, users, email addresses, organizations, memberships, invitations, sessions",
-    async load() {
-      const mod = await import("@emulators/clerk");
-      return { plugin: mod.clerkPlugin, seedFromConfig: mod.seedFromConfig };
-    },
-    defaultFallback(cfg) {
-      const firstEmail = cfg?.users?.[0]?.email_addresses?.[0] ?? "test@example.com";
-      return { login: firstEmail, id: 1, scopes: [] };
-    },
-    initConfig: {
-      clerk: {
-        users: [
-          {
-            first_name: "Test",
-            last_name: "User",
-            email_addresses: ["test@example.com"],
-            password: "clerk_test_password"
-          }
-        ],
-        organizations: [
-          {
-            name: "My Company",
-            slug: "my-company",
-            members: [{ email: "test@example.com", role: "admin" }]
-          }
-        ],
-        oauth_applications: [
-          {
-            client_id: "clerk_emulate_client",
-            client_secret: "clerk_emulate_secret",
-            name: "api-emulator App",
-            redirect_uris: ["http://localhost:3000/api/auth/callback/clerk"]
-          }
-        ]
-      }
-    }
+// src/plugin-lock.ts
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { resolve as resolve2 } from "path";
+var PLUGIN_LOCK_FILE = "api-emulator.lock";
+function createEmptyPluginLock() {
+  return { version: 1, plugins: {} };
+}
+function readPluginLock(cwd = process.cwd()) {
+  const path = resolve2(cwd, PLUGIN_LOCK_FILE);
+  if (!existsSync(path)) return createEmptyPluginLock();
+  const parsed = JSON.parse(readFileSync(path, "utf-8"));
+  if (parsed.version !== 1 || typeof parsed.plugins !== "object" || parsed.plugins === null) {
+    throw new Error(`Invalid ${PLUGIN_LOCK_FILE}`);
   }
-};
+  return parsed;
+}
+function writePluginLock(lock, cwd = process.cwd()) {
+  const sortedPlugins = Object.fromEntries(Object.entries(lock.plugins).sort(([a], [b]) => a.localeCompare(b)));
+  const content = `${JSON.stringify({ version: 1, plugins: sortedPlugins }, null, 2)}
+`;
+  writeFileSync(resolve2(cwd, PLUGIN_LOCK_FILE), content, "utf-8");
+}
+function getLockedPluginSpecifiers(cwd = process.cwd()) {
+  return Object.values(readPluginLock(cwd).plugins).map((entry) => entry.specifier);
+}
+
+// src/default-plugin-catalog.ts
+var DEFAULT_PLUGIN_NAMES = [];
+var DEFAULT_PLUGIN_REGISTRY = {};
 
 // src/registry.ts
 var DEFAULT_TOKENS = {
@@ -470,8 +90,10 @@ var DEFAULT_TOKENS = {
     }
   }
 };
-async function resolvePluginModules(pluginSpecifiers = []) {
-  const results = await Promise.all(pluginSpecifiers.map(loadExternalPluginModule));
+async function resolvePluginModules(pluginSpecifiers = [], options = {}) {
+  const installedSpecifiers = options.includeInstalled ? getLockedPluginSpecifiers() : [];
+  const allSpecifiers = [...installedSpecifiers, ...pluginSpecifiers];
+  const results = await Promise.all(allSpecifiers.map(loadExternalPluginModule));
   const externalEntries = {};
   for (const pluginModule of results) {
     if (pluginModule.name in DEFAULT_PLUGIN_REGISTRY) {
@@ -489,8 +111,8 @@ function getDefaultPluginNames() {
 }
 
 // src/commands/start.ts
-import { readFileSync, existsSync } from "fs";
-import { resolve as resolve2 } from "path";
+import { readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import { resolve as resolve3 } from "path";
 import { parse as parseYaml } from "yaml";
 import pc from "picocolors";
 
@@ -505,12 +127,12 @@ function hasPortless() {
   return result.status === 0;
 }
 function promptYesNo(question) {
-  return new Promise((resolve4) => {
+  return new Promise((resolve7) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
     rl.question(question, (answer) => {
       rl.close();
       const normalized = answer.trim().toLowerCase();
-      resolve4(normalized === "" || normalized === "y" || normalized === "yes");
+      resolve7(normalized === "" || normalized === "y" || normalized === "yes");
     });
   });
 }
@@ -580,7 +202,7 @@ function resolveBaseUrl(opts) {
   if (opts.baseUrl) {
     return opts.baseUrl.replace(/\{service\}/g, opts.service);
   }
-  const envBaseUrl = process.env.API_EMULATOR_BASE_URL ?? process.env.EMULATE_BASE_URL;
+  const envBaseUrl = process.env.API_EMULATOR_BASE_URL;
   if (envBaseUrl) {
     return envBaseUrl.replace(/\{service\}/g, opts.service);
   }
@@ -592,7 +214,11 @@ function resolveBaseUrl(opts) {
 }
 
 // src/service-runtime.ts
-import { createServer } from "@emulators/core";
+import {
+  createServer,
+  createStoreFixture,
+  fixtureStoreSnapshot
+} from "@api-emulator/core";
 import { serve } from "@hono/node-server";
 function createAuthTokens(seedConfig) {
   const tokens = {};
@@ -631,15 +257,32 @@ function createServiceRuntime(options) {
     service,
     url: baseUrl,
     store,
+    snapshot() {
+      return store.snapshot();
+    },
+    restore(fixture) {
+      store.restore(fixtureStoreSnapshot(fixture));
+    },
+    exportFixture(options2 = {}) {
+      const interactions = store.getData("api-emulator:interactions");
+      return createStoreFixture(service, store.snapshot(), {
+        ...options2,
+        interactions: options2.interactions ?? interactions
+      });
+    },
+    resetToFixture(fixture) {
+      store.reset();
+      store.restore(fixtureStoreSnapshot(fixture));
+    },
     reset() {
       store.reset();
       seed();
     },
     close() {
-      return new Promise((resolve4, reject) => {
+      return new Promise((resolve7, reject) => {
         httpServer.close((err) => {
           if (err) reject(err);
-          else resolve4();
+          else resolve7();
         });
       });
     }
@@ -647,15 +290,15 @@ function createServiceRuntime(options) {
 }
 
 // src/commands/start.ts
-var pkg = { version: "0.5.1" };
+var pkg = { version: "0.6.0" };
 function loadSeedConfig(seedPath) {
   if (seedPath) {
-    const fullPath = resolve2(seedPath);
-    if (!existsSync(fullPath)) {
+    const fullPath = resolve3(seedPath);
+    if (!existsSync2(fullPath)) {
       console.error(`Seed file not found: ${fullPath}`);
       process.exit(1);
     }
-    const content = readFileSync(fullPath, "utf-8");
+    const content = readFileSync2(fullPath, "utf-8");
     try {
       const config = fullPath.endsWith(".json") ? JSON.parse(content) : parseYaml(content);
       return { config, source: seedPath };
@@ -664,21 +307,11 @@ function loadSeedConfig(seedPath) {
       process.exit(1);
     }
   }
-  const autoFiles = [
-    "api-emulator.config.yaml",
-    "api-emulator.config.yml",
-    "api-emulator.config.json",
-    "emulate.config.yaml",
-    "emulate.config.yml",
-    "emulate.config.json",
-    "service-emulator.config.yaml",
-    "service-emulator.config.yml",
-    "service-emulator.config.json"
-  ];
+  const autoFiles = ["api-emulator.config.yaml", "api-emulator.config.yml", "api-emulator.config.json"];
   for (const file of autoFiles) {
-    const fullPath = resolve2(file);
-    if (existsSync(fullPath)) {
-      const content = readFileSync(fullPath, "utf-8");
+    const fullPath = resolve3(file);
+    if (existsSync2(fullPath)) {
+      const content = readFileSync2(fullPath, "utf-8");
       try {
         const config = fullPath.endsWith(".json") ? JSON.parse(content) : parseYaml(content);
         return { config, source: file };
@@ -706,7 +339,7 @@ async function startCommand(options) {
   const pluginSpecifiers = options.plugin?.split(",").map((s) => s.trim()).filter(Boolean) ?? [];
   let allPluginModules;
   try {
-    allPluginModules = await resolvePluginModules(pluginSpecifiers);
+    allPluginModules = await resolvePluginModules(pluginSpecifiers, { includeInstalled: true });
   } catch (err) {
     console.error(`Failed to load plugins: ${err instanceof Error ? err.message : err}`);
     process.exit(1);
@@ -804,25 +437,27 @@ function printBanner(services, tokens, configSource) {
   if (configSource) {
     lines.push(`  ${pc.dim("Config:")} ${configSource}`);
   } else {
-    lines.push(`  ${pc.dim("Config:")} defaults ${pc.dim("(run")} npx api-emulator init ${pc.dim("to customize)")}`);
+    lines.push(
+      `  ${pc.dim("Config:")} defaults ${pc.dim("(run")} npx -p api-emulator api init ${pc.dim("to customize)")}`
+    );
   }
   lines.push("");
   console.log(lines.join("\n"));
 }
 
 // src/commands/init.ts
-import { writeFileSync, existsSync as existsSync2 } from "fs";
-import { resolve as resolve3 } from "path";
+import { writeFileSync as writeFileSync2, existsSync as existsSync3 } from "fs";
+import { resolve as resolve4 } from "path";
 import { stringify as yamlStringify } from "yaml";
 async function initCommand(options) {
   const filename = "api-emulator.config.yaml";
-  const fullPath = resolve3(filename);
-  if (existsSync2(fullPath)) {
+  const fullPath = resolve4(filename);
+  if (existsSync3(fullPath)) {
     console.error(`Config file already exists: ${filename}`);
     process.exit(1);
   }
   const pluginSpecifiers = options.plugin?.split(",").map((s) => s.trim()).filter(Boolean) ?? [];
-  const pluginModules = await resolvePluginModules(pluginSpecifiers);
+  const pluginModules = await resolvePluginModules(pluginSpecifiers, { includeInstalled: true });
   const availableServices = Object.keys(pluginModules);
   let config;
   if (options.service === "all") {
@@ -839,16 +474,16 @@ async function initCommand(options) {
     config = { ...DEFAULT_TOKENS, ...pluginModule.initConfig };
   }
   const content = yamlStringify(config);
-  writeFileSync(fullPath, content, "utf-8");
+  writeFileSync2(fullPath, content, "utf-8");
   console.log(`Created ${filename}`);
   console.log(`
-Run 'npx api-emulator' to start the emulator.`);
+Run 'npx -p api-emulator api' to start the emulator.`);
 }
 
 // src/commands/list.ts
 async function listCommand(options = {}) {
   const pluginSpecifiers = options.plugin?.split(",").map((s) => s.trim()).filter(Boolean) ?? [];
-  const pluginModules = await resolvePluginModules(pluginSpecifiers);
+  const pluginModules = await resolvePluginModules(pluginSpecifiers, { includeInstalled: true });
   console.log("\nAvailable services:\n");
   for (const pluginModule of Object.values(pluginModules)) {
     console.log(`  ${pluginModule.name.padEnd(10)}${pluginModule.label}`);
@@ -857,11 +492,179 @@ async function listCommand(options = {}) {
   }
 }
 
+// src/commands/install.ts
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync5 } from "fs";
+import { resolve as resolve6 } 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";
+var PLUGIN_SOURCES = {
+  cloudflare: {
+    name: "cloudflare",
+    sourceId: "public",
+    kind: "package",
+    packageName: "@api-emulator/cloudflare",
+    specifier: "@api-emulator/cloudflare",
+    description: "Workers-style bindings, D1, KV, R2, queues, durable objects, and service bindings"
+  }
+};
+var DEFAULT_CATALOG_DIRS = ["api-emulator-plugins", "api-emulator-internal"];
+var CATALOG_MANIFEST_FILES = ["api-emulator.catalog.json"];
+var PLUGIN_ENTRY_FILES = ["api-emulator.mjs", "api-emulator/index.mjs"];
+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);
+  for (; ; ) {
+    for (const dir of DEFAULT_CATALOG_DIRS) {
+      roots.push(join(current, dir));
+      roots.push(join(dirname(current), dir));
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return [...new Set(roots.map((root) => resolve5(root)))];
+}
+function sourceIdForRoot(root) {
+  const base = root.split(/[\\/]/).pop() ?? "local";
+  if (base === "api-emulator-plugins") return "public";
+  if (base === "api-emulator-internal") return "internal";
+  return base;
+}
+function packageEntrySpecifier(packageRoot, pkg3) {
+  if (typeof pkg3.exports === "string") return resolve5(packageRoot, pkg3.exports);
+  if (typeof pkg3.exports === "object" && pkg3.exports !== null && "." in pkg3.exports && typeof pkg3.exports["."] === "string") {
+    return resolve5(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);
+  }
+  if (typeof pkg3.main === "string") return resolve5(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"));
+    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,
+        description: entry.description ?? `${name} plugin from ${sourceId} catalog`
+      });
+    }
+  }
+  return sources;
+}
+function discoverCatalog(root) {
+  if (!existsSync4(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"));
+      sources.push({
+        name,
+        sourceId,
+        kind: "package",
+        packageName: pkg3.name,
+        packageRoot,
+        specifier: packageEntrySpecifier(packageRoot, pkg3),
+        description: pkg3.description ?? `${name} package from ${sourceId} catalog`
+      });
+      break;
+    }
+  }
+  return sources;
+}
+function pluginSources() {
+  const sources = { ...PLUGIN_SOURCES };
+  for (const root of candidateCatalogRoots()) {
+    for (const source of discoverCatalog(root)) {
+      sources[source.name] ??= source;
+    }
+  }
+  return sources;
+}
+function resolvePluginSource(name) {
+  return pluginSources()[name] ?? null;
+}
+
+// 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";
+  return "npm";
+}
+function installPackage(packageManager, packageName) {
+  const args = packageManager === "bun" ? ["add", "-D", packageName] : packageManager === "pnpm" ? ["add", "-D", packageName] : packageManager === "yarn" ? ["add", "-D", packageName] : ["install", "-D", packageName];
+  const result = spawnSync2(packageManager, args, { stdio: "inherit" });
+  if (result.error) {
+    throw result.error;
+  }
+  if (result.status !== 0) {
+    throw new Error(`${packageManager} ${args.join(" ")} failed`);
+  }
+}
+async function installCommand(name, options = {}) {
+  const source = resolvePluginSource(name);
+  if (!source) {
+    throw new Error(`Unknown plugin source: ${name}`);
+  }
+  const packageManager = options.packageManager === void 0 ? detectPackageManager() : options.packageManager;
+  if (packageManager && source.packageName) {
+    installPackage(packageManager, source.packageName);
+  } else if (packageManager && source.kind === "package" && !source.packageName) {
+    throw new Error(`Plugin source "${name}" is a local package without a package name`);
+  }
+  const lock = readPluginLock();
+  lock.plugins[source.name] = {
+    name: source.name,
+    source: source.kind === "file" ? "specifier" : "registry",
+    sourceId: source.sourceId,
+    packageName: source.packageName,
+    specifier: packageManager && source.packageName ? source.packageName : source.specifier,
+    version: "latest"
+  };
+  writePluginLock(lock);
+  console.log(`Installed ${source.name} from ${source.sourceId}`);
+  console.log(`Recorded plugin in ${PLUGIN_LOCK_FILE}`);
+}
+
 // src/index.ts
-var pkg2 = { version: "0.5.1" };
-var defaultPort = process.env.API_EMULATOR_PORT ?? process.env.EMULATE_PORT ?? process.env.PORT ?? "4000";
+var pkg2 = { version: "0.6.0" };
+var defaultPort = process.env.API_EMULATOR_PORT ?? process.env.PORT ?? "4000";
 var program = new Command();
-program.name("api-emulator").description("Local API emulators you can run, share, and extend with plugins").version(pkg2.version);
+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) => {
   const port = parseInt(opts.port, 10);
   if (Number.isNaN(port) || port < 1 || port > 65535) {
@@ -883,5 +686,15 @@ program.command("init").description("Generate a starter config file").option("-s
 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, {
+      packageManager: opts.packageManager === false ? false : opts.packageManager
+    });
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+});
 program.parse();
 //# sourceMappingURL=index.js.map