mdboard 1.2.0 → 2.0.0

package/src/cli/skill.js

@@ -0,0 +1,417 @@
+/**
+ * mdboard skill — Generate and install AI skill for IDEs/agents
+ *
+ * Generates a dynamic skill document from the current project config
+ * and installs it to the appropriate location for the selected IDE/agent.
+ *
+ * Supported agents:
+ *   - Claude Code (~/.claude/skills/mdboard/SKILL.md)
+ *   - Cursor (.cursor/rules/mdboard.mdc)
+ *   - Windsurf (.windsurf/rules/mdboard.md)
+ *   - VS Code (.claude/skills/mdboard/SKILL.md)
+ *
+ * Usage:
+ *   mdboard skill                   Interactive prompt
+ *   mdboard skill --agent <name>    Install directly
+ *   mdboard skill --path <path>     Install to custom path
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+const configEngine = require('../core/config');
+
+// --- Agent definitions ---
+
+const AGENTS = {
+  'claude-code': {
+    label: 'Claude Code',
+    path: function () { return path.join(os.homedir(), '.claude', 'skills', 'mdboard', 'SKILL.md'); },
+    format: 'skill-md',
+  },
+  'cursor': {
+    label: 'Cursor',
+    path: function () { return path.join(process.cwd(), '.cursor', 'rules', 'mdboard.mdc'); },
+    format: 'mdc',
+  },
+  'windsurf': {
+    label: 'Windsurf',
+    path: function () { return path.join(process.cwd(), '.windsurf', 'rules', 'mdboard.md'); },
+    format: 'skill-md',
+  },
+  'vscode': {
+    label: 'VS Code',
+    path: function () { return path.join(process.cwd(), '.claude', 'skills', 'mdboard', 'SKILL.md'); },
+    format: 'skill-md',
+  },
+};
+
+// --- Skill content generator ---
+
+/**
+ * Generate the skill document content from the current config.
+ *
+ * @param {object} cfg - Loaded config object
+ * @param {string} format - 'skill-md' or 'mdc'
+ * @returns {string}
+ */
+function generateSkillContent(cfg, format) {
+  const types = configEngine.getEntityTypes(cfg);
+  const flat = configEngine.flattenHierarchy(cfg);
+  const hierarchyTypes = flat.filter(function (e) { return !e.standalone; });
+  const standaloneTypes = flat.filter(function (e) { return e.standalone; });
+  const methodology = cfg._preset || 'shape-up';
+
+  // Build hierarchy chain string
+  const hierarchyChain = hierarchyTypes.map(function (e) {
+    var entity = configEngine.getEntity(cfg, e.type);
+    return entity ? entity.singular : e.type;
+  }).join(' > ');
+
+  var lines = [];
+
+  // --- Frontmatter ---
+  if (format === 'mdc') {
+    lines.push('---');
+    lines.push('description: mdboard project management — ' + methodology + ' methodology');
+    lines.push('globs: "project/**/*.md"');
+    lines.push('alwaysApply: true');
+    lines.push('---');
+  } else {
+    lines.push('---');
+    lines.push('name: mdboard');
+    lines.push('description: mdboard project management — ' + methodology + ' methodology');
+    lines.push('---');
+  }
+
+  lines.push('');
+  lines.push('# mdboard — Project Management');
+  lines.push('');
+  lines.push('Manages a **' + methodology + '** project. Entity hierarchy: ' + hierarchyChain + '.');
+  if (standaloneTypes.length > 0) {
+    var standaloneNames = standaloneTypes.map(function (e) {
+      var entity = configEngine.getEntity(cfg, e.type);
+      return entity ? entity.plural : e.type;
+    }).join(', ');
+    lines.push('Standalone entities: ' + standaloneNames + '.');
+  }
+
+  // --- Entity Types ---
+  lines.push('');
+  lines.push('## Entity Types');
+  lines.push('');
+
+  for (var i = 0; i < types.length; i++) {
+    var type = types[i];
+    var entity = configEngine.getEntity(cfg, type);
+    if (!entity) continue;
+
+    var flatEntry = flat.find(function (e) { return e.type === type; });
+    var storage = entity.file === 'PREFIX-NNN.md' ? 'file-per-entity' : 'directory-per-entity';
+    var location = flatEntry ? flatEntry.dir : type;
+    var isStandalone = flatEntry && flatEntry.standalone;
+
+    lines.push('### ' + entity.singular + ' (`' + type + '`)');
+    lines.push('');
+    lines.push('- Prefix: `' + entity.prefix + '`');
+    lines.push('- Storage: ' + storage + ' in `' + location + '/`');
+    if (isStandalone) {
+      lines.push('- Standalone (not in hierarchy)');
+    }
+
+    // Fields
+    var fields = configEngine.getFields(cfg, type);
+    var fieldNames = Object.keys(fields);
+    if (fieldNames.length > 0) {
+      lines.push('- Fields:');
+      for (var f = 0; f < fieldNames.length; f++) {
+        var fname = fieldNames[f];
+        var fdef = fields[fname];
+        var desc = '  - `' + fname + '` (' + fdef.type + ')';
+        if (fdef.type === 'enum' && fdef.values) {
+          desc += ': ' + fdef.values.map(function (v) { return '`' + v.key + '`'; }).join(', ');
+        }
+        if (fdef.type === 'ref') {
+          desc += ' → ' + fdef.entity;
+          if (fdef.multiple) desc += ' (multiple)';
+        }
+        lines.push(desc);
+      }
+    }
+
+    // Statuses shortcut
+    var statuses = configEngine.getStatuses(cfg, type);
+    if (statuses) {
+      lines.push('- Statuses: ' + statuses.map(function (s) { return '`' + s.key + '`'; }).join(', '));
+    }
+
+    lines.push('');
+  }
+
+  // --- Directory Layout ---
+  lines.push('## Directory Layout');
+  lines.push('');
+  lines.push('```');
+  lines.push('project/');
+
+  for (var h = 0; h < hierarchyTypes.length; h++) {
+    var ht = hierarchyTypes[h];
+    var indent = '  '.repeat(h + 1);
+    lines.push(indent + ht.dir + '/');
+    if (h < hierarchyTypes.length - 1) {
+      var nextEntity = configEngine.getEntity(cfg, ht.type);
+      var slug = nextEntity ? nextEntity.prefix.toLowerCase() + '-nnn' : 'slug';
+      lines.push(indent + '  ' + slug + '/');
+    }
+  }
+
+  for (var s = 0; s < standaloneTypes.length; s++) {
+    lines.push('  ' + standaloneTypes[s].dir + '/');
+  }
+
+  lines.push('```');
+  lines.push('');
+
+  // --- Markdown Format ---
+  var leafType = hierarchyTypes.length > 0 ? hierarchyTypes[hierarchyTypes.length - 1].type : types[0];
+  var leafEntity = configEngine.getEntity(cfg, leafType);
+  var leafFields = configEngine.getFields(cfg, leafType);
+
+  lines.push('## Markdown Format');
+  lines.push('');
+  lines.push('Each entity is a markdown file with YAML frontmatter:');
+  lines.push('');
+  lines.push('```markdown');
+  lines.push('---');
+
+  if (leafEntity) {
+    lines.push('title: "Example ' + leafEntity.singular + '"');
+    var lfNames = Object.keys(leafFields);
+    for (var lf = 0; lf < lfNames.length; lf++) {
+      var lfName = lfNames[lf];
+      var lfDef = leafFields[lfName];
+      if (lfDef.type === 'enum' && lfDef.values && lfDef.values.length > 0) {
+        lines.push(lfName + ': ' + (lfDef.default || lfDef.values[0].key));
+      } else if (lfDef.type === 'number') {
+        lines.push(lfName + ': ' + (lfDef.default || 1));
+      } else if (lfDef.type === 'list') {
+        lines.push(lfName + ': []');
+      } else if (lfDef.type === 'date') {
+        lines.push(lfName + ': ' + new Date().toISOString().split('T')[0]);
+      } else if (lfDef.type === 'ref') {
+        lines.push(lfName + ': ' + (lfDef.multiple ? '[]' : '""'));
+      } else {
+        lines.push(lfName + ': ""');
+      }
+    }
+  }
+
+  lines.push('---');
+  lines.push('');
+  lines.push('Content goes here (markdown body).');
+  lines.push('```');
+  lines.push('');
+
+  // --- CLI Commands ---
+  lines.push('## CLI Commands');
+  lines.push('');
+  lines.push('### CRUD');
+  lines.push('');
+
+  for (var ci = 0; ci < types.length; ci++) {
+    var ctype = types[ci];
+    var centity = configEngine.getEntity(cfg, ctype);
+    if (!centity) continue;
+    var ancestors = configEngine.getAncestors(cfg, ctype);
+    var ancestorFlags = ancestors.map(function (a) { return '--' + a.replace(/_/g, '-') + ' <slug>'; }).join(' ');
+    var flagSuffix = ancestorFlags ? ' ' + ancestorFlags : '';
+
+    lines.push('- `mdboard create ' + ctype + ' "title"' + flagSuffix + '`');
+    lines.push('- `mdboard update ' + ctype + ' <id> --field value`');
+    lines.push('- `mdboard delete ' + ctype + ' <id>`');
+    lines.push('- `mdboard list ' + ctype + '`');
+  }
+
+  lines.push('');
+  lines.push('### System');
+  lines.push('');
+  lines.push('- `mdboard` — Start dashboard server');
+  lines.push('- `mdboard init [name]` — Scaffold new project');
+  lines.push('- `mdboard status` — Generate status report');
+  lines.push('- `mdboard config` — Setup preferences & AI skill');
+  lines.push('- `mdboard skill` — Install AI skill to IDE');
+  lines.push('- `mdboard cache list|clean` — Manage cache');
+  lines.push('- `mdboard history list|clean` — Manage history');
+  lines.push('- `mdboard --help` — Show all commands');
+
+  // --- API Endpoints ---
+  lines.push('');
+  lines.push('## API Endpoints');
+  lines.push('');
+  lines.push('Server runs at `http://localhost:3333` by default.');
+  lines.push('');
+  lines.push('### CRUD (per entity type)');
+  lines.push('');
+
+  for (var ai = 0; ai < types.length; ai++) {
+    var atype = types[ai];
+    var aentity = configEngine.getEntity(cfg, atype);
+    if (!aentity) continue;
+    var plural = aentity.plural.toLowerCase();
+    lines.push('- `GET /api/' + plural + '` — List ' + aentity.plural.toLowerCase());
+    lines.push('- `GET /api/' + plural + '/:id` — Get single');
+    lines.push('- `POST /api/' + plural + '` — Create');
+    lines.push('- `PATCH /api/' + plural + '/:id` — Update');
+    lines.push('- `DELETE /api/' + plural + '/:id` — Delete');
+  }
+
+  lines.push('');
+  lines.push('### System');
+  lines.push('');
+  lines.push('- `GET /api/config` — Dashboard configuration');
+  lines.push('- `GET /api/project` — Project metadata');
+  lines.push('- `GET /api/sources` — Workspace sources');
+  lines.push('- `GET /api/metrics` — Aggregated metrics');
+  lines.push('- `GET /api/health` — Project health');
+  lines.push('- `GET /api/status` — Status report');
+  lines.push('- `GET /api/events` — SSE stream');
+
+  // --- Best Practices ---
+  lines.push('');
+  lines.push('## Best Practices');
+  lines.push('');
+  lines.push('- Always use the CLI to create/update/delete entities — it handles ID generation, file placement, and frontmatter.');
+  lines.push('- Parent flags (`--cycle`, `--bet`, etc.) use **slugs** (directory names), not IDs.');
+  lines.push('- Do not manually edit entity IDs or prefixes.');
+  lines.push('- Status values are strict enums — only use the defined values listed above.');
+  lines.push('- Entity files live inside `project/` — respect the hierarchy structure.');
+  lines.push('- Use `mdboard status` to generate a summary report.');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// --- Installer ---
+
+/**
+ * Install the skill file to the given path.
+ *
+ * @param {string} projectDir - Project directory (for config loading)
+ * @param {string} filePath - Absolute path to write the skill file
+ * @param {string} format - 'skill-md' or 'mdc'
+ */
+function installSkill(projectDir, filePath, format) {
+  var cfg = configEngine.loadConfig(projectDir, process.env.MDBOARD_CONFIG);
+  var content = generateSkillContent(cfg, format);
+
+  // Create directories
+  var dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  fs.writeFileSync(filePath, content, 'utf-8');
+}
+
+// --- CLI runner ---
+
+/**
+ * Run the skill command.
+ *
+ * @param {string[]} args - CLI arguments after 'skill'
+ */
+function run(args) {
+  var agentName = null;
+  var customPath = null;
+
+  for (var i = 0; i < args.length; i++) {
+    if (args[i] === '--agent' && args[i + 1]) {
+      agentName = args[i + 1];
+      i++;
+    } else if (args[i] === '--path' && args[i + 1]) {
+      customPath = args[i + 1];
+      i++;
+    }
+  }
+
+  // Direct install with --agent
+  if (agentName) {
+    var agent = AGENTS[agentName];
+    if (!agent) {
+      console.error('  Error: unknown agent "' + agentName + '"');
+      console.error('  Available: ' + Object.keys(AGENTS).join(', '));
+      process.exit(1);
+    }
+    var filePath = agent.path();
+    installSkill(process.cwd(), filePath, agent.format);
+    console.log('\n  Skill installed: ' + agent.label);
+    console.log('  Path: ' + filePath + '\n');
+    process.exit(0);
+  }
+
+  // Direct install with --path
+  if (customPath) {
+    var resolved = path.resolve(customPath);
+    var fmt = resolved.endsWith('.mdc') ? 'mdc' : 'skill-md';
+    installSkill(process.cwd(), resolved, fmt);
+    console.log('\n  Skill installed: ' + resolved + '\n');
+    process.exit(0);
+  }
+
+  // Interactive prompt
+  var rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  console.log('\n  mdboard skill — Install AI skill to your IDE\n');
+  console.log('  Select target:\n');
+  console.log('    1) Claude Code     ~/.claude/skills/mdboard/SKILL.md');
+  console.log('    2) Cursor          .cursor/rules/mdboard.mdc');
+  console.log('    3) Windsurf        .windsurf/rules/mdboard.md');
+  console.log('    4) VS Code         .claude/skills/mdboard/SKILL.md');
+  console.log('    5) Custom path');
+  console.log('    6) Skip\n');
+
+  rl.question('  Choice [1-6]: ', function (answer) {
+    var choice = answer.trim();
+
+    if (choice === '6' || choice === '') {
+      console.log('  Skipped.\n');
+      rl.close();
+      process.exit(0);
+      return;
+    }
+
+    if (choice === '5') {
+      rl.question('  Path: ', function (pathAnswer) {
+        var p = path.resolve(pathAnswer.trim());
+        var f = p.endsWith('.mdc') ? 'mdc' : 'skill-md';
+        installSkill(process.cwd(), p, f);
+        console.log('\n  Skill installed: ' + p + '\n');
+        rl.close();
+        process.exit(0);
+      });
+      return;
+    }
+
+    var agentKeys = ['claude-code', 'cursor', 'windsurf', 'vscode'];
+    var idx = parseInt(choice, 10) - 1;
+    if (idx < 0 || idx >= agentKeys.length) {
+      console.error('  Invalid choice.');
+      rl.close();
+      process.exit(1);
+      return;
+    }
+
+    var selected = AGENTS[agentKeys[idx]];
+    var fp = selected.path();
+    installSkill(process.cwd(), fp, selected.format);
+    console.log('\n  Skill installed: ' + selected.label);
+    console.log('  Path: ' + fp + '\n');
+    rl.close();
+    process.exit(0);
+  });
+}
+
+module.exports = { run, installSkill, generateSkillContent, AGENTS };

package/src/cli/status.js

@@ -0,0 +1,180 @@
+/**
+ * mdboard — Status generator (config-driven)
+ *
+ * Generates project/status.md with computed project status.
+ * All entity types come from config — no hardcoded names.
+ *
+ * Usage: mdboard status [--project <path>]
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { buildModel } = require('./cli');
+const {
+  getEntityTypes, getEntity, flattenHierarchy, isCompletedStatus,
+} = require('../core/config');
+
+/**
+ * Generate project/status.md
+ *
+ * @param {string} projectDir - Workspace root directory
+ */
+function generateStatus(projectDir) {
+  const { model, config: cfg, projectPath } = buildModel(projectDir);
+  const status = computeStatus(model, cfg);
+
+  const projectName = (model.project && model.project.name) || path.basename(projectDir);
+  const lines = [];
+
+  // Frontmatter
+  lines.push('---');
+  lines.push('generated: ' + status.generated);
+  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 table
+  lines.push('## Summary');
+  lines.push('');
+  lines.push('| Entity | Total | Completed | Progress |');
+  lines.push('|--------|-------|-----------|----------|');
+  for (var i = 0; i < status.summary.length; i++) {
+    var s = status.summary[i];
+    var extra = s.points ? ' (' + s.completedPoints + '/' + s.points + ' pts)' : '';
+    lines.push('| ' + s.label + ' | ' + s.total + ' | ' + s.completed + ' | ' + s.percent + '%' + extra + ' |');
+  }
+  lines.push('');
+
+  // Hierarchy sections
+  for (var hi = 0; hi < status.hierarchy.length; hi++) {
+    var h = status.hierarchy[hi];
+    lines.push('## ' + h.label);
+    lines.push('');
+    for (var j = 0; j < h.items.length; j++) {
+      var item = h.items[j];
+      lines.push('### ' + item.id + ': ' + (item.title || '') + ' [' + (item.status || '-') + '] (' + item.progress + '%)');
+      lines.push('- Children: ' + item._completedCount + '/' + item._childCount + ' done');
+      lines.push('');
+    }
+  }
+
+  // Breakdown
+  for (var type in status.breakdown) {
+    var entity = getEntity(cfg, type);
+    var label = entity ? entity.plural : type;
+    lines.push('## ' + label + ' by Status');
+    lines.push('');
+    var groups = status.breakdown[type];
+    for (var statusKey in groups) {
+      lines.push('- **' + capitalize(statusKey) + '**: ' + groups[statusKey]);
+    }
+    lines.push('');
+  }
+
+  var content = lines.join('\n') + '\n';
+
+  // Write to project/status.md
+  var 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));
+  var summaryLine = status.summary.map(function(s) { return s.total + ' ' + s.label.toLowerCase(); }).join(', ');
+  console.log('  ' + summaryLine);
+}
+
+/**
+ * Compute status data from model and config.
+ * Returns the JSON structure served by GET /api/status.
+ */
+function computeStatus(model, cfg) {
+  var types = getEntityTypes(cfg);
+  var flat = flattenHierarchy(cfg);
+  var hierarchyTypes = flat.filter(function(e) { return !e.standalone; });
+  var leafType = hierarchyTypes.length > 0 ? hierarchyTypes[hierarchyTypes.length - 1].type : null;
+
+  // Summary: per entity type
+  var summary = [];
+  for (var i = 0; i < types.length; i++) {
+    var type = types[i];
+    var entity = getEntity(cfg, type);
+    var items = model.entities[type] || [];
+    var total = items.length;
+    var completed = items.filter(function(it) { return isCompletedStatus(cfg, it.status); }).length;
+    var percent = total > 0 ? Math.round(completed / total * 100) : 0;
+    var entry = {
+      type: type,
+      label: entity ? entity.plural : type,
+      total: total,
+      completed: completed,
+      percent: percent,
+    };
+
+    // Points for leaf type
+    if (type === leafType) {
+      entry.points = items.reduce(function(sum, it) { return sum + (it.points || 0); }, 0);
+      entry.completedPoints = items
+        .filter(function(it) { return isCompletedStatus(cfg, it.status); })
+        .reduce(function(sum, it) { return sum + (it.points || 0); }, 0);
+    }
+
+    summary.push(entry);
+  }
+
+  // Hierarchy: non-leaf types with progress
+  var hierarchy = [];
+  for (var hi = 0; hi < hierarchyTypes.length; hi++) {
+    var ht = hierarchyTypes[hi];
+    if (ht.type === leafType) continue;
+    var hEntity = getEntity(cfg, ht.type);
+    var hItems = model.entities[ht.type] || [];
+    var hMapped = hItems.map(function(it) {
+      return {
+        id: it.id,
+        title: it.title || '',
+        status: it.status || '',
+        progress: it._progress || 0,
+        _childCount: it._childCount || 0,
+        _completedCount: it._completedCount || 0,
+      };
+    });
+    hierarchy.push({
+      type: ht.type,
+      label: hEntity ? hEntity.plural : ht.type,
+      items: hMapped,
+    });
+  }
+
+  // Breakdown: leaf items grouped by status
+  var breakdown = {};
+  if (leafType) {
+    var leafItems = model.entities[leafType] || [];
+    var groups = {};
+    for (var li = 0; li < leafItems.length; li++) {
+      var st = leafItems[li].status || 'unknown';
+      groups[st] = (groups[st] || 0) + 1;
+    }
+    breakdown[leafType] = groups;
+  }
+
+  var projectName = (model.project && model.project.name) || '';
+
+  return {
+    generated: new Date().toISOString(),
+    project: { name: projectName },
+    summary: summary,
+    hierarchy: hierarchy,
+    breakdown: breakdown,
+  };
+}
+
+function capitalize(str) {
+  return str.replace(/(^|-)(\w)/g, function(_, sep, c) { return (sep ? ' ' : '') + c.toUpperCase(); });
+}
+
+module.exports = { generateStatus, computeStatus };