Simplify v5 help and docs and hide API tokens in help

Author: mikolalysenko

Cargo.toml

@@ -76,22 +76,14 @@ strip = true
 lto = true
 opt-level = "s"
 
-# CI-only profile for the test-release job. Inherits the shipped profile's
-# semantics (opt-level = "s", debug-assertions off, overflow-checks off) —
-# which is what test-release exists to validate — but drops
-# the full-LTO link: ~23m of that job's ~29m was LTO-relinking 159 test
-# binaries, and LTO relinks are structurally uncacheable. release.yml still
-# builds the real full-LTO [profile.release] for every shipped target.
+# Test release semantics without the cost of full-LTO links for every test binary.
+# Shipped binaries still use [profile.release].
 [profile.ci-release]
 inherits = "release"
 lto = false
 strip = "none" # unstripped test binaries => usable backtraces on failure
 
-# The benchmark gate's build (crates/socket-patch-bench, .github/workflows/
-# bench.yml): the shipped profile's codegen (opt-level = "s", no debug
-# assertions) so timings track what users run, with thin instead of full
-# LTO so CI can afford to build both sides of a comparison. Unstripped, so
-# a profiler can symbolize it.
+# Benchmark with release codegen, faster thin-LTO links, and profiler symbols.
 [profile.perf]
 inherits = "release"
 lto = "thin"
@@ -103,19 +95,12 @@ strip = "none"
 inherits = "release"
 lto = "thin"
 
-# Test-execution speed: `cargo test` builds dependencies with the dev
-# profile; at opt-level 0 the hash/compression hot loops are 10-100x
-# slower (the self_update fixtures gzip and sha256-hash the multi-MB debug
-# CLI binary per test: ~403s debug vs ~2s release). Workspace members are NOT matched by "*" — they stay
-# opt-level 0, so incremental compile speed, debugging, and llvm-cov line
-# fidelity (reports filter to workspace crates) are unchanged. Dependencies
-# keep debug-assertions and overflow-checks ON — only codegen opt changes.
+# Optimize dependencies for test speed. Workspace crates stay unoptimized;
+# debug assertions and overflow checks remain enabled everywhere.
 [profile.dev.package."*"]
 opt-level = 1
 
-# The measured hot path gets full optimization: archive building
-# (flate2/zip over multi-MB payloads), SHA hashing in fixtures and in the
-# CLI's own verify paths.
+# Fully optimize hashing and compression, the test fixtures' hot paths.
 [profile.dev.package.sha2]
 opt-level = 3
 [profile.dev.package.sha1]
@@ -141,13 +126,7 @@ opt-level = 3
 [profile.dev.package.zip]
 opt-level = 3
 
-# macOS debug builds use unpacked split-debuginfo: every linked binary —
-# including each of the ~90 e2e test executables — pins its per-codegen-unit
-# .o files in target/debug/deps, and cargo never garbage-collects the
-# generations superseded by lockfile/toolchain bumps (this grew target/ to
-# 99 GB). Line tables keep panic backtraces readable while dropping the bulk
-# of the retained DWARF; for a full-fidelity debugger session, override with
-# CARGO_PROFILE_DEV_DEBUG=full. Applies to test/bench profiles via
-# inheritance.
+# Keep backtraces readable without retaining full DWARF for every test binary.
+# Use CARGO_PROFILE_DEV_DEBUG=full for debugger sessions.
 [profile.dev]
 debug = "line-tables-only"

README.md

@@ -1,20 +1,9 @@
 # Socket Patch
 
-Apply security fixes to the dependency versions your project already uses.
-Socket provides patches for specific package versions so you can address known
-vulnerabilities without waiting for an upstream release or upgrading the dependency.
-
-The default workflow is **scan → install → vex**:
-
-- `socket-patch scan` finds available patches from project dependency files and
-  updates them to use Socket-hosted patched packages.
-- Your package manager installs those packages using the updated references and
-  integrity pins. Commit the files that `scan` reports.
-- `socket-patch vex` produces an OpenVEX document describing the vulnerabilities
-  addressed by those patches.
-
-Use `socket-patch vendor` to put the selected patched packages in your repository
-when installs must work without Socket's patch server.
+Apply security fixes to the dependency versions your project already uses,
+without waiting for an upstream release or upgrading the dependency.
+Socket Patch updates dependency files to use patched packages, which you install
+with your normal package manager.
 
 > This branch documents the v5 prerelease. Installation commands below select the
 > latest published release, which may have different behavior. To try this branch,
@@ -29,11 +18,9 @@ Install a standalone binary on macOS or Linux:
 curl -fsSL https://install.socket.dev/patch | sh
 ```
 
-The installer verifies the download against the release's `SHA256SUMS` and installs
-in `/usr/local/bin` or `~/.local/bin`. To choose a directory or release, pass
-`SOCKET_PATCH_INSTALL_DIR` or `SOCKET_PATCH_VERSION` to `sh` after the pipe.
-See the [installer source](scripts/install.sh) and
-[mirror configuration](docs/installer-hosting.md).
+The installer verifies release checksums and installs in `/usr/local/bin` or
+`~/.local/bin`. See the [installer options](scripts/install.sh) for a custom
+directory or version, and [mirror setup](docs/installer-hosting.md).
 
 On Windows, extract a `socket-patch-*-pc-windows-msvc.zip` archive from
 [GitHub Releases](https://github.com/SocketDev/socket-patch/releases) into a directory
@@ -43,13 +30,12 @@ on your `PATH`, or install through npm:
 npm install -g @socketsecurity/socket-patch
 ```
 
-Cargo users can build and install the published CLI with
-`cargo install socket-patch-cli`. All distributions support the same ecosystems;
-you do not need Node.js or Rust to use the standalone binary.
+Cargo users can run `cargo install socket-patch-cli`. The standalone binary
+requires neither Node.js nor Rust. All installation methods support the same
+ecosystems; see the [support matrix](docs/ecosystems.md) for platform details.
 
 For standalone installs, run `socket-patch --update` to update. For npm or Cargo
-installs, use that package manager's update command. The
-[platform matrix](docs/ecosystems.md#supported-platforms) lists release targets.
+installs, use that package manager's update command.
 
 ## Quick start
 
@@ -58,38 +44,25 @@ before dependencies are installed:
 
 ```sh
 socket-patch scan --dry-run       # preview available patches and edits
-socket-patch scan                 # apply hosted references; never prompts
+socket-patch scan                 # update dependency files; never prompts
 ```
 
-Agent mode needs installed packages. Some ecosystems need build-tool resolution
-records first, such as sbt and scala-cli; see the
-[ecosystem notes](docs/ecosystems.md).
-
-Without an API token, the CLI uses Socket's public proxy for free patches.
-To use your organization's patch tier, set `SOCKET_API_TOKEN`, or sign in with the
-separate Socket CLI using `socket login`. See [configuration](docs/configuration.md).
-
-A scan with no available patches means the catalog has no applicable patch for
-this run. It is **not** a finding that the project has no vulnerabilities.
-
-Review and commit the files the scan changed. Hosted mode keeps no patch ledger;
-its state is in the project's lockfiles, manifests, and package-manager configuration.
-For example, an npm project may change both `package-lock.json` and `.npmrc`:
+Review and commit the dependency and configuration files the scan reports. Then
+install the patched packages and generate OpenVEX for your vulnerability scanner:
 
 ```sh
-git diff
-git add package-lock.json .npmrc
-git commit -m "Apply Socket security patches"
-npm ci
+npm ci                           # use your project's normal install command
 socket-patch vex --output socket.vex.json
 socket-patch list
 ```
 
-Use your project's normal install command in place of `npm ci`. Some package
-managers reuse installed or cached upstream packages; follow any reinstall warning
-from the CLI and the [ecosystem notes](docs/ecosystems.md). Generate VEX after
-installing to verify the copies your build consumes, then pass the document to your
-VEX-aware vulnerability scanner.
+Follow any reinstall warning from the CLI: some package managers reuse cached
+upstream packages. Agent mode needs installed packages; sbt and scala-cli need
+resolution records first. See the [ecosystem notes](docs/ecosystems.md).
+
+Free patches need no token. For organization patches, set `SOCKET_API_TOKEN` or
+use the separate Socket CLI's `socket login`. See [configuration](docs/configuration.md).
+A scan with no available patches does **not** mean the project has no vulnerabilities.
 
 ## Patch modes
 
@@ -105,39 +78,26 @@ Hosted and vendored installs do not need an install hook or the Socket Patch CLI
 Once a project holds vendored or agent-mode patches, a bare `scan` or `get` keeps
 that mode; pass `--mode` to switch.
 
-The CLI supports npm, PyPI, Cargo, Go, RubyGems, Maven (including sbt, Mill and
-scala-cli builds), Composer, NuGet, and Deno.
-Mode and package-manager support vary: Deno uses agent mode, for example. Check the
-[ecosystem support matrix](docs/ecosystems.md) before choosing a mode.
-
-Vendored Maven reactors and Gradle 6.8+ builds are supported. See
-[JVM vendoring](docs/design/maven-vendoring.md) for supported project shapes,
-cache behavior, and offline checks. sbt 0.13.18+ builds are wired through one
-generated `socket-patch.sbt` (hosted) or `socket-patch-vendor.sbt` (vendored);
-see [Scala build tools](docs/ecosystems.md#scala-build-tools-sbt-mill-scala-cli).
+Supported ecosystems include npm, PyPI, Cargo, Go, RubyGems, Maven, Composer,
+NuGet, and Deno. Check the [support matrix](docs/ecosystems.md) for available
+modes and package-manager limitations.
 
 ## Common commands
 
 ```sh
-socket-patch scan --package lodash          # limit selection to a package
-socket-patch scan --max-new-patches 5        # introduce at most five new patches
-socket-patch scan 'apps/*'                  # scan project directories in a monorepo
-socket-patch get CVE-2024-12345              # target an advisory; hosted by default
+socket-patch scan --package lodash         # limit selection to a package
+socket-patch scan --max-new-patches 5       # introduce at most five new patches
+socket-patch scan 'apps/*'                  # scan projects in a monorepo
+socket-patch get pkg:npm/lodash@4.17.20      # target one package version
 socket-patch vendor                        # eject an existing hosted patch set
 socket-patch repair                        # restore agent or vendored patch artifacts
+socket-patch rollback lodash               # restore one package to upstream
 socket-patch rollback                      # restore upstream dependencies
 ```
 
-`get` also accepts a GHSA, patch UUID, PURL, or exact package name (every installed
-version of that name is searched; near names are only suggested). `scan` selects from
-patches your account can download, preferring the highest severity, then the most
-advisories fixed, then the newest publication date. Existing patches are upgraded
-only by a better-ranked patch.
-
-Hosted rollback resolves upstream metadata and generally needs network access.
-Where restoration is unsupported, including hosted binary `bun.lockb`, the CLI
-refuses the change and gives a version-control recovery hint. See
-[usage and recovery](docs/usage.md).
+`get` also accepts a CVE, GHSA, patch UUID, or exact package name. Hosted rollback
+generally needs network access; some formats require restoring files from version
+control. See [usage and recovery](docs/usage.md).
 
 Use `socket-patch <command> --help` for options and
 [`socket.yml`](docs/configuration.md#repository-patch-policy) for a shared rollout policy.

crates/socket-patch-cli/CLI_CONTRACT.md

@@ -64,11 +64,11 @@ uppercase letter settles on its exact-case package among case-distinct ones
 
 `get <name>` searches every installed version of the matched name (within
 `--ecosystems`) and prints `Matched: …` on stderr. With no exact match in a
-nonempty inventory it is `no_match` (exit 0, no patch-search API call) and, in
+nonempty inventory it is `noMatch` (exit 0, no patch-search API call) and, in
 human mode, suggests up to five near names (`Did you mean: …?`) without acting on
-them. An empty inventory is `no_packages` (exit 0). `--ecosystems` also filters
+them. An empty inventory is `noPackages` (exit 0). `--ecosystems` also filters
 advisory/purl search results and UUID selection before any patch is written; a
-UUID outside the selected ecosystems is `not_found` (exit 0).
+UUID outside the selected ecosystems is `notFound` (exit 0).
 
 `remove` / `rollback` accept the same names and versionless purls against manifest
 records, vendor-ledger entries and hosted pins; CVE/GHSA ids match no record
@@ -1248,7 +1248,11 @@ The v3.0 legacy names `SOCKET_PATCH_PROXY_URL`, `SOCKET_PATCH_DEBUG` and `SOCKET
 
 ## JSON output shapes
 
-Every `--json` invocation emits a single JSON object that follows the **unified envelope** below. The envelope was introduced in v3.0; older per-command shapes are deprecated. See `src/json_envelope.rs` for the source of truth; its unit tests pin the serialized names, and each command's e2e tests assert the envelope it emits. The `tests/cli_parse_*.rs` files pin the parsed clap arguments, not this shape (a few, such as `cli_parse_list.rs`, also spot-check `list`'s envelope).
+Every command's `--json` output is a single object using the envelope below.
+v5 removes the older per-command shapes. Argument-parsing errors and invalid
+`--cwd`, `--global-prefix`, or `--manifest-path` values still exit 2 with stderr
+output and no JSON. `src/json_envelope.rs` defines the serialized names; each
+command's integration tests check its output.
 
 **One error shape (v5.0, MAJOR).** On every command, every `--json` failure is a full envelope (`command`, `status: "error"`, `dryRun`, `events`, `summary`) whose top-level `error` is a `{code, message}` object — the envelope's `EnvelopeError`. `code` is a stable snake_case tag (see [Top-level `EnvelopeError` codes](#top-level-envelopeerror-codes)); `message` is for humans. No command prints a top-level `errorCode` any more (it moved into `error.code`). Per-event keys are unchanged: `events[*].error` / `events[*].errorCode` stay strings.
 

crates/socket-patch-cli/src/args.rs

@@ -1,15 +1,6 @@
-//! Shared CLI arguments flattened into every subcommand.
-//!
-//! `GlobalArgs` defines the flags that apply uniformly across every
-//! `socket-patch` subcommand. Each subcommand `#[command(flatten)]`s this
-//! struct into its own `Args` struct so the surface stays consistent.
-//!
-//! Subcommands that don't actually use a given global flag still accept it
-//! silently (no-op). See `CLI_CONTRACT.md` for the full contract.
-//!
-//! Precedence for every flag: CLI arg > env var > default.
-//!
-//! All env-var names use the `SOCKET_*` prefix.
+//! Shared CLI flags and their `SOCKET_*` environment bindings.
+//! Commands accept unused flags as no-ops. See `CLI_CONTRACT.md` for their scope
+//! and configuration precedence.
 
 use std::path::{Path, PathBuf};
 
@@ -23,14 +14,7 @@ use socket_patch_core::crawlers::Ecosystem;
 use socket_patch_core::telemetry::TelemetryAuth;
 use socket_patch_core::vendor::{VendorServiceConfig, VendorSource};
 
-/// clap value-parser for each `--ecosystems` / `SOCKET_ECOSYSTEMS` token.
-///
-/// Rejects any name that is not a supported ecosystem, so typos fail
-/// loudly instead of silently matching nothing.
-///
-/// Without this, an unsupported name parsed fine and was then silently
-/// dropped by `partition_purls`/`crawl_ecosystems`, so the user got a
-/// "0 patches" result with no hint that the ecosystem name was the cause.
+/// Reject unknown ecosystems before they can produce a misleading empty scan.
 fn parse_supported_ecosystem(s: &str) -> Result<String, String> {
     if Ecosystem::all().iter().any(|e| e.cli_name() == s) {
         Ok(s.to_string())
@@ -55,27 +39,12 @@ fn unsupported_ecosystem_message(token: &str, supported: &str) -> String {
     }
 }
 
-/// clap value-parser for `--vendor-source` / `SOCKET_VENDOR_SOURCE`.
-///
-/// Validates the token against [`VendorSource`] (`service` or its `auto` alias,
-/// case-insensitive; `build` is rejected) at parse time so a typo fails immediately
-/// rather than at vendor time, and normalizes it to the canonical lowercase
-/// tag. Mirrors [`parse_supported_ecosystem`]'s fail-loud-on-typo posture.
+/// Validate the service source and normalize its compatibility alias at parse time.
 fn parse_vendor_source(s: &str) -> Result<String, String> {
     VendorSource::parse(s).map(|v| v.as_tag().to_string())
 }
 
-/// clap value-parser for boolean flags backed by an env var.
-///
-/// Identical to clap's stock `BoolishValueParser` (case-insensitive
-/// `true/false`, `yes/no`, `on/off`, `1/0`) **except** that an empty string is
-/// treated as `false` rather than rejected.
-///
-/// Without this, an exported-but-empty env var — e.g. `SOCKET_OFFLINE=` or
-/// `SOCKET_JSON=`, which shells and CI routinely set to mean "unset" — made
-/// clap abort the whole command with `invalid value '' for '--offline': value
-/// was not a boolean`. Every bool flag here reads such an env var, so a single
-/// stray empty var crashed every subcommand before it could do any work.
+/// Parse boolish environment values, treating an exported empty value as false.
 pub(crate) fn parse_bool_flag(s: &str) -> Result<bool, String> {
     match s.trim().to_ascii_lowercase().as_str() {
         "" | "n" | "no" | "f" | "false" | "off" | "0" => Ok(false),
@@ -128,7 +97,12 @@ pub struct GlobalArgs {
     pub api_url: Option<String>,
 
     /// Socket API token. Absence selects the public patch proxy.
-    #[arg(help_heading = GLOBAL_OPTIONS, long = "api-token", env = "SOCKET_API_TOKEN")]
+    #[arg(
+        help_heading = GLOBAL_OPTIONS,
+        long = "api-token",
+        env = "SOCKET_API_TOKEN",
+        hide_env_values = true
+    )]
     pub api_token: Option<String>,
 
     /// Organization slug. Auto-resolved when omitted and a token is set.
@@ -143,8 +117,7 @@ pub struct GlobalArgs {
     #[arg(help_heading = GLOBAL_OPTIONS, long = "proxy-url", env = "SOCKET_PROXY_URL")]
     pub proxy_url: Option<String>,
 
-    /// Restrict to these ecosystems (comma-separated). Names that are not
-    /// supported ecosystems are rejected.
+    /// Restrict to these ecosystems (comma-separated).
     #[arg(
         help_heading = GLOBAL_OPTIONS,
         long = "ecosystems",
@@ -197,8 +170,7 @@ pub struct GlobalArgs {
     )]
     pub patch_server_url: Option<String>,
 
-    /// Strict airgap: never contact the network. Operations that need remote
-    /// data fail loudly when this is set.
+    /// Disable network access; fail if remote data is needed.
     #[arg(
         help_heading = GLOBAL_OPTIONS,
         long,

crates/socket-patch-cli/src/commands/rollback.rs

@@ -41,8 +41,9 @@ use crate::ui::{plural, StatusLine};
 
 #[derive(Args)]
 pub struct RollbackArgs {
-    /// What to roll back: a package PURL, a patch UUID, or a path glob
-    /// (e.g. `packages/foo`, `apps/**`) selecting the patches whose
+    /// Package names, PURLs, UUIDs, or paths; omit to restore all patches.
+    ///
+    /// Paths and globs (e.g. `packages/foo`, `apps/**`) select patches whose
     /// installed copies live under matching paths. Multiple targets union.
     /// Omit to roll back ALL patch state — in-place patches, vendored
     /// patches, and hosted lockfile redirects.
@@ -60,12 +61,13 @@ pub struct RollbackArgs {
     #[command(flatten)]
     pub common: GlobalArgs,
 
-    /// Restore the system (files and lockfiles) but PRESERVE the local
+    /// Keep local patch records and artifacts for later reuse.
+    ///
+    /// Restore the system (files and lockfiles) but preserve the local
     /// patch state for a later re-apply: manifest entries are kept,
     /// vendored artifacts and their ledger entries are kept (only the
     /// lockfile wiring is reverted), and no blob/archive cleanup runs.
-    /// Hosted redirects have no preservable local state — their ledger
-    /// records describe live wiring and are dropped with it either way.
+    /// Hosted references have no local state to preserve.
     #[arg(
         long = "preserve-state",
         env = "SOCKET_PRESERVE_STATE",