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

package/scripts/commitlint.js

@@ -1,15 +1,11 @@
 #!/usr/bin/env node
 /**
  * Cross-platform commitlint runner for lefthook commit-msg hook.
- * Replaces direct npx invocation which fails on Windows without shell: true.
- * Works on Windows CMD, PowerShell, macOS, Linux.
+ * Executes the installed commitlint CLI directly on Windows, macOS, and Linux.
  */
 
 const { spawnSync } = require('node:child_process');
 
-// On Windows, npx is npx.cmd — shell: true resolves .cmd extensions
-const isWindows = process.platform === 'win32';
-
 const commitMsgFile = process.argv[2];
 if (!commitMsgFile) {
   // Write synchronously so the message is flushed before exit: on Windows the
@@ -18,17 +14,19 @@ if (!commitMsgFile) {
   process.exit(1);
 }
 
-// Detect package manager: prefer bun (fast, works with bun.lock), fall back to npx
-// npx fails on Windows when npm 11's arborist encounters bun.lock instead of package-lock.json
-const hasBunLock = require('node:fs').existsSync(
-  require('node:path').join(__dirname, '../bun.lock')
-);
-const runner = hasBunLock ? 'bunx' : 'npx';
+let commitlintCli;
+try {
+  commitlintCli = require.resolve('@commitlint/cli/cli.js');
+} catch (error) {
+  console.error(`❌ Failed to resolve commitlint: ${error.message}`);
+  console.error('   Install project dependencies before committing.');
+  process.exit(1);
+}
 
 const result = spawnSync(
-  runner,
-  ['commitlint', '--edit', commitMsgFile],
-  { stdio: 'inherit', shell: isWindows }
+  process.execPath,
+  [commitlintCli, '--edit', commitMsgFile],
+  { stdio: 'inherit', shell: false }
 );
 
 if (result.error) {
@@ -40,5 +38,5 @@ if (result.error) {
 }
 
 if (result.status !== 0) {
-  process.exit(result.status);
+  process.exit(result.status ?? 1);
 }

package/scripts/generate-risk-manifest.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { parse } = require('yaml');
+const { stableStringify } = require('../lib/kernel/evaluators');
+const { hashManifest, validateManifest } = require('../lib/validation/risk-manifest');
+const crypto = require('node:crypto');
+
+const ROOT = path.resolve(__dirname, '..');
+const SOURCE_PATH = path.join(ROOT, 'validation', 'risk-manifest.source.yaml');
+const OUTPUT_PATH = path.join(ROOT, 'validation', 'risk-manifest.v1.json');
+
+function sha256(value) {
+  return `sha256:${crypto.createHash('sha256').update(value, 'utf8').digest('hex')}`;
+}
+
+function compareText(left, right) {
+  if (left === right) return 0;
+  return left < right ? -1 : 1;
+}
+
+function sortById(entries) {
+  return [...entries].sort((left, right) => compareText(left.id, right.id));
+}
+
+function normalizeSource(source) {
+  const canonicalSource = source.replaceAll('\r\n', '\n').replaceAll('\r', '\n');
+  const parsed = parse(canonicalSource);
+  const manifest = {
+    schema_id: parsed.schema_id,
+    revision: parsed.revision,
+    source_hash: sha256(canonicalSource),
+    generator_version: 'forge-risk-manifest-generator.v1',
+    commands: sortById(parsed.commands).map((command) => ({
+      ...command,
+      argv: [...command.argv],
+    })),
+    gates: sortById(parsed.gates).map((gate) => ({
+      ...gate,
+      command_ids: [...gate.command_ids].sort(compareText),
+    })),
+    lanes: sortById(parsed.lanes).map((lane) => ({
+      ...lane,
+      command_ids: [...lane.command_ids].sort(compareText),
+    })),
+    risks: sortById(parsed.risks).map((risk) => ({
+      ...risk,
+      gate_ids: [...risk.gate_ids].sort(),
+    })),
+    owners: sortById(parsed.owners).map((owner) => ({
+      ...owner,
+      risk_ids: [...owner.risk_ids].sort(),
+      canonical_test_ids: [...owner.canonical_test_ids].sort(),
+      dependent_routes: [...owner.dependent_routes].sort(),
+      platform_runtime_additions: [...owner.platform_runtime_additions].sort(),
+      lanes: [...owner.lanes].sort(),
+      package_roots: [...owner.package_roots].sort(),
+      selectors: [...owner.selectors].sort((left, right) => compareText(left.kind, right.kind)
+        || compareText(left.prefix, right.prefix)),
+    })),
+    unknown_owner_fallback: {
+      ...parsed.unknown_owner_fallback,
+      required_gates: [...parsed.unknown_owner_fallback.required_gates].sort(),
+    },
+  };
+  manifest.manifest_hash = hashManifest(manifest);
+  validateManifest(manifest);
+  return JSON.parse(stableStringify(manifest));
+}
+
+function generateRiskManifest(source) {
+  return `${JSON.stringify(normalizeSource(source), null, 2)}\n`;
+}
+
+function main(args = process.argv.slice(2)) {
+  const generated = generateRiskManifest(fs.readFileSync(SOURCE_PATH, 'utf8'));
+  if (args.includes('--check')) {
+    if (!fs.existsSync(OUTPUT_PATH) || fs.readFileSync(OUTPUT_PATH, 'utf8') !== generated) {
+      console.error('Risk manifest is stale. Run: node scripts/generate-risk-manifest.js');
+      process.exitCode = 1;
+    }
+    return;
+  }
+  fs.writeFileSync(OUTPUT_PATH, generated, 'utf8');
+}
+
+if (require.main === module) main();
+
+module.exports = { generateRiskManifest, normalizeSource };

package/scripts/github-context-bridge.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# GH_CMD bridge: re-enter this Forge runtime without credentials in the Bash parent.
+set -euo pipefail
+
+: "${FORGE_GITHUB_RUNTIME:?Forge GitHub runtime is required}"
+if [[ -n "${FORGE_GITHUB_ENTRY:-}" ]]; then
+  exec "$FORGE_GITHUB_RUNTIME" "$FORGE_GITHUB_ENTRY" github run -- gh "$@"
+else
+  exec "$FORGE_GITHUB_RUNTIME" github run -- gh "$@"
+fi

package/scripts/legacy-claim-repair.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+
+const {
+	createBuiltinSQLiteDriver,
+	hardenBackupPermissions,
+	hardenBackupPermissionsBatch,
+} = require('../lib/kernel/sqlite-driver');
+const {
+	ClaimRepairError,
+	createVerifiedClaimRepairBackup,
+} = require('../lib/kernel/legacy-claim-repair');
+
+const HELP = `Usage:
+  bun scripts/legacy-claim-repair.js --dry-run --database <kernel.sqlite> --backup <separate.sqlite> --at <canonical-UTC>
+  bun scripts/legacy-claim-repair.js --apply --database <kernel.sqlite> --backup <separate.sqlite> --at <canonical-UTC> --approved-digest <sha256> --actor <identity>
+
+The tool never discovers or repairs a database automatically. Apply is rejected
+without a verified restorable backup and the exact human-approved dry-run digest.`;
+
+function parseArgs(argv = []) {
+	const result = { mode: null };
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (arg === '--help' || arg === '-h') return { help: true };
+		if (arg === '--dry-run' || arg === '--apply') {
+			const mode = arg.slice(2);
+			if (result.mode && result.mode !== mode) throw new Error('Choose exactly one of --dry-run or --apply');
+			result.mode = mode;
+			continue;
+		}
+		const names = {
+			'--database': 'databasePath',
+			'--backup': 'backupPath',
+			'--at': 'observedAt',
+			'--approved-digest': 'approvedDigest',
+			'--actor': 'actor',
+		};
+		if (!Object.hasOwn(names, arg)) throw new Error(`Unknown argument: ${arg}`);
+		const name = names[arg];
+		const value = argv[index + 1];
+		if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value`);
+		result[name] = value;
+		index += 1;
+	}
+	if (!result.mode) throw new Error('Choose exactly one of --dry-run or --apply');
+	for (const required of ['databasePath', 'backupPath', 'observedAt']) {
+		if (!result[required]) throw new Error(`Missing required option: ${required}`);
+	}
+	for (const requiredPath of ['databasePath', 'backupPath']) {
+		if (!path.isAbsolute(result[requiredPath])) {
+			throw new Error(`${requiredPath} must be an absolute path`);
+		}
+	}
+	if (result.mode === 'apply' && !result.approvedDigest) {
+		throw new Error('--apply requires --approved-digest');
+	}
+	if (result.mode === 'apply' && !result.actor) {
+		throw new Error('--apply requires --actor');
+	}
+	if (result.mode === 'dry-run' && result.approvedDigest) {
+		throw new Error('--approved-digest is valid only with --apply');
+	}
+	if (result.mode === 'dry-run' && result.actor) {
+		throw new Error('--actor is valid only with --apply');
+	}
+	return result;
+}
+
+async function run(options, dependencies = {}) {
+	const openDriver = dependencies.openDriver
+		|| (databasePath => createBuiltinSQLiteDriver({ databasePath }));
+	const createBackup = dependencies.createVerifiedClaimRepairBackup
+		|| createVerifiedClaimRepairBackup;
+	const hardenPath = dependencies.hardenPath || hardenBackupPermissions;
+	const hardenPaths = dependencies.hardenPaths
+		|| (dependencies.hardenPath ? dependencies.hardenPath.batch : hardenBackupPermissionsBatch);
+	const sourceDriver = openDriver(options.databasePath);
+	try {
+		if (options.mode === 'dry-run') {
+			const backup = await createBackup({
+				sourceDriver,
+				backupPath: options.backupPath,
+				observedAt: options.observedAt,
+				openDriver,
+				hardenPath,
+				hardenPaths,
+			});
+			const preflight = await sourceDriver.preflightLegacyClaimRepair({ observedAt: options.observedAt });
+			if (preflight.digest !== backup.plan_digest) {
+				throw new ClaimRepairError(
+					'CLAIM_REPAIR_BACKUP_DRIFT',
+					'Live claim authority changed while binding the reported preflight to its verified backup',
+				);
+			}
+			return { ok: true, preflight, backup };
+		}
+
+		const receipt = await sourceDriver.applyLegacyClaimRepair({
+			observedAt: options.observedAt,
+			approvedDigest: options.approvedDigest,
+			backupPath: options.backupPath,
+			actor: options.actor,
+		});
+		return { ok: true, receipt };
+	} finally {
+		sourceDriver.close();
+	}
+}
+
+async function main(argv = process.argv.slice(2)) {
+	try {
+		const options = parseArgs(argv);
+		if (options.help) {
+			process.stdout.write(`${HELP}\n`);
+			return;
+		}
+		process.stdout.write(`${JSON.stringify(await run(options), null, 2)}\n`);
+	} catch (error) {
+		const recoveryPath = error?.code === 'CLAIM_REPAIR_BACKUP_POSTCOMMIT_DRIFT'
+			&& typeof error?.details?.recovery_path === 'string'
+			? error.details.recovery_path
+			: null;
+		process.stderr.write(`${JSON.stringify({
+			ok: false,
+			error: {
+				code: error?.code || 'CLAIM_REPAIR_USAGE',
+				message: error?.message || String(error),
+				...(recoveryPath ? { recovery_path: recoveryPath } : {}),
+			},
+		}, null, 2)}\n`);
+		process.exitCode = 1;
+	}
+}
+
+if (require.main === module) void main();
+
+module.exports = {
+	HELP,
+	main,
+	parseArgs,
+	run,
+};

package/scripts/lib/behavioral-eval-runtime.js

@@ -156,6 +156,7 @@ function createPrAdapter(projectRoot, execFile = execFileSync) {
 }
 
 async function resolveAttribution(projectRoot, head, env, deps = {}) {
+  const prExec = deps.runGh ? (_command, args, options) => deps.runGh(args, options) : deps.execFileSync;
   const branch = resolveBranch(projectRoot, deps.execFileSync);
   const requestedIssueId = env.FORGE_EVAL_ISSUE_ID;
   if (requestedIssueId && !UUID.test(String(requestedIssueId))) {
@@ -172,11 +173,11 @@ async function resolveAttribution(projectRoot, head, env, deps = {}) {
   }
   const pr = explicitPr
     ? Number(env.FORGE_EVAL_PR)
-    : resolvePrFromGh(projectRoot, deps.execFileSync);
+    : resolvePrFromGh(projectRoot, prExec);
   if (!pr) throw new Error('attribution.pr_unavailable');
   let state;
   try {
-    const adapter = deps.prAdapter || createPrAdapter(projectRoot, deps.execFileSync);
+    const adapter = deps.prAdapter || createPrAdapter(projectRoot, prExec);
     state = await adapter.readState(pr);
   } catch {
     throw new Error('attribution.pr_unavailable');

package/scripts/process-tree.js

@@ -9,6 +9,7 @@ const { spawnSync: defaultSpawnSync } = require('node:child_process');
 const MANIFEST_ENV = 'FORGE_TEST_PROCESS_MANIFEST';
 const TOKEN_ENV = 'FORGE_TEST_PROCESS_TOKEN';
 const INSTANCE_ENV = 'FORGE_TEST_PROCESS_INSTANCE';
+const SESSION_ENV = 'FORGE_SESSION_ID';
 const MANIFEST_VERSION = 1;
 const DEFAULT_MANIFEST_DIR = path.join(os.tmpdir(), 'forge-test-processes');
 
@@ -326,7 +327,11 @@ function createProcessTree(options = {}) {
     if (!identity && !hasCustomIdentity) return `unverified:${pid}`;
     return identity;
   };
-  const token = String(options.token || env[TOKEN_ENV] || randomUUID());
+  // A Forge claim records FORGE_SESSION_ID. Use that same stable runtime token
+  // for the root manifest, while preserving an inherited manifest token for
+  // nested process trees that are already attached to their parent run.
+  const inheritedToken = nonEmptyString(options.token) || nonEmptyString(env[TOKEN_ENV]);
+  const token = String(inheritedToken || env[SESSION_ENV] || randomUUID());
   const explicitManifestPath = nonEmptyString(options.manifestPath);
   const environmentManifestPath = nonEmptyString(env[MANIFEST_ENV]);
   const manifestDir = options.manifestDir || DEFAULT_MANIFEST_DIR;
@@ -351,7 +356,11 @@ function createProcessTree(options = {}) {
   const existing = readProcessManifest(manifestPath, fsApi, processApi);
   // An environment-provided path may belong to another run. Treat that as
   // unverifiable and fail closed; never overwrite or reap another run's marker.
-  const usable = !markerExists || (existing && existing.token === token);
+  const inheritedManifestVerified = explicitManifestPath
+    || !environmentManifestPath
+    || Boolean(inheritedToken && existing?.token === inheritedToken);
+  const usable = inheritedManifestVerified
+    && (!markerExists || (existing && existing.token === token));
   let manifest = existing && existing.token === token
     ? existing
     : (usable ? createInitialManifest(token, processApi, getProcessIdentity, instanceId) : null);
@@ -749,11 +758,14 @@ function reconcileProcessManifests(options = {}) {
 }
 
 module.exports = {
+  DEFAULT_MANIFEST_DIR,
   INSTANCE_ENV,
   MANIFEST_ENV,
   MANIFEST_VERSION,
   TOKEN_ENV,
   createProcessTree,
+  defaultGetProcessIdentity,
+  isValidManifest,
   readProcessManifest,
   reapProcessManifest,
   reconcileProcessManifests,