Skip to content

AGENTS.md

Latest commit

 

History

History
26 lines (25 loc) · 3 KB

AGENTS.md

File metadata and controls

26 lines (25 loc) · 3 KB

JBang Agent Handbook

  • Toolchain: Gradle build, Java 11 runtime (targets 8 bytecode).
  • Build everything: ./gradlew build; prefer Gradle tasks over direct javac.
  • Unit tests: ./gradlew test; single test with ./gradlew test --tests "pkg.Class".
  • Always add unit tests, and if relevant integration tests for new features and bugfixes.
  • Integration tests: ./gradlew integrationTest; filter via --tests "pkg.ITClass".
  • Formatting: ./gradlew spotlessApply; verify using spotlessCheck.
  • No extra linters; rely on compiler + spotless for CI hygiene.
  • Source layout: app in src/main/java, unit tests in src/test/java, IT in src/it/java.
  • Main entry point: dev.jbang.Main; CLI commands built with picocli.
  • Keep packages under dev.jbang; match existing folder hierarchy.
  • Imports ordered java → javax → org → com → dev.jbang → blank line.
  • Drop unused imports; never use wildcard or static-on-demand imports.
  • Formatting uses misc/eclipse_formatting_nowrap.xml; indent 4 spaces, no wrapping.
  • Naming: UpperCamelCase types, lowerCamelCase members, UPPER_SNAKE constants.
  • Types: prefer explicit generics; annotate nullability with @jspecify where applicable.
  • Avoid raw collections and unchecked casts; keep method signatures explicit.
  • Error handling: throw dev.jbang.cli.ExitException for controlled exits; let picocli report parameter issues.
  • Logging/output: use dev.jbang.util.Util helpers (e.g., infoMsg, verboseMsg).
  • Commits: use conventional/semantic format — feat:, fix:, build:, docs:, etc. PR titles follow the same convention.
  • Startup scripts live in src/main/scripts/: jbang (bash), jbang.cmd (CMD), jbang.ps1 (PowerShell). The CMD script delegates downloads and JDK installs to jbang.ps1. Changes affecting downloads or bootstrap must be applied consistently across all three. Behavior (e.g., retry backoff) must be consistent across tools — watch for tool-specific quirks like curl --retry-delay 0 meaning exponential backoff while wget --waitretry=0 meaning no delay.
  • Environment variables follow JBANG_* naming. New env vars must have defaults in each script that actually uses them (e.g., jbang.cmd delegates downloads to jbang.ps1, so download-related vars only need defaults in jbang and jbang.ps1). Document new vars in installation.adoc ("Startup Script Environment Variables") and ensure consistent behavior across platforms.
  • Documentation is AsciiDoc under docs/modules/ROOT/pages/ (e.g., installation.adoc, troubleshooting.adoc).
  • Test infrastructure: BaseTest includes WireMock for HTTP mocking (records/replays requests). BaseIT provides shell() helpers for running CLI commands. Use assumeTrue for conditionally skipping tests (e.g., assumeTrue(isCommandAvailable("bash")) or assumeTrue(isCommandAvailable("pwsh"))).
  • Script tests should run the real scripts from src/main/scripts/ — not synthetic copies or extracted functions. Use env var overrides (e.g., JBANG_DOWNLOAD_URL) to point real scripts at WireMock.
⚡