AGENTS.md · Atmosphere/atmosphere

Sections

1. Build System: Maven
2. Git Workflow
3. Project Structure
4. Writing Code
5. Correctness Invariants (Blocking)
6. Testing
7. Pre-Commit Validation
8. Spring Boot Starter Notes
9. Quarkus Extension Notes
10. atmosphere.js (TypeScript Client)
11. Sample Applications
12. No Hallucinations — Verify Before Claiming
13. Persona Handle — NEVER in committed artifacts
14. Honesty and Integrity — Don't Lie to the project maintainer
15. Carnet & Bilan — Issue Claims and the Completion Number
16. Getting Help
17. Knowledge Vault & Documentation Routing

First lines (shown under the repo's Apache-2.0 license)

## Build System: Maven

**This project uses Apache Maven with the Maven Wrapper (`./mvnw`).**

### Commands
| Task | Command |
|------|---------|
| Full build | `./mvnw install` |
| Fast build (skip checks) | `./mvnw install -Pfastinstall` |
| Compile only | `./mvnw compile` |
| Run tests | `./mvnw test` |
| Run single test | `./mvnw test -pl modules/cpr -Dtest=BroadcasterTest` |
| Skip tests | `./mvnw install -DskipTests` |
| Spotless check only | `./mvnw spotless:check` |
| Spotless fix | `./mvnw spotless:apply` |

### Module Build
Build a specific module (faster iteration):
```bash
# Build only atmosphere-runtime (cpr)
./mvnw install -pl modules/cpr -DskipTests

# Build only spring-boot-starter
./mvnw install -pl modules/spring-boot-starter -DskipTests

# Build only quarkus extension
./mvnw install -pl modules/quarkus-extension -DskipTests
```

## Git Workflow

### Hooks Setup
**Run this at the START OF EVERY SESSION:**
```bash
git config core.hooksPath .githooks
```
This enables pre-commit, commit-msg, and pre-push hooks. Sessions get archived/revived, so this must run EVERY time you start working.

**NEVER use `--no-verify` when committing or pushing.** The hooks enforce:
- Apache 2.0 license headers, through Spotless: the hook compiles the Maven module owning each staged Java file (nearest `pom.xml`, so `modules/quarkus-*/runtime` too) and its `validate` phase runs `spotless:check`; staged Java files owned by the root project (`generator/`, `scripts/`) get `./mvnw -N spotless:check`. A Java file anywhere else (e.g. `e2e/`, or a module directory outside `src/`) is outside every Spotless include, and the hook's architectural validation blocks it. Under the sandbox-only `ATMOSPHERE_OFFLINE_COMMIT` bypass no Maven runs, so headers are then checked by `scripts/pre-push-validate.sh` and the CI build
- No unused or duplicate imports in staged Java files (duplicates compared on the import name, read from the import section only)
- Commit message format (max 2 lines, conventional commits recommended)
- No AI-generated commit signatures
- Pre-push: Maven build must pass (via validation marker)

### Commit Message Format
Use conventional commit prefixes. The commit-msg hook warns if missing:
```
type(scope): description
```
Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`, `perf`, `ci`, `build`, `revert`

Examples:
```
feat(cpr): add WebSocket reconnection support
fix(spring-boot): resolve auto-configuration ordering
chore: update Jetty to 12.0.16
```

Rules enforced by hooks:
- Maximum 2 non-empty lines (summary + optional detail)
- First line under 100 characters (50-72 recommended)
- No AI-generated signatures (`Co-Authored-By: Claude`, `Generated with`, etc.)
- **NEVER add `Co-authored-by: Copilot` or any AI co-author trailer** — the commit-msg hook will reject it
- Do not add ANY trailer lines (Co-authored-by, Signed-off-by, etc.) to commit messages

### Branch Strategy
- Main branch: `main` (development)
- Legacy branch: `atmosphere-3.x`. Bug fixes only, nothing else
- Never touch the `atmosphere-2.x` branches (2.7.x, 2.6.x and older): unsupported, no commits, no backports
- Feature branches for new features
- Bug fixes go directly to `main`

## Project Structure

```
atmosphere/
├── modules/
│   ├── cpr/                       (atmosphere-runtime - core framework)
│   ├── spring-boot-starter/       (Spring Boot 4.0 integration)
│   └── quarkus-extension/         (Quarkus 3.21+ integration)
│       ├── runtime/
│       └── deployment/
├── samples/
│   ├── chat/                      (Jetty embedded sample)
│   ├── embedded-jetty-websocket-chat/
│   ├── spring-boot-chat/
│   └── quarkus-chat/
├── atmosphere.js/                 (TypeScript client library)
└── pom.xml                        (4.0.57-SNAPSHOT, JDK 21)
```

### Key Artifacts
| Module | ArtifactId | Description |
|--------|-----------|-------------|
| Core | `atmosphere-runtime` | Main framework JAR |
| Spring Boot | `atmosphere-spring-boot-starter` | Spring Boot 4.0 auto-configuration |
| Quarkus Runtime | `atmosphere-quarkus-extension` | Quarkus 3.21+ runtime |
| Quarkus Deployment | `atmosphere-quarkus-extension-deployment` | Quarkus build-time processing |

## Writing Code

- Java version: **21** (configured in root pom.xml `<release>21</release>`)
- License: Apache 2.0
- All Java files MUST have the copyright header (enforced by Spotless; `./mvnw spotless:apply` adds a missing one)
- Commit without AI assistant-related commit messages
- Do not add AI-generated commit text in commit messages
- **NEVER add `Co-authored-by:` trailers to commits** — no Copilot, no Claude, no AI attribution of any kind
- NEVER USE `--no-verify` WHEN COMMITTING CODE
- Match the style and formatting of surrounding code
- Make the smallest reasonable changes to get to the desired outcome
- NEVER remove code comments unless you can prove they are actively false

### Copyright Header (Required)
All Java source files must start with the header below. Spotless (`licenseHeader` in the root
`pom.xml`) enforces it on `src/**/*.java`, `generator/` and `scripts/`: the end year a file already
carries is kept, and `./mvnw spotless:apply` adds the header with the current year to a file that
lacks it. `package-info.java` and `module-info.java` are checked by a lint instead, which `apply`
cannot fix: copy the header in by hand. Third-party notices go in a separate comment block after it.
```java
/*
 * Copyright 2008-2026 Async-IO.org
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
 * use this file except in compliance with the License. You may obtain a copy of
 * the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 * License for the specific language governing permissions and limitations under
 * the License.
 */
```

### Java Code Style
- Prefer composition over inheritance
- Use `try-with-resources` for all `AutoCloseable` resources
- Prefer `Optional` over null returns for public APIs
- Use `var` for local variables when the type is obvious from context
- Prefer `switch` expressions (JDK 21) over if/else chains for enum handling
- Use sealed classes/interfaces where appropriate
- Use records for immutable data carriers
- Use pattern matching (`instanceof` patterns, switch patterns) where it improves readability
- Avoid raw types - always parameterize generics
- Use `@Override` on all overriding methods
- Prefer `StringBuilder` over string concatenation in loops
- Use `List.of()`, `Map.of()`, `Set.of()` for unmodifiable collections
- All tests use JUnit 5 (`org.junit.jupiter`)

### Build Enforcement
- **Compiler**: `javac -Xlint:all,-processing,-serial -Werror` is enabled — the compiler flags unchecked casts, deprecation usage, raw types, and other issues as warnings. It does not flag unused imports (javac has no such lint); Spotless does. **Zero compiler warnings are required.**
- **Spotless**: `spotless:check` runs in `validate` phase and fails the build. Configured inline in the root `pom.xml`: fails on a missing or altered Apache 2.0 license header, on unused, duplicate, `java.lang` and same-package imports and on any tab character in `src/**/*.java` (plus the JBang sources under `generator/` and `scripts/`, checked only from the root project; `scripts/architectural-validation.sh` fails on a tracked Java file outside these includes). Duplicate imports are matched on the imported name (static and non-static apart) within the import section: indentation, extra blanks and a trailing `//` comment do not hide one; blanks inside the dotted name, a trailing `/* */` comment on the earlier copy or two imports on one line do. `./mvnw spotless:apply` adds a missing header, removes the imports and expands leading tabs to spaces; a tab elsewhere in a line (e.g. inside a string literal) is reported for a hand fix. No code formatter is applied.
- **Not enforced (PMD was removed)**: the build no longer runs PMD, and nothing replaced the rules it enforced on main and test sources: unused local variables, unused private fields, unused private methods, unused parameters of private methods, assignments whose value is never read (`UnusedAssignment`), `size() == 0` instead of `isEmpty()` (`UseCollectionIsEmpty`), `ThreadGroup` use (`AvoidThreadGroup`) and calling `Thread.run()` directly (`DontCallThreadRun`). javac `-Xlint:all` has no lint for any of them; catch them in review or in the IDE.
- **Pre-commit hook**: blocks commits containing unused or duplicate imports in staged Java files, and compiles the Maven module owning each staged Java file (javac `-Werror` plus the Spotless check, so the license header too); root-project Java files (`generator/`, `scripts/`) get `./mvnw -N spotless:check`, and a Java file outside every Spotless include fails its architectural validation
- All checks can be skipped with `-Pfastinstall` for local iteration, but **you MUST run a full `./mvnw compile` (without `-Pfastinstall`) before committing** to verify zero warnings.
- **Architectural validation** (`scripts/architectural-validation.sh`, run by the pre-commit hook and CI): among its checks, framework code reading AI state through the process-wide `AiConfig`/`AgentRuntimeResolver` statics, `AiEnvironment.current()` or `AiEnvironment.processDefault()` fails unless allowlisted with a reason (see Correctness Invariant #1).
- **Do NOT introduce new `@SuppressWarnings` annotations** without justification. If a suppression is necessary (e.g., unavoidable raw type from a third-party API), add a comment explaining why.