From fa12fd098335f7b8fb540be5474c7c6203fabb26 Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 29 Oct 2025 07:17:56 -0500 Subject: [PATCH] feat(toolbox-stack): add shared prompt and scaffolding template --- .../collab/TSYSDevStack-toolbox-prompt.md | 2 +- ToolboxStack/output/NewToolbox.sh | 52 +++++++++++++++++++ ToolboxStack/output/PROMPT | 17 ++++++ .../.devcontainer/devcontainer.json | 14 +++++ ToolboxStack/output/toolbox-template/PROMPT | 25 +++++++++ ToolboxStack/output/toolbox-template/SEED | 3 ++ ToolboxStack/output/toolbox-template/build.sh | 36 +++++++++++++ .../toolbox-template/docker-compose.yml | 20 +++++++ ToolboxStack/output/toolbox-template/run.sh | 35 +++++++++++++ 9 files changed, 203 insertions(+), 1 deletion(-) create mode 100755 ToolboxStack/output/NewToolbox.sh create mode 100644 ToolboxStack/output/PROMPT create mode 100644 ToolboxStack/output/toolbox-template/.devcontainer/devcontainer.json create mode 100644 ToolboxStack/output/toolbox-template/PROMPT create mode 100644 ToolboxStack/output/toolbox-template/SEED create mode 100755 ToolboxStack/output/toolbox-template/build.sh create mode 100644 ToolboxStack/output/toolbox-template/docker-compose.yml create mode 100755 ToolboxStack/output/toolbox-template/run.sh diff --git a/ToolboxStack/collab/TSYSDevStack-toolbox-prompt.md b/ToolboxStack/collab/TSYSDevStack-toolbox-prompt.md index 17853ac..46d201c 100644 --- a/ToolboxStack/collab/TSYSDevStack-toolbox-prompt.md +++ b/ToolboxStack/collab/TSYSDevStack-toolbox-prompt.md @@ -25,7 +25,7 @@ The TSYSDevStack consists of four categories: - mise - zsh / oh-my-zsh / completions / - +- See `output/PROMPT` for shared toolbox contributor guidance, `output/toolbox-base/PROMPT` for the image-specific snapshot, and `output/NewToolbox.sh` for bootstrapping new toolboxes from the template (edit each toolbox's `SEED` once to set goals, then load its PROMPT when starting work). ## toolbox-gis ## toolbox-weather - diff --git a/ToolboxStack/output/NewToolbox.sh b/ToolboxStack/output/NewToolbox.sh new file mode 100755 index 0000000..d1f5965 --- /dev/null +++ b/ToolboxStack/output/NewToolbox.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash + +set -euo pipefail + +if [[ $# -ne 1 ]]; then + echo "Usage: $0 " >&2 + exit 1 +fi + +RAW_NAME="$1" +if [[ "${RAW_NAME}" == toolbox-* ]]; then + TOOLBOX_NAME="${RAW_NAME}" +else + TOOLBOX_NAME="toolbox-${RAW_NAME}" +fi + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +TEMPLATE_DIR="${SCRIPT_DIR}/toolbox-template" +TARGET_DIR="${SCRIPT_DIR}/${TOOLBOX_NAME}" + +if [[ ! -d "${TEMPLATE_DIR}" ]]; then + echo "Error: template directory not found at ${TEMPLATE_DIR}" >&2 + exit 1 +fi + +if [[ -e "${TARGET_DIR}" ]]; then + echo "Error: ${TARGET_DIR} already exists" >&2 + exit 1 +fi + +cp -R "${TEMPLATE_DIR}" "${TARGET_DIR}" + +python3 - "$TARGET_DIR" "$TOOLBOX_NAME" <<'PY' +import sys +from pathlib import Path + +base = Path(sys.argv[1]) +toolbox_name = sys.argv[2] + +for path in base.rglob("*"): + if not path.is_file(): + continue + text = path.read_text() + updated = text.replace("{{toolbox_name}}", toolbox_name) + if updated != text: + path.write_text(updated) +PY + +echo "Created ${TARGET_DIR} from template." +echo "Next steps:" +echo " 1) Edit ${TARGET_DIR}/SEED once to describe the toolbox goals." +echo " 2) Load ${TARGET_DIR}/PROMPT in Codex; it will instruct you to read SEED and proceed." diff --git a/ToolboxStack/output/PROMPT b/ToolboxStack/output/PROMPT new file mode 100644 index 0000000..cc1bee9 --- /dev/null +++ b/ToolboxStack/output/PROMPT @@ -0,0 +1,17 @@ +You are Codex helping with TSYSDevStack ToolboxStack deliverables. + +Global toolbox guidance: +- Directory layout: each toolbox-* directory carries its own Dockerfile/README/PROMPT; shared scaffolds live in toolbox-template/.devcontainer and docker-compose.yml. +- Use ./NewToolbox.sh to scaffold a new toolbox-* directory from toolbox-template. +- Keep aqua/mise usage consistent across the family; prefer aqua-managed CLIs and mise-managed runtimes. +- Reference toolbox-template when bootstrapping a new toolbox. Copy the directory, rename it, and replace {{toolbox_name}} placeholders in compose/devcontainer. +- Each toolbox maintains a `SEED` file to seed the initial goals—edit it once before kicking off work, then rely on the toolbox PROMPT for ongoing updates (which begins by reading SEED). + +Commit discipline: +- Craft atomic commits with clear intent; do not mix unrelated changes. +- Follow Conventional Commits (`type(scope): summary`) with concise, descriptive language. +- Commit frequently as features evolve, keeping diffs reviewable. +- After documentation/tooling changes, run ./build.sh to ensure the image builds, then push once the build succeeds. +- Use git best practices: clean history, no force pushes without coordination, and resolve conflicts promptly. + +Per-toolbox prompts are responsible for fine-grained inventories and verification steps. diff --git a/ToolboxStack/output/toolbox-template/.devcontainer/devcontainer.json b/ToolboxStack/output/toolbox-template/.devcontainer/devcontainer.json new file mode 100644 index 0000000..39a2fbc --- /dev/null +++ b/ToolboxStack/output/toolbox-template/.devcontainer/devcontainer.json @@ -0,0 +1,14 @@ +{ + "name": "TSYSDevStack {{toolbox_name}}", + "dockerComposeFile": [ + "../docker-compose.yml" + ], + "service": "{{toolbox_name}}", + "workspaceFolder": "/workspace", + "remoteUser": "toolbox", + "runServices": [ + "{{toolbox_name}}" + ], + "overrideCommand": false, + "postCreateCommand": "zsh -lc 'starship --version >/dev/null'" +} diff --git a/ToolboxStack/output/toolbox-template/PROMPT b/ToolboxStack/output/toolbox-template/PROMPT new file mode 100644 index 0000000..c7792b1 --- /dev/null +++ b/ToolboxStack/output/toolbox-template/PROMPT @@ -0,0 +1,25 @@ +You are Codex, collaborating with a human on the TSYSDevStack ToolboxStack project. + +- Seed context: + - `SEED` captures the initial scope. Edit it once to define goals, then treat it as read-only unless the high-level objectives change. + - Start each session by reading it (`cat SEED`) and summarize progress or adjustments here in PROMPT. + +Context snapshot ({{toolbox_name}}): +- Working directory: artifacts/ToolboxStack/{{toolbox_name}} +- Image: tsysdevstack-toolboxstack-{{toolbox_name}} (Ubuntu 24.04) +- Container user: toolbox (non-root, UID/GID mapped to host) +- Mounted workspace: current repo at /workspace (rw) + +Current state: +- Seed items above still need to be translated into Dockerfile/tooling work. +- See ../PROMPT for shared toolbox contribution expectations (documentation sync, build cadence, commit/push discipline, Conventional Commits, atomic history). + +Collaboration checklist: +1. Translate SEED goals into concrete tooling decisions; mirror outcomes in README.md and this PROMPT (do not rewrite SEED unless the scope resets). +2. Prefer aqua-managed CLIs and mise-managed runtimes for reproducibility. +3. After each tooling change, update README/PROMPT, run ./build.sh, commit (Conventional Commit message, focused diff), and push only once the build succeeds per ../PROMPT. +4. Record verification steps (build/test commands) as they are performed. +5. Maintain UID/GID mapping and non-root execution. + +Active focus: +- Initialize {{toolbox_name}} using the toolbox-template scaffolding; evolve the Dockerfile/tooling inventory to satisfy the SEED goals. diff --git a/ToolboxStack/output/toolbox-template/SEED b/ToolboxStack/output/toolbox-template/SEED new file mode 100644 index 0000000..19a2336 --- /dev/null +++ b/ToolboxStack/output/toolbox-template/SEED @@ -0,0 +1,3 @@ +- TODO: describe what this toolbox should provide (languages, CLIs, workflows). +- TODO: list required base image modifications or additional mounts. +- TODO: note verification or testing expectations specific to this toolbox. diff --git a/ToolboxStack/output/toolbox-template/build.sh b/ToolboxStack/output/toolbox-template/build.sh new file mode 100755 index 0000000..df4d133 --- /dev/null +++ b/ToolboxStack/output/toolbox-template/build.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash + +set -euo pipefail + +IMAGE_NAME="tsysdevstack-toolboxstack-{{toolbox_name}}" +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}" diff --git a/ToolboxStack/output/toolbox-template/docker-compose.yml b/ToolboxStack/output/toolbox-template/docker-compose.yml new file mode 100644 index 0000000..7af96ae --- /dev/null +++ b/ToolboxStack/output/toolbox-template/docker-compose.yml @@ -0,0 +1,20 @@ +services: + {{toolbox_name}}: + container_name: tsysdevstack-toolboxstack-{{toolbox_name}} + image: tsysdevstack-toolboxstack-{{toolbox_name}} + 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 diff --git a/ToolboxStack/output/toolbox-template/run.sh b/ToolboxStack/output/toolbox-template/run.sh new file mode 100755 index 0000000..c36bb2d --- /dev/null +++ b/ToolboxStack/output/toolbox-template/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