feat(scan): unified auto-update engine — --sync, --prune, --dry-run (v3.0)#79
Merged
Merged
Conversation
…flows
Enables `socket-patch scan` as the engine for an automated "update all
patches" workflow — a cron job or PR check that runs scan, detects new
or updated patches against the local manifest, applies them, and either
commits the change or opens a PR. Today this isn't quite possible because:
* `scan --json` is read-only — it prints the discovery JSON and exits
before the apply path runs, so there's no clean way to make it
mutate the manifest from a bot.
* Updates aren't reported in JSON — update detection (existing
manifest entry with same PURL but different UUID) only runs in the
non-JSON table-print path, so a `--json` consumer can't tell which
patches would be updates vs net-new additions.
* Per-patch JSON records lose the added-vs-updated distinction — every
successful download is reported as `action: "added"` even when it's
replacing an existing entry with a newer UUID.
Three additive (semver-MINOR) changes resolve all of the above:
1. `commands/get.rs` — `download_and_apply_patches` now emits per-patch
`{action: "updated", oldUuid}` when the PURL already had a different
UUID before insert. A new pure helper `decide_patch_action(manifest,
purl, new_uuid)` returns `Added | Updated{old_uuid} | Skipped` and is
unit-tested independently.
2. `commands/scan.rs` — new `--apply` flag (default `false`) opts JSON
callers into the full discover → select → apply pipeline. Without
`--apply`, `scan --json` keeps its prior read-only contract; with it,
`scan --json --apply` runs the same selection + download path the
non-JSON branch uses and emits one combined JSON object with an
`apply` sub-object reporting per-patch outcomes. The JSON discovery
emission also now always includes a top-level `updates` array (with
`purl`, `oldUuid`, `newUuid`) computed via a new pure helper
`detect_updates`. `severity_order` is exposed as `pub(crate)` so it
can be unit-tested.
3. `CLI_CONTRACT.md` documents the new `--apply` flag, the full
`scan` discovery and `--apply` JSON shapes, and pins the per-patch
action vocabulary (`added`/`updated`/`skipped`/`failed`) with semver
policy clauses for adding (MINOR) or renaming/removing (MAJOR) values.
## Tests
* scan.rs inline #[cfg(test)] mod tests — 4 severity_order cases +
8 detect_updates cases covering: no manifest, empty packages, no
overlap, same UUID, different UUID, multiple updates, empty patch
list, first-patch candidate selection.
* get.rs inline test module — 4 decide_patch_action cases covering
Added (no existing entry), Skipped (same UUID), Updated (different
UUID with oldUuid populated), and Added-for-different-PURL (keying
on PURL not UUID).
* tests/cli_parse_scan.rs — `--apply` parser tests (defaults false,
long form, combines with --json/--yes) + a subprocess JSON-shape
test that runs the compiled binary against an empty tempdir and
asserts the new `updates: []` key is present in stdout.
All 416 lib tests pass, all integration tests pass, clippy clean.
## How a bot uses this
```bash
socket-patch scan --json --apply --yes > scan-result.json
jq '.apply.patches[] | select(.action == "updated") | {purl, oldUuid, uuid}' scan-result.json
# Pipe into peter-evans/create-pull-request with a PR body summarizing the diff.
```
Exit code: 0 on full success (every selected patch added/updated/skipped),
1 if any `failed` records are present (and top-level `status` becomes
`"partial_failure"`).
Assisted-by: Claude Code:claude-opus-4-7
After PR #79's --apply work, scan applied patches but didn't reconcile state. Orphan blob files accumulated and manifest entries for uninstalled packages stayed forever, forcing bots to chain `scan --apply` with `repair` themselves. This commit makes scan the single command needed for the auto-update workflow: * Default GC after every scan run that has scanned packages. Removes manifest entries for PURLs no longer in the crawl results, then sweeps orphan blob/diff/package-archive files via the existing cleanup_unused_blobs / cleanup_unused_archives helpers. * New --no-prune flag opts OUT of GC entirely. Useful when a missing package reflects a temporary uninstall the user wants to preserve. * The `gc` subcommand alias (and `repair` itself) is hidden from socket-patch --help. `socket-patch gc` still parses for backwards compat, just no longer listed. Existing scripts unaffected. * Workspace version bumped 2.1.4 → 3.0.0. scripts/version-sync.sh propagated the bump to every npm/socket-patch-* package.json and to pypi/socket-patch/pyproject.toml. ## JSON output additions In `scan --json` (read-only): new `gc` sub-object reports what *would* be pruned/reaped without mutating anything (preview mode). Fields: prunableManifestEntries, orphanBlobs, orphanDiffArchives, orphanPackageArchives, bytesReclaimable. In `scan --json --apply`: `gc` switches to mutation mode. Fields: prunedManifestEntries, removedBlobs, removedDiffArchives, removedPackageArchives, bytesFreed. With --no-prune: gc is emitted as { "skipped": true } in both modes. In the empty-crawl case (no packages found at all), gc is { "skipped": true } — pruning every manifest entry on the assumption the user "uninstalled everything" is too destructive. ## Tests * 5 new detect_prunable unit tests covering empty manifest, all present, missing entries, and full prune. * --no-prune parser tests in tests/cli_parse_scan.rs (default false, long form, combines with --apply/--json/--yes). * 4 new tests in tests/cli_parse_repair.rs locking the v3.0 deprecation: top-level --help doesn't list `repair` or `[aliases: gc]`, but `socket-patch gc` still resolves to Repair and `socket-patch repair --help` still works directly. * CleanupResult gains #[derive(Default)] so scan can build empty summaries when the cleanup helpers report errors. cargo build/clippy/test --workspace --all-features all clean. 100 lib tests in CLI (+5), 19 in cli_parse_repair (+4), 26 in cli_parse_scan (+2). 416 lib tests in core unchanged. ## Breaking changes (MAJOR bump 2.1.4 → 3.0.0) * scan --apply prunes manifest entries for uninstalled packages by default. Scripts that ran `scan --apply --yes` and relied on manifest entries surviving across an uninstall break unless they add --no-prune. * scan --apply removes orphan blob/archive files on every run (non-breaking in practice — the apply path simply re-fetches anything it needs — but a visible filesystem change). * `socket-patch gc` no longer appears in top-level --help. The subcommand still works. Assisted-by: Claude Code:claude-opus-4-7
End-to-end tests for the scan + GC pipeline that uses the real Socket API. Mirrors the structure of tests/e2e_npm.rs — every test is #[ignore] so it only runs with --ignored, matching the existing e2e gating in .github/workflows/ci.yml. Uses the minimist@1.2.2 patch fixture (CVE-2021-44906) that the other e2e tests already share. ## Coverage (9 scenarios) * test_scan_apply_json_adds_new_patch — fresh install, `scan --json --apply --yes` reports action: "added" and patches the file on disk. * test_scan_apply_json_skips_existing — re-run shows action: "skipped". * test_scan_apply_json_updates_existing — seed manifest with a fake UUID, re-run shows action: "updated" with oldUuid populated. * test_scan_json_read_only_emits_updates_array — read-only mode surfaces the manifest-vs-API drift in the `updates` array. * test_scan_json_read_only_no_mutation — `scan --json` never creates a manifest or modifies files. * test_scan_apply_prunes_uninstalled_package_by_default — uninstall minimist, re-scan, manifest entry is gone + blobs are reaped. * test_scan_apply_no_prune_keeps_uninstalled_entries — same scenario with --no-prune leaves manifest + blobs intact, gc reports { skipped: true }. * test_scan_apply_cleans_orphan_blobs — plant a stray orphan blob, next scan run removes it and reports gc.removedBlobs >= 1. * test_scan_json_read_only_gc_preview — preview mode lists prunableManifestEntries and counts orphanBlobs without mutating. ## CI integration * Added e2e_scan to the e2e job matrix on ubuntu-latest and macos-latest (mirrors how e2e_npm is matrixed). * Setup Node.js step's `if:` predicate extended to also run for e2e_scan — the suite shells out to `npm install` for fixture setup. Each #[ignore] test self-skips with a SKIP message if `npm` is not on PATH, so a future runner without npm doesn't fail spuriously. Assisted-by: Claude Code:claude-opus-4-7
CLI_CONTRACT.md changes:
* Add --no-prune row to the scan flag table with a description of
the v3.0 GC default.
* Extend the scan JSON output shape with the new `gc` sub-object.
Document the split between preview-mode field names
(prunable*/orphan*/bytesReclaimable) and apply-mode field names
(pruned*/removed*/bytesFreed). Document that --no-prune emits
gc: { skipped: true } in both modes.
* Mark `repair` as "(deprecated since v3.0)" at the section heading.
Spell out the demotion: `hide = true` on the Repair variant and
`alias = "gc"` (was `visible_alias`). Removing repair or
unhiding it would be a MAJOR bump.
* Add semver-policy row: "Change `scan`'s default behavior (e.g.
pruning, GC, apply) — MAJOR." Notes the v3.0 flip is the one
grandfathered instance; future flips also MAJOR.
README.md changes:
* Remove the `repair`/`gc` section from the public command list (still
documented in CLI_CONTRACT.md for advanced users).
* Expand the `scan` section: add --apply and --no-prune flags,
-y/--yes, --download-mode rows. New "Bot mode" example with
`scan --json --apply --yes`. Add "Apply without pruning" example.
Brief note about scan being the single command for the
auto-update workflow.
Assisted-by: Claude Code:claude-opus-4-7
Mikola Lysenko (mikolalysenko)
changed the title
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
The free-tier patch API may serve multiple free patches for the same
PURL (e.g., minimist@1.2.2 currently has 2 free patches). The
`scan --json --apply` path was calling `select_patches(... is_json =
true)` which returns `Err(JsonModeNeedsExplicit)` with
`status: "selection_required"` in that scenario — no forward progress,
the bot can't apply anything.
For scan-driven workflows there's no "specify --id" option (we're
scanning the whole project), so the right behavior is to auto-select
the newest patch and continue. Pass `is_json = false` so the
non-TTY branch inside `select_one` auto-selects index 0 — which is the
most-recently-published patch (the group is sorted by `published_at`
descending before `select_one` runs).
Also relaxed the e2e_scan test assertions so they don't pin a specific
upstream UUID/hash:
* added/updated/skipped tests assert action vocabulary, PURL match,
and "file was patched" (not exact AFTER_HASH).
* updated test asserts the new UUID differs from the seeded oldUuid
rather than matching a hardcoded constant.
* read-only updates test similarly asserts `newUuid != oldUuid`.
These changes make the e2e suite robust to API churn — the contract
is "an apply happened", not "this specific patch was selected".
Assisted-by: Claude Code:claude-opus-4-7
The post-uninstall scenario hit an edge case: after a user uninstalls the only patched package and installs a new (unpatched) one, the next `scan --apply --yes` would crawl successfully, find no packages with patches, and skip the entire `--apply` block. The read-only preview GC ran instead, emitting `gc.prunableManifestEntries` (preview field name) but never actually pruning anything from the manifest. A bot relying on `scan --apply` to reach a clean state would loop forever — the stale manifest entry never gets removed. Fix: when `--apply` is set but no packages have patches, still run the mutating GC pass and emit an empty `apply` sub-object plus the `gc.prunedManifestEntries` (apply field name). Bots can now trust `scan --apply --yes` to converge to a clean state in one pass even when the crawl has no patched packages. Also dropped the now-unused `NPM_UUID` and `AFTER_HASH` constants from the e2e_scan test file (warning noise from relaxing the assertions in the previous commit). Assisted-by: Claude Code:claude-opus-4-7
Reverses the v3.0 GC-by-default decision. After feedback, default-on
GC was too aggressive: scripts running `scan --apply --yes` against a
project with a temporarily-uninstalled package would silently destroy
the manifest entry, breaking dev workflows where the package gets
reinstalled later.
The new opt-in model:
* `--prune` (new, default false) opts into garbage collection.
Manifest entries for packages no longer in the crawl are removed,
then `cleanup_unused_blobs` + `cleanup_unused_archives` sweep
orphan files. Without `--prune`, scan leaves `.socket/` alone.
* `--sync` (new) is sugar for `--apply --prune`. The canonical bot
invocation becomes `scan --json --sync --yes` (3 flags; `--json`
and `--yes` are workflow scaffolding).
* `--dry-run` / `-d` (new) previews what `--apply`/`--prune`/`--sync`
would do without mutating disk. The `apply.patches[*]` array is
populated via `decide_patch_action`, and `gc.prunable*` /
`gc.orphan*` field names are emitted (instead of `pruned*` /
`removed*`). The `apply.dryRun: true` flag explicitly marks the
output for bots that need a single signal.
* `--no-prune` field removed (it was the inverse of the now-default
behavior).
## Implementation
* `ScanArgs.no_prune` → `ScanArgs.prune` (semantics inverted). New
`sync` and `dry_run` fields.
* At the top of `scan::run`, `let apply = args.apply || args.sync;`
and `let prune = args.prune || args.sync;` — derive once, use
everywhere downstream. `--sync` is purely additive sugar.
* `run_apply_gc` no longer takes a `no_prune: bool` parameter —
callers always gate on `prune` before calling it. When GC isn't
requested, the `gc` JSON field is omitted entirely (no
`{ "skipped": true }` placeholder).
* New `preview_apply_gc` helper for the dry-run path. Runs
`cleanup_unused_blobs` / `cleanup_unused_archives` with
`dry_run=true` and emits preview field names via
`GcSummary::to_preview_json`.
* Dry-run apply path synthesizes per-patch `apply.patches[]`
records via `super::get::decide_patch_action` against the on-disk
manifest — accurately reports added/updated/skipped for the
selected patches without actually calling
`download_and_apply_patches`.
* Empty-cwd JSON branch drops `gc: { skipped: true }` (no `gc`
field at all when GC wasn't requested).
Drive-by fix: `tests/ecosystem_dispatch::partition_purls_allow_list_excludes_one`
now uses `!map.contains_key(&Ecosystem::Pypi)` instead of the
`unnecessary_get_then_check` lint trigger.
Assisted-by: Claude Code:claude-opus-4-7
The prior v3.0 iteration demoted `Commands::Repair`'s `gc` alias to a
hidden `alias = "gc"` and added `hide = true` on the subcommand itself,
banking on `scan` becoming the all-in-one command for both apply and
GC. With GC now opt-in via `--prune`/`--sync` (see prior commit),
`repair`/`gc` is the right answer for users who want to clean up
without an apply pass.
Restore `#[command(visible_alias = "gc")]` and drop `hide = true` so
the subcommand appears in `socket-patch --help` again with its
`[aliases: gc]` hint.
Update the four hidden-help tests in `tests/cli_parse_repair.rs`:
* `repair_is_hidden_from_top_level_help` →
`repair_appears_in_top_level_help` (assertion inverted).
* `gc_alias_is_hidden_from_top_level_help` →
`gc_alias_is_visible_in_top_level_help` (assertion inverted).
* `gc_alias_still_parses_for_backwards_compat` →
`gc_alias_parses_as_repair` (simplified — alias is no longer
deprecated, so the "backwards compat" framing is gone).
* `repair_subcommand_help_still_works_directly` dropped (was a
deprecation-era assertion).
These tests now lock the *opposite* contract: removing or hiding the
`gc` alias is a MAJOR bump.
Assisted-by: Claude Code:claude-opus-4-7
cli_parse_scan.rs:
* defaults_match_contract now asserts !args.prune, !args.sync,
!args.dry_run (replacing the old !args.no_prune line).
* no_prune_flag_long_form → prune_flag_long_form; assertion
inverted (passing --prune sets prune=true).
* no_prune_combines_with_apply_and_json → prune_combines_with_apply_and_json.
* NEW: sync_flag_long_form — --sync sets sync=true; does NOT
auto-derive --apply/--prune at parse time (that derivation
happens inside scan::run).
* NEW: sync_combines_with_json_and_yes.
* NEW: dry_run_long_form (--dry-run sets dry_run=true).
* NEW: dry_run_short_form (-d sets dry_run=true).
e2e_scan.rs:
* Module docstring updated to describe opt-in GC.
* test_scan_apply_prunes_uninstalled_package_by_default →
test_scan_apply_prune_prunes_uninstalled_package — now passes
--prune explicitly.
* test_scan_apply_no_prune_keeps_uninstalled_entries →
test_scan_apply_default_keeps_uninstalled_entries — drops the
--no-prune flag (it no longer exists); asserts the gc field is
omitted entirely.
* test_scan_apply_cleans_orphan_blobs →
test_scan_apply_prune_cleans_orphan_blobs — passes --prune.
* test_scan_json_read_only_gc_preview split into:
- test_scan_dry_run_sync_previews_apply_and_gc — exercises the
new --dry-run flag combined with --sync; verifies preview
output is populated AND nothing on disk changed.
- test_scan_json_no_gc_field_without_prune — locks the contract
that `gc` is omitted when --prune isn't set.
* NEW: test_scan_sync_yes_full_lifecycle — installs minimist, runs
--sync (adds patch), uninstalls + plants orphan, runs --sync again
(prunes + sweeps). End-to-end exercise of the canonical bot mode.
Total e2e_scan scenarios: 11 (was 9).
Assisted-by: Claude Code:claude-opus-4-7
CLI_CONTRACT.md:
* Scan flag table: replace --no-prune row with three new rows —
--prune, --sync, -d/--dry-run. Add a paragraph explaining each
plus the canonical bot-mode invocation.
* JSON output shape: drop the --no-prune-emits-{skipped:true} note.
Clarify that `gc` is omitted ENTIRELY when --prune/--sync isn't
set. Document --dry-run behavior including the explicit
`apply.dryRun: true` marker for bots.
* New "scan — --sync (bot mode)" section with the canonical
`scan --json --sync --yes | jq '{applied, pruned, bytes_freed}'`
recipe.
* New "scan — --dry-run" section explaining that --dry-run is a
no-op without one of the mutating flags.
* Restore the `repair` section's normal heading (drop the
"*(deprecated since v3.0)*" suffix and the deprecation paragraph).
Note that the `gc` visible_alias is now contract-guarded.
* Semver-policy table: drop the GC-default row, add explicit rows
for "flipping --prune to opt-out" and "demoting `gc` from
visible_alias" — both MAJOR.
README.md:
* Restore the `### repair` / `gc` section that was removed during
the deprecation iteration. Wording clarifies that `repair`/`gc` is
the right answer for cleanup-without-apply and points users at
`scan --sync` for the combined workflow.
* `### scan` section: replace --no-prune row with --prune, --sync,
--dry-run, --yes. Bot-mode example becomes `scan --json --sync --yes`
(the user's "one or two flags" target). Add a `scan --json --sync
--yes --dry-run` example.
* `## Scripting & CI/CD`: lead with the new `--sync` recipe piped
through jq into `peter-evans/create-pull-request`. Keep the old
`scan --json --ecosystems npm` read-only example as the second
use case.
Assisted-by: Claude Code:claude-opus-4-7
Mikola Lysenko (mikolalysenko)
changed the title
- rust-toolchain.toml: pin channel to exact version with components
- Cargo.toml: exact-pin all workspace dependencies via =X.Y.Z spec
- crates/{cli,core}/Cargo.toml: wire dev-deps through workspace pins
- npm/socket-patch/package.json: exact-pin runtime + dev deps; commit
package-lock.json so downstream installs are deterministic
- scripts/install.sh: download SHA256SUMS, verify tarball digest
before extraction; accept SOCKET_PATCH_VERSION env override
- scripts/version-sync.sh: preserve the leading = on exact-pin specs;
refresh the npm lockfile on every version bump
- .github/workflows/release.yml: SHA-pin actions, pin npm@version,
pin language toolchain versions for setup-* actions
- .github/workflows/pin-check.yml: new fail-closed workflow that
greps every uses: line and rejects non-SHA-pinned action refs
Two related changes that together complete the v3.0 contract:
* apply no longer writes to .socket/. When the manifest is missing
blobs in offline mode, apply bails with a partial_failure envelope.
When online and missing blobs need fetching, the bytes go to an OS
tempdir overlay for the duration of the run; .socket/ stays read-
only. Garbage collection moves out of apply entirely (now lives in
scan --prune / repair / gc).
* New crates/socket-patch-cli/src/json_envelope.rs defines a shared
Envelope/PatchEvent/Status/Summary shape that every --json
invocation now emits. The action vocabulary (added/updated/skipped/
applied/downloaded/removed/failed/verified) is the single contract
downstream consumers route on. CLI_CONTRACT.md is updated with the
unified shape + jq recipes.
Migrated commands: apply, list, repair, remove. (scan, get, rollback,
setup retain their pre-v3.0 shapes for now and are documented as
pending in CLI_CONTRACT.md.)
Also removes three dead-code items the audit confirmed have zero
callers:
- crates/socket-patch-core/src/utils/enumerate.rs (whole module)
- crates/socket-patch-core/src/utils/global_packages.rs (whole
module; npm crawler ships the live copy)
- path_to_group_id() in maven_crawler (test-only inverse helper)
- false-positive allow(dead_code) on get.rs::DownloadParams
BREAKING: every migrated subcommand's --json output is reshaped to the
new envelope (camelCase status, events array, summary block).
Adds ~120 new tests across the apply/scan/get/list/remove/repair/ rollback/setup CLI commands. Tests drive socket-patch in-process (commands::*::run) and via subprocess against wiremock-backed API fixtures, asserting on disk state, JSON envelope shape, and exit codes. Includes: * apply: invariants test (no .socket/ mutation), network tests with wiremock, edge cases (read-only files, nested dirs, multi-file, hash mismatch, idempotent re-apply, missing files, force overrides) * scan: invariants, sync end-to-end, dry-run preview, --apply + --prune combinations * get: identifier-type detection (UUID/CVE/GHSA/PURL/package), --save-only path, paid_required path, error paths, edge cases * repair: download-mode variants (file/diff/package), offline mode, blob cleanup verification * remove: PURL + UUID identifiers, rollback chain, blob cleanup * rollback: real bytes restore for all 8 ecosystems via handcrafted fixtures + real installer paths * setup: package.json detection, pnpm monorepo handling, dry-run * PTY-driven interactive prompt tests (portable-pty) * Alternate installer configs: yarn, pnpm, npm workspaces, bundler * Python venv variants: 3.11/3.12/3.13, .env/venv/.venv layouts, VIRTUAL_ENV override, canonical name normalization, egg-info legacy Real package managers are used where available on host (npm, pip, gem, cargo); ecosystems without host toolchains (go/maven/composer/ nuget) use handcrafted fixtures that exactly mirror what their native installers produce on disk.
* New 'coverage' job: cargo-llvm-cov (LLVM source-based instrumentation
via taiki-e/install-action), uploads lcov.info as a workflow artifact
and prints the summary to the GitHub Actions job summary. Report-only
(no --fail-under threshold) so contributors get visibility without
flaky CI when coverage shifts.
* Language toolchain pins on every setup-* action invocation: Node
20.20.2, Python 3.12.13, Ruby 3.2.11. dtolnay/rust-toolchain now
reads from rust-toolchain.toml (the toolchain: stable input is
dropped from every step).
* New 'e2e-docker' matrix: ubuntu-latest x { npm, pypi, gem, cargo,
golang, maven, composer, nuget }. Each slot builds the shared base
image and the per-ecosystem layer via docker/build-push-action with
scope-cached layers (type=gha,scope=test-<eco>), then runs the
corresponding 'cargo test --features docker-e2e --test
docker_e2e_<eco>'. Triggered on every PR. The existing 'e2e' job
(real Socket API, --ignored) stays for nightly/manual real-API
smoke runs.
Adds the Docker-driven e2e test infrastructure: * tests/docker/Dockerfile.base: multi-stage build (rust:1.93-slim- bookworm builder → debian:12-slim runtime + compiled socket-patch). Base layer shared by every ecosystem image. Both base images pinned by sha256 digest. * tests/docker/Dockerfile.npm: FROM base + Node 20 LTS via NodeSource. * tests/docker/README.md: how to build images locally, run tests with Docker or with SOCKET_PATCH_TEST_HOST=1 host mode, and how to add a new ecosystem. * tests/docker/fixtures/npm/README.md: documents the synthetic fixture approach (--force apply against any installed bytes). * docker_e2e_npm.rs: real 'npm install minimist@1.2.2' inside the container, wiremock served patch, scan --sync writes manifest + blob, apply --force overwrites the on-disk file, then grep-verifies SOCKET-PATCH-E2E-MARKER in node_modules/minimist/index.js. Hermetic (no Socket API contact); reproducible in CI. This is the working template every other ecosystem extends.
Upgrades docker_e2e_pypi.rs from scan-discovery-only to the full chain, twice: once for local (venv) install and once for global (pip --break-system-packages). * Switches the fixture package from pydantic-ai (heavy transitive deps, ~60s install) to six 1.16.0 (single-file, ~1s install). * pypi's file-path convention has NO `package/` prefix — the python crawler returns site-packages root as pkg_path, so the patch's file path is just `six.py` (lands at site-packages/six.py). * `pypi_local_install_full_apply_chain`: venv install at .venv/lib/ python3.X/site-packages/six.py, scan --sync writes manifest + blob, apply --force --offline overwrites the file. Grep verifies SOCKET-PATCH-E2E-MARKER on disk. * `pypi_global_install_full_apply_chain`: pip install --break- system-packages installs into Debian's system Python site- packages. scan + apply with --global. Same marker verification at the system-site-packages path discovered via `python3 -c "import six; print(six.__file__)"`. The Dockerfile.pypi already has python3 + pip + venv from prior infrastructure work; no Dockerfile change.
Two tests for the Ruby ecosystem: * gem_local_install_full_apply_chain: `gem install --install-dir vendor/bundle/ruby/<ver> colorize -v 1.1.0` produces the bundle- style layout that the Ruby crawler scans in local mode. scan --sync + apply --force overwrites lib/colorize.rb with the synthetic patched content; marker verified on disk. * gem_global_install_full_apply_chain: plain `gem install colorize -v 1.1.0` (no --install-dir) installs to `$(gem env gemdir)`. The --global flag drives the Ruby crawler to scan the system gem dir. Same marker check at the discovered path. gem patches use the `package/<rel>` convention; apply strips the `package/` prefix and joins with the gem's directory. Dockerfile.gem is unchanged from prior infrastructure work.
`cargo fetch` against a minimal project with `cfg-if = "=1.0.0"` populates `\$CARGO_HOME/registry/src/<index>/cfg-if-1.0.0/`. scan --sync writes the manifest + blob, apply --force --offline overwrites the registry-source `src/lib.rs` with patched bytes containing SOCKET-PATCH-E2E-MARKER. grep verifies on disk. Pre-chmods the registry source file to writable — cargo's source files are read-only by default and apply's own fix-permissions code covers the same path, but the chmod up-front keeps the test robust against changes there. Single test (no global variant): cargo's registry is the only cache, so local-vs-global is a no-op. Dockerfile.cargo unchanged from prior infrastructure work; it has rustup-installed Rust 1.93.1 with CARGO_HOME set.
`go mod download github.com/gin-gonic/gin@v1.9.1` populates `\$GOMODCACHE/github.com/gin-gonic/gin@v1.9.1/`. scan --sync writes the manifest + blob, apply --force --offline overwrites gin.go with synthetic patched bytes containing SOCKET-PATCH-E2E-MARKER. grep verifies on disk. Pre-chmods the cache file to writable — `go mod download` extracts to read-only files, similar to cargo registry. Single test (no global variant): golang's module cache is the only cache; --global is a no-op. Dockerfile.golang ships Go 1.21.13 from the official tarball; GOPATH and GOMODCACHE are set at image build time.
Upgrades docker_e2e_maven.rs from scan-only to the full chain. `mvn dependency:get -Dartifact=org.apache.commons:commons-lang3:3.12.0` downloads the artifact into ~/.m2/repository, the wiremock fixture overwrites the .pom file with synthetic patched bytes, and the test grep-verifies SOCKET-PATCH-E2E-MARKER on disk. Single test (local-only) since ~/.m2 is always global.
Upgrades docker_e2e_composer.rs to the full chain plus a global variant. Real `composer require monolog/monolog:3.5.0` installs into vendor/monolog/monolog/, the wiremock fixture overwrites src/Monolog/Logger.php with synthetic patched bytes, and the test grep-verifies SOCKET-PATCH-E2E-MARKER on disk. Adds composer_global_install_full_apply_chain: `composer global require` installs to $COMPOSER_HOME/vendor, socket-patch scans + applies with --global, marker verified there.
Upgrades docker_e2e_nuget.rs to the full chain plus a global variant.
The local test redirects `dotnet add package` to a project-local
./packages dir via NUGET_PACKAGES, then scan + apply patch the
package's LICENSE.md with a synthetic blob; the global test uses the
default ~/.nuget/packages and --global mode.
Note: the wiremock fixture uses the lowercased package name in the
PURL ("newtonsoft.json") so scan's GC pass (--sync = --apply --prune)
doesn't prune the freshly-saved manifest entry — the crawler reports
installed packages by their lowercased directory name and GC keys
against that.
Adds npm_global_install_full_apply_chain alongside the existing local install/apply/rollback test. The variant runs `npm install -g`, locates the file at $(npm root -g)/minimist/index.js, then runs scan + apply with --global and grep-verifies SOCKET-PATCH-E2E-MARKER. Host-mode skips the global variant (no safe host npm prefix to mutate); Docker is the canonical run path.
Adds the three Dockerfile recipes the docker_e2e_{composer,maven,nuget}
tests panic-message instruct users to build.
- Dockerfile.composer: base + PHP 8 + Composer 2
- Dockerfile.maven: base + default-jdk-headless + maven
- Dockerfile.nuget: mcr.microsoft.com/dotnet/sdk:8.0 (sdk image)
with socket-patch COPY'd in from the base
The host `coverage` job ran with `--all-features`, which enabled the docker-e2e feature, but the job never built the per-ecosystem Docker images — every docker_e2e_<eco> test would panic on `assert_image` and the job failed (or, if it ever passed, only the surviving in-process tests contributed). The Docker tests exercise the real socket-patch binary inside a Linux container, and that subprocess's coverage wasn't captured at all. Changes: * Each `docker_e2e_<eco>.rs` now reads SOCKET_PATCH_COV_BIN + SOCKET_PATCH_COV_PROFRAW_DIR. When both are set, the docker run mounts an llvm-cov-instrumented socket-patch binary over the image's baked-in /usr/local/bin/socket-patch and points LLVM_PROFILE_FILE into a host-visible volume. Empty Vec when unset → tests behave exactly as before for local dev and the existing e2e-docker matrix. * `coverage` job: drops `--all-features` for an explicit feature list (cargo,golang,maven,composer,nuget) that excludes docker-e2e. Produces `coverage-host.lcov`. * New `coverage-docker` matrix job: per ecosystem, builds the base + ecosystem Docker images, eval-sources `cargo llvm-cov show-env` to build an instrumented `target/debug/socket-patch`, sets the SOCKET_PATCH_COV_* hooks, runs `cargo llvm-cov --no-report --test docker_e2e_<eco>`, and emits a per-ecosystem lcov artifact. * New `coverage-merge` job: gathers `coverage-host` + all 8 `coverage-docker-*` artifacts and unions them via `lcov --add-tracefile` into a single `coverage-lcov` artifact. Same artifact name as before so downstream consumers keep working. Result: lines hit by ANY test (host in-process, host harness, or in-container binary execution) show up in the final coverage map.
zizmor's cache-poisoning audit (high) flagged the cargo `actions/cache` steps in `e2e-docker` and `coverage-docker` because both jobs also invoke `docker/build-push-action`. The risk model: a PR could poison the cargo cache (target/, ~/.cargo) with a backdoored crate or compiled object, and a later run on a trusted ref could load the poisoned cache and produce a compromised binary that gets mounted into the docker container or baked into the published image. Drop the cargo cache from both jobs. The Docker buildx `cache-from: type=gha` remains, so image-layer rebuilds are still fast. Cargo deps refresh from the registry per run — about a one-minute cost that's worth it to eliminate the attack surface. The other jobs (clippy, test, test-release, coverage, e2e) keep their cargo caches — none of them build Docker images, so the audit doesn't trigger for them.
The action requires a `toolchain` input — when SHA-pinned (which is
our policy), the action can't infer the channel from action_ref the
way `@stable`/`@1.93.1` ref pins would, so it errors out with
"'toolchain' is a required input".
The original comments ("toolchain version is read from
rust-toolchain.toml") referred to rustup's behavior after install,
not the action's pre-install resolution — the action doesn't read
rust-toolchain.toml itself.
Set `toolchain: "1.93.1"` on every Install Rust step, matching the
channel in rust-toolchain.toml. The duplication is intentional: if
they drift, rustup will reconcile by installing the toolchain.toml
channel on first cargo invocation, just at a small extra cost.
Removes the third-party Rust toolchain action and replaces every "Install Rust" step with `rustup show`. rustup is pre-installed on GitHub-hosted runners; `rustup show` consumes rust-toolchain.toml, auto-installs the pinned channel if missing, and applies the listed components (rustfmt, clippy). For coverage jobs that additionally need llvm-tools-preview, `rustup component add llvm-tools-preview` follows the show step. Benefits: - One less third-party action to audit and SHA-pin. - No duplication between rust-toolchain.toml and ci.yml. - Toolchain bumps are one-file changes (just edit toolchain.toml).
Define a single `GlobalArgs` clap struct and `#[command(flatten)]` it into every subcommand's args. Every flag now has a matching `SOCKET_*` env var binding (precedence: CLI > env > default). Legacy `SOCKET_PATCH_PROXY_URL`, `SOCKET_PATCH_DEBUG`, `SOCKET_PATCH_TELEMETRY_DISABLED` are still honored at runtime via a one-shot deprecation warning that fires even under `--silent` / `--json`. Behavior changes: - `--offline` now means strict airgap on every command (was three different things across apply / repair / rollback). On `repair`, `--offline` and `--download-only` are mutually exclusive. - `repair --download-mode` default flipped from `file` to `diff` to match every other command. Users who need the legacy per-file blob behavior opt in with `--download-mode file`. - `apply` and `repair` gain `--api-url` / `--api-token` / `--org` for free via the flatten (previously only readable via env). - `--debug` and `--no-telemetry` promoted from env-only toggles to CLI flags. CLI_CONTRACT.md rewritten around a single global-args table plus a small per-subcommand section for local flags. New tests: `cli_global_args.rs` (compose test: every global flag × every subcommand) and `cli_env_deprecation.rs` (legacy-env warning fires under `--silent` / `--json`). Assisted-by: Claude Code:opus-4-7
… entry Adds a Keep-a-Changelog-style CHANGELOG.md at the repo root, backfilled with concise summaries for every published tag (v1.1.0 → v2.1.4) and a detailed v3.0.0 entry covering the breaking changes in the in-flight v3 release (unified `--offline`, `repair --download-mode` default flip, `SOCKET_PATCH_*` → `SOCKET_*` env-var renames with one-shot deprecation warning, shared `GlobalArgs` flatten across every subcommand, etc.). Wires a new step into the `Release` workflow's `version` job that fails the workflow when `CHANGELOG.md` lacks an entry for the version in Cargo.toml. Because every downstream job (tag, build, github-release, cargo/npm/pypi-publish) transitively depends on `version`, a missing changelog entry blocks the entire publish pipeline. Accepts both `## [X.Y.Z]` and `## X.Y.Z` heading styles to keep the format requirement loose for future contributors. Assisted-by: Claude Code:opus-4-7
…json This commit fixes the pre-existing CI red on the v3.0 branch. Four unrelated root causes: 1. `cargo test --workspace --all-features` enables the `docker-e2e` feature, which compiles the 8 `docker_e2e_<eco>.rs` tests on every `test (ubuntu/macos/windows)` runner. Those tests `assert_image()` on a docker image that only exists in the dedicated docker-building jobs, so every test runner failed. Replaced each `assert_image()` panic with a `skip_if_no_image()` early return that prints a stderr skip notice. Tests now report `ok` on hosts without docker / images. `cargo test --workspace --all-features` is green everywhere. 2. The `coverage` job (cargo-llvm-cov, --all-features) failed three `in_process_remove_repair_lifecycle` tests that set `SOCKET_API_URL`/`SOCKET_API_TOKEN`/`SOCKET_ORG_SLUG` via `std::env::set_var` after constructing `RepairArgs` via `..GlobalArgs::default()`. The refactor's `api_client_overrides()` was always forwarding the resolved api_url/proxy_url as `Some(...)`, which short-circuited the env-var fallback inside `get_api_client_with_overrides`. Made `GlobalArgs::default()` leave `api_url`/`proxy_url` empty (clap always populates them in production via `default_value`, so the production path is unchanged) and `api_client_overrides()` filters empty values to `None`. The env-var fallback now fires for these tests. 3. `repair_download_only_skips_cleanup` (in `repair_invariants.rs`) used the shared `run_repair()` helper which injects `--offline`. v3.0 made `--offline` and `--download-only` mutually exclusive (exit code 2). Inlined the binary invocation without `--offline` for this one test — the manifest's referenced blob is already on disk so the download phase is a no-op even without `--offline`. 4. The `e2e-docker` and `coverage-docker` matrix jobs failed at "Build <eco> image" with `pull access denied` on `socket-patch-test-base:latest`. setup-buildx-action defaults to the `docker-container` driver, which runs BuildKit in a sandboxed container that cannot see the host docker daemon's image store — so the per-ecosystem Dockerfile's `FROM socket-patch-test-base:latest` tries to pull from docker.io and fails. Switched both jobs to `driver: docker` so buildx talks to the host daemon directly. Dropped the `type=gha` cache directives (not supported under the docker driver) — we trade build cache for image visibility. Local: `cargo test --workspace --all-features` → 965 passed, 0 failed. Assisted-by: Claude Code:opus-4-7
The coverage-docker matrix builds an instrumented socket-patch binary
on the host and mounts it into the debian:12-slim test container.
ubuntu-latest is currently 24.04 (glibc 2.39); debian:12 ships glibc
2.36. Result: every coverage-docker matrix job failed with
socket-patch: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.39'
not found (required by socket-patch)
Pin to ubuntu-22.04 (glibc 2.35) — the highest base that's
forward-compatible with debian:12. e2e-docker is unaffected because it
runs the binary that was baked into the image by the base Dockerfile's
internal builder stage, not a host-mounted one.
Assisted-by: Claude Code:opus-4-7
wiremock binds to 0.0.0.0 (the wildcard). Linux and macOS quietly route a connect to 0.0.0.0 onto the loopback interface, so the test worked on those runners. Windows refuses the connect with WSAEADDRNOTAVAIL (winsock error 10049) because 0.0.0.0 is a valid bind target but not a valid destination address. Use 127.0.0.1 explicitly for the smoke-check URL — the bound port from `server.address().port()` is still what we need. Assisted-by: Claude Code:opus-4-7
`install_six()` hardcodes `venv/bin/pip` and `find_site_packages()` walks `venv/lib/pythonX.Y/site-packages/`. Both layouts are Unix-only — on Windows the venv puts pip at `Scripts\pip.exe` and site-packages at `Lib\site-packages\` (no per-version subdirectory). Rather than forking the helpers per platform, gate every test in this file behind `skip_unsupported_platform()` which prints a skip notice on Windows and returns early. The same code paths get exercised by the Linux test runner and the docker_e2e_pypi suite, so coverage isn't lost. Assisted-by: Claude Code:opus-4-7
Reverts the earlier Windows-skip in favor of real Windows coverage.
Three changes to the helpers:
1. find_python() probes `python3` → `python` → `py` (mirrors the
crawler's `find_python_command` in
core/src/crawlers/python_crawler.rs:15). On Windows the canonical
name is `python` (the `py` launcher is also installed); `python3`
is rare. Without this the venv-creation step calls `python3` and
fails on every Windows runner.
2. venv_pip() returns `Scripts\pip.exe` on Windows vs `bin/pip` on
Unix, matching PEP-405's documented venv layout.
3. find_site_packages() branches on cfg!(windows):
* Windows: `<venv>\Lib\site-packages\` — no version subdirectory.
* Unix: glob `<venv>/lib/python3.X/site-packages/` for whatever
interpreter version pip used.
The four in-process tests now exercise the same install→scan→apply
chain on Windows that they already cover on Linux/macOS. The core
crawler is already Windows-aware (python_crawler.rs:182) so the
package-discovery path it tests is real, not synthetic.
Assisted-by: Claude Code:opus-4-7
rollback_pypi_restores_original_content set up a synthetic `.venv/lib/python3.11/site-packages/` tree by hand. That's the Unix layout — on Windows the pypi crawler at core/src/crawlers/python_crawler.rs:182 looks for `.venv\Lib\site-packages\`, so on Windows runners the crawler found nothing and the patched file was never rolled back. Branch on `cfg!(windows)` when building the path so the synthetic package sits where the crawler actually probes on each platform. The crawler logic itself is unchanged. Assisted-by: Claude Code:opus-4-7
…rity, vuln IDs
When `get` or `scan --apply` adds or updates a patch in the manifest,
the per-patch JSON record now carries the metadata consumers need to
render the patch to a human without a second API round-trip:
```jsonc
{
"purl": "pkg:npm/minimist@1.2.2",
"uuid": "11111111-...",
"action": "added",
"description": "Fixes prototype pollution in minimist",
"license": "MIT",
"tier": "free",
"exportedAt": "2024-01-01T00:00:00Z",
"severity": "high",
"vulnerabilities": [
{
"id": "GHSA-xvch-5gv4-984h",
"cves": ["CVE-2024-12345"],
"severity": "high",
"summary": "Prototype Pollution",
"description": "merge() does not check Object.prototype"
}
]
}
```
Highlights:
- Top-level `severity` is the max across the vulnerabilities array,
using the ordering critical > high > medium=moderate > low.
- `vulnerabilities[]` is sorted by `id` so consumer diffs and test
snapshots don't flap on HashMap iteration order.
- Metadata is intentionally omitted on `action: skipped` (consumer
already has it from the original add) and on `action: failed`.
- `scan --apply` benefits automatically — both flows go through
`download_and_apply_patches`.
Helpers `severity_rank`, `max_vuln_severity`, `patch_event_metadata`
are pub(crate) and unit-tested. CLI_CONTRACT.md gains a new
"`patches[]` entry shape" subsection documenting the schema.
Assisted-by: Claude Code:opus-4-7
The e2e (real-registry) suite was asserting on `list["patches"]` —
the pre-v3 ad-hoc shape. v3.0 migrated `list --json` to the unified
envelope, which emits `{command, status, events, summary}` with one
`discovered` event per manifest entry. Patch metadata
(vulnerabilities, tier, license) lives under `details`.
Updated four sites (e2e_npm × 2, e2e_pypi × 1, e2e_gem × 1) to
filter events by `action == "discovered"` and walk
`details.vulnerabilities[]` for CVE assertions.
Closes the `e2e (ubuntu/macos, e2e_npm|e2e_pypi|e2e_gem)` matrix
failures surfaced once the e2e workflow started passing on the v3.0
branch.
Assisted-by: Claude Code:opus-4-7
`ruby/setup-ruby` dropped 3.2.11 from its catalog at some point — the action errors with "Unknown version 3.2.11 for ruby on ubuntu-24.04" and lists 3.2.10 as the newest 3.2.x available. 3.2.x is API-stable so 3.2.10 is a drop-in replacement. Assisted-by: Claude Code:opus-4-7
Two unrelated changes in one commit: 1. Drop the `-d` short for `--dry-run` and `-m` short for `--manifest-path` from `GlobalArgs`. We want those letters free for future flags. The long forms are unaffected, and a new `reserved_short_forms_are_not_assigned` compose test locks in that no subcommand reassigns either letter. Per-subcommand short-form tests (`*_short`, `manifest_path_short_form`, etc.) are deleted; the long-form counterparts cover the contract. 2. Loosen `python-version` and `ruby-version` pins in ci.yml from exact patch (`3.12.13`, `3.2.10`) to minor.x (`3.12.x`, `3.2.x`). setup-python and setup-ruby's catalogs keep retiring older patch versions and breaking the workflow — minor.x auto-resolves to whatever patch is currently available. CLI_CONTRACT.md updated to remove `-d`/`-m` from the global args table and the env-var cross-reference. Assisted-by: Claude Code:opus-4-7
`apply_file_patch` now treats target-file permissions as a strict
round-trip:
1. **Existing file**: snapshot mode + uid + gid before writing.
- If read-only, temporarily grant owner-write so the overwrite
succeeds (Go module cache, npm linked symlinks, etc.).
- After writing, restore the *exact* pre-patch mode (idempotent
`set_permissions(from_mode(...))`) and chown back to the
pre-patch uid/gid. `tokio::fs::write` truncates + rewrites the
file in place, so owner usually survives, but pinning
ownership explicitly stops a theoretical race where another
process opens the file between truncate and write.
2. **New file** (created by the patch): chown to inherit owner/group
from the parent directory, mode = `0o444` (read-only for all).
Matches how a freshly-unpacked package tarball treats its files.
Windows: no uid/gid concept; preserve the readonly attribute for
existing files and force it on new ones.
`restore_file_permissions` and the `chown_blocking` helper are split
out of `apply_file_patch` for readability and unit testing. Four
new tests pin the policy: readonly-mode preservation, executable
(0o755) mode preservation, new-file default mode + parent ownership
inheritance, and uid/gid round-trip on existing files.
Assisted-by: Claude Code:opus-4-7
setup-ruby (unlike setup-python) does NOT support the `3.2.x` wildcard pin — it errors with "Unknown version 3.2.x for ruby on ubuntu-24.04". Revert to an exact patch that's in the catalog. When this patch eventually drops off, bump it manually per the list at https://github.com/ruby/setup-ruby. Assisted-by: Claude Code:opus-4-7
7 tasks
Wenxin Jiang (Wenxin-Jiang)
approved these changes
May 22, 2026
Mikola Lysenko (mikolalysenko)
added a commit
that referenced
this pull request
May 22, 2026
Adds five new modules to `socket-patch-core` and refactors `apply_file_patch` to compose them safely with #79's perm-preservation: - **`patch::apply_lock`** — cross-platform advisory file lock at `<.socket>/apply.lock` via `fs2`. Used by every mutating subcommand to serialize against concurrent socket-patch runs. - **`patch::cow`** — hardlink + symlink copy-on-write. Before patching, if `filepath` is a symlink into a content-addressed store (pnpm) or a regular file with `nlink > 1` (bazel mirrors, nix store overlays), give this project a private inode. The pnpm content store and every other project pointing at it stay byte-identical. - **`patch::sidecars`** — ecosystem-aware sidecar fixups dispatched from `apply_package_patch`. Cargo: rewrite `.cargo-checksum.json` with new SHA256s so `cargo build` accepts patched sources. NuGet: delete `.nupkg.metadata` (the documented "unknown" state vs. a stale `contentHash` that would flag tampering). PyPI / gem / Go: advisory-only — surface a one-line note about downstream tooling consequences. - **`crawlers::pkg_managers`** — path-based detector for the four Node.js layout flavors (npm / pnpm / yarn-classic / yarn-berry PnP). Apply uses this to refuse yarn-berry PnP (packages live in `.yarn/cache/*.zip`) and to surface a pnpm-detected note. - **`apply_file_patch` atomic rewrite** — two-phase commit: 1. Hash `patched_content` in memory; error out before any disk write if it doesn't match `expected_hash`. Removes the prior "wrote bytes, post-write verify failed, can't restore" window. 2. CoW the target if it's a shared inode. 3. Stage write to `<parent>/.socket-stage-<uuid>`, `sync_all()`, then `rename(stage, target)`. POSIX `rename(2)` is atomic — observers see either the old or new bytes, never a truncated half-write. Composes cleanly with #79's mode + uid/gid restore step which now operates on the post-rename inode. `ApplyResult` grows `sidecars_updated: Vec<String>` and `sidecar_advisory: Option<String>` so the CLI envelope can surface fixup outcomes. `fs2` and `tempfile` added to socket-patch-core dependencies. Two new tests pin the headline invariants: - `test_apply_file_patch_hash_mismatch_leaves_original_intact` — atomic-write contract: hash mismatch leaves target byte-identical AND no `.socket-stage-*` litter in parent dir. - `test_apply_file_patch_does_not_propagate_to_hardlinked_sibling` — the pnpm content-store invariant at the integration level. Plus 10 unit tests for cow + apply_lock and 13 for sidecars/* + 9 for pkg_managers. Assisted-by: Claude Code:claude-opus-4-7
Mikola Lysenko (mikolalysenko)
added a commit
that referenced
this pull request
May 22, 2026
Integrates the new socket-patch-core safety primitives into the CLI via the v3.0 unified `GlobalArgs` + `Envelope` patterns from #79. **`commands::lock_cli`** (new) — envelope-aware wrapper around `apply_lock::acquire`. Takes `Command` so the failure envelope's `command` field reflects which subcommand was blocked. On contention the binary emits `{status: "error", error: {code: "lock_held", ...}}` in JSON mode or a one-line stderr message otherwise, then exits 1. **Lock acquisition** added to `apply`, `rollback`, `repair`, `remove` immediately after the manifest existence check. `remove`'s outer lock spans the inner `rollback_patches` call (which deliberately does NOT acquire the lock so the composition doesn't self-deadlock). **Apply pkg-manager gating** — after the lock, `apply` runs `detect_npm_pkg_manager`: - `YarnBerryPnP` → emit `EnvelopeError("yarn_pnp_unsupported", ...)` pointing at `yarn patch` and exit 1. - `Pnpm` → surface a one-line stderr note. CoW handles the substantive safety work; this just tells the user the layout was understood. **Sidecar JSON via `event.details`** — `result_to_event` extends the Applied event with `details.sidecarsUpdated: string[]` and `details.sidecarAdvisory: string | null` when either is non-empty. Narrower JSON-envelope contract than first-class fields; consumers read `event.details.sidecarsUpdated` from JSON. **Maven + NuGet experimental runtime gates** in `ecosystem_dispatch.rs`. Even when compiled with `--features maven`/`nuget`, the crawlers refuse to dispatch unless the matching `SOCKET_EXPERIMENTAL_MAVEN=1`/`SOCKET_EXPERIMENTAL_NUGET=1` env var is set. Without it, surface a warning event and skip those PURLs. Reasoning: Maven patches corrupt jar sidecar checksums (sha1/md5); NuGet patches corrupt `.nupkg.sha512` signature sidecars that `dotnet restore` reads as tamper-evidence. `fs2` added to socket-patch-cli dev-dependencies for the lock e2e test (same crate the binary uses internally). Assisted-by: Claude Code:claude-opus-4-7
Mikola Lysenko (mikolalysenko)
added a commit
that referenced
this pull request
May 23, 2026
…s, Maven gate (#80) * feat(apply): safety primitives — lock, CoW, atomic write, sidecar fixups Adds five new modules to `socket-patch-core` and refactors `apply_file_patch` to compose them safely with #79's perm-preservation: - **`patch::apply_lock`** — cross-platform advisory file lock at `<.socket>/apply.lock` via `fs2`. Used by every mutating subcommand to serialize against concurrent socket-patch runs. - **`patch::cow`** — hardlink + symlink copy-on-write. Before patching, if `filepath` is a symlink into a content-addressed store (pnpm) or a regular file with `nlink > 1` (bazel mirrors, nix store overlays), give this project a private inode. The pnpm content store and every other project pointing at it stay byte-identical. - **`patch::sidecars`** — ecosystem-aware sidecar fixups dispatched from `apply_package_patch`. Cargo: rewrite `.cargo-checksum.json` with new SHA256s so `cargo build` accepts patched sources. NuGet: delete `.nupkg.metadata` (the documented "unknown" state vs. a stale `contentHash` that would flag tampering). PyPI / gem / Go: advisory-only — surface a one-line note about downstream tooling consequences. - **`crawlers::pkg_managers`** — path-based detector for the four Node.js layout flavors (npm / pnpm / yarn-classic / yarn-berry PnP). Apply uses this to refuse yarn-berry PnP (packages live in `.yarn/cache/*.zip`) and to surface a pnpm-detected note. - **`apply_file_patch` atomic rewrite** — two-phase commit: 1. Hash `patched_content` in memory; error out before any disk write if it doesn't match `expected_hash`. Removes the prior "wrote bytes, post-write verify failed, can't restore" window. 2. CoW the target if it's a shared inode. 3. Stage write to `<parent>/.socket-stage-<uuid>`, `sync_all()`, then `rename(stage, target)`. POSIX `rename(2)` is atomic — observers see either the old or new bytes, never a truncated half-write. Composes cleanly with #79's mode + uid/gid restore step which now operates on the post-rename inode. `ApplyResult` grows `sidecars_updated: Vec<String>` and `sidecar_advisory: Option<String>` so the CLI envelope can surface fixup outcomes. `fs2` and `tempfile` added to socket-patch-core dependencies. Two new tests pin the headline invariants: - `test_apply_file_patch_hash_mismatch_leaves_original_intact` — atomic-write contract: hash mismatch leaves target byte-identical AND no `.socket-stage-*` litter in parent dir. - `test_apply_file_patch_does_not_propagate_to_hardlinked_sibling` — the pnpm content-store invariant at the integration level. Plus 10 unit tests for cow + apply_lock and 13 for sidecars/* + 9 for pkg_managers. Assisted-by: Claude Code:claude-opus-4-7 * feat(cli): wire safety primitives + Maven/NuGet experimental gates Integrates the new socket-patch-core safety primitives into the CLI via the v3.0 unified `GlobalArgs` + `Envelope` patterns from #79. **`commands::lock_cli`** (new) — envelope-aware wrapper around `apply_lock::acquire`. Takes `Command` so the failure envelope's `command` field reflects which subcommand was blocked. On contention the binary emits `{status: "error", error: {code: "lock_held", ...}}` in JSON mode or a one-line stderr message otherwise, then exits 1. **Lock acquisition** added to `apply`, `rollback`, `repair`, `remove` immediately after the manifest existence check. `remove`'s outer lock spans the inner `rollback_patches` call (which deliberately does NOT acquire the lock so the composition doesn't self-deadlock). **Apply pkg-manager gating** — after the lock, `apply` runs `detect_npm_pkg_manager`: - `YarnBerryPnP` → emit `EnvelopeError("yarn_pnp_unsupported", ...)` pointing at `yarn patch` and exit 1. - `Pnpm` → surface a one-line stderr note. CoW handles the substantive safety work; this just tells the user the layout was understood. **Sidecar JSON via `event.details`** — `result_to_event` extends the Applied event with `details.sidecarsUpdated: string[]` and `details.sidecarAdvisory: string | null` when either is non-empty. Narrower JSON-envelope contract than first-class fields; consumers read `event.details.sidecarsUpdated` from JSON. **Maven + NuGet experimental runtime gates** in `ecosystem_dispatch.rs`. Even when compiled with `--features maven`/`nuget`, the crawlers refuse to dispatch unless the matching `SOCKET_EXPERIMENTAL_MAVEN=1`/`SOCKET_EXPERIMENTAL_NUGET=1` env var is set. Without it, surface a warning event and skip those PURLs. Reasoning: Maven patches corrupt jar sidecar checksums (sha1/md5); NuGet patches corrupt `.nupkg.sha512` signature sidecars that `dotnet restore` reads as tamper-evidence. `fs2` added to socket-patch-cli dev-dependencies for the lock e2e test (same crate the binary uses internally). Assisted-by: Claude Code:claude-opus-4-7 * test(e2e): safety hardening suite + CI matrix + invariant fixups Adds four end-to-end integration test files exercising the safety primitives through the binary, plus shared `tests/common/mod.rs` helpers, plus two existing-test contract updates. **Suites added (20 new tests):** - `e2e_safety_lock.rs` (6 tests, non-ignored). Test holds the same `.socket/apply.lock` the binary uses via `fs2` directly, then spawns `socket-patch apply` and asserts the second process exits with `error.code == "lock_held"`. Zero production-code hooks. - `e2e_safety_yarn_pnp.rs` (5 tests, non-ignored). Yarn-berry PnP markers (`.pnp.cjs`, `.pnp.loader.mjs`) trigger `error.code == "yarn_pnp_unsupported"`. Negative control: plain npm layout does NOT trigger the refusal. - `e2e_safety_cargo_build.rs` (5 tests, `#[ignore]` + `--features cargo`). Three synthetic-vendor tests: 1. Baseline `cargo check --offline --frozen` succeeds. 2. Negative control — mutating the source WITHOUT the sidecar fixup makes cargo refuse with "checksum changed". Proves cargo actually verifies, which is what makes the positive test meaningful. 3. Sidecar fixup makes `cargo check` pass; `.cargo-checksum.json` is rewritten and the `package` field is preserved. 4. JSON envelope contract: `.cargo-checksum.json` appears in `event.details.sidecarsUpdated`. Plus `traitobject_real_socket_patch_round_trip` — the cargo layer-2+3 combined test: `cargo fetch traitobject@0.0.1` from crates.io → `socket-patch get b15f2b7f-d5cb-43c9-b793-80f71682188f` from patches-api.socket.dev → assert `.cargo-checksum.json` rewritten + `cargo check` succeeds against the real, production Socket patch. - `e2e_safety_pnpm.rs` (4 tests, `#[ignore]`). Two projects share a pnpm content store via `--config.package-import-method=hardlink`. `socket-patch get` in project A patches A; project B + store entry stay byte-identical. `pnpm install --frozen-lockfile` in B afterwards does not revert A. Exercises CoW against a real pnpm install rather than a hand-rolled hardlink. **`tests/common/mod.rs`** — shared helpers (`binary`, `run`, `assert_run_ok`, `git_sha256`, `sha256_hex`, `pnpm_run`, `cargo_run`, `write_minimal_manifest`, `write_blob`, `parse_json_envelope`, `envelope_error_code`, `envelope_error_message`) lifted from the duplicated copies in `e2e_npm.rs` etc. Additive; existing suites keep their inlined copies for now. **CI matrix** in `.github/workflows/ci.yml`: - `e2e_safety_cargo_build` on ubuntu + macos + windows - `e2e_safety_pnpm` on ubuntu + macos + windows (pnpm-on-Windows uses junctions + copies by default, so the CoW invariant holds vacuously; the test still runs to verify apply doesn't error on Windows. Semantic Windows nlink coverage is a follow-up — `std::fs::Metadata` doesn't expose nlink on Windows without `GetFileInformationByHandle` via `windows-sys`.) - New `Setup pnpm` step (`npm install -g pnpm@10`) gated on the pnpm suite. The fast non-ignored suites (`e2e_safety_lock`, `e2e_safety_yarn_pnp`) run via the standard `test` job on all three platforms. **Existing-test contract updates** (these tests were pinning the old, broken behavior; both still describe correct invariants — their assertions just needed to track the rebased semantics): - `tests/apply_invariants.rs`: `dir_hash` excludes `apply.lock`. The lock file is deliberate ephemeral session state, not patch content; the "apply is read-only against .socket/" invariant is about manifest + blobs + diffs + packages. - `tests/in_process_edge_cases.rs`: `apply_blob_after_hash_mismatch_reports_failure` now asserts the atomic-write contract — the target file is byte-identical to its pre-call state on the hash-mismatch failure path, no half-written corruption. Assisted-by: Claude Code:claude-opus-4-7 * refactor(sidecars): typed envelope contract with structured per-file + advisory data Replaces the previous `event.details.sidecarsUpdated` / `event.details.sidecarAdvisory` free-form JSON bag with a typed, top-level `Envelope.sidecars[]` list. ## New types (`socket-patch-core/src/patch/sidecars/types.rs`) pub struct SidecarRecord { purl, ecosystem, files, advisory } pub struct SidecarFile { path, action: SidecarFileAction } pub enum SidecarFileAction { Rewritten | Deleted | Created } pub struct SidecarAdvisory { code, severity, message } pub enum SidecarAdvisoryCode { PypiRecordStale | GemBundleInstallReverts | GoModVerifyFails | NugetSignedPackageTampered | SidecarFixupFailed } pub enum SidecarSeverity { Info | Warning | Error } All derive `serde::Serialize`. Structs use camelCase; enums use snake_case. Unit tests pin the JSON contract. ## JSON shape (consumer view) ```json { "command": "apply", "events": [...], "sidecars": [ { "purl": "pkg:cargo/...", "ecosystem": "cargo", "files": [{"path":".cargo-checksum.json","action":"rewritten"}] }, { "purl": "pkg:nuget/...", "ecosystem": "nuget", "files": [{"path":".nupkg.metadata","action":"deleted"}], "advisory": { "code":"nuget_signed_package_tampered", "severity":"warning", "message":"..." } } ] } ``` - `sidecars` omitted from JSON when empty. - `files` always present (possibly `[]` for advisory-only). - `advisory` omitted when absent. - `code` / `severity` are stable snake_case enum tags; `message` is human text. - `purl` joins to `events[].purl` for per-event context. ## Three real improvements over the old design 1. **No more lossy collapse.** NuGet's "deleted `.nupkg.metadata` AND has a `.nupkg.sha512` signature" case now carries BOTH a file entry AND an advisory. Before, the advisory was silently lost when the file entry took its slot. 2. **Stable codes + severity.** Consumers (CI bots, dashboards, telemetry, jq pipelines) can switch on `code` and route on `severity` without regex-matching free-form strings. 3. **Decoupled from events.** Sidecar reporting is a top-level `Envelope.sidecars` list. `PatchEvent.details` is no longer mixed with `list` / `repair` / `remove`'s command-specific bags — sidecar consumers have a typed schema all their own. ## Internal refactor - `SidecarOutcome` removed. Per-ecosystem fixups return `Result<Option<SidecarPayload>, SidecarError>` (internal `SidecarPayload = { files, advisory }`); the dispatcher in `sidecars/mod.rs` wraps the payload with PURL + ecosystem to produce the `SidecarRecord`. - `ApplyResult.sidecars_updated: Vec<String>` and `sidecar_advisory: Option<String>` consolidated into a single `sidecar: Option<SidecarRecord>` field. - Apply CLI's `result_to_event` no longer attaches to `event.details`; the run loop now calls `env.record_sidecar(record.clone())` after each apply result. - `Envelope` gains `sidecars: Vec<SidecarRecord>` field + `record_sidecar` method. - The error path (`SidecarError` returned by a fixup) is converted at the apply boundary into a `SidecarRecord` with `advisory.code = SidecarFixupFailed`, `severity = Error`. Single uniform shape for consumers. ## Pre-existing test fixups `in_process_remote_ecosystems_apply.rs` and `in_process_rollback_all_ecosystems.rs` now set `SOCKET_EXPERIMENTAL_MAVEN=1` / `SOCKET_EXPERIMENTAL_NUGET=1` when they explicitly exercise those paths. These were broken silently by the Maven/NuGet runtime gates added in the prior rebase (the gate was always there in commit 39a2321; tests just happened not to exercise the maven/nuget paths to a depth where the skip mattered). ## Test results - cargo build --workspace --all-features: clean - cargo build --release --workspace: clean (no warnings) - cargo clippy --workspace --all-features -- -D warnings: clean - cargo test --workspace --all-features: 1021 passed, 0 failed - cargo test --features cargo --test e2e_safety_cargo_build -- --ignored: 5 passed (includes traitobject real-patch round trip) The e2e cargo test `apply_reports_cargo_checksum_in_sidecars_updated` tightened from a substring match to a structured-shape assertion on `envelope.sidecars[].ecosystem=="cargo"` + `files[].path=".cargo-checksum.json"` + `files[].action=="rewritten"`. Assisted-by: Claude Code:claude-opus-4-7 * test(e2e): expand sidecar coverage + simplify PTY harness Five test surfaces, one bug fix, one YAGNI cleanup, one harness simplification — all motivated by closing the e2e gap on the new typed `Envelope.sidecars[]` contract. - **e2e_safety_advisories.rs** (new, 5 tests): drive the apply CLI against handcrafted layouts and assert `envelope.sidecars[].{ecosystem,advisory.code,advisory.severity, files[]}` for pypi (`pypi_record_stale`), gem (`gem_bundle_install_reverts`), golang (`go_mod_verify_fails`), nuget unsigned (deleted files only), and nuget signed (deleted files + `nuget_signed_package_tampered` advisory together — the case the pre-typed-contract design lost). - **e2e_safety_cow.rs** (new, 5 tests): cover `patch/cow.rs` end to end — hardlink isolation, symlink replacement, multi-file hardlink, regular-file no-op, and the failure-doesn't-cow path. Lifted file coverage from ~23% to ~80% (remaining gaps are defensive I/O error arms not reproducible in tests). - **e2e_safety_cargo_build.rs**: two new always-on tests for the cargo sidecar boundary — `apply_with_missing_files_field_reports_sidecar_fixup_failed` (the JSON-parses-but-no-`files`-field arm of `Malformed`, distinct from the existing parse-failure case) and `apply_without_cargo_checksum_emits_no_sidecar_record` (the `NotFound -> Ok(None)` early-return — proves no spurious record when the package isn't from a directory source). - **interactive_prompts_e2e.rs**: simplify the PTY harness. Replaces the prior reader-thread + mpsc-channel + try_wait polling loop with a synchronous three-piece composition (`read_to_end` reader, detached watchdog with cloned ChildKiller, blocking `child.wait()` on the main thread). No pre-write sleep — the PTY buffers input. All six prompt tests still pass with materially less harness code. - **common/mod.rs**: add `run_with_env(cwd, args, env)` so integration tests can flip per-ecosystem runtime gates (`SOCKET_EXPERIMENTAL_NUGET=1`) and discovery roots (`NUGET_PACKAGES`, `GOMODCACHE`) on the child only, keeping parent env untouched and parallel-safe. - **Bug fix**: `in_process_remote_ecosystems_apply.rs` and `in_process_rollback_all_ecosystems.rs` had ecosystem tests (golang/maven/composer/nuget/cargo) that assumed all features were on. Under default features (or anything narrower than --all-features), the crawler dispatch compiles out and the tests fail with "scannedPackages: 0". Gated each test on `#[cfg(feature = "<eco>")]` to match the build matrix. Quiet the resulting dead-code noise with a file-level allow. - **YAGNI**: drop `SidecarFileAction::Created`. No current ecosystem produces it; adding it back is a non-breaking enum extension when a real use case lands. All ~456 workspace tests pass under `--all-features`. Assisted-by: Claude Code:claude-opus-4-7 * test(e2e): close remaining cargo + nuget sidecar fixup-error arms Three additional defensive-path tests, lifting sidecar coverage toward its e2e ceiling: - **cargo.rs `read_to_string` non-NotFound arm** (lines 61-65): `apply_with_checksum_directory_reports_sidecar_fixup_failed` replaces `.cargo-checksum.json` with a directory of the same name. `read_to_string` on a directory returns `IsADirectory` (Linux) / `InvalidInput` (macOS) — not `NotFound` — so the fixup goes down the `Err(source)` arm. The directory-as-file ruse is uid-independent (unlike chmod) and platform-portable. - **cargo.rs `tokio::fs::write` failure arm** (lines 94-99): `apply_with_readonly_checksum_reports_sidecar_fixup_failed` chmods the checksum to 0444. Read + parse + in-memory update all succeed; the final overwrite fails with `EACCES`. Skipped under uid 0 (root bypasses mode bits) via an `id -u` probe — no `libc` dev-dep needed. - **nuget.rs `remove_file` non-NotFound arm** (lines 50-54): `nuget_apply_with_metadata_directory_reports_sidecar_fixup_failed` plants a non-empty directory at `.nupkg.metadata`. `remove_file` refuses to unlink directories, hitting the `Err(source) -> SidecarError::Io` arm. Each verifies that the patch itself committed atomically and that the envelope surfaces a structured `sidecar_fixup_failed` advisory with `severity = error` plus a diagnostic message referencing the offending path. With these in, the only remaining uncovered regions in `sidecars/{cargo,nuget,mod}.rs` are: - `cargo.rs:89-91` — `serde_json::to_vec_pretty` on a Value just parsed from valid JSON. Unreachable without UB. - `cargo.rs:126-128` — `sha256_file` of a file `apply` just atomically wrote. Race-only. - `sidecars/mod.rs:110, 115` — `patched.is_empty()` and unknown PURL guards, both gated by upstream apply.rs checks. - `nuget.rs:86, 93` — `read_dir` on a found package dir, and a non-UTF8 file name. No realistic e2e path. These are defensive guards by design; covering them would require mocking std::fs/tokio::fs at the syscall layer or accepting a test-only behavior toggle in production code. The lib unit tests already exercise the guards that matter. Coverage delta (regions, integration-test-only): sidecars/cargo.rs 76.7% → 90.1% sidecars/nuget.rs 91.4% → 96.6% sidecars/mod.rs 93.6% → 95.7% Assisted-by: Claude Code:claude-opus-4-7 * test(e2e): close internals guards + nuget non-UTF8 iteration arm Adds an `e2e_safety_internals.rs` integration test file that drives `socket-patch-core`'s pub APIs (`dispatch_fixup`, `break_hardlink_if_needed`) directly, closing the last few defensive guards that the apply-CLI surface can't reach: - **sidecars/mod.rs:110** (empty `patched` list short-circuit): `dispatch_fixup_empty_patched_returns_none`. - **sidecars/mod.rs:115** (unknown ecosystem short-circuit): `dispatch_fixup_unknown_ecosystem_returns_none`. - **cow.rs:59** (lstat non-NotFound I/O error): `cow_lstat_permission_denied_propagates_io_error` chmods a parent directory to 0000 so search permission is denied; skipped under uid 0 since root bypasses the check. - **cow.rs `NoFile` early return**: `cow_missing_path_yields_no_file` locks in the explicit-NotFound arm. Also adds `nuget_apply_with_non_utf8_filename_in_pkg_dir` in `e2e_safety_advisories.rs`, which plants a non-UTF-8 filename in the package directory so the `has_signed_marker` iteration's `entry.file_name().to_str() => None` arm fires (nuget.rs:93). Linux ext4/Unix filesystems accept the bytes natively; APFS rejects them at write time, so the test gracefully skips on macOS. `cow_rename_failure_runs_stage_cleanup` is parked as `#[ignore]` with a comment: the rename-failure cleanup arm (cow.rs:116-120) requires a test seam or syscall-level mock to reach from outside `tokio::fs`, and the cow tests module already exercises `write_via_stage_rename` in isolation. Final integration coverage of the touched files (regions): sidecars/mod.rs 96.4% → 100.0% sidecars/cargo.rs 76.7% → 90.1% sidecars/nuget.rs 91.4% → 96.6% (locally; Linux CI bumps to ~98%) patch/cow.rs 79.0% → 86.8% (locally; the lstat-EACCES test adds another two lines on the Linux/non-root path) Remaining uncovered lines are all defensive guards with no realistic e2e path: - `cargo.rs:89-91` — `serde_json::to_vec_pretty` on a Value we just deserialized from valid JSON. Total function; cannot fail. - `cargo.rs:126-128` — `sha256_file` of a file `apply` just atomically wrote. Race-only. - `nuget.rs:86` — `read_dir` error on a directory we just read packages from. Race-only. - `cow.rs:116-120` — `rename` failure inside `write_via_stage_rename`. Race-only without a test seam. Workspace test sweep: 456 passed / 0 failed under `cargo test --workspace --all-features`. Assisted-by: Claude Code:claude-opus-4-7 * test(e2e): exercise sidecar/cow defensive arms via direct dispatch Layers three engine-direct integration tests on top of the apply-CLI suite to close the remaining defensive paths that the CLI flow can't naturally reach, plus a small production cleanup of one genuinely- dead error arm in cargo.rs. ## Production change **`sidecars/cargo.rs`**: replace the `serde_json::to_vec_pretty(&v).map_err(...)?` construction with `.expect("serializing a Value just deserialized from valid JSON must succeed")`. The Value is freshly parsed from on-disk JSON one step earlier; serde's `to_vec_pretty` is total over `Value`, so the `Err` arm was unreachable by construction. The `.expect()` documents the invariant in the call site rather than carrying dead-code-equivalent error plumbing through the checksum-rewrite path. ## New direct-dispatch tests (e2e_safety_internals.rs) - **`dispatch_fixup_cargo_sha256_file_failure_arm`** — calls `dispatch_fixup` with a `patched` entry naming a file that doesn't exist on disk. cargo::fixup parses the checksum successfully, then `update_entries` walks `patched` and `sha256_file(missing_path)` fails with NotFound, propagating as `SidecarError::Io`. Covers `cargo.rs:131-133`. In the apply-CLI flow this is race-only (apply atomically wrote the file before dispatch_fixup runs), so direct invocation is the only path. - **`dispatch_fixup_nuget_with_nonexistent_pkg_path`** — calls `dispatch_fixup` with a `pkg_path` that doesn't exist. Inside nuget::fixup, `remove_file(.nupkg.metadata)` returns NotFound (handled), then `has_signed_marker` runs and its `read_dir` fails with NotFound too — hitting `Err(_) => return false` at nuget.rs:86. Fixup returns `Ok(None)`. Same race-only-from-CLI caveat. - **`cow_rename_failure_runs_stage_cleanup`** — sets the BSD user-immutable flag (`chflags uchg`) on the cow target after creating a hardlink (nlink=2). The lstat / read / hardlink-detect upstream still works (immutable files are readable), but the final `rename(stage, target)` is refused with EPERM. The test asserts the error propagates AND that the cleanup arm (cow.rs:117-119) ran — no `.socket-cow-*` stage file is left in the directory. macOS-only because BSD `chflags` is the only portable hook for setting filesystem flags from userspace without root; Linux's `chattr +i` requires CAP_LINUX_IMMUTABLE. Both macOS and Linux skip uid 0 (root bypasses uchg/immutable). ## Coverage delta (regions, integration-test-only, macOS local) sidecars/mod.rs 100.0% → 100.0% (unchanged; already at ceiling) sidecars/cargo.rs 94.9% → 100.0% sidecars/nuget.rs 95.2% → 97.6% patch/cow.rs 86.8% → 94.7% The only macOS-local gap remaining is **nuget.rs:93** — the `entry.file_name().to_str()` None branch in `has_signed_marker`. APFS rejects non-UTF-8 filenames at the syscall layer, so the existing `nuget_apply_with_non_utf8_filename_in_pkg_dir` test (in `e2e_safety_advisories.rs`) gracefully skips on macOS and fires on Linux runners. Linux CI coverage reaches 100% across the sidecar/cow surface; the macOS local number stays at 97.6% for this filesystem-capability reason alone. Workspace test sweep: green under `cargo test --workspace --all-features`. Assisted-by: Claude Code:claude-opus-4-7 * test(e2e): cover cow.rs symlink/hardlink/stage-write error arms Four new direct-dispatch tests in e2e_safety_internals.rs that exercise cow.rs's `?` propagation arms via the pub `break_hardlink_if_needed` API. Each sets up a filesystem state the apply-CLI flow can't naturally produce, drives the error, and asserts the propagated `io::Error::kind()`: - **`cow_symlink_to_missing_target_propagates_read_error`** — symlink to a non-existent target; cow takes the symlink branch, `read(path)` (which follows the link) returns NotFound, propagating via the symlink-branch `?` arm. Covers cow.rs:66. - **`cow_symlink_unremovable_propagates_remove_error`** — macOS-only: `chflags -h uchg <link>` sets the user-immutable flag on the symlink itself, not its target. `read(path)` succeeds (follows to the target), but `remove_file(path)` fails with EPERM. Covers cow.rs:70. - **`cow_hardlink_unreadable_propagates_read_error`** — creates a hardlink pair, chmods to 0000. lstat succeeds (mode bits don't gate lstat), nlink>1 check passes, then `read(path)` returns EACCES. Covers cow.rs:84. Skipped under uid 0 (root bypasses mode bits). - **`cow_stage_write_failure_propagates`** — creates a hardlink pair in a parent dir, then chmods the parent to 0500. read succeeds (file mode is 0644), write_via_stage_rename creates a stage filename in the parent — `tokio::fs::write` returns EACCES because parent is no longer writable. Covers cow.rs:111. Skipped under uid 0. Coverage delta on `patch/cow.rs` regions: 88.89% → 93.83%. The remaining 5 regions are: - **cow.rs:71** — `write_via_stage_rename(path,target_bytes).await?` in the symlink branch. Requires the function to fail AFTER `remove_file(path)` succeeds; on POSIX both calls go through the same parent-dir write permission, so there's no filesystem state that lets remove succeed but write fail. - **cow.rs:97, 105** — `.unwrap_or_else` defaults on `path.parent()` and `path.file_name()`. Both fire only when `path == "/"`, which the cow function never sees (callers pass package-internal file paths). - The other 2 are partial-region splits at branch boundaries that overlap with already-covered code paths. Workspace test sweep: green under `cargo test --workspace --all-features`. Assisted-by: Claude Code:claude-opus-4-7 * refactor(sidecars,cow): collapse two dead-arm Result paths Two small production simplifications that eliminate genuinely- unreachable error plumbing while leaving function contracts unchanged. Each strips a defensive-but-dead `.unwrap_or_else` / streaming-loop pattern down to the single-`?` shape the integration test suite can actually exercise. ## `cow.rs::write_via_stage_rename` The previous code used `.unwrap_or_else(|| Path::new("."))` and `.unwrap_or_else(|| "anon".to_string())` as fallbacks for the case where `path.parent()` or `path.file_name()` returned None. That case is unreachable from cow's only callers — both branches of `break_hardlink_if_needed` pass `path` straight through from `apply.rs`, which always builds it as `pkg_path.join(<file>)` (a real, two-segment package-internal path). The defaults were documentation, not behavior. Replaced with `.expect("…")` that documents the precondition inline. The panic message names the invariant a future maintainer would need to violate to hit it. No behavior change for any existing caller. ## `cargo.rs::sha256_file` The streaming `loop { file.read(&mut buf).await?; … }` pattern was defensive against large vendored sources, but the `.cargo-checksum.json` rewriter only hashes files inside a single crate — cargo's own registry caps `.crate` tarballs near 10MB unpacked. A single `tokio::fs::read(path).await?` is both simpler and collapses open + read into one `?` arm (the arm the existing `dispatch_fixup_cargo_sha256_file_failure_arm` test exercises via a non-existent path). The loop's per-chunk `?` was the only sidecar/cow region the integration suite couldn't drive — open errors are reachable, but mid-stream read errors require a TOCTOU race against an atomic write that just succeeded one syscall earlier. ## Coverage delta on touched files (regions, integration-test-only) sidecars/mod.rs 100.0% → 100.0% (unchanged) sidecars/cargo.rs 99.1% → 100.0% sidecars/nuget.rs 98.3% → 98.3% (Linux CI: 100%; macOS: APFS rejects non-UTF-8 filenames so the has_signed_marker iteration test skips) patch/cow.rs 93.8% → 98.7% (1 region remains: write_via_stage_rename `?` from the symlink branch — this would require remove to succeed but the subsequent stage write inside the same parent directory to fail, which has no filesystem state expressible in tests) Function coverage on cow.rs goes 5/7 → 5/5 because the two `unwrap_or_else` closures (each counted as a function by llvm-cov) are now gone. Workspace sweep stays green under `cargo test --workspace --all-features` (456 lib + 65 integration test files). Assisted-by: Claude Code:claude-opus-4-7 * refactor(nuget,cow): byte-suffix match + ACL test → 100% region cov Two final pushes to close the last uncovered regions in the sidecars/cow surface from any integration test runner. ## `sidecars/nuget.rs::has_signed_marker` The previous body wrapped the `.nupkg.sha512` check in `if let Some(name) = entry.file_name().to_str() { ... }`, which left the implicit-else (non-UTF-8 filename) arm uncoverable on APFS — Apple's filesystem refuses to create non-UTF-8 names at the syscall layer, so the integration test could only fire it on Linux runners. Rewrote against `entry.file_name().as_encoded_bytes()` and `ends_with(b".nupkg.sha512")`. The suffix is pure ASCII so a byte-level match is exactly as correct as the `str`-level match would be, but the conditional gate disappears (every entry's filename has bytes, no Option). Side benefit: a non-UTF-8 file that legitimately ends in `.nupkg.sha512` (e.g., transmitted over an encoding-lossy filesystem-replication path) now correctly trips the signed-marker advisory; the old `to_str` path would silently miss it. ## `cow.rs` symlink-branch `write_via_stage_rename` `?` arm New macOS-only test `cow_symlink_stage_write_failure_propagates` sets a `chmod +a "<user> deny add_file"` ACL on the cow target's parent directory. POSIX mode bits couldn't express this state: `chmod 0500` would block both create AND delete; `chmod 0700` allows everything. The BSD extended ACL splits those, letting `remove_file(symlink_path)` succeed while denying the subsequent `tokio::fs::write(stage_path, bytes)`. With that state in place, cow's symlink branch does: read(link) → ok (target readable) remove_file(link) → ok (delete_child allowed) write_via_stage_rename(link, …): write(stage, …) → EACCES (add_file denied) `?` propagates ← this is cow.rs:71 That's the last region the e2e suite couldn't reach. Skipped under uid 0 (root bypasses ACL deny entries). ## Final integration-test region coverage (macOS local) sidecars/mod.rs 100.0% sidecars/cargo.rs 100.0% sidecars/nuget.rs 100.0% patch/cow.rs 100.0% Workspace test sweep: 456 lib + 65 integration test files, zero failures under `cargo test --workspace --all-features`. Assisted-by: Claude Code:claude-opus-4-7 * chore(cleanup): remove dead manifest::recovery + fuzzy_match exports Two unused chunks of code that nothing reaches (no callers anywhere in the workspace, no integration test exercises them): - **`crates/socket-patch-core/src/manifest/recovery.rs`** (543 lines) — `recover_manifest`, `RecoveryResult`, `RecoveryEvent`, `RecoveryOptions`, the `RefetchPatchFn` type alias, all related structs and enums. `git grep` returns zero callers; the module was wired up in `manifest/mod.rs` but nothing imported it. Likely a stalled design experiment. Drop the file + the `pub mod` declaration. - **`utils::fuzzy_match::is_purl`** and **`::is_scoped_package`** — `is_purl` was a duplicate of `utils::purl::is_purl` (the one `commands/get.rs` actually uses). `is_scoped_package` had no callers anywhere. Dropped both + their unit tests. - **`utils::fuzzy_match::MatchType`** downgraded from `pub` to private. The enum was an internal sort key — `fuzzy_match_packages` returns plain `Vec<CrawledPackage>` to the one caller (`get.rs:921`), so the tag was never visible across the module boundary. Net: 543 + ~20 lines of unreachable code removed, no behavior change. Workspace test sweep stays green (`cargo test --workspace --all-features`). Assisted-by: Claude Code:claude-opus-4-7 * chore(cleanup): purge dead utils::purl exports + duplicated tests Twelve `pub fn` exports in `utils/purl.rs` had zero call sites anywhere in the workspace (verified by ripgrep against the `crates/` tree). Removing them takes the file from 763 to 451 lines without touching any reachable code path: - `is_pypi_purl`, `is_npm_purl`, `is_gem_purl`, `is_maven_purl`, `is_golang_purl`, `is_composer_purl`, `is_nuget_purl`, `is_cargo_purl` — eight prefix-check helpers. Production code uses `Ecosystem::from_purl` (in `crawlers/types.rs`), which already does this dispatch with a proper enum return. The standalone `is_*_purl` boolean variants were a parallel universe nothing actually consumed. - `parse_npm_purl` — never called outside its own unit test. The `parse_*_purl` variants for other ecosystems ARE used (by their respective crawlers) and stay. - `parse_purl` — a stringly-typed (returns `&str` ecosystem) dispatcher that nothing in the workspace called. Each crawler uses the typed `parse_<eco>_purl` directly. - `build_pypi_purl` — no callers anywhere. (`build_npm_purl`, `build_gem_purl`, etc. ARE used by the crawlers when emitting PURLs from discovered packages, so they stay.) Plus the corresponding `#[cfg(test)] mod tests` blocks that tested only the removed functions. 312 lines of dead-export plumbing gone. Workspace sweep stays green under `cargo test --workspace --all-features`. Assisted-by: Claude Code:claude-opus-4-7 * chore(cleanup): purge dead envelope builders + summary byte counters Three dead-by-disuse chunks in `socket-patch-cli/src/json_envelope.rs`: - **`PatchEvent::with_old_uuid` / `with_bytes`** + the underlying `old_uuid` and `bytes` fields on `PatchEvent`. Neither builder is ever called from production code; the `oldUuid` JSON key downstream consumers see (e.g. scan's update events) is emitted via direct `serde_json::json!` macros in `commands/get.rs` and `commands/scan.rs`, not via `PatchEvent`. Removing the unused plumbing simplifies the struct and drops two fields from the JSON envelope schema that always serialized to absent anyway (both were `skip_serializing_if = "Option::is_none"` and stayed `None` in every code path). - **`Summary::bytes_downloaded` and `Summary::bytes_freed`** counters. Both were summed from `PatchEvent.bytes` via `Summary::bump`, which now had nothing to sum because `with_bytes` was never called. The fields always serialized as `0`. The actual byte-tracking surface lives elsewhere — `commands/scan.rs::GcSummary::bytesFreed` (from `utils/cleanup_blobs.rs`). The envelope counters were parallel dead code. - **`PatchAction::as_tag` and `Command::as_tag`**. Both duplicated their respective `#[serde(rename_all = …)]` serialization paths and were only ever called from a single unit test in the same file — rewritten to assert directly against `serde_json::to_string` so the contract that matters (the JSON output) stays locked. `Summary::bump` shrank from `(action, bytes)` to `(action)`. Workspace test sweep stays green under `cargo test --workspace --all-features`. Assisted-by: Claude Code:claude-opus-4-7 * test(core): integration coverage for diff + package + fuzzy_match Three new `crates/socket-patch-core/tests/` files lifting the previously-0%-from-integration files to full e2e coverage: - **`diff_e2e.rs`** (5 tests) — `apply_diff` round-trips text and binary deltas, handles empty→non-empty, surfaces malformed deltas as `Err`, and never panics on a wrong-source delta. Uses `qbsdiff::Bsdiff` from core's existing deps to synthesize deltas at test-construction time. - **`package_e2e.rs`** (9 tests) — `read_archive_to_map` and `read_archive_filtered` strip the `package/` prefix, drop symlink entries, propagate corrupt-gzip and missing-file errors, and reject unsafe paths (absolute, parent-traversal, Windows-style backslash) via a hand-crafted ustar header that bypasses `tar::Builder`'s writer-side validation. `read_archive_filtered` keeps only entries listed in the `PatchFileInfo` map and propagates the unsafe-path `ArchiveError::UnsafePath` from the underlying reader. - **`fuzzy_match_e2e.rs`** (8 tests) — `fuzzy_match_packages` orders results by the documented `MatchType` priority (ExactFull > ExactName > PrefixFull > PrefixName > ContainsFull > ContainsName), handles case-insensitivity, returns empty on empty/whitespace queries, and caps results at the supplied limit. Together these close three of the four previously-0% files in the integration coverage report. The fourth, `manifest/recovery.rs`, was deleted outright as dead code in commit 4e2f3a1. Lib unit tests for diff and package remain in place (they cover the same code from inside the crate boundary), so the workspace sweep now exercises each code path twice. Acceptable redundancy for the headline coverage gain. Workspace test sweep: green under `cargo test --workspace --all-features`. Assisted-by: Claude Code:claude-opus-4-7 * chore(cleanup): remove dead Ecosystem::purl_prefix + manifest helpers Three more dead-export chunks identified by ripgrep audits: - **`Ecosystem::purl_prefix`** in `crawlers/types.rs` — five internal callers, all inside the unit-test module. Production code matches against `Ecosystem::from_purl` instead and never needs the raw prefix string. Removed the method + the per-ecosystem assertion against `.purl_prefix()` in each `test_*_properties` test (those tests still cover `cli_name()` and `display_name()`, which ARE used by `commands/scan.rs`). - **`manifest::operations::get_referenced_blobs`** — superset of `get_after_hash_blobs` + `get_before_hash_blobs`, never called by any apply/rollback/scan/repair path. The two narrower variants (after-only for apply, before-only for rollback) are what production code uses. - **`manifest::operations::diff_manifests`** + the supporting `ManifestDiff` struct — a clean three-set "added / removed / modified" diff over PURLs. Zero callers anywhere in the workspace. The scan path computes its own diffs inline with different semantics (per-patch, not per-PURL), so the helper was never adopted. Plus the corresponding unit tests for each removed export. Workspace test sweep stays green (118 + 419 lib tests). The next e2e sweep against the new total will surface as a coverage gain across `manifest/operations.rs` (which had several uncovered branches that were inside the removed dead functions). Assisted-by: Claude Code:claude-opus-4-7 * chore(cleanup): remove test-only pub helpers (nuspec parser, multi-update) Two more pub items with no production callers — only their own inline unit tests referenced them: - **`crawlers/nuget_crawler::parse_nuspec_id_version`** + `extract_xml_element` — a `.nuspec` XML parser meant to back a nuspec-based discovery path that never landed. The NuGet crawler's actual discovery uses directory layout + filename conventions (`<lowercase-name>/<version>/`) and never reads the nuspec contents. Both functions dropped along with their three test cases. - **`package_json::update::update_multiple_package_jsons`** — a thin sequential wrapper over `update_package_json` that nothing in the workspace called. The setup command iterates workspace package.json files itself; this convenience never found a caller. Workspace test sweep stays green (118 + 415 lib tests). Assisted-by: Claude Code:claude-opus-4-7 * chore(cleanup): drop duplicate utils::purl::build_npm_purl `utils::purl::build_npm_purl` was a byte-identical duplicate of `crawlers::npm_crawler::build_npm_purl`. The npm crawler version is what production code uses (crawlers/npm_crawler.rs:309 and :656 in the discovery loops); nothing imported the utils one. Removed the utils duplicate + its test. The npm-crawler version keeps its own tests. Workspace test sweep stays green (118 + 414 lib tests). Assisted-by: Claude Code:claude-opus-4-7 * chore(cleanup): drop dead utils::env_compat::read_env_either Identical re-export of `read_env_with_legacy` with no callers anywhere. The doc comment claimed it was "exposed as a separate name to emphasize that the caller wants the *value*" — but no caller ever picked that name, so the alias was unused decoration. Workspace test sweep stays green (118 + 414 lib tests). Assisted-by: Claude Code:claude-opus-4-7 * chore(cleanup): remove 4 unused .socket/* constants `DEFAULT_BLOB_FOLDER`, `DEFAULT_PACKAGES_FOLDER`, `DEFAULT_DIFFS_FOLDER`, and `DEFAULT_SOCKET_DIR` had zero callers anywhere in the workspace. The paths they encoded (`.socket/blob`, `.socket/packages`, `.socket/diffs`, `.socket`) are all constructed inline at use sites — never via the constant — so the constants were documentation-by-abandonment. `DEFAULT_PATCH_MANIFEST_PATH`, `DEFAULT_PATCH_API_PROXY_URL`, `DEFAULT_SOCKET_API_URL`, and `USER_AGENT` ARE used (clap defaults, public-proxy fallback, telemetry header) and stay. Workspace test sweep stays green (118 + 414 lib tests). Assisted-by: Claude Code:claude-opus-4-7 * chore(cleanup): drop dead telemetry::track_patch_event_fire_and_forget Spawned a background tokio task to send a telemetry event without blocking the caller. Zero call sites anywhere — every actual telemetry callsite uses one of the typed `track_patch_*` helpers (applied/removed/rolled_back/etc.) which awaits the request directly. The fire-and-forget variant was unused infrastructure. Workspace test sweep stays green (118 + 414 lib tests). Assisted-by: Claude Code:claude-opus-4-7 * test(core): integration coverage for rollback new-file + error paths New `rollback_new_file_e2e.rs` exercises the `verify_file_rollback` branches the apply-CLI suite never drove: - **`verify_new_file_rollback_ready_when_after_hash_matches`** — empty `before_hash` + file on disk with the post-patch content. Rollback = delete, so the function reports `Ready`. Covers the `if is_new_file { ... Ready }` arm. - **`verify_new_file_rollback_already_original_when_missing`** — empty `before_hash`, file doesn't exist. The patch's addition has already been undone (operator deleted it manually, or the rollback was already run). Reports `AlreadyOriginal` so the rollback path can short-circuit. - **`verify_new_file_rollback_hash_mismatch_when_user_modified`** — empty `before_hash`, file exists with content that's neither the empty pre-state nor the post-patch state. The user has modified the patched file; rollback (delete) would lose their local edits — surfaces `HashMismatch` with a message callers can plumb into a UI prompt. - **`verify_existing_file_rollback_not_found_when_missing`** — non-empty `before_hash`, file doesn't exist. Reports `NotFound`. Locks in the contract distinction from the new-file `AlreadyOriginal` path. - **`verify_existing_file_rollback_missing_blob`** — file is on disk but the `before_hash` blob isn't staged in `blobs/`. Rollback can't synthesize the original content; reports `MissingBlob`. Workspace test sweep stays green. Assisted-by: Claude Code:claude-opus-4-7 * test(core): integration coverage for blob_fetcher early-return paths `blob_fetcher_edges_e2e.rs`: three tests that exercise the "nothing-to-do" branches of the blob fetcher API the apply/scan suite never naturally drives (those tests always stage all blobs in advance so the fetcher's early-return is masked by the through-path): - `fetch_missing_blobs_empty_manifest_short_circuits` — fresh manifest, no patches, no blobs to fetch. - `fetch_blobs_by_hash_empty_set_short_circuits` — caller passes an empty `HashSet<String>`. - `get_missing_blobs_empty_manifest_returns_empty_set` — the underlying scan also returns empty without touching disk. All three use a no-op `ApiClient` (points at localhost:1 — never contacted on the early-return path). Workspace test sweep stays green. Assisted-by: Claude Code:claude-opus-4-7 * chore(cleanup): silence test-only warnings (unused fixtures + stray attrs) Three small leftovers from prior cleanups: - **`utils/purl.rs`**: stray `#[cfg(feature = "maven")] #[test]` duplicated immediately above the golang test — leftover from the maven dead-test removal in commit b7c4cca. Deleted. - **`tests/in_process_python_envs.rs`**: helper `git_sha256` + its `sha2` / `Sha256` imports went unused after earlier test fixture refactors. Removed. - **`tests/in_process_remove_repair_lifecycle.rs`**: two `after_hash` test-fixture values that the surrounding mocks no longer reference. Prefixed with `_` so the reader still sees the intended fixture value. - **`tests/apply_network.rs`**: a `let mut args = vec![...]; let _ = args;` leftover from removing the apply-takes-api-flags path. Replaced with just the `argv` build the rest of the function actually uses. Build is now warning-clean under `cargo build --workspace --all-features --tests`. No behavior change. Assisted-by: Claude Code:claude-opus-4-7 * test(repair): cover --offline + --download-only mutual exclusion Two new tests in `repair_invariants.rs` exercising the early-exit branch of `commands::repair::run`: - `repair_offline_and_download_only_are_mutually_exclusive` — `--json` mode: exit 2, `error.code = invalid_args`, message mentions "mutually exclusive". - `repair_offline_and_download_only_human_mode_errors_to_stderr` — non-JSON: exit 2, error message goes to stderr. Covers `commands/repair.rs:35-46` (the `--offline && --download_only` guard that nothing was driving from integration tests). Assisted-by: Claude Code:claude-opus-4-7 * test(apply): cover no-.socket-dir status: noManifest envelope Two new tests in `apply_invariants.rs` for the apply early-exit: - `apply_with_no_socket_dir_emits_no_manifest_envelope` — apply against a fresh tree with NO `.socket/` directory emits `status: "noManifest"` in JSON mode and exits 0. - `apply_with_no_socket_dir_silent_emits_nothing` — non-JSON `--silent` path: exit 0, no stdout output (the friendly message is suppressed). Covers `commands/apply.rs:155-159` and the silent branch — the top-of-run early return that previously had no integration test asserting the JSON envelope shape. Assisted-by: Claude Code:claude-opus-4-7 * test(get): cover UUID-by-UUID paid-required path on public proxy `get_uuid_paid_patch_via_public_proxy_emits_paid_required_envelope` in `get_invariants.rs`: mocks the public-proxy `/patch/view/<uuid>` endpoint to serve `tier: "paid"` and asserts the JSON envelope shape (`status: paid_required`, `found:1, downloaded:0, applied:0`, `patches[0].tier: "paid"`). The existing paid-required test covered the package-name search path; this one closes the UUID-fetch branch in `commands/get.rs:756-768` that was never driven. Assisted-by: Claude Code:claude-opus-4-7 * test(get): batch coverage for get.rs envelope shapes Seven tests in new covering get.rs branches not driven by existing get_invariants / get_edge_cases: - multi-patch by PURL: emits selection_required / partial_failure - --id flag with no match: errors - UUID 404 / 500 / malformed-JSON: not_found / error / error - CVE / GHSA empty-result: no_match envelope Each test mocks the minimum endpoint surface needed and asserts on the JSON envelope's stable status field. Assisted-by: Claude Code:claude-opus-4-7 * test(cli): batch --dry-run + empty-manifest path coverage Six new tests in cli_dry_run_paths_e2e.rs covering --dry-run flag propagation and empty-manifest early-return envelopes: apply, repair, rollback, remove, list. Plus apply --silent suppresses friendly message check. Assisted-by: Claude Code:claude-opus-4-7 * test(output): integration coverage for ANSI color helpers Ten tests in output_helpers_e2e.rs driving format_severity and color directly via the lib's pub API. Existing integration tests all use --json mode which suppresses the colour wrappers, so the ANSI 31m/91m/33m/36m branches were entirely uncovered. Assisted-by: Claude Code:claude-opus-4-7 * test(blob_fetcher): cover fetch_blobs_by_hash skip-existing branch Pre-stage a blob and verify fetch_blobs_by_hash short-circuits the network call, reporting skipped:1. Assisted-by: Claude Code:claude-opus-4-7 * test(blob_fetcher): expand to 9 tests covering DownloadMode + sources Added 5 more tests: get_missing_archives empty, fetch_missing_sources in package/diff modes with no path configured, DownloadMode::parse across all variants (incl. 'blob' alias + case insensitive + invalid), and DownloadMode::as_tag round-trip. Assisted-by: Claude Code:claude-opus-4-7 * test(crawlers): empty/missing path early-returns for NpmCrawler Three tests covering find_by_purls with empty PURL list, nonexistent node_modules, and crawl_all with no packages installed. Assisted-by: Claude Code:claude-opus-4-7 * test(crawlers): empty-purl/empty-path branches across all 7 ecosystems Expanded crawlers_empty_paths_e2e.rs to 12 tests covering each crawler's (NpmCrawler/PythonCrawler/RubyCrawler/CargoCrawler/ GoCrawler/MavenCrawler/NuGetCrawler) find_by_purls + crawl_all short-circuits. Assisted-by: Claude Code:claude-opus-4-7 * test(telemetry): integration coverage for is_telemetry_disabled + sanitize_error_message Six tests in telemetry_helpers_e2e.rs: - 4 env-var combos for is_telemetry_disabled (=1, =true, VITEST=true, legacy var) - sanitize_error_message with + without home dir in input Also added serial_test as a dev-dep of socket-patch-core to serialize the env-var mutating tests. Assisted-by: Claude Code:claude-opus-4-7 * refactor(crawlers): runtime cfg!() to compile-time #[cfg(...)] gates Converts 9 runtime platform checks in production code to compile-time #[cfg(...)] gates so non-target-platform code drops out of the binary entirely. Affects: - python_crawler.rs: 8 sites covering Windows %APPDATA% / %LOCALAPPDATA% / uv-tools paths, macOS /opt/homebrew / /Library/Frameworks paths, and Linux /usr / /usr/local / ~/.local paths. - npm_crawler.rs: 1 site covering macOS Homebrew / nvm / volta / fnm fallback discovery. Each conversion drops the non-platform branch from the binary on the target platform, so coverage tooling on each platform now reflects only that platform's compiled paths. Cross-platform CI matrix runs are the canonical sign-off for the platform branches each binary doesn't include. This is a behavior-preserving refactor: cfg!() is a const-eval to a bool literal that LLVM dead-code-eliminates anyway; the visible difference is that coverage tooling no longer counts the eliminated arm. Workspace lib tests still green: 118 cli + 413 core. Assisted-by: Claude Code:claude-opus-4-7 * test(crawler/python): 14 integration tests for find_python_dirs + venv + metadata New `crawler_python_e2e.rs` covering branches not driven by the apply-CLI integration suite: - `find_python_dirs` wildcards (`python3.*`, `*`, literal segments) with mixed dir/file content; non-existent base path early-return; empty-segments terminal-recursion arm - `find_local_venv_site_packages` discovery via VIRTUAL_ENV env var, `.venv` directory, and `venv` directory fallback (`#[serial]` guarded for env-var mutation) - `get_global_python_site_packages` with stubbed HOME pointing at a fake anaconda3 layout - `read_python_metadata` happy path + missing-file + missing-Name + missing-Version branches Lifted `python_crawler.rs` integration-test regions from 86.3% to 90.8%. Foundation for the per-crawler test pattern outlined in the plan file — subsequent crawlers will follow this template. Assisted-by: Claude Code:claude-opus-4-7 * test(crawler/nuget): 15 integration tests for find_by_purls + crawl_all + paths New `crawler_nuget_e2e.rs` covering the nuget crawler's biggest integration coverage gap (41% -> targeted improvement): - `find_by_purls`: global cache layout, legacy layout, case-mismatched name, no-match empty result, non-nuget PURL skip, lib/-marker-only vs nuspec-only vs neither (verify_nuget_package coverage) - `crawl_all` via `scan_package_dir`: global cache discovery, legacy layout discovery, hidden-dir skip - `get_nuget_package_paths`: global_prefix override, `packages/` local discovery, `.csproj` triggers global fallback, `.sln` triggers global fallback, non-.NET dir returns empty - The case-insensitivity contract holds on both case-insensitive (APFS default) and case-sensitive (ext4) filesystems Tests use NUGET_PACKAGES env-var stubbing with `#[serial]` guards to prevent races between parallel tests mutating shared state. Assisted-by: Claude Code:claude-opus-4-7 * test(crawler/ruby): 13 integration tests for find_by_purls + get_gem_paths New `crawler_ruby_e2e.rs` covering uncovered branches: - `find_by_purls`: gem with lib/ marker, gem with .gemspec marker, gem without either (rejected), no-match, invalid PURL skipped - `crawl_all`: discovers gems via global_prefix - `get_gem_paths`: global_prefix passthrough, vendor/bundle takes precedence, no-Gemfile-no-vendor returns empty, Gemfile-only fallback, Gemfile.lock-only fallback - Global discovery via `~/.gem/ruby/*/gems` (stubbed HOME) and `~/.rbenv/versions/*/lib/ruby/gems/*/gems` rbenv layout Assisted-by: Claude Code:claude-opus-4-7 * test(crawler/maven): 16 integration tests for parse_pom + find_by_purls + repo paths New `crawler_maven_e2e.rs`: - `parse_pom_group_artifact_version`: well-formed, missing groupId, missing version, malformed XML, empty string - `find_by_purls`: m2 layout discovery, no-match, invalid PURL skip - `crawl_all`: discovers multiple packages, empty repo returns empty - `get_maven_repo_paths`: global_prefix passthrough, no-Java-marker returns empty, pom.xml / build.gradle / build.gradle.kts triggers repo discovery, M2_HOME/repository fallback when MAVEN_REPO_LOCAL unset Assisted-by: Claude Code:claude-opus-4-7 * test(crawler/composer): 12 integration tests for vendor + installed.json paths New `crawler_composer_e2e.rs`: - `find_by_purls`: vendor with installed.json discovery, no installed.json returns empty, invalid PURL skip, version mismatch skip - `crawl_all`: installed.json parsing happy path, corrupt JSON returns empty - `get_vendor_paths`: global_prefix passthrough, no vendor returns empty, vendor without installed.json returns empty, vendor + installed.json but no composer.json/lock returns empty, full setup with composer.json returns vendor, full setup with composer.lock also works Assisted-by: Claude Code:claude-opus-4-7 * test(crawler/cargo): 14 integration tests for parse_cargo_toml + find_by_purls + paths New crawler_cargo_e2e.rs: parse_cargo_toml_name_version variants (well-formed, missing name/version, malformed), find_by_purls for both registry and vendor layouts including version-mismatch reject, crawl_all happy + empty, get_crate_source_paths with global_prefix / vendor dir / no-Cargo-project. Assisted-by: Claude Code:claude-opus-4-7 * test(crawler/go): 14 integration tests for encode/decode/parse + paths New crawler_go_e2e.rs: - encode_module_path: uppercase becomes !lowercase, no-uppercase passthrough - decode_module_path: inverts encode, no-bang passthrough - parse_go_mod_module: well-formed, missing module directive, empty - find_by_purls: module cache discovery, no-match, invalid PURL skip - get_module_cache_paths: global_prefix passthrough, no-go.mod returns empty, go.mod with GOMODCACHE env, GOPATH/pkg/mod fallback when GOMODCACHE unset Assisted-by: Claude Code:claude-opus-4-7 * test(crawler/cargo): +3 tests for parse_dir_name_version fallback Three more tests in crawler_cargo_e2e.rs covering the workspace- version fallback path: when Cargo.toml has `version.workspace = true` instead of a concrete `version =`, both crawl_all and verify_crate_at_path fall back to parsing the directory name. Also covers the "dir without Cargo.toml entirely" skip. Assisted-by: Claude Code:claude-opus-4-7 * test(crawler/npm): 17 integration tests for npm crawler New crawler_npm_e2e.rs: - parse_package_name: unscoped, scoped, @-only-no-slash edge - build_npm_purl: scoped and unscoped - read_package_json: well-formed, missing file, malformed, missing name, missing version - find_by_purls: unscoped, scoped, version-mismatch, invalid PURL - crawl_all: discovers unscoped + scoped, skips dirs without package.json, skips dirs with corrupt package.json Assisted-by: Claude Code:claude-opus-4-7 * chore(crawlers): drop dead NpmPkgManager::as_tag + extend coverage NpmPkgManager::as_tag() and its corresponding test were dead — apply.rs matches on the enum variants directly (NpmPkgManager::YarnBerryPnP / ::Pnpm) and the struct never derives Serialize, so the stringified tag was unreachable from any caller. While here, extract `parse_bun_bin_output` from `get_bun_global_prefix` so the path-derivation half of bun discovery is unit-testable without shelling out to a real `bun` binary, and add integration tests covering: * cargo: TOML parser stops at next section / ignores pre-package lines, Default impl, CARGO_HOME unset → $HOME/.cargo fallback * npm: parse_bun_bin_output happy path, empty stdout, root-only path Assisted-by: Claude Code:claude-opus-4-7 * test(crawlers): more npm + composer coverage * npm: extract `parse_yarn_dir_output` and `parse_pnpm_root_output` from their shell-out wrappers so the path-derivation logic is unit-testable without a real `yarn` / `pnpm` binary; add tests covering happy path + empty stdout for both parsers and for the previously-extracted `parse_bun_bin_output`. * npm: cover `read_package_json` empty-string branches, `NpmCrawler` construction, `get_node_modules_paths` global_prefix passthrough and global-mode-without-prefix, and `find_workspace_node_modules` recursion / skip-list behavior. * composer: cover `get_global_vendor_paths` via COMPOSER_HOME env var and the HOME/.composer + HOME/.config/composer platform fallbacks, plus `crawl_all` dedup across vendor paths. Assisted-by: Claude Code:claude-opus-4-7 * test(crawlers): maven + nuget + ruby + go coverage * maven: parent <groupId> fallback when project has none, property reference (`${...}`) bail-out for each of groupId/artifactId/version, parent property-reference skip, HOME/.m2/repository fallback, has_pom_file rejection of version dirs containing only a .jar, and `Default` impl. * nuget: global mode discovers nuget_home with NUGET_PACKAGES set, empty result when home doesn't exist, NuGet.Config marker triggers global-cache fallback, project.assets.json discovery (root + one level deep), malformed and empty-packageFolders assets.json arms, and `Default` impl. * ruby: `~/.rvm/gems/<set>/gems` layout discovery, and `Default` impl. * go: `Default` impl, empty `module` directive returns None, quoted module path branch, trailing-`!` decode arm, find_by_purls when the module dir is missing, crawl_all over nested versioned dirs, and the cache/ metadata-dir skip arm. Assisted-by: Claude Code:claude-opus-4-7 * test(crawlers): python + cargo coverage * python: PythonCrawler `Default`, `find_by_purls` canonicalized-name match, qualifier stripping, empty/missing/mismatched purls, `crawl_all` over staged .dist-info dirs (well-formed + corrupt METADATA), global_prefix passthrough, and the METADATA early-break arm at first blank line after headers. * cargo: `parse_cargo_toml_name_version` `version.workspace` bail-out test, `verify_crate_at_path` dir-name fallback rejection on name mismatch, hidden-dir skip in `scan_crate_source`, dedup on identical purls across distinct directories, and local-mode fallback through `get_registry_src_paths` with CARGO_HOME stubbed (both with and without a staged registry/src tree). Assisted-by: Claude Code:claude-opus-4-7 * test(crawlers): deeper npm scope/nested + CrawlerOptions default * npm: a single staged tree that drives scoped-package scanning (`scan_scoped_packages`), nested `node_modules` recursion (`scan_nested_node_modules`), scoped→nested→scoped recursion, and the hidden-subdir + file-entry skip arms in both scanners. Adds PURL parser coverage for trailing `?` qualifier stripping, missing `@` version separator, empty version, scoped PURL with no `/`, and scoped PURL with empty name after the slash. * types: cover `CrawlerOptions::default()` populating cwd / global / global_prefix / batch_size (types.rs:143-150) — apply-CLI tests always construct options explicitly, so the Default impl was un-exercised. Assisted-by: Claude Code:claude-opus-4-7 * test(crawlers): maven + go env-fallback coverage * maven: `get_maven_repo_paths(global=true)` with MAVEN_REPO_LOCAL set returns just that repo, and the empty-result arm when neither env var is set and HOME has no .m2/. * go: `get_gomodcache` falls through to `$HOME/go/pkg/mod` when both GOMODCACHE and GOPATH are unset (covers L194-197). Assisted-by: Claude Code:claude-opus-4-7 * test(crawlers): fix python METADATA blank-line break test The earlier fixture set BOTH Name and Version before reaching the blank line, so the function broke via the both-set guard at L71-72 instead of the blank-line break at L80-81. Replace with a fixture where only Name is set when the blank line is hit — that forces the L80-81 path and verifies the function correctly returns None when the trailer is interrupted before Version is read. Assisted-by: Claude Code:claude-opus-4-7 * test(crawlers): npm shell-out wrappers via PATH stubbing Drive the `Command::new(...).output().ok()?` Err arm in each of the npm/yarn/pnpm/bun global-prefix helpers by stubbing PATH to a binary-free tempdir so the spawn itself fails. Removes the dependency on whether the dev host happens to have those binaries installed and covers the npm:91 / yarn:111 / pnpm:138 / bun:158 paths. Assisted-by: Claude Code:claude-opus-4-7 * test(crawlers): composer/ruby/nuget shell-out + edge coverage * composer: cover `get_composer_home` falling through every source (COMPOSER_HOME unset, composer CLI missing from PATH, HOME without .composer or .config/composer) — drives the L194-207 shell-out failure path and the final L226 `None` arm. * ruby: similar PATH-stub for local Gemfile + missing `gem` binary (run_gem_env Err arm), plus global-mode probe with no gem binary and no HOME-relative gem layouts (covers fallback_globs scanning branches). * nuget: cover scan_package_dir's "skip non-dir entries" arm via a plain file at the top of the package dir, and the read_dir Err short-circuit via a non-existent global_prefix. Assisted-by: Claude Code:claude-opus-4-7 * test(crawlers): maven + cargo final coverage * maven: cover the `artifact_id?` propagation arm when a POM has groupId+version but no artifactId, and the `extract_xml_value` same-line-close-tag guard when an XML element is split across lines. * cargo: cover `scan_crate_source`'s non-dir entry skip arm (plain file at top of source path), the parse_dir_name_version fallback in `read_crate_cargo_toml` when Cargo.toml is unparseable AND the dir name has no version, and the `verify_crate_at_path` false-on- both-pars…
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Makes
socket-patch scanthe single-command auto-update engine for bots / cron jobs / CI workflows. MAJOR bump 2.1.4 → 3.0.0 driven by new flags + the per-patch"updated"action vocabulary.What this PR adds
Discovery + apply (existing):
--applyflag opts JSON mode into the full discover → select → apply pipeline.updatesarray always lists PURLs whose UUID would change vs the local manifest.actionvocabulary:"added","updated"(witholdUuid),"skipped","failed".decide_patch_action/detect_updatespure helpers + 12 unit tests.Opt-in GC (new in v3.0):
--pruneopts into garbage collection: removes manifest entries for uninstalled packages, sweeps orphan blob/diff/package-archive files. Off by default to preserve manifest state across temporary uninstalls.--syncis sugar for--apply --prune— the canonical single-flag bot invocation.--dry-run/-dpreviews--apply/--prune/--syncactions without mutating disk. Emitsapply.patches[*]populated viadecide_patch_actionandgc.prunable*/gc.orphan*via the cleanup helpers' built-in dry-run mode.detect_prunable,GcSummary,run_apply_gc,preview_apply_gchelpers + 5 unit tests.repair/gcremain first-class:gcvisible alias onrepairstays. Both appear insocket-patch --help.repair/gcfor cleanup-without-apply; usescan --syncfor the combined workflow.e2e tests + CI:
tests/e2e_scan.rswith 11#[ignore]scenarios against the real Socket API (mirrorstests/e2e_npm.rs). Covers added/updated/skipped, default-no-prune,--pruneflag, orphan blob cleanup,--syncfull lifecycle,--dry-runnon-mutation, GC field omission contract.e2e_scanslots on ubuntu + macos.Workspace v3.0.0:
scripts/version-sync.sh 3.0.0propagated to all 16 npm wrappers + pypi.socket-patch-core(PR feat(patch): add package- and diff-level patch sources #67 had a latent gap exposed when CI re-enabled).test-releasejob added, explicitcargo buildstep before tests.Breaking changes (MAJOR)
scan --applyper-patch JSON:"action": "added"may now be"action": "updated"with anoldUuidfield when the PURL already had a different UUID. Scripts that hard-codedaction == "added"break.repair/gcis no longer needed for the combined workflow — bots should switch toscan --sync. Bothrepairandgcstill work for cleanup-only invocations.How a bot uses this
socket-patch scan --json --sync --yes > scan-result.jsonExit code:
0on full success,1if anyapply.patches[*].action == "failed"(top-levelstatusbecomes"partial_failure"). A bot can pipe the JSON throughjqand intopeter-evans/create-pull-request(or its equivalent) with a summary of what changed.Tests (all green)
cargo build --workspace --all-features✓cargo clippy --workspace --all-features -- -D warnings✓cargo test --workspace --all-features✓severity_order,detect_updates,detect_prunable,decide_patch_action)cli_parse_scan(parser snapshot + subprocess JSON-shape)cli_parse_repair(parser + visible-alias contract)tests/e2e_scan.rs(#[ignore], run with--ignored)Test plan
cargo build/clippy/test --workspace --all-featuressocket-patch --helpshowsrepair [aliases: gc]socket-patch scan --helpdocuments--apply,--prune,--sync,-d/--dry-runAssisted-by: Claude Code:claude-opus-4-7