buddy-agent-harness 0.5.0 → 0.7.0

package/src/diagnose-bridges/diagnose-bridges.ts

@@ -1,8 +1,10 @@
-import { lstatSync, readFileSync, readlinkSync, statSync } from 'node:fs'
-import { dirname, join, relative } from 'node:path'
-import { type Harness, type HarnessName, selectHarnesses } from '../harness-registry/harness-registry.ts'
+import { lstatSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { type HarnessName, selectHarnesses } from '../harness-registry/harness-registry.ts'
+import { linksTo } from '../skill-projection/skill-projection.ts'
+import { diagnoseInstructions, type InstructionReport } from './diagnose-instructions.ts'
 import { filesUnder } from './directory-files.ts'
-import { type BridgeProblem, repairFor } from './doctor-guidance.ts'
+import { type BridgeProblem, type DoctorProblem, type RepairAction, repairFor } from './doctor-guidance.ts'
 import { type DivergenceDirection, GitBridgeState } from './git-bridge-state.ts'
 
 export type BridgeKind = 'symlink' | 'copy' | 'file' | 'none'
@@ -18,9 +20,14 @@ export type BridgeReport = {
 
 export type BridgeFinding = {
 	path: string
+	/**
+	 * Which problem this is. Emitted so a caller routes on a name rather than by matching `detail`
+	 * prose, which would break the moment the wording is improved.
+	 */
+	problem: DoctorProblem
 	detail: string
-	/** The command that repairs this finding, already carrying the bridge path. */
-	repair: string
+	/** What repairs this finding, already carrying the bridge path. Empty `command` means judgment. */
+	repair: RepairAction
 }
 
 export type DivergenceReport = {
@@ -37,6 +44,11 @@ export type DiagnoseOptions = {
 
 export type DiagnoseResult = {
 	bridges: BridgeReport[]
+	/**
+	 * The instruction bridges into `AGENTS.md`, kept out of `bridges` on purpose: a different `kind`
+	 * and `status` vocabulary, and a repair that is the `init` skill rather than a command.
+	 */
+	instructions: InstructionReport[]
 	divergence: DivergenceReport[]
 	findings: BridgeFinding[]
 }
@@ -61,11 +73,6 @@ function isDirectory(path: string): boolean {
 	}
 }
 
-/** The same test `init` uses to decide a projection is already correct, plus that it still resolves. */
-function resolvesToCanonical(target: string, canonical: string): boolean {
-	return readlinkSync(target) === relative(dirname(target), canonical) && isDirectory(target)
-}
-
 function sameContent(left: string, right: string): boolean {
 	const leftFiles = filesUnder(left)
 	const rightFiles = filesUnder(right)
@@ -93,8 +100,10 @@ function inspect(target: string, path: string, canonical: string, git: GitBridge
 		// regular file holding the target path, and the harness silently loads nothing.
 		case 'file':
 			return { kind: 'file', status: 'degraded', problem: 'degraded' }
+		// The very test `init` uses to decide a projection is already correct, so a bridge `init` would
+		// leave alone never reports as one `doctor` wants rebuilt.
 		case 'symlink':
-			return resolvesToCanonical(target, canonical)
+			return linksTo(target, canonical)
 				? { kind: 'symlink', status: 'ok' }
 				: { kind: 'symlink', status: 'stale', problem: 'stale' }
 		default: {
@@ -112,16 +121,17 @@ function inspect(target: string, path: string, canonical: string, git: GitBridge
 }
 
 /**
- * Reports whether every bridge `init` would create for this repository still resolves into
- * `.agents/skills`. Read-only: nothing is created, moved, or repaired, so the caller decides what
- * to run from the repair each finding carries.
+ * Reports whether every bridge this repository needs still resolves: the skills bridges into
+ * `.agents/skills`, and the instruction bridges into `AGENTS.md`. Read-only: nothing is created,
+ * moved, or repaired, so the caller decides what to run from the repair each finding carries.
  */
 export function diagnoseBridges({ root, harnesses: preferred = [], cli }: DiagnoseOptions): DiagnoseResult {
 	const canonical = join(root, '.agents', 'skills')
 	const git = new GitBridgeState(root)
-	const bridged = selectHarnesses(root, preferred).filter((harness): harness is Harness & { skillsDirectory: string } =>
-		Boolean(harness.skillsDirectory),
-	)
+	const selected = selectHarnesses(root, preferred)
+	const bridged = selected
+		.map((harness) => ({ name: harness.name, skillsDirectory: harness.project.skillsDirectory }))
+		.filter((harness): harness is { name: HarnessName; skillsDirectory: string } => Boolean(harness.skillsDirectory))
 
 	const bridges: BridgeReport[] = []
 	const divergence: DivergenceReport[] = []
@@ -129,7 +139,12 @@ export function diagnoseBridges({ root, harnesses: preferred = [], cli }: Diagno
 
 	if (!isDirectory(canonical)) {
 		const { detail, repair } = repairFor('no-canonical')
-		findings.push({ path: canonicalPath, detail, repair: repair(canonicalPath, cli) })
+		findings.push({
+			path: canonicalPath,
+			problem: 'no-canonical',
+			detail,
+			repair: repair({ file: canonicalPath }, cli),
+		})
 	}
 
 	for (const harness of bridged) {
@@ -139,9 +154,12 @@ export function diagnoseBridges({ root, harnesses: preferred = [], cli }: Diagno
 		if (inspection.direction) divergence.push({ path, direction: inspection.direction })
 		if (inspection.problem) {
 			const { detail, repair } = repairFor(inspection.problem)
-			findings.push({ path, detail, repair: repair(path, cli) })
+			findings.push({ path, problem: inspection.problem, detail, repair: repair({ file: path }, cli) })
 		}
 	}
 
-	return { bridges, divergence, findings }
+	const instructions = diagnoseInstructions(root, selected, cli)
+	findings.push(...instructions.findings)
+
+	return { bridges, instructions: instructions.instructions, divergence, findings }
 }

package/src/diagnose-bridges/diagnose-instructions.ts

@@ -0,0 +1,145 @@
+import { lstatSync, readFileSync, readlinkSync } from 'node:fs'
+import { join, posix } from 'node:path'
+import type { Harness, HarnessName } from '../harness-registry/harness-registry.ts'
+import type { InstructionBridge } from '../harness-registry/instruction-bridge.ts'
+import { agentsFileDirectories } from './agents-files.ts'
+import type { BridgeFinding } from './diagnose-bridges.ts'
+import { type InstructionProblem, repairFor } from './doctor-guidance.ts'
+import { parseJsonWithComments } from './json-with-comments.ts'
+
+/** What is on disk where an instruction bridge belongs. */
+export type InstructionKind = 'import' | 'symlink' | 'settings-entry' | 'file' | 'none'
+/**
+ * `unbridged` is the case a skills bridge has no equivalent of: the file is there, so nothing looks
+ * wrong, and it names `AGENTS.md` nowhere — a `CLAUDE.md` overwritten with real content, or a
+ * settings file another tool rewrote.
+ */
+export type InstructionStatus = 'ok' | 'missing' | 'unbridged' | 'unreadable'
+
+export type InstructionReport = {
+	harness: HarnessName
+	/** Repository-relative path of the file that carries the bridge. */
+	path: string
+	kind: InstructionKind
+	status: InstructionStatus
+}
+
+export const canonicalInstructions = 'AGENTS.md'
+
+type Inspection = {
+	kind: InstructionKind
+	status: InstructionStatus
+	problem?: InstructionProblem
+}
+
+/**
+ * An import bridges the `AGENTS.md` beside it and nothing else, so the check is per directory
+ * holding one rather than per harness. A line of its own is enough: the harness reference allows
+ * Claude-specific notes below the import, and a file that carries the import plus notes still
+ * bridges.
+ */
+function inspectImport(target: string): Inspection {
+	let stats: ReturnType<typeof lstatSync>
+	try {
+		stats = lstatSync(target)
+	} catch {
+		return { kind: 'none', status: 'missing', problem: 'instructions-missing' }
+	}
+
+	if (stats.isSymbolicLink()) {
+		return readlinkSync(target) === canonicalInstructions
+			? { kind: 'symlink', status: 'ok' }
+			: { kind: 'symlink', status: 'unbridged', problem: 'instructions-unbridged' }
+	}
+
+	const imported = readFileSync(target, 'utf8')
+		.split('\n')
+		.some((line) => line.trim() === `@${canonicalInstructions}`)
+	return imported
+		? { kind: 'import', status: 'ok' }
+		: { kind: 'file', status: 'unbridged', problem: 'instructions-unbridged' }
+}
+
+/** Reads a dotted key out of parsed JSON without asserting anything about the rest of the file. */
+function valueAt(settings: unknown, key: string): unknown {
+	return key.split('.').reduce<unknown>((value, segment) => {
+		if (typeof value !== 'object' || value === null) return undefined
+		return (value as Record<string, unknown>)[segment]
+	}, settings)
+}
+
+function inspectSettingsEntry(target: string, key: string): Inspection {
+	let source: string
+	try {
+		source = readFileSync(target, 'utf8')
+	} catch {
+		return { kind: 'none', status: 'missing', problem: 'instructions-missing' }
+	}
+
+	const settings = parseJsonWithComments(source)
+	if (settings === undefined) return { kind: 'file', status: 'unreadable', problem: 'instructions-unreadable' }
+
+	const entry = valueAt(settings, key)
+	return Array.isArray(entry) && entry.includes(canonicalInstructions)
+		? { kind: 'settings-entry', status: 'ok' }
+		: { kind: 'file', status: 'unbridged', problem: 'instructions-unbridged' }
+}
+
+/** Every path an instruction bridge of this kind belongs at, in report order. */
+function pathsFor(root: string, bridge: InstructionBridge): string[] {
+	if (bridge.kind !== 'import') return [bridge.path]
+	return agentsFileDirectories(root).map((directory) => (directory ? posix.join(directory, bridge.path) : bridge.path))
+}
+
+function inspect(target: string, bridge: InstructionBridge): Inspection {
+	return bridge.kind === 'import' ? inspectImport(target) : inspectSettingsEntry(target, bridge.key)
+}
+
+/**
+ * Reports whether every enabled harness can still read `AGENTS.md`.
+ *
+ * Losing one of these is quieter than losing a skills bridge and costs more: a harness with no
+ * instruction bridge reads none of the repository's instructions, and says nothing about it. The
+ * checks are read-only, and no repair is a command — rewriting an instruction file is the `init`
+ * skill's judgment.
+ */
+export function diagnoseInstructions(
+	root: string,
+	harnesses: readonly Harness[],
+	cli: string,
+): { instructions: InstructionReport[]; findings: BridgeFinding[] } {
+	// Project scope only: `doctor` diagnoses a repository, and the user-scope bridges are neither
+	// written nor read by this tool.
+	const bridged = harnesses
+		.map((harness) => ({ name: harness.name, bridge: harness.project.instructionBridge }))
+		.filter((harness): harness is { name: HarnessName; bridge: InstructionBridge } => Boolean(harness.bridge))
+
+	const instructions: InstructionReport[] = []
+	const findings: BridgeFinding[] = []
+	if (!bridged.length) return { instructions, findings }
+
+	// Only reported when something bridges into it. Every other harness reads `AGENTS.md` where it
+	// lies, so its absence is a repository that has not run `init` rather than a broken bridge.
+	if (!agentsFileDirectories(root).includes('')) {
+		const { detail, repair } = repairFor('no-instructions')
+		findings.push({
+			path: canonicalInstructions,
+			problem: 'no-instructions',
+			detail,
+			repair: repair({ file: canonicalInstructions }, cli),
+		})
+	}
+
+	for (const { name, bridge } of bridged) {
+		for (const path of pathsFor(root, bridge)) {
+			const inspection = inspect(join(root, path), bridge)
+			instructions.push({ harness: name, path, kind: inspection.kind, status: inspection.status })
+			if (inspection.problem) {
+				const { detail, repair } = repairFor(inspection.problem)
+				findings.push({ path, problem: inspection.problem, detail, repair: repair({ file: path }, cli) })
+			}
+		}
+	}
+
+	return { instructions, findings }
+}