mdboard 1.0.0

package/server.js

@@ -0,0 +1,711 @@
+#!/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.
+ *
+ * Usage:
+ *   mdboard --project /path/to/workspace --port 3333
+ */
+
+const http = require('http');
+const fs = require('fs');
+const path = require('path');
+const { URL } = require('url');
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+const args = process.argv.slice(2);
+let projectDir = process.cwd();
+let port = 3333;
+
+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 'init':
+    case '-h':
+    case '--help':
+    case '-v':
+    case '--version':
+    case 'help':
+      // These are handled by bin.js; if server.js is called directly, ignore.
+      break;
+  }
+}
+
+const projectPath = path.join(projectDir, 'project');
+const boardDir = __dirname;
+
+// ---------------------------------------------------------------------------
+// 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)
+// ---------------------------------------------------------------------------
+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');
+}
+
+// ---------------------------------------------------------------------------
+// Markdown file updater
+// ---------------------------------------------------------------------------
+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;
+
+  for (const [k, v] of Object.entries(updates)) {
+    if (k === 'content') { body = v; continue; }
+    if (k.startsWith('_')) continue;
+    newFm[k] = v;
+  }
+
+  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
+// ---------------------------------------------------------------------------
+const model = {
+  project: null,
+  milestones: [],
+  epics: [],
+  features: [],
+  sprints: [],
+  boards: [],
+  reviews: [],
+  metrics: null,
+};
+
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function scanAll() {
+  model.project = null;
+  model.milestones = [];
+  model.epics = [];
+  model.features = [];
+  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 milestonesDir = path.join(projectPath, 'milestones');
+  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: `milestones/${ms}/README.md` });
+      }
+
+      const epicsDir = path.join(msPath, 'epics');
+      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: `milestones/${ms}/epics/${epic}/README.md` });
+          }
+
+          const backlogDir = path.join(epicPath, 'backlog');
+          if (fs.existsSync(backlogDir)) {
+            for (const feat of safeDirEntries(backlogDir)) {
+              if (!feat.startsWith('FEAT-') || !feat.endsWith('.md')) continue;
+
+              const featContent = safeReadFile(path.join(backlogDir, feat));
+              if (featContent) {
+                const parsed = parseFrontmatter(featContent);
+                model.features.push({
+                  ...parsed.frontmatter,
+                  content: parsed.content,
+                  _filename: feat,
+                  _epic: epic,
+                  _milestone: ms,
+                  _file: `milestones/${ms}/epics/${epic}/backlog/${feat}`,
+                });
+              }
+            }
+          }
+        }
+      }
+
+      const sprintsDir = path.join(msPath, 'sprints');
+      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: `milestones/${ms}/sprints/${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: `milestones/${ms}/sprints/${sp}/board.md` });
+          }
+
+          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: `milestones/${ms}/sprints/${sp}/review.md` });
+          }
+        }
+      }
+    }
+  }
+
+  computeProgress();
+}
+
+function safeDirEntries(dir) {
+  try {
+    return fs.readdirSync(dir).filter(e => !e.startsWith('.'));
+  } catch {
+    return [];
+  }
+}
+
+function computeProgress() {
+  for (const epic of model.epics) {
+    const epicFeatures = model.features.filter(f => f._epic === epic._dir && f._milestone === epic._milestone);
+    const done = epicFeatures.filter(f => f.status === 'done').length;
+    epic._featureCount = epicFeatures.length;
+    epic._completedCount = done;
+    epic._progress = epicFeatures.length > 0 ? Math.round((done / epicFeatures.length) * 100) : 0;
+    epic._totalPoints = epicFeatures.reduce((sum, f) => sum + (f.points || 0), 0);
+  }
+
+  for (const ms of model.milestones) {
+    const msFeatures = model.features.filter(f => f._milestone === ms._dir);
+    const done = msFeatures.filter(f => f.status === 'done').length;
+    ms._featureCount = msFeatures.length;
+    ms._completedCount = done;
+    ms._progress = msFeatures.length > 0 ? Math.round((done / msFeatures.length) * 100) : 0;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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); }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// File watcher
+// ---------------------------------------------------------------------------
+const watchTimers = new Map();
+
+function setupWatcher() {
+  if (!fs.existsSync(projectPath)) return;
+
+  try {
+    fs.watch(projectPath, { recursive: true }, (eventType, filename) => {
+      if (!filename || !filename.endsWith('.md')) return;
+
+      const key = filename;
+      if (watchTimers.has(key)) clearTimeout(watchTimers.get(key));
+
+      watchTimers.set(key, setTimeout(() => {
+        watchTimers.delete(key);
+        scanAll();
+        broadcast({ type: 'update', file: filename, timestamp: new Date().toISOString() });
+      }, 200));
+    });
+  } catch {
+    console.warn('  Warning: file watching unavailable on this platform');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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));
+}
+
+async function handlePatch(req, res, collection, id) {
+  const body = await parseBody(req);
+
+  let item;
+  switch (collection) {
+    case 'features': item = model.features.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);
+  }
+}
+
+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',
+    });
+    return res.end();
+  }
+
+  // PATCH routes
+  if (req.method === 'PATCH') {
+    let match;
+    if ((match = pathname.match(/^\/api\/features\/(.+)$/))) {
+      return handlePatch(req, res, 'features', decodeURIComponent(match[1]));
+    }
+    if ((match = pathname.match(/^\/api\/epics\/(.+)$/))) {
+      return handlePatch(req, res, 'epics', decodeURIComponent(match[1]));
+    }
+    if ((match = pathname.match(/^\/api\/milestones\/(.+)$/))) {
+      return handlePatch(req, res, 'milestones', decodeURIComponent(match[1]));
+    }
+    if ((match = pathname.match(/^\/api\/sprints\/(.+)$/))) {
+      return handlePatch(req, res, 'sprints', decodeURIComponent(match[1]));
+    }
+    return jsonResponse(res, { error: 'Not found' }, 404);
+  }
+
+  // GET routes
+  switch (pathname) {
+    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/features': {
+      let features = model.features.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) features = features.filter(f => f.status === status);
+      if (epic) features = features.filter(f => f.epic === epic);
+      if (milestone) features = features.filter(f => f.milestone === milestone);
+      if (sprint) features = features.filter(f => f.sprint === sprint);
+
+      return jsonResponse(res, features);
+    }
+
+    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 activeMilestone = model.milestones.find(m => m.status === 'active');
+      const activeSprint = model.sprints.find(s => s.status === 'active');
+      const totalFeatures = model.features.length;
+      const completedFeatures = model.features.filter(f => f.status === 'done').length;
+      const inProgressFeatures = model.features.filter(f => f.status === 'in-progress').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);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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',
+};
+
+function serveStatic(req, res) {
+  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
+// ---------------------------------------------------------------------------
+const server = http.createServer(async (req, res) => {
+  try {
+    if (req.url.startsWith('/api/')) {
+      await handleApi(req, res);
+    } 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 (!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();
+
+server.listen(port, () => {
+  console.log(`
+  mdboard — Project Dashboard
+     Project: ${projectDir}
+     Server:  http://localhost:${port}
+${fs.existsSync(projectPath) ? '\n     Watching project/ 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...');
+  for (const client of sseClients) {
+    try { client.end(); } catch { /* ignore */ }
+  }
+  server.close(() => process.exit(0));
+});
+
+process.on('SIGTERM', () => {
+  server.close(() => process.exit(0));
+});