@execuro-sw-ecosystem/sw-ecosystem-agentic-harness 0.1.5 → 0.1.7

package/lib/guide.mjs

@@ -21,16 +21,16 @@ registers the MCP servers and permission rules they depend on.
 
 1. \`${RUN} install\`
    The whole install in one command. It never prompts for consent — typing
-   the verb is the consent — but it does still need to know **which** host(s)
-   to write into, resolved in order: \`--host\`, if given; else the hosts a
-   lock file already records, if this is a re-run; else, with a real
+   the verb is the consent — but it does still need to know **which** coding
+   agent(s) to write into, resolved in order: \`--agent\`, if given; else the
+   agents a lock file already records, if this is a re-run; else, with a real
    terminal attached, an interactive picker; else it exits 2 with the four
-   \`${RUN} install --host <h>\` commands as \`help\` rather than guess or
+   \`${RUN} install --agent <a>\` commands as \`help\` rather than guess or
    hang — Codex's question tool does not block outside Plan mode, and CI has
-   no terminal, so a skill invoking this must always pass \`--host\`.
+   no terminal, so a skill invoking this must always pass \`--agent\`.
 
 2. \`${RUN} status\`
-   Read-only, optional. Reports which hosts are present, what is already
+   Read-only, optional. Reports which agents are present, what is already
    installed, and anything that has drifted since it was installed. Always safe.
 
 3. \`${RUN} plan\`
@@ -40,21 +40,26 @@ registers the MCP servers and permission rules they depend on.
 4. \`${RUN} apply --yes\`
    The scriptable name for the same write \`install\` performs — use it for
    re-runs and repairs. It refuses without \`--yes\`, and resolves which
-   host(s) to touch the same way \`install\` does (see step 1).
+   agent(s) to touch the same way \`install\` does (see step 1).
 
 5. \`${RUN} uninstall --yes\`
    Removes what the lock file records and reverts the managed config blocks.
 
 ## Flags
 
-  --host claude-code|codex|copilot|cursor   select one host, repeatable —
-                                             see the host-resolution order in
-                                             step 1 above; a skill invoking
-                                             \`install\`/\`apply\` must always
-                                             pass it, since it has no terminal
+  --agent claude-code|codex|copilot|cursor  select one coding agent,
+                                             repeatable — see the resolution
+                                             order in step 1 above; a skill
+                                             invoking \`install\`/\`apply\` must
+                                             always pass it, since it has no
+                                             terminal
   --scope project|user                      default: project
   --root <path>                             default: the current directory
   --no-extra-components                     skip the optional extra-component skills
+  --json                                    print the result object instead of
+                                             the human summary — a skill or
+                                             agent always passes this
+  --verbose                                 include the per-file detail
 
 ## Optional extra components
 
@@ -73,11 +78,14 @@ The exact command is also in a \`skipped\` action's \`remedy\`, and in
 
 ## What you can rely on
 
-- **stdout is exactly one JSON object.** Every successful result carries a
-  \`next_step\` string: the literal command to run next. Errors carry a
-  \`help\` array of runnable commands.
+- **\`--json\` puts exactly one JSON object on stdout.** Every successful
+  result carries a \`next_step\` string: the literal command to run next.
+  Errors carry a \`help\` array of runnable commands. Without \`--json\`,
+  \`install\`, \`status\`, \`plan\` and \`uninstall\` print a short human
+  summary of that same object instead — same body, one view for a person and
+  one for a program. Anything parsing this output must pass \`--json\`.
 - **Exit codes:** 0 success, 2 usage error (your invocation was wrong,
-  including \`install\`/\`apply\` run with no \`--host\`, no existing lock and
+  including \`install\`/\`apply\` run with no \`--agent\`, no existing lock and
   no terminal to ask on), 1 the work could not be done.
 - **Nothing is silently overwritten.** A file we did not install, or one you
   edited after we installed it, is reported as \`conflict\` or \`drift\` and
@@ -100,9 +108,9 @@ trailing commas is never rewritten at all; it becomes a manual step instead.
 
 ## After applying
 
-Every host reads its configuration at startup. The result's \`help\` array
-names the restart or reload each one needs — pass it on to the user rather
-than assuming the change is already live.
+Every coding agent reads its configuration at startup. The result's \`help\`
+array names the restart or reload each one needs — pass it on to the user
+rather than assuming the change is already live.
 
 ## Keeping it current
 
@@ -122,7 +130,7 @@ export async function main() {
   return out.ok('guide', {
     version: PKG_VERSION,
     next_step: `${RUN} install`,
-    help: [`${RUN} install`, `${RUN} status`, `${RUN} plan`, `${RUN} apply --yes`],
+    help: [`${RUN} install`, `${RUN} status --json`, `${RUN} plan --json`, `${RUN} apply --yes --json`],
     guide: GUIDE,
   });
 }

package/lib/hosts.mjs

@@ -4,7 +4,7 @@
 // Detection is marker-directory existence only — no network, no process scan,
 // no `which`. It feeds `status` reporting only; it never selects which hosts
 // a write command touches. Which hosts get written to is decided by
-// commands.mjs's `resolveHosts()` chain (`--host`, then a recorded lock,
+// commands.mjs's `resolveAgents()` chain (`--agent`, then a recorded lock,
 // then a TTY prompt, then a usage error) — detection has no vote there.
 
 import { homedir } from 'node:os';
@@ -17,7 +17,7 @@ import { renderTomlTable, tomlTableExists, findFence } from './merge.mjs';
 import { readTextMaybe } from './fsx.mjs';
 import { EXTRA_COMPONENTS } from './extra-components.mjs';
 
-export const HOSTS = ['claude-code', 'codex', 'copilot', 'cursor'];
+export const AGENTS = ['claude-code', 'codex', 'copilot', 'cursor'];
 
 /** Where each host reads its skills from — the base every skill-copy and
  * extra-component skill-copy action is rooted at. */
@@ -45,7 +45,7 @@ export function hostRoot(scope) {
  * but it matches the documented pattern and keeps a slow stat from serialising.
  */
 export async function detectAll(ctx) {
-  return Promise.all(HOSTS.map((id) => Promise.resolve(detect(id, ctx))));
+  return Promise.all(AGENTS.map((id) => Promise.resolve(detect(id, ctx))));
 }
 
 export function detect(id, ctx) {
@@ -67,10 +67,10 @@ export function detect(id, ctx) {
 
 // --------------------------------------------------------------- plans
 
-/** Build the full action list for the selected hosts. */
+/** Build the full action list for the selected agents. */
 export function buildPlan(ctx) {
   const actions = [];
-  for (const id of ctx.hosts) actions.push(...planFor(id, ctx));
+  for (const id of ctx.agents) actions.push(...planFor(id, ctx));
   // Shared targets are emitted per host; the id dedupe collapses them.
   return actions;
 }
@@ -249,10 +249,10 @@ function planCursor(ctx) {
   const out = [];
   // Cursor reads `.claude/skills/` and `.claude/agents/` directly. If Claude
   // Code is also being installed, or already is, there is nothing to duplicate.
-  // `ctx.hosts` is narrowed to one host while previewing, so the question
+  // `ctx.agents` is narrowed to one agent while previewing, so the question
   // "is Claude Code also being installed?" must be asked of the user's actual
-  // selection, which `selectedHosts` carries unchanged.
-  const selected = ctx.selectedHosts ?? ctx.hosts;
+  // selection, which `selectedAgents` carries unchanged.
+  const selected = ctx.selectedAgents ?? ctx.agents;
   const claudeTrees = selected.includes('claude-code')
     || (isDir(abs(ctx.root, '.claude/skills')) && isDir(abs(ctx.root, '.claude/agents')));
   if (!claudeTrees) {

package/lib/lock.mjs

@@ -28,7 +28,7 @@ export function empty(scope) {
     installed_at: null,
     updated_at: null,
     platform: process.platform,
-    hosts: {},
+    agents: {},
     files: {},
     dirs: [],
     json_pointers: [],
@@ -57,7 +57,12 @@ export function read(root, scope) {
         `version of ${PKG_NAME} (${PKG_VERSION}) does not understand.`,
     );
   }
-  return { ...empty(scope), ...lock };
+  // Locks written before the `--host` -> `--agent` rename record the
+  // selection under `hosts`. Read either, write `agents` — missing this
+  // would make every existing install look like it had never chosen an
+  // agent, and send it straight to the exit-2 "no --agent given" path.
+  const { hosts, ...rest } = lock;
+  return { ...empty(scope), ...rest, agents: lock.agents ?? hosts ?? {} };
 }
 
 export function write(root, lock) {
@@ -68,7 +73,7 @@ export function write(root, lock) {
 }
 
 /** Fold a batch of executed entries into the lock. */
-export function record(lock, entries, { host, version = PKG_VERSION } = {}) {
+export function record(lock, entries, { agent, version = PKG_VERSION } = {}) {
   const next = {
     ...lock,
     files: { ...lock.files },
@@ -77,7 +82,7 @@ export function record(lock, entries, { host, version = PKG_VERSION } = {}) {
     rules: [...lock.rules],
     fences: [...lock.fences],
     manual: [...lock.manual],
-    hosts: { ...lock.hosts },
+    agents: { ...lock.agents },
   };
   for (const entry of entries) {
     if (!entry) continue;
@@ -121,7 +126,7 @@ export function record(lock, entries, { host, version = PKG_VERSION } = {}) {
         break;
     }
   }
-  if (host) next.hosts[host] = { installed_at: new Date().toISOString(), version };
+  if (agent) next.agents[agent] = { installed_at: new Date().toISOString(), version };
   return next;
 }
 

package/lib/out.mjs

@@ -1,14 +1,19 @@
 // Output contract shared by every sw-ecosystem-agentic-harness subcommand.
 //
-// stdout carries exactly one JSON object and nothing else. Its keys are
+// There is one result object per run. `--json` prints it verbatim: keys
 // ordered small-first with the big payload LAST, so an agent that reads only
 // the head of the output already knows whether it worked and what to run next.
+// Without `--json` the same object is rendered for a human by lib/render.mjs —
+// the object is the model, the renderer is only a view, and neither can drift
+// from the other because there is only ever one body.
 //
-// stderr carries progress and warnings that are not part of the result.
+// Human text goes to stdout: it is the result, not progress. stderr carries
+// progress, warnings and the interactive picker — never part of the result.
 //
-// The contract: structured JSON on stdout, a mandatory `next_step` on every
-// success, `exit 2` on a usage error carrying a `help` array of runnable
-// commands.
+// The contract: a mandatory `next_step` on every success, `exit 2` on a usage
+// error carrying a `help` array of runnable commands.
+
+import { render } from './render.mjs';
 
 export const EXIT_OK = 0;
 export const EXIT_FAIL = 1;
@@ -19,8 +24,24 @@ export function json(value) {
   return `${JSON.stringify(value, null, 2)}\n`;
 }
 
+// Read from argv rather than threaded through every call: `bin/cli.mjs`
+// dispatches some usage errors before any flag parsing has happened, and those
+// must honour `--json` too. `setFormat`/`setVerbose` exist so a unit test can
+// drive this without re-spawning the process.
+let format = process.argv.includes('--json') ? 'json' : 'human';
+let verbose = process.argv.includes('--verbose');
+
+export function setFormat(value) { format = value === 'json' ? 'json' : 'human'; }
+export function setVerbose(value) { verbose = value === true; }
+export function isJson() { return format === 'json'; }
+
 function emit(body, code) {
-  process.stdout.write(json(body));
+  // `guide` is already prose inside its own body; rendering it would only
+  // hide it. Everything else gets the human view unless `--json` asked.
+  const asJson = format === 'json' || body.command === 'guide';
+  process.stdout.write(asJson
+    ? json(body)
+    : render(body, { verbose, color: process.stdout.isTTY === true }));
   process.exitCode = code;
   return code;
 }

package/lib/prompt.mjs

@@ -1,42 +1,37 @@
-// The interactive host picker. Used only when `apply`/`install` reach step 3
-// of the host-resolution chain: no `--host`, no lock to reuse, but a real
+// The interactive agent picker. Used only when `apply`/`install` reach step 3
+// of the agent-resolution chain: no `--agent`, no lock to reuse, but a real
 // terminal to ask on.
 //
 // node:readline only — the package has zero dependencies and that must not
-// change. Every prompt and echo goes to STDERR, never stdout: stdout carries
-// exactly one JSON object per run and every skill parses it, so a menu on
-// stdout would corrupt that contract. This module never inspects
-// `process.stdin.isTTY` itself — the caller decides whether to invoke it.
+// change. Every prompt and echo goes to STDERR, never stdout: the picker is an
+// interaction, not the result, and stdout carries the result alone — under
+// `--json` a menu there would corrupt the object every skill parses.
+// This module never inspects `process.stdin.isTTY` itself — the caller decides
+// whether to invoke it.
 
 import { createInterface } from 'node:readline';
-
-const LABELS = {
-  'claude-code': 'Claude Code',
-  codex: 'Codex',
-  copilot: 'GitHub Copilot',
-  cursor: 'Cursor',
-};
+import { LABELS } from './render.mjs';
 
 /**
  * Pure parsing, no I/O — so it can be unit-tested without a TTY.
  *
- * Accepts comma-separated 1-based indexes into `hosts` (e.g. "1,3"), the
- * word "all", or an empty string — both of the latter two mean every host,
+ * Accepts comma-separated 1-based indexes into `agents` (e.g. "1,3"), the
+ * word "all", or an empty string — both of the latter two mean every agent,
  * made explicit rather than left as a silent default. Throws a short,
  * human-readable `Error` on anything else (out of range, not a number,
  * nothing at all).
  */
-export function parseSelection(input, hosts) {
+export function parseSelection(input, agents) {
   const trimmed = (input ?? '').trim();
-  if (trimmed === '' || trimmed.toLowerCase() === 'all') return [...hosts];
+  if (trimmed === '' || trimmed.toLowerCase() === 'all') return [...agents];
   const parts = trimmed.split(',').map((p) => p.trim()).filter(Boolean);
   if (!parts.length) throw new Error('no selection given');
   const chosen = [];
   for (const part of parts) {
     if (!/^\d+$/.test(part)) throw new Error(`not a number: "${part}"`);
     const n = Number(part);
-    if (n < 1 || n > hosts.length) throw new Error(`out of range 1-${hosts.length}: ${part}`);
-    const id = hosts[n - 1];
+    if (n < 1 || n > agents.length) throw new Error(`out of range 1-${agents.length}: ${part}`);
+    const id = agents[n - 1];
     if (!chosen.includes(id)) chosen.push(id);
   }
   return chosen;
@@ -47,20 +42,20 @@ function question(rl, text) {
 }
 
 /**
- * Ask which host(s) to install into. Re-asks once on unparseable input, then
+ * Ask which agent(s) to install into. Re-asks once on unparseable input, then
  * gives up and returns `null` — the caller turns that into the same exit-2
  * usage error the no-TTY path uses, so the output contract stays one shape.
  */
-export async function askHosts(hosts) {
+export async function askAgents(agents) {
   const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
-  const menu = hosts.map((h, i) => `  ${i + 1}. ${LABELS[h] ?? h}`).join('\n');
+  const menu = agents.map((a, i) => `  ${i + 1}. ${LABELS[a] ?? a}`).join('\n');
   const prompt = `Which coding agent(s) should this install into?\n${menu}\n`
     + 'Enter comma-separated numbers (e.g. "1,3"), "all", or press Enter for all: ';
   try {
     for (let attempt = 0; attempt < 2; attempt += 1) {
       const answer = await question(rl, attempt === 0 ? prompt : 'Not understood — try again: ');
       try {
-        return parseSelection(answer, hosts);
+        return parseSelection(answer, agents);
       } catch {
         // Re-ask once; the loop's second pass falls through to null below.
       }