mdboard 1.0.0 → 1.2.0

package/init.js

@@ -2,11 +2,13 @@
 
 const fs = require('fs');
 const path = require('path');
+const { loadConfig } = require('./config');
 
 const cwd = process.cwd();
 const projectPath = path.join(cwd, 'project');
 const projectName = path.basename(cwd);
 const today = new Date().toISOString().split('T')[0];
+const config = loadConfig(cwd);
 
 if (fs.existsSync(projectPath)) {
   console.log(`\n  project/ already exists at ${projectPath}`);
@@ -14,9 +16,11 @@ if (fs.existsSync(projectPath)) {
   process.exit(0);
 }
 
+const msDir = config.entities.milestone.dir;
+
 // Create directories
 fs.mkdirSync(projectPath, { recursive: true });
-fs.mkdirSync(path.join(projectPath, 'milestones'), { recursive: true });
+fs.mkdirSync(path.join(projectPath, msDir), { recursive: true });
 fs.mkdirSync(path.join(projectPath, 'archive'), { recursive: true });
 
 // PROJECT.md
@@ -52,17 +56,54 @@ updated: ${today}
 
 `, 'utf-8');
 
+// mdboard.json — example config
+fs.writeFileSync(path.join(projectPath, 'mdboard.json'), `{
+  "entities": {
+    "task": {
+      "singular": "Task",
+      "plural": "Tasks",
+      "prefix": "TASK"
+    }
+  }
+}
+`, 'utf-8');
+
+// mdboard.css — example custom theme
+fs.writeFileSync(path.join(projectPath, 'mdboard.css'), `/* mdboard custom theme
+   Override any CSS variable from the dashboard.
+   Example:
+   :root {
+     --bg: #FFFFFF;
+     --surface: #F8F9FA;
+     --text: #212529;
+     --accent: #0969DA;
+   }
+*/
+`, 'utf-8');
+
 console.log(`
   mdboard init — project scaffolded
 
   Created:
     project/PROJECT.md
     project/metrics.md
-    project/milestones/
+    project/${msDir}/
     project/archive/
+    project/mdboard.json
+    project/mdboard.css
 
   Next steps:
     1. Edit project/PROJECT.md with your project details
-    2. Create milestones and epics under project/milestones/
-    3. Run \`mdboard\` to start the dashboard
+    2. Create milestones and epics under project/${msDir}/
+    3. Customize project/mdboard.json for your workflow
+    4. Run \`mdboard\` to start the dashboard
+
+  Multi-repo workspace:
+    Create a workspace.json to manage multiple repos:
+    {
+      "sources": [
+        { "name": "api", "path": "../api-repo", "icon": "🔧" },
+        { "name": "web", "path": "../web-repo", "icon": "🌐" }
+      ]
+    }
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdboard",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Git-based project management dashboard. Reads markdown files with YAML frontmatter and serves a visual kanban board, table, milestones, and metrics views.",
   "main": "./server.js",
   "bin": {
@@ -10,7 +10,14 @@
     "bin.js",
     "server.js",
     "index.html",
-    "init.js"
+    "init.js",
+    "config.js",
+    "defaults.json",
+    "scanner.js",
+    "watcher.js",
+    "api.js",
+    "yaml.js",
+    "workspace.js"
   ],
   "keywords": [
     "project-management",

package/scanner.js

@@ -0,0 +1,491 @@
+/**
+ * mdboard — File scanner and in-memory model
+ *
+ * Scans project directories for markdown files and builds
+ * the in-memory model. Supports multi-source scanning.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { parseFrontmatter, serializeYaml } = require('./yaml');
+
+function createModel() {
+  return {
+    project: null,
+    milestones: [],
+    epics: [],
+    tasks: [],
+    sprints: [],
+    boards: [],
+    reviews: [],
+    metrics: null,
+  };
+}
+
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+function safeDirEntries(dir) {
+  try {
+    return fs.readdirSync(dir).filter(e => !e.startsWith('.'));
+  } catch {
+    return [];
+  }
+}
+
+function isTaskFile(filename, config) {
+  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;
+  }
+  return false;
+}
+
+/**
+ * Scan a single source directory and return all items found.
+ *
+ * @param {string} sourcePath - Absolute path to the project/ directory
+ * @param {object} config - mdboard config object
+ * @param {object} sourceMeta - { name, label, color, type, readonly }
+ * @returns {object} - { project, milestones, epics, tasks, sprints, boards, reviews, metrics }
+ */
+function scanSource(sourcePath, config, sourceMeta) {
+  const result = {
+    project: null,
+    milestones: [],
+    epics: [],
+    tasks: [],
+    sprints: [],
+    boards: [],
+    reviews: [],
+    metrics: null,
+  };
+
+  if (!fs.existsSync(sourcePath)) return result;
+
+  const meta = sourceMeta || {};
+  const sourcePrefix = meta.name ? meta.name + ':' : '';
+
+  function tag(item) {
+    if (meta.name) {
+      item._source = meta.name;
+      item._sourceLabel = meta.label || meta.name;
+      item._sourceColor = meta.color || null;
+      item._sourceType = meta.type || 'local';
+      item._readonly = meta.readonly || false;
+    }
+    return item;
+  }
+
+  function qualifyId(item) {
+    if (sourcePrefix && item.id) {
+      item._originalId = item.id;
+      item.id = sourcePrefix + item.id;
+    }
+    return item;
+  }
+
+  const projectMd = safeReadFile(path.join(sourcePath, 'PROJECT.md'));
+  if (projectMd) {
+    const parsed = parseFrontmatter(projectMd);
+    result.project = tag({ ...parsed.frontmatter, content: parsed.content, _file: 'PROJECT.md' });
+  }
+
+  const metricsMd = safeReadFile(path.join(sourcePath, 'metrics.md'));
+  if (metricsMd) {
+    const parsed = parseFrontmatter(metricsMd);
+    result.metrics = tag({ ...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(sourcePath, 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);
+        result.milestones.push(qualifyId(tag({
+          ...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);
+            result.epics.push(qualifyId(tag({
+              ...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, config)) continue;
+
+              const featContent = safeReadFile(path.join(backlogDir, feat));
+              if (featContent) {
+                const parsed = parseFrontmatter(featContent);
+                result.tasks.push(qualifyId(tag({
+                  ...parsed.frontmatter, content: parsed.content,
+                  _filename: feat, _epic: epic, _milestone: ms,
+                  _file: `${msDir}/${ms}/${epicDir}/${epic}/${taskDir}/${feat}`,
+                })));
+              }
+            }
+          }
+        }
+      }
+
+      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);
+            result.sprints.push(qualifyId(tag({
+              ...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);
+            result.boards.push(tag({
+              ...parsed.frontmatter, content: parsed.content,
+              _dir: sp, _milestone: ms,
+              _file: `${msDir}/${ms}/${sprintDir}/${sp}/board.md`
+            }));
+          }
+
+          const reviewMd = safeReadFile(path.join(spPath, 'review.md'));
+          if (reviewMd) {
+            const parsed = parseFrontmatter(reviewMd);
+            result.reviews.push(tag({
+              ...parsed.frontmatter, content: parsed.content,
+              _dir: sp, _milestone: ms,
+              _file: `${msDir}/${ms}/${sprintDir}/${sp}/review.md`
+            }));
+          }
+        }
+      }
+    }
+  }
+
+  return result;
+}
+
+function computeProgress(model, completedStatus) {
+  for (const epic of model.epics) {
+    const epicTasks = model.tasks.filter(f =>
+      f._epic === epic._dir && f._milestone === epic._milestone &&
+      (!epic._source || f._source === epic._source)
+    );
+    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 &&
+      (!ms._source || f._source === ms._source)
+    );
+    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;
+  }
+}
+
+function updateMarkdownFile(projectPath, 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');
+}
+
+/**
+ * Merge results from multiple scanSource calls into a single model.
+ */
+function mergeResults(model, results) {
+  for (const r of results) {
+    if (r.project && !model.project) model.project = r.project;
+    model.milestones.push(...r.milestones);
+    model.epics.push(...r.epics);
+    model.tasks.push(...r.tasks);
+    model.sprints.push(...r.sprints);
+    model.boards.push(...r.boards);
+    model.reviews.push(...r.reviews);
+    if (r.metrics && !model.metrics) model.metrics = r.metrics;
+  }
+}
+
+/**
+ * Get the next auto-incremented ID for an entity type.
+ *
+ * @param {object[]} items - Existing items array
+ * @param {string} prefix - ID prefix (e.g. "TASK", "MS", "EPIC", "SP")
+ * @returns {string} - Next ID like "TASK-004"
+ */
+function getNextId(items, prefix) {
+  let max = 0;
+  const re = new RegExp('^(?:[\\w]+:)?' + prefix + '-(\\d+)$');
+  for (const item of items) {
+    const id = item._originalId || item.id || '';
+    const m = id.match(re);
+    if (m) {
+      const n = parseInt(m[1], 10);
+      if (n > max) max = n;
+    }
+  }
+  return prefix + '-' + String(max + 1).padStart(3, '0');
+}
+
+/**
+ * Create a new task markdown file.
+ *
+ * @param {string} sourcePath - Absolute path to project/ dir
+ * @param {object} config - mdboard config
+ * @param {object} data - { title, status, priority, points, assigned, sprint, milestone, epic, content }
+ * @param {object[]} existingTasks - Current tasks for ID generation
+ * @returns {object} - { id, file }
+ */
+function createTask(sourcePath, config, data, existingTasks) {
+  const prefix = config.entities.task.prefix;
+  const id = getNextId(existingTasks, prefix);
+  const filename = id + '.md';
+
+  const msDir = config.entities.milestone.dir;
+  const epicDir = config.entities.epic.dir;
+  const taskDir = config.entities.task.dir;
+
+  if (!data.milestone || !data.epic) {
+    throw new Error('milestone and epic are required to create a task');
+  }
+
+  const dir = path.join(sourcePath, msDir, data.milestone, epicDir, data.epic, taskDir);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const fm = {
+    id: id,
+    title: data.title || 'New Task',
+    status: data.status || 'backlog',
+  };
+  if (data.priority) fm.priority = data.priority;
+  if (data.points != null) fm.points = data.points;
+  if (data.assigned) fm.assigned = data.assigned;
+  if (data.sprint) fm.sprint = data.sprint;
+  if (data.links) fm.links = data.links;
+  fm.created = new Date().toISOString().split('T')[0];
+
+  const yaml = serializeYaml(fm);
+  const content = data.content || '';
+  const filePath = path.join(dir, filename);
+  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + content + '\n', 'utf-8');
+
+  const relFile = `${msDir}/${data.milestone}/${epicDir}/${data.epic}/${taskDir}/${filename}`;
+  return { id, file: relFile };
+}
+
+/**
+ * Create a new milestone directory with README.md.
+ *
+ * @param {string} sourcePath - Absolute path to project/ dir
+ * @param {object} config - mdboard config
+ * @param {object} data - { title, status, deadline, content, tracks }
+ * @param {object[]} existingMilestones - Current milestones for ID generation
+ * @returns {object} - { id, dir, file }
+ */
+function createMilestone(sourcePath, config, data, existingMilestones) {
+  const id = getNextId(existingMilestones, 'MS');
+  const slug = (data.title || id).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+  const msDir = config.entities.milestone.dir;
+  const dirPath = path.join(sourcePath, msDir, slug);
+
+  if (fs.existsSync(dirPath)) {
+    throw new Error('Milestone directory already exists: ' + slug);
+  }
+  fs.mkdirSync(dirPath, { recursive: true });
+
+  const fm = {
+    id: id,
+    title: data.title || 'New Milestone',
+    status: data.status || 'planned',
+  };
+  if (data.deadline) fm.deadline = data.deadline;
+  if (data.tracks) fm.tracks = data.tracks;
+  fm.created = new Date().toISOString().split('T')[0];
+
+  const yaml = serializeYaml(fm);
+  const content = data.content || '';
+  const filePath = path.join(dirPath, 'README.md');
+  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + content + '\n', 'utf-8');
+
+  const relFile = `${msDir}/${slug}/README.md`;
+  return { id, dir: slug, file: relFile };
+}
+
+/**
+ * Create a new epic directory with README.md and backlog/.
+ *
+ * @param {string} sourcePath - Absolute path to project/ dir
+ * @param {object} config - mdboard config
+ * @param {object} data - { title, status, priority, milestone, content }
+ * @param {object[]} existingEpics - Current epics for ID generation
+ * @returns {object} - { id, dir, file }
+ */
+function createEpic(sourcePath, config, data, existingEpics) {
+  if (!data.milestone) throw new Error('milestone is required to create an epic');
+
+  const id = getNextId(existingEpics, 'EPIC');
+  const slug = (data.title || id).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+
+  const msDir = config.entities.milestone.dir;
+  const epicDir = config.entities.epic.dir;
+  const taskDir = config.entities.task.dir;
+
+  const dirPath = path.join(sourcePath, msDir, data.milestone, epicDir, slug);
+  if (fs.existsSync(dirPath)) {
+    throw new Error('Epic directory already exists: ' + slug);
+  }
+  fs.mkdirSync(dirPath, { recursive: true });
+  fs.mkdirSync(path.join(dirPath, taskDir), { recursive: true });
+
+  const fm = {
+    id: id,
+    title: data.title || 'New Epic',
+    status: data.status || 'active',
+  };
+  if (data.priority) fm.priority = data.priority;
+  if (data.dependencies) fm.dependencies = data.dependencies;
+  fm.created = new Date().toISOString().split('T')[0];
+
+  const yaml = serializeYaml(fm);
+  const content = data.content || '';
+  const filePath = path.join(dirPath, 'README.md');
+  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + content + '\n', 'utf-8');
+
+  const relFile = `${msDir}/${data.milestone}/${epicDir}/${slug}/README.md`;
+  return { id, dir: slug, file: relFile };
+}
+
+/**
+ * Create a new sprint directory with plan.md.
+ *
+ * @param {string} sourcePath - Absolute path to project/ dir
+ * @param {object} config - mdboard config
+ * @param {object} data - { goal, status, start_date, end_date, milestone, planned_points, features, content }
+ * @param {object[]} existingSprints - Current sprints for ID generation
+ * @returns {object} - { id, dir, file }
+ */
+function createSprint(sourcePath, config, data, existingSprints) {
+  if (!data.milestone) throw new Error('milestone is required to create a sprint');
+
+  const id = getNextId(existingSprints, 'SP');
+  const slug = id.toLowerCase();
+
+  const msDir = config.entities.milestone.dir;
+  const sprintDir = config.entities.sprint.dir;
+
+  const dirPath = path.join(sourcePath, msDir, data.milestone, sprintDir, slug);
+  if (fs.existsSync(dirPath)) {
+    throw new Error('Sprint directory already exists: ' + slug);
+  }
+  fs.mkdirSync(dirPath, { recursive: true });
+
+  const fm = {
+    id: id,
+    status: data.status || 'planned',
+  };
+  if (data.goal) fm.goal = data.goal;
+  if (data.start_date) fm.start_date = data.start_date;
+  if (data.end_date) fm.end_date = data.end_date;
+  if (data.planned_points != null) fm.planned_points = data.planned_points;
+  if (data.features) fm.features = data.features;
+  fm.created = new Date().toISOString().split('T')[0];
+
+  const yaml = serializeYaml(fm);
+  const content = data.content || '';
+  const filePath = path.join(dirPath, 'plan.md');
+  fs.writeFileSync(filePath, '---\n' + yaml + '\n---\n\n' + content + '\n', 'utf-8');
+
+  const relFile = `${msDir}/${data.milestone}/${sprintDir}/${slug}/plan.md`;
+  return { id, dir: slug, file: relFile };
+}
+
+/**
+ * Archive an item by moving its file/directory to project/archive/.
+ *
+ * @param {string} sourcePath - Absolute path to project/ dir
+ * @param {object} item - The item with _file property
+ * @returns {boolean}
+ */
+function archiveItem(sourcePath, item) {
+  if (!item || !item._file) throw new Error('Item has no file path');
+
+  const srcPath = path.join(sourcePath, item._file);
+  if (!fs.existsSync(srcPath)) throw new Error('Source file not found: ' + item._file);
+
+  const archiveDir = path.join(sourcePath, 'archive');
+  fs.mkdirSync(archiveDir, { recursive: true });
+
+  const basename = path.basename(srcPath);
+  const timestamp = Date.now();
+  const destName = timestamp + '-' + basename;
+  const destPath = path.join(archiveDir, destName);
+
+  fs.renameSync(srcPath, destPath);
+  return true;
+}
+
+module.exports = {
+  createModel, scanSource, computeProgress, isTaskFile,
+  safeReadFile, safeDirEntries, updateMarkdownFile, mergeResults,
+  getNextId, createTask, createMilestone, createEpic, createSprint, archiveItem
+};