picopilot 0.0.0 → 0.1.0

package/src/commands/run.test.ts

@@ -0,0 +1,238 @@
+import {execFileSync} from 'node:child_process';
+import {existsSync, mkdtempSync, readdirSync, writeFileSync} from 'node:fs';
+import {homedir, tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {Cli} from 'incur';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import type {
+	Pico8Adapter,
+	Pico8RecordResult,
+	Pico8Result,
+	RecordOptions,
+	RunOptions,
+} from '../engine/pico8/index.js';
+import {pico8NotFound} from '../engine/pico8/index.js';
+import {type Pico8AdapterFactory, registerRun} from './run.js';
+
+/** A trivial valid cart the command reads (existence + a path to hand the adapter). */
+const CART_TEXT =
+	'pico-8 cartridge // http://www.pico-8.com\nversion 42\n__lua__\nprint("hi")\n';
+
+let dir: string;
+let cartPath: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'picopilot-run-'));
+	cartPath = join(dir, 'main.p8');
+	writeFileSync(cartPath, CART_TEXT);
+});
+
+afterEach(() => {
+	try {
+		execFileSync('rm', ['-rf', dir]);
+	} catch {
+		// ignore
+	}
+});
+
+/**
+ * A stub {@link Pico8Adapter} standing in for BOTH the shell adapter and a
+ * hypothetical web-export adapter. It never spawns PICO-8, so no test depends on
+ * the paid binary. It also RECORDS the {@link RunOptions} it was handed, so a
+ * test can assert the command chose an isolated shotDir (never ~/Desktop).
+ */
+function stubAdapter(
+	result: Pico8Result,
+	seen?: {options?: RunOptions; recordOptions?: RecordOptions},
+	recordResult?: Pico8RecordResult,
+): Pico8Adapter {
+	return {
+		async run(options) {
+			if (seen !== undefined) seen.options = options;
+			return result;
+		},
+		async record(options) {
+			if (seen !== undefined) seen.recordOptions = options;
+			return (
+				recordResult ?? {
+					ok: true,
+					value: {
+						wavPath: undefined,
+						printh: '',
+						exitReason: 'sentinel',
+					},
+				}
+			);
+		},
+	};
+}
+
+function ranWith(exitReason: 'sentinel' | 'timeout' | 'exit'): Pico8Result {
+	return {
+		ok: true,
+		value: {screenshots: [], printh: 'hello from cart\n', exitReason},
+	};
+}
+
+/**
+ * Drives `picopilot run` through incur's `serve` DI with an INJECTED adapter
+ * factory (the seam), capturing stdout + exit without the real environment or
+ * the paid binary. `env` defaults to a bare PATH the stub ignores.
+ */
+async function runRun(
+	factory: Pico8AdapterFactory,
+	argv: string[] = ['run', cartPath, '--json'],
+	env: Record<string, string | undefined> = {PATH: '/does/not/matter'},
+) {
+	const cli = Cli.create('picopilot', {version: '0.0.0'});
+	registerRun(cli, factory);
+	let stdout = '';
+	let exitCode = 0;
+	await cli.serve(argv, {
+		stdout(s) {
+			stdout += s;
+		},
+		exit(code) {
+			exitCode = code;
+		},
+		env,
+	});
+	return {stdout, exitCode};
+}
+
+describe('picopilot run: PICO-8 absent (the CI-testable boundary)', () => {
+	it('returns structured pico8-not-found + nonzero exit (mirrors shrinko, never a crash)', async () => {
+		const {stdout, exitCode} = await runRun(() => stubAdapter(pico8NotFound()));
+		expect(exitCode).not.toBe(0);
+		// The message carries the exact remedy + needs so an agent reading only the
+		// message still learns the fix.
+		expect(stdout).toContain('set PICO8_PATH or install PICO-8');
+		expect(stdout).toContain('pico8');
+	});
+});
+
+describe('picopilot run: structured run report', () => {
+	it('reports screenshots + printh + exitReason on a sentinel-ended run', async () => {
+		const {stdout, exitCode} = await runRun(() =>
+			stubAdapter(ranWith('sentinel')),
+		);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.exitReason).toBe('sentinel');
+		expect(out.printh).toContain('hello from cart');
+		expect(Array.isArray(out.screenshots)).toBe(true);
+	});
+
+	it('a backstop timeout CTAs toward the static gate (verify/tokens)', async () => {
+		const {stdout, exitCode} = await runRun(() =>
+			stubAdapter(ranWith('timeout')),
+		);
+		// A timeout is a soft warning, not a failure exit: the run still returns a report.
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.exitReason).toBe('timeout');
+		// The CTA points at the static checks to catch a code fault before re-running.
+		expect(stdout.toLowerCase()).toContain('verify');
+	});
+});
+
+describe('picopilot run: shotDir isolation (never ~/Desktop)', () => {
+	it('defaults to an isolated temp dir, not the real ~/Desktop', async () => {
+		const seen: {options?: RunOptions} = {};
+		const {exitCode} = await runRun(() =>
+			stubAdapter(ranWith('sentinel'), seen),
+		);
+		expect(exitCode).toBe(0);
+		const shotDir = seen.options?.shotDir ?? '';
+		// The chosen dir is a fresh temp dir, NOT the default screenshot location.
+		expect(shotDir.startsWith(tmpdir())).toBe(true);
+		expect(shotDir).not.toContain(join(homedir(), 'Desktop'));
+		// And it was actually created for PICO-8 to write into.
+		expect(existsSync(shotDir)).toBe(true);
+	});
+
+	it('threads --input through to the adapter (the one-shot playtest channel)', async () => {
+		const seen: {options?: RunOptions} = {};
+		await runRun(
+			() => stubAdapter(ranWith('sentinel'), seen),
+			['run', cartPath, '--input', 'rrrrz', '--json'],
+		);
+		expect(seen.options?.input).toBe('rrrrz');
+	});
+
+	it('honours an explicit --shot-dir', async () => {
+		const seen: {options?: RunOptions} = {};
+		const chosen = join(dir, 'shots');
+		await runRun(
+			() => stubAdapter(ranWith('sentinel'), seen),
+			['run', cartPath, '--shot-dir', chosen, '--json'],
+		);
+		expect(seen.options?.shotDir).toBe(chosen);
+		expect(existsSync(chosen)).toBe(true); // created if missing
+	});
+});
+
+describe('picopilot run: --record-audio (additive WAV capture, ADR-0009)', () => {
+	it('collects a WAV alongside the screenshots when --record-audio is set', async () => {
+		const seen: {options?: RunOptions; recordOptions?: RecordOptions} = {};
+		const wav = join(dir, 'run.wav');
+		writeFileSync(wav, 'x');
+		const {stdout, exitCode} = await runRun(
+			() =>
+				stubAdapter(ranWith('sentinel'), seen, {
+					ok: true,
+					value: {wavPath: wav, printh: '', exitReason: 'sentinel'},
+				}),
+			['run', cartPath, '--record-audio', '--json'],
+		);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		// The WAV is an ADDITIVE artifact next to the existing screenshot envelope.
+		expect(out.wav).toBe(wav);
+		expect(out.audioCaptured).toBe(true);
+		expect(Array.isArray(out.screenshots)).toBe(true);
+		// The record pass got a real A/V request into the SAME isolated shotDir.
+		expect(seen.recordOptions?.wavDir).toBe(seen.options?.shotDir);
+	});
+
+	it('is additive: without the flag no record pass runs (audioCaptured false)', async () => {
+		const seen: {options?: RunOptions; recordOptions?: RecordOptions} = {};
+		const {stdout} = await runRun(() => stubAdapter(ranWith('sentinel'), seen));
+		const out = JSON.parse(stdout);
+		expect(out.audioCaptured).toBe(false);
+		expect(out.wav).toBeUndefined();
+		expect(seen.recordOptions).toBeUndefined(); // record() never called
+	});
+});
+
+describe('picopilot run: cart-not-found (picopilot-side error, distinct from pico8 absence)', () => {
+	it('errors with a nonzero exit when the cart path does not exist', async () => {
+		const {stdout, exitCode} = await runRun(
+			() => stubAdapter(ranWith('sentinel')),
+			['run', join(dir, 'nope.p8'), '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('no cart at');
+	});
+
+	it('does NOT invoke the adapter when the cart is missing (fails fast)', async () => {
+		let called = false;
+		await runRun(() => {
+			called = true;
+			return stubAdapter(ranWith('sentinel'));
+		}, ['run', join(dir, 'missing.p8'), '--json']);
+		// The cart-existence check runs BEFORE the adapter factory.
+		expect(called).toBe(false);
+	});
+
+	it('leaves the real ~/Desktop BYTE-untouched across a run (no screenshot pollution)', async () => {
+		// The pollution guard: the -desktop flag redirects screenshots to a temp dir,
+		// so a default run must never add/change anything under the real ~/Desktop.
+		const desktop = join(homedir(), 'Desktop');
+		const snap = (): string[] =>
+			existsSync(desktop) ? readdirSync(desktop).sort() : [];
+		const before = snap();
+		await runRun(() => stubAdapter(ranWith('sentinel')));
+		expect(snap()).toEqual(before); // same entries: an absent dir stays absent, a present one unchanged
+	});
+});

package/src/commands/run.ts

@@ -0,0 +1,259 @@
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {isAbsolute, join, resolve} from 'node:path';
+import {type Cli, z} from 'incur';
+import {
+	buildRecordHarness,
+	DONE_SENTINEL,
+	HarnessError,
+	type Pico8Adapter,
+	ShellPico8Adapter,
+} from '../engine/pico8/index.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`).
+ */
+export type Pico8AdapterFactory = (env: NodeJS.ProcessEnv) => Pico8Adapter;
+
+const defaultAdapterFactory: Pico8AdapterFactory = (env) =>
+	new ShellPico8Adapter({env});
+
+/** The default backstop: kill a cart that never signals/exits after this many ms. */
+const DEFAULT_BACKSTOP_MS = 15_000;
+
+/**
+ * Registers `picopilot run`, the THIN sentinel-watch + screenshot-collect
+ * orchestration command (US #14, ADR-0006). It is NOT a `pico8` wrapper: its
+ * value is the glue an agent should not hand-roll every run, launch PICO-8,
+ * stream stdout, kill on the cart's done-sentinel (backstop as the safety net),
+ * and collect screenshots + printh + exit reason into ONE structured result.
+ *
+ * The cart cooperates: it self-screenshots via `extcmd("screen")` on a timer and
+ * prints the done-sentinel via `printh` when finished (the `picopilot-debug`
+ * skill teaches the recipe). A cart cannot self-quit the app, so the external
+ * sentinel-kill IS the quit mechanism.
+ *
+ * PICO-8 absent → structured `pico8-not-found` + nonzero exit (mirrors the
+ * shrinko boundary), never a crash or a hang. That absent path is the one
+ * exercised in CI; live runs are a manual/opt-in tier.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to drive present/absent without the real binary.
+ */
+export function registerRun(
+	cli: Cli.Cli,
+	adapterFactory: Pico8AdapterFactory = defaultAdapterFactory,
+): void {
+	cli.command('run', {
+		description:
+			"Run a cart on the user's PICO-8, capture printh + screenshots, end on a done-sentinel. Requires PICO-8.",
+		args: z.object({
+			cart: z
+				.string()
+				.default('main.p8')
+				.describe(
+					'The .p8 cart to run. Defaults to main.p8 in the current folder.',
+				),
+		}),
+		options: z.object({
+			shotDir: z
+				.string()
+				.optional()
+				.describe(
+					'Where PICO-8 writes screenshots (-desktop). Defaults to an isolated temp dir; NEVER ~/Desktop.',
+				),
+			sentinel: z
+				.string()
+				.default(DONE_SENTINEL)
+				.describe(
+					'The stdout line that ends the run. The cart printh-es this when done.',
+				),
+			backstopMs: z
+				.number()
+				.int()
+				.positive()
+				.default(DEFAULT_BACKSTOP_MS)
+				.describe(
+					'Safety backstop: kill PICO-8 after this many ms if it never signals.',
+				),
+			input: z
+				.string()
+				.optional()
+				.describe(
+					'One-shot scripted input passed as `-p` (the cart reads it via stat(6)) for automated playtests.',
+				),
+			recordAudio: z
+				.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.",
+				),
+		}),
+		// 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`.'),
+		}),
+		output: z.object({
+			screenshots: z
+				.array(z.string())
+				.describe('Absolute paths of the PNG screenshots the cart produced.'),
+			printh: z
+				.string()
+				.describe('Captured stdout (the cart printh output + PICO-8 lines).'),
+			exitReason: z
+				.enum(['sentinel', 'timeout', 'exit'])
+				.describe(
+					'sentinel = cart signalled done; timeout = backstop fired; exit = PICO-8 quit.',
+				),
+			shotDir: z.string().describe('The dir screenshots were written to.'),
+			wav: z
+				.string()
+				.optional()
+				.describe(
+					'Absolute path of the captured WAV (only with --record-audio; omitted if no audio was captured).',
+				),
+			audioCaptured: z
+				.boolean()
+				.describe(
+					'Whether a non-empty WAV was captured (false unless --record-audio ran and produced audio).',
+				),
+		}),
+		examples: [
+			{description: 'Run main.p8'},
+			{description: 'Run a specific cart', args: {cart: 'game.p8'}},
+			{
+				description: 'Collect screenshots into a chosen dir',
+				args: {cart: 'game.p8'},
+				options: {shotDir: './shots'},
+			},
+		],
+		async run({args, options, env, error, ok}) {
+			const cartPath = isAbsolute(args.cart)
+				? args.cart
+				: resolve(process.cwd(), args.cart);
+
+			// A missing cart is a picopilot-side error, distinct from PICO-8 absence.
+			if (!existsSync(cartPath)) {
+				return error({
+					code: 'cart-not-found',
+					message: `no cart at ${cartPath}`,
+					exitCode: 1,
+				});
+			}
+
+			// Screenshot dir: a user-given path, else an isolated temp dir. NEVER the
+			// default ~/Desktop (the `-desktop` flag is the isolation lever). Create
+			// it so PICO-8 has somewhere to write.
+			const shotDir =
+				options.shotDir !== undefined
+					? isAbsolute(options.shotDir)
+						? options.shotDir
+						: resolve(process.cwd(), options.shotDir)
+					: mkdtempSync(join(tmpdir(), 'picopilot-run-'));
+			if (!existsSync(shotDir)) mkdirSync(shotDir, {recursive: true});
+
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			const result = await adapter.run({
+				cartPath,
+				shotDir,
+				sentinel: options.sentinel,
+				backstopMs: options.backstopMs,
+				input: options.input,
+			});
+
+			if (!result.ok) {
+				// The two-tier structured failure (US #19, ADR-0006): PICO-8 absent.
+				// The message carries the exact remedy + needs; the code is the handle.
+				return error({
+					code: result.reason,
+					message: `PICO-8 is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+					exitCode: 1,
+				});
+			}
+
+			const {screenshots, printh, exitReason} = result.value;
+
+			// --record-audio: an ADDITIVE second pass that records the run's audio to a
+			// WAV. It cannot reuse the headless `-x` screenshot pass (which mixes no
+			// audio -> an empty WAV, ADR-0009), so it does a separate `-run` capture via
+			// the record seam, injecting the same cooperative recorder `audio record`
+			// uses. The WAV lands in the isolated shotDir alongside the screenshots.
+			let wav: string | undefined;
+			let audioCaptured = false;
+			if (options.recordAudio) {
+				try {
+					const harness = buildRecordHarness(readFileSync(cartPath, 'utf8'), {
+						sentinel: options.sentinel,
+					});
+					const harnessCart = join(shotDir, 'record-audio-harness.p8');
+					writeFileSync(harnessCart, harness.cartText);
+					const rec = await adapter.record({
+						cartPath: harnessCart,
+						wavDir: shotDir,
+						wavBasename: harness.wavBasename,
+						sentinel: options.sentinel,
+						backstopMs: options.backstopMs,
+					});
+					if (rec.ok) {
+						wav = rec.value.wavPath;
+						audioCaptured = rec.value.wavPath !== undefined;
+					}
+					// A record-pass pico8-not-found is impossible here: the screenshot
+					// pass above already returned pico8-not-found if PICO-8 were absent.
+				} catch (e) {
+					if (!(e instanceof HarnessError)) throw e;
+					// A harness-build failure (unparseable cart) leaves audioCaptured false;
+					// the screenshot run's report still stands.
+				}
+			}
+
+			// A backstop timeout is a soft warning: the cart never signalled done, so
+			// it may have hung or errored. CTA the agent toward the static checks
+			// (lint/tokens) to catch a code fault before re-running.
+			const cta =
+				exitReason === 'timeout'
+					? {
+							description:
+								'The cart never printed the done-sentinel (backstop fired). Check for a fault:',
+							commands: [
+								{
+									command: 'verify',
+									description:
+										'Run the static gate (tokens + lint + integrity).',
+								},
+								{
+									command: 'tokens',
+									description: 'Confirm the cart is under the token budget.',
+								},
+							],
+						}
+					: undefined;
+
+			return ok(
+				{
+					screenshots: [...screenshots],
+					printh,
+					exitReason,
+					shotDir,
+					wav,
+					audioCaptured,
+				},
+				cta === undefined ? undefined : {cta},
+			);
+		},
+	});
+}