@execuro-sw-ecosystem/sw-ecosystem-agentic-harness 0.1.6 → 0.1.8

package/lib/hosts.mjs

@@ -4,23 +4,23 @@
 // 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';
 import { join } from 'node:path';
 import {
-  agents, agentsMd, claudeSettings, mcpServers, LOCK_DIR, PKG_ROOT, skills,
+  agents, agentsMd, claudeSettings, lockDir, lockNeedsGitignore, mcpServers, PKG_ROOT, skills,
 } from './content.mjs';
 import { abs, isDir, isWritable, walk } from './fsx.mjs';
 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. */
+/** Where each host reads its skills from — the base every skill copy is
+ * rooted at, and the directory `sw-setup` hands to an editor package's own
+ * `install-skill --target`. */
 export const SKILL_DIR = {
   'claude-code': '.claude/skills',
   codex: '.agents/skills',
@@ -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;
 }
@@ -103,21 +103,6 @@ function skillActions(host, targetBase) {
   return out;
 }
 
-/**
- * One `skill-copy` action per optional extra component. The `skill:`
- * segment (not `file:`) keeps these ids from colliding, or deduping,
- * against a shipped `file-copy` action at the same path.
- */
-function extraComponentActions(host, targetBase) {
-  return EXTRA_COMPONENTS.map((c) => {
-    const target = `${targetBase}/${c.id}/SKILL.md`;
-    return {
-      id: `${host}:skill:${target}`, host, kind: 'skill-copy',
-      component: c.id, package: `${c.pkg}@${c.version}`, target,
-    };
-  });
-}
-
 function agentActions(host, targetBase, pick, ext) {
   return agents().map((agent) => {
     const target = `${targetBase}/${agent.name}${ext}`;
@@ -147,11 +132,17 @@ function agentsMdAction(host) {
   };
 }
 
-/** The lock file describes one machine's install, so it is gitignored. */
-function gitignoreAction(host) {
+/**
+ * The lock describes one machine's install, so it must not be tracked. Under
+ * `var/` the `shopware/core` Flex recipe already ignores it (`/var/*`), so
+ * there is nothing to write and we do not touch the user's `.gitignore` at
+ * all. Only the fallback location needs the managed line.
+ */
+function gitignoreAction(host, ctx) {
+  if (!lockNeedsGitignore(ctx.root)) return null;
   return {
     id: 'shared:text:.gitignore#lock', host, kind: 'text-fence',
-    target: '.gitignore', block: 'lock', syntax: 'gitignore', body: `${LOCK_DIR}/`,
+    target: '.gitignore', block: 'lock', syntax: 'gitignore', body: `${lockDir(ctx.root)}/`,
   };
 }
 
@@ -159,7 +150,6 @@ function planClaude(ctx) {
   const host = 'claude-code';
   const out = [
     ...skillActions(host, SKILL_DIR[host]),
-    ...(ctx.extraComponents === false ? [] : extraComponentActions(host, SKILL_DIR[host])),
     ...agentActions(host, '.claude/agents', 'claude', '.md'),
     ...mcpJsonActions(host, '.mcp.json', 'mcpServers', ctx),
   ];
@@ -176,8 +166,8 @@ function planClaude(ctx) {
       target: '.claude/settings.json', pointer: setting.pointer, op: 'set', value: setting.value,
     });
   }
-  out.push(gitignoreAction(host));
-  return out;
+  out.push(gitignoreAction(host, ctx));
+  return out.filter(Boolean);
 }
 
 function planCodex(ctx) {
@@ -185,7 +175,6 @@ function planCodex(ctx) {
   const out = [
     // Codex discovers skills from `.agents/skills`, never `.claude/skills`.
     ...skillActions(host, SKILL_DIR[host]),
-    ...(ctx.extraComponents === false ? [] : extraComponentActions(host, SKILL_DIR[host])),
     ...agentActions(host, '.codex/agents', 'codex', '.toml'),
   ];
 
@@ -222,15 +211,14 @@ function planCodex(ctx) {
     },
   });
 
-  out.push(agentsMdAction(host), gitignoreAction(host));
-  return out;
+  out.push(agentsMdAction(host), gitignoreAction(host, ctx));
+  return out.filter(Boolean);
 }
 
 function planCopilot(ctx) {
   const host = 'copilot';
   const out = [
     ...skillActions(host, SKILL_DIR[host]),
-    ...(ctx.extraComponents === false ? [] : extraComponentActions(host, SKILL_DIR[host])),
     ...agentActions(host, '.github/agents', 'copilot', '.agent.md'),
     // Copilot CLI reads `.mcp.json`; VS Code reads `.vscode/mcp.json` under the
     // incompatible `servers` key. Both, or the two surfaces disagree.
@@ -239,9 +227,9 @@ function planCopilot(ctx) {
       ...a, id: a.id.replace('shared:', 'copilot:'),
     })),
     agentsMdAction(host),
-    gitignoreAction(host),
+    gitignoreAction(host, ctx),
   ];
-  return out;
+  return out.filter(Boolean);
 }
 
 function planCursor(ctx) {
@@ -249,20 +237,34 @@ 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) {
     out.push(...skillActions(host, SKILL_DIR[host]));
-    if (ctx.extraComponents !== false) out.push(...extraComponentActions(host, SKILL_DIR[host]));
     out.push(...agentActions(host, '.cursor/agents', 'claude', '.md'));
   }
   out.push(...mcpJsonActions(host, '.cursor/mcp.json', 'mcpServers', ctx));
-  out.push(agentsMdAction(host), gitignoreAction(host));
-  return out;
+  out.push(agentsMdAction(host), gitignoreAction(host, ctx));
+  return out.filter(Boolean);
+}
+
+/**
+ * The skills directory a host actually reads, for `status` to report — the
+ * one `sw-setup` passes to an editor package's `install-skill --target`.
+ * Cursor is the exception: when the Claude trees are present it reads those,
+ * so naming `.cursor/skills` would put an editor skill where Cursor never
+ * looks.
+ */
+export function skillsDir(id, ctx) {
+  if (id === 'cursor'
+    && isDir(abs(ctx.root, '.claude/skills')) && isDir(abs(ctx.root, '.claude/agents'))) {
+    return SKILL_DIR['claude-code'];
+  }
+  return SKILL_DIR[id];
 }
 
 /** What is already installed for a host, for `status`. */

package/lib/lock.mjs

@@ -1,4 +1,6 @@
-// The lock file: `.sw-ai-sdk/harness.lock.json` in the host repository.
+// The lock file: `var/sw-ai-sdk/harness.lock.json` in the host repository, or
+// `.sw-ai-sdk/harness.lock.json` in a root that has no `var/` (see
+// `lockDir()` in content.mjs).
 //
 // This is the ownership record. JSON config files have no comments, so nothing
 // in `.mcp.json` can tell us who wrote an entry — the lock does, by content
@@ -6,15 +8,29 @@
 // removal is always narrower than addition, and which rules the user declined
 // so we never ask twice.
 //
-// It is gitignored by default: it describes one machine's install, not the
-// project.
+// It is never tracked: it describes one machine's install, not the project.
+// Under `var/` the Shopware recipe already ignores it; in the fallback
+// location the installer writes the managed `.gitignore` line itself.
+//
+// A lock left at the old `.sw-ai-sdk/` path is read and rewritten to the new
+// one on the next write, so an existing install never looks fresh.
 
-import { LOCK_FILE, SUPPORTED_CONTENT, CONTENT_VERSION, PKG_NAME, PKG_VERSION } from './content.mjs';
-import { abs, readTextMaybe, writeAtomic } from './fsx.mjs';
+import {
+  LOCK_FILE, SUPPORTED_CONTENT, CONTENT_VERSION, PKG_NAME, PKG_VERSION, lockFile,
+} from './content.mjs';
+import {
+  abs, ensureDir, exists, readTextMaybe, removeDirIfEmpty, removeFile, writeAtomic,
+} from './fsx.mjs';
+import { dirname } from 'node:path';
 
 export class LockVersionError extends Error {}
 
 export function lockPath(root) {
+  return abs(root, lockFile(root));
+}
+
+/** The pre-`var/` location, kept only so an existing install can be migrated. */
+export function legacyLockPath(root) {
   return abs(root, LOCK_FILE);
 }
 
@@ -28,7 +44,7 @@ export function empty(scope) {
     installed_at: null,
     updated_at: null,
     platform: process.platform,
-    hosts: {},
+    agents: {},
     files: {},
     dirs: [],
     json_pointers: [],
@@ -41,34 +57,55 @@ export function empty(scope) {
 
 /** Read the lock, or null when absent. Throws on a layout we cannot undo. */
 export function read(root, scope) {
-  const found = readTextMaybe(lockPath(root));
+  // The new location first; a lock still at the old one is read here and
+  // rewritten by `write()`.
+  let where = lockFile(root);
+  let found = readTextMaybe(lockPath(root));
+  if (found === null) {
+    found = readTextMaybe(legacyLockPath(root));
+    where = LOCK_FILE;
+  }
   if (found === null) return null;
   let lock;
   try {
     lock = JSON.parse(found.text);
   } catch {
     throw new LockVersionError(
-      `${LOCK_FILE} is not valid JSON. Move it aside and re-run apply to rebuild it.`,
+      `${where} is not valid JSON. Move it aside and re-run apply to rebuild it.`,
     );
   }
   if (!SUPPORTED_CONTENT.includes(lock.content_version)) {
     throw new LockVersionError(
-      `${LOCK_FILE} records content_version ${lock.content_version}, which this ` +
+      `${where} records content_version ${lock.content_version}, which this ` +
         `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) {
   const next = { ...lock, updated_at: new Date().toISOString() };
   if (!next.installed_at) next.installed_at = next.updated_at;
-  writeAtomic(lockPath(root), `${JSON.stringify(next, null, 2)}\n`);
+  const target = lockPath(root);
+  ensureDir(dirname(target));
+  writeAtomic(target, `${JSON.stringify(next, null, 2)}\n`);
+  // Migration: one lock, at one path. Writing the new one and leaving the old
+  // would make an older CLI, or our own `read()`, resurrect a stale record.
+  const legacy = legacyLockPath(root);
+  if (legacy !== target && exists(legacy)) {
+    removeFile(legacy);
+    removeDirIfEmpty(dirname(legacy));
+  }
   return next;
 }
 
 /** 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 +114,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 +158,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.
       }