specrails 0.2.0

package/templates/web-manager/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "specrails-web-manager",
+  "private": true,
+  "scripts": {
+    "dev": "concurrently \"npm run dev:server\" \"npm run dev:client\"",
+    "dev:server": "tsx watch server/index.ts",
+    "dev:client": "cd client && npm run dev",
+    "build": "cd client && npm run build",
+    "typecheck": "tsc --noEmit && cd client && tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "express": "^4.18.0",
+    "ws": "^8.16.0",
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/ws": "^8.5.0",
+    "@types/uuid": "^9.0.0",
+    "@types/node": "^20.0.0",
+    "concurrently": "^8.2.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0",
+    "supertest": "^6.3.0",
+    "@types/supertest": "^2.0.0"
+  }
+}

package/templates/web-manager/server/hooks.test.ts

@@ -0,0 +1,196 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import express from 'express'
+import { createHooksRouter, getPhaseStates, resetPhases } from './hooks'
+import type { WsMessage, PhaseName, PhaseState } from './types'
+
+// The hooks module uses module-level state, so we need a fresh import for isolation.
+// Since we can't easily re-import, we'll use resetPhases to clean up between tests.
+
+function createApp(broadcast: (msg: WsMessage) => void) {
+  const app = express()
+  app.use(express.json())
+  app.use('/hooks', createHooksRouter(broadcast))
+  return app
+}
+
+describe('getPhaseStates', () => {
+  let broadcast: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    broadcast = vi.fn()
+    // Reset all phases to idle before each test
+    resetPhases(broadcast)
+    broadcast.mockClear()
+  })
+
+  it('returns all phases as idle initially', () => {
+    const states = getPhaseStates()
+    expect(states).toEqual({
+      architect: 'idle',
+      developer: 'idle',
+      reviewer: 'idle',
+      ship: 'idle',
+    })
+  })
+
+  it('returns a copy, not a reference', () => {
+    const states = getPhaseStates()
+    states.architect = 'running'
+    expect(getPhaseStates().architect).toBe('idle')
+  })
+})
+
+describe('resetPhases', () => {
+  it('broadcasts a phase message for each phase', () => {
+    const broadcast = vi.fn()
+    resetPhases(broadcast)
+
+    expect(broadcast).toHaveBeenCalledTimes(4)
+    const phases: PhaseName[] = ['architect', 'developer', 'reviewer', 'ship']
+    for (const phase of phases) {
+      expect(broadcast).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: 'phase',
+          phase,
+          state: 'idle',
+          timestamp: expect.any(String),
+        })
+      )
+    }
+  })
+
+  it('sets all phases back to idle', async () => {
+    const broadcast = vi.fn()
+    // First, transition a phase to running via the router
+    const app = createApp(broadcast)
+    const { default: request } = await import('supertest')
+    await request(app)
+      .post('/hooks/events')
+      .send({ event: 'agent_start', agent: 'architect' })
+
+    expect(getPhaseStates().architect).toBe('running')
+
+    resetPhases(broadcast)
+    expect(getPhaseStates().architect).toBe('idle')
+  })
+})
+
+describe('POST /hooks/events', () => {
+  let broadcast: ReturnType<typeof vi.fn>
+  let app: express.Express
+  let request: any
+
+  beforeEach(async () => {
+    broadcast = vi.fn()
+    resetPhases(broadcast)
+    broadcast.mockClear()
+    app = createApp(broadcast)
+    const mod = await import('supertest')
+    request = mod.default
+  })
+
+  it('transitions phase to running on agent_start', async () => {
+    const res = await request(app)
+      .post('/hooks/events')
+      .send({ event: 'agent_start', agent: 'architect' })
+
+    expect(res.status).toBe(200)
+    expect(res.body).toEqual({ ok: true })
+    expect(getPhaseStates().architect).toBe('running')
+    expect(broadcast).toHaveBeenCalledWith(
+      expect.objectContaining({
+        type: 'phase',
+        phase: 'architect',
+        state: 'running',
+      })
+    )
+  })
+
+  it('transitions phase to done on agent_stop', async () => {
+    await request(app)
+      .post('/hooks/events')
+      .send({ event: 'agent_start', agent: 'developer' })
+    broadcast.mockClear()
+
+    const res = await request(app)
+      .post('/hooks/events')
+      .send({ event: 'agent_stop', agent: 'developer' })
+
+    expect(res.status).toBe(200)
+    expect(getPhaseStates().developer).toBe('done')
+  })
+
+  it('transitions phase to error on agent_error', async () => {
+    const res = await request(app)
+      .post('/hooks/events')
+      .send({ event: 'agent_error', agent: 'reviewer' })
+
+    expect(res.status).toBe(200)
+    expect(getPhaseStates().reviewer).toBe('error')
+  })
+
+  it('ignores unknown agent names gracefully', async () => {
+    const res = await request(app)
+      .post('/hooks/events')
+      .send({ event: 'agent_start', agent: 'unknown_agent' })
+
+    expect(res.status).toBe(200)
+    expect(res.body).toEqual({ ok: true })
+    expect(broadcast).not.toHaveBeenCalled()
+  })
+
+  it('ignores unknown event types gracefully', async () => {
+    const res = await request(app)
+      .post('/hooks/events')
+      .send({ event: 'unknown_event', agent: 'architect' })
+
+    expect(res.status).toBe(200)
+    expect(res.body).toEqual({ ok: true })
+    expect(broadcast).not.toHaveBeenCalled()
+  })
+
+  it('handles missing body gracefully', async () => {
+    const res = await request(app)
+      .post('/hooks/events')
+      .send({})
+
+    expect(res.status).toBe(200)
+    expect(res.body).toEqual({ ok: true })
+  })
+
+  it('handles all four phases', async () => {
+    const phases: PhaseName[] = ['architect', 'developer', 'reviewer', 'ship']
+    for (const phase of phases) {
+      await request(app)
+        .post('/hooks/events')
+        .send({ event: 'agent_start', agent: phase })
+      expect(getPhaseStates()[phase]).toBe('running')
+    }
+  })
+
+  it('can transition through full lifecycle: idle -> running -> done', async () => {
+    expect(getPhaseStates().ship).toBe('idle')
+
+    await request(app)
+      .post('/hooks/events')
+      .send({ event: 'agent_start', agent: 'ship' })
+    expect(getPhaseStates().ship).toBe('running')
+
+    await request(app)
+      .post('/hooks/events')
+      .send({ event: 'agent_stop', agent: 'ship' })
+    expect(getPhaseStates().ship).toBe('done')
+  })
+
+  it('can transition from running to error', async () => {
+    await request(app)
+      .post('/hooks/events')
+      .send({ event: 'agent_start', agent: 'architect' })
+    expect(getPhaseStates().architect).toBe('running')
+
+    await request(app)
+      .post('/hooks/events')
+      .send({ event: 'agent_error', agent: 'architect' })
+    expect(getPhaseStates().architect).toBe('error')
+  })
+})

package/templates/web-manager/server/hooks.ts

@@ -0,0 +1,71 @@
+import { Router, Request, Response } from 'express'
+import type { PhaseName, PhaseState, WsMessage } from './types'
+
+const PHASE_NAMES: PhaseName[] = ['architect', 'developer', 'reviewer', 'ship']
+
+const phases: Record<PhaseName, PhaseState> = {
+  architect: 'idle',
+  developer: 'idle',
+  reviewer: 'idle',
+  ship: 'idle',
+}
+
+function isValidPhase(value: string): value is PhaseName {
+  return PHASE_NAMES.includes(value as PhaseName)
+}
+
+function eventToState(event: string): PhaseState | null {
+  if (event === 'agent_start') return 'running'
+  if (event === 'agent_stop') return 'done'
+  if (event === 'agent_error') return 'error'
+  return null
+}
+
+export function getPhaseStates(): Record<PhaseName, PhaseState> {
+  return { ...phases }
+}
+
+export function resetPhases(broadcast: (msg: WsMessage) => void): void {
+  for (const phase of PHASE_NAMES) {
+    phases[phase] = 'idle'
+    broadcast({
+      type: 'phase',
+      phase,
+      state: 'idle',
+      timestamp: new Date().toISOString(),
+    })
+  }
+}
+
+export function createHooksRouter(broadcast: (msg: WsMessage) => void): Router {
+  const router = Router()
+
+  router.post('/events', (req: Request, res: Response) => {
+    const { event, agent } = req.body ?? {}
+
+    if (!agent || !isValidPhase(agent)) {
+      console.warn(`[hooks] unknown agent: ${agent}`)
+      res.json({ ok: true })
+      return
+    }
+
+    const newState = eventToState(event)
+    if (!newState) {
+      console.warn(`[hooks] unknown event: ${event}`)
+      res.json({ ok: true })
+      return
+    }
+
+    phases[agent] = newState
+    broadcast({
+      type: 'phase',
+      phase: agent,
+      state: newState,
+      timestamp: new Date().toISOString(),
+    })
+
+    res.json({ ok: true })
+  })
+
+  return router
+}

package/templates/web-manager/server/index.test.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect, beforeEach, vi, afterEach } from 'vitest'
+
+// Mock child_process and uuid before any imports
+vi.mock('child_process', () => ({
+  spawn: vi.fn(),
+  execSync: vi.fn(),
+}))
+vi.mock('uuid', () => ({
+  v4: vi.fn(() => 'test-uuid-5678'),
+}))
+
+import express from 'express'
+import type { WsMessage } from './types'
+import { ClaudeNotFoundError, SpawnBusyError } from './types'
+import { createHooksRouter, getPhaseStates, resetPhases } from './hooks'
+import { spawnClaude, isSpawnActive, getLogBuffer } from './spawner'
+
+// Build the app the same way index.ts does, but without the WebSocket/listen parts
+function createTestApp() {
+  const broadcast = vi.fn()
+
+  const app = express()
+  app.use(express.json())
+  app.use('/hooks', createHooksRouter(broadcast))
+
+  app.post('/api/spawn', (req, res) => {
+    const { command } = req.body ?? {}
+    if (!command || typeof command !== 'string' || !command.trim()) {
+      res.status(400).json({ error: 'command is required' })
+      return
+    }
+
+    try {
+      const handle = spawnClaude(
+        command,
+        broadcast,
+        () => resetPhases(broadcast)
+      )
+      res.json({ processId: handle.processId })
+    } catch (err) {
+      if (err instanceof ClaudeNotFoundError) {
+        res.status(400).json({ error: err.message })
+      } else if (err instanceof SpawnBusyError) {
+        res.status(409).json({ error: err.message })
+      } else {
+        res.status(500).json({ error: 'Internal server error' })
+      }
+    }
+  })
+
+  app.get('/api/state', (_req, res) => {
+    res.json({
+      projectName: 'test-project',
+      phases: getPhaseStates(),
+      busy: isSpawnActive(),
+    })
+  })
+
+  return { app, broadcast }
+}
+
+describe('API endpoints', () => {
+  let app: express.Express
+  let broadcast: ReturnType<typeof vi.fn>
+  let request: any
+
+  beforeEach(async () => {
+    // Reset phases to clean state
+    const dummyBroadcast = vi.fn()
+    resetPhases(dummyBroadcast)
+
+    const created = createTestApp()
+    app = created.app
+    broadcast = created.broadcast
+
+    const mod = await import('supertest')
+    request = mod.default
+  })
+
+  describe('GET /api/state', () => {
+    it('returns project name, phases, and busy status', async () => {
+      const res = await request(app).get('/api/state')
+
+      expect(res.status).toBe(200)
+      expect(res.body.projectName).toBe('test-project')
+      expect(res.body.phases).toEqual({
+        architect: 'idle',
+        developer: 'idle',
+        reviewer: 'idle',
+        ship: 'idle',
+      })
+      expect(res.body.busy).toBe(false)
+    })
+  })
+
+  describe('POST /api/spawn', () => {
+    it('returns 400 when command is missing', async () => {
+      const res = await request(app).post('/api/spawn').send({})
+
+      expect(res.status).toBe(400)
+      expect(res.body.error).toBe('command is required')
+    })
+
+    it('returns 400 when command is empty string', async () => {
+      const res = await request(app).post('/api/spawn').send({ command: '   ' })
+
+      expect(res.status).toBe(400)
+      expect(res.body.error).toBe('command is required')
+    })
+
+    it('returns 400 when command is not a string', async () => {
+      const res = await request(app).post('/api/spawn').send({ command: 123 })
+
+      expect(res.status).toBe(400)
+      expect(res.body.error).toBe('command is required')
+    })
+
+    it('returns 400 when claude is not found', async () => {
+      const { execSync } = await import('child_process')
+      vi.mocked(execSync).mockImplementation(() => {
+        throw new Error('not found')
+      })
+
+      const res = await request(app).post('/api/spawn').send({ command: '/test' })
+
+      expect(res.status).toBe(400)
+      expect(res.body.error).toBe('claude binary not found')
+    })
+
+    it('returns 409 when a process is already running', async () => {
+      const { execSync, spawn } = await import('child_process')
+      const { EventEmitter } = await import('events')
+      const { Readable } = await import('stream')
+
+      vi.mocked(execSync).mockReturnValue(Buffer.from('/usr/bin/claude'))
+      const child = new EventEmitter() as any
+      child.stdout = new Readable({ read() {} })
+      child.stderr = new Readable({ read() {} })
+      vi.mocked(spawn).mockReturnValue(child as any)
+
+      // First spawn succeeds
+      await request(app).post('/api/spawn').send({ command: '/test1' })
+
+      // Second spawn should fail with 409
+      const res = await request(app).post('/api/spawn').send({ command: '/test2' })
+
+      expect(res.status).toBe(409)
+      expect(res.body.error).toBe('A process is already running')
+
+      // Clean up: close the active process so it doesn't leak into other tests
+      child.emit('close', 0)
+    })
+
+    it('returns processId on successful spawn', async () => {
+      const { execSync, spawn } = await import('child_process')
+      const { EventEmitter } = await import('events')
+      const { Readable } = await import('stream')
+
+      vi.mocked(execSync).mockReturnValue(Buffer.from('/usr/bin/claude'))
+      const child = new EventEmitter() as any
+      child.stdout = new Readable({ read() {} })
+      child.stderr = new Readable({ read() {} })
+      vi.mocked(spawn).mockReturnValue(child as any)
+
+      const res = await request(app).post('/api/spawn').send({ command: '/implement #42' })
+
+      expect(res.status).toBe(200)
+      expect(res.body.processId).toBe('test-uuid-5678')
+    })
+  })
+
+  describe('POST /hooks/events', () => {
+    it('transitions phase state and returns ok', async () => {
+      const res = await request(app)
+        .post('/hooks/events')
+        .send({ event: 'agent_start', agent: 'architect' })
+
+      expect(res.status).toBe(200)
+      expect(res.body).toEqual({ ok: true })
+
+      // Verify state was updated
+      const stateRes = await request(app).get('/api/state')
+      expect(stateRes.body.phases.architect).toBe('running')
+    })
+  })
+})

package/templates/web-manager/server/index.ts

@@ -0,0 +1,99 @@
+import http from 'http'
+import express from 'express'
+import { WebSocketServer, WebSocket } from 'ws'
+import type { WsMessage } from './types'
+import { ClaudeNotFoundError, SpawnBusyError } from './types'
+import { createHooksRouter, getPhaseStates, resetPhases } from './hooks'
+import { spawnClaude, isSpawnActive, getLogBuffer } from './spawner'
+
+// Parse CLI args
+let projectName = process.env.SPECRAILS_PROJECT_NAME || require('path').basename(process.cwd())
+let port = 4200
+
+for (let i = 2; i < process.argv.length; i++) {
+  if (process.argv[i] === '--project' && process.argv[i + 1]) {
+    projectName = process.argv[++i]
+  } else if (process.argv[i] === '--port' && process.argv[i + 1]) {
+    port = parseInt(process.argv[++i], 10)
+  }
+}
+
+const app = express()
+app.use(express.json())
+
+const server = http.createServer(app)
+const wss = new WebSocketServer({ noServer: true })
+
+const clients = new Set<WebSocket>()
+
+function broadcast(msg: WsMessage): void {
+  const data = JSON.stringify(msg)
+  for (const client of clients) {
+    if (client.readyState === WebSocket.OPEN) {
+      client.send(data)
+    }
+  }
+}
+
+server.on('upgrade', (request, socket, head) => {
+  wss.handleUpgrade(request, socket, head, (ws) => {
+    wss.emit('connection', ws, request)
+  })
+})
+
+wss.on('connection', (ws: WebSocket) => {
+  clients.add(ws)
+
+  const initMsg: WsMessage = {
+    type: 'init',
+    projectName,
+    phases: getPhaseStates(),
+    logBuffer: getLogBuffer().slice(-500),
+  }
+  ws.send(JSON.stringify(initMsg))
+
+  ws.on('close', () => {
+    clients.delete(ws)
+  })
+})
+
+// Routes
+app.use('/hooks', createHooksRouter(broadcast))
+
+app.post('/api/spawn', (req, res) => {
+  const { command } = req.body ?? {}
+  if (!command || typeof command !== 'string' || !command.trim()) {
+    res.status(400).json({ error: 'command is required' })
+    return
+  }
+
+  try {
+    const handle = spawnClaude(
+      command,
+      broadcast,
+      () => resetPhases(broadcast)
+    )
+    res.json({ processId: handle.processId })
+  } catch (err) {
+    if (err instanceof ClaudeNotFoundError) {
+      res.status(400).json({ error: err.message })
+    } else if (err instanceof SpawnBusyError) {
+      res.status(409).json({ error: err.message })
+    } else {
+      console.error('[spawn] unexpected error:', err)
+      res.status(500).json({ error: 'Internal server error' })
+    }
+  }
+})
+
+app.get('/api/state', (_req, res) => {
+  res.json({
+    projectName,
+    phases: getPhaseStates(),
+    busy: isSpawnActive(),
+  })
+})
+
+server.listen(port, '127.0.0.1', () => {
+  console.log(`specrails web manager running on http://127.0.0.1:${port}`)
+})