forge-workflow 0.0.9 → 0.1.0-beta.2

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-setup.js

@@ -2,7 +2,7 @@
  * Utilities for configuring Beads during `forge setup`.
  *
  * Handles prefix sanitization, config/gitignore generation,
- * initialization detection, and issues.jsonl pre-seeding.
+ * initialization detection, and legacy JSONL compatibility shims.
  *
  * @module beads-setup
  */
@@ -10,6 +10,22 @@
 const fs = require('node:fs');
 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);
+}
+
+function isRecoverableCommandError(error) {
+  return error?.code === 'ENOENT' || typeof error?.status === 'number';
+}
 
 /**
  * Resolve a command to its full path to avoid relying on inherited PATH.
@@ -24,7 +40,10 @@ function resolveCommand(command) {
     if (result.status === 0 && result.stdout) {
       return result.stdout.trim().split(/\r?\n/)[0].trim();
     }
-  } catch (_e) {
+  } catch (error) {
+    if (!isRecoverableCommandError(error)) {
+      throw error;
+    }
     // Expected: command resolution may fail if 'which'/'where.exe' is unavailable — fall back to bare command name
   }
   return command;
@@ -91,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',
@@ -105,13 +128,120 @@ 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.
  *
- * Returns `true` only when all of the following are present:
+ * Returns `true` when all of the following are present:
  * - `.beads/` directory exists
  * - `.beads/config.yaml` exists and contains an `issue-prefix` key
- * - `.beads/issues.jsonl` exists
+ * - the config points to either:
+ *   - a legacy SQLite tracker with legacy data markers present, or
+ *   - a Dolt-backed tracker with at least one post-`bd init` marker present
+ *
+ * Legacy SQLite-backed Beads installs also count as initialized so `forge setup`
+ * does not run `bd init` over an existing tracker before migration.
  *
  * @param {string} projectRoot - Absolute path to the project root
  * @returns {boolean} `true` if Beads is fully initialized
@@ -119,34 +249,74 @@ function writeBeadsGitignore(projectRoot) {
 function isBeadsInitialized(projectRoot) {
   const beadsDir = path.join(projectRoot, '.beads');
   const configPath = path.join(beadsDir, 'config.yaml');
-  const jsonlPath = path.join(beadsDir, 'issues.jsonl');
 
   if (!fs.existsSync(beadsDir)) return false;
   if (!fs.existsSync(configPath)) return false;
-  if (!fs.existsSync(jsonlPath)) return false;
 
   const configContent = fs.readFileSync(configPath, 'utf8');
   if (!configContent.includes('issue-prefix:')) return false;
 
-  return true;
+  const hasLegacyState = [
+    'issues.jsonl',
+    'backup',
+    'bd.db',
+    'beads.db',
+    'db.sqlite'
+  ].some((entry) => fs.existsSync(path.join(beadsDir, entry)));
+  const hasDoltMetadata = fs.existsSync(path.join(beadsDir, 'metadata.json'));
+  const hasDoltCompanionState = [
+    'README.md',
+    'hooks',
+    'redirect'
+  ].some((entry) => fs.existsSync(path.join(beadsDir, entry)));
+  const hasDoltState = hasDoltMetadata && hasDoltCompanionState;
+
+  if (configContent.includes('backend: sqlite')) {
+    return hasLegacyState;
+  }
+
+  if (configContent.includes('backend: dolt')) {
+    return hasDoltState;
+  }
+
+  return hasLegacyState || hasDoltState;
+}
+
+function readBeadsDatabaseName(projectRoot) {
+  const metadataPath = path.join(projectRoot, '.beads', 'metadata.json');
+  if (!fs.existsSync(metadataPath)) {
+    return null;
+  }
+
+  try {
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+    if (typeof metadata.dolt_database === 'string' && metadata.dolt_database.trim()) {
+      return metadata.dolt_database.trim();
+    }
+    if (typeof metadata.database === 'string' && metadata.database.trim()) {
+      return metadata.database.trim();
+    }
+  } catch (error) {
+    if (error instanceof SyntaxError || isIgnorableFsError(error)) {
+      return null;
+    }
+    throw error;
+  }
+
+  return null;
 }
 
 /**
- * Ensure `issues.jsonl` exists inside `.beads/`.
+ * Legacy compatibility shim for the removed JSONL pre-seed workaround.
  *
- * Creates the `.beads/` directory and an empty `issues.jsonl` if either
- * is missing. Leaves an existing `issues.jsonl` untouched.
+ * Beads latest no longer requires `.beads/issues.jsonl` during init, so
+ * this helper intentionally does nothing. It remains exported because some
+ * older tests and setup paths still import it.
  *
- * @param {string} projectRoot - Absolute path to the project root
+ * @param {string} _projectRoot - Absolute path to the project root
  */
-function preSeedJsonl(projectRoot) {
-  const beadsDir = path.join(projectRoot, '.beads');
-  fs.mkdirSync(beadsDir, { recursive: true });
-
-  const jsonlPath = path.join(beadsDir, 'issues.jsonl');
-  if (!fs.existsSync(jsonlPath)) {
-    fs.writeFileSync(jsonlPath, '', 'utf8');
-  }
+function preSeedJsonl(_projectRoot) {
+  // Legacy no-op: Dolt-backed Beads no longer requires JSONL pre-seeding.
 }
 
 // ---------------------------------------------------------------------------
@@ -212,6 +382,31 @@ function restoreDirectory(dirPath, snapshot) {
   }
 }
 
+function resolveHooksDir(projectRoot) {
+  const fallbackHooksDir = path.join(projectRoot, '.git', 'hooks');
+
+  try {
+    const gitHooksPath = secureExecFileSync(resolveCommand('git'), ['rev-parse', '--git-path', 'hooks'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    }).trim();
+
+    if (!gitHooksPath) {
+      return fallbackHooksDir;
+    }
+
+    return path.isAbsolute(gitHooksPath)
+      ? gitHooksPath
+      : path.resolve(projectRoot, gitHooksPath);
+  } catch (error) {
+    if (isRecoverableCommandError(error)) {
+      return fallbackHooksDir;
+    }
+    throw error;
+  }
+}
+
 /**
  * Default bd init executor — calls `execFileSync('bd', ['init'])`.
  *
@@ -237,7 +432,7 @@ function defaultExecBdInit(projectRoot) {
  *   e. Run bd init (via execBdInit callback or default execFileSync)
  *   f. Restore .git/hooks/ from snapshot
  *   g. Restore lefthook hooks if callback provided
- *   h. Pre-seed issues.jsonl
+ *   h. Skip the removed issues.jsonl pre-seed workaround
  *
  * @param {string} projectRoot - Absolute path to the project root
  * @param {Object} [options={}] - Configuration options
@@ -252,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 {
@@ -279,7 +481,7 @@ function safeBeadsInit(projectRoot, options = {}) {
   }
 
   // (d) Snapshot current .git/hooks/ directory
-  const hooksDir = path.join(projectRoot, '.git', 'hooks');
+  const hooksDir = resolveHooksDir(projectRoot);
   const hooksSnapshot = snapshotDirectory(hooksDir);
 
   // (e) Run bd init — wrapped in try/catch
@@ -316,13 +518,6 @@ function safeBeadsInit(projectRoot, options = {}) {
     }
   }
 
-  // (h) Pre-seed JSONL if empty
-  try {
-    preSeedJsonl(projectRoot);
-  } catch (err) {
-    warnings.push(`Failed to pre-seed issues.jsonl: ${err.message}`);
-  }
-
   return {
     success: true,
     skipped: false,
@@ -335,7 +530,9 @@ module.exports = {
   sanitizePrefix,
   writeBeadsConfig,
   writeBeadsGitignore,
+  ensureBeadsGitExclude,
   isBeadsInitialized,
+  readBeadsDatabaseName,
   preSeedJsonl,
   safeBeadsInit
 };