picopilot 0.2.0 → 0.3.0

package/src/commands/gfx.ts

@@ -25,6 +25,7 @@ import {
 	createShellShrinkoFactory,
 	type ShrinkoAdapterFactory,
 } from './shrinko-env.js';
+import {mcpConfigOption} from './pico8-env.js';
 
 /** Injects the shrinko adapter `gfx import`/`gfx export` use (the spritesheet round-trip). */
 export type {ShrinkoAdapterFactory} from './shrinko-env.js';
@@ -199,11 +200,13 @@ function buildGfxGroup(shrinkoFactory: ShrinkoAdapterFactory): Cli.Cli {
 				),
 		}),
 		options: z.object({
+			// No zod default: an absent value must stay distinguishable, so that under
+			// `--mcp` (where incur loads no config) picopilot.json still applies.
 			allowMapOverlap: z
 				.boolean()
-				.default(false)
+				.optional()
 				.describe(
-					'Authorise overwriting existing shared-region data when writing sprites 128-255 (ADR-0004). Also settable as allowMapOverlap in picopilot.json.',
+					'Authorise overwriting existing shared-region data when writing sprites 128-255 (ADR-0004). Also settable as allowMapOverlap in picopilot.json. Default false.',
 				),
 		}),
 		output: z.object({
@@ -237,7 +240,7 @@ function buildGfxGroup(shrinkoFactory: ShrinkoAdapterFactory): Cli.Cli {
 				},
 			},
 		],
-		run({args, options, error, ok}) {
+		run({args, options, error, ok, var: vars}) {
 			const cartPath = resolveCart(args.cart);
 
 			// Decode the incoming grid FIRST: a malformed grid is a caller error and
@@ -267,12 +270,12 @@ function buildGfxGroup(shrinkoFactory: ShrinkoAdapterFactory): Cli.Cli {
 			// (the shared-bank bytes at risk), NOT __map__ (ADR-0004). The flag and
 			// the picopilot.json config both feed `options.allowMapOverlap` (incur
 			// resolves argv > config > default), so both authorisation paths converge
-			// here.
-			const decision = decideOverlap(
-				sheet,
-				args.sprite,
-				options.allowMapOverlap,
-			);
+			// here. Under `--mcp` incur loads no config, so the picopilot.json value
+			// comes from the `mcpConfig` var instead.
+			const allowMapOverlap =
+				options.allowMapOverlap ??
+				mcpConfigOption(vars, ['gfx', 'set'], 'allowMapOverlap') === true;
+			const decision = decideOverlap(sheet, args.sprite, allowMapOverlap);
 
 			if (decision.kind === 'refused') {
 				// The silent-corruption guard: REFUSE and DO NOT write. The cart file is

package/src/commands/music.test.ts

@@ -270,3 +270,122 @@ describe('picopilot music from-patterns: input surface (arg vs --file)', () => {
 		expect(JSON.parse(stdout).code).toBe('cart-not-found');
 	});
 });
+
+/** The __sfx__ body lines of 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 music from-score (ADR-0020)', () => {
+	const gameSfx = mmlToSfxRow('s4 @3 v6 c e g').row;
+
+	it('writes two songs, reports start patterns, and leaves other content alone', async () => {
+		writeFileSync(cartPath, cartText({sfx: `${gameSfx}\n`}));
+		const score = {
+			songs: [
+				{name: 'title', speed: 16, channels: ['l32 c d', 'o1 l64 c', null]},
+				{name: 'game', speed: 20, channels: [null, 'o1 l16 g d g d']},
+			],
+		};
+		const scoreFile = join(dir, 'score.json');
+		writeFileSync(scoreFile, JSON.stringify(score));
+		const before = readFileSync(cartPath, 'utf8');
+		const {stdout, exitCode} = await runMusic([
+			'music',
+			'from-score',
+			'--file',
+			scoreFile,
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(
+			out.songs.map((s: {name: string; startPattern: number}) => [
+				s.name,
+				s.startPattern,
+			]),
+		).toEqual([
+			['title', 0],
+			['game', 2],
+		]);
+		expect(out.patterns).toBe(4);
+		const after = readFileSync(cartPath, 'utf8');
+		// Slot 0 (the game SFX), __lua__ and __gfx__ are byte-identical.
+		expect(sfxLines(after)[0]).toBe(gameSfx);
+		expect(after.split('__sfx__')[0]).toBe(before.split('__sfx__')[0]);
+		// Free slots are used from 63 down; slot 0 is never touched.
+		expect(out.slots.every((s: {slot: number}) => s.slot > 0)).toBe(true);
+		expect(out.slots.every((s: {overwrote: boolean}) => !s.overwrote)).toBe(
+			true,
+		);
+		// The game song's first channel is off in every pattern.
+		const music = musicLines(after);
+		expect(music).toHaveLength(4);
+		for (const line of music.slice(2)) expect(line.slice(3, 5)).toBe('40');
+	});
+
+	it('--slots owns a range: re-running is idempotent (byte-identical cart)', async () => {
+		writeFileSync(cartPath, cartText({sfx: `${gameSfx}\n`}));
+		const score = JSON.stringify({channels: ['l32 c d', 'o1 l64 c']});
+		const argv = [
+			'music',
+			'from-score',
+			score,
+			'--cart',
+			cartPath,
+			'--slots',
+			'40-50',
+			'--json',
+		];
+		const first = await runMusic(argv);
+		expect(first.exitCode).toBe(0);
+		const once = readFileSync(cartPath, 'utf8');
+		await runMusic(argv);
+		expect(readFileSync(cartPath, 'utf8')).toBe(once);
+		const slots = JSON.parse(first.stdout).slots.map(
+			(s: {slot: number}) => s.slot,
+		);
+		expect(slots.every((s: number) => s >= 40 && s <= 50)).toBe(true);
+	});
+
+	it('a bad score never touches the cart', async () => {
+		writeFileSync(cartPath, cartText({sfx: `${gameSfx}\n`}));
+		const before = readFileSync(cartPath, 'utf8');
+		for (const score of [
+			'{',
+			'{"channels":["o5 g"]}',
+			'{"channels":["{c}"]}',
+		]) {
+			const {stdout, exitCode} = await runMusic([
+				'music',
+				'from-score',
+				score,
+				'--cart',
+				cartPath,
+				'--json',
+			]);
+			expect(exitCode, score).not.toBe(0);
+			expect(stdout).toMatch(/audio-(score|mml)-/);
+		}
+		expect(readFileSync(cartPath, 'utf8')).toBe(before);
+	});
+
+	it('refuses a non-contiguous --slots', async () => {
+		writeFileSync(cartPath, cartText());
+		const {stdout, exitCode} = await runMusic([
+			'music',
+			'from-score',
+			'{"channels":["c"]}',
+			'--cart',
+			cartPath,
+			'--slots',
+			'3,9',
+			'--json',
+		]);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('audio-score-bad-slot-range');
+	});
+});

package/src/commands/music.ts

@@ -3,9 +3,19 @@ import {isAbsolute, resolve} from 'node:path';
 import {Cli, z} from 'incur';
 
 import {
+	AudioMmlError,
+	clearSfxSlot,
+	formatSlots,
+	mergeSfxRow,
 	MusicError,
+	musicSfxRefs,
+	parseSlotList,
 	patternsToMusic,
 	type Pattern,
+	planScore,
+	readScore,
+	readSfxRows,
+	ScoreError,
 	SFX_INDEX_MAX,
 	setMusicSection,
 } from '../engine/audio/index.js';
@@ -270,11 +280,251 @@ function buildMusicGroup(): Cli.Cli {
 		},
 	});
 
+	music.command('from-score', {
+		description:
+			"Write whole SONGS from a score: up to 4 channels per song, each a picopilot-MML string of ANY length (ADR-0020). picopilot cuts every channel into 32-row SFX aligned across channels, makes a channel that is silent for a whole pattern OFF (null), de-duplicates identical SFX, allocates slots, and writes __sfx__ + __music__ (only the slots it writes or clears and __music__ change). Several songs (e.g. title + in-game) are laid out back to back; the report gives each song's start pattern for `music(n)`. Slots: by default only FREE (note-less) slots, filled from 63 down, never touching other content; --slots <from-to> gives the score a range it OWNS (it overwrites and clears that range; recommended when iterating, so re-runs are idempotent).",
+		args: z.object({
+			score: z
+				.string()
+				.optional()
+				.describe(
+					'The score as JSON: {"songs":[{"name":"title","speed":16,"loop":true,"channels":["<mml ch0>", {"mml":"<mml ch1>","filters":"!dampen"}, null, null]}]}. Per song: speed (ticks/row, default the channels\' shared s<N> or 16), patternRows (1-32, default 32), loop (default true; false = stop at the end), loopFrom (pattern within the song the loop returns to, default 0). One song may be given directly as {"channels":[...]}. Omit and pass --file instead.',
+				),
+		}),
+		options: z.object({
+			cart: z
+				.string()
+				.default('main.p8')
+				.describe(
+					'The .p8 cart to write. Defaults to main.p8 in the current folder.',
+				),
+			file: z
+				.string()
+				.optional()
+				.describe(
+					'Read the JSON score from this file instead of the `score` argument.',
+				),
+			slots: z
+				.string()
+				.optional()
+				.describe(
+					'A slot range the score OWNS, e.g. "16-63": any slot in it may be overwritten, and the ones the score does not use are cleared. Without it, only free (note-less) slots are used.',
+				),
+		}),
+		output: z.object({
+			cart: z
+				.string()
+				.describe('The absolute path of the cart that was written.'),
+			songs: z
+				.array(
+					z.object({
+						name: z.string(),
+						startPattern: z
+							.number()
+							.describe('Play this song with music(startPattern).'),
+						endPattern: z.number(),
+						patterns: z.number(),
+						speed: z.number(),
+						patternRows: z.number(),
+						loop: z.boolean(),
+						loopStartPattern: z.number().optional(),
+						seconds: z.number().describe('Length of one pass, in seconds.'),
+					}),
+				)
+				.describe('Each song as laid out in __music__.'),
+			patterns: z.number().describe('Total patterns written to __music__.'),
+			slots: z
+				.array(
+					z.object({
+						slot: z.number(),
+						uses: z.array(z.string()),
+						overwrote: z
+							.boolean()
+							.describe('The slot held different, non-empty content before.'),
+					}),
+				)
+				.describe('Every SFX slot the score wrote, and where it plays.'),
+			slotRange: z
+				.string()
+				.describe('The slots used, compactly (e.g. "40-63").'),
+			cleared: z
+				.array(z.number())
+				.describe(
+					'Owned slots (--slots) the score does not use, cleared to empty.',
+				),
+			warnings: z.array(z.string()).describe('Advisory warnings.'),
+		}),
+		examples: [
+			{
+				description:
+					'Two songs (title + in-game) from a file, owning slots 16-63',
+				args: {},
+				options: {file: 'score.json', slots: '16-63'},
+			},
+			{
+				description: 'One short looping song inline',
+				args: {
+					score:
+						'{"speed":16,"channels":["!dampen @0 v[3 2 2 1/0] o2 l8 a d+ f e","!dampen @0 v[2 2 1] o1 l16 d a-"]}',
+				},
+			},
+		],
+		run({args, options, error, ok}) {
+			let text: string;
+			if (options.file !== undefined) {
+				if (args.score !== undefined) {
+					return error({
+						code: 'ambiguous-input',
+						message:
+							'pass EITHER the score 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: 'score-file-not-found',
+						message: `no score file at ${filePath}`,
+						exitCode: 1,
+					});
+				}
+				text = readFileSync(filePath, 'utf8');
+			} else if (args.score !== undefined) {
+				text = args.score;
+			} else {
+				return error({
+					code: 'no-score',
+					message:
+						'no score: pass it as the `score` argument (JSON) or via --file.',
+					exitCode: 1,
+				});
+			}
+
+			let range: {from: number; to: number} | undefined;
+			if (options.slots !== undefined) {
+				const list = parseSlotList(options.slots);
+				const ok =
+					list !== undefined &&
+					list.length > 0 &&
+					list[list.length - 1]! - list[0]! + 1 === list.length;
+				if (!ok) {
+					return error({
+						code: 'audio-score-bad-slot-range',
+						message: `--slots "${options.slots}" is not one contiguous range within 0-${SFX_INDEX_MAX}, e.g. "16-63".`,
+						exitCode: 1,
+					});
+				}
+				range = {from: list![0]!, to: list![list!.length - 1]!};
+			}
+
+			const cartPath = resolvePath(options.cart);
+			const loaded = loadCart(cartPath);
+			if (!loaded.ok) {
+				return error({code: loaded.code, message: loaded.message, exitCode: 1});
+			}
+
+			// Plan FIRST (pure): a bad score never touches the cart.
+			let plan: ReturnType<typeof planScore>;
+			try {
+				let raw: unknown;
+				try {
+					raw = JSON.parse(text);
+				} catch (e) {
+					throw new ScoreError(
+						'audio-score-parse-error',
+						`score is not valid JSON: ${e instanceof Error ? e.message : String(e)}`,
+					);
+				}
+				plan = planScore(
+					readScore(raw),
+					{
+						sfxRows: readSfxRows(loaded.cart),
+						musicRefs: musicSfxRefs(loaded.cart.getSection('music')),
+					},
+					range !== undefined ? {slots: range} : {},
+				);
+			} catch (e) {
+				if (e instanceof ScoreError || e instanceof AudioMmlError) {
+					return error({
+						code: e.code,
+						message: e.message,
+						exitCode: 1,
+						...(e.code === 'audio-score-no-free-slots'
+							? {
+									cta: {
+										description: 'Give the music a slot range it owns:',
+										commands: [
+											{
+												command:
+													'music from-score --file <score.json> --slots 16-63',
+												description:
+													'The score overwrites and clears that range (and nothing else).',
+											},
+										],
+									},
+								}
+							: {}),
+					});
+				}
+				throw e;
+			}
+
+			for (const s of plan.slots) mergeSfxRow(loaded.cart, s.slot, s.row);
+			for (const slot of plan.cleared) clearSfxSlot(loaded.cart, slot);
+			setMusicSection(loaded.cart, plan.musicSection);
+			writeFileSync(cartPath, loaded.cart.serialize());
+
+			const lua = plan.songs
+				.map((s) => `${s.name}: music(${s.startPattern})`)
+				.join(', ');
+			return ok(
+				{
+					cart: cartPath,
+					songs: plan.songs.map((s) => ({
+						name: s.name,
+						startPattern: s.startPattern,
+						endPattern: s.endPattern,
+						patterns: s.patterns,
+						speed: s.speed,
+						patternRows: s.patternRows,
+						loop: s.loop,
+						...(s.loopStartPattern !== undefined
+							? {loopStartPattern: s.loopStartPattern}
+							: {}),
+						seconds: s.seconds,
+					})),
+					patterns: plan.patterns,
+					slots: plan.slots.map((s) => ({
+						slot: s.slot,
+						uses: s.uses,
+						overwrote: s.overwrote,
+					})),
+					slotRange: formatSlots(plan.slots.map((s) => s.slot)),
+					cleared: plan.cleared,
+					warnings: plan.warnings,
+				},
+				{
+					cta: {
+						description: `Written. Play from Lua with ${lua} (add a channel mask, e.g. music(n,0,7), to leave channel 3 for SFX). Then hear and measure it:`,
+						commands: [
+							{
+								command: `audio render --pattern ${plan.songs[0]!.startPattern} --seconds ${Math.ceil(2 * plan.songs[0]!.seconds + 2)} --analyze`,
+								description:
+									'Record the first song twice over (the loop length needs two passes) and get loudness/brightness/repetition numbers.',
+							},
+						],
+					},
+				},
+			);
+		},
+	});
+
 	return music;
 }
 
 /**
- * Registers the `music` command group (`music from-patterns`) on the root CLI.
+ * Registers the `music` command group (`music from-patterns`, `music
+ * from-score`) on the root CLI.
  *
  * `music` is a shrinko-FREE and PICO-8-FREE command group: it assembles a
  * structural pattern list into `__music__` and merges it through the cart model

package/src/commands/pico8-env.ts

@@ -1,6 +1,7 @@
 import {z} from 'incur';
 import {
 	DEFAULT_DISPLAY_MODE,
+	DISPLAY_MODES,
 	type DisplayMode,
 	isDisplayMode,
 	type Pico8Adapter,
@@ -72,9 +73,23 @@ export function createShellAdapterFactory(
 }
 
 /**
- * The display mode a command handler sees. The root middleware in `createCli`
- * resolves it (flag > env > config > default) into the `display` var; a command
- * mounted on a bare CLI (some tests) has no var and gets the default.
+ * The `display` option of the commands that use the display mode (`run`,
+ * `audio record`, `audio render`, `doctor`). A per-command option, not an incur
+ * global, because incur's MCP transport passes no globals: as an option it is
+ * also an argument of the MCP tool. Unset = the invocation-level value.
+ */
+export const DISPLAY_OPTION = z
+	.enum(DISPLAY_MODES)
+	.optional()
+	.describe(
+		'How a PICO-8 -run session (audio recording) gets a display: auto (default: a private virtual display only when there is none), xvfb (always virtual), native (as-is). Else PICOPILOT_DISPLAY, else picopilot.json "display".',
+	);
+
+/**
+ * The display mode the root middleware in `createCli` resolved for this
+ * invocation (top-level `--display` > PICOPILOT_DISPLAY > picopilot.json >
+ * auto). A command mounted on a bare CLI (some tests) has no var and gets the
+ * default.
  */
 export function displayModeOf(vars: unknown): DisplayMode {
 	const value =
@@ -84,6 +99,59 @@ export function displayModeOf(vars: unknown): DisplayMode {
 	return isDisplayMode(value) ? value : DEFAULT_DISPLAY_MODE;
 }
 
+/**
+ * The display mode a command uses: its own `display` option (a per-call MCP
+ * argument) wins, else the invocation-level value. An invalid invocation-level
+ * value (a typo in PICOPILOT_DISPLAY, say) is an `invalid-display-mode` error
+ * here, so only the commands that use the mode fail on it.
+ */
+export function resolveCommandDisplay(
+	option: DisplayMode | undefined,
+	vars: unknown,
+):
+	| {ok: true; mode: DisplayMode}
+	| {
+			ok: false;
+			error: {code: 'invalid-display-mode'; message: string; exitCode: number};
+	  } {
+	if (option !== undefined) return {ok: true, mode: option};
+	const problem =
+		vars !== null && typeof vars === 'object'
+			? (vars as {displayError?: unknown}).displayError
+			: undefined;
+	if (typeof problem === 'string') {
+		return {
+			ok: false,
+			error: {code: 'invalid-display-mode', message: problem, exitCode: 1},
+		};
+	}
+	return {ok: true, mode: displayModeOf(vars)};
+}
+
+/**
+ * Under `--mcp`, incur loads no config file, so picopilot loads picopilot.json
+ * itself and hands the tree to commands as the `mcpConfig` var. A command whose
+ * option can come from the config reads its fallback here (CLI runs get it from
+ * incur as the option's default, so this is undefined there).
+ */
+export function mcpConfigOption(
+	vars: unknown,
+	commandPath: readonly string[],
+	key: string,
+): unknown {
+	let node: unknown =
+		vars !== null && typeof vars === 'object'
+			? (vars as {mcpConfig?: unknown}).mcpConfig
+			: undefined;
+	for (const part of commandPath) {
+		node = (node as {commands?: Record<string, unknown>} | undefined)
+			?.commands?.[part];
+	}
+	return (node as {options?: Record<string, unknown>} | undefined)?.options?.[
+		key
+	];
+}
+
 /**
  * The `error(...)` payload for a `display-unavailable` result (ADR-0017): the
  * session needs a display, there is none, and no Xvfb is installed to provide a

package/src/commands/run.ts

@@ -16,10 +16,11 @@ import {
 import {makeReadInclude} from './cart-includes.js';
 import {
 	createShellAdapterFactory,
-	displayModeOf,
+	DISPLAY_OPTION,
 	displayUnavailableError,
 	PICO8_ENV,
 	pico8NotFoundError,
+	resolveCommandDisplay,
 	type Pico8AdapterFactory,
 } from './pico8-env.js';
 
@@ -96,6 +97,7 @@ export function registerRun(
 				.describe(
 					'One-shot scripted input passed as `-p` (the cart reads it via stat(6)) for automated playtests.',
 				),
+			display: DISPLAY_OPTION,
 			recordAudio: z
 				.boolean()
 				.default(false)
@@ -183,8 +185,12 @@ export function registerRun(
 					: mkdtempSync(join(tmpdir(), 'picopilot-run-'));
 			if (!existsSync(shotDir)) mkdirSync(shotDir, {recursive: true});
 
+			// The display mode only matters to the --record-audio (-run) pass, so a
+			// bad PICOPILOT_DISPLAY only fails a run that records.
+			const display = resolveCommandDisplay(options.display, vars);
+			if (options.recordAudio && !display.ok) return error(display.error);
 			const adapter = adapterFactory(env as NodeJS.ProcessEnv, {
-				display: displayModeOf(vars),
+				display: display.ok ? display.mode : 'auto',
 			});
 			const result = await adapter.run({
 				cartPath,

package/src/commands/sfx.test.ts

@@ -7,6 +7,9 @@ import {afterEach, beforeEach, describe, expect, it} from 'vitest';
 import {mmlToSfxRow, SFX_ROW_LENGTH} from '../engine/audio/index.js';
 import {createCli} from '../cli.js';
 
+/** The .p8 header lines. */
+const HEADER = 'pico-8 cartridge // http://www.pico-8.com\nversion 42\n';
+
 /** A minimal valid cart with a lua + gfx section (to prove they stay untouched). */
 function cartText(sfxBody?: string): string {
 	let text =
@@ -347,3 +350,55 @@ describe('picopilot sfx from-mml: dotted-length rounding is reported', () => {
 		expect(out.warnings[0]).toContain('rounded');
 	});
 });
+
+describe('picopilot sfx clear', () => {
+	it('clears the named slots and nothing else', async () => {
+		const a = mmlToSfxRow('s4 c').row;
+		const b = mmlToSfxRow('s5 d').row;
+		const c = mmlToSfxRow('s6 e0 c').row;
+		writeFileSync(
+			cartPath,
+			`${HEADER}__lua__\nprint(1)\n__sfx__\n${a}\n${b}\n${c}\n`,
+		);
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'clear',
+			'1,5',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).toBe(0);
+		const out = JSON.parse(stdout);
+		expect(out.cleared).toEqual([1]);
+		expect(out.alreadyEmpty).toEqual([5]);
+		const text = readFileSync(cartPath, 'utf8');
+		expect(text).toContain(`${a}\n${'0'.repeat(168)}\n${c}\n`);
+	});
+
+	it('clearing the last slots trims them (what PICO-8 writes)', async () => {
+		const a = mmlToSfxRow('s4 c').row;
+		writeFileSync(
+			cartPath,
+			`${HEADER}__lua__\nprint(1)\n__sfx__\n${a}\n${a}\n`,
+		);
+		await runSfx(['sfx', 'clear', '1-63', '--cart', cartPath, '--json']);
+		expect(readFileSync(cartPath, 'utf8')).toBe(
+			`${HEADER}__lua__\nprint(1)\n__sfx__\n${a}\n`,
+		);
+	});
+
+	it('refuses a bad slot list', async () => {
+		writeFileSync(cartPath, `${HEADER}__lua__\nprint(1)\n`);
+		const {stdout, exitCode} = await runSfx([
+			'sfx',
+			'clear',
+			'70',
+			'--cart',
+			cartPath,
+			'--json',
+		]);
+		expect(exitCode).not.toBe(0);
+		expect(stdout).toContain('bad-slot-list');
+	});
+});