feat(client): add Node addon and JS wrapper for runner IPC

Splits Step 4 of the runner-aware-tools plan: replaces the napi crate stub
with real module-level functions, adds the `@voidzero-dev/vite-task-client`
JS package that lazily loads the addon and falls back to no-ops outside a
`vp run` task, and renames the runner env vars to the `VP_RUN_` prefix
(`VITE_TASK_IPC_NAME` -> `VP_RUN_IPC_NAME`, new `VP_RUN_NODE_CLIENT_PATH`).

`vite_task_client::Client` now uses `&self` with `RefCell`s so the napi
layer can store it as per-env instance data without a Mutex. Adds an
end-to-end `#[ignore]` test driving the addon from Node against a live
`vite_task_server`.

Author: claude

Cargo.lock

@@ -1,4 +1,5 @@
 use std::{
+    cell::RefCell,
     ffi::OsStr,
     io::{self, Read, Write},
     sync::Arc,
@@ -8,11 +9,10 @@ use interprocess::local_socket::{Stream, prelude::*};
 use native_str::NativeStr;
 use vite_path::AbsolutePath;
 use vite_task_ipc_shared::{GetEnvResponse, IPC_ENV_NAME, Request};
-use wincode::{SchemaRead, config::DefaultConfig};
 
 pub struct Client {
-    stream: Stream,
-    scratch: Vec<u8>,
+    stream: RefCell<Stream>,
+    scratch: RefCell<Vec<u8>>,
 }
 
 impl Client {
@@ -31,7 +31,7 @@ impl Client {
         for (name, value) in envs {
             if name.as_ref() == IPC_ENV_NAME {
                 let stream = Stream::connect(resolve_name(value.as_ref())?)?;
-                return Ok(Some(Self { stream, scratch: Vec::new() }));
+                return Ok(Some(Self::from_stream(stream)));
             }
         }
         Ok(None)
@@ -44,15 +44,19 @@ impl Client {
     /// Returns an error if the connection cannot be established.
     pub fn from_name(name: &OsStr) -> io::Result<Self> {
         let stream = Stream::connect(resolve_name(name)?)?;
-        Ok(Self { stream, scratch: Vec::new() })
+        Ok(Self::from_stream(stream))
+    }
+
+    const fn from_stream(stream: Stream) -> Self {
+        Self { stream: RefCell::new(stream), scratch: RefCell::new(Vec::new()) }
     }
 
     /// `path` can be a file or a directory; for a directory, all files inside it are ignored.
     ///
     /// # Errors
     ///
     /// Returns an error if the request fails to send.
-    pub fn ignore_input(&mut self, path: &AbsolutePath) -> io::Result<()> {
+    pub fn ignore_input(&self, path: &AbsolutePath) -> io::Result<()> {
         let ns = path_to_native_str(path);
         self.send(&Request::IgnoreInput(&ns))
     }
@@ -62,15 +66,15 @@ impl Client {
     /// # Errors
     ///
     /// Returns an error if the request fails to send.
-    pub fn ignore_output(&mut self, path: &AbsolutePath) -> io::Result<()> {
+    pub fn ignore_output(&self, path: &AbsolutePath) -> io::Result<()> {
         let ns = path_to_native_str(path);
         self.send(&Request::IgnoreOutput(&ns))
     }
 
     /// # Errors
     ///
     /// Returns an error if the request fails to send.
-    pub fn disable_cache(&mut self) -> io::Result<()> {
+    pub fn disable_cache(&self) -> io::Result<()> {
         self.send(&Request::DisableCache)
     }
 
@@ -79,38 +83,42 @@ impl Client {
     ///
     /// # Errors
     ///
-    /// Returns an error if the request or response fails, or the response id mismatches.
-    pub fn get_env(&mut self, name: &OsStr, tracked: bool) -> io::Result<Option<Arc<OsStr>>> {
+    /// Returns an error if the request or response fails.
+    pub fn get_env(&self, name: &OsStr, tracked: bool) -> io::Result<Option<Arc<OsStr>>> {
         let name = Box::<NativeStr>::from(name);
 
         self.send(&Request::GetEnv { name: &name, tracked })?;
-        let get_env_response = self.recv::<GetEnvResponse>()?;
-
-        Ok(get_env_response
-            .env_value
-            .map(|env_value| Arc::<OsStr>::from(env_value.to_cow_os_str().as_ref())))
+        self.recv_with(|bytes| {
+            let response: GetEnvResponse<'_> = wincode::deserialize_exact(bytes)
+                .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))?;
+            Ok(response
+                .env_value
+                .map(|env_value| Arc::<OsStr>::from(env_value.to_cow_os_str().as_ref())))
+        })
     }
 
-    fn send(&mut self, request: &Request<'_>) -> io::Result<()> {
+    fn send(&self, request: &Request<'_>) -> io::Result<()> {
         let bytes = wincode::serialize(request)
             .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))?;
         let len = u32::try_from(bytes.len())
             .map_err(|_| io::Error::new(io::ErrorKind::InvalidData, "request too large"))?;
-        self.stream.write_all(&len.to_le_bytes())?;
-        self.stream.write_all(&bytes)?;
-        self.stream.flush()?;
+        let mut stream = self.stream.borrow_mut();
+        stream.write_all(&len.to_le_bytes())?;
+        stream.write_all(&bytes)?;
+        stream.flush()?;
         Ok(())
     }
 
-    fn recv<'a, T: SchemaRead<'a, DefaultConfig, Dst = T>>(&'a mut self) -> io::Result<T> {
+    fn recv_with<T>(&self, extract: impl FnOnce(&[u8]) -> io::Result<T>) -> io::Result<T> {
+        let mut stream = self.stream.borrow_mut();
+        let mut scratch = self.scratch.borrow_mut();
         let mut len_bytes = [0u8; 4];
-        self.stream.read_exact(&mut len_bytes)?;
+        stream.read_exact(&mut len_bytes)?;
         let len = u32::from_le_bytes(len_bytes) as usize;
-        self.scratch.clear();
-        self.scratch.resize(len, 0);
-        self.stream.read_exact(&mut self.scratch)?;
-        wincode::deserialize_exact(&self.scratch)
-            .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))
+        scratch.clear();
+        scratch.resize(len, 0);
+        stream.read_exact(&mut scratch)?;
+        extract(&scratch)
     }
 }
 

crates/vite_task_client/src/lib.rs

@@ -10,12 +10,19 @@ rust-version.workspace = true
 crate-type = ["cdylib"]
 
 [dependencies]
-napi = { workspace = true }
+napi = { workspace = true, features = ["napi6"] }
 napi-derive = { workspace = true }
+vite_path = { workspace = true }
+vite_str = { workspace = true }
 vite_task_client = { workspace = true }
 
 [build-dependencies]
 napi-build = { workspace = true }
 
+[dev-dependencies]
+rustc-hash = { workspace = true }
+tokio = { workspace = true, features = ["rt", "macros"] }
+vite_task_server = { workspace = true }
+
 [lints]
 workspace = true

crates/vite_task_client_napi/Cargo.toml

@@ -0,0 +1,3 @@
+# vite_task_client_napi
+
+Node addon that lets JS/TS tools running inside a `vp run` task talk to the runner over IPC via `vite_task_client`.

crates/vite_task_client_napi/README.md

@@ -1,8 +1,93 @@
-// NAPI bindings are implemented in step 4 of the runner-aware tools plan.
-// This stub exists to keep the crate compiling while the underlying
-// `vite_task_client` API is evolving.
+//! Node addon that exposes module-level functions for tools to talk to a
+//! `vp run` runner over IPC. Not intended to be published directly — the
+//! runner hands the compiled `.node` file to child processes via the
+//! `VP_RUN_NODE_CLIENT_PATH` env var, and the JS wrapper in
+//! `@voidzero-dev/vite-task-client` `require()`s it lazily.
+//!
+//! The module is loadable **only** inside a runner-spawned task: when
+//! module-init runs outside that context the registration fails, the JS
+//! `require()` throws, and the wrapper falls into no-op mode.
 
+// The napi boundary forces std `String` through function signatures; clippy's
+// blanket bans on disallowed types / needless-pass-by-value / missing Errors
+// sections are all about pure-Rust call sites and don't apply here (JS never
+// reads rustdoc).
+#![expect(
+    clippy::disallowed_types,
+    clippy::missing_errors_doc,
+    clippy::needless_pass_by_value,
+    reason = "napi bindings require owned std String at the JS boundary"
+)]
+
+use std::ffi::OsStr;
+
+use napi::{Env, Error, Result};
 use napi_derive::napi;
+use vite_path::AbsolutePath;
+use vite_task_client::Client;
+
+struct State {
+    client: Client,
+}
+
+#[napi(module_exports)]
+pub fn init(env: Env) -> Result<()> {
+    let client = Client::from_envs(std::env::vars_os())
+        .map_err(|err| {
+            err_string(vite_str::format!("vp run client: failed to connect to runner IPC: {err}"))
+        })?
+        .ok_or_else(|| {
+            err_static(
+                "vp run client: runner IPC env is not set; this module is only usable \
+                 inside a `vp run` task",
+            )
+        })?;
+    env.set_instance_data(State { client }, (), |_| {})?;
+    Ok(())
+}
+
+fn client(env: Env) -> Result<&'static Client> {
+    env.get_instance_data::<State>()?
+        .map(|state| &state.client as &Client)
+        .ok_or_else(|| err_static("vp run client: module state missing"))
+}
+
+fn err_static(msg: &'static str) -> Error {
+    Error::from_reason(msg)
+}
+
+fn err_string(msg: vite_str::Str) -> Error {
+    Error::from_reason(msg.as_str())
+}
+
+#[napi]
+pub fn ignore_input(env: Env, path: String) -> Result<()> {
+    let abs = AbsolutePath::new(&path)
+        .ok_or_else(|| err_string(vite_str::format!("path must be absolute: {path}")))?;
+    client(env)?.ignore_input(abs).map_err(|err| err_string(vite_str::format!("{err}")))
+}
+
+#[napi]
+pub fn ignore_output(env: Env, path: String) -> Result<()> {
+    let abs = AbsolutePath::new(&path)
+        .ok_or_else(|| err_string(vite_str::format!("path must be absolute: {path}")))?;
+    client(env)?.ignore_output(abs).map_err(|err| err_string(vite_str::format!("{err}")))
+}
+
+#[napi]
+pub fn disable_cache(env: Env) -> Result<()> {
+    client(env)?.disable_cache().map_err(|err| err_string(vite_str::format!("{err}")))
+}
 
 #[napi]
-pub const STUB: u32 = 0;
+pub fn get_env(env: Env, name: String, tracked: bool) -> Result<Option<String>> {
+    let value = client(env)?
+        .get_env(OsStr::new(&name), tracked)
+        .map_err(|err| err_string(vite_str::format!("{err}")))?;
+    value.map_or(Ok(None), |value| {
+        value
+            .to_str()
+            .map(|s| Some(s.to_owned()))
+            .ok_or_else(|| err_string(vite_str::format!("env value for {name} is not valid UTF-8")))
+    })
+}

crates/vite_task_client_napi/src/lib.rs

@@ -0,0 +1,95 @@
+//! End-to-end test for the node addon. Requires Node.js on PATH and the
+//! `@voidzero-dev/vite-task-client` JS package + the built `.node` addon
+//! on disk.
+//!
+//! Expected env vars:
+//! - `VP_RUN_NODE_CLIENT_ADDON_PATH`: absolute path to the built `.node` dylib
+//!   (e.g. `target/release/libvite_task_client_napi.so` copied or symlinked
+//!   as `.node`).
+//! - `VP_RUN_NODE_CLIENT_JS_PATH`: absolute path to
+//!   `packages/vite-task-client/index.js`.
+//!
+//! Both must be set or the test is silently skipped.
+
+use std::{
+    ffi::{OsStr, OsString},
+    process::Command,
+    sync::Arc,
+};
+
+use rustc_hash::FxHashMap;
+use tokio::runtime::Builder;
+use vite_task_server::{Recorder, ServerHandle, serve};
+
+#[test]
+#[ignore = "requires built .node addon and Node.js on PATH"]
+fn addon_round_trip() {
+    let addon_path = std::env::var_os("VP_RUN_NODE_CLIENT_ADDON_PATH")
+        .expect("VP_RUN_NODE_CLIENT_ADDON_PATH must point at the built .node addon");
+    let js_path = std::env::var_os("VP_RUN_NODE_CLIENT_JS_PATH")
+        .expect("VP_RUN_NODE_CLIENT_JS_PATH must point at packages/vite-task-client/index.js");
+
+    let mut envs: FxHashMap<Arc<OsStr>, Arc<OsStr>> = FxHashMap::default();
+    envs.insert(
+        Arc::<OsStr>::from(OsStr::new("NODE_ENV")),
+        Arc::<OsStr>::from(OsStr::new("production")),
+    );
+
+    let rt = Builder::new_current_thread().enable_all().build().unwrap();
+    let reports = rt.block_on(async move {
+        let recorder = Recorder::new(envs);
+        let (ipc_envs, ServerHandle { driver, stop_accepting }) =
+            serve(recorder).expect("bind server");
+        let (ipc_name, ipc_value) = ipc_envs.into_iter().next().expect("one IPC env");
+        let ipc_name: OsString = ipc_name.to_os_string();
+
+        let child = tokio::task::spawn_blocking(move || {
+            let js_path_str = js_path.to_str().expect("JS path is utf-8");
+            let script = vite_str::format!(
+                "\
+import({js_path_literal:?}).then(m => {{\n\
+  m.ignoreInput('/tmp/vp_run_test_in.txt');\n\
+  m.ignoreOutput('/tmp/vp_run_test_out.txt');\n\
+  m.disableCache();\n\
+  m.fetchEnv('NODE_ENV');\n\
+  if (process.env.NODE_ENV !== 'production') {{\n\
+    console.error('expected production, got ' + process.env.NODE_ENV);\n\
+    process.exit(1);\n\
+  }}\n\
+  m.fetchEnv('MISSING');\n\
+  if (process.env.MISSING !== undefined) {{\n\
+    console.error('MISSING should be undefined');\n\
+    process.exit(1);\n\
+  }}\n\
+}});\n",
+                js_path_literal = js_path_str
+            );
+            let status = Command::new("node")
+                .arg("--input-type=module")
+                .arg("-e")
+                .arg(script.as_str())
+                .env::<&OsStr, &OsStr>(&ipc_name, &ipc_value)
+                .env("VP_RUN_NODE_CLIENT_PATH", &addon_path)
+                .status()
+                .expect("spawn node");
+            stop_accepting.signal();
+            assert!(status.success(), "node exited with {status}");
+        });
+
+        let (recorder, child_result) = tokio::join!(driver, child);
+        child_result.expect("node runner panicked");
+        recorder.into_reports()
+    });
+
+    assert!(reports.cache_disabled, "disableCache should propagate");
+    assert_eq!(reports.ignored_inputs.len(), 1, "ignoreInput should record one path");
+    assert_eq!(reports.ignored_outputs.len(), 1, "ignoreOutput should record one path");
+
+    let node_env = reports.env_records.get(OsStr::new("NODE_ENV")).expect("NODE_ENV recorded");
+    assert!(node_env.tracked);
+    assert_eq!(node_env.value.as_deref(), Some(OsStr::new("production")));
+
+    let missing = reports.env_records.get(OsStr::new("MISSING")).expect("MISSING recorded");
+    assert!(missing.tracked);
+    assert!(missing.value.is_none());
+}

crates/vite_task_client_napi/tests/e2e.rs

@@ -1,7 +1,17 @@
 use native_str::NativeStr;
 use wincode::{SchemaRead, SchemaWrite};
 
-pub const IPC_ENV_NAME: &str = "VITE_TASK_IPC_NAME";
+pub const IPC_ENV_NAME: &str = "VP_RUN_IPC_NAME";
+
+/// Path to the Node client module that JS/TS tools `require()` to talk to
+/// the runner.
+///
+/// Implementation-detail leakage (`napi`, `.node`, `addon`) is intentionally
+/// kept out of the name: from the consumer's point of view this is just a
+/// path they can `require()`. The `NODE_` scope reserves room for a future
+/// C-ABI client library advertised via its own env var for non-Node
+/// consumers.
+pub const NODE_CLIENT_PATH_ENV_NAME: &str = "VP_RUN_NODE_CLIENT_PATH";
 
 #[derive(Debug, SchemaWrite, SchemaRead)]
 pub enum Request<'a> {