picopilot 0.1.5 → 0.2.1

package/src/mcp.process.test.ts

@@ -0,0 +1,219 @@
+import {type ChildProcess, spawn} from 'node:child_process';
+import {mkdtempSync, rmSync, writeFileSync} from 'node:fs';
+import {createRequire} from 'node:module';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+
+/**
+ * picopilot as an MCP server (`picopilot --mcp`), end to end over stdio. incur's
+ * MCP transport passes no global flags to a tool call and loads no config file,
+ * so these prove picopilot closes those gaps itself: the server's own
+ * `--display` / `--config`, picopilot.json in the server's cwd, and a per-call
+ * `display` argument (ADR-0017).
+ */
+
+const tsx = createRequire(import.meta.url).resolve('tsx');
+const bin = new URL('./bin.ts', import.meta.url).pathname;
+
+let dir: string;
+let child: ChildProcess | undefined;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'picopilot-mcp-'));
+});
+afterEach(() => {
+	child?.kill('SIGKILL');
+	child = undefined;
+	rmSync(dir, {recursive: true, force: true});
+});
+
+/** Starts `picopilot --mcp ...` in `dir` and returns a JSON-RPC caller. */
+async function mcp(argv: string[] = [], env: NodeJS.ProcessEnv = {}) {
+	const proc = spawn(
+		process.execPath,
+		['--import', tsx, bin, '--mcp', ...argv],
+		{
+			cwd: dir,
+			// No PICO-8 / shrinko on PATH: doctor's probes fail fast.
+			env: {PATH: '/nonexistent', HOME: dir, ...env},
+			stdio: ['pipe', 'pipe', 'pipe'],
+		},
+	);
+	child = proc;
+	const waiting = new Map<number, (msg: any) => void>();
+	let buf = '';
+	proc.stdout!.setEncoding('utf8');
+	proc.stdout!.on('data', (chunk: string) => {
+		buf += chunk;
+		let nl: number;
+		while ((nl = buf.indexOf('\n')) >= 0) {
+			const line = buf.slice(0, nl).trim();
+			buf = buf.slice(nl + 1);
+			if (line === '') continue;
+			const msg = JSON.parse(line);
+			if (typeof msg.id === 'number') waiting.get(msg.id)?.(msg);
+		}
+	});
+	let nextId = 1;
+	const request = (method: string, params: unknown) =>
+		new Promise<any>((resolve) => {
+			const id = nextId++;
+			waiting.set(id, resolve);
+			proc.stdin!.write(
+				`${JSON.stringify({jsonrpc: '2.0', id, method, params})}\n`,
+			);
+		});
+	await request('initialize', {
+		protocolVersion: '2025-06-18',
+		capabilities: {},
+		clientInfo: {name: 'test', version: '0'},
+	});
+	proc.stdin!.write(
+		`${JSON.stringify({jsonrpc: '2.0', method: 'notifications/initialized'})}\n`,
+	);
+	const call = async (name: string, args: Record<string, unknown> = {}) => {
+		const res = await request('tools/call', {name, arguments: args});
+		const text = res.result?.content?.[0]?.text ?? '';
+		return {isError: res.result?.isError === true, text};
+	};
+	return {request, call};
+}
+
+async function doctorMode(
+	session: Awaited<ReturnType<typeof mcp>>,
+	args: Record<string, unknown> = {},
+): Promise<string> {
+	const {text, isError} = await session.call('doctor', args);
+	expect(isError).toBe(false);
+	return JSON.parse(text).display.mode;
+}
+
+describe('picopilot --mcp: the display mode reaches tool calls', () => {
+	it('defaults to auto', async () => {
+		expect(await doctorMode(await mcp())).toBe('auto');
+	}, 30_000);
+
+	it('the server flag `--mcp --display xvfb` applies to every call', async () => {
+		expect(await doctorMode(await mcp(['--display', 'xvfb']))).toBe('xvfb');
+	}, 30_000);
+
+	it('picopilot.json "display" in the server cwd applies (incur loads no config under --mcp)', async () => {
+		writeFileSync(
+			join(dir, 'picopilot.json'),
+			JSON.stringify({display: 'native'}),
+		);
+		expect(await doctorMode(await mcp())).toBe('native');
+	}, 30_000);
+
+	it('the server flag beats PICOPILOT_DISPLAY, which beats picopilot.json', async () => {
+		writeFileSync(
+			join(dir, 'picopilot.json'),
+			JSON.stringify({display: 'native'}),
+		);
+		expect(await doctorMode(await mcp([], {PICOPILOT_DISPLAY: 'xvfb'}))).toBe(
+			'xvfb',
+		);
+		child?.kill('SIGKILL');
+		expect(
+			await doctorMode(
+				await mcp(['--display', 'auto'], {PICOPILOT_DISPLAY: 'xvfb'}),
+			),
+		).toBe('auto');
+	}, 30_000);
+
+	it('--no-config on the server ignores picopilot.json', async () => {
+		writeFileSync(
+			join(dir, 'picopilot.json'),
+			JSON.stringify({display: 'native'}),
+		);
+		expect(await doctorMode(await mcp(['--no-config']))).toBe('auto');
+	}, 30_000);
+
+	it('--config resolves like incur: `~` is the home dir, the last config flag wins', async () => {
+		writeFileSync(
+			join(dir, 'custom.json'),
+			JSON.stringify({display: 'native'}),
+		);
+		expect(await doctorMode(await mcp(['--config', '~/custom.json']))).toBe(
+			'native',
+		);
+		child?.kill('SIGKILL');
+		expect(
+			await doctorMode(await mcp(['--no-config', '--config=custom.json'])),
+		).toBe('native');
+	}, 30_000);
+
+	it('a broken config stops the server visibly instead of serving without it', async () => {
+		writeFileSync(join(dir, 'picopilot.json'), '{not json');
+		const proc = spawn(process.execPath, ['--import', tsx, bin, '--mcp'], {
+			cwd: dir,
+			env: {PATH: '/nonexistent', HOME: dir},
+			stdio: ['pipe', 'pipe', 'pipe'],
+		});
+		child = proc;
+		let stderr = '';
+		proc.stderr!.setEncoding('utf8');
+		proc.stderr!.on('data', (s: string) => {
+			stderr += s;
+		});
+		const code = await new Promise<number | null>((resolve) =>
+			proc.once('exit', resolve),
+		);
+		expect(code).toBe(1);
+		expect(stderr).toContain('Invalid JSON config file');
+	}, 30_000);
+
+	it('a per-call `display` argument beats the server flag', async () => {
+		const session = await mcp(['--display', 'xvfb']);
+		expect(await doctorMode(session, {display: 'native'})).toBe('native');
+	}, 30_000);
+
+	it('the recording tools expose `display` as an input', async () => {
+		const session = await mcp();
+		const list = await session.request('tools/list', {});
+		for (const name of ['audio_record', 'audio_render', 'run', 'doctor']) {
+			const tool = list.result.tools.find(
+				(t: {name: string}) => t.name === name,
+			);
+			expect(tool?.inputSchema?.properties?.display, name).toBeDefined();
+		}
+	}, 30_000);
+});
+
+describe('picopilot --mcp: per-command picopilot.json options still apply', () => {
+	/** A cart whose sprite 130 (shared map region) already holds a pixel. */
+	function cartWithSprite130Data(): string {
+		const rows = Array.from({length: 128}, () => '0'.repeat(128));
+		rows[64] = `${'0'.repeat(16)}7${'0'.repeat(111)}`;
+		const path = join(dir, 'main.p8');
+		writeFileSync(
+			path,
+			`pico-8 cartridge // http://www.pico-8.com\nversion 42\n__lua__\n__gfx__\n${rows.join('\n')}\n`,
+		);
+		return path;
+	}
+	const grid = Array.from({length: 8}, () => '33333333').join('\n');
+
+	it('gfx set is refused without authorisation, allowed by allowMapOverlap in picopilot.json', async () => {
+		const cart = cartWithSprite130Data();
+		const refused = await (
+			await mcp()
+		).call('gfx_set', {sprite: 130, grid, cart});
+		expect(refused.isError).toBe(true);
+		expect(refused.text).toContain('refusing');
+		child?.kill('SIGKILL');
+
+		writeFileSync(
+			join(dir, 'picopilot.json'),
+			JSON.stringify({
+				commands: {gfx: {commands: {set: {options: {allowMapOverlap: true}}}}},
+			}),
+		);
+		const allowed = await (
+			await mcp()
+		).call('gfx_set', {sprite: 130, grid, cart});
+		expect(allowed.isError).toBe(false);
+		expect(JSON.parse(allowed.text).overwroteSharedData).toBe(true);
+	}, 30_000);
+});

package/src/skills/picopilot-audio/SKILL.md

@@ -46,11 +46,7 @@ These steps are wired as CTAs (a merged SFX or song points you at `verify` then
 
 ## `audio render` / `audio record`: get a WAV by RECORDING (ADR-0009)
 
-PICO-8 has NO working offline WAV export (it SIGFPEs upstream), so picopilot gets
-audio-to-WAV the only way that works: by RECORDING a running session
-(`extcmd("audio_rec")`/`audio_end`). Two commands, both PICO-8-gated and both
-REAL-TIME recordings that need a real audio+video session (a developer machine,
-NOT headless CI), NOT deterministic offline exports:
+PICO-8 has NO working offline WAV export (it SIGFPEs upstream), so picopilot gets audio-to-WAV the only way that works: by RECORDING a running session (`extcmd("audio_rec")`/`audio_end`). Two commands, both PICO-8-gated and both REAL-TIME recordings of playback, NOT deterministic offline exports. They work headless (no display, no sound card): PICO-8 records its own mixer, not the audio device, and when there is no display picopilot runs the session on a private virtual display by itself (ADR-0017). You do not need to do anything for that.
 
 - **`picopilot audio render`** injects a THROWAWAY play-harness for a chosen
   target and records it, so you write NO playback code. Pick the target with
@@ -68,9 +64,9 @@ The WAV goes to an isolated dir (`--wav-dir`, default a temp dir), never
 `~/Desktop` or the carts root (the `audio_end(1)`-saves-to-the-current-folder
 trap; picopilot steers it with PICO-8's `root_path`). PICO-8 absent -> a
 structured `pico8-not-found` (remedy `set PICO8_PATH or install PICO-8`), never a
-crash. On a headless machine the recording succeeds but captures NO audio
-(`captured:false` + a nudge to run on a machine with a display + audio device):
-that is honest, not a failure of the recipe.
+crash.
+
+When a recording produces no WAV (`captured:false`), the result says why: `noAudioReason` (the backstop fired before the recorder finished, PICO-8 exited early, or the capture was empty) and `pico8LogTail` (the end of PICO-8's own log, where load errors show up). Read both before retrying; a cart that fails to load never reaches the end of the recording, so run `picopilot verify` on it. If the machine has no display AND no Xvfb, the command fails up front with `display-unavailable`, whose message names the package to install; `picopilot doctor` reports the same thing before you try.
 
 ## `sfx from-mml`: one MML string -> one SFX slot
 

package/src/skills/picopilot-overview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: picopilot-overview
-description: Start here for any PICO-8 cart built with picopilot. The #include discipline (edit main.lua, never the .p8 binary sections), the per-iteration verify loop, and which deeper skill to load for code, art, audio, or debugging. Use when you open a picopilot cart folder or run picopilot init.
+description: Start here for any PICO-8 cart built with picopilot. Call picopilot doctor first to learn what this machine can do (everything works headless), then the #include discipline (edit main.lua, never the .p8 binary sections), the per-iteration verify loop, and which deeper skill to load for code, art, audio, or debugging. Use when you open a picopilot cart folder or run picopilot init.
 ---
 
 # picopilot overview
@@ -13,6 +13,14 @@ acceptance gate, so you can build a PICO-8 game and self-correct.
 Load this skill first. Then load the group skill for whatever you are doing:
 `picopilot-code`, `picopilot-art`, `picopilot-audio`, or `picopilot-debug`.
 
+## First on a new machine: `picopilot doctor`
+
+Run `picopilot doctor` before anything else on a machine you have not used yet. It reports what THIS machine can do: whether PICO-8 is found and actually runs (with its version), whether shrinko8 is found, how a PICO-8 audio session would get a display, and the resulting `available` / `unavailable` command lists (each unavailable command says what it is missing). Plan from that list instead of discovering limits by failing.
+
+Every picopilot command works on a machine with no display and no sound card (a server, CI, an agent sandbox). Screenshots, `playtest` and `export` run PICO-8 headless. Audio recording (`audio render`, `audio record`, `run --record-audio`) needs a real PICO-8 session with a window, and picopilot provides one by itself: with the default display mode `auto`, when there is no display it starts a private virtual display for that recording and removes it afterwards. You do not need to set anything up. Only if `doctor` lists the audio commands as unavailable with `missing: display` (or a recording fails with `display-unavailable`) does the machine lack Xvfb; the error names the install command to suggest to the human.
+
+The display mode can be forced with `--display xvfb` (always virtual) or `--display native` (use the current display as-is), also settable as `PICOPILOT_DISPLAY` or `"display"` in `picopilot.json`. Through MCP, the same `display` is an argument of the `run`, `audio_record`, `audio_render` and `doctor` tools. Leave it at `auto` unless a human asks otherwise.
+
 ## The #include discipline (how every picopilot cart is laid out)
 
 - `main.p8` is the cart. Its `__lua__` section is a single line: `#include main.lua`.