chore(cli): route fbuild-cli through fbuild-paths; document the clap exception

crates/fbuild-cli/src/cli/debug.rs

@@ -561,6 +561,17 @@ pub async fn run_debug(
 mod tests {
     use super::*;
 
+    /// Fixture ELF path, built from the canonical segments so it cannot
+    /// drift from the layout the resolver actually walks
+    /// (FastLED/fbuild#1349).
+    fn fixture_elf_path() -> String {
+        format!(
+            "/proj/{}/{}/esp32dev/release/firmware.elf",
+            fbuild_paths::FBUILD_DIR_NAME,
+            fbuild_paths::BUILD_DIR_NAME
+        )
+    }
+
     // ---------- capability matrix ----------
 
     #[test]
@@ -727,7 +738,8 @@ mod tests {
 
     #[test]
     fn build_gdb_argv_orders_baud_before_target_remote() {
-        let elf = Path::new("/proj/.fbuild/build/esp32dev/release/firmware.elf");
+        let elf_path = fixture_elf_path();
+        let elf = Path::new(&elf_path);
         let argv = build_gdb_argv(elf, "COM5", 115_200);
         assert_eq!(
             argv,
@@ -736,7 +748,7 @@ mod tests {
                 "set serial baud 115200".to_string(),
                 "-ex".to_string(),
                 "target remote COM5".to_string(),
-                "/proj/.fbuild/build/esp32dev/release/firmware.elf".to_string(),
+                fixture_elf_path(),
             ]
         );
     }

crates/fbuild-cli/src/cli/dispatch.rs

@@ -81,7 +81,11 @@ pub async fn async_main() {
 
     // Notify when running in dev mode (matches Python behavior)
     if std::env::var("FBUILD_DEV_MODE").is_ok_and(|v| v == "1") {
-        output::progress("FBUILD_DEV_MODE=1 (dev mode: port 8865, ~/.fbuild/dev/)");
+        output::progress(format!(
+            "FBUILD_DEV_MODE=1 (dev mode: port {}, {})",
+            fbuild_paths::get_daemon_port(),
+            fbuild_paths::get_fbuild_root().display()
+        ));
     }
 
     // FastLED/fbuild#626 Phase 1: passive update check. Kick it off in
@@ -608,8 +612,9 @@ pub async fn async_main() {
         }) => {
             if let Some(bd) = &build_dir {
                 output::warn(format!(
-                    "--build-dir {} is accepted for pio ci compatibility but not yet honored; outputs go to .fbuild/build/...",
-                    bd
+                    "--build-dir {} is accepted for pio ci compatibility but not yet honored; outputs go to {}/...",
+                    bd,
+                    fbuild_paths::get_project_build_root(std::path::Path::new(".")).display()
                 ));
             }
             let normalized = normalize_ci_sketches(&sketches);

crates/fbuild-cli/src/cli/ide.rs

@@ -44,7 +44,7 @@ struct IdeState {
 }
 
 fn ide_state_path(project_path: &Path) -> NormalizedPath {
-    NormalizedPath::from(project_path.join(".fbuild").join("ide_state.json"))
+    NormalizedPath::from(fbuild_paths::get_project_fbuild_dir(project_path).join("ide_state.json"))
 }
 
 /// Read the persisted environment. Tolerates an absent file, an empty file,
@@ -59,7 +59,7 @@ fn read_persisted_env(project_path: &Path) -> Option<String> {
 
 /// Persist the chosen environment, creating `.fbuild/` if needed.
 fn write_persisted_env(project_path: &Path, environment: &str) -> fbuild_core::Result<()> {
-    let dir = project_path.join(".fbuild");
+    let dir = fbuild_paths::get_project_fbuild_dir(project_path);
     std::fs::create_dir_all(&dir).map_err(|e| {
         fbuild_core::FbuildError::Other(format!("failed to create {}: {}", dir.display(), e))
     })?;
@@ -580,15 +580,15 @@ mod tests {
     #[test]
     fn ide_state_malformed_json_is_none() {
         let tmp = tempfile::tempdir().unwrap();
-        std::fs::create_dir_all(tmp.path().join(".fbuild")).unwrap();
+        std::fs::create_dir_all(fbuild_paths::get_project_fbuild_dir(tmp.path())).unwrap();
         std::fs::write(ide_state_path(tmp.path()), "{ not json").unwrap();
         assert_eq!(read_persisted_env(tmp.path()), None);
     }
 
     #[test]
     fn ide_state_empty_file_is_none() {
         let tmp = tempfile::tempdir().unwrap();
-        std::fs::create_dir_all(tmp.path().join(".fbuild")).unwrap();
+        std::fs::create_dir_all(fbuild_paths::get_project_fbuild_dir(tmp.path())).unwrap();
         std::fs::write(ide_state_path(tmp.path()), "").unwrap();
         assert_eq!(read_persisted_env(tmp.path()), None);
     }

crates/fbuild-cli/src/cli/ide_debug.rs

@@ -312,12 +312,14 @@ mod tests {
 
     #[test]
     fn build_debug_entry_includes_elf_program_when_given() {
-        let elf = Path::new("/proj/.fbuild/build/esp32dev/release/firmware.elf");
-        let entry = build_debug_entry("esp32dev", Some(elf));
-        assert_eq!(
-            entry.program.as_deref(),
-            Some("/proj/.fbuild/build/esp32dev/release/firmware.elf")
+        let elf_path = format!(
+            "/proj/{}/{}/esp32dev/release/firmware.elf",
+            fbuild_paths::FBUILD_DIR_NAME,
+            fbuild_paths::BUILD_DIR_NAME
         );
+        let elf = Path::new(&elf_path);
+        let entry = build_debug_entry("esp32dev", Some(elf));
+        assert_eq!(entry.program.as_deref(), Some(elf_path.as_str()));
     }
 
     #[test]

crates/fbuild-cli/src/cli/purge.rs

@@ -132,7 +132,10 @@ pub fn list_cached_packages(cache_root: &std::path::Path) -> fbuild_core::Result
         ));
         output::result("\nUsage:");
         output::result("  fbuild purge all              Remove all cached packages");
-        output::result("  fbuild purge project          Remove project build artifacts (.fbuild/)");
+        output::result(format!(
+            "  fbuild purge project          Remove project build artifacts ({}/)",
+            fbuild_paths::FBUILD_DIR_NAME
+        ));
         output::result("  fbuild purge <name>           Remove specific cache subdirectory");
         output::result("  fbuild purge ... --dry-run    Show what would be removed");
         return Ok(());

crates/fbuild-cli/src/cli/symbols_cmd.rs

@@ -200,10 +200,12 @@ fn resolve_elf(input: &Path) -> Result<PathBuf> {
     if input.is_dir() {
         discover_elf_in_project(input).ok_or_else(|| {
             FbuildError::BuildFailed(format!(
-                "no ELF found under {} (looked for build_info.json's \
-                 prog_path, .fbuild/build/**/firmware.elf, \
-                 .pio/build/**/firmware.elf, and *.elf at top level)",
-                input.display()
+                "no ELF found under {} (looked for build_info.json's prog_path, \
+                 {}/{}/**/firmware.elf, .pio/build/**/firmware.elf, and *.elf at \
+                 top level)",
+                input.display(),
+                fbuild_paths::FBUILD_DIR_NAME,
+                fbuild_paths::BUILD_DIR_NAME
             ))
         })
     } else {
@@ -415,7 +417,9 @@ mod tests {
     fn resolve_reads_nm_from_build_info_auto_discovery() {
         let tmp = tempfile::TempDir::new().unwrap();
         let project = tmp.path();
-        let build_dir = project.join(".fbuild").join("build").join("uno");
+        let build_dir = fbuild_paths::get_project_fbuild_dir(project)
+            .join(fbuild_paths::BUILD_DIR_NAME)
+            .join("uno");
         std::fs::create_dir_all(&build_dir).unwrap();
         let elf = build_dir.join("firmware.elf");
         std::fs::write(&elf, b"\x7fELF").unwrap();

crates/fbuild-cli/src/lib_select.rs

@@ -370,7 +370,7 @@ fn should_scan_entry(entry: &DirEntry) -> bool {
         name.as_str(),
         ".git"
             | ".pio"
-            | ".fbuild"
+            | fbuild_paths::FBUILD_DIR_NAME
             | ".zap"
             | ".build"
             | "build"

crates/fbuild-cli/tests/daemon_crash_recovery.rs

@@ -45,7 +45,7 @@ fn real_home() -> Option<NormalizedPath> {
 /// `fbuild_paths` layout without mutating this process's env (env vars are
 /// process-global and tests run multi-threaded).
 fn dev_root_owner_lock(home: &NormalizedPath) -> NormalizedPath {
-    home.join(".fbuild")
+    home.join(fbuild_paths::FBUILD_DIR_NAME)
         .join("dev")
         .join("daemon")
         .join("root-owner.lock")

dylints/ban_raw_fbuild_path/Cargo.toml

@@ -3,7 +3,7 @@ name = "ban_raw_fbuild_path"
 # Bump the version to bust the dylint .so cache when allowlist.txt
 # changes (setup-soldr's dylint-cache key hashes the manifest but not
 # src/allowlist.txt). Same convention ban_manual_slash_normalize follows.
-version = "0.1.4"
+version = "0.1.5"
 description = "Ban raw '.fbuild' path literals outside fbuild-paths"
 edition = "2021"
 publish = false

dylints/ban_raw_fbuild_path/src/allowlist.txt

@@ -25,6 +25,15 @@ crates/fbuild-paths/src/lib.rs
 # `fbuild_paths::FBUILD_DIR_NAME` is still the name every other crate uses.
 crates/fbuild-core/src/path.rs
 
+# Clap derive, not a hand-written literal. `#[derive(Subcommand)]` stringifies
+# the `///` help text into `&str` literals whose `source_callsite()` is the
+# derive item, so the diagnostic lands on the whole file and cannot be
+# silenced by editing an expression. The only alternative is deleting
+# `.fbuild/build/**/firmware.elf` from the help a user reads, which makes the
+# documentation worse to satisfy a lint. Verified by removing this line: the
+# lint then fires at args.rs:121, the `#[derive(Subcommand)]`.
+crates/fbuild-cli/src/cli/args.rs
+
 # --- Baseline: legacy sites captured at landing (FastLED/fbuild#1349) ---
 # Each line below is a file that spells `.fbuild` by hand today. Removing
 # a line is the unit of progress on #1349; adding one is not allowed.
@@ -46,12 +55,3 @@ crates/fbuild-build/tests/nxplpc_core_compile_commands.rs
 crates/fbuild-build/tests/stm32_acceptance.rs
 crates/fbuild-build/tests/teensy30_acceptance.rs
 crates/fbuild-build/tests/teensy_build.rs
-crates/fbuild-cli/src/cli/args.rs
-crates/fbuild-cli/src/cli/debug.rs
-crates/fbuild-cli/src/cli/dispatch.rs
-crates/fbuild-cli/src/cli/ide.rs
-crates/fbuild-cli/src/cli/ide_debug.rs
-crates/fbuild-cli/src/cli/purge.rs
-crates/fbuild-cli/src/cli/symbols_cmd.rs
-crates/fbuild-cli/src/lib_select.rs
-crates/fbuild-cli/tests/daemon_crash_recovery.rs