ADR 0018: Justfile Organization

Status

Accepted

Date

2026-06-11

Context

The root Justfile had grown into a single large file containing unrelated repository operations: local installation, dependency checks, Node tooling, CraftOS-PC launch wrappers, headless probes, test orchestration, package validation, markdown linting, and opencode helpers.

That made the file harder to scan and edit, even though the public recipe surface is useful as a flat command list. Existing documentation, Git hooks, and developer habits refer to top-level commands such as just check, just test, just ci, and just trapos-exec.

just supports both imports and modules. Imports include another justfile into the current namespace, so imported recipes keep their top-level names. Modules create namespaced subcommands and isolate recipe/variable definitions between modules. That namespace is useful for new command families, but it would change the invocation shape of existing repository recipes.

Decision

Keep the root Justfile as the canonical entrypoint, but make it only import concern-specific recipe files under just/ and define the default listing recipe.

Use imports for the existing recipe split so all public recipe names remain unchanged. Organize imported files by operational concern:

just/deps.just for dependency/tool availability checks.
just/install.just for local install, cleanup, Git hooks, and generated environment setup.
just/npm.just for Node-based repository tooling.
just/craftos.just for CraftOS-PC launchers, headless Lua probes, install probe, and REPL wrapper.
just/opencode.just for opencode server/client helpers.
just/test.just for CI, standard tests, integration tests, and timeout harness checks.
just/check.just for source checks, package validation, and markdown link validation.

Reserve mod for future commands that are intentionally namespaced from the start. Do not use modules for this migration because preserving the existing flat command API is more important than introducing module isolation.

Consequences

Existing commands keep working without aliases or compatibility wrappers.
just --list remains the public command catalogue for the repository.
Recipe bodies are easier to locate by concern while cross-file dependencies still work through the shared imported namespace.
Duplicate recipe names remain a repository-level concern because all imported recipes share one namespace.
Future recipes should be added to the concern file that owns their lifecycle rather than growing the root Justfile again.

Future Work

Consider modules for new namespaced tool families if the desired invocation is explicitly something like just tool subcommand or just tool::subcommand.
Revisit the grouping if any imported justfile grows large enough to recreate the original navigation problem.

2.8 KiB Raw Blame History