forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/preflight/gates.js

@@ -0,0 +1,237 @@
+'use strict';
+
+/**
+ * Gate composition + real sub-runners for `forge preflight`.
+ *
+ * Each real runner takes an injectable `spawn` (defaults to spawnSync) so the
+ * composition and the runners are unit-testable without touching the shell.
+ * The four gates give DETERMINISTIC-GATE PARITY with CI on the blast radius of
+ * a change, without the slow full matrix:
+ *
+ *   1. lint     — eslint --max-warnings 0 on changed files (or all with --all)
+ *   2. drift    — skills-mirror + registry-sync + agentic-workflow structural asserts
+ *   3. sonar    — eslint-plugin-sonarjs (cognitive-complexity=15 + parity rules)
+ *   4. affected — only the tests mapped from the changed files
+ *
+ * @module preflight/gates
+ */
+
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { execFileSync } = require('node:child_process');
+const nodeFs = require('node:fs');
+const { getAffectedTestFiles } = require('../commands/test');
+
+const IS_WINDOWS = process.platform === 'win32';
+
+/** Filter a changed-file list down to the JS files eslint should look at. */
+function lintableFiles(files) {
+  if (!Array.isArray(files)) return [];
+  return files.filter((f) => /\.(mjs|cjs|js)$/.test(f) && !f.includes('node_modules'));
+}
+
+/** Short, bounded summary for a spawn result. */
+function statusSummary(result, okMsg, failMsg) {
+  return result && result.status === 0
+    ? { ok: true, summary: okMsg }
+    : { ok: false, summary: failMsg };
+}
+
+/**
+ * Gate 1 — ESLint on the change blast radius (or the whole tree with --all).
+ * `files === null` means "lint everything" (`eslint .`).
+ */
+function runEslint(files, { projectRoot, spawn = spawnSync } = {}) {
+  const lintAll = files === null;
+  const targets = lintAll ? ['.'] : lintableFiles(files);
+  if (targets.length === 0) {
+    return { ok: true, summary: 'no changed JS files' };
+  }
+  const result = spawn(
+    'npx',
+    ['eslint', '--max-warnings', '0', ...targets],
+    { cwd: projectRoot, stdio: 'inherit', shell: IS_WINDOWS },
+  );
+  return statusSummary(
+    result,
+    lintAll ? 'whole tree clean' : `${targets.length} changed file(s) clean`,
+    'eslint reported errors/warnings',
+  );
+}
+
+/**
+ * Gate 2 — deterministic structural asserts that CI enforces:
+ *   - skills mirror drift (test/structural/skills-sync-drift.test.js)
+ *   - SUBCOMMANDS<->ISSUE_COMMANDS registry sync (test/commands/_resolve-command-opts.test.js)
+ *   - committed agentic-workflow mirror (scripts/sync-agentic-workflow.js --check)
+ */
+function runStructural({ projectRoot, spawn = spawnSync, fs = nodeFs } = {}) {
+  const exists = (rel) => {
+    try {
+      return fs.existsSync(path.join(projectRoot, rel));
+    } catch {
+      return false;
+    }
+  };
+
+  // These are Forge's OWN internal structural asserts. A consumer repo does not
+  // contain them and can NEVER satisfy them, so only run the ones that actually
+  // exist in this project. If none do, the gate is not applicable here — report
+  // an explicit SKIP rather than a false pass or an impossible failure.
+  const structuralTests = [
+    'test/structural/skills-sync-drift.test.js',
+    'test/commands/_resolve-command-opts.test.js',
+  ].filter(exists);
+  const agenticScript = 'scripts/sync-agentic-workflow.js';
+  const hasAgentic = exists(agenticScript);
+
+  if (structuralTests.length === 0 && !hasAgentic) {
+    return {
+      ok: true,
+      skipped: true,
+      summary: 'no Forge-internal structural checks in this repo (consumer context)',
+    };
+  }
+
+  if (structuralTests.length > 0) {
+    const bun = spawn(
+      'bun',
+      ['test', '--timeout', '15000', ...structuralTests],
+      { cwd: projectRoot, stdio: 'inherit', shell: IS_WINDOWS },
+    );
+    if (!bun || bun.status !== 0) {
+      return { ok: false, summary: 'skills-mirror / registry-sync asserts failed' };
+    }
+  }
+
+  if (!hasAgentic) {
+    return { ok: true, summary: 'skills + registry in sync (no agentic-workflow mirror here)' };
+  }
+
+  const agentic = spawn(
+    'node',
+    [agenticScript, '--check'],
+    { cwd: projectRoot, stdio: 'inherit', shell: IS_WINDOWS },
+  );
+  return statusSummary(
+    agentic,
+    'skills + registry + agentic-workflow in sync',
+    'agentic-workflow mirror drift (run: node scripts/sync-agentic-workflow.js)',
+  );
+}
+
+/**
+ * Gate 3 — SonarCloud parity via eslint-plugin-sonarjs, using an isolated flat
+ * config (cognitive-complexity pinned to 15 + the parity rules) so it never
+ * merges with the repo's main eslint config.
+ * `files === null` means "scan everything" (whole-tree `--all` mode) — mirrors
+ * runEslint so `--all` never leaves sonar as a vacuous "no changed files" pass.
+ */
+function runSonar(files, { projectRoot, spawn = spawnSync } = {}) {
+  const scanAll = files === null;
+  const targets = scanAll ? ['.'] : lintableFiles(files);
+  if (targets.length === 0) {
+    return { ok: true, summary: 'no changed JS files' };
+  }
+  const config = path.join(projectRoot, 'scripts', 'preflight-sonar.eslint.config.mjs');
+  const result = spawn(
+    'npx',
+    ['eslint', '--no-config-lookup', '--config', config, '--max-warnings', '0', ...targets],
+    { cwd: projectRoot, stdio: 'inherit', shell: IS_WINDOWS },
+  );
+  return statusSummary(
+    result,
+    scanAll ? 'sonarjs clean (whole tree)' : `sonarjs clean (${targets.length} file(s))`,
+    'sonarjs parity violations (e.g. cognitive-complexity > 15)',
+  );
+}
+
+/**
+ * Gate 4 — run ONLY the tests mapped from the changed files (reuses the
+ * pre-push affected-test mapping). No affected tests → fast-lane pass.
+ */
+function runAffectedTests({
+  projectRoot,
+  changedFiles: _changedFiles,
+  spawn = spawnSync,
+  resolveTests,
+} = {}) {
+  const resolver = typeof resolveTests === 'function'
+    ? resolveTests
+    // strict:true so a failed `git diff` THROWS here instead of returning [] —
+    // otherwise a git error would masquerade as "no affected tests" (fast-lane
+    // green), a fail-OPEN. The catch below turns that throw into a closed gate.
+    : () => getAffectedTestFiles(projectRoot, execFileSync, nodeFs, { strict: true });
+  let targets;
+  try {
+    targets = resolver() || [];
+  } catch (err) {
+    // A resolver ERROR must NOT masquerade as "no affected tests" (green).
+    // We could not determine what to run, so fail closed — never a vacuous pass.
+    const reason = err && err.message ? err.message : String(err);
+    return { ok: false, summary: `affected-test resolution failed — fail-closed (${reason})` };
+  }
+  if (targets.length === 0) {
+    return { ok: true, summary: 'no affected tests resolved (fast lane)' };
+  }
+  const result = spawn(
+    'bun',
+    ['test', '--timeout', '15000', ...targets],
+    { cwd: projectRoot, stdio: 'inherit', shell: IS_WINDOWS },
+  );
+  return statusSummary(
+    result,
+    `${targets.length} affected test file(s) passed`,
+    'affected tests failed',
+  );
+}
+
+/**
+ * Compose the ordered gate list. Each gate delegates to a sub-runner that can
+ * be injected via `deps` for testing; defaults wire the real runners above.
+ *
+ * @param {Object} args
+ * @param {string} args.projectRoot
+ * @param {string[]} args.changedFiles
+ * @param {boolean} [args.runAll]  - lint/scan whole tree instead of changed files
+ * @param {Object} [args.deps]     - { eslint, structural, sonar, affected }
+ * @returns {{ name: string, run: () => Promise<{ok:boolean, summary?:string}> }[]}
+ */
+function buildGates({ projectRoot, changedFiles = [], runAll = false, deps = {} }) {
+  const eslint = deps.eslint || ((files) => runEslint(files, { projectRoot }));
+  const structural = deps.structural || (() => runStructural({ projectRoot }));
+  const sonar = deps.sonar || ((files) => runSonar(files, { projectRoot }));
+  const affected = deps.affected || (() => runAffectedTests({ projectRoot, changedFiles }));
+
+  // Under --all, scope BOTH lint and sonar to the whole tree (null). Otherwise
+  // sonar would receive changedFiles=[] and report a vacuous "no changed files"
+  // pass while lint scanned everything — a fail-open hole on the remedy path.
+  const scanTargets = runAll ? null : changedFiles;
+
+  // Affected-tests maps from the change set, which is empty under --all. Running
+  // the WHOLE suite here defeats preflight's fast purpose (and hangs on Windows),
+  // so mark it explicitly not-run — never a vacuous green. CI runs the full suite.
+  const affectedGate = runAll
+    ? async () => ({
+      ok: true,
+      skipped: true,
+      summary: 'whole-tree mode (--all): affected-test mapping N/A — run the full suite (CI does)',
+    })
+    : async () => affected();
+
+  return [
+    { name: 'lint', run: async () => eslint(scanTargets) },
+    { name: 'drift/registry/mirror', run: async () => structural() },
+    { name: 'sonar (cognitive-complexity=15)', run: async () => sonar(scanTargets) },
+    { name: 'affected-tests', run: affectedGate },
+  ];
+}
+
+module.exports = {
+  buildGates,
+  lintableFiles,
+  runEslint,
+  runStructural,
+  runSonar,
+  runAffectedTests,
+};

package/lib/preflight/runner.js

@@ -0,0 +1,116 @@
+'use strict';
+
+/**
+ * Fast-fail gate runner for `forge preflight`.
+ *
+ * Executes an ordered list of gates one at a time. The first gate to fail
+ * short-circuits the run: every later gate is reported as `skipped` and never
+ * executed. This keeps preflight FAST — an agent fixes the first broken gate
+ * and re-runs rather than waiting for the whole matrix.
+ *
+ * A gate is `{ name: string, run: () => Promise<{ ok: boolean, summary?: string }> }`.
+ * The sub-runner behind each `run` is injected by the composer (see gates.js),
+ * so this module stays pure and trivially testable.
+ *
+ * @module preflight/runner
+ */
+
+/**
+ * @typedef {Object} GateOutcome
+ * @property {boolean} ok       - Whether the gate passed.
+ * @property {string} [summary] - Short human-readable result line.
+ *
+ * @typedef {Object} Gate
+ * @property {string} name
+ * @property {() => Promise<GateOutcome>} run
+ *
+ * @typedef {Object} GateResult
+ * @property {string} name
+ * @property {boolean|null} ok       - true/false, or null when skipped.
+ * @property {boolean} skipped
+ * @property {string} summary
+ * @property {number} [durationMs]
+ */
+
+/**
+ * Execute a single gate, normalizing thrown errors into a failed outcome.
+ *
+ * @param {Gate} gate
+ * @returns {Promise<GateResult>}
+ */
+async function executeGate(gate) {
+  const started = Date.now();
+  let outcome;
+  try {
+    outcome = await gate.run();
+  } catch (err) {
+    const message = err && err.message ? err.message : String(err);
+    outcome = { ok: false, summary: `error: ${message}` };
+  }
+  const durationMs = Date.now() - started;
+  const skipped = !!outcome?.skipped;
+  // A skipped gate is a pass-through: it is neither a pass nor a failure, so it
+  // must never short-circuit later gates (see runGates fast-fail). BUT a skip
+  // must never MASK an explicit failure — a gate that reports {ok:false} has
+  // failed regardless of a skipped flag, so it stays failed and short-circuits.
+  const explicitOk = !!outcome?.ok;
+  const ok = skipped ? outcome?.ok !== false : explicitOk;
+  // Contract: an explicit ok:false can never normalize to a pass. Guards against
+  // a future edit reintroducing the skip-masks-failure bug (4b73b6bf).
+  if (outcome && outcome.ok === false && ok === true) {
+    throw new Error('executeGate contract violation: skipped must not override an explicit ok:false');
+  }
+  return {
+    name: gate.name,
+    ok,
+    skipped,
+    summary: outcome?.summary || '',
+    durationMs,
+  };
+}
+
+/** Live-log label for a gate result — SKIP must never read as PASS. */
+function gateLogMark(result) {
+  if (result.skipped) return 'SKIP';
+  return result.ok ? 'PASS' : 'FAIL';
+}
+
+/**
+ * Run gates in order, fast-failing at the first failure.
+ *
+ * @param {Gate[]} gates
+ * @param {{ log?: (line: string) => void }} [options]
+ * @returns {Promise<{ ok: boolean, results: GateResult[], failedIndex: number }>}
+ */
+async function runGates(gates, options = {}) {
+  const log = typeof options.log === 'function' ? options.log : () => {};
+  const results = [];
+  let ok = true;
+  let failedIndex = -1;
+
+  for (const gate of gates) {
+    if (!ok) {
+      results.push({
+        name: gate.name,
+        ok: null,
+        skipped: true,
+        summary: 'skipped (earlier gate failed)',
+      });
+      continue;
+    }
+
+    const result = await executeGate(gate);
+    results.push(result);
+    const suffix = result.summary ? ` — ${result.summary}` : '';
+    log(`${gateLogMark(result)} ${gate.name}${suffix}`);
+
+    if (!result.ok) {
+      ok = false;
+      failedIndex = results.length - 1;
+    }
+  }
+
+  return { ok, results, failedIndex };
+}
+
+module.exports = { runGates };

package/lib/project-discovery.js

@@ -263,16 +263,6 @@ async function detectInstalledAgents(projectPath) {
           }
         ]
       },
-      {
-        name: 'copilot',
-        checks: [
-          // .github/copilot-instructions.md
-          async () => {
-            const copilotFile = path.join(projectPath, '.github', 'copilot-instructions.md');
-            return fs.existsSync(copilotFile);
-          }
-        ]
-      },
       {
         name: 'cursor',
         checks: [
@@ -283,39 +273,6 @@ async function detectInstalledAgents(projectPath) {
           }
         ]
       },
-      {
-        name: 'cline',
-        checks: [
-          async () => fs.existsSync(path.join(projectPath, '.clinerules')),
-          async () => {
-            const clineDir = path.join(projectPath, '.cline');
-            return fs.existsSync(clineDir) && (await fs.promises.stat(clineDir)).isDirectory();
-          }
-        ]
-      },
-      {
-        name: 'kilocode',
-        checks: [
-          async () => {
-            const kilocodeDir = path.join(projectPath, '.kilocode');
-            return fs.existsSync(kilocodeDir) && (await fs.promises.stat(kilocodeDir)).isDirectory();
-          },
-          async () => fs.existsSync(path.join(projectPath, '.kilocode', 'workflows', 'forge-workflow.md')),
-          async () => fs.existsSync(path.join(projectPath, '.kilocode', 'rules', 'workflow.md')),
-          async () => fs.existsSync(path.join(projectPath, '.kilocode', 'skills', 'forge-workflow', 'SKILL.md'))
-        ]
-      },
-      {
-        name: 'roo',
-        checks: [
-          async () => fs.existsSync(path.join(projectPath, '.roorules')),
-          async () => {
-            const rooDir = path.join(projectPath, '.roo');
-            return fs.existsSync(rooDir) && (await fs.promises.stat(rooDir)).isDirectory();
-          },
-          async () => fs.existsSync(path.join(projectPath, '.roo', 'rules'))
-        ]
-      },
       {
         name: 'codex',
         checks: [
@@ -325,16 +282,6 @@ async function detectInstalledAgents(projectPath) {
             return fs.existsSync(codexDir) && (await fs.promises.stat(codexDir)).isDirectory();
           }
         ]
-      },
-      {
-        name: 'opencode',
-        checks: [
-          // opencode.json file
-          async () => {
-            const opencodeJson = path.join(projectPath, 'opencode.json');
-            return fs.existsSync(opencodeJson);
-          }
-        ]
       }
     ];
 

package/lib/project-memory.js

@@ -0,0 +1,166 @@
+'use strict';
+
+const { resolveKernelDatabasePath } = require('./kernel/cli-broker-factory');
+const { createBuiltinSQLiteDriver } = require('./kernel/sqlite-driver');
+
+// Project memory is a Forge read model persisted in the kernel store (kernel_memories),
+// written DIRECTLY rather than through the issue CAS/guarded-event path. The store seam
+// (options.store) is a driver-like object — { recordMemory, loadMemory, searchMemories,
+// listMemories } — so hermetic tests stay in-memory. The default seam resolves the
+// per-repo kernel database path and reuses one driver per database path (the CLI process
+// is short-lived, so the connection closing on exit is sufficient cleanup).
+
+const storeCache = new Map();
+
+function defaultStore(projectRoot, options = {}) {
+  const databasePath = resolveKernelDatabasePath({
+    projectRoot,
+    gitCommonDir: options.gitCommonDir,
+    databasePath: options.databasePath,
+  });
+  let store = storeCache.get(databasePath);
+  if (!store) {
+    store = createBuiltinSQLiteDriver({ databasePath });
+    storeCache.set(databasePath, store);
+  }
+  return store;
+}
+
+function resolveStore(projectRoot, options = {}) {
+  return options.store ?? defaultStore(projectRoot, options);
+}
+
+function assertEntryObject(entry) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new TypeError('project memory entry must be an object');
+  }
+}
+
+function assertRequiredString(value, fieldName) {
+  if (typeof value !== 'string' || value.trim() === '') {
+    throw new TypeError(`project memory entry ${fieldName} is required`);
+  }
+}
+
+function assertStringArray(value, fieldName) {
+  if (!Array.isArray(value) || value.some(item => typeof item !== 'string')) {
+    throw new TypeError(`project memory entry ${fieldName} must be an array of strings`);
+  }
+}
+
+function assertOptionalConfidence(value) {
+  if (value !== undefined && (!Number.isFinite(value) || value < 0 || value > 1)) {
+    throw new TypeError('project memory entry confidence must be a number from 0 to 1');
+  }
+}
+
+function validateEntry(entry) {
+  assertEntryObject(entry);
+  assertRequiredString(entry.key, 'key');
+  if (!Object.hasOwn(entry, 'value') || entry.value === undefined) {
+    throw new TypeError('project memory entry value is required');
+  }
+  assertRequiredString(entry.sourceAgent || entry['source-agent'], 'sourceAgent');
+  if (entry.timestamp !== undefined
+    && (typeof entry.timestamp !== 'string' || Number.isNaN(Date.parse(entry.timestamp)))) {
+    throw new TypeError('project memory entry timestamp must be an ISO timestamp string');
+  }
+  if (entry.scope !== undefined && (typeof entry.scope !== 'string' || entry.scope.trim() === '')) {
+    throw new TypeError('project memory entry scope must be a non-empty string');
+  }
+  assertOptionalConfidence(entry.confidence);
+  if (entry.tags !== undefined) assertStringArray(entry.tags, 'tags');
+  if (entry.supersedes !== undefined) assertStringArray(entry.supersedes, 'supersedes');
+  if (entry.beadsRefs !== undefined) assertStringArray(entry.beadsRefs, 'beadsRefs');
+  if (entry['beads-refs'] !== undefined) assertStringArray(entry['beads-refs'], 'beads-refs');
+}
+
+// Canonicalize an entry for storage: resolve the snake-case input aliases, default the
+// timestamp and tags, and carry the optional fields only when present (so the persisted
+// shape matches the legacy entry exactly).
+function normalizeEntry(key, entry) {
+  const normalized = {
+    key,
+    value: entry.value,
+    sourceAgent: entry.sourceAgent || entry['source-agent'],
+    tags: Array.isArray(entry.tags) ? [...entry.tags] : [],
+    timestamp: entry.timestamp ?? new Date().toISOString(),
+  };
+
+  if (entry.scope !== undefined) normalized.scope = entry.scope;
+  if (entry.confidence !== undefined) normalized.confidence = entry.confidence;
+  if (entry.supersedes !== undefined) normalized.supersedes = [...entry.supersedes];
+  if (entry.beadsRefs !== undefined || entry['beads-refs'] !== undefined) {
+    normalized.beadsRefs = [...(entry.beadsRefs || entry['beads-refs'])];
+  }
+
+  return normalized;
+}
+
+function write(projectRoot, entry, options = {}) {
+  validateEntry(entry);
+  const normalized = normalizeEntry(entry.key.trim(), entry);
+  resolveStore(projectRoot, options).recordMemory(normalized);
+  return normalized;
+}
+
+function read(projectRoot, key, options = {}) {
+  assertRequiredString(key, 'read key');
+  return resolveStore(projectRoot, options).loadMemory(key.trim());
+}
+
+function search(projectRoot, query, options = {}) {
+  if (typeof query !== 'string' || query.trim() === '') {
+    return [];
+  }
+  return resolveStore(projectRoot, options).searchMemories(query.trim());
+}
+
+function list(projectRoot, options = {}) {
+  return resolveStore(projectRoot, options).listMemories();
+}
+
+// The newest `limit` entries (default recall with no query). Delegates to the FTS-backed
+// driver so recall never loads and re-sorts the whole table. `options.agents` (a
+// source_agent allow-list) scopes the read, e.g. to human `remember` notes only.
+function recent(projectRoot, limit, options = {}) {
+  return resolveStore(projectRoot, options).recentMemories(limit, { agents: options.agents });
+}
+
+// Total stored memories (optionally scoped by `options.agents`) — paired with `recent` so
+// recall can report "showing N of TOTAL".
+function count(projectRoot, options = {}) {
+  return resolveStore(projectRoot, options).countMemories({ agents: options.agents });
+}
+
+// BM25 top-N recall over the FTS5 index (token-AND). Unlike `search` (the legacy LIKE
+// helper) this does not short-circuit an empty query — the driver falls back to recent so
+// recall stays capped either way.
+function searchRanked(projectRoot, query, limit, options = {}) {
+  return resolveStore(projectRoot, options).searchMemoriesRanked(query, limit);
+}
+
+// Close and forget every cached default store. The CLI process is short-lived (the OS
+// closes the handle on exit), so this is mainly a lifecycle helper for long-lived hosts and
+// tests — it releases the SQLite/WAL handle before a temp dir is removed.
+function closeAll() {
+  for (const store of storeCache.values()) {
+    try {
+      if (store && typeof store.close === 'function') store.close();
+    } catch {
+      // best-effort close
+    }
+  }
+  storeCache.clear();
+}
+
+module.exports = {
+  read,
+  write,
+  search,
+  list,
+  recent,
+  count,
+  searchRanked,
+  closeAll,
+};