workos 0.11.1 → 0.12.0-beta.1

package/dist/check-coverage.ts

@@ -0,0 +1,237 @@
+#!/usr/bin/env tsx
+/**
+ * Coverage checker: compares the WorkOS OpenAPI spec against the emulator's
+ * registered routes to find missing or extra endpoints.
+ *
+ * Usage:
+ *   pnpm check:coverage path/to/openapi.yaml
+ *   pnpm check:coverage ~/Developer/workos/packages/api/open-api-spec.yaml
+ *
+ * Reports:
+ *   - Spec endpoints missing from the emulator
+ *   - Emulator endpoints not in the spec (custom/internal)
+ *   - Coverage percentage
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { resolve, extname, join } from 'node:path';
+import YAML from 'yaml';
+
+// ---------------------------------------------------------------------------
+// Parse OpenAPI spec endpoints
+// ---------------------------------------------------------------------------
+
+interface SpecEndpoint {
+  method: string;
+  path: string;
+  operationId?: string;
+  summary?: string;
+  tags: string[];
+}
+
+function parseOpenApiEndpoints(specPath: string): SpecEndpoint[] {
+  const raw = readFileSync(specPath, 'utf-8');
+  const ext = extname(specPath).toLowerCase();
+  const spec = ext === '.yaml' || ext === '.yml' ? YAML.parse(raw) : JSON.parse(raw);
+
+  const endpoints: SpecEndpoint[] = [];
+  const methods = ['get', 'post', 'put', 'patch', 'delete'] as const;
+
+  for (const [path, item] of Object.entries(spec.paths ?? {}) as [string, any][]) {
+    for (const method of methods) {
+      const op = item[method];
+      if (!op) continue;
+
+      // Normalize OpenAPI path params {id} → :id
+      const normalizedPath = path.replace(/\{([^}]+)\}/g, ':$1');
+
+      endpoints.push({
+        method: method.toUpperCase(),
+        path: normalizedPath,
+        operationId: op.operationId,
+        summary: op.summary,
+        tags: op.tags ?? [],
+      });
+    }
+  }
+
+  return endpoints;
+}
+
+// ---------------------------------------------------------------------------
+// Parse emulator registered routes from source files
+// ---------------------------------------------------------------------------
+
+interface EmulatorEndpoint {
+  method: string;
+  path: string;
+  file: string;
+  line: number;
+}
+
+function parseEmulatorEndpoints(): EmulatorEndpoint[] {
+  const routesDir = resolve('src/emulate/workos/routes');
+  const serverFile = resolve('src/emulate/core/server.ts');
+  const endpoints: EmulatorEndpoint[] = [];
+
+  const routePattern = /app\.(get|post|put|patch|delete)\('([^']+)'/g;
+
+  const filesToScan: string[] = [];
+
+  // Collect route files
+  if (existsSync(routesDir)) {
+    for (const file of readdirSync(routesDir)) {
+      if (file.endsWith('.ts') && !file.endsWith('.spec.ts')) {
+        filesToScan.push(join(routesDir, file));
+      }
+    }
+  }
+
+  // Also scan server.ts for JWKS and other direct routes
+  if (existsSync(serverFile)) {
+    filesToScan.push(serverFile);
+  }
+
+  for (const filePath of filesToScan) {
+    const content = readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+      routePattern.lastIndex = 0;
+      let match;
+      while ((match = routePattern.exec(lines[i])) !== null) {
+        endpoints.push({
+          method: match[1].toUpperCase(),
+          path: match[2],
+          file: filePath.replace(resolve('.') + '/', ''),
+          line: i + 1,
+        });
+      }
+    }
+  }
+
+  return endpoints;
+}
+
+// ---------------------------------------------------------------------------
+// Normalize paths for comparison
+// ---------------------------------------------------------------------------
+
+/** Normalize path params to a canonical form for matching.
+ *  e.g., :id, :orgId, :organization_id all become :param in the same position */
+function normalizePath(path: string): string {
+  return path
+    .replace(/:[a-zA-Z_]+/g, ':param')
+    .replace(/\/+$/, '')
+    .toLowerCase();
+}
+
+function routeKey(method: string, path: string): string {
+  return `${method} ${normalizePath(path)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+function main(): void {
+  const specPath = process.argv[2];
+  if (!specPath) {
+    console.error('Usage: check-coverage <openapi-spec-path>');
+    console.error('  e.g.: pnpm check:coverage ~/Developer/workos/packages/api/open-api-spec.yaml');
+    process.exit(1);
+  }
+
+  const resolvedSpec = resolve(specPath);
+  if (!existsSync(resolvedSpec)) {
+    console.error(`Spec file not found: ${resolvedSpec}`);
+    process.exit(1);
+  }
+
+  const specEndpoints = parseOpenApiEndpoints(resolvedSpec);
+  const emulatorEndpoints = parseEmulatorEndpoints();
+
+  // Build lookup maps
+  const specMap = new Map<string, SpecEndpoint>();
+  for (const ep of specEndpoints) {
+    specMap.set(routeKey(ep.method, ep.path), ep);
+  }
+
+  const emulatorMap = new Map<string, EmulatorEndpoint>();
+  for (const ep of emulatorEndpoints) {
+    emulatorMap.set(routeKey(ep.method, ep.path), ep);
+  }
+
+  // Find gaps
+  const missing: SpecEndpoint[] = [];
+  const covered: SpecEndpoint[] = [];
+  for (const [key, ep] of specMap) {
+    if (emulatorMap.has(key)) {
+      covered.push(ep);
+    } else {
+      missing.push(ep);
+    }
+  }
+
+  const extra: EmulatorEndpoint[] = [];
+  for (const [key, ep] of emulatorMap) {
+    if (!specMap.has(key)) {
+      extra.push(ep);
+    }
+  }
+
+  // Group missing by tag
+  const missingByTag = new Map<string, SpecEndpoint[]>();
+  for (const ep of missing) {
+    const tag = ep.tags[0] ?? 'untagged';
+    if (!missingByTag.has(tag)) missingByTag.set(tag, []);
+    missingByTag.get(tag)!.push(ep);
+  }
+
+  // Report
+  const total = specEndpoints.length;
+  const coveredCount = covered.length;
+  const pct = total > 0 ? ((coveredCount / total) * 100).toFixed(1) : '0';
+
+  console.log('');
+  console.log('=== Emulator API Coverage Report ===');
+  console.log('');
+  console.log(`  Spec endpoints:     ${total}`);
+  console.log(`  Emulator endpoints: ${emulatorEndpoints.length}`);
+  console.log(`  Covered:            ${coveredCount}/${total} (${pct}%)`);
+  console.log(`  Missing:            ${missing.length}`);
+  console.log(`  Extra (emulator-only): ${extra.length}`);
+  console.log('');
+
+  if (missing.length > 0) {
+    console.log('--- Missing from emulator ---');
+    console.log('');
+    for (const [tag, eps] of [...missingByTag.entries()].sort((a, b) => a[0].localeCompare(b[0]))) {
+      console.log(`  [${tag}]`);
+      for (const ep of eps) {
+        const desc = ep.summary ? ` — ${ep.summary}` : '';
+        console.log(`    ${ep.method.padEnd(6)} ${ep.path}${desc}`);
+      }
+      console.log('');
+    }
+  }
+
+  if (extra.length > 0) {
+    console.log('--- Emulator-only (not in spec) ---');
+    console.log('');
+    for (const ep of extra.sort((a, b) => a.path.localeCompare(b.path))) {
+      console.log(`    ${ep.method.padEnd(6)} ${ep.path}  (${ep.file}:${ep.line})`);
+    }
+    console.log('');
+  }
+
+  if (missing.length === 0) {
+    console.log('Full coverage — all spec endpoints are implemented.');
+    console.log('');
+  }
+
+  // Exit 1 if there are missing endpoints (useful for CI later)
+  process.exit(missing.length > 0 ? 1 : 0);
+}
+
+main();

package/dist/commands/dev.d.ts

@@ -0,0 +1,23 @@
+import { type EmulatorSeedConfig } from '../emulate/index.js';
+export interface DevArgs {
+    port: number;
+    seed?: string;
+    '--'?: string[];
+}
+/**
+ * Build the env vars object to inject into the child process.
+ *
+ * Sets both the base URL style (`WORKOS_API_BASE_URL`) and the decomposed
+ * style (`WORKOS_API_HOSTNAME` + `WORKOS_API_PORT` + `WORKOS_API_HTTPS`)
+ * so the emulator works with authkit SDKs (which read the decomposed vars)
+ * and direct SDK consumers (which may use the base URL).
+ */
+/**
+ * Default seed data for `workos dev` so the AuthKit login flow works
+ * out of the box. Provides a test user, an organization with a verified
+ * domain, and a membership linking the two. Skipped when the user
+ * provides `--seed` or a `workos-emulate.config.*` file is auto-detected.
+ */
+export declare const DEFAULT_DEV_SEED: EmulatorSeedConfig;
+export declare function buildDevEnv(emulatorUrl: string, apiKey?: string): Record<string, string>;
+export declare function runDev(argv: DevArgs): Promise<void>;

package/dist/commands/dev.js

@@ -0,0 +1,139 @@
+import { createEmulator } from '../emulate/index.js';
+import { resolveDevCommand } from '../lib/dev-command.js';
+import { spawn } from 'node:child_process';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import chalk from 'chalk';
+function loadSeedFile(filePath) {
+    const resolved = resolve(filePath);
+    if (!existsSync(resolved)) {
+        console.error(`Seed file not found: ${resolved}`);
+        process.exit(1);
+    }
+    const content = readFileSync(resolved, 'utf-8');
+    if (resolved.endsWith('.json')) {
+        return JSON.parse(content);
+    }
+    return parseYaml(content);
+}
+function autoDetectSeedFile() {
+    const candidates = ['workos-emulate.config.yaml', 'workos-emulate.config.yml', 'workos-emulate.config.json'];
+    for (const name of candidates) {
+        const filePath = resolve(name);
+        if (existsSync(filePath)) {
+            return loadSeedFile(filePath);
+        }
+    }
+    return null;
+}
+/**
+ * Build the env vars object to inject into the child process.
+ *
+ * Sets both the base URL style (`WORKOS_API_BASE_URL`) and the decomposed
+ * style (`WORKOS_API_HOSTNAME` + `WORKOS_API_PORT` + `WORKOS_API_HTTPS`)
+ * so the emulator works with authkit SDKs (which read the decomposed vars)
+ * and direct SDK consumers (which may use the base URL).
+ */
+/**
+ * Default seed data for `workos dev` so the AuthKit login flow works
+ * out of the box. Provides a test user, an organization with a verified
+ * domain, and a membership linking the two. Skipped when the user
+ * provides `--seed` or a `workos-emulate.config.*` file is auto-detected.
+ */
+export const DEFAULT_DEV_SEED = {
+    users: [
+        {
+            email: 'test@example.com',
+            first_name: 'Test',
+            last_name: 'User',
+            password: 'password',
+            email_verified: true,
+        },
+    ],
+    organizations: [
+        {
+            name: 'Test Organization',
+            domains: [{ domain: 'example.com', state: 'verified' }],
+        },
+    ],
+};
+export function buildDevEnv(emulatorUrl, apiKey = 'sk_test_default') {
+    const url = new URL(emulatorUrl);
+    return {
+        WORKOS_API_BASE_URL: emulatorUrl,
+        WORKOS_API_HOSTNAME: url.hostname,
+        WORKOS_API_PORT: url.port,
+        WORKOS_API_HTTPS: 'false',
+        WORKOS_API_KEY: apiKey,
+        WORKOS_CLIENT_ID: 'client_emulated',
+    };
+}
+export async function runDev(argv) {
+    const userSeed = argv.seed ? loadSeedFile(argv.seed) : autoDetectSeedFile();
+    const seedConfig = userSeed ?? DEFAULT_DEV_SEED;
+    // 1. Start emulator
+    const emulator = await createEmulator({
+        port: argv.port,
+        seed: seedConfig,
+    });
+    // 2. Resolve dev command
+    const explicit = argv['--'];
+    const devCmd = explicit && explicit.length > 0
+        ? { command: explicit[0], args: explicit.slice(1), framework: null }
+        : await resolveDevCommand(process.cwd());
+    // 3. Print status banner
+    console.log();
+    console.log(`${chalk.cyan('WorkOS Emulate')} ${chalk.dim(emulator.url)}`);
+    if (devCmd.framework) {
+        console.log(chalk.dim(`Detected ${devCmd.framework}`));
+    }
+    console.log(chalk.dim(`Running: ${devCmd.command} ${devCmd.args.join(' ')}`));
+    if (!userSeed) {
+        console.log();
+        console.log(`  ${chalk.dim('Email:')}    test@example.com`);
+        console.log(`  ${chalk.dim('Password:')} password`);
+    }
+    console.log();
+    // 4. Spawn child process with env vars
+    let child;
+    try {
+        child = spawn(devCmd.command, devCmd.args, {
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                ...buildDevEnv(emulator.url, emulator.apiKey),
+            },
+        });
+    }
+    catch {
+        console.error(chalk.red(`Failed to start: ${devCmd.command} ${devCmd.args.join(' ')}`));
+        console.error(chalk.dim('Try specifying the command explicitly: workos dev -- <your-command>'));
+        await emulator.close();
+        process.exit(1);
+    }
+    child.on('error', async (err) => {
+        console.error(chalk.red(`Failed to start: ${devCmd.command}`));
+        if (err.code === 'ENOENT') {
+            console.error(chalk.dim(`Command not found: ${devCmd.command}`));
+            console.error(chalk.dim('Try specifying the command explicitly: workos dev -- <your-command>'));
+        }
+        else {
+            console.error(chalk.dim(err.message));
+        }
+        await emulator.close();
+        process.exit(1);
+    });
+    // 5. Signal handling — forward to child, then close emulator
+    const shutdown = (signal) => {
+        child.kill(signal);
+        emulator.close().then(() => process.exit(0));
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    // 6. If child exits, close emulator and exit with same code
+    child.on('exit', (code) => {
+        emulator.close().then(() => process.exit(code ?? 0));
+    });
+}
+//# sourceMappingURL=dev.js.map

package/dist/commands/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"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","sourcesContent":["import { createEmulator, type EmulatorSeedConfig } from '../emulate/index.js';\nimport { resolveDevCommand } from '../lib/dev-command.js';\nimport { spawn, type ChildProcess } from 'node:child_process';\nimport { readFileSync, existsSync } from 'node:fs';\nimport { resolve } from 'node:path';\nimport { parse as parseYaml } from 'yaml';\nimport chalk from 'chalk';\n\nexport interface DevArgs {\n  port: number;\n  seed?: string;\n  '--'?: string[];\n}\n\nfunction loadSeedFile(filePath: string): EmulatorSeedConfig {\n  const resolved = resolve(filePath);\n  if (!existsSync(resolved)) {\n    console.error(`Seed file not found: ${resolved}`);\n    process.exit(1);\n  }\n\n  const content = readFileSync(resolved, 'utf-8');\n  if (resolved.endsWith('.json')) {\n    return JSON.parse(content) as EmulatorSeedConfig;\n  }\n  return parseYaml(content) as EmulatorSeedConfig;\n}\n\nfunction autoDetectSeedFile(): EmulatorSeedConfig | null {\n  const candidates = ['workos-emulate.config.yaml', 'workos-emulate.config.yml', 'workos-emulate.config.json'];\n\n  for (const name of candidates) {\n    const filePath = resolve(name);\n    if (existsSync(filePath)) {\n      return loadSeedFile(filePath);\n    }\n  }\n  return null;\n}\n\n/**\n * Build the env vars object to inject into the child process.\n *\n * Sets both the base URL style (`WORKOS_API_BASE_URL`) and the decomposed\n * style (`WORKOS_API_HOSTNAME` + `WORKOS_API_PORT` + `WORKOS_API_HTTPS`)\n * so the emulator works with authkit SDKs (which read the decomposed vars)\n * and direct SDK consumers (which may use the base URL).\n */\n/**\n * Default seed data for `workos dev` so the AuthKit login flow works\n * out of the box. Provides a test user, an organization with a verified\n * domain, and a membership linking the two. Skipped when the user\n * provides `--seed` or a `workos-emulate.config.*` file is auto-detected.\n */\nexport const DEFAULT_DEV_SEED: EmulatorSeedConfig = {\n  users: [\n    {\n      email: 'test@example.com',\n      first_name: 'Test',\n      last_name: 'User',\n      password: 'password',\n      email_verified: true,\n    },\n  ],\n  organizations: [\n    {\n      name: 'Test Organization',\n      domains: [{ domain: 'example.com', state: 'verified' }],\n    },\n  ],\n};\n\nexport function buildDevEnv(emulatorUrl: string, apiKey = 'sk_test_default'): Record<string, string> {\n  const url = new URL(emulatorUrl);\n  return {\n    WORKOS_API_BASE_URL: emulatorUrl,\n    WORKOS_API_HOSTNAME: url.hostname,\n    WORKOS_API_PORT: url.port,\n    WORKOS_API_HTTPS: 'false',\n    WORKOS_API_KEY: apiKey,\n    WORKOS_CLIENT_ID: 'client_emulated',\n  };\n}\n\nexport async function runDev(argv: DevArgs): Promise<void> {\n  const userSeed = argv.seed ? loadSeedFile(argv.seed) : autoDetectSeedFile();\n  const seedConfig = userSeed ?? DEFAULT_DEV_SEED;\n\n  // 1. Start emulator\n  const emulator = await createEmulator({\n    port: argv.port,\n    seed: seedConfig,\n  });\n\n  // 2. Resolve dev command\n  const explicit = argv['--'];\n  const devCmd =\n    explicit && explicit.length > 0\n      ? { command: explicit[0], args: explicit.slice(1), framework: null as string | null }\n      : await resolveDevCommand(process.cwd());\n\n  // 3. Print status banner\n  console.log();\n  console.log(`${chalk.cyan('WorkOS Emulate')} ${chalk.dim(emulator.url)}`);\n  if (devCmd.framework) {\n    console.log(chalk.dim(`Detected ${devCmd.framework}`));\n  }\n  console.log(chalk.dim(`Running: ${devCmd.command} ${devCmd.args.join(' ')}`));\n  if (!userSeed) {\n    console.log();\n    console.log(`  ${chalk.dim('Email:')}    test@example.com`);\n    console.log(`  ${chalk.dim('Password:')} password`);\n  }\n  console.log();\n\n  // 4. Spawn child process with env vars\n  let child: ChildProcess;\n  try {\n    child = spawn(devCmd.command, devCmd.args, {\n      stdio: 'inherit',\n      env: {\n        ...process.env,\n        ...buildDevEnv(emulator.url, emulator.apiKey),\n      },\n    });\n  } catch {\n    console.error(chalk.red(`Failed to start: ${devCmd.command} ${devCmd.args.join(' ')}`));\n    console.error(chalk.dim('Try specifying the command explicitly: workos dev -- <your-command>'));\n    await emulator.close();\n    process.exit(1);\n  }\n\n  child.on('error', async (err) => {\n    console.error(chalk.red(`Failed to start: ${devCmd.command}`));\n    if ((err as NodeJS.ErrnoException).code === 'ENOENT') {\n      console.error(chalk.dim(`Command not found: ${devCmd.command}`));\n      console.error(chalk.dim('Try specifying the command explicitly: workos dev -- <your-command>'));\n    } else {\n      console.error(chalk.dim(err.message));\n    }\n    await emulator.close();\n    process.exit(1);\n  });\n\n  // 5. Signal handling — forward to child, then close emulator\n  const shutdown = (signal: NodeJS.Signals) => {\n    child.kill(signal);\n    emulator.close().then(() => process.exit(0));\n  };\n  process.on('SIGINT', () => shutdown('SIGINT'));\n  process.on('SIGTERM', () => shutdown('SIGTERM'));\n\n  // 6. If child exits, close emulator and exit with same code\n  child.on('exit', (code) => {\n    emulator.close().then(() => process.exit(code ?? 0));\n  });\n}\n"]}

package/dist/commands/emulate.d.ts

@@ -0,0 +1,6 @@
+export interface EmulateArgs {
+    port: number;
+    seed?: string;
+    json?: boolean;
+}
+export declare function runEmulate(argv: EmulateArgs): Promise<void>;

package/dist/commands/emulate.js

@@ -0,0 +1,64 @@
+import { createEmulator } from '../emulate/index.js';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import chalk from 'chalk';
+function loadSeedFile(filePath) {
+    const resolved = resolve(filePath);
+    if (!existsSync(resolved)) {
+        console.error(`Seed file not found: ${resolved}`);
+        process.exit(1);
+    }
+    const content = readFileSync(resolved, 'utf-8');
+    if (resolved.endsWith('.json')) {
+        return JSON.parse(content);
+    }
+    return parseYaml(content);
+}
+function autoDetectSeedFile() {
+    const candidates = ['workos-emulate.config.yaml', 'workos-emulate.config.yml', 'workos-emulate.config.json'];
+    for (const name of candidates) {
+        const filePath = resolve(name);
+        if (existsSync(filePath)) {
+            return loadSeedFile(filePath);
+        }
+    }
+    return null;
+}
+function printBanner(emulator) {
+    console.log();
+    console.log(chalk.bold('  WorkOS Emulator'));
+    console.log();
+    console.log(`  ${chalk.dim('URL:')}      ${emulator.url}`);
+    console.log(`  ${chalk.dim('API Key:')}  ${emulator.apiKey}`);
+    console.log(`  ${chalk.dim('Health:')}   ${emulator.url}/health`);
+    console.log();
+    console.log(chalk.dim('  Press Ctrl+C to stop'));
+    console.log();
+}
+export async function runEmulate(argv) {
+    const seedConfig = argv.seed ? loadSeedFile(argv.seed) : autoDetectSeedFile();
+    const emulator = await createEmulator({
+        port: argv.port,
+        seed: seedConfig ?? undefined,
+    });
+    if (argv.json) {
+        console.log(JSON.stringify({
+            url: emulator.url,
+            port: emulator.port,
+            apiKey: emulator.apiKey,
+            health: `${emulator.url}/health`,
+        }));
+    }
+    else {
+        printBanner(emulator);
+    }
+    const shutdown = () => {
+        if (!argv.json)
+            console.log(`\n${chalk.dim('Shutting down...')}`);
+        emulator.close().then(() => process.exit(0));
+    };
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+}
+//# sourceMappingURL=emulate.js.map

package/dist/commands/emulate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emulate.js","sourceRoot":"","sources":["../../src/commands/emulate.ts"],"names":[],"mappings":"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","sourcesContent":["import { createEmulator, type EmulatorSeedConfig } from '../emulate/index.js';\nimport { readFileSync, existsSync } from 'node:fs';\nimport { resolve } from 'node:path';\nimport { parse as parseYaml } from 'yaml';\nimport chalk from 'chalk';\n\nexport interface EmulateArgs {\n  port: number;\n  seed?: string;\n  json?: boolean;\n}\n\nfunction loadSeedFile(filePath: string): EmulatorSeedConfig {\n  const resolved = resolve(filePath);\n  if (!existsSync(resolved)) {\n    console.error(`Seed file not found: ${resolved}`);\n    process.exit(1);\n  }\n\n  const content = readFileSync(resolved, 'utf-8');\n  if (resolved.endsWith('.json')) {\n    return JSON.parse(content) as EmulatorSeedConfig;\n  }\n  return parseYaml(content) as EmulatorSeedConfig;\n}\n\nfunction autoDetectSeedFile(): EmulatorSeedConfig | null {\n  const candidates = ['workos-emulate.config.yaml', 'workos-emulate.config.yml', 'workos-emulate.config.json'];\n\n  for (const name of candidates) {\n    const filePath = resolve(name);\n    if (existsSync(filePath)) {\n      return loadSeedFile(filePath);\n    }\n  }\n  return null;\n}\n\nfunction printBanner(emulator: { url: string; port: number; apiKey: string }): void {\n  console.log();\n  console.log(chalk.bold('  WorkOS Emulator'));\n  console.log();\n  console.log(`  ${chalk.dim('URL:')}      ${emulator.url}`);\n  console.log(`  ${chalk.dim('API Key:')}  ${emulator.apiKey}`);\n  console.log(`  ${chalk.dim('Health:')}   ${emulator.url}/health`);\n  console.log();\n  console.log(chalk.dim('  Press Ctrl+C to stop'));\n  console.log();\n}\n\nexport async function runEmulate(argv: EmulateArgs): Promise<void> {\n  const seedConfig = argv.seed ? loadSeedFile(argv.seed) : autoDetectSeedFile();\n\n  const emulator = await createEmulator({\n    port: argv.port,\n    seed: seedConfig ?? undefined,\n  });\n\n  if (argv.json) {\n    console.log(\n      JSON.stringify({\n        url: emulator.url,\n        port: emulator.port,\n        apiKey: emulator.apiKey,\n        health: `${emulator.url}/health`,\n      }),\n    );\n  } else {\n    printBanner(emulator);\n  }\n\n  const shutdown = () => {\n    if (!argv.json) console.log(`\\n${chalk.dim('Shutting down...')}`);\n    emulator.close().then(() => process.exit(0));\n  };\n  process.once('SIGINT', shutdown);\n  process.once('SIGTERM', shutdown);\n}\n"]}

package/dist/commands/seed.d.ts

@@ -1,4 +1,6 @@
+export declare function runSeedInit(): void;
 export declare function runSeed(options: {
     file?: string;
     clean?: boolean;
+    init?: boolean;
 }, apiKey: string, baseUrl?: string): Promise<void>;

package/dist/commands/seed.js

@@ -17,7 +17,66 @@ function loadState() {
 function saveState(state) {
     writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
 }
+const DEFAULT_SEED_FILE = 'workos-seed.yml';
+const SEED_TEMPLATE = `# WorkOS seed file — provision resources with \`workos seed --file=${DEFAULT_SEED_FILE}\`
+# Resources are created in dependency order: permissions → roles → organizations → config.
+# Existing resources are skipped (idempotent). Run \`workos seed --clean\` to tear down.
+
+permissions:
+  - name: Read Posts
+    slug: posts:read
+  - name: Write Posts
+    slug: posts:write
+    description: Create and edit posts
+
+roles:
+  - name: Admin
+    slug: admin
+    description: Full access
+    permissions:
+      - posts:read
+      - posts:write
+  - name: Viewer
+    slug: viewer
+    permissions:
+      - posts:read
+
+organizations:
+  - name: Acme Corp
+    domains:
+      - acme.com
+
+config:
+  redirect_uris:
+    - http://localhost:3000/auth/callback
+  cors_origins:
+    - http://localhost:3000
+  homepage_url: http://localhost:3000
+`;
+export function runSeedInit() {
+    if (existsSync(DEFAULT_SEED_FILE)) {
+        if (isJsonMode()) {
+            outputJson({ status: 'exists', message: `${DEFAULT_SEED_FILE} already exists`, file: DEFAULT_SEED_FILE });
+        }
+        else {
+            console.log(chalk.yellow(`${DEFAULT_SEED_FILE} already exists — not overwriting.`));
+        }
+        return;
+    }
+    writeFileSync(DEFAULT_SEED_FILE, SEED_TEMPLATE);
+    if (isJsonMode()) {
+        outputJson({ status: 'ok', message: `Created ${DEFAULT_SEED_FILE}`, file: DEFAULT_SEED_FILE });
+    }
+    else {
+        console.log(chalk.green(`Created ${DEFAULT_SEED_FILE}`));
+        console.log(chalk.dim('Edit the file, then run: workos seed --file=workos-seed.yml'));
+    }
+}
 export async function runSeed(options, apiKey, baseUrl) {
+    if (options.init) {
+        runSeedInit();
+        return;
+    }
     if (options.clean) {
         await runSeedClean(apiKey, baseUrl);
         return;
@@ -25,7 +84,7 @@ export async function runSeed(options, apiKey, baseUrl) {
     if (!options.file) {
         return exitWithError({
             code: 'missing_args',
-            message: 'Provide a seed file: workos seed --file=workos-seed.yml',
+            message: 'Provide a seed file: workos seed --file=workos-seed.yml\nRun workos seed --init to create an example seed file.',
         });
     }
     if (!existsSync(options.file)) {