picopilot 0.0.0 → 0.1.0

package/dist/engine/scaffold/scaffold.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The one line of code in the scaffolded cart. PICO-8's `#include` pulls the
+ * external Lua file in at load time; keeping it the ONLY thing in `__lua__` is
+ * the `#include` discipline the whole toolchain relies on.
+ */
+export declare const LUA_INCLUDE_LINE = "#include main.lua";
+/**
+ * Builds the scaffolded `main.p8` via the cart model. `__lua__` holds only the
+ * `#include`; the cart carries no binary sections yet (a fresh cart has no gfx /
+ * map / sfx / music); those are added later by the gfx/audio commands.
+ */
+export declare function mainP8(): string;
+/**
+ * The starter `main.lua`: a minimal but RUNNABLE cart (the `_init/_update/_draw`
+ * loop the API reference calls out as load-bearing) so a fresh folder boots
+ * instead of being inert. Intentionally tiny: it is a starting point the agent
+ * replaces, not a demo.
+ */
+export declare function mainLua(): string;
+/** The scaffolded `picopilot.json` (incur config: precedence argv > config > defaults). */
+export declare function picopilotJson(): string;
+/**
+ * The curated PICO-8 reference written to `AGENTS.md`.
+ *
+ * This is CONTEXT an agent loads every turn, so it is CURATED from
+ * `work/notes/findings/pico8-api-reference.md`, not a dump of the manual: the
+ * hard specs, the `_init/_update/_draw` loop, the fixed palette, the memory map
+ * + the gfx/map overlap WARNING, the grouped most-used API, and the token
+ * discipline, the things models get wrong without a reference.
+ */
+export declare function agentsMd(): string;
+/**
+ * One scaffolded file: its cart-relative name and its exact bytes. `init`
+ * iterates these, so adding a file is a one-line change here and the tests
+ * assert against this list (the "exactly these files" contract).
+ */
+export interface ScaffoldFile {
+    readonly name: string;
+    readonly content: string;
+}
+/**
+ * The complete set of files `picopilot init` writes into a fresh cart folder,
+ * in a stable order: the cart, its editable Lua, the agent-context reference,
+ * and the config. Exactly FOUR files (the acceptance contract). `AGENTS.md` is
+ * the cross-agent context filename; Claude Code, Codex, and others read it, so
+ * one portable file beats duplicating identical content into `CLAUDE.md`.
+ */
+export declare function scaffoldFiles(): ScaffoldFile[];
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/engine/scaffold/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/engine/scaffold/scaffold.ts"],"names":[],"mappings":"AAiBA;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,sBAAsB,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,MAAM,IAAI,MAAM,CAM/B;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAehC;AAED,2FAA2F;AAC3F,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAuIjC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,YAAY,EAAE,CAO9C"}

package/dist/engine/scaffold/scaffold.js

@@ -0,0 +1,217 @@
+import { Cart } from '../cart/index.js';
+import { defaultConfigFile } from '../config/index.js';
+/**
+ * The static content `picopilot init` writes into a fresh cart folder.
+ *
+ * The single scaffolding model (US #1): the `.p8`'s `__lua__` section is exactly
+ * `#include main.lua`, and the plain-Lua `main.lua` is the file the agent edits,
+ * so the agent never hand-writes the cart's binary hex sections. `main.p8` is
+ * built THROUGH the cart model (not a hand-written string) so init and every
+ * later cart-touching command share one serializer and the output is guaranteed
+ * to round-trip.
+ */
+/** The PICO-8 cart format version init emits (the current stable text-format version). */
+const CART_VERSION = 42;
+/**
+ * The one line of code in the scaffolded cart. PICO-8's `#include` pulls the
+ * external Lua file in at load time; keeping it the ONLY thing in `__lua__` is
+ * the `#include` discipline the whole toolchain relies on.
+ */
+export const LUA_INCLUDE_LINE = '#include main.lua';
+/**
+ * Builds the scaffolded `main.p8` via the cart model. `__lua__` holds only the
+ * `#include`; the cart carries no binary sections yet (a fresh cart has no gfx /
+ * map / sfx / music); those are added later by the gfx/audio commands.
+ */
+export function mainP8() {
+    const cart = Cart.parse(`pico-8 cartridge // http://www.pico-8.com\nversion ${CART_VERSION}\n__lua__\n`);
+    cart.setSection('lua', `${LUA_INCLUDE_LINE}\n`);
+    return cart.serialize();
+}
+/**
+ * The starter `main.lua`: a minimal but RUNNABLE cart (the `_init/_update/_draw`
+ * loop the API reference calls out as load-bearing) so a fresh folder boots
+ * instead of being inert. Intentionally tiny: it is a starting point the agent
+ * replaces, not a demo.
+ */
+export function mainLua() {
+    return `-- main.lua, the plain-Lua source picopilot's main.p8 #includes.
+-- Edit THIS file; never hand-write main.p8's binary sections.
+
+function _init()
+end
+
+function _update()
+end
+
+function _draw()
+  cls()
+  print("hello picopilot", 36, 60, 7)
+end
+`;
+}
+/** The scaffolded `picopilot.json` (incur config: precedence argv > config > defaults). */
+export function picopilotJson() {
+    return defaultConfigFile();
+}
+/**
+ * The curated PICO-8 reference written to `AGENTS.md`.
+ *
+ * This is CONTEXT an agent loads every turn, so it is CURATED from
+ * `work/notes/findings/pico8-api-reference.md`, not a dump of the manual: the
+ * hard specs, the `_init/_update/_draw` loop, the fixed palette, the memory map
+ * + the gfx/map overlap WARNING, the grouped most-used API, and the token
+ * discipline, the things models get wrong without a reference.
+ */
+export function agentsMd() {
+    return `# PICO-8 cart context (generated by \`picopilot init\`)
+
+You are editing a PICO-8 cart with picopilot. This file is your always-loaded
+reference: the constraints, the loop, the palette, the memory map (+ the overlap
+warning), the most-used API, and how to stay under the token budget. It is
+curated from PICO-8's manual for the things models get wrong without a reminder.
+
+## The \`#include\` discipline (how this cart is laid out)
+
+- \`main.p8\` is the cart. Its \`__lua__\` section is a single line: \`#include main.lua\`.
+- \`main.lua\` is the plain Lua you EDIT. Never hand-write \`main.p8\`'s binary
+  sections (\`__gfx__\`, \`__map__\`, \`__sfx__\`, \`__music__\`), use picopilot's
+  \`gfx\` / audio commands, which edit them safely and round-trippably.
+
+## Hard specs (the constraints that shape everything)
+
+- Display: **128x128**, a **fixed 16-colour palette** (indices 0..15).
+- Code: **Lua**, max **8192 tokens** (the #1 thing to watch). Run \`picopilot tokens\`.
+- Sprites: 256 8x8 sprites in a base bank (0..127) plus a shared bank (128..255).
+- Map: 128x32 tiles + a shared half that ALIASES sprites 128..255 (see below).
+- Sound: 4 channels, 64 SFX slots; music is patterns of up to 4 SFX references.
+- Numbers: 16.16 fixed point, range \`-32768.0 .. 32767.99\`.
+
+## The execution loop (every cart)
+
+- \`_init()\`: runs once at startup.
+- \`_update()\`: runs every update tick at 30fps (\`_update60()\` for 60fps).
+- \`_draw()\`: runs once per visible frame.
+
+A cart with none of these is inert. Keep them defined.
+
+## The fixed 16-colour palette (index → RGB)
+
+In a char grid, \`.\` = transparent and \`0-F\` = these indices.
+
+| idx | hex | name        | R   | G   | B   |
+|-----|-----|-------------|-----|-----|-----|
+| 0   | 0   | black       | 0   | 0   | 0   |
+| 1   | 1   | dark-blue   | 29  | 43  | 83  |
+| 2   | 2   | dark-purple | 126 | 37  | 83  |
+| 3   | 3   | dark-green  | 0   | 135 | 81  |
+| 4   | 4   | brown       | 171 | 82  | 54  |
+| 5   | 5   | dark-grey   | 95  | 87  | 79  |
+| 6   | 6   | light-grey  | 194 | 195 | 199 |
+| 7   | 7   | white       | 255 | 241 | 232 |
+| 8   | 8   | red         | 255 | 0   | 77  |
+| 9   | 9   | orange      | 255 | 163 | 0   |
+| 10  | a   | yellow      | 255 | 236 | 39  |
+| 11  | b   | green       | 0   | 228 | 54  |
+| 12  | c   | blue        | 41  | 173 | 255 |
+| 13  | d   | lavender    | 131 | 118 | 156 |
+| 14  | e   | pink        | 255 | 119 | 168 |
+| 15  | f   | peach       | 255 | 204 | 170 |
+
+## Memory map + the gfx/map overlap warning
+
+\`\`\`
+0x0000  gfx (spritesheet, sprites 0..127)
+0x1000  shared gfx / map2   <-- sprites 128..255 ALIAS the bottom half of the map
+0x2000  map
+0x3000  gfx flags
+0x3100  music
+0x3200  sfx
+0x4300  user data
+0x5e00  persistent cart data (256 bytes)
+0x5f00  draw state
+0x5f40  hardware state
+0x5f80  gpio pins
+0x6000  screen (8k)
+\`\`\`
+
+**Overlap warning:** sprites 128..255 (\`0x1000\`-\`0x1fff\`) occupy the SAME memory
+as \`__map__\` rows 32..63. Writing a sprite in that range clobbers the map tiles
+there. \`picopilot gfx set\` smart-refuses such a write when real map tiles are at
+risk and nothing authorised the loss (\`--allow-map-overlap\` or \`allowMapOverlap\`
+in \`picopilot.json\`), so you never silently destroy map data you cannot see.
+
+## Most-used API (grouped)
+
+- **Graphics:** \`cls([col])\`, \`spr(n,x,y,[w,h],[fx],[fy])\`, \`sspr(...)\`,
+  \`map(cx,cy,sx,sy,cw,ch,[layer])\`, \`pset/pget\`, \`sget/sset\`,
+  \`print(str,[x,y,[col]])\`, \`rect/rectfill\`, \`circ/circfill\`, \`oval/ovalfill\`,
+  \`line\`, \`pal(c0,c1,[p])\`, \`palt(col,t)\`, \`camera([x,y])\`, \`clip([x,y,w,h])\`,
+  \`color(col)\`, \`fillp(mask)\`, \`tline(...)\`, \`flip()\`.
+- **Map / flags:** \`mget(x,y)\`, \`mset(x,y,v)\`, \`fget(n,[f])\`, \`fset(n,[f],v)\`.
+- **Input:** \`btn([i,[p]])\`, \`btnp([i,[p]])\` (buttons 0..5 = left,right,up,down,O/Z,X).
+- **Audio:** \`sfx(n,[channel,[offset]])\`, \`music([n,[fade,[mask]]])\`.
+- **Math:** \`abs\`, \`flr\` (\`-flr(-x)\` = ceil), \`min\`, \`max\`, \`mid\`, \`rnd(x)\`,
+  \`srand(x)\`, \`sgn\`, \`sqrt\`, \`sin(x)\`/\`cos(x)\` (range 0..1, sin inverted),
+  \`atan2(x,y)\`.
+- **Tables:** \`add\`, \`del\`, \`deli\`, \`count\`, \`all(t)\`, \`foreach(t,f)\`, \`pairs\`, \`ipairs\`.
+- **Memory:** \`peek\`, \`poke\`, \`memcpy\`, \`memset\`, \`cstore\`, \`reload\`.
+- **Cart data:** \`cartdata(id)\`, \`dget(i)\`, \`dset(i,v)\`.
+- **Debug:** \`printh(str)\` (to host stdout, \`picopilot run\` captures it), \`stat(n)\`.
+
+## Gotchas that silently break carts (these differ from normal Lua/math)
+
+These compile and run but behave WRONG. They are the traps models hit most:
+
+- \`sin(t)\`/\`cos(t)\` take TURNS (0..1), NOT radians, and \`sin\` is INVERTED for
+  screen space (+y is down). A full circle is \`t: 0->1\`. Do not multiply by
+  \`2*pi\`; do not re-negate \`sin\`.
+- \`/\` does NOT truncate (\`5/2\`=\`2.5\`). Integer divide is \`\\\` (\`5\\2\`=\`2\`), which
+  floors toward negative infinity (\`-5\\2\`=\`-3\`).
+- \`rnd(x)\` returns a FLOAT in [0,x). Use \`flr(rnd(x))\` for an integer;
+  \`rnd(table)\` returns a random element.
+- Tables are 1-BASED. \`del(t,val)\` removes by VALUE, \`deli(t,i)\` by INDEX.
+  Deleting the current item inside \`foreach\` is safe; inside an ascending
+  \`for i=1,#t\` it ERRORS once the list shrinks (iterate descending, or foreach).
+- Draw state PERSISTS across frames: \`camera\`, \`pal\`, \`palt\`, \`clip\`, \`color\`,
+  \`fillp\` stay set until reset (no-arg form: \`camera()\`, \`pal()\`). Reset before
+  the HUD or offsets/palette swaps leak.
+- Numbers are 16.16 fixed point; overflow WRAPS at ~32767. Drawing coords are
+  floored to integer pixels (keep true position as a float, let draw floor it).
+- Variables are GLOBAL unless \`local\`. The \`x = cond and a or b\` ternary returns
+  \`b\` when \`a\` is falsy (\`false\`/\`nil\`); use an explicit \`if\` then.
+
+(The \`picopilot-code\` skill expands these, and carries per-genre code references:
+platformer / puzzle-grid / twin-stick-arcade / top-down-adventure and more.)
+
+## Token discipline (stay under 8192)
+
+Models blow the budget by writing verbose Lua. Prefer PICO-8 shorthands:
+
+- \`?\` for \`print\`.
+- inline if: \`if(c) x=1\`.
+- compound assignment: \`+=\`, \`-=\`, \`*=\`, \`/=\`.
+- \`\\\` for integer divide.
+- reuse locals; avoid needless globals.
+
+Run \`picopilot tokens\` each iteration to see the count and where it goes; when
+over budget, \`picopilot minify\` (safe-only) reclaims tokens without changing
+behaviour.
+`;
+}
+/**
+ * The complete set of files `picopilot init` writes into a fresh cart folder,
+ * in a stable order: the cart, its editable Lua, the agent-context reference,
+ * and the config. Exactly FOUR files (the acceptance contract). `AGENTS.md` is
+ * the cross-agent context filename; Claude Code, Codex, and others read it, so
+ * one portable file beats duplicating identical content into `CLAUDE.md`.
+ */
+export function scaffoldFiles() {
+    return [
+        { name: 'main.p8', content: mainP8() },
+        { name: 'main.lua', content: mainLua() },
+        { name: 'AGENTS.md', content: agentsMd() },
+        { name: 'picopilot.json', content: picopilotJson() },
+    ];
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/engine/scaffold/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../src/engine/scaffold/scaffold.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,IAAI,EAAC,MAAM,kBAAkB,CAAC;AACtC,OAAO,EAAC,iBAAiB,EAAC,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;GASG;AAEH,0FAA0F;AAC1F,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAEpD;;;;GAIG;AACH,MAAM,UAAU,MAAM;IACrB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CACtB,sDAAsD,YAAY,aAAa,CAC/E,CAAC;IACF,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,GAAG,gBAAgB,IAAI,CAAC,CAAC;IAChD,OAAO,IAAI,CAAC,SAAS,EAAE,CAAC;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO;IACtB,OAAO;;;;;;;;;;;;;CAaP,CAAC;AACF,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,aAAa;IAC5B,OAAO,iBAAiB,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ;IACvB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqIP,CAAC;AACF,CAAC;AAYD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa;IAC5B,OAAO;QACN,EAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,EAAC;QACpC,EAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,EAAE,EAAC;QACtC,EAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAC;QACxC,EAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,EAAE,EAAC;KAClD,CAAC;AACH,CAAC"}

package/dist/engine/shrinko/adapter.d.ts

@@ -0,0 +1,167 @@
+/**
+ * The shrinko adapter SEAM: a typed interface every shrinko-backed command
+ * (`tokens`, and later `lint`, `minify`, `gfx import/export`, `verify`) talks
+ * to, plus the discriminated result shape they all return.
+ *
+ * The seam exists so the command layer never knows HOW shrinko is reached. The
+ * v1 implementation shells out to a user-installed Python `shrinko8` (see
+ * `shell.ts` and ADR-0001); a future native-TS implementation can implement the
+ * SAME {@link ShrinkoAdapter} interface and drop in without touching a single
+ * command. The command-facing contract is entirely in this file.
+ *
+ * The two-tier capability contract (ADR-0002) lives in the RESULT type: every
+ * adapter method returns a {@link ShrinkoResult}, a discriminated union of a
+ * success value OR the structured {@link ShrinkoNotFound} failure. Absent
+ * shrinko is therefore NOT an exception a command must try/catch, it is a
+ * first-class `{ok:false, reason:'shrinko-not-found', ...}` value a command maps
+ * onto incur's error envelope with a nonzero exit. Never a crash, never a hollow
+ * success.
+ */
+/** The PyPI package name in the remedy: `uv pip install shrinko` (NOT `shrinko8`). */
+export declare const SHRINKO_REMEDY: "uv pip install shrinko";
+/** What shrinko needs to run: Python 3.8+ (the module is `shrinko8`). */
+export declare const SHRINKO_NEEDS: readonly ["python>=3.8"];
+/**
+ * The structured "shrinko is not installed" failure (ADR-0002). Its shape is
+ * fixed by the prd's two-tier contract (US #17): `ok:false`, a machine-readable
+ * `reason`, the EXACT `remedy` string, and the `needs` list. A command turns
+ * this into an incur `error({ code: reason, ... })` with a nonzero exit.
+ */
+export interface ShrinkoNotFound {
+    readonly ok: false;
+    readonly reason: 'shrinko-not-found';
+    /** The EXACT remedy: `uv pip install shrinko` (package is `shrinko`, module `shrinko8`). */
+    readonly remedy: typeof SHRINKO_REMEDY;
+    /** Prerequisites the remedy assumes are present. */
+    readonly needs: readonly string[];
+}
+/** A successful adapter call carrying the parsed value. */
+export interface ShrinkoOk<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+/**
+ * The result every {@link ShrinkoAdapter} method returns: either a parsed value
+ * or the structured {@link ShrinkoNotFound}. Absence is a value, not a throw, so
+ * the two-tier contract is total and type-checked at every call site.
+ */
+export type ShrinkoResult<T> = ShrinkoOk<T> | ShrinkoNotFound;
+/**
+ * The parsed `--count` report (US #3). `tokens`/`chars`/`compressed` are the
+ * raw counts shrinko prints; `pct` fields are shrinko's own reported
+ * percentages (its `--count` prints `tokens: 8053 98%`, i.e. against PICO-8's
+ * limits), preserved verbatim so a command can show them without recomputing.
+ * `compressed`/`compressedPct` are optional because shrinko omits the
+ * compressed line for input formats where it does not apply.
+ */
+export interface CountReport {
+    readonly tokens: number;
+    readonly tokensPct: number;
+    readonly chars: number;
+    readonly charsPct: number;
+    readonly compressed: number | undefined;
+    readonly compressedPct: number | undefined;
+}
+/**
+ * The shrinko capability seam. One method per shrinko-backed operation; only
+ * `count` exists in this task, the rest (lint, minify, convert) land with their
+ * commands and extend THIS interface rather than forking a new one.
+ *
+ * Every method is async (the shell-out is async) and returns a
+ * {@link ShrinkoResult}, so absence is handled uniformly at each seam.
+ */
+export interface ShrinkoAdapter {
+    /**
+     * Runs shrinko's `--count` on the cart at `cartPath` and parses the
+     * `tokens/chars/compressed` report. Returns {@link ShrinkoNotFound} when
+     * shrinko is not installed.
+     */
+    count(cartPath: string): Promise<ShrinkoResult<CountReport>>;
+    /**
+     * Runs shrinko's `--lint` on the cart at `cartPath` and parses the warnings
+     * (undefined globals, unused/duplicate locals, etc.) into structured
+     * {@link LintFinding}s. Lint warnings are DATA, not a failure: the report is
+     * returned with `findings` (possibly empty), not a throw. Returns
+     * {@link ShrinkoNotFound} when shrinko is not installed.
+     */
+    lint(cartPath: string): Promise<ShrinkoResult<LintReport>>;
+    /**
+     * Runs shrinko's SAFE minification on `cartPath` and writes the result to
+     * `outPath` (a SEPARATE artifact; the source is never touched, see ADR-0007).
+     * Returns the before/after token counts. Returns {@link ShrinkoNotFound} when
+     * shrinko is not installed.
+     */
+    minify(cartPath: string, outPath: string): Promise<ShrinkoResult<MinifyReport>>;
+    /**
+     * Exports the cart's spritesheet as a 128x128 PNG to `pngPath` (a raw
+     * round-trip image for external tools, distinct from `gfx render`'s upscaled
+     * JUDGE image). Returns {@link ShrinkoNotFound} when shrinko is not installed.
+     */
+    exportSpritesheet(cartPath: string, pngPath: string): Promise<ShrinkoResult<void>>;
+    /**
+     * Imports a 128x128 spritesheet PNG into `srcCartPath`'s `__gfx__`, MERGING
+     * (only the gfx section is replaced; code/map/sfx/music are preserved) and
+     * writing the result to `outCartPath`. Returns {@link ShrinkoNotFound} when
+     * shrinko is not installed.
+     */
+    importSpritesheet(srcCartPath: string, pngPath: string, outCartPath: string): Promise<ShrinkoResult<void>>;
+}
+/** One shrinko lint warning, parsed from a `file:line:col: message` line. */
+export interface LintFinding {
+    readonly line: number;
+    readonly col: number;
+    readonly message: string;
+}
+/** The parsed `--lint` result: every warning shrinko reported (empty when clean). */
+export interface LintReport {
+    readonly findings: readonly LintFinding[];
+}
+/** The parsed `minify` result: token counts before and after (ADR-0007's delta report). */
+export interface MinifyReport {
+    /** Tokens in the source cart. */
+    readonly beforeTokens: number;
+    /** Tokens in the minified artifact. */
+    readonly afterTokens: number;
+    /** Absolute path of the written minified cart. */
+    readonly outPath: string;
+}
+/** The frozen {@link ShrinkoNotFound} value, so every call site returns the same shape. */
+export declare function shrinkoNotFound(): ShrinkoNotFound;
+/**
+ * Parses shrinko's `--count` output into a {@link CountReport}.
+ *
+ * shrinko prints lines like:
+ *
+ * ```
+ * tokens: 8053 98%
+ * chars: 30320 46%
+ * compressed: 12176 77%
+ * ```
+ *
+ * (the compressed line is absent for some input formats). Parsing is
+ * line-oriented and tolerant of surrounding output/whitespace: it scans for the
+ * `tokens:`/`chars:`/`compressed:` labels anywhere in the combined stdout+stderr
+ * and pulls the count and percentage off each. Throws if the required
+ * `tokens:`/`chars:` lines are missing, so a shrinko that ran but produced
+ * unparseable output surfaces as a real error rather than a silent zero.
+ */
+export declare function parseCount(output: string): CountReport;
+/**
+ * Parses shrinko's `--lint` output into {@link LintFinding}s. shrinko prints a
+ * `Lint warnings:` header then one `file:line:col: message` per warning; a clean
+ * cart prints nothing. Parsing scans the combined stdout+stderr for the
+ * `:line:col: message` shape (tolerant of the filename prefix, which we drop),
+ * so an empty result is a CLEAN cart, not an error. Unlike parseCount this never
+ * throws: no recognisable lines simply means zero findings.
+ */
+export declare function parseLint(output: string): LintReport;
+/**
+ * Thrown when shrinko RAN but its output could not be parsed (a shrinko
+ * version/format drift), distinct from shrinko being ABSENT (which is the
+ * structured {@link ShrinkoNotFound} value, not a throw). Commands surface this
+ * as a `shrinko-failed` error, separate from `shrinko-not-found`.
+ */
+export declare class ShrinkoParseError extends Error {
+    readonly name = "ShrinkoParseError";
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/engine/shrinko/adapter.d.ts.map

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

package/dist/engine/shrinko/adapter.js

@@ -0,0 +1,107 @@
+/**
+ * The shrinko adapter SEAM: a typed interface every shrinko-backed command
+ * (`tokens`, and later `lint`, `minify`, `gfx import/export`, `verify`) talks
+ * to, plus the discriminated result shape they all return.
+ *
+ * The seam exists so the command layer never knows HOW shrinko is reached. The
+ * v1 implementation shells out to a user-installed Python `shrinko8` (see
+ * `shell.ts` and ADR-0001); a future native-TS implementation can implement the
+ * SAME {@link ShrinkoAdapter} interface and drop in without touching a single
+ * command. The command-facing contract is entirely in this file.
+ *
+ * The two-tier capability contract (ADR-0002) lives in the RESULT type: every
+ * adapter method returns a {@link ShrinkoResult}, a discriminated union of a
+ * success value OR the structured {@link ShrinkoNotFound} failure. Absent
+ * shrinko is therefore NOT an exception a command must try/catch, it is a
+ * first-class `{ok:false, reason:'shrinko-not-found', ...}` value a command maps
+ * onto incur's error envelope with a nonzero exit. Never a crash, never a hollow
+ * success.
+ */
+/** The PyPI package name in the remedy: `uv pip install shrinko` (NOT `shrinko8`). */
+export const SHRINKO_REMEDY = 'uv pip install shrinko';
+/** What shrinko needs to run: Python 3.8+ (the module is `shrinko8`). */
+export const SHRINKO_NEEDS = ['python>=3.8'];
+/** The frozen {@link ShrinkoNotFound} value, so every call site returns the same shape. */
+export function shrinkoNotFound() {
+    return {
+        ok: false,
+        reason: 'shrinko-not-found',
+        remedy: SHRINKO_REMEDY,
+        needs: [...SHRINKO_NEEDS],
+    };
+}
+/**
+ * Parses shrinko's `--count` output into a {@link CountReport}.
+ *
+ * shrinko prints lines like:
+ *
+ * ```
+ * tokens: 8053 98%
+ * chars: 30320 46%
+ * compressed: 12176 77%
+ * ```
+ *
+ * (the compressed line is absent for some input formats). Parsing is
+ * line-oriented and tolerant of surrounding output/whitespace: it scans for the
+ * `tokens:`/`chars:`/`compressed:` labels anywhere in the combined stdout+stderr
+ * and pulls the count and percentage off each. Throws if the required
+ * `tokens:`/`chars:` lines are missing, so a shrinko that ran but produced
+ * unparseable output surfaces as a real error rather than a silent zero.
+ */
+export function parseCount(output) {
+    const line = (label) => {
+        // `label: <count> <pct>%` (count and percent may be separated by any run
+        // of spaces; the `%` is optional-tolerant but shrinko always prints it).
+        const re = new RegExp(`^\\s*${label}:\\s*(\\d+)\\s+(\\d+)\\s*%`, 'm');
+        const m = re.exec(output);
+        if (m === null)
+            return undefined;
+        return { n: Number(m[1]), pct: Number(m[2]) };
+    };
+    const tokens = line('tokens');
+    const chars = line('chars');
+    if (tokens === undefined || chars === undefined) {
+        throw new ShrinkoParseError(`could not parse shrinko --count output (missing tokens/chars lines):\n${output}`);
+    }
+    const compressed = line('compressed');
+    return {
+        tokens: tokens.n,
+        tokensPct: tokens.pct,
+        chars: chars.n,
+        charsPct: chars.pct,
+        compressed: compressed?.n,
+        compressedPct: compressed?.pct,
+    };
+}
+/**
+ * Parses shrinko's `--lint` output into {@link LintFinding}s. shrinko prints a
+ * `Lint warnings:` header then one `file:line:col: message` per warning; a clean
+ * cart prints nothing. Parsing scans the combined stdout+stderr for the
+ * `:line:col: message` shape (tolerant of the filename prefix, which we drop),
+ * so an empty result is a CLEAN cart, not an error. Unlike parseCount this never
+ * throws: no recognisable lines simply means zero findings.
+ */
+export function parseLint(output) {
+    const findings = [];
+    // Match `<anything>:<line>:<col>: <message>` (the filename may itself contain
+    // colons/paths, so anchor on the two trailing numeric groups before the msg).
+    const re = /:(\d+):(\d+):\s*(.+?)\s*$/gm;
+    for (const m of output.matchAll(re)) {
+        findings.push({
+            line: Number(m[1]),
+            col: Number(m[2]),
+            message: m[3] ?? '',
+        });
+    }
+    return { findings };
+}
+/**
+ * Thrown when shrinko RAN but its output could not be parsed (a shrinko
+ * version/format drift), distinct from shrinko being ABSENT (which is the
+ * structured {@link ShrinkoNotFound} value, not a throw). Commands surface this
+ * as a `shrinko-failed` error, separate from `shrinko-not-found`.
+ */
+export class ShrinkoParseError extends Error {
+    name = 'ShrinkoParseError';
+}
+//# sourceMappingURL=adapter.js.map

package/dist/engine/shrinko/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/engine/shrinko/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,sFAAsF;AACtF,MAAM,CAAC,MAAM,cAAc,GAAG,wBAAiC,CAAC;AAEhE,yEAAyE;AACzE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,aAAa,CAAU,CAAC;AAgItD,2FAA2F;AAC3F,MAAM,UAAU,eAAe;IAC9B,OAAO;QACN,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,mBAAmB;QAC3B,MAAM,EAAE,cAAc;QACtB,KAAK,EAAE,CAAC,GAAG,aAAa,CAAC;KACzB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACxC,MAAM,IAAI,GAAG,CAAC,KAAa,EAAwC,EAAE;QACpE,yEAAyE;QACzE,yEAAyE;QACzE,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC,QAAQ,KAAK,4BAA4B,EAAE,GAAG,CAAC,CAAC;QACtE,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1B,IAAI,CAAC,KAAK,IAAI;YAAE,OAAO,SAAS,CAAC;QACjC,OAAO,EAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAC,CAAC;IAC7C,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5B,IAAI,MAAM,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACjD,MAAM,IAAI,iBAAiB,CAC1B,yEAAyE,MAAM,EAAE,CACjF,CAAC;IACH,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;IAEtC,OAAO;QACN,MAAM,EAAE,MAAM,CAAC,CAAC;QAChB,SAAS,EAAE,MAAM,CAAC,GAAG;QACrB,KAAK,EAAE,KAAK,CAAC,CAAC;QACd,QAAQ,EAAE,KAAK,CAAC,GAAG;QACnB,UAAU,EAAE,UAAU,EAAE,CAAC;QACzB,aAAa,EAAE,UAAU,EAAE,GAAG;KAC9B,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc;IACvC,MAAM,QAAQ,GAAkB,EAAE,CAAC;IACnC,8EAA8E;IAC9E,8EAA8E;IAC9E,MAAM,EAAE,GAAG,6BAA6B,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;QACrC,QAAQ,CAAC,IAAI,CAAC;YACb,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YAClB,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACjB,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;SACnB,CAAC,CAAC;IACJ,CAAC;IACD,OAAO,EAAC,QAAQ,EAAC,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACzB,IAAI,GAAG,mBAAmB,CAAC;CAC7C"}

package/dist/engine/shrinko/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The shrinko adapter seam: how every shrinko-backed command reaches shrinko8.
+ *
+ * `adapter.ts` is the command-facing CONTRACT (the {@link ShrinkoAdapter}
+ * interface, the {@link ShrinkoResult} discriminated union, the structured
+ * {@link ShrinkoNotFound} value, and the `--count` parser). `shell.ts` is the v1
+ * IMPLEMENTATION that shells out to a user-installed Python `shrinko8`
+ * (ADR-0001). A future native-TS implementation implements the same interface
+ * and drops in without touching the command layer.
+ */
+export { type CountReport, type LintFinding, type LintReport, type MinifyReport, parseCount, parseLint, SHRINKO_NEEDS, SHRINKO_REMEDY, type ShrinkoAdapter, type ShrinkoNotFound, shrinkoNotFound, type ShrinkoOk, ShrinkoParseError, type ShrinkoResult, } from './adapter.js';
+export { type ChildResult, type ChildRunner, execFileRunner, ShellShrinkoAdapter, type ShellShrinkoOptions, } from './shell.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/engine/shrinko/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/shrinko/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,UAAU,EACV,SAAS,EACT,aAAa,EACb,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,eAAe,EACf,KAAK,SAAS,EACd,iBAAiB,EACjB,KAAK,aAAa,GAClB,MAAM,cAAc,CAAC;AACtB,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,cAAc,EACd,mBAAmB,EACnB,KAAK,mBAAmB,GACxB,MAAM,YAAY,CAAC"}

package/dist/engine/shrinko/index.js

@@ -0,0 +1,13 @@
+/**
+ * The shrinko adapter seam: how every shrinko-backed command reaches shrinko8.
+ *
+ * `adapter.ts` is the command-facing CONTRACT (the {@link ShrinkoAdapter}
+ * interface, the {@link ShrinkoResult} discriminated union, the structured
+ * {@link ShrinkoNotFound} value, and the `--count` parser). `shell.ts` is the v1
+ * IMPLEMENTATION that shells out to a user-installed Python `shrinko8`
+ * (ADR-0001). A future native-TS implementation implements the same interface
+ * and drops in without touching the command layer.
+ */
+export { parseCount, parseLint, SHRINKO_NEEDS, SHRINKO_REMEDY, shrinkoNotFound, ShrinkoParseError, } from './adapter.js';
+export { execFileRunner, ShellShrinkoAdapter, } from './shell.js';
+//# sourceMappingURL=index.js.map

package/dist/engine/shrinko/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/engine/shrinko/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAKN,UAAU,EACV,SAAS,EACT,aAAa,EACb,cAAc,EAGd,eAAe,EAEf,iBAAiB,GAEjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAGN,cAAc,EACd,mBAAmB,GAEnB,MAAM,YAAY,CAAC"}