@mettlecast/domain-cli 0.2.0

package/src/commands/add-test.ts

@@ -0,0 +1,328 @@
+/**
+ * Command to scaffold a vitest test for an existing domain primitive.
+ * Detects the primitive type (api, subscriber, action, job) and emits
+ * an appropriate vitest fixture.
+ */
+
+import { writeFile, access, readdir, mkdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Options for the add-test command.
+ */
+export interface AddTestOptions {
+  /** Domain ID in kebab-case. */
+  domain: string;
+  /** Primitive ID in kebab-case (matches the handler file name without extension). */
+  primitiveId: string;
+  /** Override directory for domain root (used in tests). */
+  domainsDir?: string;
+  /** Override project root. */
+  projectRoot?: string;
+}
+
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * CamelCase conversion.
+ */
+function camelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * Detect the primitive type by looking for the source file in domain subdirectories.
+ */
+async function detectPrimitiveType(
+  domainDir: string,
+  primitiveId: string,
+): Promise<{ type: string; sourceFile: string; testDir: string }> {
+  const candidates = [
+    { type: 'api', dir: 'api', testDir: 'api/__tests__' },
+    { type: 'subscriber', dir: 'subscribers', testDir: 'subscribers/__tests__' },
+    { type: 'action', dir: 'actions', testDir: 'actions/__tests__' },
+    { type: 'job', dir: 'jobs', testDir: 'jobs/__tests__' },
+  ];
+
+  for (const candidate of candidates) {
+    const sourceFile = join(domainDir, candidate.dir, `${primitiveId}.ts`);
+    try {
+      await access(sourceFile);
+      const testDir = join(domainDir, candidate.testDir);
+      return { type: candidate.type, sourceFile, testDir };
+    } catch {
+      // Continue to next candidate
+    }
+  }
+
+  throw new Error(
+    `Could not find primitive "${primitiveId}" in domain. ` +
+    `Looked in: api/, subscribers/, actions/, jobs/`,
+  );
+}
+
+/**
+ * Generate a vitest test template for the given primitive type.
+ */
+function testTemplate(
+  domain: string,
+  primitiveId: string,
+  primitiveType: string,
+): string {
+  const varName = camelCase(primitiveId);
+
+  switch (primitiveType) {
+    case 'api':
+      return `import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { ${varName} } from '../${primitiveId}.js';
+
+describe('${domain}.${primitiveId} (API)', () => {
+  const mockCtx = {
+    tenantId: 'test-tenant-000',
+    auditLog: vi.fn().mockResolvedValue(undefined),
+    publish: vi.fn().mockResolvedValue(undefined),
+    db: {
+      get: vi.fn().mockResolvedValue(null),
+      put: vi.fn().mockResolvedValue({}),
+      query: vi.fn().mockResolvedValue([]),
+      update: vi.fn().mockResolvedValue({}),
+    },
+    metrics: {
+      putMetric: vi.fn(),
+    },
+    secrets: {
+      get: vi.fn().mockResolvedValue('test-secret'),
+    },
+    actions: {
+      call: vi.fn().mockResolvedValue({}),
+    },
+    headers: {},
+  };
+
+  beforeAll(() => {
+    // Mock crypto.randomUUID
+    vi.stubGlobal('crypto', {
+      randomUUID: () => '00000000-0000-0000-0000-000000000000',
+    });
+  });
+
+  it('should define an API with id "${primitiveId}"', () => {
+    expect(${varName}).toBeDefined();
+    expect(${varName}.meta?.id).toBe('${primitiveId}');
+  });
+
+  it('should have a v1 handler', () => {
+    const v1Config = ${varName}.meta?.versions?.v1;
+    expect(v1Config).toBeDefined();
+    expect(v1Config.status).toBe('stable');
+    expect(typeof v1Config.handler).toBe('function');
+  });
+
+  it('should accept valid input and return a response', async () => {
+    const v1Config = ${varName}.meta?.versions?.v1;
+    if (!v1Config) throw new Error('No v1 config');
+
+    const input = {};
+    const result = await v1Config.handler(input, mockCtx);
+
+    expect(result).toBeDefined();
+  });
+});
+`;
+
+    case 'subscriber':
+      return `import { describe, it, expect, vi } from 'vitest';
+import { ${varName} } from '../${primitiveId}.js';
+
+describe('${domain}.${primitiveId} (Subscriber)', () => {
+  const mockCtx = {
+    tenantId: 'test-tenant-000',
+    auditLog: vi.fn().mockResolvedValue(undefined),
+    publish: vi.fn().mockResolvedValue(undefined),
+    db: {
+      get: vi.fn().mockResolvedValue(null),
+      put: vi.fn().mockResolvedValue({}),
+      query: vi.fn().mockResolvedValue([]),
+      update: vi.fn().mockResolvedValue({}),
+    },
+    metrics: {
+      putMetric: vi.fn(),
+    },
+    actions: {
+      call: vi.fn().mockResolvedValue({}),
+    },
+    fetch: vi.fn().mockResolvedValue({ ok: true }),
+    integrations: {},
+  };
+
+  it('should define a subscriber', () => {
+    expect(${varName}).toBeDefined();
+    expect(${varName}.meta?.event).toBeDefined();
+  });
+
+  it('should have a handler function', () => {
+    expect(typeof ${varName}.meta?.handler).toBe('function');
+  });
+
+  it('should process an event without throwing', async () => {
+    const mockEvent = {
+      id: 'evt-001',
+      type: 'test.event',
+      version: 1,
+      timestamp: new Date().toISOString(),
+      data: { tenantId: 'test-tenant-000', entityId: 'ent-001' },
+      source: 'test',
+      correlationId: 'corr-001',
+    };
+
+    await expect(
+      ${varName}.meta?.handler(mockEvent, mockCtx),
+    ).resolves.not.toThrow();
+  });
+});
+`;
+
+    case 'action':
+      return `import { describe, it, expect, vi } from 'vitest';
+import { ${varName} } from '../${primitiveId}.js';
+
+describe('${domain}.${primitiveId} (Action)', () => {
+  const mockCtx = {
+    tenantId: 'test-tenant-000',
+    auditLog: vi.fn().mockResolvedValue(undefined),
+    publish: vi.fn().mockResolvedValue(undefined),
+    db: {
+      get: vi.fn().mockResolvedValue(null),
+      put: vi.fn().mockResolvedValue({}),
+      query: vi.fn().mockResolvedValue([]),
+      update: vi.fn().mockResolvedValue({}),
+    },
+    metrics: {
+      putMetric: vi.fn(),
+    },
+    actions: {
+      call: vi.fn().mockResolvedValue({}),
+    },
+  };
+
+  it('should define an action', () => {
+    expect(${varName}).toBeDefined();
+    expect(${varName}.meta?.id).toBeDefined();
+  });
+
+  it('should have a handler function', () => {
+    expect(typeof ${varName}.meta?.handler).toBe('function');
+  });
+
+  it('should execute action with valid input', async () => {
+    const input = { tenantId: 'test-tenant-000' };
+    const result = await ${varName}.meta?.handler(input, mockCtx);
+
+    expect(result).toBeDefined();
+  });
+});
+`;
+
+    case 'job':
+      return `import { describe, it, expect, vi } from 'vitest';
+import { ${varName} } from '../${primitiveId}.js';
+
+describe('${domain}.${primitiveId} (Job)', () => {
+  const mockCtx = {
+    tenantId: 'test-tenant-000',
+    auditLog: vi.fn().mockResolvedValue(undefined),
+    publish: vi.fn().mockResolvedValue(undefined),
+    db: {
+      get: vi.fn().mockResolvedValue(null),
+      put: vi.fn().mockResolvedValue({}),
+      query: vi.fn().mockResolvedValue([]),
+      update: vi.fn().mockResolvedValue({}),
+    },
+    metrics: {
+      putMetric: vi.fn(),
+    },
+    actions: {
+      call: vi.fn().mockResolvedValue({}),
+    },
+  };
+
+  it('should define a job', () => {
+    expect(${varName}).toBeDefined();
+    expect(${varName}.meta?.id).toBeDefined();
+    expect(${varName}.meta?.maxRetries).toBeGreaterThanOrEqual(0);
+  });
+
+  it('should have a handler function', () => {
+    expect(typeof ${varName}.meta?.handler).toBe('function');
+  });
+
+  it('should execute job without throwing', async () => {
+    const input = {};
+
+    await expect(
+      ${varName}.meta?.handler(input, mockCtx),
+    ).resolves.not.toThrow();
+  });
+});
+`;
+
+    default:
+      throw new Error(`Unknown primitive type "${primitiveType}"`);
+  }
+}
+
+/**
+ * Execute the add-test command: scaffold a vitest test for a domain primitive.
+ */
+export async function runAddTest(opts: AddTestOptions): Promise<void> {
+  if (!KEBAB_REGEX.test(opts.domain)) {
+    throw new Error(`Invalid domain id "${opts.domain}" — must be kebab-case`);
+  }
+  if (!KEBAB_REGEX.test(opts.primitiveId)) {
+    throw new Error(`Invalid primitive id "${opts.primitiveId}" — must be kebab-case`);
+  }
+
+  const root = opts.domainsDir ?? resolve(process.cwd(), 'domains');
+  const domainDir = join(root, opts.domain);
+  const domainConfigPath = join(domainDir, 'domain.config.ts');
+
+  // Verify domain exists
+  try {
+    await access(domainConfigPath);
+  } catch {
+    throw new Error(`Domain "${opts.domain}" not found at ${domainDir}`);
+  }
+
+  // Detect primitive type
+  const { type, testDir } = await detectPrimitiveType(domainDir, opts.primitiveId);
+
+  // Create test directory if needed
+  try {
+    await access(testDir);
+  } catch {
+    await mkdir(testDir, { recursive: true });
+  }
+
+  const testFilePath = join(testDir, `${opts.primitiveId}.test.ts`);
+
+  // Refuse if test already exists
+  try {
+    await access(testFilePath);
+    throw new Error(`Test file already exists at ${testFilePath}`);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw err;
+    }
+  }
+
+  const content = testTemplate(opts.domain, opts.primitiveId, type);
+
+  await writeFile(testFilePath, content);
+
+  cliLogger.info({ domain: opts.domain, primitiveId: opts.primitiveId, type, file: testFilePath }, 'Test scaffolded');
+  // eslint-disable-next-line no-console
+  console.log(
+    `\n✓ Test for "${opts.primitiveId}" (${type}) added at ${testFilePath}`,
+  );
+}

package/src/commands/audit.ts

@@ -0,0 +1,217 @@
+/**
+ * Command to run the doctor checks, optionally filtered to one domain.
+ * Wraps the runDoctor function from doctor.ts.
+ * When --json is passed, returns structured JSON with per-check ruleId, file, line, message, fixHint, kNodeRef.
+ */
+
+import { runDoctor, type DoctorReport, type DoctorCheck } from './doctor.js';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Options for the audit command.
+ */
+export interface AuditOptions {
+  /** Optional domain filter (only run checks relevant to this domain). */
+  domain?: string;
+  /** Output structured JSON instead of pretty table. */
+  json?: boolean;
+  /** Root directory of the project. */
+  projectRoot?: string;
+  /** Exit with code 1 on any FAIL. */
+  strict?: boolean;
+}
+
+/**
+ * Enhanced check result for JSON output.
+ */
+export interface AuditCheckResult {
+  ruleId: string;
+  name: string;
+  status: 'PASS' | 'WARN' | 'FAIL';
+  message: string;
+  file?: string;
+  line?: number;
+  fixHint?: string;
+  kNodeRef?: string;
+}
+
+/**
+ * Map doctor check names to rule IDs and K-node references.
+ */
+const RULE_MAP: Record<string, { ruleId: string; kNodeRef: string }> = {
+  'Domain configs valid': {
+    ruleId: 'domain-configs-valid',
+    kNodeRef: 'K:runbook:add-domain',
+  },
+  'No raw AWS SDK in domains': {
+    ruleId: 'no-raw-aws-sdk',
+    kNodeRef: 'K:convention:tier-1-foundations',
+  },
+  'No cross-domain imports': {
+    ruleId: 'no-cross-domain-internal-import',
+    kNodeRef: 'K:convention:no-cross-domain-import',
+  },
+  'APIs declare versions': {
+    ruleId: 'apis-have-versions',
+    kNodeRef: 'K:runbook:add-domain',
+  },
+  'APIs declare tenancy': {
+    ruleId: 'apis-have-tenancy',
+    kNodeRef: 'K:convention:tier-1-foundations',
+  },
+  'scaffold-config.json matches on-disk': {
+    ruleId: 'scaffold-config-matches',
+    kNodeRef: 'K:runbook:add-domain',
+  },
+  'Husky hooks installed': {
+    ruleId: 'husky-hooks-installed',
+    kNodeRef: 'K:runbook:add-domain',
+  },
+  'No root-level flows (deprecated)': {
+    ruleId: 'flow-domain-ownership',
+    kNodeRef: 'K:convention:flow-vs-subscriber-rule',
+  },
+  // W2 checks
+  'Every API has a fixture': {
+    ruleId: 'api-fixtures-exist',
+    kNodeRef: 'K:exit-gate:domain-complete',
+  },
+  'Every event has consumer or annotation': {
+    ruleId: 'event-consumers-exist',
+    kNodeRef: 'K:convention:flow-vs-subscriber-rule',
+  },
+  'Migrations declare tenancy trio': {
+    ruleId: 'migration-tenancy-trio',
+    kNodeRef: 'K:convention:tenancy-trio',
+  },
+  'Domain has RLS test': {
+    ruleId: 'domain-rls-test',
+    kNodeRef: 'K:convention:rls-per-domain-role',
+  },
+  'Domain reachable in brain': {
+    ruleId: 'domain-brain-reachable',
+    kNodeRef: 'K:runbook:add-domain',
+  },
+  'Actions have types': {
+    ruleId: 'actions-have-types',
+    kNodeRef: 'K:exit-gate:domain-complete',
+  },
+  'Conventions have evidence': {
+    ruleId: 'conventions-have-evidence',
+    kNodeRef: 'K:exit-gate:domain-complete',
+  },
+};
+
+/**
+ * Parse file and line information from a doctor check message.
+ */
+function parseFileAndLine(message: string): { file?: string; line?: number } {
+  // Try to match patterns like "path/to/file.ts:42" or "file.ts:42"
+  const match = message.match(/([^\s:"]+\.ts):(\d+)/);
+  if (match) {
+    return { file: match[1], line: parseInt(match[2], 10) };
+  }
+  return {};
+}
+
+/**
+ * Convert a DoctorCheck to an AuditCheckResult.
+ */
+function toAuditCheck(check: DoctorCheck): AuditCheckResult {
+  const mapping = RULE_MAP[check.name] ?? {
+    ruleId: check.name.toLowerCase().replace(/\s+/g, '-'),
+    kNodeRef: undefined,
+  };
+  const { file, line } = parseFileAndLine(check.message);
+
+  return {
+    ruleId: mapping.ruleId,
+    name: check.name,
+    status: check.status,
+    message: check.message,
+    // Use parsed file/line from message
+    file,
+    line,
+    fixHint: check.fixHint,
+    kNodeRef: check.kNodeRef ?? mapping.kNodeRef,
+  };
+}
+
+/**
+ * Filter doctor checks to a specific domain (heuristic: check if domain name appears in message or file).
+ */
+function filterChecksForDomain(checks: DoctorCheck[], domain: string): DoctorCheck[] {
+  return checks.filter((check) => {
+    if (check.message.includes(domain) || (check.fixHint && check.fixHint.includes(domain))) {
+      return true;
+    }
+    return check.message.includes(`domains/${domain}/`) || check.message.includes(`'${domain}'`);
+  });
+}
+
+/**
+ * Execute the audit command.
+ */
+export async function runAudit(opts: AuditOptions = {}): Promise<AuditCheckResult[]> {
+  const projectRoot = opts.projectRoot ?? process.cwd();
+
+  cliLogger.info({ domain: opts.domain, json: opts.json }, 'Running audit');
+
+  const report: DoctorReport = await runDoctor({
+    projectRoot,
+  });
+
+  let checks = report.checks;
+
+  // Filter by domain if specified
+  if (opts.domain) {
+    const filtered = filterChecksForDomain(checks, opts.domain);
+    if (filtered.length === 0) {
+      checks = checks.filter(
+        (c) =>
+          c.name === 'Domain configs valid' ||
+          c.name === 'scaffold-config.json matches on-disk',
+      );
+    } else {
+      checks = filtered;
+    }
+  }
+
+  const results = checks.map(toAuditCheck);
+
+  if (opts.json) {
+    return results;
+  }
+
+  // Pretty-print table
+  // eslint-disable-next-line no-console
+  console.log('\n=== TIB Audit' + (opts.domain ? ` — ${opts.domain}` : '') + ' ===\n');
+  for (const result of results) {
+    const symbol = result.status === 'PASS' ? '✓' : result.status === 'WARN' ? '⚠' : '✗';
+    // eslint-disable-next-line no-console
+    console.log(`${symbol} [${result.ruleId}] ${result.message}`);
+    if (result.fixHint) {
+      // eslint-disable-next-line no-console
+      console.log(`  Fix: ${result.fixHint}`);
+    }
+    if (result.kNodeRef) {
+      // eslint-disable-next-line no-console
+      console.log(`  Docs: ${result.kNodeRef}`);
+    }
+  }
+  // eslint-disable-next-line no-console
+  console.log('');
+
+  return results;
+}
+
+/**
+ * CLI entry point: runs audit and optionally prints JSON.
+ */
+export async function runAuditCli(opts: AuditOptions = {}): Promise<void> {
+  const results = await runAudit(opts);
+  if (opts.json) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(results, null, 2));
+  }
+}