@creact-labs/creact 0.1.8 → 0.2.1

package/dist/runtime/run.js

@@ -0,0 +1,334 @@
+/**
+ * CReact - Continuous Reactive Runtime with State Machine
+ *
+ * Event-driven runtime that:
+ * 1. Renders JSX -> Fiber tree
+ * 2. Reconciles and applies changes with dependency ordering
+ * 3. Persists state to backend for crash recovery
+ * 4. Subscribes to provider events
+ * 5. When events arrive -> updates affected fibers -> re-renders -> applies new changes
+ */
+import { clearContextStacks } from '../primitives/context';
+import { clearNodeOwnership, clearNodeRegistry, clearOutputHydration, fillInstanceOutputs, getNodeById, prepareOutputHydration, } from '../primitives/instance';
+import { clearHydration, prepareHydration } from '../primitives/store';
+import { serializeNodes } from '../provider/backend';
+import { buildDependencyGraph, reconcile, topologicalSort } from './reconcile';
+import { collectInstanceNodes, renderFiber, resetResourcePath } from './render';
+// flushSync no longer needed - batch() flushes synchronously
+import { StateMachine } from './state-machine';
+/**
+ * CReact - Continuous reactive runtime with state machine
+ *
+ * Subscribes to provider events and automatically re-renders
+ * components when outputs change. This is event-driven, not poll-driven.
+ *
+ * Requires both:
+ * - CReact.provider: Materializes resources (AWS, Terraform, etc.)
+ * - CReact.backend: Persists deployment state (file, DynamoDB, etc.)
+ */
+export class CReact {
+    // Singleton configuration (both required)
+    static provider;
+    static backend;
+    // Internal storage for last runtime (for hot reload / CLI tooling)
+    static _lastRuntime = null;
+    static _lastStackName = null;
+    instanceProvider;
+    instanceBackend;
+    stateMachine;
+    rootFiber = null;
+    currentNodes = [];
+    options;
+    outputChangeHandler = null;
+    stackName = null;
+    constructor(provider, backend, options = {}) {
+        this.instanceProvider = provider;
+        this.instanceBackend = backend;
+        this.options = { maxIterations: 10, ...options };
+        // Initialize state machine (always available now)
+        this.stateMachine = new StateMachine(backend, {
+            user: options.user,
+            enableAuditLog: options.enableAuditLog,
+        });
+        // Subscribe to provider events immediately
+        if (provider.on) {
+            this.outputChangeHandler = (change) => this.handleOutputChange(change);
+            provider.on('outputsChanged', this.outputChangeHandler);
+        }
+    }
+    /**
+     * Start the runtime - render, apply, and begin listening for events
+     *
+     * @param element - JSX element to render
+     * @param stackNameOrPrevious - Stack name (string) or previous nodes (array) for backward compat
+     */
+    async run(element, stackNameOrPrevious) {
+        // Handle backward compatibility: string = stackName, array = previousNodes
+        let previousNodes;
+        if (typeof stackNameOrPrevious === 'string') {
+            this.stackName = stackNameOrPrevious;
+        }
+        else if (Array.isArray(stackNameOrPrevious)) {
+            previousNodes = stackNameOrPrevious;
+        }
+        // Check for interrupted deployment - just log it, normal reconciliation handles resume
+        // Nodes with outputs are treated as "same", nodes without are (re)created
+        if (this.stackName && (await this.stateMachine.canResume(this.stackName))) {
+            const interruptedNode = await this.stateMachine.getInterruptedNodeId(this.stackName);
+            console.log(`[CReact] Resuming interrupted deployment${interruptedNode ? ` (interrupted at: ${interruptedNode})` : ''}`);
+        }
+        // Load previous state from backend if available
+        if (this.instanceBackend && this.stackName && !previousNodes) {
+            const prevState = await this.stateMachine?.getPreviousState(this.stackName);
+            if (prevState) {
+                // Restore resource states
+                this.stateMachine?.restoreResourceStates(prevState.nodes);
+                // Prepare hydration for createStore
+                prepareHydration(prevState.nodes);
+                // Prepare output hydration for useInstance
+                prepareOutputHydration(prevState.nodes);
+                // Use previous nodes for reconciliation
+                // Filter to nodes WITH outputs (completed deployment)
+                // Nodes without outputs (crashed mid-deploy) will be treated as "creates"
+                previousNodes = prevState.nodes.filter((n) => n.outputs && Object.keys(n.outputs).length > 0);
+            }
+        }
+        else if (previousNodes) {
+            prepareHydration(previousNodes);
+            prepareOutputHydration(previousNodes);
+        }
+        // Clear ownership for new render pass (allows re-renders with same node IDs)
+        clearNodeOwnership();
+        // Initial render
+        this.rootFiber = renderFiber(element, []);
+        this.currentNodes = collectInstanceNodes(this.rootFiber);
+        // Clear hydration maps after render (no longer needed)
+        clearOutputHydration();
+        // Initial apply cycle
+        await this.applyChanges(previousNodes ?? []);
+        // Runtime is now active - events will trigger handleOutputChange
+        // For tests: return immediately (events still work)
+        // For CLI: caller can await a keep-alive promise if needed
+    }
+    /**
+     * Apply changes between previous and current nodes
+     *
+     * Uses dependency ordering from reconciler:
+     * 1. Apply deletes (reverse dependency order)
+     * 2. Apply creates/updates in deployment order
+     * 3. Recursively apply any new nodes that appeared
+     *
+     * With synchronous batching, fillInstanceOutputs triggers dependent
+     * re-renders immediately. New nodes appear in registry right away.
+     */
+    async applyChanges(previousNodes) {
+        const changes = reconcile(previousNodes, this.currentNodes);
+        if (changes.creates.length === 0 &&
+            changes.updates.length === 0 &&
+            changes.deletes.length === 0) {
+            // No changes - update state machine to reflect stable state
+            if (this.stackName) {
+                await this.stateMachine.completeDeployment(this.stackName, serializeNodes(this.currentNodes));
+            }
+            return;
+        }
+        // Start deployment tracking
+        if (this.stackName) {
+            await this.stateMachine.startDeployment(this.stackName, serializeNodes(this.currentNodes), {
+                creates: changes.creates.length,
+                updates: changes.updates.length,
+                deletes: changes.deletes.length,
+            });
+        }
+        try {
+            // Apply deletes (reverse order - children first)
+            const deleteIds = changes.deletes.map((n) => n.id);
+            const graph = buildDependencyGraph(changes.deletes);
+            const deleteOrder = topologicalSort(deleteIds, graph).reverse();
+            for (const nodeId of deleteOrder) {
+                const node = changes.deletes.find((n) => n.id === nodeId);
+                if (node) {
+                    this.stateMachine.setResourceState(nodeId, 'applying');
+                    await this.instanceProvider.destroy(node);
+                    if (this.stackName) {
+                        await this.stateMachine.recordResourceDestroyed(this.stackName, nodeId);
+                    }
+                }
+            }
+            // Materialize creates and updates in deployment order
+            // With synchronous batching, fillInstanceOutputs triggers re-renders
+            // immediately - new nodes appear in registry right after each materialize
+            for (const nodeId of changes.deploymentOrder) {
+                // Get current node state from registry (reflects signal updates from prior materializes)
+                const node = getNodeById(nodeId);
+                if (!node)
+                    continue;
+                this.stateMachine.setResourceState(nodeId, 'applying');
+                // Mark this node as being applied (for crash recovery)
+                if (this.stackName) {
+                    await this.stateMachine.markApplying(this.stackName, nodeId);
+                }
+                // Materialize - provider calls node.setOutputs() when outputs are available
+                // For sync providers: setOutputs() is called immediately, triggers reactive updates
+                // For async providers: setOutputs() is called in callback, triggers reactive updates later
+                await this.instanceProvider.materialize([node]);
+                // Extract outputs for state recording (may be empty for async providers)
+                const outputs = node.outputs ?? {};
+                // Note: fillInstanceOutputs is no longer called here - provider uses node.setOutputs()
+                this.stateMachine.setResourceState(nodeId, 'deployed');
+                if (this.stackName) {
+                    await this.stateMachine.clearApplying(this.stackName);
+                    await this.stateMachine.updateNodeOutputs(this.stackName, nodeId, outputs);
+                    await this.stateMachine.recordResourceApplied(this.stackName, nodeId, outputs);
+                }
+            }
+            // Re-collect nodes - new nodes are already created thanks to synchronous batching
+            const newNodes = collectInstanceNodes(this.rootFiber);
+            const hasNewNodes = newNodes.some((n) => !this.currentNodes.some((p) => p.id === n.id));
+            if (hasNewNodes) {
+                const prevNodes = this.currentNodes;
+                this.currentNodes = newNodes;
+                await this.applyChanges(prevNodes); // Recurse for new nodes
+            }
+            else {
+                this.currentNodes = newNodes;
+                // Complete deployment
+                if (this.stackName) {
+                    await this.stateMachine.completeDeployment(this.stackName, serializeNodes(this.currentNodes));
+                }
+            }
+        }
+        catch (error) {
+            // Record failure
+            if (this.stackName) {
+                await this.stateMachine.failDeployment(this.stackName, error instanceof Error ? error : new Error(String(error)));
+            }
+            throw error;
+        }
+    }
+    /**
+     * Handle provider output change events
+     *
+     * This is the event-driven part - when provider emits changes,
+     * we update signals (triggering synchronous re-renders via batch),
+     * and apply any new nodes.
+     */
+    async handleOutputChange(change) {
+        // Find node by resource name (props.name) or node.id
+        const node = this.currentNodes.find((n) => n.props.name === change.resourceName || n.id === change.resourceName);
+        if (!node) {
+            console.warn(`[CReact] No node found for resource: ${change.resourceName}`);
+            return;
+        }
+        // Update signal - reactive system triggers component re-execution
+        // With synchronous batching, re-renders happen inside fillInstanceOutputs
+        fillInstanceOutputs(node.id, change.outputs);
+        // Re-collect and apply any new nodes
+        if (this.rootFiber) {
+            const prevNodes = this.currentNodes;
+            this.currentNodes = collectInstanceNodes(this.rootFiber);
+            await this.applyChanges(prevNodes);
+        }
+    }
+    /**
+     * Get current instance nodes (for debugging/testing)
+     */
+    getNodes() {
+        return [...this.currentNodes];
+    }
+    /**
+     * Get the state machine (for advanced usage)
+     */
+    getStateMachine() {
+        return this.stateMachine;
+    }
+    /**
+     * Stop the runtime
+     */
+    stop() {
+        if (this.instanceProvider.off && this.outputChangeHandler) {
+            this.instanceProvider.off('outputsChanged', this.outputChangeHandler);
+        }
+        if (this.instanceProvider.stop) {
+            this.instanceProvider.stop();
+        }
+    }
+    /**
+     * Render CloudDOM - main entry point
+     *
+     * Usage:
+     *   CReact.provider = myProvider;
+     *   CReact.backend = myBackend;
+     *   export default () => renderCloudDOM(<App />, 'my-stack');
+     */
+    static async renderCloudDOM(element, stackName) {
+        if (!CReact.provider) {
+            throw new Error('CReact.provider must be set before calling renderCloudDOM');
+        }
+        if (!CReact.backend) {
+            throw new Error('CReact.backend must be set before calling renderCloudDOM');
+        }
+        const runtime = new CReact(CReact.provider, CReact.backend);
+        await runtime.run(element, stackName);
+        // Store for CLI/tooling access
+        CReact._lastRuntime = runtime;
+        CReact._lastStackName = stackName;
+        // Return immediately - process stays alive via provider event listeners
+        return runtime.getNodes();
+    }
+    /**
+     * Get last runtime instance (for hot reload / CLI tooling)
+     * Hot reload uses this to re-render with updated code without full restart
+     */
+    static getLastRuntime() {
+        const runtime = CReact._lastRuntime;
+        const stackName = CReact._lastStackName;
+        return runtime && stackName ? { runtime, stackName } : null;
+    }
+}
+/**
+ * Reset all runtime state (for testing)
+ */
+export function resetRuntime() {
+    clearNodeRegistry();
+    clearHydration();
+    clearOutputHydration();
+    clearContextStacks();
+    resetResourcePath();
+}
+/**
+ * Minimal in-memory backend for the convenience run() function
+ * @internal
+ */
+class SimpleInMemoryBackend {
+    states = new Map();
+    async getState(stackName) {
+        const state = this.states.get(stackName);
+        return state ? JSON.parse(JSON.stringify(state)) : null;
+    }
+    async saveState(stackName, state) {
+        this.states.set(stackName, JSON.parse(JSON.stringify(state)));
+    }
+}
+/**
+ * Convenience function to run once and return nodes (for testing)
+ *
+ * Creates a runtime with a simple in-memory backend and runs it.
+ * Use this for tests where you don't need persistent state.
+ */
+export async function run(rootElement, provider, previousNodes, options) {
+    const backend = new SimpleInMemoryBackend();
+    const runtime = new CReact(provider, backend, options);
+    await runtime.run(rootElement, previousNodes);
+    return runtime.getNodes();
+}
+/**
+ * Run with explicit backend (for production use)
+ */
+export async function runWithBackend(rootElement, provider, backend, stackName, options) {
+    const runtime = new CReact(provider, backend, options);
+    await runtime.run(rootElement, stackName);
+    return runtime.getNodes();
+}
+// Convenience export
+export const renderCloudDOM = CReact.renderCloudDOM.bind(CReact);

package/dist/runtime/state-machine.d.ts

@@ -0,0 +1,95 @@
+/**
+ * StateMachine - Resource lifecycle tracking and deployment orchestration
+ *
+ * Tracks:
+ * - Individual resource states (pending → applying → deployed)
+ * - Deployment lifecycle (start → checkpoint → complete/fail)
+ * - Resume capability from crash
+ */
+import type { Backend, DeploymentState, ResourceState, SerializedNode } from '../provider/backend';
+export interface StateMachineOptions {
+    user?: string;
+    enableAuditLog?: boolean;
+}
+/**
+ * StateMachine manages deployment lifecycle and resource states
+ */
+export declare class StateMachine {
+    private backend;
+    private resourceStates;
+    private options;
+    constructor(backend: Backend, options?: StateMachineOptions);
+    /**
+     * Get the current state of a resource
+     */
+    getResourceState(nodeId: string): ResourceState;
+    /**
+     * Set the state of a resource
+     */
+    setResourceState(nodeId: string, state: ResourceState): void;
+    /**
+     * Restore resource states from persisted nodes
+     */
+    restoreResourceStates(nodes: SerializedNode[]): void;
+    /**
+     * Clear all resource states
+     */
+    clearResourceStates(): void;
+    /**
+     * Start a new deployment
+     */
+    startDeployment(stackName: string, nodes: SerializedNode[], changeStats?: {
+        creates: number;
+        updates: number;
+        deletes: number;
+    }): Promise<void>;
+    /**
+     * Update a node's outputs in persisted state (for crash recovery)
+     * This is the real checkpoint - nodes with outputs are considered deployed
+     */
+    updateNodeOutputs(stackName: string, nodeId: string, outputs: Record<string, any>): Promise<void>;
+    /**
+     * Mark a node as currently being applied (for crash recovery)
+     */
+    markApplying(stackName: string, nodeId: string): Promise<void>;
+    /**
+     * Clear the applying marker after successful apply
+     */
+    clearApplying(stackName: string): Promise<void>;
+    /**
+     * Record a resource being applied
+     */
+    recordResourceApplied(stackName: string, nodeId: string, outputs: Record<string, any>): Promise<void>;
+    /**
+     * Record a resource being destroyed
+     */
+    recordResourceDestroyed(stackName: string, nodeId: string): Promise<void>;
+    /**
+     * Complete a successful deployment
+     */
+    completeDeployment(stackName: string, nodes: SerializedNode[]): Promise<void>;
+    /**
+     * Record a failed deployment
+     */
+    failDeployment(stackName: string, error: Error): Promise<void>;
+    /**
+     * Check if a deployment can be resumed
+     */
+    canResume(stackName: string): Promise<boolean>;
+    /**
+     * Get the node that was being applied when crash occurred
+     */
+    getInterruptedNodeId(stackName: string): Promise<string | null>;
+    /**
+     * Get previous deployment state
+     */
+    getPreviousState(stackName: string): Promise<DeploymentState | null>;
+    /**
+     * Acquire deployment lock (if backend supports it)
+     */
+    acquireLock(stackName: string, holder: string, ttlSeconds?: number): Promise<boolean>;
+    /**
+     * Release deployment lock (if backend supports it)
+     */
+    releaseLock(stackName: string): Promise<void>;
+}

package/dist/runtime/state-machine.js

@@ -0,0 +1,209 @@
+/**
+ * StateMachine - Resource lifecycle tracking and deployment orchestration
+ *
+ * Tracks:
+ * - Individual resource states (pending → applying → deployed)
+ * - Deployment lifecycle (start → checkpoint → complete/fail)
+ * - Resume capability from crash
+ */
+/**
+ * StateMachine manages deployment lifecycle and resource states
+ */
+export class StateMachine {
+    backend;
+    resourceStates = new Map();
+    options;
+    constructor(backend, options = {}) {
+        this.backend = backend;
+        this.options = options;
+    }
+    /**
+     * Get the current state of a resource
+     */
+    getResourceState(nodeId) {
+        return this.resourceStates.get(nodeId) ?? 'pending';
+    }
+    /**
+     * Set the state of a resource
+     */
+    setResourceState(nodeId, state) {
+        this.resourceStates.set(nodeId, state);
+    }
+    /**
+     * Restore resource states from persisted nodes
+     */
+    restoreResourceStates(nodes) {
+        this.resourceStates.clear();
+        for (const node of nodes) {
+            // If node has outputs, it was previously deployed
+            const state = node.state ?? (node.outputs ? 'deployed' : 'pending');
+            this.resourceStates.set(node.id, state);
+        }
+    }
+    /**
+     * Clear all resource states
+     */
+    clearResourceStates() {
+        this.resourceStates.clear();
+    }
+    /**
+     * Start a new deployment
+     */
+    async startDeployment(stackName, nodes, changeStats) {
+        const state = {
+            nodes,
+            status: 'applying',
+            stackName,
+            lastDeployedAt: Date.now(),
+            user: this.options.user,
+        };
+        await this.backend.saveState(stackName, state);
+        if (this.options.enableAuditLog && this.backend.appendAuditLog) {
+            await this.backend.appendAuditLog(stackName, {
+                timestamp: Date.now(),
+                action: 'deploy_start',
+                user: this.options.user,
+                details: changeStats,
+            });
+        }
+    }
+    /**
+     * Update a node's outputs in persisted state (for crash recovery)
+     * This is the real checkpoint - nodes with outputs are considered deployed
+     */
+    async updateNodeOutputs(stackName, nodeId, outputs) {
+        const state = await this.backend.getState(stackName);
+        if (state) {
+            const node = state.nodes.find((n) => n.id === nodeId);
+            if (node) {
+                node.outputs = outputs;
+                await this.backend.saveState(stackName, state);
+            }
+        }
+    }
+    /**
+     * Mark a node as currently being applied (for crash recovery)
+     */
+    async markApplying(stackName, nodeId) {
+        const state = await this.backend.getState(stackName);
+        if (state) {
+            state.applyingNodeId = nodeId;
+            await this.backend.saveState(stackName, state);
+        }
+    }
+    /**
+     * Clear the applying marker after successful apply
+     */
+    async clearApplying(stackName) {
+        const state = await this.backend.getState(stackName);
+        if (state) {
+            state.applyingNodeId = undefined;
+            await this.backend.saveState(stackName, state);
+        }
+    }
+    /**
+     * Record a resource being applied
+     */
+    async recordResourceApplied(stackName, nodeId, outputs) {
+        this.setResourceState(nodeId, 'deployed');
+        if (this.options.enableAuditLog && this.backend.appendAuditLog) {
+            await this.backend.appendAuditLog(stackName, {
+                timestamp: Date.now(),
+                action: 'resource_applied',
+                nodeId,
+                user: this.options.user,
+                details: { outputKeys: Object.keys(outputs) },
+            });
+        }
+    }
+    /**
+     * Record a resource being destroyed
+     */
+    async recordResourceDestroyed(stackName, nodeId) {
+        this.resourceStates.delete(nodeId);
+        if (this.options.enableAuditLog && this.backend.appendAuditLog) {
+            await this.backend.appendAuditLog(stackName, {
+                timestamp: Date.now(),
+                action: 'resource_destroyed',
+                nodeId,
+                user: this.options.user,
+            });
+        }
+    }
+    /**
+     * Complete a successful deployment
+     */
+    async completeDeployment(stackName, nodes) {
+        const state = {
+            nodes,
+            status: 'deployed',
+            stackName,
+            lastDeployedAt: Date.now(),
+            user: this.options.user,
+        };
+        await this.backend.saveState(stackName, state);
+        if (this.options.enableAuditLog && this.backend.appendAuditLog) {
+            await this.backend.appendAuditLog(stackName, {
+                timestamp: Date.now(),
+                action: 'deploy_complete',
+                user: this.options.user,
+                details: { nodeCount: nodes.length },
+            });
+        }
+    }
+    /**
+     * Record a failed deployment
+     */
+    async failDeployment(stackName, error) {
+        const state = await this.backend.getState(stackName);
+        if (state) {
+            state.status = 'failed';
+            await this.backend.saveState(stackName, state);
+        }
+        if (this.options.enableAuditLog && this.backend.appendAuditLog) {
+            await this.backend.appendAuditLog(stackName, {
+                timestamp: Date.now(),
+                action: 'deploy_failed',
+                user: this.options.user,
+                details: { error: error.message },
+            });
+        }
+    }
+    /**
+     * Check if a deployment can be resumed
+     */
+    async canResume(stackName) {
+        const state = await this.backend.getState(stackName);
+        return state?.status === 'applying';
+    }
+    /**
+     * Get the node that was being applied when crash occurred
+     */
+    async getInterruptedNodeId(stackName) {
+        const state = await this.backend.getState(stackName);
+        return state?.applyingNodeId ?? null;
+    }
+    /**
+     * Get previous deployment state
+     */
+    async getPreviousState(stackName) {
+        return this.backend.getState(stackName);
+    }
+    /**
+     * Acquire deployment lock (if backend supports it)
+     */
+    async acquireLock(stackName, holder, ttlSeconds = 300) {
+        if (this.backend.acquireLock) {
+            return this.backend.acquireLock(stackName, holder, ttlSeconds);
+        }
+        return true; // No locking support, allow
+    }
+    /**
+     * Release deployment lock (if backend supports it)
+     */
+    async releaseLock(stackName) {
+        if (this.backend.releaseLock) {
+            await this.backend.releaseLock(stackName);
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared types
+ */
+export type { JSXElement } from './jsx/jsx-runtime';
+export type { Context } from './primitives/context';
+export type { InstanceNode, OutputAccessors } from './primitives/instance';
+export type { SetStoreFunction } from './primitives/store';
+export type { AuditLogEntry, Backend, DeploymentState, DeploymentStatus, ResourceState, SerializedNode, } from './provider/backend';
+export type { Provider } from './provider/interface';
+export type { Accessor, Computation, Setter, Signal } from './reactive/signal';
+export type { Fiber } from './runtime/fiber';
+export type { ChangeSet, DependencyGraph } from './runtime/reconcile';
+export type { StateMachineOptions } from './runtime/state-machine';

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared types
+ */
+export {};