forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/forge-lock.js

@@ -0,0 +1,262 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const LOCKFILE_NAME = 'forge.lock';
+const AUDIT_LOG_PATH = path.join('.forge', 'log.jsonl');
+const REMOTE_SOURCE_PATTERN = /^(?:https?:|gh:|gist:|npm:)/i;
+
+function toPosixPath(value) {
+  return String(value || '').replaceAll('\\', '/');
+}
+
+function normalizeRelativePath(projectRoot, fullPath) {
+  return toPosixPath(path.relative(projectRoot, fullPath));
+}
+
+function isInsideRoot(projectRoot, fullPath) {
+  const relative = path.relative(projectRoot, fullPath);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function lockPath(projectRoot) {
+  return path.join(projectRoot, LOCKFILE_NAME);
+}
+
+function defaultLock() {
+  return {
+    version: 1,
+    generatedBy: 'forge',
+    extensions: [],
+  };
+}
+
+function readForgeLock(projectRoot) {
+  const filePath = lockPath(projectRoot);
+  if (!fs.existsSync(filePath)) return defaultLock();
+  const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  return {
+    ...defaultLock(),
+    ...parsed,
+    extensions: Array.isArray(parsed.extensions) ? parsed.extensions : [],
+  };
+}
+
+function writeForgeLock(projectRoot, lock) {
+  fs.writeFileSync(lockPath(projectRoot), `${JSON.stringify(lock, null, 2)}\n`, 'utf8');
+}
+
+function appendAuditEvent(projectRoot, event) {
+  const logPath = path.join(projectRoot, AUDIT_LOG_PATH);
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  fs.appendFileSync(logPath, `${JSON.stringify({
+    kind: 'forge.lock',
+    schemaVersion: 1,
+    recordedAt: new Date().toISOString(),
+    ...event,
+  })}\n`, 'utf8');
+}
+
+function isRemoteSource(source) {
+  return REMOTE_SOURCE_PATTERN.test(String(source || ''));
+}
+
+function resolveLocalSource(projectRoot, source) {
+  const root = path.resolve(projectRoot);
+  const resolved = path.resolve(root, source);
+  if (!isInsideRoot(root, resolved)) {
+    throw new Error(`Source must stay inside project root: ${source}`);
+  }
+  if (!fs.existsSync(resolved) || !fs.statSync(resolved).isFile()) {
+    throw new Error(`Local source does not exist: ${source}`);
+  }
+  const realRoot = fs.realpathSync(root);
+  const realResolved = fs.realpathSync(resolved);
+  if (!isInsideRoot(realRoot, realResolved)) {
+    throw new Error(`Source must stay inside project root: ${source}`);
+  }
+  if (!fs.statSync(realResolved).isFile()) {
+    throw new Error(`Local source does not exist: ${source}`);
+  }
+  return realResolved;
+}
+
+function sourceIntegrity(filePath) {
+  const digest = crypto
+    .createHash('sha512')
+    .update(fs.readFileSync(filePath))
+    .digest('base64');
+  return `sha512-${digest}`;
+}
+
+function verifyUnsupportedRemoteEntry(entry) {
+  if (!isRemoteSource(entry.source)) {
+    return {
+      name: entry.name,
+      status: 'fail',
+      reason: 'unsupported remote verification requires a remote source locator',
+    };
+  }
+  if (entry.resolvedPath || entry.integrity || entry.trust?.allowUntrusted !== true) {
+    return {
+      name: entry.name,
+      status: 'fail',
+      reason: 'unsupported remote entry has inconsistent lock metadata',
+    };
+  }
+  return {
+    name: entry.name,
+    status: 'warn',
+    reason: 'remote source integrity cannot be rechecked by this foundation',
+  };
+}
+
+function classifySource(projectRoot, source, options = {}) {
+  if (!source) {
+    throw new Error('Source is required');
+  }
+
+  if (isRemoteSource(source)) {
+    if (!options.allowUntrusted) {
+      throw new Error(`Untrusted source refused: ${source}. Re-run with --allow-untrusted to record it explicitly.`);
+    }
+    return {
+      trusted: false,
+      allowUntrusted: true,
+      resolvedPath: null,
+      integrity: null,
+      verification: 'unsupported-remote',
+      reason: 'remote locator requires explicit --allow-untrusted',
+    };
+  }
+
+  const resolvedPath = resolveLocalSource(projectRoot, source);
+  return {
+    trusted: true,
+    allowUntrusted: false,
+    resolvedPath,
+    integrity: sourceIntegrity(resolvedPath),
+    verification: 'sri',
+    reason: 'local file inside project root',
+  };
+}
+
+function upsertExtension(extensions, entry) {
+  const next = extensions.filter(existing => existing.name !== entry.name);
+  next.push(entry);
+  return next.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function addLockEntry(projectRoot, options) {
+  const root = path.resolve(projectRoot);
+  const realRoot = fs.realpathSync(root);
+  const sourceInfo = classifySource(root, options.source, {
+    allowUntrusted: Boolean(options.allowUntrusted),
+  });
+  const lock = readForgeLock(root);
+  const entry = {
+    name: options.name,
+    source: options.source,
+    resolvedPath: sourceInfo.resolvedPath ? normalizeRelativePath(realRoot, sourceInfo.resolvedPath) : null,
+    integrity: sourceInfo.integrity,
+    verification: sourceInfo.verification,
+    trust: {
+      trusted: sourceInfo.trusted,
+      allowUntrusted: sourceInfo.allowUntrusted,
+      reason: sourceInfo.reason,
+    },
+    lockedAt: new Date().toISOString(),
+  };
+
+  lock.extensions = upsertExtension(lock.extensions, entry);
+  writeForgeLock(root, lock);
+  appendAuditEvent(root, {
+    action: 'add',
+    name: entry.name,
+    source: entry.source,
+    trusted: entry.trust.trusted,
+    verification: entry.verification,
+    integrity: entry.integrity,
+  });
+
+  return { lock, entry };
+}
+
+function verifyEntry(projectRoot, entry) {
+  if (entry.verification === 'unsupported-remote') {
+    return verifyUnsupportedRemoteEntry(entry);
+  }
+  if (isRemoteSource(entry.source) || isRemoteSource(entry.resolvedPath)) {
+    return {
+      name: entry.name,
+      status: 'fail',
+      reason: 'remote source locator requires unsupported-remote verification policy',
+    };
+  }
+
+  const relativePath = entry.resolvedPath || entry.source;
+  const root = path.resolve(projectRoot);
+  const realRoot = fs.realpathSync(root);
+  const fullPath = path.resolve(realRoot, relativePath);
+  if (!isInsideRoot(realRoot, fullPath)) {
+    return {
+      name: entry.name,
+      status: 'fail',
+      reason: `source escapes project root: ${relativePath}`,
+    };
+  }
+  if (!fs.existsSync(fullPath) || !fs.statSync(fullPath).isFile()) {
+    return {
+      name: entry.name,
+      status: 'fail',
+      reason: `source missing: ${relativePath}`,
+    };
+  }
+  const realFullPath = fs.realpathSync(fullPath);
+  if (!isInsideRoot(realRoot, realFullPath)) {
+    return {
+      name: entry.name,
+      status: 'fail',
+      reason: `source escapes project root: ${relativePath}`,
+    };
+  }
+
+  const actual = sourceIntegrity(realFullPath);
+  if (actual !== entry.integrity) {
+    return {
+      name: entry.name,
+      status: 'fail',
+      reason: `integrity mismatch: expected ${entry.integrity}, got ${actual}`,
+    };
+  }
+
+  return {
+    name: entry.name,
+    status: 'pass',
+    reason: 'integrity verified',
+  };
+}
+
+function verifyForgeLock(projectRoot) {
+  const lock = readForgeLock(projectRoot);
+  const results = lock.extensions.map(entry => verifyEntry(projectRoot, entry));
+  return {
+    ok: results.every(result => result.status !== 'fail'),
+    path: LOCKFILE_NAME,
+    results,
+    lock,
+  };
+}
+
+module.exports = {
+  LOCKFILE_NAME,
+  AUDIT_LOG_PATH,
+  addLockEntry,
+  classifySource,
+  readForgeLock,
+  sourceIntegrity,
+  verifyForgeLock,
+  writeForgeLock,
+};

package/lib/gate-events.js

@@ -0,0 +1,192 @@
+'use strict';
+
+/**
+ * @module gate-events
+ *
+ * Human gates enforced by kernel EVENTS, not skill prose (Fable's key insight,
+ * locked in docs/work/2026-07-04-kernel-native-skills/decisions.md). A gate
+ * approval is a durable, queryable, resume-safe kernel event on the ISSUE:
+ * `gate.approved` / `gate.rejected` by an actor. `forge gate check` (and, later,
+ * the ship stage) refuses to proceed without the required `gate.approved` event
+ * UNLESS the gate is toggled off — giving evidence-checked HARD-GATEs and
+ * resume-from-kernel-state after a compaction/crash for free.
+ *
+ * Mechanism: a PURE APPEND to the issue's event stream via the driver primitives
+ * (`insertKernelEvent` + `listKernelEvents`), NOT the guarded issue-mutation
+ * pipeline. Gate events do not mutate the issue, so they must not participate in
+ * the issue-revision CAS (`lib/kernel/evaluators.js` would otherwise quarantine an
+ * `expected_revision:0` append against a non-zero issue revision as `stale_revision`).
+ * Idempotency is enforced two ways: a pre-check on the idempotency key, plus the
+ * unique index `idx_kernel_events_idempotency` catching a concurrent race.
+ *
+ * Config-surface note: which gates EXIST (and whether each is enabled) lives in the
+ * runtime graph + `.forge/config.yaml`; this module only records/reads the events.
+ */
+
+const { resolveOwnedKernel, closeIfOwned } = require('./kernel/owned-kernel');
+const { resolveIssueActor } = require('./forge-issues');
+
+const GATE_APPROVED_EVENT = 'gate.approved';
+const GATE_REJECTED_EVENT = 'gate.rejected';
+
+const GATE_EVENT_TYPES = {
+  approved: GATE_APPROVED_EVENT,
+  rejected: GATE_REJECTED_EVENT,
+};
+
+const ISSUE_ENTITY_TYPE = 'issue';
+const GATE_EVENT_ORIGIN = 'cli';
+
+// Kernel lifecycle (resolve + close-what-you-built) is shared with
+// grounding/context-events via lib/kernel/owned-kernel. A gate read/append that
+// builds its own kernel must close it — an unclosed SQLite handle leaks and, on
+// Windows, locks the DB directory (EBUSY on rmSync, kernel issue e62e4bde). Safe
+// here today because gate events only fire on explicit `forge gate` commands,
+// but the leak is identical so we close proactively via closeIfOwned.
+
+/**
+ * Idempotency key for a gate event. Scoped to issue + gate + actor + decision so a
+ * SAME-actor re-approval mints no duplicate, while a later reject (different
+ * decision) or a different actor is recorded as its own event.
+ */
+function gateIdempotencyKey(eventType, issueId, gateId, actor) {
+  return `${eventType}:${issueId}:${gateId}:${actor}`;
+}
+
+/** Shape a stored kernel_events row into the gate-event view callers consume. */
+function parseGateEvent(row) {
+  let payload;
+  try {
+    payload = row.payload_json ? JSON.parse(row.payload_json) : {};
+  } catch {
+    payload = {};
+  }
+  const view = {
+    event_type: row.event_type,
+    gate: payload.gate,
+    actor: row.actor,
+    created_at: row.created_at,
+  };
+  if (payload.reason !== undefined) view.reason = payload.reason;
+  return view;
+}
+
+function isIdempotencyRace(error) {
+  const message = error && error.message ? String(error.message) : '';
+  return /UNIQUE constraint failed/i.test(message) && /idempotency_key/i.test(message);
+}
+
+/**
+ * Record a gate decision as a kernel event on the issue. Idempotent per
+ * issue+gate+actor+decision. Validates the issue exists (the caller validates the
+ * gate id against the known-gate set before calling).
+ *
+ * @param {string} projectRoot
+ * @param {Object} params
+ * @param {string} params.issueId
+ * @param {string} params.gateId
+ * @param {'approved'|'rejected'} params.decision
+ * @param {string} [params.reason]
+ * @param {Object} [params.env] - env source for actor resolution (FORGE_ACTOR → …).
+ * @param {Object} [params.deps] - injected { kernelBroker, kernelDriver }.
+ * @param {string} [params.now] - ISO timestamp (defaults to now).
+ * @returns {Promise<{ ok: boolean, duplicate?: boolean, issueMissing?: boolean, event?: Object, actor?: string }>}
+ */
+async function recordGateEvent(projectRoot, params = {}) {
+  const { issueId, gateId, decision, reason, env, deps, now } = params;
+  const eventType = GATE_EVENT_TYPES[decision];
+  if (!eventType) {
+    throw new Error(`Unknown gate decision '${decision}' (expected 'approved' or 'rejected').`);
+  }
+
+  const actor = resolveIssueActor(env || process.env) || 'forge';
+  const kernel = await resolveOwnedKernel(projectRoot, deps);
+  const { driver, config } = kernel;
+
+  try {
+    const entity = await driver.loadKernelEntity(ISSUE_ENTITY_TYPE, issueId, {}, config);
+    if (!entity) {
+      return { ok: false, issueMissing: true, actor };
+    }
+
+    const idempotencyKey = gateIdempotencyKey(eventType, issueId, gateId, actor);
+
+    const existing = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
+    if (existing) {
+      return { ok: true, duplicate: true, event: parseGateEvent(existing), actor };
+    }
+
+    const payload = { gate: gateId, actor };
+    if (typeof reason === 'string' && reason.length > 0) payload.reason = reason;
+
+    const event = {
+      entity_type: ISSUE_ENTITY_TYPE,
+      entity_id: issueId,
+      event_type: eventType,
+      idempotency_key: idempotencyKey,
+      expected_revision: 0,
+      actor,
+      origin: GATE_EVENT_ORIGIN,
+      payload,
+      created_at: now || new Date().toISOString(),
+    };
+
+    try {
+      const inserted = await driver.insertKernelEvent(event, {}, config);
+      return { ok: true, duplicate: false, event: parseGateEvent(inserted), actor };
+    } catch (error) {
+      if (isIdempotencyRace(error)) {
+        const winner = await driver.loadKernelEventByIdempotencyKey(idempotencyKey, {}, config);
+        return { ok: true, duplicate: true, event: winner ? parseGateEvent(winner) : parseGateEvent(event), actor };
+      }
+      throw error;
+    }
+  } finally {
+    closeIfOwned(kernel);
+  }
+}
+
+/**
+ * List every gate event on an issue, oldest first.
+ *
+ * @param {string} projectRoot
+ * @param {string} issueId
+ * @param {{ deps?: Object }} [options]
+ * @returns {Promise<Array<{ event_type: string, gate: string, actor: string, created_at: string, reason?: string }>>}
+ */
+async function listGateEvents(projectRoot, issueId, options = {}) {
+  const kernel = await resolveOwnedKernel(projectRoot, options.deps);
+  try {
+    const rows = await kernel.driver.listKernelEvents(ISSUE_ENTITY_TYPE, issueId, {}, kernel.config);
+    return (rows || [])
+      .filter(row => typeof row.event_type === 'string' && row.event_type.startsWith('gate.'))
+      .map(parseGateEvent);
+  } finally {
+    closeIfOwned(kernel);
+  }
+}
+
+/**
+ * True iff a `gate.approved` event exists for this issue + gate.
+ *
+ * @param {string} projectRoot
+ * @param {string} issueId
+ * @param {string} gateId
+ * @param {{ deps?: Object }} [options]
+ * @returns {Promise<boolean>}
+ */
+async function isGateApproved(projectRoot, issueId, gateId, options = {}) {
+  const events = await listGateEvents(projectRoot, issueId, options);
+  return events.some(event => event.event_type === GATE_APPROVED_EVENT && event.gate === gateId);
+}
+
+module.exports = {
+  GATE_APPROVED_EVENT,
+  GATE_REJECTED_EVENT,
+  GATE_EVENT_TYPES,
+  gateIdempotencyKey,
+  parseGateEvent,
+  recordGateEvent,
+  listGateEvents,
+  isGateApproved,
+};

package/lib/global-flags.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * Global CLI flags recognized by bin/forge.js parseGlobalFlags().
+ *
+ * bin/forge.js parses these into the `flags` object but leaves them inside the
+ * positional `args` array it hands to command handlers. Free-text commands
+ * (remember, recall) that join positionals into content must strip them first,
+ * or `forge remember "note" -p <dir>` stores the literal `note -p <dir>`
+ * (kernel issue c1e090ff).
+ *
+ * Keep these sets in sync with parseGlobalFlags() in bin/forge.js.
+ * @module lib/global-flags
+ */
+
+// Flags that consume a following value token (also accepted as --flag=value).
+const GLOBAL_VALUE_FLAGS = new Set([
+  '--path', '-p',
+  '--agents',
+  '--merge',
+  '--type',
+  '--budget',
+]);
+
+const GLOBAL_VALUE_FLAG_PREFIXES = ['--path=', '--agents=', '--merge=', '--type=', '--budget='];
+
+// Boolean flags that take no value.
+const GLOBAL_BOOLEAN_FLAGS = new Set([
+  '--quick', '-q',
+  '--skip-external', '--skip-services',
+  '--all',
+  '--help', '-h',
+  '--version', '-V',
+  '--yes', '-y',
+  '--non-interactive',
+  '--force',
+  '--verbose',
+  '--dry-run',
+  '--symlink',
+  '--sync',
+  '--interview',
+]);
+
+/**
+ * Remove recognized global flags (and their values) from a positional args
+ * array. Plain words that merely resemble flag names (no leading dash) are
+ * always kept.
+ *
+ * @param {string[]} args - Raw command arguments.
+ * @returns {string[]} Arguments with global flags stripped.
+ */
+function stripGlobalFlags(args) {
+  const kept = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (GLOBAL_BOOLEAN_FLAGS.has(arg)) continue;
+    if (GLOBAL_VALUE_FLAG_PREFIXES.some((prefix) => arg.startsWith(prefix))) continue;
+    if (GLOBAL_VALUE_FLAGS.has(arg)) {
+      const next = args[index + 1];
+      // Mirror parsePathFlag() in bin/forge.js: the value is consumed only
+      // when it exists and is not itself a flag.
+      if (next !== undefined && !next.startsWith('-')) index += 1;
+      continue;
+    }
+    kept.push(arg);
+  }
+  return kept;
+}
+
+/**
+ * Index of the first positional token (a bare, non-flag argument), skipping any
+ * leading global flags and their consumed values. Returns -1 when no positional
+ * exists. Uses the SAME flag-consumption rules as {@link stripGlobalFlags} so the
+ * two agree on what counts as a positional. Unlike stripGlobalFlags this returns
+ * an index into the ORIGINAL array, so callers can splice out the positional
+ * while preserving the intervening flags.
+ *
+ * @param {string[]} args - Raw command arguments.
+ * @param {number} [start=0] - Index to begin scanning from.
+ * @returns {number} Index into `args` of the first positional token, or -1.
+ */
+function firstPositionalIndex(args, start = 0) {
+  for (let index = start; index < args.length; index += 1) {
+    const arg = args[index];
+    if (GLOBAL_BOOLEAN_FLAGS.has(arg)) continue;
+    if (GLOBAL_VALUE_FLAG_PREFIXES.some((prefix) => arg.startsWith(prefix))) continue;
+    if (GLOBAL_VALUE_FLAGS.has(arg)) {
+      const next = args[index + 1];
+      if (next !== undefined && !next.startsWith('-')) index += 1;
+      continue;
+    }
+    // Any other dash-prefixed token is a non-global flag, not the positional.
+    if (arg.startsWith('-')) continue;
+    return index;
+  }
+  return -1;
+}
+
+module.exports = {
+  GLOBAL_BOOLEAN_FLAGS,
+  GLOBAL_VALUE_FLAGS,
+  stripGlobalFlags,
+  firstPositionalIndex,
+};

package/lib/greptile-match.js

@@ -1,80 +1,24 @@
 'use strict';
 
-const { execFileSync } = require('node:child_process');
+const { GreptileReviewAdapter } = require('./adapters/greptile-review-adapter');
 
 /**
  * Match unresolved review threads to recent commits that touched the same files.
  *
- * For each thread, runs `git log --oneline --follow -- <file>` to find
- * recent commits. If a commit exists, the thread is considered resolved
- * (the file was modified after the review comment).
- *
- * Uses execFileSync (not exec) to prevent shell injection (OWASP A03).
+ * This backward-compatible export now delegates to the Greptile review adapter
+ * so existing Greptile scripts keep working while new review integrations use
+ * the ReviewAdapter SPI.
  *
  * @param {Array<{file: string, line: number}>} threads - Review threads with file paths
  * @param {string} projectRoot - Absolute path to the project root (used with git -C)
  * @param {object} [opts] - Options
- * @param {Function} [opts._exec] - Injected exec function for testing (defaults to execFileSync)
+ * @param {Function} [opts._exec] - Injected exec function for testing
  * @param {string} [opts.sinceCommit] - Merge-base SHA to restrict log to PR commits only
  * @returns {Array<{file: string, line: number, resolved: boolean, sha?: string, reason?: string}>}
  */
 function matchThreadsToCommits(threads, projectRoot, opts = {}) {
-  if (!threads || threads.length === 0) {
-    return [];
-  }
-
-  const exec = opts._exec || ((cmd, args) => {
-    return execFileSync(cmd, args, { encoding: 'utf8' });
-  });
-
-  // Determine commit range — restrict to PR commits when sinceCommit provided
-  let sinceCommit = opts.sinceCommit;
-  if (!sinceCommit) {
-    try {
-      sinceCommit = exec('git', ['-C', projectRoot, 'merge-base', 'HEAD', 'main']).trim();
-    } catch (_e) { // NOSONAR S2486
-      /* intentional: main branch not found, try master instead */
-      try {
-        sinceCommit = exec('git', ['-C', projectRoot, 'merge-base', 'HEAD', 'master']).trim();
-      } catch (_e2) { /* intentional: no merge-base available, fall back to unbounded log */ // NOSONAR S2486
-        sinceCommit = null;
-      }
-    }
-  }
-
-  return threads.map((thread) => {
-    const { file, line } = thread;
-
-    try {
-      const logArgs = [
-        '-C', projectRoot,
-        'log',
-        '--oneline',
-        '--follow',
-      ];
-      if (sinceCommit) {
-        logArgs.push(`${sinceCommit}..HEAD`);
-      }
-      logArgs.push('--', file);
-
-      const output = exec('git', logArgs);
-
-      const trimmed = (output || '').trim();
-
-      if (!trimmed) {
-        return { file, line, resolved: false, reason: 'no matching commit' };
-      }
-
-      // git log --oneline format: "<sha> <message>"
-      // Take the first (most recent) line
-      const firstLine = trimmed.split('\n')[0];
-      const sha = firstLine.split(' ')[0];
-
-      return { file, line, resolved: true, sha };
-    } catch (_err) { /* intentional: git log failed (file missing or git unavailable), mark unresolved */ // NOSONAR S2486
-      return { file, line, resolved: false, reason: 'no matching commit' };
-    }
-  });
+  const adapter = new GreptileReviewAdapter();
+  return adapter.score(threads, { ...opts, projectRoot });
 }
 
 module.exports = { matchThreadsToCommits };