mdboard 1.3.0 → 2.1.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 };