@entelligentsia/forgecli 0.7.10 → 0.9.0

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

@@ -1,326 +0,0 @@
-#!/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

@@ -1,226 +0,0 @@
-#!/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,
-};