@execuro-sw-ecosystem/sw-ecosystem-agentic-harness 0.1.0

package/lib/fsx.mjs

@@ -0,0 +1,188 @@
+// Filesystem primitives for the installer.
+//
+// Two rules hold everywhere in this file:
+//   1. Every write is atomic — temp file in the *target* directory, then
+//      rename, so a crash mid-write can never truncate a user's config.
+//   2. Every path that leaves this module towards output or the lock file is
+//      POSIX-separated and relative to the install root, so a lock written on
+//      Windows is readable on Linux and vice versa.
+
+import { createHash } from 'node:crypto';
+import {
+  accessSync, constants, copyFileSync, existsSync, mkdirSync, readFileSync,
+  readdirSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync,
+} from 'node:fs';
+import { join, posix, relative, resolve, sep, dirname } from 'node:path';
+
+export function sha256(data) {
+  return `sha256:${createHash('sha256').update(data).digest('hex')}`;
+}
+
+/** Read bytes, or null when the file is absent. Never throws on ENOENT. */
+export function readMaybe(abs) {
+  try {
+    return readFileSync(abs);
+  } catch (e) {
+    if (e.code === 'ENOENT' || e.code === 'EISDIR') return null;
+    throw e;
+  }
+}
+
+/**
+ * Read text and remember how it was formatted, so a merge can write it back
+ * the way the user had it. A config we reformat is a diff the user did not ask
+ * for.
+ */
+export function readTextMaybe(abs) {
+  const buf = readMaybe(abs);
+  if (buf === null) return null;
+  let text = buf.toString('utf8');
+  const bom = text.startsWith('');
+  if (bom) text = text.slice(1);
+  const crlf = /\r\n/.test(text);
+  const indentMatch = /\n([ \t]+)\S/.exec(text);
+  return {
+    text,
+    bom,
+    eol: crlf ? '\r\n' : '\n',
+    indent: indentMatch ? indentMatch[1] : '  ',
+    trailingNewline: text.endsWith('\n'),
+  };
+}
+
+/** Restore the EOL style captured on read. */
+export function restoreEol(text, eol) {
+  const lf = text.replace(/\r\n/g, '\n');
+  return eol === '\r\n' ? lf.replace(/\n/g, '\r\n') : lf;
+}
+
+export function ensureDir(abs) {
+  mkdirSync(abs, { recursive: true });
+}
+
+/**
+ * Write atomically. The temp file goes in the target's own directory so the
+ * rename is same-volume; an EXDEV still falls back to copy+unlink.
+ *
+ * Windows throws EPERM/EBUSY when an editor or antivirus briefly holds the
+ * target, which is common rather than exceptional, so the rename is retried
+ * with backoff before the action is given up on.
+ */
+export function writeAtomic(abs, data, { eol = '\n', bom = false } = {}) {
+  const dir = dirname(abs);
+  ensureDir(dir);
+  let payload = typeof data === 'string' ? restoreEol(data, eol) : data;
+  if (typeof payload === 'string' && bom) payload = `${payload}`;
+  const tmp = join(dir, `.${posix.basename(abs.split(sep).join('/'))}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`);
+  writeFileSync(tmp, payload);
+  const delays = [0, 20, 40, 80, 160, 320];
+  for (let i = 0; i < delays.length; i += 1) {
+    try {
+      renameSync(tmp, abs);
+      return;
+    } catch (e) {
+      if (e.code === 'EXDEV') {
+        copyFileSync(tmp, abs);
+        try { unlinkSync(tmp); } catch { /* the copy landed; the temp is noise */ }
+        return;
+      }
+      const retriable = e.code === 'EPERM' || e.code === 'EBUSY' || e.code === 'EACCES';
+      if (!retriable || i === delays.length - 1) {
+        try { unlinkSync(tmp); } catch { /* best effort */ }
+        throw e;
+      }
+      sleep(delays[i + 1]);
+    }
+  }
+}
+
+/** Blocking sleep — the retry loop must not be async, callers are sync. */
+function sleep(ms) {
+  if (ms <= 0) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+export function removeFile(abs) {
+  try {
+    unlinkSync(abs);
+    return true;
+  } catch (e) {
+    if (e.code === 'ENOENT') return false;
+    throw e;
+  }
+}
+
+/** Remove a directory only when it is empty. Returns whether it went. */
+export function removeDirIfEmpty(abs) {
+  try {
+    if (readdirSync(abs).length > 0) return false;
+    rmdirSync(abs);
+    return true;
+  } catch (e) {
+    if (e.code === 'ENOENT') return false;
+    throw e;
+  }
+}
+
+/** Every file under a root, as sorted POSIX paths relative to it. */
+export function walk(absRoot) {
+  const out = [];
+  const visit = (dir, prefix) => {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch (e) {
+      if (e.code === 'ENOENT') return;
+      throw e;
+    }
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+      const child = join(dir, entry.name);
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) visit(child, rel);
+      else out.push(rel);
+    }
+  };
+  visit(absRoot, '');
+  return out;
+}
+
+/** Root-relative, POSIX-separated — the form used in output and the lock. */
+export function rel(root, abs) {
+  return relative(root, abs).split(sep).join('/');
+}
+
+/** The inverse: a POSIX lock key back to a platform path. */
+export function abs(root, relPosix) {
+  return resolve(root, ...relPosix.split('/'));
+}
+
+export function isDir(abs_) {
+  try {
+    return statSync(abs_).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function exists(abs_) {
+  return existsSync(abs_);
+}
+
+/** Whether we could write here — checked on the nearest existing ancestor. */
+export function isWritable(abs_) {
+  let probe = abs_;
+  for (let i = 0; i < 64; i += 1) {
+    if (existsSync(probe)) {
+      try {
+        accessSync(probe, constants.W_OK);
+        return true;
+      } catch {
+        return false;
+      }
+    }
+    const parent = dirname(probe);
+    if (parent === probe) return false;
+    probe = parent;
+  }
+  return false;
+}

package/lib/guide.mjs

@@ -0,0 +1,98 @@
+// The install protocol, in one place.
+//
+// The `sw-setup` skill is a stub that sends the agent here rather than
+// restating any of this: an installed copy of a skill goes stale, this does
+// not, because it ships with the CLI that implements it.
+
+import * as out from './out.mjs';
+import { PKG_NAME, PKG_VERSION } from './content.mjs';
+
+const RUN = `npx -y ${PKG_NAME}@${PKG_VERSION}`;
+
+export const GUIDE = `# ${PKG_NAME} — install protocol
+
+This CLI installs the Shopware agentic harness — 11 \`sw-*\` skills and 7
+\`sw-*\` sub-agents — into whichever coding agents this repository uses, and
+registers the MCP servers and permission rules they depend on.
+
+## The loop
+
+1. \`${RUN} status\`
+   Read-only. Reports which hosts are present, what is already installed, and
+   anything that has drifted since it was installed. Always safe.
+
+2. \`${RUN} plan\`
+   Prints the exact set of changes and writes nothing. Every entry says what it
+   would do and why. Show this to the user before applying.
+
+3. \`${RUN} apply --yes\`
+   Performs the changes. It refuses without \`--yes\`; there is no prompt,
+   because Codex's question tool does not block outside Plan mode and CI has no
+   terminal.
+
+4. \`${RUN} uninstall --yes\`
+   Removes what the lock file records and reverts the managed config blocks.
+
+## Flags
+
+  --host claude-code|codex|copilot|cursor   restrict to one host, repeatable
+  --scope project|user                      default: project
+  --root <path>                             default: the current directory
+  --no-companions                           skip the optional companion-package skills
+
+## Optional companion packages
+
+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. A \`skipped\` action means the
+package is not on this machine yet: install it with
+\`npm i -D <package>@<version>\` (the exact command is in the action's
+\`remedy\`, and in \`status\`'s \`companions\` array), then re-run
+\`${RUN} apply --yes\`.
+
+## 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.
+- **Exit codes:** 0 success, 2 usage error (your invocation was wrong),
+  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
+  left exactly as it is. Its \`remedy\` field tells the user what to do.
+- **Existing rules are never removed or loosened.** Permission lists are
+  merged. A rule you delete after install is recorded as declined and is never
+  offered again.
+- **Re-running is free.** A second \`apply\` reports everything as
+  \`unchanged\` and does not rewrite a single byte.
+
+## The one thing it cannot preserve
+
+Rewriting a JSON config re-serialises it, so an array the user had written on
+one line comes back expanded one element per line. Indentation, line endings,
+a BOM and key order are all preserved; inline array style is not, because
+preserving it would mean shipping a JSON parser that keeps a full syntax tree,
+and this CLI has no dependencies by design. Nothing is lost — the value is
+identical — but the diff is larger than the change. A file with comments or
+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.
+
+## If you are a skill
+
+Call this CLI. Do not re-implement any of it, and do not copy this text into a
+skill file — run \`${RUN} guide\` and follow what it says now.
+`;
+
+export async function main() {
+  return out.ok('guide', {
+    version: PKG_VERSION,
+    next_step: `${RUN} status`,
+    help: [`${RUN} status`, `${RUN} plan`, `${RUN} apply --yes`],
+    guide: GUIDE,
+  });
+}

package/lib/hosts.mjs

@@ -0,0 +1,283 @@
+// The host registry. Everything host-specific is declarative and lives here,
+// so adding a host or following a schema change is one table to edit.
+//
+// Detection is marker-directory existence only — no network, no process scan,
+// no `which`. It is allowed to be wrong in the harmless direction: a host that
+// is installed but has no marker directory simply is not written to, and
+// `--host` forces it.
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  agents, agentsMd, claudeSettings, mcpServers, LOCK_DIR, 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 { COMPANIONS } from './companions.mjs';
+
+export const HOSTS = ['claude-code', 'codex', 'copilot', 'cursor'];
+
+/** Where each host reads its skills from — the base every skill-copy and
+ * companion skill-copy action is rooted at. */
+export const SKILL_DIR = {
+  'claude-code': '.claude/skills',
+  codex: '.agents/skills',
+  copilot: '.github/skills',
+  cursor: '.cursor/skills',
+};
+
+const MARKERS = {
+  'claude-code': { project: ['.claude'], user: ['.claude'] },
+  codex: { project: ['.codex', '.agents'], user: ['.codex'] },
+  copilot: { project: ['.github', '.vscode'], user: ['.copilot'] },
+  cursor: { project: ['.cursor'], user: ['.cursor'] },
+};
+
+/** Where a host's trees live, given the scope. User scope is rooted at $HOME. */
+export function hostRoot(scope) {
+  return scope === 'user' ? homedir() : null;
+}
+
+/**
+ * Detect every host in parallel. Cheap enough that parallelism is cosmetic,
+ * 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))));
+}
+
+export function detect(id, ctx) {
+  const markers = MARKERS[id][ctx.scope] ?? MARKERS[id].project;
+  const present = markers.filter((m) => isDir(abs(ctx.root, m)));
+  const writable = present.every((m) => isWritable(abs(ctx.root, m)));
+  const notes = [];
+  if (id === 'codex' && present.length && !writable) {
+    notes.push(
+      '`.codex/` and `.agents/` are read-only under Codex\'s default workspace-write ' +
+        'sandbox. Run this CLI from a plain shell rather than from inside a Codex session.',
+    );
+  }
+  if (id === 'cursor' && isDir(abs(ctx.root, '.claude/skills')) && isDir(abs(ctx.root, '.claude/agents'))) {
+    notes.push('Skills and agents are read from `.claude/` directly — nothing to install under `.cursor/`.');
+  }
+  return { id, detected: present.length > 0, markers, marker: present[0] ?? markers[0], writable, notes };
+}
+
+// --------------------------------------------------------------- plans
+
+/** Build the full action list for the selected hosts. */
+export function buildPlan(ctx) {
+  const actions = [];
+  for (const id of ctx.hosts) actions.push(...planFor(id, ctx));
+  // Shared targets are emitted per host; the id dedupe collapses them.
+  return actions;
+}
+
+export function planFor(id, ctx) {
+  switch (id) {
+    case 'claude-code': return planClaude(ctx);
+    case 'codex': return planCodex(ctx);
+    case 'copilot': return planCopilot(ctx);
+    case 'cursor': return planCursor(ctx);
+    default: throw new Error(`unknown host: ${id}`);
+  }
+}
+
+function copyTree(host, sourceRoot, targetRoot) {
+  const out = [];
+  for (const file of walk(join(PKG_ROOT, sourceRoot))) {
+    const target = `${targetRoot}/${file}`;
+    out.push({
+      id: `${host}:file:${target}`, host, kind: 'file-copy',
+      source: `${sourceRoot}/${file}`, target,
+    });
+  }
+  return out;
+}
+
+function skillActions(host, targetBase) {
+  const out = [];
+  for (const skill of skills()) out.push(...copyTree(host, skill.root, `${targetBase}/${skill.name}`));
+  return out;
+}
+
+/**
+ * One `skill-copy` action per optional companion package. The `skill:`
+ * segment (not `file:`) keeps these ids from colliding, or deduping,
+ * against a shipped `file-copy` action at the same path.
+ */
+function companionActions(host, targetBase) {
+  return COMPANIONS.map((c) => {
+    const target = `${targetBase}/${c.id}/SKILL.md`;
+    return {
+      id: `${host}:skill:${target}`, host, kind: 'skill-copy',
+      companion: c.id, package: `${c.pkg}@${c.version}`, target,
+    };
+  });
+}
+
+function agentActions(host, targetBase, pick, ext) {
+  return agents().map((agent) => {
+    const target = `${targetBase}/${agent.name}${ext}`;
+    return {
+      id: `${host}:file:${target}`, host, kind: 'file-copy',
+      source: agent[pick], target,
+    };
+  });
+}
+
+function mcpJsonActions(host, file, rootKey, ctx) {
+  return mcpServers({ platform: ctx.platform, root: ctx.root, projectWiki: ctx.projectWiki }).map((server) => {
+    const { name, ...value } = server;
+    const pointer = `/${rootKey}/${name}`;
+    return {
+      id: `shared:json:${file}#${pointer}`, host, kind: 'json-merge',
+      target: file, pointer, op: 'set', value,
+    };
+  });
+}
+
+/** AGENTS.md — read by Codex, Copilot and Cursor; Claude Code reads CLAUDE.md. */
+function agentsMdAction(host) {
+  return {
+    id: 'shared:text:AGENTS.md#harness', host, kind: 'text-fence',
+    target: 'AGENTS.md', block: 'harness', syntax: 'markdown', body: agentsMd().trimEnd(),
+  };
+}
+
+/** The lock file describes one machine's install, so it is gitignored. */
+function gitignoreAction(host) {
+  return {
+    id: 'shared:text:.gitignore#lock', host, kind: 'text-fence',
+    target: '.gitignore', block: 'lock', syntax: 'gitignore', body: `${LOCK_DIR}/`,
+  };
+}
+
+function planClaude(ctx) {
+  const host = 'claude-code';
+  const out = [
+    ...skillActions(host, SKILL_DIR[host]),
+    ...(ctx.companions === false ? [] : companionActions(host, SKILL_DIR[host])),
+    ...agentActions(host, '.claude/agents', 'claude', '.md'),
+    ...mcpJsonActions(host, '.mcp.json', 'mcpServers', ctx),
+  ];
+  const settings = claudeSettings();
+  for (const rule of settings.rules) {
+    out.push({
+      id: `${host}:json:.claude/settings.json#${rule.pointer}`, host, kind: 'json-merge',
+      target: '.claude/settings.json', pointer: rule.pointer, op: 'array-union', values: rule.values,
+    });
+  }
+  for (const setting of settings.settings) {
+    out.push({
+      id: `${host}:json:.claude/settings.json#${setting.pointer}`, host, kind: 'json-merge',
+      target: '.claude/settings.json', pointer: setting.pointer, op: 'set', value: setting.value,
+    });
+  }
+  out.push(gitignoreAction(host));
+  return out;
+}
+
+function planCodex(ctx) {
+  const host = 'codex';
+  const out = [
+    // Codex discovers skills from `.agents/skills`, never `.claude/skills`.
+    ...skillActions(host, SKILL_DIR[host]),
+    ...(ctx.companions === false ? [] : companionActions(host, SKILL_DIR[host])),
+    ...agentActions(host, '.codex/agents', 'codex', '.toml'),
+  ];
+
+  const file = '.codex/config.toml';
+  const found = readTextMaybe(abs(ctx.root, file));
+  const text = found?.text ?? '';
+
+  // Codex is TOML-only and never reads `.mcp.json`, and performs no `${VAR}`
+  // expansion — so paths are resolved here, at install time.
+  const servers = mcpServers({ platform: ctx.platform, root: ctx.root, projectWiki: ctx.projectWiki });
+  const clash = servers.find((s) => tomlTableExists(text, `[mcp_servers.${s.name}]`, ['mcp_servers', 'agents']));
+  out.push({
+    id: `${host}:toml:${file}#mcp_servers`, host, kind: 'toml-fence',
+    target: file, block: 'mcp_servers', syntax: 'toml',
+    body: servers.map((s) => renderTomlTable(`[mcp_servers.${s.name}]`, {
+      command: s.command, args: s.args, type: undefined,
+    })).join('\n\n'),
+    conflict: clash && {
+      reason: `a \`[mcp_servers.${clash.name}]\` table already exists outside our managed block, and TOML forbids a duplicate table header`,
+      remedy: `remove or rename the existing [mcp_servers.${clash.name}] table in ${file}, then re-run apply`,
+    },
+  });
+
+  // `[agents]` may already be the user's own table. Merging would mean editing
+  // their lines, which this installer does not do — so it becomes a manual step.
+  const agentsClash = tomlTableExists(text, '[agents]', ['mcp_servers', 'agents']);
+  out.push({
+    id: `${host}:toml:${file}#agents`, host, kind: 'toml-fence',
+    target: file, block: 'agents', syntax: 'toml',
+    body: renderTomlTable('[agents]', { max_concurrent_threads_per_session: 4 }),
+    conflict: agentsClash && {
+      reason: `an unfenced [agents] table already exists in ${file}; TOML forbids a duplicate table header and the installer never edits your lines`,
+      remedy: `add \`max_concurrent_threads_per_session = 4\` to the existing [agents] table in ${file}`,
+    },
+  });
+
+  out.push(agentsMdAction(host), gitignoreAction(host));
+  return out;
+}
+
+function planCopilot(ctx) {
+  const host = 'copilot';
+  const out = [
+    ...skillActions(host, SKILL_DIR[host]),
+    ...(ctx.companions === false ? [] : companionActions(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.
+    ...mcpJsonActions(host, '.mcp.json', 'mcpServers', ctx),
+    ...mcpJsonActions(host, '.vscode/mcp.json', 'servers', ctx).map((a) => ({
+      ...a, id: a.id.replace('shared:', 'copilot:'),
+    })),
+    agentsMdAction(host),
+    gitignoreAction(host),
+  ];
+  return out;
+}
+
+function planCursor(ctx) {
+  const host = 'cursor';
+  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
+  // "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;
+  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.companions !== false) out.push(...companionActions(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;
+}
+
+/** What is already installed for a host, for `status`. */
+export function installedCounts(id, ctx) {
+  const lock = ctx.lock;
+  if (!lock) return {};
+  const mine = Object.entries(lock.files).filter(([, v]) => v.host === id);
+  const skillNames = new Set();
+  let agentCount = 0;
+  for (const [target] of mine) {
+    if (/\/skills\//.test(target)) skillNames.add(target.split('/skills/')[1].split('/')[0]);
+    else if (/\/agents\//.test(target)) agentCount += 1;
+  }
+  const mcp = lock.json_pointers.filter((p) => p.pointer.includes('erver') || p.pointer.startsWith('/mcpServers')).length;
+  const rules = lock.rules.reduce((n, r) => n + (r.values?.length ?? 0), 0);
+  return { skills: skillNames.size, agents: agentCount, mcp, rules };
+}
+
+export { findFence };