picopilot 0.0.0 → 0.1.0

package/src/engine/pico8/sentinel.ts

@@ -0,0 +1,93 @@
+import {DONE_SENTINEL} from './adapter.js';
+
+/**
+ * The pure sentinel-watch core (ADR-0006): scan a stdout stream line by line and
+ * decide WHEN to kill PICO-8. A cart cannot self-quit the app, so it signals
+ * "done" by printing a sentinel line via `printh`; the launcher kills the moment
+ * it matches. This is strictly better than a blind timeout (no guessing the
+ * duration), which stays only as a backstop in the shell layer.
+ *
+ * Kept PURE and stream-shaped on purpose: it is the load-bearing logic and the
+ * one piece testable in CI WITHOUT the paid PICO-8 binary. The shell layer feeds
+ * it real child stdout; a test feeds it a fake array of lines.
+ */
+
+/**
+ * Splits a raw stdout chunk into complete lines plus a trailing remainder,
+ * so sentinel matching works on whole lines even when the OS delivers stdout in
+ * arbitrary chunks. The remainder (an unterminated final line) is carried to the
+ * next chunk by the caller.
+ *
+ * Handles both `\n` and `\r\n`; the `\r` is stripped so a sentinel matches
+ * regardless of platform line endings.
+ */
+export function splitLines(chunk: string): {lines: string[]; rest: string} {
+	const parts = chunk.split('\n');
+	const rest = parts.pop() ?? '';
+	return {
+		lines: parts.map((l) => (l.endsWith('\r') ? l.slice(0, -1) : l)),
+		rest,
+	};
+}
+
+/**
+ * Scans `lines` for the `sentinel` and reports whether it appeared and at which
+ * index. A match means the caller should kill PICO-8 now (exit reason
+ * `sentinel`); no match means keep streaming until the backstop or a natural
+ * exit. The comparison is an EXACT line match (the cart prints the sentinel on
+ * its own line), so incidental substrings in other output never trip it.
+ */
+export function findSentinel(
+	lines: readonly string[],
+	sentinel: string = DONE_SENTINEL,
+): {matched: boolean; index: number} {
+	const index = lines.findIndex((l) => l === sentinel);
+	return {matched: index !== -1, index};
+}
+
+/**
+ * A stateful line accumulator for a streaming run: feed it raw stdout chunks;
+ * it buffers partial lines, exposes the complete lines seen so far, and reports
+ * the moment the sentinel is matched. This is the exact glue the shell adapter
+ * drives (feed chunks, stop on `sentinelSeen`), and a test drives it with
+ * synthetic chunks to assert prompt-kill vs. no-match without a real process.
+ */
+export class SentinelWatcher {
+	private buffer = '';
+	private readonly linesSeen: string[] = [];
+	private matched = false;
+
+	constructor(private readonly sentinel: string = DONE_SENTINEL) {}
+
+	/**
+	 * Feeds one raw stdout chunk. Returns `true` the first time the sentinel is
+	 * matched (the caller should kill PICO-8 then); once matched it stays matched.
+	 */
+	push(chunk: string): boolean {
+		const {lines, rest} = splitLines(this.buffer + chunk);
+		this.buffer = rest;
+		for (const line of lines) {
+			this.linesSeen.push(line);
+			if (line === this.sentinel) this.matched = true;
+		}
+		return this.matched;
+	}
+
+	/** Whether the sentinel has been seen on a complete line so far. */
+	get sentinelSeen(): boolean {
+		return this.matched;
+	}
+
+	/**
+	 * The full captured stdout as text (complete lines plus any unterminated
+	 * trailing buffer), for the run report's `printh`. The sentinel line itself
+	 * is KEPT (it is real cart output); the command decides whether to show it.
+	 */
+	get text(): string {
+		const all =
+			this.buffer.length > 0
+				? [...this.linesSeen, this.buffer]
+				: this.linesSeen;
+		return all.join('\n');
+	}
+}

package/src/engine/pico8/session-daemon-entry.ts

@@ -0,0 +1,12 @@
+/**
+ * The detached daemon process ENTRY (ADR-0011, prd US #6). `playtest start`
+ * spawns this file (via `process.execPath [+ execArgv] <this> <configJson>`, so
+ * it re-uses the exact loader the parent ran under, dev `tsx` or built `dist`) as
+ * a DETACHED background process that owns the live driven PICO-8 for the session's
+ * lifetime. It just decodes its JSON config and hands off to {@link daemonMain};
+ * all the logic lives in `session-daemon-main.ts` (so it stays unit-testable).
+ */
+
+import {daemonMain} from './session-daemon-main.js';
+
+daemonMain(process.argv.slice(2));

package/src/engine/pico8/session-daemon-main.ts

@@ -0,0 +1,98 @@
+/**
+ * The playtest session DAEMON ENTRYPOINT (ADR-0011, prd US #6): the small
+ * detached process `playtest start` spawns to OWN a live driven PICO-8 for a
+ * session's lifetime. It is invoked via the hidden `playtest __daemon` verb (so it
+ * re-uses the exact same executable/loader the parent ran under, dev `tsx` or
+ * built `dist`), reads its config from JSON on argv, spawns PICO-8 on the
+ * throwaway driven cart with a LIVE stdin, and hands the process to
+ * {@link serveSession} to answer verbs over the session socket.
+ *
+ * PICO-8 ABSENT: the spawn ENOENTs, so the daemon writes a `pico8-not-found`
+ * marker file into the session dir and exits; the `start` client polls for either
+ * the socket (ready) or that marker (absent) and maps the marker to the same
+ * structured `pico8-not-found` boundary as `run`/`audio render`. This keeps the
+ * absent path structured WITHOUT the parent ever launching PICO-8 itself (the
+ * `pico8 --help` footgun is never touched).
+ */
+
+import {writeFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {pico8NotFound} from './adapter.js';
+import {serveSession} from './session-daemon.js';
+import {spawnRunner, pico8Candidates, withPico8Home} from './shell.js';
+import type {SessionPaths} from './supervisor.js';
+
+/** The marker file the daemon writes into the session dir when PICO-8 is absent. */
+export const PICO8_NOT_FOUND_MARKER = 'pico8-not-found' as const;
+
+/** The daemon's launch config, passed as a single JSON argument. */
+export interface DaemonConfig {
+	readonly id: string;
+	readonly paths: SessionPaths;
+	/** Absolute path to the throwaway driven cart to run live. */
+	readonly cartPath: string;
+	/** The screenshot basename the driven cart names each SHOT. */
+	readonly shotBasename: string;
+	/** Idle-reap window in ms. */
+	readonly idleTimeoutMs: number;
+	/** Per-command ACK deadline in ms. */
+	readonly ackTimeoutMs: number;
+}
+
+/**
+ * Runs the daemon from its JSON config: spawns PICO-8 live on the driven cart and
+ * serves the session, or writes the pico8-not-found marker and exits on ENOENT.
+ * Exported so a test can drive it with an injected spawner (no real binary).
+ */
+export function runDaemon(
+	config: DaemonConfig,
+	env: NodeJS.ProcessEnv = process.env,
+	spawn = spawnRunner,
+): void {
+	const [file] = pico8Candidates(env) as [string, ...string[]];
+	// Live session: `-desktop <shotDir>` for SHOT captures, `-x` headless, stdin
+	// piped so the daemon can send fixed-size command blocks per verb.
+	const args = ['-desktop', config.paths.shotDir, '-x', config.cartPath];
+	// `-home <isolated>` so PICO-8's config/data tree lands in a throwaway dir, not
+	// the caller's CWD (matches the shell adapter's spawn sites).
+	const proc = spawn(file, withPico8Home(args), env, {stdin: true});
+
+	// A spawn ENOENT means PICO-8 is absent (a bad PICO8_PATH surfaces the same
+	// way): leave the structured marker the `start` client polls for, then exit.
+	// This can only happen at spawn time (a launched binary does not ENOENT later),
+	// so it is unambiguously the absent boundary, not a mid-session fault.
+	proc.onError((err) => {
+		if (err.code === 'ENOENT') {
+			writeFileSync(
+				join(config.paths.dir, PICO8_NOT_FOUND_MARKER),
+				JSON.stringify(pico8NotFound()),
+			);
+			process.exit(0);
+		}
+		process.exit(1);
+	});
+
+	serveSession({
+		id: config.id,
+		paths: config.paths,
+		process: proc,
+		shotBasename: config.shotBasename,
+		idleTimeoutMs: config.idleTimeoutMs,
+		ackTimeoutMs: config.ackTimeoutMs,
+		onExit: () => process.exit(0),
+	});
+}
+
+/**
+ * The daemon process main: reads the JSON config from `argv[0]` and runs. Called
+ * by the hidden `playtest __daemon <configJson>` verb in a detached child.
+ */
+export function daemonMain(argv: readonly string[]): void {
+	const raw = argv[0];
+	if (raw === undefined) {
+		process.stderr.write('playtest daemon: missing config\n');
+		process.exit(2);
+	}
+	const config = JSON.parse(raw) as DaemonConfig;
+	runDaemon(config);
+}

package/src/engine/pico8/session-daemon.test.ts

@@ -0,0 +1,212 @@
+import {existsSync, mkdtempSync, readFileSync, rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {ACK, OPCODE} from './drive.js';
+import {runDaemon, PICO8_NOT_FOUND_MARKER} from './session-daemon-main.js';
+import {SessionClient, serveSession, sessionExists} from './session-daemon.js';
+import type {Pico8Process, SpawnRunner} from './shell.js';
+import {SessionRegistry, type SessionPaths} from './supervisor.js';
+
+/**
+ * The session DAEMON dispatch is CI-tested over a REAL Unix socket but a FAKE
+ * driven process (no paid binary): a client verb round-trips through the daemon
+ * to the handshake and back. The pico8-not-found marker path (start with PICO-8
+ * absent) and the idle-reap are asserted too. A live end-to-end session (real
+ * PICO-8) is the manual/opt-in tier.
+ */
+
+/** A fake driven process the test drives via ACK emission. */
+class FakeDriven implements Pico8Process {
+	private stdoutCb: (c: string) => void = () => {};
+	private closeCb: (code: number | null) => void = () => {};
+	private errorCb: (e: NodeJS.ErrnoException) => void = () => {};
+	killed = false;
+	writes: Uint8Array[] = [];
+	onStdout(cb: (c: string) => void): void {
+		this.stdoutCb = cb;
+	}
+	onClose(cb: (code: number | null) => void): void {
+		this.closeCb = cb;
+	}
+	onError(cb: (e: NodeJS.ErrnoException) => void): void {
+		this.errorCb = cb;
+	}
+	writeStdin(bytes: Uint8Array): void {
+		// Auto-ACK: the fake cart acks the command it was just handed, so the daemon
+		// round-trip completes deterministically (the ack CONTENT is the contract).
+		this.writes.push(bytes);
+		const op = bytes[0];
+		queueMicrotask(() => {
+			if (op === OPCODE.input) this.stdoutCb(`${ACK.input}\n`);
+			else if (op === OPCODE.step) this.stdoutCb(`${ACK.stepDone}\n`);
+			else if (op === OPCODE.shot) this.stdoutCb(`${ACK.shot}\n`);
+		});
+	}
+	kill(): void {
+		this.killed = true;
+	}
+	/** Simulate PICO-8 exiting mid-session. */
+	die(): void {
+		this.closeCb(0);
+	}
+}
+
+let base: string;
+let registry: SessionRegistry;
+let paths: SessionPaths;
+const daemons: {close: () => void}[] = [];
+
+beforeEach(() => {
+	base = mkdtempSync(join(tmpdir(), 'pp-daemon-'));
+	registry = new SessionRegistry(base);
+	paths = registry.create('run1');
+});
+
+afterEach(() => {
+	for (const d of daemons.splice(0)) d.close();
+	rmSync(base, {recursive: true, force: true});
+});
+
+function startFakeDaemon(proc: FakeDriven, idleTimeoutMs?: number) {
+	const d = serveSession({
+		id: 'run1',
+		paths,
+		process: proc,
+		shotBasename: 'play',
+		idleTimeoutMs,
+	});
+	daemons.push(d);
+	return d;
+}
+
+/** Waits until the daemon's socket is listening (its readiness signal). */
+async function waitSocket(): Promise<void> {
+	for (let i = 0; i < 200; i++) {
+		if (sessionExists(paths)) return;
+		await new Promise((r) => setTimeout(r, 5));
+	}
+	throw new Error('socket never appeared');
+}
+
+describe('session daemon: verb round-trip over the socket (fake process)', () => {
+	it('step advances frames and returns the structured result', async () => {
+		startFakeDaemon(new FakeDriven());
+		await waitSocket();
+		const client = new SessionClient(paths.socket);
+		const res = await client.send({verb: 'step', frames: 5});
+		expect(res.ok).toBe(true);
+		if (res.ok) {
+			expect(res.value.frame).toBe(5);
+			expect(res.value.ack).toBe(ACK.stepDone);
+		}
+	});
+
+	it('a large step is issued as repeated <=255 sub-steps (exact + lossless)', async () => {
+		const proc = new FakeDriven();
+		startFakeDaemon(proc);
+		await waitSocket();
+		const res = await new SessionClient(paths.socket).send({
+			verb: 'step',
+			frames: 600,
+		});
+		expect(res.ok && res.value.frame).toBe(600);
+		// 600 = 255 + 255 + 90 -> three STEP blocks written.
+		expect(proc.writes.length).toBe(3);
+	});
+
+	it('status reports alive + the frame count without stepping', async () => {
+		startFakeDaemon(new FakeDriven());
+		await waitSocket();
+		const res = await new SessionClient(paths.socket).send({verb: 'status'});
+		expect(res.ok && res.value.alive).toBe(true);
+		expect(res.ok && res.value.frame).toBe(0);
+	});
+
+	it('stop returns a clean final response then reaps the socket', async () => {
+		startFakeDaemon(new FakeDriven());
+		await waitSocket();
+		const res = await new SessionClient(paths.socket).send({verb: 'stop'});
+		expect(res.ok && res.value.alive).toBe(false);
+		// After stop the socket is gone (the session is torn down).
+		for (let i = 0; i < 100 && sessionExists(paths); i++) {
+			await new Promise((r) => setTimeout(r, 5));
+		}
+		expect(sessionExists(paths)).toBe(false);
+	});
+
+	it('a dead process surfaces process-dead on the next verb (not a hang)', async () => {
+		const proc = new FakeDriven();
+		startFakeDaemon(proc);
+		await waitSocket();
+		// Kill the fake mid-life: emit a close so the session marks itself dead.
+		proc.die();
+		const res = await new SessionClient(paths.socket).send({
+			verb: 'step',
+			frames: 1,
+		});
+		expect(res.ok).toBe(false);
+		if (!res.ok) expect(res.code).toBe('playtest-session-process-dead');
+	});
+});
+
+describe('session daemon: orphan idle-reap', () => {
+	it('tears the session down after the idle window with no verbs', async () => {
+		const proc = new FakeDriven();
+		startFakeDaemon(proc, 40); // tiny idle window
+		await waitSocket();
+		for (let i = 0; i < 100 && sessionExists(paths); i++) {
+			await new Promise((r) => setTimeout(r, 5));
+		}
+		expect(sessionExists(paths)).toBe(false);
+		expect(proc.killed).toBe(true); // the live process was reaped
+	});
+});
+
+describe('runDaemon: PICO-8 absent -> structured marker (start absent path)', () => {
+	it('writes the pico8-not-found marker on spawn ENOENT (no hang)', async () => {
+		let exited = false;
+		const realExit = process.exit;
+		// runDaemon calls process.exit on ENOENT; stub it so the test survives.
+		(process as {exit: unknown}).exit = ((): never => {
+			exited = true;
+			return undefined as never;
+		}) as typeof process.exit;
+
+		const enoentSpawn: SpawnRunner = () => {
+			const proc: Pico8Process = {
+				onStdout() {},
+				onClose() {},
+				onError(cb) {
+					const err = new Error('enoent') as NodeJS.ErrnoException;
+					err.code = 'ENOENT';
+					queueMicrotask(() => cb(err));
+				},
+				kill() {},
+				writeStdin() {},
+			};
+			return proc;
+		};
+		try {
+			runDaemon(
+				{
+					id: 'run1',
+					paths,
+					cartPath: join(paths.dir, 'driven.p8'),
+					shotBasename: 'play',
+					idleTimeoutMs: 1000,
+					ackTimeoutMs: 1000,
+				},
+				{},
+				enoentSpawn,
+			);
+			await new Promise((r) => setTimeout(r, 20));
+			const markerPath = join(paths.dir, PICO8_NOT_FOUND_MARKER);
+			expect(existsSync(markerPath)).toBe(true);
+			expect(readFileSync(markerPath, 'utf8')).toContain('pico8-not-found');
+			expect(exited).toBe(true);
+		} finally {
+			(process as {exit: unknown}).exit = realExit;
+		}
+	});
+});