dungbeetle 0.1.1

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 DungbeetleDev
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/NOTICE

@@ -0,0 +1,19 @@
+Dungbeetle
+Copyright 2026 DungbeetleDev
+
+This product includes software developed as part of the Dungbeetle project
+(https://github.com/DungbeetleTech/client).
+
+The command-line tool and core engine in this repository (the `dungbeetle`
+package at the repository root) are licensed under the Functional Source License,
+Version 1.1 (FSL-1.1-ALv2): source-available and free for any use except offering
+a competing product or service, with an automatic conversion to the Apache License,
+Version 2.0 two years after each release. See the LICENSE file for the full text.
+
+The cloud server in the `server/` directory is licensed separately under the
+Business Source License 1.1 (BUSL-1.1). See `server/LICENSE` and LICENSING.md for
+details and the change-license terms.
+
+"Dungbeetle" and the Dungbeetle logo are trademarks of DungbeetleDev. The licenses
+above grant rights to the software but not to the marks; see TRADEMARK.md for the
+brand-use policy.

package/README.md

@@ -0,0 +1,139 @@
+<p align="center">
+  <img src="brand/logo.svg" alt="Dungbeetle" width="220">
+</p>
+
+# Dungbeetle
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dungbeetle"><img src="https://img.shields.io/npm/v/dungbeetle" alt="npm version"></a>
+  <a href="https://github.com/DungbeetleTech/client/actions/workflows/ci.yml"><img src="https://github.com/DungbeetleTech/client/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/node/v/dungbeetle" alt="Node.js version">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-FSL--1.1--ALv2-blue" alt="License: FSL-1.1-ALv2"></a>
+</p>
+
+> Web, desktop, terminal, and eventually anything — zero adoption cost and runs anywhere.
+
+Dungbeetle captures your app's output as stable, reviewable JSON and produces
+**semantic diffs** instead of brittle pixel comparisons. Output is normalized (timestamps,
+UUIDs, and temp paths are masked) so baselines stay readable and survive cosmetic
+churn.
+
+- 🖥️ **Terminal** — capture with ANSI normalization
+- 🌐 **Web** — structured DOM snapshots (`url`/`html` fetch by default, or a
+  `playwright` driver when a browser is available)
+- ⚡ **Performance** — baselines from k6 metrics, compared with numeric tolerance
+- 🪟 **Desktop** — accessibility-tree snapshots (role/name/state), with an
+  experimental native macOS driver (`driver: "macos-ax"`)
+- 🔌 **API** — REST/GraphQL response snapshots (status, allow-listed headers,
+  parsed JSON body) with structural diffs
+- 🎮 **Game** — scripted walkthroughs snapshotting semantic game state at named
+  markers, deterministic and headless (Godot 4.x first; see `adapters/godot`)
+- 🎭 **Shared masking** for dynamic values, and stable JSON diffs you can review
+  in a pull request
+
+Baselines are committed under `dungbeetle.snapshots/` so changes show up in code
+review. An optional **Dungbeetle cloud** service (a separate product) can store runs
+and baselines centrally when you'd rather not commit them.
+
+## 📚 Documentation
+
+Full documentation — guides, capture types, configuration, and the CLI
+reference — lives at the Dungbeetle docs site:
+
+**→ <https://dungbeetle.dev>**
+
+<!-- The docs domain is a placeholder until the site goes live. When the
+     production URL is set, update this one link (and the matching pointers in
+     SUPPORT.md and CONTRIBUTING.md). -->
+
+## Requirements
+
+- **Node.js 22.5.0 or newer.**
+- No native build step and no external services for the CLI.
+
+## Installation
+
+```sh
+npm install -g dungbeetle   # global `dungbeetle` binary
+# or, per-project:
+npm install --save-dev dungbeetle && npx dungbeetle --help
+```
+
+## Quick start
+
+Scaffold a config, then add at least one **capture target** — `init` writes an
+empty `lifecycle.capture` array (unless it detects a Laravel app), so you tell
+Dungbeetle what to snapshot:
+
+```sh
+dungbeetle init     # scaffold dungbeetle.config.json
+```
+
+Add a target to `lifecycle.capture` in `dungbeetle.config.json` — here a minimal
+terminal snapshot (see the [docs](https://dungbeetle.dev) for web, desktop, game,
+API, and check targets):
+
+```json
+{
+  "lifecycle": {
+    "capture": [{ "kind": "terminal", "name": "hello", "command": "echo hello world" }]
+  }
+}
+```
+
+Then capture and compare:
+
+```sh
+dungbeetle update   # run your capture targets and write the first baselines
+dungbeetle test     # compare current output against the baselines
+```
+
+`update` writes baselines under `dungbeetle.snapshots/` (commit these). `test`
+compares current output to them and exits non-zero on any difference, so it drops
+straight into CI. Run `dungbeetle doctor` any time to check your config and
+targets. For machine-readable CI output:
+
+```sh
+dungbeetle ci --json report.json --html report.html
+```
+
+Run `dungbeetle doctor` to validate your config, paths, targets, and optional browser
+setup. See the [documentation](https://dungbeetle.dev) for the next steps.
+
+## Dungbeetle cloud
+
+An optional **Dungbeetle cloud** service stores runs and baselines centrally with a
+review/approve UI — useful when you'd rather not commit baselines to your repo. It
+is a **separate product** (not part of this repository); see
+<https://dungbeetle.dev> for details. Production self-hosting is available to
+enterprise customers on request.
+
+## Contributing
+
+```sh
+npm install
+npm run check           # lint + typecheck + test (run before a PR)
+git commit -s           # sign off your commits (DCO — required)
+```
+
+We welcome contributions! Please read [CONTRIBUTING.md](CONTRIBUTING.md) (it
+covers the **DCO sign-off** every commit needs) and our
+[Code of Conduct](CODE_OF_CONDUCT.md). Questions go to
+[Discussions](https://github.com/DungbeetleTech/client/discussions); bugs and
+features to [Issues](https://github.com/DungbeetleTech/client/issues/new/choose);
+security reports to [SECURITY.md](SECURITY.md). See also [SUPPORT.md](SUPPORT.md)
+and [GOVERNANCE.md](GOVERNANCE.md).
+
+## License
+
+Dungbeetle's **CLI & core engine** (`dungbeetle`, this repository) is
+**source-available** under the **Functional Source License 1.1**
+([`LICENSE`](LICENSE)) — free for any use, including internal and commercial,
+except offering it to others as a competing product or service; each release
+converts to **Apache-2.0** two years later.
+
+The **Dungbeetle cloud** server is a separate product under the **Business Source
+License 1.1** and lives in its own repository.
+
+See [LICENSING.md](LICENSING.md) for the rationale and [TRADEMARK.md](TRADEMARK.md)
+for the brand-use policy. "Dungbeetle" and the Dungbeetle logo are trademarks of DungbeetleDev.

package/dist/api/capture.d.ts

@@ -0,0 +1,24 @@
+import type { MaskRule } from "../config.js";
+export type ApiSnapshot = {
+    kind: "api";
+    status: number;
+    headers: Record<string, string>;
+    bodyType: "json" | "text";
+    body: unknown;
+};
+export type ApiCaptureOptions = {
+    url: string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    includeHeaders: string[];
+    timeoutMs: number;
+    maskRules: MaskRule[];
+};
+export declare function maskJsonValue(value: unknown, rules: MaskRule[]): unknown;
+export declare function normalizeApiResponse(input: {
+    status: number;
+    headers: Headers;
+    text: string;
+}, options: Pick<ApiCaptureOptions, "includeHeaders" | "maskRules">): ApiSnapshot;
+export declare function captureApi(options: ApiCaptureOptions): Promise<ApiSnapshot>;

package/dist/api/capture.js

@@ -0,0 +1,61 @@
+import { isRecord } from "../guards.js";
+import { applyMaskRules } from "../normalization.js";
+// Apply mask rules to every string leaf of a parsed JSON value.
+export function maskJsonValue(value, rules) {
+    if (typeof value === "string") {
+        return applyMaskRules(value, rules);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => maskJsonValue(entry, rules));
+    }
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, nested]) => [key, maskJsonValue(nested, rules)]));
+    }
+    return value;
+}
+// Turn a fetched response into the snapshot shape. Split from `captureApi` so
+// tests can exercise the normalization without a live server.
+export function normalizeApiResponse(input, options) {
+    const headers = {};
+    for (const name of options.includeHeaders) {
+        const value = input.headers.get(name);
+        if (value !== null) {
+            headers[name.toLowerCase()] = applyMaskRules(value, options.maskRules);
+        }
+    }
+    const contentType = input.headers.get("content-type") ?? "";
+    if (contentType.includes("json")) {
+        try {
+            return {
+                kind: "api",
+                status: input.status,
+                headers,
+                bodyType: "json",
+                body: maskJsonValue(JSON.parse(input.text), options.maskRules)
+            };
+        }
+        catch {
+            // Declared JSON but unparseable — fall through and snapshot the raw text,
+            // which is itself the signal a reviewer needs to see.
+        }
+    }
+    return {
+        kind: "api",
+        status: input.status,
+        headers,
+        bodyType: "text",
+        body: applyMaskRules(input.text, options.maskRules)
+    };
+}
+// Note: a non-2xx status is NOT an error here — the status is part of the
+// snapshot, so an endpoint whose contract is `404` can be baselined and a
+// drift to `200` shows up as a diff.
+export async function captureApi(options) {
+    const response = await fetch(options.url, {
+        method: options.method,
+        headers: options.headers,
+        body: options.body,
+        signal: AbortSignal.timeout(options.timeoutMs)
+    });
+    return normalizeApiResponse({ status: response.status, headers: response.headers, text: await response.text() }, options);
+}

package/dist/baselines.d.ts

@@ -0,0 +1,7 @@
+export declare class MissingBaselineError extends Error {
+    readonly baselinePath: string;
+    constructor(baselinePath: string);
+}
+export declare function baselinePathForTarget(baselinesDir: string, targetName: string, cwd?: string): string;
+export declare function readBaseline(filePath: string): Promise<unknown>;
+export declare function writeBaseline(filePath: string, value: unknown): Promise<void>;

package/dist/baselines.js

@@ -0,0 +1,38 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseJsonFile, stableStringify } from "./json.js";
+import { isErrno } from "./guards.js";
+export class MissingBaselineError extends Error {
+    baselinePath;
+    constructor(baselinePath) {
+        super(`Missing baseline at ${baselinePath}`);
+        this.baselinePath = baselinePath;
+    }
+}
+export function baselinePathForTarget(baselinesDir, targetName, cwd = process.cwd()) {
+    return path.join(path.resolve(cwd, baselinesDir), `${slugifyTargetName(targetName)}.json`);
+}
+export async function readBaseline(filePath) {
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT")) {
+            throw new MissingBaselineError(filePath);
+        }
+        throw error;
+    }
+    return parseJsonFile(raw, filePath);
+}
+export async function writeBaseline(filePath, value) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, `${stableStringify(value)}\n`, "utf8");
+}
+function slugifyTargetName(value) {
+    const slug = value
+        .toLowerCase()
+        .replace(/[^a-z0-9._-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return slug || "snapshot";
+}

package/dist/brand.d.ts

@@ -0,0 +1,2 @@
+export declare const BRAND_NAME: string;
+export declare const BRAND_SUBTITLE = "Web, desktop, terminal, and eventually anything \u2014 zero adoption cost and runs anywhere.";

package/dist/brand.js

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Display name for the CLI, overridable via env so the tool can be white-labelled
+// when self-hosted without editing source. Structural identifiers (the `dungbeetle`
+// binary name, `dungbeetle.config.json`) are intentionally NOT driven by this —
+// they stay fixed regardless of the display brand.
+export const BRAND_NAME = process.env.BRAND_NAME?.trim() || "Dungbeetle";
+// Shared brand copy — one source, mirrored by the README/docs (which build
+// separately and can't import this).
+export const BRAND_SUBTITLE = "Web, desktop, terminal, and eventually anything — zero adoption cost and runs anywhere.";

package/dist/capture.d.ts

@@ -0,0 +1,15 @@
+import type { ApiSnapshot } from "./api/capture.js";
+import type { CheckSnapshot } from "./check/capture.js";
+import type { CaptureTarget, DungbeetleConfig } from "./config.js";
+import type { DesktopSnapshot } from "./desktop/a11y.js";
+import type { GameSnapshot } from "./game/capture.js";
+import type { PerformanceSnapshot } from "./perf/k6.js";
+import type { TerminalCapture } from "./terminal/capture.js";
+import type { DomSnapshot, WebFileSnapshot } from "./web/domSnapshot.js";
+import type { PlaywrightWebSnapshot } from "./web/playwrightCapture.js";
+export type SnapshotArtifact = ApiSnapshot | CheckSnapshot | TerminalCapture | DomSnapshot | WebFileSnapshot | PlaywrightWebSnapshot | PerformanceSnapshot | DesktopSnapshot | GameSnapshot;
+export type CaptureContext = {
+    config: DungbeetleConfig;
+    cwd: string;
+};
+export declare function captureTarget(target: CaptureTarget, options: CaptureContext): Promise<SnapshotArtifact>;

package/dist/capture.js

@@ -0,0 +1,7 @@
+import { captureTypes } from "./captures/registry.js";
+// Thin dispatcher: each capture kind owns its full lifecycle in its own
+// `src/captures/<kind>.ts` module; this routes to the registered handler. The
+// web sub-dispatch (playwright/html/url) lives inside the web module's capture.
+export function captureTarget(target, options) {
+    return captureTypes[target.kind].capture(target, options);
+}

package/dist/captures/api.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureType } from "./types.js";
+export declare const api: CaptureType;

package/dist/captures/api.js

@@ -0,0 +1,114 @@
+import { captureApi } from "../api/capture.js";
+import { coerceSnapshot, render } from "../compare/shared.js";
+import { structuralChanges } from "../diff/structural.js";
+import { canonicalizeSnapshot } from "../snapshot.js";
+// Response headers kept in the snapshot unless the target says otherwise.
+// Everything else (dates, request ids, rate-limit counters) is volatile.
+const DEFAULT_INCLUDE_HEADERS = ["content-type"];
+// GraphQL sugar: a `query` (+ optional `variables`) becomes the standard
+// `{query, variables}` JSON POST. A raw `body` is sent verbatim with the
+// user's own headers.
+function requestBody(target) {
+    if (target.query) {
+        return JSON.stringify({ query: target.query, variables: target.variables ?? {} });
+    }
+    return target.body;
+}
+function requestHeaders(target) {
+    const headers = { ...(target.headers ?? {}) };
+    const hasContentType = Object.keys(headers).some((name) => name.toLowerCase() === "content-type");
+    if (target.query && !hasContentType) {
+        headers["content-type"] = "application/json";
+    }
+    return headers;
+}
+function requestMethod(target) {
+    return target.method ?? (target.query || target.body ? "POST" : "GET");
+}
+function compareApi(baseline, candidate, options) {
+    const sections = [];
+    if (baseline.status !== candidate.status) {
+        sections.push(`~ status: ${String(baseline.status)} → ${String(candidate.status)}`);
+    }
+    const changes = structuralChanges({ headers: baseline.headers, body: baseline.body }, { headers: candidate.headers, body: candidate.body }, { numericTolerance: options.comparison.numericTolerance });
+    for (const change of changes) {
+        sections.push(`~ ${change.path}: ${render(change.before)} → ${render(change.after)}`);
+    }
+    return {
+        equal: sections.length === 0,
+        rendered: sections.join("\n")
+    };
+}
+function parsesAsUrl(value) {
+    try {
+        new URL(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function validateApiTarget(target) {
+    if (!target.url || !parsesAsUrl(target.url)) {
+        return {
+            name: "api-target",
+            severity: "fail",
+            target: target.name,
+            message: `API target "${target.name}" must have a valid "url".`
+        };
+    }
+    if (target.body && target.query) {
+        return {
+            name: "api-target",
+            severity: "fail",
+            target: target.name,
+            message: `API target "${target.name}" sets both "body" and "query" — use one.`
+        };
+    }
+    return {
+        name: "api-target",
+        severity: "pass",
+        target: target.name,
+        message: `API target "${target.name}" points at ${target.url}.`
+    };
+}
+export const api = {
+    kind: "api",
+    parallelSafe: true,
+    capture: (target, { config }) => {
+        const apiTarget = target;
+        return captureApi({
+            url: apiTarget.url,
+            method: requestMethod(apiTarget),
+            headers: requestHeaders(apiTarget),
+            body: requestBody(apiTarget),
+            includeHeaders: apiTarget.includeHeaders ?? DEFAULT_INCLUDE_HEADERS,
+            timeoutMs: apiTarget.timeoutMs ?? config.lifecycle.wait.timeoutMs,
+            maskRules: config.normalization.masks
+        });
+    },
+    canonicalize: (value) => ({
+        kind: value.kind,
+        status: value.status,
+        headers: value.headers,
+        bodyType: value.bodyType,
+        body: canonicalizeSnapshot(value.body)
+    }),
+    compare: (baseline, candidate, options) => compareApi(coerceSnapshot(baseline), coerceSnapshot(candidate), options),
+    validateConfig: (target, { label, issues }) => {
+        const apiTarget = target;
+        if (!apiTarget.url || typeof apiTarget.url !== "string") {
+            issues.push(`${label} (api "${apiTarget.name}") must have a "url".`);
+        }
+        else if (!parsesAsUrl(apiTarget.url)) {
+            issues.push(`${label} (api "${apiTarget.name}") has an invalid "url".`);
+        }
+        if (apiTarget.body && apiTarget.query) {
+            issues.push(`${label} (api "${apiTarget.name}") sets both "body" and "query" — use one.`);
+        }
+        if (apiTarget.variables && !apiTarget.query) {
+            issues.push(`${label} (api "${apiTarget.name}") sets "variables" without a "query".`);
+        }
+    },
+    doctorChecks: (target) => [validateApiTarget(target)]
+};

package/dist/captures/check.d.ts

@@ -0,0 +1,2 @@
+import type { CaptureType } from "./types.js";
+export declare const check: CaptureType;