sillyspec 3.20.3 → 3.20.4

package/packages/dashboard/server/index.js

@@ -1,508 +1,588 @@
-import { createServer } from 'http'
-import { WebSocketServer } from 'ws'
-import { existsSync, readFileSync, readdirSync, realpathSync, watch } from 'fs'
-import { join, dirname, basename, sep, resolve } from 'path'
-import { fileURLToPath } from 'url'
-import { homedir } from 'os'
-import open from 'open'
-import { parseProjectState, parseDocsTree, parseProjectOverview, parseGitDetail, parseTechStackDetail, parseDocsList } from './parser.js'
-import { startWatcher, stopWatcher, addCustomScanPath, removeCustomScanPath, getCustomScanPaths, customScanPaths } from './watcher.js'
-import { executeCommand } from './executor.js'
-
-const __dirname = dirname(fileURLToPath(import.meta.url))
-
-// WebSocket clients and active processes
-let wss = null
-const activeProcesses = new Map()
-
-// Progress file watchers: projectPath -> { watcher, timer, refCount }
-const progressWatchers = new Map()
-
-function startProgressWatch(projectPath) {
-  if (progressWatchers.has(projectPath)) {
-    progressWatchers.get(projectPath).refCount++
-    return
-  }
-  const progressFile = join(projectPath, '.sillyspec', '.runtime', 'progress.json')
-  if (!existsSync(progressFile)) return
-
-  let timer = null
-  try {
-    const watcher = watch(progressFile, (eventType) => {
-      if (timer) clearTimeout(timer)
-      timer = setTimeout(() => {
-        timer = null
-        try {
-          const state = parseProjectState(projectPath)
-          broadcast({ type: 'project:update', data: { path: projectPath, state } })
-        } catch {}
-      }, 200)
-    })
-    progressWatchers.set(projectPath, { watcher, timer, refCount: 1 })
-  } catch {}
-}
-
-function stopProgressWatch(projectPath) {
-  const entry = progressWatchers.get(projectPath)
-  if (!entry) return
-  entry.refCount--
-  if (entry.refCount <= 0) {
-    entry.watcher.close()
-    if (entry.timer) clearTimeout(entry.timer)
-    progressWatchers.delete(projectPath)
-  }
-}
-
-/**
- * Broadcast message to all connected WebSocket clients
- * @param {object} data - Data to broadcast
- */
-function broadcast(data) {
-  if (!wss) return
-  const message = JSON.stringify(data)
-  wss.clients.forEach(client => {
-    if (client.readyState === 1) { // OPEN
-      client.send(message)
-    }
-  })
-}
-
-// --- Shared scan logic (aligned with watcher.js) ---
-
-const excludeDirs = new Set([
-  '.Trash', '.cache', '.npm', '.local', '.vscode', 'Library',
-  '.git', 'node_modules', '.Trash-*', '.DS_Store', '.config',
-  '.cocoapods', '.gem', '.rvm', '.nvm', '.asdf', '.brew',
-  'AppData', 'Application Data', '.cargo', '.rustup',
-  '.nuget', '.android', '.gradle', '.m2', '.vscode-server'
-])
-
-function shouldExclude(name, cwd) {
-  if (excludeDirs.has(name)) return true
-  for (const pattern of excludeDirs) {
-    if (pattern.includes('*')) {
-      const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$')
-      if (regex.test(name)) return true
-    }
-  }
-  const cwdName = cwd.split(sep).pop() || cwd.split('/').pop() || ''
-  if (name.startsWith('.') && name !== cwdName) return true
-  return false
-}
-
-function scanDirectory(baseDir, seen, maxDepth = 2, currentDepth = 0) {
-  const cwd = process.cwd()
-  const projects = []
-  try {
-    const entries = readdirSync(baseDir, { withFileTypes: true })
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue
-      if (shouldExclude(entry.name, cwd)) continue
-      const dirPath = join(baseDir, entry.name)
-      let realPath
-      try { realPath = realpathSync(dirPath) } catch { realPath = dirPath }
-      const normalizedPath = realPath.toLowerCase()
-      if (seen.has(normalizedPath)) continue
-      seen.add(normalizedPath)
-      if (existsSync(join(dirPath, '.sillyspec'))) {
-        projects.push({ name: entry.name, path: dirPath })
-      }
-      if (currentDepth < maxDepth) {
-        projects.push(...scanDirectory(dirPath, seen, maxDepth, currentDepth + 1))
-      }
-    }
-  } catch (err) {}
-  return projects
-}
-
-/**
- * Discover all SillySpec projects
- * @returns {Promise<Array>} Array of project objects
- */
-async function discoverProjects() {
-  const home = homedir()
-  const cwd = process.cwd()
-
-  const scanDirs = new Set()
-  scanDirs.add(cwd)
-  scanDirs.add(dirname(cwd))
-  scanDirs.add(dirname(dirname(cwd)))
-  scanDirs.add(home)
-
-  const extraDirs = [
-    'Desktop', '桌面', 'Documents', '文档', 'Downloads', '下载',
-    'Projects', '项目', 'Work', '工作', 'Repos', 'Code', 'src', 'dev',
-    'workspace', '工作区'
-  ]
-
-  for (const extra of extraDirs) {
-    const extraPath = join(home, extra)
-    if (existsSync(extraPath)) scanDirs.add(extraPath)
-  }
-
-  for (const customPath of customScanPaths) {
-    if (existsSync(customPath)) scanDirs.add(customPath)
-  }
-
-  const seen = new Set()
-  const projects = []
-
-  // Normalize cwd for dedup
-  let cwdReal
-  try { cwdReal = realpathSync(cwd) } catch { cwdReal = cwd }
-  seen.add(cwdReal.toLowerCase())
-  if (existsSync(join(cwd, '.sillyspec'))) {
-    projects.push({ name: basename(cwd), path: cwd })
-  }
-
-  for (const baseDir of scanDirs) {
-    projects.push(...scanDirectory(baseDir, seen, 2, 0))
-  }
-
-  return projects
-}
-
-/**
- * Handle WebSocket message for CLI execution
- * @param {object} ws - WebSocket client
- * @param {object} data - Message data
- */
-function handleCliExecute(ws, data) {
-  const { projectName, command } = data
-
-  if (!projectName || !command) {
-    ws.send(JSON.stringify({
-      type: 'cli:error',
-      data: { message: 'Missing projectName or command' }
-    }))
-    return
-  }
-
-  discoverProjects().then(projects => {
-    const project = projects.find(p => p.name === projectName)
-    if (!project) {
-      ws.send(JSON.stringify({
-        type: 'cli:error',
-        data: { message: `Project not found: ${projectName}` }
-      }))
-      return
-    }
-
-    const existingKill = activeProcesses.get(projectName)
-    if (existingKill) existingKill()
-
-    const kill = executeCommand(
-      project.path,
-      command,
-      (output) => {
-        broadcast({
-          type: 'cli:output',
-          data: { projectName, output: output.data, outputType: output.type }
-        })
-      },
-      (result) => {
-        activeProcesses.delete(projectName)
-        broadcast({
-          type: 'cli:complete',
-          data: { projectName, exitCode: result.code, signal: result.signal }
-        })
-      }
-    )
-
-    activeProcesses.set(projectName, kill)
-    broadcast({ type: 'cli:started', data: { projectName, command } })
-  })
-}
-
-/**
- * Start the dashboard server
- * @param {object} options - Server options
- * @returns {object} HTTP server instance
- */
-function startServer({ port = 3456, open: openBrowser = true } = {}) {
-  const server = createServer((req, res) => {
-    res.setHeader('Access-Control-Allow-Origin', '*')
-    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type')
-
-    if (req.method === 'OPTIONS') {
-      res.writeHead(200)
-      res.end()
-      return
-    }
-
-    if (req.url === '/api/projects') {
-      discoverProjects().then(projects => {
-        res.setHeader('Content-Type', 'application/json')
-        res.writeHead(200)
-        res.end(JSON.stringify(projects))
-      }).catch(err => {
-        res.writeHead(500)
-        res.end(JSON.stringify({ error: err.message }))
-      })
-      return
-    }
-
-    // Detail API
-    const detailMatch = req.url?.match(/^\/api\/projects\/(.+)\/detail(\?|$)/)
-    if (detailMatch) {
-      const projectPath = decodeURIComponent(detailMatch[1])
-      const url = new URL(req.url, `http://${req.headers.host}`)
-      const type = url.searchParams.get('type')
-      let data
-      try {
-        if (type === 'git') data = parseGitDetail(projectPath)
-        else if (type === 'tech') data = parseTechStackDetail(projectPath)
-        else if (type === 'docs') data = parseDocsList(projectPath)
-        else { res.writeHead(400); res.end(JSON.stringify({ error: 'Invalid type' })); return }
-        res.setHeader('Content-Type', 'application/json')
-        res.writeHead(200)
-        res.end(JSON.stringify(data))
-      } catch (err) {
-        res.writeHead(500)
-        res.end(JSON.stringify({ error: err.message }))
-      }
-      return
-    }
-
-    // Overview API
-    if (req.url?.startsWith('/api/projects/') && req.url.endsWith('/overview')) {
-      const parts = req.url.replace('/api/projects/', '').replace('/overview', '').split('/')
-      const projectPath = decodeURIComponent(parts.join('/'))
-      try {
-        const overview = parseProjectOverview(projectPath)
-        res.setHeader('Content-Type', 'application/json')
-        res.writeHead(200)
-        res.end(JSON.stringify(overview))
-      } catch (err) {
-        res.writeHead(500)
-        res.end(JSON.stringify({ error: err.message }))
-      }
-      return
-    }
-
-    if (req.url?.startsWith('/api/project/')) {
-      const projectName = decodeURIComponent(req.url.split('/').pop())
-      discoverProjects().then(projects => {
-        const project = projects.find(p => p.name === projectName)
-        if (project) {
-          const state = parseProjectState(project.path)
-          res.setHeader('Content-Type', 'application/json')
-          res.writeHead(200)
-          res.end(JSON.stringify({ ...project, state }))
-        } else {
-          res.writeHead(404)
-          res.end(JSON.stringify({ error: 'Project not found' }))
-        }
-      }).catch(err => {
-        res.writeHead(500)
-        res.end(JSON.stringify({ error: err.message }))
-      })
-      return
-    }
-
-    // Docs API
-    if (req.url?.startsWith('/api/docs/content')) {
-      const url = new URL(req.url, `http://${req.headers.host}`)
-      const filePath = url.searchParams.get('path')
-      if (!filePath) {
-        res.writeHead(400)
-        res.end(JSON.stringify({ error: 'Missing path parameter' }))
-        return
-      }
-      // Security: only allow reading files under .sillyspec/docs/
-      const normalizedPath = resolve(filePath)
-      if (!normalizedPath.includes('.sillyspec' + sep + 'docs')) {
-        res.writeHead(403)
-        res.end(JSON.stringify({ error: 'Access denied' }))
-        return
-      }
-      if (existsSync(normalizedPath)) {
-        try {
-          const content = readFileSync(normalizedPath, 'utf-8')
-          res.setHeader('Content-Type', 'text/plain; charset=utf-8')
-          res.writeHead(200)
-          res.end(content)
-        } catch (err) {
-          res.writeHead(500)
-          res.end(JSON.stringify({ error: err.message }))
-        }
-      } else {
-        res.writeHead(404)
-        res.end(JSON.stringify({ error: 'File not found' }))
-      }
-      return
-    }
-
-    if (req.url?.startsWith('/api/docs')) {
-      const url = new URL(req.url, `http://${req.headers.host}`)
-      const projectPath = url.searchParams.get('project')
-      if (!projectPath) {
-        res.writeHead(400)
-        res.end(JSON.stringify({ error: 'Missing project parameter' }))
-        return
-      }
-      const docs = parseDocsTree(projectPath)
-      res.setHeader('Content-Type', 'application/json')
-      res.writeHead(200)
-      res.end(JSON.stringify(docs))
-      return
-    }
-
-    // Serve static files (dist/)
-    const distDir = join(__dirname, '../dist')
-    const indexPath = join(distDir, 'index.html')
-    if (existsSync(distDir)) {
-      const filePath = join(distDir, req.url === '/' ? 'index.html' : req.url.replace(/^\//, ''))
-      if (existsSync(filePath) && !filePath.includes('..')) {
-        const ext = filePath.split('.').pop()
-        const mimeTypes = { html: 'text/html', js: 'application/javascript', css: 'text/css', svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg' }
-        res.setHeader('Content-Type', mimeTypes[ext] || 'application/octet-stream')
-        res.writeHead(200)
-        res.end(readFileSync(filePath))
-        return
-      }
-      if (existsSync(indexPath)) {
-        res.setHeader('Content-Type', 'text/html')
-        res.writeHead(200)
-        res.end(readFileSync(indexPath, 'utf8'))
-        return
-      }
-    }
-
-    res.writeHead(404)
-    res.end('Not found')
-  })
-
-  wss = new WebSocketServer({ server })
-
-  wss.on('error', (err) => {
-    console.error('WebSocket server error:', err)
-  })
-
-  wss.on('connection', (ws) => {
-    console.log('WebSocket client connected')
-
-    // Send initial projects list
-    discoverProjects().then(projects => {
-      const projectsWithState = projects.map(p => ({
-        ...p,
-        state: parseProjectState(p.path),
-        overview: parseProjectOverview(p.path)
-      }))
-
-      ws.send(JSON.stringify({
-        type: 'projects:init',
-        data: projectsWithState
-      }))
-
-      // Start watching progress files for all discovered projects
-      for (const p of projectsWithState) {
-        startProgressWatch(p.path)
-      }
-
-      // Send current scan paths
-      ws.send(JSON.stringify({
-        type: 'scan:paths',
-        data: getCustomScanPaths()
-      }))
-    }).catch(err => {
-      console.error('Error sending initial projects:', err)
-    })
-
-    ws.on('message', (message) => {
-      try {
-        const data = JSON.parse(message)
-
-        switch (data.type) {
-          case 'cli:execute':
-            handleCliExecute(ws, data.data)
-            break
-          case 'cli:kill':
-            const kill = activeProcesses.get(data.data.projectName)
-            if (kill) {
-              kill()
-              activeProcesses.delete(data.data.projectName)
-              broadcast({ type: 'cli:killed', data: { projectName: data.data.projectName } })
-            }
-            break
-          case 'scan:add-path':
-            if (data.data?.path) {
-              addCustomScanPath(data.data.path)
-              broadcast({ type: 'scan:paths', data: getCustomScanPaths() })
-              // Resend projects after scan
-              discoverProjects().then(projects => {
-                broadcast({
-                  type: 'projects:updated',
-                  data: projects.map(p => ({ ...p, state: parseProjectState(p.path) }))
-                })
-              })
-            }
-            break
-          case 'scan:remove-path':
-            if (data.data?.path) {
-              removeCustomScanPath(data.data.path)
-              ws.send(JSON.stringify({ type: 'scan:paths', data: getCustomScanPaths() }))
-            }
-            break
-          case 'scan:get-paths':
-            ws.send(JSON.stringify({ type: 'scan:paths', data: getCustomScanPaths() }))
-            break
-          case 'docs:get':
-            if (data.data?.projectPath) {
-              const docs = parseDocsTree(data.data.projectPath)
-              ws.send(JSON.stringify({ type: 'docs:tree', data: docs }))
-            }
-            break
-          default:
-            console.log('Unknown message type:', data.type)
-        }
-      } catch (err) {
-        console.error('Error handling message:', err)
-      }
-    })
-
-    ws.on('close', () => {
-      console.log('WebSocket client disconnected')
-      // Decrement progress watchers — we track which projects this client was watching
-      // via the initial projects:init. For simplicity, stop all that we started.
-      // (Other clients will re-start via their connection if still active)
-      for (const [path] of progressWatchers) {
-        stopProgressWatch(path)
-      }
-    })
-
-    ws.on('error', (err) => {
-      console.error('WebSocket error:', err)
-    })
-  })
-
-  try {
-    startWatcher((projects) => {
-      broadcast({ type: 'projects:updated', data: projects })
-    })
-  } catch (err) {
-    console.error('Failed to start file watcher:', err)
-  }
-
-  server.listen(port, () => {
-    console.log(`Dashboard server running on http://localhost:${port}`)
-    if (openBrowser) {
-      open(`http://localhost:${port}`)
-    }
-  })
-
-  const shutdown = () => {
-    stopWatcher()
-    activeProcesses.forEach(kill => kill())
-    activeProcesses.clear()
-    server.close()
-  }
-
-  process.on('SIGTERM', shutdown)
-  process.on('SIGINT', shutdown)
-
-  return server
-}
-
-export { startServer, broadcast, discoverProjects }
+import { createServer } from 'http'
+import { WebSocketServer } from 'ws'
+import { existsSync, readFileSync, readdirSync, realpathSync, watch } from 'fs'
+import { join, dirname, basename, sep, resolve, relative } from 'path'
+import { fileURLToPath } from 'url'
+import { homedir } from 'os'
+import open from 'open'
+import { parseProjectState, parseSillyspecDocsTree, parseProjectOverview, parseGitDetail, parseTechStackDetail } from './parser.js'
+import { startWatcher, stopWatcher, addCustomScanPath, removeCustomScanPath, getCustomScanPaths, customScanPaths } from './watcher.js'
+import { executeCommand } from './executor.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// WebSocket clients and active processes
+let wss = null
+const activeProcesses = new Map()
+const allowedStages = new Set(['brainstorm', 'plan', 'execute', 'verify', 'scan', 'quick', 'explore', 'archive', 'status', 'doctor', 'auto'])
+
+function isAllowedCliCommand(command) {
+  const args = String(command || '').trim().split(/\s+/).filter(Boolean)
+  if (args.length === 0) return false
+  if (args[0] === 'run') {
+    if (!allowedStages.has(args[1])) return false
+    const allowedFlags = new Set(['--status', '--reset', '--done', '--skip', '--output', '--input', '--change'])
+    for (let i = 2; i < args.length; i++) {
+      if (args[i].startsWith('-') && !allowedFlags.has(args[i])) return false
+      if (['--output', '--input', '--change'].includes(args[i])) i++
+    }
+    return true
+  }
+  if (args[0] === 'progress') {
+    const sub = args[1]
+    if (!['show', 'status', 'validate', 'reset'].includes(sub)) return false
+    for (let i = 2; i < args.length; i++) {
+      if (!['--stage', '--deep'].includes(args[i])) return false
+      if (args[i] === '--stage') i++
+    }
+    return true
+  }
+  return false
+}
+
+// Progress file watchers: projectPath -> { watcher, timer, refCount }
+const progressWatchers = new Map()
+
+function startProgressWatch(projectPath) {
+  if (progressWatchers.has(projectPath)) {
+    progressWatchers.get(projectPath).refCount++
+    return
+  }
+  // Watch the SQLite database file for changes (replaces old progress.json watch)
+  const dbFile = join(projectPath, '.sillyspec', '.runtime', 'sillyspec.db')
+  if (!existsSync(dbFile)) return
+
+  let timer = null
+  try {
+    const watcher = watch(dbFile, (eventType) => {
+      if (timer) clearTimeout(timer)
+      timer = setTimeout(() => {
+        timer = null
+        try {
+          const state = parseProjectState(projectPath)
+          broadcast({ type: 'project:update', data: { path: projectPath, state } })
+        } catch {}
+      }, 200)
+    })
+    progressWatchers.set(projectPath, { watcher, timer, refCount: 1 })
+  } catch {}
+}
+
+function stopProgressWatch(projectPath) {
+  const entry = progressWatchers.get(projectPath)
+  if (!entry) return
+  entry.refCount--
+  if (entry.refCount <= 0) {
+    entry.watcher.close()
+    if (entry.timer) clearTimeout(entry.timer)
+    progressWatchers.delete(projectPath)
+  }
+}
+
+/**
+ * Broadcast message to all connected WebSocket clients
+ * @param {object} data - Data to broadcast
+ */
+function broadcast(data) {
+  if (!wss) return
+  const message = JSON.stringify(data)
+  wss.clients.forEach(client => {
+    if (client.readyState === 1) { // OPEN
+      client.send(message)
+    }
+  })
+}
+
+function isInside(parent, child) {
+  const rel = relative(resolve(parent), resolve(child))
+  return rel === '' || (!!rel && !rel.startsWith('..') && !rel.includes(`..${sep}`))
+}
+
+function isSillyspecPath(filePath) {
+  const parts = resolve(filePath).split(/[\\/]+/)
+  return parts.includes('.sillyspec')
+}
+
+function isViewableDocPath(filePath) {
+  return /\.(md|markdown|mdx|html?|txt|log|json|ya?ml|toml|xml|csv)$/i.test(filePath)
+}
+
+function isLocalOrigin(origin) {
+  if (!origin) return true
+  try {
+    const { hostname } = new URL(origin)
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1'
+  } catch {
+    return false
+  }
+}
+
+// --- Shared scan logic (aligned with watcher.js) ---
+
+const excludeDirs = new Set([
+  '.Trash', '.cache', '.npm', '.local', '.vscode', 'Library',
+  '.git', 'node_modules', '.Trash-*', '.DS_Store', '.config',
+  '.cocoapods', '.gem', '.rvm', '.nvm', '.asdf', '.brew',
+  'AppData', 'Application Data', '.cargo', '.rustup',
+  '.nuget', '.android', '.gradle', '.m2', '.vscode-server'
+])
+
+function shouldExclude(name, cwd) {
+  if (excludeDirs.has(name)) return true
+  for (const pattern of excludeDirs) {
+    if (pattern.includes('*')) {
+      const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$')
+      if (regex.test(name)) return true
+    }
+  }
+  const cwdName = cwd.split(sep).pop() || cwd.split('/').pop() || ''
+  if (name.startsWith('.') && name !== cwdName) return true
+  return false
+}
+
+function scanDirectory(baseDir, seen, maxDepth = 2, currentDepth = 0) {
+  const cwd = process.cwd()
+  const projects = []
+  try {
+    const entries = readdirSync(baseDir, { withFileTypes: true })
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      if (shouldExclude(entry.name, cwd)) continue
+      const dirPath = join(baseDir, entry.name)
+      let realPath
+      try { realPath = realpathSync(dirPath) } catch { realPath = dirPath }
+      const normalizedPath = realPath.toLowerCase()
+      if (seen.has(normalizedPath)) continue
+      seen.add(normalizedPath)
+      if (existsSync(join(dirPath, '.sillyspec'))) {
+        projects.push({ name: entry.name, path: dirPath })
+      }
+      if (currentDepth < maxDepth) {
+        projects.push(...scanDirectory(dirPath, seen, maxDepth, currentDepth + 1))
+      }
+    }
+  } catch (err) {}
+  return projects
+}
+
+/**
+ * Discover all SillySpec projects
+ * @returns {Promise<Array>} Array of project objects
+ */
+async function discoverProjects() {
+  const home = homedir()
+  const cwd = process.cwd()
+
+  const scanDirs = new Set()
+  scanDirs.add(cwd)
+  scanDirs.add(dirname(cwd))
+  scanDirs.add(dirname(dirname(cwd)))
+  scanDirs.add(home)
+
+  const extraDirs = [
+    'Desktop', '桌面', 'Documents', '文档', 'Downloads', '下载',
+    'Projects', '项目', 'Work', '工作', 'Repos', 'Code', 'src', 'dev',
+    'workspace', '工作区'
+  ]
+
+  for (const extra of extraDirs) {
+    const extraPath = join(home, extra)
+    if (existsSync(extraPath)) scanDirs.add(extraPath)
+  }
+
+  for (const customPath of customScanPaths) {
+    if (existsSync(customPath)) scanDirs.add(customPath)
+  }
+
+  const seen = new Set()
+  const projects = []
+
+  // Normalize cwd for dedup
+  let cwdReal
+  try { cwdReal = realpathSync(cwd) } catch { cwdReal = cwd }
+  seen.add(cwdReal.toLowerCase())
+  if (existsSync(join(cwd, '.sillyspec'))) {
+    projects.push({ name: basename(cwd), path: cwd })
+  }
+
+  for (const baseDir of scanDirs) {
+    projects.push(...scanDirectory(baseDir, seen, 2, 0))
+  }
+
+  return projects
+}
+
+/**
+ * Handle WebSocket message for CLI execution
+ * @param {object} ws - WebSocket client
+ * @param {object} data - Message data
+ */
+function handleCliExecute(ws, data) {
+  const { projectName, command } = data
+
+  if (!projectName || !command) {
+    ws.send(JSON.stringify({
+      type: 'cli:error',
+      data: { message: 'Missing projectName or command' }
+    }))
+    return
+  }
+
+  if (!isAllowedCliCommand(command)) {
+    ws.send(JSON.stringify({
+      type: 'cli:error',
+      data: { message: `Command not allowed: ${command}` }
+    }))
+    return
+  }
+
+  discoverProjects().then(projects => {
+    const project = projects.find(p => p.name === projectName)
+    if (!project) {
+      ws.send(JSON.stringify({
+        type: 'cli:error',
+        data: { message: `Project not found: ${projectName}` }
+      }))
+      return
+    }
+
+    const existingKill = activeProcesses.get(projectName)
+    if (existingKill) existingKill()
+
+    const kill = executeCommand(
+      project.path,
+      command,
+      (output) => {
+        broadcast({
+          type: 'cli:output',
+          data: { projectName, output: output.data, outputType: output.type }
+        })
+      },
+      (result) => {
+        activeProcesses.delete(projectName)
+        broadcast({
+          type: 'cli:complete',
+          data: { projectName, exitCode: result.code, signal: result.signal }
+        })
+      }
+    )
+
+    activeProcesses.set(projectName, kill)
+    broadcast({ type: 'cli:started', data: { projectName, command } })
+  })
+}
+
+/**
+ * Start the dashboard server
+ * @param {object} options - Server options
+ * @returns {object} HTTP server instance
+ */
+function startServer({ port = 3456, open: openBrowser = true } = {}) {
+  const server = createServer((req, res) => {
+    const origin = req.headers.origin
+    if (!isLocalOrigin(origin)) {
+      res.writeHead(403)
+      res.end('Forbidden')
+      return
+    }
+    res.setHeader('Access-Control-Allow-Origin', origin || `http://127.0.0.1:${port}`)
+    res.setHeader('Vary', 'Origin')
+    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS')
+    res.setHeader('Access-Control-Allow-Headers', 'Content-Type')
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(200)
+      res.end()
+      return
+    }
+
+    if (req.url === '/api/projects') {
+      discoverProjects().then(projects => {
+        res.setHeader('Content-Type', 'application/json')
+        res.writeHead(200)
+        res.end(JSON.stringify(projects))
+      }).catch(err => {
+        res.writeHead(500)
+        res.end(JSON.stringify({ error: err.message }))
+      })
+      return
+    }
+
+    // Detail API
+    const detailMatch = req.url?.match(/^\/api\/projects\/(.+)\/detail(\?|$)/)
+    if (detailMatch) {
+      const projectPath = decodeURIComponent(detailMatch[1])
+      const url = new URL(req.url, `http://${req.headers.host}`)
+      const type = url.searchParams.get('type')
+      let data
+      try {
+        if (type === 'git') data = parseGitDetail(projectPath)
+        else if (type === 'tech') data = parseTechStackDetail(projectPath)
+        else if (type === 'docs') data = parseSillyspecDocsTree(projectPath).groups
+        else { res.writeHead(400); res.end(JSON.stringify({ error: 'Invalid type' })); return }
+        res.setHeader('Content-Type', 'application/json')
+        res.writeHead(200)
+        res.end(JSON.stringify(data))
+      } catch (err) {
+        res.writeHead(500)
+        res.end(JSON.stringify({ error: err.message }))
+      }
+      return
+    }
+
+    // Overview API
+    if (req.url?.startsWith('/api/projects/') && req.url.endsWith('/overview')) {
+      const parts = req.url.replace('/api/projects/', '').replace('/overview', '').split('/')
+      const projectPath = decodeURIComponent(parts.join('/'))
+      try {
+        const overview = parseProjectOverview(projectPath)
+        res.setHeader('Content-Type', 'application/json')
+        res.writeHead(200)
+        res.end(JSON.stringify(overview))
+      } catch (err) {
+        res.writeHead(500)
+        res.end(JSON.stringify({ error: err.message }))
+      }
+      return
+    }
+
+    if (req.url?.startsWith('/api/project/')) {
+      const projectName = decodeURIComponent(req.url.split('/').pop())
+      discoverProjects().then(projects => {
+        const project = projects.find(p => p.name === projectName)
+        if (project) {
+          const state = parseProjectState(project.path)
+          res.setHeader('Content-Type', 'application/json')
+          res.writeHead(200)
+          res.end(JSON.stringify({ ...project, state }))
+        } else {
+          res.writeHead(404)
+          res.end(JSON.stringify({ error: 'Project not found' }))
+        }
+      }).catch(err => {
+        res.writeHead(500)
+        res.end(JSON.stringify({ error: err.message }))
+      })
+      return
+    }
+
+    // Docs API
+    if (req.url?.startsWith('/api/docs/content')) {
+      const url = new URL(req.url, `http://${req.headers.host}`)
+      const filePath = url.searchParams.get('path')
+      if (!filePath) {
+        res.writeHead(400)
+        res.end(JSON.stringify({ error: 'Missing path parameter' }))
+        return
+      }
+      // Security: only allow reading viewable text documents under a .sillyspec tree.
+      const normalizedPath = resolve(filePath)
+      if (!isSillyspecPath(normalizedPath) || !isViewableDocPath(normalizedPath)) {
+        res.writeHead(403)
+        res.end(JSON.stringify({ error: 'Access denied' }))
+        return
+      }
+      if (existsSync(normalizedPath)) {
+        try {
+          const content = readFileSync(normalizedPath, 'utf-8')
+          res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+          res.writeHead(200)
+          res.end(content)
+        } catch (err) {
+          res.writeHead(500)
+          res.end(JSON.stringify({ error: err.message }))
+        }
+      } else {
+        res.writeHead(404)
+        res.end(JSON.stringify({ error: 'File not found' }))
+      }
+      return
+    }
+
+    if (req.url?.startsWith('/api/docs')) {
+      const url = new URL(req.url, `http://${req.headers.host}`)
+      const projectPath = url.searchParams.get('project')
+      if (!projectPath) {
+        res.writeHead(400)
+        res.end(JSON.stringify({ error: 'Missing project parameter' }))
+        return
+      }
+      const docs = parseSillyspecDocsTree(projectPath)
+      res.setHeader('Content-Type', 'application/json')
+      res.writeHead(200)
+      res.end(JSON.stringify(docs))
+      return
+    }
+
+    // Serve static files (dist/)
+    const distDir = join(__dirname, '../dist')
+    const indexPath = join(distDir, 'index.html')
+    if (existsSync(distDir)) {
+      const url = new URL(req.url || '/', `http://${req.headers.host}`)
+      const requestPath = decodeURIComponent(url.pathname)
+      const filePath = resolve(distDir, requestPath === '/' ? 'index.html' : `.${requestPath}`)
+      if (!isInside(distDir, filePath)) {
+        res.writeHead(403)
+        res.end('Access denied')
+        return
+      }
+      if (existsSync(filePath)) {
+        const ext = filePath.split('.').pop()
+        const mimeTypes = { html: 'text/html', js: 'application/javascript', css: 'text/css', svg: 'image/svg+xml', png: 'image/png', jpg: 'image/jpeg' }
+        res.setHeader('Content-Type', mimeTypes[ext] || 'application/octet-stream')
+        res.writeHead(200)
+        res.end(readFileSync(filePath))
+        return
+      }
+      if (existsSync(indexPath)) {
+        res.setHeader('Content-Type', 'text/html')
+        res.writeHead(200)
+        res.end(readFileSync(indexPath, 'utf8'))
+        return
+      }
+    }
+
+    res.writeHead(404)
+    res.end('Not found')
+  })
+
+  wss = new WebSocketServer({ server })
+
+  wss.on('error', (err) => {
+    console.error('WebSocket server error:', err)
+  })
+
+  wss.on('connection', (ws, req) => {
+    if (!isLocalOrigin(req.headers.origin)) {
+      ws.close(1008, 'Forbidden origin')
+      return
+    }
+    console.log('WebSocket client connected')
+
+    // Send initial projects list
+    discoverProjects().then(projects => {
+      const projectsWithState = projects.map(p => ({
+        ...p,
+        state: parseProjectState(p.path),
+        overview: parseProjectOverview(p.path)
+      }))
+
+      ws.send(JSON.stringify({
+        type: 'projects:init',
+        data: projectsWithState
+      }))
+
+      // Start watching progress files for all discovered projects
+      for (const p of projectsWithState) {
+        startProgressWatch(p.path)
+      }
+
+      // Send current scan paths
+      ws.send(JSON.stringify({
+        type: 'scan:paths',
+        data: getCustomScanPaths()
+      }))
+    }).catch(err => {
+      console.error('Error sending initial projects:', err)
+    })
+
+    ws.on('message', (message) => {
+      try {
+        const data = JSON.parse(message)
+
+        switch (data.type) {
+          case 'cli:execute':
+            handleCliExecute(ws, data.data)
+            break
+          case 'cli:kill':
+            const kill = activeProcesses.get(data.data.projectName)
+            if (kill) {
+              kill()
+              activeProcesses.delete(data.data.projectName)
+              broadcast({ type: 'cli:killed', data: { projectName: data.data.projectName } })
+            }
+            break
+          case 'scan:add-path':
+            if (data.data?.path) {
+              addCustomScanPath(data.data.path)
+              broadcast({ type: 'scan:paths', data: getCustomScanPaths() })
+              // Resend projects after scan
+              discoverProjects().then(projects => {
+                broadcast({
+                  type: 'projects:updated',
+                  data: projects.map(p => ({
+                    ...p,
+                    state: parseProjectState(p.path),
+                    overview: parseProjectOverview(p.path)
+                  }))
+                })
+              })
+            }
+            break
+          case 'scan:remove-path':
+            if (data.data?.path) {
+              removeCustomScanPath(data.data.path)
+              ws.send(JSON.stringify({ type: 'scan:paths', data: getCustomScanPaths() }))
+            }
+            break
+          case 'scan:get-paths':
+            ws.send(JSON.stringify({ type: 'scan:paths', data: getCustomScanPaths() }))
+            break
+          case 'docs:get':
+            if (data.data?.projectPath) {
+              const docs = parseSillyspecDocsTree(data.data.projectPath)
+              ws.send(JSON.stringify({ type: 'docs:tree', data: docs }))
+            }
+            break
+          default:
+            console.log('Unknown message type:', data.type)
+        }
+      } catch (err) {
+        console.error('Error handling message:', err)
+      }
+    })
+
+    ws.on('close', () => {
+      console.log('WebSocket client disconnected')
+      // Decrement progress watchers — we track which projects this client was watching
+      // via the initial projects:init. For simplicity, stop all that we started.
+      // (Other clients will re-start via their connection if still active)
+      for (const [path] of progressWatchers) {
+        stopProgressWatch(path)
+      }
+    })
+
+    ws.on('error', (err) => {
+      console.error('WebSocket error:', err)
+    })
+  })
+
+  try {
+    startWatcher((projects) => {
+      broadcast({ type: 'projects:updated', data: projects })
+    })
+  } catch (err) {
+    console.error('Failed to start file watcher:', err)
+  }
+
+  server.listen(port, '127.0.0.1', () => {
+    console.log(`Dashboard server running on http://127.0.0.1:${port}`)
+    if (openBrowser) {
+      open(`http://127.0.0.1:${port}`)
+    }
+  })
+
+  const shutdown = () => {
+    stopWatcher()
+    activeProcesses.forEach(kill => kill())
+    activeProcesses.clear()
+    server.close()
+  }
+
+  process.on('SIGTERM', shutdown)
+  process.on('SIGINT', shutdown)
+
+  return server
+}
+
+export { startServer, broadcast, discoverProjects }