picopilot 0.0.0 → 0.1.0

package/src/commands/verify.ts

@@ -0,0 +1,256 @@
+import {existsSync, readFileSync} from 'node:fs';
+import {isAbsolute, resolve} from 'node:path';
+import {type Cli, z} from 'incur';
+
+import {Cart, CartParseError} from '../engine/cart/index.js';
+import {
+	type ShrinkoAdapter,
+	ShrinkoParseError,
+	ShellShrinkoAdapter,
+} from '../engine/shrinko/index.js';
+import {TOKEN_BUDGET} from './tokens.js';
+
+/**
+ * The one-line self-scoping the `picopilot verify` envelope always carries, so
+ * the connotation of "verify" never misleads an agent into treating a green
+ * static gate as terminal (ADR-0003). It states BOTH facts: verify is static,
+ * and passing does NOT mean the cart runs.
+ */
+export const VERIFY_SCOPE =
+	'static gate: tokens + integrity; passing does NOT mean the cart runs' as const;
+
+/**
+ * The exit code for the DISTINCT `gate-incapable` outcome (shrinko absent).
+ * Chosen as 2 to be categorically separate from `fail` (exit 1, a cart that
+ * flunked a check) and from `pass` (exit 0): an absent capability is neither a
+ * green gate nor a failed check but a gate that could not run its most
+ * important check, so it gets its own nonzero code an agent can branch on.
+ */
+export const GATE_INCAPABLE_EXIT = 2;
+
+/** See {@link ShrinkoAdapterFactory} in `tokens.ts` — verify reuses the same seam. */
+export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+
+const defaultAdapterFactory: ShrinkoAdapterFactory = (env) =>
+	new ShellShrinkoAdapter({env});
+
+/**
+ * The result of the integrity check: the cart parses AND round-trips
+ * byte-identically through the cart model (well-formed sections). A cart that
+ * fails to parse, or one whose serialize does not reproduce the source, is not
+ * well-formed and fails integrity.
+ */
+type IntegrityResult = {ok: true} | {ok: false; detail: string};
+
+/**
+ * Runs the STATIC cart-integrity check against `text`: the cart must parse into
+ * the cart model and round-trip cleanly (`Cart.parse(text).serialize() ===
+ * text`). This is a purely static, well-formedness check — it never runs the
+ * cart. A {@link CartParseError} (malformed header/version/section) or a
+ * round-trip mismatch is a fail with a human-readable detail.
+ */
+function checkIntegrity(text: string): IntegrityResult {
+	let cart: Cart;
+	try {
+		cart = Cart.parse(text);
+	} catch (e) {
+		if (e instanceof CartParseError) {
+			return {
+				ok: false,
+				detail: `cart does not parse (${e.code}): ${e.message}`,
+			};
+		}
+		throw e;
+	}
+	if (cart.serialize() !== text) {
+		return {
+			ok: false,
+			detail:
+				'cart does not round-trip cleanly through the cart model (malformed sections)',
+		};
+	}
+	return {ok: true};
+}
+
+/**
+ * Registers `picopilot verify` (US #15, #18), the STATIC cart-acceptance gate an
+ * agent drives each iteration toward.
+ *
+ * It runs two static checks and returns ONE structured envelope:
+ *
+ * - **integrity** — the cart parses and round-trips cleanly through the cart
+ *   model (well-formed sections). No run.
+ * - **tokens** — the cart is within the 8,192-token budget (via the shrinko
+ *   adapter `--count`).
+ *
+ * (Lint folds in when the lint task lands; in v1-core verify = tokens +
+ * integrity.)
+ *
+ * Three categorical outcomes (ADR-0003):
+ *
+ * - **pass** (exit 0) — both checks green. The envelope SELF-SCOPES (states it
+ *   is static and that passing does not mean the cart runs) and CTAs to
+ *   `picopilot run` ("static checks pass, now confirm it boots"), so the agent
+ *   is led from well-formed to actually-runs.
+ * - **fail** (exit 1) — a check flunked (over budget, or a malformed/non-parsing
+ *   cart). A structured `verify-failed` error listing which checks failed.
+ * - **gate-incapable** (exit {@link GATE_INCAPABLE_EXIT}) — shrinko is ABSENT,
+ *   so the token check (the #1 failure mode, token bloat) cannot run. verify
+ *   returns a DISTINCT `gate-incapable` result, NEVER green, categorically
+ *   separate from pass and fail. This is the gate-as-theatre regression guard:
+ *   verify must never report green by skipping its most important check.
+ *
+ * verify is STATIC and never runs the cart, so it has NO PICO-8 dependency (US
+ * #19). It reaches shrinko entirely through the {@link ShrinkoAdapter} seam, so
+ * a native-TS shrinko would satisfy it unchanged.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to drive present / absent / over-budget without the real
+ *   binary.
+ */
+export function registerVerify(
+	cli: Cli.Cli,
+	adapterFactory: ShrinkoAdapterFactory = defaultAdapterFactory,
+): void {
+	cli.command('verify', {
+		description:
+			'Static acceptance gate: run tokens + cart-integrity and return one pass/fail envelope. Does NOT run the cart. Requires shrinko.',
+		args: z.object({
+			cart: z
+				.string()
+				.default('main.p8')
+				.describe(
+					'The .p8 cart to verify. Defaults to main.p8 in the current folder.',
+				),
+		}),
+		// Declared so incur resolves it from the (test-overridable) env source and
+		// hands it to the shrinko child; verify itself never runs the cart, so it
+		// needs no PICO-8 env.
+		env: z.object({
+			PATH: z
+				.string()
+				.optional()
+				.describe('Used to locate shrinko8 in the child process.'),
+		}),
+		output: z.object({
+			status: z
+				.literal('pass')
+				.describe('The overall gate result. Only a green gate reaches ok.'),
+			scope: z
+				.string()
+				.describe(
+					'The self-scoping note: verify is static and passing does NOT mean the cart runs.',
+				),
+			checks: z
+				.object({
+					integrity: z
+						.boolean()
+						.describe('True when the cart parses and round-trips cleanly.'),
+					tokens: z
+						.boolean()
+						.describe('True when the cart is within the 8,192-token budget.'),
+				})
+				.describe('Per-check pass/fail, so the agent sees WHAT was checked.'),
+			tokens: z.number().describe('The token count shrinko reported.'),
+			budget: z.number().describe('The token budget checked against (8192).'),
+		}),
+		examples: [
+			{description: 'Verify main.p8'},
+			{description: 'Verify 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 a fail: there is
+			// nothing to gate. Surface it clearly rather than reporting a hollow fail.
+			if (!existsSync(cartPath)) {
+				return error({
+					code: 'cart-not-found',
+					message: `no cart at ${cartPath}`,
+					exitCode: 1,
+				});
+			}
+
+			const text = readFileSync(cartPath, 'utf8');
+
+			// Integrity is a static, shrinko-free check: the cart parses + round-trips.
+			const integrity = checkIntegrity(text);
+
+			// Tokens goes through the shrinko seam. Absent shrinko is the gate-incapable
+			// trigger (below); a parse failure of shrinko's own output is shrinko-failed.
+			const adapter = adapterFactory(env as NodeJS.ProcessEnv);
+			let count: Awaited<ReturnType<ShrinkoAdapter['count']>>;
+			try {
+				count = await adapter.count(cartPath);
+			} catch (e) {
+				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;
+			}
+
+			// GATE-INCAPABLE (ADR-0003): shrinko absent → verify CANNOT check the #1
+			// failure mode (token bloat). It returns a DISTINCT outcome, NEVER green,
+			// never a silent skip. This is the load-bearing regression guard: verify
+			// must not report pass by omitting its most important check.
+			if (!count.ok) {
+				return error({
+					code: 'gate-incapable',
+					message: `${VERIFY_SCOPE}. gate-incapable: cannot check tokens without shrinko, so verify will not report green. ${count.remedy} (needs: ${count.needs.join(', ')})`,
+					exitCode: GATE_INCAPABLE_EXIT,
+				});
+			}
+
+			const tokens = count.value.tokens;
+			const tokensOk = tokens <= TOKEN_BUDGET;
+
+			// FAIL (exit 1): a static check flunked. List every failing check so the
+			// agent knows what to fix, not just that something did.
+			if (!integrity.ok || !tokensOk) {
+				const failed: string[] = [];
+				if (!integrity.ok) failed.push(`integrity: ${integrity.detail}`);
+				if (!tokensOk) {
+					failed.push(
+						`tokens: ${tokens} exceeds the ${TOKEN_BUDGET}-token budget`,
+					);
+				}
+				return error({
+					code: 'verify-failed',
+					message: `${VERIFY_SCOPE}. verify FAILED: ${failed.join('; ')}`,
+					exitCode: 1,
+				});
+			}
+
+			// PASS (exit 0): both static checks green. Self-scope, then CTA to `run` so
+			// the agent is led from well-formed to actually-boots (ADR-0003 CTA).
+			return ok(
+				{
+					status: 'pass' as const,
+					scope: VERIFY_SCOPE,
+					checks: {integrity: true, tokens: true},
+					tokens,
+					budget: TOKEN_BUDGET,
+				},
+				{
+					cta: {
+						description:
+							'Static checks pass. Now confirm the cart actually boots:',
+						commands: [
+							{
+								command: 'run',
+								description:
+									'Launch the cart headless to confirm it boots (verify does not run it).',
+							},
+						],
+					},
+				},
+			);
+		},
+	});
+}

package/src/commands/version.test.ts

@@ -0,0 +1,70 @@
+import {describe, expect, it} from 'vitest';
+import {createCli} from '../cli.js';
+import {VERSION} from '../version.js';
+
+/**
+ * Drives the CLI end-to-end through incur's `serve(argv, { stdout, exit })` DI,
+ * capturing output and the exit code without touching the real process.
+ */
+async function run(argv: string[]) {
+	let stdout = '';
+	let exitCode = 0;
+	await createCli().serve(argv, {
+		stdout(s) {
+			stdout += s;
+		},
+		exit(code) {
+			exitCode = code;
+		},
+	});
+	return {stdout, exitCode};
+}
+
+describe('picopilot version', () => {
+	it('runs end-to-end and reports the package version, exit 0', async () => {
+		const {stdout, exitCode} = await run(['version']);
+		expect(exitCode).toBe(0);
+		expect(stdout).toContain(VERSION);
+		expect(stdout).toContain('picopilot');
+	});
+
+	it('emits TOON by default (unquoted key: value, not JSON braces)', async () => {
+		const {stdout} = await run(['version']);
+		// TOON renders `name: picopilot`, never the JSON `"name": "picopilot"`.
+		expect(stdout).toContain(`version: ${VERSION}`);
+		expect(stdout).not.toContain('"version"');
+		expect(stdout.trimStart().startsWith('{')).toBe(false);
+	});
+
+	it('emits parseable JSON under --json', async () => {
+		const {stdout, exitCode} = await run(['version', '--json']);
+		expect(exitCode).toBe(0);
+		const parsed = JSON.parse(stdout);
+		expect(parsed).toEqual({name: 'picopilot', version: VERSION});
+	});
+});
+
+describe('picopilot CLI surface', () => {
+	it('--help lists the incur agent-discovery built-ins', async () => {
+		const {stdout} = await run(['--help']);
+		// incur renders `skills add` / `mcp add` as grouped integrations.
+		expect(stdout).toMatch(/skills\s+Sync skill files to agents/);
+		expect(stdout).toMatch(/mcp\s+Register as MCP server/);
+		expect(stdout).toContain('--format');
+		expect(stdout).toContain('--llms');
+		expect(stdout).toContain('--mcp');
+	});
+
+	it('exposes `skills add` and `mcp add` as real subcommands', async () => {
+		const skills = await run(['skills', '--help']);
+		expect(skills.stdout).toMatch(/\badd\b/);
+		const mcp = await run(['mcp', '--help']);
+		expect(mcp.stdout).toMatch(/\badd\b/);
+	});
+
+	it('--llms emits a machine-readable manifest that includes version', async () => {
+		const {stdout, exitCode} = await run(['--llms']);
+		expect(exitCode).toBe(0);
+		expect(stdout).toContain('version');
+	});
+});

package/src/commands/version.ts

@@ -0,0 +1,24 @@
+import {type Cli, z} from 'incur';
+import {VERSION} from '../version.js';
+
+/**
+ * Registers the trivial `version` command onto the given CLI (or command group).
+ *
+ * This is the skeleton's proof-of-life command: it exercises the full incur
+ * pipeline (output schema, the structured envelope, TOON-by-default and `--json`
+ * formatting) with no engine dependencies, so the `verify` gate has something
+ * real to build and test. Later command groups mount alongside it via their own
+ * `register*` helpers, called from `createCli`.
+ */
+export function registerVersion(cli: Cli.Cli): void {
+	cli.command('version', {
+		description: 'Print the picopilot version.',
+		output: z.object({
+			name: z.string().describe('The tool name.'),
+			version: z.string().describe('The installed picopilot version.'),
+		}),
+		run() {
+			return {name: 'picopilot', version: VERSION};
+		},
+	});
+}

package/src/engine/audio/index.ts

@@ -0,0 +1,47 @@
+/**
+ * `engine/audio` — the shrinko-free, PICO-8-free audio codec. Two halves:
+ * the picopilot-MML to `__sfx__` transpiler (finding Part A/B, ADR-0005 +
+ * ADR-0008) and the structural pattern-list to `__music__` codec (finding A.5 /
+ * B.6, ADR-0005).
+ *
+ * Mirrors the `engine/gfx` shape: a pure module + this index re-export, no
+ * adapter. The `sfx from-mml` command is thin wiring over {@link mmlToSfxRow};
+ * the `music from-patterns` command over {@link patternsToMusic}.
+ */
+export {mergeSfxRow, setMusicSection, SFX_SLOT_COUNT} from './section.js';
+export {
+	AudioMmlError,
+	type AudioMmlErrorCode,
+	DEFAULT_LENGTH,
+	DEFAULT_OCTAVE,
+	DEFAULT_SPEED,
+	FILTER_BUZZ,
+	FILTER_DAMPEN_LEVEL,
+	FILTER_DETUNE_1,
+	FILTER_DETUNE_2,
+	FILTER_MAX_LEVEL,
+	FILTER_NOIZ,
+	FILTER_REVERB,
+	mmlToSfxRow,
+	PITCH_MAX,
+	PITCH_MIN,
+	type RowRoundingWarning,
+	SFX_MAX_ROWS,
+	SFX_ROW_LENGTH,
+	type SfxTranspileResult,
+} from './sfx.js';
+export {
+	CHANNEL_OFF_BIT,
+	type ChannelRef,
+	FLAG_LOOP_BACK,
+	FLAG_LOOP_START,
+	FLAG_STOP,
+	MUSIC_PATTERN_MAX,
+	MusicError,
+	type MusicErrorCode,
+	type MusicTranspileResult,
+	type MusicWarning,
+	type Pattern,
+	patternsToMusic,
+	SFX_INDEX_MAX,
+} from './music.js';

package/src/engine/audio/music.test.ts

@@ -0,0 +1,188 @@
+import {describe, expect, it} from 'vitest';
+
+import {
+	MUSIC_PATTERN_MAX,
+	MusicError,
+	type Pattern,
+	patternsToMusic,
+} from './music.js';
+
+/**
+ * Table-driven codec tests: a known pattern list -> a known `__music__` row,
+ * asserted BYTE-FOR-BYTE against the finding's Part A.5 (`FF CCCCCCCC` = a 2-hex
+ * flag byte + space + 4 channel bytes; flag bits loop-start=0x01, loop-back=0x02,
+ * stop=0x04, combinable; channel byte = sfx 0..63, bit6=0x40 = off).
+ */
+describe('patternsToMusic: one pattern -> one FF CCCCCCCC row (finding A.5)', () => {
+	const cases: Array<{name: string; pattern: Pattern; row: string}> = [
+		{
+			name: 'a plain 4-channel pattern (no flags, no off) -> flag 00',
+			pattern: {channels: [0, 1, 2, 3]},
+			row: '00 00010203',
+		},
+		{
+			name: 'loop-start alone -> flag 01',
+			pattern: {channels: [0, 0, 0, 0], loopStart: true},
+			row: '01 00000000',
+		},
+		{
+			name: 'loop-back alone -> flag 02 (with a loop-start elsewhere, no warn)',
+			// A lone loopBack would warn; here we test the FLAG BYTE in isolation.
+			pattern: {channels: [1, 1, 1, 1], loopBack: true},
+			row: '02 01010101',
+		},
+		{
+			name: 'stop alone -> flag 04',
+			pattern: {channels: [5, 6, 7, 8], stop: true},
+			row: '04 05060708',
+		},
+		{
+			name: 'combined loop-start + stop -> flag 05 (0x01 | 0x04)',
+			pattern: {channels: [0, 0, 0, 0], loopStart: true, stop: true},
+			row: '05 00000000',
+		},
+		{
+			name: 'all three flags -> flag 07 (0x01 | 0x02 | 0x04)',
+			pattern: {
+				channels: [0, 0, 0, 0],
+				loopStart: true,
+				loopBack: true,
+				stop: true,
+			},
+			row: '07 00000000',
+		},
+		{
+			name: 'an off channel sets bit6 -> byte 40 (finding A.5: null = bare 0x40)',
+			pattern: {channels: [null, 1, 2, 3]},
+			row: '00 40010203',
+		},
+		{
+			name: 'the finding\u2019s verified 0x40|17 = 51 example (off + sfx 17)... but null carries no index, so a null ch0 is 40',
+			pattern: {channels: [null, null, null, null]},
+			row: '00 40404040',
+		},
+		{
+			name: 'max SFX index 63 -> byte 3f',
+			pattern: {channels: [63, 63, 63, 63]},
+			row: '00 3f3f3f3f',
+		},
+	];
+
+	for (const {name, pattern, row} of cases) {
+		it(name, () => {
+			const result = patternsToMusic([pattern]);
+			expect(result.section).toBe(`${row}\n`);
+			expect(result.patterns).toBe(1);
+		});
+	}
+});
+
+describe('patternsToMusic: "off" is NOT "sfx 0" (finding B.6 / B.7 #9)', () => {
+	it('sfx 0 -> byte 00 (a real, playing SFX)', () => {
+		expect(patternsToMusic([{channels: [0, 1, 2, 3]}]).section).toBe(
+			'00 00010203\n',
+		);
+	});
+
+	it('off -> byte 40 (bit6 set, silent), DISTINCT from sfx 0', () => {
+		expect(patternsToMusic([{channels: [null, 1, 2, 3]}]).section).toBe(
+			'00 40010203\n',
+		);
+	});
+
+	it('the two are different bytes for the same channel position', () => {
+		const sfx0 = patternsToMusic([{channels: [0, 0, 0, 0]}]).section;
+		const off = patternsToMusic([{channels: [null, null, null, null]}]).section;
+		expect(sfx0).toBe('00 00000000\n');
+		expect(off).toBe('00 40404040\n');
+		expect(sfx0).not.toBe(off);
+	});
+});
+
+describe('patternsToMusic: multiple patterns are song order (finding A.5/B.6)', () => {
+	it('emits one row per pattern, top to bottom = song order', () => {
+		const result = patternsToMusic([
+			{channels: [0, 1, 2, 3], loopStart: true},
+			{channels: [4, 5, null, 6]},
+			{channels: [0, 0, 0, 0], loopBack: true, stop: true},
+		]);
+		expect(result.section).toBe(
+			['01 00010203', '00 04054006', '06 00000000'].join('\n') + '\n',
+		);
+		expect(result.patterns).toBe(3);
+	});
+});
+
+describe('patternsToMusic: loop-back without loop-start WARNS, not errors (finding B.6)', () => {
+	it('a lone loopBack (no loopStart anywhere) warns about the pattern-0 fall-back', () => {
+		const result = patternsToMusic([
+			{channels: [0, 0, 0, 0]},
+			{channels: [1, 1, 1, 1], loopBack: true},
+		]);
+		expect(result.warnings).toHaveLength(1);
+		expect(result.warnings[0]!.code).toBe('loop-back-without-loop-start');
+		expect(result.warnings[0]!.message).toContain('pattern 0');
+		// It still emits (does NOT hard-fail).
+		expect(result.patterns).toBe(2);
+	});
+
+	it('a loopBack WITH a loopStart somewhere does NOT warn', () => {
+		const result = patternsToMusic([
+			{channels: [0, 0, 0, 0], loopStart: true},
+			{channels: [1, 1, 1, 1], loopBack: true},
+		]);
+		expect(result.warnings).toHaveLength(0);
+	});
+});
+
+describe('patternsToMusic: out-of-range + malformed refusals (NO silent clamp)', () => {
+	it('an SFX index > 63 -> audio-music-sfx-out-of-range', () => {
+		try {
+			patternsToMusic([{channels: [64, 0, 0, 0]}]);
+			expect.fail('expected a MusicError');
+		} catch (e) {
+			expect(e).toBeInstanceOf(MusicError);
+			expect((e as MusicError).code).toBe('audio-music-sfx-out-of-range');
+		}
+	});
+
+	it('a negative SFX index -> audio-music-sfx-out-of-range', () => {
+		expect(() => patternsToMusic([{channels: [-1, 0, 0, 0]}])).toThrow(
+			MusicError,
+		);
+	});
+
+	it('the wrong channel count -> audio-music-bad-channel-count', () => {
+		try {
+			// Deliberately malformed (3 channels) via a cast, mirroring how a
+			// hand-authored JSON payload could arrive.
+			patternsToMusic([
+				{channels: [0, 1, 2] as unknown as Pattern['channels']},
+			]);
+			expect.fail('expected a MusicError');
+		} catch (e) {
+			expect((e as MusicError).code).toBe('audio-music-bad-channel-count');
+		}
+	});
+
+	it('an empty list -> audio-music-empty', () => {
+		try {
+			patternsToMusic([]);
+			expect.fail('expected a MusicError');
+		} catch (e) {
+			expect((e as MusicError).code).toBe('audio-music-empty');
+		}
+	});
+
+	it('more than 64 patterns -> audio-music-too-many-patterns', () => {
+		const many: Pattern[] = Array.from({length: MUSIC_PATTERN_MAX + 1}, () => ({
+			channels: [0, 0, 0, 0] as Pattern['channels'],
+		}));
+		try {
+			patternsToMusic(many);
+			expect.fail('expected a MusicError');
+		} catch (e) {
+			expect((e as MusicError).code).toBe('audio-music-too-many-patterns');
+		}
+	});
+});