picopilot 0.0.0 → 0.1.1

package/src/commands/sfx.test.ts

@@ -0,0 +1,349 @@
+import {execFileSync} from 'node:child_process';
+import {mkdtempSync, readFileSync, writeFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+
+import {mmlToSfxRow, SFX_ROW_LENGTH} from '../engine/audio/index.js';
+import {createCli} from '../cli.js';
+
+/** A minimal valid cart with a lua + gfx section (to prove they stay untouched). */
+function cartText(sfxBody?: string): string {
+	let text =
+		'pico-8 cartridge // http://www.pico-8.com\nversion 42\n__lua__\nprint("hi")\n__gfx__\n0011223344556677\n';
+	if (sfxBody !== undefined) text += `__sfx__\n${sfxBody}`;
+	return text;
+}
+
+let dir: string;
+let cartPath: string;
+
+beforeEach(() => {
+	dir = mkdtempSync(join(tmpdir(), 'picopilot-sfx-'));
+	cartPath = join(dir, 'main.p8');
+});
+
+afterEach(() => {
+	try {
+		execFileSync('rm', ['-rf', dir]);
+	} catch {
+		// ignore
+	}
+});
+
+/** Drives a `picopilot sfx ...` invocation through incur's serve DI. */
+async function runSfx(argv: string[]) {
+	let stdout = '';
+	let exitCode = 0;
+	await createCli().serve(argv, {
+		stdout(s) {
+			stdout += s;
+		},
+		exit(code) {
+			exitCode = code;
+		},
+		env: {},
+	});
+	return {stdout, exitCode};
+}
+
+/** Extracts the __sfx__ body lines from a cart file. */
+function sfxLines(text: string): string[] {
+	const m = text.match(/__sfx__\n([\s\S]*?)(?:\n__|$)/);
+	return (m?.[1] ?? '').split('\n').filter((l) => l.length > 0);
+}
+
+describe('picopilot sfx from-mml: transpile + merge', () => {
+	it('merges a transpiled __sfx__ row into the target slot and reports it', async () => {
+		writeFileSync(cartPath, cartText());
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'from-mml',
+			'0',
+			's8 @1 v6 c d e',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.slot).toBe(0);
+		expect(out.rows).toBe(3);
+		expect(out.speed).toBe(8);
+		expect(out.row).toBe(mmlToSfxRow('s8 @1 v6 c d e').row);
+		expect(out.row).toHaveLength(SFX_ROW_LENGTH);
+		// Persisted: slot 0 holds the row.
+		const lines = sfxLines(readFileSync(cartPath, 'utf8'));
+		expect(lines[0]).toBe(out.row);
+	});
+
+	it('writes into a non-zero slot, padding intermediate slots', async () => {
+		writeFileSync(cartPath, cartText());
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'from-mml',
+			'3',
+			'@2 c',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).toBe(0);
+		expect(JSON.parse(stdout).slot).toBe(3);
+		const lines = sfxLines(readFileSync(cartPath, 'utf8'));
+		expect(lines).toHaveLength(4);
+		expect(lines[3]).toBe(mmlToSfxRow('@2 c').row);
+	});
+
+	it('CTAs toward verify + audio render', async () => {
+		writeFileSync(cartPath, cartText());
+		const {stdout} = await runSfx([
+			'sfx',
+			'from-mml',
+			'0',
+			'c',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		const cta = JSON.stringify(JSON.parse(stdout).cta);
+		expect(cta).toContain('verify');
+		expect(cta).toContain('audio render');
+	});
+});
+
+describe('picopilot sfx from-mml: leaves every OTHER section byte-identical', () => {
+	it('only __sfx__ changes; lua + gfx + header preserved', async () => {
+		writeFileSync(cartPath, cartText());
+		const before = readFileSync(cartPath, 'utf8');
+		await runSfx([
+			'sfx',
+			'from-mml',
+			'0',
+			'@1 c d e',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		const after = readFileSync(cartPath, 'utf8');
+		// The whole prefix up to __sfx__ is byte-identical.
+		const cut = before.length; // before has no __sfx__ yet
+		expect(after.slice(0, cut)).toBe(before);
+		expect(after).toContain('print("hi")');
+		expect(after).toContain('__gfx__\n0011223344556677\n');
+	});
+
+	it('overwrites only the target slot, preserving other authored slots', async () => {
+		// Pre-author slots 0 and 2.
+		const row0 = mmlToSfxRow('@2 c').row;
+		const row2 = mmlToSfxRow('@5 g').row;
+		const empty = '0'.repeat(SFX_ROW_LENGTH);
+		writeFileSync(cartPath, cartText(`${row0}\n${empty}\n${row2}\n`));
+
+		await runSfx([
+			'sfx',
+			'from-mml',
+			'1',
+			'@7 e',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		const lines = sfxLines(readFileSync(cartPath, 'utf8'));
+		expect(lines[0]).toBe(row0); // untouched
+		expect(lines[1]).toBe(mmlToSfxRow('@7 e').row); // new
+		expect(lines[2]).toBe(row2); // untouched
+	});
+});
+
+describe('picopilot sfx from-mml: SFX filters (finding A.7)', () => {
+	it('merges the filter bits into the header, reporting the filter byte', async () => {
+		writeFileSync(cartPath, cartText());
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'from-mml',
+			'3',
+			'!dampen2 !reverb @6 v7 o3 e c o1 g c', // a designed explosion
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		// !dampen2 (0xc0) | !reverb (0x20) = 0xe0 = 224.
+		expect(out.filters).toBe(0xe0);
+		expect(out.row.slice(0, 2)).toBe('e0'); // first header byte
+		expect(out.row).toBe(
+			mmlToSfxRow('!dampen2 !reverb @6 v7 o3 e c o1 g c').row,
+		);
+		expect(out.row).toHaveLength(SFX_ROW_LENGTH);
+	});
+
+	it('leaves the note rows + other sections byte-identical (filters are header-only)', async () => {
+		writeFileSync(cartPath, cartText());
+		const before = readFileSync(cartPath, 'utf8');
+		await runSfx([
+			'sfx',
+			'from-mml',
+			'0',
+			'!dampen @6 v7 c d e',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		const after = readFileSync(cartPath, 'utf8');
+		// Prefix (lua + gfx, before __sfx__) untouched.
+		expect(after.slice(0, before.length)).toBe(before);
+		expect(after).toContain('__gfx__\n0011223344556677\n');
+		// The written row's NOTE body matches the same MML without the filter.
+		const lines = sfxLines(after);
+		expect(lines[0]!.slice(8)).toBe(mmlToSfxRow('@6 v7 c d e').row.slice(8));
+		expect(lines[0]!.slice(0, 2)).toBe('80'); // dampen header byte
+	});
+
+	it('an out-of-range filter level -> audio-mml-filter-level-out-of-range, no write', async () => {
+		writeFileSync(cartPath, cartText());
+		const before = readFileSync(cartPath, 'utf8');
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'from-mml',
+			'0',
+			'!dampen3 c', // dampen has only 2 levels
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).not.toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.code).toBe('audio-mml-filter-level-out-of-range');
+		expect(out.message).toContain('DAMPEN');
+		// The cart is byte-untouched (refusal never writes).
+		expect(readFileSync(cartPath, 'utf8')).toBe(before);
+	});
+});
+
+describe('picopilot sfx from-mml: structured refusals (NO silent clamp)', () => {
+	it('out-of-range pitch -> audio-mml-pitch-out-of-range + nonzero exit, no write', async () => {
+		writeFileSync(cartPath, cartText());
+		const before = readFileSync(cartPath, 'utf8');
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'from-mml',
+			'0',
+			'o5 g', // pitch 67 > 63
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).not.toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.code).toBe('audio-mml-pitch-out-of-range');
+		expect(out.message).toContain('C0..D#5');
+		// The cart is byte-untouched (refusal never writes).
+		expect(readFileSync(cartPath, 'utf8')).toBe(before);
+	});
+
+	it('>32 rows -> audio-mml-sfx-overflow + nonzero exit, no write', async () => {
+		writeFileSync(cartPath, cartText());
+		const before = readFileSync(cartPath, 'utf8');
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'from-mml',
+			'0',
+			'c33',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).not.toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.code).toBe('audio-mml-sfx-overflow');
+		expect(out.message).toContain('32');
+		expect(readFileSync(cartPath, 'utf8')).toBe(before);
+	});
+
+	it('a tempo-style token -> audio-mml-parse-error naming tracker rows', async () => {
+		writeFileSync(cartPath, cartText());
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'from-mml',
+			'0',
+			't120 c',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).not.toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.code).toBe('audio-mml-parse-error');
+		expect(out.message).toContain('TRACKER ROWS');
+	});
+});
+
+describe('picopilot sfx from-mml: input surface (arg vs --file)', () => {
+	it('reads the MML from --file', async () => {
+		writeFileSync(cartPath, cartText());
+		const mmlPath = join(dir, 'lead.mml');
+		writeFileSync(mmlPath, 's4 @3 v7 c e g');
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'from-mml',
+			'0',
+			'--cart',
+			cartPath,
+			'--file',
+			mmlPath,
+			'--json',
+		]);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.row).toBe(mmlToSfxRow('s4 @3 v7 c e g').row);
+	});
+
+	it('errors when neither the mml arg nor --file is given', async () => {
+		writeFileSync(cartPath, cartText());
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'from-mml',
+			'0',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).not.toBe(0);
+		expect(JSON.parse(stdout).code).toBe('no-mml');
+	});
+
+	it('a missing cart is a distinct cart-not-found error', async () => {
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'from-mml',
+			'0',
+			'c',
+			'--cart',
+			join(dir, 'nope.p8'),
+			'--json',
+		]);
+		expect(exitCode).not.toBe(0);
+		expect(JSON.parse(stdout).code).toBe('cart-not-found');
+	});
+});
+
+describe('picopilot sfx from-mml: dotted-length rounding is reported', () => {
+	it('warns when a dotted length rounds to a whole row', async () => {
+		writeFileSync(cartPath, cartText());
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'from-mml',
+			'0',
+			'c3.', // 4.5 rows -> rounds
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.warnings.length).toBeGreaterThan(0);
+		expect(out.warnings[0]).toContain('rounded');
+	});
+});

package/src/commands/sfx.ts

@@ -0,0 +1,300 @@
+import {existsSync, readFileSync, writeFileSync} from 'node:fs';
+import {isAbsolute, resolve} from 'node:path';
+import {Cli, z} from 'incur';
+
+import {
+	AudioMmlError,
+	mergeSfxRow,
+	mmlToSfxRow,
+	PITCH_MAX,
+	SFX_MAX_ROWS,
+	SFX_SLOT_COUNT,
+} from '../engine/audio/index.js';
+import {Cart, CartParseError} from '../engine/cart/index.js';
+
+/** Resolves a path argument to an absolute path (relative to cwd). */
+function resolvePath(p: string): string {
+	return isAbsolute(p) ? p : resolve(process.cwd(), p);
+}
+
+/**
+ * Loads + parses a cart, returning either the parsed cart or a structured reason
+ * the caller turns into an `error(...)`. Mirrors the gfx command's loader.
+ */
+function loadCart(
+	cartPath: string,
+): {ok: true; cart: Cart} | {ok: false; code: string; message: string} {
+	if (!existsSync(cartPath)) {
+		return {
+			ok: false,
+			code: 'cart-not-found',
+			message: `no cart at ${cartPath}`,
+		};
+	}
+	const text = readFileSync(cartPath, 'utf8');
+	try {
+		return {ok: true, cart: Cart.parse(text)};
+	} catch (e) {
+		if (e instanceof CartParseError) {
+			return {
+				ok: false,
+				code: 'cart-parse-failed',
+				message: `cart at ${cartPath} does not parse (${e.code}): ${e.message}`,
+			};
+		}
+		throw e;
+	}
+}
+
+/**
+ * Builds the `sfx` command group. Currently just `sfx from-mml` (the
+ * picopilot-MML to `__sfx__` transpiler + cart merge).
+ */
+function buildSfxGroup(): Cli.Cli {
+	const sfx = Cli.create('sfx', {
+		description:
+			'Compose SFX as text: transpile picopilot-MML into a cart __sfx__ slot. Durations are TRACKER ROWS at one SFX speed, NOT tempo/BPM (PICO-8 has no per-note duration).',
+	});
+
+	sfx.command('from-mml', {
+		description:
+			'Transpile picopilot-MML text into one __sfx__ slot (0-63) and merge it into the cart (only that slot changes). picopilot-MML is TRACKER-ROW based: a length is a ROW COUNT (l4 = 4 rows), NOT a musical note value, and there is NO tempo/BPM (PICO-8 measures in ticks/row via `s<N>` speed). Notes carry per-note waveform (@0-7, @8-f = custom SFX-instrument), volume (v0-7), and effect (e0-7) that a score notation cannot express. SFX-level FILTER directives reach DESIGNED sounds (explosion/engine/pad): !dampen[2] (low-pass body), !reverb (echo tail), !noiz (@6 white noise), !buzz, !detune1/!detune2. Out-of-range pitch (below C0 / above D#5), >32 rows, and a bad filter level are refused loudly, never silently clamped.',
+		args: z.object({
+			slot: z.coerce
+				.number()
+				.int()
+				.min(0)
+				.max(SFX_SLOT_COUNT - 1)
+				.describe(`The target SFX slot 0-${SFX_SLOT_COUNT - 1} to write.`),
+			mml: z
+				.string()
+				.optional()
+				.describe(
+					'The picopilot-MML source (e.g. "s16 @1 v6 c d e f"). Omit and pass --file to read from a file instead. Modal state: @ waveform, v volume, e effect, o octave, l default length (all sticky). Durations are ROWS: c4 = 4 rows (held via tie rows). Loop with {..}; a lone { marks the pattern LEN. SFX filters (per-SFX, place anywhere): !dampen/!dampen2, !reverb, !noiz, !buzz, !detune1/!detune2 (e.g. "!dampen !reverb @6 v7 o3 e c o1 g" = an explosion).',
+				),
+		}),
+		options: z.object({
+			cart: z
+				.string()
+				.default('main.p8')
+				.describe(
+					'The .p8 cart to merge into. Defaults to main.p8 in the current folder. (An option, not a positional, so it never collides with an omitted `mml` when using --file.)',
+				),
+			file: z
+				.string()
+				.optional()
+				.describe(
+					'Read the picopilot-MML from this file instead of the `mml` argument (for longer sources).',
+				),
+		}),
+		output: z.object({
+			slot: z.number().describe('The SFX slot that was written.'),
+			cart: z
+				.string()
+				.describe('The absolute path of the cart that was written.'),
+			rows: z
+				.number()
+				.describe('The number of tracker rows the MML produced (0-32).'),
+			speed: z
+				.number()
+				.describe('The SFX speed (ticks/row) written into the header.'),
+			loopStart: z
+				.number()
+				.describe('The header loop-start value (row index, or a LEN).'),
+			loopEnd: z
+				.number()
+				.describe(
+					'The header loop-end value (0 = off or the LEN special case).',
+				),
+			filters: z
+				.number()
+				.describe(
+					'The per-SFX FILTER byte (first header byte): the OR of the selected filters, 0 = none.',
+				),
+			row: z
+				.string()
+				.describe('The 168-char __sfx__ text row that was merged.'),
+			warnings: z
+				.array(z.string())
+				.describe(
+					'Advisory warnings (e.g. a dotted length whose row count was rounded).',
+				),
+		}),
+		examples: [
+			{
+				description: 'A simple square-wave arpeggio into slot 0',
+				args: {slot: 0, mml: 's8 @3 v6 c e g > c'},
+			},
+			{
+				description: 'A held note (4 rows) with vibrato into slot 5 of a cart',
+				args: {slot: 5, mml: 's16 @1 v5 e2 c4'},
+				options: {cart: 'game.p8'},
+			},
+			{
+				description:
+					'A DESIGNED explosion: DAMPEN body + REVERB tail on @6 noise',
+				args: {slot: 3, mml: 's7 !dampen2 !reverb @6 v7 o3 e c o1 g c'},
+			},
+			{
+				description: 'Read a longer source from a file',
+				args: {slot: 1},
+				options: {file: 'lead.mml'},
+			},
+		],
+		run({args, options, error, ok}) {
+			// Resolve the MML source: the `mml` arg OR `--file` (exactly one). This is
+			// the input surface; both are pure text, shrinko-free + PICO-8-free.
+			let mml: string;
+			if (options.file !== undefined) {
+				if (args.mml !== undefined) {
+					return error({
+						code: 'ambiguous-input',
+						message:
+							'pass EITHER the mml argument OR --file, not both (they are two ways to give the same source).',
+						exitCode: 1,
+					});
+				}
+				const filePath = resolvePath(options.file);
+				if (!existsSync(filePath)) {
+					return error({
+						code: 'mml-file-not-found',
+						message: `no picopilot-MML file at ${filePath}`,
+						exitCode: 1,
+					});
+				}
+				mml = readFileSync(filePath, 'utf8');
+			} else if (args.mml !== undefined) {
+				mml = args.mml;
+			} else {
+				return error({
+					code: 'no-mml',
+					message:
+						'no picopilot-MML source: pass it as the `mml` argument or via --file.',
+					exitCode: 1,
+				});
+			}
+
+			// Transpile FIRST: a bad MML is a caller error and must never touch the
+			// cart (no bytes change on a refusal), mirroring `gfx set`'s grid-first
+			// discipline.
+			let result: ReturnType<typeof mmlToSfxRow>;
+			try {
+				result = mmlToSfxRow(mml);
+			} catch (e) {
+				if (e instanceof AudioMmlError) {
+					// The structured refusals + parse errors surface as incur's error
+					// envelope with a nonzero exit (never a silent clamp). The CTA points
+					// at the range/cap/level the author must respect.
+					const cta =
+						e.code === 'audio-mml-pitch-out-of-range'
+							? {
+									description:
+										'PICO-8 pitch is a hard range; author within it:',
+									commands: [
+										{
+											command: 'sfx from-mml <slot> "<mml>"',
+											description: `Use octaves that keep every note within C0..D#5 (0..${PITCH_MAX}).`,
+										},
+									],
+								}
+							: e.code === 'audio-mml-sfx-overflow'
+								? {
+										description: `One SFX holds at most ${SFX_MAX_ROWS} rows; split longer melodies:`,
+										commands: [
+											{
+												command: 'sfx from-mml <other-slot> "<rest>"',
+												description:
+													'Author the remainder as another SFX, then arrange both with `music from-patterns`.',
+											},
+										],
+									}
+								: e.code === 'audio-mml-filter-level-out-of-range'
+									? {
+											description: 'The SFX filters + their valid levels:',
+											commands: [
+												{
+													command:
+														'sfx from-mml <slot> "!dampen[2] !reverb !noiz !buzz !detune1/!detune2 ..."',
+													description:
+														'!dampen has 2 levels (!dampen/!dampen2); !reverb/!noiz/!buzz are on/off; !detune needs 1 or 2.',
+												},
+											],
+										}
+									: undefined;
+					return error({
+						code: e.code,
+						message: e.message,
+						exitCode: 1,
+						...(cta ? {cta} : {}),
+					});
+				}
+				throw e;
+			}
+
+			const cartPath = resolvePath(options.cart);
+			const loaded = loadCart(cartPath);
+			if (!loaded.ok) {
+				return error({code: loaded.code, message: loaded.message, exitCode: 1});
+			}
+
+			// Merge into the target slot ONLY, through the cart model, so every other
+			// section (and every other SFX slot) stays byte-identical.
+			mergeSfxRow(loaded.cart, args.slot, result.row);
+			writeFileSync(cartPath, loaded.cart.serialize());
+
+			const warnings = result.roundingWarnings.map(
+				(w) =>
+					`length "${w.token}" = ${w.exactRows} rows rounded to ${w.roundedRows} (rows are whole; PICO-8 has no fractional-length notes).`,
+			);
+
+			// CTA toward the verify/hear loop: a merged SFX is next confirmed by
+			// verify (static integrity) and heard via `audio render`.
+			return ok(
+				{
+					slot: args.slot,
+					cart: cartPath,
+					rows: result.rows,
+					speed: result.speed,
+					loopStart: result.loopStart,
+					loopEnd: result.loopEnd,
+					filters: result.filters,
+					row: result.row,
+					warnings,
+				},
+				{
+					cta: {
+						description: 'The SFX is merged. Confirm it, then hear it:',
+						commands: [
+							{
+								command: 'verify',
+								description:
+									'Static gate: the cart still parses + is within budget.',
+							},
+							{
+								command: 'audio render',
+								description:
+									'Record a WAV to hear the result (real-time capture, requires PICO-8).',
+							},
+						],
+					},
+				},
+			);
+		},
+	});
+
+	return sfx;
+}
+
+/**
+ * Registers the `sfx` command group (`sfx from-mml`) on the root CLI.
+ *
+ * `sfx` is a shrinko-FREE and PICO-8-FREE command group: it transpiles
+ * picopilot-MML to `__sfx__` and merges it through the cart model entirely in
+ * TS, so it works with both absent and never spawns a child process. The
+ * picopilot-MML dialect (ADR-0005 + the audio spike finding) is TRACKER-ROW
+ * based: durations are row counts at one SFX speed, NOT tempo (ADR-0008), and
+ * out-of-range pitch / >32 rows are structured refusals, never silent clamps.
+ */
+export function registerSfx(cli: Cli.Cli): void {
+	cli.command(buildSfxGroup());
+}