diff --git a/artifacts/ToolboxStack/toolbox-base/PROMPT b/artifacts/ToolboxStack/toolbox-base/PROMPT index cbeac36..1573f7d 100644 --- a/artifacts/ToolboxStack/toolbox-base/PROMPT +++ b/artifacts/ToolboxStack/toolbox-base/PROMPT @@ -12,15 +12,15 @@ Current state: - mise handles language/tool runtimes; activation wired into zsh, bash, and fish. - docker-compose.yml runs container with host UID/GID, `sleep infinity`, and docker socket mount; run via run.sh/build.sh. - Devcontainer config ( .devcontainer/devcontainer.json ) references the compose service. -- Documentation: docs/TOOLS.md tracks tooling inventory and must stay current. +- Documentation: README.md (tooling inventory & workflow) and this PROMPT must stay current. Collaboration guidelines: 1. Default to non-destructive operations; respect existing scripts run.sh/build.sh. -2. Any tooling changes require updating docs/TOOLS.md (inventory) and this prompt summary. +2. Any tooling changes require updating README.md (inventory) and this prompt summary. 3. Keep configurations reproducible: prefer aqua/mise for new CLI/runtimes over apt unless prerequisites. 4. Mention verification steps (build/test) after changes. 5. Maintain UID/GID mapping and non-root execution. Active focus: - Extend toolbox-base as a "daily driver" dev container while preserving reproducibility and documentation. -- Next contributor should review docs/TOOLS.md before modifying tooling and ensure both docs and this prompt reflect new state. +- Next contributor should review README.md before modifying tooling and ensure both README and this prompt reflect new state. diff --git a/artifacts/ToolboxStack/toolbox-base/README.md b/artifacts/ToolboxStack/toolbox-base/README.md new file mode 100644 index 0000000..ae13e19 --- /dev/null +++ b/artifacts/ToolboxStack/toolbox-base/README.md @@ -0,0 +1,81 @@ +# ๐Ÿงฐ 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** + ```bash + ./build.sh + ``` +2. **Start the container** + ```bash + ./run.sh up + ``` +3. **Attach to a shell** + ```bash + docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh + # or: bash / fish + ``` +4. **Stop the container** + ```bash + ./run.sh down + ``` + +The compose service mounts the current repo to `/workspace` (read/write) and runs as the mapped host user (`toolbox`). + +--- + +## ๐Ÿงฉ 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`) โ€ข ๐Ÿ” `ripgrep` โ€ข ๐Ÿงญ `fzf` โ€ข ๐Ÿ“ `fd` โ€ข ๐Ÿ“– `bat` โ€ข ๐Ÿ”— `openssh-client` โ€ข ๐Ÿงต `tmux` โ€ข ๐Ÿ–ฅ๏ธ `screen` โ€ข ๐Ÿ“Š `jq` | Provides ergonomic defaults plus toolchain deps for compiling runtimes (no global language installs). | +| **Aqua-Managed CLIs** | ๐Ÿ™ `gh` โ€ข ๐Ÿซ– `tea` โ€ข ๐ŸŒ€ `lazygit` | Extend via `~/.config/aquaproj-aqua/aqua.yaml` and run `aqua install`. | +| **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. diff --git a/artifacts/ToolboxStack/toolbox-base/aqua.yaml b/artifacts/ToolboxStack/toolbox-base/aqua.yaml index 9f79701..4450ea4 100644 --- a/artifacts/ToolboxStack/toolbox-base/aqua.yaml +++ b/artifacts/ToolboxStack/toolbox-base/aqua.yaml @@ -6,3 +6,6 @@ packages: - name: cli/cli@latest - name: go-gitea/tea@latest - name: jesseduffield/lazygit@latest + - name: direnv/direnv@latest + - name: dandavison/delta@latest + - name: ajeetdsouza/zoxide@latest diff --git a/artifacts/ToolboxStack/toolbox-base/docs/TOOLS.md b/artifacts/ToolboxStack/toolbox-base/docs/TOOLS.md deleted file mode 100644 index 1dcd9b3..0000000 --- a/artifacts/ToolboxStack/toolbox-base/docs/TOOLS.md +++ /dev/null @@ -1,20 +0,0 @@ -# ๐Ÿงฐ TSYSDevStack Toolbox Base โ€“ Installed Tooling - -| Category | Tooling | Notes | -|----------|---------|-------| -| Shells & Prompts | ๐Ÿš `zsh` โ€ข ๐ŸŸ `fish` โ€ข ๐Ÿง‘โ€๐Ÿ’ป `bash` โ€ข โญ `starship` โ€ข ๐Ÿ’Ž `oh-my-zsh` | Shell choice is flexible; Starship prompt configured for all three; oh-my-zsh with `git` + `fzf` plugins. | -| Runtime & CLI Managers | ๐Ÿช„ `mise` โ€ข ๐Ÿ’ง `aqua` | `mise` manages language/tool runtimes (activated for zsh/bash/fish); `aqua` manages standalone CLIs (global config under `~/.config/aquaproj-aqua/aqua.yaml`). | -| Core CLI Utilities | ๐Ÿ“ฆ `curl` โ€ข ๐Ÿ“ฅ `wget` โ€ข ๐Ÿ” `ca-certificates` โ€ข ๐Ÿงญ `git` โ€ข ๐Ÿ”ง `build-essential` + headers โ€ข ๐Ÿ” `ripgrep` โ€ข ๐Ÿงญ `fzf` โ€ข ๐Ÿ“ `fd` โ€ข ๐Ÿ“– `bat` โ€ข ๐Ÿ”— `openssh-client` โ€ข ๐Ÿงต `tmux` โ€ข ๐Ÿ–ฅ๏ธ `screen` โ€ข ๐Ÿ“Š `jq` | Provides day-to-day development ergonomics and compile toolchain requirements (openssl/zlib/sqlite/readline/ffi headers, pkg-config). | -| Aqua-Managed CLIs | ๐Ÿ™ `gh` โ€ข ๐Ÿซ– `tea` โ€ข ๐ŸŒ€ `lazygit` | Installed via aqua; extendable by editing `~/.config/aquaproj-aqua/aqua.yaml`. | -| Container Workflow | ๐Ÿณ Docker integration via host Docker socket | Compose file binds `/var/run/docker.sock` read-only; `docker` CLI expected on host. | -| Misc | ๐Ÿ—‚๏ธ `/workspace` mount (rw) โ€ข ๐Ÿ‘ค Non-root user `toolbox` mapped to host UID/GID | Container runs as the mapped host user; current repo mounted to `/workspace`. | - -## Usage Highlights - -1. Build the image: `./build.sh` -2. Start the dev environment: `./run.sh up` -3. Attach a shell: `docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh` (or `bash` / `fish`) -4. Manage runtimes: `mise use python@3.12` (per project) -5. Install extra CLIs: add entries to `~/.config/aquaproj-aqua/aqua.yaml` then run `aqua install` - -> โ„น๏ธ **Documentation policy:** Update this file whenever tooling changes (new utilities, removals, or configuration shifts) so contributors always have an accurate inventory.