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

package/lib/commands.mjs

@@ -1,21 +1,23 @@
 // status / plan / apply / uninstall.
 //
-// Error aggregation lives here: each host is planned and applied inside its
-// own try, failures accumulate, and the process fails only after every host
-// has been attempted. One unwritable host must not abort the others.
+// Error aggregation lives here: each agent is planned and applied inside its
+// own try, failures accumulate, and the process fails only after every agent
+// has been attempted. One unwritable agent must not abort the others.
 
 import { homedir } from 'node:os';
 import { resolve } from 'node:path';
 import * as out from './out.mjs';
 import {
-  CONTENT_VERSION, LOCK_FILE, PKG_NAME, PKG_VERSION, agents, skills,
+  CONTENT_VERSION, LOCK_DIR as LOCK_DIR_LEGACY, PKG_NAME, PKG_VERSION, agents,
+  lockDir, lockFile, lockNeedsGitignore, skills,
 } from './content.mjs';
 import { exists, isWritable, abs } from './fsx.mjs';
-import { HOSTS, buildPlan, detectAll, installedCounts } from './hosts.mjs';
+import { AGENTS, buildPlan, detectAll, installedCounts, skillsDir } from './hosts.mjs';
 import * as lockfile from './lock.mjs';
 import { dedupe, execute, isWritableState, preview, pruneDirs, revert } from './actions.mjs';
-import { probeAll } from './extra-components.mjs';
-import { askHosts } from './prompt.mjs';
+import { removeDirIfEmpty, removeFile } from './fsx.mjs';
+import { askAgents } from './prompt.mjs';
+import { RESTART } from './render.mjs';
 
 const RUN = 'sw-ecosystem-agentic-harness';
 
@@ -25,24 +27,26 @@ class UsageError extends Error {
 
 /** Parse the flags every command shares. */
 export function buildContext(argv, command) {
-  const hosts = [];
+  const agents = [];
   let scope = 'project';
   let root = process.cwd();
   let yes = false;
   let projectWiki;
-  let extraComponents = true;
+  let asJson = false;
+  let verbose = false;
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--yes' || arg === '-y') { yes = true; continue; }
-    if (arg === '--no-extra-components') { extraComponents = false; continue; }
-    if (arg === '--host') {
+    if (arg === '--json') { asJson = true; continue; }
+    if (arg === '--verbose') { verbose = true; continue; }
+    if (arg === '--agent') {
       const value = argv[++i];
-      if (!HOSTS.includes(value)) {
-        throw new UsageError(`unknown --host ${value ?? '(missing)'}`,
-          HOSTS.map((h) => `${RUN} ${command} --host ${h}`));
+      if (!AGENTS.includes(value)) {
+        throw new UsageError(`unknown --agent ${value ?? '(missing)'}`,
+          AGENTS.map((a) => `${RUN} ${command} --agent ${a}`));
       }
-      hosts.push(value);
+      agents.push(value);
       continue;
     }
     if (arg === '--scope') {
@@ -59,17 +63,20 @@ export function buildContext(argv, command) {
     throw new UsageError(`unknown option ${arg}`, [`${RUN} guide`, `${RUN} ${command}`]);
   }
 
+  out.setFormat(asJson ? 'json' : 'human');
+  out.setVerbose(verbose);
+
   // User scope writes under $HOME; project scope stays in the repository.
   if (scope === 'user') root = homedir();
   root = resolve(root);
   if (!exists(root)) throw new UsageError(`--root does not exist: ${root}`, [`${RUN} ${command} --root .`]);
 
   return {
-    root, scope, yes, projectWiki, extraComponents,
-    // Empty means "nothing chosen yet" — resolveHosts() applies the
+    root, scope, yes, projectWiki, json: asJson, verbose,
+    // Empty means "nothing chosen yet" — resolveAgents() applies the
     // per-command fallback once the lock (and, for apply/install, a TTY)
     // is available to consult.
-    hosts: [...new Set(hosts)],
+    agents: [...new Set(agents)],
     platform: process.platform,
     version: PKG_VERSION,
     lock: null,
@@ -77,35 +84,36 @@ export function buildContext(argv, command) {
 }
 
 /**
- * The host-resolution chain every write command shares:
- *   1. `--host` given → use exactly those. No question.
- *   2. else a lock already records hosts → reuse them. This is an update;
- *      the choice was already made. No question.
+ * The agent-resolution chain every write command shares:
+ *   1. `--agent` given → use exactly those. No question.
+ *   2. else a lock already records agents → reuse them. This is an update;
+ *      the choice was already made. No question. A lock written before the
+ *      rename records them under `hosts`; lib/lock.mjs reads either.
  *   3. else a TTY is attached (apply/install only) → ask, via lib/prompt.mjs.
  *   4. else → UsageError, exit 2, `help` lists the four runnable commands.
  *
- * `status` and `uninstall` keep their old, ungated default of every host —
+ * `status` and `uninstall` keep their old, ungated default of every agent —
  * reporting and removal are not consent points. `plan` writes nothing, so it
  * never reaches step 3: steps 1-2, then it previews all four and says so.
  *
  * Call after `loadLock(ctx)` so `ctx.lock` is populated for step 2.
  */
-async function resolveHosts(ctx, command) {
-  if (ctx.hosts.length) return { hosts: [...new Set(ctx.hosts)], chosen: true };
-  if (command === 'status' || command === 'uninstall') return { hosts: [...HOSTS], chosen: true };
+async function resolveAgents(ctx, command) {
+  if (ctx.agents.length) return { agents: [...new Set(ctx.agents)], chosen: true };
+  if (command === 'status' || command === 'uninstall') return { agents: [...AGENTS], chosen: true };
 
-  const lockHosts = ctx.lock?.hosts ? Object.keys(ctx.lock.hosts) : [];
-  if (lockHosts.length) return { hosts: lockHosts, chosen: true };
+  const recorded = ctx.lock?.agents ? Object.keys(ctx.lock.agents) : [];
+  if (recorded.length) return { agents: recorded, chosen: true };
 
-  if (command === 'plan') return { hosts: [...HOSTS], chosen: false };
+  if (command === 'plan') return { agents: [...AGENTS], chosen: false };
 
   if (process.stdin.isTTY) {
-    const chosen = await askHosts(HOSTS);
-    if (chosen) return { hosts: chosen, chosen: true };
+    const chosen = await askAgents(AGENTS);
+    if (chosen) return { agents: chosen, chosen: true };
   }
   throw new UsageError(
-    'no --host given, this repository has no recorded install, and there is no terminal to ask which host(s) to use',
-    HOSTS.map((h) => `${RUN} ${command} --host ${h}`),
+    'no --agent given, this repository has no recorded install, and there is no terminal to ask which coding agent(s) to use',
+    AGENTS.map((a) => `${RUN} ${command} --agent ${a}`),
   );
 }
 
@@ -121,13 +129,13 @@ function loadLock(ctx) {
   return ctx.lock;
 }
 
-/** Preview every action for the selected hosts, aggregating per-host failures. */
+/** Preview every action for the selected agents, aggregating per-agent failures. */
 function previewAll(ctx) {
   const errors = [];
   const actions = [];
-  for (const host of ctx.hosts) {
+  for (const host of ctx.agents) {
     try {
-      const forHost = dedupe(buildPlan({ ...ctx, hosts: [host], selectedHosts: ctx.hosts }));
+      const forHost = dedupe(buildPlan({ ...ctx, agents: [host], selectedAgents: ctx.agents }));
       for (const action of forHost) {
         try {
           actions.push(preview(action, ctx));
@@ -143,18 +151,11 @@ function previewAll(ctx) {
 }
 
 function summarise(actions) {
-  const s = { create: 0, update: 0, unchanged: 0, drift: 0, conflict: 0, manual: 0, skipped: 0 };
+  const s = { create: 0, update: 0, unchanged: 0, drift: 0, conflict: 0, manual: 0 };
   for (const a of actions) if (a.state in s) s[a.state] += 1;
   return s;
 }
 
-/** The `npm i -D <spec>` line(s) for every skipped skill-copy action. */
-function skippedInstalls(actions) {
-  return [...new Set(
-    actions.filter((a) => a.state === 'skipped' && a.remedy?.startsWith('npm i -D')).map((a) => a.remedy),
-  )];
-}
-
 /** Strip the fields that are machinery, not result. */
 function publicAction(a) {
   const { doc, fmt, body, value, conflict, newly_declined: nd, absolute, ...rest } = a;
@@ -175,13 +176,13 @@ export async function status(argv) {
     }
     throw e;
   }
-  ({ hosts: ctx.hosts } = await resolveHosts(ctx, 'status'));
+  ({ agents: ctx.agents } = await resolveAgents(ctx, 'status'));
 
   const detections = await detectAll(ctx);
   const { actions, errors } = previewAll(ctx);
   const byHost = new Map(detections.map((d) => [d.id, d]));
 
-  const hosts = detections.map((d) => {
+  const agentStates = detections.map((d) => {
     const mine = actions.filter((a) => a.host === d.id || a.host === 'shared');
     let state = 'absent';
     if (d.detected) {
@@ -189,41 +190,29 @@ export async function status(argv) {
       const bad = mine.filter((a) => a.state === 'conflict' || a.state === 'drift');
       if (bad.length) state = bad.some((a) => a.state === 'conflict') ? 'conflict' : 'drift';
       else if (pending.length === 0) state = 'ok';
-      else state = lock?.hosts?.[d.id] ? 'drift' : 'not-installed';
+      else state = lock?.agents?.[d.id] ? 'drift' : 'not-installed';
     }
     return {
       id: d.id, detected: d.detected, marker: d.marker, writable: d.writable,
+      skills_dir: skillsDir(d.id, ctx),
       installed: installedCounts(d.id, ctx), state, notes: d.notes,
     };
   });
 
+  // `drift[]` carries conflicts too; `state` says which, so a file someone
+  // else wrote is not reported back to the user as their own edit.
   const drift = actions.filter((a) => a.state === 'drift' || a.state === 'conflict').map((a) => ({
-    target: a.target, expected: a.hash ?? null, actual: a.prior ?? null,
+    target: a.target, state: a.state, expected: a.hash ?? null, actual: a.prior ?? null,
     reason: a.reason, remedy: a.remedy,
   }));
 
   const pending = actions.filter((a) => isWritableState(a.state)).length;
   const worst = ['conflict', 'drift', 'not-installed', 'ok', 'absent']
-    .find((s) => hosts.some((h) => h.state === s)) ?? 'absent';
-
-  const extraComponents = ctx.extraComponents === false ? [] : probeAll({ platform: ctx.platform }).map((p) => ({
-    id: p.id, package: p.pkg, version: p.version, label: p.label,
-    available: p.available, probe: p.state, reason: p.reason ?? null,
-    installed_for: Object.entries(lock?.files ?? {})
-      .filter(([target]) => target.endsWith(`/skills/${p.id}/SKILL.md`))
-      .map(([, v]) => v.host),
-    install: p.available ? null : `npm i -D ${p.spec}`,
-  }));
+    .find((s) => agentStates.some((a) => a.state === s)) ?? 'absent';
 
   let next = pending
     ? `Run \`${RUN} plan\` to see the ${pending} change(s) needed, then \`${RUN} apply --yes\`.`
     : `Nothing to do — the harness is installed and up to date. Run \`${RUN} plan\` any time to re-check.`;
-  if (ctx.extraComponents !== false) {
-    const unavailable = extraComponents.filter((c) => !c.available);
-    if (unavailable.length) {
-      next += ` ${unavailable.length} optional extra component(s) are not on this machine — install with ${unavailable.map((c) => `\`${c.install}\``).join(', ')} to enable their skills.`;
-    }
-  }
 
   return out.ok('status', head(ctx, {
     installed_version: lock?.version ?? null,
@@ -231,7 +220,7 @@ export async function status(argv) {
     next_step: next,
     help: [`${RUN} plan`, `${RUN} apply --yes`, `${RUN} guide`],
     inventory: { skills: skills().length, agents: agents().length },
-    hosts, extra_components: extraComponents, drift,
+    agents: agentStates, drift,
     declined: lock?.declined ?? [],
     manual: lock?.manual ?? [],
     errors,
@@ -251,27 +240,23 @@ export async function plan(argv) {
     }
     throw e;
   }
-  const { hosts, chosen } = await resolveHosts(ctx, 'plan');
-  ctx.hosts = hosts;
+  const { agents: chosenAgents, chosen } = await resolveAgents(ctx, 'plan');
+  ctx.agents = chosenAgents;
   const { actions, errors } = previewAll(ctx);
   const summary = summarise(actions);
   const changes = summary.create + summary.update;
 
-  let next = chosen ? '' : 'No --host given and no existing install found, so this previews all four hosts. ';
+  let next = chosen ? '' : 'No --agent given and no existing install found, so this previews all four agents. ';
   next += changes
     ? `Nothing was written. Run \`${RUN} apply --yes\` to perform the ${changes} change(s).`
       + (summary.conflict || summary.manual
         ? ` The ${summary.conflict} conflict(s) and ${summary.manual} manual step(s) will be reported again and left to you.`
         : '')
     : `Nothing to do — every target is already up to date.`;
-  const installs = skippedInstalls(actions);
-  if (installs.length) {
-    next += ` ${summary.skipped} action(s) skipped — run ${installs.map((i) => `\`${i}\``).join(', ')} to enable them.`;
-  }
 
   return out.ok('plan', head(ctx, {
     summary, next_step: next,
-    help: [`${RUN} apply --yes`, ...ctx.hosts.map((h) => `${RUN} apply --yes --host ${h}`)],
+    help: [`${RUN} apply --yes`, ...ctx.agents.map((a) => `${RUN} apply --yes --agent ${a}`)],
     actions: actions.map(publicAction),
     errors,
   }));
@@ -279,15 +264,8 @@ export async function plan(argv) {
 
 // ------------------------------------------------------------------- apply
 
-const RESTART_HELP = {
-  'claude-code': 'Restart Claude Code, or run `/mcp` in the running session',
-  codex: 'Restart `codex` — .codex/config.toml is read once at startup',
-  copilot: 'Reload the VS Code window (Developer: Reload Window) for .vscode/mcp.json',
-  cursor: 'Restart Cursor so it re-reads .cursor/mcp.json',
-};
-
 export async function apply(argv, label = 'apply') {
-  const ctx = buildContext(argv, 'apply');
+  const ctx = buildContext(argv, label);
   if (!ctx.yes) {
     return out.usage(label, 'apply refuses to write without --yes',
       [`${RUN} plan`, `${RUN} apply --yes`]);
@@ -303,24 +281,46 @@ export async function apply(argv, label = 'apply') {
     }
     throw e;
   }
-  ({ hosts: ctx.hosts } = await resolveHosts(ctx, label));
+  ({ agents: ctx.agents } = await resolveAgents(ctx, label));
 
   // An apply we cannot record is an apply we cannot undo. Refuse up front
   // rather than leave the user with files and no way back.
-  if (!isWritable(abs(ctx.root, LOCK_FILE))) {
-    return out.failure(label, `cannot write the lock file at ${LOCK_FILE}`, {
+  if (!isWritable(abs(ctx.root, lockFile(ctx.root)))) {
+    return out.failure(label, `cannot write the lock file at ${lockFile(ctx.root)}`, {
       next_step: `Make ${ctx.root} writable, then re-run \`${RUN} apply --yes\`.`,
       help: [`${RUN} status`],
     });
   }
 
+  // Migration: a lock that used to live in the repository root carried a
+  // managed `.gitignore` line. Under `var/` the recipe ignores it already, so
+  // that line is ours to take back rather than leave behind as litter.
+  const staleIgnore = !lockNeedsGitignore(ctx.root)
+    && (lock.fences ?? []).find((f) => f.file === '.gitignore' && f.block === 'lock');
+  const migrated = [];
+  if (staleIgnore) {
+    try {
+      const result = revert({ kind: 'text-fence', target: '.gitignore', ...staleIgnore }, ctx);
+      if (result.state !== 'kept') {
+        lock = { ...lock, fences: lock.fences.filter((f) => f !== staleIgnore) };
+        migrated.push({
+          target: '.gitignore',
+          detail: `removed the managed \`${LOCK_DIR_LEGACY}/\` line — the lock now lives in ${lockDir(ctx.root)}/, which this project already ignores`,
+        });
+      }
+    } catch {
+      // Cosmetic. An apply that installed everything must not fail over a
+      // line we were trying to tidy away.
+    }
+  }
+
   const { actions, errors } = previewAll(ctx);
   const results = [];
-  const perHost = new Map(ctx.hosts.map((h) => [h, { id: h, created: 0, updated: 0, unchanged: 0, failed: 0 }]));
+  const perAgent = new Map(ctx.agents.map((a) => [a, { id: a, created: 0, updated: 0, unchanged: 0, failed: 0 }]));
   const manual = [];
 
   for (const action of actions) {
-    const bucket = perHost.get(action.host) ?? perHost.get(ctx.hosts[0]);
+    const bucket = perAgent.get(action.host) ?? perAgent.get(ctx.agents[0]);
     if (action.state === 'manual') {
       manual.push({ target: action.target, reason: action.reason, remedy: action.remedy });
       results.push({ ...publicAction(action), state: 'manual' });
@@ -333,7 +333,7 @@ export async function apply(argv, label = 'apply') {
     }
     try {
       const entry = execute(action, ctx);
-      lock = lockfile.record(lock, [entry], { host: action.host === 'shared' ? undefined : action.host });
+      lock = lockfile.record(lock, [entry], { agent: action.host === 'shared' ? undefined : action.host });
       if (bucket) bucket[action.state === 'create' ? 'created' : 'updated'] += 1;
       results.push({ ...publicAction(action), state: action.state === 'create' ? 'created' : 'updated' });
     } catch (e) {
@@ -355,8 +355,8 @@ export async function apply(argv, label = 'apply') {
   for (const entry of manual) {
     lock = lockfile.record(lock, [{ kind: 'manual', target: entry.target, remedy: entry.remedy }]);
   }
-  for (const host of ctx.hosts) {
-    lock = { ...lock, hosts: { ...lock.hosts, [host]: { installed_at: new Date().toISOString(), version: PKG_VERSION } } };
+  for (const agent of ctx.agents) {
+    lock = { ...lock, agents: { ...lock.agents, [agent]: { installed_at: new Date().toISOString(), version: PKG_VERSION } } };
   }
   lockfile.write(ctx.root, lock);
 
@@ -367,25 +367,21 @@ export async function apply(argv, label = 'apply') {
     conflict: results.filter((r) => r.state === 'conflict').length,
     drift: results.filter((r) => r.state === 'drift').length,
     manual: manual.length,
-    skipped: results.filter((r) => r.state === 'skipped').length,
     failed: results.filter((r) => r.state === 'failed').length,
   };
 
-  const help = ctx.hosts.map((h) => RESTART_HELP[h]).filter(Boolean);
+  const help = ctx.agents.map((a) => RESTART[a]).filter(Boolean);
   help.push(`${RUN} status`);
 
   let next = summary.failed
     ? `${summary.failed} change(s) failed — see \`errors\`. Fix those, then re-run \`${RUN} apply --yes\`.`
-    : `Restart the hosts listed in \`help\` so they pick up the new skills, agents and MCP servers.`
+    : `Restart the coding agents listed in \`help\` so they pick up the new skills, sub-agents and MCP servers.`
       + (manual.length ? ` Then finish the ${manual.length} manual step(s) in \`manual\`.` : '');
-  const installs = skippedInstalls(results);
-  if (installs.length) {
-    next += ` ${summary.skipped} action(s) skipped — run ${installs.map((i) => `\`${i}\``).join(', ')} to enable them.`;
-  }
 
   const body = head(ctx, {
-    summary, lock_file: LOCK_FILE, next_step: next, help,
-    hosts: [...perHost.values()], actions: results, manual, errors,
+    summary, lock_file: lockFile(ctx.root), next_step: next, help,
+    agents: [...perAgent.values()], actions: results, manual, errors,
+    ...(migrated.length ? { migrated } : {}),
   });
   return summary.failed ? out.failure(label, `${summary.failed} change(s) failed`, body) : out.ok(label, body);
 }
@@ -412,20 +408,20 @@ export async function uninstall(argv) {
     }
     throw e;
   }
-  ({ hosts: ctx.hosts } = await resolveHosts(ctx, 'uninstall'));
+  ({ agents: ctx.agents } = await resolveAgents(ctx, 'uninstall'));
 
   if (!lock) {
     // No record means no evidence of what we own. Guessing here would delete
     // someone else's files, so it does nothing and says so.
     return out.ok('uninstall', head(ctx, {
       summary: { removed: 0, reverted: 0, kept: 0, missing: 0, failed: 0 },
-      next_step: `Nothing to remove — no ${LOCK_FILE} was found, so this repository has no recorded install.`,
+      next_step: `Nothing to remove — no ${lockFile(ctx.root)} was found, so this repository has no recorded install.`,
       help: [`${RUN} status`],
       kept: [], missing: [], errors: [],
     }));
   }
 
-  const selected = new Set(ctx.hosts);
+  const selected = new Set(ctx.agents);
   const all = lockfile.entries(lock);
   const mine = all.filter((e) => !e.host || selected.has(e.host) || e.host === 'shared');
 
@@ -452,11 +448,17 @@ export async function uninstall(argv) {
   const prunedDirs = pruneDirs(lock.dirs ?? [], ctx);
   const failed = errors.length;
 
-  if (failed === 0 && survivors.length === 0 && selected.size === HOSTS.length) {
+  if (failed === 0 && survivors.length === 0 && selected.size === AGENTS.length) {
     // Everything we recorded is gone; the lock has nothing left to describe.
-    const { removeFile } = await import('./fsx.mjs');
     removeFile(lockfile.lockPath(ctx.root));
-    pruneDirs(['.sw-ai-sdk'], ctx);
+    removeFile(lockfile.legacyLockPath(ctx.root));
+    // `pruneDirs` deliberately never touches a top-level directory — that
+    // rule protects a host's own `.claude`/`.codex`, but `.sw-ai-sdk` and
+    // `var/sw-ai-sdk` are ours, and an empty one left behind is the clutter
+    // this move set out to remove.
+    pruneDirs([lockDir(ctx.root)], ctx);
+    removeDirIfEmpty(abs(ctx.root, LOCK_DIR_LEGACY));
+    removeDirIfEmpty(abs(ctx.root, lockDir(ctx.root)));
   } else {
     // Keep a lock describing exactly what survived, so a re-run resumes.
     lockfile.write(ctx.root, rebuild(lock, survivors, selected));
@@ -466,8 +468,8 @@ export async function uninstall(argv) {
     summary: { removed, reverted, kept: kept.length, missing: missing.length, failed },
     next_step: failed
       ? `${failed} item(s) could not be removed — see \`errors\`.`
-      : `Restart your hosts.` + (kept.length ? ` ${kept.length} file(s) were left in place because you edited them — they are listed under \`kept\`.` : ''),
-    help: [...ctx.hosts.map((h) => RESTART_HELP[h]).filter(Boolean), `${RUN} status`],
+      : `Restart your coding agent(s).` + (kept.length ? ` ${kept.length} file(s) were left in place because you edited them — they are listed under \`kept\`.` : ''),
+    help: [...ctx.agents.map((a) => RESTART[a]).filter(Boolean), `${RUN} status`],
     kept, missing, pruned_dirs: prunedDirs, errors,
   });
   return failed ? out.failure('uninstall', `${failed} item(s) could not be removed`, body) : out.ok('uninstall', body);
@@ -484,9 +486,9 @@ function rebuild(lock, survivors, selected) {
     else if (entry.kind === 'json-merge') json_pointers.push(entry);
     else fences.push(entry);
   }
-  const hosts = { ...lock.hosts };
-  for (const host of selected) delete hosts[host];
-  return { ...lock, files, json_pointers, rules, fences, hosts };
+  const agents = { ...lock.agents };
+  for (const agent of selected) delete agents[agent];
+  return { ...lock, files, json_pointers, rules, fences, agents };
 }
 
 export { UsageError };

package/lib/content.mjs

@@ -9,7 +9,7 @@
 import { readFileSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { walk } from './fsx.mjs';
+import { isDir, walk } from './fsx.mjs';
 
 export const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -25,8 +25,38 @@ export const PKG_VERSION = pkg.version;
 export const CONTENT_VERSION = 1;
 export const SUPPORTED_CONTENT = [1];
 
+/**
+ * Where the lock lives, relative to the install root.
+ *
+ * A Shopware project ignores the whole of `var/` through the `shopware/core`
+ * Flex recipe (`/var/*` with a single `!/var/.htaccess` negation), and `var/`
+ * is already where that project keeps machine-local state — `var/cache`,
+ * `var/log`. Writing the lock there keeps the repository root clean and means
+ * the installer needs no `.gitignore` line at all.
+ *
+ * A root with no `var/` — a user-scope install under $HOME, or a checkout that
+ * is not a Shopware project — keeps the original dot-directory, which is
+ * gitignored through the managed block as before. Nothing here looks at the
+ * platform or at any path outside the install root.
+ */
 export const LOCK_DIR = '.sw-ai-sdk';
 export const LOCK_FILE = `${LOCK_DIR}/harness.lock.json`;
+export const VAR_LOCK_DIR = 'var/sw-ai-sdk';
+export const VAR_LOCK_FILE = `${VAR_LOCK_DIR}/harness.lock.json`;
+
+/** `var/sw-ai-sdk` when the root has a `var/`, else `.sw-ai-sdk`. */
+export function lockDir(root) {
+  return isDir(join(root, 'var')) ? VAR_LOCK_DIR : LOCK_DIR;
+}
+
+export function lockFile(root) {
+  return `${lockDir(root)}/harness.lock.json`;
+}
+
+/** Whether this root still needs the managed `.gitignore` line for the lock. */
+export function lockNeedsGitignore(root) {
+  return lockDir(root) === LOCK_DIR;
+}
 
 function dirsIn(abs) {
   return readdirSync(abs)

package/lib/guide.mjs

@@ -6,10 +6,8 @@
 
 import * as out from './out.mjs';
 import { PKG_NAME, PKG_VERSION } from './content.mjs';
-import { EXTRA_COMPONENTS } from './extra-components.mjs';
 
 const RUN = `npx -y ${PKG_NAME}@${PKG_VERSION}`;
-const EXTRA_COMPONENT_INSTALLS = EXTRA_COMPONENTS.map((c) => `npm i -D ${c.pkg}@${c.version}`).join('\n');
 
 export const GUIDE = `# ${PKG_NAME} — install protocol
 
@@ -21,16 +19,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,44 +38,47 @@ 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
-
-## Optional extra components
-
-Two skills — Specs Editor and Tender Discovery Tool — ship inside their own
-npm packages, not this one. \`plan\`/\`apply\` detect them offline
-(\`npx --no-install\`) and never fetch them, probing for the exact version
-this release pins — any other version, including \`@latest\`, is treated as
-absent and the skill is skipped:
-
-\`\`\`bash
-${EXTRA_COMPONENT_INSTALLS}
-\`\`\`
-
-The exact command is also in a \`skipped\` action's \`remedy\`, and in
-\`status\`'s \`extra_components\` array. Install it, then re-run \`${RUN} apply --yes\`.
+  --json                                    print the result object instead of
+                                             the human summary — a skill or
+                                             agent always passes this
+  --verbose                                 include the per-file detail
+
+## The two visual editors
+
+The Specs Editor and the Tender Discovery Tool are optional, ship their own
+skill inside their own npm package, and are **not installed by this CLI**.
+The \`sw-setup\` skill owns their whole lifecycle — it offers them, installs
+each one with that package's own \`install-skill --target <skills dir>\`,
+updates them by re-running it, and removes them with \`uninstall-skill\`.
+This CLI never probes for them, never reports them, and never reaches the
+network for them; \`status --json\` reports each agent's \`skills_dir\`,
+which is the target \`sw-setup\` hands them.
 
 ## 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 +101,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 +123,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,
   });
 }