picopilot 0.0.0 → 0.1.1

package/src/commands/serve.test.ts

@@ -0,0 +1,227 @@
+import {execFileSync} from 'node:child_process';
+import {existsSync, mkdtempSync, 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 type {
+	ExportOptions,
+	Pico8Adapter,
+	Pico8ExportResult,
+} from '../engine/pico8/index.js';
+import {pico8NotFound} from '../engine/pico8/index.js';
+import {
+	type CleanupRegistrar,
+	type Pico8AdapterFactory,
+	registerServe,
+	type ServerFactory,
+} from './serve.js';
+
+const CART_TEXT =
+	'pico-8 cartridge // http://www.pico-8.com\nversion 42\n__lua__\nprint("hi")\n';
+
+let dir: string;
+let cartPath: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'picopilot-serve-'));
+	cartPath = join(dir, 'main.p8');
+	writeFileSync(cartPath, CART_TEXT);
+});
+
+afterEach(() => {
+	try {
+		execFileSync('rm', ['-rf', dir]);
+	} catch {
+		// ignore
+	}
+});
+
+/**
+ * A stub adapter whose `export` writes the bundle into `outDir` so the serve
+ * loop can verify the export step ran and produced a payload, WITHOUT the paid
+ * binary. Records the {@link ExportOptions} for assertions.
+ */
+function stubAdapter(
+	result: Pico8ExportResult | 'writes-bundle' | 'writes-no-js',
+	seen?: {options?: ExportOptions},
+): Pico8Adapter {
+	const notUsed = () => {
+		throw new Error('not used by serve');
+	};
+	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></html>');
+				writeFileSync(js, '// runtime');
+				return {
+					ok: true,
+					value: {
+						htmlPath: html,
+						jsPath: js,
+						files: [html, js],
+						labelWarning: false,
+					},
+				};
+			}
+			if (result === 'writes-no-js') {
+				return {
+					ok: true,
+					value: {
+						htmlPath: undefined,
+						jsPath: undefined,
+						files: [],
+						labelWarning: true,
+					},
+				};
+			}
+			return result;
+		},
+	};
+}
+
+/**
+ * A fake {@link ServerFactory} that never opens a real socket: it records the
+ * root dir it was asked to serve and returns a dummy server + the port it would
+ * have bound. This keeps the serve loop testable with no dangling listener.
+ */
+function fakeServer(seen?: {rootDir?: string; port?: number}): ServerFactory {
+	return async (rootDir, port) => {
+		if (seen !== undefined) {
+			seen.rootDir = rootDir;
+			seen.port = port;
+		}
+		// A minimal object satisfying the return contract; nothing listens.
+		return {server: {close() {}} as never, port: port === 0 ? 49152 : port};
+	};
+}
+
+async function runServe(
+	factory: Pico8AdapterFactory,
+	serverFactory: ServerFactory,
+	argv: string[] = ['serve', cartPath, '--json'],
+	env: Record<string, string | undefined> = {PATH: '/does/not/matter'},
+	// Captures the cleanup fn instead of wiring real process signal handlers.
+	cleanupSink?: {cleanup?: () => void},
+) {
+	const cli = Cli.create('picopilot', {version: '0.0.0'});
+	const registerCleanup: CleanupRegistrar = (cleanup) => {
+		if (cleanupSink !== undefined) cleanupSink.cleanup = cleanup;
+	};
+	registerServe(cli, factory, serverFactory, registerCleanup);
+	let stdout = '';
+	let exitCode = 0;
+	await cli.serve(argv, {
+		stdout(s) {
+			stdout += s;
+		},
+		exit(code) {
+			exitCode = code;
+		},
+		env,
+	});
+	return {stdout, exitCode};
+}
+
+describe('picopilot serve: PICO-8 absent (serve always exports, so it requires PICO-8)', () => {
+	it('returns structured pico8-not-found + nonzero exit before serving anything', async () => {
+		const seen: {rootDir?: string} = {};
+		const {stdout, exitCode} = await runServe(
+			() => stubAdapter(pico8NotFound()),
+			fakeServer(seen),
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('set PICO8_PATH or install PICO-8');
+		// The server was never bound because the export failed first.
+		expect(seen.rootDir).toBeUndefined();
+	});
+});
+
+describe('picopilot serve: export-then-serve loop', () => {
+	it('exports the cart, then serves the export dir and reports the URL', async () => {
+		const exportSeen: {options?: ExportOptions} = {};
+		const serveSeen: {rootDir?: string; port?: number} = {};
+		const {stdout, exitCode} = await runServe(
+			() => stubAdapter('writes-bundle', exportSeen),
+			fakeServer(serveSeen),
+			['serve', cartPath, '--port', '8080', '--json'],
+		);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.url).toBe('http://127.0.0.1:8080/');
+		expect(out.port).toBe(8080);
+		// The dir served is exactly the dir the export wrote into (a temp dir).
+		expect(serveSeen.rootDir).toBe(exportSeen.options?.outDir);
+		expect(serveSeen.rootDir?.startsWith(tmpdir())).toBe(true);
+	});
+
+	it('registers a cleanup that removes the temp serve dir (no leak on a long-lived serve)', async () => {
+		const serveSeen: {rootDir?: string} = {};
+		const cleanupSink: {cleanup?: () => void} = {};
+		await runServe(
+			() => stubAdapter('writes-bundle'),
+			fakeServer(serveSeen),
+			['serve', cartPath, '--json'],
+			{PATH: '/does/not/matter'},
+			cleanupSink,
+		);
+		const serveDir = serveSeen.rootDir!;
+		// The dir exists while serving; the registered cleanup removes it on exit.
+		expect(existsSync(serveDir)).toBe(true);
+		expect(cleanupSink.cleanup).toBeTypeOf('function');
+		cleanupSink.cleanup!();
+		expect(existsSync(serveDir)).toBe(false);
+	});
+
+	it('reports the OS-assigned port when --port 0 is chosen', async () => {
+		const {stdout} = await runServe(
+			() => stubAdapter('writes-bundle'),
+			fakeServer(),
+			['serve', cartPath, '--port', '0', '--json'],
+		);
+		const out = JSON.parse(stdout);
+		// The fake maps 0 -> 49152 to model an OS-assigned free port.
+		expect(out.port).toBe(49152);
+		expect(out.url).toBe('http://127.0.0.1:49152/');
+	});
+});
+
+describe('picopilot serve: failure paths', () => {
+	it('errors when the export produced no bundle, and removes the temp dir immediately', async () => {
+		const serveSeen: {rootDir?: string} = {};
+		const exportSeen: {options?: ExportOptions} = {};
+		const {stdout, exitCode} = await runServe(
+			() => stubAdapter('writes-no-js', exportSeen),
+			fakeServer(serveSeen),
+			['serve', cartPath, '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(serveSeen.rootDir).toBeUndefined();
+		// The temp dir created before the failed export is cleaned up on the spot.
+		expect(existsSync(exportSeen.options!.outDir)).toBe(false);
+		// The labelless message redirects to the self-verify tools (run/playtest)
+		// and points at the real label remedy, NOT hand-editing main.p8: this is the
+		// exact loop weak models fell into.
+		const lower = stdout.toLowerCase();
+		expect(lower).toContain('picopilot run');
+		expect(lower).toContain('playtest');
+		expect(lower).toContain('export --label');
+		expect(lower).toContain('do not hand-edit main.p8');
+	});
+
+	it('errors with a nonzero exit when the cart path does not exist', async () => {
+		const {stdout, exitCode} = await runServe(
+			() => stubAdapter('writes-bundle'),
+			fakeServer(),
+			['serve', join(dir, 'nope.p8'), '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('no cart at');
+	});
+});

package/src/commands/serve.ts

@@ -0,0 +1,272 @@
+import {
+	createReadStream,
+	existsSync,
+	mkdtempSync,
+	rmSync,
+	statSync,
+} from 'node:fs';
+import {createServer, type Server} from 'node:http';
+import {tmpdir} from 'node:os';
+import {extname, isAbsolute, join, normalize, resolve} from 'node:path';
+import {type Cli, z} from 'incur';
+import {
+	EXPORT_HTML_NAME,
+	type Pico8Adapter,
+	ShellPico8Adapter,
+} from '../engine/pico8/index.js';
+
+/**
+ * Injects the PICO-8 adapter `serve` uses (defaults to the shell adapter). Same
+ * seam as `export`/`run`: a test passes a stub so the export step needs no paid
+ * binary, and the child `env` (`PICO8_PATH`/`PATH`) stays isolated.
+ */
+export type Pico8AdapterFactory = (env: NodeJS.ProcessEnv) => Pico8Adapter;
+
+const defaultAdapterFactory: Pico8AdapterFactory = (env) =>
+	new ShellPico8Adapter({env});
+
+/**
+ * Injects the HTTP-server factory `serve` binds. The default is a zero-dep
+ * `node:http` static server over the export dir; a test injects a fake to assert
+ * the serve loop WITHOUT opening a real socket. The factory returns the started
+ * server plus the bound port (so `:0` -> an OS-assigned port is observable).
+ */
+export type ServerFactory = (
+	rootDir: string,
+	port: number,
+) => Promise<{server: Server; port: number}>;
+
+const DEFAULT_PORT = 5858;
+const DEFAULT_BACKSTOP_MS = 30_000;
+
+/**
+ * Best-effort recursive removal of the temp export dir, swallowing any error (a
+ * cleanup failure must never mask the command's own result or crash on exit).
+ */
+function removeDir(dir: string): void {
+	try {
+		rmSync(dir, {recursive: true, force: true});
+	} catch {
+		// A stubborn temp dir is not fatal; the OS reaps it eventually.
+	}
+}
+
+/**
+ * Registers a one-shot cleanup for the serving case: `serve` runs until the user
+ * interrupts it (the socket keeps the process alive), so the temp export dir is
+ * removed on SIGINT/SIGTERM and on normal `exit`. The handler fires at most once.
+ * The default uses `process`; a test injects a fake to assert the wiring without
+ * touching real signal handlers.
+ */
+export type CleanupRegistrar = (cleanup: () => void) => void;
+
+const defaultCleanupRegistrar: CleanupRegistrar = (cleanup) => {
+	let done = false;
+	const once = (): void => {
+		if (done) return;
+		done = true;
+		cleanup();
+	};
+	process.once('exit', once);
+	// On a signal, run cleanup then re-exit so the temp dir is gone even on Ctrl-C.
+	process.once('SIGINT', () => {
+		once();
+		process.exit(130);
+	});
+	process.once('SIGTERM', () => {
+		once();
+		process.exit(143);
+	});
+};
+
+/** MIME types the static server needs for a PICO-8 export (html + the runtime js). */
+const MIME: Record<string, string> = {
+	'.html': 'text/html; charset=utf-8',
+	'.js': 'text/javascript; charset=utf-8',
+	'.wasm': 'application/wasm',
+	'.png': 'image/png',
+	'.json': 'application/json; charset=utf-8',
+	'.css': 'text/css; charset=utf-8',
+};
+
+/**
+ * The default {@link ServerFactory}: a minimal, zero-dependency `node:http`
+ * static file server rooted at `rootDir`. It resolves `/` to `index.html`,
+ * path-traversal-guards every request against `rootDir`, and streams files with
+ * a best-effort content type. It exists to PLAY an export locally, not to be a
+ * production server. Binding `:0` yields an OS-assigned port, reported back so
+ * the command can print the real URL.
+ */
+const defaultServerFactory: ServerFactory = (rootDir, port) =>
+	new Promise((resolvePromise, reject) => {
+		const server = createServer((req, res) => {
+			const urlPath = decodeURIComponent((req.url ?? '/').split('?')[0]!);
+			// Resolve the request against the root and guard against traversal: the
+			// resolved path must stay inside rootDir.
+			const rel = normalize(urlPath).replace(/^(\.\.[/\\])+/, '');
+			let filePath = join(rootDir, rel);
+			if (!filePath.startsWith(rootDir)) {
+				res.writeHead(403).end('forbidden');
+				return;
+			}
+			try {
+				if (existsSync(filePath) && statSync(filePath).isDirectory()) {
+					filePath = join(filePath, 'index.html');
+				}
+				if (!existsSync(filePath)) {
+					res.writeHead(404).end('not found');
+					return;
+				}
+				res.writeHead(200, {
+					'content-type':
+						MIME[extname(filePath).toLowerCase()] ?? 'application/octet-stream',
+				});
+				createReadStream(filePath).pipe(res);
+			} catch {
+				res.writeHead(500).end('server error');
+			}
+		});
+		server.on('error', reject);
+		server.listen(port, '127.0.0.1', () => {
+			const addr = server.address();
+			const bound =
+				typeof addr === 'object' && addr !== null ? addr.port : port;
+			resolvePromise({server, port: bound});
+		});
+	});
+
+/**
+ * Registers `picopilot serve`, the "play this cart in a browser" loop. It ALWAYS
+ * exports first (the quick round-trip: cart -> standalone HTML bundle -> local
+ * server -> URL you open), so it takes a cart path, not a pre-built dir. The
+ * export step hard-requires PICO-8 (absence is the structured `pico8-not-found`
+ * value + a nonzero exit, mirroring `run`/`export`); the static server itself is
+ * a zero-dep `node:http` file server over the temp export dir, so no extra
+ * dependency and no ~/Desktop pollution.
+ *
+ * It is distinct from `export`: `export` PRODUCES a bundle at a chosen dest (for
+ * the showcase); `serve` throws the bundle in a temp dir and serves it for a
+ * quick manual play. It runs until interrupted (the server keeps the process
+ * alive), which is why the injected {@link ServerFactory} seam lets a test drive
+ * the export + bind path without leaving a real socket open.
+ *
+ * @param adapterFactory injects the PICO-8 adapter (defaults to the shell one).
+ * @param serverFactory injects the HTTP server (defaults to the zero-dep static
+ *   server); a test passes a fake to assert the loop without a real socket.
+ * @param registerCleanup injects the exit/signal cleanup wiring (defaults to the
+ *   real `process` handlers); a test passes a fake to capture the cleanup fn.
+ */
+export function registerServe(
+	cli: Cli.Cli,
+	adapterFactory: Pico8AdapterFactory = defaultAdapterFactory,
+	serverFactory: ServerFactory = defaultServerFactory,
+	registerCleanup: CleanupRegistrar = defaultCleanupRegistrar,
+): void {
+	cli.command('serve', {
+		description:
+			'Export a cart and serve it locally so a HUMAN can play it in a browser (for SHARING a playable build). Requires PICO-8, and a cart __label__. To verify your OWN build works, use `picopilot run` (screenshots) or `picopilot playtest` instead: serve is not the self-verification path.',
+		args: z.object({
+			cart: z
+				.string()
+				.default('main.p8')
+				.describe(
+					'The .p8 cart to export and serve. Defaults to main.p8 in the current folder.',
+				),
+		}),
+		options: z.object({
+			port: z
+				.number()
+				.int()
+				.min(0)
+				.max(65535)
+				.default(DEFAULT_PORT)
+				.describe('Port to serve on (0 = an OS-assigned free port).'),
+			backstopMs: z
+				.number()
+				.int()
+				.positive()
+				.default(DEFAULT_BACKSTOP_MS)
+				.describe('Safety backstop for the export step.'),
+		}),
+		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({
+			url: z.string().describe('The local URL to open in a browser.'),
+			port: z.number().describe('The port the server bound to.'),
+			serveDir: z
+				.string()
+				.describe('The temp dir the export bundle was served from.'),
+		}),
+		examples: [
+			{description: 'Export and serve main.p8'},
+			{description: 'Serve a specific cart', args: {cart: 'game.p8'}},
+			{
+				description: 'Serve on a chosen port',
+				args: {cart: 'game.p8'},
+				options: {port: 8080},
+			},
+		],
+		async run({args, options, env, error, ok}) {
+			const cartPath = isAbsolute(args.cart)
+				? args.cart
+				: resolve(process.cwd(), args.cart);
+
+			if (!existsSync(cartPath)) {
+				return error({
+					code: 'cart-not-found',
+					message: `no cart at ${cartPath}`,
+					exitCode: 1,
+				});
+			}
+
+			// Always export first, into an isolated temp dir (never a user path or
+			// ~/Desktop). The bundle is the standalone pair the static server plays.
+			const serveDir = mkdtempSync(join(tmpdir(), 'picopilot-serve-'));
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			const result = await adapter.export({
+				cartPath,
+				outDir: serveDir,
+				htmlName: EXPORT_HTML_NAME,
+				backstopMs: options.backstopMs,
+			});
+
+			if (!result.ok) {
+				// Nothing is being served: remove the temp dir now, not on exit.
+				removeDir(serveDir);
+				return error({
+					code: result.reason,
+					message: `PICO-8 is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+					exitCode: 1,
+				});
+			}
+
+			if (result.value.jsPath === undefined) {
+				removeDir(serveDir);
+				return error({
+					code: 'export-failed',
+					message: result.value.labelWarning
+						? 'PICO-8 produced no bundle: this cart has no __label__ (the export splash), which the browser export needs. To just SEE your own build work, use `picopilot run` or `picopilot playtest` (no label needed) instead of serve. If you genuinely want a browser build to SHARE, bake a label first with `picopilot export --label <128x128.png>` (do NOT hand-edit main.p8), then re-serve.'
+						: 'PICO-8 produced no export bundle. Check the cart runs without a boot error (via `picopilot run`).',
+					exitCode: 1,
+				});
+			}
+
+			const {server, port} = await serverFactory(serveDir, options.port);
+			const url = `http://127.0.0.1:${port}/`;
+
+			// The server keeps the process alive until interrupted; the temp export dir
+			// is reaped on SIGINT/SIGTERM/exit so a long-lived serve leaves no leak.
+			// `server` is referenced so its lifetime is the command's; a test's fake
+			// resolves without a real socket.
+			registerCleanup(() => removeDir(serveDir));
+			void server;
+
+			return ok({url, port, serveDir});
+		},
+	});
+}