@svenroth-ai/shipwright 0.24.1-next.0

package/lib/cache-sync.mjs

@@ -0,0 +1,243 @@
+/**
+ * cache-sync.mjs — AC1b, the single most important fact in this sub-iterate.
+ *
+ * `claude plugin install` alone leaves a BROKEN install: the plugins' hooks run
+ * `uv run "${CLAUDE_PLUGIN_ROOT}/../../shared/scripts/…"`, and that `shared/`
+ * tree is NOT a plugin, NOT in the manifest, so `install` never delivers it.
+ * Every hook of every plugin then dies at session start while the plugin still
+ * lists as installed. This module absorbs the BEHAVIOUR of
+ * `scripts/update-marketplace.sh` (sync shared/, full file-sync, plugins/
+ * symlink layer with a Windows copy fallback, GC of stale version dirs) — but
+ * NEVER its hardcoded 14-plugin list; the names come from the manifest.
+ *
+ * Pure over concrete paths + node:fs, so tests drive it against temp dirs.
+ */
+
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  readlinkSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+} from "node:fs";
+import path from "node:path";
+
+const SKIP_DIRS = new Set([
+  "__pycache__",
+  ".git",
+  ".venv",
+  "venv",
+  ".pytest_cache",
+  "node_modules",
+]);
+
+/** Recursively list files under `dir` (posix-relative), skipping SKIP_DIRS + *.pyc. */
+export function listFiles(dir, base = dir) {
+  /** @type {string[]} */
+  const out = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      out.push(...listFiles(path.join(dir, e.name), base));
+    } else if (e.isFile()) {
+      if (e.name.endsWith(".pyc")) continue;
+      out.push(path.relative(base, path.join(dir, e.name)).split(path.sep).join("/"));
+    }
+  }
+  return out;
+}
+
+function bytesEqual(a, b) {
+  try {
+    return readFileSync(a).equals(readFileSync(b));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Full file sync src → dst: add new, overwrite changed, remove orphans. Mirrors
+ * update-marketplace.sh's deliberate "full sync regardless of version number"
+ * (a version compare alone is NOT sufficient to decide "already up to date").
+ * @returns {{ added: number, changed: number, removed: number }}
+ */
+export function fullFileSync(src, dst) {
+  if (!existsSync(src)) return { added: 0, changed: 0, removed: 0 };
+  mkdirSync(dst, { recursive: true });
+  let added = 0;
+  let changed = 0;
+  let removed = 0;
+  for (const rel of listFiles(src)) {
+    const from = path.join(src, rel);
+    const to = path.join(dst, rel);
+    if (!existsSync(to)) {
+      mkdirSync(path.dirname(to), { recursive: true });
+      cpSync(from, to);
+      added++;
+    } else if (!bytesEqual(from, to)) {
+      cpSync(from, to);
+      changed++;
+    }
+  }
+  const srcSet = new Set(listFiles(src));
+  for (const rel of listFiles(dst)) {
+    if (!srcSet.has(rel)) {
+      rmSync(path.join(dst, rel), { force: true });
+      removed++;
+    }
+  }
+  return { added, changed, removed };
+}
+
+/** THE make-or-break step: marketplace `shared/` → `<cacheRoot>/shared/`. */
+export function syncSharedTree(marketplaceDir, cacheRoot) {
+  return fullFileSync(path.join(marketplaceDir, "shared"), path.join(cacheRoot, "shared"));
+}
+
+/** Full-sync one plugin's marketplace source into its installed version dir. */
+export function syncPluginCache(marketplaceDir, name, installPath) {
+  return fullFileSync(path.join(marketplaceDir, "plugins", name), installPath);
+}
+
+/**
+ * The plugins/ symlink layer: `<cacheRoot>/plugins/<name>` → the version dir, so
+ * cross-plugin `../../plugins/<name>` references resolve. A symlink silently
+ * degrades to a copy on Windows non-admin — handle that explicitly (copy),
+ * never assume the link took.
+ * @returns {"symlink"|"copied"|"skipped"}
+ */
+export function ensurePluginsLayer(name, installPath, cacheRoot) {
+  if (!installPath || !existsSync(installPath)) return "skipped";
+  const linkDir = path.join(cacheRoot, "plugins");
+  mkdirSync(linkDir, { recursive: true });
+  const linkPath = path.join(linkDir, name);
+  try {
+    if (existsSync(linkPath) || isSymlink(linkPath)) {
+      if (isSymlink(linkPath) && safeReadlink(linkPath) === installPath) return "symlink";
+      rmSync(linkPath, { recursive: true, force: true });
+    }
+    symlinkSync(installPath, linkPath, "junction");
+    if (isSymlink(linkPath)) return "symlink";
+  } catch {
+    /* fall through to copy */
+  }
+  fullFileSync(installPath, linkPath);
+  return "copied";
+}
+
+function isSymlink(p) {
+  try {
+    return lstatSync(p).isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+function safeReadlink(p) {
+  try {
+    return readlinkSync(p);
+  } catch {
+    return null;
+  }
+}
+
+/** Remove `<cacheRoot>/<name>/<v>` dirs that are not the installed version. */
+export function gcStaleVersionDirs(name, cacheRoot, keepVersion) {
+  const base = path.join(cacheRoot, name);
+  if (!keepVersion || !existsSync(base)) return [];
+  const removed = [];
+  for (const entry of readdirSync(base, { withFileTypes: true })) {
+    if (entry.isDirectory() && entry.name !== keepVersion) {
+      rmSync(path.join(base, entry.name), { recursive: true, force: true });
+      removed.push(entry.name);
+    }
+  }
+  return removed;
+}
+
+/** Extract `${CLAUDE_PLUGIN_ROOT}/../../shared/<rel>` references from a hooks.json blob. */
+export function hookSharedRefs(hooksJsonText) {
+  const refs = new Set();
+  const re = /\$\{CLAUDE_PLUGIN_ROOT\}((?:\/\.\.)+\/shared\/[A-Za-z0-9_./-]+)/g;
+  let m;
+  while ((m = re.exec(hooksJsonText)) !== null) refs.add(m[1]);
+  return [...refs];
+}
+
+/**
+ * AC1b post-condition self-check. For each installed plugin version dir, every
+ * `${CLAUDE_PLUGIN_ROOT}/../../shared/…` its hooks.json references must resolve
+ * to a real file, the plugins/ layer entry must exist, and NO stale version
+ * dir may remain beside the installed one. Also asserts the canonical
+ * `shared/scripts/hooks/capture_session_id.py` is present, and — when
+ * `requestedNames` is passed — that EVERY requested manifest plugin actually
+ * materialised (a failed/partial install can otherwise be silently "coherent").
+ * @param {{ cacheRoot: string, pluginVersionDirs: {name:string, versionDir:string}[], requestedNames?: string[] }} opts
+ * @returns {{ ok: boolean, problems: string[] }}
+ */
+export function verifyCacheCoherent({ cacheRoot, pluginVersionDirs, requestedNames }) {
+  const problems = [];
+  const canary = path.join(cacheRoot, "shared", "scripts", "hooks", "capture_session_id.py");
+  if (!existsSync(canary)) problems.push(`missing shared canary: ${canary}`);
+
+  const materialised = new Set(pluginVersionDirs.map((p) => p.name));
+  for (const name of requestedNames ?? []) {
+    if (!materialised.has(name)) {
+      problems.push(`${name}: requested by the manifest but not installed/synced (hooks would be absent)`);
+    }
+  }
+
+  for (const { name, versionDir } of pluginVersionDirs) {
+    const hooksJson = path.join(versionDir, "hooks", "hooks.json");
+    if (existsSync(hooksJson)) {
+      let text = "";
+      try {
+        text = readFileSync(hooksJson, "utf-8");
+      } catch {
+        problems.push(`${name}: hooks.json unreadable`);
+      }
+      for (const ref of hookSharedRefs(text)) {
+        // Resolve exactly as the runtime does: relative to the version dir.
+        const resolved = path.resolve(versionDir, "." + ref);
+        if (!existsSync(resolved)) problems.push(`${name}: hook path does not resolve: ${resolved}`);
+      }
+    }
+    const layer = path.join(cacheRoot, "plugins", name);
+    if (!existsSync(layer) && !isSymlink(layer)) {
+      problems.push(`${name}: plugins/ layer entry missing (${layer})`);
+    }
+    // No stale version dir may linger beside the installed version.
+    const installedVersion = path.basename(versionDir);
+    const base = path.join(cacheRoot, name);
+    try {
+      for (const entry of readdirSync(base, { withFileTypes: true })) {
+        if (entry.isDirectory() && entry.name !== installedVersion) {
+          problems.push(`${name}: stale version dir not GC'd: ${entry.name}`);
+        }
+      }
+    } catch {
+      /* base not enumerable — the missing-plugin check above already covers it */
+    }
+  }
+  return { ok: problems.length === 0, problems };
+}
+
+/** Best-effort: newest-looking size for a dir (used only for diagnostics). */
+export function dirExists(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/lib/claude-cli.mjs

@@ -0,0 +1,173 @@
+/**
+ * claude-cli.mjs — the OS-touching default seams for plugins.mjs.
+ *
+ * Split out (like deploy-procs.mjs vs kill-targets.js) so plugins.mjs stays
+ * pure and fully unit-testable. Everything here talks to the real `claude`
+ * binary, the real `~/.claude/plugins/` tree, or the network — and every one
+ * of them is injectable, so tests never touch any of it.
+ *
+ * ARCHITECTURE FENCE: this drives the `claude` PLUGIN CLI as an installer. It
+ * NEVER starts a `claude` session and never writes `~/.claude/projects/**`,
+ * `shipwright_run_config.json`, or `run_loop_state.json` (CLAUDE.md rule 1 /
+ * DO-NOT #12). The only verbs used are `plugin marketplace …` and `plugin
+ * install|update …`.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { MANIFEST_RAW_URL, buildInstalledMap } from "./plugins.mjs";
+import { resolveSpawn } from "./win32-spawn.mjs";
+
+/**
+ * Argument charset gate for the `claude` CLI. Exported so BOTH directions can be
+ * asserted without starting a process (a gate that refuses everything would pass
+ * a refusal-only test). See `defaultRunClaude` for why it is still load-bearing
+ * after the shell:true removal.
+ */
+export const SAFE_ARG = /^[A-Za-z0-9@._/:-]+$/;
+
+/** The one "we could not run claude at all" verdict, identical on every platform. */
+const notFound = () => ({
+  ok: false,
+  code: null,
+  stdout: "",
+  stderr: "claude not found on PATH",
+});
+
+/**
+ * Run the real `claude` CLI, always with `shell: false`.
+ *
+ * On Windows `claude` is often a `.cmd` shim, which a bare `shell: false` spawn
+ * cannot reach: `CreateProcess` only ever appends `.exe`, and Node's
+ * CVE-2024-27980 hardening EINVAL-blocks a direct `.cmd`. That used to be
+ * answered with `shell: true`; it is now answered by `resolveSpawn`, which finds
+ * the real file via PATHEXT and invokes a shim through an explicit
+ * `cmd.exe /d /s /c` with discrete argv (see lib/win32-spawn.mjs).
+ *
+ * SAFE_ARG STAYS, and is still load-bearing — do not remove it as newly
+ * redundant. A `.cmd` target is still ultimately parsed by cmd.exe, and Node
+ * quotes an argument for spaces, not for `&` / `|` / `^` / `%`. The charset gate
+ * is what guarantees no token can carry one. What changed is that an `.exe`
+ * target (the common case — `claude.exe` from the native installer) now involves
+ * no cmd.exe at all.
+ * @param {string[]} args
+ */
+export function defaultRunClaude(args) {
+  for (const a of args) {
+    if (!SAFE_ARG.test(a)) {
+      return { ok: false, code: null, stdout: "", stderr: `refused unsafe claude arg: ${a}` };
+    }
+  }
+  const plan = resolveSpawn(["claude", ...args]);
+  if (!plan) {
+    // UNREACHABLE as of iterate-2026-07-31: `resolveSpawn` no longer returns
+    // null — an unresolvable bare name comes back as the bare name for
+    // CreateProcess to resolve PATH-only (win32-spawn divergence 5), and the
+    // ENOENT that follows is turned into `notFound()` below. What actually
+    // prevents cmd.exe's cwd-first lookup is that fallback, NOT this branch.
+    // Kept as contract insurance: if the resolver ever regains a null path,
+    // this is already the right answer. Verified 2026-08-01.
+    return notFound();
+  }
+  const r = spawnSync(plan.command, plan.args, {
+    encoding: "utf-8",
+    shell: false,
+    timeout: 120_000,
+    windowsVerbatimArguments: plan.windowsVerbatimArguments,
+  });
+  // POSIX takes `resolveSpawn`'s pass-through branch, so an absent `claude`
+  // arrives here as an ENOENT spawn error with EMPTY stderr instead of the
+  // win32 resolver's null. Report the SAME verdict on both platforms — a caller
+  // should not have to know which OS swallowed the message.
+  if (r.error && r.error.code === "ENOENT") return notFound();
+  return {
+    ok: r.status === 0 && !r.error,
+    code: r.status ?? null,
+    stdout: (r.stdout ?? "").toString(),
+    stderr: (r.stderr ?? "").toString(),
+  };
+}
+
+/** `~/.claude/plugins` root (override via CLAUDE_PLUGINS_ROOT for tests). */
+export function pluginsRoot(env = process.env, home = os.homedir()) {
+  return env.CLAUDE_PLUGINS_ROOT || path.join(home, ".claude", "plugins");
+}
+
+export function installedPluginsPath(env, home) {
+  return path.join(pluginsRoot(env, home), "installed_plugins.json");
+}
+
+export function marketplaceDir(env, home) {
+  return path.join(pluginsRoot(env, home), "marketplaces", "shipwright");
+}
+
+export function cacheRoot(env, home) {
+  return path.join(pluginsRoot(env, home), "cache", "shipwright");
+}
+
+/** Read + parse installed_plugins.json into a `{ name: version }` map (empty on any error). */
+export function defaultSnapshotInstalled(env = process.env, home = os.homedir()) {
+  try {
+    const raw = readFileSync(installedPluginsPath(env, home), "utf-8");
+    return buildInstalledMap(JSON.parse(raw));
+  } catch {
+    return {};
+  }
+}
+
+/** Precedence 1 — the local marketplace clone materialised by `marketplace add`. */
+export function defaultReadLocalManifest(env = process.env, home = os.homedir()) {
+  const p = path.join(marketplaceDir(env, home), ".claude-plugin", "marketplace.json");
+  try {
+    if (!existsSync(p)) return null;
+    return { text: readFileSync(p, "utf-8"), source: p };
+  } catch {
+    return null;
+  }
+}
+
+/** Precedence 2 — GitHub raw. Offline-safe: any failure resolves to null. */
+export function makeFetchRemoteManifest(deps = {}) {
+  const {
+    fetchImpl = typeof fetch === "function" ? fetch : undefined,
+    url = MANIFEST_RAW_URL,
+    timeoutMs = 4000,
+  } = deps;
+  return async () => {
+    if (!fetchImpl) return null;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetchImpl(url, { signal: ctrl.signal });
+      if (!res || !res.ok) return null;
+      return { text: await res.text(), source: url };
+    } catch {
+      return null;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+
+/** Precedence 3 — explicit path override (also the test seam). */
+export function defaultReadOverrideManifest(env = process.env) {
+  const p = env.SHIPWRIGHT_MARKETPLACE_MANIFEST;
+  if (!p) return null;
+  // A set-but-unreadable override is an OPERATOR error, not a fall-through:
+  // surface it loudly rather than silently sliding to "no list".
+  return { text: readFileSync(p, "utf-8"), source: p };
+}
+
+/** Bundle the three resolver seams with their real implementations. */
+export function defaultResolverSeams(deps = {}) {
+  const env = deps.env ?? process.env;
+  const home = deps.home ?? os.homedir();
+  return {
+    readLocalManifest: () => defaultReadLocalManifest(env, home),
+    fetchRemoteManifest: makeFetchRemoteManifest(deps),
+    readOverrideManifest: () => defaultReadOverrideManifest(env),
+  };
+}

package/lib/plugins.mjs

@@ -0,0 +1,181 @@
+/**
+ * plugins.mjs — manifest-derived plugin install/update (NEVER a hardcoded list).
+ *
+ * The list of plugins comes from the marketplace manifest, in strict
+ * precedence: (1) the local marketplace cache that `claude plugin marketplace
+ * add/update` materialises, (2) a fetch of the GitHub raw manifest, (3) the
+ * `SHIPWRIGHT_MARKETPLACE_MANIFEST` path override (also the test seam). There is
+ * no step 4: if none resolve we ABORT loudly rather than bake in a list.
+ *
+ * Why so emphatic: the monorepo README says "all 13 plugins" while
+ * `.claude-plugin/marketplace.json` lists 14 — the hardcoded list already
+ * drifted. A baked list is a bug waiting to happen; the manifest is the SSoT.
+ *
+ * This module is PURE over injected seams (resolve, run, snapshot). The default
+ * OS-touching implementations live in `claude-cli.mjs`.
+ */
+
+export const MANIFEST_RAW_URL =
+  "https://raw.githubusercontent.com/svenroth-ai/shipwright/main/.claude-plugin/marketplace.json";
+
+/**
+ * Parse + DEFENSIVELY validate a marketplace manifest. A cross-repo schema
+ * change breaks every user at once, so an unrecognised shape is a hard error
+ * that NAMES the source — never a silent empty/partial plugin list.
+ * @param {string} text @param {string} source  URL or path, for the error text
+ * @returns {string[]} plugin names, in manifest order
+ */
+export function parseManifest(text, source) {
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch (e) {
+    throw new Error(`marketplace manifest at ${source} is not valid JSON: ${String(e?.message ?? e)}`);
+  }
+  if (!data || typeof data !== "object" || !Array.isArray(data.plugins)) {
+    throw new Error(
+      `marketplace manifest at ${source} has no plugins[] array — refusing to guess a plugin list`,
+    );
+  }
+  const names = [];
+  const seen = new Set();
+  for (const p of data.plugins) {
+    if (!p || typeof p.name !== "string" || p.name.trim() === "") {
+      throw new Error(
+        `marketplace manifest at ${source} has a plugin entry with no valid "name" — ` +
+          `refusing a silently empty or partial list`,
+      );
+    }
+    const name = p.name.trim();
+    // A name becomes an argument to `claude plugin install <name>@shipwright`.
+    // Reject anything that isn't a plain package identifier — whitespace,
+    // control chars, or shell metacharacters must never reach that call.
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name)) {
+      throw new Error(`marketplace manifest at ${source} has an invalid plugin name ${JSON.stringify(name)}`);
+    }
+    if (seen.has(name)) {
+      throw new Error(`marketplace manifest at ${source} lists duplicate plugin name "${name}"`);
+    }
+    seen.add(name);
+    names.push(name);
+  }
+  if (names.length === 0) {
+    throw new Error(`marketplace manifest at ${source} lists zero plugins — refusing to proceed`);
+  }
+  return names;
+}
+
+/**
+ * Resolve the plugin names through the precedence chain. Every source is an
+ * injected seam returning `{ text, source } | null` (or throwing, for the
+ * explicit override path).
+ * @param {{
+ *   readLocalManifest: () => { text: string, source: string } | null,
+ *   fetchRemoteManifest: () => Promise<{ text: string, source: string } | null>,
+ *   readOverrideManifest: () => { text: string, source: string } | null,
+ * }} seams
+ * @returns {Promise<{ names: string[], source: string }>}
+ */
+export async function resolveMarketplacePlugins(seams) {
+  const local = seams.readLocalManifest();
+  if (local) return { names: parseManifest(local.text, local.source), source: local.source };
+
+  const remote = await seams.fetchRemoteManifest();
+  if (remote) return { names: parseManifest(remote.text, remote.source), source: remote.source };
+
+  const override = seams.readOverrideManifest();
+  if (override) return { names: parseManifest(override.text, override.source), source: override.source };
+
+  throw new Error(
+    "could not resolve the marketplace plugin list from the local cache, GitHub, or " +
+      "SHIPWRIGHT_MARKETPLACE_MANIFEST — refusing to fall back to a hardcoded list",
+  );
+}
+
+/**
+ * Build a `{ name: version }` map from a parsed installed_plugins.json. Keys are
+ * `<name>@<marketplace>`; we key the result by the bare plugin name.
+ * @param {unknown} installedJson
+ * @returns {Record<string, string>}
+ */
+export function buildInstalledMap(installedJson) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  const plugins =
+    installedJson && typeof installedJson === "object"
+      ? /** @type {any} */ (installedJson).plugins
+      : null;
+  if (!plugins || typeof plugins !== "object") return out;
+  for (const [key, entries] of Object.entries(plugins)) {
+    const name = key.split("@")[0];
+    const first = Array.isArray(entries) ? entries[0] : null;
+    if (name && first && typeof first.version === "string") out[name] = first.version;
+  }
+  return out;
+}
+
+/**
+ * Install (first run) or update (already installed) every resolved plugin,
+ * sequentially, each exit code checked. One failure is reported and does not
+ * stop the rest. `pluginsChanged` is derived from a name→version snapshot taken
+ * before and after — it, and only it, drives the restart notice (AC5).
+ *
+ * @param {{
+ *   runClaude: (args: string[]) => { ok: boolean, code: number | null, stdout: string, stderr: string },
+ *   resolvePlugins: () => Promise<{ names: string[], source: string }>,
+ *   snapshotInstalled: () => Record<string, string>,
+ *   log?: (msg: string) => void,
+ * }} deps
+ */
+export async function ensurePlugins(deps) {
+  const log = deps.log ?? (() => {});
+
+  // 1. Marketplace: add (first run) → on "already exists", update (rerun). Every
+  //    exit code is checked: a failed add for ANY OTHER reason (network/auth) is
+  //    recorded, not silently ignored (we still try the resolver fallbacks, but
+  //    the caller must be able to see the marketplace step failed).
+  const add = deps.runClaude(["plugin", "marketplace", "add", "svenroth-ai/shipwright"]);
+  let marketplaceAction = "add";
+  let marketplaceOk = add.ok;
+  const alreadyExists = /already exist/i.test(`${add.stderr}${add.stdout}`);
+  if (!add.ok && alreadyExists) {
+    const upd = deps.runClaude(["plugin", "marketplace", "update", "shipwright"]);
+    marketplaceAction = "update";
+    marketplaceOk = upd.ok;
+    if (!upd.ok) log(`  marketplace update FAILED (exit ${upd.code})`);
+  } else if (!add.ok) {
+    log(`  marketplace add FAILED (exit ${add.code}) — will try the manifest fallbacks`);
+  }
+
+  // 2. Snapshot BEFORE (from the same cache the resolver reads).
+  const before = deps.snapshotInstalled();
+
+  // 3. Resolve the list — the local cache exists now that `add` ran.
+  const { names, source } = await deps.resolvePlugins();
+
+  // 4. Install-or-update each, checking every exit code.
+  /** @type {{name:string, action:string, ok:boolean, code:number|null}[]} */
+  const results = [];
+  for (const name of names) {
+    const action = before[name] != null ? "update" : "install";
+    const r = deps.runClaude(["plugin", action, `${name}@shipwright`]);
+    results.push({ name, action, ok: r.ok, code: r.code });
+    if (!r.ok) log(`  plugin ${action} FAILED: ${name}@shipwright (exit ${r.code})`);
+  }
+
+  // 5. Snapshot AFTER, derive the changed-set (order-independent — the maps come
+  //    from installed_plugins.json, whose key order is not a signal).
+  const after = deps.snapshotInstalled();
+  const pluginsChanged = !mapsEqual(before, after);
+  const failures = results.filter((r) => !r.ok);
+
+  return { names, source, marketplaceAction, marketplaceOk, results, before, after, pluginsChanged, failures };
+}
+
+/** Order-independent equality of two `{ name: version }` maps. */
+export function mapsEqual(a, b) {
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => a[k] === b[k]);
+}