fix(tui): give cargo the absolute path of protoc, so it stops rebuilding pi-tools-api - #30

Summary

Plan item protoc_abs, chosen by the owner on 2026-10-20: find_protoc() returns the absolute path of protoc when it finds the tool on PATH. Before, it returned the bare name.

build script of pi-tools-api
  pi_proto_build::compile_protos
    find_protoc()
      1. $PROTOC                    exists?  -> that path
      2. bin/protoc (walk up)       runs?    -> relative path  (exists, so cargo can track it)
      3. protoc on PATH
-        check "protoc"                       -> "protoc"       (no such file in the package dir)
+        for each dir in PATH: <dir>/protoc, a file with an execute bit, runs?
+                                             -> /abs/path/protoc
    emit_rerun_if_changed
      println!("cargo:rerun-if-changed={protoc}")   <- cargo: missing path = changed in every run

cargo:rerun-if-changed=protoc names a path that does not exist in the package directory. Cargo treats such a path as changed in every run (its own words: stale: missing ".../pi-tools-api/protoc"). So each cargo run started the build script again and rebuilt pi-tools-api and the crates above it. CI has protoc on PATH (arduino/setup-protoc) and no PROTOC variable, so CI hit this. A developer with an absolute PROTOC did not. How much CI gains is small (see "CI result, and a correction"): the loop shows only when the same cargo command runs again. Only one build script uses pi-proto-build (pi-tools-api/build.rs).

crates/build/pi-proto-build/src/find_protoc.rs
├── executables_on_path(name, path, cwd)   NEW  PATH search; absolute results; file + execute bit
├── is_executable_file                     NEW  (unix: mode & 0o111; else is_file)
├── find_protoc  step 3                    uses it; the first candidate that runs wins
└── tests                                  8 new (7 for the search, 1 regression test)
CHANGELOG.md                               1 entry (Fixed)

Base: ci/release-setup-protoc-token (#29), the same chain as #28. Not merged. #27, #28 and #29 are not merged either.

One difference to know: for a protoc found on PATH, find_protoc_include_dir now gets an absolute path, so pi-proto-build also passes -I<prefix>/include (the directory next to bin/, if it exists). It already did this for an absolute PROTOC. On CI the directory should exist (setup-protoc unpacks bin/ and include/), and the TUI CI run of this PR builds the protos without error. The log does not print the protoc arguments, so it does not show that the flag was passed. On the WSL machine used below the directory does not exist, so that flag was not tested there.

Evidence

WSL2, protoc 28.3 on PATH, PROTOC unset, build output in tmpfs, cargo check --locked -p pi-tools-api, nothing changed between the runs:

• Before: cargo's fingerprint log says stale: missing "<repo>/tui/crates/codegen/pi-tools-api/protoc".
• After: the third run prints only Finished, and the fingerprint log has no line for pi-tools-api.
• The file that the build script generates (pi.grok.tools.v1.rs) has the same sha256 before and after.
• cargo test -p pi-proto-build --lib: 10 passed (the 8 new and the 2 old tests). cargo fmt --check and cargo clippy --all-targets for the package: clean.
• Mutation check: the old find_protoc.rs with only the new regression test fails:

test find_protoc::tests::the_path_that_find_protoc_gives_is_a_file_that_exists ... FAILED
`protoc` is not a file

CI result, and a correction

TUI CI (run 39356795564) and CI (run 39356795545) passed on 7a4ce9d: 8,490 passed / 0 failed / 21 ignored, and every suite equals its reference number. The commits after 7a4ce9d change docs only.

The gain in CI is small:

"Before": the compile counts come from the run 39193752451; the times come from the three runs for #28.

The cargo check job runs two cargo commands with the same packages, so it showed the loop: one compile less now. The cargo test job runs one cargo command for each suite, and each command builds the dependencies with the features of its own packages. So pi-tools-api is compiled once in each of the 7 suites that use it, with or without this PR, and the same suites compile pi-shell and pi-pager before and after.

An earlier version of this description, the CHANGELOG entry and the execution log said that the 7 / 4 / 3 compiles were the loop. That was wrong, and the CI run of this PR shows it. The CHANGELOG entry and the execution log are corrected in e2de4c4. The effect of this PR is on a developer's machine, where the same command runs again and again.

Merge Danger

Door: two-way. One function in a build helper; revert it at any time.

Blast Radius: the build of pi-tools-api (the only user of pi-proto-build), and with it every crate above it, on Linux and macOS. If protoc were in a place that the old check found and the new search does not, the build would fail at that crate. I know of no such place: on Linux and macOS, Command::new looks in the PATH directories only, as the new search does. The TUI does not build on Windows.