dungbeetle 0.1.1

package/dist/index.js

@@ -0,0 +1,504 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Dungbeetle CLI — Copyright 2026 DungbeetleDev. See LICENSE.
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import { detectLaravelTargets } from "./check/laravel.js";
+import { createDefaultConfig, loadConfig, writeDefaultConfig } from "./config.js";
+import { stableStringify } from "./json.js";
+import { runDoctor } from "./doctor.js";
+import { renderConsoleReport, writeHtmlReport, writeJsonReport } from "./reporters.js";
+import { buildScreenshotComparison, screenshotBuffer, testBaselines, updateBaselines } from "./runner.js";
+import { startManagedLifecycle } from "./lifecycle.js";
+import { Spinner } from "./tty.js";
+import { pushAnonReport, pushBaselines, pushReport } from "./cloud.js";
+import { baselinePathForTarget } from "./baselines.js";
+import { captureTarget } from "./capture.js";
+import { compareSnapshots } from "./compare.js";
+import { canonicalizeSnapshot } from "./snapshot.js";
+import { BRAND_NAME, BRAND_SUBTITLE } from "./brand.js";
+import { stripControlChars } from "./terminal/ansi.js";
+// Read the version from package.json so `dungbeetle --version` always matches the
+// published package. Resolves to ../package.json both from dist/ (built) and
+// from src/ (tsx dev), since package.json sits one level above either.
+const pkg = createRequire(import.meta.url)("../package.json");
+const program = new Command();
+program.name("dungbeetle").description(BRAND_SUBTITLE).version(pkg.version);
+program
+    .command("init")
+    .description(`Scaffold a ${BRAND_NAME} config file.`)
+    .option("-o, --out <path>", "Config path to write", "dungbeetle.config.json")
+    .option("--project-name <name>", "Project name for the config")
+    .option("-f, --force", "Overwrite an existing config", false)
+    .action(async (options) => {
+    const outputPath = path.resolve(options.out);
+    if (!options.force && (await exists(outputPath))) {
+        throw new Error(`Config already exists at ${outputPath}; use --force to overwrite.`);
+    }
+    const laravelTargets = await detectLaravelTargets(path.dirname(outputPath));
+    const writtenPath = await writeDefaultConfig(outputPath, options.projectName ?? path.basename(process.cwd()), laravelTargets ?? []);
+    console.log(`Wrote ${writtenPath}`);
+    if (laravelTargets) {
+        console.log(`Detected a Laravel app — scaffolded ${laravelTargets.length} check targets: ` +
+            `${laravelTargets.map((target) => target.name).join(", ")}.`);
+    }
+});
+program
+    .command("update")
+    .description("Capture configured targets and update local baselines.")
+    .option("--config <path>", "Config path")
+    .option("--cwd <path>", "Project directory", process.cwd())
+    .option("--json <path>", "JSON report path")
+    .option("--html <path>", "HTML report path")
+    .option("--target <name...>", "Only update selected target names")
+    .action(async (options) => {
+    const cwd = path.resolve(options.cwd);
+    const config = await loadConfig(options.config, cwd);
+    const report = await runWithSpinner(captureLabel(config, options.target, "Updating baselines for"), () => updateBaselines({ config, cwd, targets: options.target }));
+    await emitRunnerReport(report, options.json ?? path.join(config.artifactsDir, "update-report.json"), options.html ?? path.join(config.artifactsDir, "update-report.html"), cwd);
+});
+program
+    .command("test")
+    .description("Capture configured targets and compare them to local baselines.")
+    .option("--config <path>", "Config path")
+    .option("--cwd <path>", "Project directory", process.cwd())
+    .option("--json <path>", "JSON report path")
+    .option("--html <path>", "HTML report path")
+    .option("--target <name...>", "Only test selected target names")
+    .option("--with-snapshots", "Include candidate snapshots in the report (for cloud promote)", false)
+    .action(async (options) => {
+    const cwd = path.resolve(options.cwd);
+    const config = await loadConfig(options.config, cwd);
+    const report = await runWithSpinner(captureLabel(config, options.target, "Testing"), () => testBaselines({
+        config,
+        cwd,
+        targets: options.target,
+        includeSnapshots: options.withSnapshots
+    }));
+    await emitRunnerReport(report, options.json ?? path.join(config.artifactsDir, "test-report.json"), options.html ?? path.join(config.artifactsDir, "test-report.html"), cwd);
+});
+program
+    .command("ci")
+    .description("Same as `test`, with CI-friendly JSON output.")
+    .option("--config <path>", "Config path")
+    .option("--cwd <path>", "Project directory", process.cwd())
+    .option("--json <path>", "JSON report path")
+    .option("--html <path>", "HTML report path")
+    .option("--quiet", "Suppress detailed console report", false)
+    .option("--json-only", "Only write the JSON report and suppress HTML/console output", false)
+    .option("--no-html-report", "Do not write an HTML report")
+    .option("--target <name...>", "Only test selected target names")
+    .option("--with-snapshots", "Include candidate snapshots in the report (for cloud promote)", false)
+    .action(async (options) => {
+    const cwd = path.resolve(options.cwd);
+    const config = await loadConfig(options.config, cwd);
+    const report = await runWithSpinner(captureLabel(config, options.target, "Testing"), () => testBaselines({
+        config,
+        cwd,
+        targets: options.target,
+        includeSnapshots: options.withSnapshots
+    }));
+    await emitRunnerReport(report, options.json ?? path.join(config.artifactsDir, "ci-report.json"), shouldWriteHtmlReport(options)
+        ? (options.html ?? path.join(config.artifactsDir, "ci-report.html"))
+        : undefined, cwd, {
+        quiet: options.quiet || options.jsonOnly
+    });
+});
+program
+    .command("doctor")
+    .description(`Check ${BRAND_NAME} config, paths, targets, and optional browser setup.`)
+    .option("--config <path>", "Config path")
+    .option("--cwd <path>", "Project directory", process.cwd())
+    .option("--json <path>", "JSON report path")
+    .action(async (options) => {
+    const cwd = path.resolve(options.cwd);
+    const config = await loadConfig(options.config, cwd);
+    const report = await runDoctor({
+        config,
+        cwd
+    });
+    if (options.json) {
+        await writeJson(path.resolve(cwd, options.json), report);
+    }
+    for (const check of report.checks) {
+        console.log(`${check.severity.toUpperCase()} ${check.name}${check.target ? `:${check.target}` : ""} - ${check.message}`);
+    }
+    if (!report.passed) {
+        process.exitCode = 1;
+    }
+});
+program
+    .command("flake")
+    .description("Capture targets repeatedly and report run-to-run divergence — no baselines involved.")
+    .option("--config <path>", "Config path")
+    .option("--cwd <path>", "Project directory", process.cwd())
+    .option("--target <name...>", "Only check selected target names")
+    .option("--repeat <n>", "Capture repetitions per target", "5")
+    .action(async (options) => {
+    const cwd = path.resolve(options.cwd);
+    const config = await loadConfig(options.config, cwd);
+    const repeat = Math.max(2, Number.parseInt(options.repeat, 10) || 5);
+    const targets = config.lifecycle.capture.filter((target) => !options.target || options.target.includes(target.name));
+    if (targets.length === 0) {
+        throw new Error("No matching targets to check.");
+    }
+    const managed = await startManagedLifecycle(config.lifecycle, cwd);
+    let flaky = false;
+    try {
+        for (const target of targets) {
+            // Force visual divergence to count for game targets: flake detection
+            // wants EVERY source of instability visible, advisory or not.
+            const strictTarget = target.kind === "game" ? { ...target, screenshotMode: "strict" } : target;
+            const runs = [];
+            const canonicals = [];
+            for (let i = 0; i < repeat; i += 1) {
+                const snapshot = await captureTarget(strictTarget, { config, cwd });
+                const canonical = canonicalizeSnapshot(snapshot);
+                canonicals.push(canonical);
+                runs.push(stableStringify(canonical));
+            }
+            const diverged = runs
+                .map((run, index) => ({ run, index }))
+                .filter(({ run }) => run !== runs[0]);
+            if (diverged.length === 0) {
+                console.log(`✅ ${target.kind}:${target.name} — ${repeat}/${repeat} runs identical`);
+                continue;
+            }
+            flaky = true;
+            console.log(`❌ ${target.kind}:${target.name} — ${diverged.length}/${repeat} runs diverged from run 1`);
+            for (const { index } of diverged) {
+                const comparison = compareSnapshots(canonicals[0], canonicals[index], {
+                    comparison: config.comparison,
+                    target: strictTarget
+                });
+                console.log(`  run ${index + 1}:`);
+                for (const line of comparison.rendered.split("\n").filter(Boolean)) {
+                    console.log(`    ${line}`);
+                }
+            }
+        }
+    }
+    finally {
+        await managed.stop();
+    }
+    if (flaky) {
+        process.exitCode = 1;
+    }
+});
+program
+    .command("push")
+    .description(`Upload a run report to a ${BRAND_NAME} cloud server.`)
+    .option("--report <path>", "Path to a JSON report produced by test/ci")
+    .option("--server <url>", "Server base URL", process.env.DUNGBEETLE_SERVER_URL)
+    .option("--client-id <id>", "Repository client id", process.env.DUNGBEETLE_CLIENT_ID)
+    .option("--client-secret <secret>", "Repository client secret (prefer DUNGBEETLE_CLIENT_SECRET — flags leak into shell history and process lists)", process.env.DUNGBEETLE_CLIENT_SECRET)
+    .option("--branch <name>", "Branch label to attach to the run")
+    .option("--commit <sha>", "Commit SHA to attach to the run")
+    .action(async (options) => {
+    if (!options.server) {
+        throw new Error("Missing server URL; pass --server or set DUNGBEETLE_SERVER_URL.");
+    }
+    const credentials = requireClientCredentials(options);
+    if (!options.report) {
+        throw new Error("Missing report path; pass --report <path>.");
+    }
+    const spinner = new Spinner();
+    spinner.start("Uploading run…");
+    let run;
+    try {
+        run = await pushReport({
+            serverUrl: options.server,
+            ...credentials,
+            reportPath: path.resolve(options.report),
+            branch: options.branch,
+            commit: options.commit
+        });
+    }
+    finally {
+        spinner.stop();
+    }
+    console.log(`Uploaded run ${run.id} (${run.status})`);
+    console.log(safeUrl(run.url));
+});
+program
+    .command("push-baselines")
+    .description(`Upload local baselines to a ${BRAND_NAME} cloud server (versioned).`)
+    .option("--config <path>", "Config path")
+    .option("--cwd <path>", "Project directory", process.cwd())
+    .option("--server <url>", "Server base URL", process.env.DUNGBEETLE_SERVER_URL)
+    .option("--client-id <id>", "Repository client id", process.env.DUNGBEETLE_CLIENT_ID)
+    .option("--client-secret <secret>", "Repository client secret (prefer DUNGBEETLE_CLIENT_SECRET — flags leak into shell history and process lists)", process.env.DUNGBEETLE_CLIENT_SECRET)
+    .option("--target <name...>", "Only upload selected target names")
+    .action(async (options) => {
+    if (!options.server) {
+        throw new Error("Missing server URL; pass --server or set DUNGBEETLE_SERVER_URL.");
+    }
+    const credentials = requireClientCredentials(options);
+    const cwd = path.resolve(options.cwd);
+    const config = await loadConfig(options.config, cwd);
+    const selected = new Set(options.target ?? []);
+    const baselines = config.lifecycle.capture
+        .filter((target) => selected.size === 0 || selected.has(target.name))
+        .map((target) => {
+        const snapshotPath = baselinePathForTarget(config.baselinesDir, target.name, cwd);
+        return {
+            target: target.name,
+            kind: target.kind,
+            snapshotPath,
+            screenshotPath: snapshotPath.replace(/\.json$/, ".png")
+        };
+    });
+    if (baselines.length === 0) {
+        throw new Error("No matching capture targets to upload.");
+    }
+    const spinner = new Spinner();
+    spinner.start(`Uploading ${baselines.length} baseline${baselines.length === 1 ? "" : "s"}…`);
+    let uploaded;
+    try {
+        uploaded = await pushBaselines({
+            serverUrl: options.server,
+            ...credentials,
+            baselines
+        });
+    }
+    finally {
+        spinner.stop();
+    }
+    for (const item of uploaded) {
+        const note = item.deduped ? "unchanged" : "new version";
+        console.log(`${item.target} → v${item.version} (${note})`);
+    }
+});
+program
+    .command("anon")
+    .description(`Capture a target and share it on a ${BRAND_NAME} cloud server — no account needed.`)
+    .argument("[url]", "URL to capture (web snapshot)")
+    .option("--compare <url>", "Capture a second URL and share the semantic diff between the two")
+    .option("--screenshot", "Also capture full-page screenshots (needs a Chrome/Chromium)", false)
+    .option("--cmd <command>", "Capture a terminal command's output instead of a URL")
+    .option("--name <name>", "Label for the capture")
+    .option("--server <url>", "Server base URL", process.env.DUNGBEETLE_SERVER_URL)
+    .action(async (url, options) => {
+    if (!options.server) {
+        throw new Error("Missing server URL; pass --server or set DUNGBEETLE_SERVER_URL.");
+    }
+    if (!url && !options.cmd) {
+        throw new Error('Provide a URL to capture, or --cmd "<command>" for a terminal capture.');
+    }
+    if (url && options.cmd) {
+        throw new Error("Pass either a URL or --cmd, not both.");
+    }
+    if (options.compare && !url) {
+        throw new Error("--compare needs two URLs: pass the first as the argument.");
+    }
+    if (options.screenshot && !url) {
+        throw new Error("--screenshot captures a page, so it needs a URL (not --cmd).");
+    }
+    const name = options.name ?? (url ? safeHostname(url) : "command");
+    if (options.cmd) {
+        // The command's output is published to a public share — don't let the
+        // spawned shell inherit cloud credentials it could echo.
+        delete process.env.DUNGBEETLE_CLIENT_ID;
+        delete process.env.DUNGBEETLE_CLIENT_SECRET;
+    }
+    const target = options.cmd
+        ? { kind: "terminal", name, command: options.cmd }
+        : { kind: "web", name, url: url };
+    const config = createDefaultConfig(name);
+    // Capture a URL for the anon flow. With --screenshot the capture goes
+    // through the Playwright driver (screenshots need a real browser); if that
+    // fails — typically no Chrome — the trial degrades to the fetch driver with
+    // a warning instead of dying, so the one-liner stays reliable.
+    let screenshotWarned = false;
+    const captureUrl = async (targetUrl) => {
+        if (options.screenshot) {
+            const withShots = {
+                kind: "web",
+                name,
+                url: targetUrl,
+                driver: "playwright",
+                screenshot: true,
+                // The env var wins inside the driver; only suggest the Chrome channel
+                // when no explicit executable is configured.
+                ...(process.env.DUNGBEETLE_CHROMIUM_EXECUTABLE_PATH
+                    ? {}
+                    : { browser: { channel: "chrome" } })
+            };
+            try {
+                return await captureTarget(withShots, { config, cwd: process.cwd() });
+            }
+            catch (error) {
+                if (!screenshotWarned) {
+                    screenshotWarned = true;
+                    console.error(`warning: screenshot capture unavailable (${error instanceof Error ? error.message : String(error)}); continuing without screenshots.`);
+                }
+            }
+        }
+        return captureTarget({ kind: "web", name, url: targetUrl }, { config, cwd: process.cwd() });
+    };
+    const spinner = new Spinner();
+    spinner.start(options.compare ? "Capturing, comparing, uploading…" : "Capturing and uploading…");
+    let result;
+    let equal;
+    try {
+        const startedAt = new Date().toISOString();
+        const snapshot = url
+            ? await captureUrl(url)
+            : await captureTarget(target, { config, cwd: process.cwd() });
+        const canonical = canonicalizeSnapshot(snapshot);
+        const baselineShot = screenshotBuffer(snapshot);
+        // With --compare the first capture is the baseline and the second the
+        // candidate: the shared page leads with the real semantic diff, exactly
+        // what `test` would report in CI. Without it the single capture is
+        // "missing" (nothing to compare against).
+        let results;
+        if (options.compare) {
+            const candidateArtifact = await captureUrl(options.compare);
+            const candidate = canonicalizeSnapshot(candidateArtifact);
+            const candidateShot = screenshotBuffer(candidateArtifact);
+            const comparison = compareSnapshots(canonical, candidate, {
+                comparison: config.comparison,
+                baselineScreenshot: baselineShot,
+                candidateScreenshot: candidateShot
+            });
+            equal = comparison.equal;
+            const screenshot = candidateShot
+                ? buildScreenshotComparison(baselineShot, candidateShot, config.comparison.pixelTolerance, true, comparison.screenshotImages)
+                : undefined;
+            results = [
+                {
+                    name,
+                    kind: target.kind,
+                    status: comparison.equal ? "passed" : "failed",
+                    ...(comparison.rendered ? { diff: comparison.rendered } : {}),
+                    ...(screenshot ? { screenshot } : {}),
+                    snapshot: stableStringify(candidate)
+                }
+            ];
+        }
+        else {
+            results = [
+                {
+                    name,
+                    kind: target.kind,
+                    status: "missing",
+                    ...(baselineShot ? { screenshot: { candidate: baselineShot.toString("base64") } } : {}),
+                    snapshot: stableStringify(canonical)
+                }
+            ];
+        }
+        const report = {
+            mode: "test",
+            passed: equal ?? true,
+            project: name,
+            startedAt,
+            finishedAt: new Date().toISOString(),
+            results
+        };
+        result = await pushAnonReport({ serverUrl: options.server, report });
+    }
+    finally {
+        spinner.stop();
+    }
+    if (equal !== undefined) {
+        console.log(equal ? "No changes between the two captures." : "Changes found — see the diff:");
+    }
+    console.log(`Shared anonymously → ${safeUrl(result.url)}`);
+    console.log("Public and read-only; deleted after 24 hours.");
+});
+// A server can be pointed anywhere, so treat the URL it hands back as untrusted:
+// strip control characters (terminal-escape injection) and only echo it when it
+// parses as an http(s) URL.
+function safeUrl(url) {
+    const cleaned = stripControlChars(url);
+    try {
+        const parsed = new URL(cleaned);
+        if (parsed.protocol === "http:" || parsed.protocol === "https:") {
+            return cleaned;
+        }
+    }
+    catch {
+        // fall through
+    }
+    return "(server returned an invalid URL)";
+}
+// Best-effort label for a web capture from its URL host; falls back if the URL
+// is malformed (captureTarget will surface the real error).
+function safeHostname(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return "web";
+    }
+}
+program.parseAsync(process.argv).catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});
+// Both upload commands need the repository's client credentials; resolve them
+// from flags or the DUNGBEETLE_CLIENT_ID / DUNGBEETLE_CLIENT_SECRET environment vars.
+function requireClientCredentials(options) {
+    if (!options.clientId) {
+        throw new Error("Missing client id; pass --client-id or set DUNGBEETLE_CLIENT_ID.");
+    }
+    if (!options.clientSecret) {
+        throw new Error("Missing client secret; pass --client-secret or set DUNGBEETLE_CLIENT_SECRET.");
+    }
+    return { clientId: options.clientId, clientSecret: options.clientSecret };
+}
+async function exists(filePath) {
+    try {
+        await readFile(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeJson(filePath, value) {
+    await writeText(filePath, `${stableStringify(value)}\n`);
+}
+async function writeText(filePath, value) {
+    const resolvedPath = path.resolve(filePath);
+    await mkdir(path.dirname(resolvedPath), { recursive: true });
+    await writeFile(resolvedPath, value, "utf8");
+}
+function captureLabel(config, targets, verb) {
+    const all = config.lifecycle?.capture?.map((target) => target.name) ?? [];
+    const selected = targets && targets.length > 0 ? targets : all;
+    const count = selected.length;
+    return `${verb} ${count} target${count === 1 ? "" : "s"}…`;
+}
+async function runWithSpinner(label, run) {
+    const spinner = new Spinner();
+    spinner.start(label);
+    try {
+        return await run();
+    }
+    finally {
+        spinner.stop();
+    }
+}
+async function emitRunnerReport(report, reportPath, htmlReportPath, cwd, options = {}) {
+    const resolvedReportPath = path.resolve(cwd, reportPath);
+    await writeJsonReport(resolvedReportPath, report);
+    if (htmlReportPath) {
+        await writeHtmlReport(path.resolve(cwd, htmlReportPath), report);
+    }
+    if (!options.quiet) {
+        console.log(renderConsoleReport(report));
+        console.log(`Wrote JSON report at ${resolvedReportPath}`);
+        if (htmlReportPath) {
+            console.log(`Wrote HTML report at ${path.resolve(cwd, htmlReportPath)}`);
+        }
+    }
+    if (!report.passed) {
+        process.exitCode = 1;
+    }
+}
+function shouldWriteHtmlReport(options) {
+    return options.jsonOnly ? false : options.htmlReport !== false;
+}

package/dist/json.d.ts

@@ -0,0 +1,2 @@
+export declare function parseJsonFile(raw: string, filePath: string, onError?: (message: string) => never): unknown;
+export declare function stableStringify(value: unknown): string;

package/dist/json.js

@@ -0,0 +1,40 @@
+// Parse JSON that came from a file (or other named source), attaching the file
+// path to a syntax error so callers get a clear "Could not parse JSON at <path>"
+// instead of a bare `SyntaxError` with no context. An optional `onError` hook
+// lets a caller throw its own error type (e.g. a domain ValidationError) while
+// still receiving the formatted message.
+export function parseJsonFile(raw, filePath, onError) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const message = `Could not parse JSON at ${filePath}: ${detail}`;
+        if (onError) {
+            onError(message);
+        }
+        throw new Error(message);
+    }
+}
+// Deterministic JSON serialization: object keys are sorted recursively so a
+// canonicalized snapshot (or report) serializes byte-identically across runs —
+// the basis for stable baselines and dedupe digests.
+export function stableStringify(value) {
+    return JSON.stringify(sortKeys(value), null, 2);
+}
+function sortKeys(value) {
+    if (Array.isArray(value)) {
+        return value.map(sortKeys);
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value)
+            // Compare by UTF-16 code unit, not localeCompare: collation order is
+            // ICU/locale-dependent (LC_ALL/LANG), which would let the same canonical
+            // data serialize with different key order across machines and break the
+            // "byte-identical across runs" guarantee that baselines and dedupe digests
+            // rely on. Code-unit order is stable everywhere.
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+            .map(([key, nested]) => [key, sortKeys(nested)]));
+    }
+    return value;
+}

package/dist/lifecycle.d.ts

@@ -0,0 +1,14 @@
+import type { LifecycleConfig } from "./config.js";
+export type LifecycleRun = {
+    phase: "setup" | "start" | "wait" | "teardown";
+    command: string;
+    exitCode: number | null;
+    durationMs: number;
+    pid?: number;
+};
+export type ManagedLifecycle = {
+    runs: LifecycleRun[];
+    stop: () => Promise<LifecycleRun[]>;
+};
+export declare function runLifecycleCommands(lifecycle: LifecycleConfig, cwd?: string): Promise<LifecycleRun[]>;
+export declare function startManagedLifecycle(lifecycle: LifecycleConfig, cwd?: string): Promise<ManagedLifecycle>;