picopilot 0.1.4 → 0.2.0

package/src/cli.ts

@@ -1,5 +1,7 @@
-import {Cli} from 'incur';
+import {readFileSync} from 'node:fs';
+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 +15,58 @@ 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 commands that use the display mode (they start a `-run` session, or report on it). */
+const DISPLAY_COMMANDS: ReadonlySet<string> = new Set([
+	'run',
+	'audio record',
+	'audio render',
+	'doctor',
+]);
+
+/**
+ * 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 +80,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.',
@@ -39,23 +92,76 @@ export function createCli(): Cli.Cli {
 		config: {
 			flag: 'config',
 			files: ['picopilot.json'],
+			loader: async (path) => loadConfig(path, configSink),
 		},
+		// The display mode (ADR-0017) is global: it applies to every command that
+		// starts a PICO-8 `-run` session. Precedence: --display > PICOPILOT_DISPLAY
+		// > picopilot.json `display` > auto.
+		globals: z.object({
+			display: z
+				.enum(DISPLAY_MODES)
+				.optional()
+				.describe(
+					'How PICO-8 -run sessions (audio record/render, run --record-audio) get a display: auto (default: a private virtual display only when there is none), xvfb (always virtual), native (as-is). Also PICOPILOT_DISPLAY or picopilot.json "display" (under --mcp, only PICOPILOT_DISPLAY applies).',
+				),
+		}),
+		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),
+		}),
+	});
+
+	cli.use(async (c, next) => {
+		const configured = configSink.display;
+		configSink.display = undefined; // never leak into a later invocation
+		const resolved = resolveDisplayMode({
+			// incur's MCP transport passes no globals (and loads no config file), so
+			// under `--mcp` only PICOPILOT_DISPLAY applies.
+			flag: c.globals?.display,
+			env: (c.env as Record<string, string | undefined>)[DISPLAY_ENV_VAR],
+			config: configured,
+		});
+		if (!resolved.ok) {
+			// A bad value only fails the commands that use it; the rest run as usual.
+			if (!DISPLAY_COMMANDS.has(c.command)) return next();
+			// (An invalid --display never gets here: incur's enum rejects it first.)
+			const where =
+				resolved.source === 'env'
+					? DISPLAY_ENV_VAR
+					: `picopilot.json "${DISPLAY_CONFIG_KEY}"`;
+			return c.error({
+				code: 'invalid-display-mode',
+				message: `${where} is "${resolved.value}"; expected one of: ${DISPLAY_MODES.join(', ')}.`,
+				exitCode: 1,
+			});
+		}
+		c.set('display', resolved.mode);
+		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);
+	// 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 cli;
+	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';
@@ -54,6 +54,12 @@ function stubAdapter(
 	seen?: {record?: RecordOptions},
 ): Pico8Adapter {
 	return {
+		async drive() {
+			throw new Error('drive not used');
+		},
+		async export() {
+			throw new Error('export not used');
+		},
 		async run(_options: RunOptions) {
 			return {
 				ok: true,
@@ -171,6 +177,12 @@ describe('audio render: orchestration against a fake runner', () => {
 		let recordCalled = false;
 		const {stdout, exitCode} = await runAudio(
 			() => ({
+				async drive() {
+					throw new Error('drive not used');
+				},
+				async export() {
+					throw new Error('export not used');
+				},
 				async run() {
 					return {
 						ok: true,
@@ -278,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');
+	});
+});

package/src/commands/audio.ts

@@ -14,21 +14,28 @@ import {
 	buildRenderHarness,
 	DONE_SENTINEL,
 	HarnessError,
-	type Pico8Adapter,
+	type Pico8RecordResult,
 	type RenderTarget,
-	ShellPico8Adapter,
 } from '../engine/pico8/index.js';
+import {makeReadInclude} from './cart-includes.js';
+import {
+	createShellAdapterFactory,
+	displayModeOf,
+	displayUnavailableError,
+	PICO8_ENV,
+	type Pico8AdapterFactory,
+	pico8NotFoundError,
+} from './pico8-env.js';
 
 /**
  * Injects the PICO-8 adapter the audio commands use (defaults to the shell
  * adapter over native `pico8 -run`). Mirrors `run`'s `Pico8AdapterFactory` seam:
  * a test passes a fake to drive the record orchestration + the absent path
- * WITHOUT the paid binary, and to isolate the child `env`.
+ * WITHOUT the paid binary.
  */
-export type Pico8AdapterFactory = (env: NodeJS.ProcessEnv) => Pico8Adapter;
+export type {Pico8AdapterFactory} from './pico8-env.js';
 
-const defaultAdapterFactory: Pico8AdapterFactory = (env) =>
-	new ShellPico8Adapter({env});
+const defaultAdapterFactory: Pico8AdapterFactory = createShellAdapterFactory();
 
 /**
  * The default record backstop: kill a capture that never signals after this many
@@ -39,7 +46,7 @@ const DEFAULT_BACKSTOP_MS = 30_000;
 
 /** The honest one-liner both `record` and `render` carry (ADR-0009): not offline. */
 const HONEST_CAVEAT =
-	'This is a REAL-TIME recording of playback (needs a real audio+video session, not headless), NOT a deterministic offline export.';
+	'This is a REAL-TIME recording of playback in a -run session, NOT a deterministic offline export. Works headless: with no display, picopilot runs the session on a private virtual display (ADR-0017, --display).';
 
 /** Resolves a path argument to an absolute path (relative to cwd). */
 function resolvePath(p: string): string {
@@ -64,14 +71,8 @@ function chooseWavDir(given: string | undefined): string {
 	return dir;
 }
 
-/** The env schema both audio subcommands share (locates the binary, in isolation). */
-const AUDIO_ENV = z.object({
-	PICO8_PATH: z
-		.string()
-		.optional()
-		.describe('Explicit path to the PICO-8 binary (else `pico8` on PATH).'),
-	PATH: z.string().optional().describe('Used to locate `pico8`.'),
-});
+/** The env schema both audio subcommands share (locates the binary). */
+const AUDIO_ENV = PICO8_ENV;
 
 /** The structured output shape shared by `record` and `render`. */
 const AUDIO_OUTPUT = z.object({
@@ -79,7 +80,7 @@ const AUDIO_OUTPUT = z.object({
 		.string()
 		.optional()
 		.describe(
-			'Absolute path of the recorded WAV, or omitted if no audio was captured (e.g. a headless session with no audio device).',
+			'Absolute path of the recorded WAV, or omitted if no audio was captured (see noAudioReason).',
 		),
 	captured: z
 		.boolean()
@@ -98,41 +99,60 @@ const AUDIO_OUTPUT = z.object({
 		.number()
 		.describe('The record window in seconds the capture ran for.'),
 	printh: z.string().describe('Captured stdout from the session.'),
+	display: z
+		.enum(['native', 'Xvfb', 'xvfb-run'])
+		.optional()
+		.describe(
+			'Which display the -run session used: native, or a private virtual display (Xvfb / xvfb-run).',
+		),
+	noAudioReason: z
+		.string()
+		.optional()
+		.describe(
+			'When no WAV was captured: why (backstop fired / PICO-8 exited before the done-sentinel / empty capture).',
+		),
+	pico8LogTail: z
+		.string()
+		.optional()
+		.describe(
+			"When no WAV was captured: the tail of PICO-8's own log.txt (load errors, SDL init failures).",
+		),
 });
 
-/** The message a `pico8-not-found` error carries (mirrors `run`): exact remedy + needs. */
-function pico8NotFoundMessage(notFound: {
-	remedy: string;
-	needs: readonly string[];
-}): string {
-	return `PICO-8 is not installed. ${notFound.remedy} (needs: ${notFound.needs.join(', ')})`;
-}
-
 /**
- * The advisory CTA when a record/render run captured NO audio (a headless /
- * no-audio-device session): the orchestration worked, there is just nothing to
- * hear (ADR-0009's live-tier caveat), so it is a nudge, not a hard error.
+ * The advisory CTA when a record/render run captured NO audio. The report's
+ * `noAudioReason` + `pico8LogTail` say why; this points at the next step.
  */
-function noAudioCta(caveat: string) {
+function noAudioCta(reason: string | undefined) {
 	return {
-		description: `No audio was captured (${caveat}) Recording needs a real audio+video session:`,
+		description: `No audio was captured${reason !== undefined ? ` (${reason})` : ''}. Next:`,
 		commands: [
 			{
-				command: 'audio render --sfx <n>',
+				command: 'verify',
 				description:
-					'Run on a developer machine with a display + audio device (not headless CI).',
+					'Run the static gate: a cart that fails to load or errors never reaches audio_end.',
+			},
+			{
+				command: 'doctor',
+				description: 'Check PICO-8 and display capabilities on this machine.',
 			},
 		],
 	};
 }
 
+/** Maps a failed record result onto the structured `error(...)` payload. */
+function recordFailure(
+	what: string,
+	result: Exclude<Pico8RecordResult, {ok: true}>,
+) {
+	return result.reason === 'display-unavailable'
+		? displayUnavailableError(what, result)
+		: pico8NotFoundError(result);
+}
+
 /** Shapes an adapter record report into the structured output object. */
 function recordOutput(
-	report: {
-		wavPath: string | undefined;
-		printh: string;
-		exitReason: 'sentinel' | 'timeout' | 'exit';
-	},
+	report: Extract<Pico8RecordResult, {ok: true}>['value'],
 	harness: {seconds: number; description: string},
 ) {
 	return {
@@ -142,6 +162,13 @@ function recordOutput(
 		target: harness.description,
 		seconds: harness.seconds,
 		printh: report.printh,
+		...(report.display !== undefined ? {display: report.display} : {}),
+		...(report.noWavReason !== undefined
+			? {noAudioReason: report.noWavReason}
+			: {}),
+		...(report.pico8LogTail !== undefined
+			? {pico8LogTail: report.pico8LogTail}
+			: {}),
 	};
 }
 
@@ -154,7 +181,7 @@ function recordOutput(
 function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 	const audio = Cli.create('audio', {
 		description:
-			'Get a WAV out of a cart by RECORDING a running session (ADR-0009). PICO-8 has no working offline WAV export, so both commands are REAL-TIME recordings that need a real audio+video session (not headless), NOT deterministic offline exports. Requires PICO-8.',
+			'Get a WAV out of a cart by RECORDING a running session (ADR-0009). PICO-8 has no working offline WAV export, so both commands are REAL-TIME recordings of a -run session, NOT deterministic offline exports. They work headless: with no display, picopilot runs the session on a private virtual display (ADR-0017). Requires PICO-8.',
 	});
 
 	// --- audio record <cart> ---------------------------------------------------
@@ -203,7 +230,7 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				options: {seconds: 4},
 			},
 		],
-		async run({args, options, env, error, ok}) {
+		async run({args, options, env, error, ok, var: vars}) {
 			const cartPath = resolvePath(args.cart);
 			if (!existsSync(cartPath)) {
 				return error({
@@ -215,9 +242,12 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 
 			let harness: ReturnType<typeof buildRecordHarness>;
 			try {
+				// `#include`s are inlined against the SOURCE cart's folder: the harness
+				// runs from the isolated wavDir, where `main.lua` does not exist.
 				harness = buildRecordHarness(readFileSync(cartPath, 'utf8'), {
 					seconds: options.seconds,
 					sentinel: options.sentinel,
+					readInclude: makeReadInclude(cartPath),
 				});
 			} catch (e) {
 				if (e instanceof HarnessError) {
@@ -232,7 +262,9 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 			const harnessCart = join(wavDir, 'record-harness.p8');
 			writeFileSync(harnessCart, harness.cartText);
 
-			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv, {
+				display: displayModeOf(vars),
+			});
 			const result = await adapter.record({
 				cartPath: harnessCart,
 				wavDir,
@@ -241,18 +273,12 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				backstopMs: options.backstopMs,
 			});
 
-			if (!result.ok) {
-				return error({
-					code: 'pico8-not-found',
-					message: pico8NotFoundMessage(result),
-					exitCode: 1,
-				});
-			}
+			if (!result.ok) return error(recordFailure('audio record', result));
 
 			const out = recordOutput(result.value, harness);
 			return ok(
 				out,
-				out.captured ? undefined : {cta: noAudioCta(HONEST_CAVEAT)},
+				out.captured ? undefined : {cta: noAudioCta(out.noAudioReason)},
 			);
 		},
 	});
@@ -324,7 +350,7 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				options: {pattern: 2, seconds: 6},
 			},
 		],
-		async run({args, options, env, error, ok}) {
+		async run({args, options, env, error, ok, var: vars}) {
 			if (options.sfx !== undefined && options.pattern !== undefined) {
 				return error({
 					code: 'ambiguous-target',
@@ -368,7 +394,9 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 			const harnessCart = join(wavDir, 'render-harness.p8');
 			writeFileSync(harnessCart, harness.cartText);
 
-			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv, {
+				display: displayModeOf(vars),
+			});
 			const result = await adapter.record({
 				cartPath: harnessCart,
 				wavDir,
@@ -377,18 +405,12 @@ function buildAudioGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 				backstopMs: options.backstopMs,
 			});
 
-			if (!result.ok) {
-				return error({
-					code: 'pico8-not-found',
-					message: pico8NotFoundMessage(result),
-					exitCode: 1,
-				});
-			}
+			if (!result.ok) return error(recordFailure('audio render', result));
 
 			const out = recordOutput(result.value, harness);
 			return ok(
 				out,
-				out.captured ? undefined : {cta: noAudioCta(HONEST_CAVEAT)},
+				out.captured ? undefined : {cta: noAudioCta(out.noAudioReason)},
 			);
 		},
 	});

package/src/commands/cart-includes.ts

@@ -0,0 +1,27 @@
+import {readFileSync} from 'node:fs';
+import {dirname, isAbsolute, join} from 'node:path';
+
+/**
+ * A `#include` resolver for the drive-transform, bound to the SOURCE cart's dir:
+ * picopilot's standard scaffold is `main.p8` = `#include main.lua`, and the
+ * driven cart runs from a throwaway temp dir where `main.lua` is absent, so the
+ * transform inlines includes to be self-contained. Reads the included file
+ * relative to the cart (absolute paths honoured); returns `undefined` if it
+ * cannot be read (the directive is then left verbatim). Shared by `playtest` and
+ * the `--label-frame` capture.
+ */
+export function makeReadInclude(
+	cartPath: string,
+): (p: string) => string | undefined {
+	const base = dirname(cartPath);
+	return (includePath) => {
+		const full = isAbsolute(includePath)
+			? includePath
+			: join(base, includePath);
+		try {
+			return readFileSync(full, 'utf8');
+		} catch {
+			return undefined;
+		}
+	};
+}