picopilot 0.0.0 → 0.1.0

package/dist/commands/export.js

@@ -0,0 +1,257 @@
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { z } from 'incur';
+import { Cart, CartParseError } from '../engine/cart/index.js';
+import { labelHexFromPng, LabelError } from '../engine/gfx/index.js';
+import { EXPORT_HTML_NAME, ShellPico8Adapter, } from '../engine/pico8/index.js';
+const defaultAdapterFactory = (env) => new ShellPico8Adapter({ env });
+/** The default backstop: kill an export that never completes/exits after this many ms. */
+const DEFAULT_BACKSTOP_MS = 30_000;
+/**
+ * Registers `picopilot export`, the THIN structured wrapper over PICO-8's HTML
+ * export (`pico8 <cart> -export <name>.html -x`, the headless `-x` path, no
+ * display needed). It is NOT a `pico8` reimplementation: PICO-8 owns the bundle
+ * (an Emscripten runtime `.js` with the cart baked in, plus a shell `.html`).
+ * The value picopilot adds is the glue an agent should not hand-roll: resolve
+ * the cart, pick/create the output dir, name the pair `index.html` + `index.js`
+ * so a dest folder is directly serveable/showcase-ready, and return ONE
+ * structured result (output dir + file paths + the labelless-cart warning). It
+ * hard-requires PICO-8; absence is a first-class `pico8-not-found` value + a
+ * nonzero exit (mirrors `run`), never a crash or a hang. Live export is the
+ * manual/opt-in tier; the absent path is the CI-testable one.
+ *
+ * Two shapes, one command:
+ *  - default (standalone): keep the `index.html` + `index.js` pair; the html
+ *    references its sibling by name, so the dir plays directly (and `serve`
+ *    uses this internally).
+ *  - `--payload-only`: keep only the `.js` runtime payload; drop the shell page.
+ *    For a website that provides its OWN player shell (a Svelte component that
+ *    ports PICO-8's small bootstrap and loads the exported `.js`). The split is
+ *    a post-export file op the command owns, never the PICO-8 binary's concern.
+ *
+ * @param adapterFactory injects the adapter (defaults to the shell adapter);
+ *   tests pass a stub to drive present/absent without the real binary.
+ */
+export function registerExport(cli, adapterFactory = defaultAdapterFactory) {
+    cli.command('export', {
+        description: "Export a cart to a playable HTML bundle (index.html + index.js) via the user's PICO-8. Requires PICO-8.",
+        args: z.object({
+            cart: z
+                .string()
+                .default('main.p8')
+                .describe('The .p8 cart to export. Defaults to main.p8 in the current folder.'),
+            dest: z
+                .string()
+                .optional()
+                .describe('Output folder (created if missing). Point it at a showcase dir (e.g. ./website/static/games/<slug>/). Defaults to an isolated temp dir.'),
+        }),
+        options: z.object({
+            label: z
+                .string()
+                .optional()
+                .describe('Path to a 128x128 PNG to bake in as the cart __label__ (the export splash), for a cart that has none. Ignored if the cart already has a label.'),
+            payloadOnly: z
+                .boolean()
+                .default(false)
+                .describe('Keep only the .js runtime payload (drop the shell .html), for a site that provides its own player component.'),
+            backstopMs: z
+                .number()
+                .int()
+                .positive()
+                .default(DEFAULT_BACKSTOP_MS)
+                .describe('Safety backstop: kill PICO-8 after this many ms if the export never completes.'),
+        }),
+        // 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({
+            outDir: z
+                .string()
+                .describe('Absolute path of the folder the bundle was written to.'),
+            html: z
+                .string()
+                .optional()
+                .describe('Absolute path of the shell index.html (omitted with --payload-only).'),
+            js: z.string().describe('Absolute path of the runtime payload index.js.'),
+            files: z
+                .array(z.string())
+                .describe('Absolute paths of every file the bundle contains.'),
+            labelWarning: z
+                .boolean()
+                .describe('True when the cart has no __label__: it exports with a blank/ugly splash.'),
+        }),
+        examples: [
+            { description: 'Export main.p8 to a temp dir' },
+            {
+                description: 'Export a cart into a showcase folder',
+                args: { cart: 'game.p8', dest: './website/static/games/my-game' },
+            },
+            {
+                description: 'Bake a PNG as the label splash for a labelless cart',
+                args: { cart: 'game.p8', dest: './website/static/games/my-game' },
+                options: { label: './label.png' },
+            },
+            {
+                description: 'Export only the runtime payload for a site player component',
+                args: { cart: 'game.p8', dest: './website/static/games/my-game' },
+                options: { payloadOnly: true },
+            },
+        ],
+        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,
+                });
+            }
+            // --label <png>: bake a 128x128 PNG in as the cart's __label__ so a
+            // labelless cart gets a splash without an interactive F7 capture. We do
+            // NOT mutate the user's cart: we write a labeled copy NEXT TO it (same dir,
+            // so `#include main.lua` still resolves) and export that, then clean it up.
+            // A cart that ALREADY has a label wins (the flag is a fallback, not an
+            // override), matching the export precedence PICO-8 itself uses.
+            let exportCartPath = cartPath;
+            let labeledCopy;
+            if (options.label !== undefined) {
+                const labelPath = isAbsolute(options.label)
+                    ? options.label
+                    : resolve(process.cwd(), options.label);
+                if (!existsSync(labelPath)) {
+                    return error({
+                        code: 'label-not-found',
+                        message: `no label image at ${labelPath}`,
+                        exitCode: 1,
+                    });
+                }
+                try {
+                    const cart = Cart.parse(readFileSync(cartPath, 'utf8'));
+                    const existingLabel = cart.getSection('label');
+                    if (existingLabel === undefined || existingLabel.trim() === '') {
+                        const hex = labelHexFromPng(readFileSync(labelPath));
+                        cart.setSection('label', hex);
+                        labeledCopy = join(dirname(cartPath), `.picopilot-export-${process.pid}-${Date.now()}.p8`);
+                        writeFileSync(labeledCopy, cart.serialize());
+                        exportCartPath = labeledCopy;
+                    }
+                    // else: cart already has a label; keep it, ignore --label.
+                }
+                catch (e) {
+                    if (e instanceof LabelError) {
+                        return error({
+                            code: `label-${e.code}`,
+                            message: e.message,
+                            exitCode: 1,
+                        });
+                    }
+                    if (e instanceof CartParseError) {
+                        return error({
+                            code: `cart-${e.code}`,
+                            message: `could not parse the cart to inject a label: ${e.message}`,
+                            exitCode: 1,
+                        });
+                    }
+                    throw e;
+                }
+            }
+            // Output dir: a user-given dest (point it at the showcase), else an
+            // isolated temp dir. Create it so PICO-8 has somewhere to write.
+            const outDir = args.dest !== undefined
+                ? isAbsolute(args.dest)
+                    ? args.dest
+                    : resolve(process.cwd(), args.dest)
+                : mkdtempSync(join(tmpdir(), 'picopilot-export-'));
+            if (!existsSync(outDir))
+                mkdirSync(outDir, { recursive: true });
+            const adapter = adapterFactory(env);
+            const result = await adapter.export({
+                cartPath: exportCartPath,
+                outDir,
+                htmlName: EXPORT_HTML_NAME,
+                backstopMs: options.backstopMs,
+            });
+            // Remove the temporary labeled copy now that PICO-8 has read it (on every
+            // path below); best-effort, a leftover dotfile is not fatal.
+            if (labeledCopy !== undefined) {
+                try {
+                    rmSync(labeledCopy);
+                }
+                catch {
+                    // ignore
+                }
+            }
+            if (!result.ok) {
+                // The two-tier structured failure: 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,
+                });
+            }
+            let { htmlPath, jsPath, files, labelWarning } = result.value;
+            // PICO-8 must have produced the runtime payload; if not, the export failed
+            // (most often a labelless-cart bail that wrote nothing).
+            if (jsPath === undefined) {
+                return error({
+                    code: 'export-failed',
+                    message: labelWarning
+                        ? 'PICO-8 produced no bundle (the cart has no __label__ to embed). Give it one with --label <128x128.png>, or capture a label in PICO-8 (F7), then re-export.'
+                        : 'PICO-8 produced no export bundle. Check the cart runs without a boot error.',
+                    exitCode: 1,
+                });
+            }
+            // --payload-only: drop the shell .html; keep just the runtime payload the
+            // site's own player component loads. A post-export file op we own, not the
+            // binary's concern.
+            if (options.payloadOnly && htmlPath !== undefined) {
+                try {
+                    rmSync(htmlPath);
+                }
+                catch {
+                    // A stubborn html is not fatal: the payload is what matters.
+                }
+                htmlPath = undefined;
+                files = listFiles(outDir);
+            }
+            const cta = labelWarning && !options.payloadOnly
+                ? {
+                    description: 'The cart has no __label__, so the export splash is blank. Add one for a nicer bundle:',
+                    commands: [
+                        {
+                            command: 'export --label <128x128.png>',
+                            description: 'Bake a PNG in as the label splash, or capture one in PICO-8 (F7) before exporting.',
+                        },
+                    ],
+                }
+                : undefined;
+            return ok({
+                outDir,
+                html: htmlPath,
+                js: jsPath,
+                files: [...files],
+                labelWarning,
+            }, cta === undefined ? undefined : { cta });
+        },
+    });
+}
+/** Absolute, sorted file paths currently in `dir` (post file-op re-scan). */
+function listFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .sort()
+        .map((f) => join(dir, f));
+}
+//# sourceMappingURL=export.js.map

package/dist/commands/export.js.map

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

package/dist/commands/gfx.d.ts

@@ -0,0 +1,28 @@
+import { Cli } from 'incur';
+import { type ShrinkoAdapter } from '../engine/shrinko/index.js';
+/** Injects the shrinko adapter `gfx import`/`gfx export` use (the spritesheet round-trip). */
+export type ShrinkoAdapterFactory = (env: NodeJS.ProcessEnv) => ShrinkoAdapter;
+/**
+ * The exit code for the `map-overlap` refusal. Chosen as 1 (a plain failure),
+ * matching every other picopilot structured refusal (`cart-not-found`,
+ * `already-initialised`, `verify-failed`): the refusal is a "you asked for
+ * something I won't do" failure, not a distinct capability-gap the way `verify`'s
+ * `gate-incapable` (exit 2) is. What makes it safe is not a special exit code
+ * but that it is NON-ZERO (an agent must not read it as done) AND the sprite's
+ * bytes are left untouched.
+ */
+export declare const MAP_OVERLAP_EXIT = 1;
+/**
+ * Registers the `gfx` command group (`gfx show` / `gfx set`) on the root CLI.
+ *
+ * `gfx` is a shrinko-FREE command group (ADR-0002): it reads/writes `__gfx__`
+ * entirely through the cart model + the TS char-grid codec, so it works with
+ * shrinko absent and never spawns a child process. `gfx set` carries the
+ * gfx/map overlap smart-refuse (ADR-0004): a write to a shared-bank sprite
+ * (128-255) whose current pixels hold data is refused unless authorised, so
+ * picopilot never SILENTLY destroys shared-region data. `gfx render` is likewise
+ * shrinko-free: a pure-TS hex->PNG encoder using PICO-8's fixed 16-colour palette
+ * (the eyes-loop stays dependency-light, ADR/US #7).
+ */
+export declare function registerGfx(cli: Cli.Cli, shrinkoFactory?: ShrinkoAdapterFactory): void;
+//# sourceMappingURL=gfx.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gfx.d.ts","sourceRoot":"","sources":["../../src/commands/gfx.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,GAAG,EAAI,MAAM,OAAO,CAAC;AAoB7B,OAAO,EACN,KAAK,cAAc,EAEnB,MAAM,4BAA4B,CAAC;AAEpC,8FAA8F;AAC9F,MAAM,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,cAAc,CAAC;AAK/E;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAykBlC;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAC1B,GAAG,EAAE,GAAG,CAAC,GAAG,EACZ,cAAc,GAAE,qBAA6C,GAC3D,IAAI,CAEN"}