@mettlecast/domain-cli 0.2.0

package/src/commands/show.ts

@@ -0,0 +1,179 @@
+/**
+ * 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, basename } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Options for the show command.
+ */
+export interface ShowDomainOptions {
+  /** Domain ID in kebab-case. */
+  domain: string;
+  /** Override directory for domains. */
+  domainsDir?: string;
+}
+
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * 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[];
+}
+
+/**
+ * Recursively list all files in a directory, excluding node_modules and __tests__.
+ */
+async function listFilesRecursive(dir: string): Promise<string[]> {
+  const result: string[] = [];
+
+  async function walk(current: string, base: string): Promise<void> {
+    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: string, type: PrimitiveEntry['type']): Promise<PrimitiveEntry[]> {
+  const results: PrimitiveEntry[] = [];
+  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: ShowDomainOptions): Promise<DomainSummary> {
+  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: string[] = [];
+  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: string[] = [];
+  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: DomainSummary = {
+    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: ShowDomainOptions): Promise<void> {
+  const summary = await runShowDomain(opts);
+  // eslint-disable-next-line no-console
+  console.log(JSON.stringify(summary, null, 2));
+}

package/src/commands/test.ts

@@ -0,0 +1,91 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import type { RegistryEntry } from '@mettlecast/domain-cdk-packer';
+import { buildRegistry } from '../builder/build-registry.js';
+import { hydrateLocalCtx } from '../runtime-stubs/hydrate-local-ctx.js';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * 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;
+}
+
+interface Fixture {
+  event: unknown;
+  ctx?: {
+    tenantId?: string;
+    actorSub?: 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 async function runTest(options: TestOptions): Promise<void> {
+  const domainRoot = resolve(options.domainRoot);
+  const fixturePath = resolve(options.fixturePath);
+
+  const { registry } = await buildRegistry(domainRoot);
+
+  const allEntries: RegistryEntry[] = [
+    ...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) as Fixture;
+
+  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) as Record<string, unknown>;
+  const def = Object.values(mod).find(
+    v => v && typeof v === 'object' && (v as Record<string, unknown>)['id'] === entry.id
+  ) as Record<string, unknown> | undefined;
+
+  if (!def || typeof def['handler'] !== 'function') {
+    throw new Error(`runTest: no handler function found for '${entry.id}' in ${handlerAbsPath}`);
+  }
+
+  const handler = def['handler'] as (event: unknown, ctx: unknown) => Promise<unknown>;
+
+  cliLogger.info({ handlerId: entry.id, kind: entry.kind }, 'Invoking handler');
+
+  let result: unknown;
+  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/src/commands/upgrade-backend.ts

@@ -0,0 +1,72 @@
+import { execSync } from 'child_process';
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+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;
+}
+
+interface Migration {
+  fromMajor: number;
+  toMajor: number;
+  description: string;
+  transform: (repoRoot: string, dryRun: boolean) => void;
+}
+
+const MIGRATIONS: Migration[] = [
+  {
+    fromMajor: 1,
+    toMajor: 2,
+    description: 'Migrate defineApi from v1 to v2: rename `versions.v1.handler` shape',
+    transform(repoRoot: string, dryRun: boolean): void {
+      // 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: UpgradeBackendOptions): Promise<void> {
+  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')) as { version: string };
+  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/src/commands/upgrade-event.ts

@@ -0,0 +1,175 @@
+/**
+ * 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';
+
+/**
+ * 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;
+}
+
+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: UpgradeEventOptions): Promise<void> {
+  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: string,
+  eventId: string,
+  toVersion: number,
+  domain: string,
+): string {
+  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: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/commands/upgrade-frontend.ts

@@ -0,0 +1,135 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+
+export interface UpgradeFrontendOptions {
+  dryRun?: boolean;
+  projectDir?: string;
+}
+
+interface PackageJson {
+  name?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+const TIB_PACKAGES = [
+  '@mettlecast/design-system',
+  '@mettlecast/dashboard-shell',
+  '@mettlecast/sdk',
+  '@mettlecast/observability',
+  '@mettlecast/eslint-config-react',
+  '@mettlecast/tsconfig-react',
+] as const;
+
+type TibPackage = (typeof TIB_PACKAGES)[number];
+
+const REQUIRED_PACKAGES: TibPackage[] = [
+  '@mettlecast/design-system',
+  '@mettlecast/dashboard-shell',
+  '@mettlecast/sdk',
+];
+
+const RECOMMENDED_PACKAGES: TibPackage[] = [
+  '@mettlecast/observability',
+  '@mettlecast/eslint-config-react',
+  '@mettlecast/tsconfig-react',
+];
+
+interface CheckResult {
+  pkg: string;
+  status: 'ok' | 'missing' | 'outdated' | 'recommended';
+  installedVersion?: string;
+  message: string;
+}
+
+function allDeps(pkg: PackageJson): Record<string, string> {
+  return { ...pkg.dependencies, ...pkg.devDependencies };
+}
+
+export async function runUpgradeFrontend(opts: UpgradeFrontendOptions = {}): Promise<void> {
+  const root = opts.projectDir ? resolve(opts.projectDir) : process.cwd();
+  const pkgPath = resolve(root, 'package.json');
+
+  let pkg: PackageJson;
+  try {
+    const raw = await readFile(pkgPath, 'utf8');
+    pkg = JSON.parse(raw) as PackageJson;
+  } catch {
+    throw new Error(`Could not read package.json at ${pkgPath}`);
+  }
+
+  const deps = allDeps(pkg);
+  const results: CheckResult[] = [];
+
+  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: Record<CheckResult['status'], string> = {
+    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);
+  }
+}