82 lines
5 KiB
Markdown
82 lines
5 KiB
Markdown
|
# Toolchain Baseline (cross-platform)
|
||
|
|
|
||
|
|
**Goal: the same frameworks and language runtimes across all hosts and OSes**, so an
|
||
|
|
agent relocated between Linux and FreeBSD finds an identical toolchain. Version drift
|
||
|
|
is a survivability bug — if debby and OSA disagree on Python or Node, a script that
|
||
|
|
works on one can silently fail on the other.
|
||
|
|
|
||
|
|
Probe before trusting this table — facts come from `scripts/verify_facts_probe.py
|
||
|
|
--build-tools`, not memory. Update the row when you bump a host.
|
||
|
|
|
||
|
|
## Baseline versions
|
||
|
|
|
||
|
|
| Tool | Standard | Linux (Debian/Ubuntu) | FreeBSD 15 (pkg) | Manager / source |
|
||
|
|
| ----------- | ------------------ | ---------------------------- | ----------------------- | --------------------------------- |
|
||
|
|
| **Python** | **3.12** (floor) | `python3.12` | `python312` + `py312-*` | system pkg + **uv** for venvs |
|
||
|
|
| **uv** | ≥ 0.11 | `uv` (astral) | `uv` (pkg) — confirm | standalone binary |
|
||
|
|
| **Node** | **24 LTS** (target)| `node` 24 | `node24` + `npm-node24` | LTS only; never a non-LTS major |
|
||
|
|
| **Rust** | stable (pinned) | rustup `stable` | `rust` (pkg) | `rust-toolchain.toml` per repo |
|
||
|
|
| **Go** | latest stable | `golang` | `go` (pkg) | only where a Go component exists |
|
||
|
|
| **Zig** | 0.15.2 | `~/.local/bin/zig` | manual | pinned (herdr build dep) |
|
||
|
|
| **tmux** | latest stable | `tmux` | `tmux` | system pkg |
|
||
|
|
|
||
|
|
## Conventions
|
||
|
|
|
||
|
|
### Python — never pin the version in a shebang
|
||
|
|
- Scripts use `#!/usr/bin/env python3`. **No `python3.11` / `python3.12` shebangs.**
|
||
|
|
- The interpreter is selected by a **symlink provided at image/host setup time**, so a
|
||
|
|
future bump (3.12 → 3.13) is a one-line change in one place, not a sweep across scripts.
|
||
|
|
- **FreeBSD ISO build provides the symlink** (FreeBSD pkg ships `python3.12` but no bare
|
||
|
|
`python3`):
|
||
|
|
```sh
|
||
|
|
# in clawdie-iso build.sh, version-agnostic:
|
||
|
|
PYVER=3.12 # single source of truth for the bump
|
||
|
|
ln -sf "python${PYVER}" "${MOUNT_POINT}/usr/local/bin/python3"
|
||
|
|
ln -sf "python${PYVER}" "${MOUNT_POINT}/usr/local/bin/python"
|
||
|
|
```
|
||
|
|
- venv creation calls `python3 -m venv` (resolves via the symlink) — **not** `python3.12 -m venv`.
|
||
|
|
- **uv is the standard venv/dependency manager** across all OSes. Prefer `uv venv` / `uv pip`
|
||
|
|
/ `uv sync` over raw `python -m venv` + `pip` so resolution and lockfiles match everywhere.
|
||
|
|
uv itself is interpreter-agnostic and picks up whatever `python3` resolves to.
|
||
|
|
|
||
|
|
### Node — LTS only, one major across the matrix
|
||
|
|
- Standard target: **Node 24 LTS** (FreeBSD already ships `node24`; npm 11).
|
||
|
|
- **Open divergence to resolve:** debby's Hermes Docker image deliberately pins **Node 22
|
||
|
|
LTS** (Debian trixie's bundled 20.x is EOL). FreeBSD is on **24**. These must converge.
|
||
|
|
Proposed resolution: bump the Hermes `node_source` stage `22 → 24` and retest the gateway
|
||
|
|
UI build. **Pending Hermes confirmation before flipping.**
|
||
|
|
- `package.json` engines floor stays generous (`>=20`) but installed runtime tracks the
|
||
|
|
agreed LTS. Never run a non-LTS Node major in production.
|
||
|
|
|
||
|
|
### Rust / Go / Zig
|
||
|
|
- Rust: pin per-repo with `rust-toolchain.toml` (channel `stable`) so FreeBSD pkg `rust`
|
||
|
|
and Linux rustup resolve the same toolchain. TLS via rustls (no openssl-sys) for the
|
||
|
|
`x86_64-unknown-freebsd` Tier-2 target.
|
||
|
|
- Go: only where a Go component exists; track latest stable.
|
||
|
|
- Zig pinned at 0.15.2 (herdr); bump deliberately.
|
||
|
|
|
||
|
|
### Managed tools (tmux, codex, pi, zot, …)
|
||
|
|
- These are agent/utility tools, not language runtimes. Track latest stable from the
|
||
|
|
platform package manager; record notable pins here when they matter.
|
||
|
|
- Pi is being retired (see consolidation on zot + Colibri). Codex stays (osa, ISO builds).
|
||
|
|
|
||
|
|
## Python 3.12 standardization (decision, 2026-06-17)
|
||
|
|
|
||
|
|
Consensus of operator + Hermes + Claude. Standardize on **Python 3.12 floor** everywhere.
|
||
|
|
|
||
|
|
- **Rationale:** available on Debian 13 and FreeBSD 15 via pkg; has needed stdlib
|
||
|
|
(`zoneinfo`, `match`/`case`); avoids 3.13 bleeding-edge quirks. Unifies a stack that was
|
||
|
|
drifting (debby Docker 3.13, domedog 3.12, OSA 3.11).
|
||
|
|
- **No code blocker:** `hermes-bsd/pyproject.toml` already allows `>=3.11,<3.14`; Hermes
|
||
|
|
scripts use `env python3`.
|
||
|
|
- **Work remaining is FreeBSD packaging in `clawdie-iso`:** `python311 → python312`,
|
||
|
|
`py311-* → py312-*` in `packages/pkg-list-*.txt`; version-agnostic symlink in `build.sh`;
|
||
|
|
`python3 -m venv` (not `python3.11`) in `firstboot/shell-deploy.sh`; `PYTHON_VERSION` in
|
||
|
|
`setup-hermes.sh`; `BUILD.md` docs.
|
||
|
|
- **Gate before flipping the ISO:** confirm FreeBSD pkg coverage on OSA —
|
||
|
|
`pkg search '^py312-aider_chat' '^py312-pygobject'` (gnumeric dep). Common modules
|
||
|
|
(pillow/pip) are safe; hold any module that lacks a py312 flavor.
|
||
|
|
|
||
|
|
_See [`AGENTS.md`](../AGENTS.md) for the agent matrix and [`HOST-MATRIX.md`](./HOST-MATRIX.md)
|
||
|
|
for per-host hardware facts._
|