@entelligentsia/forgecli 0.7.9 → 0.8.4

package/dist/forge-payload/.tools/build-overlay.cjs

@@ -0,0 +1,326 @@
+#!/usr/bin/env node
+'use strict';
+
+// Forge tool: build-overlay
+// Materializes a per-spawn PROJECT_OVERLAY from task/bug record + MASTER_INDEX slice.
+// Usage: node build-overlay.cjs --task <TASK_ID> [--bug <BUG_ID>] [--format json|md]
+
+const fs = require('fs');
+const path = require('path');
+
+const PHASE_ORDER = ['plan', 'review_plan', 'implementation', 'code_review', 'validation'];
+
+try {
+  main();
+} catch (err) {
+  console.error('build-overlay error:', err.message);
+  process.exit(1);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.error('Usage: node build-overlay.cjs --task <TASK_ID> [--bug <BUG_ID>] [--format json|md]');
+    process.exit(1);
+  }
+
+  const taskId = argValue(args, '--task');
+  const bugId  = argValue(args, '--bug');
+  const format = argValue(args, '--format') || 'json';
+
+  if (!taskId && !bugId) {
+    console.error('Error: --task <TASK_ID> or --bug <BUG_ID> required');
+    process.exit(1);
+  }
+
+  const config = loadConfig();
+  const overlay = taskId
+    ? buildTaskOverlay(taskId, config)
+    : buildBugOverlay(bugId, config);
+
+  validateOverlay(overlay);
+
+  if (format === 'md') {
+    process.stdout.write(renderMarkdown(overlay));
+  } else {
+    process.stdout.write(JSON.stringify(overlay, null, 2) + '\n');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Config loading
+// ---------------------------------------------------------------------------
+
+function loadConfig() {
+  let configPath = path.join('.forge', 'config.json');
+  if (!fs.existsSync(configPath)) {
+    // Try parent directories (for development/nested invocation)
+    const parentPath = path.join('..', '.forge', 'config.json');
+    if (fs.existsSync(parentPath)) configPath = parentPath;
+  }
+
+  let config = {};
+  try {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  } catch (_) {}
+
+  return {
+    storeRoot: config.paths?.store || '.forge/store',
+    engineeringRoot: config.paths?.engineering || 'engineering',
+    commands: config.commands || {},
+    projectPrefix: derivePrefix(config),
+  };
+}
+
+function derivePrefix(config) {
+  // Derive the project prefix from config or directory name
+  const cwd = process.cwd();
+  const dirname = path.basename(cwd).toUpperCase().replace(/[^A-Z0-9-]/g, '-');
+  // Return first segment that looks like a prefix (upper-case short token)
+  return dirname.split('-')[0] || 'PROJ';
+}
+
+// ---------------------------------------------------------------------------
+// Task overlay builder
+// ---------------------------------------------------------------------------
+
+function buildTaskOverlay(taskId, config) {
+  const taskPath = path.join(config.storeRoot, 'tasks', `${taskId}.json`);
+  if (!fs.existsSync(taskPath)) {
+    // FR-015: Exit 1 for "task not found" per CLI convention (non-zero = error).
+    // This is intentional — the caller must know the task ID was invalid.
+    throw new Error(`Task not found: ${taskId} (looked at ${taskPath})`);
+  }
+
+  const task = JSON.parse(fs.readFileSync(taskPath, 'utf8'));
+  const indexSlice = extractIndexSlice(taskId, task.sprintId || '', config.storeRoot);
+  const lastPhaseSummary = extractLastPhaseSummary(task);
+
+  const overlay = {
+    projectPrefix: config.projectPrefix,
+    sprintId:      task.sprintId || '',
+    sprintDir:     sprintDirFromId(task.sprintId || ''),
+    taskId:        task.taskId,
+    taskDir:       task.path || '',
+    taskStatus:    task.status || '',
+    storeRoot:     config.storeRoot,
+    indexSlice,
+    toolCommands:  config.commands,
+  };
+
+  if (lastPhaseSummary) {
+    overlay.lastPhaseSummary = lastPhaseSummary;
+  }
+
+  return overlay;
+}
+
+// ---------------------------------------------------------------------------
+// Bug overlay builder
+// ---------------------------------------------------------------------------
+
+function buildBugOverlay(bugId, config) {
+  const bugPath = path.join(config.storeRoot, 'bugs', `${bugId}.json`);
+  if (!fs.existsSync(bugPath)) {
+    throw new Error(`Bug not found: ${bugId} (looked at ${bugPath})`);
+  }
+
+  const bug = JSON.parse(fs.readFileSync(bugPath, 'utf8'));
+  const indexSlice = extractBugIndexSlice(bugId, config.storeRoot);
+  const lastPhaseSummary = extractLastPhaseSummary(bug);
+
+  const overlay = {
+    projectPrefix: config.projectPrefix,
+    bugId:         bug.bugId,
+    bugDir:        bug.path || '',
+    storeRoot:     config.storeRoot,
+    indexSlice,
+    toolCommands:  config.commands,
+  };
+
+  if (lastPhaseSummary) {
+    overlay.lastPhaseSummary = lastPhaseSummary;
+  }
+
+  return overlay;
+}
+
+// ---------------------------------------------------------------------------
+// Index slice extraction (queries the store directly — MASTER_INDEX.md is a
+// downstream view and not the source of truth)
+// ---------------------------------------------------------------------------
+
+function extractIndexSlice(taskId, sprintId, storeRoot) {
+  const tasksDir = path.join(storeRoot, 'tasks');
+  if (!sprintId || !fs.existsSync(tasksDir)) return '';
+
+  const siblings = [];
+  for (const entry of fs.readdirSync(tasksDir)) {
+    if (!entry.endsWith('.json')) continue;
+    try {
+      const rec = JSON.parse(fs.readFileSync(path.join(tasksDir, entry), 'utf8'));
+      if (rec.sprintId === sprintId) siblings.push(rec);
+    } catch (_) { /* skip unreadable */ }
+  }
+  if (!siblings.length) return '';
+
+  siblings.sort((a, b) => (a.taskId || '').localeCompare(b.taskId || ''));
+
+  const lines = [
+    `**Sprint ${sprintId} tasks:**`,
+    '| Task | Title | Status |',
+    '|------|-------|--------|',
+  ];
+  for (const t of siblings) {
+    const marker = t.taskId === taskId ? ' ← this' : '';
+    const title = (t.title || '').replace(/\|/g, '\\|').slice(0, 60);
+    lines.push(`| ${t.taskId}${marker} | ${title} | ${t.status || ''} |`);
+  }
+
+  return budget(lines.join('\n'), 800);
+}
+
+function extractBugIndexSlice(bugId, storeRoot) {
+  const bugsDir = path.join(storeRoot, 'bugs');
+  if (!fs.existsSync(bugsDir)) return '';
+
+  const open = [];
+  let target = null;
+  for (const entry of fs.readdirSync(bugsDir)) {
+    if (!entry.endsWith('.json')) continue;
+    try {
+      const rec = JSON.parse(fs.readFileSync(path.join(bugsDir, entry), 'utf8'));
+      if (rec.bugId === bugId) target = rec;
+      else if (rec.status && !['fixed', 'verified'].includes(rec.status)) open.push(rec);
+    } catch (_) { /* skip */ }
+  }
+
+  const rows = [];
+  if (target) rows.push(target);
+  open.sort((a, b) => (a.bugId || '').localeCompare(b.bugId || ''));
+  rows.push(...open);
+  if (!rows.length) return '';
+
+  const lines = [
+    '**Active bugs:**',
+    '| Bug | Title | Severity | Status |',
+    '|-----|-------|----------|--------|',
+  ];
+  for (const b of rows) {
+    const marker = b.bugId === bugId ? ' ← this' : '';
+    const title = (b.title || '').replace(/\|/g, '\\|').slice(0, 50);
+    lines.push(`| ${b.bugId}${marker} | ${title} | ${b.severity || ''} | ${b.status || ''} |`);
+  }
+
+  return budget(lines.join('\n'), 800);
+}
+
+function budget(text, max) {
+  return text.length <= max ? text : text.slice(0, max - 3) + '...';
+}
+
+// ---------------------------------------------------------------------------
+// Phase summary helpers
+// ---------------------------------------------------------------------------
+
+function extractLastPhaseSummary(record) {
+  if (!record.summaries) return null;
+  // Find the last phase with a summary in canonical order
+  let last = null;
+  let lastPhase = null;
+  for (const phase of PHASE_ORDER) {
+    if (record.summaries[phase]) {
+      last = record.summaries[phase];
+      lastPhase = phase;
+    }
+  }
+  if (!last) return null;
+  return { phase: lastPhase, ...last };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function argValue(args, flag) {
+  const idx = args.indexOf(flag);
+  if (idx === -1) return null;
+  return args[idx + 1] || null;
+}
+
+function sprintDirFromId(sprintId) {
+  if (!sprintId) return '';
+  return sprintId;
+}
+
+// ---------------------------------------------------------------------------
+// Schema validation
+// ---------------------------------------------------------------------------
+
+function validateOverlay(overlay) {
+  const schemaPath = path.join(__dirname, '..', 'schemas', 'project-overlay.schema.json');
+  if (!fs.existsSync(schemaPath)) return; // schema optional at dev time
+
+  const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+  const errors = [];
+
+  for (const req of (schema.required || [])) {
+    if (overlay[req] === undefined) {
+      errors.push(`missing required field: ${req}`);
+    }
+  }
+
+  if (overlay.indexSlice && overlay.indexSlice.length > 800) {
+    errors.push(`indexSlice exceeds 800 chars (${overlay.indexSlice.length})`);
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Overlay schema validation failed:\n${errors.join('\n')}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Markdown rendering
+// ---------------------------------------------------------------------------
+
+function renderMarkdown(overlay) {
+  const lines = ['### Project Overlay\n'];
+
+  if (overlay.taskId) {
+    lines.push(`**Task:** ${overlay.taskId} (${overlay.taskStatus || 'unknown'})`);
+    lines.push(`**Sprint:** ${overlay.sprintId || 'unknown'}`);
+    lines.push(`**Task dir:** ${overlay.taskDir || 'unknown'}`);
+  } else if (overlay.bugId) {
+    lines.push(`**Bug:** ${overlay.bugId}`);
+    lines.push(`**Bug dir:** ${overlay.bugDir || 'unknown'}`);
+  }
+
+  lines.push(`**Store root:** ${overlay.storeRoot}`);
+
+  if (overlay.indexSlice) {
+    lines.push('\n**Sprint context (from index):**');
+    lines.push('```');
+    lines.push(overlay.indexSlice);
+    lines.push('```');
+  }
+
+  if (overlay.lastPhaseSummary) {
+    const s = overlay.lastPhaseSummary;
+    lines.push(`\n**Last phase (${s.phase}):** ${s.objective || ''}`);
+    if (s.key_changes && s.key_changes.length > 0) {
+      lines.push('Key changes:');
+      for (const c of s.key_changes.slice(0, 5)) {
+        lines.push(`- ${c}`);
+      }
+    }
+  }
+
+  if (overlay.toolCommands) {
+    const cmds = overlay.toolCommands;
+    if (cmds.test) lines.push(`\n**Test command:** \`${cmds.test}\``);
+    if (cmds.lint) lines.push(`**Lint command:** \`${cmds.lint}\``);
+  }
+
+  return lines.join('\n') + '\n';
+}

package/dist/forge-payload/.tools/build-persona-pack.cjs

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * build-persona-pack.cjs — compile persona/skill YAML frontmatter from
+ * forge/meta/personas/* and forge/meta/skills/* into a compact JSON pack
+ * at .forge/cache/persona-pack.json. The pack is used by meta-orchestrate
+ * and meta-fix-bug to inject persona references (not verbatim prose) into
+ * subagent prompts.
+ *
+ * CLI:
+ *   node build-persona-pack.cjs [--meta-root <path>] [--out <path>]
+ *
+ * Exported API:
+ *   parseFrontmatter(content, filePath)    → object (throws on missing/malformed)
+ *   buildPack({ personaDir, skillDir })    → pack object
+ *   computeSourceHash({ personaDir, skillDir }) → "sha256:..."
+ *   writePack(pack, outPath)               → atomic write
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+// ── YAML frontmatter parser ──────────────────────────────────────────────────
+// Narrow-scope parser: handles scalars, folded scalars (`>`), block lists
+// (`- item`) under a key, and inline flow lists (`[a, b]`). Anything else
+// throws a descriptive error with the source file path.
+
+function parseFrontmatter(content, filePath) {
+  const lines = content.split(/\r?\n/);
+  if (lines[0] !== '---') {
+    throw new Error(`${filePath}: no frontmatter block found (missing opening '---')`);
+  }
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') { end = i; break; }
+  }
+  if (end === -1) {
+    throw new Error(`${filePath}: frontmatter block is unterminated (missing closing '---')`);
+  }
+  const body = lines.slice(1, end);
+  return parseBlock(body, filePath);
+}
+
+function parseBlock(lines, filePath) {
+  const out = {};
+  let i = 0;
+  while (i < lines.length) {
+    const raw = lines[i];
+    if (raw.trim() === '' || raw.trim().startsWith('#')) { i++; continue; }
+    const m = raw.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
+    if (!m) {
+      throw new Error(`${filePath}: cannot parse frontmatter line ${i + 1}: ${JSON.stringify(raw)}`);
+    }
+    const key = m[1];
+    const rest = m[2];
+
+    // Folded scalar: `>` — consume indented continuation lines
+    if (rest === '>' || rest === '>-' || rest === '>+') {
+      const chunks = [];
+      i++;
+      while (i < lines.length && /^\s+\S/.test(lines[i])) {
+        chunks.push(lines[i].trim());
+        i++;
+      }
+      out[key] = chunks.join(' ').trim();
+      continue;
+    }
+
+    // Inline flow list: `[a, b, c]`
+    if (/^\[.*\]$/.test(rest)) {
+      out[key] = rest
+        .slice(1, -1)
+        .split(',')
+        .map((s) => stripQuotes(s.trim()))
+        .filter((s) => s.length > 0);
+      i++;
+      continue;
+    }
+
+    // Block list: key with no inline value, followed by `- item` lines
+    if (rest === '') {
+      const items = [];
+      i++;
+      while (i < lines.length && /^\s*-\s+/.test(lines[i])) {
+        items.push(lines[i].replace(/^\s*-\s+/, '').trim());
+        i++;
+      }
+      if (items.length === 0) {
+        // empty map value (rare) — leave as empty string
+        out[key] = '';
+      } else {
+        out[key] = items;
+      }
+      continue;
+    }
+
+    // Plain scalar
+    out[key] = stripQuotes(rest.trim());
+    i++;
+  }
+  return out;
+}
+
+function stripQuotes(s) {
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+// ── Pack building ────────────────────────────────────────────────────────────
+
+const REQUIRED_PERSONA_FIELDS = ['id', 'role', 'summary', 'responsibilities', 'outputs', 'file_ref'];
+const REQUIRED_SKILL_FIELDS = ['id', 'applies_to', 'summary', 'capabilities', 'file_ref'];
+
+function listMarkdown(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.md') && f !== 'README.md')
+    .sort()
+    .map((f) => path.join(dir, f));
+}
+
+function loadEntries(dir, requiredFields) {
+  const entries = {};
+  for (const filePath of listMarkdown(dir)) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    let fm;
+    try {
+      fm = parseFrontmatter(content, filePath);
+    } catch (err) {
+      // Re-throw with original path-bearing message intact.
+      throw err;
+    }
+    for (const field of requiredFields) {
+      if (!(field in fm)) {
+        throw new Error(`${filePath}: frontmatter missing required field '${field}'`);
+      }
+    }
+    entries[fm.id] = fm;
+  }
+  return entries;
+}
+
+function buildPack({ personaDir, skillDir }) {
+  const personas = loadEntries(personaDir, REQUIRED_PERSONA_FIELDS);
+  const skills = loadEntries(skillDir, REQUIRED_SKILL_FIELDS);
+  return {
+    version: 1,
+    built_at: new Date().toISOString(),
+    source_hash: computeSourceHash({ personaDir, skillDir }),
+    personas,
+    skills,
+  };
+}
+
+function computeSourceHash({ personaDir, skillDir }) {
+  const files = [...listMarkdown(personaDir), ...listMarkdown(skillDir)].sort();
+  const hash = crypto.createHash('sha256');
+  // FR-012: Content-based hashing for reproducibility.
+  // Old mtime-based hash was non-deterministic across runs after git checkout.
+  // New pattern: filePath\0 + fileContents + \0 — null-byte separators prevent
+  // concatenation ambiguity and make the hash a pure function of content.
+  for (const f of files) {
+    hash.update(`${f}\0`);
+    hash.update(fs.readFileSync(f));
+    hash.update('\0');
+  }
+  return `sha256:${hash.digest('hex')}`;
+}
+
+// ── Atomic write ─────────────────────────────────────────────────────────────
+
+function writePack(pack, outPath) {
+  const dir = path.dirname(outPath);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = outPath + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(pack, null, 2) + '\n', 'utf8');
+  fs.renameSync(tmp, outPath);
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--meta-root') out.metaRoot = argv[++i];
+    else if (a === '--out') out.out = argv[++i];
+    else if (a === '--persona-dir') out.personaDir = argv[++i];
+    else if (a === '--skill-dir') out.skillDir = argv[++i];
+  }
+  return out;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const metaRoot = args.metaRoot || path.resolve(__dirname, '..', 'meta');
+  const personaDir = args.personaDir || path.join(metaRoot, 'personas');
+  const skillDir = args.skillDir || path.join(metaRoot, 'skills');
+  const out = args.out || path.resolve(process.cwd(), '.forge/cache/persona-pack.json');
+
+  const pack = buildPack({ personaDir, skillDir });
+  writePack(pack, out);
+  process.stdout.write(
+    `persona-pack: wrote ${Object.keys(pack.personas).length} personas, ${Object.keys(pack.skills).length} skills → ${out}\n`,
+  );
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (err) {
+    process.stderr.write(`build-persona-pack: ${err.message}\n`);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  parseFrontmatter,
+  buildPack,
+  computeSourceHash,
+  writePack,
+};