@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.10 → 0.1.12

package/packages/fleet/src/repo-maintain.ts

@@ -0,0 +1,403 @@
+/**
+ * Repository maintenance: the repository step of `adl reconcile`
+ * (`adl maintain --location DIR`). It replaces the retired git-maintain
+ * LaunchAgent (2026-09-30, Tarun: "one binary controlling everything").
+ *
+ * Scope is exactly ONE directory, the host's `repo_location` from the fleet
+ * manifest, and only its IMMEDIATE children that carry `adl-config.toml` and
+ * are git top-levels. Nothing else is ever touched or mentioned: every child
+ * is resolved (symlinks followed) and must still be a direct child of the
+ * location BEFORE any file inside it is stat'ed, so a symlink can never make
+ * this step read, fetch into or install into anything outside the location.
+ * A directory without the marker is not this step's business at all.
+ *
+ * Per repository, in order:
+ *   1. `git fetch origin --prune`;
+ *   2. fast-forward the local `integration` and `main` (whichever exist on
+ *      both sides) -- only ever a true fast-forward. A branch checked out in a
+ *      worktree (this one or another) is moved only when that worktree is
+ *      clean (`merge --ff-only`), else WARN and skip; a branch checked out
+ *      nowhere is moved with a compare-and-swap `update-ref`;
+ *   3. the safe-only local branch prune (ported from git-maintain): protected
+ *      integration/main/master/develop and HEAD are never deleted, the KEEP
+ *      most recent branches are kept, and only "[gone]" upstreams (-D) or
+ *      branches merged into the baseline (-d) are deleted;
+ *   4. `adl install --repo <repo>` -- the existing per-repo enrolment.
+ *
+ * This runs as the device administrator, never root (the caller,
+ * bin/reconcile-host, drops privileges and `adl maintain --expect-user`
+ * refuses otherwise). It never migrates enact-config.toml: a repo that has
+ * both markers is a named failure.
+ *
+ * Reporting: plain progress lines go to `out`; every warning and failure goes
+ * to `err` as `WARN repo-maintain: ...` / `ERROR repo-maintain: ...` (the
+ * level word `adl logs` filters on). A failure never stops the other
+ * repositories; the run returns `ok: false` when any occurred.
+ */
+import { spawnSync } from 'node:child_process'
+import { readdirSync, realpathSync, statSync, type Dirent } from 'node:fs'
+import { basename, dirname, isAbsolute, join } from 'node:path'
+import { NO_AGENT_IDENTITY_MESSAGE, resolveAgentIdentity } from '../../azdo/src/lib/agent-identity.ts'
+
+export const TCC_DENIED_MARKER = 'TCC denied'
+
+/** The file whose presence puts a repository in this step's scope. */
+export const MARKER = 'adl-config.toml'
+/** The retired marker; a repo with both is ambiguous and fails loud. */
+const LEGACY_MARKER = 'enact-config.toml'
+
+/** Branches fast-forwarded, in this order. */
+const SYNCED_BRANCHES = ['integration', 'main'] as const
+const PROTECTED = new Set(['integration', 'main', 'master', 'develop'])
+const DEFAULT_KEEP = 3
+
+/** Case-insensitive, by name and by realpath: never an Azure Pipelines agent install. */
+const FORBIDDEN_PATH_PATTERN = /azagent|vsts\.agent/i
+
+export interface MaintainOptions {
+  /** Absolute path of the host's `repo_location`. */
+  readonly location: string
+  /** The running adl binary, named in the Full Disk Access remedy. */
+  readonly executable: string
+  /** How to run `adl`: `<command> <...leadingArgs> install --repo <repo>`. */
+  readonly install: { readonly command: string; readonly leadingArgs: readonly string[] }
+  /** Most recent non-protected local branches kept by the prune. Default 3. */
+  readonly keep?: number
+  /** Report only: fetches, but never moves a ref, deletes a branch or runs install. */
+  readonly dryRun?: boolean
+  /** Environment for identity resolution and every child. Default process.env. */
+  readonly env?: NodeJS.ProcessEnv
+  readonly out?: (line: string) => void
+  readonly err?: (line: string) => void
+}
+
+export interface MaintainResult {
+  readonly ok: boolean
+  readonly repositories: number
+  readonly failures: readonly string[]
+}
+
+/**
+ * Lines explaining why `root` could not be listed. EPERM from readdir is what
+ * macOS privacy protection (TCC) returns -- plain permission bits give EACCES
+ * -- so it names the exact binary the owner must grant Full Disk Access.
+ */
+export function listFailureLines(root: string, error: unknown, executable: string): readonly string[] {
+  const message = error instanceof Error ? error.message : String(error)
+  const code = (error as { code?: unknown } | null)?.code
+  if (code === 'ENOTDIR') return [`${root}: ${message}`]
+  const lines = [`${root}: cannot list: ${message}`]
+  if (code === 'EPERM') {
+    lines.push(
+      `${root}: ${TCC_DENIED_MARKER}: macOS privacy protection blocked ${executable}; ` +
+        `one-time fix: System Settings › Privacy & Security › Full Disk Access › + › add ${executable}`,
+    )
+  }
+  return lines
+}
+
+interface GitResult {
+  readonly ok: boolean
+  readonly stdout: string
+  readonly stderr: string
+}
+
+function errorCode(error: unknown): string | undefined {
+  const code = (error as { code?: unknown } | null)?.code
+  return typeof code === 'string' ? code : undefined
+}
+
+function lines(output: string): string[] {
+  return output.split('\n').filter((line) => line.length > 0)
+}
+
+function isForbiddenAzurePipelinesPath(path: string): boolean {
+  if (FORBIDDEN_PATH_PATTERN.test(path)) return true
+  try {
+    return FORBIDDEN_PATH_PATTERN.test(realpathSync(path))
+  } catch {
+    return false
+  }
+}
+
+/** `packages/<name>/enact-config.toml` -- the per-package copies of the retired marker. */
+function legacyMarkers(repo: string): string[] {
+  const found: string[] = []
+  const tryStat = (relative: string): void => {
+    try {
+      if (statSync(join(repo, relative)).isFile()) found.push(relative)
+    } catch (error) {
+      if (errorCode(error) !== 'ENOENT' && errorCode(error) !== 'ENOTDIR') throw error
+    }
+  }
+  tryStat(LEGACY_MARKER)
+  let packages: Dirent[] = []
+  try {
+    packages = readdirSync(join(repo, 'packages'), { withFileTypes: true })
+  } catch (error) {
+    if (errorCode(error) !== 'ENOENT' && errorCode(error) !== 'ENOTDIR') throw error
+  }
+  for (const entry of packages.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.isDirectory()) tryStat(join('packages', entry.name, LEGACY_MARKER))
+  }
+  return found
+}
+
+export function maintainRepositories(options: MaintainOptions): MaintainResult {
+  const env = options.env ?? process.env
+  const keep = options.keep ?? DEFAULT_KEEP
+  const dry = options.dryRun ?? false
+  const out = options.out ?? ((line: string) => void process.stdout.write(`${line}\n`))
+  const errOut = options.err ?? ((line: string) => void process.stderr.write(`${line}\n`))
+  const info = (message: string): void => out(`repo-maintain: ${message}`)
+  const warn = (message: string): void => errOut(`WARN repo-maintain: ${message}`)
+  const failures: string[] = []
+  const fail = (message: string, subject: string): void => {
+    errOut(`ERROR repo-maintain: ${message}`)
+    failures.push(subject)
+  }
+
+  let identityEnv: NodeJS.ProcessEnv = {}
+  const childEnv = (): NodeJS.ProcessEnv => ({ ...env, ...identityEnv })
+  const git = (repo: string, ...args: string[]): GitResult => {
+    const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', env: childEnv() })
+    if (result.error !== undefined) throw result.error
+    return { ok: result.status === 0, stdout: result.stdout, stderr: result.stderr ?? '' }
+  }
+
+  const { location } = options
+  if (!isAbsolute(location)) {
+    fail(`location must be an absolute path: ${location}`, location)
+    return { ok: false, repositories: 0, failures }
+  }
+  if (isForbiddenAzurePipelinesPath(location)) {
+    fail(`${location}: refusing an Azure Pipelines agent path`, location)
+    return { ok: false, repositories: 0, failures }
+  }
+
+  // Resolve the Azure DevOps agent identity ONCE, before touching any repo
+  // (F6): this job runs with no TTY and no ADL_AGENT_ID_AGENT, and bin/git-ado
+  // fails closed without one. A real resolution error is fatal; "nothing
+  // configured" is only fatal for Azure DevOps remotes, which are skipped
+  // loudly below rather than fetched with no identity.
+  let agent: string | undefined
+  try {
+    agent = resolveAgentIdentity(env).agent
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (message !== NO_AGENT_IDENTITY_MESSAGE) {
+      fail(`cannot resolve an Azure DevOps agent identity: ${message}`, 'identity')
+      return { ok: false, repositories: 0, failures }
+    }
+    warn(
+      'no Azure DevOps agent identity resolved (no ADL_AGENT_ID_AGENT, no default-agent file): ' +
+        'Azure DevOps repos will be skipped this run, not silently fetched with no identity',
+    )
+  }
+  if (agent !== undefined) identityEnv = { ADL_AGENT_ID_AGENT: agent }
+
+  info(`start location=${location} keep=${keep} dry=${dry ? 1 : 0}`)
+
+  let entries: Dirent[]
+  let locationReal: string
+  try {
+    locationReal = realpathSync(location)
+    entries = readdirSync(locationReal, { withFileTypes: true })
+  } catch (error) {
+    for (const line of listFailureLines(location, error, options.executable)) errOut(`ERROR repo-maintain: ${line}`)
+    failures.push(location)
+    return { ok: false, repositories: 0, failures }
+  }
+
+  const seen = new Set<string>()
+  let repositories = 0
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    // Files and other non-directories (a symlink is the one kind resolved below).
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+    const candidate = join(locationReal, entry.name)
+
+    // 1. Resolve, then scope-check, BEFORE looking inside. A broken symlink
+    //    points nowhere and so carries no marker; any other failure to
+    //    resolve is reported, because it may hide an in-scope repository.
+    let real: string
+    try {
+      real = realpathSync(candidate)
+    } catch (error) {
+      if (errorCode(error) === 'ENOENT') continue
+      fail(`${candidate}: cannot resolve: ${error instanceof Error ? error.message : String(error)}`, candidate)
+      continue
+    }
+    if (dirname(real) !== locationReal) continue
+    if (seen.has(real)) continue
+
+    // 2. The marker decides scope. Not there: not this step's business, and
+    //    silent. Anything other than "not there" is a named failure.
+    try {
+      if (!statSync(join(real, MARKER)).isFile()) continue
+    } catch (error) {
+      const code = errorCode(error)
+      if (code === 'ENOENT' || code === 'ENOTDIR') continue
+      fail(`${real}: cannot read ${MARKER}: ${error instanceof Error ? error.message : String(error)}`, real)
+      continue
+    }
+    seen.add(real)
+
+    // 3. In scope from here on.
+    let legacy: string[]
+    try {
+      legacy = legacyMarkers(real)
+    } catch (error) {
+      fail(`${real}: cannot read: ${error instanceof Error ? error.message : String(error)}`, real)
+      continue
+    }
+    if (legacy.length > 0) {
+      fail(`${real}: duplicate markers: ${MARKER} and ${LEGACY_MARKER} (${legacy.join(', ')}); migrate or remove one`, real)
+      continue
+    }
+    if (!isGitToplevel(real)) {
+      warn(`${real}: ${MARKER} but not a git top-level; skipped`)
+      continue
+    }
+    repositories += 1
+    maintainRepo(real)
+  }
+
+  info(`done (${repositories} repositories, ${failures.length} failed)`)
+  return { ok: failures.length === 0, repositories, failures }
+
+  function isGitToplevel(directory: string): boolean {
+    const top = spawnSync('git', ['-C', directory, 'rev-parse', '--show-toplevel'], { encoding: 'utf8', env: childEnv() })
+    if (top.error !== undefined || top.status !== 0) return false
+    try {
+      return realpathSync(top.stdout.trim()) === directory
+    } catch {
+      return false
+    }
+  }
+
+  function baselineFor(repo: string): string {
+    for (const branch of ['integration', 'main', 'master']) {
+      if (git(repo, 'show-ref', '--verify', '--quiet', `refs/remotes/origin/${branch}`).ok) return branch
+    }
+    return ''
+  }
+
+  function maintainRepo(repo: string): void {
+    const name = basename(repo)
+
+    // An Azure DevOps remote needs an agent identity; without one the fetch
+    // would only fail (or be refused) far from the cause.
+    if (agent === undefined) {
+      const url = git(repo, 'remote', 'get-url', 'origin')
+      if (url.ok && /^https:\/\/[^/]*dev\.azure\.com\//.test(url.stdout.trim())) {
+        fail(`${name}: skipping: Azure DevOps remote but no agent identity resolved (see the start-of-run warning)`, repo)
+        return
+      }
+    }
+
+    const head = git(repo, 'symbolic-ref', '--short', '-q', 'HEAD')
+    const current = head.ok ? head.stdout.trim() : '(detached)'
+
+    // 1. fetch + prune. Report what git SAID, never a guess at what it meant.
+    const fetched = git(repo, 'fetch', 'origin', '--prune', '--quiet')
+    if (!fetched.ok) {
+      const reason = fetched.stderr.trim().split('\n').pop() || 'no stderr from git'
+      fail(`${name}: fetch failed, skipping repo: ${reason}`, repo)
+      return
+    }
+
+    // 2. fast-forward integration and main.
+    for (const branch of SYNCED_BRANCHES) fastForward(repo, name, branch)
+
+    // 3. guarded prune.
+    prune(repo, name, current)
+
+    // 4. the per-repo enrolment.
+    const argv = [...options.install.leadingArgs, 'install', '--repo', repo]
+    const shown = `adl install --repo ${repo}`
+    if (dry) {
+      info(`${name}: [dry] would run ${shown}`)
+      return
+    }
+    const result = spawnSync(options.install.command, argv, { encoding: 'utf8', env: childEnv() })
+    if (result.error !== undefined) {
+      fail(`${name}: could not run ${options.install.command}: ${result.error.message}`, repo)
+    } else if (result.status !== 0) {
+      fail(`${name}: ${shown} exited ${result.status}: ${(result.stderr ?? '').trim()}`, repo)
+    } else {
+      info(`${name}: ${shown}: ok`)
+    }
+  }
+
+  function fastForward(repo: string, name: string, branch: string): void {
+    const local = `refs/heads/${branch}`
+    const remote = `refs/remotes/origin/${branch}`
+    if (!git(repo, 'show-ref', '--verify', '--quiet', local).ok) return
+    if (!git(repo, 'show-ref', '--verify', '--quiet', remote).ok) return
+    const localSha = git(repo, 'rev-parse', local).stdout.trim()
+    const remoteSha = git(repo, 'rev-parse', remote).stdout.trim()
+    if (localSha === remoteSha) return
+    if (!git(repo, 'merge-base', '--is-ancestor', local, remote).ok) {
+      // Not a fast-forward (local has commits origin lacks). Never moved.
+      if (!git(repo, 'merge-base', '--is-ancestor', remote, local).ok) {
+        warn(`${name}: ${branch} has diverged from origin/${branch}; not moved`)
+      }
+      return
+    }
+    // Where is it checked out, if anywhere? (`%(worktreepath)` covers this
+    // worktree and every linked one.)
+    const worktree = git(repo, 'for-each-ref', local, '--format=%(worktreepath)').stdout.trim()
+    if (worktree !== '') {
+      if (git(worktree, 'status', '--porcelain').stdout.trim() !== '') {
+        warn(`${name}: ${branch} checked out but dirty; skipped fast-forward`)
+      } else if (dry) {
+        info(`${name}: [dry] would fast-forward ${branch} (checked out)`)
+      } else if (git(worktree, 'merge', '--ff-only', `origin/${branch}`, '--quiet').ok) {
+        info(`${name}: ${branch} fast-forwarded (checked out)`)
+      } else {
+        fail(`${name}: ${branch} could not be fast-forwarded (checked out)`, repo)
+      }
+      return
+    }
+    if (dry) {
+      info(`${name}: [dry] would fast-forward ${branch} (background)`)
+    } else if (git(repo, 'update-ref', '-m', `adl maintain: fast-forward ${branch}`, local, remoteSha, localSha).ok) {
+      info(`${name}: ${branch} ref fast-forwarded (background)`)
+    } else {
+      fail(`${name}: ${branch} ref could not be fast-forwarded (background)`, repo)
+    }
+  }
+
+  function prune(repo: string, name: string, current: string): void {
+    const base = baselineFor(repo)
+    const keptRecent = new Set(
+      lines(git(repo, 'for-each-ref', '--sort=-committerdate', 'refs/heads/', '--format=%(refname:short)').stdout)
+        .filter((branch) => !PROTECTED.has(branch) && branch !== current)
+        .slice(0, keep),
+    )
+    const merged =
+      base === ''
+        ? new Set<string>()
+        : new Set(lines(git(repo, 'branch', '--merged', `origin/${base}`, '--format=%(refname:short)').stdout))
+
+    for (const line of lines(git(repo, 'for-each-ref', 'refs/heads/', '--format=%(refname:short)|%(upstream:track)').stdout)) {
+      const separator = line.indexOf('|')
+      const branch = line.slice(0, separator)
+      const track = line.slice(separator + 1)
+      if (PROTECTED.has(branch) || branch === current || keptRecent.has(branch)) continue
+
+      if (track.includes('[gone]')) {
+        // remote branch deleted after merge -> proven safe
+        if (dry) info(`${name}: [dry] would delete (upstream gone) ${branch}`)
+        else if (git(repo, 'branch', '-D', branch).ok) info(`${name}: deleted (upstream gone) ${branch}`)
+        else warn(`${name}: could not delete (upstream gone) ${branch}`)
+      } else if (base !== '' && merged.has(branch)) {
+        if (dry) info(`${name}: [dry] would delete (merged into ${base}) ${branch}`)
+        else if (git(repo, 'branch', '-d', branch).ok) info(`${name}: deleted (merged into ${base}) ${branch}`)
+        else info(`${name}: kept (${branch}: -d refused)`)
+      } else {
+        info(`${name}: kept (unconfirmed merged) ${branch}`)
+      }
+    }
+  }
+}

package/packages/fleet/src/scratch-reap.ts

@@ -20,7 +20,7 @@
  * `git worktree prune` is not a substitute for any of this. It only clears
  * metadata for worktrees whose directory has ALREADY been deleted.
  *
- * Invoked by reconcile's six-hourly pass (bin/reconcile), gated on
+ * Invoked by reconcile's 12-hourly pass (bin/reconcile), gated on
  * config.scratch_reap.enabled and the per-device scratch_repos list. Devices
  * that declare no scratch_repos are never touched — a developer machine's
  * scratch worktrees are working state, not fleet state.

package/packages/repo-controls/package.json

@@ -14,7 +14,6 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "bun test tests --coverage --timeout 30000",
-    "test:coverage": "bun test tests --coverage --timeout 30000",
     "check": "tsc --noEmit && bun test tests --coverage --timeout 30000",
     "coverage:ratchet": "bun workflows/scripts/coverage/ci-ratchet.ts",
     "coverage:produce": "bun test tests --coverage --timeout 30000 && bun workflows/scripts/coverage/command.ts"