picopilot 0.1.4 → 0.2.0

package/src/commands/label-cart.ts

@@ -0,0 +1,304 @@
+import {
+	existsSync,
+	mkdtempSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {dirname, isAbsolute, join, resolve} from 'node:path';
+import {Cart, CartParseError} from '../engine/cart/index.js';
+import {labelHexFromPng, LabelError} from '../engine/gfx/index.js';
+import {
+	buildDriveHarness,
+	DriveError,
+	type DriveOptions,
+	type Pico8DriveResult,
+} from '../engine/pico8/index.js';
+import {makeReadInclude} from './cart-includes.js';
+
+/**
+ * The remedy for both label-image errors (`label-wrong-size`,
+ * `label-unsupported-png`): the screenshot `run`/`playtest` already wrote is a
+ * valid label as-is, so point at that rather than at an external image tool.
+ */
+export const LABEL_FIX_CTA = {
+	description:
+		'Pass a picopilot screenshot directly; it is scaled for you (any 128*k square: 128x128, 256x256, 384x384, ...). No image tool needed:',
+	commands: [
+		{
+			command: 'run <cart> --shot-dir shots',
+			description:
+				'Capture a frame (the cart calls extcmd("screen")), then pass shots/<name>.png to --label unchanged.',
+		},
+		{
+			command: 'export <cart> <dest> --label shots/<name>.png',
+			description:
+				'Bake that screenshot in as the label splash (`serve --label` takes it the same way). playtest screenshots work too.',
+		},
+	],
+};
+
+/** Where the exported cart's `__label__` came from. */
+export type LabelSource = 'cart' | 'image' | 'frame' | 'none';
+
+/** A cart ready to hand to PICO-8's export, plus how to tidy up after it. */
+export interface LabeledCart {
+	readonly ok: true;
+	/** The cart to export: the original, or a labeled throwaway copy. */
+	readonly cartPath: string;
+	/**
+	 * Where the label comes from: the cart's own (`cart`), `--label` (`image`),
+	 * `--label-frame` (`frame`), or nowhere (`none`, the cart stays labelless).
+	 */
+	readonly labelSource: LabelSource;
+	/** Removes the throwaway copy (if one was made). Best-effort, idempotent. */
+	readonly cleanup: () => void;
+}
+
+/** A label-preparation failure, shaped for incur's `error({...})`. */
+export interface LabelCartFailure {
+	readonly ok: false;
+	readonly code: string;
+	readonly message: string;
+	readonly cta?: {
+		description: string;
+		commands: {command: string; description: string}[];
+	};
+}
+
+/** The label flags `export` and `serve` share. */
+export interface LabelOptions {
+	/** `--label <png>`: an image (a run/playtest screenshot as-is, or 128x128). */
+	readonly label?: string;
+	/** `--label-frame <n>`: capture frame `n` of the running cart, no input. */
+	readonly labelFrame?: number;
+	/** The backstop for the `--label-frame` capture run. */
+	readonly backstopMs: number;
+}
+
+/** The base filename the `--label-frame` capture names its screenshot. */
+const LABEL_FRAME_BASENAME = 'label';
+
+/**
+ * The `--label` / `--label-frame` step shared by `export` and `serve` (ADR-0013,
+ * ADR-0015, ADR-0016): give a labelless cart a `__label__` (the export splash)
+ * without an interactive F7 capture.
+ *
+ *  - `--label <png>`: decode an image (a `run`/`playtest` screenshot as-is, any
+ *    square integer multiple of 128x128, or any 128x128 PNG).
+ *  - `--label-frame <n>`: RUN the cart headlessly through the playtest drive
+ *    harness (ADR-0011) with NO input, advance `n` frames, screenshot that frame,
+ *    and decode it. Needs PICO-8 (`drive`); an arbitrary cart does not have to
+ *    cooperate, since the harness owns its frame loop.
+ *
+ * The two flags are mutually exclusive (`label-flags-conflict`). The user's cart
+ * is NEVER mutated: a labeled copy is written NEXT TO it (same dir, so
+ * `#include main.lua` still resolves) and the caller exports that, then calls
+ * `cleanup()`. A cart that ALREADY has a label wins (the flags are a fallback,
+ * not an override): it is returned untouched and nothing is run.
+ *
+ * @param drive the adapter's `drive`, only called for `--label-frame`.
+ */
+export async function prepareLabeledCart(
+	cartPath: string,
+	options: LabelOptions,
+	drive: (options: DriveOptions) => Promise<Pico8DriveResult>,
+): Promise<LabeledCart | LabelCartFailure> {
+	const keep = (labelSource: LabelSource): LabeledCart => ({
+		ok: true,
+		cartPath,
+		labelSource,
+		cleanup: () => {},
+	});
+
+	if (options.label !== undefined && options.labelFrame !== undefined) {
+		return {
+			ok: false,
+			code: 'label-flags-conflict',
+			message:
+				'pass either --label <png> (an image) or --label-frame <n> (capture a frame of the running cart), not both',
+		};
+	}
+
+	// With no label flag the cart is only read to REPORT `labelSource`; anything
+	// odd about it (unreadable, unparseable) is left for PICO-8 to judge, exactly
+	// as before the label flags existed.
+	const noFlag =
+		options.label === undefined && options.labelFrame === undefined;
+	let cart: Cart;
+	try {
+		cart = Cart.parse(readFileSync(cartPath, 'utf8'));
+	} catch (e) {
+		if (noFlag) return keep('none');
+		if (e instanceof CartParseError) {
+			return {
+				ok: false,
+				code: `cart-${e.code}`,
+				message: `could not parse the cart to inject a label: ${e.message}`,
+			};
+		}
+		throw e;
+	}
+
+	const existingLabel = cart.getSection('label');
+	if (existingLabel !== undefined && existingLabel.trim() !== '') {
+		return keep('cart');
+	}
+
+	let png: Uint8Array;
+	let labelSource: LabelSource;
+	if (options.label !== undefined) {
+		const labelPath = isAbsolute(options.label)
+			? options.label
+			: resolve(process.cwd(), options.label);
+		if (!existsSync(labelPath)) {
+			return {
+				ok: false,
+				code: 'label-not-found',
+				message: `no label image at ${labelPath}`,
+			};
+		}
+		png = readFileSync(labelPath);
+		labelSource = 'image';
+	} else if (options.labelFrame !== undefined) {
+		const captured = await captureFrame(
+			cartPath,
+			options.labelFrame,
+			options.backstopMs,
+			drive,
+		);
+		if (!captured.ok) return captured;
+		png = captured.png;
+		labelSource = 'frame';
+	} else {
+		return keep('none');
+	}
+
+	let hex: string;
+	try {
+		hex = labelHexFromPng(png);
+	} catch (e) {
+		if (e instanceof LabelError) {
+			return {
+				ok: false,
+				code: `label-${e.code}`,
+				message: e.message,
+				cta: LABEL_FIX_CTA,
+			};
+		}
+		throw e;
+	}
+
+	cart.setSection('label', hex);
+	const copy = join(
+		dirname(cartPath),
+		`.picopilot-export-${process.pid}-${Date.now()}.p8`,
+	);
+	writeFileSync(copy, cart.serialize());
+	return {
+		ok: true,
+		cartPath: copy,
+		labelSource,
+		cleanup: () => {
+			try {
+				rmSync(copy, {force: true});
+			} catch {
+				// A leftover dotfile is not fatal.
+			}
+		},
+	};
+}
+
+/**
+ * Runs the cart through the playtest drive harness with NO input for `frame + 1`
+ * frames, screenshotting after frame `frame` (0 = the first drawn frame), and
+ * returns that PNG. The driven cart and PICO-8's screenshot dir live in a temp
+ * dir that is removed before returning.
+ */
+async function captureFrame(
+	cartPath: string,
+	frame: number,
+	backstopMs: number,
+	drive: (options: DriveOptions) => Promise<Pico8DriveResult>,
+): Promise<{ok: true; png: Uint8Array} | LabelCartFailure> {
+	let harness;
+	try {
+		harness = buildDriveHarness(readFileSync(cartPath, 'utf8'), {
+			presses: [],
+			frames: frame + 1,
+			shotFrames: [frame],
+			shotBasename: LABEL_FRAME_BASENAME,
+			readInclude: makeReadInclude(cartPath),
+		});
+	} catch (e) {
+		if (e instanceof DriveError) {
+			return {ok: false, code: e.code, message: e.message};
+		}
+		throw e;
+	}
+
+	const shotDir = mkdtempSync(join(tmpdir(), 'picopilot-label-frame-'));
+	try {
+		const drivenCart = join(shotDir, 'driven.p8');
+		writeFileSync(drivenCart, harness.cartText);
+		const result = await drive({
+			cartPath: drivenCart,
+			shotDir,
+			blocks: harness.blocks,
+			backstopMs,
+		});
+		if (!result.ok) {
+			return {
+				ok: false,
+				code: result.reason,
+				message: `PICO-8 is not installed, so --label-frame cannot capture a frame. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+			};
+		}
+		const shot = result.value.screenshots[0];
+		if (shot === undefined) {
+			const {exitReason} = result.value;
+			const tail = result.value.printh.trim().split('\n').slice(-5).join('\n');
+			const commands = [
+				{
+					command: 'verify',
+					description: 'Run the static gate (tokens + lint + integrity).',
+				},
+				{
+					command: 'playtest start <cart>',
+					description:
+						'Reproduce the SAME no-input frame to look at it: start a paused session (nothing held), then step and shoot.',
+				},
+				{
+					command: `playtest step <id> --frames ${frame + 1}`,
+					description: `Advance to frame ${frame}, as --label-frame ${frame} does.`,
+				},
+				{
+					command: 'playtest shot <id>',
+					description:
+						'Screenshot it; if it looks right, pass that PNG with --label <png> (then `playtest stop <id>`).',
+				},
+			];
+			if (exitReason === 'timeout') {
+				commands.push({
+					command: `export <cart> --label-frame ${frame} --backstop-ms <more>`,
+					description:
+						'The capture hit the backstop (it runs about one frame per PICO-8 tick): allow more time, or pick an earlier frame.',
+				});
+			}
+			return {
+				ok: false,
+				code: 'label-frame-not-captured',
+				message: `the cart produced no frame ${frame} screenshot (exit: ${exitReason}).${tail === '' ? '' : ` Last output:\n${tail}`}`,
+				cta: {
+					description:
+						'The cart did not reach that frame. Check it boots, or look at the frame first:',
+					commands,
+				},
+			};
+		}
+		return {ok: true, png: readFileSync(shot)};
+	} finally {
+		rmSync(shotDir, {recursive: true, force: true});
+	}
+}

package/src/commands/lint.test.ts

@@ -34,6 +34,12 @@ afterEach(() => {
 /** A stub adapter whose `lint` returns whatever the test wires; `count`/`minify` unused here. */
 function stubAdapter(result: ShrinkoResult<LintReport>): ShrinkoAdapter {
 	return {
+		async exportSpritesheet() {
+			throw new Error('exportSpritesheet not used');
+		},
+		async importSpritesheet() {
+			throw new Error('importSpritesheet not used');
+		},
 		async count() {
 			throw new Error('not used');
 		},

package/src/commands/lint.ts

@@ -1,16 +1,17 @@
 import {existsSync} from 'node:fs';
 import {isAbsolute, resolve} from 'node:path';
 import {type Cli, z} from 'incur';
+import {type ShrinkoAdapter} from '../engine/shrinko/index.js';
 import {
-	type ShrinkoAdapter,
-	ShellShrinkoAdapter,
-} from '../engine/shrinko/index.js';
+	createShellShrinkoFactory,
+	type ShrinkoAdapterFactory,
+} from './shrinko-env.js';
 
 /** See {@link import('./tokens.js').ShrinkoAdapterFactory}: lint reuses the same seam. */
-export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+export type {ShrinkoAdapterFactory} from './shrinko-env.js';
 
-const defaultAdapterFactory: ShrinkoAdapterFactory = (env) =>
-	new ShellShrinkoAdapter({env});
+const defaultAdapterFactory: ShrinkoAdapterFactory =
+	createShellShrinkoFactory();
 
 /**
  * Registers `picopilot lint` (US #4): surface PICO-8-specific issues (undefined

package/src/commands/minify.test.ts

@@ -41,6 +41,12 @@ function stubAdapter(
 	seen?: {outPath?: string},
 ): ShrinkoAdapter {
 	return {
+		async exportSpritesheet() {
+			throw new Error('exportSpritesheet not used');
+		},
+		async importSpritesheet() {
+			throw new Error('importSpritesheet not used');
+		},
 		async count() {
 			throw new Error('not used');
 		},

package/src/commands/minify.ts

@@ -1,16 +1,17 @@
 import {existsSync} from 'node:fs';
 import {dirname, isAbsolute, join, resolve} from 'node:path';
 import {type Cli, z} from 'incur';
+import {type ShrinkoAdapter} from '../engine/shrinko/index.js';
 import {
-	type ShrinkoAdapter,
-	ShellShrinkoAdapter,
-} from '../engine/shrinko/index.js';
+	createShellShrinkoFactory,
+	type ShrinkoAdapterFactory,
+} from './shrinko-env.js';
 
 /** See {@link import('./tokens.js').ShrinkoAdapterFactory}: minify reuses the same seam. */
-export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+export type {ShrinkoAdapterFactory} from './shrinko-env.js';
 
-const defaultAdapterFactory: ShrinkoAdapterFactory = (env) =>
-	new ShellShrinkoAdapter({env});
+const defaultAdapterFactory: ShrinkoAdapterFactory =
+	createShellShrinkoFactory();
 
 /**
  * Derives the default output path `<name>.min.p8` next to the source cart:

package/src/commands/pico8-env.ts

@@ -0,0 +1,124 @@
+import {z} from 'incur';
+import {
+	DEFAULT_DISPLAY_MODE,
+	type DisplayMode,
+	isDisplayMode,
+	type Pico8Adapter,
+	pico8ChildEnv,
+	ShellPico8Adapter,
+	type SpawnRunner,
+	type VirtualDisplayDeps,
+} from '../engine/pico8/index.js';
+
+/**
+ * The env schema every PICO-8-gated command declares. These are the values
+ * picopilot itself RESOLVES (incur reads them from its env source, which tests
+ * override); they are NOT the whole child environment. The child gets the
+ * parent environment with these overlaid ({@link pico8ChildEnv}), so PICO-8
+ * still sees DISPLAY, HOME, XDG_RUNTIME_DIR, SDL_* and the rest.
+ */
+export const PICO8_ENV = z.object({
+	PICO8_PATH: z
+		.string()
+		.optional()
+		.describe('Explicit path to the PICO-8 binary (else `pico8` on PATH).'),
+	PATH: z.string().optional().describe('Used to locate `pico8`.'),
+});
+
+/** What a command knows beyond the env when it builds an adapter. */
+export interface Pico8AdapterContext {
+	/** The resolved display mode for `-run` sessions (ADR-0017). */
+	readonly display: DisplayMode;
+}
+
+/**
+ * Injects the PICO-8 adapter a command uses. A test passes a stub to drive the
+ * sentinel/backstop/absent paths without the paid binary; the default is
+ * {@link createShellAdapterFactory}.
+ */
+export type Pico8AdapterFactory = (
+	env: NodeJS.ProcessEnv,
+	context?: Pico8AdapterContext,
+) => Pico8Adapter;
+
+/** Dependencies for {@link createShellAdapterFactory}, injectable for tests. */
+export interface ShellAdapterFactoryDeps {
+	/** The parent environment PICO-8 inherits (defaults to `process.env`). */
+	readonly parentEnv?: NodeJS.ProcessEnv;
+	/** The PICO-8 spawn seam (defaults to the real spawn). */
+	readonly spawn?: SpawnRunner;
+	/** The virtual-display seam (Xvfb lookup + spawn). */
+	readonly virtualDisplay?: VirtualDisplayDeps;
+}
+
+/**
+ * The default adapter factory: the shell adapter over the user's PICO-8, with
+ * the child env = parent env + the command's resolved values, and the display
+ * mode from the context.
+ */
+export function createShellAdapterFactory(
+	deps: ShellAdapterFactoryDeps = {},
+): Pico8AdapterFactory {
+	return (env, context) =>
+		new ShellPico8Adapter({
+			env: pico8ChildEnv(
+				env as Record<string, string | undefined>,
+				deps.parentEnv ?? process.env,
+			),
+			spawn: deps.spawn,
+			display: context?.display ?? DEFAULT_DISPLAY_MODE,
+			virtualDisplay: deps.virtualDisplay,
+		});
+}
+
+/**
+ * The display mode a command handler sees. The root middleware in `createCli`
+ * resolves it (flag > env > config > default) into the `display` var; a command
+ * mounted on a bare CLI (some tests) has no var and gets the default.
+ */
+export function displayModeOf(vars: unknown): DisplayMode {
+	const value =
+		vars !== null && typeof vars === 'object'
+			? (vars as {display?: unknown}).display
+			: undefined;
+	return isDisplayMode(value) ? value : DEFAULT_DISPLAY_MODE;
+}
+
+/**
+ * The `error(...)` payload for a `display-unavailable` result (ADR-0017): the
+ * session needs a display, there is none, and no Xvfb is installed to provide a
+ * virtual one. The message and CTA name the fix, so the agent never has to
+ * discover it by a silent timeout.
+ */
+export function displayUnavailableError(
+	what: string,
+	result: {detail: string; remedy: string},
+) {
+	return {
+		code: 'display-unavailable' as const,
+		message: `${what} needs a display (a real audio+video -run session): ${result.detail}. Remedy: ${result.remedy}.`,
+		exitCode: 1,
+		cta: {
+			description: `No display and no Xvfb on this machine. Fix: ${result.remedy}. Then re-run; picopilot starts a private virtual display by itself (--display auto). Check what this machine can do:`,
+			commands: [
+				{
+					command: 'doctor',
+					description:
+						'Report PICO-8, shrinko8 and display capabilities, and which commands are available here.',
+				},
+			],
+		},
+	};
+}
+
+/** The `error(...)` payload for a `pico8-not-found` result (the exact remedy + needs). */
+export function pico8NotFoundError(result: {
+	remedy: string;
+	needs: readonly string[];
+}) {
+	return {
+		code: 'pico8-not-found' as const,
+		message: `PICO-8 is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+		exitCode: 1,
+	};
+}

package/src/commands/playtest.test.ts

@@ -58,6 +58,9 @@ function stubAdapter(
 	seen?: {options?: DriveOptions},
 ): Pico8Adapter {
 	return {
+		async export() {
+			throw new Error('export not used');
+		},
 		async run() {
 			throw new Error('run not used by playtest');
 		},

package/src/commands/playtest.ts

@@ -6,7 +6,7 @@ import {
 	writeFileSync,
 } from 'node:fs';
 import {tmpdir} from 'node:os';
-import {dirname, isAbsolute, join, resolve} from 'node:path';
+import {isAbsolute, join, resolve} from 'node:path';
 import {type Cli, Cli as IncurCli, z} from 'incur';
 import {
 	buildDriveHarness,
@@ -22,12 +22,17 @@ import {
 	SessionRegistry,
 	sessionExists,
 	SHOT_BASENAME,
-	ShellPico8Adapter,
 	spawnSessionDaemon,
 	type SessionRequest,
 	type SessionResponse,
 	type SessionResponseValue,
 } from '../engine/pico8/index.js';
+import {
+	createShellAdapterFactory,
+	PICO8_ENV,
+	type Pico8AdapterFactory,
+} from './pico8-env.js';
+import {makeReadInclude} from './cart-includes.js';
 
 /**
  * Injects the PICO-8 adapter `playtest` uses (defaults to the shell adapter over
@@ -35,10 +40,9 @@ import {
  * stub to drive the drive-orchestration + the absent path WITHOUT the paid
  * binary, and to isolate the child `env` (its `PICO8_PATH`/`PATH`).
  */
-export type Pico8AdapterFactory = (env: NodeJS.ProcessEnv) => Pico8Adapter;
+export type {Pico8AdapterFactory} from './pico8-env.js';
 
-const defaultAdapterFactory: Pico8AdapterFactory = (env) =>
-	new ShellPico8Adapter({env});
+const defaultAdapterFactory: Pico8AdapterFactory = createShellAdapterFactory();
 
 /**
  * The default backstop: kill a driven cart that never signals/exits after this
@@ -57,28 +61,6 @@ function resolvePath(p: string): string {
 	return isAbsolute(p) ? p : resolve(process.cwd(), p);
 }
 
-/**
- * A `#include` resolver for the drive-transform, bound to the SOURCE cart's dir:
- * picopilot's standard scaffold is `main.p8` = `#include main.lua`, and the
- * driven cart runs from a throwaway temp dir where `main.lua` is absent, so the
- * transform inlines includes to be self-contained. Reads the included file
- * relative to the cart (absolute paths honoured); returns `undefined` if it
- * cannot be read (the directive is then left verbatim).
- */
-function makeReadInclude(cartPath: string): (p: string) => string | undefined {
-	const base = dirname(cartPath);
-	return (includePath) => {
-		const full = isAbsolute(includePath)
-			? includePath
-			: join(base, includePath);
-		try {
-			return readFileSync(full, 'utf8');
-		} catch {
-			return undefined;
-		}
-	};
-}
-
 /** A small sleep for the `start` readiness poll. */
 function sleep(ms: number): Promise<void> {
 	return new Promise((r) => setTimeout(r, ms));
@@ -240,13 +222,7 @@ function buildPlaytestGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 }
 
 /** The env schema the whole `playtest` group shares (locates the binary, isolated). */
-const PLAYTEST_ENV = z.object({
-	PICO8_PATH: z
-		.string()
-		.optional()
-		.describe('Explicit path to the PICO-8 binary (else `pico8` on PATH).'),
-	PATH: z.string().optional().describe('Used to locate `pico8`.'),
-});
+const PLAYTEST_ENV = PICO8_ENV;
 
 /**
  * The ONE-SHOT root handler (unchanged behaviour from the one-shot task): build