@zackees/soldr 0.9.11 → 0.9.12

package/README.md

@@ -46,20 +46,90 @@ Current release line:
 - the supported external integration boundary remains the `soldr` executable, not the internal Rust crates; see [docs/API_BOUNDARY.md](./docs/API_BOUNDARY.md)
 - practical integration examples for local builds and GitHub Actions live in [INTEGRATION.md](./INTEGRATION.md)
 
-## Install from npm
+## Quick start
 
 ```bash
-npm install -g @zackees/soldr
-soldr --version
+# 1. Install or upgrade (same command)
+uv tool install --upgrade soldr
+
+# 2. Put `soldr` in front of every Rust command
+soldr cargo build --release
+soldr cargo test
+soldr cargo clippy --workspace
+
+# 3. See what the cache is doing
+soldr status
 ```
 
-The npm package is a small launcher that downloads the matching `soldr` GitHub
-Release binary for your OS and architecture during install, verifies it against
-the published `SHA256SUMS` file, and exposes the `soldr` command.
+That is the whole integration. The first cacheable compile starts the
+`soldr-daemon` sidecar, pins the toolchain from `rust-toolchain.toml`, and
+every later build on any branch or worktree hits the shared cache.
+
+<details>
+<summary><b>Command reference</b></summary>
+
+### Everyday
+
+| Command | What it does |
+|---|---|
+| `soldr cargo <args>` | Run cargo through the cache with the pinned toolchain |
+| `soldr build --target <triple\|alias>` | Blessed cross-compile with a managed SDK (`win-x64`, `mac-arm64`, `linux-x64-musl`, ...) |
+| `soldr cc` / `soldr c++` | Compile C / C++ with a catalogue-backed toolchain |
+| `soldr lint` | Unified Rust and dependency lint suites |
+| `soldr ci-test` | The prescribed host-validation DAG used in CI |
+| `soldr <tool>` | Fetch and run a pre-built ecosystem tool: `nextest`, `deny`, `audit`, `mdbook`, `just`, ... |
+
+### Toolchain
+
+| Command | What it does |
+|---|---|
+| `soldr rustc`, `rustfmt`, `clippy-driver`, `rustdoc` | Pinned-toolchain passthroughs |
+| `soldr rustup <args>` | Passthrough to rustup, toolchain-aware |
+| `soldr toolchain ensure` | Bootstrap rustup, install the pinned channel, components, and targets |
+| `soldr toolchain link --shim-dir <dir>` | Write PATH shims that re-enter soldr |
+| `soldr doctor` | Report drift between `rust-toolchain.toml` and rustup |
+| `soldr rust-analyzer`, `rust-gdb`, `rust-lldb` | Language server and debuggers |
+
+### Cache
+
+| Command | What it does |
+|---|---|
+| `soldr status` | Cache status and active toolchain |
+| `soldr cache` | Inspect compilation cache entries |
+| `soldr cook` | Prebuild dependencies via bundled cargo-chef |
+| `soldr save` / `soldr load` | Bundle a build cache to `.tar.zst` and restore it on a fresh checkout |
+| `soldr gc` | Review reclaimable cargo `target/` directories |
+| `soldr clean` / `soldr purge` | Clear the build cache / purge every soldr-managed artifact |
+| `soldr config` | Show or set configuration in `~/.soldr/config.toml` |
+
+### Ops
+
+| Command | What it does |
+|---|---|
+| `soldr daemon start\|stop` | Manage the long-lived `soldr-daemon` process |
+| `soldr optimize` | Platform-specific hot-cache tuning |
+| `soldr defender-exclusions` | Manage Windows Defender exclusions for soldr caches |
+| `soldr help <command>` | Full help for any command |
+
+</details>
+
+Also on npm as `@zackees/soldr`: a small launcher that downloads the matching
+GitHub Release binary during install and verifies it against the published
+`SHA256SUMS` file.
 
 Published npm archives and PyPI wheels support both Intel (`x86_64`) and Apple
-Silicon (`arm64`) macOS. Intel artifacts are cross-built through soldr's
-blessed Apple SDK path and smoke-tested on an Intel macOS runner before release.
+Silicon (`arm64`) macOS. Both are cross-built through soldr's blessed Apple
+SDK path on Linux; Intel artifacts are then smoke-tested inside a
+[zackees/docker-mac-x64](https://github.com/zackees/docker-mac-x64) macOS
+Recovery guest hosted on an ordinary Linux runner before release (no GitHub
+Actions job runs on a native macOS runner). The same Recovery guest also
+replays the real `x86_64-apple-darwin` nextest archive -- toolchain
+provisioning included -- on every pull request and again at the release
+commit before publish, so Intel macOS gets the same positively-owned native
+test coverage every other cross-built target gets, without a native macOS
+runner anywhere in the pipeline. Apple Silicon artifacts are cross-built the
+same way but are not executed anywhere in CI until a follow-up issue
+re-enables that before release.
 
 ## GitHub Actions setup
 
@@ -76,6 +146,8 @@ The current GitHub Actions entry point is the public `setup-soldr` action:
 
 That action:
 
+> **Deprecated (soldr#2996).** soldr no longer implements a target cache, so the `target-cache` / `target-cache-mode` / `target-dir` inputs and the `target-cache-hit` / `target-cache-mode` outputs are inert: nothing on the soldr side reads the environment they export. They remain listed because the pinned action still declares them; retiring the inputs themselves is an upstream change. Use `soldr cook`, which is the only durable compiler cache.
+
 - installs `soldr`
 - bootstraps `rustup` into the cached runner-local root when the runner does not already have it
 - preinstalls the exact Rust toolchain from `rust-toolchain.toml` by default via `rustup`

package/contracts/zccache-integration-guardrails.v1.json

@@ -24,11 +24,6 @@
       "gate": "hard",
       "command": "soldr --no-cache cargo nextest run -p soldr-cli --test cargo_front_door -E 'test(/^cli_cargo_wrappers::/)'"
     },
-    {
-      "id": "rust-rust-plan",
-      "gate": "hard",
-      "command": "soldr --no-cache cargo nextest run -p soldr-cli --test cargo_front_door -E 'test(/^cli_rust_plan::/)'"
-    },
     {
       "id": "rust-cache-cli",
       "gate": "hard",
@@ -124,26 +119,6 @@
         "rust-cache-session"
       ]
     },
-    {
-      "id": "rust-plan-cache",
-      "axis": "rust artifact plan",
-      "gate": "hard",
-      "covers": [
-        "in-process restore before cargo",
-        "in-process save after cargo",
-        "artifact bundle cache dir",
-        "partial restore warning",
-        "embedded compile counts drive warm-save decisions"
-      ],
-      "test_files": [
-        "crates/soldr-cli/tests/cargo_front_door/cli_rust_plan.rs",
-        "crates/soldr-cli/src/rust_plan_tests",
-        "crates/soldr-cli/src/cargo_front_door/cache_plan.rs"
-      ],
-      "validation_command_ids": [
-        "rust-rust-plan"
-      ]
-    },
     {
       "id": "disabled-and-non-build",
       "axis": "cache scoping",

package/package.json

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