@mettlecast/domain-cli 0.2.0

package/src/commands/add-domain.ts

@@ -0,0 +1,100 @@
+/**
+ * Command to scaffold a new domain skeleton.
+ */
+
+import { mkdir, writeFile, access, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { domainConfigTemplate } from '../templates/domain-config.js';
+import { apiSkeletonTemplate, apiFixtureSkeleton } from '../templates/api-skeleton.js';
+import { eventsSkeletonTemplate } from '../templates/events-skeleton.js';
+import { claudeMdTemplate } from '../templates/claude-md.js';
+import { readmeTemplate } from '../templates/readme.js';
+import { addDomainToScaffoldConfig } from '../utils/scaffold-config.js';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Options for the add-domain command.
+ */
+export interface AddDomainOptions {
+  /** Domain ID in kebab-case. */
+  id: string;
+  /** Tenancy mode: 'required', 'none', or 'system'. */
+  tenancy: 'required' | 'none' | 'system';
+  /** Override directory for domain root (used in tests). */
+  domainsDir?: string;
+}
+
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Execute the add-domain command: scaffold a new domain under domains/<id>
+ * and register it in .mc/scaffold-config.json.
+ * @param opts - AddDomainOptions specifying the domain ID and tenancy mode.
+ * @throws If domain ID is invalid, domain already exists, or file operations fail.
+ */
+export async function runAddDomain(opts: AddDomainOptions): Promise<void> {
+  if (!KEBAB_REGEX.test(opts.id)) {
+    throw new Error(`Invalid domain id "${opts.id}" — must be kebab-case (lowercase with hyphens)`);
+  }
+
+  const root = opts.domainsDir ?? resolve(process.cwd(), 'domains');
+  const domainDir = join(root, opts.id);
+
+  // Refuse if domain already exists
+  try {
+    await access(domainDir);
+    throw new Error(`Domain "${opts.id}" already exists at ${domainDir}`);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw err;
+    }
+  }
+
+  // Create directory structure
+  await mkdir(join(domainDir, 'api', '__tests__'), { recursive: true });
+  await mkdir(join(domainDir, 'subscribers'), { recursive: true });
+  await mkdir(join(domainDir, 'publishes'), { recursive: true });
+
+  // Write skeleton files
+  await writeFile(join(domainDir, 'domain.config.ts'), domainConfigTemplate(opts.id, opts.tenancy));
+  await writeFile(
+    join(domainDir, 'api', 'example.ts'),
+    apiSkeletonTemplate(opts.id, 'example', opts.tenancy)
+  );
+  await writeFile(
+    join(domainDir, 'api', '__tests__', 'example.fixture.json'),
+    apiFixtureSkeleton(opts.id, 'example')
+  );
+  await writeFile(join(domainDir, 'publishes', 'events.ts'), eventsSkeletonTemplate(opts.id));
+  await writeFile(join(domainDir, 'CLAUDE.md'), claudeMdTemplate(opts.id));
+  await writeFile(join(domainDir, 'README.md'), readmeTemplate(opts.id));
+
+  // Generate package.json for L1 graph scanner auto-detection
+  let projectScope = 'project';
+  try {
+    const pkgRaw = await readFile(join(resolve(opts.domainsDir ?? process.cwd(), '..'), 'package.json'), 'utf8');
+    const rootPkg = JSON.parse(pkgRaw) as { name?: string };
+    if (rootPkg.name) {
+      const match = /^@([^/]+)/.exec(rootPkg.name);
+      projectScope = match ? match[1] : rootPkg.name;
+    }
+  } catch { /* fall back to 'project' */ }
+
+  await writeFile(join(domainDir, 'package.json'), JSON.stringify({
+    name: `@${projectScope}/domain-${opts.id}`,
+    version: '0.1.0',
+    private: true,
+    description: `Domain module for ${opts.id}`,
+  }, null, 2) + '\n');
+
+  // Register domain in scaffold config
+  const configRoot = opts.domainsDir ?? process.cwd();
+  await addDomainToScaffoldConfig(opts.id, configRoot);
+
+  cliLogger.info({ id: opts.id, dir: domainDir }, 'Domain scaffolded');
+  // eslint-disable-next-line no-console
+  console.log(
+    `\n✓ Domain "${opts.id}" added at ${domainDir}\nNext: edit api/example.ts, ` +
+      `then run \`mc-domain-module build ${opts.id}\` to generate the registry.`
+  );
+}

package/src/commands/add-flow.ts

@@ -0,0 +1,136 @@
+import { mkdir, writeFile, access } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { fanOutReactionTemplate } from '../templates/patterns/flow/fan-out-reaction.js';
+import { multiStepOrchestrationTemplate } from '../templates/patterns/flow/multi-step-orchestration.js';
+import { autonomousRemediationTemplate } from '../templates/patterns/flow/autonomous-remediation.js';
+import { humanInLoopTemplate } from '../templates/patterns/flow/human-in-loop.js';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Valid flow pattern IDs.
+ */
+export const FLOW_PATTERNS = [
+  'fan-out-reaction',
+  'multi-step-orchestration',
+  'autonomous-remediation',
+  'human-in-loop',
+] as const;
+
+export type FlowPattern = (typeof FLOW_PATTERNS)[number];
+
+export interface AddFlowOptions {
+  domain: string;
+  id: string;
+  type?: 'express' | 'standard';
+  /** Pattern template ID (optional). */
+  pattern?: FlowPattern;
+  projectRoot?: string;
+}
+
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+
+function toCamelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c: string) => (c as string).toUpperCase());
+}
+
+function flowSkeletonTemplate(domain: string, id: string, type: 'express' | 'standard'): string {
+  const varName = toCamelCase(id);
+  return `import { defineFlow } from '@mettlecast/domain-runtime';
+
+export const ${varName} = defineFlow({
+  id: '${id}',
+  owningDomain: '${domain}',
+  type: '${type}',
+  name: '${id}',
+  steps: [
+    {
+      type: 'domain-action',
+      name: 'ExampleAction',
+      domainId: '${domain}',
+      actionId: 'example-action',
+      next: 'Done',
+    },
+    {
+      type: 'flow-control',
+      control: 'succeed',
+      name: 'Done',
+    },
+  ],
+});
+`;
+}
+
+export async function runAddFlow(opts: AddFlowOptions): 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.id)) {
+    throw new Error(`Invalid flow id "${opts.id}" — must be kebab-case (lowercase with hyphens)`);
+  }
+
+  const root = opts.projectRoot ?? resolve(process.cwd());
+  const flowType = opts.type ?? 'express';
+
+  // Verify domain exists
+  const domainDir = join(root, 'domains', opts.domain);
+  try {
+    await access(domainDir);
+  } catch {
+    throw new Error(`Domain "${opts.domain}" does not exist at ${domainDir}`);
+  }
+
+  const flowsDir = join(domainDir, 'flows');
+  const flowFile = join(flowsDir, `${opts.id}.ts`);
+
+  // Refuse if flow already exists
+  try {
+    await access(flowFile);
+    throw new Error(`Flow "${opts.id}" already exists at ${flowFile}`);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw err;
+    }
+  }
+
+  await mkdir(flowsDir, { recursive: true });
+
+  // Resolve template content
+  let flowContent: string;
+  if (opts.pattern) {
+    flowContent = resolveFlowPattern(opts.pattern, opts.domain, opts.id);
+    cliLogger.info({ pattern: opts.pattern }, 'Using pattern template');
+  } else {
+    flowContent = flowSkeletonTemplate(opts.domain, opts.id, flowType);
+  }
+
+  await writeFile(flowFile, flowContent);
+
+  cliLogger.info({ domain: opts.domain, id: opts.id, file: flowFile, pattern: opts.pattern ?? 'skeleton' }, 'Flow scaffolded');
+  // eslint-disable-next-line no-console
+  console.log(
+    `\n✓ Flow "${opts.id}" added at ${flowFile}\nNext: edit the flow definition, ` +
+      `then run \`mc-domain-module build-flows\` to generate the registry.`
+  );
+}
+
+/**
+ * Resolve a flow pattern template to its generated TypeScript source.
+ */
+function resolveFlowPattern(
+  pattern: FlowPattern,
+  domain: string,
+  id: string,
+): string {
+  switch (pattern) {
+    case 'fan-out-reaction':
+      return fanOutReactionTemplate(domain, id);
+    case 'multi-step-orchestration':
+      return multiStepOrchestrationTemplate(domain, id);
+    case 'autonomous-remediation':
+      return autonomousRemediationTemplate(domain, id);
+    case 'human-in-loop':
+      return humanInLoopTemplate(domain, id);
+    default:
+      throw new Error(`Unknown flow pattern "${pattern}". Available: ${FLOW_PATTERNS.join(', ')}`);
+  }
+}

package/src/commands/add-hook.ts

@@ -0,0 +1,100 @@
+/**
+ * Command: tib add-hook <name> --pattern <pattern>
+ *
+ * Scaffolds a typed data-fetching hook using TanStack Query and @mettlecast/sdk.
+ */
+import { writeFile, mkdir, access } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { cliLogger } from '../utils/logger.js';
+import {
+  paginatedListHookTemplate,
+  mutationHookTemplate,
+  featureFlagHookTemplate,
+  subscriptionHookTemplate,
+} from '../templates/patterns/hook/index.js';
+
+/** Supported hook patterns. */
+export type HookPattern = 'paginated-list' | 'mutation' | 'feature-flag' | 'subscription';
+
+export const HOOK_PATTERNS: readonly HookPattern[] = [
+  'paginated-list',
+  'mutation',
+  'feature-flag',
+  'subscription',
+] as const;
+
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+
+const PATTERN_TEMPLATES: Record<HookPattern, (name: string) => string> = {
+  'paginated-list': paginatedListHookTemplate,
+  mutation: mutationHookTemplate,
+  'feature-flag': featureFlagHookTemplate,
+  subscription: subscriptionHookTemplate,
+};
+
+export interface AddHookOptions {
+  /** Hook name in kebab-case (e.g. "search-items"). */
+  name: string;
+  /** Hook pattern to scaffold. */
+  pattern: HookPattern;
+  /** Override the output directory (default: src/hooks/). */
+  outputDir?: string;
+}
+
+/**
+ * Scaffold a typed data-fetching hook file.
+ */
+export async function runAddHook(opts: AddHookOptions): Promise<void> {
+  const { name, pattern, outputDir } = opts;
+
+  if (!KEBAB_REGEX.test(name)) {
+    throw new Error(`Invalid hook name "${name}" — must be kebab-case`);
+  }
+
+  if (!HOOK_PATTERNS.includes(pattern)) {
+    const available = HOOK_PATTERNS.join(', ');
+    throw new Error(
+      `Unknown hook pattern "${pattern}".\n\nAvailable patterns: ${available}`
+    );
+  }
+
+  const templateFn = PATTERN_TEMPLATES[pattern];
+  const content = templateFn(name);
+
+  const outDir = outputDir
+    ? resolve(outputDir)
+    : resolve(process.cwd(), 'src', 'hooks');
+
+  await mkdir(outDir, { recursive: true });
+
+  const fileName = `use-${name}.ts`;
+  const outPath = join(outDir, fileName);
+
+  // Refuse if target already exists
+  try {
+    await access(outPath);
+    throw new Error(
+      `Hook file already exists at ${outPath}. Remove it first or use a different --output directory.`
+    );
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
+  }
+
+  await writeFile(outPath, content, 'utf8');
+
+  cliLogger.info({ name, pattern, outPath }, 'Hook scaffolded');
+  // eslint-disable-next-line no-console
+  console.log(
+    `\n✓ Hook "use-${name}" (pattern: ${pattern}) added at ${outPath}\n` +
+    `  Import: import { use${capitalize(name)} } from './hooks/use-${name}';\n` +
+    `  Pattern: ${pattern}\n`
+  );
+}
+
+/** Capitalizes the first character of a kebab-case name into PascalCase. */
+function capitalize(s: string): string {
+  return s
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}

package/src/commands/add-migration.ts

@@ -0,0 +1,129 @@
+/**
+ * Command to add a new database migration to an existing domain.
+ * Supports --pattern for predefined migration templates.
+ */
+
+import { writeFile, access, mkdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { tenantScopedTableTemplate } from '../templates/patterns/migration/tenant-scoped-table.js';
+import { rlsPolicyTemplate } from '../templates/patterns/migration/rls-policy.js';
+import { columnAddTemplate } from '../templates/patterns/migration/column-add.js';
+import { indexTemplate } from '../templates/patterns/migration/index.js';
+import { eventStoreTemplate } from '../templates/patterns/migration/event-store.js';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Valid migration pattern IDs.
+ */
+export const MIGRATION_PATTERNS = [
+  'tenant-scoped-table',
+  'rls-policy',
+  'column-add',
+  'index',
+  'event-store',
+] as const;
+
+export type MigrationPattern = (typeof MIGRATION_PATTERNS)[number];
+
+/**
+ * Options for the add-migration command.
+ */
+export interface AddMigrationOptions {
+  /** Domain ID in kebab-case. */
+  domain: string;
+  /** Migration name in kebab-case. */
+  name: string;
+  /** Pattern template ID (required). */
+  pattern: MigrationPattern;
+  /** Override directory for domain root (used in tests). */
+  domainsDir?: string;
+}
+
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Generates a timestamp prefix matching the project convention.
+ */
+function generateTimestamp(): string {
+  return new Date().toISOString().replace(/[-:T.]/g, '').slice(0, 14);
+}
+
+/**
+ * Execute the add-migration command: create a new SQL migration in an existing domain.
+ */
+export async function runAddMigration(opts: AddMigrationOptions): 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.name)) {
+    throw new Error(`Invalid migration name "${opts.name}" — must be kebab-case`);
+  }
+  if (!MIGRATION_PATTERNS.includes(opts.pattern)) {
+    throw new Error(
+      `Unknown migration pattern "${opts.pattern}". Available: ${MIGRATION_PATTERNS.join(', ')}`,
+    );
+  }
+
+  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}`);
+  }
+
+  const migrationsDir = join(domainDir, 'db', 'migrations');
+  await mkdir(migrationsDir, { recursive: true });
+
+  const timestamp = generateTimestamp();
+  const fileName = `${timestamp}_${opts.name}.sql`;
+  const filePath = join(migrationsDir, fileName);
+
+  // Refuse if migration already exists
+  try {
+    await access(filePath);
+    throw new Error(`Migration "${fileName}" already exists at ${filePath}`);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw err;
+    }
+  }
+
+  // Resolve pattern template
+  const sqlContent = resolveMigrationPattern(opts.pattern, opts.domain, opts.name);
+
+  await writeFile(filePath, sqlContent);
+
+  cliLogger.info({ domain: opts.domain, migration: opts.name, pattern: opts.pattern, file: filePath }, 'Migration added');
+  // eslint-disable-next-line no-console
+  console.log(
+    `\n✓ Migration "${opts.name}" added to domain "${opts.domain}" at ${filePath}`,
+  );
+}
+
+/**
+ * Resolve a migration pattern template to its generated SQL source.
+ */
+function resolveMigrationPattern(
+  pattern: MigrationPattern,
+  domain: string,
+  name: string,
+): string {
+  switch (pattern) {
+    case 'tenant-scoped-table':
+      return tenantScopedTableTemplate(domain, name);
+    case 'rls-policy':
+      return rlsPolicyTemplate(domain, name);
+    case 'column-add':
+      return columnAddTemplate(domain, name);
+    case 'index':
+      return indexTemplate(domain, name);
+    case 'event-store':
+      return eventStoreTemplate(domain, name);
+    default:
+      throw new Error(`Unknown migration pattern "${pattern}". Available: ${MIGRATION_PATTERNS.join(', ')}`);
+  }
+}