@creact-labs/creact 0.1.8 → 0.2.0

package/dist/core/StateMachine.js

@@ -1,883 +0,0 @@
-"use strict";
-/**
-
- * Licensed under the Apache License, Version 2.0 (the "License");
-
- * you may not use this file except in compliance with the License.
-
- * You may obtain a copy of the License at
-
- *
-
- *     http://www.apache.org/licenses/LICENSE-2.0
-
- *
-
- * Unless required by applicable law or agreed to in writing, software
-
- * distributed under the License is distributed on an "AS IS" BASIS,
-
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-
- * See the License for the specific language governing permissions and
-
- * limitations under the License.
-
- *
-
- * Copyright 2025 Daniel Coutinho Ribeiro
-
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.StateMachine = void 0;
-const errors_1 = require("./errors");
-const Logger_1 = require("../utils/Logger");
-const logger = Logger_1.LoggerFactory.getLogger('state-machine');
-/**
- * StateMachine manages deployment lifecycle with crash recovery
- *
- * Responsibilities:
- * - Track deployment state transitions
- * - Save checkpoints after each resource deploys
- * - Enable crash recovery (resume or rollback)
- * - Provide atomic state persistence via BackendProvider
- * - Prevent concurrent deployments via locking (REQ-O02)
- * - Emit audit trail for compliance (REQ-O05)
- * - Retry transient backend failures (REQ-O03)
- *
- * Design principles:
- * - All state changes are atomic (saved to BackendProvider immediately)
- * - Checkpoints enable resume from any point
- * - Rollback applies reverse change set
- * - State machine is universal (works with all providers)
- * - Locking prevents race conditions
- * - Audit trail provides compliance and debugging
- *
- * REQ-O01: CloudDOM State Machine
- * REQ-O02: State Locking
- * REQ-O03: Retry Logic
- * REQ-O05: Audit Log
- * REQ-ARCH-01: Provider-Orchestration Separation
- *
- * @example
- * ```typescript
- * const stateMachine = new StateMachine(backendProvider);
- *
- * // Listen to events
- * stateMachine.on('checkpoint', (state) => {
- *   logger.info(`Checkpoint: ${state.checkpoint}`);
- * });
- *
- * // Start deployment (acquires lock)
- * await stateMachine.startDeployment('my-stack', changeSet, cloudDOM, 'user@example.com');
- *
- * // Update checkpoint after each resource
- * await stateMachine.updateCheckpoint('my-stack', 0);
- * await stateMachine.updateCheckpoint('my-stack', 1);
- *
- * // Complete deployment (releases lock)
- * await stateMachine.completeDeployment('my-stack');
- *
- * // Or handle failure (releases lock)
- * await stateMachine.failDeployment('my-stack', new DeploymentError('Provider timeout'));
- * ```
- */
-class StateMachine {
-    constructor(backendProvider, options = {}) {
-        this.backendProvider = backendProvider;
-        this.options = options;
-        this.listeners = {
-            started: [],
-            checkpoint: [],
-            completed: [],
-            failed: [],
-            rolled_back: [],
-        };
-        /**
-         * Map of active lock renewal timers by stack name
-         * Used to clean up timers when deployment completes
-         */
-        this.lockRenewalTimers = new Map();
-        this.options = {
-            maxRetries: 3,
-            enableAuditLog: true,
-            enableSnapshots: false,
-            lockTTL: 600,
-            ...options,
-        };
-    }
-    /**
-     * Subscribe to state machine events
-     *
-     * Enables observability and telemetry integration.
-     *
-     * @param event - Event type to listen for
-     * @param handler - Callback function receiving structured payload
-     */
-    on(event, handler) {
-        this.listeners[event].push(handler);
-    }
-    /**
-     * Unsubscribe from state machine events
-     *
-     * @param event - Event type to stop listening for
-     * @param handler - Callback function to remove
-     */
-    off(event, handler) {
-        const index = this.listeners[event].indexOf(handler);
-        if (index !== -1) {
-            this.listeners[event].splice(index, 1);
-        }
-    }
-    /**
-     * Emit event to all listeners with structured payload
-     *
-     * @param event - Event type
-     * @param state - Current deployment state
-     * @param metadata - Additional metadata (optional)
-     */
-    emit(event, state, metadata) {
-        const payload = {
-            event,
-            state,
-            metadata,
-        };
-        for (const handler of this.listeners[event]) {
-            try {
-                handler(payload);
-            }
-            catch (error) {
-                // Don't let listener errors break state machine
-                logger.error(`Error in StateMachine event handler for ${event}:`, error);
-            }
-        }
-    }
-    /**
-     * Start lock auto-renewal for a stack
-     *
-     * Renews the lock at 50% of the TTL interval to prevent expiration
-     * during long deployments. Only starts renewal if backend supports locking.
-     *
-     * @param stackName - Name of the stack
-     * @param holder - Lock holder identifier
-     * @param ttl - Lock TTL in seconds
-     */
-    startLockRenewal(stackName, holder, ttl) {
-        // Only start renewal if backend supports locking
-        if (!this.backendProvider.acquireLock) {
-            return;
-        }
-        // Clear any existing timer for this stack
-        this.stopLockRenewal(stackName);
-        // Renew at 50% of TTL (convert to milliseconds)
-        const renewalInterval = (ttl * 1000) / 2;
-        const timer = setInterval(async () => {
-            try {
-                // Renew the lock with the same TTL
-                await this.backendProvider.acquireLock(stackName, holder, ttl);
-                logger.debug(`Lock renewed for stack: ${stackName}`);
-            }
-            catch (error) {
-                logger.error(`Failed to renew lock for ${stackName}:`, error);
-                // Stop renewal on failure to prevent spam
-                this.stopLockRenewal(stackName);
-            }
-        }, renewalInterval);
-        this.lockRenewalTimers.set(stackName, timer);
-        logger.debug(`Lock auto-renewal started for stack: ${stackName} (interval: ${renewalInterval}ms)`);
-    }
-    /**
-     * Stop lock auto-renewal for a stack
-     *
-     * Cleans up the renewal timer to prevent memory leaks.
-     *
-     * @param stackName - Name of the stack
-     */
-    stopLockRenewal(stackName) {
-        const timer = this.lockRenewalTimers.get(stackName);
-        if (timer) {
-            clearInterval(timer);
-            this.lockRenewalTimers.delete(stackName);
-            logger.debug(`Lock auto-renewal stopped for stack: ${stackName}`);
-        }
-    }
-    /**
-     * Validate state transition
-     *
-     * Ensures state machine only transitions through valid states.
-     * Prevents accidental invalid state mutations.
-     *
-     * @param from - Current state
-     * @param to - Target state
-     * @throws DeploymentError if transition is invalid
-     */
-    validateTransition(from, to) {
-        const allowedTransitions = StateMachine.VALID_TRANSITIONS[from];
-        if (!allowedTransitions || !allowedTransitions.includes(to)) {
-            throw new errors_1.DeploymentError(`Invalid state transition: ${from} → ${to}`, {
-                message: `Invalid state transition: ${from} → ${to}`,
-                code: 'INVALID_STATE_TRANSITION',
-                details: {
-                    from,
-                    to,
-                    allowedTransitions,
-                },
-            });
-        }
-    }
-    /**
-     * Retry operation with exponential backoff
-     *
-     * Handles transient backend failures (network issues, timeouts, etc.)
-     *
-     * REQ-O03: Error handling and retry logic
-     *
-     * @param operation - Async operation to retry
-     * @param retries - Number of retries (default: from options)
-     * @returns Promise resolving to operation result
-     * @throws Error if all retries fail
-     */
-    async withRetry(operation, retries = this.options.maxRetries ?? 3) {
-        let lastError;
-        for (let i = 0; i < retries; i++) {
-            try {
-                return await operation();
-            }
-            catch (err) {
-                lastError = err;
-                // Don't retry on final attempt
-                if (i < retries - 1) {
-                    // Exponential backoff: 100ms, 200ms, 400ms, etc.
-                    const delay = Math.pow(2, i) * 100;
-                    await new Promise((resolve) => setTimeout(resolve, delay));
-                }
-            }
-        }
-        throw new errors_1.DeploymentError(`Backend operation failed after ${retries} attempts: ${lastError?.message || 'Unknown error'}`, {
-            message: `Backend operation failed after ${retries} attempts`,
-            code: 'BACKEND_OPERATION_FAILED',
-            details: { originalError: lastError, retries },
-        });
-    }
-    /**
-     * Log action to audit trail
-     *
-     * REQ-O05: Audit log for compliance
-     *
-     * @param stackName - Stack name
-     * @param action - Action performed
-     * @param state - Current deployment state
-     * @param error - Error if action failed
-     */
-    async logAction(stackName, action, state, error) {
-        if (!this.options.enableAuditLog) {
-            return;
-        }
-        if (!this.backendProvider.appendAuditLog) {
-            // Backend doesn't support audit logging yet
-            return;
-        }
-        const entry = {
-            timestamp: Date.now(),
-            user: state.user,
-            action,
-            stackName,
-            status: error ? 'failed' : 'completed',
-            error: error?.message,
-            changeSet: state.changeSet,
-            checkpoint: state.checkpoint,
-        };
-        try {
-            await this.backendProvider.appendAuditLog(stackName, entry);
-        }
-        catch (err) {
-            // Don't fail deployment if audit logging fails
-            logger.error(`Failed to append audit log for ${stackName}:`, err);
-        }
-    }
-    /**
-     * Save state snapshot for time-travel debugging
-     *
-     * Creates a deep copy to ensure immutability.
-     *
-     * REQ-O01: Immutable state snapshots
-     *
-     * @param stackName - Stack name
-     * @param state - Current deployment state
-     */
-    async saveSnapshot(stackName, state) {
-        if (!this.options.enableSnapshots) {
-            return;
-        }
-        if (!this.backendProvider.saveSnapshot) {
-            // Backend doesn't support snapshots yet
-            return;
-        }
-        try {
-            // Deep copy to ensure immutability
-            const snapshot = JSON.parse(JSON.stringify({
-                ...state,
-                timestamp: Date.now(),
-            }));
-            await this.backendProvider.saveSnapshot(stackName, snapshot);
-        }
-        catch (err) {
-            // Don't fail deployment if snapshot fails
-            logger.error(`Failed to save snapshot for ${stackName}:`, err);
-        }
-    }
-    /**
-     * Start a deployment transaction
-     *
-     * Transitions state from PENDING to APPLYING and saves to backend.
-     * Acquires lock to prevent concurrent deployments.
-     *
-     * REQ-O01.1: WHEN deployment starts THEN CloudDOM state SHALL transition to APPLYING
-     * REQ-O02: State locking to prevent concurrent deployments
-     *
-     * @param stackName - Name of the stack being deployed
-     * @param changeSet - Change set computed by Reconciler
-     * @param cloudDOM - CloudDOM tree being deployed
-     * @param user - User initiating the deployment
-     * @returns Promise that resolves when state is saved
-     * @throws DeploymentError if lock cannot be acquired or state save fails
-     */
-    async startDeployment(stackName, changeSet, cloudDOM, user) {
-        // Validate changeSet is not empty
-        if (!changeSet.deploymentOrder || changeSet.deploymentOrder.length === 0) {
-            throw new errors_1.DeploymentError(`Cannot start deployment: no resources to deploy for stack ${stackName}`, {
-                message: `Cannot start deployment: no resources to deploy for stack ${stackName}`,
-                code: 'EMPTY_CHANGESET',
-                details: { stackName, changeSet },
-            });
-        }
-        // Acquire lock to prevent concurrent deployments
-        // NOTE: Lock acquisition should NOT be retried - it should fail immediately
-        if (this.backendProvider.acquireLock) {
-            const lockTTL = this.options.lockTTL ?? 600;
-            try {
-                await this.backendProvider.acquireLock(stackName, user, lockTTL);
-                // Start auto-renewal to prevent lock expiration during long deployments
-                this.startLockRenewal(stackName, user, lockTTL);
-            }
-            catch (error) {
-                throw new errors_1.DeploymentError(`Failed to acquire lock for stack ${stackName}. ` +
-                    `Another deployment may be in progress.`, {
-                    message: `Failed to acquire lock for stack ${stackName}`,
-                    code: 'LOCK_ACQUISITION_FAILED',
-                    details: { stackName, user },
-                    cause: error instanceof Error ? error.message : String(error),
-                });
-            }
-        }
-        const state = {
-            status: 'APPLYING',
-            cloudDOM,
-            changeSet,
-            checkpoint: undefined,
-            timestamp: Date.now(),
-            user,
-            stackName,
-        };
-        try {
-            // Validate transition (PENDING → APPLYING)
-            // Note: We assume PENDING as initial state for new deployments
-            this.validateTransition('PENDING', 'APPLYING');
-            // Save state with retry
-            await this.withRetry(() => this.backendProvider.saveState(stackName, state));
-            // Log action to audit trail
-            await this.logAction(stackName, 'start', state);
-            // Emit event with metadata
-            this.emit('started', state, {
-                resourceCount: changeSet.deploymentOrder.length,
-                creates: changeSet.creates.length,
-                updates: changeSet.updates.length,
-                deletes: changeSet.deletes.length,
-            });
-        }
-        catch (error) {
-            // Stop lock renewal and release lock if state save fails
-            this.stopLockRenewal(stackName);
-            if (this.backendProvider.releaseLock) {
-                try {
-                    await this.backendProvider.releaseLock(stackName);
-                }
-                catch (releaseError) {
-                    logger.error(`Failed to release lock after error:`, releaseError);
-                }
-            }
-            throw error;
-        }
-    }
-    /**
-     * Update checkpoint after each resource deploys
-     *
-     * Saves progress to enable crash recovery. If deployment crashes,
-     * it can resume from the last checkpoint.
-     *
-     * REQ-O01.5: WHEN any provider executes THEN StateMachine SHALL checkpoint after each resource
-     *
-     * @param stackName - Name of the stack being deployed
-     * @param checkpoint - Index of last successfully deployed resource
-     * @returns Promise that resolves when checkpoint is saved
-     * @throws DeploymentError if state is invalid or save fails
-     */
-    async updateCheckpoint(stackName, checkpoint) {
-        const state = await this.withRetry(() => this.getState(stackName));
-        if (!state) {
-            throw new errors_1.DeploymentError(`No deployment state found for stack: ${stackName}`, {
-                message: `No deployment state found for stack: ${stackName}`,
-                code: 'STATE_NOT_FOUND',
-                details: { stackName, checkpoint },
-            });
-        }
-        if (state.status !== 'APPLYING') {
-            throw new errors_1.DeploymentError(`Cannot update checkpoint for stack in ${state.status} state. ` +
-                `Checkpoints can only be updated during APPLYING state.`, {
-                message: `Cannot update checkpoint for stack in ${state.status} state`,
-                code: 'INVALID_STATE_FOR_CHECKPOINT',
-                details: { stackName, currentStatus: state.status, checkpoint },
-            });
-        }
-        // Save snapshot before updating checkpoint (for time-travel debugging)
-        await this.saveSnapshot(stackName, state);
-        state.checkpoint = checkpoint;
-        state.timestamp = Date.now();
-        await this.withRetry(() => this.backendProvider.saveState(stackName, state));
-        // Log checkpoint to audit trail
-        await this.logAction(stackName, 'checkpoint', state);
-        // Emit event
-        this.emit('checkpoint', state);
-    }
-    /**
-     * Mark deployment as complete
-     *
-     * Transitions state from APPLYING to DEPLOYED and releases lock.
-     *
-     * REQ-O01.2: WHEN deployment succeeds THEN state SHALL transition to DEPLOYED
-     * REQ-O02: Release lock after deployment completes
-     *
-     * @param stackName - Name of the stack that was deployed
-     * @returns Promise that resolves when state is saved
-     * @throws DeploymentError if state is invalid or save fails
-     */
-    async completeDeployment(stackName) {
-        const state = await this.withRetry(() => this.getState(stackName));
-        if (!state) {
-            throw new errors_1.DeploymentError(`No deployment state found for stack: ${stackName}`, {
-                message: `No deployment state found for stack: ${stackName}`,
-                code: 'STATE_NOT_FOUND',
-                details: { stackName },
-            });
-        }
-        // Validate transition
-        this.validateTransition(state.status, 'DEPLOYED');
-        // Save snapshot before completing
-        await this.saveSnapshot(stackName, state);
-        state.status = 'DEPLOYED';
-        state.timestamp = Date.now();
-        // Clear checkpoint and changeSet after successful deployment
-        state.checkpoint = undefined;
-        state.changeSet = undefined;
-        await this.withRetry(() => this.backendProvider.saveState(stackName, state));
-        // Log action to audit trail
-        await this.logAction(stackName, 'complete', state);
-        // Stop lock renewal and release lock
-        this.stopLockRenewal(stackName);
-        if (this.backendProvider.releaseLock) {
-            try {
-                await this.backendProvider.releaseLock(stackName);
-            }
-            catch (error) {
-                logger.error(`Failed to release lock for ${stackName}:`, error);
-            }
-        }
-        // Emit event
-        this.emit('completed', state);
-    }
-    /**
-     * Mark deployment as failed
-     *
-     * Transitions state from APPLYING to FAILED, stores error details, and releases lock.
-     *
-     * @param stackName - Name of the stack that failed
-     * @param error - Error that caused the failure (should be DeploymentError or subclass)
-     * @returns Promise that resolves when state is saved
-     * @throws DeploymentError if state is invalid or save fails
-     */
-    async failDeployment(stackName, error) {
-        const state = await this.withRetry(() => this.getState(stackName));
-        if (!state) {
-            throw new errors_1.DeploymentError(`No deployment state found for stack: ${stackName}`, {
-                message: `No deployment state found for stack: ${stackName}`,
-                code: 'STATE_NOT_FOUND',
-                details: { stackName },
-                cause: error.message,
-            });
-        }
-        // Validate transition
-        this.validateTransition(state.status, 'FAILED');
-        // Save snapshot before failing
-        await this.saveSnapshot(stackName, state);
-        state.status = 'FAILED';
-        // Store structured error data
-        if (error instanceof errors_1.DeploymentError) {
-            state.error = error.data;
-        }
-        else {
-            state.error = {
-                message: error.message,
-                stack: error.stack,
-                code: error.code,
-            };
-        }
-        state.timestamp = Date.now();
-        await this.withRetry(() => this.backendProvider.saveState(stackName, state));
-        // Log action to audit trail
-        await this.logAction(stackName, 'fail', state, error);
-        // Stop lock renewal and release lock
-        this.stopLockRenewal(stackName);
-        if (this.backendProvider.releaseLock) {
-            try {
-                await this.backendProvider.releaseLock(stackName);
-            }
-            catch (releaseError) {
-                logger.error(`Failed to release lock for ${stackName}:`, releaseError);
-            }
-        }
-        // Emit event with error metadata
-        this.emit('failed', state, {
-            errorCode: state.error?.code,
-            errorMessage: state.error?.message,
-        });
-    }
-    /**
-     * Resume interrupted deployment from checkpoint
-     *
-     * Returns the change set and checkpoint so deployment can continue
-     * from where it left off.
-     *
-     * REQ-O01.4: WHEN CReact restarts THEN it SHALL detect incomplete transactions
-     *            and offer resume/rollback
-     *
-     * @param stackName - Name of the stack to resume
-     * @returns Promise resolving to change set, checkpoint index, and cloudDOM
-     * @throws DeploymentError if no incomplete deployment found
-     */
-    async resumeDeployment(stackName) {
-        // Check lock status before resuming
-        if (this.backendProvider.checkLock) {
-            const lockInfo = await this.backendProvider.checkLock(stackName);
-            if (lockInfo) {
-                const lockAge = Date.now() - lockInfo.acquiredAt;
-                const lockTTL = lockInfo.ttl * 1000; // Convert to milliseconds
-                if (lockAge < lockTTL) {
-                    throw new errors_1.DeploymentError(`Cannot resume: lock held by ${lockInfo.holder}`, {
-                        message: `Cannot resume: lock held by ${lockInfo.holder}`,
-                        code: 'LOCK_HELD',
-                        details: {
-                            stackName,
-                            lockHolder: lockInfo.holder,
-                            lockAcquiredAt: new Date(lockInfo.acquiredAt).toISOString(),
-                            lockExpiresAt: new Date(lockInfo.acquiredAt + lockTTL).toISOString(),
-                        },
-                    });
-                }
-            }
-        }
-        const state = await this.withRetry(() => this.getState(stackName));
-        if (!state) {
-            throw new errors_1.DeploymentError(`No deployment state found for stack: ${stackName}`, {
-                message: `No deployment state found for stack: ${stackName}`,
-                code: 'STATE_NOT_FOUND',
-                details: { stackName },
-            });
-        }
-        if (state.status !== 'APPLYING') {
-            throw new errors_1.DeploymentError(`Cannot resume deployment for stack in ${state.status} state. ` +
-                `Only APPLYING deployments can be resumed.`, {
-                message: `Cannot resume deployment for stack in ${state.status} state`,
-                code: 'INVALID_STATE_FOR_RESUME',
-                details: { stackName, currentStatus: state.status },
-            });
-        }
-        if (!state.changeSet ||
-            !state.changeSet.deploymentOrder ||
-            state.changeSet.deploymentOrder.length === 0) {
-            throw new errors_1.DeploymentError(`Cannot resume deployment: no change set found in state for stack ${stackName}`, {
-                message: `Cannot resume deployment: no change set found in state for stack ${stackName}`,
-                code: 'MISSING_CHANGESET',
-                details: { stackName },
-            });
-        }
-        return {
-            changeSet: state.changeSet,
-            checkpoint: state.checkpoint ?? -1,
-            cloudDOM: state.cloudDOM,
-        };
-    }
-    /**
-     * Rollback to previous state
-     *
-     * Applies reverse change set (deletes → creates, creates → deletes)
-     * and transitions state to ROLLED_BACK. Releases lock.
-     *
-     * Note: This method only updates the state machine status. The actual
-     * rollback logic (applying reverse change set) is handled by the caller
-     * (typically CReact or CLI).
-     *
-     * REQ-O01: Crash recovery with rollback
-     * REQ-O02: Release lock after rollback
-     *
-     * @param stackName - Name of the stack to rollback
-     * @returns Promise that resolves when state is saved
-     * @throws DeploymentError if state is invalid or save fails
-     */
-    async rollback(stackName) {
-        const state = await this.withRetry(() => this.getState(stackName));
-        if (!state) {
-            throw new errors_1.DeploymentError(`No deployment state found for stack: ${stackName}`, {
-                message: `No deployment state found for stack: ${stackName}`,
-                code: 'STATE_NOT_FOUND',
-                details: { stackName },
-            });
-        }
-        // Validate transition
-        this.validateTransition(state.status, 'ROLLED_BACK');
-        // Save snapshot before rollback
-        await this.saveSnapshot(stackName, state);
-        state.status = 'ROLLED_BACK';
-        state.timestamp = Date.now();
-        // Clear checkpoint and changeSet after rollback
-        state.checkpoint = undefined;
-        state.changeSet = undefined;
-        await this.withRetry(() => this.backendProvider.saveState(stackName, state));
-        // Log action to audit trail
-        await this.logAction(stackName, 'rollback', state);
-        // Stop lock renewal and release lock
-        this.stopLockRenewal(stackName);
-        if (this.backendProvider.releaseLock) {
-            try {
-                await this.backendProvider.releaseLock(stackName);
-            }
-            catch (error) {
-                logger.error(`Failed to release lock for ${stackName}:`, error);
-            }
-        }
-        // Emit event
-        this.emit('rolled_back', state);
-    }
-    /**
-     * Get current deployment state for a stack
-     *
-     * @param stackName - Name of the stack
-     * @returns Promise resolving to deployment state, or undefined if not found
-     */
-    async getState(stackName) {
-        return await this.backendProvider.getState(stackName);
-    }
-    /**
-     * Update the CloudDOM in the deployment state (for post-deployment effects)
-     *
-     * @param stackName - Stack name
-     * @param cloudDOM - Updated CloudDOM with new outputs
-     * @throws DeploymentError if state update fails
-     */
-    async updateCloudDOM(stackName, cloudDOM) {
-        const state = await this.withRetry(() => this.getState(stackName));
-        if (!state) {
-            throw new errors_1.DeploymentError(`No deployment state found for stack: ${stackName}`, {
-                message: `No deployment state found for stack: ${stackName}`,
-                code: 'STATE_NOT_FOUND',
-                details: { stackName },
-            });
-        }
-        // Update the CloudDOM in the state
-        state.cloudDOM = cloudDOM;
-        state.timestamp = Date.now();
-        // Save the updated state
-        await this.withRetry(() => this.backendProvider.saveState(stackName, state));
-        // Log action to audit trail
-        await this.logAction(stackName, 'checkpoint', state);
-    }
-    /**
-     * Check if a stack has an incomplete deployment
-     *
-     * Used on startup to detect crashed deployments that need recovery.
-     *
-     * REQ-O01.3: WHEN CReact process crashes mid-deploy THEN state SHALL remain in APPLYING
-     * REQ-O01.4: WHEN CReact restarts THEN it SHALL detect incomplete transactions
-     *
-     * @param stackName - Name of the stack to check
-     * @returns Promise resolving to true if deployment is incomplete
-     */
-    async hasIncompleteDeployment(stackName) {
-        const state = await this.getState(stackName);
-        return state?.status === 'APPLYING';
-    }
-    /**
-     * Get checkpoint info for display
-     *
-     * Returns human-readable checkpoint information for CLI/UI.
-     * Includes resource ID for better UX.
-     *
-     * @param stackName - Name of the stack
-     * @returns Promise resolving to checkpoint info, or undefined if not found
-     */
-    async getCheckpointInfo(stackName) {
-        const state = await this.getState(stackName);
-        if (!state || !state.changeSet) {
-            return undefined;
-        }
-        const checkpoint = state.checkpoint ?? -1;
-        const totalResources = state.changeSet.deploymentOrder.length;
-        const percentComplete = totalResources > 0 ? Math.round(((checkpoint + 1) / totalResources) * 100) : 0;
-        // Get resource ID at checkpoint for better CLI UX
-        const resourceId = checkpoint >= 0 && checkpoint < state.changeSet.deploymentOrder.length
-            ? state.changeSet.deploymentOrder[checkpoint]
-            : undefined;
-        return {
-            checkpoint,
-            resourceId,
-            totalResources,
-            percentComplete,
-        };
-    }
-    /**
-     * Auto-recover from incomplete deployment
-     *
-     * Convenience method for CLI/orchestrator to automatically resume or rollback
-     * based on configuration.
-     *
-     * @param stackName - Name of the stack to recover
-     * @param strategy - Recovery strategy ('resume' or 'rollback')
-     * @returns Promise resolving to recovery info, or undefined if no recovery needed
-     */
-    async autoRecover(stackName, strategy) {
-        if (!(await this.hasIncompleteDeployment(stackName))) {
-            return { action: 'none' };
-        }
-        if (strategy === 'resume') {
-            const { changeSet, checkpoint, cloudDOM } = await this.resumeDeployment(stackName);
-            return {
-                action: 'resumed',
-                checkpoint,
-                changeSet,
-                cloudDOM,
-            };
-        }
-        else {
-            await this.rollback(stackName);
-            return { action: 'rolled_back' };
-        }
-    }
-    /**
-     * Detect and fix drift in deployed resources
-     *
-     * Checks if resources in the backend state still match reality.
-     * If drift is detected, refreshes the state to reflect actual cloud state.
-     *
-     * This is called automatically during state load to ensure state accuracy.
-     *
-     * @param stackName - Stack name to check for drift
-     * @param cloudProvider - Cloud provider with drift detection capabilities
-     * @returns Promise resolving to drift detection results
-     */
-    async detectAndFixDrift(stackName, cloudProvider) {
-        const state = await this.getState(stackName);
-        if (!state?.cloudDOM) {
-            return { driftDetected: false, driftResults: [], resourcesFixed: 0 };
-        }
-        logger.debug(`Detecting drift for stack: ${stackName}`);
-        const driftResults = [];
-        let resourcesFixed = 0;
-        for (const node of state.cloudDOM) {
-            // Skip nodes without outputs (not yet deployed)
-            if (!node.outputs) {
-                continue;
-            }
-            // Detect drift (required method)
-            const result = await cloudProvider.detectDrift(node);
-            driftResults.push(result);
-            if (result.hasDrifted) {
-                logger.info(`Drift detected: ${node.id} - ${result.driftDescription || 'State mismatch'}`);
-                // Refresh state to fix drift (required method)
-                logger.debug(`Refreshing state for: ${node.id}`);
-                await cloudProvider.refreshState(node);
-                resourcesFixed++;
-            }
-        }
-        // If any drift was detected, clear outputs for drifted resources and their children
-        // With the "one useInstance per component" constraint, dependencies = nesting
-        // So clearing a drifted node + its children ensures complete redeployment
-        if (resourcesFixed > 0) {
-            const driftedNodeIds = new Set(driftResults.filter(r => r.hasDrifted).map(r => r.nodeId));
-            logger.info(`Clearing outputs for ${driftedNodeIds.size} drifted resources and their children`);
-            // Clear outputs for drifted nodes and all their descendants
-            const clearDriftedOutputs = (nodes) => {
-                for (const node of nodes) {
-                    const isDrifted = driftedNodeIds.has(node.id);
-                    if (isDrifted && node.outputs) {
-                        logger.debug(`Clearing outputs for drifted resource: ${node.id}`);
-                        node.outputs = undefined;
-                    }
-                    // If this node is drifted, clear all its children too
-                    if (node.children) {
-                        if (isDrifted) {
-                            // Clear all children of drifted nodes
-                            const clearAllChildren = (childNodes) => {
-                                for (const child of childNodes) {
-                                    if (child.outputs) {
-                                        logger.debug(`Clearing outputs for child of drifted resource: ${child.id}`);
-                                        child.outputs = undefined;
-                                    }
-                                    if (child.children) {
-                                        clearAllChildren(child.children);
-                                    }
-                                }
-                            };
-                            clearAllChildren(node.children);
-                        }
-                        else {
-                            // Continue searching for drifted nodes in children
-                            clearDriftedOutputs(node.children);
-                        }
-                    }
-                }
-            };
-            clearDriftedOutputs(state.cloudDOM);
-        }
-        // If drift was detected and state was refreshed, save updated state
-        const driftDetected = driftResults.some(r => r.hasDrifted);
-        if (driftDetected && resourcesFixed > 0) {
-            logger.info(`Saving refreshed state after fixing ${resourcesFixed} drifted resources`);
-            await this.withRetry(() => this.backendProvider.saveState(stackName, {
-                ...state,
-                cloudDOM: state.cloudDOM,
-                timestamp: Date.now(),
-            }));
-            // Log drift detection to audit trail
-            await this.logAction(stackName, 'checkpoint', state);
-        }
-        if (driftDetected) {
-            logger.info(`Drift detection complete: ${driftResults.filter(r => r.hasDrifted).length} resources drifted, ${resourcesFixed} fixed`);
-        }
-        else {
-            logger.debug('No drift detected');
-        }
-        return { driftDetected, driftResults, resourcesFixed };
-    }
-}
-exports.StateMachine = StateMachine;
-/**
- * Valid state transitions
- *
- * Defines allowed transitions for state machine validation.
- */
-StateMachine.VALID_TRANSITIONS = {
-    PENDING: ['APPLYING'],
-    APPLYING: ['DEPLOYED', 'FAILED', 'ROLLED_BACK'],
-    FAILED: ['ROLLED_BACK'],
-    DEPLOYED: [],
-    ROLLED_BACK: [],
-};