TSYSDevStack/ToolboxStack/output/toolbox-base/README.md

🧰 TSYSDevStack Toolbox Base

Daily-driver development container for ToolboxStack work. It provides a reproducible Ubuntu 24.04 environment with curated shell tooling, package managers, and helper scripts.

---

🚀 Quick Start

1. Build the image (local dev tag)

   ./build.sh
   

   Builds and tags the image as tsysdevstack-toolboxstack-toolbox-base:dev. Uses docker buildx with a local cache at .build-cache/ for faster rebuilds.

2. Start the container

   ./run.sh up
   

   Defaults to the release-current tag; override with TOOLBOX_IMAGE_OVERRIDE=... when testing other tags. Mise runtimes persist to your host in ~/.local/share/mise and ~/.cache/mise so language/tool downloads are shared across projects.

3. Attach to a shell

   docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh
   # or: bash / fish
   

4. Stop the container

   ./run.sh down
   

The compose service mounts the current repo to /workspace (read/write) and runs as the mapped host user (toolbox).

---

🏷️ Image Tagging & Releases

• ./build.sh (no overrides) ⇒ builds :dev for active development.
• ./release.sh <semver> ⇒ rebuilds, retags, and pushes :dev, :release-current, and v<semver> (e.g., ./release.sh 0.2.0). Requires a clean git tree.
• Add --dry-run to rehearse the release without pushing (optionally --allow-dirty for experimentation only).
• Downstream Dockerfiles should inherit from tsysdevstack-toolboxstack-toolbox-base:release-current (or pin to a semantic tag for reproducibility).

---

🧩 Tooling Inventory

Category	Tooling	Notes
Shells & Prompts	🐚 zsh • 🐟 fish • 🧑‍💻 bash • ⭐ starship • 💎 oh-my-zsh	Starship prompt enabled for all shells; oh-my-zsh configured with git + fzf plugins.
Runtime & CLI Managers	🪄 mise • 💧 aqua	mise handles language/tool runtimes (activation wired into zsh/bash/fish); aqua manages standalone CLIs with config at ~/.config/aquaproj-aqua/aqua.yaml.
Core CLI Utilities	📦 curl • 📥 wget • 🔐 ca-certificates • 🧭 git • 🔧 build-essential + headers (pkg-config, libssl-dev, zlib1g-dev, libffi-dev, libsqlite3-dev, libreadline-dev, make) • 🔍 ripgrep • 🧭 fzf • 📁 fd • 📖 bat • 🔗 openssh-client • 🧵 tmux • 🖥️ screen • 📈 htop • 📉 btop • ♻️ entr • 📊 jq • 🌐 httpie • ☕ tea • 🧮 bc	Provides ergonomic defaults plus toolchain deps for compiling runtimes (no global language installs).
Aqua-Managed CLIs	🐙 gh • 🌀 lazygit • 🪄 direnv • 🎨 git-delta • 🧭 zoxide • 🧰 just • 🧾 yq • ⚡ xh • 🌍 curlie • 🏠 chezmoi • 🛠️ shfmt • ✅ shellcheck • 🐳 hadolint • 🐍 uv • 🔁 watchexec	Extend via ~/.config/aquaproj-aqua/aqua.yaml and run aqua install. Direnv logging is muted and hooks for direnv/zoxide are pre-configured for zsh, bash, and fish.
AI CLI Tools	🧠 @just-every/code • 🤖 @qwen-code/qwen-code • 💎 @google/gemini-cli • 🔮 @openai/codex • 🌐 opencode-ai	AI-powered command-line tools for enhanced development workflows. Node.js is installed via mise to support npm package installation.
Container Workflow	🐳 Docker socket mount (/var/run/docker.sock)	Enables Docker CLIs inside the container; host Docker daemon required.
Runtime Environment	👤 Non-root user toolbox (UID/GID mapped) • 🗂️ /workspace mount	Maintains host permissions and isolates artifacts under artifacts/ToolboxStack/toolbox-base.

---

🛠️ Extending the Sandbox

• Add a runtime: mise use python@3.12 (per project). Run inside /workspace to persist .mise.toml.
• Add a CLI tool: update ~/.config/aquaproj-aqua/aqua.yaml, then run aqua install.
• Adjust base image: modify Dockerfile, run ./build.sh, and keep this README & PROMPT in sync.

🔁 Documentation policy: Whenever you add/remove tooling or change the developer experience, update both this README and the PROMPT file so the next collaborator has an accurate snapshot.

---

📂 Project Layout

Path	Purpose
Dockerfile	Defines the toolbox-base image.
docker-compose.yml	Compose service providing the container runtime.
build.sh	Wrapper around docker build with host UID/GID mapping.
run.sh	Helper to bring the compose service up/down (exports UID/GID env vars).
.devcontainer/devcontainer.json	VS Code remote container definition.
aqua.yaml	Default aqua configuration (gh, tea, lazygit).
PROMPT	LLM onboarding prompt for future contributors (must remain current).

---

✅ Verification Checklist

After any image changes:

1. Run ./build.sh and ensure it succeeds.
2. Optionally ./run.sh up and sanity-check key tooling (e.g., mise --version, gh --version).
3. Update this README and the PROMPT with any new or removed tooling.

---

🤝 Collaboration Notes

• Container always runs as the mapped non-root user; avoid adding steps that require root login.
• Prefer mise/aqua for new tooling to keep installations reproducible.
• Keep documentation synchronized (README + PROMPT) so future contributors can resume quickly.