WIP: build: add just command recipes #810

Closed
Marcuss2 wants to merge 2 commits from Marcuss2/Longshot:builder/just-command-recipes into main
Contributor

Type: build · Risk: low · Tested on: Linux, game-free checks and a full local build; no GPU run · Needs: Windows command-line smoke test, no GPU

Why

The repository's build, test, team and packaging commands were spread across scripts and guides, and a just
wrapper split an escaped .nup filename at every space. Contributors need one readable command index whose recipes
preserve the documented commands and arguments. No existing issue covers this command-index work.

What changed

Add a root justfile with 29 thin recipes, a listing-only default, full-test and CI-safe lint commands, and argument-safe
build forwarding using just 1.59.0's opt-in list support. Keep direct commands documented, modernize contributor and
agent guides without changing clone instructions, and pin just plus actionlint in the workflow-lint CI job. Windows uses
an explicit cmd.exe /c shell so bare just does not require sh.

  • justfile: command groups for checks, repository rules, team commands, the game and Linux packaging; bare just
    lists recipes, just test runs the game-free suite, and just lint --check fails on formatting or workflow-lint errors.
  • justfile: build double-quotes each forwarded argument separately, preserving whitespace and brackets. Other script
    bodies remain in their scripts rather than being inlined.
  • tests/test_justfile.py: 14 checks for the documented copy, 29-recipe manifest, one-line bodies, documented-command
    parity, listing-only default behavior and the escaped .nup path regression.
  • CONTRIBUTING.md, AGENTS.md, docs/development.md, docs/justfile.md: just-first commands and agent discovery,
    with canonical direct commands and clone steps retained.
  • .forgejo/workflows/ci.yml: the workflow-lint job downloads pinned just 1.59.0 and actionlint 1.7.12, verifies both
    SHA-256 hashes, and runs just lint --check. Other CI jobs keep direct commands and do not download just.

Measurements

N/A — no fps, VRAM, load-time or AppImage-size claim; command wrappers, documentation, checks and CI setup only.

Flags and settings

None — no game flags or settings changed. The justfile explicitly enables just 1.59.0's unstable and lists settings so
build can quote each argument separately; CI pins that just version.

Testing

Tested: on Linux, with no dump needed except for the explicitly requested local build:

  • just lint --check with just 1.59.0 and CI-pinned actionlint 1.7.12: passed; the archive's SHA-256 was verified.
  • python -I -B tests/run_all.py justfile: 1 passed. Direct python -I -B tests/test_justfile.py: 14 checks passed.
  • just test: 517 passed, 13 failed, 64 skipped. Base main @ aa95d35f (python -I -B tests/run_all.py): 516 passed,
    13 failed, 64 skipped, with the exact same failure set. The only delta is the new passing tests/test_justfile.py.
    The pre-existing failures are test_lift_cleanup_error.py, test_make_game_cache.py, test_crash_dialog.py,
    test_cpm_discovery.py, test_env_on.py, test_appimage_player_build.py, test_options_budget_once.py,
    test_linux_preflight.py, test_pipeline_tour.py, test_mods_size_table.py, test_readback_late.py,
    test_vk_pgo.py and test_walk_key.py.
  • The exact requested just build with an escaped .nup path containing spaces and brackets: full Linux build completed
    with exit code 0 and @@done /mnt/sdd1/games/Longshot/build. Before the fix it failed during argument parsing.
  • Windows 11 review by Rogasse on 63e949db: just --list, 14 justfile tests, formatting and spaced/bracketed synthetic
    path quoting passed; bare just exposed just 1.59.0's default sh dependency. b8602afd pins the tester's confirmed
    cmd.exe /c override; Linux justfile manifest checks and bare just pass on that head. Windows retest is below.
  • just --fmt --check --unstable, just, just --list, git diff --check, and documented build/check-dump/test/lint
    dry runs: passed. No .nup file is staged or tracked.

Not tested: Windows cmd on b8602afd (the previous head exposed the bare-just shell failure), the Windows
PowerShell just run recipe, or an in-game GPU run. No game code changed; the corrected Windows shell needs a retest.

Must be tested:

  • Windows 11, no GPU, by hand: on b8602afd with just 1.59.0 and no sh in PATH, run bare just, expecting the complete recipe list without a shell override; repeat the spaced/bracketed synthetic just build dry-run, expecting one intact quoted path, and run the 14 justfile tests, expecting all to pass. No game dump is needed; report the commands and output on this PR.

Risks

Low: contributor command wrappers and one CI setup step. A just older than 1.59.0 does not provide the list support used
by build; direct commands remain documented and no game source changes. Generic passthroughs other than build retain
the documented shell-quoting limitation. No server protocol or behavior changes.

Compatibility

  • Saves: unchanged.
  • Options file: unchanged.
  • Caches, bases, packs and installed builder tools: unchanged.
  • MkwVkHost/MkwVkRenderer ABI: unchanged, MKWVK_API_VERSION not bumped.
  • Build invocation: the same nx2/make_game.py arguments reach the builder; only their shell quoting is fixed.
  • CI: only the workflow-lint job gains pinned downloads; other jobs' commands are unchanged.

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched). No existing issue fits this new command index.
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how.
  • Rebased on current main. The branch is based on aa95d35f, which still matches origin/main.
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named). The exact same 13 base failures are named above; this PR adds one passing check.
  • No game files, dumps, build output or generated files. Explicitly verified: no .nup is tracked or staged.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • A check under tests/ that reads changed source updated in this PR, not weakened. tests/test_justfile.py covers the new justfile and its documented commands.
  • Docs updated.
**Type:** build · **Risk:** low · **Tested on:** Linux, game-free checks and a full local build; no GPU run · **Needs:** Windows command-line smoke test, no GPU ## Why The repository's build, test, team and packaging commands were spread across scripts and guides, and a just wrapper split an escaped .nup filename at every space. Contributors need one readable command index whose recipes preserve the documented commands and arguments. No existing issue covers this command-index work. ## What changed Add a root justfile with 29 thin recipes, a listing-only default, full-test and CI-safe lint commands, and argument-safe `build` forwarding using just 1.59.0's opt-in list support. Keep direct commands documented, modernize contributor and agent guides without changing clone instructions, and pin just plus actionlint in the workflow-lint CI job. Windows uses an explicit `cmd.exe /c` shell so bare `just` does not require `sh`. - `justfile`: command groups for checks, repository rules, team commands, the game and Linux packaging; bare `just` lists recipes, `just test` runs the game-free suite, and `just lint --check` fails on formatting or workflow-lint errors. - `justfile`: `build` double-quotes each forwarded argument separately, preserving whitespace and brackets. Other script bodies remain in their scripts rather than being inlined. - `tests/test_justfile.py`: 14 checks for the documented copy, 29-recipe manifest, one-line bodies, documented-command parity, listing-only default behavior and the escaped .nup path regression. - `CONTRIBUTING.md`, `AGENTS.md`, `docs/development.md`, `docs/justfile.md`: just-first commands and agent discovery, with canonical direct commands and clone steps retained. - `.forgejo/workflows/ci.yml`: the workflow-lint job downloads pinned just 1.59.0 and actionlint 1.7.12, verifies both SHA-256 hashes, and runs `just lint --check`. Other CI jobs keep direct commands and do not download just. ## Measurements N/A — no fps, VRAM, load-time or AppImage-size claim; command wrappers, documentation, checks and CI setup only. ### Flags and settings None — no game flags or settings changed. The justfile explicitly enables just 1.59.0's `unstable` and `lists` settings so `build` can quote each argument separately; CI pins that just version. ## Testing **Tested:** on Linux, with no dump needed except for the explicitly requested local build: - `just lint --check` with just 1.59.0 and CI-pinned actionlint 1.7.12: passed; the archive's SHA-256 was verified. - `python -I -B tests/run_all.py justfile`: 1 passed. Direct `python -I -B tests/test_justfile.py`: 14 checks passed. - `just test`: 517 passed, 13 failed, 64 skipped. Base `main @ aa95d35f` (`python -I -B tests/run_all.py`): 516 passed, 13 failed, 64 skipped, with the exact same failure set. The only delta is the new passing `tests/test_justfile.py`. The pre-existing failures are `test_lift_cleanup_error.py`, `test_make_game_cache.py`, `test_crash_dialog.py`, `test_cpm_discovery.py`, `test_env_on.py`, `test_appimage_player_build.py`, `test_options_budget_once.py`, `test_linux_preflight.py`, `test_pipeline_tour.py`, `test_mods_size_table.py`, `test_readback_late.py`, `test_vk_pgo.py` and `test_walk_key.py`. - The exact requested `just build` with an escaped .nup path containing spaces and brackets: full Linux build completed with exit code 0 and `@@done /mnt/sdd1/games/Longshot/build`. Before the fix it failed during argument parsing. - Windows 11 review by Rogasse on `63e949db`: `just --list`, 14 justfile tests, formatting and spaced/bracketed synthetic path quoting passed; bare `just` exposed just 1.59.0's default `sh` dependency. `b8602afd` pins the tester's confirmed `cmd.exe /c` override; Linux justfile manifest checks and bare `just` pass on that head. Windows retest is below. - `just --fmt --check --unstable`, `just`, `just --list`, `git diff --check`, and documented build/check-dump/test/lint dry runs: passed. No .nup file is staged or tracked. **Not tested:** Windows `cmd` on `b8602afd` (the previous head exposed the bare-`just` shell failure), the Windows PowerShell `just run` recipe, or an in-game GPU run. No game code changed; the corrected Windows shell needs a retest. **Must be tested:** - Windows 11, no GPU, by hand: on `b8602afd` with just 1.59.0 and no `sh` in PATH, run bare `just`, expecting the complete recipe list without a shell override; repeat the spaced/bracketed synthetic `just build` dry-run, expecting one intact quoted path, and run the 14 justfile tests, expecting all to pass. No game dump is needed; report the commands and output on this PR. ## Risks Low: contributor command wrappers and one CI setup step. A just older than 1.59.0 does not provide the list support used by `build`; direct commands remain documented and no game source changes. Generic passthroughs other than `build` retain the documented shell-quoting limitation. No server protocol or behavior changes. ### Compatibility - Saves: unchanged. - Options file: unchanged. - Caches, bases, packs and installed builder tools: unchanged. - `MkwVkHost`/`MkwVkRenderer` ABI: unchanged, `MKWVK_API_VERSION` not bumped. - Build invocation: the same `nx2/make_game.py` arguments reach the builder; only their shell quoting is fixed. - CI: only the workflow-lint job gains pinned downloads; other jobs' commands are unchanged. ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). No existing issue fits this new command index. - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [x] Testing names what was tested, what wasn't, and what must still be tested, where and how. - [x] Rebased on current `main`. The branch is based on `aa95d35f`, which still matches `origin/main`. - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). The exact same 13 base failures are named above; this PR adds one passing check. - [x] No game files, dumps, build output or generated files. Explicitly verified: no .nup is tracked or staged. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. `tests/test_justfile.py` covers the new justfile and its documented commands. - [x] Docs updated.
build: add just command recipes
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 4s
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
63e949dbe1
Assisted-by: DeepSeek Harness
Author
Contributor

Added the applicable source-check and documentation checklist boxes identified by pr status; no code changed.

Added the applicable source-check and documentation checklist boxes identified by pr status; no code changed.
Author
Contributor

Aligned the Docs updated checklist entry with the exact template wording; no code changed.

Aligned the Docs updated checklist entry with the exact template wording; no code changed.
First-time contributor

Windows smoke test on PR head 63e949dbe1a67697434b86b8197b39f409bbd03f (Windows 11, PowerShell and cmd, official just 1.59.0):

  • just --list: PASS; the 29 recipes are listed.
  • Bare just: FAIL in both PowerShell and cmd: recipe default could not be run because just could not find the shell sh: program not found.
  • just --shell cmd.exe --shell-arg /c and just --shell powershell.exe --shell-arg -Command: PASS; the default recipe lists the recipes with either override.
  • just --dry-run build --nup 'C:\Fake Folder\Game [v131072].nup' --out 'C:\Fake Folder\Longshot [test]': PASS; each synthetic path appears intact and double-quoted in the generated Python command. No build or game file was used.
  • python -I -B tests/test_justfile.py: PASS (14 tests). just --fmt --check --unstable: PASS.

The justfile leaves shell and windows_shell unset. just 1.59.0 defaults to sh on Windows even when launched from PowerShell/cmd, so the documented bare just entry point does not work on a Windows setup without sh in PATH. A Windows shell setting or a platform-specific default-list approach should fix this; a runtime test of bare just would catch it.

Windows smoke test on PR head `63e949dbe1a67697434b86b8197b39f409bbd03f` (Windows 11, PowerShell and cmd, official `just 1.59.0`): - `just --list`: PASS; the 29 recipes are listed. - Bare `just`: FAIL in both PowerShell and cmd: `recipe default could not be run because just could not find the shell sh: program not found`. - `just --shell cmd.exe --shell-arg /c` and `just --shell powershell.exe --shell-arg -Command`: PASS; the default recipe lists the recipes with either override. - `just --dry-run build --nup 'C:\Fake Folder\Game [v131072].nup' --out 'C:\Fake Folder\Longshot [test]'`: PASS; each synthetic path appears intact and double-quoted in the generated Python command. No build or game file was used. - `python -I -B tests/test_justfile.py`: PASS (14 tests). `just --fmt --check --unstable`: PASS. The justfile leaves `shell` and `windows_shell` unset. `just` 1.59.0 defaults to `sh` on Windows even when launched from PowerShell/cmd, so the documented bare `just` entry point does not work on a Windows setup without `sh` in PATH. A Windows shell setting or a platform-specific default-list approach should fix this; a runtime test of bare `just` would catch it.
fix(just): support Windows without sh
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 3s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
b8602afd38
Assisted-by: DeepSeek Harness
Author
Contributor

@Rogasse Thanks for catching this. b8602afd now sets windows-shell to the cmd.exe /c configuration you confirmed, so bare just no longer depends on sh on Windows. Linux bare just and all 14 justfile tests still pass. Please retest that head without an override, including the synthetic spaced/bracketed build path. The PR description records your original results and the remaining retest.

@Rogasse Thanks for catching this. b8602afd now sets windows-shell to the cmd.exe /c configuration you confirmed, so bare just no longer depends on sh on Windows. Linux bare just and all 14 justfile tests still pass. Please retest that head without an override, including the synthetic spaced/bracketed build path. The PR description records your original results and the remaining retest.
futondestroyer left a comment

Review of b8602afd38: changes requested for argument forwarding.

The Windows shell correction works. With the checksum-verified official just 1.59.0 Windows binary and a PATH containing no sh, bare just lists the recipes, just --fmt --check --unstable passes, and all 14 tests/test_justfile.py checks pass. The current description checker also reports no errors.

Two runtime reproductions remain: non-build recipes split argument values containing spaces, and build corrupts a Windows output directory ending in a backslash. Inline comments give the cases. I used synthetic paths and replaced the Python command with a local argv recorder; no game dump, game build, or Forgejo write was involved in those reproductions. Please test the invoked process's argv rather than only the dry-run command text.

I did not run the full suite or a game build. This review covers the command wrappers at the named head; it is not an approval of the WIP PR.

Review of b8602afd38107338ec8e7171db2a2c869c967c4e: changes requested for argument forwarding. The Windows shell correction works. With the checksum-verified official just 1.59.0 Windows binary and a PATH containing no sh, bare just lists the recipes, just --fmt --check --unstable passes, and all 14 tests/test_justfile.py checks pass. The current description checker also reports no errors. Two runtime reproductions remain: non-build recipes split argument values containing spaces, and build corrupts a Windows output directory ending in a backslash. Inline comments give the cases. I used synthetic paths and replaced the Python command with a local argv recorder; no game dump, game build, or Forgejo write was involved in those reproductions. Please test the invoked process's argv rather than only the dry-run command text. I did not run the full suite or a game build. This review covers the command wrappers at the named head; it is not an approval of the WIP PR.
@ -0,0 +88,4 @@
# forge.py pr <create|update|status|view|ready|wip|comment|checkout|edit> ...
@pr *args:
{{ py }} -I scripts/forge.py pr {{ args }}
Member

[P2] Preserve argument boundaries in the non-build wrappers. In a Windows runtime test, just pr update 1 --comment "what changed and why" reached the local argv recorder as four separate words after --comment. Similarly, just check-dump with one synthetic argument C:\Fake Folder\Game [v131072].nup reached it as three path fragments (line 109). No remote command or game build was executed: PYTHON pointed to a local argv recorder. The documentation acknowledges this limitation, but AGENTS.md and CONTRIBUTING.md now replace working direct commands with these wrappers, including multiword --comment examples. Please preserve individual arguments in these recipes and add actual argv regression checks; dry-run output alone cannot verify the shell boundary.

[P2] Preserve argument boundaries in the non-build wrappers. In a Windows runtime test, just pr update 1 --comment "what changed and why" reached the local argv recorder as four separate words after --comment. Similarly, just check-dump with one synthetic argument C:\Fake Folder\Game [v131072].nup reached it as three path fragments (line 109). No remote command or game build was executed: PYTHON pointed to a local argv recorder. The documentation acknowledges this limitation, but AGENTS.md and CONTRIBUTING.md now replace working direct commands with these wrappers, including multiword --comment examples. Please preserve individual arguments in these recipes and add actual argv regression checks; dry-run output alone cannot verify the shell boundary.
@ -0,0 +102,4 @@
# A game folder from a dump: just build --nup /path/game.nup --out /games/Longshot
@build *args:
{{ py }} -I nx2/make_game.py {{ prepend('"', append('"', args)) }}
Member

[P2] Escape trailing Windows backslashes when quoting build arguments. On Windows with just 1.59.0 and this cmd.exe /c setting, passing one --out argument consisting of C:\Fake Folder\ caused the invoked argv recorder to receive C:\Fake Folder" instead: the final backslash escapes the closing quote under Windows argument parsing. A space/bracket path without a trailing backslash passes, so the existing regression does not catch it. Please use Windows-aware argument escaping or a forwarding mechanism that avoids reconstructing the command line, with a runtime test for a directory ending in a backslash. This was reproduced with synthetic paths and a local argv recorder, without running make_game.py.

[P2] Escape trailing Windows backslashes when quoting build arguments. On Windows with just 1.59.0 and this cmd.exe /c setting, passing one --out argument consisting of C:\Fake Folder\ caused the invoked argv recorder to receive C:\Fake Folder" instead: the final backslash escapes the closing quote under Windows argument parsing. A space/bracket path without a trailing backslash passes, so the existing regression does not catch it. Please use Windows-aware argument escaping or a forwarding mechanism that avoids reconstructing the command line, with a runtime test for a directory ending in a backslash. This was reproduced with synthetic paths and a local argv recorder, without running make_game.py.
Author
Contributor

Closing this now that upstream has adopted mise (mise run lint / mise run test), which covers the same command entry-point need and makes this justfile approach redundant. Thanks @Rogasse and @futondestroyer for the Windows testing and detailed argv reviews; they were valuable even though this PR will not proceed.

Closing this now that upstream has adopted mise (mise run lint / mise run test), which covers the same command entry-point need and makes this justfile approach redundant. Thanks @Rogasse and @futondestroyer for the Windows testing and detailed argv reviews; they were valuable even though this PR will not proceed.
Marcuss2 closed this pull request 2026-11-15 17:30:02 +00:00
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 3s
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled

Pull request closed

Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!810
No description provided.