forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/audit-evidence.js

@@ -0,0 +1,282 @@
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const VERDICT_LABELS = {
+	PASS: 'good',
+	FAIL: 'bad',
+};
+
+const REVIEWER_ROLES = new Set(['spec_reviewer', 'quality_reviewer']);
+const SECRET_KEY_PATTERN = /(api(?:[_-]|\s)?key|authorization|credential|password|private(?:[_-]|\s)?key|secret|token)/i;
+const SECRET_TEXT_KEY_PATTERN = String.raw`(?:api(?:[_-]|\s)?key|authorization|credential|password|private(?:[_-]|\s)?key|secret|token)`;
+const SECRET_TEXT_PATTERNS = [
+	{
+		pattern: /\bBearer\s+\S+/gi,
+		replace: () => 'Bearer [REDACTED]',
+	},
+	{
+		pattern: new RegExp(`(\\b${SECRET_TEXT_KEY_PATTERN}\\b\\s*=\\s*)([^&,\r\n]+)`, 'gi'),
+		replace: (_match, prefix) => `${prefix}[REDACTED]`,
+	},
+	{
+		pattern: new RegExp(`(\\b${SECRET_TEXT_KEY_PATTERN}\\b\\s+is\\s+)([^&,\r\n]+)`, 'gi'),
+		replace: (_match, prefix) => `${prefix}[REDACTED]`,
+	},
+	{
+		pattern: new RegExp(
+			`(\\b${SECRET_TEXT_KEY_PATTERN}\\b\\s+)(?!is\\b)([^&,\r\n]*?)(?=\\s+\\b${SECRET_TEXT_KEY_PATTERN}\\b\\s+|[&,\r\n]|$)`,
+			'gi'
+		),
+		replace: (_match, prefix) => `${prefix}[REDACTED]`,
+	},
+	{
+		pattern: new RegExp(
+			`((?:"|')?${SECRET_TEXT_KEY_PATTERN}(?:"|')?\\s*:\\s*)(?:"[^"]*"|'[^']*'|[^,}\\]\r\n]+)`,
+			'gi'
+		),
+		replace: (_match, prefix) => `${prefix}"[REDACTED]"`,
+	},
+	/\bsk-[A-Za-z0-9_-]{8,}\b/g,
+];
+
+function defaultRunCommand(command, args, options = {}) {
+	return execFileSync(command, args, {
+		cwd: options.cwd || process.cwd(),
+		encoding: 'utf8',
+		input: options.input,
+		timeout: options.timeout || 120000,
+	});
+}
+
+function redactString(value) {
+	return SECRET_TEXT_PATTERNS.reduce(
+		(current, entry) => {
+			if (entry && typeof entry === 'object' && !(entry instanceof RegExp)) {
+				return current.replace(entry.pattern, entry.replace);
+			}
+			return current.replace(entry, () => '[REDACTED]');
+		},
+		value,
+	);
+}
+
+function redact(value, key = '') {
+	if (SECRET_KEY_PATTERN.test(key)) {
+		return '[REDACTED]';
+	}
+
+	if (typeof value === 'string') {
+		return redactString(value);
+	}
+
+	if (Array.isArray(value)) {
+		return value.map(item => redact(item));
+	}
+
+	if (value && typeof value === 'object') {
+		return Object.fromEntries(
+			Object.entries(value).map(([entryKey, entryValue]) => [entryKey, redact(entryValue, entryKey)]),
+		);
+	}
+
+	return value;
+}
+
+function asJsonString(value) {
+	if (typeof value === 'string') return redactString(value);
+	return JSON.stringify(redact(value));
+}
+
+function buildSubagentAuditPayload(event) {
+	if (!event || typeof event !== 'object') {
+		throw new TypeError('Audit event must be an object');
+	}
+	if (!event.command) {
+		throw new TypeError('Audit event command is required');
+	}
+	if (!event.role) {
+		throw new TypeError('Audit event role is required');
+	}
+
+	const metadata =
+		event.metadata && typeof event.metadata === 'object' && !Array.isArray(event.metadata)
+			? event.metadata
+			: {};
+
+	return {
+		kind: 'llm_call',
+		command: event.command,
+		issueId: event.issueId,
+		role: event.role,
+		phase: event.phase,
+		taskId: event.taskId,
+		taskTitle: event.taskTitle,
+		model: event.model || 'unknown',
+		prompt: asJsonString({
+			command: event.command,
+			role: event.role,
+			phase: event.phase,
+			taskId: event.taskId,
+			taskTitle: event.taskTitle,
+			content: event.prompt || '',
+		}),
+		response: asJsonString({
+			command: event.command,
+			role: event.role,
+			verdict: event.verdict || 'UNKNOWN',
+			content: event.response || '',
+		}),
+		metadata: redact(metadata),
+		verdict: event.verdict,
+	};
+}
+
+function parseRecordId(output, { requireJson = false } = {}) {
+	if (!output) return null;
+	try {
+		const parsed = JSON.parse(output);
+		return typeof parsed.id === 'string' ? parsed.id : null;
+	} catch (_error) {
+		if (requireJson) return null;
+		const match = /\bint-[A-Za-z0-9_-]+\b/.exec(String(output));
+		return match ? match[0] : null;
+	}
+}
+
+function hasAuditMetaJsonSupport(runCommand = defaultRunCommand, options = {}) {
+	const output = runCommand('bd', ['audit', 'record', '--help'], options);
+	return String(output).includes('--meta-json');
+}
+
+function writeFallbackMetadata(payload, entryId, options) {
+	if (!entryId || !payload.metadata || Object.keys(payload.metadata).length === 0) {
+		return null;
+	}
+
+	const cwd = options.cwd || process.cwd();
+	const fsImpl = options.fs || fs;
+	const forgeDir = path.join(cwd, '.forge').replace(/\\/g, '/');
+	const logPath = path.join(forgeDir, 'log.jsonl').replace(/\\/g, '/');
+	const line = {
+		kind: 'forge.auditEvidence',
+		sourceOfTruth: 'beads',
+		beadsEntryId: entryId,
+		command: redact(payload.command),
+		role: redact(payload.role),
+		phase: redact(payload.phase),
+		taskId: redact(payload.taskId),
+		taskTitle: redact(payload.taskTitle),
+		metadata: redact(payload.metadata),
+	};
+
+	try {
+		fsImpl.mkdirSync(forgeDir, { recursive: true });
+		fsImpl.appendFileSync(logPath, `${JSON.stringify(line)}\n`);
+		return { path: logPath, line };
+	} catch (error) {
+		return { path: logPath, line, skipped: true, error: error.message };
+	}
+}
+
+function recordSubagentAuditEvent(event, options = {}) {
+	const payload = buildSubagentAuditPayload(event);
+	const runCommand = options.runCommand || defaultRunCommand;
+	const metaJsonSupported =
+		typeof options.metaJsonSupported === 'boolean'
+			? options.metaJsonSupported
+			: hasAuditMetaJsonSupport(runCommand, { cwd: options.cwd || process.cwd() });
+	const args = [
+		'audit',
+		'record',
+		'--json',
+		'--kind',
+		'llm_call',
+	];
+
+	if (payload.issueId) {
+		args.push('--issue-id', payload.issueId);
+	}
+
+	args.push(
+		'--model',
+		payload.model,
+		'--prompt',
+		payload.prompt,
+		'--response',
+		payload.response,
+	);
+
+	if (metaJsonSupported && Object.keys(payload.metadata).length > 0) {
+		args.push('--meta-json', JSON.stringify(payload.metadata));
+	}
+
+	const output = runCommand('bd', args, { cwd: options.cwd || process.cwd() });
+	const entryId = parseRecordId(output, { requireJson: true });
+	const fallback = metaJsonSupported ? null : writeFallbackMetadata(payload, entryId, options);
+
+	return {
+		success: Boolean(entryId),
+		entryId,
+		output,
+		payload,
+		fallback,
+	};
+}
+
+function labelSubagentAuditEvent(entryId, event, options = {}) {
+	const verdict = String(event?.verdict || '').toUpperCase();
+	const role = event?.role;
+	const label = VERDICT_LABELS[verdict];
+
+	if (!entryId || !REVIEWER_ROLES.has(role) || !label) {
+		return { skipped: true };
+	}
+
+	const runCommand = options.runCommand || defaultRunCommand;
+	const reason = `${role} verdict: ${verdict}`;
+	let output;
+	try {
+		output = runCommand('bd', [
+			'audit',
+			'label',
+			entryId,
+			'--json',
+			'--label',
+			label,
+			'--reason',
+			reason,
+		], { cwd: options.cwd || process.cwd() });
+	} catch (error) {
+		return {
+			success: false,
+			label,
+			error: error.message,
+		};
+	}
+
+	const labeledEntryId = parseRecordId(output, { requireJson: true });
+
+	return {
+		success: labeledEntryId === entryId,
+		label,
+		entryId: labeledEntryId,
+		output,
+	};
+}
+
+function recordAndLabelSubagentAuditEvent(event, options = {}) {
+	const record = recordSubagentAuditEvent(event, options);
+	const label = labelSubagentAuditEvent(record.entryId, event, options);
+	return { record, label };
+}
+
+module.exports = {
+	VERDICT_LABELS,
+	buildSubagentAuditPayload,
+	recordSubagentAuditEvent,
+	labelSubagentAuditEvent,
+	recordAndLabelSubagentAuditEvent,
+	hasAuditMetaJsonSupport,
+	redact,
+};

package/lib/beads-detect.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Single-source, side-effect-free Beads-store detector (kernel issue a5399f3d).
+//
+// Both upgrade-safety surfaces reuse this ONE definition: the issue-path
+// unmigrated-beads nudge (lib/commands/_issue.js) and the `forge upgrade`
+// advisory (lib/upgrade-safety.js). It deliberately lives in a neutral module,
+// NOT in lib/commands/migrate.js — re-exporting a `detectBeadsJsonlSource` name
+// from the migrate command would revive the identifier the a7e1443c
+// implicit-auto-migrate tombstone pins gone (test/commands/runtime-no-auto-migrate).
+// This detector only READS the filesystem and never triggers a migration, so it
+// honors that tombstone's spirit while giving both nudges a shared source.
+
+function dirHasJsonl(dir) {
+  try {
+    return fs.readdirSync(dir).some(entry => entry.endsWith('.jsonl'));
+  } catch (_err) { // NOSONAR S2486 — line-scoped; must sit on the catch line
+    /* intentional: an unreadable directory has no usable jsonl */
+    return false;
+  }
+}
+
+/**
+ * Return the absolute path of the directory holding a returning user's Beads
+ * JSONL under `projectRoot`, or null when none is found. Checks the top-level
+ * `.beads/` first, then the split-store `.beads/backup/` layout (jsonl there and
+ * nowhere else — a layout the migrator itself reads), so neither surface misses
+ * it. Never throws.
+ *
+ * @param {string} [projectRoot]
+ * @returns {string|null}
+ */
+function detectBeadsJsonlSource(projectRoot) {
+  const root = projectRoot || process.cwd();
+  const beadsDir = path.join(root, '.beads');
+  try {
+    if (!fs.existsSync(beadsDir)) {
+      return null;
+    }
+    if (dirHasJsonl(beadsDir)) {
+      return beadsDir;
+    }
+    const backupDir = path.join(beadsDir, 'backup');
+    if (fs.existsSync(backupDir) && dirHasJsonl(backupDir)) {
+      return backupDir;
+    }
+    return null;
+  } catch (_err) { // NOSONAR S2486 — line-scoped; must sit on the catch line
+    /* intentional: an unreadable project root has no detectable beads source */
+    return null;
+  }
+}
+
+module.exports = {
+  detectBeadsJsonlSource,
+  dirHasJsonl,
+};

package/lib/beads-nudge.js

@@ -0,0 +1,91 @@
+'use strict';
+
+const { resolveIssueBackend } = require('./issue-backend');
+const { detectBeadsJsonlSource } = require('./beads-detect');
+
+// Unmigrated legacy-store nudge (kernel issue a5399f3d — upgrade-safety
+// 0.0.10 -> current).
+//
+// The 0.0.10 -> current upgrade flipped the DEFAULT issue backend to the Kernel,
+// but the legacy -> kernel migration fires ONLY from `forge setup`/`init`, never
+// lazily on the issue path. So a user who runs `bun update` then `forge list` /
+// `forge ready` reads an EMPTY kernel and their 0.0.10 issues APPEAR GONE — the
+// data is safe on disk, just invisible, with no hint. This helper closes that
+// footgun: when the resolved backend is the (default) Kernel, a read comes back
+// empty, AND a legacy jsonl store still exists, it prints a one-time guided hint.
+//
+// It lives in this NEUTRAL module (not lib/commands/_issue.js) on purpose: the
+// message text names the retired backend + its `.beads` store, and _issue.js is a
+// D20 release-readiness hot-path surface that must stay free of those tokens (the
+// bd-call-site audit + kernel-backed checks scan it). Keeping the strings here
+// lets the hot path call a token-free helper.
+//
+// Best-effort and non-blocking: it NEVER throws and never alters the read result.
+// Fires at most once per project root per process to avoid spam.
+const NUDGE_READS = new Set(['list', 'ready']);
+const warnedRoots = new Set();
+
+// A kernel read looks empty when its contract data carries no issues. Handles the
+// issue.list/issue.ready shape ({ issues, count }) plus a bare array / null, and
+// is deliberately conservative: anything it cannot confirm as empty is treated as
+// NON-empty so a user with real kernel issues is never nagged.
+function kernelReadLooksEmpty(result) {
+  if (!result || typeof result !== 'object' || result.ok !== true) {
+    return false;
+  }
+  const data = result.data;
+  if (data === null || data === undefined) {
+    return true;
+  }
+  if (Array.isArray(data)) {
+    return data.length === 0;
+  }
+  if (Array.isArray(data.issues)) {
+    return data.issues.length === 0;
+  }
+  if (Array.isArray(data.items)) {
+    return data.items.length === 0;
+  }
+  if (typeof data.count === 'number') {
+    return data.count === 0;
+  }
+  return false;
+}
+
+function maybeWarnUnmigratedBeads(subcommand, result, projectRoot, rawOpts = {}) {
+  try {
+    if (!NUDGE_READS.has(subcommand) || !projectRoot) {
+      return;
+    }
+    if (warnedRoots.has(projectRoot)) {
+      return;
+    }
+    const env = rawOpts.env || process.env;
+    // Resolve the EFFECTIVE backend (default kernel). An explicit opt-in to the
+    // retired backend means the user chose it deliberately — nothing to nudge.
+    const backend = resolveIssueBackend({ deps: rawOpts, env, projectRoot, warn: () => {} });
+    if (backend !== 'kernel' || !kernelReadLooksEmpty(result)) {
+      return;
+    }
+    if (!detectBeadsJsonlSource(projectRoot)) {
+      return;
+    }
+    warnedRoots.add(projectRoot);
+    console.error(
+      '\n[forge] Legacy issue data detected (.beads/*.jsonl) but the Kernel issue store is empty.\n'
+      + 'Forge now defaults to the Kernel backend (breaking change since 0.0.10). Your legacy\n'
+      + 'issues are safe on disk but will not appear until migrated. To migrate:\n'
+      + '  forge migrate --from beads   # import your legacy issues into the Kernel\n'
+      + '  forge setup                  # (re)wire hooks + provision the Kernel store\n'
+      + 'Prefer to stay on the legacy backend? Set `issueBackend: beads` in .forge/config.yaml '
+      + '(or FORGE_ISSUE_BACKEND=beads).\n',
+    );
+  } catch (_err) { // NOSONAR S2486 — line-scoped; must sit on the catch line
+    /* the nudge is a best-effort hint; it must never break a read */
+  }
+}
+
+module.exports = {
+  maybeWarnUnmigratedBeads,
+  kernelReadLooksEmpty,
+};

package/lib/beads-setup.js

@@ -12,6 +12,13 @@ const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { secureExecFileSync } = require('./shell-utils');
 
+const BEADS_LOCAL_EXCLUDE_LINES = [
+  '# Forge local Beads state',
+  '.beads/',
+  '.dolt/',
+  '.beads-credential-key'
+];
+
 function isIgnorableFsError(error) {
   return ['EACCES', 'ENOENT', 'ENOTDIR', 'EPERM'].includes(error?.code);
 }
@@ -103,6 +110,10 @@ function writeBeadsGitignore(projectRoot) {
   fs.mkdirSync(beadsDir, { recursive: true });
 
   const gitignoreContent = [
+    '# Beads runtime, export, and backup state is local',
+    '*',
+    '!.gitignore',
+    '',
     '# Dolt database files (binary, not suitable for git)',
     'dolt/',
     '*.db',
@@ -117,6 +128,108 @@ function writeBeadsGitignore(projectRoot) {
   );
 }
 
+function resolveGitInfoExcludePath(projectRoot) {
+  try {
+    const gitExcludePath = secureExecFileSync(resolveCommand('git'), ['rev-parse', '--git-path', 'info/exclude'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    }).trim();
+
+    if (gitExcludePath) {
+      return path.isAbsolute(gitExcludePath)
+        ? gitExcludePath
+        : path.resolve(projectRoot, gitExcludePath);
+    }
+  } catch (error) {
+    if (!isRecoverableCommandError(error)) {
+      throw error;
+    }
+  }
+
+  return path.join(projectRoot, '.git', 'info', 'exclude');
+}
+
+function untrackExistingBeadsState(projectRoot) {
+  let tracked;
+  try {
+    tracked = secureExecFileSync(resolveCommand('git'), [
+      'ls-files',
+      '-z',
+      '--',
+      '.beads',
+      '.dolt',
+      '.beads-credential-key'
+    ], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+  } catch (error) {
+    if (!isRecoverableCommandError(error)) {
+      throw error;
+    }
+    return;
+  }
+
+  if (!tracked) {
+    return;
+  }
+
+  try {
+    secureExecFileSync(resolveCommand('git'), [
+      'rm',
+      '--cached',
+      '-r',
+      '-f',
+      '--ignore-unmatch',
+      '--',
+      '.beads',
+      '.dolt',
+      '.beads-credential-key'
+    ], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+  } catch (error) {
+    if (!isRecoverableCommandError(error)) {
+      throw error;
+    }
+  }
+}
+
+/**
+ * Add local-only Git exclude rules for Beads state.
+ *
+ * Uses `.git/info/exclude` instead of the tracked `.gitignore` so `forge setup`
+ * does not dirty downstream repositories just to keep Beads runtime files local.
+ * Existing tracked Beads state is removed from the Git index only, leaving local
+ * files in place for the Beads runtime.
+ *
+ * @param {string} projectRoot - Absolute path to the project root
+ */
+function ensureBeadsGitExclude(projectRoot) {
+  const excludePath = resolveGitInfoExcludePath(projectRoot);
+  fs.mkdirSync(path.dirname(excludePath), { recursive: true });
+
+  const existing = fs.existsSync(excludePath)
+    ? fs.readFileSync(excludePath, 'utf8')
+    : '';
+  const existingLines = new Set(existing.split(/\r?\n/));
+  const missingLines = BEADS_LOCAL_EXCLUDE_LINES.filter((line) => !existingLines.has(line));
+
+  if (missingLines.length === 0) {
+    untrackExistingBeadsState(projectRoot);
+    return;
+  }
+
+  const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+  const spacer = existing.trim() ? '\n' : '';
+  fs.appendFileSync(excludePath, `${prefix}${spacer}${missingLines.join('\n')}\n`, 'utf8');
+  untrackExistingBeadsState(projectRoot);
+}
+
 /**
  * Check whether Beads is properly initialized in a project.
  *
@@ -334,6 +447,13 @@ function safeBeadsInit(projectRoot, options = {}) {
   const warnings = [];
   const errors = [];
 
+  // Keep Beads runtime/export state local even when the tracker already exists.
+  try {
+    ensureBeadsGitExclude(projectRoot);
+  } catch (err) {
+    warnings.push(`Failed to write local Beads git exclude rules: ${err.message}`);
+  }
+
   // (a) Check if already initialized — idempotent skip
   if (isBeadsInitialized(projectRoot)) {
     return {
@@ -410,6 +530,7 @@ module.exports = {
   sanitizePrefix,
   writeBeadsConfig,
   writeBeadsGitignore,
+  ensureBeadsGitExclude,
   isBeadsInitialized,
   readBeadsDatabaseName,
   preSeedJsonl,