@aifabrix/builder 2.58.0 → 2.60.0

package/lib/agent-kit/codex-app-server.js

@@ -0,0 +1,44 @@
+/** Discover and stop direct Codex app servers owned by the current user. */
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+function parseServerLine(line) {
+  const match = /^\s*(\d+)\s+(\d+)\s+(.+)$/.exec(line);
+  if (!match) return null;
+  const args = match[3];
+  if (!/(?:^|\s)(?:\S*\/)?codex(?:\s|$)/.test(args) ||
+      !/(?:^|\s)app-server\s+--listen(?:\s|$)/.test(args)) return null;
+  return { pid: Number(match[1]), parentPid: Number(match[2]) };
+}
+
+function listCodexAppServers(options = {}) {
+  if (typeof process.getuid !== 'function') return [];
+  const exec = options.execFileSync || execFileSync;
+  const output = exec('ps', ['-u', String(process.getuid()), '-ww', '-o', 'pid=,ppid=,args='], {
+    encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe']
+  });
+  const candidates = String(output).split('\n').map(parseServerLine).filter(Boolean);
+  const pids = new Set(candidates.map(server => server.pid));
+  return candidates.filter(server => !pids.has(server.parentPid)).map((server) => {
+    try {
+      const startTime = String(exec('ps', ['-p', String(server.pid), '-o', 'lstart='], {
+        encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe']
+      })).trim();
+      return startTime ? { pid: server.pid, startTime } : null;
+    } catch (error) {
+      if (error.status === 1) return null;
+      throw error;
+    }
+  }).filter(Boolean);
+}
+
+function stopCodexAppServer(server, options = {}) {
+  const current = listCodexAppServers(options)
+    .find(item => item.pid === server.pid && item.startTime === server.startTime);
+  if (!current) throw new Error('Codex app server changed or exited. Run agent-kit list and retry.');
+  (options.kill || process.kill)(current.pid, 'SIGTERM');
+  return { command: 'kill', kind: 'codex-app-server', pid: current.pid, stopped: true };
+}
+
+module.exports = { parseServerLine, listCodexAppServers, stopCodexAppServer };

package/lib/agent-kit/git-identity.js

@@ -0,0 +1,180 @@
+/**
+ * Git commit identity for onboarding and Agent Kit GitHub work.
+ *
+ * Resolution order:
+ *   1. Existing `git config` — never rewritten, because it is the user's own setting.
+ *   2. The AI Fabrix login token's claims, offered as editable defaults.
+ *   3. The prompt answer, written to git config.
+ *
+ * The GitHub token is deliberately not used for the address: `gh api user` returns null whenever
+ * the account keeps its email private, and reading `user/emails` would demand the broader `user`
+ * scope for a value the login token already holds.
+ *
+ * @fileoverview Resolve and persist git user.name / user.email
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { execFileSync } = require('child_process');
+const logger = require('../utils/logger');
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+/**
+ * @param {Function} exec - execFileSync
+ * @param {string} key - Config key
+ * @param {boolean} global - Read the global scope only
+ * @returns {string} Trimmed value or ''
+ */
+function readConfig(exec, key, global) {
+  try {
+    const args = global ? ['config', '--global', '--get', key] : ['config', '--get', key];
+    return String(exec('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })).trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Current identity, preferring any effective value (local or global) over none.
+ * @param {Object} [options] - `execFileSync`
+ * @returns {{ name: string, email: string, complete: boolean }}
+ */
+function readGitIdentity(options = {}) {
+  const exec = options.execFileSync || execFileSync;
+  const name = readConfig(exec, 'user.name', false);
+  const email = readConfig(exec, 'user.email', false);
+  return { name, email, complete: Boolean(name && email) };
+}
+
+function decodeJwtClaims(token) {
+  const raw = String(token || '');
+  const parts = raw.split('.');
+  if (parts.length < 2) return null;
+  try {
+    return JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Name and email from the AI Fabrix login token, used as prompt defaults.
+ * @param {Object} [options] - `config` and `controller` overrides for tests
+ * @returns {Promise<{ name: string, email: string }>} Empty strings when unavailable
+ */
+async function identityFromLoginToken(options = {}) {
+  const config = options.config || require('../core/config');
+  try {
+    const controller = options.controller || (await config.getControllerUrl());
+    if (!controller) return { name: '', email: '' };
+    const entry = await config.getDeviceToken(controller);
+    const claims = decodeJwtClaims(entry && (entry.token || entry.accessToken));
+    if (!claims) return { name: '', email: '' };
+    return {
+      name: String(claims.name || '').trim(),
+      email: String(claims.email || claims.preferred_username || '').trim()
+    };
+  } catch {
+    return { name: '', email: '' };
+  }
+}
+
+/**
+ * @param {Object} [options] - `config`
+ * @returns {Promise<string>} adminEmail from config.yaml, or ''
+ */
+async function emailFromConfig(options = {}) {
+  const config = options.config || require('../core/config');
+  try {
+    const cfg = await config.getConfig();
+    return String((cfg && cfg.adminEmail) || '').trim();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * @param {string} value - Candidate address
+ * @returns {boolean|string} true, or the reason it is rejected
+ */
+function validateEmail(value) {
+  return EMAIL_RE.test(String(value || '').trim()) || 'Enter an email address, for example name@example.com';
+}
+
+function validateName(value) {
+  return String(value || '').trim().length > 0 || 'Enter the name to record on commits';
+}
+
+async function promptIdentity(defaults, deps) {
+  const inquirer = deps.inquirer || require('inquirer');
+  return inquirer.prompt([
+    {
+      type: 'input',
+      name: 'name',
+      message: 'Name for git commits',
+      default: defaults.name || undefined,
+      validate: validateName
+    },
+    {
+      type: 'input',
+      name: 'email',
+      message: 'Email for git commits',
+      default: defaults.email || undefined,
+      validate: validateEmail
+    }
+  ]);
+}
+
+function writeGitIdentity(identity, options) {
+  const exec = options.execFileSync || execFileSync;
+  exec('git', ['config', '--global', 'user.name', identity.name], { stdio: 'ignore' });
+  exec('git', ['config', '--global', 'user.email', identity.email], { stdio: 'ignore' });
+}
+
+function missingIdentityError(defaults) {
+  const name = defaults.name || 'Your Name';
+  const email = defaults.email || 'you@example.com';
+  return new Error(
+    'Git commit identity is not configured. Run:\n' +
+    `  git config --global user.name ${JSON.stringify(name)}\n` +
+    `  git config --global user.email ${email}`
+  );
+}
+
+/**
+ * Ensures git has a commit identity, asking only when one is missing.
+ * @param {Object} [options] - `interactive`, `execFileSync`, `inquirer`, `config`
+ * @returns {Promise<{ name: string, email: string, source: 'git'|'prompt' }>}
+ */
+async function ensureGitIdentity(options = {}) {
+  const current = readGitIdentity(options);
+  if (current.complete) {
+    return { name: current.name, email: current.email, source: 'git' };
+  }
+  const token = await identityFromLoginToken(options);
+  const defaults = {
+    name: current.name || token.name,
+    email: current.email || token.email || (await emailFromConfig(options))
+  };
+  if (!options.interactive) {
+    throw missingIdentityError(defaults);
+  }
+  logger.log('Git commit identity is not set. Defaults come from your AI Fabrix login; edit if needed.');
+  const answers = await promptIdentity(defaults, options);
+  const identity = { name: String(answers.name).trim(), email: String(answers.email).trim() };
+  writeGitIdentity(identity, options);
+  logger.log(`Git identity set to ${identity.name} <${identity.email}>`);
+  return { ...identity, source: 'prompt' };
+}
+
+module.exports = {
+  readGitIdentity,
+  identityFromLoginToken,
+  emailFromConfig,
+  ensureGitIdentity,
+  validateEmail,
+  validateName
+};

package/lib/agent-kit/init.js

@@ -122,8 +122,7 @@ function runInit(options) {
   const cwd = options.cwd || process.cwd();
   const dryRun = Boolean(options.dryRun);
   const scm = normalizeScm(options.scm);
-  const interactive =
-    typeof options.interactive === 'boolean' ? options.interactive : Boolean(process.stdout.isTTY);
+  const interactive = typeof options.interactive === 'boolean' ? options.interactive : Boolean(process.stdout.isTTY);
   const { targetAbs, workspaceName } = resolveWorkspaceTarget(options.nameOrPath, cwd);
   assertSafeTarget(targetAbs, Boolean(options.force));
   assertRemoteFlags(options, interactive);
@@ -160,15 +159,7 @@ function runInit(options) {
 
   const remote = remotePhase({ options, targetAbs, workspaceName, dryRun, phases });
 
-  return buildInitReport({
-    dryRun,
-    targetAbs,
-    workspaceName,
-    scm,
-    kit,
-    remote,
-    phases
-  });
+  return buildInitReport({ dryRun, targetAbs, workspaceName, scm, kit, remote, phases });
 }
 
 /**
@@ -258,8 +249,7 @@ function buildInitReport(p) {
 function runRemoteCreate(options) {
   const cwd = options.cwd || process.cwd();
   const dryRun = Boolean(options.dryRun);
-  const interactive =
-    typeof options.interactive === 'boolean' ? options.interactive : Boolean(process.stdout.isTTY);
+  const interactive = typeof options.interactive === 'boolean' ? options.interactive : Boolean(process.stdout.isTTY);
   const targetAbs = path.resolve(cwd);
   if (isUnsafeRoot(targetAbs)) {
     throw new Error(
@@ -285,10 +275,7 @@ function runRemoteCreate(options) {
     throw new Error('Non-interactive remote create requires --org <owner>.');
   }
   checkRemoteAuth(options);
-  const commit = ensureInitialCommit(targetAbs, {
-    dryRun,
-    execFileSync: options.execFileSync
-  });
+  const commit = ensureInitialCommit(targetAbs, { dryRun, execFileSync: options.execFileSync });
   const name = options.name || path.basename(targetAbs);
   const remote = createGithubRemote({
     name,

package/lib/agent-kit/session-report.js

@@ -41,17 +41,22 @@ function formatSessionList(report) {
   const lines = [sectionTitle(`Tmux sessions — ${sessions.length} active:`), ''];
   if (sessions.length === 0) {
     lines.push(metadata('  No active tmux sessions.'));
-    return lines.join('\n');
+  } else {
+    const widths = columnWidths(sessions);
+    const header = `${pad('Name', widths.name)}${pad('Status', widths.status)}Windows`;
+    lines.push(metadata(header));
+    lines.push(metadata('-'.repeat(widths.name + widths.status + widths.windows)));
+    sessions.forEach((session) => {
+      const status = session.attached ? 'attached' : 'detached';
+      lines.push(`${pad(session.name, widths.name)}${pad(status, widths.status)}${session.windows}`);
+    });
+  }
+  const servers = Array.isArray(report.codexServers) ? report.codexServers : [];
+  if (servers.length) {
+    lines.push('', sectionTitle(`Codex app servers — ${servers.length} active:`), '');
+    lines.push(metadata('  Started by Codex clients, independently of af onboarding.'));
+    servers.forEach(server => lines.push(`  PID ${server.pid}  ${server.startTime}`));
   }
-
-  const widths = columnWidths(sessions);
-  const header = `${pad('Name', widths.name)}${pad('Status', widths.status)}Windows`;
-  lines.push(metadata(header));
-  lines.push(metadata('-'.repeat(widths.name + widths.status + widths.windows)));
-  sessions.forEach((session) => {
-    const status = session.attached ? 'attached' : 'detached';
-    lines.push(`${pad(session.name, widths.name)}${pad(status, widths.status)}${session.windows}`);
-  });
   return lines.join('\n');
 }
 

package/lib/agent-kit/setup-auth.js

@@ -0,0 +1,131 @@
+/** Reuse Controller device login and delegate provider login to official CLIs. */
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const { spawnSync } = require('child_process');
+const config = require('../core/config');
+const paths = require('../utils/paths');
+const { checkDeviceToken } = require('../commands/auth-status');
+const { handleDeviceCodeLogin } = require('../commands/login-device');
+const { capture, checked, interactive, available } = require('./setup-process');
+const { assertDirectory } = require('./setup-context');
+const logger = require('../utils/logger');
+
+const PROVIDERS = {
+  codex: { package: '@openai/codex', status: ['login', 'status'], login: ['login', '--device-auth'] },
+  claude: { package: '@anthropic-ai/claude-code', status: ['auth', 'status'], login: ['auth', 'login'] }
+};
+
+async function ensureController(context) {
+  const environment = await config.getCurrentEnvironment();
+  let auth;
+  try {
+    auth = await checkDeviceToken(context.controller);
+  } catch {
+    auth = null;
+  }
+  if (!auth || !auth.authenticated) {
+    await handleDeviceCodeLogin(context.controller, environment, false, undefined, {
+      compact: true, exitOnFailure: false
+    });
+    auth = await checkDeviceToken(context.controller);
+  }
+  if (!auth || !auth.authenticated) {
+    throw new Error('Controller authentication could not be verified. Run aifabrix login, then retry.');
+  }
+  await config.setControllerUrl(context.controller);
+  return environment;
+}
+
+function ensureGithubLogin(options) {
+  try {
+    capture('gh', ['auth', 'status', '--hostname', 'github.com'], options);
+    return;
+  } catch {
+    const loginOptions = options.managed
+      ? { ...options, env: { ...process.env, ...options.env, GH_BROWSER: 'true' } } : options;
+    if (options.managed) {
+      logger.log('GitHub sign-in: open https://github.com/login/device on your computer and enter the code shown below.');
+    }
+    interactive('gh', ['auth', 'login', '--hostname', 'github.com', '--git-protocol', 'https', '--web'],
+      'GitHub login did not complete. Open https://github.com/login/device on your computer, then retry.', loginOptions);
+  }
+  checked('gh', ['auth', 'status', '--hostname', 'github.com'], 'GitHub authentication could not be verified.', options);
+}
+
+function providerEnvironment(options) {
+  const prefix = path.join(paths.getAifabrixSystemDir(), 'agent-tools');
+  const env = { ...process.env, ...options.env };
+  const localBin = path.join(options.homedir || os.homedir(), '.local', 'bin');
+  env.PATH = [path.join(prefix, 'bin'), localBin, env.PATH || ''].join(path.delimiter);
+  return { ...options, env, prefix };
+}
+
+function installClaudeNative(runtime) {
+  if (!available('curl', runtime) || !available('bash', runtime)) {
+    throw new Error('Install curl and bash to install Claude Code, then retry.');
+  }
+  logger.log('Installing Claude Code for the current user...');
+  const script = checked('curl', ['-fsSL', 'https://claude.ai/install.sh'],
+    'Could not download the Claude Code installer. Check network access, then retry.', runtime);
+  const result = (runtime.spawnSync || spawnSync)('bash', ['-s', 'stable'], {
+    cwd: runtime.cwd, env: runtime.env, input: script, encoding: 'utf8',
+    stdio: ['pipe', 'inherit', 'inherit']
+  });
+  if (!result || result.error || result.signal || result.status !== 0) {
+    throw new Error('Could not install Claude Code. Check user-directory permissions, then retry.');
+  }
+}
+
+function exposeManagedProvider(binary, code, options = {}) {
+  const localDir = path.join(options.homedir || os.homedir(), '.local');
+  const binDir = path.join(localDir, 'bin');
+  assertDirectory(localDir);
+  fs.mkdirSync(localDir, { recursive: true });
+  assertDirectory(binDir);
+  fs.mkdirSync(binDir, { recursive: true });
+  const link = path.join(binDir, code);
+  let existing;
+  try {
+    existing = fs.lstatSync(link);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  if (existing) {
+    if (path.resolve(binary) === path.resolve(link)) return link;
+    if (existing.isSymbolicLink() && fs.readlinkSync(link) === binary) return link;
+    throw new Error(`Cannot expose ${code} on PATH because ${link} already exists. Preserve it and resolve the conflict.`);
+  }
+  fs.symlinkSync(binary, link);
+  return link;
+}
+
+function ensureProvider(context, options = {}) {
+  const provider = PROVIDERS[context.code];
+  const runtime = providerEnvironment(options);
+  if (!available(context.code, runtime)) {
+    if (context.code === 'claude') {
+      installClaudeNative(runtime);
+    } else {
+      if (!available('npm', runtime)) throw new Error('Install npm to install the selected coding CLI, then retry.');
+      logger.log(`Installing ${context.code} for the current user...`);
+      checked('npm', ['install', '--global', '--prefix', runtime.prefix, provider.package],
+        `Could not install ${context.code}. Check npm access and user-directory permissions, then retry.`, runtime);
+    }
+  }
+  const binary = available(context.code, runtime);
+  if (!binary) throw new Error(`The ${context.code} executable was not found after installation.`);
+  checked(binary, ['--version'], `The ${context.code} executable is not usable. Reinstall it, then retry.`, runtime);
+  try {
+    capture(binary, provider.status, runtime);
+  } catch {
+    interactive(binary, provider.login, `${context.code} login did not complete. Sign in and retry.`, runtime);
+  }
+  checked(binary, provider.status, `${context.code} authentication could not be verified.`, runtime);
+  if (options.managed) exposeManagedProvider(binary, context.code, options);
+  return { binary, env: runtime.env };
+}
+
+module.exports = { ensureController, ensureGithubLogin, ensureProvider, providerEnvironment, exposeManagedProvider };

package/lib/agent-kit/setup-context.js

@@ -0,0 +1,118 @@
+/** Validate the minimal onboarding inputs and resolve the configured workspace root. */
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const inquirer = require('inquirer');
+const fs = require('../internal/fs-real-sync');
+const config = require('../core/config');
+const paths = require('../utils/paths');
+const { isUnsafeRoot } = require('./repo-guard');
+const { available } = require('./setup-process');
+
+function controllerUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error('A valid Controller URL is required.');
+  }
+  if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password || url.search || url.hash) {
+    throw new Error('Controller URL must use HTTP(S) without credentials, query parameters, or a fragment.');
+  }
+  return url.href.replace(/\/+$/, '');
+}
+
+function setupName(options, repository) {
+  if (options.managed && options.name !== undefined) return options.name;
+  return repository === undefined ? 'workspace' : repository;
+}
+
+function validFolderName(name) {
+  return typeof name === 'string' && /^[a-z0-9][a-z0-9._-]{0,99}$/i.test(name) && !name.endsWith('.git');
+}
+
+function normalizeSetup(options) {
+  const controller = controllerUrl(options.controllerUrl);
+  const code = options.code || 'codex';
+  const hosts = options.managed ? ['codex', 'claude', 'cursor'] : ['codex', 'claude'];
+  if (!hosts.includes(code)) throw new Error(options.managed
+    ? 'Managed codingPlatform must be codex, claude, or cursor.' : 'Use codex or claude for --code.');
+  if (options.repo !== undefined && (typeof options.repo !== 'string' || options.repo.split('/').length !== 2)) {
+    throw new Error('Use --repo owner/name for a GitHub repository.');
+  }
+  const [org, repository] = options.repo === undefined ? [] : options.repo.split('/');
+  const name = setupName(options, repository);
+  if (org !== undefined && !/^[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?$/i.test(org)) {
+    throw new Error('Invalid GitHub organization or user name.');
+  }
+  if (!validFolderName(name)) {
+    throw new Error(options.managed
+      ? 'Invalid --name. Use one folder name without slashes or a .git suffix.'
+      : 'Invalid repository name. Use a simple folder name without a .git suffix.');
+  }
+  return { controller, code, name, fullName: org ? `${org}/${name}` : null };
+}
+
+function preflight(context, options = {}) {
+  const platform = options.platform || process.platform;
+  const arch = options.arch || process.arch;
+  if (!['linux', 'darwin'].includes(platform) || !['x64', 'arm64'].includes(arch)) {
+    throw new Error('Agent onboarding supports Linux/macOS on x64 or arm64.');
+  }
+  const tty = options.isTTY === undefined ? process.stdin.isTTY && process.stdout.isTTY : options.isTTY;
+  if (!tty) throw new Error(options.managed
+    ? 'Run onboarding in an interactive terminal for account login.'
+    : 'Run agent-kit setup in an interactive terminal for login and agent attachment.');
+  for (const bin of ['git', ...(!options.managed || context.code === 'claude' ? ['tmux'] : []),
+    ...(context.fullName ? ['gh'] : [])]) {
+    if (!available(bin, options)) throw new Error(`${bin} is required on PATH. Install it, then retry onboarding.`);
+  }
+}
+
+function assertDirectory(file) {
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if (error.code === 'ENOENT') return;
+    throw error;
+  }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`Expected a directory, not a link or file: ${file}`);
+  }
+}
+
+function workspaceName(context, options, root, home) {
+  if (options.managed && root === home && options.name === undefined && !context.fullName) {
+    return 'agent-kit-workspace';
+  }
+  return context.name;
+}
+
+async function resolveWork(context, options = {}) {
+  let root = (options.getWork || paths.getAifabrixWork)();
+  if (!root && options.managed) root = path.join(options.homedir || os.homedir(), 'aifabrix-work');
+  if (!root) {
+    const answer = await (options.prompt || inquirer.prompt)([{
+      type: 'input', name: 'work', message: 'AI Fabrix work directory:',
+      default: path.join(os.homedir(), 'aifabrix-work'),
+      validate: value => path.isAbsolute(String(value).trim()) || 'Enter an absolute directory path.'
+    }]);
+    root = String(answer.work || '').trim();
+    if (!path.isAbsolute(root)) throw new Error('Work directory must be an absolute path.');
+    await (options.setWork || config.setAifabrixWorkOverride)(root);
+  }
+  root = path.resolve(root);
+  assertDirectory(root);
+  fs.mkdirSync(root, { recursive: true });
+  root = fs.realpathSync(root);
+  const home = fs.realpathSync(options.homedir || os.homedir());
+  const name = workspaceName(context, options, root, home);
+  const target = path.join(root, name);
+  if (isUnsafeRoot(target)) throw new Error('Refusing to use home or the filesystem root as a workspace.');
+  assertDirectory(target);
+  return { ...context, name, root, target };
+}
+
+module.exports = { normalizeSetup, preflight, resolveWork, assertDirectory };

package/lib/agent-kit/setup-github.js

@@ -0,0 +1,70 @@
+/** Optional GitHub onboarding; API creation arbitrates missing/private repository names. */
+'use strict';
+
+const { capture, checked } = require('./setup-process');
+
+function githubOptions(options = {}) {
+  return { ...options, env: { ...process.env, ...options.env, GH_HOST: 'github.com' } };
+}
+
+function lookupRepository(fullName, options) {
+  options = githubOptions(options);
+  try {
+    return JSON.parse(capture('gh', ['api', `repos/${fullName}`], options));
+  } catch (error) {
+    // gh's included HTTP response allows status checking without exposing its body/errors.
+    try {
+      capture('gh', ['api', '--include', `repos/${fullName}`], options);
+    } catch (probe) {
+      if (/^HTTP\/\S+ 404(?:\s|$)/m.test(String(probe.stdout || ''))) return null;
+    }
+    throw new Error('Cannot inspect the GitHub repository. Check account access and connectivity, then retry.');
+  }
+}
+
+function createRepository(fullName, options) {
+  checked('gh', ['repo', 'create', fullName, '--private'],
+    'GitHub could not create the private repository. It may already exist without access, or creation is denied. No push was attempted.', githubOptions(options));
+}
+
+function cloneRepository(context, options) {
+  checked('gh', ['repo', 'clone', context.fullName, context.target, '--', '--origin', 'origin'],
+    'Repository clone failed. Preserve any partial folder and inspect GitHub access before retrying.', githubOptions(options));
+}
+
+function originIdentity(target, options) {
+  let origin;
+  try {
+    origin = String(capture('git', ['remote', 'get-url', 'origin'], { ...options, cwd: target })).trim();
+  } catch {
+    return null;
+  }
+  const match = /^(?:https:\/\/github\.com\/|git@github\.com:)([a-z0-9-]+\/[a-z0-9._-]+?)(?:\.git)?$/i.exec(origin);
+  return match ? match[1].toLowerCase() : 'unrecognized';
+}
+
+function assertOrigin(context, options) {
+  if (originIdentity(context.target, options) !== context.fullName.toLowerCase()) {
+    throw new Error('The existing origin does not match the requested GitHub repository. No remote was changed.');
+  }
+}
+
+function pushInitialCommit(context, progress, save, options) {
+  const opts = { ...githubOptions(options), cwd: context.target };
+  assertOrigin(context, options);
+  const expected = progress.state.initialCommit;
+  if (!/^[0-9a-f]{40,64}$/.test(expected || '')) throw new Error('Missing initial commit identity; refusing to push.');
+  const credentials = ['-c', 'credential.helper=', '-c', 'credential.https://github.com.helper=!gh auth git-credential'];
+  const remote = String(checked('git', [...credentials, 'ls-remote', 'origin', 'refs/heads/main'],
+    'Cannot verify the remote branch before initial push.', opts)).trim();
+  if (remote && remote.split(/\s/)[0] !== expected) {
+    throw new Error('Remote branch changed during onboarding. Reconcile it with Git before retrying.');
+  }
+  if (!remote) {
+    checked('git', [...credentials, 'push', 'origin', `${expected}:refs/heads/main`],
+      'Initial push failed. Local files and the private repository are preserved; retry setup.', opts);
+  }
+  save(progress, { pushed: true });
+}
+
+module.exports = { lookupRepository, createRepository, cloneRepository, originIdentity, assertOrigin, pushInitialCommit };