feat(client): serve getEnv over runner IPC

Motivation:
The JS client already exposes getEnv, but before this change it always fell back to no-op behavior. Runner-aware tools need a real round-trip way to ask the runner for an env value before those reads can be used for cache tracking.

Scope:
Add the GetEnv request/response frame, response reading in the Rust client, server-side resolution from the spawned task env map, and a real NAPI getEnv implementation. This PR intentionally does not add tracked envs to cache fingerprints.

Verification:
- cargo test -p vite_task_server --test integration
- UPDATE_SNAPSHOTS=1 cargo test -p vite_task_bin --test e2e_snapshots fetch_env_reads_declared_env -- --ignored
- cargo test -p vite_task_bin --test e2e_snapshots fetch_env_reads_declared_env -- --ignored

Author: wan9chi

Cargo.lock

@@ -18,6 +18,7 @@ use std::{
 };
 
 use futures_util::future::LocalBoxFuture;
+use rustc_hash::FxHashMap;
 use tokio_util::sync::CancellationToken;
 use vite_path::{AbsolutePath, RelativePathBuf};
 use vite_task_ipc_shared::NODE_CLIENT_PATH_ENV_NAME;
@@ -156,6 +157,7 @@ impl<'a> ExecutionMode<'a> {
         cache_metadata: Option<&'a CacheMetadata>,
         stdio_config: StdioConfig,
         globbed_inputs: BTreeMap<RelativePathBuf, u64>,
+        envs: &BTreeMap<Arc<OsStr>, Arc<OsStr>>,
     ) -> Result<Self, ExecutionError> {
         let Some(metadata) = cache_metadata else {
             return Ok(Self::Uncached {
@@ -182,8 +184,10 @@ impl<'a> ExecutionMode<'a> {
         // Bind runner IPC for every cached task. The merged cache-control API
         // (`disableCache`) must work even when a task uses explicit inputs and
         // therefore does not need fspy auto-input inference.
+        let ipc_env_map: FxHashMap<Arc<OsStr>, Arc<OsStr>> =
+            envs.iter().map(|(name, value)| (Arc::clone(name), Arc::clone(value))).collect();
         let (ipc_envs, ServerHandle { driver, stop_accepting }) =
-            serve(Recorder::new()).map_err(ExecutionError::IpcServerBind)?;
+            serve(Recorder::new(Arc::new(ipc_env_map))).map_err(ExecutionError::IpcServerBind)?;
         let tracking =
             Tracking { fspy, ipc_envs: ipc_envs.collect(), ipc_server_fut: driver, stop_accepting };
 
@@ -405,8 +409,13 @@ async fn run(
     };
 
     // 4. Fold the cache/fspy/stdio decisions into the typed mode.
-    let mut mode = ExecutionMode::build(cache_metadata, stdio_config, globbed_inputs)
-        .map_err(Report::failed)?;
+    let mut mode = ExecutionMode::build(
+        cache_metadata,
+        stdio_config,
+        globbed_inputs,
+        &spawn_execution.spawn_command.all_envs,
+    )
+    .map_err(Report::failed)?;
 
     // Measure end-to-end duration here — spawn() doesn't track time.
     let start = Instant::now();

crates/vite_task/src/session/execute/mod.rs

@@ -0,0 +1,5 @@
+import { getEnv } from '@voidzero-dev/vite-task-client';
+
+const value = getEnv('PROBE_ENV') ?? '(unset)';
+
+console.log('PROBE_ENV=' + value);

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/scripts/fetch_env.mjs

@@ -46,3 +46,22 @@ steps = [
     "--last-details",
   ], comment = "summary names the opt-out as the not-cached reason" },
 ]
+
+[[e2e]]
+name = "fetch_env_reads_declared_env"
+comment = """
+Exercises `getEnv(name)`: the tool asks the runner for a declared env var and prints the served value. This verifies the round-trip IPC behavior before any runner-reported env is added to the cache fingerprint.
+"""
+ignore = true
+steps = [
+  { argv = [
+    "vt",
+    "run",
+    "fetch-env-declared",
+  ], envs = [
+    [
+      "PROBE_ENV",
+      "served",
+    ],
+  ], comment = "runner serves PROBE_ENV from the spawned task env map" },
+]

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots.toml

@@ -0,0 +1,12 @@
+# fetch_env_reads_declared_env
+
+Exercises `getEnv(name)`: the tool asks the runner for a declared env var and prints the served value. This verifies the round-trip IPC behavior before any runner-reported env is added to the cache fingerprint.
+
+## `PROBE_ENV=served vt run fetch-env-declared`
+
+runner serves PROBE_ENV from the spawned task env map
+
+```
+$ node scripts/fetch_env.mjs
+PROBE_ENV=served
+```

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/snapshots/fetch_env_reads_declared_env.md

@@ -8,6 +8,11 @@
       "command": "node scripts/disable_cache.mjs",
       "input": [],
       "cache": true
+    },
+    "fetch-env-declared": {
+      "command": "node scripts/fetch_env.mjs",
+      "env": ["PROBE_ENV"],
+      "cache": true
     }
   }
 }

crates/vite_task_bin/tests/e2e_snapshots/fixtures/ipc_client_test/vite-task.json

@@ -7,6 +7,7 @@ publish = false
 rust-version.workspace = true
 
 [dependencies]
+native_str = { workspace = true }
 vite_task_ipc_shared = { workspace = true }
 wincode = { workspace = true, features = ["derive"] }
 

crates/vite_task_client/Cargo.toml

@@ -1,10 +1,12 @@
 use std::{
     cell::RefCell,
     ffi::OsStr,
-    io::{self, Write},
+    io::{self, Read, Write},
+    sync::Arc,
 };
 
-use vite_task_ipc_shared::{IPC_ENV_NAME, Request};
+use native_str::NativeStr;
+use vite_task_ipc_shared::{GetEnvResponse, IPC_ENV_NAME, Request};
 
 #[cfg(unix)]
 type Stream = std::os::unix::net::UnixStream;
@@ -13,6 +15,7 @@ type Stream = std::fs::File;
 
 pub struct Client {
     stream: RefCell<Stream>,
+    scratch: RefCell<Vec<u8>>,
 }
 
 impl Client {
@@ -38,7 +41,7 @@ impl Client {
     }
 
     const fn from_stream(stream: Stream) -> Self {
-        Self { stream: RefCell::new(stream) }
+        Self { stream: RefCell::new(stream), scratch: RefCell::new(Vec::new()) }
     }
 
     /// Fire-and-forget: the call returns once the request is flushed to the
@@ -53,7 +56,26 @@ impl Client {
         self.send(&Request::DisableCache)
     }
 
-    fn send(&self, request: &Request) -> io::Result<()> {
+    /// Requests an env value from the runner. Returns `None` if the runner
+    /// reports the env is not available.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the request or response fails.
+    pub fn get_env(&self, name: &OsStr) -> io::Result<Option<Arc<OsStr>>> {
+        let name = Box::<NativeStr>::from(name);
+
+        self.send(&Request::GetEnv { name: &name })?;
+        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(&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())
@@ -64,6 +86,18 @@ impl Client {
         stream.flush()?;
         Ok(())
     }
+
+    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];
+        stream.read_exact(&mut len_bytes)?;
+        let len = u32::from_le_bytes(len_bytes) as usize;
+        scratch.clear();
+        scratch.resize(len, 0);
+        stream.read_exact(&mut scratch)?;
+        extract(&scratch)
+    }
 }
 
 #[cfg(unix)]

crates/vite_task_client/src/lib.rs

@@ -37,7 +37,7 @@
     reason = "no-op stubs keep the signature of the real implementations that replace them"
 )]
 
-use std::collections::HashMap;
+use std::{collections::HashMap, ffi::OsStr};
 
 use napi::{Error, Result};
 use napi_derive::napi;
@@ -92,16 +92,17 @@ impl RunnerClient {
         self.client.disable_cache().map_err(|err| err_string(vite_str::format!("{err}")))
     }
 
-    /// No-op for now: always returns `None`, so callers fall back to their
-    /// own process env. Becomes a real request once env tracking can
-    /// fingerprint the served values.
     #[napi]
-    pub fn get_env(
-        &self,
-        _name: String,
-        _options: Option<GetEnvOptions>,
-    ) -> Result<Option<String>> {
-        Ok(None)
+    pub fn get_env(&self, name: String, _options: Option<GetEnvOptions>) -> Result<Option<String>> {
+        let value = self
+            .client
+            .get_env(OsStr::new(&name))
+            .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"))
+            })
+        })
     }
 
     /// No-op for now: always returns an empty match-set — see

crates/vite_task_client_napi/src/lib.rs

@@ -7,6 +7,7 @@ publish = false
 rust-version.workspace = true
 
 [dependencies]
+native_str = { workspace = true }
 wincode = { workspace = true, features = ["derive"] }
 
 [lints]