@mettlecast/domain-cli 0.2.0

package/dist/cli.js

@@ -0,0 +1,338 @@
+#!/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 } from './commands/add-subscriber.js';
+import { runAddFlow } 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, HOOK_PATTERNS } from './commands/add-hook.js';
+import { runAddComponent, 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, opts) => {
+    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) => {
+    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, handlerId, opts) => {
+    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, opts) => {
+    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) => {
+    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, opts) => {
+    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, id, opts) => {
+    await runAddApi({
+        domain,
+        id,
+        method: opts.method,
+        tenancy: opts.tenancy,
+        pattern: opts.pattern,
+    });
+});
+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, id, opts) => {
+    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, id, opts) => {
+    await runAddFlow({ domain, id, type: opts.type });
+});
+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, opts) => {
+    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) => {
+    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) => {
+    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, opts) => {
+    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, opts) => {
+    // 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,
+        layout: opts.layout,
+        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, opts) => {
+    if (!HOOK_PATTERNS.includes(opts.pattern)) {
+        throw new Error(`Unknown hook pattern "${opts.pattern}". Available patterns: ${HOOK_PATTERNS.join(', ')}`);
+    }
+    await runAddHook({
+        name,
+        pattern: opts.pattern,
+        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, opts) => {
+    if (!COMPONENT_TIERS.includes(opts.pattern)) {
+        throw new Error(`Unknown component tier "${opts.pattern}". Available tiers: ${COMPONENT_TIERS.join(', ')}`);
+    }
+    await runAddComponent({
+        name,
+        tier: opts.pattern,
+        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, opts) => {
+    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) => {
+    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, opts) => {
+    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, name, opts) => {
+    await runAddMigration({
+        domain,
+        name,
+        pattern: opts.pattern,
+    });
+});
+program
+    .command('add-test <domain> <primitive-id>')
+    .description('Scaffold a vitest fixture for an existing domain primitive')
+    .action(async (domain, primitiveId) => {
+    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, eventId, opts) => {
+    await runUpgradeEvent({ domain, eventId, toVersion: opts.toVersion });
+});
+program
+    .command('show domain <domain>')
+    .description('Show a structured JSON summary of a domain')
+    .action(async (domain) => {
+    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, opts) => {
+    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) => {
+    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, primitive) => {
+    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, opts) => {
+    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, opts) => {
+    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) => {
+    await runShowDns(opts);
+});
+program.parseAsync(process.argv).catch((err) => {
+    // eslint-disable-next-line no-console
+    console.error(err);
+    process.exit(1);
+});

package/dist/commands/add-api.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Command to add a new API to an existing domain.
+ * Supports --pattern to scaffold from predefined templates.
+ */
+/**
+ * Valid API pattern IDs.
+ */
+export declare const API_PATTERNS: readonly ["simple-crud", "paginated-list", "create-with-event", "idempotent-mutation", "webhook-receiver-style", "system-admin"];
+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;
+}
+/**
+ * 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 declare function runAddApi(opts: AddApiOptions): Promise<void>;

package/dist/commands/add-api.js

@@ -0,0 +1,106 @@
+/**
+ * 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',
+];
+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) {
+    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.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+    // Resolve template content
+    let apiContent;
+    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, domain, id, tenancy) {
+    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/dist/commands/add-component.d.ts

@@ -0,0 +1,15 @@
+/** Supported component tiers. */
+export type ComponentTier = 'atom' | 'molecule' | 'organism';
+export declare const COMPONENT_TIERS: readonly ComponentTier[];
+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 declare function runAddComponent(opts: AddComponentOptions): Promise<void>;

package/dist/commands/add-component.js

@@ -0,0 +1,78 @@
+/**
+ * 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';
+export const COMPONENT_TIERS = [
+    'atom',
+    'molecule',
+    'organism',
+];
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+const TIER_TEMPLATES = {
+    atom: atomTemplate,
+    molecule: moleculeTemplate,
+    organism: organismTemplate,
+};
+/**
+ * Scaffold a design-system component with story + test files.
+ */
+export async function runAddComponent(opts) {
+    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 = [
+        { 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.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) {
+    return s
+        .split('-')
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}

package/dist/commands/add-domain.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Command to scaffold a new domain skeleton.
+ */
+/**
+ * Options for the add-domain command.
+ */
+export interface AddDomainOptions {
+    /** Domain ID in kebab-case. */
+    id: string;
+    /** Tenancy mode: 'required', 'none', or 'system'. */
+    tenancy: 'required' | 'none' | 'system';
+    /** Override directory for domain root (used in tests). */
+    domainsDir?: string;
+}
+/**
+ * Execute the add-domain command: scaffold a new domain under domains/<id>
+ * and register it in .mc/scaffold-config.json.
+ * @param opts - AddDomainOptions specifying the domain ID and tenancy mode.
+ * @throws If domain ID is invalid, domain already exists, or file operations fail.
+ */
+export declare function runAddDomain(opts: AddDomainOptions): Promise<void>;

package/dist/commands/add-domain.js

@@ -0,0 +1,71 @@
+/**
+ * Command to scaffold a new domain skeleton.
+ */
+import { mkdir, writeFile, access, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { domainConfigTemplate } from '../templates/domain-config.js';
+import { apiSkeletonTemplate, apiFixtureSkeleton } from '../templates/api-skeleton.js';
+import { eventsSkeletonTemplate } from '../templates/events-skeleton.js';
+import { claudeMdTemplate } from '../templates/claude-md.js';
+import { readmeTemplate } from '../templates/readme.js';
+import { addDomainToScaffoldConfig } from '../utils/scaffold-config.js';
+import { cliLogger } from '../utils/logger.js';
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+/**
+ * Execute the add-domain command: scaffold a new domain under domains/<id>
+ * and register it in .mc/scaffold-config.json.
+ * @param opts - AddDomainOptions specifying the domain ID and tenancy mode.
+ * @throws If domain ID is invalid, domain already exists, or file operations fail.
+ */
+export async function runAddDomain(opts) {
+    if (!KEBAB_REGEX.test(opts.id)) {
+        throw new Error(`Invalid domain id "${opts.id}" — must be kebab-case (lowercase with hyphens)`);
+    }
+    const root = opts.domainsDir ?? resolve(process.cwd(), 'domains');
+    const domainDir = join(root, opts.id);
+    // Refuse if domain already exists
+    try {
+        await access(domainDir);
+        throw new Error(`Domain "${opts.id}" already exists at ${domainDir}`);
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+    // Create directory structure
+    await mkdir(join(domainDir, 'api', '__tests__'), { recursive: true });
+    await mkdir(join(domainDir, 'subscribers'), { recursive: true });
+    await mkdir(join(domainDir, 'publishes'), { recursive: true });
+    // Write skeleton files
+    await writeFile(join(domainDir, 'domain.config.ts'), domainConfigTemplate(opts.id, opts.tenancy));
+    await writeFile(join(domainDir, 'api', 'example.ts'), apiSkeletonTemplate(opts.id, 'example', opts.tenancy));
+    await writeFile(join(domainDir, 'api', '__tests__', 'example.fixture.json'), apiFixtureSkeleton(opts.id, 'example'));
+    await writeFile(join(domainDir, 'publishes', 'events.ts'), eventsSkeletonTemplate(opts.id));
+    await writeFile(join(domainDir, 'CLAUDE.md'), claudeMdTemplate(opts.id));
+    await writeFile(join(domainDir, 'README.md'), readmeTemplate(opts.id));
+    // Generate package.json for L1 graph scanner auto-detection
+    let projectScope = 'project';
+    try {
+        const pkgRaw = await readFile(join(resolve(opts.domainsDir ?? process.cwd(), '..'), 'package.json'), 'utf8');
+        const rootPkg = JSON.parse(pkgRaw);
+        if (rootPkg.name) {
+            const match = /^@([^/]+)/.exec(rootPkg.name);
+            projectScope = match ? match[1] : rootPkg.name;
+        }
+    }
+    catch { /* fall back to 'project' */ }
+    await writeFile(join(domainDir, 'package.json'), JSON.stringify({
+        name: `@${projectScope}/domain-${opts.id}`,
+        version: '0.1.0',
+        private: true,
+        description: `Domain module for ${opts.id}`,
+    }, null, 2) + '\n');
+    // Register domain in scaffold config
+    const configRoot = opts.domainsDir ?? process.cwd();
+    await addDomainToScaffoldConfig(opts.id, configRoot);
+    cliLogger.info({ id: opts.id, dir: domainDir }, 'Domain scaffolded');
+    // eslint-disable-next-line no-console
+    console.log(`\n✓ Domain "${opts.id}" added at ${domainDir}\nNext: edit api/example.ts, ` +
+        `then run \`mc-domain-module build ${opts.id}\` to generate the registry.`);
+}