@entelligentsia/forgecli 0.7.9 → 0.7.10

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

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+'use strict';
+// store-query.cjs — Forge store query engine CLI
+// Implements exact-args, keyword, and NLP intent paths.
+// Spawned by store-cli.cjs query/nlp/schema dispatch.
+
+const path = require('path');
+
+process.on('uncaughtException', (e) => {
+  process.stderr.write(`Error: ${e.message}\n`);
+  process.exit(1);
+});
+
+const { StoreFacade, loadForgeConfig, resetConfigCache } = require('./lib/store-facade.cjs');
+const { parseIntentNLP, ENTITY_SYNONYMS, STATUS_MAP }    = require('./lib/store-nlp.cjs');
+const { executeQuery, buildResult, kwMatches }            = require('./lib/store-query-exec.cjs');
+
+// ── Argument parser ───────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { _raw: argv.join(' ') };
+  const intentWords = [];
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    switch (a) {
+      case '--sprint':            args.sprint   = argv[++i]; break;
+      case '--task':              args.task     = argv[++i]; break;
+      case '--bug':               args.bug      = argv[++i]; break;
+      case '--feature':           args.feature  = argv[++i]; break;
+      case '--status':            args.status   = argv[++i]; break;
+      case '--keyword':           args.keyword  = argv[++i]; break;
+      case '--type':              args.type     = argv[++i]; break;
+      case '--mode':              args.mode     = argv[++i]; break;
+      case '--with-blockers':     args.withBlockers    = true; break;
+      case '--with-blocked-tasks':args.withBlockedTasks = true; break;
+      case '--with-sprint':       args.withSprint      = true; break;
+      case '--with-feature':      args.withFeature     = true; break;
+      case '--no-excerpts':       args.noExcerpts      = true; break;
+      case '--list-sprints':      args.listSprints     = true; break;
+      case '--help': case '-h':   args.help = true; break;
+      default:
+        if (!a.startsWith('-')) intentWords.push(a);
+        break;
+    }
+    i++;
+  }
+  if (intentWords.length > 0) args.intent = intentWords.join(' ');
+  return args;
+}
+
+function printHelp() {
+  process.stdout.write(`Usage: store-query <command> [options]
+
+Commands:
+  query   Query the Forge store (exact args or NLP intent)
+  nlp     Query the Forge store using NLP intent parser
+  schema  Dump project schema and grammar reference
+
+Query options:
+  --sprint <id>           List tasks/bugs for a sprint
+  --task <id>             Get task details
+  --bug <id>              Get bug details
+  --feature <id>          Get feature + related tasks
+  --list-sprints          List all sprints
+  --status <status>       Filter by status
+  --keyword <term>        Search entity titles
+  --type <entity>         Limit --keyword to sprints|tasks|bugs|features
+  --with-blockers         Follow blockedBy FK on tasks
+  --with-blocked-tasks    Follow blocksTask FK on bugs
+  --with-sprint           Follow sprintId FK
+  --with-feature          Follow featureId FK
+  --no-excerpts           Omit INDEX.md excerpts
+  --mode strict|nlp|off   Engine mode (default: nlp for intent, strict for flags)
+`);
+}
+
+// ── Exact-args query path ─────────────────────────────────────────────────────
+
+function cmdQueryExact(args, store, cfg) {
+  const trace = [];
+  const results = [];
+  const relatedFiles = [];
+  const includeExcerpts = !args.noExcerpts;
+  const filter = {};
+  if (args.status) filter.status = args.status;
+
+  if (args.sprint === 'all' || args.listSprints) {
+    const sprints = store.listSprints(filter);
+    trace.push(`listed all sprints: ${sprints.length}`);
+    for (const s of sprints) results.push(buildResult(s, 'sprint', store, includeExcerpts));
+  } else if (args.sprint) {
+    const sprint = store.getEntity('sprints', args.sprint);
+    const tasks = store.listTasks({ sprintId: args.sprint, ...filter });
+    const bugs  = store.listBugs({ sprintId: args.sprint, ...filter });
+    trace.push(`sprint ${args.sprint}: ${tasks.length} tasks, ${bugs.length} bugs`);
+    if (sprint) results.push(buildResult(sprint, 'sprint', store, includeExcerpts));
+    for (const t of tasks) {
+      results.push(buildResult(t, 'task', store, includeExcerpts));
+      if (args.withBlockers && t.blockedBy) {
+        for (const bugId of (Array.isArray(t.blockedBy) ? t.blockedBy : [t.blockedBy])) {
+          const bug = store.getEntity('bugs', bugId);
+          if (bug) { results.push(buildResult(bug, 'bug', store, includeExcerpts)); trace.push(`followed blockedBy → ${bugId}`); }
+        }
+      }
+    }
+    for (const b of bugs) results.push(buildResult(b, 'bug', store, includeExcerpts));
+  } else if (args.task) {
+    const task = store.getEntity('tasks', args.task);
+    if (task) {
+      results.push(buildResult(task, 'task', store, includeExcerpts));
+      if (args.withSprint && task.sprintId) {
+        const s = store.getEntity('sprints', task.sprintId);
+        if (s) { results.push(buildResult(s, 'sprint', store, includeExcerpts)); trace.push(`followed sprintId → ${task.sprintId}`); }
+      }
+      if (args.withFeature && (task.featureId || task.feature_id)) {
+        const fid = task.featureId || task.feature_id;
+        const f = store.getEntity('features', fid);
+        if (f) { results.push(buildResult(f, 'feature', store, includeExcerpts)); trace.push(`followed featureId → ${fid}`); }
+      }
+      trace.push(`task ${args.task} found`);
+    } else {
+      trace.push(`task ${args.task} not found`);
+    }
+  } else if (args.bug) {
+    const bug = store.getEntity('bugs', args.bug);
+    if (bug) {
+      results.push(buildResult(bug, 'bug', store, includeExcerpts));
+      if (args.withBlockedTasks && bug.blocksTask) {
+        for (const tid of (Array.isArray(bug.blocksTask) ? bug.blocksTask : [bug.blocksTask])) {
+          const t = store.getEntity('tasks', tid);
+          if (t) { results.push(buildResult(t, 'task', store, includeExcerpts)); trace.push(`followed blocksTask → ${tid}`); }
+        }
+      }
+      trace.push(`bug ${args.bug} found`);
+    } else {
+      trace.push(`bug ${args.bug} not found`);
+    }
+  } else if (args.feature) {
+    const feat = store.getEntity('features', args.feature);
+    if (feat) {
+      results.push(buildResult(feat, 'feature', store, includeExcerpts));
+      const tasks = store.listTasks({ featureId: args.feature, ...filter });
+      trace.push(`feature ${args.feature}: ${tasks.length} tasks`);
+      for (const t of tasks) results.push(buildResult(t, 'task', store, includeExcerpts));
+    } else {
+      trace.push(`feature ${args.feature} not found`);
+    }
+  }
+
+  for (const r of results) {
+    if (r.fileRefs?.md) relatedFiles.push(r.fileRefs.md);
+    if (r.fileRefs?.json) relatedFiles.push(r.fileRefs.json);
+  }
+
+  return { query: args._raw, path: 'exact', traversalTrace: trace, results, relatedFileRefs: [...new Set(relatedFiles)], config: { store: cfg.storePathRel, engineering: cfg.kbPath || 'engineering' } };
+}
+
+// ── Keyword search path ───────────────────────────────────────────────────────
+
+function cmdKeywordSearch(args, store, cfg) {
+  const trace = [];
+  const results = [];
+  const relatedFiles = [];
+  const includeExcerpts = !args.noExcerpts;
+  const keyword = args.keyword;
+  const targetType = args.type || null;
+
+  const entityTypes = targetType
+    ? [targetType]
+    : ['sprints', 'tasks', 'bugs', 'features'];
+  const singMap = { sprints: 'sprint', tasks: 'task', bugs: 'bug', features: 'feature' };
+
+  for (const plural of entityTypes) {
+    const singular = singMap[plural];
+    let entities;
+    switch (plural) {
+      case 'sprints':  entities = store.listSprints();  break;
+      case 'tasks':    entities = store.listTasks();    break;
+      case 'bugs':     entities = store.listBugs();     break;
+      case 'features': entities = store.listFeatures(); break;
+      default:         entities = [];
+    }
+    const before = entities.length;
+    const matched = entities.filter(e => kwMatches(e.title || '', keyword));
+    if (matched.length > 0) {
+      trace.push(`keyword "${keyword}" in ${plural}: ${before} → ${matched.length}`);
+      for (const m of matched) results.push(buildResult(m, singular, store, includeExcerpts));
+    }
+  }
+
+  for (const r of results) {
+    if (r.fileRefs?.md) relatedFiles.push(r.fileRefs.md);
+    if (r.fileRefs?.json) relatedFiles.push(r.fileRefs.json);
+  }
+
+  return { query: args._raw, path: 'keyword', traversalTrace: trace, results, relatedFileRefs: [...new Set(relatedFiles)], config: { store: cfg.storePathRel, engineering: cfg.kbPath || 'engineering' } };
+}
+
+// ── Schema command ────────────────────────────────────────────────────────────
+
+function cmdSchema(cfg) {
+  const { buildFieldValidators } = require('./lib/store-query-exec.cjs');
+  // build validators inline since not exported — rebuild here
+  const p = cfg.prefix;
+  const esc = p.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const fv = {
+    sprints:  { sprintId: /^S\d+$/,  status: ['planning','active','completed','retrospective-done','blocked','partially-completed','abandoned'] },
+    tasks:    { taskId: new RegExp(`^${esc}-S\\d+-T\\d+$`), sprintId: /^S\d+$/, featureId: /^FEAT-\d+$/, status: ['draft','planned','plan-approved','implementing','implemented','review-approved','approved','committed','plan-revision-required','code-revision-required','blocked','escalated','abandoned'] },
+    bugs:     { bugId: new RegExp(`^${esc}-BUG-\\d+$`), sprintId: /^S\d+$/, severity: ['critical','major','minor'], status: ['reported','triaged','in-progress','fixed','verified'] },
+    features: { featureId: /^FEAT-\d+$/, status: ['active','draft','shipped','retired'] },
+  };
+  const toEnum = spec => Array.isArray(spec) ? spec : (spec instanceof RegExp ? `pattern: ${spec}` : null);
+
+  return {
+    project: { prefix: cfg.prefix, name: cfg.projectName, kbPath: cfg.kbPath, storePath: cfg.storePathRel },
+    entities: {
+      sprints:  { idField: 'sprintId',  idPattern: fv.sprints.sprintId.toString(),  status: toEnum(fv.sprints.status), fks: [] },
+      tasks:    { idField: 'taskId',    idPattern: fv.tasks.taskId.toString(),      status: toEnum(fv.tasks.status),   fks: ['sprintId','featureId','blockedBy'] },
+      bugs:     { idField: 'bugId',     idPattern: fv.bugs.bugId.toString(),        status: toEnum(fv.bugs.status), severity: toEnum(fv.bugs.severity), fks: ['sprintId','blocksTask'] },
+      features: { idField: 'featureId', idPattern: fv.features.featureId.toString(),status: toEnum(fv.features.status), fks: [] },
+    },
+    entitySynonyms: ENTITY_SYNONYMS,
+    statusSynonyms: STATUS_MAP,
+    grammar: {
+      recency: ['last','latest','newest','recent','most recent','oldest','earliest','first'],
+      limit:   ['top N','first N','last N'],
+      count:   ['how many','count of','number of','count'],
+      fkPhrases: ['with sprint','with feature','blocking','blocked','which sprint','sprint for','feature for'],
+    },
+  };
+}
+
+// ── Main ──────────────────────────────────────────────────────────────────────
+
+function main() {
+  const argv = process.argv.slice(2);
+  const startMs = Date.now();
+
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  const command = argv[0];
+  const rest = argv.slice(1);
+  const args = parseArgs(rest);
+
+  if (args.help) { printHelp(); process.exit(0); }
+
+  const cfg = loadForgeConfig();
+  const store = new StoreFacade(cfg.storePathAbs);
+
+  let result;
+
+  switch (command) {
+    case 'schema': {
+      result = cmdSchema(cfg);
+      break;
+    }
+    case 'nlp': {
+      if (!args.intent) {
+        process.stderr.write('Usage: store-query nlp "<natural language query>"\n');
+        process.exit(1);
+      }
+      const plan = parseIntentNLP(args.intent);
+      result = executeQuery(plan, store, { query: args.intent, noExcerpts: args.noExcerpts });
+      result.query = args.intent;
+      result.path  = 'intent-nlp';
+      result.config = { store: cfg.storePathRel, engineering: cfg.kbPath || 'engineering' };
+      break;
+    }
+    case 'query': {
+      const mode = args.mode || 'auto';
+      const hasExactFlags = args.sprint || args.task || args.bug || args.feature || args.listSprints;
+      const hasKeyword = !!args.keyword;
+
+      if (mode === 'strict' || mode === 'off') {
+        if (args.intent && !hasExactFlags && !hasKeyword) {
+          process.stderr.write('Mode is strict — intent strings not accepted. Use --sprint/--task/--bug/--feature flags.\n');
+          process.exit(1);
+        }
+      }
+
+      if (hasExactFlags) {
+        result = cmdQueryExact(args, store, cfg);
+      } else if (hasKeyword) {
+        result = cmdKeywordSearch(args, store, cfg);
+      } else if (args.intent) {
+        const plan = parseIntentNLP(args.intent);
+        result = executeQuery(plan, store, { query: args.intent, noExcerpts: args.noExcerpts });
+        result.query = args.intent;
+        result.path  = 'intent-nlp';
+        result.config = { store: cfg.storePathRel, engineering: cfg.kbPath || 'engineering' };
+      } else {
+        process.stderr.write('Provide an entity flag (--sprint, --task, --bug, --feature) or an intent string.\n');
+        process.exit(1);
+      }
+      break;
+    }
+    default: {
+      process.stderr.write(`Unknown command: ${command}\n`);
+      printHelp();
+      process.exit(1);
+    }
+  }
+
+  // Attach meta timing block
+  const totalMs = Date.now() - startMs;
+  result.meta = {
+    mode:         args.mode || 'auto',
+    engineVersion: '1.0.0',
+    totalTimeMs:   totalMs,
+  };
+
+  process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+}
+
+main();

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

@@ -0,0 +1,315 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { findProjectRoot } = require('./lib/project-root.cjs');
+
+/**
+ * Store Facade for Forge
+ * Provides a backend-agnostic interface for CRUD operations on core store entities.
+ */
+class Store {
+  constructor(implementation) {
+    this.impl = implementation;
+  }
+
+  // --- Sprints ---
+  getSprint(id) { return this.impl.getSprint(id); }
+  listSprints(filter) { return this.impl.listSprints(filter); }
+  writeSprint(data) { return this.impl.writeSprint(data); }
+  deleteSprint(id) { return this.impl.deleteSprint(id); }
+
+  // --- Tasks ---
+  getTask(id) { return this.impl.getTask(id); }
+  listTasks(filter) { return this.impl.listTasks(filter); }
+  writeTask(data) { return this.impl.writeTask(data); }
+  deleteTask(id) { return this.impl.deleteTask(id); }
+
+  // --- Bugs ---
+  getBug(id) { return this.impl.getBug(id); }
+  listBugs(filter) { return this.impl.listBugs(filter); }
+  writeBug(data) { return this.impl.writeBug(data); }
+  deleteBug(id) { return this.impl.deleteBug(id); }
+
+  // --- Events ---
+  getEvent(id, sprintId) { return this.impl.getEvent(id, sprintId); }
+  listEvents(sprintId, filter) { return this.impl.listEvents(sprintId, filter); }
+  writeEvent(sprintId, data) { return this.impl.writeEvent(sprintId, data); }
+  deleteEvent(id, sprintId) { return this.impl.deleteEvent(id, sprintId); }
+  renameEvent(sprintId, oldFilename, newEventId) { return this.impl.renameEvent(sprintId, oldFilename, newEventId); }
+
+  // --- Features ---
+  getFeature(id) { return this.impl.getFeature(id); }
+  listFeatures(filter) { return this.impl.listFeatures(filter); }
+  writeFeature(data) { return this.impl.writeFeature(data); }
+  deleteFeature(id) { return this.impl.deleteFeature(id); }
+
+  // --- Collation State ---
+  writeCollationState(data) { return this.impl.writeCollationState(data); }
+  readCollationState() { return this.impl.readCollationState(); }
+
+  // --- Event Operations (extended) ---
+  /**
+   * Purge all event files for a sprint directory.
+   * @param {string} sprintId
+   * @param {{ dryRun?: boolean }} opts - dryRun: return file list without deleting
+   * @returns {{ purged: boolean, fileCount: number, files: string[] }}
+   */
+  purgeEvents(sprintId, opts) { return this.impl.purgeEvents(sprintId, opts); }
+  /**
+   * List event filenames for a sprint directory.
+   * @param {string} sprintId
+   * @returns {{ filename: string, id: string }[]}
+   */
+  listEventFilenames(sprintId) { return this.impl.listEventFilenames(sprintId); }
+}
+
+/**
+ * Filesystem Implementation of the Store facade.
+ * Manages JSON flat-files in the .forge/store directory.
+ */
+class FSImpl {
+  constructor(configPath = '.forge/config.json') {
+    this.configPath = configPath;
+    this.storeRoot = this._resolveStoreRoot();
+  }
+
+  _resolveStoreRoot() {
+    const configPathIsAbsolute = path.isAbsolute(this.configPath);
+    const projectRoot = configPathIsAbsolute ? null : findProjectRoot();
+    try {
+      const resolved = projectRoot ? path.join(projectRoot, this.configPath) : this.configPath;
+      const config = JSON.parse(fs.readFileSync(resolved, 'utf8'));
+      const storePath = config.paths.store;
+      return path.isAbsolute(storePath) ? storePath
+        : projectRoot ? path.join(projectRoot, storePath) : storePath;
+    } catch (e) {
+      // Fallback to default if config is missing or corrupt
+      return projectRoot ? path.join(projectRoot, '.forge', 'store') : '.forge/store';
+    }
+  }
+
+  _getPath(entity, id) {
+    const entityMap = {
+      sprint: 'sprints',
+      task: 'tasks',
+      bug: 'bugs',
+      event: 'events',
+      feature: 'features'
+    };
+    const dir = entityMap[entity];
+    if (!dir) throw new Error(`Unknown entity type: ${entity}`);
+    return path.join(this.storeRoot, dir, `${id}.json`);
+  }
+
+  _readJson(filePath) {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  }
+
+  _writeJson(filePath, data) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    return data;
+  }
+
+  // Sprints
+  getSprint(id) { return this._readJson(this._getPath('sprint', id)); }
+  listSprints(filter) {
+    const dir = path.join(this.storeRoot, 'sprints');
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => this._readJson(path.join(dir, f)))
+      .filter(s => !s || (filter ? this._matches(s, filter) : true));
+  }
+  writeSprint(data) {
+    return this._writeJson(this._getPath('sprint', data.sprintId), data);
+  }
+  deleteSprint(id) {
+    const p = this._getPath('sprint', id);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+  }
+
+  // Tasks
+  getTask(id) { return this._readJson(this._getPath('task', id)); }
+  listTasks(filter) {
+    const dir = path.join(this.storeRoot, 'tasks');
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => this._readJson(path.join(dir, f)))
+      .filter(t => !t || (filter ? this._matches(t, filter) : true));
+  }
+  writeTask(data) {
+    return this._writeJson(this._getPath('task', data.taskId), data);
+  }
+  deleteTask(id) {
+    const p = this._getPath('task', id);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+  }
+
+  // Bugs
+  getBug(id) { return this._readJson(this._getPath('bug', id)); }
+  listBugs(filter) {
+    const dir = path.join(this.storeRoot, 'bugs');
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => this._readJson(path.join(dir, f)))
+      .filter(b => !b || (filter ? this._matches(b, filter) : true));
+  }
+  writeBug(data) {
+    return this._writeJson(this._getPath('bug', data.bugId), data);
+  }
+  deleteBug(id) {
+    const p = this._getPath('bug', id);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+  }
+
+  // Events
+  getEvent(id, sprintId) {
+    const p = path.join(this.storeRoot, 'events', sprintId, `${id}.json`);
+    return this._readJson(p);
+  }
+  listEvents(sprintId, filter) {
+    const dir = path.join(this.storeRoot, 'events', sprintId);
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => this._readJson(path.join(dir, f)))
+      .filter(e => !e || (filter ? this._matches(e, filter) : true));
+  }
+  /**
+   * Find an event file whose internal eventId matches the given eventId,
+   * but whose filename does not. Returns the mismatched filename (without
+   * .json extension), or null if none found. Skips _-prefixed (ephemeral) files.
+   */
+  _findEventFileByContentId(sprintId, eventId) {
+    const dir = path.join(this.storeRoot, 'events', sprintId);
+    if (!fs.existsSync(dir)) return null;
+    const files = fs.readdirSync(dir).filter(f => f.endsWith('.json') && !f.startsWith('_'));
+    for (const file of files) {
+      const filename = file.slice(0, -5); // strip .json
+      if (filename === eventId) continue; // already canonical
+      const rec = this._readJson(path.join(dir, file));
+      if (rec && rec.eventId === eventId) {
+        return filename;
+      }
+    }
+    return null;
+  }
+  /**
+   * Rename an event file from oldFilename to match newEventId.
+   * Throws if the target file already exists (collision).
+   */
+  renameEvent(sprintId, oldFilename, newEventId) {
+    const dir = path.join(this.storeRoot, 'events', sprintId);
+    const oldPath = path.join(dir, `${oldFilename}.json`);
+    const newPath = path.join(dir, `${newEventId}.json`);
+    if (oldPath === newPath) return; // no-op
+    if (fs.existsSync(newPath)) {
+      throw new Error(`Cannot rename event: target file already exists: ${newPath}`);
+    }
+    if (fs.existsSync(oldPath)) {
+      fs.renameSync(oldPath, newPath);
+    }
+  }
+  writeEvent(sprintId, data) {
+    // Detect ghost file: an existing file whose content eventId matches but
+    // whose filename does not. Rename it to the canonical name before writing.
+    const ghostFilename = this._findEventFileByContentId(sprintId, data.eventId);
+    if (ghostFilename !== null) {
+      this.renameEvent(sprintId, ghostFilename, data.eventId);
+    }
+    const p = path.join(this.storeRoot, 'events', sprintId, `${data.eventId}.json`);
+    return this._writeJson(p, data);
+  }
+  deleteEvent(id, sprintId) {
+    const p = path.join(this.storeRoot, 'events', sprintId, `${id}.json`);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+  }
+
+  // Features
+  getFeature(id) { return this._readJson(this._getPath('feature', id)); }
+  listFeatures(filter) {
+    const dir = path.join(this.storeRoot, 'features');
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => this._readJson(path.join(dir, f)))
+      .filter(f => !f || (filter ? this._matches(f, filter) : true));
+  }
+  writeFeature(data) {
+    return this._writeJson(this._getPath('feature', data.feature_id), data);
+  }
+  deleteFeature(id) {
+    const p = this._getPath('feature', id);
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+  }
+
+  // Collation State
+  writeCollationState(data) {
+    const filePath = path.join(this.storeRoot, 'COLLATION_STATE.json');
+    return this._writeJson(filePath, data);
+  }
+  readCollationState() {
+    const filePath = path.join(this.storeRoot, 'COLLATION_STATE.json');
+    return this._readJson(filePath);
+  }
+
+  // Event Operations (extended)
+  /**
+   * Purge the events directory for a given sprint.
+   * Includes a path-traversal guard: the resolved directory must remain
+   * within the events base directory. Throws on escape attempt.
+   * Note: fileCount reflects .json files only, but the directory is removed
+   * entirely (including any non-.json files).
+   */
+  purgeEvents(sprintId, { dryRun = false } = {}) {
+    const eventsBase = path.resolve(this.storeRoot, 'events');
+    const eventsDir = path.resolve(eventsBase, sprintId);
+    // Guard: resolved path must stay within the events base directory.
+    if (!eventsDir.startsWith(eventsBase + path.sep) && eventsDir !== eventsBase) {
+      throw new Error(`Resolved events path '${eventsDir}' escapes store root — aborting purge`);
+    }
+    if (!fs.existsSync(eventsDir)) {
+      return { purged: false, fileCount: 0, files: [] };
+    }
+    const files = fs.readdirSync(eventsDir).filter(f => f.endsWith('.json'));
+    if (dryRun) {
+      return { purged: false, fileCount: files.length, files };
+    }
+    fs.rmSync(eventsDir, { recursive: true, force: true });
+    return { purged: true, fileCount: files.length, files };
+  }
+
+  /**
+   * List all event filenames for a sprint directory.
+   * Returns { filename, id } objects for ALL .json files including
+   * _-prefixed ephemeral sidecars. Callers filter internally.
+   */
+  listEventFilenames(sprintId) {
+    const dir = path.join(this.storeRoot, 'events', sprintId);
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => ({
+        filename: f,
+        id: f.slice(0, -5) // strip .json extension
+      }));
+  }
+
+  _matches(record, filter) {
+    if (!filter) return true;
+    return Object.entries(filter).every(([key, value]) => record[key] === value);
+  }
+}
+
+// Export a singleton instance for the plugin, plus classes for testing
+module.exports = new Store(new FSImpl());
+module.exports.Store = Store;
+module.exports.FSImpl = FSImpl;