bmad-studio 0.1.0

package/packages/server/src/core/project-detector.test.ts

@@ -0,0 +1,94 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { detectProject } from './project-detector.js'
+
+describe('project-detector', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'detect-test-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('detects project with _bmad/ and module config', () => {
+    const bmadDir = path.join(tmpDir, '_bmad', 'core')
+    fs.mkdirSync(bmadDir, { recursive: true })
+    fs.writeFileSync(path.join(bmadDir, 'config.yaml'), 'user_name: Test\n')
+
+    const result = detectProject(tmpDir)
+    expect(result).not.toBeNull()
+    expect(result!.projectRoot).toBe(tmpDir)
+  })
+
+  it('reads manifest for version and modules', () => {
+    const bmadDir = path.join(tmpDir, '_bmad')
+    const coreDir = path.join(bmadDir, 'core')
+    const configDir = path.join(bmadDir, '_config')
+    fs.mkdirSync(coreDir, { recursive: true })
+    fs.mkdirSync(configDir, { recursive: true })
+    fs.writeFileSync(path.join(coreDir, 'config.yaml'), 'user_name: Test\n')
+    fs.writeFileSync(
+      path.join(configDir, 'manifest.yaml'),
+      `installation:\n  version: 6.2.0\nmodules:\n  - name: core\n    version: 6.2.0\n    source: built-in\nides:\n  - claude-code\n`,
+    )
+
+    const result = detectProject(tmpDir)
+    expect(result).not.toBeNull()
+    expect(result!.bmadVersion).toBe('6.2.0')
+    expect(result!.versionSupported).toBe(true)
+    expect(result!.modules).toHaveLength(1)
+    expect(result!.modules[0].name).toBe('core')
+    expect(result!.ideDirectories).toEqual(['claude-code'])
+  })
+
+  it('scans upward from subdirectory', () => {
+    const bmadDir = path.join(tmpDir, '_bmad', 'core')
+    fs.mkdirSync(bmadDir, { recursive: true })
+    fs.writeFileSync(path.join(bmadDir, 'config.yaml'), 'user_name: Test\n')
+
+    const subDir = path.join(tmpDir, 'deep', 'nested', 'dir')
+    fs.mkdirSync(subDir, { recursive: true })
+
+    const result = detectProject(subDir)
+    expect(result).not.toBeNull()
+    expect(result!.projectRoot).toBe(tmpDir)
+  })
+
+  it('returns null when no _bmad/ found', () => {
+    const result = detectProject(tmpDir)
+    expect(result).toBeNull()
+  })
+
+  it('returns null when _bmad/ exists but no module with config', () => {
+    const bmadDir = path.join(tmpDir, '_bmad')
+    fs.mkdirSync(bmadDir, { recursive: true })
+    // _bmad/ exists but no module subdirectory with config.yaml
+
+    const result = detectProject(tmpDir)
+    expect(result).toBeNull()
+  })
+
+  it('warns about unsupported version', () => {
+    const bmadDir = path.join(tmpDir, '_bmad')
+    const coreDir = path.join(bmadDir, 'core')
+    const configDir = path.join(bmadDir, '_config')
+    fs.mkdirSync(coreDir, { recursive: true })
+    fs.mkdirSync(configDir, { recursive: true })
+    fs.writeFileSync(path.join(coreDir, 'config.yaml'), 'user_name: Test\n')
+    fs.writeFileSync(
+      path.join(configDir, 'manifest.yaml'),
+      `installation:\n  version: 5.0.0\nmodules:\n  - name: core\n    version: 5.0.0\n    source: built-in\n`,
+    )
+
+    const result = detectProject(tmpDir)
+    expect(result).not.toBeNull()
+    expect(result!.bmadVersion).toBe('5.0.0')
+    expect(result!.versionSupported).toBe(false)
+  })
+})

package/packages/server/src/core/project-detector.ts

@@ -0,0 +1,97 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import yaml from 'js-yaml'
+
+const SUPPORTED_VERSIONS = ['6']
+
+export type DetectedModule = {
+  name: string
+  version: string
+  source: string
+}
+
+export type ProjectDetectionResult = {
+  projectRoot: string
+  bmadVersion: string | null
+  versionSupported: boolean
+  modules: DetectedModule[]
+  ideDirectories: string[]
+}
+
+function readManifest(bmadDir: string): {
+  version: string | null
+  modules: DetectedModule[]
+  ides: string[]
+} {
+  const manifestPath = path.join(bmadDir, '_config', 'manifest.yaml')
+  if (!fs.existsSync(manifestPath)) {
+    return { version: null, modules: [], ides: [] }
+  }
+
+  try {
+    const content = fs.readFileSync(manifestPath, 'utf-8')
+    const manifest = yaml.load(content) as Record<string, unknown>
+
+    const installation = manifest.installation as Record<string, unknown> | undefined
+    const version = installation?.version as string | undefined
+
+    const rawModules = (manifest.modules as Array<Record<string, unknown>>) || []
+    const modules: DetectedModule[] = rawModules.map((m) => ({
+      name: (m.name as string) || '',
+      version: (m.version as string) || '',
+      source: (m.source as string) || 'unknown',
+    }))
+
+    const ides = (manifest.ides as string[]) || []
+
+    return { version: version ?? null, modules, ides }
+  } catch {
+    return { version: null, modules: [], ides: [] }
+  }
+}
+
+function hasModuleWithConfig(bmadDir: string): boolean {
+  if (!fs.existsSync(bmadDir)) return false
+
+  const entries = fs.readdirSync(bmadDir, { withFileTypes: true })
+  for (const entry of entries) {
+    if (entry.isDirectory() && !entry.name.startsWith('_') && !entry.name.startsWith('.')) {
+      const configPath = path.join(bmadDir, entry.name, 'config.yaml')
+      if (fs.existsSync(configPath)) return true
+    }
+  }
+  return false
+}
+
+export function detectProject(startDir: string): ProjectDetectionResult | null {
+  let currentDir = path.resolve(startDir)
+  const root = path.parse(currentDir).root
+
+  while (currentDir !== root) {
+    const bmadDir = path.join(currentDir, '_bmad')
+
+    if (fs.existsSync(bmadDir) && fs.statSync(bmadDir).isDirectory()) {
+      if (hasModuleWithConfig(bmadDir)) {
+        const { version, modules, ides } = readManifest(bmadDir)
+
+        const majorVersion = version?.split('.')[0] ?? null
+        const versionSupported = majorVersion !== null && SUPPORTED_VERSIONS.includes(majorVersion)
+
+        return {
+          projectRoot: currentDir,
+          bmadVersion: version,
+          versionSupported,
+          modules,
+          ideDirectories: ides,
+        }
+      }
+    }
+
+    const parentDir = path.dirname(currentDir)
+    if (parentDir === currentDir) break
+    currentDir = parentDir
+  }
+
+  return null
+}

package/packages/server/src/core/websocket.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest'
+
+import type { WebSocketEvent } from '@bmad-studio/shared'
+
+import { WebSocketManager } from './websocket.js'
+
+function createMockSocket(readyState = 1) {
+  const sent: string[] = []
+  const handlers: Record<string, Array<() => void>> = {}
+  return {
+    readyState,
+    send: (data: string) => sent.push(data),
+    on: (event: string, handler: () => void) => {
+      handlers[event] = handlers[event] || []
+      handlers[event].push(handler)
+    },
+    triggerClose: () => handlers['close']?.forEach((h) => h()),
+    sent,
+  }
+}
+
+describe('WebSocketManager', () => {
+  it('tracks connected clients', () => {
+    const manager = new WebSocketManager()
+    const socket = createMockSocket()
+    manager.addClient(socket as never)
+
+    expect(manager.clientCount).toBe(1)
+  })
+
+  it('removes client on close', () => {
+    const manager = new WebSocketManager()
+    const socket = createMockSocket()
+    manager.addClient(socket as never)
+    socket.triggerClose()
+
+    expect(manager.clientCount).toBe(0)
+  })
+
+  it('broadcasts event to all connected clients', () => {
+    const manager = new WebSocketManager()
+    const socket1 = createMockSocket()
+    const socket2 = createMockSocket()
+    manager.addClient(socket1 as never)
+    manager.addClient(socket2 as never)
+
+    const event: WebSocketEvent = { type: 'file:changed', path: '/test.yaml', category: 'agent' }
+    manager.broadcast(event)
+
+    expect(socket1.sent).toHaveLength(1)
+    expect(JSON.parse(socket1.sent[0])).toEqual(event)
+    expect(socket2.sent).toHaveLength(1)
+  })
+
+  it('skips clients that are not in OPEN state', () => {
+    const manager = new WebSocketManager()
+    const openSocket = createMockSocket(1)
+    const closedSocket = createMockSocket(3) // CLOSED
+    manager.addClient(openSocket as never)
+    manager.addClient(closedSocket as never)
+
+    manager.broadcast({ type: 'project:reloaded' })
+
+    expect(openSocket.sent).toHaveLength(1)
+    expect(closedSocket.sent).toHaveLength(0)
+  })
+
+  it('broadcasts compile:needed with agent names', () => {
+    const manager = new WebSocketManager()
+    const socket = createMockSocket()
+    manager.addClient(socket as never)
+
+    const event: WebSocketEvent = { type: 'compile:needed', agents: ['pm', 'analyst'] }
+    manager.broadcast(event)
+
+    const received = JSON.parse(socket.sent[0])
+    expect(received.type).toBe('compile:needed')
+    expect(received.agents).toEqual(['pm', 'analyst'])
+  })
+})

package/packages/server/src/core/websocket.ts

@@ -0,0 +1,47 @@
+import websocket from '@fastify/websocket'
+
+import type { FastifyInstance } from 'fastify'
+import type { WebSocket } from 'ws'
+import type { WebSocketEvent } from '@bmad-studio/shared'
+
+export class WebSocketManager {
+  private clients = new Set<WebSocket>()
+
+  addClient(socket: WebSocket) {
+    this.clients.add(socket)
+    socket.on('close', () => {
+      this.clients.delete(socket)
+    })
+  }
+
+  broadcast(event: WebSocketEvent) {
+    const data = JSON.stringify(event)
+    for (const client of this.clients) {
+      if (client.readyState === 1) {
+        client.send(data)
+      }
+    }
+  }
+
+  get clientCount() {
+    return this.clients.size
+  }
+}
+
+export async function registerWebSocket(app: FastifyInstance) {
+  const manager = new WebSocketManager()
+
+  await app.register(websocket)
+
+  app.get('/ws', { websocket: true }, (socket) => {
+    manager.addClient(socket)
+  })
+
+  app.decorate('ws', manager)
+}
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    ws: WebSocketManager
+  }
+}

package/packages/server/src/core/write-service.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { writeFile, getHistory } from './write-service.js'
+
+describe('write-service', () => {
+  let tmpDir: string
+  let studioDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'write-test-'))
+    studioDir = path.join(tmpDir, '.bmad-studio')
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('writes a new file atomically', () => {
+    const filePath = path.join(tmpDir, 'test.md')
+    const result = writeFile(filePath, 'hello world', studioDir)
+
+    expect(result.ok).toBe(true)
+    expect(fs.readFileSync(filePath, 'utf-8')).toBe('hello world')
+  })
+
+  it('creates snapshot before overwriting existing file', () => {
+    const filePath = path.join(tmpDir, 'test.md')
+    fs.writeFileSync(filePath, 'original content')
+
+    const result = writeFile(filePath, 'new content', studioDir)
+
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.snapshotPath).not.toBeNull()
+      expect(fs.readFileSync(result.snapshotPath!, 'utf-8')).toBe('original content')
+    }
+    expect(fs.readFileSync(filePath, 'utf-8')).toBe('new content')
+  })
+
+  it('does not create snapshot for new files', () => {
+    const filePath = path.join(tmpDir, 'brand-new.md')
+    const result = writeFile(filePath, 'content', studioDir)
+
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.snapshotPath).toBeNull()
+    }
+  })
+
+  it('prunes history when exceeding 50 snapshots', () => {
+    const historyDir = path.join(studioDir, 'history')
+    fs.mkdirSync(historyDir, { recursive: true })
+
+    // Create 52 existing snapshots
+    for (let i = 0; i < 52; i++) {
+      fs.writeFileSync(path.join(historyDir, `${1000 + i}-old.md`), `snapshot ${i}`)
+    }
+
+    const filePath = path.join(tmpDir, 'test.md')
+    fs.writeFileSync(filePath, 'existing')
+    writeFile(filePath, 'updated', studioDir)
+
+    const remaining = fs.readdirSync(historyDir)
+    expect(remaining.length).toBeLessThanOrEqual(50)
+  })
+
+  it('getHistory returns sorted list of snapshots', () => {
+    const historyDir = path.join(studioDir, 'history')
+    fs.mkdirSync(historyDir, { recursive: true })
+    fs.writeFileSync(path.join(historyDir, '1000-a.md'), 'a')
+    fs.writeFileSync(path.join(historyDir, '2000-b.md'), 'b')
+
+    const history = getHistory(studioDir)
+    expect(history).toEqual(['2000-b.md', '1000-a.md'])
+  })
+
+  it('returns error on write to invalid path', () => {
+    const filePath = path.join(tmpDir, 'nonexistent', 'deep', 'nested', 'file.md')
+    const result = writeFile(filePath, 'content', studioDir)
+
+    expect(result.ok).toBe(true) // ensureDir creates parents
+    expect(fs.readFileSync(filePath, 'utf-8')).toBe('content')
+  })
+})

package/packages/server/src/core/write-service.ts

@@ -0,0 +1,75 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const HISTORY_CAP = 50
+
+function ensureDir(dir: string) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true })
+  }
+}
+
+function pruneHistory(historyDir: string) {
+  if (!fs.existsSync(historyDir)) return
+
+  const files = fs.readdirSync(historyDir).sort()
+
+  while (files.length > HISTORY_CAP) {
+    const oldest = files.shift()!
+    fs.unlinkSync(path.join(historyDir, oldest))
+  }
+}
+
+export type WriteResult =
+  | { ok: true; filePath: string; snapshotPath: string | null }
+  | { ok: false; error: string; filePath: string }
+
+export function writeFile(filePath: string, content: string, studioDir: string): WriteResult {
+  const historyDir = path.join(studioDir, 'history')
+  let snapshotPath: string | null = null
+
+  try {
+    // Step 1: Read current file for snapshot (if exists)
+    let previousContent: string | null = null
+    if (fs.existsSync(filePath)) {
+      previousContent = fs.readFileSync(filePath, 'utf-8')
+    }
+
+    // Step 2: Snapshot to history
+    if (previousContent !== null) {
+      ensureDir(historyDir)
+      const timestamp = Date.now()
+      const basename = path.basename(filePath)
+      snapshotPath = path.join(historyDir, `${timestamp}-${basename}`)
+      fs.writeFileSync(snapshotPath, previousContent, 'utf-8')
+    }
+
+    // Step 3: Write to temp file
+    const tmpPath = `${filePath}.tmp`
+    ensureDir(path.dirname(filePath))
+    fs.writeFileSync(tmpPath, content, 'utf-8')
+
+    // Step 4: Atomic rename
+    fs.renameSync(tmpPath, filePath)
+
+    // Step 5: Verify
+    const written = fs.readFileSync(filePath, 'utf-8')
+    if (written !== content) {
+      return { ok: false, error: 'Write verification failed: content mismatch', filePath }
+    }
+
+    // Step 6: Prune history
+    pruneHistory(historyDir)
+
+    return { ok: true, filePath, snapshotPath }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    return { ok: false, error: `Write failed: ${message}`, filePath }
+  }
+}
+
+export function getHistory(studioDir: string): string[] {
+  const historyDir = path.join(studioDir, 'history')
+  if (!fs.existsSync(historyDir)) return []
+  return fs.readdirSync(historyDir).sort().reverse()
+}

package/packages/server/src/index.ts

@@ -0,0 +1,97 @@
+import fs from 'node:fs'
+
+import { createApp } from './app.js'
+import { detectProject } from './core/project-detector.js'
+
+const DEFAULT_PORT = 4040
+const MAX_PORT_RETRIES = 10
+
+function parseArgs(args: string[]) {
+  let port = DEFAULT_PORT
+  let dir: string | undefined
+  let verbose = false
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--port') {
+      if (!args[i + 1]) {
+        console.error('Error: --port requires a value')
+        process.exit(1)
+      }
+      const parsed = parseInt(args[i + 1], 10)
+      if (Number.isNaN(parsed) || parsed < 1 || parsed > 65535) {
+        console.error(`Error: invalid port "${args[i + 1]}" (must be 1-65535)`)
+        process.exit(1)
+      }
+      port = parsed
+      i++
+    } else if (args[i] === '--dir') {
+      if (!args[i + 1]) {
+        console.error('Error: --dir requires a value')
+        process.exit(1)
+      }
+      dir = args[i + 1]
+      i++
+    } else if (args[i] === '--verbose') {
+      verbose = true
+    }
+  }
+
+  return { port, dir, verbose }
+}
+
+async function main() {
+  const { port, dir, verbose } = parseArgs(process.argv.slice(2))
+
+  const startDir = dir ?? process.cwd()
+  if (dir && !fs.existsSync(dir)) {
+    console.error(`Error: directory "${dir}" does not exist`)
+    process.exit(1)
+  }
+
+  // Detect BMAD project
+  const project = detectProject(startDir)
+
+  if (project) {
+    console.log(`BMAD project detected: ${project.projectRoot}`)
+    console.log(`  Version: ${project.bmadVersion ?? 'unknown'}`)
+    console.log(`  Modules: ${project.modules.map((m) => m.name).join(', ')}`)
+    if (!project.versionSupported) {
+      console.warn(
+        `  Warning: BMAD version ${project.bmadVersion} may not be fully supported. Supported: v6.x`,
+      )
+    }
+  } else {
+    console.warn('No BMAD project found. Run from project root or use --dir /path')
+    console.warn('Starting in setup mode...')
+  }
+
+  const app = await createApp({
+    logger: verbose ? { level: 'debug' } : true,
+    project,
+  })
+
+  // Listen with port auto-increment on EADDRINUSE
+  let actualPort = port
+  for (let attempt = 0; attempt < MAX_PORT_RETRIES; attempt++) {
+    try {
+      await app.listen({ port: actualPort, host: '127.0.0.1' })
+      if (actualPort !== port) {
+        console.log(`Port ${port} was in use, using ${actualPort} instead`)
+      }
+      return
+    } catch (err) {
+      const error = err as NodeJS.ErrnoException
+      if (error.code === 'EADDRINUSE' && attempt < MAX_PORT_RETRIES - 1) {
+        actualPort++
+        continue
+      }
+      app.log.error(err)
+      process.exit(1)
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('Fatal startup error:', err)
+  process.exit(1)
+})

package/packages/server/src/parsers/agent-parser.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest'
+
+import { parseAgent } from './agent-parser.js'
+
+const sampleAgent = `---
+name: "analyst"
+description: "Business Analyst"
+---
+
+You must fully embody this agent.
+
+\`\`\`xml
+<agent id="analyst.agent.yaml" name="Mary" title="Business Analyst" icon="📊" capabilities="market research, competitive analysis">
+<menu>
+  <item cmd="BP or fuzzy match on brainstorm" exec="skill:bmad-brainstorming">[BP] Brainstorm Project</item>
+  <item cmd="MR or fuzzy match on market-research" exec="skill:bmad-market-research">[MR] Market Research</item>
+</menu>
+</agent>
+\`\`\`
+`
+
+describe('agent-parser', () => {
+  it('extracts agent attributes from XML', () => {
+    const result = parseAgent('_bmad/bmm/agents/analyst.md', sampleAgent)
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.data.id).toBe('analyst')
+      expect(result.data.name).toBe('Mary')
+      expect(result.data.filePath).toBe('_bmad/bmm/agents/analyst.md')
+    }
+  })
+
+  it('extracts menu items from XML', () => {
+    const result = parseAgent('analyst.md', sampleAgent)
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.data.menu).toHaveLength(2)
+      expect(result.data.menu[0].trigger).toBe('bp')
+      expect(result.data.menu[0].route).toBe('skill:bmad-brainstorming')
+      expect(result.data.menu[0].input).toBe('Brainstorm Project')
+      expect(result.data.menu[1].trigger).toBe('mr')
+      expect(result.data.menu[1].route).toBe('skill:bmad-market-research')
+    }
+  })
+
+  it('falls back to frontmatter when XML is missing', () => {
+    const simple = `---
+name: "test-agent"
+description: "A test agent"
+---
+Just a simple agent with no XML.
+`
+    const result = parseAgent('test.md', simple)
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.data.id).toBe('test-agent')
+      expect(result.data.name).toBe('test-agent')
+      expect(result.data.role).toBe('A test agent')
+      expect(result.data.menu).toHaveLength(0)
+    }
+  })
+
+  it('handles malformed content gracefully', () => {
+    const result = parseAgent('bad.md', '')
+    expect(result.ok).toBe(true)
+    if (result.ok) {
+      expect(result.data.id).toBe('')
+      expect(result.data.menu).toHaveLength(0)
+    }
+  })
+})