Skip to main content

byob_exec/env/
mod.rs

1//! Workspace environments: where the programs and libraries a run needs come from.
2//!
3//! Models fail most often not on the task but on a missing tool (`jq: not found`,
4//! `No module named 'matplotlib'`, a `pip install` that can't work on NixOS). So every
5//! `run_command` / `run_python` call is prepared by [`Envs`]. If the user opted the
6//! workspace into a [`container`] (Docker/Podman; asked once when it has a
7//! devcontainer.json), the call runs there. Otherwise [`Envs`] stacks **layers** onto the
8//! clean sandbox environment, first match winning:
9//!
10//! 1. **Installed**: packages the model asked for with `install_packages`, kept per
11//!    workspace under `<data>/envs/` (Nix: one `buildEnv`, a GC root, nixpkgs pinned;
12//!    without Nix: a [`pixi`] manifest of conda-forge packages).
13//! 2. **Project venv**: a `.venv` / `venv` in the workspace (any OS).
14//! 3. **Project environments** (`Project`): what the workspace declares itself, loaded
15//!    once the user agreed ([`choices`], asked once per workspace), then cached until its
16//!    files change — a `flake.nix` / `shell.nix` dev shell (`nix print-dev-env`, shellHook
17//!    included), a pixi project (`pixi shell-hook --json`), mise tools (`mise env --json`).
18//! 4. **Support**: what a package manager's own CLI needs inside the sandbox, so the model
19//!    can also run `nix shell nixpkgs#foo --command …` itself (store, daemon socket,
20//!    config, a persistent eval cache), and Homebrew's `bin`.
21//!
22//! The last resort, [`system`] (Homebrew / winget, system-wide), always needs a person's
23//! approval. Failed output gets a [`hints`] line that names the one tool to call, because
24//! small models follow an explicit next step far better than prose. Design and plans:
25//! `docs/environments.md`.
26
27pub mod choices;
28pub mod command;
29pub mod container;
30pub mod devcontainer;
31pub mod hints;
32pub mod nix;
33pub mod pixi;
34pub mod project;
35pub mod system;
36
37use std::collections::{BTreeMap, BTreeSet};
38use std::ffi::OsString;
39use std::path::{Path, PathBuf};
40use std::sync::{Mutex, PoisonError};
41
42use byob_protocol::{ContainerEnv, EnvAction, EnvSupport, WorkspaceEnv};
43use byob_sandbox::Outcome;
44use byob_tools::{Access, Answer, EnvControl, EnvPlan, Question};
45use serde::{Deserialize, Serialize};
46
47use crate::Job;
48pub use command::CommandProvider;
49
50/// A provider a run uses: a registered one, or a plugin's command provider made for it.
51enum Provider<'a> {
52    Native(&'a dyn Project),
53    Command(CommandProvider),
54}
55
56impl Provider<'_> {
57    fn get(&self) -> &dyn Project {
58        match self {
59            Self::Native(p) => *p,
60            Self::Command(c) => c,
61        }
62    }
63}
64
65/// Changes a run gets: `PATH` entries in front of the host's, variables, and sandbox access.
66#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
67pub struct Layer {
68    /// Put in front of `PATH`, in this order.
69    #[serde(default)]
70    pub path: Vec<PathBuf>,
71    /// Variables to set (never `PATH`; see [`Layer::path`]).
72    #[serde(default)]
73    pub vars: Vec<(String, String)>,
74    #[serde(default)]
75    pub read: Vec<PathBuf>,
76    #[serde(default)]
77    pub write: Vec<PathBuf>,
78    /// Unix sockets the run may connect to without network (the Nix daemon's).
79    #[serde(default)]
80    pub sockets: Vec<PathBuf>,
81}
82
83impl Layer {
84    pub fn is_empty(&self) -> bool {
85        self == &Self::default()
86    }
87
88    /// Add `other` underneath: its `PATH` entries go after ours and it can't override our
89    /// variables.
90    pub fn stack(&mut self, other: &Layer) {
91        for p in &other.path {
92            if !self.path.contains(p) {
93                self.path.push(p.clone());
94            }
95        }
96        for (k, v) in &other.vars {
97            if !self.vars.iter().any(|(have, _)| have == k) {
98                self.vars.push((k.clone(), v.clone()));
99            }
100        }
101        self.read.extend(other.read.iter().cloned());
102        self.write.extend(other.write.iter().cloned());
103        self.sockets.extend(other.sockets.iter().cloned());
104    }
105
106    pub fn var(&self, name: &str) -> Option<&str> {
107        self.vars.iter().find(|(k, _)| k == name).map(|(_, v)| v.as_str())
108    }
109}
110
111/// Variables a layer must never set: the sandbox's own home, temp and cache folders, and
112/// what only makes sense inside a Nix build (mirrors `nix develop`'s ignore list).
113pub const KEEP_VARS: &[&str] = &[
114    "PATH",
115    "HOME",
116    "USER",
117    "LOGNAME",
118    "USERPROFILE",
119    "TMPDIR",
120    "TMP",
121    "TEMP",
122    "TEMPDIR",
123    "XDG_CACHE_HOME",
124    "XDG_CONFIG_HOME",
125    "MPLCONFIGDIR",
126    "TERM",
127    "TZ",
128    "PWD",
129    "OLDPWD",
130    "SHLVL",
131    "_",
132    "UID",
133    "PPID",
134    "BASHOPTS",
135    "SHELLOPTS",
136    "NIX_BUILD_TOP",
137    "NIX_LOG_FD",
138    "NIX_ENFORCE_PURITY",
139    "NIX_REMOTE",
140    "NIX_ATTRS_JSON_FILE",
141    "NIX_ATTRS_SH_FILE",
142    "SSL_CERT_FILE",
143    "NIX_SSL_CERT_FILE",
144    "SOURCE_DATE_EPOCH",
145    "DISPLAY",
146    "WAYLAND_DISPLAY",
147    "out",
148    "shellHook",
149];
150
151pub fn keep_var(name: &str) -> bool {
152    KEEP_VARS.contains(&name)
153}
154
155/// Runs a sandboxed job for a provider (the tool's own sandbox, with the support layer).
156pub trait Runner {
157    /// Run `job` in `cwd` with `tmp` as its private temp folder.
158    fn run(&self, job: Job, cwd: &Path, tmp: &Path) -> Result<Outcome, String>;
159    /// Ask the user (see [`byob_tools::ToolContext::ask`]).
160    fn ask(&self, _q: &Question) -> Answer {
161        Answer::AutoNo
162    }
163    /// The user pressed Stop.
164    fn cancelled(&self) -> bool {
165        false
166    }
167    /// What the chat's settings decide about where it runs (see [`EnvPlan`]).
168    fn plan(&self) -> EnvPlan {
169        EnvPlan::default()
170    }
171    /// The chat the call runs in, if known (the model is told things once per chat).
172    fn chat(&self) -> Option<String> {
173        None
174    }
175}
176
177/// What [`Envs::prepare`] found for one run.
178#[derive(Debug, Default)]
179pub(crate) struct Prepared {
180    pub layer: Layer,
181    /// One-time messages for the model (a dev shell just loaded, or failed to).
182    pub notes: Vec<String>,
183}
184
185/// The result of installing packages.
186#[derive(Debug, Clone, PartialEq, Eq)]
187pub struct Installed {
188    pub text: String,
189    /// Some packages weren't found or the build failed.
190    pub failed: bool,
191    /// The names it couldn't find (what `install_system_packages` may then try).
192    pub missing: Vec<String>,
193}
194
195/// Override the per-workspace question: `BYOB_WORKSPACE_ENV=off` never loads a workspace's
196/// own environment (installed packages and the Nix CLI still work), `on` loads it without
197/// asking. Unset (or `ask`): ask once per workspace and remember the answer.
198pub const WORKSPACE_ENV: &str = "BYOB_WORKSPACE_ENV";
199
200/// Whether project environments load (see [`WORKSPACE_ENV`]).
201#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
202pub enum ProjectMode {
203    /// Ask once per workspace.
204    #[default]
205    Ask,
206    Always,
207    Never,
208}
209
210impl ProjectMode {
211    pub fn from_env() -> Self {
212        match std::env::var(WORKSPACE_ENV).map(|v| v.trim().to_ascii_lowercase()).as_deref() {
213            Ok("off" | "0" | "false" | "no") => Self::Never,
214            Ok("on" | "1" | "true" | "yes") => Self::Always,
215            _ => Self::Ask,
216        }
217    }
218}
219
220/// An environment a workspace declares in a project file (`flake.nix`, `pixi.toml`,
221/// `mise.toml`, …): loaded once (slow, may download), then cached until its files change.
222///
223/// The providers form a registry: byob's own (Nix dev shells, pixi, mise; ids
224/// [`NATIVE_PROVIDERS`]) are made from what [`Found`] lists, more can be added with
225/// [`Envs::register`], and plugins declare command providers in their manifest
226/// (`environments`, see [`CommandProvider`]). Which ones a chat uses is
227/// [`EnvPlan::providers`] (`None`: every registered one).
228pub trait EnvProvider: Send + Sync + std::fmt::Debug {
229    /// Names the cache file.
230    fn id(&self) -> &str;
231    /// For messages: "Nix dev shell".
232    fn label(&self) -> &str;
233    /// The file in `ws` that declares it, if any.
234    fn file(&self, ws: &Path) -> Option<String>;
235    /// Files whose contents key the cache (lock files included).
236    fn inputs(&self) -> Vec<String>;
237    /// Load it now: a sandboxed run with network that may write the workspace and `dir`.
238    fn load(&self, ws: &Path, dir: &Path, run: &dyn Runner) -> Result<Layer, String>;
239}
240
241pub(crate) use EnvProvider as Project;
242
243/// byob's own providers, by the id plugin manifests name them with (`environments[].native`),
244/// and `container` (dev containers, which aren't an [`EnvProvider`] but switch the same way).
245pub const NATIVE_PROVIDERS: [&str; 4] = ["nix", "pixi", "mise", "container"];
246
247/// The result of [`load_project`].
248#[derive(Debug)]
249pub(crate) struct ProjectEnv {
250    pub file: String,
251    pub result: Result<Layer, String>,
252    /// Loaded just now (else from the cache).
253    pub fresh: bool,
254}
255
256#[derive(Debug, Serialize, Deserialize)]
257struct ProjectCache {
258    stamp: String,
259    #[serde(default)]
260    layer: Option<Layer>,
261    #[serde(default)]
262    error: Option<String>,
263}
264
265/// Cache key: the project's input files' contents.
266fn stamp(ws: &Path, p: &dyn Project) -> String {
267    let mut bytes = format!("{}\0", p.id()).into_bytes();
268    for f in p.inputs() {
269        bytes.extend_from_slice(f.as_bytes());
270        bytes.push(0);
271        bytes.extend(std::fs::read(ws.join(f)).unwrap_or_default());
272        bytes.push(0);
273    }
274    format!("{:016x}", fnv64(&bytes))
275}
276
277/// `p`'s environment for `ws`, from `<dir>/<id>.json` while its files are unchanged (and the
278/// folders it put on `PATH` still exist), else loaded now. Failures are cached too, so a
279/// broken project file is reported once rather than retried before every command.
280pub(crate) fn load_project(p: &dyn Project, ws: &Path, dir: &Path, run: &dyn Runner) -> Option<ProjectEnv> {
281    let file = p.file(ws)?;
282    let cache_file = dir.join(format!("{}.json", p.id()));
283    let now = stamp(ws, p);
284    if let Some(c) = std::fs::read_to_string(&cache_file).ok().and_then(|s| serde_json::from_str::<ProjectCache>(&s).ok())
285        && c.stamp == now
286    {
287        match (c.layer, c.error) {
288            (Some(l), _) if l.path.iter().all(|p| p.exists()) => return Some(ProjectEnv { file, result: Ok(l), fresh: false }),
289            (_, Some(e)) => return Some(ProjectEnv { file, result: Err(e), fresh: false }),
290            _ => {}
291        }
292    }
293    let result = std::fs::create_dir_all(dir)
294        .map_err(|e| format!("can't create {}: {e}", dir.display()))
295        .and_then(|()| dir.canonicalize().map_err(|e| e.to_string()))
296        .and_then(|dir| p.load(ws, &dir, run));
297    // Stamp after loading: the tool may just have written its lock file.
298    let cache = match &result {
299        Ok(l) => ProjectCache { stamp: stamp(ws, p), layer: Some(l.clone()), error: None },
300        Err(e) => ProjectCache { stamp: stamp(ws, p), layer: None, error: Some(e.clone()) },
301    };
302    if result.as_ref().err().is_none_or(|e| e != STOPPED)
303        && let Err(e) = write_atomic(&cache_file, serde_json::to_string(&cache).unwrap_or_default().as_bytes())
304    {
305        log::warn!("environments: {e}");
306    }
307    Some(ProjectEnv { file, result, fresh: true })
308}
309
310pub(crate) const STOPPED: &str = "Stopped by the user.";
311
312/// The package managers and tools found on this machine. [`Found::detect`] looks on
313/// `PATH`; tests build one by hand to hide what they don't want used (e.g. Nix, to test
314/// the pixi installer on a machine that has both).
315#[derive(Debug, Clone, Default)]
316pub struct Found {
317    pub nix: Option<nix::Nix>,
318    /// The `pixi` program.
319    pub pixi: Option<PathBuf>,
320    /// The `mise` program.
321    pub mise: Option<PathBuf>,
322    /// Homebrew or winget, for `install_system_packages` (the last resort).
323    pub system: Option<system::SystemInstaller>,
324    /// Docker or Podman, for workspaces whose commands run in a container.
325    pub containers: Option<container::Runtime>,
326    /// The image for containers without a devcontainer.json (default [`container::DEFAULT_IMAGE`]).
327    pub container_image: Option<String>,
328}
329
330impl Found {
331    /// Look for everything. `data_dir` holds caches and installed packages.
332    pub fn detect(data_dir: Option<&Path>) -> Self {
333        Self::detect_with(data_dir, None, None)
334    }
335
336    /// Like [`Found::detect`], with the settings for containers: the default image and
337    /// `docker` / `podman` (else Podman if installed, else Docker).
338    pub fn detect_with(data_dir: Option<&Path>, container_image: Option<String>, container_runtime: Option<&str>) -> Self {
339        let nix = nix::Nix::detect(data_dir);
340        if let Some(n) = &nix {
341            log::info!("environments: Nix {} ({})", n.binary().display(), if n.daemon() { "daemon" } else { "single-user" });
342        }
343        let pixi = byob_sandbox::which("pixi".as_ref());
344        let mise = byob_sandbox::which("mise".as_ref());
345        for (name, p) in [("pixi", &pixi), ("mise", &mise)] {
346            if let Some(p) = p {
347                log::info!("environments: {name} ({})", p.display());
348            }
349        }
350        let system = system::SystemInstaller::detect();
351        if let Some(s) = &system {
352            log::info!("environments: {} ({}), only as an approved last resort", s.name(), s.program.display());
353        }
354        let containers = container::Runtime::detect(container_runtime);
355        if let Some(c) = &containers {
356            log::info!("environments: containers with {} ({}), opt-in per workspace", c.name(), c.program.display());
357        }
358        Self { nix, pixi, mise, system, containers, container_image }
359    }
360}
361
362/// The package managers found on this machine, the per-workspace state they keep, and
363/// what the user decided per workspace.
364#[derive(Debug, Default)]
365pub struct Envs {
366    nix: Option<nix::Nix>,
367    /// The installer where there's no Nix.
368    pixi: Option<pixi::Pixi>,
369    /// Project environments, in order of precedence, by the id a plugin switches them with.
370    projects: Vec<(String, Box<dyn Project>)>,
371    /// `<data>/envs`, holding one folder per workspace.
372    state: Option<PathBuf>,
373    mode: ProjectMode,
374    choices: choices::Choices,
375    /// Workspaces whose declined environment the model was told about.
376    told: Mutex<BTreeSet<PathBuf>>,
377    system: Option<system::SystemInstaller>,
378    containers: Option<container::Containers>,
379    /// Workspaces (and chats in them) whose container the model was told about (or whose
380    /// declined devcontainer it was told about).
381    told_container: Mutex<BTreeSet<(PathBuf, Option<String>)>>,
382    /// Per workspace: names `install_packages` couldn't find (the only ones
383    /// `install_system_packages` may install while there is a workspace installer).
384    missing: Mutex<BTreeMap<PathBuf, BTreeSet<String>>>,
385    /// One question at a time, so two runs don't ask the same thing.
386    asking: Mutex<()>,
387    /// One activation or install at a time (they share caches and GC roots).
388    busy: Mutex<()>,
389}
390
391impl Envs {
392    /// Detect what this machine has. `data_dir` holds caches, installed packages and the
393    /// per-workspace answers; without it only the package managers' CLIs are made to work
394    /// inside the sandbox.
395    pub fn detect(data_dir: Option<&Path>) -> Self {
396        Self::new(data_dir, Found::detect(data_dir), ProjectMode::from_env())
397    }
398
399    /// Use exactly what `found` lists.
400    pub fn new(data_dir: Option<&Path>, found: Found, mode: ProjectMode) -> Self {
401        let mut projects: Vec<(String, Box<dyn Project>)> = Vec::new();
402        if let Some(n) = &found.nix {
403            projects.push(("nix".into(), Box::new(nix::NixShell(n.clone()))));
404        }
405        // Loading these goes through `sh`, which Windows lacks (like run_command itself).
406        if !cfg!(windows) {
407            for (id, kind, program) in [("pixi", project::Kind::Pixi, &found.pixi), ("mise", project::Kind::Mise, &found.mise)] {
408                if let Some(program) = program {
409                    projects.push((id.into(), Box::new(project::JsonEnvTool::new(kind, program.clone(), data_dir))));
410                }
411            }
412        }
413        let state = data_dir.map(|d| d.join("envs"));
414        let choices = choices::Choices::new(state.as_ref().map(|s| s.join("workspaces.json")));
415        // Nix first wherever it's present (conda-forge binaries need nix-ld on NixOS).
416        let pixi = match (&found.nix, &found.pixi, data_dir) {
417            (None, Some(program), Some(data)) => Some(pixi::Pixi::new(program.clone(), data)),
418            _ => None,
419        };
420        // Containers keep their temp folders in the data folder.
421        let containers = found.containers.filter(|_| data_dir.is_some()).map(|rt| container::Containers::new(rt, found.container_image));
422        Self { nix: found.nix, pixi, projects, state, mode, choices, system: found.system, containers, ..Self::default() }
423    }
424
425    /// No package managers (tests, or a machine without any).
426    pub fn none() -> Self {
427        Self::default()
428    }
429
430    /// Add a provider (after byob's own), switched on and off in chats by `id` like theirs
431    /// (an [`EnvPlan::providers`] whose `off` names it leaves it out).
432    pub fn register(&mut self, id: &str, provider: Box<dyn EnvProvider>) {
433        self.projects.retain(|(have, _)| have != id);
434        self.projects.push((id.to_owned(), provider));
435    }
436
437    /// The providers a run with `plan` uses: the registered ones its plan doesn't switch
438    /// off, then the plugins' command providers.
439    fn providers(&self, plan: &EnvPlan) -> Vec<Provider<'_>> {
440        let mut out = Vec::new();
441        for (id, p) in &self.projects {
442            if plan.providers.as_ref().is_none_or(|p| !p.off.iter().any(|n| n == id)) {
443                out.push(Provider::Native(p.as_ref()));
444            }
445        }
446        if !cfg!(windows) {
447            for decl in plan.providers.iter().flat_map(|p| &p.external) {
448                out.push(Provider::Command(CommandProvider::new(decl.clone())));
449            }
450        }
451        out
452    }
453
454    /// Dev containers are switched on for runs with `plan` (see [`NATIVE_PROVIDERS`]).
455    fn containers_on(&self, plan: &EnvPlan) -> bool {
456        plan.providers.as_ref().is_none_or(|p| !p.off.iter().any(|n| n == "container"))
457    }
458
459    /// The package manager `install_packages` uses here, if any.
460    pub fn installer(&self) -> Option<&'static str> {
461        self.state.as_ref()?;
462        if self.nix.is_some() { Some("Nix") } else { self.pixi.as_ref().map(|_| "pixi") }
463    }
464
465    /// Docker or Podman, if workspaces can run their commands in a container.
466    pub fn containers(&self) -> Option<&container::Containers> {
467        self.containers.as_ref()
468    }
469
470    /// A short paragraph for the system prompt.
471    pub fn prompt(&self) -> Option<String> {
472        let name = self.installer().or_else(|| self.containers.as_ref().map(|_| "the container's package manager"))?;
473        Some(format!(
474            "Software: run_command and run_python only have what is installed. When a program or a Python library is missing \
475             (\"command not found\", ModuleNotFoundError), call install_packages — it uses {name} and keeps the packages for this \
476             workspace — then run the command again. Don't use pip install, apt, brew or sudo: they don't work here."
477        ))
478    }
479
480    /// Per-workspace state folder: `<data>/envs/<name>-<hash of the path>`.
481    fn ws_dir(&self, ws: &Path) -> Option<PathBuf> {
482        let base = self.state.as_ref()?;
483        let name: String = ws
484            .file_name()
485            .map(|n| n.to_string_lossy().chars().filter(|c| c.is_ascii_alphanumeric() || "-_".contains(*c)).take(32).collect())
486            .unwrap_or_default();
487        let hash = fnv64(ws.as_os_str().as_encoded_bytes());
488        Some(base.join(format!("{}-{hash:016x}", if name.is_empty() { "ws" } else { &name })))
489    }
490
491    /// The support layer every sandboxed run gets.
492    pub(crate) fn support(&self) -> Layer {
493        let mut l = self.nix.as_ref().map(nix::Nix::support).unwrap_or_default();
494        if let Some(s) = &self.system {
495            l.stack(&s.layer());
496        }
497        l
498    }
499
500    /// Homebrew or winget, if `install_system_packages` is offered.
501    pub fn system(&self) -> Option<&system::SystemInstaller> {
502        self.system.as_ref()
503    }
504
505    /// May `install_system_packages` install `packages` for `ws`? Only what the workspace
506    /// installer couldn't find, or anything where there is none.
507    pub(crate) fn system_allowed(&self, ws: &Path, packages: &[String], plan: &EnvPlan) -> Result<(), String> {
508        if self.containers.is_some() && plan.container.or(self.choices.get(ws).container) == Some(true) {
509            return Err("This workspace's commands run in its container: call install_packages, which installs there.".into());
510        }
511        let Some(installer) = self.installer() else { return Ok(()) };
512        let missing = self.missing.lock().unwrap_or_else(PoisonError::into_inner);
513        let known = missing.get(ws);
514        let untried: Vec<&str> = packages.iter().filter(|p| !known.is_some_and(|k| k.contains(p.as_str()))).map(String::as_str).collect();
515        if untried.is_empty() {
516            return Ok(());
517        }
518        Err(format!(
519            "Call install_packages with {} first: it installs into this workspace with {installer}. install_system_packages is only \
520             for packages install_packages couldn't find.",
521            serde_json::json!({"packages": untried})
522        ))
523    }
524
525    /// Layers for one run in workspace `ws` (canonical path).
526    pub(crate) fn prepare(&self, ws: &Path, run: &dyn Runner) -> Prepared {
527        let mut out = Prepared::default();
528        let load = self.project_consent(ws, run, &mut out.notes);
529        let _busy = self.busy.lock().unwrap_or_else(PoisonError::into_inner);
530        let dir = self.ws_dir(ws);
531        if let Some(dir) = &dir {
532            let installed = match (&self.nix, &self.pixi) {
533                (Some(nix), _) => nix.installed(dir),
534                (None, Some(pixi)) => pixi.installed(dir),
535                (None, None) => None,
536            };
537            if let Some(l) = installed {
538                out.layer.stack(&l);
539            }
540        }
541        if let Some(l) = venv_layer(ws) {
542            out.layer.stack(&l);
543        }
544        let Some(dir) = dir.filter(|_| load) else { return out };
545        for p in self.providers(&run.plan()) {
546            let p = p.get();
547            let Some(env) = load_project(p, ws, &dir, run) else { continue };
548            match env.result {
549                Ok(l) => {
550                    out.layer.stack(&l);
551                    if env.fresh {
552                        out.notes.push(format!("Loaded the workspace's {} from {} (its programs are on PATH; cached until it changes).", p.label(), env.file));
553                    }
554                }
555                Err(e) if env.fresh => out.notes.push(format!("The workspace's {} ({}) failed to load, so this ran without it:\n{e}", p.label(), env.file)),
556                Err(_) => {}
557            }
558        }
559        out
560    }
561
562    /// Whether `ws`'s commands run in its container, and if so the container (created or
563    /// started as needed). `None`: on this machine. Asks once per workspace when it has a
564    /// devcontainer.json; without one, only the user's setting turns it on. `notes` gets
565    /// what the model should hear once.
566    pub(crate) fn container(&self, ws: &Path, run: &dyn Runner, notes: &mut Vec<String>) -> Option<Result<container::Ready, String>> {
567        let plan = run.plan();
568        if !self.containers_on(&plan) {
569            return None;
570        }
571        let devcontainer = devcontainer::find(ws);
572        // The workspace's (or chat's) environment setting decides; else the folder's answer.
573        let choice = plan.container.or_else(|| self.choices.get(ws).container);
574        let Some(c) = &self.containers else {
575            return (choice == Some(true)).then(|| {
576                Err("This workspace is set to run commands in a container, but neither Docker nor Podman is installed. Nothing ran. \
577                     Install one, or change the environment in the workspace's settings."
578                    .to_owned())
579            });
580        };
581        let dir = self.ws_dir(ws)?;
582        let want = match (choice, devcontainer, self.mode) {
583            (Some(v), ..) => v,
584            (None, None, _) | (None, Some(_), ProjectMode::Never) => false,
585            (None, Some(_), ProjectMode::Always) => true,
586            (None, Some(file), ProjectMode::Ask) => {
587                let _one = self.asking.lock().unwrap_or_else(PoisonError::into_inner);
588                match self.choices.get(ws).container {
589                    Some(v) => v,
590                    None => {
591                        let answer = run.ask(&container_question(file, c.runtime.name()));
592                        if let Err(e) = self.choices.set(ws, choices::Field::Container, Some(answer.allowed()), answer.by_user()) {
593                            log::warn!("environments: {e}");
594                        }
595                        answer.allowed()
596                    }
597                }
598            }
599        };
600        let first = self.told_container.lock().unwrap_or_else(PoisonError::into_inner).insert((ws.to_path_buf(), run.chat().filter(|_| want)));
601        if !want {
602            if let (Some(file), true) = (devcontainer, first) {
603                notes.push(format!("This workspace has {file}, but the user chose to run commands on their machine, not in the dev container."));
604            }
605            return None;
606        }
607        let spec = match spec_for(ws, &plan, &c.default_image) {
608            Ok(s) => s,
609            Err(e) => return Some(Err(format!("The workspace's dev container can't be used: {e}. Nothing ran."))),
610        };
611        let ready = c.ensure(ws, &spec, &dir.join("ctmp"), &|| run.cancelled());
612        if let Ok(r) = &ready {
613            if first || r.fresh {
614                let mut n = format!(
615                    "Commands run inside this workspace's {} container {} (image {}), as the user, not on their machine; the workspace is \
616                     mounted at the same path. install_packages installs with the container's package manager or pip. No internet unless a \
617                     call sets network: true.",
618                    c.runtime.name(),
619                    r.name,
620                    r.image
621                );
622                if !spec.ignored.is_empty() {
623                    n.push_str(&format!(" Settings in {} that byob ignores: {}.", spec.file.unwrap_or("devcontainer.json"), spec.ignored.join(", ")));
624                }
625                notes.push(n);
626            }
627            notes.extend(r.notes.iter().cloned());
628        }
629        Some(ready)
630    }
631
632    /// Remember what an install couldn't find, and point at the last resort.
633    fn note_missing(&self, ws: &Path, done: &mut Installed) {
634        if done.missing.is_empty() {
635            return;
636        }
637        self.missing.lock().unwrap_or_else(PoisonError::into_inner).entry(ws.to_path_buf()).or_default().extend(done.missing.iter().cloned());
638        if let Some(s) = &self.system {
639            done.text.push_str(&format!(
640                "\nOnly if there is no other way: install_system_packages can install {} system-wide with {} (the user must approve it).",
641                serde_json::json!(done.missing),
642                s.name()
643            ));
644        }
645    }
646
647    /// The project files of `ws` byob can load an environment from, with their labels.
648    fn project_files(&self, ws: &Path, plan: &EnvPlan) -> Vec<(String, String)> {
649        self.providers(plan).iter().filter_map(|p| p.get().file(ws).map(|f| (f, p.get().label().to_owned()))).collect()
650    }
651
652    /// May `ws`'s project environment be loaded? Asks the user the first time (once per
653    /// workspace; a person's answer is saved, the policy's lasts for this process). When
654    /// it may not, the model is told once.
655    fn project_consent(&self, ws: &Path, run: &dyn Runner, notes: &mut Vec<String>) -> bool {
656        let files = self.project_files(ws, &run.plan());
657        if files.is_empty() || self.state.is_none() {
658            return false;
659        }
660        let allowed = match (self.mode, run.plan().project) {
661            (ProjectMode::Never, _) => return false,
662            (ProjectMode::Always, _) => true,
663            // The workspace's environment setting (Nix) decided; no question.
664            (ProjectMode::Ask, Some(v)) => v,
665            (ProjectMode::Ask, None) => {
666                let _one = self.asking.lock().unwrap_or_else(PoisonError::into_inner);
667                match self.choices.get(ws).project {
668                    Some(v) => v,
669                    None => {
670                        let answer = run.ask(&project_question(&files));
671                        let save = answer.by_user();
672                        if let Err(e) = self.choices.set(ws, choices::Field::Project, Some(answer.allowed()), save) {
673                            log::warn!("environments: {e}");
674                        }
675                        answer.allowed()
676                    }
677                }
678            }
679        };
680        if !allowed && self.told.lock().unwrap_or_else(PoisonError::into_inner).insert(ws.to_path_buf()) {
681            let what: Vec<String> = files.iter().map(|(f, label)| format!("{f} ({label})")).collect();
682            notes.push(format!(
683                "This workspace declares an environment in {}, but the user chose not to load it, so commands run without it. \
684                 Don't load it yourself (e.g. with nix develop).",
685                what.join(", ")
686            ));
687        }
688        allowed
689    }
690
691    /// Install `packages` for workspace `ws`.
692    pub(crate) fn install(&self, ws: &Path, packages: &[String], run: &dyn Runner) -> Result<Installed, String> {
693        let mut notes = Vec::new();
694        if let Some(ready) = self.container(ws, run, &mut notes) {
695            let ready = ready?;
696            let c = self.containers.as_ref().ok_or("no container runtime")?;
697            let mut done = c.install(&ready, ws, packages, &|| run.cancelled())?;
698            if !notes.is_empty() {
699                done.text = format!("({})\n\n{}", notes.join(")\n("), done.text);
700            }
701            return Ok(done);
702        }
703        let _busy = self.busy.lock().unwrap_or_else(PoisonError::into_inner);
704        let Some(dir) = self.ws_dir(ws) else { return Err("byob has no data folder to install packages into".into()) };
705        let mut done = match (&self.nix, &self.pixi) {
706            (Some(nix), _) => nix.install(&dir, packages, run)?,
707            (None, Some(pixi)) => pixi.install(&dir, packages, run)?,
708            (None, None) => return Err(format!("no package manager is available here: {}", hints::GET_PIXI)),
709        };
710        self.note_missing(ws, &mut done);
711        Ok(done)
712    }
713}
714
715/// The canonical path of a workspace (how its answers are keyed), or `ws` as given.
716fn canonical(ws: &Path) -> PathBuf {
717    ws.canonicalize().unwrap_or_else(|_| ws.to_path_buf())
718}
719
720/// How to make `ws`'s container: the image its settings name, else its devcontainer.json,
721/// else `default_image`.
722fn spec_for(ws: &Path, plan: &EnvPlan, default_image: &str) -> Result<devcontainer::Spec, String> {
723    match plan.image.as_deref().filter(|i| devcontainer::valid_image(i)) {
724        Some(image) => Ok(devcontainer::Spec::default_image(image)),
725        None => devcontainer::Spec::for_workspace(ws, default_image),
726    }
727}
728
729impl EnvControl for Envs {
730    fn describe(&self, ws: &Path, plan: &EnvPlan) -> WorkspaceEnv {
731        let ws = canonical(ws);
732        let c = self.choices.get(&ws);
733        WorkspaceEnv {
734            workspace: ws.display().to_string(),
735            project_files: self.project_files(&ws, plan).into_iter().map(|(f, _)| f).collect(),
736            project_env: c.project,
737            project_env_forced: match (self.mode, plan.project) {
738                (ProjectMode::Always, _) => Some(true),
739                (ProjectMode::Never, _) => Some(false),
740                (ProjectMode::Ask, forced) => forced,
741            },
742            installer: self.installer().map(str::to_owned),
743            container: match &self.containers {
744                None => ContainerEnv {
745                    use_container: plan.container.or(c.container),
746                    devcontainer: devcontainer::find(&ws).map(str::to_owned),
747                    ..ContainerEnv::default()
748                },
749                Some(k) => ContainerEnv {
750                    runtime: Some(k.runtime.name().to_owned()),
751                    devcontainer: devcontainer::find(&ws).map(str::to_owned),
752                    use_container: plan.container.or(c.container),
753                    image: spec_for(&ws, plan, &k.default_image).map_or_else(|e| e, |s| s.describe(&ws)),
754                    state: k.state(&ws),
755                },
756            },
757            message: None,
758            failed: false,
759        }
760    }
761
762    fn support(&self) -> EnvSupport {
763        EnvSupport {
764            nix: self.nix.is_some(),
765            installer: self.installer().map(str::to_owned),
766            runtime: self.containers.as_ref().map(|c| c.runtime.name().to_owned()),
767        }
768    }
769
770    fn check_containers(&self) -> Result<String, String> {
771        let c = self.containers.as_ref().ok_or("Neither Docker nor Podman is installed on the machine byob runs on.")?;
772        c.runtime.check()?;
773        Ok(format!("{} is running.", c.runtime.name()))
774    }
775
776    fn forget(&self, ws: &Path) -> Result<String, String> {
777        let ws = canonical(ws);
778        let mut done = Vec::new();
779        if let Some(c) = &self.containers
780            && c.state(&ws).is_some()
781        {
782            c.remove(&ws)?;
783            done.push("removed its container");
784        }
785        if let Some(dir) = self.ws_dir(&ws).filter(|d| d.exists()) {
786            std::fs::remove_dir_all(&dir).map_err(|e| format!("couldn't delete {}: {e}", dir.display()))?;
787            done.push("deleted its installed packages and caches");
788        }
789        let had = self.choices.get(&ws) != choices::Choice::default();
790        self.choices.set(&ws, choices::Field::Project, None, true)?;
791        self.choices.set(&ws, choices::Field::Container, None, true)?;
792        if had {
793            done.push("forgot its answers");
794        }
795        self.told.lock().unwrap_or_else(PoisonError::into_inner).remove(&ws);
796        self.told_container.lock().unwrap_or_else(PoisonError::into_inner).retain(|(w, _)| *w != ws);
797        self.missing.lock().unwrap_or_else(PoisonError::into_inner).remove(&ws);
798        Ok(if done.is_empty() { "byob kept nothing else for this folder.".into() } else { format!("byob {}.", done.join(", ")) })
799    }
800
801    fn apply(&self, ws: &Path, action: &EnvAction) -> Result<String, String> {
802        let ws = canonical(ws);
803        match action {
804            EnvAction::ProjectEnv { load } => {
805                self.choices.set(&ws, choices::Field::Project, *load, true)?;
806                self.told.lock().unwrap_or_else(PoisonError::into_inner).remove(&ws);
807                Ok(match load {
808                    Some(true) => "The workspace's environment loads from the next command on.",
809                    Some(false) => "Commands run without the workspace's environment.",
810                    None => "byob asks again before the next command.",
811                }
812                .into())
813            }
814            EnvAction::Container { on } => {
815                self.choices.set(&ws, choices::Field::Container, *on, true)?;
816                self.told_container.lock().unwrap_or_else(PoisonError::into_inner).retain(|(w, _)| *w != ws);
817                Ok(match on {
818                    Some(true) => "Commands run in the workspace's container from the next one on.",
819                    Some(false) => "Commands run on this machine (the container is kept until you remove it).",
820                    None => "byob asks again if the workspace has a devcontainer.json.",
821                }
822                .into())
823            }
824            EnvAction::StopContainer => self.containers.as_ref().ok_or("Neither Docker nor Podman is installed.")?.stop(&ws),
825            EnvAction::RemoveContainer => self.containers.as_ref().ok_or("Neither Docker nor Podman is installed.")?.remove(&ws),
826            EnvAction::Unsupported => Err("This version of byob doesn't know that environment action.".into()),
827        }
828    }
829}
830
831/// "Run commands in the dev container?", asked once per workspace with a devcontainer.json.
832fn container_question(file: &str, runtime: &str) -> Question {
833    Question {
834        title: format!("Run this workspace's commands in its dev container ({file})"),
835        text: format!(
836            "byob would create a long-lived {runtime} container from {file} for this workspace and run run_command and run_python inside it, \
837             as your user, with the workspace mounted at the same path. Getting or building the image can take minutes and uses the \
838             internet; its setup commands run once. Your answer is remembered for this workspace; change it in the workspace's settings (its menu in the chat list)."
839        ),
840        warning: None,
841        access: Access::Execute,
842        always_ask: false,
843    }
844}
845
846/// "Load this workspace's environment?", asked once per workspace.
847fn project_question(files: &[(String, String)]) -> Question {
848    let labels: Vec<&str> = files.iter().map(|(_, l)| l.as_str()).collect();
849    let names: Vec<&str> = files.iter().map(|(f, _)| f.as_str()).collect();
850    Question {
851        title: format!("Load this workspace's {} ({})", labels.join(" and "), names.join(", ")),
852        text: format!(
853            "byob would load the environment {} declares before every run_command and run_python, so its programs are available. \
854             The first load can take minutes, downloads with internet access, runs the project's setup code, and may write lock files \
855             (flake.lock, pixi.lock) or a .pixi folder into the workspace. Your answer is remembered for this workspace; \
856             change it in the workspace's settings (its menu in the chat list).",
857            names.join(" / ")
858        ),
859        warning: None,
860        access: Access::Execute,
861        always_ask: false,
862    }
863}
864
865/// A Python virtual environment in the workspace (`.venv` or `venv`): its scripts folder
866/// goes first on `PATH`, as `activate` would do.
867pub fn venv_layer(ws: &Path) -> Option<Layer> {
868    for name in [".venv", "venv"] {
869        let venv = ws.join(name);
870        if !venv.join("pyvenv.cfg").is_file() {
871            continue;
872        }
873        let bin = if cfg!(windows) { venv.join("Scripts") } else { venv.join("bin") };
874        if bin.is_dir() {
875            return Some(Layer { path: vec![bin], vars: vec![("VIRTUAL_ENV".into(), venv.to_string_lossy().into_owned())], ..Default::default() });
876        }
877    }
878    None
879}
880
881/// `PATH` for a run: `prefix` then the host's.
882pub fn join_path(prefix: &[PathBuf], host: Option<&std::ffi::OsStr>) -> OsString {
883    let mut all: Vec<PathBuf> = prefix.to_vec();
884    if let Some(h) = host {
885        for p in std::env::split_paths(h) {
886            if !all.contains(&p) {
887                all.push(p);
888            }
889        }
890    }
891    std::env::join_paths(all).unwrap_or_default()
892}
893
894/// FNV-1a: a stable 64-bit hash for cache keys (std's hasher may change between releases).
895pub fn fnv64(bytes: &[u8]) -> u64 {
896    let mut h: u64 = 0xcbf2_9ce4_8422_2325;
897    for b in bytes {
898        h ^= u64::from(*b);
899        h = h.wrapping_mul(0x0100_0000_01b3);
900    }
901    h
902}
903
904/// Write `bytes` to `path` via a temp file and rename, so readers never see half a file.
905pub(crate) fn write_atomic(path: &Path, bytes: &[u8]) -> Result<(), String> {
906    if let Some(parent) = path.parent() {
907        std::fs::create_dir_all(parent).map_err(|e| format!("can't create {}: {e}", parent.display()))?;
908    }
909    let tmp = path.with_extension("tmp");
910    std::fs::write(&tmp, bytes).and_then(|()| std::fs::rename(&tmp, path)).map_err(|e| format!("can't write {}: {e}", path.display()))
911}
912
913#[cfg(test)]
914mod tests {
915    use super::*;
916
917    #[test]
918    fn stacking_keeps_the_first_value_and_order() {
919        let mut a = Layer { path: vec!["/a".into()], vars: vec![("X".into(), "1".into())], ..Default::default() };
920        let b = Layer {
921            path: vec!["/b".into(), "/a".into()],
922            vars: vec![("X".into(), "2".into()), ("Y".into(), "3".into())],
923            sockets: vec!["/s".into()],
924            ..Default::default()
925        };
926        a.stack(&b);
927        assert_eq!(a.path, vec![PathBuf::from("/a"), PathBuf::from("/b")]);
928        assert_eq!(a.var("X"), Some("1"));
929        assert_eq!(a.var("Y"), Some("3"));
930        assert_eq!(a.sockets, vec![PathBuf::from("/s")]);
931    }
932
933    #[cfg(unix)]
934    #[test]
935    fn path_is_prefix_then_host_without_duplicates() {
936        let p = join_path(&["/env/bin".into(), "/usr/bin".into()], Some("/usr/bin:/bin".as_ref()));
937        assert_eq!(p, "/env/bin:/usr/bin:/bin");
938    }
939
940    #[test]
941    fn venv_in_the_workspace_goes_first() {
942        let d = tempfile::tempdir().unwrap();
943        assert!(venv_layer(d.path()).is_none());
944        let bin = if cfg!(windows) { "Scripts" } else { "bin" };
945        std::fs::create_dir_all(d.path().join(".venv").join(bin)).unwrap();
946        assert!(venv_layer(d.path()).is_none(), "no pyvenv.cfg, not a venv");
947        std::fs::write(d.path().join(".venv/pyvenv.cfg"), "home = /usr/bin\n").unwrap();
948        let l = venv_layer(d.path()).unwrap();
949        assert_eq!(l.path, vec![d.path().join(".venv").join(bin)]);
950        assert!(l.var("VIRTUAL_ENV").is_some());
951    }
952
953    /// Loads by counting; fails while `bad` exists in the workspace.
954    #[derive(Debug, Default)]
955    struct Fake(std::sync::atomic::AtomicUsize);
956
957    impl Project for Fake {
958        fn id(&self) -> &str {
959            "fake"
960        }
961        fn label(&self) -> &str {
962            "fake env"
963        }
964        fn file(&self, ws: &Path) -> Option<String> {
965            ws.join("fake.toml").is_file().then(|| "fake.toml".to_owned())
966        }
967        fn inputs(&self) -> Vec<String> {
968            vec!["fake.toml".into(), "fake.lock".into()]
969        }
970        fn load(&self, ws: &Path, _dir: &Path, _run: &dyn Runner) -> Result<Layer, String> {
971            self.0.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
972            // Like `nix` writing flake.lock on first load.
973            std::fs::write(ws.join("fake.lock"), "locked").map_err(|e| e.to_string())?;
974            if ws.join("bad").exists() { Err("broken".into()) } else { Ok(Layer { vars: vec![("A".into(), "1".into())], ..Default::default() }) }
975        }
976    }
977
978    struct NoRun;
979    impl Runner for NoRun {
980        fn run(&self, _job: Job, _cwd: &Path, _tmp: &Path) -> Result<Outcome, String> {
981            Err("not in this test".into())
982        }
983    }
984
985    /// Answers every question with `answer`, counting them.
986    struct Asks {
987        answer: Answer,
988        asked: std::sync::atomic::AtomicUsize,
989    }
990    impl Asks {
991        fn new(answer: Answer) -> Self {
992            Self { answer, asked: std::sync::atomic::AtomicUsize::new(0) }
993        }
994        fn count(&self) -> usize {
995            self.asked.load(std::sync::atomic::Ordering::SeqCst)
996        }
997    }
998    impl Runner for Asks {
999        fn run(&self, _job: Job, _cwd: &Path, _tmp: &Path) -> Result<Outcome, String> {
1000            Err("not in this test".into())
1001        }
1002        fn ask(&self, q: &Question) -> Answer {
1003            assert!(q.title.contains("fake.toml") && !q.always_ask, "{q:?}");
1004            self.asked.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
1005            self.answer
1006        }
1007    }
1008
1009    impl Project for std::sync::Arc<Fake> {
1010        fn id(&self) -> &str {
1011            self.as_ref().id()
1012        }
1013        fn label(&self) -> &str {
1014            self.as_ref().label()
1015        }
1016        fn file(&self, ws: &Path) -> Option<String> {
1017            self.as_ref().file(ws)
1018        }
1019        fn inputs(&self) -> Vec<String> {
1020            self.as_ref().inputs()
1021        }
1022        fn load(&self, ws: &Path, dir: &Path, run: &dyn Runner) -> Result<Layer, String> {
1023            self.as_ref().load(ws, dir, run)
1024        }
1025    }
1026
1027    fn envs_with_fake(data: &Path, mode: ProjectMode) -> (Envs, std::sync::Arc<Fake>) {
1028        let fake = std::sync::Arc::new(Fake::default());
1029        let state = data.join("envs");
1030        let e = Envs {
1031            projects: vec![("fake".into(), Box::new(std::sync::Arc::clone(&fake)))],
1032            choices: choices::Choices::new(Some(state.join("workspaces.json"))),
1033            state: Some(state),
1034            mode,
1035            ..Envs::default()
1036        };
1037        (e, fake)
1038    }
1039
1040    #[test]
1041    fn project_envs_load_only_after_the_user_agrees_once_per_workspace() {
1042        let data = tempfile::tempdir().unwrap();
1043        let ws = tempfile::tempdir().unwrap();
1044        let ws = ws.path().canonicalize().unwrap();
1045        let (e, fake) = envs_with_fake(data.path(), ProjectMode::Ask);
1046        let loads = || fake.0.load(std::sync::atomic::Ordering::SeqCst);
1047        // No project file: nothing to ask.
1048        let yes = Asks::new(Answer::Yes);
1049        assert!(e.prepare(&ws, &yes).notes.is_empty() && yes.count() == 0);
1050
1051        std::fs::write(ws.join("fake.toml"), "v1").unwrap();
1052        // The user says no: not loaded, the model is told once, and the answer is saved.
1053        let no = Asks::new(Answer::No);
1054        let p = e.prepare(&ws, &no);
1055        assert_eq!((no.count(), loads()), (1, 0));
1056        assert!(p.notes.len() == 1 && p.notes[0].contains("chose not to load") && p.notes[0].contains("fake.toml"), "{:?}", p.notes);
1057        let p = e.prepare(&ws, &no);
1058        assert!(p.notes.is_empty() && no.count() == 1 && loads() == 0, "asked and told once");
1059        let (fresh, _) = envs_with_fake(data.path(), ProjectMode::Ask);
1060        let p = fresh.prepare(&ws, &no);
1061        assert_eq!(no.count(), 1, "remembered across restarts");
1062        assert_eq!(p.notes.len(), 1, "a new process tells the model again, once");
1063
1064        // Forget it in the settings: asked again; yes loads it, and is remembered.
1065        let forgot = e.apply(&ws, &EnvAction::ProjectEnv { load: None }).unwrap();
1066        assert!(forgot.contains("asks again"), "{forgot}");
1067        assert_eq!(e.describe(&ws, &byob_tools::EnvPlan::default()).project_env, None);
1068        let p = e.prepare(&ws, &yes);
1069        assert_eq!((yes.count(), loads()), (1, 1));
1070        assert!(p.layer.var("A") == Some("1") && p.notes[0].starts_with("Loaded"), "{:?}", p.notes);
1071        e.prepare(&ws, &yes);
1072        assert_eq!(yes.count(), 1);
1073        let d = e.describe(&ws, &byob_tools::EnvPlan::default());
1074        assert_eq!((d.project_files, d.project_env, d.project_env_forced), (vec!["fake.toml".to_owned()], Some(true), None));
1075    }
1076
1077    #[test]
1078    fn automatic_answers_last_for_the_session_and_the_override_wins() {
1079        let data = tempfile::tempdir().unwrap();
1080        let ws = tempfile::tempdir().unwrap();
1081        let ws = ws.path().canonicalize().unwrap();
1082        std::fs::write(ws.join("fake.toml"), "v1").unwrap();
1083        // --auto-approve: loaded without a person, not saved.
1084        let (e, fake) = envs_with_fake(data.path(), ProjectMode::Ask);
1085        let auto = Asks::new(Answer::AutoYes);
1086        assert_eq!(e.prepare(&ws, &auto).layer.var("A"), Some("1"));
1087        e.prepare(&ws, &auto);
1088        assert_eq!(auto.count(), 1, "asked once per session");
1089        let (again, _) = envs_with_fake(data.path(), ProjectMode::Ask);
1090        assert_eq!(again.describe(&ws, &byob_tools::EnvPlan::default()).project_env, None, "not saved");
1091        // Nobody to ask (no asker): not loaded, nothing saved.
1092        let nobody = NoRun;
1093        assert!(again.prepare(&ws, &nobody).layer.var("A").is_none());
1094        // BYOB_WORKSPACE_ENV=off / on.
1095        let (never, _) = envs_with_fake(data.path(), ProjectMode::Never);
1096        let yes = Asks::new(Answer::Yes);
1097        assert!(never.prepare(&ws, &yes).layer.is_empty() && yes.count() == 0);
1098        let (always, _) = envs_with_fake(data.path(), ProjectMode::Always);
1099        assert!(always.prepare(&ws, &yes).layer.var("A") == Some("1") && yes.count() == 0);
1100        assert_eq!(always.describe(&ws, &byob_tools::EnvPlan::default()).project_env_forced, Some(true));
1101        assert!(fake.0.load(std::sync::atomic::Ordering::SeqCst) >= 1);
1102    }
1103
1104    #[test]
1105    fn project_envs_are_cached_until_their_files_change() {
1106        let ws = tempfile::tempdir().unwrap();
1107        let dir = tempfile::tempdir().unwrap();
1108        let p = Fake::default();
1109        let loads = || p.0.load(std::sync::atomic::Ordering::SeqCst);
1110        assert!(load_project(&p, ws.path(), dir.path(), &NoRun).is_none(), "no project file");
1111        std::fs::write(ws.path().join("fake.toml"), "v1").unwrap();
1112        let first = load_project(&p, ws.path(), dir.path(), &NoRun).unwrap();
1113        assert!(first.fresh && first.result.unwrap().var("A") == Some("1") && loads() == 1);
1114        let second = load_project(&p, ws.path(), dir.path(), &NoRun).unwrap();
1115        assert!(!second.fresh && second.result.is_ok() && loads() == 1, "cached, though the load wrote the lock file");
1116        std::fs::write(ws.path().join("fake.toml"), "v2").unwrap();
1117        std::fs::write(ws.path().join("bad"), "").unwrap();
1118        let broken = load_project(&p, ws.path(), dir.path(), &NoRun).unwrap();
1119        assert!(broken.fresh && broken.result.is_err() && loads() == 2);
1120        let again = load_project(&p, ws.path(), dir.path(), &NoRun).unwrap();
1121        assert!(!again.fresh && again.result.is_err() && loads() == 2, "a failure is cached too");
1122    }
1123
1124    #[test]
1125    fn workspace_folders_are_stable_and_distinct() {
1126        let e = Envs { state: Some("/data/envs".into()), ..Envs::default() };
1127        let a = e.ws_dir(Path::new("/home/me/My Project")).unwrap();
1128        assert_eq!(a, e.ws_dir(Path::new("/home/me/My Project")).unwrap());
1129        assert_ne!(a, e.ws_dir(Path::new("/home/you/My Project")).unwrap());
1130        assert!(a.file_name().unwrap().to_string_lossy().starts_with("MyProject-"));
1131        assert_eq!(fnv64(b""), 0xcbf2_9ce4_8422_2325);
1132        assert!(Envs::none().installer().is_none() && Envs::none().prompt().is_none());
1133    }
1134}