@entelligentsia/forgecli 0.8.4 → 0.9.0

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

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

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

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

@@ -1,151 +0,0 @@
-'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

@@ -1,67 +0,0 @@
-'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);
-}