47 lines
2.8 KiB
Markdown
47 lines
2.8 KiB
Markdown
# 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.
|