@almadar/cli 0.3.2 → 0.3.3

package/shells/typescript-shell/packages/client/src/components/organisms/debug/hooks/useDebugData.ts

@@ -0,0 +1,100 @@
+/**
+ * useDebugData - Hook that aggregates data from all debug registries
+ * 
+ * Polls registries and provides combined data for the RuntimeDebugger.
+ * 
+ * @packageDocumentation
+ */
+
+import * as React from 'react';
+import {
+    getAllTraits,
+    subscribeToTraitChanges,
+    type TraitDebugInfo
+} from '../../../../lib/traitRegistry';
+import {
+    getAllTicks,
+    subscribeToTickChanges,
+    type TickExecution
+} from '../../../../lib/tickRegistry';
+import {
+    getGuardHistory,
+    subscribeToGuardChanges,
+    type GuardEvaluation
+} from '../../../../lib/guardRegistry';
+import {
+    getEntitySnapshot,
+    type EntitySnapshot
+} from '../../../../lib/entityDebug';
+import {
+    getDebugEvents,
+    subscribeToDebugEvents,
+    type DebugEvent
+} from '../../../../lib/debugRegistry';
+
+export interface DebugData {
+    traits: TraitDebugInfo[];
+    ticks: TickExecution[];
+    guards: GuardEvaluation[];
+    events: DebugEvent[];
+    entitySnapshot: EntitySnapshot | null;
+    lastUpdate: number;
+}
+
+/**
+ * Hook that aggregates data from all debug registries.
+ * Subscribes to changes and polls entity snapshots.
+ */
+export function useDebugData(): DebugData {
+    const [data, setData] = React.useState<DebugData>(() => ({
+        traits: [],
+        ticks: [],
+        guards: [],
+        events: [],
+        entitySnapshot: null,
+        lastUpdate: Date.now(),
+    }));
+
+    // Subscribe to all registries
+    React.useEffect(() => {
+        // Update function
+        const updateData = () => {
+            setData({
+                traits: getAllTraits(),
+                ticks: getAllTicks(),
+                guards: getGuardHistory(),
+                events: getDebugEvents(),
+                entitySnapshot: getEntitySnapshot(),
+                lastUpdate: Date.now(),
+            });
+        };
+
+        // Initial load
+        updateData();
+
+        // Subscribe to changes
+        const unsubTraits = subscribeToTraitChanges(updateData);
+        const unsubTicks = subscribeToTickChanges(updateData);
+        const unsubGuards = subscribeToGuardChanges(updateData);
+        const unsubEvents = subscribeToDebugEvents(updateData);
+
+        // Poll entity snapshot (entities don't have a subscription system)
+        const pollInterval = setInterval(() => {
+            setData(prev => ({
+                ...prev,
+                entitySnapshot: getEntitySnapshot(),
+                lastUpdate: Date.now(),
+            }));
+        }, 500);
+
+        return () => {
+            unsubTraits();
+            unsubTicks();
+            unsubGuards();
+            unsubEvents();
+            clearInterval(pollInterval);
+        };
+    }, []);
+
+    return data;
+}

package/shells/typescript-shell/packages/client/src/components/organisms/debug/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Debug Organism Components
+ * 
+ * Runtime debugging tools for KFlow applications.
+ * 
+ * @packageDocumentation
+ */
+
+export { RuntimeDebugger, type RuntimeDebuggerProps } from './RuntimeDebugger';
+export { useDebugData, type DebugData } from './hooks/useDebugData';

package/shells/typescript-shell/packages/client/src/components/organisms/debug/tabs/EntitiesTab.tsx

@@ -0,0 +1,130 @@
+/**
+ * EntitiesTab - Displays entity snapshots
+ * Uses existing component library atoms/molecules.
+ */
+
+import * as React from 'react';
+import type { EntitySnapshot } from '../../../../lib/entityDebug';
+import { Accordion } from '../../../molecules/Accordion';
+import { Badge } from '../../../atoms/Badge';
+import { Typography } from '../../../atoms/Typography';
+import { Stack } from '../../../atoms/Stack';
+import { EmptyState } from '../../../molecules/EmptyState';
+
+interface EntitiesTabProps {
+    snapshot: EntitySnapshot | null;
+}
+
+export function EntitiesTab({ snapshot }: EntitiesTabProps) {
+    if (!snapshot) {
+        return (
+            <EmptyState
+                title="No entity data"
+                description="Debug mode may not be enabled"
+                className="py-8"
+            />
+        );
+    }
+
+    const singletonEntries = Object.entries(snapshot.singletons);
+    const runtimeEntities = snapshot.runtime;
+    const persistentEntries = Object.entries(snapshot.persistent);
+
+    if (singletonEntries.length === 0 && runtimeEntities.length === 0 && persistentEntries.length === 0) {
+        return (
+            <EmptyState
+                title="No entities"
+                description="Entities will appear when spawned"
+                className="py-8"
+            />
+        );
+    }
+
+    // Build accordion items for singletons
+    const singletonItems = singletonEntries.map(([name, data]) => ({
+        id: `singleton-${name}`,
+        header: (
+            <div className="flex items-center gap-2">
+                <Badge variant="primary" size="sm">Singleton</Badge>
+                <Typography variant="body" weight="semibold" className="text-sky-600 dark:text-sky-400">
+                    {name}
+                </Typography>
+            </div>
+        ),
+        content: (
+            <pre className="text-xs text-gray-600 dark:text-gray-400 bg-gray-50 dark:bg-gray-800 p-2 rounded overflow-auto max-h-40">
+                {JSON.stringify(data, null, 2)}
+            </pre>
+        ),
+    }));
+
+    // Build accordion items for runtime entities (limit to 20)
+    const runtimeItems = runtimeEntities.slice(0, 20).map(entity => ({
+        id: entity.id,
+        header: (
+            <div className="flex items-center gap-2">
+                <Typography variant="body" weight="semibold" className="text-sky-600 dark:text-sky-400">
+                    {entity.type}
+                </Typography>
+                <Typography variant="small" className="text-gray-500">
+                    #{entity.id.slice(0, 8)}
+                </Typography>
+            </div>
+        ),
+        content: (
+            <pre className="text-xs text-gray-600 dark:text-gray-400 bg-gray-50 dark:bg-gray-800 p-2 rounded overflow-auto max-h-40">
+                {JSON.stringify(entity.data, null, 2)}
+            </pre>
+        ),
+    }));
+
+    return (
+        <div className="debug-tab debug-tab--entities">
+            {/* Singletons */}
+            {singletonItems.length > 0 && (
+                <div className="mb-4">
+                    <Typography variant="small" weight="medium" className="text-gray-500 mb-2">
+                        Singletons ({singletonItems.length})
+                    </Typography>
+                    <Accordion items={singletonItems} multiple />
+                </div>
+            )}
+
+            {/* Runtime entities */}
+            {runtimeItems.length > 0 && (
+                <div className="mb-4">
+                    <Typography variant="small" weight="medium" className="text-gray-500 mb-2">
+                        Runtime ({runtimeEntities.length})
+                    </Typography>
+                    <Accordion items={runtimeItems} multiple />
+                    {runtimeEntities.length > 20 && (
+                        <Typography variant="small" className="text-gray-400 text-center mt-2">
+                            +{runtimeEntities.length - 20} more entities
+                        </Typography>
+                    )}
+                </div>
+            )}
+
+            {/* Persistent entities */}
+            {persistentEntries.length > 0 && (
+                <div>
+                    <Typography variant="small" weight="medium" className="text-gray-500 mb-2">
+                        Persistent
+                    </Typography>
+                    <Stack gap="xs">
+                        {persistentEntries.map(([type, info]) => (
+                            <div key={type} className="flex items-center justify-between py-1">
+                                <Typography variant="small">{type}</Typography>
+                                <Badge variant={info.loaded ? 'success' : 'default'} size="sm">
+                                    {info.loaded ? `${info.count} loaded` : 'not loaded'}
+                                </Badge>
+                            </div>
+                        ))}
+                    </Stack>
+                </div>
+            )}
+        </div>
+    );
+}
+
+EntitiesTab.displayName = 'EntitiesTab';

package/shells/typescript-shell/packages/client/src/components/organisms/debug/tabs/EventFlowTab.tsx

@@ -0,0 +1,135 @@
+/**
+ * EventFlowTab - Displays event flow and debug messages
+ * Uses existing component library atoms/molecules.
+ */
+
+import * as React from 'react';
+import type { DebugEvent } from '../../../../lib/debugRegistry';
+import { Badge } from '../../../atoms/Badge';
+import { Typography } from '../../../atoms/Typography';
+import { ButtonGroup } from '../../../molecules/ButtonGroup';
+import { Button } from '../../../atoms/Button';
+import { Checkbox } from '../../../atoms/Checkbox';
+import { EmptyState } from '../../../molecules/EmptyState';
+
+interface EventFlowTabProps {
+    events: DebugEvent[];
+}
+
+const TYPE_BADGES: Record<string, { variant: 'default' | 'primary' | 'success' | 'warning' | 'danger' | 'info'; icon: string }> = {
+    trait: { variant: 'primary', icon: '🔄' },
+    tick: { variant: 'warning', icon: '⏱️' },
+    guard: { variant: 'warning', icon: '🛡️' },
+    entity: { variant: 'info', icon: '📦' },
+    event: { variant: 'success', icon: '⚡' },
+    state: { variant: 'danger', icon: '📊' },
+};
+
+export function EventFlowTab({ events }: EventFlowTabProps) {
+    const [filter, setFilter] = React.useState<string>('all');
+    const containerRef = React.useRef<HTMLDivElement>(null);
+    const [autoScroll, setAutoScroll] = React.useState(true);
+
+    // Auto-scroll to bottom when new events arrive
+    React.useEffect(() => {
+        if (autoScroll && containerRef.current) {
+            containerRef.current.scrollTop = containerRef.current.scrollHeight;
+        }
+    }, [events.length, autoScroll]);
+
+    const filteredEvents = React.useMemo(() => {
+        if (filter === 'all') return events;
+        return events.filter(e => e.type === filter);
+    }, [events, filter]);
+
+    const formatTime = (timestamp: number) => {
+        const date = new Date(timestamp);
+        return date.toLocaleTimeString('en-US', {
+            hour12: false,
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+        }) + '.' + String(date.getMilliseconds()).padStart(3, '0');
+    };
+
+    if (events.length === 0) {
+        return (
+            <EmptyState
+                title="No events yet"
+                description="Events will appear as traits, ticks, and other systems execute"
+                className="py-8"
+            />
+        );
+    }
+
+    const eventTypes = Object.keys(TYPE_BADGES).filter(type =>
+        events.some(e => e.type === type)
+    );
+
+    return (
+        <div className="debug-tab debug-tab--events">
+            {/* Filters */}
+            <div className="flex items-center gap-2 mb-3 flex-wrap">
+                <ButtonGroup>
+                    <Button
+                        size="sm"
+                        variant={filter === 'all' ? 'primary' : 'secondary'}
+                        onClick={() => setFilter('all')}
+                    >
+                        All ({events.length})
+                    </Button>
+                    {eventTypes.map(type => {
+                        const count = events.filter(e => e.type === type).length;
+                        const { icon } = TYPE_BADGES[type];
+                        return (
+                            <Button
+                                key={type}
+                                size="sm"
+                                variant={filter === type ? 'primary' : 'secondary'}
+                                onClick={() => setFilter(type)}
+                            >
+                                {icon} {count}
+                            </Button>
+                        );
+                    })}
+                </ButtonGroup>
+                <label className="flex items-center gap-1 text-xs text-gray-500 ml-auto cursor-pointer">
+                    <Checkbox
+                        checked={autoScroll}
+                        onChange={(e) => setAutoScroll(e.target.checked)}
+                    />
+                    Auto-scroll
+                </label>
+            </div>
+
+            {/* Event list */}
+            <div
+                ref={containerRef}
+                className="max-h-64 overflow-y-auto space-y-1 bg-gray-50 dark:bg-gray-800 rounded p-2"
+            >
+                {filteredEvents.slice(-100).map(event => {
+                    const { variant, icon } = TYPE_BADGES[event.type] || { variant: 'default' as const, icon: '•' };
+                    return (
+                        <div
+                            key={event.id}
+                            className="flex items-start gap-2 text-xs py-1 hover:bg-gray-100 dark:hover:bg-gray-700 rounded px-1"
+                        >
+                            <Typography variant="small" className="text-gray-400 font-mono min-w-[65px]">
+                                {formatTime(event.timestamp)}
+                            </Typography>
+                            <span>{icon}</span>
+                            <Badge variant={variant} size="sm" className="min-w-[60px] justify-center">
+                                {event.source}
+                            </Badge>
+                            <Typography variant="small" className="text-gray-600 dark:text-gray-400">
+                                {event.message}
+                            </Typography>
+                        </div>
+                    );
+                })}
+            </div>
+        </div>
+    );
+}
+
+EventFlowTab.displayName = 'EventFlowTab';

package/shells/typescript-shell/packages/client/src/components/organisms/debug/tabs/GuardsPanel.tsx

@@ -0,0 +1,124 @@
+/**
+ * GuardsPanel - Displays guard evaluation history
+ * Uses existing component library atoms/molecules.
+ */
+
+import * as React from 'react';
+import type { GuardEvaluation } from '../../../../lib/guardRegistry';
+import { Accordion } from '../../../molecules/Accordion';
+import { Badge } from '../../../atoms/Badge';
+import { Typography } from '../../../atoms/Typography';
+import { Stack } from '../../../atoms/Stack';
+import { ButtonGroup } from '../../../molecules/ButtonGroup';
+import { Button } from '../../../atoms/Button';
+import { EmptyState } from '../../../molecules/EmptyState';
+
+interface GuardsPanelProps {
+    guards: GuardEvaluation[];
+}
+
+export function GuardsPanel({ guards }: GuardsPanelProps) {
+    const [filter, setFilter] = React.useState<'all' | 'passed' | 'failed'>('all');
+
+    if (guards.length === 0) {
+        return (
+            <EmptyState
+                title="No guard evaluations"
+                description="Guard evaluations will appear when transitions or ticks with guards execute"
+                className="py-8"
+            />
+        );
+    }
+
+    const passedCount = guards.filter(g => g.result).length;
+    const failedCount = guards.length - passedCount;
+
+    const filteredGuards = React.useMemo(() => {
+        if (filter === 'all') return guards;
+        if (filter === 'passed') return guards.filter(g => g.result);
+        return guards.filter(g => !g.result);
+    }, [guards, filter]);
+
+    const formatTime = (timestamp: number) => {
+        const date = new Date(timestamp);
+        return date.toLocaleTimeString('en-US', {
+            hour12: false,
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+        });
+    };
+
+    const accordionItems = filteredGuards.slice(-50).reverse().map(guard => ({
+        id: guard.id,
+        header: (
+            <div className="flex items-center gap-2 w-full">
+                <Badge variant={guard.result ? 'success' : 'danger'} size="sm">
+                    {guard.result ? '✓' : '✗'}
+                </Badge>
+                <Typography variant="body" weight="semibold" className="text-amber-600 dark:text-amber-400">
+                    {guard.guardName}
+                </Typography>
+                <Typography variant="small" className="text-gray-500">
+                    {guard.context.type === 'transition'
+                        ? `${guard.context.transitionFrom} → ${guard.context.transitionTo}`
+                        : guard.context.tickName
+                    }
+                </Typography>
+                <Typography variant="small" className="text-gray-400 ml-auto">
+                    {formatTime(guard.timestamp)}
+                </Typography>
+            </div>
+        ),
+        content: (
+            <Stack gap="sm">
+                <div>
+                    <Typography variant="small" weight="medium" className="text-gray-500">Expression</Typography>
+                    <code className="block mt-1 text-xs text-amber-600 dark:text-amber-400 bg-amber-50 dark:bg-amber-900/20 px-2 py-1 rounded">
+                        {guard.expression}
+                    </code>
+                </div>
+                <div>
+                    <Typography variant="small" weight="medium" className="text-gray-500">Inputs</Typography>
+                    <pre className="mt-1 text-xs text-gray-600 dark:text-gray-400 bg-gray-50 dark:bg-gray-800 p-2 rounded overflow-auto max-h-24">
+                        {JSON.stringify(guard.inputs, null, 2)}
+                    </pre>
+                </div>
+                <div>
+                    <Typography variant="small" weight="medium" className="text-gray-500">Trait</Typography>
+                    <Typography variant="small">{guard.context.traitName}</Typography>
+                </div>
+            </Stack>
+        ),
+    }));
+
+    return (
+        <div className="debug-tab debug-tab--guards">
+            {/* Stats and filters */}
+            <div className="flex items-center justify-between mb-3">
+                <div className="flex gap-3">
+                    <Badge variant="success" size="sm">✓ {passedCount}</Badge>
+                    <Badge variant="danger" size="sm">✗ {failedCount}</Badge>
+                </div>
+                <ButtonGroup>
+                    <Button size="sm" variant={filter === 'all' ? 'primary' : 'secondary'} onClick={() => setFilter('all')}>
+                        All
+                    </Button>
+                    <Button size="sm" variant={filter === 'passed' ? 'primary' : 'secondary'} onClick={() => setFilter('passed')}>
+                        Passed
+                    </Button>
+                    <Button size="sm" variant={filter === 'failed' ? 'primary' : 'secondary'} onClick={() => setFilter('failed')}>
+                        Failed
+                    </Button>
+                </ButtonGroup>
+            </div>
+
+            {/* Guard list */}
+            <div className="max-h-80 overflow-y-auto">
+                <Accordion items={accordionItems} />
+            </div>
+        </div>
+    );
+}
+
+GuardsPanel.displayName = 'GuardsPanel';

package/shells/typescript-shell/packages/client/src/components/organisms/debug/tabs/TicksTab.tsx

@@ -0,0 +1,100 @@
+/**
+ * TicksTab - Displays tick execution timing and status
+ * Uses existing component library atoms/molecules.
+ */
+
+import * as React from 'react';
+import type { TickExecution } from '../../../../lib/tickRegistry';
+import { Badge } from '../../../atoms/Badge';
+import { Typography } from '../../../atoms/Typography';
+import { Stack } from '../../../atoms/Stack';
+import { Card } from '../../../atoms/Card';
+import { EmptyState } from '../../../molecules/EmptyState';
+
+interface TicksTabProps {
+    ticks: TickExecution[];
+}
+
+export function TicksTab({ ticks }: TicksTabProps) {
+    const activeTicks = ticks.filter(t => t.active);
+    const inactiveTicks = ticks.filter(t => !t.active);
+
+    if (ticks.length === 0) {
+        return (
+            <EmptyState
+                title="No ticks registered"
+                description="Ticks will appear when trait tick handlers are running"
+                className="py-8"
+            />
+        );
+    }
+
+    const formatTime = (ms: number) => {
+        if (ms === 0) return 'never';
+        const seconds = Math.floor((Date.now() - ms) / 1000);
+        if (seconds < 1) return 'just now';
+        if (seconds < 60) return `${seconds}s ago`;
+        return `${Math.floor(seconds / 60)}m ago`;
+    };
+
+    const TickCard = ({ tick, active }: { tick: TickExecution; active: boolean }) => (
+        <Card className={`p-3 ${!active ? 'opacity-50' : ''}`}>
+            <div className="flex items-center gap-2 mb-2">
+                <span className={`w-2 h-2 rounded-full ${active ? 'bg-green-500' : 'bg-gray-400'}`} />
+                <Typography variant="body" weight="semibold" className="text-amber-600 dark:text-amber-400">
+                    {tick.name}
+                </Typography>
+                <Typography variant="small" className="text-gray-500">
+                    {tick.traitName}
+                </Typography>
+            </div>
+            <div className="flex gap-3 text-xs text-gray-500">
+                <span>{tick.interval}ms</span>
+                <span>{tick.runCount} runs</span>
+                <span>{tick.executionTime.toFixed(1)}ms exec</span>
+                <span>{formatTime(tick.lastRun)}</span>
+            </div>
+            {tick.guardName && (
+                <div className="mt-2">
+                    <Badge variant={tick.guardPassed ? 'success' : 'danger'} size="sm">
+                        {tick.guardName}: {tick.guardPassed ? '✓' : '✗'}
+                    </Badge>
+                </div>
+            )}
+        </Card>
+    );
+
+    return (
+        <div className="debug-tab debug-tab--ticks">
+            {/* Active ticks */}
+            {activeTicks.length > 0 && (
+                <div className="mb-4">
+                    <Typography variant="small" weight="medium" className="text-gray-500 mb-2">
+                        Active ({activeTicks.length})
+                    </Typography>
+                    <Stack gap="sm">
+                        {activeTicks.map(tick => (
+                            <TickCard key={tick.id} tick={tick} active />
+                        ))}
+                    </Stack>
+                </div>
+            )}
+
+            {/* Inactive ticks */}
+            {inactiveTicks.length > 0 && (
+                <div>
+                    <Typography variant="small" weight="medium" className="text-gray-400 mb-2">
+                        Inactive ({inactiveTicks.length})
+                    </Typography>
+                    <Stack gap="sm">
+                        {inactiveTicks.map(tick => (
+                            <TickCard key={tick.id} tick={tick} active={false} />
+                        ))}
+                    </Stack>
+                </div>
+            )}
+        </div>
+    );
+}
+
+TicksTab.displayName = 'TicksTab';