@decido/shell 1.0.0

package/src/hooks/useGeminiStream.ts

@@ -0,0 +1,282 @@
+/**
+ * useGeminiStream — Direct Gemini API streaming for Decido Studio chat.
+ *
+ * Uses the REST SSE endpoint to stream responses from Gemini,
+ * emitting ChatMessage V2 fields (thinking, executionSteps) in real time.
+ *
+ * 📚 Inspired by Gemini CLI (geminiChat.ts):
+ *   - Retry with exponential backoff on 429/500/503
+ *   - Content retry on empty/invalid responses
+ *   - Abort signal propagation for clean cancellation
+ *   - Chunk validation (finishReason check)
+ *
+ * API key is read from:
+ *   1. localStorage 'google_gemini_api_key'
+ *   2. import.meta.env.VITE_GEMINI_API_KEY
+ *
+ * Usage:
+ *   const { sendMessage, abort, isStreaming } = useGeminiStream();
+ *   sendMessage('Explica qué es un grafo DSD');
+ */
+import { useState, useCallback, useRef } from 'react';
+import { usePlaygroundStore } from '../store/usePlaygroundStore';
+import type { ExecutionStep } from '../store/playgroundTypes';
+
+interface UseGeminiStreamOptions {
+    model?: string;
+    systemInstruction?: string;
+    maxRetries?: number;           // Max retry attempts (default: 3)
+    initialRetryDelay?: number;    // Initial delay in ms (default: 500)
+}
+
+/** Retry configuration inspired by Gemini CLI's retryWithBackoff */
+interface RetryConfig {
+    maxAttempts: number;
+    initialDelay: number;
+    maxDelay: number;
+    retryableStatusCodes: number[];
+}
+
+const DEFAULT_RETRY: RetryConfig = {
+    maxAttempts: 3,
+    initialDelay: 500,
+    maxDelay: 30000,
+    retryableStatusCodes: [429, 500, 502, 503],
+};
+
+export function useGeminiStream(options: UseGeminiStreamOptions = {}) {
+    const {
+        model = 'gemini-flash-lite-latest',
+        systemInstruction,
+        maxRetries = DEFAULT_RETRY.maxAttempts,
+        initialRetryDelay = DEFAULT_RETRY.initialDelay,
+    } = options;
+
+    const [isStreaming, setIsStreaming] = useState(false);
+    const [error, setError] = useState<string | null>(null);
+    const abortRef = useRef<AbortController | null>(null);
+    const addChatMessage = usePlaygroundStore(s => s.addChatMessage);
+
+    const getApiKey = useCallback(() => {
+        return localStorage.getItem('google_gemini_api_key')
+            || (import.meta as any).env?.VITE_GEMINI_API_KEY
+            || '';
+    }, []);
+
+    const sendMessage = useCallback(async (prompt: string) => {
+        const apiKey = getApiKey();
+        if (!apiKey) {
+            setError('No Gemini API key found. Set it in localStorage "google_gemini_api_key" or VITE_GEMINI_API_KEY.');
+            addChatMessage({
+                type: 'error', sender: 'system',
+                text: '⚠️ No se encontró API key de Gemini. Configúrala en localStorage como "google_gemini_api_key".',
+            });
+            return;
+        }
+
+        setIsStreaming(true);
+        setError(null);
+
+        // Add user message
+        addChatMessage({ type: 'text', sender: 'user', text: prompt });
+
+        const executionSteps: ExecutionStep[] = [];
+        const thinkingStart = Date.now();
+        executionSteps.push({ type: 'thinking', label: 'Processing', startTime: thinkingStart });
+
+        // Create AbortController
+        const controller = new AbortController();
+        abortRef.current = controller;
+
+        const retryConfig: RetryConfig = {
+            ...DEFAULT_RETRY,
+            maxAttempts: maxRetries,
+            initialDelay: initialRetryDelay,
+        };
+
+        try {
+            const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:streamGenerateContent?alt=sse&key=${apiKey}`;
+
+            const body: any = {
+                contents: [{ role: 'user', parts: [{ text: prompt }] }],
+                generationConfig: { temperature: 0.7, maxOutputTokens: 4096 },
+            };
+
+            if (systemInstruction) {
+                body.systemInstruction = { parts: [{ text: systemInstruction }] };
+            }
+
+            // ── Retry loop with exponential backoff (from Gemini CLI) ──
+            let response: Response | null = null;
+            let delay = retryConfig.initialDelay;
+
+            for (let attempt = 1; attempt <= retryConfig.maxAttempts; attempt++) {
+                if (controller.signal.aborted) break;
+
+                try {
+                    response = await fetch(url, {
+                        method: 'POST',
+                        headers: { 'Content-Type': 'application/json' },
+                        body: JSON.stringify(body),
+                        signal: controller.signal,
+                    });
+
+                    if (response.ok) break; // Success, exit retry loop
+
+                    // Check retryable status
+                    if (retryConfig.retryableStatusCodes.includes(response.status)) {
+                        if (attempt < retryConfig.maxAttempts) {
+                            executionSteps.push({
+                                type: 'retry' as any,
+                                label: `Retry ${attempt}/${retryConfig.maxAttempts} (HTTP ${response.status})`,
+                                startTime: Date.now(),
+                            });
+                            // Update UI with retry step
+                            const retryMsgId = `retry-${Date.now()}`;
+                            usePlaygroundStore.getState().upsertChatMessage(retryMsgId, {
+                                id: retryMsgId, type: 'alert', sender: 'system',
+                                text: `🔄 Reintentando (${attempt}/${retryConfig.maxAttempts})... HTTP ${response.status}`,
+                                timestamp: Date.now(),
+                            });
+
+                            await new Promise(resolve => setTimeout(resolve, delay));
+                            delay = Math.min(delay * 2, retryConfig.maxDelay);
+                            response = null; // Reset for next attempt
+                            continue;
+                        }
+                    }
+
+                    // Non-retryable error
+                    const errText = await response.text();
+                    throw new Error(`Gemini API error ${response.status}: ${errText.slice(0, 200)}`);
+                } catch (fetchErr: any) {
+                    if (fetchErr.name === 'AbortError') throw fetchErr;
+                    if (attempt >= retryConfig.maxAttempts) throw fetchErr;
+
+                    // Network error → retry
+                    executionSteps.push({
+                        type: 'retry' as any,
+                        label: `Retry ${attempt}/${retryConfig.maxAttempts} (network)`,
+                        startTime: Date.now(),
+                    });
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    delay = Math.min(delay * 2, retryConfig.maxDelay);
+                }
+            }
+
+            if (!response || !response.ok) {
+                throw new Error('All retry attempts exhausted');
+            }
+
+            // Mark thinking done, start text streaming
+            executionSteps[0].endTime = Date.now();
+            const textStart = Date.now();
+            executionSteps.push({ type: 'text_delta', label: 'Streaming', startTime: textStart });
+
+            // Read SSE stream
+            const reader = response.body?.getReader();
+            if (!reader) throw new Error('No response body reader');
+
+            const decoder = new TextDecoder();
+            let fullText = '';
+            const msgId = `gemini-${Date.now()}`;
+
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+
+                const chunk = decoder.decode(value, { stream: true });
+                const lines = chunk.split('\n');
+
+                for (const line of lines) {
+                    if (!line.startsWith('data: ')) continue;
+                    const jsonStr = line.slice(6).trim();
+                    if (!jsonStr || jsonStr === '[DONE]') continue;
+
+                    try {
+                        const data = JSON.parse(jsonStr);
+
+                        // ── Chunk validation (from Gemini CLI) ──
+                        const candidate = data?.candidates?.[0];
+                        if (!candidate) continue; // Skip empty candidates
+
+                        const text = candidate?.content?.parts?.[0]?.text;
+                        if (text) {
+                            fullText += text;
+
+                            // Upsert the streaming message
+                            usePlaygroundStore.getState().upsertChatMessage(msgId, {
+                                id: msgId,
+                                type: 'text',
+                                sender: 'agent',
+                                text: fullText,
+                                timestamp: Date.now(),
+                                executionSteps: [...executionSteps],
+                            });
+                        }
+
+                        // Check finishReason (Gemini CLI validates this)
+                        if (candidate.finishReason && candidate.finishReason !== 'STOP') {
+                            executionSteps.push({
+                                type: 'text_complete',
+                                label: `Finished: ${candidate.finishReason}`,
+                                startTime: Date.now(),
+                                endTime: Date.now(),
+                            });
+                        }
+                    } catch {
+                        // Skip invalid JSON lines
+                    }
+                }
+            }
+
+            // ── Content retry: if stream ended with empty text, retry once ──
+            if (!fullText.trim() && !controller.signal.aborted) {
+                executionSteps.push({
+                    type: 'retry' as any,
+                    label: 'Content retry (empty response)',
+                    startTime: Date.now(),
+                });
+                addChatMessage({
+                    type: 'alert', sender: 'system',
+                    text: '🔄 Respuesta vacía, reintentando...',
+                });
+                // Recursive single retry
+                setIsStreaming(false);
+                abortRef.current = null;
+                return sendMessage(prompt);
+            }
+
+            // Finalize execution steps
+            executionSteps[executionSteps.length - 1].endTime ??= Date.now();
+            executionSteps.push({ type: 'text_complete', label: 'Complete', startTime: Date.now(), endTime: Date.now() });
+
+            // Final update
+            usePlaygroundStore.getState().upsertChatMessage(msgId, {
+                id: msgId,
+                type: 'text',
+                sender: 'agent',
+                text: fullText,
+                timestamp: Date.now(),
+                executionSteps,
+            });
+
+        } catch (err: any) {
+            if (err.name === 'AbortError') {
+                addChatMessage({ type: 'alert', sender: 'system', text: '⏹️ Generación cancelada por el usuario.' });
+            } else {
+                setError(err.message);
+                addChatMessage({ type: 'error', sender: 'system', text: `❌ Error: ${err.message}` });
+            }
+        } finally {
+            setIsStreaming(false);
+            abortRef.current = null;
+        }
+    }, [model, systemInstruction, maxRetries, initialRetryDelay, getApiKey, addChatMessage]);
+
+    const abort = useCallback(() => {
+        abortRef.current?.abort();
+    }, []);
+
+    return { sendMessage, abort, isStreaming, error };
+}

package/src/hooks/useIntentLens.ts

@@ -0,0 +1,224 @@
+/**
+ * useIntentLens — Real-time intent detection for chat input.
+ * 
+ * As the user types, this hook detects intent-triggering words/phrases
+ * and returns colored tokens for visual feedback in the input field.
+ * 
+ * Only uses regex (Level ①, 0ms). The LLM (Level ②) is called only on submit.
+ */
+import { useMemo } from 'react';
+
+// ═══════════════════════════════════════════
+// Intent Types
+// ═══════════════════════════════════════════
+
+export type IntentType =
+    | 'CREATE_GRAPH'
+    | 'EDIT_GRAPH'
+    | 'UI_ACTION'
+    | 'MCP_ACTION'
+    | 'NAVIGATE'
+    | 'NONE';
+
+export interface IntentToken {
+    text: string;
+    intent: IntentType;
+    color: string | null;
+    isMatch: boolean;
+}
+
+export interface DetectedIntent {
+    type: IntentType;
+    label: string;
+    color: string;
+    icon: string;
+    matchedPhrases: string[];
+}
+
+// ═══════════════════════════════════════════
+// Intent Patterns (mirrors usePlaygroundCommander regex)
+// ═══════════════════════════════════════════
+
+export const INTENT_PATTERNS: Array<{
+    type: IntentType;
+    pattern: RegExp;
+    label: string;
+    icon: string;
+    color: string;
+    examples: string[];
+}> = [
+    {
+        type: 'EDIT_GRAPH',
+        pattern: /\b(agrega|suma|añade|conecta|modifica|cambia|elimina|borra|parchea|actualiza|inserta|mueve)\b/gi,
+        label: 'Editar Grafo',
+        icon: '✏️',
+        color: '#f59e0b',
+        examples: [
+            'Agrega un nodo de validación después de login',
+            'Conecta el nodo de pago con el de confirmación',
+            'Elimina el paso de verificación duplicado',
+        ],
+    },
+    {
+        type: 'CREATE_GRAPH',
+        pattern: /\b(grafo|flujo|nodos|blueprint|escenario|onboarding|proceso|workflow|pipeline|trigger|subflujo|orquest)\b|\b(crea|diseña|genera|construye)\s+(un|una|el|la|los|las)\b/gi,
+        label: 'Crear Grafo',
+        icon: '🔗',
+        color: '#10b981',
+        examples: [
+            'Crea un flujo de onboarding para nuevos usuarios',
+            'Diseña un pipeline de procesamiento de datos',
+            'Genera un blueprint con 5 nodos de decisión',
+        ],
+    },
+    {
+        type: 'UI_ACTION',
+        pattern: /\b(shell|tema|theme|sidebar|panel|activity\s*bar|status\s*bar|top\s*bar|notificaci[oó]n|shortcut|atajo|layout)\b|\b(configura)\s+(el|la|los|las)\b/gi,
+        label: 'Acción UI',
+        icon: '🎨',
+        color: '#3b82f6',
+        examples: [
+            'Abre el panel de sidebar',
+            'Configura el tema oscuro',
+            'Cambia el layout a pantalla completa',
+        ],
+    },
+    {
+        type: 'MCP_ACTION',
+        pattern: /\b(ejecuta|invoca|llama|herramienta|tool|api|endpoint)\b/gi,
+        label: 'Acción MCP',
+        icon: '⚡',
+        color: '#a855f7',
+        examples: [
+            'Ejecuta la herramienta de análisis de código',
+            'Invoca el endpoint de validación',
+            'Llama al API de búsqueda semántica',
+        ],
+    },
+    {
+        type: 'NAVIGATE',
+        pattern: /\b(landing|página\s*web|web\s*page|website|diseño\s*web|sitio|homepage|portfolio|dashboard\s*ui|ui\s*design|mockup|prototipo\s*web)\b/gi,
+        label: 'Web Preview',
+        icon: '🌐',
+        color: '#06b6d4',
+        examples: [
+            'Crea una landing page para un SaaS de IA',
+            'Diseña un portfolio moderno con tema oscuro',
+            'Genera un dashboard UI para métricas de ventas',
+            'Crea una página de pricing con 3 planes',
+        ],
+    },
+];
+
+// Dynamic pattern registry for SDK extensibility
+let _extraPatterns: typeof INTENT_PATTERNS = [];
+export function registerIntentPattern(p: typeof INTENT_PATTERNS[0]) { _extraPatterns.push(p); }
+export function getIntentPatterns() { return [...INTENT_PATTERNS, ..._extraPatterns]; }
+
+// ═══════════════════════════════════════════
+// Tokenizer
+// ═══════════════════════════════════════════
+
+function tokenizeWithIntents(input: string): IntentToken[] {
+    if (!input.trim()) return [];
+
+    // Find all matches across all patterns
+    const matches: Array<{ start: number; end: number; intent: IntentType; color: string }> = [];
+
+    for (const { type, pattern, color } of INTENT_PATTERNS) {
+        // Reset regex lastIndex
+        const re = new RegExp(pattern.source, pattern.flags);
+        let match;
+        while ((match = re.exec(input)) !== null) {
+            matches.push({
+                start: match.index,
+                end: match.index + match[0].length,
+                intent: type,
+                color,
+            });
+        }
+    }
+
+    // Sort by position
+    matches.sort((a, b) => a.start - b.start);
+
+    // Build tokens
+    const tokens: IntentToken[] = [];
+    let cursor = 0;
+
+    for (const m of matches) {
+        // Skip overlapping matches
+        if (m.start < cursor) continue;
+
+        // Non-matching text before this match
+        if (m.start > cursor) {
+            tokens.push({
+                text: input.slice(cursor, m.start),
+                intent: 'NONE',
+                color: null,
+                isMatch: false,
+            });
+        }
+
+        // The matched token
+        tokens.push({
+            text: input.slice(m.start, m.end),
+            intent: m.intent,
+            color: m.color,
+            isMatch: true,
+        });
+
+        cursor = m.end;
+    }
+
+    // Remaining text
+    if (cursor < input.length) {
+        tokens.push({
+            text: input.slice(cursor),
+            intent: 'NONE',
+            color: null,
+            isMatch: false,
+        });
+    }
+
+    return tokens;
+}
+
+// ═══════════════════════════════════════════
+// Hook
+// ═══════════════════════════════════════════
+
+export function useIntentLens(input: string) {
+    const result = useMemo(() => {
+        const tokens = tokenizeWithIntents(input);
+
+        // Deduplicate detected intents
+        const intentMap = new Map<IntentType, DetectedIntent>();
+        for (const token of tokens) {
+            if (token.isMatch && token.intent !== 'NONE') {
+                const existing = intentMap.get(token.intent);
+                if (existing) {
+                    existing.matchedPhrases.push(token.text);
+                } else {
+                    const pattern = INTENT_PATTERNS.find((p) => p.type === token.intent)!;
+                    intentMap.set(token.intent, {
+                        type: token.intent,
+                        label: pattern.label,
+                        color: pattern.color,
+                        icon: pattern.icon,
+                        matchedPhrases: [token.text],
+                    });
+                }
+            }
+        }
+
+        return {
+            tokens,
+            detectedIntents: Array.from(intentMap.values()),
+            hasIntents: intentMap.size > 0,
+            primaryIntent: intentMap.size > 0 ? Array.from(intentMap.values())[0] : null,
+        };
+    }, [input]);
+
+    return result;
+}

package/src/hooks/useKeyboardShortcuts.ts

@@ -0,0 +1,69 @@
+import { useEffect } from 'react';
+import { useShellStore } from '../store/engine';
+import { useCommandRegistry, useShortcutManager } from '@decido/commands';
+
+export const useKeyboardShortcuts = () => {
+    const registerCommand = useCommandRegistry((state) => state.registerCommand);
+    const registerDefaultShortcut = useShortcutManager((state) => state.registerDefaultShortcut);
+
+    useEffect(() => {
+        // Register Core Commands
+        registerCommand({
+            id: 'shell.toggleCommandPalette',
+            title: 'Toggle Command Palette',
+            category: 'Shell',
+            handler: () => {
+                const state = useShellStore.getState();
+                state.setCommandPaletteOpen(!state.isCommandPaletteOpen);
+            }
+        });
+        registerDefaultShortcut('shell.toggleCommandPalette', '$mod+k');
+
+        registerCommand({
+            id: 'shell.openShortcutSettings',
+            title: 'Configurar Atajos',
+            category: 'Shell',
+            handler: () => {
+                const state = useShellStore.getState();
+                state.setShortcutSettingsOpen(!state.isShortcutSettingsOpen);
+            }
+        });
+        registerDefaultShortcut('shell.openShortcutSettings', '$mod+Shift+K');
+
+        registerCommand({
+            id: 'shell.toggleForgeTerminal',
+            title: 'Toggle Forge Terminal',
+            category: 'Shell',
+            handler: () => {
+                const state = useShellStore.getState();
+                state.setForgeTerminalOpen(!state.isForgeTerminalOpen);
+            }
+        });
+        registerDefaultShortcut('shell.toggleForgeTerminal', '$mod+j');
+
+        registerCommand({
+            id: 'shell.toggleGodMode',
+            title: 'Toggle God Mode',
+            category: 'Shell',
+            handler: () => {
+                const state = useShellStore.getState();
+                state.setGodModePanelOpen(!state.isGodModePanelOpen);
+            }
+        });
+        registerDefaultShortcut('shell.toggleGodMode', '$mod+Shift+D');
+
+        registerCommand({
+            id: 'shell.closePanels',
+            title: 'Close Active Panels',
+            category: 'Shell',
+            handler: () => {
+                const state = useShellStore.getState();
+                if (state.isCommandPaletteOpen) state.setCommandPaletteOpen(false);
+                if (state.isForgeTerminalOpen) state.setForgeTerminalOpen(false);
+                if (state.isGodModePanelOpen) state.setGodModePanelOpen(false);
+            }
+        });
+        registerDefaultShortcut('shell.closePanels', 'Escape');
+
+    }, [registerCommand, registerDefaultShortcut]);
+};

package/src/hooks/useLoggerBridge.ts

@@ -0,0 +1,32 @@
+import { useEffect } from 'react';
+import { logger } from '@decido/logger';
+import { usePlaygroundStore } from '../store/usePlaygroundStore';
+import { useDebugPanelStore } from '../store/useDebugPanelStore';
+
+/**
+ * useLoggerBridge — Subscribes to @decido/logger and pipes entries to both:
+ * 1. usePlaygroundStore.addLog (legacy terminal)
+ * 2. useDebugPanelStore.addLogEntry (structured debug panel)
+ *
+ * Should be called once, at the top-level component (PDC or AppShell).
+ */
+export function useLoggerBridge() {
+    const addLog = usePlaygroundStore((s) => s.addLog);
+    const addDebugLogEntry = useDebugPanelStore((s) => s.addLogEntry);
+
+    useEffect(() => {
+        const unsubscribe = logger.subscribe((entry) => {
+            const catPrefix = entry.categories.length > 0 ? `[${entry.categories.join(',')}] ` : '';
+            addLog(`${catPrefix}${entry.message}`, entry.level);
+            addDebugLogEntry({
+                timestamp: entry.timestamp,
+                level: entry.level,
+                categories: entry.categories,
+                message: entry.message,
+                data: entry.data,
+                source: entry.source,
+            });
+        });
+        return () => unsubscribe();
+    }, [addLog, addDebugLogEntry]);
+}