@mettlecast/domain-cli 0.2.0

package/dist/commands/build-flows.js

@@ -0,0 +1,174 @@
+/**
+ * Command to build flows into a registry JSON file.
+ */
+import { writeFile, mkdir, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { loadModuleExports } from '../builder/load-module.js';
+import { cliLogger } from '../utils/logger.js';
+/**
+ * Zod schema for validating FlowConfig.
+ * Mirrors the schema from domain-runtime's defineFlow.
+ */
+const DomainActionStepSchema = z.object({
+    type: z.literal('domain-action'),
+    name: z.string().min(1),
+    domainId: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    actionId: z.string().min(1),
+    parameters: z.record(z.string(), z.unknown()).optional(),
+    waitForTaskToken: z.boolean().optional(),
+    next: z.string().optional(),
+});
+const DomainApiStepSchema = z.object({
+    type: z.literal('domain-api'),
+    name: z.string().min(1),
+    domainId: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    apiId: z.string().min(1),
+    parameters: z.record(z.string(), z.unknown()).optional(),
+    next: z.string().optional(),
+});
+const DomainEventStepSchema = z.object({
+    type: z.literal('domain-event'),
+    name: z.string().min(1),
+    eventId: z.string().refine(val => val.includes('.'), { message: 'eventId must be namespaced (e.g. domain.event)' }),
+    payload: z.record(z.string(), z.unknown()),
+    version: z.number().int().positive(),
+    next: z.string().optional(),
+});
+const FlowControlStepSchema = z.discriminatedUnion('control', [
+    z.object({ type: z.literal('flow-control'), control: z.literal('choice'), name: z.string(), choices: z.array(z.object({ when: z.string(), next: z.string() })), default: z.string().optional() }),
+    z.object({ type: z.literal('flow-control'), control: z.literal('parallel'), name: z.string(), branches: z.array(z.array(z.unknown())), next: z.string().optional() }),
+    z.object({ type: z.literal('flow-control'), control: z.literal('wait'), name: z.string(), seconds: z.number().int().positive(), next: z.string().optional() }),
+    z.object({ type: z.literal('flow-control'), control: z.literal('succeed'), name: z.string() }),
+    z.object({ type: z.literal('flow-control'), control: z.literal('fail'), name: z.string(), cause: z.string().optional(), error: z.string().optional() }),
+    z.object({ type: z.literal('flow-control'), control: z.literal('pass'), name: z.string(), result: z.unknown().optional(), next: z.string().optional() }),
+]);
+const FlowStepSchema = z.union([
+    DomainActionStepSchema,
+    DomainApiStepSchema,
+    DomainEventStepSchema,
+    FlowControlStepSchema,
+]);
+const FlowConfigSchema = z.object({
+    id: z.string().regex(/^[a-z][a-z0-9-]*$/),
+    owningDomain: z.string().regex(/^[a-z][a-z0-9-]*$/).optional(),
+    type: z.enum(['express', 'standard']).optional(),
+    name: z.string().min(1),
+    steps: z.array(FlowStepSchema).min(1),
+    trigger: z.object({
+        type: z.literal('event'),
+        eventId: z.string().includes('.'),
+        semverRange: z.string().min(1),
+    }).optional(),
+});
+/**
+ * Custom error for flow ID collisions.
+ */
+export class FlowIdCollisionError extends Error {
+    constructor(id) {
+        super(`Flow id "${id}" appears in multiple sources`);
+        this.name = 'FlowIdCollisionError';
+    }
+}
+async function loadFlowsFromDir(dir, owningDomainOverride) {
+    const entries = [];
+    let files;
+    try {
+        files = await readdir(dir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return entries;
+        throw err;
+    }
+    for (const file of files) {
+        if (file.endsWith('.ts')) {
+            const filePath = join(dir, file);
+            const exports = await loadModuleExports(filePath);
+            for (const exp of exports) {
+                if (exp._kind !== 'flow')
+                    continue;
+                const config = FlowConfigSchema.parse(exp);
+                entries.push({
+                    id: config.id,
+                    owningDomain: owningDomainOverride ?? config.owningDomain,
+                    type: config.type,
+                    name: config.name,
+                    steps: config.steps,
+                    trigger: config.trigger,
+                });
+            }
+        }
+        else if (file.endsWith('.json')) {
+            const filePath = join(dir, file);
+            const raw = await readFile(filePath, 'utf8');
+            const config = FlowConfigSchema.parse(JSON.parse(raw));
+            entries.push({
+                id: config.id,
+                owningDomain: owningDomainOverride ?? config.owningDomain,
+                type: config.type,
+                name: config.name,
+                steps: config.steps,
+                trigger: config.trigger,
+            });
+        }
+    }
+    return entries;
+}
+/**
+ * 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 async function runBuildFlows(options) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    const outFile = options.outFile ?? join(projectRoot, '.tib', 'flows-registry.json');
+    cliLogger.info({ projectRoot }, 'Building flows registry');
+    const allEntries = [];
+    const seenIds = new Set();
+    // Scan root-level flows/ (deprecated)
+    const rootFlowsDir = join(projectRoot, 'flows');
+    const rootEntries = await loadFlowsFromDir(rootFlowsDir);
+    if (rootEntries.length > 0) {
+        cliLogger.warn({ dir: rootFlowsDir }, 'Root-level flows/ is deprecated. Move flows to domains/{x}/flows/ and re-run build-flows.');
+        for (const e of rootEntries) {
+            if (seenIds.has(e.id))
+                throw new FlowIdCollisionError(e.id);
+            seenIds.add(e.id);
+            allEntries.push(e);
+        }
+    }
+    // Scan domains/*/flows/ (preferred)
+    const domainsDir = join(projectRoot, 'domains');
+    let domainEntries;
+    try {
+        domainEntries = (await readdir(domainsDir, { withFileTypes: true }))
+            .filter(e => e.isDirectory())
+            .map(e => e.name);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            domainEntries = [];
+        }
+        else {
+            throw err;
+        }
+    }
+    for (const domainId of domainEntries) {
+        const domainFlowsDir = join(domainsDir, domainId, 'flows');
+        const domainFlowEntries = await loadFlowsFromDir(domainFlowsDir, domainId);
+        for (const e of domainFlowEntries) {
+            if (seenIds.has(e.id))
+                throw new FlowIdCollisionError(e.id);
+            seenIds.add(e.id);
+            allEntries.push(e);
+        }
+    }
+    const registry = { schemaVersion: '1', flows: allEntries };
+    await mkdir(join(outFile, '..'), { recursive: true });
+    await writeFile(outFile, JSON.stringify(registry, null, 2), 'utf8');
+    cliLogger.info({ outFile, flowCount: registry.flows.length }, 'Flows registry written');
+    return outFile;
+}

package/dist/commands/build.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Options for the build command.
+ */
+export interface BuildOptions {
+    /** Absolute or relative path to the domain root directory. */
+    domainRoot: string;
+    /** Output path for the registry JSON file. Defaults to .mc/domain-registry.json relative to cwd. */
+    outFile?: string;
+}
+/**
+ * Execute the build command: load the domain source directory, build the DomainRegistry,
+ * and write the serialised JSON snapshot to disk.
+ * @param options - BuildOptions specifying domain root and optional output path.
+ * @returns The absolute path to the written registry file.
+ * @throws If domain.config.ts is missing or the registry build fails.
+ */
+export declare function runBuild(options: BuildOptions): Promise<string>;

package/dist/commands/build.js

@@ -0,0 +1,39 @@
+import { writeFile, mkdir, readdir, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { buildRegistry } from '../builder/build-registry.js';
+import { buildActionsTypes } from '../builder/build-types.js';
+import { cliLogger } from '../utils/logger.js';
+/**
+ * Execute the build command: load the domain source directory, build the DomainRegistry,
+ * and write the serialised JSON snapshot to disk.
+ * @param options - BuildOptions specifying domain root and optional output path.
+ * @returns The absolute path to the written registry file.
+ * @throws If domain.config.ts is missing or the registry build fails.
+ */
+export async function runBuild(options) {
+    const domainRoot = resolve(options.domainRoot);
+    const outFile = options.outFile
+        ? resolve(options.outFile)
+        : join(process.cwd(), '.tib', 'domain-registry.json');
+    cliLogger.info({ domainRoot }, 'Building domain registry');
+    const { registry, warnings } = await buildRegistry(domainRoot);
+    for (const w of warnings) {
+        cliLogger.warn(w);
+    }
+    await mkdir(join(outFile, '..'), { recursive: true });
+    await writeFile(outFile, JSON.stringify(registry, null, 2), 'utf8');
+    cliLogger.info({ outFile, apis: registry.apis.length, events: registry.events.length }, 'Registry written');
+    // Discover all sibling registries and emit aggregated types
+    const tibDir = join(process.cwd(), '.tib');
+    const registryFiles = (await readdir(tibDir)).filter(f => f.endsWith('-registry.json'));
+    const allRegistries = [];
+    for (const f of registryFiles) {
+        const raw = await readFile(join(tibDir, f), 'utf8');
+        allRegistries.push(JSON.parse(raw));
+    }
+    const typesContent = buildActionsTypes(allRegistries);
+    const typesFile = join(tibDir, 'actions-types.d.ts');
+    await writeFile(typesFile, typesContent);
+    cliLogger.info({ outFile: typesFile }, 'Types file written');
+    return outFile;
+}

package/dist/commands/check-hashes.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Options for the check-hashes command.
+ */
+export interface CheckHashesOptions {
+    /** Root directory of the project (defaults to cwd). */
+    projectRoot?: string;
+}
+/**
+ * A single hash check result.
+ */
+export interface DriftedFile {
+    /** File path relative to project root. */
+    path: string;
+    /** Expected SHA256 hash from manifest. */
+    expectedHash: string;
+    /** Actual SHA256 hash on disk. */
+    actualHash: string;
+}
+/**
+ * Result of the check-hashes command.
+ */
+export interface CheckHashesResult {
+    /** Whether all hashes match. */
+    ok: boolean;
+    /** Files that have been modified since scaffold. */
+    drifted: DriftedFile[];
+    /** Files that existed at scaffold time but are now missing. */
+    missing: string[];
+    /** Files on disk that were not in the scaffold manifest. */
+    unexpected: string[];
+}
+/**
+ * Verify that infra/modules/ has not been hand-edited since last scaffold.
+ * Reads .mc/modules-hashes.json manifest and compares each file's SHA256.
+ * @param opts Options including project root directory.
+ * @returns CheckHashesResult with ok, drifted, missing, and unexpected arrays.
+ */
+export declare function runCheckHashes(opts?: CheckHashesOptions): Promise<CheckHashesResult>;

package/dist/commands/check-hashes.js

@@ -0,0 +1,97 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { createHash } from 'node:crypto';
+import { cliLogger } from '../utils/logger.js';
+/**
+ * Verify that infra/modules/ has not been hand-edited since last scaffold.
+ * Reads .mc/modules-hashes.json manifest and compares each file's SHA256.
+ * @param opts Options including project root directory.
+ * @returns CheckHashesResult with ok, drifted, missing, and unexpected arrays.
+ */
+export async function runCheckHashes(opts = {}) {
+    const root = opts.projectRoot ?? process.cwd();
+    const manifestPath = join(root, '.tib', 'modules-hashes.json');
+    const modulesDir = join(root, 'infra', 'modules');
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`tib check-hashes: cannot read ${manifestPath} (${err.message}). Re-scaffold to regenerate the manifest.`);
+    }
+    const drifted = [];
+    const missing = [];
+    const unexpected = [];
+    // Files/directories to skip when walking infra/modules/
+    const SKIP_NAMES = new Set(['node_modules', 'dist', 'cdk.out', 'package-lock.json', '.npmrc']);
+    /** Normalize CRLF → LF so hashes match across platforms (Windows vs Linux). */
+    function normalizeLineEndings(buf) {
+        const str = buf.toString('utf8');
+        if (!str.includes('\r\n'))
+            return buf;
+        return Buffer.from(str.replace(/\r\n/g, '\n'), 'utf8');
+    }
+    // Walk infra/modules/ to compute current hashes
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => []);
+        const files = [];
+        for (const entry of entries) {
+            if (SKIP_NAMES.has(entry.name))
+                continue;
+            const full = join(dir, entry.name);
+            if (entry.isDirectory())
+                files.push(...await walk(full));
+            else if (entry.isFile())
+                files.push(full);
+        }
+        return files;
+    }
+    const onDiskFiles = await walk(modulesDir);
+    const onDiskRel = onDiskFiles.map(f => relative(root, f).replace(/\\/g, '/'));
+    const onDiskSet = new Set(onDiskRel);
+    // Check each manifest entry
+    for (const [relPath, expectedHash] of Object.entries(manifest.files)) {
+        if (!onDiskSet.has(relPath)) {
+            missing.push(relPath);
+            continue;
+        }
+        const content = await readFile(join(root, relPath));
+        const normalized = normalizeLineEndings(content);
+        const actualHash = createHash('sha256').update(normalized).digest('hex');
+        if (actualHash !== expectedHash) {
+            drifted.push({ path: relPath, expectedHash, actualHash });
+        }
+    }
+    // Files on disk but not in manifest
+    for (const relPath of onDiskRel) {
+        if (!Object.prototype.hasOwnProperty.call(manifest.files, relPath)) {
+            unexpected.push(relPath);
+        }
+    }
+    const result = {
+        ok: drifted.length === 0 && missing.length === 0 && unexpected.length === 0,
+        drifted,
+        missing,
+        unexpected,
+    };
+    if (!result.ok) {
+        cliLogger.error({ drifted: drifted.length, missing: missing.length, unexpected: unexpected.length }, 'infra/modules/ has drifted from scaffold');
+        if (drifted.length > 0) {
+            cliLogger.error('Files modified since last scaffold:');
+            for (const d of drifted)
+                cliLogger.error(`  - ${d.path}`);
+        }
+        if (missing.length > 0) {
+            cliLogger.error('Files deleted since last scaffold:');
+            for (const m of missing)
+                cliLogger.error(`  - ${m}`);
+        }
+        if (unexpected.length > 0) {
+            cliLogger.error('Files added that were not scaffolded (manually-added):');
+            for (const u of unexpected)
+                cliLogger.error(`  - ${u}`);
+        }
+        cliLogger.error('infra/modules/ is TIB-owned. Re-scaffold to update legitimately.');
+    }
+    return result;
+}

package/dist/commands/create-project.d.ts

@@ -0,0 +1,5 @@
+export interface CreateProjectOptions {
+    name: string;
+    outDir?: string;
+}
+export declare function runCreateProject(opts: CreateProjectOptions): Promise<void>;

package/dist/commands/create-project.js

@@ -0,0 +1,272 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { Readable } from 'node:stream';
+import { execSync } from 'node:child_process';
+import * as tar from 'tar';
+import { cliLogger } from '../utils/logger.js';
+import { fetchVersionsJson, fetchModulesJson, fetchModuleTarball, } from '../utils/s3-fetch.js';
+import { computeChecksumString } from '../utils/checksum.js';
+import { applyTokens, buildTokenContext } from '../utils/token-substitution.js';
+import { injectHeader } from '../utils/header-inject.js';
+import { createManifest, writeManifest, upsertManifestFile, } from '../utils/manifest.js';
+import { writeScaffoldConfig } from '../utils/scaffold-config.js';
+const SCAFFOLD_BUCKET = 'mc-scaffold';
+// ── Prompts ────────────────────────────────────────────────────────────────────
+async function prompt(rl, question) {
+    return new Promise((res) => rl.question(question, res));
+}
+async function promptDefault(rl, question, defaultVal) {
+    const answer = await prompt(rl, `${question} [${defaultVal}]: `);
+    return answer.trim() || defaultVal;
+}
+async function promptYesNo(rl, question, defaultYes = true) {
+    const hint = defaultYes ? 'Y/n' : 'y/N';
+    const answer = await prompt(rl, `${question} [${hint}]: `);
+    const trimmed = answer.trim().toLowerCase();
+    if (!trimmed)
+        return defaultYes;
+    return trimmed === 'y' || trimmed === 'yes';
+}
+// ── Topological sort ───────────────────────────────────────────────────────────
+function topoSort(modules, selected) {
+    const byId = new Map(modules.map((m) => [m.id, m]));
+    const result = [];
+    const visited = new Set();
+    function visit(id) {
+        if (visited.has(id))
+            return;
+        visited.add(id);
+        const mod = byId.get(id);
+        if (!mod)
+            return;
+        for (const dep of mod.dependencies) {
+            if (selected.has(dep))
+                visit(dep);
+        }
+        result.push(mod);
+    }
+    // Always core first, then backend-lambda, then rest
+    const priorityOrder = ['core', 'backend-lambda'];
+    for (const id of priorityOrder) {
+        if (selected.has(id))
+            visit(id);
+    }
+    for (const id of selected) {
+        visit(id);
+    }
+    return result;
+}
+async function parseTarball(buf) {
+    const entries = [];
+    await new Promise((resolve, reject) => {
+        const parser = new tar.Parser({
+            gzip: true,
+            onentry(entry) {
+                if (entry.type !== 'File') {
+                    entry.resume();
+                    return;
+                }
+                const chunks = [];
+                entry.on('data', (chunk) => {
+                    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+                });
+                entry.on('end', () => {
+                    entries.push({ path: entry.path, content: Buffer.concat(chunks) });
+                });
+                entry.on('error', reject);
+            },
+        });
+        parser.on('finish', resolve);
+        parser.on('error', reject);
+        const readable = Readable.from(buf);
+        readable.pipe(parser);
+    });
+    return entries;
+}
+function getTarEntry(entries, targetPath) {
+    // Strip leading ./ or component prefix from tarball paths
+    return entries.find((e) => {
+        const normalized = e.path.replace(/^\.\//, '').replace(/^[^/]+\//, '');
+        return normalized === targetPath || e.path === targetPath || e.path.endsWith(`/${targetPath}`);
+    });
+}
+// ── Main ───────────────────────────────────────────────────────────────────────
+export async function runCreateProject(opts) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        // 1. Collect project details
+        console.log('\nTIB scaffold — create new project\n');
+        const projectName = await promptDefault(rl, 'Project name', opts.name || 'my-project');
+        const awsRegion = await promptDefault(rl, 'AWS region', 'eu-north-1');
+        const awsAccountId = await promptDefault(rl, 'AWS account ID', '');
+        const includeDatabase = await promptYesNo(rl, 'Include database (Aurora)?', false);
+        const includeAuth = await promptYesNo(rl, 'Include authentication (Cognito)?', false);
+        const includeFrontend = await promptYesNo(rl, 'Include frontend?', false);
+        const includeFlows = await promptYesNo(rl, 'Include flows?', false);
+        const adminEmail = includeAuth
+            ? await promptDefault(rl, 'Admin email', '')
+            : undefined;
+        // Optional custom domain for prod (bare domain, no scheme/path/port)
+        const BARE_DOMAIN_RE = /^[a-z0-9.-]+\.[a-z]{2,}$/;
+        let prodUrl = '';
+        if (includeFrontend) {
+            const raw = await promptDefault(rl, 'Production dashboard URL (optional — skip for CloudFront-default)', '');
+            if (raw && !BARE_DOMAIN_RE.test(raw.trim())) {
+                console.warn('[tib] Invalid domain format — must be a bare domain like "app.acme.com". Skipping.');
+            }
+            else {
+                prodUrl = raw.trim();
+            }
+        }
+        const defaultOutDir = opts.outDir ? resolve(opts.outDir) : resolve(process.cwd(), projectName);
+        const outputDirRaw = await promptDefault(rl, 'Output directory', defaultOutDir);
+        const outputDir = resolve(outputDirRaw);
+        // 2. Fetch versions.json
+        console.log('\nFetching scaffold versions...');
+        const versionsJson = await fetchVersionsJson(SCAFFOLD_BUCKET);
+        const scaffoldVersion = await promptDefault(rl, 'Scaffold version', versionsJson.latest);
+        rl.close();
+        // 3. Fetch modules.json
+        console.log(`\nFetching modules for scaffold@${scaffoldVersion}...`);
+        const modulesJson = await fetchModulesJson(SCAFFOLD_BUCKET, scaffoldVersion);
+        // 4. Resolve module selection
+        const selectedIds = new Set(['core', 'backend-lambda']);
+        if (includeDatabase)
+            selectedIds.add('db-aurora');
+        if (includeAuth)
+            selectedIds.add('auth-cognito');
+        if (includeFrontend)
+            selectedIds.add('frontend');
+        if (includeFlows)
+            selectedIds.add('flows');
+        // Expand dependencies
+        const moduleMap = new Map(modulesJson.modules.map((m) => [m.id, m]));
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const id of [...selectedIds]) {
+                const mod = moduleMap.get(id);
+                if (!mod)
+                    continue;
+                for (const dep of mod.dependencies) {
+                    if (!selectedIds.has(dep)) {
+                        selectedIds.add(dep);
+                        changed = true;
+                    }
+                }
+            }
+        }
+        const orderedModules = topoSort(modulesJson.modules, selectedIds);
+        // 5. Prepare output directory
+        await mkdir(outputDir, { recursive: true });
+        await mkdir(join(outputDir, '.tib'), { recursive: true });
+        // 6. Get CLI version from package.json
+        let cliVersion = '0.0.0';
+        try {
+            const { createRequire } = await import('node:module');
+            const require = createRequire(import.meta.url);
+            const pkgJson = require('../../package.json');
+            cliVersion = pkgJson.version;
+        }
+        catch {
+            // ignore — fallback to 0.0.0
+        }
+        // 7. Build token context
+        const tokenCtx = buildTokenContext({ projectName, awsRegion, awsAccountId, adminEmail }, scaffoldVersion, cliVersion);
+        // 8. Create manifest
+        const manifest = createManifest(scaffoldVersion, projectName, awsRegion, [...selectedIds]);
+        // 9. Process each module in topological order
+        for (const mod of orderedModules) {
+            console.log(`  Installing module: ${mod.id}@${mod.version}...`);
+            const tarBuf = await fetchModuleTarball(SCAFFOLD_BUCKET, scaffoldVersion, mod.tarball, mod.sha256);
+            const tarEntries = await parseTarball(tarBuf);
+            // Extract MANIFEST.json from tarball
+            const manifestEntry = getTarEntry(tarEntries, 'MANIFEST.json');
+            if (!manifestEntry) {
+                cliLogger.warn({ moduleId: mod.id }, 'No MANIFEST.json in tarball — skipping');
+                continue;
+            }
+            const tarManifest = JSON.parse(manifestEntry.content.toString('utf-8'));
+            // installPrefix for modules like 'frontend'
+            const modMeta = moduleMap.get(mod.id);
+            const installPrefix = modMeta?.installPrefix ?? '';
+            for (const fileEntry of tarManifest) {
+                const tarEntry = getTarEntry(tarEntries, fileEntry.path);
+                if (!tarEntry) {
+                    cliLogger.warn({ moduleId: mod.id, path: fileEntry.path }, 'File listed 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 = installPath.slice(0, -4);
+                }
+                // Apply installPrefix
+                if (installPrefix) {
+                    installPath = `${installPrefix}/${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, mod.id, mod.version);
+                // Write file
+                const destPath = join(outputDir, installPath);
+                const parentParts = installPath.split('/').slice(0, -1);
+                if (parentParts.length > 0) {
+                    await mkdir(join(outputDir, ...parentParts), { recursive: true });
+                }
+                await writeFile(destPath, content, 'utf-8');
+                // Track in manifest (SHA-256 of written content)
+                const sha256 = computeChecksumString(content);
+                upsertManifestFile(manifest, {
+                    path: installPath,
+                    module: mod.id,
+                    moduleVersion: mod.version,
+                    sha256,
+                    wasTemplate: fileEntry.isTemplate,
+                    installedAt: new Date().toISOString(),
+                    policy: fileEntry.policy ?? 'tracked',
+                });
+            }
+        }
+        // 10. Write .mc/scaffold-config.json
+        const environments = prodUrl
+            ? { prod: { dashboardUrl: prodUrl } }
+            : undefined;
+        const scaffoldConfig = {
+            scaffoldVersion,
+            enabledModules: [...selectedIds],
+            projectName,
+            awsRegion,
+            awsAccountId,
+            adminEmail,
+            domainIds: [],
+            flowIds: [],
+            scaffoldBucket: SCAFFOLD_BUCKET,
+            ...(environments ? { environments } : {}),
+        };
+        await writeScaffoldConfig(outputDir, scaffoldConfig);
+        // 11. Write .mc/manifest.json
+        await writeManifest(outputDir, manifest);
+        // 12. Git init + initial commit
+        console.log('\nInitialising git repository...');
+        execSync(`git -C "${outputDir}" init`, { stdio: 'pipe' });
+        execSync(`git -C "${outputDir}" add -A`, { stdio: 'pipe' });
+        execSync(`git -C "${outputDir}" commit -m "chore: initial scaffold from mc-scaffold@${scaffoldVersion}"`, { stdio: 'pipe' });
+        cliLogger.info({ projectName, outputDir, scaffoldVersion }, 'Project created');
+        console.log(`\nProject "${projectName}" created at ${outputDir}\n\n` +
+            `  Next steps:\n` +
+            `    cd ${outputDir}\n` +
+            `    npm install\n` +
+            `    npm run dev\n`);
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/commands/dev.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Options for the dev command.
+ */
+export interface DevOptions {
+    /** Absolute or relative path to the domain root directory. */
+    domainRoot: string;
+    /** Port for the local HTTP server. Defaults to 3000. */
+    port?: number;
+}
+/**
+ * Execute the dev command: build the domain registry and start the local Fastify
+ * HTTP server. Keeps the process running. Shuts down gracefully on SIGINT/SIGTERM.
+ * @param options - DevOptions specifying domain root and optional port.
+ */
+export declare function runDev(options: DevOptions): Promise<void>;