dungbeetle 0.1.1

package/dist/doctor.d.ts

@@ -0,0 +1,18 @@
+import type { DungbeetleConfig } from "./config.js";
+export type DoctorSeverity = "pass" | "warn" | "fail";
+export type DoctorCheck = {
+    name: string;
+    severity: DoctorSeverity;
+    message: string;
+    target?: string;
+};
+export type DoctorReport = {
+    kind: "dungbeetle-doctor";
+    passed: boolean;
+    project: string;
+    checks: DoctorCheck[];
+};
+export declare function runDoctor(options: {
+    config: DungbeetleConfig;
+    cwd?: string;
+}): Promise<DoctorReport>;

package/dist/doctor.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+import { captureTypes } from "./captures/registry.js";
+export async function runDoctor(options) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const checks = [
+        validateCaptureTargets(options.config),
+        validateBaselinePath(options.config),
+        validateArtifactsPath(options.config),
+        ...(await validateTargets(options.config, cwd))
+    ];
+    return {
+        kind: "dungbeetle-doctor",
+        passed: checks.every((check) => check.severity !== "fail"),
+        project: options.config.project.name,
+        checks
+    };
+}
+function validateCaptureTargets(config) {
+    return config.lifecycle.capture.length > 0
+        ? {
+            name: "capture-targets",
+            severity: "pass",
+            message: `${config.lifecycle.capture.length} capture target(s) configured.`
+        }
+        : {
+            name: "capture-targets",
+            severity: "fail",
+            message: "No capture targets configured. Add terminal or web targets to lifecycle.capture."
+        };
+}
+function validateBaselinePath(config) {
+    return config.baselinesDir.startsWith(".dungbeetle")
+        ? {
+            name: "baseline-path",
+            severity: "warn",
+            message: "baselinesDir is inside .dungbeetle, which is usually ignored. Use a reviewable path such as dungbeetle.snapshots."
+        }
+        : {
+            name: "baseline-path",
+            severity: "pass",
+            message: `Baselines will be stored in ${config.baselinesDir}.`
+        };
+}
+function validateArtifactsPath(config) {
+    return {
+        name: "artifact-path",
+        severity: "pass",
+        message: `Run artifacts will be stored in ${config.artifactsDir}.`
+    };
+}
+async function validateTargets(config, cwd) {
+    const checks = [];
+    for (const target of config.lifecycle.capture) {
+        checks.push(...(await captureTypes[target.kind].doctorChecks(target, cwd)));
+    }
+    return checks;
+}

package/dist/game/capture.d.ts

@@ -0,0 +1,24 @@
+import type { CaptureTarget } from "../config.js";
+export type GameTarget = Extract<CaptureTarget, {
+    kind: "game";
+}>;
+export type GameSnapshot = {
+    kind: "game";
+    engine: string;
+    engineVersion: string;
+    adapterVersion: string;
+    ticks: number;
+    markers: Record<string, {
+        tick: number;
+        state: unknown;
+    }>;
+    screenshots?: Record<string, {
+        mimeType: "image/png";
+        data: string;
+    }>;
+};
+export declare function resolveEnginePath(target: GameTarget): string;
+export declare function captureGame(target: GameTarget, options: {
+    cwd: string;
+    timeoutMs: number;
+}): Promise<GameSnapshot>;

package/dist/game/capture.js

@@ -0,0 +1,51 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { runWalkthrough } from "./protocol.js";
+import { loadWalkthrough } from "./walkthrough.js";
+export function resolveEnginePath(target) {
+    return target.enginePath ?? process.env.DUNGBEETLE_GODOT_PATH ?? "godot";
+}
+export async function captureGame(target, options) {
+    const walkthrough = await loadWalkthrough(path.resolve(options.cwd, target.walkthrough));
+    const project = path.resolve(options.cwd, target.project);
+    const visual = target.mode === "visual";
+    const outDir = await mkdtemp(path.join(tmpdir(), "dungbeetle-game-"));
+    try {
+        const run = await runWalkthrough({
+            command: resolveEnginePath(target),
+            args: visual ? ["--path", project] : ["--headless", "--path", project],
+            cwd: project,
+            timeoutMs: target.timeoutMs ?? options.timeoutMs,
+            handshakeTimeoutMs: 10_000,
+            seed: target.seed ?? 0,
+            physicsFps: target.physicsFps ?? 60,
+            screenshots: visual,
+            outDir,
+            steps: walkthrough.steps
+        });
+        const markers = {};
+        const screenshots = {};
+        for (const [name, marker] of Object.entries(run.markers)) {
+            markers[name] = { tick: marker.tick, state: marker.state };
+            if (marker.screenshot) {
+                screenshots[name] = {
+                    mimeType: "image/png",
+                    data: (await readFile(marker.screenshot)).toString("base64")
+                };
+            }
+        }
+        return {
+            kind: "game",
+            engine: run.engine.name,
+            engineVersion: run.engine.version,
+            adapterVersion: run.adapter.version,
+            ticks: run.ticks,
+            markers,
+            ...(Object.keys(screenshots).length > 0 ? { screenshots } : {})
+        };
+    }
+    finally {
+        await rm(outDir, { recursive: true, force: true });
+    }
+}

package/dist/game/protocol.d.ts

@@ -0,0 +1,30 @@
+import type { WalkthroughStep } from "./walkthrough.js";
+export declare const PROTOCOL_VERSION = 1;
+export type GameRunResult = {
+    engine: {
+        name: string;
+        version: string;
+    };
+    adapter: {
+        version: string;
+    };
+    ticks: number;
+    markers: Record<string, {
+        tick: number;
+        state: unknown;
+        screenshot?: string;
+    }>;
+};
+export type GameRunOptions = {
+    command: string;
+    args: string[];
+    cwd: string;
+    timeoutMs: number;
+    handshakeTimeoutMs: number;
+    seed: number;
+    physicsFps: number;
+    screenshots: boolean;
+    outDir: string;
+    steps: WalkthroughStep[];
+};
+export declare function runWalkthrough(options: GameRunOptions): Promise<GameRunResult>;

package/dist/game/protocol.js

@@ -0,0 +1,146 @@
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import path from "node:path";
+import { isRecord } from "../guards.js";
+export const PROTOCOL_VERSION = 1;
+// Drive one walkthrough over the v1 stdio JSON-lines protocol: spawn the
+// engine, handshake, configure determinism, send the whole script, collect
+// marker events until `done`. See docs/design/game-capture-protocol-v1.md.
+export function runWalkthrough(options) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(options.command, options.args, {
+            cwd: options.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+            // The adapter autoload is inert unless this is set, so a shipped game
+            // never accidentally speaks protocol on players' machines.
+            env: { ...process.env, DUNGBEETLE_PROTOCOL: "1" }
+        });
+        const markers = {};
+        const stderrTail = [];
+        let engine;
+        let adapter;
+        let settled = false;
+        let requestId = 0;
+        const fail = (message) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(watchdog);
+            clearTimeout(handshakeDeadline);
+            child.kill("SIGKILL");
+            const tail = stderrTail.length > 0 ? `\nEngine stderr:\n${stderrTail.join("\n")}` : "";
+            reject(new Error(`${message}${tail}`));
+        };
+        const finish = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(watchdog);
+            clearTimeout(handshakeDeadline);
+            send({ type: "quit" });
+            // Grace period, then make sure the child is gone.
+            const grace = setTimeout(() => child.kill("SIGKILL"), 2000);
+            child.once("exit", () => clearTimeout(grace));
+            resolve(result);
+        };
+        const send = (message) => {
+            requestId += 1;
+            child.stdin.write(`${JSON.stringify({ ...message, id: requestId })}\n`);
+        };
+        const watchdog = setTimeout(() => fail(`Game run timed out after ${options.timeoutMs}ms.`), options.timeoutMs);
+        const handshakeDeadline = setTimeout(() => fail(`Engine adapter did not respond to the handshake within ${options.handshakeTimeoutMs}ms. Is the Dungbeetle adapter installed in the project?`), options.handshakeTimeoutMs);
+        child.on("error", (error) => fail(`Failed to launch engine "${options.command}": ${error.message}`));
+        child.on("exit", (code) => {
+            if (!settled) {
+                fail(`Engine exited (code ${code}) before the walkthrough finished.`);
+            }
+        });
+        createInterface({ input: child.stderr }).on("line", (line) => {
+            stderrTail.push(line);
+            if (stderrTail.length > 20) {
+                stderrTail.shift();
+            }
+        });
+        createInterface({ input: child.stdout }).on("line", (line) => {
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                return; // Engine banners and stray prints are not protocol.
+            }
+            if (!isRecord(message) || typeof message.type !== "string") {
+                return;
+            }
+            switch (message.type) {
+                case "hello": {
+                    clearTimeout(handshakeDeadline);
+                    const protocol = isRecord(message.protocol) ? message.protocol : {};
+                    const min = typeof protocol.min === "number" ? protocol.min : NaN;
+                    const max = typeof protocol.max === "number" ? protocol.max : NaN;
+                    if (!(min <= PROTOCOL_VERSION && PROTOCOL_VERSION <= max)) {
+                        fail(`Protocol mismatch: CLI speaks v${PROTOCOL_VERSION}, adapter supports v${min}–v${max}. Upgrade the ${min > PROTOCOL_VERSION ? "CLI" : "adapter"}.`);
+                        return;
+                    }
+                    engine = isRecord(message.engine)
+                        ? { name: String(message.engine.name), version: String(message.engine.version) }
+                        : { name: "unknown", version: "unknown" };
+                    adapter = isRecord(message.adapter)
+                        ? { version: String(message.adapter.version) }
+                        : { version: "unknown" };
+                    send({
+                        type: "configure",
+                        seed: options.seed,
+                        physicsFps: options.physicsFps,
+                        screenshots: options.screenshots,
+                        outDir: options.outDir
+                    });
+                    return;
+                }
+                case "ready":
+                    send({ type: "run", steps: options.steps });
+                    return;
+                case "marker": {
+                    // The adapter is game code, so it doesn't get to steer filesystem
+                    // paths: marker names become artifact filenames and the screenshot
+                    // path is read back by the CLI. Enforce the walkthrough's name
+                    // shape and confine the screenshot to this run's outDir.
+                    const name = String(message.name);
+                    if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+                        fail(`Engine adapter reported an invalid marker name: ${JSON.stringify(name)}`);
+                        return;
+                    }
+                    const screenshot = typeof message.screenshot === "string" ? path.resolve(message.screenshot) : undefined;
+                    if (screenshot && !screenshot.startsWith(path.resolve(options.outDir) + path.sep)) {
+                        fail(`Engine adapter reported a screenshot outside the run directory: ${screenshot}`);
+                        return;
+                    }
+                    markers[name] = {
+                        tick: typeof message.tick === "number" ? message.tick : 0,
+                        state: message.state,
+                        ...(screenshot ? { screenshot } : {})
+                    };
+                    return;
+                }
+                case "error": {
+                    const step = typeof message.step === "number" ? ` at steps[${message.step}]` : "";
+                    fail(`Engine adapter error${step}: ${String(message.message)} (${String(message.code)})`);
+                    return;
+                }
+                case "done":
+                    finish({
+                        engine: engine ?? { name: "unknown", version: "unknown" },
+                        adapter: adapter ?? { version: "unknown" },
+                        ticks: typeof message.ticks === "number" ? message.ticks : 0,
+                        markers
+                    });
+                    return;
+                default:
+                    return; // Unknown types are ignored — additive-only within a major.
+            }
+        });
+        send({ type: "hello", protocolVersion: PROTOCOL_VERSION });
+    });
+}

package/dist/game/walkthrough.d.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+declare const stepSchema: z.ZodUnion<readonly [z.ZodObject<{
+    input: z.ZodString;
+    mode: z.ZodOptional<z.ZodEnum<{
+        down: "down";
+        up: "up";
+        tap: "tap";
+    }>>;
+    ticks: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    wait: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    waitFor: z.ZodString;
+    timeoutTicks: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    screenshot: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    assert: z.ZodString;
+}, z.core.$strict>]>;
+declare const walkthroughSchema: z.ZodObject<{
+    description: z.ZodOptional<z.ZodString>;
+    steps: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        input: z.ZodString;
+        mode: z.ZodOptional<z.ZodEnum<{
+            down: "down";
+            up: "up";
+            tap: "tap";
+        }>>;
+        ticks: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        wait: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        waitFor: z.ZodString;
+        timeoutTicks: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+        screenshot: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        assert: z.ZodString;
+    }, z.core.$strict>]>>;
+}, z.core.$strict>;
+export type WalkthroughStep = z.infer<typeof stepSchema>;
+export type Walkthrough = z.infer<typeof walkthroughSchema>;
+export declare function walkthroughIssues(value: unknown): string[];
+export declare function loadWalkthrough(filePath: string): Promise<Walkthrough>;
+export {};

package/dist/game/walkthrough.js

@@ -0,0 +1,85 @@
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+// The walkthrough script format (protocol v1 wire shape for `run.steps`, see
+// docs/design/game-capture-protocol-v1.md). Inputs are input-map ACTIONS, not
+// raw key events — raw injection measured flaky against physics catch-up
+// bursts, while action-level injection was deterministic.
+const inputStep = z
+    .object({
+    input: z.string().min(1),
+    mode: z.enum(["down", "up", "tap"]).optional(),
+    ticks: z.number().int().min(1).optional()
+})
+    .strict();
+const waitStep = z.object({ wait: z.number().int().min(1) }).strict();
+// Predicate waits carry a mandatory tick budget so a walkthrough can never
+// hang the run — the engine watchdog is the backstop, not the plan.
+const waitForStep = z
+    .object({ waitFor: z.string().min(1), timeoutTicks: z.number().int().min(1) })
+    .strict();
+const screenshotStep = z.object({ screenshot: z.string().regex(/^[a-z0-9][a-z0-9-]*$/) }).strict();
+const assertStep = z.object({ assert: z.string().min(1) }).strict();
+const stepSchema = z.union([inputStep, waitStep, waitForStep, screenshotStep, assertStep]);
+const walkthroughSchema = z
+    .object({
+    description: z.string().optional(),
+    steps: z.array(stepSchema).min(1)
+})
+    .strict();
+// Validation issues beyond the schema shape, phrased for the config/doctor
+// surface: each issue names the step index so the user can jump to it.
+export function walkthroughIssues(value) {
+    const parsed = walkthroughSchema.safeParse(value);
+    if (!parsed.success) {
+        return parsed.error.issues.map((issue) => {
+            const at = issue.path.length > 0 ? ` at ${issue.path.join(".")}` : "";
+            return `${issue.message}${at}`;
+        });
+    }
+    const issues = [];
+    const seen = new Map();
+    parsed.data.steps.forEach((step, index) => {
+        if ("screenshot" in step) {
+            const first = seen.get(step.screenshot);
+            if (first !== undefined) {
+                issues.push(`duplicate marker "${step.screenshot}" at steps[${index}] (first used at steps[${first}]) — markers name snapshot keys and must be unique.`);
+            }
+            else {
+                seen.set(step.screenshot, index);
+            }
+        }
+        if ("input" in step &&
+            step.ticks !== undefined &&
+            step.mode !== undefined &&
+            step.mode !== "tap") {
+            issues.push(`steps[${index}] sets "ticks" with mode "${step.mode}" — ticks is the tap hold duration and only applies to mode "tap".`);
+        }
+    });
+    if (seen.size === 0) {
+        issues.push('walkthrough has no "screenshot" marker steps — the run would capture nothing.');
+    }
+    return issues;
+}
+// Parse + fully validate a walkthrough file. Throws one actionable error
+// carrying every issue, not just the first.
+export async function loadWalkthrough(filePath) {
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf8");
+    }
+    catch {
+        throw new Error(`Walkthrough file is missing at ${filePath}.`);
+    }
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Walkthrough at ${filePath} is not valid JSON: ${error.message}`);
+    }
+    const issues = walkthroughIssues(value);
+    if (issues.length > 0) {
+        throw new Error(`Walkthrough at ${filePath} is invalid:\n  - ${issues.join("\n  - ")}`);
+    }
+    return walkthroughSchema.parse(value);
+}

package/dist/guards.d.ts

@@ -0,0 +1,2 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isErrno(error: unknown, code: string): boolean;

package/dist/guards.js

@@ -0,0 +1,15 @@
+// Shared runtime type guards.
+//
+// `isRecord` was previously copy-pasted into six modules, and the copies had
+// drifted (one omitted the array check). Keep the single definition here so the
+// snapshot canonicalizer, comparer, and adapters all agree on what "a plain
+// object" means.
+export function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+// True when `error` is a Node system error carrying the given errno code (e.g.
+// "ENOENT" for a missing file or binary). Previously hand-rolled in several
+// modules; kept here so the ENOENT check is written once.
+export function isErrno(error, code) {
+    return (error instanceof Error && "code" in error && error.code === code);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};