picopilot 0.0.0 → 0.1.0

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);
+	});
+});

package/src/engine/skills/index.ts

@@ -0,0 +1,14 @@
+/**
+ * The skills-install engine behind `picopilot init --install-skills`, the one
+ * picopilot path that writes to a shared/global location. Every install-target
+ * knob is a parameter here so tests redirect it to a temp dir and the real agent
+ * skill dirs stay byte-untouched. See `skills.ts` for the isolation contract.
+ */
+export {
+	installSkills,
+	type InstallSkillsOptions,
+	type InstallSkillsResult,
+	SKILL_NAMES,
+	skillsSourceDir,
+	type WiredAgent,
+} from './skills.js';