From cf66c9a0652bf368adc954d86209247347c7a85f Mon Sep 17 00:00:00 2001 From: ReachableCEO Date: Wed, 17 Sep 2025 11:07:06 -0500 Subject: [PATCH] ci: add Gitea Actions workflow and Docker Compose test runner; add test image\n\ngovernance: encode CI/containers rules in system prompts and AGENTS templates; update proposal and docs --- .gitea/workflows/ci.yml | 17 +++++++++++++++++ collab/proposals/01-codexhelper.llm.md | 10 ++++++---- collab/proposals/01-codexhelper.md | 7 +++++-- docker/compose.yml | 19 +++++++++++++++++++ docker/test/Dockerfile | 11 +++++++++++ docs/devlog/DEVLOG_LLM.md | 10 ++++++++++ docs/wrapper.md | 3 ++- meta/AGENTS.seed.llm.md | 2 ++ meta/AGENTS.seed.md | 7 +++++++ prompts/global/system.llm.md | 8 ++++++++ prompts/global/system.md | 9 +++++++++ scripts/test.docker.sh | 12 ++++++++++++ templates/project/_shared/AGENTS.md | 6 ++++++ 13 files changed, 114 insertions(+), 7 deletions(-) create mode 100644 .gitea/workflows/ci.yml create mode 100644 docker/compose.yml create mode 100644 docker/test/Dockerfile create mode 100644 scripts/test.docker.sh diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml new file mode 100644 index 0000000..eb8491d --- /dev/null +++ b/.gitea/workflows/ci.yml @@ -0,0 +1,17 @@ +name: ci + +on: + push: + pull_request: + +jobs: + test: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v3 + - name: Build and run tests via Docker + run: | + docker compose -f docker/compose.yml up --build --abort-on-container-exit --remove-orphans + docker compose -f docker/compose.yml down -v --remove-orphans + diff --git a/collab/proposals/01-codexhelper.llm.md b/collab/proposals/01-codexhelper.llm.md index 3d42e98..fbc7d0c 100644 --- a/collab/proposals/01-codexhelper.llm.md +++ b/collab/proposals/01-codexhelper.llm.md @@ -12,12 +12,13 @@ - Safety: no overwrites without `--force`; never `git push` for user projects. - Outputs: `/runs//...`. - Layout (repo): `CodexHelper`, `bin/install.sh`, `prompts/global/{system.md,system.llm.md}`, `modes//{mode.md,system.md?,defaults.yaml}`, `templates/project//...`, `templates/project/_shared/AGENTS.md`, `meta/{AGENTS.seed.md,AGENTS.seed.llm.md}`. -- Layout (project): `AGENTS.md`, `prompts/{project.md,style.md?}`, `prompts/_mode/`, `codex.yaml`, `codex.sh`, `runs/`. +- Layout (project): `AGENTS.md`, `prompts/{project.md,style.md?}`, `prompts/_mode/`, `codex.yaml`, `codex.sh`, `runs/`, `.gitea/workflows/`, `docker/`, `scripts/`. - Governance/Propagation: non-project-specific workflow changes get recorded in `prompts/global/` and seed AGENTS templates; proposal/plan updated so scaffolding includes them. - TDD Governance: adopt test-driven development with full unit/integration tests for all features in this repo and generated projects; tests written first and required for acceptance. - - Zero Technical Debt: safety first; no technical debt; production-ready at all times; no deferring tests/docs/refactors; use sub-agents as needed. - - Planning/Architecture Governance: plan ahead via Questions→Proposal→Plan; maintain a global architecture/module map; implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated. - - Clean Root Governance: keep repo root minimal; organize assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`. +- Zero Technical Debt: safety first; no technical debt; production-ready at all times; no deferring tests/docs/refactors; use sub-agents as needed. +- Planning/Architecture Governance: plan ahead via Questions→Proposal→Plan; maintain a global architecture/module map; implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated. +- Clean Root Governance: keep repo root minimal; organize assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`. +- CI/Containers Governance: use Gitea Actions with local parity via Docker Compose; do work inside containers; host for git/tea + Docker orchestration; dependencies via Docker; explicit names/cleanup. - Phase 1 acceptance: - new-mode creates mode skeleton - new-project scaffolds without overwrites @@ -30,6 +31,7 @@ - zero debt: docs/tests included with every feature; no pending TODOs/deferrals; production-ready criteria met - planning: architecture/module map documented; module implementations follow approved plan with no unplanned refactors - clean root: root remains minimal; scaffolding organizes assets under subdirectories + - ci/containers: Gitea Actions and local Docker Compose run identical workflows; explicit names and cleanup verified \n+## Approval — Tick All That Apply - Subcommands approved: `new-project`, `run`, `new-mode` [ ] diff --git a/collab/proposals/01-codexhelper.md b/collab/proposals/01-codexhelper.md index 1ef2726..e1beb42 100644 --- a/collab/proposals/01-codexhelper.md +++ b/collab/proposals/01-codexhelper.md @@ -42,7 +42,8 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes - TDD Governance: enforce test-driven development; require unit/integration tests for all features here and in generated projects. - Zero Technical Debt: safety first; always production-ready; no deferring tests/docs/refactors; leverage sub-agents when needed. - Planning/Architecture Governance: plan ahead via Questions→Proposal→Plan; keep a global architecture/module map; implement module-by-module; avoid refactors except when assumptions change and plans/docs are updated. - - Clean Root Governance: keep repo root minimal; organize assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`. +- Clean Root Governance: keep repo root minimal; organize assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`. + - CI/Containers Governance: use Gitea Actions with local parity via Docker Compose; do work inside containers; host for git/tea and Docker only; dependencies via Docker; explicit names and cleanup. ## Project Layout (generated) - `AGENTS.md` (from `templates/project/_shared/AGENTS.md`) @@ -51,6 +52,7 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes - `codex.yaml` (project config) - `codex.sh` (entrypoint wrapper around codex-cli) - `runs/` (created on first run; ignored by VCS) + - `.gitea/workflows/` for CI; `docker/` for compose and Dockerfiles; `scripts/` for docker orchestration (tests, ci) ## Config Details - Format: YAML (`yq` for merging/reading) @@ -105,7 +107,8 @@ Purpose: Implement a bash wrapper (CodexHelper) around codex-cli with “modes - Governance/Propagation honored: when norms change, update `prompts/global/` and AGENTS templates; log in DevLog. - TDD honored: a test suite (bats) covers CLI flows and guardrails; tests pass. - Zero Debt honored: code, tests, and docs complete; no debt items remain. - - Clean Root honored: only essential files at root; scaffolding places assets under subdirectories. +- Clean Root honored: only essential files at root; scaffolding places assets under subdirectories. + - CI/Containers honored: CI runs in Gitea and locally using the same Docker Compose; containers and networks use explicit names and are cleaned up. ## Open Items for Confirmation - Template coverage: include `prompts/style.md` by default? (we’ll include as optional, empty file) diff --git a/docker/compose.yml b/docker/compose.yml new file mode 100644 index 0000000..735bace --- /dev/null +++ b/docker/compose.yml @@ -0,0 +1,19 @@ +name: codexhelper + +services: + tests: + build: + context: .. + dockerfile: docker/test/Dockerfile + container_name: codexhelper-tests + working_dir: /work + volumes: + - ..:/work:Z + command: ["/bin/bash", "-lc", "scripts/test.sh"] + networks: + - codexhelper-net + +networks: + codexhelper-net: + name: codexhelper-net + diff --git a/docker/test/Dockerfile b/docker/test/Dockerfile new file mode 100644 index 0000000..d3330ed --- /dev/null +++ b/docker/test/Dockerfile @@ -0,0 +1,11 @@ +FROM debian:bookworm-slim + +ENV DEBIAN_FRONTEND=noninteractive +RUN apt-get update \ + && apt-get install -y --no-install-recommends \ + ca-certificates git bash curl jq yq \ + bats \ + && rm -rf /var/lib/apt/lists/* + +WORKDIR /work + diff --git a/docs/devlog/DEVLOG_LLM.md b/docs/devlog/DEVLOG_LLM.md index 9ade76b..65031f1 100644 --- a/docs/devlog/DEVLOG_LLM.md +++ b/docs/devlog/DEVLOG_LLM.md @@ -171,3 +171,13 @@ This log is concise and structured for quick machine parsing and summarization. - Updated CLI guardrail tests accordingly - next: - Keep root minimal going forward; store assets under subdirectories + +## 2025-09-17T16:50Z +- context: CI/Containers governance (Gitea + Docker) and local parity +- actions: + - Added `.gitea/workflows/ci.yml` using Docker Compose + - Added `docker/compose.yml` and `docker/test/Dockerfile` with explicit names and cleanup flow + - Added `scripts/test.docker.sh` wrapper + - Propagated CI/containers rules to system prompts and AGENTS templates; updated proposal +- next: + - Ensure future features include containerized workflows and CI updates diff --git a/docs/wrapper.md b/docs/wrapper.md index d353813..32e6bd3 100644 --- a/docs/wrapper.md +++ b/docs/wrapper.md @@ -7,6 +7,7 @@ Overview Status (Phase 1 in progress) - Implemented: `new-mode` scaffolder (repo-only), CLI skeleton, guardrails. - Pending (per plan): `new-project`, `run`, config precedence (YAML+yq). + - CI/Containers: Gitea Actions workflow in `.gitea/workflows/ci.yml`; local parity via `docker/compose.yml`. CLI - Help: `./CodexHelper --help` @@ -16,6 +17,6 @@ CLI Development - Tests: run `scripts/test.sh` (uses bats if available, falls back to internal runner). +- Docker tests: `scripts/test.docker.sh` runs the same suite via Docker Compose. - Follow TDD: write failing tests first, make them pass, refactor. - Keep `docs/architecture.md` and README up to date as features land. - diff --git a/meta/AGENTS.seed.llm.md b/meta/AGENTS.seed.llm.md index 122e266..71b444a 100644 --- a/meta/AGENTS.seed.llm.md +++ b/meta/AGENTS.seed.llm.md @@ -15,3 +15,5 @@ - Planning/Architecture: Plan via Questions→Proposal→Plan; maintain global architecture/module map; implement module-by-module; avoid refactors unless assumptions change and plans/docs are updated. - Clean Roots: Keep project root minimal; use `docs/`, `templates/`, `prompts/`, `scripts/`, etc.; avoid ad-hoc root files. + +- CI/Containers: Use Gitea Actions with local parity via Docker Compose; do work in containers; host for git/tea + Docker orchestration; dependencies via Docker; explicit names; cleanup. diff --git a/meta/AGENTS.seed.md b/meta/AGENTS.seed.md index 02f504a..e280f10 100644 --- a/meta/AGENTS.seed.md +++ b/meta/AGENTS.seed.md @@ -75,3 +75,10 @@ Customize this AGENTS.md to fit your project specifics while preserving the one- ## Clean Repository Roots - Keep the project root minimal and tidy. Prefer directories over many files at root. - Place docs, templates, prompts, and scripts under dedicated subdirectories. + +## CI and Containers (Gitea + Docker) +- Use Gitea Actions for CI (`.gitea/workflows/`). +- Ensure local parity with Docker Compose; provide scripts to run the same CI tasks locally. +- Perform work inside containers where appropriate; use host for git/tea and Docker orchestration only. +- Manage dependencies via container images; avoid host-level installs. +- Use explicit container/network names; clean up containers, networks, and volumes. diff --git a/prompts/global/system.llm.md b/prompts/global/system.llm.md index ef10378..84e81b1 100644 --- a/prompts/global/system.llm.md +++ b/prompts/global/system.llm.md @@ -29,3 +29,11 @@ -- Clean Roots -- - Keep repo root minimal; store assets under `docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`. Avoid ad-hoc root files. + +-- CI/Containers (Gitea + Docker) -- +- CI uses Gitea Actions in `.gitea/workflows/` with local parity via Docker Compose. +- Do work inside containers; host only for git/tea and Docker orchestration. +- Dependencies via Docker (e.g., bats). Avoid host installs. +- Use explicit container/network names; remove orphans; clean networks/volumes. +- Mount host config (e.g., codex) when needed. +- Keep local/remote in sync; no dangling files or empty directories. diff --git a/prompts/global/system.md b/prompts/global/system.md index ded27e6..f95c9f5 100644 --- a/prompts/global/system.md +++ b/prompts/global/system.md @@ -95,6 +95,15 @@ You are a coding agent running in the Codex CLI (terminal-based). Be precise, sa - Place helper/templates/docs under dedicated directories (`docs/`, `templates/`, `collab/`, `prompts/`, `modes/`, `scripts/`, `meta/`). - Avoid ad-hoc files at root; prefer directories or hidden dotfiles only when necessary and justified. +## CI and Containers (Gitea + Docker) +- CI: Use Gitea Actions exclusively. Store workflows under `.gitea/workflows/`. +- Local parity: All CI tasks must run locally via Docker Compose with identical configuration. +- Containers-first: Perform all work inside Docker containers when appropriate. Host is for git/tea and Docker orchestration only. +- Dependencies: Pull tools (e.g., bats, yq) via Docker images; do not require host installs. +- Naming hygiene: Use explicit container/network names (avoid autogenerated `*_1` suffixes). Clean up containers, networks, and volumes after runs. +- Config: Where host auth/config is required (e.g., codex), mount the necessary config dirs into the container securely. +- Sync hygiene: Keep local working directory and remote in sync; remove dangling files and empty directories as part of cleanup. + ## Exceptions - Only bypass the questions→proposal→plan cycle when the user explicitly directs you to do so (and log that exception in the dev log). diff --git a/scripts/test.docker.sh b/scripts/test.docker.sh new file mode 100644 index 0000000..4f719a5 --- /dev/null +++ b/scripts/test.docker.sh @@ -0,0 +1,12 @@ +#!/usr/bin/env bash +set -euo pipefail + +here="$(cd "$(dirname "$0")" && pwd)" +root="$(cd "$here/.." && pwd)" + +compose_file="$root/docker/compose.yml" + +echo "[docker] Running tests via docker compose" +docker compose -f "$compose_file" up --build --abort-on-container-exit --remove-orphans +docker compose -f "$compose_file" down -v --remove-orphans + diff --git a/templates/project/_shared/AGENTS.md b/templates/project/_shared/AGENTS.md index 62dfc95..6184f1b 100644 --- a/templates/project/_shared/AGENTS.md +++ b/templates/project/_shared/AGENTS.md @@ -49,3 +49,9 @@ This file is copied by scaffolding into new projects. Edit to suit the project w ## Clean Repository Roots - Keep the project root minimal and tidy; prefer organizing assets under subdirectories (docs, templates, prompts, scripts, etc.). + +## CI and Containers (Gitea + Docker) +- Use Gitea Actions for CI (`.gitea/workflows/`) with local parity via Docker Compose. +- Perform work inside containers when appropriate; reserve host for git/tea and Docker orchestration. +- Manage dependencies via Docker images; avoid host installs. +- Use explicit container/network names and clean up artifacts (`down -v --remove-orphans`).