@zackees/soldr 0.7.89 → 0.7.90

package/README.md

@@ -198,18 +198,56 @@ soldr rustfmt src/main.rs
 
 ## How it works
 
-```text
-soldr cargo build --release
-  +-- resolve the real cargo binary
-  +-- on Windows, re-run from a soldr-owned runtime copy when needed
-  +-- fetch/start managed zccache when cache is enabled
-  +-- set soldr as the compiler wrapper for this build
-  +-- have soldr wrapper mode delegate to managed zccache
-  +-- delegate to cargo with your existing flags
+soldr is a **chameleon binary**: one executable that picks its role from `argv[1]` on every invocation. Three roles:
+
+```mermaid
+flowchart TD
+    A["soldr <argv[1]> ..."] --> B{"classify argv[1]"}
+    B -->|"path to rustc"| C["<b>Cache mode</b><br/>invoked as RUSTC_WRAPPER by cargo.<br/>hash inputs, query cache,<br/>forward to real rustc on miss."]
+    B -->|"built-in verb<br/>cargo · rustup · status · cache · ..."| D["<b>Dispatch mode</b><br/>run internal handler,<br/>or exec a toolchain binary<br/>resolved via rustup."]
+    B -->|"anything else<br/>maturin · cargo-nextest · cbindgen · ..."| E["<b>Tool-fetch mode</b><br/>resolve via known_tools,<br/>download from GitHub Releases,<br/>exec the fetched binary."]
+```
+
+When you run `soldr cargo build`, the two other modes both come into play. soldr acts as the dispatch-mode front door, then cargo re-invokes soldr once per crate as the RUSTC_WRAPPER — that second soldr is the cache-mode instance that talks to the managed zccache daemon:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant U as User
+    participant S1 as soldr (front door)
+    participant C as cargo
+    participant S2 as soldr (RUSTC_WRAPPER)
+    participant Z as zccache daemon
+    participant R as real rustc
+
+    U->>S1: soldr cargo build --release
+    S1->>S1: dispatch mode: cargo verb
+    S1->>Z: start managed zccache if needed
+    S1->>C: exec cargo (RUSTC_WRAPPER=soldr)
+    loop per crate
+        C->>S2: soldr [path-to-rustc] [args]
+        S2->>Z: query cache (hash of inputs)
+        alt cache hit
+            Z-->>S2: cached artifact
+            S2-->>C: emit artifact, exit 0
+        else cache miss
+            Z->>R: forward to rustc
+            R-->>Z: fresh artifact
+            Z->>Z: store keyed by input hash
+            Z-->>S2: artifact
+            S2-->>C: emit artifact, exit 0
+        end
+    end
+    C-->>S1: build complete
+    S1-->>U: exit
+```
+
+Tool fetches are much simpler — no cargo, no rustc, no wrapper handshake:
 
+```text
 soldr maturin build --release
-  +-- maturin cached? --> run instantly
-  +-- not cached?     --> download pre-built binary (2s) --> run
+  +-- maturin cached?  --> run instantly
+  +-- not cached?      --> download pre-built binary (2s) --> run
 ```
 
 ## Linker speed (the other half of fast CI)
@@ -256,25 +294,30 @@ If you also have many separate test binaries, consider consolidating them under
 
 ## Architecture
 
+**Monocrate.** A single Rust crate `soldr-cli` under `crates/soldr-cli/`, with four module trees inside it. The earlier four-crate workspace (`soldr-core` / `soldr-fetch` / `soldr-cache` / `soldr-cli`) was collapsed in 2026-05; the regression guard `crates/soldr-cli/tests/monocrate_guard.rs` fails the build if anyone reintroduces a second crate.
+
 ```
 soldr/
 |-- crates/
-|   |-- soldr-core/      # Shared types, config, cache directory layout
-|   |-- soldr-fetch/     # Binary resolution + download (the crgx half)
-|   |-- soldr-cache/     # Compilation caching (the zccache half)
-|   `-- soldr-cli/       # CLI entry point + wrapper mode
-|-- src/soldr/           # Python package (maturin bin bindings)
+|   `-- soldr-cli/
+|       |-- src/
+|       |   |-- core/            # Shared types, config, cache paths (formerly soldr-core)
+|       |   |-- fetch/           # Binary resolution + download (formerly soldr-fetch)
+|       |   |-- cache_lib/       # RUSTC_WRAPPER + daemon IPC (formerly soldr-cache)
+|       |   `-- main.rs + cli/   # Mode detection, dispatch, cargo front door
+|       `-- tests/
+|-- src/soldr/                    # Python package (maturin bin bindings)
 `-- tests/
 ```
 
-| Crate | Role |
+| Module | Role |
 |---|---|
-| `soldr-core` | Cache paths, config, version types |
-| `soldr-fetch` | Resolve crate binaries from crates.io metadata and GitHub Releases. Download and cache. |
-| `soldr-cache` | zccache integration helpers, cache policy, session plumbing. |
-| `soldr-cli` | Mode detection, cargo front door, built-in commands (`status`, `clean`, `config`, `cache`), tool fetch dispatch. |
+| `src/core/` | Shared types, config (`~/.soldr/config.toml`), target-triple resolution (MSVC default on Windows), cache paths, error types. No I/O beyond config files. |
+| `src/fetch/` | Binary resolution. `known_tools` registry, `trust` (SHA-256 pins + `SOLDR_TRUST_MODE` enforcement), rustup auto-bootstrap, resolution chain (local cache → repo lookup → GitHub Releases → extract). |
+| `src/cache_lib/` | `RUSTC_WRAPPER` mode: hash inputs (blake3), check `~/.soldr/cache/`, daemon IPC (Unix socket / Windows named pipe), LRU eviction, `soldr save` / `soldr load` archive transport, auto-GC. |
+| `src/main.rs` + cli/ | Mode detection (chameleon dispatch), clap for built-ins, exec for tool fetch, cargo front door (`soldr cargo ...`). |
 
-These workspace crates are implementation details. They are not a supported public Rust library API.
+A thin `src/lib.rs` re-exports `pub mod core; pub mod fetch; pub mod cache_lib;` so the library integration tests can keep `use soldr_cli::core::*`-style imports. This is not a supported public Rust library API.
 
 ## Prior art
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackees/soldr",
-  "version": "0.7.89",
+  "version": "0.7.90",
   "description": "Instant Rust tools and builds from one command.",
   "license": "BSD-3-Clause",
   "homepage": "https://github.com/zackees/soldr",