picopilot 0.1.5 → 0.2.0

package/src/commands/doctor.test.ts

@@ -0,0 +1,149 @@
+import {Cli} from 'incur';
+import {describe, expect, it} from 'vitest';
+import type {Pico8Adapter, RunOptions} from '../engine/pico8/index.js';
+import {pico8NotFound} from '../engine/pico8/index.js';
+import {shrinkoNotFound} from '../engine/shrinko/index.js';
+import type {ShrinkoAdapter} from '../engine/shrinko/index.js';
+import {type DoctorDeps, registerDoctor} from './doctor.js';
+
+/**
+ * `doctor` reports what this machine can do, from injected probes: a fake
+ * PICO-8 adapter (prints a version id, or is absent), a fake shrinko, a fake
+ * executable lookup and a controlled parent env (DISPLAY or not).
+ */
+
+function pico8Present(versionId = 43): Pico8Adapter {
+	return {
+		async run(_o: RunOptions) {
+			return {
+				ok: true,
+				value: {
+					screenshots: [],
+					printh: `__PICOPILOT_PICO8_VERSION__${versionId}\n`,
+					exitReason: 'sentinel',
+				},
+			};
+		},
+		async record() {
+			throw new Error('unused');
+		},
+		async drive() {
+			throw new Error('unused');
+		},
+		async export() {
+			throw new Error('unused');
+		},
+	};
+}
+
+const pico8Absent: Pico8Adapter = {
+	...pico8Present(),
+	async run() {
+		return pico8NotFound();
+	},
+};
+
+function shrinko(present: boolean): ShrinkoAdapter {
+	return {
+		async count() {
+			return present
+				? {ok: true, value: {tokens: 1, chars: 1, compressed: 1}}
+				: shrinkoNotFound();
+		},
+	} as unknown as ShrinkoAdapter;
+}
+
+async function doctor(deps: DoctorDeps, argv: string[] = []) {
+	const cli = Cli.create('picopilot', {version: '0.0.0'});
+	registerDoctor(cli, deps);
+	let stdout = '';
+	let exitCode = 0;
+	await cli.serve(['doctor', ...argv, '--json'], {
+		stdout(s) {
+			stdout += s;
+		},
+		exit(code) {
+			exitCode = code;
+		},
+		env: {PICO8_PATH: '/opt/pico-8-0.2.7/pico8'},
+	});
+	return {out: JSON.parse(stdout), exitCode};
+}
+
+const finds =
+	(...names: string[]) =>
+	(n: string) =>
+		names.some((x) => n === x || n.endsWith(`/${x}`)) ? n : undefined;
+
+describe('picopilot doctor', () => {
+	it('headless server with Xvfb: everything is available, -run sessions go virtual', async () => {
+		const {out, exitCode} = await doctor({
+			pico8: () => pico8Present(43),
+			shrinko: () => shrinko(true),
+			parentEnv: {},
+			find: finds('pico8', 'Xvfb'),
+		});
+		expect(exitCode).toBe(0);
+		expect(out.pico8).toMatchObject({
+			found: true,
+			runs: true,
+			versionId: 43,
+			version: '0.2.7',
+		});
+		expect(out.shrinko8.found).toBe(true);
+		expect(out.display).toEqual({
+			mode: 'auto',
+			native: false,
+			virtual: 'Xvfb',
+			runSessions: 'xvfb',
+		});
+		expect(out.unavailable).toEqual([]);
+		expect(out.available).toContain('audio record');
+	});
+
+	it('no display and no Xvfb: only the -run commands are unavailable, missing "display"', async () => {
+		const {out} = await doctor({
+			pico8: () => pico8Present(),
+			shrinko: () => shrinko(true),
+			parentEnv: {},
+			find: finds('pico8'),
+		});
+		expect(out.display.runSessions).toBe('none');
+		expect(
+			out.unavailable.map((u: {command: string}) => u.command).sort(),
+		).toEqual(['audio record', 'audio render', 'run --record-audio'].sort());
+		expect(out.unavailable[0].missing).toEqual(['display']);
+		expect(out.available).toContain('run');
+		expect(out.available).toContain('playtest');
+		expect(out.available).toContain('export');
+	});
+
+	it('a desktop (DISPLAY set): -run sessions are native', async () => {
+		const {out} = await doctor({
+			pico8: () => pico8Present(),
+			shrinko: () => shrinko(true),
+			parentEnv: {DISPLAY: ':0'},
+			find: finds('pico8'),
+		});
+		expect(out.display.native).toBe(true);
+		expect(out.display.runSessions).toBe('native');
+	});
+
+	it('no PICO-8 and no shrinko8: reports both as missing, still exits 0 (the report is the result)', async () => {
+		const {out, exitCode} = await doctor({
+			pico8: () => pico8Absent,
+			shrinko: () => shrinko(false),
+			parentEnv: {},
+			find: () => undefined,
+		});
+		expect(exitCode).toBe(0);
+		expect(out.pico8).toEqual({found: false, runs: false});
+		expect(out.shrinko8.found).toBe(false);
+		expect(out.available).toEqual([
+			'init',
+			'gfx show / set / render',
+			'sfx',
+			'music',
+		]);
+	});
+});

package/src/commands/doctor.ts

@@ -0,0 +1,280 @@
+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,
+	displayModeOf,
+	PICO8_ENV,
+	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,
+		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, var: vars}) {
+			const display: DisplayMode = displayModeOf(vars);
+			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,17 @@ 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';
 
 /** 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),

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,124 @@
+import {z} from 'incur';
+import {
+	DEFAULT_DISPLAY_MODE,
+	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 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.
+ */
+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 `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,
+	};
+}