diff --git a/plugins/claude-ops/.claude-plugin/plugin.json b/plugins/claude-ops/.claude-plugin/plugin.json index 603b48b13b8..022c1d28027 100644 --- a/plugins/claude-ops/.claude-plugin/plugin.json +++ b/plugins/claude-ops/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "claude-ops", - "version": "0.44.6", + "version": "0.45.0", "description": "Claude Code operations toolkit. Twelve skills: audit-skill-visibility (audit whether each installed skill is actually VISIBLE to the model, and diagnose why most of a fleet never gets used \u2014 a skill is invisible when its description is dropped by Claude Code's skill-listing context budget, which sheds descriptions lowest-score-first so an unused skill loses the keywords that would let it be matched, from skills genuinely not wanted, from skills the run cannot observe at all; computes whether the listing overflows from documented settings, and withholds every cold verdict the data cannot support rather than reporting absence of data as absence of use), inventory (read-only enumeration of the complete invocable surface \u2014 every built-in CLI command with aliases and hidden/gated status, every bundled skill, and every component of every installed plugin across all marketplaces; reads the shipped binary because upstream publishes no built-in command list, and carries an integrity verdict so a drifted build reports counts as floors rather than silently short totals), audit-install-state (read-only audit of the machine-scope ~/.claude installation directory and ~/.claude.json \u2014 full inventory split into an authored surface and rolled-up bulk trees, product-managed retention vs genuinely unmanaged state, filename-scheme resolution before any process-liveness check, and deliberate/mid-experiment detection; reports, never deletes), audit-performance (read-only slowness-diagnostic capture run at the moment the machine or a session feels slow: CLI version, retention-sweep health including the silent unparsable-settings pause, a timed census walk of the install tree as a sweep-cost proxy, active-session and plugin-fleet counts, a process census, and the fan-out layer, which covers a load-labelled no-op spawn baseline, every hook that will fire bucketed per-tool-call versus per-turn with its invocation shape, the configured statusline, subagent concurrency and spawn-depth ceilings against documented defaults, whether running sessions predate the settings file they are judged by, and orphan attribution by parent liveness rather than age, plus on Windows a kernel-object census (Token objects against uptime, paged pool) that names a host-level leak beneath all four suspects; read against a bundled known-performance-issues reference that also records the causes tested and cleared; separates the four documented suspects of accumulated state, version regression, component bloat, and per-spawn fan-out cost, and routes remediation out; reports, never mutates, and never executes a discovered hook or statusline command), audit-native-overlap (map native Claude Code surfaces \u2014 built-in CLI commands, bundled skills, plugin-backed built-ins, session-provided skills \u2014 against the current repo's plugin skills and agents, so a custom component never silently duplicates what Claude Code itself ships; bare invocation is a read-only overlap report carrying the extraction's integrity floors and a shared-listing-budget exposure section, verdicts are human-gated in a committed store rendered into a generated registry whose every row carries an observable recheck trigger, and only an explicit apply step bakes presence-gated native references into descriptions and Boundary sections), observability (read locally captured telemetry \u2014 OTEL store, collector, the per-session hook event log and hook-event JSONL, ccusage \u2014 with trend reports, a per-session report of what fired, what was blocked and the event timeline, and store pruning), known-issues (search known Claude product GitHub bugs, check service health, maintain a persistent tracked-issue registry), changelog (ingest Claude Code changelog entries and integrate them into the current repo), plugins (bring a machine's plugin fleet current on demand \u2014 marketplace refresh, effective-scope updates including in-repo project/local installs, new-plugin install per policy, scope-divergence detection and explicit convergence), morning-brief (read-only gh-based operator morning view \u2014 queue-label counts, merge-ready PRs, parked decisions with their RECOMMENDED lines, and loop-lane telemetry freshness), lanes (start/restart/stop/status loop lanes as named background Claude Code sessions seeded from canonical prompt files, with per-lane model/effort, a repo-pull + marketplace-refresh launch step, and a consume-restarts action \u2014 an OS-schedulable reader that relaunches stopped lanes whose telemetry carries a restart_request), and a re-runnable setup action that settles where the known-issues registry, the skill-usage log and the hook log root live, places the root's self-ignoring guard, and detects retired conventions. Plus an opt-in, default-off per-session hook event log (one JSON line per hook event on every event the generated registry marks observable, written to /sessions/.jsonl, with SessionEnd retention by session count or age and an optional detached pre-prune command), a family of eight advisory *-audit hooks (API errors, config changes, instruction loads, permission denials, pre-compaction, skill usage, tool failures, and unsurfaced hook failures \u2014 the last also warns the user via systemMessage, since a hook that fails to launch enforces nothing and Claude Code surfaces the failure to nobody) that emit the shared hook-telemetry envelope, and a reference sink that routes envelopes under the same root: per session when the envelope carries a session id, else into the shared hook-events.jsonl the observability skill reads.", "author": { "name": "Melodic Software", diff --git a/plugins/claude-ops/CHANGELOG.md b/plugins/claude-ops/CHANGELOG.md index 04f54a98da9..2951b8411f7 100644 --- a/plugins/claude-ops/CHANGELOG.md +++ b/plugins/claude-ops/CHANGELOG.md @@ -3,6 +3,33 @@ All notable changes to the `claude-ops` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.45.0] + +### Changed + +- **The `plugins` skill's `sync` and `audit` run Steps 1-5b through one `sync-run.sh` + invocation with a JSON digest, instead of the model driving each step by hand.** + A current-fleet run now costs 2 model turns where it cost 14. +- **`cache-content-check.sh` batches fleet-wide** instead of spawning per plugin: 400 + spawns fall to 17, and the authoring host's wall clock drops from roughly 100 s to + roughly 15 s. +- **Step 5b calls the checker once, not twice.** +- **A journal-creation failure now exits 2 before any mutation, instead of degrading.** + +### Fixed + +- **`--only-install` keeps first-pass update and projection failures in the + replacement digest.** Successful moves already survived through the move + ledger; a failed `claude plugin update` or a failed projection did not, so the + digest that supersedes an `ask`-policy stop could report a successful sync + while a plugin remained stale. +- **The batched cache-content join attaches a blob to every matching source + directory, not only the longest.** Nested marketplace sources such as + `plugins/alpha` and `plugins/alpha/nested` previously each received the blob + from their own `ls-tree`; longest-match-only dropped the nested subtree from + the ancestor's expected tree, so a healthy ancestor cache was reported + `stale-content` and a hole in that subtree was reported as a match. + ## [0.44.6] ### Changed diff --git a/plugins/claude-ops/skills/plugins/SKILL.md b/plugins/claude-ops/skills/plugins/SKILL.md index f7193f695fc..ef5e6349b07 100644 --- a/plugins/claude-ops/skills/plugins/SKILL.md +++ b/plugins/claude-ops/skills/plugins/SKILL.md @@ -74,6 +74,56 @@ arrive as a literal placeholder with no error to warn anyone. See Bare invocation (no arguments) → `sync` against the default marketplace. `help` or an unrecognized action → show this table. +## Running `sync` and `audit` + +Both actions execute Steps 1 through 5b as ONE bundled script call, then the model writes Step 6's +report from the JSON digest that call prints. The step sequence, and the reason behind every step, +stay in [context/sync.md](context/sync.md); the script is bound to that file. + +1. **Run it.** Substitute the marketplace target, the policy, and the flags into this command. The + journal root is written here because `${CLAUDE_PLUGIN_DATA}` resolves in skill content and + **not** in a `context/*.md` spoke, which is read raw: + + ```bash + "${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/sync-run.sh \ + [--marketplace | --all] \ + --journal-root "${CLAUDE_PLUGIN_DATA}/plugins-sync/runs" \ + --install-new [--allow-downgrade] + ``` + + `audit` is the same command with `--audit` instead of `--journal-root` (it writes to a scratch + directory it deletes) and never `--allow-downgrade`, which it ignores and says so. + + `` is the word from the **Configured value** line under "userConfig: `install_new`" + below — `all`, `none`, or `ask`, and `ask` when that line still shows the unset placeholder + token. Pass the WORD, never the token: a placeholder inside a command is a shell substitution + error, not a policy. Any other value is treated as `ask` and named back in the digest's + `install_new_invalid` so the report can flag it. + +2. **Read the digest.** One compact JSON object on stdout, also written to `/digest.json`. + It carries everything the Report needs, per marketplace, plus a `run_dir` that holds every + snapshot and the journal. + +3. **Resolve an `ask` install gap.** When a block has a non-empty `install_gap` and + `stopped_before_install: true`, run the batched multi-select from + [context/sync-install-enable.md](context/sync-install-enable.md), then re-enter for Steps 4 and 5 + against the same run: + + ```bash + "${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/sync-run.sh \ + --only-install "" --run-dir "" + ``` + + An empty id list is legal and means "install nothing, still complete Step 5". Report from the + digest that call prints; it supersedes the first one and reuses the same cache-content finding + rather than checking again. + +4. **Report.** Emit the Report section below. + +Load [context/sync.md](context/sync.md) when a digest carries errors, a non-empty gap, a catalog +regression, or a cache-content finding, and when the user asks why a step behaved the way it did. +A run with none of those has nothing in the file that changes the report. + ## Marketplace resolution No hardcoded marketplace name anywhere in this skill. Every action resolves its target the same way: @@ -106,9 +156,12 @@ The third form projects that same id list from a report already on disk rather t fleet, and is the form `sync`'s steps use: each step re-reads the full report anyway, and every selector is derivable from it. Same script, same projection, so the `\r` protection is unchanged. +`sync-run.sh` above is what calls these scripts during `sync` and `audit`; the contracts below are +what it and any other caller are bound to. + A second read-only script answers the question `fleet-state.sh` structurally cannot: whether the -files in a plugin's cache directory actually match the commit its install record claims. Run it as -Step 5b of `sync` and of `audit`: +files in a plugin's cache directory actually match the commit its install record claims. Step 5b of +`sync` and of `audit` calls it ONCE per marketplace: ```bash "${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/cache-content-check.sh --marketplace [--scope user|project|all] @@ -116,7 +169,9 @@ Step 5b of `sync` and of `audit`: ``` `--ids` emits the stale ids alone, one per line, CR-free, the same contract and for the same reason -as `fleet-state.sh --ids`. The script never writes anything and never runs `git fetch`; a commit +as `fleet-state.sh --ids`. Step 5b does not use it beside the JSON form: the ids are already in that +JSON, and a second call would repeat the run's most expensive read. It is the fallback for a JSON +that could not be produced. The script never writes anything and never runs `git fetch`; a commit that is not in the local marketplace clone is reported as `sha-not-local`, not fetched. See [context/sync.md](context/sync.md) Step 5b, and [context/scope-semantics.md](context/scope-semantics.md) for the mechanism that makes a cache @@ -187,9 +242,9 @@ action. Marketplace: — (autoUpdate: ) (repeat this line per marketplace in `all` mode — Steps 2–5 run once per marketplace) In-repo: project/local install(s) updated in - (N counts FORWARD moves only; an in-repo record moved backward, only possible under - --allow-downgrade or for an id whose catalog version could not be read, renders under - `Downgraded:` with its scope and is not counted here) + (N is `in_repo.updated | length`; it counts FORWARD moves only. An in-repo record moved + backward, only possible under --allow-downgrade or for an id whose catalog version could + not be read, renders under `Downgraded:` with its scope and is not counted here) | 0 — has no project/local installs | skipped — no project context resolved from Updated: plugin(s) — @: → (only when N > 0) @@ -231,8 +286,16 @@ than a lookup: itself the primary value path, so a run in which it did nothing has to say so in the default output, not only when it succeeds. The three variants are not cosmetic: `skipped` and `0` answer genuinely different questions ("there was no *here* to update" versus "here has nothing installed"), and -collapsing them is the whole defect this row exists to close. `fleet-state.sh`'s top-level -`project_root` is what distinguishes them. See [context/sync.md](context/sync.md) Step 2. +collapsing them is the whole defect this row exists to close. Two digest fields pick the variant, +in this order: + +- `project_root` is `null` → `skipped`, naming the cwd. +- `in_repo_records == 0` → `0 — has no project/local installs`. +- `in_repo_records > 0` → the counted variant, with N taken from `in_repo.updated | length`. + +`in_repo_records` counts the records belonging to this root whether or not any of them moved, so a +root that HAS project/local installs and updated none of them reads `0` against a named root rather +than claiming the root has nothing installed. See [context/sync.md](context/sync.md) Step 2. Add a self-update row when Step 3's sweep updated `claude-ops` itself: @@ -295,6 +358,9 @@ Stale project records: record(s) across

path(s) not present on this mach verdict that the directory is gone for good.) ``` +`K` is `stale_project_records.total` and `P` is the length of `stale_project_records.by_path`; each +`by_path` entry is the `{path, count}` one row renders. + A project-scope enable gap is a row `sync` deliberately does not fix. Step 5 enables automatically only where the write is not team-shared state. Give each one its runnable command rather than a count, so acting on it is a copy, not a reconstruction: @@ -349,6 +415,12 @@ Cache content: install(s) whose cache files disagree with their recorded git `claude plugin update @`, which recreates it from the clone. ``` +`N` is `cache_content.stale_content`, and one row comes from each `cache_content.stale[]` entry: +`id`, `version`, and `files_differ`, which sums every direction of disagreement — bytes that +changed, files the tree has and the cache lacks, and files the cache holds and the tree does not. +`files_differ` reads `null` when the digest fell back to the checker's `--ids` form, which knows the +ids and no per-file detail; report the ids alone then. + **The check never repairs.** It does not delete a cache directory, does not re-run an update, and does not `git fetch` a commit the marketplace clone lacks. A commit that is not local is reported as `sha-not-local` and left alone: fetching is a network mutation this audit does not perform, and it diff --git a/plugins/claude-ops/skills/plugins/context/sync.md b/plugins/claude-ops/skills/plugins/context/sync.md index 90c5a844ca9..46bb3c081c8 100644 --- a/plugins/claude-ops/skills/plugins/context/sync.md +++ b/plugins/claude-ops/skills/plugins/context/sync.md @@ -2,6 +2,7 @@ ## Contents +- [Execution — one script runs Steps 1 through 5b](#execution--one-script-runs-steps-1-through-5b) - [Concurrency](#concurrency) - [Downgrade guard](#downgrade-guard) - [Version capture for the report](#version-capture-for-the-report) @@ -20,6 +21,44 @@ is CLI-mediated — never edit `installed_plugins.json`, `known_marketplaces.jso `.claude/settings*.json` directly. `audit` runs this same sequence with every mutating call replaced by a prediction (see SKILL.md's "Action: audit"). +## Execution — one script runs Steps 1 through 5b + +`scripts/sync-run.sh` is this algorithm's executable form. One invocation runs Steps 1 through 5b +for every target marketplace and prints ONE JSON digest; the model reads that digest and writes +Step 6's report from it. This file stays the normative statement of what each step does and why — +the script is bound to it, so a rule changed here is a rule changed in the script and its tests. + +```bash +sync-run.sh [--marketplace | --all] --journal-root

\ + [--install-new all|none|ask] [--allow-downgrade] +sync-run.sh [--marketplace | --all] --audit [--install-new all|none|ask] +sync-run.sh --only-install --run-dir [--marketplace | --all] +``` + +Why a script rather than a step-per-turn transcript: every guarantee below is a property of the +ORDER and the STATUS CHECKS between calls, not of a human-readable narration between them. Running +them in one process keeps the re-read boundary, the `rc` checks, and the journal exactly where this +file puts them, and it removes the retyping error that a per-step transcript invites. + +What the model still owns, because the script cannot: + +- **The `install_new` policy.** `${user_config.install_new}` substitutes only when Claude Code + renders SKILL.md; a `context/*.md` spoke is read raw. SKILL.md's "Configured value" line is the + rendered value, and the model passes it as `--install-new`. On `ask` with a non-empty install gap + the script reports the gap and STOPS before Step 4, because only the model can run the batched + prompt; it then re-enters with `--only-install --run-dir `, which + performs Step 4 and Step 5 against the same run journal and re-emits the digest. +- **The journal root.** `${CLAUDE_PLUGIN_DATA}` substitutes in SKILL.md and not here, so SKILL.md + passes the substituted path as `--journal-root`. +- **Step 6.** The report is prose over the digest. + +The digest carries, per marketplace: the refresh result, `project_root`, the in-repo and user-scope +sweep outcomes with each pair's direction, withheld downgrades, the install and enable gaps, what +was installed and enabled, the project-scope enable rows, the normalizer result, the cache-content +counts and stale ids, the catalog regression interval, the three-snapshot divergence split, and +whether the sweep updated this plugin itself. Ids and counts only — the per-file cache detail and +every snapshot stay in the run directory, which the digest names. + ## Concurrency The `claude plugin` CLI is the serialization point — there is no separate lock this skill manages. @@ -119,21 +158,16 @@ removing the marketplace. It stays in the data directory anyway, because that is per-plugin persistent location. See [gotchas.md](gotchas.md), "`marketplace remove` is a bulk uninstall, not a declaration removal, and it deletes this skill's own run journal". -At run start, take `journal_root` from SKILL.md's "State inspection" section (the value substitutes -there and **not** here — a `context/*.md` spoke is read raw, so a `${CLAUDE_PLUGIN_DATA}` written -here would resolve to nothing) and create one directory for this run: - -```bash -mkdir -p "$journal_root" -run_dir=$(mktemp -d "$journal_root/$(date -u +%Y%m%dT%H%M%SZ).XXXXXX") -``` +At run start the script creates one directory for this run under the `--journal-root` SKILL.md +passes (the `${CLAUDE_PLUGIN_DATA}` value substitutes there and **not** here — a `context/*.md` +spoke is read raw, so a token written here would resolve to nothing). -`mktemp -d`, not a bare `mkdir -p` on the timestamp alone: the stamp has one-second resolution, so -two `sync` sessions started within the same second compute the *same* path and `mkdir -p` succeeds -for both — snapshots overwrite each other and the two runs' `journal.log` lines interleave, which -is exactly the reconstruction failure this journal exists to prevent. `mktemp -d` creates the -directory atomically or fails, so each run gets its own. The suffix means a run directory is -`.XXXXXX`, not the bare timestamp; sort by name to order runs. +It is `mktemp -d` on a UTC timestamp, not a bare `mkdir -p` on the timestamp alone: the stamp has +one-second resolution, so two `sync` sessions started within the same second compute the *same* path +and `mkdir -p` succeeds for both — snapshots overwrite each other and the two runs' `journal.log` +lines interleave, which is exactly the reconstruction failure this journal exists to prevent. +`mktemp -d` creates the directory atomically or fails, so each run gets its own. The suffix means a +run directory is `.XXXXXX`, not the bare timestamp; sort by name to order runs. Then, for the rest of the run: @@ -166,25 +200,11 @@ Then, for the rest of the run: `audit` no refresh runs, so a regression in that same first interval is the checkout changing under the run as well, never this run's doing. The interval names when; the action names what it means. This diff is REPORT-ONLY and its output never becomes an id list handed to the CLI, so - the hand-written-`jq` prohibition that governs `--ids` does not apply to it: - - ```bash - jq -r --slurpfile a "$run_dir/pre-refresh.$mp.json" --slurpfile b "$run_dir/pre.$mp.json" -n ' - def triple: - if type == "string" then - ((capture("^v?(?[0-9]+)[.](?[0-9]+)[.](?[0-9]+)") // null) - | if . == null then null else [.x, .y, .z] | map(tonumber) end) - else null end; - ($a[0].catalog_versions // {}) as $before | ($b[0].catalog_versions // {}) as $after - | $before | to_entries[] - | select((.value | triple) != null and ($after[.key] | triple) != null - and ($after[.key] | triple) < (.value | triple)) - | "\(.key) \(.value) \($after[.key])"' - ``` + the hand-written-`jq` prohibition that governs `--ids` does not apply to it. - Run it per consecutive pair and stop at the first pair that prints anything. Emit SKILL.md's - `Catalog regression:` line with the interval and the ids; report nothing when every pair is - silent. + The script runs the triple compare per consecutive pair, stops at the first pair that finds a + backward move, and reports that interval and its rows in the digest's `catalog_regression`. + Emit SKILL.md's `Catalog regression:` line from it; report nothing when the field is null. - **Append every mutating CLI call and its output** to `$run_dir/journal.log` as it runs, so the `` values that only the CLI reports survive the step that produced them: @@ -218,27 +238,19 @@ action table says `audit` mutates nothing, and a run that leaves directories beh data dir does not match that line even though the data dir is not fleet state. But `audit` runs this same algorithm, and it writes reports: Step 1 saves its pre-refresh snapshot, and Steps 2–5 project their id lists with `--from` against a saved report. So it does need somewhere to put them, and that -somewhere has to exist before Step 1. It gets one outside the journal root and deletes it: - -```bash -run_dir=$(mktemp -d "${TMPDIR:-${TEMP:-.}}/plugins-audit.XXXXXX") -# ... run the algorithm ... -rm -rf "$run_dir" -``` - -Note `${TMPDIR:-${TEMP:-.}}` and **not** a hardcoded `/tmp`: on Windows that path is an MSYS mount -alias this repo's guardrails reject. Remove the directory when the run ends, including on the error -paths — an audit that leaks one scratch directory per invocation is its own drift. +somewhere has to exist before Step 1. `--audit` makes one under `${TMPDIR:-${TEMP:-.}}` and removes +it on exit, including on the error paths — an audit that leaks one scratch directory per invocation +is its own drift. That expansion, and **not** a hardcoded POSIX temp literal: on Windows the literal +is an MSYS mount alias a native consumer resolves against the current drive root. So `audit` and `sync` execute one algorithm, differing only in where the reports land and in issuing no mutating call. `audit` has no ` → ` pairs to lose and nothing durable the journal would protect, which is why its copy is disposable rather than kept. -The journal is best-effort and never fails the sweep: if `mkdir -p` or `mktemp -d` fails, say so in -the report and fall back to holding the values in context, which is the weaker guarantee this -section exists to replace. Without a `run_dir` the `--from` projections have no saved report to read, -so those steps fall back to the live `--marketplace "$mp" --ids ` form — the second process -`--from` exists to avoid, correct but costlier. +A run directory that cannot be created is a run that cannot journal, so the script exits 2 and names +the root rather than sweeping unjournaled: without it the `--from` projections have no saved report, +the ` → ` pairs have nowhere to survive to Step 6, and the report the run owes would be a +reconstruction from memory of the run. ## Marketplace scoping — Steps 2–5 are the per-marketplace loop body @@ -249,16 +261,9 @@ exactly **one** of them — the resolved default — while emitting a report tha boundary. That is a silent partial sweep: the plugins of every other marketplace are neither updated nor reported as skipped. -Get the names from `fleet-state.sh --marketplaces`, never from a hand-written `jq` over +`--all` takes the names from `fleet-state.sh --marketplaces`, never from a hand-written `jq` over `known_marketplaces.json` — enumerating names has exactly the trailing-`\r` hazard that enumerating -ids does, and for the same reason: - -```bash -while IFS= read -r mp; do - [[ -n "$mp" ]] || continue - # Steps 2–5 for "$mp" -done < <("${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/fleet-state.sh --marketplaces) -``` +ids does, and for the same reason. The bare (no `--marketplace`) form is not a fleet-wide form; it resolves the default marketplace and scopes to it. Nor can the sweep be widened by combining flags — the script refuses that composition @@ -282,55 +287,27 @@ reported inline and never aborts the loop for the rest. Steps 2–5 all do the same three things: take the live re-read the concurrency rule already requires and **redirect it to the run journal**, project the step's selector out of that file with `--from`, -and loop the result. Written out once, with Step 3's selector as the example: - -```bash -"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/fleet-state.sh --marketplace "$mp" \ - >"$run_dir/mid.$mp.json" - -"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/fleet-state.sh \ - --ids update-candidates-user --from "$run_dir/mid.$mp.json" >"$run_dir/ids.mid.$mp.txt" -rc=$? -``` - -**Check that `rc` before looping — an empty projection is ambiguous and the exit status is the only -thing that disambiguates it.** Every `--from` rejection (a missing or malformed report, an `--all` -envelope, a report lacking the field the selector reads, a `--marketplace` disagreeing with the -report's own name) exits 2 with **empty stdout**, deliberately, so a failure can never be handed to -`claude plugin update` as an id. That makes the two outcomes identical to a +and loop the result. `--from` replaces only the second process a step used to launch to project its +ids; it never replaces the re-read. + +**The projection's exit status is checked before the loop — an empty projection is ambiguous and the +status is the only thing that disambiguates it.** Every `--from` rejection (a missing or malformed +report, an `--all` envelope, a report lacking the field the selector reads, a `--marketplace` +disagreeing with the report's own name) exits 2 with **empty stdout**, deliberately, so a failure can +never be handed to `claude plugin update` as an id. That makes the two outcomes identical to a `while read … done < <(fleet-state.sh …)` consumer, which never sees the exit status at all: zero lines read, step reports nothing to do. So: - **exit 0, empty output** — genuinely nothing to do for this selector. Proceed. -- **exit 2, empty output** — the projection failed. Report it inline under "Action needed" with the - script's own error text and treat the step as not run; never as "nothing to do". +- **exit 2, empty output** — the projection failed. It reaches the digest's per-marketplace + `errors[]` and the report's "Action needed" with the script's own error text, and the step counts + as not run; never as "nothing to do". -Project to a file and check `$?` first, then loop the file, rather than reading from a process -substitution whose status the loop discards. The intermediate lands in `$run_dir` alongside the -reports, so it is covered by the same cleanup and no third temp location is invented: +Each projection lands in a file inside the run directory alongside the reports, rather than in a +process substitution whose status a loop discards, so the status is available where the branch is. -```bash -if ((rc != 0)); then - # The step did NOT run. Report it inline under "Action needed" with the - # script's own error text; do not fall through to the loop. -else - while IFS= read -r id; do - [[ -n "$id" ]] || continue - # the step's mutating call for "$id" - done <"$run_dir/ids.mid.$mp.txt" -fi -``` - -The branch is the point. A snippet that assigns `rc` and then loops unconditionally has done nothing -the bare process substitution did not, which is the same defect as journaling a mutating call through -`tee` without capturing `PIPESTATUS[0]`: the status is available and discarded. - -Pass `--marketplace "$mp"` alongside `--from` when you want the script to prove the saved report is -the one you think it is; with `--from` that flag is a consistency check (mismatch is exit 2), never -a second read. - -Steps 2 through 5 each name their own report file and selector below; the redirect, the `rc` check, -and the loop-from-a-file shape are this section's and are not restated at each step. +Steps 2 through 5 each name their own report file and selector below; the redirect, the status +check, and the loop-from-a-file shape are this section's and are not restated at each step. ## Step 1 — Marketplace refresh @@ -339,19 +316,12 @@ argument is `all`), save that marketplace's pre-refresh snapshot and then refres **The snapshot is a read, and BOTH actions take it.** It is the earliest link in the catalog regression check's snapshot chain, and an action that skips it starts that check at `pre` and loses -its first interval: +its first interval. It is saved as `pre-refresh..json`. When no marketplace argument was given, +that same read is what resolves the default marketplace's name, so resolution costs no extra process. -```bash -"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/fleet-state.sh --marketplace "$mp" \ - >"$run_dir/pre-refresh.$mp.json" -``` - -**The refresh is the mutation, and it is `sync` only.** It is the one call this step replaces with -`would run: claude plugin marketplace update ` in an `audit` report: - -```bash -claude plugin marketplace update "$mp" -``` +**The refresh is the mutation, and it is `sync` only.** `claude plugin marketplace update "$mp"` is +the one call this step replaces with `would run: claude plugin marketplace update ` in an +`audit` report. The update call attempts to re-fetch from the marketplace's registered source; this skill never re-clones or performs cache surgery by hand. It does not reliably self-heal: the refresh is known to fail against an @@ -381,8 +351,9 @@ In `all` mode, loop this per marketplace name (rather than the bulk no-argument marketplace's failure is attributable and reported inline without aborting the sweep for the rest. **On a non-zero exit — every mode, including single/default.** Not fatal, and never silently -absorbed: report the marketplace and the CLI's own error text inline under "Action needed" and -continue to Step 2. +absorbed: the marketplace and the CLI's own error text reach that marketplace's `errors[]` and the +report's "Action needed", the block's `install_enable_deferred` is set, and the run continues to +Step 2. Which later steps a stale catalog compromises, and how each one degrades: @@ -444,6 +415,11 @@ report. They are categorically different answers and the user cannot tell them a which is an honest zero rather than an absent step. - **`project_root` is a path and records carry `currentProject: true`** — the success path below. +`sync-run.sh` carries this branch into its digest as `project_root` plus `in_repo_records`, the +count of records with `currentProject: true`. A report written over the digest branches on those +two fields; the record-level read below is the same question asked of the `fleet-state.sh` report +directly. + Reading `project_root` costs nothing extra: this step already calls `fleet-state.sh` above, and the field is in the JSON it returned. Do not try to recover the distinction from `--ids update-candidates-project` alone: that selector emits nothing in both of the first two cases, @@ -451,13 +427,9 @@ so a step keyed on it no-ops invisibly. And do not infer it from `currentProject tri-state whose `null` covers user-scope records, records with no `projectPath`, *and* the no-project-context case all at once. -Then look at `installed[]` entries with `currentProject: true` and run an update for **every one of -them the downgrade guard does not withhold**: - -```bash -claude plugin update -s project # for a currentProject:true entry with scope "project" -claude plugin update -s local # for a currentProject:true entry with scope "local" -``` +Then look at `installed[]` entries with `currentProject: true` and run +`claude plugin update -s ` for **every one of them the downgrade guard +does not withhold**. `fleet-state.sh --ids update-candidates-project` emits exactly those records. Use it rather than a hand-written `jq` over `installed[]` (see Step 3 for why the hand-written form breaks on Windows). @@ -465,33 +437,14 @@ hand-written `jq` over `installed[]` (see Step 3 for why the hand-written form b Project it with `--from` off the report this step just saved rather than running a second live process: that process would re-parse `installed_plugins.json`, re-walk the catalog manifests, and re-run `realpath` to recompute a block already on disk. Same script, same projection, so the -`\r` protection is identical. Each line is `\t`, so the `-s` flag comes off the same line -as the id it belongs to: +`\r` protection is identical. -Per the projection section above, this step's own re-read is redirected to `pre.$mp.json` — that -file is what the branch on `project_root` above reads, and what `--from` projects — and the -projection's exit status is checked before the loop: +Per the projection section above, this step's own re-read is redirected to `pre..json` — that +file is what the branch on `project_root` above reads, and what `--from update-candidates-project` +projects — and the projection's exit status is checked before the loop. Each projected line is +`\t`, so the `-s` flag comes off the same line as the id it belongs to. -```bash -"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/fleet-state.sh --marketplace "$mp" \ - >"$run_dir/pre.$mp.json" -project_root=$(jq -r '.project_root // "null"' "$run_dir/pre.$mp.json") - -"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/fleet-state.sh \ - --ids update-candidates-project --from "$run_dir/pre.$mp.json" >"$run_dir/ids.pre.$mp.txt" -rc=$? # exit 2 with empty output is a FAILED projection, not "nothing in-repo" - -if ((rc != 0)); then - # Report the projection failure under "Action needed"; the step did not run. -else - while IFS=$'\t' read -r id scope; do - [[ -n "$id" ]] || continue - claude plugin update "$id" -s "$scope" - done <"$run_dir/ids.pre.$mp.txt" -fi -``` - -The `rc` check matters more here than anywhere else: this is the primary value path, and an +The status check matters more here than anywhere else: this is the primary value path, and an unchecked failed projection is indistinguishable from the honest "a project resolved and it has no in-repo installs" zero the step is required to report. @@ -556,11 +509,7 @@ an id current, and what each does: Never present an `audit` prediction of zero as "the fleet is current" — it means "nothing is behind the catalog as it stands on disk", which is a different claim. -Update the catalog plugins installed at `user` scope: - -```bash -claude plugin update -s user -``` +Update the catalog plugins installed at `user` scope with `claude plugin update -s user`. One call per plugin — `claude plugin update` takes a single `` argument, there is no bulk "update everything" flag. Loop it; a single plugin's update failure is reported inline (under @@ -569,38 +518,19 @@ One call per plugin — `claude plugin update` takes a single `` argumen Take the ids from `fleet-state.sh --ids`, never from a hand-written `jq` over its JSON, and use the **`update-candidates-user`** selector rather than `installed-user`. This step makes its own live re-read — the one the concurrency rule requires before a mutating step — redirects it to -`mid.$mp.json`, and projects from that file, for the reason Step 2 gives: - -```bash -"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/fleet-state.sh --marketplace "$mp" \ - >"$run_dir/mid.$mp.json" - -"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/fleet-state.sh \ - --ids update-candidates-user --from "$run_dir/mid.$mp.json" >"$run_dir/ids.mid.$mp.txt" -rc=$? # exit 2 with empty output is a FAILED projection, not "fleet already current" - -"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/fleet-state.sh \ - --ids downgrade-candidates --from "$run_dir/mid.$mp.json" >"$run_dir/downgrades.$mp.txt" -dg_rc=$? # same rule: exit 2 is a failed projection, not "no downgrades" - -if ((rc != 0)); then - # Report the projection failure under "Action needed"; the sweep did not run. -else - while IFS= read -r id; do - [[ -n "$id" ]] || continue - claude plugin update "$id" -s user - done <"$run_dir/ids.mid.$mp.txt" -fi -``` +`mid..json`, and projects two selectors from that file, for the reason Step 2 gives: +`update-candidates-user` into `ids.mid..txt` and `downgrade-candidates` into +`downgrades..txt`. Reading an unchecked empty projection as "already current" is the silently-skipped-update failure -this step exists to prevent, so check `rc` per the projection section before concluding the sweep -had nothing to do. The same check governs `dg_rc`: an unchecked failed downgrade projection reads -as "no downgrades", which is the guard reporting the all-clear it never established. +this step exists to prevent, so the sweep projection's status is checked per the projection section +before concluding the sweep had nothing to do. The same check governs the downgrade projection: an +unchecked failure there reads as "no downgrades", which is the guard reporting an all-clear it never +established. ### The withheld set -`downgrades.$mp.txt` carries one `\t\t\t` line per proven downgrade, +`downgrades..txt` carries one `\t\t\t` line per proven downgrade, across user scope and this repo's in-repo records both, so it covers what Step 2's selector withheld as well as Step 3's. What happens to it is the operator's call, not this step's: @@ -608,19 +538,9 @@ as well as Step 3's. What happens to it is the operator's call, not this step's: both versions and the likely cause, per SKILL.md's `downgrade withheld:` row. - **`--allow-downgrade` WAS given.** Loop them too, taking `-s ` from field 2 the way Step 2 takes it off its own line, journaled through the same `tee` plus `PIPESTATUS[0]` shape as every - other mutating call: - - ```bash - while IFS=$'\t' read -r id scope installed catalog; do - [[ -n "$id" ]] || continue - { echo "\$ claude plugin update $id -s $scope # downgrade $installed -> $catalog" - claude plugin update "$id" -s "$scope" 2>&1; } | tee -a "$run_dir/journal.log" - rc=${PIPESTATUS[0]} - done <"$run_dir/downgrades.$mp.txt" - ``` - - Their outcomes render under `Downgraded:`, never under `Updated:`, whatever the CLI's own line - calls them. + other mutating call. Their outcomes render under `Downgraded:`, never under `Updated:`, whatever + the CLI's own line calls them — the digest carries them in `downgraded`, which is a separate array + from `user_sweep.updated` for exactly that reason. ### Why the pre-filter, and why it can only ever be a candidate list @@ -663,16 +583,11 @@ and on Windows a hand-written ## Steps 4 and 5 — install and enable -**Take a fresh live re-read first, and gate the spoke on THAT report — never on Step 1's.** Step 4 -is a mutating step, so the concurrency rule already requires its own re-read; make it here, before -deciding whether to load the spoke: +**Take a fresh live re-read first, and gate on THAT report — never on Step 1's.** Step 4 is a +mutating step, so the concurrency rule already requires its own re-read; it is taken here, before +either step decides whether it has anything to do, and saved as `pre-install..json`. -```bash -"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/fleet-state.sh --marketplace "$mp" \ - >"$run_dir/pre-install.$mp.json" -``` - -**Read [sync-install-enable.md](sync-install-enable.md) only when `pre-install.$mp.json` has a +**Read [sync-install-enable.md](sync-install-enable.md) only when `pre-install..json` has a non-empty `missing_from_user_install` or a non-empty `missing_from_enabled`, or when Step 1's refresh failed for this marketplace.** Both arrays are empty on an already-current fleet, which is the common case, and then both steps are no-ops with nothing to load. @@ -686,8 +601,15 @@ disclosure is kept; only the report it keys on moves. Step 4 reuses this file ra again, so the honest gate costs nothing. **Step 5 still takes its own re-read.** Step 4 mutates in between — it installs, and it normalizes -the user-scope `enabledPlugins` map — so `pre-install.$mp.json` is stale by the time Step 5 runs and -cannot stand in for `pre-enable.$mp.json`. Do not collapse the two. +the user-scope `enabledPlugins` map — so `pre-install..json` is stale by the time Step 5 runs and +cannot stand in for `pre-enable..json`. The two are never collapsed. + +**Step 4 stops for the `ask` policy.** When `install_new` renders as `ask` and the install gap is +non-empty, the script reports the gap and issues no install: the batched prompt belongs to the +model, which runs it and re-enters with `--only-install ` against the same run +directory. The digest says so in `stopped_before_install`, so a gap left unresolved is a reported +state rather than a silent skip. Under `all` the gap is installed; under `none` it is reported and +Step 5 still runs. - **Step 4 — install new catalog plugins.** Installs the `missing_from_user_install` ids at `user` scope per the configured `install_new` policy, then normalizes the user-scope `enabledPlugins` @@ -705,24 +627,20 @@ Read-only, runs after Step 5's enables and before the report, and is the same ca every earlier step reports success, so a check that only ran when something else looked wrong would never fire on the condition it exists to catch. -```bash -"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/cache-content-check.sh --marketplace "$mp" \ - >"$run_dir/cache-content.$mp.json" -``` +**One call per marketplace.** `cache-content-check.sh --marketplace "$mp"` writes its JSON to +`cache-content..json`, and the stale ids come out of that same JSON, CR-stripped in the shell +the way every id list in this algorithm is. A second call for the id list would recompute a +fleet-wide byte comparison the first call already did, which is the most expensive read in the run. In `sync` that redirect lands in the run journal beside the `fleet-state.sh` snapshots, so Step 6 reads the finding rather than remembering it. In `audit` it lands in the throwaway scratch directory -that run deletes, the same way `audit` handles every other report it writes. +that run deletes, the same way `audit` handles every other report it writes. The `--only-install` +re-entry reuses the report already in the run directory rather than checking again. -Read the ids to act on with `--ids` rather than a hand-written `jq` extraction over the JSON, for -the reason [gotchas.md](gotchas.md) gives: on Windows a `jq -r … | while read` appends a `\r` to -every id but the last. - -```bash -while IFS=$'\t' read -r id; do - echo "cache content disagrees with recorded sha: $id" -done < <("${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/cache-content-check.sh --marketplace "$mp" --ids) -``` +The extraction is CR-safe by construction, for the reason [gotchas.md](gotchas.md) gives: on Windows +a `jq -r … | while read` appends a `\r` to every id but the last, so the ids are captured and +stripped in the shell instead of piped. The checker's own `--ids` form is the fallback for a JSON +that could not be produced, never a second pass beside a JSON that was. **Neither action repairs what this finds, and `sync` is no exception.** The remediation is a directory removal under Claude Code's own plugin cache, which is outside the boundary the rest of @@ -740,10 +658,11 @@ rather than leading with the match count. ## Step 6 — Report Emit the report per SKILL.md's "Report" section, filling each updated plugin's ` → ` from -the sources the "Version capture for the report" section above fixes, read back out of the run -journal rather than out of memory of the run. +the sources the "Version capture for the report" section above fixes. The digest carries them, +resolved from the run journal rather than from memory of the run, and the run directory it names +holds every snapshot behind them. -**Classify every ` -> ` pair by direction before printing it.** Apply the same triple +**Every ` -> ` pair reaches the report already classified by direction.** Apply the same triple compare the guard uses: a pair whose new version is higher, or whose direction the compare cannot read, goes under `Updated:`, with an unreadable one flagged `(direction unknown)`; a pair whose new version is lower goes under `Downgraded:`. A pair whose two versions differ as strings but whose @@ -751,7 +670,9 @@ triples tie, `1.2.3` to `1.2.3-beta`, goes under `Updated:` flagged `(direction because the compare cannot rank suffixes. This classification is what makes a backward move unprintable as `Updated:` for the ids that still reach the CLI on the guard's fail-open path, the ones whose catalog version was null or unparsable and so could never be proven a downgrade in -advance. The guard withholds what it can prove; this step catches what only the outcome reveals. +advance. The guard withholds what it can prove; this classification catches what only the outcome +reveals. In the digest that is the split between each block's `updated` arrays, whose rows carry +`direction`, and its `downgraded` array. The same classification governs the `In-repo:` count: it counts forward moves only, and an in-repo record that moved backward renders under `Downgraded:` with its scope instead of being counted there. diff --git a/plugins/claude-ops/skills/plugins/evals/evals.json b/plugins/claude-ops/skills/plugins/evals/evals.json index 160f705ef5b..8f58e13818c 100644 --- a/plugins/claude-ops/skills/plugins/evals/evals.json +++ b/plugins/claude-ops/skills/plugins/evals/evals.json @@ -5,11 +5,11 @@ "id": 1, "name": "bare-invocation-routes-to-sync", "prompt": "/claude-ops:plugins", - "expected_output": "Bare invocation (no action argument) routes to the default action, sync, against the dynamically-resolved default marketplace. The response calls fleet-state.sh, runs the sync algorithm (marketplace refresh, in-repo update when applicable, user-scope sweep, install-new per policy, user-scope enabledPlugins key-order normalize after any install, enabledPlugins completeness), and ends with a terse fixed-section report plus reload guidance.", + "expected_output": "Bare invocation (no action argument) routes to the default action, sync, against the dynamically-resolved default marketplace. The response runs the sync algorithm through sync-run.sh (marketplace refresh, in-repo update when applicable, user-scope sweep, install-new per policy, user-scope enabledPlugins key-order normalize after any install, enabledPlugins completeness, cache content check), reads the JSON digest it prints, and ends with a terse fixed-section report plus reload guidance.", "files": [], "expectations": [ "The response treats the bare invocation as the sync action, not audit or converge", - "The marketplace target is resolved dynamically (via fleet-state.sh's CLAUDE_PLUGIN_ROOT join) rather than a hardcoded marketplace name", + "The marketplace target is resolved dynamically (via fleet-state.sh's CLAUDE_PLUGIN_ROOT join, reached through sync-run.sh) rather than a hardcoded marketplace name", "The response ends with a terse fixed-section report and bare `/reload-plugins` guidance — `--force` is only suggested if an updated/installed component ships an MCP server whose tools aren't deferred, never as a blanket default" ] }, @@ -21,7 +21,7 @@ "files": [], "expectations": [ "The response issues zero `claude plugin install|update|uninstall` or `claude plugin marketplace update` invocations", - "The response still calls the read-only fleet-state.sh script to compute state", + "The response still computes state from the read-only fleet-state.sh reads, which sync-run.sh --audit takes", "The response still takes Step 1's pre-refresh fleet-state.sh snapshot before declining the refresh: it does not treat the whole of Step 1 as skipped, and the catalog-regression check still has its pre-refresh to pre interval available", "The response frames its output as a prediction of what `sync` (and, where relevant, `converge`) would do, not as work already performed", "If the response mentions enabledPlugins key order, it uses normalize-enabled-plugins.sh --check (or equivalent prediction) and never writes ~/.claude/settings.json or a committed project settings file" diff --git a/plugins/claude-ops/skills/plugins/scripts/cache-content-check.sh b/plugins/claude-ops/skills/plugins/scripts/cache-content-check.sh index 44f2c1f7e8d..6e095822262 100755 --- a/plugins/claude-ops/skills/plugins/scripts/cache-content-check.sh +++ b/plugins/claude-ops/skills/plugins/scripts/cache-content-check.sh @@ -23,18 +23,35 @@ # a test of the wrong thing. Six plugins were found in that state on one # machine, twelve stale files in the worst case. # -# How the compare works, and why it is a fixed number of git processes per -# install rather than one per file. For each install record this script resolves -# the marketplace's `installLocation` (a git clone) and the plugin's `source` -# directory, then: -# 1. `git ls-tree -r -z -- ` — every blob id the commit says the -# plugin's files should have; -# 2. one `git hash-object --stdin-paths` over every regular file in the cache -# directory — the blob id each file on disk actually has. -# Set difference on the relative paths yields files present at the sha but +# How the compare works, and why the process count is a property of the +# MARKETPLACE rather than of the number of installs in it. Every external call +# is batched fleet-wide: a marketplace with 77 installs costs the same handful +# of processes as one with 3. Each process creation on Windows Git Bash is a +# fork() emulation plus a CreateProcess, so a per-install call is the only cost +# that matters here — the comparison itself is shell-local set arithmetic. +# 1. one `jq` over installed_plugins.json — every install record, every +# marketplace, read once; +# 2. one `git cat-file --batch-check` over every DISTINCT recorded sha — a +# sha the batch reports `missing` is `sha-not-local`; +# 3. per distinct sha, one `git show :.claude-plugin/marketplace.json` +# plus one `jq` — the plugin→source-directory map AT THAT COMMIT; +# 4. per distinct sha, ONE `git ls-tree -r -z -- ` — every blob id the commit says those plugins' files should +# have. A multi-pathspec ls-tree reports a pathspec that matched nothing +# by simply not emitting it, so the per-install "matched nothing" signal +# is recovered in the join: an install whose source directory contributed +# zero blobs is `no-source-at-sha`, never `match` and never +# `stale-content`; +# 5. ONE `find` over every install root (`-print0`, one `sort -z`); +# 6. ONE `git hash-object --stdin-paths` over the CACHE∩TREE intersection — +# the blob id each comparable file on disk actually has. A cache-only file +# is never hashed: its hash is not part of any answer, only its existence +# is, and it is settled by the ignore pass instead; +# 7. ONE `git check-ignore -z --no-index --stdin` over every cache-only file +# in the whole marketplace, and no process at all when there are none. +# Set difference on the relative paths then yields files present at the sha but # missing from the cache and files in the cache but absent at the sha; hash -# inequality on the intersection yields changed files. No `git cat-file` pass -# is needed once ls-tree has carried the ids. +# inequality on the intersection yields changed files. # # The source directory is read from the marketplace.json AT THE RECORDED SHA # (`git show :.claude-plugin/marketplace.json`), never from the clone's @@ -46,9 +63,7 @@ # perfectly matching cache reports `stale-content`. Reading both the source path # and the expected tree from the same revision removes the mismatch; a pathspec # that still matches nothing at that sha gets its own `no-source-at-sha` -# verdict, counted unverifiable, never reported as stale content. The per-sha -# manifest read is cached, so it costs one `git show` plus one `jq` per DISTINCT -# sha in the marketplace, not one per install record. +# verdict, counted unverifiable, never reported as stale content. # # Path transport is NUL-separated end to end (`ls-tree -z`, `find -print0`, # `check-ignore -z`). Without `-z`, git QUOTES a pathname carrying non-ASCII, @@ -79,9 +94,9 @@ # content is identical. Rather than pay a per-file `--path` hash for the whole # fleet, the raw batch runs first and only the MISMATCHES are re-hashed with # `git hash-object --path `, which does apply that path's -# attributes. A clean fleet therefore costs the two processes above; a dirty -# one pays one extra process per differing file, which is the population the -# operator is about to read one by one anyway. +# attributes. A clean fleet therefore costs the batch alone; a dirty one pays +# one extra process per differing file, which is the population the operator is +# about to read one by one anyway. # # Excluded from the cache side, by name, never by guesswork: `.git` (a cache # directory is a checkout, not a clone, but exclude it if one ever appears) and @@ -96,8 +111,10 @@ # tree — generated state that was never in any commit. Without this filter the # authoring machine reported three installs as stale purely on that state, one # of them on 6,141 files, with zero genuinely differing bytes. The filter is one -# batched `git check-ignore` per plugin that has any cache-only file at all, and -# no process for a clean one. +# batched `git check-ignore` for the whole marketplace, and no process at all +# when nothing in it has a cache-only file. The answer is keyed by the path the +# clone would see (`/`), so two records sharing a +# source directory read the same answer rather than asking twice. # # Verdicts, one per install record: # match every tree file present in the cache with the same @@ -265,6 +282,12 @@ MARKETPLACES_JSON="${CACHE_CONTENT_MARKETPLACES_JSON:-${FLEET_STATE_MARKETPLACES # every file and a report naming all of them is not a report. MAX_REPORTED_PATHS=10 +# A shape rejection has to be distinguishable from a legitimate jq result, and +# every legitimate result here is a path, a name, or a blob id. SOH (0x01) +# cannot appear in any of them. +SENTINEL_SHAPE=$'\x01shape' +SENTINEL_UNKNOWN=$'\x01unknown' + # --- Arg parsing --------------------------------------------------------------- # Parsed before any file is read, so a usage error costs no process. @@ -342,37 +365,64 @@ for f in "$INSTALLED_JSON" "$MARKETPLACES_JSON"; do fi done -# Shape validation is its own pass and it fails LOUD. A malformed state file -# read leniently produces an empty install list, which is indistinguishable -# from a clean fleet — the one wrong answer this check must never give. -if ! jq_to _shape_ok -e ' - (type == "object") - and ((.plugins // {}) | type == "object") - and ((.plugins // {}) | to_entries | all(.value | type == "array")) -' "$INSTALLED_JSON" >/dev/null 2>&1; then +# Shape validation rides the SAME jq pass that reads the records, so a +# marketplace costs one jq for its whole install list rather than one to +# validate plus one to read. It still fails LOUD: a malformed state file read +# leniently produces an empty install list, which is indistinguishable from a +# clean fleet — the one wrong answer this check must never give. +# +# Every marketplace's records are read here, once, and the per-marketplace +# filter is a suffix test in the shell. A filtered subsequence keeps +# `to_entries` order, so the install order in the report is unchanged. +installed_bad() { echo "ERROR: $INSTALLED_JSON is not valid installed_plugins.json (expected an object with a .plugins map of arrays)" >&2 exit 2 -fi -if ! jq_to _shape_ok -e 'type == "object"' "$MARKETPLACES_JSON" >/dev/null 2>&1; then +} +ALL_RECORDS="" +# shellcheck disable=SC2016 # a jq program: every $var is a jq variable +jq_to ALL_RECORDS -r --arg scope "$SCOPE" ' + if (type == "object") + and ((.plugins // {}) | type == "object") + and ((.plugins // {}) | to_entries | all(.value | type == "array")) + then + (.plugins // {}) + | to_entries + | map(.key as $id | .value[] | { + id: $id, + scope: (.scope // "user"), + version: (.version // ""), + sha: (.gitCommitSha // ""), + installPath: (.installPath // ""), + projectPath: (.projectPath // "") + }) + | map(select($scope == "all" or (if $scope == "user" then .scope == "user" else .scope != "user" end))) + | map([.id, .scope, .version, .sha, .installPath, .projectPath] | join("\u001f")) + | .[] + else + "\u0001shape" + end +' "$INSTALLED_JSON" 2>/dev/null || installed_bad +[[ "$ALL_RECORDS" != "$SENTINEL_SHAPE" ]] || installed_bad + +marketplaces_bad() { echo "ERROR: $MARKETPLACES_JSON is not valid known_marketplaces.json (expected an object)" >&2 exit 2 -fi +} # --- Per-marketplace check ----------------------------------------------------- -# Emits, on stdout, the single-marketplace JSON body for $1. Returns non-zero -# with a message on stderr only for a marketplace that cannot be named at all. +# Emits, on stdout, the single-marketplace JSON body for $1 whose resolved +# installLocation is $2. Returns non-zero with a message on stderr only for a +# marketplace that cannot be named at all. check_marketplace() { - local mp="$1" - local install_loc install_loc_native records + local mp="$1" install_loc="$2" + local install_loc_native + to_slashes_to install_loc_native "$install_loc" + local checked=0 n_match=0 n_stale=0 n_unverifiable=0 n_skipped=0 local records_json="" first="yes" local stale_ids="" - # shellcheck disable=SC2016 # a jq program: every $var is a jq variable - jq_to install_loc -r --arg mp "$mp" '.[$mp].installLocation // ""' "$MARKETPLACES_JSON" || return 1 - to_slashes_to install_loc_native "$install_loc" - # Marketplace-wide precondition, resolved ONCE rather than per install: the # worktree test is the same answer for every record. The source map is NOT # marketplace-wide — it is read per recorded sha, below. @@ -404,24 +454,8 @@ check_marketplace() { source_map_by_sha["$s"]="$parsed" } - # shellcheck disable=SC2016 # a jq program: every $var is a jq variable - jq_to records -r --arg mp "$mp" --arg scope "$SCOPE" ' - (.plugins // {}) - | to_entries - | map(select(.key | endswith("@" + $mp))) - | map(.key as $id | .value[] | { - id: $id, - scope: (.scope // "user"), - version: (.version // ""), - sha: (.gitCommitSha // ""), - installPath: (.installPath // ""), - projectPath: (.projectPath // "") - }) - | map(select($scope == "all" or (if $scope == "user" then .scope == "user" else .scope != "user" end))) - | map([.id, .scope, .version, .sha, .installPath, .projectPath] | join("\u001f")) - | .[] - ' "$INSTALLED_JSON" || return 1 - + # --- Pass 0: this marketplace's records, and the verdicts that need no git -- + # # US (0x1f), not tab, and the reason is not cosmetic. Bash treats tab as IFS # WHITESPACE, so consecutive tabs collapse into one separator and an EMPTY # middle field disappears: a record with no `gitCommitSha` would shift its @@ -429,15 +463,18 @@ check_marketplace() { # carrying a fabricated sha instead of the honest `no-git-commit-sha`. A # non-whitespace separator preserves every empty column. Same choice, and the # same character, as fleet-state.sh's internal record format. + local -a i_id=() i_scope=() i_version=() i_sha=() i_ipath=() i_root=() + local -a i_verdict=() i_srcdir=() local id scope version sha install_path project_path + local project_path_native install_path_native pre_verdict while IFS=$'\x1f' read -r id scope version sha install_path project_path; do [[ -n "$id" ]] || continue + [[ "$id" == *"@$mp" ]] || continue # A project/local record naming a directory that is not present is skipped # and counted, never verdicted: the cache directory may be perfectly fine # and the repo simply on an unmounted volume. if [[ "$scope" != "user" && -n "$project_path" ]]; then - local project_path_native to_slashes_to project_path_native "$project_path" if [[ ! -d "$project_path_native" ]]; then n_skipped=$((n_skipped + 1)) @@ -446,248 +483,470 @@ check_marketplace() { fi checked=$((checked + 1)) - local verdict="" paths=() n_differ=0 n_missing=0 n_extra=0 - local install_path_native to_slashes_to install_path_native "$install_path" - - local plugin_name="${id%@*}" - local source_dir="" - + pre_verdict="" if [[ -n "$loc_verdict" ]]; then - verdict="$loc_verdict" + pre_verdict="$loc_verdict" elif [[ -z "$install_path_native" || ! -d "$install_path_native" ]]; then - verdict="install-path-missing" + pre_verdict="install-path-missing" elif [[ -z "$sha" ]]; then - verdict="no-git-commit-sha" - elif ! git -C "$install_loc_native" cat-file -e "${sha}^{commit}" >/dev/null 2>&1; then - # Never `git fetch` here. Fetching is a network mutation the audit does - # not perform, and it would also silently repair the very condition the - # verdict exists to report. - # - # This test comes BEFORE the source lookup, and must: the source path is - # now read out of the commit itself, so there is nothing to read until the - # commit is known to be present locally. - verdict="sha-not-local" - else - # Source directory as the RECORDED COMMIT spelled it, never as the current - # checkout spells it. A plugin renamed or moved after that commit would - # otherwise be looked up under a path the older tree does not contain, and - # a pathspec matching nothing is success-with-empty-output, not an error. - load_source_map "$sha" - local sm_name sm_source - while IFS=$'\x1f' read -r sm_name sm_source; do - if [[ "$sm_name" == "$plugin_name" ]]; then - source_dir="$sm_source" - break - fi - done <<<"${source_map_by_sha[$sha]}" - # marketplace.json spells a local source relative to the clone root and - # commonly with a leading `./`, which ls-tree's pathspec does not want. - source_dir="${source_dir#./}" - source_dir="${source_dir%/}" + pre_verdict="no-git-commit-sha" fi - if [[ -z "$verdict" && -z "$source_dir" ]]; then - verdict="no-source" + i_id+=("$id") + i_scope+=("$scope") + i_version+=("$version") + i_sha+=("$sha") + i_ipath+=("$install_path") + i_root+=("$install_path_native") + i_verdict+=("$pre_verdict") + i_srcdir+=("") + done <<<"$ALL_RECORDS" + + local n=${#i_id[@]} + local k + + # --- Pass 1: is each DISTINCT sha an object in this clone ------------------- + # + # One `cat-file --batch-check` for the whole marketplace. Never `git fetch` + # here. Fetching is a network mutation the audit does not perform, and it + # would also silently repair the very condition the verdict exists to report. + # This test comes BEFORE the source lookup, and must: the source path is read + # out of the commit itself, so there is nothing to read until the commit is + # known to be present locally. + local -A sha_local=() sha_seen=() + local -a probe_shas=() + for ((k = 0; k < n; k++)); do + [[ -z "${i_verdict[k]}" ]] || continue + sha="${i_sha[k]}" + [[ -z "${sha_seen[$sha]+set}" ]] || continue + sha_seen["$sha"]=1 + # The batch's protocol is one object name per LINE, so a sha carrying + # whitespace would desynchronise every answer after it. Such a value is not + # an object name either — it is left out and reads as `sha-not-local`, + # which is what a per-record `cat-file -e` would have said. + case "$sha" in + *[$' \t\n\r']*) continue ;; + *) ;; + esac + probe_shas+=("$sha") + done + if [[ ${#probe_shas[@]} -gt 0 ]]; then + local probe_in="" probe_out="" probe_line="" pi=0 + printf -v probe_in '%s^{commit}\n' "${probe_shas[@]}" + if git_to probe_out -C "$install_loc_native" cat-file --batch-check <<<"${probe_in%$'\n'}" && + [[ -n "$probe_out" ]]; then + # Positional by contract: one answer line per input line, in order. A + # present object answers ` `, an absent one echoes the + # input back with ` missing`. + while IFS= read -r probe_line; do + [[ $pi -lt ${#probe_shas[@]} ]] || break + case "$probe_line" in + "" | *" missing" | *" ambiguous") ;; + *) sha_local["${probe_shas[pi]}"]=1 ;; + esac + pi=$((pi + 1)) + done <<<"$probe_out" fi + fi + for ((k = 0; k < n; k++)); do + [[ -z "${i_verdict[k]}" ]] || continue + [[ -z "${sha_local[${i_sha[k]}]+set}" ]] || continue + i_verdict[k]="sha-not-local" + done - if [[ -z "$verdict" ]]; then - # `ls-tree -z` never goes through `git_to`: command substitution DROPS NUL - # bytes, which is the whole transport here. Read as NUL records instead, - # with the exit status appended as one final record so a process - # substitution's otherwise-invisible status is still checked. - local -a tree_recs=() - local tree_rc=0 - mapfile -d '' -t tree_recs < <( - git -C "$install_loc_native" ls-tree -r -z "$sha" -- "$source_dir" 2>/dev/null - printf '%d\0' "$?" - ) - tree_rc="${tree_recs[-1]}" - unset 'tree_recs[-1]' - if [[ "$tree_rc" != "0" ]]; then - verdict="no-source" - elif [[ ${#tree_recs[@]} -eq 0 ]]; then - # The pathspec matched nothing at this sha. Its own verdict, counted - # unverifiable: an empty expected tree makes every cache file an extra, - # and reporting that as stale-content accuses a healthy cache. - verdict="no-source-at-sha" - else - # The two sides are indexed into associative arrays rather than walked - # as parallel lists: a plugin that vendors `node_modules` carries - # thousands of cache files, and a nested-loop membership test over both - # directions is quadratic in exactly the population where it hurts. - local -a tree_paths=() tree_hashes=() - local -A tree_hash_by_path=() cache_hash_by_path=() - local rec meta path_rel blob - for rec in "${tree_recs[@]}"; do - [[ -n "$rec" ]] || continue - meta="${rec%%$'\t'*}" - path_rel="${rec#*$'\t'}" - blob="${meta##* }" - # Keep only blobs; a submodule (commit) entry has no file on disk to - # compare and is not a stale-content signal. Mode 120000 is a blob - # too — a symlink — and is kept, because the cache walk below hashes - # links the same way git stores them. - case "$meta" in - *" blob "*) ;; - *) continue ;; - esac - path_rel="${path_rel#"$source_dir"/}" - tree_paths+=("$path_rel") - tree_hashes+=("$blob") - tree_hash_by_path["$path_rel"]="$blob" - done + # --- Pass 2: the source directory each record's own commit names ------------ + # + # Source directory as the RECORDED COMMIT spelled it, never as the current + # checkout spells it. A plugin renamed or moved after that commit would + # otherwise be looked up under a path the older tree does not contain, and a + # pathspec matching nothing is success-with-empty-output, not an error. + local plugin_name sm_name sm_source src_dir + for ((k = 0; k < n; k++)); do + [[ -z "${i_verdict[k]}" ]] || continue + load_source_map "${i_sha[k]}" + plugin_name="${i_id[k]%@*}" + src_dir="" + while IFS=$'\x1f' read -r sm_name sm_source; do + if [[ "$sm_name" == "$plugin_name" ]]; then + src_dir="$sm_source" + break + fi + done <<<"${source_map_by_sha[${i_sha[k]}]}" + # marketplace.json spells a local source relative to the clone root and + # commonly with a leading `./`, which ls-tree's pathspec does not want. + src_dir="${src_dir#./}" + src_dir="${src_dir%/}" + if [[ -z "$src_dir" ]]; then + i_verdict[k]="no-source" + else + i_srcdir[k]="$src_dir" + fi + done - # Cache side: one find, then one batched hash-object. `.in_use` is - # Claude Code's own refcount directory and `.git` would be a checkout - # artifact; both are excluded by name. `-print0` because a pathname may - # carry any byte but NUL, and the enumeration must not be the place a - # name gets mangled. Symlinks are enumerated alongside regular files; - # `-type f` alone would report every tracked link as missing forever. - # `sort -z` keeps the reported paths[] sample stable across runs on the - # same fixture, which a report read by a human is entitled to. - local -a cache_entries=() cache_paths=() batch_paths=() - mapfile -d '' -t cache_entries < <( - find "$install_path_native" \( -type f -o -type l \) \ - -not -path '*/.git/*' -not -path '*/.in_use/*' -print0 2>/dev/null | - sort -z - ) - - local cache_list="" f rel link_target="" one_hash="" - for f in ${cache_entries+"${cache_entries[@]}"}; do - [[ -n "$f" ]] || continue - rel="${f#"$install_path_native"/}" - cache_paths+=("$rel") - if [[ -L "$f" ]]; then - # git stores a symlink as a blob holding the TARGET TEXT, so that is - # what gets hashed. Feeding the link path to `hash-object` would - # hash the file it points at and call every link stale. - link_target=$(readlink "$f" 2>/dev/null) - if git_to one_hash -C "$install_loc_native" hash-object --stdin < <(printf '%s' "$link_target"); then - cache_hash_by_path["$rel"]="$one_hash" - fi - continue - fi - if [[ "$f" == *$'\n'* ]]; then - # `git hash-object --stdin-paths` has no `-z` switch, so its input - # is newline-terminated and a name containing a newline cannot ride - # it. That one character, and only that one, falls back to a process - # of its own; tabs, backslashes and non-ASCII all survive the batch. - if git_to one_hash -C "$install_loc_native" hash-object -- "$f"; then - cache_hash_by_path["$rel"]="$one_hash" - fi - continue - fi - batch_paths+=("$rel") - cache_list+="$f"$'\n' - done + # --- Pass 3: one ls-tree per DISTINCT sha, every source dir at once --------- + local -a g_sha=() g_dir=() + local -A g_seen=() + local gkey + for ((k = 0; k < n; k++)); do + [[ -z "${i_verdict[k]}" ]] || continue + gkey="${i_sha[k]}"$'\x1f'"${i_srcdir[k]}" + [[ -z "${g_seen[$gkey]+set}" ]] || continue + g_seen["$gkey"]=1 + g_sha+=("${i_sha[k]}") + g_dir+=("${i_srcdir[k]}") + done - # The batch's output is positional: line N is the hash of input path N. - # If it ever comes back short, every entry after the gap is filed under - # the WRONG path and the run reports files as differing that are fine. - # `hash-object` is one line per input by contract, so this is a guard - # against a broken contract rather than an expected branch — and the - # answer to a broken contract is to say so, not to compare a table that - # may be shifted. - local hash_misaligned="" line - if [[ -n "$cache_list" ]]; then - local hash_out="" hi=0 - if git_to hash_out -C "$install_loc_native" hash-object --stdin-paths <<<"${cache_list%$'\n'}"; then - while IFS= read -r line; do - [[ -n "$line" ]] || continue - [[ $hi -lt ${#batch_paths[@]} ]] || break - cache_hash_by_path["${batch_paths[hi]}"]="$line" - hi=$((hi + 1)) - done <<<"$hash_out" - fi - [[ $hi -eq ${#batch_paths[@]} ]] || hash_misaligned="yes" - fi + local -a uniq_shas=() + local -A uniq_seen=() + local gi + for ((gi = 0; gi < ${#g_sha[@]}; gi++)); do + [[ -z "${uniq_seen[${g_sha[gi]}]+set}" ]] || continue + uniq_seen["${g_sha[gi]}"]=1 + uniq_shas+=("${g_sha[gi]}") + done - local i - if [[ -n "$hash_misaligned" ]]; then - verdict="hash-batch-misaligned" - tree_paths=() + # Flat, in ls-tree order; owner_idx[""] is the ordered + # index list of the entries that belong to one install's source directory. + # `ls-tree -r` walks the tree in sorted order regardless of pathspec order, + # so filtering that one stream per source directory preserves the order a + # single-pathspec call would have produced. + local -a tree_rel=() tree_blob=() + local -A tree_hash=() owner_idx=() tree_rc_bad=() + local s rec meta path_rel blob owner walk rel idx tree_rc + for s in ${uniq_shas+"${uniq_shas[@]}"}; do + local -a specs=() + for ((gi = 0; gi < ${#g_sha[@]}; gi++)); do + [[ "${g_sha[gi]}" == "$s" ]] || continue + specs+=("${g_dir[gi]}") + done + # ponytail: one pathspec per distinct source directory at this sha, in one + # argv. A marketplace would need thousands of DISTINCT source directories + # sharing a single commit to approach the argv ceiling; chunk here if one + # ever does. + local -a tree_recs=() + mapfile -d '' -t tree_recs < <( + git -C "$install_loc_native" ls-tree -r -z "$s" -- "${specs[@]}" 2>/dev/null + printf '%d\0' "$?" + ) + tree_rc="${tree_recs[-1]}" + unset 'tree_recs[-1]' + if [[ "$tree_rc" != "0" ]]; then + tree_rc_bad["$s"]=1 + continue + fi + for rec in ${tree_recs+"${tree_recs[@]}"}; do + [[ -n "$rec" ]] || continue + meta="${rec%%$'\t'*}" + path_rel="${rec#*$'\t'}" + blob="${meta##* }" + # Keep only blobs; a submodule (commit) entry has no file on disk to + # compare and is not a stale-content signal. Mode 120000 is a blob + # too — a symlink — and is kept, because the cache walk below hashes + # links the same way git stores them. + case "$meta" in + *" blob "*) ;; + *) continue ;; + esac + # Which source directories this entry belongs to. Attach it to EVERY + # matching source, not only the longest: two marketplace entries can nest + # (`plugins/alpha` and `plugins/alpha/nested`), and the previous + # per-source `ls-tree` included the blob in both expected trees. The path + # itself is tried first so a `source` naming a single file still resolves + # the way a single-pathspec call resolved it. + walk="$path_rel" + while :; do + gkey="$s"$'\x1f'"$walk" + if [[ -n "${g_seen[$gkey]+set}" ]]; then + owner="$walk" + rel="${path_rel#"$owner"/}" + idx=${#tree_rel[@]} + tree_rel+=("$rel") + tree_blob+=("$blob") + # Keyed by SHA as well as source directory, the way `owner_idx` and + # `g_seen` are. Two records can share one source directory at + # different shas — the same plugin id at user and project scope, same + # version, one installPath — and a map keyed by directory alone would + # merge their trees: a file present only at the newer sha would then + # read as in-tree for the older record, never reach `extras_idx`, and + # a stale cache would verdict `match`. + tree_hash["$s"$'\x1f'"$owner"$'\x1f'"$rel"]="$blob" + owner_idx["$s"$'\x1f'"$owner"]+=" $idx" fi - # Direction 1: every tree path must exist in the cache with the same - # blob id. - for ((i = 0; i < ${#tree_paths[@]}; i++)); do - if [[ -z "${cache_hash_by_path[${tree_paths[i]}]+set}" ]]; then - n_missing=$((n_missing + 1)) - paths+=("missing-from-cache: ${tree_paths[i]}") - continue - fi - if [[ "${cache_hash_by_path[${tree_paths[i]}]}" == "${tree_hashes[i]}" ]]; then - continue - fi - # Raw hashes disagree. Re-hash THIS file with the repo-relative path - # so `.gitattributes` (an `eol=crlf` pin, a clean filter) applies, and - # only report a difference the filtered hash also sees. This is the - # per-file process the batch above exists to avoid paying fleet-wide. - local filtered="" - if git_to filtered -C "$install_loc_native" hash-object \ - --path "$source_dir/${tree_paths[i]}" -- "$install_path_native/${tree_paths[i]}" 2>/dev/null && - [[ "$filtered" == "${tree_hashes[i]}" ]]; then - continue + [[ "$walk" == */* ]] || break + walk="${walk%/*}" + done + done + done + # A multi-pathspec ls-tree cannot report "this one pathspec matched nothing", + # so the signal is recovered here: an install whose source directory + # contributed no blob at its sha is `no-source-at-sha`, never `match`. + for ((k = 0; k < n; k++)); do + [[ -z "${i_verdict[k]}" ]] || continue + if [[ -n "${tree_rc_bad[${i_sha[k]}]+set}" ]]; then + i_verdict[k]="no-source" + continue + fi + gkey="${i_sha[k]}"$'\x1f'"${i_srcdir[k]}" + [[ -n "${owner_idx[$gkey]+set}" ]] || i_verdict[k]="no-source-at-sha" + done + + # --- Pass 4: one find over every install root ------------------------------- + # + # `.in_use` is Claude Code's own refcount directory and `.git` would be a + # checkout artifact; both are excluded by name. `-print0` because a pathname + # may carry any byte but NUL, and the enumeration must not be the place a + # name gets mangled. Symlinks are enumerated alongside regular files; + # `-type f` alone would report every tracked link as missing forever. + # `sort -z` keeps the reported paths[] sample stable across runs on the same + # fixture, which a report read by a human is entitled to — and sorting the + # whole fleet's paths at once preserves, within each install, the order + # sorting that install alone would have produced. + local -a roots=() + local -A root_seen=() root_files=() + local rt + for ((k = 0; k < n; k++)); do + [[ -z "${i_verdict[k]}" ]] || continue + rt="${i_root[k]}" + [[ -n "${root_seen[$rt]+set}" ]] || { + root_seen["$rt"]=1 + roots+=("$rt") + } + done + + local -a cache_full=() + if [[ ${#roots[@]} -gt 0 ]]; then + mapfile -d '' -t cache_full < <( + { + # Chunked on a byte budget: an argv over the OS limit would make find + # fail, and with its stderr discarded that reads as an empty cache — + # every install in the fleet reported wholly missing-from-cache. + chunk=() + chunk_len=0 + for rt in "${roots[@]}"; do + if [[ ${#chunk[@]} -gt 0 ]] && ((chunk_len + ${#rt} + 1 > 16000)); then + find "${chunk[@]}" \( -type f -o -type l \) \ + -not -path '*/.git/*' -not -path '*/.in_use/*' -print0 2>/dev/null + chunk=() + chunk_len=0 fi - n_differ=$((n_differ + 1)) - paths+=("differs: ${tree_paths[i]}") + chunk+=("$rt") + chunk_len=$((chunk_len + ${#rt} + 1)) done + if [[ ${#chunk[@]} -gt 0 ]]; then + find "${chunk[@]}" \( -type f -o -type l \) \ + -not -path '*/.git/*' -not -path '*/.in_use/*' -print0 2>/dev/null + fi + } | sort -z + ) + fi - # Direction 2: a file deleted at the sha but still sitting in the cache - # is the same defect seen from the other side, and is exactly one of - # the shapes the reported incident carried. - # - # Filtered through the marketplace's OWN .gitignore first, and that - # filter is not an optimization — without it the check is wrong. A - # cache directory is a live plugin root: Python writes `__pycache__` - # beside the scripts it runs and a plugin that vendors dependencies has - # a `node_modules` tree, none of which was ever in any commit. On the - # authoring machine those alone reported three installs as stale, one - # of them on 6,141 files, with zero genuinely differing bytes. A path - # the marketplace repo itself declines to track is generated state, not - # a stale build. One batched `git check-ignore` per plugin that has any - # extra at all, and none for a clean one. `--no-index` so the answer is - # the ignore rules' answer rather than "tracked, therefore not - # ignored"; the paths are rewritten under the plugin's source directory - # so a source-scoped rule matches the same way it would in the clone. - local -a extras=() - local cp - for cp in "${cache_paths[@]:-}"; do - [[ -z "$hash_misaligned" ]] || break - [[ -n "$cp" ]] || continue - [[ -z "${tree_hash_by_path[$cp]+set}" ]] || continue - extras+=("$cp") - done - if [[ ${#extras[@]} -gt 0 ]]; then - local -a ignored_recs=() - local -A ignored=() - # `-z` on both sides, and read as NUL records rather than through - # command substitution, for the same reason ls-tree is: a quoted - # pathname would not match the raw path it came from. - # check-ignore exits 1 when NOTHING matched, which is a valid answer, - # so its status is deliberately not read as a failure. - mapfile -d '' -t ignored_recs < <( - printf '%s\0' "${extras[@]/#/$source_dir/}" | - git -C "$install_loc_native" check-ignore -z --no-index --stdin 2>/dev/null - ) - for line in ${ignored_recs+"${ignored_recs[@]}"}; do - [[ -n "$line" ]] || continue - ignored["${line#"$source_dir"/}"]=1 - done - for cp in "${extras[@]}"; do - [[ -z "${ignored[$cp]+set}" ]] || continue - n_extra=$((n_extra + 1)) - paths+=("extra-in-cache: $cp") - done + # Each file's path relative to its own install root is derived HERE, once. + # The passes below index it rather than re-deriving it: with ten thousand + # cache files and three passes over them, the shell's own loop is what a + # batched run spends its time on, not the processes it no longer starts. + local -a cache_rel=() + local cache_i f walk_dir + for ((cache_i = 0; cache_i < ${#cache_full[@]}; cache_i++)); do + cache_rel[cache_i]="" + f="${cache_full[cache_i]}" + [[ -n "$f" ]] || continue + walk_dir="$f" + while [[ "$walk_dir" == */* ]]; do + walk_dir="${walk_dir%/*}" + if [[ -n "${root_seen[$walk_dir]+set}" ]]; then + root_files["$walk_dir"]+=" $cache_i" + cache_rel[cache_i]="${f#"$walk_dir"/}" + break + fi + done + done + + # --- Pass 5: split each install's cache files at the tree boundary ---------- + # + # One walk settles both directions: a file the tree also carries joins the + # hash batch, and a file it does not is recorded as this install's extra for + # the ignore pass below. + # + # A cache-only file is deliberately not hashed. Its hash answers no question: + # direction 2 needs only its existence, and the ignore pass decides whether it + # counts. On a fleet with a vendored `node_modules` that is the difference + # between hashing three thousand files and hashing ten thousand. + local -a b_full=() b_owner=() b_rel=() + local -a ins_batch_start=() ins_batch_end=() + local -A cache_hash=() extras_idx=() extra_seen=() + local -a extra_probe=() + local src_key probe_key link_target one_hash + for ((k = 0; k < n; k++)); do + ins_batch_start[k]=${#b_full[@]} + if [[ -n "${i_verdict[k]}" ]]; then + ins_batch_end[k]=${#b_full[@]} + continue + fi + rt="${i_root[k]}" + src_dir="${i_srcdir[k]}" + for cache_i in ${root_files[$rt]:-}; do + f="${cache_full[cache_i]}" + rel="${cache_rel[cache_i]}" + src_key="${i_sha[k]}"$'\x1f'"$src_dir"$'\x1f'"$rel" + if [[ -z "${tree_hash[$src_key]+set}" ]]; then + extras_idx[$k]+=" $cache_i" + probe_key="$src_dir/$rel" + [[ -n "${extra_seen[$probe_key]+set}" ]] || { + extra_seen["$probe_key"]=1 + extra_probe+=("$probe_key") + } + continue + fi + if [[ -L "$f" ]]; then + # git stores a symlink as a blob holding the TARGET TEXT, so that is + # what gets hashed. Feeding the link path to `hash-object` would hash + # the file it points at and call every link stale. + link_target=$(readlink "$f" 2>/dev/null) + if git_to one_hash -C "$install_loc_native" hash-object --stdin < <(printf '%s' "$link_target"); then + cache_hash["$k"$'\x1f'"$rel"]="$one_hash" fi + continue + fi + if [[ "$f" == *$'\n'* ]]; then + # `git hash-object --stdin-paths` has no `-z` switch, so its input is + # newline-terminated and a name containing a newline cannot ride it. + # That one character, and only that one, falls back to a process of its + # own; tabs, backslashes and non-ASCII all survive the batch. + if git_to one_hash -C "$install_loc_native" hash-object -- "$f"; then + cache_hash["$k"$'\x1f'"$rel"]="$one_hash" + fi + continue + fi + b_full+=("$f") + b_owner+=("$k") + b_rel+=("$rel") + done + ins_batch_end[k]=${#b_full[@]} + done + + # The batch's output is positional: line N is the hash of input path N. If it + # ever comes back short, every entry after the gap is filed under the WRONG + # path and the run reports files as differing that are fine. `hash-object` is + # one line per input by contract, so this is a guard against a broken + # contract rather than an expected branch — and the answer to a broken + # contract is to say so, not to compare a table that may be shifted. + # + # ponytail: one batch for the whole marketplace, so a truncation lands on the + # install that owns the gap AND on every install after it, where a per-install + # batch would have confined it to one. Both are the same unexpected + # contract break, and the reported verdict is still "refused to compare"; + # split the batch per install if that blast radius ever needs narrowing. + local hi=0 + if [[ ${#b_full[@]} -gt 0 ]]; then + local batch_in="" hash_out="" line + printf -v batch_in '%s\n' "${b_full[@]}" + if git_to hash_out -C "$install_loc_native" hash-object --stdin-paths <<<"${batch_in%$'\n'}"; then + while IFS= read -r line; do + [[ -n "$line" ]] || continue + [[ $hi -lt ${#b_full[@]} ]] || break + cache_hash["${b_owner[hi]}"$'\x1f'"${b_rel[hi]}"]="$line" + hi=$((hi + 1)) + done <<<"$hash_out" + fi + for ((k = 0; k < n; k++)); do + [[ -z "${i_verdict[k]}" ]] || continue + ((ins_batch_end[k] > ins_batch_start[k])) || continue + ((hi < ins_batch_end[k])) || continue + i_verdict[k]="hash-batch-misaligned" + done + fi + + # --- Pass 6: one check-ignore over every cache-only file -------------------- + # + # Filtered through the marketplace's OWN .gitignore, and that filter is not an + # optimization — without it the check is wrong. A cache directory is a live + # plugin root: Python writes `__pycache__` beside the scripts it runs and a + # plugin that vendors dependencies has a `node_modules` tree, none of which + # was ever in any commit. On the authoring machine those alone reported three + # installs as stale, one of them on 6,141 files, with zero genuinely differing + # bytes. A path the marketplace repo itself declines to track is generated + # state, not a stale build. `--no-index` so the answer is the ignore rules' + # answer rather than "tracked, therefore not ignored"; the paths are rewritten + # under the plugin's source directory so a source-scoped rule matches the same + # way it would in the clone, and the answer is keyed by that same spelling so + # two records sharing a source directory read one answer. + local -A ignored=() + if [[ ${#extra_probe[@]} -gt 0 ]]; then + local -a ignored_recs=() + # `-z` on both sides, and read as NUL records rather than through command + # substitution, for the same reason ls-tree is: a quoted pathname would not + # match the raw path it came from. check-ignore exits 1 when NOTHING + # matched, which is a valid answer, so its status is deliberately not read + # as a failure. + mapfile -d '' -t ignored_recs < <( + printf '%s\0' "${extra_probe[@]}" | + git -C "$install_loc_native" check-ignore -z --no-index --stdin 2>/dev/null + ) + for line in ${ignored_recs+"${ignored_recs[@]}"}; do + [[ -n "$line" ]] || continue + ignored["$line"]=1 + done + fi + + # --- Pass 7: the per-install verdict and its JSON record -------------------- + local verdict n_differ n_missing n_extra ti filtered + local j_id j_scope j_version j_sha j_path j_verdict + local paths_json p np pfirst jp + for ((k = 0; k < n; k++)); do + verdict="${i_verdict[k]}" + local -a paths=() + n_differ=0 + n_missing=0 + n_extra=0 - if [[ -n "$hash_misaligned" ]]; then - : # verdict already set to hash-batch-misaligned; counts stay at zero - elif [[ $((n_differ + n_missing + n_extra)) -gt 0 ]]; then - verdict="stale-content" - else - verdict="match" + if [[ -z "$verdict" ]]; then + rt="${i_root[k]}" + src_dir="${i_srcdir[k]}" + gkey="${i_sha[k]}"$'\x1f'"$src_dir" + + # Direction 1: every tree path must exist in the cache with the same + # blob id. + for ti in ${owner_idx[$gkey]:-}; do + rel="${tree_rel[ti]}" + src_key="$k"$'\x1f'"$rel" + if [[ -z "${cache_hash[$src_key]+set}" ]]; then + n_missing=$((n_missing + 1)) + paths+=("missing-from-cache: $rel") + continue + fi + if [[ "${cache_hash[$src_key]}" == "${tree_blob[ti]}" ]]; then + continue fi + # Raw hashes disagree. Re-hash THIS file with the repo-relative path so + # `.gitattributes` (an `eol=crlf` pin, a clean filter) applies, and only + # report a difference the filtered hash also sees. This is the per-file + # process the batch above exists to avoid paying fleet-wide. + filtered="" + if git_to filtered -C "$install_loc_native" hash-object \ + --path "$src_dir/$rel" -- "$rt/$rel" 2>/dev/null && + [[ "$filtered" == "${tree_blob[ti]}" ]]; then + continue + fi + n_differ=$((n_differ + 1)) + paths+=("differs: $rel") + done + + # Direction 2: a file deleted at the sha but still sitting in the cache + # is the same defect seen from the other side, and is exactly one of the + # shapes the reported incident carried. + for cache_i in ${extras_idx[$k]:-}; do + rel="${cache_rel[cache_i]}" + probe_key="$src_dir/$rel" + [[ -z "${ignored[$probe_key]+set}" ]] || continue + n_extra=$((n_extra + 1)) + paths+=("extra-in-cache: $rel") + done + + if [[ $((n_differ + n_missing + n_extra)) -gt 0 ]]; then + verdict="stale-content" + else + verdict="match" fi fi @@ -695,24 +954,25 @@ check_marketplace() { match) n_match=$((n_match + 1)) ;; stale-content) n_stale=$((n_stale + 1)) - stale_ids+="$id"$'\n' + stale_ids+="${i_id[k]}"$'\n' ;; *) n_unverifiable=$((n_unverifiable + 1)) ;; esac - local j_id j_scope j_version j_sha j_path j_verdict - json_string_to j_id "$id" - json_string_to j_scope "$scope" - json_string_to j_version "$version" - json_string_to j_sha "$sha" - json_string_to j_path "$install_path" + json_string_to j_id "${i_id[k]}" + json_string_to j_scope "${i_scope[k]}" + json_string_to j_version "${i_version[k]}" + json_string_to j_sha "${i_sha[k]}" + json_string_to j_path "${i_ipath[k]}" json_string_to j_verdict "$verdict" - local paths_json="" p n=0 pfirst="yes" jp + paths_json="" + np=0 + pfirst="yes" for p in "${paths[@]:-}"; do [[ -n "$p" ]] || continue - n=$((n + 1)) - [[ $n -le $MAX_REPORTED_PATHS ]] || break + np=$((np + 1)) + [[ $np -le $MAX_REPORTED_PATHS ]] || break json_string_to jp "$p" if [[ "$pfirst" == "yes" ]]; then pfirst="no" @@ -731,7 +991,7 @@ check_marketplace() { records_json+=",\"installPath\":$j_path,\"verdict\":$j_verdict" records_json+=",\"differing\":$n_differ,\"missing_from_cache\":$n_missing,\"extra_in_cache\":$n_extra" records_json+=",\"paths\":[$paths_json]}" - done <<<"$records" + done if [[ -n "$IDS_MODE" ]]; then printf '%s' "$stale_ids" @@ -747,24 +1007,31 @@ check_marketplace() { # --- Dispatch ------------------------------------------------------------------ -# `known` is a write-only sink: the membership answer this run acts on is -# jq's EXIT STATUS under -e, not the `true`/`false` it also prints. Declared -# so `jq_to`'s indirect `printf -v` has a target the linter can see. -# shellcheck disable=SC2034 -known="" -mp_names="" +mp_loc="" +mp_pairs="" envelope="" j_name="" j_err="" if [[ "$MODE" == "single" ]]; then + # One jq answers all three questions the single-marketplace path asks of this + # file: is it shaped like a map, does it name the requested marketplace, and + # where is that marketplace's clone. # shellcheck disable=SC2016 # a jq program: every $var is a jq variable - jq_to known -e --arg mp "$TARGET" 'has($mp)' "$MARKETPLACES_JSON" >/dev/null 2>&1 || { + jq_to mp_loc -r --arg mp "$TARGET" ' + if type != "object" then "\u0001shape" + elif (has($mp) | not) then "\u0001unknown" + else (.[$mp] as $v + | if ($v | type) == "object" then ($v.installLocation // "" | tostring) else "" end) + end + ' "$MARKETPLACES_JSON" 2>/dev/null || marketplaces_bad + [[ "$mp_loc" != "$SENTINEL_SHAPE" ]] || marketplaces_bad + if [[ "$mp_loc" == "$SENTINEL_UNKNOWN" ]]; then echo "ERROR: unknown marketplace: $TARGET (not in $MARKETPLACES_JSON)" >&2 exit 2 - } + fi out="" - out=$(check_marketplace "$TARGET") || { + out=$(check_marketplace "$TARGET" "$mp_loc") || { echo "ERROR: could not read marketplace: $TARGET" >&2 exit 2 } @@ -773,15 +1040,24 @@ if [[ "$MODE" == "single" ]]; then exit 0 fi -jq_to mp_names -r 'keys[]' "$MARKETPLACES_JSON" || { - echo "ERROR: could not enumerate marketplaces in $MARKETPLACES_JSON" >&2 - exit 2 -} +# `keys[]` order, so the envelope's key order is the sorted one the +# single-marketplace path's callers already see from `--all`. +# shellcheck disable=SC2016 # a jq program: every $var is a jq variable +jq_to mp_pairs -r ' + if type != "object" then "\u0001shape" + else (keys[] as $k + | $k + "\u001f" + + (.[$k] as $v + | if ($v | type) == "object" then ($v.installLocation // "" | tostring) else "" end)) + end +' "$MARKETPLACES_JSON" 2>/dev/null || marketplaces_bad +[[ "$mp_pairs" != "$SENTINEL_SHAPE" ]] || marketplaces_bad + envelope="" env_first="yes" -while IFS= read -r mp; do +while IFS=$'\x1f' read -r mp mp_loc; do [[ -n "$mp" ]] || continue block="" - if ! block=$(check_marketplace "$mp"); then + if ! block=$(check_marketplace "$mp" "$mp_loc"); then json_string_to j_err "could not read marketplace" block="{\"error\":$j_err}" fi @@ -792,6 +1068,6 @@ while IFS= read -r mp; do envelope+="," fi envelope+="$j_name:$block" -done <<<"$mp_names" +done <<<"$mp_pairs" printf '{"marketplaces":{%s}}\n' "$envelope" exit 0 diff --git a/plugins/claude-ops/skills/plugins/scripts/cache-content-check.test.sh b/plugins/claude-ops/skills/plugins/scripts/cache-content-check.test.sh index 8b1024a230a..5c8c107ff8e 100755 --- a/plugins/claude-ops/skills/plugins/scripts/cache-content-check.test.sh +++ b/plugins/claude-ops/skills/plugins/scripts/cache-content-check.test.sh @@ -710,6 +710,117 @@ out=$(run_check "$case_dir" --marketplace market1) assert_eq "hash-batch-misaligned: the same fixture with the real git is a match" \ "match" "$(jq -r '.installs[0].verdict' <<<"$out" 2>/dev/null)" +# ============================================================================ +# Case: two records share ONE source directory at DIFFERENT shas. The tree +# lookup is keyed by sha as well as by source directory, so the newer sha's +# file list cannot stand in for the older one's: a file that exists only at the +# newer sha is a cache-only extra for the record pinned to the older one, and +# that record is stale-content rather than match. +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +read -r SHA1 SHA2 <<<"$(seed_market_repo "$case_dir")" +# A third commit whose ONLY delta is one added file. Anything else in it would +# make the older record stale for a `differs` or `missing-from-cache` reason and +# the extra-in-cache direction — the one a sha-blind tree map suppresses — would +# never be what the verdict rests on. +write "$case_dir/market/plugins/alpha/lib/extra.sh" 'echo extra' +git -C "$case_dir/market" add -A +git -C "$case_dir/market" commit -q -m three +SHA3=$(git -C "$case_dir/market" rev-parse HEAD) +seed_cache_from "$case_dir" "$SHA3" >/dev/null +mkdir -p "$case_dir/present-repo" +write "$case_dir/installed_plugins.json" "{ + \"version\": 1, + \"plugins\": { + \"alpha@market1\": [ + {\"scope\":\"user\",\"version\":\"1.0.0\",\"gitCommitSha\":\"$SHA2\",\"installPath\":\"$case_dir/cache/alpha/1.0.0\"}, + {\"scope\":\"project\",\"version\":\"1.0.0\",\"gitCommitSha\":\"$SHA3\",\"installPath\":\"$case_dir/cache/alpha/1.0.0\",\"projectPath\":\"$case_dir/present-repo\"} + ] + } +}" +write "$case_dir/known_marketplaces.json" \ + "{\"market1\": {\"installLocation\": \"$case_dir/market\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +out=$(run_check "$case_dir" --marketplace market1 --scope all) +rc=$? +assert_exit "shared source dir, two shas: exit 0" 0 "$rc" +assert_eq "shared source dir: both records checked" "2" "$(jq -r '.checked' <<<"$out" 2>/dev/null)" +# Selected by sha, never by array position: the record order is the state file's, +# not this assertion's to assume. +assert_eq "shared source dir: the record at the newer sha matches" "match" \ + "$(jq -r --arg s "$SHA3" 'first(.installs[] | select(.gitCommitSha == $s) | .verdict)' <<<"$out" 2>/dev/null)" +assert_eq "shared source dir: the record at the older sha is stale-content" "stale-content" \ + "$(jq -r --arg s "$SHA2" 'first(.installs[] | select(.gitCommitSha == $s) | .verdict)' <<<"$out" 2>/dev/null)" +assert_eq "shared source dir: the file added at the newer sha is the older record's cache-only extra" "1" \ + "$(jq -r --arg s "$SHA2" 'first(.installs[] | select(.gitCommitSha == $s) | .extra_in_cache)' <<<"$out" 2>/dev/null)" +assert_contains "shared source dir: that extra is named" \ + "$(jq -r --arg s "$SHA2" 'first(.installs[] | select(.gitCommitSha == $s) | .paths | join(","))' <<<"$out" 2>/dev/null)" \ + "extra-in-cache: lib/extra.sh" +assert_eq "shared source dir: and nothing else is reported against it" "0 0" \ + "$(jq -r --arg s "$SHA2" 'first(.installs[] | select(.gitCommitSha == $s) | "\(.differing) \(.missing_from_cache)")' <<<"$out" 2>/dev/null)" +assert_eq "shared source dir: exactly one of the two is stale" "1" "$(jq -r '.stale_content' <<<"$out" 2>/dev/null)" + +# ============================================================================ +# Case: two marketplace entries with nested source directories share one sha. +# The batched ls-tree emits each blob once; the join must attach it to EVERY +# matching source, the way a per-source ls-tree included it in both expected +# trees. Longest-match-only drops the nested subtree from the ancestor, so a +# healthy ancestor cache containing that subtree is reported stale-content +# (cache-only extras) and an ancestor cache missing it is reported as a match. +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +repo="$case_dir/market" +mkdir -p "$repo" +git -C "$repo" init -q -b main +git -C "$repo" config user.email fixture@example.invalid +git -C "$repo" config user.name fixture +git -C "$repo" config commit.gpgsign false +write "$repo/.claude-plugin/marketplace.json" \ + '{"plugins":[{"name":"alpha","source":"./plugins/alpha"},{"name":"nested","source":"./plugins/alpha/nested"}]}' +write "$repo/plugins/alpha/root.sh" 'echo root' +write "$repo/plugins/alpha/nested/inner.sh" 'echo inner' +git -C "$repo" add -A +git -C "$repo" commit -q -m nested-sources +NESTED_SHA=$(git -C "$repo" rev-parse HEAD) +mkdir -p "$case_dir/cache/alpha/1.0.0/nested" "$case_dir/cache/nested/1.0.0" +write "$case_dir/cache/alpha/1.0.0/root.sh" 'echo root' +write "$case_dir/cache/alpha/1.0.0/nested/inner.sh" 'echo inner' +write "$case_dir/cache/nested/1.0.0/inner.sh" 'echo inner' +write "$case_dir/installed_plugins.json" "{ + \"version\": 1, + \"plugins\": { + \"alpha@market1\": [ + {\"scope\":\"user\",\"version\":\"1.0.0\",\"gitCommitSha\":\"$NESTED_SHA\",\"installPath\":\"$case_dir/cache/alpha/1.0.0\"} + ], + \"nested@market1\": [ + {\"scope\":\"user\",\"version\":\"1.0.0\",\"gitCommitSha\":\"$NESTED_SHA\",\"installPath\":\"$case_dir/cache/nested/1.0.0\"} + ] + } +}" +write "$case_dir/known_marketplaces.json" \ + "{\"market1\": {\"installLocation\": \"$case_dir/market\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +out=$(run_check "$case_dir" --marketplace market1) +rc=$? +assert_exit "nested sources: exit 0" 0 "$rc" +assert_eq "nested sources: both records checked" "2" "$(jq -r '.checked' <<<"$out" 2>/dev/null)" +assert_eq "nested sources: the ancestor cache that holds the nested subtree is a match" \ + "match" "$(jq -r 'first(.installs[] | select(.id == "alpha@market1") | .verdict)' <<<"$out" 2>/dev/null)" +assert_eq "nested sources: the nested plugin is a match" \ + "match" "$(jq -r 'first(.installs[] | select(.id == "nested@market1") | .verdict)' <<<"$out" 2>/dev/null)" +assert_eq "nested sources: neither is stale" "0" "$(jq -r '.stale_content' <<<"$out" 2>/dev/null)" +# Inverse: drop the nested file from the ancestor cache. Longest-match-only +# would still call that a match (the blob never joined the ancestor's tree); +# attaching it to every matching source makes the hole missing-from-cache. +rm -f "$case_dir/cache/alpha/1.0.0/nested/inner.sh" +out=$(run_check "$case_dir" --marketplace market1) +assert_eq "nested sources: an ancestor cache missing the nested file is stale-content" \ + "stale-content" "$(jq -r 'first(.installs[] | select(.id == "alpha@market1") | .verdict)' <<<"$out" 2>/dev/null)" +assert_eq "nested sources: that hole is missing-from-cache, not a cache-only extra" \ + "1 0" "$(jq -r 'first(.installs[] | select(.id == "alpha@market1") | "\(.missing_from_cache) \(.extra_in_cache)")' <<<"$out" 2>/dev/null)" +assert_eq "nested sources: the nested plugin is unaffected" \ + "match" "$(jq -r 'first(.installs[] | select(.id == "nested@market1") | .verdict)' <<<"$out" 2>/dev/null)" + # ============================================================================ # Process budget: a clean install costs a FIXED number of process creations, # never one per file. Each creation is a fork() emulation plus a CreateProcess diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh new file mode 100755 index 00000000000..dd7fdeb7a26 --- /dev/null +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh @@ -0,0 +1,1311 @@ +#!/usr/bin/env bash +# Deterministic executor for `sync`/`audit` Steps 1 through 5b, one JSON digest out. +# +# `context/sync.md` is the normative algorithm and states why each step exists. +# This script is that algorithm's executable form: it runs the whole per-marketplace +# loop in ONE process and prints a single digest the model reads, rather than the +# model retyping each step's bash into its own turn. Every invariant sync.md fixes +# holds here — per-step `fleet-state.sh` re-reads, the run journal, the +# `rc=${PIPESTATUS[0]}` capture after every `tee`-journaled mutating call, the +# downgrade guard, the projection exit-status check, the per-marketplace failure +# rule, and Step 4/5 gating on the fresh pre-install read. +# +# The one decision it cannot make is the `install_new` policy: `${user_config.*}` +# substitutes only when Claude Code renders SKILL.md, so the caller passes the +# rendered value with `--install-new`. On `ask` with a non-empty install gap the +# script reports the gap and STOPS before Step 4; the caller prompts and re-enters +# with `--only-install`. +# +# Usage: +# sync-run.sh [--marketplace | --all] --journal-root +# [--install-new all|none|ask] [--allow-downgrade] +# sync-run.sh [--marketplace | --all] --audit +# [--install-new all|none|ask] [--allow-downgrade] +# sync-run.sh --only-install --run-dir [--marketplace | --all] +# +# With neither `--marketplace` nor `--all`, the target is the default marketplace +# `fleet-state.sh` resolves dynamically from `CLAUDE_PLUGIN_ROOT`; no marketplace +# name is hardcoded anywhere in this script. `--all` runs Steps 2-5b once per +# marketplace from `fleet-state.sh --marketplaces`, and a marketplace whose +# iteration fails is recorded in that block's `errors[]` without aborting the rest. +# +# `--journal-root ` is REQUIRED in sync mode and is the run journal's parent. +# SKILL.md passes the substituted `${CLAUDE_PLUGIN_DATA}` path because that token +# resolves in skill content and not in a `context/*.md` spoke. `--audit` ignores it +# and uses a scratch directory under `${TMPDIR:-${TEMP:-.}}`, removed on exit, so an +# audit leaves nothing behind. +# +# `--only-install ` is the narrow re-entry after an `ask` prompt: a comma- or +# space-separated list of fully-qualified `@` ids to install +# (empty is legal and means install nothing), against the run directory the first +# invocation reported. It runs Step 4, the normalizer, Step 5, and the post re-read, +# reuses the cache-content report the first invocation already wrote, and re-emits +# the full digest. The cache checker therefore runs exactly ONCE per marketplace +# across both invocations. +# +# Output (stdout): one compact JSON object, also written to `/digest.json`. +# {run_dir, mode, allow_downgrade, install_new, install_new_invalid, +# marketplaces:[…], errors:[…]} +# Each marketplace block: {name, catalog_last_updated, auto_update, +# refresh:{rc,output,predicted}, project_root, in_repo:{updated,failed,would_update}, +# user_sweep:{updated,failed,would_update,withheld_downgrades}, +# downgraded, install_gap, installed, install_enable_deferred, +# stopped_before_install, enable_gap, enabled, project_enable_rows, normalize, +# cache_content, catalog_regression, divergences, divergences_here, +# in_repo_records, in_repo_ids, stale_project_records, user_scope_orphans, +# self_updated, errors} +# `in_repo_records` counts the project/local records belonging to the repo the +# run stands in, whether or not any of them moved; `stale_project_records` is +# `{total, by_path:[{path,count}]}`; `cache_content.stale[]` is +# `{id, version, files_differ}` per stale install. +# `enable_gap` is the gap the step FOUND; `enabled` is what it filled at user and +# local scope, and `project_enable_rows` is what it reports rather than writes. +# `updated` carries forward moves and unreadable-direction moves (flagged +# `direction: "unknown"`); a pair whose new version is LOWER lands in `downgraded` +# instead, which is what keeps a backward move off the report's `Updated:` line +# even for an id the guard could not prove in advance. +# Ids and counts only: the digest is read by a model in one turn, so per-file +# cache-check detail stays in `/cache-content..json`. +# +# Exit codes: +# 0 the run completed; per-marketplace and per-id failures are reported in the +# digest body, because a failed id is a finding, not a run failure +# 2 usage error, a missing prerequisite, or a run-level failure that left no +# digest to emit +# +# Env overrides (testing only; production uses the bundled siblings): +# SYNC_RUN_FLEET_STATE path to fleet-state.sh +# SYNC_RUN_CACHE_CHECK path to cache-content-check.sh +# SYNC_RUN_NORMALIZE path to normalize-enabled-plugins.sh +# SYNC_RUN_CLAUDE_BIN the `claude` CLI to invoke (default: `claude` on PATH) + +# `set -e` is deliberately absent: it would abort a `{ …; } | tee` pipeline whose +# CLI element failed before `${PIPESTATUS[0]}` is read, and that status is what +# every mutating step here branches on. +set -uo pipefail + +if ! command -v jq >/dev/null 2>&1; then + echo "ERROR: jq required (install with: winget install jqlang.jq | apt install jq | brew install jq)" >&2 + exit 2 +fi + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +FLEET_STATE="${SYNC_RUN_FLEET_STATE:-$SCRIPT_DIR/fleet-state.sh}" +CACHE_CHECK="${SYNC_RUN_CACHE_CHECK:-$SCRIPT_DIR/cache-content-check.sh}" +NORMALIZE="${SYNC_RUN_NORMALIZE:-$SCRIPT_DIR/normalize-enabled-plugins.sh}" +CLAUDE_BIN="${SYNC_RUN_CLAUDE_BIN:-claude}" + +# fleet-state.sh resolves the DEFAULT marketplace by joining CLAUDE_PLUGIN_ROOT +# against the install records, so a headless run that never had it set still gets a +# target instead of an error. This script's own location is inside the plugin root +# by construction (/skills/plugins/scripts), so it is the honest default. +export CLAUDE_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$SCRIPT_DIR/../../.." && pwd)}" + +MODE="sync" +TARGET_MP="" +ALL=0 +ALLOW_DOWNGRADE=0 +INSTALL_NEW="ask" +INSTALL_NEW_INVALID="" +JOURNAL_ROOT="" +RUN_DIR="" +ONLY_INSTALL="" +ONLY_INSTALL_MODE=0 + +usage() { + cat <<'EOF' +sync-run.sh — run `sync`/`audit` Steps 1-5b and print one JSON digest. + +Usage: + sync-run.sh [--marketplace | --all] --journal-root + [--install-new all|none|ask] [--allow-downgrade] + sync-run.sh [--marketplace | --all] --audit + [--install-new all|none|ask] [--allow-downgrade] + sync-run.sh --only-install --run-dir [--marketplace | --all] +EOF +} + +while [[ $# -gt 0 ]]; do + case "$1" in + --marketplace) + [[ $# -ge 2 ]] || { + echo "ERROR: --marketplace requires a name" >&2 + exit 2 + } + TARGET_MP="$2" + shift 2 + ;; + --all) + ALL=1 + shift + ;; + --audit) + MODE="audit" + shift + ;; + --allow-downgrade) + ALLOW_DOWNGRADE=1 + shift + ;; + --install-new) + [[ $# -ge 2 ]] || { + echo "ERROR: --install-new requires a value" >&2 + exit 2 + } + INSTALL_NEW="$2" + shift 2 + ;; + --journal-root) + [[ $# -ge 2 ]] || { + echo "ERROR: --journal-root requires a directory" >&2 + exit 2 + } + JOURNAL_ROOT="$2" + shift 2 + ;; + --run-dir) + [[ $# -ge 2 ]] || { + echo "ERROR: --run-dir requires a directory" >&2 + exit 2 + } + RUN_DIR="$2" + shift 2 + ;; + --only-install) + [[ $# -ge 2 ]] || { + echo "ERROR: --only-install requires an id list (an empty string is legal)" >&2 + exit 2 + } + ONLY_INSTALL="$2" + ONLY_INSTALL_MODE=1 + shift 2 + ;; + -h | --help) + usage + exit 0 + ;; + *) + echo "ERROR: unknown argument: $1" >&2 + usage >&2 + exit 2 + ;; + esac +done + +if ((ALL == 1)) && [[ -n "$TARGET_MP" ]]; then + echo "ERROR: --all cannot be combined with --marketplace" >&2 + exit 2 +fi + +# An unsupported value becomes the default and is NAMED in the digest, the rule +# SKILL.md states for the rendered option: a policy the caller thought it set must +# never disappear silently. +case "$INSTALL_NEW" in +all | none | ask) ;; +*) + INSTALL_NEW_INVALID="$INSTALL_NEW" + INSTALL_NEW="ask" + ;; +esac + +if ((ONLY_INSTALL_MODE == 1)); then + if [[ -z "$RUN_DIR" ]]; then + echo "ERROR: --only-install requires --run-dir (the run it re-enters)" >&2 + exit 2 + fi + if [[ ! -d "$RUN_DIR" ]]; then + echo "ERROR: --run-dir is not a directory: $RUN_DIR" >&2 + exit 2 + fi + if [[ "$MODE" == "audit" ]]; then + echo "ERROR: --only-install is a sync-mode re-entry; audit installs nothing" >&2 + exit 2 + fi +elif [[ "$MODE" == "sync" && -z "$JOURNAL_ROOT" ]]; then + echo "ERROR: --journal-root is required in sync mode" >&2 + echo " SKILL.md passes the substituted \${CLAUDE_PLUGIN_DATA} journal path;" >&2 + echo " a context/*.md spoke is read raw and cannot substitute it." >&2 + exit 2 +fi + +# --- jq capture --------------------------------------------------------------- +# Some native-Windows jq builds CRLF-terminate every line, including single-line +# compact output. `$(...)` strips only the trailing LF, so a stray CR survives at +# the end of a captured value and corrupts it once re-parsed as JSON, and every id +# but the last in a line-oriented output arrives as `@\r`. Every +# jq call goes through this helper, which strips ALL carriage returns in the shell +# and stores the result in the named variable. +jq_to() { + local __jq_var="$1" + shift + local __jq_out __jq_rc=0 + __jq_out=$(command jq "$@") || __jq_rc=$? + printf -v "$__jq_var" '%s' "${__jq_out//$'\r'/}" + return "$__jq_rc" +} + +# JSON array of the non-empty lines of a file, CR-stripped. Used for every id list +# in the digest, so a `\r` can never ride into a report row or a later CLI call. +json_lines() { + local __var="$1" __file="$2" + if [[ ! -f "$__file" ]]; then + printf -v "$__var" '%s' '[]' + return 0 + fi + jq_to "$__var" -R -s -c 'gsub("\r"; "") | split("\n") | map(select(length > 0))' <"$__file" +} + +# JSON array literal from the shell array named by $2, empty array included. +json_array_of() { + local __var="$1" + shift + if (($# == 0)); then + printf -v "$__var" '%s' '[]' + return 0 + fi + jq_to "$__var" -c -s '.' <<<"$(printf '%s\n' "$@")" +} + +RUN_ERRORS=() +MP_ERRORS=() + +run_error() { RUN_ERRORS+=("$1"); } +mp_error() { MP_ERRORS+=("$1"); } + +# --- version direction --------------------------------------------------------- +# The same major.minor.patch triple compare the downgrade guard uses. Anything that +# does not parse on both sides is "unknown", never silently ranked: an unrankable +# pair is reported as such rather than assumed forward. +version_direction() { + local old="$1" new="$2" + local ore ore_ok=0 nre_ok=0 + local o1 o2 o3 n1 n2 n3 + if [[ "$old" =~ ^v?([0-9]+)\.([0-9]+)\.([0-9]+) ]]; then + o1=${BASH_REMATCH[1]} + o2=${BASH_REMATCH[2]} + o3=${BASH_REMATCH[3]} + ore_ok=1 + fi + if [[ "$new" =~ ^v?([0-9]+)\.([0-9]+)\.([0-9]+) ]]; then + n1=${BASH_REMATCH[1]} + n2=${BASH_REMATCH[2]} + n3=${BASH_REMATCH[3]} + nre_ok=1 + fi + ore="$ore_ok$nre_ok" + if [[ "$ore" != "11" ]]; then + echo "unknown" + return 0 + fi + if ((n1 > o1)) || { ((n1 == o1)) && ((n2 > o2)); } || + { ((n1 == o1)) && ((n2 == o2)) && ((n3 > o3)); }; then + echo "forward" + elif ((n1 < o1)) || { ((n1 == o1)) && ((n2 < o2)); } || + { ((n1 == o1)) && ((n2 == o2)) && ((n3 < o3)); }; then + echo "backward" + else + # Triples tie while the strings differ (`1.2.3` vs `1.2.3-beta`): the compare + # cannot rank a suffix, so the pair is unknown rather than forward. + if [[ "$old" == "$new" ]]; then echo "same"; else echo "unknown"; fi + fi +} + +# That id's version in a saved fleet-state report, at that scope. Empty when the +# report does not carry the record. +version_at() { + local __var="$1" report="$2" id="$3" scope="$4" + # shellcheck disable=SC2016 # a jq program: every $var is a jq variable + jq_to "$__var" -r --arg id "$id" --arg sc "$scope" \ + 'first(.installed[]? | select(.id == $id and .scope == $sc) | .version) // ""' "$report" +} + +# --- journaled mutation -------------------------------------------------------- +# The canonical shape from sync.md's "Run journal": the call and its output are +# appended to journal.log through `tee`, and `${PIPESTATUS[0]}` is read as the very +# next statement. A pipeline's own `$?` is `tee`'s status, and `tee` succeeds +# whenever it can write the log, so without this capture a failed CLI call journals +# its own error text and is then read as a success. +CLI_OUT="" +CLI_RC=0 +run_cli() { + local label="$1" + shift + local sink="$RUN_DIR/.last-cli-out" + { echo "\$ $label"; "$CLAUDE_BIN" "$@" 2>&1; } | tee -a "$JOURNAL_LOG" >"$sink" + CLI_RC=${PIPESTATUS[0]} + CLI_OUT=$(<"$sink") + CLI_OUT="${CLI_OUT//$'\r'/}" +} + +# audit's stand-in for run_cli: journals the prediction, issues nothing. +predict_cli() { + local label="$1" + echo "would run: $label" >>"$JOURNAL_LOG" + CLI_RC=0 + CLI_OUT="would run: $label" +} + +# `` from the CLI's own line, which is the only source that reflects an update +# immediately (sync.md's source 2). Empty when the line names no version. +cli_reported_version() { + local __var="$1" text="$2" + if [[ "$text" =~ updated\ from\ ([^[:space:]]+)\ to\ ([^[:space:]]+) ]]; then + printf -v "$__var" '%s' "${BASH_REMATCH[2]}" + else + printf -v "$__var" '%s' "" + fi +} + +# What the CLI said it did, classified at capture time, because the outcome is not +# recoverable later: an id the CLI reported as ALREADY CURRENT and an id whose +# update the state write has not landed for both read as "no version change" from a +# post-sweep snapshot. Reporting the first as an update with an unknown version +# would put most of an already-current fleet under `Updated:`. +# updated the CLI named a version pair +# noop the CLI said the id is already at the latest version +# other the CLI named neither; the post-sweep read decides +cli_move_result() { + local __var="$1" text="$2" + case "$text" in + *"updated from"*) printf -v "$__var" '%s' "updated" ;; + *"already at the latest version"*) printf -v "$__var" '%s' "noop" ;; + *) printf -v "$__var" '%s' "other" ;; + esac +} + +# --- projection ---------------------------------------------------------------- +# Redirect the selector to a file and hand back the exit status. An empty +# projection is ambiguous: every `--from` rejection exits 2 with EMPTY stdout so a +# failure can never reach the CLI as an id, which makes the status the only thing +# that tells "nothing to do" from "the projection failed". +project_ids() { + local selector="$1" from="$2" out="$3" + "$FLEET_STATE" --ids "$selector" --from "$from" >"$out" 2>"$RUN_DIR/.proj-err" + return $? +} + +# The digest is read by a model in one turn, so no single field may run away with +# the window. Output is kept, bounded. +trunc() { + local __var="$1" text="$2" max="${3:-400}" + if ((${#text} > max)); then + printf -v "$__var" '%s' "${text:0:max}…" + else + printf -v "$__var" '%s' "$text" + fi +} + +# The selector's stderr, bounded HERE rather than at each call site: every caller +# embeds it in a digest string, so the truncation belongs to the reader and not to +# any one message. +proj_err() { + local text="" bounded="" + [[ -f "$RUN_DIR/.proj-err" ]] && text=$(<"$RUN_DIR/.proj-err") + trunc bounded "${text//$'\r'/}" + printf '%s' "$bounded" +} + +# --- run directory ------------------------------------------------------------- +# `mktemp -d`, never a bare `mkdir -p` on the timestamp: the stamp has one-second +# resolution, so two runs started in the same second compute the same path, +# `mkdir -p` succeeds for both, and their snapshots overwrite each other. +setup_run_dir() { + if ((ONLY_INSTALL_MODE == 1)); then + JOURNAL_LOG="$RUN_DIR/journal.log" + return 0 + fi + if [[ "$MODE" == "audit" ]]; then + # `${TMPDIR:-${TEMP:-.}}` and never a hardcoded POSIX temp literal: on Windows + # that literal is resolved by a native consumer against the current drive root. + RUN_DIR=$(mktemp -d "${TMPDIR:-${TEMP:-.}}/plugins-audit.XXXXXX") || { + echo "ERROR: could not create the audit scratch directory" >&2 + exit 2 + } + AUDIT_SCRATCH="$RUN_DIR" + trap 'rm -rf "$AUDIT_SCRATCH"' EXIT + else + mkdir -p "$JOURNAL_ROOT" 2>/dev/null + RUN_DIR=$(mktemp -d "$JOURNAL_ROOT/$(date -u +%Y%m%dT%H%M%SZ).XXXXXX") || { + echo "ERROR: could not create a run directory under: $JOURNAL_ROOT" >&2 + exit 2 + } + fi + JOURNAL_LOG="$RUN_DIR/journal.log" + : >"$JOURNAL_LOG" +} + +# --- own plugin name ----------------------------------------------------------- +# Step 3 sweeps every user-scope id, which necessarily includes the plugin +# providing this skill. Read the name from the manifest rather than hardcoding it, +# for the same reason no marketplace name is hardcoded. +own_plugin_name() { + local manifest="$CLAUDE_PLUGIN_ROOT/.claude-plugin/plugin.json" name="" + [[ -f "$manifest" ]] && jq_to name -r '.name // ""' "$manifest" 2>/dev/null + printf '%s' "$name" +} + +# --- catalog regression -------------------------------------------------------- +# Diff `catalog_versions` across consecutive saved snapshots and report the FIRST +# interval in which any id moved backward. That interval is what names the cause: +# in `sync` a regression across pre-refresh→pre is this run's refresh pulling a +# source that moved backward, while one appearing later is the checkout changing +# under the run. REPORT-ONLY — its output never becomes an id list handed to a CLI. +catalog_regression_rows() { + local __interval_var="$1" __rows_var="$2" mp="$3" + local snaps=(pre-refresh pre mid post) + local i a b rows="" + printf -v "$__interval_var" '%s' "" + printf -v "$__rows_var" '%s' "[]" + for ((i = 0; i + 1 < ${#snaps[@]}; i++)); do + a="$RUN_DIR/${snaps[i]}.$mp.json" + b="$RUN_DIR/${snaps[i + 1]}.$mp.json" + [[ -f "$a" && -f "$b" ]] || continue + # shellcheck disable=SC2016 # a jq program: every $var is a jq variable + jq_to rows -c --slurpfile a "$a" --slurpfile b "$b" -n ' + def triple: + if type == "string" then + ((capture("^v?(?[0-9]+)[.](?[0-9]+)[.](?[0-9]+)") // null) + | if . == null then null else [.x, .y, .z] | map(tonumber) end) + else null end; + ($a[0].catalog_versions // {}) as $before | ($b[0].catalog_versions // {}) as $after + | [$before | to_entries[] + | select((.value | triple) != null and ($after[.key] | triple) != null + and ($after[.key] | triple) < (.value | triple)) + | "\(.key) \(.value) \($after[.key])"]' || continue + if [[ -n "$rows" && "$rows" != "[]" ]]; then + printf -v "$__interval_var" '%s' "${snaps[i]}→${snaps[i + 1]}" + printf -v "$__rows_var" '%s' "$rows" + return 0 + fi + done + return 0 +} + +# --- divergence attribution ---------------------------------------------------- +# Three snapshots, not two: Steps 2 and 3 both mutate versions, so a single +# pre/post bracket cannot tell which step created a new actionable divergence, and +# labelling the whole delta "the user-scope sweep" is wrong whenever Step 2 caused +# it. Only `versionsMatch: false` rows are actionable; a same-version multi-scope +# install is benign and is never counted. +divergence_block() { + local __var="$1" mp="$2" + local pre="$RUN_DIR/pre.$mp.json" mid="$RUN_DIR/mid.$mp.json" post="$RUN_DIR/post.$mp.json" + if [[ ! -f "$pre" || ! -f "$mid" || ! -f "$post" ]]; then + jq_to "$__var" -c -n '{pre: null, mid: null, post: null, new_total: null, + new_by_interval: {in_repo: null, user_sweep: null}, pre_existing: null, + note: "a snapshot was missing; the split could not be computed"}' + return 0 + fi + # shellcheck disable=SC2016 # a jq program: every $var is a jq variable + jq_to "$__var" -c -n \ + --slurpfile p "$pre" --slurpfile m "$mid" --slurpfile q "$post" ' + def act: [.divergences[]? | select(.versionsMatch == false) | .id]; + ($p[0] | act) as $pre | ($m[0] | act) as $mid | ($q[0] | act) as $post + | ($post - $pre) as $new + | {pre: ($pre | length), mid: ($mid | length), post: ($post | length), + new_total: ($new | length), + new_by_interval: {in_repo: ([$new[] | select(. as $i | $mid | index($i))] | length), + user_sweep: ([$new[] | select(. as $i | $mid | index($i) | not)] | length)}, + pre_existing: (($post | length) - ($new | length))}' +} + +# --- per-marketplace accumulators ---------------------------------------------- +# Script-scope rather than `local`, because the step helpers below append to them +# and a `local` array is invisible to a function the step calls. +IR_UPDATED=() IR_FAILED=() IR_WOULD=() +US_UPDATED=() US_FAILED=() US_WOULD=() +WITHHELD=() DOWNGRADED=() INSTALLED_ROWS=() ENABLED_ROWS=() PROJECT_ROWS=() +INSTALL_GAP="[]" ENABLE_GAP="[]" NORMALIZE_JSON="null" CACHE_JSON="null" +SELF_UPDATED="false" INSTALL_DEFERRED="false" STOPPED_BEFORE_INSTALL="false" +REFRESH_RC="null" REFRESH_OUT="" REFRESH_PREDICTED="false" REFRESH_FAILED=0 +CATALOG_LAST_UPDATED="" PROJECT_ROOT_JSON="null" + +reset_marketplace_state() { + MP_ERRORS=() + IR_UPDATED=() IR_FAILED=() IR_WOULD=() + US_UPDATED=() US_FAILED=() US_WOULD=() + WITHHELD=() DOWNGRADED=() INSTALLED_ROWS=() ENABLED_ROWS=() PROJECT_ROWS=() + INSTALL_GAP="[]" ENABLE_GAP="[]" NORMALIZE_JSON="null" CACHE_JSON="null" + SELF_UPDATED="false" INSTALL_DEFERRED="false" STOPPED_BEFORE_INSTALL="false" + REFRESH_RC="null" REFRESH_OUT="" REFRESH_PREDICTED="false" REFRESH_FAILED=0 + CATALOG_LAST_UPDATED="" PROJECT_ROOT_JSON="null" +} + +# First-pass result rows that live only in these arrays. Successful moves ride +# `moves..tsv` and withheld downgrades ride `downgrades..txt`, so an +# `--only-install` re-entry can rebuild those; a failed update or a projection +# error has no other store. Without this sidecar the replacement digest drops +# them and a run that left a plugin stale can report as a successful sync. +persist_first_pass_rows() { + local mp="$1" ir_f us_f errs persisted + json_array_of ir_f ${IR_FAILED[@]+"${IR_FAILED[@]}"} + json_array_of us_f ${US_FAILED[@]+"${US_FAILED[@]}"} + if ((${#MP_ERRORS[@]} == 0)); then + errs='[]' + else + jq_to errs -c -R -s 'split("\n") | map(select(length > 0))' <<<"$(printf '%s\n' "${MP_ERRORS[@]}")" + fi + # shellcheck disable=SC2016 # a jq program: every $var is a jq variable + jq_to persisted -c -n \ + --argjson errors "$errs" \ + --argjson ir_failed "$ir_f" \ + --argjson us_failed "$us_f" \ + --arg refresh_rc "$REFRESH_RC" \ + --arg refresh_out "$REFRESH_OUT" \ + --arg refresh_predicted "$REFRESH_PREDICTED" \ + '{errors: $errors, ir_failed: $ir_failed, us_failed: $us_failed, + refresh: {rc: (if $refresh_rc == "null" or $refresh_rc == "" then null + else ($refresh_rc | tonumber? // $refresh_rc) end), + output: $refresh_out, + predicted: ($refresh_predicted == "true")}}' + printf '%s\n' "$persisted" >"$RUN_DIR/first-pass.$mp.json" +} + +restore_first_pass_rows() { + local mp="$1" + local sidecar="$RUN_DIR/first-pass.$mp.json" lines line + [[ -f "$sidecar" ]] || return 0 + jq_to lines -r '.errors[]?' "$sidecar" + while IFS= read -r line; do + [[ -n "$line" ]] && MP_ERRORS+=("$line") + done <<<"$lines" + jq_to lines -c '.ir_failed[]?' "$sidecar" + while IFS= read -r line; do + [[ -n "$line" ]] && IR_FAILED+=("$line") + done <<<"$lines" + jq_to lines -c '.us_failed[]?' "$sidecar" + while IFS= read -r line; do + [[ -n "$line" ]] && US_FAILED+=("$line") + done <<<"$lines" + # Digest fields only. `REFRESH_FAILED` stays 0 so the re-entry can still run + # Steps 4 and 5: that flag is the first-pass defer gate, and restoring it + # would skip the install the caller just confirmed. + jq_to REFRESH_OUT -r '.refresh.output // ""' "$sidecar" + jq_to REFRESH_PREDICTED -r 'if .refresh.predicted == true then "true" else "false" end' "$sidecar" + jq_to REFRESH_RC -r 'if .refresh.rc == null then "null" else (.refresh.rc | tostring) end' "$sidecar" +} + +# --- the per-marketplace loop body (Steps 2-5b, plus Step 1's own refresh) ------- +run_marketplace() { + local mp="$1" + reset_marketplace_state + # The `--only-install` re-entry APPENDS to the same move ledger. Truncating it + # would drop the sweep's ` → ` pairs from the digest that supersedes + # the first one, and the report would then show an empty `Updated:` for a run + # that updated plugins. + ((ONLY_INSTALL_MODE == 1)) || : >"$RUN_DIR/moves.$mp.tsv" + + local rc dg_rc id scope old new result row text out + + local pre_refresh="$RUN_DIR/pre-refresh.$mp.json" + + # ---- Step 1 — marketplace refresh ------------------------------------------- + # The snapshot is a READ and both actions take it: it is the earliest link in the + # catalog regression check's chain, and an action that skips it starts that check + # at `pre` and loses the interval that isolates the refresh point. + if ((ONLY_INSTALL_MODE == 0)); then + if [[ ! -f "$pre_refresh" ]]; then + "$FLEET_STATE" --marketplace "$mp" >"$pre_refresh" 2>"$RUN_DIR/.fs-err" + rc=$? + if ((rc != 0)); then + text=$(<"$RUN_DIR/.fs-err") + mp_error "pre-refresh fleet-state read failed (exit $rc): ${text//$'\r'/}" + emit_marketplace_block "$mp" + return 0 + fi + fi + jq_to CATALOG_LAST_UPDATED -r '.marketplace.lastUpdated // ""' "$pre_refresh" + + if [[ "$MODE" == "audit" ]]; then + predict_cli "claude plugin marketplace update $mp" + REFRESH_PREDICTED="true" + REFRESH_RC="null" + trunc REFRESH_OUT "$CLI_OUT" + else + run_cli "claude plugin marketplace update $mp" plugin marketplace update "$mp" + REFRESH_RC="$CLI_RC" + trunc REFRESH_OUT "$CLI_OUT" + if ((CLI_RC != 0)); then + REFRESH_FAILED=1 + mp_error "marketplace refresh failed (exit $CLI_RC); catalog may be stale, install/enable maintenance deferred" + fi + fi + else + # The re-entry reports the whole run, so the fields Steps 1-3 filled come back + # off their saved snapshots rather than reading as absent. + [[ -f "$pre_refresh" ]] && jq_to CATALOG_LAST_UPDATED -r '.marketplace.lastUpdated // ""' "$pre_refresh" + if [[ -f "$RUN_DIR/pre.$mp.json" ]]; then + jq_to PROJECT_ROOT_JSON -c '.project_root' "$RUN_DIR/pre.$mp.json" + [[ -n "$PROJECT_ROOT_JSON" ]] || PROJECT_ROOT_JSON="null" + fi + if ((ALLOW_DOWNGRADE == 0)) && [[ -f "$RUN_DIR/downgrades.$mp.txt" ]]; then + while IFS=$'\t' read -r id scope old new; do + id="${id//$'\r'/}" + [[ -n "$id" ]] || continue + WITHHELD+=("$(jq -c -n --arg id "$id" --arg sc "${scope//$'\r'/}" \ + --arg o "${old//$'\r'/}" --arg n "${new//$'\r'/}" \ + '{id: $id, scope: $sc, installed: $o, catalog: $n}')") + done <"$RUN_DIR/downgrades.$mp.txt" + fi + restore_first_pass_rows "$mp" + fi + + # ---- Step 2 — in-repo update (the primary value path) ------------------------ + if ((ONLY_INSTALL_MODE == 0)); then + "$FLEET_STATE" --marketplace "$mp" >"$RUN_DIR/pre.$mp.json" 2>"$RUN_DIR/.fs-err" + rc=$? + if ((rc != 0)); then + text=$(<"$RUN_DIR/.fs-err") + mp_error "pre fleet-state read failed (exit $rc): ${text//$'\r'/}" + emit_marketplace_block "$mp" + return 0 + fi + jq_to PROJECT_ROOT_JSON -c '.project_root' "$RUN_DIR/pre.$mp.json" + [[ -n "$PROJECT_ROOT_JSON" ]] || PROJECT_ROOT_JSON="null" + + project_ids update-candidates-project "$RUN_DIR/pre.$mp.json" "$RUN_DIR/ids.pre.$mp.txt" + rc=$? + if ((rc != 0)); then + # exit 2 with empty output is a FAILED projection, never "nothing in-repo". + mp_error "in-repo projection failed (exit $rc), step not run: $(proj_err)" + else + while IFS=$'\t' read -r id scope; do + id="${id//$'\r'/}" + scope="${scope//$'\r'/}" + [[ -n "$id" ]] || continue + version_at old "$RUN_DIR/pre.$mp.json" "$id" "$scope" + if [[ "$MODE" == "audit" ]]; then + predict_cli "claude plugin update $id -s $scope" + IR_WOULD+=("$(jq -c -n --arg id "$id" --arg sc "$scope" --arg old "$old" \ + '{id: $id, scope: $sc, installed: $old}')") + continue + fi + run_cli "claude plugin update $id -s $scope" plugin update "$id" -s "$scope" + if ((CLI_RC != 0)); then + trunc out "$CLI_OUT" + IR_FAILED+=("$(jq -c -n --arg id "$id" --arg sc "$scope" --argjson rc "$CLI_RC" \ + --arg out "$out" '{id: $id, scope: $sc, rc: $rc, output: $out}')") + continue + fi + cli_reported_version new "$CLI_OUT" + cli_move_result result "$CLI_OUT" + printf 'in_repo\t%s\t%s\t%s\t%s\t%s\n' "$id" "$scope" "${old:--}" "${new:--}" "$result" \ + >>"$RUN_DIR/moves.$mp.tsv" + done <"$RUN_DIR/ids.pre.$mp.txt" + fi + fi + + # ---- Step 3 — user-scope update sweep ---------------------------------------- + if ((ONLY_INSTALL_MODE == 0)); then + "$FLEET_STATE" --marketplace "$mp" >"$RUN_DIR/mid.$mp.json" 2>"$RUN_DIR/.fs-err" + rc=$? + if ((rc != 0)); then + text=$(<"$RUN_DIR/.fs-err") + mp_error "mid fleet-state read failed (exit $rc): ${text//$'\r'/}" + emit_marketplace_block "$mp" + return 0 + fi + + project_ids downgrade-candidates "$RUN_DIR/mid.$mp.json" "$RUN_DIR/downgrades.$mp.txt" + dg_rc=$? + if ((dg_rc != 0)); then + # An unchecked failed downgrade projection reads as "no downgrades", which is + # the guard reporting an all-clear it never established. + mp_error "downgrade projection failed (exit $dg_rc): $(proj_err)" + : >"$RUN_DIR/downgrades.$mp.txt" + fi + + project_ids update-candidates-user "$RUN_DIR/mid.$mp.json" "$RUN_DIR/ids.mid.$mp.txt" + rc=$? + if ((rc != 0)); then + mp_error "user-scope projection failed (exit $rc), sweep not run: $(proj_err)" + else + while IFS= read -r id; do + id="${id//$'\r'/}" + [[ -n "$id" ]] || continue + version_at old "$RUN_DIR/mid.$mp.json" "$id" user + if [[ "$MODE" == "audit" ]]; then + predict_cli "claude plugin update $id -s user" + US_WOULD+=("$(jq -c -n --arg id "$id" --arg old "$old" '{id: $id, installed: $old}')") + continue + fi + run_cli "claude plugin update $id -s user" plugin update "$id" -s user + if ((CLI_RC != 0)); then + trunc out "$CLI_OUT" + US_FAILED+=("$(jq -c -n --arg id "$id" --argjson rc "$CLI_RC" --arg out "$out" \ + '{id: $id, rc: $rc, output: $out}')") + continue + fi + cli_reported_version new "$CLI_OUT" + cli_move_result result "$CLI_OUT" + printf 'user_sweep\t%s\t%s\t%s\t%s\t%s\n' "$id" user "${old:--}" "${new:--}" "$result" \ + >>"$RUN_DIR/moves.$mp.tsv" + done <"$RUN_DIR/ids.mid.$mp.txt" + fi + + # The withheld set. `--allow-downgrade` is the operator's explicit opt-in; without + # it a proven downgrade is reported and never issued. + while IFS=$'\t' read -r id scope old new; do + id="${id//$'\r'/}" + [[ -n "$id" ]] || continue + scope="${scope//$'\r'/}" + old="${old//$'\r'/}" + new="${new//$'\r'/}" + if ((ALLOW_DOWNGRADE == 1)) && [[ "$MODE" == "sync" ]]; then + run_cli "claude plugin update $id -s $scope # downgrade $old -> $new" \ + plugin update "$id" -s "$scope" + if ((CLI_RC != 0)); then + trunc out "$CLI_OUT" + US_FAILED+=("$(jq -c -n --arg id "$id" --argjson rc "$CLI_RC" --arg out "$out" \ + '{id: $id, rc: $rc, output: $out}')") + continue + fi + # Through the move ledger like every other mutation, so the direction + # compare is the one that decides where it renders and the row survives an + # `--only-install` re-entry. + local applied="" + cli_reported_version applied "$CLI_OUT" + [[ -n "$applied" ]] || applied="$new" + printf 'user_sweep\t%s\t%s\t%s\t%s\t%s\n' "$id" "$scope" "${old:--}" "${applied:--}" updated \ + >>"$RUN_DIR/moves.$mp.tsv" + else + WITHHELD+=("$(jq -c -n --arg id "$id" --arg sc "$scope" --arg o "$old" --arg n "$new" \ + '{id: $id, scope: $sc, installed: $o, catalog: $n}')") + fi + done <"$RUN_DIR/downgrades.$mp.txt" + fi + + # ---- Steps 4 and 5 — install and enable, gated on the FRESH pre-install read --- + "$FLEET_STATE" --marketplace "$mp" >"$RUN_DIR/pre-install.$mp.json" 2>"$RUN_DIR/.fs-err" + rc=$? + if ((rc != 0)); then + text=$(<"$RUN_DIR/.fs-err") + mp_error "pre-install fleet-state read failed (exit $rc): ${text//$'\r'/}" + else + project_ids missing-user-install "$RUN_DIR/pre-install.$mp.json" "$RUN_DIR/ids.pre-install.$mp.txt" + rc=$? + if ((rc != 0)); then + mp_error "install-gap projection failed (exit $rc), Step 4 not run: $(proj_err)" + else + json_lines INSTALL_GAP "$RUN_DIR/ids.pre-install.$mp.txt" + fi + project_ids missing-enabled "$RUN_DIR/pre-install.$mp.json" "$RUN_DIR/ids.gap-enable.$mp.txt" + rc=$? + if ((rc != 0)); then + mp_error "enable-gap projection failed (exit $rc): $(proj_err)" + else + json_lines ENABLE_GAP "$RUN_DIR/ids.gap-enable.$mp.txt" + fi + fi + + local gap_count enable_gap_count + jq_to gap_count -r 'length' <<<"$INSTALL_GAP" + jq_to enable_gap_count -r 'length' <<<"$ENABLE_GAP" + + if ((REFRESH_FAILED == 1)); then + # Step 4 derives installations from the catalog and Step 5 consults catalog + # metadata, so an unrefreshed checkout can install a since-removed plugin or + # enable one the publisher has made opt-in-only. Defer both and report. + INSTALL_DEFERRED="true" + elif [[ "$MODE" == "sync" && "$INSTALL_NEW" == "ask" ]] && ((gap_count > 0)) && ((ONLY_INSTALL_MODE == 0)); then + # The `ask` policy needs a human, and only the caller can prompt. Report the gap + # and stop before Step 4; the caller re-enters with `--only-install`. + STOPPED_BEFORE_INSTALL="true" + elif ((gap_count > 0)) || ((enable_gap_count > 0)) || ((ONLY_INSTALL_MODE == 1)); then + # Both arrays are empty on an already-current fleet, and then Steps 4 and 5 are + # no-ops with nothing to read: the same gate that keeps the spoke unloaded. + run_install_step "$mp" "$gap_count" + run_enable_step "$mp" + fi + + # ---- Step 5b — cache content check, exactly once per marketplace --------------- + cache_content_block "$mp" + + # ---- post re-read, then the report inputs Step 6 reads back -------------------- + "$FLEET_STATE" --marketplace "$mp" >"$RUN_DIR/post.$mp.json" 2>"$RUN_DIR/.fs-err" + rc=$? + if ((rc != 0)); then + text=$(<"$RUN_DIR/.fs-err") + mp_error "post fleet-state read failed (exit $rc): ${text//$'\r'/}" + fi + + finalize_moves "$mp" + + local own + own=$(own_plugin_name) + if [[ -n "$own" ]]; then + # Every scope, not just the user sweep: a project/local `claude-ops` record + # Step 2 moved is the same self-update, and the running algorithm is just as + # stale for it. + for row in ${IR_UPDATED[@]+"${IR_UPDATED[@]}"} ${US_UPDATED[@]+"${US_UPDATED[@]}"} \ + ${DOWNGRADED[@]+"${DOWNGRADED[@]}"}; do + case "$row" in + *"\"id\":\"$own@"*) SELF_UPDATED="true" ;; + *) ;; + esac + done + fi + + emit_marketplace_block "$mp" +} + +# --- Step 4 — install new catalog plugins, per the caller's rendered policy ------- +run_install_step() { + local mp="$1" gap_count="$2" + local id out installed_any=0 wanted="" + + if ((ONLY_INSTALL_MODE == 1)); then + # The narrow re-entry installs exactly the ids the caller's prompt returned, + # scoped to this marketplace by the id's own `@` suffix. + wanted=$(printf '%s' "${ONLY_INSTALL//,/ }") + for id in $wanted; do + [[ "$id" == *"@$mp" ]] || continue + run_cli "claude plugin install $id -s user" plugin install "$id" -s user + trunc out "$CLI_OUT" + INSTALLED_ROWS+=("$(jq -c -n --arg id "$id" --argjson rc "$CLI_RC" --arg out "$out" \ + '{id: $id, rc: $rc, output: $out}')") + ((CLI_RC == 0)) && installed_any=1 + done + elif ((gap_count > 0)) && [[ "$INSTALL_NEW" == "all" ]]; then + while IFS= read -r id; do + id="${id//$'\r'/}" + [[ -n "$id" ]] || continue + if [[ "$MODE" == "audit" ]]; then + predict_cli "claude plugin install $id -s user" + installed_any=1 + continue + fi + run_cli "claude plugin install $id -s user" plugin install "$id" -s user + trunc out "$CLI_OUT" + INSTALLED_ROWS+=("$(jq -c -n --arg id "$id" --argjson rc "$CLI_RC" --arg out "$out" \ + '{id: $id, rc: $rc, output: $out}')") + ((CLI_RC == 0)) && installed_any=1 + done <"$RUN_DIR/ids.pre-install.$mp.txt" + fi + + # The reorder heals the unsorted tail an install just created, so it runs only + # when this step installed something. `audit` predicts it with `--check`, which + # writes nothing. + ((installed_any == 1)) || return 0 + local nrc=0 nout="" + if [[ "$MODE" == "audit" ]]; then + nout=$("$NORMALIZE" --check 2>&1) || nrc=$? + else + nout=$("$NORMALIZE" 2>&1) || nrc=$? + fi + trunc nout "${nout//$'\r'/}" 200 + + # The project-scope map is INSPECTED and never rewritten: `project-unsorted` is a + # report row, and `converge` remains the only action that may touch that file. + local prc=0 pout="" proot="" + jq_to proot -r '. // ""' <<<"$PROJECT_ROOT_JSON" + if [[ -n "$proot" && -f "$proot/.claude/settings.json" ]]; then + pout=$("$NORMALIZE" --report-project "$proot/.claude/settings.json" 2>&1) || prc=$? + trunc pout "${pout//$'\r'/}" 200 + fi + + # shellcheck disable=SC2016 # a jq program: every $var is a jq variable + jq_to NORMALIZE_JSON -c -n --argjson rc "$nrc" --arg out "$nout" --arg mode "$MODE" \ + --argjson prc "$prc" --arg pout "$pout" \ + '{rc: $rc, output: $out, checked_only: ($mode == "audit"), + project_report: (if $pout == "" then null else {rc: $prc, output: $pout} end)}' +} + +# --- Step 5 — enabledPlugins completeness ---------------------------------------- +# Its own live re-read: Step 4 mutated in between (it installs, and it normalizes the +# user-scope map), so the pre-install report no longer describes the state this step +# acts on. +run_enable_step() { + local mp="$1" rc id row has_user has_local has_project ppath + + "$FLEET_STATE" --marketplace "$mp" >"$RUN_DIR/pre-enable.$mp.json" 2>"$RUN_DIR/.fs-err" + rc=$? + if ((rc != 0)); then + mp_error "pre-enable fleet-state read failed (exit $rc), Step 5 not run" + return 0 + fi + + project_ids missing-enabled "$RUN_DIR/pre-enable.$mp.json" "$RUN_DIR/ids.pre-enable.$mp.txt" + rc=$? + if ((rc != 0)); then + mp_error "enable projection failed (exit $rc), Step 5 not run: $(proj_err)" + return 0 + fi + json_lines ENABLE_GAP "$RUN_DIR/ids.pre-enable.$mp.txt" + + while IFS= read -r id; do + id="${id//$'\r'/}" + [[ -n "$id" ]] || continue + # shellcheck disable=SC2016 # a jq program: every $var is a jq variable + jq_to row -r --arg id "$id" ' + [.installed[]? | select(.id == $id)] as $r + | [(any($r[]; .scope == "user") | tostring), + (any($r[]; .scope == "local" and .currentProject == true) | tostring), + (any($r[]; .scope == "project" and .currentProject == true) | tostring), + (first($r[] | select(.scope == "project" and .currentProject == true) | .projectPath) // "")] + | @tsv' "$RUN_DIR/pre-enable.$mp.json" + IFS=$'\t' read -r has_user has_local has_project ppath <<<"$row" + + local enabled_here=0 + if [[ "$has_user" == "true" ]]; then + enable_one "$id" user + enabled_here=1 + fi + if [[ "$has_local" == "true" ]]; then + enable_one "$id" local + enabled_here=1 + fi + # `sync` never writes a committed settings file, so a project-scope gap is + # reported with its runnable command instead of enabled. Suppressed for an id + # this run already enabled at user or local scope: `enable -s project` gates on + # the merged effective value, so the reported command would fail. + if [[ "$has_project" == "true" ]] && ((enabled_here == 0)); then + PROJECT_ROWS+=("$(jq -c -n --arg id "$id" --arg p "$ppath" '{id: $id, project_path: $p}')") + fi + done <"$RUN_DIR/ids.pre-enable.$mp.txt" +} + +enable_one() { + local id="$1" scope="$2" out + if [[ "$MODE" == "audit" ]]; then + predict_cli "claude plugin enable $id -s $scope" + ENABLED_ROWS+=("$(jq -c -n --arg id "$id" --arg sc "$scope" \ + '{id: $id, scope: $sc, rc: null, predicted: true}')") + return 0 + fi + run_cli "claude plugin enable $id -s $scope" plugin enable "$id" -s "$scope" + trunc out "$CLI_OUT" + ENABLED_ROWS+=("$(jq -c -n --arg id "$id" --arg sc "$scope" --argjson rc "$CLI_RC" --arg out "$out" \ + '{id: $id, scope: $sc, rc: $rc, output: $out, predicted: false}')") +} + +# --- Step 5b — cache content check ------------------------------------------------ +# ONE call per marketplace. The stale ids come from the JSON this call already +# wrote, extracted CR-safe; the `--ids` form is reached only when the JSON could not +# be produced, never in addition to it. +cache_content_block() { + local mp="$1" + local report="$RUN_DIR/cache-content.$mp.json" rc=0 ids + + if [[ ! -f "$report" ]]; then + "$CACHE_CHECK" --marketplace "$mp" >"$report" 2>"$RUN_DIR/.cc-err" + rc=$? + fi + + # `stale[]` carries the per-id row the report renders: the version the record + # names, and one file count. All three directions are summed, because the row + # says the cache DISAGREES with the recorded sha and a file only in the tree or + # only in the cache disagrees exactly as much as one whose bytes changed. + # `stale_ids` stays alongside it for readers that only need the ids. + if ((rc == 0)) && jq -e 'has("checked")' "$report" >/dev/null 2>&1; then + jq_to CACHE_JSON -c '{checked, match, stale_content, unverifiable, + skipped_absent_project_paths, + stale_ids: [.installs[]? | select(.verdict == "stale-content") | .id], + stale: [.installs[]? | select(.verdict == "stale-content") + | {id, version, files_differ: ((.differing // 0) + (.missing_from_cache // 0) + + (.extra_in_cache // 0))}], + source: "json"}' "$report" + return 0 + fi + + # The JSON is unusable, so the id list is projected with the checker's own `--ids` + # form rather than left unknown. + "$CACHE_CHECK" --marketplace "$mp" --ids >"$RUN_DIR/cache-stale-ids.$mp.txt" 2>>"$RUN_DIR/.cc-err" + rc=$? + json_lines ids "$RUN_DIR/cache-stale-ids.$mp.txt" + mp_error "cache-content JSON unusable; stale ids taken from the checker's --ids form (exit $rc)" + # Same shape either way, with the per-id detail the `--ids` form cannot know + # spelled `null` rather than omitted: a reader that finds no `stale` key cannot + # tell an empty finding from a missing field. + # shellcheck disable=SC2016 # a jq program: every $var is a jq variable + jq_to CACHE_JSON -c -n --argjson ids "$ids" \ + '{checked: null, match: null, stale_content: ($ids | length), unverifiable: null, + skipped_absent_project_paths: null, stale_ids: $ids, + stale: ($ids | map({id: ., version: null, files_differ: null})), + source: "ids-fallback"}' +} + +# --- version capture -------------------------------------------------------------- +# `` is the pre-mutation snapshot's version by construction; `` is the +# CLI's own line when it named one (source 2), else the post-sweep read (source 3). +# When the CLI reported an update and the post version is unchanged, the pair keeps +# `unknown` rather than rendering ` → `, which would claim nothing changed +# for a plugin that did. +finalize_moves() { + local mp="$1" + local kind id scope old new result dir row post="$RUN_DIR/post.$mp.json" + [[ -f "$RUN_DIR/moves.$mp.tsv" ]] || return 0 + while IFS=$'\t' read -r kind id scope old new result; do + [[ -n "$id" ]] || continue + # A version field is written as `-` when it is empty, and read back the same + # way: tab is IFS WHITESPACE, so two adjacent tabs collapse into one delimiter + # and an empty interior field would shift every later column left by one. + [[ "$old" == "-" ]] && old="" + [[ "$new" == "-" ]] && new="" + # An id the CLI called already-current changed nothing and is not a report row. + [[ "$result" == "noop" ]] && continue + if [[ -z "$new" && -f "$post" ]]; then + version_at new "$post" "$id" "$scope" + [[ "$new" == "$old" ]] && new="" + fi + if [[ -z "$new" ]]; then + new="unknown" + dir="unknown" + else + dir=$(version_direction "$old" "$new") + fi + case "$dir" in + same) continue ;; + backward) + DOWNGRADED+=("$(jq -c -n --arg id "$id" --arg sc "$scope" --arg o "$old" --arg n "$new" \ + '{id: $id, scope: $sc, old: $o, new: $n}')") + ;; + *) + row=$(jq -c -n --arg id "$id" --arg sc "$scope" --arg o "$old" --arg n "$new" --arg d "$dir" \ + '{id: $id, scope: $sc, old: $o, new: $n, direction: $d}') + if [[ "$kind" == "in_repo" ]]; then IR_UPDATED+=("$row"); else US_UPDATED+=("$row"); fi + ;; + esac + done <"$RUN_DIR/moves.$mp.tsv" +} + +# --- report rows that live in the state, not in this run's actions ------------------ +# SKILL.md's Report has rows whose only source is a fleet-state report: the +# marketplace's own autoUpdate, the stale project records, the user-scope orphans, +# and the share of actionable divergences that belong to the repo the run stands in. +# They ride the digest so the report costs no extra read. +report_extras() { + local __var="$1" mp="$2" src="" + for src in "$RUN_DIR/post.$mp.json" "$RUN_DIR/pre-install.$mp.json" "$RUN_DIR/pre.$mp.json" \ + "$RUN_DIR/pre-refresh.$mp.json"; do + [[ -f "$src" ]] && break + src="" + done + if [[ -z "$src" ]]; then + jq_to "$__var" -c -n '{auto_update: null, user_scope_orphans: [], + stale_project_records: {total: null, by_path: []}, + in_repo_records: null, in_repo_ids: [], divergences_here: null}' + return 0 + fi + # `in_repo_records` is the count of project/local records belonging to the repo + # the run stands in, independent of whether any of them diverged. The report's + # `In-repo:` row needs exactly that: `0` means this root has no project/local + # installs, and the intersection with the divergences answers a different + # question. `by_path` carries the per-path counts the stale-project-records + # section renders one row each from. + # shellcheck disable=SC2016 # a jq program: every $var is a jq variable + jq_to "$__var" -c ' + ([.divergences[]? | select(.versionsMatch == false) | .id]) as $act + | ([.installed[]? | select(.currentProject == true) | .id]) as $here + | ([.installed[]? | select(.projectPathPresent == false)]) as $absent + | {auto_update: (.marketplace.autoUpdate // null), + user_scope_orphans: (.user_scope_orphans // []), + stale_project_records: {total: ($absent | length), + by_path: ($absent | group_by(.projectPath) + | map({path: .[0].projectPath, count: length}))}, + in_repo_records: ($here | length), + in_repo_ids: $here, + divergences_here: ($act | map(select(. as $i | $here | index($i))) | length)}' "$src" +} + +# --- one marketplace block -------------------------------------------------------- +emit_marketplace_block() { + local mp="$1" + local ir_u ir_f ir_w us_u us_f us_w wh dg inst en pr errs + # Written on the first pass only. The re-entry reads this sidecar; overwriting + # it after restore would drop the first-pass failures from a later re-entry. + if ((ONLY_INSTALL_MODE == 0)); then + persist_first_pass_rows "$mp" + fi + local reg_interval reg_rows div extras block + + json_array_of ir_u ${IR_UPDATED[@]+"${IR_UPDATED[@]}"} + json_array_of ir_f ${IR_FAILED[@]+"${IR_FAILED[@]}"} + json_array_of ir_w ${IR_WOULD[@]+"${IR_WOULD[@]}"} + json_array_of us_u ${US_UPDATED[@]+"${US_UPDATED[@]}"} + json_array_of us_f ${US_FAILED[@]+"${US_FAILED[@]}"} + json_array_of us_w ${US_WOULD[@]+"${US_WOULD[@]}"} + json_array_of wh ${WITHHELD[@]+"${WITHHELD[@]}"} + json_array_of dg ${DOWNGRADED[@]+"${DOWNGRADED[@]}"} + json_array_of inst ${INSTALLED_ROWS[@]+"${INSTALLED_ROWS[@]}"} + json_array_of en ${ENABLED_ROWS[@]+"${ENABLED_ROWS[@]}"} + json_array_of pr ${PROJECT_ROWS[@]+"${PROJECT_ROWS[@]}"} + + if ((${#MP_ERRORS[@]} == 0)); then + errs='[]' + else + jq_to errs -c -R -s 'split("\n") | map(select(length > 0))' <<<"$(printf '%s\n' "${MP_ERRORS[@]}")" + fi + + catalog_regression_rows reg_interval reg_rows "$mp" + divergence_block div "$mp" + report_extras extras "$mp" + # A field that could not be computed becomes an empty object, never an empty + # string: an empty --argjson would take the whole digest down with it. + [[ -n "$div" ]] || div='{}' + [[ -n "$extras" ]] || extras='{}' + [[ -n "$reg_rows" ]] || reg_rows='[]' + + # shellcheck disable=SC2016 # a jq program: every $var is a jq variable + jq_to block -c -n \ + --arg name "$mp" \ + --arg lastUpdated "$CATALOG_LAST_UPDATED" \ + --argjson refresh_rc "${REFRESH_RC:-null}" \ + --arg refresh_out "$REFRESH_OUT" \ + --argjson refresh_predicted "$REFRESH_PREDICTED" \ + --argjson project_root "$PROJECT_ROOT_JSON" \ + --argjson ir_u "$ir_u" --argjson ir_f "$ir_f" --argjson ir_w "$ir_w" \ + --argjson us_u "$us_u" --argjson us_f "$us_f" --argjson us_w "$us_w" \ + --argjson wh "$wh" --argjson dg "$dg" \ + --argjson install_gap "$INSTALL_GAP" --argjson inst "$inst" \ + --argjson enable_gap "$ENABLE_GAP" --argjson en "$en" --argjson pr "$pr" \ + --argjson deferred "$INSTALL_DEFERRED" --argjson stopped "$STOPPED_BEFORE_INSTALL" \ + --argjson normalize "$NORMALIZE_JSON" --argjson cache "$CACHE_JSON" \ + --arg reg_interval "$reg_interval" --argjson reg_rows "$reg_rows" \ + --argjson div "$div" --argjson self_updated "$SELF_UPDATED" \ + --argjson extras "$extras" \ + --argjson errors "$errs" ' + $extras + {name: $name, + catalog_last_updated: (if $lastUpdated == "" then null else $lastUpdated end), + refresh: {rc: $refresh_rc, output: $refresh_out, predicted: $refresh_predicted}, + project_root: $project_root, + in_repo: {updated: $ir_u, failed: $ir_f, would_update: $ir_w}, + user_sweep: {updated: $us_u, failed: $us_f, would_update: $us_w, + withheld_downgrades: $wh}, + downgraded: $dg, + install_gap: $install_gap, + installed: $inst, + install_enable_deferred: $deferred, + stopped_before_install: $stopped, + enable_gap: $enable_gap, + enabled: $en, + project_enable_rows: $pr, + normalize: $normalize, + cache_content: $cache, + catalog_regression: (if $reg_interval == "" then null + else {interval: $reg_interval, rows: $reg_rows} end), + divergences: $div, + self_updated: $self_updated, + errors: $errors}' + printf '%s\n' "$block" >>"$RUN_DIR/.blocks.jsonl" +} + +# --- main -------------------------------------------------------------------------- +setup_run_dir + +# `--allow-downgrade` belongs to the RUN, not to one invocation of it. A re-entry +# that omitted the flag would otherwise rebuild the withheld list from +# `downgrades..txt` and report a downgrade the first pass already applied. The +# flag is written once by the pass that starts the run and read back by the +# re-entry, before anything branches on it; a run directory from an older version +# carries no file and keeps the previous behaviour. +SAVED_ALLOW_DOWNGRADE="" +if ((ONLY_INSTALL_MODE == 1)); then + if [[ -f "$RUN_DIR/flags.json" ]]; then + jq_to SAVED_ALLOW_DOWNGRADE -r '.allow_downgrade // false' "$RUN_DIR/flags.json" 2>/dev/null + [[ "$SAVED_ALLOW_DOWNGRADE" != "true" ]] || ALLOW_DOWNGRADE=1 + fi +else + FLAG_AD="false" + ((ALLOW_DOWNGRADE == 0)) || FLAG_AD="true" + printf '{"allow_downgrade":%s}\n' "$FLAG_AD" >"$RUN_DIR/flags.json" +fi + +: >"$RUN_DIR/.blocks.jsonl" +[[ -f "$JOURNAL_LOG" ]] || : >"$JOURNAL_LOG" + +MPS=() +if ((ONLY_INSTALL_MODE == 1)); then + # The re-entry's marketplaces are the ones the first pass actually swept, read off + # its own snapshots. Resolving the default again would run Steps 4 and 5 against + # one marketplace and emit a one-block digest for a run that covered several, + # which is the silent partial sweep the marketplace-scoping rule exists to + # prevent. + for snapshot in "$RUN_DIR"/pre-refresh.*.json; do + [[ -f "$snapshot" ]] || continue + snapshot="${snapshot##*/pre-refresh.}" + MPS+=("${snapshot%.json}") + done + if [[ -n "$TARGET_MP" ]]; then + if [[ ! -f "$RUN_DIR/pre-refresh.$TARGET_MP.json" ]]; then + echo "ERROR: that run directory carries no snapshot for marketplace: $TARGET_MP" >&2 + echo " --only-install re-enters a run; it cannot start one for a new marketplace." >&2 + exit 2 + fi + MPS=("$TARGET_MP") + fi + if ((${#MPS[@]} == 0)); then + echo "ERROR: that run directory carries no marketplace snapshot: $RUN_DIR" >&2 + exit 2 + fi +elif ((ALL == 1)); then + # Names come from the script, never a hand-written jq over known_marketplaces.json: + # enumerating names carries the same trailing-`\r` hazard as enumerating ids. + if ! "$FLEET_STATE" --marketplaces >"$RUN_DIR/.marketplaces.txt" 2>"$RUN_DIR/.fs-err"; then + echo "ERROR: could not enumerate marketplaces" >&2 + cat "$RUN_DIR/.fs-err" >&2 + exit 2 + fi + while IFS= read -r line; do + line="${line//$'\r'/}" + [[ -n "$line" ]] || continue + MPS+=("$line") + done <"$RUN_DIR/.marketplaces.txt" +elif [[ -n "$TARGET_MP" ]]; then + MPS=("$TARGET_MP") +else + # The default marketplace, resolved dynamically. The resolving read IS Step 1's + # pre-refresh snapshot, so it is saved under the resolved name rather than repeated. + if ! "$FLEET_STATE" >"$RUN_DIR/.default.json" 2>"$RUN_DIR/.fs-err"; then + echo "ERROR: could not resolve the default marketplace" >&2 + cat "$RUN_DIR/.fs-err" >&2 + exit 2 + fi + jq_to DEFAULT_MP -r '.marketplace.name // ""' "$RUN_DIR/.default.json" + if [[ -z "$DEFAULT_MP" ]]; then + echo "ERROR: the default marketplace report carries no marketplace name" >&2 + exit 2 + fi + MPS=("$DEFAULT_MP") + [[ -f "$RUN_DIR/pre-refresh.$DEFAULT_MP.json" ]] || + mv "$RUN_DIR/.default.json" "$RUN_DIR/pre-refresh.$DEFAULT_MP.json" +fi + +if ((${#MPS[@]} == 0)); then + run_error "no marketplace resolved for this run" +fi + +for mp in ${MPS[@]+"${MPS[@]}"}; do + run_marketplace "$mp" +done + +BLOCKS='[]' +[[ -s "$RUN_DIR/.blocks.jsonl" ]] && jq_to BLOCKS -c -s '.' "$RUN_DIR/.blocks.jsonl" + +if ((${#RUN_ERRORS[@]} == 0)); then + RUN_ERRS='[]' +else + jq_to RUN_ERRS -c -R -s 'split("\n") | map(select(length > 0))' <<<"$(printf '%s\n' "${RUN_ERRORS[@]}")" +fi + +DIGEST="" +ALLOW_DOWNGRADE_JSON="false" +((ALLOW_DOWNGRADE == 1)) && ALLOW_DOWNGRADE_JSON="true" + +# shellcheck disable=SC2016 # a jq program: every $var is a jq variable +jq_to DIGEST -c -n \ + --arg run_dir "$RUN_DIR" \ + --arg mode "$MODE" \ + --argjson allow_downgrade "$ALLOW_DOWNGRADE_JSON" \ + --arg install_new "$INSTALL_NEW" \ + --arg install_new_invalid "$INSTALL_NEW_INVALID" \ + --argjson marketplaces "$BLOCKS" \ + --argjson errors "$RUN_ERRS" ' + {run_dir: $run_dir, mode: $mode, allow_downgrade: $allow_downgrade, + install_new: $install_new, + install_new_invalid: (if $install_new_invalid == "" then null else $install_new_invalid end), + marketplaces: $marketplaces, errors: $errors}' + +printf '%s\n' "$DIGEST" >"$RUN_DIR/digest.json" +printf '%s\n' "$DIGEST" +exit 0 diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh new file mode 100755 index 00000000000..46e439a77b6 --- /dev/null +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh @@ -0,0 +1,698 @@ +#!/usr/bin/env bash +# Black-box contract tests for sync-run.sh (self-contained — ships with the plugin). +# Fixtures are built per case into a temp dir and driven through the REAL +# fleet-state.sh via its FLEET_STATE_* env overrides, so every `--from` projection +# and its exit status is the production one. Only the two siblings whose real work +# needs a machine — the `claude` CLI and cache-content-check.sh's git compare — are +# stubbed, through sync-run.sh's own SYNC_RUN_* overrides. +set -uo pipefail + +# Fixture git isolation: an inherited GIT_DIR/GIT_WORK_TREE/GIT_CONFIG would +# redirect a fixture's git usage into the caller's repository. +unset GIT_DIR GIT_WORK_TREE GIT_CONFIG + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SCRIPT="$SCRIPT_DIR/sync-run.sh" +TEST_TMPDIR="$(mktemp -d)" +trap 'rm -rf "$TEST_TMPDIR"' EXIT + +FAILED=0 +CASE_NUM=0 + +pass() { printf 'PASS: %s\n' "$1"; } +fail() { + FAILED=$((FAILED + 1)) + printf 'FAIL: %s\n detail: %s\n' "$1" "$2" >&2 +} +assert_eq() { + if [[ "$2" == "$3" ]]; then pass "$1"; else fail "$1" "expected: $2, actual: $3"; fi +} +assert_exit() { + if [[ "$2" == "$3" ]]; then pass "$1"; else fail "$1" "expected exit $2, got $3"; fi +} +assert_contains() { + case "$2" in + *"$3"*) pass "$1" ;; + *) fail "$1" "expected to contain: $3 — got: $2" ;; + esac +} + +if ! command -v jq >/dev/null 2>&1; then + echo "SKIP: jq not installed" >&2 + exit 0 +fi + +# --- Fixture builders -------------------------------------------------------- + +# CASE_NUM must be incremented in the CALLER's shell before calling this, never +# inside it: `case_dir=$(new_case_dir)` runs in a subshell, so an assignment made +# in here is discarded and every case would silently reuse case-1's directory. +new_case_dir() { + local case_dir="$TEST_TMPDIR/case-$CASE_NUM" + mkdir -p "$case_dir/catalog" "$case_dir/journal" "$case_dir/stubs" + echo "$case_dir" +} + +write() { printf '%s' "$2" >"$1"; } + +# A catalog entry with its own manifest, so `catalog_versions` resolves and the +# equality pre-filter and the downgrade guard are the production ones. Under +# FLEET_STATE_CATALOG_DIR the manifests live at +# ///.claude-plugin/plugin.json, mirroring +# production's //.claude-plugin/plugin.json. +catalog_plugin() { + local case_dir="$1" mp="$2" name="$3" version="$4" + mkdir -p "$case_dir/catalog/$mp/$name/.claude-plugin" + write "$case_dir/catalog/$mp/$name/.claude-plugin/plugin.json" \ + "{\"name\":\"$name\",\"version\":\"$version\"}" +} + +# fleet-state.sh normalizes a project root to the platform's own spelling, so a +# fixture that records a projectPath has to record it the same way or the record +# never reads as `currentProject: true`. +norm_path() { + if command -v cygpath >/dev/null 2>&1; then + cygpath -m "$1" + else + printf '%s' "$1" + fi +} + +# The `claude` stub. Records every invocation and, on `plugin update`, rewrites the +# fixture's installed_plugins.json so the post-sweep re-read really moves. +write_claude_stub() { + local case_dir="$1" + cat >"$case_dir/stubs/claude" <<'STUB' +#!/usr/bin/env bash +printf '%s\n' "$*" >>"$CLAUDE_STUB_LOG" +verb="${1:-} ${2:-}" +case "$verb" in +"plugin marketplace") + mp="${4:-}" + if [[ -n "${CLAUDE_STUB_REFRESH_FAIL_MP:-}" && "$mp" == "$CLAUDE_STUB_REFRESH_FAIL_MP" ]]; then + echo "Failed to clone marketplace repository" >&2 + exit 1 + fi + echo "Successfully updated marketplace: $mp" + ;; +"plugin update") + id="${3:-}" + scope="${5:-user}" + if [[ -n "${CLAUDE_STUB_UPDATE_FAIL_ID:-}" && "$id" == "$CLAUDE_STUB_UPDATE_FAIL_ID" ]]; then + echo "Plugin \"$id\" not found" + exit 1 + fi + if [[ -n "${CLAUDE_STUB_NOOP_ID:-}" && "$id" == "$CLAUDE_STUB_NOOP_ID" ]]; then + cur=$(jq -r --arg id "$id" --arg sc "$scope" \ + 'first(.plugins[$id][]? | select(.scope == $sc) | .version) // "0.0.0"' \ + "$CLAUDE_STUB_INSTALLED_JSON") + echo "${id%@*} is already at the latest version ($cur)." + exit 0 + fi + new="${CLAUDE_STUB_NEW_VERSION:-9.9.9}" + old=$(jq -r --arg id "$id" --arg sc "$scope" \ + 'first(.plugins[$id][]? | select(.scope == $sc) | .version) // "0.0.0"' \ + "$CLAUDE_STUB_INSTALLED_JSON") + tmp="$CLAUDE_STUB_INSTALLED_JSON.next" + jq --arg id "$id" --arg sc "$scope" --arg v "$new" \ + '.plugins[$id] = [.plugins[$id][] | if .scope == $sc then .version = $v else . end]' \ + "$CLAUDE_STUB_INSTALLED_JSON" >"$tmp" && mv "$tmp" "$CLAUDE_STUB_INSTALLED_JSON" + echo "Plugin \"${id%@*}\" updated from $old to $new for scope $scope. Restart to apply changes" + ;; +"plugin install") + echo "Installed ${3:-}" + ;; +"plugin enable") + echo "Enabled ${3:-}" + ;; +*) + echo "unexpected stub invocation: $*" >&2 + exit 9 + ;; +esac +exit 0 +STUB + chmod +x "$case_dir/stubs/claude" +} + +# The cache-content-check.sh stub. Counts calls so the once-per-marketplace +# contract is asserted directly, and emits the JSON shape the real script emits. +write_cache_stub() { + local case_dir="$1" + cat >"$case_dir/stubs/cache-content-check.sh" <<'STUB' +#!/usr/bin/env bash +printf '%s\n' "$*" >>"$CC_STUB_LOG" +mp="" +ids=0 +while [[ $# -gt 0 ]]; do + case "$1" in + --marketplace) mp="$2"; shift 2 ;; + --ids) ids=1; shift ;; + *) shift ;; + esac +done +if ((ids == 1)); then + printf '%s\n' "alpha@$mp" + exit 0 +fi +if [[ "${CC_STUB_BREAK_JSON:-0}" == "1" ]]; then + echo "not json at all" + exit 2 +fi +cat <"$case_dir/stubs/normalize-enabled-plugins.sh" <<'STUB' +#!/usr/bin/env bash +printf '%s\n' "$*" >>"${NORMALIZE_STUB_LOG:-/dev/null}" +echo "already-sorted" +exit 0 +STUB + chmod +x "$case_dir/stubs/normalize-enabled-plugins.sh" +} + +setup_case() { + local case_dir="$1" + write_claude_stub "$case_dir" + write_cache_stub "$case_dir" + write_normalize_stub "$case_dir" + : >"$case_dir/claude.log" + : >"$case_dir/cc.log" + : >"$case_dir/normalize.log" + [[ -f "$case_dir/user_settings.json" ]] || write "$case_dir/user_settings.json" '{"enabledPlugins":{}}' +} + +# Runs sync-run.sh against a case fixture. Extra args are sync-run.sh's own. +run_sync() { + local case_dir="$1" + shift + env \ + FLEET_STATE_INSTALLED_JSON="$case_dir/installed_plugins.json" \ + FLEET_STATE_MARKETPLACES_JSON="$case_dir/known_marketplaces.json" \ + FLEET_STATE_USER_SETTINGS="$case_dir/user_settings.json" \ + FLEET_STATE_CATALOG_DIR="$case_dir/catalog" \ + SYNC_RUN_CLAUDE_BIN="$case_dir/stubs/claude" \ + SYNC_RUN_CACHE_CHECK="$case_dir/stubs/cache-content-check.sh" \ + SYNC_RUN_NORMALIZE="$case_dir/stubs/normalize-enabled-plugins.sh" \ + CLAUDE_STUB_LOG="$case_dir/claude.log" \ + CLAUDE_STUB_INSTALLED_JSON="$case_dir/installed_plugins.json" \ + CC_STUB_LOG="$case_dir/cc.log" \ + NORMALIZE_STUB_LOG="$case_dir/normalize.log" \ + PATH="$case_dir/stubs:$PATH" \ + "${EXTRA_ENV[@]}" \ + bash "$SCRIPT" "$@" 2>"$case_dir/stderr.txt" +} + +# ============================================================================ +# Case: audit issues ZERO mutating CLI calls, and still takes every read +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +catalog_plugin "$case_dir" market1 alpha 0.3.0 +write "$case_dir/installed_plugins.json" '{ + "version": 1, + "plugins": {"alpha@market1": [{"scope": "user", "installPath": "y", "version": "0.1.0"}]} +}' +write "$case_dir/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m\"}, \"installLocation\": \"$case_dir/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +write "$case_dir/catalog/market1.json" '{"plugins": [{"name": "alpha", "source": "alpha"}]}' +write "$case_dir/user_settings.json" '{"enabledPlugins": {"alpha@market1": true}}' +setup_case "$case_dir" +EXTRA_ENV=() +# The policy argument is deliberately the unset placeholder token here: it is the +# one value a caller can pass by mistake, and it must fall back to `ask` and be +# named rather than swallowed. +# shellcheck disable=SC2016 # the unrendered placeholder token is the literal input under test +out=$(run_sync "$case_dir" --marketplace market1 --audit --install-new '${user_config.install_new}') +rc=$? +assert_exit "audit: exit 0" 0 "$rc" +assert_eq "invalid policy: falls back to ask" "ask" "$(jq -r '.install_new' <<<"$out")" +# shellcheck disable=SC2016 # the unrendered placeholder token is the literal expected value +assert_eq "invalid policy: the value is named, not swallowed" '${user_config.install_new}' \ + "$(jq -r '.install_new_invalid' <<<"$out")" +assert_eq "audit: mode is audit" "audit" "$(jq -r '.mode' <<<"$out")" +assert_eq "audit: zero claude invocations" "0" "$(wc -l <"$case_dir/claude.log" | tr -d ' ')" +assert_eq "audit: refresh is a prediction" "true" "$(jq -r '.marketplaces[0].refresh.predicted' <<<"$out")" +assert_eq "audit: the update candidate is predicted, not performed" "1" \ + "$(jq -r '.marketplaces[0].user_sweep.would_update | length' <<<"$out")" +assert_eq "audit: nothing recorded as updated" "0" \ + "$(jq -r '.marketplaces[0].user_sweep.updated | length' <<<"$out")" +assert_eq "audit: the scratch run directory is removed on exit" "absent" \ + "$([[ -d "$(jq -r '.run_dir' <<<"$out")" ]] && echo present || echo absent)" +# The other half of the `In-repo:` row's input: no project context, so no +# project/local record belongs to the root the run stands in. +assert_eq "audit: a run with no project context reports zero in-repo records" "0" \ + "$(jq -r '.marketplaces[0].in_repo_records' <<<"$out")" + +# ============================================================================ +# Case: sync calls the cache checker exactly ONCE per marketplace, and reads the +# stale ids out of that call's own JSON +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +catalog_plugin "$case_dir" market1 alpha 0.3.0 +write "$case_dir/installed_plugins.json" '{ + "version": 1, + "plugins": {"alpha@market1": [{"scope": "user", "installPath": "y", "version": "0.1.0"}]} +}' +write "$case_dir/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m\"}, \"installLocation\": \"$case_dir/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +write "$case_dir/catalog/market1.json" '{"plugins": [{"name": "alpha", "source": "alpha"}]}' +write "$case_dir/user_settings.json" '{"enabledPlugins": {"alpha@market1": true}}' +setup_case "$case_dir" +EXTRA_ENV=(CLAUDE_STUB_NEW_VERSION=0.3.0) +out=$(run_sync "$case_dir" --marketplace market1 --journal-root "$case_dir/journal") +rc=$? +assert_exit "sync: exit 0" 0 "$rc" +assert_eq "sync: checker called exactly once" "1" "$(wc -l <"$case_dir/cc.log" | tr -d ' ')" +assert_eq "sync: that one call was the JSON form, not --ids" "0" \ + "$(grep -c -- '--ids' "$case_dir/cc.log")" +assert_eq "sync: stale ids came from the JSON" "alpha@market1" \ + "$(jq -r '.marketplaces[0].cache_content.stale_ids[0]' <<<"$out")" +assert_eq "sync: cache source is the JSON" "json" \ + "$(jq -r '.marketplaces[0].cache_content.source' <<<"$out")" +# The per-id row the `Cache content:` section renders: only the stale install, its +# version, and one file count summing all three directions of disagreement. +assert_eq "sync: only the stale install gets a per-id row" "1" \ + "$(jq -r '.marketplaces[0].cache_content.stale | length' <<<"$out")" +assert_eq "sync: that row carries the id, its version, and the file count" "alpha@market1 0.1.0 4" \ + "$(jq -r '.marketplaces[0].cache_content.stale[0] | "\(.id) \(.version) \(.files_differ)"' <<<"$out")" +assert_eq "sync: the update is reported as a forward move" "forward" \ + "$(jq -r '.marketplaces[0].user_sweep.updated[0].direction' <<<"$out")" +assert_eq "sync: old version came from the pre-mutation snapshot" "0.1.0" \ + "$(jq -r '.marketplaces[0].user_sweep.updated[0].old' <<<"$out")" +assert_eq "sync: new version came from the CLI's own line" "0.3.0" \ + "$(jq -r '.marketplaces[0].user_sweep.updated[0].new' <<<"$out")" +assert_eq "sync: the journal recorded the mutating call" "1" \ + "$(grep -c 'claude plugin update alpha@market1' "$(jq -r '.run_dir' <<<"$out")/journal.log")" +assert_eq "sync: the digest is also written to the run directory" "market1" \ + "$(jq -r '.marketplaces[0].name' "$(jq -r '.run_dir' <<<"$out")/digest.json")" + +# ============================================================================ +# Case: a failing `claude plugin update` lands in `failed`, never in `updated` +# (the rc=${PIPESTATUS[0]} guarantee — tee succeeds whenever it can write the log) +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +catalog_plugin "$case_dir" market1 alpha 0.3.0 +write "$case_dir/installed_plugins.json" '{ + "version": 1, + "plugins": {"alpha@market1": [{"scope": "user", "installPath": "y", "version": "0.1.0"}]} +}' +write "$case_dir/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m\"}, \"installLocation\": \"$case_dir/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +write "$case_dir/catalog/market1.json" '{"plugins": [{"name": "alpha", "source": "alpha"}]}' +write "$case_dir/user_settings.json" '{"enabledPlugins": {"alpha@market1": true}}' +setup_case "$case_dir" +EXTRA_ENV=(CLAUDE_STUB_UPDATE_FAIL_ID=alpha@market1) +out=$(run_sync "$case_dir" --marketplace market1 --journal-root "$case_dir/journal") +assert_eq "failed update: recorded as failed" "1" \ + "$(jq -r '.marketplaces[0].user_sweep.failed | length' <<<"$out")" +assert_eq "failed update: NOT recorded as updated" "0" \ + "$(jq -r '.marketplaces[0].user_sweep.updated | length' <<<"$out")" +assert_eq "failed update: the CLI's own status is kept" "1" \ + "$(jq -r '.marketplaces[0].user_sweep.failed[0].rc' <<<"$out")" + +# ============================================================================ +# Case: a first-pass update failure survives an `--only-install` re-entry. The +# replacement digest is the whole-run report; dropping the failure would let a +# plugin that never moved render as a successful sync. +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +catalog_plugin "$case_dir" market1 alpha 0.3.0 +catalog_plugin "$case_dir" market1 beta 0.2.0 +write "$case_dir/installed_plugins.json" '{ + "version": 1, + "plugins": {"alpha@market1": [{"scope": "user", "installPath": "y", "version": "0.1.0"}]} +}' +write "$case_dir/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m\"}, \"installLocation\": \"$case_dir/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +write "$case_dir/catalog/market1.json" '{"plugins": [{"name": "alpha", "source": "alpha"}, {"name": "beta", "source": "beta"}]}' +write "$case_dir/user_settings.json" '{"enabledPlugins": {"alpha@market1": true}}' +setup_case "$case_dir" +EXTRA_ENV=(CLAUDE_STUB_UPDATE_FAIL_ID=alpha@market1) +out=$(run_sync "$case_dir" --marketplace market1 --install-new ask --journal-root "$case_dir/journal") +assert_eq "ask+fail: the update failure is recorded" "1" \ + "$(jq -r '.marketplaces[0].user_sweep.failed | length' <<<"$out")" +assert_eq "ask+fail: stops before Step 4" "true" \ + "$(jq -r '.marketplaces[0].stopped_before_install' <<<"$out")" +run_dir=$(jq -r '.run_dir' <<<"$out") +out2=$(run_sync "$case_dir" --only-install beta@market1 --run-dir "$run_dir") +assert_exit "ask+fail re-entry: exit 0" 0 $? +assert_eq "ask+fail re-entry: the first-pass failure is still in the digest" "alpha@market1" \ + "$(jq -r '.marketplaces[0].user_sweep.failed[0].id' <<<"$out2")" +assert_eq "ask+fail re-entry: its CLI status is kept" "1" \ + "$(jq -r '.marketplaces[0].user_sweep.failed[0].rc' <<<"$out2")" +assert_eq "ask+fail re-entry: the chosen id is still installed" "1" \ + "$(grep -c 'plugin install beta@market1' "$case_dir/claude.log")" +assert_eq "ask+fail re-entry: refresh output from the first pass is kept" \ + "$(jq -r '.marketplaces[0].refresh.output' <<<"$out")" \ + "$(jq -r '.marketplaces[0].refresh.output' <<<"$out2")" + +# ============================================================================ +# Case: a proven downgrade is WITHHELD by default and acted on only with +# --allow-downgrade, where it renders as downgraded and never as updated +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +catalog_plugin "$case_dir" market1 alpha 0.1.0 +write "$case_dir/installed_plugins.json" '{ + "version": 1, + "plugins": {"alpha@market1": [{"scope": "user", "installPath": "y", "version": "0.5.0"}]} +}' +write "$case_dir/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m\"}, \"installLocation\": \"$case_dir/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +write "$case_dir/catalog/market1.json" '{"plugins": [{"name": "alpha", "source": "alpha"}]}' +write "$case_dir/user_settings.json" '{"enabledPlugins": {"alpha@market1": true}}' +setup_case "$case_dir" +EXTRA_ENV=() +out=$(run_sync "$case_dir" --marketplace market1 --journal-root "$case_dir/journal") +assert_eq "downgrade: withheld by default" "1" \ + "$(jq -r '.marketplaces[0].user_sweep.withheld_downgrades | length' <<<"$out")" +assert_eq "downgrade: no update issued for it" "0" \ + "$(grep -c 'plugin update' "$case_dir/claude.log")" +assert_eq "downgrade: both versions carried for the report" "0.5.0 0.1.0" \ + "$(jq -r '.marketplaces[0].user_sweep.withheld_downgrades[0] | "\(.installed) \(.catalog)"' <<<"$out")" + +CASE_NUM=$((CASE_NUM + 1)) +case_dir2=$(new_case_dir) +cp -r "$case_dir"/. "$case_dir2"/ +: >"$case_dir2/claude.log" +: >"$case_dir2/cc.log" +write "$case_dir2/installed_plugins.json" '{ + "version": 1, + "plugins": {"alpha@market1": [{"scope": "user", "installPath": "y", "version": "0.5.0"}]} +}' +write "$case_dir2/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m\"}, \"installLocation\": \"$case_dir2/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +EXTRA_ENV=(CLAUDE_STUB_NEW_VERSION=0.1.0) +out=$(run_sync "$case_dir2" --marketplace market1 --allow-downgrade --journal-root "$case_dir2/journal") +assert_eq "--allow-downgrade: the rollback is issued" "1" \ + "$(grep -c 'plugin update alpha@market1' "$case_dir2/claude.log")" +assert_eq "--allow-downgrade: it renders as downgraded" "1" \ + "$(jq -r '.marketplaces[0].downgraded | length' <<<"$out")" +assert_eq "--allow-downgrade: never as updated" "0" \ + "$(jq -r '.marketplaces[0].user_sweep.updated | length' <<<"$out")" +assert_eq "--allow-downgrade: recorded in the digest" "true" \ + "$(jq -r '.allow_downgrade' <<<"$out")" + +# The flag belongs to the RUN. A re-entry that does not repeat it must not rebuild +# the withheld list from the run's own downgrade projection and report a rollback +# the first pass already applied. +run_dir2=$(jq -r '.run_dir' <<<"$out") +out2=$(run_sync "$case_dir2" --only-install '' --run-dir "$run_dir2") +assert_exit "--only-install after --allow-downgrade: exit 0" 0 $? +assert_eq "--only-install: the applied downgrade is not re-reported as withheld" "0" \ + "$(jq -r '.marketplaces[0].user_sweep.withheld_downgrades | length' <<<"$out2")" +assert_eq "--only-install: it still renders as downgraded" "1" \ + "$(jq -r '.marketplaces[0].downgraded | length' <<<"$out2")" +assert_eq "--only-install: and the run's flag is carried into the second digest" "true" \ + "$(jq -r '.allow_downgrade' <<<"$out2")" + +# ============================================================================ +# Case: an install gap under the `ask` policy stops before Step 4, and the narrow +# --only-install re-entry then installs and enables against the SAME run directory +# without re-running the cache checker +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +catalog_plugin "$case_dir" market1 alpha 0.2.0 +catalog_plugin "$case_dir" market1 beta 0.2.0 +write "$case_dir/installed_plugins.json" '{ + "version": 1, + "plugins": {"alpha@market1": [{"scope": "user", "installPath": "y", "version": "0.1.0"}]} +}' +write "$case_dir/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m\"}, \"installLocation\": \"$case_dir/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +write "$case_dir/catalog/market1.json" '{"plugins": [{"name": "alpha", "source": "alpha"}, {"name": "beta", "source": "beta"}]}' +write "$case_dir/user_settings.json" '{"enabledPlugins": {"alpha@market1": true}}' +setup_case "$case_dir" +EXTRA_ENV=(CLAUDE_STUB_NEW_VERSION=0.2.0) +out=$(run_sync "$case_dir" --marketplace market1 --install-new ask --journal-root "$case_dir/journal") +assert_eq "ask: the sweep still ran before the stop" "1" \ + "$(jq -r '.marketplaces[0].user_sweep.updated | length' <<<"$out")" +assert_eq "ask: stops before Step 4" "true" \ + "$(jq -r '.marketplaces[0].stopped_before_install' <<<"$out")" +assert_eq "ask: the gap is reported" "beta@market1" \ + "$(jq -r '.marketplaces[0].install_gap[0]' <<<"$out")" +assert_eq "ask: nothing installed" "0" "$(grep -c 'plugin install' "$case_dir/claude.log")" +assert_eq "ask: the checker still ran exactly once" "1" "$(wc -l <"$case_dir/cc.log" | tr -d ' ')" + +run_dir=$(jq -r '.run_dir' <<<"$out") +# The documented form carries no marketplace argument: the re-entry takes its +# marketplaces from the run directory's own snapshots. +out2=$(run_sync "$case_dir" --only-install beta@market1 --run-dir "$run_dir") +assert_exit "--only-install: exit 0" 0 $? +assert_eq "--only-install: it covers the run's marketplace without being told" "market1" \ + "$(jq -r '.marketplaces[0].name' <<<"$out2")" +assert_eq "--only-install: the chosen id is installed" "1" \ + "$(grep -c 'plugin install beta@market1' "$case_dir/claude.log")" +assert_eq "--only-install: reuses the same run directory" "$run_dir" "$(jq -r '.run_dir' <<<"$out2")" +assert_eq "--only-install: the first pass's sweep row survives into the second digest" "alpha@market1" \ + "$(jq -r '.marketplaces[0].user_sweep.updated[0].id' <<<"$out2")" +assert_eq "--only-install: and its project_root does too" "$(jq -r '.marketplaces[0].project_root' <<<"$out")" \ + "$(jq -r '.marketplaces[0].project_root' <<<"$out2")" +assert_eq "--only-install: the checker is NOT run a second time" "1" \ + "$(wc -l <"$case_dir/cc.log" | tr -d ' ')" +assert_eq "--only-install: the cache finding survives into the second digest" "alpha@market1" \ + "$(jq -r '.marketplaces[0].cache_content.stale_ids[0]' <<<"$out2")" +run_sync "$case_dir" --only-install beta@market2 --run-dir "$run_dir" --marketplace market2 >/dev/null +assert_exit "--only-install: a marketplace the run never swept is exit 2" 2 $? +assert_contains "--only-install: and says why" "$(cat "$case_dir/stderr.txt")" "no snapshot for marketplace" +assert_eq "--only-install: the refusal installed nothing" "1" \ + "$(grep -c 'plugin install' "$case_dir/claude.log")" + +assert_eq "--only-install: the normalizer wrote user scope once after the install" "1" \ + "$(grep -cv -- '--report-project' "$case_dir/normalize.log")" +assert_eq "--only-install: and only INSPECTED the project-scope map" "1" \ + "$(grep -c -- '--report-project' "$case_dir/normalize.log")" + +# ============================================================================ +# Case: `none` reports the gap and installs nothing; `all` installs it +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +catalog_plugin "$case_dir" market1 alpha 0.1.0 +catalog_plugin "$case_dir" market1 beta 0.2.0 +write "$case_dir/installed_plugins.json" '{ + "version": 1, + "plugins": {"alpha@market1": [{"scope": "user", "installPath": "y", "version": "0.1.0"}]} +}' +write "$case_dir/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m\"}, \"installLocation\": \"$case_dir/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +write "$case_dir/catalog/market1.json" '{"plugins": [{"name": "alpha", "source": "alpha"}, {"name": "beta", "source": "beta"}]}' +write "$case_dir/user_settings.json" '{"enabledPlugins": {"alpha@market1": true}}' +setup_case "$case_dir" +EXTRA_ENV=() +out=$(run_sync "$case_dir" --marketplace market1 --install-new none --journal-root "$case_dir/journal") +assert_eq "none: nothing installed" "0" "$(grep -c 'plugin install' "$case_dir/claude.log")" +assert_eq "none: the gap is still reported" "beta@market1" \ + "$(jq -r '.marketplaces[0].install_gap[0]' <<<"$out")" +assert_eq "none: the run did not stop before Step 4" "false" \ + "$(jq -r '.marketplaces[0].stopped_before_install' <<<"$out")" + +CASE_NUM=$((CASE_NUM + 1)) +case_dir2=$(new_case_dir) +cp -r "$case_dir"/. "$case_dir2"/ +: >"$case_dir2/claude.log" +: >"$case_dir2/cc.log" +: >"$case_dir2/normalize.log" +write "$case_dir2/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m\"}, \"installLocation\": \"$case_dir2/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +out=$(run_sync "$case_dir2" --marketplace market1 --install-new all --journal-root "$case_dir2/journal") +assert_eq "all: the gap is installed" "1" "$(grep -c 'plugin install beta@market1' "$case_dir2/claude.log")" +assert_eq "all: the normalizer heals the key order the install disturbed" "1" \ + "$(grep -cv -- '--report-project' "$case_dir2/normalize.log")" + +# ============================================================================ +# Case: an empty projection that EXITED 2 is an error, never "nothing to do" +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +catalog_plugin "$case_dir" market1 alpha 0.1.0 +write "$case_dir/installed_plugins.json" '{ + "version": 1, + "plugins": {"alpha@market1": [{"scope": "user", "installPath": "y", "version": "0.1.0"}]} +}' +write "$case_dir/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m\"}, \"installLocation\": \"$case_dir/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +write "$case_dir/catalog/market1.json" '{"plugins": [{"name": "alpha", "source": "alpha"}]}' +write "$case_dir/user_settings.json" '{"enabledPlugins": {"alpha@market1": true}}' +setup_case "$case_dir" +# A fleet-state wrapper that answers reads normally and rejects every projection +# the way the real script rejects a malformed report: exit 2, EMPTY stdout. +cat >"$case_dir/stubs/fleet-state.sh" <&2 + exit 2 + fi +done +exec bash "$SCRIPT_DIR/fleet-state.sh" "\$@" +STUB +chmod +x "$case_dir/stubs/fleet-state.sh" +EXTRA_ENV=(SYNC_RUN_FLEET_STATE="$case_dir/stubs/fleet-state.sh") +out=$(run_sync "$case_dir" --marketplace market1 --journal-root "$case_dir/journal") +assert_contains "exit-2 projection: reported as an error" \ + "$(jq -r '.marketplaces[0].errors | join(" | ")' <<<"$out")" "projection failed" +assert_eq "exit-2 projection: the sweep is not reported as done" "0" \ + "$(jq -r '.marketplaces[0].user_sweep.updated | length' <<<"$out")" +assert_eq "exit-2 projection: no update was issued off an empty list" "0" \ + "$(grep -c 'plugin update' "$case_dir/claude.log")" + +# ============================================================================ +# Case: --all loops every marketplace, and one marketplace's failure does not +# abort the sweep for the rest +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +catalog_plugin "$case_dir" market1 alpha 0.1.0 +catalog_plugin "$case_dir" market2 gamma 0.1.0 +write "$case_dir/installed_plugins.json" '{ + "version": 1, + "plugins": { + "alpha@market1": [{"scope": "user", "installPath": "y", "version": "0.1.0"}], + "gamma@market2": [{"scope": "user", "installPath": "z", "version": "0.1.0"}] + } +}' +write "$case_dir/known_marketplaces.json" "{ + \"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m1\"}, \"installLocation\": \"$case_dir/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}, + \"market2\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m2\"}, \"installLocation\": \"$case_dir/mkt2\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"} +}" +write "$case_dir/catalog/market1.json" '{"plugins": [{"name": "alpha", "source": "alpha"}]}' +write "$case_dir/catalog/market2.json" '{"plugins": [{"name": "gamma", "source": "gamma"}]}' +write "$case_dir/user_settings.json" '{"enabledPlugins": {"alpha@market1": true, "gamma@market2": true}}' +setup_case "$case_dir" +EXTRA_ENV=(CLAUDE_STUB_REFRESH_FAIL_MP=market1) +out=$(run_sync "$case_dir" --all --journal-root "$case_dir/journal") +rc=$? +assert_exit "--all: exit 0 despite a per-marketplace failure" 0 "$rc" +assert_eq "--all: both marketplaces are in the digest" "2" "$(jq -r '.marketplaces | length' <<<"$out")" +assert_contains "--all: the failing marketplace names its failure inline" \ + "$(jq -r '.marketplaces[] | select(.name == "market1") | .errors | join(" | ")' <<<"$out")" \ + "marketplace refresh failed" +assert_eq "--all: its install/enable maintenance is deferred, not silently skipped" "true" \ + "$(jq -r '.marketplaces[] | select(.name == "market1") | .install_enable_deferred' <<<"$out")" +assert_eq "--all: the other marketplace still refreshed" "0" \ + "$(jq -r '.marketplaces[] | select(.name == "market2") | .refresh.rc' <<<"$out")" +assert_eq "--all: the checker ran once per marketplace" "2" "$(wc -l <"$case_dir/cc.log" | tr -d ' ')" + +# ============================================================================ +# Case: an enable gap is filled at user scope and REPORTED at project scope +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +catalog_plugin "$case_dir" market1 alpha 0.1.0 +catalog_plugin "$case_dir" market1 delta 0.1.0 +ppath=$(norm_path "$case_dir") +write "$case_dir/installed_plugins.json" "{ + \"version\": 1, + \"plugins\": { + \"alpha@market1\": [{\"scope\": \"user\", \"installPath\": \"y\", \"version\": \"0.1.0\"}], + \"delta@market1\": [{\"scope\": \"project\", \"projectPath\": \"$ppath\", \"installPath\": \"d\", \"version\": \"0.1.0\"}] + } +}" +write "$case_dir/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m\"}, \"installLocation\": \"$case_dir/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +write "$case_dir/catalog/market1.json" '{"plugins": [{"name": "alpha", "source": "alpha"}, {"name": "delta", "source": "delta"}]}' +write "$case_dir/user_settings.json" '{"enabledPlugins": {}}' +setup_case "$case_dir" +EXTRA_ENV=(CLAUDE_PROJECT_DIR="$case_dir" CLAUDE_STUB_NOOP_ID=delta@market1) +out=$(run_sync "$case_dir" --marketplace market1 --install-new none --journal-root "$case_dir/journal") +assert_eq "no-op update: the in-repo sweep called the CLI for the record" "1" \ + "$(grep -c 'plugin update delta@market1' "$case_dir/claude.log")" +assert_eq "no-op update: an already-current id is NOT an Updated row" "0" \ + "$(jq -r '.marketplaces[0].in_repo.updated | length' <<<"$out")" +assert_eq "no-op update: and is not a downgrade either" "0" \ + "$(jq -r '.marketplaces[0].downgraded | length' <<<"$out")" +assert_eq "report inputs: the marketplace's autoUpdate rides the digest" "null" \ + "$(jq -r '.marketplaces[0] | has("auto_update") | if . then "null" else "missing" end' <<<"$out")" +assert_eq "report inputs: the stale-project-record count rides the digest" "0" \ + "$(jq -r '.marketplaces[0].stale_project_records.total' <<<"$out")" +# The `In-repo:` row's own input. This root HAS a project-scope install and the +# run moved none of it, which is exactly the case an intersection with the +# divergences cannot tell from "this root has no project/local installs". +assert_eq "report inputs: the in-repo record count rides the digest" "1" \ + "$(jq -r '.marketplaces[0].in_repo_records' <<<"$out")" +assert_eq "report inputs: and names the id" "delta@market1" \ + "$(jq -r '.marketplaces[0].in_repo_ids[0]' <<<"$out")" +assert_eq "report inputs: with nothing updated in it" "0" \ + "$(jq -r '.marketplaces[0].in_repo.updated | length' <<<"$out")" +assert_eq "enable gap: the user-scope id is enabled" "1" \ + "$(grep -c 'plugin enable alpha@market1 -s user' "$case_dir/claude.log")" +assert_eq "enable gap: no project-scope enable is ever issued" "0" \ + "$(grep -c 'plugin enable .* -s project' "$case_dir/claude.log")" +assert_eq "enable gap: the project-scope row is reported with its path" "$ppath" \ + "$(jq -r '.marketplaces[0].project_enable_rows[0].project_path' <<<"$out")" + +# ============================================================================ +# Case: an in-repo record for the plugin providing this skill is a self-update +# too, and the stale-project-record rows carry a count PER PATH +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +catalog_plugin "$case_dir" market1 delta 0.2.0 +catalog_plugin "$case_dir" market1 alpha 0.1.0 +catalog_plugin "$case_dir" market1 beta 0.1.0 +ppath=$(norm_path "$case_dir") +gone_a=$(norm_path "$case_dir/gone-a") +gone_b=$(norm_path "$case_dir/gone-b") +# The manifest `own_plugin_name` reads. Naming the fixture's own plugin here is +# what makes the assertion about the mechanism rather than about this +# repository's plugin name. +mkdir -p "$case_dir/self/.claude-plugin" +write "$case_dir/self/.claude-plugin/plugin.json" '{"name":"delta","version":"0.1.0"}' +write "$case_dir/installed_plugins.json" "{ + \"version\": 1, + \"plugins\": { + \"delta@market1\": [{\"scope\": \"project\", \"projectPath\": \"$ppath\", \"installPath\": \"d\", \"version\": \"0.1.0\"}], + \"alpha@market1\": [ + {\"scope\": \"project\", \"projectPath\": \"$gone_a\", \"installPath\": \"a\", \"version\": \"0.1.0\"}, + {\"scope\": \"local\", \"projectPath\": \"$gone_a\", \"installPath\": \"a\", \"version\": \"0.1.0\"} + ], + \"beta@market1\": [{\"scope\": \"project\", \"projectPath\": \"$gone_b\", \"installPath\": \"b\", \"version\": \"0.1.0\"}] + } +}" +write "$case_dir/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\": \"github\", \"repo\": \"e/m\"}, \"installLocation\": \"$case_dir/mkt\", \"lastUpdated\": \"2026-01-01T00:00:00Z\"}}" +write "$case_dir/catalog/market1.json" '{"plugins": [{"name": "delta", "source": "delta"}, {"name": "alpha", "source": "alpha"}, {"name": "beta", "source": "beta"}]}' +write "$case_dir/user_settings.json" '{"enabledPlugins": {"delta@market1": true, "alpha@market1": true, "beta@market1": true}}' +setup_case "$case_dir" +EXTRA_ENV=(CLAUDE_PROJECT_DIR="$case_dir" CLAUDE_PLUGIN_ROOT="$case_dir/self" CLAUDE_STUB_NEW_VERSION=0.2.0) +out=$(run_sync "$case_dir" --marketplace market1 --install-new none --journal-root "$case_dir/journal") +assert_eq "self-update: the in-repo record moved" "delta@market1" \ + "$(jq -r '.marketplaces[0].in_repo.updated[0].id' <<<"$out")" +assert_eq "self-update: an in-repo move of this plugin is a self-update" "true" \ + "$(jq -r '.marketplaces[0].self_updated' <<<"$out")" +assert_eq "stale project records: the total counts records, not paths" "3" \ + "$(jq -r '.marketplaces[0].stale_project_records.total' <<<"$out")" +assert_eq "stale project records: one row per distinct path" "2" \ + "$(jq -r '.marketplaces[0].stale_project_records.by_path | length' <<<"$out")" +assert_eq "stale project records: each row carries its own count" "2" \ + "$(jq -r --arg p "$gone_a" 'first(.marketplaces[0].stale_project_records.by_path[] | select(.path == $p) | .count)' <<<"$out")" +assert_eq "stale project records: and the single-record path reads 1" "1" \ + "$(jq -r --arg p "$gone_b" 'first(.marketplaces[0].stale_project_records.by_path[] | select(.path == $p) | .count)' <<<"$out")" +# An absent path is not "here": those records must not inflate the In-repo row. +assert_eq "stale project records: they are not counted as in-repo records" "1" \ + "$(jq -r '.marketplaces[0].in_repo_records' <<<"$out")" + +# ============================================================================ +# Case: sync mode without --journal-root is a usage error, not a silent scratch run +# ============================================================================ +CASE_NUM=$((CASE_NUM + 1)) +case_dir=$(new_case_dir) +setup_case "$case_dir" +EXTRA_ENV=() +out=$(run_sync "$case_dir" --marketplace market1) +rc=$? +assert_exit "no journal root: exit 2" 2 "$rc" +assert_contains "no journal root: names the flag" "$(cat "$case_dir/stderr.txt")" "--journal-root" + +# ============================================================================ +if ((FAILED > 0)); then + printf '\n%d test(s) failed\n' "$FAILED" >&2 + exit 1 +fi +printf '\nAll tests passed\n'