buddy-agent-harness 0.1.0

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

@@ -0,0 +1,76 @@
+import { encode } from '@toon-format/toon'
+import type { cli } from 'clibuilder'
+import { command, z } from 'clibuilder'
+import { type HarnessName, harnessRegistry } from '../harness-registry/harness-registry.ts'
+import { initializeHarnesses } from './initialize-harnesses.ts'
+
+function write(value: object, format: 'json' | 'toon' | undefined): void {
+	process.stdout.write(`${format === 'json' ? JSON.stringify(value) : encode(value)}\n`)
+}
+
+export const initCommand: cli.Command = command({
+	name: 'init',
+	description: 'Set up canonical agent skills for the harnesses already enabled in a repository.',
+	options: {
+		root: {
+			description: 'Repository or package directory. Defaults to the current directory.',
+			type: z.optional(z.string()),
+		},
+		harness: {
+			description: 'Comma-separated harnesses to enable in addition to Claude Code and Cursor, e.g. codex,windsurf.',
+			type: z.optional(z.string()),
+		},
+		copy: {
+			description: 'Copy skills instead of linking them.',
+			type: z.optional(z.boolean()),
+		},
+		force: {
+			description: 'Replace conflicting target skill directories.',
+			type: z.optional(z.boolean()),
+		},
+		format: {
+			description: 'Output format: toon (default) or json.',
+			type: z.optional(z.string()),
+			default: 'toon',
+		},
+	},
+	run(args) {
+		try {
+			const format = args.format
+			if (format !== 'toon' && format !== 'json') throw new Error('--format must be toon or json.')
+			const requested = args.harness
+				?.split(',')
+				.map((name) => name.trim())
+				.filter(Boolean)
+			const unsupported = requested?.filter((name) => !harnessRegistry.some((harness) => harness.name === name))
+			if (unsupported?.length)
+				throw new Error(
+					`Unsupported harness: ${unsupported.join(', ')}. Supported: ${harnessRegistry
+						.map((harness) => harness.name)
+						.join(', ')}.`,
+				)
+			write(
+				initializeHarnesses({
+					root: args.root ?? process.cwd(),
+					...(requested?.length ? { harnesses: requested as HarnessName[] } : {}),
+					...(args.copy === undefined ? {} : { copy: args.copy }),
+					...(args.force === undefined ? {} : { force: args.force }),
+				}),
+				format,
+			)
+		} catch (error) {
+			process.stderr.write(`error: ${error instanceof Error ? error.message : 'Harness initialization failed.'}\n`)
+			process.exitCode = 1
+		}
+	},
+})
+
+export const harnessCommand: cli.Command = command({
+	name: 'harness',
+	description: 'Commands for configuring agent harness compatibility.',
+	commands: [initCommand],
+})
+
+export function activate({ addCommand }: { addCommand(command: typeof harnessCommand): void }): void {
+	addCommand(harnessCommand)
+}

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

@@ -0,0 +1,44 @@
+import { join } from 'node:path'
+import { type HarnessName, selectHarnesses } from '../harness-registry/harness-registry.ts'
+import { countSkills, projectSkills } from '../skill-projection/skill-projection.ts'
+
+export type InitializeOptions = {
+	root: string
+	harnesses?: HarnessName[]
+	copy?: boolean
+	force?: boolean
+}
+export type InitializeResult = {
+	root: string
+	harnesses: HarnessName[]
+	native: HarnessName[]
+	linked: HarnessName[]
+	/** Enabled harnesses whose name has been superseded, as `{ name, replacedBy }`. */
+	deprecated: { name: HarnessName; replacedBy: HarnessName }[]
+	skills: number
+	copied: boolean
+}
+
+export function initializeHarnesses({
+	root,
+	harnesses: preferred = [],
+	copy = false,
+	force = false,
+}: InitializeOptions): InitializeResult {
+	const canonicalSkills = join(root, '.agents', 'skills')
+	const skills = countSkills(canonicalSkills)
+	const harnesses = selectHarnesses(root, preferred)
+	const linked = projectSkills({ root, canonicalSkills, harnesses, copy, force })
+
+	return {
+		root,
+		harnesses: harnesses.map((harness) => harness.name),
+		native: harnesses.filter((harness) => !harness.skillsDirectory).map((harness) => harness.name),
+		linked,
+		deprecated: harnesses
+			.filter((harness) => harness.deprecated)
+			.map((harness) => ({ name: harness.name, replacedBy: harness.deprecated as HarnessName })),
+		skills,
+		copied: copy,
+	}
+}

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

@@ -0,0 +1,78 @@
+import { cpSync, lstatSync, mkdirSync, readdirSync, readlinkSync, rmSync, symlinkSync } from 'node:fs'
+import { dirname, join, relative } from 'node:path'
+import type { Harness, HarnessName } from '../harness-registry/harness-registry.ts'
+
+function skillNames(skillsDirectory: string): string[] {
+	return readdirSync(skillsDirectory, { withFileTypes: true })
+		.filter((entry) => entry.isDirectory())
+		.map((entry) => entry.name)
+		.sort()
+}
+
+function pathOccupied(path: string): boolean {
+	try {
+		lstatSync(path)
+		return true
+	} catch {
+		return false
+	}
+}
+
+function isCorrectLink(target: string, source: string): boolean {
+	return lstatSync(target).isSymbolicLink() && readlinkSync(target) === relative(dirname(target), source)
+}
+
+/** Creates the canonical directory when absent, so a fresh repository reports zero skills. */
+export function countSkills(canonicalSkills: string): number {
+	mkdirSync(canonicalSkills, { recursive: true })
+	return skillNames(canonicalSkills).length
+}
+
+export type ProjectSkillsOptions = {
+	root: string
+	canonicalSkills: string
+	harnesses: readonly Harness[]
+	copy: boolean
+	force: boolean
+}
+
+/**
+ * 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.
+ */
+export function projectSkills({ root, canonicalSkills, harnesses, copy, force }: ProjectSkillsOptions): HarnessName[] {
+	const projections = harnesses
+		.filter((harness) => harness.skillsDirectory)
+		.map((harness) => ({
+			harness,
+			target: join(root, harness.skillsDirectory as string),
+		}))
+
+	const conflicts = projections
+		.filter(({ target }) => pathOccupied(target) && !isCorrectLink(target, canonicalSkills))
+		.map(({ target }) => target)
+
+	if (conflicts.length && !force) {
+		throw new Error(
+			`Refusing to replace existing skill targets:\n${conflicts.map((target) => `- ${target}`).join('\n')}`,
+		)
+	}
+
+	for (const { target } of projections) {
+		mkdirSync(dirname(target), { recursive: true })
+		if (pathOccupied(target) && isCorrectLink(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')
+		} catch (error) {
+			if (pathOccupied(target)) throw error
+			cpSync(canonicalSkills, target, { recursive: true })
+		}
+	}
+
+	return projections.map(({ harness }) => harness.name)
+}