@ramme-io/create-app 1.2.0 → 1.2.2

package/template/src/{hooks → engine/runtime}/useAction.ts

@@ -1,17 +1,32 @@
-// src/hooks/useAction.ts
 import { useCallback } from 'react';
-import { useMqtt } from '../contexts/MqttContext';
-import { appManifest } from '../config/app.manifest';
+import { useMqtt } from './MqttContext';
+// ✅ User Verified Path
+import { appManifest } from '../../config/app.manifest';
+
+/**
+ * @file useAction.ts
+ * @description The "Effectuator" hook.
+ *
+ * ARCHITECTURAL ROLE:
+ * This hook handles outgoing commands from the UI. It abstracts the transport layer,
+ * automatically routing actions to the correct destination (MQTT, HTTP, or Mock Console)
+ * based on the entity's configuration in the manifest.
+ */
 
 export const useAction = () => {
   const { publish, isConnected } = useMqtt();
+  
+  // Destructure config/domain from the manifest
   const { config, domain } = appManifest;
 
   const sendAction = useCallback(async (entityId: string, value: any) => {
     // 1. Find the Entity definition
+    // Note: If domain.entities is empty (early stage), this is where we'd add fallback logic
     const entity = domain.entities.find(e => e.id === entityId);
+    
     if (!entity) {
-      console.warn(`[Action] Entity not found: ${entityId}`);
+      // For development/debugging, we log this even if the entity is missing
+      console.warn(`[Action] Entity ID '${entityId}' not found in manifest.`);
       return;
     }
 
@@ -29,7 +44,6 @@ export const useAction = () => {
     // --- Mock Mode ---
     if (config.mockMode) {
       console.log(`%c[Mock Action] Setting ${entity.name} to:`, 'color: #10b981; font-weight: bold;', value);
-      // In a real app, we would update the local cache optimistically here
       return;
     }
 
@@ -47,8 +61,6 @@ export const useAction = () => {
     // --- Live Mode (HTTP) ---
     if (signal.source === 'http' && signal.endpoint) {
       console.log(`[HTTP] POST to ${signal.endpoint}:`, value);
-      // Note: This will likely fail (404/405) against a static .json file, 
-      // but this is the correct code for a real API.
       try {
         await fetch(signal.endpoint, {
             method: 'POST',
@@ -56,7 +68,6 @@ export const useAction = () => {
             body: JSON.stringify({ id: signal.id, value })
         });
       } catch (err) {
-        // We expect this to fail on the static demo, so we suppress the error alert
         console.log('[HTTP] (Simulation) Request sent.'); 
       }
     }

package/template/src/{hooks → engine/runtime}/useCrudLocalStorage.ts

@@ -1,10 +1,12 @@
 import { useState, useCallback } from 'react';
 
 /**
- * A generic hook for performing CRUD (Create, Read, Update, Delete)
+ * @hook useCrudLocalStorage
+ * @description A generic hook for performing CRUD (Create, Read, Update, Delete)
  * operations on an array of items stored in the browser's localStorage.
+ * * It serves as the "Database Engine" for the mock runtime.
  *
- * @param storageKey The unique key for this data in localStorage.
+ * @param storageKey The unique key for this data in localStorage (e.g., 'ramme_db_users').
  * @param initialData The default data to seed localStorage with if it's empty.
  * @returns An object with the current data and functions to manipulate it.
  */
@@ -12,28 +14,43 @@ export const useCrudLocalStorage = <T extends { id: any }>(
   storageKey: string,
   initialData: T[]
 ) => {
+  // 1. Initialize State from LocalStorage
   const [data, setData] = useState<T[]>(() => {
+    // Safety check for Server-Side Rendering
+    if (typeof window === 'undefined') return initialData;
+    
     try {
       const item = window.localStorage.getItem(storageKey);
       if (item) {
-        // If data exists in localStorage, parse and return it.
         return JSON.parse(item);
       } else {
-        // Otherwise, seed localStorage with the initial data.
+        // Seed the "DB" if empty
         window.localStorage.setItem(storageKey, JSON.stringify(initialData));
         return initialData;
       }
     } catch (error) {
-      console.error("Error reading from localStorage", error);
+      console.error(`[Data Lake] Error reading key "${storageKey}":`, error);
       return initialData;
     }
   });
 
+  // 2. CREATE
   const createItem = useCallback((newItem: Omit<T, 'id'>) => {
     setData(prevData => {
-      // Find the highest existing ID to safely create a new one.
-      const maxId = prevData.reduce((max, item) => (item.id > max ? item.id : max), 0);
-      const fullNewItem = { ...newItem, id: maxId + 1 } as T;
+      // ✅ ROBUST ID GENERATION (Zero Jank)
+      // Detects if existing IDs are Numbers or Strings to prevent type conflicts.
+      let newId: any;
+      const isNumeric = prevData.length > 0 && typeof prevData[0].id === 'number';
+
+      if (isNumeric) {
+        const maxId = prevData.reduce((max, item) => (typeof item.id === 'number' && item.id > max ? item.id : max), 0);
+        newId = maxId + 1;
+      } else {
+        // Fallback for string IDs (e.g. 'usr_17354...')
+        newId = `id_${Date.now()}`;
+      }
+
+      const fullNewItem = { ...newItem, id: newId } as T;
       
       const updatedData = [...prevData, fullNewItem];
       window.localStorage.setItem(storageKey, JSON.stringify(updatedData));
@@ -41,6 +58,7 @@ export const useCrudLocalStorage = <T extends { id: any }>(
     });
   }, [storageKey]);
 
+  // 3. UPDATE
   const updateItem = useCallback((updatedItem: T) => {
     setData(prevData => {
       const updatedData = prevData.map(item =>
@@ -51,6 +69,7 @@ export const useCrudLocalStorage = <T extends { id: any }>(
     });
   }, [storageKey]);
 
+  // 4. DELETE
   const deleteItem = useCallback((id: T['id']) => {
     setData(prevData => {
       const updatedData = prevData.filter(item => item.id !== id);

package/template/src/{hooks → engine/runtime}/useDataQuery.ts

@@ -1,6 +1,20 @@
 import { useMemo } from 'react';
 
-// --- 1. Export the Missing Types (Fixes ts(2305)) ---
+/**
+ * @file useDataQuery.ts
+ * @description The "In-Memory Database Engine".
+ *
+ * ARCHITECTURAL ROLE:
+ * Since this application runs without a real backend, this hook acts as the
+ * SQL Query Engine. It takes raw arrays from the Data Lake and performs
+ * real-time filtering, sorting, and pagination before passing the result
+ * to the UI.
+ *
+ * CAPABILITIES:
+ * 1. WHERE: Supports complex filtering (equals, contains, gt, lt).
+ * 2. ORDER BY: Handles ascending/descending sorts on any field.
+ * 3. LIMIT/OFFSET: Calculates pagination slices automatically.
+ */
 
 export type SortDirection = 'asc' | 'desc';
 

package/template/src/engine/runtime/useSignal.ts

@@ -0,0 +1,51 @@
+import { useMemo } from 'react';
+import { useSignalStore } from './useSignalStore';
+// ✅ Import Manifest to get static metadata (min, max, units)
+import { appManifest } from '../../config/app.manifest';
+
+export interface SignalState {
+  id: string;
+  value: any;
+  unit?: string;
+  min?: number;
+  max?: number;
+  timestamp?: number;
+  status: 'fresh' | 'stale'; // Simplified status
+}
+
+/**
+ * @hook useSignal
+ * @description The "Signal Selector".
+ *
+ * ARCHITECTURAL ROLE:
+ * This hook is the bridge between the Static Manifest and the Dynamic Store.
+ * 1. It finds the signal definition in the Manifest (for min/max/unit).
+ * 2. It grabs the live value from the Zustand SignalStore.
+ * 3. It merges them into a single object for the UI to consume.
+ */
+export const useSignal = (signalId: string): SignalState => {
+  // 1. Get Live Data from Store
+  const signalData = useSignalStore((state: { signals: { [x: string]: any; }; }) => state.signals[signalId]);
+
+  // 2. Get Static Definition from Manifest
+  // We use useMemo so we don't search the array on every render
+  const signalDef = useMemo(() => {
+    return appManifest.domain.signals.find((s) => s.id === signalId);
+  }, [signalId]);
+
+  // 3. Merge and Return
+  const value = signalData?.value ?? signalDef?.defaultValue ?? 0;
+  
+  // Determine if data is stale (older than 10 seconds)
+  const isStale = signalData ? (Date.now() - signalData.timestamp > 10000) : true;
+
+  return {
+    id: signalId,
+    value: value,
+    unit: signalDef?.unit,
+    min: signalDef?.min,
+    max: signalDef?.max,
+    timestamp: signalData?.timestamp,
+    status: isStale ? 'stale' : 'fresh'
+  };
+};

package/template/src/engine/runtime/useSignalStore.ts

@@ -0,0 +1,94 @@
+import { create } from 'zustand';
+import { useEffect } from 'react';
+
+/**
+ * @file useSignalStore.ts
+ * @description The "Short-Term Memory" of the application.
+ *
+ * ARCHITECTURAL ROLE:
+ * This Zustand store holds the instantaneous value of every Signal (IoT sensor).
+ * It acts as the buffer between the high-speed data stream (MQTT/Simulation)
+ * and the UI components.
+ */
+
+// --- 1. SIGNAL STORE TYPES ---
+export interface SignalValue {
+  value: any;
+  timestamp: number;
+}
+
+interface SignalStore {
+  signals: Record<string, SignalValue>;
+  // Single update (used by UI controls)
+  updateSignal: (id: string, value: any) => void;
+  // Batch update (used by MQTT/Simulation)
+  updateSignals: (updates: Record<string, any>) => void;
+}
+
+// Initial State matches your dashboard IDs to prevent "undefined" errors on load
+const initialState = {
+  living_room_ac: { value: 72, timestamp: Date.now() },
+  living_room_hum: { value: 45, timestamp: Date.now() },
+  server_01: { value: 42, timestamp: Date.now() },
+  front_door_lock: { value: 'LOCKED', timestamp: Date.now() }
+};
+
+export const useSignalStore = create<SignalStore>((set) => ({
+  signals: initialState,
+  
+  updateSignal: (id, value) => set((state) => ({
+    signals: {
+      ...state.signals,
+      [id]: { value, timestamp: Date.now() }
+    }
+  })),
+
+  updateSignals: (updates) => set((state) => {
+    const newSignals = { ...state.signals };
+    Object.entries(updates).forEach(([id, val]) => {
+      newSignals[id] = { value: val, timestamp: Date.now() };
+    });
+    return { signals: newSignals };
+  })
+}));
+
+/**
+ * Hook to access specific signals in a component.
+ * Usage: const signals = useGeneratedSignals();
+ */
+export const useGeneratedSignals = () => {
+  return useSignalStore((state) => state.signals);
+};
+
+// --- 2. SIMULATION ENGINE (The Missing Piece) ---
+/**
+ * A hook that generates fake data for testing when no MQTT broker is connected.
+ * You can toggle this on/off via the manifest config.
+ */
+export const useSimulation = (isEnabled: boolean = true) => {
+  const { updateSignals } = useSignalStore();
+
+  useEffect(() => {
+    if (!isEnabled) return;
+
+    console.log("[System] Simulation Mode: ON 🎲");
+    const interval = setInterval(() => {
+      // Simulate random fluctuations
+      const updates: Record<string, any> = {};
+      
+      // Randomize values slightly around a baseline
+      updates['living_room_ac'] = Number((72 + (Math.random() * 4 - 2)).toFixed(1));
+      updates['living_room_hum'] = Number((45 + (Math.random() * 6 - 3)).toFixed(1));
+      updates['server_01'] = Math.floor(Math.random() * 100);
+      
+      // Randomly flip the lock status occasionally (1% chance)
+      if (Math.random() > 0.99) {
+         updates['front_door_lock'] = Math.random() > 0.5 ? 'LOCKED' : 'UNLOCKED';
+      }
+      
+      updateSignals(updates);
+    }, 2000); // Update every 2 seconds
+
+    return () => clearInterval(interval);
+  }, [isEnabled, updateSignals]);
+};

package/template/src/engine/runtime/useWorkflowEngine.ts

@@ -0,0 +1,144 @@
+import { useEffect } from 'react';
+import { useToast } from '@ramme-io/ui';
+// ✅ 1. Correct Imports from Store
+import { useGeneratedSignals, useSimulation } from './useSignalStore';
+// ✅ 2. Correct Import from Manifest
+import { appManifest } from '../../config/app.manifest';
+
+// Minimal Types for internal use (until schema is formalized)
+interface ActionDefinition {
+  type: string;
+  config: Record<string, any>;
+}
+
+interface WorkflowDefinition {
+  id: string;
+  name: string;
+  active: boolean;
+  trigger: {
+    type: string;
+    config: {
+      signalId: string;
+      condition: string;
+    };
+  };
+  actions: ActionDefinition[];
+}
+
+/**
+ * THE RUNTIME LOGIC ENGINE
+ * This hook breathes life into the application.
+ * It watches for signal changes and executes the workflows defined in the manifest.
+ */
+export const useWorkflowEngine = () => {
+  const signals = useGeneratedSignals();
+  const { addToast } = useToast();
+  
+  // 1. Activate the Data Simulation (Randomizer)
+  // This now checks internally if it should run (based on boolean arg)
+  useSimulation(appManifest.config.mockMode);
+
+  // 2. Define the Action Executor
+  const executeAction = async (action: ActionDefinition, context: any) => {
+    console.log(`[Engine] Executing: ${action.type}`, action);
+
+    switch (action.type) {
+      case 'send_notification':
+        addToast(action.config.message || 'Notification Sent', 'info');
+        break;
+
+      case 'update_resource':
+        // In a real app, this would call the API
+        addToast(`Updating Resource: ${JSON.stringify(action.config)}`, 'success');
+        break;
+
+      case 'agent_task':
+        // Simulate AI Agent processing
+        console.log(`[AI Agent] Thinking about: "${action.config.prompt}"...`);
+        addToast('AI Agent Analyzing...', 'info');
+        
+        setTimeout(() => {
+          // Mock response based on prompt context
+          const response = action.config.prompt?.includes('health') 
+            ? "System Operating Normally." 
+            : "Optimization Recommended.";
+            
+          addToast(`🤖 Agent: "${response}"`, 'success', 5000);
+        }, 1500);
+        break;
+
+      case 'navigate':
+        window.location.href = action.config.path;
+        break;
+
+      default:
+        console.warn('Unknown action type:', action.type);
+    }
+  };
+
+  // 3. Watch Signals & Trigger Workflows
+  useEffect(() => {
+    // Safety check for undefined domain/workflows
+    if (!appManifest.domain?.workflows) return;
+
+    // We cast to our local type since manifest might be "any"
+    (appManifest.domain.workflows as unknown as WorkflowDefinition[]).forEach((flow) => {
+      if (!flow.active) return;
+
+      // Check Trigger: Signal Change
+      if (flow.trigger.type === 'signal_change') {
+        const signalId = flow.trigger.config.signalId;
+        const condition = flow.trigger.config.condition; // e.g., "> 80"
+        
+        const signal = signals[signalId];
+        
+        if (signal) {
+          const val = signal.value; // Cleaned up access
+          
+          try {
+            // Check if condition is met (e.g. "50 > 80")
+            const isMet = checkCondition(val, condition); 
+            
+            // Debounce: In a real app, we'd check timestamps to avoid firing every 2ms
+            // For now, we rely on the simulation being slow (2s)
+            if (isMet) {
+              console.log(`[Engine] Trigger Fired: ${flow.name}`);
+              flow.actions.forEach(action => executeAction(action, { signal: val }));
+            }
+          } catch (e) {
+            // Ignore parse errors
+          }
+        }
+      }
+    });
+  }, [signals, addToast]); 
+
+  return { 
+    // Exposed for manual triggering (e.g. Buttons)
+    triggerWorkflow: (workflowId: string) => {
+      // @ts-ignore
+      const flow = appManifest.domain?.workflows?.find(w => w.id === workflowId);
+      if (flow) {
+        // @ts-ignore
+        flow.actions.forEach(action => executeAction(action, { manual: true }));
+      }
+    }
+  };
+};
+
+// --- HELPER: Safe Condition Checker ---
+const checkCondition = (value: number, condition: string): boolean => {
+  if (!condition) return false;
+  const parts = condition.trim().split(' ');
+  const operator = parts[0];
+  const target = parseFloat(parts[1]);
+
+  switch (operator) {
+    case '>': return value > target;
+    case '<': return value < target;
+    case '>=': return value >= target;
+    case '<=': return value <= target;
+    case '==': return value === target;
+    default: return false;
+  }
+};

package/template/src/{core → engine/types}/manifest-types.ts

@@ -1,5 +1,17 @@
 // src/core/manifest-types.ts
 
+import { type IconName } from '@ramme-io/ui';
+
+/**
+ * Defines a simple navigation link structure used in menus.
+ */
+export interface ManifestLink {
+  id: string;
+  title: string;
+  path: string;
+  icon?: IconName;
+}
+
 /**
  * The fundamental unit of the UI.
  * Corresponds to a specific React component in the registry.
@@ -40,12 +52,32 @@ export interface PageDefinition {
   sections: PageSection[];
 }
 
+// ✅ NEW: Full App Specification Types (Matches app.manifest.ts)
+export interface AppMeta {
+  name: string;
+  version: string;
+  description: string;
+  author: string;
+}
+
+export interface AppConfig {
+  theme: 'system' | 'light' | 'dark';
+  mockMode: boolean;
+  brokerUrl?: string; // Added for MQTT
+}
+
+export interface AppDomain {
+  signals: any[];
+  entities: any[];
+}
+
 /**
  * The "Brain" of the application.
  * This JSON structure drives the entire UI.
  */
-export interface AppManifest {
-  appName: string;
-  version: string;
+export interface AppSpecification {
+  meta: AppMeta;
+  config: AppConfig;
+  domain: AppDomain;
   pages: PageDefinition[];
 }

package/template/src/{types → engine/validation}/schema.ts

@@ -1,5 +1,22 @@
 import { z } from 'zod';
 
+/**
+ * @file schema.ts
+ * @description The "Application Constitution".
+ *
+ * ARCHITECTURAL ROLE:
+ * This file uses Zod to define the strict runtime validation rules for the 
+ * App Manifest. While `manifest-types.ts` handles compile-time TypeScript checks,
+ * this file handles runtime validation, ensuring that any JSON loaded into the 
+ * engine (whether from a file, API, or user input) is structurally sound.
+ *
+ * LAYERS DEFINED:
+ * 1. **SaaS Layer:** Data resources, fields, and tables.
+ * 2. **Physical Layer:** IoT signals, sensors, and entities.
+ * 3. **Logic Layer:** Workflows, triggers, and automated actions.
+ * 4. **Presentation Layer:** Pages, sections, and UI blocks.
+ */
+
 // ------------------------------------------------------------------
 // 1. DATA RESOURCE DEFINITIONS (SaaS Layer)
 // ------------------------------------------------------------------
@@ -70,6 +87,39 @@ export const EntitySchema = z.object({
 });
 export type EntityDefinition = z.infer<typeof EntitySchema>;
 
+// ------------------------------------------------------------------
+// ✅ NEW: LOGIC & WORKFLOW DEFINITIONS
+// ------------------------------------------------------------------
+
+export const TriggerSchema = z.object({
+  id: z.string(),
+  type: z.enum(['signal_change', 'manual_action', 'schedule', 'webhook']),
+  config: z.record(z.string(), z.any()), 
+});
+
+export const ActionSchema = z.object({
+  id: z.string(),
+  type: z.enum([
+    'update_resource', 
+    'send_notification', 
+    'mqtt_publish', 
+    'api_call', 
+    'navigate', 
+    'agent_task'
+  ]),
+  config: z.record(z.string(), z.any()),
+});
+
+export const WorkflowSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  active: z.boolean().default(true),
+  trigger: TriggerSchema,
+  actions: z.array(ActionSchema),
+});
+export type WorkflowDefinition = z.infer<typeof WorkflowSchema>;
+export type ActionDefinition = z.infer<typeof ActionSchema>;
+
 
 // ------------------------------------------------------------------
 // 3. UI LAYOUT DEFINITIONS (Presentation Layer)
@@ -78,7 +128,6 @@ export type EntityDefinition = z.infer<typeof EntitySchema>;
 export const BlockSchema = z.object({
   id: z.string(),
   type: z.string(),
-  // ✅ FIX: Explicitly define Key and Value types
   props: z.record(z.string(), z.any()), 
   layout: z.object({
     colSpan: z.number().optional(),
@@ -115,7 +164,7 @@ export const AppSpecificationSchema = z.object({
     version: z.string(),
     description: z.string().optional(),
     author: z.string().optional(),
-    createdAt: z.string().optional(), // <--- ADD THIS LINE
+    createdAt: z.string().optional(),
   }),
   
   config: z.object({
@@ -130,6 +179,8 @@ export const AppSpecificationSchema = z.object({
   domain: z.object({
     signals: z.array(SignalSchema),
     entities: z.array(EntitySchema),
+    // ✅ ADDED WORKFLOWS HERE
+    workflows: z.array(WorkflowSchema).optional(),
   }),
 
   pages: z.array(PageSchema).optional(),

package/template/src/{pages → features/ai/pages}/AiChat.tsx

@@ -7,7 +7,7 @@ import {
   Message,
   PromptInput,
 } from '@ramme-io/ui';
-import { useMockChat } from '../hooks/useMockChat'; // <--- The new brain
+import { useMockChat } from '../../assistant/useMockChat'; // <--- The new brain
 
 const AiChat: React.FC = () => {
   const { messages, isLoading, sendMessage } = useMockChat();