bmad-studio 0.1.0

package/packages/client/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "rootDir": "src",
+    "outDir": "dist",
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/packages/client/vite.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  server: {
+    port: 5173,
+    proxy: {
+      '/api': {
+        target: 'http://localhost:4040',
+        changeOrigin: true,
+      },
+      '/ws': {
+        target: 'ws://localhost:4040',
+        ws: true,
+      },
+    },
+  },
+})

package/packages/server/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@bmad-studio/server",
+  "version": "0.1.0",
+  "description": "BMAD Studio server — Fastify API serving BMAD project data",
+  "type": "module",
+  "main": "./src/index.ts",
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@bmad-studio/shared": "*",
+    "@fastify/static": "^8.1.0",
+    "@fastify/websocket": "^11.2.0",
+    "chokidar": "^5.0.0",
+    "fastify": "^5.3.3",
+    "gray-matter": "^4.0.3",
+    "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.15.3",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.19.0"
+  },
+  "license": "MIT"
+}

package/packages/server/src/app.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { createApp } from './app.js'
+
+describe('app', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'app-test-'))
+  })
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('returns health check response', async () => {
+    const app = await createApp({ logger: false, serveStatic: false, project: null })
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/api/health',
+    })
+
+    expect(response.statusCode).toBe(200)
+    const body = JSON.parse(response.body)
+    expect(body.status).toBe('ok')
+    expect(body.name).toBe('bmad-studio')
+    expect(body.version).toBe('0.1.0')
+  })
+
+  it('returns project status when no project detected', async () => {
+    const app = await createApp({ logger: false, serveStatic: false, project: null })
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/api/project',
+    })
+
+    expect(response.statusCode).toBe(200)
+    const body = JSON.parse(response.body)
+    expect(body.detected).toBe(false)
+  })
+
+  it('returns project status when project detected', async () => {
+    // Create a real temp directory structure so file store can initialize
+    const bmadDir = path.join(tmpDir, '_bmad', 'core')
+    fs.mkdirSync(bmadDir, { recursive: true })
+    fs.writeFileSync(path.join(bmadDir, 'config.yaml'), 'user_name: Test\n')
+
+    const app = await createApp({
+      logger: false,
+      serveStatic: false,
+      project: {
+        projectRoot: tmpDir,
+        bmadVersion: '6.2.0',
+        versionSupported: true,
+        modules: [{ name: 'core', version: '6.2.0', source: 'built-in' }],
+        ideDirectories: ['claude-code'],
+      },
+    })
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/api/project',
+    })
+
+    expect(response.statusCode).toBe(200)
+    const body = JSON.parse(response.body)
+    expect(body.detected).toBe(true)
+    expect(body.bmadVersion).toBe('6.2.0')
+    expect(body.modules).toEqual(['core'])
+
+    await app.close()
+  })
+
+  it('global error handler returns JSON for AppError', async () => {
+    const app = await createApp({ logger: false, serveStatic: false, project: null })
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/api/nonexistent',
+    })
+
+    expect(response.statusCode).toBe(404)
+  })
+})

package/packages/server/src/app.ts

@@ -0,0 +1,101 @@
+import Fastify from 'fastify'
+
+import type { AppInfo, ProjectStatus } from '@bmad-studio/shared'
+import type { FastifyServerOptions } from 'fastify'
+
+import { registerStatic } from './static.js'
+import { registerFileStore } from './core/file-store.js'
+import { registerWebSocket } from './core/websocket.js'
+import { AppError } from './core/errors.js'
+import { overviewPlugin } from './plugins/overview-plugin.js'
+import { agentsPlugin } from './plugins/agents-plugin.js'
+import { validationPlugin } from './plugins/validation-plugin.js'
+import { searchPlugin } from './plugins/search-plugin.js'
+import { skillsPlugin } from './plugins/skills-plugin.js'
+import { workflowsPlugin } from './plugins/workflows-plugin.js'
+import { outputsPlugin } from './plugins/outputs-plugin.js'
+import { filesPlugin } from './plugins/files-plugin.js'
+import { settingsPlugin } from './plugins/settings-plugin.js'
+import { modulesPlugin } from './plugins/modules-plugin.js'
+import { teamsPlugin } from './plugins/teams-plugin.js'
+import type { ProjectDetectionResult } from './core/project-detector.js'
+
+type CreateAppOptions = {
+  logger?: FastifyServerOptions['logger']
+  serveStatic?: boolean
+  project?: ProjectDetectionResult | null
+}
+
+export async function createApp(options: CreateAppOptions = {}) {
+  const app = Fastify({
+    logger: options.logger ?? true,
+  })
+
+  // Global error handler
+  app.setErrorHandler((error, _request, reply) => {
+    if (error instanceof AppError) {
+      return reply.status(error.statusCode).send(error.toJSON())
+    }
+    app.log.error(error)
+    return reply.status(500).send({
+      error: {
+        code: 'INTERNAL_ERROR',
+        message: 'An unexpected error occurred',
+        severity: 'error',
+      },
+    })
+  })
+
+  app.get('/api/health', async () => {
+    const info: AppInfo = {
+      name: 'bmad-studio',
+      version: '0.1.0',
+    }
+    return { status: 'ok', ...info }
+  })
+
+  // Project status endpoint
+  const project = options.project
+  const projectStatus: ProjectStatus = project
+    ? {
+        detected: true,
+        bmadVersion: project.bmadVersion ?? undefined,
+        projectRoot: project.projectRoot,
+        modules: project.modules.map((m) => m.name),
+        ideDirectories: project.ideDirectories,
+      }
+    : {
+        detected: false,
+        modules: [],
+        ideDirectories: [],
+      }
+
+  app.get('/api/project', async () => projectStatus)
+
+  // Register WebSocket support
+  await registerWebSocket(app)
+
+  // Register file store if project detected
+  if (project) {
+    await registerFileStore(app, project.projectRoot)
+  }
+
+  // Register API plugins
+  await app.register(overviewPlugin)
+  await app.register(agentsPlugin)
+  await app.register(validationPlugin)
+  await app.register(searchPlugin)
+  await app.register(skillsPlugin)
+  await app.register(workflowsPlugin)
+  await app.register(outputsPlugin)
+  await app.register(filesPlugin)
+  await app.register(settingsPlugin)
+  await app.register(modulesPlugin)
+  await app.register(teamsPlugin)
+
+  if (options.serveStatic !== false) {
+    await registerStatic(app)
+  }
+
+  return app
+}

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

@@ -0,0 +1,49 @@
+import { describe, it, expect } from 'vitest'
+
+import {
+  AppError,
+  NotFoundError,
+  ValidationError,
+  ConflictError,
+  FileSystemError,
+} from './errors.js'
+
+describe('error classes', () => {
+  it('AppError has correct properties', () => {
+    const err = new AppError('NOT_FOUND', 'test', 404, 'error', { path: '/x' })
+    expect(err.code).toBe('NOT_FOUND')
+    expect(err.statusCode).toBe(404)
+    expect(err.severity).toBe('error')
+    expect(err.message).toBe('test')
+    expect(err.details).toEqual({ path: '/x' })
+    expect(err).toBeInstanceOf(Error)
+  })
+
+  it('toJSON returns API error shape', () => {
+    const err = new NotFoundError('file not found', { path: '/x' })
+    expect(err.toJSON()).toEqual({
+      error: {
+        code: 'NOT_FOUND',
+        message: 'file not found',
+        severity: 'error',
+        details: { path: '/x' },
+      },
+    })
+  })
+
+  it('NotFoundError has statusCode 404', () => {
+    expect(new NotFoundError('x').statusCode).toBe(404)
+  })
+
+  it('ValidationError has statusCode 422', () => {
+    expect(new ValidationError('x').statusCode).toBe(422)
+  })
+
+  it('ConflictError has statusCode 409', () => {
+    expect(new ConflictError('x').statusCode).toBe(409)
+  })
+
+  it('FileSystemError has statusCode 500', () => {
+    expect(new FileSystemError('x').statusCode).toBe(500)
+  })
+})

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

@@ -0,0 +1,62 @@
+import type { ErrorCode, Severity } from '@bmad-studio/shared'
+
+export class AppError extends Error {
+  readonly code: ErrorCode
+  readonly statusCode: number
+  readonly severity: Severity
+  readonly details?: unknown
+
+  constructor(
+    code: ErrorCode,
+    message: string,
+    statusCode: number,
+    severity: Severity = 'error',
+    details?: unknown,
+  ) {
+    super(message)
+    this.name = 'AppError'
+    this.code = code
+    this.statusCode = statusCode
+    this.severity = severity
+    this.details = details
+  }
+
+  toJSON() {
+    return {
+      error: {
+        code: this.code,
+        message: this.message,
+        severity: this.severity,
+        ...(this.details !== undefined && { details: this.details }),
+      },
+    }
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message: string, details?: unknown) {
+    super('NOT_FOUND', message, 404, 'error', details)
+    this.name = 'NotFoundError'
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, details?: unknown) {
+    super('VALIDATION_ERROR', message, 422, 'error', details)
+    this.name = 'ValidationError'
+  }
+}
+
+export class ConflictError extends AppError {
+  constructor(message: string, details?: unknown) {
+    super('CONFLICT', message, 409, 'error', details)
+    this.name = 'ConflictError'
+  }
+}
+
+export class FileSystemError extends AppError {
+  constructor(message: string, details?: unknown) {
+    super('FILE_SYSTEM_ERROR', message, 500, 'error', details)
+    this.name = 'FileSystemError'
+  }
+}

package/packages/server/src/core/file-store.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { FileStore } from './file-store.js'
+
+describe('FileStore', () => {
+  let tmpDir: string
+  let studioDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'filestore-test-'))
+    studioDir = path.join(tmpDir, '.bmad-studio')
+  })
+
+  afterEach(async () => {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  })
+
+  it('initializes with empty index when no _bmad/ exists', async () => {
+    const store = new FileStore({ projectRoot: tmpDir, studioDir })
+    await store.initialize()
+
+    const index = store.getIndex()
+    expect(index.agents).toHaveLength(0)
+    expect(index.skills).toHaveLength(0)
+
+    await store.close()
+  })
+
+  it('builds index from _bmad/ on initialize', async () => {
+    const skillDir = path.join(tmpDir, '_bmad', 'core', 'skills', 'test')
+    fs.mkdirSync(skillDir, { recursive: true })
+    fs.writeFileSync(
+      path.join(skillDir, 'SKILL.md'),
+      '---\nname: test-skill\ndescription: A test\n---\nContent.\n',
+    )
+
+    const store = new FileStore({ projectRoot: tmpDir, studioDir })
+    await store.initialize()
+
+    const index = store.getIndex()
+    expect(index.skills).toHaveLength(1)
+    expect(index.skills[0].name).toBe('test-skill')
+
+    await store.close()
+  })
+
+  it('saves and loads cache', async () => {
+    const skillDir = path.join(tmpDir, '_bmad', 'core', 'skills', 'test')
+    fs.mkdirSync(skillDir, { recursive: true })
+    fs.writeFileSync(
+      path.join(skillDir, 'SKILL.md'),
+      '---\nname: cached-skill\ndescription: Cached\n---\nContent.\n',
+    )
+
+    // First init — builds index, saves cache
+    const store1 = new FileStore({ projectRoot: tmpDir, studioDir })
+    await store1.initialize()
+    await store1.close()
+
+    // Verify cache file exists
+    const cacheFile = path.join(studioDir, 'cache', 'entities.json')
+    expect(fs.existsSync(cacheFile)).toBe(true)
+
+    // Second init — loads from cache
+    const store2 = new FileStore({ projectRoot: tmpDir, studioDir })
+    await store2.initialize()
+    expect(store2.getIndex().skills).toHaveLength(1)
+    expect(store2.getIndex().skills[0].name).toBe('cached-skill')
+
+    await store2.close()
+  })
+
+  it('tracks pending writes for feedback loop suppression', async () => {
+    const store = new FileStore({ projectRoot: tmpDir, studioDir })
+    await store.initialize()
+
+    const testPath = '/some/file.yaml'
+    store.markPendingWrite(testPath)
+
+    // File is marked as pending
+    // (Internal state — we can verify by checking the suppression works)
+    store.clearPendingWrite(testPath)
+
+    await store.close()
+  })
+
+  it('handles corrupt cache gracefully', async () => {
+    const cacheDir = path.join(studioDir, 'cache')
+    fs.mkdirSync(cacheDir, { recursive: true })
+    fs.writeFileSync(path.join(cacheDir, 'entities.json'), 'NOT VALID JSON')
+
+    const store = new FileStore({ projectRoot: tmpDir, studioDir })
+    await store.initialize()
+
+    // Should rebuild index instead of crashing
+    expect(store.getIndex()).toBeDefined()
+    expect(store.getIndex().agents).toHaveLength(0)
+
+    await store.close()
+  })
+})

package/packages/server/src/core/file-store.ts

@@ -0,0 +1,209 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { watch } from 'chokidar'
+
+import type { FastifyInstance } from 'fastify'
+import type { FileCategory } from '@bmad-studio/shared'
+
+import { buildIndex } from '../parsers/index-builder.js'
+import type { EntityIndex } from '../parsers/index-builder.js'
+
+const BATCH_DELAY_MS = 100
+const SUPPRESSION_TIMEOUT_MS = 5000
+
+function categorizeFile(filePath: string): FileCategory {
+  if (filePath.includes('/agents/')) return 'agent'
+  if (filePath.includes('/skills/') || filePath.endsWith('SKILL.md')) return 'skill'
+  if (filePath.includes('/workflows/') || filePath.includes('/tasks/')) return 'workflow'
+  if (filePath.endsWith('config.yaml') || filePath.endsWith('manifest.yaml')) return 'config'
+  if (filePath.includes('/ides/') || filePath.includes('/connections/')) return 'connection'
+  return 'other'
+}
+
+export type FileChangeEvent = {
+  type: 'created' | 'modified' | 'deleted'
+  path: string
+  category: FileCategory
+}
+
+export type FileStoreOptions = {
+  projectRoot: string
+  studioDir: string
+  onBatchUpdate?: (events: FileChangeEvent[]) => void
+}
+
+export class FileStore {
+  private index: EntityIndex
+  private pendingWrites = new Set<string>()
+  private batchedEvents: FileChangeEvent[] = []
+  private batchTimer: ReturnType<typeof setTimeout> | null = null
+  private watcher: ReturnType<typeof watch> | null = null
+  readonly projectRoot: string
+  readonly studioDir: string
+  private onBatchUpdate?: (events: FileChangeEvent[]) => void
+
+  constructor(options: FileStoreOptions) {
+    this.projectRoot = options.projectRoot
+    this.studioDir = options.studioDir
+    this.onBatchUpdate = options.onBatchUpdate
+    this.index = {
+      agents: [],
+      skills: [],
+      workflows: [],
+      teams: [],
+      configs: [],
+      packages: [],
+      ideConfigs: [],
+      manifests: [],
+      errors: [],
+    }
+  }
+
+  async initialize() {
+    const cacheFile = path.join(this.studioDir, 'cache', 'entities.json')
+
+    // Try loading from cache
+    if (fs.existsSync(cacheFile)) {
+      try {
+        const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf-8')) as EntityIndex
+        this.index = cached
+      } catch {
+        // Cache corrupt — rebuild
+        this.index = buildIndex(this.projectRoot)
+      }
+    } else {
+      this.index = buildIndex(this.projectRoot)
+    }
+
+    this.saveCache()
+    this.startWatching()
+  }
+
+  private saveCache() {
+    const cacheDir = path.join(this.studioDir, 'cache')
+    if (!fs.existsSync(cacheDir)) {
+      fs.mkdirSync(cacheDir, { recursive: true })
+    }
+    fs.writeFileSync(
+      path.join(cacheDir, 'entities.json'),
+      JSON.stringify(this.index, null, 2),
+      'utf-8',
+    )
+  }
+
+  private startWatching() {
+    const bmadDir = path.join(this.projectRoot, '_bmad')
+    if (!fs.existsSync(bmadDir)) return
+
+    this.watcher = watch(bmadDir, {
+      ignored: ['**/node_modules/**', '**/.git/**', '**/.bmad-studio/**', '**/dist/**'],
+      persistent: true,
+      ignoreInitial: true,
+    })
+
+    const handleChange = (eventType: 'created' | 'modified' | 'deleted', filePath: string) => {
+      // Feedback loop suppression
+      if (this.pendingWrites.has(filePath)) {
+        return
+      }
+
+      const category = categorizeFile(filePath)
+      this.batchedEvents.push({ type: eventType, path: filePath, category })
+
+      if (!this.batchTimer) {
+        this.batchTimer = setTimeout(() => {
+          this.processBatch()
+        }, BATCH_DELAY_MS)
+      }
+    }
+
+    this.watcher
+      .on('add', (p) => handleChange('created', p))
+      .on('change', (p) => handleChange('modified', p))
+      .on('unlink', (p) => handleChange('deleted', p))
+  }
+
+  private processBatch() {
+    const events = [...this.batchedEvents]
+    this.batchedEvents = []
+    this.batchTimer = null
+
+    // Rebuild index (incremental would be better, but full rebuild is simpler and fast enough for v1)
+    this.index = buildIndex(this.projectRoot)
+    this.saveCache()
+
+    if (this.onBatchUpdate && events.length > 0) {
+      this.onBatchUpdate(events)
+    }
+  }
+
+  markPendingWrite(filePath: string) {
+    this.pendingWrites.add(filePath)
+    setTimeout(() => {
+      this.pendingWrites.delete(filePath)
+    }, SUPPRESSION_TIMEOUT_MS)
+  }
+
+  clearPendingWrite(filePath: string) {
+    this.pendingWrites.delete(filePath)
+  }
+
+  getIndex(): EntityIndex {
+    return this.index
+  }
+
+  rebuild() {
+    this.index = buildIndex(this.projectRoot)
+    this.saveCache()
+  }
+
+  async close() {
+    if (this.watcher) {
+      await this.watcher.close()
+      this.watcher = null
+    }
+    if (this.batchTimer) {
+      clearTimeout(this.batchTimer)
+      this.batchTimer = null
+    }
+  }
+}
+
+export async function registerFileStore(app: FastifyInstance, projectRoot: string) {
+  const studioDir = path.join(projectRoot, '.bmad-studio')
+
+  const store = new FileStore({
+    projectRoot,
+    studioDir,
+    onBatchUpdate: (events) => {
+      app.log.info({ eventCount: events.length }, 'File store batch update')
+      if (app.ws) {
+        for (const event of events) {
+          app.ws.broadcast({
+            type: `file:${event.type === 'modified' ? 'changed' : event.type}` as
+              | 'file:changed'
+              | 'file:created'
+              | 'file:deleted',
+            path: event.path,
+            category: event.category,
+          })
+        }
+      }
+    },
+  })
+
+  await store.initialize()
+
+  app.decorate('fileStore', store)
+
+  app.addHook('onClose', async () => {
+    await store.close()
+  })
+}
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    fileStore: FileStore
+  }
+}