picopilot 0.1.5 → 0.2.1

package/src/cli.test.ts

@@ -0,0 +1,229 @@
+import {mkdtempSync, rmSync, writeFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {z} from 'incur';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {createCli} from './cli.js';
+import {displayModeOf} from './commands/pico8-env.js';
+
+/**
+ * The display mode (ADR-0017) is resolved ONCE, globally, by the root CLI:
+ * `--display` > `PICOPILOT_DISPLAY` > picopilot.json `display` > `auto`. A probe
+ * command mounted on the real CLI reports what a command handler sees.
+ */
+
+let dir: string;
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'picopilot-cli-'));
+});
+afterEach(() => rmSync(dir, {recursive: true, force: true}));
+
+async function probe(
+	argv: string[],
+	env: Record<string, string | undefined> = {},
+	config?: unknown,
+) {
+	const cli = createCli();
+	cli.command('probe-display', {
+		run: (c) => ({display: displayModeOf(c.var)}),
+	});
+	const args = [...argv];
+	if (config !== undefined) {
+		const path = join(dir, 'picopilot.json');
+		writeFileSync(path, JSON.stringify(config));
+		args.push('--config', path);
+	}
+	let stdout = '';
+	let exitCode = 0;
+	await cli.serve([...args, '--json'], {
+		stdout(s) {
+			stdout += s;
+		},
+		exit(code) {
+			exitCode = code;
+		},
+		env,
+	});
+	return {out: JSON.parse(stdout), exitCode};
+}
+
+describe('display mode resolution through the CLI', () => {
+	it('defaults to auto', async () => {
+		expect((await probe(['probe-display'])).out.display).toBe('auto');
+	});
+
+	it('reads picopilot.json "display"', async () => {
+		const {out} = await probe(['probe-display'], {}, {display: 'native'});
+		expect(out.display).toBe('native');
+	});
+
+	it('PICOPILOT_DISPLAY beats picopilot.json', async () => {
+		const {out} = await probe(
+			['probe-display'],
+			{PICOPILOT_DISPLAY: 'xvfb'},
+			{display: 'native'},
+		);
+		expect(out.display).toBe('xvfb');
+	});
+
+	it('--display beats both, before or after the command', async () => {
+		for (const argv of [
+			['--display', 'native', 'probe-display'],
+			['probe-display', '--display', 'native'],
+			['probe-display', '--display=native'],
+		]) {
+			const {out} = await probe(
+				argv,
+				{PICOPILOT_DISPLAY: 'xvfb'},
+				{display: 'xvfb'},
+			);
+			expect(out.display).toBe('native');
+		}
+	});
+
+	it('an invalid PICOPILOT_DISPLAY is an error for a display command, not a silent auto', async () => {
+		const cli = createCli();
+		let stdout = '';
+		let exitCode = 0;
+		await cli.serve(['doctor', '--json'], {
+			stdout(s) {
+				stdout += s;
+			},
+			exit(code) {
+				exitCode = code;
+			},
+			env: {PICOPILOT_DISPLAY: 'xfvb'},
+		});
+		expect(exitCode).not.toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.code).toBe('invalid-display-mode');
+		expect(out.message).toContain('PICOPILOT_DISPLAY');
+	});
+
+	it('an invalid --display is an error for a display command', async () => {
+		const cli = createCli();
+		let stdout = '';
+		let exitCode = 0;
+		await cli.serve(['doctor', '--display', 'bogus', '--json'], {
+			stdout(s) {
+				stdout += s;
+			},
+			exit(code) {
+				exitCode = code;
+			},
+			env: {},
+		});
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('--display');
+	});
+
+	it('a --display with no value is rejected, and does not eat the next flag', async () => {
+		for (const argv of [
+			['doctor', '--display', '--json'],
+			['doctor', '--json', '--display'],
+		]) {
+			const cli = createCli();
+			let stdout = '';
+			let exitCode = 0;
+			await cli.serve(argv, {
+				stdout(s) {
+					stdout += s;
+				},
+				exit(code) {
+					exitCode = code;
+				},
+				env: {},
+			});
+			expect(exitCode, argv.join(' ')).not.toBe(0);
+			// --json still applied: the error envelope is JSON.
+			expect(() => JSON.parse(stdout), argv.join(' ')).not.toThrow();
+		}
+	});
+
+	it('an invalid value does not break commands that never use the display', async () => {
+		const cli = createCli();
+		let stdout = '';
+		let exitCode = 0;
+		await cli.serve(['version', '--json'], {
+			stdout(s) {
+				stdout += s;
+			},
+			exit(code) {
+				exitCode = code;
+			},
+			env: {PICOPILOT_DISPLAY: 'xfvb'},
+		});
+		expect(exitCode).toBe(0);
+		expect(JSON.parse(stdout).name).toBe('picopilot');
+	});
+
+	it('--no-config ignores the picopilot.json display key', async () => {
+		const path = join(dir, 'picopilot.json');
+		writeFileSync(path, JSON.stringify({display: 'native'}));
+		// First load it (so a stale value could leak), then disable config.
+		const cli = createCli();
+		cli.command('probe-display', {
+			run: (c) => ({display: displayModeOf(c.var)}),
+		});
+		const outs: string[] = [];
+		for (const argv of [
+			['probe-display', '--config', path, '--json'],
+			['probe-display', '--no-config', '--json'],
+		]) {
+			let stdout = '';
+			await cli.serve(argv, {
+				stdout(s) {
+					stdout += s;
+				},
+				exit() {},
+				env: {},
+			});
+			outs.push(JSON.parse(stdout).display);
+		}
+		expect(outs).toEqual(['native', 'auto']);
+	});
+
+	it('--config naming a missing file is an error', async () => {
+		const cli = createCli();
+		let stdout = '';
+		let exitCode = 0;
+		await cli.serve(['version', '--config', join(dir, 'nope.json'), '--json'], {
+			stdout(s) {
+				stdout += s;
+			},
+			exit(code) {
+				exitCode = code;
+			},
+			env: {},
+		});
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('not found');
+	});
+
+	it('a per-command config option still loads next to the display key', async () => {
+		// The custom config loader must keep incur's per-command option defaults.
+		const cli = createCli();
+		let seen: unknown;
+		cli.command('probe-opt', {
+			options: z.object({flag: z.boolean().default(false)}),
+			run: (c) => {
+				seen = c.options.flag;
+				return {};
+			},
+		});
+		const path = join(dir, 'picopilot.json');
+		writeFileSync(
+			path,
+			JSON.stringify({
+				display: 'native',
+				commands: {'probe-opt': {options: {flag: true}}},
+			}),
+		);
+		await cli.serve(['probe-opt', '--config', path, '--json'], {
+			stdout() {},
+			exit() {},
+			env: {},
+		});
+		expect(seen).toBe(true);
+	});
+});

package/src/cli.ts

@@ -1,5 +1,9 @@
-import {Cli} from 'incur';
+import {existsSync, readFileSync} from 'node:fs';
+import {homedir} from 'node:os';
+import {join, resolve} from 'node:path';
+import {Cli, z} from 'incur';
 import {registerAudio} from './commands/audio.js';
+import {registerDoctor} from './commands/doctor.js';
 import {registerExport} from './commands/export.js';
 import {registerGfx} from './commands/gfx.js';
 import {registerInit} from './commands/init.js';
@@ -13,8 +17,133 @@ import {registerSfx} from './commands/sfx.js';
 import {registerTokens} from './commands/tokens.js';
 import {registerVerify} from './commands/verify.js';
 import {registerVersion} from './commands/version.js';
+import {
+	DEFAULT_DISPLAY_MODE,
+	DISPLAY_CONFIG_KEY,
+	DISPLAY_ENV_VAR,
+	DISPLAY_MODES,
+	resolveDisplayMode,
+} from './engine/pico8/display.js';
 import {VERSION} from './version.js';
 
+/** The config files picopilot searches (first existing wins), relative to the cwd. */
+const CONFIG_FILES = ['picopilot.json'];
+
+/**
+ * What one `serve` invocation said at the top level, captured BEFORE incur sees
+ * the argv: the `--display` flag (taken out of argv, so it works before or after
+ * the command name and on `--mcp`), and for `--mcp` the config flags. incur's
+ * MCP transport passes no global flags to a tool call and loads no config file,
+ * so picopilot carries both itself.
+ */
+interface Invocation {
+	display?: string;
+	mcp: boolean;
+	/** MCP only: the config tree picopilot loaded itself (undefined = none). */
+	mcpConfig?: Record<string, unknown>;
+}
+
+/**
+ * Removes every `--display <v>` / `--display=<v>` from argv and returns the last
+ * value. A `--display` with no value (last token, or followed by another flag)
+ * stays in argv, so incur rejects it instead of it silently eating the next flag.
+ */
+function takeDisplayFlag(argv: string[]): {argv: string[]; display?: string} {
+	const rest: string[] = [];
+	let display: string | undefined;
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i] as string;
+		const next = argv[i + 1];
+		if (a === '--display' && next !== undefined && !next.startsWith('-')) {
+			display = next;
+			i++;
+		} else if (a.startsWith('--display=') && a.length > '--display='.length) {
+			display = a.slice('--display='.length);
+		} else {
+			rest.push(a);
+		}
+	}
+	return {argv: rest, display};
+}
+
+/** Resolves a config path the way incur does: `~` is the home dir, else relative to the cwd. */
+function resolveConfigPath(path: string): string {
+	return path === '~' || path.startsWith('~/')
+		? join(homedir(), path.slice(1))
+		: resolve(path);
+}
+
+/**
+ * For `--mcp`: the config file incur would have loaded on the CLI. Mirrors
+ * incur's own parsing: `--config <p>` / `--config=<p>` / `--no-config`, the last
+ * one wins, a missing value is an error; else the first existing default file.
+ */
+function loadMcpConfig(argv: string[]): Record<string, unknown> | undefined {
+	let explicit: string | undefined;
+	let disabled = false;
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i] as string;
+		let value: string | undefined;
+		if (a === '--config') value = argv[++i];
+		else if (a.startsWith('--config=')) value = a.slice('--config='.length);
+		else if (a === '--no-config') {
+			explicit = undefined;
+			disabled = true;
+			continue;
+		} else continue;
+		if (value === undefined || value === '') {
+			throw new Error('Missing value for flag: --config');
+		}
+		explicit = value;
+		disabled = false;
+	}
+	if (disabled) return undefined;
+	const sink: {display?: unknown} = {};
+	if (explicit !== undefined) {
+		return loadConfig(resolveConfigPath(explicit), sink);
+	}
+	for (const file of CONFIG_FILES) {
+		const path = resolveConfigPath(file);
+		if (existsSync(path)) return loadConfig(path, sink);
+	}
+	return undefined;
+}
+
+/**
+ * Reads a picopilot.json for incur's config layer AND captures its top-level
+ * {@link DISPLAY_CONFIG_KEY}. incur only maps per-command `options` from the
+ * config file; the display mode is a GLOBAL setting, so the loader hands the
+ * value to the display middleware through `sink`.
+ */
+function loadConfig(
+	path: string | undefined,
+	sink: {display?: unknown},
+): Record<string, unknown> | undefined {
+	sink.display = undefined;
+	if (path === undefined) return undefined;
+	let raw: string;
+	try {
+		raw = readFileSync(path, 'utf8');
+	} catch (e) {
+		// incur only hands the loader an existing file unless --config named one.
+		if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
+			throw new Error(`Config file not found: ${path}`);
+		}
+		throw e;
+	}
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		throw new Error(`Invalid JSON config file: ${path}`);
+	}
+	if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+		throw new Error(`Config file must hold a JSON object: ${path}`);
+	}
+	sink.display = (parsed as Record<string, unknown>)[DISPLAY_CONFIG_KEY];
+	return parsed as Record<string, unknown>;
+}
+
 /**
  * Builds the root picopilot CLI.
  *
@@ -28,6 +157,7 @@ import {VERSION} from './version.js';
  * CLI and drive it with `cli.serve(argv, { stdout, exit, env })` DI overrides.
  */
 export function createCli(): Cli.Cli {
+	const configSink: {display?: unknown} = {};
 	const cli = Cli.create('picopilot', {
 		version: VERSION,
 		description: 'An agent-first toolchain for PICO-8 game development.',
@@ -38,24 +168,106 @@ export function createCli(): Cli.Cli {
 		// Per-cart policy config (e.g. `allowMapOverlap`); precedence argv > config > defaults.
 		config: {
 			flag: 'config',
-			files: ['picopilot.json'],
+			files: CONFIG_FILES,
+			loader: async (path) => loadConfig(path, configSink),
 		},
+		// The display mode (ADR-0017): `--display` (a per-command option on the
+		// commands that use it, also accepted anywhere on the command line and on
+		// `--mcp`) > PICOPILOT_DISPLAY > picopilot.json `display` > auto.
+		env: z.object({
+			[DISPLAY_ENV_VAR]: z
+				.string()
+				.optional()
+				.describe('Display mode: auto | xvfb | native (below --display).'),
+		}),
+		vars: z.object({
+			display: z.enum(DISPLAY_MODES).default(DEFAULT_DISPLAY_MODE),
+			displayError: z.string().optional(),
+			mcpConfig: z.record(z.string(), z.unknown()).optional(),
+		}),
+		mcp: {
+			// One MCP tool per command (incur's default is progressive discovery
+			// behind search/call meta-tools); picopilot's surface is small, and the
+			// skills name commands directly.
+			tools: {discovery: 'direct'},
+		},
+	});
+
+	const invocation: Invocation = {mcp: false};
+
+	cli.use(async (c, next) => {
+		const configured = invocation.mcp
+			? invocation.mcpConfig?.[DISPLAY_CONFIG_KEY]
+			: configSink.display;
+		configSink.display = undefined; // never leak into a later invocation
+		const resolved = resolveDisplayMode({
+			flag: invocation.display,
+			env: (c.env as Record<string, string | undefined>)[DISPLAY_ENV_VAR],
+			config: configured,
+		});
+		if (resolved.ok) {
+			c.set('display', resolved.mode);
+		} else {
+			// Not an error here: only the commands that USE the display mode fail
+			// on a bad value (see resolveCommandDisplay); the rest run as usual.
+			const where =
+				resolved.source === 'flag'
+					? '--display'
+					: resolved.source === 'env'
+						? DISPLAY_ENV_VAR
+						: `picopilot.json "${DISPLAY_CONFIG_KEY}"`;
+			c.set(
+				'displayError',
+				`${where} is "${resolved.value}"; expected one of: ${DISPLAY_MODES.join(', ')}.`,
+			);
+		}
+		if (invocation.mcp && invocation.mcpConfig !== undefined) {
+			c.set('mcpConfig', invocation.mcpConfig);
+		}
+		await next();
 	});
 
-	registerVersion(cli);
-	registerInit(cli);
-	registerGfx(cli);
-	registerTokens(cli);
-	registerLint(cli);
-	registerMinify(cli);
-	registerVerify(cli);
-	registerRun(cli);
-	registerExport(cli);
-	registerServe(cli);
-	registerPlaytest(cli);
-	registerSfx(cli);
-	registerMusic(cli);
-	registerAudio(cli);
-
-	return cli;
+	// Capture the top-level `--display` (and, for `--mcp`, the config) before
+	// incur parses argv; see {@link Invocation}.
+	const serve = cli.serve.bind(cli);
+	cli.serve = async (argv = process.argv.slice(2), options) => {
+		const taken = takeDisplayFlag(argv);
+		invocation.display = taken.display;
+		invocation.mcp = taken.argv.includes('--mcp');
+		invocation.mcpConfig = undefined;
+		if (invocation.mcp) {
+			try {
+				invocation.mcpConfig = loadMcpConfig(taken.argv);
+			} catch (e) {
+				// A broken config must stop the server visibly, not serve without it.
+				process.stderr.write(
+					`picopilot --mcp: ${e instanceof Error ? e.message : String(e)}\n`,
+				);
+				process.exitCode = 1;
+				return;
+			}
+		}
+		return serve(taken.argv, options);
+	};
+
+	// The register* helpers take the untyped Cli: the display var is read through
+	// `displayModeOf`, so they do not depend on this CLI's generics.
+	const root = cli as unknown as Cli.Cli;
+	registerVersion(root);
+	registerDoctor(root);
+	registerInit(root);
+	registerGfx(root);
+	registerTokens(root);
+	registerLint(root);
+	registerMinify(root);
+	registerVerify(root);
+	registerRun(root);
+	registerExport(root);
+	registerServe(root);
+	registerPlaytest(root);
+	registerSfx(root);
+	registerMusic(root);
+	registerAudio(root);
+
+	return root;
 }

package/src/commands/audio.test.ts

@@ -19,7 +19,7 @@ import type {
 	RecordOptions,
 	RunOptions,
 } from '../engine/pico8/index.js';
-import {pico8NotFound} from '../engine/pico8/index.js';
+import {displayUnavailable, pico8NotFound} from '../engine/pico8/index.js';
 import {type Pico8AdapterFactory, registerAudio} from './audio.js';
 
 const HEADER = 'pico-8 cartridge // http://www.pico-8.com\nversion 42\n';
@@ -290,3 +290,66 @@ describe('audio: honest help text (record-based, NOT an offline export)', () =>
 		expect(lower).toContain('offline export');
 	});
 });
+
+describe('audio record/render: headless (ADR-0017)', () => {
+	it('record inlines `#include main.lua` so the harness loads from the temp wavDir', async () => {
+		writeFileSync(cartPath, `${HEADER}__lua__\n#include main.lua\n`);
+		writeFileSync(
+			join(dir, 'main.lua'),
+			'function _update() from_main=1 end\n',
+		);
+		const seen: {record?: RecordOptions} = {};
+		await runAudio(
+			() => stubAdapter(recorded(undefined), seen),
+			['audio', 'record', cartPath, '--json'],
+		);
+		const harness = readFileSync(seen.record!.cartPath, 'utf8');
+		expect(harness).not.toMatch(/#include/);
+		expect(harness).toContain('from_main=1');
+	});
+
+	for (const sub of [
+		['audio', 'record'],
+		['audio', 'render', '--sfx', '0'],
+	]) {
+		it(`${sub.join(' ')}: display-unavailable is a structured error naming the fix`, async () => {
+			const {stdout, exitCode} = await runAudio(
+				() => stubAdapter(displayUnavailable('no display, no Xvfb')),
+				[
+					...sub.slice(0, 2),
+					cartPath,
+					...sub.slice(2),
+					'--json',
+					'--full-output',
+				],
+			);
+			expect(exitCode).not.toBe(0);
+			const out = JSON.parse(stdout);
+			expect(out.error.code).toBe('display-unavailable');
+			expect(out.meta.cta.description).toMatch(/install Xvfb/);
+		});
+	}
+
+	it('a run with no WAV reports noAudioReason, pico8LogTail and the display used', async () => {
+		const {stdout} = await runAudio(
+			() =>
+				stubAdapter({
+					ok: true,
+					value: {
+						wavPath: undefined,
+						printh: '',
+						exitReason: 'timeout',
+						display: 'Xvfb',
+						noWavReason: 'the backstop fired',
+						pico8LogTail: 'could not include main.lua',
+					},
+				}),
+			['audio', 'record', cartPath, '--json'],
+		);
+		const out = JSON.parse(stdout);
+		expect(out.captured).toBe(false);
+		expect(out.display).toBe('Xvfb');
+		expect(out.noAudioReason).toBe('the backstop fired');
+		expect(out.pico8LogTail).toContain('main.lua');
+	});
+});