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

package/lib/commands/validate.js

@@ -95,7 +95,6 @@ function getExecOptions(rootDir = process.cwd(), fullSuite = false) {
 }
 
 const ERROR_PATTERNS = {
-	COMMAND_NOT_FOUND: ['ENOENT', 'not found'],
 	NO_LOCK_FILE: ['requires an existing', 'package-lock'],
 	GIT_LISTING_UNAVAILABLE: [
 		'not a git repository',
@@ -113,9 +112,7 @@ const ERROR_PATTERNS = {
  * @private
  */
 function isCommandNotFound(error) {
-	return ERROR_PATTERNS.COMMAND_NOT_FOUND.some(pattern =>
-		error.message.includes(pattern),
-	);
+	return error?.code === 'ENOENT';
 }
 
 function isGitListingUnavailableError(error) {
@@ -360,7 +357,7 @@ async function runTypeCheck() {
  * const result = await runLint();
  * console.log(`Warnings: ${result.warnings}, Errors: ${result.errors}`);
  */
-async function runLint(exec = execFileSync) {
+async function runLint(exec = secureExecFileSync) {
 	const startTime = Date.now();
 
 	try {
@@ -577,6 +574,21 @@ async function runSecurityScan() { // NOSONAR S3776
  */
 function parseTestCounts(output) {
 	const text = String(output || '');
+	const effectiveBudgetMatch = /Full suite resource budget: requested=(default|\d+) effective=(\d+)/.exec(text);
+	const rejectedBudgetMatch = /Full suite resource budget: requested=(\d+) minimum=(\d+) outcome=rejected/.exec(text);
+	let resourceBudget;
+	if (effectiveBudgetMatch) {
+		resourceBudget = {
+			requested: effectiveBudgetMatch[1] === 'default' ? null : Number(effectiveBudgetMatch[1]),
+			effective: Number(effectiveBudgetMatch[2]),
+		};
+	} else if (rejectedBudgetMatch) {
+		resourceBudget = {
+			requested: Number(rejectedBudgetMatch[1]),
+			minimum: Number(rejectedBudgetMatch[2]),
+			outcome: 'rejected',
+		};
+	}
 	const aggregateMatches = [...text.matchAll(
 		/Full suite aggregate: status=(PASS|FAIL|INCOMPLETE) tests=(\d+) assertions=\d+ passed=(\d+) failed=(\d+) errors=(\d+) skipped=(\d+)/g,
 	)]; // NOSONAR S5852 - fixed tokens and bounded numeric fields
@@ -585,6 +597,7 @@ function parseTestCounts(output) {
 		const total = parseNumber(aggregate, 2);
 		return {
 			status: aggregate[1],
+			resourceBudget,
 			passed: parseNumber(aggregate, 3),
 			failed: parseNumber(aggregate, 4),
 			errors: parseNumber(aggregate, 5),
@@ -598,7 +611,24 @@ function parseTestCounts(output) {
 	const skipped = parseNumber(/(\d+) skip/.exec(text));  // NOSONAR S5852 - bounded \d+ pattern
 	const ranMatch = /Ran (\d+) tests/.exec(text);  // NOSONAR S5852 - bounded \d+ pattern
 	const total = ranMatch ? parseNumber(ranMatch, 1) : passed + failed + skipped;
-	return { passed, failed, skipped, total, testsFound: total > 0 };
+	return { passed, failed, skipped, total, testsFound: total > 0, resourceBudget };
+}
+
+function parseResourceBudget(args = []) {
+	let budget = null;
+	for (let index = 0; index < args.length; index += 1) {
+		if (args[index] !== '--shards') continue;
+		const value = args[index + 1];
+		if (!/^[1-9]\d*$/.test(String(value ?? ''))) {
+			throw new TypeError('--shards must be a positive integer resource budget');
+		}
+		budget = Number(value);
+		if (!Number.isSafeInteger(budget)) {
+			throw new TypeError('--shards must be a positive integer resource budget');
+		}
+		index += 1;
+	}
+	return budget;
 }
 
 function isForgeCheckout(rootDir) {
@@ -614,17 +644,142 @@ function isForgeCheckout(rootDir) {
 	}
 }
 
-async function runAllTests(exec = execFileSync, rootDir = process.cwd()) {
+function isValidationRootAvailable(rootDir) {
+	try {
+		return fs.statSync(rootDir).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function unavailableValidationRootResult(startTime) {
+	return {
+		success: false,
+		testsFound: false,
+		fullSuite: false,
+		duration: Date.now() - startTime,
+		passed: 0,
+		failed: 0,
+		total: 0,
+		message: 'Test execution failed: validation root directory is unavailable',
+	};
+}
+
+function testExecutionErrorResult(error, startTime, rootDir, useFullSuite, timeout) {
+	const output = error.stdout || error.message;
+	const counts = parseTestCounts(output);
+	const budgetEvidence = counts.resourceBudget ? { resourceBudget: counts.resourceBudget } : {};
+	if (error.code === 'ETIMEDOUT' || (error.killed && error.signal === 'SIGTERM')) {
+		return {
+			success: false,
+			fullSuite: useFullSuite,
+			...budgetEvidence,
+			duration: Date.now() - startTime,
+			passed: 0,
+			failed: 0,
+			total: 0,
+			message: validationTimeoutMessage('Test execution', timeout),
+		};
+	}
+
+	if (isCommandNotFound(error)) {
+		if (!isValidationRootAvailable(rootDir)) {
+			return { ...unavailableValidationRootResult(startTime), ...budgetEvidence };
+		}
+		return {
+			success: true,
+			skipped: true,
+			testsFound: false,
+			fullSuite: useFullSuite,
+			...budgetEvidence,
+			duration: Date.now() - startTime,
+			passed: 0,
+			failed: 0,
+			total: 0,
+			message: 'Tests skipped: test runner not found. Install Node.js and Bun to run tests.',
+		};
+	}
+
+	if (counts.resourceBudget?.outcome === 'rejected') {
+		return {
+			success: false,
+			testsFound: false,
+			fullSuite: useFullSuite,
+			resourceBudget: counts.resourceBudget,
+			duration: Date.now() - startTime,
+			passed: 0,
+			failed: 0,
+			total: 0,
+			message: `Full suite resource budget rejected: requested=${counts.resourceBudget.requested} minimum=${counts.resourceBudget.minimum}`,
+			output,
+		};
+	}
+	const passed = counts.passed;
+	const failed = counts.failed > 0 ? counts.failed : Math.max(1, counts.errors || 0);
+	const total = counts.total > 0 ? counts.total : passed + failed + counts.skipped;
+
+	return {
+		success: false,
+		testsFound: counts.testsFound,
+		fullSuite: useFullSuite,
+		resourceBudget: counts.resourceBudget,
+		duration: Date.now() - startTime,
+		passed,
+		failed,
+		total,
+		message: `${failed}/${total} tests failed`,
+		output,
+	};
+}
+
+async function runAllTests(exec = execFileSync, rootDir = process.cwd(), resourceBudget = null) {
 	const startTime = Date.now();
+	if (!isValidationRootAvailable(rootDir)) return unavailableValidationRootResult(startTime);
 	const useFullSuite = isForgeCheckout(rootDir);
+	if (resourceBudget !== null && !useFullSuite) {
+		return {
+			success: false,
+			testsFound: false,
+			fullSuite: false,
+			duration: Date.now() - startTime,
+			passed: 0,
+			failed: 0,
+			total: 0,
+			message: '--shards requires the canonical Forge full-suite runner',
+		};
+	}
 	const command = useFullSuite ? 'node' : 'bun';
 	const args = useFullSuite ? ['scripts/test-full-suite.js'] : ['test', '--timeout', '30000'];
+	if (useFullSuite && resourceBudget !== null) args.push('--shards', String(resourceBudget));
 	const execOptions = getExecOptions(rootDir, useFullSuite);
 
 	try {
 		const result = exec(command, args, execOptions);  // NOSONAR S4036 - fixed CLI commands, no user input, developer tool context
 
-		const { status, passed, failed, errors = 0, skipped, total, testsFound } = parseTestCounts(result);
+		const {
+			status,
+			passed,
+			failed,
+			errors = 0,
+			skipped,
+			total,
+			testsFound,
+			resourceBudget: budgetEvidence,
+		} = parseTestCounts(result);
+		if (useFullSuite && status !== 'PASS') {
+			return {
+				success: false,
+				testsFound,
+				fullSuite: true,
+				resourceBudget: budgetEvidence,
+				duration: Date.now() - startTime,
+				passed,
+				failed,
+				skipped,
+				total,
+				message: 'Full suite did not report a passing terminal aggregate',
+			};
+		}
 		const success = failed === 0 && errors === 0 && (status === undefined || status === 'PASS');
 
 		// B2 (N1): a bun run that executes 0 tests must NEVER report PASS — that
@@ -647,64 +802,16 @@ async function runAllTests(exec = execFileSync, rootDir = process.cwd()) {
 			success,
 			testsFound: true,
 			fullSuite: useFullSuite,
+			resourceBudget: budgetEvidence,
 			duration: Date.now() - startTime,
 			passed,
 			failed,
 			skipped,
 			total,
-			message: success
-				? `All ${total} tests passed`
-				: `${failed + errors}/${total} tests failed`,
+			message: success ? `All ${total} tests passed` : `${failed + errors}/${total} tests failed`,
 		};
 	} catch (error) {
-		// Check for timeout
-		if (error.code === 'ETIMEDOUT' || (error.killed && error.signal === 'SIGTERM')) {
-			return {
-				success: false,
-				fullSuite: useFullSuite,
-				duration: Date.now() - startTime,
-				passed: 0,
-				failed: 0,
-				total: 0,
-				message: validationTimeoutMessage('Test execution', execOptions.timeout),
-			};
-		}
-
-		// Test runner absent — say so explicitly (do NOT silently pass).
-		if (isCommandNotFound(error)) {
-			return {
-				success: true,
-				skipped: true,
-				testsFound: false,
-				fullSuite: useFullSuite,
-				duration: Date.now() - startTime,
-				passed: 0,
-				failed: 0,
-				total: 0,
-				message: 'Tests skipped: test runner not found. Install Node.js and Bun to run tests.',
-			};
-		}
-
-		// Parse test failures from output
-		const output = error.stdout || error.message;
-		const counts = parseTestCounts(output);
-		const passed = counts.passed;
-		// bun exited non-zero: if the output shows no explicit failure count, treat
-		// it as at least one failure rather than swallowing the non-zero exit.
-		const failed = counts.failed > 0 ? counts.failed : Math.max(1, counts.errors || 0);
-		const total = counts.total > 0 ? counts.total : passed + failed + counts.skipped;
-
-		return {
-			success: false,
-			testsFound: counts.testsFound,
-			fullSuite: useFullSuite,
-			duration: Date.now() - startTime,
-			passed,
-			failed,
-			total,
-			message: `${failed}/${total} tests failed`,
-			output,
-		};
+		return testExecutionErrorResult(error, startTime, rootDir, useFullSuite, execOptions.timeout);
 	}
 }
 
@@ -730,16 +837,27 @@ async function runAllTests(exec = execFileSync, rootDir = process.cwd()) {
  * console.log(result.summary);
  */
 async function executeValidate(options = {}) { // NOSONAR S3776
-	const { skip = [], continueOnError = true, rootDir = process.cwd() } = options || {};
+	const {
+		skip = [],
+		continueOnError = true,
+		rootDir = process.cwd(),
+		resourceBudget = null,
+	} = options || {};
+	const startTime = Date.now();
+	if (!isValidationRootAvailable(rootDir)) {
+		const checks = { tests: unavailableValidationRootResult(startTime) };
+		const result = buildResult(checks, [CHECK_TYPES.TESTS], [], startTime);
+		result.validationReceipt = false;
+		return result;
+	}
 	const receiptApi = options?.validationReceipt || validationReceipt;
+	const testRunner = options?.runAllTests || runAllTests;
 	const validationSnapshot = receiptApi.beginValidation(rootDir);
 	const receiptSnapshot = skip.length === 0 ? validationSnapshot : null;
 
 	const checks = {};
 	const failedChecks = [];
 	const errors = [];
-	const startTime = Date.now();
-
 	// 0. Conflict markers
 	if (!skip.includes(CHECK_TYPES.CONFLICT_MARKERS)) {
 		try {
@@ -807,7 +925,7 @@ async function executeValidate(options = {}) { // NOSONAR S3776
 	// 4. Tests
 	if (!skip.includes(CHECK_TYPES.TESTS)) {
 		try {
-			checks.tests = await runAllTests(execFileSync, rootDir);
+			checks.tests = await testRunner(execFileSync, rootDir, resourceBudget);
 			if (!checks.tests.success && checks.tests.skipped !== true) {
 				failedChecks.push(CHECK_TYPES.TESTS);
 				if (!continueOnError) {
@@ -897,21 +1015,43 @@ function executeDebugMode({ fixAttempts = 0, claim } = {}) {
 module.exports = {
 	name: 'validate',
 	description: 'Run validation checks across type, lint, security, and tests',
-	handler: async () => {
-		const result = await executeValidate();
-		if (!result.success) {
-			return result;
+	usage: 'forge validate [--shards N]',
+	flags: {
+		'--shards N': 'Set the full-suite resource budget',
+	},
+	handler: async (args = [], _flags = {}, projectRoot = process.cwd(), deps = {}) => {
+		let resourceBudget;
+		try {
+			resourceBudget = parseResourceBudget(args);
+		} catch (error) {
+			return { success: false, error: error.message };
 		}
-
+		const result = await (deps.executeValidate || executeValidate)({
+			rootDir: projectRoot,
+			resourceBudget,
+		});
+		const errorParts = Array.isArray(result.errors) ? result.errors.filter(Boolean) : [];
+		for (const check of Object.values(result.checks || {})) {
+			if (check?.success !== false || check.skipped === true || !check.message) continue;
+			if (!errorParts.some(error => error.endsWith(check.message))) errorParts.push(check.message);
+		}
+		const budget = result.checks?.tests?.resourceBudget;
+		const budgetOutput = Number.isInteger(budget?.effective)
+			? `Full suite resource budget: requested=${budget.requested ?? 'default'} effective=${budget.effective}`
+			: null;
+		const output = [result.success ? result.summary : null, budgetOutput].filter(Boolean).join('\n');
+		const error = result.error || result.message || errorParts.join('; ') || result.summary;
 		return {
 			...result,
-			output: result.summary,
+			...(output ? { output } : {}),
+			...(!result.success && error ? { error } : {}),
 		};
 	},
 	runTypeCheck,
 	runLint,
 	runSecurityScan,
 	runAllTests,
+	parseResourceBudget,
 	parseTestCounts,
 	scanForConflictMarkers,
 	executeValidate,

package/lib/gh-proxy.js

@@ -0,0 +1,309 @@
+'use strict';
+
+const { execFileSync, spawnSync: nativeSpawnSync } = require('node:child_process');
+const { createGithubTokenContext, readGithubAuto } = require('./github-context');
+const {
+  commandName, exitCode, isForgeProxy, isLocalGhInvocation, resolveRealGh, runNativeGh, shortOptionValue,
+  withoutProxyMarker,
+} = require('./native-gh');
+const { assertGithubRouterCloneRegistered } = require('./github-router');
+const { resolveLocalGithubTarget } = require('./commands/github');
+
+const COMMAND_VALUE_FLAGS = new Set(['--hostname', '--repo', '-R', '--jq', '--template']);
+const REPOSITORY_TARGET_POSITIONS = new Map([
+  ['extension install', 2],
+  ['issue transfer', 3],
+  ['label clone', 2],
+  ...['archive', 'clone', 'create', 'delete', 'edit', 'fork', 'new', 'set-default', 'sync', 'unarchive', 'view']
+    .map(verb => [`repo ${verb}`, 2]),
+]);
+const RESOURCE_TARGET_POSITIONS = new Map([
+  ['co', 1],
+  ['api', 1],
+  ['agent-task view', 2],
+  ...['clone', 'delete', 'edit', 'rename', 'view'].map(verb => [`gist ${verb}`, 2]),
+]);
+
+function capturedRunner(realGh) {
+  return (command, args, options = {}) => {
+    if (command !== 'gh') return execFileSync(command, args, options);
+    const result = nativeSpawnSync(realGh, args, options);
+    if (result.error) throw result.error;
+    if (result.status !== 0) {
+      const error = new Error(`GitHub CLI exited with status ${result.status}.`);
+      Object.assign(error, { status: result.status, stdout: result.stdout, stderr: result.stderr });
+      throw error;
+    }
+    return result.stdout || '';
+  };
+}
+
+function environmentValue(environment, name, platform) {
+  if (platform !== 'win32') return environment[name] || undefined;
+  const key = Object.keys(environment).find(candidate => candidate.toUpperCase() === name);
+  return key ? (environment[key] || undefined) : undefined;
+}
+
+function resourceHostname(value) {
+  const text = String(value || '');
+  if (text.includes('://')) {
+    const url = new URL(text);
+    if (url.protocol !== 'https:' || url.port) throw new Error('Unsupported GitHub target URL.');
+    const hostname = url.hostname.toLowerCase();
+    return ['api.github.com', 'gist.github.com', 'uploads.github.com'].includes(hostname) ? 'github.com' : hostname;
+  }
+  return undefined;
+}
+
+function repositoryHostname(value) {
+  const text = String(value || '');
+  if (text.includes('://')) {
+    const url = new URL(text);
+    if (!['https:', 'ssh:'].includes(url.protocol) || (url.protocol === 'https:' && url.port)) {
+      throw new Error('Unsupported GitHub target URL.');
+    }
+    return url.hostname.toLowerCase();
+  }
+  const scpHost = /^(?:[^@\s/:]+@)?([^:\s/]+):[^/\s]+\/[^/\s]+$/.exec(text);
+  if (scpHost) return scpHost[1].toLowerCase();
+  if (text.includes(':')) throw new Error('Unknown GitHub repository destination.');
+  const parts = text.split('/');
+  if (parts.length === 2 && parts.every(Boolean)) return undefined;
+  if (parts.length === 3 && parts.every(Boolean)) return parts[0].toLowerCase();
+  throw new Error('Unknown GitHub repository destination.');
+}
+
+function commandPath(args) {
+  const result = [];
+  let started = false;
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (COMMAND_VALUE_FLAGS.has(arg)) { index += 1; continue; }
+    if (/^(?:--hostname|--repo|--jq|--template)=/.test(arg) || /^-R=?\S+/.test(arg)) continue;
+    if (arg === '--' || (started && arg.startsWith('-'))) break;
+    if (arg.startsWith('-')) continue;
+    started = true;
+    result.push(arg);
+  }
+  return result;
+}
+
+function flagTakesValue(help, flag) {
+  const matches = new Set();
+  for (const line of String(help || '').split(/\r?\n/)) {
+    const [declaration, description] = line.trim().split(/\s{2,}/, 2);
+    if (!description) continue;
+    const tokens = declaration.replaceAll(',', '').split(/\s+/);
+    if (tokens.includes(flag)) matches.add(tokens.some(token => !token.startsWith('-')));
+  }
+  return matches.size === 1 ? [...matches][0] : null;
+}
+
+function optionValueResolver(args, realGh, baseEnv, options) {
+  let help;
+  const readHelp = () => {
+    if (help !== undefined) return help;
+    if (options.readCommandHelp) help = String(options.readCommandHelp(commandPath(args)) || '');
+    else {
+      const pathParts = commandPath(args);
+      for (let length = pathParts.length; length > 0; length -= 1) {
+        try {
+          help = String((options.execFileSync || execFileSync)(realGh, ['help', ...pathParts.slice(0, length)], {
+            encoding: 'utf8', env: baseEnv, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, timeout: 3000,
+          }) || '');
+          break;
+        } catch { /* try the parent command */ }
+      }
+    }
+    return help || '';
+  };
+  const resolve = flag => flagTakesValue(readHelp(), flag);
+  resolve.help = readHelp;
+  return resolve;
+}
+
+function isOptionValue(args, index, resolveOptionValue) {
+  const previous = args[index - 1];
+  if (!previous?.startsWith('-') || previous.includes('=')) return false;
+  if (COMMAND_VALUE_FLAGS.has(previous)) return true;
+  if (!previous.startsWith('--') && previous.length > 2) {
+    const option = shortOptionValue(previous, resolveOptionValue);
+    return Boolean(option && !option.attached);
+  }
+  const takesValue = resolveOptionValue(previous);
+  if (typeof takesValue !== 'boolean') throw new Error(`Unable to determine GitHub CLI option arity for ${previous}.`);
+  return takesValue;
+}
+
+function positionalArguments(args, resolveOptionValue) {
+  const delimiter = args.indexOf('--');
+  return args.filter((arg, index) => arg !== '--' && ((delimiter >= 0 && index > delimiter)
+    || (!arg.startsWith('-') && !isOptionValue(args, index, resolveOptionValue))));
+}
+
+function namedUrlPositions(help, positionalCount) {
+  const positions = new Set();
+  for (const line of String(help || '').split(/\r?\n/)) {
+    const usage = /^\s*(?:Usage:\s*)?gh\s+(.+)$/i.exec(line)?.[1];
+    if (!usage) continue;
+    const tokens = usage.match(/\[[^\]]*\]|\{[^}]*\}|<[^>]+>|\S+/g) || [];
+    let position = tokens.findIndex(token => /^[\[{<]/.test(token));
+    if (position < 0) continue;
+    for (const token of tokens.slice(position)) {
+      const placeholders = [...token.matchAll(/<([^>]+)>/g)].map(match => match[1]);
+      if (!placeholders.length) continue;
+      if (placeholders.some(name => /(?:^|[-_])urls?$/i.test(name))) {
+        positions.add(position);
+        if (placeholders.some(name => /(?:^|[-_])urls$/i.test(name))) {
+          for (let index = position + 1; index < positionalCount; index += 1) positions.add(index);
+        }
+      }
+      position += 1;
+    }
+  }
+  return positions;
+}
+
+function positionalResourceHosts(args, command, resolveOptionValue, excludedPosition) {
+  if (!args.some(arg => arg.includes('://'))) return [];
+  const route = command.slice(0, 2).join(' ');
+  const position = RESOURCE_TARGET_POSITIONS.get(route) ?? RESOURCE_TARGET_POSITIONS.get(command[0]);
+  const help = position === undefined ? resolveOptionValue.help() : '';
+  if (position === undefined && !help.trim()) throw new Error('Unable to classify the GitHub CLI URL argument.');
+  const positions = position === undefined ? namedUrlPositions(help, args.length) : new Set([position]);
+  if (positions.size === 0) return [];
+  const values = positionalArguments(args, resolveOptionValue);
+  return [...positions].filter(index => index !== excludedPosition)
+    .map(index => resourceHostname(values[index])).filter(Boolean);
+}
+
+function repositoryFromShortOptions(arg, args, index, resolveOptionValue) {
+  if (!arg.startsWith('-') || arg.startsWith('--') || !arg.slice(1).includes('R')) return null;
+  const option = shortOptionValue(arg, resolveOptionValue);
+  if (option?.flag !== '-R') return null;
+  const next = args[index + 1];
+  return option.attached || (next && !next.startsWith('-') ? next : '');
+}
+
+function argumentDestinations(args, realGh, baseEnv, options) {
+  const hosts = [];
+  let explicit = false;
+  let remoteName;
+  const resolveOptionValue = optionValueResolver(args, realGh, baseEnv, options);
+  const command = commandPath(args);
+  const commandRoute = command.slice(0, 2).join(' ');
+  const delimiter = args.indexOf('--');
+  const end = delimiter < 0 ? args.length : delimiter;
+  for (let index = 0; index < end; index += 1) {
+    const arg = args[index];
+    let value;
+    if (arg === '--hostname' || arg === '--repo' || arg === '-R'
+      || (commandRoute === 'repo create' && (arg === '--template' || arg === '-p'))) {
+      if (arg !== '--hostname') explicit = true;
+      value = args[++index];
+      if (!value || value.startsWith('-')) throw new Error(`Missing value for ${arg}.`);
+    } else if (arg.startsWith('--hostname=')) {
+      value = arg.slice('--hostname='.length);
+      if (!value) throw new Error('Missing value for --hostname.');
+    } else if (arg.startsWith('--repo=')) {
+      explicit = true;
+      value = arg.slice('--repo='.length);
+      if (!value) throw new Error('Missing value for --repo.');
+    } else if (commandRoute === 'repo create' && arg.startsWith('--template=')) {
+      explicit = true;
+      value = arg.slice('--template='.length);
+      if (!value) throw new Error('Missing value for --template.');
+    } else if (commandRoute === 'repo create' && /^-p=?\S+/.test(arg)) {
+      explicit = true;
+      value = arg.slice(2).replace(/^=/, '');
+    } else if (/^-R=?\S+/.test(arg)) {
+      explicit = true;
+      value = arg.slice(2).replace(/^=/, '');
+    } else {
+      value = repositoryFromShortOptions(arg, args, index, resolveOptionValue);
+      if (value === null) continue;
+      explicit = true;
+      if (!value) throw new Error('Missing value for -R.');
+    }
+    const host = arg.startsWith('--hostname') ? value.toLowerCase() : repositoryHostname(value);
+    if (host) hosts.push(host);
+  }
+
+  const repositoryPosition = REPOSITORY_TARGET_POSITIONS.get(commandRoute);
+  if (repositoryPosition !== undefined) {
+    const target = positionalArguments(args, resolveOptionValue)[repositoryPosition];
+    if (target) {
+      explicit = true;
+      const localName = ['repo create', 'repo new'].includes(commandRoute) && !/[/:]/.test(target);
+      const localRemote = commandRoute === 'repo set-default' && !/[/:]/.test(target);
+      if (localRemote) remoteName = target;
+      const host = localName || localRemote ? undefined : repositoryHostname(target);
+      if (host) hosts.push(host);
+    }
+  }
+  const resourceHosts = positionalResourceHosts(args, command, resolveOptionValue, repositoryPosition);
+  if (resourceHosts.length) { explicit = true; hosts.push(...resourceHosts); }
+  return { explicit, hosts, remoteName };
+}
+
+function selectedTarget(args, projectRoot, baseEnv, options, platform) {
+  const destinations = argumentDestinations(args, options.realGh, baseEnv, options);
+  const hosts = destinations.hosts;
+  const environmentHost = environmentValue(baseEnv, 'GH_HOST', platform);
+  const environmentRepository = environmentValue(baseEnv, 'GH_REPO', platform);
+  if (environmentHost) hosts.push(environmentHost.toLowerCase());
+  const repositoryHost = environmentRepository ? repositoryHostname(environmentRepository) : undefined;
+  if (repositoryHost) hosts.push(repositoryHost);
+
+  let local;
+  if (destinations.remoteName || (!destinations.explicit && !environmentRepository)) {
+    local = resolveLocalGithubTarget(projectRoot, options, destinations.remoteName);
+    if (!local) throw new Error('Unable to resolve the local GitHub repository host.');
+    hosts.push(local.hostname.toLowerCase());
+  }
+  if (hosts.length === 0) hosts.push('github.com');
+  const unique = [...new Set(hosts)];
+  if (unique.length !== 1 || unique[0] !== 'github.com') throw new Error('Automatic routing supports github.com only.');
+  return { local, environmentRepository };
+}
+
+function runGhProxy(args, projectRoot = process.cwd(), options = {}) {
+  const writeError = options.writeError || (value => process.stderr.write(value));
+  const realGh = (options.resolveExecutable || resolveRealGh)(options);
+  if (!realGh) {
+    writeError('GitHub CLI executable not found outside the Forge proxy.\n');
+    return 127;
+  }
+  const baseEnv = withoutProxyMarker(options.baseEnv || process.env);
+  const resolveOptionValue = optionValueResolver(args, realGh, baseEnv, options);
+  if (isLocalGhInvocation(args, resolveOptionValue)) {
+    return runNativeGh(args, projectRoot, { ...options, resolveExecutable: () => realGh });
+  }
+  const spawnSync = options.spawnSync || nativeSpawnSync;
+  const passthrough = () => exitCode(spawnSync(realGh, args, {
+    cwd: projectRoot, env: baseEnv, stdio: 'inherit', shell: false,
+  }));
+  try {
+    const automatic = (options.readAuto || readGithubAuto)(projectRoot, options);
+    if (automatic === false) return passthrough();
+    if (automatic !== true) throw new Error('Invalid automatic routing state.');
+    (options.assertRegistered || assertGithubRouterCloneRegistered)(projectRoot, options);
+    const platform = options.platform || process.platform;
+    const { local, environmentRepository } = selectedTarget(args, projectRoot, baseEnv, { ...options, realGh }, platform);
+    const childRepository = environmentRepository || (local ? `github.com/${local.repository}` : undefined);
+    const childRunner = (command, childArgs, childOptions) => spawnSync(command, childArgs, {
+      ...childOptions,
+      ...(childRepository ? { env: { ...childOptions.env, GH_REPO: childRepository } } : {}),
+    });
+    const context = (options.createContext || createGithubTokenContext)(projectRoot, {
+      ...options, baseEnv, runner: options.runner || capturedRunner(realGh), childRunner,
+    });
+    if (!context.bound) throw new Error('Automatic routing requires a clone account binding.');
+    return exitCode(context.runChild(realGh, args, { cwd: projectRoot, stdio: 'inherit', shell: false }));
+  } catch {
+    writeError('Forge could not select this clone\'s GitHub account. Run forge github status.\n');
+    return 1;
+  }
+}
+
+module.exports = { commandName, isForgeProxy, resolveRealGh, runGhProxy };