buddy-agent-harness 0.7.0 → 0.9.0

package/src/dep-plugins/generate.ts

@@ -0,0 +1,115 @@
+/**
+ * Deriving a repository's dependency-plugin catalog, and deciding whether what is on disk matches.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import {
+	buildCatalog,
+	type Catalog,
+	type DepPlugin,
+	declaredDependencies,
+	isGenericName,
+	marketplaceName,
+	serializeCatalog,
+} from './dep-plugins.ts'
+import { isPnp, readDepPlugin, type SkipReason } from './resolve.ts'
+
+/**
+ * The catalog's home, relative to the repository root.
+ *
+ * Under this tool's own directory, beside the other files it owns there — the same place as
+ * `mcp.toml` and `mcp.projected.json`, and the same shape as `.agents/repobuddy/` and
+ * `.agents/cyberlegion/`. A directory named for what it holds rather than for who writes it would be
+ * a second convention in a tree that already has one.
+ *
+ * Not the repository root's `.claude-plugin/`, which is where a repository publishes its *own*
+ * plugins for its *own* consumers. Merging the two would leak every dependency-provided plugin into
+ * what a consumer sees on adding the published marketplace, and no harness has a notion of a private
+ * catalog entry to prevent that. Being a separate directory also makes this one a marketplace root
+ * in its own right, which is what lets its entries be resolved without reaching outside it.
+ */
+export const CATALOG_DIR: string = join('.agents', 'buddy-agent-harness')
+export const CATALOG_PATH: string = join(CATALOG_DIR, '.claude-plugin', 'marketplace.json')
+
+/** A declared dependency that yielded no plugin, kept so a report can say why rather than go quiet. */
+export type Skipped = { package: string; reason: SkipReason }
+
+export type DerivedCatalog = {
+	catalog: Catalog
+	plugins: DepPlugin[]
+	/** Only the dependencies that failed to resolve at all; a dependency with no plugin is not news. */
+	unresolved: Skipped[]
+	/** Set when the marketplace name is one two repositories are likely to share. */
+	genericName: boolean
+	/** Set under Yarn PnP, where no dependency has a directory for a harness to install from. */
+	pnp: boolean
+}
+
+function readManifest(path: string): Record<string, unknown> {
+	return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>
+}
+
+/**
+ * Derives the catalog from the repository's declared dependencies.
+ *
+ * Derived in full every time. A plugin newly added to `package.json` appears, one removed disappears,
+ * and a version that moved follows — all three without a line of reconciliation logic, because there
+ * is nothing to reconcile against. That is the same rule the vendor manifests already follow: the
+ * artifact is derived, never authored.
+ */
+export function deriveCatalog(root: string): DerivedCatalog {
+	const manifestPath = join(root, 'package.json')
+	const manifest = readManifest(manifestPath)
+
+	const plugins: DepPlugin[] = []
+	const unresolved: Skipped[] = []
+	for (const pkg of declaredDependencies(manifest)) {
+		const outcome = readDepPlugin(pkg, manifestPath)
+		if (outcome.ok) plugins.push(outcome.plugin)
+		else if (outcome.reason === 'unresolved') unresolved.push({ package: pkg, reason: outcome.reason })
+	}
+
+	const owner = typeof manifest['name'] === 'string' ? manifest['name'] : 'unknown'
+	const name = marketplaceName(owner)
+
+	return {
+		catalog: buildCatalog({ name, owner, plugins }),
+		plugins,
+		unresolved,
+		genericName: isGenericName(name),
+		pnp: isPnp(),
+	}
+}
+
+/** What a write did, or would do, so a caller can report a no-op as a no-op rather than as a change. */
+export type WriteOutcome = 'created' | 'updated' | 'unchanged'
+
+/**
+ * What writing the catalog would do, without touching the disk.
+ *
+ * Comparing the serialized form rather than the parsed one is deliberate: a byte comparison is what
+ * lets a check mode be a comparison instead of an interpretation, and `buildCatalog` sorts its
+ * entries so that unchanged inputs serialize identically.
+ */
+export function catalogStatus(root: string, catalog: Catalog): WriteOutcome {
+	let current: string | undefined
+	try {
+		current = readFileSync(join(root, CATALOG_PATH), 'utf8')
+	} catch {
+		current = undefined
+	}
+	if (current === serializeCatalog(catalog)) return 'unchanged'
+	return current === undefined ? 'created' : 'updated'
+}
+
+/** Writes the catalog, reporting whether it moved. A write that would change nothing writes nothing. */
+export function writeCatalog(root: string, catalog: Catalog): WriteOutcome {
+	const outcome = catalogStatus(root, catalog)
+	if (outcome === 'unchanged') return outcome
+
+	const path = join(root, CATALOG_PATH)
+	mkdirSync(dirname(path), { recursive: true })
+	writeFileSync(path, serializeCatalog(catalog))
+	return outcome
+}

package/src/dep-plugins/harness-plugins.ts

@@ -0,0 +1,232 @@
+/**
+ * What each harness does with a marketplace catalog, and how to read what it currently has.
+ *
+ * The runtimes diverge more than they look, and every difference below was established by running
+ * the shipped CLI rather than by reading a document:
+ *
+ * - **Claude Code** refreshes with `plugin update`; re-running `plugin install` is a no-op that
+ *   reports "already installed" and leaves the stale copy in place. Every verb defaults to user
+ *   scope, so each one has to name `--scope project` explicitly.
+ * - **Codex** has no update verb and no scope. Re-running `plugin add` re-reads the catalog and
+ *   replaces the cached copy, so the same command installs and refreshes. It records no version in
+ *   its config — the installed version is only in the cache directory's name.
+ * - **Copilot CLI** accepts a path source but **rejects an `npm` source**, so it cannot consume this
+ *   catalog at all. See {@link COPILOT_LIMITATION}.
+ * - **Cursor** exposes no plugin subcommand from a terminal.
+ *
+ * A consumer should not have to know any of that, which is why it is here rather than in a document.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export type PluginRuntimeName = 'claude-code' | 'codex'
+
+export type InstalledPlugin = {
+	/** `<plugin>@<marketplace>` — the identity a harness installs and uninstalls by. */
+	id: string
+	version: string
+	scope: string
+	/** Present for project- and local-scoped installs; absent where a runtime has no scopes. */
+	projectPath?: string
+}
+
+export type RegisteredMarketplace = { name: string; path: string }
+
+/**
+ * The state a harness keeps outside the repository. Read, never written: the install is the
+ * runtime's own job, and driving it through its own CLI is what keeps that true.
+ */
+export type HarnessPluginState = {
+	installed: InstalledPlugin[]
+	marketplaces: RegisteredMarketplace[]
+}
+
+/**
+ * One runtime's half of the contract: where its state lives, how to read it, and the commands that
+ * move it toward a catalog.
+ */
+export type PluginRuntime = {
+	name: PluginRuntimeName
+	/** Whether this runtime is set up on this machine at all. */
+	present(home: string, env?: NodeJS.ProcessEnv): boolean
+	state(home: string, env?: NodeJS.ProcessEnv): HarnessPluginState
+	register(catalogDir: string): string
+	install(id: string): string
+	update(id: string): string
+	uninstall(id: string): string
+	/** Empty where a runtime re-reads the catalog on install and needs no separate refresh. */
+	refreshMarketplace(marketplace: string): string
+	/**
+	 * True where an install belongs to one repository rather than the whole machine. Where false,
+	 * every repository on the machine shares one install and the reconciliation cannot isolate them.
+	 */
+	scoped: boolean
+}
+
+/**
+ * Why Copilot CLI is absent from the table. Recorded rather than dropped, so the reason travels with
+ * the code: `copilot plugin marketplace add` rejects this catalog with
+ * `Invalid marketplace.json: plugins.0.source: Invalid input`, while the same catalog with a
+ * `./path` source is accepted. Supporting it needs a second, path-sourced catalog — and a path source
+ * cannot escape its marketplace root, which is the constraint the `npm` source was chosen to avoid.
+ */
+export const COPILOT_LIMITATION =
+	'Copilot CLI rejects an npm marketplace source, so it cannot install from this catalog. It needs a path-sourced catalog, which cannot reach node_modules from a subdirectory.'
+
+function readJson(path: string): unknown {
+	try {
+		return JSON.parse(readFileSync(path, 'utf8'))
+	} catch {
+		return undefined
+	}
+}
+
+function directories(path: string): string[] {
+	try {
+		return readdirSync(path, { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => entry.name)
+	} catch {
+		return []
+	}
+}
+
+// ── Claude Code ──
+
+/**
+ * `CLAUDE_CONFIG_DIR` wins where set, which is also what keeps a test off a developer's real
+ * configuration.
+ */
+export function claudeConfigDir(home: string, env: NodeJS.ProcessEnv = process.env): string {
+	return env['CLAUDE_CONFIG_DIR'] || join(home, '.claude')
+}
+
+/**
+ * Reads what Claude Code has installed.
+ *
+ * The file keys each plugin by `<plugin>@<marketplace>` and holds an *array* per key, because the
+ * same plugin can be installed at more than one scope and, at project scope, once per project.
+ */
+export function readClaudeState(configDir: string): HarnessPluginState {
+	const installedFile = readJson(join(configDir, 'plugins', 'installed_plugins.json')) as
+		| { plugins?: Record<string, unknown> }
+		| undefined
+	const installed: InstalledPlugin[] = []
+	for (const [id, entries] of Object.entries(installedFile?.plugins ?? {})) {
+		if (!Array.isArray(entries)) continue
+		for (const entry of entries) {
+			if (!entry || typeof entry !== 'object') continue
+			const record = entry as Record<string, unknown>
+			const version = typeof record['version'] === 'string' ? record['version'] : undefined
+			const scope = typeof record['scope'] === 'string' ? record['scope'] : undefined
+			if (!version || !scope) continue
+			const projectPath = typeof record['projectPath'] === 'string' ? record['projectPath'] : undefined
+			installed.push(projectPath ? { id, version, scope, projectPath } : { id, version, scope })
+		}
+	}
+
+	const knownFile = readJson(join(configDir, 'plugins', 'known_marketplaces.json')) as
+		| Record<string, { source?: { path?: unknown } }>
+		| undefined
+	const marketplaces: RegisteredMarketplace[] = []
+	for (const [name, value] of Object.entries(knownFile ?? {})) {
+		marketplaces.push({ name, path: typeof value?.source?.path === 'string' ? value.source.path : '' })
+	}
+
+	return { installed, marketplaces }
+}
+
+export const claudeCode: PluginRuntime = {
+	name: 'claude-code',
+	scoped: true,
+	present: (home, env = process.env) => existsSync(claudeConfigDir(home, env)),
+	state: (home, env = process.env) => readClaudeState(claudeConfigDir(home, env)),
+	register: (catalogDir) => `claude plugin marketplace add ./${catalogDir} --scope project`,
+	install: (id) => `claude plugin install ${id} --scope project`,
+	/**
+	 * Not `install`: re-running that on an already-installed plugin changes nothing and says so, which
+	 * reads as success. `--scope project` is required rather than cosmetic — every verb defaults to
+	 * user scope, so an update omitting it fails with "not installed at scope user" against a plugin
+	 * that is plainly installed.
+	 */
+	update: (id) => `claude plugin update ${id} --scope project`,
+	uninstall: (id) => `claude plugin uninstall ${id} --scope project`,
+	refreshMarketplace: (marketplace) => `claude plugin marketplace update ${marketplace}`,
+}
+
+// ── Codex ──
+
+export function codexHome(home: string, env: NodeJS.ProcessEnv = process.env): string {
+	return env['CODEX_HOME'] || join(home, '.codex')
+}
+
+/**
+ * Reads what Codex has installed.
+ *
+ * The installed version comes from the cache layout, `plugins/cache/<marketplace>/<plugin>/<version>`,
+ * because Codex's `config.toml` records only that a plugin is enabled — never which version.
+ *
+ * Registered marketplaces are read from `config.toml` by scanning for its `[marketplaces.<name>]`
+ * tables. A deliberately narrow read rather than a TOML parser: only two keys are needed, and the
+ * cost of being wrong is a report that suggests re-registering, which is harmless to re-run.
+ */
+export function readCodexState(home: string): HarnessPluginState {
+	const cacheRoot = join(home, 'plugins', 'cache')
+	const installed: InstalledPlugin[] = []
+	for (const marketplace of directories(cacheRoot)) {
+		for (const plugin of directories(join(cacheRoot, marketplace))) {
+			for (const version of directories(join(cacheRoot, marketplace, plugin))) {
+				installed.push({ id: `${plugin}@${marketplace}`, version, scope: 'user' })
+			}
+		}
+	}
+
+	const marketplaces: RegisteredMarketplace[] = []
+	let config = ''
+	try {
+		config = readFileSync(join(home, 'config.toml'), 'utf8')
+	} catch {
+		config = ''
+	}
+	// The entry itself is carried rather than its name, so assigning a source needs no index lookup
+	// and no guard against one that cannot fail.
+	let current: RegisteredMarketplace | undefined
+	for (const line of config.split('\n')) {
+		const header = /^\s*\[marketplaces\.(?:"([^"]+)"|([^\]]+))\]\s*$/.exec(line)
+		if (header) {
+			current = { name: (header[1] ?? header[2]) as string, path: '' }
+			marketplaces.push(current)
+			continue
+		}
+		if (/^\s*\[/.test(line)) {
+			current = undefined
+			continue
+		}
+		const source = current ? /^\s*source\s*=\s*"([^"]*)"\s*$/.exec(line) : undefined
+		if (source?.[1] && current) current.path = source[1]
+	}
+
+	return { installed, marketplaces }
+}
+
+export const codex: PluginRuntime = {
+	name: 'codex',
+	/**
+	 * Codex installs into `CODEX_HOME` with no notion of scope, so one install is shared by every
+	 * repository on the machine. Two repositories whose catalogs share a marketplace name cannot be
+	 * told apart here, which is what makes the marketplace name derived from the package name matter.
+	 */
+	scoped: false,
+	present: (home, env = process.env) => existsSync(codexHome(home, env)),
+	state: (home, env = process.env) => readCodexState(codexHome(home, env)),
+	register: (catalogDir) => `codex plugin marketplace add ./${catalogDir}`,
+	install: (id) => `codex plugin add ${id}`,
+	/** No update verb: re-running `add` re-reads the catalog and replaces the cached copy. */
+	update: (id) => `codex plugin add ${id}`,
+	uninstall: (id) => `codex plugin remove ${id}`,
+	/** `marketplace upgrade` refreshes git snapshots only; `add` already re-reads a local catalog. */
+	refreshMarketplace: () => '',
+}
+
+export const runtimes: readonly PluginRuntime[] = [claudeCode, codex]

package/src/dep-plugins/reconcile.ts

@@ -0,0 +1,132 @@
+/**
+ * Comparing a derived catalog against what a harness actually has installed.
+ *
+ * The harness reconciles nothing on its own. A catalog entry that appears is not installed; one that
+ * disappears leaves the plugin installed and failing to load, with `prune` declining to remove it
+ * because it was never an auto-installed dependency. So the delta has to be computed, and every
+ * conclusion here comes from that asymmetry.
+ *
+ * Pure. Reading harness state lives in `harness-plugins.ts`.
+ */
+
+import type { Catalog } from './dep-plugins.ts'
+import type { InstalledPlugin, RegisteredMarketplace } from './harness-plugins.ts'
+
+export type ActionKind = 'register' | 'install' | 'update' | 'uninstall'
+
+export type Action = {
+	kind: ActionKind
+	/** `<plugin>@<marketplace>`, or the marketplace name for `register`. */
+	subject: string
+	/** Why, in the terms a reader can act on: the version moving, or the entry that went away. */
+	detail: string
+}
+
+export type Reconciliation = {
+	actions: Action[]
+	/**
+	 * Set when a marketplace of this name is registered against a different directory — the silent
+	 * collision, which produces no error from the harness at any point.
+	 */
+	collision?: string
+	/** Set when the catalog's marketplace is not registered with the harness at all. */
+	unregistered: boolean
+}
+
+export type ReconcileOptions = {
+	catalog: Catalog
+	/** Where the catalog lives, relative to the repository root. */
+	catalogDir: string
+	/** Absolute repository root, used to keep another project's installs out of the comparison. */
+	root: string
+	installed: readonly InstalledPlugin[]
+	marketplaces: readonly RegisteredMarketplace[]
+	/**
+	 * Whether this runtime installs per repository. Where it does not — Codex keeps one install per
+	 * machine — every install under this marketplace is this repository's by default, because there
+	 * is nothing to tell two repositories apart.
+	 */
+	scoped?: boolean
+}
+
+/**
+ * Installs belonging to this repository and this catalog.
+ *
+ * On a scoped runtime a user-scoped install is deliberately excluded rather than counted: it is
+ * shared with every other repository on the machine, so treating it as satisfying this repository's
+ * catalog would let one project's pin silently stand in for another's.
+ */
+function ours(
+	installed: readonly InstalledPlugin[],
+	marketplace: string,
+	root: string,
+	scoped: boolean,
+): InstalledPlugin[] {
+	const suffix = `@${marketplace}`
+	return installed.filter((entry) => entry.id.endsWith(suffix) && (!scoped || entry.projectPath === root))
+}
+
+export function reconcile({
+	catalog,
+	catalogDir,
+	root,
+	installed,
+	marketplaces,
+	scoped = true,
+}: ReconcileOptions): Reconciliation {
+	const registration = marketplaces.find((entry) => entry.name === catalog.name)
+	const actions: Action[] = []
+
+	// A registration pointing somewhere else is the collision case. Reported rather than repaired:
+	// re-registering would take the name from whichever repository currently holds it, trading one
+	// silent breakage for another.
+	const expected = catalogDir.split(/[\\/]/).filter(Boolean)
+	const pointsHere = registration ? expected.every((segment) => registration.path.includes(segment)) : false
+	const collision = registration && !pointsHere ? registration.path : undefined
+
+	if (!registration) {
+		actions.push({
+			kind: 'register',
+			subject: catalog.name,
+			detail: 'marketplace is not registered with this harness',
+		})
+	}
+
+	const mine = ours(installed, catalog.name, root, scoped)
+	const byId = new Map(mine.map((entry) => [entry.id, entry]))
+
+	for (const entry of catalog.plugins) {
+		const id = `${entry.name}@${catalog.name}`
+		const current = byId.get(id)
+		if (!current) {
+			actions.push({ kind: 'install', subject: id, detail: `not installed; catalog pins ${entry.source.version}` })
+			continue
+		}
+		if (current.version !== entry.source.version) {
+			actions.push({
+				kind: 'update',
+				subject: id,
+				detail: `installed ${current.version}, catalog pins ${entry.source.version}`,
+			})
+		}
+	}
+
+	// Installed but no longer in the catalog: the dependency was removed or stopped shipping a plugin.
+	// Nothing else removes these — the harness leaves them installed and failing to load.
+	const wanted = new Set(catalog.plugins.map((entry) => `${entry.name}@${catalog.name}`))
+	for (const entry of mine) {
+		if (!wanted.has(entry.id)) {
+			actions.push({
+				kind: 'uninstall',
+				subject: entry.id,
+				detail: 'installed but no longer in the catalog; it will report a load failure until removed',
+			})
+		}
+	}
+
+	return {
+		actions,
+		...(collision ? { collision } : {}),
+		unregistered: !registration,
+	}
+}

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'])
+}