@uxmaltech/collab-cli 0.1.0

package/dist/lib/domain-gen.js

@@ -0,0 +1,376 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderPrinciplesMd = renderPrinciplesMd;
+exports.renderRulesMd = renderRulesMd;
+exports.renderAntiPatternsMd = renderAntiPatternsMd;
+exports.renderGlossaryMd = renderGlossaryMd;
+exports.renderPatternMd = renderPatternMd;
+exports.writeDomainFiles = writeDomainFiles;
+exports.findNextIds = findNextIds;
+exports.generateDomainGraphSeed = generateDomainGraphSeed;
+exports.appendGraphSeed = appendGraphSeed;
+exports.buildDomainGenPrompt = buildDomainGenPrompt;
+exports.parseDomainGenerationResponse = parseDomainGenerationResponse;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const repo_analysis_helpers_1 = require("./repo-analysis-helpers");
+// ────────────────────────────────────────────────────────────────
+// Renderers — follow exact collab-architecture/domains/ format
+// ────────────────────────────────────────────────────────────────
+/** Renders principles as markdown following the collab-architecture domain format. */
+function renderPrinciplesMd(r) {
+    const lines = [`# ${r.domainName} Principles`, ''];
+    for (const p of r.principles) {
+        lines.push(`- ${p.id}: ${p.text}`);
+    }
+    lines.push('');
+    lines.push('<!-- AI-GENERATED -->');
+    lines.push('');
+    return lines.join('\n');
+}
+/** Renders rules as markdown following the collab-architecture domain format. */
+function renderRulesMd(r) {
+    const lines = [`# ${r.domainName} Rules`, ''];
+    for (const rule of r.rules) {
+        lines.push(`- ${rule.id}: ${rule.text}`);
+    }
+    lines.push('');
+    lines.push('<!-- AI-GENERATED -->');
+    lines.push('');
+    return lines.join('\n');
+}
+/** Renders anti-patterns as markdown with violated rule references. */
+function renderAntiPatternsMd(r) {
+    const lines = [`# ${r.domainName} Anti-Patterns`, ''];
+    for (const ap of r.antiPatterns) {
+        lines.push(`- ${ap.id}: ${ap.description}`);
+        lines.push('');
+        lines.push('  **Rules Violated:**');
+        for (const rule of ap.rulesViolated) {
+            lines.push(`  - ${rule}`);
+        }
+        lines.push('');
+    }
+    lines.push('<!-- AI-GENERATED -->');
+    lines.push('');
+    return lines.join('\n');
+}
+/** Renders the domain glossary as a markdown term list. */
+function renderGlossaryMd(r) {
+    const lines = [`# ${r.domainName} Glossary`, ''];
+    for (const g of r.glossary) {
+        lines.push(`- ${g.term}: ${g.definition}`);
+    }
+    lines.push('');
+    lines.push('<!-- AI-GENERATED -->');
+    lines.push('');
+    return lines.join('\n');
+}
+/** Renders a single pattern as a full markdown document with context, problem, and solution. */
+function renderPatternMd(p) {
+    const lines = [
+        `# Pattern: ${p.name}`,
+        '',
+        `Pattern ID: ${p.id}`,
+        'Status: Active',
+        'Confidence: provisional',
+        '',
+        'Context:',
+        p.context,
+        '',
+        'Problem:',
+        p.problem,
+        '',
+        'Solution:',
+        p.solution,
+        '',
+        'Rules Enforced:',
+        ...p.rulesEnforced.map((r) => `- ${r}`),
+        '',
+        'Consequences:',
+        p.consequences,
+        '',
+        '<!-- AI-GENERATED -->',
+        '',
+    ];
+    return lines.join('\n');
+}
+// ────────────────────────────────────────────────────────────────
+// File writing
+// ────────────────────────────────────────────────────────────────
+/**
+ * Sanitizes a string for use as a directory or file name.
+ */
+function slugify(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Writes all domain files to a target directory via the executor abstraction.
+ * Creates: principles.md, rules.md, anti-patterns.md, glossary.md, patterns/*.md
+ *
+ * When an executor is provided, all filesystem operations go through it
+ * to respect `--dry-run` mode and centralized side-effect control.
+ *
+ * @returns The number of files written.
+ */
+function writeDomainFiles(targetDir, result, executor) {
+    let count = 0;
+    const writeFile = (filePath, content, desc) => {
+        if (executor) {
+            executor.writeFile(filePath, content, { description: desc });
+        }
+        else {
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+            node_fs_1.default.writeFileSync(filePath, content, 'utf8');
+        }
+    };
+    const ensureDir = (dirPath) => {
+        if (executor) {
+            executor.ensureDirectory(dirPath);
+        }
+        else {
+            node_fs_1.default.mkdirSync(dirPath, { recursive: true });
+        }
+    };
+    ensureDir(targetDir);
+    writeFile(node_path_1.default.join(targetDir, 'principles.md'), renderPrinciplesMd(result), 'write principles.md');
+    count++;
+    writeFile(node_path_1.default.join(targetDir, 'rules.md'), renderRulesMd(result), 'write rules.md');
+    count++;
+    writeFile(node_path_1.default.join(targetDir, 'anti-patterns.md'), renderAntiPatternsMd(result), 'write anti-patterns.md');
+    count++;
+    writeFile(node_path_1.default.join(targetDir, 'glossary.md'), renderGlossaryMd(result), 'write glossary.md');
+    count++;
+    if (result.patterns.length > 0) {
+        const patternsDir = node_path_1.default.join(targetDir, 'patterns');
+        ensureDir(patternsDir);
+        for (const pattern of result.patterns) {
+            const filename = `${slugify(pattern.name)}.md`;
+            writeFile(node_path_1.default.join(patternsDir, filename), renderPatternMd(pattern), `write pattern ${filename}`);
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Parses an existing data.ngql file to find the next available IDs
+ * for domains, patterns, and technologies.
+ */
+function findNextIds(dataPath) {
+    const ids = { domain: 1, pattern: 1, technology: 1 };
+    if (!node_fs_1.default.existsSync(dataPath)) {
+        return ids;
+    }
+    const content = node_fs_1.default.readFileSync(dataPath, 'utf8');
+    // Find highest DOM-NNN
+    const domMatches = content.matchAll(/DOM-(\d+)/g);
+    for (const m of domMatches) {
+        const num = parseInt(m[1], 10);
+        if (num >= ids.domain)
+            ids.domain = num + 1;
+    }
+    // Find highest PAT-NNN
+    const patMatches = content.matchAll(/PAT-(\d+)/g);
+    for (const m of patMatches) {
+        const num = parseInt(m[1], 10);
+        if (num >= ids.pattern)
+            ids.pattern = num + 1;
+    }
+    // Find highest TECH-NNN
+    const techMatches = content.matchAll(/TECH-(\d+)/g);
+    for (const m of techMatches) {
+        const num = parseInt(m[1], 10);
+        if (num >= ids.technology)
+            ids.technology = num + 1;
+    }
+    return ids;
+}
+/**
+ * Generates nGQL INSERT statements for a domain, its technologies,
+ * patterns, and relationships.
+ */
+function generateDomainGraphSeed(result, nextIds) {
+    const lines = [];
+    const pad = (n) => String(n).padStart(3, '0');
+    const domId = `DOM-${pad(nextIds.domain)}`;
+    // Domain vertex
+    lines.push(`INSERT VERTEX Node(name, type, status, summary) VALUES` +
+        ` "${domId}":("${escape(result.domainName)}", "domain", "active", "${escape(result.summary)}");`);
+    // Technology vertices and edges
+    let techCounter = nextIds.technology;
+    for (const tech of result.technologies) {
+        const techId = `TECH-${pad(techCounter)}`;
+        lines.push(`INSERT VERTEX Node(name, type, status, summary) VALUES` +
+            ` "${techId}":("${escape(tech.name)}", "technology", "active", "${escape(tech.summary)}");`);
+        lines.push(`INSERT EDGE Relationship(type) VALUES` +
+            ` "${domId}"->"${techId}":("USES_TECHNOLOGY");`);
+        techCounter++;
+    }
+    // Pattern vertices and edges
+    let patCounter = nextIds.pattern;
+    for (const pat of result.patterns) {
+        const patId = `PAT-${pad(patCounter)}`;
+        lines.push(`INSERT VERTEX Node(name, type, status, summary) VALUES` +
+            ` "${patId}":("${escape(pat.name)}", "pattern", "active", "${escape(pat.context)}");`);
+        lines.push(`INSERT EDGE Relationship(type) VALUES` +
+            ` "${domId}"->"${patId}":("IMPLEMENTS");`);
+        patCounter++;
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+function escape(str) {
+    return str.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, ' ');
+}
+/**
+ * Appends nGQL statements to a data.ngql file, creating parent dirs if needed.
+ *
+ * When an executor is provided, the write goes through the executor abstraction
+ * to respect `--dry-run` mode and centralized side-effect control.
+ */
+function appendGraphSeed(dataPath, nGql, executor) {
+    const separator = `\n-- Domain generated by collab-cli (${new Date().toISOString().split('T')[0]})\n`;
+    const existing = node_fs_1.default.existsSync(dataPath) ? node_fs_1.default.readFileSync(dataPath, 'utf8') : '';
+    if (executor) {
+        executor.writeFile(dataPath, existing + separator + nGql, { description: 'append graph seed' });
+    }
+    else {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(dataPath), { recursive: true });
+        node_fs_1.default.appendFileSync(dataPath, separator + nGql, 'utf8');
+    }
+}
+// ────────────────────────────────────────────────────────────────
+// AI prompt
+// ────────────────────────────────────────────────────────────────
+const DOMAIN_GEN_SYSTEM_PROMPT = `You are a software architecture analyst. Your task is to analyze a repository and generate canonical domain definitions following the collab-architecture framework format.
+
+You MUST respond with a single JSON object — no markdown, no explanations, just JSON.
+
+The JSON must follow this exact schema:
+
+{
+  "domainName": "Human-readable domain name (e.g. 'Chat AI', 'User Management')",
+  "domainSlug": "kebab-case slug (e.g. 'chat-ai', 'user-management')",
+  "prefix": "SHORT uppercase prefix for IDs (e.g. 'CHAT', 'USR') — max 4 characters",
+  "summary": "One-sentence summary of this domain's purpose",
+  "principles": [
+    { "id": "{PREFIX}-P-001", "text": "Concise principle statement" }
+  ],
+  "rules": [
+    { "id": "{PREFIX}-R-001", "text": "Prescriptive rule using MUST/MUST NOT language" }
+  ],
+  "antiPatterns": [
+    {
+      "id": "{PREFIX}-AP-001",
+      "description": "Description of the anti-pattern",
+      "rulesViolated": ["{PREFIX}-R-001"]
+    }
+  ],
+  "glossary": [
+    { "term": "Term", "definition": "Clear one-line definition" }
+  ],
+  "patterns": [
+    {
+      "id": "{PREFIX}-PAT-001",
+      "name": "Pattern Name",
+      "context": "When/where this pattern applies",
+      "problem": "What problem it solves",
+      "solution": "How to implement it",
+      "rulesEnforced": ["{PREFIX}-R-001"],
+      "consequences": "What happens when you follow this pattern"
+    }
+  ],
+  "technologies": [
+    { "name": "Technology Name", "summary": "Brief description of role in domain" }
+  ]
+}
+
+Guidelines:
+- Generate 3-7 principles, 3-7 rules, 2-5 anti-patterns, 5-10 glossary terms, 2-5 patterns, and list all key technologies
+- Principles are aspirational statements of what should be true
+- Rules are prescriptive and use MUST/MUST NOT language
+- Anti-patterns reference specific rule IDs they violate
+- Patterns reference specific rule IDs they enforce
+- Technologies should list frameworks, databases, message brokers, etc. used by the domain`;
+/**
+ * Builds the AI prompt messages for domain generation.
+ */
+function buildDomainGenPrompt(repoCtx) {
+    const parts = [
+        `# Repository: ${repoCtx.name}`,
+        '',
+        `**Language:** ${repoCtx.language}`,
+        repoCtx.framework ? `**Framework:** ${repoCtx.framework}` : null,
+        `**Source files:** ${repoCtx.totalSourceFiles}`,
+        '',
+        '## Dependencies',
+        repoCtx.dependencies.length > 0
+            ? repoCtx.dependencies.map((d) => `- ${d}`).join('\n')
+            : '_No dependencies detected._',
+        '',
+        '## Key Files',
+        repoCtx.keyFiles.map((f) => `- ${f}`).join('\n'),
+        '',
+        '## Directory Structure',
+        '```',
+        repoCtx.structure,
+        '```',
+        '',
+        'Analyze this repository and generate a complete domain definition as a JSON object.',
+    ];
+    return {
+        system: DOMAIN_GEN_SYSTEM_PROMPT,
+        user: parts.filter((p) => p !== null).join('\n'),
+    };
+}
+// ────────────────────────────────────────────────────────────────
+// Response parser
+// ────────────────────────────────────────────────────────────────
+/**
+ * Parses the AI response into a DomainGenerationResult.
+ * Handles JSON wrapped in markdown code fences.
+ * Validates required fields and nested element shapes, failing fast on malformed data.
+ */
+function parseDomainGenerationResponse(raw) {
+    const jsonStr = (0, repo_analysis_helpers_1.extractJson)(raw);
+    const parsed = JSON.parse(jsonStr);
+    // Validate required fields
+    const required = ['domainName', 'domainSlug', 'prefix', 'summary'];
+    for (const field of required) {
+        if (!parsed[field] || typeof parsed[field] !== 'string') {
+            throw new Error(`Missing or invalid required field: ${field}`);
+        }
+    }
+    return {
+        domainName: parsed.domainName,
+        domainSlug: parsed.domainSlug,
+        prefix: parsed.prefix,
+        summary: parsed.summary,
+        principles: validateArray(parsed.principles, 'principles', ['id', 'text']),
+        rules: validateArray(parsed.rules, 'rules', ['id', 'text']),
+        antiPatterns: validateArray(parsed.antiPatterns, 'antiPatterns', ['id', 'description']),
+        glossary: validateArray(parsed.glossary, 'glossary', ['term', 'definition']),
+        patterns: validateArray(parsed.patterns, 'patterns', ['id', 'name']),
+        technologies: validateArray(parsed.technologies, 'technologies', ['name', 'summary']),
+    };
+}
+/**
+ * Validates an array field from the AI response, filtering out malformed entries
+ * and ensuring each element has the required string fields.
+ */
+function validateArray(value, fieldName, requiredKeys) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => {
+        if (typeof item !== 'object' || item === null)
+            return false;
+        const obj = item;
+        return requiredKeys.every((key) => typeof obj[key] === 'string' && obj[key] !== '');
+    });
+}

package/dist/lib/ecosystem.js

@@ -0,0 +1,150 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkEcosystemCompatibility = checkEcosystemCompatibility;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const semver_1 = __importDefault(require("semver"));
+const health_checker_1 = require("./health-checker");
+const MANIFEST_PATH = node_path_1.default.resolve(__dirname, '../../ecosystem.manifest.json');
+function readJsonFile(targetFile) {
+    try {
+        const raw = node_fs_1.default.readFileSync(targetFile, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function readManifest() {
+    const manifest = readJsonFile(MANIFEST_PATH);
+    if (!manifest) {
+        return {
+            manifestVersion: '1.0.0',
+            cliVersionRange: '>=0.1.0',
+            collabArchitectureSchemaRange: '^1.0.0',
+            collabArchitectureMcpVersionRange: '^0.1.0',
+            collabArchitectureMcpContractRange: '^1.0.0',
+        };
+    }
+    return manifest;
+}
+function readCliVersion() {
+    const packagePath = node_path_1.default.resolve(__dirname, '../../package.json');
+    const pkg = readJsonFile(packagePath);
+    return pkg?.version ?? '0.0.0';
+}
+function findSchemaVersionFile(config) {
+    const envOverride = process.env.COLLAB_ARCHITECTURE_SCHEMA_PATH;
+    if (envOverride && node_fs_1.default.existsSync(envOverride)) {
+        return node_path_1.default.resolve(envOverride);
+    }
+    const candidates = [
+        node_path_1.default.resolve(config.workspaceDir, '../collab-architecture/schema/version.json'),
+        node_path_1.default.resolve(config.workspaceDir, 'collab-architecture/schema/version.json'),
+    ];
+    for (const candidate of candidates) {
+        if (node_fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+async function checkEcosystemCompatibility(config, options = {}) {
+    const manifest = readManifest();
+    const checks = [];
+    const cliVersion = readCliVersion();
+    const cliCompatible = semver_1.default.satisfies(cliVersion, manifest.cliVersionRange, {
+        includePrerelease: true,
+    });
+    checks.push({
+        id: 'cli-version',
+        ok: cliCompatible,
+        detail: `CLI ${cliVersion} vs required ${manifest.cliVersionRange}`,
+        fix: `Upgrade collab-cli to satisfy ${manifest.cliVersionRange}.`,
+    });
+    const schemaFile = findSchemaVersionFile(config);
+    if (!schemaFile) {
+        checks.push({
+            id: 'canon-schema-version',
+            ok: false,
+            detail: 'schema/version.json not found for collab-architecture',
+            fix: 'Clone collab-architecture next to this workspace or set COLLAB_ARCHITECTURE_SCHEMA_PATH.',
+        });
+    }
+    else {
+        const schema = readJsonFile(schemaFile);
+        const schemaVersion = schema?.schemaVersion ?? '0.0.0';
+        const schemaCompatible = semver_1.default.satisfies(schemaVersion, manifest.collabArchitectureSchemaRange, {
+            includePrerelease: true,
+        });
+        checks.push({
+            id: 'canon-schema-version',
+            ok: schemaCompatible,
+            detail: `schema ${schemaVersion} vs required ${manifest.collabArchitectureSchemaRange}`,
+            fix: 'Update collab-architecture to a compatible schema version.',
+        });
+        if (schema?.minCompatibleCLI) {
+            const minCliCompatible = semver_1.default.gte(cliVersion, schema.minCompatibleCLI);
+            checks.push({
+                id: 'canon-min-cli',
+                ok: minCliCompatible,
+                detail: `CLI ${cliVersion} vs schema minCompatibleCLI ${schema.minCompatibleCLI}`,
+                fix: `Upgrade collab-cli to >= ${schema.minCompatibleCLI}.`,
+            });
+        }
+    }
+    const mcpHealthUrl = options.mcpHealthUrl ??
+        `http://${process.env.MCP_HOST || '127.0.0.1'}:${process.env.MCP_PORT || '7337'}/health`;
+    const mcpHealth = await (0, health_checker_1.checkHttpHealth)('mcp-health', mcpHealthUrl, {
+        retries: 1,
+        timeoutMs: 3_000,
+        retryDelayMs: 0,
+        dryRun: options.dryRun,
+    });
+    if (!mcpHealth.ok || mcpHealth.skipped) {
+        checks.push({
+            id: 'mcp-version',
+            ok: Boolean(mcpHealth.skipped),
+            detail: mcpHealth.skipped
+                ? 'skipped in dry-run mode'
+                : `MCP health endpoint unreachable (${mcpHealth.error ?? mcpHealth.detail})`,
+            fix: 'Start MCP service and retry doctor or compatibility checks.',
+        });
+    }
+    else {
+        try {
+            const response = await fetch(mcpHealthUrl);
+            const payload = (await response.json());
+            const mcpVersion = payload.version ?? '0.0.0';
+            const contractVersion = payload.contractVersion ?? '0.0.0';
+            checks.push({
+                id: 'mcp-version',
+                ok: semver_1.default.satisfies(mcpVersion, manifest.collabArchitectureMcpVersionRange, {
+                    includePrerelease: true,
+                }),
+                detail: `MCP ${mcpVersion} vs required ${manifest.collabArchitectureMcpVersionRange}`,
+                fix: 'Upgrade/downgrade collab-architecture-mcp to a compatible version.',
+            });
+            checks.push({
+                id: 'mcp-contract-version',
+                ok: semver_1.default.satisfies(contractVersion, manifest.collabArchitectureMcpContractRange, {
+                    includePrerelease: true,
+                }),
+                detail: `MCP contract ${contractVersion} vs required ${manifest.collabArchitectureMcpContractRange}`,
+                fix: 'Upgrade collab-architecture-mcp or update compatibility manifest.',
+            });
+        }
+        catch (error) {
+            checks.push({
+                id: 'mcp-version',
+                ok: false,
+                detail: error instanceof Error ? error.message : String(error),
+                fix: 'Verify MCP /health endpoint returns JSON with version and contractVersion.',
+            });
+        }
+    }
+    return checks;
+}

package/dist/lib/env-file.js

@@ -0,0 +1,77 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readEnvFile = readEnvFile;
+exports.mergeEnvWithDefaults = mergeEnvWithDefaults;
+exports.renderEnvFile = renderEnvFile;
+exports.writeEnvFile = writeEnvFile;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function parseEnvLine(line) {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) {
+        return null;
+    }
+    const index = trimmed.indexOf('=');
+    if (index <= 0) {
+        return null;
+    }
+    const key = trimmed.slice(0, index).trim();
+    const value = trimmed.slice(index + 1);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+        return null;
+    }
+    return [key, value];
+}
+function readEnvFile(filePath) {
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return {};
+    }
+    const content = node_fs_1.default.readFileSync(filePath, 'utf8');
+    const env = {};
+    for (const line of content.split(/\r?\n/)) {
+        const parsed = parseEnvLine(line);
+        if (parsed) {
+            env[parsed[0]] = parsed[1];
+        }
+    }
+    return env;
+}
+function mergeEnvWithDefaults(existing, defaults) {
+    const merged = { ...defaults };
+    for (const [key, value] of Object.entries(existing)) {
+        merged[key] = value;
+    }
+    return merged;
+}
+function renderEnvFile(env, keyOrder) {
+    const orderedKeys = new Set();
+    const lines = [];
+    for (const key of keyOrder) {
+        if (key in env) {
+            lines.push(`${key}=${env[key]}`);
+            orderedKeys.add(key);
+        }
+    }
+    const customKeys = Object.keys(env)
+        .filter((key) => !orderedKeys.has(key))
+        .sort((a, b) => a.localeCompare(b));
+    if (customKeys.length > 0) {
+        lines.push('');
+        for (const key of customKeys) {
+            lines.push(`${key}=${env[key]}`);
+        }
+    }
+    return `# Generated by collab-cli. You can edit values; regeneration preserves your overrides.\n${lines.join('\n')}\n`;
+}
+function writeEnvFile(filePath, env, keyOrder, executor) {
+    const rendered = renderEnvFile(env, keyOrder);
+    if (executor) {
+        executor.writeFile(filePath, rendered, { description: 'write env file' });
+        return;
+    }
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+    node_fs_1.default.writeFileSync(filePath, rendered, 'utf8');
+}

package/dist/lib/errors.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandExecutionError = exports.CliError = void 0;
+/**
+ * Base error class for all expected CLI failures.
+ * The top-level entrypoint catches these and exits with `exitCode`
+ * instead of printing an unhandled exception stack trace.
+ */
+class CliError extends Error {
+    exitCode;
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = 'CliError';
+        this.exitCode = exitCode;
+    }
+}
+exports.CliError = CliError;
+/**
+ * Thrown when a subprocess exits with a non-zero status.
+ * Carries the full stdout/stderr for diagnostics.
+ */
+class CommandExecutionError extends CliError {
+    details;
+    constructor(message, details) {
+        super(message, details.exitCode ?? 1);
+        this.name = 'CommandExecutionError';
+        this.details = details;
+    }
+}
+exports.CommandExecutionError = CommandExecutionError;