From 04c65e73bc40e6f07b9d12e2eb32a859927ea5ea Mon Sep 17 00:00:00 2001 From: Sam & Pi Date: Wed, 17 Jun 2026 14:57:36 +0200 Subject: [PATCH] docs(toolchain): record clean Python 3.12 FreeBSD baseline (Sam & Pi) --- docs/TOOLCHAIN.md | 43 +++++++++++-------- .../references/graphify-freebsd-clawdie.md | 26 ++++------- 2 files changed, 32 insertions(+), 37 deletions(-) diff --git a/docs/TOOLCHAIN.md b/docs/TOOLCHAIN.md index 50d5d92..92913c0 100644 --- a/docs/TOOLCHAIN.md +++ b/docs/TOOLCHAIN.md @@ -10,19 +10,20 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe ## 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 | +| Tool | Standard | Linux (Debian/Ubuntu) | FreeBSD 15 (pkg) | Manager / source | +| ---------- | ------------------- | --------------------- | ----------------------- | -------------------------------- | +| **Python** | **3.12** (floor) | `python3.12` | `python312` | 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. @@ -30,9 +31,10 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe `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" + py_bin=$(ls "${MOUNT_POINT}/usr/local/bin"/python3.* 2>/dev/null \ + | sed 's@.*/@@' | grep -E '^python3\.[0-9]+$' | sort -V | tail -1) + ln -sf "${py_bin}" "${MOUNT_POINT}/usr/local/bin/python3" + ln -sf "${py_bin}" "${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` @@ -40,6 +42,7 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe 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. @@ -49,6 +52,7 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe 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. @@ -56,6 +60,7 @@ Probe before trusting this table — facts come from `scripts/verify_facts_probe - 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). @@ -69,13 +74,13 @@ Consensus of operator + Hermes + Claude. Standardize on **Python 3.12 floor** ev 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. +- **FreeBSD packaging reality:** OSA's FreeBSD quarterly repo publishes `python312`, but + not the matching `py312-aider_chat`, `py312-pillow`, `py312-pip`, or `py312-pygobject` + flavors yet. Keep Python package-flavored extras out of `pkg-list-*.txt` until they + exist; install those tools into explicit Python 3.12 venvs with uv/pip when needed. +- **ISO direction:** `clawdie-iso` should carry `python312`, version-agnostic `python3` + symlinks in `build.sh`, and `python3 -m venv` calls. Drop packages such as `gnumeric` + when they keep the old Python flavor alive transitively. _See [`AGENTS.md`](../AGENTS.md) for the agent matrix and [`HOST-MATRIX.md`](./HOST-MATRIX.md) for per-host hardware facts._ diff --git a/skills/codebase-knowledge-graphs/references/graphify-freebsd-clawdie.md b/skills/codebase-knowledge-graphs/references/graphify-freebsd-clawdie.md index aa8e287..f6c3381 100644 --- a/skills/codebase-knowledge-graphs/references/graphify-freebsd-clawdie.md +++ b/skills/codebase-knowledge-graphs/references/graphify-freebsd-clawdie.md @@ -19,30 +19,20 @@ python: >=3.10 PyPI provides source distributions, but no FreeBSD wheels were observed for `graphifyy` or key compiled deps. FreeBSD will likely build some dependencies from source unless FreeBSD packages cover them. -FreeBSD 14 amd64 quarterly packages observed available: +FreeBSD 15 amd64 quarterly packages observed available for the clean Python +3.12 baseline: ```text -python311 -py311-pip +python312 uv -py311-uv -py311-numpy -py311-scipy -py311-rapidfuzz -py311-networkx -py311-tree-sitter -py311-tree-sitter-python -py311-tree-sitter-javascript -py311-tree-sitter-go -py311-tree-sitter-bash ``` -Not observed as FreeBSD packages in that check: +Not observed as Python 3.12 FreeBSD packages in that check: ```text graphifyy -py311-datasketch -many tree-sitter grammar packages used by graphifyy, including typescript, rust, java, c, cpp, ruby, c-sharp, kotlin, scala, php, swift, lua, zig, powershell, elixir, objc, julia, verilog, fortran, json +Python package-flavored graph dependencies such as datasketch, numpy, scipy, +rapidfuzz, networkx, and tree-sitter grammar packages ``` ## Integration rule @@ -56,8 +46,8 @@ Run on the target FreeBSD builder/host from a clean repo checkout: ```sh mkdir -p tmp/graphify-test export TMPDIR="$(pwd)/tmp/graphify-test" -pkg install -y python311 py311-pip uv git cmake ninja py311-numpy py311-scipy py311-rapidfuzz py311-networkx -uvx --from graphifyy graphify --help +pkg install -y python312 uv git cmake ninja +uvx --python 3.12 --from graphifyy graphify --help ``` Small extraction first: