picopilot 0.0.0 → 0.1.1

package/src/commands/tokens.test.ts

@@ -0,0 +1,212 @@
+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 {
+	CountReport,
+	ShrinkoAdapter,
+	ShrinkoResult,
+} from '../engine/shrinko/index.js';
+import {shrinkoNotFound} from '../engine/shrinko/index.js';
+import {type ShrinkoAdapterFactory, registerTokens} from './tokens.js';
+
+/** A trivial but valid cart the command reads (existence + a path to hand shrinko). */
+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-tokens-'));
+	cartPath = join(dir, 'main.p8');
+	writeFileSync(cartPath, CART_TEXT);
+});
+
+afterEach(() => {
+	try {
+		execFileSync('rm', ['-rf', dir]);
+	} catch {
+		// ignore
+	}
+});
+
+/**
+ * A stub {@link ShrinkoAdapter} standing in for BOTH a shrinko-present shell
+ * adapter and a hypothetical native-TS adapter. It never spawns anything, so no
+ * test depends on shrinko being installed. `count` returns whatever result the
+ * test wired.
+ */
+function stubAdapter(result: ShrinkoResult<CountReport>): ShrinkoAdapter {
+	return {
+		async count() {
+			return result;
+		},
+	};
+}
+
+function present(over: boolean): ShrinkoResult<CountReport> {
+	return {
+		ok: true,
+		// Over: 9001 tokens > the 8192 budget. Under: a small cart.
+		value: over
+			? {
+					tokens: 9001,
+					tokensPct: 109,
+					chars: 34000,
+					charsPct: 52,
+					compressed: 13000,
+					compressedPct: 82,
+				}
+			: {
+					tokens: 512,
+					tokensPct: 6,
+					chars: 1840,
+					charsPct: 2,
+					compressed: 980,
+					compressedPct: 6,
+				},
+	};
+}
+
+/**
+ * Drives `picopilot tokens` through incur's `serve` DI with an INJECTED adapter
+ * factory (the seam), capturing stdout + exit without the real environment or
+ * the real binary. `env` defaults to a bare PATH the (stub) adapter ignores.
+ */
+async function runTokens(
+	factory: ShrinkoAdapterFactory,
+	argv: string[] = ['tokens', cartPath, '--json'],
+	env: Record<string, string | undefined> = {PATH: '/does/not/matter'},
+) {
+	// Use a UNIQUE cli name (not the real 'picopilot'), so incur's skills-freshness
+	// check (`SyncSkills.readHash(name)` + `hasInstalledSkills(name)`) finds NO
+	// stored hash for it and never attaches a "Skills are out of date" CTA. Under
+	// the full parallel run the real `picopilot` skill hash (in $XDG_DATA_HOME) goes
+	// stale (the skills test installs/removes skills concurrently), which would
+	// otherwise inject that ambient CTA and flakily break `expect(cta).toBeUndefined()`.
+	// A unit test of `tokens` must not depend on the machine's installed-skills state.
+	const cli = Cli.create('picopilot-tokens-test', {version: '0.0.0'});
+	registerTokens(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 tokens: present (parses --count into the budget struct)', () => {
+	it('reports {tokens, pct, chars, compressed} under budget with no minify CTA', async () => {
+		const {stdout, exitCode} = await runTokens(() =>
+			stubAdapter(present(false)),
+		);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.tokens).toBe(512);
+		expect(out.chars).toBe(1840);
+		expect(out.compressed).toBe(980);
+		expect(out.budget).toBe(8192);
+		expect(out.overBudget).toBe(false);
+		// 512 / 8192 ≈ 6%.
+		expect(out.pct).toBe(6);
+		// Under budget: no minify CTA.
+		expect(out.cta).toBeUndefined();
+		expect(JSON.stringify(out)).not.toContain('minify');
+	});
+
+	it('reports over budget and CTAs to minify', async () => {
+		const {stdout, exitCode} = await runTokens(() =>
+			stubAdapter(present(true)),
+		);
+		// Over budget is still a successful count (exit 0); the CTA drives the fix.
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.tokens).toBe(9001);
+		expect(out.overBudget).toBe(true);
+		// 9001 / 8192 ≈ 110%.
+		expect(out.pct).toBe(110);
+		// The over-budget → minify CTA is present (incur prefixes the CLI name).
+		expect(out.cta.commands[0].command).toContain('minify');
+	});
+});
+
+describe('picopilot tokens: absent (structured shrinko-not-found + nonzero exit)', () => {
+	it('returns the exact structured failure and a nonzero exit, never a crash', async () => {
+		const {stdout, exitCode} = await runTokens(() =>
+			stubAdapter(shrinkoNotFound()),
+		);
+		expect(exitCode).not.toBe(0);
+		const out = JSON.parse(stdout);
+		// incur error envelope: the reason is the machine code, the exact remedy is
+		// carried in the message so an agent reading only the message learns the fix.
+		expect(out.code).toBe('shrinko-not-found');
+		expect(out.message).toContain('uv pip install shrinko');
+		expect(out.message).toContain('python>=3.8');
+	});
+});
+
+describe('picopilot tokens: seam-swap (a stub adapter leaves output/exit unchanged)', () => {
+	it('produces byte-identical public output whether the adapter is A or B', async () => {
+		// Two DIFFERENT adapter implementations returning the SAME count value must
+		// yield the SAME command output + exit: the command depends only on the
+		// interface, so a native-TS shrinko drops in without a visible change.
+		const value = present(true);
+		// A: returns the value synchronously-resolved.
+		const adapterA: ShrinkoAdapter = {
+			async count() {
+				return value;
+			},
+		};
+		// B: a DIFFERENT implementation (extra async work, freshly-built struct) that
+		// yields the same count. Stands in for a native-TS shrinko behind the seam.
+		const adapterB: ShrinkoAdapter = {
+			async count() {
+				await Promise.resolve();
+				const v = value.ok ? value.value : undefined;
+				if (v === undefined) throw new Error('unreachable');
+				return {ok: true, value: {...v}};
+			},
+		};
+
+		const a = await runTokens(() => adapterA);
+		const b = await runTokens(() => adapterB);
+		expect(a.stdout).toBe(b.stdout);
+		expect(a.exitCode).toBe(b.exitCode);
+	});
+
+	it('the injected factory receives the incur-resolved env (PATH isolation lever)', async () => {
+		let seenEnv: NodeJS.ProcessEnv | undefined;
+		const factory: ShrinkoAdapterFactory = (env) => {
+			seenEnv = env;
+			return stubAdapter(present(false));
+		};
+		await runTokens(factory, ['tokens', cartPath, '--json'], {
+			PATH: '/isolated/bin',
+		});
+		// The command handed the adapter exactly the overridden env, so the child's
+		// PATH is controllable from the test without touching the real environment.
+		expect(seenEnv?.PATH).toBe('/isolated/bin');
+	});
+});
+
+describe('picopilot tokens: a missing cart is a distinct error (not shrinko-not-found)', () => {
+	it('errors with cart-not-found + nonzero exit when the cart path does not exist', async () => {
+		const {stdout, exitCode} = await runTokens(
+			() => stubAdapter(present(false)),
+			['tokens', join(dir, 'nope.p8'), '--json'],
+		);
+		expect(exitCode).not.toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.code).toBe('cart-not-found');
+	});
+});

package/src/commands/tokens.ts

@@ -0,0 +1,168 @@
+import {existsSync} from 'node:fs';
+import {isAbsolute, resolve} from 'node:path';
+import {type Cli, z} from 'incur';
+
+import {
+	type ShrinkoAdapter,
+	ShrinkoParseError,
+	ShellShrinkoAdapter,
+} from '../engine/shrinko/index.js';
+
+/** PICO-8's Lua token budget. A cart over this will not load in PICO-8 (US #3). */
+export const TOKEN_BUDGET = 8192;
+
+/**
+ * Builds the {@link ShrinkoAdapter} a command uses, given the incur-resolved
+ * env. The default is the shell-out {@link ShellShrinkoAdapter}, whose child
+ * process inherits ONLY this `env` (its `PATH` is the test isolation lever).
+ *
+ * A test passes its own factory to {@link registerTokens} to SWAP a stub
+ * adapter (the seam-swap contract): the command's public output/exit must be
+ * unchanged whether the real shell adapter or a native-TS stub is behind the
+ * seam, because the command only ever talks to the {@link ShrinkoAdapter}
+ * interface.
+ */
+export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+
+const defaultAdapterFactory: ShrinkoAdapterFactory = (env) =>
+	new ShellShrinkoAdapter({env});
+
+/**
+ * Registers `picopilot tokens` (US #3), the first shrinko-backed command.
+ *
+ * It reports `{tokens, pct, chars, compressed}` for a cart against the 8,192
+ * token budget via shrinko8 `--count`, and CTAs to `minify` when over budget so
+ * the agent is led straight to the fix (the detect-then-fix loop, ADR CTAs).
+ *
+ * Two-tier contract (ADR-0002): `tokens` is shrinko-BACKED, so with shrinko
+ * ABSENT it returns the structured `shrinko-not-found` error (nonzero exit,
+ * exact remedy `uv pip install shrinko`) rather than crashing or reporting a
+ * hollow zero. The dependency is reached entirely through the {@link
+ * ShrinkoAdapter} seam, so a native-TS shrinko would satisfy this command
+ * unchanged.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to swap the seam and to drive present/absent without the
+ *   real binary.
+ */
+export function registerTokens(
+	cli: Cli.Cli,
+	adapterFactory: ShrinkoAdapterFactory = defaultAdapterFactory,
+): void {
+	cli.command('tokens', {
+		description:
+			'Count a cart against the 8,192-token PICO-8 budget (via shrinko8 --count). Requires shrinko.',
+		args: z.object({
+			cart: z
+				.string()
+				.default('main.p8')
+				.describe(
+					'The .p8 cart to count. Defaults to main.p8 in the current folder.',
+				),
+		}),
+		// Declaring PATH here makes incur resolve it from the (test-overridable)
+		// env source and hand it to us, so we pass a controlled PATH to the child.
+		env: z.object({
+			PATH: z
+				.string()
+				.optional()
+				.describe('Used to locate shrinko8 in the child process.'),
+		}),
+		output: z.object({
+			tokens: z.number().describe('The token count shrinko reported.'),
+			pct: z
+				.number()
+				.describe(
+					'tokens as a percentage of the 8,192 budget (rounded); >100 means over budget.',
+				),
+			chars: z.number().describe('The character count shrinko reported.'),
+			compressed: z
+				.number()
+				.optional()
+				.describe('The compressed byte count (absent for some input formats).'),
+			budget: z
+				.number()
+				.describe('The token budget the percentage is against (8192).'),
+			overBudget: z.boolean().describe('True when tokens exceed the budget.'),
+		}),
+		examples: [
+			{description: 'Count main.p8'},
+			{description: 'Count 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);
+
+			// A missing cart is a picopilot-side error, distinct from shrinko absence:
+			// surface it clearly instead of letting shrinko fail opaquely on the path.
+			if (!existsSync(cartPath)) {
+				return error({
+					code: 'cart-not-found',
+					message: `no cart at ${cartPath}`,
+					exitCode: 1,
+				});
+			}
+
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+
+			let result: Awaited<ReturnType<ShrinkoAdapter['count']>>;
+			try {
+				result = await adapter.count(cartPath);
+			} catch (e) {
+				// shrinko RAN but its output was unparseable (version/format drift):
+				// a distinct `shrinko-failed`, NOT `shrinko-not-found` (which is absence).
+				if (e instanceof ShrinkoParseError) {
+					return error({
+						code: 'shrinko-failed',
+						message: `shrinko ran but its --count output could not be parsed: ${e.message}`,
+						exitCode: 1,
+					});
+				}
+				throw e;
+			}
+
+			if (!result.ok) {
+				// The two-tier structured failure (ADR-0002 / US #17): shrinko absent.
+				// The message CARRIES the exact remedy + needs so an agent reading only
+				// the message still learns the fix; the code is the machine handle.
+				return error({
+					code: result.reason,
+					message: `shrinko is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+					exitCode: 1,
+				});
+			}
+
+			const {tokens, chars, compressed} = result.value;
+			const pct = Math.round((tokens / TOKEN_BUDGET) * 100);
+			const overBudget = tokens > TOKEN_BUDGET;
+
+			// Over budget → CTA to `minify` (the detect-then-fix loop). Under budget
+			// needs no CTA: nothing to do.
+			const cta = overBudget
+				? {
+						description: 'Over the 8,192-token budget. Reclaim tokens with:',
+						commands: [
+							{
+								command: 'minify',
+								description:
+									'Safe-minify the cart to reduce tokens without changing behaviour.',
+							},
+						],
+					}
+				: undefined;
+
+			return ok(
+				{
+					tokens,
+					pct,
+					chars,
+					compressed,
+					budget: TOKEN_BUDGET,
+					overBudget,
+				},
+				cta === undefined ? undefined : {cta},
+			);
+		},
+	});
+}

package/src/commands/verify.test.ts

@@ -0,0 +1,238 @@
+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 {
+	CountReport,
+	ShrinkoAdapter,
+	ShrinkoResult,
+} from '../engine/shrinko/index.js';
+import {shrinkoNotFound} from '../engine/shrinko/index.js';
+import {
+	GATE_INCAPABLE_EXIT,
+	type ShrinkoAdapterFactory,
+	registerVerify,
+} from './verify.js';
+
+/** A well-formed cart: parses AND round-trips cleanly (passes integrity). */
+const GOOD_CART =
+	'pico-8 cartridge // http://www.pico-8.com\nversion 42\n__lua__\nprint("hi")\n';
+
+/**
+ * A MALFORMED cart: no `version N` line after the header, so `Cart.parse`
+ * throws a `missing-version` `CartParseError` and integrity fails.
+ */
+const MALFORMED_CART =
+	'pico-8 cartridge // http://www.pico-8.com\n__lua__\nprint("hi")\n';
+
+let dir: string;
+let cartPath: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'picopilot-verify-'));
+	cartPath = join(dir, 'main.p8');
+	writeFileSync(cartPath, GOOD_CART);
+});
+
+afterEach(() => {
+	try {
+		execFileSync('rm', ['-rf', dir]);
+	} catch {
+		// ignore
+	}
+});
+
+/**
+ * A stub {@link ShrinkoAdapter} standing in for a shrinko-present shell adapter
+ * (or a native-TS one). It never spawns anything, so no test depends on shrinko
+ * being installed. `count` returns whatever result the test wired.
+ */
+function stubAdapter(result: ShrinkoResult<CountReport>): ShrinkoAdapter {
+	return {
+		async count() {
+			return result;
+		},
+	};
+}
+
+/** A present-shrinko count: `over` picks an over-budget vs under-budget value. */
+function present(over: boolean): ShrinkoResult<CountReport> {
+	return {
+		ok: true,
+		value: over
+			? {
+					tokens: 9001,
+					tokensPct: 109,
+					chars: 34000,
+					charsPct: 52,
+					compressed: 13000,
+					compressedPct: 82,
+				}
+			: {
+					tokens: 512,
+					tokensPct: 6,
+					chars: 1840,
+					charsPct: 2,
+					compressed: 980,
+					compressedPct: 6,
+				},
+	};
+}
+
+/**
+ * Drives `picopilot verify` through incur's `serve` DI with an INJECTED adapter
+ * factory (the seam), capturing stdout + exit without the real environment or
+ * binary. `--json` so the structured envelope is asserted directly.
+ */
+async function runVerify(
+	factory: ShrinkoAdapterFactory,
+	cart: string = cartPath,
+	env: Record<string, string | undefined> = {PATH: '/does/not/matter'},
+) {
+	// Unique cli name (not 'picopilot') so incur's skills-freshness check finds no
+	// stored hash and never injects an ambient "Skills are out of date" CTA. Under
+	// the full parallel run that CTA would land as cta.commands[0] and flakily break
+	// the verify->run CTA assertion. (Same isolation as tokens.test.ts.)
+	const cli = Cli.create('picopilot-verify-test', {version: '0.0.0'});
+	registerVerify(cli, factory);
+	let stdout = '';
+	let exitCode = 0;
+	await cli.serve(['verify', cart, '--json'], {
+		stdout(s) {
+			stdout += s;
+		},
+		exit(code) {
+			exitCode = code;
+		},
+		env,
+	});
+	return {stdout, exitCode};
+}
+
+describe('picopilot verify: pass (integrity + tokens both green)', () => {
+	it('returns one structured envelope with an overall pass and per-check results', async () => {
+		const {stdout, exitCode} = await runVerify(() =>
+			stubAdapter(present(false)),
+		);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.status).toBe('pass');
+		expect(out.checks.integrity).toBe(true);
+		expect(out.checks.tokens).toBe(true);
+		expect(out.tokens).toBe(512);
+		expect(out.budget).toBe(8192);
+	});
+
+	it('SELF-SCOPES: the envelope states it is static and passing does not mean the cart runs', async () => {
+		const {stdout} = await runVerify(() => stubAdapter(present(false)));
+		const out = JSON.parse(stdout);
+		expect(out.scope.toLowerCase()).toContain('static');
+		// The connotation guard: passing must NOT be claimed as "the cart runs".
+		expect(out.scope.toLowerCase()).toContain('does not mean the cart runs');
+	});
+
+	it('green verify CTAs to `run` (well-formed → now confirm it boots)', async () => {
+		const {stdout} = await runVerify(() => stubAdapter(present(false)));
+		const out = JSON.parse(stdout);
+		// incur prefixes the CLI name onto the CTA command.
+		expect(out.cta.commands[0].command).toContain('run');
+	});
+});
+
+describe('picopilot verify: fail (a static check flunked, nonzero exit)', () => {
+	it('fails when tokens are over budget', async () => {
+		const {stdout, exitCode} = await runVerify(() =>
+			stubAdapter(present(true)),
+		);
+		expect(exitCode).toBe(1);
+		const out = JSON.parse(stdout);
+		expect(out.code).toBe('verify-failed');
+		// NOT reported as pass, and NOT the gate-incapable code.
+		expect(out.code).not.toBe('gate-incapable');
+		expect(out.message).toContain('budget');
+		// Still self-scopes on failure.
+		expect(out.message.toLowerCase()).toContain('static');
+	});
+
+	it('fails when the cart is malformed (integrity), independent of PICO-8', async () => {
+		writeFileSync(cartPath, MALFORMED_CART);
+		const {stdout, exitCode} = await runVerify(() =>
+			stubAdapter(present(false)),
+		);
+		expect(exitCode).toBe(1);
+		const out = JSON.parse(stdout);
+		expect(out.code).toBe('verify-failed');
+		expect(out.message).toContain('integrity');
+	});
+});
+
+describe('picopilot verify: gate-incapable (shrinko absent, the regression guard)', () => {
+	it('shrinko absent → DISTINCT gate-incapable outcome with a nonzero exit, NEVER green', async () => {
+		const {stdout, exitCode} = await runVerify(() =>
+			stubAdapter(shrinkoNotFound()),
+		);
+		// Nonzero, and specifically the distinct gate-incapable exit code.
+		expect(exitCode).not.toBe(0);
+		expect(exitCode).toBe(GATE_INCAPABLE_EXIT);
+		const out = JSON.parse(stdout);
+		// A categorically DISTINCT outcome: not pass, not the ordinary fail.
+		expect(out.code).toBe('gate-incapable');
+		expect(out.code).not.toBe('verify-failed');
+		// It names the missing capability + the remedy so the agent can enable it.
+		expect(out.message).toContain('shrinko');
+		expect(out.message).toContain('uv pip install shrinko');
+	});
+
+	it('REGRESSION GUARD: shrinko absent NEVER reports green, even for a perfect cart', async () => {
+		// The cart is well-formed (integrity would pass). If verify ever let a clean
+		// cart go green without checking tokens, THIS is the gate-as-theatre bug.
+		const {stdout, exitCode} = await runVerify(() =>
+			stubAdapter(shrinkoNotFound()),
+		);
+		expect(exitCode).not.toBe(0);
+		const out = JSON.parse(stdout);
+		// Must NOT be a success envelope: no `status: 'pass'`.
+		expect(out.status).not.toBe('pass');
+		expect(out.code).toBe('gate-incapable');
+	});
+
+	it('gate-incapable is a distinct exit code from fail (an agent can branch on it)', async () => {
+		const incapable = await runVerify(() => stubAdapter(shrinkoNotFound()));
+		const failed = await runVerify(() => stubAdapter(present(true)));
+		expect(incapable.exitCode).toBe(GATE_INCAPABLE_EXIT);
+		expect(failed.exitCode).toBe(1);
+		expect(incapable.exitCode).not.toBe(failed.exitCode);
+	});
+});
+
+describe('picopilot verify: no PICO-8 dependency (it never runs the cart)', () => {
+	it('passes with no PICO8_PATH / pico8 anywhere in env (static gate)', async () => {
+		// A bare env with only a PATH that has no pico8: verify still passes, proving
+		// it never reaches for PICO-8.
+		const {stdout, exitCode} = await runVerify(
+			() => stubAdapter(present(false)),
+			cartPath,
+			{
+				PATH: '/empty',
+			},
+		);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.status).toBe('pass');
+	});
+});
+
+describe('picopilot verify: a missing cart is a distinct error (not fail, not gate-incapable)', () => {
+	it('errors with cart-not-found + nonzero exit when the cart path does not exist', async () => {
+		const {stdout, exitCode} = await runVerify(
+			() => stubAdapter(present(false)),
+			join(dir, 'nope.p8'),
+		);
+		expect(exitCode).not.toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.code).toBe('cart-not-found');
+	});
+});