@jterrats/smart-deployment 1.0.3

package/lib/deployment/test-executor.js

@@ -0,0 +1,87 @@
+/**
+ * Test Execution Management - US-087
+ * Manages intelligent test execution per wave
+ *
+ * @ac US-087-AC-1: Run tests only in Apex waves
+ * @ac US-087-AC-2: Support RunLocalTests
+ * @ac US-087-AC-3: Support RunSpecifiedTests
+ * @ac US-087-AC-4: Support NoTestRun (sandbox)
+ * @ac US-087-AC-5: Track test results
+ * @ac US-087-AC-6: Report coverage
+ * @issue #87
+ */
+import { getLogger } from '../utils/logger.js';
+const logger = getLogger('TestExecutor');
+/**
+ * @ac US-087-AC-1: Run tests only in Apex waves
+ * @ac US-087-AC-2: Support RunLocalTests
+ * @ac US-087-AC-3: Support RunSpecifiedTests
+ * @ac US-087-AC-4: Support NoTestRun (sandbox)
+ */
+export class TestExecutor {
+    determineTestLevel(wave, isSandbox) {
+        // AC-1: Only run tests in Apex waves
+        const hasApex = wave.metadata.types.some((type) => type === 'ApexClass' || type === 'ApexTrigger');
+        // AC-4: No tests in sandbox
+        if (isSandbox) {
+            return {
+                testLevel: 'NoTestRun',
+                tests: [],
+                reason: 'Sandbox deployment - tests not required',
+            };
+        }
+        if (!hasApex) {
+            return {
+                testLevel: 'NoTestRun',
+                tests: [],
+                reason: 'No Apex code in wave',
+            };
+        }
+        // AC-3: Run specified tests if available
+        const apexComponents = wave.components.filter((component) => component.startsWith('ApexClass:') || component.startsWith('ApexTrigger:'));
+        if (apexComponents.length > 0 && apexComponents.length <= 10) {
+            const tests = this.findRelatedTests(apexComponents);
+            if (tests.length > 0) {
+                return {
+                    testLevel: 'RunSpecifiedTests',
+                    tests,
+                    reason: `Running ${tests.length} related tests`,
+                };
+            }
+        }
+        // AC-2: Default to RunLocalTests
+        return {
+            testLevel: 'RunLocalTests',
+            tests: [],
+            reason: 'Running all local tests',
+        };
+    }
+    findRelatedTests(apexComponents) {
+        // Placeholder: In real implementation, this would analyze test classes
+        // and match them to the components being deployed
+        return apexComponents
+            .filter((component) => component.startsWith('ApexClass:'))
+            .map((component) => component.replace('ApexClass:', '') + 'Test');
+    }
+    /**
+     * @ac US-087-AC-5: Track test results
+     * @ac US-087-AC-6: Report coverage
+     */
+    analyzeTestResults(testsRun, testFailures, coverage) {
+        logger.info('Analyzing test results', { testsRun, testFailures, coverage });
+        return {
+            testsRun,
+            testFailures,
+            coverage,
+            failedTests: [], // Would be populated from actual results
+        };
+    }
+    formatTestResults(results) {
+        const lines = [`Tests Run: ${results.testsRun}`, `Failures: ${results.testFailures}`];
+        if (results.coverage !== undefined) {
+            lines.push(`Coverage: ${results.coverage}%`);
+        }
+        return lines.join(' | ');
+    }
+}
+//# sourceMappingURL=test-executor.js.map

package/lib/deployment/test-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-executor.js","sourceRoot":"","sources":["../../src/deployment/test-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAI/C,MAAM,MAAM,GAAG,SAAS,CAAC,cAAc,CAAC,CAAC;AAezC;;;;;GAKG;AACH,MAAM,OAAO,YAAY;IAChB,kBAAkB,CAAC,IAAU,EAAE,SAAkB;QACtD,qCAAqC;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,aAAa,CAAC,CAAC;QAEnG,4BAA4B;QAC5B,IAAI,SAAS,EAAE,CAAC;YACd,OAAO;gBACL,SAAS,EAAE,WAAW;gBACtB,KAAK,EAAE,EAAE;gBACT,MAAM,EAAE,yCAAyC;aAClD,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO;gBACL,SAAS,EAAE,WAAW;gBACtB,KAAK,EAAE,EAAE;gBACT,MAAM,EAAE,sBAAsB;aAC/B,CAAC;QACJ,CAAC;QAED,yCAAyC;QACzC,MAAM,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAC3C,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC,cAAc,CAAC,CAC1F,CAAC;QAEF,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,IAAI,cAAc,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;YAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,gBAAgB,CAAC,cAAc,CAAC,CAAC;YACpD,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACrB,OAAO;oBACL,SAAS,EAAE,mBAAmB;oBAC9B,KAAK;oBACL,MAAM,EAAE,WAAW,KAAK,CAAC,MAAM,gBAAgB;iBAChD,CAAC;YACJ,CAAC;QACH,CAAC;QAED,iCAAiC;QACjC,OAAO;YACL,SAAS,EAAE,eAAe;YAC1B,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,yBAAyB;SAClC,CAAC;IACJ,CAAC;IAEO,gBAAgB,CAAC,cAAwB;QAC/C,uEAAuE;QACvE,kDAAkD;QAClD,OAAO,cAAc;aAClB,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;aACzD,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC;IACtE,CAAC;IAED;;;OAGG;IACI,kBAAkB,CAAC,QAAgB,EAAE,YAAoB,EAAE,QAAiB;QACjF,MAAM,CAAC,IAAI,CAAC,wBAAwB,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,CAAC;QAE5E,OAAO;YACL,QAAQ;YACR,YAAY;YACZ,QAAQ;YACR,WAAW,EAAE,EAAE,EAAE,yCAAyC;SAC3D,CAAC;IACJ,CAAC;IAEM,iBAAiB,CAAC,OAAoB;QAC3C,MAAM,KAAK,GAAG,CAAC,cAAc,OAAO,CAAC,QAAQ,EAAE,EAAE,aAAa,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;QAEtF,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;YACnC,KAAK,CAAC,IAAI,CAAC,aAAa,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QAC/C,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,CAAC;CACF"}

package/lib/errors/base-error.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Base custom error class with context and suggestions
+ *
+ * All plugin errors extend this base class to provide:
+ * - Structured error context
+ * - Actionable suggestions
+ * - JSON serialization
+ * - Stack trace preservation
+ */
+export declare abstract class SmartDeploymentError extends Error {
+    readonly code: string;
+    readonly context: Record<string, unknown>;
+    readonly suggestions: string[];
+    readonly timestamp: Date;
+    constructor(message: string, code: string, context?: Record<string, unknown>, suggestions?: string[]);
+    /**
+     * Serialize error to JSON for logging/reporting
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Format error for display to user
+     */
+    toString(): string;
+}

package/lib/errors/base-error.js

@@ -0,0 +1,66 @@
+/**
+ * Base custom error class with context and suggestions
+ *
+ * All plugin errors extend this base class to provide:
+ * - Structured error context
+ * - Actionable suggestions
+ * - JSON serialization
+ * - Stack trace preservation
+ */
+export class SmartDeploymentError extends Error {
+    code;
+    context;
+    suggestions;
+    timestamp;
+    constructor(message, code, context = {}, suggestions = []) {
+        super(message);
+        // Maintain proper stack trace (V8 engines)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+        this.name = this.constructor.name;
+        this.code = code;
+        this.context = context;
+        this.suggestions = suggestions;
+        this.timestamp = new Date();
+        // Ensure instanceof works correctly
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /**
+     * Serialize error to JSON for logging/reporting
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            context: this.context,
+            suggestions: this.suggestions,
+            timestamp: this.timestamp.toISOString(),
+            stack: this.stack,
+        };
+    }
+    /**
+     * Format error for display to user
+     */
+    toString() {
+        const lines = [`${this.name} [${this.code}]: ${this.message}`, ''];
+        // Add context if present
+        if (Object.keys(this.context).length > 0) {
+            lines.push('Context:');
+            for (const [key, value] of Object.entries(this.context)) {
+                lines.push(`  ${key}: ${JSON.stringify(value)}`);
+            }
+            lines.push('');
+        }
+        // Add suggestions if present
+        if (this.suggestions.length > 0) {
+            lines.push('Suggestions:');
+            for (const suggestion of this.suggestions) {
+                lines.push(`  • ${suggestion}`);
+            }
+        }
+        return lines.join('\n');
+    }
+}
+//# sourceMappingURL=base-error.js.map

package/lib/errors/base-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-error.js","sourceRoot":"","sources":["../../src/errors/base-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,OAAgB,oBAAqB,SAAQ,KAAK;IACtC,IAAI,CAAS;IACb,OAAO,CAA0B;IACjC,WAAW,CAAW;IACtB,SAAS,CAAO;IAEhC,YAAmB,OAAe,EAAE,IAAY,EAAE,UAAmC,EAAE,EAAE,cAAwB,EAAE;QACjH,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,2CAA2C;QAC3C,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAClD,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QAE5B,oCAAoC;QACpC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;IAED;;OAEG;IACI,MAAM;QACX,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE;YACvC,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC;IACJ,CAAC;IAED;;OAEG;IACI,QAAQ;QACb,MAAM,KAAK,GAAa,CAAC,GAAG,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;QAE7E,yBAAyB;QACzB,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACzC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBACxD,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACnD,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;QAED,6BAA6B;QAC7B,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;YAC3B,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBAC1C,KAAK,CAAC,IAAI,CAAC,OAAO,UAAU,EAAE,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;QAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;CACF"}

package/lib/errors/dependency-error.d.ts

@@ -0,0 +1,37 @@
+import { SmartDeploymentError } from './base-error.js';
+/**
+ * Error thrown when dependency analysis or resolution fails
+ *
+ * @example
+ * ```typescript
+ * throw new DependencyError('Circular dependency detected', {
+ *   cycle: ['ApexClass:A', 'ApexClass:B', 'ApexClass:C', 'ApexClass:A'],
+ *   affectedComponents: 3
+ * });
+ * ```
+ */
+export declare class DependencyError extends SmartDeploymentError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when circular dependencies are detected
+ */
+export declare class CircularDependencyError extends DependencyError {
+    constructor(cycle: string[], context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when a required dependency is missing
+ */
+export declare class MissingDependencyError extends DependencyError {
+    constructor(component: string, missingDependency: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when dependency graph is too complex
+ */
+export declare class DependencyComplexityError extends DependencyError {
+    constructor(message: string, context?: {
+        [key: string]: unknown;
+        totalComponents?: number;
+        maxDepth?: number;
+    });
+}

package/lib/errors/dependency-error.js

@@ -0,0 +1,76 @@
+import { SmartDeploymentError } from './base-error.js';
+/**
+ * Error thrown when dependency analysis or resolution fails
+ *
+ * @example
+ * ```typescript
+ * throw new DependencyError('Circular dependency detected', {
+ *   cycle: ['ApexClass:A', 'ApexClass:B', 'ApexClass:C', 'ApexClass:A'],
+ *   affectedComponents: 3
+ * });
+ * ```
+ */
+export class DependencyError extends SmartDeploymentError {
+    constructor(message, context = {}) {
+        const suggestions = [];
+        // Add context-specific suggestions
+        if (context.cycle) {
+            suggestions.push('Break the circular dependency by refactoring shared logic');
+            suggestions.push('Consider using dependency injection or interfaces');
+        }
+        if (context.missingDependency) {
+            suggestions.push(`Add missing dependency: ${String(context.missingDependency)}`);
+            suggestions.push('Check if the component exists in your project');
+        }
+        if (context.affectedComponents) {
+            suggestions.push(`Review ${String(context.affectedComponents)} affected components`);
+        }
+        super(message, 'DEPENDENCY_ERROR', context, suggestions);
+    }
+}
+/**
+ * Error thrown when circular dependencies are detected
+ */
+export class CircularDependencyError extends DependencyError {
+    constructor(cycle, context = {}) {
+        super(`Circular dependency detected: ${cycle.join(' → ')}`, {
+            ...context,
+            cycle,
+            cycleLength: cycle.length,
+        });
+        this.suggestions.push('Visualize the dependency graph to identify the cycle');
+        this.suggestions.push('Extract shared code into a common utility');
+    }
+}
+/**
+ * Error thrown when a required dependency is missing
+ */
+export class MissingDependencyError extends DependencyError {
+    constructor(component, missingDependency, context = {}) {
+        super(`Component '${component}' depends on missing '${missingDependency}'`, {
+            ...context,
+            component,
+            missingDependency,
+        });
+        this.suggestions.push(`Include '${missingDependency}' in your deployment`);
+        this.suggestions.push('Check if the dependency was deleted or renamed');
+        this.suggestions.push('Verify metadata type spelling and casing');
+    }
+}
+/**
+ * Error thrown when dependency graph is too complex
+ */
+export class DependencyComplexityError extends DependencyError {
+    constructor(message, context = {}) {
+        super(message, context);
+        if (context.maxDepth && context.maxDepth > 50) {
+            this.suggestions.push('Dependency depth > 50 indicates over-coupling');
+            this.suggestions.push('Refactor to reduce dependency chains');
+        }
+        if (context.totalComponents && context.totalComponents > 10_000) {
+            this.suggestions.push('Consider splitting into multiple deployments');
+            this.suggestions.push('Use selective deployment for changed components only');
+        }
+    }
+}
+//# sourceMappingURL=dependency-error.js.map

package/lib/errors/dependency-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-error.js","sourceRoot":"","sources":["../../src/errors/dependency-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,eAAgB,SAAQ,oBAAoB;IACvD,YAAmB,OAAe,EAAE,UAAmC,EAAE;QACvE,MAAM,WAAW,GAAa,EAAE,CAAC;QAEjC,mCAAmC;QACnC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,WAAW,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAC;YAC9E,WAAW,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;QACxE,CAAC;QAED,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;YAC9B,WAAW,CAAC,IAAI,CAAC,2BAA2B,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC;YACjF,WAAW,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;QACpE,CAAC;QAED,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;YAC/B,WAAW,CAAC,IAAI,CAAC,UAAU,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,sBAAsB,CAAC,CAAC;QACvF,CAAC;QAED,KAAK,CAAC,OAAO,EAAE,kBAAkB,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;IAC3D,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,uBAAwB,SAAQ,eAAe;IAC1D,YAAmB,KAAe,EAAE,UAAmC,EAAE;QACvE,KAAK,CAAC,iCAAiC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE;YAC1D,GAAG,OAAO;YACV,KAAK;YACL,WAAW,EAAE,KAAK,CAAC,MAAM;SAC1B,CAAC,CAAC;QAEH,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,sDAAsD,CAAC,CAAC;QAC9E,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;IACrE,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,sBAAuB,SAAQ,eAAe;IACzD,YAAmB,SAAiB,EAAE,iBAAyB,EAAE,UAAmC,EAAE;QACpG,KAAK,CAAC,cAAc,SAAS,yBAAyB,iBAAiB,GAAG,EAAE;YAC1E,GAAG,OAAO;YACV,SAAS;YACT,iBAAiB;SAClB,CAAC,CAAC;QAEH,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,YAAY,iBAAiB,sBAAsB,CAAC,CAAC;QAC3E,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,gDAAgD,CAAC,CAAC;QACxE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,0CAA0C,CAAC,CAAC;IACpE,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,yBAA0B,SAAQ,eAAe;IAC5D,YACE,OAAe,EACf,UAII,EAAE;QAEN,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAExB,IAAI,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,GAAG,EAAE,EAAE,CAAC;YAC9C,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,+CAA+C,CAAC,CAAC;YACvE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;QAChE,CAAC;QAED,IAAI,OAAO,CAAC,eAAe,IAAI,OAAO,CAAC,eAAe,GAAG,MAAM,EAAE,CAAC;YAChE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,8CAA8C,CAAC,CAAC;YACtE,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,sDAAsD,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;CACF"}

package/lib/errors/deployment-error.d.ts

@@ -0,0 +1,55 @@
+import { SmartDeploymentError } from './base-error.js';
+/**
+ * Error thrown when Salesforce deployment fails
+ *
+ * @example
+ * ```typescript
+ * throw new DeploymentError('Deployment failed due to test failures', {
+ *   deploymentId: '0Af...',
+ *   failedTests: ['AccountServiceTest.testInsert'],
+ *   testCoverage: 68
+ * });
+ * ```
+ */
+export declare class DeploymentError extends SmartDeploymentError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when deployment validation fails
+ */
+export declare class DeploymentValidationError extends DeploymentError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when test execution fails during deployment
+ */
+export declare class TestFailureError extends DeploymentError {
+    constructor(failedTests: string[], context?: {
+        [key: string]: unknown;
+        totalTests?: number;
+        passedTests?: number;
+        testCoverage?: number;
+    });
+}
+/**
+ * Error thrown when deployment times out
+ */
+export declare class DeploymentTimeoutError extends DeploymentError {
+    constructor(timeoutMs: number, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when deployment exceeds Salesforce limits
+ */
+export declare class DeploymentLimitError extends DeploymentError {
+    constructor(limitType: 'files' | 'size' | 'components', limit: number, actual: number, context?: Record<string, unknown>);
+}
+/**
+ * Error thrown when Salesforce API returns an error
+ */
+export declare class SalesforceApiError extends DeploymentError {
+    constructor(apiError: string, context?: {
+        [key: string]: unknown;
+        statusCode?: number;
+        errorCode?: string;
+    });
+}

package/lib/errors/deployment-error.js

@@ -0,0 +1,132 @@
+import { SmartDeploymentError } from './base-error.js';
+/**
+ * Error thrown when Salesforce deployment fails
+ *
+ * @example
+ * ```typescript
+ * throw new DeploymentError('Deployment failed due to test failures', {
+ *   deploymentId: '0Af...',
+ *   failedTests: ['AccountServiceTest.testInsert'],
+ *   testCoverage: 68
+ * });
+ * ```
+ */
+export class DeploymentError extends SmartDeploymentError {
+    constructor(message, context = {}) {
+        const suggestions = [];
+        // Add context-specific suggestions
+        if (context.deploymentId) {
+            suggestions.push(`Check deployment status: sf project deploy report -i ${String(context.deploymentId)}`);
+        }
+        if (context.failedTests) {
+            suggestions.push('Review and fix failing test classes');
+            suggestions.push('Run tests locally: sf apex run test');
+        }
+        if (context.testCoverage && typeof context.testCoverage === 'number' && context.testCoverage < 75) {
+            suggestions.push('Increase test coverage to at least 75%');
+            suggestions.push('Add test methods for untested code paths');
+        }
+        if (context.componentFailures) {
+            suggestions.push('Review component-specific errors in the deployment report');
+        }
+        super(message, 'DEPLOYMENT_ERROR', context, suggestions);
+    }
+}
+/**
+ * Error thrown when deployment validation fails
+ */
+export class DeploymentValidationError extends DeploymentError {
+    constructor(message, context = {}) {
+        super(`Deployment validation failed: ${message}`, {
+            ...context,
+            validationError: true,
+        });
+        this.suggestions.push('Run validation before deploying: sf project deploy validate');
+        this.suggestions.push('Fix validation errors and retry');
+    }
+}
+/**
+ * Error thrown when test execution fails during deployment
+ */
+export class TestFailureError extends DeploymentError {
+    constructor(failedTests, context = {}) {
+        super(`${failedTests.length} test(s) failed`, {
+            ...context,
+            failedTests,
+        });
+        this.suggestions.push('Review failed test methods:');
+        for (const test of failedTests.slice(0, 5)) {
+            // Show max 5
+            this.suggestions.push(`  - ${test}`);
+        }
+        if (failedTests.length > 5) {
+            this.suggestions.push(`  ... and ${failedTests.length - 5} more`);
+        }
+        this.suggestions.push('Run failed tests locally to debug');
+    }
+}
+/**
+ * Error thrown when deployment times out
+ */
+export class DeploymentTimeoutError extends DeploymentError {
+    constructor(timeoutMs, context = {}) {
+        super(`Deployment timed out after ${timeoutMs}ms`, {
+            ...context,
+            timeoutMs,
+        });
+        this.suggestions.push('Large deployments may exceed timeout limits');
+        this.suggestions.push('Consider splitting into smaller waves');
+        this.suggestions.push('Increase timeout if appropriate for your org');
+    }
+}
+/**
+ * Error thrown when deployment exceeds Salesforce limits
+ */
+export class DeploymentLimitError extends DeploymentError {
+    constructor(limitType, limit, actual, context = {}) {
+        super(`Deployment exceeds ${limitType} limit: ${actual} > ${limit}`, {
+            ...context,
+            limitType,
+            limit,
+            actual,
+        });
+        if (limitType === 'files') {
+            this.suggestions.push('Split deployment to stay under 10,000 file limit');
+        }
+        if (limitType === 'size') {
+            this.suggestions.push('Reduce deployment size (max 39MB compressed)');
+            this.suggestions.push('Remove unnecessary static resources or large files');
+        }
+        if (limitType === 'components') {
+            this.suggestions.push('Deploy in multiple waves');
+            this.suggestions.push('Use smart-deployment wave generation');
+        }
+    }
+}
+/**
+ * Error thrown when Salesforce API returns an error
+ */
+export class SalesforceApiError extends DeploymentError {
+    constructor(apiError, context = {}) {
+        super(`Salesforce API error: ${apiError}`, {
+            ...context,
+            apiError,
+        });
+        if (context.statusCode === 401) {
+            this.suggestions.push('Authentication failed - check your credentials');
+            this.suggestions.push('Run: sf org login web');
+        }
+        if (context.statusCode === 403) {
+            this.suggestions.push('Insufficient permissions - check user permissions');
+        }
+        if (context.statusCode === 429) {
+            this.suggestions.push('API rate limit exceeded - wait and retry');
+            this.suggestions.push('Reduce concurrent API calls');
+        }
+        if (context.statusCode && context.statusCode >= 500) {
+            this.suggestions.push('Salesforce server error - retry later');
+            this.suggestions.push('Check Salesforce status: https://status.salesforce.com');
+        }
+    }
+}
+//# sourceMappingURL=deployment-error.js.map

package/lib/errors/deployment-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployment-error.js","sourceRoot":"","sources":["../../src/errors/deployment-error.ts"],"names":[],"mappings":"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"}

package/lib/errors/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Custom Error Types for Smart Deployment Plugin
+ *
+ * All errors extend SmartDeploymentError and provide:
+ * - Error codes for programmatic handling
+ * - Contextual information about the failure
+ * - Actionable suggestions for resolution
+ * - JSON serialization for logging
+ *
+ * @example
+ * ```typescript
+ * import { ParsingError, DeploymentError } from './errors/index.js';
+ *
+ * try {
+ *   await parseXml(file);
+ * } catch (error) {
+ *   throw new ParsingError('Failed to parse XML', {
+ *     filePath: file,
+ *     originalError: error.message
+ *   });
+ * }
+ * ```
+ */
+import { SmartDeploymentError as BaseError } from './base-error.js';
+export { SmartDeploymentError } from './base-error.js';
+export { ParsingError, XmlParsingError, JsonParsingError, ProjectStructureError } from './parsing-error.js';
+export { DependencyError, CircularDependencyError, MissingDependencyError, DependencyComplexityError, } from './dependency-error.js';
+export { DeploymentError, DeploymentValidationError, TestFailureError, DeploymentTimeoutError, DeploymentLimitError, SalesforceApiError, } from './deployment-error.js';
+export { ValidationError, ConfigurationError, ApiVersionError, UnknownMetadataTypeError, ComponentCountError, MissingMetadataError, FileNotFoundError, PermissionError, } from './validation-error.js';
+/**
+ * Type guard to check if error is a SmartDeploymentError
+ */
+export declare function isSmartDeploymentError(error: unknown): error is BaseError;
+/**
+ * Extract error message safely from unknown error
+ */
+export declare function getErrorMessage(error: unknown): string;
+/**
+ * Extract error context safely
+ */
+export declare function getErrorContext(error: unknown): Record<string, unknown>;
+/**
+ * Get suggestions from error if available
+ */
+export declare function getErrorSuggestions(error: unknown): string[];

package/lib/errors/index.js

@@ -0,0 +1,71 @@
+/**
+ * Custom Error Types for Smart Deployment Plugin
+ *
+ * All errors extend SmartDeploymentError and provide:
+ * - Error codes for programmatic handling
+ * - Contextual information about the failure
+ * - Actionable suggestions for resolution
+ * - JSON serialization for logging
+ *
+ * @example
+ * ```typescript
+ * import { ParsingError, DeploymentError } from './errors/index.js';
+ *
+ * try {
+ *   await parseXml(file);
+ * } catch (error) {
+ *   throw new ParsingError('Failed to parse XML', {
+ *     filePath: file,
+ *     originalError: error.message
+ *   });
+ * }
+ * ```
+ */
+// Base error
+import { SmartDeploymentError as BaseError } from './base-error.js';
+export { SmartDeploymentError } from './base-error.js';
+// Parsing errors
+export { ParsingError, XmlParsingError, JsonParsingError, ProjectStructureError } from './parsing-error.js';
+// Dependency errors
+export { DependencyError, CircularDependencyError, MissingDependencyError, DependencyComplexityError, } from './dependency-error.js';
+// Deployment errors
+export { DeploymentError, DeploymentValidationError, TestFailureError, DeploymentTimeoutError, DeploymentLimitError, SalesforceApiError, } from './deployment-error.js';
+// Validation errors
+export { ValidationError, ConfigurationError, ApiVersionError, UnknownMetadataTypeError, ComponentCountError, MissingMetadataError, FileNotFoundError, PermissionError, } from './validation-error.js';
+/**
+ * Type guard to check if error is a SmartDeploymentError
+ */
+export function isSmartDeploymentError(error) {
+    return error instanceof BaseError;
+}
+/**
+ * Extract error message safely from unknown error
+ */
+export function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    return 'Unknown error occurred';
+}
+/**
+ * Extract error context safely
+ */
+export function getErrorContext(error) {
+    if (isSmartDeploymentError(error)) {
+        return error.context;
+    }
+    return {};
+}
+/**
+ * Get suggestions from error if available
+ */
+export function getErrorSuggestions(error) {
+    if (isSmartDeploymentError(error)) {
+        return error.suggestions;
+    }
+    return [];
+}
+//# sourceMappingURL=index.js.map

package/lib/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,aAAa;AACb,OAAO,EAAE,oBAAoB,IAAI,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEvD,iBAAiB;AACjB,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE5G,oBAAoB;AACpB,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B,oBAAoB;AACpB,OAAO,EACL,eAAe,EACf,yBAAyB,EACzB,gBAAgB,EAChB,sBAAsB,EACtB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,oBAAoB;AACpB,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,wBAAwB,EACxB,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAE/B;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,OAAO,KAAK,YAAY,SAAS,CAAC;AACpC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,wBAAwB,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,IAAI,sBAAsB,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC,OAAO,CAAC;IACvB,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,sBAAsB,CAAC,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC,WAAW,CAAC;IAC3B,CAAC;IAED,OAAO,EAAE,CAAC;AACZ,CAAC"}