feat(client): serve getEnv over runner IPC

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

@@ -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 server_envs: 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(server_envs))).map_err(ExecutionError::IpcServerBind)?;
  let tracking =
  Tracking { fspy, ipc_envs: ipc_envs.collect(), ipc_server_fut: driver, stop_accepting };
 
@@ -405,8 +409,16 @@ 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,
+ // TODO(env-track): A later PR in this stack replaces this child env
+ // map with the full planned env context so IPC can serve envs even
+ // when they were not declared in `env` or `untrackedEnv`.
+ &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_bin/tests/e2e_snapshots/fixtures/ipc_client_test/scripts/fetch_env.mjs

@@ -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/snapshots.toml

@@ -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/fetch_env_reads_declared_env.md

@@ -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/vite-task.json

@@ -8,6 +8,12 @@
  "command": "node scripts/disable_cache.mjs",
  "input": [],
  "cache": true
+ },
+ "fetch-env-declared": {
+ "command": "node scripts/fetch_env.mjs",
+ // TODO(env-track): Remove this explicit env declaration down the stack and update the e2e name once runner-tracked env reads cover it.
+ "env": ["PROBE_ENV"],
+ "cache": true
  }
  }
 }

crates/vite_task_client/Cargo.toml

@@ -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/src/lib.rs

@@ -1,10 +1,13 @@
 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};
+use wincode::{SchemaRead, config::DefaultConfig};
 
 #[cfg(unix)]
 type Stream = std::os::unix::net::UnixStream;
@@ -13,6 +16,7 @@ type Stream = std::fs::File;
 
 pub struct Client {
  stream: RefCell<Stream>,
+ scratch: RefCell<Vec<u8>>,
 }
 
 impl Client {
@@ -38,7 +42,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 +57,25 @@ 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.
+ // TODO(env-track): A later PR in this stack adds a tracked flag so env
+ // reads can participate in cache fingerprints instead of being IPC-only.
+ pub fn get_env(&self, name: &OsStr) -> io::Result<Option<Arc<OsStr>>> {
+ let name = Box::<NativeStr>::from(name);
+
+ self.send(&Request::GetEnv { name: &name })?;
+ let response: GetEnvResponse = self.recv()?;
+ 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,22 @@ impl Client {
  stream.flush()?;
  Ok(())
  }
+
+ fn recv<T>(&self) -> io::Result<T>
+ where
+ for<'de> T: SchemaRead<'de, DefaultConfig, Dst = 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)?;
+ wincode::deserialize_exact(&scratch)
+ .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))
+ }
 }
 
 #[cfg(unix)]

crates/vite_task_client_napi/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_ipc_shared/Cargo.toml

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

crates/vite_task_ipc_shared/src/lib.rs

@@ -1,3 +1,4 @@
+use native_str::NativeStr;
 use wincode::{SchemaRead, SchemaWrite};
 
 pub const IPC_ENV_NAME: &str = "VP_RUN_IPC_NAME";
@@ -15,14 +16,23 @@ pub const NODE_CLIENT_PATH_ENV_NAME: &str = "VP_RUN_NODE_CLIENT_PATH";
 /// IPC request frame sent by tools to the runner.
 ///
 /// `DisableCache` is fire-and-forget: the runner processes it when it
-/// arrives and never writes a response.
+/// arrives and never writes a response. `GetEnv` is a round-trip and pairs
+/// with [`GetEnvResponse`].
 ///
 /// Fire-and-forget is safe because nothing in the runner observes individual
 /// IPC events live — the recorded set is only consumed *after* the per-task
 /// IPC driver has drained the connection, which happens after the child
 /// process exits. So a tool can `flush + exit` and the server's drain phase
 /// will still consume every buffered frame.
 #[derive(Debug, SchemaWrite, SchemaRead)]
-pub enum Request {
+pub enum Request<'a> {
+ // TODO(env-track): A later PR in this stack adds a tracked flag once the
+ // runner records served env reads into the post-run cache fingerprint.
+ GetEnv { name: &'a NativeStr },
  DisableCache,
 }
+
+#[derive(Debug, SchemaWrite, SchemaRead)]
+pub struct GetEnvResponse {
+ pub env_value: Option<Box<NativeStr>>,
+}

crates/vite_task_server/Cargo.toml

@@ -8,6 +8,7 @@ rust-version.workspace = true
 
 [dependencies]
 futures = { workspace = true }
+rustc-hash = { workspace = true }
 tempfile = { workspace = true }
 thiserror = { workspace = true }
 tokio = { workspace = true, features = ["io-util", "net", "rt", "macros"] }