# 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
*
!.gitignore
```

2. Add `check-jq` to `Justfile`.

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

   `check-jq` and `check-luacheck` are tool-presence checks only (verify the binary is on `$PATH`), mirroring the shape of the existing `check-craftos`. They do not run lint.

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. Because `check-luacheck` only verifies presence (step 3), no lint runs twice.

   Leave `ci: check-craftos check` unchanged. `ci` deliberately does not pull in `check-jq`: the pre-commit path does not use `jq`, so adding it would inflate the hook's required tooling for no benefit. The two dep chains (`install → check-install`, `ci → check-craftos + check → check-luacheck`) are intentional, not an oversight to unify later.

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. `just` forwards flags to variadic recipes normally, so callers should use commands like `just craftos --headless` and `just craftos --exec 'print("__READY__"); os.shutdown()'` without an extra `--` separator.

Build the recipe-generated argv with quoted arguments and invoke `craftos` with forwarded user args as `"$@"` so paths and `--exec` code containing spaces survive. Do not use unquoted `$mount_args` word splitting, and do not use `{{args}}` for forwarding because it does not preserve shell quoting.

Sketch:

```just
# Launch CraftOS-PC with repo-local data and read-only repo mounts.
# Pass args through to `craftos`, for example:
#   just craftos --headless --exec 'print("__READY__"); os.shutdown()'
[positional-arguments]
craftos *args: check-install
    #!/usr/bin/env bash
    set -euo pipefail
    repo='{{justfile_directory()}}'
    argv=(--directory "$repo/.craftos")
    if [ "$(uname -s)" = "Darwin" ]; then
        argv+=(--rom /Applications/CraftOS-PC.app/Contents/Resources)
    fi
    argv+=(--mount-ro "/trapos=$repo")
    while IFS= read -r dir; do
        argv+=(--mount-ro "/$dir=$repo/$dir")
    done < <(jq -r '.files[] | split("/")[0]' manifest.json | sort -u)
    exec craftos "${argv[@]}" "$@"
```

Verify the shebang recipe receives variadic args as `"$@"` before committing. If it does not, use a linewise `[positional-arguments]` recipe that delegates to `bash -c '...' craftos "$@"`; do not fall back to `{{args}}`.

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

```just
# 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:

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

2. CCEmuX computer-data override:

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

3. Explicit mounts:

```sh
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()'
```

4. macOS `-d` + `--rom` combo (the recipe's actual shape):

```sh
craftos -d <temp-data> \
  --rom /Applications/CraftOS-PC.app/Contents/Resources \
  --mount-ro /trapos=<repo> \
  --headless \
  --exec 'print(fs.exists("/trapos/manifest.json")); os.shutdown()'
```

This must succeed before committing the macOS branch of the recipe — `-d` changes data-root resolution, and the existing test recipe only proves `--rom` works without `-d`.

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.