@mettlecast/domain-cli 0.2.0

package/dist/commands/add-flow.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Valid flow pattern IDs.
+ */
+export declare const FLOW_PATTERNS: readonly ["fan-out-reaction", "multi-step-orchestration", "autonomous-remediation", "human-in-loop"];
+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;
+}
+export declare function runAddFlow(opts: AddFlowOptions): Promise<void>;

package/dist/commands/add-flow.js

@@ -0,0 +1,108 @@
+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',
+];
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+function toCamelCase(s) {
+    return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function flowSkeletonTemplate(domain, id, type) {
+    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) {
+    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.code !== 'ENOENT') {
+            throw err;
+        }
+    }
+    await mkdir(flowsDir, { recursive: true });
+    // Resolve template content
+    let flowContent;
+    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, domain, id) {
+    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/dist/commands/add-hook.d.ts

@@ -0,0 +1,15 @@
+/** Supported hook patterns. */
+export type HookPattern = 'paginated-list' | 'mutation' | 'feature-flag' | 'subscription';
+export declare const HOOK_PATTERNS: readonly HookPattern[];
+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 declare function runAddHook(opts: AddHookOptions): Promise<void>;

package/dist/commands/add-hook.js

@@ -0,0 +1,65 @@
+/**
+ * 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';
+export const HOOK_PATTERNS = [
+    'paginated-list',
+    'mutation',
+    'feature-flag',
+    'subscription',
+];
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+const PATTERN_TEMPLATES = {
+    'paginated-list': paginatedListHookTemplate,
+    mutation: mutationHookTemplate,
+    'feature-flag': featureFlagHookTemplate,
+    subscription: subscriptionHookTemplate,
+};
+/**
+ * Scaffold a typed data-fetching hook file.
+ */
+export async function runAddHook(opts) {
+    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.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) {
+    return s
+        .split('-')
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}

package/dist/commands/add-migration.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Command to add a new database migration to an existing domain.
+ * Supports --pattern for predefined migration templates.
+ */
+/**
+ * Valid migration pattern IDs.
+ */
+export declare const MIGRATION_PATTERNS: readonly ["tenant-scoped-table", "rls-policy", "column-add", "index", "event-store"];
+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;
+}
+/**
+ * Execute the add-migration command: create a new SQL migration in an existing domain.
+ */
+export declare function runAddMigration(opts: AddMigrationOptions): Promise<void>;

package/dist/commands/add-migration.js

@@ -0,0 +1,93 @@
+/**
+ * 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',
+];
+const KEBAB_REGEX = /^[a-z][a-z0-9-]*$/;
+/**
+ * Generates a timestamp prefix matching the project convention.
+ */
+function generateTimestamp() {
+    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) {
+    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.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, domain, name) {
+    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(', ')}`);
+    }
+}

package/dist/commands/add-module.d.ts

@@ -0,0 +1,7 @@
+export interface AddModuleOptions {
+    moduleId: string;
+    githubToken?: string;
+    dryRun?: boolean;
+    projectDir?: string;
+}
+export declare function runAddModule(opts: AddModuleOptions): Promise<void>;

package/dist/commands/add-module.js

@@ -0,0 +1,261 @@
+import { execSync } from 'node:child_process';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { Parser as TarParser } from 'tar';
+import { readScaffoldConfig, writeScaffoldConfig } from '../utils/scaffold-config.js';
+import { readManifest, writeManifest, upsertManifestFile, inferPolicyFromPath } from '../utils/manifest.js';
+import { fetchModulesJson, fetchModuleTarball } from '../utils/s3-fetch.js';
+import { applyTokens, buildTokenContext, stripTplExtension } from '../utils/token-substitution.js';
+import { injectHeader } from '../utils/header-inject.js';
+import { computeChecksumString } from '../utils/checksum.js';
+import { installScaffoldFile } from '../utils/install-file.js';
+import { cliLogger } from '../utils/logger.js';
+async function parseTarball(buf) {
+    const entries = [];
+    const chunks = {};
+    await new Promise((resolve, reject) => {
+        const parser = new TarParser({
+            onentry: (entry) => {
+                const p = entry.path;
+                chunks[p] = [];
+                entry.on('data', (chunk) => chunks[p].push(chunk));
+            },
+        });
+        parser.on('finish', resolve);
+        parser.on('error', reject);
+        Readable.from(buf).pipe(parser);
+    });
+    for (const [path, buffers] of Object.entries(chunks)) {
+        if (buffers.length > 0) {
+            entries.push({ path, content: Buffer.concat(buffers) });
+        }
+    }
+    return entries;
+}
+function getTarEntry(entries, path) {
+    return entries.find((e) => e.path === path);
+}
+async function getCliVersion() {
+    try {
+        const { createRequire } = await import('node:module');
+        const require = createRequire(import.meta.url);
+        const pkgJson = require('../../package.json');
+        return pkgJson.version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+async function detectRepoInfo() {
+    try {
+        const remoteUrl = execSync('git remote get-url origin', {
+            encoding: 'utf8',
+            stdio: 'pipe',
+        }).trim();
+        // Parse git@github.com:owner/repo.git or https://github.com/owner/repo.git
+        let match = /github\.com[:/]([^/]+)\/(.+?)(?:\.git)?$/.exec(remoteUrl);
+        if (match) {
+            return { owner: match[1], repo: match[2].replace(/\.git$/, '') };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+async function createGitHubPR(owner, repo, branchName, title, body, token) {
+    try {
+        const response = await fetch(`https://api.github.com/repos/${owner}/${repo}/pulls`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                title,
+                body,
+                head: branchName,
+                base: 'develop',
+            }),
+        });
+        if (!response.ok) {
+            const error = await response.json();
+            cliLogger.warn(error, 'Failed to create GitHub PR');
+            return null;
+        }
+        const data = (await response.json());
+        if (data.html_url && data.number) {
+            return { prUrl: data.html_url, prNumber: data.number };
+        }
+        return null;
+    }
+    catch (err) {
+        cliLogger.warn(err, 'Failed to create GitHub PR');
+        return null;
+    }
+}
+export async function runAddModule(opts) {
+    const projectDir = opts.projectDir ?? process.cwd();
+    const moduleId = opts.moduleId;
+    const dryRun = opts.dryRun ?? false;
+    // 1. Read .mc/scaffold-config.json
+    let config;
+    try {
+        config = await readScaffoldConfig(projectDir);
+    }
+    catch (err) {
+        throw new Error(`Failed to read scaffold config from ${projectDir}: ${err}`);
+    }
+    // 2. Fetch modules.json from S3
+    let modulesJson;
+    try {
+        modulesJson = await fetchModulesJson(config.scaffoldBucket, config.scaffoldVersion);
+    }
+    catch (err) {
+        throw new Error(`Failed to fetch modules.json for version ${config.scaffoldVersion}: ${err}`);
+    }
+    // 3. Validate moduleId is a known module
+    const module = modulesJson.modules.find((m) => m.id === moduleId);
+    if (!module) {
+        const available = modulesJson.modules.map((m) => m.id).join(', ');
+        throw new Error(`Unknown module "${moduleId}". Available modules: ${available}`);
+    }
+    // 4. Check moduleId is NOT already installed
+    if (config.enabledModules.includes(moduleId)) {
+        throw new Error(`Module "${moduleId}" is already installed`);
+    }
+    // 5. Check all dependencies of moduleId ARE installed
+    for (const dep of module.dependencies) {
+        if (!config.enabledModules.includes(dep)) {
+            throw new Error(`Module "${moduleId}" requires "${dep}" which is not installed. ` +
+                `Install "${dep}" first with: tib add-module ${dep}`);
+        }
+    }
+    // 6. Fetch tarball from S3
+    let tarBuf;
+    try {
+        tarBuf = await fetchModuleTarball(config.scaffoldBucket, config.scaffoldVersion, module.tarball, module.sha256);
+    }
+    catch (err) {
+        throw new Error(`Failed to fetch tarball for ${moduleId}: ${err}`);
+    }
+    // 7. Parse tarball
+    const tarEntries = await parseTarball(tarBuf);
+    // 8. Extract MANIFEST.json
+    const manifestEntry = getTarEntry(tarEntries, 'MANIFEST.json');
+    if (!manifestEntry) {
+        throw new Error(`No MANIFEST.json found in tarball for ${moduleId}`);
+    }
+    const tarManifest = JSON.parse(manifestEntry.content.toString('utf-8'));
+    // 9. Read manifest.json
+    let manifest = await readManifest(projectDir);
+    if (!manifest) {
+        throw new Error(`No .mc/manifest.json found in ${projectDir}`);
+    }
+    // 10. Get CLI version for header
+    const cliVersion = await getCliVersion();
+    // 11. Build token context
+    const tokenCtx = buildTokenContext(config, config.scaffoldVersion, cliVersion);
+    // 12. Process files from tarball
+    const filesInstalled = [];
+    for (const fileEntry of tarManifest) {
+        const tarEntry = getTarEntry(tarEntries, fileEntry.path);
+        if (!tarEntry) {
+            cliLogger.warn({ moduleId, path: fileEntry.path }, 'File in MANIFEST.json not found in tarball');
+            continue;
+        }
+        // Determine install path
+        let installPath = fileEntry.installedAs ?? fileEntry.path;
+        // Strip .tpl extension
+        if (installPath.endsWith('.tpl')) {
+            installPath = stripTplExtension(installPath);
+        }
+        // Process content
+        let content = tarEntry.content.toString('utf-8');
+        // Token substitution for template files
+        if (fileEntry.isTemplate) {
+            content = applyTokens(content, tokenCtx);
+        }
+        // Inject scaffold header
+        content = injectHeader(content, installPath, moduleId, module.version);
+        if (!dryRun) {
+            // Determine policy: use fileEntry.policy if present, else infer from path
+            const policy = fileEntry.policy ?? inferPolicyFromPath(installPath);
+            // Get current entry if exists
+            const currentEntry = manifest.files.find((f) => f.path === installPath);
+            // Install file using policy-based dispatch
+            const destPath = join(projectDir, installPath);
+            const installResult = await installScaffoldFile(destPath, content, policy, currentEntry, {
+                dryRun: false,
+            });
+            // Only update manifest if file was not skipped
+            if (installResult.status !== 'skipped') {
+                const sha256 = computeChecksumString(content);
+                upsertManifestFile(manifest, {
+                    path: installPath,
+                    module: moduleId,
+                    moduleVersion: module.version,
+                    sha256,
+                    wasTemplate: fileEntry.isTemplate,
+                    installedAt: new Date().toISOString(),
+                    policy,
+                });
+            }
+        }
+        filesInstalled.push(installPath);
+    }
+    if (dryRun) {
+        console.log(`\n✓ Dry run: would install ${filesInstalled.length} file(s) from ${moduleId}@${module.version}`);
+        filesInstalled.forEach((f) => console.log(`  ${f}`));
+        console.log(`\nTo apply changes, run: tib add-module ${moduleId}\n`);
+        return;
+    }
+    // 13. Update .mc/manifest.json
+    await writeManifest(projectDir, manifest);
+    // 14. Update .mc/scaffold-config.json
+    config.enabledModules = [...config.enabledModules, moduleId];
+    await writeScaffoldConfig(projectDir, config);
+    console.log(`\n✓ Module "${moduleId}" installed (${filesInstalled.length} file(s) added)`);
+    // 15. Git operations
+    const branchName = `tib/add-module-${moduleId}`;
+    let commitSha = null;
+    try {
+        // Create new branch
+        execSync(`git -C "${projectDir}" checkout -b ${branchName}`, { stdio: 'pipe' });
+        // Stage changes
+        execSync(`git -C "${projectDir}" add .mc/`, { stdio: 'pipe' });
+        // Commit
+        const commitMsg = `feat: add tib module ${moduleId}@${config.scaffoldVersion}`;
+        execSync(`git -C "${projectDir}" commit -m "${commitMsg}"`, { stdio: 'pipe' });
+        commitSha = execSync(`git -C "${projectDir}" rev-parse HEAD`, {
+            encoding: 'utf8',
+            stdio: 'pipe',
+        }).trim();
+        cliLogger.info({ moduleId, commitSha, branchName }, 'Module commit created');
+    }
+    catch (err) {
+        cliLogger.warn(err, `Failed to create git commit for module ${moduleId}`);
+    }
+    // 16. GitHub PR creation if token available
+    const githubToken = opts.githubToken ?? process.env.GITHUB_TOKEN;
+    if (githubToken && commitSha) {
+        try {
+            // Push branch to remote
+            execSync(`git -C "${projectDir}" push -u origin ${branchName}`, { stdio: 'pipe' });
+            const repoInfo = await detectRepoInfo();
+            if (repoInfo) {
+                const prResult = await createGitHubPR(repoInfo.owner, repoInfo.repo, branchName, `feat: add tib module ${moduleId}`, `Adds optional scaffold module: ${moduleId}@${config.scaffoldVersion}\n\nFiles added: ${filesInstalled.length}`, githubToken);
+                if (prResult) {
+                    console.log(`\nPR created: ${prResult.prUrl}`);
+                    cliLogger.info({ prUrl: prResult.prUrl, prNumber: prResult.prNumber }, 'Module PR created');
+                }
+            }
+        }
+        catch (err) {
+            cliLogger.warn(err, 'Failed to push and create PR');
+        }
+    }
+    else if (commitSha) {
+        console.log(`\nBranch "${branchName}" created. Push with: git push -u origin ${branchName}`);
+    }
+}

package/dist/commands/add-page.d.ts

@@ -0,0 +1,13 @@
+import { type PagePattern } from '../templates/patterns/page/index.js';
+export interface AddPageOptions {
+    pageId: string;
+    outputDir?: string;
+    auth?: boolean;
+    protected?: boolean;
+    public?: boolean;
+    /** Pattern-based scaffolding (list, detail, form, wizard, dashboard, settings). */
+    pattern?: PagePattern;
+    /** Layout to use: app (default) or auth. */
+    layout?: 'app' | 'auth';
+}
+export declare function runAddPage(opts: AddPageOptions): Promise<void>;