buddy-agent-harness 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/.cursor-plugin/plugin.json +1 -1
- package/CHANGELOG.md +31 -0
- package/dist/cli.mjs +2227 -840
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +521 -439
- package/dist/index.mjs.map +1 -1
- package/dist/skill-scripts/doctor.mjs +74 -67
- package/dist/skill-scripts/init.mjs +74 -67
- package/dist/skill-scripts/mcp.mjs +74 -67
- package/llms.txt +2 -1
- package/package.json +4 -4
- package/plugin.json +1 -1
- package/skills/doctor-buddy-agent-harness/README.md +1 -1
- package/skills/doctor-buddy-agent-harness/SKILL.md +1 -1
- package/skills/doctor-buddy-agent-harness/scripts/doctor.mjs +74 -67
- package/skills/enhance/SKILL.md +1 -1
- package/skills/enhance/references/list-identifiers.history.md +9 -1
- package/skills/enhance/references/list-identifiers.md +6 -9
- package/skills/enhance/scripts/doctor.mjs +74 -67
- package/skills/init-buddy-agent-harness/SKILL.md +2 -2
- package/skills/init-buddy-agent-harness/references/standard.md +1 -1
- package/skills/init-buddy-agent-harness/scripts/doctor.mjs +74 -67
- package/skills/init-buddy-agent-harness/scripts/init.mjs +74 -67
- package/skills/repair/SKILL.md +1 -1
- package/skills/repair/scripts/doctor.mjs +74 -67
- package/skills/repair/scripts/mcp.mjs +74 -67
- package/src/cli.ts +13 -3
- package/src/command-output/command-output.ts +28 -5
- package/src/dep-plugins/dep-plugins.command.ts +4 -0
- package/src/diagnose-bridges/doctor.command.ts +67 -49
- package/src/governance-overrides/governance.command.ts +13 -8
- package/src/initialize-harnesses/init.command.ts +9 -3
- package/src/project-mcp/mcp.command.ts +15 -9
- package/src/reconcile-mcp/reconcile.command.ts +17 -11
- package/src/references/references.ts +1 -0
package/dist/index.mjs
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { declaredDependencies, listReferences, listReferences as listReferences$1, packageDir, parseReferenceName, referenceLayers as referenceLayers$1, referenceNames, repoReferencesDir, resolveReference, searchReferences, skillsDirectories } from "cyber-agentkit";
|
|
2
2
|
import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
|
|
3
3
|
import { cli, command, t } from "clibuilder";
|
|
4
|
-
import { CliError, document, exitCodes, isCliError, printAnswer, result } from "clibuilder/axi";
|
|
4
|
+
import { CliError, document, empty, exitCodes, homeHeader, isCliError, printAnswer, ref, result } from "clibuilder/axi";
|
|
5
5
|
import { homedir, platform } from "node:os";
|
|
6
6
|
import { basename, dirname, join, posix, relative, resolve, sep } from "node:path";
|
|
7
7
|
import { parse, stringify } from "smol-toml";
|
|
@@ -10,15 +10,276 @@ import { fileURLToPath } from "node:url";
|
|
|
10
10
|
import { execFileSync } from "node:child_process";
|
|
11
11
|
import { parseTOML } from "toml-eslint-parser";
|
|
12
12
|
import { findNodeAtLocation, parseTree } from "jsonc-parser";
|
|
13
|
+
//#region src/harness-registry/harness-registry.ts
|
|
14
|
+
/**
|
|
15
|
+
* Throws on a harness `skillsDirectories` does not confirm: treating it as native would silently
|
|
16
|
+
* drop a projection it may need.
|
|
17
|
+
*/
|
|
18
|
+
function skillsProjection(harness, scope, directories = skillsDirectories(harness)?.[scope]) {
|
|
19
|
+
const listed = directories ?? [];
|
|
20
|
+
const [first] = listed;
|
|
21
|
+
if (first === void 0) throw new Error(`cyber-agentkit records no ${scope} skills directories for ${harness}.`);
|
|
22
|
+
return listed.includes(".agents/skills") ? {} : { skillsDirectory: first };
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* The user-scope counterpart of the root `AGENTS.md`, relative to the home directory. No harness
|
|
26
|
+
* reads it natively; each loads it only through a user-scope `instructionBridge` (E-CC-18, E-CODEX-05,
|
|
27
|
+
* E-GEM-03, E-COPILOT-04, E-CUR-08).
|
|
28
|
+
*/
|
|
29
|
+
const globalInstructions = ".agents/AGENTS.md";
|
|
30
|
+
/**
|
|
31
|
+
* Skills directories come from `cyber-agentkit`, except for the harnesses it does not know
|
|
32
|
+
* (`devin-desktop`, `windsurf`); see `.research/agentic-configuration-standards/` for the rest.
|
|
33
|
+
*/
|
|
34
|
+
const harnessRegistry = [
|
|
35
|
+
{
|
|
36
|
+
name: "claude-code",
|
|
37
|
+
project: {
|
|
38
|
+
detect: ".claude",
|
|
39
|
+
...skillsProjection("claude-code", "project"),
|
|
40
|
+
shadowedBy: [
|
|
41
|
+
"CLAUDE.md",
|
|
42
|
+
".claude/CLAUDE.md",
|
|
43
|
+
"CLAUDE.local.md"
|
|
44
|
+
],
|
|
45
|
+
mcpConfig: {
|
|
46
|
+
path: ".mcp.json",
|
|
47
|
+
key: "mcpServers",
|
|
48
|
+
format: "json",
|
|
49
|
+
dialect: "claude-code"
|
|
50
|
+
},
|
|
51
|
+
nonstandard: [
|
|
52
|
+
{
|
|
53
|
+
path: ".claude/commands",
|
|
54
|
+
shape: "directory",
|
|
55
|
+
kind: "command"
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
path: ".claude/rules",
|
|
59
|
+
shape: "directory",
|
|
60
|
+
kind: "rule"
|
|
61
|
+
},
|
|
62
|
+
{
|
|
63
|
+
path: ".claude/agents",
|
|
64
|
+
shape: "directory",
|
|
65
|
+
kind: "subagent"
|
|
66
|
+
}
|
|
67
|
+
]
|
|
68
|
+
},
|
|
69
|
+
user: {
|
|
70
|
+
detect: ".claude",
|
|
71
|
+
...skillsProjection("claude-code", "user"),
|
|
72
|
+
relocatedBy: "CLAUDE_CONFIG_DIR",
|
|
73
|
+
emptyRelocatesToStart: true,
|
|
74
|
+
instructionBridge: {
|
|
75
|
+
kind: "import",
|
|
76
|
+
path: ".claude/CLAUDE.md",
|
|
77
|
+
line: `@~/${globalInstructions}`
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
},
|
|
81
|
+
{
|
|
82
|
+
name: "cursor",
|
|
83
|
+
project: {
|
|
84
|
+
detect: ".cursor",
|
|
85
|
+
...skillsProjection("cursor", "project"),
|
|
86
|
+
mcpConfig: {
|
|
87
|
+
path: ".cursor/mcp.json",
|
|
88
|
+
key: "mcpServers",
|
|
89
|
+
format: "json",
|
|
90
|
+
dialect: "cursor"
|
|
91
|
+
},
|
|
92
|
+
nonstandard: [
|
|
93
|
+
{
|
|
94
|
+
path: ".cursorrules",
|
|
95
|
+
shape: "file",
|
|
96
|
+
kind: "instructions"
|
|
97
|
+
},
|
|
98
|
+
{
|
|
99
|
+
path: ".cursor/rules",
|
|
100
|
+
shape: "directory",
|
|
101
|
+
kind: "rule"
|
|
102
|
+
},
|
|
103
|
+
{
|
|
104
|
+
path: ".cursor/commands",
|
|
105
|
+
shape: "directory",
|
|
106
|
+
kind: "command"
|
|
107
|
+
},
|
|
108
|
+
{
|
|
109
|
+
path: ".cursor/skills",
|
|
110
|
+
shape: "directory",
|
|
111
|
+
kind: "skill"
|
|
112
|
+
}
|
|
113
|
+
]
|
|
114
|
+
},
|
|
115
|
+
user: {
|
|
116
|
+
detect: ".cursor",
|
|
117
|
+
...skillsProjection("cursor", "user")
|
|
118
|
+
}
|
|
119
|
+
},
|
|
120
|
+
{
|
|
121
|
+
name: "codex",
|
|
122
|
+
project: {
|
|
123
|
+
detect: ".codex",
|
|
124
|
+
...skillsProjection("codex", "project"),
|
|
125
|
+
mcpConfig: {
|
|
126
|
+
path: ".codex/config.toml",
|
|
127
|
+
key: "mcp_servers",
|
|
128
|
+
format: "toml",
|
|
129
|
+
dialect: "codex",
|
|
130
|
+
shared: true
|
|
131
|
+
},
|
|
132
|
+
nonstandard: [{
|
|
133
|
+
path: ".codex/skills",
|
|
134
|
+
shape: "directory",
|
|
135
|
+
kind: "skill"
|
|
136
|
+
}]
|
|
137
|
+
},
|
|
138
|
+
user: {
|
|
139
|
+
detect: ".codex",
|
|
140
|
+
...skillsProjection("codex", "user"),
|
|
141
|
+
instructionBridge: {
|
|
142
|
+
kind: "symlink",
|
|
143
|
+
path: ".codex/AGENTS.md"
|
|
144
|
+
},
|
|
145
|
+
shadowedBy: [".codex/AGENTS.override.md"],
|
|
146
|
+
relocatedBy: "CODEX_HOME"
|
|
147
|
+
}
|
|
148
|
+
},
|
|
149
|
+
{
|
|
150
|
+
name: "copilot-cli",
|
|
151
|
+
project: {
|
|
152
|
+
detect: ".github/skills",
|
|
153
|
+
...skillsProjection("copilot-cli", "project"),
|
|
154
|
+
nonstandard: [
|
|
155
|
+
{
|
|
156
|
+
path: ".github/copilot-instructions.md",
|
|
157
|
+
shape: "file",
|
|
158
|
+
kind: "instructions"
|
|
159
|
+
},
|
|
160
|
+
{
|
|
161
|
+
path: ".github/instructions",
|
|
162
|
+
shape: "directory",
|
|
163
|
+
kind: "instructions"
|
|
164
|
+
},
|
|
165
|
+
{
|
|
166
|
+
path: ".github/skills",
|
|
167
|
+
shape: "directory",
|
|
168
|
+
kind: "skill"
|
|
169
|
+
}
|
|
170
|
+
]
|
|
171
|
+
},
|
|
172
|
+
user: {
|
|
173
|
+
detect: ".copilot",
|
|
174
|
+
...skillsProjection("copilot-cli", "user"),
|
|
175
|
+
relocatedBy: "COPILOT_HOME",
|
|
176
|
+
instructionBridge: {
|
|
177
|
+
kind: "symlink",
|
|
178
|
+
path: ".copilot/copilot-instructions.md"
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
},
|
|
182
|
+
{
|
|
183
|
+
name: "gemini-cli",
|
|
184
|
+
project: {
|
|
185
|
+
detect: ".gemini",
|
|
186
|
+
...skillsProjection("gemini-cli", "project"),
|
|
187
|
+
instructionBridge: {
|
|
188
|
+
kind: "settings-entry",
|
|
189
|
+
path: ".gemini/settings.json",
|
|
190
|
+
key: "context.fileName"
|
|
191
|
+
},
|
|
192
|
+
mcpConfig: {
|
|
193
|
+
path: ".gemini/settings.json",
|
|
194
|
+
key: "mcpServers",
|
|
195
|
+
format: "json",
|
|
196
|
+
dialect: "gemini-cli",
|
|
197
|
+
shared: true
|
|
198
|
+
},
|
|
199
|
+
nonstandard: [{
|
|
200
|
+
path: "GEMINI.md",
|
|
201
|
+
shape: "file",
|
|
202
|
+
kind: "instructions"
|
|
203
|
+
}, {
|
|
204
|
+
path: ".gemini/skills",
|
|
205
|
+
shape: "directory",
|
|
206
|
+
kind: "skill"
|
|
207
|
+
}]
|
|
208
|
+
},
|
|
209
|
+
user: {
|
|
210
|
+
detect: ".gemini",
|
|
211
|
+
...skillsProjection("gemini-cli", "user"),
|
|
212
|
+
instructionBridge: {
|
|
213
|
+
kind: "symlink",
|
|
214
|
+
path: ".gemini/GEMINI.md"
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
},
|
|
218
|
+
{
|
|
219
|
+
name: "devin-desktop",
|
|
220
|
+
project: { detect: ".devin" }
|
|
221
|
+
},
|
|
222
|
+
{
|
|
223
|
+
name: "windsurf",
|
|
224
|
+
project: {
|
|
225
|
+
detect: ".windsurf",
|
|
226
|
+
skillsDirectory: ".windsurf/skills",
|
|
227
|
+
nonstandard: [{
|
|
228
|
+
path: ".windsurfrules",
|
|
229
|
+
shape: "file",
|
|
230
|
+
kind: "instructions"
|
|
231
|
+
}, {
|
|
232
|
+
path: ".windsurf/rules",
|
|
233
|
+
shape: "directory",
|
|
234
|
+
kind: "rule"
|
|
235
|
+
}]
|
|
236
|
+
},
|
|
237
|
+
deprecated: "devin-desktop"
|
|
238
|
+
}
|
|
239
|
+
];
|
|
240
|
+
const harnessNames = new Set(harnessRegistry.map((harness) => harness.name));
|
|
241
|
+
function isHarnessName(value) {
|
|
242
|
+
return harnessNames.has(value);
|
|
243
|
+
}
|
|
244
|
+
/**
|
|
245
|
+
* An unknown name throws rather than being dropped — silently falling back to the defaults would
|
|
246
|
+
* misreport what was diagnosed.
|
|
247
|
+
*/
|
|
248
|
+
function parseHarnesses(value) {
|
|
249
|
+
const requested = (value ?? "").split(",").map((name) => name.trim()).filter(Boolean);
|
|
250
|
+
const unsupported = requested.filter((name) => !isHarnessName(name));
|
|
251
|
+
if (unsupported.length) throw new Error(`Unsupported harness: ${unsupported.join(", ")}. Supported: ${harnessRegistry.map((harness) => harness.name).join(", ")}.`);
|
|
252
|
+
return requested.filter(isHarnessName);
|
|
253
|
+
}
|
|
254
|
+
/** Enabled whether or not the repository already contains their directories. */
|
|
255
|
+
const defaultHarnesses = ["claude-code", "cursor"];
|
|
256
|
+
function directoryExists(path) {
|
|
257
|
+
try {
|
|
258
|
+
return lstatSync(path).isDirectory();
|
|
259
|
+
} catch {
|
|
260
|
+
return false;
|
|
261
|
+
}
|
|
262
|
+
}
|
|
263
|
+
/** The default harnesses, plus the preferred ones, plus every harness whose directory is present. */
|
|
264
|
+
function selectHarnesses(root, preferred) {
|
|
265
|
+
const enabled = /* @__PURE__ */ new Set([...defaultHarnesses, ...preferred]);
|
|
266
|
+
return harnessRegistry.filter((harness) => enabled.has(harness.name) || directoryExists(join(root, harness.project.detect)));
|
|
267
|
+
}
|
|
268
|
+
//#endregion
|
|
13
269
|
//#region src/command-output/command-output.ts
|
|
14
270
|
/**
|
|
15
|
-
*
|
|
16
|
-
*
|
|
271
|
+
* AXI §6: a failure is a coded error on stdout, in the caller's format, with a `help` line saying
|
|
272
|
+
* what to do next. A `CliError` the command already built is rethrown untouched; anything else
|
|
273
|
+
* becomes `command-failed`, exit code 1.
|
|
17
274
|
*/
|
|
18
|
-
function fail(error, fallback) {
|
|
275
|
+
function fail(error, fallback, help) {
|
|
19
276
|
if (isCliError(error)) throw error;
|
|
20
|
-
|
|
21
|
-
|
|
277
|
+
throw new CliError(error instanceof Error ? error.message : fallback, {
|
|
278
|
+
code: "command-failed",
|
|
279
|
+
exitCode: exitCodes.error,
|
|
280
|
+
...help ? { help } : {},
|
|
281
|
+
cause: error
|
|
282
|
+
});
|
|
22
283
|
}
|
|
23
284
|
/**
|
|
24
285
|
* An answer that comes with a failing exit code. The cli prints only an answer a command returns, and
|
|
@@ -39,6 +300,22 @@ function collapseHome(home, path) {
|
|
|
39
300
|
function displayBinPath(home, executable) {
|
|
40
301
|
return executable ? collapseHome(home, executable) : "buddy-agent-harness";
|
|
41
302
|
}
|
|
303
|
+
/**
|
|
304
|
+
* `parseHarnesses` for a command's `--harness`: an unsupported name is a usage error, exit code 2.
|
|
305
|
+
* The registry stays free of clibuilder, which the library entry treats as an optional peer.
|
|
306
|
+
*/
|
|
307
|
+
function parseHarnessOption(value) {
|
|
308
|
+
try {
|
|
309
|
+
return parseHarnesses(value);
|
|
310
|
+
} catch (error) {
|
|
311
|
+
throw new CliError(error.message, {
|
|
312
|
+
code: "unsupported-harness",
|
|
313
|
+
exitCode: exitCodes.usage,
|
|
314
|
+
help: "Pass --harness as a comma-separated list of the supported names.",
|
|
315
|
+
cause: error
|
|
316
|
+
});
|
|
317
|
+
}
|
|
318
|
+
}
|
|
42
319
|
//#endregion
|
|
43
320
|
//#region src/dep-plugins/dep-plugins.ts
|
|
44
321
|
/** Generic marketplace names: a second registration under one of these replaces the first, silently. */
|
|
@@ -377,367 +654,118 @@ function reconcile({ catalog, catalogDir, root, installed, marketplaces, scoped
|
|
|
377
654
|
detail: "installed but no longer in the catalog; it will report a load failure until removed"
|
|
378
655
|
});
|
|
379
656
|
return {
|
|
380
|
-
actions,
|
|
381
|
-
...collision ? { collision } : {},
|
|
382
|
-
unregistered: !registration
|
|
383
|
-
};
|
|
384
|
-
}
|
|
385
|
-
//#endregion
|
|
386
|
-
//#region src/dep-plugins/dep-plugins.command.ts
|
|
387
|
-
function commandFor(runtime, action, marketplace) {
|
|
388
|
-
switch (action.kind) {
|
|
389
|
-
case "register": return runtime.register(CATALOG_DIR);
|
|
390
|
-
case "install": return runtime.install(action.subject);
|
|
391
|
-
case "update": {
|
|
392
|
-
const refresh = runtime.refreshMarketplace(marketplace);
|
|
393
|
-
const update = runtime.update(action.subject);
|
|
394
|
-
return refresh ? `${refresh} && ${update}` : update;
|
|
395
|
-
}
|
|
396
|
-
case "uninstall": return runtime.uninstall(action.subject);
|
|
397
|
-
}
|
|
398
|
-
}
|
|
399
|
-
function notesFor(derived) {
|
|
400
|
-
const notes = [];
|
|
401
|
-
if (derived.pnp) notes.push("Yarn Plug’n’Play is active: dependencies live inside zip archives, so no harness can install from them. Set nodeLinker: node-modules, or unplug the plugin dependencies.");
|
|
402
|
-
if (derived.genericName) notes.push(`Marketplace name "${derived.catalog.name}" is generic. Registering a second marketplace under a name already in use replaces the first silently, and the install that follows reports "already installed" — the repository then runs the other one's versions.`);
|
|
403
|
-
for (const { package: pkg } of derived.unresolved) notes.push(`Declared dependency "${pkg}" is not installed; install dependencies before generating.`);
|
|
404
|
-
return notes;
|
|
405
|
-
}
|
|
406
|
-
const depPluginsCommand = command({
|
|
407
|
-
name: "dep-plugins",
|
|
408
|
-
description: "Derive the marketplace catalog for plugins shipped by this repository’s dependencies, so a harness can install them. Writes the catalog; installing is the harness’s own job.",
|
|
409
|
-
options: {
|
|
410
|
-
root: {
|
|
411
|
-
description: "Repository directory. Defaults to the current directory.",
|
|
412
|
-
type: t.string().optional()
|
|
413
|
-
},
|
|
414
|
-
check: {
|
|
415
|
-
description: "Report whether the catalog is current without writing it. For CI and postinstall.",
|
|
416
|
-
type: t.boolean().optional()
|
|
417
|
-
}
|
|
418
|
-
},
|
|
419
|
-
run(args) {
|
|
420
|
-
try {
|
|
421
|
-
const root = args.root ?? process.cwd();
|
|
422
|
-
const derived = deriveCatalog(root);
|
|
423
|
-
const outcome = args.check ? catalogStatus(root, derived.catalog) === "unchanged" ? "current" : "would-change" : writeCatalog(root, derived.catalog);
|
|
424
|
-
const home = homedir();
|
|
425
|
-
const notes = notesFor(derived);
|
|
426
|
-
const detected = runtimes.filter((candidate) => candidate.installedOnMachine(home));
|
|
427
|
-
const harness = [];
|
|
428
|
-
const actions = [];
|
|
429
|
-
for (const runtime of detected) {
|
|
430
|
-
const state = runtime.state(home);
|
|
431
|
-
const delta = reconcile({
|
|
432
|
-
catalog: derived.catalog,
|
|
433
|
-
catalogDir: CATALOG_DIR,
|
|
434
|
-
root: resolve(root),
|
|
435
|
-
installed: state.installed,
|
|
436
|
-
marketplaces: state.marketplaces,
|
|
437
|
-
scoped: runtime.scoped
|
|
438
|
-
});
|
|
439
|
-
if (delta.collision) notes.push(`${runtime.name}: marketplace "${derived.catalog.name}" is already registered against ${delta.collision}. Registering over it replaces the other repository's silently, and the install that follows reports "already installed" — rename this repository's marketplace instead.`);
|
|
440
|
-
harness.push({
|
|
441
|
-
runtime: runtime.name,
|
|
442
|
-
status: delta.actions.length ? `${delta.actions.length} to apply` : "in sync"
|
|
443
|
-
});
|
|
444
|
-
for (const action of delta.actions) actions.push({
|
|
445
|
-
runtime: runtime.name,
|
|
446
|
-
do: commandFor(runtime, action, derived.catalog.name),
|
|
447
|
-
subject: action.subject,
|
|
448
|
-
why: action.detail
|
|
449
|
-
});
|
|
450
|
-
}
|
|
451
|
-
if (derived.plugins.length) notes.push(COPILOT_LIMITATION);
|
|
452
|
-
const report = {
|
|
453
|
-
catalog: CATALOG_PATH,
|
|
454
|
-
marketplace: derived.catalog.name,
|
|
455
|
-
outcome,
|
|
456
|
-
plugins: derived.plugins.length ? derived.plugins.map(({ plugin, package: pkg, version }) => ({
|
|
457
|
-
name: plugin,
|
|
458
|
-
package: pkg,
|
|
459
|
-
version
|
|
460
|
-
})) : "0 dependencies ship a plugin — nothing to install",
|
|
461
|
-
harness: harness.length ? harness : "no supported harness detected on this machine",
|
|
462
|
-
actions: actions.length ? actions : "0 actions — every detected harness matches the catalog",
|
|
463
|
-
...notes.length ? { notes } : {}
|
|
464
|
-
};
|
|
465
|
-
const answer = result(report);
|
|
466
|
-
return outcome === "would-change" ? answerThenFail(answer, this.format) : answer;
|
|
467
|
-
} catch (error) {
|
|
468
|
-
return fail(error, "Catalog generation failed.");
|
|
469
|
-
}
|
|
470
|
-
}
|
|
471
|
-
});
|
|
472
|
-
//#endregion
|
|
473
|
-
//#region src/diagnose-bridges/directory-files.ts
|
|
474
|
-
/** A directory that does not exist reads as empty: `doctor` never creates one to look at it. */
|
|
475
|
-
function filesUnder(directory) {
|
|
476
|
-
try {
|
|
477
|
-
return readdirSync(directory, {
|
|
478
|
-
recursive: true,
|
|
479
|
-
withFileTypes: true
|
|
480
|
-
}).filter((entry) => entry.isFile()).map((entry) => relative(directory, join(entry.parentPath, entry.name)).split(sep).join(posix.sep)).sort();
|
|
481
|
-
} catch {
|
|
482
|
-
return [];
|
|
483
|
-
}
|
|
484
|
-
}
|
|
485
|
-
//#endregion
|
|
486
|
-
//#region src/harness-registry/harness-registry.ts
|
|
487
|
-
/**
|
|
488
|
-
* Throws on a harness `skillsDirectories` does not confirm: treating it as native would silently
|
|
489
|
-
* drop a projection it may need.
|
|
490
|
-
*/
|
|
491
|
-
function skillsProjection(harness, scope, directories = skillsDirectories(harness)?.[scope]) {
|
|
492
|
-
const listed = directories ?? [];
|
|
493
|
-
const [first] = listed;
|
|
494
|
-
if (first === void 0) throw new Error(`cyber-agentkit records no ${scope} skills directories for ${harness}.`);
|
|
495
|
-
return listed.includes(".agents/skills") ? {} : { skillsDirectory: first };
|
|
496
|
-
}
|
|
497
|
-
/**
|
|
498
|
-
* The user-scope counterpart of the root `AGENTS.md`, relative to the home directory. No harness
|
|
499
|
-
* reads it natively; each loads it only through a user-scope `instructionBridge` (E-CC-18, E-CODEX-05,
|
|
500
|
-
* E-GEM-03, E-COPILOT-04, E-CUR-08).
|
|
501
|
-
*/
|
|
502
|
-
const globalInstructions = ".agents/AGENTS.md";
|
|
503
|
-
/**
|
|
504
|
-
* Skills directories come from `cyber-agentkit`, except for the harnesses it does not know
|
|
505
|
-
* (`devin-desktop`, `windsurf`); see `.research/agentic-configuration-standards/` for the rest.
|
|
506
|
-
*/
|
|
507
|
-
const harnessRegistry = [
|
|
508
|
-
{
|
|
509
|
-
name: "claude-code",
|
|
510
|
-
project: {
|
|
511
|
-
detect: ".claude",
|
|
512
|
-
...skillsProjection("claude-code", "project"),
|
|
513
|
-
shadowedBy: [
|
|
514
|
-
"CLAUDE.md",
|
|
515
|
-
".claude/CLAUDE.md",
|
|
516
|
-
"CLAUDE.local.md"
|
|
517
|
-
],
|
|
518
|
-
mcpConfig: {
|
|
519
|
-
path: ".mcp.json",
|
|
520
|
-
key: "mcpServers",
|
|
521
|
-
format: "json",
|
|
522
|
-
dialect: "claude-code"
|
|
523
|
-
},
|
|
524
|
-
nonstandard: [
|
|
525
|
-
{
|
|
526
|
-
path: ".claude/commands",
|
|
527
|
-
shape: "directory",
|
|
528
|
-
kind: "command"
|
|
529
|
-
},
|
|
530
|
-
{
|
|
531
|
-
path: ".claude/rules",
|
|
532
|
-
shape: "directory",
|
|
533
|
-
kind: "rule"
|
|
534
|
-
},
|
|
535
|
-
{
|
|
536
|
-
path: ".claude/agents",
|
|
537
|
-
shape: "directory",
|
|
538
|
-
kind: "subagent"
|
|
539
|
-
}
|
|
540
|
-
]
|
|
541
|
-
},
|
|
542
|
-
user: {
|
|
543
|
-
detect: ".claude",
|
|
544
|
-
...skillsProjection("claude-code", "user"),
|
|
545
|
-
relocatedBy: "CLAUDE_CONFIG_DIR",
|
|
546
|
-
emptyRelocatesToStart: true,
|
|
547
|
-
instructionBridge: {
|
|
548
|
-
kind: "import",
|
|
549
|
-
path: ".claude/CLAUDE.md",
|
|
550
|
-
line: `@~/${globalInstructions}`
|
|
551
|
-
}
|
|
552
|
-
}
|
|
553
|
-
},
|
|
554
|
-
{
|
|
555
|
-
name: "cursor",
|
|
556
|
-
project: {
|
|
557
|
-
detect: ".cursor",
|
|
558
|
-
...skillsProjection("cursor", "project"),
|
|
559
|
-
mcpConfig: {
|
|
560
|
-
path: ".cursor/mcp.json",
|
|
561
|
-
key: "mcpServers",
|
|
562
|
-
format: "json",
|
|
563
|
-
dialect: "cursor"
|
|
564
|
-
},
|
|
565
|
-
nonstandard: [
|
|
566
|
-
{
|
|
567
|
-
path: ".cursorrules",
|
|
568
|
-
shape: "file",
|
|
569
|
-
kind: "instructions"
|
|
570
|
-
},
|
|
571
|
-
{
|
|
572
|
-
path: ".cursor/rules",
|
|
573
|
-
shape: "directory",
|
|
574
|
-
kind: "rule"
|
|
575
|
-
},
|
|
576
|
-
{
|
|
577
|
-
path: ".cursor/commands",
|
|
578
|
-
shape: "directory",
|
|
579
|
-
kind: "command"
|
|
580
|
-
},
|
|
581
|
-
{
|
|
582
|
-
path: ".cursor/skills",
|
|
583
|
-
shape: "directory",
|
|
584
|
-
kind: "skill"
|
|
585
|
-
}
|
|
586
|
-
]
|
|
587
|
-
},
|
|
588
|
-
user: {
|
|
589
|
-
detect: ".cursor",
|
|
590
|
-
...skillsProjection("cursor", "user")
|
|
591
|
-
}
|
|
592
|
-
},
|
|
593
|
-
{
|
|
594
|
-
name: "codex",
|
|
595
|
-
project: {
|
|
596
|
-
detect: ".codex",
|
|
597
|
-
...skillsProjection("codex", "project"),
|
|
598
|
-
mcpConfig: {
|
|
599
|
-
path: ".codex/config.toml",
|
|
600
|
-
key: "mcp_servers",
|
|
601
|
-
format: "toml",
|
|
602
|
-
dialect: "codex",
|
|
603
|
-
shared: true
|
|
604
|
-
},
|
|
605
|
-
nonstandard: [{
|
|
606
|
-
path: ".codex/skills",
|
|
607
|
-
shape: "directory",
|
|
608
|
-
kind: "skill"
|
|
609
|
-
}]
|
|
610
|
-
},
|
|
611
|
-
user: {
|
|
612
|
-
detect: ".codex",
|
|
613
|
-
...skillsProjection("codex", "user"),
|
|
614
|
-
instructionBridge: {
|
|
615
|
-
kind: "symlink",
|
|
616
|
-
path: ".codex/AGENTS.md"
|
|
617
|
-
},
|
|
618
|
-
shadowedBy: [".codex/AGENTS.override.md"],
|
|
619
|
-
relocatedBy: "CODEX_HOME"
|
|
657
|
+
actions,
|
|
658
|
+
...collision ? { collision } : {},
|
|
659
|
+
unregistered: !registration
|
|
660
|
+
};
|
|
661
|
+
}
|
|
662
|
+
//#endregion
|
|
663
|
+
//#region src/dep-plugins/dep-plugins.command.ts
|
|
664
|
+
function commandFor(runtime, action, marketplace) {
|
|
665
|
+
switch (action.kind) {
|
|
666
|
+
case "register": return runtime.register(CATALOG_DIR);
|
|
667
|
+
case "install": return runtime.install(action.subject);
|
|
668
|
+
case "update": {
|
|
669
|
+
const refresh = runtime.refreshMarketplace(marketplace);
|
|
670
|
+
const update = runtime.update(action.subject);
|
|
671
|
+
return refresh ? `${refresh} && ${update}` : update;
|
|
620
672
|
}
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
{
|
|
639
|
-
path: ".github/skills",
|
|
640
|
-
shape: "directory",
|
|
641
|
-
kind: "skill"
|
|
642
|
-
}
|
|
643
|
-
]
|
|
673
|
+
case "uninstall": return runtime.uninstall(action.subject);
|
|
674
|
+
}
|
|
675
|
+
}
|
|
676
|
+
function notesFor(derived) {
|
|
677
|
+
const notes = [];
|
|
678
|
+
if (derived.pnp) notes.push("Yarn Plug’n’Play is active: dependencies live inside zip archives, so no harness can install from them. Set nodeLinker: node-modules, or unplug the plugin dependencies.");
|
|
679
|
+
if (derived.genericName) notes.push(`Marketplace name "${derived.catalog.name}" is generic. Registering a second marketplace under a name already in use replaces the first silently, and the install that follows reports "already installed" — the repository then runs the other one's versions.`);
|
|
680
|
+
for (const { package: pkg } of derived.unresolved) notes.push(`Declared dependency "${pkg}" is not installed; install dependencies before generating.`);
|
|
681
|
+
return notes;
|
|
682
|
+
}
|
|
683
|
+
const depPluginsCommand = command({
|
|
684
|
+
name: "dep-plugins",
|
|
685
|
+
description: "Derive the marketplace catalog for plugins shipped by this repository’s dependencies, so a harness can install them. Writes the catalog; installing is the harness’s own job.",
|
|
686
|
+
options: {
|
|
687
|
+
root: {
|
|
688
|
+
description: "Repository directory. Defaults to the current directory.",
|
|
689
|
+
type: t.string().optional()
|
|
644
690
|
},
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
relocatedBy: "COPILOT_HOME",
|
|
649
|
-
instructionBridge: {
|
|
650
|
-
kind: "symlink",
|
|
651
|
-
path: ".copilot/copilot-instructions.md"
|
|
652
|
-
}
|
|
691
|
+
check: {
|
|
692
|
+
description: "Report whether the catalog is current without writing it. For CI and postinstall.",
|
|
693
|
+
type: t.boolean().optional()
|
|
653
694
|
}
|
|
654
695
|
},
|
|
655
|
-
{
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
696
|
+
examples: [{
|
|
697
|
+
command: "buddy-agent-harness dep-plugins",
|
|
698
|
+
description: "Write the marketplace catalog for dependency plugins"
|
|
699
|
+
}, {
|
|
700
|
+
command: "buddy-agent-harness dep-plugins --check",
|
|
701
|
+
description: "Fail when the catalog is stale (CI)"
|
|
702
|
+
}],
|
|
703
|
+
run(args) {
|
|
704
|
+
try {
|
|
705
|
+
const root = args.root ?? process.cwd();
|
|
706
|
+
const derived = deriveCatalog(root);
|
|
707
|
+
const outcome = args.check ? catalogStatus(root, derived.catalog) === "unchanged" ? "current" : "would-change" : writeCatalog(root, derived.catalog);
|
|
708
|
+
const home = homedir();
|
|
709
|
+
const notes = notesFor(derived);
|
|
710
|
+
const detected = runtimes.filter((candidate) => candidate.installedOnMachine(home));
|
|
711
|
+
const harness = [];
|
|
712
|
+
const actions = [];
|
|
713
|
+
for (const runtime of detected) {
|
|
714
|
+
const state = runtime.state(home);
|
|
715
|
+
const delta = reconcile({
|
|
716
|
+
catalog: derived.catalog,
|
|
717
|
+
catalogDir: CATALOG_DIR,
|
|
718
|
+
root: resolve(root),
|
|
719
|
+
installed: state.installed,
|
|
720
|
+
marketplaces: state.marketplaces,
|
|
721
|
+
scoped: runtime.scoped
|
|
722
|
+
});
|
|
723
|
+
if (delta.collision) notes.push(`${runtime.name}: marketplace "${derived.catalog.name}" is already registered against ${delta.collision}. Registering over it replaces the other repository's silently, and the install that follows reports "already installed" — rename this repository's marketplace instead.`);
|
|
724
|
+
harness.push({
|
|
725
|
+
runtime: runtime.name,
|
|
726
|
+
status: delta.actions.length ? `${delta.actions.length} to apply` : "in sync"
|
|
727
|
+
});
|
|
728
|
+
for (const action of delta.actions) actions.push({
|
|
729
|
+
runtime: runtime.name,
|
|
730
|
+
do: commandFor(runtime, action, derived.catalog.name),
|
|
731
|
+
subject: action.subject,
|
|
732
|
+
why: action.detail
|
|
733
|
+
});
|
|
688
734
|
}
|
|
735
|
+
if (derived.plugins.length) notes.push(COPILOT_LIMITATION);
|
|
736
|
+
const report = {
|
|
737
|
+
catalog: CATALOG_PATH,
|
|
738
|
+
marketplace: derived.catalog.name,
|
|
739
|
+
outcome,
|
|
740
|
+
plugins: derived.plugins.length ? derived.plugins.map(({ plugin, package: pkg, version }) => ({
|
|
741
|
+
name: plugin,
|
|
742
|
+
package: pkg,
|
|
743
|
+
version
|
|
744
|
+
})) : "0 dependencies ship a plugin — nothing to install",
|
|
745
|
+
harness: harness.length ? harness : "no supported harness detected on this machine",
|
|
746
|
+
actions: actions.length ? actions : "0 actions — every detected harness matches the catalog",
|
|
747
|
+
...notes.length ? { notes } : {}
|
|
748
|
+
};
|
|
749
|
+
const answer = result(report);
|
|
750
|
+
return outcome === "would-change" ? answerThenFail(answer, this.format) : answer;
|
|
751
|
+
} catch (error) {
|
|
752
|
+
return fail(error, "Catalog generation failed.");
|
|
689
753
|
}
|
|
690
|
-
},
|
|
691
|
-
{
|
|
692
|
-
name: "devin-desktop",
|
|
693
|
-
project: { detect: ".devin" }
|
|
694
|
-
},
|
|
695
|
-
{
|
|
696
|
-
name: "windsurf",
|
|
697
|
-
project: {
|
|
698
|
-
detect: ".windsurf",
|
|
699
|
-
skillsDirectory: ".windsurf/skills",
|
|
700
|
-
nonstandard: [{
|
|
701
|
-
path: ".windsurfrules",
|
|
702
|
-
shape: "file",
|
|
703
|
-
kind: "instructions"
|
|
704
|
-
}, {
|
|
705
|
-
path: ".windsurf/rules",
|
|
706
|
-
shape: "directory",
|
|
707
|
-
kind: "rule"
|
|
708
|
-
}]
|
|
709
|
-
},
|
|
710
|
-
deprecated: "devin-desktop"
|
|
711
754
|
}
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
/**
|
|
718
|
-
* An unknown name throws rather than being dropped — silently falling back to the defaults would
|
|
719
|
-
* misreport what was diagnosed.
|
|
720
|
-
*/
|
|
721
|
-
function parseHarnesses(value) {
|
|
722
|
-
const requested = (value ?? "").split(",").map((name) => name.trim()).filter(Boolean);
|
|
723
|
-
const unsupported = requested.filter((name) => !isHarnessName(name));
|
|
724
|
-
if (unsupported.length) throw new Error(`Unsupported harness: ${unsupported.join(", ")}. Supported: ${harnessRegistry.map((harness) => harness.name).join(", ")}.`);
|
|
725
|
-
return requested.filter(isHarnessName);
|
|
726
|
-
}
|
|
727
|
-
/** Enabled whether or not the repository already contains their directories. */
|
|
728
|
-
const defaultHarnesses = ["claude-code", "cursor"];
|
|
729
|
-
function directoryExists(path) {
|
|
755
|
+
});
|
|
756
|
+
//#endregion
|
|
757
|
+
//#region src/diagnose-bridges/directory-files.ts
|
|
758
|
+
/** A directory that does not exist reads as empty: `doctor` never creates one to look at it. */
|
|
759
|
+
function filesUnder(directory) {
|
|
730
760
|
try {
|
|
731
|
-
return
|
|
761
|
+
return readdirSync(directory, {
|
|
762
|
+
recursive: true,
|
|
763
|
+
withFileTypes: true
|
|
764
|
+
}).filter((entry) => entry.isFile()).map((entry) => relative(directory, join(entry.parentPath, entry.name)).split(sep).join(posix.sep)).sort();
|
|
732
765
|
} catch {
|
|
733
|
-
return
|
|
766
|
+
return [];
|
|
734
767
|
}
|
|
735
768
|
}
|
|
736
|
-
/** The default harnesses, plus the preferred ones, plus every harness whose directory is present. */
|
|
737
|
-
function selectHarnesses(root, preferred) {
|
|
738
|
-
const enabled = /* @__PURE__ */ new Set([...defaultHarnesses, ...preferred]);
|
|
739
|
-
return harnessRegistry.filter((harness) => enabled.has(harness.name) || directoryExists(join(root, harness.project.detect)));
|
|
740
|
-
}
|
|
741
769
|
//#endregion
|
|
742
770
|
//#region src/diagnose-bridges/locator.ts
|
|
743
771
|
/** The locator as one string: the finding's `path`, and what a repair names. */
|
|
@@ -2204,10 +2232,13 @@ function referenceLayers({ packageRoot = dirname(packageGovernancesDir()), ...op
|
|
|
2204
2232
|
}
|
|
2205
2233
|
});
|
|
2206
2234
|
}
|
|
2207
|
-
const referenceCommand = createReferenceCommand({
|
|
2208
|
-
|
|
2209
|
-
|
|
2210
|
-
|
|
2235
|
+
const referenceCommand = createReferenceCommand({
|
|
2236
|
+
plugin: {
|
|
2237
|
+
name: PACKAGE_PLUGIN,
|
|
2238
|
+
root: dirname(packageGovernancesDir())
|
|
2239
|
+
},
|
|
2240
|
+
path: "buddy-agent-harness reference"
|
|
2241
|
+
});
|
|
2211
2242
|
//#endregion
|
|
2212
2243
|
//#region src/skill-projection/skill-projection.ts
|
|
2213
2244
|
function skillNames(skillsDirectory) {
|
|
@@ -2922,64 +2953,77 @@ function buildDoctorReport(bin, result, configuration = [], held = []) {
|
|
|
2922
2953
|
help: [...new Map(findings.map((finding) => [`${finding.repair.command}\u0000${finding.repair.instruction}`, finding.repair])).values()]
|
|
2923
2954
|
};
|
|
2924
2955
|
}
|
|
2925
|
-
const
|
|
2926
|
-
|
|
2927
|
-
|
|
2928
|
-
|
|
2929
|
-
root: {
|
|
2930
|
-
description: "Repository or package directory. Defaults to the current directory.",
|
|
2931
|
-
type: t.string().optional()
|
|
2932
|
-
},
|
|
2933
|
-
harness: {
|
|
2934
|
-
description: "Comma-separated harnesses to check in addition to Claude Code and Cursor, e.g. codex,gemini-cli.",
|
|
2935
|
-
type: t.string().optional()
|
|
2936
|
-
}
|
|
2956
|
+
const doctorOptions = {
|
|
2957
|
+
root: {
|
|
2958
|
+
description: "Repository or package directory. Defaults to the current directory.",
|
|
2959
|
+
type: t.string().optional()
|
|
2937
2960
|
},
|
|
2938
|
-
|
|
2939
|
-
|
|
2940
|
-
|
|
2941
|
-
|
|
2942
|
-
|
|
2943
|
-
|
|
2961
|
+
harness: {
|
|
2962
|
+
description: "Comma-separated harnesses to check in addition to Claude Code and Cursor, e.g. codex,gemini-cli.",
|
|
2963
|
+
type: t.string().optional()
|
|
2964
|
+
}
|
|
2965
|
+
};
|
|
2966
|
+
const doctorDescription = "Report whether this repository's harness bridges still resolve — skills into .agents/skills, instructions into AGENTS.md — and whether each harness's user-scope file loads ~/.agents/AGENTS.md. Read-only.";
|
|
2967
|
+
/** The live report `doctor` answers with, shared with the bare invocation of the CLI. */
|
|
2968
|
+
async function diagnoseReport(args) {
|
|
2969
|
+
try {
|
|
2970
|
+
const harnesses = parseHarnessOption(args.harness);
|
|
2971
|
+
const root = args.root ?? process.cwd();
|
|
2972
|
+
const home = homedir();
|
|
2973
|
+
const diagnosis = diagnoseBridges({
|
|
2974
|
+
root,
|
|
2975
|
+
...harnesses.length ? { harnesses } : {},
|
|
2976
|
+
cli: commandInvocation,
|
|
2977
|
+
home,
|
|
2978
|
+
env: process.env
|
|
2979
|
+
});
|
|
2980
|
+
const git = new GitBridgeState(root);
|
|
2981
|
+
const configuration = [
|
|
2982
|
+
...diagnoseConfiguration({
|
|
2944
2983
|
root,
|
|
2945
|
-
|
|
2946
|
-
cli: commandInvocation
|
|
2947
|
-
|
|
2948
|
-
|
|
2949
|
-
});
|
|
2950
|
-
const git = new GitBridgeState(root);
|
|
2951
|
-
const configuration = [
|
|
2952
|
-
...diagnoseConfiguration({
|
|
2953
|
-
root,
|
|
2954
|
-
git,
|
|
2955
|
-
cli: commandInvocation
|
|
2956
|
-
}),
|
|
2957
|
-
...diagnoseMcp({
|
|
2958
|
-
root,
|
|
2959
|
-
git,
|
|
2960
|
-
cli: commandInvocation
|
|
2961
|
-
}),
|
|
2962
|
-
...diagnoseNonstandard({
|
|
2963
|
-
root,
|
|
2964
|
-
cli: commandInvocation
|
|
2965
|
-
})
|
|
2966
|
-
];
|
|
2967
|
-
const { layers: rows } = listReferences$1(await referenceLayers({
|
|
2984
|
+
git,
|
|
2985
|
+
cli: commandInvocation
|
|
2986
|
+
}),
|
|
2987
|
+
...diagnoseMcp({
|
|
2968
2988
|
root,
|
|
2969
|
-
|
|
2970
|
-
|
|
2971
|
-
|
|
2972
|
-
|
|
2973
|
-
|
|
2974
|
-
|
|
2975
|
-
|
|
2976
|
-
|
|
2977
|
-
|
|
2978
|
-
|
|
2979
|
-
|
|
2980
|
-
|
|
2981
|
-
|
|
2982
|
-
}
|
|
2989
|
+
git,
|
|
2990
|
+
cli: commandInvocation
|
|
2991
|
+
}),
|
|
2992
|
+
...diagnoseNonstandard({
|
|
2993
|
+
root,
|
|
2994
|
+
cli: commandInvocation
|
|
2995
|
+
})
|
|
2996
|
+
];
|
|
2997
|
+
const { layers: rows } = listReferences$1(await referenceLayers({
|
|
2998
|
+
root,
|
|
2999
|
+
home,
|
|
3000
|
+
platform: process.platform,
|
|
3001
|
+
env: process.env
|
|
3002
|
+
}));
|
|
3003
|
+
const held = rows.filter(({ tier }) => tier !== "plugin").map(({ name, tier, path, outcome }) => ({
|
|
3004
|
+
name,
|
|
3005
|
+
tier,
|
|
3006
|
+
path: collapseHome(home, path),
|
|
3007
|
+
status: outcome
|
|
3008
|
+
}));
|
|
3009
|
+
return buildDoctorReport(displayBinPath(home, process.argv[1]), diagnosis, configuration, held);
|
|
3010
|
+
} catch (error) {
|
|
3011
|
+
return fail(error, "Harness diagnosis failed.");
|
|
3012
|
+
}
|
|
3013
|
+
}
|
|
3014
|
+
const doctorCommand = command({
|
|
3015
|
+
name: "doctor",
|
|
3016
|
+
description: doctorDescription,
|
|
3017
|
+
options: doctorOptions,
|
|
3018
|
+
examples: [{
|
|
3019
|
+
command: "buddy-agent-harness doctor",
|
|
3020
|
+
description: "Check the current repository"
|
|
3021
|
+
}, {
|
|
3022
|
+
command: "buddy-agent-harness doctor --harness codex,gemini-cli",
|
|
3023
|
+
description: "Also check Codex and Gemini CLI"
|
|
3024
|
+
}],
|
|
3025
|
+
async run(args) {
|
|
3026
|
+
return result(await diagnoseReport(args));
|
|
2983
3027
|
}
|
|
2984
3028
|
});
|
|
2985
3029
|
//#endregion
|
|
@@ -3010,6 +3054,10 @@ const governanceListCommand = command({
|
|
|
3010
3054
|
root: rootOption,
|
|
3011
3055
|
"overrides-only": overridesOnlyOption
|
|
3012
3056
|
},
|
|
3057
|
+
examples: [{
|
|
3058
|
+
command: "buddy-agent-harness governance list",
|
|
3059
|
+
description: "List the governances the layers hold"
|
|
3060
|
+
}],
|
|
3013
3061
|
run(args) {
|
|
3014
3062
|
process.stderr.write(GOVERNANCE_DEPRECATED);
|
|
3015
3063
|
try {
|
|
@@ -3046,16 +3094,21 @@ const governanceShowCommand = command({
|
|
|
3046
3094
|
root: rootOption,
|
|
3047
3095
|
"overrides-only": overridesOnlyOption
|
|
3048
3096
|
},
|
|
3097
|
+
examples: [{
|
|
3098
|
+
command: "buddy-agent-harness governance show skill-design",
|
|
3099
|
+
description: "Print one governance document"
|
|
3100
|
+
}],
|
|
3049
3101
|
run(args) {
|
|
3050
3102
|
const format = this.format;
|
|
3051
3103
|
process.stderr.write(GOVERNANCE_DEPRECATED);
|
|
3052
3104
|
try {
|
|
3053
3105
|
const name = parseGovernanceName(args.name);
|
|
3054
3106
|
const found = resolveGovernance(name, layersFor(args));
|
|
3055
|
-
if (!found) {
|
|
3056
|
-
|
|
3057
|
-
|
|
3058
|
-
|
|
3107
|
+
if (!found) throw new CliError(args["overrides-only"] ? `no override for governance "${name}" in the project, user, or machine-wide layer.` : `no governance named "${name}" in any layer.`, {
|
|
3108
|
+
code: "governance-not-found",
|
|
3109
|
+
details: { name },
|
|
3110
|
+
help: ref("reference list", {}, "see what is available")
|
|
3111
|
+
});
|
|
3059
3112
|
const report = {
|
|
3060
3113
|
name: found.name,
|
|
3061
3114
|
scope: found.scope,
|
|
@@ -3136,9 +3189,16 @@ const initCommand = command({
|
|
|
3136
3189
|
type: t.string().optional()
|
|
3137
3190
|
}
|
|
3138
3191
|
},
|
|
3192
|
+
examples: [{
|
|
3193
|
+
command: "buddy-agent-harness init",
|
|
3194
|
+
description: "Set up skills for Claude Code and Cursor"
|
|
3195
|
+
}, {
|
|
3196
|
+
command: "buddy-agent-harness init --harness codex --copy",
|
|
3197
|
+
description: "Also enable Codex, copying skills instead of linking"
|
|
3198
|
+
}],
|
|
3139
3199
|
run(args) {
|
|
3140
3200
|
try {
|
|
3141
|
-
const harnesses =
|
|
3201
|
+
const harnesses = parseHarnessOption(args.harness);
|
|
3142
3202
|
return result(initializeHarnesses({
|
|
3143
3203
|
root: args.root ?? process.cwd(),
|
|
3144
3204
|
...harnesses.length ? { harnesses } : {},
|
|
@@ -3594,6 +3654,13 @@ const mcpReconcileCommand = command({
|
|
|
3594
3654
|
type: t.array(t.string()).optional()
|
|
3595
3655
|
}
|
|
3596
3656
|
},
|
|
3657
|
+
examples: [{
|
|
3658
|
+
command: "buddy-agent-harness mcp reconcile",
|
|
3659
|
+
description: "List harness-side changes the golden set lacks"
|
|
3660
|
+
}, {
|
|
3661
|
+
command: "buddy-agent-harness mcp reconcile --accept <path>",
|
|
3662
|
+
description: "Import one approved field"
|
|
3663
|
+
}],
|
|
3597
3664
|
run(args) {
|
|
3598
3665
|
try {
|
|
3599
3666
|
const root = args.root ?? process.cwd();
|
|
@@ -3605,19 +3672,17 @@ const mcpReconcileCommand = command({
|
|
|
3605
3672
|
});
|
|
3606
3673
|
if (plan.kind === "unreadable") {
|
|
3607
3674
|
const at = plan.position ? ` at line ${plan.position.line}, column ${plan.position.column}` : "";
|
|
3608
|
-
|
|
3609
|
-
|
|
3610
|
-
|
|
3611
|
-
|
|
3612
|
-
process.stderr.write(`error: nothing written.\n${plan.reasons.map((reason) => `- ${reason}\n`).join("")}`);
|
|
3613
|
-
throw CliError.reported(exitCodes.error);
|
|
3675
|
+
throw new CliError(`${goldenSetPath} does not parse${at}.`, {
|
|
3676
|
+
code: "golden-set-unreadable",
|
|
3677
|
+
help: `Fix the TOML syntax in ${goldenSetPath}, then re-run.`
|
|
3678
|
+
});
|
|
3614
3679
|
}
|
|
3615
|
-
if (plan.kind === "
|
|
3616
|
-
|
|
3617
|
-
|
|
3618
|
-
|
|
3619
|
-
record: "not written"
|
|
3680
|
+
if (plan.kind === "rejected") throw new CliError("nothing written.", {
|
|
3681
|
+
code: "accept-rejected",
|
|
3682
|
+
details: { reasons: plan.reasons },
|
|
3683
|
+
help: ref("mcp reconcile", {}, "list the fields that can be approved")
|
|
3620
3684
|
});
|
|
3685
|
+
if (plan.kind === "absent") return empty(`0 servers — no golden set at ${goldenSetPath}`, { help: `Create ${goldenSetPath} first; there is nothing to reconcile into.` });
|
|
3621
3686
|
const report = {
|
|
3622
3687
|
golden: goldenSetPath,
|
|
3623
3688
|
mode: plan.written ? "written — only the fields named by --accept" : "dry run — nothing written; re-run with --accept <path> for each approved field",
|
|
@@ -3882,6 +3947,13 @@ const mcpProjectCommand = command({
|
|
|
3882
3947
|
type: t.boolean().optional()
|
|
3883
3948
|
}
|
|
3884
3949
|
},
|
|
3950
|
+
examples: [{
|
|
3951
|
+
command: "buddy-agent-harness mcp project",
|
|
3952
|
+
description: "Preview what would be projected"
|
|
3953
|
+
}, {
|
|
3954
|
+
command: "buddy-agent-harness mcp project --write",
|
|
3955
|
+
description: "Project the golden set into each harness"
|
|
3956
|
+
}],
|
|
3885
3957
|
run(args) {
|
|
3886
3958
|
try {
|
|
3887
3959
|
const root = args.root ?? process.cwd();
|
|
@@ -3893,15 +3965,12 @@ const mcpProjectCommand = command({
|
|
|
3893
3965
|
});
|
|
3894
3966
|
if (plan.kind === "unreadable") {
|
|
3895
3967
|
const at = plan.position ? ` at line ${plan.position.line}, column ${plan.position.column}` : "";
|
|
3896
|
-
|
|
3897
|
-
|
|
3968
|
+
throw new CliError(`${goldenSetPath} does not parse${at}.`, {
|
|
3969
|
+
code: "golden-set-unreadable",
|
|
3970
|
+
help: `Fix the TOML syntax in ${goldenSetPath}, then re-run.`
|
|
3971
|
+
});
|
|
3898
3972
|
}
|
|
3899
|
-
if (plan.kind === "absent") return
|
|
3900
|
-
golden: `0 servers — no golden set at ${goldenSetPath}`,
|
|
3901
|
-
mode: "nothing to project",
|
|
3902
|
-
actions: "0 changes",
|
|
3903
|
-
record: "not written"
|
|
3904
|
-
});
|
|
3973
|
+
if (plan.kind === "absent") return empty(`0 servers — no golden set at ${goldenSetPath}`, { help: [`Create ${goldenSetPath} with the MCP servers to project.`, ref("mcp project", {}, "preview the projection")] });
|
|
3905
3974
|
const report = {
|
|
3906
3975
|
golden: goldenSetPath,
|
|
3907
3976
|
mode: write ? "written" : "dry run — nothing written; re-run with --write to apply",
|
|
@@ -3943,6 +4012,19 @@ function app(format) {
|
|
|
3943
4012
|
version,
|
|
3944
4013
|
description: rootCommand.description,
|
|
3945
4014
|
format
|
|
4015
|
+
}).default({
|
|
4016
|
+
description: "Report whether this repository's harness bridges resolve (the same as `doctor`).",
|
|
4017
|
+
options: doctorCommand.options,
|
|
4018
|
+
async run(args) {
|
|
4019
|
+
const { bin: _bin, ...report } = await diagnoseReport({
|
|
4020
|
+
root: args["root"],
|
|
4021
|
+
harness: args["harness"]
|
|
4022
|
+
});
|
|
4023
|
+
return result({
|
|
4024
|
+
...homeHeader({ description: rootCommand.description }),
|
|
4025
|
+
...report
|
|
4026
|
+
});
|
|
4027
|
+
}
|
|
3946
4028
|
}).command(first));
|
|
3947
4029
|
}
|
|
3948
4030
|
const textByDefault = {
|