picopilot 0.0.0 → 0.1.1

package/src/commands/export.test.ts

@@ -0,0 +1,310 @@
+import {execFileSync} from 'node:child_process';
+import {
+	existsSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {Cli} from 'incur';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {encodePng} from '../engine/gfx/index.js';
+import {PICO8_PALETTE} from '../engine/gfx/index.js';
+import type {
+	ExportOptions,
+	Pico8Adapter,
+	Pico8ExportResult,
+} from '../engine/pico8/index.js';
+import {pico8NotFound} from '../engine/pico8/index.js';
+import {type Pico8AdapterFactory, registerExport} from './export.js';
+
+/** A trivial valid cart the command reads (existence + a path to hand the adapter). */
+const CART_TEXT =
+	'pico-8 cartridge // http://www.pico-8.com\nversion 42\n__lua__\nprint("hi")\n';
+
+/** A 128x128 solid PNG (index 12, blue) usable as a --label fixture. */
+function labelPng(): Uint8Array {
+	const c = PICO8_PALETTE[12]!;
+	const rgb = new Uint8Array(128 * 128 * 3);
+	for (let i = 0; i < 128 * 128; i++) {
+		rgb[i * 3] = c.r;
+		rgb[i * 3 + 1] = c.g;
+		rgb[i * 3 + 2] = c.b;
+	}
+	return encodePng({width: 128, height: 128, rgb});
+}
+
+let dir: string;
+let cartPath: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'picopilot-export-'));
+	cartPath = join(dir, 'main.p8');
+	writeFileSync(cartPath, CART_TEXT);
+});
+
+afterEach(() => {
+	try {
+		execFileSync('rm', ['-rf', dir]);
+	} catch {
+		// ignore
+	}
+});
+
+/**
+ * A stub {@link Pico8Adapter} whose `export` REALLY writes the bundle files into
+ * the `outDir` it is handed, so the command's file collection + the
+ * --payload-only file split are exercised end-to-end WITHOUT the paid binary. It
+ * records the {@link ExportOptions} so a test can assert the chosen out dir.
+ */
+function stubAdapter(
+	result: Pico8ExportResult | 'writes-bundle' | 'writes-no-js',
+	seen?: {options?: ExportOptions},
+	labelWarning = false,
+): Pico8Adapter {
+	const notUsed = () => {
+		throw new Error('not used by export');
+	};
+	return {
+		run: notUsed as never,
+		record: notUsed as never,
+		drive: notUsed as never,
+		async export(options) {
+			if (seen !== undefined) seen.options = options;
+			if (result === 'writes-bundle') {
+				const html = join(options.outDir, 'index.html');
+				const js = join(options.outDir, 'index.js');
+				writeFileSync(html, '<html><script src="index.js"></script></html>');
+				writeFileSync(js, '// pico8 runtime');
+				return {
+					ok: true,
+					value: {htmlPath: html, jsPath: js, files: [html, js], labelWarning},
+				};
+			}
+			if (result === 'writes-no-js') {
+				return {
+					ok: true,
+					value: {
+						htmlPath: undefined,
+						jsPath: undefined,
+						files: [],
+						labelWarning,
+					},
+				};
+			}
+			return result;
+		},
+	};
+}
+
+/** Drives `picopilot export` through incur's serve DI with an injected adapter. */
+async function runExport(
+	factory: Pico8AdapterFactory,
+	argv: string[],
+	env: Record<string, string | undefined> = {PATH: '/does/not/matter'},
+) {
+	const cli = Cli.create('picopilot', {version: '0.0.0'});
+	registerExport(cli, factory);
+	let stdout = '';
+	let exitCode = 0;
+	await cli.serve(argv, {
+		stdout(s) {
+			stdout += s;
+		},
+		exit(code) {
+			exitCode = code;
+		},
+		env,
+	});
+	return {stdout, exitCode};
+}
+
+describe('picopilot export: PICO-8 absent (the CI-testable boundary)', () => {
+	it('returns structured pico8-not-found + nonzero exit (mirrors run, never a crash)', async () => {
+		const {stdout, exitCode} = await runExport(
+			() => stubAdapter(pico8NotFound()),
+			['export', cartPath, '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('set PICO8_PATH or install PICO-8');
+		expect(stdout).toContain('pico8');
+	});
+});
+
+describe('picopilot export: standalone bundle into a dest dir', () => {
+	it('writes index.html + index.js and reports both paths', async () => {
+		const dest = join(dir, 'out');
+		const {stdout, exitCode} = await runExport(
+			() => stubAdapter('writes-bundle'),
+			['export', cartPath, dest, '--json'],
+		);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.outDir).toBe(dest);
+		expect(out.html.endsWith('index.html')).toBe(true);
+		expect(out.js.endsWith('index.js')).toBe(true);
+		// The dest dir is directly serveable: both files are present on disk.
+		expect(existsSync(join(dest, 'index.html'))).toBe(true);
+		expect(existsSync(join(dest, 'index.js'))).toBe(true);
+	});
+
+	it('names the export index.html so a dest folder plays directly', async () => {
+		const seen: {options?: ExportOptions} = {};
+		await runExport(
+			() => stubAdapter('writes-bundle', seen),
+			['export', cartPath, join(dir, 'out'), '--json'],
+		);
+		expect(seen.options?.htmlName).toBe('index.html');
+	});
+
+	it('defaults the dest to an isolated temp dir (never a user path)', async () => {
+		const seen: {options?: ExportOptions} = {};
+		await runExport(
+			() => stubAdapter('writes-bundle', seen),
+			['export', cartPath, '--json'],
+		);
+		expect(seen.options?.outDir.startsWith(tmpdir())).toBe(true);
+	});
+});
+
+describe('picopilot export: --payload-only (drop the shell page for a site component)', () => {
+	it('removes index.html and keeps only the js payload', async () => {
+		const dest = join(dir, 'payload');
+		const {stdout, exitCode} = await runExport(
+			() => stubAdapter('writes-bundle'),
+			['export', cartPath, dest, '--payload-only', '--json'],
+		);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.html).toBeUndefined();
+		expect(out.js.endsWith('index.js')).toBe(true);
+		// The shell page is gone; the runtime payload remains.
+		expect(existsSync(join(dest, 'index.html'))).toBe(false);
+		expect(existsSync(join(dest, 'index.js'))).toBe(true);
+	});
+});
+
+describe('picopilot export: --label (bake a PNG in as the __label__ splash)', () => {
+	it('injects the label into a copy and exports that (original cart untouched)', async () => {
+		const seen: {options?: ExportOptions} = {};
+		const labelFile = join(dir, 'label.png');
+		writeFileSync(labelFile, labelPng());
+		const {exitCode} = await runExport(
+			() => stubAdapter('writes-bundle', seen),
+			['export', cartPath, join(dir, 'out'), '--label', labelFile, '--json'],
+		);
+		expect(exitCode).toBe(0);
+		// The cart handed to PICO-8 is a labeled COPY, not the original path.
+		const handed = seen.options!.cartPath;
+		expect(handed).not.toBe(cartPath);
+		// The original cart is byte-untouched (no label added to it).
+		expect(readFileSync(cartPath, 'utf8')).toBe(CART_TEXT);
+		expect(readFileSync(cartPath, 'utf8')).not.toContain('__label__');
+	});
+
+	it('cleans up the temporary labeled copy after export', async () => {
+		const seen: {options?: ExportOptions} = {};
+		const labelFile = join(dir, 'label.png');
+		writeFileSync(labelFile, labelPng());
+		await runExport(
+			() => stubAdapter('writes-bundle', seen),
+			['export', cartPath, join(dir, 'out'), '--label', labelFile, '--json'],
+		);
+		// No stray .picopilot-export-*.p8 copy left beside the cart.
+		const leftovers = readdirSync(dir).filter((f) =>
+			f.startsWith('.picopilot-export-'),
+		);
+		expect(leftovers).toEqual([]);
+	});
+
+	it('ignores --label when the cart ALREADY has a label (does not override)', async () => {
+		const seen: {options?: ExportOptions} = {};
+		const labeled = join(dir, 'labeled.p8');
+		writeFileSync(labeled, `${CART_TEXT}__label__\n${'0'.repeat(128)}\n`);
+		const labelFile = join(dir, 'label.png');
+		writeFileSync(labelFile, labelPng());
+		const {exitCode} = await runExport(
+			() => stubAdapter('writes-bundle', seen),
+			['export', labeled, join(dir, 'out'), '--label', labelFile, '--json'],
+		);
+		expect(exitCode).toBe(0);
+		// The cart already had a label, so it is exported AS-IS (no copy made).
+		expect(seen.options!.cartPath).toBe(labeled);
+	});
+
+	it('errors when the --label file does not exist', async () => {
+		const {stdout, exitCode} = await runExport(
+			() => stubAdapter('writes-bundle'),
+			[
+				'export',
+				cartPath,
+				join(dir, 'out'),
+				'--label',
+				join(dir, 'nope.png'),
+				'--json',
+			],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('no label image at');
+	});
+
+	it('errors on a wrong-size label image (must be 128x128)', async () => {
+		const small = encodePng({
+			width: 64,
+			height: 64,
+			rgb: new Uint8Array(64 * 64 * 3),
+		});
+		const labelFile = join(dir, 'small.png');
+		writeFileSync(labelFile, small);
+		const {stdout, exitCode} = await runExport(
+			() => stubAdapter('writes-bundle'),
+			['export', cartPath, join(dir, 'out'), '--label', labelFile, '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('128x128');
+	});
+});
+
+describe('picopilot export: labelless cart + failure paths', () => {
+	it('surfaces the labelWarning and CTAs toward capturing a label (standalone)', async () => {
+		const {stdout, exitCode} = await runExport(
+			() => stubAdapter('writes-bundle', undefined, true),
+			['export', cartPath, join(dir, 'out'), '--json'],
+		);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.labelWarning).toBe(true);
+		expect(stdout.toLowerCase()).toContain('label');
+	});
+
+	it('errors when PICO-8 produced no js payload (labelless bail)', async () => {
+		const {stdout, exitCode} = await runExport(
+			() => stubAdapter('writes-no-js', undefined, true),
+			['export', cartPath, join(dir, 'out'), '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout.toLowerCase()).toContain('label');
+	});
+});
+
+describe('picopilot export: cart-not-found (picopilot-side error, distinct from pico8 absence)', () => {
+	it('errors with a nonzero exit when the cart path does not exist', async () => {
+		const {stdout, exitCode} = await runExport(
+			() => stubAdapter('writes-bundle'),
+			['export', join(dir, 'nope.p8'), '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('no cart at');
+	});
+
+	it('does NOT invoke the adapter when the cart is missing (fails fast)', async () => {
+		let called = false;
+		await runExport(() => {
+			called = true;
+			return stubAdapter('writes-bundle');
+		}, ['export', join(dir, 'missing.p8'), '--json']);
+		expect(called).toBe(false);
+	});
+});

package/src/commands/export.ts

@@ -0,0 +1,316 @@
+import {
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {dirname, isAbsolute, join, resolve} from 'node:path';
+import {type Cli, z} from 'incur';
+import {Cart, CartParseError} from '../engine/cart/index.js';
+import {labelHexFromPng, LabelError} from '../engine/gfx/index.js';
+import {
+	EXPORT_HTML_NAME,
+	type Pico8Adapter,
+	ShellPico8Adapter,
+} from '../engine/pico8/index.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`).
+ */
+export type Pico8AdapterFactory = (env: NodeJS.ProcessEnv) => Pico8Adapter;
+
+const defaultAdapterFactory: Pico8AdapterFactory = (env) =>
+	new ShellPico8Adapter({env});
+
+/** The default backstop: kill an export that never completes/exits after this many ms. */
+const DEFAULT_BACKSTOP_MS = 30_000;
+
+/**
+ * Registers `picopilot export`, the THIN structured wrapper over PICO-8's HTML
+ * export (`pico8 <cart> -export <name>.html -x`, the headless `-x` path, no
+ * display needed). It is NOT a `pico8` reimplementation: PICO-8 owns the bundle
+ * (an Emscripten runtime `.js` with the cart baked in, plus a shell `.html`).
+ * The value picopilot adds is the glue an agent should not hand-roll: resolve
+ * the cart, pick/create the output dir, name the pair `index.html` + `index.js`
+ * so a dest folder is directly serveable/showcase-ready, and return ONE
+ * structured result (output dir + file paths + the labelless-cart warning). It
+ * hard-requires PICO-8; absence is a first-class `pico8-not-found` value + a
+ * nonzero exit (mirrors `run`), never a crash or a hang. Live export is the
+ * manual/opt-in tier; the absent path is the CI-testable one.
+ *
+ * Two shapes, one command:
+ *  - default (standalone): keep the `index.html` + `index.js` pair; the html
+ *    references its sibling by name, so the dir plays directly (and `serve`
+ *    uses this internally).
+ *  - `--payload-only`: keep only the `.js` runtime payload; drop the shell page.
+ *    For a website that provides its OWN player shell (a Svelte component that
+ *    ports PICO-8's small bootstrap and loads the exported `.js`). The split is
+ *    a post-export file op the command owns, never the PICO-8 binary's concern.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to drive present/absent without the real binary.
+ */
+export function registerExport(
+	cli: Cli.Cli,
+	adapterFactory: Pico8AdapterFactory = defaultAdapterFactory,
+): void {
+	cli.command('export', {
+		description:
+			"Export a cart to a playable HTML bundle (index.html + index.js) via the user's PICO-8. Requires PICO-8.",
+		args: z.object({
+			cart: z
+				.string()
+				.default('main.p8')
+				.describe(
+					'The .p8 cart to export. Defaults to main.p8 in the current folder.',
+				),
+			dest: z
+				.string()
+				.optional()
+				.describe(
+					'Output folder (created if missing). Point it at a showcase dir (e.g. ./website/static/games/<slug>/). Defaults to an isolated temp dir.',
+				),
+		}),
+		options: z.object({
+			label: z
+				.string()
+				.optional()
+				.describe(
+					'Path to a 128x128 PNG to bake in as the cart __label__ (the export splash), for a cart that has none. Ignored if the cart already has a label.',
+				),
+			payloadOnly: z
+				.boolean()
+				.default(false)
+				.describe(
+					'Keep only the .js runtime payload (drop the shell .html), for a site that provides its own player component.',
+				),
+			backstopMs: z
+				.number()
+				.int()
+				.positive()
+				.default(DEFAULT_BACKSTOP_MS)
+				.describe(
+					'Safety backstop: kill PICO-8 after this many ms if the export never completes.',
+				),
+		}),
+		// 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`.'),
+		}),
+		output: z.object({
+			outDir: z
+				.string()
+				.describe('Absolute path of the folder the bundle was written to.'),
+			html: z
+				.string()
+				.optional()
+				.describe(
+					'Absolute path of the shell index.html (omitted with --payload-only).',
+				),
+			js: z.string().describe('Absolute path of the runtime payload index.js.'),
+			files: z
+				.array(z.string())
+				.describe('Absolute paths of every file the bundle contains.'),
+			labelWarning: z
+				.boolean()
+				.describe(
+					'True when the cart has no __label__: it exports with a blank/ugly splash.',
+				),
+		}),
+		examples: [
+			{description: 'Export main.p8 to a temp dir'},
+			{
+				description: 'Export a cart into a showcase folder',
+				args: {cart: 'game.p8', dest: './website/static/games/my-game'},
+			},
+			{
+				description: 'Bake a PNG as the label splash for a labelless cart',
+				args: {cart: 'game.p8', dest: './website/static/games/my-game'},
+				options: {label: './label.png'},
+			},
+			{
+				description:
+					'Export only the runtime payload for a site player component',
+				args: {cart: 'game.p8', dest: './website/static/games/my-game'},
+				options: {payloadOnly: true},
+			},
+		],
+		async run({args, options, env, error, ok}) {
+			const cartPath = isAbsolute(args.cart)
+				? args.cart
+				: resolve(process.cwd(), args.cart);
+
+			// A missing cart is a picopilot-side error, distinct from PICO-8 absence.
+			if (!existsSync(cartPath)) {
+				return error({
+					code: 'cart-not-found',
+					message: `no cart at ${cartPath}`,
+					exitCode: 1,
+				});
+			}
+
+			// --label <png>: bake a 128x128 PNG in as the cart's __label__ so a
+			// labelless cart gets a splash without an interactive F7 capture. We do
+			// NOT mutate the user's cart: we write a labeled copy NEXT TO it (same dir,
+			// so `#include main.lua` still resolves) and export that, then clean it up.
+			// A cart that ALREADY has a label wins (the flag is a fallback, not an
+			// override), matching the export precedence PICO-8 itself uses.
+			let exportCartPath = cartPath;
+			let labeledCopy: string | undefined;
+			if (options.label !== undefined) {
+				const labelPath = isAbsolute(options.label)
+					? options.label
+					: resolve(process.cwd(), options.label);
+				if (!existsSync(labelPath)) {
+					return error({
+						code: 'label-not-found',
+						message: `no label image at ${labelPath}`,
+						exitCode: 1,
+					});
+				}
+				try {
+					const cart = Cart.parse(readFileSync(cartPath, 'utf8'));
+					const existingLabel = cart.getSection('label');
+					if (existingLabel === undefined || existingLabel.trim() === '') {
+						const hex = labelHexFromPng(readFileSync(labelPath));
+						cart.setSection('label', hex);
+						labeledCopy = join(
+							dirname(cartPath),
+							`.picopilot-export-${process.pid}-${Date.now()}.p8`,
+						);
+						writeFileSync(labeledCopy, cart.serialize());
+						exportCartPath = labeledCopy;
+					}
+					// else: cart already has a label; keep it, ignore --label.
+				} catch (e) {
+					if (e instanceof LabelError) {
+						return error({
+							code: `label-${e.code}`,
+							message: e.message,
+							exitCode: 1,
+						});
+					}
+					if (e instanceof CartParseError) {
+						return error({
+							code: `cart-${e.code}`,
+							message: `could not parse the cart to inject a label: ${e.message}`,
+							exitCode: 1,
+						});
+					}
+					throw e;
+				}
+			}
+
+			// Output dir: a user-given dest (point it at the showcase), else an
+			// isolated temp dir. Create it so PICO-8 has somewhere to write.
+			const outDir =
+				args.dest !== undefined
+					? isAbsolute(args.dest)
+						? args.dest
+						: resolve(process.cwd(), args.dest)
+					: mkdtempSync(join(tmpdir(), 'picopilot-export-'));
+			if (!existsSync(outDir)) mkdirSync(outDir, {recursive: true});
+
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			const result = await adapter.export({
+				cartPath: exportCartPath,
+				outDir,
+				htmlName: EXPORT_HTML_NAME,
+				backstopMs: options.backstopMs,
+			});
+
+			// Remove the temporary labeled copy now that PICO-8 has read it (on every
+			// path below); best-effort, a leftover dotfile is not fatal.
+			if (labeledCopy !== undefined) {
+				try {
+					rmSync(labeledCopy);
+				} catch {
+					// ignore
+				}
+			}
+
+			if (!result.ok) {
+				// The two-tier structured failure: PICO-8 absent. The message carries
+				// the exact remedy + needs; the code is the handle.
+				return error({
+					code: result.reason,
+					message: `PICO-8 is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+					exitCode: 1,
+				});
+			}
+
+			let {htmlPath, jsPath, files, labelWarning} = result.value;
+
+			// PICO-8 must have produced the runtime payload; if not, the export failed
+			// (most often a labelless-cart bail that wrote nothing).
+			if (jsPath === undefined) {
+				return error({
+					code: 'export-failed',
+					message: labelWarning
+						? 'PICO-8 produced no bundle (the cart has no __label__ to embed). Give it one with --label <128x128.png>, or capture a label in PICO-8 (F7), then re-export.'
+						: 'PICO-8 produced no export bundle. Check the cart runs without a boot error.',
+					exitCode: 1,
+				});
+			}
+
+			// --payload-only: drop the shell .html; keep just the runtime payload the
+			// site's own player component loads. A post-export file op we own, not the
+			// binary's concern.
+			if (options.payloadOnly && htmlPath !== undefined) {
+				try {
+					rmSync(htmlPath);
+				} catch {
+					// A stubborn html is not fatal: the payload is what matters.
+				}
+				htmlPath = undefined;
+				files = listFiles(outDir);
+			}
+
+			const cta =
+				labelWarning && !options.payloadOnly
+					? {
+							description:
+								'The cart has no __label__, so the export splash is blank. Add one for a nicer bundle:',
+							commands: [
+								{
+									command: 'export --label <128x128.png>',
+									description:
+										'Bake a PNG in as the label splash, or capture one in PICO-8 (F7) before exporting.',
+								},
+							],
+						}
+					: undefined;
+
+			return ok(
+				{
+					outDir,
+					html: htmlPath,
+					js: jsPath,
+					files: [...files],
+					labelWarning,
+				},
+				cta === undefined ? undefined : {cta},
+			);
+		},
+	});
+}
+
+/** Absolute, sorted file paths currently in `dir` (post file-op re-scan). */
+function listFiles(dir: string): string[] {
+	if (!existsSync(dir)) return [];
+	return readdirSync(dir)
+		.sort()
+		.map((f) => join(dir, f));
+}