From 44599044d91febf48be26a1b36e415830e589d97 Mon Sep 17 00:00:00 2001 From: zackees Date: Wed, 13 May 2026 15:26:25 -0700 Subject: [PATCH 1/2] build: retire ./_cargo trampolines; route Rust tooling through soldr Closes #76. Companion to #75. Delete ./_cargo, ./_rustc, ./_rustfmt and route every caller through soldr cargo / soldr rustfmt etc. so the zccache compile cache is hit on every Rust build. The trampolines were useful before soldr existed; now they're noise that bypasses the cache (8-10 min cold builds vs. seconds on warm cache). Add a PreToolUse Bash hook (ci/hooks/tool_guard.py wired via .claude/settings.json) that blocks bare cargo / rustc / rustfmt / clippy-driver and the legacy ./_cargo invocations, with a clear message pointing at soldr. Pattern adapted from zackees/zccache. uv run is rejected too because it bypasses soldr's toolchain selection. Callers updated to use 'soldr cargo' with a plain-cargo fallback (plus a "install soldr with: uv tool install soldr" hint): - ./lint - cargo fmt --check + cargo clippy - ./test - cargo test --workspace - ./install - cargo build --bin fastled when binstall missed - ./build-wheel - cargo build --release --bin fastled - .github/workflows/_build.yml - same path in CI CLAUDE.md updated to document the new rule and the hook. Tested locally: bash lint passes (soldr cargo fmt + soldr cargo clippy both hit the zccache). Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/settings.json | 16 ++++ .github/workflows/_build.yml | 7 +- CLAUDE.md | 4 +- _cargo | 33 -------- _rustc | 16 ---- _rustfmt | 16 ---- build-wheel | 14 +++- ci/hooks/README.md | 19 +++++ ci/hooks/tool_guard.py | 154 +++++++++++++++++++++++++++++++++++ install | 16 ++-- lint | 15 ++-- test | 12 ++- 12 files changed, 234 insertions(+), 88 deletions(-) create mode 100644 .claude/settings.json delete mode 100755 _cargo delete mode 100755 _rustc delete mode 100755 _rustfmt create mode 100644 ci/hooks/README.md create mode 100644 ci/hooks/tool_guard.py diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 00000000..24e372bd --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,16 @@ +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "uv run python ci/hooks/tool_guard.py", + "timeout": 5 + } + ] + } + ] + } +} diff --git a/.github/workflows/_build.yml b/.github/workflows/_build.yml index a8f68be7..dec2b81c 100644 --- a/.github/workflows/_build.yml +++ b/.github/workflows/_build.yml @@ -63,19 +63,20 @@ jobs: # so maturin packages it into -.data/scripts/ in the wheel. # See `build-wheel` and `[tool.maturin] data` in pyproject.toml. if [ -n "${{ inputs.maturin-target }}" ]; then - ./_cargo build --release --bin fastled --target "${{ inputs.maturin-target }}" + soldr cargo build --release --bin fastled --target "${{ inputs.maturin-target }}" case "${{ inputs.maturin-target }}" in *windows*) EXE_NAME="fastled.exe" ;; *) EXE_NAME="fastled" ;; esac BIN_SRC="target/${{ inputs.maturin-target }}/release/${EXE_NAME}" else - ./_cargo build --release --bin fastled + soldr cargo build --release --bin fastled case "$(uname -s)" in MINGW*|MSYS*|CYGWIN*) EXE_NAME="fastled.exe" ;; *) EXE_NAME="fastled" ;; esac - # _cargo forces an MSVC target on Windows even without --target. + # On Windows the rustup default host triple is MSVC; cargo writes + # the binary under target//release/ even without --target. if [ -n "${CARGO_BUILD_TARGET:-}" ] || [ "$EXE_NAME" = "fastled.exe" ]; then ARCH="$(uname -m)" if [ "$ARCH" = "x86_64" ]; then TRIPLE="x86_64-pc-windows-msvc"; else TRIPLE="aarch64-pc-windows-msvc"; fi diff --git a/CLAUDE.md b/CLAUDE.md index 344b30bd..7c677dd4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,9 +18,9 @@ This project uses **soldr** (build orchestrator) + **zccache** (compile cache). - `soldr` wraps `cargo` and automatically uses `zccache` as `RUSTC_WRAPPER`. - CI installs soldr via `zackees/setup-soldr@v0` (see workflows). Local dev should match. -**When you invoke cargo from an agent, prefer `soldr cargo …` over plain `cargo …`.** The `./_cargo` trampoline currently exec's plain `cargo` — that's a known gap (#76) and will be replaced. Until then, run cargo directly through soldr or you'll burn 10 minutes per build. +**When you invoke any Rust tool from an agent, use `soldr cargo …`, `soldr rustfmt …`, etc.** Plain `cargo` / `rustc` / `rustfmt` are blocked by the PreToolUse hook (`ci/hooks/tool_guard.py`) — they bypass zccache and turn a 30-second incremental build into a 10-minute cold build. The legacy `./_cargo`, `./_rustc`, `./_rustfmt` trampolines were retired in #76; the hook explicitly rejects them too. -If `soldr` is not on PATH, fall back to plain `cargo` but warn the user that builds will be slow. +If `soldr` is not on PATH, install it with `uv tool install soldr` (or see `zackees/soldr` on GitHub). ## Tests are slow — pick a narrow set diff --git a/_cargo b/_cargo deleted file mode 100755 index d89acd99..00000000 --- a/_cargo +++ /dev/null @@ -1,33 +0,0 @@ -#!/bin/bash -# Trampoline: ensure the correct Rust toolchain is used. -# On Windows, Chocolatey may install a GNU-based Rust that conflicts with -# the MSVC toolchain required by this project. This script: -# 1. Puts the rustup-managed toolchain bin FIRST in PATH -# 2. Sets CARGO_BUILD_TARGET to force MSVC on Windows -SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" - -# Find rustup -RUSTUP="$(command -v rustup 2>/dev/null || true)" -if [ -z "$RUSTUP" ]; then - exec cargo "$@" -fi - -# Get the toolchain's bin directory and prepend it to PATH -TOOLCHAIN_BIN="$($RUSTUP run "$(grep channel "$SCRIPT_DIR/rust-toolchain.toml" 2>/dev/null | head -1 | sed 's/.*"\(.*\)"/\1/')" rustc --print sysroot 2>/dev/null)/bin" -if [ -d "$TOOLCHAIN_BIN" ]; then - export PATH="$TOOLCHAIN_BIN:$PATH" -fi - -# On Windows, force MSVC target to prevent GNU toolchain contamination -case "$(uname -s)" in - MINGW*|MSYS*|CYGWIN*) - ARCH="$(uname -m)" - if [ "$ARCH" = "x86_64" ]; then - export CARGO_BUILD_TARGET="x86_64-pc-windows-msvc" - else - export CARGO_BUILD_TARGET="aarch64-pc-windows-msvc" - fi - ;; -esac - -exec cargo "$@" diff --git a/_rustc b/_rustc deleted file mode 100755 index cebfea3d..00000000 --- a/_rustc +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/bash -# Trampoline: prefers the shared rustup proxy in ~/.cargo/bin when present. -if [ -n "${CARGO_HOME:-}" ]; then - CARGO_BIN="$CARGO_HOME/bin" -elif [ -n "${HOME:-}" ]; then - CARGO_BIN="$HOME/.cargo/bin" -elif [ -n "${USERPROFILE:-}" ]; then - CARGO_BIN="$USERPROFILE/.cargo/bin" -else - CARGO_BIN="" -fi - -if [ -n "$CARGO_BIN" ] && [ -d "$CARGO_BIN" ]; then - export PATH="$CARGO_BIN:$PATH" -fi -exec rustc "$@" diff --git a/_rustfmt b/_rustfmt deleted file mode 100755 index 1d9efda3..00000000 --- a/_rustfmt +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/bash -# Trampoline: prefers the shared rustup proxy in ~/.cargo/bin when present. -if [ -n "${CARGO_HOME:-}" ]; then - CARGO_BIN="$CARGO_HOME/bin" -elif [ -n "${HOME:-}" ]; then - CARGO_BIN="$HOME/.cargo/bin" -elif [ -n "${USERPROFILE:-}" ]; then - CARGO_BIN="$USERPROFILE/.cargo/bin" -else - CARGO_BIN="" -fi - -if [ -n "$CARGO_BIN" ] && [ -d "$CARGO_BIN" ]; then - export PATH="$CARGO_BIN:$PATH" -fi -exec rustfmt "$@" diff --git a/build-wheel b/build-wheel index 765a5abf..9bfd1203 100644 --- a/build-wheel +++ b/build-wheel @@ -19,17 +19,23 @@ case "$(uname -s)" in esac echo "Compiling fastled CLI (release)..." -"$SCRIPT_DIR/_cargo" build --release --bin fastled +if command -v soldr &> /dev/null; then + soldr cargo build --release --bin fastled +else + echo "Warning: soldr not found; falling back to plain cargo (slow). Install with: uv tool install soldr" + cargo build --release --bin fastled +fi -# Resolve where cargo wrote the binary. The _cargo wrapper sets -# CARGO_BUILD_TARGET on Windows so the binary lands under a triple subdir. +# Resolve where cargo wrote the binary. cargo on Windows MSVC writes the +# binary under a triple subdir. if [[ -n "${CARGO_BUILD_TARGET:-}" ]]; then BIN_SRC="$SCRIPT_DIR/target/${CARGO_BUILD_TARGET}/release/${EXE_NAME}" else BIN_SRC="$SCRIPT_DIR/target/release/${EXE_NAME}" fi -# Discover from _cargo's exported target on Windows even if not set in env. +# On Windows the rustup default host triple is MSVC; the binary lands under +# target//release/ even when CARGO_BUILD_TARGET isn't set. case "$(uname -s)" in MINGW*|MSYS*|CYGWIN*) ARCH="$(uname -m)" diff --git a/ci/hooks/README.md b/ci/hooks/README.md new file mode 100644 index 00000000..906311a8 --- /dev/null +++ b/ci/hooks/README.md @@ -0,0 +1,19 @@ +# Claude Code hooks + +Python scripts invoked by Claude Code hooks (configured in `.claude/settings.json`). + +All hooks run via `uv run python ci/hooks/.py` so they share the project +Python environment. + +## Hooks + +- `tool_guard.py` — **PreToolUse / Bash**. Blocks bare `cargo`, `rustc`, + `rustfmt`, `clippy-driver`, the `cargo-clippy` / `cargo-fmt` aliases, and the + legacy `./_cargo`, `./_rustc`, `./_rustfmt` trampolines (retired in #76). All + Rust tooling must go through `soldr` so zccache is consulted; otherwise cold + builds take 8–10 minutes (see #75). + + Also rejects `uv run cargo ...` and friends because `uv run ` + bypasses soldr's toolchain selection. + + `soldr ` invocations and `uv pip ...` pass through. diff --git a/ci/hooks/tool_guard.py b/ci/hooks/tool_guard.py new file mode 100644 index 00000000..f97b9809 --- /dev/null +++ b/ci/hooks/tool_guard.py @@ -0,0 +1,154 @@ +#!/usr/bin/env python3 +"""PreToolUse Bash hook: enforce soldr for Rust tooling. + +Blocks invocations that bypass soldr/zccache: + +* Bare ``cargo``, ``rustc``, ``rustfmt``, ``clippy-driver`` (and their + ``cargo-`` variants). These must run through ``soldr cargo …`` so the + zccache compile cache is consulted; otherwise cold builds take 8-10 + minutes (see issue #75). +* Legacy ``./_cargo``, ``./_rustc``, ``./_rustfmt`` trampolines. Removed + by issue #76; suggests the soldr equivalent. +* ``uv run ``. Bypasses soldr's toolchain selection. + +Exit code 0 always; denial signalled via JSON payload on stdout so the +Claude Code harness reports the reason inline. +""" + +from __future__ import annotations + +import json +import re +import sys + +RUST_TOOLS = { + "cargo", + "rustc", + "rustfmt", + "clippy-driver", + "cargo-clippy", + "cargo-fmt", +} +LEGACY_RUST_TRAMPOLINES = {"_cargo", "_rustc", "_rustfmt"} + + +def _is_env_assignment(word: str) -> bool: + return re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", word) is not None + + +def _command_words(seg: str) -> list[str]: + words = seg.split() + if words and words[0] == "env": + words = words[1:] + while words and _is_env_assignment(words[0]): + words = words[1:] + return words + + +def _resolve_uv_run_tool(seg: str) -> str | None: + m = re.match(r"uv\s+run\s+--script\s+(\S+)", seg) + if m: + return m.group(1) + m = re.match(r"uv\s+run\s+(\S+)", seg) + return m.group(1) if m else None + + +def check_command(command: str) -> tuple[str, str] | None: + """Return (tool, reason) if forbidden, otherwise None.""" + segments = re.split(r"&&|\|\||;", command) + + for seg in segments: + seg = seg.strip() + if not seg: + continue + + words = _command_words(seg) + if not words: + continue + + first = words[0] + bare = first.lstrip("./\\") + normalized = " ".join(words) + + if bare in LEGACY_RUST_TRAMPOLINES: + replacement = bare[1:] + return ( + bare, + f"`./{bare}` was retired (see issue #76). " + f"Use `soldr {replacement} ...` instead.", + ) + + if normalized.startswith("soldr "): + continue + + if normalized.startswith("uv run ") or normalized.startswith("uv run "): + tool = _resolve_uv_run_tool(normalized) + if tool is None: + continue + tool_bare = tool.lstrip("./\\") + if tool_bare in LEGACY_RUST_TRAMPOLINES: + replacement = tool_bare[1:] + return ( + tool_bare, + f"`{tool}` was retired (see issue #76). " + f"Use `soldr {replacement} ...` instead.", + ) + if tool in RUST_TOOLS: + return ( + tool, + f"Use `soldr {tool} ...` instead of `uv run {tool} ...`. " + "`uv run ` bypasses soldr's toolchain " + "selection and the zccache compile cache.", + ) + continue + + if normalized.startswith("uv pip "): + continue + + if first in RUST_TOOLS: + return ( + first, + f"Use `soldr {first} ...` instead of bare `{first}`. " + "Plain cargo invocations bypass zccache and turn a 30-second " + "incremental build into a 10-minute cold build (see issue #75).", + ) + + return None + + +def deny(reason: str) -> None: + json.dump( + { + "hookSpecificOutput": { + "hookEventName": "PreToolUse", + "permissionDecision": "deny", + "permissionDecisionReason": reason, + } + }, + sys.stdout, + ) + + +def main() -> int: + try: + data = json.load(sys.stdin) + except json.JSONDecodeError: + return 0 + + if data.get("tool_name", "") != "Bash": + return 0 + + command = data.get("tool_input", {}).get("command", "") + if not command: + return 0 + + result = check_command(command) + if result: + _, reason = result + deny(reason) + + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/install b/install index 52b77133..248e112e 100755 --- a/install +++ b/install @@ -113,8 +113,14 @@ fi # auto-install plumbing flags (--internal-ensure-fastled-repo, etc.). if [[ "$FASTLED_CLI_BINSTALLED" -eq 0 ]]; then echo "Building fastled CLI from source..." - "$(dirname "$0")/_cargo" build --release --bin fastled \ - || { echo "Error: cargo build --bin fastled failed"; exit 1; } + if command -v soldr &> /dev/null; then + soldr cargo build --release --bin fastled \ + || { echo "Error: soldr cargo build --bin fastled failed"; exit 1; } + else + echo "Warning: soldr not found; falling back to plain cargo (slow). Install with: uv tool install soldr" + cargo build --release --bin fastled \ + || { echo "Error: cargo build --bin fastled failed"; exit 1; } + fi fi # Locate the just-built (or binstalled) Rust binary and stage it where @@ -135,9 +141,9 @@ else fi BIN_SRC="" -# Discover where the binary landed. `_cargo` sets CARGO_BUILD_TARGET on -# Windows, so the bin is under target//release/; on other platforms -# (and when binstall provided it) check the usual locations. +# Discover where the binary landed. cargo on Windows MSVC writes under +# target//release/; on other platforms (and when binstall provided it) +# check the usual locations. for CANDIDATE in \ "target/x86_64-pc-windows-msvc/release/${EXE_NAME}" \ "target/aarch64-pc-windows-msvc/release/${EXE_NAME}" \ diff --git a/lint b/lint index 7f8f39ea..4e94a49d 100755 --- a/lint +++ b/lint @@ -3,14 +3,19 @@ set -e SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" -# Rust linting (skip if cargo not available) -if command -v cargo &> /dev/null; then +# Rust linting goes through soldr so the zccache compile cache is hit. +# Install soldr with: uv tool install soldr (or see zackees/soldr). +if command -v soldr &> /dev/null; then echo Running cargo fmt check - "$SCRIPT_DIR/_cargo" fmt --all --check + soldr cargo fmt --all --check echo Running cargo clippy - "$SCRIPT_DIR/_cargo" clippy --workspace --all-targets -- -D warnings + soldr cargo clippy --workspace --all-targets -- -D warnings +elif command -v cargo &> /dev/null; then + echo "WARNING: soldr not found; falling back to plain cargo (slow). Install with: uv tool install soldr" + cargo fmt --all --check + cargo clippy --workspace --all-targets -- -D warnings else - echo "WARNING: cargo not found, skipping Rust linting" + echo "WARNING: neither soldr nor cargo found; skipping Rust linting" fi echo Running ruff src diff --git a/test b/test index fdf0e786..82bbfd95 100755 --- a/test +++ b/test @@ -4,11 +4,15 @@ set -euo pipefail SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" -# Rust tests (skip if cargo not available) -if command -v cargo &> /dev/null; then - "$SCRIPT_DIR/_cargo" test --workspace +# Rust tests go through soldr so the zccache compile cache is hit. +# Install soldr with: uv tool install soldr (or see zackees/soldr). +if command -v soldr &> /dev/null; then + soldr cargo test --workspace +elif command -v cargo &> /dev/null; then + echo "WARNING: soldr not found; falling back to plain cargo (slow). Install with: uv tool install soldr" + cargo test --workspace else - echo "WARNING: cargo not found, skipping Rust tests" + echo "WARNING: neither soldr nor cargo found; skipping Rust tests" fi uv run pytest -x -v -s --durations=0 tests/unit "$@" From 23a00eb022fc654c059bde55a635e6679377028a Mon Sep 17 00:00:00 2001 From: zackees Date: Wed, 13 May 2026 15:27:46 -0700 Subject: [PATCH 2/2] fix(hook): ignore cargo references inside heredocs and quoted strings The PreToolUse hook was rejecting gh pr create invocations whose heredoc body documented the hook's deny semantics with literal 'cargo build' text. Strip heredocs, command substitutions, and single/double-quoted strings before splitting the command into pipeline segments. Verified: 'cargo build' still denied; 'echo "cargo build"', 'cat < --- ci/hooks/tool_guard.py | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/ci/hooks/tool_guard.py b/ci/hooks/tool_guard.py index f97b9809..2c29abd7 100644 --- a/ci/hooks/tool_guard.py +++ b/ci/hooks/tool_guard.py @@ -53,9 +53,29 @@ def _resolve_uv_run_tool(seg: str) -> str | None: return m.group(1) if m else None +def _strip_noncode(command: str) -> str: + """Remove heredocs, quoted strings, and command substitutions. + + These regions contain prose that may include words like 'cargo build' + in PR bodies or documentation, but they are not invoked as commands. + """ + out = re.sub( + r"<<-?\s*'?\"?(\w+)'?\"?[\s\S]*?(?:^|\n)\s*\1\s*(?=\n|$)", + " ", + command, + flags=re.MULTILINE, + ) + out = re.sub(r"\$\([^()]*\)", " ", out) + out = re.sub(r"`[^`]*`", " ", out) + out = re.sub(r"'[^']*'", " ", out) + out = re.sub(r'"[^"]*"', " ", out) + return out + + def check_command(command: str) -> tuple[str, str] | None: """Return (tool, reason) if forbidden, otherwise None.""" - segments = re.split(r"&&|\|\||;", command) + command = _strip_noncode(command) + segments = re.split(r"&&|\|\||;|\n", command) for seg in segments: seg = seg.strip()