@mettlecast/domain-cli 0.2.0

package/dist/commands/show-dns.js

@@ -0,0 +1,101 @@
+import { readFile } from 'fs/promises';
+import path from 'path';
+import { cliLogger } from '../utils/logger.js';
+function toZoneLine(r) {
+    return `${r.name}. 300 IN ${r.type} ${r.value}.`;
+}
+/**
+ * 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 async function runShowDns(opts) {
+    const projectDir = opts.projectDir ? path.resolve(opts.projectDir) : process.cwd();
+    const configPath = path.join(projectDir, '.tib', 'scaffold-config.json');
+    let config;
+    try {
+        const raw = await readFile(configPath, 'utf-8');
+        config = JSON.parse(raw);
+    }
+    catch {
+        console.error('[tib] Could not read .mc/scaffold-config.json — run from a TIB project root.');
+        process.exit(1);
+    }
+    const environments = config.environments ?? {};
+    if (Object.keys(environments).length === 0) {
+        console.log('[tib] No environments configured. Set a custom domain via `tib show-dns` or the Setup tab.');
+        return;
+    }
+    // Try to load CDK outputs for routing records
+    let cdkOutputs = {};
+    try {
+        const outputsPath = path.join(projectDir, '.tib', 'cdk-outputs.json');
+        const raw = await readFile(outputsPath, 'utf-8');
+        cdkOutputs = JSON.parse(raw);
+    }
+    catch {
+        // No CDK outputs yet — routing CNAMEs will show a placeholder
+    }
+    const targetEnvs = opts.env
+        ? [opts.env]
+        : Object.keys(environments);
+    for (const env of targetEnvs) {
+        const cfg = environments[env];
+        if (!cfg?.dashboardUrl) {
+            console.log(`\n;; ${env}: no custom domain configured`);
+            continue;
+        }
+        const info = await buildEnvDnsInfo(env, cfg.dashboardUrl, cdkOutputs);
+        printEnvDns(env, info);
+    }
+}
+async function buildEnvDnsInfo(env, dashboardUrl, cdkOutputs) {
+    // Look for cert validation records from CDK outputs
+    // Cert validation CNAMEs are emitted by ACM and captured in CDK outputs under the cert resource
+    const certArnOutputKey = `tib-cert-${env}-arn`;
+    const certArn = Object.values(cdkOutputs)
+        .flatMap(stack => Object.entries(stack))
+        .find(([k]) => k === certArnOutputKey)?.[1];
+    // Look for the CloudFront distribution domain from CDK outputs
+    const distributionDomainName = Object.values(cdkOutputs)
+        .flatMap(stack => Object.entries(stack))
+        .find(([k]) => k.toLowerCase().includes('distributiondomain') && k.toLowerCase().includes(env))?.[1]
+        ?? `<run cdk synth — distribution domain not yet available>`;
+    const validationRecords = certArn
+        // When CDK outputs include validation record overrides, they'd be here.
+        // Without a live describe-certificate call, we surface a placeholder.
+        ? [{ type: 'CNAME', name: `_acm-validation.${dashboardUrl}`, value: `<see ACM console for cert ${certArn}>` }]
+        : [{ type: 'CNAME', name: `_acm-validation.${dashboardUrl}`, value: `<deploy the FrontendCustomDomainStack first>` }];
+    const routingRecords = [
+        { type: 'CNAME', name: dashboardUrl, value: distributionDomainName },
+    ];
+    return {
+        dashboardUrl,
+        status: certArn ? 'deployed' : 'not_deployed',
+        validationRecords,
+        routingRecords,
+    };
+}
+function printEnvDns(env, info) {
+    console.log(`\n;; ${env} — ${info.dashboardUrl}`);
+    if (info.validationRecords.length > 0) {
+        console.log(';; Certificate validation records (add once, shared across deploys)');
+        for (const r of info.validationRecords) {
+            console.log(toZoneLine(r));
+        }
+    }
+    if (info.routingRecords.length > 0) {
+        console.log(';; Traffic routing records (update when CloudFront domain changes)');
+        for (const r of info.routingRecords) {
+            console.log(toZoneLine(r));
+        }
+    }
+    if (info.errorMessage) {
+        cliLogger.error({ env, errorMessage: info.errorMessage }, 'DNS info error');
+    }
+}

package/dist/commands/show.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Command to show a structured JSON summary of a domain's structure.
+ * Reads the domains/<id>/ directory and builds a summary of primitives,
+ * tables, events, and files.
+ */
+/**
+ * Options for the show command.
+ */
+export interface ShowDomainOptions {
+    /** Domain ID in kebab-case. */
+    domain: string;
+    /** Override directory for domains. */
+    domainsDir?: string;
+}
+/**
+ * Represents a primitive entry (API, subscriber, action, or job).
+ */
+interface PrimitiveEntry {
+    type: 'api' | 'subscriber' | 'action' | 'job';
+    id: string;
+    file: string;
+}
+/**
+ * Represents a domain summary.
+ */
+interface DomainSummary {
+    domain: string;
+    primitives: {
+        apis: PrimitiveEntry[];
+        subscribers: PrimitiveEntry[];
+        actions: PrimitiveEntry[];
+        jobs: PrimitiveEntry[];
+    };
+    tables: string[];
+    events: string[];
+    files: string[];
+}
+/**
+ * Execute the show domain command.
+ */
+export declare function runShowDomain(opts: ShowDomainOptions): Promise<DomainSummary>;
+/**
+ * CLI entry point: print the structured JSON to stdout.
+ */
+export declare function runShowDomainCli(opts: ShowDomainOptions): Promise<void>;
+export {};

package/dist/commands/show.js

@@ -0,0 +1,135 @@
+/**
+ * Command to show a structured JSON summary of a domain's structure.
+ * Reads the domains/<id>/ directory and builds a summary of primitives,
+ * tables, events, and files.
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+/**
+ * Recursively list all files in a directory, excluding node_modules and __tests__.
+ */
+async function listFilesRecursive(dir) {
+    const result = [];
+    async function walk(current, base) {
+        try {
+            const entries = await readdir(current, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = join(current, entry.name);
+                const relativePath = join(base, entry.name);
+                if (entry.isDirectory()) {
+                    if (entry.name === 'node_modules' || entry.name === '__tests__')
+                        continue;
+                    await walk(fullPath, relativePath);
+                }
+                else {
+                    result.push(relativePath.replace(/\\/g, '/'));
+                }
+            }
+        }
+        catch {
+            // Silently skip inaccessible directories
+        }
+    }
+    await walk(dir, '');
+    return result.sort();
+}
+/**
+ * Scan a subdirectory for TypeScript primitives.
+ */
+async function scanPrimitives(dir, type) {
+    const results = [];
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isFile() && entry.name.endsWith('.ts')) {
+                const id = entry.name.replace(/\.ts$/, '');
+                results.push({
+                    type,
+                    id,
+                    file: `${type === 'subscriber' ? 'subscribers' : type + 's'}/${entry.name}`,
+                });
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist — no primitives of this type
+    }
+    return results.sort((a, b) => a.id.localeCompare(b.id));
+}
+/**
+ * Execute the show domain command.
+ */
+export async function runShowDomain(opts) {
+    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);
+    try {
+        await stat(domainDir);
+    }
+    catch {
+        throw new Error(`Domain "${opts.domain}" not found at ${domainDir}`);
+    }
+    // Scan primitives
+    const apis = await scanPrimitives(join(domainDir, 'api'), 'api');
+    const subscribers = await scanPrimitives(join(domainDir, 'subscribers'), 'subscriber');
+    const actions = await scanPrimitives(join(domainDir, 'actions'), 'action');
+    const jobs = await scanPrimitives(join(domainDir, 'jobs'), 'job');
+    // Scan migrations for table definitions
+    const tables = [];
+    try {
+        const migrationDir = join(domainDir, 'db', 'migrations');
+        const migrationFiles = await readdir(migrationDir, { withFileTypes: true });
+        for (const entry of migrationFiles) {
+            if (entry.isFile() && entry.name.endsWith('.sql')) {
+                tables.push(entry.name);
+            }
+        }
+        tables.sort();
+    }
+    catch {
+        // No migrations directory
+    }
+    // Scan events
+    const events = [];
+    try {
+        const publishesDir = join(domainDir, 'publishes');
+        const publishFiles = await readdir(publishesDir, { withFileTypes: true });
+        for (const entry of publishFiles) {
+            if (entry.isFile() && entry.name.endsWith('.ts')) {
+                events.push(entry.name);
+            }
+        }
+        events.sort();
+    }
+    catch {
+        // No publishes directory
+    }
+    // List all files
+    const files = await listFilesRecursive(domainDir);
+    const summary = {
+        domain: opts.domain,
+        primitives: {
+            apis,
+            subscribers,
+            actions,
+            jobs,
+        },
+        tables,
+        events,
+        files,
+    };
+    cliLogger.info({ domain: opts.domain }, 'Domain summary generated');
+    return summary;
+}
+/**
+ * CLI entry point: print the structured JSON to stdout.
+ */
+export async function runShowDomainCli(opts) {
+    const summary = await runShowDomain(opts);
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(summary, null, 2));
+}

package/dist/commands/test.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Options for the test command.
+ */
+export interface TestOptions {
+    /** Absolute or relative path to the domain root. */
+    domainRoot: string;
+    /** Handler id to invoke (e.g. 'get-invoice'). */
+    handlerId: string;
+    /** Absolute or relative path to the fixture JSON file. */
+    fixturePath: string;
+}
+/**
+ * Execute the test command: build the registry, find the named handler, load the fixture,
+ * hydrate a local dev ctx, invoke the handler, and print results to stdout as JSON.
+ * @param options - TestOptions specifying domain root, handler id, and fixture path.
+ * @throws If the handler id is not found in the registry or the fixture file cannot be read.
+ */
+export declare function runTest(options: TestOptions): Promise<void>;

package/dist/commands/test.js

@@ -0,0 +1,56 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { buildRegistry } from '../builder/build-registry.js';
+import { hydrateLocalCtx } from '../runtime-stubs/hydrate-local-ctx.js';
+import { cliLogger } from '../utils/logger.js';
+/**
+ * Execute the test command: build the registry, find the named handler, load the fixture,
+ * hydrate a local dev ctx, invoke the handler, and print results to stdout as JSON.
+ * @param options - TestOptions specifying domain root, handler id, and fixture path.
+ * @throws If the handler id is not found in the registry or the fixture file cannot be read.
+ */
+export async function runTest(options) {
+    const domainRoot = resolve(options.domainRoot);
+    const fixturePath = resolve(options.fixturePath);
+    const { registry } = await buildRegistry(domainRoot);
+    const allEntries = [
+        ...registry.apis,
+        ...registry.webhooks,
+        ...registry.subscribers,
+        ...registry.schedules,
+        ...registry.jobs,
+        ...registry.actions,
+    ];
+    const entry = allEntries.find(e => e.id === options.handlerId);
+    if (!entry) {
+        throw new Error(`runTest: handler '${options.handlerId}' not found. Available: ${allEntries.map(e => e.id).join(', ')}`);
+    }
+    if (!entry.handlerFile) {
+        throw new Error(`runTest: entry '${entry.id}' has no handlerFile`);
+    }
+    const fixtureRaw = await readFile(fixturePath, 'utf8');
+    const fixture = JSON.parse(fixtureRaw);
+    const { ctx, captures } = await hydrateLocalCtx({
+        domainRoot,
+        tenantId: fixture.ctx?.tenantId,
+        actorSub: fixture.ctx?.actorSub,
+    });
+    const handlerAbsPath = join(domainRoot, entry.handlerFile);
+    const mod = await import(handlerAbsPath);
+    const def = Object.values(mod).find(v => v && typeof v === 'object' && v['id'] === entry.id);
+    if (!def || typeof def['handler'] !== 'function') {
+        throw new Error(`runTest: no handler function found for '${entry.id}' in ${handlerAbsPath}`);
+    }
+    const handler = def['handler'];
+    cliLogger.info({ handlerId: entry.id, kind: entry.kind }, 'Invoking handler');
+    let result;
+    try {
+        result = await handler(fixture.event, ctx);
+    }
+    catch (err) {
+        cliLogger.error({ err }, 'Handler threw an error');
+        process.stdout.write(JSON.stringify({ error: String(err), captures }, null, 2) + '\n');
+        process.exit(1);
+    }
+    process.stdout.write(JSON.stringify({ result, captures }, null, 2) + '\n');
+}

package/dist/commands/upgrade-backend.d.ts

@@ -0,0 +1,9 @@
+export interface UpgradeBackendOptions {
+    /** Target major version, e.g. '2' */
+    targetMajor: string;
+    /** Root of the repo (defaults to cwd) */
+    repoRoot?: string;
+    /** Dry run — print changes without applying */
+    dryRun?: boolean;
+}
+export declare function runUpgradeBackend(opts: UpgradeBackendOptions): Promise<void>;

package/dist/commands/upgrade-backend.js

@@ -0,0 +1,46 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
+const MIGRATIONS = [
+    {
+        fromMajor: 1,
+        toMajor: 2,
+        description: 'Migrate defineApi from v1 to v2: rename `versions.v1.handler` shape',
+        transform(repoRoot, dryRun) {
+            // Placeholder: real migration uses ts-morph to rewrite handler signatures
+            console.log(`[G20] Would apply: defineApi v1→v2 migration in ${repoRoot}/domains/**`);
+            if (!dryRun) {
+                console.log('[G20] ts-morph transform: (not yet implemented — add jscodeshift transforms here)');
+            }
+        },
+    },
+];
+export async function runUpgradeBackend(opts) {
+    const { targetMajor, repoRoot = process.cwd(), dryRun = false } = opts;
+    const target = parseInt(targetMajor, 10);
+    if (isNaN(target) || target < 1) {
+        throw new Error(`Invalid target major version: ${targetMajor}`);
+    }
+    // Detect current major from package.json
+    const pkgPath = join(repoRoot, 'packages', 'domain-runtime', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    const currentMajor = parseInt(pkg.version.split('.')[0] ?? '1', 10);
+    if (currentMajor >= target) {
+        console.log(`Already at v${currentMajor} — nothing to upgrade.`);
+        return;
+    }
+    const applicableMigrations = MIGRATIONS.filter(m => m.fromMajor >= currentMajor && m.toMajor <= target);
+    if (applicableMigrations.length === 0) {
+        console.log(`No migrations found from v${currentMajor} to v${target}.`);
+        return;
+    }
+    for (const migration of applicableMigrations) {
+        console.log(`Applying: v${migration.fromMajor} → v${migration.toMajor}: ${migration.description}`);
+        migration.transform(repoRoot, dryRun);
+    }
+    if (!dryRun) {
+        console.log(`\nUpgrade to v${target} complete. Run: npm run lint && npm test`);
+    }
+    else {
+        console.log(`\n[dry-run] No files changed.`);
+    }
+}

package/dist/commands/upgrade-event.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Command to upgrade an event definition to a new version.
+ * Reads the existing event definition from publishes/events.ts,
+ * adds a new version entry with proper sunset semantics on the previous version.
+ */
+/**
+ * Options for the upgrade-event command.
+ */
+export interface UpgradeEventOptions {
+    /** Domain ID in kebab-case. */
+    domain: string;
+    /** Event ID (e.g., 'domain.event'). */
+    eventId: string;
+    /** Target version number. */
+    toVersion: number;
+    /** Override directory for domain root. */
+    domainsDir?: string;
+}
+/**
+ * Execute the upgrade-event command: bump an event definition to a new version.
+ */
+export declare function runUpgradeEvent(opts: UpgradeEventOptions): Promise<void>;

package/dist/commands/upgrade-event.js

@@ -0,0 +1,111 @@
+/**
+ * Command to upgrade an event definition to a new version.
+ * Reads the existing event definition from publishes/events.ts,
+ * adds a new version entry with proper sunset semantics on the previous version.
+ */
+import { readFile, writeFile, access } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+/**
+ * Execute the upgrade-event command: bump an event definition to a new version.
+ */
+export async function runUpgradeEvent(opts) {
+    if (!KEBAB_REGEX.test(opts.domain)) {
+        throw new Error(`Invalid domain id "${opts.domain}" — must be kebab-case`);
+    }
+    if (!Number.isInteger(opts.toVersion) || opts.toVersion < 2) {
+        throw new Error(`--to-version must be an integer >= 2, got "${opts.toVersion}"`);
+    }
+    const root = opts.domainsDir ?? resolve(process.cwd(), 'domains');
+    const domainDir = join(root, opts.domain);
+    const eventsFilePath = join(domainDir, 'publishes', 'events.ts');
+    // Verify events file exists
+    try {
+        await access(eventsFilePath);
+    }
+    catch {
+        throw new Error(`Events file not found at ${eventsFilePath}. Run add-domain first.`);
+    }
+    const content = await readFile(eventsFilePath, 'utf8');
+    const newContent = upgradeEventInSource(content, opts.eventId, opts.toVersion, opts.domain);
+    if (newContent === content) {
+        throw new Error(`Event "${opts.eventId}" not found in ${eventsFilePath}, or version ${opts.toVersion - 1} not found.`);
+    }
+    await writeFile(eventsFilePath, newContent);
+    cliLogger.info({ domain: opts.domain, eventId: opts.eventId, toVersion: opts.toVersion }, 'Event upgraded');
+    // eslint-disable-next-line no-console
+    console.log(`\n✓ Event "${opts.eventId}" upgraded to version ${opts.toVersion} in ${eventsFilePath}`);
+}
+/**
+ * Upgrade an event definition in-source by adding a new version entry
+ * and marking the previous version as deprecated with a sunset date.
+ */
+function upgradeEventInSource(content, eventId, toVersion, domain) {
+    const prevVersion = toVersion - 1;
+    const sunsetDate = new Date(Date.now() + 180 * 86400 * 1000).toISOString().split('T')[0]; // 180 days from now
+    // Find the event definition block
+    // Pattern: export const eventName = defineEvent({ ... versions: [ ... ] ... });
+    const eventPattern = new RegExp(`(export\\s+const\\s+\\w+\\s*=\\s*defineEvent\\(\\{[^}]*id:\\s*['"]${escapeRegex(eventId)}['"][^}]*versions:\\s*\\[)([^\\]]*)(\\][^}]*\\}\\);)`, 's');
+    const match = eventPattern.exec(content);
+    if (!match) {
+        // Try without the export name assumption — search for the eventId
+        const altPattern = new RegExp(`('${escapeRegex(eventId)}'|"${escapeRegex(eventId)}")\\s*,\\s*\\n?\\s*versions:\\s*\\[`, 's');
+        const altMatch = altPattern.exec(content);
+        if (!altMatch) {
+            return content; // Not found — caller will detect unchanged content
+        }
+        throw new Error(`Found event "${eventId}" but could not parse its versions array. Manual edit required.`);
+    }
+    const beforeVersions = match[1];
+    const versionsContent = match[2];
+    const afterVersions = match[3];
+    // Check if the target version already exists
+    if (versionsContent.includes(`version: ${toVersion}`)) {
+        throw new Error(`Event "${eventId}" already has version ${toVersion}.`);
+    }
+    // Find the previous version and mark it deprecated
+    let updatedVersions = versionsContent;
+    // Add sunset to the previous version entry
+    const prevVersionRegex = new RegExp(`(version:\\s*${prevVersion}\\s*,[^}]*?)(\\s*\\})`, 's');
+    const prevMatch = prevVersionRegex.exec(updatedVersions);
+    if (prevMatch) {
+        // Check if already has status
+        if (!prevMatch[1].includes('status:')) {
+            updatedVersions = updatedVersions.replace(prevMatch[0], prevMatch[1].replace(`version: ${prevVersion},`, `version: ${prevVersion},\n      status: 'deprecated',\n      sunset: '${sunsetDate}',`) + prevMatch[2]);
+        }
+        else if (!prevMatch[1].includes('sunset:')) {
+            updatedVersions = updatedVersions.replace(prevMatch[0], prevMatch[1].replace(/status:\s*'stable'/, "status: 'deprecated'") + `\n      sunset: '${sunsetDate}',` + prevMatch[2]);
+        }
+    }
+    else {
+        throw new Error(`Could not find version ${prevVersion} in event "${eventId}".`);
+    }
+    // Add the new version entry
+    const newVersionEntry = `,
+    {
+      version: ${toVersion},
+      status: 'stable',
+      schema: z.object({
+        // TODO: Define the v${toVersion} schema — extend or replace v${prevVersion}
+      }),
+    }`;
+    // Insert before the closing bracket of the versions array
+    const closingBracketIndex = updatedVersions.lastIndexOf(']');
+    if (closingBracketIndex === -1) {
+        throw new Error(`Could not find closing bracket of versions array for event "${eventId}".`);
+    }
+    updatedVersions =
+        updatedVersions.slice(0, closingBracketIndex) +
+            newVersionEntry +
+            '\n  ' +
+            updatedVersions.slice(closingBracketIndex);
+    const result = beforeVersions + updatedVersions + afterVersions;
+    return result;
+}
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/commands/upgrade-frontend.d.ts

@@ -0,0 +1,5 @@
+export interface UpgradeFrontendOptions {
+    dryRun?: boolean;
+    projectDir?: string;
+}
+export declare function runUpgradeFrontend(opts?: UpgradeFrontendOptions): Promise<void>;

package/dist/commands/upgrade-frontend.js

@@ -0,0 +1,99 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+const TIB_PACKAGES = [
+    '@mettlecast/design-system',
+    '@mettlecast/dashboard-shell',
+    '@mettlecast/sdk',
+    '@mettlecast/observability',
+    '@mettlecast/eslint-config-react',
+    '@mettlecast/tsconfig-react',
+];
+const REQUIRED_PACKAGES = [
+    '@mettlecast/design-system',
+    '@mettlecast/dashboard-shell',
+    '@mettlecast/sdk',
+];
+const RECOMMENDED_PACKAGES = [
+    '@mettlecast/observability',
+    '@mettlecast/eslint-config-react',
+    '@mettlecast/tsconfig-react',
+];
+function allDeps(pkg) {
+    return { ...pkg.dependencies, ...pkg.devDependencies };
+}
+export async function runUpgradeFrontend(opts = {}) {
+    const root = opts.projectDir ? resolve(opts.projectDir) : process.cwd();
+    const pkgPath = resolve(root, 'package.json');
+    let pkg;
+    try {
+        const raw = await readFile(pkgPath, 'utf8');
+        pkg = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Could not read package.json at ${pkgPath}`);
+    }
+    const deps = allDeps(pkg);
+    const results = [];
+    for (const p of REQUIRED_PACKAGES) {
+        const installed = deps[p];
+        if (!installed) {
+            results.push({ pkg: p, status: 'missing', message: `Not installed — required. Add to dependencies.` });
+        }
+        else {
+            results.push({ pkg: p, status: 'ok', installedVersion: installed, message: `Installed at ${installed}` });
+        }
+    }
+    for (const p of RECOMMENDED_PACKAGES) {
+        const installed = deps[p];
+        if (!installed) {
+            results.push({ pkg: p, status: 'recommended', message: `Not installed — recommended for full functionality.` });
+        }
+        else {
+            results.push({ pkg: p, status: 'ok', installedVersion: installed, message: `Installed at ${installed}` });
+        }
+    }
+    // Print results
+    const symbols = {
+        ok: '✓',
+        missing: '✗',
+        outdated: '⚠',
+        recommended: '·',
+    };
+    // eslint-disable-next-line no-console
+    console.log(`\nTIB frontend upgrade check for ${pkg.name ?? root}\n`);
+    let hasErrors = false;
+    for (const r of results) {
+        // eslint-disable-next-line no-console
+        console.log(`  ${symbols[r.status]} ${r.pkg.padEnd(32)} ${r.message}`);
+        if (r.status === 'missing')
+            hasErrors = true;
+    }
+    const missingCount = results.filter(r => r.status === 'missing').length;
+    const recommendedCount = results.filter(r => r.status === 'recommended').length;
+    // eslint-disable-next-line no-console
+    console.log('');
+    if (missingCount > 0) {
+        // eslint-disable-next-line no-console
+        console.log(`  ${missingCount} required package(s) missing. Run:\n`);
+        const missing = results.filter(r => r.status === 'missing').map(r => r.pkg);
+        // eslint-disable-next-line no-console
+        console.log(`    npm install ${missing.join(' ')}\n`);
+    }
+    if (recommendedCount > 0) {
+        // eslint-disable-next-line no-console
+        console.log(`  ${recommendedCount} recommended package(s) not installed. See docs/migration/v0-to-v1.md\n`);
+    }
+    if (!hasErrors && missingCount === 0) {
+        // eslint-disable-next-line no-console
+        console.log('  All required @mettlecast/* packages are installed.\n');
+    }
+    if (opts.dryRun) {
+        // eslint-disable-next-line no-console
+        console.log('  (dry-run mode — no changes made)\n');
+    }
+    cliLogger.info({ missingCount, recommendedCount }, 'upgrade-frontend check complete');
+    if (hasErrors && !opts.dryRun) {
+        process.exit(1);
+    }
+}

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,7 @@
+export interface UpgradeOptions {
+    dryRun: boolean;
+    projectDir: string;
+    githubToken?: string;
+    frontendComponents?: boolean;
+}
+export declare function runUpgrade(packageSpec: string | undefined, opts: UpgradeOptions): Promise<void>;