From 0fcd218b9f7fe956393b75b653d180cae9c29548 Mon Sep 17 00:00:00 2001 From: James Maes Date: Sun, 12 Jul 2026 10:02:03 -0500 Subject: [PATCH] docs(#9): close out 0.3 release --- AGENTS.md | 16 ++++++++ CLAUDE.md | 10 ++++- README.md | 32 +++++++-------- docs/SESSION-STATE.md | 96 +++++++++---------------------------------- docs/TODO.md | 14 +++---- 5 files changed, 66 insertions(+), 102 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f0d3d68 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,16 @@ +# Repository instructions + +Read `CLAUDE.md`, `CONTRIBUTING.md`, `docs/SESSION-STATE.md`, and `docs/TODO.md` +before substantive work. Munitor is a CircleCI orb: source changes belong under +`src/`, generated packed scripts must remain synchronized, and consumer behavior +must be covered by BATS fixtures and assertions. + +Use feature branches targeting `develop`; `main` is release-only. Run `make all` +before opening a pull request and `make validate` when the CircleCI CLI is +available. Publish development snapshots from feature or `develop`; publish +stable orb versions only from semantic version tags on `main`. + +For deployment changes, preserve the established contract: repository-owned +Dockerfiles are opt-in, consolidated GitOps paths are repository-relative +`kustomization.yaml` files, and `production_only` prevents non-main write-back. +Never put credentials in manifests, fixtures, logs, or documentation. diff --git a/CLAUDE.md b/CLAUDE.md index f3a174e..c51629f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -29,11 +29,19 @@ GitHub Issues (org: KofTwentyTwo). Commit format: `feat(#N): description` or `Cl - Namespace: `kof22` - Orb: `kof22/munitor` -- Latest stable: `kof22/munitor@0.2.0` +- Latest stable: `kof22/munitor@0.3.0` - Dev snapshot: `kof22/munitor@dev:snapshot` +`0.3.0` includes first-class pnpm support, repository-owned Dockerfiles for +`node-webapp`, and consolidated Kustomize GitOps write-back with optional +production-only behavior and bounded push-race retries. + ## Session Continuity - Session state: `docs/SESSION-STATE.md` - Active tasks: `docs/TODO.md` - Plans: `docs/PLAN-*.md` + +Read `AGENTS.md` and `CONTRIBUTING.md` before changing orb behavior. Feature +branches target `develop`; release branches promote to `main`, and stable orb +publication is driven by a `vX.Y.Z` tag. diff --git a/README.md b/README.md index 9e67948..4f14d84 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ This file is identical across all repos: version: 2.1 setup: true orbs: - munitor: kof22/munitor@1 + munitor: kof22/munitor@0.3 workflows: setup: jobs: @@ -53,7 +53,7 @@ Munitor validates branch names and will fail on non-conforming names. | Context | Secrets | Used By | |---------|---------|---------| -| `ghcr` | `GHCR_TOKEN`, `GHCR_USER` | Docker push to GitHub Container Registry | +| `ghcr` | `GHCR_TOKEN`, `GHCR_USERNAME` | Docker push to GitHub Container Registry | | `github` | `GITHUB_TOKEN` | Git operations, CD repo updates, SBOM, GitHub Releases | | `sonarcloud` | `SONAR_TOKEN` | SonarCloud analysis | | `nvd` | `NVD_API_KEY` | OWASP dependency check (Java only, optional) | @@ -68,7 +68,7 @@ For Node.js/Next.js applications with Docker deployment. ```yaml pipeline: node-api -orb_version: dev:snapshot +orb_version: "0.3" image_name: my-app docker: registry: ghcr.io/KofTwentyTwo @@ -81,7 +81,7 @@ contexts: ```yaml pipeline: node-api -orb_version: dev:snapshot +orb_version: "0.3" image_name: my-app node_version: "22" # default: 20 @@ -145,7 +145,7 @@ For Node.js applications that provide their own Dockerfile (unlike `node-api` wh ```yaml pipeline: node-webapp -orb_version: dev:snapshot +orb_version: "0.3" image_name: my-webapp docker: registry: ghcr.io/KofTwentyTwo @@ -159,7 +159,7 @@ contexts: ```yaml pipeline: node-webapp -orb_version: dev:snapshot +orb_version: "0.3" image_name: my-webapp node_version: "22" # default: 20 @@ -227,7 +227,7 @@ For Java/Maven applications with Docker deployment. ```yaml pipeline: java-webapp -orb_version: dev:snapshot +orb_version: "0.3" image_name: my-service docker: registry: ghcr.io/KofTwentyTwo @@ -241,7 +241,7 @@ contexts: ```yaml pipeline: java-webapp -orb_version: dev:snapshot +orb_version: "0.3" image_name: my-service java_version: "21" # default: 21 @@ -287,7 +287,7 @@ For Terraform/Terragrunt infrastructure repos. ```yaml pipeline: terraform -orb_version: dev:snapshot +orb_version: "0.3" terraform: path: terraform/ ``` @@ -296,7 +296,7 @@ terraform: ```yaml pipeline: terraform -orb_version: dev:snapshot +orb_version: "0.3" terraform: path: terraform/ # default: terraform/ live_path: terraform/live # default: terraform/live @@ -318,14 +318,14 @@ For CD/GitOps repositories containing Kubernetes manifests, Kustomize overlays, ```yaml pipeline: validate-cd-repo -orb_version: dev:snapshot +orb_version: "0.3" ``` **Full config:** ```yaml pipeline: validate-cd-repo -orb_version: dev:snapshot +orb_version: "0.3" kustomize: version: "5.5.0" # default: 5.5.0 @@ -350,14 +350,14 @@ For ArgoCD app-of-apps repositories that use environment directories (`envs/`) i ```yaml pipeline: argocd-apps -orb_version: dev:snapshot +orb_version: "0.3" ``` **Full config:** ```yaml pipeline: argocd-apps -orb_version: dev:snapshot +orb_version: "0.3" kustomize: version: "5.5.0" # default: 5.5.0 @@ -382,7 +382,7 @@ For SDK packaging and GitHub Releases. Triggered by semver tags (`v1.2.3`). ```yaml pipeline: sdk-distribution -orb_version: dev:snapshot +orb_version: "0.3" contexts: github: github ``` @@ -516,7 +516,7 @@ Default endpoint: `GET /api/health` on port 3000 (node-api, node-webapp) or 8080 ## Troubleshooting -**"Missing required fields: orb_version"** -- Add `orb_version` to your `.munitor.yml`. Use `dev:snapshot` for pre-release testing or `1` once a stable release is published. +**"Missing required fields: orb_version"** -- Add `orb_version` to your `.munitor.yml`. Use `dev:snapshot` for unreleased feature testing or `0.3` for the current stable line. **"munitor_header: command not found"** -- You're using an older orb version. Update to `dev:snapshot` or wait for the next stable release. diff --git a/docs/SESSION-STATE.md b/docs/SESSION-STATE.md index 1ca4067..f9a566f 100644 --- a/docs/SESSION-STATE.md +++ b/docs/SESSION-STATE.md @@ -1,83 +1,25 @@ -# Munitor Session State +# Munitor session state -## Last Updated -2026-03-27 +## Current status -## Current Status -Feature branch `feature/GH-5-pnpm-support` is at `7519d62`, pushed to origin. 17 commits ahead of `develop`. Dev snapshot published: `kof22/munitor@dev:snapshot`. All 219 tests pass. Ready for PR to develop when consumer repo validation confirms the fixes work. +The `develop` branch contains the complete `0.3.0` feature set. PR #6 added +first-class pnpm support and the Obsidian pipeline, PR #8 added opt-in +repository Dockerfile preservation for `node-webapp`, and PR #10 added +consolidated Kustomize GitOps write-back with production-only controls and +bounded push-race retries. Investing in Chester and QRun marketing both proved +the release path through CircleCI, GHCR, `KofTwentyTwo/cluster-gitops`, and +ArgoCD. -## Branch -- `feature/GH-5-pnpm-support` at `7519d62` (pushed, 17 commits ahead of develop) -- `develop` at `af15015` -- `main` at `1e558c1` (2 commits ahead of develop) +## Release state -## Tags / Releases -- `v0.1.0` at `9247dcc` - Initial stable release (7 pipeline types, 362+ tests) -- `v0.1.1` at `5f70823` - Supplemental images, health check, Trivy bump (505+ tests) -- `v0.1.2` at `d766747` - Overridable org defaults (PR #1) -- `v0.2.0` at `af15015` - Gradle-webapp pipeline type (PR #2), marked as Latest +- Latest stable target: `kof22/munitor@0.3.0` +- Stable consumer pin: `kof22/munitor@0.3` +- Development aliases: `dev:` and `dev:snapshot` +- Default branch: `develop`; `main` is release-only +- Release tag: `v0.3.0` -All four have GitHub Releases. +## Verification -## Key Facts -- GitHub org: KofTwentyTwo (repo: KofTwentyTwo/Munitor) -- CircleCI namespace: kof22 (orb: kof22/munitor) -- Latest stable orb: kof22/munitor@0.2.0 -- Dev snapshot: kof22/munitor@dev:snapshot (pnpm support, 2026-03-27) -- Pipeline types (8): java-webapp, gradle-webapp, node-api, node-webapp, terraform, validate-cd-repo, sdk-distribution, argocd-apps -- CI workflows: lint-pack (all), snapshot (develop/feature), test-deploy (tags only) -- Default branch: develop (main is release-only) -- Test count: 219 assertions passing (across 7 test files) -- GitHub Issue: #5 (first-class pnpm support) - -## pnpm Support (GH-5) Implementation Summary - -### What was done (17 commits on feature/GH-5-pnpm-support) - -**Phase 1 - Mechanical rename:** -- Renamed all `npm_*` jobs/commands/scripts to `node_*` (except `npm_auth` which stays) -- Updated all templates, tests, and CONTRIBUTING.md references - -**Phase 2 - Package manager threading:** -- `package_manager` parameter threaded through: `install_node` -> `node_install_deps` -> `node_test` -> cache commands -> `node_build_and_test` job -> all templates -- Corepack activation in `install_node.sh` for pnpm/yarn (version detection from `packageManager` field or `engines`) -- `node_install_deps.sh` rewritten with npm/pnpm branching + Prisma auto-detection -- `node_test.sh` falls back to `pnpm test` for pnpm (instead of `npx jest`) -- Cache commands use PM-specific lockfile checksums and cache paths - -**Phase 3 - Supplemental features:** -- `run_test_setup.sh` supports inline commands (not just file paths) -- `generate_dockerfile.sh` has pnpm Dockerfile variants for node-api (nextjs + express) and node-webapp -- Prisma auto-detection runs `prisma generate` after install for all PMs - -**Phase 4 - Secondary job fixes (latest commit):** -- All secondary jobs (code-quality, coverage, e2e, security-scan, sonar, sbom) now run `install_node` with `node_version` + `package_manager` to bootstrap corepack/pnpm in their executors -- `node_coverage_check` supports configurable `coverage_summary_path` with glob patterns for monorepo weighted-average aggregation -- New `.munitor.yml` config: `test.coverage.summary_path` (default: `coverage/coverage-summary.json`) - -### Design decisions -- Spec: `ClaudeCode/Munitor/docs/2026-03-27-pnpm-support-design.md` -- Plan: `ClaudeCode/Munitor/docs/2026-03-27-pnpm-support-plan.md` -- `npm_auth` NOT renamed (genuinely npm-registry-specific, .npmrc auth works for pnpm too) -- Monorepo Dockerfile generation out of scope (user provides custom Dockerfile) -- Yarn support limited to corepack plumbing (no yarn-specific testing) -- Coverage monorepo: glob + weighted average rather than auto-search - -## Consumer Repos - Orb Version Status (updated 2026-03-27) -- `KofTwentyTwo/Concilium` - gradle-webapp, develop, **@0.2**, green (PR #41 merged) -- `KofTwentyTwo/Website-Backend` - java-webapp, develop, **@0.2** (PR #44 merged) -- `KofTwentyTwo/Website-Frontend` - node-webapp, develop, **@0.2** (PR #6 merged) - testing pnpm support via dev:snapshot -- `KofTwentyTwo/k8s-app-of-apps` - argocd-apps, develop, green (still on @0.1, compatible) -- `KofTwentyTwo/Website-CD` - validate-cd-repo, main, green (still on @0.1, compatible) -- `KofTwentyTwo/makers4` - java-webapp, main, **needs CircleCI follow** -- `KofTwentyTwo/terraform-proxmox-talos` - terraform, develop, **needs CircleCI follow** - -## Next Steps -- Validate dev:snapshot on Website-Frontend (pnpm consumer) - confirm coverage job now works without corepack workaround -- Test `coverage_summary_path` glob if Website-Frontend is a monorepo -- Create PR #3 targeting develop once consumer validation passes -- Merge and release v0.3.0 -- Bump consumer repos to @0.3 -- Follow makers4 and terraform-proxmox-talos on CircleCI (manual UI step) -- Fix Website-Frontend ESLint error (DebugPanel.tsx:73 setState in effect, pre-existing) -- Adopt supplemental images on a consumer repo (e.g., me-health-portal with Liquibase) +Run `make all` before release. The stable tag must publish successfully through +CircleCI before consumer repositories move from immutable development pins to +`0.3`. diff --git a/docs/TODO.md b/docs/TODO.md index 73841e0..540dba6 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -2,17 +2,15 @@ ## Pending -- [ ] Validate dev:snapshot on Website-Frontend (confirm pnpm coverage job fix) -- [ ] Create PR #3 for pnpm support (feature/GH-5-pnpm-support -> develop) -- [ ] Release v0.3.0 after PR merge -- [ ] Bump consumer repos to @0.3 -- [ ] Follow makers4 and terraform-proxmox-talos on CircleCI (manual step) -- [ ] Fix Website-Frontend ESLint error (DebugPanel.tsx:73 setState in effect) -- [ ] Adopt supplemental images on a consumer repo (e.g., me-health-portal with Liquibase) -- [ ] Bump k8s-app-of-apps and Website-CD to @0.2+ (optional, @0.1 still compatible) +- [ ] Follow makers4 and terraform-proxmox-talos on CircleCI when those repos are next active. +- [ ] Adopt supplemental images on an appropriate consumer. ## Completed +- [x] Prove consolidated production write-back with Investing in Chester and QRun marketing. +- [x] Release v0.3.0 and move the verified consumers to the stable 0.3 line. +- [x] Merge repository Dockerfile preservation and consolidated GitOps write-back. +- [x] Validate first-class pnpm support and merge PR #6. - [x] Add opt-in repository Dockerfile preservation for node-webapp (GH-7) - [x] Implement first-class pnpm support (GH-5, 17 commits, 219 tests) - [x] Rename all npm_* orb components to node_* (backward-incompatible, pre-1.0) -- 2.54.0