buddy-agent-harness 0.6.0 → 0.8.0

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

@@ -0,0 +1,131 @@
+/**
+ * Dependency-provided plugins: the catalog half.
+ *
+ * A dependency that ships an Agent Plugins manifest at its package root is a plugin the consuming
+ * repository can install through its harness. This module turns the set of such dependencies into a
+ * marketplace catalog; installing from that catalog is the runtime's own job, and the lifecycle half
+ * drives it.
+ *
+ * Everything here is pure. Resolution against `node_modules` lives in `resolve.ts`.
+ */
+
+/** One dependency that ships a plugin manifest. */
+export type DepPlugin = {
+	/** The npm package name — what a consumer declared, and what the catalog installs by. */
+	package: string
+	/** The plugin's own name from its manifest, which need not match the package name. */
+	plugin: string
+	/** The version actually installed, read from the dependency's own `package.json`. */
+	version: string
+	description?: string
+}
+
+/**
+ * A catalog entry's `npm` source. Deliberately not a path: a path source is resolved against the
+ * marketplace root and may not escape it, so a path-sourced catalog would have to sit at the
+ * repository root — the one place the repository's own public catalog already occupies. An `npm`
+ * source carries no path, so this catalog can live in its own directory and stay separate from
+ * whatever the repository publishes for its own consumers.
+ */
+export type NpmSource = {
+	source: 'npm'
+	package: string
+	version: string
+}
+
+export type CatalogEntry = {
+	name: string
+	source: NpmSource
+	description?: string
+}
+
+/**
+ * The Claude-shaped catalog, which Codex, Copilot CLI, and Cursor also read. `owner` is an object
+ * whose `name` is required — a string there is a schema error rather than a tolerated shorthand.
+ */
+export type Catalog = {
+	name: string
+	owner: { name: string }
+	description: string
+	plugins: CatalogEntry[]
+}
+
+/**
+ * Marketplace names generic enough that two repositories are likely to pick the same one. The
+ * collision is silent and costly: registering a second marketplace under a name already in use
+ * replaces the first, and the install that follows reports "already installed" and does nothing —
+ * so the repository silently runs the other one's plugin versions.
+ */
+const GENERIC_NAMES = new Set(['deps', 'dependencies', 'local', 'plugins', 'marketplace', 'plugin', 'default'])
+
+export function isGenericName(name: string): boolean {
+	return GENERIC_NAMES.has(name.toLowerCase())
+}
+
+/**
+ * A marketplace name derived from the consuming package's own name, so two repositories do not
+ * collide by default. A scope is folded into the name rather than dropped (`@acme/web` → `acme-web`)
+ * because the unscoped half is the part most likely to repeat across organizations.
+ */
+export function marketplaceName(packageName: string): string {
+	const folded = packageName.replace(/^@/, '').replace(/\//g, '-')
+	const cleaned = folded
+		.replace(/[^a-zA-Z0-9-_.]/g, '-')
+		.replace(/-+/g, '-')
+		.replace(/^-|-$/g, '')
+	return cleaned || 'agent-plugins'
+}
+
+/**
+ * Dependency names a repository declares, both runtime and development.
+ *
+ * Development dependencies are included on purpose: a plugin that supplies a project's testing or
+ * release workflow is a development dependency, and excluding them would drop most of the cases this
+ * exists for. Transitive dependencies are never included — see `resolve.ts`.
+ */
+export function declaredDependencies(manifest: unknown): string[] {
+	if (!manifest || typeof manifest !== 'object') return []
+	const record = manifest as Record<string, unknown>
+	const names = new Set<string>()
+	for (const field of ['dependencies', 'devDependencies']) {
+		const group = record[field]
+		if (!group || typeof group !== 'object') continue
+		for (const name of Object.keys(group as Record<string, unknown>)) names.add(name)
+	}
+	return [...names].sort()
+}
+
+export type BuildCatalogOptions = {
+	name: string
+	owner: string
+	plugins: readonly DepPlugin[]
+}
+
+/**
+ * The catalog is derived in full on every run and never merged into what is already on disk. That is
+ * what makes the three cases a consumer cares about — a plugin added, a plugin removed, a version
+ * moved — fall out of regeneration instead of needing reconciliation logic of their own.
+ *
+ * Entries are sorted by name so that a regeneration whose inputs did not change produces a
+ * byte-identical file, which is what lets a check mode compare rather than interpret.
+ */
+export function buildCatalog({ name, owner, plugins }: BuildCatalogOptions): Catalog {
+	const entries = [...plugins]
+		.sort((a, b) => a.plugin.localeCompare(b.plugin))
+		.map(({ plugin, package: pkg, version, description }): CatalogEntry => {
+			const source: NpmSource = { source: 'npm', package: pkg, version }
+			return description ? { name: plugin, source, description } : { name: plugin, source }
+		})
+
+	return {
+		name,
+		owner: { name: owner },
+		description: 'Plugins provided by this repository’s dependencies. Generated — do not edit.',
+		plugins: entries,
+	}
+}
+
+/** Serialized the way the repository formats JSON, with the trailing newline a text file needs. */
+export function serializeCatalog(catalog: Catalog): string {
+	return `${JSON.stringify(catalog, null, '\t')}\n`
+}

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,
+	}
+}