test(cli): foundation for CLI-contract unit-test campaign (#68)

* test(cli): comprehensive unit-test campaign for the CLI contract

Add unit-test coverage for every subcommand, flag, default, alias, and
helper in the socket-patch CLI, plus a new CLI_CONTRACT.md that documents
the surface as semver-significant.

Before this change the CLI crate had zero unit tests under src/ —
only network-dependent tests/e2e_*.rs suites gated on --ignored. A flag
rename, a default change, or a JSON key drift could land green and break
every shipped wrapper (npm @socketsecurity/socket-patch, pypi
socket-patch, cargo, prebuilt binaries).

## What's covered

Library surface (new src/lib.rs):
  - Cli, Commands, looks_like_uuid, parse_with_uuid_fallback extracted
    from main.rs so integration tests can verify the parser without
    spawning the binary.
  - main.rs becomes a thin wrapper that delegates to the lib.
  - Cargo.toml gains [lib] alongside [[bin]].

Core helper extraction:
  - socket_patch_core::manifest::operations::resolve_manifest_path
    replaces the 5-line absolute-vs-relative join block previously
    copy-pasted into apply/rollback/list/remove/repair (5 callers).

CLI_CONTRACT.md (new):
  - Documents every subcommand, flag, default value, visible alias
    (download, gc), hidden alias (--no-apply), JSON output shape, and
    exit code as semver-significant.
  - Pins the divergent defaults: --download-mode=diff for apply/get/scan
    and --download-mode=file for repair, --batch-size=100 for scan.
  - Spells out the bump policy and how to invoke scripts/version-sync.sh.

Helper unit tests (#[cfg(test)] mod tests in each file):
  - src/lib.rs — looks_like_uuid (valid/invalid shapes, case-insensitive),
    parse_with_uuid_fallback (success, fallback, fallback-fails preserves
    original error, no double-rewrite).
  - src/output.rs — format_severity, color, confirm (skip_prompt and
    is_json short-circuits; interactive path intentionally not tested).
  - src/ecosystem_dispatch.rs — partition_purls (filter, dedup, unknown
    ecosystem dropped).
  - commands/apply.rs — verify_status_str (all 4 VerifyStatus variants),
    result_to_json (top-level + filesVerified key sets).
  - commands/rollback.rs — find_patches_to_rollback (None=all, PURL match,
    UUID match, no-match=empty).
  - commands/get.rs — detect_identifier_type (UUID/CVE/GHSA/PURL/None,
    case-insensitive for CVE+GHSA), select_patches (paid auto, free
    single auto, free multi+is_json -> Err(1)).

Clap parser snapshot tests (new tests/cli_parse_*.rs):
  - One file per command: apply, get, list, main, remove, repair,
    rollback, scan, setup.
  - Every flag (long + short) has at least one parser assertion.
  - Every #[arg(default_value)] is asserted on the no-flag parse.
  - The download visible alias on get is exercised.
  - The gc visible alias on repair is exercised.
  - The hidden --no-apply alias on get --save-only is exercised.
  - --ecosystems CSV splitting is verified on apply/rollback/scan.
  - The bare-UUID rewrite is exercised end-to-end via Cli::try_parse_from.
  - Failure paths assert clap::error::ErrorKind variants.

Async run() integration tests:
  - tests/cli_parse_list.rs covers missing manifest -> 1, empty -> 0,
    populated -> 0, absolute-path override, and a subprocess JSON-shape
    assertion against the compiled binary.
  - tests/cli_parse_remove.rs covers missing-manifest -> 1.
  - tests/cli_parse_setup.rs covers no-package-json -> 0 with the
    JSON status:"no_files" shape pinned via subprocess.

## Verification

  cargo build --workspace --all-features
  cargo clippy --workspace --all-features -- -D warnings
  cargo test --workspace --all-features

All clean. 79 new lib tests + 156 new integration tests added on top of
the existing 415 unit tests; cumulative 650 tests pass.

## Why squashed

Originally landed as a foundation PR (#68) plus 10 sibling test PRs
(#69-#78), one per command/file, dispatched in parallel. Squashing the
sibling PRs back into #68 so the contract + tests land as one
self-contained unit — reviewers see the full picture, and a future
revert touches one commit instead of eleven.

Assisted-by: Claude Code:claude-opus-4-7

* ci: tighten CI matrix — add macOS, release-mode tests, explicit build step

The CI workflow's unit-test job ran on ubuntu-latest + windows-latest;
extend the matrix with macos-latest so the new CLI parser tests are
exercised on every platform the binary ships for. socket-patch ships
prebuilt binaries for x86_64-apple-darwin and aarch64-apple-darwin (see
release.yml), so silent macOS-specific regressions in path handling,
TTY detection, or terminal escapes are real risks today.

Three changes:

  - Add `macos-latest` to the test matrix.
  - Add `fail-fast: false` so a failure on one OS doesn't mask failures
    on the others.
  - Add an explicit `cargo build --workspace --all-features` step
    before `cargo test`. `cargo test` already builds, but a dedicated
    build step gives a cleaner red signal when a build-only failure
    happens (e.g. a feature-gated compile error) without the noise of
    test-discovery output.
  - New `test-release` job: `cargo test --workspace --all-features
    --release` on ubuntu-latest. Catches optimization-level regressions
    that debug mode hides (e.g. release-mode-only inlining changes that
    affect assertion behavior). One OS keeps total CI time reasonable
    while still locking in release-mode correctness.

Assisted-by: Claude Code:claude-opus-4-7

* fix(patch): reject POSIX-style absolute paths in archive entries on Windows

`read_archive_to_map` rejects entries whose path is absolute or contains
a `..` component, but the check used `Path::is_absolute()` alone. On
Windows that function requires a drive letter or UNC prefix, so a tar
entry like `/etc/passwd` is NOT considered absolute and would slip
through the guard — when later joined to the target directory, Windows
would treat it as relative to the current drive's root.

Add an explicit check for a leading `/` or `\` byte alongside
`Path::is_absolute()` so the guard rejects POSIX-style absolute paths
on every platform. The new test_read_archive_rejects_backslash_absolute_paths
case locks the symmetric backslash form in.

This was uncovered when the CI matrix was extended to actually run on
Windows. The existing test_read_archive_rejects_absolute_paths failed on
windows-latest because it constructed the archive with a POSIX-style
path that the platform-specific `is_absolute()` did not catch.

Assisted-by: Claude Code:claude-opus-4-7

Author: mikolalysenko

.github/workflows/ci.yml

@@ -38,8 +38,9 @@ jobs:
 
   test:
     strategy:
+      fail-fast: false
       matrix:
-        os: [ubuntu-latest, windows-latest]
+        os: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.os }}
     steps:
       - name: Checkout
@@ -62,9 +63,38 @@ jobs:
           key: ${{ matrix.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
           restore-keys: ${{ matrix.os }}-cargo-
 
+      - name: Build
+        run: cargo build --workspace --all-features
+
       - name: Run tests
         run: cargo test --workspace --all-features
 
+  test-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@efa25f7f19611383d5b0ccf2d1c8914531636bf9 # stable
+        with:
+          toolchain: stable
+
+      - name: Cache cargo
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ubuntu-latest-cargo-release-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ubuntu-latest-cargo-release-
+
+      - name: Run tests (release)
+        run: cargo test --workspace --all-features --release
+
   dispatch-tests:
     runs-on: ubuntu-latest
     steps:

crates/socket-patch-cli/CLI_CONTRACT.md

@@ -0,0 +1,266 @@
+# socket-patch CLI contract
+
+This document defines the **public surface** of the `socket-patch` binary. Anything listed here is part of the user-visible contract: third-party scripts, CI pipelines, and the npm/pypi/cargo wrappers depend on it. Changes are governed by the semver policy at the bottom of this file.
+
+> **Why this exists.** Until late 2026 the CLI crate had zero unit tests under `src/` — only network-dependent `tests/e2e_*.rs` suites that run with `--ignored`. A flag rename, a default-value change, or a JSON key rename could land green and break every shipped wrapper silently. The contract below is now backed by the unit tests under `crates/socket-patch-cli/src/**` (`#[cfg(test)] mod tests`) and the parser tests under `crates/socket-patch-cli/tests/cli_parse_*.rs`. Changes that violate the contract must update those tests in lock-step with a major version bump.
+
+## Subcommands
+
+| Name | Visible alias(es) | Notes |
+|---|---|---|
+| `apply` | — | Apply patches from the local manifest |
+| `rollback` | — | Restore original files; takes optional positional `identifier` |
+| `get` | `download` | Fetch + apply patch; requires positional `identifier` |
+| `scan` | — | Crawl installed packages for available patches |
+| `list` | — | Print patches in the local manifest |
+| `remove` | — | Remove patch from manifest (rolls back first); requires positional `identifier` |
+| `setup` | — | Configure package.json postinstall scripts |
+| `repair` | `gc` | Download missing blobs + clean up unused ones |
+
+**Bare-UUID fallback.** `socket-patch <UUID>` is rewritten to `socket-patch get <UUID>`. The UUID shape checked is the standard 8-4-4-4-12 hex pattern (case-insensitive). See [`src/lib.rs::looks_like_uuid`](src/lib.rs).
+
+## Flags — long and short forms
+
+Every flag below is part of the contract. The default values are pinned by parser tests.
+
+### `apply`
+
+| Long | Short | Default | Type |
+|---|---|---|---|
+| `--cwd` | — | `.` | path |
+| `--dry-run` | `-d` | `false` | bool |
+| `--silent` | `-s` | `false` | bool |
+| `--manifest-path` | `-m` | `.socket/manifest.json` | string |
+| `--offline` | — | `false` | bool |
+| `--global` | `-g` | `false` | bool |
+| `--global-prefix` | — | (none) | path |
+| `--ecosystems` | — | (none) | CSV → `Vec<String>` |
+| `--force` | `-f` | `false` | bool |
+| `--json` | — | `false` | bool |
+| `--verbose` | `-v` | `false` | bool |
+| `--download-mode` | — | **`diff`** | string |
+
+### `rollback`
+
+Same as `apply` plus: `--one-off` (bool), `--org` (string), `--api-url` (string), `--api-token` (string). Positional `identifier` is **optional** (omit to rollback everything).
+
+### `get`
+
+Required positional `identifier`. Flags:
+
+| Long | Short | Alias | Default | Type |
+|---|---|---|---|---|
+| `--org` | — | — | (none) | string |
+| `--cwd` | — | — | `.` | path |
+| `--id` | — | — | `false` | bool |
+| `--cve` | — | — | `false` | bool |
+| `--ghsa` | — | — | `false` | bool |
+| `--package` | `-p` | — | `false` | bool |
+| `--yes` | `-y` | — | `false` | bool |
+| `--api-url` | — | — | (none) | string |
+| `--api-token` | — | — | (none) | string |
+| `--save-only` | — | **`--no-apply`** | `false` | bool |
+| `--global` | `-g` | — | `false` | bool |
+| `--global-prefix` | — | — | (none) | path |
+| `--one-off` | — | — | `false` | bool |
+| `--json` | — | — | `false` | bool |
+| `--download-mode` | — | — | **`diff`** | string |
+
+The hidden alias `--no-apply` on `--save-only` is **part of the contract** — it does not appear in `--help` but is widely used in existing scripts.
+
+### `scan`
+
+| Long | Short | Default | Type |
+|---|---|---|---|
+| `--cwd` | — | `.` | path |
+| `--org` | — | (none) | string |
+| `--json` | — | `false` | bool |
+| `--yes` | `-y` | `false` | bool |
+| `--global` | `-g` | `false` | bool |
+| `--global-prefix` | — | (none) | path |
+| `--batch-size` | — | **`100`** | usize |
+| `--api-url` | — | (none) | string |
+| `--api-token` | — | (none) | string |
+| `--ecosystems` | — | (none) | CSV → `Vec<String>` |
+| `--download-mode` | — | **`diff`** | string |
+
+### `list`
+
+| Long | Short | Default | Type |
+|---|---|---|---|
+| `--cwd` | — | `.` | path |
+| `--manifest-path` | `-m` | `.socket/manifest.json` | string |
+| `--json` | — | `false` | bool |
+
+### `remove`
+
+Required positional `identifier`. Flags:
+
+| Long | Short | Default | Type |
+|---|---|---|---|
+| `--cwd` | — | `.` | path |
+| `--manifest-path` | `-m` | `.socket/manifest.json` | string |
+| `--skip-rollback` | — | `false` | bool |
+| `--yes` | `-y` | `false` | bool |
+| `--global` | `-g` | `false` | bool |
+| `--global-prefix` | — | (none) | path |
+| `--json` | — | `false` | bool |
+
+### `setup`
+
+| Long | Short | Default | Type |
+|---|---|---|---|
+| `--cwd` | — | `.` | path |
+| `--dry-run` | `-d` | `false` | bool |
+| `--yes` | `-y` | `false` | bool |
+| `--json` | — | `false` | bool |
+
+### `repair`
+
+| Long | Short | Default | Type |
+|---|---|---|---|
+| `--cwd` | — | `.` | path |
+| `--manifest-path` | `-m` | `.socket/manifest.json` | string |
+| `--dry-run` | `-d` | `false` | bool |
+| `--offline` | — | `false` | bool |
+| `--download-only` | — | `false` | bool |
+| `--json` | — | `false` | bool |
+| `--download-mode` | — | **`file`** | string |
+
+**Note:** `repair`'s `--download-mode` default differs from every other command (`file` vs `diff`). This is intentional — repair restores legacy per-file blobs needed to apply any patch.
+
+## CSV value parsing
+
+`--ecosystems` on `apply`, `rollback`, and `scan` uses clap's `value_delimiter = ','`. Input `--ecosystems npm,pypi,cargo` becomes `vec!["npm", "pypi", "cargo"]`. Switching to space-separated or dropping the delimiter is a **breaking** change.
+
+## JSON output shapes
+
+When `--json` is set, commands print a single JSON object to stdout. The schemas below are stable.
+
+### Missing-manifest error (`apply`/`list`/`remove`/`repair`/`rollback`)
+
+```json
+{
+  "status": "error",
+  "error": "Manifest not found",
+  "path": "<absolute path that was looked up>"
+}
+```
+
+### Invalid-manifest error
+
+```json
+{ "status": "error", "error": "Invalid manifest" }
+```
+
+### Generic error
+
+```json
+{ "status": "error", "error": "<message>" }
+```
+
+### `list` success — empty manifest
+
+```json
+{ "status": "success", "patches": [] }
+```
+
+### `list` success — populated
+
+```json
+{
+  "status": "success",
+  "patches": [
+    {
+      "purl": "pkg:npm/foo@1.2.3",
+      "uuid": "…",
+      "exportedAt": "…",
+      "tier": "free|paid",
+      "license": "…",
+      "description": "…",
+      "files": ["…"],
+      "vulnerabilities": [
+        { "id": "…", "cves": ["…"], "summary": "…", "severity": "…", "description": "…" }
+      ]
+    }
+  ]
+}
+```
+
+### `setup` — no package.json files found
+
+```json
+{
+  "status": "no_files",
+  "updated": 0,
+  "alreadyConfigured": 0,
+  "errors": 0,
+  "files": []
+}
+```
+
+### `get` — multiple-patch selection required (JSON mode)
+
+```json
+{
+  "status": "selection_required",
+  "error": "Multiple patches available for <purl>. Specify --id <UUID> to select one.",
+  "purl": "<purl>",
+  "options": [
+    { "uuid": "…", "tier": "…", "published_at": "…", "description": "…", "vulnerabilities": [ … ] }
+  ]
+}
+```
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `1` | Error (missing/invalid manifest, fetch failed, apply failed, selection cancelled in non-JSON mode, etc.) |
+
+`list` returns **`0`** for an empty manifest and **`1`** for a missing manifest — these are distinct and load-bearing.
+
+## Semver policy
+
+Versioning lives in **`Cargo.toml`** at the workspace root (`version = "..."`) and is propagated to npm, pypi, and cargo wrappers by **`scripts/version-sync.sh <new-version>`**.
+
+| Change | Bump |
+|---|---|
+| Rename or remove a subcommand | **MAJOR** |
+| Rename or remove a visible alias (`download`, `gc`) | **MAJOR** |
+| Rename or remove a hidden alias (`--no-apply`) | **MAJOR** |
+| Rename, remove, or change short form of a flag (`-d`, `-m`, etc.) | **MAJOR** |
+| Change a default value (`--download-mode`, `--batch-size`, `--manifest-path`, …) | **MAJOR** |
+| Change an exit code's meaning or add a new non-zero code with different semantics | **MAJOR** |
+| Rename a JSON output key or change a `status` string | **MAJOR** |
+| Remove a JSON output key | **MAJOR** |
+| Drop the bare-UUID fallback | **MAJOR** |
+| Add a *required* new flag | **MAJOR** |
+| Add a new subcommand | **MINOR** |
+| Add a new optional flag | **MINOR** |
+| Add a new optional JSON output key (additive) | **MINOR** |
+| Add a new visible alias to an existing subcommand | **MINOR** |
+| Fix a bug without changing any of the above | **PATCH** |
+
+After bumping `Cargo.toml`, run:
+
+```bash
+scripts/version-sync.sh <new-version>
+```
+
+This syncs the workspace package version into:
+
+- `npm/socket-patch/package.json` (and its `optionalDependencies`)
+- every per-platform `npm/socket-patch-*/package.json`
+- `pypi/socket-patch/pyproject.toml`
+
+## How the contract is enforced
+
+Every item in this document is locked in by at least one of:
+
+- **clap parser snapshots** in `crates/socket-patch-cli/tests/cli_parse_*.rs` — assert flag names, short forms, defaults, aliases, and CSV delimiters by calling `socket_patch_cli::Cli::try_parse_from(...)`.
+- **Helper unit tests** in `crates/socket-patch-cli/src/**` (`#[cfg(test)] mod tests` blocks) — cover `looks_like_uuid`, `parse_with_uuid_fallback`, `detect_identifier_type`, `select_patches`, `find_patches_to_rollback`, `partition_purls`, `verify_status_str`, `format_severity`, `color`, and the JSON serializers.
+- **Async `run()` integration tests** in `tests/cli_parse_list.rs`, `tests/cli_parse_remove.rs`, `tests/cli_parse_setup.rs` — exercise the no-network error paths and assert JSON shape via `serde_json::from_str::<Value>` + per-key assertions.
+
+If you add a new flag/subcommand/JSON key, add a test here that locks the new surface in the same PR.

crates/socket-patch-cli/Cargo.toml

@@ -7,6 +7,10 @@ license.workspace = true
 repository.workspace = true
 readme = "README.md"
 
+[lib]
+name = "socket_patch_cli"
+path = "src/lib.rs"
+
 [[bin]]
 name = "socket-patch"
 path = "src/main.rs"