@entelligentsia/forgecli 0.10.0 → 0.11.2

package/dist/forge-payload/tools/store.cjs

@@ -56,6 +56,7 @@ class Store {
    * @returns {{ purged: boolean, fileCount: number, files: string[] }}
    */
   purgeEvents(sprintId, opts) { return this.impl.purgeEvents(sprintId, opts); }
+  purgeBugEvents(bugId, opts) { return this.impl.purgeBugEvents(bugId, opts); }
   /**
    * List event filenames for a sprint directory.
    * @param {string} sprintId
@@ -287,6 +288,66 @@ class FSImpl {
     return { purged: true, fileCount: files.length, files };
   }
 
+  /**
+   * Purge only the events belonging to a specific bug from the shared
+   * `.forge/store/events/bugs/` virtual sprint dir.
+   *
+   * Bugs share a single events directory (`events/bugs/`) — see
+   * `meta-fix-bug.md § Event Emission` and `validate-store.spec.md`. Purging
+   * by bug therefore must filter primary events by `event.bugId === bugId`
+   * and sweep sidecars whose filename pattern `_{eventId}_usage.json`
+   * matches a purged primary. The `events/bugs/` directory itself is
+   * never removed — other bugs' events remain.
+   *
+   * Returns `{ purged, fileCount, files }` matching `purgeEvents`.
+   */
+  purgeBugEvents(bugId, { dryRun = false } = {}) {
+    const eventsBugsDir = path.join(this.storeRoot, 'events', 'bugs');
+    if (!fs.existsSync(eventsBugsDir)) {
+      return { purged: false, fileCount: 0, files: [] };
+    }
+
+    const all = fs.readdirSync(eventsBugsDir).filter(f => f.endsWith('.json'));
+    const primaries = all.filter(f => !f.startsWith('_'));
+    const sidecars  = all.filter(f =>  f.startsWith('_') && f.endsWith('_usage.json'));
+
+    // Identify primaries whose payload.bugId matches the requested bug.
+    const matchedPrimaries = [];
+    const matchedEventIds = new Set();
+    for (const filename of primaries) {
+      const filePath = path.join(eventsBugsDir, filename);
+      let payload;
+      try {
+        payload = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      } catch (_) {
+        continue; // malformed file — skip
+      }
+      if (payload && payload.bugId === bugId) {
+        matchedPrimaries.push(filename);
+        if (payload.eventId) matchedEventIds.add(payload.eventId);
+      }
+    }
+
+    // Match sidecars by filename pattern: `_{eventId}_usage.json`.
+    const matchedSidecars = sidecars.filter(filename => {
+      const m = filename.match(/^_(.+)_usage\.json$/);
+      return m && matchedEventIds.has(m[1]);
+    });
+
+    const allMatches = [...matchedPrimaries, ...matchedSidecars];
+    if (dryRun) {
+      return { purged: false, fileCount: allMatches.length, files: allMatches };
+    }
+    for (const filename of allMatches) {
+      fs.unlinkSync(path.join(eventsBugsDir, filename));
+    }
+    return {
+      purged: allMatches.length > 0,
+      fileCount: allMatches.length,
+      files: allMatches,
+    };
+  }
+
   /**
    * List all event filenames for a sprint directory.
    * Returns { filename, id } objects for ALL .json files including

package/dist/forge-payload/tools/substitute-placeholders.cjs

@@ -343,13 +343,14 @@ function renderDeploymentTable(envs) {
  * Advisory Note 3: every output path is resolved and checked to be under outRoot
  * to prevent path traversal via symlinks or '..' segments.
  *
- * @param {string} basePack       — absolute path to the base-pack directory
+ * @param {string} basePack           — absolute path to the base-pack directory
  * @param {Map<string, string>} map
- * @param {string} outRoot        — absolute project root (e.g. '/home/user/myproject')
- * @param {boolean} dryRun        — if true, perform no writes
- * @param {{ warn: function }} io  — pluggable stderr for warnings
+ * @param {string} outRoot            — absolute project root (e.g. '/home/user/myproject')
+ * @param {boolean} dryRun            — if true, perform no writes
+ * @param {{ warn: function }} io     — pluggable stderr for warnings
+ * @param {Set<string>|null} categoryFilter — Defect E: if set, only walk matching subdirs
  */
-function walkBasePack(basePack, map, outRoot, dryRun, io) {
+function walkBasePack(basePack, map, outRoot, dryRun, io, categoryFilter) {
   const warn = (io && io.warn) || ((msg) => process.stderr.write(msg + '\n'));
 
   // Extract prefix from substitution map for commands path computation
@@ -363,6 +364,11 @@ function walkBasePack(basePack, map, outRoot, dryRun, io) {
     const stat = fs.statSync(subdirPath);
     if (!stat.isDirectory()) continue;
 
+    // Defect E: skip subdirs not in the category filter when one is provided
+    if (categoryFilter !== null && categoryFilter !== undefined && !categoryFilter.has(subdir)) {
+      continue;
+    }
+
     let relOutputDir;
     if (subdir === 'commands') {
       relOutputDir = path.join('.claude', 'commands', commandsSubdir);
@@ -464,6 +470,32 @@ function walkBasePackPi(src, outRoot, dryRun, io) {
 if (require.main === module) {
   try {
     const argv = process.argv.slice(2);
+
+    // ── Defect C fix: short-circuit --help/-h BEFORE any path resolution ────────
+    if (argv.includes('--help') || argv.includes('-h')) {
+      process.stdout.write([
+        'substitute-placeholders.cjs — Phase 3 (Materialize) engine.',
+        '',
+        'Usage:',
+        '  node substitute-placeholders.cjs [options]',
+        '',
+        'Options:',
+        '  --target <claude-code|pi>  Output layout target (default: claude-code)',
+        '  --src <path>               Base-pack source dir for --target pi',
+        '  --forge-root <path>        Forge plugin root directory',
+        '  --base-pack <path>         Base-pack directory (probes .base-pack/ then init/base-pack/)',
+        '  --config <path>            Path to .forge/config.json',
+        '  --context <path>           Path to project-context.json',
+        '  --rules <path>             Path to build-base-pack-rules.json',
+        '  --out <path>               Output root directory (default: cwd)',
+        '  --dry-run                  Preview without writing',
+        '  --category <name[,name]>   Limit materialisation to named subdirectories',
+        '                             (personas, skills, workflows, templates, commands)',
+        '  --help, -h                 Show this message and exit',
+      ].join('\n') + '\n');
+      process.exit(0);
+    }
+
     const args = parseCliArgs(argv);
 
     const dryRun = args.dryRun || false;
@@ -515,8 +547,20 @@ if (require.main === module) {
     // Resolve forge root
     const forgeRoot = args.forgeRoot || resolveForgeRoot();
 
-    // Resolve base-pack
-    const basePack = args.basePack || path.join(forgeRoot, 'init', 'base-pack');
+    // Resolve base-pack — Defect C fix: when no --base-pack flag given,
+    // probe .base-pack/ (bundled layout) before init/base-pack (source layout).
+    let basePack;
+    if (args.basePack) {
+      basePack = args.basePack;
+    } else {
+      const dotBasePack = path.resolve(process.cwd(), '.base-pack');
+      const initBasePack = path.join(forgeRoot, 'init', 'base-pack');
+      if (fs.existsSync(dotBasePack)) {
+        basePack = dotBasePack;
+      } else {
+        basePack = initBasePack;
+      }
+    }
     if (!fs.existsSync(basePack)) {
       process.stderr.write(`substitute-placeholders: base-pack not found at ${basePack}\n`);
       process.exit(1);
@@ -563,8 +607,15 @@ if (require.main === module) {
       process.exit(1);
     }
 
+    // Defect E: parse --category flag into a Set<string> filter (or null for all)
+    let categoryFilter = null;
+    if (args.category) {
+      const cats = args.category.split(',').map((c) => c.trim()).filter(Boolean);
+      categoryFilter = new Set(cats);
+    }
+
     // Walk and materialise
-    walkBasePack(basePack, map, outRoot, dryRun, null);
+    walkBasePack(basePack, map, outRoot, dryRun, null, categoryFilter);
 
     if (dryRun) {
       process.stdout.write('substitute-placeholders: dry run complete (no files written)\n');
@@ -593,6 +644,7 @@ function parseCliArgs(argv) {
     if (a === '--context' && argv[i + 1]) { args.context = argv[++i]; continue; }
     if (a === '--rules' && argv[i + 1]) { args.rules = argv[++i]; continue; }
     if (a === '--out' && argv[i + 1]) { args.out = argv[++i]; continue; }
+    if (a === '--category' && argv[i + 1]) { args.category = argv[++i]; continue; }
   }
   return args;
 }

package/dist/forge-payload/tools/validate-store.cjs

@@ -494,8 +494,12 @@ for (const sprint of allSprints) {
 
 // --- Pass 2b: Orphan event directories ---
 // Scan .forge/store/events/ for subdirectories whose name does not match any
-// known sprintId and is not a reserved SYS-* prefix.
-const RESERVED_EVENT_PREFIX = /^SYS-/;
+// known sprintId and is not a reserved virtual dir.
+// Reserved:
+//   - SYS-* — system-generated events that predate sprint records
+//   - bugs  — virtual sprint dir for fix-bug phase events (see
+//             meta/tool-specs/validate-store.spec.md §"event.sprintId")
+const RESERVED_EVENT_PREFIX = /^(SYS-|bugs$)/;
 const eventsBaseDir = path.join(storeRootFromConfig, 'events');
 if (fs.existsSync(eventsBaseDir)) {
   let eventDirEntries;

package/dist/forge-payload/tools/verify-integrity.cjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+'use strict';
+
+// Forge tool: verify-integrity
+// Runtime integrity verifier — reads integrity.json, re-hashes each file, reports drift.
+// Usage: node verify-integrity.cjs [--forge-root <path>]
+// Exit codes: 0 = all clean, 1 = one or more files modified or missing, 2 = manifest missing
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+function computeHash(filePath) {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+function verifyIntegrity(forgeRoot) {
+  const manifestPath = path.join(forgeRoot, 'integrity.json');
+
+  if (!fs.existsSync(manifestPath)) {
+    const output = '× integrity.json not found — run /forge:update to restore';
+    return { exitCode: 1, output, modified: [], missing: [] };
+  }
+
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (e) {
+    const output = `× integrity.json is not valid JSON: ${e.message}`;
+    return { exitCode: 1, output, modified: [], missing: [] };
+  }
+
+  const { files } = manifest;
+  if (!files || typeof files !== 'object') {
+    const output = '× integrity.json has no "files" field';
+    return { exitCode: 1, output, modified: [], missing: [] };
+  }
+
+  const modified = [];
+  const missing = [];
+
+  for (const [rel, expectedHash] of Object.entries(files)) {
+    const abs = path.join(forgeRoot, rel);
+    if (!fs.existsSync(abs)) {
+      missing.push(rel);
+      continue;
+    }
+    const actual = computeHash(abs);
+    if (actual !== expectedHash) {
+      modified.push(rel);
+    }
+  }
+
+  const totalFiles = Object.keys(files).length;
+  const problemCount = modified.length + missing.length;
+
+  if (problemCount === 0) {
+    const output = `〇 Plugin integrity — all ${totalFiles} files unmodified`;
+    return { exitCode: 0, output, modified: [], missing: [] };
+  }
+
+  const lines = [`△ Plugin integrity — ${problemCount} file${problemCount === 1 ? '' : 's'} modified or missing:`];
+  for (const f of modified) {
+    lines.push(`  · ${f} (hash mismatch — run /forge:update to restore)`);
+  }
+  for (const f of missing) {
+    lines.push(`  · ${f} (missing — run /forge:update to restore)`);
+  }
+
+  return { exitCode: 1, output: lines.join('\n'), modified, missing };
+}
+
+module.exports = { verifyIntegrity };
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const forgeRootIdx = args.indexOf('--forge-root');
+  const forgeRoot = forgeRootIdx !== -1
+    ? path.resolve(args[forgeRootIdx + 1])
+    : path.resolve(__dirname, '..');
+
+  const result = verifyIntegrity(forgeRoot);
+  console.log(result.output);
+  process.exit(result.exitCode);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@entelligentsia/forgecli",
-  "version": "0.10.0",
+  "version": "0.11.2",
   "description": "Forge SDLC ported onto @earendil-works/pi-coding-agent — production launcher with three bin aliases (forge/forgecli/4ge). Bundles a curated fork of pi-coding-agent vendored under earendil-works names.",
   "license": "MIT",
   "author": "Entelligentsia",
@@ -49,7 +49,7 @@
     ]
   },
   "forge": {
-    "bundledVersion": "0.43.19",
+    "bundledVersion": "0.44.6",
     "forgeRoot": "../forge/forge"
   },
   "scripts": {