picopilot 0.2.0 → 0.2.1

package/src/commands/pico8-env.ts

@@ -1,6 +1,7 @@
 import {z} from 'incur';
 import {
 	DEFAULT_DISPLAY_MODE,
+	DISPLAY_MODES,
 	type DisplayMode,
 	isDisplayMode,
 	type Pico8Adapter,
@@ -72,9 +73,23 @@ export function createShellAdapterFactory(
 }
 
 /**
- * The display mode a command handler sees. The root middleware in `createCli`
- * resolves it (flag > env > config > default) into the `display` var; a command
- * mounted on a bare CLI (some tests) has no var and gets the default.
+ * The `display` option of the commands that use the display mode (`run`,
+ * `audio record`, `audio render`, `doctor`). A per-command option, not an incur
+ * global, because incur's MCP transport passes no globals: as an option it is
+ * also an argument of the MCP tool. Unset = the invocation-level value.
+ */
+export const DISPLAY_OPTION = z
+	.enum(DISPLAY_MODES)
+	.optional()
+	.describe(
+		'How a PICO-8 -run session (audio recording) gets a display: auto (default: a private virtual display only when there is none), xvfb (always virtual), native (as-is). Else PICOPILOT_DISPLAY, else picopilot.json "display".',
+	);
+
+/**
+ * The display mode the root middleware in `createCli` resolved for this
+ * invocation (top-level `--display` > PICOPILOT_DISPLAY > picopilot.json >
+ * auto). A command mounted on a bare CLI (some tests) has no var and gets the
+ * default.
  */
 export function displayModeOf(vars: unknown): DisplayMode {
 	const value =
@@ -84,6 +99,59 @@ export function displayModeOf(vars: unknown): DisplayMode {
 	return isDisplayMode(value) ? value : DEFAULT_DISPLAY_MODE;
 }
 
+/**
+ * The display mode a command uses: its own `display` option (a per-call MCP
+ * argument) wins, else the invocation-level value. An invalid invocation-level
+ * value (a typo in PICOPILOT_DISPLAY, say) is an `invalid-display-mode` error
+ * here, so only the commands that use the mode fail on it.
+ */
+export function resolveCommandDisplay(
+	option: DisplayMode | undefined,
+	vars: unknown,
+):
+	| {ok: true; mode: DisplayMode}
+	| {
+			ok: false;
+			error: {code: 'invalid-display-mode'; message: string; exitCode: number};
+	  } {
+	if (option !== undefined) return {ok: true, mode: option};
+	const problem =
+		vars !== null && typeof vars === 'object'
+			? (vars as {displayError?: unknown}).displayError
+			: undefined;
+	if (typeof problem === 'string') {
+		return {
+			ok: false,
+			error: {code: 'invalid-display-mode', message: problem, exitCode: 1},
+		};
+	}
+	return {ok: true, mode: displayModeOf(vars)};
+}
+
+/**
+ * Under `--mcp`, incur loads no config file, so picopilot loads picopilot.json
+ * itself and hands the tree to commands as the `mcpConfig` var. A command whose
+ * option can come from the config reads its fallback here (CLI runs get it from
+ * incur as the option's default, so this is undefined there).
+ */
+export function mcpConfigOption(
+	vars: unknown,
+	commandPath: readonly string[],
+	key: string,
+): unknown {
+	let node: unknown =
+		vars !== null && typeof vars === 'object'
+			? (vars as {mcpConfig?: unknown}).mcpConfig
+			: undefined;
+	for (const part of commandPath) {
+		node = (node as {commands?: Record<string, unknown>} | undefined)
+			?.commands?.[part];
+	}
+	return (node as {options?: Record<string, unknown>} | undefined)?.options?.[
+		key
+	];
+}
+
 /**
  * The `error(...)` payload for a `display-unavailable` result (ADR-0017): the
  * session needs a display, there is none, and no Xvfb is installed to provide a

package/src/commands/run.ts

@@ -16,10 +16,11 @@ import {
 import {makeReadInclude} from './cart-includes.js';
 import {
 	createShellAdapterFactory,
-	displayModeOf,
+	DISPLAY_OPTION,
 	displayUnavailableError,
 	PICO8_ENV,
 	pico8NotFoundError,
+	resolveCommandDisplay,
 	type Pico8AdapterFactory,
 } from './pico8-env.js';
 
@@ -96,6 +97,7 @@ export function registerRun(
 				.describe(
 					'One-shot scripted input passed as `-p` (the cart reads it via stat(6)) for automated playtests.',
 				),
+			display: DISPLAY_OPTION,
 			recordAudio: z
 				.boolean()
 				.default(false)
@@ -183,8 +185,12 @@ export function registerRun(
 					: mkdtempSync(join(tmpdir(), 'picopilot-run-'));
 			if (!existsSync(shotDir)) mkdirSync(shotDir, {recursive: true});
 
+			// The display mode only matters to the --record-audio (-run) pass, so a
+			// bad PICOPILOT_DISPLAY only fails a run that records.
+			const display = resolveCommandDisplay(options.display, vars);
+			if (options.recordAudio && !display.ok) return error(display.error);
 			const adapter = adapterFactory(env as NodeJS.ProcessEnv, {
-				display: displayModeOf(vars),
+				display: display.ok ? display.mode : 'auto',
 			});
 			const result = await adapter.run({
 				cartPath,

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-overview/SKILL.md

@@ -19,7 +19,7 @@ Run `picopilot doctor` before anything else on a machine you have not used yet.
 
 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` (when picopilot runs as an MCP server, only `PICOPILOT_DISPLAY` in the server's environment applies). Leave it at `auto` unless a human asks otherwise.
+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)