@mettlecast/domain-cli 0.2.0

package/src/commands/add-seed-page.ts

@@ -0,0 +1,338 @@
+import { mkdir, writeFile, access } from 'node:fs/promises';
+import { join, resolve, dirname } from 'node:path';
+import { execSync } from 'node:child_process';
+import { createGunzip } from 'node:zlib';
+import { Readable } from 'node:stream';
+import { extract } from 'tar';
+import { cliLogger } from '../utils/logger.js';
+import {
+  fetchVersionsJson,
+  fetchModulesJson,
+  fetchModuleTarball,
+} from '../utils/s3-fetch.js';
+import { readManifest } from '../utils/manifest.js';
+import { readScaffoldConfig } from '../utils/scaffold-config.js';
+
+const SCAFFOLD_BUCKET = 'mc-scaffold';
+
+// ── Tarball types ──────────────────────────────────────────────────────────────
+
+interface TarEntry {
+  path: string;
+  content: Buffer;
+}
+
+export interface AddSeedPageOptions {
+  pageName: string;
+  projectDir?: string;
+}
+
+// ── GitHub helpers ─────────────────────────────────────────────────────────────
+
+function detectGitRemote(projectDir: string): { owner: string; repo: string } | null {
+  try {
+    const url = execSync('git remote get-url origin', {
+      cwd: projectDir,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+
+    const sshMatch = url.match(/git@github\.com:([^/]+)\/([^.]+?)(?:\.git)?$/);
+    if (sshMatch) return { owner: sshMatch[1], repo: sshMatch[2] };
+
+    const httpsMatch = url.match(/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:\/)?$/);
+    if (httpsMatch) return { owner: httpsMatch[1], repo: httpsMatch[2] };
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+async function createGitHubPR(
+  owner: string,
+  repo: string,
+  token: string,
+  branch: string,
+  title: string,
+  body: string
+): Promise<{ url: string; number: number }> {
+  const url = `https://api.github.com/repos/${owner}/${repo}/pulls`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: 'application/vnd.github+json',
+      'Content-Type': 'application/json',
+      'X-GitHub-Api-Version': '2022-11-28',
+    },
+    body: JSON.stringify({
+      title,
+      body,
+      head: branch,
+      base: 'develop',
+    }),
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`GitHub PR creation failed (${res.status}): ${err}`);
+  }
+
+  const data = (await res.json()) as { html_url: string; number: number };
+  return { url: data.html_url, number: data.number };
+}
+
+// ── Page discovery ─────────────────────────────────────────────────────────────
+
+function getCategoryForPageId(pageId: string): string {
+  const authPages = [
+    'login',
+    'signup',
+    'verify-email',
+    'forgot-password',
+    'reset-password',
+    'mfa-setup',
+    'mfa-verify',
+    'choose-org',
+    'accept-invitation',
+    'sign-out',
+  ];
+  const accountPages = ['profile', 'workspace-settings', 'members', 'api-keys', 'audit-log'];
+
+  if (authPages.includes(pageId)) return 'auth';
+  if (accountPages.includes(pageId)) return 'account';
+  return 'shell';
+}
+
+// ── Tarball parsing ────────────────────────────────────────────────────────────
+
+async function parseTarball(buf: Buffer): Promise<TarEntry[]> {
+  const decompressed = await new Promise<Buffer>((res, rej) => {
+    const gunzip = createGunzip();
+    const chunks: Buffer[] = [];
+    const input = Readable.from(buf);
+    input.pipe(gunzip);
+    gunzip.on('data', (chunk: Buffer) =>
+      chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as ArrayBuffer))
+    );
+    gunzip.on('end', () => res(Buffer.concat(chunks)));
+    gunzip.on('error', rej);
+  });
+
+  const entries: TarEntry[] = [];
+  let offset = 0;
+
+  while (offset + 512 <= decompressed.length) {
+    const header = decompressed.slice(offset, offset + 512);
+    if (header.every((b) => b === 0)) break;
+
+    let name = header.slice(0, 100).toString('utf-8').replace(/\0.*/, '');
+    const prefix = header.slice(345, 500).toString('utf-8').replace(/\0.*/, '');
+    if (prefix) name = `${prefix}/${name}`;
+
+    const sizeStr = header.slice(124, 136).toString('utf-8').replace(/\0.*/, '').trim();
+    const size = parseInt(sizeStr, 8) || 0;
+    const typeFlag = header[156];
+    const isRegularFile = typeFlag === 0x30 || typeFlag === 0 || typeFlag === undefined;
+
+    offset += 512;
+
+    if (isRegularFile && name && size > 0) {
+      const content = decompressed.slice(offset, offset + size);
+      entries.push({ path: name, content });
+    }
+
+    offset += Math.ceil(size / 512) * 512;
+  }
+
+  return entries;
+}
+
+function getTarEntry(entries: TarEntry[], targetPath: string): TarEntry | undefined {
+  return entries.find((e) => {
+    const normalized = e.path.replace(/^\.\//, '').replace(/^[^/]+\//, '');
+    return normalized === targetPath || e.path === targetPath || e.path.endsWith(`/${targetPath}`);
+  });
+}
+
+// ── Main export ────────────────────────────────────────────────────────────────
+
+export async function runAddSeedPage(opts: AddSeedPageOptions): Promise<void> {
+  const projectDir = resolve(opts.projectDir ?? process.cwd());
+  const { pageName } = opts;
+
+  console.log(`\nTIB Add Seed Page\n`);
+  console.log(`Project: ${projectDir}\n`);
+  console.log(`Page: ${pageName}\n`);
+
+  // 1. Read manifest + scaffold-config
+  const manifest = await readManifest(projectDir);
+  if (!manifest) {
+    throw new Error(
+      `.mc/manifest.json not found in ${projectDir}. Is this a TIB scaffold project?`
+    );
+  }
+
+  const scaffoldConfig = await readScaffoldConfig(projectDir);
+  const bucket = scaffoldConfig.scaffoldBucket ?? SCAFFOLD_BUCKET;
+
+  // 2. Get latest version
+  const versionsJson = await fetchVersionsJson(bucket);
+  const latestVersion = versionsJson.latest;
+
+  console.log(`Latest scaffold version: ${latestVersion}\n`);
+
+  // 3. Fetch frontend module tarball
+  const modulesJson = await fetchModulesJson(bucket, latestVersion);
+  const frontendModule = modulesJson.modules.find((m) => m.id === 'frontend');
+  if (!frontendModule) {
+    throw new Error(`Frontend module not found in modules.json for version ${latestVersion}`);
+  }
+
+  console.log(`Fetching frontend module...\n`);
+
+  const tarBuf = await fetchModuleTarball(
+    bucket,
+    latestVersion,
+    frontendModule.tarball,
+    frontendModule.sha256
+  );
+
+  const tarEntries = await parseTarball(tarBuf);
+
+  // 4. Find the page in the tarball
+  const category = getCategoryForPageId(pageName);
+  const expectedPath = `frontend/src/pages/${category}/${pageName}.tsx`;
+
+  const pageEntry = getTarEntry(tarEntries, expectedPath);
+  if (!pageEntry) {
+    throw new Error(`Seed page not found at ${expectedPath} in frontend tarball`);
+  }
+
+  const pageContent = pageEntry.content.toString('utf-8');
+
+  // 5. Create git branch for the addition
+  const branchName = `tib-add-seed-page/${pageName}`;
+
+  try {
+    execSync(`git -C "${projectDir}" checkout -b "${branchName}"`, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch {
+    // Branch may already exist
+    try {
+      execSync(`git -C "${projectDir}" checkout "${branchName}"`, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+    } catch {
+      throw new Error(`Failed to create or checkout branch: ${branchName}`);
+    }
+  }
+
+  // 6. Write the seed page to disk (WITHOUT @mc-scaffold header — it's user-owned)
+  const diskPath = join(projectDir, 'frontend', 'src', 'pages', category, `${pageName}.tsx`);
+
+  // Check if file already exists
+  try {
+    await access(diskPath);
+    throw new Error(
+      `Seed page already exists at ${diskPath}. Remove it first before adding a new one.`
+    );
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw err;
+    }
+  }
+
+  console.log(`Writing ${diskPath}...`);
+  await mkdir(dirname(diskPath), { recursive: true });
+  await writeFile(diskPath, pageContent, 'utf-8');
+
+  // 7. Commit changes
+  execSync(`git -C "${projectDir}" add -A`, { stdio: 'pipe' });
+
+  let hasChanges = false;
+  try {
+    const status = execSync(`git -C "${projectDir}" status --porcelain`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+    hasChanges = status.length > 0;
+  } catch {
+    // ignore
+  }
+
+  if (!hasChanges) {
+    console.log('No changes to commit.\n');
+    return;
+  }
+
+  const commitMsg = `feat: add ${pageName} seed page (user-owned, scaffold v${latestVersion})`;
+
+  execSync(`git -C "${projectDir}" commit -m "${commitMsg}"`, { stdio: 'pipe' });
+
+  try {
+    execSync(`git -C "${projectDir}" push --set-upstream origin "${branchName}"`, {
+      stdio: 'pipe',
+    });
+  } catch {
+    cliLogger.warn({ branchName }, 'add-seed-page: git push failed — skipping PR creation');
+    console.log(`\nCommit created on branch: ${branchName}`);
+    console.log('Note: push failed — create the PR manually.\n');
+    return;
+  }
+
+  // 8. Create GitHub PR
+  const token = process.env['GITHUB_TOKEN'];
+  const remote = detectGitRemote(projectDir);
+
+  if (!token) {
+    console.log(`\nBranch pushed: ${branchName}`);
+    console.log('Set GITHUB_TOKEN env var to create a PR automatically.\n');
+    return;
+  }
+
+  if (!remote) {
+    console.log(`\nBranch pushed: ${branchName}`);
+    console.log('Could not detect GitHub owner/repo from git remote — create the PR manually.\n');
+    return;
+  }
+
+  const prTitle = `Add ${pageName} seed page (user-owned, scaffold v${latestVersion})`;
+
+  const prBody = buildAddSeedPagePrBody(pageName, latestVersion, diskPath);
+
+  const prResult = await createGitHubPR(
+    remote.owner,
+    remote.repo,
+    token,
+    branchName,
+    prTitle,
+    prBody
+  );
+
+  console.log(`\nPR created: ${prResult.url}\n`);
+  cliLogger.info({ prUrl: prResult.url, pageName }, 'add-seed-page: PR created');
+}
+
+function buildAddSeedPagePrBody(pageName: string, version: string, filePath: string): string {
+  const lines: string[] = [
+    `## Add ${pageName} Seed Page`,
+    '',
+    'This PR adds a new seed page from the TIB scaffold library.',
+    '',
+    '### About seed pages',
+    'Seed pages are **user-owned from day one**. TIB will never auto-update them during scaffold upgrades.',
+    'You are free to customize, refactor, or remove them at any time.',
+    '',
+    '### Files added',
+    `- \`${filePath}\``,
+    '',
+    '### Scaffold version',
+    `This page was sourced from scaffold \`v${version}\`.`,
+    '',
+  ];
+
+  return lines.join('\n');
+}

package/src/commands/add-subscriber.ts

@@ -0,0 +1,123 @@
+/**
+ * Command to add a new event subscriber to an existing domain.
+ * Supports --pattern to scaffold from predefined templates.
+ */
+
+import { writeFile, access } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { subscriberSkeletonTemplate } from '../templates/subscriber-skeleton.js';
+import { singleStepProjectionTemplate } from '../templates/patterns/subscriber/single-step-projection.js';
+import { cascadeDeletionTemplate } from '../templates/patterns/subscriber/cascade-deletion.js';
+import { auditRelayTemplate } from '../templates/patterns/subscriber/audit-relay.js';
+import { cliLogger } from '../utils/logger.js';
+
+/**
+ * Valid subscriber pattern IDs.
+ */
+export const SUBSCRIBER_PATTERNS = [
+  'single-step-projection',
+  'cascade-deletion',
+  'audit-relay',
+] as const;
+
+export type SubscriberPattern = (typeof SUBSCRIBER_PATTERNS)[number];
+
+/**
+ * Options for the add-subscriber command.
+ */
+export interface AddSubscriberOptions {
+  /** Domain ID in kebab-case. */
+  domain: string;
+  /** Subscriber ID in kebab-case. */
+  id: string;
+  /** Event ID to subscribe to (e.g., 'domain.event'). */
+  event: string;
+  /** Pattern template ID (optional). */
+  pattern?: SubscriberPattern;
+  /** Override directory for domain root (used in tests). */
+  domainsDir?: string;
+}
+
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Execute the add-subscriber command: create a new event subscriber in an existing domain.
+ * @param opts - AddSubscriberOptions specifying domain, subscriber ID, and event.
+ * @throws If domain does not exist, subscriber ID is invalid, or file already exists.
+ */
+export async function runAddSubscriber(opts: AddSubscriberOptions): Promise<void> {
+  if (!KEBAB_REGEX.test(opts.id)) {
+    throw new Error(`Invalid subscriber id "${opts.id}" — must be kebab-case`);
+  }
+
+  if (!KEBAB_REGEX.test(opts.domain)) {
+    throw new Error(`Invalid domain id "${opts.domain}" — must be kebab-case`);
+  }
+
+  if (!opts.event || opts.event.trim() === '') {
+    throw new Error(`Event ID is required and cannot be empty`);
+  }
+
+  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 subscriberFilePath = join(domainDir, 'subscribers', `${opts.id}.ts`);
+
+  // Refuse if subscriber already exists
+  try {
+    await access(subscriberFilePath);
+    throw new Error(`Subscriber "${opts.id}" already exists at ${subscriberFilePath}`);
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      throw err;
+    }
+  }
+
+  // Resolve template content
+  let subscriberContent: string;
+  if (opts.pattern) {
+    subscriberContent = resolveSubscriberPattern(opts.pattern, opts.domain, opts.id, opts.event);
+    cliLogger.info({ pattern: opts.pattern }, 'Using pattern template');
+  } else {
+    subscriberContent = subscriberSkeletonTemplate(opts.domain, opts.id, opts.event);
+  }
+
+  // Write subscriber file
+  await writeFile(subscriberFilePath, subscriberContent);
+
+  cliLogger.info({ domain: opts.domain, subscriber: opts.id, event: opts.event, pattern: opts.pattern ?? 'skeleton' }, 'Subscriber added');
+  // eslint-disable-next-line no-console
+  console.log(
+    `\n✓ Subscriber "${opts.id}" added to domain "${opts.domain}" ` +
+      `listening to event "${opts.event}" at ${subscriberFilePath}`
+  );
+}
+
+/**
+ * Resolve a subscriber pattern template to its generated TypeScript source.
+ */
+function resolveSubscriberPattern(
+  pattern: SubscriberPattern,
+  domain: string,
+  id: string,
+  event: string,
+): string {
+  switch (pattern) {
+    case 'single-step-projection':
+      return singleStepProjectionTemplate(domain, id, event);
+    case 'cascade-deletion':
+      return cascadeDeletionTemplate(domain, id, event);
+    case 'audit-relay':
+      return auditRelayTemplate(domain, id, event);
+    default:
+      throw new Error(`Unknown subscriber pattern "${pattern}". Available: ${SUBSCRIBER_PATTERNS.join(', ')}`);
+  }
+}