@mettlecast/domain-cli 0.2.0

package/dist/commands/upgrade.js

@@ -0,0 +1,495 @@
+import { createGunzip } from 'node:zlib';
+import { Readable } from 'node:stream';
+import { unlink } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { execSync } from 'node:child_process';
+import { cliLogger } from '../utils/logger.js';
+import { fetchVersionsJson, fetchModulesJson, fetchModuleTarball, fetchScaffoldFile, } from '../utils/s3-fetch.js';
+import { computeChecksumString } from '../utils/checksum.js';
+import { applyTokens, buildTokenContext } from '../utils/token-substitution.js';
+import { injectHeader } from '../utils/header-inject.js';
+import { readManifest, writeManifest, upsertManifestFile, removeManifestFile, inferPolicyFromPath, } from '../utils/manifest.js';
+import { installScaffoldFile } from '../utils/install-file.js';
+import { readScaffoldConfig, writeScaffoldConfig } from '../utils/scaffold-config.js';
+const SCAFFOLD_BUCKET = 'mc-scaffold';
+// ── Tarball parsing (same impl as create-project.ts) ──────────────────────────
+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}`);
+    });
+}
+/**
+ * Check if a file path is a seed file (user-owned, not auto-upgraded).
+ * Seed files include: pages/auth/*, pages/account/*, pages/shell/*, pages/_errors/*, layouts/*, styles/brand.css
+ */
+function isSeedFile(filePath) {
+    const seedPatterns = [
+        /^frontend\/src\/pages\/auth\//,
+        /^frontend\/src\/pages\/account\//,
+        /^frontend\/src\/pages\/shell\//,
+        /^frontend\/src\/pages\/_errors\//,
+        /^frontend\/src\/layouts\//,
+        /^frontend\/src\/styles\/brand\.css$/,
+    ];
+    return seedPatterns.some((pattern) => pattern.test(filePath));
+}
+// ── Topological sort ───────────────────────────────────────────────────────────
+function topoSort(modules, selected) {
+    const byId = new Map(modules.map((m) => [m.id, m]));
+    const result = [];
+    const visited = new Set();
+    function visit(id) {
+        if (visited.has(id))
+            return;
+        visited.add(id);
+        const mod = byId.get(id);
+        if (!mod)
+            return;
+        for (const dep of mod.dependencies) {
+            if (selected.has(dep))
+                visit(dep);
+        }
+        result.push(mod);
+    }
+    for (const id of ['core', 'backend-lambda']) {
+        if (selected.has(id))
+            visit(id);
+    }
+    for (const id of selected)
+        visit(id);
+    return result;
+}
+// ── GitHub helpers ─────────────────────────────────────────────────────────────
+function detectGitRemote(projectDir) {
+    try {
+        const url = execSync('git remote get-url origin', {
+            cwd: projectDir,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        // SSH: git@github.com:owner/repo.git
+        const sshMatch = url.match(/git@github\.com:([^/]+)\/([^.]+?)(?:\.git)?$/);
+        if (sshMatch)
+            return { owner: sshMatch[1], repo: sshMatch[2] };
+        // HTTPS: https://github.com/owner/repo.git
+        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 && labels.length > 0 && { 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 };
+}
+// ── PR body builder ────────────────────────────────────────────────────────────
+function buildPrBody(currentVersion, targetVersion, results, changelogUrl) {
+    const added = results.filter((r) => r.status === 'added');
+    const updated = results.filter((r) => r.status === 'updated');
+    const deleted = results.filter((r) => r.status === 'deleted');
+    const conflicts = results.filter((r) => r.status === 'conflict');
+    const lines = [
+        `## TIB Scaffold Upgrade: ${currentVersion} → ${targetVersion}`,
+        '',
+        '### Summary',
+        `- **Added:** ${added.length} file(s)`,
+        `- **Updated:** ${updated.length} file(s)`,
+        `- **Deleted:** ${deleted.length} file(s)`,
+        `- **Conflicts (drift):** ${conflicts.length} file(s)`,
+        '',
+    ];
+    if (added.length > 0) {
+        lines.push('### Added files');
+        for (const r of added)
+            lines.push(`- \`${r.path}\` _(${r.module})_`);
+        lines.push('');
+    }
+    if (updated.length > 0) {
+        lines.push('### Updated files');
+        for (const r of updated)
+            lines.push(`- \`${r.path}\` _(${r.module})_`);
+        lines.push('');
+    }
+    if (deleted.length > 0) {
+        lines.push('### Deleted files');
+        for (const r of deleted)
+            lines.push(`- \`${r.path}\` _(${r.module})_`);
+        lines.push('');
+    }
+    if (conflicts.length > 0) {
+        lines.push('### Drift warnings — manual review required');
+        lines.push('The following files were locally modified after scaffold installation. ' +
+            'New versions have been written to `{path}.tib-upgrade` — merge manually then remove the `.tib-upgrade` file.');
+        for (const r of conflicts)
+            lines.push(`- \`${r.path}\` → \`${r.path}.tib-upgrade\``);
+        lines.push('');
+    }
+    if (changelogUrl) {
+        lines.push(`### Changelog`);
+        lines.push(`See full changelog: ${changelogUrl}`);
+        lines.push('');
+    }
+    lines.push('### Visual diff');
+    lines.push('');
+    lines.push('This PR has been automatically labelled `tib-frontend-upgrade`.');
+    lines.push('The Chromatic job will run and post a visual diff link here.');
+    lines.push('');
+    lines.push('**Before merging:** A reviewer must comment `visual diff reviewed` to acknowledge they have checked the Chromatic baseline diff.');
+    lines.push('');
+    lines.push('> Chromatic baseline link will appear in the Chromatic job output above once CI completes.');
+    lines.push('');
+    return lines.join('\n');
+}
+function buildFrontendComponentsPrBody(currentVersion, targetVersion, results, changelogUrl) {
+    const added = results.filter((r) => r.status === 'added');
+    const updated = results.filter((r) => r.status === 'updated');
+    const deleted = results.filter((r) => r.status === 'deleted');
+    const conflicts = results.filter((r) => r.status === 'conflict');
+    const lines = [
+        `## TIB Frontend Components Upgrade: ${currentVersion} → ${targetVersion}`,
+        '',
+        '### Summary',
+        `Upgrades scaffold-tracked frontend component files only (seed pages excluded).`,
+        '',
+        `- **Added:** ${added.length} file(s)`,
+        `- **Updated:** ${updated.length} file(s)`,
+        `- **Deleted:** ${deleted.length} file(s)`,
+        `- **Conflicts (drift):** ${conflicts.length} file(s)`,
+        '',
+    ];
+    if (added.length > 0) {
+        lines.push('### Added files');
+        for (const r of added)
+            lines.push(`- \`${r.path}\` _(${r.module})_`);
+        lines.push('');
+    }
+    if (updated.length > 0) {
+        lines.push('### Updated files');
+        for (const r of updated)
+            lines.push(`- \`${r.path}\` _(${r.module})_`);
+        lines.push('');
+    }
+    if (deleted.length > 0) {
+        lines.push('### Deleted files');
+        for (const r of deleted)
+            lines.push(`- \`${r.path}\` _(${r.module})_`);
+        lines.push('');
+    }
+    if (conflicts.length > 0) {
+        lines.push('### Drift warnings — manual review required');
+        lines.push('The following files were locally modified after scaffold installation. ' +
+            'New versions have been written to `{path}.tib-upgrade` — merge manually then remove the `.tib-upgrade` file.');
+        for (const r of conflicts)
+            lines.push(`- \`${r.path}\` → \`${r.path}.tib-upgrade\``);
+        lines.push('');
+    }
+    if (changelogUrl) {
+        lines.push(`### Visual diff`);
+        lines.push(`See Chromatic visual diff (when available): ${changelogUrl}`);
+        lines.push('');
+        lines.push(`> **Reviewer action required:** Comment \`visual diff reviewed\` on this PR after checking the Chromatic baseline diff. The \`require-visual-diff-review\` CI check will block merge until this comment is present.`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+export async function runUpgrade(packageSpec, opts) {
+    const projectDir = resolve(opts.projectDir ?? process.cwd());
+    console.log(`\nTIB Upgrade${opts.dryRun ? ' (dry run)' : ''}\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 currentVersion = manifest.scaffoldVersion;
+    // 2. Resolve target version
+    const versionsJson = await fetchVersionsJson(scaffoldConfig.scaffoldBucket ?? SCAFFOLD_BUCKET);
+    const targetVersion = packageSpec ?? versionsJson.latest;
+    console.log(`Current version : ${currentVersion}`);
+    console.log(`Target version  : ${targetVersion}\n`);
+    if (currentVersion === targetVersion) {
+        console.log('Already at target version — nothing to do.');
+        cliLogger.info({ currentVersion, targetVersion }, 'upgrade: already at target version');
+        return;
+    }
+    const bucket = scaffoldConfig.scaffoldBucket ?? SCAFFOLD_BUCKET;
+    const targetModulesJson = await fetchModulesJson(bucket, targetVersion);
+    // 3. Resolve enabled modules in topological order
+    let enabledSet = new Set(scaffoldConfig.enabledModules);
+    // If --frontend-components flag is set, scope to frontend module only
+    if (opts.frontendComponents) {
+        enabledSet = new Set(['frontend']);
+    }
+    const orderedModules = topoSort(targetModulesJson.modules, enabledSet);
+    // Build current version module map (for change detection)
+    let currentModulesJson = null;
+    try {
+        currentModulesJson = await fetchModulesJson(bucket, currentVersion);
+    }
+    catch {
+        // If current release is gone from S3, proceed without skipping unchanged modules
+    }
+    const currentModuleVersionMap = new Map((currentModulesJson?.modules ?? []).map((m) => [m.id, m.version]));
+    // 4. Get CLI version
+    let cliVersion = '0.0.0';
+    try {
+        const { createRequire } = await import('node:module');
+        const require = createRequire(import.meta.url);
+        const pkgJson = require('../../package.json');
+        cliVersion = pkgJson.version;
+    }
+    catch {
+        // ignore
+    }
+    // 5. Build token context
+    const tokenCtx = buildTokenContext({
+        projectName: manifest.projectName,
+        awsRegion: manifest.awsRegion,
+        awsAccountId: scaffoldConfig.awsAccountId,
+        adminEmail: scaffoldConfig.adminEmail,
+    }, targetVersion, cliVersion);
+    // 6. Process each module
+    const allResults = [];
+    const updatedManifest = { ...manifest, files: [...manifest.files] };
+    // Track all file paths present in the target release (to detect deletions)
+    const targetFilePaths = new Set();
+    for (const mod of orderedModules) {
+        const currentModVer = currentModuleVersionMap.get(mod.id);
+        if (currentModVer !== undefined && currentModVer === mod.version) {
+            // Module version unchanged — no file changes possible; still track paths
+            const currentModFiles = manifest.files.filter((f) => f.module === mod.id);
+            for (const f of currentModFiles)
+                targetFilePaths.add(f.path);
+            cliLogger.debug({ moduleId: mod.id, version: mod.version }, 'upgrade: module unchanged, skipping');
+            continue;
+        }
+        console.log(`  Processing module: ${mod.id}@${mod.version}...`);
+        const tarBuf = await fetchModuleTarball(bucket, targetVersion, mod.tarball, mod.sha256);
+        const tarEntries = await parseTarball(tarBuf);
+        const manifestEntry = getTarEntry(tarEntries, 'MANIFEST.json');
+        if (!manifestEntry) {
+            cliLogger.warn({ moduleId: mod.id }, 'upgrade: No MANIFEST.json in tarball — skipping module');
+            continue;
+        }
+        const tarManifest = JSON.parse(manifestEntry.content.toString('utf-8'));
+        for (const fileEntry of tarManifest) {
+            const tarEntry = getTarEntry(tarEntries, fileEntry.path);
+            if (!tarEntry) {
+                cliLogger.warn({ moduleId: mod.id, path: fileEntry.path }, 'upgrade: file listed in MANIFEST.json not found in tarball');
+                continue;
+            }
+            // Resolve install path
+            let installPath = fileEntry.installedAs ?? fileEntry.path;
+            if (installPath.endsWith('.tpl'))
+                installPath = installPath.slice(0, -4);
+            // When --frontend-components flag is set, skip seed files
+            if (opts.frontendComponents && isSeedFile(installPath)) {
+                cliLogger.debug({ moduleId: mod.id, path: installPath }, 'upgrade: skipping seed file (--frontend-components scoped)');
+                continue;
+            }
+            targetFilePaths.add(installPath);
+            // Process new content
+            let newContent = tarEntry.content.toString('utf-8');
+            if (fileEntry.isTemplate) {
+                newContent = applyTokens(newContent, tokenCtx);
+            }
+            newContent = injectHeader(newContent, installPath, mod.id, mod.version);
+            // Determine policy: use fileEntry.policy if present, else infer from path
+            const policy = fileEntry.policy ?? inferPolicyFromPath(installPath);
+            // Look up current manifest entry for this file
+            const currentEntry = updatedManifest.files.find((f) => f.path === installPath);
+            const diskPath = join(projectDir, installPath);
+            // Install file using policy-based dispatch
+            const installResult = await installScaffoldFile(diskPath, newContent, policy, currentEntry, {
+                dryRun: opts.dryRun,
+            });
+            // Handle result
+            if (installResult.status === 'skipped') {
+                // Skipped files are not tracked in results (e.g., seed file with --frontend-components)
+                continue;
+            }
+            // Add to results
+            allResults.push({ path: installPath, status: installResult.status, module: mod.id });
+            // Update manifest if file was not skipped
+            const newChecksum = computeChecksumString(newContent);
+            upsertManifestFile(updatedManifest, {
+                path: installPath,
+                module: mod.id,
+                moduleVersion: mod.version,
+                sha256: newChecksum,
+                wasTemplate: fileEntry.isTemplate,
+                installedAt: new Date().toISOString(),
+                policy,
+            });
+        }
+    }
+    // 7. Handle deleted files (in current manifest but not in target release)
+    const currentManagedFiles = manifest.files.filter((f) => enabledSet.has(f.module));
+    for (const f of currentManagedFiles) {
+        if (!targetFilePaths.has(f.path)) {
+            const diskPath = join(projectDir, f.path);
+            if (!opts.dryRun) {
+                try {
+                    await unlink(diskPath);
+                }
+                catch (err) {
+                    if (err.code !== 'ENOENT')
+                        throw err;
+                }
+            }
+            removeManifestFile(updatedManifest, f.path);
+            allResults.push({ path: f.path, status: 'deleted', module: f.module });
+        }
+    }
+    // 8. Print upgrade report
+    const added = allResults.filter((r) => r.status === 'added');
+    const updated = allResults.filter((r) => r.status === 'updated');
+    const deleted = allResults.filter((r) => r.status === 'deleted');
+    const conflicts = allResults.filter((r) => r.status === 'conflict');
+    console.log('\nUpgrade report:');
+    console.log(`  Added   : ${added.length}`);
+    console.log(`  Updated : ${updated.length}`);
+    console.log(`  Deleted : ${deleted.length}`);
+    console.log(`  Conflicts (drift): ${conflicts.length}`);
+    if (conflicts.length > 0) {
+        console.log('\nDrift warnings:');
+        for (const r of conflicts) {
+            console.log(`  ${r.path} — new version written to ${r.path}.tib-upgrade`);
+        }
+    }
+    if (opts.dryRun) {
+        console.log('\nDry run complete — no files were written.\n');
+        return;
+    }
+    // 9. Update manifest + scaffold-config
+    updatedManifest.scaffoldVersion = targetVersion;
+    await writeManifest(projectDir, updatedManifest);
+    const updatedConfig = { ...scaffoldConfig, scaffoldVersion: targetVersion };
+    await writeScaffoldConfig(projectDir, updatedConfig);
+    // 10. Commit on upgrade branch
+    const branchName = `tib-upgrade/${targetVersion}`;
+    try {
+        execSync(`git -C "${projectDir}" checkout -b "${branchName}"`, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    catch {
+        // Branch may already exist
+        execSync(`git -C "${projectDir}" checkout "${branchName}"`, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+    }
+    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) {
+        execSync(`git -C "${projectDir}" commit -m "chore: tib scaffold upgrade ${currentVersion} -> ${targetVersion}"`, { stdio: 'pipe' });
+        try {
+            execSync(`git -C "${projectDir}" push --set-upstream origin "${branchName}"`, {
+                stdio: 'pipe',
+            });
+        }
+        catch {
+            cliLogger.warn({ branchName }, 'upgrade: git push failed — skipping PR creation');
+            console.log(`\nCommit created on branch: ${branchName}`);
+            console.log('Note: push failed — create the PR manually.\n');
+            return;
+        }
+        // 11. Create GitHub PR
+        const token = opts.githubToken ?? process.env['GITHUB_TOKEN'];
+        const remote = detectGitRemote(projectDir);
+        if (!token) {
+            console.log(`\nBranch pushed: ${branchName}`);
+            console.log('Set GITHUB_TOKEN or pass --github-token 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 changelogUrl = await fetchScaffoldFile(bucket, targetVersion, 'CHANGELOG.md')
+            .then((c) => (c ? `https://${bucket}.s3.amazonaws.com/versions/${targetVersion}/CHANGELOG.md` : null))
+            .catch(() => null);
+        const prBody = opts.frontendComponents
+            ? buildFrontendComponentsPrBody(currentVersion, targetVersion, allResults, changelogUrl)
+            : buildPrBody(currentVersion, targetVersion, allResults, changelogUrl);
+        const prResult = await createGitHubPR(remote.owner, remote.repo, token, branchName, opts.frontendComponents
+            ? `chore: tib scaffold frontend components upgrade ${currentVersion} → ${targetVersion}`
+            : `chore: tib scaffold upgrade ${currentVersion} → ${targetVersion}`, prBody, opts.frontendComponents ? ['tib-frontend-upgrade'] : undefined);
+        console.log(`\nPR created: ${prResult.url}\n`);
+        cliLogger.info({ prUrl: prResult.url, targetVersion }, 'upgrade: PR created');
+    }
+    else {
+        console.log('\nNo file changes — skipping commit and PR.\n');
+    }
+    cliLogger.info({ currentVersion, targetVersion, added: added.length, updated: updated.length, deleted: deleted.length, conflicts: conflicts.length }, 'upgrade complete');
+}

package/dist/commands/validate.d.ts

@@ -0,0 +1,30 @@
+import type { DomainModuleConfig } from '@mettlecast/domain-runtime/types';
+/**
+ * A single validation failure.
+ */
+export interface ValidationError {
+    /** Short error code for CI parsing. */
+    code: string;
+    /** Human-readable message. */
+    message: string;
+}
+/**
+ * Result of the validate command.
+ */
+export interface ValidationResult {
+    /** true if all checks passed. */
+    valid: boolean;
+    /** List of validation failures. Empty when valid is true. */
+    errors: ValidationError[];
+    /** Non-fatal warnings from the registry build. */
+    warnings: string[];
+}
+/**
+ * Run the validate command: build the registry and perform structural validation.
+ * Exits the process with code 1 if validation fails (CI gate usage).
+ * @param domainRoot - Absolute or relative path to the domain root directory.
+ * @param exitOnFailure - If true, calls process.exit(1) on failure. Defaults to true.
+ * @param config - Optional domain module configuration. Defaults to { mode: 'optional' }.
+ * @returns ValidationResult for programmatic use (e.g. in tests).
+ */
+export declare function runValidate(domainRoot: string, exitOnFailure?: boolean, config?: DomainModuleConfig): Promise<ValidationResult>;

package/dist/commands/validate.js

@@ -0,0 +1,148 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { validRange } from 'semver';
+import { buildRegistry } from '../builder/build-registry.js';
+import { cliLogger } from '../utils/logger.js';
+/**
+ * Check for duplicate IDs in a list of registry entries.
+ * @param entries - Array of registry entries to check.
+ * @param kind - Kind name for error messages (e.g. 'api', 'webhook').
+ * @returns Array of ValidationError objects for any duplicates found.
+ */
+function checkDuplicateIds(entries, kind) {
+    const seen = new Set();
+    const errors = [];
+    for (const e of entries) {
+        if (seen.has(e.id)) {
+            errors.push({ code: 'DUPLICATE_ID', message: `Duplicate ${kind} id: '${e.id}'` });
+        }
+        seen.add(e.id);
+    }
+    return errors;
+}
+/**
+ * Check that every subscriber entry has a valid semver range string.
+ * @param entries - Subscriber registry entries to check.
+ * @returns Validation errors for any entry with an unparseable semver range.
+ */
+function checkSubscriberSemverRanges(entries) {
+    const errors = [];
+    for (const entry of entries) {
+        if (entry.semverRange && !validRange(entry.semverRange)) {
+            errors.push({
+                code: 'INVALID_SEMVER_RANGE',
+                message: `Subscriber '${entry.id}' has invalid semver range: '${entry.semverRange}'`,
+            });
+        }
+    }
+    return errors;
+}
+/**
+ * Check version lifecycle consistency: sunsetAt must be present and at least
+ * 90 days after deprecatedAt when both are specified.
+ * @param lifecycle - Optional lifecycle metadata from a registry entry.
+ * @param entryLabel - Human-readable label for error messages.
+ * @returns Validation errors for lifecycle inconsistencies.
+ */
+function checkLifecycleConsistency(lifecycle, entryLabel) {
+    if (!lifecycle?.deprecatedAt)
+        return [];
+    const errors = [];
+    const deprecated = new Date(lifecycle.deprecatedAt);
+    if (!lifecycle.sunsetAt) {
+        errors.push({
+            code: 'MISSING_SUNSET_DATE',
+            message: `${entryLabel}: deprecatedAt is set but sunsetAt is missing (90-day rule requires a sunset date)`,
+        });
+        return errors;
+    }
+    const sunset = new Date(lifecycle.sunsetAt);
+    const minSunset = new Date(deprecated.getTime() + 90 * 24 * 60 * 60 * 1000);
+    if (sunset < minSunset) {
+        errors.push({
+            code: 'SUNSET_TOO_SOON',
+            message: `${entryLabel}: sunsetAt must be at least 90 days after deprecatedAt (90-day deprecation rule)`,
+        });
+    }
+    return errors;
+}
+/**
+ * Stub: check for backend files not under `.mc/domains/` when mode is enforced or strict.
+ * Full file-tree scan is deferred to v1.x — this stub records the intent.
+ * @param _repoRoot - Absolute path to the repository root.
+ * @param config - Enforcement configuration.
+ * @returns Empty array (scan not yet implemented).
+ */
+async function checkRawPathViolations(_repoRoot, config) {
+    if (config.mode === 'optional')
+        return [];
+    return [];
+}
+/**
+ * Run the validate command: build the registry and perform structural validation.
+ * Exits the process with code 1 if validation fails (CI gate usage).
+ * @param domainRoot - Absolute or relative path to the domain root directory.
+ * @param exitOnFailure - If true, calls process.exit(1) on failure. Defaults to true.
+ * @param config - Optional domain module configuration. Defaults to { mode: 'optional' }.
+ * @returns ValidationResult for programmatic use (e.g. in tests).
+ */
+export async function runValidate(domainRoot, exitOnFailure = true, config = { mode: 'optional' }) {
+    const { registry, warnings } = await buildRegistry(domainRoot);
+    const errors = [];
+    // Log any build warnings (e.g. tsx import failures) immediately.
+    for (const w of warnings) {
+        cliLogger.warn(w);
+    }
+    errors.push(...checkDuplicateIds(registry.apis, 'api'), ...checkDuplicateIds(registry.webhooks, 'webhook'), ...checkDuplicateIds(registry.subscribers, 'subscriber'), ...checkDuplicateIds(registry.schedules, 'schedule'), ...checkDuplicateIds(registry.jobs, 'job'), ...checkDuplicateIds(registry.actions, 'action'), ...checkDuplicateIds(registry.integrations, 'integration'), ...checkDuplicateIds(registry.events, 'event'));
+    const entriesWithFiles = [
+        ...registry.apis,
+        ...registry.webhooks,
+        ...registry.subscribers,
+        ...registry.schedules,
+        ...registry.jobs,
+        ...registry.actions,
+    ];
+    await Promise.all(entriesWithFiles.map(async (entry) => {
+        if (!entry.handlerFile)
+            return;
+        const absPath = join(registry.domainRoot, entry.handlerFile);
+        try {
+            await stat(absPath);
+        }
+        catch {
+            errors.push({
+                code: 'MISSING_HANDLER_FILE',
+                message: `Handler file not found for ${entry.kind} '${entry.id}': ${absPath}`,
+            });
+        }
+    }));
+    errors.push(...checkSubscriberSemverRanges(registry.subscribers));
+    for (const api of registry.apis) {
+        const entry = api;
+        errors.push(...checkLifecycleConsistency(entry, `api '${api.id}'`));
+    }
+    const rawPathErrors = await checkRawPathViolations(registry.domainRoot, config);
+    errors.push(...rawPathErrors);
+    const totalPrimitives = registry.apis.length + registry.webhooks.length +
+        registry.subscribers.length + registry.schedules.length +
+        registry.jobs.length + registry.actions.length;
+    if (totalPrimitives === 0) {
+        errors.push({ code: 'EMPTY_DOMAIN', message: 'Domain has no primitives defined' });
+    }
+    const valid = errors.length === 0;
+    if (valid) {
+        cliLogger.info({ domain: registry.domain.id, primitives: totalPrimitives, warnings: warnings.length }, 'Validation passed');
+    }
+    else {
+        for (const e of errors) {
+            cliLogger.error({ code: e.code }, e.message);
+        }
+        if (warnings.length > 0) {
+            cliLogger.warn({ count: warnings.length }, 'Build warnings were encountered (see above)');
+        }
+        if (exitOnFailure) {
+            process.exit(1);
+        }
+    }
+    return { valid, errors, warnings };
+}