@mettlecast/domain-cli 0.2.0

package/src/templates/patterns/subscriber/cascade-deletion.ts

@@ -0,0 +1,63 @@
+/**
+ * Cascade-deletion subscriber pattern template.
+ * Produces: subscriber that deletes related records when a parent is deleted.
+ */
+
+function camelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export function cascadeDeletionTemplate(domain: string, id: string, event: string): string {
+  const varName = camelCase(id);
+
+  return `import { defineSubscriber } from '@mettlecast/domain-runtime';
+
+/**
+ * ${id} — Cascading deletion triggered by ${event}.
+ *
+ * When a parent ${event} event fires, this subscriber:
+ * 1. Queries for all child records owned by the deleted parent.
+ * 2. Soft-deletes each child (sets deletedAt timestamp).
+ * 3. Emits metrics for observability.
+ */
+export const ${varName} = defineSubscriber({
+  id: '${domain}.${id}',
+  event: '${event}',
+  semverRange: '^1',
+  handler: async (event, ctx) => {
+    const { entityId, tenantId } = event.data;
+
+    // ── Find all children ────────────────────────────────────
+    const children = await ctx.db.query({
+      pk: 'TENANT#' + tenantId,
+      skPrefix: 'CHILD#' + entityId,
+    });
+
+    // ── Soft-delete each child ───────────────────────────────
+    const now = new Date().toISOString();
+    for (const child of children) {
+      await ctx.db.update({
+        key: { pk: child.pk, sk: child.sk },
+        updates: {
+          deletedAt: now,
+          deletedBy: event.data.deletedBy ?? 'system',
+        },
+      });
+    }
+
+    // ── Audit log ────────────────────────────────────────────
+    await ctx.auditLog({
+      action: 'cascade.delete',
+      tenantId,
+      entityId,
+      meta: {
+        childrenDeleted: children.length,
+        triggeredBy: event.id,
+      },
+    });
+
+    ctx.metrics?.putMetric('${id}.cascade.deleted', children.length, 'Count');
+  },
+});
+`;
+}

package/src/templates/patterns/subscriber/single-step-projection.ts

@@ -0,0 +1,39 @@
+/**
+ * Single-step-projection subscriber pattern template.
+ * Produces: subscriber that updates a read-model projection table.
+ */
+
+function camelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+export function singleStepProjectionTemplate(domain: string, id: string, event: string): string {
+  const varName = camelCase(id);
+
+  return `import { defineSubscriber } from '@mettlecast/domain-runtime';
+
+/**
+ * ${id} — Projects ${event} events into a read-optimised view.
+ */
+export const ${varName} = defineSubscriber({
+  id: '${domain}.${id}',
+  event: '${event}',
+  semverRange: '^1',
+  handler: async (event, ctx) => {
+    const { tenantId, ...eventData } = event.data;
+
+    // ── Upsert projection ────────────────────────────────────
+    // Each event updates the projection row for fast reads.
+    await ctx.db.put({
+      pk: 'TENANT#' + tenantId,
+      sk: 'PROJECTION#' + event.id,
+      ...eventData,
+      lastEventId: event.id,
+      projectedAt: new Date().toISOString(),
+    });
+
+    ctx.metrics?.putMetric('${id}.projection.applied', 1, 'Count');
+  },
+});
+`;
+}

package/src/templates/readme.ts

@@ -0,0 +1,7 @@
+/**
+ * Template for generating per-domain README.md.
+ */
+export function readmeTemplate(id: string): string {
+  const titleName = id.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+  return `# ${titleName}\n\n> One-line description of what this domain does — update this.\n\n## Overview\n\nDomain ID: \`${id}\`\n\n## API Endpoints\n\nSee \`domains/${id}/api/\` for all endpoint handlers.\n\n## Events Published\n\nSee \`domains/${id}/publishes/events.ts\` for all published event types.\n\n## Development\n\n\`\`\`bash\nnpx mc-domain-module dev domains/${id}\nnpx mc-domain-module validate domains/${id}\nnpx mc-domain-module build domains/${id}\n\`\`\`\n`;
+}

package/src/templates/subscriber-skeleton.ts

@@ -0,0 +1,28 @@
+/**
+ * Template for generating subscriber handler skeleton.
+ */
+
+/**
+ * Generates a subscriber handler skeleton.
+ * @param domainId - Domain ID in kebab-case.
+ * @param subscriberId - Subscriber ID in kebab-case.
+ * @param eventId - Event ID to subscribe to (e.g. 'domain.event').
+ * @returns TypeScript source code as a string.
+ */
+export function subscriberSkeletonTemplate(
+  domainId: string,
+  subscriberId: string,
+  eventId: string
+): string {
+  return `import { defineSubscriber } from '../../../lib/domain-runtime';
+
+export const ${subscriberId.replace(/-([a-z])/g, (_, c) => c.toUpperCase())} = defineSubscriber({
+  id: '${domainId}.${subscriberId}',
+  event: '${eventId}',
+  semverRange: '*',
+  handler: async (_event, _ctx) => {
+    // TODO: Implement subscriber handler
+  },
+});
+`;
+}

package/src/utils/checksum.ts

@@ -0,0 +1,43 @@
+import { createHash } from 'crypto';
+import { readFile } from 'fs/promises';
+
+/**
+ * Compute SHA-256 checksum of a Buffer, returning a lowercase hex string.
+ */
+export function computeChecksumBuffer(buf: Buffer): string {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * Compute SHA-256 checksum of a string (encoded as UTF-8), returning a lowercase hex string.
+ */
+export function computeChecksumString(content: string): string {
+  return createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+
+/**
+ * Compute SHA-256 checksum of a file on disk, returning a lowercase hex string.
+ * Returns null if the file does not exist.
+ */
+export async function computeChecksumFile(filePath: string): Promise<string | null> {
+  try {
+    const buf = await readFile(filePath);
+    return computeChecksumBuffer(buf);
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * Returns true if the file on disk has been modified compared to the expected checksum.
+ * Returns false if the checksums match, or null if the file does not exist.
+ */
+export async function isDrifted(
+  filePath: string,
+  expectedChecksum: string
+): Promise<boolean | null> {
+  const actual = await computeChecksumFile(filePath);
+  if (actual === null) return null;
+  return actual !== expectedChecksum;
+}

package/src/utils/file-helpers.ts

@@ -0,0 +1,91 @@
+import { readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Maps each convention slot to the absolute file paths found for that slot.
+ * For the 'domain' slot there is exactly one path (domain.config.ts).
+ * For the 'publishes' slot there is exactly one path (publishes/events.ts).
+ * All other slots may have 0..N paths.
+ */
+export interface DomainFilePaths {
+  /** Path to domain.config.ts if present. */
+  domain: string | undefined;
+  /** API handler file paths under api/. */
+  apis: string[];
+  /** Webhook handler file paths under webhooks/. */
+  webhooks: string[];
+  /** Subscriber handler file paths under subscribers/. */
+  subscribers: string[];
+  /** Action handler file paths under actions/. */
+  actions: string[];
+  /** Schedule handler file paths under schedules/. */
+  schedules: string[];
+  /** Job handler file paths under jobs/. */
+  jobs: string[];
+  /** Integration definition file paths under integrations/. */
+  integrations: string[];
+  /** Path to publishes/events.ts if present. */
+  publishes: string | undefined;
+}
+
+/**
+ * Walk a domain root directory and return the conventional file paths for each primitive slot.
+ * Only returns files with a `.ts` extension. Recurses into subdirectories but skips
+ * node_modules, __tests__, and dist directories.
+ * Returns undefined for slots where no files are found (domain.config.ts, publishes/events.ts).
+ * @param domainRoot - Absolute path to the domain directory (e.g. `.mc/domains/billing`).
+ * @returns DomainFilePaths with absolute paths.
+ */
+export async function walkDomainDir(domainRoot: string): Promise<DomainFilePaths> {
+  async function tsFiles(dir: string): Promise<string[]> {
+    const result: string[] = [];
+
+    async function walk(current: string): Promise<void> {
+      try {
+        const entries = await readdir(current, { withFileTypes: true });
+
+        for (const entry of entries) {
+          // Skip node_modules, __tests__, dist directories
+          if (entry.isDirectory()) {
+            if (['node_modules', '__tests__', 'dist', '.git'].includes(entry.name)) {
+              continue;
+            }
+            // Recurse into subdirectories
+            await walk(join(current, entry.name));
+          } else if (entry.isFile() && entry.name.endsWith('.ts')) {
+            result.push(join(current, entry.name));
+          }
+        }
+      } catch {
+        // Directory doesn't exist or is unreadable, return empty
+      }
+    }
+
+    await walk(dir);
+    return result;
+  }
+
+  async function singleTs(filePath: string): Promise<string | undefined> {
+    try {
+      await stat(filePath);
+      return filePath;
+    } catch {
+      return undefined;
+    }
+  }
+
+  const [domain, apis, webhooks, subscribers, actions, schedules, jobs, integrations, publishes] =
+    await Promise.all([
+      singleTs(join(domainRoot, 'domain.config.ts')),
+      tsFiles(join(domainRoot, 'api')),
+      tsFiles(join(domainRoot, 'webhooks')),
+      tsFiles(join(domainRoot, 'subscribers')),
+      tsFiles(join(domainRoot, 'actions')),
+      tsFiles(join(domainRoot, 'schedules')),
+      tsFiles(join(domainRoot, 'jobs')),
+      tsFiles(join(domainRoot, 'integrations')),
+      singleTs(join(domainRoot, 'publishes', 'events.ts')),
+    ]);
+
+  return { domain, apis, webhooks, subscribers, actions, schedules, jobs, integrations, publishes };
+}

package/src/utils/header-inject.ts

@@ -0,0 +1,126 @@
+import path from 'path';
+
+// Files where adding a key/comment would break schema validation — tracked via manifest only
+const JSON_SKIP_LIST = new Set([
+  'package.json',
+  'tsconfig.json',
+  'tsconfig.base.json',
+]);
+
+/**
+ * Inject the @mc-scaffold ownership header into file content.
+ * The header format depends on the file type.
+ * For JSON files in the skip list, returns content unchanged.
+ *
+ * @param content  The file content (post-token-substitution)
+ * @param filename The destination filename (used to determine type)
+ * @param moduleId The scaffold module id (e.g. 'backend-lambda')
+ * @param version  The scaffold module version (e.g. '1.0.0')
+ */
+export function injectHeader(
+  content: string,
+  filename: string,
+  moduleId: string,
+  version: string
+): string {
+  const basename = path.basename(filename);
+  const ext = path.extname(filename).toLowerCase();
+
+  if (basename.endsWith('.fixture.json')) {
+    return content;
+  }
+
+  if (ext === '.json') {
+    if (JSON_SKIP_LIST.has(basename)) {
+      return content;
+    }
+    return injectJsonHeader(content, moduleId, version);
+  }
+
+  if (ext === '.ts' || ext === '.tsx' || ext === '.js' || ext === '.jsx' || ext === '.mjs') {
+    return injectLineCommentHeader(content, '//', moduleId, version);
+  }
+
+  if (ext === '.yml' || ext === '.yaml') {
+    return injectLineCommentHeader(content, '#', moduleId, version);
+  }
+
+  if (ext === '.css' || ext === '.scss') {
+    return injectBlockCommentHeader(content, '/*', '*/', moduleId, version);
+  }
+
+  if (ext === '.html') {
+    return injectBlockCommentHeader(content, '<!--', '-->', moduleId, version);
+  }
+
+  if (ext === '.md') {
+    return content;
+  }
+
+  return content;
+}
+
+function injectLineCommentHeader(
+  content: string,
+  commentChar: string,
+  moduleId: string,
+  version: string
+): string {
+  const header = [
+    `${commentChar} @mc-scaffold: ${moduleId}@${version}`,
+    `${commentChar} This file is managed by TIB scaffold. Manual edits will be flagged during \`tib upgrade\`.`,
+    `${commentChar} To opt out of upgrade management for this file, remove these header lines.`,
+    '',
+  ].join('\n');
+
+  // Preserve shebang line if present
+  if (content.startsWith('#!')) {
+    const newlineIdx = content.indexOf('\n');
+    if (newlineIdx === -1) return content + '\n' + header;
+    return content.slice(0, newlineIdx + 1) + header + content.slice(newlineIdx + 1);
+  }
+
+  return header + content;
+}
+
+function injectBlockCommentHeader(
+  content: string,
+  open: string,
+  close: string,
+  moduleId: string,
+  version: string
+): string {
+  const header = [
+    `${open} @mc-scaffold: ${moduleId}@${version} ${close}`,
+    `${open} This file is managed by TIB scaffold. Manual edits will be flagged during \`tib upgrade\`. ${close}`,
+    '',
+  ].join('\n');
+  return header + content;
+}
+
+function injectJsonHeader(content: string, moduleId: string, version: string): string {
+  try {
+    const parsed = JSON.parse(content) as Record<string, unknown>;
+    const withHeader = { _tibScaffold: `${moduleId}@${version}`, ...parsed };
+    return JSON.stringify(withHeader, null, 2);
+  } catch {
+    return content;
+  }
+}
+
+/**
+ * Strip the @mc-scaffold header from file content (used during upgrade conflict detection).
+ */
+export function stripHeader(content: string, filename: string): string {
+  const ext = path.extname(filename).toLowerCase();
+
+  if (ext === '.ts' || ext === '.tsx' || ext === '.js' || ext === '.jsx' || ext === '.mjs') {
+    return content.replace(/^\/\/ @mc-scaffold:.*\n\/\/ This file is.*\n\/\/ To opt out.*\n\n?/, '');
+  }
+
+  if (ext === '.yml' || ext === '.yaml') {
+    return content.replace(/^# @mc-scaffold:.*\n# This file is.*\n\n?/, '');
+  }
+
+  return content;
+}

package/src/utils/install-file.ts

@@ -0,0 +1,99 @@
+import { writeFile, mkdir, access } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { computeChecksumString, computeChecksumFile } from './checksum.js';
+import type { ManifestFileEntry } from './manifest.js';
+
+export type FilePolicy = 'owned' | 'tracked' | 'seed';
+
+export interface InstallResult {
+  status: 'added' | 'updated' | 'conflict' | 'skipped' | 'unchanged';
+}
+
+/**
+ * Install a scaffold file according to its policy.
+ *
+ * - owned: always overwrite. Return 'added' if new, 'updated' if existed.
+ * - tracked: check sha256. If same → 'unchanged'. If different, check disk for drift.
+ *   If drifted → write .tib-upgrade file → 'conflict'. If not drifted → overwrite → 'updated'.
+ *   If no currentEntry → write new → 'added'.
+ * - seed: if file exists → 'skipped'. Else write → 'added'.
+ */
+export async function installScaffoldFile(
+  absPath: string,
+  content: string,
+  policy: FilePolicy,
+  currentEntry: ManifestFileEntry | undefined,
+  opts?: { dryRun?: boolean }
+): Promise<InstallResult> {
+  const dryRun = opts?.dryRun ?? false;
+  const newChecksum = computeChecksumString(content);
+
+  // Helper to check if file exists
+  const fileExists = async (path: string): Promise<boolean> => {
+    try {
+      await access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  if (policy === 'owned') {
+    // owned: always overwrite, no sha256 check
+    const exists = await fileExists(absPath);
+    if (!dryRun) {
+      await mkdir(dirname(absPath), { recursive: true });
+      await writeFile(absPath, content, 'utf-8');
+    }
+    return { status: exists ? 'updated' : 'added' };
+  }
+
+  if (policy === 'seed') {
+    // seed: never overwrite existing file
+    const exists = await fileExists(absPath);
+    if (exists) {
+      return { status: 'skipped' };
+    }
+    if (!dryRun) {
+      await mkdir(dirname(absPath), { recursive: true });
+      await writeFile(absPath, content, 'utf-8');
+    }
+    return { status: 'added' };
+  }
+
+  // policy === 'tracked'
+  if (!currentEntry) {
+    // New file: write it
+    if (!dryRun) {
+      await mkdir(dirname(absPath), { recursive: true });
+      await writeFile(absPath, content, 'utf-8');
+    }
+    return { status: 'added' };
+  }
+
+  // File exists in manifest: check if content changed
+  if (newChecksum === currentEntry.sha256) {
+    // Content unchanged
+    return { status: 'unchanged' };
+  }
+
+  // Content changed: check for drift
+  const diskChecksum = await computeChecksumFile(absPath);
+  const drifted = diskChecksum !== null && diskChecksum !== currentEntry.sha256;
+
+  if (drifted) {
+    // Drift detected: write .tib-upgrade file, don't touch original
+    if (!dryRun) {
+      await mkdir(dirname(absPath), { recursive: true });
+      await writeFile(`${absPath}.tib-upgrade`, content, 'utf-8');
+    }
+    return { status: 'conflict' };
+  }
+
+  // No drift: safe to overwrite
+  if (!dryRun) {
+    await mkdir(dirname(absPath), { recursive: true });
+    await writeFile(absPath, content, 'utf-8');
+  }
+  return { status: 'updated' };
+}

package/src/utils/logger.ts

@@ -0,0 +1,26 @@
+import pino, { type Logger } from 'pino';
+
+/**
+ * Factory that creates a pino logger with pino-pretty transport for CLI output.
+ * @param name - Optional logger name shown in pino-pretty output. Defaults to 'tib-domain'.
+ * @returns A pino Logger instance configured for human-readable terminal output.
+ */
+export function createCliLogger(name = 'tib-domain'): Logger {
+  return pino({
+    name,
+    transport: {
+      target: 'pino-pretty',
+      options: {
+        colorize: true,
+        translateTime: 'SYS:HH:MM:ss',
+        ignore: 'pid,hostname',
+      },
+    },
+  });
+}
+
+/**
+ * Default singleton CLI logger used by all domain-cli commands.
+ * Pretty-printed with timestamps to stdout.
+ */
+export const cliLogger: Logger = createCliLogger();

package/src/utils/manifest.ts

@@ -0,0 +1,137 @@
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import path from 'path';
+import { cliLogger } from './logger.js';
+
+export type FilePolicy = 'owned' | 'tracked' | 'seed';
+
+export interface ManifestFileEntry {
+  path: string;
+  module: string;
+  moduleVersion: string;
+  sha256: string;
+  wasTemplate: boolean;
+  installedAt: string;
+  policy: FilePolicy;
+}
+
+export interface TibManifest {
+  $schema: string;
+  scaffoldVersion: string;
+  createdAt: string;
+  updatedAt: string;
+  projectName: string;
+  awsRegion: string;
+  enabledModules: string[];
+  files: ManifestFileEntry[];
+}
+
+const MANIFEST_PATH = '.mc/manifest.json';
+const SCHEMA_URL = 'https://mc-scaffold.s3.amazonaws.com/schema/manifest.v3.json';
+
+export function inferPolicyFromPath(filePath: string): FilePolicy {
+  // owned: infra/, .mc/infra/, mc-deploy.yml, .github/workflows/
+  if (
+    filePath.match(/^infra\//) ||
+    filePath.match(/^\.tib\/infra\//) ||
+    filePath === 'mc-deploy.yml' ||
+    filePath.match(/^\.github\/workflows\//)
+  ) {
+    return 'owned';
+  }
+
+  // seed: specific frontend paths
+  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$/,
+  ];
+  if (seedPatterns.some((pattern) => pattern.test(filePath))) {
+    return 'seed';
+  }
+
+  // tracked: everything else
+  return 'tracked';
+}
+
+export async function readManifest(projectRoot: string): Promise<TibManifest | null> {
+  const manifestPath = path.join(projectRoot, MANIFEST_PATH);
+  try {
+    const content = await readFile(manifestPath, 'utf-8');
+    const manifest = JSON.parse(content) as TibManifest;
+
+    // v1→v2 migration: infer policy for entries missing it
+    let needsMigration = false;
+    for (const entry of manifest.files as unknown as Array<Record<string, unknown>>) {
+      if (!entry['policy']) {
+        entry['policy'] = inferPolicyFromPath(entry['path'] as string);
+        needsMigration = true;
+      }
+    }
+
+    if (needsMigration) {
+      cliLogger.info('manifest: migrating v1→v2 with inferred policies');
+      await writeManifest(projectRoot, manifest);
+    }
+
+    return manifest;
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+export async function writeManifest(projectRoot: string, manifest: TibManifest): Promise<void> {
+  const manifestPath = path.join(projectRoot, MANIFEST_PATH);
+  await mkdir(path.dirname(manifestPath), { recursive: true });
+  manifest.$schema = SCHEMA_URL;
+  manifest.updatedAt = new Date().toISOString();
+  await writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+
+export function createManifest(
+  scaffoldVersion: string,
+  projectName: string,
+  awsRegion: string,
+  enabledModules: string[]
+): TibManifest {
+  const now = new Date().toISOString();
+  return {
+    $schema: SCHEMA_URL,
+    scaffoldVersion,
+    createdAt: now,
+    updatedAt: now,
+    projectName,
+    awsRegion,
+    enabledModules,
+    files: [],
+  };
+}
+
+export function upsertManifestFile(manifest: TibManifest, entry: ManifestFileEntry): void {
+  const idx = manifest.files.findIndex((f) => f.path === entry.path);
+  if (idx === -1) {
+    manifest.files.push(entry);
+  } else {
+    manifest.files[idx] = entry;
+  }
+}
+
+export function removeManifestFile(manifest: TibManifest, filePath: string): void {
+  manifest.files = manifest.files.filter((f) => f.path !== filePath);
+}
+
+export function getManifestFile(
+  manifest: TibManifest,
+  filePath: string
+): ManifestFileEntry | undefined {
+  return manifest.files.find((f) => f.path === filePath);
+}
+
+export function isScaffoldOwned(manifest: TibManifest, filePath: string): boolean {
+  const entry = manifest.files.find((f) => f.path === filePath);
+  // Scaffold-managed means in manifest AND policy is not 'seed'
+  return entry != null && entry.policy !== 'seed';
+}