mdboard 1.1.0 → 1.2.0

package/server.js

@@ -5,6 +5,8 @@
  * Zero-dependency Node.js server that reads markdown project management
  * files and serves a visual dashboard + JSON API.
  *
+ * Supports multi-repo workspaces via workspace.json.
+ *
  * Usage:
  *   mdboard --project /path/to/workspace --port 3333
  */
@@ -13,8 +15,12 @@ const http = require('http');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const { URL } = require('url');
-const { loadConfig } = require('./config');
+const { loadConfig, deepMerge } = require('./config');
+const { createModel, scanSource, computeProgress, updateMarkdownFile, mergeResults,
+        createTask, createMilestone, createEpic, createSprint, archiveItem } = require('./scanner');
+const { setupWatchers } = require('./watcher');
+const { handleApi } = require('./api');
+const { loadWorkspace, syncAllRemotes, getGitAuthor } = require('./workspace');
 
 // ---------------------------------------------------------------------------
 // CLI argument parsing
@@ -22,6 +28,7 @@ const { loadConfig } = require('./config');
 const args = process.argv.slice(2);
 let projectDir = process.cwd();
 let port = 3333;
+let workspacePath = process.env.MDBOARD_WORKSPACE || null;
 
 for (let i = 0; i < args.length; i++) {
   switch (args[i]) {
@@ -32,16 +39,15 @@ for (let i = 0; i < args.length; i++) {
       port = parseInt(args[++i], 10) || 3333;
       break;
     case '--config':
-      // Handled by bin.js via process.env.MDBOARD_CONFIG; skip value here.
       i++;
       break;
+    case '--workspace':
+      workspacePath = path.resolve(args[++i] || '.');
+      break;
     case 'init':
-    case '-h':
-    case '--help':
-    case '-v':
-    case '--version':
-    case 'help':
-      // These are handled by bin.js; if server.js is called directly, ignore.
+    case '-h': case '--help':
+    case '-v': case '--version':
+    case 'help': case 'cache':
       break;
   }
 }
@@ -59,662 +65,152 @@ function reloadConfig() {
 }
 
 // ---------------------------------------------------------------------------
-// YAML frontmatter parser
-// ---------------------------------------------------------------------------
-function parseFrontmatter(content) {
-  const result = { frontmatter: {}, content: '' };
-  if (!content.startsWith('---')) return { frontmatter: {}, content };
-
-  const end = content.indexOf('\n---', 3);
-  if (end === -1) return { frontmatter: {}, content };
-
-  const yaml = content.substring(4, end).trim();
-  result.content = content.substring(end + 4).trim();
-  result.frontmatter = parseYaml(yaml);
-  return result;
-}
-
-function parseYaml(text) {
-  const obj = {};
-  const lines = text.split('\n');
-  let i = 0;
-
-  while (i < lines.length) {
-    const line = lines[i];
-    const match = line.match(/^(\w[\w.-]*)\s*:\s*(.*)/);
-
-    if (!match) { i++; continue; }
-
-    const key = match[1];
-    const rawValue = match[2].trim();
-
-    if (rawValue === '' || rawValue === '') {
-      const nested = {};
-      let dashList = null;
-      let j = i + 1;
-
-      while (j < lines.length) {
-        const nextLine = lines[j];
-        if (!nextLine.match(/^\s/) || nextLine.trim() === '') break;
-
-        const dashMatch = nextLine.match(/^\s+-\s+(.*)/);
-        const nestedMatch = nextLine.match(/^\s+(\w[\w.-]*)\s*:\s*(.*)/);
-
-        if (dashMatch) {
-          if (!dashList) dashList = [];
-          dashList.push(parseValue(dashMatch[1].trim()));
-        } else if (nestedMatch) {
-          nested[nestedMatch[1]] = parseValue(nestedMatch[2].trim());
-        }
-        j++;
-      }
-
-      obj[key] = dashList || (Object.keys(nested).length > 0 ? nested : parseValue(rawValue));
-      i = j;
-      continue;
-    }
-
-    obj[key] = parseValue(rawValue);
-    i++;
-  }
-
-  return obj;
-}
-
-function parseValue(raw) {
-  if (raw === '' || raw === undefined) return null;
-
-  if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
-    return raw.slice(1, -1);
-  }
-
-  if (raw.startsWith('[') && raw.endsWith(']')) {
-    const inner = raw.slice(1, -1).trim();
-    if (inner === '') return [];
-    return inner.split(',').map(s => parseValue(s.trim()));
-  }
-
-  if (raw === 'true') return true;
-  if (raw === 'false') return false;
-  if (raw === 'null' || raw === '~') return null;
-  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
-
-  return raw;
-}
-
-// ---------------------------------------------------------------------------
-// YAML serializer (for writing back to .md files)
+// Workspace
 // ---------------------------------------------------------------------------
-function serializeValue(v) {
-  if (v === null || v === undefined) return '';
-  if (typeof v === 'boolean') return v ? 'true' : 'false';
-  if (typeof v === 'number') return String(v);
-  if (typeof v === 'string') {
-    if (/[:#\[\]{}&*!|>'"%@`,\n]/.test(v) || v === '' || v === 'true' || v === 'false' || v === 'null') {
-      return '"' + v.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
-    }
-    return v;
-  }
-  return String(v);
-}
-
-function serializeYaml(obj) {
-  const lines = [];
-  for (const [key, value] of Object.entries(obj)) {
-    if (key.startsWith('_')) continue;
-    if (value === undefined) continue;
-    if (value === null) {
-      lines.push(key + ':');
-      continue;
-    }
-    if (Array.isArray(value)) {
-      if (value.length === 0) {
-        lines.push(key + ': []');
-      } else {
-        lines.push(key + ': [' + value.map(v => serializeValue(v)).join(', ') + ']');
-      }
-    } else if (typeof value === 'object') {
-      lines.push(key + ':');
-      for (const [k, v] of Object.entries(value)) {
-        lines.push('  ' + k + ': ' + serializeValue(v));
-      }
-    } else {
-      lines.push(key + ': ' + serializeValue(value));
-    }
-  }
-  return lines.join('\n');
-}
+let workspace = loadWorkspace(projectDir, workspacePath);
+let sources = workspace ? workspace.sources : [];
+let syncInterval = null;
 
 // ---------------------------------------------------------------------------
-// Markdown file updater
+// SSE clients
 // ---------------------------------------------------------------------------
-function updateMarkdownFile(relFile, updates) {
-  const filePath = path.join(projectPath, relFile);
-  if (!fs.existsSync(filePath)) throw new Error('File not found: ' + relFile);
-
-  const raw = fs.readFileSync(filePath, 'utf-8');
-  const parsed = parseFrontmatter(raw);
-
-  const newFm = { ...parsed.frontmatter };
-  let body = parsed.content;
+const sseClients = new Set();
 
-  for (const [k, v] of Object.entries(updates)) {
-    if (k === 'content') { body = v; continue; }
-    if (k.startsWith('_')) continue;
-    newFm[k] = v;
+function broadcast(data) {
+  const payload = `data: ${JSON.stringify(data)}\n\n`;
+  for (const res of sseClients) {
+    try { res.write(payload); } catch { sseClients.delete(res); }
   }
-
-  const yaml = serializeYaml(newFm);
-  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + (body || '') + '\n', 'utf-8');
-}
-
-// ---------------------------------------------------------------------------
-// Body parser
-// ---------------------------------------------------------------------------
-function parseBody(req) {
-  return new Promise((resolve) => {
-    const chunks = [];
-    req.on('data', c => chunks.push(c));
-    req.on('end', () => {
-      try { resolve(JSON.parse(Buffer.concat(chunks).toString())); }
-      catch { resolve({}); }
-    });
-  });
 }
 
 // ---------------------------------------------------------------------------
-// File scanner and in-memory model
+// Model & scanning — sourceStates tracks per-source state
 // ---------------------------------------------------------------------------
-const model = {
-  project: null,
-  milestones: [],
-  epics: [],
-  tasks: [],
-  sprints: [],
-  boards: [],
-  reviews: [],
-  metrics: null,
-};
-
-function safeReadFile(filePath) {
-  try {
-    return fs.readFileSync(filePath, 'utf-8');
-  } catch {
-    return null;
-  }
-}
+let model = createModel();
+const sourceStates = new Map();
 
-function isTaskFile(filename) {
-  if (!filename.endsWith('.md')) return false;
-  const prefix = config.entities.task.prefix;
-  if (filename.startsWith(prefix + '-')) return true;
-  const legacy = config.entities.task.legacyPrefixes || [];
-  for (const lp of legacy) {
-    if (filename.startsWith(lp + '-')) return true;
+function loadSourceConfig(source) {
+  // Try to load per-source mdboard.json
+  if (!source._repoRoot) return config;
+  const candidates = [
+    path.join(source._resolvedPath, 'mdboard.json'),
+    path.join(source._repoRoot, 'mdboard.json'),
+  ];
+  for (const p of candidates) {
+    try {
+      const raw = fs.readFileSync(p, 'utf-8');
+      const srcCfg = JSON.parse(raw);
+      return deepMerge(config, srcCfg);
+    } catch { continue; }
   }
-  return false;
+  return config;
 }
 
 function scanAll() {
-  model.project = null;
-  model.milestones = [];
-  model.epics = [];
-  model.tasks = [];
-  model.sprints = [];
-  model.boards = [];
-  model.reviews = [];
-  model.metrics = null;
-
-  if (!fs.existsSync(projectPath)) return;
-
-  const projectMd = safeReadFile(path.join(projectPath, 'PROJECT.md'));
-  if (projectMd) {
-    const parsed = parseFrontmatter(projectMd);
-    model.project = { ...parsed.frontmatter, content: parsed.content, _file: 'PROJECT.md' };
-  }
-
-  const metricsMd = safeReadFile(path.join(projectPath, 'metrics.md'));
-  if (metricsMd) {
-    const parsed = parseFrontmatter(metricsMd);
-    model.metrics = { ...parsed.frontmatter, content: parsed.content, _file: 'metrics.md' };
-  }
-
-  const msDir = config.entities.milestone.dir;
-  const epicDir = config.entities.epic.dir;
-  const taskDir = config.entities.task.dir;
-  const sprintDir = config.entities.sprint.dir;
-
-  const milestonesDir = path.join(projectPath, msDir);
-  if (fs.existsSync(milestonesDir)) {
-    for (const ms of safeDirEntries(milestonesDir)) {
-      const msPath = path.join(milestonesDir, ms);
-      if (!fs.statSync(msPath).isDirectory()) continue;
-
-      const msReadme = safeReadFile(path.join(msPath, 'README.md'));
-      if (msReadme) {
-        const parsed = parseFrontmatter(msReadme);
-        model.milestones.push({ ...parsed.frontmatter, content: parsed.content, _dir: ms, _file: `${msDir}/${ms}/README.md` });
-      }
-
-      const epicsDir = path.join(msPath, epicDir);
-      if (fs.existsSync(epicsDir)) {
-        for (const epic of safeDirEntries(epicsDir)) {
-          const epicPath = path.join(epicsDir, epic);
-          if (!fs.statSync(epicPath).isDirectory()) continue;
-
-          const epicReadme = safeReadFile(path.join(epicPath, 'README.md'));
-          if (epicReadme) {
-            const parsed = parseFrontmatter(epicReadme);
-            model.epics.push({ ...parsed.frontmatter, content: parsed.content, _dir: epic, _milestone: ms, _file: `${msDir}/${ms}/${epicDir}/${epic}/README.md` });
-          }
-
-          const backlogDir = path.join(epicPath, taskDir);
-          if (fs.existsSync(backlogDir)) {
-            for (const feat of safeDirEntries(backlogDir)) {
-              if (!isTaskFile(feat)) continue;
-
-              const featContent = safeReadFile(path.join(backlogDir, feat));
-              if (featContent) {
-                const parsed = parseFrontmatter(featContent);
-                model.tasks.push({
-                  ...parsed.frontmatter,
-                  content: parsed.content,
-                  _filename: feat,
-                  _epic: epic,
-                  _milestone: ms,
-                  _file: `${msDir}/${ms}/${epicDir}/${epic}/${taskDir}/${feat}`,
-                });
-              }
-            }
+  model = createModel();
+  sourceStates.clear();
+
+  if (workspace && sources.length > 0) {
+    // Multi-source mode
+    const results = [];
+    for (const source of sources) {
+      const sourcePath = source._resolvedPath;
+      if (!sourcePath) continue;
+
+      const readonly = source.readonly != null ? source.readonly : (source.type === 'remote');
+      const meta = {
+        name: source.name,
+        label: source.label || source.name,
+        color: source.color || null,
+        type: source.type,
+        readonly,
+      };
+
+      // Load per-source config
+      const srcConfig = loadSourceConfig(source);
+      const result = scanSource(sourcePath, srcConfig, meta);
+
+      // Add author info if showAuthor is enabled
+      if (workspace.settings && workspace.settings.showAuthor) {
+        const repoRoot = source._repoRoot;
+        if (repoRoot) {
+          for (const task of result.tasks) {
+            task._author = getGitAuthor(repoRoot, task._file);
           }
         }
       }
 
-      const sprintsDir = path.join(msPath, sprintDir);
-      if (fs.existsSync(sprintsDir)) {
-        for (const sp of safeDirEntries(sprintsDir)) {
-          const spPath = path.join(sprintsDir, sp);
-          if (!fs.statSync(spPath).isDirectory()) continue;
-
-          const planMd = safeReadFile(path.join(spPath, 'plan.md'));
-          if (planMd) {
-            const parsed = parseFrontmatter(planMd);
-            model.sprints.push({ ...parsed.frontmatter, content: parsed.content, _dir: sp, _milestone: ms, _file: `${msDir}/${ms}/${sprintDir}/${sp}/plan.md` });
-          }
-
-          const boardMd = safeReadFile(path.join(spPath, 'board.md'));
-          if (boardMd) {
-            const parsed = parseFrontmatter(boardMd);
-            model.boards.push({ ...parsed.frontmatter, content: parsed.content, _dir: sp, _milestone: ms, _file: `${msDir}/${ms}/${sprintDir}/${sp}/board.md` });
-          }
+      // Store per-source state
+      sourceStates.set(source.name, {
+        model: result,
+        config: srcConfig,
+        sourcePath,
+        repoRoot: source._repoRoot,
+        source,
+      });
 
-          const reviewMd = safeReadFile(path.join(spPath, 'review.md'));
-          if (reviewMd) {
-            const parsed = parseFrontmatter(reviewMd);
-            model.reviews.push({ ...parsed.frontmatter, content: parsed.content, _dir: sp, _milestone: ms, _file: `${msDir}/${ms}/${sprintDir}/${sp}/review.md` });
-          }
-        }
-      }
+      results.push(result);
     }
+    mergeResults(model, results);
+  } else {
+    // Legacy single-source mode
+    const result = scanSource(projectPath, config, {});
+    mergeResults(model, [result]);
   }
 
-  computeProgress();
-}
-
-function safeDirEntries(dir) {
-  try {
-    return fs.readdirSync(dir).filter(e => !e.startsWith('.'));
-  } catch {
-    return [];
-  }
-}
-
-function computeProgress() {
-  const completedStatus = config.completedStatus;
-
-  for (const epic of model.epics) {
-    const epicTasks = model.tasks.filter(f => f._epic === epic._dir && f._milestone === epic._milestone);
-    const done = epicTasks.filter(f => f.status === completedStatus).length;
-    epic._featureCount = epicTasks.length;
-    epic._completedCount = done;
-    epic._progress = epicTasks.length > 0 ? Math.round((done / epicTasks.length) * 100) : 0;
-    epic._totalPoints = epicTasks.reduce((sum, f) => sum + (f.points || 0), 0);
-  }
-
-  for (const ms of model.milestones) {
-    const msTasks = model.tasks.filter(f => f._milestone === ms._dir);
-    const done = msTasks.filter(f => f.status === completedStatus).length;
-    ms._featureCount = msTasks.length;
-    ms._completedCount = done;
-    ms._progress = msTasks.length > 0 ? Math.round((done / msTasks.length) * 100) : 0;
-  }
+  computeProgress(model, config.completedStatus);
 }
 
 // ---------------------------------------------------------------------------
-// SSE clients
+// File update helper — resolves correct projectPath per source
 // ---------------------------------------------------------------------------
-const sseClients = new Set();
-
-function broadcast(data) {
-  const payload = `data: ${JSON.stringify(data)}\n\n`;
-  for (const res of sseClients) {
-    try { res.write(payload); } catch { sseClients.delete(res); }
+function updateFile(sourceName, relFile, updates) {
+  if (sourceName && sources.length > 0) {
+    const source = sources.find(s => s.name === sourceName);
+    if (source && source._resolvedPath) {
+      return updateMarkdownFile(source._resolvedPath, relFile, updates);
+    }
   }
+  return updateMarkdownFile(projectPath, relFile, updates);
 }
 
 // ---------------------------------------------------------------------------
-// File watcher
+// Remote sync
 // ---------------------------------------------------------------------------
-const watchTimers = new Map();
-
-function setupWatcher() {
-  if (!fs.existsSync(projectPath)) return;
-
-  try {
-    fs.watch(projectPath, { recursive: true }, (eventType, filename) => {
-      if (!filename) return;
-
-      // Watch .md files, mdboard.json, and mdboard.css
-      const isMd = filename.endsWith('.md');
-      const isConfig = filename === 'mdboard.json' || filename.endsWith('/mdboard.json');
-      const isCss = filename === 'mdboard.css' || filename.endsWith('/mdboard.css');
-
-      if (!isMd && !isConfig && !isCss) return;
-
-      const key = filename;
-      if (watchTimers.has(key)) clearTimeout(watchTimers.get(key));
-
-      watchTimers.set(key, setTimeout(() => {
-        watchTimers.delete(key);
-        if (isConfig) reloadConfig();
-        scanAll();
-        const eventData = { type: 'update', file: filename, timestamp: new Date().toISOString() };
-        if (isCss) eventData.cssReload = true;
-        broadcast(eventData);
-      }, 200));
-    });
-  } catch {
-    console.warn('  Warning: file watching unavailable on this platform');
-  }
+async function doSyncRemotes() {
+  if (!workspace || sources.length === 0) return;
 
-  // Also watch workspace-level mdboard.json and mdboard.css
-  try {
-    fs.watch(projectDir, (eventType, filename) => {
-      if (!filename) return;
-      if (filename !== 'mdboard.json' && filename !== 'mdboard.css') return;
-
-      const key = 'root-' + filename;
-      if (watchTimers.has(key)) clearTimeout(watchTimers.get(key));
-
-      watchTimers.set(key, setTimeout(() => {
-        watchTimers.delete(key);
-        if (filename === 'mdboard.json') {
-          reloadConfig();
-          scanAll();
-        }
-        const eventData = { type: 'update', file: filename, timestamp: new Date().toISOString() };
-        if (filename === 'mdboard.css') eventData.cssReload = true;
-        broadcast(eventData);
-      }, 200));
-    });
-  } catch {
-    // Non-critical: workspace-level watch failed
-  }
-}
+  const remoteSources = sources.filter(s => s.type === 'remote');
+  if (remoteSources.length === 0) return;
 
-// ---------------------------------------------------------------------------
-// API handlers
-// ---------------------------------------------------------------------------
-function jsonResponse(res, data, status = 200) {
-  res.writeHead(status, {
-    'Content-Type': 'application/json',
-    'Access-Control-Allow-Origin': '*',
-    'Access-Control-Allow-Methods': 'GET, PATCH, OPTIONS',
-    'Access-Control-Allow-Headers': 'Content-Type',
-  });
-  res.end(JSON.stringify(data, null, 2));
+  await syncAllRemotes(remoteSources);
+  scanAll();
+  broadcast({ type: 'update', timestamp: new Date().toISOString() });
 }
 
-async function handlePatch(req, res, collection, id) {
-  const body = await parseBody(req);
-
-  let item;
-  switch (collection) {
-    case 'tasks': item = model.tasks.find(f => f.id === id); break;
-    case 'epics': item = model.epics.find(e => e.id === id); break;
-    case 'milestones': item = model.milestones.find(m => m.id === id); break;
-    case 'sprints': item = model.sprints.find(s => s.id === id); break;
-  }
-
-  if (!item) return jsonResponse(res, { error: collection.slice(0, -1) + ' not found: ' + id }, 404);
-
-  try {
-    updateMarkdownFile(item._file, body);
-    scanAll();
-    broadcast({ type: 'update', timestamp: new Date().toISOString() });
-    return jsonResponse(res, { ok: true });
-  } catch (err) {
-    return jsonResponse(res, { error: err.message }, 500);
-  }
-}
+function startSyncInterval() {
+  if (syncInterval) clearInterval(syncInterval);
+  if (!workspace) return;
 
-// Build PATCH route map from config
-function buildPatchMap() {
-  const map = {
-    features: 'tasks', tasks: 'tasks',
-    epics: 'epics', milestones: 'milestones', sprints: 'sprints',
-  };
-  // Add configured plural names as aliases
-  map[config.entities.task.plural.toLowerCase()] = 'tasks';
-  map[config.entities.epic.plural.toLowerCase()] = 'epics';
-  map[config.entities.milestone.plural.toLowerCase()] = 'milestones';
-  map[config.entities.sprint.plural.toLowerCase()] = 'sprints';
-  return map;
-}
+  const refreshSeconds = (workspace.settings && workspace.settings.refresh) || 300;
+  const remoteSources = sources.filter(s => s.type === 'remote');
+  if (remoteSources.length === 0) return;
 
-async function handleApi(req, res) {
-  const url = new URL(req.url, `http://localhost:${port}`);
-  const pathname = url.pathname;
-
-  // CORS preflight
-  if (req.method === 'OPTIONS') {
-    res.writeHead(204, {
-      'Access-Control-Allow-Origin': '*',
-      'Access-Control-Allow-Methods': 'GET, PATCH, OPTIONS',
-      'Access-Control-Allow-Headers': 'Content-Type',
+  syncInterval = setInterval(() => {
+    doSyncRemotes().catch(err => {
+      console.warn('  Warning: remote sync failed:', err.message);
     });
-    return res.end();
-  }
-
-  // PATCH routes — dynamic via config
-  if (req.method === 'PATCH') {
-    const match = pathname.match(/^\/api\/([\w-]+)\/(.+)$/);
-    if (match) {
-      const patchMap = buildPatchMap();
-      const collection = patchMap[match[1]];
-      if (collection) return handlePatch(req, res, collection, decodeURIComponent(match[2]));
-    }
-    return jsonResponse(res, { error: 'Not found' }, 404);
-  }
-
-  // GET routes
-  switch (pathname) {
-    case '/api/config':
-      return jsonResponse(res, {
-        entities: config.entities,
-        statuses: config.statuses,
-        priorities: config.priorities,
-        boardColumns: config.boardColumns,
-        completedStatus: config.completedStatus,
-      });
-
-    case '/api/project':
-      return jsonResponse(res, model.project || {});
-
-    case '/api/milestones':
-      return jsonResponse(res, model.milestones.map(ms => ({
-        id: ms.id,
-        title: ms.title,
-        status: ms.status,
-        deadline: ms.deadline,
-        progress: ms._progress || 0,
-        featureCount: ms._featureCount || 0,
-        completedCount: ms._completedCount || 0,
-        created: ms.created,
-        content: ms.content,
-      })));
-
-    case '/api/epics':
-      return jsonResponse(res, model.epics.map(e => ({
-        id: e.id,
-        title: e.title,
-        milestone: e._milestone,
-        status: e.status,
-        priority: e.priority,
-        dependencies: e.dependencies,
-        featureCount: e._featureCount || 0,
-        completedCount: e._completedCount || 0,
-        totalPoints: e._totalPoints || 0,
-        progress: e._progress || 0,
-        content: e.content,
-      })));
-
-    case '/api/tasks':
-    case '/api/features': {
-      let tasks = model.tasks.map(f => ({
-        id: f.id,
-        title: f.title,
-        epic: f._epic || f.epic,
-        milestone: f._milestone || f.milestone,
-        sprint: f.sprint,
-        status: f.status,
-        priority: f.priority,
-        points: f.points,
-        assigned: f.assigned,
-        branches: f.branches,
-        pull_requests: f.pull_requests,
-        created: f.created,
-        started: f.started,
-        completed: f.completed,
-        content: f.content,
-      }));
-
-      const status = url.searchParams.get('status');
-      const epic = url.searchParams.get('epic');
-      const milestone = url.searchParams.get('milestone');
-      const sprint = url.searchParams.get('sprint');
-
-      if (status) tasks = tasks.filter(f => f.status === status);
-      if (epic) tasks = tasks.filter(f => f.epic === epic);
-      if (milestone) tasks = tasks.filter(f => f.milestone === milestone);
-      if (sprint) tasks = tasks.filter(f => f.sprint === sprint);
-
-      return jsonResponse(res, tasks);
-    }
-
-    case '/api/sprints':
-      return jsonResponse(res, model.sprints.map(s => ({
-        id: s.id,
-        milestone: s._milestone,
-        status: s.status,
-        goal: s.goal,
-        start_date: s.start_date,
-        end_date: s.end_date,
-        planned_points: s.planned_points,
-        completed_points: s.completed_points,
-        features: s.features,
-      })));
-
-    case '/api/sprint': {
-      const activeSprint = model.sprints.find(s => s.status === 'active');
-      if (!activeSprint) return jsonResponse(res, null);
-
-      const board = model.boards.find(b => b._dir === activeSprint._dir && b._milestone === activeSprint._milestone);
-      return jsonResponse(res, {
-        id: activeSprint.id,
-        milestone: activeSprint._milestone,
-        status: activeSprint.status,
-        goal: activeSprint.goal,
-        start_date: activeSprint.start_date,
-        end_date: activeSprint.end_date,
-        planned_points: activeSprint.planned_points,
-        completed_points: activeSprint.completed_points,
-        features: activeSprint.features,
-        board: board ? board.content : null,
-      });
-    }
-
-    case '/api/metrics':
-      return jsonResponse(res, model.metrics || {});
-
-    case '/api/health': {
-      const completedStatus = config.completedStatus;
-      const inProgressStatus = (config.statuses.task.find(s => s.icon === 'half-circle') || {}).key || 'in-progress';
-
-      const activeMilestone = model.milestones.find(m => m.status === 'active');
-      const activeSprint = model.sprints.find(s => s.status === 'active');
-      const totalFeatures = model.tasks.length;
-      const completedFeatures = model.tasks.filter(f => f.status === completedStatus).length;
-      const inProgressFeatures = model.tasks.filter(f => f.status === inProgressStatus).length;
-
-      const completedSprints = model.sprints.filter(s => s.status === 'completed');
-      let velocity = null;
-      if (completedSprints.length > 0) {
-        const totalVelocity = completedSprints.reduce((sum, s) => {
-          const planned = s.planned_points || 1;
-          const completed = s.completed_points || 0;
-          return sum + Math.round((completed / planned) * 100);
-        }, 0);
-        velocity = Math.round(totalVelocity / completedSprints.length);
-      }
-
-      return jsonResponse(res, {
-        status: 'ok',
-        activeMilestone: activeMilestone ? activeMilestone.id : null,
-        activeSprint: activeSprint ? activeSprint.id : null,
-        totalFeatures,
-        completedFeatures,
-        inProgressFeatures,
-        velocity,
-      });
-    }
-
-    case '/api/events':
-      res.writeHead(200, {
-        'Content-Type': 'text/event-stream',
-        'Cache-Control': 'no-cache',
-        'Connection': 'keep-alive',
-        'Access-Control-Allow-Origin': '*',
-      });
-      res.write(`data: ${JSON.stringify({ type: 'connected' })}\n\n`);
-      sseClients.add(res);
-
-      const keepalive = setInterval(() => {
-        try { res.write(': keepalive\n\n'); } catch { /* client gone */ }
-      }, 30000);
-
-      req.on('close', () => {
-        sseClients.delete(res);
-        clearInterval(keepalive);
-      });
-      return;
-
-    default:
-      return jsonResponse(res, { error: 'Not found' }, 404);
-  }
+  }, refreshSeconds * 1000);
 }
 
 // ---------------------------------------------------------------------------
 // Static file serving
 // ---------------------------------------------------------------------------
 const MIME_TYPES = {
-  '.html': 'text/html',
-  '.css': 'text/css',
-  '.js': 'application/javascript',
-  '.json': 'application/json',
-  '.png': 'image/png',
-  '.svg': 'image/svg+xml',
-  '.ico': 'image/x-icon',
+  '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
+  '.json': 'application/json', '.png': 'image/png', '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif', '.webp': 'image/webp',
 };
 
 function findCustomCss() {
@@ -732,7 +228,6 @@ function findCustomCss() {
 function serveStatic(req, res) {
   const url = new URL(req.url, `http://localhost:${port}`);
 
-  // Serve custom CSS
   if (url.pathname === '/mdboard.css') {
     const cssPath = findCustomCss();
     if (cssPath) {
@@ -741,17 +236,33 @@ function serveStatic(req, res) {
         res.writeHead(200, { 'Content-Type': 'text/css' });
         res.end(content);
         return;
-      } catch {
-        // Fall through to 204
-      }
+      } catch { /* Fall through */ }
     }
     res.writeHead(204);
     res.end();
     return;
   }
 
-  let filePath = path.join(boardDir, 'index.html');
+  if (url.pathname === '/logo') {
+    if (config.logo && !config.logo.startsWith('http')) {
+      const logoPath = path.resolve(projectDir, config.logo);
+      if (logoPath.startsWith(projectDir) && fs.existsSync(logoPath)) {
+        try {
+          const logoContent = fs.readFileSync(logoPath);
+          const logoExt = path.extname(logoPath);
+          const logoMime = MIME_TYPES[logoExt] || 'application/octet-stream';
+          res.writeHead(200, { 'Content-Type': logoMime });
+          res.end(logoContent);
+          return;
+        } catch { /* fall through */ }
+      }
+    }
+    res.writeHead(404);
+    res.end('Not found');
+    return;
+  }
 
+  let filePath = path.join(boardDir, 'index.html');
   if (!filePath.startsWith(boardDir)) {
     res.writeHead(403);
     res.end('Forbidden');
@@ -774,10 +285,70 @@ function serveStatic(req, res) {
 // ---------------------------------------------------------------------------
 // HTTP server
 // ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// CRUD helpers — resolve source path and delegate to scanner
+// ---------------------------------------------------------------------------
+function createItemFn(sourceName, collection, data) {
+  let sourcePath = projectPath;
+  let cfg = config;
+
+  if (sourceName && sources.length > 0) {
+    const source = sources.find(s => s.name === sourceName);
+    if (source && source._resolvedPath) {
+      sourcePath = source._resolvedPath;
+      const state = sourceStates.get(sourceName);
+      if (state) cfg = state.config;
+    }
+  }
+
+  // Use ALL items across sources to compute next ID — prevents cross-source collisions
+  switch (collection) {
+    case 'tasks':
+      return createTask(sourcePath, cfg, data, model.tasks);
+    case 'milestones':
+      return createMilestone(sourcePath, cfg, data, model.milestones);
+    case 'epics':
+      return createEpic(sourcePath, cfg, data, model.epics);
+    case 'sprints':
+      return createSprint(sourcePath, cfg, data, model.sprints);
+    default:
+      throw new Error('Unknown collection: ' + collection);
+  }
+}
+
+function archiveItemFn(sourceName, item) {
+  let sourcePath = projectPath;
+
+  if (sourceName && sources.length > 0) {
+    const source = sources.find(s => s.name === sourceName);
+    if (source && source._resolvedPath) {
+      sourcePath = source._resolvedPath;
+    }
+  }
+
+  return archiveItem(sourcePath, item);
+}
+
+const apiCtx = {
+  get model() { return model; },
+  get config() { return config; },
+  port,
+  projectDir,
+  get sources() { return sources; },
+  get sourceStates() { return sourceStates; },
+  sseClients,
+  broadcast,
+  updateFile,
+  rescanAll: () => scanAll(),
+  syncRemotes: doSyncRemotes,
+  createItem: createItemFn,
+  archiveItem: archiveItemFn,
+};
+
 const server = http.createServer(async (req, res) => {
   try {
     if (req.url.startsWith('/api/')) {
-      await handleApi(req, res);
+      await handleApi(req, res, apiCtx);
     } else {
       serveStatic(req, res);
     }
@@ -792,20 +363,55 @@ const server = http.createServer(async (req, res) => {
 // ---------------------------------------------------------------------------
 // Startup
 // ---------------------------------------------------------------------------
-if (!fs.existsSync(projectPath)) {
+if (!workspace && !fs.existsSync(projectPath)) {
   console.warn(`\n  Warning: project/ directory not found at ${projectPath}`);
   console.warn('  Run `mdboard init` to scaffold a new project.\n');
 }
 
 scanAll();
-setupWatcher();
+
+// 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);
+    }
+  }
+} else if (fs.existsSync(projectPath)) {
+  projectDirs.push(projectPath);
+}
+
+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() });
+  },
+});
+
+// Initial async sync + start periodic sync
+doSyncRemotes().catch(() => {});
+startSyncInterval();
 
 server.listen(port, () => {
+  const sourceInfo = workspace && sources.length > 0
+    ? `\n     Sources: ${sources.map(s => s.label || s.name).join(', ')}`
+    : '';
   console.log(`
   mdboard — Project Dashboard
      Project: ${projectDir}
-     Server:  http://localhost:${port}${config._path ? '\n     Config:  ' + config._path : ''}
-${fs.existsSync(projectPath) ? '\n     Watching project/ for changes...' : ''}
+     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...' : ''}
 `);
 });
 
@@ -819,6 +425,7 @@ server.on('error', (err) => {
 
 process.on('SIGINT', () => {
   console.log('\n  Shutting down...');
+  if (syncInterval) clearInterval(syncInterval);
   for (const client of sseClients) {
     try { client.end(); } catch { /* ignore */ }
   }
@@ -826,5 +433,6 @@ process.on('SIGINT', () => {
 });
 
 process.on('SIGTERM', () => {
+  if (syncInterval) clearInterval(syncInterval);
   server.close(() => process.exit(0));
 });