@mettlecast/domain-cli 0.2.0

package/src/cli.ts

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { runBuild } from './commands/build.js';
+import { runValidate } from './commands/validate.js';
+import { runTest } from './commands/test.js';
+import { runDev } from './commands/dev.js';
+import { runBuildCatalog } from './commands/build-catalog.js';
+import { runAddDomain } from './commands/add-domain.js';
+import { runAddApi, API_PATTERNS } from './commands/add-api.js';
+import { runAddSubscriber, SUBSCRIBER_PATTERNS } from './commands/add-subscriber.js';
+import { runAddFlow, FLOW_PATTERNS } from './commands/add-flow.js';
+import { runAddModule } from './commands/add-module.js';
+import { runBuildFlows } from './commands/build-flows.js';
+import { runDoctor } from './commands/doctor.js';
+import { runCheckHashes } from './commands/check-hashes.js';
+import { runUpgradeBackend } from './commands/upgrade-backend.js';
+import { runAddPage } from './commands/add-page.js';
+import { runCreateProject } from './commands/create-project.js';
+import { runUpgradeFrontend } from './commands/upgrade-frontend.js';
+import { runUpgrade } from './commands/upgrade.js';
+import { runAddMigration, MIGRATION_PATTERNS } from './commands/add-migration.js';
+import { runAddTest } from './commands/add-test.js';
+import { runUpgradeEvent } from './commands/upgrade-event.js';
+import { runShowDomainCli } from './commands/show.js';
+import { runAuditCli } from './commands/audit.js';
+import { runExplainCli } from './commands/explain.js';
+import { runAddHook, type HookPattern, HOOK_PATTERNS } from './commands/add-hook.js';
+import { runAddComponent, type ComponentTier, COMPONENT_TIERS } from './commands/add-component.js';
+import { runPowerTune } from './commands/power-tune.js';
+import { runReseedPage } from './commands/reseed-page.js';
+import { runAddSeedPage } from './commands/add-seed-page.js';
+import { runShowDns } from './commands/show-dns.js';
+
+/**
+ * Root CLI program for the TIB Domain Module local developer toolchain.
+ * Provides build, validate, test, dev, add-domain, add-api, and add-subscriber subcommands.
+ */
+const program = new Command();
+
+program
+  .name('mc-domain-module')
+  .description('TIB Domain Module local developer toolchain')
+  .version('0.1.0');
+
+program
+  .command('build <domain>')
+  .description('Build the DomainRegistry from source and write .mc/domain-registry.json')
+  .option('--out <path>', 'Override the output file path')
+  .action(async (domain: string, opts: { out?: string }) => {
+    await runBuild({ domainRoot: domain, outFile: opts.out });
+  });
+
+program
+  .command('validate <domain>')
+  .description('Build the registry and validate structure (CI gate — exits 1 on failure)')
+  .action(async (domain: string) => {
+    await runValidate(domain, true);
+  });
+
+program
+  .command('test <domain> <handler-id>')
+  .description('Invoke a handler with fixture data and print the result')
+  .requiredOption('--fixture <path>', 'Path to fixture JSON file ({ event, ctx? })')
+  .action(async (domain: string, handlerId: string, opts: { fixture: string }) => {
+    await runTest({ domainRoot: domain, handlerId, fixturePath: opts.fixture });
+  });
+
+program
+  .command('dev <domain>')
+  .description('Start a local HTTP server simulating API Gateway for all defineApi handlers')
+  .option('--port <n>', 'Port to listen on', '3000')
+  .action(async (domain: string, opts: { port?: string }) => {
+    await runDev({ domainRoot: domain, port: opts.port ? parseInt(opts.port, 10) : 3000 });
+  });
+
+program
+  .command('build-catalog')
+  .description('Merge all per-domain registry files into .mc/domain-registry.json for TIB sync')
+  .option('--tib-dir <path>', 'Path to the .tib directory (defaults to .tib in cwd)')
+  .action(async (opts: { tibDir?: string }) => {
+    await runBuildCatalog(opts.tibDir);
+  });
+
+program
+  .command('add-domain <id>')
+  .description(
+    'Scaffold a new domain under domains/<id> and register it in .mc/scaffold-config.json'
+  )
+  .option('--tenancy <mode>', 'Tenancy mode (required|none|system)', 'required')
+  .action(async (id: string, opts: { tenancy: 'required' | 'none' | 'system' }) => {
+    await runAddDomain({ id, tenancy: opts.tenancy });
+  });
+
+program
+  .command('add-api <domain> <id>')
+  .description('Add a new API primitive to an existing domain')
+  .option('--method <method>', 'HTTP method', 'GET')
+  .option('--tenancy <mode>', 'Tenancy mode', 'required')
+  .option('--pattern <pattern>', `Pattern template: ${API_PATTERNS.join(' | ')}`)
+  .action(
+    async (
+      domain: string,
+      id: string,
+      opts: { method: string; tenancy: 'required' | 'none' | 'system'; pattern?: string }
+    ) => {
+      await runAddApi({
+        domain,
+        id,
+        method: opts.method,
+        tenancy: opts.tenancy,
+        pattern: opts.pattern as typeof API_PATTERNS[number] | undefined,
+      });
+    }
+  );
+
+program
+  .command('add-subscriber <domain> <id>')
+  .description('Add a new event subscriber to an existing domain')
+  .requiredOption('--event <eventId>', 'Event id to subscribe to')
+  .action(async (domain: string, id: string, opts: { event: string }) => {
+    await runAddSubscriber({ domain, id, event: opts.event });
+  });
+
+program
+  .command('add-flow <domain> <id>')
+  .description('Scaffold a new flow under domains/<domain>/flows/<id>.ts')
+  .option('--type <type>', 'Flow type: express (default) or standard', 'express')
+  .action(async (domain: string, id: string, opts: { type: string }) => {
+    await runAddFlow({ domain, id, type: opts.type as 'express' | 'standard' });
+  });
+
+program
+  .command('add-module <module>')
+  .description('Install a scaffold module from S3 at the project\'s pinned scaffold version and raise a PR')
+  .option('--github-token <token>', 'GitHub token for PR creation (overrides GITHUB_TOKEN env var)')
+  .option('--dry-run', 'Show what would be installed without making changes', false)
+  .action(async (module: string, opts: { githubToken?: string; dryRun: boolean }) => {
+    await runAddModule({ moduleId: module, githubToken: opts.githubToken, dryRun: opts.dryRun });
+  });
+
+program
+  .command('build-flows')
+  .description('Build all flows into .mc/flows-registry.json')
+  .option('--out <path>', 'Override the output file path')
+  .action(async (opts: { out?: string }) => {
+    await runBuildFlows({ outFile: opts.out });
+  });
+
+program
+  .command('doctor')
+  .description('Run all structural checks for the current TIB project (strict by default — any FAIL causes exit code 1)')
+  .option('--strict', 'DEPRECATED: Doctor is always strict now. This flag is a no-op.', false)
+  .option('--json', 'Output JSON instead of pretty table', false)
+  .action(async (opts: { strict: boolean; json: boolean }) => {
+    if (opts.strict) {
+      // eslint-disable-next-line no-console
+      console.warn('⚠  --strict is deprecated: doctor is always strict now. This flag is a no-op.');
+    }
+    const report = await runDoctor({ projectRoot: process.cwd() });
+    if (opts.json) {
+      // eslint-disable-next-line no-console
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      // Pretty-print table
+      // eslint-disable-next-line no-console
+      console.log('\n=== TIB Project Health Check ===\n');
+      for (const check of report.checks) {
+        const symbol = check.status === 'PASS' ? '✓' : check.status === 'WARN' ? '⚠' : '✗';
+        // eslint-disable-next-line no-console
+        console.log(`${symbol} ${check.name}: ${check.message}`);
+        if (check.fixHint) {
+          // eslint-disable-next-line no-console
+          console.log(`  Fix: ${check.fixHint}`);
+        }
+      }
+      // eslint-disable-next-line no-console
+      console.log(`\nExit code: ${report.exitCode}\n`);
+    }
+    process.exit(report.exitCode);
+  });
+
+program
+  .command('check-hashes')
+  .description('Verify infra/modules/ has not been hand-edited since last scaffold')
+  .action(async () => {
+    const result = await runCheckHashes({});
+    process.exit(result.ok ? 0 : 1);
+  });
+
+program
+  .command('upgrade-backend <target-major>')
+  .description('Run jscodeshift/ts-morph migrations between major versions of domain-runtime')
+  .option('--repo-root <path>', 'Root of the repo (defaults to cwd)')
+  .option('--dry-run', 'Print changes without applying', false)
+  .action(async (targetMajor: string, opts: { repoRoot?: string; dryRun: boolean }) => {
+    await runUpgradeBackend({ targetMajor, repoRoot: opts.repoRoot, dryRun: opts.dryRun });
+  });
+
+program
+  .command('add-page <pageId>')
+  .description('Scaffold a seed page from the dashboard-pages template registry')
+  .option('--output <dir>', 'Override the output directory (default: src/pages/<category>)')
+  .option('--pattern <pattern>', 'Scaffold with a page pattern template (list, detail, form, wizard, dashboard, settings)')
+  .option('--layout <layout>', 'Layout to use: app (default) or auth', 'app')
+  .option('--auth', 'Scaffold with auth guard wiring (login-redirect on unauthenticated)')
+  .option('--protected', 'Add requireAuth() loader to the route')
+  .option('--public', 'No auth guard (public page)')
+  .action(async (pageId: string, opts: { output?: string; pattern?: string; layout: string; auth?: boolean; protected?: boolean; public?: boolean }) => {
+    // Validate pattern early to give a clear error before the inner command
+    if (opts.pattern && !['list', 'detail', 'form', 'wizard', 'dashboard', 'settings'].includes(opts.pattern)) {
+      throw new Error(
+        `Unknown page pattern "${opts.pattern}". Available patterns: list, detail, form, wizard, dashboard, settings`
+      );
+    }
+    if (!['app', 'auth'].includes(opts.layout)) {
+      throw new Error(
+        `Unknown layout "${opts.layout}". Available layouts: app, auth`
+      );
+    }
+    await runAddPage({
+      pageId,
+      outputDir: opts.output,
+      pattern: opts.pattern as import('./commands/add-page.js').AddPageOptions['pattern'],
+      layout: opts.layout as 'app' | 'auth',
+      auth: opts.auth,
+      protected: opts.protected,
+      public: opts.public,
+    });
+  });
+
+program
+  .command('add-hook <name>')
+  .description('Scaffold a typed data-fetching hook (TanStack Query + @mettlecast/sdk)')
+  .option('--pattern <pattern>', 'Hook pattern', 'paginated-list')
+  .option('--output <dir>', 'Override the output directory (default: src/hooks/)')
+  .action(async (name: string, opts: { pattern: string; output?: string }) => {
+    if (!HOOK_PATTERNS.includes(opts.pattern as HookPattern)) {
+      throw new Error(
+        `Unknown hook pattern "${opts.pattern}". Available patterns: ${HOOK_PATTERNS.join(', ')}`
+      );
+    }
+    await runAddHook({
+      name,
+      pattern: opts.pattern as HookPattern,
+      outputDir: opts.output,
+    });
+  });
+
+program
+  .command('add-component <name>')
+  .description('Scaffold a design-system component with Storybook story and a11y check')
+  .option('--pattern <tier>', 'Component tier: atom, molecule, or organism', 'atom')
+  .option('--output <dir>', 'Override the output directory (default: src/components/)')
+  .action(async (name: string, opts: { pattern: string; output?: string }) => {
+    if (!COMPONENT_TIERS.includes(opts.pattern as ComponentTier)) {
+      throw new Error(
+        `Unknown component tier "${opts.pattern}". Available tiers: ${COMPONENT_TIERS.join(', ')}`
+      );
+    }
+    await runAddComponent({
+      name,
+      tier: opts.pattern as ComponentTier,
+      outputDir: opts.output,
+    });
+  });
+
+program
+  .command('create-project <name>')
+  .description('Initialise a new TIB frontend project with seed pages and router wiring')
+  .option('--out <dir>', 'Parent directory for the new project (default: current directory)')
+  .action(async (name: string, opts: { out?: string }) => {
+    await runCreateProject({ name, outDir: opts.out });
+  });
+
+program
+  .command('upgrade-frontend')
+  .description('Check @mettlecast/* frontend package versions and report missing/outdated packages')
+  .option('--dry-run', 'Report issues without making changes', false)
+  .option('--project-dir <path>', 'Path to the project to check (default: current directory)')
+  .action(async (opts: { dryRun: boolean; projectDir?: string }) => {
+    await runUpgradeFrontend({ dryRun: opts.dryRun, projectDir: opts.projectDir });
+  });
+
+program
+  .command('upgrade [version]')
+  .description('Upgrade scaffold to a new version — diffs S3 tarballs, raises a GitHub PR with exact file changes')
+  .option('--dry-run', 'Preview changes without writing files or creating PR', false)
+  .option('--project-dir <path>', 'Path to the project to upgrade')
+  .option('--github-token <token>', 'GitHub token for PR creation (overrides GITHUB_TOKEN env var)')
+  .option('--frontend-components', 'Scope upgrade to scaffold-tracked frontend files only (opens a PR with Chromatic visual diff)', false)
+  .action(async (version: string | undefined, opts: { dryRun: boolean; projectDir?: string; githubToken?: string; frontendComponents: boolean }) => {
+    await runUpgrade(version, { dryRun: opts.dryRun, projectDir: opts.projectDir ?? process.cwd(), githubToken: opts.githubToken, frontendComponents: opts.frontendComponents });
+  });
+
+// ── New W4 commands ───────────────────────────────────────────────
+
+program
+  .command('add-migration <domain> <name>')
+  .description('Add a new database migration to an existing domain')
+  .requiredOption('--pattern <pattern>', `Migration pattern: ${MIGRATION_PATTERNS.join(' | ')}`)
+  .action(async (domain: string, name: string, opts: { pattern: string }) => {
+    await runAddMigration({
+      domain,
+      name,
+      pattern: opts.pattern as typeof MIGRATION_PATTERNS[number],
+    });
+  });
+
+program
+  .command('add-test <domain> <primitive-id>')
+  .description('Scaffold a vitest fixture for an existing domain primitive')
+  .action(async (domain: string, primitiveId: string) => {
+    await runAddTest({ domain, primitiveId });
+  });
+
+program
+  .command('upgrade-event <domain> <event-id>')
+  .description('Bump an event definition to a new version with sunset semantics')
+  .requiredOption('--to-version <N>', 'Target version number (integer >= 2)', parseInt)
+  .action(async (domain: string, eventId: string, opts: { toVersion: number }) => {
+    await runUpgradeEvent({ domain, eventId, toVersion: opts.toVersion });
+  });
+
+program
+  .command('show domain <domain>')
+  .description('Show a structured JSON summary of a domain')
+  .action(async (domain: string) => {
+    await runShowDomainCli({ domain });
+  });
+
+program
+  .command('audit [domain]')
+  .description('Run structural audit checks, optionally filtered to one domain')
+  .option('--json', 'Output structured JSON', false)
+  .action(async (domain: string | undefined, opts: { json: boolean }) => {
+    await runAuditCli({ domain, json: opts.json });
+  });
+
+program
+  .command('explain <rule-id>')
+  .description('Explain a rule ID with description, examples, and K-node reference')
+  .action(async (ruleId: string) => {
+    runExplainCli({ ruleId });
+  });
+
+program
+  .command('power-tune <domain> <primitive>')
+  .description('Run AWS Lambda Power Tuning on a deployed Lambda. Returns recommended memorySize.')
+  .option('--strategy <strategy>', 'Optimization strategy: cost, speed, or balanced', 'cost')
+  .action(async (domain: string, primitive: string) => {
+    await runPowerTune(domain, primitive);
+  });
+
+program
+  .command('reseed-page [name]')
+  .description('Force-reseed a seed page (or all seed pages) with the latest scaffold version. Opens a [DESTRUCTIVE] PR.')
+  .option('--all', 'Reseed all seed pages in bulk (single PR)', false)
+  .option('--project-dir <path>', 'Path to the project to reseed')
+  .action(async (name: string | undefined, opts: { all: boolean; projectDir?: string }) => {
+    if (!name && !opts.all) {
+      throw new Error('Provide a page name or use --all to reseed all seed pages');
+    }
+    await runReseedPage({ pageName: name, all: opts.all, projectDir: opts.projectDir });
+  });
+
+program
+  .command('add-seed-page <name>')
+  .description('Add a seed page from the scaffold library. The page is yours immediately — TIB will never auto-update it.')
+  .option('--project-dir <path>', 'Path to the project')
+  .action(async (name: string, opts: { projectDir?: string }) => {
+    await runAddSeedPage({ pageName: name, projectDir: opts.projectDir });
+  });
+
+program
+  .command('show-dns')
+  .description('Print DNS records (zone-file format) needed to activate custom domains')
+  .option('--env <env>', 'Filter to a single environment (dev|staging|prod)')
+  .option('--project-dir <path>', 'Path to the project root (defaults to cwd)')
+  .action(async (opts: { env?: string; projectDir?: string }) => {
+    await runShowDns(opts);
+  });
+
+program.parseAsync(process.argv).catch((err: unknown) => {
+  // eslint-disable-next-line no-console
+  console.error(err);
+  process.exit(1);
+});

package/src/commands/add-api.ts

@@ -0,0 +1,145 @@
+/**
+ * Command to add a new API to an existing domain.
+ * Supports --pattern to scaffold from predefined templates.
+ */
+
+import { writeFile, access, mkdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { apiSkeletonTemplate, apiFixtureSkeleton } from '../templates/api-skeleton.js';
+import { simpleCrudTemplate, simpleCrudListTemplate } from '../templates/patterns/api/simple-crud.js';
+import { paginatedListTemplate } from '../templates/patterns/api/paginated-list.js';
+import { createWithEventTemplate } from '../templates/patterns/api/create-with-event.js';
+import { idempotentMutationTemplate } from '../templates/patterns/api/idempotent-mutation.js';
+import { webhookReceiverStyleTemplate } from '../templates/patterns/api/webhook-receiver-style.js';
+import { systemAdminTemplate } from '../templates/patterns/api/system-admin.js';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Valid API pattern IDs.
+ */
+export const API_PATTERNS = [
+  'simple-crud',
+  'paginated-list',
+  'create-with-event',
+  'idempotent-mutation',
+  'webhook-receiver-style',
+  'system-admin',
+] as const;
+
+export type ApiPattern = (typeof API_PATTERNS)[number];
+
+/**
+ * Options for the add-api command.
+ */
+export interface AddApiOptions {
+  /** Domain ID in kebab-case. */
+  domain: string;
+  /** API ID in kebab-case. */
+  id: string;
+  /** HTTP method (defaults to GET). */
+  method?: string;
+  /** Tenancy mode: 'required', 'none', or 'system'. */
+  tenancy: 'required' | 'none' | 'system';
+  /** Pattern template ID (optional — when provided, uses pattern instead of skeleton). */
+  pattern?: ApiPattern;
+  /** Override directory for domain root (used in tests). */
+  domainsDir?: string;
+}
+
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Execute the add-api command: create a new API handler in an existing domain.
+ * @param opts - AddApiOptions specifying domain, API ID, and tenancy.
+ * @throws If domain does not exist, API ID is invalid, or file already exists.
+ */
+export async function runAddApi(opts: AddApiOptions): Promise<void> {
+  if (!KEBAB_REGEX.test(opts.id)) {
+    throw new Error(`Invalid API id "${opts.id}" — must be kebab-case`);
+  }
+
+  if (!KEBAB_REGEX.test(opts.domain)) {
+    throw new Error(`Invalid domain id "${opts.domain}" — must be kebab-case`);
+  }
+
+  const root = opts.domainsDir ?? resolve(process.cwd(), 'domains');
+  const domainDir = join(root, opts.domain);
+  const domainConfigPath = join(domainDir, 'domain.config.ts');
+
+  // Verify domain exists
+  try {
+    await access(domainConfigPath);
+  } catch {
+    throw new Error(`Domain "${opts.domain}" not found at ${domainDir}`);
+  }
+
+  const apiFilePath = join(domainDir, 'api', `${opts.id}.ts`);
+
+  // Refuse if API already exists
+  try {
+    await access(apiFilePath);
+    throw new Error(`API "${opts.id}" already exists at ${apiFilePath}`);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw err;
+    }
+  }
+
+  // Resolve template content
+  let apiContent: string;
+  if (opts.pattern) {
+    apiContent = resolveApiPattern(opts.pattern, opts.domain, opts.id, opts.tenancy);
+    cliLogger.info({ pattern: opts.pattern }, 'Using pattern template');
+  } else {
+    apiContent = apiSkeletonTemplate(opts.domain, opts.id, opts.tenancy);
+  }
+
+  // Write API file
+  await writeFile(apiFilePath, apiContent);
+
+  // Create fixture
+  const apiTestDir = join(domainDir, 'api', '__tests__');
+  await mkdir(apiTestDir, { recursive: true });
+  await writeFile(
+    join(apiTestDir, `${opts.id}.fixture.json`),
+    apiFixtureSkeleton(opts.domain, opts.id)
+  );
+
+  cliLogger.info({ domain: opts.domain, api: opts.id, method: opts.method ?? 'GET', pattern: opts.pattern ?? 'skeleton' }, 'API added');
+  // eslint-disable-next-line no-console
+  console.log(`\n✓ API "${opts.id}" added to domain "${opts.domain}" at ${apiFilePath}`);
+}
+
+/**
+ * Resolve a pattern template to its generated TypeScript source.
+ * @param pattern - The pattern ID.
+ * @param domain - Domain ID.
+ * @param id - API ID.
+ * @param tenancy - Tenancy mode.
+ * @returns TypeScript source code as a string.
+ */
+function resolveApiPattern(
+  pattern: ApiPattern,
+  domain: string,
+  id: string,
+  tenancy: string,
+): string {
+  switch (pattern) {
+    case 'simple-crud':
+      return simpleCrudTemplate(domain, id, tenancy) +
+        '\n' +
+        simpleCrudListTemplate(domain, id, tenancy);
+    case 'paginated-list':
+      return paginatedListTemplate(domain, id, tenancy);
+    case 'create-with-event':
+      return createWithEventTemplate(domain, id, tenancy);
+    case 'idempotent-mutation':
+      return idempotentMutationTemplate(domain, id, tenancy);
+    case 'webhook-receiver-style':
+      return webhookReceiverStyleTemplate(domain, id, tenancy);
+    case 'system-admin':
+      return systemAdminTemplate(domain, id, tenancy);
+    default:
+      throw new Error(`Unknown API pattern "${pattern}". Available: ${API_PATTERNS.join(', ')}`);
+  }
+}

package/src/commands/add-component.ts

@@ -0,0 +1,116 @@
+/**
+ * Command: tib add-component <name> --pattern <tier>
+ *
+ * Scaffolds a design-system component with Storybook story and a11y check.
+ *
+ * Tiers:
+ *   - atom:     Single design token usage (Button, Input, Icon).
+ *   - molecule: Composition of 2+ atoms (SearchBar, FormField, DataRow).
+ *   - organism: Complex section (DataTable, WizardFlow, DashboardWidget).
+ */
+import { writeFile, mkdir, access } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+import {
+  atomTemplate,
+  moleculeTemplate,
+  organismTemplate,
+} from '../templates/patterns/component/index.js';
+
+/** Supported component tiers. */
+export type ComponentTier = 'atom' | 'molecule' | 'organism';
+
+export const COMPONENT_TIERS: readonly ComponentTier[] = [
+  'atom',
+  'molecule',
+  'organism',
+] as const;
+
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+
+const TIER_TEMPLATES: Record<
+  ComponentTier,
+  (name: string) => { component: string; story: string; test: string }
+> = {
+  atom: atomTemplate,
+  molecule: moleculeTemplate,
+  organism: organismTemplate,
+};
+
+export interface AddComponentOptions {
+  /** Component name in kebab-case (e.g. "action-button"). */
+  name: string;
+  /** Component tier / pattern. */
+  tier: ComponentTier;
+  /** Override the output base directory (default: src/components/). */
+  outputDir?: string;
+}
+
+/**
+ * Scaffold a design-system component with story + test files.
+ */
+export async function runAddComponent(opts: AddComponentOptions): Promise<void> {
+  const { name, tier, outputDir } = opts;
+
+  if (!KEBAB_REGEX.test(name)) {
+    throw new Error(`Invalid component name "${name}" — must be kebab-case`);
+  }
+
+  if (!COMPONENT_TIERS.includes(tier)) {
+    const available = COMPONENT_TIERS.join(', ');
+    throw new Error(
+      `Unknown component tier "${tier}".\n\nAvailable tiers: ${available}`
+    );
+  }
+
+  const templateFn = TIER_TEMPLATES[tier];
+  const { component, story, test } = templateFn(name);
+
+  const baseDir = outputDir
+    ? resolve(outputDir)
+    : resolve(process.cwd(), 'src', 'components');
+
+  const compDir = join(baseDir, name);
+
+  const files: Array<{ name: string; content: string }> = [
+    { name: `${name}.tsx`, content: component },
+    { name: `${name}.stories.tsx`, content: story },
+    { name: `${name}.test.tsx`, content: test },
+  ];
+
+  // Check for existing component directory first
+  try {
+    await access(compDir);
+    throw new Error(
+      `Component directory already exists at ${compDir}. Remove it first or use a different --output directory.`
+    );
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+  }
+
+  await mkdir(compDir, { recursive: true });
+
+  for (const file of files) {
+    const outPath = join(compDir, file.name);
+    await writeFile(outPath, file.content, 'utf8');
+  }
+
+  cliLogger.info({ name, tier, compDir }, 'Component scaffolded');
+  // eslint-disable-next-line no-console
+  console.log(
+    `\n✓ Component "${name}" (tier: ${tier}) added in ${compDir}/\n` +
+    `  ${name}.tsx          — component implementation\n` +
+    `  ${name}.stories.tsx  — Storybook story (2+ variants)\n` +
+    `  ${name}.test.tsx     — Playwright smoke test + a11y check\n` +
+    `\n` +
+    `  Import: import { ${capitalize(name)} } from './components/${name}/${name}';\n`
+  );
+}
+
+/** Capitalizes the first character of a kebab-case name into PascalCase. */
+function capitalize(s: string): string {
+  return s
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}