picopilot 0.1.5 → 0.2.1

package/src/commands/doctor.ts

@@ -0,0 +1,284 @@
+import {mkdtempSync, realpathSync, rmSync, writeFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {type Cli, z} from 'incur';
+import {
+	DISPLAY_MODES,
+	type DisplayMode,
+	detectVirtualDisplayBackend,
+	findExecutable,
+	hasNativeDisplay,
+	needsVirtualDisplay,
+	pico8Candidates,
+	pico8ChildEnv,
+	type VirtualDisplayBackend,
+} from '../engine/pico8/index.js';
+import {
+	createShellAdapterFactory,
+	DISPLAY_OPTION,
+	PICO8_ENV,
+	resolveCommandDisplay,
+	type Pico8AdapterFactory,
+} from './pico8-env.js';
+import {
+	createShellShrinkoFactory,
+	type ShrinkoAdapterFactory,
+} from './shrinko-env.js';
+
+/** The marker the version-probe cart prints in front of `stat(5)`. */
+const VERSION_MARKER = '__PICOPILOT_PICO8_VERSION__';
+
+/** The probe cart: print PICO-8's version id, then the done-sentinel. */
+const PROBE_SENTINEL = '__PICOPILOT_DOCTOR_DONE__';
+const PROBE_CART = `pico-8 cartridge // http://www.pico-8.com
+version 42
+__lua__
+printh("${VERSION_MARKER}"..stat(5))
+printh("${PROBE_SENTINEL}")
+`;
+
+/** A tiny cart for the shrinko probe (a real `--count` run). */
+const SHRINKO_PROBE_CART = `pico-8 cartridge // http://www.pico-8.com
+version 42
+__lua__
+print("hi")
+`;
+
+/** The doctor's backstop for the headless PICO-8 probe. */
+const PROBE_BACKSTOP_MS = 15_000;
+
+/** What a command needs to run (beyond picopilot itself). */
+type Need = 'pico8' | 'shrinko8' | 'display';
+
+/**
+ * The capability table: every command (or command mode) and what it needs.
+ * `display` means a PICO-8 `-run` session: a native display or a virtual one.
+ * The `-x` paths (run screenshots, playtest, export, serve) are headless and
+ * need PICO-8 only.
+ */
+const COMMAND_NEEDS: readonly {command: string; needs: readonly Need[]}[] = [
+	{command: 'init', needs: []},
+	{command: 'gfx show / set / render', needs: []},
+	{command: 'sfx', needs: []},
+	{command: 'music', needs: []},
+	{command: 'gfx import / export', needs: ['shrinko8']},
+	{command: 'tokens', needs: ['shrinko8']},
+	{command: 'lint', needs: ['shrinko8']},
+	{command: 'minify', needs: ['shrinko8']},
+	{command: 'verify', needs: ['shrinko8']},
+	{command: 'run', needs: ['pico8']},
+	{command: 'playtest', needs: ['pico8']},
+	{command: 'export', needs: ['pico8']},
+	{command: 'serve', needs: ['pico8']},
+	{command: 'run --record-audio', needs: ['pico8', 'display']},
+	{command: 'audio record', needs: ['pico8', 'display']},
+	{command: 'audio render', needs: ['pico8', 'display']},
+];
+
+/** The PICO-8 version from its install path (e.g. `.../pico-8-0.2.7/...`), if it names one. */
+function versionFromPath(path: string): string | undefined {
+	const m = /pico-?8[-_ ]v?(\d+\.\d+\.\d+[a-z]?)/i.exec(path);
+	return m?.[1];
+}
+
+/** How a `-run` session would get its display here. */
+type RunSessionDisplay = 'native' | 'xvfb' | 'none';
+
+/** Dependencies for {@link registerDoctor}, injectable for tests. */
+export interface DoctorDeps {
+	readonly pico8?: Pico8AdapterFactory;
+	readonly shrinko?: ShrinkoAdapterFactory;
+	/** The parent environment (defaults to `process.env`): DISPLAY etc. are read from it. */
+	readonly parentEnv?: NodeJS.ProcessEnv;
+	/** Executable lookup (defaults to a PATH search). */
+	readonly find?: (name: string, env: NodeJS.ProcessEnv) => string | undefined;
+}
+
+/**
+ * Registers `picopilot doctor`: what can THIS machine do? It reports whether
+ * PICO-8 is found (and runs headless, with its version), whether shrinko8 is
+ * found, how a PICO-8 `-run` session would get a display (native, a private
+ * virtual one via Xvfb, or none), and therefore which commands are available.
+ * An agent calls it first instead of discovering limits by failing. It never
+ * fails itself: a missing dependency is data in the report.
+ */
+export function registerDoctor(cli: Cli.Cli, deps: DoctorDeps = {}): void {
+	const pico8Factory =
+		deps.pico8 ?? createShellAdapterFactory({parentEnv: deps.parentEnv});
+	const shrinkoFactory: ShrinkoAdapterFactory =
+		deps.shrinko ?? createShellShrinkoFactory({parentEnv: deps.parentEnv});
+	const find = deps.find ?? findExecutable;
+
+	cli.command('doctor', {
+		description:
+			'Report what this machine can do: PICO-8 (found, runs headless, version), shrinko8, the display a PICO-8 -run session would use (native / virtual Xvfb / none), and which picopilot commands are therefore available. Call this first on a new machine.',
+		env: PICO8_ENV,
+		options: z.object({display: DISPLAY_OPTION}),
+		output: z.object({
+			pico8: z.object({
+				found: z.boolean().describe('Whether the PICO-8 binary was found.'),
+				path: z.string().optional().describe('The resolved binary path.'),
+				runs: z
+					.boolean()
+					.describe('Whether a headless -x probe run actually worked.'),
+				version: z
+					.string()
+					.optional()
+					.describe('The PICO-8 version, when its install path names it.'),
+				versionId: z
+					.number()
+					.optional()
+					.describe("PICO-8's internal version number (stat(5))."),
+			}),
+			shrinko8: z.object({
+				found: z
+					.boolean()
+					.describe('Whether shrinko8 ran (token count on a probe cart).'),
+			}),
+			display: z.object({
+				mode: z
+					.enum(DISPLAY_MODES)
+					.describe('The resolved display mode (--display / env / config).'),
+				native: z
+					.boolean()
+					.describe('Whether DISPLAY or WAYLAND_DISPLAY is set.'),
+				virtual: z
+					.enum(['Xvfb', 'xvfb-run'])
+					.optional()
+					.describe('The virtual-display backend available, if any.'),
+				runSessions: z
+					.enum(['native', 'xvfb', 'none'])
+					.describe(
+						'How a PICO-8 -run session (audio record/render, run --record-audio) gets a display here.',
+					),
+			}),
+			available: z
+				.array(z.string())
+				.describe('Commands that work on this machine.'),
+			unavailable: z
+				.array(
+					z.object({
+						command: z.string(),
+						missing: z.array(z.string()),
+					}),
+				)
+				.describe('Commands that do not, and what they are missing.'),
+		}),
+		async run({env, ok, error, options, var: vars}) {
+			const resolved = resolveCommandDisplay(options.display, vars);
+			if (!resolved.ok) return error(resolved.error);
+			const display: DisplayMode = resolved.mode;
+			const childEnv = pico8ChildEnv(
+				env as Record<string, string | undefined>,
+				deps.parentEnv ?? process.env,
+			);
+
+			// --- PICO-8: locate, then a real headless probe for the version.
+			const [pico8File] = pico8Candidates(childEnv) as [string, ...string[]];
+			const pico8Path = find(pico8File, childEnv);
+			let runs = false;
+			let versionId: number | undefined;
+			let version: string | undefined;
+			const probeDir = mkdtempSync(join(tmpdir(), 'picopilot-doctor-'));
+			try {
+				const cartPath = join(probeDir, 'probe.p8');
+				writeFileSync(cartPath, PROBE_CART);
+				const result = await pico8Factory(env as NodeJS.ProcessEnv, {
+					display,
+				}).run({
+					cartPath,
+					shotDir: probeDir,
+					sentinel: PROBE_SENTINEL,
+					backstopMs: PROBE_BACKSTOP_MS,
+				});
+				if (result.ok) {
+					const m = new RegExp(`${VERSION_MARKER}(\\d+)`).exec(
+						result.value.printh,
+					);
+					if (m !== null) {
+						runs = true;
+						versionId = Number(m[1]);
+					}
+				}
+			} finally {
+				rmSync(probeDir, {recursive: true, force: true});
+			}
+			if (pico8Path !== undefined) {
+				let real = pico8Path;
+				try {
+					real = realpathSync(pico8Path);
+				} catch {
+					// keep the unresolved path
+				}
+				version = versionFromPath(real) ?? versionFromPath(pico8Path);
+			}
+			const pico8Found = pico8Path !== undefined || runs;
+
+			// --- shrinko8: a real --count on a tiny cart.
+			let shrinkoFound = false;
+			const shrinkoDir = mkdtempSync(join(tmpdir(), 'picopilot-doctor-'));
+			try {
+				const cartPath = join(shrinkoDir, 'probe.p8');
+				writeFileSync(cartPath, SHRINKO_PROBE_CART);
+				try {
+					const count = await shrinkoFactory(env as NodeJS.ProcessEnv).count(
+						cartPath,
+					);
+					shrinkoFound = count.ok;
+				} catch {
+					// ran but did not parse: present, yet not usable for us
+					shrinkoFound = false;
+				}
+			} finally {
+				rmSync(shrinkoDir, {recursive: true, force: true});
+			}
+
+			// --- display: how a -run session would get one here.
+			const native = hasNativeDisplay(childEnv);
+			const virtual: VirtualDisplayBackend | undefined =
+				detectVirtualDisplayBackend(childEnv, find);
+			const runSessions: RunSessionDisplay = needsVirtualDisplay(
+				display,
+				childEnv,
+			)
+				? virtual !== undefined
+					? 'xvfb'
+					: 'none'
+				: native
+					? 'native'
+					: 'none';
+
+			const have: Record<Need, boolean> = {
+				pico8: runs,
+				shrinko8: shrinkoFound,
+				display: runSessions !== 'none',
+			};
+			const available: string[] = [];
+			const unavailable: {command: string; missing: string[]}[] = [];
+			for (const {command, needs} of COMMAND_NEEDS) {
+				const missing = needs.filter((n) => !have[n]);
+				if (missing.length === 0) available.push(command);
+				else unavailable.push({command, missing});
+			}
+
+			return ok({
+				pico8: {
+					found: pico8Found,
+					...(pico8Path !== undefined ? {path: pico8Path} : {}),
+					runs,
+					...(version !== undefined ? {version} : {}),
+					...(versionId !== undefined ? {versionId} : {}),
+				},
+				shrinko8: {found: shrinkoFound},
+				display: {
+					mode: display,
+					native,
+					...(virtual !== undefined ? {virtual} : {}),
+					runSessions,
+				},
+				available,
+				unavailable,
+			});
+		},
+	});
+}

package/src/commands/export.ts

@@ -6,20 +6,22 @@ import {
 	EXPORT_HTML_NAME,
 	type Pico8Adapter,
 	type Pico8ExportResult,
-	ShellPico8Adapter,
 } from '../engine/pico8/index.js';
+import {
+	createShellAdapterFactory,
+	PICO8_ENV,
+	type Pico8AdapterFactory,
+} from './pico8-env.js';
 import {prepareLabeledCart} from './label-cart.js';
 
 /**
  * Injects the PICO-8 adapter `export` uses (defaults to the shell adapter over
  * native `pico8 <cart> -export <name>.html -x`). Mirrors the `run` seam: a test
- * passes a stub to drive the present/absent paths without the paid binary, and
- * to isolate the child `env` (its `PICO8_PATH`/`PATH`).
+ * passes a stub to drive the present/absent paths without the paid binary, (the child env is the parent env + PICO8_PATH/PATH).
  */
-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 backstop: kill an export that never completes/exits after this many ms. */
 const DEFAULT_BACKSTOP_MS = 30_000;
@@ -102,13 +104,7 @@ export function registerExport(
 		}),
 		// incur resolves these from the (test-overridable) env source and hands
 		// them to the child, so PICO8_PATH/PATH locate the binary in isolation.
-		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`.'),
-		}),
+		env: PICO8_ENV,
 		output: z.object({
 			outDir: z
 				.string()

package/src/commands/gfx.ts

@@ -20,16 +20,18 @@ import {
 	SHEET_RENDER_SCALE,
 	SPRITE_RENDER_SCALE,
 } from '../engine/gfx/index.js';
+import {type ShrinkoAdapter} from '../engine/shrinko/index.js';
 import {
-	type ShrinkoAdapter,
-	ShellShrinkoAdapter,
-} from '../engine/shrinko/index.js';
+	createShellShrinkoFactory,
+	type ShrinkoAdapterFactory,
+} from './shrinko-env.js';
+import {mcpConfigOption} from './pico8-env.js';
 
 /** Injects the shrinko adapter `gfx import`/`gfx export` use (the spritesheet round-trip). */
-export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+export type {ShrinkoAdapterFactory} from './shrinko-env.js';
 
-const defaultShrinkoFactory: ShrinkoAdapterFactory = (env) =>
-	new ShellShrinkoAdapter({env});
+const defaultShrinkoFactory: ShrinkoAdapterFactory =
+	createShellShrinkoFactory();
 
 /**
  * The exit code for the `map-overlap` refusal. Chosen as 1 (a plain failure),
@@ -198,11 +200,13 @@ function buildGfxGroup(shrinkoFactory: ShrinkoAdapterFactory): Cli.Cli {
 				),
 		}),
 		options: z.object({
+			// No zod default: an absent value must stay distinguishable, so that under
+			// `--mcp` (where incur loads no config) picopilot.json still applies.
 			allowMapOverlap: z
 				.boolean()
-				.default(false)
+				.optional()
 				.describe(
-					'Authorise overwriting existing shared-region data when writing sprites 128-255 (ADR-0004). Also settable as allowMapOverlap in picopilot.json.',
+					'Authorise overwriting existing shared-region data when writing sprites 128-255 (ADR-0004). Also settable as allowMapOverlap in picopilot.json. Default false.',
 				),
 		}),
 		output: z.object({
@@ -236,7 +240,7 @@ function buildGfxGroup(shrinkoFactory: ShrinkoAdapterFactory): Cli.Cli {
 				},
 			},
 		],
-		run({args, options, error, ok}) {
+		run({args, options, error, ok, var: vars}) {
 			const cartPath = resolveCart(args.cart);
 
 			// Decode the incoming grid FIRST: a malformed grid is a caller error and
@@ -266,12 +270,12 @@ function buildGfxGroup(shrinkoFactory: ShrinkoAdapterFactory): Cli.Cli {
 			// (the shared-bank bytes at risk), NOT __map__ (ADR-0004). The flag and
 			// the picopilot.json config both feed `options.allowMapOverlap` (incur
 			// resolves argv > config > default), so both authorisation paths converge
-			// here.
-			const decision = decideOverlap(
-				sheet,
-				args.sprite,
-				options.allowMapOverlap,
-			);
+			// here. Under `--mcp` incur loads no config, so the picopilot.json value
+			// comes from the `mcpConfig` var instead.
+			const allowMapOverlap =
+				options.allowMapOverlap ??
+				mcpConfigOption(vars, ['gfx', 'set'], 'allowMapOverlap') === true;
+			const decision = decideOverlap(sheet, args.sprite, allowMapOverlap);
 
 			if (decision.kind === 'refused') {
 				// The silent-corruption guard: REFUSE and DO NOT write. The cart file is

package/src/commands/lint.ts

@@ -1,16 +1,17 @@
 import {existsSync} from 'node:fs';
 import {isAbsolute, resolve} from 'node:path';
 import {type Cli, z} from 'incur';
+import {type ShrinkoAdapter} from '../engine/shrinko/index.js';
 import {
-	type ShrinkoAdapter,
-	ShellShrinkoAdapter,
-} from '../engine/shrinko/index.js';
+	createShellShrinkoFactory,
+	type ShrinkoAdapterFactory,
+} from './shrinko-env.js';
 
 /** See {@link import('./tokens.js').ShrinkoAdapterFactory}: lint reuses the same seam. */
-export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+export type {ShrinkoAdapterFactory} from './shrinko-env.js';
 
-const defaultAdapterFactory: ShrinkoAdapterFactory = (env) =>
-	new ShellShrinkoAdapter({env});
+const defaultAdapterFactory: ShrinkoAdapterFactory =
+	createShellShrinkoFactory();
 
 /**
  * Registers `picopilot lint` (US #4): surface PICO-8-specific issues (undefined

package/src/commands/minify.ts

@@ -1,16 +1,17 @@
 import {existsSync} from 'node:fs';
 import {dirname, isAbsolute, join, resolve} from 'node:path';
 import {type Cli, z} from 'incur';
+import {type ShrinkoAdapter} from '../engine/shrinko/index.js';
 import {
-	type ShrinkoAdapter,
-	ShellShrinkoAdapter,
-} from '../engine/shrinko/index.js';
+	createShellShrinkoFactory,
+	type ShrinkoAdapterFactory,
+} from './shrinko-env.js';
 
 /** See {@link import('./tokens.js').ShrinkoAdapterFactory}: minify reuses the same seam. */
-export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+export type {ShrinkoAdapterFactory} from './shrinko-env.js';
 
-const defaultAdapterFactory: ShrinkoAdapterFactory = (env) =>
-	new ShellShrinkoAdapter({env});
+const defaultAdapterFactory: ShrinkoAdapterFactory =
+	createShellShrinkoFactory();
 
 /**
  * Derives the default output path `<name>.min.p8` next to the source cart:

package/src/commands/pico8-env.ts

@@ -0,0 +1,192 @@
+import {z} from 'incur';
+import {
+	DEFAULT_DISPLAY_MODE,
+	DISPLAY_MODES,
+	type DisplayMode,
+	isDisplayMode,
+	type Pico8Adapter,
+	pico8ChildEnv,
+	ShellPico8Adapter,
+	type SpawnRunner,
+	type VirtualDisplayDeps,
+} from '../engine/pico8/index.js';
+
+/**
+ * The env schema every PICO-8-gated command declares. These are the values
+ * picopilot itself RESOLVES (incur reads them from its env source, which tests
+ * override); they are NOT the whole child environment. The child gets the
+ * parent environment with these overlaid ({@link pico8ChildEnv}), so PICO-8
+ * still sees DISPLAY, HOME, XDG_RUNTIME_DIR, SDL_* and the rest.
+ */
+export const PICO8_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`.'),
+});
+
+/** What a command knows beyond the env when it builds an adapter. */
+export interface Pico8AdapterContext {
+	/** The resolved display mode for `-run` sessions (ADR-0017). */
+	readonly display: DisplayMode;
+}
+
+/**
+ * Injects the PICO-8 adapter a command uses. A test passes a stub to drive the
+ * sentinel/backstop/absent paths without the paid binary; the default is
+ * {@link createShellAdapterFactory}.
+ */
+export type Pico8AdapterFactory = (
+	env: NodeJS.ProcessEnv,
+	context?: Pico8AdapterContext,
+) => Pico8Adapter;
+
+/** Dependencies for {@link createShellAdapterFactory}, injectable for tests. */
+export interface ShellAdapterFactoryDeps {
+	/** The parent environment PICO-8 inherits (defaults to `process.env`). */
+	readonly parentEnv?: NodeJS.ProcessEnv;
+	/** The PICO-8 spawn seam (defaults to the real spawn). */
+	readonly spawn?: SpawnRunner;
+	/** The virtual-display seam (Xvfb lookup + spawn). */
+	readonly virtualDisplay?: VirtualDisplayDeps;
+}
+
+/**
+ * The default adapter factory: the shell adapter over the user's PICO-8, with
+ * the child env = parent env + the command's resolved values, and the display
+ * mode from the context.
+ */
+export function createShellAdapterFactory(
+	deps: ShellAdapterFactoryDeps = {},
+): Pico8AdapterFactory {
+	return (env, context) =>
+		new ShellPico8Adapter({
+			env: pico8ChildEnv(
+				env as Record<string, string | undefined>,
+				deps.parentEnv ?? process.env,
+			),
+			spawn: deps.spawn,
+			display: context?.display ?? DEFAULT_DISPLAY_MODE,
+			virtualDisplay: deps.virtualDisplay,
+		});
+}
+
+/**
+ * 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 =
+		vars !== null && typeof vars === 'object'
+			? (vars as {display?: unknown}).display
+			: undefined;
+	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
+ * virtual one. The message and CTA name the fix, so the agent never has to
+ * discover it by a silent timeout.
+ */
+export function displayUnavailableError(
+	what: string,
+	result: {detail: string; remedy: string},
+) {
+	return {
+		code: 'display-unavailable' as const,
+		message: `${what} needs a display (a real audio+video -run session): ${result.detail}. Remedy: ${result.remedy}.`,
+		exitCode: 1,
+		cta: {
+			description: `No display and no Xvfb on this machine. Fix: ${result.remedy}. Then re-run; picopilot starts a private virtual display by itself (--display auto). Check what this machine can do:`,
+			commands: [
+				{
+					command: 'doctor',
+					description:
+						'Report PICO-8, shrinko8 and display capabilities, and which commands are available here.',
+				},
+			],
+		},
+	};
+}
+
+/** The `error(...)` payload for a `pico8-not-found` result (the exact remedy + needs). */
+export function pico8NotFoundError(result: {
+	remedy: string;
+	needs: readonly string[];
+}) {
+	return {
+		code: 'pico8-not-found' as const,
+		message: `PICO-8 is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+		exitCode: 1,
+	};
+}

package/src/commands/playtest.ts

@@ -22,12 +22,16 @@ import {
 	SessionRegistry,
 	sessionExists,
 	SHOT_BASENAME,
-	ShellPico8Adapter,
 	spawnSessionDaemon,
 	type SessionRequest,
 	type SessionResponse,
 	type SessionResponseValue,
 } from '../engine/pico8/index.js';
+import {
+	createShellAdapterFactory,
+	PICO8_ENV,
+	type Pico8AdapterFactory,
+} from './pico8-env.js';
 import {makeReadInclude} from './cart-includes.js';
 
 /**
@@ -36,10 +40,9 @@ import {makeReadInclude} from './cart-includes.js';
  * stub to drive the drive-orchestration + the absent path WITHOUT the paid
  * binary, and to isolate the child `env` (its `PICO8_PATH`/`PATH`).
  */
-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 backstop: kill a driven cart that never signals/exits after this
@@ -219,13 +222,7 @@ function buildPlaytestGroup(adapterFactory: Pico8AdapterFactory): Cli.Cli {
 }
 
 /** The env schema the whole `playtest` group shares (locates the binary, isolated). */
-const PLAYTEST_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`.'),
-});
+const PLAYTEST_ENV = PICO8_ENV;
 
 /**
  * The ONE-SHOT root handler (unchanged behaviour from the one-shot task): build