picopilot 0.0.0 → 0.1.1

package/src/engine/shrinko/adapter.ts

@@ -0,0 +1,241 @@
+/**
+ * The shrinko adapter SEAM: a typed interface every shrinko-backed command
+ * (`tokens`, and later `lint`, `minify`, `gfx import/export`, `verify`) talks
+ * to, plus the discriminated result shape they all return.
+ *
+ * The seam exists so the command layer never knows HOW shrinko is reached. The
+ * v1 implementation shells out to a user-installed Python `shrinko8` (see
+ * `shell.ts` and ADR-0001); a future native-TS implementation can implement the
+ * SAME {@link ShrinkoAdapter} interface and drop in without touching a single
+ * command. The command-facing contract is entirely in this file.
+ *
+ * The two-tier capability contract (ADR-0002) lives in the RESULT type: every
+ * adapter method returns a {@link ShrinkoResult}, a discriminated union of a
+ * success value OR the structured {@link ShrinkoNotFound} failure. Absent
+ * shrinko is therefore NOT an exception a command must try/catch, it is a
+ * first-class `{ok:false, reason:'shrinko-not-found', ...}` value a command maps
+ * onto incur's error envelope with a nonzero exit. Never a crash, never a hollow
+ * success.
+ */
+
+/** The PyPI package name in the remedy: `uv pip install shrinko` (NOT `shrinko8`). */
+export const SHRINKO_REMEDY = 'uv pip install shrinko' as const;
+
+/** What shrinko needs to run: Python 3.8+ (the module is `shrinko8`). */
+export const SHRINKO_NEEDS = ['python>=3.8'] as const;
+
+/**
+ * The structured "shrinko is not installed" failure (ADR-0002). Its shape is
+ * fixed by the prd's two-tier contract (US #17): `ok:false`, a machine-readable
+ * `reason`, the EXACT `remedy` string, and the `needs` list. A command turns
+ * this into an incur `error({ code: reason, ... })` with a nonzero exit.
+ */
+export interface ShrinkoNotFound {
+	readonly ok: false;
+	readonly reason: 'shrinko-not-found';
+	/** The EXACT remedy: `uv pip install shrinko` (package is `shrinko`, module `shrinko8`). */
+	readonly remedy: typeof SHRINKO_REMEDY;
+	/** Prerequisites the remedy assumes are present. */
+	readonly needs: readonly string[];
+}
+
+/** A successful adapter call carrying the parsed value. */
+export interface ShrinkoOk<T> {
+	readonly ok: true;
+	readonly value: T;
+}
+
+/**
+ * The result every {@link ShrinkoAdapter} method returns: either a parsed value
+ * or the structured {@link ShrinkoNotFound}. Absence is a value, not a throw, so
+ * the two-tier contract is total and type-checked at every call site.
+ */
+export type ShrinkoResult<T> = ShrinkoOk<T> | ShrinkoNotFound;
+
+/**
+ * The parsed `--count` report (US #3). `tokens`/`chars`/`compressed` are the
+ * raw counts shrinko prints; `pct` fields are shrinko's own reported
+ * percentages (its `--count` prints `tokens: 8053 98%`, i.e. against PICO-8's
+ * limits), preserved verbatim so a command can show them without recomputing.
+ * `compressed`/`compressedPct` are optional because shrinko omits the
+ * compressed line for input formats where it does not apply.
+ */
+export interface CountReport {
+	readonly tokens: number;
+	readonly tokensPct: number;
+	readonly chars: number;
+	readonly charsPct: number;
+	readonly compressed: number | undefined;
+	readonly compressedPct: number | undefined;
+}
+
+/**
+ * The shrinko capability seam. One method per shrinko-backed operation; only
+ * `count` exists in this task, the rest (lint, minify, convert) land with their
+ * commands and extend THIS interface rather than forking a new one.
+ *
+ * Every method is async (the shell-out is async) and returns a
+ * {@link ShrinkoResult}, so absence is handled uniformly at each seam.
+ */
+export interface ShrinkoAdapter {
+	/**
+	 * Runs shrinko's `--count` on the cart at `cartPath` and parses the
+	 * `tokens/chars/compressed` report. Returns {@link ShrinkoNotFound} when
+	 * shrinko is not installed.
+	 */
+	count(cartPath: string): Promise<ShrinkoResult<CountReport>>;
+
+	/**
+	 * Runs shrinko's `--lint` on the cart at `cartPath` and parses the warnings
+	 * (undefined globals, unused/duplicate locals, etc.) into structured
+	 * {@link LintFinding}s. Lint warnings are DATA, not a failure: the report is
+	 * returned with `findings` (possibly empty), not a throw. Returns
+	 * {@link ShrinkoNotFound} when shrinko is not installed.
+	 */
+	lint(cartPath: string): Promise<ShrinkoResult<LintReport>>;
+
+	/**
+	 * Runs shrinko's SAFE minification on `cartPath` and writes the result to
+	 * `outPath` (a SEPARATE artifact; the source is never touched, see ADR-0007).
+	 * Returns the before/after token counts. Returns {@link ShrinkoNotFound} when
+	 * shrinko is not installed.
+	 */
+	minify(
+		cartPath: string,
+		outPath: string,
+	): Promise<ShrinkoResult<MinifyReport>>;
+
+	/**
+	 * Exports the cart's spritesheet as a 128x128 PNG to `pngPath` (a raw
+	 * round-trip image for external tools, distinct from `gfx render`'s upscaled
+	 * JUDGE image). Returns {@link ShrinkoNotFound} when shrinko is not installed.
+	 */
+	exportSpritesheet(
+		cartPath: string,
+		pngPath: string,
+	): Promise<ShrinkoResult<void>>;
+
+	/**
+	 * Imports a 128x128 spritesheet PNG into `srcCartPath`'s `__gfx__`, MERGING
+	 * (only the gfx section is replaced; code/map/sfx/music are preserved) and
+	 * writing the result to `outCartPath`. Returns {@link ShrinkoNotFound} when
+	 * shrinko is not installed.
+	 */
+	importSpritesheet(
+		srcCartPath: string,
+		pngPath: string,
+		outCartPath: string,
+	): Promise<ShrinkoResult<void>>;
+}
+
+/** One shrinko lint warning, parsed from a `file:line:col: message` line. */
+export interface LintFinding {
+	readonly line: number;
+	readonly col: number;
+	readonly message: string;
+}
+
+/** The parsed `--lint` result: every warning shrinko reported (empty when clean). */
+export interface LintReport {
+	readonly findings: readonly LintFinding[];
+}
+
+/** The parsed `minify` result: token counts before and after (ADR-0007's delta report). */
+export interface MinifyReport {
+	/** Tokens in the source cart. */
+	readonly beforeTokens: number;
+	/** Tokens in the minified artifact. */
+	readonly afterTokens: number;
+	/** Absolute path of the written minified cart. */
+	readonly outPath: string;
+}
+
+/** The frozen {@link ShrinkoNotFound} value, so every call site returns the same shape. */
+export function shrinkoNotFound(): ShrinkoNotFound {
+	return {
+		ok: false,
+		reason: 'shrinko-not-found',
+		remedy: SHRINKO_REMEDY,
+		needs: [...SHRINKO_NEEDS],
+	};
+}
+
+/**
+ * Parses shrinko's `--count` output into a {@link CountReport}.
+ *
+ * shrinko prints lines like:
+ *
+ * ```
+ * tokens: 8053 98%
+ * chars: 30320 46%
+ * compressed: 12176 77%
+ * ```
+ *
+ * (the compressed line is absent for some input formats). Parsing is
+ * line-oriented and tolerant of surrounding output/whitespace: it scans for the
+ * `tokens:`/`chars:`/`compressed:` labels anywhere in the combined stdout+stderr
+ * and pulls the count and percentage off each. Throws if the required
+ * `tokens:`/`chars:` lines are missing, so a shrinko that ran but produced
+ * unparseable output surfaces as a real error rather than a silent zero.
+ */
+export function parseCount(output: string): CountReport {
+	const line = (label: string): {n: number; pct: number} | undefined => {
+		// `label: <count> <pct>%` (count and percent may be separated by any run
+		// of spaces; the `%` is optional-tolerant but shrinko always prints it).
+		const re = new RegExp(`^\\s*${label}:\\s*(\\d+)\\s+(\\d+)\\s*%`, 'm');
+		const m = re.exec(output);
+		if (m === null) return undefined;
+		return {n: Number(m[1]), pct: Number(m[2])};
+	};
+
+	const tokens = line('tokens');
+	const chars = line('chars');
+	if (tokens === undefined || chars === undefined) {
+		throw new ShrinkoParseError(
+			`could not parse shrinko --count output (missing tokens/chars lines):\n${output}`,
+		);
+	}
+	const compressed = line('compressed');
+
+	return {
+		tokens: tokens.n,
+		tokensPct: tokens.pct,
+		chars: chars.n,
+		charsPct: chars.pct,
+		compressed: compressed?.n,
+		compressedPct: compressed?.pct,
+	};
+}
+
+/**
+ * Parses shrinko's `--lint` output into {@link LintFinding}s. shrinko prints a
+ * `Lint warnings:` header then one `file:line:col: message` per warning; a clean
+ * cart prints nothing. Parsing scans the combined stdout+stderr for the
+ * `:line:col: message` shape (tolerant of the filename prefix, which we drop),
+ * so an empty result is a CLEAN cart, not an error. Unlike parseCount this never
+ * throws: no recognisable lines simply means zero findings.
+ */
+export function parseLint(output: string): LintReport {
+	const findings: LintFinding[] = [];
+	// Match `<anything>:<line>:<col>: <message>` (the filename may itself contain
+	// colons/paths, so anchor on the two trailing numeric groups before the msg).
+	const re = /:(\d+):(\d+):\s*(.+?)\s*$/gm;
+	for (const m of output.matchAll(re)) {
+		findings.push({
+			line: Number(m[1]),
+			col: Number(m[2]),
+			message: m[3] ?? '',
+		});
+	}
+	return {findings};
+}
+
+/**
+ * Thrown when shrinko RAN but its output could not be parsed (a shrinko
+ * version/format drift), distinct from shrinko being ABSENT (which is the
+ * structured {@link ShrinkoNotFound} value, not a throw). Commands surface this
+ * as a `shrinko-failed` error, separate from `shrinko-not-found`.
+ */
+export class ShrinkoParseError extends Error {
+	override readonly name = 'ShrinkoParseError';
+}

package/src/engine/shrinko/fixtures/count-no-compressed.txt

@@ -0,0 +1,2 @@
+tokens: 300 3%
+chars: 1200 1%

package/src/engine/shrinko/fixtures/count-over-budget.txt

@@ -0,0 +1,3 @@
+tokens: 8053 98%
+chars: 30320 46%
+compressed: 12176 77%

package/src/engine/shrinko/fixtures/count-under-budget.txt

@@ -0,0 +1,3 @@
+tokens: 512 6%
+chars: 1840 2%
+compressed: 980 6%

package/src/engine/shrinko/index.ts

@@ -0,0 +1,33 @@
+/**
+ * The shrinko adapter seam: how every shrinko-backed command reaches shrinko8.
+ *
+ * `adapter.ts` is the command-facing CONTRACT (the {@link ShrinkoAdapter}
+ * interface, the {@link ShrinkoResult} discriminated union, the structured
+ * {@link ShrinkoNotFound} value, and the `--count` parser). `shell.ts` is the v1
+ * IMPLEMENTATION that shells out to a user-installed Python `shrinko8`
+ * (ADR-0001). A future native-TS implementation implements the same interface
+ * and drops in without touching the command layer.
+ */
+export {
+	type CountReport,
+	type LintFinding,
+	type LintReport,
+	type MinifyReport,
+	parseCount,
+	parseLint,
+	SHRINKO_NEEDS,
+	SHRINKO_REMEDY,
+	type ShrinkoAdapter,
+	type ShrinkoNotFound,
+	shrinkoNotFound,
+	type ShrinkoOk,
+	ShrinkoParseError,
+	type ShrinkoResult,
+} from './adapter.js';
+export {
+	type ChildResult,
+	type ChildRunner,
+	execFileRunner,
+	ShellShrinkoAdapter,
+	type ShellShrinkoOptions,
+} from './shell.js';

package/src/engine/shrinko/shell.ts

@@ -0,0 +1,224 @@
+import {execFile} from 'node:child_process';
+
+import {
+	type CountReport,
+	type LintReport,
+	type MinifyReport,
+	parseCount,
+	parseLint,
+	type ShrinkoAdapter,
+	type ShrinkoResult,
+	shrinkoNotFound,
+} from './adapter.js';
+
+/**
+ * The result of running one child process: its exit `code` (null when killed by
+ * a signal), captured `stdout`/`stderr`, and `spawnError` set when the binary
+ * could not be launched AT ALL (ENOENT etc.) rather than launched-and-exited.
+ * `spawnError` is how the shell adapter distinguishes "shrinko is not installed"
+ * from "shrinko ran and failed".
+ */
+export interface ChildResult {
+	readonly code: number | null;
+	readonly stdout: string;
+	readonly stderr: string;
+	readonly spawnError: NodeJS.ErrnoException | undefined;
+}
+
+/**
+ * The child-process seam. The real implementation shells out with the CALLER's
+ * `env` (so a test overrides the child's `PATH` and nothing else). Tests inject
+ * a stub runner to simulate shrinko present/absent WITHOUT ever requiring the
+ * real binary, and to assert exactly what argv/env the adapter would spawn.
+ */
+export type ChildRunner = (
+	file: string,
+	args: string[],
+	env: NodeJS.ProcessEnv,
+) => Promise<ChildResult>;
+
+/**
+ * The default {@link ChildRunner}: an `execFile` that captures stdout/stderr and
+ * NEVER rejects. A failed spawn (ENOENT) becomes `spawnError`; a nonzero exit
+ * becomes a `code`, so both outcomes are data the adapter maps to a structured
+ * result. The child inherits ONLY the `env` it is handed (the command layer
+ * passes the incur-resolved env, whose `PATH` a test can override) so there is
+ * no ambient-environment leak.
+ */
+export const execFileRunner: ChildRunner = (file, args, env) =>
+	new Promise((resolve) => {
+		execFile(file, args, {env, encoding: 'utf8'}, (error, stdout, stderr) => {
+			const err = error as NodeJS.ErrnoException | null;
+			resolve({
+				// `execFile` sets error.code to the string 'ENOENT' on spawn failure and
+				// to the numeric exit code on a nonzero exit; separate the two.
+				code:
+					err !== null && typeof err.code === 'number'
+						? err.code
+						: err === null
+							? 0
+							: null,
+				stdout,
+				stderr,
+				spawnError:
+					err !== null && typeof err.code === 'string' ? err : undefined,
+			});
+		});
+	});
+
+/**
+ * The candidate ways to invoke shrinko, tried in order. First the `shrinko8`
+ * entry-point on `PATH`, then `python -m shrinko8` / `python3 -m shrinko8` as
+ * fallbacks (the module is `shrinko8`; the pip package is `shrinko`). The first
+ * candidate that SPAWNS (does not ENOENT) is the one shrinko is reached through.
+ */
+const SHRINKO_INVOCATIONS: readonly (readonly string[])[] = [
+	['shrinko8'],
+	['python', '-m', 'shrinko8'],
+	['python3', '-m', 'shrinko8'],
+];
+
+/** Options for {@link ShellShrinkoAdapter}. */
+export interface ShellShrinkoOptions {
+	/**
+	 * The environment handed to the child process. The command layer passes the
+	 * incur-resolved env here; its `PATH` is the isolation lever a test overrides
+	 * (an empty/`PATH`-less env makes every invocation ENOENT ⇒ shrinko-absent).
+	 */
+	readonly env: NodeJS.ProcessEnv;
+	/** The child runner (defaults to {@link execFileRunner}); tests inject a stub. */
+	readonly run?: ChildRunner;
+}
+
+/**
+ * The v1 {@link ShrinkoAdapter}: shells out to a user-installed Python
+ * `shrinko8` (ADR-0001). It is the ONLY place that knows shrinko is an external
+ * process; every command talks to the {@link ShrinkoAdapter} interface, so a
+ * future native-TS adapter replaces this class without touching a command.
+ *
+ * Presence detection and invocation are the SAME act: the adapter tries each
+ * {@link SHRINKO_INVOCATIONS} candidate and uses the first that spawns. If every
+ * candidate ENOENTs, shrinko is absent and the method returns the structured
+ * {@link shrinkoNotFound} value (never a throw, never a hollow success).
+ */
+export class ShellShrinkoAdapter implements ShrinkoAdapter {
+	private readonly env: NodeJS.ProcessEnv;
+	private readonly run: ChildRunner;
+
+	constructor(options: ShellShrinkoOptions) {
+		this.env = options.env;
+		this.run = options.run ?? execFileRunner;
+	}
+
+	async count(cartPath: string): Promise<ShrinkoResult<CountReport>> {
+		const outcome = await this.invoke([cartPath, '--count']);
+		if (outcome === undefined) {
+			return shrinkoNotFound();
+		}
+		// shrinko prints the count report; some builds send it to stderr, so parse
+		// the combined stream. parseCount throws on unparseable output (ShrinkoParseError).
+		return {
+			ok: true,
+			value: parseCount(`${outcome.stdout}\n${outcome.stderr}`),
+		};
+	}
+
+	async lint(cartPath: string): Promise<ShrinkoResult<LintReport>> {
+		// `-l` lints; it exits nonzero (2) WHEN it finds warnings, which is a normal
+		// result (findings are data), NOT a spawn failure. Only a spawnError means
+		// shrinko is absent, so we key absence off `outcome === undefined`, and parse
+		// the warnings regardless of the (0-or-2) exit code.
+		const outcome = await this.invoke([cartPath, '-l']);
+		if (outcome === undefined) {
+			return shrinkoNotFound();
+		}
+		return {
+			ok: true,
+			value: parseLint(`${outcome.stdout}\n${outcome.stderr}`),
+		};
+	}
+
+	async minify(
+		cartPath: string,
+		outPath: string,
+	): Promise<ShrinkoResult<MinifyReport>> {
+		// Count the source first (the "before"): if shrinko is absent, this returns
+		// the not-found value and we never write anything.
+		const before = await this.count(cartPath);
+		if (!before.ok) return before;
+
+		// Minify SAFE-only (ADR-0007): the three safe-only knobs keep rename/reorder/
+		// builtins behaviour-preserving. Output goes to a SEPARATE cart (outPath).
+		const out = await this.invoke([
+			cartPath,
+			'-m',
+			'--rename-safe-only',
+			'--reorder-safe-only',
+			'--builtins-safe-only',
+			outPath,
+		]);
+		if (out === undefined) return shrinkoNotFound();
+
+		// Count the artifact (the "after"). It exists now, so this is a normal count.
+		const after = await this.count(outPath);
+		if (!after.ok) return after;
+
+		return {
+			ok: true,
+			value: {
+				beforeTokens: before.value.tokens,
+				afterTokens: after.value.tokens,
+				outPath,
+			},
+		};
+	}
+
+	async exportSpritesheet(
+		cartPath: string,
+		pngPath: string,
+	): Promise<ShrinkoResult<void>> {
+		// `<cart> <out.png> -f spritesheet` writes the 128x128 spritesheet PNG.
+		const outcome = await this.invoke([cartPath, pngPath, '-f', 'spritesheet']);
+		if (outcome === undefined) return shrinkoNotFound();
+		return {ok: true, value: undefined};
+	}
+
+	async importSpritesheet(
+		srcCartPath: string,
+		pngPath: string,
+		outCartPath: string,
+	): Promise<ShrinkoResult<void>> {
+		// `<cart> <out.p8> --merge <png> gfx spritesheet` merges ONLY the gfx section
+		// from the PNG into the source cart, preserving code/map/sfx/music. (A plain
+		// `-F spritesheet` would drop everything but gfx, wiping the user's code.)
+		const outcome = await this.invoke([
+			srcCartPath,
+			outCartPath,
+			'--merge',
+			pngPath,
+			'gfx',
+			'spritesheet',
+		]);
+		if (outcome === undefined) return shrinkoNotFound();
+		return {ok: true, value: undefined};
+	}
+
+	/**
+	 * Runs shrinko with the given trailing args, trying each invocation candidate
+	 * until one SPAWNS. Returns the {@link ChildResult} of the first candidate
+	 * that launched, or `undefined` when every candidate ENOENTs (shrinko absent).
+	 */
+	private async invoke(args: string[]): Promise<ChildResult | undefined> {
+		for (const inv of SHRINKO_INVOCATIONS) {
+			const [file, ...prefix] = inv as [string, ...string[]];
+			const result = await this.run(file, [...prefix, ...args], this.env);
+			if (result.spawnError === undefined) {
+				return result;
+			}
+			// ENOENT on this candidate: fall through to the next. Any other spawn
+			// error (EACCES etc.) also falls through, so a broken candidate never
+			// masks a working one.
+		}
+		return undefined;
+	}
+}

package/src/engine/shrinko/shrinko.test.ts

@@ -0,0 +1,182 @@
+import {readFileSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {describe, expect, it} from 'vitest';
+
+import {
+	type ChildResult,
+	type ChildRunner,
+	parseCount,
+	SHRINKO_REMEDY,
+	ShellShrinkoAdapter,
+	ShrinkoParseError,
+} from './index.js';
+
+/** Reads a captured `--count` sample as raw text. */
+function sample(name: string): string {
+	return readFileSync(
+		fileURLToPath(new URL(`./fixtures/${name}`, import.meta.url)),
+		'utf8',
+	);
+}
+
+/** A recorded spawn, so tests can assert the exact argv + env the adapter used. */
+interface Spawn {
+	file: string;
+	args: string[];
+	env: NodeJS.ProcessEnv;
+}
+
+/**
+ * Builds a stub {@link ChildRunner} that returns a fixed {@link ChildResult} for
+ * a chosen `file`, and ENOENT for every other candidate. Records each spawn so a
+ * test can assert which invocation was used and with what env. This is how every
+ * test drives shrinko present/absent WITHOUT the real binary.
+ */
+function stubRunner(opts: {
+	presentFile?: string;
+	stdout?: string;
+	stderr?: string;
+	code?: number;
+}): {run: ChildRunner; spawns: Spawn[]} {
+	const spawns: Spawn[] = [];
+	const run: ChildRunner = async (file, args, env) => {
+		spawns.push({file, args, env});
+		if (opts.presentFile !== undefined && file === opts.presentFile) {
+			return {
+				code: opts.code ?? 0,
+				stdout: opts.stdout ?? '',
+				stderr: opts.stderr ?? '',
+				spawnError: undefined,
+			} satisfies ChildResult;
+		}
+		// Not the present binary → simulate ENOENT (not installed on PATH).
+		const err = Object.assign(new Error(`spawn ${file} ENOENT`), {
+			code: 'ENOENT',
+		}) as NodeJS.ErrnoException;
+		return {code: null, stdout: '', stderr: '', spawnError: err};
+	};
+	return {run, spawns};
+}
+
+describe('parseCount: parses shrinko --count output', () => {
+	it('parses the documented over-budget sample', () => {
+		const report = parseCount(sample('count-over-budget.txt'));
+		expect(report).toEqual({
+			tokens: 8053,
+			tokensPct: 98,
+			chars: 30320,
+			charsPct: 46,
+			compressed: 12176,
+			compressedPct: 77,
+		});
+	});
+
+	it('parses a sample with no compressed line (compressed undefined)', () => {
+		const report = parseCount(sample('count-no-compressed.txt'));
+		expect(report.tokens).toBe(300);
+		expect(report.chars).toBe(1200);
+		expect(report.compressed).toBeUndefined();
+		expect(report.compressedPct).toBeUndefined();
+	});
+
+	it('parses the count even when embedded in surrounding output/whitespace', () => {
+		const noisy = `some banner line\n\n  tokens: 8053 98%\n  chars: 30320 46%\n  compressed: 12176 77%\ntrailing\n`;
+		const report = parseCount(noisy);
+		expect(report.tokens).toBe(8053);
+		expect(report.chars).toBe(30320);
+		expect(report.compressed).toBe(12176);
+	});
+
+	it('throws ShrinkoParseError when the required lines are absent', () => {
+		expect(() => parseCount('unexpected shrinko output\n')).toThrow(
+			ShrinkoParseError,
+		);
+	});
+});
+
+describe('ShellShrinkoAdapter.count: present', () => {
+	it('parses --count from the shrinko8 entry-point on PATH', async () => {
+		const {run, spawns} = stubRunner({
+			presentFile: 'shrinko8',
+			stdout: sample('count-over-budget.txt'),
+		});
+		const adapter = new ShellShrinkoAdapter({env: {PATH: '/fake/bin'}, run});
+		const result = await adapter.count('/carts/main.p8');
+
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.tokens).toBe(8053);
+			expect(result.value.chars).toBe(30320);
+			expect(result.value.compressed).toBe(12176);
+		}
+		// It spawned `shrinko8 /carts/main.p8 --count` first and stopped there.
+		expect(spawns[0]?.file).toBe('shrinko8');
+		expect(spawns[0]?.args).toEqual(['/carts/main.p8', '--count']);
+	});
+
+	it('parses --count even when shrinko prints to stderr', async () => {
+		const {run} = stubRunner({
+			presentFile: 'shrinko8',
+			stdout: '',
+			stderr: sample('count-under-budget.txt'),
+		});
+		const adapter = new ShellShrinkoAdapter({env: {PATH: '/fake/bin'}, run});
+		const result = await adapter.count('/carts/main.p8');
+		expect(result.ok).toBe(true);
+		if (result.ok) expect(result.value.tokens).toBe(512);
+	});
+
+	it('falls back to `python -m shrinko8` when shrinko8 is not on PATH', async () => {
+		const {run, spawns} = stubRunner({
+			presentFile: 'python',
+			stdout: sample('count-over-budget.txt'),
+		});
+		const adapter = new ShellShrinkoAdapter({env: {PATH: '/fake/bin'}, run});
+		const result = await adapter.count('/carts/main.p8');
+
+		expect(result.ok).toBe(true);
+		// First tried shrinko8 (ENOENT), then python -m shrinko8 (spawned).
+		expect(spawns.map((s) => s.file)).toEqual(['shrinko8', 'python']);
+		expect(spawns[1]?.args).toEqual([
+			'-m',
+			'shrinko8',
+			'/carts/main.p8',
+			'--count',
+		]);
+	});
+});
+
+describe('ShellShrinkoAdapter.count: absent (structured, never a crash)', () => {
+	it('returns shrinko-not-found with the EXACT remedy when nothing spawns', async () => {
+		// Every candidate ENOENTs (an empty PATH is the isolation lever).
+		const {run, spawns} = stubRunner({presentFile: undefined});
+		const adapter = new ShellShrinkoAdapter({env: {}, run});
+		const result = await adapter.count('/carts/main.p8');
+
+		expect(result.ok).toBe(false);
+		if (!result.ok) {
+			expect(result.reason).toBe('shrinko-not-found');
+			expect(result.remedy).toBe(SHRINKO_REMEDY);
+			expect(result.remedy).toBe('uv pip install shrinko');
+			expect(result.needs).toEqual(['python>=3.8']);
+		}
+		// It tried every invocation candidate before giving up.
+		expect(spawns.map((s) => s.file)).toEqual([
+			'shrinko8',
+			'python',
+			'python3',
+		]);
+	});
+
+	it('passes ONLY the given env to the child (the PATH isolation lever)', async () => {
+		const {run, spawns} = stubRunner({
+			presentFile: 'shrinko8',
+			stdout: sample('count-over-budget.txt'),
+		});
+		const env = {PATH: '/only/this/bin', SOME_OTHER: 'x'};
+		const adapter = new ShellShrinkoAdapter({env, run});
+		await adapter.count('/carts/main.p8');
+		// The child sees exactly the env we handed the adapter, nothing ambient.
+		expect(spawns[0]?.env).toEqual(env);
+	});
+});