@eldrforge/tree-execution 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Calen Varek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,130 @@
+# @eldrforge/tree-execution
+
+Parallel execution framework and tree orchestration for monorepo workflows.
+
+## Features
+
+- 🚀 **Parallel Execution** - Run tasks concurrently with dependency awareness
+- 🔄 **Smart Scheduling** - Priority-based task scheduling
+- 💾 **Checkpoint/Resume** - Save and restore execution state
+- 🛡️ **Error Recovery** - Sophisticated error handling and rollback
+- 📊 **Progress Tracking** - Real-time execution progress
+- 🎯 **Resource Management** - CPU and memory-aware execution
+- ⚡ **Retry Logic** - Exponential backoff for transient failures
+- 🎭 **Dependency Injection** - Flexible command integration
+- 🧪 **Fully Tested** - 140+ tests with excellent coverage
+
+## Installation
+
+```bash
+npm install @eldrforge/tree-execution
+```
+
+## Usage
+
+### Quick Start - TreeExecutor (Recommended)
+
+```typescript
+import { createTreeExecutor } from '@eldrforge/tree-execution';
+
+// Create executor with custom commands
+const executor = createTreeExecutor({
+    commands: {
+        commit: myCommitCommand,
+        publish: myPublishCommand
+    }
+});
+
+// Execute tree command
+const result = await executor.execute(config);
+```
+
+### Advanced - DynamicTaskPool
+
+```typescript
+import { DynamicTaskPool } from '@eldrforge/tree-execution';
+import { buildDependencyGraph } from '@eldrforge/tree-core';
+
+// Build dependency graph
+const graph = await buildDependencyGraph(packagePaths);
+
+// Create execution pool
+const pool = new DynamicTaskPool({
+  graph,
+  maxConcurrency: 4,
+  command: 'npm test',
+  config: runConfig
+});
+
+// Execute with parallel coordination
+const result = await pool.execute();
+
+console.log(`Completed: ${result.completed.length}`);
+console.log(`Failed: ${result.failed.length}`);
+```
+
+### Custom Logger
+
+```typescript
+import { setLogger } from '@eldrforge/tree-execution';
+
+setLogger({
+    info: (...args) => myLogger.info(...args),
+    error: (...args) => myLogger.error(...args),
+    warn: (...args) => myLogger.warn(...args),
+    verbose: (...args) => myLogger.verbose(...args),
+    debug: (...args) => myLogger.debug(...args),
+    silly: (...args) => myLogger.silly(...args)
+});
+```
+
+## Components
+
+### TreeExecutor (New!)
+High-level class-based API with dependency injection. Encapsulates all state management and provides clean integration points.
+
+### DynamicTaskPool
+Orchestrates parallel execution with dependency awareness.
+
+### RecoveryManager
+Handles error recovery, rollback, and state validation.
+
+### Scheduler
+Decides which packages to execute next based on dependencies and resources.
+
+### ResourceMonitor
+Tracks available execution slots and resource usage.
+
+### CheckpointManager
+Saves and restores execution state for resume capability.
+
+### CommandValidator
+Validates commands for parallel execution safety.
+
+### DependencyChecker
+Verifies package dependencies and readiness.
+
+## Testing
+
+This package includes 140+ comprehensive tests:
+
+```bash
+npm test           # Run tests
+npm run test:coverage  # Run with coverage
+```
+
+**Test Coverage**:
+- TreeExecutor: 94.82%
+- Utilities: 80%+
+- Execution framework: 60%+
+
+## Dependencies
+
+- `@eldrforge/tree-core` - Dependency graph algorithms
+- `@eldrforge/git-tools` - Git operations
+- `@eldrforge/shared` - Shared utilities
+
+## License
+
+MIT © Calen Varek
+

package/dist/TreeExecutor.d.ts

@@ -0,0 +1,113 @@
+/**
+ * TreeExecutor - Class-based tree command orchestration
+ *
+ * Refactored from tree.ts to use instance state instead of global state
+ * and dependency injection for commands.
+ */
+import type { TreeExecutionConfig } from './types/config.js';
+/**
+ * Published version tracking
+ */
+export interface PublishedVersion {
+    packageName: string;
+    version: string;
+    publishTime: Date;
+}
+/**
+ * Tree execution context for persistence
+ */
+export interface TreeExecutionContext {
+    command: string;
+    originalConfig: TreeExecutionConfig;
+    publishedVersions: PublishedVersion[];
+    completedPackages: string[];
+    buildOrder: string[];
+    startTime: Date;
+    lastUpdateTime: Date;
+}
+/**
+ * Command executor interface for dependency injection
+ */
+export interface CommandExecutor {
+    execute(config: TreeExecutionConfig, mode?: string): Promise<any>;
+}
+/**
+ * Command registry for built-in commands
+ */
+export interface CommandRegistry {
+    updates?: CommandExecutor;
+    commit?: CommandExecutor;
+    link?: CommandExecutor;
+    unlink?: CommandExecutor;
+}
+/**
+ * TreeExecutor options
+ */
+export interface TreeExecutorOptions {
+    /**
+     * Command registry for dependency injection
+     */
+    commands?: CommandRegistry;
+    /**
+     * Custom logger (optional)
+     */
+    logger?: any;
+}
+/**
+ * TreeExecutor - Orchestrates tree command execution
+ *
+ * This class encapsulates all state that was previously global,
+ * making it testable and allowing multiple concurrent executions.
+ */
+export declare class TreeExecutor {
+    private publishedVersions;
+    private executionContext;
+    private stateMutex;
+    private commands;
+    private logger;
+    constructor(options?: TreeExecutorOptions);
+    /**
+     * Get published versions (thread-safe)
+     */
+    getPublishedVersions(): Promise<PublishedVersion[]>;
+    /**
+     * Add published version (thread-safe)
+     */
+    addPublishedVersion(version: PublishedVersion): Promise<void>;
+    /**
+     * Get execution context (thread-safe)
+     * Returns a deep copy to prevent external modifications
+     */
+    getExecutionContext(): Promise<TreeExecutionContext | null>;
+    /**
+     * Set execution context (thread-safe)
+     */
+    setExecutionContext(context: TreeExecutionContext | null): Promise<void>;
+    /**
+     * Reset state (for testing)
+     */
+    reset(): Promise<void>;
+    /**
+     * Execute tree command
+     *
+     * This will be the main entry point, delegating to the execute function
+     * from tree.ts but with instance state instead of global state.
+     *
+     * @param config - Tree execution configuration
+     * @returns Result message
+     */
+    execute(config: TreeExecutionConfig): Promise<string>;
+    /**
+     * Get command executor
+     */
+    getCommand(name: keyof CommandRegistry): CommandExecutor | undefined;
+    /**
+     * Set command executor (for testing/injection)
+     */
+    setCommand(name: keyof CommandRegistry, executor: CommandExecutor): void;
+}
+/**
+ * Create a default TreeExecutor instance
+ */
+export declare function createTreeExecutor(options?: TreeExecutorOptions): TreeExecutor;
+//# sourceMappingURL=TreeExecutor.d.ts.map

package/dist/TreeExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreeExecutor.d.ts","sourceRoot":"","sources":["../src/TreeExecutor.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,IAAI,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,mBAAmB,CAAC;IACpC,iBAAiB,EAAE,gBAAgB,EAAE,CAAC;IACtC,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,IAAI,CAAC;IAChB,cAAc,EAAE,IAAI,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,OAAO,CAAC,MAAM,EAAE,mBAAmB,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACrE;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC5B,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC;;OAEG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAC;IAE3B;;OAEG;IACH,MAAM,CAAC,EAAE,GAAG,CAAC;CAChB;AAED;;;;;GAKG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,iBAAiB,CAA0B;IACnD,OAAO,CAAC,gBAAgB,CAAqC;IAC7D,OAAO,CAAC,UAAU,CAAc;IAGhC,OAAO,CAAC,QAAQ,CAAkB;IAClC,OAAO,CAAC,MAAM,CAAM;gBAER,OAAO,GAAE,mBAAwB;IAM7C;;OAEG;IACG,oBAAoB,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAMzD;;OAEG;IACG,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMnE;;;OAGG;IACG,mBAAmB,IAAI,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAcjE;;OAEG;IACG,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAM9E;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAO5B;;;;;;;;OAQG;IACG,OAAO,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAU3D;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,eAAe,GAAG,eAAe,GAAG,SAAS;IAIpE;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,eAAe,EAAE,QAAQ,EAAE,eAAe,GAAG,IAAI;CAG3E;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,YAAY,CAE9E"}

package/dist/TreeExecutor.js

@@ -0,0 +1,113 @@
+/**
+ * TreeExecutor - Class-based tree command orchestration
+ *
+ * Refactored from tree.ts to use instance state instead of global state
+ * and dependency injection for commands.
+ */
+import { SimpleMutex } from './util/mutex.js';
+/**
+ * TreeExecutor - Orchestrates tree command execution
+ *
+ * This class encapsulates all state that was previously global,
+ * making it testable and allowing multiple concurrent executions.
+ */
+export class TreeExecutor {
+    // Instance state (previously global)
+    publishedVersions = [];
+    executionContext = null;
+    stateMutex;
+    // Dependency injection
+    commands;
+    logger;
+    constructor(options = {}) {
+        this.commands = options.commands || {};
+        this.logger = options.logger;
+        this.stateMutex = new SimpleMutex();
+    }
+    /**
+     * Get published versions (thread-safe)
+     */
+    async getPublishedVersions() {
+        return await this.stateMutex.runExclusive(async () => {
+            return [...this.publishedVersions];
+        });
+    }
+    /**
+     * Add published version (thread-safe)
+     */
+    async addPublishedVersion(version) {
+        await this.stateMutex.runExclusive(async () => {
+            this.publishedVersions.push(version);
+        });
+    }
+    /**
+     * Get execution context (thread-safe)
+     * Returns a deep copy to prevent external modifications
+     */
+    async getExecutionContext() {
+        return await this.stateMutex.runExclusive(async () => {
+            if (!this.executionContext)
+                return null;
+            // Return deep copy to prevent external modification
+            return {
+                ...this.executionContext,
+                publishedVersions: [...this.executionContext.publishedVersions],
+                completedPackages: [...this.executionContext.completedPackages],
+                buildOrder: [...this.executionContext.buildOrder]
+            };
+        });
+    }
+    /**
+     * Set execution context (thread-safe)
+     */
+    async setExecutionContext(context) {
+        await this.stateMutex.runExclusive(async () => {
+            this.executionContext = context;
+        });
+    }
+    /**
+     * Reset state (for testing)
+     */
+    async reset() {
+        await this.stateMutex.runExclusive(async () => {
+            this.publishedVersions = [];
+            this.executionContext = null;
+        });
+    }
+    /**
+     * Execute tree command
+     *
+     * This will be the main entry point, delegating to the execute function
+     * from tree.ts but with instance state instead of global state.
+     *
+     * @param config - Tree execution configuration
+     * @returns Result message
+     */
+    async execute(config) {
+        // Import the execute function from tree.ts
+        // We'll need to refactor tree.ts to accept TreeExecutor instance
+        const { execute } = await import('./tree.js');
+        // For now, this is a placeholder
+        // We'll refactor tree.ts to accept TreeExecutor in the next step
+        return await execute(config);
+    }
+    /**
+     * Get command executor
+     */
+    getCommand(name) {
+        return this.commands[name];
+    }
+    /**
+     * Set command executor (for testing/injection)
+     */
+    setCommand(name, executor) {
+        this.commands[name] = executor;
+    }
+}
+/**
+ * Create a default TreeExecutor instance
+ */
+export function createTreeExecutor(options) {
+    return new TreeExecutor(options);
+}
+//# sourceMappingURL=TreeExecutor.js.map

package/dist/TreeExecutor.js.map

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

package/dist/checkpoint/CheckpointManager.d.ts

@@ -0,0 +1,18 @@
+import type { ParallelExecutionCheckpoint } from '../types/index.js';
+export declare class CheckpointManager {
+    private checkpointPath;
+    private lockPath;
+    private tempPath;
+    private logger;
+    private storage;
+    constructor(outputDirectory?: string);
+    save(checkpoint: ParallelExecutionCheckpoint): Promise<void>;
+    load(): Promise<ParallelExecutionCheckpoint | null>;
+    backup(): Promise<void>;
+    cleanup(): Promise<void>;
+    private acquireLock;
+    private validateCheckpoint;
+    private isCompatibleVersion;
+    private loadBackup;
+}
+//# sourceMappingURL=CheckpointManager.d.ts.map

package/dist/checkpoint/CheckpointManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CheckpointManager.d.ts","sourceRoot":"","sources":["../../src/checkpoint/CheckpointManager.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mBAAmB,CAAC;AASrE,qBAAa,iBAAiB;IAC1B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,OAAO,CAAmB;gBAEtB,eAAe,GAAE,MAAsB;IAM7C,IAAI,CAAC,UAAU,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;IAwB5D,IAAI,IAAI,OAAO,CAAC,2BAA2B,GAAG,IAAI,CAAC;IAoCnD,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IASvB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAahB,WAAW;IAqCzB,OAAO,CAAC,kBAAkB;IAwB1B,OAAO,CAAC,mBAAmB;YAOb,UAAU;CAa3B"}

package/dist/checkpoint/CheckpointManager.js

@@ -0,0 +1,156 @@
+import path from 'path';
+import fs from 'fs/promises';
+import { getLogger } from '../util/logger.js';
+import { createStorage } from '@eldrforge/shared';
+const CHECKPOINT_VERSION = '1.0.0';
+export class CheckpointManager {
+    checkpointPath;
+    lockPath;
+    tempPath;
+    logger = getLogger();
+    storage = createStorage();
+    constructor(outputDirectory = process.cwd()) {
+        this.checkpointPath = path.join(outputDirectory, '.kodrdriv-parallel-context.json');
+        this.lockPath = `${this.checkpointPath}.lock`;
+        this.tempPath = `${this.checkpointPath}.tmp`;
+    }
+    async save(checkpoint) {
+        const lock = await this.acquireLock();
+        try {
+            // Set version and timestamp
+            checkpoint.version = CHECKPOINT_VERSION;
+            checkpoint.lastUpdated = new Date().toISOString();
+            // Validate before saving
+            this.validateCheckpoint(checkpoint);
+            // Write to temp file
+            const serialized = JSON.stringify(checkpoint, null, 2);
+            await fs.writeFile(this.tempPath, serialized, 'utf-8');
+            // Atomic rename
+            await fs.rename(this.tempPath, this.checkpointPath);
+            this.logger.debug(`Checkpoint saved: ${this.checkpointPath}`);
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    async load() {
+        if (!await this.storage.exists(this.checkpointPath)) {
+            return null;
+        }
+        const lock = await this.acquireLock();
+        try {
+            const content = await fs.readFile(this.checkpointPath, 'utf-8');
+            const checkpoint = JSON.parse(content);
+            // Validate
+            this.validateCheckpoint(checkpoint);
+            // Check version
+            if (!this.isCompatibleVersion(checkpoint.version)) {
+                throw new Error(`Incompatible checkpoint version: ${checkpoint.version}`);
+            }
+            return checkpoint;
+        }
+        catch (error) {
+            this.logger.error(`CHECKPOINT_LOAD_FAILED: Failed to load checkpoint file | Error: ${error.message} | Impact: Cannot resume execution`);
+            // Try backup
+            const backup = await this.loadBackup();
+            if (backup) {
+                this.logger.info('CHECKPOINT_RECOVERED_BACKUP: Recovered from backup checkpoint | Source: backup | Status: loaded');
+                return backup;
+            }
+            return null;
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    async backup() {
+        if (!await this.storage.exists(this.checkpointPath)) {
+            return;
+        }
+        const backupPath = `${this.checkpointPath}.backup`;
+        await fs.copyFile(this.checkpointPath, backupPath);
+    }
+    async cleanup() {
+        const files = [
+            this.checkpointPath,
+            this.lockPath,
+            this.tempPath,
+            `${this.checkpointPath}.backup`
+        ];
+        await Promise.all(files.map(file => fs.unlink(file).catch(() => { })));
+    }
+    async acquireLock() {
+        const maxWaitMs = 30000;
+        const startTime = Date.now();
+        while (true) {
+            try {
+                const fileHandle = await fs.open(this.lockPath, 'wx');
+                try {
+                    const pid = process.pid;
+                    const timestamp = new Date().toISOString();
+                    await fileHandle.writeFile(`${pid}\n${timestamp}`);
+                }
+                finally {
+                    await fileHandle.close();
+                }
+                return {
+                    release: async () => {
+                        await fs.unlink(this.lockPath).catch(() => { });
+                    }
+                };
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST') {
+                    throw error;
+                }
+                const elapsed = Date.now() - startTime;
+                if (elapsed > maxWaitMs) {
+                    this.logger.warn('CHECKPOINT_LOCK_STALE: Breaking stale checkpoint lock | Reason: Lock expired | Action: Force break lock');
+                    await fs.unlink(this.lockPath).catch(() => { });
+                    continue;
+                }
+                await new Promise(resolve => setTimeout(resolve, 100));
+            }
+        }
+    }
+    validateCheckpoint(checkpoint) {
+        if (!checkpoint.executionId) {
+            throw new Error('Invalid checkpoint: missing executionId');
+        }
+        if (!checkpoint.state) {
+            throw new Error('Invalid checkpoint: missing state');
+        }
+        // Validate state consistency
+        const allPackages = new Set([
+            ...checkpoint.state.pending,
+            ...checkpoint.state.ready,
+            ...checkpoint.state.running.map(r => r.name),
+            ...checkpoint.state.completed,
+            ...checkpoint.state.failed.map(f => f.name),
+            ...checkpoint.state.skipped
+        ]);
+        if (allPackages.size !== checkpoint.buildOrder.length) {
+            this.logger.warn('CHECKPOINT_INCONSISTENCY: Checkpoint state inconsistency detected | Issue: State validation failed | Impact: May need manual recovery');
+        }
+    }
+    isCompatibleVersion(version) {
+        // Simple major version check
+        const [major] = version.split('.');
+        const [expectedMajor] = CHECKPOINT_VERSION.split('.');
+        return major === expectedMajor;
+    }
+    async loadBackup() {
+        const backupPath = `${this.checkpointPath}.backup`;
+        if (!await this.storage.exists(backupPath)) {
+            return null;
+        }
+        try {
+            const content = await fs.readFile(backupPath, 'utf-8');
+            return JSON.parse(content);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=CheckpointManager.js.map

package/dist/checkpoint/CheckpointManager.js.map

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

package/dist/checkpoint/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Checkpoint management for parallel execution
+ */
+export { CheckpointManager } from './CheckpointManager.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/checkpoint/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/checkpoint/index.js

@@ -0,0 +1,5 @@
+/**
+ * Checkpoint management for parallel execution
+ */
+export { CheckpointManager } from './CheckpointManager.js';
+//# sourceMappingURL=index.js.map

package/dist/checkpoint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/checkpoint/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/execution/CommandValidator.d.ts

@@ -0,0 +1,25 @@
+export interface ValidationResult {
+    valid: boolean;
+    issues: string[];
+    warnings: string[];
+    recommendations: string[];
+}
+/**
+ * CommandValidator checks if commands are safe for parallel execution
+ */
+export declare class CommandValidator {
+    private static logger;
+    /**
+     * Validate a command for parallel execution
+     */
+    static validateForParallel(command: string, builtInCommand?: string): ValidationResult;
+    /**
+     * Log validation results
+     */
+    static logValidation(result: ValidationResult): void;
+    /**
+     * Get recommended concurrency for a command type
+     */
+    static getRecommendedConcurrency(builtInCommand?: string, cpuCount?: number, command?: string): number;
+}
+//# sourceMappingURL=CommandValidator.d.ts.map

package/dist/execution/CommandValidator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CommandValidator.d.ts","sourceRoot":"","sources":["../../src/execution/CommandValidator.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAe;IAEpC;;OAEG;IACH,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,gBAAgB;IAoEtF;;OAEG;IACH,MAAM,CAAC,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAuBpD;;OAEG;IACH,MAAM,CAAC,yBAAyB,CAAC,cAAc,CAAC,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAU,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM;CAuC5G"}