feat(scan): add --apply + structured updates for auto-update bot workflows

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

Author: mikolalysenko

crates/socket-patch-cli/CLI_CONTRACT.md

@@ -83,6 +83,9 @@ The hidden alias `--no-apply` on `--save-only` is **part of the contract** — i
 | `--api-token` | — | (none) | string |
 | `--ecosystems` | — | (none) | CSV → `Vec<String>` |
 | `--download-mode` | — | **`diff`** | string |
+| `--apply` | — | `false` | bool |
+
+`--apply` opts JSON callers into the full discover → select → apply pipeline. Without it, `scan --json` stays read-only (discovery + `updates` array only). No effect outside `--json` mode — the non-JSON path always prompts the user interactively. Designed for unattended workflows (cron jobs, bots that open PRs).
 
 ### `list`
 
@@ -212,6 +215,71 @@ When `--json` is set, commands print a single JSON object to stdout. The schemas
 }
 ```
 
+### `scan` — discovery (read-only, default `--json` mode)
+
+```json
+{
+  "status": "success",
+  "scannedPackages": 42,
+  "packagesWithPatches": 3,
+  "totalPatches": 5,
+  "freePatches": 4,
+  "paidPatches": 1,
+  "canAccessPaidPatches": false,
+  "packages": [
+    {
+      "purl": "pkg:npm/minimist@1.2.2",
+      "patches": [
+        { "uuid": "…", "purl": "pkg:npm/minimist@1.2.2", "tier": "free", "cveIds": ["CVE-…"], "ghsaIds": [], "severity": "high", "title": "…" }
+      ]
+    }
+  ],
+  "updates": [
+    { "purl": "pkg:npm/foo@1.0", "oldUuid": "<previous>", "newUuid": "<newest>" }
+  ]
+}
+```
+
+The `updates` array lists PURLs where the newest available patch UUID differs from the one currently recorded in `.socket/manifest.json`. Bots use this to drive "what would change" summaries without mutating anything.
+
+### `scan` — `--apply` mode
+
+When invoked as `scan --json --apply`, the discovery object above is augmented with a top-level `apply` sub-object reporting per-patch outcomes from the download + manifest write:
+
+```json
+{
+  "status": "success",                  // or "partial_failure"
+  "scannedPackages": 42,
+  // … all discovery fields above …
+  "updates": [ … ],
+  "apply": {
+    "found": 3,
+    "downloaded": 2,
+    "skipped": 1,
+    "failed": 0,
+    "applied": 2,
+    "updated": 1,
+    "patches": [
+      { "purl": "pkg:npm/foo@1.0", "uuid": "<new>", "action": "added" },
+      { "purl": "pkg:npm/bar@2.0", "uuid": "<new>", "action": "updated", "oldUuid": "<previous>" },
+      { "purl": "pkg:npm/baz@3.0", "uuid": "<existing>", "action": "skipped" },
+      { "purl": "pkg:npm/qux@4.0", "uuid": "<attempted>", "action": "failed", "error": "…" }
+    ]
+  }
+}
+```
+
+Per-patch `action` vocabulary is stable:
+
+| `action` | Meaning |
+|---|---|
+| `"added"` | PURL was not in the manifest before. |
+| `"updated"` | PURL was in the manifest with a different UUID. `oldUuid` is included. |
+| `"skipped"` | PURL was in the manifest with the same UUID. No work was done. |
+| `"failed"` | The patch could not be downloaded or saved. `error` is included. |
+
+Exit code follows the apply outcome: `0` if every selected patch was added, updated, or skipped; `1` if any `failed` record is present (and `status` becomes `"partial_failure"`).
+
 ## Exit codes
 
 | Code | Meaning |
@@ -235,11 +303,13 @@ Versioning lives in **`Cargo.toml`** at the workspace root (`version = "..."`) a
 | 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** |
+| Rename or remove a per-patch `action` value (`added`/`updated`/`skipped`/`failed`) | **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 value to a per-patch `action` enum (additive) | **MINOR** |
 | Add a new visible alias to an existing subcommand | **MINOR** |
 | Fix a bug without changing any of the above | **PATCH** |
 

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

@@ -16,6 +16,36 @@ use std::path::PathBuf;
 use crate::ecosystem_dispatch::crawl_all_ecosystems;
 use crate::output::{confirm, select_one, SelectError};
 
+/// Per-patch outcome reported in the JSON output of `download_and_apply_patches`.
+/// `Updated` carries the previous UUID so a bot can diff a manifest update against
+/// what was there before — see CLI_CONTRACT.md for the stable vocabulary.
+#[derive(Debug, PartialEq, Eq, Clone)]
+pub(crate) enum PatchAction {
+    /// Patch did not exist in the manifest at this PURL.
+    Added,
+    /// Patch existed under this PURL with a different UUID; the new UUID
+    /// replaces the old one. `old_uuid` is the UUID being overwritten.
+    Updated { old_uuid: String },
+    /// Patch already exists with the same UUID; download is a no-op.
+    Skipped,
+}
+
+/// Classify what `download_and_apply_patches` will do to a given PURL based on
+/// the manifest state *before* any insert. Pure / no I/O so it's unit-testable.
+pub(crate) fn decide_patch_action(
+    manifest: &PatchManifest,
+    purl: &str,
+    new_uuid: &str,
+) -> PatchAction {
+    match manifest.patches.get(purl) {
+        Some(existing) if existing.uuid == new_uuid => PatchAction::Skipped,
+        Some(existing) => PatchAction::Updated {
+            old_uuid: existing.uuid.clone(),
+        },
+        None => PatchAction::Added,
+    }
+}
+
 #[derive(Args)]
 pub struct GetArgs {
     /// Patch identifier (UUID, CVE ID, GHSA ID, PURL, or package name)
@@ -335,12 +365,11 @@ pub async fn download_and_apply_patches(
             .await
         {
             Ok(Some(patch)) => {
-                // Check if already in manifest with same UUID
-                if manifest
-                    .patches
-                    .get(&patch.purl)
-                    .is_some_and(|p| p.uuid == patch.uuid)
-                {
+                // Classify against the manifest state BEFORE we touch it.
+                // `Skipped` early-returns; `Updated` is preserved so the
+                // per-patch JSON record below can include `oldUuid`.
+                let action = decide_patch_action(&manifest, &patch.purl, &patch.uuid);
+                if let PatchAction::Skipped = action {
                     if !params.json && !params.silent {
                         eprintln!("  [skip] {} (already in manifest)", patch.purl);
                     }
@@ -458,14 +487,30 @@ pub async fn download_and_apply_patches(
                     },
                 );
 
-                if !params.json && !params.silent {
-                    eprintln!("  [add] {}", patch.purl);
-                }
-                downloaded_patches.push(serde_json::json!({
-                    "purl": patch.purl,
-                    "uuid": patch.uuid,
-                    "action": "added",
-                }));
+                let action_record = match &action {
+                    PatchAction::Updated { old_uuid } => {
+                        if !params.json && !params.silent {
+                            eprintln!("  [update] {}", patch.purl);
+                        }
+                        serde_json::json!({
+                            "purl": patch.purl,
+                            "uuid": patch.uuid,
+                            "action": "updated",
+                            "oldUuid": old_uuid,
+                        })
+                    }
+                    _ => {
+                        if !params.json && !params.silent {
+                            eprintln!("  [add] {}", patch.purl);
+                        }
+                        serde_json::json!({
+                            "purl": patch.purl,
+                            "uuid": patch.uuid,
+                            "action": "added",
+                        })
+                    }
+                };
+                downloaded_patches.push(action_record);
                 patches_added += 1;
             }
             Ok(None) => {
@@ -1451,4 +1496,66 @@ mod tests {
         assert_eq!(out[0].uuid, "free");
         assert_eq!(out[0].tier, "free");
     }
+
+    // --- decide_patch_action ---------------------------------------------
+    // Locks in the per-patch action vocabulary surfaced by
+    // download_and_apply_patches in JSON mode. See CLI_CONTRACT.md.
+
+    fn manifest_with_entry(purl: &str, uuid: &str) -> PatchManifest {
+        let mut m = PatchManifest::new();
+        m.patches.insert(
+            purl.to_string(),
+            PatchRecord {
+                uuid: uuid.to_string(),
+                exported_at: String::new(),
+                files: HashMap::new(),
+                vulnerabilities: HashMap::new(),
+                description: String::new(),
+                license: String::new(),
+                tier: "free".to_string(),
+            },
+        );
+        m
+    }
+
+    #[test]
+    fn decide_patch_action_added_when_purl_absent() {
+        let manifest = PatchManifest::new();
+        assert_eq!(
+            decide_patch_action(&manifest, "pkg:npm/foo@1.0", "uuid-a"),
+            PatchAction::Added,
+        );
+    }
+
+    #[test]
+    fn decide_patch_action_skipped_when_same_uuid() {
+        let manifest = manifest_with_entry("pkg:npm/foo@1.0", "uuid-a");
+        assert_eq!(
+            decide_patch_action(&manifest, "pkg:npm/foo@1.0", "uuid-a"),
+            PatchAction::Skipped,
+        );
+    }
+
+    #[test]
+    fn decide_patch_action_updated_when_different_uuid() {
+        let manifest = manifest_with_entry("pkg:npm/foo@1.0", "uuid-a");
+        assert_eq!(
+            decide_patch_action(&manifest, "pkg:npm/foo@1.0", "uuid-b"),
+            PatchAction::Updated {
+                old_uuid: "uuid-a".to_string()
+            },
+        );
+    }
+
+    #[test]
+    fn decide_patch_action_added_for_different_purl_even_with_overlapping_manifest() {
+        // Ensure update detection keys on PURL, not UUID. A new PURL with a
+        // UUID that happens to match an existing entry under a different
+        // PURL must still be `Added`.
+        let manifest = manifest_with_entry("pkg:npm/foo@1.0", "uuid-a");
+        assert_eq!(
+            decide_patch_action(&manifest, "pkg:npm/bar@2.0", "uuid-a"),
+            PatchAction::Added,
+        );
+    }
 }