dungbeetle 0.1.1

package/dist/terminal/capture.js

@@ -0,0 +1,91 @@
+import { spawn } from "node:child_process";
+import { normalizeAnsiStream } from "./ansi.js";
+export async function captureTerminal(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const startedAt = performance.now();
+    const result = await runShellCommand({
+        command: options.command,
+        cwd,
+        timeoutMs: options.timeoutMs ?? 30_000
+    });
+    return {
+        kind: "terminal",
+        command: options.command,
+        cwd,
+        exitCode: result.exitCode,
+        signal: result.signal,
+        durationMs: Math.round(performance.now() - startedAt),
+        stdout: normalizeAnsiStream(result.stdout, options.maskRules),
+        stderr: normalizeAnsiStream(result.stderr, options.maskRules)
+    };
+}
+// Terminate the spawned shell and any commands it started. On POSIX the child
+// is a process-group leader (spawned `detached`), so signalling the negated PID
+// reaches the whole group; on Windows process groups work differently, so fall
+// back to a direct kill (this path is exercised by callers, not the timeout
+// test, which is skipped on win32).
+function killTree(child) {
+    if (process.platform === "win32" || child.pid === undefined) {
+        child.kill("SIGTERM");
+        return;
+    }
+    try {
+        process.kill(-child.pid, "SIGTERM");
+    }
+    catch {
+        // The group may already be gone (race with normal exit); signal the child
+        // directly as a best effort.
+        child.kill("SIGTERM");
+    }
+}
+export function runShellCommand(options) {
+    return new Promise((resolve, reject) => {
+        // `shell: true` means the command runs as a child of a shell process. On
+        // its own, `child.kill()` would only signal that shell, leaving the actual
+        // command (e.g. a long-running `node`) alive and holding the stdout/stderr
+        // pipes open — so `close` never fires until it finishes. Run the child in
+        // its own process group (`detached`) so a single signal to the group tears
+        // down the shell and everything it spawned.
+        const child = spawn(options.command, {
+            cwd: options.cwd,
+            shell: true,
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: process.platform !== "win32"
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const timeout = setTimeout(() => {
+            killTree(child);
+        }, options.timeoutMs);
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            reject(error);
+        });
+        child.on("close", (exitCode, signal) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            resolve({
+                stdout,
+                stderr,
+                exitCode,
+                signal
+            });
+        });
+    });
+}

package/dist/tty.d.ts

@@ -0,0 +1,72 @@
+export type WriteStream = NodeJS.WriteStream;
+/**
+ * Whether ANSI colour escapes should be emitted for the given stream.
+ *
+ * Honors the de-facto standards: `FORCE_COLOR` wins over everything, then
+ * `NO_COLOR` (presence disables, per the no-color.org spec), `TERM=dumb`, and
+ * finally whether the stream is an interactive TTY.
+ */
+export declare function colorEnabled(stream?: WriteStream): boolean;
+/**
+ * Whether unicode/emoji glyphs are safe to print.
+ *
+ * Non-Windows terminals handle unicode unless they are the bare Linux console.
+ * On Windows, only modern hosts (Windows Terminal, VS Code, ConEmu) render
+ * emoji reliably, so legacy `cmd.exe` / PowerShell consoles fall back to ASCII.
+ * `DUNGBEETLE_ASCII=1` forces ASCII everywhere for testing or troublesome setups.
+ */
+export declare function unicodeEnabled(): boolean;
+export type Palette = {
+    enabled: boolean;
+    bold(value: string): string;
+    dim(value: string): string;
+    red(value: string): string;
+    green(value: string): string;
+    yellow(value: string): string;
+    blue(value: string): string;
+    magenta(value: string): string;
+    cyan(value: string): string;
+    gray(value: string): string;
+};
+/** Build a palette whose functions are no-ops when colour is disabled. */
+export declare function makePalette(enabled: boolean): Palette;
+export type Symbols = {
+    passed: string;
+    failed: string;
+    missing: string;
+    updated: string;
+    error: string;
+    bullet: string;
+    arrow: string;
+    clock: string;
+};
+/** Status glyphs with an ASCII fallback for terminals without emoji. */
+export declare function makeSymbols(unicode: boolean): Symbols;
+/**
+ * A minimal loading spinner.
+ *
+ * It animates only on an interactive TTY; in CI, pipes, and dumb terminals it
+ * is completely silent so it never pollutes logs or report output. It writes
+ * to stderr by default to keep stdout free for JSON/HTML report paths.
+ */
+export declare class Spinner {
+    private readonly stream;
+    private readonly frames;
+    private readonly palette;
+    private readonly active;
+    private readonly intervalMs;
+    private timer;
+    private frame;
+    private text;
+    constructor(options?: {
+        stream?: WriteStream;
+        intervalMs?: number;
+    });
+    start(text: string): this;
+    setText(text: string): this;
+    /** Stop the spinner and clear its line, leaving nothing behind. */
+    stop(): this;
+    private render;
+}
+/** Format a millisecond duration as a short human string (e.g. `1.2s`). */
+export declare function formatDuration(ms: number): string;

package/dist/tty.js

@@ -0,0 +1,175 @@
+// Small, dependency-free terminal styling helpers.
+//
+// Everything here degrades gracefully so output stays readable in any
+// terminal — including Windows legacy consoles, dumb terminals, piped output,
+// and CI logs. Colour and unicode are detected independently: a terminal may
+// support ANSI colour but not render emoji well, so the two are gated apart.
+function readEnv(name) {
+    return process.env[name];
+}
+/**
+ * Whether ANSI colour escapes should be emitted for the given stream.
+ *
+ * Honors the de-facto standards: `FORCE_COLOR` wins over everything, then
+ * `NO_COLOR` (presence disables, per the no-color.org spec), `TERM=dumb`, and
+ * finally whether the stream is an interactive TTY.
+ */
+export function colorEnabled(stream = process.stdout) {
+    const force = readEnv("FORCE_COLOR");
+    if (force !== undefined) {
+        return force !== "0" && force !== "false" && force !== "";
+    }
+    if ("NO_COLOR" in process.env) {
+        return false;
+    }
+    if (readEnv("TERM") === "dumb") {
+        return false;
+    }
+    return Boolean(stream.isTTY);
+}
+/**
+ * Whether unicode/emoji glyphs are safe to print.
+ *
+ * Non-Windows terminals handle unicode unless they are the bare Linux console.
+ * On Windows, only modern hosts (Windows Terminal, VS Code, ConEmu) render
+ * emoji reliably, so legacy `cmd.exe` / PowerShell consoles fall back to ASCII.
+ * `DUNGBEETLE_ASCII=1` forces ASCII everywhere for testing or troublesome setups.
+ */
+export function unicodeEnabled() {
+    if (readEnv("DUNGBEETLE_ASCII") === "1") {
+        return false;
+    }
+    if (process.platform !== "win32") {
+        return readEnv("TERM") !== "linux";
+    }
+    return Boolean(readEnv("WT_SESSION") || readEnv("TERM_PROGRAM") || readEnv("ConEmuTask") || readEnv("TERM"));
+}
+const ANSI = {
+    reset: "",
+    bold: "",
+    dim: "",
+    red: "",
+    green: "",
+    yellow: "",
+    blue: "",
+    magenta: "",
+    cyan: "",
+    gray: ""
+};
+/** Build a palette whose functions are no-ops when colour is disabled. */
+export function makePalette(enabled) {
+    const wrap = (code) => (value) => enabled ? `${code}${value}${ANSI.reset}` : value;
+    return {
+        enabled,
+        bold: wrap(ANSI.bold),
+        dim: wrap(ANSI.dim),
+        red: wrap(ANSI.red),
+        green: wrap(ANSI.green),
+        yellow: wrap(ANSI.yellow),
+        blue: wrap(ANSI.blue),
+        magenta: wrap(ANSI.magenta),
+        cyan: wrap(ANSI.cyan),
+        gray: wrap(ANSI.gray)
+    };
+}
+/** Status glyphs with an ASCII fallback for terminals without emoji. */
+export function makeSymbols(unicode) {
+    if (unicode) {
+        return {
+            passed: "✅",
+            failed: "❌",
+            missing: "⚠️",
+            updated: "📝",
+            error: "🛑",
+            bullet: "•",
+            arrow: "›",
+            clock: "⏱"
+        };
+    }
+    return {
+        passed: "[pass]",
+        failed: "[fail]",
+        missing: "[miss]",
+        updated: "[upd]",
+        error: "[err]",
+        bullet: "-",
+        arrow: ">",
+        clock: ""
+    };
+}
+const SPINNER_FRAMES = {
+    unicode: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+    ascii: ["-", "\\", "|", "/"]
+};
+const CLEAR_LINE = "\r";
+/**
+ * A minimal loading spinner.
+ *
+ * It animates only on an interactive TTY; in CI, pipes, and dumb terminals it
+ * is completely silent so it never pollutes logs or report output. It writes
+ * to stderr by default to keep stdout free for JSON/HTML report paths.
+ */
+export class Spinner {
+    stream;
+    frames;
+    palette;
+    active;
+    intervalMs;
+    timer;
+    frame = 0;
+    text = "";
+    constructor(options = {}) {
+        this.stream = options.stream ?? process.stderr;
+        this.intervalMs = options.intervalMs ?? 80;
+        const unicode = unicodeEnabled();
+        this.frames = unicode ? SPINNER_FRAMES.unicode : SPINNER_FRAMES.ascii;
+        this.palette = makePalette(colorEnabled(this.stream));
+        this.active = Boolean(this.stream.isTTY);
+    }
+    start(text) {
+        this.text = text;
+        if (!this.active) {
+            return this;
+        }
+        this.render();
+        this.timer = setInterval(() => {
+            this.frame = (this.frame + 1) % this.frames.length;
+            this.render();
+        }, this.intervalMs);
+        // Don't keep the event loop alive solely for the spinner.
+        this.timer.unref?.();
+        return this;
+    }
+    setText(text) {
+        this.text = text;
+        if (this.active && this.timer) {
+            this.render();
+        }
+        return this;
+    }
+    /** Stop the spinner and clear its line, leaving nothing behind. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (this.active) {
+            this.stream.write(CLEAR_LINE);
+        }
+        return this;
+    }
+    render() {
+        const glyph = this.palette.cyan(this.frames[this.frame] ?? "");
+        this.stream.write(`${CLEAR_LINE}${glyph} ${this.text}`);
+    }
+}
+/** Format a millisecond duration as a short human string (e.g. `1.2s`). */
+export function formatDuration(ms) {
+    if (!Number.isFinite(ms) || ms < 0) {
+        return "0ms";
+    }
+    if (ms < 1000) {
+        return `${Math.round(ms)}ms`;
+    }
+    return `${(ms / 1000).toFixed(1)}s`;
+}

package/dist/web/domSnapshot.d.ts

@@ -0,0 +1,27 @@
+import type { MaskRule } from "../config.js";
+export type DomSnapshotNode = {
+    type: "element";
+    tagName: string;
+    attributes: Record<string, string>;
+    children: DomSnapshotNode[];
+} | {
+    type: "text";
+    value: string;
+};
+export type DomSnapshot = {
+    kind: "web";
+    source: string;
+    capturedAt: "masked";
+    root: DomSnapshotNode[];
+};
+export type WebFileSnapshot = DomSnapshot & {
+    driver: "file";
+    screenshot: {
+        mimeType: "image/png";
+        data: string;
+    };
+};
+export declare function createDomSnapshot(html: string, options: {
+    source: string;
+    maskRules?: MaskRule[];
+}): DomSnapshot;

package/dist/web/domSnapshot.js

@@ -0,0 +1,55 @@
+import { parse } from "parse5";
+import { applyMaskRules, collapseWhitespace } from "../normalization.js";
+export function createDomSnapshot(html, options) {
+    const parsed = parse(html);
+    return {
+        kind: "web",
+        source: options.source,
+        capturedAt: "masked",
+        root: snapshotChildren(parsed.childNodes ?? [], options.maskRules ?? [])
+    };
+}
+function snapshotChildren(nodes, maskRules) {
+    return nodes
+        .map((node) => snapshotNode(node, maskRules))
+        .filter((node) => node !== null);
+}
+function snapshotNode(node, maskRules) {
+    if (node.nodeName === "#text") {
+        const value = collapseWhitespace(applyMaskRules(node.value ?? "", maskRules));
+        if (!value) {
+            return null;
+        }
+        return {
+            type: "text",
+            value
+        };
+    }
+    if (node.nodeName?.startsWith("#")) {
+        return null;
+    }
+    if (!node.tagName) {
+        return {
+            type: "element",
+            tagName: node.nodeName ?? "document",
+            attributes: {},
+            children: snapshotChildren(node.childNodes ?? [], maskRules)
+        };
+    }
+    return {
+        type: "element",
+        tagName: node.tagName,
+        attributes: snapshotAttributes(node.attrs ?? [], maskRules),
+        children: snapshotChildren(node.childNodes ?? [], maskRules)
+    };
+}
+// Attributes that are volatile by construction and would make every capture of
+// a CSP-protected page diff against itself: a nonce is a fresh random value per
+// response, exactly the class of dynamic content masks exist for.
+const VOLATILE_ATTRIBUTES = new Set(["nonce"]);
+function snapshotAttributes(attrs, maskRules) {
+    return Object.fromEntries(attrs
+        .filter((attr) => !VOLATILE_ATTRIBUTES.has(attr.name.toLowerCase()))
+        .map((attr) => [attr.name, applyMaskRules(attr.value, maskRules)])
+        .sort(([left], [right]) => left.localeCompare(right)));
+}

package/dist/web/playwrightCapture.d.ts

@@ -0,0 +1,16 @@
+import type { CaptureTarget, MaskRule } from "../config.js";
+import { type DomSnapshot } from "./domSnapshot.js";
+export type PlaywrightWebSnapshot = DomSnapshot & {
+    driver: "playwright";
+    accessibility?: unknown;
+    screenshot?: {
+        mimeType: "image/png";
+        data: string;
+    };
+};
+export declare function capturePlaywrightWeb(target: Extract<CaptureTarget, {
+    kind: "web";
+}>, options: {
+    maskRules: MaskRule[];
+    timeoutMs: number;
+}): Promise<PlaywrightWebSnapshot>;

package/dist/web/playwrightCapture.js

@@ -0,0 +1,64 @@
+import { createDomSnapshot } from "./domSnapshot.js";
+export async function capturePlaywrightWeb(target, options) {
+    if (!target.url) {
+        throw new Error(`Playwright web target "${target.name}" requires a url.`);
+    }
+    const playwright = await import("playwright-core");
+    const browser = await launchBrowser(playwright, target);
+    try {
+        const context = await browser.newContext({
+            viewport: target.viewport ?? {
+                width: 1280,
+                height: 720
+            }
+        });
+        const page = await context.newPage();
+        await page.goto(target.url, {
+            waitUntil: "networkidle",
+            timeout: target.timeoutMs ?? options.timeoutMs
+        });
+        const dom = createDomSnapshot(await page.content(), {
+            source: target.url,
+            maskRules: options.maskRules
+        });
+        dom.driver = "playwright";
+        if (target.accessibility) {
+            dom.accessibility = await captureAccessibility(page);
+        }
+        if (target.screenshot) {
+            dom.screenshot = {
+                mimeType: "image/png",
+                data: (await page.screenshot({
+                    fullPage: true,
+                    type: "png"
+                })).toString("base64")
+            };
+        }
+        await context.close();
+        return dom;
+    }
+    finally {
+        await browser.close();
+    }
+}
+async function launchBrowser(playwright, target) {
+    const executablePath = target.browser?.executablePath ?? process.env.DUNGBEETLE_CHROMIUM_EXECUTABLE_PATH;
+    return playwright.chromium.launch({
+        channel: target.browser?.channel,
+        executablePath,
+        headless: true
+    });
+}
+async function captureAccessibility(page) {
+    const pageLike = page;
+    if (pageLike.accessibility?.snapshot) {
+        return pageLike.accessibility.snapshot({
+            interestingOnly: false
+        });
+    }
+    const body = pageLike.locator?.("body");
+    if (body?.ariaSnapshot) {
+        return body.ariaSnapshot();
+    }
+    return null;
+}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "dungbeetle",
+  "version": "0.1.1",
+  "description": "Web, desktop, terminal, and eventually anything — zero adoption cost and runs anywhere.",
+  "type": "module",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "bin": {
+    "dungbeetle": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "npm run lint && npm run typecheck && npm test",
+    "lint": "biome check src test",
+    "lint:fix": "biome check --write src test",
+    "format": "biome format --write src test",
+    "format:check": "biome format src test",
+    "check:terms": "bash scripts/check-banned-terms.sh",
+    "coverage": "vitest run --coverage",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run check",
+    "dev": "tsx src/index.ts",
+    "p1:ci": "tsx src/index.ts ci --config examples/demo/dungbeetle.config.json --json .dungbeetle/p1/ci-report.json --html .dungbeetle/p1/ci-report.html",
+    "p1:ci:json": "tsx src/index.ts ci --config examples/demo/dungbeetle.config.json --json .dungbeetle/p1/ci-report.json --json-only",
+    "p1:doctor": "tsx src/index.ts doctor --config examples/demo/dungbeetle.config.json --json .dungbeetle/p1/doctor-report.json",
+    "p1:doctor:playwright": "tsx src/index.ts doctor --config examples/p1/playwright/dungbeetle.config.json --json .dungbeetle/p1/playwright-doctor-report.json",
+    "p1:test": "tsx src/index.ts test --config examples/demo/dungbeetle.config.json --json .dungbeetle/p1/test-report.json --html .dungbeetle/p1/test-report.html",
+    "p1:update": "tsx src/index.ts update --config examples/demo/dungbeetle.config.json --json .dungbeetle/p1/update-report.json --html .dungbeetle/p1/update-report.html",
+    "game:doctor": "tsx src/index.ts doctor --config examples/game/dungbeetle.config.json",
+    "game:ci": "tsx src/index.ts ci --config examples/game/dungbeetle.config.json",
+    "game:update": "tsx src/index.ts update --config examples/game/dungbeetle.config.json",
+    "game:flake": "tsx src/index.ts flake --config examples/game/dungbeetle.config.json --repeat 5",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DungbeetleTech/client.git"
+  },
+  "keywords": [
+    "snapshot-testing",
+    "visual-regression",
+    "terminal",
+    "dom",
+    "testing"
+  ],
+  "author": "DungbeetleDev <tech@dungbeetle.dev>",
+  "license": "SEE LICENSE IN LICENSE",
+  "bugs": {
+    "url": "https://github.com/DungbeetleTech/client/issues"
+  },
+  "homepage": "https://github.com/DungbeetleTech/client#readme",
+  "dependencies": {
+    "commander": "^15.0.0",
+    "parse5": "^8.0.1",
+    "playwright-core": "^1.61.1",
+    "pngjs": "^7.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.1",
+    "@types/node": "^26.0.1",
+    "@types/pngjs": "^6.0.5",
+    "@vitest/coverage-v8": "^4.1.9",
+    "esbuild": "^0.28.1",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}