@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.29 → 0.1.32

package/packages/repo-controls/src/install-compliance.ts

@@ -0,0 +1,112 @@
+// Post-install grading (Bug 570); see README, "Compliance seeding".
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { loadComplianceConfig } from './compliance-config.ts'
+import { runTool } from './hook.ts'
+import { which, type Env } from './runtime.ts'
+
+interface ComplianceFinding {
+  message: string
+  /** What the engine says to do; '' when the finding carries no fix clause. */
+  fix: string
+}
+
+interface ComplianceGate {
+  id: string
+  address: string
+  /** FAIL: graded and found wrong. ERROR: could not run. */
+  status: 'FAIL' | 'ERROR'
+  summary: string
+  findings: ComplianceFinding[]
+}
+
+export interface InstallCompliance {
+  /** True only when every enabled gate PASSED. */
+  ok: boolean
+  enabled: string[]
+  failing: ComplianceGate[]
+  /** Printable lines for an agent. */
+  guidance: string[]
+}
+
+const ROW = /^(\S+)\s+(\S+)\s+\S\s+(FAIL|ERROR)\s*(.*)$/
+const FINDING = /^\s{4}(\S.*)$/
+
+/** Parse the engine's failures.log into its non-passing gates. */
+function parseFailuresLog(text: string): ComplianceGate[] {
+  const gates: ComplianceGate[] = []
+  for (const line of text.split('\n')) {
+    if (line.startsWith('#') || line.trim() === '') continue
+    const finding = FINDING.exec(line)
+    if (finding !== null) {
+      const current = gates.at(-1)
+      if (current === undefined) throw new Error(`compliance failures.log has a finding before any gate row: ${line}`)
+      const at = finding[1]!.lastIndexOf('; fix: ')
+      current.findings.push(
+        at === -1 ? { message: finding[1]!, fix: '' } : { message: finding[1]!.slice(0, at), fix: finding[1]!.slice(at + '; fix: '.length) },
+      )
+      continue
+    }
+    const row = ROW.exec(line)
+    if (row === null) throw new Error(`compliance failures.log has a line this installer cannot read: ${line}`)
+    gates.push({ id: row[1]!, address: row[2]!, status: row[3] as 'FAIL' | 'ERROR', summary: row[4]!.trim(), findings: [] })
+  }
+  return gates
+}
+
+const SWITCH_OFF_GUIDANCE =
+  "To switch a gate off, remove it from [controls.compliance] enabled in adl-config.toml \u2014 that is this repository's decision, and adl-config.toml is a protected file landed by the owner."
+
+function guidanceFor(enabled: string[], failing: ComplianceGate[]): string[] {
+  if (enabled.length === 0) {
+    return ['adl-config.toml [controls.compliance].enabled is empty: nothing is enforced. Name the gates to arm.']
+  }
+  if (failing.length === 0) return [`This repository now enforces ${enabled.length} compliance gates; all pass.`, SWITCH_OFF_GUIDANCE]
+  const lines = [
+    `This repository now enforces ${enabled.length} compliance gates; ${failing.length} failing. Fix the findings below before committing.`,
+  ]
+  for (const gate of failing) {
+    if (gate.status === 'ERROR') {
+      lines.push(`COULD-NOT-RUN ${gate.address} (${gate.id}): ${gate.summary}`)
+      continue
+    }
+    lines.push(`FAIL ${gate.address} (${gate.id}): ${gate.summary}`)
+    for (const finding of gate.findings) {
+      lines.push(`  - ${finding.message}`)
+      if (finding.fix !== '') lines.push(`    fix: ${finding.fix}`)
+    }
+  }
+  lines.push(SWITCH_OFF_GUIDANCE)
+  return lines
+}
+
+export class UvMissingError extends Error {}
+
+/** Grade `repo` with the gates its `enabled` names; throws when no verdict is known, and an empty `enabled` runs nothing. */
+export function gradeInstalledRepo(repo: string, env: Env): InstallCompliance {
+  const enabled = loadComplianceConfig(repo).enabled
+  if (enabled.length === 0) return { ok: true, enabled, failing: [], guidance: guidanceFor(enabled, []) }
+  if (which('uv', env) === null) {
+    throw new UvMissingError(
+      'uv not found on PATH — install wired the hooks and armed the compliance gates, but cannot grade them. Install uv (https://docs.astral.sh/uv/), then run `adl repo controls compliance run --repo ' + repo + '`',
+    )
+  }
+  const logDir = mkdtempSync(join(tmpdir(), 'adl-install-compliance-'))
+  try {
+    const code = runTool('compliance', repo, ['--summary', '--log-dir', logDir], { env, cwd: repo, err: () => {}, quietEngine: true })
+    let log: string | null = null
+    try {
+      log = readFileSync(join(logDir, 'failures.log'), 'utf8')
+    } catch {
+      log = null
+    }
+    if (code === 0) return { ok: true, enabled, failing: [], guidance: guidanceFor(enabled, []) }
+    if (log === null) throw new Error(`the compliance engine exited ${code} without a failures.log, so no gate verdict is known`)
+    const failing = parseFailuresLog(log)
+    if (failing.length === 0) throw new Error(`the compliance engine exited ${code} but its failures.log names no gate`)
+    return { ok: false, enabled, failing, guidance: guidanceFor(enabled, failing) }
+  } finally {
+    rmSync(logDir, { recursive: true, force: true })
+  }
+}

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

@@ -3,13 +3,16 @@
 // every install. The only preserved bytes are pre-hard-cut hook-log evidence;
 // there is no adoption, merge, or displaced-original path for managed content.
 import { createHash } from 'node:crypto'
-import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { chmodSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import { defaultComplianceConfigTextFor, seededComplianceAttributesFor } from './compliance-config.ts'
+import type { SeededAttribute } from './config.ts'
+import { DEFAULT_COMPLIANCE_CONFIG_TEXT, SEEDED_COMPLIANCE_ATTRIBUTES } from './compliance-config.ts'
+import { gradeInstalledRepo, type InstallCompliance } from './install-compliance.ts'
+import type { Env } from './runtime.ts'
 import {
   appendToTableSpan,
-  DEFAULT_CONFIG_TEXT,
   extractTableSpan,
+  integritySeed,
   isTable,
   removeTableSpan,
   removeFromTableSpan,
@@ -21,10 +24,15 @@ import {
   ADL_NPM_INSTALL,
   CONFIG_REL,
   GITIGNORE_REL,
+  GLOBAL_INVARIANTS_SOURCE,
+  GLOBAL_INVARIANTS_TARGET,
   HOOK_NAMES,
   HOOKS_PATH,
   LOCK_REL,
   MANAGED_ASSETS,
+  SCAFFOLD_ROOT,
+  SCAFFOLD_ROOT_FILES,
+  SCAFFOLD_TREES,
   TOOL,
   VERSION,
   WORKFLOWS_ROOT,
@@ -183,6 +191,24 @@ class Ops {
     if (mode !== undefined) chmodSync(path, mode)
   }
 
+  /** Create `rel` only if nothing is there; see README, "Scaffolding". */
+  create(rel: string, content: string | Buffer, reason: string): void {
+    if (this.writtenSoFar.has(rel) || lstatSync(this.abs(rel), { throwIfNoEntry: false }) !== undefined) return
+    this.write(rel, content, reason)
+  }
+
+  /** Whether anything (file, folder or link, even dangling) is at `rel`. A non-directory in the way of a parent fails loudly. */
+  occupied(rel: string): boolean {
+    const segments = rel.split('/')
+    for (let end = 1; end <= segments.length; end += 1) {
+      const current = lstatSync(this.abs(segments.slice(0, end).join('/')), { throwIfNoEntry: false })
+      if (current === undefined) return false
+      if (current.isSymbolicLink() && statSync(this.abs(segments.slice(0, end).join('/')), { throwIfNoEntry: false })?.isDirectory() === true) continue
+      if (!current.isDirectory()) throw new Error(`cannot scaffold ${rel}: ${segments.slice(0, end).join('/')} exists and is not a directory`)
+    }
+    return true
+  }
+
   remove(rel: string, reason: string): void {
     const path = this.abs(rel)
     // `existsSync` follows links and reports false for a dangling link.  Owned
@@ -204,12 +230,18 @@ class Ops {
 
 export interface InstallOptions {
   dryRun?: boolean
+  /** Grade the repository once the wiring is complete (never under dryRun); see README, "Compliance seeding". */
+  grade?: { env: Env }
+  /** Re-wire only: no config seeding, no scaffolding, no grading (fleet reconcile; see README, "Re-wiring"). */
+  rewire?: boolean
 }
 
 export interface InstallResult {
   repo: string
   actions: Action[]
   dryRun: boolean
+  /** Present only when `options.grade` was given and this was a real run. */
+  compliance?: InstallCompliance
 }
 
 /**
@@ -238,6 +270,7 @@ export function install(repoArg: string, options: InstallOptions): InstallResult
   // Validate only repo-controls' declared tables before deleting its root.
   // Other owners' tables remain deliberately opaque.
   validateOwnedConfig(initialConfigText)
+  declaredScaffoldTrees(initialConfigText)
   // The lock is outside neither configuration nor runtime boundaries, so read
   // its bookkeeping before replacing its containing root.  It is never used
   // to preserve root content.
@@ -271,32 +304,39 @@ export function install(repoArg: string, options: InstallOptions): InstallResult
     files[rel] = { sha256: sha256(text) }
   }
 
-  const controlsResult = installConfigTable(
-    initialConfigText,
-    'controls',
-    DEFAULT_CONFIG_TEXT,
-    SEEDED_ATTRIBUTES,
-    prev?.config ?? null,
-    ops,
-  )
-  const complianceResult = installConfigTable(
-    controlsResult.text,
-    'controls.compliance',
-    defaultComplianceConfigTextFor(repo),
-    seededComplianceAttributesFor(repo),
-    prev?.complianceConfig ?? null,
-    ops,
-  )
-  // Both entries' hashes are computed from the SAME final merged text (not each call's
-  // intermediate view of it): appending [compliance] after [controls] can extend the byte
-  // span findTableSpan reports for [controls] (e.g. a trailing blank separator line before
-  // the next header), so hashing at each call's own intermediate text would immediately
-  // go stale the moment a later call appends more content to the same file.
-  const finalConfigText = complianceResult.text
-  const config: TableConfigRecord = { created: controlsResult.created, sha256: sha256(extractTableSpan(finalConfigText, 'controls') as string) }
-  const complianceConfig: TableConfigRecord = {
-    created: complianceResult.created,
-    sha256: sha256(extractTableSpan(finalConfigText, 'controls.compliance') as string),
+  const rewire = options.rewire === true
+  let config: TableConfigRecord = prev?.config ?? null
+  let complianceConfig: TableConfigRecord = prev?.complianceConfig ?? null
+  if (!rewire) {
+    const controlsAttributes = [...SEEDED_ATTRIBUTES, ...integrityWatchSeed(initialConfigText)]
+    const controlsResult = installConfigTable(
+      initialConfigText,
+      'controls',
+      `[controls]${controlsAttributes.map((a) => a.text).join('')}`,
+      controlsAttributes,
+      prev?.config ?? null,
+      ops,
+    )
+    const complianceResult = installConfigTable(
+      controlsResult.text,
+      'controls.compliance',
+      DEFAULT_COMPLIANCE_CONFIG_TEXT,
+      SEEDED_COMPLIANCE_ATTRIBUTES,
+      prev?.complianceConfig ?? null,
+      ops,
+    )
+    // Both entries' hashes are computed from the SAME final merged text (not each call's
+    // intermediate view of it): appending [compliance] after [controls] can extend the byte
+    // span findTableSpan reports for [controls] (e.g. a trailing blank separator line before
+    // the next header), so hashing at each call's own intermediate text would immediately
+    // go stale the moment a later call appends more content to the same file.
+    const finalConfigText = complianceResult.text
+    config = { created: controlsResult.created, sha256: sha256(extractTableSpan(finalConfigText, 'controls') as string) }
+    complianceConfig = {
+      created: complianceResult.created,
+      sha256: sha256(extractTableSpan(finalConfigText, 'controls.compliance') as string),
+    }
+    scaffoldStandardTrees(finalConfigText, ops)
   }
 
   const gitignore = installGitignore(repo, prev?.gitignore ?? null, ops)
@@ -314,7 +354,19 @@ export function install(repoArg: string, options: InstallOptions): InstallResult
     gitignore,
   }
   ops.write(LOCK_REL, `${JSON.stringify(lock, null, 2)}\n`, 'install lock')
-  return { repo, actions: ops.actions, dryRun }
+  // Graded last, so a missing `uv` fails loudly only after every file is wired.
+  const compliance = options.grade !== undefined && !dryRun && !rewire ? gradeInstalledRepo(repo, options.grade.env) : undefined
+  return { repo, actions: ops.actions, dryRun, ...(compliance === undefined ? {} : { compliance }) }
+}
+
+/** The `[controls] integrity` seed: watch the declared compliance register folder (see README, "Compliance seeding"). Empty when no folder is declared. */
+function integrityWatchSeed(configText: string): SeededAttribute[] {
+  const trees = ownedTable(configText, 'controls.compliance')?.trees
+  // declaredScaffoldTrees ran first in install() and already rejected a non-string value.
+  const declared = (isTable(trees) ? (trees.compliance ?? 'compliance') : 'compliance') as string
+  const folder = declared.replace(/^(\.\/)+/, '').replace(/\/+$/, '')
+  if (folder === '') return []
+  return [integritySeed(folder)]
 }
 
 /** The value at a dotted table path (`controls.compliance`), or undefined if absent. */
@@ -425,6 +477,57 @@ function installConfigTable(
   return { text: appended, created: true }
 }
 
+/** The scaffold trees declared in config, validated; throws on a malformed path so install can refuse before any write. */
+function declaredScaffoldTrees(configText: string): { name: string; base: string }[] {
+  const trees: { name: string; base: string }[] = []
+  const declared = ownedTable(configText, 'controls.compliance')?.trees
+  if (!isTable(declared)) return trees
+  assertComplianceTree(declared.compliance)
+  for (const name of SCAFFOLD_TREES) {
+    const value = declared[name]
+    if (value === undefined || value === '') continue
+    if (typeof value !== 'string') throw new Error(`${CONFIG_REL} [controls.compliance.trees] ${name} must be a string`)
+    const base = value.replace(/^(\.\/)+/, '').replace(/\/+$/, '')
+    if (!isRelative(base)) throw new Error(`${CONFIG_REL} [controls.compliance.trees] ${name} must be a repository-relative path: ${value}`)
+    trees.push({ name, base })
+  }
+  return trees
+}
+
+/** The compliance register folder is not scaffolded but is seeded into `[controls] integrity`, so it takes the tree path rules plus a safe character set. */
+function assertComplianceTree(value: unknown): void {
+  if (value === undefined || value === '') return
+  const where = `${CONFIG_REL} [controls.compliance.trees] compliance`
+  if (typeof value !== 'string') throw new Error(`${where} must be a string`)
+  const base = value.replace(/^(\.\/)+/, '').replace(/\/+$/, '')
+  if (!isRelative(base)) throw new Error(`${where} must be a repository-relative path: ${value}`)
+  if (!/^[A-Za-z0-9._/-]+$/.test(base)) throw new Error(`${where} may only contain letters, digits, '.', '_', '-' and '/': ${value}`)
+}
+
+/** Bootstrap the standard trees at their declared paths, only where the folder is missing; see README, "Scaffolding". */
+function scaffoldStandardTrees(configText: string, ops: Ops): void {
+  const missing = declaredScaffoldTrees(configText).filter(({ base }) => !ops.occupied(base))
+  for (const rel of SCAFFOLD_ROOT_FILES) {
+    ops.create(rel, readFileSync(join(SCAFFOLD_ROOT, 'root', rel)), 'scaffold the repository entry files (user-owned after install)')
+  }
+  ops.create(GLOBAL_INVARIANTS_TARGET, readFileSync(GLOBAL_INVARIANTS_SOURCE), 'deploy the global invariants (user-owned after install)')
+  for (const { name, base } of missing) {
+    for (const rel of scaffoldFiles(join(SCAFFOLD_ROOT, name), '')) {
+      ops.create(`${base}/${rel}`, readFileSync(join(SCAFFOLD_ROOT, name, rel)), `scaffold the ${name} tree (user-owned after install)`)
+    }
+  }
+}
+
+/** Every file under `dir`, relative to it, sorted, depth-first. */
+function scaffoldFiles(dir: string, prefix: string): string[] {
+  return readdirSync(join(dir, prefix), { withFileTypes: true })
+    .sort((a, b) => (a.name < b.name ? -1 : 1))
+    .flatMap((entry) => {
+      const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`
+      return entry.isDirectory() ? scaffoldFiles(dir, rel) : [rel]
+    })
+}
+
 function installGitignore(repo: string, prev: GitignoreRecord | null, ops: Ops): GitignoreRecord {
   const path = join(repo, GITIGNORE_REL)
   const exists = existsSync(path)