From cd61f8e4e3ad70626ceab86324cf6d4938e23458 Mon Sep 17 00:00:00 2001 From: Jake Willmsen <42048994+jdwillmsen@users.noreply.github.com> Date: Wed, 27 May 2026 22:35:09 -0500 Subject: [PATCH 1/9] docs: add CLAUDE.md with NX monorepo AI agent guidance --- CLAUDE.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..afc16fa --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,95 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working in this repository. + +## Repository Overview + +NX monorepo for jdwlabs application services. Contains Angular micro-frontends, Go backend services, and database migration tooling. + +### Structure + +- `apps/frontend/` — Angular micro-frontend apps (authui, rolesui, usersui) +- `apps/backend/` — Go backend services (servicediscovery, usersrole) +- `apps/database/` — Database migration apps (authdb) +- `apps/e2e/` — Cypress end-to-end tests +- `libs/frontend/` — Shared Angular libraries +- `libs/backend/` — Shared Go libraries + +### Tech Stack + +- **Frontend:** Angular, Module Federation, Jest, Cypress +- **Backend:** Go (workspace at repo root via go.work) +- **Monorepo tooling:** NX, pnpm + +## Development Commands + +### Build + +```bash +npx nx build # Build a single app +npx nx run-many -t build # Build all apps +``` + +### Test + +```bash +npx nx test # Unit tests for one app +npx nx run-many -t test # All unit tests +npx nx e2e -e2e # Cypress E2E tests +``` + +### Lint + +```bash +npx nx lint # Lint one app +npx nx run-many -t lint # Lint all +``` + +### Affected (used in CI to scope work to changed code) + +```bash +npx nx affected -t build # Build only what changed vs main +npx nx affected -t test # Test only what changed +npx nx affected -t lint # Lint only what changed +``` + +### Go (backend services) + +```bash +go build ./... # Run from repo root (go.work) +go test ./... # Run all Go tests +``` + +## Common Tasks + +### Add a new Angular app + +```bash +npx nx g @nx/angular:application --directory=apps/frontend/ +``` + +### Add a new shared Angular library + +```bash +npx nx g @nx/angular:library --directory=libs/frontend/ +``` + +### Add a dependency + +```bash +pnpm add --filter +pnpm install --frozen-lockfile # Restore lockfile-exact install +``` + +## AI Agent Contract + +- Use `npx nx` for all build/test/lint operations — never invoke `ng` directly +- For Go: use `go build ./...` and `go test ./...` from the repo root (go.work handles workspace) +- Do not modify `pnpm-lock.yaml` directly — run `pnpm install` to update +- Do not run `git push` — leave that to the developer +- CI runs `nx affected` — changes that don't appear in the affected graph will not be tested in CI + +## References + +- [NX Documentation](https://nx.dev) +- [Conventional Commits](CONTRIBUTING.md) From b1be5e1eb1d1edad3dd4ee0acf0fdf1db4acfa50 Mon Sep 17 00:00:00 2001 From: Jake Willmsen <42048994+jdwillmsen@users.noreply.github.com> Date: Wed, 27 May 2026 22:35:38 -0500 Subject: [PATCH 2/9] fix: add shebang to commit-msg hook for Windows compatibility --- .husky/commit-msg | 1 + 1 file changed, 1 insertion(+) diff --git a/.husky/commit-msg b/.husky/commit-msg index 70bd3dd..f6f2ce3 100644 --- a/.husky/commit-msg +++ b/.husky/commit-msg @@ -1 +1,2 @@ +#!/usr/bin/env sh npx --no-install commitlint --edit "$1" From 66c96a6386f44ff06e19e313aa618cea55e877bb Mon Sep 17 00:00:00 2001 From: Jake Willmsen <42048994+jdwillmsen@users.noreply.github.com> Date: Wed, 27 May 2026 22:41:24 -0500 Subject: [PATCH 3/9] docs: fix directory paths in CLAUDE.md to match actual repo structure --- CLAUDE.md | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index afc16fa..6a6125d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,17 +8,18 @@ NX monorepo for jdwlabs application services. Contains Angular micro-frontends, ### Structure -- `apps/frontend/` — Angular micro-frontend apps (authui, rolesui, usersui) -- `apps/backend/` — Go backend services (servicediscovery, usersrole) +- `apps/angular/` — Angular micro-frontend apps (authui, container, rolesui, usersui, platform-e2e) +- `apps/go/` — Go services (servicediscovery) +- `apps/springboot/` — Spring Boot/Kotlin service (usersrole) - `apps/database/` — Database migration apps (authdb) -- `apps/e2e/` — Cypress end-to-end tests -- `libs/frontend/` — Shared Angular libraries -- `libs/backend/` — Shared Go libraries +- `libs/angular/` — Shared Angular libraries +- `libs/go/` — Shared Go libraries ### Tech Stack - **Frontend:** Angular, Module Federation, Jest, Cypress -- **Backend:** Go (workspace at repo root via go.work) +- **Backend (Go):** Go 1.23, workspace at repo root via `go.work` (covers `apps/go/` and `libs/go/`) +- **Backend (JVM):** Spring Boot, Kotlin, Gradle - **Monorepo tooling:** NX, pnpm ## Development Commands @@ -65,13 +66,13 @@ go test ./... # Run all Go tests ### Add a new Angular app ```bash -npx nx g @nx/angular:application --directory=apps/frontend/ +npx nx g @nx/angular:application --directory=apps/angular/ ``` ### Add a new shared Angular library ```bash -npx nx g @nx/angular:library --directory=libs/frontend/ +npx nx g @nx/angular:library --directory=libs/angular/ ``` ### Add a dependency @@ -84,7 +85,7 @@ pnpm install --frozen-lockfile # Restore lockfile-exact install ## AI Agent Contract - Use `npx nx` for all build/test/lint operations — never invoke `ng` directly -- For Go: use `go build ./...` and `go test ./...` from the repo root (go.work handles workspace) +- For Go: use `go build ./...` and `go test ./...` from the repo root (`go.work` covers `apps/go/` and `libs/go/`) - Do not modify `pnpm-lock.yaml` directly — run `pnpm install` to update - Do not run `git push` — leave that to the developer - CI runs `nx affected` — changes that don't appear in the affected graph will not be tested in CI From a2e394c5102f6559fc8c6e7cd939b4818e95faca Mon Sep 17 00:00:00 2001 From: Jake Willmsen <42048994+jdwillmsen@users.noreply.github.com> Date: Wed, 27 May 2026 22:42:21 -0500 Subject: [PATCH 4/9] chore: add .claude/settings.json with tool permissions --- .claude/settings.json | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 .claude/settings.json diff --git a/.claude/settings.json b/.claude/settings.json new file mode 100644 index 0000000..7a0bbf3 --- /dev/null +++ b/.claude/settings.json @@ -0,0 +1,20 @@ +{ + "permissions": { + "allow": [ + "Bash(npx nx *)", + "Bash(pnpm *)", + "Bash(go build *)", + "Bash(go test *)", + "Bash(go vet *)", + "Bash(git diff*)", + "Bash(git log*)", + "Bash(git status*)", + "Bash(git add *)", + "Bash(git commit*)" + ], + "deny": [ + "Bash(git push*)", + "Bash(rm -rf *)" + ] + } +} From 3ef129273969af1c966b8118f4f5518c764fdb7a Mon Sep 17 00:00:00 2001 From: Jake Willmsen <42048994+jdwillmsen@users.noreply.github.com> Date: Wed, 27 May 2026 22:43:04 -0500 Subject: [PATCH 5/9] docs: add GEMINI.md and AGENTS.md for AI agent context --- AGENTS.md | 37 +++++++++++++++++++++++++++++++++++++ GEMINI.md | 35 +++++++++++++++++++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 AGENTS.md create mode 100644 GEMINI.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..81f9e92 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,37 @@ +# AGENTS.md + +Context for AI agents (OpenAI Codex, GitHub Copilot, and others) working in this repository. + +## What This Repo Is + +jdwlabs `apps` is an NX monorepo containing the full application stack for the jdwlabs platform: + +- **Auth UI** (`apps/angular/authui`) — login, registration, session management +- **Roles UI** (`apps/angular/rolesui`) — role assignment and management +- **Users UI** (`apps/angular/usersui`) — user listing and administration +- **Container** (`apps/angular/container`) — shell app that composes micro-frontends via Module Federation +- **Platform E2E** (`apps/angular/platform-e2e`) — Cypress end-to-end test suite +- **Service Discovery** (`apps/go/servicediscovery`) — Go backend service registry +- **Users/Role service** (`apps/springboot/usersrole`) — Spring Boot/Kotlin user-role assignment API +- **Auth DB** (`apps/database/authdb`) — database migration management + +## Key Concepts + +- **Module Federation:** frontends are micro-frontends composed at runtime via Webpack Module Federation — each Angular app is independently deployable but the container app assembles them +- **NX affected:** CI only builds/tests code touched by a PR — understand the dependency graph before assuming a change is isolated (`npx nx graph` to visualize) +- **go.work:** a Go workspace at the repo root covers `apps/go/servicediscovery` and `libs/go/shared/util` — always run `go` commands from the repo root + +## Navigation + +- Angular entry points: `apps/angular//src/main.ts` +- Go entry point: `apps/go/servicediscovery/main.go` +- Spring Boot entry point: `apps/springboot/usersrole/src/main/kotlin/` +- Shared Angular code: `libs/angular/` +- Shared Go code: `libs/go/` +- NX project graph: `npx nx graph` + +## Constraints + +- Do not add direct dependencies between Angular apps — use shared libs in `libs/angular/` +- All secrets come from environment variables injected at deploy time — no hardcoded secrets +- Do not push to remote without developer review diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..ada0310 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,35 @@ +# GEMINI.md + +This file provides guidance to Gemini CLI when working in this repository. +For the canonical reference, see [CLAUDE.md](CLAUDE.md) — this file mirrors that content. + +## Repository Overview + +NX monorepo for jdwlabs application services. Contains Angular micro-frontends, Go backend services, a Spring Boot/Kotlin service, and database migration tooling. + +### Structure + +- `apps/angular/` — Angular micro-frontend apps (authui, container, rolesui, usersui, platform-e2e) +- `apps/go/` — Go services (servicediscovery) +- `apps/springboot/` — Spring Boot/Kotlin service (usersrole) +- `apps/database/` — Database migration apps (authdb) +- `libs/angular/` — Shared Angular libraries +- `libs/go/` — Shared Go libraries + +## Development Commands + +```bash +npx nx build # Build one app +npx nx test # Test one app +npx nx lint # Lint one app +npx nx affected -t build,test # CI-equivalent: affected apps only +go build ./... # Go workspace build (from repo root) +go test ./... # Go workspace test (from repo root) +``` + +## Agent Contract + +- Use `npx nx` for all Angular build/test/lint — never `ng` directly +- Use `go` commands from repo root for Go services (`go.work` covers `apps/go/` and `libs/go/`) +- Do not modify lockfiles directly +- Do not push to remote — stage and commit only From b35d514b7acf3d6abaddaa5962076ec67b44900c Mon Sep 17 00:00:00 2001 From: Jake Willmsen <42048994+jdwillmsen@users.noreply.github.com> Date: Wed, 27 May 2026 22:43:39 -0500 Subject: [PATCH 6/9] docs: add CONTRIBUTING.md and PR template with conventional commit convention --- .github/pull_request_template.md | 21 +++++++++++ CONTRIBUTING.md | 65 ++++++++++++++++++++++++++++++++ 2 files changed, 86 insertions(+) create mode 100644 .github/pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..37f364e --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,21 @@ +## What + + + +## Type of change + +- [ ] `feat` — new feature or capability +- [ ] `fix` — bug fix +- [ ] `chore` — maintenance / dependency / config +- [ ] `docs` — documentation only +- [ ] `ci` — CI/CD pipeline change +- [ ] `refactor` — restructure, no behavior change +- [ ] `test` — test additions or updates +- [ ] `perf` — performance improvement + +## Checklist + +- [ ] PR title follows conventional commit format: `type(scope): description` +- [ ] `npx nx affected -t build,test,lint` passes locally +- [ ] No secrets or credentials in diff +- [ ] CONTRIBUTING.md consulted for commit message format diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..779a6c4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,65 @@ +# Contributing + +## Commit Convention + +This repository follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/). + +### Types + +| Type | When to use | +|------|-------------| +| `feat` | New feature or user-visible capability | +| `fix` | Bug fix | +| `chore` | Maintenance: dependency upgrades, config, tooling | +| `docs` | Documentation only (no code changes) | +| `ci` | CI/CD pipeline changes | +| `refactor` | Code restructure with no behavior change | +| `test` | Adding or updating tests | +| `perf` | Performance improvement | +| `revert` | Reverting a previous commit | + +### Format + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +### Examples + +``` +feat(authui): add OIDC token refresh flow +fix(usersrole): return 404 when user not found +ci: add pnpm cache to build workflow +docs: document module federation remote config +chore: upgrade angular to 19.2 +refactor(rolesui): extract role list to shared component +test(usersrole): add integration test for role assignment +``` + +### Rules + +- Subject line ≤72 characters, lowercase, no trailing period +- Use imperative mood: "add" not "added" / "adds" +- Scope is optional but encouraged — use the app or lib name +- Breaking changes: add `!` after type/scope and a `BREAKING CHANGE:` footer + +## Pull Requests + +1. Branch from `main`: `git checkout -b feat/short-description` +2. Keep PRs focused — one logical change per PR +3. PR title must follow conventional commit format: `type(scope): description` +4. Fill the PR template completely +5. Squash-merge to main to keep history clean + +## Development Setup + +```bash +pnpm install --frozen-lockfile # Install dependencies +npx nx run-many -t build # Verify build passes +npx nx run-many -t test # Verify tests pass +npx nx run-many -t lint # Verify lint passes +``` From a76f312bf9db286faa678d54a026b854c35d58fd Mon Sep 17 00:00:00 2001 From: Jake Willmsen <42048994+jdwillmsen@users.noreply.github.com> Date: Thu, 28 May 2026 00:13:44 -0500 Subject: [PATCH 7/9] docs: add build, style types to conform to full conventional commits spec --- .github/pull_request_template.md | 9 ++++++--- CONTRIBUTING.md | 10 ++++++---- 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 37f364e..daf3071 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -6,12 +6,15 @@ - [ ] `feat` — new feature or capability - [ ] `fix` — bug fix -- [ ] `chore` — maintenance / dependency / config -- [ ] `docs` — documentation only +- [ ] `build` — build system or external dependency change +- [ ] `chore` — maintenance / config / tooling - [ ] `ci` — CI/CD pipeline change +- [ ] `docs` — documentation only +- [ ] `perf` — performance improvement - [ ] `refactor` — restructure, no behavior change +- [ ] `revert` — revert a previous commit +- [ ] `style` — formatting / whitespace (no logic change) - [ ] `test` — test additions or updates -- [ ] `perf` — performance improvement ## Checklist diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 779a6c4..d657123 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,13 +10,15 @@ This repository follows [Conventional Commits](https://www.conventionalcommits.o |------|-------------| | `feat` | New feature or user-visible capability | | `fix` | Bug fix | -| `chore` | Maintenance: dependency upgrades, config, tooling | -| `docs` | Documentation only (no code changes) | +| `build` | Build system or external dependency change (NX, pnpm, Go modules) | +| `chore` | Maintenance: config, tooling (no production code change) | | `ci` | CI/CD pipeline changes | -| `refactor` | Code restructure with no behavior change | -| `test` | Adding or updating tests | +| `docs` | Documentation only (no code changes) | | `perf` | Performance improvement | +| `refactor` | Code restructure with no behavior change | | `revert` | Reverting a previous commit | +| `style` | Formatting or whitespace only (no logic change) | +| `test` | Adding or updating tests | ### Format From 86a663a9e3d70ad4c6605bdf197856db9e299716 Mon Sep 17 00:00:00 2001 From: Jake Willmsen <42048994+jdwillmsen@users.noreply.github.com> Date: Thu, 28 May 2026 00:21:19 -0500 Subject: [PATCH 8/9] docs: add commit footer examples with Jira refs and AI contributor --- CONTRIBUTING.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d657123..3ac6d66 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,6 +42,45 @@ refactor(rolesui): extract role list to shared component test(usersrole): add integration test for role assignment ``` +### Footers + +Footers appear after an optional body, separated by a blank line. Common footers: + +| Footer | When to use | +|--------|-------------| +| `Refs: JDWLABS-XX` | Links commit to a Jira issue (does not close it) | +| `Closes: JDWLABS-XX` | Closes the Jira issue on merge | +| `Closes: #N` | Closes a GitHub issue by number | +| `BREAKING CHANGE: ` | Required when a commit introduces a breaking API/interface change | +| `Co-Authored-By: Name ` | Credit a co-author (human or AI) | + +**AI contributor footer** — include when commits were written with AI assistance: + +``` +Co-Authored-By: Claude Sonnet 4.6 +``` + +**Full examples with footers:** + +``` +feat(authui): add OIDC token refresh flow + +Implements silent refresh using a hidden iframe per the OIDC spec. +Falls back to full re-login if the refresh token is expired. + +Refs: JDWLABS-42 +Co-Authored-By: Claude Sonnet 4.6 +``` + +``` +fix!(usersrole): remove deprecated /users/list endpoint + +BREAKING CHANGE: /users/list removed; use /users?page=N instead. + +Closes: JDWLABS-38 +Closes: #17 +``` + ### Rules - Subject line ≤72 characters, lowercase, no trailing period From d89ff56cd31f80c95d7b54095a63d3e99874af34 Mon Sep 17 00:00:00 2001 From: Jake Willmsen <42048994+jdwillmsen@users.noreply.github.com> Date: Wed, 3 Jun 2026 00:49:59 -0500 Subject: [PATCH 9/9] style: format .claude/settings.json to satisfy nx format:check Prettier collapses the deny array to a single line. Unblocks the CI Run Format Check step. Co-Authored-By: Claude Opus 4.8 --- .claude/settings.json | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.claude/settings.json b/.claude/settings.json index 7a0bbf3..6023809 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -12,9 +12,6 @@ "Bash(git add *)", "Bash(git commit*)" ], - "deny": [ - "Bash(git push*)", - "Bash(rm -rf *)" - ] + "deny": ["Bash(git push*)", "Bash(rm -rf *)"] } }