@mettlecast/domain-cli 0.2.0

package/dist/commands/explain.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Command to explain a rule ID (ESLint rule name or doctor check name).
+ * Maps rule IDs to descriptions and K-node references.
+ */
+/**
+ * Options for the explain command.
+ */
+export interface ExplainOptions {
+    /** The rule ID to explain (e.g., 'no-cross-domain-internal-import'). */
+    ruleId: string;
+}
+/**
+ * A rule explanation entry.
+ */
+interface RuleExplanation {
+    ruleId: string;
+    title: string;
+    description: string;
+    severity: 'error' | 'warn';
+    category: 'convention' | 'security' | 'structure' | 'performance' | 'correctness';
+    kNodeRef: string;
+    fixHint: string;
+    exampleBad: string;
+    exampleGood: string;
+}
+/**
+ * Execute the explain command: look up a rule ID and print its explanation.
+ */
+export declare function runExplain(opts: ExplainOptions): RuleExplanation;
+/**
+ * CLI entry point: prints the explanation in a human-readable format.
+ */
+export declare function runExplainCli(opts: ExplainOptions): void;
+export {};

package/dist/commands/explain.js

@@ -0,0 +1,167 @@
+/**
+ * Command to explain a rule ID (ESLint rule name or doctor check name).
+ * Maps rule IDs to descriptions and K-node references.
+ */
+/**
+ * Lookup table of rule IDs to explanations.
+ */
+const RULE_EXPLANATIONS = {
+    'no-cross-domain-internal-import': {
+        ruleId: 'no-cross-domain-internal-import',
+        title: 'No cross-domain internal imports',
+        description: 'Domain code must never import from another domain directly. Cross-domain communication must use actions (ctx.actions.call), events (ctx.publish), or defined integrations.',
+        severity: 'error',
+        category: 'structure',
+        kNodeRef: 'K:convention:no-cross-domain-import',
+        fixHint: "Replace 'import { ... } from \"../../other-domain/...\"' with 'await ctx.actions.call(\"other-domain.action-id\", input)'.",
+        exampleBad: "import { doThing } from '../../payments/api/charge';",
+        exampleGood: "await ctx.actions.call('payments.charge', { amount: 100 });",
+    },
+    'no-raw-aws-sdk': {
+        ruleId: 'no-raw-aws-sdk',
+        title: 'No raw AWS SDK imports',
+        description: 'Domain code must never import @aws-sdk/* directly. Use ctx-provided helpers (ctx.db, ctx.publish, ctx.secrets, ctx.fetch) or define an integration.',
+        severity: 'error',
+        category: 'structure',
+        kNodeRef: 'K:convention:tier-1-foundations',
+        fixHint: "Use ctx.db for DynamoDB, ctx.secrets for Secrets Manager, ctx.fetch for HTTP calls. For other services, define an integration via defineIntegration.",
+        exampleBad: "import { S3Client } from '@aws-sdk/client-s3';",
+        exampleGood: "await ctx.integrations.s3.putObject({ Bucket, Key, Body });",
+    },
+    'no-raw-http-server': {
+        ruleId: 'no-raw-http-server',
+        title: 'No raw HTTP server in domain code',
+        description: 'Domain code must not create raw HTTP servers (express, fastify, etc.). All HTTP handling goes through defineApi which is wired to API Gateway by the scaffold.',
+        severity: 'error',
+        category: 'structure',
+        kNodeRef: 'K:convention:tier-1-foundations',
+        fixHint: 'Wrap your HTTP handler with defineApi({ ... }). The scaffold handles API Gateway wiring.',
+        exampleBad: "import express from 'express';\nconst app = express();",
+        exampleGood: "export const myApi = defineApi({ id: 'my-api', path: '/v1/my-api', ... });",
+    },
+    'require-define-primitive': {
+        ruleId: 'require-define-primitive',
+        title: 'Require define primitive factories',
+        description: 'All domain handlers must use the appropriate factory function: defineApi for HTTP APIs, defineSubscriber for event subscribers, defineAction for cross-domain actions, defineJob for background jobs.',
+        severity: 'error',
+        category: 'structure',
+        kNodeRef: 'K:runbook:add-domain',
+        fixHint: "Wrap your handler with the appropriate define* factory from @mettlecast/domain-runtime.",
+        exampleBad: "export const handler = async (event) => ({ statusCode: 200 });",
+        exampleGood: "export const myApi = defineApi({ id: 'my-api', ... });",
+    },
+    'flow-domain-ownership': {
+        ruleId: 'flow-domain-ownership',
+        title: 'Flow domain ownership',
+        description: 'Every flow must have an owningDomain. Root-level flows/ directory is deprecated. Flows belong inside domains/{owningDomain}/flows/.',
+        severity: 'error',
+        category: 'structure',
+        kNodeRef: 'K:convention:flow-vs-subscriber-rule',
+        fixHint: "Move the flow file to domains/<owningDomain>/flows/<id>.ts and set owningDomain in the defineFlow call.",
+        exampleBad: "// flows/onboarding.ts (root level — deprecated)",
+        exampleGood: "// domains/auth/flows/onboarding.ts\nexport const onboarding = defineFlow({ owningDomain: 'auth', ... });",
+    },
+    'domain-configs-valid': {
+        ruleId: 'domain-configs-valid',
+        title: 'Domain configs are valid',
+        description: 'Every domain directory under domains/ must contain a valid domain.config.ts file exported by defineDomain().',
+        severity: 'error',
+        category: 'structure',
+        kNodeRef: 'K:runbook:add-domain',
+        fixHint: "Run 'mc-domain-module add-domain <id>' to scaffold a missing domain.",
+        exampleBad: '// domains/payments/ — missing domain.config.ts',
+        exampleGood: "// domains/payments/domain.config.ts\nexport const domain = defineDomain({ id: 'payments', tenancy: 'required' });",
+    },
+    'apis-have-versions': {
+        ruleId: 'apis-have-versions',
+        title: 'APIs declare versions',
+        description: 'Every defineApi must have a versions field with at least one version entry. Versioning is mandatory for API evolution.',
+        severity: 'error',
+        category: 'correctness',
+        kNodeRef: 'K:runbook:add-domain',
+        fixHint: 'Add versions: { v1: { status, input, output, handler } } to your defineApi call.',
+        exampleBad: "defineApi({ id: 'my-api', path: '/v1/my-api' }) // missing versions",
+        exampleGood: "defineApi({ id: 'my-api', path: '/v1/my-api', versions: { v1: { ... } } });",
+    },
+    'apis-have-tenancy': {
+        ruleId: 'apis-have-tenancy',
+        title: 'APIs declare tenancy',
+        description: 'Every defineApi must declare its tenancy mode: required (tenant-scoped), none (tenant-agnostic like registration), or system (system-internal admin).',
+        severity: 'error',
+        category: 'correctness',
+        kNodeRef: 'K:convention:tier-1-foundations',
+        fixHint: "Add tenancy: 'required' | 'none' | 'system' to your defineApi call.",
+        exampleBad: "defineApi({ id: 'my-api', path: '/v1/my-api' }) // missing tenancy",
+        exampleGood: "defineApi({ id: 'my-api', path: '/v1/my-api', tenancy: 'required' });",
+    },
+    'no-cross-domain-imports': {
+        ruleId: 'no-cross-domain-imports',
+        title: 'No cross-domain imports (doctor check)',
+        description: 'The doctor command scans for import statements that reference files in other domain directories. These violate domain isolation.',
+        severity: 'error',
+        category: 'structure',
+        kNodeRef: 'K:convention:no-cross-domain-import',
+        fixHint: "Use domain actions or events to communicate between domains. See 'tib explain no-cross-domain-internal-import' for details.",
+        exampleBad: "import { charge } from '../../payments/api/charge';",
+        exampleGood: "await ctx.actions.call('payments.charge', { amount: 100 });",
+    },
+    'scaffold-config-matches': {
+        ruleId: 'scaffold-config-matches',
+        title: 'Scaffold config matches on-disk domains',
+        description: 'The .mc/scaffold-config.json domainIds array must match the directories present under domains/. Run add-domain to sync.',
+        severity: 'error',
+        category: 'structure',
+        kNodeRef: 'K:runbook:add-domain',
+        fixHint: "Run 'mc-domain-module add-domain <id>' for missing domains, or remove stale entries from .mc/scaffold-config.json.",
+        exampleBad: '// domains/ has "billing" but .mc/scaffold-config.json does not list it',
+        exampleGood: '// Run: mc-domain-module add-domain billing',
+    },
+    'husky-hooks-installed': {
+        ruleId: 'husky-hooks-installed',
+        title: 'Husky git hooks are installed',
+        description: 'The .husky/pre-commit hook should be present and executable. It enforces pre-commit checks like ESLint and commit message format.',
+        severity: 'warn',
+        category: 'structure',
+        kNodeRef: 'K:runbook:add-domain',
+        fixHint: "Run 'npx husky install' to set up git hooks.",
+        exampleBad: 'Missing .husky/pre-commit',
+        exampleGood: 'npx husky install  # creates .husky/pre-commit',
+    },
+};
+/**
+ * Execute the explain command: look up a rule ID and print its explanation.
+ */
+export function runExplain(opts) {
+    const explanation = RULE_EXPLANATIONS[opts.ruleId];
+    if (!explanation) {
+        const available = Object.keys(RULE_EXPLANATIONS).join(', ');
+        throw new Error(`Unknown rule ID "${opts.ruleId}".\n\nAvailable rules: ${available}`);
+    }
+    return explanation;
+}
+/**
+ * CLI entry point: prints the explanation in a human-readable format.
+ */
+export function runExplainCli(opts) {
+    const explanation = runExplain(opts);
+    // eslint-disable-next-line no-console
+    console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║  ${explanation.ruleId}
+╚══════════════════════════════════════════════════════════════╝
+
+  Severity:  ${explanation.severity.toUpperCase()}
+  Category:  ${explanation.category}
+  Docs:      ${explanation.kNodeRef}
+
+  ${explanation.description}
+
+  Fix: ${explanation.fixHint}
+
+  ❌ BAD:
+  ${explanation.exampleBad.split('\n').map((l) => '  ' + l).join('\n')}
+
+  ✅ GOOD:
+  ${explanation.exampleGood.split('\n').map((l) => '  ' + l).join('\n')}
+`);
+}

package/dist/commands/power-tune.d.ts

@@ -0,0 +1 @@
+export declare function runPowerTune(domain: string, primitive: string): Promise<void>;

package/dist/commands/power-tune.js

@@ -0,0 +1,87 @@
+import { SFNClient, StartExecutionCommand, DescribeExecutionCommand } from '@aws-sdk/client-sfn';
+import { readFileSync } from 'fs';
+import path from 'path';
+import { cliLogger } from '../utils/logger.js';
+export async function runPowerTune(domain, primitive) {
+    // Load registry to find Lambda ARN
+    const registryPath = path.join(process.cwd(), '.tib', `${domain}-registry.json`);
+    let registry;
+    try {
+        registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+    }
+    catch {
+        cliLogger.error({}, `Registry not found at ${registryPath}. Run: tib build domains/${domain}`);
+        process.exit(1);
+    }
+    // Find Lambda ARN for the primitive
+    const lambdaArn = registry.functionArns?.[primitive];
+    if (!lambdaArn) {
+        cliLogger.error({}, `No Lambda ARN found for primitive '${primitive}' in domain '${domain}'.`);
+        cliLogger.error({}, `Available primitives: ${Object.keys(registry.functionArns ?? {}).join(', ')}`);
+        process.exit(1);
+    }
+    // Get state machine ARN
+    const stateMachineArn = process.env['POWER_TUNING_STATE_MACHINE_ARN'];
+    if (!stateMachineArn) {
+        cliLogger.error({}, 'POWER_TUNING_STATE_MACHINE_ARN environment variable not set.');
+        cliLogger.error({}, 'Deploy PowerTuningStack first and export the ARN.');
+        process.exit(1);
+    }
+    const sfnClient = new SFNClient({});
+    const input = JSON.stringify({
+        lambdaARN: lambdaArn,
+        powerValues: [128, 256, 512, 1024, 1536, 3008],
+        num: 10,
+        payload: '{}',
+        parallelInvocation: true,
+        strategy: 'cost',
+    });
+    cliLogger.info({ domain, primitive, lambdaArn }, 'Starting power tuning');
+    const startResult = await sfnClient.send(new StartExecutionCommand({
+        stateMachineArn,
+        input,
+        name: `tib-power-tune-${domain}-${primitive}-${Date.now()}`,
+    }));
+    const executionArn = startResult.executionArn;
+    cliLogger.info({ executionArn }, 'Execution started');
+    cliLogger.info({}, 'Polling for results (this takes 1-3 minutes)...');
+    // Poll for completion
+    let attempts = 0;
+    const maxAttempts = 60; // 5 minutes at 5s intervals
+    while (attempts < maxAttempts) {
+        await new Promise(resolve => setTimeout(resolve, 5000));
+        attempts++;
+        const status = await sfnClient.send(new DescribeExecutionCommand({ executionArn }));
+        if (status.status === 'RUNNING') {
+            process.stdout.write('.');
+            continue;
+        }
+        process.stdout.write('\n');
+        if (status.status === 'SUCCEEDED') {
+            const output = JSON.parse(status.output ?? '{}');
+            cliLogger.info({}, '\n=== Power Tuning Results ===');
+            cliLogger.info({ domain, primitive }, 'Power tuning complete');
+            if (output.results && Array.isArray(output.results) && output.results.length > 0) {
+                const optimal = output.results.reduce((best, r) => r.cost < best.cost ? r : best);
+                const baseline = output.results[0];
+                const costPercentChange = ((optimal.cost / baseline.cost - 1) * 100).toFixed(1);
+                const durationPercentChange = ((optimal.duration / baseline.duration - 1) * 100).toFixed(1);
+                cliLogger.info({ memory: optimal.power }, `Optimal memory size: ${optimal.power} MB`);
+                cliLogger.info({ change: costPercentChange }, `Expected cost change: ${costPercentChange}%`);
+                cliLogger.info({ change: durationPercentChange }, `Expected duration change: ${durationPercentChange}%`);
+                cliLogger.info({}, `To apply: update your domain registry config:`);
+                cliLogger.info({}, `  domains/${domain}/domain.config.ts → defaultDeployment.memory = ${optimal.power}`);
+            }
+            cliLogger.info({}, `Visualization: https://lambda-power-tuning.show/#${Buffer.from(JSON.stringify(output)).toString('base64')}`);
+            return;
+        }
+        cliLogger.error({ status }, `Execution failed with status: ${status.status}`);
+        if (status.cause) {
+            cliLogger.error({}, `Cause: ${status.cause}`);
+        }
+        process.exit(1);
+    }
+    cliLogger.error({}, 'Timeout: execution did not complete within 5 minutes.');
+    cliLogger.error({ executionArn }, `Check manually: aws stepfunctions describe-execution --execution-arn ${executionArn}`);
+    process.exit(1);
+}

package/dist/commands/reseed-page.d.ts

@@ -0,0 +1,6 @@
+export interface ReseedPageOptions {
+    pageName?: string;
+    all?: boolean;
+    projectDir?: string;
+}
+export declare function runReseedPage(opts: ReseedPageOptions): Promise<void>;

package/dist/commands/reseed-page.js

@@ -0,0 +1,297 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+import { execSync } from 'node:child_process';
+import { createGunzip } from 'node:zlib';
+import { Readable } from 'node:stream';
+import { cliLogger } from '../utils/logger.js';
+import { fetchVersionsJson, fetchModulesJson, fetchModuleTarball, } from '../utils/s3-fetch.js';
+import { readManifest } from '../utils/manifest.js';
+import { readScaffoldConfig } from '../utils/scaffold-config.js';
+const SCAFFOLD_BUCKET = 'mc-scaffold';
+// ── Seed page categories ───────────────────────────────────────────────────────
+const SEED_PAGE_CATEGORIES = ['auth', 'account', 'shell', '_errors'];
+const SEED_LAYOUT_DIR = 'layouts';
+// ── Tarball parsing ────────────────────────────────────────────────────────────
+async function parseTarball(buf) {
+    const decompressed = await new Promise((res, rej) => {
+        const gunzip = createGunzip();
+        const chunks = [];
+        const input = Readable.from(buf);
+        input.pipe(gunzip);
+        gunzip.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+        gunzip.on('end', () => res(Buffer.concat(chunks)));
+        gunzip.on('error', rej);
+    });
+    const entries = [];
+    let offset = 0;
+    while (offset + 512 <= decompressed.length) {
+        const header = decompressed.slice(offset, offset + 512);
+        if (header.every((b) => b === 0))
+            break;
+        let name = header.slice(0, 100).toString('utf-8').replace(/\0.*/, '');
+        const prefix = header.slice(345, 500).toString('utf-8').replace(/\0.*/, '');
+        if (prefix)
+            name = `${prefix}/${name}`;
+        const sizeStr = header.slice(124, 136).toString('utf-8').replace(/\0.*/, '').trim();
+        const size = parseInt(sizeStr, 8) || 0;
+        const typeFlag = header[156];
+        const isRegularFile = typeFlag === 0x30 || typeFlag === 0 || typeFlag === undefined;
+        offset += 512;
+        if (isRegularFile && name && size > 0) {
+            const content = decompressed.slice(offset, offset + size);
+            entries.push({ path: name, content });
+        }
+        offset += Math.ceil(size / 512) * 512;
+    }
+    return entries;
+}
+function getTarEntry(entries, targetPath) {
+    return entries.find((e) => {
+        const normalized = e.path.replace(/^\.\//, '').replace(/^[^/]+\//, '');
+        return normalized === targetPath || e.path === targetPath || e.path.endsWith(`/${targetPath}`);
+    });
+}
+// ── GitHub helpers ─────────────────────────────────────────────────────────────
+function detectGitRemote(projectDir) {
+    try {
+        const url = execSync('git remote get-url origin', {
+            cwd: projectDir,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        const sshMatch = url.match(/git@github\.com:([^/]+)\/([^.]+?)(?:\.git)?$/);
+        if (sshMatch)
+            return { owner: sshMatch[1], repo: sshMatch[2] };
+        const httpsMatch = url.match(/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:\/)?$/);
+        if (httpsMatch)
+            return { owner: httpsMatch[1], repo: httpsMatch[2] };
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function createGitHubPR(owner, repo, token, branch, title, body, labels) {
+    const url = `https://api.github.com/repos/${owner}/${repo}/pulls`;
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/vnd.github+json',
+            'Content-Type': 'application/json',
+            'X-GitHub-Api-Version': '2022-11-28',
+        },
+        body: JSON.stringify({
+            title,
+            body,
+            head: branch,
+            base: 'develop',
+            labels,
+        }),
+    });
+    if (!res.ok) {
+        const err = await res.text();
+        throw new Error(`GitHub PR creation failed (${res.status}): ${err}`);
+    }
+    const data = (await res.json());
+    return { url: data.html_url, number: data.number };
+}
+// ── Seed page fetching ─────────────────────────────────────────────────────────
+async function fetchSeedPagesToReseed(tarEntries, tarManifest, pageName) {
+    const results = [];
+    if (pageName) {
+        // Single page mode: fetch one specific page
+        for (const fileEntry of tarManifest) {
+            if (fileEntry.path.includes(`/pages/`) && fileEntry.path.includes(`${pageName}.tsx`)) {
+                const tarEntry = getTarEntry(tarEntries, fileEntry.path);
+                if (tarEntry) {
+                    let installPath = fileEntry.installedAs ?? fileEntry.path;
+                    if (installPath.endsWith('.tpl'))
+                        installPath = installPath.slice(0, -4);
+                    results.push({
+                        path: installPath,
+                        content: tarEntry.content.toString('utf-8'),
+                    });
+                }
+            }
+        }
+    }
+    else {
+        // Bulk mode (--all): fetch all seed pages
+        for (const fileEntry of tarManifest) {
+            const isSeedPage = isSeedPagePath(fileEntry.path);
+            if (isSeedPage) {
+                const tarEntry = getTarEntry(tarEntries, fileEntry.path);
+                if (tarEntry) {
+                    let installPath = fileEntry.installedAs ?? fileEntry.path;
+                    if (installPath.endsWith('.tpl'))
+                        installPath = installPath.slice(0, -4);
+                    results.push({
+                        path: installPath,
+                        content: tarEntry.content.toString('utf-8'),
+                    });
+                }
+            }
+        }
+    }
+    return results;
+}
+function isSeedPagePath(filePath) {
+    const seedPatterns = [
+        /^frontend\/src\/pages\/auth\//,
+        /^frontend\/src\/pages\/account\//,
+        /^frontend\/src\/pages\/shell\//,
+        /^frontend\/src\/pages\/_errors\//,
+        /^frontend\/src\/layouts\//,
+    ];
+    return seedPatterns.some((pattern) => pattern.test(filePath));
+}
+// ── Main export ────────────────────────────────────────────────────────────────
+export async function runReseedPage(opts) {
+    const projectDir = resolve(opts.projectDir ?? process.cwd());
+    if (!opts.pageName && !opts.all) {
+        throw new Error('Provide a page name or use --all to reseed all seed pages');
+    }
+    const mode = opts.all ? 'bulk' : 'single';
+    console.log(`\nTIB Reseed Page (${mode} mode)\n`);
+    console.log(`Project: ${projectDir}\n`);
+    // 1. Read manifest + scaffold-config
+    const manifest = await readManifest(projectDir);
+    if (!manifest) {
+        throw new Error(`.mc/manifest.json not found in ${projectDir}. Is this a TIB scaffold project?`);
+    }
+    const scaffoldConfig = await readScaffoldConfig(projectDir);
+    const bucket = scaffoldConfig.scaffoldBucket ?? SCAFFOLD_BUCKET;
+    // 2. Get latest version
+    const versionsJson = await fetchVersionsJson(bucket);
+    const latestVersion = versionsJson.latest;
+    console.log(`Current version : ${manifest.scaffoldVersion}`);
+    console.log(`Latest version  : ${latestVersion}\n`);
+    // 3. Fetch frontend module tarball
+    const modulesJson = await fetchModulesJson(bucket, latestVersion);
+    const frontendModule = modulesJson.modules.find((m) => m.id === 'frontend');
+    if (!frontendModule) {
+        throw new Error(`Frontend module not found in modules.json for version ${latestVersion}`);
+    }
+    console.log(`Fetching frontend module ${frontendModule.id}@${frontendModule.version}...\n`);
+    const tarBuf = await fetchModuleTarball(bucket, latestVersion, frontendModule.tarball, frontendModule.sha256);
+    const tarEntries = await parseTarball(tarBuf);
+    const manifestEntry = getTarEntry(tarEntries, 'MANIFEST.json');
+    if (!manifestEntry) {
+        throw new Error('No MANIFEST.json in frontend module tarball');
+    }
+    const tarManifest = JSON.parse(manifestEntry.content.toString('utf-8'));
+    // 4. Fetch seed pages to reseed
+    const seedPages = await fetchSeedPagesToReseed(tarEntries, tarManifest, opts.pageName);
+    if (seedPages.length === 0) {
+        const msg = opts.pageName
+            ? `No seed page found matching "${opts.pageName}"`
+            : 'No seed pages found to reseed';
+        throw new Error(msg);
+    }
+    console.log(`Found ${seedPages.length} seed page(s) to reseed`);
+    seedPages.forEach((p) => {
+        console.log(`  - ${p.path}`);
+    });
+    console.log('');
+    // 5. Create git branch for the reseed
+    const branchName = opts.all
+        ? `tib-reseed/all-v${latestVersion}`
+        : `tib-reseed/${opts.pageName}-v${latestVersion}`;
+    try {
+        execSync(`git -C "${projectDir}" checkout -b "${branchName}"`, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch {
+        // Branch may already exist
+        try {
+            execSync(`git -C "${projectDir}" checkout "${branchName}"`, {
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+        }
+        catch {
+            throw new Error(`Failed to create or checkout branch: ${branchName}`);
+        }
+    }
+    // 6. Write seed pages to disk
+    for (const seedPage of seedPages) {
+        const diskPath = join(projectDir, seedPage.path);
+        console.log(`Writing ${seedPage.path}...`);
+        await mkdir(dirname(diskPath), { recursive: true });
+        await writeFile(diskPath, seedPage.content, 'utf-8');
+    }
+    // 7. Commit changes
+    execSync(`git -C "${projectDir}" add -A`, { stdio: 'pipe' });
+    let hasChanges = false;
+    try {
+        const status = execSync(`git -C "${projectDir}" status --porcelain`, {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        hasChanges = status.length > 0;
+    }
+    catch {
+        // ignore
+    }
+    if (!hasChanges) {
+        console.log('No changes to commit — seed pages are already up to date.\n');
+        return;
+    }
+    const commitMsg = opts.all
+        ? `chore: [DESTRUCTIVE] bulk reseed all seed pages to v${latestVersion}`
+        : `chore: [DESTRUCTIVE] reseed ${opts.pageName} to v${latestVersion}`;
+    execSync(`git -C "${projectDir}" commit -m "${commitMsg}"`, { stdio: 'pipe' });
+    try {
+        execSync(`git -C "${projectDir}" push --set-upstream origin "${branchName}"`, {
+            stdio: 'pipe',
+        });
+    }
+    catch {
+        cliLogger.warn({ branchName }, 'reseed-page: git push failed — skipping PR creation');
+        console.log(`\nCommit created on branch: ${branchName}`);
+        console.log('Note: push failed — create the PR manually.\n');
+        return;
+    }
+    // 8. Create GitHub PR
+    const token = process.env['GITHUB_TOKEN'];
+    const remote = detectGitRemote(projectDir);
+    if (!token) {
+        console.log(`\nBranch pushed: ${branchName}`);
+        console.log('Set GITHUB_TOKEN env var to create a PR automatically.\n');
+        return;
+    }
+    if (!remote) {
+        console.log(`\nBranch pushed: ${branchName}`);
+        console.log('Could not detect GitHub owner/repo from git remote — create the PR manually.\n');
+        return;
+    }
+    const prTitle = opts.all
+        ? `[DESTRUCTIVE] Bulk reseed all seed pages to scaffold v${latestVersion}`
+        : `[DESTRUCTIVE] Reseed ${opts.pageName} to scaffold v${latestVersion}`;
+    const prBody = buildReseedPagePrBody(opts.pageName ?? 'all pages', latestVersion, seedPages);
+    const prResult = await createGitHubPR(remote.owner, remote.repo, token, branchName, prTitle, prBody, ['tib-destructive-reseed']);
+    console.log(`\nPR created: ${prResult.url}\n`);
+    cliLogger.info({ prUrl: prResult.url, latestVersion }, 'reseed-page: PR created');
+}
+function buildReseedPagePrBody(pageName, version, pages) {
+    const lines = [
+        '## ⚠️ DESTRUCTIVE: Reseed Seed Pages',
+        '',
+        'This PR **overwrites** the following seed page(s) with the latest scaffold version.',
+        'This is a destructive operation — verify changes carefully.',
+        '',
+        '### Seed pages to be overwritten',
+        '',
+    ];
+    for (const page of pages) {
+        lines.push(`- \`${page.path}\``);
+    }
+    lines.push('');
+    lines.push('### What to do');
+    lines.push('1. Review the file diffs in this PR');
+    lines.push('2. If acceptable, merge this PR');
+    lines.push('3. The seed pages will be reset to their scaffold defaults');
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/commands/show-dns.d.ts

@@ -0,0 +1,15 @@
+export interface ShowDnsOptions {
+    env?: string;
+    projectDir?: string;
+}
+/**
+ * tib show-dns [--env dev|staging|prod] [--project-dir <path>]
+ *
+ * Reads the scaffold-config.json and prints DNS records that must be added for
+ * custom domain wiring: certificate validation CNAMEs (step 1) and traffic
+ * routing CNAMEs (step 2).
+ *
+ * For the routing CNAME the CloudFront domain is read from the CDK outputs file
+ * (.mc/cdk-outputs.json) if available; otherwise it is shown as a placeholder.
+ */
+export declare function runShowDns(opts: ShowDnsOptions): Promise<void>;