# jbangdev/jbang architecture

> Architecture diagram of the GitHub repository jbangdev/jbang, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jbangdev/jbang
- Repository: https://github.com/jbangdev/jbang

## Overview

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: [`src/main/java/dev/jbang/cli`](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/cli) (CLI), [`src/main/java/dev/jbang/resources`](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/resources) (Resources), [`src/main/java/dev/jbang/source`](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source) (Source model), [`src/test/java`](https://github.com/jbangdev/jbang/tree/main/src/test/java) (Unit tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_main(("Main<br/>entrypoint<br/>[Main.java]"))
  node_cli["CLI<br/>command layer"]
  node_basecmd["Base cmd<br/>command base<br/>[BaseCommand.java]"]
  node_runmix["Run mixin<br/>cli mixin<br/>[RunMixin.java]"]
  node_scriptmix["Script mixin<br/>cli mixin<br/>[ScriptMixin.java]"]
  node_catalog["Catalogs<br/>distribution model"]
end

subgraph group_source["Source pipeline"]
  node_sourcecore[("Source model<br/>script normalization")]
  node_parser["Directives<br/>parser"]
  node_langs["Lang sources<br/>language adapters"]
  node_buildsteps["Build steps<br/>build pipeline"]
  node_generators["Generators<br/>launcher generation"]
end

subgraph group_infra["Infra services"]
  node_resolver[("Resources<br/>resource resolution")]
  node_trust(("Trust<br/>security boundary"))
  node_deps[("Dependencies<br/>artifact resolution")]
  node_search["Search"]
  node_jdk["JDK mgmt<br/>runtime selection"]
  node_ai(("AI<br/>assistant integration"))
  node_util["Utilities<br/>shared services"]
end

subgraph group_delivery["Delivery"]
  node_update["Exports<br/>project generation"]
  node_packaging["Packaging<br/>distribution assets"]
end

subgraph group_tests["Tests"]
  node_unit["Unit tests<br/>test layer"]
  node_itests["Integration"]
end

node_main -->|"delegates to"| node_cli
node_cli -->|"shares base"| node_basecmd
node_cli -->|"uses"| node_runmix
node_cli -->|"uses"| node_scriptmix
node_cli -->|"manages"| node_catalog
node_cli -->|"manages"| node_jdk
node_cli -->|"loads scripts"| node_resolver
node_cli -->|"resolves libs"| node_deps
node_cli -->|"exports"| node_update
node_sourcecore -->|"parses"| node_parser
node_sourcecore -->|"adapts"| node_langs
node_sourcecore -->|"builds via"| node_buildsteps
node_sourcecore -->|"emits"| node_generators
node_resolver -->|"guards"| node_trust
node_resolver -->|"resolves refs"| node_catalog
node_deps -->|"discovers"| node_search
node_deps -->|"fetches artifacts"| node_resolver
node_jdk -->|"downloads via"| node_resolver
node_update -->|"uses"| node_util
node_packaging -->|"packages outputs"| node_update
node_ai -->|"uses"| node_util
node_unit -.->|"covers"| node_cli
node_unit -.->|"covers"| node_sourcecore
node_unit -.->|"covers"| node_deps
node_unit -.->|"covers"| node_resolver
node_itests -.->|"exercises"| node_cli
node_itests -.->|"exercises"| node_sourcecore
node_itests -.->|"exercises"| node_jdk
node_itests -.->|"exercises"| node_resolver

click node_main "https://github.com/jbangdev/jbang/blob/main/src/main/java/dev/jbang/Main.java"
click node_cli "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/cli"
click node_basecmd "https://github.com/jbangdev/jbang/blob/main/src/main/java/dev/jbang/cli/BaseCommand.java"
click node_runmix "https://github.com/jbangdev/jbang/blob/main/src/main/java/dev/jbang/cli/RunMixin.java"
click node_scriptmix "https://github.com/jbangdev/jbang/blob/main/src/main/java/dev/jbang/cli/ScriptMixin.java"
click node_resolver "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/resources"
click node_trust "https://github.com/jbangdev/jbang/blob/main/src/main/java/dev/jbang/net/TrustedSources.java"
click node_deps "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/dependencies"
click node_search "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/search"
click node_jdk "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/net"
click node_sourcecore "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source"
click node_parser "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source/parser"
click node_langs "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source/sources"
click node_buildsteps "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source/buildsteps"
click node_generators "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source/generators"
click node_update "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source/update"
click node_catalog "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/catalog"
click node_ai "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/ai"
click node_util "https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/util"
click node_packaging "https://github.com/jbangdev/jbang/tree/main/src/jreleaser"
click node_unit "https://github.com/jbangdev/jbang/tree/main/src/test/java"
click node_itests "https://github.com/jbangdev/jbang/tree/main/src/it/java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_cli,node_basecmd,node_runmix,node_scriptmix,node_catalog toneBlue
class node_sourcecore,node_parser,node_langs,node_buildsteps,node_generators toneAmber
class node_resolver,node_trust,node_deps,node_search,node_jdk,node_ai,node_util toneMint
class node_update,node_packaging toneRose
class node_unit,node_itests toneIndigo
```

## Components

### Core runtime

Main entrypoint, CLI, and shared runtime services.

- [Main](https://github.com/jbangdev/jbang/blob/main/src/main/java/dev/jbang/Main.java): entrypoint · Application entrypoint that boots the CLI layer. · `src/main/java/dev/jbang/Main.java`
- [CLI](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/cli): command layer · User-facing subcommands and shared command mixins. · `src/main/java/dev/jbang/cli`
- [Base cmd](https://github.com/jbangdev/jbang/blob/main/src/main/java/dev/jbang/cli/BaseCommand.java): command base · Common command behavior and parsing support. · `src/main/java/dev/jbang/cli/BaseCommand.java`
- [Run mixin](https://github.com/jbangdev/jbang/blob/main/src/main/java/dev/jbang/cli/RunMixin.java): cli mixin · Shared options and behavior for run-style commands. · `src/main/java/dev/jbang/cli/RunMixin.java`
- [Script mixin](https://github.com/jbangdev/jbang/blob/main/src/main/java/dev/jbang/cli/ScriptMixin.java): cli mixin · Shared script resolution and script-oriented options. · `src/main/java/dev/jbang/cli/ScriptMixin.java`
- [Catalogs](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/catalog): distribution model · 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](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source): script normalization · Models scripts and turns raw inputs into build/run context. · `src/main/java/dev/jbang/source`
- [Directives](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source/parser): parser · Parses embedded directives and metadata from source files. · `src/main/java/dev/jbang/source/parser`
- [Lang sources](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source/sources): language adapters · Language-specific source support for Java, JShell, Kotlin, Groovy, and Markdown. · `src/main/java/dev/jbang/source/sources`
- [Build steps](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source/buildsteps): build pipeline · Compile, jar, integration, and native-image build stages. · `src/main/java/dev/jbang/source/buildsteps`
- [Generators](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source/generators): launcher generation · 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](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/resources): resource resolution · Unified resolution of files, URLs, GAVs, aliases, and literals with trust enforcement. · `src/main/java/dev/jbang/resources`
- [Trust](https://github.com/jbangdev/jbang/blob/main/src/main/java/dev/jbang/net/TrustedSources.java): security boundary · Trusted source policy for remote content. · `src/main/java/dev/jbang/net/TrustedSources.java`
- [Dependencies](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/dependencies): artifact resolution · Maven-style dependency detection, resolution, caching, and classpath handling. · `src/main/java/dev/jbang/dependencies`
- [Search](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/search): artifact search · Artifact search and intent scoring against external search endpoints. · `src/main/java/dev/jbang/search`
- [JDK mgmt](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/net): runtime selection · JDK discovery, install, and selection for execution and export. · `src/main/java/dev/jbang/net`
- [AI](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/ai): assistant integration · Optional AI provider abstraction and OpenAI-backed implementation. · `src/main/java/dev/jbang/ai`
- [Utilities](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/util): shared services · Cross-cutting helpers for networking, templates, archives, modules, and version checks. · `src/main/java/dev/jbang/util`

### Delivery

Templates, packaging, and release assets.

- [Exports](https://github.com/jbangdev/jbang/tree/main/src/main/java/dev/jbang/source/update): project generation · File update and export strategies for IDE, Maven, Gradle, and similar outputs. · `src/main/java/dev/jbang/source/update`
- [Packaging](https://github.com/jbangdev/jbang/tree/main/src/jreleaser): distribution assets · Gradle, JReleaser, scripts, native-image config, and release packaging assets. · `src/jreleaser`

### Tests

Unit and integration test layers with fixtures.

- [Unit tests](https://github.com/jbangdev/jbang/tree/main/src/test/java): test layer · Focused tests for CLI, source, dependency, network, and utility components. · `src/test/java`
- [Integration](https://github.com/jbangdev/jbang/tree/main/src/it/java): integration layer · End-to-end CLI and runtime tests across languages, downloads, and platforms. · `src/it/java`

## Connections

- 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.
