picopilot 0.0.0 → 0.1.1

package/src/engine/pico8/shell.ts

@@ -0,0 +1,412 @@
+import {spawn} from 'node:child_process';
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	statSync,
+} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {
+	type DriveOptions,
+	type ExitReason,
+	EXPORT_HTML_NAME,
+	type ExportOptions,
+	type Pico8Adapter,
+	pico8NotFound,
+	type Pico8DriveResult,
+	type Pico8ExportResult,
+	type Pico8RecordResult,
+	type Pico8Result,
+	RECORD_WAV_BASENAME,
+	type RecordOptions,
+	type RunOptions,
+} from './adapter.js';
+import {SentinelWatcher} from './sentinel.js';
+
+/**
+ * A spawned PICO-8 process, abstracted so tests inject a fake. `onStdout`
+ * delivers stdout chunks (both `stdout` and `stderr` folded in, since PICO-8's
+ * `printh` and its own lines can land on either); `onClose` fires when the
+ * process exits on its own; `onError` fires on a spawn failure (ENOENT ⇒ PICO-8
+ * absent). `kill` terminates the process tree (the backstop / sentinel kill).
+ */
+export interface Pico8Process {
+	onStdout(cb: (chunk: string) => void): void;
+	onClose(cb: (code: number | null) => void): void;
+	onError(cb: (err: NodeJS.ErrnoException) => void): void;
+	kill(): void;
+	/**
+	 * Writes raw bytes to the process's stdin, for the `drive` transport (the
+	 * fixed-size command blocks). Absent/undefined when stdin was detached
+	 * (`run`/`record` ignore stdin so the cart never blocks on console input).
+	 */
+	writeStdin?(bytes: Uint8Array): void;
+}
+
+/**
+ * The process-spawn seam (mirrors shrinko's `ChildRunner`). The real impl spawns
+ * `pico8 -x`; a test injects a fake that emits synthetic stdout and a chosen
+ * outcome, so the sentinel-kill / backstop / pico8-absent paths are all testable
+ * WITHOUT the paid binary. `env` is handed in (its `PICO8_PATH`/`PATH` are the
+ * isolation levers), never read ambiently.
+ */
+export type SpawnRunner = (
+	file: string,
+	args: string[],
+	env: NodeJS.ProcessEnv,
+	options?: {stdin?: boolean},
+) => Pico8Process;
+
+/**
+ * The default {@link SpawnRunner}: `spawn` with stdin detached (`ignore`) so the
+ * cart never blocks on console input, stdout/stderr piped for the sentinel
+ * watch. A spawn failure surfaces via `onError` (ENOENT ⇒ absent). `kill` sends
+ * SIGKILL to the whole tree (`detached` + negative pid) so a hung PICO-8 dies.
+ */
+/**
+ * An isolated directory to hand PICO-8 as its `-home`, so it writes its config /
+ * data tree (`config.txt`, `log.txt`, `sdl_controllers.txt`, `backup/`, `carts/`,
+ * `bbs/`, `cdata/`, `cstore/`, `plates/`) THERE and never litters the caller's
+ * CWD. Without `-home`, PICO-8 creates that tree in whatever directory it was
+ * spawned from, e.g. a user's repo root (see
+ * work/notes/observations/pico8-appimage-writes-config-into-cwd.md). Verified:
+ * `-home <dir>` fully redirects every one of those files/dirs.
+ *
+ * One dir per process, created lazily under the OS temp dir and reused by every
+ * launch (run/drive/export/record/session). It is throwaway config, so OS temp
+ * cleanup reclaims it; picopilot never needs its contents.
+ */
+let cachedHome: string | undefined;
+export function pico8HomeDir(): string {
+	if (cachedHome !== undefined && existsSync(cachedHome)) return cachedHome;
+	cachedHome = mkdtempSync(join(tmpdir(), 'picopilot-pico8-home-'));
+	return cachedHome;
+}
+
+/**
+ * Prepend `-home <isolatedDir>` to a PICO-8 arg list so its config/data never
+ * land in the CWD. Applied at every spawn site.
+ */
+export function withPico8Home(args: string[]): string[] {
+	const home = pico8HomeDir();
+	mkdirSync(home, {recursive: true});
+	return ['-home', home, ...args];
+}
+
+export const spawnRunner: SpawnRunner = (file, args, env, options) => {
+	// `drive` pipes fixed-size command blocks to stdin; `run`/`record` detach it so
+	// the cart never blocks on console input.
+	const stdin = options?.stdin === true ? 'pipe' : 'ignore';
+	const child = spawn(file, args, {
+		env,
+		stdio: [stdin, 'pipe', 'pipe'],
+		detached: true,
+	});
+	child.stdout?.setEncoding('utf8');
+	child.stderr?.setEncoding('utf8');
+	return {
+		onStdout(cb) {
+			child.stdout?.on('data', cb);
+			child.stderr?.on('data', cb);
+		},
+		onClose(cb) {
+			child.on('close', cb);
+		},
+		onError(cb) {
+			child.on('error', cb as (e: Error) => void);
+		},
+		writeStdin(bytes) {
+			try {
+				child.stdin?.write(Buffer.from(bytes));
+			} catch {
+				// A closed stdin (the cart exited) is not fatal to the run.
+			}
+		},
+		kill() {
+			try {
+				// Negative pid kills the process GROUP (detached), so any child dies too.
+				if (child.pid !== undefined) process.kill(-child.pid, 'SIGKILL');
+			} catch {
+				child.kill('SIGKILL'); // fall back to killing just the process
+			}
+		},
+	};
+};
+
+/** The candidate ways to launch PICO-8, tried in order: `PICO8_PATH`, then `pico8` on `PATH`. */
+export function pico8Candidates(env: NodeJS.ProcessEnv): string[] {
+	const fromEnv = env.PICO8_PATH?.trim();
+	return fromEnv !== undefined && fromEnv.length > 0
+		? [fromEnv, 'pico8']
+		: ['pico8'];
+}
+
+/**
+ * The files an export produced in `outDir`, absolute + sorted. PICO-8 writes the
+ * `<name>.html` shell and the `<name>.js` runtime payload; we return every file
+ * present so the report is faithful even if a future PICO-8 adds siblings.
+ */
+function collectExportFiles(outDir: string): string[] {
+	if (!existsSync(outDir)) return [];
+	return readdirSync(outDir)
+		.sort()
+		.map((f) => join(outDir, f))
+		.filter((p) => {
+			try {
+				return statSync(p).isFile();
+			} catch {
+				return false;
+			}
+		});
+}
+
+/** PNG files a run produced in its `-desktop` dir, sorted for deterministic order. */
+function collectScreenshots(shotDir: string): string[] {
+	if (!existsSync(shotDir)) return [];
+	return readdirSync(shotDir)
+		.filter((f) => f.toLowerCase().endsWith('.png'))
+		.sort()
+		.map((f) => join(shotDir, f));
+}
+
+/**
+ * The WAV a record run produced in its `wavDir`, or `undefined`. Prefers the
+ * expected `<basename>.wav` (what the harness named via `set_filename`); falls
+ * back to any single `.wav` present. A well-formed but EMPTY WAV (a headless
+ * `-x` capture yields a 44-byte 0-frame RIFF header, ADR-0009) is treated as
+ * "no usable WAV" so a silent capture is not reported as a real recording.
+ */
+function collectWav(wavDir: string, basename: string): string | undefined {
+	if (!existsSync(wavDir)) return undefined;
+	const wavs = readdirSync(wavDir).filter((f) =>
+		f.toLowerCase().endsWith('.wav'),
+	);
+	if (wavs.length === 0) return undefined;
+	const expected = `${basename}.wav`;
+	const chosen = wavs.includes(expected) ? expected : wavs.sort()[0]!;
+	const path = join(wavDir, chosen);
+	// A 44-byte RIFF header with no PCM data is the empty/silent (headless) WAV.
+	try {
+		if (statSync(path).size <= 44) return undefined;
+	} catch {
+		return undefined;
+	}
+	return path;
+}
+
+/** Options for {@link ShellPico8Adapter}. */
+export interface ShellPico8Options {
+	/** The environment for the child (its `PICO8_PATH`/`PATH` locate the binary). */
+	readonly env: NodeJS.ProcessEnv;
+	/** The spawn runner (defaults to {@link spawnRunner}); tests inject a fake. */
+	readonly spawn?: SpawnRunner;
+}
+
+/**
+ * The v1 {@link Pico8Adapter}: shells out to the user's native `pico8 -x`
+ * (ADR-0006, native path first). It owns the ORCHESTRATION the command should
+ * not hand-roll: launch, stream stdout, kill on the done-sentinel, arm the
+ * backstop, and collect screenshots + printh + exit reason into one result.
+ *
+ * PICO-8 absent (the first candidate ENOENTs and there is no fallback) returns
+ * the structured {@link pico8NotFound} value, never a throw or a hang. That
+ * absent path is the CI-testable one; live runs are a manual/opt-in tier.
+ */
+export class ShellPico8Adapter implements Pico8Adapter {
+	private readonly env: NodeJS.ProcessEnv;
+	private readonly spawnRun: SpawnRunner;
+
+	constructor(options: ShellPico8Options) {
+		this.env = options.env;
+		this.spawnRun = options.spawn ?? spawnRunner;
+	}
+
+	run(options: RunOptions): Promise<Pico8Result> {
+		const [file] = pico8Candidates(this.env) as [string, ...string[]];
+		const args = [
+			'-desktop',
+			options.shotDir,
+			'-x',
+			options.cartPath,
+			// One-shot scripted input (the cart reads it via stat(6)); omitted if absent.
+			...(options.input !== undefined ? ['-p', options.input] : []),
+		];
+		return this.orchestrate(file, args, options, (exitReason, printh) => ({
+			ok: true,
+			value: {
+				screenshots: collectScreenshots(options.shotDir),
+				printh,
+				exitReason,
+			},
+		}));
+	}
+
+	/**
+	 * Records a running cart's audio to a WAV (ADR-0009). Launches PICO-8 in a
+	 * REAL A/V session (`-run`, NOT the headless `-x` that mixes no audio) and
+	 * controls the WAV location with `-root_path <wavDir>`, because
+	 * `extcmd("audio_end", 1)` saves to PICO-8's CURRENT folder, not `-desktop`
+	 * (the `audio_end(1)` trap). The cooperating cart (a harness for `record`, or
+	 * the whole render harness) does the `audio_rec`/`audio_end`/sentinel dance; we
+	 * watch the sentinel, arm the backstop, and collect `<basename>.wav` from the
+	 * isolated `wavDir`. Live capture is a manual/opt-in tier; the absent path is
+	 * the CI-testable one.
+	 */
+	/**
+	 * Drives a throwaway cart through scripted input and captures live gameplay
+	 * (ADR-0011). Launches `-desktop <shotDir> -x <cart>` with a LIVE stdin, writes
+	 * the whole encoded FIXED-SIZE command block stream up front (the one-shot; the
+	 * cart drains one block per frame and screenshots at the SHOT points), watches
+	 * the sentinel, arms the backstop, and collects the SHOT PNGs + printh + exit
+	 * reason. Returns {@link pico8NotFound} when PICO-8 is absent. Live capture is a
+	 * manual/opt-in tier; the absent path is the CI-testable one.
+	 */
+	drive(options: DriveOptions): Promise<Pico8DriveResult> {
+		const [file] = pico8Candidates(this.env) as [string, ...string[]];
+		const args = ['-desktop', options.shotDir, '-x', options.cartPath];
+		return this.orchestrate<Pico8DriveResult>(
+			file,
+			args,
+			{sentinel: options.sentinel, backstopMs: options.backstopMs},
+			(exitReason, printh) => ({
+				ok: true,
+				value: {
+					screenshots: collectScreenshots(options.shotDir),
+					printh,
+					exitReason,
+				},
+			}),
+			{stdin: true, onSpawn: (proc) => proc.writeStdin?.(options.blocks)},
+		);
+	}
+
+	/**
+	 * Exports the cart as a PICO-8 HTML bundle over the HEADLESS `-x` path (no
+	 * display needed: `pico8 <cart> -export <outDir>/<name> -x` runs the cart, writes
+	 * `<name>.html` + `<name>.js`, and exits). PICO-8 derives both file names from
+	 * the `.html` name, so passing `index.html` yields a directly-serveable pair.
+	 * A labelless cart prints "please capture a label first" and still exports (a
+	 * blank splash), surfaced as `labelWarning`. PICO-8 absent -> {@link pico8NotFound}.
+	 */
+	export(options: ExportOptions): Promise<Pico8ExportResult> {
+		const [file] = pico8Candidates(this.env) as [string, ...string[]];
+		const htmlName = options.htmlName ?? EXPORT_HTML_NAME;
+		const outPath = join(options.outDir, htmlName);
+		// `-export <name>.html` is a load-and-export command; `-x` makes it headless
+		// (run the cart, perform the export, exit) so no window/display is needed.
+		const args = ['-export', outPath, '-x', options.cartPath];
+		return this.orchestrate<Pico8ExportResult>(
+			file,
+			args,
+			// The export has no cooperative done-sentinel; `-x` exits on its own when
+			// finished, and the backstop is the net for a cart that hangs at boot.
+			{backstopMs: options.backstopMs},
+			(_exitReason, printh) => {
+				const files = collectExportFiles(options.outDir);
+				const htmlPath = files.find((p) => p.endsWith('.html'));
+				const jsPath = files.find((p) => p.endsWith('.js'));
+				return {
+					ok: true,
+					value: {
+						htmlPath,
+						jsPath,
+						files,
+						// PICO-8 warns when the cart has no `__label__` to embed as the splash.
+						labelWarning: /please capture a label first/i.test(printh),
+					},
+				};
+			},
+		);
+	}
+
+	record(options: RecordOptions): Promise<Pico8RecordResult> {
+		const [file] = pico8Candidates(this.env) as [string, ...string[]];
+		const basename = options.wavBasename ?? RECORD_WAV_BASENAME;
+		// `-root_path <wavDir>` steers the `audio_end(1)`-to-current-folder WAV into
+		// the isolated temp dir (never ~/Desktop or the carts root). `-run` is a real
+		// A/V session (recording needs audio to capture; `-x` yields an empty WAV).
+		const args = ['-root_path', options.wavDir, '-run', options.cartPath];
+		return this.orchestrate<Pico8RecordResult>(
+			file,
+			args,
+			{sentinel: options.sentinel, backstopMs: options.backstopMs},
+			(exitReason, printh) => ({
+				ok: true,
+				value: {
+					wavPath: collectWav(options.wavDir, basename),
+					printh,
+					exitReason,
+				},
+			}),
+		);
+	}
+
+	/**
+	 * The shared launch/sentinel-watch/backstop/collect loop behind both
+	 * {@link run} and {@link record}. `buildOk` turns the exit reason + captured
+	 * stdout into the command-specific success value; a spawn ENOENT with no
+	 * fallback resolves the structured {@link pico8NotFound}. `printh` for `run` is
+	 * filled by the caller from the run report path (kept out of `buildOk` there so
+	 * the two report shapes stay distinct).
+	 */
+	private orchestrate<R extends {ok: boolean}>(
+		file: string,
+		args: string[],
+		opts: {sentinel?: string; backstopMs: number},
+		buildOk: (exitReason: ExitReason, printh: string) => R,
+		spawnOpts?: {stdin?: boolean; onSpawn?: (proc: Pico8Process) => void},
+	): Promise<R | ReturnType<typeof pico8NotFound>> {
+		const watcher = new SentinelWatcher(opts.sentinel);
+
+		return new Promise<R | ReturnType<typeof pico8NotFound>>((resolve) => {
+			let settled = false;
+			let backstop: NodeJS.Timeout | undefined;
+			const proc = this.spawnRun(file, withPico8Home(args), this.env, {
+				stdin: spawnOpts?.stdin,
+			});
+
+			const finish = (exitReason: ExitReason): void => {
+				if (settled) return;
+				settled = true;
+				if (backstop !== undefined) clearTimeout(backstop);
+				resolve(buildOk(exitReason, watcher.text));
+			};
+
+			proc.onError((err) => {
+				// A spawn ENOENT ⇒ PICO-8 is absent (a bad PICO8_PATH surfaces as absence
+				// with the same remedy, not a silent fall-through). Any other spawn error
+				// is a failed run, not a crash.
+				if (settled) return;
+				if (err.code === 'ENOENT') {
+					settled = true;
+					if (backstop !== undefined) clearTimeout(backstop);
+					resolve(pico8NotFound());
+				} else {
+					finish('exit');
+				}
+			});
+
+			proc.onStdout((chunk) => {
+				if (watcher.push(chunk) && !settled) {
+					proc.kill(); // sentinel matched: end the run promptly
+					finish('sentinel');
+				}
+			});
+
+			proc.onClose(() => finish('exit')); // PICO-8 exited on its own
+
+			// For `drive`: write the command blocks to the live stdin now that it is
+			// spawned. A spawn ENOENT resolves via onError before this matters.
+			spawnOpts?.onSpawn?.(proc);
+
+			// Backstop: a cart that neither signals nor exits gets killed.
+			backstop = setTimeout(() => {
+				if (settled) return;
+				proc.kill();
+				finish('timeout');
+			}, opts.backstopMs);
+		});
+	}
+}

package/src/engine/pico8/supervisor.test.ts

@@ -0,0 +1,105 @@
+import {mkdtempSync, rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {
+	encodeFrame,
+	FrameDecoder,
+	SESSION_BASE_DIRNAME,
+	SessionRegistry,
+	type SessionRequest,
+	type SessionResponse,
+} from './supervisor.js';
+
+/**
+ * The session SUPERVISOR's pure pieces are CI-tested without a socket or binary
+ * (ADR-0011): the id/path registry (so a session can never escape its controlled
+ * base) and the newline-JSON frame codec (so the client<->daemon protocol is
+ * exact). The live daemon is the manual/opt-in tier.
+ */
+
+describe('SessionRegistry: id validation (no path traversal, controlled base)', () => {
+	it('accepts filesystem-safe ids', () => {
+		for (const id of ['run1', 's-abc123', 'A.b_c-1']) {
+			expect(SessionRegistry.validateId(id)).toBe(id);
+		}
+	});
+
+	it('rejects traversal + unsafe ids (structured throw)', () => {
+		for (const bad of ['..', '.', 'a/b', '../etc', 'a b', '', 'x'.repeat(65)]) {
+			expect(() => SessionRegistry.validateId(bad)).toThrow();
+		}
+	});
+
+	it('fresh ids are unique + safe', () => {
+		const a = SessionRegistry.freshId();
+		const b = SessionRegistry.freshId();
+		expect(a).not.toBe(b);
+		expect(SessionRegistry.validateId(a)).toBe(a);
+	});
+});
+
+describe('SessionRegistry: path derivation under a controlled base', () => {
+	let base: string;
+	beforeEach(() => {
+		base = mkdtempSync(join(tmpdir(), 'pp-sess-'));
+	});
+	afterEach(() => rmSync(base, {recursive: true, force: true}));
+
+	it('resolves a session id to its dir/socket/shots under the base', () => {
+		const reg = new SessionRegistry(base);
+		const p = reg.resolve('run1');
+		expect(p.dir).toBe(join(base, 'run1'));
+		expect(p.socket.startsWith(p.dir)).toBe(true);
+		expect(p.shotDir.startsWith(p.dir)).toBe(true);
+	});
+
+	it('a resolved socket/shotDir NEVER escapes the base (no traversal path)', () => {
+		const reg = new SessionRegistry(base);
+		expect(() => reg.resolve('../escape')).toThrow();
+	});
+
+	it('create makes the dir + shotDir and list/remove round-trip', () => {
+		const reg = new SessionRegistry(base);
+		reg.create('a');
+		reg.create('b');
+		expect(reg.list()).toEqual(['a', 'b']);
+		reg.remove('a');
+		expect(reg.list()).toEqual(['b']);
+	});
+
+	it('the default base sits under tmp (never ~/Desktop or the carts root)', () => {
+		const reg = new SessionRegistry();
+		expect(reg.base).toBe(join(tmpdir(), SESSION_BASE_DIRNAME));
+	});
+});
+
+describe('the session frame codec (client <-> daemon protocol)', () => {
+	it('encodes a request as one newline-terminated JSON frame', () => {
+		const req: SessionRequest = {verb: 'step', frames: 30};
+		expect(encodeFrame(req)).toBe(`${JSON.stringify(req)}\n`);
+	});
+
+	it('decodes whole frames + buffers a partial one across chunks', () => {
+		const a: SessionResponse = {
+			ok: true,
+			value: {id: 'x', frame: 1, alive: true},
+		};
+		const b: SessionResponse = {ok: false, code: 'e', message: 'boom'};
+		const wire = encodeFrame(a) + encodeFrame(b);
+
+		// A single push of the whole stream yields both frames, in order.
+		expect(new FrameDecoder<SessionResponse>().push(wire)).toEqual([a, b]);
+
+		// A frame split across two chunks still decodes exactly once (no half frame).
+		const dec = new FrameDecoder<SessionResponse>();
+		const cut = Math.floor(wire.indexOf('\n') / 2); // mid the FIRST frame
+		expect(dec.push(wire.slice(0, cut))).toEqual([]); // no complete frame yet
+		expect(dec.push(wire.slice(cut))).toEqual([a, b]); // both complete now
+	});
+
+	it('ignores blank lines between frames', () => {
+		const dec = new FrameDecoder<SessionRequest>();
+		expect(dec.push('\n\n')).toEqual([]);
+	});
+});