@mettlecast/domain-cli 0.2.0

package/dist/commands/add-test.js

@@ -0,0 +1,285 @@
+/**
+ * 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, mkdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+/**
+ * CamelCase conversion.
+ */
+function camelCase(s) {
+    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, primitiveId) {
+    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, primitiveId, primitiveType) {
+    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) {
+    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.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/dist/commands/audit.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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.
+ */
+/**
+ * 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;
+}
+/**
+ * Execute the audit command.
+ */
+export declare function runAudit(opts?: AuditOptions): Promise<AuditCheckResult[]>;
+/**
+ * CLI entry point: runs audit and optionally prints JSON.
+ */
+export declare function runAuditCli(opts?: AuditOptions): Promise<void>;

package/dist/commands/audit.js

@@ -0,0 +1,171 @@
+/**
+ * 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 } from './doctor.js';
+import { cliLogger } from '../utils/logger.js';
+/**
+ * Map doctor check names to rule IDs and K-node references.
+ */
+const RULE_MAP = {
+    '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) {
+    // 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) {
+    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, domain) {
+    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 = {}) {
+    const projectRoot = opts.projectRoot ?? process.cwd();
+    cliLogger.info({ domain: opts.domain, json: opts.json }, 'Running audit');
+    const report = 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 = {}) {
+    const results = await runAudit(opts);
+    if (opts.json) {
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify(results, null, 2));
+    }
+}

package/dist/commands/build-catalog.d.ts

@@ -0,0 +1,68 @@
+/** A single API entry in the catalog. */
+export interface CatalogApi {
+    id: string;
+    domainId: string;
+    path: string;
+    method: string;
+    authType: string;
+    description?: string;
+    requestSchema?: Record<string, unknown>;
+    responseSchema?: Record<string, unknown>;
+    versions?: Array<{
+        version: string;
+        requestSchema?: Record<string, unknown>;
+        responseSchema?: Record<string, unknown>;
+    }>;
+}
+/** A single action entry in the catalog. */
+export interface CatalogAction {
+    id: string;
+    domainId: string;
+    visibility: string;
+    idempotent: boolean;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
+/** A single event entry in the catalog. */
+export interface CatalogEvent {
+    id: string;
+    domainId: string;
+    description?: string;
+    versions?: Array<{
+        version: number;
+        schema: Record<string, unknown>;
+    }>;
+}
+/** A single subscriber entry in the catalog. */
+export interface CatalogSubscriber {
+    id: string;
+    domainId: string;
+    event: string;
+    semverRange: string;
+    description?: string;
+}
+/** A single domain entry in the catalog. */
+export interface CatalogDomain {
+    id: string;
+    name: string;
+    tenancy: string;
+    description?: string;
+}
+/** The combined domain catalog written to .mc/domain-registry.json. */
+export interface DomainCatalog {
+    version: 2;
+    generatedAt: string;
+    domains: CatalogDomain[];
+    apis: CatalogApi[];
+    actions: CatalogAction[];
+    events: CatalogEvent[];
+    subscribers: CatalogSubscriber[];
+}
+/**
+ * Build the combined domain catalog from all per-domain registry files.
+ * Reads .mc/{domain}-registry.json files and merges them into .mc/domain-registry.json.
+ * @param tibDir - Path to the .tib directory. Defaults to .tib in cwd.
+ * @returns The written catalog.
+ */
+export declare function runBuildCatalog(tibDir?: string): Promise<DomainCatalog>;

package/dist/commands/build-catalog.js

@@ -0,0 +1,105 @@
+import { readFile, writeFile, readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+/**
+ * Build the combined domain catalog from all per-domain registry files.
+ * Reads .mc/{domain}-registry.json files and merges them into .mc/domain-registry.json.
+ * @param tibDir - Path to the .tib directory. Defaults to .tib in cwd.
+ * @returns The written catalog.
+ */
+export async function runBuildCatalog(tibDir) {
+    const dir = tibDir ? resolve(tibDir) : join(process.cwd(), '.tib');
+    // Find all per-domain registry files
+    let files;
+    try {
+        files = await readdir(dir);
+    }
+    catch {
+        throw new Error(`build-catalog: .tib directory not found at ${dir}. Run tib build first.`);
+    }
+    const registryFiles = files.filter(f => f.endsWith('-registry.json') && f !== 'domain-registry.json');
+    if (registryFiles.length === 0) {
+        throw new Error(`build-catalog: no domain registry files found in ${dir}. Run tib build <domain> first.`);
+    }
+    const catalog = {
+        version: 2,
+        generatedAt: new Date().toISOString(),
+        domains: [],
+        apis: [],
+        actions: [],
+        events: [],
+        subscribers: [],
+    };
+    for (const file of registryFiles) {
+        const raw = await readFile(join(dir, file), 'utf8');
+        let registry;
+        try {
+            registry = JSON.parse(raw);
+        }
+        catch {
+            cliLogger.warn({ file }, 'Skipping invalid JSON registry file');
+            continue;
+        }
+        const domainEntry = registry['domain'];
+        if (!domainEntry) {
+            cliLogger.warn({ file }, 'Skipping registry file with no domain entry');
+            continue;
+        }
+        const domainId = String(domainEntry['id']);
+        catalog.domains.push({
+            id: domainId,
+            name: String(domainEntry['name'] ?? domainId),
+            tenancy: String(domainEntry['tenancy'] ?? 'none'),
+            description: domainEntry['description'],
+        });
+        const apis = registry['apis'] ?? [];
+        for (const api of apis) {
+            catalog.apis.push({
+                id: String(api['id']),
+                domainId,
+                path: String(api['path']),
+                method: String(api['method'] ?? 'ANY'),
+                authType: String(api['authType'] ?? 'jwt'),
+                description: api['description'],
+                requestSchema: api['requestSchema'],
+                responseSchema: api['responseSchema'],
+                versions: api['versions'],
+            });
+        }
+        const actions = registry['actions'] ?? [];
+        for (const action of actions) {
+            catalog.actions.push({
+                id: String(action['id']),
+                domainId,
+                visibility: String(action['visibility'] ?? 'private'),
+                idempotent: Boolean(action['idempotent'] ?? false),
+                description: action['description'],
+                inputSchema: action['inputSchema'],
+                outputSchema: action['outputSchema'],
+            });
+        }
+        const events = registry['events'] ?? [];
+        for (const event of events) {
+            catalog.events.push({
+                id: String(event['id']),
+                domainId,
+                description: event['description'],
+                versions: event['versions'],
+            });
+        }
+        const subscribers = registry['subscribers'] ?? [];
+        for (const sub of subscribers) {
+            catalog.subscribers.push({
+                id: String(sub['id']),
+                domainId,
+                event: String(sub['event']),
+                semverRange: String(sub['semverRange'] ?? '*'),
+                description: sub['description'],
+            });
+        }
+    }
+    const outPath = join(dir, 'domain-registry.json');
+    await writeFile(outPath, JSON.stringify(catalog, null, 2), 'utf8');
+    cliLogger.info({ outPath, domains: catalog.domains.length, apis: catalog.apis.length, actions: catalog.actions.length, events: catalog.events.length }, 'Domain catalog written');
+    return catalog;
+}

package/dist/commands/build-flows.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Command to build flows into a registry JSON file.
+ */
+/**
+ * Options for the build-flows command.
+ */
+export interface BuildFlowsOptions {
+    /** Project root directory. Defaults to current working directory. */
+    projectRoot?: string;
+    /** Output path for the flows registry JSON file. Defaults to .mc/flows-registry.json. */
+    outFile?: string;
+}
+/**
+ * Custom error for flow ID collisions.
+ */
+export declare class FlowIdCollisionError extends Error {
+    constructor(id: string);
+}
+/**
+ * Execute the build-flows command: scan flows/ and domains/x/flows/ directories for .ts and .json files,
+ * validate and serialize them, and write .mc/flows-registry.json.
+ * @param options - BuildFlowsOptions specifying project root and optional output path.
+ * @returns The absolute path to the written registry file.
+ * @throws If flow validation fails or IDs collide.
+ */
+export declare function runBuildFlows(options: BuildFlowsOptions): Promise<string>;