chore: commit base plan craftos-just-plan.md

2026-06-08 03:03:14 +02:00 · 2026-06-08 03:03:14 +02:00 · 23d546c3a9
commit 23d546c3a9
parent a127a7693e
1 changed files with 134 additions and 0 deletions
--- a/.plans/craftos-just-plan.md
+++ b/.plans/craftos-just-plan.md
@ -0,0 +1,134 @@
+# 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.