picopilot 0.0.0 → 0.1.0

package/dist/commands/run.d.ts

@@ -0,0 +1,30 @@
+import { type Cli } from 'incur';
+import { type Pico8Adapter } from '../engine/pico8/index.js';
+/**
+ * Injects the PICO-8 adapter `run` uses (defaults to the shell adapter over
+ * native `pico8 -x`). Mirrors the shrinko `adapterFactory` seam: a test passes a
+ * stub to drive the sentinel/backstop/absent paths without the paid binary, and
+ * to isolate the child `env` (its `PICO8_PATH`/`PATH`).
+ */
+export type Pico8AdapterFactory = (env: NodeJS.ProcessEnv) => Pico8Adapter;
+/**
+ * Registers `picopilot run`, the THIN sentinel-watch + screenshot-collect
+ * orchestration command (US #14, ADR-0006). It is NOT a `pico8` wrapper: its
+ * value is the glue an agent should not hand-roll every run, launch PICO-8,
+ * stream stdout, kill on the cart's done-sentinel (backstop as the safety net),
+ * and collect screenshots + printh + exit reason into ONE structured result.
+ *
+ * The cart cooperates: it self-screenshots via `extcmd("screen")` on a timer and
+ * prints the done-sentinel via `printh` when finished (the `picopilot-debug`
+ * skill teaches the recipe). A cart cannot self-quit the app, so the external
+ * sentinel-kill IS the quit mechanism.
+ *
+ * PICO-8 absent → structured `pico8-not-found` + nonzero exit (mirrors the
+ * shrinko boundary), never a crash or a hang. That absent path is the one
+ * exercised in CI; live runs are a 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 registerRun(cli: Cli.Cli, adapterFactory?: Pico8AdapterFactory): void;
+//# sourceMappingURL=run.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/commands/run.ts"],"names":[],"mappings":"AASA,OAAO,EAAC,KAAK,GAAG,EAAI,MAAM,OAAO,CAAC;AAClC,OAAO,EAIN,KAAK,YAAY,EAEjB,MAAM,0BAA0B,CAAC;AAElC;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,YAAY,CAAC;AAQ3E;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAC1B,GAAG,EAAE,GAAG,CAAC,GAAG,EACZ,cAAc,GAAE,mBAA2C,GACzD,IAAI,CA4MN"}

package/dist/commands/run.js

@@ -0,0 +1,202 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { z } from 'incur';
+import { buildRecordHarness, DONE_SENTINEL, HarnessError, ShellPico8Adapter, } from '../engine/pico8/index.js';
+const defaultAdapterFactory = (env) => new ShellPico8Adapter({ env });
+/** The default backstop: kill a cart that never signals/exits after this many ms. */
+const DEFAULT_BACKSTOP_MS = 15_000;
+/**
+ * Registers `picopilot run`, the THIN sentinel-watch + screenshot-collect
+ * orchestration command (US #14, ADR-0006). It is NOT a `pico8` wrapper: its
+ * value is the glue an agent should not hand-roll every run, launch PICO-8,
+ * stream stdout, kill on the cart's done-sentinel (backstop as the safety net),
+ * and collect screenshots + printh + exit reason into ONE structured result.
+ *
+ * The cart cooperates: it self-screenshots via `extcmd("screen")` on a timer and
+ * prints the done-sentinel via `printh` when finished (the `picopilot-debug`
+ * skill teaches the recipe). A cart cannot self-quit the app, so the external
+ * sentinel-kill IS the quit mechanism.
+ *
+ * PICO-8 absent → structured `pico8-not-found` + nonzero exit (mirrors the
+ * shrinko boundary), never a crash or a hang. That absent path is the one
+ * exercised in CI; live runs are a 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 function registerRun(cli, adapterFactory = defaultAdapterFactory) {
+    cli.command('run', {
+        description: "Run a cart on the user's PICO-8, capture printh + screenshots, end on a done-sentinel. Requires PICO-8.",
+        args: z.object({
+            cart: z
+                .string()
+                .default('main.p8')
+                .describe('The .p8 cart to run. Defaults to main.p8 in the current folder.'),
+        }),
+        options: z.object({
+            shotDir: z
+                .string()
+                .optional()
+                .describe('Where PICO-8 writes screenshots (-desktop). Defaults to an isolated temp dir; NEVER ~/Desktop.'),
+            sentinel: z
+                .string()
+                .default(DONE_SENTINEL)
+                .describe('The stdout line that ends the run. The cart printh-es this when done.'),
+            backstopMs: z
+                .number()
+                .int()
+                .positive()
+                .default(DEFAULT_BACKSTOP_MS)
+                .describe('Safety backstop: kill PICO-8 after this many ms if it never signals.'),
+            input: z
+                .string()
+                .optional()
+                .describe('One-shot scripted input passed as `-p` (the cart reads it via stat(6)) for automated playtests.'),
+            recordAudio: z
+                .boolean()
+                .default(false)
+                .describe("Also capture a WAV of the run's audio alongside the screenshots (ADR-0009). A REAL-TIME recording that needs a real audio+video session (a separate -run pass, NOT the headless screenshot pass), never an offline export."),
+        }),
+        // incur resolves these from the (test-overridable) env source and hands
+        // them to the child, so PICO8_PATH/PATH locate the binary in isolation.
+        env: z.object({
+            PICO8_PATH: z
+                .string()
+                .optional()
+                .describe('Explicit path to the PICO-8 binary (else `pico8` on PATH).'),
+            PATH: z.string().optional().describe('Used to locate `pico8`.'),
+        }),
+        output: z.object({
+            screenshots: z
+                .array(z.string())
+                .describe('Absolute paths of the PNG screenshots the cart produced.'),
+            printh: z
+                .string()
+                .describe('Captured stdout (the cart printh output + PICO-8 lines).'),
+            exitReason: z
+                .enum(['sentinel', 'timeout', 'exit'])
+                .describe('sentinel = cart signalled done; timeout = backstop fired; exit = PICO-8 quit.'),
+            shotDir: z.string().describe('The dir screenshots were written to.'),
+            wav: z
+                .string()
+                .optional()
+                .describe('Absolute path of the captured WAV (only with --record-audio; omitted if no audio was captured).'),
+            audioCaptured: z
+                .boolean()
+                .describe('Whether a non-empty WAV was captured (false unless --record-audio ran and produced audio).'),
+        }),
+        examples: [
+            { description: 'Run main.p8' },
+            { description: 'Run a specific cart', args: { cart: 'game.p8' } },
+            {
+                description: 'Collect screenshots into a chosen dir',
+                args: { cart: 'game.p8' },
+                options: { shotDir: './shots' },
+            },
+        ],
+        async run({ args, options, 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 PICO-8 absence.
+            if (!existsSync(cartPath)) {
+                return error({
+                    code: 'cart-not-found',
+                    message: `no cart at ${cartPath}`,
+                    exitCode: 1,
+                });
+            }
+            // Screenshot dir: a user-given path, else an isolated temp dir. NEVER the
+            // default ~/Desktop (the `-desktop` flag is the isolation lever). Create
+            // it so PICO-8 has somewhere to write.
+            const shotDir = options.shotDir !== undefined
+                ? isAbsolute(options.shotDir)
+                    ? options.shotDir
+                    : resolve(process.cwd(), options.shotDir)
+                : mkdtempSync(join(tmpdir(), 'picopilot-run-'));
+            if (!existsSync(shotDir))
+                mkdirSync(shotDir, { recursive: true });
+            const adapter = adapterFactory(env);
+            const result = await adapter.run({
+                cartPath,
+                shotDir,
+                sentinel: options.sentinel,
+                backstopMs: options.backstopMs,
+                input: options.input,
+            });
+            if (!result.ok) {
+                // The two-tier structured failure (US #19, ADR-0006): PICO-8 absent.
+                // The message carries the exact remedy + needs; the code is the handle.
+                return error({
+                    code: result.reason,
+                    message: `PICO-8 is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+                    exitCode: 1,
+                });
+            }
+            const { screenshots, printh, exitReason } = result.value;
+            // --record-audio: an ADDITIVE second pass that records the run's audio to a
+            // WAV. It cannot reuse the headless `-x` screenshot pass (which mixes no
+            // audio -> an empty WAV, ADR-0009), so it does a separate `-run` capture via
+            // the record seam, injecting the same cooperative recorder `audio record`
+            // uses. The WAV lands in the isolated shotDir alongside the screenshots.
+            let wav;
+            let audioCaptured = false;
+            if (options.recordAudio) {
+                try {
+                    const harness = buildRecordHarness(readFileSync(cartPath, 'utf8'), {
+                        sentinel: options.sentinel,
+                    });
+                    const harnessCart = join(shotDir, 'record-audio-harness.p8');
+                    writeFileSync(harnessCart, harness.cartText);
+                    const rec = await adapter.record({
+                        cartPath: harnessCart,
+                        wavDir: shotDir,
+                        wavBasename: harness.wavBasename,
+                        sentinel: options.sentinel,
+                        backstopMs: options.backstopMs,
+                    });
+                    if (rec.ok) {
+                        wav = rec.value.wavPath;
+                        audioCaptured = rec.value.wavPath !== undefined;
+                    }
+                    // A record-pass pico8-not-found is impossible here: the screenshot
+                    // pass above already returned pico8-not-found if PICO-8 were absent.
+                }
+                catch (e) {
+                    if (!(e instanceof HarnessError))
+                        throw e;
+                    // A harness-build failure (unparseable cart) leaves audioCaptured false;
+                    // the screenshot run's report still stands.
+                }
+            }
+            // A backstop timeout is a soft warning: the cart never signalled done, so
+            // it may have hung or errored. CTA the agent toward the static checks
+            // (lint/tokens) to catch a code fault before re-running.
+            const cta = exitReason === 'timeout'
+                ? {
+                    description: 'The cart never printed the done-sentinel (backstop fired). Check for a fault:',
+                    commands: [
+                        {
+                            command: 'verify',
+                            description: 'Run the static gate (tokens + lint + integrity).',
+                        },
+                        {
+                            command: 'tokens',
+                            description: 'Confirm the cart is under the token budget.',
+                        },
+                    ],
+                }
+                : undefined;
+            return ok({
+                screenshots: [...screenshots],
+                printh,
+                exitReason,
+                shotDir,
+                wav,
+                audioCaptured,
+            }, cta === undefined ? undefined : { cta });
+        },
+    });
+}
+//# sourceMappingURL=run.js.map

package/dist/commands/run.js.map

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

package/dist/commands/serve.d.ts

@@ -0,0 +1,50 @@
+import { type Server } from 'node:http';
+import { type Cli } from 'incur';
+import { type Pico8Adapter } from '../engine/pico8/index.js';
+/**
+ * Injects the PICO-8 adapter `serve` uses (defaults to the shell adapter). Same
+ * seam as `export`/`run`: a test passes a stub so the export step needs no paid
+ * binary, and the child `env` (`PICO8_PATH`/`PATH`) stays isolated.
+ */
+export type Pico8AdapterFactory = (env: NodeJS.ProcessEnv) => Pico8Adapter;
+/**
+ * Injects the HTTP-server factory `serve` binds. The default is a zero-dep
+ * `node:http` static server over the export dir; a test injects a fake to assert
+ * the serve loop WITHOUT opening a real socket. The factory returns the started
+ * server plus the bound port (so `:0` -> an OS-assigned port is observable).
+ */
+export type ServerFactory = (rootDir: string, port: number) => Promise<{
+    server: Server;
+    port: number;
+}>;
+/**
+ * Registers a one-shot cleanup for the serving case: `serve` runs until the user
+ * interrupts it (the socket keeps the process alive), so the temp export dir is
+ * removed on SIGINT/SIGTERM and on normal `exit`. The handler fires at most once.
+ * The default uses `process`; a test injects a fake to assert the wiring without
+ * touching real signal handlers.
+ */
+export type CleanupRegistrar = (cleanup: () => void) => void;
+/**
+ * Registers `picopilot serve`, the "play this cart in a browser" loop. It ALWAYS
+ * exports first (the quick round-trip: cart -> standalone HTML bundle -> local
+ * server -> URL you open), so it takes a cart path, not a pre-built dir. The
+ * export step hard-requires PICO-8 (absence is the structured `pico8-not-found`
+ * value + a nonzero exit, mirroring `run`/`export`); the static server itself is
+ * a zero-dep `node:http` file server over the temp export dir, so no extra
+ * dependency and no ~/Desktop pollution.
+ *
+ * It is distinct from `export`: `export` PRODUCES a bundle at a chosen dest (for
+ * the showcase); `serve` throws the bundle in a temp dir and serves it for a
+ * quick manual play. It runs until interrupted (the server keeps the process
+ * alive), which is why the injected {@link ServerFactory} seam lets a test drive
+ * the export + bind path without leaving a real socket open.
+ *
+ * @param adapterFactory injects the PICO-8 adapter (defaults to the shell one).
+ * @param serverFactory injects the HTTP server (defaults to the zero-dep static
+ *   server); a test passes a fake to assert the loop without a real socket.
+ * @param registerCleanup injects the exit/signal cleanup wiring (defaults to the
+ *   real `process` handlers); a test passes a fake to capture the cleanup fn.
+ */
+export declare function registerServe(cli: Cli.Cli, adapterFactory?: Pico8AdapterFactory, serverFactory?: ServerFactory, registerCleanup?: CleanupRegistrar): void;
+//# sourceMappingURL=serve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AAOA,OAAO,EAAe,KAAK,MAAM,EAAC,MAAM,WAAW,CAAC;AAGpD,OAAO,EAAC,KAAK,GAAG,EAAI,MAAM,OAAO,CAAC;AAClC,OAAO,EAEN,KAAK,YAAY,EAEjB,MAAM,0BAA0B,CAAC;AAElC;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,YAAY,CAAC;AAK3E;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,KACR,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC,CAAC;AAiB7C;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AA6E7D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAC5B,GAAG,EAAE,GAAG,CAAC,GAAG,EACZ,cAAc,GAAE,mBAA2C,EAC3D,aAAa,GAAE,aAAoC,EACnD,eAAe,GAAE,gBAA0C,GACzD,IAAI,CA4GN"}

package/dist/commands/serve.js

@@ -0,0 +1,213 @@
+import { createReadStream, existsSync, mkdtempSync, rmSync, statSync, } from 'node:fs';
+import { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { extname, isAbsolute, join, normalize, resolve } from 'node:path';
+import { z } from 'incur';
+import { EXPORT_HTML_NAME, ShellPico8Adapter, } from '../engine/pico8/index.js';
+const defaultAdapterFactory = (env) => new ShellPico8Adapter({ env });
+const DEFAULT_PORT = 5858;
+const DEFAULT_BACKSTOP_MS = 30_000;
+/**
+ * Best-effort recursive removal of the temp export dir, swallowing any error (a
+ * cleanup failure must never mask the command's own result or crash on exit).
+ */
+function removeDir(dir) {
+    try {
+        rmSync(dir, { recursive: true, force: true });
+    }
+    catch {
+        // A stubborn temp dir is not fatal; the OS reaps it eventually.
+    }
+}
+const defaultCleanupRegistrar = (cleanup) => {
+    let done = false;
+    const once = () => {
+        if (done)
+            return;
+        done = true;
+        cleanup();
+    };
+    process.once('exit', once);
+    // On a signal, run cleanup then re-exit so the temp dir is gone even on Ctrl-C.
+    process.once('SIGINT', () => {
+        once();
+        process.exit(130);
+    });
+    process.once('SIGTERM', () => {
+        once();
+        process.exit(143);
+    });
+};
+/** MIME types the static server needs for a PICO-8 export (html + the runtime js). */
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.wasm': 'application/wasm',
+    '.png': 'image/png',
+    '.json': 'application/json; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+};
+/**
+ * The default {@link ServerFactory}: a minimal, zero-dependency `node:http`
+ * static file server rooted at `rootDir`. It resolves `/` to `index.html`,
+ * path-traversal-guards every request against `rootDir`, and streams files with
+ * a best-effort content type. It exists to PLAY an export locally, not to be a
+ * production server. Binding `:0` yields an OS-assigned port, reported back so
+ * the command can print the real URL.
+ */
+const defaultServerFactory = (rootDir, port) => new Promise((resolvePromise, reject) => {
+    const server = createServer((req, res) => {
+        const urlPath = decodeURIComponent((req.url ?? '/').split('?')[0]);
+        // Resolve the request against the root and guard against traversal: the
+        // resolved path must stay inside rootDir.
+        const rel = normalize(urlPath).replace(/^(\.\.[/\\])+/, '');
+        let filePath = join(rootDir, rel);
+        if (!filePath.startsWith(rootDir)) {
+            res.writeHead(403).end('forbidden');
+            return;
+        }
+        try {
+            if (existsSync(filePath) && statSync(filePath).isDirectory()) {
+                filePath = join(filePath, 'index.html');
+            }
+            if (!existsSync(filePath)) {
+                res.writeHead(404).end('not found');
+                return;
+            }
+            res.writeHead(200, {
+                'content-type': MIME[extname(filePath).toLowerCase()] ?? 'application/octet-stream',
+            });
+            createReadStream(filePath).pipe(res);
+        }
+        catch {
+            res.writeHead(500).end('server error');
+        }
+    });
+    server.on('error', reject);
+    server.listen(port, '127.0.0.1', () => {
+        const addr = server.address();
+        const bound = typeof addr === 'object' && addr !== null ? addr.port : port;
+        resolvePromise({ server, port: bound });
+    });
+});
+/**
+ * Registers `picopilot serve`, the "play this cart in a browser" loop. It ALWAYS
+ * exports first (the quick round-trip: cart -> standalone HTML bundle -> local
+ * server -> URL you open), so it takes a cart path, not a pre-built dir. The
+ * export step hard-requires PICO-8 (absence is the structured `pico8-not-found`
+ * value + a nonzero exit, mirroring `run`/`export`); the static server itself is
+ * a zero-dep `node:http` file server over the temp export dir, so no extra
+ * dependency and no ~/Desktop pollution.
+ *
+ * It is distinct from `export`: `export` PRODUCES a bundle at a chosen dest (for
+ * the showcase); `serve` throws the bundle in a temp dir and serves it for a
+ * quick manual play. It runs until interrupted (the server keeps the process
+ * alive), which is why the injected {@link ServerFactory} seam lets a test drive
+ * the export + bind path without leaving a real socket open.
+ *
+ * @param adapterFactory injects the PICO-8 adapter (defaults to the shell one).
+ * @param serverFactory injects the HTTP server (defaults to the zero-dep static
+ *   server); a test passes a fake to assert the loop without a real socket.
+ * @param registerCleanup injects the exit/signal cleanup wiring (defaults to the
+ *   real `process` handlers); a test passes a fake to capture the cleanup fn.
+ */
+export function registerServe(cli, adapterFactory = defaultAdapterFactory, serverFactory = defaultServerFactory, registerCleanup = defaultCleanupRegistrar) {
+    cli.command('serve', {
+        description: 'Export a cart and serve it locally so you can play it in a browser. Requires PICO-8.',
+        args: z.object({
+            cart: z
+                .string()
+                .default('main.p8')
+                .describe('The .p8 cart to export and serve. Defaults to main.p8 in the current folder.'),
+        }),
+        options: z.object({
+            port: z
+                .number()
+                .int()
+                .min(0)
+                .max(65535)
+                .default(DEFAULT_PORT)
+                .describe('Port to serve on (0 = an OS-assigned free port).'),
+            backstopMs: z
+                .number()
+                .int()
+                .positive()
+                .default(DEFAULT_BACKSTOP_MS)
+                .describe('Safety backstop for the export step.'),
+        }),
+        env: z.object({
+            PICO8_PATH: z
+                .string()
+                .optional()
+                .describe('Explicit path to the PICO-8 binary (else `pico8` on PATH).'),
+            PATH: z.string().optional().describe('Used to locate `pico8`.'),
+        }),
+        output: z.object({
+            url: z.string().describe('The local URL to open in a browser.'),
+            port: z.number().describe('The port the server bound to.'),
+            serveDir: z
+                .string()
+                .describe('The temp dir the export bundle was served from.'),
+        }),
+        examples: [
+            { description: 'Export and serve main.p8' },
+            { description: 'Serve a specific cart', args: { cart: 'game.p8' } },
+            {
+                description: 'Serve on a chosen port',
+                args: { cart: 'game.p8' },
+                options: { port: 8080 },
+            },
+        ],
+        async run({ args, options, env, error, ok }) {
+            const cartPath = isAbsolute(args.cart)
+                ? args.cart
+                : resolve(process.cwd(), args.cart);
+            if (!existsSync(cartPath)) {
+                return error({
+                    code: 'cart-not-found',
+                    message: `no cart at ${cartPath}`,
+                    exitCode: 1,
+                });
+            }
+            // Always export first, into an isolated temp dir (never a user path or
+            // ~/Desktop). The bundle is the standalone pair the static server plays.
+            const serveDir = mkdtempSync(join(tmpdir(), 'picopilot-serve-'));
+            const adapter = adapterFactory(env);
+            const result = await adapter.export({
+                cartPath,
+                outDir: serveDir,
+                htmlName: EXPORT_HTML_NAME,
+                backstopMs: options.backstopMs,
+            });
+            if (!result.ok) {
+                // Nothing is being served: remove the temp dir now, not on exit.
+                removeDir(serveDir);
+                return error({
+                    code: result.reason,
+                    message: `PICO-8 is not installed. ${result.remedy} (needs: ${result.needs.join(', ')})`,
+                    exitCode: 1,
+                });
+            }
+            if (result.value.jsPath === undefined) {
+                removeDir(serveDir);
+                return error({
+                    code: 'export-failed',
+                    message: result.value.labelWarning
+                        ? 'PICO-8 produced no bundle (the cart has no __label__). Capture a label first, then re-serve.'
+                        : 'PICO-8 produced no export bundle. Check the cart runs without a boot error.',
+                    exitCode: 1,
+                });
+            }
+            const { server, port } = await serverFactory(serveDir, options.port);
+            const url = `http://127.0.0.1:${port}/`;
+            // The server keeps the process alive until interrupted; the temp export dir
+            // is reaped on SIGINT/SIGTERM/exit so a long-lived serve leaves no leak.
+            // `server` is referenced so its lifetime is the command's; a test's fake
+            // resolves without a real socket.
+            registerCleanup(() => removeDir(serveDir));
+            void server;
+            return ok({ url, port, serveDir });
+        },
+    });
+}
+//# sourceMappingURL=serve.js.map

package/dist/commands/serve.js.map

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

package/dist/commands/sfx.d.ts

@@ -0,0 +1,13 @@
+import { Cli } from 'incur';
+/**
+ * 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 declare function registerSfx(cli: Cli.Cli): void;
+//# sourceMappingURL=sfx.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sfx.d.ts","sourceRoot":"","sources":["../../src/commands/sfx.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,GAAG,EAAI,MAAM,OAAO,CAAC;AA6R7B;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,GAAG,IAAI,CAE9C"}