picopilot 0.0.0 → 0.1.0

package/dist/commands/sfx.js

@@ -0,0 +1,254 @@
+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) {
+    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) {
+    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() {
+    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;
+            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;
+            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.command(buildSfxGroup());
+}
+//# sourceMappingURL=sfx.js.map

package/dist/commands/sfx.js.map

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

package/dist/commands/tokens.d.ts

@@ -0,0 +1,36 @@
+import { type Cli } from 'incur';
+import { type ShrinkoAdapter } from '../engine/shrinko/index.js';
+/** PICO-8's Lua token budget. A cart over this will not load in PICO-8 (US #3). */
+export declare const TOKEN_BUDGET = 8192;
+/**
+ * Builds the {@link ShrinkoAdapter} a command uses, given the incur-resolved
+ * env. The default is the shell-out {@link ShellShrinkoAdapter}, whose child
+ * process inherits ONLY this `env` (its `PATH` is the test isolation lever).
+ *
+ * A test passes its own factory to {@link registerTokens} to SWAP a stub
+ * adapter (the seam-swap contract): the command's public output/exit must be
+ * unchanged whether the real shell adapter or a native-TS stub is behind the
+ * seam, because the command only ever talks to the {@link ShrinkoAdapter}
+ * interface.
+ */
+export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+/**
+ * Registers `picopilot tokens` (US #3), the first shrinko-backed command.
+ *
+ * It reports `{tokens, pct, chars, compressed}` for a cart against the 8,192
+ * token budget via shrinko8 `--count`, and CTAs to `minify` when over budget so
+ * the agent is led straight to the fix (the detect-then-fix loop, ADR CTAs).
+ *
+ * Two-tier contract (ADR-0002): `tokens` is shrinko-BACKED, so with shrinko
+ * ABSENT it returns the structured `shrinko-not-found` error (nonzero exit,
+ * exact remedy `uv pip install shrinko`) rather than crashing or reporting a
+ * hollow zero. The dependency is reached entirely through the {@link
+ * ShrinkoAdapter} seam, so a native-TS shrinko would satisfy this command
+ * unchanged.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to swap the seam and to drive present/absent without the
+ *   real binary.
+ */
+export declare function registerTokens(cli: Cli.Cli, adapterFactory?: ShrinkoAdapterFactory): void;
+//# sourceMappingURL=tokens.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/commands/tokens.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,KAAK,GAAG,EAAI,MAAM,OAAO,CAAC;AAElC,OAAO,EACN,KAAK,cAAc,EAGnB,MAAM,4BAA4B,CAAC;AAEpC,mFAAmF;AACnF,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,cAAc,CAAC;AAK/E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,GAAG,CAAC,GAAG,EACZ,cAAc,GAAE,qBAA6C,GAC3D,IAAI,CAqHN"}

package/dist/commands/tokens.js

@@ -0,0 +1,129 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { z } from 'incur';
+import { ShrinkoParseError, ShellShrinkoAdapter, } from '../engine/shrinko/index.js';
+/** PICO-8's Lua token budget. A cart over this will not load in PICO-8 (US #3). */
+export const TOKEN_BUDGET = 8192;
+const defaultAdapterFactory = (env) => new ShellShrinkoAdapter({ env });
+/**
+ * Registers `picopilot tokens` (US #3), the first shrinko-backed command.
+ *
+ * It reports `{tokens, pct, chars, compressed}` for a cart against the 8,192
+ * token budget via shrinko8 `--count`, and CTAs to `minify` when over budget so
+ * the agent is led straight to the fix (the detect-then-fix loop, ADR CTAs).
+ *
+ * Two-tier contract (ADR-0002): `tokens` is shrinko-BACKED, so with shrinko
+ * ABSENT it returns the structured `shrinko-not-found` error (nonzero exit,
+ * exact remedy `uv pip install shrinko`) rather than crashing or reporting a
+ * hollow zero. The dependency is reached entirely through the {@link
+ * ShrinkoAdapter} seam, so a native-TS shrinko would satisfy this command
+ * unchanged.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to swap the seam and to drive present/absent without the
+ *   real binary.
+ */
+export function registerTokens(cli, adapterFactory = defaultAdapterFactory) {
+    cli.command('tokens', {
+        description: 'Count a cart against the 8,192-token PICO-8 budget (via shrinko8 --count). Requires shrinko.',
+        args: z.object({
+            cart: z
+                .string()
+                .default('main.p8')
+                .describe('The .p8 cart to count. Defaults to main.p8 in the current folder.'),
+        }),
+        // Declaring PATH here makes incur resolve it from the (test-overridable)
+        // env source and hand it to us, so we pass a controlled PATH to the child.
+        env: z.object({
+            PATH: z
+                .string()
+                .optional()
+                .describe('Used to locate shrinko8 in the child process.'),
+        }),
+        output: z.object({
+            tokens: z.number().describe('The token count shrinko reported.'),
+            pct: z
+                .number()
+                .describe('tokens as a percentage of the 8,192 budget (rounded); >100 means over budget.'),
+            chars: z.number().describe('The character count shrinko reported.'),
+            compressed: z
+                .number()
+                .optional()
+                .describe('The compressed byte count (absent for some input formats).'),
+            budget: z
+                .number()
+                .describe('The token budget the percentage is against (8192).'),
+            overBudget: z.boolean().describe('True when tokens exceed the budget.'),
+        }),
+        examples: [
+            { description: 'Count main.p8' },
+            { description: 'Count 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 shrinko absence:
+            // surface it clearly instead of letting shrinko fail opaquely on the path.
+            if (!existsSync(cartPath)) {
+                return error({
+                    code: 'cart-not-found',
+                    message: `no cart at ${cartPath}`,
+                    exitCode: 1,
+                });
+            }
+            const adapter = adapterFactory(env);
+            let result;
+            try {
+                result = await adapter.count(cartPath);
+            }
+            catch (e) {
+                // shrinko RAN but its output was unparseable (version/format drift):
+                // a distinct `shrinko-failed`, NOT `shrinko-not-found` (which is absence).
+                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;
+            }
+            if (!result.ok) {
+                // The two-tier structured failure (ADR-0002 / US #17): shrinko absent.
+                // The message CARRIES the exact remedy + needs so an agent reading only
+                // the message still learns the fix; the code is the machine handle.
+                return error({
+                    code: result.reason,
+                    message: `shrinko is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+                    exitCode: 1,
+                });
+            }
+            const { tokens, chars, compressed } = result.value;
+            const pct = Math.round((tokens / TOKEN_BUDGET) * 100);
+            const overBudget = tokens > TOKEN_BUDGET;
+            // Over budget → CTA to `minify` (the detect-then-fix loop). Under budget
+            // needs no CTA: nothing to do.
+            const cta = overBudget
+                ? {
+                    description: 'Over the 8,192-token budget. Reclaim tokens with:',
+                    commands: [
+                        {
+                            command: 'minify',
+                            description: 'Safe-minify the cart to reduce tokens without changing behaviour.',
+                        },
+                    ],
+                }
+                : undefined;
+            return ok({
+                tokens,
+                pct,
+                chars,
+                compressed,
+                budget: TOKEN_BUDGET,
+                overBudget,
+            }, cta === undefined ? undefined : { cta });
+        },
+    });
+}
+//# sourceMappingURL=tokens.js.map

package/dist/commands/tokens.js.map

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

package/dist/commands/verify.d.ts

@@ -0,0 +1,57 @@
+import { type Cli } from 'incur';
+import { type ShrinkoAdapter } from '../engine/shrinko/index.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 declare const VERIFY_SCOPE: "static gate: tokens + integrity; passing does NOT mean the cart runs";
+/**
+ * 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 declare const GATE_INCAPABLE_EXIT = 2;
+/** See {@link ShrinkoAdapterFactory} in `tokens.ts` — verify reuses the same seam. */
+export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+/**
+ * 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 declare function registerVerify(cli: Cli.Cli, adapterFactory?: ShrinkoAdapterFactory): void;
+//# sourceMappingURL=verify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/commands/verify.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,KAAK,GAAG,EAAI,MAAM,OAAO,CAAC;AAGlC,OAAO,EACN,KAAK,cAAc,EAGnB,MAAM,4BAA4B,CAAC;AAGpC;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EACxB,sEAA+E,CAAC;AAEjF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,sFAAsF;AACtF,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,cAAc,CAAC;AA2C/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,GAAG,CAAC,GAAG,EACZ,cAAc,GAAE,qBAA6C,GAC3D,IAAI,CA8IN"}