picopilot 0.0.0 → 0.1.1

package/dist/commands/music.js

@@ -0,0 +1,241 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { Cli, z } from 'incur';
+import { MusicError, patternsToMusic, SFX_INDEX_MAX, setMusicSection, } 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) {
+    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 sfx/gfx command loaders.
+ */
+function loadCart(cartPath) {
+    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;
+    }
+}
+/**
+ * Reads the pattern-list JSON into the codec's `Pattern[]` model (finding B.6).
+ *
+ * The serialization is JSON: an array of `{channels:[c0,c1,c2,c3], loopStart?,
+ * loopBack?, stop?}` (see the command help). This maps 1:1 to the finding's B.6
+ * model, so an author (human or agent) writes exactly that structure. An SFX
+ * reference is a number 0..63; an OFF channel is `null` (distinct from sfx 0, per
+ * finding B.7 #9). This parser is deliberately structural-only: it accepts the
+ * shape and hands it to the codec, which owns range/count validation.
+ */
+function parsePatterns(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (e) {
+        return {
+            ok: false,
+            code: 'audio-music-parse-error',
+            message: `pattern list is not valid JSON: ${e instanceof Error ? e.message : String(e)}. Expected an array of patterns, e.g. [{"channels":[0,1,null,3],"loopStart":true}].`,
+        };
+    }
+    if (!Array.isArray(raw)) {
+        return {
+            ok: false,
+            code: 'audio-music-parse-error',
+            message: 'pattern list must be a JSON array of patterns, e.g. [{"channels":[0,1,null,3]}]. Each channel is an SFX index 0..63 or null (off).',
+        };
+    }
+    // Hand the array straight to the codec as Pattern[]; the codec validates
+    // channel count + sfx range structurally and refuses out-of-range values.
+    return { ok: true, patterns: raw };
+}
+/**
+ * Builds the `music` command group. Currently just `music from-patterns` (the
+ * structural pattern-list to `__music__` codec + cart merge).
+ */
+function buildMusicGroup() {
+    const music = Cli.create('music', {
+        description: 'Assemble music STRUCTURALLY: an ordered list of up-to-4 SFX-channel references per pattern -> __music__. There is NO melodic content in __music__; melody lives in the referenced SFX (built by `sfx from-mml`). Pattern LENGTH is inherited from the referenced SFX (the left-most non-looping channel), NOT stored per pattern.',
+    });
+    music.command('from-patterns', {
+        description: 'Assemble a JSON pattern list into __music__ and merge it into the cart (only __music__ changes; every other section incl. __sfx__ stays byte-identical). A pattern is {"channels":[c0,c1,c2,c3], loopStart?, loopBack?, stop?}: each channel is an SFX index 0-63 OR null = OFF (silent this pattern; null is NOT sfx 0). Flags: loopStart (0x01), loopBack (0x02, jump back to loop-start), stop (0x04). Pattern order = song order. Pattern length is INHERITED from the referenced SFX (its speed + LEN via `sfx from-mml`), so no per-pattern length is stored. Out-of-range SFX index is refused; loopBack with no loopStart warns (PICO-8 falls back to pattern 0), not a crash.',
+        args: z.object({
+            patterns: z
+                .string()
+                .optional()
+                .describe('The pattern list as JSON: an array of {"channels":[c0,c1,c2,c3], loopStart?, loopBack?, stop?}. A channel is an SFX index 0-63 or null (off). Omit and pass --file to read from a file instead. Example: \'[{"channels":[0,1,null,3],"loopStart":true},{"channels":[2,2,2,2],"loopBack":true,"stop":true}]\'.'),
+        }),
+        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 `patterns` when using --file.)'),
+            file: z
+                .string()
+                .optional()
+                .describe('Read the JSON pattern list from this file instead of the `patterns` argument (for longer songs).'),
+        }),
+        output: z.object({
+            cart: z
+                .string()
+                .describe('The absolute path of the cart that was written.'),
+            patterns: z
+                .number()
+                .describe('The number of patterns written (= song length).'),
+            section: z
+                .string()
+                .describe('The __music__ section body that was merged.'),
+            warnings: z
+                .array(z.string())
+                .describe('Advisory warnings (e.g. loopBack with no loopStart -> PICO-8 loops to pattern 0).'),
+        }),
+        examples: [
+            {
+                description: 'A two-pattern loop (pattern 0 loops back to itself)',
+                args: {
+                    patterns: '[{"channels":[0,1,2,3],"loopStart":true},{"channels":[0,1,2,3],"loopBack":true}]',
+                },
+            },
+            {
+                description: 'A pattern with channel 2 OFF (silent), not sfx 0',
+                args: { patterns: '[{"channels":[0,1,null,3]}]' },
+                options: { cart: 'game.p8' },
+            },
+            {
+                description: 'Read a longer song from a file',
+                args: {},
+                options: { file: 'song.json' },
+            },
+        ],
+        run({ args, options, error, ok }) {
+            // Resolve the pattern-list source: the `patterns` arg OR `--file` (exactly
+            // one). Pure text, shrinko-free + PICO-8-free (mirrors `sfx from-mml`).
+            let text;
+            if (options.file !== undefined) {
+                if (args.patterns !== undefined) {
+                    return error({
+                        code: 'ambiguous-input',
+                        message: 'pass EITHER the patterns 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: 'patterns-file-not-found',
+                        message: `no pattern-list file at ${filePath}`,
+                        exitCode: 1,
+                    });
+                }
+                text = readFileSync(filePath, 'utf8');
+            }
+            else if (args.patterns !== undefined) {
+                text = args.patterns;
+            }
+            else {
+                return error({
+                    code: 'no-patterns',
+                    message: 'no pattern list: pass it as the `patterns` argument (JSON) or via --file.',
+                    exitCode: 1,
+                });
+            }
+            const parsed = parsePatterns(text);
+            if (!parsed.ok) {
+                return error({ code: parsed.code, message: parsed.message, exitCode: 1 });
+            }
+            // Transpile FIRST: a bad list is a caller error and must never touch the
+            // cart (no bytes change on a refusal), mirroring `sfx from-mml`.
+            let result;
+            try {
+                result = patternsToMusic(parsed.patterns);
+            }
+            catch (e) {
+                if (e instanceof MusicError) {
+                    const cta = e.code === 'audio-music-sfx-out-of-range'
+                        ? {
+                            description: `SFX indices are a hard range (0..${SFX_INDEX_MAX}); to silence a channel use null, not an out-of-range index:`,
+                            commands: [
+                                {
+                                    command: 'sfx from-mml <slot> "<mml>"',
+                                    description: `Author the SFX you reference first (slots 0..${SFX_INDEX_MAX}), then arrange them here.`,
+                                },
+                            ],
+                        }
+                        : 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 });
+            }
+            // Replace __music__ ONLY, through the cart model, so every other section
+            // (and __sfx__) stays byte-identical.
+            setMusicSection(loaded.cart, result.section);
+            writeFileSync(cartPath, loaded.cart.serialize());
+            const warnings = result.warnings.map((w) => w.message);
+            // CTA toward the verify/hear loop: a merged song is next confirmed by
+            // verify (static integrity) and heard via `audio render`.
+            return ok({
+                cart: cartPath,
+                patterns: result.patterns,
+                section: result.section,
+                warnings,
+            }, {
+                cta: {
+                    description: 'The song 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 music;
+}
+/**
+ * Registers the `music` command group (`music from-patterns`) 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
+ * entirely in TS, so it works with both absent and never spawns a child process.
+ * Music is STRUCTURAL (ADR-0005 + the audio spike finding A.5/B.6): a pattern
+ * list of SFX references, NOT a notation. "Off" (bit6) is distinct from "sfx 0",
+ * and pattern length is inherited from the referenced SFX (stored nowhere here).
+ */
+export function registerMusic(cli) {
+    cli.command(buildMusicGroup());
+}
+//# sourceMappingURL=music.js.map

package/dist/commands/music.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"music.js","sourceRoot":"","sources":["../../src/commands/music.ts"],"names":[],"mappings":"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"}

package/dist/commands/playtest.d.ts

@@ -0,0 +1,29 @@
+import { type Cli } from 'incur';
+import { type Pico8Adapter } from '../engine/pico8/index.js';
+/**
+ * Injects the PICO-8 adapter `playtest` uses (defaults to the shell adapter over
+ * native `pico8 -x`). Mirrors `run`'s `Pico8AdapterFactory` seam: a test passes a
+ * stub to drive the drive-orchestration + the absent path WITHOUT the paid
+ * binary, and to isolate the child `env` (its `PICO8_PATH`/`PATH`).
+ */
+export type Pico8AdapterFactory = (env: NodeJS.ProcessEnv) => Pico8Adapter;
+/**
+ * Registers `picopilot playtest`, the driven-playtest command group (ADR-0011).
+ * The ROOT command (`playtest <cart>`) is the ONE-SHOT driver (US #1-5,7-11): it
+ * sends the whole scripted input up front and captures gameplay in one envelope.
+ * The SUBCOMMANDS are the RESUMABLE LIVE SESSION (US #6, the "A" model): `start`
+ * launches a persistent driven process the agent addresses BY ID, and `step` /
+ * `input` / `shot` / `stop` / `status` drive it across SEPARATE invocations while
+ * the game stays alive + paused between turns, over the same verified block+ACK
+ * transport. The cart-side drive-transform is reused UNCHANGED (see `drive.ts`).
+ *
+ * PICO-8 absent -> structured `pico8-not-found` + nonzero exit (mirrors `run`),
+ * never a crash or a hang. The CI-testable surface is the pure transform + the
+ * session handshake core (against a fake process); a live multi-turn session is
+ * the manual/opt-in tier.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to drive present/absent without the real binary.
+ */
+export declare function registerPlaytest(cli: Cli.Cli, adapterFactory?: Pico8AdapterFactory): void;
+//# sourceMappingURL=playtest.d.ts.map

package/dist/commands/playtest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playtest.d.ts","sourceRoot":"","sources":["../../src/commands/playtest.ts"],"names":[],"mappings":"AASA,OAAO,EAAC,KAAK,GAAG,EAAqB,MAAM,OAAO,CAAC;AACnD,OAAO,EAMN,KAAK,YAAY,EAajB,MAAM,0BAA0B,CAAC;AAElC;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,YAAY,CAAC;AAiD3E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAC/B,GAAG,EAAE,GAAG,CAAC,GAAG,EACZ,cAAc,GAAE,mBAA2C,GACzD,IAAI,CAEN"}