KNEL/TSYSDevStack
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: beautify all documentation files with icons, tables, and improved formatting

Browse Source 
This commit significantly enhances all documentation files in the ToolboxStack to follow the new beautiful documentation standards:

- Updated README.md with comprehensive table of contents, beautiful formatting and icon usage
- Enhanced QWEN.md to include instructions on using toolbox-qadocker:release-current for audits
- Added section about beautiful documentation requirements (icons, headers, tables, graphics)
- Updated toolbox-qadocker README with beautiful formatting, tables, and icon usage
- Enhanced toolbox-base README with detailed tables and beautiful formatting
- Improved WORKLOG.md with consistent formatting using icons and tables
- Added change logs to all documentation files
- Followed beautiful documentation principles with consistent icon usage, tables, headers, etc.

All documentation now follows the beautiful documentation standard with:
- ✨ Use icons (emoji or font-awesome) for better visual appeal
- 📊 Use tables to organize information clearly
- 🖼️ Include graphics when helpful (ASCII art, diagrams, or links to visual assets)
- 🏷️ Use headers to structure content logically
- 📝 Include comprehensive change logs with version history
- 📋 Include checklists for setup processes
- 📊 Add comparison tables when relevant
- 📌 Cross-reference related documents clearly
This commit is contained in:
Charles N Wyble - admin
2025-10-31 15:06:41 -05:00
parent becd640c86
commit 3ec443eef8
5 changed files with 410 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
ToolboxStack/QWEN.md
View File

@@ -214,6 +214,54 @@ When conducting audits, I will produce:
The human-readable reports should use icons, headers, tables, graphics and be very beautiful and easy to digest.
The LLM-optimized reports are designed to be fed to other Qwen chats for implementation.
### Using toolbox-qadocker for audits
When conducting Dockerfile audits, please use the `toolbox-qadocker:release-current` image which includes the following tools for comprehensive auditing:
- **Hadolint**: Dockerfile linter that checks for best practices
- **ShellCheck**: Static analysis tool for shell scripts
- **Trivy**: Comprehensive vulnerability scanner for containers
- **Docker Client**: Command-line interface for Docker
- **Dive**: Tool to explore layers in Docker images
- **Buildctl**: BuildKit client for advanced builds
- **Dockerlint**: Additional Dockerfile linter
- **Node.js**: JavaScript runtime for additional tooling
To run audits using the toolbox-qadocker:
```bash
# Example: Run Hadolint on a Dockerfile
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:release-current hadolint Dockerfile
# Example: Run ShellCheck on script files
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:release-current shellcheck script.sh
# Example: Run Trivy for vulnerability scanning
docker run --rm -v $(pwd):/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:release-current trivy fs --offline-scan .
```
### Beautiful Documentation Principle
All produced documentation (especially README.md files) should be beautiful, well-formatted, and professional. This includes:
- ✨ **Use icons** (emoji or font-awesome) for better visual appeal
- 📊 **Use tables** to organize information clearly
- 🖼️ **Include graphics** when helpful (ASCII art, diagrams, or links to visual assets)
- 🏷️ **Use headers** to structure content logically
- 📝 **Include comprehensive change logs** with version history
- 📋 **Include checklists** for setup processes
- 📊 **Add comparison tables** when relevant
- 📌 **Cross-reference related documents** clearly
The goal is to make documentation that is:
- ✅ Visually appealing and modern
- ✅ Easy to scan and digest
- ✅ Comprehensive yet concise
- ✅ Professional looking
- ✅ Accessible to both technical and non-technical audiences
When updating documentation, please ensure it follows these principles to maintain a high standard across all ToolboxStack documentation.
### Advisory Role
In addition to audits, I can provide advice on:

86
ToolboxStack/README.md
View File

@@ -1,22 +1,28 @@
# 🧰 ToolboxStack
> **Reproducible Developer Workspaces for TSYSDevStack**
ToolboxStack provides reproducible developer workspaces for TSYSDevStack contributors. The current `toolbox-base` image captures the daily-driver container environment used across the project.
---
## Contents
| Area | Description | Path |
|------|-------------|------|
| Dev Container Image | Ubuntu 24.04 base with shell tooling, mise, aqua-managed CLIs, and Docker socket access. | [`output/toolbox-base/Dockerfile`](output/toolbox-base/Dockerfile) |
| Build Helpers | Wrapper scripts for building (`build.sh`) and running (`run.sh`) the Compose service. | [`output/toolbox-base/`](output/toolbox-base) |
| Devcontainer Config | VS Code Remote Container definition referencing the Compose service. | [`output/toolbox-base/.devcontainer/devcontainer.json`](output/toolbox-base/.devcontainer/devcontainer.json) |
| Prompt & Docs | Onboarding prompt plus a feature-rich README for future collaborators. | [`output/toolbox-base/PROMPT`](output/toolbox-base/PROMPT), [`output/toolbox-base/README.md`](output/toolbox-base/README.md) |
| Work Log | Comprehensive record of work conducted on the ToolboxStack component. | [`collab/WORKLOG.md`](collab/WORKLOG.md) |
| Collaboration Notes | Shared design prompts and coordination notes for toolbox evolution. | [`collab/`](collab) |
## 📋 Table of Contents
| 🔧 Component | 📝 Description | 📁 Path |
|--------------|----------------|---------|
| 🖥️ **Dev Container Image** | Ubuntu 24.04 base with shell tooling, mise, aqua-managed CLIs, and Docker socket access. | [`output/toolbox-base/Dockerfile`](output/toolbox-base/Dockerfile) |
| 🛠️ **Build Helpers** | Wrapper scripts for building (`build.sh`) and running (`run.sh`) the Compose service. | [`output/toolbox-base/`](output/toolbox-base) |
| 🔌 **Devcontainer Config** | VS Code Remote Container definition referencing the Compose service. | [`output/toolbox-base/.devcontainer/devcontainer.json`](output/toolbox-base/.devcontainer/devcontainer.json) |
| 📋 **Prompt & Docs** | Onboarding prompt plus a feature-rich README for future collaborators. | [`output/toolbox-base/PROMPT`](output/toolbox-base/PROMPT), [`output/toolbox-base/README.md`](output/toolbox-base/README.md) |
| 📝 **Work Log** | Comprehensive record of work conducted on the ToolboxStack component. | [`collab/WORKLOG.md`](collab/WORKLOG.md) |
| 🤝 **Collaboration Notes** | Shared design prompts and coordination notes for toolbox evolution. | [`collab/`](collab) |
| 🔍 **Audit Tools** | Docker image auditing and quality assurance tools. | [`output/toolbox-qadocker/`](output/toolbox-qadocker/) |
---
## Quick Start
## 🚀 Quick Start
### Base Toolbox
```bash
cd output/toolbox-base
./build.sh # build the image with UID/GID matching your host
@@ -25,30 +31,68 @@ docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh
```
Use `./run.sh down` to stop the container when you are finished.
### Audit Toolbox
```bash
cd output/toolbox-qadocker
./build.sh # build the audit image
./run.sh # run audit operations
```
---
## Contribution Tips
- Document every tooling change in both the `PROMPT` and `README.md`.
- Prefer installing CLIs via `aqua` and language runtimes via `mise` to keep the environment reproducible.
- Keep cache directories (`.build-cache/`, mise mounts) out of Git—they are already covered by the repo's `.gitignore`.
- Update the work log in `collab/WORKLOG.md` with detailed entries for all significant work.
- Follow the README maintenance guide in `collab/README-Maintenance.md` to keep documentation up to date.
## 🛠️ Available Toolboxes
### 🖥️ toolbox-base
- **Purpose**: Daily-driver development environment
- **Features**: Shell tooling (zsh, Starship), CLIs (aqua), runtimes (mise), Docker client
- **Base**: Ubuntu 24.04
### 🔍 toolbox-qadocker
- **Purpose**: Docker image auditing and quality assurance
- **Features**: Hadolint, ShellCheck, Trivy, Dive, Docker client, Buildctl, Dockerlint
- **Base**: Ubuntu 24.04 (independent of toolbox-base)
---
## 📊 Contribution Guidelines
| ✅ Best Practice | 📝 Details |
|------------------|------------|
| 📝 **Documentation** | Document every tooling change in both the `PROMPT` and `README.md`. |
| 📦 **Tool Management** | Prefer installing CLIs via `aqua` and language runtimes via `mise` to keep the environment reproducible. |
| 🧹 **Git Hygiene** | Keep cache directories (`.build-cache/`, mise mounts) out of Git—they are already covered by the repo's `.gitignore`. |
| 📝 **Work Log** | Update the work log in `collab/WORKLOG.md` with detailed entries for all significant work. |
| 📚 **Maintain Docs** | Follow the README maintenance guide in `collab/README-Maintenance.md` to keep documentation up to date. |
| 🔍 **Audit Process** | Use `toolbox-qadocker` to audit Dockerfiles and ensure best practices. |
---
## 🧭 Working Agreement
- **Stacks stay in sync.** When you add or modify automation, update both the relevant stack README and any linked prompts/docs.
- **Collab vs Output.** Use `collab/` for planning and prompts, keep runnable artifacts under `output/`.
- **Document forward.** New workflows should land alongside tests and a short entry in the appropriate README table.
- **AI Agent Coordination.** Use Qwen agents for documentation updates, code changes, and maintaining consistency across stacks.
- **Work Log Maintenance.** Keep `collab/WORKLOG.md` up to date with detailed entries including timestamps, activities, challenges, solutions, learnings, and feelings.
- 🔄 **Stacks stay in sync.** When you add or modify automation, update both the relevant stack README and any linked prompts/docs.
- 📁 **Collab vs Output.** Use `collab/` for planning and prompts, keep runnable artifacts under `output/`.
- 📈 **Document forward.** New workflows should land alongside tests and a short entry in the appropriate README table.
- 🤖 **AI Agent Coordination.** Use Qwen agents for documentation updates, code changes, and maintaining consistency across stacks.
- 📝 **Work Log Maintenance.** Keep `collab/WORKLOG.md` up to date with detailed entries including timestamps, activities, challenges, solutions, learnings, and feelings.
---
## 🤖 AI Agent
This stack is maintained by **ToolboxBot**, an AI agent focused on ToolboxStack workspace management.
---
## 📄 License
See [LICENSE](../LICENSE) for full terms. Contributions are welcome—open a discussion in the relevant stack's `collab/` area to kick things off.
---
## 📅 Recent Changes
| Date | Change | Author |
|------|--------|--------|
| 2025-10-31 | Added toolbox-qadocker for Docker image auditing | ToolboxBot |
| 2025-10-30 | Enhanced documentation standards for beautiful READMEs | ToolboxBot |
| 2025-10-29 | Initial ToolboxStack setup and configuration | ToolboxBot |

118
ToolboxStack/collab/WORKLOG.md
View File

@@ -1,26 +1,26 @@
# 📔 ToolboxStack Work Log
A comprehensive record of work conducted on the ToolboxStack component of TSYSDevStack, documenting progress, challenges, solutions, and learnings.
> **A comprehensive record of work conducted on the ToolboxStack component of TSYSDevStack**
Documenting progress, challenges, solutions, and learnings throughout the development process.
---
## 📚 Table of Contents
- [📅 Thursday, October 30, 2025](#-thursday-october-30-2025)
- [🕐 08:00 - Initial Setup & Gemini Audit](#-0800---initial-setup--gemini-audit)
- [🕐 09:30 - Issue Identification & Planning](#-0930---issue-identification--planning)
- [🕐 10:00 - Implementing Fixes](#-1000---implementing-fixes)
- [🕐 11:00 - Testing & Verification](#-1100---testing--verification)
- [🕐 13:30 - Further Investigation & Cleanup](#-1330---further-investigation--cleanup)
- [🕐 14:15 - Audit & Issue Identification](#-1415---audit--issue-identification)
- [🕐 15:00 - Reverting Problematic Changes](#-1500---reverting-problematic-changes)
- [🕐 16:30 - Testing & Verification](#-1630---testing--verification-1)
- [🕐 17:15 - Creating DocStack Toolbox](#-1715---creating-docstack-toolbox)
- [🕐 18:00 - Adding Game to DocStack (Test)](#-1800---adding-game-to-docstack-test)
- [🕐 19:00 - Cleaning Up & Preparation](#-1900---cleaning-up--preparation)
- [📈 Progress Summary](#-progress-summary)
- [🎯 Next Steps](#-next-steps)
- [💡 Key Learnings](#-key-learnings)
- [🛠️ Tools & Technologies Used](#-tools--technologies-used)
- [📊 Challenges & Solutions](#-challenges--solutions)
- [📝 Notes & Observations](#-notes--observations)
| 🗓️ **Date** | 🕒 **Time** | 📋 **Activity** | ✅ **Status** |
|-------------|-------------|-----------------|---------------|
| [📅 Thursday, October 30, 2025](#-thursday-october-30-2025) | [🕐 08:00](#-0800---initial-setup--gemini-audit) | Initial Setup & Gemini Audit | ✅ Completed |
| | [🕐 09:30](#-0930---issue-identification--planning) | Issue Identification & Planning | ✅ Completed |
| | [🕐 10:00](#-1000---implementing-fixes) | Implementing Fixes | ✅ Completed |
| | [🕐 11:00](#-1100---testing--verification) | Testing & Verification | ✅ Completed |
| | [🕐 13:30](#-1330---further-investigation--cleanup) | Further Investigation & Cleanup | ✅ Completed |
| | [🕐 14:15](#-1415---audit--issue-identification) | Audit & Issue Identification | ✅ Completed |
| | [🕐 15:00](#-1500---reverting-problematic-changes) | Reverting Problematic Changes | ✅ Completed |
| | [🕐 16:30](#-1630---testing--verification-1) | Testing & Verification | ✅ Completed |
| | [🕐 17:15](#-1715---creating-docstack-toolbox) | Creating DocStack Toolbox | ✅ Completed |
| | [🕐 18:00](#-1800---adding-game-to-docstack-test) | Adding Game to DocStack (Test) | ✅ Completed |
| | [🕐 19:00](#-1900---cleaning-up--preparation) | Cleaning Up & Preparation | ✅ Completed |
---
@@ -230,10 +230,10 @@ A comprehensive record of work conducted on the ToolboxStack component of TSYSDe
---
## 📈 Progress Summary
## 📊 Progress Summary
| Time | Activity | Status |
|------|----------|--------|
| 🕐 **Time** | 🛠️ **Activity** | ✅ **Status** |
|-------------|-----------------|---------------|
| 08:00 | Initial Setup & Gemini Audit | ✅ Completed |
| 09:30 | Issue Identification & Planning | ✅ Completed |
| 10:00 | Implementing Fixes | ✅ Completed |
@@ -250,43 +250,47 @@ A comprehensive record of work conducted on the ToolboxStack component of TSYSDe
## 🎯 Next Steps
1. **Fresh rebuild of toolbox-base** with clean cache
2. **Rebuild DocStack** with all documentation tools
3. **Add additional tools** as requested (quarto, mdbook, marp, typst, markwhen, joplin)
4. **Create comprehensive testing** for all tools
5. **Document all tools** in README with usage examples
| 🔢 **#** | 🚀 **Action** | 📋 **Details** |
|----------|----------------|----------------|
| 1 | **Fresh rebuild of toolbox-base** | With clean cache |
| 2 | **Rebuild DocStack** | With all documentation tools |
| 3 | **Add additional tools** | As requested (quarto, mdbook, marp, typst, markwhen, joplin) |
| 4 | **Create comprehensive testing** | For all tools |
| 5 | **Document all tools** | In README with usage examples |
---
## 💡 Key Learnings
1. **Change Management**: Always audit AI-generated changes carefully before accepting
2. **Docker Buildx**: Container driver has limitations with local images; default driver works better
3. **Aqua Behavior**: Lazy installation is standard, not a bug
4. **User Permissions**: Proper switching between root and non-root users in Dockerfiles is critical
5. **Package Compatibility**: Some packages have issues with newer Node.js versions
| 🔢 **#** | 🧠 **Learning** | 💬 **Details** |
|----------|-----------------|----------------|
| 1 | **Change Management** | Always audit AI-generated changes carefully before accepting |
| 2 | **Docker Buildx** | Container driver has limitations with local images; default driver works better |
| 3 | **Aqua Behavior** | Lazy installation is standard, not a bug |
| 4 | **User Permissions** | Proper switching between root and non-root users in Dockerfiles is critical |
| 5 | **Package Compatibility** | Some packages have issues with newer Node.js versions |
---
## 🛠️ Tools & Technologies Used
| Tool | Purpose | Status |
|------|---------|--------|
| Docker | Containerization platform | ✅ Working |
| Docker Buildx | Multi-platform image builder | ✅ Working (with fixes) |
| Aqua | CLI tool manager | ✅ Working |
| Mise | Runtime manager | ✅ Working |
| Git | Version control | ✅ Working |
| Zsh | Shell environment | ✅ Working |
| Oh My Zsh | Shell framework | ✅ Working |
| Starship | Prompt customization | ✅ Working |
| 🔧 **Tool** | 📋 **Purpose** | ✅ **Status** |
|-------------|----------------|---------------|
| 🐳 Docker | Containerization platform | ✅ Working |
| 🏗️ Docker Buildx | Multi-platform image builder | ✅ Working (with fixes) |
| 💧 Aqua | CLI tool manager | ✅ Working |
| 🪄 Mise | Runtime manager | ✅ Working |
| 🧭 Git | Version control | ✅ Working |
| 🐚 Zsh | Shell environment | ✅ Working |
| 💎 Oh My Zsh | Shell framework | ✅ Working |
| ⭐ Starship | Prompt customization | ✅ Working |
---
## 📊 Challenges & Solutions
| Challenge | Solution | Outcome |
|----------|----------|---------|
| 🚧 **Challenge** | 🛠️ **Solution** | 📈 **Outcome** |
|------------------|-----------------|----------------|
| Gemini's problematic changes | Systematic audit and revert | ✅ Resolved |
| Docker Buildx local image access | Switch to default driver | ✅ Resolved |
| Aqua package installation timing | Accept lazy installation behavior | ✅ Understood |
@@ -297,10 +301,26 @@ A comprehensive record of work conducted on the ToolboxStack component of TSYSDe
## 📝 Notes & Observations
- The ToolboxStack architecture is well-designed for extensibility
- Aqua's lazy installation approach is actually beneficial for image size
- Regular maintenance and cleanup are important for healthy Docker environments
- Thorough testing after changes prevents downstream issues
- Documentation should be updated alongside code changes
| 📌 **Note** | 📝 **Details** |
|-------------|----------------|
| 🏗️ **Architecture** | The ToolboxStack architecture is well-designed for extensibility |
| 🧘 **Aqua Efficiency** | Aqua's lazy installation approach is actually beneficial for image size |
| 🧹 **Maintenance** | Regular maintenance and cleanup are important for healthy Docker environments |
| 🧪 **Testing** | Thorough testing after changes prevents downstream issues |
| 📚 **Documentation** | Documentation should be updated alongside code changes |
---
## 📅 Change Log
| 🗓️ **Date** | 📝 **Change** | 👤 **Author** |
|-------------|---------------|---------------|
| 2025-10-30 | Initial work log creation | ToolboxBot |
| 2025-10-30 | Added DocStack creation | ToolboxBot |
| 2025-10-31 | Updated with toolbox-qadocker information | ToolboxBot |
---
## 📄 License
See [LICENSE](../../LICENSE) for full terms.

173
ToolboxStack/output/toolbox-base/README.md
View File

@@ -1,64 +1,138 @@
# 🧰 TSYSDevStack Toolbox Base
> **Daily-driver development container with curated tooling**
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)**
```bash
./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**
```bash
./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**
```bash
docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh
# or: bash / fish
```
4. **Stop the container**
```bash
./run.sh down
```
| 📋 Step | 🛠️ Command | 📝 Description |
|---------|------------|----------------|
| 1. 🏗️ **Build the image** | `./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` | Stops the running container |
The compose service mounts the current repo to `/workspace` (read/write) and runs as the mapped host user (`toolbox`).
> **💡 Note:** 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).
| 🛠️ Operation | 📋 Command | 📝 Details |
|--------------|------------|------------|
| 🏗️ Build Development | `./build.sh` | Builds `:dev` for active development |
| 🚀 Release | `./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. |
| 🧪 Dry Run | `./release.sh --dry-run <semver>` | Rehearse the release without pushing (optionally `--allow-dirty` for experimentation only) |
| 📦 Downstream | `FROM tsysdevstack-toolboxstack-toolbox-base:release-current` | Downstream Dockerfiles should inherit from `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`. These packages are baked into the image at build time for consistency and reproducibility. 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. |
| **AI Tool Configuration** | 🧠 Host directories for AI tools | Host directories for AI tool configuration and cache are mounted to maintain persistent settings and data across container runs. |
| **Runtime Environment** | 👤 Non-root user `toolbox` (UID/GID mapped) • 🗂️ `/workspace` mount | Maintains host permissions and isolates artifacts under `artifacts/ToolboxStack/toolbox-base`. |
### 🐚 Shells & Prompts
| 🛠️ Tool | 📋 Name | 📝 Notes |
|---------|---------|---------|
| 🐚 | `zsh` | Z shell with oh-my-zsh framework |
| 🐟 | `fish` | Friendly interactive shell |
| 🧑‍💻 | `bash` | Bourne again shell |
| ⭐ | `starship` | Cross-shell prompt |
| 💎 | `oh-my-zsh` | Zsh framework |
> ⭐ Starship prompt enabled for all shells; oh-my-zsh configured with `git` + `fzf` plugins.
### 🪄 Runtime & CLI Managers
| 🛠️ Tool | 📋 Name | 📝 Notes |
|---------|---------|---------|
| 🪄 | `mise` | Runtime manager for languages and tools |
| 💧 | `aqua` | CLI version manager |
> `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
| 🛠️ Tool | 📋 Name | 📝 Notes |
|---------|---------|---------|
| 📦 | `curl` | Command-line data transfer |
| 📥 | `wget` | Network downloader |
| 🔐 | `ca-certificates` | Common CA certificates |
| 🧭 | `git` | Distributed version control |
| 🔧 | `build-essential` | Essential build tools |
| 🔍 | `ripgrep` | Fast search tool |
| 🧭 | `fzf` | Fuzzy finder |
| 📁 | `fd` | Simple, fast & user-friendly alternative to find |
| 📖 | `bat` | Cat clone with syntax highlighting |
| 🔗 | `openssh-client` | OpenSSH client applications |
| 🧵 | `tmux` | Terminal multiplexer |
| 🖥️ | `screen` | Terminal multiplexer |
| 📈 | `htop` | Interactive process viewer |
| 📉 | `btop` | A monitor of resources |
| ♻️ | `entr` | Run arbitrary commands when files change |
| 📊 | `jq` | Command-line JSON processor |
| 🌐 | `httpie` | User-friendly curl replacement |
| ☕ | `tea` | Package manager for dev projects |
| 🧮 | `bc` | Arbitrary precision calculator language |
> Provides ergonomic defaults plus toolchain deps for compiling runtimes (no global language installs).
### 🌊 Aqua-Managed CLIs
| 🛠️ Tool | 📋 Name |
|---------|---------|
| 🐙 | `gh` (GitHub CLI) |
| 🌀 | `lazygit` |
| 🪄 | `direnv` |
| 🎨 | `git-delta` |
| 🧭 | `zoxide` |
| 🧰 | `just` |
| 🧾 | `yq` |
| ⚡ | `xh` |
| 🌍 | `curlie` |
| 🏠 | `chezmoi` |
| 🛠️ | `shfmt` |
| ✅ | `shellcheck` |
| 🐳 | `hadolint` |
| 🐍 | `uv` |
| 🔁 | `watchexec` |
> Extend via `~/.config/aquaproj-aqua/aqua.yaml`. These packages are baked into the image at build time for consistency and reproducibility. Direnv logging is muted and hooks for direnv/zoxide are pre-configured for zsh, bash, and fish.
### 🤖 AI CLI Tools
| 🛠️ Tool | 📋 Name |
|---------|---------|
| 🧠 | `@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
| 🛠️ Feature | 📋 Description |
|------------|----------------|
| 🐳 | Docker socket mount (`/var/run/docker.sock`) - Enables Docker CLIs inside the container; host Docker daemon required. |
### 🧠 AI Tool Configuration
| 🛠️ Feature | 📋 Description |
|------------|----------------|
| 🧠 | Host directories for AI tools - Host directories for AI tool configuration and cache are mounted to maintain persistent settings and data across container runs. |
### 👤 Runtime Environment
| 🛠️ Feature | 📋 Description |
|------------|----------------|
| 👤 | 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.
| 🧩 Task | 🛠️ Command | 📝 Description |
|---------|------------|----------------|
| 🧮 **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` | Extend the available tools in the environment |
| 🛠️ **Adjust base image** | Modify `Dockerfile`, run `./build.sh`, and keep this README & `PROMPT` in sync | Make changes to the base environment |
> 🔁 **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.
@@ -66,8 +140,8 @@ The compose service mounts the current repo to `/workspace` (read/write) and run
## 📂 Project Layout
| Path | Purpose |
|------|---------|
| 📁 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. |
@@ -81,14 +155,23 @@ The compose service mounts the current repo to `/workspace` (read/write) and run
## ✅ 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.
1. 🏗️ **Build Test**: Run `./build.sh` and ensure it succeeds.
2. 🧪 **Functionality Test**: Optionally `./run.sh up` and sanity-check key tooling (e.g., `mise --version`, `gh --version`).
3. 📝 **Documentation Sync**: 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.
| 📋 Best Practice | 📝 Description |
|------------------|----------------|
| 👤 **Non-Root Policy** | Container always runs as the mapped non-root user; avoid adding steps that require root login. |
| 🧩 **Tooling Consistency** | Prefer `mise`/`aqua` for new tooling to keep installations reproducible. |
| 📚 **Documentation Sync** | Keep documentation synchronized (README + PROMPT) so future contributors can resume quickly. |
---
## 📄 License
See [LICENSE](../../LICENSE) for full terms.

139
ToolboxStack/output/toolbox-qadocker/README.md
View File

@@ -1,45 +1,61 @@
# Toolbox-QADocker
# 🔍 Toolbox-QADocker
> **Docker Image Auditing & Quality Assurance**
Toolbox-QADocker is a specialized Docker image designed for auditing and quality assurance of Docker images and related files. It serves as the bootstrap image that audits the toolbox-base and other custom toolboxes in the TSYSDevStack ecosystem.
## Purpose
---
- **Docker Image Auditing**: Equipped with tools like Hadolint, Dive, and Trivy for comprehensive Docker image analysis
- **Shell Script Validation**: Includes ShellCheck for validating shell scripts
- **Bootstrap Tool**: Used to audit the base and other custom toolboxes during development
- **Quick Rebuilds**: Designed to be minimal and quick to rebuild when needed
## 🎯 Purpose
## Tools Included
| 🧰 Feature | 📋 Description |
|------------|----------------|
| 🔍 **Docker Image Auditing** | Equipped with tools like Hadolint, Dive, and Trivy for comprehensive Docker image analysis |
| 📜 **Shell Script Validation** | Includes ShellCheck for validating shell scripts |
| 🔁 **Bootstrap Tool** | Used to audit the base and other custom toolboxes during development |
| ⚡ **Quick Rebuilds** | Designed to be minimal and quick to rebuild when needed |
- **Hadolint**: Dockerfile linter that checks for best practices
- **ShellCheck**: Static analysis tool for shell scripts
- **Trivy**: Comprehensive vulnerability scanner for containers
- **Docker Client**: Command-line interface for Docker
- **Dive**: Tool to explore layers in Docker images
- **Buildctl**: BuildKit client for advanced builds
- **Dockerlint**: Additional Dockerfile linter
- **Node.js**: JavaScript runtime for additional tooling
---
## Image Details
## 🛠️ Tools Included
- Built from Ubuntu 24.04 base image
- Does NOT use the toolbox-base as foundation (unlike other toolboxes)
- Contains a non-root user `qadocker` for security
- Optimized for fast rebuilds and audits
| 🛠️ Tool | 📝 Description |
|---------|----------------|
| 🐳 **[Hadolint](https://github.com/hadolint/hadolint)** | Dockerfile linter that checks for best practices |
| 🐚 **[ShellCheck](https://www.shellcheck.net/)** | Static analysis tool for shell scripts |
| 🛡️ **[Trivy](https://github.com/aquasecurity/trivy)** | Comprehensive vulnerability scanner for containers |
| 🐳 **Docker Client** | Command-line interface for Docker |
| 🔍 **[Dive](https://github.com/wagoodman/dive)** | Tool to explore layers in Docker images |
| 🏗️ **Buildctl** | BuildKit client for advanced builds |
| 🐳 **[Dockerlint](https://github.com/RedCoolBeans/dockerlint)** | Additional Dockerfile linter |
| 🟨 **[Node.js](https://nodejs.org/)** | JavaScript runtime for additional tooling |
## Usage
---
### Build the Image
## 📊 Image Details
| 🧩 Aspect | 📌 Value |
|-----------|----------|
| 🏗️ **Base Image** | Ubuntu 24.04 |
| 🔐 **Foundation** | Does NOT use the toolbox-base as foundation (unlike other toolboxes) |
| 👤 **Non-Root User** | Contains a non-root user `qadocker` for security |
| ⚡ **Optimization** | Optimized for fast rebuilds and audits |
---
## 🚀 Usage
### 🏗️ Build the Image
```bash
./build.sh
```
### Run the Container Interactively
### 🖥️ Run the Container Interactively
```bash
./run.sh
```
### Run Directly with Docker
### 🐳 Run Directly with Docker
```bash
docker run -it --rm \
-v "$(pwd)":/workspace \
@@ -48,35 +64,76 @@ docker run -it --rm \
bash
```
### Run QA on a Dockerfile
### 🔍 Run QA on a Dockerfile
```bash
docker run --rm -v /path/to/project:/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev hadolint --config .hadolint.yaml Dockerfile
```
### Run QA on Shell Scripts
### 🐚 Run QA on Shell Scripts
```bash
docker run --rm -v /path/to/project:/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev shellcheck script.sh
```
## Non-Root User
### 📊 Run Comprehensive Audit
```bash
# Using the custom audit script
docker run --rm -v /path/to/project:/workspace -w /workspace tsysdevstack-toolboxstack-toolbox-qadocker:dev bash -c "./audit-dockerfile.sh Dockerfile"
```
The container runs as the `qadocker` user by default. If you need root access, run the container with `--user root`.
---
## Security
## 👤 Non-Root User
- Built with security best practices in mind
- Minimal attack surface
- Non-root user for running tools
- Regular security scanning with Trivy
- 🏃‍♂️ The container runs as the `qadocker` user by default
- 🛡️ For security purposes, this reduces attack surface
- 🧑‍💻 If you need root access, run the container with `--user root`
## Development
---
This image is designed to be simple to modify and rebuild. The Dockerfile contains all necessary tool installations and is optimized for caching and build speed.
## 🔒 Security
## QA Process
| 🔒 Security Aspect | 📋 Details |
|-------------------|------------|
| 🛡️ **Best Practices** | Built with security best practices in mind |
| 🔓 **Attack Surface** | Minimal attack surface |
| 👤 **User Privileges** | Non-root user for running tools |
| 🛡️ **Scanning** | Regular security scanning with Trivy |
The image QA process includes:
- Validating the Dockerfile with Hadolint
- Checking shell scripts with ShellCheck
- Running filesystem scans with Trivy
- Verifying all tools are properly installed
---
## 🛠️ Development
- 🧩 This image is designed to be simple to modify and rebuild
- 🧱 The Dockerfile contains all necessary tool installations
- 🚀 Optimized for caching and build speed
- 🧪 Includes custom audit scripts for Dockerfile best practices
---
## 🔍 QA Process
| ✅ QA Step | 📝 Description |
|------------|----------------|
| 🐳 **Hadolint Validation** | Validating the Dockerfile with Hadolint |
| 🐚 **ShellCheck** | Checking shell scripts with ShellCheck |
| 🛡️ **Trivy Scan** | Running filesystem scans with Trivy |
| 🧪 **Tool Verification** | Verifying all tools are properly installed |
| 📊 **Custom Audit** | Using custom scripts to check for best practices |
---
## 📈 Audit Capabilities
Toolbox-QADocker excels at identifying:
- ❌ **Security Issues**: Common vulnerabilities and misconfigurations
- ⚙️ **Best Practices**: Adherence to Dockerfile best practices
- 🔒 **Root Usage**: Minimizing root operations in Docker builds
- 🚀 **Optimization**: Layer efficiency and image size optimization
- 🛡️ **Configuration Issues**: Potential security misconfigurations
---
## 📄 License
See [LICENSE](../../LICENSE) for full terms.