Files

ReachableCEO 27948346b4 feat(toolbox): update toolbox configuration and scripts

- Update collab/TSYSDevStack-toolbox-prompt.md with latest guidelines
- Update output/PROMPT with improved instructions for AI collaboration
- Update output/toolbox-base/PROMPT with enhanced development guidelines
- Update output/toolbox-base/README.md with current documentation
- Update output/toolbox-base/build.sh with improved build process
- Update output/toolbox-base/docker-compose.yml with refined service definitions
- Update output/toolbox-base/run.sh with enhanced runtime configuration
- Add output/toolbox-base/release.sh for release management processes

These changes improve the developer workspace experience and ensure
consistent tooling across the TSYSDevStack project.

2025-10-29 08:26:35 -05:00

5.1 KiB

Raw Permalink Blame History

🧰 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

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.
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.

Attach to a shell

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

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.
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:

Run ./build.sh and ensure it succeeds.
Optionally ./run.sh up and sanity-check key tooling (e.g., mise --version, gh --version).
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.

5.1 KiB Raw Permalink Blame History