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

package/lib/commands.mjs

@@ -0,0 +1,446 @@
+// 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.
+
+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,
+} from './content.mjs';
+import { exists, isWritable, abs } from './fsx.mjs';
+import { HOSTS, buildPlan, detectAll, installedCounts } from './hosts.mjs';
+import * as lockfile from './lock.mjs';
+import { dedupe, execute, isWritableState, preview, pruneDirs, revert } from './actions.mjs';
+import { probeAll } from './companions.mjs';
+
+const RUN = 'sw-ecosystem-agentic-harness';
+
+class UsageError extends Error {
+  constructor(message, help) { super(message); this.help = help; }
+}
+
+/** Parse the flags every command shares. */
+export function buildContext(argv, command) {
+  const hosts = [];
+  let scope = 'project';
+  let root = process.cwd();
+  let yes = false;
+  let projectWiki;
+  let companions = true;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--yes' || arg === '-y') { yes = true; continue; }
+    if (arg === '--no-companions') { companions = false; continue; }
+    if (arg === '--host') {
+      const value = argv[++i];
+      if (!HOSTS.includes(value)) {
+        throw new UsageError(`unknown --host ${value ?? '(missing)'}`,
+          HOSTS.map((h) => `${RUN} ${command} --host ${h}`));
+      }
+      hosts.push(value);
+      continue;
+    }
+    if (arg === '--scope') {
+      const value = argv[++i];
+      if (value !== 'project' && value !== 'user') {
+        throw new UsageError(`unknown --scope ${value ?? '(missing)'}`,
+          [`${RUN} ${command} --scope project`, `${RUN} ${command} --scope user`]);
+      }
+      scope = value;
+      continue;
+    }
+    if (arg === '--root') { root = argv[++i] ?? root; continue; }
+    if (arg === '--project-wiki') { projectWiki = argv[++i]; continue; }
+    throw new UsageError(`unknown option ${arg}`, [`${RUN} guide`, `${RUN} ${command}`]);
+  }
+
+  // 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, companions,
+    hosts: hosts.length ? [...new Set(hosts)] : [...HOSTS],
+    platform: process.platform,
+    version: PKG_VERSION,
+    lock: null,
+  };
+}
+
+function head(ctx, extra = {}) {
+  return {
+    version: PKG_VERSION, content_version: CONTENT_VERSION,
+    scope: ctx.scope, root: ctx.root, ...extra,
+  };
+}
+
+function loadLock(ctx) {
+  ctx.lock = lockfile.read(ctx.root, ctx.scope);
+  return ctx.lock;
+}
+
+/** Preview every action for the selected hosts, aggregating per-host failures. */
+function previewAll(ctx) {
+  const errors = [];
+  const actions = [];
+  for (const host of ctx.hosts) {
+    try {
+      const forHost = dedupe(buildPlan({ ...ctx, hosts: [host], selectedHosts: ctx.hosts }));
+      for (const action of forHost) {
+        try {
+          actions.push(preview(action, ctx));
+        } catch (e) {
+          errors.push({ host, target: action.target, error: e.message });
+        }
+      }
+    } catch (e) {
+      errors.push({ host, error: e.message });
+    }
+  }
+  return { actions: dedupe(actions), errors };
+}
+
+function summarise(actions) {
+  const s = { create: 0, update: 0, unchanged: 0, drift: 0, conflict: 0, manual: 0, skipped: 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;
+  return rest;
+}
+
+// ------------------------------------------------------------------ status
+
+export async function status(argv) {
+  const ctx = buildContext(argv, 'status');
+  let lock = null;
+  try { lock = loadLock(ctx); } catch (e) {
+    if (e instanceof lockfile.LockVersionError) {
+      return out.failure('status', e.message, {
+        next_step: `Upgrade the package: npm i -D ${PKG_NAME}@latest`,
+        help: [`npm i -D ${PKG_NAME}@latest`, `${RUN} status`],
+      });
+    }
+    throw e;
+  }
+
+  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 mine = actions.filter((a) => a.host === d.id || a.host === 'shared');
+    let state = 'absent';
+    if (d.detected) {
+      const pending = mine.filter((a) => isWritableState(a.state));
+      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';
+    }
+    return {
+      id: d.id, detected: d.detected, marker: d.marker, writable: d.writable,
+      installed: installedCounts(d.id, ctx), state, notes: d.notes,
+    };
+  });
+
+  const drift = actions.filter((a) => a.state === 'drift' || a.state === 'conflict').map((a) => ({
+    target: a.target, 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 companions = ctx.companions === 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}`,
+  }));
+
+  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.companions !== false) {
+    const unavailable = companions.filter((c) => !c.available);
+    if (unavailable.length) {
+      next += ` ${unavailable.length} optional companion package(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,
+    state: worst,
+    next_step: next,
+    help: [`${RUN} plan`, `${RUN} apply --yes`, `${RUN} guide`],
+    inventory: { skills: skills().length, agents: agents().length },
+    hosts, companions, drift,
+    declined: lock?.declined ?? [],
+    manual: lock?.manual ?? [],
+    errors,
+  }));
+}
+
+// -------------------------------------------------------------------- plan
+
+export async function plan(argv) {
+  const ctx = buildContext(argv, 'plan');
+  try { loadLock(ctx); } catch (e) {
+    if (e instanceof lockfile.LockVersionError) {
+      return out.failure('plan', e.message, {
+        next_step: `Upgrade the package: npm i -D ${PKG_NAME}@latest`,
+        help: [`npm i -D ${PKG_NAME}@latest`],
+      });
+    }
+    throw e;
+  }
+  const { actions, errors } = previewAll(ctx);
+  const summary = summarise(actions);
+  const changes = summary.create + summary.update;
+
+  let 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}`)],
+    actions: actions.map(publicAction),
+    errors,
+  }));
+}
+
+// ------------------------------------------------------------------- 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) {
+  const ctx = buildContext(argv, 'apply');
+  if (!ctx.yes) {
+    return out.usage('apply', 'apply refuses to write without --yes',
+      [`${RUN} plan`, `${RUN} apply --yes`]);
+  }
+
+  let lock;
+  try { lock = loadLock(ctx) ?? lockfile.empty(ctx.scope); } catch (e) {
+    if (e instanceof lockfile.LockVersionError) {
+      return out.failure('apply', e.message, {
+        next_step: `Upgrade the package: npm i -D ${PKG_NAME}@latest`,
+        help: [`npm i -D ${PKG_NAME}@latest`],
+      });
+    }
+    throw e;
+  }
+
+  // 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('apply', `cannot write the lock file at ${LOCK_FILE}`, {
+      next_step: `Make ${ctx.root} writable, then re-run \`${RUN} apply --yes\`.`,
+      help: [`${RUN} status`],
+    });
+  }
+
+  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 manual = [];
+
+  for (const action of actions) {
+    const bucket = perHost.get(action.host) ?? perHost.get(ctx.hosts[0]);
+    if (action.state === 'manual') {
+      manual.push({ target: action.target, reason: action.reason, remedy: action.remedy });
+      results.push({ ...publicAction(action), state: 'manual' });
+      continue;
+    }
+    if (!isWritableState(action.state)) {
+      if (action.state === 'unchanged' && bucket) bucket.unchanged += 1;
+      results.push(publicAction(action));
+      continue;
+    }
+    try {
+      const entry = execute(action, ctx);
+      lock = lockfile.record(lock, [entry], { host: 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) {
+      if (bucket) bucket.failed += 1;
+      errors.push({ host: action.host, target: action.target, error: e.message });
+      results.push({ ...publicAction(action), state: 'failed', reason: e.message });
+    }
+  }
+
+  // Rules the user deleted after we installed them are declines, not gaps.
+  for (const action of actions) {
+    for (const value of action.newly_declined ?? []) {
+      lock = lockfile.decline(lock, {
+        file: action.target, pointer: action.pointer, value,
+        reason: 'removed by the user after install',
+      });
+    }
+  }
+  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 } } };
+  }
+  lockfile.write(ctx.root, lock);
+
+  const summary = {
+    created: results.filter((r) => r.state === 'created').length,
+    updated: results.filter((r) => r.state === 'updated').length,
+    unchanged: results.filter((r) => r.state === 'unchanged').length,
+    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);
+  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.`
+      + (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,
+  });
+  return summary.failed ? out.failure('apply', `${summary.failed} change(s) failed`, body) : out.ok('apply', body);
+}
+
+// --------------------------------------------------------------- uninstall
+
+export async function uninstall(argv) {
+  const ctx = buildContext(argv, 'uninstall');
+  if (!ctx.yes) {
+    return out.usage('uninstall', 'uninstall refuses to write without --yes',
+      [`${RUN} status`, `${RUN} uninstall --yes`]);
+  }
+
+  let lock;
+  try { lock = loadLock(ctx); } catch (e) {
+    if (e instanceof lockfile.LockVersionError) {
+      return out.failure('uninstall', e.message, {
+        next_step: `Upgrade the package: npm i -D ${PKG_NAME}@latest`,
+        help: [`npm i -D ${PKG_NAME}@latest`],
+      });
+    }
+    throw e;
+  }
+
+  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.`,
+      help: [`${RUN} status`],
+      kept: [], missing: [], errors: [],
+    }));
+  }
+
+  const selected = new Set(ctx.hosts);
+  const all = lockfile.entries(lock);
+  const mine = all.filter((e) => !e.host || selected.has(e.host) || e.host === 'shared');
+
+  const kept = [];
+  const missing = [];
+  const errors = [];
+  let removed = 0;
+  let reverted = 0;
+  const survivors = [];
+
+  for (const entry of mine) {
+    try {
+      const result = revert(entry, ctx);
+      if (result.state === 'removed') removed += 1;
+      else if (result.state === 'reverted') reverted += 1;
+      else if (result.state === 'kept') { kept.push(result); survivors.push(entry); }
+      else missing.push(result);
+    } catch (e) {
+      errors.push({ target: entry.target, error: e.message });
+      survivors.push(entry);
+    }
+  }
+
+  const prunedDirs = pruneDirs(lock.dirs ?? [], ctx);
+  const failed = errors.length;
+
+  if (failed === 0 && survivors.length === 0 && selected.size === HOSTS.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);
+  } else {
+    // Keep a lock describing exactly what survived, so a re-run resumes.
+    lockfile.write(ctx.root, rebuild(lock, survivors, selected));
+  }
+
+  const body = head(ctx, {
+    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`],
+    kept, missing, pruned_dirs: prunedDirs, errors,
+  });
+  return failed ? out.failure('uninstall', `${failed} item(s) could not be removed`, body) : out.ok('uninstall', body);
+}
+
+function rebuild(lock, survivors, selected) {
+  const files = {};
+  const json_pointers = [];
+  const rules = [];
+  const fences = [];
+  for (const entry of survivors) {
+    if (entry.kind === 'file-copy') files[entry.target] = { host: entry.host, source: entry.source, hash: entry.hash, bytes: entry.bytes, created_file: entry.created_file };
+    else if (entry.kind === 'json-merge' && entry.op === 'array-union') rules.push(entry);
+    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 };
+}
+
+export { UsageError };

package/lib/companions.mjs

@@ -0,0 +1,117 @@
+// The two optional companion packages, probed rather than installed by us.
+//
+// Read-then-copy, not `install-skill --target`: the engine's whole safety
+// story is "hash what we intend to write, compare, record". A foreign binary
+// that writes on its own cannot be previewed, so `plan` would lie and
+// `uninstall` would have to guess. Reading the body with `--print` and
+// copying it ourselves through `writeAtomic` keeps every companion skill on
+// the same adopt/conflict/drift/update ladder as everything else this CLI
+// writes, and makes `uninstall` exact even after the user has removed the
+// companion package — the common case, since it is optional.
+//
+// `--no-install` plus `npm_config_yes=false` are two independent guards that
+// this can never reach the network: the first tells npx not to fetch a
+// missing package, the second refuses the prompt that would offer to.
+
+import { spawnSync } from 'node:child_process';
+import { sha256 } from './fsx.mjs';
+import { wrapCommand } from './content.mjs';
+
+export const COMPANIONS = [
+  {
+    id: 'sw-specs-editor', pkg: '@execuro-sw-ecosystem/sw-specs-editor', version: '0.1.0',
+    label: 'Specs Editor',
+  },
+  {
+    id: 'sw-tender-discovery-tool', pkg: '@execuro-sw-ecosystem/sw-tender-discovery-tool', version: '0.1.0',
+    label: 'Tender Discovery Tool',
+  },
+];
+
+/** The argv `probe` would spawn, without spawning it — for tests. */
+export function probeArgs(companion, platform) {
+  const spec = `${companion.pkg}@${companion.version}`;
+  const wrapped = wrapCommand(
+    { command: 'npx', args: ['--no-install', spec, 'install-skill', '--print'] },
+    platform,
+  );
+  return [wrapped.command, ...wrapped.args];
+}
+
+// One probe per `<pkg>@<version>` per process. `status`/`plan`/`apply` each
+// ask this question once per host, and the answer never changes mid-run.
+const cache = new Map();
+
+export function resetProbeCache() {
+  cache.clear();
+}
+
+function lastLine(text) {
+  const lines = text.trim().split('\n').filter(Boolean);
+  return lines.length ? lines[lines.length - 1] : '';
+}
+
+function doProbe(companion, platform) {
+  const spec = `${companion.pkg}@${companion.version}`;
+  const base = { id: companion.id, pkg: companion.pkg, version: companion.version, spec, label: companion.label };
+  const wrapped = wrapCommand(
+    { command: 'npx', args: ['--no-install', spec, 'install-skill', '--print'] },
+    platform,
+  );
+
+  const res = spawnSync(wrapped.command, wrapped.args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 20000,
+    windowsHide: true,
+    env: { ...process.env, npm_config_yes: 'false', npm_config_audit: 'false' },
+  });
+
+  if (res.error) {
+    if (res.error.code === 'ENOENT') {
+      return { ...base, available: false, state: 'probe-failed', reason: 'npx was not found on PATH' };
+    }
+    return {
+      ...base, available: false, state: 'probe-failed',
+      reason: `probing ${spec} failed: ${res.error.message}`,
+    };
+  }
+  if (res.signal) {
+    return {
+      ...base, available: false, state: 'probe-failed',
+      reason: `probing ${spec} was killed (${res.signal}), possibly a timeout`,
+    };
+  }
+  if (res.status !== 0) {
+    return {
+      ...base, available: false, state: 'absent', reason: `${spec} is not installed locally`,
+      detail: lastLine((res.stderr ?? Buffer.alloc(0)).toString('utf8')),
+    };
+  }
+  const stdout = res.stdout ?? Buffer.alloc(0);
+  if (stdout.length === 0) {
+    return {
+      ...base, available: false, state: 'probe-failed',
+      reason: `${spec} install-skill --print returned nothing`,
+    };
+  }
+  if (!stdout.toString('utf8').startsWith('---')) {
+    return {
+      ...base, available: false, state: 'probe-failed',
+      reason: `${spec} install-skill --print did not return a skill document`,
+    };
+  }
+  return { ...base, available: true, state: 'available', body: stdout, hash: sha256(stdout), bytes: stdout.length };
+}
+
+/** Probe one companion. Never throws. */
+export function probe(companion, { platform = process.platform } = {}) {
+  const key = `${companion.pkg}@${companion.version}`;
+  if (cache.has(key)) return cache.get(key);
+  const result = doProbe(companion, platform);
+  cache.set(key, result);
+  return result;
+}
+
+export function probeAll(opts) {
+  return COMPANIONS.map((c) => probe(c, opts));
+}

package/lib/content.mjs

@@ -0,0 +1,101 @@
+// What this package ships, and the two things that can only be decided on the
+// user's machine: an absolute path, and `process.platform`.
+//
+// Everything else — the Codex TOMLs, the Copilot adapters, AGENTS.md — is
+// generated at build time by `scripts/gen-*.mjs`, committed and CI-diffed. A
+// bad transform is then a red CI run on our own PR rather than a stranger's
+// broken install.
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { walk } from './fsx.mjs';
+
+export const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+const pkg = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8'));
+export const PKG_NAME = pkg.name;
+export const PKG_VERSION = pkg.version;
+
+/**
+ * The layout of what we install. Bumped only when an old CLI would write a
+ * layout a newer one cannot uninstall; the lock records it and `read()`
+ * refuses anything not in SUPPORTED_CONTENT.
+ */
+export const CONTENT_VERSION = 1;
+export const SUPPORTED_CONTENT = [1];
+
+export const LOCK_DIR = '.sw-ai-sdk';
+export const LOCK_FILE = `${LOCK_DIR}/harness.lock.json`;
+
+function dirsIn(abs) {
+  return readdirSync(abs)
+    .filter((entry) => statSync(join(abs, entry)).isDirectory())
+    .sort();
+}
+
+/** Every shipped skill, with its file list relative to the skill directory. */
+export function skills() {
+  const root = join(PKG_ROOT, 'skills');
+  return dirsIn(root).map((name) => ({
+    name,
+    root: `skills/${name}`,
+    files: walk(join(root, name)),
+  }));
+}
+
+/** Every shipped agent, with the path to each host's adapter. */
+export function agents() {
+  const root = join(PKG_ROOT, 'agents');
+  return readdirSync(root)
+    .filter((f) => f.endsWith('.md'))
+    .sort()
+    .map((file) => {
+      const name = file.replace(/\.md$/, '');
+      return {
+        name,
+        claude: `agents/${name}.md`,
+        codex: `codex/agents/${name}.toml`,
+        copilot: `copilot/agents/${name}.agent.md`,
+      };
+    });
+}
+
+export function agentsMd() {
+  return readFileSync(join(PKG_ROOT, 'content', 'AGENTS.md'), 'utf8');
+}
+
+/** The permission rules and settings keys the installer merges. */
+export function claudeSettings() {
+  return JSON.parse(readFileSync(join(PKG_ROOT, 'content', 'claude-settings.json'), 'utf8'));
+}
+
+/**
+ * Wrap a command for the host platform.
+ *
+ * `npx` on Windows is a `.cmd` shim, and a bare `"command": "npx"` fails with
+ * `spawn ENOENT` in every host we target. `platform` is a parameter rather
+ * than a read of `process.platform` so the Windows behaviour is testable on
+ * Linux — which is the only way it ever actually gets tested.
+ */
+export function wrapCommand({ command, args }, platform) {
+  if (platform === 'win32') return { command: 'cmd', args: ['/c', command, ...args] };
+  return { command, args: [...args] };
+}
+
+/**
+ * The MCP servers to register, fully resolved: no `${VAR}`, because Codex
+ * performs no expansion at all and the others disagree about the syntax.
+ */
+export function mcpServers({ platform, root, projectWiki } = {}) {
+  const spec = JSON.parse(readFileSync(join(PKG_ROOT, 'content', 'mcp-servers.json'), 'utf8'));
+  return spec.servers.map((server) => {
+    const args = [...server.args];
+    if (server.projectWikiFlag) {
+      const wiki = projectWiki ?? join(root ?? process.cwd(), ...server.projectWikiDefault.split('/'));
+      args.push(server.projectWikiFlag, wiki);
+    }
+    const wrapped = wrapCommand({ command: 'npx', args }, platform);
+    return { name: server.name, type: 'stdio', ...wrapped };
+  });
+}