cc-libs/.plans/craftos-just-plan.md

CraftOS Just Recipes Plan

Goal

Add repository-local CraftOS-PC launch recipes:

• just craftos launches CraftOS-PC with repo-local save data under .craftos.
• just repl launches the same environment with --cli for human interactive use only.
• just install delegates tool validation to a new just check-install recipe.

Findings

CraftOS-PC docs confirm -d / --directory changes the save data root. With -d .craftos, generated files should be under .craftos/config/global.json, .craftos/config/0.json, and .craftos/computer/0/, not directly as .craftos/global.json.

CraftOS-PC docs describe -C as a CCEmuX compatibility flag for the computer-data directory. Do not make -C . the default unless an isolated probe proves it gives the desired repo layout without polluting the repository root.

just runs recipes from the Justfile directory by default, and justfile_directory() is available. Use it to anchor .craftos and mount paths to the repository root even when just is invoked from a subdirectory.

manifest.json already lists the shipped files. Its top-level directories are currently startup, servers, programs, and apis.

Recommended Approach

Use --directory for persistent CraftOS-PC state and command-line mounts for repository files.

Do not use -C . as the normal path to expose this repository. It controls saved computer contents, while --mount-ro directly models the intended behavior: make repo files available in the ComputerCraft filesystem without copying them into a VM save.

Mount the repository root at /trapos so existing code can read /trapos/manifest.json. Also mount each manifest top-level directory at its ComputerCraft root path, for example /apis, /programs, /servers, and /startup.

Prefer read-only mounts by default. Use explicit caller-provided args for unusual cases.

Implementation Steps

1. Add .craftos/.gitignore so the directory exists in the repo while generated CraftOS-PC state stays untracked.

*
!.gitignore

2. Add check-jq to Justfile.

3. Add check-luacheck to Justfile so install checks every host-side CLI requirement explicitly.

4. Add check-install: check-craftos check-jq check-luacheck.

5. Change install from install-git-hooks check-craftos to install-git-hooks check-install.

6. Change check to depend on check-luacheck and keep luacheck . as the command.

7. Add craftos *args: check-install.

Recommended behavior:

• Use --directory "{{justfile_directory()}}/.craftos".
• Keep the existing macOS --rom /Applications/CraftOS-PC.app/Contents/Resources workaround.
• Add --mount-ro "/trapos={{justfile_directory()}}".
• Use jq over manifest.json to derive unique top-level directories and add one --mount-ro "/<dir>={{justfile_directory()}}/<dir>" per directory.
• Forward user args after the recipe defaults.

Sketch:

# Launch CraftOS-PC with repo-local data and read-only repo mounts. Pass args through to `craftos`.
craftos *args: check-install
    @rom_arg=""; \
    if [ "$(uname -s)" = "Darwin" ]; then \
        rom_arg="--rom /Applications/CraftOS-PC.app/Contents/Resources"; \
    fi; \
    mount_args="--mount-ro /trapos={{justfile_directory()}}"; \
    for dir in $(jq -r '.files[] | split("/")[0]' manifest.json | sort -u); do \
        mount_args="$mount_args --mount-ro /$dir={{justfile_directory()}}/$dir"; \
    done; \
    exec craftos --directory "{{justfile_directory()}}/.craftos" $rom_arg $mount_args {{args}}

8. Add repl as an interactive human-only wrapper.

# Human-only interactive REPL. LLM agents must not execute this command.
repl:
    @just craftos --cli

9. Add the same just repl restriction to CLAUDE.md under constraints or boot/install guidance.

10. Update DEVELOPMENT.md requirements to include jq.

11. If the final mount behavior changes the local harness contract, update docs/install-craftos-pc.md or ADR-0005 accordingly.

Probe Before Finalizing Mounts

Run probes in /var/folders/l7/c5f9hw8j52zg5rx0vwz7_4d40000gn/T/opencode, not in the repository first.

Compare these cases:

1. Plain repo-local data directory:

craftos -d <temp-data> --headless --exec 'print("__READY__"); os.shutdown()'

2. CCEmuX computer-data override:

craftos -d <temp-data> -C <temp-computers> --headless --exec 'print("__READY__"); os.shutdown()'

3. Explicit mounts:

craftos -d <temp-data> \
  --mount-ro /trapos=<repo> \
  --mount-ro /apis=<repo>/apis \
  --mount-ro /programs=<repo>/programs \
  --mount-ro /servers=<repo>/servers \
  --mount-ro /startup=<repo>/startup \
  --headless \
  --exec 'print(fs.exists("/apis/net.lua")); print(fs.exists("/trapos/manifest.json")); os.shutdown()'

Choose mounts unless -C demonstrably gives the desired repo-root ComputerCraft layout without repository pollution.

Verification

Run:

• just --list
• just check-install
• just craftos --help
• just craftos --headless --exec 'print("__READY__"); os.shutdown()'
• just test
• git status --short

Do not run just repl as an LLM agent.