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

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 };

package/lib/github-context.js

@@ -1,12 +1,16 @@
 'use strict';
 
 const { execFileSync } = require('node:child_process');
+const { isManagedCredentialHelperValue, isOwnedCredentialHelperValue, isUsableCredentialHelperValue } = require('./github-router');
+const { resolveRealGh } = require('./native-gh');
 
 const ACCOUNT_KEY = 'github.account';
+const AUTO_KEY = 'github.auto';
+const CREDENTIAL_HELPER_KEY = 'credential.https://github.com.helper';
 const HOST = 'github.com';
 const LOGIN_RE = /^(?=.{1,39}$)[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/;
-const GITHUB_ENV_NAMES = new Set(['gh_token', 'github_token', 'gh_host', 'gh_repo']);
-const GITHUB_SECRET_ENV_NAMES = new Set(['gh_token', 'github_token']);
+const GITHUB_ENV_NAMES = new Set(['gh_token', 'github_token', 'gh_enterprise_token', 'github_enterprise_token', 'gh_host', 'gh_repo']);
+const GITHUB_SECRET_ENV_NAMES = new Set(['gh_token', 'github_token', 'gh_enterprise_token', 'github_enterprise_token']);
 
 class GithubContextError extends Error {
   constructor(code, message) {
@@ -29,16 +33,17 @@ function safeLogin(login) {
 }
 
 function runnerFor(options) {
-  return options.runner || options._runner || options._exec || options.execFileSync || defaultRunner;
-}
-
-function defaultRunner(command, args, options = {}) {
-  return execFileSync(command, args, {
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-    windowsHide: true,
-    ...options,
-  });
+  const injected = options.runner || options._runner || options._exec;
+  if (injected) return injected;
+  const execute = options.execFileSync || execFileSync;
+  const resolve = options.resolveRealGh || resolveRealGh;
+  return (command, args, runOptions = {}) => {
+    const executable = command === 'gh' ? resolve({ env: runOptions.env }) : command;
+    if (!executable) throw Object.assign(new Error('GitHub CLI was not found.'), { code: 'ENOENT' });
+    return execute(executable, args, {
+      encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, ...runOptions,
+    });
+  };
 }
 
 function errorText(error) {
@@ -86,35 +91,50 @@ function gitConfig(projectRoot, args, options, absentIsOkay = false) {
       windowsHide: true,
     });
   } catch (error) {
-    if (absentIsOkay && (error?.status === 1 || /key does not contain|not found|no such key/i.test(errorText(error)))) {
-      return '';
+    if (absentIsOkay && (error?.status === 1 || /key does not contain|not found|no such key|not a git repository|--local can only be used/i.test(errorText(error)))) {
+      return null;
     }
     throw safeCommandFailure('GIT_CONFIG_FAILED', 'Unable to read this clone-local GitHub account binding.');
   }
 }
 
-function readGithubAccount(projectRoot, options = {}) {
-  const output = gitConfig(projectRoot, ['--get', ACCOUNT_KEY], options, true);
-  const value = output == null ? '' : output.toString().trim();
-  return value || null;
+function readLocalValues(projectRoot, key, options = {}) {
+  const output = gitConfig(projectRoot, ['--get-all', key], options, true);
+  if (output == null) return [];
+  return output.toString().replace(/\r?\n$/, '').split(/\r?\n/);
 }
 
-function writeGithubAccount(projectRoot, login, options = {}) {
-  if (!validateGithubLogin(login)) {
-    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'GitHub login must be 1-39 letters, numbers, or internal hyphens.');
-  }
+function runGitConfig(projectRoot, args, options, message) {
   try {
-    runnerFor(options)('git', ['config', '--local', '--replace-all', ACCOUNT_KEY, login], {
+    return runnerFor(options)('git', ['config', '--local', ...args], {
       cwd: projectRoot,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
       windowsHide: true,
     });
-  } catch (_error) {
-    throw safeCommandFailure('GIT_CONFIG_FAILED', 'Unable to write the clone-local GitHub account binding.');
+  } catch {
+    throw safeCommandFailure('GIT_CONFIG_FAILED', message);
   }
 }
 
+function readGithubAccount(projectRoot, options = {}) {
+  const values = readLocalValues(projectRoot, ACCOUNT_KEY, options);
+  if (values.length === 0) return null;
+  if (values.length !== 1) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'The clone-local github.account value must be unique.');
+  }
+  const value = values[0].trim();
+  return value || null;
+}
+
+function writeGithubAccount(projectRoot, login, options = {}) {
+  if (!validateGithubLogin(login)) {
+    throw safeCommandFailure('INVALID_GITHUB_LOGIN', 'GitHub login must be 1-39 letters, numbers, or internal hyphens.');
+  }
+  runGitConfig(projectRoot, ['--replace-all', ACCOUNT_KEY, login], options,
+    'Unable to write the clone-local GitHub account binding.');
+}
+
 function unsetGithubAccount(projectRoot, options = {}) {
   try {
     runnerFor(options)('git', ['config', '--local', '--unset-all', ACCOUNT_KEY], {
@@ -129,6 +149,91 @@ function unsetGithubAccount(projectRoot, options = {}) {
   }
 }
 
+function readGithubAuto(projectRoot, options = {}) {
+  const values = readLocalValues(projectRoot, AUTO_KEY, options);
+  if (values.length === 0) return false;
+  if (values.length !== 1) return null;
+  const value = values[0].toLowerCase();
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  return null;
+}
+
+function ownsCredentialHelper(value, options) {
+  return (options.isOwnedCredentialHelper || isOwnedCredentialHelperValue)(value);
+}
+
+function hasGithubAutoCredentialHelper(projectRoot, options = {}) {
+  const helpers = readLocalValues(projectRoot, CREDENTIAL_HELPER_KEY, options);
+  return helpers.length === 2 && helpers[0] === ''
+    && (options.isOwnedCredentialHelper || isUsableCredentialHelperValue)(helpers[1], options);
+}
+
+function isForgeCredentialHelper(value, options) {
+  return ownsCredentialHelper(value, options)
+    || (options.isManagedCredentialHelper || isManagedCredentialHelperValue)(value, options);
+}
+
+function restoreLocalValues(projectRoot, snapshots, options) {
+  for (const [key, values] of snapshots) {
+    try {
+      unsetLocalKey(projectRoot, key, options);
+      for (const value of values) runnerFor(options)('git', ['config', '--local', '--add', key, value], { cwd: projectRoot, stdio: 'ignore' });
+    } catch { /* best effort rollback */ }
+  }
+}
+
+function unsetLocalKey(projectRoot, key, options) {
+  try {
+    runnerFor(options)('git', ['config', '--local', '--unset-all', key], {
+      cwd: projectRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true,
+    });
+  } catch (error) {
+    if (error?.status === 5 || error?.status === 1 || /key does not contain|not found|no such key/i.test(errorText(error))) return;
+    throw error;
+  }
+}
+
+function assertGithubAutoAvailable(projectRoot, options = {}) {
+  const helpers = readLocalValues(projectRoot, CREDENTIAL_HELPER_KEY, options);
+  const replaceable = helpers.length === 2 && helpers[0] === ''
+    && isForgeCredentialHelper(helpers[1], options);
+  if (helpers.length && !replaceable) {
+    throw safeCommandFailure('GIT_CREDENTIAL_HELPER_CONFLICT', 'A clone-local GitHub credential helper is already configured.');
+  }
+}
+
+function enableGithubAuto(projectRoot, options = {}) {
+  assertGithubAutoAvailable(projectRoot, options);
+  const helperValue = options.credentialHelperValue;
+  if (!ownsCredentialHelper(helperValue || '', options)) {
+    throw safeCommandFailure('GIT_CONFIG_FAILED', 'Forge did not provide a valid credential helper command.');
+  }
+  const previousHelpers = readLocalValues(projectRoot, CREDENTIAL_HELPER_KEY, options);
+  const previousAuto = readLocalValues(projectRoot, AUTO_KEY, options);
+  try {
+    runGitConfig(projectRoot, ['--replace-all', CREDENTIAL_HELPER_KEY, ''], options, 'Unable to enable automatic GitHub routing.');
+    runGitConfig(projectRoot, ['--add', CREDENTIAL_HELPER_KEY, helperValue], options, 'Unable to enable automatic GitHub routing.');
+    runGitConfig(projectRoot, ['--replace-all', AUTO_KEY, 'true'], options, 'Unable to enable automatic GitHub routing.');
+  } catch (error) {
+    restoreLocalValues(projectRoot, [[CREDENTIAL_HELPER_KEY, previousHelpers], [AUTO_KEY, previousAuto]], options);
+    throw error;
+  }
+}
+
+function disableGithubAuto(projectRoot, options = {}) {
+  const helpers = readLocalValues(projectRoot, CREDENTIAL_HELPER_KEY, options);
+  const previousAuto = readLocalValues(projectRoot, AUTO_KEY, options);
+  const owned = helpers.length === 2 && helpers[0] === '' && isForgeCredentialHelper(helpers[1], options);
+  const keys = [AUTO_KEY, ...(owned ? [CREDENTIAL_HELPER_KEY] : [])];
+  try {
+    for (const key of keys) unsetLocalKey(projectRoot, key, options);
+  } catch {
+    restoreLocalValues(projectRoot, [[AUTO_KEY, previousAuto], [CREDENTIAL_HELPER_KEY, helpers]], options);
+    throw safeCommandFailure('GIT_CONFIG_FAILED', 'Unable to disable automatic GitHub routing.');
+  }
+}
+
 function withoutGithubEnvironment(environment) {
   const result = {};
   for (const [key, value] of Object.entries(environment || {})) {
@@ -177,6 +282,20 @@ function retrieveGithubToken(login, options) {
   return token;
 }
 
+function createGithubTokenContext(projectRoot, options = {}) {
+  const account = (options.readAccount || readGithubAccount)(projectRoot, options);
+  if (!validateGithubLogin(account)) {
+    throw safeCommandFailure('GITHUB_NOT_AUTHENTICATED', 'No selected GitHub account is available.');
+  }
+  const baseEnv = { ...(options.baseEnv || options.env || process.env) };
+  const token = retrieveGithubToken(account, { ...options, baseEnv });
+  return createPublicContext(publicStatus('selected', account, null), token, baseEnv, options);
+}
+
+function writeGithubCredential(projectRoot, write, options = {}) {
+  createGithubTokenContext(projectRoot, options).writeCredential(write);
+}
+
 function loginFromOutput(output) {
   const text = output == null ? '' : output.toString().trim();
   if (!text) return null;
@@ -270,9 +389,16 @@ function createPublicContext(status, token, baseEnv, options) {
       throw safeGithubCommandFailure(error);
     }
   };
+  const writeCredential = (write) => {
+    if (status.state === 'unbound' || typeof write !== 'function') {
+      throw safeCommandFailure('GITHUB_NOT_AUTHENTICATED', 'No selected GitHub account is available.');
+    }
+    write(`username=${status.account}\npassword=${token}\n\n`);
+  };
   Object.defineProperties(context, {
     runChild: { value: runChild, enumerable: false },
     runGh: { value: runGh, enumerable: false },
+    writeCredential: { value: writeCredential, enumerable: false },
     getStatus: { value: () => ({ ...status }), enumerable: false },
   });
   return context;
@@ -296,12 +422,21 @@ function createGithubContext(projectRoot, options = {}) {
 
 module.exports = {
   ACCOUNT_KEY,
+  AUTO_KEY,
+  CREDENTIAL_HELPER_KEY,
   GithubContextError,
+  assertGithubAutoAvailable,
   createGithubContext,
+  createGithubTokenContext,
+  disableGithubAuto,
+  enableGithubAuto,
+  hasGithubAutoCredentialHelper,
   prepareGithubAccount,
   prepareGithubContext: createGithubContext,
   readGithubAccount,
+  readGithubAuto,
   resolveGithubLogin,
+  writeGithubCredential,
   unsetGithubAccount,
   validateGithubLogin,
   writeGithubAccount,

package/lib/github-credential.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const { readGithubAuto, writeGithubCredential } = require('./github-context');
+const { assertGithubRouterCloneRegistered } = require('./github-router');
+
+function parseRequest(input) {
+  if (typeof input !== 'string' || input.length > 64 * 1024) return null;
+  const request = Object.create(null);
+  for (const line of input.split(/\r?\n/)) {
+    if (!line) break;
+    const separator = line.indexOf('=');
+    if (separator < 1) return null;
+    request[line.slice(0, separator)] = line.slice(separator + 1);
+  }
+  return request;
+}
+
+function runCredentialHelper(operation, options = {}) {
+  if (!['get', 'store', 'erase'].includes(operation)) return 1;
+  if (operation !== 'get') return 0;
+  const request = parseRequest(options.input || '');
+  const host = request?.host?.toLowerCase();
+  if (request?.protocol !== 'https' || (host !== 'github.com' && host !== 'github.com:443')) return 0;
+  const projectRoot = options.projectRoot || process.cwd();
+  const write = options.write || (value => process.stdout.write(value));
+  const writeError = options.writeError || (value => process.stderr.write(value));
+  try {
+    const automatic = (options.readAuto || readGithubAuto)(projectRoot, options);
+    if (automatic === false) return 0;
+    if (automatic !== true) throw new Error('Automatic GitHub routing configuration is invalid.');
+    if (!options.createContext || options.assertRegistered) {
+      (options.assertRegistered || assertGithubRouterCloneRegistered)(projectRoot, options);
+    }
+    if (options.createContext) {
+      options.createContext(projectRoot, options).writeCredential(write);
+    } else {
+      writeGithubCredential(projectRoot, write, options);
+    }
+    return 0;
+  } catch {
+    write('quit=true\n\n');
+    writeError('Forge could not resolve this clone\'s GitHub account. Run forge github status.\n');
+    return 1;
+  }
+}
+
+module.exports = { parseRequest, runCredentialHelper };