@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.7 → 0.1.9

package/packages/agent-hooks/src/deploy/deploy.ts

@@ -15,7 +15,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { renderOpencodePlugin } from './opencode-template.ts'
-import { mergeCursorHooksFile, mergeJsonHooksFile } from './json-merge.ts'
+import { type AmbiguousPairConflict, mergeCursorHooksFile, mergeJsonHooksFile, type RestoredHook } from './json-merge.ts'
 import {
   legacyFileHash,
   type LegacyLockDoc,
@@ -37,6 +37,18 @@ export interface DeployHooksOptions {
   readonly profile?: HookDeployProfile
   /** Defaults to loading `profile.source` relative to `dirname(assetsDir)`. */
   readonly hooksDoc?: CanonicalHooksDoc
+  /**
+   * Computes the exact same written/unchanged/conflicts result WITHOUT
+   * writing anything — not the target files, not the lock, not the legacy
+   * lock (independent review, 2026-09-29: `adl install --dry-run` used to
+   * run this for real against a throwaway `cpSync` sandbox instead, which
+   * risked rewriting symlinks to absolute paths, copying `node_modules`,
+   * and touching a worktree's real `.git`; a real plan mode has none of
+   * that). Every filesystem WRITE below is gated on `!dryRun`; every READ
+   * (existing file content, the current lock) still runs for real, since
+   * an accurate plan needs the real current state.
+   */
+  readonly dryRun?: boolean
 }
 
 export interface HookConflict {
@@ -44,11 +56,41 @@ export interface HookConflict {
   readonly reason: string
 }
 
+/** One hook healed via the PAIR fallback (not hash, not the legacy channel) this run — see json-merge.ts's `RestoredHook` for the full rationale (2026-09-30, round 5, finding 2). */
+export interface RestoredHookReport {
+  readonly file: string
+  readonly event: string
+  readonly command: string
+  readonly matcher?: string
+}
+
+function makeRestoredReport(file: string, hook: RestoredHook & { readonly event: string }): RestoredHookReport {
+  return hook.matcher !== undefined ? { file, event: hook.event, command: hook.command, matcher: hook.matcher } : { file, event: hook.event, command: hook.command }
+}
+
+function ambiguousConflictReason(c: AmbiguousPairConflict): string {
+  const matcherPart = c.matcher !== undefined ? ` (matcher "${c.matcher}")` : ' (no matcher)'
+  return `ambiguous duplicate adl-owned hook in event '${c.event}': more than one unverified candidate for "${c.command}"${matcherPart}; neither healed, left untouched — resolve by hand`
+}
+
 export interface DeployHooksResult {
   readonly written: readonly string[]
   readonly unchanged: readonly string[]
   readonly conflicts: readonly HookConflict[]
   readonly lockPath: string
+  /**
+   * Surface files whose lock entry moved from the legacy
+   * (`ownedCommands`-only) shape to the content-addressed one
+   * (`ownedEntries`) on THIS run (independent review, 2026-09-30, finding
+   * 7). This can be non-empty even when the surface's own `written`/
+   * `unchanged` outcome looks like nothing happened — the deployed JSON
+   * file can stay byte-identical while the LOCK itself is rewritten, and
+   * that rewrite deserves its own truthful line in the CLI's output
+   * rather than being folded silently into "unchanged".
+   */
+  readonly lockMigrated: readonly string[]
+  /** Hooks healed via the pair fallback this run, named explicitly (round 5, finding 2) so deploy's own output, doctor's preview, and `adl install` can all say "restored adl hook <event>/<matcher>/<command> — local changes to it were replaced". */
+  readonly restored: readonly RestoredHookReport[]
 }
 
 function readExistingJson(path: string): Record<string, unknown> | undefined {
@@ -65,14 +107,15 @@ function readExistingJson(path: string): Record<string, unknown> | undefined {
   return doc as Record<string, unknown>
 }
 
-function writeJsonIfChanged(path: string, content: Record<string, unknown>, changed: boolean): void {
-  if (!changed) return
+function writeJsonIfChanged(path: string, content: Record<string, unknown>, changed: boolean, dryRun: boolean): void {
+  if (!changed || dryRun) return
   mkdirSync(dirname(path), { recursive: true })
   writeFileSync(path, `${JSON.stringify(content, null, 2)}\n`)
 }
 
 export function deployHooks(options: DeployHooksOptions): DeployHooksResult {
   const { assetsDir, targetRepo } = options
+  const dryRun = options.dryRun === true
 
   if (!existsSync(assetsDir) || !statSync(assetsDir).isDirectory()) {
     throw new Error(`agent-hooks assets directory not found: ${assetsDir}`)
@@ -91,19 +134,21 @@ export function deployHooks(options: DeployHooksOptions): DeployHooksResult {
   const written: string[] = []
   const unchanged: string[] = []
   const conflicts: HookConflict[] = []
+  const lockMigrated: string[] = []
+  const restored: RestoredHookReport[] = []
   const takeover = { any: false }
 
   for (const surface of profile.surfaces) {
-    deploySurface(surface, { assetsDir, targetRepo, hooksDoc, lock, legacyDoc, takeover, newEntries, written, unchanged, conflicts })
+    deploySurface(surface, { assetsDir, targetRepo, hooksDoc, lock, legacyDoc, takeover, newEntries, written, unchanged, conflicts, lockMigrated, restored, dryRun })
   }
 
-  writeLock(targetRepo, { version: 1, entries: newEntries })
+  if (!dryRun) writeLock(targetRepo, { version: 1, entries: newEntries })
 
   // Once anything was actually taken over, this package's own bookkeeping in
   // the legacy lock is stale — ownership has fully moved to the lock just
   // written above. A legacy lock present but untouched by any takeover (no
   // hash matched, or this repo never had one) is left exactly as found.
-  if (takeover.any && legacyDoc !== undefined && legacyLockPath !== undefined) {
+  if (!dryRun && takeover.any && legacyDoc !== undefined && legacyLockPath !== undefined) {
     const opencodeSurface = profile.surfaces.find((s) => s.format === 'opencode-plugin')
     if (opencodeSurface !== undefined) stripLegacyOwnership(legacyDoc, legacyLockPath, opencodeSurface.file)
   }
@@ -113,6 +158,8 @@ export function deployHooks(options: DeployHooksOptions): DeployHooksResult {
     unchanged: unchanged.sort(),
     conflicts: conflicts.sort((a, b) => a.file.localeCompare(b.file)),
     lockPath: lockPathFor(targetRepo),
+    lockMigrated: lockMigrated.sort(),
+    restored,
   }
 }
 
@@ -129,6 +176,9 @@ interface DeploySurfaceContext {
   readonly written: string[]
   readonly unchanged: string[]
   readonly conflicts: HookConflict[]
+  readonly lockMigrated: string[]
+  readonly restored: RestoredHookReport[]
+  readonly dryRun: boolean
 }
 
 function deploySurface(surface: HookSurface, ctx: DeploySurfaceContext): void {
@@ -147,8 +197,10 @@ function deploySurface(surface: HookSurface, ctx: DeploySurfaceContext): void {
     const rendered = renderOpencodePlugin({ assetsDir: ctx.assetsDir, surface, hooksDoc: ctx.hooksDoc })
     const changed = !exists || readFileSync(targetAbs, 'utf8') !== rendered
     if (changed) {
-      mkdirSync(dirname(targetAbs), { recursive: true })
-      writeFileSync(targetAbs, rendered)
+      if (!ctx.dryRun) {
+        mkdirSync(dirname(targetAbs), { recursive: true })
+        writeFileSync(targetAbs, rendered)
+      }
       ctx.written.push(surface.file)
     } else {
       ctx.unchanged.push(surface.file)
@@ -157,25 +209,53 @@ function deploySurface(surface: HookSurface, ctx: DeploySurfaceContext): void {
     return
   }
 
-  const ownOwned = prevEntry !== undefined && prevEntry.format === surface.format ? prevEntry.ownedCommands : {}
+  // Ownership is content-addressed (json-merge.ts's own header, second
+  // independent review 2026-09-29): `recordedEntries` is THIS package's own
+  // prior write, read straight from the lock as hash+command pairs, never
+  // derived from command text alone. A lock with no `ownedEntries` at all
+  // (every repo enrolled before this fix) has no hashes to give — for
+  // exactly this one transitional deploy, its OLD `ownedCommands` feeds the
+  // command-anywhere fallback channel instead, unioned with
+  // `legacyTakeover.ownedByEvent` (the pre-agent-hooks engine's own
+  // hash-verified takeover signal — a different legacy source, same
+  // "command text is the only proof we have" shape).
+  const sameFormatPrev = prevEntry !== undefined && prevEntry.format === surface.format ? prevEntry : undefined
+  const isLegacyShapedLock = sameFormatPrev !== undefined && sameFormatPrev.ownedEntries === undefined
+  // Independent review, 2026-09-30, finding 7: this transitional deploy
+  // rewrites the LOCK from the legacy (`ownedCommands`-only) shape to the
+  // content-addressed one — report it, since the deployed JSON file can
+  // stay byte-identical while that rewrite happens underneath it.
+  if (isLegacyShapedLock) ctx.lockMigrated.push(surface.file)
+  const recordedEntries = sameFormatPrev?.ownedEntries ?? {}
+  const ownCommandsLegacyFallback = isLegacyShapedLock ? sameFormatPrev.ownedCommands : {}
   const existingRaw = readExistingJson(targetAbs)
   const legacyTakeover = legacyTakeoverForJsonHooksSurface(existingRaw, ctx.legacyDoc, surface.file)
   if (legacyTakeover.matched) ctx.takeover.any = true
-  const previousOwned = unionOwnedCommands(ownOwned, legacyTakeover.ownedByEvent)
+  const legacyCommandsAnywhere = unionOwnedCommands(ownCommandsLegacyFallback, legacyTakeover.ownedByEvent)
 
   if (surface.format === 'cursor-hooks-v1') {
     const desired = renderCursorEntries(ctx.hooksDoc, surface)
-    const { fileContent, ownedCommands, changed } = mergeCursorHooksFile(existingRaw, desired, previousOwned)
-    writeJsonIfChanged(targetAbs, fileContent, changed)
-    ;(changed ? ctx.written : ctx.unchanged).push(surface.file)
-    ctx.newEntries[surface.file] = { format: 'cursor-hooks-v1', ownedCommands }
+    const { fileContent, ownedCommands, ownedEntries, changed, restored, ambiguousConflicts } = mergeCursorHooksFile(existingRaw, desired, recordedEntries, legacyCommandsAnywhere)
+    writeJsonIfChanged(targetAbs, fileContent, changed, ctx.dryRun)
+    // Independent review, 2026-09-30, round 5, finding 4: a legacy lock
+    // migration rewrites the LOCK for real even when this surface's own
+    // deployed content stays byte-identical — count that as "written",
+    // not "unchanged", so a caller reading these two arrays (which is
+    // exactly what "up to date (no changes)" and "written: N" do) never
+    // reports a pure no-op when something real did change on disk.
+    ;(changed || isLegacyShapedLock ? ctx.written : ctx.unchanged).push(surface.file)
+    ctx.newEntries[surface.file] = { format: 'cursor-hooks-v1', ownedCommands, ownedEntries }
+    for (const hook of restored) ctx.restored.push(makeRestoredReport(surface.file, hook))
+    for (const conflict of ambiguousConflicts) ctx.conflicts.push({ file: surface.file, reason: ambiguousConflictReason(conflict) })
     return
   }
 
   // claude-settings | codex-hooks
   const desired = renderJsonHooksGroups(ctx.hooksDoc, surface)
-  const { fileContent, ownedCommands, changed } = mergeJsonHooksFile(existingRaw, desired, previousOwned)
-  writeJsonIfChanged(targetAbs, fileContent, changed)
-  ;(changed ? ctx.written : ctx.unchanged).push(surface.file)
-  ctx.newEntries[surface.file] = { format: surface.format, ownedCommands }
+  const { fileContent, ownedCommands, ownedEntries, changed, restored, ambiguousConflicts } = mergeJsonHooksFile(existingRaw, desired, recordedEntries, legacyCommandsAnywhere)
+  writeJsonIfChanged(targetAbs, fileContent, changed, ctx.dryRun)
+  ;(changed || isLegacyShapedLock ? ctx.written : ctx.unchanged).push(surface.file)
+  ctx.newEntries[surface.file] = { format: surface.format, ownedCommands, ownedEntries }
+  for (const hook of restored) ctx.restored.push(makeRestoredReport(surface.file, hook))
+  for (const conflict of ambiguousConflicts) ctx.conflicts.push({ file: surface.file, reason: ambiguousConflictReason(conflict) })
 }

package/packages/agent-hooks/src/deploy/doctor.ts

@@ -17,7 +17,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { mergeCursorHooksFile, mergeJsonHooksFile } from './json-merge.ts'
-import { readLock } from './lock.ts'
+import { type JsonHooksLockEntry, readLock } from './lock.ts'
 import { renderOpencodePlugin } from './opencode-template.ts'
 import {
   DEFAULT_PROFILE_PATH,
@@ -70,7 +70,14 @@ function readExistingJson(path: string): Record<string, unknown> | undefined {
 function doctorJsonSurface(surface: HookSurface, targetRepo: string, hooksDoc: CanonicalHooksDoc, lock: ReturnType<typeof readLock>): DoctorIssue[] {
   const targetAbs = join(targetRepo, surface.file)
   const exists = existsSync(targetAbs)
-  const previousOwned = lock.entries[surface.file]?.format === surface.format ? (lock.entries[surface.file] as { ownedCommands: Record<string, readonly string[]> }).ownedCommands : {}
+  const lockEntry = lock.entries[surface.file]?.format === surface.format ? (lock.entries[surface.file] as JsonHooksLockEntry) : undefined
+  // Same fallback deploy.ts itself uses: a lock with no ownedEntries at all
+  // (every repo enrolled before the content-hash fix) has no hashes to
+  // give, so its OLD ownedCommands feeds the command-anywhere channel
+  // instead -- otherwise doctor would report drift for every currently-
+  // enrolled repo's untouched content that deploy itself recognizes fine.
+  const recordedEntries = lockEntry?.ownedEntries ?? {}
+  const legacyCommandsAnywhere = lockEntry !== undefined && lockEntry.ownedEntries === undefined ? lockEntry.ownedCommands : {}
 
   let parseFailed = false
   if (exists) {
@@ -85,21 +92,64 @@ function doctorJsonSurface(surface: HookSurface, targetRepo: string, hooksDoc: C
   const existingRaw = readExistingJson(targetAbs)
   const merged =
     surface.format === 'cursor-hooks-v1'
-      ? mergeCursorHooksFile(existingRaw, renderCursorEntries(hooksDoc, surface), previousOwned)
-      : mergeJsonHooksFile(existingRaw, renderJsonHooksGroups(hooksDoc, surface), previousOwned)
+      ? mergeCursorHooksFile(existingRaw, renderCursorEntries(hooksDoc, surface), recordedEntries, legacyCommandsAnywhere)
+      : mergeJsonHooksFile(existingRaw, renderJsonHooksGroups(hooksDoc, surface), recordedEntries, legacyCommandsAnywhere)
 
   if (!exists) {
     return [{ severity: 'error', path: surface.file, reason: 'expected hook wiring has not been deployed' }]
   }
-  if (!merged.changed) return []
-  return merged.changedEvents.map((event) => ({
+  // Independent review, 2026-09-30, round 5 (finding 1, pair-scoped —
+  // never flags a same-command entry under a different matcher): a
+  // duplicated adl-owned (command, matcher) pair can sit in the file
+  // even when the merge is otherwise a structural no-op (the duplicate
+  // isn't healed into the verified original, but it also isn't
+  // restructured — nothing else changes), so this check runs
+  // UNCONDITIONALLY, never gated behind `merged.changed`.
+  const duplicateIssues: DoctorIssue[] = Object.entries(merged.duplicateCommands).flatMap(([event, commands]) =>
+    commands.map((command) => ({
+      severity: 'error' as const,
+      path: `${surface.file}#${event}`,
+      reason: `adl-owned command appears more than once (a duplicate, not a self-heal): ${command} — the hook runs twice; deploy does not remove a user's copy, so remove the extra copy by hand`,
+    })),
+  )
+  // Round 5, finding 2: more than one unverified candidate for a pair is
+  // ambiguous — deploy heals neither, so this is ALSO unconditional
+  // (never gated behind `merged.changed`, since a frozen event by
+  // definition never registers as changed).
+  const ambiguousIssues: DoctorIssue[] = merged.ambiguousConflicts.map((conflict) => ({
     severity: 'error' as const,
-    path: `${surface.file}#${event}`,
-    reason:
-      previousOwned[event] !== undefined
-        ? 'deploy-written hook entries were modified since deploy, or assets/hooks.json changed since; run deploy to update'
-        : 'expected hook wiring for this event has not been deployed',
+    path: `${surface.file}#${conflict.event}`,
+    reason: `two unverified copies of this adl-owned hook exist (ambiguous — matcher ${conflict.matcher ?? 'none'}, command "${conflict.command}"); deploy will not choose one for you, resolve by hand`,
   }))
+  if (!merged.changed) return [...duplicateIssues, ...ambiguousIssues]
+  // Round 5, finding 2: when a heal is about to happen (not just "some
+  // drift"), doctor's own PREVIEW names exactly what would be restored —
+  // "restored adl hook <event>/<matcher>/<command>" — instead of the
+  // generic "modified since deploy" wording, matching what deploy's own
+  // output and `adl install` will say.
+  const restoredByEvent = new Map(merged.restored.map((r) => [r.event, r] as const))
+  return [
+    ...duplicateIssues,
+    ...ambiguousIssues,
+    ...merged.changedEvents.map((event) => {
+      const restoredHere = restoredByEvent.get(event)
+      if (restoredHere !== undefined) {
+        return {
+          severity: 'error' as const,
+          path: `${surface.file}#${event}`,
+          reason: `restored adl hook ${event}/${restoredHere.matcher ?? '-'}/${restoredHere.command} — local changes to it were replaced; run deploy to apply`,
+        }
+      }
+      return {
+        severity: 'error' as const,
+        path: `${surface.file}#${event}`,
+        reason:
+          recordedEntries[event] !== undefined || legacyCommandsAnywhere[event] !== undefined
+            ? 'deploy-written hook entries were modified since deploy, or assets/hooks.json changed since; run deploy to update'
+            : 'expected hook wiring for this event has not been deployed',
+      }
+    }),
+  ]
 }
 
 function doctorOpencodeSurface(surface: HookSurface, ctx: { assetsDir: string; targetRepo: string; hooksDoc: CanonicalHooksDoc; lock: ReturnType<typeof readLock> }): DoctorIssue[] {