picopilot 0.0.0 → 0.1.0

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,236 @@
+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 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()},
+	];
+}

package/src/engine/shrinko/adapter.ts

@@ -0,0 +1,241 @@
+/**
+ * The shrinko adapter SEAM: a typed interface every shrinko-backed command
+ * (`tokens`, and later `lint`, `minify`, `gfx import/export`, `verify`) talks
+ * to, plus the discriminated result shape they all return.
+ *
+ * The seam exists so the command layer never knows HOW shrinko is reached. The
+ * v1 implementation shells out to a user-installed Python `shrinko8` (see
+ * `shell.ts` and ADR-0001); a future native-TS implementation can implement the
+ * SAME {@link ShrinkoAdapter} interface and drop in without touching a single
+ * command. The command-facing contract is entirely in this file.
+ *
+ * The two-tier capability contract (ADR-0002) lives in the RESULT type: every
+ * adapter method returns a {@link ShrinkoResult}, a discriminated union of a
+ * success value OR the structured {@link ShrinkoNotFound} failure. Absent
+ * shrinko is therefore NOT an exception a command must try/catch, it is a
+ * first-class `{ok:false, reason:'shrinko-not-found', ...}` value a command maps
+ * onto incur's error envelope with a nonzero exit. Never a crash, never a hollow
+ * success.
+ */
+
+/** The PyPI package name in the remedy: `uv pip install shrinko` (NOT `shrinko8`). */
+export const SHRINKO_REMEDY = 'uv pip install shrinko' as const;
+
+/** What shrinko needs to run: Python 3.8+ (the module is `shrinko8`). */
+export const SHRINKO_NEEDS = ['python>=3.8'] as const;
+
+/**
+ * The structured "shrinko is not installed" failure (ADR-0002). Its shape is
+ * fixed by the prd's two-tier contract (US #17): `ok:false`, a machine-readable
+ * `reason`, the EXACT `remedy` string, and the `needs` list. A command turns
+ * this into an incur `error({ code: reason, ... })` with a nonzero exit.
+ */
+export interface ShrinkoNotFound {
+	readonly ok: false;
+	readonly reason: 'shrinko-not-found';
+	/** The EXACT remedy: `uv pip install shrinko` (package is `shrinko`, module `shrinko8`). */
+	readonly remedy: typeof SHRINKO_REMEDY;
+	/** Prerequisites the remedy assumes are present. */
+	readonly needs: readonly string[];
+}
+
+/** A successful adapter call carrying the parsed value. */
+export interface ShrinkoOk<T> {
+	readonly ok: true;
+	readonly value: T;
+}
+
+/**
+ * The result every {@link ShrinkoAdapter} method returns: either a parsed value
+ * or the structured {@link ShrinkoNotFound}. Absence is a value, not a throw, so
+ * the two-tier contract is total and type-checked at every call site.
+ */
+export type ShrinkoResult<T> = ShrinkoOk<T> | ShrinkoNotFound;
+
+/**
+ * The parsed `--count` report (US #3). `tokens`/`chars`/`compressed` are the
+ * raw counts shrinko prints; `pct` fields are shrinko's own reported
+ * percentages (its `--count` prints `tokens: 8053 98%`, i.e. against PICO-8's
+ * limits), preserved verbatim so a command can show them without recomputing.
+ * `compressed`/`compressedPct` are optional because shrinko omits the
+ * compressed line for input formats where it does not apply.
+ */
+export interface CountReport {
+	readonly tokens: number;
+	readonly tokensPct: number;
+	readonly chars: number;
+	readonly charsPct: number;
+	readonly compressed: number | undefined;
+	readonly compressedPct: number | undefined;
+}
+
+/**
+ * The shrinko capability seam. One method per shrinko-backed operation; only
+ * `count` exists in this task, the rest (lint, minify, convert) land with their
+ * commands and extend THIS interface rather than forking a new one.
+ *
+ * Every method is async (the shell-out is async) and returns a
+ * {@link ShrinkoResult}, so absence is handled uniformly at each seam.
+ */
+export interface ShrinkoAdapter {
+	/**
+	 * Runs shrinko's `--count` on the cart at `cartPath` and parses the
+	 * `tokens/chars/compressed` report. Returns {@link ShrinkoNotFound} when
+	 * shrinko is not installed.
+	 */
+	count(cartPath: string): Promise<ShrinkoResult<CountReport>>;
+
+	/**
+	 * Runs shrinko's `--lint` on the cart at `cartPath` and parses the warnings
+	 * (undefined globals, unused/duplicate locals, etc.) into structured
+	 * {@link LintFinding}s. Lint warnings are DATA, not a failure: the report is
+	 * returned with `findings` (possibly empty), not a throw. Returns
+	 * {@link ShrinkoNotFound} when shrinko is not installed.
+	 */
+	lint(cartPath: string): Promise<ShrinkoResult<LintReport>>;
+
+	/**
+	 * Runs shrinko's SAFE minification on `cartPath` and writes the result to
+	 * `outPath` (a SEPARATE artifact; the source is never touched, see ADR-0007).
+	 * Returns the before/after token counts. Returns {@link ShrinkoNotFound} when
+	 * shrinko is not installed.
+	 */
+	minify(
+		cartPath: string,
+		outPath: string,
+	): Promise<ShrinkoResult<MinifyReport>>;
+
+	/**
+	 * Exports the cart's spritesheet as a 128x128 PNG to `pngPath` (a raw
+	 * round-trip image for external tools, distinct from `gfx render`'s upscaled
+	 * JUDGE image). Returns {@link ShrinkoNotFound} when shrinko is not installed.
+	 */
+	exportSpritesheet(
+		cartPath: string,
+		pngPath: string,
+	): Promise<ShrinkoResult<void>>;
+
+	/**
+	 * Imports a 128x128 spritesheet PNG into `srcCartPath`'s `__gfx__`, MERGING
+	 * (only the gfx section is replaced; code/map/sfx/music are preserved) and
+	 * writing the result to `outCartPath`. Returns {@link ShrinkoNotFound} when
+	 * shrinko is not installed.
+	 */
+	importSpritesheet(
+		srcCartPath: string,
+		pngPath: string,
+		outCartPath: string,
+	): Promise<ShrinkoResult<void>>;
+}
+
+/** One shrinko lint warning, parsed from a `file:line:col: message` line. */
+export interface LintFinding {
+	readonly line: number;
+	readonly col: number;
+	readonly message: string;
+}
+
+/** The parsed `--lint` result: every warning shrinko reported (empty when clean). */
+export interface LintReport {
+	readonly findings: readonly LintFinding[];
+}
+
+/** The parsed `minify` result: token counts before and after (ADR-0007's delta report). */
+export interface MinifyReport {
+	/** Tokens in the source cart. */
+	readonly beforeTokens: number;
+	/** Tokens in the minified artifact. */
+	readonly afterTokens: number;
+	/** Absolute path of the written minified cart. */
+	readonly outPath: string;
+}
+
+/** The frozen {@link ShrinkoNotFound} value, so every call site returns the same shape. */
+export function shrinkoNotFound(): ShrinkoNotFound {
+	return {
+		ok: false,
+		reason: 'shrinko-not-found',
+		remedy: SHRINKO_REMEDY,
+		needs: [...SHRINKO_NEEDS],
+	};
+}
+
+/**
+ * Parses shrinko's `--count` output into a {@link CountReport}.
+ *
+ * shrinko prints lines like:
+ *
+ * ```
+ * tokens: 8053 98%
+ * chars: 30320 46%
+ * compressed: 12176 77%
+ * ```
+ *
+ * (the compressed line is absent for some input formats). Parsing is
+ * line-oriented and tolerant of surrounding output/whitespace: it scans for the
+ * `tokens:`/`chars:`/`compressed:` labels anywhere in the combined stdout+stderr
+ * and pulls the count and percentage off each. Throws if the required
+ * `tokens:`/`chars:` lines are missing, so a shrinko that ran but produced
+ * unparseable output surfaces as a real error rather than a silent zero.
+ */
+export function parseCount(output: string): CountReport {
+	const line = (label: string): {n: number; pct: number} | undefined => {
+		// `label: <count> <pct>%` (count and percent may be separated by any run
+		// of spaces; the `%` is optional-tolerant but shrinko always prints it).
+		const re = new RegExp(`^\\s*${label}:\\s*(\\d+)\\s+(\\d+)\\s*%`, 'm');
+		const m = re.exec(output);
+		if (m === null) return undefined;
+		return {n: Number(m[1]), pct: Number(m[2])};
+	};
+
+	const tokens = line('tokens');
+	const chars = line('chars');
+	if (tokens === undefined || chars === undefined) {
+		throw new ShrinkoParseError(
+			`could not parse shrinko --count output (missing tokens/chars lines):\n${output}`,
+		);
+	}
+	const compressed = line('compressed');
+
+	return {
+		tokens: tokens.n,
+		tokensPct: tokens.pct,
+		chars: chars.n,
+		charsPct: chars.pct,
+		compressed: compressed?.n,
+		compressedPct: compressed?.pct,
+	};
+}
+
+/**
+ * Parses shrinko's `--lint` output into {@link LintFinding}s. shrinko prints a
+ * `Lint warnings:` header then one `file:line:col: message` per warning; a clean
+ * cart prints nothing. Parsing scans the combined stdout+stderr for the
+ * `:line:col: message` shape (tolerant of the filename prefix, which we drop),
+ * so an empty result is a CLEAN cart, not an error. Unlike parseCount this never
+ * throws: no recognisable lines simply means zero findings.
+ */
+export function parseLint(output: string): LintReport {
+	const findings: LintFinding[] = [];
+	// Match `<anything>:<line>:<col>: <message>` (the filename may itself contain
+	// colons/paths, so anchor on the two trailing numeric groups before the msg).
+	const re = /:(\d+):(\d+):\s*(.+?)\s*$/gm;
+	for (const m of output.matchAll(re)) {
+		findings.push({
+			line: Number(m[1]),
+			col: Number(m[2]),
+			message: m[3] ?? '',
+		});
+	}
+	return {findings};
+}
+
+/**
+ * Thrown when shrinko RAN but its output could not be parsed (a shrinko
+ * version/format drift), distinct from shrinko being ABSENT (which is the
+ * structured {@link ShrinkoNotFound} value, not a throw). Commands surface this
+ * as a `shrinko-failed` error, separate from `shrinko-not-found`.
+ */
+export class ShrinkoParseError extends Error {
+	override readonly name = 'ShrinkoParseError';
+}

package/src/engine/shrinko/fixtures/count-no-compressed.txt

@@ -0,0 +1,2 @@
+tokens: 300 3%
+chars: 1200 1%