refactor: move stack assets and wire in mailhog

2025-10-29 05:56:27 -05:00
parent 8f37c46310
commit 7061fbb2a9
41 changed files with 217 additions and 251 deletions
--- a/ToolboxStack/output/toolbox-base/.devcontainer/devcontainer.json
+++ b/ToolboxStack/output/toolbox-base/.devcontainer/devcontainer.json
@@ -0,0 +1,14 @@
+{
+  "name": "TSYSDevStack Toolbox Base",
+  "dockerComposeFile": [
+    "../docker-compose.yml"
+  ],
+  "service": "toolbox-base",
+  "workspaceFolder": "/workspace",
+  "remoteUser": "toolbox",
+  "runServices": [
+    "toolbox-base"
+  ],
+  "overrideCommand": false,
+  "postCreateCommand": "zsh -lc 'starship --version >/dev/null'"
+}
--- a/ToolboxStack/output/toolbox-base/Dockerfile
+++ b/ToolboxStack/output/toolbox-base/Dockerfile
@@ -0,0 +1,114 @@
+FROM ubuntu:24.04
+
+ARG USER_ID=1000
+ARG GROUP_ID=1000
+ARG USERNAME=toolbox
+ARG TEA_VERSION=0.11.1
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \
+    apt-get update \
+    && apt-get install -y --no-install-recommends \
+        ca-certificates \
+        curl \
+        fish \
+        fzf \
+        git \
+        jq \
+        bc \
+        locales \
+        openssh-client \
+        ripgrep \
+        tmux \
+        screen \
+        fd-find \
+        bat \
+        httpie \
+        build-essential \
+        pkg-config \
+        libssl-dev \
+        zlib1g-dev \
+        libffi-dev \
+        libsqlite3-dev \
+        libreadline-dev \
+        wget \
+        zsh \
+    && apt-get clean \
+    && rm -rf /var/lib/apt/lists/*
+
+# Provide common aliases for fd and bat binaries
+RUN ln -sf /usr/bin/fdfind /usr/local/bin/fd \
+    && ln -sf /usr/bin/batcat /usr/local/bin/bat
+
+# Install Gitea tea CLI
+RUN curl -fsSL "https://dl.gitea.io/tea/${TEA_VERSION}/tea-${TEA_VERSION}-linux-amd64" -o /tmp/tea \
+    && curl -fsSL "https://dl.gitea.io/tea/${TEA_VERSION}/tea-${TEA_VERSION}-linux-amd64.sha256" -o /tmp/tea.sha256 \
+    && sed -n 's/ .*//p' /tmp/tea.sha256 | awk '{print $1 "  /tmp/tea"}' | sha256sum -c - \
+    && install -m 0755 /tmp/tea /usr/local/bin/tea \
+    && rm -f /tmp/tea /tmp/tea.sha256
+
+# Configure locale to ensure consistent tool behavior
+RUN locale-gen en_US.UTF-8
+ENV LANG=en_US.UTF-8 \
+    LANGUAGE=en_US:en \
+    LC_ALL=en_US.UTF-8
+
+# Install Starship prompt
+RUN curl -fsSL https://starship.rs/install.sh | sh -s -- -y -b /usr/local/bin
+
+# Install aqua package manager (manages additional CLI tooling)
+RUN curl -sSfL https://raw.githubusercontent.com/aquaproj/aqua-installer/v2.3.1/aqua-installer | AQUA_ROOT_DIR=/usr/local/share/aquaproj-aqua bash \
+    && ln -sf /usr/local/share/aquaproj-aqua/bin/aqua /usr/local/bin/aqua
+
+# Install mise for runtime management (no global toolchains pre-installed)
+RUN curl -sSfL https://mise.jdx.dev/install.sh | env MISE_INSTALL_PATH=/usr/local/bin/mise MISE_INSTALL_HELP=0 sh
+
+# Create non-root user with matching UID/GID for host mapping
+RUN if getent passwd "${USER_ID}" >/dev/null; then \
+        existing_user="$(getent passwd "${USER_ID}" | cut -d: -f1)"; \
+        userdel --remove "${existing_user}"; \
+    fi \
+    && if ! getent group "${GROUP_ID}" >/dev/null; then \
+        groupadd --gid "${GROUP_ID}" "${USERNAME}"; \
+    fi \
+    && useradd --uid "${USER_ID}" --gid "${GROUP_ID}" --shell /usr/bin/zsh --create-home "${USERNAME}"
+
+# Install Oh My Zsh and configure shells for the unprivileged user
+RUN su - "${USERNAME}" -c 'git clone --depth=1 https://github.com/ohmyzsh/ohmyzsh.git ~/.oh-my-zsh' \
+    && su - "${USERNAME}" -c 'cp ~/.oh-my-zsh/templates/zshrc.zsh-template ~/.zshrc' \
+    && su - "${USERNAME}" -c 'mkdir -p ~/.config' \
+    && su - "${USERNAME}" -c 'sed -i "s/^plugins=(git)$/plugins=(git fzf)/" ~/.zshrc' \
+    && su - "${USERNAME}" -c 'printf "\nexport PATH=\"\$HOME/.local/share/aquaproj-aqua/bin:\$HOME/.local/share/mise/shims:\$HOME/.local/bin:\$PATH\"\n" >> ~/.zshrc' \
+    && su - "${USERNAME}" -c 'printf "\nexport AQUA_GLOBAL_CONFIG=\"\$HOME/.config/aquaproj-aqua/aqua.yaml\"\n" >> ~/.zshrc' \
+    && su - "${USERNAME}" -c 'printf "\n# Starship prompt\neval \"\$(starship init zsh)\"\n" >> ~/.zshrc' \
+    && su - "${USERNAME}" -c 'printf "\n# mise runtime manager\neval \"\$(mise activate zsh)\"\n" >> ~/.zshrc' \
+    && su - "${USERNAME}" -c 'printf "\n# direnv\nexport DIRENV_LOG_FORMAT=\"\"\neval \"\$(direnv hook zsh)\"\n" >> ~/.zshrc' \
+    && su - "${USERNAME}" -c 'printf "\n# zoxide\neval \"\$(zoxide init zsh)\"\n" >> ~/.zshrc' \
+    && su - "${USERNAME}" -c 'printf "\nexport AQUA_GLOBAL_CONFIG=\"\$HOME/.config/aquaproj-aqua/aqua.yaml\"\n" >> ~/.bashrc' \
+    && su - "${USERNAME}" -c 'printf "\n# mise runtime manager (bash)\neval \"\$(mise activate bash)\"\n" >> ~/.bashrc' \
+    && su - "${USERNAME}" -c 'printf "\n# direnv\nexport DIRENV_LOG_FORMAT=\"\"\neval \"\$(direnv hook bash)\"\n" >> ~/.bashrc' \
+    && su - "${USERNAME}" -c 'printf "\n# zoxide\neval \"\$(zoxide init bash)\"\n" >> ~/.bashrc' \
+    && su - "${USERNAME}" -c 'mkdir -p ~/.config/fish' \
+    && su - "${USERNAME}" -c 'printf "\nset -gx AQUA_GLOBAL_CONFIG \$HOME/.config/aquaproj-aqua/aqua.yaml\n# Shell prompt and runtime manager\nstarship init fish | source\nmise activate fish | source\ndirenv hook fish | source\nzoxide init fish | source\n" >> ~/.config/fish/config.fish'
+
+COPY aqua.yaml /tmp/aqua.yaml
+
+RUN chown "${USER_ID}:${GROUP_ID}" /tmp/aqua.yaml \
+    && su - "${USERNAME}" -c 'mkdir -p ~/.config/aquaproj-aqua' \
+    && su - "${USERNAME}" -c 'cp /tmp/aqua.yaml ~/.config/aquaproj-aqua/aqua.yaml' \
+    && su - "${USERNAME}" -c 'AQUA_GLOBAL_CONFIG=~/.config/aquaproj-aqua/aqua.yaml aqua install'
+
+# Prepare workspace directory with appropriate ownership
+RUN mkdir -p /workspace \
+    && chown "${USER_ID}:${GROUP_ID}" /workspace
+
+ENV SHELL=/usr/bin/zsh \
+    AQUA_GLOBAL_CONFIG=/home/${USERNAME}/.config/aquaproj-aqua/aqua.yaml \
+    PATH=/home/${USERNAME}/.local/share/aquaproj-aqua/bin:/home/${USERNAME}/.local/share/mise/shims:/home/${USERNAME}/.local/bin:${PATH}
+
+WORKDIR /workspace
+USER ${USERNAME}
+
+CMD ["/usr/bin/zsh"]
--- a/ToolboxStack/output/toolbox-base/PROMPT
+++ b/ToolboxStack/output/toolbox-base/PROMPT
@@ -0,0 +1,26 @@
+You are Codex, collaborating with a human on the TSYSDevStack ToolboxStack project.
+
+Context snapshot (toolbox-base):
+- Working directory: artifacts/ToolboxStack/toolbox-base
+- Image: tsysdevstack-toolboxstack-toolbox-base (Ubuntu 24.04)
+- Container user: toolbox (non-root, UID/GID mapped to host)
+- Mounted workspace: current repo at /workspace (rw)
+
+Current state:
+- Dockerfile installs shell tooling (zsh/bash/fish with Starship & oh-my-zsh), core CLI utilities (curl, wget, git, tmux, screen, httpie, tea, bc, etc.), build-essential + headers, aqua, and mise. Aqua is pinned to specific versions for gh, lazygit, direnv, git-delta, zoxide, just, yq, xh, curlie, chezmoi, shfmt, shellcheck, hadolint; direnv/zoxide hooks are enabled for all shells (direnv logging muted).
+- aqua-managed CLI inventory lives in README.md alongside usage notes; tea installs via direct download with checksum verification (TEA_VERSION build arg).
+- 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. Host directories `~/.local/share/mise` and `~/.cache/mise` are mounted for persistent runtimes.
+- Devcontainer config ( .devcontainer/devcontainer.json ) references the compose service.
+- Documentation: README.md (tooling inventory & workflow) and this PROMPT must stay current. README also notes that build.sh now uses docker buildx with a local cache directory.
+
+Collaboration guidelines:
+1. Default to non-destructive operations; respect existing scripts run.sh/build.sh.
+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 README.md before modifying tooling and ensure both README and this prompt reflect new state.
--- a/ToolboxStack/output/toolbox-base/README.md
+++ b/ToolboxStack/output/toolbox-base/README.md
@@ -0,0 +1,83 @@
+# 🧰 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
+   ```
+   > Uses `docker buildx` with a local cache at `.build-cache/` for faster rebuilds.
+2. **Start the container**
+   ```bash
+   ./run.sh up
+   ```
+   > 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**
+   ```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`, `make`) • 🔍 `ripgrep` • 🧭 `fzf` • 📁 `fd` • 📖 `bat` • 🔗 `openssh-client` • 🧵 `tmux` • 🖥️ `screen` • 📊 `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` | 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:
+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.
--- a/ToolboxStack/output/toolbox-base/aqua.yaml
+++ b/ToolboxStack/output/toolbox-base/aqua.yaml
@@ -0,0 +1,18 @@
+version: 1.0.0
+registries:
+  - type: standard
+    ref: v4.200.0
+packages:
+  - name: cli/cli@v2.82.1
+  - name: jesseduffield/lazygit@v0.55.1
+  - name: direnv/direnv@v2.37.1
+  - name: dandavison/delta@0.18.2
+  - name: ajeetdsouza/zoxide@v0.9.8
+  - name: casey/just@1.43.0
+  - name: mikefarah/yq@v4.48.1
+  - name: ducaale/xh@v0.25.0
+  - name: rs/curlie@v1.8.2
+  - name: twpayne/chezmoi@v2.66.1
+  - name: mvdan/sh@v3.12.0
+  - name: koalaman/shellcheck@v0.11.0
+  - name: hadolint/hadolint@v2.14.0
--- a/ToolboxStack/output/toolbox-base/build.sh
+++ b/ToolboxStack/output/toolbox-base/build.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+IMAGE_NAME="tsysdevstack-toolboxstack-toolbox-base"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+USER_ID="${USER_ID_OVERRIDE:-$(id -u)}"
+GROUP_ID="${GROUP_ID_OVERRIDE:-$(id -g)}"
+USERNAME="${USERNAME_OVERRIDE:-toolbox}"
+TEA_VERSION="${TEA_VERSION_OVERRIDE:-0.11.1}"
+BUILDER_NAME="${BUILDER_NAME:-tsysdevstack-toolboxstack-builder}"
+CACHE_DIR="${SCRIPT_DIR}/.build-cache"
+
+echo "Building ${IMAGE_NAME} with UID=${USER_ID} GID=${GROUP_ID} USERNAME=${USERNAME}"
+
+if ! docker buildx inspect "${BUILDER_NAME}" >/dev/null 2>&1; then
+    docker buildx create --driver docker-container --name "${BUILDER_NAME}" --use >/dev/null
+else
+    docker buildx use "${BUILDER_NAME}" >/dev/null
+fi
+
+mkdir -p "${CACHE_DIR}"
+
+docker buildx build \
+    --builder "${BUILDER_NAME}" \
+    --load \
+    --progress=plain \
+    --build-arg USER_ID="${USER_ID}" \
+    --build-arg GROUP_ID="${GROUP_ID}" \
+    --build-arg USERNAME="${USERNAME}" \
+    --build-arg TEA_VERSION="${TEA_VERSION}" \
+    --cache-from "type=local,src=${CACHE_DIR}" \
+    --cache-to "type=local,dest=${CACHE_DIR},mode=max" \
+    --tag "${IMAGE_NAME}" \
+    "${SCRIPT_DIR}"
--- a/ToolboxStack/output/toolbox-base/docker-compose.yml
+++ b/ToolboxStack/output/toolbox-base/docker-compose.yml
@@ -0,0 +1,20 @@
+services:
+  toolbox-base:
+    container_name: tsysdevstack-toolboxstack-toolbox-base
+    image: tsysdevstack-toolboxstack-toolbox-base
+    build:
+      context: .
+      args:
+        USER_ID: ${LOCAL_UID:-1000}
+        GROUP_ID: ${LOCAL_GID:-1000}
+        USERNAME: ${LOCAL_USERNAME:-toolbox}
+    user: "${LOCAL_UID:-1000}:${LOCAL_GID:-1000}"
+    working_dir: /workspace
+    command: ["sleep", "infinity"]
+    init: true
+    tty: true
+    stdin_open: true
+    volumes:
+      - .:/workspace:rw
+      - ${HOME}/.local/share/mise:/home/toolbox/.local/share/mise:rw
+      - ${HOME}/.cache/mise:/home/toolbox/.cache/mise:rw
--- a/ToolboxStack/output/toolbox-base/run.sh
+++ b/ToolboxStack/output/toolbox-base/run.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COMPOSE_FILE="${SCRIPT_DIR}/docker-compose.yml"
+
+export LOCAL_UID="${USER_ID_OVERRIDE:-$(id -u)}"
+export LOCAL_GID="${GROUP_ID_OVERRIDE:-$(id -g)}"
+export LOCAL_USERNAME="${USERNAME_OVERRIDE:-toolbox}"
+
+if [[ ! -f "${COMPOSE_FILE}" ]]; then
+    echo "Error: docker-compose.yml not found at ${COMPOSE_FILE}" >&2
+    exit 1
+fi
+
+ACTION="${1:-up}"
+shift || true
+
+if [[ "${ACTION}" == "up" ]]; then
+    mkdir -p "${HOME}/.local/share/mise" "${HOME}/.cache/mise"
+fi
+
+case "${ACTION}" in
+    up)
+        docker compose -f "${COMPOSE_FILE}" up --build --detach "$@"
+        ;;
+    down)
+        docker compose -f "${COMPOSE_FILE}" down "$@"
+        ;;
+    *)
+        echo "Usage: $0 [up|down] [additional docker compose args]" >&2
+        exit 1
+        ;;
+esac