Just and new features: docs, lua, test

[thvl3]

Migrated from PR: thvl3/BAR-Devtools#5
Original author: @keithharvey
Created: 2026-03-16T09:07:37Z
Status: Open

---

Add Just as task runner; decompose devtools.sh

Introduce Just as the cross-repo task runner and break devtools.sh into modular scripts.

Old	New
./devtools.sh up lobby	just services::up lobby
./devtools.sh clone extra	just repos::clone extra
./devtools.sh engine build linux	just engine::build linux
./devtools.sh repos	just repos::status
./devtools.sh link	just link::status

The Justfile uses mod for domain-based namespacing (services, repos, engine, setup, link), with bash logic extracted into scripts/. This keeps each .just file focused on interface and delegation.

Motivation

I want to add lua-library generation, doc serving, and test runner recipes (next PR), and the 997-line monolith won't scale.

All existing devtools.sh commands are preserved under namespaced modules:

Why Just

Mise might seem like the default option here, since Recoil already uses that in its doc pipeline

However:

1. Just is by design JUST a runner -- we're composing commands, not managing tool versions.
2. Docker already handles environment provisioning, so mise's tool and configuration management adds no value at this layer.

By design, Just prevents adding configuration here and keeps it purely idempotent bash scripts with some helpers.

Tests

Set up a new machine on my mac. Tested most of these existing and new commands at least once on my linux machine.

LLM Disclosure:

Yes. Gave opus 4.6 "refactor to use Just without changing existing functionality" for the initial conversion commit and it did a decent job

[thvl3]

Comment by @keithharvey on 2026-03-16T09:57:15Z:

Added some new functionality as Just modules by converting my existing scripts:

Available recipes:
    docs:
        generate    # Generate Lua API pages (full pipeline: extract -> JSON -> markdown)
        server      # Generate everything then start Hugo dev server
        server-only # Start Hugo dev server without regenerating
...
    lua:
        build-lde             # Build lua-doc-extractor from local checkout
        library *flags        # Generate Lua library from RecoilEngine sources, copy into BAR submodule
        library-reload *flags # Generate library then restart LuaLS so the editor picks up changes
...
    test:
        all          # Run all BAR tests (units + integrations)
        integrations # Run integration tests (placeholder)
        units *args  # Run busted unit tests in the BAR container

Docs

• Ties in lua-doc-extractor, so you can make changes to lua-doc-extractor, or make changes to your Lua type function decorators in Recoil, then generate the recoil-lua-library, have your local lua language server get restarted (killed) by the script and then automatically see those changes in BAR.
• Also adds just docs::server, a command to start hugo and see the recoil docs.

Test

• Very useful. Run either the unit tests or the integration tests in BAR. test::units just runs busted but does depend on Unit Test Bootstrapping Beyond-All-Reason#5902 (edit: now merged). This cluster of mods are all closely related to that testing loop in BAR between making changes in Recoil -> automatically seeing changes in the Lua language server in BAR -> updating tests -> no more linter errors dev loop.

Notable implementation details:

• Added a minimalist bar.Dockerfile, an ubuntu image with the dependencies necessary to install Lux (a likely future BAR lua package manager)
• The container uses an anonymous volume to shadow .lux/, isolating the container's lux dependency tree from the host's -- without this the bind-mounted .lux/ leaks in wrapper scripts with hardcoded host paths that don't exist in the container
• Workaround for a lux bug where its internally-compiled Lua 5.1 lacks dlopen support, so C modules like luafilesystem (needed by busted) can't load. We just symlink the system lua5.1 over it. Candidate for an upstream bug report

[thvl3]

Comment by @keithharvey on 2026-03-17T07:11:59Z:

• Added macOS support (I like to run just test::units from my couch often), tested setup
• engine build warns on arm since it's currently x86 only. We could force emulation but gross
• fixed engine submodules not being cloned
• added guard clauses to test in case people forget to setup/clone
• added a test::mix which closes [NortySpock] How would I run mix test? #4

[thvl3]

Comment by @keithharvey on 2026-03-20T04:38:51Z:

• Added an optional .env entry for DEVTOOLS_DISTROBOX=rust-dev. Don't have node installed on this host so need to run "distrobox enter rust-dev" before running any scripts that relate to node.

Let me know if you want any of these features split up. Mostly just getting the docs working on both my machines at the moment and fixing/documenting as I go.

[thvl3]

Comment by @keithharvey on 2026-03-23T18:11:04Z:

Added just reset, which resets the generated artifacts from docs/ in Recoil and recoil-lua-library in BAR, a common thing I do when working on those two things so my PRs don't get polluted with generated noise.

[thvl3]

Comment by @keithharvey on 2026-03-23T22:09:57Z:

• Added just bar::test-shell that gets you into lx shell --test (mostly for discoverability) so you can easily run busted quickly when iterating on the bar unit tests.
• The pictures from earlier are out of date because I moved test::units -> bar::units instead (and "integrations" too) and test::mix -> tei::tests, because the process-oriented grouping just made sense in my head.
• also added a just tei::test-shell, that mimics bar::test-shell for teiserver, and drops you into an interactive shell so you can run mix test quickly yourself.

[keithharvey]

Please close, new PR opened with less noise.