refactor(ipc): hide env-name detail; serve returns envs iterator

- Add `IPC_ENV_NAME` constant in `vite_task_ipc_shared` as the single
  source of truth for the IPC env var name (shared between server and
  client, not exposed to callers).
- `serve()` now returns `impl Iterator<Item = (&'static OsStr, OsString)>`
  instead of a bare `OsString` name. Callers chain the iterator directly
  into spawn's envs without knowing the env var name.
- `Client::from_env()` → `from_envs(envs)`: takes an env-pair iterator,
  scans for the IPC env. Symmetric with server output.
- Unify temp socket prefix to `vite_task_ipc_` on both platforms.
- Drop lingering `VP_RUN_IPC` / `VP_RUN_CLIENT_NAPI` references from docs;
  the env var names are now internal to server/client crates.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: wan9chi

crates/vite_task_client/src/lib.rs

@@ -1,15 +1,12 @@
 use std::{
-    env,
     ffi::{OsStr, OsString},
     io::{self, Read, Write},
 };
 
 use interprocess::local_socket::{Stream, prelude::*};
 use native_str::NativeStr;
 use vite_path::AbsolutePath;
-use vite_task_ipc_shared::{Request, Response, ResponseBody};
-
-const IPC_ENV: &str = "VP_RUN_IPC";
+use vite_task_ipc_shared::{IPC_ENV_NAME, Request, Response, ResponseBody};
 
 pub struct Client {
     stream: Stream,
@@ -18,14 +15,25 @@ pub struct Client {
 }
 
 impl Client {
-    /// `Ok(None)` if `VP_RUN_IPC` is not set (running outside the runner).
+    /// Scans `envs` for the runner's IPC connection info and connects if
+    /// present. Typical callers pass `std::env::vars_os()`.
+    ///
+    /// Returns `Ok(None)` if the IPC env is absent (running outside the runner).
     /// `Err(..)` if the env is set but connecting fails.
     ///
     /// # Errors
     ///
     /// Returns an error if the env var is set but the server cannot be reached.
-    pub fn from_env() -> io::Result<Option<Self>> {
-        env::var_os(IPC_ENV).map_or_else(|| Ok(None), |name| Self::from_name(&name).map(Some))
+    pub fn from_envs(
+        envs: impl Iterator<Item = (impl AsRef<OsStr>, impl AsRef<OsStr>)>,
+    ) -> io::Result<Option<Self>> {
+        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, next_id: 0, scratch: Vec::new() }));
+            }
+        }
+        Ok(None)
     }
 
     /// Connects to a server at the given socket path (Unix) or pipe name (Windows).

crates/vite_task_ipc_shared/src/lib.rs

@@ -1,6 +1,8 @@
 use native_str::NativeStr;
 use wincode::{SchemaRead, SchemaWrite};
 
+pub const IPC_ENV_NAME: &str = "VITE_TASK_IPC_NAME";
+
 #[derive(Debug, SchemaWrite, SchemaRead)]
 pub enum Request<'a> {
     IgnoreInput(&'a NativeStr),

crates/vite_task_server/src/lib.rs

@@ -13,7 +13,7 @@ use native_str::NativeStr;
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 use tokio_util::sync::CancellationToken;
 use vite_path::AbsolutePath;
-use vite_task_ipc_shared::{Request, Response, ResponseBody};
+use vite_task_ipc_shared::{IPC_ENV_NAME, Request, Response, ResponseBody};
 
 pub trait Handler {
     fn ignore_input(&self, path: &Arc<AbsolutePath>);
@@ -50,15 +50,17 @@ impl StopAccepting {
 
 /// Starts an IPC server.
 ///
-/// Returns the socket path / pipe name (for `VP_RUN_IPC`) plus a handle
-/// bundling the driver future and the `StopAccepting` signal. See
-/// [`ServerHandle`] for driver semantics.
+/// Returns the env entries that a child process must inherit to find and
+/// connect to this server, plus a handle bundling the driver future and the
+/// `StopAccepting` signal. See [`ServerHandle`] for driver semantics.
 ///
 /// # Errors
 ///
 /// Returns an error if creating the listener fails (on Unix, this includes
 /// creating the temp socket path).
-pub fn serve<'h, H: Handler + 'h>(handler: H) -> io::Result<(OsString, ServerHandle<'h, H>)> {
+pub fn serve<'h, H: Handler + 'h>(
+    handler: H,
+) -> io::Result<(impl Iterator<Item = (&'static OsStr, OsString)>, ServerHandle<'h, H>)> {
     let stop_token = CancellationToken::new();
     let (name, bound) = bind_listener()?;
 
@@ -69,7 +71,10 @@ pub fn serve<'h, H: Handler + 'h>(handler: H) -> io::Result<(OsString, ServerHan
     }
     .boxed_local();
 
-    Ok((name, ServerHandle { driver, stop_accepting: StopAccepting { token: stop_token } }))
+    Ok((
+        std::iter::once((OsStr::new(IPC_ENV_NAME), name)),
+        ServerHandle { driver, stop_accepting: StopAccepting { token: stop_token } },
+    ))
 }
 
 #[cfg(unix)]
@@ -81,7 +86,7 @@ type Bound = Listener;
 fn bind_listener() -> io::Result<(OsString, Bound)> {
     use interprocess::local_socket::{GenericFilePath, ToFsName};
 
-    let bound = tempfile::Builder::new().prefix("vp_run_ipc_").make(|path| {
+    let bound = tempfile::Builder::new().prefix("vite_task_ipc_").make(|path| {
         let name = path.to_fs_name::<GenericFilePath>()?;
         ListenerOptions::new().name(name).create_tokio()
     })?;
@@ -93,7 +98,7 @@ fn bind_listener() -> io::Result<(OsString, Bound)> {
 fn bind_listener() -> io::Result<(OsString, Bound)> {
     use interprocess::local_socket::{GenericNamespaced, ToNsName};
 
-    let name_str = vite_str::format!("vp_run_ipc_{}", uuid::Uuid::new_v4());
+    let name_str = vite_str::format!("vite_task_ipc_{}", uuid::Uuid::new_v4());
     let name = name_str.as_str().to_ns_name::<GenericNamespaced>()?;
     let listener = ListenerOptions::new().name(name).create_tokio()?;
     Ok((OsString::from(name_str.as_str()), listener))

crates/vite_task_server/tests/integration.rs

@@ -50,7 +50,8 @@ where
 {
     let rt = Builder::new_current_thread().enable_all().build().unwrap();
     rt.block_on(async move {
-        let (name, ServerHandle { driver, stop_accepting }) = serve(handler).expect("bind server");
+        let (envs, ServerHandle { driver, stop_accepting }) = serve(handler).expect("bind server");
+        let name = envs.into_iter().next().expect("serve should yield an IPC env").1;
 
         let client = async move {
             tokio::task::spawn_blocking(move || client_work(name))

docs/runner-task-ipc/index.md

@@ -21,7 +21,7 @@ Rust crates:
 
 1. crates/vite_task_ipc_shared: defines the IPC message types shared between client and server. Uses wincode's zero-copy `SchemaWrite`/`SchemaRead` to minimize allocation. `Request` variants: `IgnoreInput`, `IgnoreOutput`, `GetEnv { id, name, tracked }`, `DisableCache`. Only `GetEnv` expects a `Response` (correlated via `id`); the others are fire-and-forget.
 2. vite_task_server: exposes a `Handler` trait and a `serve(&handler, shutdown)` free function that binds a listener (via `interprocess`, auto-cleaned via `tempfile` on Unix) and returns the socket path / pipe name plus a single-threaded future. The future accepts new clients until the `shutdown` future resolves, then stops accepting and waits for every in-flight per-client task to drain (each drains naturally when its client closes the stream — e.g. the task process exits). Uses `FuturesUnordered` (not `spawn_local`) so the handler can be borrowed and hold `!Send` state (`Rc`, `RefCell`) without locking.
-3. vite_task_client: a sync, blocking client with `&mut self` methods. Reads `VP_RUN_IPC` and `VP_RUN_CLIENT_NAPI` from the process env to set up the IPC connection, so that env var names are implementation details. Falls back to no-op if the env vars are not defined, so that it won't break the tool when it's not run by the runner.
+3. vite_task_client: a sync, blocking client with `&mut self` methods. Reads IPC connection info and the client-napi dylib path from the process env (specific env var names are an implementation detail shared with `vite_task_server`). Falls back to no-op if the envs are not defined, so that it won't break the tool when it's not run by the runner.
 4. vite_task_client_napi: a NAPI wrapper around the client, so that tools can require it in JavaScript/TypeScript and use it to communicate with the vite task runner.
 
 Js Packages:
@@ -38,7 +38,7 @@ Workflow:
 1. `vite_task_server` uses crate `interprocess` to create a server along with a unique name, and listens to messages from tools.
 2. `vite_task` calls vite_task_server to run server for every spawn execution. and collect what's reported from tools, and respone with requested envs
 3. `vite_task` embed `vite_task_client_napi` dylib and write to temp folder in the same way as `crates/fspy/src/unix/mod.rs:56`. (we should extract crates/fspy/src/artifact.rs into a separate crate)
-4. `vite_task` passes VP_RUN_CLIENT_NAPI env with the path of the dylib to the tool's process env, and VP_RUN_IPC env with the unique name of the server for the tool to connect.
+4. `vite_task` passes both the dylib path and the IPC connection info to the tool's process env, via env vars that `vite_task_client` knows to look up.
 5. the tool is expected to use `@voidzero-dev/vite-task-client`
 6. `@voidzero-dev/vite-task-client` initializes `vite_task_client_napi`, which internally reads the env vars and sets up the connection.
 

docs/runner-task-ipc/plan.md

@@ -4,5 +4,5 @@
 2. **Transport** — `vite_task_server` + `vite_task_client`. Build both sides, test them against each other directly in Rust. ✅
 3. **Extract artifact** — Pull `artifact.rs` out of fspy into a shared crate. Prerequisite for dylib embedding.
 4. **JS bridge** — `vite_task_client_napi` (real impl) + `@voidzero-dev/vite-task-client` (JS wrapper with `fetchEnvs` logic).
-5. **Runner integration** — Wire into `vite_task` spawn: start server per execution, embed/extract dylib, pass `VP_RUN_IPC` + `VP_RUN_CLIENT_NAPI`.
+5. **Runner integration** — Wire into `vite_task` spawn: start server per execution, embed/extract dylib, inject the IPC envs via `serve()`'s returned iterator.
 6. **Cache integration** — Runner consumes the reported data (ignored inputs/outputs, requested envs, disable cache) and adjusts caching behavior.

docs/runner-task-ipc/server-design.md

@@ -23,7 +23,7 @@ pub trait Handler {
 
 pub fn serve<'h, H: Handler + 'h>(
     handler: H,
-) -> io::Result<(OsString, ServerHandle<'h, H>)>;
+) -> io::Result<(impl Iterator<Item = (&'static OsStr, OsString)>, ServerHandle<'h, H>)>;
 
 pub struct ServerHandle<'h, H> {
     pub driver: LocalBoxFuture<'h, H>,
@@ -55,17 +55,17 @@ Only when fspy is enabled (`cache_metadata.input_config.includes_auto`). No fspy
 
 ### Construction (at `ExecutionMode` build time)
 
+`serve()` yields an env-pair iterator that the caller chains directly into the spawn's envs. The specific env var(s) used for IPC handoff are an implementation detail between the server and client crates — the runner never has to know their names.
+
 ```rust
-let (name, server) = serve(IpcRecorder::new(env_config))?;
-let envs = cmd.all_envs.iter()
-    .map(|(k, v)| (&**k, &**v))
-    .chain(std::iter::once((OsStr::new("VP_RUN_IPC"), name.as_os_str())));
+let (ipc_envs, server) = serve(IpcRecorder::new(env_config))?;
+let envs = cmd.all_envs.iter().map(|(k, v)| (&**k, &**v)).chain(ipc_envs);
 let child = spawn(&cmd, envs, true, SpawnStdio::Piped, token).await?;
-// `name` dropped here — it was only needed for envs.
+// After the child is spawned, nothing else needs the IPC envs.
 
 let fspy = FspyState {
     negatives,
-    server,  // ServerHandle<IpcRecorder>
+    server,  // ServerHandle<'h, IpcRecorder>
 };
 ```
 
@@ -80,7 +80,7 @@ struct FspyState {
 
 **Not stored:**
 
-- `name` — consumed once to build envs, dropped immediately.
+- IPC env name/value — consumed once to build the spawn envs, dropped immediately.
 - `handler` — lives inside `server.driver`'s async state; recovered by value when the driver resolves.
 
 ### Driving the server during `pipe_stdio` / `child.wait`
@@ -144,4 +144,4 @@ Earlier direction: "server doesn't care about cancellation token; it simply stop
 
 ### On `spawn()` changes (deferred)
 
-`spawn()` will need an `extra_envs`-style parameter (or an `envs: impl IntoIterator<(impl AsRef<OsStr>, impl AsRef<OsStr>)>`) so the caller can inject `VP_RUN_IPC` without cloning `Arc<BTreeMap>`. Not part of this step.
+`spawn()` will need to accept extra envs (e.g. `envs: impl IntoIterator<Item = (impl AsRef<OsStr>, impl AsRef<OsStr>)>`) so the caller can inject the IPC envs without cloning `Arc<BTreeMap>`. Not part of this step.

docs/runner-task-ipc/transport.md

@@ -7,7 +7,7 @@ Cross-platform IPC via `interprocess` crate:
 | Unix (macOS/Linux) | Unix domain socket |
 | Windows            | Named pipe         |
 
-The socket path or pipe name is passed to the task process via the `VP_RUN_IPC` env var. Clients check for its presence and skip IPC gracefully if absent.
+The socket path or pipe name is passed to the task process via an env var shared between `vite_task_server` and `vite_task_client` (the specific name is an implementation detail). Clients check for its presence and skip IPC gracefully if absent.
 
 ## Server Model