mdboard 1.2.0 → 1.3.0

package/{api.js → src/server/api.js}

@@ -12,6 +12,9 @@
  */
 
 const { URL } = require('url');
+const fs = require('fs');
+const { resolveTheme } = require('../core/config');
+const { isValidProject } = require('../core/history');
 
 function jsonResponse(res, data, status = 200) {
   res.writeHead(status, {
@@ -41,6 +44,7 @@ function buildPatchMap(config) {
   const map = {
     features: 'tasks', tasks: 'tasks',
     epics: 'epics', milestones: 'milestones', sprints: 'sprints',
+    notes: 'notes',
   };
   map[config.entities.task.plural.toLowerCase()] = 'tasks';
   map[config.entities.epic.plural.toLowerCase()] = 'epics';
@@ -78,6 +82,8 @@ function formatTask(f) {
     started: f.started,
     completed: f.completed,
     content: f.content,
+    ai: f._ai && Object.keys(f._ai).length > 0 ? f._ai : undefined,
+    aiOwn: f._aiOwn && Object.keys(f._aiOwn).length > 0 ? f._aiOwn : undefined,
     ...sourceFields(f),
   };
 }
@@ -94,6 +100,8 @@ function formatMilestone(ms) {
     completedCount: ms._completedCount || 0,
     created: ms.created,
     content: ms.content,
+    ai: ms._ai && Object.keys(ms._ai).length > 0 ? ms._ai : undefined,
+    aiOwn: ms._aiOwn && Object.keys(ms._aiOwn).length > 0 ? ms._aiOwn : undefined,
     ...sourceFields(ms),
   };
 }
@@ -111,6 +119,8 @@ function formatEpic(e) {
     totalPoints: e._totalPoints || 0,
     progress: e._progress || 0,
     content: e.content,
+    ai: e._ai && Object.keys(e._ai).length > 0 ? e._ai : undefined,
+    aiOwn: e._aiOwn && Object.keys(e._aiOwn).length > 0 ? e._aiOwn : undefined,
     ...sourceFields(e),
   };
 }
@@ -130,6 +140,18 @@ function formatSprint(s) {
   };
 }
 
+function formatNote(n, includeContent) {
+  const result = {
+    id: n.id,
+    title: n.title,
+    created: n.created,
+    updated: n.updated,
+    ...sourceFields(n),
+  };
+  if (includeContent) result.content = n.content;
+  return result;
+}
+
 function filterTasks(tasks, url) {
   const status = url.searchParams.get('status');
   const epic = url.searchParams.get('epic');
@@ -191,7 +213,7 @@ function itemsBySource(model, sourceName) {
     sprints: filter(model.sprints),
     boards: filter(model.boards),
     reviews: filter(model.reviews),
-    metrics: model.metrics && model.metrics._source === sourceName ? model.metrics : null,
+    notes: filter(model.notes),
   };
 }
 
@@ -233,8 +255,71 @@ async function handleApi(req, res, ctx) {
     return handleOverviewRoute(req, res, ctx, url, pathname);
   }
 
+  // ─── GET /api/history ───────────────────────────────────────────────
+  if (req.method === 'GET' && pathname === '/api/history') {
+    if (ctx.getProjectHistory) {
+      return jsonResponse(res, ctx.getProjectHistory());
+    }
+    return jsonResponse(res, []);
+  }
+
   // ─── POST routes ────────────────────────────────────────────────────
   if (req.method === 'POST') {
+    if (pathname === '/api/history/switch') {
+      const body = await parseBody(req);
+      const targetPath = body && body.path;
+      if (!targetPath) {
+        return jsonResponse(res, { error: 'Missing path' }, 400);
+      }
+      if (!fs.existsSync(targetPath)) {
+        return jsonResponse(res, { error: 'Directory does not exist: ' + targetPath }, 400);
+      }
+      if (!isValidProject(targetPath)) {
+        return jsonResponse(res, { error: 'Not a valid mdboard project: ' + targetPath }, 400);
+      }
+      if (ctx.loadProject) {
+        try {
+          ctx.loadProject(targetPath);
+          const name = (ctx.model && ctx.model.project && ctx.model.project.name) || require('path').basename(targetPath);
+          return jsonResponse(res, { ok: true, projectDir: ctx.projectDir, name });
+        } catch (err) {
+          return jsonResponse(res, { error: err.message }, 500);
+        }
+      }
+      return jsonResponse(res, { error: 'Project switching not available' }, 500);
+    }
+
+    if (pathname === '/api/theme') {
+      const body = await parseBody(req);
+      if (!body.themeId || !body.css) {
+        return jsonResponse(res, { error: 'Missing themeId or css' }, 400);
+      }
+
+      const path = require('path');
+      const os = require('os');
+
+      if (body.setDefault) {
+        // Global: write CSS to ~/.config/mdboard/mdboard.css
+        const globalDir = path.join(os.homedir(), '.config', 'mdboard');
+        if (!fs.existsSync(globalDir)) fs.mkdirSync(globalDir, { recursive: true });
+        fs.writeFileSync(path.join(globalDir, 'mdboard.css'), body.css, 'utf-8');
+        // Also save theme ID in config JSON
+        const configPath = path.join(globalDir, 'mdboard.json');
+        let cfg = {};
+        try { cfg = JSON.parse(fs.readFileSync(configPath, 'utf-8')); } catch {}
+        cfg.theme = body.themeId;
+        fs.writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+      } else {
+        // Local: write CSS to project/mdboard.css
+        const projectCssPath = path.join(ctx.projectDir, 'project', 'mdboard.css');
+        const fallbackCssPath = path.join(ctx.projectDir, 'mdboard.css');
+        const cssPath = fs.existsSync(path.dirname(projectCssPath)) ? projectCssPath : fallbackCssPath;
+        fs.writeFileSync(cssPath, body.css, 'utf-8');
+      }
+
+      return jsonResponse(res, { ok: true });
+    }
+
     if (pathname === '/api/sources/sync') {
       if (ctx.syncRemotes) {
         try {
@@ -248,7 +333,7 @@ async function handleApi(req, res, ctx) {
     }
 
     // Legacy CRUD: POST /api/tasks, /api/milestones, etc.
-    const postMap = { tasks: 'tasks', milestones: 'milestones', epics: 'epics', sprints: 'sprints' };
+    const postMap = { tasks: 'tasks', milestones: 'milestones', epics: 'epics', sprints: 'sprints', notes: 'notes' };
     const postMatch = pathname.match(/^\/api\/([\w-]+)$/);
     if (postMatch && postMap[postMatch[1]]) {
       return handleLegacyCreate(req, res, ctx, postMap[postMatch[1]]);
@@ -283,6 +368,17 @@ async function handleApi(req, res, ctx) {
     return jsonResponse(res, { error: 'Not found' }, 404);
   }
 
+  // ─── GET /api/notes/:id ─────────────────────────────────────────────
+  if (req.method === 'GET') {
+    const noteMatch = pathname.match(/^\/api\/notes\/(.+)$/);
+    if (noteMatch) {
+      const noteId = decodeURIComponent(noteMatch[1]);
+      const note = model.notes.find(n => n.id === noteId);
+      if (!note) return jsonResponse(res, { error: 'Note not found: ' + noteId }, 404);
+      return jsonResponse(res, formatNote(note, true));
+    }
+  }
+
   // ─── GET routes (legacy + global) ──────────────────────────────────
   switch (pathname) {
     case '/api/config': {
@@ -293,6 +389,10 @@ async function handleApi(req, res, ctx) {
         boardColumns: config.boardColumns,
         completedStatus: config.completedStatus,
       };
+      const theme = resolveTheme(ctx.projectDir, process.env.MDBOARD_CONFIG);
+      result.theme = theme || null;
+      result.hasProject = ctx.hasProject != null ? ctx.hasProject : true;
+      result.projectDir = ctx.projectDir || null;
       if (sources && sources.length > 0) {
         result.workspace = {
           sources: sources.map(s => ({
@@ -337,8 +437,17 @@ async function handleApi(req, res, ctx) {
       });
     }
 
-    case '/api/metrics':
-      return jsonResponse(res, model.metrics || {});
+    case '/api/metrics': {
+      const cs = config.completedStatus;
+      return jsonResponse(res, {
+        totalTasks: model.tasks.length,
+        completedTasks: model.tasks.filter(t => t.status === cs).length,
+        totalMilestones: model.milestones.length,
+        totalEpics: model.epics.length,
+        totalPoints: model.tasks.reduce((sum, t) => sum + (t.points || 0), 0),
+        completedPoints: model.tasks.filter(t => t.status === cs).reduce((sum, t) => sum + (t.points || 0), 0),
+      });
+    }
 
     case '/api/health':
       return jsonResponse(res, computeHealth(model, config));
@@ -364,6 +473,12 @@ async function handleApi(req, res, ctx) {
       }));
     }
 
+    case '/api/notes':
+      return jsonResponse(res, model.notes.map(function(n) { return formatNote(n, false); }));
+
+    case '/api/ai-suggestions':
+      return jsonResponse(res, ctx.getAiSuggestions ? ctx.getAiSuggestions() : { skills: [], agents: [], mcps: [], commands: [], context: [] });
+
     case '/api/events': {
       res.writeHead(200, {
         'Content-Type': 'text/event-stream',
@@ -411,6 +526,15 @@ async function handleSourceRoute(req, res, ctx, url, sourceName, subPath) {
 
   // ── GET routes ──
   if (req.method === 'GET') {
+    // GET /api/sources/:name/notes/:id
+    const noteSubMatch = subPath.match(/^notes\/(.+)$/);
+    if (noteSubMatch) {
+      const noteId = decodeURIComponent(noteSubMatch[1]);
+      const note = (sourceModel.notes || []).find(n => n.id === noteId);
+      if (!note) return jsonResponse(res, { error: 'Note not found: ' + noteId }, 404);
+      return jsonResponse(res, formatNote(note, true));
+    }
+
     switch (subPath) {
       case 'config': {
         // Source-specific config (from sourceStates if available)
@@ -426,8 +550,11 @@ async function handleSourceRoute(req, res, ctx, url, sourceName, subPath) {
         });
       }
 
-      case 'project':
-        return jsonResponse(res, sourceModel.project || {});
+      case 'project': {
+        const sourceState = ctx.sourceStates ? ctx.sourceStates.get(sourceName) : null;
+        const proj = sourceState && sourceState.model ? sourceState.model.project : sourceModel.project;
+        return jsonResponse(res, proj || {});
+      }
 
       case 'milestones':
         return jsonResponse(res, sourceModel.milestones.map(formatMilestone));
@@ -453,11 +580,23 @@ async function handleSourceRoute(req, res, ctx, url, sourceName, subPath) {
         });
       }
 
+      case 'notes':
+        return jsonResponse(res, (sourceModel.notes || []).map(function(n) { return formatNote(n, false); }));
+
       case 'health':
         return jsonResponse(res, computeHealth(sourceModel, config));
 
-      case 'metrics':
-        return jsonResponse(res, sourceModel.metrics || {});
+      case 'metrics': {
+        const cs2 = config.completedStatus;
+        return jsonResponse(res, {
+          totalTasks: sourceModel.tasks.length,
+          completedTasks: sourceModel.tasks.filter(t => t.status === cs2).length,
+          totalMilestones: sourceModel.milestones.length,
+          totalEpics: sourceModel.epics.length,
+          totalPoints: sourceModel.tasks.reduce((sum, t) => sum + (t.points || 0), 0),
+          completedPoints: sourceModel.tasks.filter(t => t.status === cs2).reduce((sum, t) => sum + (t.points || 0), 0),
+        });
+      }
 
       default:
         return jsonResponse(res, { error: 'Not found' }, 404);
@@ -470,7 +609,7 @@ async function handleSourceRoute(req, res, ctx, url, sourceName, subPath) {
       return jsonResponse(res, { error: 'Source is read-only' }, 403);
     }
 
-    const entityMap = { tasks: 'tasks', milestones: 'milestones', epics: 'epics', sprints: 'sprints' };
+    const entityMap = { tasks: 'tasks', milestones: 'milestones', epics: 'epics', sprints: 'sprints', notes: 'notes' };
     if (entityMap[subPath] && ctx.createItem) {
       const body = await parseBody(req);
       try {
@@ -656,6 +795,7 @@ async function handlePatch(req, res, collection, id, ctx, sourceName) {
     case 'epics': item = findIn(model.epics); break;
     case 'milestones': item = findIn(model.milestones); break;
     case 'sprints': item = findIn(model.sprints); break;
+    case 'notes': item = findIn(model.notes); break;
   }
 
   if (!item) return jsonResponse(res, { error: collection.slice(0, -1) + ' not found: ' + id }, 404);
@@ -695,6 +835,7 @@ async function handleDelete(req, res, ctx, collection, id, sourceName) {
     case 'epics': item = findIn(model.epics); break;
     case 'milestones': item = findIn(model.milestones); break;
     case 'sprints': item = findIn(model.sprints); break;
+    case 'notes': item = findIn(model.notes); break;
   }
 
   if (!item) return jsonResponse(res, { error: collection.slice(0, -1) + ' not found: ' + id }, 404);

package/{server.js → src/server/server.js}

@@ -15,12 +15,14 @@ const http = require('http');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { loadConfig, deepMerge } = require('./config');
-const { createModel, scanSource, computeProgress, updateMarkdownFile, mergeResults,
-        createTask, createMilestone, createEpic, createSprint, archiveItem } = require('./scanner');
-const { setupWatchers } = require('./watcher');
+const { loadConfig, deepMerge } = require('../core/config');
+const { createModel, scanSource, computeProgress, computeAgentProps, updateMarkdownFile, mergeResults,
+        createTask, createMilestone, createEpic, createSprint, createNote, archiveItem } = require('../core/scanner');
+const { scanAgentConfigs } = require('../core/agent-scanner');
+const { setupWatchers, closeWatchers } = require('./watcher');
 const { handleApi } = require('./api');
-const { loadWorkspace, syncAllRemotes, getGitAuthor } = require('./workspace');
+const { loadWorkspace, syncAllRemotes, getGitAuthor } = require('../core/workspace');
+const { registerProject, getHistory, isValidProject } = require('../core/history');
 
 // ---------------------------------------------------------------------------
 // CLI argument parsing
@@ -52,8 +54,8 @@ for (let i = 0; i < args.length; i++) {
   }
 }
 
-const projectPath = path.join(projectDir, 'project');
-const boardDir = __dirname;
+let projectPath = path.join(projectDir, 'project');
+const boardDir = path.resolve(__dirname, '..', '..');
 
 // ---------------------------------------------------------------------------
 // Load configuration
@@ -88,6 +90,12 @@ function broadcast(data) {
 // ---------------------------------------------------------------------------
 let model = createModel();
 const sourceStates = new Map();
+let aiSuggestions = null;
+
+function refreshAiSuggestions() {
+  try { aiSuggestions = scanAgentConfigs(projectDir); }
+  catch { aiSuggestions = { skills: [], agents: [], mcps: [], commands: [], context: [] }; }
+}
 
 function loadSourceConfig(source) {
   // Try to load per-source mdboard.json
@@ -159,6 +167,8 @@ function scanAll() {
   }
 
   computeProgress(model, config.completedStatus);
+  computeAgentProps(model);
+  refreshAiSuggestions();
 }
 
 // ---------------------------------------------------------------------------
@@ -311,6 +321,8 @@ function createItemFn(sourceName, collection, data) {
       return createEpic(sourcePath, cfg, data, model.epics);
     case 'sprints':
       return createSprint(sourcePath, cfg, data, model.sprints);
+    case 'notes':
+      return createNote(sourcePath, data, model.notes);
     default:
       throw new Error('Unknown collection: ' + collection);
   }
@@ -333,7 +345,7 @@ const apiCtx = {
   get model() { return model; },
   get config() { return config; },
   port,
-  projectDir,
+  get projectDir() { return projectDir; },
   get sources() { return sources; },
   get sourceStates() { return sourceStates; },
   sseClients,
@@ -343,6 +355,13 @@ const apiCtx = {
   syncRemotes: doSyncRemotes,
   createItem: createItemFn,
   archiveItem: archiveItemFn,
+  getAiSuggestions: () => aiSuggestions || { skills: [], agents: [], mcps: [], commands: [], context: [] },
+  get hasProject() {
+    return fs.existsSync(path.join(projectDir, 'project')) ||
+      (workspace && sources.length > 0);
+  },
+  loadProject: loadProject,
+  getProjectHistory: () => getHistory(projectDir),
 };
 
 const server = http.createServer(async (req, res) => {
@@ -371,33 +390,84 @@ if (!workspace && !fs.existsSync(projectPath)) {
 scanAll();
 
 // Setup watchers
-const projectDirs = [];
-const rootDirs = [projectDir];
-
-if (workspace && sources.length > 0) {
-  for (const s of sources) {
-    if (s._resolvedPath && fs.existsSync(s._resolvedPath)) {
-      projectDirs.push(s._resolvedPath);
+function buildWatcherOpts() {
+  const pDirs = [];
+  const rDirs = [projectDir];
+  if (workspace && sources.length > 0) {
+    for (const s of sources) {
+      if (s._resolvedPath && fs.existsSync(s._resolvedPath)) {
+        pDirs.push(s._resolvedPath);
+      }
     }
+  } else if (fs.existsSync(projectPath)) {
+    pDirs.push(projectPath);
   }
-} else if (fs.existsSync(projectPath)) {
-  projectDirs.push(projectPath);
+  return {
+    projectDirs: pDirs,
+    rootDirs: rDirs,
+    onScan: () => scanAll(),
+    onConfigReload: () => reloadConfig(),
+    onBroadcast: (data) => broadcast(data),
+    workspacePath: workspace ? workspace._path : null,
+    onWorkspaceChange: () => {
+      workspace = loadWorkspace(projectDir, workspacePath);
+      sources = workspace ? workspace.sources : [];
+      scanAll();
+      broadcast({ type: 'update', timestamp: new Date().toISOString() });
+    },
+  };
 }
 
-setupWatchers({
-  projectDirs,
-  rootDirs,
-  onScan: () => scanAll(),
-  onConfigReload: () => reloadConfig(),
-  onBroadcast: (data) => broadcast(data),
-  workspacePath: workspace ? workspace._path : null,
-  onWorkspaceChange: () => {
-    workspace = loadWorkspace(projectDir, workspacePath);
-    sources = workspace ? workspace.sources : [];
-    scanAll();
-    broadcast({ type: 'update', timestamp: new Date().toISOString() });
-  },
-});
+let activeWatchers = setupWatchers(buildWatcherOpts());
+
+// Register current project in history
+if (isValidProject(projectDir)) {
+  const projName = (model.project && model.project.name) || path.basename(projectDir);
+  registerProject(projectDir, projName);
+}
+
+/**
+ * Load a different project directory dynamically.
+ *
+ * @param {string} newProjectDir - Absolute path to the new project
+ */
+function loadProject(newProjectDir) {
+  // 1. Close existing watchers
+  closeWatchers(activeWatchers);
+
+  // 2. Stop sync interval
+  if (syncInterval) clearInterval(syncInterval);
+  syncInterval = null;
+
+  // 3. Update paths
+  projectDir = path.resolve(newProjectDir);
+  projectPath = path.join(projectDir, 'project');
+  workspacePath = null;
+
+  // 4. Reload config
+  config = loadConfig(projectDir);
+
+  // 5. Reload workspace
+  workspace = loadWorkspace(projectDir, null);
+  sources = workspace ? workspace.sources : [];
+
+  // 6. Rescan
+  scanAll();
+
+  // 7. Setup new watchers
+  activeWatchers = setupWatchers(buildWatcherOpts());
+
+  // 8. Restart remote sync
+  doSyncRemotes().catch(() => {});
+  startSyncInterval();
+
+  // 9. Register in history
+  const projName = (model.project && model.project.name) || path.basename(projectDir);
+  registerProject(projectDir, projName);
+
+  // 10. Broadcast to SSE clients
+  broadcast({ type: 'project-changed', projectDir });
+}
 
 // Initial async sync + start periodic sync
 doSyncRemotes().catch(() => {});
@@ -407,11 +477,12 @@ server.listen(port, () => {
   const sourceInfo = workspace && sources.length > 0
     ? `\n     Sources: ${sources.map(s => s.label || s.name).join(', ')}`
     : '';
+  const watchCount = activeWatchers.length;
   console.log(`
   mdboard — Project Dashboard
      Project: ${projectDir}
      Server:  http://localhost:${port}${config._path ? '\n     Config:  ' + config._path : ''}${sourceInfo}
-${projectDirs.length > 0 ? '\n     Watching ' + projectDirs.length + ' director' + (projectDirs.length === 1 ? 'y' : 'ies') + ' for changes...' : ''}
+${watchCount > 0 ? '\n     Watching ' + watchCount + ' director' + (watchCount === 1 ? 'y' : 'ies') + ' for changes...' : ''}
 `);
 });
 
@@ -426,6 +497,7 @@ server.on('error', (err) => {
 process.on('SIGINT', () => {
   console.log('\n  Shutting down...');
   if (syncInterval) clearInterval(syncInterval);
+  closeWatchers(activeWatchers);
   for (const client of sseClients) {
     try { client.end(); } catch { /* ignore */ }
   }
@@ -434,5 +506,6 @@ process.on('SIGINT', () => {
 
 process.on('SIGTERM', () => {
   if (syncInterval) clearInterval(syncInterval);
+  closeWatchers(activeWatchers);
   server.close(() => process.exit(0));
 });

package/{watcher.js → src/server/watcher.js}

@@ -14,12 +14,13 @@ const watchTimers = new Map();
  *
  * @param {string} dir - Directory to watch recursively
  * @param {object} callbacks - { onChange(filename), onConfigChange(), onCssChange(filename) }
+ * @returns {fs.FSWatcher|null}
  */
 function watchDir(dir, callbacks) {
-  if (!fs.existsSync(dir)) return;
+  if (!fs.existsSync(dir)) return null;
 
   try {
-    fs.watch(dir, { recursive: true }, (eventType, filename) => {
+    const watcher = fs.watch(dir, { recursive: true }, (eventType, filename) => {
       if (!filename) return;
 
       const isMd = filename.endsWith('.md');
@@ -37,8 +38,10 @@ function watchDir(dir, callbacks) {
         if (callbacks.onChange) callbacks.onChange(filename, isCss);
       }, 200));
     });
+    return watcher;
   } catch {
     console.warn('  Warning: file watching unavailable for ' + dir);
+    return null;
   }
 }
 
@@ -47,12 +50,13 @@ function watchDir(dir, callbacks) {
  *
  * @param {string} filePath - Absolute path to file
  * @param {function} onChange - Callback on change
+ * @returns {fs.FSWatcher|null}
  */
 function watchFile(filePath, onChange) {
-  if (!fs.existsSync(filePath)) return;
+  if (!fs.existsSync(filePath)) return null;
 
   try {
-    fs.watch(filePath, (eventType) => {
+    const watcher = fs.watch(filePath, (eventType) => {
       const key = 'file:' + filePath;
       if (watchTimers.has(key)) clearTimeout(watchTimers.get(key));
 
@@ -61,11 +65,31 @@ function watchFile(filePath, onChange) {
         if (onChange) onChange();
       }, 200));
     });
+    return watcher;
   } catch {
-    // Non-critical
+    return null;
   }
 }
 
+/**
+ * Close all FSWatcher instances and clear pending timers.
+ *
+ * @param {Array<fs.FSWatcher|null>} watchers - Array of watchers to close
+ */
+function closeWatchers(watchers) {
+  if (!watchers) return;
+  for (const w of watchers) {
+    if (w) {
+      try { w.close(); } catch { /* ignore */ }
+    }
+  }
+  // Clear all pending debounce timers
+  for (const [key, timer] of watchTimers) {
+    clearTimeout(timer);
+  }
+  watchTimers.clear();
+}
+
 /**
  * Setup watchers for project directories and workspace-level config.
  *
@@ -77,13 +101,15 @@ function watchFile(filePath, onChange) {
  * @param {function} opts.onBroadcast - Called with event data to broadcast via SSE
  * @param {string} [opts.workspacePath] - Path to workspace.json to watch
  * @param {function} [opts.onWorkspaceChange] - Called when workspace.json changes
+ * @returns {Array<fs.FSWatcher|null>} - Array of active watchers
  */
 function setupWatchers(opts) {
   const { projectDirs, rootDirs, onScan, onConfigReload, onBroadcast, workspacePath, onWorkspaceChange } = opts;
+  const watchers = [];
 
   // Watch each project directory recursively
   for (const dir of projectDirs) {
-    watchDir(dir, {
+    const w = watchDir(dir, {
       onConfigChange: () => {
         if (onConfigReload) onConfigReload();
       },
@@ -94,12 +120,13 @@ function setupWatchers(opts) {
         if (onBroadcast) onBroadcast(eventData);
       },
     });
+    if (w) watchers.push(w);
   }
 
   // Watch root directories for workspace-level mdboard.json and mdboard.css
   for (const dir of rootDirs) {
     try {
-      fs.watch(dir, (eventType, filename) => {
+      const w = fs.watch(dir, (eventType, filename) => {
         if (!filename) return;
         if (filename !== 'mdboard.json' && filename !== 'mdboard.css') return;
 
@@ -117,6 +144,7 @@ function setupWatchers(opts) {
           if (onBroadcast) onBroadcast(eventData);
         }, 200));
       });
+      watchers.push(w);
     } catch {
       // Non-critical
     }
@@ -124,8 +152,11 @@ function setupWatchers(opts) {
 
   // Watch workspace.json
   if (workspacePath && onWorkspaceChange) {
-    watchFile(workspacePath, onWorkspaceChange);
+    const w = watchFile(workspacePath, onWorkspaceChange);
+    if (w) watchers.push(w);
   }
+
+  return watchers;
 }
 
-module.exports = { setupWatchers, watchDir, watchFile };
+module.exports = { setupWatchers, closeWatchers, watchDir, watchFile };