erupt: Instructions file for Codex

AGENTS.md

This file provides guidance to coding agents (Claude Code, Codex, ...) when working with code in this repository.

Build & Test Commands

# Build entire project
mvn clean install

# Build a single module (and its dependencies)
mvn clean install -pl erupt-core -am

# Skip tests for faster builds
mvn clean install -DskipTests

# Run all tests (erupt-test module uses H2 in-memory DB)
mvn test -pl erupt-test

# Run a specific test class
mvn test -pl erupt-test -Dtest=LambdaQueryTest

# Run a specific test method
mvn test -pl erupt-test -Dtest=LambdaQueryTest#lambdaQueryTest

# Run the sample application for local testing
cd erupt-sample && mvn spring-boot:run

# Regenerate the OpenAPI spec (openapi/erupt.json) from controller Javadoc via smart-doc; commit the result
mvn -pl erupt-test -Popenapi process-classes

# Regenerate the node SDK contract (schema/*.json, consumed by github.com/erupt-io/erupt-sdk) after an
# annotation change; a plain `mvn test` fails while these files are stale. Commit the result
mvn -pl erupt-test -Pnode-schema test

# Publish to Maven Central (GPG signing, Javadoc; wraps `mvn clean deploy -P release`)
./scripts/deploy.sh

# Bump version across this repo AND satellite repos (erupt-web etc.)
./scripts/bump-erupt.sh [--dry-run] x.x.x

# Full release SOP (frontend build, bump, Maven Central, Docker Hub, merge+tag, gitee sync)
# Driven phase by phase by the /release command (.claude/commands/release.md)
./scripts/release.sh <preflight|frontend|bump|maven|docker|publish|start|verify> [x.x.x]

Java 17 required. Spring Boot 3.5.x (pinned via spring.boot.version in the parent pom). No Maven wrapper — use system mvn.

Compatibility

Erupt runs on Java 17 or newer and on every mainstream database. Both are promises to users, not defaults of the machine a feature happens to be written on — check a new feature against them.

• Java 17 is the floor. The parent pom compiles with <release>17</release>, so a newer API fails the build rather than the user's runtime. Developing on a newer JDK is fine; List.getFirst(), SequencedCollection and friends are not.
• The dialect owns the SQL. Never write a type name, a function or a DDL fragment that only one database understands. Ask Hibernate for it (DdlTypeRegistry, Dialect) or keep it in JPQL / criteria. A columnDefinition is raw DDL and travels to every database as written.
• Watch what schema generation freezes. ddl-auto=update adds columns and nothing else — it never changes a type, a check constraint or an enum value list. Anything the create statement pins down becomes permanent for databases already in the field (see EnumColumnIntegrator).
• Mind reserved words and identifier case. Column names such as value or order need quoting; erupt enables globally_quoted_identifiers for that reason, so identifiers are case sensitive.
• Test against more than H2. erupt-test runs on H2 in MySQL mode; a feature that touches SQL, metadata or DDL deserves a look at how Oracle, PostgreSQL and SQL Server would read it.