refactor(platform): migrate device consumers to neutral facade

ci/platform_boundary_ledger.tsv

@@ -22,32 +22,8 @@ crates/fbuild-config/src/bin/enrich_boards.rs	attr_cfg	#[cfg(windows)]	0	host	ho
 crates/fbuild-daemon/src/handlers/emulator/tests_npm_cache.rs	attr_cfg	#[cfg(windows)]	0	host_executable	host_artifact_policy
 crates/fbuild-daemon/src/handlers/emulator/tests_process.rs	attr_cfg	#[cfg(not(windows))]	0	host_executable	host_artifact_policy
 crates/fbuild-daemon/src/handlers/emulator/tests_process.rs	attr_cfg	#[cfg(windows)]	0	host_executable	host_artifact_policy
-crates/fbuild-deploy/src/lpc.rs	attr_cfg	#[cfg(not(target_os=))]	0	device	host_mechanic
-crates/fbuild-deploy/src/lpc.rs	attr_cfg	#[cfg(not(windows))]	0	device	host_mechanic
-crates/fbuild-deploy/src/lpc.rs	attr_cfg	#[cfg(target_os=)]	0	device	host_mechanic
-crates/fbuild-deploy/src/lpc.rs	attr_cfg	#[cfg(windows)]	0	device	host_mechanic
-crates/fbuild-deploy/src/lpc_debugger_reflash.rs	attr_cfg	#[cfg(target_os=)]	0	device	host_mechanic
-crates/fbuild-deploy/src/probe_rs.rs	attr_cfg	#[cfg(windows)]	0	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_mount.rs	attr_cfg	#[cfg(any(target_os=,test))]	0	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_mount.rs	attr_cfg	#[cfg(any(target_os=,test))]	1	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_mount.rs	attr_cfg	#[cfg(not(target_os=))]	0	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_mount.rs	attr_cfg	#[cfg(target_os=)]	0	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	attr_cfg	#[cfg(any(windows,test))]	0	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	attr_cfg	#[cfg(any(windows,test))]	1	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	attr_cfg	#[cfg(any(windows,test))]	2	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	attr_cfg	#[cfg(any(windows,test))]	3	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	attr_cfg	#[cfg(any(windows,test))]	4	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	attr_cfg	#[cfg(any(windows,test))]	5	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	attr_cfg	#[cfg(not(windows))]	0	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	attr_cfg	#[cfg(not(windows))]	1	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	attr_cfg	#[cfg(windows)]	0	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	attr_cfg	#[cfg(windows)]	1	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	native_path	std::os::windows::ffi::OsStrExt	0	device	host_mechanic
 crates/fbuild-library/src/library/library_spec.rs	attr_cfg	#[cfg(windows)]	0	host	host_mechanic
 crates/fbuild-paths/src/dev_daemon_namespace.rs	native_path	std::env::current_exe	0	host_executable	host_mechanic
-crates/fbuild-serial/src/ports.rs	attr_cfg	#[cfg(target_os=)]	0	device	host_mechanic
-crates/fbuild-serial/src/ports.rs	attr_cfg	#[cfg(target_os=)]	1	device	host_mechanic
-crates/fbuild-serial/src/ports.rs	attr_cfg	#[cfg(target_os=)]	2	device	host_mechanic
 crates/fbuild-toolchain/src/toolchain/esp_qemu.rs	attr_cfg	#[cfg(not(target_os=))]	0	host_executable	host_mechanic
 crates/fbuild-toolchain/src/toolchain/esp_qemu.rs	attr_cfg	#[cfg(not(windows))]	0	host_executable	host_mechanic
 crates/fbuild-toolchain/src/toolchain/esp_qemu.rs	attr_cfg	#[cfg(not(windows))]	1	host_executable	host_mechanic

ci/platform_boundary_research.tsv

@@ -37,7 +37,7 @@ crates/fbuild-core/src/platform/linux/ipc.rs	2	native_path	interprocess::local_s
 crates/fbuild-core/src/platform/linux/ipc.rs	3	native_path	interprocess::os::unix	ipc	host_mechanic
 crates/fbuild-core/src/platform/linux/ipc.rs	4	native_path	socket2::	ipc	host_mechanic
 crates/fbuild-core/src/platform/linux/ipc.rs	66	native_path	std::os::unix::fs::PermissionsExt	ipc	host_mechanic
-crates/fbuild-core/src/platform/linux/mod.rs	12	compile_host_fact	std::env::consts::ARCH	host	host_mechanic
+crates/fbuild-core/src/platform/linux/mod.rs	13	compile_host_fact	std::env::consts::ARCH	host	host_mechanic
 crates/fbuild-core/src/platform/linux/process.rs	1	native_path	std::os::unix::process::ExitStatusExt	process	host_mechanic
 crates/fbuild-core/src/platform/macos/fs.rs	2	native_path	std::os::unix::fs::PermissionsExt	fs	host_mechanic
 crates/fbuild-core/src/platform/macos/fs.rs	40	native_path	std::os::unix::fs::symlink	fs	host_mechanic
@@ -50,13 +50,13 @@ crates/fbuild-core/src/platform/macos/ipc.rs	2	native_path	interprocess::local_s
 crates/fbuild-core/src/platform/macos/ipc.rs	3	native_path	socket2::	ipc	host_mechanic
 crates/fbuild-core/src/platform/macos/ipc.rs	19	native_path	std::os::unix::fs::PermissionsExt	ipc	host_mechanic
 crates/fbuild-core/src/platform/macos/ipc.rs	72	native_path	std::os::unix::fs::PermissionsExt	ipc	host_mechanic
-crates/fbuild-core/src/platform/macos/mod.rs	12	compile_host_fact	std::env::consts::ARCH	host	host_mechanic
+crates/fbuild-core/src/platform/macos/mod.rs	13	compile_host_fact	std::env::consts::ARCH	host	host_mechanic
 crates/fbuild-core/src/platform/macos/process.rs	1	native_path	std::os::unix::process::ExitStatusExt	process	host_mechanic
 crates/fbuild-core/src/platform/windows/device.rs	18	native_path	windows_sys::	process	host_mechanic
-crates/fbuild-core/src/platform/windows/device.rs	26	native_path	windows_sys::	process	host_mechanic
-crates/fbuild-core/src/platform/windows/device.rs	29	native_path	windows_sys::	process	host_mechanic
+crates/fbuild-core/src/platform/windows/device.rs	27	native_path	windows_sys::	process	host_mechanic
 crates/fbuild-core/src/platform/windows/device.rs	30	native_path	windows_sys::	process	host_mechanic
-crates/fbuild-core/src/platform/windows/device.rs	34	native_path	windows_sys::	process	host_mechanic
+crates/fbuild-core/src/platform/windows/device.rs	31	native_path	windows_sys::	process	host_mechanic
+crates/fbuild-core/src/platform/windows/device.rs	35	native_path	windows_sys::	process	host_mechanic
 crates/fbuild-core/src/platform/windows/fs.rs	2	native_path	std::os::windows::ffi::OsStrExt	process	host_mechanic
 crates/fbuild-core/src/platform/windows/fs.rs	3	native_path	std::os::windows::fs	fs	host_mechanic
 crates/fbuild-core/src/platform/windows/fs.rs	4	native_path	std::os::windows::io::AsRawHandle	process	host_mechanic
@@ -70,7 +70,7 @@ crates/fbuild-core/src/platform/windows/ipc.rs	3	native_path	interprocess::os::w
 crates/fbuild-core/src/platform/windows/ipc.rs	4	native_path	interprocess::os::windows	ipc	host_mechanic
 crates/fbuild-core/src/platform/windows/ipc.rs	5	native_path	socket2::	ipc	host_mechanic
 crates/fbuild-core/src/platform/windows/ipc.rs	6	native_path	std::os::windows::io::AsRawSocket	ipc	host_mechanic
-crates/fbuild-core/src/platform/windows/mod.rs	12	compile_host_fact	std::env::consts::ARCH	host	host_mechanic
+crates/fbuild-core/src/platform/windows/mod.rs	13	compile_host_fact	std::env::consts::ARCH	host	host_mechanic
 crates/fbuild-core/src/platform/windows/process.rs	1	native_path	std::os::windows::io::AsHandle	process	host_mechanic
 crates/fbuild-core/src/platform/windows/usb_pnp.rs	13	native_path	windows_sys::	process	host_mechanic
 crates/fbuild-core/src/platform/windows/usb_pnp.rs	24	native_path	windows_sys::	process	host_mechanic
@@ -82,32 +82,8 @@ crates/fbuild-core/src/platform/windows/usb_pnp.rs	40	native_path	windows_sys::
 crates/fbuild-daemon/src/handlers/emulator/tests_npm_cache.rs	146	attr_cfg	#[cfg(windows)]	host_executable	host_artifact_policy
 crates/fbuild-daemon/src/handlers/emulator/tests_process.rs	9	attr_cfg	#[cfg(windows)]	host_executable	host_artifact_policy
 crates/fbuild-daemon/src/handlers/emulator/tests_process.rs	21	attr_cfg	#[cfg(not(windows))]	host_executable	host_artifact_policy
-crates/fbuild-deploy/src/lpc.rs	27	attr_cfg	#[cfg(target_os=)]	device	host_mechanic
-crates/fbuild-deploy/src/lpc.rs	31	attr_cfg	#[cfg(not(target_os=))]	device	host_mechanic
-crates/fbuild-deploy/src/lpc.rs	972	attr_cfg	#[cfg(windows)]	device	host_mechanic
-crates/fbuild-deploy/src/lpc.rs	987	attr_cfg	#[cfg(not(windows))]	device	host_mechanic
-crates/fbuild-deploy/src/lpc_debugger_reflash.rs	294	attr_cfg	#[cfg(target_os=)]	device	host_mechanic
-crates/fbuild-deploy/src/probe_rs.rs	508	attr_cfg	#[cfg(windows)]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_mount.rs	3	attr_cfg	#[cfg(any(target_os=,test))]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_mount.rs	6	attr_cfg	#[cfg(any(target_os=,test))]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_mount.rs	23	attr_cfg	#[cfg(target_os=)]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_mount.rs	53	attr_cfg	#[cfg(not(target_os=))]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	6	attr_cfg	#[cfg(windows)]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	11	attr_cfg	#[cfg(not(windows))]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	20	attr_cfg	#[cfg(any(windows,test))]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	31	attr_cfg	#[cfg(any(windows,test))]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	71	attr_cfg	#[cfg(any(windows,test))]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	81	attr_cfg	#[cfg(any(windows,test))]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	88	attr_cfg	#[cfg(any(windows,test))]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	99	attr_cfg	#[cfg(any(windows,test))]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	119	attr_cfg	#[cfg(windows)]	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	123	native_path	std::os::windows::ffi::OsStrExt	device	host_mechanic
-crates/fbuild-deploy/src/rp2040_topology.rs	506	attr_cfg	#[cfg(not(windows))]	device	host_mechanic
 crates/fbuild-library/src/library/library_spec.rs	266	attr_cfg	#[cfg(windows)]	host	host_mechanic
 crates/fbuild-paths/src/dev_daemon_namespace.rs	83	native_path	std::env::current_exe	host_executable	host_mechanic
-crates/fbuild-serial/src/ports.rs	222	attr_cfg	#[cfg(target_os=)]	device	host_mechanic
-crates/fbuild-serial/src/ports.rs	234	attr_cfg	#[cfg(target_os=)]	device	host_mechanic
-crates/fbuild-serial/src/ports.rs	291	attr_cfg	#[cfg(target_os=)]	device	host_mechanic
 crates/fbuild-toolchain/src/toolchain/esp_qemu.rs	220	attr_cfg	#[cfg(not(target_os=))]	host_executable	host_mechanic
 crates/fbuild-toolchain/src/toolchain/esp_qemu.rs	226	attr_cfg	#[cfg(target_os=)]	host_executable	host_mechanic
 crates/fbuild-toolchain/src/toolchain/esp_qemu.rs	576	attr_cfg	#[cfg(windows)]	host_executable	host_mechanic

ci/test_enforce_platform_boundary.py

@@ -14,7 +14,10 @@ def setUpClass(cls) -> None:
         cls.observed = boundary.rows_from_findings(boundary.research.inventory())
 
     def test_committed_exact_occurrence_ledger_matches_whole_tree(self) -> None:
-        self.assertEqual(len(self.expected), 57)
+        # Phase 8a (FastLED/fbuild#1314): the 24 `device`-namespace rows
+        # migrated behind the platform facade are gone; what remains is
+        # fs/ipc/host/process/host_executable work for later phases.
+        self.assertEqual(len(self.expected), 33)
         self.assertFalse(boundary.validate_ledger(self.expected))
         self.assertFalse(boundary.compare(self.expected, self.observed))
 

crates/fbuild-core/src/platform/device.rs

@@ -82,6 +82,10 @@ pub struct SerialPortFacts {
     /// Physical USB location paths. Empty when unavailable. These are
     /// identity history only and never make a phantom endpoint selectable.
     pub location_paths: Vec<String>,
+    /// The host's short human location string for the devnode (Windows
+    /// `SPDRP_LOCATION_INFORMATION`, e.g. `Port_#0003.Hub_#0004`).
+    /// `None` where the host has no equivalent.
+    pub location_information: Option<String>,
 }
 
 /// Map a portable `serialport` enumeration entry onto neutral facts.
@@ -115,6 +119,7 @@ pub fn facts_from_port_info(info: serialport::SerialPortInfo) -> SerialPortFacts
         parent_instance_id: None,
         ancestor_instance_ids: Vec::new(),
         location_paths: Vec::new(),
+        location_information: None,
     }
 }
 
@@ -256,6 +261,15 @@ pub fn is_picotool_reset_compatible_id(value: &str) -> bool {
     value.eq_ignore_ascii_case("USB\\Class_ff&SubClass_00&Prot_01")
 }
 
+/// Best-effort mount of USB mass-storage block-device paths discovered by
+/// the caller (Linux: `udisksctl mount --block-device`, one attempt per
+/// path, 5 s timeout each; diagnostics logged, failures never fatal). A
+/// no-op on hosts without a supported auto-mount mechanic — callers keep
+/// their own scan/policy and derive behavior from their own enumeration.
+pub fn mount_block_devices(device_paths: &[&str]) {
+    super::selected::device::mount_block_devices(device_paths);
+}
+
 /// Number of bounded post-operation observations the host backend wants.
 /// Fakes stay instant; real backends wait between observations for
 /// re-enumeration to settle.

crates/fbuild-core/src/platform/host.rs

@@ -1,4 +1,7 @@
 //! Neutral host identity and runtime facts.
+//!
+//! Host-filesystem mechanics (e.g. the home directory) live in the
+//! per-OS `selected::host` tree; this module exposes the neutral API.
 
 /// Operating systems supported by the fbuild executable.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
@@ -124,6 +127,17 @@ pub fn path_list_separator_str() -> &'static str {
     current().path_list_separator_str()
 }
 
+/// The current user's home directory: `%USERPROFILE%` on Windows (with a
+/// `%HOME%` fallback for POSIX-style shells), `$HOME` elsewhere.
+///
+/// Callers keep their own policy for what to do when the variable is
+/// unset — the facade only reports the fact. Returned as a
+/// [`NormalizedPath`](crate::path::NormalizedPath), matching the other
+/// neutral facades that hand out paths.
+pub fn home_dir() -> Option<crate::path::NormalizedPath> {
+    super::selected::host::home_dir()
+}
+
 #[cfg(test)]
 mod tests {
     use super::{HostArch, HostOs, HostPlatform};

crates/fbuild-core/src/platform/linux/device.rs

@@ -33,6 +33,32 @@ pub(crate) fn live_sysfs_usb_root() -> Option<NormalizedPath> {
     Some(NormalizedPath::from(SYSFS_USB_ROOT))
 }
 
+pub(crate) fn mount_block_devices(device_paths: &[&str]) {
+    for device in device_paths {
+        let args = ["udisksctl", "mount", "--block-device", device];
+        match crate::subprocess::run_command_blocking(
+            &args,
+            None,
+            None,
+            Some(std::time::Duration::from_secs(5)),
+        ) {
+            Ok(output) if output.success() => {
+                tracing::debug!(device, "mounted RP-series ROM volume with udisksctl");
+            }
+            Ok(output) => {
+                tracing::debug!(
+                    device,
+                    stderr = output.stderr.trim(),
+                    "udisksctl could not mount RP-series ROM volume"
+                );
+            }
+            Err(error) => {
+                tracing::debug!(device, error = %error, "RP-series ROM auto-mount unavailable");
+            }
+        }
+    }
+}
+
 /// Linux implementation, factored on `sysfs_root` so unit tests can
 /// point at a temp dir holding a fake sysfs.
 pub(crate) fn detect_with_sysfs_root(

crates/fbuild-core/src/platform/linux/host.rs

@@ -0,0 +1,8 @@
+//! Selected Linux host mechanics behind [`crate::platform::host`].
+
+use crate::path::NormalizedPath;
+
+/// `$HOME`.
+pub(crate) fn home_dir() -> Option<NormalizedPath> {
+    std::env::var_os("HOME").map(NormalizedPath::new)
+}

crates/fbuild-core/src/platform/linux/mod.rs

@@ -2,6 +2,7 @@ use super::host::{HostArch, HostOs};
 
 pub(super) mod device;
 pub(super) mod fs;
+pub(super) mod host;
 pub(super) mod ipc;
 pub(super) mod process;
 pub(super) mod usb_pnp;

crates/fbuild-core/src/platform/macos/device.rs

@@ -28,6 +28,11 @@ pub(crate) fn live_sysfs_usb_root() -> Option<crate::path::NormalizedPath> {
     None
 }
 
+pub(crate) fn mount_block_devices(_device_paths: &[&str]) {
+    // No fbuild-supported auto-mount mechanic on macOS: macOS auto-mounts
+    // USB mass-storage volumes itself.
+}
+
 /// Classify a macOS serial devnode from its device-node name.
 ///
 /// Any name we don't recognize returns `None` so the caller falls back

crates/fbuild-core/src/platform/macos/host.rs

@@ -0,0 +1,8 @@
+//! Selected macOS host mechanics behind [`crate::platform::host`].
+
+use crate::path::NormalizedPath;
+
+/// `$HOME`.
+pub(crate) fn home_dir() -> Option<NormalizedPath> {
+    std::env::var_os("HOME").map(NormalizedPath::new)
+}

crates/fbuild-core/src/platform/macos/mod.rs

@@ -2,6 +2,7 @@ use super::host::{HostArch, HostOs};
 
 pub(super) mod device;
 pub(super) mod fs;
+pub(super) mod host;
 pub(super) mod ipc;
 pub(super) mod process;
 pub(super) mod usb_pnp;

crates/fbuild-core/src/platform/windows/device.rs

@@ -18,7 +18,8 @@ use std::ptr;
 use windows_sys::Win32::Devices::DeviceAndDriverInstallation::{
     CM_Get_DevNode_Status, CM_Get_Device_IDW, CM_Get_Parent, CR_NO_SUCH_DEVINST, CR_SUCCESS,
     DICS_FLAG_GLOBAL, DIREG_DEV, HDEVINFO, MAX_DEVICE_ID_LEN, SP_DEVINFO_DATA,
-    SPDRP_FRIENDLYNAME, SPDRP_HARDWAREID, SPDRP_MFG, SetupDiClassGuidsFromNameW,
+    SPDRP_FRIENDLYNAME, SPDRP_HARDWAREID, SPDRP_LOCATION_INFORMATION, SPDRP_MFG,
+    SetupDiClassGuidsFromNameW,
     SetupDiDestroyDeviceInfoList, SetupDiEnumDeviceInfo, SetupDiGetClassDevsW,
     SetupDiGetDeviceInstanceIdW, SetupDiGetDevicePropertyW, SetupDiGetDeviceRegistryPropertyW,
     SetupDiOpenDevRegKey,
@@ -60,6 +61,7 @@ pub(crate) fn available_serial_ports() -> io::Result<Vec<SerialPortFacts>> {
             let parent_instance_id = port_device.parent_instance_id();
             let ancestor_instance_ids = ancestor_ids(port_device.devinfo_data.DevInst);
             let observation = port_device.pnp_observation();
+            let location_information = port_device.property(SPDRP_LOCATION_INFORMATION);
             let port_type =
                 port_device.port_type(instance_id.as_deref(), parent_instance_id.as_deref());
             let is_usb = matches!(port_type, SerialPortTypeFacts::Usb(_));
@@ -88,6 +90,7 @@ pub(crate) fn available_serial_ports() -> io::Result<Vec<SerialPortFacts>> {
                     port_device.hdi,
                     &port_device.devinfo_data,
                 ),
+                location_information,
             });
         }
     }
@@ -103,6 +106,7 @@ pub(crate) fn available_serial_ports() -> io::Result<Vec<SerialPortFacts>> {
                 parent_instance_id: None,
                 ancestor_instance_ids: Vec::new(),
                 location_paths: Vec::new(),
+                location_information: None,
             });
         }
     }
@@ -120,6 +124,11 @@ pub(crate) fn live_sysfs_usb_root() -> Option<NormalizedPath> {
     None
 }
 
+pub(crate) fn mount_block_devices(_device_paths: &[&str]) {
+    // No fbuild-supported auto-mount mechanic on Windows: the RP-series
+    // ROM volume auto-assigns a drive letter without help.
+}
+
 pub(super) fn as_utf16(utf8: &str) -> Vec<u16> {
     utf8.encode_utf16().chain(Some(0)).collect()
 }

crates/fbuild-core/src/platform/windows/host.rs

@@ -0,0 +1,11 @@
+//! Selected Windows host mechanics behind [`crate::platform::host`].
+
+use crate::path::NormalizedPath;
+
+/// `%USERPROFILE%`, falling back to `%HOME%` for environments (MSYS,
+/// cross-toolchain shells) that export only the POSIX variable.
+pub(crate) fn home_dir() -> Option<NormalizedPath> {
+    std::env::var_os("USERPROFILE")
+        .or_else(|| std::env::var_os("HOME"))
+        .map(NormalizedPath::new)
+}

crates/fbuild-core/src/platform/windows/mod.rs

@@ -2,6 +2,7 @@ use super::host::{HostArch, HostOs};
 
 pub(super) mod device;
 pub(super) mod fs;
+pub(super) mod host;
 pub(super) mod ipc;
 pub(super) mod process;
 pub(super) mod usb_pnp;