From 8d71de58ba73c5d8373077bb9f34a3d19bc8e6eb Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 7 Sep 2026 19:27:15 -0400 Subject: [PATCH 01/12] feat(claude-ops): run plugins sync Steps 1-5b in one script with a JSON digest sync-run.sh executes the sync/audit algorithm's Steps 1 through 5b for every target marketplace in one process and prints one digest the model reports from, instead of one model turn per step. Every invariant context/sync.md fixes holds in the script: per-step fleet-state.sh re-reads, the run journal, the PIPESTATUS[0] capture after each tee-journaled mutating call, the downgrade guard and its --allow-downgrade opt-in, the exit-2-is-not-empty projection check, the per-marketplace failure rule, and Step 4/5 gating on the fresh pre-install read. The cache-content checker is called ONCE per marketplace: the stale ids are extracted CR-safe from the JSON that call already wrote, and the checker's --ids form is a fallback for a JSON that could not be produced rather than a second pass beside one that was. install_new stays the model's decision because the user_config render happens only in SKILL.md: --install-new carries the rendered word, and on ask with a non-empty install gap the script reports the gap and stops before Step 4. --only-install --run-dir is the narrow re-entry that then performs Steps 4 and 5 against the same run journal and re-emits the digest without re-running the checker. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Pg4g2e7wXamNq2h4JeU8yg --- .../skills/plugins/scripts/sync-run.sh | 1060 +++++++++++++++++ .../skills/plugins/scripts/sync-run.test.sh | 540 +++++++++ 2 files changed, 1600 insertions(+) create mode 100644 plugins/claude-ops/skills/plugins/scripts/sync-run.sh create mode 100644 plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh 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 100644 index 00000000000..65078682b16 --- /dev/null +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh @@ -0,0 +1,1060 @@ +#!/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, 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, self_updated, errors} +# `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" + 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 +} + +# --- 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 $? +} + +proj_err() { + local text="" + [[ -f "$RUN_DIR/.proj-err" ]] && text=$(<"$RUN_DIR/.proj-err") + printf '%s' "${text//$'\r'/}" +} + +# 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 +} + +# --- 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 + 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 + 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" +} + +# --- the per-marketplace loop body (Steps 2-5b, plus Step 1's own refresh) ------- +run_marketplace() { + local mp="$1" + reset_marketplace_state + : >"$RUN_DIR/moves.$mp.tsv" + + local rc dg_rc id scope old new 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 + [[ -f "$pre_refresh" ]] && jq_to CATALOG_LAST_UPDATED -r '.marketplace.lastUpdated // ""' "$pre_refresh" + 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" + printf 'in_repo\t%s\t%s\t%s\t%s\n' "$id" "$scope" "$old" "$new" >>"$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" + printf 'user_sweep\t%s\t%s\t%s\t%s\n' "$id" user "$old" "$new" >>"$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 + DOWNGRADED+=("$(jq -c -n --arg id "$id" --arg sc "$scope" --arg o "$old" --arg n "$new" \ + '{id: $id, scope: $sc, old: $o, new: $n}')") + 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 + for row in ${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 + jq_to NORMALIZE_JSON -c -n --argjson rc "$nrc" --arg out "$nout" --arg mode "$MODE" \ + '{rc: $rc, output: $out, checked_only: ($mode == "audit")}' +} + +# --- 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 + 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 + + 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], + 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)" + 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, 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 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; do + [[ -n "$id" ]] || 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" +} + +# --- 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 + local reg_interval reg_rows div 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" + + 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 errors "$errs" ' + {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 +: >"$RUN_DIR/.blocks.jsonl" +[[ -f "$JOURNAL_LOG" ]] || : >"$JOURNAL_LOG" + +MPS=() +if ((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" + +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 100644 index 00000000000..fbb6551cc1b --- /dev/null +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh @@ -0,0 +1,540 @@ +#!/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 + 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. +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")" +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)" + +# ============================================================================ +# 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")" +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 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")" + +# ============================================================================ +# 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.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 ask --journal-root "$case_dir/journal") +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") +out2=$(run_sync "$case_dir" --marketplace market1 --only-install beta@market1 --run-dir "$run_dir") +assert_exit "--only-install: exit 0" 0 $? +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 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")" +assert_eq "--only-install: the normalizer ran after the install" "1" \ + "$(wc -l <"$case_dir/normalize.log" | tr -d ' ')" + +# ============================================================================ +# 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" \ + "$(wc -l <"$case_dir2/normalize.log" | tr -d ' ')" + +# ============================================================================ +# 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") +out=$(run_sync "$case_dir" --marketplace market1 --install-new none --journal-root "$case_dir/journal") +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: 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' From 9d03728ae7e69e8cae723b8d7b7b5816dadf5fcd Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 7 Sep 2026 19:28:18 -0400 Subject: [PATCH 02/12] chore(claude-ops): mark sync-run.sh and its suite executable Every sibling script in this directory is 100755; a 100644 helper is not runnable from a checkout that honours the mode bit. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Pg4g2e7wXamNq2h4JeU8yg --- plugins/claude-ops/skills/plugins/scripts/sync-run.sh | 0 plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh | 0 2 files changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 plugins/claude-ops/skills/plugins/scripts/sync-run.sh mode change 100644 => 100755 plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh old mode 100644 new mode 100755 diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh old mode 100644 new mode 100755 From febff4b6fb9d94db21671ad08114cc39636cbeef Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 7 Sep 2026 19:30:52 -0400 Subject: [PATCH 03/12] perf(claude-ops): batch cache-content-check fleet-wide, 400 spawns -> 17 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every external call in `cache-content-check.sh` was per install record: 77 installs on this fleet cost 400 PATH-visible process creations (git 238, find 77, sort 77, jq 8) and ~100 s, process-creation-bound rather than CPU-bound. The compare itself is set arithmetic and never needed a process per install. Now batched per MARKETPLACE, so the process count is a property of the marketplace rather than of how many installs it holds: - one `jq` over installed_plugins.json: the shape gate and every record for every marketplace, read once, filtered by suffix in the shell; - one `jq` over known_marketplaces.json: shape gate, membership, and the installLocation in the same pass; - one `git cat-file --batch-check` over every DISTINCT sha, replacing 77 `cat-file -e` calls (`missing` -> `sha-not-local`, positional by contract); - per distinct sha, one `git show` + one `jq` for the source map (unchanged); - per distinct sha, ONE `git ls-tree -r -z -- `. A multi-pathspec ls-tree cannot report "this pathspec matched nothing", so that 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`; - ONE `find` over every install root into one `sort -z` (chunked on a byte budget so an argv over the OS limit cannot silently read as an empty cache); - ONE `git hash-object --stdin-paths` over the CACHE-INTERSECT-TREE files only (3,402 here, not all 9,547) — a cache-only file's hash answers no question, only its existence does; - ONE `git check-ignore -z --no-index --stdin` for the whole marketplace, keyed by `/` so records sharing a source directory read one answer. Counter, `--marketplace melodic-software`, 77 user installs: before 400 spawns (git 238, find 77, sort 77, jq 8) ~100 s p50 after 17 spawns (git 10, find 1, sort 1, jq 5) 15.6 s p50 Three independent censuses of the new script agreed at 17 (two runs of the performance plugin's spawn-census.sh, one of the baseline's own first-arg argcensus.sh), and the shimmed stdout is byte-identical to the unshimmed reference run — the shims are not a variable in the subject. Equivalence. Output contract byte-for-byte unchanged: - live fleet, `--marketplace melodic-software`: OLD and two NEW runs all 24,492 bytes, `cmp` identical, and identical to the baseline's recorded reference run. checked 77 / match 77 / stale 0 / unverifiable 0. `--ids` identical (empty, correct on a clean fleet); - a synthetic fixture exercises the paths[] ordering the clean fleet cannot: stale-content with two `differs`, one `missing-from-cache` and three `extra-in-cache` (one of them gitignored and correctly excluded), plus `match`, `no-source-at-sha`, `sha-not-local`, `no-git-commit-sha`, `install-path-missing` and a second marketplace with no installLocation. OLD vs NEW `cmp` identical across `--marketplace`, `--ids`, `--all` and `--scope all`; - cache-content-check.test.sh: 24 cases, 0 failed, unchanged. The bundled process-budget probe measures 12 creations against its ceiling of 26. Two error-path divergences, both untested edges rather than output-contract changes. Under `--all`, an installed_plugins.json whose record read fails mid-pass now exits 2 fleet-wide instead of emitting an inline `{"error": …}` for one marketplace — the read is now one pass for the whole file, and failing loud on state-file drift is what the rest of this script already does. Also under `--all`, a marketplace whose value is not an object now verdicts `no-install-location` instead of an inline error block. One deliberate degradation, noted in the code: a single hash batch means a `hash-object` contract break lands on the install that owns the gap and on every install after it, where a per-install batch confined it to one. Both report the same "refused to compare" verdict. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Pg4g2e7wXamNq2h4JeU8yg --- .../plugins/scripts/cache-content-check.sh | 885 ++++++++++++------ 1 file changed, 577 insertions(+), 308 deletions(-) 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..8a458c4fe54 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,463 @@ 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 directory this entry belongs to. Longest match wins, and + # the path itself is tried first so a `source` naming a single file still + # resolves the way a single-pathspec call resolved it. + owner="" + walk="$path_rel" + while :; do + gkey="$s"$'\x1f'"$walk" + if [[ -n "${g_seen[$gkey]+set}" ]]; then + owner="$walk" + break 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 + [[ -n "$owner" ]] || continue + rel="${path_rel#"$owner"/}" + idx=${#tree_rel[@]} + tree_rel+=("$rel") + tree_blob+=("$blob") + tree_hash["$owner"$'\x1f'"$rel"]="$blob" + owner_idx["$s"$'\x1f'"$owner"]+=" $idx" + 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="$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 - 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" + # --- 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 [[ -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 +947,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 +984,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 +1000,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 +1033,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 +1061,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 From 0b2c5ad01ed221cf6a9f4f52c354b111d9bc28ef Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 7 Sep 2026 19:35:31 -0400 Subject: [PATCH 04/12] docs(claude-ops): state the sync algorithm once, with sync-run.sh as its executor The step bodies keep every rule and its reason and drop the inline bash a reader would otherwise retype: the redirect-project-loop shape, the per-step fleet-state.sh invocations, the catalog-regression jq, the run-directory and scratch-directory creation, and the marketplace enumeration loop are all sync-run.sh's, and the file now says what each step does and why rather than spelling out its shell twice. Step 5b is one call. The checker's JSON already carries the stale ids, so a second --ids pass recomputed the run's most expensive read; --ids is now the fallback for a JSON that could not be produced. A new "Execution" section carries the script's usage, what the model still owns (the install_new render, the journal root, and Step 6), and the ask-policy stop before Step 4 with its --only-install re-entry. Every section anchor is unchanged; the file loses 88 lines. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Pg4g2e7wXamNq2h4JeU8yg --- .../claude-ops/skills/plugins/context/sync.md | 356 +++++++----------- 1 file changed, 136 insertions(+), 220 deletions(-) diff --git a/plugins/claude-ops/skills/plugins/context/sync.md b/plugins/claude-ops/skills/plugins/context/sync.md index 0737e34f2e2..0fe654a2f5e 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: +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). -```bash -mkdir -p "$journal_root" -run_dir=$(mktemp -d "$journal_root/$(date -u +%Y%m%dT%H%M%SZ).XXXXXX") -``` - -`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". - -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: +- **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". -```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 -``` +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. -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: - -```bash -"${CLAUDE_PLUGIN_ROOT}"/skills/plugins/scripts/fleet-state.sh --marketplace "$mp" \ - >"$run_dir/pre-refresh.$mp.json" -``` +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. -**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 @@ -375,8 +345,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: @@ -445,13 +416,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). @@ -459,33 +426,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. @@ -550,11 +498,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 @@ -563,38 +507,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: @@ -602,19 +527,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 @@ -657,16 +572,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. @@ -680,8 +590,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` @@ -699,24 +616,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 @@ -734,10 +647,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 @@ -745,7 +659,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. From 38eb342910b462296f1986b044d8be14b3138e25 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 7 Sep 2026 19:35:55 -0400 Subject: [PATCH 05/12] feat(claude-ops): route plugins sync and audit through one script call The action router now spells the execution shape out: one bundled sync-run.sh call with the substituted journal root and the rendered install_new word, read the JSON digest, resolve an ask-policy install gap through the batched prompt and the --only-install re-entry, then emit the Report. context/sync.md loads when a digest carries errors, a gap, a catalog regression, or a cache finding, and when the user asks why a step behaved as it did. The policy is passed as a WORD, never as the ${user_config.install_new} token: an unset key leaves that token literal, and a literal token inside a command is a shell substitution error rather than a policy. The render itself, the Report template, and every scope, downgrade, stale-record, cache-content and reload guarantee are unchanged. Step 5b's contract line now says the checker runs once per marketplace and that --ids is the fallback for a JSON that could not be produced. The two evals that named fleet-state.sh as the thing the response calls now name sync-run.sh as the executor that takes those reads; no eval asserted the step-per-turn shape, so nothing else changed. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Pg4g2e7wXamNq2h4JeU8yg --- plugins/claude-ops/skills/plugins/SKILL.md | 61 ++++++++++++++++++- .../skills/plugins/evals/evals.json | 6 +- 2 files changed, 61 insertions(+), 6 deletions(-) diff --git a/plugins/claude-ops/skills/plugins/SKILL.md b/plugins/claude-ops/skills/plugins/SKILL.md index f7193f695fc..90d84e61f41 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 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" From dae6b84589f5981622ccc6afdeac518b776d04f3 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 7 Sep 2026 20:17:00 -0400 Subject: [PATCH 06/12] fix(claude-ops): keep an already-current id off the Updated row, and carry the state rows the report needs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three defects the first pass left in sync-run.sh, each one a report the operator would have had to distrust. An id the CLI answers with "already at the latest version" changed nothing, and a post-sweep snapshot cannot tell that apart from an update whose state write has not landed. The CLI line is now classified at capture time, so a no-op is dropped instead of rendering as `: -> unknown` under Updated: — on an already-current fleet that was most of the sweep. The move ledger writes an empty version as `-`. Tab is IFS whitespace, so two adjacent tabs collapse into one delimiter and an empty interior field shifted every later column left by one. The digest now carries the Report rows whose only source is a fleet-state read: the marketplace's autoUpdate, the stale project records with their distinct paths, the user-scope orphans, and the share of actionable divergences that belongs to the repo the run stands in. Step 4 also inspects the project-scope enabledPlugins map with --report-project after an install, which is a report row and never a write. The --only-install re-entry keeps the first pass's sweep rows, project_root and withheld downgrades, so the digest that supersedes the first one is still a whole-run report. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Pg4g2e7wXamNq2h4JeU8yg --- .../skills/plugins/scripts/sync-run.sh | 131 ++++++++++++++++-- .../skills/plugins/scripts/sync-run.test.sh | 37 ++++- 2 files changed, 148 insertions(+), 20 deletions(-) diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh index 65078682b16..f10b020e30c 100755 --- a/plugins/claude-ops/skills/plugins/scripts/sync-run.sh +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh @@ -46,12 +46,15 @@ # 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, refresh:{rc,output,predicted}, -# project_root, in_repo:{updated,failed,would_update}, +# 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, self_updated, errors} +# cache_content, catalog_regression, divergences, divergences_here, +# stale_project_records, user_scope_orphans, self_updated, errors} +# `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 @@ -347,6 +350,23 @@ cli_reported_version() { 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 @@ -503,9 +523,13 @@ reset_marketplace_state() { run_marketplace() { local mp="$1" reset_marketplace_state - : >"$RUN_DIR/moves.$mp.tsv" + # 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 row text out + local rc dg_rc id scope old new result row text out local pre_refresh="$RUN_DIR/pre-refresh.$mp.json" @@ -541,7 +565,22 @@ run_marketplace() { 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 fi # ---- Step 2 — in-repo update (the primary value path) ------------------------ @@ -582,7 +621,9 @@ run_marketplace() { continue fi cli_reported_version new "$CLI_OUT" - printf 'in_repo\t%s\t%s\t%s\t%s\n' "$id" "$scope" "$old" "$new" >>"$RUN_DIR/moves.$mp.tsv" + 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 @@ -629,7 +670,9 @@ run_marketplace() { continue fi cli_reported_version new "$CLI_OUT" - printf 'user_sweep\t%s\t%s\t%s\t%s\n' "$id" user "$old" "$new" >>"$RUN_DIR/moves.$mp.tsv" + 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 @@ -650,8 +693,14 @@ run_marketplace() { '{id: $id, rc: $rc, output: $out}')") continue fi - DOWNGRADED+=("$(jq -c -n --arg id "$id" --arg sc "$scope" --arg o "$old" --arg n "$new" \ - '{id: $id, scope: $sc, old: $o, new: $n}')") + # 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}')") @@ -773,8 +822,20 @@ run_install_step() { 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 + jq_to NORMALIZE_JSON -c -n --argjson rc "$nrc" --arg out "$nout" --arg mode "$MODE" \ - '{rc: $rc, output: $out, checked_only: ($mode == "audit")}' + --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 ---------------------------------------- @@ -884,10 +945,17 @@ cache_content_block() { # for a plugin that did. finalize_moves() { local mp="$1" - local kind id scope old new dir row post="$RUN_DIR/post.$mp.json" + 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; do + 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="" @@ -913,11 +981,39 @@ finalize_moves() { 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: {records: null, paths: []}, divergences_here: null}' + return 0 + fi + 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: {records: ($absent | length), + paths: ([$absent[] | .projectPath] | unique)}, + 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 - local reg_interval reg_rows div block + 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[@]}"} @@ -939,6 +1035,12 @@ emit_marketplace_block() { 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='[]' jq_to block -c -n \ --arg name "$mp" \ @@ -956,8 +1058,9 @@ emit_marketplace_block() { --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" ' - {name: $name, + $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, diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh index fbb6551cc1b..e431cdf66ad 100755 --- a/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh @@ -102,6 +102,13 @@ case "$verb" in 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"' \ @@ -352,7 +359,7 @@ assert_eq "--allow-downgrade: recorded in the digest" "true" \ # ============================================================================ CASE_NUM=$((CASE_NUM + 1)) case_dir=$(new_case_dir) -catalog_plugin "$case_dir" market1 alpha 0.1.0 +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, @@ -362,8 +369,10 @@ write "$case_dir/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\ 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=() +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" \ @@ -377,12 +386,18 @@ assert_exit "--only-install: exit 0" 0 $? 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")" -assert_eq "--only-install: the normalizer ran after the install" "1" \ - "$(wc -l <"$case_dir/normalize.log" | tr -d ' ')" +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 @@ -417,7 +432,7 @@ write "$case_dir2/known_marketplaces.json" "{\"market1\": {\"source\": {\"source 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" \ - "$(wc -l <"$case_dir2/normalize.log" | tr -d ' ')" + "$(grep -cv -- '--report-project' "$case_dir2/normalize.log")" # ============================================================================ # Case: an empty projection that EXITED 2 is an error, never "nothing to do" @@ -511,8 +526,18 @@ write "$case_dir/known_marketplaces.json" "{\"market1\": {\"source\": {\"source\ 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") +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.records' <<<"$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" \ From 3e29faaa0f5a796b08b151e782c31499f5595d99 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 7 Sep 2026 20:29:49 -0400 Subject: [PATCH 07/12] fix(claude-ops): take the --only-install re-entry's marketplaces from the run it re-enters The documented re-entry carries no marketplace argument, so with no target the run fell through to default-marketplace resolution: after a `--marketplace foo` or an `--all` first pass it would have performed Steps 4 and 5 against the default marketplace and emitted a one-block digest for a run that covered several. That is the silent partial sweep the marketplace-scoping rule exists to prevent. The re-entry now derives its marketplaces from the run directory's own pre-refresh snapshots, and a marketplace the run never swept is exit 2 with the reason rather than a run started under the wrong name. The suite exercises the documented form (no marketplace argument) and the refusal. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Pg4g2e7wXamNq2h4JeU8yg --- .../skills/plugins/scripts/sync-run.sh | 25 ++++++++++++++++++- .../skills/plugins/scripts/sync-run.test.sh | 12 ++++++++- 2 files changed, 35 insertions(+), 2 deletions(-) diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh index f10b020e30c..bb287c71905 100755 --- a/plugins/claude-ops/skills/plugins/scripts/sync-run.sh +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh @@ -1091,7 +1091,30 @@ setup_run_dir [[ -f "$JOURNAL_LOG" ]] || : >"$JOURNAL_LOG" MPS=() -if ((ALL == 1)); then +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 diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh index e431cdf66ad..650cd68b074 100755 --- a/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh @@ -381,8 +381,12 @@ assert_eq "ask: nothing installed" "0" "$(grep -c 'plugin install' "$case_dir/cl 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") -out2=$(run_sync "$case_dir" --marketplace market1 --only-install beta@market1 --run-dir "$run_dir") +# 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")" @@ -394,6 +398,12 @@ 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" \ From 2b72c0cd4cdfbb700c7ac9df2312892f79c1cf70 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 7 Sep 2026 20:45:17 -0400 Subject: [PATCH 08/12] perf(claude-ops): bump to 0.45.0 for the one-script plugins sync/audit path Steps 1-5b of the plugins skill's sync and audit now run through one sync-run.sh invocation with a JSON digest (2 model turns on a current fleet, was 14); cache-content-check.sh batches fleet-wide (400 spawns -> 17, ~100s -> ~15s on the authoring host); Step 5b calls the checker once instead of twice; a journal-creation failure now exits 2 before any mutation instead of degrading. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Pg4g2e7wXamNq2h4JeU8yg --- plugins/claude-ops/.claude-plugin/plugin.json | 2 +- plugins/claude-ops/CHANGELOG.md | 13 +++++++++++++ 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/plugins/claude-ops/.claude-plugin/plugin.json b/plugins/claude-ops/.claude-plugin/plugin.json index d32bc021255..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.3", + "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 af4d86e8b9c..f24461c331e 100644 --- a/plugins/claude-ops/CHANGELOG.md +++ b/plugins/claude-ops/CHANGELOG.md @@ -3,6 +3,19 @@ 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.** + ## [0.44.3] ### Fixed From ce26abe4b49769ac898cf7fe21697ebc5c7bd0eb Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 7 Sep 2026 21:10:40 -0400 Subject: [PATCH 09/12] fix(claude-ops): key the cache-content tree map by sha as well as source dir MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `tree_hash` was keyed `␟` while `owner_idx` and `g_seen` are keyed by sha too. Two records sharing one source directory at different `gitCommitSha` — the same plugin id at user and project scope, same version, one `installPath` — merged their trees: a file present only at the newer sha read as in-tree for the older record, never reached `extras_idx`, and a stale cache verdicted `match`. Reachable at `--scope project` and `--scope all`. The lookup in the cache-split pass now spells the same key. Every other map in the batch join was audited: `owner_idx`, `g_seen`, `uniq_seen` and `tree_rc_bad` already carry the sha; `cache_hash` and `extras_idx` are keyed per install record; `extra_seen`/`ignored` are sha-free on purpose, because a `.gitignore` answer does not depend on the commit. The new case builds a third commit whose only delta is one added file, so the older record's verdict rests on the extra-in-cache direction alone — the one the merged map suppressed. It fails on the unfixed script and passes on the fixed one. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Pg4g2e7wXamNq2h4JeU8yg --- .../plugins/scripts/cache-content-check.sh | 10 +++- .../scripts/cache-content-check.test.sh | 50 +++++++++++++++++++ 2 files changed, 58 insertions(+), 2 deletions(-) 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 8a458c4fe54..6f273ca7bba 100755 --- a/plugins/claude-ops/skills/plugins/scripts/cache-content-check.sh +++ b/plugins/claude-ops/skills/plugins/scripts/cache-content-check.sh @@ -667,7 +667,13 @@ check_marketplace() { idx=${#tree_rel[@]} tree_rel+=("$rel") tree_blob+=("$blob") - tree_hash["$owner"$'\x1f'"$rel"]="$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" done done @@ -781,7 +787,7 @@ check_marketplace() { for cache_i in ${root_files[$rt]:-}; do f="${cache_full[cache_i]}" rel="${cache_rel[cache_i]}" - src_key="$src_dir"$'\x1f'"$rel" + 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" 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..4c3fe904385 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,56 @@ 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)" + # ============================================================================ # 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 From 2fc813d32c6ed60b52683678c8056ef12fe61bcc Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Mon, 7 Sep 2026 21:11:02 -0400 Subject: [PATCH 10/12] fix(claude-ops): give the report's In-repo, stale-path and cache-content rows a digest source MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three Report rows could not be rendered from the digest: - `In-repo:` chose between its three variants from `project_root` and the intersection of `currentProject` records with the divergences, so a current fleet inside a repo that HAS project/local installs rendered as "0 — has no project/local installs", which is false. The digest now carries `in_repo_records` (and `in_repo_ids`), the count of records belonging to the root regardless of whether any moved, and SKILL.md keys the three variants off `project_root` null / `in_repo_records == 0` / `> 0` with `in_repo.updated | length` as the count. - `Stale project records` needs a count per path: `stale_project_records` is now `{total, by_path:[{path,count}]}` instead of `{records, paths}`. - `Cache content` needs a per-id ` — file(s) differ`: `cache_content.stale[]` is derived from the checker JSON already on disk, summing all three directions of disagreement. `stale_ids` stays alongside it. Also: - `self_updated` scanned only the user sweep and the downgrades. A project/local record for this plugin that Step 2 moved is the same self-update, so `IR_UPDATED` joins the scan. - `--allow-downgrade` is now persisted in the run directory and honoured on an `--only-install` re-entry, which otherwise rebuilt the withheld list from the run's own downgrade projection and reported a rollback the first pass had already applied. A run directory without the file keeps the previous behaviour. - `proj_err` bounds its own output through `trunc` rather than leaving each of its six call sites to embed unbounded stderr in a digest string. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Pg4g2e7wXamNq2h4JeU8yg --- plugins/claude-ops/skills/plugins/SKILL.md | 27 ++++-- .../claude-ops/skills/plugins/context/sync.md | 5 ++ .../skills/plugins/scripts/sync-run.sh | 79 +++++++++++++--- .../skills/plugins/scripts/sync-run.test.sh | 89 ++++++++++++++++++- 4 files changed, 181 insertions(+), 19 deletions(-) diff --git a/plugins/claude-ops/skills/plugins/SKILL.md b/plugins/claude-ops/skills/plugins/SKILL.md index 90d84e61f41..ef5e6349b07 100644 --- a/plugins/claude-ops/skills/plugins/SKILL.md +++ b/plugins/claude-ops/skills/plugins/SKILL.md @@ -242,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) @@ -286,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: @@ -350,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: @@ -404,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 0fe654a2f5e..e7649244381 100644 --- a/plugins/claude-ops/skills/plugins/context/sync.md +++ b/plugins/claude-ops/skills/plugins/context/sync.md @@ -409,6 +409,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, diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh index bb287c71905..a384b3476b4 100755 --- a/plugins/claude-ops/skills/plugins/scripts/sync-run.sh +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh @@ -52,7 +52,12 @@ # downgraded, install_gap, installed, install_enable_deferred, # stopped_before_install, enable_gap, enabled, project_enable_rows, normalize, # cache_content, catalog_regression, divergences, divergences_here, -# stale_project_records, user_scope_orphans, self_updated, errors} +# 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 @@ -378,12 +383,6 @@ project_ids() { return $? } -proj_err() { - local text="" - [[ -f "$RUN_DIR/.proj-err" ]] && text=$(<"$RUN_DIR/.proj-err") - printf '%s' "${text//$'\r'/}" -} - # 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() { @@ -395,6 +394,16 @@ trunc() { 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, @@ -767,7 +776,11 @@ run_marketplace() { local own own=$(own_plugin_name) if [[ -n "$own" ]]; then - for row in ${US_UPDATED[@]+"${US_UPDATED[@]}"} ${DOWNGRADED[@]+"${DOWNGRADED[@]}"}; do + # 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 @@ -918,10 +931,18 @@ cache_content_block() { 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 @@ -932,9 +953,14 @@ cache_content_block() { 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. 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, source: "ids-fallback"}' + skipped_absent_project_paths: null, stale_ids: $ids, + stale: ($ids | map({id: ., version: null, files_differ: null})), + source: "ids-fallback"}' } # --- version capture -------------------------------------------------------------- @@ -995,17 +1021,27 @@ report_extras() { done if [[ -z "$src" ]]; then jq_to "$__var" -c -n '{auto_update: null, user_scope_orphans: [], - stale_project_records: {records: null, paths: []}, divergences_here: null}' + 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. 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: {records: ($absent | length), - paths: ([$absent[] | .projectPath] | unique)}, + 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" } @@ -1087,6 +1123,25 @@ emit_marketplace_block() { # --- 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" diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh index 650cd68b074..757dbd3a572 100755 --- a/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh @@ -162,7 +162,10 @@ fi cat < Date: Mon, 7 Sep 2026 21:37:21 -0400 Subject: [PATCH 11/12] fix(claude-ops): mark sync-run's jq programs and placeholder literals for shellcheck CI lints at info severity: SC2016 on eleven single-quoted jq programs and test literals (every $var there is jq's or the unrendered placeholder under test), and SC2249 on the self-update case. Same line-level directive the sibling scripts use, plus an explicit default arm. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Pg4g2e7wXamNq2h4JeU8yg --- plugins/claude-ops/skills/plugins/scripts/sync-run.sh | 10 ++++++++++ .../claude-ops/skills/plugins/scripts/sync-run.test.sh | 2 ++ 2 files changed, 12 insertions(+) diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh index a384b3476b4..f3ca88d4599 100755 --- a/plugins/claude-ops/skills/plugins/scripts/sync-run.sh +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh @@ -314,6 +314,7 @@ version_direction() { # 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" } @@ -459,6 +460,7 @@ catalog_regression_rows() { 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 @@ -494,6 +496,7 @@ divergence_block() { 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]; @@ -783,6 +786,7 @@ run_marketplace() { ${DOWNGRADED[@]+"${DOWNGRADED[@]}"}; do case "$row" in *"\"id\":\"$own@"*) SELF_UPDATED="true" ;; + *) ;; esac done fi @@ -845,6 +849,7 @@ run_install_step() { 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"), @@ -876,6 +881,7 @@ run_enable_step() { 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), @@ -956,6 +962,7 @@ cache_content_block() { # 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, @@ -1031,6 +1038,7 @@ report_extras() { # 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 @@ -1078,6 +1086,7 @@ emit_marketplace_block() { [[ -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" \ @@ -1223,6 +1232,7 @@ 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" \ diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh index 757dbd3a572..c867d244b6e 100755 --- a/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh @@ -233,10 +233,12 @@ 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")" From 1a0c72399b1d22f89f5fa7aeee0d3abb356e7eea Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Tue, 8 Sep 2026 01:43:10 +0000 Subject: [PATCH 12/12] fix(claude-ops): keep first-pass sync failures across --only-install An ask-policy re-entry reset IR_FAILED, US_FAILED, and MP_ERRORS, so the replacement digest could report a successful sync while a plugin stayed stale. Persist those rows (and the refresh digest fields) in the run directory and restore them on re-entry. The batched cache-content join now attaches each blob to every matching source directory, not only the longest, so nested marketplace sources keep the same expected trees the per-source ls-tree produced. Co-authored-by: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> --- plugins/claude-ops/CHANGELOG.md | 14 +++++ .../plugins/scripts/cache-content-check.sh | 37 +++++------ .../scripts/cache-content-check.test.sh | 61 +++++++++++++++++++ .../skills/plugins/scripts/sync-run.sh | 60 ++++++++++++++++++ .../skills/plugins/scripts/sync-run.test.sh | 36 +++++++++++ 5 files changed, 190 insertions(+), 18 deletions(-) diff --git a/plugins/claude-ops/CHANGELOG.md b/plugins/claude-ops/CHANGELOG.md index 95434fd3ea8..2951b8411f7 100644 --- a/plugins/claude-ops/CHANGELOG.md +++ b/plugins/claude-ops/CHANGELOG.md @@ -16,6 +16,20 @@ All notable changes to the `claude-ops` plugin are documented here. Format follo - **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/scripts/cache-content-check.sh b/plugins/claude-ops/skills/plugins/scripts/cache-content-check.sh index 6f273ca7bba..6e095822262 100755 --- a/plugins/claude-ops/skills/plugins/scripts/cache-content-check.sh +++ b/plugins/claude-ops/skills/plugins/scripts/cache-content-check.sh @@ -648,33 +648,34 @@ check_marketplace() { *" blob "*) ;; *) continue ;; esac - # Which source directory this entry belongs to. Longest match wins, and - # the path itself is tried first so a `source` naming a single file still - # resolves the way a single-pathspec call resolved it. - owner="" + # 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" - break + 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 [[ "$walk" == */* ]] || break walk="${walk%/*}" done - [[ -n "$owner" ]] || continue - 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" done done # A multi-pathspec ls-tree cannot report "this one pathspec matched nothing", 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 4c3fe904385..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 @@ -760,6 +760,67 @@ 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 index f3ca88d4599..dd7fdeb7a26 100755 --- a/plugins/claude-ops/skills/plugins/scripts/sync-run.sh +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.sh @@ -531,6 +531,60 @@ reset_marketplace_state() { 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" @@ -593,6 +647,7 @@ run_marketplace() { '{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) ------------------------ @@ -1057,6 +1112,11 @@ report_extras() { 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[@]}"} diff --git a/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh index c867d244b6e..46e439a77b6 100755 --- a/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh +++ b/plugins/claude-ops/skills/plugins/scripts/sync-run.test.sh @@ -322,6 +322,42 @@ assert_eq "failed update: NOT recorded as updated" "0" \ 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