@creact-labs/creact 0.1.4 → 0.1.6

package/dist/core/CReact.js

@@ -1096,9 +1096,28 @@ class CReact {
         CReact._lastInstance = instance;
         CReact._lastElement = element;
         CReact._lastStackName = stackName;
+        // Initialize providers if they have an initialize method
+        if (CReact.cloudProvider.initialize) {
+            await CReact.cloudProvider.initialize();
+        }
+        if (CReact.backendProvider.initialize) {
+            await CReact.backendProvider.initialize();
+        }
         // CRITICAL: Load previous state from backend before rendering
         // This enables useState to hydrate from persisted state
         await instance.loadStateForHydration(stackName);
+        // CRITICAL: Detect and fix drift before rendering
+        // This ensures state matches reality and prevents stale deployments
+        const driftResult = await instance.stateMachine.detectAndFixDrift(stackName, CReact.cloudProvider);
+        // If drift was detected and fixed, reload state to get updated outputs
+        if (driftResult.resourcesFixed > 0) {
+            logger.debug(`Reloading state after fixing ${driftResult.resourcesFixed} drifted resources`);
+            // Clear existing hydration data and reload with fresh state
+            const freshState = await instance.stateMachine.getState(stackName);
+            if (freshState?.cloudDOM) {
+                instance.prepareHydration(freshState.cloudDOM, true); // clearExisting = true
+            }
+        }
         // Build and return CloudDOM
         return instance.build(element, stackName);
     }

package/dist/core/StateMachine.d.ts

@@ -421,4 +421,21 @@ export declare class StateMachine {
         changeSet?: ChangeSet;
         cloudDOM?: CloudDOMNode[];
     }>;
+    /**
+     * 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
+     */
+    detectAndFixDrift(stackName: string, cloudProvider: import('../providers/ICloudProvider').ICloudProvider): Promise<{
+        driftDetected: boolean;
+        driftResults: import('../providers/ICloudProvider').DriftDetectionResult[];
+        resourcesFixed: number;
+    }>;
 }

package/dist/core/StateMachine.js

@@ -771,6 +771,102 @@ class StateMachine {
             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;
 /**

package/dist/hooks/useInstance.js

@@ -248,6 +248,40 @@ function useInstance(construct, props) {
     const { currentPath, previousOutputsMap } = context;
     // Get hook index for this useInstance call (instance-specific)
     const hookIndex = (0, context_1.incrementHookIndex)('instance');
+    // CONSTRAINT: Only one useInstance per component
+    // This simplifies dependency tracking and drift recovery
+    if (hookIndex > 0) {
+        const componentName = currentFiber.type?.name || 'Anonymous';
+        throw new Error(`[CReact Constraint] Only one useInstance call is allowed per component.\n\n` +
+            `Component: ${componentName}\n` +
+            `Path: ${currentPath.join('.')}\n\n` +
+            `This constraint ensures:\n` +
+            `  1. Clear resource dependencies (parent-child nesting)\n` +
+            `  2. Simpler drift recovery (clear drifted node + children)\n` +
+            `  3. Better component composition\n\n` +
+            `Solution: Split your component into multiple components, one per resource.\n\n` +
+            `Example:\n` +
+            `  ❌ function Stack() {\n` +
+            `       const db = useInstance(Database, {...});\n` +
+            `       const api = useInstance(API, {...});  // Error!\n` +
+            `     }\n\n` +
+            `  ✅ function Stack() {\n` +
+            `       return (\n` +
+            `         <>\n` +
+            `           <PrimaryDatabase />\n` +
+            `           <ApiServer />\n` +
+            `         </>\n` +
+            `       );\n` +
+            `     }\n` +
+            `     function PrimaryDatabase() {\n` +
+            `       const db = useInstance(Database, {...});\n` +
+            `       return <></>;\n` +
+            `     }\n` +
+            `     function ApiServer() {\n` +
+            `       const api = useInstance(API, {...});\n` +
+            `       return <></>;\n` +
+            `     }\n`);
+    }
     // Extract key from props (React-like)
     const { key, ...restProps } = props;
     // Check for undefined dependencies - enforce deployment order

package/dist/index.d.ts

@@ -28,7 +28,7 @@
 
  */
 export { CReact, JSXElement } from './jsx';
-export type { FC, PropsWithChildren } from './jsx.d';
+export type { FC, PropsWithChildren, ComponentProps } from './jsx';
 import { CReact as CReactClass } from './core/CReact';
 export { CReact as CReactCore, CReactConfig } from './core/CReact';
 export declare const renderCloudDOM: typeof CReactClass.renderCloudDOM;
@@ -36,7 +36,7 @@ export { Renderer } from './core/Renderer';
 export { Validator } from './core/Validator';
 export { CloudDOMBuilder } from './core/CloudDOMBuilder';
 export { FiberNode, CloudDOMNode } from './core/types';
-export { ICloudProvider } from './providers/ICloudProvider';
+export { ICloudProvider, DriftDetectionResult, OutputChangeEvent } from './providers/ICloudProvider';
 export { IBackendProvider } from './providers/IBackendProvider';
 export { useInstance } from './hooks/useInstance';
 export { useState } from './hooks/useState';

package/dist/index.js

@@ -30,7 +30,6 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseResourceId = exports.formatPath = exports.normalizePath = exports.normalizePathSegment = exports.validateIdUniqueness = exports.getNodeName = exports.toKebabCase = exports.generateResourceId = exports.createContext = exports.useEffect = exports.useContext = exports.useState = exports.useInstance = exports.CloudDOMBuilder = exports.Validator = exports.Renderer = exports.renderCloudDOM = exports.CReactCore = exports.CReact = void 0;
-/// <reference path="./jsx.d.ts" />
 // CReact - Infrastructure as Code with JSX
 // Main entry point for the library
 // JSX support

package/dist/jsx.d.ts

@@ -62,3 +62,82 @@ export declare namespace CReact {
         children?: any;
     }) => JSXElement;
 }
+/**
+ * Global JSX namespace declarations
+ *
+ * These declarations tell TypeScript how to validate JSX syntax and component props.
+ * By including them in this file (not a separate .d.ts), they are automatically
+ * included in the compiled output and available to package consumers.
+ */
+declare global {
+    namespace JSX {
+        /**
+         * The type returned by JSX expressions
+         */
+        interface Element extends JSXElement {
+        }
+        /**
+         * Intrinsic elements (HTML-like elements)
+         * Empty for CReact - we only support component elements
+         */
+        interface IntrinsicElements {
+        }
+        /**
+         * Defines which prop contains children
+         * This allows TypeScript to understand the children prop
+         */
+        interface ElementChildrenAttribute {
+            children: {};
+        }
+        /**
+         * Base attributes available on all elements (including key)
+         * This applies to all JSX elements, both intrinsic and component-based
+         *
+         * IMPORTANT: This makes 'key' available on ALL JSX elements,
+         * including function components, without needing to add it to props
+         */
+        interface IntrinsicAttributes {
+            key?: string | number;
+        }
+        /**
+         * Attributes available on class components
+         */
+        interface IntrinsicClassAttributes<T> {
+            key?: string | number;
+        }
+        /**
+         * Tell TypeScript how to extract props from a component type
+         * This is critical for making LibraryManagedAttributes work
+         */
+        interface ElementAttributesProperty {
+            props: {};
+        }
+        /**
+         * Augment LibraryManagedAttributes to properly handle key prop
+         *
+         * This tells TypeScript that when checking JSX element props:
+         * 1. Take the component's declared props (P)
+         * 2. Make key optional (it's in IntrinsicAttributes but shouldn't be required)
+         * 3. Allow key to be passed even if not in component props
+         *
+         * We use Omit to remove 'key' from P if it exists, then add it back as optional
+         */
+        type LibraryManagedAttributes<C, P> = Omit<P, 'key'> & IntrinsicAttributes;
+    }
+}
+/**
+ * Type helper for component props with children
+ */
+export interface PropsWithChildren {
+    children?: JSX.Element | JSX.Element[];
+}
+/**
+ * Type helper for functional components
+ * Note: key is handled by JSX.IntrinsicAttributes and doesn't need to be in props
+ */
+export type FC<P = Record<string, unknown>> = (props: P & PropsWithChildren) => JSX.Element | null;
+/**
+ * Type helper for component props that includes JSX attributes (like key)
+ * Use this when defining component prop types to allow key prop
+ */
+export type ComponentProps<P = Record<string, unknown>> = P & JSX.IntrinsicAttributes;

package/dist/providers/ICloudProvider.d.ts

@@ -40,6 +40,23 @@ export interface OutputChangeEvent {
     /** 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.
@@ -143,4 +160,71 @@ export interface ICloudProvider {
      * @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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creact-labs/creact",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "CReact - React for Infrastructure. Render JSX to CloudDOM.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",