picopilot 0.0.0 → 0.1.0

package/dist/engine/pico8/session.js

@@ -0,0 +1,250 @@
+/**
+ * The RESUMABLE playtest SESSION handshake core (ADR-0011, prd US #6): the pure,
+ * CI-testable half of the "A" live model. It keeps a single driven PICO-8 process
+ * ALIVE and PAUSED between the agent's turns and drives it one command at a time
+ * over the verified transport: write a FIXED-SIZE command block, WAIT for the
+ * cart's ACK line on stdout, then return. The handshake (not wall-clock spacing)
+ * is what makes stepping deterministic and lossless, so the agent always acts on
+ * a SETTLED, known frame.
+ *
+ * This module owns ONLY the send -> wait-ack -> return logic against the
+ * {@link Pico8Process} seam (the same seam the one-shot `drive` uses), so every
+ * path (a completed step, a lost/late ack, the process dying mid-command) is
+ * unit-tested against a FAKE process WITHOUT the paid binary. The daemon that
+ * spawns the real process and exposes the session to separate CLI invocations by
+ * id lives in `supervisor.ts`; a live multi-turn session is the manual/opt-in
+ * tier. The cart-side transform is reused UNCHANGED from `drive.ts`.
+ */
+import { ACK, BLOCK_SIZE, encodeCommand } from './drive.js';
+/** A structured session-command failure (never a raw throw across the seam). */
+export class SessionError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SessionError';
+        this.code = code;
+    }
+}
+/**
+ * How long a single command waits for its ACK before it is declared lost (the
+ * lost/late-ack path). Generous: a STEP of many frames takes real time at 30fps,
+ * plus PICO-8 scheduling jitter, but a hung/dead cart must not wall the session
+ * forever. The supervisor's process-death signal (see {@link DriveSession}) ends
+ * a command EARLY when the process dies, so this only fires for a truly stuck
+ * cart.
+ */
+export const DEFAULT_ACK_TIMEOUT_MS = 15_000;
+/**
+ * A stateful line reader over a PICO-8 stdout stream: the cart's `printh` ACKs
+ * and the done-sentinel land line-by-line, but the OS delivers stdout in
+ * arbitrary chunks. This buffers partial lines and lets a waiter await the NEXT
+ * line matching a predicate, so the handshake is exact (an ACK is a whole line,
+ * never a substring of unrelated output). Mirrors `SentinelWatcher`'s line
+ * discipline; kept separate because the session awaits a SPECIFIC ack, not a
+ * single terminal sentinel.
+ */
+class AckLineReader {
+    buffer = '';
+    pending = [];
+    /** Lines seen but not yet consumed by a waiter (an ACK that raced ahead). */
+    queued = [];
+    /** Feeds a raw stdout chunk; resolves any waiter its lines satisfy. */
+    push(chunk) {
+        this.buffer += chunk;
+        let nl;
+        while ((nl = this.buffer.indexOf('\n')) !== -1) {
+            let line = this.buffer.slice(0, nl);
+            if (line.endsWith('\r'))
+                line = line.slice(0, -1);
+            this.buffer = this.buffer.slice(nl + 1);
+            this.deliver(line);
+        }
+    }
+    deliver(line) {
+        // A waiter already parked for this line consumes it; else queue it so a
+        // waiter that parks AFTER the cart printed can still find it.
+        const idx = this.pending.findIndex((p) => p.match(line));
+        if (idx !== -1) {
+            const [waiter] = this.pending.splice(idx, 1);
+            waiter.resolve(line);
+        }
+        else {
+            this.queued.push(line);
+        }
+    }
+    /**
+     * Awaits the next line satisfying `match`. If such a line was already seen
+     * (queued) it resolves synchronously-soon; otherwise it parks until one
+     * arrives. The caller races this against a timeout / process-death signal.
+     */
+    waitFor(match) {
+        const idx = this.queued.findIndex(match);
+        if (idx !== -1) {
+            const [line] = this.queued.splice(idx, 1);
+            return Promise.resolve(line);
+        }
+        return new Promise((resolve) => {
+            this.pending.push({ match, resolve });
+        });
+    }
+}
+/**
+ * The live-session handshake engine (ADR-0011, US #6). Wraps ONE driven
+ * {@link Pico8Process} and exposes the agent's verbs: {@link input} (set the
+ * held-buttons byte), {@link step} (advance exactly N frames), {@link shot}
+ * (capture the frozen current frame), {@link stop} (tear the session down). Each
+ * verb WRITES a single fixed-size command block and AWAITS the cart's ACK before
+ * resolving, so the process stays alive + paused between verbs and the caller
+ * always acts on a settled frame. Between the ACK and the next verb the game is
+ * frozen (its callbacks skipped, a stable framebuffer), so a {@link shot} always
+ * captures exactly the intended moment.
+ *
+ * The engine is transport-agnostic: it talks to the {@link Pico8Process} seam,
+ * so the send/wait/return + lost-ack + process-death paths are unit-tested
+ * against a FAKE process with no real binary. The supervisor supplies a REAL
+ * spawned process for a live session (the manual/opt-in tier).
+ */
+export class DriveSession {
+    proc;
+    reader = new AckLineReader();
+    ackTimeoutMs;
+    shotBasename;
+    frames = 0;
+    shotIndex = 0;
+    /** Set once the process dies; every in-flight + future command rejects. */
+    dead = false;
+    closed = false;
+    deathWaiters = [];
+    constructor(options) {
+        this.proc = options.process;
+        this.ackTimeoutMs = options.ackTimeoutMs ?? DEFAULT_ACK_TIMEOUT_MS;
+        this.shotBasename = options.shotBasename;
+        this.proc.onStdout((chunk) => this.reader.push(chunk));
+        this.proc.onClose(() => this.markDead());
+        this.proc.onError(() => this.markDead());
+    }
+    /** Total frames the session has advanced so far. */
+    get frame() {
+        return this.frames;
+    }
+    /** Whether the underlying process has died (crashed/quit). */
+    get isDead() {
+        return this.dead;
+    }
+    markDead() {
+        if (this.dead)
+            return;
+        this.dead = true;
+        for (const w of this.deathWaiters.splice(0))
+            w();
+    }
+    /**
+     * Sets the per-frame HELD-buttons byte for the upcoming steps (US #6: inject
+     * input between turns). Writes an INPUT block and awaits its ACK. The held
+     * level persists until the next INPUT (the cart holds it), and `btnp` edges
+     * are reconstructed cart-side from the held sequence.
+     */
+    async input(held) {
+        await this.send({ op: 'input', held: held & 0xff }, ACK.input);
+        return { frame: this.frames, ack: ACK.input };
+    }
+    /**
+     * Advances EXACTLY `frames` frames then pauses (US #6, US #4). Writes a STEP
+     * block and awaits the STEP-DONE ack, which the cart prints only when the
+     * frame budget reaches 0, so the returned result means the N frames ACTUALLY
+     * ran and the game is now paused on a settled frame. `frames` must fit one
+     * byte (the block's arg); larger spans are issued as repeated steps by the
+     * caller.
+     */
+    async step(frames) {
+        if (frames <= 0)
+            return { frame: this.frames, ack: ACK.stepDone };
+        await this.send({ op: 'step', frames: frames & 0xff }, ACK.stepDone);
+        this.frames += frames;
+        return { frame: this.frames, ack: ACK.stepDone };
+    }
+    /**
+     * Captures the current (paused, frozen) frame (US #6, US #5). Writes a SHOT
+     * block and awaits its ACK; the cart renders the frozen state once then
+     * screenshots it, so the capture is exactly the intended moment. Returns the
+     * `<basename><n>` the cart named it, which the supervisor collects from the
+     * `-desktop` dir.
+     */
+    async shot() {
+        await this.send({ op: 'shot' }, ACK.shot);
+        const shotName = `${this.shotBasename}${this.shotIndex}`;
+        this.shotIndex += 1;
+        return { frame: this.frames, ack: ACK.shot, shotName };
+    }
+    /**
+     * Tears the session down: writes a QUIT block (the cart prints the sentinel so
+     * the launcher kills PICO-8), then kills the process as the backstop. Does NOT
+     * await an ACK (QUIT ends the cart), and is idempotent + safe on a dead
+     * process. After `stop`, every verb rejects with `playtest-session-closed`.
+     */
+    stop() {
+        this.closed = true;
+        if (!this.dead) {
+            try {
+                this.proc.writeStdin?.(encodeCommand({ op: 'quit' }));
+            }
+            catch {
+                // A closed stdin (already exiting) is fine; the kill below finishes it.
+            }
+        }
+        this.proc.kill();
+        this.markDead();
+    }
+    /**
+     * The core handshake: write one command block, then race the ACK line against
+     * the timeout and the process-death signal. A missing ACK within the deadline
+     * is the structured lost/late-ack error; a process that dies mid-command is the
+     * structured process-dead error. Never a hang, never a silent success.
+     */
+    async send(cmd, ackLine) {
+        if (this.closed) {
+            throw new SessionError('playtest-session-closed', 'the playtest session is stopped; start a new one');
+        }
+        if (this.dead) {
+            throw new SessionError('playtest-session-process-dead', 'PICO-8 exited; the playtest session is dead (start a new one)');
+        }
+        const block = encodeCommand(cmd);
+        if (block.length !== BLOCK_SIZE) {
+            // Defensive: the transport is fixed-size by construction; a mismatch is a
+            // codec bug, surfaced loudly rather than sent as a short (coalescing) write.
+            throw new SessionError('playtest-session-closed', `encoded command block is ${block.length} bytes, expected ${BLOCK_SIZE}`);
+        }
+        // Park the ACK waiter BEFORE writing, so an ACK the cart prints promptly is
+        // never missed between the write and the await.
+        const ackP = this.reader.waitFor((line) => line === ackLine);
+        this.proc.writeStdin?.(block);
+        let timer;
+        const timeoutP = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), this.ackTimeoutMs);
+        });
+        const deathP = new Promise((resolve) => {
+            if (this.dead)
+                resolve('dead');
+            else
+                this.deathWaiters.push(() => resolve('dead'));
+        });
+        try {
+            const outcome = await Promise.race([
+                ackP.then(() => 'ack'),
+                timeoutP,
+                deathP,
+            ]);
+            if (outcome === 'timeout') {
+                throw new SessionError('playtest-session-ack-timeout', `no ACK "${ackLine}" within ${this.ackTimeoutMs}ms (the cart may have hung or faulted)`);
+            }
+            if (outcome === 'dead') {
+                throw new SessionError('playtest-session-process-dead', `PICO-8 exited before ACK "${ackLine}" (the session is dead)`);
+            }
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/engine/pico8/session.js.map

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

package/dist/engine/pico8/shell.d.ts

@@ -0,0 +1,103 @@
+import { type DriveOptions, type ExportOptions, type Pico8Adapter, type Pico8DriveResult, type Pico8ExportResult, type Pico8RecordResult, type Pico8Result, type RecordOptions, type RunOptions } from './adapter.js';
+/**
+ * A spawned PICO-8 process, abstracted so tests inject a fake. `onStdout`
+ * delivers stdout chunks (both `stdout` and `stderr` folded in, since PICO-8's
+ * `printh` and its own lines can land on either); `onClose` fires when the
+ * process exits on its own; `onError` fires on a spawn failure (ENOENT ⇒ PICO-8
+ * absent). `kill` terminates the process tree (the backstop / sentinel kill).
+ */
+export interface Pico8Process {
+    onStdout(cb: (chunk: string) => void): void;
+    onClose(cb: (code: number | null) => void): void;
+    onError(cb: (err: NodeJS.ErrnoException) => void): void;
+    kill(): void;
+    /**
+     * Writes raw bytes to the process's stdin, for the `drive` transport (the
+     * fixed-size command blocks). Absent/undefined when stdin was detached
+     * (`run`/`record` ignore stdin so the cart never blocks on console input).
+     */
+    writeStdin?(bytes: Uint8Array): void;
+}
+/**
+ * The process-spawn seam (mirrors shrinko's `ChildRunner`). The real impl spawns
+ * `pico8 -x`; a test injects a fake that emits synthetic stdout and a chosen
+ * outcome, so the sentinel-kill / backstop / pico8-absent paths are all testable
+ * WITHOUT the paid binary. `env` is handed in (its `PICO8_PATH`/`PATH` are the
+ * isolation levers), never read ambiently.
+ */
+export type SpawnRunner = (file: string, args: string[], env: NodeJS.ProcessEnv, options?: {
+    stdin?: boolean;
+}) => Pico8Process;
+export declare function pico8HomeDir(): string;
+/**
+ * Prepend `-home <isolatedDir>` to a PICO-8 arg list so its config/data never
+ * land in the CWD. Applied at every spawn site.
+ */
+export declare function withPico8Home(args: string[]): string[];
+export declare const spawnRunner: SpawnRunner;
+/** The candidate ways to launch PICO-8, tried in order: `PICO8_PATH`, then `pico8` on `PATH`. */
+export declare function pico8Candidates(env: NodeJS.ProcessEnv): string[];
+/** Options for {@link ShellPico8Adapter}. */
+export interface ShellPico8Options {
+    /** The environment for the child (its `PICO8_PATH`/`PATH` locate the binary). */
+    readonly env: NodeJS.ProcessEnv;
+    /** The spawn runner (defaults to {@link spawnRunner}); tests inject a fake. */
+    readonly spawn?: SpawnRunner;
+}
+/**
+ * The v1 {@link Pico8Adapter}: shells out to the user's native `pico8 -x`
+ * (ADR-0006, native path first). It owns the ORCHESTRATION the command should
+ * not hand-roll: launch, stream stdout, kill on the done-sentinel, arm the
+ * backstop, and collect screenshots + printh + exit reason into one result.
+ *
+ * PICO-8 absent (the first candidate ENOENTs and there is no fallback) returns
+ * the structured {@link pico8NotFound} value, never a throw or a hang. That
+ * absent path is the CI-testable one; live runs are a manual/opt-in tier.
+ */
+export declare class ShellPico8Adapter implements Pico8Adapter {
+    private readonly env;
+    private readonly spawnRun;
+    constructor(options: ShellPico8Options);
+    run(options: RunOptions): Promise<Pico8Result>;
+    /**
+     * Records a running cart's audio to a WAV (ADR-0009). Launches PICO-8 in a
+     * REAL A/V session (`-run`, NOT the headless `-x` that mixes no audio) and
+     * controls the WAV location with `-root_path <wavDir>`, because
+     * `extcmd("audio_end", 1)` saves to PICO-8's CURRENT folder, not `-desktop`
+     * (the `audio_end(1)` trap). The cooperating cart (a harness for `record`, or
+     * the whole render harness) does the `audio_rec`/`audio_end`/sentinel dance; we
+     * watch the sentinel, arm the backstop, and collect `<basename>.wav` from the
+     * isolated `wavDir`. Live capture is a manual/opt-in tier; the absent path is
+     * the CI-testable one.
+     */
+    /**
+     * Drives a throwaway cart through scripted input and captures live gameplay
+     * (ADR-0011). Launches `-desktop <shotDir> -x <cart>` with a LIVE stdin, writes
+     * the whole encoded FIXED-SIZE command block stream up front (the one-shot; the
+     * cart drains one block per frame and screenshots at the SHOT points), watches
+     * the sentinel, arms the backstop, and collects the SHOT PNGs + printh + exit
+     * reason. Returns {@link pico8NotFound} when PICO-8 is absent. Live capture is a
+     * manual/opt-in tier; the absent path is the CI-testable one.
+     */
+    drive(options: DriveOptions): Promise<Pico8DriveResult>;
+    /**
+     * Exports the cart as a PICO-8 HTML bundle over the HEADLESS `-x` path (no
+     * display needed: `pico8 <cart> -export <outDir>/<name> -x` runs the cart, writes
+     * `<name>.html` + `<name>.js`, and exits). PICO-8 derives both file names from
+     * the `.html` name, so passing `index.html` yields a directly-serveable pair.
+     * A labelless cart prints "please capture a label first" and still exports (a
+     * blank splash), surfaced as `labelWarning`. PICO-8 absent -> {@link pico8NotFound}.
+     */
+    export(options: ExportOptions): Promise<Pico8ExportResult>;
+    record(options: RecordOptions): Promise<Pico8RecordResult>;
+    /**
+     * The shared launch/sentinel-watch/backstop/collect loop behind both
+     * {@link run} and {@link record}. `buildOk` turns the exit reason + captured
+     * stdout into the command-specific success value; a spawn ENOENT with no
+     * fallback resolves the structured {@link pico8NotFound}. `printh` for `run` is
+     * filled by the caller from the run report path (kept out of `buildOk` there so
+     * the two report shapes stay distinct).
+     */
+    private orchestrate;
+}
+//# sourceMappingURL=shell.d.ts.map

package/dist/engine/pico8/shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.d.ts","sourceRoot":"","sources":["../../../src/engine/pico8/shell.ts"],"names":[],"mappings":"AAUA,OAAO,EACN,KAAK,YAAY,EAGjB,KAAK,aAAa,EAClB,KAAK,YAAY,EAEjB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAEhB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,MAAM,cAAc,CAAC;AAGtB;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,CAAC;IAC5C,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;IACjD,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,cAAc,KAAK,IAAI,GAAG,IAAI,CAAC;IACxD,IAAI,IAAI,IAAI,CAAC;IACb;;;;OAIG;IACH,UAAU,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,CAAC,EAAE;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAC,KACvB,YAAY,CAAC;AAsBlB,wBAAgB,YAAY,IAAI,MAAM,CAIrC;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAItD;AAED,eAAO,MAAM,WAAW,EAAE,WAsCzB,CAAC;AAEF,iGAAiG;AACjG,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,EAAE,CAKhE;AAuDD,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IACjC,iFAAiF;IACjF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IACrD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;gBAE3B,OAAO,EAAE,iBAAiB;IAKtC,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC;IAoB9C;;;;;;;;;;OAUG;IACH;;;;;;;;OAQG;IACH,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAmBvD;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IA+B1D,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAsB1D;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;CA0DnB"}