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

package/lib/protected-state-surfaces.js

@@ -25,7 +25,15 @@ function hashProtectedContent(content) {
 	return `sha256:${crypto.createHash('sha256').update(bytes).digest('hex')}`;
 }
 
-function createProtectedStateAuditRecord({ actor, surface, path: filePath, content, operation = 'generate' }) {
+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');
 	}
@@ -38,6 +46,8 @@ function createProtectedStateAuditRecord({ actor, surface, path: filePath, conte
 		requiredSurface: surface,
 		declaredSurface: surface,
 		operation,
+		viaForgeApi: viaForgeApi === true,
+		...(sourceHead ? { sourceHead } : {}),
 		contentHash: hashProtectedContent(content),
 		reason: `Forge API generated content for protected surface: ${surface}.`,
 		repairHint: null,
@@ -296,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) {
@@ -334,8 +427,88 @@ function writeProtectedFile(projectRoot, filePath, content, options = {}) {
 		};
 	}
 
-	fs.writeFileSync(resolved.target, content, options.encoding || 'utf8');
-	return { ...decision, contentHash: hashProtectedContent(content), 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) {
@@ -351,6 +524,8 @@ 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,
@@ -358,6 +533,8 @@ function buildProtectedStateAuditEvent(decision) {
 			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,
@@ -402,6 +579,7 @@ module.exports = {
 	classifyProtectedPath,
 	assertProtectedWriteAllowed,
 	writeProtectedFile,
+	removeProtectedFile,
 	buildProtectedStateAuditEvent,
 	recordProtectedStateAuditEvent,
 };

package/lib/release-readiness.js

@@ -510,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,
     });

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/skills-sync.js

@@ -34,6 +34,7 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { execFileSync } = require('node:child_process');
 const { parseFrontmatter } = require('./using-forge');
 
 /** Canonical skills live under this directory at the repo/package root. */
@@ -134,6 +135,23 @@ function normalizeContent(buffer) {
   return buffer.toString('utf8').replace(/\r\n/g, '\n');
 }
 
+function gitIgnoredCanonicalPaths(repoRoot, runGit = execFileSync, { strict = false } = {}) {
+  if (!fs.existsSync(path.join(repoRoot, '.git'))) return new Set();
+  try {
+    const output = runGit('git', [
+      'ls-files', '-z', '--others', '--ignored', '--exclude-standard', '--', 'skills',
+    ], {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    return new Set(output.split('\0').filter(Boolean).map(repoPath => repoPath.normalize('NFC')));
+  } catch (error) {
+    if (strict) throw error;
+    return new Set();
+  }
+}
+
 /**
  * Remove a symlink sitting at a target path so a real directory can be written
  * in its place. Only ever removes the link entry itself — never a real
@@ -177,13 +195,18 @@ function clearSymlinkAtPath(targetPath) {
  * @param {string} sourcePath - Source skill directory.
  * @param {string} targetPath - Target skill directory.
  */
-function copySkillDir(sourcePath, targetPath) {
+function copySkillDir(sourcePath, targetPath, excludeRelativePaths = new Set(), prefix = '') {
   fs.mkdirSync(targetPath, { recursive: true });
   for (const entry of fs.readdirSync(sourcePath, { withFileTypes: true })) {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
     const src = path.join(sourcePath, entry.name);
     const dest = path.join(targetPath, entry.name);
+    if (excludeRelativePaths.has(relative.normalize('NFC'))) {
+      fs.rmSync(dest, { recursive: true, force: true });
+      continue;
+    }
     if (entry.isDirectory()) {
-      copySkillDir(src, dest);
+      copySkillDir(src, dest, excludeRelativePaths, relative);
     } else if (entry.isFile()) {
       fs.copyFileSync(src, dest);
     }
@@ -204,7 +227,12 @@ function copySkillDir(sourcePath, targetPath) {
  * @param {boolean} [params.clean=false] - Remove canonical-managed stale dirs first.
  * @returns {{written: string[]}} Names of skills written.
  */
-function populateAgentSkills({ sourceRoot, targetSkillsDir, only, clean = false }) {
+function populateAgentSkills({ sourceRoot, targetSkillsDir, only, clean = false, excludeRelativePaths }) {
+  if (excludeRelativePaths === undefined) {
+    excludeRelativePaths = new Set([...gitIgnoredCanonicalPaths(sourceRoot)]
+      .map(repoPath => repoPath.slice('skills/'.length))
+      .filter(relative => !/^[^/]+\/SKILL\.md$/.test(relative)));
+  }
   const skills = listCanonicalSkills(sourceRoot, { only });
   fs.mkdirSync(targetSkillsDir, { recursive: true });
 
@@ -225,7 +253,7 @@ function populateAgentSkills({ sourceRoot, targetSkillsDir, only, clean = false
     // Defensive: clear a pre-existing (possibly dangling) symlink so the copy
     // doesn't fail. Only symlinks are removed — real dirs are overwritten in place.
     clearSymlinkAtPath(targetPath);
-    copySkillDir(skill.sourcePath, targetPath);
+    copySkillDir(skill.sourcePath, targetPath, excludeRelativePaths, skill.name);
     written.push(skill.name);
   }
   return { written };
@@ -238,9 +266,12 @@ function populateAgentSkills({ sourceRoot, targetSkillsDir, only, clean = false
  * @param {string} targetPath - Target (generated) skill dir.
  * @returns {{file: string, status: 'missing'|'changed'|'extra'}[]} Drift entries.
  */
-function diffSkillDir(sourcePath, targetPath) {
+function diffSkillDir(sourcePath, targetPath, excludeRelativePaths = new Set(), prefix = '') {
   const drift = [];
-  const sourceFiles = new Set(listFilesRecursive(sourcePath));
+  const sourceFiles = new Set(listFilesRecursive(sourcePath).filter(rel => {
+    const relative = prefix ? `${prefix}/${rel}` : rel;
+    return !excludeRelativePaths.has(relative.normalize('NFC'));
+  }));
   const targetFiles = new Set(listFilesRecursive(targetPath));
 
   for (const rel of sourceFiles) {
@@ -264,6 +295,28 @@ function diffSkillDir(sourcePath, targetPath) {
   return drift;
 }
 
+function collectAgentSkillDrift({ repoRoot, rel, skills, canonicalByName, excludeRelativePaths }) {
+  const agentDir = path.join(repoRoot, rel);
+  const drift = [];
+  const targetNames = fs.readdirSync(agentDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name);
+  for (const skill of skills) {
+    const targetPath = path.join(agentDir, skill.name);
+    if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
+      drift.push({ agent: rel, skill: skill.name, file: 'SKILL.md', status: 'missing' });
+      continue;
+    }
+    for (const entry of diffSkillDir(skill.sourcePath, targetPath, excludeRelativePaths, skill.name)) {
+      drift.push({ agent: rel, skill: skill.name, ...entry });
+    }
+  }
+  for (const name of targetNames) {
+    if (!canonicalByName.has(name)) drift.push({ agent: rel, skill: name, file: '*', status: 'stale' });
+  }
+  return drift;
+}
+
 /**
  * Check that existing agent skill mirrors match the canonical source.
  *
@@ -279,9 +332,12 @@ function diffSkillDir(sourcePath, targetPath) {
  * @param {string[]} [params.agentSkillDirs] - Override the agent dirs to scan.
  * @returns {{inSync: boolean, checkedAgents: string[], drift: object[]}}
  */
-function checkSkillsSync({ repoRoot, only, agentSkillDirs = AGENT_SKILL_DIRS }) {
+function checkSkillsSync({ repoRoot, only, agentSkillDirs = AGENT_SKILL_DIRS, runGit = execFileSync }) {
   const skills = listCanonicalSkills(repoRoot, { only });
   const canonicalByName = new Map(skills.map((s) => [s.name, s]));
+  const excludeRelativePaths = new Set([...gitIgnoredCanonicalPaths(repoRoot, runGit)]
+    .map(repoPath => repoPath.slice('skills/'.length))
+    .filter(relative => !/^[^/]+\/SKILL\.md$/.test(relative)));
   const drift = [];
   const checkedAgents = [];
 
@@ -290,31 +346,7 @@ function checkSkillsSync({ repoRoot, only, agentSkillDirs = AGENT_SKILL_DIRS })
     if (!fs.existsSync(agentDir)) continue; // populated at setup time; absence ≠ drift
     checkedAgents.push(rel);
 
-    const targetNames = fs
-      .readdirSync(agentDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory())
-      .map((e) => e.name);
-
-    // Skills present canonically but missing/changed in the mirror.
-    for (const skill of skills) {
-      const targetPath = path.join(agentDir, skill.name);
-      // A regular file at the skill path is corruption, not a valid mirror:
-      // treat it as drift instead of letting diffSkillDir() throw ENOTDIR.
-      if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
-        drift.push({ agent: rel, skill: skill.name, file: 'SKILL.md', status: 'missing' });
-        continue;
-      }
-      for (const entry of diffSkillDir(skill.sourcePath, targetPath)) {
-        drift.push({ agent: rel, skill: skill.name, ...entry });
-      }
-    }
-
-    // Skill dirs in the mirror with no canonical source = stale.
-    for (const name of targetNames) {
-      if (!canonicalByName.has(name)) {
-        drift.push({ agent: rel, skill: name, file: '*', status: 'stale' });
-      }
-    }
+    drift.push(...collectAgentSkillDrift({ repoRoot, rel, skills, canonicalByName, excludeRelativePaths }));
   }
 
   return { inSync: drift.length === 0, checkedAgents, drift };
@@ -327,6 +359,7 @@ module.exports = {
   listCanonicalSkills,
   listFilesRecursive,
   clearSymlinkAtPath,
+  gitIgnoredCanonicalPaths,
   populateAgentSkills,
   diffSkillDir,
   checkSkillsSync,