@creact-labs/creact 0.1.0

package/dist/providers/IBackendProvider.d.ts

@@ -0,0 +1,177 @@
+/**
+
+ * 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

@@ -0,0 +1,31 @@
+"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

@@ -0,0 +1,146 @@
+/**
+
+ * 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;
+}
+/**
+ * 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;
+}

package/dist/providers/ICloudProvider.js

@@ -0,0 +1,31 @@
+"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

@@ -0,0 +1,31 @@
+/**
+
+ * 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

@@ -0,0 +1,31 @@
+"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

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

package/dist/utils/Logger.d.ts

@@ -0,0 +1,144 @@
+/**
+
+ * 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;
+}