buddy-agent-harness 0.6.0 → 0.8.0

package/src/dep-plugins/resolve.ts

@@ -0,0 +1,117 @@
+/**
+ * Locating a declared dependency on disk, and reading the plugin manifest it may ship.
+ *
+ * Resolution rather than scanning. Walking `node_modules` finds transitive dependencies nobody
+ * vetted, and a skill or plugin is instruction text that steers an agent — an unvetted transitive
+ * dependency is a supply-chain surface, not a convenience. Asking the module resolver where a
+ * *declared* dependency lives answers the question that was actually asked, and it is correct under
+ * npm, pnpm, yarn with the node-modules linker, and bun alike, because all four put a real directory
+ * on disk. Only Yarn PnP does not, and it is reported rather than guessed at.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import type { DepPlugin } from './dep-plugins.ts'
+
+/** Why a declared dependency yielded no plugin, when the caller needs to explain itself. */
+export type SkipReason = 'unresolved' | 'no-manifest' | 'unnamed'
+
+export type ResolveOutcome = { ok: true; plugin: DepPlugin } | { ok: false; package: string; reason: SkipReason }
+
+function readJson(path: string): unknown {
+	try {
+		return JSON.parse(readFileSync(path, 'utf8'))
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * Every ancestor `node_modules/<pkg>` from `startDir` upward. The fallback path only — see
+ * {@link packageDir}.
+ */
+function ancestorCandidates(startDir: string, pkg: string): string[] {
+	const segments = pkg.split('/')
+	const candidates: string[] = []
+	let dir = startDir
+	for (;;) {
+		candidates.push(join(dir, 'node_modules', ...segments))
+		const parent = dirname(dir)
+		if (parent === dir) break
+		dir = parent
+	}
+	return candidates
+}
+
+/**
+ * The directory a declared dependency was installed into, or `undefined`.
+ *
+ * Two mechanisms, in order, because neither alone is sufficient:
+ *
+ * 1. **`require.resolve('<pkg>/package.json')`, anchored at the declaring manifest.** The anchor
+ *    matters: under pnpm's isolated store only the package that declares a dependency can resolve it,
+ *    so resolving from a workspace root would miss what a workspace member declared.
+ * 2. **A walk up `node_modules`.** Roughly one package in seven declares an `exports` map without a
+ *    `./package.json` entry, and those refuse the first mechanism with `ERR_PACKAGE_PATH_NOT_EXPORTED`
+ *    however plainly they are installed. Resolving a deeper file instead is not an escape — the same
+ *    map blocks that too.
+ */
+export function packageDir(pkg: string, fromManifest: string): string | undefined {
+	try {
+		const require = createRequire(fromManifest)
+		return dirname(require.resolve(`${pkg}/package.json`))
+	} catch {
+		// fall through to the walk
+	}
+	for (const candidate of ancestorCandidates(dirname(fromManifest), pkg)) {
+		if (existsSync(join(candidate, 'package.json'))) return candidate
+	}
+	return undefined
+}
+
+/**
+ * Reads the plugin a dependency ships, if it ships one.
+ *
+ * The version comes from the dependency's own `package.json` rather than from a lockfile. It is the
+ * same number — the version actually installed — and reading it needs no knowledge of which of the
+ * four lockfile formats this repository uses.
+ *
+ * A manifest at the package root is what the Agent Plugins Specification pins, and it is the form a
+ * harness accepts as a marketplace source without any vendor-specific manifest alongside it.
+ */
+export function readDepPlugin(pkg: string, fromManifest: string): ResolveOutcome {
+	const dir = packageDir(pkg, fromManifest)
+	if (!dir) return { ok: false, package: pkg, reason: 'unresolved' }
+
+	const manifest = readJson(join(dir, 'plugin.json'))
+	if (!manifest || typeof manifest !== 'object') return { ok: false, package: pkg, reason: 'no-manifest' }
+
+	const record = manifest as Record<string, unknown>
+	const name = typeof record['name'] === 'string' ? record['name'] : undefined
+	if (!name) return { ok: false, package: pkg, reason: 'unnamed' }
+
+	// The installed version, not the manifest's: the catalog installs the package from npm, so the
+	// number that must match is the one npm published the tree under.
+	const installed = readJson(join(dir, 'package.json')) as { version?: unknown } | undefined
+	const version = typeof installed?.version === 'string' ? installed.version : undefined
+	if (!version) return { ok: false, package: pkg, reason: 'no-manifest' }
+
+	const description = typeof record['description'] === 'string' ? record['description'] : undefined
+	return {
+		ok: true,
+		plugin: description
+			? { package: pkg, plugin: name, version, description }
+			: { package: pkg, plugin: name, version },
+	}
+}
+
+/**
+ * True when the process is running under Yarn's Plug'n'Play resolver, where packages live inside zip
+ * archives rather than as directories. A marketplace source must be a real directory and an npm
+ * source must be installable, so a PnP project needs `nodeLinker: node-modules` or the affected
+ * dependencies unplugged. Detected rather than worked around, so the report can say so.
+ */
+export function isPnp(): boolean {
+	return Boolean((process.versions as Record<string, string | undefined>)['pnp'])
+}

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

@@ -1,9 +1,10 @@
-import { lstatSync, readFileSync, readlinkSync, statSync } from 'node:fs'
-import { dirname, join, relative } from 'node:path'
+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'
@@ -19,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 = {
@@ -67,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)
@@ -99,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: {
@@ -136,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) {
@@ -146,7 +154,7 @@ 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) })
 		}
 	}
 

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

@@ -122,7 +122,12 @@ export function diagnoseInstructions(
 	// 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, detail, repair: repair(canonicalInstructions, cli) })
+		findings.push({
+			path: canonicalInstructions,
+			problem: 'no-instructions',
+			detail,
+			repair: repair({ file: canonicalInstructions }, cli),
+		})
 	}
 
 	for (const { name, bridge } of bridged) {
@@ -131,7 +136,7 @@ export function diagnoseInstructions(
 			instructions.push({ harness: name, path, kind: inspection.kind, status: inspection.status })
 			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) })
 			}
 		}
 	}