How jbangdev/jbang works
1. Top-level purpose
JBbang is a Java-based command-line tool for running, editing, exporting, and packaging scripts and small apps. The main entry point is dev.jbang.Main, which delegates to the CLI command layer in dev.jbang.cli.
2. CLI command boundary
The src/main/java/dev/jbang/cli package is the user-facing surface. Each subcommand—such as run, init, edit, deps, alias, catalog, app, export, jdk, trust, cache, and template—is implemented as a separate command class, with shared behavior factored into mixins and base classes like BaseCommand, RunMixin, ScriptMixin, and BuildMixin.
3. Script intake and normalization
Script handling starts by locating a script source, then parsing directives embedded in comments or metadata. The dev.jbang.source package models this flow with Source, SourceSet, Project, BuildContext, and parser classes under source.parser. This layer turns a raw file, remote URL, alias, or catalog reference into a normalized build/run description.
4. Language-specific source support
JBang supports multiple script languages through source.sources implementations for Java, JShell, Kotlin, Groovy, and Markdown. These classes abstract language-specific parsing and execution details so the rest of the pipeline can treat them uniformly.
5. Build and execution pipeline
Once a script is resolved, the build pipeline generates runnable artifacts or launch commands. The source.buildsteps package contains compile, jar, integration, and native-image steps, while source.generators turns source metadata into command launchers. This is the core flow from “script file” to “executable action.”
6. Dependency resolution subsystem
External libraries are handled by dev.jbang.dependencies. It resolves Maven-style coordinates, detects dependencies from source, caches artifacts, and supports special cases like JitPack and modular classpaths. This subsystem is one of the main boundaries between local script execution and external artifact networks such as Maven repositories.
7. Resource resolution and trust model
Script and asset loading is unified through dev.jbang.resources and its resolver implementations. These handle local files, classpath resources, remote URLs, GAV-style artifacts, aliases, and literal scripts. TrustingResourceResolver and TrustedSources enforce the trust boundary for remote content, which is central to safe execution of downloaded scripts.
8. Catalogs, aliases, templates, and app metadata
Reusable script distribution is modeled in dev.jbang.catalog, with catalog items, aliases, templates, and references. The related CLI commands manage these registries, enabling users to run scripts by name, publish catalogs, or scaffold new scripts from templates. This is the main indirection layer above raw file execution.
9. JDK management and runtime selection
The dev.jbang.net and cli.Jdk areas manage local JDK discovery, installation, and selection. Tests and WireMock fixtures show that JBang can download JDKs from external distribution services, especially Adoptium/Temurin. This subsystem controls which Java runtime the script or export uses.
10. IDE, export, and project-generation outputs
JBang can generate traditional project artifacts and editor integrations. The source.update, source.builders, and resource templates under src/main/resources support exports such as Maven, Gradle, POM, launch configs, and IDE files. Commands like edit, export, and init are thin entry points over this generation layer.
11. Search, completion, and AI-assisted features
Search-related code lives in dev.jbang.search, including artifact search and intent scoring, backed by external Maven search endpoints. Command completion integrates with GitHub/completion providers. The dev.jbang.ai package adds an optional AI provider abstraction, currently with an OpenAI-backed implementation and prompt/template resources.
12. Utilities and cross-cutting services
Shared concerns are centralized in dev.jbang.util: networking, command buffering, template rendering, archive unpacking, version checks, module handling, and Java utilities. These are cross-cutting support services used by the CLI, dependency resolver, and source pipeline rather than separate subsystems.
13. Packaging, distribution, and release
The project is built with Gradle and includes extra packaging assets for scripts, wrappers, native-image config, and distribution formats. src/jreleaser and the jreleaser.yml file drive release artifacts such as Docker images, Homebrew formulas, and Snap packages. GitHub Actions workflows orchestrate CI, tests, releases, and package publication.
14. Testing architecture
The repository has three major test layers: unit tests under src/test, integration tests under src/it, and fixture-heavy networked tests using WireMock under src/test/resources/wiremock. The integration suite exercises real CLI behavior, multiple languages, remote resources, JDK installs, and platform-specific behavior across Windows, macOS, and Linux.
Main entry points: cli CLI · resources Resources · source Source model · java Unit tests
Components 22
Core runtime
Main entrypoint, CLI, and shared runtime services.
- Main · Application entrypoint that boots the CLI layer.
src/main/java/dev/jbang/Main.java - CLI · User-facing subcommands and shared command mixins.
src/main/java/dev/jbang/cli - Base cmd · Common command behavior and parsing support.
src/main/java/dev/jbang/cli/BaseCommand.java - Run mixin · Shared options and behavior for run-style commands.
src/main/java/dev/jbang/cli/RunMixin.java - Script mixin · Shared script resolution and script-oriented options.
src/main/java/dev/jbang/cli/ScriptMixin.java - Catalogs · Aliases, templates, catalog items, and reusable script references.
src/main/java/dev/jbang/catalog
Source pipeline
Script intake, normalization, build steps, and generation.
- Source model · Models scripts and turns raw inputs into build/run context.
src/main/java/dev/jbang/source - Directives · Parses embedded directives and metadata from source files.
src/main/java/dev/jbang/source/parser - Lang sources · Language-specific source support for Java, JShell, Kotlin, Groovy, and Markdown.
src/main/java/dev/jbang/source/sources - Build steps · Compile, jar, integration, and native-image build stages.
src/main/java/dev/jbang/source/buildsteps - Generators · Turns source metadata into command launchers and runnable wrappers.
src/main/java/dev/jbang/source/generators
Infra services
Dependencies, resources, trust, search, JDK, and AI integrations.
- Resources · Unified resolution of files, URLs, GAVs, aliases, and literals with trust enforcement.
src/main/java/dev/jbang/resources - Trust · Trusted source policy for remote content.
src/main/java/dev/jbang/net/TrustedSources.java - Dependencies · Maven-style dependency detection, resolution, caching, and classpath handling.
src/main/java/dev/jbang/dependencies - Search · Artifact search and intent scoring against external search endpoints.
src/main/java/dev/jbang/search - JDK mgmt · JDK discovery, install, and selection for execution and export.
src/main/java/dev/jbang/net - AI · Optional AI provider abstraction and OpenAI-backed implementation.
src/main/java/dev/jbang/ai - Utilities · Cross-cutting helpers for networking, templates, archives, modules, and version checks.
src/main/java/dev/jbang/util
Delivery
Templates, packaging, and release assets.
Tests
Unit and integration test layers with fixtures.
- Unit tests · Focused tests for CLI, source, dependency, network, and utility components.
src/test/java - Integration · End-to-end CLI and runtime tests across languages, downloads, and platforms.
src/it/java
Connections 29
- Main → CLI: delegates to · Main dispatches execution into the command layer.
- CLI → Base cmd: shares base · Commands reuse common parsing and lifecycle behavior.
- CLI → Run mixin: uses · Run-oriented commands share launch options and execution behavior.
- CLI → Script mixin: uses · Script commands share resolution and script-specific options.
- CLI → Catalogs: manages · Alias, catalog, app, and template commands operate on reusable distribution metadata.
- CLI → JDK mgmt: manages · JDK commands discover, install, and select runtimes.
- CLI → Resources: loads scripts · Commands resolve scripts and resources from many source kinds.
- CLI → Dependencies: resolves libs · Dependency-related commands and script execution rely on artifact resolution.
- CLI → Exports: exports · Init, edit, and export commands generate project and IDE outputs.
- Source model → Directives: parses · Source normalization starts by extracting embedded directives and metadata.
- Source model → Lang sources: adapts · Language-specific source handlers normalize Java, JShell, Kotlin, Groovy, and Markdown.
- Source model → Build steps: builds via · Resolved sources flow through compile, jar, integration, and native stages.
- Source model → Generators: emits · Build context is turned into launchers and runnable wrappers.
- Resources → Trust: guards · Remote and downloaded content is checked against trust policy.
- Resources → Catalogs: resolves refs · Alias and catalog references are resolved through the resource layer.
- Dependencies → Search: discovers · Artifact search helps locate dependencies and build inputs.
- Dependencies → Resources: fetches artifacts · Dependency resolution pulls remote artifacts through the resource boundary.
- JDK mgmt → Resources: downloads via · JDK installation and selection rely on remote resource fetching.
- Exports → Utilities: uses · Export and generation strategies use shared rendering and file utilities.
- Packaging → Exports: packages outputs · Release assets and distribution templates wrap generated project outputs.
- AI → Utilities: uses · AI integration reuses shared networking and template utilities.
- Unit tests → CLI: covers · Unit tests exercise command parsing and command behavior.
- Unit tests → Source model: covers · Unit tests exercise normalization, builders, and source modeling.
- Unit tests → Dependencies: covers · Unit tests cover dependency resolution and special cases.
- Unit tests → Resources: covers · Unit tests cover trust, resource resolution, and network helpers.
- Integration → CLI: exercises · Integration tests run the real CLI across commands.
- Integration → Source model: exercises · Integration tests validate multi-language scripts, directives, and builds.
- Integration → JDK mgmt: exercises · Integration tests cover JDK install and runtime selection flows.
- Integration → Resources: exercises · Integration tests validate remote resources, aliases, and trust behavior.