buddy-agent-harness 0.6.0 → 0.7.0

package/src/initialize-harnesses/initialize-harnesses.ts

@@ -1,18 +1,20 @@
 import { join } from 'node:path'
 import { type HarnessName, selectHarnesses } from '../harness-registry/harness-registry.ts'
-import { countSkills, projectSkills } from '../skill-projection/skill-projection.ts'
+import { countSkills, type ForceSelection, projectSkills } from '../skill-projection/skill-projection.ts'
 
 export type InitializeOptions = {
 	root: string
 	harnesses?: HarnessName[]
 	copy?: boolean
-	force?: boolean
+	force?: ForceSelection
 }
 export type InitializeResult = {
 	root: string
 	harnesses: HarnessName[]
 	native: HarnessName[]
 	linked: HarnessName[]
+	/** Enabled harnesses left untouched because their target conflicts and `--force` did not name it. */
+	skipped: HarnessName[]
 	/** Enabled harnesses whose name has been superseded, as `{ name, replacedBy }`. */
 	deprecated: { name: HarnessName; replacedBy: HarnessName }[]
 	skills: number
@@ -28,13 +30,14 @@ export function initializeHarnesses({
 	const canonicalSkills = join(root, '.agents', 'skills')
 	const skills = countSkills(canonicalSkills)
 	const harnesses = selectHarnesses(root, preferred)
-	const linked = projectSkills({ root, canonicalSkills, harnesses, copy, force })
+	const { linked, skipped } = projectSkills({ root, canonicalSkills, harnesses, copy, force })
 
 	return {
 		root,
 		harnesses: harnesses.map((harness) => harness.name),
 		native: harnesses.filter((harness) => !harness.project.skillsDirectory).map((harness) => harness.name),
 		linked,
+		skipped,
 		deprecated: harnesses
 			.filter((harness) => harness.deprecated)
 			.map((harness) => ({ name: harness.name, replacedBy: harness.deprecated as HarnessName })),

package/src/is-record/is-record.ts

@@ -0,0 +1,12 @@
+/**
+ * Whether a value is a record: an object with named keys, and not an array.
+ *
+ * Everything this package reads is a file someone else wrote — a golden MCP set, a harness config,
+ * a projection record — so every parse lands on `unknown` and every reader narrows it here before
+ * asking for a key. Four modules had their own copy of the same three clauses; a predicate that
+ * decides what counts as a parsed object is one fact, and a copy of it that drifts changes what a
+ * file is read to say.
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/skill-projection/skill-projection.ts

@@ -1,5 +1,6 @@
-import { cpSync, lstatSync, mkdirSync, readdirSync, readlinkSync, rmSync, symlinkSync } from 'node:fs'
-import { dirname, join, relative } from 'node:path'
+import { cpSync, lstatSync, mkdirSync, readdirSync, realpathSync, rmSync, symlinkSync } from 'node:fs'
+import { platform } from 'node:os'
+import { dirname, join, relative, resolve } from 'node:path'
 import type { Harness, HarnessName } from '../harness-registry/harness-registry.ts'
 
 function skillNames(skillsDirectory: string): string[] {
@@ -18,8 +19,19 @@ function pathOccupied(path: string): boolean {
 	}
 }
 
-function isCorrectLink(target: string, source: string): boolean {
-	return lstatSync(target).isSymbolicLink() && readlinkSync(target) === relative(dirname(target), source)
+/**
+ * Whether `target` is a symbolic link that resolves to `canonical`. Resolved paths are compared
+ * rather than link text, so a link a user wrote as an absolute path, one this tool wrote as a
+ * Windows junction, and one reached through a symbolic link in a parent directory all read as the
+ * correct bridge. A link that no longer resolves is not.
+ */
+export function linksTo(target: string, canonical: string): boolean {
+	try {
+		if (!lstatSync(target).isSymbolicLink()) return false
+		return realpathSync(target) === realpathSync(canonical)
+	} catch {
+		return false
+	}
 }
 
 /** Creates the canonical directory when absent, so a fresh repository reports zero skills. */
@@ -28,19 +40,72 @@ export function countSkills(canonicalSkills: string): number {
 	return skillNames(canonicalSkills).length
 }
 
+/**
+ * A junction is the only link Windows grants an unprivileged process, and Node resolves a relative
+ * junction target against the process directory rather than the link's own, so Windows is given the
+ * absolute path. Every other platform keeps the link relative, so it survives the repository moving.
+ */
+function linkTarget(target: string, canonicalSkills: string): string {
+	return platform() === 'win32' ? resolve(canonicalSkills) : relative(dirname(target), canonicalSkills)
+}
+
+/**
+ * Which conflicting targets a run may replace. `true` is every one of them; a list names them
+ * individually, so a run invoked to fix one bridge cannot reach past it to another. `false` and an
+ * empty list both mean none, which is what makes a conflict stop the run.
+ */
+export type ForceSelection = boolean | readonly string[]
+
+/**
+ * Translates what the option parser hands back into a selection. A valueless `--force` arrives as
+ * the literal string `true` — that is how the parser encodes a flag given no value — and means
+ * every conflicting target, which is what keeps an existing `init --force` doing what it always did.
+ * Anything else is a comma-separated list of targets.
+ */
+export function parseForce(value: string): ForceSelection {
+	if (value === 'true') return true
+	if (value === 'false') return false
+	return value
+		.split(',')
+		.map((target) => target.trim())
+		.filter((target) => target.length > 0)
+}
+
 export type ProjectSkillsOptions = {
 	root: string
 	canonicalSkills: string
 	harnesses: readonly Harness[]
 	copy: boolean
-	force: boolean
+	force: ForceSelection
+}
+
+export type ProjectSkillsResult = {
+	/** Harnesses whose target now points at the canonical directory. */
+	linked: HarnessName[]
+	/** Harnesses left untouched because their target conflicts and `--force` did not name it. */
+	skipped: HarnessName[]
+}
+
+/**
+ * Targets are matched against what the caller typed, resolved against the repository root, so the
+ * repo-relative form the conflict message prints is the form that selects it back — and an absolute
+ * path naming the same directory selects it too.
+ */
+function namesTarget(root: string, target: string, given: string): boolean {
+	return resolve(root, given) === resolve(target)
 }
 
 /**
  * Points every harness that cannot read `.agents/skills` at the canonical directory. Symlinking is
- * preferred; a platform that refuses the link falls back to a copy. Returns the projected harnesses.
+ * preferred; a platform that refuses the link falls back to a copy.
  */
-export function projectSkills({ root, canonicalSkills, harnesses, copy, force }: ProjectSkillsOptions): HarnessName[] {
+export function projectSkills({
+	root,
+	canonicalSkills,
+	harnesses,
+	copy,
+	force,
+}: ProjectSkillsOptions): ProjectSkillsResult {
 	const projections = harnesses
 		.filter((harness) => harness.project.skillsDirectory)
 		.map((harness) => ({
@@ -48,31 +113,52 @@ export function projectSkills({ root, canonicalSkills, harnesses, copy, force }:
 			target: join(root, harness.project.skillsDirectory as string),
 		}))
 
-	const conflicts = projections
-		.filter(({ target }) => pathOccupied(target) && !isCorrectLink(target, canonicalSkills))
-		.map(({ target }) => target)
+	const named = Array.isArray(force) ? force : []
+	// A name matching no projection target at all is a typo, not a narrower run: silently forcing
+	// nothing would surface as the conflict error the flag was reached for, blaming the wrong thing.
+	const unknown = named.filter((given) => !projections.some(({ target }) => namesTarget(root, target, given)))
+	if (unknown.length) {
+		throw new Error(
+			`No skill target matches:\n${unknown.map((given) => `- ${given}`).join('\n')}\n` +
+				`Targets for the enabled harnesses:\n${projections.map(({ target }) => `- ${relative(root, target)}`).join('\n')}`,
+		)
+	}
+
+	const forces = (target: string): boolean => force === true || named.some((given) => namesTarget(root, target, given))
 
-	if (conflicts.length && !force) {
+	const conflicts = projections.filter(({ target }) => pathOccupied(target) && !linksTo(target, canonicalSkills))
+	const blocked = conflicts.filter(({ target }) => !forces(target))
+
+	// Nothing was named, so nothing distinguishes one conflict from another: stop before writing.
+	// Once a target IS named, the unnamed conflicts are the ones this run was told to leave alone,
+	// so they are skipped and reported rather than turned into a refusal that writes nothing at all.
+	if (blocked.length && named.length === 0) {
 		throw new Error(
-			`Refusing to replace existing skill targets:\n${conflicts.map((target) => `- ${target}`).join('\n')}`,
+			`Refusing to replace existing skill targets:\n${blocked.map(({ target }) => `- ${relative(root, target)}`).join('\n')}`,
 		)
 	}
 
-	for (const { target } of projections) {
+	const skipped = new Set(blocked.map(({ harness }) => harness.name))
+
+	for (const { harness, target } of projections) {
+		if (skipped.has(harness.name)) continue
 		mkdirSync(dirname(target), { recursive: true })
-		if (pathOccupied(target) && isCorrectLink(target, canonicalSkills)) continue
+		if (linksTo(target, canonicalSkills)) continue
 		if (pathOccupied(target)) rmSync(target, { recursive: true, force: true })
 		if (copy) {
 			cpSync(canonicalSkills, target, { recursive: true })
 			continue
 		}
 		try {
-			symlinkSync(relative(dirname(target), canonicalSkills), target, 'junction')
+			symlinkSync(linkTarget(target, canonicalSkills), target, platform() === 'win32' ? 'junction' : undefined)
 		} catch (error) {
 			if (pathOccupied(target)) throw error
 			cpSync(canonicalSkills, target, { recursive: true })
 		}
 	}
 
-	return projections.map(({ harness }) => harness.name)
+	return {
+		linked: projections.filter(({ harness }) => !skipped.has(harness.name)).map(({ harness }) => harness.name),
+		skipped: projections.filter(({ harness }) => skipped.has(harness.name)).map(({ harness }) => harness.name),
+	}
 }

package/dist/cli.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["import { cli } from 'clibuilder'\nimport { doctorCommand } from './diagnose-bridges/doctor.command.ts'\nimport { initCommand } from './initialize-harnesses/init.command.ts'\n\nexport async function main(): Promise<void> {\n\tconst app = cli({\n\t\tname: 'buddy-agent-harness',\n\t\tversion: '0.1.0',\n\t\tdescription: 'Initialize agent harness skill compatibility in consumer repositories.',\n\t})\n\ttry {\n\t\tawait app.command(initCommand).command(doctorCommand).parse(process.argv)\n\t} catch (error) {\n\t\tprocess.stdout.write(`error: ${error instanceof Error ? error.message : 'Invalid command.'}\\n`)\n\t\tprocess.exitCode = 2\n\t}\n}\n"],"mappings":";;;AAIA,eAAsB,OAAsB;CAC3C,MAAM,MAAM,IAAI;EACf,MAAM;EACN,SAAS;EACT,aAAa;CACd,CAAC;CACD,IAAI;EACH,MAAM,IAAI,QAAQ,WAAW,CAAC,CAAC,QAAQ,aAAa,CAAC,CAAC,MAAM,QAAQ,IAAI;CACzE,SAAS,OAAO;EACf,QAAQ,OAAO,MAAM,UAAU,iBAAiB,QAAQ,MAAM,UAAU,mBAAmB,GAAG;EAC9F,QAAQ,WAAW;CACpB;AACD"}