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

package/CHANGELOG.md

@@ -7,6 +7,93 @@ release.
 
 ## [Unreleased]
 
+## [0.1.8] - 2026-09-19
+
+### Changed
+
+- **The lock file moved to `var/sw-ai-sdk/harness.lock.json`, and the
+  `.gitignore` line is gone with it.** A Shopware project ignores the whole of
+  `var/` through the `shopware/core` Flex recipe (`/var/*`, with a single
+  `!/var/.htaccess` negation) and already keeps its machine-local state there
+  — `var/cache`, `var/log` — so the installer no longer creates a directory in
+  the repository root and no longer writes to `.gitignore` at all. A root with
+  no `var/` (`--scope user` under $HOME, or a checkout that is not a Shopware
+  project) keeps `.sw-ai-sdk/` and its managed line, unchanged. Nothing here
+  reads a path outside the install root, on any platform.
+  **Migration is automatic and lossless:** a lock still at the old path is
+  read, rewritten to the new one, and the old file, its directory and the
+  managed `.gitignore` block are removed. Declined rules, recorded agents and
+  file hashes all survive, so the first run after upgrading reinstalls nothing
+  — it reports `migrated[]` in `--json` and one line in the human summary.
+  `lock_file` in every result body now carries the resolved path; anything
+  that hard-coded `.sw-ai-sdk/` should read that key instead.
+
+### Removed
+
+- **BREAKING: the "extra component" mechanism is gone.** The CLI no longer
+  detects, installs, updates or removes the two optional visual editors
+  (Specs Editor, Tender Discovery Tool); each package installs its own skill,
+  orchestrated by the `sw-setup` skill. Removed with it: the
+  `extra_components[]` key from `status --json`, the `--no-extra-components`
+  flag on `install`/`plan`/`apply`, the `skipped` field from `plan`'s and
+  `apply`'s `summary` (nothing else could produce that state), the
+  `skill-copy` action kind, and the "Optional extra components" section of
+  `guide`. Anything reading `extra_components[]` or counting `summary.skipped`
+  must stop.
+  **Why:** the mechanism had never once worked. It spawned `npx --no-install
+  <pkg>@<pin> install-skill --print` and required stdout to begin with `---`,
+  but both editors document a `source:`/`next_step:` preamble before the skill
+  document, so the check could never pass and neither skill was ever installed.
+  `--no-install` also suppresses installing but not resolving, so every
+  `status`, `plan` and `apply` issued a real request to the npm registry —
+  `status` was never offline-safe, contrary to what the module claimed.
+- The two editors are now invoked as `@latest` everywhere, including in the
+  `allowed-tools` permission grants of `sw-design-requirements`,
+  `sw-design-solution` and `sw-discover-tender`, which still named an exact
+  version and would therefore have denied the calls. The `@latest` check now
+  guards `allowed-tools` lines as well as prose.
+
+### Added
+
+- `status --json` reports `skills_dir` per agent — the directory that agent
+  actually reads skills from, and the `--target` `sw-setup` hands to an
+  editor package's own `install-skill`/`uninstall-skill`.
+
+## [0.1.7] - 2026-09-19
+
+### Changed
+
+- **BREAKING: `install`, `status`, `plan` and `uninstall` print a human
+  summary, not JSON.** Typing `install` and getting several hundred lines of
+  JSON made success unreadable; the result object is now rendered for a
+  person on stdout — what changed, grouped by coding agent, and the restart
+  each one needs. A run with nothing to do is one line. Conflicts, drift and
+  manual steps are never collapsed: each names its file and its remedy, and
+  an agent this project has not installed is never named at all. Pass
+  `--json` for the previous object, unchanged apart from the key rename
+  below, and `--verbose` for the per-file detail alongside the summary.
+  **Every skill, script or agent parsing this output must add `--json`.**
+- **BREAKING: `--host` is now `--agent`, with no alias.** `--host` is
+  rejected as an unknown option (exit 2, with runnable `--agent` help), the
+  `hosts` key in every result body is now `agents`, and the lock file records
+  `agents`. A lock written by an earlier version under `hosts` is still read
+  and is rewritten as `agents` on the next run, so an existing install keeps
+  its recorded selection. Consistent with the earlier
+  `--no-companions` -> `--no-extra-components` break.
+  **WARNING — the lock migration is one-way:** writing `agents` drops the
+  legacy `hosts` key, so after any run of this version an older pinned CLI
+  (`npx …@0.1.6`) exits 2 in that repository with "no --host given, this
+  repository has no recorded install". Verified against the published 0.1.6
+  tarball.
+- `install` invoked with a bad flag now reports `install`, not `apply`, in
+  its usage help.
+
+### Fixed
+
+- `status` no longer labels a conflict as "edited since install". Its
+  `drift[]` entries now carry the action's `state`, and the human renderer
+  titles conflicts as conflicts.
+
 ## [0.1.6] - 2026-09-18
 
 ### Changed

package/CONTRIBUTING.md

@@ -15,7 +15,7 @@ npm run gen:check                # generated adapters match their sources
 node scripts/check-pack.mjs      # the tarball matches the files allow-list
 ```
 
-If you edited an agent or a skill, regenerate the host adapters first and
+If you edited an agent or a skill, regenerate the per-agent adapters first and
 commit the result:
 
 ```bash
@@ -29,14 +29,23 @@ npm run gen
   `scripts/gen-copilot-agents.mjs`. Never hand-edit them — run `npm run gen`
   and commit the output. `npm run gen:check` fails the build on drift.
 - **Every `SKILL.md` stays under 8192 bytes**, Codex's effective cap and the
-  smallest of the four hosts'. A test enforces it. When a skill grows past the
-  cap, move material into `reference/*.md` beside it — that is
+  smallest of the four coding agents'. A test enforces it. When a skill grows
+  past the cap, move material into `reference/*.md` beside it — that is
   **reorganisation, never compression**. Audit the split against the
   pre-split file line by line; do not drop meaning to make the number work.
-- **Skills stay host-neutral.** No `${CLAUDE_SKILL_DIR}`, no `$ARGUMENTS`, no
+- **Skills stay agent-neutral.** No `${CLAUDE_SKILL_DIR}`, no `$ARGUMENTS`, no
   `SendMessage` or `subagent_type`, no literal `.claude/…` path. Any prose that
   asks the user a question names both Claude Code's and Codex's question
   tools, not just one.
+- **The result object is the model; `lib/render.mjs` is only a view.** Every
+  command builds one body, `--json` prints it verbatim and the human summary
+  is rendered from that same body — never assembled beside it. The renderer is
+  pure `body -> string` with no I/O, so it is unit-tested in
+  `test/render.test.mjs` without a terminal. Human text goes to stdout (it is
+  the result); only the interactive picker and warnings go to stderr.
+- **Test suites pass `--json`.** `test/helpers.mjs`'s `run()` appends it for
+  every call; only a suite that is about the human output opts out with
+  `{ json: false }`.
 - **The installer never prompts, never fetches, and writes atomically.**
   Every file is written to a temporary path and renamed. A change that breaks
   any of those three properties is a change to the contract this package

package/README.md

@@ -43,34 +43,50 @@ identity, not an npm package name — and can be run standalone in any stdio MCP
 client without this harness.
 
 The two editors are **optional add-ons**, and each ships its own skill inside
-its package rather than here. `sw-setup` offers to install them; a host that
-declines is fully set up without them, and `--editor` on `sw-design-requirements`,
-`sw-design-solution` or `sw-discover-tender` then stops with one line saying so.
+its package rather than here. They are not this CLI's business at all: it
+neither detects nor installs them. `sw-setup` owns their whole lifecycle —
+it offers them, and installs, updates and removes each one with that
+package's own `install-skill`/`uninstall-skill --target <skills dir>`. A
+project that declines is fully set up without them, and `--editor` on
+`sw-design-requirements`, `sw-design-solution` or `sw-discover-tender` then
+stops with one line saying so.
 
 ## Commands
 
 | Command | What it does |
 | --- | --- |
-| `install` | installs into the resolved host(s) (see Flags below); the same as `apply --yes` |
-| `status` | read-only; what is installed, what drifted, which optional extra components are present |
+| `install` | installs into the resolved coding agent(s) (see Flags below); the same as `apply --yes` |
+| `status` | read-only; what is installed, what drifted, and each agent's `skills_dir` |
 | `plan` | the exact changes, written as a diff; writes nothing |
 | `apply --yes` | performs them |
 | `uninstall --yes` | removes what the lock file records |
 | `guide` | the install protocol, the single source of truth |
 
-Flags: `--host claude-code|codex|copilot|cursor` (repeatable), `--scope
+Flags: `--agent claude-code|codex|copilot|cursor` (repeatable), `--scope
 project|user` (default `project`), `--root <path>` (default the current
 directory), `--yes` (required by `apply` and `uninstall` — `install` implies
-it), and `--no-extra-components` (skip detection of the optional editor
-packages).
+it), `--json` and `--verbose` (see Output below).
 
-`install`/`apply` resolve which host(s) to write into, in order: `--host` if
-given; else the hosts a lock file already records (a re-run needs no
-question); else, with a terminal attached, an interactive picker; else exit 2
-with the four `install --host <h>` commands as `help` — it never guesses and
-never hangs. `status` and `uninstall` are unaffected by this and keep
-covering every host by default; `plan` writes nothing, so with no `--host` and
-no lock it previews all four and says so.
+`install`/`apply` resolve which coding agent(s) to write into, in order:
+`--agent` if given; else the agents a lock file already records (a re-run
+needs no question); else, with a terminal attached, an interactive picker;
+else exit 2 with the four `install --agent <a>` commands as `help` — it never
+guesses and never hangs. `status` and `uninstall` are unaffected by this and
+keep covering every agent by default; `plan` writes nothing, so with no
+`--agent` and no lock it previews all four and says so.
+
+### Output
+
+`install`, `status`, `plan` and `uninstall` print a short human summary on
+stdout — what changed, grouped by coding agent, and the restart each one
+needs. When nothing changed, that is a single line. Conflicts, drift and
+manual steps are always shown in full, with the file and the remedy, because
+those are the only things you have to act on.
+
+`--json` prints the result object instead: the same body, with the per-file
+detail, a `next_step` on every success and a `help` array of runnable commands
+on every error. **Anything parsing this output must pass `--json`.**
+`--verbose` keeps the human summary but adds the per-file detail.
 
 ## Install
 
@@ -86,9 +102,9 @@ The command's output tells you which ones and how.
 
 `apply` refuses without `--yes`. Neither `apply` nor `install` prompts for
 consent — typing the verb, or passing `--yes`, is the consent — but with no
-`--host`, no existing lock and no terminal (Codex's question tool does not
+`--agent`, no existing lock and no terminal (Codex's question tool does not
 block outside Plan mode, and CI has no terminal either), it exits 2 rather
-than guess. Add `--host claude-code` (repeatable) to install into one agent,
+than guess. Add `--agent claude-code` (repeatable) to install into one agent,
 and `--scope user` to install into your home directory instead of this
 repository. The default scope is the project — nothing is written under `~`
 unless you ask.
@@ -105,6 +121,17 @@ unless you ask.
 `AGENTS.md` gets a managed block too — Codex, Copilot and Cursor read it, and
 Codex never reads `CLAUDE.md`.
 
+The installer's own state — the lock file recording what it wrote — goes to
+`var/sw-ai-sdk/harness.lock.json`. A Shopware project already ignores the whole
+of `var/` through the `shopware/core` Flex recipe (`/var/*`) and already keeps
+its machine-local state there, so the repository root stays clean and **no
+`.gitignore` line is written at all**. A root with no `var/` — `--scope user`
+under your home directory, or a checkout that is not a Shopware project —
+falls back to `.sw-ai-sdk/` and gets the managed `.gitignore` line as before.
+An install recorded at the old path is moved on the next `install`, which also
+takes back the `.gitignore` line it no longer needs; nothing is reinstalled and
+no declined rule is forgotten.
+
 ### What it will not do
 
 - **It never overwrites a file it did not install.** A file already at one of
@@ -124,15 +151,16 @@ Undo everything with:
 npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest uninstall --yes
 ```
 
-It removes exactly what the lock file at `.sw-ai-sdk/harness.lock.json` records,
+It removes exactly what the lock file at `var/sw-ai-sdk/harness.lock.json` records,
 keeps anything you hand-edited, and tells you what it kept.
 
 ### From a skill
 
-`sw-setup` is a stub: it runs `status`, renders the table, asks once, and runs
-`apply --yes`. It deliberately restates none of the protocol, because an
-installed skill file goes stale and the CLI does not. Anything that needs the
-protocol runs:
+`sw-setup` is a stub: it runs `status --json`, renders the table, asks once,
+and runs `apply --yes --json`. A skill always passes `--json`; the bare
+commands print the human summary. It deliberately restates none of the
+protocol, because an installed skill file goes stale and the CLI does not.
+Anything that needs the protocol runs:
 
 ```bash
 npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest guide
@@ -146,16 +174,16 @@ Three things update on different schedules.
 | --- | --- |
 | This package — skills, sub-agents, permission rules, MCP registrations | `npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest install` |
 | The MCP servers (`ShopwareDevKnowledgeBase`, `playwright`) | By themselves. They are registered as `@latest`, so your agent fetches the newest build the next time it starts one. Nothing to run. |
-| Specs Editor, Tender Discovery Tool | You update them. Each has its own line — see below. |
+| Specs Editor, Tender Discovery Tool | `sw-setup` does, by re-running each package's own `install-skill` at `@latest` — see below. |
 
 ### The optional editors
 
-Install or update each at the exact version this release pins — the CLI
-probes for that version and skips the skill if it finds another:
+They are installed, updated and removed by the `sw-setup` skill, not by this
+CLI, and there is no version to match against this package:
 
 ```bash
-npm i -D @execuro-sw-ecosystem/sw-specs-editor@0.1.0
-npm i -D @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0
+npx -y @execuro-sw-ecosystem/sw-specs-editor@latest install-skill --target <skills dir>
+npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest install-skill --target <skills dir>
 ```
 
 - `sw-specs-editor` backs the `--editor` flag on `sw-design-requirements` and
@@ -163,22 +191,25 @@ npm i -D @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0
 - `sw-tender-discovery-tool` backs the `--editor` flag and the `.xlsx` import
   on `sw-discover-tender`.
 
-Re-run `install` afterwards so the new skill lands in each host. `status`'s
-`extra_components[]` array reports the pinned `version` and the exact `install`
-command for whichever one is missing.
+`<skills dir>` is the `skills_dir` this CLI reports for that agent in
+`status --json`. Re-running the same line is the update — `@latest` plus the
+editor's own "already current" path makes it idempotent — and
+`uninstall-skill` with the same `--target` removes it. Nothing needs to be
+re-run here afterwards.
 
 Re-running `install` is safe at any time: it rewrites only what it owns,
 leaves anything you hand-edited alone (reported as drift), and records the new
-version in the lock file. Restart your coding agent afterwards — every host
-reads its configuration at startup.
+version in the lock file. It prints one line when there was nothing to change.
+Restart your coding agent afterwards — every host reads its configuration at
+startup.
 
 `@latest` matters. Without it, `npx` can reuse a copy already in its cache or
 in this project's `node_modules`, so you would silently keep running the
 version you first installed.
 
 To look before you change anything: `... @latest status` reports
-`installed_version`, any drift, and which extra components are present. It
-writes nothing.
+`installed_version`, any drift, and each agent's `skills_dir`. It writes
+nothing.
 
 ## Prerequisites
 
@@ -334,7 +365,7 @@ repository is development-only.**
 
 ### Every `SKILL.md` is capped at 8 KB
 
-Codex's effective skill-body limit is the smallest of the four hosts', so it is
+Codex's effective skill-body limit is the smallest of the four coding agents', so it is
 the budget every skill is written to. Overflow lives in `reference/*.md` beside
 each `SKILL.md`, loaded on demand. A test enforces the cap, so the gate is
 mechanical rather than a review habit.
@@ -343,7 +374,7 @@ mechanical rather than a review habit.
 
 | Symptom | What it means | What to do |
 | --- | --- | --- |
-| `state: "conflict"` | A file we did not install already sits at that path. It is never overwritten. | Move or delete the existing file, or `--host`-scope the run away from it, then re-run `apply`. |
+| `state: "conflict"` | A file we did not install already sits at that path. It is never overwritten. | Move or delete the existing file, or `--agent`-scope the run away from it, then re-run `apply`. |
 | `state: "drift"` | You (or something else) edited a file this installer wrote. It is left alone on every later run. | Nothing to fix — this is by design. Re-run `status` to confirm it is the only thing reported. |
 | A manual step for `.vscode/mcp.json` | That file is JSONC (comments or trailing commas). Rewriting it would destroy your notes, so it is never touched automatically. | Add the printed snippet to `.vscode/mcp.json` yourself, under the `servers` key. |
 | `.codex/` reported read-only | Codex's default workspace-write sandbox makes `.codex/` and `.agents/` read-only from inside a Codex session. | Run the installer from a plain shell, not from inside Codex. |

package/SECURITY.md

@@ -41,7 +41,7 @@ scripts** on install, which removes a large part of the usual npm attack
 surface.
 
 Out of scope: vulnerabilities in the coding agents themselves, in the
-separately published extra components (they have their own repositories
+separately published visual editors (they have their own repositories
 and their own reporting), or in a third-party MCP server this package merely
 registers, such as Playwright's (report those upstream).
 

package/bin/cli.mjs

@@ -28,32 +28,38 @@ const COMMANDS = {
 
 const USAGE = `usage: sw-ecosystem-agentic-harness <command> [options]
 
-  install    [--host <h>] [--scope project|user] [--root <path>] [--no-extra-components]
-  status     [--host <h>] [--scope project|user] [--root <path>]
-  plan       [--host <h>] [--scope project|user] [--root <path>] [--no-extra-components]
-  apply      --yes [--host <h>] [--scope project|user] [--root <path>] [--no-extra-components]
-  uninstall  --yes [--host <h>] [--scope project|user] [--root <path>]
+  install    [--agent <a>] [--scope project|user] [--root <path>]
+  status     [--agent <a>] [--scope project|user] [--root <path>]
+  plan       [--agent <a>] [--scope project|user] [--root <path>]
+  apply      --yes [--agent <a>] [--scope project|user] [--root <path>]
+  uninstall  --yes [--agent <a>] [--scope project|user] [--root <path>]
   guide      print the install protocol
 
   install is apply --yes under a friendlier name: the whole install in one
   command, no --yes needed — typing the verb is the consent for that write;
-  it can still ask which host(s), see below.
+  it can still ask which coding agent(s), see below.
 
-  <h> is one of: claude-code, codex, copilot, cursor. Repeat --host to select
-  several. install/apply resolve which host(s) to use, in order: --host if
-  given; else the hosts already recorded in the lock file, if one exists;
+  <a> is one of: claude-code, codex, copilot, cursor. Repeat --agent to select
+  several. install/apply resolve which agent(s) to use, in order: --agent if
+  given; else the agents already recorded in the lock file, if one exists;
   else, with a terminal attached, an interactive picker; else exit 2 with
-  the four "... install --host <h>" commands as help. status and uninstall
-  keep covering every host by default.
+  the four "... install --agent <a>" commands as help. status and uninstall
+  keep covering every agent by default.
 
   --scope defaults to project: nothing is written under your home directory
   unless you ask for it. --root defaults to the current directory.
 
-  --no-extra-components skips the two optional extra-component skills (Specs
-  Editor, Tender Discovery Tool) even when the package is present locally.
+  The two optional visual editors (Specs Editor, Tender Discovery Tool) are
+  not this CLI's business: each ships its own skill inside its own npm
+  package, and the sw-setup skill offers, installs, updates and removes
+  them.
 
-Every command prints one JSON object on stdout carrying a next_step. Run
-\`sw-ecosystem-agentic-harness guide\` first — it is the install protocol.`;
+  --json      print the result object instead of the human summary
+  --verbose   include the per-file detail --json carries
+
+install, status, plan and uninstall print a short human summary on stdout.
+Add --json for the machine-readable object, which always carries a next_step.
+Run \`sw-ecosystem-agentic-harness guide\` first — it is the install protocol.`;
 
 const argv = process.argv.slice(2);
 const cmd = argv[0];

package/lib/actions.mjs

@@ -20,13 +20,11 @@ import {
 import { PKG_ROOT } from './content.mjs';
 import { isDeclined } from './lock.mjs';
 import { readFileSync } from 'node:fs';
-import { EXTRA_COMPONENTS, probe } from './extra-components.mjs';
 
 /** Preview one action against the filesystem. Reads only. */
 export function preview(action, ctx) {
   switch (action.kind) {
     case 'file-copy': return previewFile(action, ctx);
-    case 'skill-copy': return previewSkill(action, ctx);
     case 'json-merge': return previewJson(action, ctx);
     case 'toml-fence':
     case 'text-fence': return previewFence(action, ctx);
@@ -42,8 +40,7 @@ function previewFile(action, ctx) {
   return previewBytes(action, ctx, shipped);
 }
 
-/** The adopt/conflict/drift/update ladder, shared by `file-copy` and, with a
- * probed body instead of a shipped one, `skill-copy`. */
+/** The adopt/conflict/drift/update ladder every byte-for-byte target walks. */
 function previewBytes(action, ctx, bytes) {
   const hash = sha256(bytes);
   const target = abs(ctx.root, action.target);
@@ -74,35 +71,6 @@ function previewBytes(action, ctx, bytes) {
     detail: 'shipped content changed' };
 }
 
-// ------------------------------------------------------------ skill-copy
-
-/** Strip the probed body (a Buffer) before it lands anywhere near the
- * action, which `commands.mjs` serialises straight to stdout. */
-function stripProbeBody({ body, ...rest }) {
-  return rest;
-}
-
-function previewSkill(action, ctx) {
-  const component = EXTRA_COMPONENTS.find((c) => c.id === action.component);
-  const probed = probe(component, { platform: ctx.platform });
-  const probeSummary = stripProbeBody(probed);
-
-  if (!probed.available) {
-    const remedy = probed.state === 'absent'
-      ? `npm i -D ${probed.spec}`
-      : 'check that npx works — probing needs network-free npx --no-install';
-    return {
-      ...action, state: 'skipped', available: false,
-      probe: probeSummary, reason: probed.reason, remedy,
-    };
-  }
-
-  return {
-    ...previewBytes(action, ctx, probed.body),
-    available: true, probe: probeSummary, body: probed.body,
-  };
-}
-
 // ------------------------------------------------------------- json-merge
 
 function previewJson(action, ctx) {
@@ -275,18 +243,6 @@ export function execute(action, ctx) {
       return { kind: 'file-copy', host: action.host, target: action.target, source: action.source,
         hash: action.hash, bytes: action.bytes, created_file: action.created_file !== false, dirs };
     }
-    case 'skill-copy': {
-      // Collapses to a `file-copy` lock entry on purpose: `lock.record`,
-      // `lock.entries`, `revert` and `rebuild` need no extra-component-specific
-      // case, and `uninstall` needs no probe. `source` is provenance only —
-      // `revert` never reads it.
-      ensureDir(dirname(target));
-      writeAtomic(target, action.body);
-      const dirs = ancestorDirs(ctx.root, action.target);
-      return { kind: 'file-copy', host: action.host, target: action.target,
-        source: `npm:${action.package}#install-skill --print`,
-        hash: action.hash, bytes: action.bytes, created_file: action.created_file !== false, dirs };
-    }
     case 'json-merge': {
       // Recompute from what is on disk right now rather than writing the
       // snapshot `preview` took. Several actions can target one file — the two