mdboard 1.2.0 → 2.0.0

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

@@ -2,25 +2,25 @@
 /**
  * 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.
+ * Config-driven server that reads markdown project management files
+ * and serves a JSON API. No hardcoded entity names.
  *
  * Usage:
  *   mdboard --project /path/to/workspace --port 3333
  */
 
+'use strict';
+
 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, updateEntity, createEntity, deleteEntity, mergeResults } = require('../core/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,11 +52,11 @@ 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
+// Load configuration (new config engine)
 // ---------------------------------------------------------------------------
 let config = loadConfig(projectDir, process.env.MDBOARD_CONFIG);
 
@@ -86,11 +86,10 @@ function broadcast(data) {
 // ---------------------------------------------------------------------------
 // Model & scanning — sourceStates tracks per-source state
 // ---------------------------------------------------------------------------
-let model = createModel();
+let model = createModel(config);
 const sourceStates = new Map();
 
 function loadSourceConfig(source) {
-  // Try to load per-source mdboard.json
   if (!source._repoRoot) return config;
   const candidates = [
     path.join(source._resolvedPath, 'mdboard.json'),
@@ -107,11 +106,10 @@ function loadSourceConfig(source) {
 }
 
 function scanAll() {
-  model = createModel();
+  model = createModel(config);
   sourceStates.clear();
 
   if (workspace && sources.length > 0) {
-    // Multi-source mode
     const results = [];
     for (const source of sources) {
       const sourcePath = source._resolvedPath;
@@ -126,21 +124,21 @@ function scanAll() {
         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 leafType = getLeafType(srcConfig);
+          if (leafType && result.entities[leafType]) {
+            for (const item of result.entities[leafType]) {
+              item._author = getGitAuthor(repoRoot, item._file);
+            }
           }
         }
       }
 
-      // Store per-source state
       sourceStates.set(source.name, {
         model: result,
         config: srcConfig,
@@ -153,25 +151,59 @@ function scanAll() {
     }
     mergeResults(model, results);
   } else {
-    // Legacy single-source mode
     const result = scanSource(projectPath, config, {});
     mergeResults(model, [result]);
   }
 
-  computeProgress(model, config.completedStatus);
+  computeProgress(model, config);
+}
+
+function getLeafType(cfg) {
+  const { flattenHierarchy } = require('../core/config');
+  const flat = flattenHierarchy(cfg);
+  const h = flat.filter(e => !e.standalone);
+  return h.length > 0 ? h[h.length - 1].type : null;
 }
 
 // ---------------------------------------------------------------------------
-// File update helper — resolves correct projectPath per source
+// File update helper
 // ---------------------------------------------------------------------------
 function updateFile(sourceName, relFile, updates) {
+  let sourcePath = projectPath;
+  if (sourceName && sources.length > 0) {
+    const source = sources.find(s => s.name === sourceName);
+    if (source && source._resolvedPath) sourcePath = source._resolvedPath;
+  }
+  return updateEntity(sourcePath, relFile, updates);
+}
+
+// ---------------------------------------------------------------------------
+// CRUD helpers — dynamic, uses entityType not collection name
+// ---------------------------------------------------------------------------
+function createItemFn(sourceName, entityType, data) {
+  let sourcePath = projectPath;
+  let cfg = config;
+
   if (sourceName && sources.length > 0) {
     const source = sources.find(s => s.name === sourceName);
     if (source && source._resolvedPath) {
-      return updateMarkdownFile(source._resolvedPath, relFile, updates);
+      sourcePath = source._resolvedPath;
+      const state = sourceStates.get(sourceName);
+      if (state) cfg = state.config;
     }
   }
-  return updateMarkdownFile(projectPath, relFile, updates);
+
+  const existingItems = model.entities[entityType] || [];
+  return createEntity(sourcePath, cfg, entityType, data, existingItems);
+}
+
+function deleteItemFn(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 deleteEntity(sourcePath, item);
 }
 
 // ---------------------------------------------------------------------------
@@ -179,7 +211,6 @@ function updateFile(sourceName, relFile, updates) {
 // ---------------------------------------------------------------------------
 async function doSyncRemotes() {
   if (!workspace || sources.length === 0) return;
-
   const remoteSources = sources.filter(s => s.type === 'remote');
   if (remoteSources.length === 0) return;
 
@@ -225,6 +256,15 @@ function findCustomCss() {
   return null;
 }
 
+// Cache index.html at startup
+let _indexHtmlCache = null;
+function getIndexHtml() {
+  if (!_indexHtmlCache) {
+    try { _indexHtmlCache = fs.readFileSync(path.join(boardDir, 'index.html')); } catch { /* */ }
+  }
+  return _indexHtmlCache;
+}
+
 function serveStatic(req, res) {
   const url = new URL(req.url, `http://localhost:${port}`);
 
@@ -243,108 +283,57 @@ function serveStatic(req, res) {
     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 });
+  const content = getIndexHtml();
+  if (content) {
+    res.writeHead(200, { 'Content-Type': 'text/html' });
     res.end(content);
-  } catch {
+  } else {
     res.writeHead(404);
     res.end('Not found');
   }
 }
 
 // ---------------------------------------------------------------------------
-// HTTP server
-// ---------------------------------------------------------------------------
-// ---------------------------------------------------------------------------
-// CRUD helpers — resolve source path and delegate to scanner
+// API context
 // ---------------------------------------------------------------------------
-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 projectDir() { return projectDir; },
   get sources() { return sources; },
   get sourceStates() { return sourceStates; },
   sseClients,
   broadcast,
   updateFile,
   rescanAll: () => scanAll(),
+  reloadConfig: () => reloadConfig(),
   syncRemotes: doSyncRemotes,
   createItem: createItemFn,
-  archiveItem: archiveItemFn,
+  deleteItem: deleteItemFn,
+  get hasProject() {
+    return fs.existsSync(path.join(projectDir, 'project')) ||
+      (workspace && sources.length > 0);
+  },
+  loadProject: loadProject,
+  getProjectHistory: () => getHistory(projectDir),
+  get workspacePath() {
+    return workspace ? workspace._path : (workspacePath || path.join(projectDir, 'workspace.json'));
+  },
+  onWorkspaceChange() {
+    workspace = loadWorkspace(projectDir, workspacePath);
+    sources = workspace ? workspace.sources : [];
+    closeWatchers(activeWatchers);
+    scanAll();
+    activeWatchers = setupWatchers(buildWatcherOpts());
+    doSyncRemotes().catch(() => {});
+    broadcast({ type: 'update', timestamp: new Date().toISOString() });
+  },
 };
 
+// ---------------------------------------------------------------------------
+// HTTP server
+// ---------------------------------------------------------------------------
 const server = http.createServer(async (req, res) => {
   try {
     if (req.url.startsWith('/api/')) {
@@ -371,33 +360,71 @@ 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.
+ */
+function loadProject(newProjectDir) {
+  closeWatchers(activeWatchers);
+  if (syncInterval) clearInterval(syncInterval);
+  syncInterval = null;
+
+  projectDir = path.resolve(newProjectDir);
+  projectPath = path.join(projectDir, 'project');
+  workspacePath = null;
+
+  // Clear startup preset so each project resolves its own
+  delete process.env.MDBOARD_PRESET;
+
+  config = loadConfig(projectDir);
+  workspace = loadWorkspace(projectDir, null);
+  sources = workspace ? workspace.sources : [];
+
+  scanAll();
+  activeWatchers = setupWatchers(buildWatcherOpts());
+
+  doSyncRemotes().catch(() => {});
+  startSyncInterval();
+
+  const projName = (model.project && model.project.name) || path.basename(projectDir);
+  registerProject(projectDir, projName);
+  broadcast({ type: 'project-changed', projectDir });
+}
 
 // Initial async sync + start periodic sync
 doSyncRemotes().catch(() => {});
@@ -407,11 +434,27 @@ server.listen(port, () => {
   const sourceInfo = workspace && sources.length > 0
     ? `\n     Sources: ${sources.map(s => s.label || s.name).join(', ')}`
     : '';
+  const watchCount = activeWatchers.length;
+
+  // Resolve leaf type for tips
+  const { flattenHierarchy } = require('../core/config');
+  const flat = flattenHierarchy(config);
+  const hierarchy = flat.filter(e => !e.standalone);
+  const leafType = hierarchy.length > 0 ? hierarchy[hierarchy.length - 1].type : null;
+
   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...' : ''}
+     Server:  http://localhost:${port}${config._entitiesPath ? '\n     Config:  ' + config._entitiesPath : ''}${sourceInfo}
+${watchCount > 0 ? '\n     Watching ' + watchCount + ' director' + (watchCount === 1 ? 'y' : 'ies') + ' for changes...' : ''}
+  Open in browser:
+     http://localhost:${port}
+
+  Quick start:
+     mdboard config             Setup preferences & AI skill
+     mdboard preset list        Switch methodology (scrum, kanban, ...)
+     mdboard skill              Add AI skill to your IDE${leafType ? '\n     mdboard create ' + leafType + ' "title"   Create a new ' + leafType : ''}
+     mdboard --help             Show all commands
 `);
 });
 
@@ -426,6 +469,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 +478,9 @@ process.on('SIGINT', () => {
 
 process.on('SIGTERM', () => {
   if (syncInterval) clearInterval(syncInterval);
+  closeWatchers(activeWatchers);
   server.close(() => process.exit(0));
 });
+
+// Export for programmatic use in tests
+module.exports = { server, scanAll, apiCtx };

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 };