@creact-labs/creact 0.1.8 → 0.2.1

package/dist/providers/IBackendProvider.d.ts

@@ -1,177 +0,0 @@
-/**
-
- * 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
-
- */
-/**
- * Lock information for state locking
- * REQ-O02: State locking to prevent concurrent deployments
- */
-export interface LockInfo {
-    /** Process/user holding the lock */
-    holder: string;
-    /** Timestamp when lock was acquired (milliseconds since epoch) */
-    acquiredAt: number;
-    /** Time-to-live in seconds */
-    ttl: number;
-}
-/**
- * IBackendProvider defines the interface for state storage backends.
- * Implementations manage persistent state for CloudDOM trees and outputs.
- *
- * This interface supports dependency injection, allowing different backends
- * (e.g., DummyBackendProvider for testing, S3BackendProvider for production)
- * to be swapped without changing core CReact logic.
- *
- * @template TState - Type of state object stored (defaults to any for flexibility)
- *
- * @example
- * ```typescript
- * class DummyBackendProvider implements IBackendProvider {
- *   private state = new Map<string, any>();
- *   private locks = new Map<string, LockInfo>();
- *
- *   async initialize() {
- *     console.log('Backend initialized');
- *   }
- *
- *   async getState(stackName: string): Promise<any | undefined> {
- *     return this.state.get(stackName);
- *   }
- *
- *   async saveState(stackName: string, state: any): Promise<void> {
- *     this.state.set(stackName, state);
- *   }
- *
- *   async acquireLock(stackName: string, holder: string, ttl: number): Promise<void> {
- *     // Implementation
- *   }
- *
- *   async releaseLock(stackName: string): Promise<void> {
- *     this.locks.delete(stackName);
- *   }
- *
- *   async checkLock(stackName: string): Promise<LockInfo | null> {
- *     return this.locks.get(stackName) || null;
- *   }
- * }
- * ```
- */
-export interface IBackendProvider<TState = any> {
-    /**
-     * Optional async initialization for remote connections (S3, DynamoDB, etc.)
-     * Called before any other provider methods.
-     *
-     * REQ-04.4: Support async initialization for providers that need to
-     * establish remote connections or load configuration.
-     *
-     * @returns Promise that resolves when initialization is complete
-     */
-    initialize?(): Promise<void>;
-    /**
-     * Retrieve state for a given stack.
-     * Returns undefined if no state exists for the stack.
-     *
-     * REQ-04: Core provider interface for state retrieval
-     * REQ-05: State management for deployment tracking and idempotency
-     * REQ-06: Universal output access across stacks
-     *
-     * @param stackName - Name of the stack to retrieve state for
-     * @returns Promise resolving to stack state, or undefined if not found
-     */
-    getState(stackName: string): Promise<TState | undefined>;
-    /**
-     * Save state for a given stack.
-     * State typically includes CloudDOM tree, outputs, and metadata.
-     *
-     * REQ-04: Core provider interface for state persistence
-     * REQ-05: State management for deployment tracking and idempotency
-     * REQ-08.5: Store migration map versions in backend state
-     *
-     * @param stackName - Name of the stack to save state for
-     * @param state - State object to persist (CloudDOM, outputs, metadata)
-     * @returns Promise that resolves when state is saved
-     */
-    saveState(stackName: string, state: TState): Promise<void>;
-    /**
-     * Acquire lock for a stack to prevent concurrent deployments.
-     * Locking mechanism is backend-specific:
-     * - File backend: flock on .creact/.lock
-     * - S3 backend: DynamoDB conditional writes
-     * - Redis backend: SETNX with TTL
-     *
-     * REQ-O02: State locking to prevent concurrent deployments
-     * REQ-O02.1: WHEN deployment starts THEN CReact SHALL call acquireLock
-     * REQ-O02.2: WHEN lock is held THEN acquireLock SHALL throw error with lock holder info
-     *
-     * @param stackName - Name of the stack to lock
-     * @param holder - Identifier of the lock holder (user/process)
-     * @param ttl - Time-to-live in seconds (lock auto-expires after this duration)
-     * @throws Error if lock is already held and not expired
-     */
-    acquireLock?(stackName: string, holder: string, ttl: number): Promise<void>;
-    /**
-     * Release lock for a stack.
-     *
-     * REQ-O02: State locking to prevent concurrent deployments
-     * REQ-O02.5: WHEN deployment completes THEN CReact SHALL call releaseLock
-     *
-     * @param stackName - Name of the stack to unlock
-     */
-    releaseLock?(stackName: string): Promise<void>;
-    /**
-     * Check lock status for a stack.
-     * Returns lock info if lock exists, null otherwise.
-     *
-     * REQ-O02: State locking to prevent concurrent deployments
-     * REQ-O02.3: WHEN process crashes THEN lock SHALL have TTL and auto-expire
-     *
-     * @param stackName - Name of the stack to check
-     * @returns Lock info if lock exists, null otherwise
-     */
-    checkLock?(stackName: string): Promise<LockInfo | null>;
-    /**
-     * Append audit log entry for compliance and debugging.
-     * Optional method for backends that support audit logging.
-     *
-     * REQ-O05: Audit log for compliance and debugging
-     *
-     * @param stackName - Name of the stack
-     * @param entry - Audit log entry to append
-     */
-    appendAuditLog?(stackName: string, entry: any): Promise<void>;
-    /**
-     * Save state snapshot for time-travel debugging.
-     * Optional method for backends that support snapshots.
-     *
-     * REQ-O01: State snapshots for time-travel debugging
-     *
-     * @param stackName - Name of the stack
-     * @param state - State snapshot to save
-     */
-    saveSnapshot?(stackName: string, state: TState): Promise<void>;
-}

package/dist/providers/IBackendProvider.js

@@ -1,31 +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 });

package/dist/providers/ICloudProvider.d.ts

@@ -1,230 +0,0 @@
-/**
-
- * 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
-
- */
-import { CloudDOMNode } from '../core/types';
-/**
- * OutputChangeEvent represents a provider output change notification
- * Emitted when a resource's outputs become available or change
- */
-export interface OutputChangeEvent {
-    /** CloudDOM node ID that changed */
-    nodeId: string;
-    /** New output values */
-    outputs: Record<string, any>;
-    /** Timestamp of the change */
-    timestamp: number;
-}
-/**
- * DriftDetectionResult represents the result of checking if a resource has drifted
- */
-export interface DriftDetectionResult {
-    /** Resource ID that was checked */
-    nodeId: string;
-    /** Whether the resource has drifted from expected state */
-    hasDrifted: boolean;
-    /** Expected state from CloudDOM */
-    expectedState?: Record<string, any>;
-    /** Actual state from cloud provider */
-    actualState?: Record<string, any>;
-    /** Human-readable description of the drift */
-    driftDescription?: string;
-    /** Timestamp of the check */
-    timestamp: number;
-}
-/**
- * ICloudProvider defines the interface for cloud infrastructure providers.
- * Implementations materialize CloudDOM trees into actual cloud resources.
- *
- * This interface supports dependency injection, allowing different providers
- * (e.g., DummyCloudProvider for testing, CDKTFProvider for production) to be
- * swapped without changing core CReact logic.
- *
- * @example
- * ```typescript
- * class DummyCloudProvider implements ICloudProvider {
- *   async initialize() {
- *     console.log('Provider initialized');
- *   }
- *
- *   materialize(cloudDOM: CloudDOMNode[], scope: any): void {
- *     console.log('Materializing:', cloudDOM);
- *   }
- * }
- * ```
- */
-export interface ICloudProvider {
-    /**
-     * Optional async initialization for remote connections (AWS, Vault, etc.)
-     * Called before any other provider methods.
-     *
-     * REQ-04.4: Support async initialization for providers that need to
-     * establish remote connections or load configuration.
-     *
-     * @returns Promise that resolves when initialization is complete
-     */
-    initialize?(): Promise<void>;
-    /**
-     * Materialize CloudDOM tree into actual cloud resources.
-     * This is the core method that deploys infrastructure.
-     *
-     * REQ-04: Core provider interface for cloud resource creation
-     *
-     * @param cloudDOM - Array of CloudDOM nodes to materialize
-     * @param scope - Optional provider-specific scope object (e.g., CDKTF App)
-     */
-    materialize(cloudDOM: CloudDOMNode[], scope?: any): void;
-    /**
-     * Optional lifecycle hook called before deployment begins.
-     * Use for validation, logging, or pre-deployment checks.
-     *
-     * REQ-09.1: preDeploy lifecycle hook for auditing and validation
-     *
-     * @param cloudDOM - CloudDOM tree about to be deployed
-     * @returns Promise that resolves when pre-deployment tasks complete
-     * @throws Error if pre-deployment checks fail (halts deployment)
-     */
-    preDeploy?(cloudDOM: CloudDOMNode[]): Promise<void>;
-    /**
-     * Optional lifecycle hook called after successful deployment.
-     * Use for logging, metrics collection, or post-deployment actions.
-     *
-     * REQ-09.2: postDeploy lifecycle hook for observability
-     *
-     * @param cloudDOM - CloudDOM tree that was deployed
-     * @param outputs - Collected outputs from deployed resources
-     * @returns Promise that resolves when post-deployment tasks complete
-     */
-    postDeploy?(cloudDOM: CloudDOMNode[], outputs: Record<string, any>): Promise<void>;
-    /**
-     * Optional lifecycle hook called when deployment fails.
-     * Use for error logging, cleanup, or alerting.
-     *
-     * REQ-09.3: onError lifecycle hook for error handling
-     *
-     * @param error - Error that caused deployment to fail
-     * @param cloudDOM - CloudDOM tree that failed to deploy
-     * @returns Promise that resolves when error handling completes
-     */
-    onError?(error: Error, cloudDOM: CloudDOMNode[]): Promise<void>;
-    /**
-     * Subscribe to output change events (optional - for event-driven reactivity)
-     * Providers can emit events when resource outputs become available
-     *
-     * This enables real-time reactivity without polling:
-     * - Provider emits when outputs are ready
-     * - Orchestrator subscribes and triggers re-renders
-     * - useEffect callbacks can react to specific output changes
-     *
-     * @param event - Event type to subscribe to
-     * @param handler - Callback function to handle the event
-     */
-    on?(event: 'outputsChanged', handler: (change: OutputChangeEvent) => void): void;
-    /**
-     * Unsubscribe from output change events
-     *
-     * @param event - Event type to unsubscribe from
-     * @param handler - Callback function to remove
-     */
-    off?(event: 'outputsChanged', handler: (change: OutputChangeEvent) => void): void;
-    /**
-     * Emit output change event (used by provider implementations)
-     * Internal method for providers to notify subscribers
-     *
-     * @param event - Event type
-     * @param change - Output change details
-     */
-    emit?(event: 'outputsChanged', change: OutputChangeEvent): void;
-    /**
-     * Detect drift for a specific resource (REQUIRED)
-     *
-     * Compares the expected state (from CloudDOM) with the actual state
-     * (from the cloud provider) to detect if the resource has drifted.
-     *
-     * This is called by CReact automatically during:
-     * - Every state load (to detect stale state)
-     * - Plan command (to show drift before deployment)
-     * - Deploy command (to ensure state accuracy)
-     *
-     * Providers MUST implement this to ensure state accuracy.
-     *
-     * @param node - CloudDOM node representing expected state
-     * @returns Promise resolving to drift detection result
-     *
-     * @example
-     * ```typescript
-     * async detectDrift(node: CloudDOMNode): Promise<DriftDetectionResult> {
-     *   // For resources without outputs, no drift possible
-     *   if (!node.outputs) {
-     *     return { nodeId: node.id, hasDrifted: false, timestamp: Date.now() };
-     *   }
-     *
-     *   const actualState = await this.getActualResourceState(node.id);
-     *   const hasDrifted = !this.statesMatch(node.outputs, actualState);
-     *
-     *   return {
-     *     nodeId: node.id,
-     *     hasDrifted,
-     *     expectedState: node.outputs,
-     *     actualState,
-     *     driftDescription: hasDrifted ? 'Resource no longer exists' : undefined,
-     *     timestamp: Date.now(),
-     *   };
-     * }
-     * ```
-     */
-    detectDrift(node: CloudDOMNode): Promise<DriftDetectionResult>;
-    /**
-     * Refresh resource state from actual cloud provider (REQUIRED)
-     *
-     * Queries the actual state of a resource and updates the node's outputs
-     * to reflect reality. This is the mechanism for fixing drift.
-     *
-     * Called automatically by CReact when drift is detected.
-     *
-     * Providers MUST implement this to enable automatic drift recovery.
-     *
-     * @param node - CloudDOM node to refresh
-     * @returns Promise resolving when refresh is complete (node.outputs updated)
-     *
-     * @example
-     * ```typescript
-     * async refreshState(node: CloudDOMNode): Promise<void> {
-     *   const actualState = await this.getActualResourceState(node.id);
-     *   if (actualState) {
-     *     // Resource exists - update outputs to match reality
-     *     node.outputs = actualState;
-     *   } else {
-     *     // Resource doesn't exist - clear outputs to force redeployment
-     *     node.outputs = undefined;
-     *   }
-     * }
-     * ```
-     */
-    refreshState(node: CloudDOMNode): Promise<void>;
-}

package/dist/providers/ICloudProvider.js

@@ -1,31 +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 });

package/dist/providers/index.d.ts

@@ -1,31 +0,0 @@
-/**
-
- * 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
-
- */
-export { ICloudProvider } from './ICloudProvider';
-export { IBackendProvider } from './IBackendProvider';

package/dist/providers/index.js

@@ -1,31 +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 });

package/dist/test-event-callbacks.js

@@ -1 +0,0 @@
-"use strict";

package/dist/utils/Logger.d.ts

@@ -1,144 +0,0 @@
-/**
-
- * 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
-
- */
-/**
- * Logger - Internal debugging and diagnostics only
- *
- * IMPORTANT: This logger is for INTERNAL debugging only, not user-facing output.
- * - All output goes to stderr (not stdout)
- * - Controlled by --verbose flag or CREACT_DEBUG environment variable
- * - For user-facing messages, use OutputManager (src/utils/Output.ts)
- *
- * Usage:
- * - logger.debug() - Internal state tracking, algorithm steps
- * - logger.info() - Internal lifecycle events (not user messages)
- * - logger.warn() - Internal warnings
- * - logger.error() - Internal errors with stack traces
- */
-/**
- * Log levels in order of severity
- */
-export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-/**
- * Standard log scopes for CReact subsystems
- */
-export type LogScope = 'renderer' | 'reconciler' | 'validator' | 'clouddom' | 'state-machine' | 'provider' | 'hooks' | 'cli' | 'runtime' | 'parallel';
-/**
- * Logger configuration
- */
-export interface LoggerConfig {
-    /** Enabled scopes (or ['*'] for all) */
-    scopes: string[];
-    /** Minimum log level */
-    level: LogLevel;
-}
-/**
- * Scoped logger with level filtering
- */
-export declare class Logger {
-    private readonly scope;
-    private readonly config;
-    private readonly context;
-    private readonly enabled;
-    constructor(scope: LogScope, config: LoggerConfig, context?: Record<string, any>);
-    /**
-     * Log a debug message
-     */
-    debug(message: string, ...args: any[]): void;
-    /**
-     * Log an info message
-     */
-    info(message: string, ...args: any[]): void;
-    /**
-     * Log a warning message
-     */
-    warn(message: string, ...args: any[]): void;
-    /**
-     * Log an error message
-     */
-    error(message: string, ...args: any[]): void;
-    /**
-     * Create a child logger with additional context
-     */
-    child(additionalContext: Record<string, any>): Logger;
-    /**
-     * Internal log method with filtering
-     */
-    private log;
-}
-/**
- * Logger factory for creating scoped loggers
- */
-export declare class LoggerFactory {
-    private static config;
-    /**
-     * Configure the logger factory
-     */
-    static configure(config: Partial<LoggerConfig>): void;
-    /**
-     * Get a logger for a specific scope
-     */
-    static getLogger(scope: LogScope): Logger;
-    /**
-     * Parse configuration from environment variables
-     * Supports CREACT_LOG=scope1,scope2 or CREACT_LOG=*
-     * Supports CREACT_LOG_LEVEL=debug|info|warn|error
-     */
-    static configureFromEnv(): void;
-    /**
-     * Parse configuration from CLI flags
-     * Supports --log=scope1,scope2 or --log=*
-     * Supports --log-level=debug|info|warn|error
-     */
-    static configureFromCLI(args: {
-        log?: string;
-        logLevel?: string;
-    }): void;
-    /**
-     * Parse configuration from config file
-     */
-    static configureFromFile(fileConfig: {
-        log?: {
-            scopes?: string[];
-            level?: string;
-        };
-    }): void;
-    /**
-     * Get current configuration
-     */
-    static getConfig(): LoggerConfig;
-    /**
-     * Reset configuration to defaults
-     */
-    static reset(): void;
-    /**
-     * Check if a string is a valid log level
-     */
-    private static isValidLogLevel;
-}