forge-workflow 0.1.0-beta.4 → 0.1.0-beta.6

package/lib/protected-state-surfaces.js

@@ -1,7 +1,17 @@
 const fs = require('node:fs');
 const path = require('node:path');
-const { execFileSync } = require('node:child_process');
+const crypto = require('node:crypto');
 const { redact } = require('./audit-evidence');
+const { appendCappedJsonlRecord } = require('./capped-jsonl-log');
+
+/**
+ * Protected-state decisions are logged locally rather than to the kernel event
+ * stream: kernel events are issue-scoped and async, and this runs inside a
+ * synchronous pre-commit hook that has no issue id and must not open the kernel
+ * SQLite handle. Capped so a repeated blocked commit cannot grow it unbounded.
+ */
+const PROTECTED_STATE_AUDIT_LOG = '.forge/protected-state-audit.jsonl';
+const PROTECTED_STATE_AUDIT_MAX_RECORDS = 500;
 
 function normalizeRepoPath(filePath) {
 	return String(filePath || '')
@@ -10,6 +20,40 @@ function normalizeRepoPath(filePath) {
 		.replace(/\/+/g, '/');
 }
 
+function hashProtectedContent(content) {
+	const bytes = Buffer.isBuffer(content) ? content : Buffer.from(String(content), 'utf8');
+	return `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+function createProtectedStateAuditRecord({
+	actor,
+	surface,
+	path: filePath,
+	content,
+	operation = 'generate',
+	viaForgeApi = false,
+	sourceHead,
+}) {
+	if (!actor || !surface || !filePath || content === undefined) {
+		throw new TypeError('Protected state audit record requires actor, surface, path, and content');
+	}
+
+	return {
+		kind: 'protected_state_write',
+		actor,
+		path: normalizeRepoPath(filePath),
+		decision: 'allowed',
+		requiredSurface: surface,
+		declaredSurface: surface,
+		operation,
+		viaForgeApi: viaForgeApi === true,
+		...(sourceHead ? { sourceHead } : {}),
+		contentHash: hashProtectedContent(content),
+		reason: `Forge API generated content for protected surface: ${surface}.`,
+		repairHint: null,
+	};
+}
+
 function startsWithAny(filePath, prefixes) {
 	return prefixes.some(prefix => filePath === prefix || filePath.startsWith(`${prefix}/`));
 }
@@ -42,13 +86,13 @@ const PROTECTED_SURFACES = [
 				'.forge/agent-log.ndjson',
 				'.beads/interactions.jsonl',
 			].includes(filePath),
-		repairHint: 'append-only logs must be written by the Forge or Beads audit writer; do not rewrite existing log content.',
+		repairHint: 'append-only logs must be written by the Forge audit writer; do not rewrite existing log content.',
 	},
 	{
 		id: 'beads_state',
-		label: 'Beads state',
+		label: 'Legacy Beads state',
 		matches: filePath => startsWithAny(filePath, ['.beads']),
-		repairHint: 'Use bd or Forge issue commands such as bd update, bd close, forge ready, or forge close.',
+		repairHint: 'A legacy .beads directory is import-only state. Import it with `forge migrate --from beads`, then use Forge issue commands such as forge ready or forge close.',
 	},
 	{
 		id: 'forge_config',
@@ -164,8 +208,12 @@ function nearestExistingPath(candidate) {
 	return current;
 }
 
+function realpathNearestExistingPath(candidate) {
+	return fs.realpathSync(nearestExistingPath(candidate));
+}
+
 function assertNoAncestorSymlinkEscape(root, target) {
-	const realRoot = fs.realpathSync(root);
+	const realRoot = realpathNearestExistingPath(root);
 	const existing = nearestExistingPath(path.dirname(target));
 	const existingStat = lstatIfPresent(existing);
 	if (existing !== root && existingStat?.isSymbolicLink()) {
@@ -177,7 +225,7 @@ function assertNoAncestorSymlinkEscape(root, target) {
 		};
 	}
 
-	const realExisting = fs.realpathSync(existing);
+	const realExisting = realpathNearestExistingPath(existing);
 	if (!pathStaysInsideRoot(realRoot, realExisting)) {
 		return {
 			allowed: false,
@@ -191,8 +239,8 @@ function assertNoAncestorSymlinkEscape(root, target) {
 
 function assertNoSymlinkEscape(root, target) {
 	const parent = path.dirname(target);
-	const realRoot = fs.realpathSync(root);
-	const existingParent = fs.existsSync(parent) ? fs.realpathSync(parent) : parent;
+	const realRoot = realpathNearestExistingPath(root);
+	const existingParent = realpathNearestExistingPath(parent);
 	if (!pathStaysInsideRoot(realRoot, existingParent)) {
 		return {
 			allowed: false,
@@ -258,6 +306,89 @@ function assertProtectedWriteAllowed(filePath, options = {}) {
 	};
 }
 
+function fileIdentity(stat) {
+	return `${stat.dev}:${stat.ino}`;
+}
+
+function blockedAtomicDecision(decision, reason) {
+	return {
+		...decision,
+		allowed: false,
+		decision: 'blocked',
+		reason,
+		repairHint: 'Retry through the owning Forge command after confirming the protected path is unchanged.',
+	};
+}
+
+function captureParentBoundary(root, target) {
+	const parent = path.dirname(target);
+	const stat = lstatIfPresent(parent);
+	if (!stat?.isDirectory() || stat.isSymbolicLink()) {
+		return { ok: false, reason: `Protected write parent boundary changed: ${parent}` };
+	}
+	const realRoot = fs.realpathSync(root);
+	const realParent = fs.realpathSync(parent);
+	if (!pathStaysInsideRoot(realRoot, realParent)) {
+		return { ok: false, reason: `Protected write parent boundary changed outside project root: ${parent}` };
+	}
+	return { ok: true, parent, realParent, identity: fileIdentity(stat) };
+}
+
+function captureTargetState(target) {
+	const before = lstatIfPresent(target);
+	if (!before) return { ok: true, exists: false };
+	if (!before.isFile() || before.isSymbolicLink()) {
+		return { ok: false, reason: `Protected write target boundary changed: ${target}` };
+	}
+	const content = fs.readFileSync(target);
+	const after = fs.lstatSync(target);
+	if (fileIdentity(before) !== fileIdentity(after) || after.isSymbolicLink()) {
+		return { ok: false, reason: `Protected write target boundary changed while reading: ${target}` };
+	}
+	return {
+		ok: true,
+		exists: true,
+		identity: fileIdentity(after),
+		content,
+		contentHash: hashProtectedContent(content),
+	};
+}
+
+function sameParentBoundary(left, right) {
+	return left.ok && right.ok && left.realParent === right.realParent && left.identity === right.identity;
+}
+
+function sameTargetState(left, right) {
+	if (!left.ok || !right.ok || left.exists !== right.exists) return false;
+	if (!left.exists) return true;
+	return left.identity === right.identity && left.contentHash === right.contentHash;
+}
+
+function expectedTargetMatches(state, expectedContent) {
+	if (expectedContent === null) return !state.exists;
+	if (!state.exists) return false;
+	const expected = Buffer.isBuffer(expectedContent)
+		? expectedContent
+		: Buffer.from(String(expectedContent), 'utf8');
+	return state.content.equals(expected);
+}
+
+function expectedTargetChanged(state, options) {
+	return Object.prototype.hasOwnProperty.call(options, 'expectedContent')
+		&& !expectedTargetMatches(state, options.expectedContent);
+}
+
+function cleanupOwnedTemp(tempPath, identity) {
+	try {
+		const current = fs.lstatSync(tempPath);
+		if (current.isFile() && !current.isSymbolicLink() && fileIdentity(current) === identity) {
+			fs.unlinkSync(tempPath);
+		}
+	} catch (error) {
+		if (error.code !== 'ENOENT') throw error;
+	}
+}
+
 function writeProtectedFile(projectRoot, filePath, content, options = {}) {
 	const resolved = resolveRepoRelativePath(projectRoot, filePath);
 	if (!resolved.insideRoot) {
@@ -296,8 +427,88 @@ function writeProtectedFile(projectRoot, filePath, content, options = {}) {
 		};
 	}
 
-	fs.writeFileSync(resolved.target, content, options.encoding || 'utf8');
-	return { ...decision, fullPath: resolved.target };
+	const initialParent = captureParentBoundary(resolved.root, resolved.target);
+	if (!initialParent.ok) return blockedAtomicDecision(decision, initialParent.reason);
+	const initialTarget = captureTargetState(resolved.target);
+	if (!initialTarget.ok) return blockedAtomicDecision(decision, initialTarget.reason);
+	if (expectedTargetChanged(initialTarget, options)) {
+		return blockedAtomicDecision(decision, 'Protected workflow has a concurrent content change; refusing to overwrite it.');
+	}
+
+	const bytes = Buffer.isBuffer(content) ? content : Buffer.from(String(content), options.encoding || 'utf8');
+	const tempPath = path.join(
+		initialParent.parent,
+		`.${path.basename(resolved.target)}.forge-${process.pid}-${crypto.randomUUID()}.tmp`,
+	);
+	let tempIdentity;
+	try {
+		const flags = fs.constants.O_NOFOLLOW
+			? fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW
+			: 'wx';
+		const fd = fs.openSync(tempPath, flags, 0o600);
+		try {
+			fs.writeFileSync(fd, bytes);
+			fs.fsyncSync(fd);
+			tempIdentity = fileIdentity(fs.fstatSync(fd));
+		} finally {
+			fs.closeSync(fd);
+		}
+
+		if (typeof options.beforeAtomicCommit === 'function') {
+			options.beforeAtomicCommit({ parent: initialParent.parent, target: resolved.target, tempPath });
+		}
+
+		const finalParent = captureParentBoundary(resolved.root, resolved.target);
+		const finalTarget = captureTargetState(resolved.target);
+		if (!sameParentBoundary(initialParent, finalParent) || !sameTargetState(initialTarget, finalTarget)) {
+			return blockedAtomicDecision(decision, 'Protected write boundary changed before atomic replacement.');
+		}
+		if (expectedTargetChanged(finalTarget, options)) {
+			return blockedAtomicDecision(decision, 'Protected workflow has a concurrent content change; refusing to overwrite it.');
+		}
+		const tempState = fs.lstatSync(tempPath);
+		if (!tempState.isFile() || tempState.isSymbolicLink() || fileIdentity(tempState) !== tempIdentity) {
+			return blockedAtomicDecision(decision, 'Protected write temporary-file identity changed before atomic replacement.');
+		}
+
+		fs.renameSync(tempPath, resolved.target);
+		tempIdentity = null;
+		return { ...decision, contentHash: hashProtectedContent(bytes), fullPath: resolved.target };
+	} catch (error) {
+		return blockedAtomicDecision(decision, `Protected atomic write failed: ${error.message}`);
+	} finally {
+		if (tempIdentity) cleanupOwnedTemp(tempPath, tempIdentity);
+	}
+}
+
+function removeProtectedFile(projectRoot, filePath, options = {}) {
+	const resolved = resolveRepoRelativePath(projectRoot, filePath);
+	if (!resolved.insideRoot) {
+		return blockedAtomicDecision({}, `Protected remove path escapes project root: ${filePath}`);
+	}
+	const decision = assertProtectedWriteAllowed(resolved.relativePath, {
+		...options,
+		operation: options.operation || 'remove',
+	});
+	if (!decision.allowed) return decision;
+	const initialParent = captureParentBoundary(resolved.root, resolved.target);
+	const initialTarget = captureTargetState(resolved.target);
+	if (!initialParent.ok || !initialTarget.ok) {
+		return blockedAtomicDecision(decision, initialParent.reason || initialTarget.reason);
+	}
+	if (!Object.prototype.hasOwnProperty.call(options, 'expectedContent') || !expectedTargetMatches(initialTarget, options.expectedContent)) {
+		return blockedAtomicDecision(decision, 'Protected workflow has a concurrent content change; refusing to remove it.');
+	}
+	if (typeof options.beforeAtomicCommit === 'function') {
+		options.beforeAtomicCommit({ parent: initialParent.parent, target: resolved.target });
+	}
+	const finalParent = captureParentBoundary(resolved.root, resolved.target);
+	const finalTarget = captureTargetState(resolved.target);
+	if (!sameParentBoundary(initialParent, finalParent) || !sameTargetState(initialTarget, finalTarget)) {
+		return blockedAtomicDecision(decision, 'Protected remove boundary changed before exact-content removal.');
+	}
+	fs.unlinkSync(resolved.target);
+	return { ...decision, removed: true, fullPath: resolved.target };
 }
 
 function buildProtectedStateAuditEvent(decision) {
@@ -313,12 +524,18 @@ function buildProtectedStateAuditEvent(decision) {
 		requiredSurface: decision.requiredSurface,
 		declaredSurface: decision.declaredSurface || null,
 		operation: decision.operation || 'write',
+		viaForgeApi: decision.viaForgeApi === true,
+		...(decision.sourceHead ? { sourceHead: decision.sourceHead } : {}),
+		contentHash: decision.contentHash || null,
 		reason: decision.reason,
 		repairHint: decision.repairHint,
 		metadata: {
 			actor: decision.actor || 'unknown',
 			path: decision.path,
 			operation: decision.operation || 'write',
+			viaForgeApi: decision.viaForgeApi === true,
+			...(decision.sourceHead ? { sourceHead: decision.sourceHead } : {}),
+			contentHash: decision.contentHash || null,
 			requiredSurface: decision.requiredSurface,
 			declaredSurface: decision.declaredSurface || null,
 			decision: decision.decision,
@@ -330,51 +547,31 @@ function buildProtectedStateAuditEvent(decision) {
 	return redact(event);
 }
 
+/**
+ * Best-effort: a failed audit write is reported to the caller, never thrown, so
+ * the protected-state decision itself still stands.
+ */
 function recordProtectedStateAuditEvent(decision, options = {}) {
 	const event = buildProtectedStateAuditEvent(decision);
-	const runCommand = options.runCommand || execFileSync;
-	try {
-		const args = [
-			'audit',
-			'record',
-			'--json',
-			'--kind',
-			'protected_state_write',
-			'--model',
-			'forge-protected-state',
-			'--prompt',
-			JSON.stringify({
-				actor: event.actor,
-				path: event.path,
-				operation: event.operation,
-			}),
-			'--response',
-			JSON.stringify({
-				decision: event.decision,
-				requiredSurface: event.requiredSurface,
-				repairHint: event.repairHint,
-			}),
-		];
-
-		if (event.metadata) {
-			args.push('--meta-json', JSON.stringify(event.metadata));
-		}
+	const logPath = path.resolve(options.cwd || process.cwd(), PROTECTED_STATE_AUDIT_LOG);
+	const appendRecord = options.appendRecord || appendCappedJsonlRecord;
 
-		const output = runCommand('bd', args, {
-			cwd: options.cwd || process.cwd(),
-			encoding: 'utf8',
-			stdio: ['ignore', 'pipe', 'pipe'],
-			timeout: options.timeoutMs || 5000,
-		});
-		return { success: true, event, output };
+	try {
+		const record = { ...event, recordedAt: options.now || new Date().toISOString() };
+		appendRecord(logPath, record, options.maxRecords || PROTECTED_STATE_AUDIT_MAX_RECORDS);
+		return { success: true, event, logPath };
 	} catch (error) {
-		return { success: false, event, error: error.message };
+		return { success: false, event, logPath, error: error.message };
 	}
 }
 
 module.exports = {
 	PROTECTED_SURFACES,
+	PROTECTED_STATE_AUDIT_LOG,
+	PROTECTED_STATE_AUDIT_MAX_RECORDS,
 	normalizeRepoPath,
+	hashProtectedContent,
+	createProtectedStateAuditRecord,
 	resolveRepoRelativePath,
 	lstatIfPresent,
 	assertNoAncestorSymlinkEscape,
@@ -382,6 +579,7 @@ module.exports = {
 	classifyProtectedPath,
 	assertProtectedWriteAllowed,
 	writeProtectedFile,
+	removeProtectedFile,
 	buildProtectedStateAuditEvent,
 	recordProtectedStateAuditEvent,
 };

package/lib/release-readiness.js

@@ -413,13 +413,27 @@ function readSyncManifestScanRoots(projectRoot) {
   }
 }
 
+// Scan roots reach here in whatever spelling their source used — a plugin manifest
+// directory entry, a sync-manifest file, an explicit scanRoots option — so they are
+// normalized once, at the single place they are resolved. walkFiles would join a trailing
+// separator away and scan the tree regardless, while isBdCensusPath would build `root//`
+// and match nothing under it; normalizing here is what keeps the census and the
+// pre-commit predicate from disagreeing about which files count.
+function normalizeScanRoot(root) {
+  if (typeof root !== 'string' || root.length === 0) {
+    return '';
+  }
+  return normalizeRepoPath(root).replace(/[/\\]+$/, '');
+}
+
 function getScanRoots(projectRoot, options = {}) {
   const roots = options.scanRoots || getDefaultScanRoots(projectRoot);
   return [
-    ...new Set([
-      ...roots,
-      ...readSyncManifestScanRoots(projectRoot),
-    ]),
+    ...new Set(
+      [...roots, ...readSyncManifestScanRoots(projectRoot)]
+        .map(normalizeScanRoot)
+        .filter(Boolean),
+    ),
   ];
 }
 
@@ -496,9 +510,8 @@ function addCallSites(groups, group, relativePath, lineEntries) {
 function trackedRepoFiles(projectRoot) {
   let output;
   try {
-    // NOSONAR S4036 — `git` is resolved from PATH by design (cross-platform CLI; the repo
-    // spawns git this way throughout and cannot hardcode a portable absolute path).
-    output = execFileSync('git', ['-C', projectRoot, 'ls-files', '-z'], {
+    // `git` is resolved from PATH by design; Forge cannot hardcode a portable absolute path.
+    output = execFileSync('git', ['-C', projectRoot, 'ls-files', '-z'], { // NOSONAR S4036 -- Fixed local Git executable with structured non-shell arguments is the trusted repository toolchain boundary.
       encoding: 'utf8',
       maxBuffer: 64 * 1024 * 1024,
     });
@@ -557,6 +570,38 @@ function auditBdCallSites(projectRoot, options = {}) {
   };
 }
 
+// Would a change to this repo-relative path shift the bd call-site census?
+//
+// The pre-commit auto-heal (scripts/sync-d20-audit.js) asks this before doing any work,
+// so it must answer exactly what auditBdCallSites would scan. It is therefore assembled
+// from that walk's own pieces — getScanRoots, shouldSkipRelativePath, isTextFile,
+// SKIP_DIR_NAMES — rather than a parallel list that could drift from the gate.
+function isBdCensusPath(projectRoot, filePath, options = {}) {
+  const relativePath = safeNormalizeRepoPath(projectRoot, filePath);
+  if (!relativePath || shouldSkipRelativePath(relativePath) || !isTextFile(relativePath, projectRoot)) {
+    return false;
+  }
+
+  // getScanRoots already returns normalized roots — re-normalizing here would be a second
+  // copy of that rule, free to drift from the one auditBdCallSites walks.
+  return getScanRoots(projectRoot, options)
+    .some(root => {
+      // walkFiles applies no directory skips to a root that is itself a file.
+      if (relativePath === root) {
+        return true;
+      }
+      if (!relativePath.startsWith(`${root}/`)) {
+        return false;
+      }
+      // Below a directory root it refuses to descend into skipped directories.
+      return !relativePath
+        .slice(root.length + 1)
+        .split('/')
+        .slice(0, -1)
+        .some(directory => SKIP_DIR_NAMES.has(directory));
+    });
+}
+
 function readRepoFile(projectRoot, relativePath) {
   const fullPath = absolutePath(projectRoot, relativePath);
   return fs.existsSync(fullPath) ? fs.readFileSync(fullPath, 'utf8') : '';
@@ -2096,6 +2141,7 @@ module.exports = {
   auditBdCallSites,
   buildReadinessReport,
   canonicalizeAuditArtifact,
+  isBdCensusPath,
   renderBdCallSiteAuditMarkdown,
   renderReadinessReport,
   writeAuditArtifact,

package/lib/review-adapter.js

@@ -8,6 +8,68 @@ const REQUIRED_REVIEW_ADAPTER_METHODS = [
   'score',
 ];
 
+const REVIEW_EVIDENCE_LIMITS = Object.freeze({
+  maxTextChars: 256,
+});
+
+const SECRET_PATTERNS = [
+  /\bBearer\s+\S+/gi,
+  /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g,
+  /\bgithub_pat_\w{20,}\b/gi,
+  /\b(?:sk_(?:live|test)_[A-Za-z0-9]{16,}|sk-[A-Za-z0-9]{16,})\b/g,
+  /\bAKIA[0-9A-Z]{16}\b/gi,
+  /\b(?:api[_ -]?key|authorization|credential|password|private[_ -]?key|secret|token)\s*[:=]\s*\S{8,}/gi,
+];
+const PRIVATE_PATH_PATTERNS = [
+  /[a-z]:\\Users\\[^\\\s]+(?:\\[^\s]*)?/gi,
+  /\/(?:Users|home)\/[^/\s]+(?:\/[^\s]*)?/g,
+  /\/root\/[^\s"'<>{}[\]]+/g,
+];
+
+function stripControlCharacters(value) {
+  let output = '';
+  for (const character of value) {
+    const code = character.codePointAt(0);
+    const control = (code >= 0 && code <= 8)
+      || code === 11
+      || code === 12
+      || (code >= 14 && code <= 31)
+      || code === 127;
+    output += control ? ' ' : character;
+  }
+  return output;
+}
+
+function normalizeEvidenceText(value, options = {}) {
+  const requestedLimit = options.maxChars ?? REVIEW_EVIDENCE_LIMITS.maxTextChars;
+  const maxChars = Number.isInteger(requestedLimit) && requestedLimit > 0
+    ? requestedLimit
+    : REVIEW_EVIDENCE_LIMITS.maxTextChars;
+  let text = stripControlCharacters(String(value ?? ''))
+    .replace(/[\r\n\t]+/g, ' ');
+  for (const pattern of SECRET_PATTERNS) text = text.replace(pattern, '[REDACTED]');
+  for (const pattern of PRIVATE_PATH_PATTERNS) text = text.replace(pattern, '[REDACTED_PATH]');
+  text = text.replace(/\s+/g, ' ').trim();
+  return text.length <= maxChars ? text : `${text.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+function classifyReviewActor(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return 'unknown';
+  const typename = value.authorTypename
+    || value.authorType
+    || value.actorTypename
+    || value.actorType
+    || value.author?.__typename;
+  const actorKinds = {
+    Bot: 'bot',
+    User: 'user',
+    Organization: 'organization',
+    Mannequin: 'mannequin',
+    EnterpriseUserAccount: 'enterprise-user',
+  };
+  return actorKinds[typename] || 'unknown';
+}
+
 class ReviewAdapter {
   constructor(options = {}) {
     this.id = options.id || 'review-adapter';
@@ -62,7 +124,10 @@ function validateReviewAdapter(adapter) {
 }
 
 module.exports = {
+  REVIEW_EVIDENCE_LIMITS,
   ReviewAdapter,
   REQUIRED_REVIEW_ADAPTER_METHODS,
+  classifyReviewActor,
+  normalizeEvidenceText,
   validateReviewAdapter,
 };

package/lib/shell-utils.js

@@ -105,7 +105,7 @@ function secureExecFileSync(command, args = [], options = {}) {
       // metacharacters, so fold them into a single command line and pass no args array —
       // identical execution through cmd.exe (npm.cmd/npx.cmd shims), no deprecation warning.
       const commandLine = [command, ...args].join(' ');
-      return _execFileSync(commandLine, [], { ...execOptions, shell: true });
+      return _execFileSync(commandLine, [], { env: process.env, ...execOptions, shell: true });
     }
     return _execFileSync(spec.file, args, execOptions);
   }