@contractual/cli 0.1.0-dev.0

package/dist/config/schema.json

@@ -0,0 +1,121 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://contractual.dev/schemas/config.json",
+    "title": "Contractual Configuration",
+    "description": "Configuration file for Contractual schema contract lifecycle orchestrator",
+    "type": "object",
+    "required": ["contracts"],
+    "properties": {
+        "contracts": {
+            "type": "array",
+            "description": "List of contract definitions",
+            "minItems": 1,
+            "items": {
+                "type": "object",
+                "required": ["name", "type", "path"],
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Unique identifier for the contract",
+                        "pattern": "^[a-z][a-z0-9-]*$"
+                    },
+                    "type": {
+                        "type": "string",
+                        "description": "Type of schema",
+                        "enum": ["openapi", "json-schema", "asyncapi", "odcs"]
+                    },
+                    "path": {
+                        "type": "string",
+                        "description": "Path to spec file (can be glob pattern)"
+                    },
+                    "lint": {
+                        "oneOf": [
+                            { "type": "string", "description": "Linter tool name or custom command" },
+                            { "type": "boolean", "const": false, "description": "Disable linting" }
+                        ]
+                    },
+                    "breaking": {
+                        "oneOf": [
+                            { "type": "string", "description": "Differ tool name or custom command" },
+                            { "type": "boolean", "const": false, "description": "Disable breaking change detection" }
+                        ]
+                    },
+                    "generate": {
+                        "type": "array",
+                        "description": "Output generation commands",
+                        "items": { "type": "string" }
+                    }
+                },
+                "additionalProperties": false
+            }
+        },
+        "versioning": {
+            "type": "object",
+            "description": "Versioning configuration",
+            "properties": {
+                "mode": {
+                    "type": "string",
+                    "enum": ["independent", "fixed"],
+                    "description": "Versioning mode: independent (each contract separate) or fixed (all share same version)",
+                    "default": "independent"
+                }
+            },
+            "additionalProperties": false
+        },
+        "changeset": {
+            "type": "object",
+            "description": "Changeset behavior configuration",
+            "properties": {
+                "autoDetect": {
+                    "type": "boolean",
+                    "description": "Auto-detect change classifications",
+                    "default": true
+                },
+                "requireOnPR": {
+                    "type": "boolean",
+                    "description": "Require changeset for spec changes in PRs",
+                    "default": true
+                }
+            },
+            "additionalProperties": false
+        },
+        "ai": {
+            "type": "object",
+            "description": "AI/LLM integration configuration",
+            "properties": {
+                "provider": {
+                    "type": "string",
+                    "enum": ["anthropic"],
+                    "default": "anthropic"
+                },
+                "model": {
+                    "type": "string",
+                    "description": "Model to use"
+                },
+                "features": {
+                    "type": "object",
+                    "properties": {
+                        "explain": {
+                            "type": "boolean",
+                            "description": "PR change explanations",
+                            "default": true
+                        },
+                        "changelog": {
+                            "type": "boolean",
+                            "description": "AI-enriched changelog entries",
+                            "default": true
+                        },
+                        "enhance": {
+                            "type": "boolean",
+                            "description": "Spec metadata enhancement",
+                            "default": false
+                        }
+                    },
+                    "additionalProperties": false
+                }
+            },
+            "additionalProperties": false
+        }
+    },
+    "additionalProperties": false
+}

package/dist/config/validator.d.ts

@@ -0,0 +1,28 @@
+import type { ContractualConfig } from '@contractual/types';
+/**
+ * Validation error with path and message
+ */
+export interface ValidationError {
+    path: string;
+    message: string;
+}
+/**
+ * Result of config validation
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/**
+ * Validates a parsed config object against the JSON schema
+ */
+export declare function validateConfig(config: unknown): ValidationResult;
+/**
+ * Type guard to check if config is valid ContractualConfig
+ */
+export declare function isValidConfig(config: unknown): config is ContractualConfig;
+/**
+ * Format validation errors for display
+ */
+export declare function formatValidationErrors(errors: ValidationError[]): string;
+//# sourceMappingURL=validator.d.ts.map

package/dist/config/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/config/validator.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAiBhE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,iBAAiB,CAE1E;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,CAExE"}

package/dist/config/validator.js

@@ -0,0 +1,34 @@
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+const AjvConstructor = Ajv.default ?? Ajv;
+const addFormatsFunc = addFormats.default ?? addFormats;
+import configSchema from './schema.json' with { type: 'json' };
+/**
+ * Validates a parsed config object against the JSON schema
+ */
+export function validateConfig(config) {
+    const ajv = new AjvConstructor({ allErrors: true, strict: false });
+    addFormatsFunc(ajv);
+    const validate = ajv.compile(configSchema);
+    const valid = validate(config);
+    if (valid) {
+        return { valid: true, errors: [] };
+    }
+    const errors = (validate.errors ?? []).map((err) => ({
+        path: err.instancePath || '/',
+        message: err.message ?? 'Unknown validation error',
+    }));
+    return { valid: false, errors };
+}
+/**
+ * Type guard to check if config is valid ContractualConfig
+ */
+export function isValidConfig(config) {
+    return validateConfig(config).valid;
+}
+/**
+ * Format validation errors for display
+ */
+export function formatValidationErrors(errors) {
+    return errors.map((err) => `  ${err.path}: ${err.message}`).join('\n');
+}

package/dist/core/diff.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Core diffing logic
+ *
+ * Shared module for running diffs across contracts.
+ * Used by `diff`, `breaking`, and `changeset` commands.
+ */
+import type { ResolvedConfig, DiffResult } from '@contractual/types';
+export interface DiffOptions {
+    /** Filter to specific contract names */
+    contracts?: string[];
+    /** Include contracts with no changes in results */
+    includeEmpty?: boolean;
+}
+export interface DiffContractsResult {
+    results: DiffResult[];
+    contractualDir: string;
+}
+/**
+ * Core diffing function. Runs the appropriate differ for each contract,
+ * comparing current spec against last versioned snapshot.
+ *
+ * Returns classified changes for all contracts.
+ * This is the primitive that `diff`, `breaking`, and `changeset` all use.
+ */
+export declare function diffContracts(config: ResolvedConfig, options?: DiffOptions): Promise<DiffContractsResult>;
+//# sourceMappingURL=diff.d.ts.map

package/dist/core/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/core/diff.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAoB,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAIvF,MAAM,WAAW,WAAW;IAC1B,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,mDAAmD;IACnD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CA+B9B"}

package/dist/core/diff.js

@@ -0,0 +1,89 @@
+/**
+ * Core diffing logic
+ *
+ * Shared module for running diffs across contracts.
+ * Used by `diff`, `breaking`, and `changeset` commands.
+ */
+import { getDiffer } from '../governance/index.js';
+import { findContractualDir, getSnapshotPath } from '../utils/files.js';
+/**
+ * Core diffing function. Runs the appropriate differ for each contract,
+ * comparing current spec against last versioned snapshot.
+ *
+ * Returns classified changes for all contracts.
+ * This is the primitive that `diff`, `breaking`, and `changeset` all use.
+ */
+export async function diffContracts(config, options = {}) {
+    const contractualDir = findContractualDir(config.configDir);
+    if (!contractualDir) {
+        throw new Error('No .contractual directory found. Run `contractual init` first.');
+    }
+    // Filter contracts if specific ones requested
+    let contracts = config.contracts;
+    if (options.contracts && options.contracts.length > 0) {
+        contracts = config.contracts.filter((c) => options.contracts.includes(c.name));
+        // Check for missing contracts
+        for (const name of options.contracts) {
+            if (!config.contracts.some((c) => c.name === name)) {
+                throw new Error(`Contract "${name}" not found in configuration.`);
+            }
+        }
+    }
+    const results = [];
+    for (const contract of contracts) {
+        const result = await diffSingleContract(contract, contractualDir);
+        // Include result if it has changes, or if includeEmpty is true
+        if (result.changes.length > 0 || options.includeEmpty) {
+            results.push(result);
+        }
+    }
+    return { results, contractualDir };
+}
+/**
+ * Diff a single contract against its snapshot
+ */
+async function diffSingleContract(contract, contractualDir) {
+    // Get snapshot path
+    const snapshotPath = getSnapshotPath(contract.name, contractualDir);
+    // No snapshot = first version, no changes
+    if (!snapshotPath) {
+        return createEmptyResult(contract.name, 'first-version');
+    }
+    // Check if breaking detection is disabled
+    if (contract.breaking === false) {
+        return createEmptyResult(contract.name, 'disabled');
+    }
+    // Get the differ from the registry
+    const differ = getDiffer(contract.type, contract.breaking);
+    if (differ === null) {
+        // Disabled via config override
+        return createEmptyResult(contract.name, 'disabled');
+    }
+    if (!differ) {
+        // No differ registered for this type
+        return createEmptyResult(contract.name, 'no-differ');
+    }
+    // Run the differ: snapshot (old) vs current spec (new)
+    const diffResult = await differ(snapshotPath, contract.absolutePath);
+    // Override contract name to match config
+    return {
+        ...diffResult,
+        contract: contract.name,
+    };
+}
+/**
+ * Create an empty diff result
+ */
+function createEmptyResult(contractName, _reason) {
+    return {
+        contract: contractName,
+        changes: [],
+        summary: {
+            breaking: 0,
+            nonBreaking: 0,
+            patch: 0,
+            unknown: 0,
+        },
+        suggestedBump: 'none',
+    };
+}

package/dist/formatters/diff.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Diff output formatters
+ *
+ * Format diff results for text and JSON output.
+ */
+import type { DiffResult } from '@contractual/types';
+export interface FormatOptions {
+    /** Show JSON Pointer paths for each change */
+    verbose?: boolean;
+}
+/**
+ * Format diff results as human-readable text
+ */
+export declare function formatDiffText(results: DiffResult[], options?: FormatOptions): void;
+/**
+ * Format diff results as JSON
+ *
+ * Output format:
+ * {
+ *   "contracts": {
+ *     "order": { "changes": [...], "summary": {...}, "suggestedBump": "minor" },
+ *     "petstore": { "changes": [...], "summary": {...}, "suggestedBump": "none" }
+ *   }
+ * }
+ */
+export declare function formatDiffJson(results: DiffResult[]): string;
+/**
+ * Filter results by severity level
+ */
+export declare function filterBySeverity(results: DiffResult[], severity: string): DiffResult[];
+//# sourceMappingURL=diff.d.ts.map

package/dist/formatters/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"","sources":["../../src/formatters/diff.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAuC,MAAM,oBAAoB,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,8CAA8C;IAC9C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,IAAI,CASvF;AAsED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAS5D;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,EAAE,CActF"}

package/dist/formatters/diff.js

@@ -0,0 +1,139 @@
+/**
+ * Diff output formatters
+ *
+ * Format diff results for text and JSON output.
+ */
+import chalk from 'chalk';
+/**
+ * Format diff results as human-readable text
+ */
+export function formatDiffText(results, options = {}) {
+    if (results.length === 0) {
+        console.log(chalk.dim('No contracts to diff.'));
+        return;
+    }
+    for (const result of results) {
+        formatContractResult(result, options);
+    }
+}
+/**
+ * Format a single contract's diff result
+ */
+function formatContractResult(result, options) {
+    if (result.changes.length === 0) {
+        console.log(`${chalk.cyan(result.contract)}: ${chalk.dim('no changes')}`);
+        console.log();
+        return;
+    }
+    // Build summary parts
+    const parts = [];
+    if (result.summary.breaking > 0) {
+        parts.push(`${result.summary.breaking} breaking`);
+    }
+    if (result.summary.nonBreaking > 0) {
+        parts.push(`${result.summary.nonBreaking} non-breaking`);
+    }
+    if (result.summary.patch > 0) {
+        parts.push(`${result.summary.patch} patch`);
+    }
+    if (result.summary.unknown > 0) {
+        parts.push(`${result.summary.unknown} unknown`);
+    }
+    // Color for suggested bump
+    const bumpColor = result.suggestedBump === 'major'
+        ? chalk.red
+        : result.suggestedBump === 'minor'
+            ? chalk.yellow
+            : chalk.green;
+    // Header line
+    console.log(`${chalk.cyan(result.contract)}: ${result.changes.length} change(s) (${parts.join(', ')}) — suggested bump: ${bumpColor(result.suggestedBump)}`);
+    console.log();
+    // Each change
+    for (const change of result.changes) {
+        const label = formatSeverityLabel(change.severity);
+        console.log(`  ${label} ${change.message}`);
+        if (options.verbose && change.path) {
+            console.log(`${' '.repeat(14)}path: ${chalk.dim(change.path)}`);
+        }
+    }
+    console.log();
+}
+/**
+ * Format severity as a colored, padded label
+ */
+function formatSeverityLabel(severity) {
+    switch (severity) {
+        case 'breaking':
+            return chalk.red.bold('BREAKING'.padEnd(12));
+        case 'non-breaking':
+            return chalk.yellow('non-breaking');
+        case 'patch':
+            return chalk.green('patch'.padEnd(12));
+        case 'unknown':
+            return chalk.gray('unknown'.padEnd(12));
+        default:
+            return chalk.gray(String(severity).padEnd(12));
+    }
+}
+/**
+ * Format diff results as JSON
+ *
+ * Output format:
+ * {
+ *   "contracts": {
+ *     "order": { "changes": [...], "summary": {...}, "suggestedBump": "minor" },
+ *     "petstore": { "changes": [...], "summary": {...}, "suggestedBump": "none" }
+ *   }
+ * }
+ */
+export function formatDiffJson(results) {
+    const contracts = {};
+    for (const result of results) {
+        const { contract, ...rest } = result;
+        contracts[contract] = rest;
+    }
+    return JSON.stringify({ contracts }, null, 2);
+}
+/**
+ * Filter results by severity level
+ */
+export function filterBySeverity(results, severity) {
+    if (severity === 'all') {
+        return results;
+    }
+    return results.map((r) => {
+        const filteredChanges = r.changes.filter((c) => c.severity === severity);
+        return {
+            ...r,
+            changes: filteredChanges,
+            summary: recalculateSummary(filteredChanges),
+            suggestedBump: calculateSuggestedBump(filteredChanges),
+        };
+    });
+}
+/**
+ * Recalculate summary from filtered changes
+ */
+function recalculateSummary(changes) {
+    return {
+        breaking: changes.filter((c) => c.severity === 'breaking').length,
+        nonBreaking: changes.filter((c) => c.severity === 'non-breaking').length,
+        patch: changes.filter((c) => c.severity === 'patch').length,
+        unknown: changes.filter((c) => c.severity === 'unknown').length,
+    };
+}
+/**
+ * Calculate suggested bump from changes
+ */
+function calculateSuggestedBump(changes) {
+    if (changes.some((c) => c.severity === 'breaking')) {
+        return 'major';
+    }
+    if (changes.some((c) => c.severity === 'non-breaking')) {
+        return 'minor';
+    }
+    if (changes.some((c) => c.severity === 'patch')) {
+        return 'patch';
+    }
+    return 'none';
+}

package/dist/governance/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-export governance engines from @contractual/governance
+ *
+ * This module re-exports the governance registry functions and auto-registers
+ * all built-in engines on import.
+ */
+import '@contractual/governance';
+export { registerLinter, registerDiffer, getLinter, getDiffer, hasLinter, hasDiffer, getRegisteredLinterTypes, getRegisteredDifferTypes, } from '@contractual/governance';
+export { lintOpenAPI, lintJsonSchema, diffOpenAPI, diffJsonSchema } from '@contractual/governance';
+export { executeCustomCommand, parseCustomLintOutput, parseCustomDiffOutput, } from '@contractual/governance';
+//# sourceMappingURL=index.d.ts.map

package/dist/governance/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/governance/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,yBAAyB,CAAC;AAGjC,OAAO,EACL,cAAc,EACd,cAAc,EACd,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,wBAAwB,EACxB,wBAAwB,GACzB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAGnG,OAAO,EACL,oBAAoB,EACpB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,yBAAyB,CAAC"}

package/dist/governance/index.js

@@ -0,0 +1,14 @@
+/**
+ * Re-export governance engines from @contractual/governance
+ *
+ * This module re-exports the governance registry functions and auto-registers
+ * all built-in engines on import.
+ */
+// Import to trigger auto-registration of all engines
+import '@contractual/governance';
+// Re-export registry functions
+export { registerLinter, registerDiffer, getLinter, getDiffer, hasLinter, hasDiffer, getRegisteredLinterTypes, getRegisteredDifferTypes, } from '@contractual/governance';
+// Re-export individual engines for direct use
+export { lintOpenAPI, lintJsonSchema, diffOpenAPI, diffJsonSchema } from '@contractual/governance';
+// Re-export runner utilities for custom commands
+export { executeCustomCommand, parseCustomLintOutput, parseCustomDiffOutput, } from '@contractual/governance';

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { loadConfig, ConfigError } from './config/index.js';
+export { registerLinter, registerDiffer, getLinter, getDiffer } from './governance/index.js';
+export { diffContracts } from './core/diff.js';
+export type { DiffOptions, DiffContractsResult } from './core/diff.js';
+export { findContractualDir, getSnapshotPath, copyToSnapshots, CONTRACTUAL_DIR, } from './utils/files.js';
+export { VersionManager, PreReleaseManager, createChangeset, readChangesets, aggregateBumps, generateChangesetName, extractContractChanges, appendChangelog, incrementVersionWithPreRelease, VERSIONS_FILE, SNAPSHOTS_DIR, CHANGESETS_DIR, PRE_RELEASE_FILE, } from '@contractual/changesets';
+export type { BumpOperationResult } from '@contractual/changesets';
+export type * from '@contractual/types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAG7F,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,YAAY,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGvE,OAAO,EACL,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,eAAe,EACf,8BAA8B,EAC9B,aAAa,EACb,aAAa,EACb,cAAc,EACd,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAGnE,mBAAmB,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+// Public API for programmatic use
+export { loadConfig, ConfigError } from './config/index.js';
+export { registerLinter, registerDiffer, getLinter, getDiffer } from './governance/index.js';
+// Core diffing
+export { diffContracts } from './core/diff.js';
+// File utilities
+export { findContractualDir, getSnapshotPath, copyToSnapshots, CONTRACTUAL_DIR, } from './utils/files.js';
+// Re-export from @contractual/changesets
+export { VersionManager, PreReleaseManager, createChangeset, readChangesets, aggregateBumps, generateChangesetName, extractContractChanges, appendChangelog, incrementVersionWithPreRelease, VERSIONS_FILE, SNAPSHOTS_DIR, CHANGESETS_DIR, PRE_RELEASE_FILE, } from '@contractual/changesets';

package/dist/utils/exec.d.ts

@@ -0,0 +1,29 @@
+import { type ExecSyncOptions } from 'node:child_process';
+/**
+ * Result of executing a command
+ */
+export interface ExecResult {
+    /** Standard output */
+    stdout: string;
+    /** Standard error */
+    stderr: string;
+    /** Exit code */
+    exitCode: number;
+}
+/**
+ * Substitute placeholders in a command string
+ */
+export declare function substitutePlaceholders(command: string, substitutions: Record<string, string>): string;
+/**
+ * Check if a string contains placeholders
+ */
+export declare function hasPlaceholders(command: string): boolean;
+/**
+ * Execute a command and return the result
+ */
+export declare function execCommand(command: string, substitutions?: Record<string, string>, options?: ExecSyncOptions): ExecResult;
+/**
+ * Execute a command and throw if it fails
+ */
+export declare function execCommandOrThrow(command: string, substitutions?: Record<string, string>, options?: ExecSyncOptions): string;
+//# sourceMappingURL=exec.d.ts.map

package/dist/utils/exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.d.ts","sourceRoot":"","sources":["../../src/utils/exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAY,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAEpE;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAsBD;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,MAAM,CAMR;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExD;AAED;;GAEG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EAC1C,OAAO,GAAE,eAAoB,GAC5B,UAAU,CA2BZ;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EAC1C,OAAO,GAAE,eAAoB,GAC5B,MAAM,CAMR"}

package/dist/utils/exec.js

@@ -0,0 +1,66 @@
+import { execSync } from 'node:child_process';
+/**
+ * Type guard for execSync errors
+ */
+function isExecSyncError(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        ('status' in err || 'stdout' in err || 'stderr' in err));
+}
+/**
+ * Substitute placeholders in a command string
+ */
+export function substitutePlaceholders(command, substitutions) {
+    let result = command;
+    for (const [key, value] of Object.entries(substitutions)) {
+        result = result.replace(new RegExp(`\\{${key}\\}`, 'g'), value);
+    }
+    return result;
+}
+/**
+ * Check if a string contains placeholders
+ */
+export function hasPlaceholders(command) {
+    return /\{(spec|old|new)\}/.test(command);
+}
+/**
+ * Execute a command and return the result
+ */
+export function execCommand(command, substitutions = {}, options = {}) {
+    const resolvedCommand = substitutePlaceholders(command, substitutions);
+    try {
+        const stdout = execSync(resolvedCommand, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+            ...options,
+        });
+        return { stdout, stderr: '', exitCode: 0 };
+    }
+    catch (err) {
+        if (isExecSyncError(err)) {
+            const stdout = typeof err.stdout === 'string' ? err.stdout : (err.stdout?.toString() ?? '');
+            const stderr = typeof err.stderr === 'string' ? err.stderr : (err.stderr?.toString() ?? '');
+            return {
+                stdout,
+                stderr,
+                exitCode: err.status ?? 1,
+            };
+        }
+        // Unknown error type - return generic failure
+        return {
+            stdout: '',
+            stderr: err instanceof Error ? err.message : 'Unknown error',
+            exitCode: 1,
+        };
+    }
+}
+/**
+ * Execute a command and throw if it fails
+ */
+export function execCommandOrThrow(command, substitutions = {}, options = {}) {
+    const result = execCommand(command, substitutions, options);
+    if (result.exitCode !== 0) {
+        throw new Error(`Command failed with exit code ${result.exitCode}: ${result.stderr}`);
+    }
+    return result.stdout;
+}