| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 4 | 5 | 0% |
| Commands | 2 | 7 | 3 | 17% |
| Section tags | 2 | 2 | 1 | 40% |
What each file covers
Sections
0 shared · 4 only in A · 5 only in B- − Repository Guidelines
- − Modules
- − Quick Commands
- − Cross-Module Rules
- + Backend Application Guidelines
- + Structure
- + Commands
- + Conventions
- + Boundaries
Commands
2 shared · 7 only in A · 3 only in B- − ./gradlew build
- − ./gradlew spotlessApply
- − pnpm -C ui typecheck && pnpm -C ui lint
- − pnpm -C ui test:unit
- − gradle/libs.versions.toml
- − gradle.properties
- − git add -A
- + ./gradlew :application:bootRun
- + ./gradlew :application:copyUiDist
- + ./gradlew generateOpenApiDocs
- ./gradlew :application:test
- ./gradlew generateOpenApiDocs && pnpm -C ui api-client:gen
Section tags
2 shared · 2 only in A · 1 only in B- − security
- − do-not
- + code-style
- architecture
- agent-behaviour
Line diff
halo-dev/halo · AGENTS.md
@@ −1 @@
1# Repository Guidelines
2
3Halo is a full-stack monorepo: Java 21 / Spring Boot WebFlux + R2DBC backend and a Vue 3 + TypeScript + TailwindCSS frontend. Work from the repo root and load **every relevant module guide** for the areas you touch.
4
5## Modules
6
7| Module | Path | Guide |
8|---------------------|-----------------------------------------------------------|------------------------------------------------------------------|
9| API library | `api/` (extension model, contracts, security) | [api/AGENTS.md](api/AGENTS.md) |
10| Backend application | `application/` (services, routers, migrations, packaging) | [application/AGENTS.md](application/AGENTS.md) |
11| Frontend | `ui/` (console, user center, workspace packages) | [ui/AGENTS.md](ui/AGENTS.md) |
12| Application BOM | `platform/application/` (shared dependency constraints) | [platform/application/AGENTS.md](platform/application/AGENTS.md) |
13| Plugin BOM | `platform/plugin/` (plugin-facing constraints) | [platform/plugin/AGENTS.md](platform/plugin/AGENTS.md) |
14
15## Quick Commands
16
17Run from the repo root:
18
19- `./gradlew build` — full backend build and tests.
20- `./gradlew spotlessApply` — format Java, Markdown, JSON, and properties.
21- `./gradlew :application:test` — backend tests.
22- `pnpm -C ui typecheck && pnpm -C ui lint` — frontend validation.
23- `pnpm -C ui test:unit` — frontend unit tests.
24- `./gradlew generateOpenApiDocs && pnpm -C ui api-client:gen` — regenerate the UI client after contract changes.
25
26## Cross-Module Rules
27
28- Keep API contracts, backend handlers, and UI usage in sync; never hand-edit `ui/packages/api-client/src/` — regenerate it after contract changes.
29- Versions live in `gradle/libs.versions.toml`, `gradle.properties`, or `ui/package.json`; never hard-code them.
30- Branch naming: `feat/`, `fix/`, `improvement/`, `upgrade/`; PRs target `upstream` and follow `.github/pull_request_template.md`.
31- Stage specific files only; never `git add -A` (H2 artifacts and build outputs appear under `application/`).
32- Add tests for changed behavior; keep CI green.
33- Ask before public API changes, new dependencies, database migrations, security configuration, or CI workflow changes.
34- Never commit secrets or introduce blocking I/O into reactive flows.
35
36
halo-dev/halo · application/AGENTS.md
@@ +1 @@
1# Backend Application Guidelines
2
3`application/` is the WebFlux + R2DBC backend: services, routers, security, migrations, and packaging. Everything here is reactive — never block threads.
4
5## Structure
6
7- `application/src/main/java/` — services, routers, endpoints, and configuration.
8- `application/src/main/resources/application*.yaml` — environment configuration.
9- `application/src/main/resources/db/migration/{h2,mariadb,mysql,postgresql}/` — per-dialect migrations.
10- `application/src/main/resources/extensions/` — extension schemas and role templates.
11- `application/src/test/` — backend tests.
12
13## Commands
14
15- `./gradlew :application:test` — run backend tests.
16- `./gradlew :application:bootRun` — start the backend dev server.
17- `./gradlew :application:copyUiDist` — embed the built UI into the JAR.
18- `./gradlew generateOpenApiDocs` — emit the OpenAPI spec used to regenerate the UI client.
19
20## Conventions
21
22- Keep reactive flows non-blocking; no blocking I/O in request paths.
23- Database migrations are versioned per dialect — never auto-generate them, and review them with the `application/` guide in mind.
24- Tests: JUnit 5 with Spring Boot test support; name unit tests `XxxTest` and integration tests `XxxIntegrationTest`.
25- After DTO, route, or schema changes, regenerate the UI client (`./gradlew generateOpenApiDocs && pnpm -C ui api-client:gen`) and update `ui/` usage.
26
27## Boundaries
28
29- Ask before adding database migrations, changing security configuration, or introducing new dependencies.
30
31
@@ −1 +1 @@
1−# Repository Guidelines
1+# Backend Application Guidelines
22
3−Halo is a full-stack monorepo: Java 21 / Spring Boot WebFlux + R2DBC backend and a Vue 3 + TypeScript + TailwindCSS frontend. Work from the repo root and load **every relevant module guide** for the areas you touch.
3+`application/` is the WebFlux + R2DBC backend: services, routers, security, migrations, and packaging. Everything here is reactive — never block threads.
44
5−## Modules
5+## Structure
66
7−| Module | Path | Guide |
8−|---------------------|-----------------------------------------------------------|------------------------------------------------------------------|
9−| API library | `api/` (extension model, contracts, security) | [api/AGENTS.md](api/AGENTS.md) |
10−| Backend application | `application/` (services, routers, migrations, packaging) | [application/AGENTS.md](application/AGENTS.md) |
11−| Frontend | `ui/` (console, user center, workspace packages) | [ui/AGENTS.md](ui/AGENTS.md) |
12−| Application BOM | `platform/application/` (shared dependency constraints) | [platform/application/AGENTS.md](platform/application/AGENTS.md) |
13−| Plugin BOM | `platform/plugin/` (plugin-facing constraints) | [platform/plugin/AGENTS.md](platform/plugin/AGENTS.md) |
7+- `application/src/main/java/` — services, routers, endpoints, and configuration.
8+- `application/src/main/resources/application*.yaml` — environment configuration.
9+- `application/src/main/resources/db/migration/{h2,mariadb,mysql,postgresql}/` — per-dialect migrations.
10+- `application/src/main/resources/extensions/` — extension schemas and role templates.
11+- `application/src/test/` — backend tests.
1412
15−## Quick Commands
13+## Commands
1614
17−Run from the repo root:
15+- `./gradlew :application:test` — run backend tests.
16+- `./gradlew :application:bootRun` — start the backend dev server.
17+- `./gradlew :application:copyUiDist` — embed the built UI into the JAR.
18+- `./gradlew generateOpenApiDocs` — emit the OpenAPI spec used to regenerate the UI client.
1819
19−- `./gradlew build` — full backend build and tests.
20−- `./gradlew spotlessApply` — format Java, Markdown, JSON, and properties.
21−- `./gradlew :application:test` — backend tests.
22−- `pnpm -C ui typecheck && pnpm -C ui lint` — frontend validation.
23−- `pnpm -C ui test:unit` — frontend unit tests.
24−- `./gradlew generateOpenApiDocs && pnpm -C ui api-client:gen` — regenerate the UI client after contract changes.
20+## Conventions
2521
26−## Cross-Module Rules
22+- Keep reactive flows non-blocking; no blocking I/O in request paths.
23+- Database migrations are versioned per dialect — never auto-generate them, and review them with the `application/` guide in mind.
24+- Tests: JUnit 5 with Spring Boot test support; name unit tests `XxxTest` and integration tests `XxxIntegrationTest`.
25+- After DTO, route, or schema changes, regenerate the UI client (`./gradlew generateOpenApiDocs && pnpm -C ui api-client:gen`) and update `ui/` usage.
2726
28−- Keep API contracts, backend handlers, and UI usage in sync; never hand-edit `ui/packages/api-client/src/` — regenerate it after contract changes.
29−- Versions live in `gradle/libs.versions.toml`, `gradle.properties`, or `ui/package.json`; never hard-code them.
30−- Branch naming: `feat/`, `fix/`, `improvement/`, `upgrade/`; PRs target `upstream` and follow `.github/pull_request_template.md`.
31−- Stage specific files only; never `git add -A` (H2 artifacts and build outputs appear under `application/`).
32−- Add tests for changed behavior; keep CI green.
33−- Ask before public API changes, new dependencies, database migrations, security configuration, or CI workflow changes.
34−- Never commit secrets or introduce blocking I/O into reactive flows.
27+## Boundaries
28+
29+- Ask before adding database migrations, changing security configuration, or introducing new dependencies.
3530
3631
