feat: add musl target support (#273)

## Summary

- Always use seccomp in fspy to infer inputs
- Add a dedicated `test-musl` CI job that runs the full test suite
against `x86_64-unknown-linux-musl`

https://claude.ai/code/session_01Cqj3gbQjb7yFe49f1tfwYv

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: branchseer

.cargo/config.toml

@@ -4,8 +4,8 @@ rustflags = ["--cfg", "tokio_unstable", "-D", "warnings"]
 [unstable]
 bindeps = true
 
-# Linker wrappers for cross-compiling bindep targets (fspy_test_bin) via cargo-zigbuild.
-# On native Linux the system linker can handle musl targets; these are needed on non-Linux hosts.
+# Linker wrappers for musl targets. On Linux hosts these use the system cc directly;
+# on non-Linux hosts (macOS, Windows) they cross-compile via cargo-zigbuild.
 [target.x86_64-unknown-linux-musl]
 rustflags = ["-C", "linker=.cargo/zigcc-x86_64-unknown-linux-musl"]
 

.cargo/zigcc-aarch64-unknown-linux-musl

@@ -1,2 +1,7 @@
 #!/bin/sh
+# Linker wrapper for aarch64-unknown-linux-musl targets.
+# On Linux, use the system cc directly. On other hosts, cross-compile via cargo-zigbuild.
+if [ "$(uname -s)" = "Linux" ]; then
+  exec cc "$@"
+fi
 exec cargo-zigbuild zig cc -- -fno-sanitize=all -target aarch64-linux-musl "$@"

.cargo/zigcc-x86_64-unknown-linux-musl

@@ -1,2 +1,7 @@
 #!/bin/sh
+# Linker wrapper for x86_64-unknown-linux-musl targets.
+# On Linux, use the system cc directly. On other hosts, cross-compile via cargo-zigbuild.
+if [ "$(uname -s)" = "Linux" ]; then
+  exec cc "$@"
+fi
 exec cargo-zigbuild zig cc -- -fno-sanitize=all -target x86_64-linux-musl "$@"

.github/workflows/ci.yml

@@ -133,6 +133,44 @@ jobs:
       - run: cargo-zigbuild test --target x86_64-unknown-linux-gnu.2.17
         if: ${{ matrix.os == 'ubuntu-latest' }}
 
+  test-musl:
+    needs: detect-changes
+    if: needs.detect-changes.outputs.code-changed == 'true'
+    name: Test (musl)
+    runs-on: ubuntu-latest
+    container:
+      image: node:22-alpine3.21
+      options: --shm-size=256m # shm_io tests need bigger shared memory
+    env:
+      # Override all rustflags to skip the zig cross-linker from .cargo/config.toml.
+      # Alpine's cc is already musl-native, so no custom linker is needed.
+      # Must mirror [build].rustflags from .cargo/config.toml.
+      RUSTFLAGS: --cfg tokio_unstable -D warnings
+    steps:
+      - name: Install Alpine dependencies
+        shell: sh {0}
+        run: apk add --no-cache bash curl git musl-dev gcc g++ python3
+
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+          submodules: true
+
+      - name: Install rustup
+        run: |
+          curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --default-toolchain none
+          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+
+      - name: Install Rust toolchain
+        run: rustup show
+
+      - name: Install pnpm and Node tools
+        run: |
+          corepack enable
+          pnpm install
+
+      - run: cargo test
+
   fmt:
     name: Format and Check Deps
     runs-on: ubuntu-latest
@@ -168,6 +206,7 @@ jobs:
     needs:
       - clippy
       - test
+      - test-musl
       - fmt
     steps:
       - run: exit 1

crates/fspy/Cargo.toml

@@ -28,8 +28,10 @@ fspy_seccomp_unotify = { workspace = true, features = ["supervisor"] }
 nix = { workspace = true, features = ["uio"] }
 tokio = { workspace = true, features = ["bytes"] }
 
-[target.'cfg(unix)'.dependencies]
+[target.'cfg(all(unix, not(target_env = "musl")))'.dependencies]
 fspy_preload_unix = { workspace = true }
+
+[target.'cfg(unix)'.dependencies]
 fspy_shared_unix = { workspace = true }
 nix = { workspace = true, features = ["fs", "process", "socket", "feature"] }
 

crates/fspy/README.md

@@ -2,7 +2,7 @@
 
 Run a command and capture all the paths it tries to access.
 
-## macOS/Linux implementation
+## macOS/Linux (glibc) implementation
 
 It uses `DYLD_INSERT_LIBRARIES` on macOS and `LD_PRELOAD` on Linux to inject a shared library that intercepts file system calls.
 The injection process is almost identical on both platforms other than the environment variable name. The implementation is in `src/unix`.
@@ -11,6 +11,10 @@ The injection process is almost identical on both platforms other than the envir
 
 For fully static binaries (such as `esbuild`), `LD_PRELOAD` does not work. In this case, `seccomp_unotify` is used to intercept direct system calls. The handler is implemented in `src/unix/syscall_handler`.
 
+## Linux musl implementation
+
+On musl targets, only `seccomp_unotify`-based tracking is used (no preload library).
+
 ## Windows implementation
 
 It uses [Detours](https://github.com/microsoft/Detours) to intercept file system calls. The implementation is in `src/windows`.

crates/fspy/src/lib.rs

@@ -2,6 +2,8 @@
 #![feature(once_cell_try)]
 
 // Persist the injected DLL/shared library somewhere in the filesystem.
+// Not needed on musl (seccomp-only tracking).
+#[cfg(not(target_env = "musl"))]
 mod artifact;
 
 pub mod error;

crates/fspy/src/unix/mod.rs

@@ -8,7 +8,9 @@ use std::{io, path::Path};
 
 #[cfg(target_os = "linux")]
 use fspy_seccomp_unotify::supervisor::supervise;
-use fspy_shared::ipc::{NativeStr, PathAccess, channel::channel};
+#[cfg(not(target_env = "musl"))]
+use fspy_shared::ipc::NativeStr;
+use fspy_shared::ipc::{PathAccess, channel::channel};
 #[cfg(target_os = "macos")]
 use fspy_shared_unix::payload::Artifacts;
 use fspy_shared_unix::{
@@ -33,28 +35,39 @@ pub struct SpyImpl {
     #[cfg(target_os = "macos")]
     artifacts: Artifacts,
 
+    #[cfg(not(target_env = "musl"))]
     preload_path: Box<NativeStr>,
 }
 
+#[cfg(not(target_env = "musl"))]
 const PRELOAD_CDYLIB_BINARY: &[u8] = include_bytes!(env!("CARGO_CDYLIB_FILE_FSPY_PRELOAD_UNIX"));
 
 impl SpyImpl {
-    /// Initialize the fs access spy by writing the preload library on disk
-    pub fn init_in(dir: &Path) -> io::Result<Self> {
-        use const_format::formatcp;
-        use xxhash_rust::const_xxh3::xxh3_128;
-
-        use crate::artifact::Artifact;
-
-        const PRELOAD_CDYLIB: Artifact = Artifact {
-            name: "fspy_preload",
-            content: PRELOAD_CDYLIB_BINARY,
-            hash: formatcp!("{:x}", xxh3_128(PRELOAD_CDYLIB_BINARY)),
+    /// Initialize the fs access spy by writing the preload library on disk.
+    ///
+    /// On musl targets, we don't build a preload library —
+    /// only seccomp-based tracking is used.
+    pub fn init_in(#[cfg_attr(target_env = "musl", allow(unused))] dir: &Path) -> io::Result<Self> {
+        #[cfg(not(target_env = "musl"))]
+        let preload_path = {
+            use const_format::formatcp;
+            use xxhash_rust::const_xxh3::xxh3_128;
+
+            use crate::artifact::Artifact;
+
+            const PRELOAD_CDYLIB: Artifact = Artifact {
+                name: "fspy_preload",
+                content: PRELOAD_CDYLIB_BINARY,
+                hash: formatcp!("{:x}", xxh3_128(PRELOAD_CDYLIB_BINARY)),
+            };
+
+            let preload_cdylib_path = PRELOAD_CDYLIB.write_to(dir, ".dylib")?;
+            preload_cdylib_path.as_path().into()
         };
 
-        let preload_cdylib_path = PRELOAD_CDYLIB.write_to(dir, ".dylib")?;
         Ok(Self {
-            preload_path: preload_cdylib_path.as_path().into(),
+            #[cfg(not(target_env = "musl"))]
+            preload_path,
             #[cfg(target_os = "macos")]
             artifacts: {
                 let coreutils_path = macos_artifacts::COREUTILS_BINARY.write_to(dir, "")?;
@@ -80,6 +93,7 @@ impl SpyImpl {
             #[cfg(target_os = "macos")]
             artifacts: self.artifacts.clone(),
 
+            #[cfg(not(target_env = "musl"))]
             preload_path: self.preload_path.clone(),
 
             #[cfg(target_os = "linux")]

crates/fspy/src/unix/syscall_handler/mod.rs

@@ -92,6 +92,11 @@ impl_handler!(
     #[cfg(target_arch = "x86_64")] lstat,
     #[cfg(target_arch = "x86_64")] newfstatat,
     #[cfg(target_arch = "aarch64")] fstatat,
+    statx,
+
+    #[cfg(target_arch = "x86_64")] access,
+    faccessat,
+    faccessat2,
 
     execve,
     execveat,

crates/fspy/src/unix/syscall_handler/stat.rs

@@ -32,4 +32,37 @@ impl SyscallHandler {
     ) -> io::Result<()> {
         self.handle_open(caller, dir_fd, path_ptr, libc::O_RDONLY)
     }
+
+    /// statx(2) — modern replacement for stat/fstatat used by newer glibc.
+    pub(super) fn statx(
+        &mut self,
+        caller: Caller,
+        (dir_fd, path_ptr): (Fd, CStrPtr),
+    ) -> io::Result<()> {
+        self.handle_open(caller, dir_fd, path_ptr, libc::O_RDONLY)
+    }
+
+    /// access(2) — check file accessibility (e.g. existsSync in Node.js).
+    #[cfg(target_arch = "x86_64")]
+    pub(super) fn access(&mut self, caller: Caller, (path,): (CStrPtr,)) -> io::Result<()> {
+        self.handle_open(caller, Fd::cwd(), path, libc::O_RDONLY)
+    }
+
+    /// faccessat(2) — check file accessibility relative to directory fd.
+    pub(super) fn faccessat(
+        &mut self,
+        caller: Caller,
+        (dir_fd, path_ptr): (Fd, CStrPtr),
+    ) -> io::Result<()> {
+        self.handle_open(caller, dir_fd, path_ptr, libc::O_RDONLY)
+    }
+
+    /// faccessat2(2) — extended faccessat with flags parameter.
+    pub(super) fn faccessat2(
+        &mut self,
+        caller: Caller,
+        (dir_fd, path_ptr): (Fd, CStrPtr),
+    ) -> io::Result<()> {
+        self.handle_open(caller, dir_fd, path_ptr, libc::O_RDONLY)
+    }
 }