# 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.

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:

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

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

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.