@mettlecast/domain-cli 0.2.0

package/src/commands/explain.ts

@@ -0,0 +1,209 @@
+/**
+ * Command to explain a rule ID (ESLint rule name or doctor check name).
+ * Maps rule IDs to descriptions and K-node references.
+ */
+
+/**
+ * Options for the explain command.
+ */
+export interface ExplainOptions {
+  /** The rule ID to explain (e.g., 'no-cross-domain-internal-import'). */
+  ruleId: string;
+}
+
+/**
+ * A rule explanation entry.
+ */
+interface RuleExplanation {
+  ruleId: string;
+  title: string;
+  description: string;
+  severity: 'error' | 'warn';
+  category: 'convention' | 'security' | 'structure' | 'performance' | 'correctness';
+  kNodeRef: string;
+  fixHint: string;
+  exampleBad: string;
+  exampleGood: string;
+}
+
+/**
+ * Lookup table of rule IDs to explanations.
+ */
+const RULE_EXPLANATIONS: Record<string, RuleExplanation> = {
+  'no-cross-domain-internal-import': {
+    ruleId: 'no-cross-domain-internal-import',
+    title: 'No cross-domain internal imports',
+    description:
+      'Domain code must never import from another domain directly. Cross-domain communication must use actions (ctx.actions.call), events (ctx.publish), or defined integrations.',
+    severity: 'error',
+    category: 'structure',
+    kNodeRef: 'K:convention:no-cross-domain-import',
+    fixHint: "Replace 'import { ... } from \"../../other-domain/...\"' with 'await ctx.actions.call(\"other-domain.action-id\", input)'.",
+    exampleBad: "import { doThing } from '../../payments/api/charge';",
+    exampleGood: "await ctx.actions.call('payments.charge', { amount: 100 });",
+  },
+  'no-raw-aws-sdk': {
+    ruleId: 'no-raw-aws-sdk',
+    title: 'No raw AWS SDK imports',
+    description:
+      'Domain code must never import @aws-sdk/* directly. Use ctx-provided helpers (ctx.db, ctx.publish, ctx.secrets, ctx.fetch) or define an integration.',
+    severity: 'error',
+    category: 'structure',
+    kNodeRef: 'K:convention:tier-1-foundations',
+    fixHint: "Use ctx.db for DynamoDB, ctx.secrets for Secrets Manager, ctx.fetch for HTTP calls. For other services, define an integration via defineIntegration.",
+    exampleBad: "import { S3Client } from '@aws-sdk/client-s3';",
+    exampleGood: "await ctx.integrations.s3.putObject({ Bucket, Key, Body });",
+  },
+  'no-raw-http-server': {
+    ruleId: 'no-raw-http-server',
+    title: 'No raw HTTP server in domain code',
+    description:
+      'Domain code must not create raw HTTP servers (express, fastify, etc.). All HTTP handling goes through defineApi which is wired to API Gateway by the scaffold.',
+    severity: 'error',
+    category: 'structure',
+    kNodeRef: 'K:convention:tier-1-foundations',
+    fixHint: 'Wrap your HTTP handler with defineApi({ ... }). The scaffold handles API Gateway wiring.',
+    exampleBad: "import express from 'express';\nconst app = express();",
+    exampleGood: "export const myApi = defineApi({ id: 'my-api', path: '/v1/my-api', ... });",
+  },
+  'require-define-primitive': {
+    ruleId: 'require-define-primitive',
+    title: 'Require define primitive factories',
+    description:
+      'All domain handlers must use the appropriate factory function: defineApi for HTTP APIs, defineSubscriber for event subscribers, defineAction for cross-domain actions, defineJob for background jobs.',
+    severity: 'error',
+    category: 'structure',
+    kNodeRef: 'K:runbook:add-domain',
+    fixHint: "Wrap your handler with the appropriate define* factory from @mettlecast/domain-runtime.",
+    exampleBad: "export const handler = async (event) => ({ statusCode: 200 });",
+    exampleGood: "export const myApi = defineApi({ id: 'my-api', ... });",
+  },
+  'flow-domain-ownership': {
+    ruleId: 'flow-domain-ownership',
+    title: 'Flow domain ownership',
+    description:
+      'Every flow must have an owningDomain. Root-level flows/ directory is deprecated. Flows belong inside domains/{owningDomain}/flows/.',
+    severity: 'error',
+    category: 'structure',
+    kNodeRef: 'K:convention:flow-vs-subscriber-rule',
+    fixHint: "Move the flow file to domains/<owningDomain>/flows/<id>.ts and set owningDomain in the defineFlow call.",
+    exampleBad: "// flows/onboarding.ts (root level — deprecated)",
+    exampleGood: "// domains/auth/flows/onboarding.ts\nexport const onboarding = defineFlow({ owningDomain: 'auth', ... });",
+  },
+  'domain-configs-valid': {
+    ruleId: 'domain-configs-valid',
+    title: 'Domain configs are valid',
+    description:
+      'Every domain directory under domains/ must contain a valid domain.config.ts file exported by defineDomain().',
+    severity: 'error',
+    category: 'structure',
+    kNodeRef: 'K:runbook:add-domain',
+    fixHint: "Run 'mc-domain-module add-domain <id>' to scaffold a missing domain.",
+    exampleBad: '// domains/payments/ — missing domain.config.ts',
+    exampleGood: "// domains/payments/domain.config.ts\nexport const domain = defineDomain({ id: 'payments', tenancy: 'required' });",
+  },
+  'apis-have-versions': {
+    ruleId: 'apis-have-versions',
+    title: 'APIs declare versions',
+    description:
+      'Every defineApi must have a versions field with at least one version entry. Versioning is mandatory for API evolution.',
+    severity: 'error',
+    category: 'correctness',
+    kNodeRef: 'K:runbook:add-domain',
+    fixHint: 'Add versions: { v1: { status, input, output, handler } } to your defineApi call.',
+    exampleBad: "defineApi({ id: 'my-api', path: '/v1/my-api' }) // missing versions",
+    exampleGood: "defineApi({ id: 'my-api', path: '/v1/my-api', versions: { v1: { ... } } });",
+  },
+  'apis-have-tenancy': {
+    ruleId: 'apis-have-tenancy',
+    title: 'APIs declare tenancy',
+    description:
+      'Every defineApi must declare its tenancy mode: required (tenant-scoped), none (tenant-agnostic like registration), or system (system-internal admin).',
+    severity: 'error',
+    category: 'correctness',
+    kNodeRef: 'K:convention:tier-1-foundations',
+    fixHint: "Add tenancy: 'required' | 'none' | 'system' to your defineApi call.",
+    exampleBad: "defineApi({ id: 'my-api', path: '/v1/my-api' }) // missing tenancy",
+    exampleGood: "defineApi({ id: 'my-api', path: '/v1/my-api', tenancy: 'required' });",
+  },
+  'no-cross-domain-imports': {
+    ruleId: 'no-cross-domain-imports',
+    title: 'No cross-domain imports (doctor check)',
+    description:
+      'The doctor command scans for import statements that reference files in other domain directories. These violate domain isolation.',
+    severity: 'error',
+    category: 'structure',
+    kNodeRef: 'K:convention:no-cross-domain-import',
+    fixHint: "Use domain actions or events to communicate between domains. See 'tib explain no-cross-domain-internal-import' for details.",
+    exampleBad: "import { charge } from '../../payments/api/charge';",
+    exampleGood: "await ctx.actions.call('payments.charge', { amount: 100 });",
+  },
+  'scaffold-config-matches': {
+    ruleId: 'scaffold-config-matches',
+    title: 'Scaffold config matches on-disk domains',
+    description:
+      'The .mc/scaffold-config.json domainIds array must match the directories present under domains/. Run add-domain to sync.',
+    severity: 'error',
+    category: 'structure',
+    kNodeRef: 'K:runbook:add-domain',
+    fixHint: "Run 'mc-domain-module add-domain <id>' for missing domains, or remove stale entries from .mc/scaffold-config.json.",
+    exampleBad: '// domains/ has "billing" but .mc/scaffold-config.json does not list it',
+    exampleGood: '// Run: mc-domain-module add-domain billing',
+  },
+  'husky-hooks-installed': {
+    ruleId: 'husky-hooks-installed',
+    title: 'Husky git hooks are installed',
+    description:
+      'The .husky/pre-commit hook should be present and executable. It enforces pre-commit checks like ESLint and commit message format.',
+    severity: 'warn',
+    category: 'structure',
+    kNodeRef: 'K:runbook:add-domain',
+    fixHint: "Run 'npx husky install' to set up git hooks.",
+    exampleBad: 'Missing .husky/pre-commit',
+    exampleGood: 'npx husky install  # creates .husky/pre-commit',
+  },
+};
+
+/**
+ * Execute the explain command: look up a rule ID and print its explanation.
+ */
+export function runExplain(opts: ExplainOptions): RuleExplanation {
+  const explanation = RULE_EXPLANATIONS[opts.ruleId];
+
+  if (!explanation) {
+    const available = Object.keys(RULE_EXPLANATIONS).join(', ');
+    throw new Error(
+      `Unknown rule ID "${opts.ruleId}".\n\nAvailable rules: ${available}`,
+    );
+  }
+
+  return explanation;
+}
+
+/**
+ * CLI entry point: prints the explanation in a human-readable format.
+ */
+export function runExplainCli(opts: ExplainOptions): void {
+  const explanation = runExplain(opts);
+
+  // eslint-disable-next-line no-console
+  console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║  ${explanation.ruleId}
+╚══════════════════════════════════════════════════════════════╝
+
+  Severity:  ${explanation.severity.toUpperCase()}
+  Category:  ${explanation.category}
+  Docs:      ${explanation.kNodeRef}
+
+  ${explanation.description}
+
+  Fix: ${explanation.fixHint}
+
+  ❌ BAD:
+  ${explanation.exampleBad.split('\n').map((l) => '  ' + l).join('\n')}
+
+  ✅ GOOD:
+  ${explanation.exampleGood.split('\n').map((l) => '  ' + l).join('\n')}
+`);
+}

package/src/commands/power-tune.ts

@@ -0,0 +1,112 @@
+import { SFNClient, StartExecutionCommand, DescribeExecutionCommand } from '@aws-sdk/client-sfn';
+import { readFileSync } from 'fs';
+import path from 'path';
+import { cliLogger } from '../utils/logger.js';
+
+export async function runPowerTune(domain: string, primitive: string): Promise<void> {
+  // Load registry to find Lambda ARN
+  const registryPath = path.join(process.cwd(), '.tib', `${domain}-registry.json`);
+
+  let registry: { domain: { id: string }; functionArns?: Record<string, string> };
+  try {
+    registry = JSON.parse(readFileSync(registryPath, 'utf8'));
+  } catch {
+    cliLogger.error({}, `Registry not found at ${registryPath}. Run: tib build domains/${domain}`);
+    process.exit(1);
+  }
+
+  // Find Lambda ARN for the primitive
+  const lambdaArn = registry.functionArns?.[primitive];
+  if (!lambdaArn) {
+    cliLogger.error({}, `No Lambda ARN found for primitive '${primitive}' in domain '${domain}'.`);
+    cliLogger.error({}, `Available primitives: ${Object.keys(registry.functionArns ?? {}).join(', ')}`);
+    process.exit(1);
+  }
+
+  // Get state machine ARN
+  const stateMachineArn = process.env['POWER_TUNING_STATE_MACHINE_ARN'];
+  if (!stateMachineArn) {
+    cliLogger.error({}, 'POWER_TUNING_STATE_MACHINE_ARN environment variable not set.');
+    cliLogger.error({}, 'Deploy PowerTuningStack first and export the ARN.');
+    process.exit(1);
+  }
+
+  const sfnClient = new SFNClient({});
+
+  const input = JSON.stringify({
+    lambdaARN: lambdaArn,
+    powerValues: [128, 256, 512, 1024, 1536, 3008],
+    num: 10,
+    payload: '{}',
+    parallelInvocation: true,
+    strategy: 'cost',
+  });
+
+  cliLogger.info({ domain, primitive, lambdaArn }, 'Starting power tuning');
+
+  const startResult = await sfnClient.send(
+    new StartExecutionCommand({
+      stateMachineArn,
+      input,
+      name: `tib-power-tune-${domain}-${primitive}-${Date.now()}`,
+    })
+  );
+
+  const executionArn = startResult.executionArn!;
+  cliLogger.info({ executionArn }, 'Execution started');
+  cliLogger.info({}, 'Polling for results (this takes 1-3 minutes)...');
+
+  // Poll for completion
+  let attempts = 0;
+  const maxAttempts = 60; // 5 minutes at 5s intervals
+
+  while (attempts < maxAttempts) {
+    await new Promise(resolve => setTimeout(resolve, 5000));
+    attempts++;
+
+    const status = await sfnClient.send(new DescribeExecutionCommand({ executionArn }));
+
+    if (status.status === 'RUNNING') {
+      process.stdout.write('.');
+      continue;
+    }
+
+    process.stdout.write('\n');
+
+    if (status.status === 'SUCCEEDED') {
+      const output = JSON.parse(status.output ?? '{}');
+
+      cliLogger.info({}, '\n=== Power Tuning Results ===');
+      cliLogger.info({ domain, primitive }, 'Power tuning complete');
+
+      if (output.results && Array.isArray(output.results) && output.results.length > 0) {
+        const optimal = output.results.reduce((best: { power: number; cost: number; duration: number }, r: { power: number; cost: number; duration: number }) =>
+          r.cost < best.cost ? r : best
+        );
+
+        const baseline = output.results[0];
+        const costPercentChange = ((optimal.cost / baseline.cost - 1) * 100).toFixed(1);
+        const durationPercentChange = ((optimal.duration / baseline.duration - 1) * 100).toFixed(1);
+
+        cliLogger.info({ memory: optimal.power }, `Optimal memory size: ${optimal.power} MB`);
+        cliLogger.info({ change: costPercentChange }, `Expected cost change: ${costPercentChange}%`);
+        cliLogger.info({ change: durationPercentChange }, `Expected duration change: ${durationPercentChange}%`);
+        cliLogger.info({}, `To apply: update your domain registry config:`);
+        cliLogger.info({}, `  domains/${domain}/domain.config.ts → defaultDeployment.memory = ${optimal.power}`);
+      }
+
+      cliLogger.info({}, `Visualization: https://lambda-power-tuning.show/#${Buffer.from(JSON.stringify(output)).toString('base64')}`);
+      return;
+    }
+
+    cliLogger.error({ status }, `Execution failed with status: ${status.status}`);
+    if (status.cause) {
+      cliLogger.error({}, `Cause: ${status.cause}`);
+    }
+    process.exit(1);
+  }
+
+  cliLogger.error({}, 'Timeout: execution did not complete within 5 minutes.');
+  cliLogger.error({ executionArn }, `Check manually: aws stepfunctions describe-execution --execution-arn ${executionArn}`);
+  process.exit(1);
+}