xtask_todo_lib/devshell/vm/config/constants.rs
1//! `DEVSHELL_VM*` environment variable names (documented in module root).
2
3/// `DEVSHELL_VM` — **Release / binary default:** unset means **on** (use VM backend per `ENV_DEVSHELL_VM_BACKEND`).
4///
5/// Set to `off` / `0` / `false` / `no` (case-insensitive) to use **only** the host temp sandbox.
6/// `on` / `1` / `true` / `yes` also enable VM mode.
7///
8/// **Unit tests** (`cfg(test)`): unset defaults to **off** so `cargo test` works without Lima.
9pub const ENV_DEVSHELL_VM: &str = "DEVSHELL_VM";
10
11/// Backend selector: `host`, `auto`, `lima`, `beta`, …
12///
13/// **Release / binary default on Unix:** `lima` (γ) when this variable is unset.
14/// **Windows** default: **`beta`** (with **`beta-vm`** feature). Use **`DEVSHELL_VM_BACKEND=host`** for host-only sandbox.
15/// **Other non-Unix (non-Windows):** `host`.
16/// **`cfg(test)`:** unset → `auto` (host sandbox) for the same reason as `ENV_DEVSHELL_VM`.
17pub const ENV_DEVSHELL_VM_BACKEND: &str = "DEVSHELL_VM_BACKEND";
18
19/// When `1`/`true`/`yes`, start the VM session eagerly (future γ); default is lazy start on first rust tool.
20pub const ENV_DEVSHELL_VM_EAGER: &str = "DEVSHELL_VM_EAGER";
21
22/// Lima instance name for γ (`limactl shell <name>`).
23pub const ENV_DEVSHELL_VM_LIMA_INSTANCE: &str = "DEVSHELL_VM_LIMA_INSTANCE";
24
25/// Unix socket path for β client ↔ `devshell-vm --serve-socket` (see IPC draft).
26pub const ENV_DEVSHELL_VM_SOCKET: &str = "DEVSHELL_VM_SOCKET";
27
28/// When set (non-empty), β **`session_start`** sends this string as **`staging_dir`** to the sidecar instead of
29///
30/// `canonicalize(DEVSHELL_VM_WORKSPACE_PARENT / …)`. Use a **POSIX path** visible to the sidecar process
31/// (e.g. **`/workspace`** inside a Podman/WSL Linux container) while **`DEVSHELL_VM_WORKSPACE_PARENT`** on the
32/// host remains the real Windows path for push/pull. See **`docs/devshell-vm-windows.md`** (Podman).
33///
34/// On Windows, **`stdio`** (default) maps the host workspace to **`/mnt/<drive>/…`** inside Podman Machine for
35/// `session_start` **`staging_dir`** unless you set this explicitly.
36pub const ENV_DEVSHELL_VM_BETA_SESSION_STAGING: &str = "DEVSHELL_VM_BETA_SESSION_STAGING";
37
38/// When set (any value), skip **`podman machine ssh`** bootstrap on Windows: no Podman check / no requirement
39/// that the Linux `devshell-vm` binary exists (tests or fully manual β setup).
40pub const ENV_DEVSHELL_VM_SKIP_PODMAN_BOOTSTRAP: &str = "DEVSHELL_VM_SKIP_PODMAN_BOOTSTRAP";
41
42/// **Windows β:** optional full **Windows** path to the **Linux** `devshell-vm` binary
43/// (`x86_64-unknown-linux-gnu` / ELF) for **`podman machine ssh`** transport.
44///
45/// If unset, the binary is searched under **`$repo_root/target/x86_64-unknown-linux-gnu/release/devshell-vm`**
46/// where `repo_root` is discovered from cwd, [`ENV_DEVSHELL_VM_REPO_ROOT`], or walking up from the workspace
47/// parent — **not** the ephemeral `cargo-devshell-exports` tree. If still not found, **automatic fallback
48/// uses [`ENV_DEVSHELL_VM_CONTAINER_IMAGE`] with `podman run -i`** (see `podman_machine.rs`).
49pub const ENV_DEVSHELL_VM_LINUX_BINARY: &str = "DEVSHELL_VM_LINUX_BINARY";
50
51/// **Windows β:** optional **Windows** path to an **`xtask_todo`** repository root (directory containing
52///
53/// **`containers/devshell-vm/Containerfile`**). Locates **`target/x86_64-unknown-linux-gnu/release/devshell-vm`**
54/// when [`ENV_DEVSHELL_VM_LINUX_BINARY`] is unset. Useful if you keep a checkout for building the sidecar but run
55/// **`cargo devshell`** from other directories; **not** applicable when you only have a crates.io install and no clone.
56pub const ENV_DEVSHELL_VM_REPO_ROOT: &str = "DEVSHELL_VM_REPO_ROOT";
57
58/// **Windows β:** OCI image used when **no** host Linux `devshell-vm` ELF is found: `podman run -i` with
59///
60/// **`--serve-stdio`** and the workspace mounted at **`/workspace`** (no host TCP).
61/// Default: **`ghcr.io/tangcan/xtask_todo/devshell-vm:v{CARGO_PKG_VERSION}`** (published by CI on release).
62pub const ENV_DEVSHELL_VM_CONTAINER_IMAGE: &str = "DEVSHELL_VM_CONTAINER_IMAGE";
63
64/// **Windows β:** timeout (seconds) for each `podman pull` attempt in OCI fallback mode.
65/// When unset/invalid/0, default timeout is applied by implementation.
66#[cfg(windows)]
67pub const ENV_DEVSHELL_VM_PULL_TIMEOUT_SECS: &str = "DEVSHELL_VM_PULL_TIMEOUT_SECS";
68
69/// **Windows β:** stdio transport for `DEVSHELL_VM_SOCKET=stdio`: **`auto`** (default), **`machine-ssh`**
70/// (host ELF + `podman machine ssh`), or **`podman-run`** (OCI image + `podman run -i`).
71pub const ENV_DEVSHELL_VM_STDIO_TRANSPORT: &str = "DEVSHELL_VM_STDIO_TRANSPORT";
72
73/// When set (any value), do **not** isolate **`USERPROFILE` / `HOME`** for `podman` subprocesses (Windows).
74///
75/// By default we point **`USERPROFILE`** (Go’s `UserHomeDir()` on Windows — not only `HOME`) at a writable
76/// temp “profile” with an **empty default** `.ssh/known_hosts`, so a **locked, protected, or invalid**
77/// **`%USERPROFILE%\.ssh\known_hosts`** is not read. An existing Podman Machine dir is **symlinked** in when
78/// possible (see `podman_machine.rs`).
79pub const ENV_DEVSHELL_VM_DISABLE_PODMAN_SSH_HOME: &str = "DEVSHELL_VM_DISABLE_PODMAN_SSH_HOME";
80
81/// `DEVSHELL_VM_WORKSPACE_MODE` — **`sync`** (default) or **`guest`** (Mode P; guest filesystem as source of truth).
82///
83/// **`guest`** is effective only when the VM is enabled and the backend is **`lima`** or **`beta`**; otherwise
84/// `VmConfig::workspace_mode_effective` returns `WorkspaceMode::Sync` (design `2026-03-20-devshell-guest-primary-design.md` §6).
85///
86/// **Unset** (including **`cfg(test)`**): `WorkspaceMode::Sync`.
87pub const ENV_DEVSHELL_VM_WORKSPACE_MODE: &str = "DEVSHELL_VM_WORKSPACE_MODE";
88
89/// **β 侧车 `exec`：** 若设为正整数，作为毫秒超时（与 JSON **`timeout_ms`** 二选一/叠加见 **`devshell-vm`**）。**`0`** 或未设置表示不限制（仅受宿主/客户端是否在 JSON 里传 **`timeout_ms`** 约束）。
90pub const ENV_DEVSHELL_VM_EXEC_TIMEOUT_MS: &str = "DEVSHELL_VM_EXEC_TIMEOUT_MS";