mdboard 1.2.0 → 1.3.0

package/package.json

@@ -1,23 +1,20 @@
 {
   "name": "mdboard",
-  "version": "1.2.0",
+  "version": "1.3.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",
+  "main": "./src/server/server.js",
   "bin": {
     "mdboard": "bin.js"
   },
+  "scripts": {
+    "build": "node build.js"
+  },
   "files": [
     "bin.js",
-    "server.js",
+    "build.js",
     "index.html",
-    "init.js",
-    "config.js",
     "defaults.json",
-    "scanner.js",
-    "watcher.js",
-    "api.js",
-    "yaml.js",
-    "workspace.js"
+    "src/"
   ],
   "keywords": [
     "project-management",

package/src/cli/cli.js

@@ -0,0 +1,362 @@
+/**
+ * mdboard — CLI utilities + CRUD handlers
+ *
+ * Provides buildModel() for shared use by status/sync/CRUD,
+ * parseFlags() for CLI argument parsing, and
+ * create/update/delete handlers with reference cleanup.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { loadConfig } = require('../core/config');
+const { loadWorkspace } = require('../core/workspace');
+const {
+  createModel, scanSource, computeProgress, mergeResults,
+  updateMarkdownFile, createTask, createMilestone, createEpic,
+  createSprint, archiveItem,
+} = require('../core/scanner');
+const { parseFrontmatter, serializeYaml } = require('../core/yaml');
+
+/**
+ * Build the full project model from disk.
+ *
+ * @param {string} projectDir - Workspace root directory
+ * @returns {{ model, config, projectPath, workspace, sources }}
+ */
+function buildModel(projectDir) {
+  const projectPath = path.join(projectDir, 'project');
+  const config = loadConfig(projectDir, process.env.MDBOARD_CONFIG);
+  const wsPath = process.env.MDBOARD_WORKSPACE || null;
+  const workspace = loadWorkspace(projectDir, wsPath);
+  const sources = workspace ? workspace.sources : [];
+
+  const model = createModel();
+
+  if (workspace && sources.length > 0) {
+    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,
+      };
+      results.push(scanSource(sourcePath, config, meta));
+    }
+    mergeResults(model, results);
+  } else {
+    mergeResults(model, [scanSource(projectPath, config, {})]);
+  }
+
+  computeProgress(model, config.completedStatus);
+
+  return { model, config, projectPath, workspace, sources };
+}
+
+/**
+ * Parse CLI flags and positional arguments.
+ *
+ * @param {string[]} args - Raw CLI arguments
+ * @returns {{ flags: object, positional: string[] }}
+ */
+const GLOBAL_FLAGS = new Set(['project', 'config', 'workspace']);
+
+function parseFlags(args) {
+  const flags = {};
+  const positional = [];
+
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      const key = args[i].slice(2);
+      const next = args[i + 1];
+      if (GLOBAL_FLAGS.has(key)) {
+        // Skip global flags (consumed by resolveProjectDir / bin.js)
+        if (next && !next.startsWith('--')) i++;
+        continue;
+      }
+      if (next && !next.startsWith('--')) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(args[i]);
+    }
+  }
+
+  return { flags, positional };
+}
+
+/**
+ * Resolve the project directory from args.
+ *
+ * @param {string[]} args - Raw CLI arguments
+ * @returns {string}
+ */
+function resolveProjectDir(args) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--project' && args[i + 1]) {
+      return path.resolve(args[i + 1]);
+    }
+  }
+  return process.cwd();
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// CRUD handlers
+// ═══════════════════════════════════════════════════════════════════════
+
+/**
+ * mdboard create <entity> <title> [flags]
+ */
+function handleCreate(projectDir, args) {
+  const { flags, positional } = parseFlags(args);
+  const entity = positional[0];
+  const title = positional.slice(1).join(' ');
+
+  if (!entity) {
+    console.log(`
+  mdboard create — Create a new entity
+
+  Usage:
+    mdboard create milestone <title>
+    mdboard create epic <title> --milestone <slug>
+    mdboard create task <title> --milestone <slug> --epic <slug> [--priority p] [--points n] [--sprint id]
+    mdboard create sprint --milestone <slug> [--goal "text"]
+`);
+    process.exit(1);
+  }
+
+  const { model, config, projectPath } = buildModel(projectDir);
+
+  switch (entity) {
+    case 'milestone': {
+      if (!title) { console.error('  Error: title is required'); process.exit(1); }
+      const result = createMilestone(projectPath, config, { title }, model.milestones);
+      console.log(`  Created milestone ${result.id}: ${result.file}`);
+      break;
+    }
+
+    case 'epic': {
+      if (!title) { console.error('  Error: title is required'); process.exit(1); }
+      if (!flags.milestone) { console.error('  Error: --milestone is required'); process.exit(1); }
+      const result = createEpic(projectPath, config, {
+        title,
+        milestone: flags.milestone,
+      }, model.epics);
+      console.log(`  Created epic ${result.id}: ${result.file}`);
+      break;
+    }
+
+    case 'task': {
+      if (!title) { console.error('  Error: title is required'); process.exit(1); }
+      if (!flags.milestone) { console.error('  Error: --milestone is required'); process.exit(1); }
+      if (!flags.epic) { console.error('  Error: --epic is required'); process.exit(1); }
+      const data = {
+        title,
+        milestone: flags.milestone,
+        epic: flags.epic,
+      };
+      if (flags.priority) data.priority = flags.priority;
+      if (flags.points) data.points = parseInt(flags.points, 10);
+      if (flags.sprint) data.sprint = flags.sprint;
+      if (flags.assigned) data.assigned = flags.assigned;
+      if (flags.status) data.status = flags.status;
+      const result = createTask(projectPath, config, data, model.tasks);
+      console.log(`  Created task ${result.id}: ${result.file}`);
+      break;
+    }
+
+    case 'sprint': {
+      if (!flags.milestone) { console.error('  Error: --milestone is required'); process.exit(1); }
+      const data = { milestone: flags.milestone };
+      if (flags.goal) data.goal = flags.goal;
+      if (flags.status) data.status = flags.status;
+      const result = createSprint(projectPath, config, data, model.sprints);
+      console.log(`  Created sprint ${result.id}: ${result.file}`);
+      break;
+    }
+
+    default:
+      console.error(`  Error: unknown entity "${entity}". Use: milestone, epic, task, sprint`);
+      process.exit(1);
+  }
+}
+
+/**
+ * mdboard update <entity> <id> [--key value ...]
+ */
+function handleUpdate(projectDir, args) {
+  const { flags, positional } = parseFlags(args);
+  const entity = positional[0];
+  const id = positional[1];
+
+  if (!entity || !id) {
+    console.log(`
+  mdboard update — Update an entity's frontmatter
+
+  Usage:
+    mdboard update task TASK-005 --status in-progress --assigned john
+    mdboard update milestone MS-001 --status active
+    mdboard update epic EPIC-002 --priority high
+    mdboard update sprint SP-003 --status active --goal "New goal"
+`);
+    process.exit(1);
+  }
+
+  const { model, projectPath } = buildModel(projectDir);
+
+  const collectionMap = {
+    task: 'tasks',
+    milestone: 'milestones',
+    epic: 'epics',
+    sprint: 'sprints',
+  };
+
+  const collection = collectionMap[entity];
+  if (!collection) {
+    console.error(`  Error: unknown entity "${entity}". Use: task, milestone, epic, sprint`);
+    process.exit(1);
+  }
+
+  const items = model[collection];
+  const item = items.find(x => x.id === id) || items.find(x => x._originalId === id);
+
+  if (!item) {
+    console.error(`  Error: ${entity} "${id}" not found`);
+    process.exit(1);
+  }
+
+  if (Object.keys(flags).length === 0) {
+    console.error('  Error: no fields to update. Use --key value flags.');
+    process.exit(1);
+  }
+
+  // Convert numeric fields
+  const updates = { ...flags };
+  if (updates.points) updates.points = parseInt(updates.points, 10);
+  if (updates.planned_points) updates.planned_points = parseInt(updates.planned_points, 10);
+
+  updateMarkdownFile(projectPath, item._file, updates);
+  console.log(`  Updated ${entity} ${id}: ${item._file}`);
+}
+
+/**
+ * mdboard delete <entity> <id>
+ */
+function handleDelete(projectDir, args) {
+  const { positional } = parseFlags(args);
+  const entity = positional[0];
+  const id = positional[1];
+
+  if (!entity || !id) {
+    console.log(`
+  mdboard delete — Delete an entity
+
+  Usage:
+    mdboard delete task TASK-005
+    mdboard delete sprint SP-003
+    mdboard delete epic EPIC-002
+    mdboard delete milestone MS-001
+`);
+    process.exit(1);
+  }
+
+  const { model, config, projectPath } = buildModel(projectDir);
+
+  const collectionMap = {
+    task: 'tasks',
+    milestone: 'milestones',
+    epic: 'epics',
+    sprint: 'sprints',
+  };
+
+  const collection = collectionMap[entity];
+  if (!collection) {
+    console.error(`  Error: unknown entity "${entity}". Use: task, milestone, epic, sprint`);
+    process.exit(1);
+  }
+
+  const items = model[collection];
+  const item = items.find(x => x.id === id) || items.find(x => x._originalId === id);
+
+  if (!item) {
+    console.error(`  Error: ${entity} "${id}" not found`);
+    process.exit(1);
+  }
+
+  archiveItem(projectPath, item);
+  console.log(`  Deleted ${entity} ${id}: ${item._file}`);
+
+  // Clean up references
+  const cleaned = cleanReferences(projectPath, model, config, entity, item);
+  if (cleaned > 0) {
+    console.log(`  Cleaned ${cleaned} reference${cleaned > 1 ? 's' : ''}.`);
+  }
+}
+
+/**
+ * Clean up dangling references after deleting an entity.
+ *
+ * @param {string} projectPath - Absolute path to project/ dir
+ * @param {object} model - Current model
+ * @param {object} config - Config object
+ * @param {string} entity - Entity type deleted (task, sprint, epic)
+ * @param {object} deletedItem - The deleted item
+ * @returns {number} - Number of references cleaned
+ */
+function cleanReferences(projectPath, model, config, entity, deletedItem) {
+  let cleaned = 0;
+  const deletedId = deletedItem.id;
+
+  if (entity === 'task') {
+    // Remove task from sprint.features[]
+    for (const sprint of model.sprints) {
+      if (sprint.features && Array.isArray(sprint.features) && sprint.features.includes(deletedId)) {
+        const newFeatures = sprint.features.filter(f => f !== deletedId);
+        updateMarkdownFile(projectPath, sprint._file, { features: newFeatures });
+        cleaned++;
+      }
+    }
+  }
+
+  if (entity === 'sprint') {
+    // Clear task.sprint references
+    for (const task of model.tasks) {
+      if (task.sprint === deletedId) {
+        updateMarkdownFile(projectPath, task._file, { sprint: null });
+        cleaned++;
+      }
+    }
+  }
+
+  if (entity === 'epic') {
+    // Clean epic.dependencies[] references
+    for (const epic of model.epics) {
+      if (epic.dependencies && Array.isArray(epic.dependencies) && epic.dependencies.includes(deletedId)) {
+        const newDeps = epic.dependencies.filter(d => d !== deletedId);
+        updateMarkdownFile(projectPath, epic._file, { dependencies: newDeps });
+        cleaned++;
+      }
+    }
+    // Warn about orphaned tasks
+    const orphanedTasks = model.tasks.filter(t =>
+      t._epic === deletedItem._dir && t._milestone === deletedItem._milestone
+    );
+    if (orphanedTasks.length > 0) {
+      console.log(`  Warning: ${orphanedTasks.length} task(s) under deleted epic may be orphaned.`);
+    }
+  }
+
+  return cleaned;
+}
+
+module.exports = {
+  buildModel, parseFlags, resolveProjectDir,
+  handleCreate, handleUpdate, handleDelete, cleanReferences,
+};

package/src/cli/init.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { loadConfig } = require('../core/config');
+
+const cwd = process.cwd();
+const projectPath = path.join(cwd, 'project');
+const today = new Date().toISOString().split('T')[0];
+const config = loadConfig(cwd);
+
+if (fs.existsSync(projectPath)) {
+  console.log(`\n  project/ already exists at ${projectPath}`);
+  console.log('  Skipping init to avoid overwriting existing data.\n');
+  process.exit(0);
+}
+
+const nameArg = (process.env.MDBOARD_INIT_NAME || '').trim();
+
+if (nameArg) {
+  scaffold(nameArg);
+} else {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.question('  Workspace name: ', function (answer) {
+    rl.close();
+    const name = answer.trim() || path.basename(cwd);
+    scaffold(name);
+  });
+}
+
+function scaffold(name) {
+  const msDir = config.entities.milestone.dir;
+
+  // Create directories
+  fs.mkdirSync(projectPath, { recursive: true });
+  fs.mkdirSync(path.join(projectPath, msDir), { recursive: true });
+  // PROJECT.md
+  fs.writeFileSync(path.join(projectPath, 'PROJECT.md'), `---
+name: "${name}"
+description: ""
+created: ${today}
+---
+
+# ${name}
+
+## Overview
+
+Describe your project here.
+
+## Objectives
+
+-
+
+## Scope
+
+-
+
+`, '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');
+
+  // workspace.json — default workspace with current project as source
+  const wsPath = path.join(cwd, 'workspace.json');
+  if (!fs.existsSync(wsPath)) {
+    fs.writeFileSync(wsPath, JSON.stringify({
+      name: name,
+      sources: [
+        { name: name.toLowerCase().replace(/\s+/g, '-'), label: name, path: ".", color: "#5B6EF5" }
+      ],
+      settings: {}
+    }, null, 2) + '\n', 'utf-8');
+  }
+
+  console.log(`
+  mdboard init — workspace "${name}" scaffolded
+
+  Created:
+    project/PROJECT.md
+    project/${msDir}/
+    project/mdboard.json
+    project/mdboard.css
+    workspace.json
+
+  Next steps:
+    1. Edit project/PROJECT.md with your project details
+    2. Create milestones and epics under project/${msDir}/
+    3. Customize project/mdboard.json for your workflow
+    4. Run \`mdboard\` to start the dashboard
+
+  Add sources to workspace.json to manage multiple repos:
+    {
+      "name": "${name}",
+      "sources": [
+        { "name": "api", "path": "../api-repo", "icon": "🔧" },
+        { "name": "web", "path": "../web-repo", "icon": "🌐" }
+      ]
+    }
+`);
+}

package/src/cli/status.js

@@ -0,0 +1,150 @@
+/**
+ * mdboard — Status generator
+ *
+ * Generates project/status.md with computed project status
+ * from the real model on disk.
+ *
+ * Usage: mdboard status
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { buildModel } = require('./cli');
+
+/**
+ * Generate project/status.md
+ *
+ * @param {string} projectDir - Workspace root directory
+ */
+function generateStatus(projectDir) {
+  const { model, config, projectPath } = buildModel(projectDir);
+
+  const projectName = (model.project && model.project.name) || path.basename(projectDir);
+  const completedStatus = config.completedStatus;
+  const now = new Date().toISOString();
+
+  const lines = [];
+
+  // Frontmatter
+  lines.push('---');
+  lines.push(`generated: ${now}`);
+  lines.push('---');
+  lines.push('');
+  lines.push(`# Project Status: ${projectName}`);
+  lines.push('');
+  lines.push('> Auto-generated by `mdboard status`. Do not edit manually.');
+  lines.push('');
+
+  // Summary
+  const totalTasks = model.tasks.length;
+  const doneTasks = model.tasks.filter(t => t.status === completedStatus).length;
+  const donePercent = totalTasks > 0 ? Math.round((doneTasks / totalTasks) * 100) : 0;
+  const totalPoints = model.tasks.reduce((sum, t) => sum + (t.points || 0), 0);
+  const donePoints = model.tasks.filter(t => t.status === completedStatus)
+    .reduce((sum, t) => sum + (t.points || 0), 0);
+  const pointsPercent = totalPoints > 0 ? Math.round((donePoints / totalPoints) * 100) : 0;
+  const activeMilestones = model.milestones.filter(m => m.status === 'active');
+  const activeSprint = model.sprints.find(s => s.status === 'active');
+
+  lines.push('## Summary');
+  lines.push('');
+  lines.push('| Metric | Value |');
+  lines.push('|--------|-------|');
+  lines.push(`| Milestones | ${model.milestones.length} (${activeMilestones.length} active) |`);
+  lines.push(`| Tasks | ${totalTasks} total, ${doneTasks} done (${donePercent}%) |`);
+  lines.push(`| Points | ${donePoints}/${totalPoints} (${pointsPercent}%) |`);
+  lines.push(`| Active Sprint | ${activeSprint ? activeSprint.id : 'none'} |`);
+  lines.push('');
+
+  // Milestones
+  if (model.milestones.length > 0) {
+    lines.push('## Milestones');
+    lines.push('');
+    for (const ms of model.milestones) {
+      const msEpics = model.epics.filter(e => e._milestone === ms._dir);
+      const msTasks = model.tasks.filter(t => t._milestone === ms._dir);
+      const msDone = msTasks.filter(t => t.status === completedStatus).length;
+      lines.push(`### ${ms.id}: ${ms.title || ms._dir} [${ms.status}] (${ms._progress || 0}%)`);
+      lines.push(`- File: [${ms._file}](${ms._file})`);
+      lines.push(`- Epics: ${msEpics.length}, Tasks: ${msDone}/${msTasks.length} done`);
+      lines.push('');
+    }
+  }
+
+  // Active Sprint
+  if (activeSprint) {
+    lines.push('## Active Sprint');
+    lines.push('');
+    lines.push(`### ${activeSprint.id}`);
+    lines.push(`- File: [${activeSprint._file}](${activeSprint._file})`);
+    if (activeSprint.goal) {
+      lines.push(`- Goal: ${activeSprint.goal}`);
+    }
+
+    const sprintFeatureIds = activeSprint.features || [];
+    const sprintTasks = sprintFeatureIds.length > 0
+      ? model.tasks.filter(t => sprintFeatureIds.includes(t.id))
+      : model.tasks.filter(t => t.sprint === activeSprint.id);
+
+    if (sprintTasks.length > 0) {
+      lines.push('- Tasks:');
+      for (const t of sprintTasks) {
+        lines.push(`  - ${t.id} [${t.status}] ${t.title || ''} -> [${t._file}](${t._file})`);
+      }
+    }
+    lines.push('');
+  }
+
+  // Tasks by status
+  const statusGroups = {};
+  for (const task of model.tasks) {
+    const s = task.status || 'unknown';
+    if (!statusGroups[s]) statusGroups[s] = [];
+    statusGroups[s].push(task);
+  }
+
+  const statusOrder = Object.keys(statusGroups).sort((a, b) => {
+    // Put completed last, in-progress first
+    if (a === completedStatus) return 1;
+    if (b === completedStatus) return -1;
+    if (a === 'in-progress') return -1;
+    if (b === 'in-progress') return 1;
+    return a.localeCompare(b);
+  });
+
+  if (statusOrder.length > 0) {
+    lines.push('## Tasks by Status');
+    lines.push('');
+
+    for (const status of statusOrder) {
+      const tasks = statusGroups[status];
+      lines.push(`### ${capitalize(status)} (${tasks.length})`);
+      lines.push('');
+      lines.push('| ID | Title | Epic | Priority | File |');
+      lines.push('|----|-------|------|----------|------|');
+      for (const t of tasks) {
+        const title = t.title || '';
+        const epic = t._epic || '';
+        const priority = t.priority || '';
+        lines.push(`| ${t.id} | ${title} | ${epic} | ${priority} | [${t._file}](${t._file}) |`);
+      }
+      lines.push('');
+    }
+  }
+
+  const content = lines.join('\n') + '\n';
+
+  // Write to project/status.md
+  const statusPath = path.join(projectPath, 'status.md');
+  fs.mkdirSync(projectPath, { recursive: true });
+  fs.writeFileSync(statusPath, content, 'utf-8');
+
+  console.log(`  mdboard status — Generated ${path.relative(projectDir, statusPath)}`);
+  console.log(`  ${totalTasks} tasks, ${model.milestones.length} milestones, ${model.sprints.length} sprints`);
+}
+
+function capitalize(str) {
+  return str.replace(/(^|-)(\w)/g, (_, sep, c) => (sep ? ' ' : '') + c.toUpperCase());
+}
+
+module.exports = { generateStatus };