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..2c29abd7 --- /dev/null +++ b/ci/hooks/tool_guard.py @@ -0,0 +1,174 @@ +#!/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 _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.""" + command = _strip_noncode(command) + segments = re.split(r"&&|\|\||;|\n", 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 "$@"