picopilot 0.1.4 → 0.2.0

package/src/commands/run.test.ts

@@ -1,5 +1,11 @@
 import {execFileSync} from 'node:child_process';
-import {existsSync, mkdtempSync, readdirSync, writeFileSync} from 'node:fs';
+import {
+	existsSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs';
 import {homedir, tmpdir} from 'node:os';
 import {join} from 'node:path';
 import {Cli} from 'incur';
@@ -11,7 +17,8 @@ import type {
 	RecordOptions,
 	RunOptions,
 } from '../engine/pico8/index.js';
-import {pico8NotFound} from '../engine/pico8/index.js';
+import {displayUnavailable, pico8NotFound} from '../engine/pico8/index.js';
+import {createShellAdapterFactory} from './pico8-env.js';
 import {type Pico8AdapterFactory, registerRun} from './run.js';
 
 /** A trivial valid cart the command reads (existence + a path to hand the adapter). */
@@ -47,6 +54,12 @@ function stubAdapter(
 	recordResult?: Pico8RecordResult,
 ): Pico8Adapter {
 	return {
+		async drive() {
+			throw new Error('drive not used');
+		},
+		async export() {
+			throw new Error('export not used');
+		},
 		async run(options) {
 			if (seen !== undefined) seen.options = options;
 			return result;
@@ -262,3 +275,104 @@ describe('picopilot run: cart-not-found (picopilot-side error, distinct from pic
 		expect(snap()).toEqual(before); // same entries: an absent dir stays absent, a present one unchanged
 	});
 });
+
+describe('picopilot run --record-audio: an #include cart produces a loadable harness', () => {
+	it('inlines the cart includes into the harness it hands the record pass', async () => {
+		writeFileSync(
+			cartPath,
+			'pico-8 cartridge // http://www.pico-8.com\nversion 42\n__lua__\n#include main.lua\n',
+		);
+		writeFileSync(
+			join(dir, 'main.lua'),
+			'function _update() hello_from_main=1 end\n',
+		);
+		const seen: {recordOptions?: RecordOptions} = {};
+		const {exitCode} = await runRun(
+			() => stubAdapter(ranWith('sentinel'), seen),
+			['run', cartPath, '--record-audio', '--json'],
+		);
+		expect(exitCode).toBe(0);
+		const harness = readFileSync(seen.recordOptions!.cartPath, 'utf8');
+		expect(harness).not.toMatch(/#include/);
+		expect(harness).toContain('hello_from_main=1');
+	});
+});
+
+describe('picopilot run --record-audio: failures are explained, never silent', () => {
+	it('surfaces noAudioReason + pico8LogTail when no WAV was captured', async () => {
+		const {stdout} = await runRun(
+			() =>
+				stubAdapter(ranWith('sentinel'), undefined, {
+					ok: true,
+					value: {
+						wavPath: undefined,
+						printh: '',
+						exitReason: 'timeout',
+						noWavReason: 'the backstop fired before the done-sentinel',
+						pico8LogTail: 'syntax error',
+					},
+				}),
+			['run', cartPath, '--record-audio', '--json'],
+		);
+		const out = JSON.parse(stdout);
+		expect(out.audioCaptured).toBe(false);
+		expect(out.noAudioReason).toMatch(/backstop/);
+		expect(out.pico8LogTail).toBe('syntax error');
+	});
+
+	it('display-unavailable is a structured error whose CTA names the fix', async () => {
+		const {stdout, exitCode} = await runRun(
+			() =>
+				stubAdapter(
+					ranWith('sentinel'),
+					undefined,
+					displayUnavailable('no DISPLAY and no Xvfb'),
+				),
+			['run', cartPath, '--record-audio', '--json', '--full-output'],
+		);
+		expect(exitCode).not.toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.error.code).toBe('display-unavailable');
+		expect(out.error.message).toMatch(/Xvfb/);
+		expect(JSON.stringify(out.meta?.cta ?? out.cta)).toMatch(/install Xvfb/);
+	});
+});
+
+describe('picopilot run: the PICO-8 child inherits the parent environment', () => {
+	it('DISPLAY, HOME and XDG_RUNTIME_DIR from the parent reach the spawn; PICO8_PATH comes from the resolved env', async () => {
+		let spawnedEnv: NodeJS.ProcessEnv | undefined;
+		const factory = createShellAdapterFactory({
+			parentEnv: {
+				DISPLAY: ':5',
+				HOME: '/home/agent',
+				XDG_RUNTIME_DIR: '/run/user/1000',
+				SDL_AUDIODRIVER: 'pulseaudio',
+				PICO8_PATH: '/parent/pico8',
+			},
+			spawn: (_file, _args, env) => {
+				spawnedEnv = env;
+				return {
+					onStdout(cb) {
+						setImmediate(() => cb('__PICOPILOT_DONE__\n'));
+					},
+					onClose() {},
+					onError() {},
+					kill() {},
+				};
+			},
+		});
+		const {exitCode} = await runRun(factory, ['run', cartPath, '--json'], {
+			PICO8_PATH: '/resolved/pico8',
+			PATH: '/usr/bin',
+		});
+		expect(exitCode).toBe(0);
+		expect(spawnedEnv).toMatchObject({
+			DISPLAY: ':5',
+			HOME: '/home/agent',
+			XDG_RUNTIME_DIR: '/run/user/1000',
+			SDL_AUDIODRIVER: 'pulseaudio',
+			PICO8_PATH: '/resolved/pico8',
+			PATH: '/usr/bin',
+		});
+	});
+});

package/src/commands/run.ts

@@ -12,20 +12,25 @@ import {
 	buildRecordHarness,
 	DONE_SENTINEL,
 	HarnessError,
-	type Pico8Adapter,
-	ShellPico8Adapter,
 } from '../engine/pico8/index.js';
+import {makeReadInclude} from './cart-includes.js';
+import {
+	createShellAdapterFactory,
+	displayModeOf,
+	displayUnavailableError,
+	PICO8_ENV,
+	pico8NotFoundError,
+	type Pico8AdapterFactory,
+} from './pico8-env.js';
 
 /**
  * Injects the PICO-8 adapter `run` uses (defaults to the shell adapter over
  * native `pico8 -x`). Mirrors the shrinko `adapterFactory` seam: a test passes a
- * stub to drive the sentinel/backstop/absent paths without the paid binary, and
- * to isolate the child `env` (its `PICO8_PATH`/`PATH`).
+ * stub to drive the sentinel/backstop/absent paths without the paid binary.
  */
-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 cart that never signals/exits after this many ms. */
 const DEFAULT_BACKSTOP_MS = 15_000;
@@ -95,18 +100,12 @@ export function registerRun(
 				.boolean()
 				.default(false)
 				.describe(
-					"Also capture a WAV of the run's audio alongside the screenshots (ADR-0009). A REAL-TIME recording that needs a real audio+video session (a separate -run pass, NOT the headless screenshot pass), never an offline export.",
+					"Also capture a WAV of the run's audio alongside the screenshots (ADR-0009). A REAL-TIME recording in a separate -run pass (not the headless screenshot pass), never an offline export. Works headless: with no display, picopilot runs that pass on a private virtual display (ADR-0017, --display).",
 				),
 		}),
-		// incur resolves these from the (test-overridable) env source and hands
-		// them to the child, so PICO8_PATH/PATH locate the binary in isolation.
-		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`.'),
-		}),
+		// incur resolves these from the (test-overridable) env source; the child
+		// gets the parent env with them overlaid (DISPLAY, HOME, ... pass through).
+		env: PICO8_ENV,
 		output: z.object({
 			screenshots: z
 				.array(z.string())
@@ -131,6 +130,24 @@ export function registerRun(
 				.describe(
 					'Whether a non-empty WAV was captured (false unless --record-audio ran and produced audio).',
 				),
+			audioDisplay: z
+				.enum(['native', 'Xvfb', 'xvfb-run'])
+				.optional()
+				.describe(
+					'With --record-audio: which display the -run pass used (native, or a private virtual display).',
+				),
+			noAudioReason: z
+				.string()
+				.optional()
+				.describe(
+					'With --record-audio and no WAV: why (backstop fired / PICO-8 exited before the done-sentinel / empty capture).',
+				),
+			pico8LogTail: z
+				.string()
+				.optional()
+				.describe(
+					"With --record-audio and no WAV: the tail of PICO-8's own log.txt (load errors, SDL init failures).",
+				),
 		}),
 		examples: [
 			{description: 'Run main.p8'},
@@ -141,7 +158,7 @@ export function registerRun(
 				options: {shotDir: './shots'},
 			},
 		],
-		async run({args, options, env, error, ok}) {
+		async run({args, options, env, error, ok, var: vars}) {
 			const cartPath = isAbsolute(args.cart)
 				? args.cart
 				: resolve(process.cwd(), args.cart);
@@ -166,7 +183,9 @@ export function registerRun(
 					: mkdtempSync(join(tmpdir(), 'picopilot-run-'));
 			if (!existsSync(shotDir)) mkdirSync(shotDir, {recursive: true});
 
-			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv, {
+				display: displayModeOf(vars),
+			});
 			const result = await adapter.run({
 				cartPath,
 				shotDir,
@@ -194,10 +213,16 @@ export function registerRun(
 			// uses. The WAV lands in the isolated shotDir alongside the screenshots.
 			let wav: string | undefined;
 			let audioCaptured = false;
+			let noAudioReason: string | undefined;
+			let pico8LogTail: string | undefined;
+			let audioDisplay: 'native' | 'Xvfb' | 'xvfb-run' | undefined;
 			if (options.recordAudio) {
 				try {
+					// `#include`s are inlined (resolved against the SOURCE cart's folder):
+					// the harness runs from shotDir, where `main.lua` does not exist.
 					const harness = buildRecordHarness(readFileSync(cartPath, 'utf8'), {
 						sentinel: options.sentinel,
+						readInclude: makeReadInclude(cartPath),
 					});
 					const harnessCart = join(shotDir, 'record-audio-harness.p8');
 					writeFileSync(harnessCart, harness.cartText);
@@ -208,16 +233,26 @@ export function registerRun(
 						sentinel: options.sentinel,
 						backstopMs: options.backstopMs,
 					});
-					if (rec.ok) {
-						wav = rec.value.wavPath;
-						audioCaptured = rec.value.wavPath !== undefined;
+					if (!rec.ok) {
+						// pico8-not-found is impossible here (the screenshot pass above would
+						// have returned it); display-unavailable is the real case: the -run
+						// pass needs a display, there is none, and no Xvfb to make one.
+						return error(
+							rec.reason === 'display-unavailable'
+								? displayUnavailableError('run --record-audio', rec)
+								: pico8NotFoundError(rec),
+						);
 					}
-					// A record-pass pico8-not-found is impossible here: the screenshot
-					// pass above already returned pico8-not-found if PICO-8 were absent.
+					wav = rec.value.wavPath;
+					audioCaptured = rec.value.wavPath !== undefined;
+					noAudioReason = rec.value.noWavReason;
+					pico8LogTail = rec.value.pico8LogTail;
+					audioDisplay = rec.value.display;
 				} catch (e) {
 					if (!(e instanceof HarnessError)) throw e;
 					// A harness-build failure (unparseable cart) leaves audioCaptured false;
 					// the screenshot run's report still stands.
+					noAudioReason = `the record harness could not be built: ${e.message}`;
 				}
 			}
 
@@ -277,6 +312,9 @@ export function registerRun(
 					shotDir,
 					wav,
 					audioCaptured,
+					...(audioDisplay !== undefined ? {audioDisplay} : {}),
+					...(noAudioReason !== undefined ? {noAudioReason} : {}),
+					...(pico8LogTail !== undefined ? {pico8LogTail} : {}),
 				},
 				cta === undefined ? undefined : {cta},
 			);

package/src/commands/serve.test.ts

@@ -1,12 +1,21 @@
 import {execFileSync} from 'node:child_process';
-import {existsSync, mkdtempSync, writeFileSync} from 'node:fs';
+import {
+	existsSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs';
 import {tmpdir} from 'node:os';
 import {join} from 'node:path';
 import {Cli} from 'incur';
 import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {encodePng} from '../engine/gfx/index.js';
 import type {
+	DriveOptions,
 	ExportOptions,
 	Pico8Adapter,
+	Pico8DriveResult,
 	Pico8ExportResult,
 } from '../engine/pico8/index.js';
 import {pico8NotFound} from '../engine/pico8/index.js';
@@ -211,7 +220,12 @@ describe('picopilot serve: failure paths', () => {
 		const lower = stdout.toLowerCase();
 		expect(lower).toContain('picopilot run');
 		expect(lower).toContain('playtest');
-		expect(lower).toContain('export --label');
+		// The remedy must be one that WORKS: `export --label` never writes the label
+		// into the cart, so "export --label, then re-serve" would fail again. serve
+		// takes the label itself.
+		expect(lower).toMatch(/picopilot serve [^`]*--label/);
+		expect(lower).toContain('--label-frame 0');
+		expect(lower).not.toContain('then re-serve');
 		expect(lower).toContain('do not hand-edit main.p8');
 	});
 
@@ -225,3 +239,125 @@ describe('picopilot serve: failure paths', () => {
 		expect(stdout).toContain('no cart at');
 	});
 });
+
+describe('picopilot serve: --label (bake a screenshot in for a labelless cart)', () => {
+	const shotPath = new URL(
+		'../engine/gfx/fixtures/pico8-screenshot-384.png',
+		import.meta.url,
+	);
+
+	it('exports a labeled COPY (the screenshot as-is), leaves the cart untouched, and cleans the copy up', async () => {
+		const labelFile = join(dir, 'shot.png');
+		writeFileSync(labelFile, readFileSync(shotPath));
+		let exportedCart = '';
+		const exportSeen: {options?: ExportOptions} = {};
+		const {exitCode} = await runServe(
+			() => {
+				const inner = stubAdapter('writes-bundle', exportSeen);
+				return {
+					...inner,
+					export: async (o: ExportOptions) => {
+						exportedCart = readFileSync(o.cartPath, 'utf8');
+						return inner.export(o);
+					},
+				} as Pico8Adapter;
+			},
+			fakeServer(),
+			['serve', cartPath, '--label', labelFile, '--json'],
+		);
+		expect(exitCode).toBe(0);
+		expect(exportSeen.options!.cartPath).not.toBe(cartPath);
+		const label = exportedCart.split('__label__\n')[1]!.split('\n');
+		expect(label[10]![10]).toBe('8');
+		expect(label[100]![100]).toBe('c');
+		expect(readFileSync(cartPath, 'utf8')).not.toContain('__label__');
+		// Only the cart and the label image remain: the labeled copy is gone.
+		expect(readdirSync(dir).sort()).toEqual(['main.p8', 'shot.png']);
+	});
+
+	it('removes the labeled copy even when the export step throws', async () => {
+		const labelFile = join(dir, 'shot.png');
+		writeFileSync(labelFile, readFileSync(shotPath));
+		await runServe(
+			() =>
+				({
+					...stubAdapter('writes-bundle'),
+					export: async () => {
+						throw new Error('boom');
+					},
+				}) as Pico8Adapter,
+			fakeServer(),
+			['serve', cartPath, '--label', labelFile, '--json'],
+		).catch(() => undefined);
+		expect(readdirSync(dir).sort()).toEqual(['main.p8', 'shot.png']);
+	});
+
+	it('surfaces a bad label image as label-wrong-size with the screenshot CTA, before exporting', async () => {
+		const labelFile = join(dir, 'odd.png');
+		writeFileSync(
+			labelFile,
+			encodePng({width: 200, height: 200, rgb: new Uint8Array(200 * 200 * 3)}),
+		);
+		const exportSeen: {options?: ExportOptions} = {};
+		const {stdout, exitCode} = await runServe(
+			() => stubAdapter('writes-bundle', exportSeen),
+			fakeServer(),
+			['serve', cartPath, '--label', labelFile, '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('label-wrong-size');
+		expect(stdout).toContain('scaled for you');
+		expect(exportSeen.options).toBeUndefined();
+	});
+});
+
+describe('picopilot serve: --label-frame (capture the label from the game)', () => {
+	it('captures frame N with no input and serves the export of a labeled copy', async () => {
+		let drive: DriveOptions | undefined;
+		let exportedCart = '';
+		const {exitCode} = await runServe(
+			() => ({
+				...stubAdapter('writes-bundle'),
+				async drive(o: DriveOptions): Promise<Pico8DriveResult> {
+					drive = o;
+					const shot = join(o.shotDir, 'label0.png');
+					writeFileSync(
+						shot,
+						readFileSync(
+							new URL(
+								'../engine/gfx/fixtures/pico8-screenshot-384.png',
+								import.meta.url,
+							),
+						),
+					);
+					return {
+						ok: true,
+						value: {screenshots: [shot], printh: '', exitReason: 'sentinel'},
+					};
+				},
+				async export(o: ExportOptions) {
+					exportedCart = readFileSync(o.cartPath, 'utf8');
+					return stubAdapter('writes-bundle').export(o);
+				},
+			}),
+			fakeServer(),
+			['serve', cartPath, '--label-frame', '2', '--json'],
+		);
+		expect(exitCode).toBe(0);
+		expect(drive).toBeDefined();
+		expect(exportedCart.split('__label__\n')[1]!.split('\n')[10]![10]).toBe(
+			'8',
+		);
+		expect(readdirSync(dir)).toEqual(['main.p8']);
+	});
+
+	it('rejects --label with --label-frame', async () => {
+		const {stdout, exitCode} = await runServe(
+			() => stubAdapter('writes-bundle'),
+			fakeServer(),
+			['serve', cartPath, '--label', 'x.png', '--label-frame', '1', '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('label-flags-conflict');
+	});
+});

package/src/commands/serve.ts

@@ -12,18 +12,23 @@ import {type Cli, z} from 'incur';
 import {
 	EXPORT_HTML_NAME,
 	type Pico8Adapter,
-	ShellPico8Adapter,
+	type Pico8ExportResult,
 } from '../engine/pico8/index.js';
+import {
+	createShellAdapterFactory,
+	PICO8_ENV,
+	type Pico8AdapterFactory,
+} from './pico8-env.js';
+import {prepareLabeledCart} from './label-cart.js';
 
 /**
  * Injects the PICO-8 adapter `serve` uses (defaults to the shell adapter). Same
  * seam as `export`/`run`: a test passes a stub so the export step needs no paid
  * binary, and the child `env` (`PICO8_PATH`/`PATH`) stays isolated.
  */
-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();
 
 /**
  * Injects the HTTP-server factory `serve` binds. The default is a zero-dep
@@ -174,6 +179,20 @@ export function registerServe(
 				),
 		}),
 		options: z.object({
+			label: z
+				.string()
+				.optional()
+				.describe(
+					'PNG to bake in as the __label__ (the export splash) for a cart that has none: a `run`/`playtest` screenshot as-is, or any 128x128 PNG. The cart itself is not modified. Ignored if the cart already has a label.',
+				),
+			labelFrame: z
+				.number()
+				.int()
+				.min(0)
+				.optional()
+				.describe(
+					'Capture the label from the game itself: run the cart headlessly with NO input and use frame N (0-based: 0 = the first drawn frame, usually the title screen) as the __label__. Needs PICO-8; the cart need not cooperate. Exclusive with --label; ignored if the cart already has a label.',
+				),
 			port: z
 				.number()
 				.int()
@@ -186,15 +205,11 @@ export function registerServe(
 				.int()
 				.positive()
 				.default(DEFAULT_BACKSTOP_MS)
-				.describe('Safety backstop for the export step.'),
-		}),
-		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`.'),
+				.describe(
+					'Safety backstop for the export step (and the --label-frame capture run).',
+				),
 		}),
+		env: PICO8_ENV,
 		output: z.object({
 			url: z.string().describe('The local URL to open in a browser.'),
 			port: z.number().describe('The port the server bound to.'),
@@ -210,6 +225,18 @@ export function registerServe(
 				args: {cart: 'game.p8'},
 				options: {port: 8080},
 			},
+			{
+				description:
+					'Serve a labelless cart, using a `run` screenshot as the splash',
+				args: {cart: 'game.p8'},
+				options: {label: './shots/<name>.png'},
+			},
+			{
+				description:
+					'Serve a labelless cart, using its title screen (frame 0) as the splash',
+				args: {cart: 'game.p8'},
+				options: {labelFrame: 0},
+			},
 		],
 		async run({args, options, env, error, ok}) {
 			const cartPath = isAbsolute(args.cart)
@@ -224,16 +251,48 @@ export function registerServe(
 				});
 			}
 
-			// Always export first, into an isolated temp dir (never a user path or
-			// ~/Desktop). The bundle is the standalone pair the static server plays.
-			const serveDir = mkdtempSync(join(tmpdir(), 'picopilot-serve-'));
+			// --label / --label-frame: export a labeled throwaway copy (shared with
+			// `export`; the cart is never mutated). A bad image or a failed capture
+			// fails before anything is exported.
 			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
-			const result = await adapter.export({
+			const labeled = await prepareLabeledCart(
 				cartPath,
-				outDir: serveDir,
-				htmlName: EXPORT_HTML_NAME,
-				backstopMs: options.backstopMs,
-			});
+				{
+					label: options.label,
+					labelFrame: options.labelFrame,
+					backstopMs: options.backstopMs,
+				},
+				(o) => adapter.drive(o),
+			);
+			if (!labeled.ok) {
+				return error({
+					code: labeled.code,
+					message: labeled.message,
+					exitCode: 1,
+					...(labeled.cta ? {cta: labeled.cta} : {}),
+				});
+			}
+
+			// Always export first, into an isolated temp dir (never a user path or
+			// ~/Desktop). The bundle is the standalone pair the static server plays.
+			// The labeled copy (in the user's cart dir) is removed on every path; a
+			// throw also reaps the temp dir, since nothing will be served from it.
+			let result: Pico8ExportResult;
+			let serveDir: string | undefined;
+			try {
+				serveDir = mkdtempSync(join(tmpdir(), 'picopilot-serve-'));
+				result = await adapter.export({
+					cartPath: labeled.cartPath,
+					outDir: serveDir,
+					htmlName: EXPORT_HTML_NAME,
+					backstopMs: options.backstopMs,
+				});
+			} catch (e) {
+				if (serveDir !== undefined) removeDir(serveDir);
+				throw e;
+			} finally {
+				labeled.cleanup();
+			}
 
 			if (!result.ok) {
 				// Nothing is being served: remove the temp dir now, not on exit.
@@ -250,7 +309,7 @@ export function registerServe(
 				return error({
 					code: 'export-failed',
 					message: result.value.labelWarning
-						? 'PICO-8 produced no bundle: this cart has no __label__ (the export splash), which the browser export needs. To just SEE your own build work, use `picopilot run` or `picopilot playtest` (no label needed) instead of serve. If you genuinely want a browser build to SHARE, bake a label first with `picopilot export --label <128x128.png>` (do NOT hand-edit main.p8), then re-serve.'
+						? 'PICO-8 produced no bundle: this cart has no __label__ (the export splash), which the browser export needs. To just SEE your own build work, use `picopilot run` or `picopilot playtest` (no label needed) instead of serve. If you genuinely want a browser build to SHARE, give it a splash: `picopilot serve <cart> --label-frame 0` captures the title screen for you, or `picopilot serve <cart> --label <screenshot.png>` takes any path `run`/`playtest` lists under `screenshots` as-is (do NOT hand-edit main.p8).'
 						: 'PICO-8 produced no export bundle. Check the cart runs without a boot error (via `picopilot run`).',
 					exitCode: 1,
 				});

package/src/commands/shrinko-env.test.ts

@@ -0,0 +1,68 @@
+import {mkdtempSync, rmSync, writeFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {Cli} from 'incur';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import type {ChildRunner} from '../engine/shrinko/index.js';
+import {createShellShrinkoFactory} from './shrinko-env.js';
+import {registerTokens} from './tokens.js';
+
+/**
+ * shrinko8 is a Python tool: a `pip install --user` copy is found through HOME
+ * (user site-packages), so the child must inherit the parent environment, with
+ * the command's resolved PATH overlaid (the same rule as the PICO-8 child,
+ * ADR-0017).
+ */
+
+let dir: string;
+let cartPath: string;
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'picopilot-shrinko-env-'));
+	cartPath = join(dir, 'main.p8');
+	writeFileSync(
+		cartPath,
+		'pico-8 cartridge // http://www.pico-8.com\nversion 42\n__lua__\nprint("hi")\n',
+	);
+});
+afterEach(() => rmSync(dir, {recursive: true, force: true}));
+
+describe('shrinko child env', () => {
+	it('HOME and the rest of the parent env reach shrinko; PATH comes from the resolved env', async () => {
+		let seen: NodeJS.ProcessEnv | undefined;
+		const run: ChildRunner = async (_file, _args, env) => {
+			seen = env;
+			return {
+				code: 0,
+				stdout: 'tokens: 3 0%\nchars: 11 0%\ncompressed: 20 0%\n',
+				stderr: '',
+				spawnError: undefined,
+			};
+		};
+		const cli = Cli.create('picopilot', {version: '0.0.0'});
+		registerTokens(
+			cli,
+			createShellShrinkoFactory({
+				parentEnv: {
+					HOME: '/home/agent',
+					PYTHONUSERBASE: '/home/agent/.local',
+					PATH: '/parent/bin',
+				},
+				run,
+			}),
+		);
+		let stdout = '';
+		await cli.serve(['tokens', cartPath, '--json'], {
+			stdout(s) {
+				stdout += s;
+			},
+			exit() {},
+			env: {PATH: '/resolved/bin'},
+		});
+		expect(JSON.parse(stdout).tokens).toBe(3);
+		expect(seen).toMatchObject({
+			HOME: '/home/agent',
+			PYTHONUSERBASE: '/home/agent/.local',
+			PATH: '/resolved/bin',
+		});
+	});
+});