picopilot 0.0.0 → 0.1.1

package/src/engine/pico8/supervisor.ts

@@ -0,0 +1,197 @@
+/**
+ * The playtest SESSION SUPERVISOR (ADR-0011, prd US #6): the daemon that keeps a
+ * driven PICO-8 process ALIVE + PAUSED across the agent's separate CLI turns, and
+ * the client the per-verb sub-invocations use to address it BY ID.
+ *
+ * The problem this solves: `playtest step <id>` / `input <id>` / `shot <id>` are
+ * SEPARATE process invocations, but the driven PICO-8 must survive between them
+ * (staying alive + paused). A one-shot CLI process cannot hold another process's
+ * pipe, so `start` spawns a small DETACHED daemon that owns the live process + its
+ * stdin/stdout (via {@link DriveSession}) and listens on a per-session Unix domain
+ * socket; each later verb CONNECTS to that socket, sends its request, and gets the
+ * structured result back. The session is addressed by an id = the socket + a
+ * session dir under a controlled temp base (never `~/Desktop`, never the carts
+ * root).
+ *
+ * Lifecycle robustness (US #6 acceptance):
+ *  - ORPHAN reaping: the daemon self-reaps after an IDLE timeout (no verb within
+ *    the window), so a session whose agent never `stop`s it does not leak a live
+ *    PICO-8 forever. `stop <id>` tears it down promptly.
+ *  - PICO-8 dying mid-session surfaces as a STRUCTURED error (via
+ *    {@link SessionError}), not a hang; the next verb reports `process-dead`.
+ *  - `start` with PICO-8 ABSENT returns the same structured `pico8-not-found`
+ *    boundary as `run`/`audio render`.
+ *
+ * ONE session per id (the id IS the socket). Multiple concurrent sessions ARE
+ * allowed (distinct ids/dirs/daemons); the tool does not serialize them, an agent
+ * that wants isolation uses distinct ids (the default id is random, so parallel
+ * `start`s never collide).
+ *
+ * The pure, CI-testable pieces (the id/path registry, the request/response codec)
+ * live here alongside the IO daemon; the live daemon end-to-end is the
+ * manual/opt-in tier. The handshake core it drives ({@link DriveSession}) is
+ * separately unit-tested against a fake process.
+ */
+
+import {randomBytes} from 'node:crypto';
+import {existsSync, mkdirSync, readdirSync, rmSync, statSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+
+/** The controlled base dir all session dirs live under (never `~/Desktop`). */
+export const SESSION_BASE_DIRNAME = 'picopilot-playtest-sessions' as const;
+
+/**
+ * The default IDLE-reap window: a daemon with no verb for this long tears its
+ * session (and the live PICO-8) down, so an orphaned session (the agent walked
+ * away without `stop`) cannot leak a process indefinitely. Every verb resets it.
+ */
+export const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60_000;
+
+/** The session verbs a client can send the daemon over the socket. */
+export type SessionVerb = 'input' | 'step' | 'shot' | 'stop' | 'status';
+
+/** A request sent from a verb sub-invocation to the session daemon. */
+export type SessionRequest =
+	| {readonly verb: 'input'; readonly held: number}
+	| {readonly verb: 'step'; readonly frames: number}
+	| {readonly verb: 'shot'}
+	| {readonly verb: 'stop'}
+	| {readonly verb: 'status'};
+
+/** A structured daemon response: either an ok payload or a structured error. */
+export type SessionResponse =
+	| {readonly ok: true; readonly value: SessionResponseValue}
+	| {readonly ok: false; readonly code: string; readonly message: string};
+
+/** The ok payload shape (a superset; each verb fills the relevant fields). */
+export interface SessionResponseValue {
+	/** The session id. */
+	readonly id: string;
+	/** Total frames advanced so far. */
+	readonly frame: number;
+	/** The ACK line the cart printed for this command (settled-frame proof). */
+	readonly ack?: string;
+	/** For `shot`: the absolute screenshot path the cart just wrote. */
+	readonly screenshot?: string;
+	/** For `shot`: the basename the cart named the capture. */
+	readonly shotName?: string;
+	/** Whether the session is still alive after this verb. */
+	readonly alive: boolean;
+}
+
+/**
+ * Encodes a request/response as a single newline-terminated JSON frame (the
+ * socket protocol). Newline-framed so a reader can split a stream into whole
+ * messages; kept pure so the codec is unit-tested without a socket.
+ */
+export function encodeFrame(msg: SessionRequest | SessionResponse): string {
+	return `${JSON.stringify(msg)}\n`;
+}
+
+/**
+ * A stateful frame decoder mirroring {@link encodeFrame}: feed it raw socket
+ * chunks, it yields whole parsed messages (buffering partial lines). Typed loose
+ * (`T`) because a client decodes responses and the daemon decodes requests.
+ */
+export class FrameDecoder<T> {
+	private buffer = '';
+	push(chunk: string): T[] {
+		this.buffer += chunk;
+		const out: T[] = [];
+		let nl: number;
+		while ((nl = this.buffer.indexOf('\n')) !== -1) {
+			const line = this.buffer.slice(0, nl);
+			this.buffer = this.buffer.slice(nl + 1);
+			if (line.trim().length > 0) out.push(JSON.parse(line) as T);
+		}
+		return out;
+	}
+}
+
+/** A resolved session's on-disk layout (all under the controlled base). */
+export interface SessionPaths {
+	/** The session id (also the dir name under the base). */
+	readonly id: string;
+	/** The session dir: `<base>/<id>`. */
+	readonly dir: string;
+	/** The Unix domain socket the daemon listens on. */
+	readonly socket: string;
+	/** The `-desktop` dir PICO-8 writes SHOT screenshots into. */
+	readonly shotDir: string;
+	/** The pidfile written by the daemon (for reap/liveness checks). */
+	readonly pidfile: string;
+}
+
+/**
+ * The session REGISTRY: the pure id/path logic mapping a session id to its
+ * on-disk layout under a controlled base dir. No IO beyond the base-dir join, so
+ * the id validation + path derivation are unit-tested. The daemon and the client
+ * both resolve a session THROUGH this, so they agree on where the socket is.
+ */
+export class SessionRegistry {
+	readonly base: string;
+
+	constructor(base?: string) {
+		this.base = base ?? join(tmpdir(), SESSION_BASE_DIRNAME);
+	}
+
+	/** A fresh random session id (short, filesystem-safe, collision-free enough). */
+	static freshId(): string {
+		return `s-${randomBytes(6).toString('hex')}`;
+	}
+
+	/**
+	 * Validates a caller-supplied id: filesystem-safe, no path traversal, so an id
+	 * can never escape the controlled base. Returns the id or throws a plain Error
+	 * (the command maps it to a structured refusal).
+	 */
+	static validateId(id: string): string {
+		if (!/^[A-Za-z0-9._-]{1,64}$/.test(id) || id === '.' || id === '..') {
+			throw new Error(
+				`invalid session id "${id}": use 1-64 chars of [A-Za-z0-9._-]`,
+			);
+		}
+		return id;
+	}
+
+	/** Resolves a session id to its {@link SessionPaths} under the base. */
+	resolve(id: string): SessionPaths {
+		SessionRegistry.validateId(id);
+		const dir = join(this.base, id);
+		return {
+			id,
+			dir,
+			socket: join(dir, 'sock'),
+			shotDir: join(dir, 'shots'),
+			pidfile: join(dir, 'pid'),
+		};
+	}
+
+	/** Creates the session dir + shot dir (idempotent), returning the paths. */
+	create(id: string): SessionPaths {
+		const paths = this.resolve(id);
+		mkdirSync(paths.shotDir, {recursive: true});
+		return paths;
+	}
+
+	/** The ids of all sessions with a dir present under the base (for listing/reap). */
+	list(): string[] {
+		if (!existsSync(this.base)) return [];
+		return readdirSync(this.base)
+			.filter((name) => {
+				try {
+					return statSync(join(this.base, name)).isDirectory();
+				} catch {
+					return false;
+				}
+			})
+			.sort();
+	}
+
+	/** Removes a session's whole dir (the reap/cleanup, after the daemon exits). */
+	remove(id: string): void {
+		const {dir} = this.resolve(id);
+		rmSync(dir, {recursive: true, force: true});
+	}
+}

package/src/engine/scaffold/index.ts

@@ -0,0 +1,15 @@
+/**
+ * The static content `picopilot init` scaffolds: the `#include`-discipline
+ * `main.p8` (built through the cart model), the editable `main.lua`, the curated
+ * `AGENTS.md` PICO-8 reference, and the `picopilot.json` config. See
+ * `scaffold.ts` for the single scaffolding model and why these are the files.
+ */
+export {
+	agentsMd,
+	LUA_INCLUDE_LINE,
+	mainLua,
+	mainP8,
+	picopilotJson,
+	type ScaffoldFile,
+	scaffoldFiles,
+} from './scaffold.js';

package/src/engine/scaffold/scaffold.ts

@@ -0,0 +1,278 @@
+import {Cart} from '../cart/index.js';
+import {defaultConfigFile} from '../config/index.js';
+
+/**
+ * The static content `picopilot init` writes into a fresh cart folder.
+ *
+ * The single scaffolding model (US #1): the `.p8`'s `__lua__` section is exactly
+ * `#include main.lua`, and the plain-Lua `main.lua` is the file the agent edits,
+ * so the agent never hand-writes the cart's binary hex sections. `main.p8` is
+ * built THROUGH the cart model (not a hand-written string) so init and every
+ * later cart-touching command share one serializer and the output is guaranteed
+ * to round-trip.
+ */
+
+/** The PICO-8 cart format version init emits (the current stable text-format version). */
+const CART_VERSION = 42;
+
+/**
+ * The one line of code in the scaffolded cart. PICO-8's `#include` pulls the
+ * external Lua file in at load time; keeping it the ONLY thing in `__lua__` is
+ * the `#include` discipline the whole toolchain relies on.
+ */
+export const LUA_INCLUDE_LINE = '#include main.lua';
+
+/**
+ * Builds the scaffolded `main.p8` via the cart model. `__lua__` holds only the
+ * `#include`; the cart carries no binary sections yet (a fresh cart has no gfx /
+ * map / sfx / music); those are added later by the gfx/audio commands.
+ */
+export function mainP8(): string {
+	const cart = Cart.parse(
+		`pico-8 cartridge // http://www.pico-8.com\nversion ${CART_VERSION}\n__lua__\n`,
+	);
+	cart.setSection('lua', `${LUA_INCLUDE_LINE}\n`);
+	return cart.serialize();
+}
+
+/**
+ * The starter `main.lua`: a minimal but RUNNABLE cart (the `_init/_update/_draw`
+ * loop the API reference calls out as load-bearing) so a fresh folder boots
+ * instead of being inert. Intentionally tiny: it is a starting point the agent
+ * replaces, not a demo.
+ */
+export function mainLua(): string {
+	return `-- main.lua, the plain-Lua source picopilot's main.p8 #includes.
+-- Edit THIS file; never hand-write main.p8's binary sections.
+
+function _init()
+end
+
+function _update()
+end
+
+function _draw()
+  cls()
+  print("hello picopilot", 36, 60, 7)
+end
+`;
+}
+
+/** The scaffolded `picopilot.json` (incur config: precedence argv > config > defaults). */
+export function picopilotJson(): string {
+	return defaultConfigFile();
+}
+
+/**
+ * The curated PICO-8 reference written to `AGENTS.md`.
+ *
+ * This is CONTEXT an agent loads every turn, so it is CURATED from
+ * `work/notes/findings/pico8-api-reference.md`, not a dump of the manual: the
+ * hard specs, the `_init/_update/_draw` loop, the fixed palette, the memory map
+ * + the gfx/map overlap WARNING, the grouped most-used API, and the token
+ * discipline, the things models get wrong without a reference.
+ */
+export function agentsMd(): string {
+	return `# PICO-8 cart context (generated by \`picopilot init\`)
+
+You are editing a PICO-8 cart with picopilot. This file is your always-loaded
+reference: the constraints, the loop, the palette, the memory map (+ the overlap
+warning), the most-used API, and how to stay under the token budget. It is
+curated from PICO-8's manual for the things models get wrong without a reminder.
+
+## The \`#include\` discipline (how this 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. Never hand-write \`main.p8\`'s binary
+  sections (\`__gfx__\`, \`__map__\`, \`__sfx__\`, \`__music__\`), use picopilot's
+  \`gfx\` / audio commands, which edit them safely and round-trippably.
+
+## Hard specs (the constraints that shape everything)
+
+- Display: **128x128**, a **fixed 16-colour palette** (indices 0..15).
+- Code: **Lua**, max **8192 tokens** (the #1 thing to watch). Run \`picopilot tokens\`.
+- Sprites: 256 8x8 sprites in a base bank (0..127) plus a shared bank (128..255).
+- Map: 128x32 tiles + a shared half that ALIASES sprites 128..255 (see below).
+- Sound: 4 channels, 64 SFX slots; music is patterns of up to 4 SFX references.
+- Numbers: 16.16 fixed point, range \`-32768.0 .. 32767.99\`.
+
+## The execution loop (every cart)
+
+- \`_init()\`: runs once at startup.
+- \`_update()\`: runs every update tick at 30fps (\`_update60()\` for 60fps).
+- \`_draw()\`: runs once per visible frame.
+
+A cart with none of these is inert. Keep them defined.
+
+## The build loop (do this every iteration, and to finish)
+
+One change = one pass through this loop. Do NOT skip the last step:
+
+1. Edit \`main.lua\` (or a cart section via a picopilot command).
+2. \`picopilot tokens\` to watch the 8192-token budget.
+3. \`picopilot verify\` (the static gate: tokens + integrity). GREEN means
+   well-formed, it does NOT mean the cart runs or plays.
+4. **SEE it run.** Add a temporary probe to \`main.lua\` and \`picopilot run\`, then
+   LOOK at the screenshot PNG. Remove the probe after. Or use
+   \`picopilot playtest run\` to drive input and screenshot live gameplay with no
+   cart edit. Probe recipe:
+
+   \`\`\`lua
+   -- TEMPORARY: screenshot a couple of frames, then signal done so run exits.
+   if t==20 then extcmd("set_filename","probe_0") extcmd("screen") end
+   if t==40 then extcmd("set_filename","probe_1") extcmd("screen") end
+   if t==45 then printh("__PICOPILOT_DONE__") end
+   \`\`\`
+
+**Definition of done: you have looked at a screenshot of the running cart and it
+renders what you intended.** A green \`verify\` is NOT done. A \`picopilot run\`
+that ends in \`exitReason: timeout\` with NO screenshot is NOT proof it works, it
+just means the cart never self-quit; you still have not seen it. Never declare a
+game finished on static checks or a bare timeout alone.
+
+## Handing the finished cart to the user
+
+When it is verified and looks right, tell the user to play it with:
+
+\`\`\`sh
+pico8 -run /absolute/path/to/main.p8
+\`\`\`
+
+(or \`picopilot run\` for a headless screenshot pass). Do NOT reach for
+\`picopilot serve\` to prove your own build: that exports + serves a browser build
+for SHARING a playable cart with a human, needs a cart \`__label__\`, and puts a
+human-in-the-loop where none is needed. Verify with \`run\`/\`playtest\`; serve only
+if the user explicitly wants a browser build. And do NOT emit extra deliverables
+(summary docs, play-guides, shell scripts, ASCII banners): the deliverable is the
+verified cart itself.
+
+## The fixed 16-colour palette (index → RGB)
+
+In a char grid, \`.\` = transparent and \`0-F\` = these indices.
+
+| idx | hex | name        | R   | G   | B   |
+|-----|-----|-------------|-----|-----|-----|
+| 0   | 0   | black       | 0   | 0   | 0   |
+| 1   | 1   | dark-blue   | 29  | 43  | 83  |
+| 2   | 2   | dark-purple | 126 | 37  | 83  |
+| 3   | 3   | dark-green  | 0   | 135 | 81  |
+| 4   | 4   | brown       | 171 | 82  | 54  |
+| 5   | 5   | dark-grey   | 95  | 87  | 79  |
+| 6   | 6   | light-grey  | 194 | 195 | 199 |
+| 7   | 7   | white       | 255 | 241 | 232 |
+| 8   | 8   | red         | 255 | 0   | 77  |
+| 9   | 9   | orange      | 255 | 163 | 0   |
+| 10  | a   | yellow      | 255 | 236 | 39  |
+| 11  | b   | green       | 0   | 228 | 54  |
+| 12  | c   | blue        | 41  | 173 | 255 |
+| 13  | d   | lavender    | 131 | 118 | 156 |
+| 14  | e   | pink        | 255 | 119 | 168 |
+| 15  | f   | peach       | 255 | 204 | 170 |
+
+## Memory map + the gfx/map overlap warning
+
+\`\`\`
+0x0000  gfx (spritesheet, sprites 0..127)
+0x1000  shared gfx / map2   <-- sprites 128..255 ALIAS the bottom half of the map
+0x2000  map
+0x3000  gfx flags
+0x3100  music
+0x3200  sfx
+0x4300  user data
+0x5e00  persistent cart data (256 bytes)
+0x5f00  draw state
+0x5f40  hardware state
+0x5f80  gpio pins
+0x6000  screen (8k)
+\`\`\`
+
+**Overlap warning:** sprites 128..255 (\`0x1000\`-\`0x1fff\`) occupy the SAME memory
+as \`__map__\` rows 32..63. Writing a sprite in that range clobbers the map tiles
+there. \`picopilot gfx set\` smart-refuses such a write when real map tiles are at
+risk and nothing authorised the loss (\`--allow-map-overlap\` or \`allowMapOverlap\`
+in \`picopilot.json\`), so you never silently destroy map data you cannot see.
+
+## Most-used API (grouped)
+
+- **Graphics:** \`cls([col])\`, \`spr(n,x,y,[w,h],[fx],[fy])\`, \`sspr(...)\`,
+  \`map(cx,cy,sx,sy,cw,ch,[layer])\`, \`pset/pget\`, \`sget/sset\`,
+  \`print(str,[x,y,[col]])\`, \`rect/rectfill\`, \`circ/circfill\`, \`oval/ovalfill\`,
+  \`line\`, \`pal(c0,c1,[p])\`, \`palt(col,t)\`, \`camera([x,y])\`, \`clip([x,y,w,h])\`,
+  \`color(col)\`, \`fillp(mask)\`, \`tline(...)\`, \`flip()\`.
+- **Map / flags:** \`mget(x,y)\`, \`mset(x,y,v)\`, \`fget(n,[f])\`, \`fset(n,[f],v)\`.
+- **Input:** \`btn([i,[p]])\`, \`btnp([i,[p]])\` (buttons 0..5 = left,right,up,down,O/Z,X).
+- **Audio:** \`sfx(n,[channel,[offset]])\`, \`music([n,[fade,[mask]]])\`.
+- **Math:** \`abs\`, \`flr\` (\`-flr(-x)\` = ceil), \`min\`, \`max\`, \`mid\`, \`rnd(x)\`,
+  \`srand(x)\`, \`sgn\`, \`sqrt\`, \`sin(x)\`/\`cos(x)\` (range 0..1, sin inverted),
+  \`atan2(x,y)\`.
+- **Tables:** \`add\`, \`del\`, \`deli\`, \`count\`, \`all(t)\`, \`foreach(t,f)\`, \`pairs\`, \`ipairs\`.
+- **Memory:** \`peek\`, \`poke\`, \`memcpy\`, \`memset\`, \`cstore\`, \`reload\`.
+- **Cart data:** \`cartdata(id)\`, \`dget(i)\`, \`dset(i,v)\`.
+- **Debug:** \`printh(str)\` (to host stdout, \`picopilot run\` captures it), \`stat(n)\`.
+
+## Gotchas that silently break carts (these differ from normal Lua/math)
+
+These compile and run but behave WRONG. They are the traps models hit most:
+
+- \`sin(t)\`/\`cos(t)\` take TURNS (0..1), NOT radians, and \`sin\` is INVERTED for
+  screen space (+y is down). A full circle is \`t: 0->1\`. Do not multiply by
+  \`2*pi\`; do not re-negate \`sin\`.
+- \`/\` does NOT truncate (\`5/2\`=\`2.5\`). Integer divide is \`\\\` (\`5\\2\`=\`2\`), which
+  floors toward negative infinity (\`-5\\2\`=\`-3\`).
+- \`rnd(x)\` returns a FLOAT in [0,x). Use \`flr(rnd(x))\` for an integer;
+  \`rnd(table)\` returns a random element.
+- Tables are 1-BASED. \`del(t,val)\` removes by VALUE, \`deli(t,i)\` by INDEX.
+  Deleting the current item inside \`foreach\` is safe; inside an ascending
+  \`for i=1,#t\` it ERRORS once the list shrinks (iterate descending, or foreach).
+- Draw state PERSISTS across frames: \`camera\`, \`pal\`, \`palt\`, \`clip\`, \`color\`,
+  \`fillp\` stay set until reset (no-arg form: \`camera()\`, \`pal()\`). Reset before
+  the HUD or offsets/palette swaps leak.
+- Numbers are 16.16 fixed point; overflow WRAPS at ~32767. Drawing coords are
+  floored to integer pixels (keep true position as a float, let draw floor it).
+- Variables are GLOBAL unless \`local\`. The \`x = cond and a or b\` ternary returns
+  \`b\` when \`a\` is falsy (\`false\`/\`nil\`); use an explicit \`if\` then.
+
+(The \`picopilot-code\` skill expands these, and carries per-genre code references:
+platformer / puzzle-grid / twin-stick-arcade / top-down-adventure and more.)
+
+## Token discipline (stay under 8192)
+
+Models blow the budget by writing verbose Lua. Prefer PICO-8 shorthands:
+
+- \`?\` for \`print\`.
+- inline if: \`if(c) x=1\`.
+- compound assignment: \`+=\`, \`-=\`, \`*=\`, \`/=\`.
+- \`\\\` for integer divide.
+- reuse locals; avoid needless globals.
+
+Run \`picopilot tokens\` each iteration to see the count and where it goes; when
+over budget, \`picopilot minify\` (safe-only) reclaims tokens without changing
+behaviour.
+`;
+}
+
+/**
+ * One scaffolded file: its cart-relative name and its exact bytes. `init`
+ * iterates these, so adding a file is a one-line change here and the tests
+ * assert against this list (the "exactly these files" contract).
+ */
+export interface ScaffoldFile {
+	readonly name: string;
+	readonly content: string;
+}
+
+/**
+ * The complete set of files `picopilot init` writes into a fresh cart folder,
+ * in a stable order: the cart, its editable Lua, the agent-context reference,
+ * and the config. Exactly FOUR files (the acceptance contract). `AGENTS.md` is
+ * the cross-agent context filename; Claude Code, Codex, and others read it, so
+ * one portable file beats duplicating identical content into `CLAUDE.md`.
+ */
+export function scaffoldFiles(): ScaffoldFile[] {
+	return [
+		{name: 'main.p8', content: mainP8()},
+		{name: 'main.lua', content: mainLua()},
+		{name: 'AGENTS.md', content: agentsMd()},
+		{name: 'picopilot.json', content: picopilotJson()},
+	];
+}