mdboard 1.1.0 → 1.3.0

package/src/server/server.js

@@ -0,0 +1,511 @@
+#!/usr/bin/env node
+/**
+ * mdboard — Project Dashboard Server
+ *
+ * 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
+ */
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+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('../core/workspace');
+const { registerProject, getHistory, isValidProject } = require('../core/history');
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+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]) {
+    case '--project':
+      projectDir = path.resolve(args[++i] || '.');
+      break;
+    case '--port':
+      port = parseInt(args[++i], 10) || 3333;
+      break;
+    case '--config':
+      i++;
+      break;
+    case '--workspace':
+      workspacePath = path.resolve(args[++i] || '.');
+      break;
+    case 'init':
+    case '-h': case '--help':
+    case '-v': case '--version':
+    case 'help': case 'cache':
+      break;
+  }
+}
+
+let projectPath = path.join(projectDir, 'project');
+const boardDir = path.resolve(__dirname, '..', '..');
+
+// ---------------------------------------------------------------------------
+// Load configuration
+// ---------------------------------------------------------------------------
+let config = loadConfig(projectDir, process.env.MDBOARD_CONFIG);
+
+function reloadConfig() {
+  config = loadConfig(projectDir, process.env.MDBOARD_CONFIG);
+}
+
+// ---------------------------------------------------------------------------
+// Workspace
+// ---------------------------------------------------------------------------
+let workspace = loadWorkspace(projectDir, workspacePath);
+let sources = workspace ? workspace.sources : [];
+let syncInterval = null;
+
+// ---------------------------------------------------------------------------
+// SSE clients
+// ---------------------------------------------------------------------------
+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); }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Model & scanning — sourceStates tracks per-source state
+// ---------------------------------------------------------------------------
+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
+  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 config;
+}
+
+function scanAll() {
+  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);
+          }
+        }
+      }
+
+      // Store per-source state
+      sourceStates.set(source.name, {
+        model: result,
+        config: srcConfig,
+        sourcePath,
+        repoRoot: source._repoRoot,
+        source,
+      });
+
+      results.push(result);
+    }
+    mergeResults(model, results);
+  } else {
+    // Legacy single-source mode
+    const result = scanSource(projectPath, config, {});
+    mergeResults(model, [result]);
+  }
+
+  computeProgress(model, config.completedStatus);
+  computeAgentProps(model);
+  refreshAiSuggestions();
+}
+
+// ---------------------------------------------------------------------------
+// File update helper — resolves correct projectPath per source
+// ---------------------------------------------------------------------------
+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);
+}
+
+// ---------------------------------------------------------------------------
+// Remote sync
+// ---------------------------------------------------------------------------
+async function doSyncRemotes() {
+  if (!workspace || sources.length === 0) return;
+
+  const remoteSources = sources.filter(s => s.type === 'remote');
+  if (remoteSources.length === 0) return;
+
+  await syncAllRemotes(remoteSources);
+  scanAll();
+  broadcast({ type: 'update', timestamp: new Date().toISOString() });
+}
+
+function startSyncInterval() {
+  if (syncInterval) clearInterval(syncInterval);
+  if (!workspace) return;
+
+  const refreshSeconds = (workspace.settings && workspace.settings.refresh) || 300;
+  const remoteSources = sources.filter(s => s.type === 'remote');
+  if (remoteSources.length === 0) return;
+
+  syncInterval = setInterval(() => {
+    doSyncRemotes().catch(err => {
+      console.warn('  Warning: remote sync failed:', err.message);
+    });
+  }, 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', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif', '.webp': 'image/webp',
+};
+
+function findCustomCss() {
+  const candidates = [
+    path.join(projectPath, 'mdboard.css'),
+    path.join(projectDir, 'mdboard.css'),
+    path.join(os.homedir(), '.config', 'mdboard', 'mdboard.css'),
+  ];
+  for (const p of candidates) {
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+function serveStatic(req, res) {
+  const url = new URL(req.url, `http://localhost:${port}`);
+
+  if (url.pathname === '/mdboard.css') {
+    const cssPath = findCustomCss();
+    if (cssPath) {
+      try {
+        const content = fs.readFileSync(cssPath);
+        res.writeHead(200, { 'Content-Type': 'text/css' });
+        res.end(content);
+        return;
+      } catch { /* Fall through */ }
+    }
+    res.writeHead(204);
+    res.end();
+    return;
+  }
+
+  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');
+    return;
+  }
+
+  const ext = path.extname(filePath);
+  const contentType = MIME_TYPES[ext] || 'text/plain';
+
+  try {
+    const content = fs.readFileSync(filePath);
+    res.writeHead(200, { 'Content-Type': contentType });
+    res.end(content);
+  } catch {
+    res.writeHead(404);
+    res.end('Not found');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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);
+    case 'notes':
+      return createNote(sourcePath, data, model.notes);
+    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,
+  get projectDir() { return projectDir; },
+  get sources() { return sources; },
+  get sourceStates() { return sourceStates; },
+  sseClients,
+  broadcast,
+  updateFile,
+  rescanAll: () => scanAll(),
+  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) => {
+  try {
+    if (req.url.startsWith('/api/')) {
+      await handleApi(req, res, apiCtx);
+    } else {
+      serveStatic(req, res);
+    }
+  } catch (err) {
+    if (!res.headersSent) {
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Internal server error' }));
+    }
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Startup
+// ---------------------------------------------------------------------------
+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();
+
+// Setup watchers
+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);
+  }
+  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() });
+    },
+  };
+}
+
+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(() => {});
+startSyncInterval();
+
+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}
+${watchCount > 0 ? '\n     Watching ' + watchCount + ' director' + (watchCount === 1 ? 'y' : 'ies') + ' for changes...' : ''}
+`);
+});
+
+server.on('error', (err) => {
+  if (err.code === 'EADDRINUSE') {
+    console.error(`\n  Error: Port ${port} is already in use. Use --port <number> to pick a different port.\n`);
+    process.exit(1);
+  }
+  throw 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 */ }
+  }
+  server.close(() => process.exit(0));
+});
+
+process.on('SIGTERM', () => {
+  if (syncInterval) clearInterval(syncInterval);
+  closeWatchers(activeWatchers);
+  server.close(() => process.exit(0));
+});

package/src/server/watcher.js

@@ -0,0 +1,162 @@
+/**
+ * mdboard — File watcher
+ *
+ * Watches project directories for changes to .md, config, and CSS files.
+ * Supports watching multiple directories for multi-source workspaces.
+ */
+
+const fs = require('fs');
+
+const watchTimers = new Map();
+
+/**
+ * Setup recursive watcher on a directory for .md, mdboard.json, and mdboard.css changes.
+ *
+ * @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 null;
+
+  try {
+    const watcher = fs.watch(dir, { recursive: true }, (eventType, filename) => {
+      if (!filename) return;
+
+      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 = dir + ':' + filename;
+      if (watchTimers.has(key)) clearTimeout(watchTimers.get(key));
+
+      watchTimers.set(key, setTimeout(() => {
+        watchTimers.delete(key);
+        if (isConfig && callbacks.onConfigChange) callbacks.onConfigChange();
+        if (callbacks.onChange) callbacks.onChange(filename, isCss);
+      }, 200));
+    });
+    return watcher;
+  } catch {
+    console.warn('  Warning: file watching unavailable for ' + dir);
+    return null;
+  }
+}
+
+/**
+ * Watch a single file for changes (e.g., workspace.json).
+ *
+ * @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 null;
+
+  try {
+    const watcher = fs.watch(filePath, (eventType) => {
+      const key = 'file:' + filePath;
+      if (watchTimers.has(key)) clearTimeout(watchTimers.get(key));
+
+      watchTimers.set(key, setTimeout(() => {
+        watchTimers.delete(key);
+        if (onChange) onChange();
+      }, 200));
+    });
+    return watcher;
+  } catch {
+    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.
+ *
+ * @param {object} opts
+ * @param {string[]} opts.projectDirs - List of project/ directories to watch recursively
+ * @param {string[]} opts.rootDirs - List of root directories to watch for mdboard.json/css
+ * @param {function} opts.onScan - Called when files change and a rescan is needed
+ * @param {function} opts.onConfigReload - Called when mdboard.json changes
+ * @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) {
+    const w = watchDir(dir, {
+      onConfigChange: () => {
+        if (onConfigReload) onConfigReload();
+      },
+      onChange: (filename, isCss) => {
+        if (onScan) onScan();
+        const eventData = { type: 'update', file: filename, timestamp: new Date().toISOString() };
+        if (isCss) eventData.cssReload = true;
+        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 {
+      const w = fs.watch(dir, (eventType, filename) => {
+        if (!filename) return;
+        if (filename !== 'mdboard.json' && filename !== 'mdboard.css') return;
+
+        const key = 'root:' + dir + ':' + filename;
+        if (watchTimers.has(key)) clearTimeout(watchTimers.get(key));
+
+        watchTimers.set(key, setTimeout(() => {
+          watchTimers.delete(key);
+          if (filename === 'mdboard.json') {
+            if (onConfigReload) onConfigReload();
+            if (onScan) onScan();
+          }
+          const eventData = { type: 'update', file: filename, timestamp: new Date().toISOString() };
+          if (filename === 'mdboard.css') eventData.cssReload = true;
+          if (onBroadcast) onBroadcast(eventData);
+        }, 200));
+      });
+      watchers.push(w);
+    } catch {
+      // Non-critical
+    }
+  }
+
+  // Watch workspace.json
+  if (workspacePath && onWorkspaceChange) {
+    const w = watchFile(workspacePath, onWorkspaceChange);
+    if (w) watchers.push(w);
+  }
+
+  return watchers;
+}
+
+module.exports = { setupWatchers, closeWatchers, watchDir, watchFile };