@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/repo-controls/src/azdo-push.ts

@@ -0,0 +1,463 @@
+#!/usr/bin/env bun
+
+import { parseAzureDevOpsRemote } from './azure-devops-remote.ts'
+// Agent identity, not a fallback to the human's own Azure CLI login (12g:
+// STATUS.md 12p -- an agent pushed as the human
+// because this path used to mint its bearer from the human's Azure CLI
+// session). packages/azdo/src/lib/agent-identity.ts is THE one identity
+// resolver and mint path (W1); this is the same async `getAccessToken`
+// bin/git-ado's agent path and packages/azdo's own callers drive.
+// `resolveAgentIdentity` throws before any spawn or network call when no
+// identity resolves, so a missing identity never reaches Azure DevOps.
+import { resolveAgentIdentity } from '../../azdo/src/lib/agent-identity.ts'
+import { getAccessToken } from '../../azdo/src/lib/agent-token.ts'
+
+const HOOKS_PATH = '.workflows/hooks'
+// Read on CALL, not on import. As a spawned script these could be module-level
+// constants; as a CLI module, evaluating them at import would throw before the
+// command that needs them was even chosen.
+const branchPattern = () =>
+  new RegExp(`^(${requiredEnv('ADL_REPO_CONTROLS_BRANCH_PREFIXES')})\\/[a-z0-9]+(?:-[a-z0-9]+)*$`)
+const projectRoot = () => requiredEnv('ADL_REPO_CONTROLS_ROOT')
+function requiredEnv(name: string): string {
+  const value = process.env[name]
+  if (!value) throw new Error(`${name} is not set — run through adl-repo-controls`)
+  return value
+}
+
+/** The git remote azdo-push pushes to and reads status from (`[pre_push] remote`, default `origin`). */
+export function resolveRemoteName(env: Readonly<Record<string, string | undefined>>): string {
+  const value = env.ADL_REPO_CONTROLS_REMOTE
+  if (!value) throw new Error('ADL_REPO_CONTROLS_REMOTE is not set — run through adl-repo-controls')
+  return value
+}
+
+/** How many times to retry a concurrent Azure ref update (TF401028) under the push lock. */
+export const PUSH_RACE_ATTEMPTS = Number(process.env.ADL_PUSH_RACE_ATTEMPTS || 3)
+
+interface CommandResult {
+  exitCode: number
+  stderr: string
+  stdout: string
+}
+
+export function isAzureRefUpdatedByOtherClient(text: string): boolean {
+  return /TF401028/i.test(text) || /already been updated by another client/i.test(text)
+}
+
+export type PushDeliveryState = 'delivered' | 'retry' | 'behind'
+export type FailedPushRecovery = 'delivered' | 'retry' | 'fail'
+
+/** After fetch: ahead=0 means every local commit is on the remote tip ancestry. */
+export function classifyPushDelivery(aheadCount: number, behindCount: number): PushDeliveryState {
+  if (!Number.isFinite(aheadCount) || !Number.isFinite(behindCount) || aheadCount < 0 || behindCount < 0) {
+    throw new Error(`Invalid ahead/behind counts: ahead=${aheadCount} behind=${behindCount}`)
+  }
+  if (aheadCount === 0) return 'delivered'
+  if (behindCount > 0) return 'behind'
+  return 'retry'
+}
+
+export function decideFailedPushRecovery(options: {
+  afterState: PushDeliveryState
+  concurrentUpdate: boolean
+  attempt: number
+  attempts: number
+}): FailedPushRecovery {
+  if (options.afterState === 'delivered') return 'delivered'
+  if (options.concurrentUpdate && options.afterState === 'retry' && options.attempt < options.attempts) {
+    return 'retry'
+  }
+  return 'fail'
+}
+
+export function deliveredPushMessage(
+  remoteName: string,
+  branch: string,
+  ahead: number,
+  behind: number,
+  afterFailure: boolean,
+): string {
+  if (afterFailure) {
+    return `azdo-push: push reported failure but ${remoteName}/${branch} already contains HEAD — treating as delivered`
+  }
+  return ahead === 0 && behind === 0
+    ? `azdo-push: ${remoteName}/${branch} already at HEAD — nothing to push`
+    : `azdo-push: ${remoteName}/${branch} already contains HEAD — treating push as delivered`
+}
+
+export function parseRevCount(value: string, label: string): number {
+  const trimmed = value.trim()
+  if (!/^\d+$/.test(trimmed)) throw new Error(`Unable to parse ${label} rev-list count: ${trimmed || '(empty)'}`)
+  return Number(trimmed)
+}
+
+export function azureDevOpsHttpsRemote(remote: string): string {
+  return parseAzureDevOpsRemote(remote).httpsRemote
+}
+
+export function assertPushBranch(branch: string): string {
+  const value = branch.trim()
+  if (!branchPattern().test(value)) {
+    throw new Error(`Refusing to push invalid or protected branch: ${value || '(detached HEAD)'}`)
+  }
+  return value
+}
+
+/**
+ * Fail loudly when this checkout has no repository hooks.
+ *
+ * Without core.hooksPath every commit skips the staged coverage measure, the
+ * ratchet and the publish lock, and nothing says so — the hook that would have
+ * reported it is the missing one. A checkout provisioned by anything other
+ * than a completed setup.sh run (the 6-hourly upgrade job does not reinstall
+ * hooks) lands silently ungated, so assert it on the one path every agent push
+ * goes through.
+ */
+export function assertRepositoryHooksInstalled(hooksPath: string): void {
+  const configured = hooksPath.trim()
+  if (configured === HOOKS_PATH) return
+  throw new Error(
+    `Repository hooks are not installed: core.hooksPath is ${configured ? `"${configured}"` : 'unset'}, ` +
+      `expected "${HOOKS_PATH}". Commits are not being gated by the staged coverage ratchet. ` +
+      'Run: adl-repo-controls install --repo .',
+  )
+}
+
+/**
+ * `agent`, when given, is the SAME identity `accessToken` was minted for
+ * (`resolveAgentIdentity(process.env).agent` at the call site). It is set as
+ * `ADL_AGENT_ID_AGENT` on the returned environment so every git spawn built
+ * from it -- fetch, push, and everything else in this module -- carries an
+ * agent identity of its own, even when the caller's OWN identity resolved
+ * from the machine default-agent file rather than the environment (STATUS.md
+ * 12p, orchestrator sweep 2026-09-29: `bin/git-ado` now fails closed on an
+ * Azure DevOps network git command with no `ADL_AGENT_ID_AGENT` in its env,
+ * unless the caller is a marked human terminal -- neither of which describes
+ * this spawned child). `ADL_HUMAN_AZDO` is always stripped from the
+ * inherited environment, never carried through: this module is agent
+ * automation, never a marked human terminal, and an inherited marker (e.g.
+ * Tarun's own `.zshrc` export, if this ever runs from a shell that sourced
+ * it) must never let a git child claim the human pass-through instead.
+ */
+export function gitEnvironmentWithBearer(
+  source: Readonly<Record<string, string | undefined>>,
+  accessToken: string,
+  agent?: string,
+): Record<string, string> {
+  const token = accessToken.trim()
+  if (!token) throw new Error('Received an empty Azure DevOps access token.')
+
+  const rawCount = source.GIT_CONFIG_COUNT?.trim() || '0'
+  if (!/^\d+$/.test(rawCount)) throw new Error('GIT_CONFIG_COUNT must be a non-negative integer when set.')
+  const index = Number(rawCount)
+  const environment = Object.fromEntries(
+    Object.entries(source).filter(
+      (entry): entry is [string, string] => entry[1] !== undefined && entry[0] !== 'ADL_HUMAN_AZDO',
+    ),
+  )
+  if (agent) environment.ADL_AGENT_ID_AGENT = agent
+  environment.GIT_CONFIG_COUNT = String(index + 1)
+  environment[`GIT_CONFIG_KEY_${index}`] = 'http.extraheader'
+  environment[`GIT_CONFIG_VALUE_${index}`] = `AUTHORIZATION: bearer ${token}`
+  return environment
+}
+
+export function assertBranchNotBehindRemote(behindCount: string, remoteName: string, branch: string): void {
+  const behind = behindCount.trim()
+  if (behind !== '0') {
+    throw new Error(
+      `Local branch is behind ${remoteName}/${branch} by ${behind} commit(s). ` +
+        `Run: git fetch ${remoteName} && git rebase ${remoteName}/${branch}`,
+    )
+  }
+}
+
+/* istanbul ignore next -- git/az CLI process wrappers */
+function commandText(value: Uint8Array | undefined): string {
+  return value ? new TextDecoder().decode(value) : ''
+}
+
+/* istanbul ignore next -- git/az CLI process wrappers */
+function capture(command: string[], failure: string, environment?: Record<string, string>): CommandResult {
+  const result = Bun.spawnSync({
+    cmd: command,
+    cwd: projectRoot(),
+    env: environment,
+    stderr: 'pipe',
+    stdout: 'pipe',
+  })
+  const stderr = commandText(result.stderr).trimEnd()
+  const stdout = commandText(result.stdout).trimEnd()
+  if (result.exitCode !== 0) {
+    throw new Error(`${failure}: ${[stderr, stdout].filter(Boolean).join('\n') || `exit ${result.exitCode}`}`)
+  }
+  return { exitCode: 0, stderr, stdout }
+}
+
+/* istanbul ignore next -- git/az CLI process wrappers */
+function runInherited(command: string[], environment: Record<string, string>, failure: string): void {
+  const result = Bun.spawnSync({
+    cmd: command,
+    cwd: projectRoot(),
+    env: environment,
+    stderr: 'inherit',
+    stdin: 'inherit',
+    stdout: 'inherit',
+  })
+  if (result.exitCode !== 0) throw new Error(`${failure}: exit ${result.exitCode}`)
+}
+
+/* istanbul ignore next -- git/az CLI process wrappers */
+function runCaptured(
+  command: string[],
+  environment: Record<string, string>,
+  emitOutput = true,
+): CommandResult {
+  const result = Bun.spawnSync({
+    cmd: command,
+    cwd: projectRoot(),
+    env: environment,
+    stderr: 'pipe',
+    stdin: 'inherit',
+    stdout: 'pipe',
+  })
+  const stderr = commandText(result.stderr)
+  const stdout = commandText(result.stdout)
+  if (emitOutput && stdout) process.stdout.write(stdout)
+  if (emitOutput && stderr) process.stderr.write(stderr)
+  return { exitCode: result.exitCode ?? 1, stderr, stdout }
+}
+
+/* istanbul ignore next -- git process wrappers */
+function aheadBehind(
+  remoteName: string,
+  branch: string,
+  environment: Record<string, string>,
+): { ahead: number; behind: number } {
+  const trackingBranch = `${remoteName}/${branch}`
+  const ahead = parseRevCount(
+    capture(
+      ['git', 'rev-list', '--count', `${trackingBranch}..HEAD`],
+      `Unable to count commits ahead of ${trackingBranch}`,
+      environment,
+    ).stdout,
+    'ahead',
+  )
+  const behind = parseRevCount(
+    capture(
+      ['git', 'rev-list', '--count', `HEAD..${trackingBranch}`],
+      `Unable to count commits behind ${trackingBranch}`,
+      environment,
+    ).stdout,
+    'behind',
+  )
+  return { ahead, behind }
+}
+
+/* istanbul ignore next -- git process wrappers */
+function fetchRemoteBranch(
+  remote: string,
+  remoteName: string,
+  branch: string,
+  environment: Record<string, string>,
+  failure: string,
+  allowMissing = false,
+): boolean {
+  const fetched = runCaptured(
+    ['git', 'fetch', remote, `refs/heads/${branch}:refs/remotes/${remoteName}/${branch}`],
+    environment,
+    false,
+  )
+  if (fetched.exitCode === 0) return true
+
+  const detail = [fetched.stderr.trimEnd(), fetched.stdout.trimEnd()].filter(Boolean).join('\n') || `exit ${fetched.exitCode}`
+  const normalizedDetail = detail.trim().replace(/\r\n/g, '\n')
+  if (allowMissing && normalizedDetail === `fatal: couldn't find remote ref refs/heads/${branch}`) {
+    return false
+  }
+  throw new Error(`${failure}: ${detail}`)
+}
+
+type PushAttemptResult = { status: 'delivered' } | { status: 'retry' } | { status: 'failed'; detail: string }
+
+/* istanbul ignore next -- git process wrappers */
+function evaluateFailedPushAttempt(options: {
+  branch: string
+  remote: string
+  remoteName: string
+  environment: Record<string, string>
+  failureText: string
+  attempt: number
+  attempts: number
+}): PushAttemptResult {
+  fetchRemoteBranch(
+    options.remote,
+    options.remoteName,
+    options.branch,
+    options.environment,
+    `Unable to fetch ${options.remoteName}/${options.branch} after a failed push`,
+  )
+  const after = aheadBehind(options.remoteName, options.branch, options.environment)
+  const afterState = classifyPushDelivery(after.ahead, after.behind)
+  const recovery = decideFailedPushRecovery({
+    afterState,
+    concurrentUpdate: isAzureRefUpdatedByOtherClient(options.failureText),
+    attempt: options.attempt,
+    attempts: options.attempts,
+  })
+
+  if (recovery === 'delivered') {
+    process.stdout.write(`${deliveredPushMessage(options.remoteName, options.branch, after.ahead, after.behind, true)}\n`)
+    return { status: 'delivered' }
+  }
+  if (recovery === 'retry') {
+    process.stdout.write(
+      `azdo-push: concurrent remote update (TF401028) — retrying push (${options.attempt}/${options.attempts})\n`,
+    )
+    return { status: 'retry' }
+  }
+  if (afterState === 'behind') {
+    assertBranchNotBehindRemote(String(after.behind), options.remoteName, options.branch)
+  }
+  return { status: 'failed', detail: options.failureText }
+}
+
+/* istanbul ignore next -- git process wrappers */
+function deliverBranchTip(
+  remote: string,
+  remoteName: string,
+  branch: string,
+  environment: Record<string, string>,
+): void {
+  const attempts = Math.max(1, PUSH_RACE_ATTEMPTS)
+  let lastFailure = ''
+
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const remoteBranchExists = fetchRemoteBranch(
+      remote,
+      remoteName,
+      branch,
+      environment,
+      `Unable to fetch ${remoteName}/${branch} before push`,
+      true,
+    )
+    if (remoteBranchExists) {
+      const { ahead, behind } = aheadBehind(remoteName, branch, environment)
+      const state = classifyPushDelivery(ahead, behind)
+
+      if (state === 'delivered') {
+        process.stdout.write(`${deliveredPushMessage(remoteName, branch, ahead, behind, false)}\n`)
+        return
+      }
+      if (state === 'behind') {
+        assertBranchNotBehindRemote(String(behind), remoteName, branch)
+      }
+    }
+
+    process.stdout.write(`azdo-push: git push attempt ${attempt}/${attempts}\n`)
+    const pushed = runCaptured(['git', 'push', remote, `HEAD:refs/heads/${branch}`], environment)
+    if (pushed.exitCode === 0) return
+
+    lastFailure = [pushed.stderr, pushed.stdout].filter(Boolean).join('\n') || `exit ${pushed.exitCode}`
+    const outcome = evaluateFailedPushAttempt({
+      branch,
+      remote,
+      remoteName,
+      environment,
+      failureText: lastFailure,
+      attempt,
+      attempts,
+    })
+    if (outcome.status === 'delivered') return
+    if (outcome.status === 'retry') continue
+    throw new Error(`Unable to push ${branch}: ${outcome.detail}`)
+  }
+
+  throw new Error(`Unable to push ${branch}: ${lastFailure || 'exhausted push race attempts'}`)
+}
+
+/* istanbul ignore next -- git process wrappers */
+function configureUpstream(
+  remote: string,
+  remoteName: string,
+  branch: string,
+  environment: Record<string, string>,
+): void {
+  fetchRemoteBranch(
+    remote,
+    remoteName,
+    branch,
+    environment,
+    `Push succeeded but ${remoteName}/${branch} could not be refreshed`,
+  )
+  const fetchKey = `remote.${remoteName}.fetch`
+  const branchFetch = `+refs/heads/${branch}:refs/remotes/${remoteName}/${branch}`
+  const configured = runCaptured(['git', 'config', '--get-all', fetchKey], environment, false)
+  if (configured.exitCode !== 0 && configured.exitCode !== 1) {
+    const detail = [configured.stderr.trimEnd(), configured.stdout.trimEnd()].filter(Boolean).join('\n')
+    throw new Error(`Push succeeded but ${fetchKey} could not be read: ${detail || `exit ${configured.exitCode}`}`)
+  }
+  if (!configured.stdout.split(/\r?\n/).includes(branchFetch)) {
+    runInherited(
+      ['git', 'config', '--add', fetchKey, branchFetch],
+      environment,
+      `Push succeeded but ${remoteName}/${branch} fetch mapping could not be configured`,
+    )
+  }
+  runInherited(
+    ['git', 'branch', `--set-upstream-to=${remoteName}/${branch}`, branch],
+    environment,
+    `Push succeeded but ${branch} tracking could not be configured`,
+  )
+}
+
+/* istanbul ignore next -- git/az CLI process wrappers */
+async function main(): Promise<void> {
+  const branch = assertPushBranch(
+    capture(['git', 'branch', '--show-current'], 'Unable to read the current branch').stdout,
+  )
+  const remoteName = resolveRemoteName(process.env)
+  const remote = azureDevOpsHttpsRemote(
+    capture(['git', 'remote', 'get-url', remoteName], `Unable to read ${remoteName}`).stdout,
+  )
+  const agent = resolveAgentIdentity(process.env).agent
+  const token = await getAccessToken(agent)
+  const bearerEnvironment = gitEnvironmentWithBearer(process.env, token, agent)
+  const lockEnvironment = {
+    ...bearerEnvironment,
+  }
+  // Held across the network push so pre-push EXIT cannot open a TF401028 race window.
+  const pushEnvironment = {
+    ...lockEnvironment,
+  }
+
+  // Checked before the network push so an ungated checkout is reported once,
+  // loudly, instead of quietly shipping commits that no hook ever measured.
+  assertRepositoryHooksInstalled(
+    Bun.spawnSync({
+      cmd: ['git', 'config', '--get', 'core.hooksPath'],
+      cwd: projectRoot(),
+      stderr: 'pipe',
+      stdout: 'pipe',
+    }).stdout.toString(),
+  )
+
+  process.stdout.write(`azdo-push: pushing ${branch} through ${remote}\n`)
+  // The branch push lock went with the coverage mechanism: it serialised a
+  // MEASUREMENT, so it belongs to whoever produces one. TF401028 retries below
+  // are what actually make a concurrent ref update safe.
+  deliverBranchTip(remote, remoteName, branch, pushEnvironment)
+  configureUpstream(remote, remoteName, branch, pushEnvironment)
+}
+
+/** `adl-repo-controls azdo-push` — the CLI entry point. */
+export async function azdoPush(err: (line: string) => void): Promise<number> {
+  try {
+    await main()
+    return 0
+  } catch (error) {
+    err(`azdo-push: FAIL — ${error instanceof Error ? error.message : String(error)}`)
+    return 1
+  }
+}