picopilot 0.0.0 → 0.1.1

package/src/commands/lint.test.ts

@@ -0,0 +1,137 @@
+import {execFileSync} from 'node:child_process';
+import {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 {
+	LintReport,
+	ShrinkoAdapter,
+	ShrinkoResult,
+} from '../engine/shrinko/index.js';
+import {parseLint, shrinkoNotFound} from '../engine/shrinko/index.js';
+import {type ShrinkoAdapterFactory, registerLint} from './lint.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-lint-'));
+	cartPath = join(dir, 'main.p8');
+	writeFileSync(cartPath, CART_TEXT);
+});
+afterEach(() => {
+	try {
+		execFileSync('rm', ['-rf', dir]);
+	} catch {
+		// ignore
+	}
+});
+
+/** A stub adapter whose `lint` returns whatever the test wires; `count`/`minify` unused here. */
+function stubAdapter(result: ShrinkoResult<LintReport>): ShrinkoAdapter {
+	return {
+		async count() {
+			throw new Error('not used');
+		},
+		async lint() {
+			return result;
+		},
+		async minify() {
+			throw new Error('not used');
+		},
+	};
+}
+
+async function runLint(
+	factory: ShrinkoAdapterFactory,
+	argv: string[] = ['lint', cartPath, '--json'],
+	env: Record<string, string | undefined> = {PATH: '/x'},
+) {
+	const cli = Cli.create('picopilot', {version: '0.0.0'});
+	registerLint(cli, factory);
+	let stdout = '';
+	let exitCode = 0;
+	await cli.serve(argv, {
+		stdout(s) {
+			stdout += s;
+		},
+		exit(code) {
+			exitCode = code;
+		},
+		env,
+	});
+	return {stdout, exitCode};
+}
+
+describe('parseLint: shrinko --lint output to structured findings', () => {
+	it('parses file:line:col: message lines, dropping the filename', () => {
+		const out = [
+			'Lint warnings:',
+			"lintme.p8:5:8: Local 'unused' isn't used",
+			"lintme.p8:6:4: Identifier 'undefined_global' not found",
+		].join('\n');
+		const {findings} = parseLint(out);
+		expect(findings).toHaveLength(2);
+		expect(findings[0]).toEqual({
+			line: 5,
+			col: 8,
+			message: "Local 'unused' isn't used",
+		});
+		expect(findings[1]?.message).toContain('undefined_global');
+	});
+
+	it('a clean cart (no warning lines) parses to zero findings, not an error', () => {
+		expect(parseLint('').findings).toEqual([]);
+		expect(parseLint('Lint warnings:\n').findings).toEqual([]);
+	});
+});
+
+describe('picopilot lint: present', () => {
+	it('reports findings as data (exit 0) and CTAs when there are warnings', async () => {
+		const {stdout, exitCode} = await runLint(() =>
+			stubAdapter({
+				ok: true,
+				value: {findings: [{line: 5, col: 8, message: "Local 'x' isn't used"}]},
+			}),
+		);
+		// Findings are DATA, not a failure exit.
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.clean).toBe(false);
+		expect(out.count).toBe(1);
+		expect(out.findings[0].message).toContain('x');
+	});
+
+	it('a clean cart reports clean=true and no CTA', async () => {
+		const {stdout, exitCode} = await runLint(() =>
+			stubAdapter({ok: true, value: {findings: []}}),
+		);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.clean).toBe(true);
+		expect(out.count).toBe(0);
+	});
+});
+
+describe('picopilot lint: shrinko absent + cart missing', () => {
+	it('returns structured shrinko-not-found + nonzero exit', async () => {
+		const {stdout, exitCode} = await runLint(() =>
+			stubAdapter(shrinkoNotFound()),
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('uv pip install shrinko');
+	});
+
+	it('cart-not-found is a distinct picopilot-side error', async () => {
+		const {stdout, exitCode} = await runLint(
+			() => stubAdapter({ok: true, value: {findings: []}}),
+			['lint', join(dir, 'nope.p8'), '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('no cart at');
+	});
+});

package/src/commands/lint.ts

@@ -0,0 +1,117 @@
+import {existsSync} from 'node:fs';
+import {isAbsolute, resolve} from 'node:path';
+import {type Cli, z} from 'incur';
+import {
+	type ShrinkoAdapter,
+	ShellShrinkoAdapter,
+} from '../engine/shrinko/index.js';
+
+/** See {@link import('./tokens.js').ShrinkoAdapterFactory}: lint reuses the same seam. */
+export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+
+const defaultAdapterFactory: ShrinkoAdapterFactory = (env) =>
+	new ShellShrinkoAdapter({env});
+
+/**
+ * Registers `picopilot lint` (US #4): surface PICO-8-specific issues (undefined
+ * globals, unused/duplicate locals, and, via the parsed findings, the classic
+ * gotchas) as STRUCTURED findings via shrinko8 `--lint`, so an agent catches
+ * them before running. Findings are DATA: a cart WITH warnings is a successful
+ * lint that reports them (exit 0), not a failure exit; only a broken cart or a
+ * missing dependency is an error.
+ *
+ * shrinko-backed: absent shrinko returns the structured `shrinko-not-found`
+ * error + nonzero exit (ADR-0002), mirroring `tokens`.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to drive present/absent without the real binary.
+ */
+export function registerLint(
+	cli: Cli.Cli,
+	adapterFactory: ShrinkoAdapterFactory = defaultAdapterFactory,
+): void {
+	cli.command('lint', {
+		description:
+			'Surface PICO-8 lint findings (undefined globals, unused/duplicate locals) via shrinko8. Requires shrinko.',
+		args: z.object({
+			cart: z
+				.string()
+				.default('main.p8')
+				.describe(
+					'The .p8 cart to lint. Defaults to main.p8 in the current folder.',
+				),
+		}),
+		env: z.object({
+			PATH: z
+				.string()
+				.optional()
+				.describe('Used to locate shrinko8 in the child process.'),
+		}),
+		output: z.object({
+			findings: z
+				.array(
+					z.object({
+						line: z.number().describe('1-based line in the cart.'),
+						col: z.number().describe('1-based column.'),
+						message: z.string().describe('The lint warning text.'),
+					}),
+				)
+				.describe(
+					'Every lint warning shrinko reported (empty when the cart is clean).',
+				),
+			clean: z.boolean().describe('True when there are no findings.'),
+			count: z.number().describe('Number of findings.'),
+		}),
+		examples: [
+			{description: 'Lint main.p8'},
+			{description: 'Lint a specific cart', args: {cart: 'game.p8'}},
+		],
+		async run({args, 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,
+				});
+			}
+
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			const result = await adapter.lint(cartPath);
+
+			if (!result.ok) {
+				return error({
+					code: result.reason,
+					message: `shrinko is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+					exitCode: 1,
+				});
+			}
+
+			const {findings} = result.value;
+			const clean = findings.length === 0;
+
+			// Findings are DATA, not a failure exit (an agent reads them and fixes the
+			// code). When there ARE findings, CTA toward the run/verify loop.
+			const cta = clean
+				? undefined
+				: {
+						description: `${findings.length} lint finding(s). Fix them, then re-check:`,
+						commands: [
+							{command: 'lint', description: 'Re-lint after fixing.'},
+							{
+								command: 'verify',
+								description: 'Run the static gate before running.',
+							},
+						],
+					};
+
+			return ok(
+				{findings: [...findings], clean, count: findings.length},
+				cta === undefined ? undefined : {cta},
+			);
+		},
+	});
+}

package/src/commands/minify.test.ts

@@ -0,0 +1,166 @@
+import {execFileSync} from 'node:child_process';
+import {existsSync, mkdtempSync, 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 type {
+	MinifyReport,
+	ShrinkoAdapter,
+	ShrinkoResult,
+} from '../engine/shrinko/index.js';
+import {shrinkoNotFound} from '../engine/shrinko/index.js';
+import {type ShrinkoAdapterFactory, registerMinify} from './minify.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-minify-'));
+	cartPath = join(dir, 'main.p8');
+	writeFileSync(cartPath, CART_TEXT);
+});
+afterEach(() => {
+	try {
+		execFileSync('rm', ['-rf', dir]);
+	} catch {
+		// ignore
+	}
+});
+
+/**
+ * A stub adapter whose `minify` records the outPath it was handed, WRITES a fake
+ * minified cart there (so the command's on-disk assertions are real), and
+ * returns a wired token delta. `count`/`lint` unused.
+ */
+function stubAdapter(
+	result: ShrinkoResult<MinifyReport> | 'write',
+	seen?: {outPath?: string},
+): ShrinkoAdapter {
+	return {
+		async count() {
+			throw new Error('not used');
+		},
+		async lint() {
+			throw new Error('not used');
+		},
+		async minify(_cart, outPath) {
+			if (seen !== undefined) seen.outPath = outPath;
+			if (result === 'write') {
+				writeFileSync(outPath, '-- minified\n');
+				return {
+					ok: true,
+					value: {beforeTokens: 100, afterTokens: 60, outPath},
+				};
+			}
+			return result;
+		},
+	};
+}
+
+async function runMinify(
+	factory: ShrinkoAdapterFactory,
+	argv: string[] = ['minify', cartPath, '--json'],
+	env: Record<string, string | undefined> = {PATH: '/x'},
+) {
+	const cli = Cli.create('picopilot', {version: '0.0.0'});
+	registerMinify(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 minify: compiler-style (ADR-0007)', () => {
+	it('writes <name>.min.p8 by default and reports the token delta', async () => {
+		const {stdout, exitCode} = await runMinify(() => stubAdapter('write'));
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.outPath).toBe(join(dir, 'main.min.p8'));
+		expect(out.beforeTokens).toBe(100);
+		expect(out.afterTokens).toBe(60);
+		expect(out.saved).toBe(40);
+		expect(existsSync(join(dir, 'main.min.p8'))).toBe(true);
+	});
+
+	it('NEVER mutates the source cart (the compiler invariant)', async () => {
+		const before = readFileSync(cartPath, 'utf8');
+		await runMinify(() => stubAdapter('write'));
+		expect(readFileSync(cartPath, 'utf8')).toBe(before); // source byte-identical
+	});
+
+	it('honours an explicit --out path', async () => {
+		const seen: {outPath?: string} = {};
+		const chosen = join(dir, 'dist', 'game.p8');
+		await runMinify(
+			() => stubAdapter('write', seen),
+			['minify', cartPath, '--out', chosen, '--json'],
+		);
+		expect(seen.outPath).toBe(chosen);
+	});
+});
+
+describe('picopilot minify: no-clobber + source guard', () => {
+	it('refuses to overwrite an existing output without --force', async () => {
+		writeFileSync(join(dir, 'main.min.p8'), 'existing artifact');
+		const {stdout, exitCode} = await runMinify(() => stubAdapter('write'));
+		expect(exitCode).not.toBe(0);
+		expect(stdout.toLowerCase()).toContain('refusing to overwrite');
+		// The existing artifact is untouched (the adapter never ran).
+		expect(readFileSync(join(dir, 'main.min.p8'), 'utf8')).toBe(
+			'existing artifact',
+		);
+	});
+
+	it('--force overwrites an existing output', async () => {
+		writeFileSync(join(dir, 'main.min.p8'), 'old');
+		const {exitCode} = await runMinify(
+			() => stubAdapter('write'),
+			['minify', cartPath, '--force', '--json'],
+		);
+		expect(exitCode).toBe(0);
+		expect(readFileSync(join(dir, 'main.min.p8'), 'utf8')).toContain(
+			'minified',
+		);
+	});
+
+	it('refuses --out pointing AT the source (no in-place mutation)', async () => {
+		const {stdout, exitCode} = await runMinify(
+			() => stubAdapter('write'),
+			['minify', cartPath, '--out', cartPath, '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout.toLowerCase()).toContain('must differ from the source');
+	});
+});
+
+describe('picopilot minify: shrinko absent + cart missing', () => {
+	it('returns structured shrinko-not-found (and writes nothing)', async () => {
+		const {stdout, exitCode} = await runMinify(() =>
+			stubAdapter(shrinkoNotFound()),
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('uv pip install shrinko');
+		expect(existsSync(join(dir, 'main.min.p8'))).toBe(false);
+	});
+
+	it('cart-not-found is a distinct picopilot-side error', async () => {
+		const {stdout, exitCode} = await runMinify(
+			() => stubAdapter('write'),
+			['minify', join(dir, 'nope.p8'), '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('no cart at');
+	});
+});

package/src/commands/minify.ts

@@ -0,0 +1,156 @@
+import {existsSync} from 'node:fs';
+import {dirname, isAbsolute, join, resolve} from 'node:path';
+import {type Cli, z} from 'incur';
+import {
+	type ShrinkoAdapter,
+	ShellShrinkoAdapter,
+} from '../engine/shrinko/index.js';
+
+/** See {@link import('./tokens.js').ShrinkoAdapterFactory}: minify reuses the same seam. */
+export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+
+const defaultAdapterFactory: ShrinkoAdapterFactory = (env) =>
+	new ShellShrinkoAdapter({env});
+
+/**
+ * Derives the default output path `<name>.min.p8` next to the source cart:
+ * `main.p8` -> `main.min.p8`, `game.p8.png` -> `game.min.p8.png` is NOT the
+ * case (we only special-case the final `.p8`); a plain `<name>.p8` becomes
+ * `<name>.min.p8`. Anything without a `.p8` suffix just gets `.min.p8` appended.
+ */
+function defaultOutPath(cartPath: string): string {
+	const dir = dirname(cartPath);
+	const base = cartPath.slice(dir.length + 1);
+	const out = base.endsWith('.p8')
+		? `${base.slice(0, -'.p8'.length)}.min.p8`
+		: `${base}.min.p8`;
+	return join(dir, out);
+}
+
+/**
+ * Registers `picopilot minify` (US #5, ADR-0007): run shrinko8's SAFE
+ * minification and write the result to a SEPARATE artifact (`<name>.min.p8` by
+ * default), reporting the before/after token delta. It is COMPILER-STYLE: the
+ * user's authored source (`main.p8` / the `#include`d `main.lua`) is NEVER
+ * touched, and it refuses to clobber an existing output unless `--force`.
+ *
+ * Safe-only by default (never aggressive-minify silently). shrinko-backed:
+ * absent shrinko returns the structured `shrinko-not-found` error + nonzero
+ * exit, mirroring `tokens`/`lint`.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to drive present/absent without the real binary.
+ */
+export function registerMinify(
+	cli: Cli.Cli,
+	adapterFactory: ShrinkoAdapterFactory = defaultAdapterFactory,
+): void {
+	cli.command('minify', {
+		description:
+			'Safe-minify a cart to a SEPARATE artifact (<name>.min.p8), reporting the token delta. Source untouched. Requires shrinko.',
+		args: z.object({
+			cart: z
+				.string()
+				.default('main.p8')
+				.describe(
+					'The .p8 cart to minify. Defaults to main.p8 in the current folder.',
+				),
+		}),
+		options: z.object({
+			out: z
+				.string()
+				.optional()
+				.describe(
+					'Output cart path. Defaults to <name>.min.p8 next to the source.',
+				),
+			force: z
+				.boolean()
+				.default(false)
+				.describe(
+					'Overwrite an existing output cart. Default off (no-clobber).',
+				),
+		}),
+		env: z.object({
+			PATH: z
+				.string()
+				.optional()
+				.describe('Used to locate shrinko8 in the child process.'),
+		}),
+		output: z.object({
+			outPath: z
+				.string()
+				.describe('Absolute path of the minified cart written.'),
+			beforeTokens: z.number().describe('Tokens in the source cart.'),
+			afterTokens: z.number().describe('Tokens in the minified cart.'),
+			saved: z.number().describe('Tokens reclaimed (before - after).'),
+		}),
+		examples: [
+			{description: 'Minify main.p8 to main.min.p8'},
+			{
+				description: 'Minify to a chosen path',
+				args: {cart: 'game.p8'},
+				options: {out: 'dist/game.p8'},
+			},
+		],
+		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,
+				});
+			}
+
+			const outPath =
+				options.out !== undefined
+					? isAbsolute(options.out)
+						? options.out
+						: resolve(process.cwd(), options.out)
+					: defaultOutPath(cartPath);
+
+			// Guard the source FIRST: never let --out point AT the source cart (that
+			// would be in-place mutation, which ADR-0007 forbids). Checked before the
+			// no-clobber guard so it wins even though the source obviously exists.
+			if (outPath === cartPath) {
+				return error({
+					code: 'output-is-source',
+					message: `--out must differ from the source cart (${cartPath}); minify never mutates the source`,
+					exitCode: 1,
+				});
+			}
+
+			// No-clobber (ADR-0007, mirrors init): refuse to overwrite an existing
+			// artifact unless --force, so a minify never silently destroys a prior one.
+			if (existsSync(outPath) && !options.force) {
+				return error({
+					code: 'output-exists',
+					message: `refusing to overwrite existing ${outPath}; pass --force to overwrite`,
+					exitCode: 1,
+				});
+			}
+
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			const result = await adapter.minify(cartPath, outPath);
+
+			if (!result.ok) {
+				return error({
+					code: result.reason,
+					message: `shrinko is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+					exitCode: 1,
+				});
+			}
+
+			const {beforeTokens, afterTokens} = result.value;
+			return ok({
+				outPath,
+				beforeTokens,
+				afterTokens,
+				saved: beforeTokens - afterTokens,
+			});
+		},
+	});
+}