forge-workflow 0.1.0-beta.7 → 0.1.0-beta.8

package/lib/commands/push.js

@@ -1,12 +1,28 @@
 'use strict';
 
-const { execFileSync, spawnSync } = require('node:child_process');
+const { randomUUID } = require('node:crypto');
+const { execFileSync, spawn, spawnSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');
 const forgeToken = require('../../scripts/check-forge-token');
-const { QUICK_LANE_ENV_VAR, QUICK_LANE_VALUE, resolveFullSuiteTimeoutMs } = require('../../scripts/test');
+const {
+	QUICK_LANE_ENV_VAR,
+	QUICK_LANE_VALUE,
+	TIMEOUT_EXIT_CODE,
+	resolveFullSuiteTimeoutMs,
+	runCommand,
+} = require('../../scripts/test');
+const {
+	INSTANCE_ENV,
+	MANIFEST_ENV,
+	TOKEN_ENV,
+	createProcessTree,
+} = require('../../scripts/process-tree');
 const { fireAndForget } = require('../pr-monitor/reconcile-executor');
-const { verifyValidationReceipt } = require('../validation-receipt');
+const validationReceipt = require('../validation-receipt');
+
+const { verifyValidationReceipt } = validationReceipt;
+const PUSH_NONCE_ENV_VAR = forgeToken._internal.NONCE_ENV_VAR;
 
 const isWindows = process.platform === 'win32';
 
@@ -25,6 +41,19 @@ function detectPackageManager(projectRoot, existsSync = fs.existsSync) {
 	return 'npm';
 }
 
+function isForgeCheckout(projectRoot, readFileSync = fs.readFileSync, existsSync = fs.existsSync) {
+	try {
+		const manifest = JSON.parse(readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+		return manifest.name === 'forge-workflow'
+			&& manifest.bin?.forge === 'bin/forge.js'
+			&& manifest.scripts?.['test:full:parallel'] === 'node scripts/test-full-suite.js'
+			&& existsSync(path.join(projectRoot, 'scripts', 'test-full-suite.js'));
+	} catch (error) {
+		if (error instanceof SyntaxError || error.code === 'ENOENT' || error.code === 'ENOTDIR') return false;
+		throw error;
+	}
+}
+
 /**
  * Get the current git branch name.
  *
@@ -146,19 +175,26 @@ function maybeTriggerShepherdAfterPush({
  * the tests from a `forge push`.
  *
  * @param {boolean} quickMode - Whether this is a --quick push
- * @param {NodeJS.ProcessEnv} [baseEnv=process.env] - Environment to derive from
+ * @param {NodeJS.ProcessEnv} [baseEnv] - Environment to derive from
+ * @param {string} [nonce] - Signed invocation proof locator for the Git child
  * @returns {NodeJS.ProcessEnv} Environment for the git push child process
  */
-function buildPushEnv(quickMode, baseEnv = process.env) {
-	const env = { ...baseEnv };
+function buildPushEnv(quickMode, baseEnv, nonce) {
+	const env = { ...(baseEnv || process.env) };
+	delete env[PUSH_NONCE_ENV_VAR];
 	if (quickMode) {
 		env[QUICK_LANE_ENV_VAR] = QUICK_LANE_VALUE;
 	} else {
 		delete env[QUICK_LANE_ENV_VAR];
 	}
+	if (nonce) env[PUSH_NONCE_ENV_VAR] = nonce;
 	return env;
 }
 
+function buildGateEnv(baseEnv = process.env) {
+	return buildPushEnv(false, baseEnv);
+}
+
 /**
  * Run branch protection check as a subprocess.
  * @param {function} execFn - execFileSync or mock
@@ -166,9 +202,9 @@ function buildPushEnv(quickMode, baseEnv = process.env) {
  * @param {function} log - Logger function
  * @returns {boolean} True if branch protection passed
  */
-function runBranchProtection(execFn, projectRoot, log) {
+function runBranchProtection(execFn, projectRoot, log, env) {
 	try {
-		execFn('node', [path.join(projectRoot, 'scripts', 'branch-protection.js')]);
+		execFn('node', [path.join(projectRoot, 'scripts', 'branch-protection.js')], { env });
 		return true;
 	} catch (_err) { /* intentional: fallback to failure */ // NOSONAR S2486
 		log('Branch protection check failed — push aborted.');
@@ -183,11 +219,12 @@ function runBranchProtection(execFn, projectRoot, log) {
  * @param {string} projectRoot - Absolute path to project root
  * @returns {boolean} True if lint passed
  */
-function runLint(spawnFn, pkgManager, projectRoot) {
+function runLint(spawnFn, pkgManager, projectRoot, env) {
 	const lintResult = spawnFn(pkgManager, ['run', 'lint'], {
 		stdio: 'inherit',
 		shell: isWindows,
 		cwd: projectRoot,
+		env,
 	});
 	return lintResult.status === 0;
 }
@@ -280,18 +317,104 @@ function reportTestRunTermination(testResult, timeoutMs, log) {
 	log('Test run ended without an exit status — push aborted.');
 }
 
+async function runSupervisedTestCommand({
+	testCommand,
+	testArgs,
+	projectRoot,
+	env,
+	timeoutMs,
+	log,
+	spawnAsyncFn,
+	createProcessTreeFn,
+}) {
+	const isolatedEnv = { ...env };
+	delete isolatedEnv[MANIFEST_ENV];
+	delete isolatedEnv[TOKEN_ENV];
+	delete isolatedEnv[INSTANCE_ENV];
+	// A unique manifest prevents timeout cleanup from touching an outer
+	// validation run while allInstances reaches this runner's nested shards.
+	const processTree = createProcessTreeFn({
+		env: isolatedEnv,
+		token: randomUUID(),
+		allInstances: true,
+		reconcile: false,
+	});
+	let supervisedEnv = null;
+	try {
+		supervisedEnv = processTree.envFor(isolatedEnv);
+	} catch { /* handled by the fail-closed check below */ }
+	const supervisionMarker = supervisedEnv?.[MANIFEST_ENV];
+	if (typeof supervisionMarker !== 'string' || supervisionMarker.length === 0) {
+		log('Test supervision unavailable — push aborted.');
+		processTree.cleanup('SIGKILL');
+		return false;
+	}
+	let cancellationSignal = null;
+	const removeSignalHandlers = processTree.installSignalHandlers((signal) => {
+		cancellationSignal = signal;
+		processTree.cleanup('SIGKILL');
+	});
+	let terminationSignal = null;
+	const observingSpawn = (...spawnArgs) => {
+		const child = spawnAsyncFn(...spawnArgs);
+		child.once?.('close', (_status, signal) => {
+			terminationSignal = signal;
+		});
+		return child;
+	};
+	try {
+		if (cancellationSignal) return false;
+		const status = await runCommand(testCommand, testArgs, {
+			cwd: projectRoot,
+			detached: !isWindows,
+			env: supervisedEnv,
+			killSignal: TEST_RUN_KILL_SIGNAL,
+			processTree,
+			timeout: timeoutMs,
+			windowsHide: true,
+		}, observingSpawn);
+		if (cancellationSignal) {
+			reportTestRunTermination({ status: null, signal: cancellationSignal }, timeoutMs, log);
+			return false;
+		}
+		if (status === TIMEOUT_EXIT_CODE) {
+			reportTestRunTermination({
+				status: null,
+				signal: TEST_RUN_KILL_SIGNAL,
+				error: Object.assign(new Error('test run timed out'), { code: 'ETIMEDOUT' }),
+			}, timeoutMs, log);
+		}
+		if (terminationSignal) {
+			reportTestRunTermination({ status: null, signal: terminationSignal }, timeoutMs, log);
+			return false;
+		}
+		return status === 0;
+	} catch (error) {
+		reportTestRunTermination({ status: null, signal: null, error }, timeoutMs, log);
+		return false;
+	} finally {
+		removeSignalHandlers();
+		processTree.cleanup(cancellationSignal ? 'SIGKILL' : 'SIGTERM');
+	}
+}
+
 /**
  * Run tests unless in quick mode, logging warnings for first push.
- * @param {function} spawnFn - spawnSync or mock
- * @param {function} execFn - execFileSync or mock
- * @param {string} pkgManager - Package manager command
- * @param {string} projectRoot - Absolute path to project root
- * @param {boolean} quickMode - Whether to skip tests
- * @param {function} log - Logger function
- * @param {NodeJS.ProcessEnv} [env] - Environment used to resolve the test budget
- * @returns {boolean|undefined} True if tests passed, undefined if skipped
+ * @param {object} options - Test execution dependencies and state
+ * @returns {Promise<boolean|undefined>} True if tests passed, undefined if skipped
  */
-function runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log, env = process.env) {
+async function runTests({
+	spawnAsyncFn,
+	execFn,
+	readFileFn,
+	existsFn,
+	pkgManager,
+	projectRoot,
+	quickMode,
+	log,
+	env = process.env,
+	createProcessTreeFn = createProcessTree,
+}) {
 	if (quickMode) {
 		log('Tests skipped (--quick) — CI will run full suite on GitHub');
 		const branch = getCurrentBranch(execFn);
@@ -301,7 +424,10 @@ function runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log, env
 		return undefined;
 	}
 
-	// `forge push` runs the package-level `test` script, i.e. the whole suite.
+	const useForgeRunner = isForgeCheckout(projectRoot, readFileFn, existsFn);
+	const testCommand = useForgeRunner ? 'node' : pkgManager;
+	const testArgs = useForgeRunner ? ['scripts/test-full-suite.js'] : ['run', 'test'];
+
 	// Budget it from the shared full-suite budget in scripts/test.js — which is
 	// sized as ~2x the measured healthy full-suite runtime and overridable with
 	// FORGE_TEST_TIMEOUT_MS — instead of an arbitrary local cap: the old fixed
@@ -309,18 +435,108 @@ function runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log, env
 	// reintroduce a local constant here; change the shared budget with a fresh
 	// measurement instead.
 	const timeoutMs = resolveFullSuiteTimeoutMs(env);
-	const testResult = spawnFn(pkgManager, ['run', 'test'], {
-		stdio: 'inherit',
-		shell: isWindows,
-		cwd: projectRoot,
-		timeout: timeoutMs,
-		killSignal: TEST_RUN_KILL_SIGNAL,
+	return runSupervisedTestCommand({
+		testCommand,
+		testArgs,
+		projectRoot,
+		env,
+		timeoutMs,
+		log,
+		spawnAsyncFn,
+		createProcessTreeFn,
 	});
-	if (testResult.status === null || testResult.status === undefined) {
-		reportTestRunTermination(testResult, timeoutMs, log);
+}
+
+/**
+ * Consume Forge-owned push arguments while preserving Git-owned arguments.
+ * Only the first `--` is a Forge delimiter; everything after it belongs to Git.
+ *
+ * @param {string[]} args - Raw command arguments
+ * @param {object} flags - Parsed Forge flags
+ * @returns {{ quickMode: boolean, gitArgs: string[] }} Parsed push arguments
+ */
+function parsePushArguments(args, flags) {
+	const delimiterIndex = args.indexOf('--');
+	const forgeArgs = delimiterIndex === -1 ? args : args.slice(0, delimiterIndex);
+	const gitArgsAfterDelimiter = delimiterIndex === -1 ? [] : args.slice(delimiterIndex + 1);
+	const quickMode = delimiterIndex === -1
+		? Boolean(flags && (flags['--quick'] || flags.quick))
+		: forgeArgs.some(arg => arg === '--quick' || arg === '-q');
+	return {
+		quickMode,
+		gitArgs: [
+			...forgeArgs.filter(arg => arg !== '--quick' && arg !== '-q'),
+			...gitArgsAfterDelimiter,
+		],
+	};
+}
+
+/**
+ * Bind full-mode authorization to either the reused receipt or this fresh run.
+ * Quick mode has no test evidence and must carry no receipt identity.
+ */
+function receiptIdentityForPush(quickMode, validationReused, receipt) {
+	if (quickMode) return null;
+	if (validationReused) return receipt.identity;
+	return 'fresh-tests';
+}
+
+/**
+ * Write the short-lived pre-push authorization after all required gates pass.
+ * Failure is non-fatal because Lefthook then executes its gates normally.
+ */
+function writePushAuthorization({
+	tokenWrite,
+	worktreeRoot,
+	proofSnapshot,
+	quickMode,
+	completedGates,
+	validationReused,
+	receipt,
+	gateEnv,
+	log,
+}) {
+	try {
+		return tokenWrite(worktreeRoot, {
+			snapshot: proofSnapshot,
+			mode: quickMode ? 'quick' : 'full',
+			gates: completedGates,
+			receiptIdentity: receiptIdentityForPush(quickMode, validationReused, receipt),
+			env: gateEnv,
+		});
+	} catch (_err) { /* intentional: non-fatal, lefthook will re-run hooks */ // NOSONAR S2486
+		log('Warning: Could not write forge push token — lefthook hooks will run again');
+		return null;
+	}
+}
+
+/**
+ * Execute Git push and revoke this invocation's proof regardless of outcome.
+ */
+function executeGitPush({
+	execFn,
+	gitArgs,
+	quickMode,
+	baseEnv,
+	authorization,
+	tokenConsume,
+	worktreeRoot,
+	log,
+}) {
+	try {
+		execFn('git', ['push', ...gitArgs], {
+			stdio: 'inherit',
+			env: buildPushEnv(quickMode, baseEnv, authorization?.nonce),
+		});
+		return true;
+	} catch (_pushErr) { // NOSONAR S2486
+		log('git push failed.');
 		return false;
+	} finally {
+		if (authorization?.nonce) {
+			try { tokenConsume(worktreeRoot, { nonce: authorization.nonce }); } catch { /* best effort revocation */ }
+		}
 	}
-	return testResult.status === 0;
 }
 
 module.exports = {
@@ -344,59 +560,94 @@ module.exports = {
 	handler: async (args, flags, projectRoot, deps) => {
 		const execFn = deps?.execFileSync || execFileSync;
 		const spawnFn = deps?.spawnSync || spawnSync;
+		const spawnAsyncFn = deps?.spawn || spawn;
 		const existsFn = deps?.existsSync || fs.existsSync;
+		const readFileFn = deps?.readFileSync || fs.readFileSync;
 		const log = deps?.log || console.log;
 		const tokenWrite = deps?.writeForgeToken || forgeToken.write;
+		const tokenConsume = deps?.consumeForgeToken || forgeToken.consume;
+		const beginPushProof = deps?.beginPushProof || validationReceipt._pushProof.begin;
 		const verifyReceipt = deps?.verifyValidationReceipt || verifyValidationReceipt;
 
-		const quickMode = !!(flags && (flags['--quick'] || flags.quick));
+		const { quickMode, gitArgs } = parsePushArguments(args, flags);
 		const pkgManager = detectPackageManager(projectRoot, existsFn);
+		const worktreeRoot = resolveGitToplevel(execFn, projectRoot);
+		const gateEnv = buildGateEnv(deps?.env || process.env);
+		let proofSnapshot = null;
+		try {
+			proofSnapshot = beginPushProof(worktreeRoot, { env: gateEnv });
+		} catch { /* invalid snapshot falls back to ordinary hooks */ }
+		const completedGates = [];
 
 		// Step 1: Branch protection
-		const branchOk = runBranchProtection(execFn, projectRoot, log);
+		const branchOk = runBranchProtection(execFn, projectRoot, log, gateEnv);
 		if (!branchOk) {
 			return { success: false, quickMode, lintPassed: false, pushed: false };
 		}
+		completedGates.push('branch-protection');
 
 		// Auto-file rail (non-blocking): ensure the branch being pushed has a backing
 		// Kernel issue so started work never goes unfiled. Never aborts the push.
 		await autoFileBackingIssueForPush(projectRoot, execFn, deps || {});
 
 		// Step 2: Lint
-		const lintPassed = runLint(spawnFn, pkgManager, projectRoot);
+		const lintPassed = runLint(spawnFn, pkgManager, projectRoot, gateEnv);
 		if (!lintPassed) {
 			log('Lint failed — push aborted.');
 			return { success: false, quickMode, lintPassed: false, pushed: false };
 		}
+		completedGates.push('lint');
 
 		// Step 3: Tests (skip in quick mode)
 		const receipt = quickMode
 			? { valid: false }
-			: verifyReceipt(resolveGitToplevel(execFn, projectRoot));
+			: verifyReceipt(worktreeRoot);
 		const validationReused = receipt.valid === true;
 		if (validationReused) log(`Tests reused from full validation at ${receipt.head || 'current HEAD'}`);
 		const testsPassed = validationReused
 			? true
-			: runTests(spawnFn, execFn, pkgManager, projectRoot, quickMode, log, deps?.env || process.env);
+			: await runTests({
+				spawnAsyncFn,
+				execFn,
+				readFileFn,
+				existsFn,
+				pkgManager,
+				projectRoot,
+				quickMode,
+				log,
+				env: gateEnv,
+				createProcessTreeFn: deps?.createProcessTree || createProcessTree,
+			});
 		if (!quickMode && !testsPassed) {
 			return { success: false, quickMode, lintPassed: true, testsPassed: false, validationReused, pushed: false };
 		}
+		if (!quickMode) completedGates.push('tests');
 
-		// Step 4: Write nonce token so lefthook skips pre-push hooks.
-		// Write to the git worktree top-level (where the hook checks), not the
-		// inherited projectRoot, so the skip works from linked worktrees too.
-		try {
-			tokenWrite(resolveGitToplevel(execFn, projectRoot));
-		} catch (_err) { /* intentional: non-fatal, lefthook will re-run hooks */ // NOSONAR S2486
-			log('Warning: Could not write forge push token — lefthook hooks will run again');
-		}
+		// Step 4: Write invocation proof under worktree-private Git metadata.
+		const authorization = writePushAuthorization({
+			tokenWrite,
+			worktreeRoot,
+			proofSnapshot,
+			quickMode,
+			completedGates,
+			validationReused,
+			receipt,
+			gateEnv,
+			log,
+		});
 
 		// Step 5: git push with passthrough args
-		const gitArgs = args.filter(a => a !== '--quick');
-		try {
-			execFn('git', ['push', ...gitArgs], { stdio: 'inherit', env: buildPushEnv(quickMode) });
-		} catch (_pushErr) { // NOSONAR S2486
-			log('git push failed.');
+		const pushed = executeGitPush({
+			execFn,
+			gitArgs,
+			quickMode,
+			baseEnv: deps?.env || process.env,
+			authorization,
+			tokenConsume,
+			worktreeRoot,
+			log,
+		});
+		if (!pushed) {
 			return {
 				success: false,
 				quickMode,
@@ -424,6 +675,7 @@ module.exports = {
 	// Exposed for unit tests; not part of the CLI surface.
 	_internal: {
 		autoFileBackingIssueForPush,
+		buildGateEnv,
 		buildPushEnv,
 		maybeTriggerShepherdAfterPush,
 	},

package/lib/commands/release.js

@@ -9,13 +9,14 @@ const {
 const { runIssueOperation: defaultRunIssueOperation } = require('../forge-issues');
 const { normalizeArgs, normalizeIssueResult, withResolvedIssueBackend } = require('./_issue');
 const { generateNpmPublishWorkflow } = require('../npm-publish-workflow');
+const { generateTestWorkflow } = require('../test-workflow');
 const { updateBunWorkflowPins } = require('../bun-workflow-pins');
 
 // `forge release <id>` releases a claimed issue; `forge release check` runs the
 // release-readiness gate. The two share the top-level verb, so this command
 // dispatches `check` to the gate and routes everything else through the shared
 // issue dispatch (resolve backend → runIssueOperation('release') → normalize).
-const usage = 'Usage: forge release <id>  |  forge release check --target 0.1.0 [--json]  |  forge release regen-audit  |  forge release generate-npm-workflow --expect-head <full-sha>  |  forge release update-bun-pins --expect-head <full-sha>';
+const usage = 'Usage: forge release <id>  |  forge release check --target 0.1.0 [--json]  |  forge release regen-audit  |  forge release generate-npm-workflow --expect-head <full-sha>  |  forge release generate-test-workflow --expect-head <full-sha>  |  forge release update-bun-pins --expect-head <full-sha>';
 
 async function runReleaseIssue(args, projectRoot, opts = {}) {
   const resolved = withResolvedIssueBackend(projectRoot, opts);
@@ -59,6 +60,22 @@ function parseReleaseArgs(args = []) {
 
 async function handler(args, _flags, projectRoot, opts = {}) {
 	const parsed = parseReleaseArgs(args);
+	if (parsed.subcommand === 'generate-test-workflow') {
+		const generator = opts.generateTestWorkflow || generateTestWorkflow;
+		const generated = await generator(projectRoot, {
+			env: opts.env,
+			kernelDeps: opts.kernelDeps,
+			expectedHead: parsed.expectedHead,
+			resolveHead: opts.resolveHead,
+		});
+		return generated.success
+			? {
+				success: true,
+				generated,
+				output: `Generated ${generated.path} (${generated.contentHash}).\n`,
+			}
+			: generated;
+	}
 	if (parsed.subcommand === 'update-bun-pins') {
 		const updater = opts.updateBunWorkflowPins || updateBunWorkflowPins;
 		const updated = await updater(projectRoot, {

package/lib/commands/test.js

@@ -28,6 +28,8 @@ const LOCKFILE_MAP = [
 
 const DEFAULT_TIMEOUT = 120000;
 const DIRECT_TEST_CANDIDATES = Object.freeze({
+	'lib/test-workflow.js': ['test/test-workflow.test.js'],
+	'lib/workflow-templates/test.yml': ['test/test-workflow.test.js'],
 	'bin/forge.js': [
 		'test/cli-flags.test.js',
 		'test/forge-cli-registry.test.js',
@@ -86,7 +88,13 @@ const DIRECT_TEST_CANDIDATES = Object.freeze({
 		'test/github-launcher.test.js',
 		'test/integration/github-account-context.test.js',
 	],
+	'bin/forge-gh-proxy.js': ['test/bin/forge-gh-proxy.test.js', 'test/github-launcher.test.js'],
+	'bin/forge-github-credential.js': ['test/bin/forge-github-credential.test.js', 'test/github-launcher.test.js'],
 	'lib/github-context.js': ['test/github-context.test.js', 'test/integration/github-account-context.test.js'],
+	'lib/github-credential.js': ['test/github-credential.test.js', 'test/github-launcher.test.js'],
+	'lib/github-router.js': ['test/github-router.test.js', 'test/commands/github.test.js'],
+	'lib/gh-proxy.js': ['test/gh-proxy.test.js', 'test/github-launcher.test.js'],
+	'lib/native-gh.js': ['test/native-gh.test.js', 'test/integration/github-account-context.test.js'],
 	'lib/commands/_registry.js': [
 		'test/commands/_registry.test.js',
 		'test/commands/_registry-github-context.test.js',