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

package/packages/repo-controls/src/gitignore-block.ts

@@ -0,0 +1,253 @@
+// One marker-bounded block, written into a target repository's root
+// `.gitignore` by `install()`, listing every repository-local directory the
+// adl process (repo-controls itself, plus the sibling tools it enrolls a
+// repository into: agent-hooks' `lean-ctx` runtime, the `adl` CLI's own
+// logger, and the `.scratchpad/` convention every agent surface follows) is
+// known to create there. Before this module the only programmatic coverage
+// was two individually-appended lines (`GITIGNORE_LINES`, retired) plus a
+// data-dependent legacy-quarantine reconciliation; everything else
+// (`.scratchpad/`, `.agents/lean-ctx/*`, `.adl/`) accumulated by hand into
+// this monorepo's own root `.gitignore` over time and was never shipped to a
+// repository that only runs `install`. This is the single source of truth
+// for that list, and the one mechanism that writes or checks it — see
+// `install.ts`'s `installGitignore`/`removeGitignoreLines` (the writer) and
+// `doctor.ts`/`workflows-drift.ts` (the reader, via `checkGitignoreBlock`).
+//
+// Evidence for each entry, gathered 2026-09-27 by reading this monorepo's
+// own source (not guessed):
+//   - `/.enact/logs/`      — pre-hard-cut evidence only (constants.ts
+//                            `LOGS_ROOT_REL`). Neither repo-controls' git
+//                            hooks (`src/hook-log.ts`, 2026-09-27) nor
+//                            agent-hooks' own hook log write here any more —
+//                            both moved to `.adl/logs/` JSON-Lines files
+//                            (docs/architecture/cli-design.md §5a). Existing rows are
+//                            quarantined in place, never migrated.
+//   - `/.coverage-cache/`  — constants.ts `GITIGNORE_LINES` (retired) /
+//                            install.ts `installGitignore`'s coverage-cache
+//                            handling; populated by the coverage ratchet.
+//   - `/.workflows/hooks/logs/`,
+//     `/.enact-runtime/repo-controls/hooks/`
+//                          — install.ts `LEGACY_LOG_QUARANTINES`: pre-hardcut
+//                            hook-log roots. Reconciliation only PRESERVES
+//                            bytes already there (never reads/writes them);
+//                            this block ignores both unconditionally rather
+//                            than the old data-dependent
+//                            present-only-while-evidence-exists behaviour —
+//                            a static, always-present pattern that matches
+//                            nothing costs a consumer repo nothing, and one
+//                            static list is the whole point of this file.
+//   - `/.adl/`             — packages/cli/src/log.ts's `.adl/logs` (repo
+//                            root's session/tool-call log; docs/architecture/cli-design.md
+//                            §5a). Whole `.adl/` dir ignored, matching this
+//                            monorepo's own hand-authored line.
+//   - `/.agents/lean-ctx/{data,state,cache}/`
+//                          — packages/agent-hooks/src/lean-ctx/env.ts:
+//                            `leanCtxEnv` points the `lean-ctx` binary's
+//                            data/state/cache dirs under
+//                            `<repo>/<DEFAULT_LEAN_CTX_DIR>/{data,state,cache}`.
+//                            `config/` is deliberately NOT listed: this
+//                            monorepo's own `.agents/lean-ctx/config/lean-ctx/
+//                            *.toml` is git-tracked (confirmed via
+//                            `git ls-files .agents`), so it is committed
+//                            configuration, not generated state. A repository
+//                            whose `adl-config.toml` overrides
+//                            `[hooks] lean_ctx_dir` away from the default is
+//                            a known gap this static list does not cover —
+//                            repo-controls does not depend on agent-hooks, so
+//                            it cannot resolve that override at install time
+//                            without introducing a new cross-package
+//                            dependency nobody asked for.
+//   - `/.scratchpad/`, `packages/*/.scratchpad/`
+//                          — not created by any single tool's code, but
+//                            mandated by the global agent convention (every
+//                            agent surface's own instructions: "all scratch
+//                            and throwaway work goes in `.scratchpad/` at the
+//                            repo root"). Both the root and the (discouraged
+//                            but observed) per-package form are ignored,
+//                            matching this monorepo's own root `.gitignore`.
+//
+// Deliberately NOT included (seen in one repo or another's `.gitignore`, but
+// no creator found in this monorepo's source — see the install task's own
+// inventory notes for the full accounting):
+//   - `.code-review-graph/` — created by the third-party `code-review-graph`
+//     binary at its own default location when agent-hooks' `crg` hook (see
+//     src/hooks/crg/index.ts) invokes it; agent-hooks sets no env var
+//     directing that output anywhere, so the path is the binary's own
+//     choice, not one this process configures.
+//   - `.cache/`, `.scratch/`, `.inject/`, `traces/`, `_evidence/`, `.donor/`,
+//     `.codegraph/`, `global-surfaces-live/`, `extensions/*/.{codex,claude,
+//     cursor,kimi}-plugin/`, `.bun/`, `bun.lockb` — present in this
+//     monorepo's own root `.gitignore` (accumulated by hand) but grepping
+//     this monorepo's source for each turned up either nothing, or (for
+//     `.cache/`/`.scratch/`/`.inject`) only unrelated matches: a `$HOME/
+//     .cache` global path, a code comment naming a DIFFERENT repository's
+//     `.scratch/`, and a local variable named `injected`. Not this process's
+//     output; not this task's to gitignore.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { GITIGNORE_REL, INSTALL_HINT } from './constants.ts'
+
+export const GITIGNORE_MARKER_START = '# >>> adl managed (do not edit) >>>'
+export const GITIGNORE_MARKER_END = '# <<< adl managed <<<'
+
+/**
+ * The block's body, in the exact order written — comments included, since a
+ * generated `.gitignore` block that explains itself is worth the extra
+ * lines. This is the single source of truth `install()`'s writer and
+ * `checkGitignoreBlock()`'s reader both consult; changing what the adl
+ * process ignores means changing this array, nothing else.
+ */
+export const GITIGNORE_BLOCK_LINES: readonly string[] = [
+  '# repo-controls: coverage ratchet cache',
+  '/.coverage-cache/',
+  '',
+  '# repo-controls / agent-hooks: canonical repository-local hook and session logs',
+  '/.enact/logs/',
+  '',
+  '# repo-controls: pre-hardcut hook-log quarantine (evidence only, never read or written)',
+  '/.workflows/hooks/logs/',
+  '/.enact-runtime/repo-controls/hooks/',
+  '',
+  "# adl CLI: repo-root session/tool-call logs (docs/architecture/cli-design.md §5a)",
+  '/.adl/',
+  '',
+  '# agent-hooks: lean-ctx per-repo runtime state (config/ subtree is committed)',
+  '/.agents/lean-ctx/data/',
+  '/.agents/lean-ctx/state/',
+  '/.agents/lean-ctx/cache/',
+  '',
+  '# adl process convention: scratch and throwaway work, never committed',
+  '/.scratchpad/',
+  'packages/*/.scratchpad/',
+] as const
+
+interface SplitText {
+  /** Lines with no trailing empty element from a final line terminator. */
+  readonly lines: string[]
+  /** `\r\n` if the input contained one, else `\n`. */
+  readonly nl: string
+}
+
+function splitText(text: string): SplitText {
+  const nl = text.includes('\r\n') ? '\r\n' : '\n'
+  if (text.length === 0) return { lines: [], nl }
+  const raw = text.split(/\r\n|\n/)
+  // A trailing terminator produces one trailing '' element from split(); a
+  // file with no trailing terminator does not. Track the terminator via
+  // `nl` and the join step below rather than keeping that ambiguity in
+  // `lines` itself, so both writer and remover treat the two the same way.
+  const lines = raw.length > 0 && raw[raw.length - 1] === '' ? raw.slice(0, -1) : raw
+  return { lines, nl }
+}
+
+function joinText(lines: readonly string[], nl: string): string {
+  return lines.length === 0 ? '' : `${lines.join(nl)}${nl}`
+}
+
+function findBlock(lines: readonly string[]): { start: number; end: number } | null {
+  const start = lines.indexOf(GITIGNORE_MARKER_START)
+  if (start === -1) return null
+  const end = lines.indexOf(GITIGNORE_MARKER_END, start + 1)
+  if (end === -1) return null
+  return { start, end }
+}
+
+/**
+ * Pure. Write (or replace in place) the adl-managed block inside `text`,
+ * preserving every other line byte-for-byte and never reordering them.
+ *
+ * - No existing block: appended at the end, with a single blank-line
+ *   separator when the file already has non-blank trailing content (never
+ *   when the file is empty/new).
+ * - An existing block (found by its start/end markers): replaced in place —
+ *   same position, canonical body — so a stale or hand-edited block is
+ *   repaired without moving relative to the rest of the file.
+ * - Only the FIRST start/end marker pair is treated as the block; content
+ *   after a second, orphaned start marker (there should never be one — the
+ *   writer never creates a second) is left untouched. `checkGitignoreBlock`
+ *   flags that shape as drift rather than silently accepting it.
+ * - A line the caller already had that happens to equal one of this block's
+ *   own lines (e.g. a hand-written `/.coverage-cache/` before this feature
+ *   existed) is left exactly where it was; the block still carries its own
+ *   copy. This function never scans outside the block to deduplicate — it
+ *   would mean rewriting a line it does not own.
+ */
+export function applyGitignoreBlock(text: string): string {
+  const { lines, nl } = splitText(text)
+  const blockLines = [GITIGNORE_MARKER_START, ...GITIGNORE_BLOCK_LINES, GITIGNORE_MARKER_END]
+  const found = findBlock(lines)
+  if (found !== null) {
+    const next = [...lines.slice(0, found.start), ...blockLines, ...lines.slice(found.end + 1)]
+    return joinText(next, nl)
+  }
+  const needsSeparator = lines.length > 0 && lines[lines.length - 1] !== ''
+  const next = needsSeparator ? [...lines, '', ...blockLines] : [...lines, ...blockLines]
+  return joinText(next, nl)
+}
+
+/**
+ * Pure inverse of `applyGitignoreBlock`: strip the adl-managed block back
+ * out, including the single blank separator line immediately before it
+ * (when present) — the same one `applyGitignoreBlock` inserts when
+ * appending — so an install immediately followed by an uninstall, with no
+ * other edits in between, restores the file to its pre-install bytes
+ * (module trailing-newline normalization; see `joinText`).
+ *
+ * Text with no recognizable block (already removed, or never installed) is
+ * returned unchanged.
+ */
+export function removeGitignoreBlock(text: string): string {
+  const { lines, nl } = splitText(text)
+  const found = findBlock(lines)
+  if (found === null) return text
+  const collapseSeparator = found.start > 0 && lines[found.start - 1] === ''
+  const from = collapseSeparator ? found.start - 1 : found.start
+  const next = [...lines.slice(0, from), ...lines.slice(found.end + 1)]
+  return joinText(next, nl)
+}
+
+export interface GitignoreBlockFinding {
+  /** Same id `doctor()` uses for this surface (`gitignore`). */
+  readonly id: string
+  readonly message: string
+}
+
+export interface GitignoreBlockReport {
+  readonly repo: string
+  readonly ok: boolean
+  readonly findings: GitignoreBlockFinding[]
+}
+
+/**
+ * Pure, read-only comparison of a repository's root `.gitignore` against the
+ * canonical adl-managed block this package would install. Same report shape
+ * as `workflows-drift.ts`'s `checkWorkflowsDrift` — `{ repo, ok, findings }`
+ * — so `adl repo doctor` (and anything else) can treat every drift surface
+ * uniformly. Never mutates the repository.
+ */
+export function checkGitignoreBlock(repoRoot: string): GitignoreBlockReport {
+  const path = join(repoRoot, GITIGNORE_REL)
+  const text = existsSync(path) ? readFileSync(path, 'utf8') : ''
+  const { lines } = splitText(text)
+
+  const starts = lines.reduce<number[]>((acc, line, index) => (line === GITIGNORE_MARKER_START ? [...acc, index] : acc), [])
+  const findings: GitignoreBlockFinding[] = []
+
+  if (starts.length === 0) {
+    findings.push({ id: 'gitignore', message: `${GITIGNORE_REL} is missing the adl managed block — ${INSTALL_HINT}` })
+  } else if (starts.length > 1) {
+    findings.push({ id: 'gitignore', message: `${GITIGNORE_REL} has ${starts.length} adl managed blocks, expected 1 — ${INSTALL_HINT}` })
+  } else {
+    const end = lines.indexOf(GITIGNORE_MARKER_END, starts[0]! + 1)
+    if (end === -1) {
+      findings.push({ id: 'gitignore', message: `${GITIGNORE_REL}'s adl managed block has no end marker — ${INSTALL_HINT}` })
+    } else {
+      const body = lines.slice(starts[0]! + 1, end)
+      const same = body.length === GITIGNORE_BLOCK_LINES.length && body.every((line, index) => line === GITIGNORE_BLOCK_LINES[index])
+      if (!same) findings.push({ id: 'gitignore', message: `${GITIGNORE_REL}'s adl managed block is stale — ${INSTALL_HINT}` })
+    }
+  }
+
+  return { repo: repoRoot, ok: findings.length === 0, findings }
+}

package/packages/repo-controls/src/hook-log.ts

@@ -0,0 +1,72 @@
+/**
+ * Bridges the bundled bash git-hook scripts (`scripts/hooks/lib/hook-log.sh`)
+ * to the one shared `.adl/logs/` JSON-Lines format every adl tool writes
+ * (docs/architecture/cli-design.md §5a, `agent-hooks/src/log/writer.ts`'s `writeLogEntry`).
+ *
+ * `adl repo controls log <hook> <reason> [<context> [<message>]]` (`src/cli.ts`)
+ * is the seam. A bash hook cannot import a TypeScript module, and the TS
+ * wrapper that DOES run first (`hook.ts`'s `runHook`, via `runBundled`) execs
+ * the bundled bash script with stdio `'inherit'` — so git's own real-time
+ * output reaches the terminal, but that also means the wrapper can never SEE
+ * the specific per-failure reason a hook prints to stderr (e.g. commit-msg's
+ * "type 'x' is not allowed"). Only the script itself knows that string, so it
+ * calls back into this same already-on-PATH binary to log it, rather than the
+ * wrapper trying to scrape it back out of output it never captures.
+ *
+ * BEHAVIOUR CHANGE (Tarun, 2026-09-27, §5a): this replaces two CSV files
+ * under `.enact/logs/` (`adl-repo-controls-{activity,deny}.log`) with the
+ * shared format's `.adl/logs/repo-controls.log` (every invocation) and
+ * `.adl/logs/hooks-deny.log` (FAIL rows only — shared with agent-hooks' own
+ * PreToolUse denies, so a human `git commit` denial and an agent's blocked
+ * shell command land in one timeline). `.enact/logs/` is a hard cut: this
+ * module never reads or writes it; whatever evidence is already there (see
+ * `constants.ts`'s `LOGS_ROOT_REL`) is left exactly where it is.
+ *
+ * Field mapping onto `LogEntryInput` (`../../agent-hooks/src/log/writer.ts`)
+ * — the old CSV's single `git:<hook>` label now lands in the schema's real
+ * fields (Tarun, 2026-09-28: host second with the host alone, tool_call
+ * third with the hook kind):
+ *   - `host` is the constant `'git'` — distinguishes a git-hook row from an
+ *     agent-hook row sharing the same files.
+ *   - `tool_call` is the hook name (`commit-msg`, `pre-commit`, ...),
+ *     unchanged from `hook_log_init`'s first argument.
+ *   - `event` is the hook name too, unchanged from `hook_log_init`'s first
+ *     argument.
+ *   - `decision` is the hook's own reason, verbatim: `PASS`, `FAIL exit=<n>`,
+ *     or a hook's specific `FAIL — <why>` (e.g. commit-msg's `reject()`) —
+ *     never re-derived or re-worded here.
+ *   - `command` is the hook's context when non-empty (commit-msg's subject;
+ *     every other hook's current branch, from `hook_log_init`'s second
+ *     argument). `writeLogEntry` redacts it before it reaches disk.
+ *   - `result` is the hook's free-text message when non-empty (e.g. "reason
+ *     printed to the terminal by the hook" for a bare exit-code failure with
+ *     no specific reason to report).
+ *   - `target` is left absent on git-hook rows: per §5a it is the Azure
+ *     DevOps target of a write, not a row label. (`run_id` is also unset
+ *     here — git hooks run outside an `adl run` child env.)
+ *
+ * Best-effort by construction, the same contract `hook-log.sh`'s CSV writer
+ * always had: `writeLogEntry` throwing is swallowed here rather than
+ * propagated, so a genuinely unwritable `.adl/logs/` can never change a git
+ * hook's exit code.
+ */
+import type { LogEntryInput } from '../../agent-hooks/src/log/writer.ts'
+import { writeLogEntry } from '../../agent-hooks/src/log/writer.ts'
+import type { HookName } from './constants.ts'
+
+export function logHookEvent(hook: HookName, reason: string, context: string, message: string, cwd: string): void {
+  const entry: LogEntryInput = {
+    host: 'git',
+    tool_call: hook,
+    event: hook,
+    decision: reason,
+    ...(context !== '' ? { command: context } : {}),
+    ...(message !== '' ? { result: message } : {}),
+  }
+  try {
+    writeLogEntry('repo-controls', entry, { cwd })
+    if (reason.startsWith('FAIL')) writeLogEntry('hooks-deny', entry, { cwd })
+  } catch {
+    // Best-effort: a log write must never change a git hook's outcome.
+  }
+}