@entelligentsia/forgecli 0.7.9 → 0.7.10

package/dist/forge-payload/.tools/manage-versions.cjs

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+'use strict';
+
+// Forge tool: manage-versions
+// Manage .forge/structure-versions.json — snapshot lifecycle for structural elements.
+//
+// Subcommands:
+//   init         Write snapshot 0 at first init (idempotent: no-op if file exists)
+//   current      Print current snapshot index and metadata
+//   list         Print tabular summary of all snapshots
+//   add-snapshot Archive current structural elements and record a new snapshot entry
+//
+// Composition model: Working Artifact = base@pluginVersion + snapshot@currentSnapshot + user_enhancements
+// Snapshot-array invariant: snapshots is ordered ascending by index; currentSnapshot always equals
+//   snapshots[snapshots.length - 1].index.
+//
+// Usage:
+//   node manage-versions.cjs init [--dry-run]
+//   node manage-versions.cjs current
+//   node manage-versions.cjs list
+//   node manage-versions.cjs add-snapshot --source <source> [--enhanced-elements <csv>] [--dry-run]
+//     --source <string>              Required. One of: post-init | post-sprint:<ID> | on-demand
+//     --enhanced-elements <csv>      Optional. Comma-separated list of .forge/-relative paths that were enhanced.
+//     --dry-run                      Log intent without performing I/O.
+//
+// Environment:
+//   FORGE_ROOT — path to forge plugin root (used by init to locate plugin.json and schemas)
+//   Falls back to auto-detection via ../../ from __dirname when FORGE_ROOT is unset.
+
+const fs = require('fs');
+const path = require('path');
+const { resolveForgeRoot } = require('./lib/forge-root.cjs');
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+// Relative path suffix for structure-versions.json (from project root)
+const VERSIONS_SUFFIX = path.join('.forge', 'structure-versions.json');
+
+// Default project root is cwd when used as CLI; exports allow test injection.
+const VERSIONS_PATH = path.join(process.cwd(), VERSIONS_SUFFIX);
+
+// ---------------------------------------------------------------------------
+// Exported helpers (used by unit tests and callers)
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the path to structure-versions.json for the given project root.
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+function versionsPath(projectRoot) {
+  return path.join(projectRoot, VERSIONS_SUFFIX);
+}
+
+/**
+ * Read and parse .forge/structure-versions.json.
+ * @param {string} projectRoot
+ * @returns {object} parsed document
+ * @throws {Error} when file does not exist or cannot be parsed
+ */
+function readStructureVersions(projectRoot) {
+  const filePath = versionsPath(projectRoot);
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`structure-versions.json not found at ${filePath}. Run \`manage-versions init\` first.`);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (e) {
+    throw new Error(`Failed to parse structure-versions.json at ${filePath}: ${e.message}`);
+  }
+}
+
+/**
+ * Write data to .forge/structure-versions.json atomically via .tmp.PID rename.
+ * @param {string} projectRoot
+ * @param {object} data
+ */
+function writeStructureVersions(projectRoot, data) {
+  const filePath = versionsPath(projectRoot);
+  const json = JSON.stringify(data, null, 2) + '\n';
+  const tmp = filePath + '.tmp.' + process.pid;
+  try {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(tmp, json, 'utf8');
+    fs.renameSync(tmp, filePath);
+  } catch (e) {
+    try { fs.unlinkSync(tmp); } catch {}
+    throw new Error(`Failed to write structure-versions.json: ${e.message}`);
+  }
+}
+
+/**
+ * Resolve forge root from env or __dirname fallback.
+ * Delegates to the shared forge-root.cjs helper (FR-001).
+ * @param {string} [envForgeRoot] - value of FORGE_ROOT env var
+ * @returns {string}
+ */
+
+/**
+ * Read the plugin version from FORGE_ROOT/.claude-plugin/plugin.json.
+ * @param {string} forgeRoot
+ * @returns {string}
+ */
+function readPluginVersion(forgeRoot) {
+  const pluginPath = path.join(forgeRoot, '.claude-plugin', 'plugin.json');
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pluginPath, 'utf8'));
+    if (!pkg.version) throw new Error('version field missing');
+    return pkg.version;
+  } catch (e) {
+    throw new Error(`Failed to read plugin version from ${pluginPath}: ${e.message}`);
+  }
+}
+
+/**
+ * Read the overlay tool version from FORGE_ROOT/schemas/project-overlay.schema.json.
+ * Falls back to "1.0.0" if the schema does not contain a version field.
+ * @param {string} forgeRoot
+ * @returns {string}
+ */
+function readOverlayToolVersion(forgeRoot) {
+  const schemaPath = path.join(forgeRoot, 'schemas', 'project-overlay.schema.json');
+  try {
+    const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+    if (typeof schema.version === 'string' && schema.version) {
+      return schema.version;
+    }
+  } catch {
+    // Schema unreadable — fall back
+  }
+  return '1.0.0';
+}
+
+// Structural element directories that are eligible to be archived.
+const STRUCTURAL_ELEMENT_DIRS = ['personas', 'skills', 'workflows', 'templates'];
+
+/**
+ * Copy a file, creating intermediate directories as needed.
+ * @param {string} src
+ * @param {string} dest
+ */
+function copyFileWithDirs(src, dest) {
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+}
+
+/**
+ * Add a new snapshot entry to structure-versions.json and archive the
+ * current structural elements listed in enhancedElements.
+ *
+ * @param {string} projectRoot        - path to the project root (where .forge/ lives)
+ * @param {string} source             - snapshot source label (post-init | post-sprint:<ID> | on-demand)
+ * @param {string[]} enhancedElements - list of .forge/-relative paths that were enhanced
+ * @param {boolean} [dryRun]          - when true, log intent but perform no I/O
+ */
+function addSnapshot(projectRoot, source, enhancedElements, dryRun) {
+  if (!source) {
+    throw new Error('--source is required for add-snapshot. Provide one of: post-init | post-sprint:<ID> | on-demand');
+  }
+
+  const doc = readStructureVersions(projectRoot);
+  const nextIndex = doc.currentSnapshot + 1;
+  const archivePath = path.join('.forge', 'archive', `snap-${nextIndex}`);
+  const archiveAbsPath = path.join(projectRoot, archivePath);
+
+  // Guard: fail if archive directory already exists to prevent corruption.
+  if (fs.existsSync(archiveAbsPath)) {
+    throw new Error(
+      `Archive directory already exists: ${archiveAbsPath} (snap-${nextIndex}). ` +
+      'Cannot create snapshot — remove or rename the existing archive directory first.'
+    );
+  }
+
+  const createdAt = new Date().toISOString();
+  const newSnapshot = {
+    index: nextIndex,
+    createdAt,
+    source,
+    enhancedElements: enhancedElements || [],
+    archivePath
+  };
+
+  if (dryRun) {
+    console.log(`[dry-run] Would create archive at: ${archiveAbsPath}`);
+    console.log(`[dry-run] Would archive ${(enhancedElements || []).length} element(s).`);
+    console.log(`[dry-run] Would write snapshot entry:`);
+    console.log(JSON.stringify(newSnapshot, null, 2));
+    return;
+  }
+
+  // Archive each enhanced element by copying from .forge/ into the archive dir.
+  for (const relPath of (enhancedElements || [])) {
+    const srcPath = path.join(projectRoot, '.forge', relPath);
+    const destPath = path.join(archiveAbsPath, relPath);
+    if (fs.existsSync(srcPath)) {
+      copyFileWithDirs(srcPath, destPath);
+    }
+    // If the source file does not exist, skip silently — the element list
+    // may reference files that were removed or renamed; archiving what's there
+    // is better than failing the whole snapshot.
+  }
+
+  // Also create the archive directory even if no elements were listed,
+  // so archivePath references a real directory.
+  fs.mkdirSync(archiveAbsPath, { recursive: true });
+
+  // Append snapshot entry and advance currentSnapshot.
+  doc.snapshots.push(newSnapshot);
+  doc.currentSnapshot = nextIndex;
+  writeStructureVersions(projectRoot, doc);
+
+  console.log(`ノ add-snapshot complete — snapshot ${nextIndex} written (source: ${source}, elements: ${(enhancedElements || []).length})`);
+}
+
+/**
+ * Initialise structure-versions.json with snapshot 0.
+ * Idempotent: if the file already exists, exits cleanly without overwriting.
+ *
+ * @param {string} projectRoot - path to the project root (where .forge/ lives)
+ * @param {string} forgeRoot   - path to the forge plugin root
+ * @param {boolean} [dryRun]   - when true, log intent but perform no I/O
+ * @param {string} [source]    - source label for snapshot 0 (default: 'base-pack')
+ */
+function initStructureVersions(projectRoot, forgeRoot, dryRun, source) {
+  const filePath = versionsPath(projectRoot);
+
+  // Idempotency: if the file already exists, do nothing.
+  if (fs.existsSync(filePath)) {
+    console.log(`〇 structure-versions.json already exists — skipping (idempotent).`);
+    return;
+  }
+
+  const effectiveSource = source || 'base-pack';
+  const basePackVersion = readPluginVersion(forgeRoot);
+  const overlayToolVersion = readOverlayToolVersion(forgeRoot);
+
+  const doc = {
+    basePackVersion,
+    overlayToolVersion,
+    currentSnapshot: 0,
+    snapshots: [
+      {
+        index: 0,
+        createdAt: new Date().toISOString(),
+        source: effectiveSource,
+        enhancedElements: [],
+        archivePath: null
+      }
+    ]
+  };
+
+  if (dryRun) {
+    console.log('[dry-run] Would write structure-versions.json:');
+    console.log(JSON.stringify(doc, null, 2));
+    return;
+  }
+
+  writeStructureVersions(projectRoot, doc);
+  console.log(`ノ structure-versions.json written (snapshot 0, source: ${effectiveSource}, plugin: v${basePackVersion})`);
+}
+
+// ---------------------------------------------------------------------------
+// Exports (for unit tests)
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  initStructureVersions,
+  addSnapshot,
+  readStructureVersions,
+  writeStructureVersions,
+  VERSIONS_PATH,
+  versionsPath,
+  readPluginVersion,
+  readOverlayToolVersion,
+};
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+if (require.main === module) {
+
+  process.on('uncaughtException', (error) => {
+    console.error('Fatal manage-versions error:', error.message);
+    process.exit(1);
+  });
+
+  const args = process.argv.slice(2);
+  const DRY_RUN = args.includes('--dry-run');
+  const subcommand = args.find(a => !a.startsWith('--'));
+
+  const forgeRoot = resolveForgeRoot(process.env.FORGE_ROOT);
+  const projectRoot = process.cwd();
+
+  try {
+    switch (subcommand) {
+      case 'init': {
+        const sourceIdx = args.indexOf('--source');
+        const initSource = sourceIdx !== -1 ? args[sourceIdx + 1] : undefined;
+        initStructureVersions(projectRoot, forgeRoot, DRY_RUN, initSource);
+        break;
+      }
+
+      case 'current': {
+        const doc = readStructureVersions(projectRoot);
+        const snap = doc.snapshots.find(s => s.index === doc.currentSnapshot);
+        console.log(`Current snapshot: ${doc.currentSnapshot}`);
+        if (snap) {
+          console.log(`  source:    ${snap.source}`);
+          console.log(`  createdAt: ${snap.createdAt}`);
+          console.log(`  plugin:    v${doc.basePackVersion}`);
+        }
+        break;
+      }
+
+      case 'list': {
+        const doc = readStructureVersions(projectRoot);
+        console.log(`Snapshots (current: ${doc.currentSnapshot}):`);
+        console.log(`${'#'.padEnd(4)} ${'source'.padEnd(20)} ${'createdAt'.padEnd(28)} elements`);
+        console.log('-'.repeat(70));
+        for (const snap of doc.snapshots) {
+          const current = snap.index === doc.currentSnapshot ? '*' : ' ';
+          const elems = snap.enhancedElements ? snap.enhancedElements.length : 0;
+          console.log(`${current}${String(snap.index).padEnd(3)} ${snap.source.padEnd(20)} ${snap.createdAt.padEnd(28)} ${elems}`);
+        }
+        break;
+      }
+
+      case 'add-snapshot': {
+        // Parse --source flag
+        const sourceIdx = args.indexOf('--source');
+        const source = sourceIdx !== -1 ? args[sourceIdx + 1] : null;
+        if (!source || source.startsWith('--')) {
+          console.error('× add-snapshot requires --source <value>.');
+          console.error('  Accepted values: post-init | post-sprint:<SPRINT_ID> | on-demand');
+          process.exit(1);
+        }
+
+        // Parse optional --enhanced-elements flag (comma-separated list)
+        const elementsIdx = args.indexOf('--enhanced-elements');
+        let enhancedElements = [];
+        if (elementsIdx !== -1) {
+          const raw = args[elementsIdx + 1];
+          if (raw && !raw.startsWith('--')) {
+            enhancedElements = raw.split(',').map(s => s.trim()).filter(Boolean);
+          }
+        }
+
+        addSnapshot(projectRoot, source, enhancedElements, DRY_RUN);
+        break;
+      }
+
+      default: {
+        console.error(`× Unknown subcommand: ${subcommand || '(none)'}`);
+        console.error('  Usage: manage-versions.cjs <init|current|list|add-snapshot> [--dry-run]');
+        process.exit(1);
+      }
+    }
+  } catch (err) {
+    console.error(`× manage-versions error: ${err.message}`);
+    process.exit(1);
+  }
+}

package/dist/forge-payload/.tools/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/forge-payload/.tools/parse-gates.cjs

@@ -0,0 +1,151 @@
+'use strict';
+
+// parse-gates.cjs — minimal DSL for per-phase gate declarations.
+//
+// Grammar (closed — unknown directives throw):
+//   artifact <path> [min=<bytes>]
+//   require  <field> <op> <value>
+//   forbid   <field> <op> <value>
+//   after    <phase> = <approved|revision>
+//
+// Predicate ops: ==, !=, in [v1, v2, ...]
+// Blank lines and lines beginning with # (optionally indented) are ignored.
+// Gates live in fenced blocks self-identified by phase via a fence-label
+// attribute, e.g. ```gates phase=implement . The fence is self-contained;
+// gate blocks can appear anywhere in the workflow file without depending on
+// surrounding heading structure.
+
+const FENCE_OPEN = /^```gates\s+phase=([A-Za-z0-9_-]+)\s*$/;
+const FENCE_CLOSE = /^```\s*$/;
+
+const VALID_VERDICTS = new Set(['approved', 'revision']);
+
+function parseGates(markdown) {
+  if (typeof markdown !== 'string' || markdown.length === 0) return {};
+  const lines = markdown.split('\n');
+  const result = {};
+
+  let currentPhase = null;
+  let inFence = false;
+  let fenceStartLine = -1;
+  let fenceBuffer = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNo = i + 1;
+
+    if (!inFence) {
+      const m = line.match(FENCE_OPEN);
+      if (m) {
+        currentPhase = m[1];
+        if (result[currentPhase]) {
+          throw new Error(
+            `parse-gates: line ${lineNo}: duplicate gates block for phase "${currentPhase}"`,
+          );
+        }
+        inFence = true;
+        fenceStartLine = lineNo;
+        fenceBuffer = [];
+      }
+      continue;
+    }
+
+    // Inside a gates fence
+    if (FENCE_CLOSE.test(line)) {
+      result[currentPhase] = parseBlock(fenceBuffer, fenceStartLine);
+      inFence = false;
+      currentPhase = null;
+      continue;
+    }
+    fenceBuffer.push({ text: line, lineNo });
+  }
+
+  if (inFence) {
+    throw new Error(`parse-gates: unterminated \`\`\`gates fence opened at line ${fenceStartLine}`);
+  }
+  return result;
+}
+
+function parseBlock(bufferedLines, _fenceStartLine) {
+  const spec = { artifacts: [], require: [], forbid: [], after: [] };
+  for (const { text, lineNo } of bufferedLines) {
+    const trimmed = text.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) continue;
+
+    const firstSpace = trimmed.search(/\s/);
+    if (firstSpace < 0) {
+      throw new Error(`parse-gates: line ${lineNo}: malformed directive "${trimmed}"`);
+    }
+    const directive = trimmed.slice(0, firstSpace);
+    const rest = trimmed.slice(firstSpace + 1).trim();
+
+    switch (directive) {
+      case 'artifact':
+        spec.artifacts.push(parseArtifact(rest, lineNo));
+        break;
+      case 'require':
+        spec.require.push(parsePredicate(rest, lineNo));
+        break;
+      case 'forbid':
+        spec.forbid.push(parsePredicate(rest, lineNo));
+        break;
+      case 'after':
+        spec.after.push(parseAfter(rest, lineNo));
+        break;
+      default:
+        throw new Error(`parse-gates: line ${lineNo}: unknown directive "${directive}"`);
+    }
+  }
+  return spec;
+}
+
+function parseArtifact(rest, lineNo) {
+  const minMatch = rest.match(/\bmin=(\d+)\s*$/);
+  let path = rest;
+  let minBytes = 0;
+  if (minMatch) {
+    minBytes = parseInt(minMatch[1], 10);
+    path = rest.slice(0, minMatch.index).trim();
+  }
+  if (!path) {
+    throw new Error(`parse-gates: line ${lineNo}: artifact directive missing path`);
+  }
+  return { path, minBytes };
+}
+
+function parsePredicate(rest, lineNo) {
+  // in-list form: <field> in [v1, v2, ...]
+  const inMatch = rest.match(/^(\S+)\s+in\s+\[(.*)\]\s*$/);
+  if (inMatch) {
+    const field = inMatch[1];
+    const value = inMatch[2]
+      .split(',')
+      .map((v) => v.trim())
+      .filter((v) => v.length > 0);
+    return { field, op: 'in', value };
+  }
+  // binary form: <field> <op> <value>
+  const binMatch = rest.match(/^(\S+)\s+(==|!=)\s+(.+?)\s*$/);
+  if (binMatch) {
+    return { field: binMatch[1], op: binMatch[2], value: binMatch[3].trim() };
+  }
+  throw new Error(
+    `parse-gates: line ${lineNo}: unknown predicate op or malformed predicate "${rest}"`,
+  );
+}
+
+function parseAfter(rest, lineNo) {
+  const m = rest.match(/^(\S+)\s*=\s*(\S+)\s*$/);
+  if (!m) {
+    throw new Error(`parse-gates: line ${lineNo}: malformed "after" directive "${rest}"`);
+  }
+  const verdict = m[2].toLowerCase();
+  if (!VALID_VERDICTS.has(verdict)) {
+    throw new Error(
+      `parse-gates: line ${lineNo}: "after" verdict must be "approved" or "revision", got "${m[2]}"`,
+    );
+  }
+  return { phase: m[1], verdict };
+}
+
+module.exports = { parseGates };

package/dist/forge-payload/.tools/parse-verdict.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+// Closed verdict vocabulary. Anything outside this map yields null so the
+// orchestrator halts loudly instead of guessing from reviewer prose.
+const APPROVED = new Set(['approved', 'approve']);
+const REVISION = new Set([
+  'revision required',
+  'revision',
+  'needs revision',
+  'changes requested',
+]);
+
+const VERDICT_LINE = /^[ \t]*\*\*verdict:\*\*[ \t]*(.+?)[ \t]*$/gim;
+
+function parseVerdict(markdown) {
+  if (typeof markdown !== 'string' || markdown.length === 0) return null;
+
+  let lastValue = null;
+  let match;
+  VERDICT_LINE.lastIndex = 0;
+  while ((match = VERDICT_LINE.exec(markdown)) !== null) {
+    lastValue = match[1];
+  }
+  if (lastValue === null) return null;
+
+  const normalised = lastValue
+    .trim()
+    .replace(/^\[(.*)\]$/, '$1')
+    .trim()
+    .toLowerCase();
+
+  if (APPROVED.has(normalised)) return 'approved';
+  if (REVISION.has(normalised)) return 'revision';
+  return null;
+}
+
+module.exports = { parseVerdict };
+
+// CLI shim: `node parse-verdict.cjs <path-to-review.md>`
+// stdout: "approved" | "revision" | "unknown"
+// exit codes: 0 approved, 1 revision, 2 unknown/malformed
+if (require.main === module) {
+  const fs = require('node:fs');
+  const path = process.argv[2];
+  if (!path) {
+    process.stderr.write('Usage: parse-verdict.cjs <path-to-review.md>\n');
+    process.exit(2);
+  }
+  let contents;
+  try {
+    contents = fs.readFileSync(path, 'utf8');
+  } catch (err) {
+    process.stderr.write(`parse-verdict: cannot read ${path}: ${err.message}\n`);
+    process.exit(2);
+  }
+  const verdict = parseVerdict(contents);
+  if (verdict === 'approved') {
+    process.stdout.write('approved\n');
+    process.exit(0);
+  }
+  if (verdict === 'revision') {
+    process.stdout.write('revision\n');
+    process.exit(1);
+  }
+  process.stdout.write('unknown\n');
+  process.exit(2);
+}