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.
Files changed (37) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/.cursor-plugin/plugin.json +1 -1
  4. package/CHANGELOG.md +31 -0
  5. package/dist/cli.mjs +2227 -840
  6. package/dist/index.d.mts.map +1 -1
  7. package/dist/index.mjs +521 -439
  8. package/dist/index.mjs.map +1 -1
  9. package/dist/skill-scripts/doctor.mjs +74 -67
  10. package/dist/skill-scripts/init.mjs +74 -67
  11. package/dist/skill-scripts/mcp.mjs +74 -67
  12. package/llms.txt +2 -1
  13. package/package.json +4 -4
  14. package/plugin.json +1 -1
  15. package/skills/doctor-buddy-agent-harness/README.md +1 -1
  16. package/skills/doctor-buddy-agent-harness/SKILL.md +1 -1
  17. package/skills/doctor-buddy-agent-harness/scripts/doctor.mjs +74 -67
  18. package/skills/enhance/SKILL.md +1 -1
  19. package/skills/enhance/references/list-identifiers.history.md +9 -1
  20. package/skills/enhance/references/list-identifiers.md +6 -9
  21. package/skills/enhance/scripts/doctor.mjs +74 -67
  22. package/skills/init-buddy-agent-harness/SKILL.md +2 -2
  23. package/skills/init-buddy-agent-harness/references/standard.md +1 -1
  24. package/skills/init-buddy-agent-harness/scripts/doctor.mjs +74 -67
  25. package/skills/init-buddy-agent-harness/scripts/init.mjs +74 -67
  26. package/skills/repair/SKILL.md +1 -1
  27. package/skills/repair/scripts/doctor.mjs +74 -67
  28. package/skills/repair/scripts/mcp.mjs +74 -67
  29. package/src/cli.ts +13 -3
  30. package/src/command-output/command-output.ts +28 -5
  31. package/src/dep-plugins/dep-plugins.command.ts +4 -0
  32. package/src/diagnose-bridges/doctor.command.ts +67 -49
  33. package/src/governance-overrides/governance.command.ts +13 -8
  34. package/src/initialize-harnesses/init.command.ts +9 -3
  35. package/src/project-mcp/mcp.command.ts +15 -9
  36. package/src/reconcile-mcp/reconcile.command.ts +17 -11
  37. 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
- * Reports a failure on stderr, not stdout — stdout carries what an agent parses — and fails the cli
16
- * with the exit code. A `CliError` the cli already reports is rethrown untouched.
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
- process.stderr.write(`error: ${error instanceof Error ? error.message : fallback}\n`);
21
- throw CliError.reported(exitCodes.error);
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
- name: "copilot-cli",
624
- project: {
625
- detect: ".github/skills",
626
- ...skillsProjection("copilot-cli", "project"),
627
- nonstandard: [
628
- {
629
- path: ".github/copilot-instructions.md",
630
- shape: "file",
631
- kind: "instructions"
632
- },
633
- {
634
- path: ".github/instructions",
635
- shape: "directory",
636
- kind: "instructions"
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
- user: {
646
- detect: ".copilot",
647
- ...skillsProjection("copilot-cli", "user"),
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
- name: "gemini-cli",
657
- project: {
658
- detect: ".gemini",
659
- ...skillsProjection("gemini-cli", "project"),
660
- instructionBridge: {
661
- kind: "settings-entry",
662
- path: ".gemini/settings.json",
663
- key: "context.fileName"
664
- },
665
- mcpConfig: {
666
- path: ".gemini/settings.json",
667
- key: "mcpServers",
668
- format: "json",
669
- dialect: "gemini-cli",
670
- shared: true
671
- },
672
- nonstandard: [{
673
- path: "GEMINI.md",
674
- shape: "file",
675
- kind: "instructions"
676
- }, {
677
- path: ".gemini/skills",
678
- shape: "directory",
679
- kind: "skill"
680
- }]
681
- },
682
- user: {
683
- detect: ".gemini",
684
- ...skillsProjection("gemini-cli", "user"),
685
- instructionBridge: {
686
- kind: "symlink",
687
- path: ".gemini/GEMINI.md"
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
- const harnessNames = new Set(harnessRegistry.map((harness) => harness.name));
714
- function isHarnessName(value) {
715
- return harnessNames.has(value);
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 lstatSync(path).isDirectory();
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 false;
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({ plugin: {
2208
- name: PACKAGE_PLUGIN,
2209
- root: dirname(packageGovernancesDir())
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 doctorCommand = command({
2926
- name: "doctor",
2927
- description: "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.",
2928
- options: {
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
- async run(args) {
2939
- try {
2940
- const harnesses = parseHarnesses(args.harness);
2941
- const root = args.root ?? process.cwd();
2942
- const home = homedir();
2943
- const diagnosis = diagnoseBridges({
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
- ...harnesses.length ? { harnesses } : {},
2946
- cli: commandInvocation,
2947
- home,
2948
- env: process.env
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
- home,
2970
- platform: process.platform,
2971
- env: process.env
2972
- }));
2973
- const held = rows.filter(({ tier }) => tier !== "plugin").map(({ name, tier, path, outcome }) => ({
2974
- name,
2975
- tier,
2976
- path: collapseHome(home, path),
2977
- status: outcome
2978
- }));
2979
- return result(buildDoctorReport(displayBinPath(home, process.argv[1]), diagnosis, configuration, held));
2980
- } catch (error) {
2981
- return fail(error, "Harness diagnosis failed.");
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
- process.stderr.write(args["overrides-only"] ? `error: no override for governance "${name}" in the project, user, or machine-wide layer.\n` : `error: no governance named "${name}" in any layer.\n`);
3057
- throw CliError.reported(exitCodes.error);
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 = parseHarnesses(args.harness);
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
- process.stderr.write(`error: ${goldenSetPath} does not parse${at}.\n`);
3609
- throw CliError.reported(exitCodes.error);
3610
- }
3611
- if (plan.kind === "rejected") {
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 === "absent") return result({
3616
- golden: `0 servers — no golden set at ${goldenSetPath}`,
3617
- mode: "nothing to reconcile into",
3618
- fields: "0 fields",
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
- process.stderr.write(`error: ${goldenSetPath} does not parse${at}.\n`);
3897
- throw CliError.reported(exitCodes.error);
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 result({
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 = {