dungbeetle 0.1.1

package/dist/cloud.js

@@ -0,0 +1,334 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { isErrno, isRecord } from "./guards.js";
+import { BRAND_NAME } from "./brand.js";
+// The API major version this CLI speaks. The server echoes its own version in the
+// `Dungbeetle-Api-Version` header on every API response; a mismatch means the CLI and
+// server are incompatible, so we fail with a clear message rather than confusing
+// 404s or validation errors. Bump in lockstep with a breaking server change.
+const CLIENT_API_VERSION = 1;
+const API_BASE = `/api/v${CLIENT_API_VERSION}`;
+function assertApiVersion(response, origin) {
+    const serverVersion = response.headers.get("dungbeetle-api-version");
+    if (serverVersion !== null && serverVersion !== String(CLIENT_API_VERSION)) {
+        throw new Error(`${BRAND_NAME} API version mismatch: this CLI speaks v${CLIENT_API_VERSION} but ${origin} ` +
+            `speaks v${serverVersion}. Upgrade the CLI or the server so they match.`);
+    }
+}
+// Upload a JSON report (as written by `dungbeetle test`/`ci`) to a Dungbeetle server.
+// Keeps "how tests are written" unchanged: this consumes the existing report
+// artifact rather than re-running capture.
+export async function pushReport(options) {
+    let report;
+    try {
+        report = JSON.parse(await readFile(options.reportPath, "utf8"));
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            throw new Error(`Report not found at ${options.reportPath}; run \`dungbeetle test\` first.`);
+        }
+        throw new Error(`Could not read report at ${options.reportPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    // Upload screenshots as discrete artifacts so the run POST carries refs, not
+    // base64. Best-effort: on failure the report keeps its inline screenshots and
+    // the server offloads them on ingest (no hard cutover).
+    await offloadScreenshots(report, options);
+    const body = await postJson(options.serverUrl, `${API_BASE}/runs`, options, {
+        report,
+        branch: options.branch,
+        commit: options.commit
+    });
+    // Validate the wire shape before handing it back: a malformed but 2xx response
+    // (e.g. an HTML error page) would otherwise surface as a confusing TypeError
+    // when a caller reads a field.
+    const run = isRecord(body) ? body.run : undefined;
+    if (!isRecord(run) ||
+        typeof run.id !== "string" ||
+        typeof run.repositoryId !== "string" ||
+        typeof run.status !== "string" ||
+        typeof run.url !== "string" ||
+        !isRecord(run.counts)) {
+        throw new Error("Server response did not include a valid run.");
+    }
+    return {
+        id: run.id,
+        repositoryId: run.repositoryId,
+        status: run.status,
+        counts: run.counts,
+        url: run.url
+    };
+}
+// Roles whose screenshot bytes are offloaded out of the report.
+const SCREENSHOT_ROLES = ["baseline", "candidate", "diff"];
+// Move each result's inline base64 screenshots into content-addressed artifacts:
+// probe which digests the server lacks, upload only those, then rewrite the
+// report's results to reference them by id. Mutates `report` in place — but only
+// after every upload succeeds, so a failure leaves the inline bytes untouched for
+// the server to offload instead. Unchanged screenshots upload zero bytes.
+async function offloadScreenshots(report, options) {
+    if (!isRecord(report) || !Array.isArray(report.results)) {
+        return;
+    }
+    const artifacts = new Map();
+    const plans = [];
+    const namedPlans = [];
+    const collectRefs = (shot) => {
+        const refs = {};
+        for (const role of SCREENSHOT_ROLES) {
+            const encoded = shot[role];
+            if (typeof encoded !== "string" || encoded.length === 0) {
+                continue;
+            }
+            const buf = Buffer.from(encoded, "base64");
+            if (buf.length === 0) {
+                continue;
+            }
+            const digest = createHash("sha256").update(buf).digest("hex");
+            if (!artifacts.has(digest)) {
+                artifacts.set(digest, buf);
+            }
+            refs[role] = digest;
+        }
+        return refs;
+    };
+    for (const result of report.results) {
+        if (!isRecord(result)) {
+            continue;
+        }
+        if (isRecord(result.screenshot)) {
+            const refs = collectRefs(result.screenshot);
+            if (Object.keys(refs).length > 0) {
+                plans.push({ result, refs });
+            }
+        }
+        // Named per-marker screenshots (game targets) offload the same way, one
+        // ref set per marker.
+        if (isRecord(result.screenshots)) {
+            const refsByMarker = {};
+            for (const [marker, shot] of Object.entries(result.screenshots)) {
+                if (!isRecord(shot)) {
+                    continue;
+                }
+                const refs = collectRefs(shot);
+                if (Object.keys(refs).length > 0) {
+                    refsByMarker[marker] = refs;
+                }
+            }
+            if (Object.keys(refsByMarker).length > 0) {
+                namedPlans.push({ result, refs: refsByMarker });
+            }
+        }
+    }
+    if (artifacts.size === 0) {
+        return;
+    }
+    const digests = [...artifacts.keys()];
+    try {
+        const probe = (await postJson(options.serverUrl, `${API_BASE}/screenshots/probe`, options, {
+            digests
+        }));
+        const missing = new Set(Array.isArray(probe.missing)
+            ? probe.missing.filter((d) => typeof d === "string")
+            : digests);
+        for (const digest of digests) {
+            if (missing.has(digest)) {
+                await putArtifact(options, digest, artifacts.get(digest));
+            }
+        }
+    }
+    catch (error) {
+        // Leave inline screenshots in place; the server still offloads them on ingest.
+        process.stderr.write(`warning: screenshot pre-upload failed (${error instanceof Error ? error.message : String(error)}); sending them inline instead.\n`);
+        return;
+    }
+    // All artifacts are stored — swap inline bytes for refs.
+    for (const { result, refs } of plans) {
+        result.screenshotRefs = refs;
+        delete result.screenshot;
+    }
+    for (const { result, refs } of namedPlans) {
+        result.screenshotsRefs = refs;
+        delete result.screenshots;
+    }
+}
+// Upload local baseline snapshots (and any screenshot artifact) to the server,
+// which versions them. Sends the snapshot file verbatim so its digest is stable.
+export async function pushBaselines(options) {
+    const uploaded = [];
+    for (const source of options.baselines) {
+        const snapshot = await readBaselineSnapshot(source);
+        const screenshot = await readScreenshot(source.screenshotPath);
+        const body = await postJson(options.serverUrl, `${API_BASE}/baselines`, options, {
+            target: source.target,
+            kind: source.kind,
+            snapshot,
+            screenshot
+        });
+        if (!isRecord(body) || !isRecord(body.baseline) || typeof body.baseline.version !== "number") {
+            throw new Error(`Server response for baseline "${source.target}" was malformed (missing baseline.version).`);
+        }
+        uploaded.push({
+            target: source.target,
+            version: body.baseline.version,
+            deduped: body.deduped === true
+        });
+    }
+    return uploaded;
+}
+// Client credentials are sent as HTTP Basic, so over plaintext http:// they are
+// exposed to anyone on-path. Warn loudly for non-loopback http targets; loopback
+// (local dev) stays quiet. Localhost over http is fine; a remote http server is
+// a real credential-exposure risk that deserves a heads-up.
+function warnIfInsecure(endpoint) {
+    if (endpoint.protocol === "https:") {
+        return;
+    }
+    const host = endpoint.hostname;
+    const isLoopback = host === "localhost" || host === "127.0.0.1" || host === "::1";
+    if (!isLoopback) {
+        process.stderr.write(`warning: sending client credentials over plaintext ${endpoint.protocol}// to ${endpoint.host}. ` +
+            `Use https:// so they are not exposed on the network.\n`);
+    }
+}
+async function readBaselineSnapshot(source) {
+    try {
+        return await readFile(source.snapshotPath, "utf8");
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            throw new Error(`No baseline for "${source.target}" at ${source.snapshotPath}; run \`dungbeetle update\` first.`);
+        }
+        throw error;
+    }
+}
+async function readScreenshot(screenshotPath) {
+    if (!screenshotPath) {
+        return undefined;
+    }
+    try {
+        return (await readFile(screenshotPath)).toString("base64");
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function basicAuthHeader(credentials) {
+    const basic = Buffer.from(`${credentials.clientId}:${credentials.clientSecret}`, "utf8").toString("base64");
+    return `Basic ${basic}`;
+}
+async function postJson(serverUrl, pathname, credentials, body) {
+    const endpoint = new URL(pathname, serverUrl);
+    warnIfInsecure(endpoint);
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: basicAuthHeader(credentials)
+            },
+            body: JSON.stringify(body)
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not reach ${BRAND_NAME} server at ${endpoint.origin}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    assertApiVersion(response, endpoint.origin);
+    if (!response.ok) {
+        const detail = await safeErrorMessage(response);
+        throw new Error(`Upload failed (HTTP ${response.status})${detail ? `: ${detail}` : ""}.`);
+    }
+    return readJsonCapped(response);
+}
+// Share a capture anonymously: POST the report to the public /anon/runs endpoint
+// (no credentials, not API-versioned) and return the public web link. Deliberately
+// separate from pushReport — no auth header, no version handshake.
+export async function pushAnonReport(options) {
+    const endpoint = new URL("/anon/runs", options.serverUrl);
+    warnIfInsecure(endpoint);
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({ report: options.report })
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not reach ${BRAND_NAME} server at ${endpoint.origin}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok) {
+        const detail = await safeErrorMessage(response);
+        throw new Error(`Upload failed (HTTP ${response.status})${detail ? `: ${detail}` : ""}.`);
+    }
+    const body = await readJsonCapped(response);
+    const run = isRecord(body) ? body.run : undefined;
+    if (!isRecord(run) || typeof run.id !== "string" || typeof run.url !== "string") {
+        throw new Error("Server response did not include a valid anonymous run.");
+    }
+    return { id: run.id, url: run.url };
+}
+// Upload one screenshot artifact as raw bytes, content-addressed by `digest`.
+async function putArtifact(options, digest, data) {
+    const endpoint = new URL(`${API_BASE}/screenshots/${digest}`, options.serverUrl);
+    let response;
+    try {
+        response = await fetch(endpoint, {
+            method: "PUT",
+            headers: {
+                "content-type": "application/octet-stream",
+                authorization: basicAuthHeader(options)
+            },
+            body: new Uint8Array(data)
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not reach ${BRAND_NAME} server at ${endpoint.origin}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    assertApiVersion(response, endpoint.origin);
+    if (!response.ok) {
+        const detail = await safeErrorMessage(response);
+        throw new Error(`Screenshot upload failed (HTTP ${response.status})${detail ? `: ${detail}` : ""}.`);
+    }
+}
+// The CLI can be pointed at any server, so cap the response body before parsing:
+// a malicious or compromised endpoint could otherwise stream an unbounded body
+// and exhaust memory. Run metadata responses are a few KB; 8 MiB is generous.
+const MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+async function readJsonCapped(response) {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
+        throw new Error("Server response exceeded the maximum allowed size.");
+    }
+    const reader = response.body?.getReader();
+    if (!reader) {
+        return JSON.parse(await response.text());
+    }
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        total += value.length;
+        if (total > MAX_RESPONSE_BYTES) {
+            await reader.cancel();
+            throw new Error("Server response exceeded the maximum allowed size.");
+        }
+        chunks.push(value);
+    }
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+async function safeErrorMessage(response) {
+    try {
+        const body = (await readJsonCapped(response));
+        return isRecord(body) && typeof body.error === "string" ? body.error : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/compare/shared.d.ts

@@ -0,0 +1,42 @@
+import type { CaptureTarget, ComparisonConfig } from "../config.js";
+import type { CanonicalSnapshot, CanonicalWeb } from "../snapshot.js";
+import { type DecodedImage, type PixelDiffResult, type PixelTolerance } from "../diff/pixel.js";
+import type { DomSnapshotNode } from "../web/domSnapshot.js";
+export type ScreenshotImages = {
+    baseline: DecodedImage;
+    candidate: DecodedImage;
+};
+export type SnapshotComparison = {
+    equal: boolean;
+    rendered: string;
+    pixel?: PixelDiffResult;
+    screenshotImages?: ScreenshotImages;
+    screenshotImagesByMarker?: Record<string, ScreenshotImages>;
+};
+export type CompareOptions = {
+    comparison: ComparisonConfig;
+    target?: CaptureTarget;
+    baselineScreenshot?: Buffer;
+    candidateScreenshot?: Buffer;
+    baselineScreenshots?: Record<string, Buffer>;
+    candidateScreenshots?: Record<string, Buffer>;
+};
+export declare function coerceSnapshot<T extends CanonicalSnapshot>(value: unknown): T;
+export declare function compareScreenshot(baseline: CanonicalWeb, candidate: CanonicalWeb, options: CompareOptions, tolerance?: PixelTolerance): ScreenshotPairComparison;
+export type ScreenshotPairComparison = {
+    line?: string;
+    pixel?: PixelDiffResult;
+    images?: ScreenshotImages;
+};
+export declare function compareScreenshotPair(baselineDigest: string | undefined, candidateDigest: string | undefined, baselineImage: Buffer | undefined, candidateImage: Buffer | undefined, tolerance: PixelTolerance, label: string): ScreenshotPairComparison;
+export declare function compareStream(name: string, baseline: unknown, candidate: unknown, options: CompareOptions): string | undefined;
+export declare function a11yToDomNode(value: unknown): DomSnapshotNode;
+export declare function renderPerformanceChange(change: {
+    path: string;
+    before: unknown;
+    after: unknown;
+}): string;
+export declare function asNodes(value: unknown): DomSnapshotNode[];
+export declare function digestOf(value: unknown): string | undefined;
+export declare function textOf(value: unknown): string;
+export declare function render(value: unknown): string;

package/dist/compare/shared.js

@@ -0,0 +1,115 @@
+import { isRecord } from "../guards.js";
+import { structuralChanges } from "../diff/structural.js";
+import { diffWords, renderInline } from "../diff/text.js";
+import { decodePng, diffImages } from "../diff/pixel.js";
+// One centralized, invariant-documented narrowing: callers reach this only after
+// `snapshotKind` has confirmed the discriminant, so the assertion is safe. The
+// target type is inferred from the comparer's parameter, so there are no scattered
+// `as Record<string, unknown>` casts at the call sites.
+export function coerceSnapshot(value) {
+    return value;
+}
+export function compareScreenshot(baseline, candidate, options, 
+// Per-target tolerance override (web targets); defaults to the global one.
+tolerance = options.comparison.pixelTolerance) {
+    return compareScreenshotPair(digestOf(baseline.screenshot), digestOf(candidate.screenshot), options.baselineScreenshot, options.candidateScreenshot, tolerance, "screenshot");
+}
+// The digest-then-pixels comparison shared by every screenshot-carrying kind:
+// equal digests are free, differing digests fall back to a tolerant pixel diff
+// when the actual images are available. `label` names the screenshot in the
+// rendered line ("screenshot" for web, "screenshot[marker]" for game).
+export function compareScreenshotPair(baselineDigest, candidateDigest, baselineImage, candidateImage, tolerance, label) {
+    if (!baselineDigest && !candidateDigest) {
+        return {};
+    }
+    if (Boolean(baselineDigest) !== Boolean(candidateDigest)) {
+        return { line: candidateDigest ? `+ ${label} added` : `- ${label} removed` };
+    }
+    if (baselineDigest === candidateDigest) {
+        return {};
+    }
+    if (baselineImage && candidateImage) {
+        const images = {
+            baseline: decodePng(baselineImage),
+            candidate: decodePng(candidateImage)
+        };
+        const pixel = diffImages(images.baseline, images.candidate, tolerance);
+        if (pixel.withinTolerance) {
+            return { pixel, images };
+        }
+        const summary = pixel.dimensionsMatch
+            ? `${pixel.changedPixels}/${pixel.totalPixels} pixels changed (${(pixel.changedRatio * 100).toFixed(2)}%)`
+            : `dimensions changed to ${pixel.width}x${pixel.height}`;
+        return { line: `~ ${label}: ${summary}`, pixel, images };
+    }
+    return { line: `~ ${label} changed (no baseline image available for pixel diff)` };
+}
+export function compareStream(name, baseline, candidate, options) {
+    const structural = structuralChanges(baseline, candidate, {
+        numericTolerance: options.comparison.numericTolerance
+    });
+    if (structural.length === 0) {
+        return undefined;
+    }
+    const baselineText = textOf(baseline);
+    const candidateText = textOf(candidate);
+    if (baselineText !== candidateText) {
+        return `~ ${name}: ${renderInline(diffWords(baselineText, candidateText))}`;
+    }
+    // Text matched but styling/segments differ.
+    return `~ ${name} styling changed`;
+}
+// Desktop accessibility trees reuse the structural DOM tree diff: each a11y
+// node maps to an element whose tag is the role and whose attributes carry the
+// name/value/description/state. Alignment is by role, so a renamed control
+// surfaces as a changed @name rather than a remove + add.
+export function a11yToDomNode(value) {
+    const node = isRecord(value) ? value : {};
+    const attributes = {};
+    if (typeof node.name === "string") {
+        attributes.name = node.name;
+    }
+    if (typeof node.value === "string") {
+        attributes.value = node.value;
+    }
+    if (typeof node.description === "string") {
+        attributes.description = node.description;
+    }
+    if (Array.isArray(node.state) && node.state.length > 0) {
+        attributes.state = node.state.filter((flag) => typeof flag === "string").join(",");
+    }
+    return {
+        type: "element",
+        tagName: typeof node.role === "string" ? node.role : "unknown",
+        attributes,
+        children: Array.isArray(node.children) ? node.children.map(a11yToDomNode) : []
+    };
+}
+export function renderPerformanceChange(change) {
+    const metric = change.path.replace(/^\$\.(metrics\.)?/, "");
+    if (typeof change.before === "number" && typeof change.after === "number") {
+        const delta = percentDelta(change.before, change.after);
+        return `~ ${metric}: ${change.before} → ${change.after}${delta}`;
+    }
+    return `~ ${metric}: ${render(change.before)} → ${render(change.after)}`;
+}
+function percentDelta(before, after) {
+    if (before === 0) {
+        return after === 0 ? "" : " (new)";
+    }
+    const change = ((after - before) / Math.abs(before)) * 100;
+    const sign = change >= 0 ? "+" : "";
+    return ` (${sign}${change.toFixed(1)}%)`;
+}
+export function asNodes(value) {
+    return Array.isArray(value) ? value : [];
+}
+export function digestOf(value) {
+    return isRecord(value) && typeof value.sha256 === "string" ? value.sha256 : undefined;
+}
+export function textOf(value) {
+    return isRecord(value) && typeof value.text === "string" ? value.text : "";
+}
+export function render(value) {
+    return typeof value === "string" ? `"${value}"` : JSON.stringify(value);
+}

package/dist/compare.d.ts

@@ -0,0 +1,3 @@
+import { type CompareOptions, type SnapshotComparison } from "./compare/shared.js";
+export type { CompareOptions, ScreenshotImages, SnapshotComparison } from "./compare/shared.js";
+export declare function compareSnapshots(baseline: unknown, candidate: unknown, options: CompareOptions): SnapshotComparison;

package/dist/compare.js

@@ -0,0 +1,33 @@
+import { captureTypes } from "./captures/registry.js";
+import { render } from "./compare/shared.js";
+import { structuralChanges } from "./diff/structural.js";
+import { snapshotKind } from "./snapshot.js";
+// Top-level, snapshot-aware comparison used by the runner. Narrows both sides to
+// the canonical snapshot union once via `snapshotKind`, then routes to the
+// per-kind comparer in the registry — producing a readable, semantic diff
+// instead of a raw JSON line diff.
+export function compareSnapshots(baseline, candidate, options) {
+    const baselineKind = snapshotKind(baseline);
+    const candidateKind = snapshotKind(candidate);
+    // Both sides are the same known capture type → typed, per-kind comparison.
+    if (baselineKind && baselineKind === candidateKind) {
+        return captureTypes[baselineKind].compare(baseline, candidate, options);
+    }
+    // A target that switched capture type (e.g. terminal → web) is a meaningful change
+    // in its own right, not a noisy field-by-field structural diff.
+    if (baselineKind && candidateKind && baselineKind !== candidateKind) {
+        return { equal: false, rendered: `~ kind: ${baselineKind} → ${candidateKind}` };
+    }
+    return compareGeneric(baseline, candidate, options);
+}
+function compareGeneric(baseline, candidate, options) {
+    const changes = structuralChanges(baseline, candidate, {
+        numericTolerance: options.comparison.numericTolerance
+    });
+    return {
+        equal: changes.length === 0,
+        rendered: changes
+            .map((change) => `~ ${change.path}: ${render(change.before)} → ${render(change.after)}`)
+            .join("\n")
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,146 @@
+import type { NumericTolerance } from "./diff/numeric.js";
+import type { PixelTolerance } from "./diff/pixel.js";
+export type MaskRule = {
+    name: string;
+    pattern: string;
+    replacement: string;
+};
+export type CaptureTarget = {
+    kind: "api";
+    name: string;
+    url: string;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    query?: string;
+    variables?: Record<string, unknown>;
+    includeHeaders?: string[];
+    timeoutMs?: number;
+} | {
+    kind: "terminal";
+    name: string;
+    command: string;
+    cwd?: string;
+    timeoutMs?: number;
+} | {
+    kind: "check";
+    name: string;
+    tool: string;
+    command?: string;
+    output?: string;
+    cwd?: string;
+    timeoutMs?: number;
+} | {
+    kind: "web";
+    name: string;
+    driver?: "fetch" | "playwright";
+    url?: string;
+    html?: string;
+    screenshotFile?: string;
+    screenshotMode?: "strict" | "advisory";
+    pixelTolerance?: {
+        maxChangedRatio?: number;
+        perChannelThreshold?: number;
+    };
+    accessibility?: boolean;
+    screenshot?: boolean;
+    browser?: {
+        channel?: string;
+        executablePath?: string;
+    };
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    timeoutMs?: number;
+} | {
+    kind: "performance";
+    name: string;
+    tool?: string;
+    script?: string;
+    command?: string;
+    summary?: string;
+    metrics?: string[];
+    k6Path?: string;
+    env?: Record<string, string>;
+    cwd?: string;
+    timeoutMs?: number;
+} | {
+    kind: "game";
+    name: string;
+    engine: "godot";
+    project: string;
+    walkthrough: string;
+    mode?: "semantic" | "visual";
+    enginePath?: string;
+    seed?: number;
+    physicsFps?: number;
+    pixelTolerance?: {
+        maxChangedRatio?: number;
+        perChannelThreshold?: number;
+    };
+    screenshotMode?: "advisory" | "strict";
+    markers?: Record<string, {
+        pixelTolerance?: {
+            maxChangedRatio?: number;
+            perChannelThreshold?: number;
+        };
+    }>;
+    timeoutMs?: number;
+} | {
+    kind: "desktop";
+    name: string;
+    driver?: "macos-ax" | "ocr";
+    app?: string;
+    tree?: string;
+    command?: string;
+    maxDepth?: number;
+    ocrFallback?: boolean;
+    screenshot?: string;
+    screenshotCommand?: string;
+    ocrCommand?: string;
+    cwd?: string;
+    timeoutMs?: number;
+};
+export type LifecycleConfig = {
+    setup: string[];
+    start: string[];
+    wait: {
+        command?: string;
+        url?: string;
+        timeoutMs: number;
+    };
+    capture: CaptureTarget[];
+    teardown: string[];
+};
+export type NormalizationConfig = {
+    ansi: "semantic" | "strip";
+    masks: MaskRule[];
+};
+export type ComparisonConfig = {
+    numericTolerance: NumericTolerance;
+    pixelTolerance: PixelTolerance;
+};
+export type DungbeetleConfig = {
+    version: 1;
+    project: {
+        name: string;
+    };
+    baselinesDir: string;
+    artifactsDir: string;
+    lifecycle: LifecycleConfig;
+    normalization: NormalizationConfig;
+    comparison: ComparisonConfig;
+};
+export declare const CONFIG_FILE_NAME = "dungbeetle.config.json";
+export declare const defaultMaskRules: MaskRule[];
+export declare function createDefaultConfig(projectName?: string): DungbeetleConfig;
+export declare function findConfigPath(cwd?: string): Promise<string | null>;
+export declare function loadConfig(configPath?: string, cwd?: string): Promise<DungbeetleConfig>;
+export declare class ConfigValidationError extends Error {
+    readonly issues: string[];
+    readonly configPath?: string | undefined;
+    constructor(issues: string[], configPath?: string | undefined);
+}
+export declare function validateConfig(config: DungbeetleConfig, configPath?: string): void;
+export declare function writeDefaultConfig(outputPath?: string, projectName?: string, targets?: CaptureTarget[]): Promise<string>;