@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

package/packages/repo-controls/src/azure-devops-governance.ts

@@ -0,0 +1,248 @@
+import {
+  promotionPolicyReceipts,
+  type PolicyConfiguration,
+} from './promote.ts'
+import { parseAzureDevOpsRemote } from './azure-devops-remote.ts'
+// The relative cross-package import below (not `@adl/azdo`) matches
+// apps/cli/src/commands/mcp.ts and apps/cli/src/commands/repo-doctor.ts:
+// this workspace has no node_modules/@adl/* symlinks without `bun install`.
+// packages/azdo/src/lib/agent-identity.ts is now THE one identity resolver
+// and packages/azdo/src/lib/agent-token.ts is now THE one mint (STATUS.md
+// 12p, W1 and finding M9) — this package no longer keeps its own copy of
+// either.
+import { resolveAgentIdentity } from '../../azdo/src/lib/agent-identity.ts'
+import { getAccessTokenSync } from '../../azdo/src/lib/agent-token.ts'
+import { capture, type Env } from './runtime.ts'
+
+const HTTPS_HANDLE = 'https://amsterdamdatalabs@dev.azure.com/<org>/<project>/_git/<repo>'
+
+export interface AzureDevOpsRemote {
+  org: string
+  project: string
+  repository: string
+  remote: string
+}
+
+export interface AzureDevOpsPolicyEvidence {
+  repositoryId: string
+  policies: PolicyConfiguration[]
+}
+
+export interface AzureDevOpsGovernanceCheck {
+  id: string
+  status: 'ok' | 'warn' | 'fail'
+  message: string
+}
+
+export interface AzureDevOpsGovernanceRequest {
+  repo: string
+  remote: AzureDevOpsRemote
+  target: string
+  env: Env
+  /**
+   * Hermetic reader-test seam for agent-identity resolution
+   * (`resolveAgentIdentity`, packages/azdo/src/lib/agent-identity.ts).
+   * Production doctor and hook requests never set this, so they always
+   * resolve against the real `process.platform`.
+   */
+  platform?: NodeJS.Platform
+}
+
+export type AzureDevOpsPolicyReader = (request: AzureDevOpsGovernanceRequest) => AzureDevOpsPolicyEvidence
+
+const errorText = (error: unknown): string => (error instanceof Error ? error.message : String(error))
+
+/**
+ * Promotion governance is bound to the fleet's HTTPS form. A bare HTTPS URL
+ * is intentionally insufficient: the agreed `amsterdamdatalabs@` handle is
+ * what makes the machine's Git credential selection deterministic.
+ */
+export function parseAzureDevOpsHttpsRemote(value: string): AzureDevOpsRemote {
+  const parsed = parseAzureDevOpsRemote(value)
+  if (parsed.form !== 'https-handle') {
+    throw new Error(`origin must use the HTTPS handle ${HTTPS_HANDLE}; found ${parsed.remote || '(empty)'}`)
+  }
+  return {
+    org: parsed.org,
+    project: parsed.project,
+    repository: parsed.repository,
+    remote: parsed.remote,
+  }
+}
+
+function parseJson(text: string, label: string): unknown {
+  try {
+    return JSON.parse(text) as unknown
+  } catch {
+    throw new Error(`${label} returned malformed JSON`)
+  }
+}
+
+/**
+ * Mints a bearer token for the effective agent identity through THE one mint
+ * (`packages/azdo/src/lib/agent-token.ts`'s `getAccessTokenSync` — same
+ * two-hop exec `bin/git-ado`'s agent path also drives, same parsing, same
+ * pinned addresses; STATUS.md 12p finding M9: this package no longer keeps
+ * its own copy). `env` is threaded through unmerged with real `process.env`
+ * (not `capture`'s childEnv) so a hermetic test's sparse env is exactly what
+ * decides both which `adl-agent-id` is found and what the spawned child
+ * sees — same isolation the old copy's own `which(..., env)` gave. This
+ * process never sees the vault proxy, the CA, or a client secret — only the
+ * finished bearer token, read from the child's stdout pipe; nothing here
+ * logs it or puts it on argv.
+ */
+function mintAccessToken(env: Env, platform?: NodeJS.Platform): string {
+  const agent = resolveAgentIdentity(env, platform).agent
+  return getAccessTokenSync(agent, env)
+}
+
+function getJson(repo: string, env: Env, token: string, url: string, label: string): unknown {
+  // The bearer never enters argv, the command text, a file, or process.env
+  // that a listing of this process would show — it is confined to this
+  // child's own environment and expanded inside the shell after exec.
+  const result = capture(
+    [
+      '/bin/sh',
+      '-c',
+      'curl --fail-with-body --silent --show-error --header "Authorization: Bearer $ADL_REPO_CONTROLS_AZDO_BEARER" "$ADL_REPO_CONTROLS_AZDO_URL"',
+    ],
+    repo,
+    {
+      ...env,
+      ADL_REPO_CONTROLS_AZDO_BEARER: token,
+      ADL_REPO_CONTROLS_AZDO_URL: url,
+    },
+  )
+  if (result.code !== 0) {
+    throw new Error(`${label} request failed (exit ${result.code}): ${result.stderr.trim() || 'no diagnostic'}`)
+  }
+  return parseJson(result.stdout, label)
+}
+
+/** Read-only evidence retrieval. No Azure DevOps mutation is available on this path. */
+export function readAzureDevOpsPolicyEvidence(request: AzureDevOpsGovernanceRequest): AzureDevOpsPolicyEvidence {
+  const { org, project, repository } = request.remote
+  const projectUrl = `https://dev.azure.com/${encodeURIComponent(org)}/${encodeURIComponent(project)}`
+  const token = mintAccessToken(request.env, request.platform)
+  const repositoryJson = getJson(
+    request.repo,
+    request.env,
+    token,
+    `${projectUrl}/_apis/git/repositories/${encodeURIComponent(repository)}?api-version=7.1`,
+    'Azure DevOps repository endpoint',
+  )
+  if (typeof repositoryJson !== 'object' || repositoryJson === null || typeof (repositoryJson as { id?: unknown }).id !== 'string') {
+    throw new Error('Azure DevOps repository endpoint did not return repository id')
+  }
+  const repositoryId = (repositoryJson as { id: string }).id.trim()
+  if (!repositoryId) throw new Error('Azure DevOps repository endpoint returned an empty repository id')
+  const query = new URLSearchParams({
+    repositoryId,
+    refName: `refs/heads/${request.target}`,
+    '$top': '1000',
+    'api-version': '7.1',
+  })
+  const policiesJson = getJson(
+    request.repo,
+    request.env,
+    token,
+    `${projectUrl}/_apis/git/policy/configurations?${query}`,
+    'Azure DevOps policy endpoint',
+  )
+  if (
+    typeof policiesJson !== 'object' ||
+    policiesJson === null ||
+    !Array.isArray((policiesJson as { value?: unknown }).value)
+  ) {
+    throw new Error('Azure DevOps policy endpoint did not return a policy list')
+  }
+  return { repositoryId, policies: (policiesJson as { value: PolicyConfiguration[] }).value }
+}
+
+export interface AzureDevOpsGovernanceOptions {
+  repo?: string
+  remote: string
+  target: string
+  env?: Env
+  readEvidence?: AzureDevOpsPolicyReader
+}
+
+/**
+ * One read-only receipt per promotion guard. Unreadable evidence is a failure,
+ * never a warning: a commit cannot claim the remote guard is armed when that
+ * fact could not be established.
+ */
+export function azureDevOpsGovernanceChecks(options: AzureDevOpsGovernanceOptions): AzureDevOpsGovernanceCheck[] {
+  const checks: AzureDevOpsGovernanceCheck[] = []
+  let remote: AzureDevOpsRemote
+  try {
+    remote = parseAzureDevOpsHttpsRemote(options.remote)
+    checks.push({ id: 'azure-devops.remote', status: 'ok', message: `origin is ${remote.remote}` })
+  } catch (error) {
+    checks.push({ id: 'azure-devops.remote', status: 'fail', message: errorText(error) })
+    return checks
+  }
+
+  const target = options.target.trim()
+  if (!target) {
+    checks.push({
+      id: 'azure-devops.policy-read',
+      status: 'fail',
+      message: '[controls.release].target is required before doctor can verify Azure DevOps promotion governance',
+    })
+    return checks
+  }
+
+  let evidence: AzureDevOpsPolicyEvidence
+  try {
+    const request: AzureDevOpsGovernanceRequest = {
+      repo: options.repo ?? '.',
+      remote,
+      target,
+      env: options.env ?? {},
+    }
+    evidence = (options.readEvidence ?? readAzureDevOpsPolicyEvidence)(request)
+  } catch (error) {
+    checks.push({
+      id: 'azure-devops.policy-read',
+      status: 'fail',
+      message: `could not read Azure DevOps policy evidence: ${errorText(error)}`,
+    })
+    return checks
+  }
+
+  const targetRef = `refs/heads/${target}`
+  const receipts = promotionPolicyReceipts(evidence.policies, {
+    repositoryId: evidence.repositoryId,
+    targetRef,
+  })
+  const id = (policy: PolicyConfiguration): string => String(policy.id ?? '(unknown)')
+  const prefix = `${evidence.repositoryId} ${targetRef}`
+  checks.push(
+    receipts.minimumReviewer
+      ? {
+          id: 'azure-devops.minimum-review',
+          status: 'ok',
+          message: `blocking minimum-reviewer policy #${id(receipts.minimumReviewer)} requires one approval and resets votes for ${prefix}`,
+        }
+      : {
+          id: 'azure-devops.minimum-review',
+          status: 'fail',
+          message: `missing blocking minimum-reviewer policy requiring one approval and resetOnSourcePush=true for ${prefix}`,
+        },
+  )
+  checks.push(
+    receipts.build
+      ? {
+          id: 'azure-devops.build-policy',
+          status: 'ok',
+          message: `blocking build policy #${id(receipts.build)} uses definition ${receipts.build.settings?.buildDefinitionId} for ${prefix}`,
+        }
+      : {
+          id: 'azure-devops.build-policy',
+          status: 'fail',
+          message: `missing blocking build policy with a build definition for ${prefix}`,
+        },
+  )
+  return checks
+}

package/packages/repo-controls/src/azure-devops-remote.ts

@@ -0,0 +1,61 @@
+const HTTPS_HANDLE_USER = 'amsterdamdatalabs'
+
+export type AzureDevOpsRemoteForm = 'https-handle' | 'https' | 'ssh'
+
+export interface ParsedAzureDevOpsRemote {
+  form: AzureDevOpsRemoteForm
+  httpsRemote: string
+  org: string
+  project: string
+  remote: string
+  repository: string
+}
+
+function decoded(segment: string, label: string): string {
+  try {
+    const value = decodeURIComponent(segment)
+    if (value.trim() === '') throw new Error('empty')
+    return value
+  } catch {
+    throw new Error(`origin contains an invalid ${label} segment: ${segment}`)
+  }
+}
+
+function parsed(
+  remote: string,
+  form: AzureDevOpsRemoteForm,
+  orgSegment: string,
+  projectSegment: string,
+  repositorySegment: string,
+): ParsedAzureDevOpsRemote {
+  const org = decoded(orgSegment, 'organization')
+  const project = decoded(projectSegment, 'project')
+  const repository = decoded(repositorySegment, 'repository').replace(/\.git$/, '')
+  if (!repository) throw new Error(`origin contains an invalid repository segment: ${repositorySegment}`)
+  return {
+    form,
+    httpsRemote: `https://dev.azure.com/${encodeURIComponent(org)}/${encodeURIComponent(project)}/_git/${encodeURIComponent(repository)}`,
+    org,
+    project,
+    remote,
+    repository,
+  }
+}
+
+/** Strictly parse every Azure DevOps remote form supported by repository controls. */
+export function parseAzureDevOpsRemote(value: string): ParsedAzureDevOpsRemote {
+  const remote = value.trim().replace(/\/$/, '')
+
+  const handle = new RegExp(
+    `^https://${HTTPS_HANDLE_USER}@dev\\.azure\\.com/([^/]+)/([^/]+)/_git/([^/]+)$`,
+  ).exec(remote)
+  if (handle) return parsed(remote, 'https-handle', handle[1] as string, handle[2] as string, handle[3] as string)
+
+  const https = /^https:\/\/dev\.azure\.com\/([^/]+)\/([^/]+)\/_git\/([^/]+)$/.exec(remote)
+  if (https) return parsed(remote, 'https', https[1] as string, https[2] as string, https[3] as string)
+
+  const ssh = /^git@ssh\.dev\.azure\.com:v3\/([^/]+)\/([^/]+)\/([^/]+)$/.exec(remote)
+  if (ssh) return parsed(remote, 'ssh', ssh[1] as string, ssh[2] as string, ssh[3] as string)
+
+  throw new Error('origin must be an Azure DevOps SSH or HTTPS repository URL.')
+}

package/packages/repo-controls/src/cli.ts

@@ -0,0 +1,188 @@
+import { HOOK_NAMES, TOOL, VERSION } from './constants.ts'
+import { doctor } from './doctor.ts'
+import { azdoPush } from './azdo-push.ts'
+import { ensurePromotionPullRequest } from './promote.ts'
+import { configEnv, loadConfig } from './config.ts'
+import { logHookEvent } from './hook-log.ts'
+import { isHookName, isToolName, runHook, runTool, TOOLS } from './hook.ts'
+import { resolveRepo } from './runtime.ts'
+import { type Action, install, uninstall } from './install.ts'
+import type { Env } from './runtime.ts'
+
+export interface Io {
+  out: (line: string) => void
+  err: (line: string) => void
+  env: Env
+  cwd: string
+}
+
+export const USAGE = `usage:
+  ${TOOL} install --repo <path> [--dry-run]
+  ${TOOL} uninstall --repo <path> [--dry-run]
+  ${TOOL} doctor --repo <path> [--json]
+  ${TOOL} hook <${HOOK_NAMES.join('|')}> [git hook args...]
+  ${TOOL} log <${HOOK_NAMES.join('|')}> <reason> [context] [message]   (internal — called by the bundled hooks)
+  ${TOOL} promote --repo <path>
+  ${TOOL} run <${Object.keys(TOOLS).join('|')}> --repo <path> [-- args...]
+  ${TOOL} --version | help`
+
+class UsageError extends Error {
+  constructor(message: string) {
+    super(message)
+  }
+}
+
+interface Parsed {
+  repo: string
+  flags: Set<string>
+  positional: string[]
+  rest: string[]
+}
+
+function parse(command: string, argv: string[], allowed: string[]): Parsed {
+  const parsed: Parsed = { repo: '', flags: new Set(), positional: [], rest: [] }
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index] as string
+    if (arg === '--') {
+      parsed.rest = argv.slice(index + 1)
+      break
+    }
+    if (arg === '--repo') {
+      parsed.repo = argv[++index] ?? ''
+    } else if (arg.startsWith('--')) {
+      if (!allowed.includes(arg)) throw new UsageError(`unknown option for ${command}: ${arg}`)
+      parsed.flags.add(arg)
+    } else {
+      parsed.positional.push(arg)
+    }
+  }
+  if (parsed.repo === '') throw new UsageError('--repo <path> is required')
+  return parsed
+}
+
+function printActions(io: Io, actions: Action[], dryRun: boolean): void {
+  const tag = dryRun ? '[dry-run] ' : ''
+  for (const action of actions) io.out(`${tag}${action.kind} ${action.target} (${action.reason})`)
+  io.out(actions.length === 0 ? 'up to date (no changes)' : `${tag}${dryRun ? 'would change' : 'changed'} ${actions.length} item(s)`)
+}
+
+async function dispatch(argv: string[], io: Io): Promise<number> {
+  const [command = '', ...args] = argv
+  const context = { env: io.env, cwd: io.cwd, err: io.err }
+  switch (command) {
+    case '--version':
+      io.out(VERSION)
+      return 0
+    case 'help':
+    case '--help':
+      io.out(USAGE)
+      return 0
+    case 'install': {
+      const parsed = parse(command, args, ['--dry-run'])
+      const result = install(parsed.repo, { dryRun: parsed.flags.has('--dry-run') })
+      printActions(io, result.actions, result.dryRun)
+      io.out(`${result.dryRun ? '[dry-run] ' : ''}${TOOL} ${VERSION} installed into ${result.repo}`)
+      return 0
+    }
+    case 'uninstall': {
+      const parsed = parse(command, args, ['--dry-run'])
+      const result = uninstall(parsed.repo, {
+        dryRun: parsed.flags.has('--dry-run'),
+      })
+      printActions(io, result.actions, result.dryRun)
+      for (const note of result.notes) io.out(`note: ${note}`)
+      io.out(`${result.dryRun ? '[dry-run] ' : ''}${TOOL} uninstalled from ${result.repo}`)
+      return 0
+    }
+    case 'doctor': {
+      const parsed = parse(command, args, ['--json'])
+      const report = doctor(parsed.repo, io.env)
+      if (parsed.flags.has('--json')) {
+        io.out(JSON.stringify(report, null, 2))
+      } else {
+        for (const check of report.checks) {
+          io.out(`${(check.status === 'fail' ? 'FAIL' : check.status).padEnd(5)} ${check.id}  ${check.message}`)
+        }
+      }
+      return report.ok ? 0 : 1
+    }
+    case 'hook': {
+      const [name = '', ...hookArgs] = args
+      if (!isHookName(name)) throw new UsageError(`unknown hook: ${name}`)
+      return runHook(name, hookArgs, context)
+    }
+    // The bundled bash hooks' seam back into the shared `.adl/logs/` JSON-Lines
+    // writer — see src/hook-log.ts's header for why a bash script needs this
+    // rather than the `hook` command above capturing its own output.
+    case 'log': {
+      const [name = '', reason = '', hookContext = '', message = ''] = args
+      if (!isHookName(name)) throw new UsageError(`unknown hook: ${name}`)
+      logHookEvent(name, reason, hookContext, message, io.cwd)
+      return 0
+    }
+    // Exit enforcement, run BY the CLI rather than spawned as a file: branch
+    // prefixes, hooks-installed, not-behind-remote, and ADO's TF401028 ref-update
+    // race. Owner ruling 2026-09-16: "the whole integration, main, branch
+    // policies, raising PR approval mechanism has to be standard".
+    case 'azdo-push': {
+      const parsed = parse(command, args, [])
+      const repo = resolveRepo(parsed.repo)
+      // The push mechanics read their configuration from the environment, which
+      // `configEnv` supplies; `azdoPush` itself only needs somewhere to report.
+      Object.assign(process.env, configEnv(repo, loadConfig(repo)))
+      return await azdoPush(context.err)
+    }
+    // Promote one branch to another through an Azure DevOps pull request.
+    //
+    // NOT superseded by the azure-devops MCP server, though it looks it. Two
+    // reasons, both checked: this runs inside an Azure pipeline
+    // (enact-m5 promote-main-stage.yaml:30) and a CI agent has no MCP client --
+    // MCP is stdio, agent-side. And `repo_pull_request_write` constrains
+    // mergeStrategy to `enum: ['Squash']` (mcp-server.ts:139), so it cannot
+    // express the rebase/fast-forward this performs. Replacing this with the
+    // MCP tool would silently change the merge strategy.
+    case 'promote': {
+      const parsed = parse(command, args, [])
+      const repo = resolveRepo(parsed.repo)
+      const { release } = loadConfig(repo)
+      const result = await ensurePromotionPullRequest({
+        collectionUri: context.env.AZURE_DEVOPS_COLLECTION_URI,
+        project: context.env.AZURE_DEVOPS_PROJECT,
+        repositoryId: context.env.AZURE_DEVOPS_REPOSITORY_ID,
+        token: context.env.AZURE_DEVOPS_TOKEN,
+        buildId: context.env.AZURE_DEVOPS_BUILD_ID,
+        sourceVersion: context.env.AZURE_DEVOPS_SOURCE_VERSION,
+        source: release.source,
+        target: release.target,
+        mergeStrategy: release.mergeStrategy,
+      })
+      if (result.status === 'not-needed') {
+        context.err(`promote: no promotion needed for ${release.source} -> ${release.target}`)
+      } else {
+        context.err(`promote: ${result.status} ${release.source} -> ${release.target} PR #${result.pullRequestId}`)
+      }
+      return 0
+    }
+    case 'run': {
+      const parsed = parse(command, args, [])
+      const tool = parsed.positional[0] ?? ''
+      if (!isToolName(tool)) throw new UsageError(`unknown tool: ${tool}`)
+      return runTool(tool, parsed.repo, parsed.rest, context)
+    }
+    default:
+      throw new UsageError(command === '' ? 'missing command' : `unknown command: ${command}`)
+  }
+}
+
+export async function main(argv: string[], io: Io): Promise<number> {
+  try {
+    return await dispatch(argv, io)
+  } catch (error) {
+    if (error instanceof UsageError) {
+      io.err(`${TOOL}: ${error.message}\n${USAGE}`)
+      return 2
+    }
+    io.err(`${TOOL}: FAIL — ${(error as Error).message}`)
+    return 1
+  }
+}