TibiaWikiApi: Instructions file for Codex

TibiaWikiApi — agent notes

What this is

Spring Boot REST API over TibiaWiki (Fandom). Public Swagger: https://tibiawiki.dev. Deployed to GCP Cloud Run (cloudbuild.yaml). Resource list and ?expand=true: README.md.

Stack

• JDK 25 (java.toolchain and Kotlin jvmTarget 25 in build.gradle.kts). Gradle wrapper 9.7.1 — always use ./gradlew.
• Kotlin 2.4.10, Spring Boot 4.1.1.
• Layout: production, unit, and integration code is Kotlin under src/main/kotlin, src/test/kotlin, and src/integrationTest/kotlin.

Build / run

JDK 25 required.

./gradlew build
./gradlew bootRun          # http://localhost:8080 — default profile is live jwiki → Fandom

GitHub Actions Gradle workflow is .github/workflows/buid.yml (filename typo; do not rename unless asked).

Tests (Gradle)

CI (buid.yml) runs:

./gradlew ktlintCheck jacocoTestReport

jacocoTestReport depends on check, which also runs the integrationTest source set. A slice of those ITs (FixturesProfileIT) uses @ActiveProfiles("fixtures") and the real FixtureArticleRepository — no mocks and no Fandom. ktlint is the style checker — do not add a style guide.

Cloud Run uses the default profile (live JwikiArticleRepository, LOGGING_JSON=true). When changing beans, constructors, logging, or Boot config: add or keep a default (or prod-like) profile IT that constructs real beans (DefaultProfileWikiBeansIT). Fixtures and @MockitoBean alone do not cover that path. Prod env flags that affect logging (e.g. LOGGING_JSON=true) must be exercised in CI (LoggingJsonActuatorIT).

The Bun harness in regression/ is not part of the Gradle test task.

Docker ENTRYPOINT / PORT (critical)

Cloud Run injects PORT. Bind it in Spring only: server.port=${PORT:8080} in application.properties. The production image ENTRYPOINT must be exec-form java with no $ / $$ / sh -c:

ENTRYPOINT ["java", "-Dserver.address=0.0.0.0", "-jar", "/project/TibiaWikiApi.jar"]