picopilot 0.0.0 → 0.1.1

package/src/skills/picopilot-debug/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: picopilot-debug
+description: Close the run-test loop for a PICO-8 cart with picopilot. Run the cart headless and read printh output, use the static verify gate honestly (well-formed is not proven-to-run), and understand the structured pico8-not-found / shrinko-not-found boundaries. Use when a cart misbehaves or you need to confirm it boots.
+---
+
+# picopilot debug
+
+Static checks tell you a cart is well-formed; only running it tells you it works.
+picopilot gives you both a static gate and a headless run so you can drive a
+closed loop. (See `picopilot-overview` for the `#include` discipline and
+`picopilot-code` for the token loop.)
+
+## Static first: `picopilot verify`
+
+`picopilot verify` runs tokens + integrity and returns ONE structured pass/fail
+envelope. It is STATIC and NEVER runs the cart, so:
+
+- A green verify means "well-formed", NOT "it runs". The passing result points
+  you at `picopilot run` to confirm the cart boots. Do not stop at green.
+- A fail lists WHICH check flunked (over budget, or a malformed cart), so you fix
+  the named thing.
+- With shrinko absent, verify is `gate-incapable` (a distinct nonzero outcome,
+  NEVER green): it cannot check token bloat, so it refuses to report pass.
+
+## Then run it: `picopilot run`
+
+`picopilot run <cart>` launches PICO-8 headless (`pico8 -x`), streams stdout,
+ENDS the run the moment the cart prints a done-sentinel, and collects one
+structured result: the screenshot PNG paths, the captured `printh` stdout, and
+the exit reason (`sentinel` / `timeout` / `exit`). Read the screenshots to SEE
+the running game; read printh for text traces. On a backstop `timeout` it CTAs
+you to `verify`/`tokens` to catch a code fault.
+
+`run` requires PICO-8 (a licensed, paid binary with no pip/npm path). If PICO-8
+is absent, `run` returns a structured `pico8-not-found` result with a remedy
+(`set PICO8_PATH or install PICO-8`) and a nonzero exit, not a crash or a hang.
+Use the static `verify` loop while PICO-8 is unavailable; it never needs it.
+
+### NEVER run `pico8 --help` / `--version` / bare `pico8` (they BLOCK your tool call)
+
+PICO-8 is a GUI app with NO headless diagnostic mode. `pico8 --help`,
+`pico8 --version`, and bare `pico8` do NOT print text and exit like a normal
+CLI, they LAUNCH THE INTERACTIVE APP and hang forever (verified: `timeout 5
+pico8 --help` exits 124 with zero output). Running one from an agent/automation
+context STALLS your own tool call indefinitely (it has already bitten this
+project's agents more than once, hanging a whole build). Do NOT invoke `pico8`
+to "see its flags" or check it works. The only safe, non-blocking calls are the
+automation ones, ALWAYS with `</dev/null` + a `timeout` backstop:
+`pico8 -x <cart>`, `pico8 -run <cart>`, `pico8 <cart> -export foo.p8.png`. And
+prefer to let picopilot (`run`, `audio render`, etc.) shell out for you rather
+than calling `pico8` by hand. To learn a CLI flag, read the PICO-8 manual, never
+ask the binary.
+
+### The cart must COOPERATE (the recipe `run` orchestrates)
+
+There is no "screenshot an arbitrary running cart" hook and a cart CANNOT quit
+the PICO-8 app itself (`extcmd("shutdown")` works only in EXPORTED binaries).
+So the cart takes its own screenshots and signals when it is done, and `run`
+does the watch + kill + collect. Add these debug lines to the cart, run, then
+remove them:
+
+```lua
+-- screenshot on a frame timer (the verb is "screen", NOT "screenshot")
+if t==20 then extcmd("set_filename","frame_0") extcmd("screen") end
+if t==40 then extcmd("set_filename","frame_1") extcmd("screen") end
+-- signal done so run kills PICO-8 promptly (it can't self-quit)
+if t==45 then printh("__PICOPILOT_DONE__") end
+```
+
+Load-bearing details (each an easy wrong guess, all tested):
+
+- The screenshot verb is **`extcmd("screen")`**. `extcmd("screenshot")` ERRORS
+  ("unknown extcmd"). `extcmd("set_filename","frame_0")` before it names the next
+  shot deterministically (so you can read `frame_0.png`, `frame_1.png`, ... in
+  order and PERCEIVE MOTION by comparing frames).
+- The done-sentinel is the default `__PICOPILOT_DONE__` on its OWN line via
+  `printh`. `run` kills PICO-8 the instant it matches, so the run lasts exactly
+  as long as the cart's logic needs, no blind wait. `--sentinel` changes it.
+- A cart that never prints the sentinel is killed by the backstop
+  (`--backstop-ms`, default 15000) and reported as `exitReason: timeout`.
+- `-x` IS genuinely headless (runs with no display); the external kill is needed
+  only because a cart cannot self-quit, NOT because of a window.
+- Screenshots go to a run-controlled dir (`--shot-dir`, default an isolated temp
+  dir), never `~/Desktop`.
+
+To SEE the game actually being PLAYED (drive input + capture gameplay), use
+`picopilot playtest`, next. (`run` boots the cart and captures what it does on
+its own; `playtest` drives it.) There is also a legacy `run --input` that passes
+a one-shot `-p`/`stat(6)` string, but it only works if the cart hand-decodes
+`stat(6)`; for driving an arbitrary game, `playtest` is the tool, not `run
+--input`.
+
+## Actually PLAY it: `picopilot playtest`
+
+`picopilot playtest` drives ANY normally-written cart (one that reads real
+`btn`/`btnp`) with NO change to it: on a THROWAWAY copy it redefines `btn`/`btnp`
+to read a harness-piped held-buttons byte (reconstructing `btnp` edges) and OWNS the frame
+loop, so it advances an exact number of frames, PAUSES (freezing all state,
+including logic in `_draw`) for a clean screenshot, and captures gameplay (not
+the title). Your `main.p8` is never mutated. `playtest` requires PICO-8 and
+returns the same structured `pico8-not-found` boundary as `run` when it is
+absent. (Mechanism: ADR-0011.)
+
+There are three ways to drive a cart; pick by how much continuity you need.
+
+### One-shot: `picopilot playtest run <cart>`
+
+The whole scripted input is known up front, so the cart replays it to completion
+and exits, returning ONE envelope (screenshot paths + captured printh + the
+steps run). Great for a scripted playtest or benchmark judging.
+
+```
+picopilot playtest run main.p8                          # generic driver (press-to-start + gentle presses)
+picopilot playtest run game.p8 --input "z"              # just press O (a bare button = a press at frame 0)
+picopilot playtest run game.p8 --input "3:o, 18-22:o, 20:right"  # a timeline: press/hold at specific frames
+picopilot playtest run game.p8 --seed 1 --input "o"     # opt-in srand for deterministic replay
+```
+
+`--input` accepts EITHER a bare list of buttons (`"z"`, `"o right"`, pressed at
+frame 0, the same "just press these" form as the session `input` verb) OR a
+timeline of `frame:button` (a single press, one clean `btnp` edge) /
+`from-to:button` (a hold). A button is a NAME (`o x left right up down`, aliases
+`l r u d`, PICO-8 keys `z`/`x`) or a bit `0..5`. Omit `--input` for the generic
+one-button/runner/flappy driver. `--seed n` injects `srand(n)` at cart start
+(never silent) so a random cart replays identically. Screenshots go to
+`--shot-dir` (default an isolated temp dir, NEVER `~/Desktop`).
+
+### (A) Resumable LIVE session: `start` -> `step`/`input`/`shot` -> `stop`
+
+When you want to PLAY across turns (look at the last frame, decide, inject input,
+step, look again), keep the game ALIVE and PAUSED between your turns. `start`
+launches a persistent driven PICO-8 and returns a SESSION ID; every other verb
+addresses that id in a SEPARATE invocation, and the game stays alive + paused in
+between. Stepping is deterministic via a stdout ACK handshake (the host waits for
+the cart's ack before returning), so you always act on a settled, known frame, no
+wall-clock guessing.
+
+```
+ID=$(picopilot playtest start main.p8 --format json | jq -r .id)   # launch, get the id
+picopilot playtest input  $ID "right o"    # hold buttons for the next steps (names: left/right/up/down/o/x)
+picopilot playtest step   $ID --frames 30  # advance EXACTLY 30 frames, then pause
+picopilot playtest shot   $ID              # screenshot the current frozen frame -> a PNG path
+picopilot playtest status $ID              # is it alive? how many frames in?
+picopilot playtest stop   $ID              # tear it down (quit PICO-8, reap the dir)
+```
+
+Lifecycle notes (each verified/handled, not a hope):
+
+- Each verb WRITES a fixed-size command block and WAITS for the cart's ACK, so a
+  `step N` advances exactly N frames and a `shot` between steps captures the
+  frozen intended frame. Between verbs the game is frozen (stable framebuffer).
+- ONE session per id; MULTIPLE concurrent sessions are allowed (distinct ids get
+  distinct daemons/dirs). Omit `--id` for a fresh random id; pass `--id name` for
+  a stable one.
+- ORPHAN reaping: a session you never `stop` self-reaps after an idle window
+  (`--idle-timeout-ms`, default 10 min), so a walked-away session cannot leak a
+  live PICO-8 forever. `stop` is idempotent (safe on an already-dead session).
+- PICO-8 dying mid-session surfaces as a STRUCTURED error on the next verb
+  (`playtest-session-process-dead`), never a hang; a command with no ACK by the
+  deadline is `playtest-session-ack-timeout`. `start` with PICO-8 absent is
+  `pico8-not-found`, same as `run`.
+- Screenshots + the throwaway driven cart live under a controlled temp session
+  dir, never `~/Desktop` or your carts root.
+
+### (C) Stateless REPLAY (the free fallback, no daemon)
+
+You do NOT always need a live session. Because the one-shot is deterministic
+under `--seed`, you can "resume" by RE-INVOKING `playtest run` with an
+ACCUMULATING script each turn: re-run from frame 0 with the same seed plus the
+new presses appended. It is cheap, reproducible, and daemon-free.
+
+```
+picopilot playtest run game.p8 --seed 1 --input "3:4"                 # turn 1
+picopilot playtest run game.p8 --seed 1 --input "3:4, 40:1"          # turn 2 (replays turn 1, then the new press)
+picopilot playtest run game.p8 --seed 1 --input "3:4, 40:1, 55:5"    # turn 3 ...
+```
+
+Prefer (C) for short, replay-safe games (it needs no live process). Use the live
+session (A) for true continuity: long games, or games that reseed from a
+NON-deterministic source (wall-clock/entropy) mid-run and so cannot be replayed
+from frame 0. Both drive the SAME cart-side transform; only the host lifecycle
+differs.
+
+## The two structured boundaries
+
+Both dependency boundaries are soft and well-signposted, so read the result, do
+not guess:
+
+- `shrinko-not-found` (remedy `uv pip install shrinko`): gates the token/lint
+  commands and therefore `verify`.
+- `pico8-not-found` (remedy `set PICO8_PATH or install PICO-8`): gates `run`,
+  `playtest`, `audio render`, and binary/PNG exports.
+
+Each is a structured `{ ok: false, reason, remedy }` envelope with a nonzero
+exit, telling you exactly which capability is gated and how to enable it.

package/src/skills/picopilot-overview/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: picopilot-overview
+description: Start here for any PICO-8 cart built with picopilot. The #include discipline (edit main.lua, never the .p8 binary sections), the per-iteration verify loop, and which deeper skill to load for code, art, audio, or debugging. Use when you open a picopilot cart folder or run picopilot init.
+---
+
+# picopilot overview
+
+picopilot is the transpile-and-verify layer between what you are good at (text)
+and PICO-8's reality (binary cart sections). It gives you eyes (render sprites to
+a viewable PNG), token-bloat detection, safe cart editing, and one static
+acceptance gate, so you can build a PICO-8 game and self-correct.
+
+Load this skill first. Then load the group skill for whatever you are doing:
+`picopilot-code`, `picopilot-art`, `picopilot-audio`, or `picopilot-debug`.
+
+## The #include discipline (how every picopilot cart is laid out)
+
+- `main.p8` is the cart. Its `__lua__` section is a single line: `#include main.lua`.
+- `main.lua` is the plain Lua you EDIT. You work in ordinary Lua and never
+  hand-write the cart's binary hex sections (`__gfx__`, `__map__`, `__sfx__`,
+  `__music__`).
+- To touch a binary section, use picopilot's commands (`gfx set`, the audio
+  transpiles). They edit those sections safely and round-trippably. Editing hex
+  by hand is how art and audio silently break.
+
+`picopilot init` scaffolds this layout: `main.p8`, `main.lua`, an `AGENTS.md`
+PICO-8 reference you should read, and a `picopilot.json` config.
+
+## The iteration loop
+
+Every change follows the same shape:
+
+1. Edit `main.lua` (or a cart section via a picopilot command).
+2. `picopilot tokens` to watch the 8,192-token budget (see `picopilot-code`).
+3. `picopilot verify` as the single static acceptance gate.
+
+`picopilot verify` is STATIC: it runs tokens + integrity and NEVER runs the cart.
+A green verify means "well-formed", not "it works", so a passing verify points
+you at `picopilot run` to confirm the cart actually boots. Never treat a green
+static gate as done.
+
+If shrinko is not installed, token-backed commands (and therefore `verify`) fail
+with a structured `shrinko-not-found` result carrying the exact remedy
+`uv pip install shrinko`. `verify` in that state returns `gate-incapable`, never
+green, so the gate can never pass by skipping its most important check.
+
+## Making your agent discover picopilot
+
+`picopilot init` PRINTS how to make your agent discover these skills; it does not
+silently write into your shared skill dirs. To actually install them, run
+`picopilot init --install-skills` (or `picopilot skills add`). That is the one
+deliberate, opt-in write to a shared location.

package/src/version.ts

@@ -0,0 +1,22 @@
+import {readFileSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+/**
+ * The installed picopilot version, read from the package manifest at load time.
+ *
+ * Single source of truth: the version lives only in `package.json`. The manifest
+ * sits one level above the compiled module (`dist/version.js` → `package.json`)
+ * and one level above the source module (`src/version.ts` → `package.json`), so
+ * the same relative lookup works for both the built binary and `tsx` dev runs.
+ */
+function readVersion(): string {
+	const here = dirname(fileURLToPath(import.meta.url));
+	const manifestPath = join(here, '..', 'package.json');
+	const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as {
+		version?: string;
+	};
+	return manifest.version ?? '0.0.0';
+}
+
+export const VERSION = readVersion();