feat(cargo): land Cargo trait, LiveCargo, MockCargo, install-list parser (#11)

Plan §6.7 — second M1 Week 2 adapter probe path. Inventory only at M1;
install/uninstall arrive in M2 with the rest of the apply-engine
adapters per Plan §7.3.

Public surface:

- pub trait Cargo { fn inventory(&self) -> Result<CargoInventory, CargoError>; }
- pub struct LiveCargo with new() / with_binary() / binary().
- pub struct MockCargo (test-mocks feature) with new() / with_inventory().
- pub fn parse_install_list(&str) -> CargoInventory — exposed because
  parsing is purely textual and useful from tests / probes.
- pub enum CargoError — NotInPath (hint: paru -S rustup), Io,
  InvocationFailed { code, stderr }, NotUtf8.

Parser handles:
- standard `crate-name vX.Y.Z:` header
- registry source spec `(registry+...)` after the version
- git source spec `(https://...#sha)` after the version
- version without `v` prefix (defensive against future cargo releases)
- indented binary listings (skipped — Pearlite tracks crates, not bins)

Tests (10 passing):
- inventory: parse_known_output, empty_output_yields_empty_inventory,
  parses_registry_source_spec, parses_git_source_spec, ignores_binary_lines,
  version_without_v_prefix_still_parses.
- live: cargo_not_in_path_error_class,
  live_cargo_inventory_succeeds_in_a_rust_environment.
- mock: empty_mock_yields_empty_inventory, with_inventory_round_trips.

Cargo dep on pearlite-schema pinned to "0.1" per the cargo-deny
wildcard rule.

Verification:
- cargo test -p pearlite-cargo  (10 passed; 0 failed)
- cargo clippy --workspace --all-targets -- -D warnings  (zero warnings)
- cargo fmt --all --check
- scripts/ci/check-spdx.sh
- pearlite-audit check .  (1 check, 0 violations)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: UnbreakableMJ

crates/pearlite-cargo/Cargo.toml

@@ -11,4 +11,9 @@ repository.workspace = true
 [lints]
 workspace = true
 
+[features]
+test-mocks = []
+
 [dependencies]
+pearlite-schema = { path = "../pearlite-schema", version = "0.1" }
+thiserror = { workspace = true }

crates/pearlite-cargo/src/errors.rs

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Mohamed Hammad
+
+//! Errors emitted by `pearlite-cargo`.
+
+use thiserror::Error;
+
+/// Errors emitted while invoking the `cargo` binary or parsing its
+/// output.
+#[derive(Debug, Error)]
+pub enum CargoError {
+    /// The configured `cargo` binary could not be spawned. Usually a
+    /// Class 1 preflight failure at the engine level — the user does
+    /// not have `rustup` installed.
+    #[error("cargo binary not found: {hint}")]
+    NotInPath {
+        /// Hint string with a runnable command (`paru -S rustup`).
+        hint: &'static str,
+    },
+    /// `std::io` error during spawn or stdout capture.
+    #[error("I/O error invoking cargo: {0}")]
+    Io(#[from] std::io::Error),
+    /// `cargo install --list` exited non-zero.
+    #[error("cargo exited with code {code}:\n{stderr}")]
+    InvocationFailed {
+        /// Process exit code.
+        code: i32,
+        /// Captured stderr verbatim.
+        stderr: String,
+    },
+    /// `cargo` stdout was not valid UTF-8.
+    #[error("cargo stdout was not valid UTF-8: {0}")]
+    NotUtf8(#[from] std::string::FromUtf8Error),
+}

crates/pearlite-cargo/src/inventory.rs

@@ -0,0 +1,142 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Mohamed Hammad
+
+//! `cargo install --list` output parsing.
+
+use pearlite_schema::CargoInventory;
+use std::collections::BTreeMap;
+
+/// Parse the stdout of `cargo install --list` into a [`CargoInventory`].
+///
+/// The format is:
+///
+/// ```text
+/// crate-name vX.Y.Z:
+///     binary-name
+///     other-binary
+/// crate-name2 vA.B.C (registry+https://...):
+///     binary
+/// ```
+///
+/// Crate header lines start in column 0 and end with a colon. Binary
+/// names are indented and ignored — Pearlite tracks installed crates,
+/// not the binaries they ship.
+///
+/// Unknown lines are skipped silently; the parser is forgiving so a
+/// future `cargo` release that adds a banner or a footer doesn't break
+/// the probe.
+#[must_use]
+pub fn parse_install_list(stdout: &str) -> CargoInventory {
+    let mut crates = BTreeMap::new();
+    for line in stdout.lines() {
+        // Indented lines list binary names.
+        if line.starts_with(' ') || line.starts_with('\t') {
+            continue;
+        }
+        let trimmed = line.trim_end().trim_end_matches(':');
+        if trimmed.is_empty() {
+            continue;
+        }
+        let Some((name, rest)) = trimmed.split_once(' ') else {
+            continue;
+        };
+        // `rest` is `vX.Y.Z` optionally followed by ` (source...)`.
+        let Some(version_field) = rest.split_whitespace().next() else {
+            continue;
+        };
+        let version = version_field.strip_prefix('v').unwrap_or(version_field);
+        if name.is_empty() || version.is_empty() {
+            continue;
+        }
+        crates.insert(name.to_owned(), version.to_owned());
+    }
+    CargoInventory { crates }
+}
+
+#[cfg(test)]
+#[allow(
+    clippy::expect_used,
+    clippy::unwrap_used,
+    clippy::panic,
+    reason = "tests may use expect()/unwrap()/panic!() per Plan §4.2 + CLAUDE.md"
+)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_known_output() {
+        let stdout = "\
+cargo-machete v0.7.0:
+    cargo-machete
+nickel-lang-cli v1.10.0 (registry+https://github.com/rust-lang/crates.io-index):
+    nickel
+ripgrep-all v0.10.6:
+    rga
+    rga-fzf
+    rga-preproc
+zellij v0.41.2:
+    zellij
+";
+        let inv = parse_install_list(stdout);
+        assert_eq!(inv.crates.len(), 4);
+        assert_eq!(inv.crates.get("cargo-machete"), Some(&"0.7.0".to_owned()));
+        assert_eq!(
+            inv.crates.get("nickel-lang-cli"),
+            Some(&"1.10.0".to_owned())
+        );
+        assert_eq!(inv.crates.get("ripgrep-all"), Some(&"0.10.6".to_owned()));
+        assert_eq!(inv.crates.get("zellij"), Some(&"0.41.2".to_owned()));
+    }
+
+    #[test]
+    fn empty_output_yields_empty_inventory() {
+        let inv = parse_install_list("");
+        assert!(inv.crates.is_empty());
+    }
+
+    #[test]
+    fn parses_registry_source_spec() {
+        let stdout = "\
+foo v1.2.3 (registry+https://github.com/rust-lang/crates.io-index):
+    foo
+";
+        let inv = parse_install_list(stdout);
+        assert_eq!(inv.crates.get("foo"), Some(&"1.2.3".to_owned()));
+    }
+
+    #[test]
+    fn parses_git_source_spec() {
+        let stdout = "\
+bar v0.1.0 (https://github.com/example/bar#abc123):
+    bar
+";
+        let inv = parse_install_list(stdout);
+        assert_eq!(inv.crates.get("bar"), Some(&"0.1.0".to_owned()));
+    }
+
+    #[test]
+    fn ignores_binary_lines() {
+        let stdout = "\
+crate-a v1.0.0:
+    binary-a
+    other
+crate-b v2.0.0:
+\tbinary-b
+";
+        let inv = parse_install_list(stdout);
+        assert_eq!(inv.crates.len(), 2);
+        assert!(!inv.crates.contains_key("binary-a"));
+        assert!(!inv.crates.contains_key("binary-b"));
+    }
+
+    #[test]
+    fn version_without_v_prefix_still_parses() {
+        // Defensive: future cargo release might drop the 'v' prefix.
+        let stdout = "\
+crate-x 1.0.0:
+    crate-x
+";
+        let inv = parse_install_list(stdout);
+        assert_eq!(inv.crates.get("crate-x"), Some(&"1.0.0".to_owned()));
+    }
+}

crates/pearlite-cargo/src/lib.rs

@@ -2,3 +2,23 @@
 // Copyright (C) 2026 Mohamed Hammad
 
 //! cargo adapter: list installed crates; install and uninstall on apply.
+//!
+//! At M1 only the read side ([`Cargo::inventory`]) is implemented.
+//! Install/uninstall land in M2 with the rest of the apply-engine
+//! adapters per Plan §7.3.
+
+mod errors;
+mod inventory;
+mod live;
+#[cfg(any(test, feature = "test-mocks"))]
+mod mock;
+
+pub use errors::CargoError;
+pub use inventory::parse_install_list;
+pub use live::{Cargo, LiveCargo};
+
+#[cfg(feature = "test-mocks")]
+pub use mock::MockCargo;
+
+#[doc(no_inline)]
+pub use pearlite_schema::CargoInventory;

crates/pearlite-cargo/src/live.rs

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Copyright (C) 2026 Mohamed Hammad
+
+//! [`Cargo`] trait + production [`LiveCargo`] implementation.
+
+use crate::errors::CargoError;
+use crate::inventory::parse_install_list;
+use pearlite_schema::CargoInventory;
+use std::path::{Path, PathBuf};
+use std::process::Command;
+
+/// Trait the rest of the workspace consumes to talk to `cargo`.
+///
+/// At M1 only [`inventory`](Self::inventory) is implemented. Install and
+/// uninstall arrive with M2's apply-engine wiring per Plan §7.3.
+pub trait Cargo: Send + Sync {
+    /// Snapshot the `cargo install --list` output as a
+    /// [`CargoInventory`].
+    ///
+    /// # Errors
+    /// Implementations propagate adapter-specific failures via
+    /// [`CargoError`].
+    fn inventory(&self) -> Result<CargoInventory, CargoError>;
+}
+
+/// Production [`Cargo`] backed by the `cargo` binary.
+///
+/// Uses argv-array subprocess invocation per CLAUDE.md hard invariant
+/// #5: never `sh -c`, never string interpolation into a shell string.
+#[derive(Clone, Debug)]
+pub struct LiveCargo {
+    binary: PathBuf,
+}
+
+impl LiveCargo {
+    /// Construct a [`LiveCargo`] that resolves `cargo` from `PATH`.
+    #[must_use]
+    pub fn new() -> Self {
+        Self {
+            binary: PathBuf::from("cargo"),
+        }
+    }
+
+    /// Construct a [`LiveCargo`] with a caller-supplied binary path.
+    pub fn with_binary(binary: impl Into<PathBuf>) -> Self {
+        Self {
+            binary: binary.into(),
+        }
+    }
+
+    /// Path of the `cargo` binary this adapter invokes.
+    #[must_use]
+    pub fn binary(&self) -> &Path {
+        &self.binary
+    }
+}
+
+impl Default for LiveCargo {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl Cargo for LiveCargo {
+    fn inventory(&self) -> Result<CargoInventory, CargoError> {
+        let output = match Command::new(&self.binary)
+            .args(["install", "--list"])
+            .output()
+        {
+            Ok(o) => o,
+            Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
+                return Err(CargoError::NotInPath {
+                    hint: "paru -S rustup",
+                });
+            }
+            Err(e) => return Err(CargoError::Io(e)),
+        };
+
+        if !output.status.success() {
+            let code = output.status.code().unwrap_or(-1);
+            let stderr = String::from_utf8_lossy(&output.stderr).into_owned();
+            return Err(CargoError::InvocationFailed { code, stderr });
+        }
+
+        let stdout = String::from_utf8(output.stdout)?;
+        Ok(parse_install_list(&stdout))
+    }
+}
+
+#[cfg(test)]
+#[allow(
+    clippy::expect_used,
+    clippy::unwrap_used,
+    clippy::panic,
+    reason = "tests may use expect()/unwrap()/panic!() per Plan §4.2 + CLAUDE.md"
+)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn cargo_not_in_path_error_class() {
+        let live = LiveCargo::with_binary("/nonexistent/path/cargo-binary-12345");
+        let err = live.inventory().expect_err("must fail");
+        assert!(matches!(err, CargoError::NotInPath { .. }), "got {err:?}");
+    }
+
+    /// Plan §6.7 acceptance: `cargo install --list` parses correctly. CI
+    /// has cargo installed via dtolnay/rust-toolchain; locally cargo is
+    /// always present (we're inside a Rust workspace). The test asserts
+    /// the call succeeds; whatever crates happen to be installed don't
+    /// matter for parser coverage.
+    #[test]
+    fn live_cargo_inventory_succeeds_in_a_rust_environment() {
+        let live = LiveCargo::new();
+        let probe = Command::new(live.binary()).arg("--version").output();
+        if !matches!(&probe, Ok(o) if o.status.success()) {
+            return;
+        }
+        let inv = live.inventory().expect("inventory");
+        // Every crate name is a valid cargo package name (kebab-case
+        // alphanumerics + a few extras). Defensive sanity check.
+        for name in inv.crates.keys() {
+            assert!(!name.is_empty(), "empty crate name in inventory");
+            assert!(!name.contains(' '), "crate name has whitespace: {name}");
+        }
+    }
+}