@debuffjp/cli 0.0.0-stage → 0.2.0

package/dist/fuzz.js

@@ -0,0 +1,229 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { hooksReady } from "./scenario/browser.js";
+import { launchBrowser } from "./scenario/run.js";
+import { createDevServer } from "./vite.js";
+/** Keys most small games use. Override with `keys` (KeyboardEvent.code values). */
+export const DEFAULT_FUZZ_KEYS = [
+    "ArrowLeft",
+    "ArrowRight",
+    "ArrowUp",
+    "ArrowDown",
+    "KeyA",
+    "KeyD",
+    "KeyW",
+    "KeyS",
+    "Space",
+    "Enter",
+    "KeyZ",
+    "KeyX",
+];
+const MOVE_KEYS = new Set(["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "KeyA", "KeyD", "KeyW", "KeyS"]);
+/** Steps between state samples while fuzzing; loops shorter than this can slip through. */
+const SAMPLE_STEPS = 10;
+/** A field flipping between the same two values this many times with input unchanged counts as a loop. */
+const LOOP_FLIPS = 4;
+/** Small, fast, seeded PRNG (mulberry32): the same seed always gives the same inputs. */
+function rng(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/**
+ * Call a dev hook. If the game throws, hand the error to the page's own error reporting (so the dev tools
+ * explain and source-map it, exactly as for a crash during play) and return it instead of throwing.
+ */
+function callSafe(page, method, args) {
+    return page.evaluate(([m, a]) => {
+        const hooks = window.__DEBUFF_DEV__;
+        try {
+            return { ok: true, value: hooks[m]?.(...a) };
+        }
+        catch (err) {
+            reportError(err);
+            return { ok: false, error: err instanceof Error ? `${err.name}: ${err.message}` : String(err) };
+        }
+    }, [method, args]);
+}
+/**
+ * Play the game with random but plausible input: movement keys held for a while, action keys tapped.
+ * Finds runtime errors and stuck states, and writes each as a replayable scenario in `.debuff/fuzz/`.
+ * Deterministic: fixed steps plus a seeded game mean the recorded inputs reproduce the run exactly.
+ */
+export async function runFuzz(options) {
+    const started = Date.now();
+    const seed = options.seed ?? Math.floor(Math.random() * 2 ** 31);
+    const runs = options.runs ?? 3;
+    const budget = Math.round((options.seconds ?? 60) * 60);
+    const keys = options.keys?.length ? options.keys : DEFAULT_FUZZ_KEYS;
+    const stuckSteps = Math.round((options.stuckSeconds ?? 15) * 60);
+    const outDir = join(options.root, ".debuff", "fuzz");
+    mkdirSync(outDir, { recursive: true });
+    const server = await createDevServer(options.root, { port: 0, logLevel: "error" });
+    await server.listen();
+    const base = server.resolvedUrls?.local[0];
+    if (!base)
+        throw new Error("Dev server did not report a URL");
+    const browser = await launchBrowser();
+    const findings = [];
+    let totalSteps = 0;
+    try {
+        for (let run = 1; run <= runs; run++) {
+            const random = rng(seed + run * 7919);
+            const page = await browser.newPage({ viewport: { width: 960, height: 540 }, deviceScaleFactor: 1 });
+            try {
+                const url = new URL(options.page ?? "/", base);
+                url.searchParams.set("debuff-scenario", "1");
+                await page.goto(url.toString());
+                await page.waitForFunction(hooksReady, undefined, { timeout: 15_000 });
+                const steps = [];
+                const held = new Set();
+                let played = 0;
+                let lastState = "";
+                let changedAt = 0;
+                let stuckReported = false;
+                let loopReported = false;
+                // Loop detection: per top-level state field, the values it took since input last changed.
+                let flips = new Map();
+                const inputChanged = () => {
+                    flips = new Map();
+                };
+                const save = (label) => {
+                    const file = join(outDir, `fuzz-${seed}-run${run}-${label}.json`);
+                    // Release anything still held so the replay ends cleanly, then let the scenario runner judge it.
+                    const replay = [...steps, ...[...held].map((code) => ({ release: code }))];
+                    writeFileSync(file, `${JSON.stringify({ name: `fuzz ${seed} run ${run} (${label})`, ...(options.page ? { page: options.page } : {}), steps: replay }, null, 2)}\n`);
+                    // Relative to the project root, so it reads well and works as an argument to `debuff scenario`.
+                    return relative(options.root, file).split("\\").join("/");
+                };
+                /** Bouncing back and forth between two values with input unchanged, e.g. a door or stairs that send you straight back. */
+                const checkLoop = (state) => {
+                    if (loopReported || held.size === 0)
+                        return;
+                    const fields = [["scene", state.scene]];
+                    if (state.state && typeof state.state === "object")
+                        fields.push(...Object.entries(state.state).map(([k, v]) => [`state.${k}`, v]));
+                    for (const [path, value] of fields) {
+                        // true/false phase flags (scrolling, attacking) flip all the time in normal play.
+                        if (typeof value === "boolean")
+                            continue;
+                        const json = JSON.stringify(value) ?? "undefined";
+                        const seen = flips.get(path) ?? [];
+                        if (seen.at(-1) !== json)
+                            seen.push(json);
+                        flips.set(path, seen);
+                        if (seen.length >= LOOP_FLIPS + 1 && new Set(seen).size === 2) {
+                            loopReported = true;
+                            findings.push({
+                                kind: "loop",
+                                run,
+                                tick: state.tick,
+                                message: `${path} kept flipping between ${seen[0]} and ${seen[1]} while ${[...held].join("+")} stayed held. Possible loop (e.g. a door or stairs that send the player straight back).`,
+                                repro: save("loop"),
+                            });
+                            return;
+                        }
+                    }
+                };
+                const advance = async (n) => {
+                    // Step in short chunks so loops shorter than one hold are seen.
+                    let result = { ok: true, value: undefined };
+                    for (let left = n; left > 0 && result.ok; left -= SAMPLE_STEPS) {
+                        const chunk = Math.min(SAMPLE_STEPS, left);
+                        steps.push({ wait: chunk });
+                        played += chunk;
+                        result = await callSafe(page, "step", [chunk]);
+                        const value = result.ok ? result.value : undefined;
+                        if (value && typeof value.tick === "number")
+                            checkLoop(value);
+                    }
+                    return result;
+                };
+                while (played < budget) {
+                    // Mostly hold a movement key for a while, sometimes tap an action key, sometimes do nothing.
+                    const roll = random();
+                    const key = keys[Math.floor(random() * keys.length)] ?? "Space";
+                    let result;
+                    if (roll < 0.15) {
+                        result = await advance(1 + Math.floor(random() * 20));
+                    }
+                    else if (MOVE_KEYS.has(key) || roll < 0.35) {
+                        inputChanged();
+                        if (held.has(key)) {
+                            held.delete(key);
+                            steps.push({ release: key });
+                            await callSafe(page, "release", [key]);
+                        }
+                        else {
+                            held.add(key);
+                            steps.push({ press: key });
+                            await callSafe(page, "press", [key]);
+                        }
+                        // Mostly short holds; sometimes a long one, which is what walks into loops and softlocks.
+                        result = await advance(random() < 0.1 ? 120 + Math.floor(random() * 180) : 6 + Math.floor(random() * 50));
+                    }
+                    else {
+                        inputChanged();
+                        steps.push({ press: key });
+                        await callSafe(page, "press", [key]);
+                        result = await advance(1 + Math.floor(random() * 4));
+                        steps.push({ release: key });
+                        await callSafe(page, "release", [key]);
+                        inputChanged();
+                    }
+                    if (!result.ok) {
+                        // Give the dev tools a moment to explain and source-map the error.
+                        await page.waitForTimeout(250);
+                        const explained = (await callSafe(page, "errors", []));
+                        const state = (await callSafe(page, "state", []));
+                        findings.push({
+                            kind: "error",
+                            run,
+                            tick: state.ok ? state.value.tick : played,
+                            message: result.error,
+                            ...(explained.ok && explained.value.length ? { error: explained.value.at(-1) } : {}),
+                            repro: save("error"),
+                        });
+                        break;
+                    }
+                    // Stuck: input keeps arriving but the scene's inspect() state hasn't changed for a long time.
+                    const state = (await callSafe(page, "state", []));
+                    if (state.ok && state.value.state !== undefined && !stuckReported) {
+                        const now = JSON.stringify([state.value.scene, state.value.state]);
+                        if (now !== lastState) {
+                            lastState = now;
+                            changedAt = played;
+                        }
+                        else if (played - changedAt >= stuckSteps) {
+                            stuckReported = true;
+                            findings.push({
+                                kind: "stuck",
+                                run,
+                                tick: state.value.tick,
+                                message: `State unchanged for ${Math.round((played - changedAt) / 60)} s of input (scene "${state.value.scene ?? "?"}"). Possible softlock, or a screen that ignores these keys.`,
+                                repro: save("stuck"),
+                            });
+                        }
+                    }
+                }
+                totalSteps += played;
+            }
+            finally {
+                await page.close();
+            }
+        }
+    }
+    finally {
+        await browser.close();
+        await server.close();
+    }
+    const report = { seed, runs, steps: totalSteps, findings, durationMs: Date.now() - started };
+    writeFileSync(join(outDir, `fuzz-${seed}-report.json`), `${JSON.stringify(report, null, 2)}\n`);
+    return report;
+}
+//# sourceMappingURL=fuzz.js.map

package/dist/fuzz.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { AGENT_PATHS, type AgentStatus, DEV_SERVER_FILE, type DevServerInfo } from "./agent-link.js";
+export * from "./assets/index.js";
+export { CONFIG_FILES, type DebuffConfig, defineConfig, loadConfig, type ResolvedConfig, validatePlugins } from "./config.js";
+export { DEFAULT_FUZZ_KEYS, type FuzzFinding, type FuzzOptions, type FuzzReport, runFuzz } from "./fuzz.js";
+export { inspectProject } from "./inspect.js";
+export type * from "./plugin.js";
+export { TOOLING_API_VERSION } from "./plugin.js";
+export { type BuildReport, buildReport, DEV_TOKENS, type FileReport, formatReport } from "./report.js";
+export * from "./scenario/index.js";
+export { createDevServer, viteConfig } from "./vite.js";
+export { ASSETS_DIR, type DebuffViteOptions, debuff } from "./vite-plugin.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,WAAW,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrG,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,KAAK,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9H,OAAO,EAAE,iBAAiB,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC5G,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,mBAAmB,aAAa,CAAC;AACjC,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,KAAK,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACvG,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,11 @@
+export { AGENT_PATHS, DEV_SERVER_FILE } from "./agent-link.js";
+export * from "./assets/index.js";
+export { CONFIG_FILES, defineConfig, loadConfig, validatePlugins } from "./config.js";
+export { DEFAULT_FUZZ_KEYS, runFuzz } from "./fuzz.js";
+export { inspectProject } from "./inspect.js";
+export { TOOLING_API_VERSION } from "./plugin.js";
+export { buildReport, DEV_TOKENS, formatReport } from "./report.js";
+export * from "./scenario/index.js";
+export { createDevServer, viteConfig } from "./vite.js";
+export { ASSETS_DIR, debuff } from "./vite-plugin.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAoB,eAAe,EAAsB,MAAM,iBAAiB,CAAC;AACrG,cAAc,mBAAmB,CAAC;AAClC,OAAO,EAAE,YAAY,EAAqB,YAAY,EAAE,UAAU,EAAuB,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9H,OAAO,EAAE,iBAAiB,EAAuD,OAAO,EAAE,MAAM,WAAW,CAAC;AAC5G,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAoB,WAAW,EAAE,UAAU,EAAmB,YAAY,EAAE,MAAM,aAAa,CAAC;AACvG,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAE,UAAU,EAA0B,MAAM,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/inspect.d.ts

@@ -0,0 +1,35 @@
+/** JSON summary of a debuff project for agents and tools (`debuff inspect`, MCP `inspect_project`). */
+export declare function inspectProject(root: string): Promise<{
+    name: unknown;
+    debuff: string;
+    dependencies: {};
+    config: string | null;
+    plugins: {
+        name: string;
+        apiVersion: 1;
+        importers: {
+            name: string;
+            extensions: string[];
+            kind: string;
+        }[];
+        commands: string[];
+        scenarioSteps: string[];
+        vite: boolean;
+    }[];
+    assets: {
+        count: number;
+        bytes: number;
+        byId: Record<string, import("./plugin.js").CompiledEntry>;
+        unused: string[];
+        warnings: string[];
+    };
+    build: {
+        totals: Record<"asset" | "code" | "html" | "map" | "other", {
+            bytes: number;
+            gzip: number;
+            brotli: number;
+        }>;
+    } | null;
+    runtime: string;
+}>;
+//# sourceMappingURL=inspect.d.ts.map

package/dist/inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect.d.ts","sourceRoot":"","sources":["../src/inspect.ts"],"names":[],"mappings":"AAQA,uGAAuG;AACvG,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BhD"}

package/dist/inspect.js

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { compileAssets, findUnused } from "./assets/index.js";
+import { loadConfig } from "./config.js";
+import { buildReport } from "./report.js";
+const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+/** JSON summary of a debuff project for agents and tools (`debuff inspect`, MCP `inspect_project`). */
+export async function inspectProject(root) {
+    const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+    const config = await loadConfig(root);
+    const { manifest, warnings } = await compileAssets(root, { plugins: config.plugins, atlas: config.atlas });
+    const dist = join(root, "dist");
+    return {
+        name: pkg.name,
+        debuff: version,
+        dependencies: pkg.dependencies ?? {},
+        config: config.file ?? null,
+        plugins: config.plugins.map((pl) => ({
+            name: pl.name,
+            apiVersion: pl.apiVersion,
+            importers: (pl.assets ?? []).map((i) => ({ name: i.name, extensions: i.extensions, kind: "command" in i ? "command" : "function" })),
+            commands: (pl.commands ?? []).map((c) => `${pl.name}:${c.name}`),
+            scenarioSteps: (pl.scenarioSteps ?? []).map((s) => `${pl.name}:${s.name}`),
+            vite: Boolean(pl.vite),
+        })),
+        assets: {
+            count: Object.keys(manifest.assets).length,
+            bytes: Object.values(manifest.assets).reduce((n, a) => n + a.bytes, 0),
+            byId: manifest.assets,
+            unused: findUnused(root, manifest),
+            warnings,
+        },
+        build: existsSync(dist) ? { totals: buildReport(dist).totals } : null,
+        runtime: "Live params and scene state: window.__DEBUFF_DEV__ in the dev server, `debuff scenario`, or the debuff MCP game_* tools.",
+    };
+}
+//# sourceMappingURL=inspect.js.map

package/dist/inspect.js.map

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

package/dist/plugin.d.ts

@@ -0,0 +1,146 @@
+import type { PluginOption } from "vite";
+/** Manifest entry types the runtime loader understands. */
+export type AssetType = "image" | "json" | "audio" | "text" | "sheet";
+/** One frame of a sprite sheet, in source-image pixels. `duration` is in seconds. */
+export interface SheetFrame {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    duration?: number;
+}
+export interface SheetAnimation {
+    /** Indices into `frames`. */
+    frames: number[];
+    loop?: boolean;
+}
+/** A manifest entry as produced by an importer; the compiler adds `bytes` and `hash`. */
+export interface AssetEntry {
+    type: AssetType;
+    /** URL relative to the site root, e.g. "assets/hero.png". */
+    src: string;
+    group?: string;
+    /** Uniform sprite grid (from the `name@WxH.png` convention). */
+    grid?: {
+        frameWidth: number;
+        frameHeight: number;
+    };
+    /** Region of `src` holding this image, when it was packed into an atlas. */
+    rect?: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /** Explicit frames, for `sheet` entries. */
+    frames?: SheetFrame[];
+    animations?: Record<string, SheetAnimation>;
+}
+export interface CompiledEntry extends AssetEntry {
+    bytes: number;
+    hash: string;
+}
+/** What an importer is given. Serialised as JSON on stdin for command importers. */
+export interface SourceFile {
+    /** Absolute path on disk. */
+    path: string;
+    /** Path relative to `assets/`, forward slashes. */
+    rel: string;
+    /** Default asset id derived from the path (group prefix, no extension). */
+    id: string;
+    /** Preload group (first folder), if any. */
+    group?: string;
+    /** Lower-case extension including the dot, e.g. ".json". For multi-part matches, the matched suffix. */
+    ext: string;
+}
+/** A generated file, served in dev and emitted into the build under `assets/`. */
+export interface GeneratedFile {
+    /** Path relative to `assets/`, e.g. "hero.png". */
+    path: string;
+    contents: string;
+    encoding?: "utf8" | "base64";
+}
+/** What an importer returns. Command importers print this as JSON on stdout. */
+export interface ImportResult {
+    /** Manifest entries keyed by asset id. Entries without `src` bytes on disk must reference a generated file. */
+    assets: Record<string, AssetEntry>;
+    /** Files to serve and emit (atlases, transcoded audio…). Sources are never modified. */
+    outputs?: GeneratedFile[];
+    /** Other source files (relative to `assets/`) this importer handled, so built-ins skip them. */
+    consumes?: string[];
+    warnings?: string[];
+}
+interface ImporterBase {
+    /** Used in errors, cache keys and `debuff inspect`. */
+    name: string;
+    /** File suffixes this importer claims, matched case-insensitively against the end of the path, e.g. [".aseprite.json"]. */
+    extensions: string[];
+}
+/** Runs inside the CLI process. Must be a pure function of the file contents and options. */
+export interface FunctionImporter extends ImporterBase {
+    import(file: SourceFile): ImportResult | Promise<ImportResult>;
+}
+/** Runs an external program (any language): `SourceFile` JSON on stdin, `ImportResult` JSON on stdout. */
+export interface CommandImporter extends ImporterBase {
+    command: [string, ...string[]];
+}
+export type AssetImporter = FunctionImporter | CommandImporter;
+export interface CommandOption {
+    /** cac-style flags, e.g. "--out <dir>" or "-w, --watch". */
+    flags: string;
+    description: string;
+    default?: unknown;
+}
+export interface CommandContext {
+    /** Project root. */
+    root: string;
+    /** Positional arguments after the command name. */
+    args: string[];
+    /** Parsed options (camelCased). */
+    options: Record<string, unknown>;
+    /** Emit machine-readable output when true (`--json`). */
+    json: boolean;
+}
+/** A CLI command, exposed as `debuff <plugin>:<name>`. */
+export interface CommandDef {
+    /** kebab-case; the full command is `<plugin name>:<name>`. */
+    name: string;
+    description: string;
+    options?: CommandOption[];
+    /** Return an exit code (0 = success). */
+    run(ctx: CommandContext): number | Promise<number>;
+}
+/** What a scenario step handler can do in the running game. */
+export interface StepContext {
+    /** Call a `window.__DEBUFF_DEV__` method, e.g. `call("press", "Space")`. */
+    call<R = unknown>(method: string, ...args: unknown[]): Promise<R>;
+    /** Evaluate a function in the page (Playwright semantics). */
+    evaluate<R, A>(fn: (arg: A) => R | Promise<R>, arg: A): Promise<R>;
+}
+/** A scenario step type, used in JSON as `{ "<plugin>:<name>": value }`. */
+export interface StepDef<V = unknown> {
+    /** kebab-case; the step key is `<plugin name>:<name>`. */
+    name: string;
+    description: string;
+    /** JSON Schema for the step's value; merged into the scenario schema for editors and agents. */
+    schema: Record<string, unknown>;
+    /** Return a failure message, or undefined if the step passed. */
+    run(value: V, ctx: StepContext): string | undefined | Promise<string | undefined>;
+}
+/** Tooling plugin contract (ADR 0004). */
+export interface ToolingPlugin {
+    /** Unique kebab-case id. */
+    name: string;
+    /** Contract version this plugin targets. */
+    apiVersion: 1;
+    assets?: AssetImporter[];
+    /** CLI commands, namespaced as `debuff <name>:<command>`. */
+    commands?: CommandDef[];
+    /** Scenario step types, namespaced as `"<name>:<step>"`. */
+    scenarioSteps?: StepDef[];
+    /** Extra Vite plugins (escape hatch). */
+    vite?: PluginOption;
+}
+export declare const TOOLING_API_VERSION = 1;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

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

package/dist/plugin.js

@@ -0,0 +1,2 @@
+export const TOOLING_API_VERSION = 1;
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AA0JA,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC"}

package/dist/report.d.ts

@@ -0,0 +1,26 @@
+export interface FileReport {
+    path: string;
+    kind: "code" | "html" | "asset" | "map" | "other";
+    bytes: number;
+    gzip: number;
+    brotli: number;
+}
+export interface BuildReport {
+    dir: string;
+    files: FileReport[];
+    totals: Record<FileReport["kind"], {
+        bytes: number;
+        gzip: number;
+        brotli: number;
+    }>;
+    largestAsset: FileReport | undefined;
+    leaks: {
+        path: string;
+        token: string;
+    }[];
+}
+/** Tokens that only exist in dev builds. Kept short so false positives are unlikely. */
+export declare const DEV_TOKENS: string[];
+export declare function buildReport(dir: string): BuildReport;
+export declare function formatReport(r: BuildReport): string;
+//# sourceMappingURL=report.d.ts.map

package/dist/report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../src/report.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,GAAG,OAAO,CAAC;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACpF,YAAY,EAAE,UAAU,GAAG,SAAS,CAAC;IACrC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC1C;AAED,wFAAwF;AACxF,eAAO,MAAM,UAAU,UAAqB,CAAC;AAkB7C,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAyBpD;AAID,wBAAgB,YAAY,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,CA2BnD"}

package/dist/report.js

@@ -0,0 +1,80 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join, relative, sep } from "node:path";
+import { brotliCompressSync, gzipSync } from "node:zlib";
+import { lime, paint, pink, sky } from "create-debuff";
+import pc from "picocolors";
+/** Tokens that only exist in dev builds. Kept short so false positives are unlikely. */
+export const DEV_TOKENS = ["__DEBUFF_DEV__"];
+function walk(dir) {
+    return readdirSync(dir).flatMap((name) => {
+        const path = join(dir, name);
+        return statSync(path).isDirectory() ? walk(path) : [path];
+    });
+}
+function kindOf(path) {
+    const ext = extname(path);
+    if (ext === ".map")
+        return "map";
+    if (ext === ".js" || ext === ".mjs" || ext === ".css")
+        return "code";
+    if (ext === ".html")
+        return "html";
+    if (/\.(png|jpe?g|webp|gif|ogg|mp3|wav|m4a|json|txt|woff2?)$/.test(path))
+        return "asset";
+    return "other";
+}
+export function buildReport(dir) {
+    if (!existsSync(dir))
+        throw new Error(`No build output at ${dir}. Run \`debuff build\` first.`);
+    const files = [];
+    const leaks = [];
+    for (const file of walk(dir).sort()) {
+        if (basename(file).startsWith(".") || basename(file) === "debuff-report.json")
+            continue;
+        const data = readFileSync(file);
+        const path = relative(dir, file).split(sep).join("/");
+        const kind = kindOf(path);
+        files.push({ path, kind, bytes: data.length, gzip: gzipSync(data).length, brotli: brotliCompressSync(data).length });
+        if (kind === "code" || kind === "html") {
+            const text = data.toString("utf8");
+            for (const token of DEV_TOKENS)
+                if (text.includes(token))
+                    leaks.push({ path, token });
+        }
+    }
+    const zero = () => ({ bytes: 0, gzip: 0, brotli: 0 });
+    const totals = { code: zero(), html: zero(), asset: zero(), map: zero(), other: zero() };
+    for (const f of files) {
+        const t = totals[f.kind];
+        t.bytes += f.bytes;
+        t.gzip += f.gzip;
+        t.brotli += f.brotli;
+    }
+    const largestAsset = files.filter((f) => f.kind === "asset").sort((a, b) => b.bytes - a.bytes)[0];
+    return { dir, files, totals, largestAsset, leaks };
+}
+const kb = (n) => `${(n / 1024).toFixed(1)} kB`;
+export function formatReport(r) {
+    const w = Math.max(...r.files.map((f) => f.path.length), 4);
+    const kindColor = {
+        code: sky,
+        html: (s) => paint("violet", s),
+        asset: pink,
+        map: pc.dim,
+        other: pc.dim,
+    };
+    const lines = [pc.dim(`${"file".padEnd(w)}  ${"raw".padStart(9)}  ${"gzip".padStart(9)}  ${"brotli".padStart(9)}`)];
+    for (const f of r.files) {
+        lines.push(`${kindColor[f.kind](f.path.padEnd(w))}  ${pc.dim(kb(f.bytes).padStart(9))}  ${kb(f.gzip).padStart(9)}  ${pc.bold(kb(f.brotli).padStart(9))}`);
+    }
+    lines.push("");
+    for (const [kind, t] of Object.entries(r.totals)) {
+        if (t.bytes)
+            lines.push(`${kindColor[kind](kind.padEnd(6))} ${pc.bold(kb(t.brotli))} brotli  ${pc.dim(`${kb(t.gzip)} gzip · ${kb(t.bytes)} raw`)}`);
+    }
+    if (r.largestAsset)
+        lines.push(pc.dim(`largest asset: ${r.largestAsset.path} (${kb(r.largestAsset.bytes)})`));
+    lines.push(r.leaks.length ? pc.red(`✖ dev leaks: ${r.leaks.map((l) => `${l.token} in ${l.path}`).join(", ")}`) : lime("✔ dev boundary clean"));
+    return lines.join("\n");
+}
+//# sourceMappingURL=report.js.map