rufloui 0.3.2 → 0.3.35

package/TESTS.md

@@ -0,0 +1,91 @@
+# RuFloUI Test Suite
+
+## Quick Start
+
+```bash
+npm test              # Run all tests once
+npx vitest            # Run in watch mode
+npx vitest --coverage # Run with coverage report
+npx vitest run src/backend   # Run only backend tests
+npx vitest run src/frontend  # Run only frontend tests
+```
+
+## Test Runner
+
+- **Vitest 2.x** with two environment modes:
+  - `jsdom` (default) — for React component and browser API tests
+  - `node` — for backend tests (opted-in per file via `// @vitest-environment node`)
+
+Configuration: `vitest.config.ts`
+Setup file: `src/frontend/test-setup.ts` (loads `@testing-library/jest-dom` matchers)
+
+## Test Structure
+
+```
+src/
+├── backend/__tests__/
+│   ├── server-utils.test.ts         # Unit: parseCliTable, parseCliOutput, sanitizeShellArg
+│   ├── server-integration.test.ts   # Integration: persistence layer, health check parsing,
+│   │                                 #   time matching, env var cleanup, WebSocket broadcast logic
+│   ├── e2e-workflows.test.ts        # E2E: task lifecycle, agent lifecycle, swarm lifecycle,
+│   │                                 #   session lifecycle, workflow lifecycle
+│   ├── webhook-github.test.ts       # Unit+Integration: GitHub webhook signature verification,
+│   │                                 #   route handlers, config, auto-assign, templates
+│   └── webhook-gitlab.test.ts       # Unit+Integration: GitLab webhook token validation,
+│                                     #   route handlers, config, auto-assign, edge cases
+└── frontend/__tests__/
+    ├── store.test.ts                # Unit: Zustand store actions and selectors (agents, tasks,
+    │                                 #   logs, viz sessions, swarm monitor, all setters)
+    ├── api.test.ts                  # Unit: API client (all endpoint namespaces, error handling,
+    │                                 #   timeout behavior)
+    └── components.test.tsx          # Unit: UI components (Button, Card, StatusBadge) with
+                                      #   variants, sizes, hover, disabled/loading states
+```
+
+## What Each File Covers
+
+### Backend
+
+| File | Level | Coverage |
+|------|-------|----------|
+| `server-utils.test.ts` | Unit | `parseCliTable` (8 cases: empty, headers, multi-col, ellipsis, separators, CRLF, missing cells), `parseCliOutput` (4 cases), `sanitizeShellArg` (6 cases: injection vectors) |
+| `server-integration.test.ts` | Integration | Persistence save/load (6 cases: tasks, agents, workflows, .tmp recovery, atomic write, corruption), health check parsing (5 cases: pass/warn/fail/Windows), time matching (3 cases), env var cleanup (3 cases), WebSocket broadcast event classification (3 cases), sanitizeShellArg injection prevention (5 cases), parseCliTable with real CLI output patterns (3 cases) |
+| `e2e-workflows.test.ts` | E2E | Task lifecycle: create-assign-complete-cancel (8 cases), Agent lifecycle: spawn-list-terminate (5 cases), Swarm lifecycle: init-status-shutdown-reinit (5 cases), Session lifecycle: save-list-restore-delete (6 cases), Workflow lifecycle: create-execute-complete (4 cases) |
+| `webhook-github.test.ts` | Unit+Integration | Signature verification (9 cases), webhook receiver (4 cases), event storage/ordering (3 cases), invalid payloads (8 cases), config GET/PUT (10 cases), HMAC integration (2 cases), test endpoint (5 cases), task templates (5 cases), auto-assign failures (2 cases), event status updates (3 cases) |
+| `webhook-gitlab.test.ts` | Unit+Integration | GitLab issue hooks (3 cases), disabled state (1 case), token validation (4 cases), event/repo filtering (5 cases), auto-assign (3 cases), config GET/PUT (3 cases), test endpoint (5 cases), event updates (2 cases), edge cases (4 cases) |
+
+### Frontend
+
+| File | Level | Coverage |
+|------|-------|----------|
+| `store.test.ts` | Unit | Simple setters (6 cases), agent CRUD (6 cases), task CRUD (4 cases), log management (3 cases: prepend, cap), collection setters (4 cases), viz session actions (4 cases), swarm monitor (1 case), additional setters (5 cases: memory stats, active session, hive mind, neural, performance, coordination) |
+| `api.test.ts` | Unit | System endpoints (2 cases), agent endpoints (5 cases), task endpoints (8 cases), memory endpoints (2 cases), swarm endpoints (3 cases), session endpoints (4 cases), webhook endpoints (6 cases), workflow endpoints (5 cases), config endpoints (3 cases), performance endpoints (2 cases), error handling (3 cases: non-OK, JSON parse fail, timeout) |
+| `components.test.tsx` | Unit | Button: render, click, disabled, loading, variants, sizes, hover behavior, custom style (12 cases). Card: children, title, actions, header presence, complex children (7 cases). StatusBadge: render, statuses, empty/null, dot element, sizes, all color mappings (8 cases) |
+
+## Coverage Strategy
+
+### Unit Tests
+Test individual functions and components in isolation. Mock external dependencies (fetch, store, CLI). Fast and deterministic.
+
+### Integration Tests
+Test interaction between components: persistence layer (file I/O), health check parsing (regex matching on CLI output), WebSocket message format and event classification. Use real file system (temp dirs) where needed.
+
+### E2E Tests
+Simulate full user workflows through the in-memory store layer: creating a task and moving it through its lifecycle, spawning agents and managing them, initializing and shutting down swarms. These verify the logical flow without requiring the actual Express server or CLI.
+
+## Test Dependencies
+
+- `vitest` — test runner
+- `jsdom` — browser environment for React tests
+- `@testing-library/react` — React component rendering
+- `@testing-library/jest-dom` — DOM assertion matchers
+- `@testing-library/user-event` — user interaction simulation
+
+All dependencies are in `devDependencies` in `package.json`.
+
+## Adding New Tests
+
+1. **Backend**: Add to `src/backend/__tests__/`. Use `// @vitest-environment node` at the top.
+2. **Frontend**: Add to `src/frontend/__tests__/`. Default jsdom environment applies.
+3. **Naming**: Use `*.test.ts` for pure logic, `*.test.tsx` for React components.
+4. **Pattern**: Server utility functions are copied into test files (since importing `server.ts` starts the server). Webhook modules export testable functions directly.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "rufloui",
-  "version": "0.3.2",
+  "version": "0.3.35",
   "description": "React 19 dashboard for claude-flow v3 multi-agent orchestration",
   "repository": {
     "type": "git",
     "url": "https://github.com/Mario-PB/rufloui.git"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org"
+    "registry": "https://npm.pkg.github.com"
   },
   "license": "MIT",
   "type": "module",

package/src/backend/__tests__/e2e-workflows.test.ts

@@ -0,0 +1,438 @@
+// @vitest-environment node
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+// ── E2E-style tests that verify full workflows ──────────────────────────
+// These simulate the complete request/response cycles that the server handles,
+// testing the logical flow without actually starting the Express server or CLI.
+
+// ── In-memory stores (replicating server.ts store pattern) ──────────────
+
+type TaskRecord = {
+  id: string; title: string; description: string; status: string
+  priority: string; createdAt: string; assignedTo?: string; completedAt?: string; result?: string
+}
+
+type WorkflowRecord = {
+  id: string; name: string; status: string
+  steps: Array<{ id: string; name: string; status: string }>; createdAt: string
+}
+
+type SessionRecord = {
+  id: string; name: string; status: string; createdAt: string
+  agentCount: number; taskCount: number
+}
+
+let taskStore: Map<string, TaskRecord>
+let agentRegistry: Map<string, { id: string; name: string; type: string }>
+let terminatedAgents: Set<string>
+let workflowStore: Map<string, WorkflowRecord>
+let sessionStore: Map<string, SessionRecord>
+let broadcastEvents: Array<{ type: string; payload: unknown }>
+
+function broadcast(type: string, payload: unknown) {
+  broadcastEvents.push({ type, payload })
+}
+
+beforeEach(() => {
+  taskStore = new Map()
+  agentRegistry = new Map()
+  terminatedAgents = new Set()
+  workflowStore = new Map()
+  sessionStore = new Map()
+  broadcastEvents = []
+})
+
+// ── Task lifecycle: create → assign → complete ──────────────────────────
+
+describe('E2E: Task lifecycle (create → assign → complete)', () => {
+  function createTask(title: string, description: string, priority = 'normal'): TaskRecord {
+    const id = `task-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`
+    const task: TaskRecord = {
+      id, title, description, status: 'pending', priority, createdAt: new Date().toISOString(),
+    }
+    taskStore.set(id, task)
+    broadcast('task:added', task)
+    return task
+  }
+
+  function assignTask(taskId: string, agentId: string): TaskRecord {
+    const task = taskStore.get(taskId)
+    if (!task) throw new Error(`Task ${taskId} not found`)
+    task.status = 'in_progress'
+    task.assignedTo = agentId
+    broadcast('task:updated', task)
+    return task
+  }
+
+  function completeTask(taskId: string, result: string): TaskRecord {
+    const task = taskStore.get(taskId)
+    if (!task) throw new Error(`Task ${taskId} not found`)
+    task.status = 'completed'
+    task.completedAt = new Date().toISOString()
+    task.result = result
+    broadcast('task:updated', task)
+    return task
+  }
+
+  function cancelTask(taskId: string): TaskRecord {
+    const task = taskStore.get(taskId)
+    if (!task) throw new Error(`Task ${taskId} not found`)
+    task.status = 'cancelled'
+    broadcast('task:updated', task)
+    return task
+  }
+
+  it('creates a task with pending status', () => {
+    const task = createTask('Fix bug', 'Fix the login bug')
+    expect(task.status).toBe('pending')
+    expect(task.title).toBe('Fix bug')
+    expect(taskStore.has(task.id)).toBe(true)
+    expect(broadcastEvents).toHaveLength(1)
+    expect(broadcastEvents[0].type).toBe('task:added')
+  })
+
+  it('assigns a task to an agent', () => {
+    const task = createTask('Fix bug', 'Fix the login bug')
+    const assigned = assignTask(task.id, 'agent-1')
+    expect(assigned.status).toBe('in_progress')
+    expect(assigned.assignedTo).toBe('agent-1')
+    expect(broadcastEvents).toHaveLength(2)
+    expect(broadcastEvents[1].type).toBe('task:updated')
+  })
+
+  it('completes a task with result', () => {
+    const task = createTask('Fix bug', 'Fix the login bug')
+    assignTask(task.id, 'agent-1')
+    const completed = completeTask(task.id, 'Bug fixed by patching auth module')
+    expect(completed.status).toBe('completed')
+    expect(completed.result).toBe('Bug fixed by patching auth module')
+    expect(completed.completedAt).toBeTruthy()
+    expect(broadcastEvents).toHaveLength(3)
+  })
+
+  it('full lifecycle: create → assign → complete broadcasts 3 events', () => {
+    const task = createTask('Deploy', 'Deploy to staging')
+    assignTask(task.id, 'agent-1')
+    completeTask(task.id, 'Deployed successfully')
+
+    const types = broadcastEvents.map(e => e.type)
+    expect(types).toEqual(['task:added', 'task:updated', 'task:updated'])
+  })
+
+  it('cancels a pending task', () => {
+    const task = createTask('Unused task', 'Not needed')
+    const cancelled = cancelTask(task.id)
+    expect(cancelled.status).toBe('cancelled')
+  })
+
+  it('cancels an in-progress task', () => {
+    const task = createTask('Long task', 'Takes too long')
+    assignTask(task.id, 'agent-1')
+    const cancelled = cancelTask(task.id)
+    expect(cancelled.status).toBe('cancelled')
+  })
+
+  it('throws when assigning a non-existent task', () => {
+    expect(() => assignTask('nonexistent', 'agent-1')).toThrow('not found')
+  })
+
+  it('handles multiple tasks independently', () => {
+    const t1 = createTask('Task 1', 'First')
+    const t2 = createTask('Task 2', 'Second')
+    assignTask(t1.id, 'agent-1')
+    completeTask(t1.id, 'Done 1')
+
+    expect(taskStore.get(t1.id)!.status).toBe('completed')
+    expect(taskStore.get(t2.id)!.status).toBe('pending')
+  })
+})
+
+// ── Agent lifecycle: spawn → list → terminate ───────────────────────────
+
+describe('E2E: Agent lifecycle (spawn → list → terminate)', () => {
+  let agentCounter = 0
+  function spawnAgent(type: string, name: string): { id: string; name: string; type: string; createdAt: string } {
+    agentCounter++
+    const createdAt = `2025-01-01T00:00:${String(agentCounter).padStart(2, '0')}Z`
+    const id = `agent-${agentCounter}`
+    const agent = { id, name, type }
+    agentRegistry.set(createdAt, agent)
+    broadcast('agent:added', { ...agent, createdAt })
+    return { ...agent, createdAt }
+  }
+
+  function listAgents(): Array<{ id: string; name: string; type: string; terminated: boolean }> {
+    return [...agentRegistry.entries()].map(([createdAt, agent]) => ({
+      ...agent,
+      terminated: terminatedAgents.has(createdAt),
+    })).filter(a => !a.terminated)
+  }
+
+  function terminateAgent(createdAt: string) {
+    if (!agentRegistry.has(createdAt)) throw new Error('Agent not found')
+    terminatedAgents.add(createdAt)
+    const agent = agentRegistry.get(createdAt)!
+    broadcast('agent:removed', { id: agent.id })
+  }
+
+  it('spawns an agent and adds to registry', () => {
+    const agent = spawnAgent('coder', 'my-coder')
+    expect(agent.type).toBe('coder')
+    expect(agent.name).toBe('my-coder')
+    expect(agentRegistry.size).toBe(1)
+    expect(broadcastEvents[0].type).toBe('agent:added')
+  })
+
+  it('lists active agents (excludes terminated)', () => {
+    const a1 = spawnAgent('coder', 'coder-1')
+    const a2 = spawnAgent('tester', 'tester-1')
+
+    let agents = listAgents()
+    expect(agents).toHaveLength(2)
+
+    terminateAgent(a1.createdAt)
+    agents = listAgents()
+    expect(agents).toHaveLength(1)
+    expect(agents[0].name).toBe('tester-1')
+  })
+
+  it('terminate broadcasts agent:removed event', () => {
+    const a1 = spawnAgent('coder', 'coder-1')
+    terminateAgent(a1.createdAt)
+    const removeEvents = broadcastEvents.filter(e => e.type === 'agent:removed')
+    expect(removeEvents).toHaveLength(1)
+  })
+
+  it('throws when terminating unknown agent', () => {
+    expect(() => terminateAgent('unknown-time')).toThrow('not found')
+  })
+
+  it('supports spawning multiple agent types', () => {
+    spawnAgent('coder', 'c1')
+    spawnAgent('researcher', 'r1')
+    spawnAgent('tester', 't1')
+    spawnAgent('reviewer', 'rev1')
+
+    const agents = listAgents()
+    expect(agents).toHaveLength(4)
+    expect(agents.map(a => a.type).sort()).toEqual(['coder', 'researcher', 'reviewer', 'tester'])
+  })
+})
+
+// ── Swarm lifecycle: init → status → shutdown ───────────────────────────
+
+describe('E2E: Swarm lifecycle (init → status → shutdown)', () => {
+  let swarmConfig = {
+    id: '', topology: '', strategy: '', maxAgents: 0, createdAt: '', shutdown: true,
+  }
+
+  function initSwarm(topology: string, maxAgents: number, strategy = 'round-robin') {
+    swarmConfig = {
+      id: `swarm-${Date.now()}`,
+      topology,
+      strategy,
+      maxAgents,
+      createdAt: new Date().toISOString(),
+      shutdown: false,
+    }
+    broadcast('swarm:status', {
+      status: 'active', id: swarmConfig.id, topology, maxAgents, strategy,
+    })
+    return swarmConfig
+  }
+
+  function getSwarmStatus() {
+    if (swarmConfig.shutdown) {
+      return { status: 'inactive', id: '', topology: '', maxAgents: 0 }
+    }
+    return {
+      status: 'active',
+      id: swarmConfig.id,
+      topology: swarmConfig.topology,
+      maxAgents: swarmConfig.maxAgents,
+      strategy: swarmConfig.strategy,
+    }
+  }
+
+  function shutdownSwarm() {
+    swarmConfig.shutdown = true
+    broadcast('swarm:status', { status: 'inactive' })
+  }
+
+  beforeEach(() => {
+    swarmConfig = { id: '', topology: '', strategy: '', maxAgents: 0, createdAt: '', shutdown: true }
+  })
+
+  it('initializes a swarm', () => {
+    const config = initSwarm('mesh', 8, 'round-robin')
+    expect(config.topology).toBe('mesh')
+    expect(config.maxAgents).toBe(8)
+    expect(config.shutdown).toBe(false)
+  })
+
+  it('reports active status after init', () => {
+    initSwarm('hierarchical', 4)
+    const status = getSwarmStatus()
+    expect(status.status).toBe('active')
+    expect(status.topology).toBe('hierarchical')
+  })
+
+  it('reports inactive status after shutdown', () => {
+    initSwarm('mesh', 8)
+    shutdownSwarm()
+    const status = getSwarmStatus()
+    expect(status.status).toBe('inactive')
+  })
+
+  it('full lifecycle broadcasts correct events', () => {
+    initSwarm('star', 6)
+    shutdownSwarm()
+    expect(broadcastEvents).toHaveLength(2)
+    expect(broadcastEvents[0].type).toBe('swarm:status')
+    expect((broadcastEvents[0].payload as any).status).toBe('active')
+    expect((broadcastEvents[1].payload as any).status).toBe('inactive')
+  })
+
+  it('can re-initialize after shutdown', () => {
+    initSwarm('mesh', 8)
+    shutdownSwarm()
+    initSwarm('hierarchical', 12)
+    const status = getSwarmStatus()
+    expect(status.status).toBe('active')
+    expect(status.topology).toBe('hierarchical')
+    expect(status.maxAgents).toBe(12)
+  })
+})
+
+// ── Session lifecycle: save → list → restore → delete ───────────────────
+
+describe('E2E: Session lifecycle (save → list → restore → delete)', () => {
+  let sessionCounter = 0
+  function saveSession(name: string): SessionRecord {
+    sessionCounter++
+    const id = `sess-${sessionCounter}`
+    const session: SessionRecord = {
+      id, name, status: 'saved', createdAt: new Date().toISOString(),
+      agentCount: agentRegistry.size, taskCount: taskStore.size,
+    }
+    sessionStore.set(id, session)
+    broadcast('session:list', [...sessionStore.values()])
+    return session
+  }
+
+  function listSessions(): SessionRecord[] {
+    return [...sessionStore.values()]
+  }
+
+  function restoreSession(id: string): SessionRecord {
+    const session = sessionStore.get(id)
+    if (!session) throw new Error('Session not found')
+    session.status = 'restored'
+    broadcast('session:active', session)
+    return session
+  }
+
+  function deleteSession(id: string) {
+    if (!sessionStore.has(id)) throw new Error('Session not found')
+    sessionStore.delete(id)
+    broadcast('session:list', [...sessionStore.values()])
+  }
+
+  it('saves a session', () => {
+    const session = saveSession('morning-session')
+    expect(session.status).toBe('saved')
+    expect(session.name).toBe('morning-session')
+    expect(sessionStore.size).toBe(1)
+  })
+
+  it('lists all sessions', () => {
+    saveSession('session-1')
+    saveSession('session-2')
+    const sessions = listSessions()
+    expect(sessions).toHaveLength(2)
+  })
+
+  it('restores a session', () => {
+    const saved = saveSession('my-session')
+    const restored = restoreSession(saved.id)
+    expect(restored.status).toBe('restored')
+  })
+
+  it('deletes a session', () => {
+    const s1 = saveSession('temp')
+    deleteSession(s1.id)
+    expect(sessionStore.size).toBe(0)
+  })
+
+  it('throws when restoring non-existent session', () => {
+    expect(() => restoreSession('bad-id')).toThrow('not found')
+  })
+
+  it('throws when deleting non-existent session', () => {
+    expect(() => deleteSession('bad-id')).toThrow('not found')
+  })
+})
+
+// ── Workflow lifecycle ──────────────────────────────────────────────────
+
+describe('E2E: Workflow lifecycle', () => {
+  function createWorkflow(name: string, steps: string[]): WorkflowRecord {
+    const id = `wf-${Date.now()}`
+    const workflow: WorkflowRecord = {
+      id, name, status: 'draft', createdAt: new Date().toISOString(),
+      steps: steps.map((s, i) => ({ id: `step-${i}`, name: s, status: 'pending' })),
+    }
+    workflowStore.set(id, workflow)
+    broadcast('workflow:added', workflow)
+    return workflow
+  }
+
+  function executeWorkflow(id: string): WorkflowRecord {
+    const wf = workflowStore.get(id)
+    if (!wf) throw new Error('Workflow not found')
+    wf.status = 'running'
+    for (const step of wf.steps) step.status = 'running'
+    broadcast('workflow:updated', wf)
+    return wf
+  }
+
+  function completeWorkflow(id: string): WorkflowRecord {
+    const wf = workflowStore.get(id)
+    if (!wf) throw new Error('Workflow not found')
+    wf.status = 'completed'
+    for (const step of wf.steps) step.status = 'completed'
+    broadcast('workflow:updated', wf)
+    return wf
+  }
+
+  it('creates a workflow with steps', () => {
+    const wf = createWorkflow('deploy-pipeline', ['build', 'test', 'deploy'])
+    expect(wf.steps).toHaveLength(3)
+    expect(wf.status).toBe('draft')
+    expect(wf.steps[0].name).toBe('build')
+  })
+
+  it('executes a workflow', () => {
+    const wf = createWorkflow('ci', ['lint', 'test'])
+    const running = executeWorkflow(wf.id)
+    expect(running.status).toBe('running')
+    expect(running.steps.every(s => s.status === 'running')).toBe(true)
+  })
+
+  it('completes a workflow', () => {
+    const wf = createWorkflow('ci', ['lint', 'test'])
+    executeWorkflow(wf.id)
+    const completed = completeWorkflow(wf.id)
+    expect(completed.status).toBe('completed')
+    expect(completed.steps.every(s => s.status === 'completed')).toBe(true)
+  })
+
+  it('full lifecycle broadcasts correct events', () => {
+    const wf = createWorkflow('ci', ['test'])
+    executeWorkflow(wf.id)
+    completeWorkflow(wf.id)
+    expect(broadcastEvents.map(e => e.type)).toEqual([
+      'workflow:added', 'workflow:updated', 'workflow:updated',
+    ])
+  })
+})