@bigbertha/sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felix Owens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# @bigbertha/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Error reporting for bertha. Browser, Node, edge and Next.js, with no dependencies and
+source maps matched by debug id rather than by file path.
+
+- About 4.4 kB gzipped in the browser (`npm run size` enforces the budget).
+- Batches events, backs off when bertha says so, and sends what's queued as the page or
+  process goes away.
+- Scrubs emails, bearer tokens and secret-looking query values by default.
+- The build plugins give each bundle a debug id, upload its map and delete the `.map`
+  files, so maps never ship to browsers.
+
+Each project's setup page in bertha shows the exact snippet for its runtimes, with its
+keys filled in. This file covers the same ground in more detail.
+
+## Install
+
+```bash
+npm install @bigbertha/sdk
+```
+
+Each version is also attached to its GitHub release as `bigbertha-sdk-<version>.tgz`.
+To build one yourself: `npm ci && npm run build && npm pack` in this folder.
+
+## Keys
+
+Every project has two:
+
+- **Ingest key** (`BERTHA_KEY`): sends events. It ships to browsers, so it's public; a
+  leaked key can only send events, at most 50 a second.
+- **Upload key** (`BERTHA_UPLOAD_KEY`): uploads source maps and records deploys. Keep it
+  in CI secrets only.
+
+`bertha project keys <name>` on the server prints both. Rotating the ingest key in
+project settings stops the old one at once.
+
+## Next.js
+
+```bash
+# .env.local and your host
+NEXT_PUBLIC_BERTHA_KEY="…"
+NEXT_PUBLIC_BERTHA_URL="https://bertha.example.com"
+BERTHA_UPLOAD_KEY="…"   # CI only
+```
+
+```ts
+// instrumentation.ts: server and edge errors, including onRequestError
+export { register, onRequestError } from "@bigbertha/sdk/next"
+
+// instrumentation-client.ts: browser errors and navigation breadcrumbs
+export { onRouterTransitionStart } from "@bigbertha/sdk/next/client"
+
+// next.config.ts: stamps the release, uploads maps after `next build`
+import { withBertha } from "@bigbertha/sdk/next/config"
+export default withBertha({ /* your config */ })
+```
+
+`withBertha` options: `release`, `keepMaps` (default false), `disableUpload`.
+
+## Vite (browser)
+
+```ts
+// src/main.ts
+import { init } from "@bigbertha/sdk/browser"
+init({ key: import.meta.env.VITE_BERTHA_KEY, url: import.meta.env.VITE_BERTHA_URL })
+
+// vite.config.ts
+import { bertha } from "@bigbertha/sdk/vite"
+export default defineConfig({ plugins: [bertha()] })
+```
+
+The plugin turns on hidden source maps if the build has none. It only uploads when
+`BERTHA_UPLOAD_KEY` is set, so local builds stay offline and keep their maps.
+Options: `release`, `url`, `uploadKey`, `keepMaps`.
+
+## Node
+
+```ts
+import { init } from "@bigbertha/sdk/node"
+init() // reads BERTHA_KEY, BERTHA_URL, BERTHA_RELEASE and NODE_ENV
+```
+
+`init` reports uncaught exceptions and unhandled rejections, flushes, then exits as Node
+would (`handlers: false` turns that off). It also sends a heartbeat every 20 minutes so
+bertha can tell "no errors" from "not running" (`heartbeat: false`).
+
+`wrapHandler(fn)` reports what a request handler throws and rethrows it.
+
+For bundled Node code, give the output debug ids and upload its maps after the build:
+
+```bash
+npx bertha sourcemaps upload dist
+```
+
+## Edge
+
+```ts
+import { init } from "@bigbertha/sdk/edge"
+init({ key: env.BERTHA_KEY, url: env.BERTHA_URL })
+```
+
+## Capturing by hand
+
+Every entry exports the same functions:
+
+```ts
+captureException(err, { level: "warning", tags: { job: "nightly" }, fingerprint: ["nightly-import"] })
+captureMessage("Payment provider slow", { level: "warning" })
+addBreadcrumb({ category: "cart", message: "Added 2 items" })
+setUser({ id: "u_42" })   // hashed on the server, never shown in full
+setTag("tenant", "harbour")
+await flush()
+```
+
+## Options
+
+| Option | Default | |
+| --- | --- | --- |
+| `key`, `url` | from env (Node, edge) | Required in the browser. |
+| `release` | stamped at build time | The plugins stamp it from `BERTHA_RELEASE`, the CI's commit sha or `git HEAD`. |
+| `environment` | `BERTHA_ENVIRONMENT` or `NODE_ENV` (Node, edge), else production | Free text is mapped to production, staging or development. |
+| `sampleRate` | `1` | Share of events to send. |
+| `beforeSend` | | Change an event, or return `null` to drop it. |
+| `scrub` | `true` | Redact emails, bearer tokens and secret query values. |
+| `tags` | | Tags on every event. |
+| `debug` | `false` | Log what the SDK does. |
+
+## Deploys
+
+Record each deploy from CI, after it goes out:
+
+```bash
+npx bertha deploy --env production
+```
+
+It sends the release and the last commit's sha, message and author. The release page
+then shows what the deploy brought in and what went quiet after it. A first event from an
+unknown release also creates the release, without the commit details.
+
+## Development
+
+```bash
+npm run check   # types
+npm test        # unit tests
+npm run size    # browser bundle budget
+npm run e2e     # the real bertha binary and the example apps, end to end
+```
+
+`npm run e2e` uses `../server/target/debug/bertha`, or `BERTHA_BIN`. `-- --next` adds the
+Next.js example (`npm install` in `examples/next-app` first).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./cli.js";
+process.exitCode = await main(process.argv.slice(2));

package/dist/browser/index.d.ts

@@ -0,0 +1,9 @@
+import { Client } from "../core/client.ts";
+import type { Options } from "../core/types.ts";
+export { addBreadcrumb, captureException, captureMessage, flush, getClient, setTag, setUser } from "../core/hub.ts";
+export type { CaptureContext, IngestEvent, Options } from "../core/types.ts";
+export interface BrowserOptions extends Options {
+    /** Which breadcrumbs to record automatically. All on by default. */
+    breadcrumbs?: Partial<Record<"fetch" | "xhr" | "navigation" | "click" | "console", boolean>>;
+}
+export declare function init(options: BrowserOptions): Client | undefined;

package/dist/browser/index.js

@@ -0,0 +1,164 @@
+// @bigbertha/sdk/browser: uncaught errors and rejections, with breadcrumbs from
+// fetch, XHR, navigation, clicks and the console.
+import { Client } from "../core/client.js";
+import { setClient } from "../core/hub.js";
+import { scrubUrl } from "../core/scrub.js";
+import { fetchTransport, streamGzip } from "../core/transport.js";
+import { VERSION } from "../core/version.js";
+import { userAgent } from "./user-agent.js";
+export { addBreadcrumb, captureException, captureMessage, flush, getClient, setTag, setUser } from "../core/hub.js";
+let installed = false;
+export function init(options) {
+    if (typeof window === "undefined")
+        return undefined;
+    if (!options.key || !options.url) {
+        console.warn("[bertha] init needs a key and a url. Nothing will be sent.");
+        return undefined;
+    }
+    const nativeFetch = window.fetch.bind(window);
+    const client = new Client(options, fetchTransport({
+        url: options.url,
+        key: options.key,
+        keyInQuery: true,
+        gzip: streamGzip,
+        fetch: nativeFetch,
+        beacon: (url, body) => !!navigator.sendBeacon?.(url, new Blob([body], { type: "text/plain" })),
+    }), { name: "bertha.browser", version: VERSION }, { ...userAgent(navigator.userAgent), userAgent: navigator.userAgent });
+    setClient(client);
+    if (installed)
+        return client;
+    installed = true;
+    window.addEventListener("error", (e) => {
+        // Resource load errors (img, script) bubble here too, without an error object.
+        if (!e.error && !e.message)
+            return;
+        client.captureException(e.error ?? new ErrorFromEvent(e), { level: "error" });
+    });
+    window.addEventListener("unhandledrejection", (e) => client.captureException(e.reason));
+    addEventListener("pagehide", () => void client.flush(true));
+    document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden")
+            void client.flush(true);
+    });
+    const on = { fetch: true, xhr: true, navigation: true, click: true, console: true, ...options.breadcrumbs };
+    const base = options.url.replace(/\/+$/, "");
+    const crumb = (category, message, level) => client.addBreadcrumb(level ? { category, message, level } : { category, message });
+    if (on.fetch)
+        instrumentFetch(base, crumb);
+    if (on.xhr)
+        instrumentXhr(base, crumb);
+    if (on.navigation)
+        instrumentHistory(crumb);
+    if (on.click)
+        instrumentClicks(crumb);
+    if (on.console)
+        instrumentConsole(crumb);
+    return client;
+}
+class ErrorFromEvent extends Error {
+    constructor(e) {
+        super(e.message);
+        this.name = "Error";
+        this.stack = `${e.message}\n    at ${e.filename}:${e.lineno}:${e.colno}`;
+    }
+}
+function requestLine(method, url, status) {
+    return `${method.toUpperCase()} ${scrubUrl(url)} ${status}`;
+}
+function instrumentFetch(base, crumb) {
+    const original = window.fetch;
+    window.fetch = async function (input, init) {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+        if (url.startsWith(base))
+            return original.call(window, input, init);
+        try {
+            const res = await original.call(window, input, init);
+            crumb("fetch", requestLine(method, url, res.status), res.status >= 400 ? "error" : undefined);
+            return res;
+        }
+        catch (e) {
+            crumb("fetch", requestLine(method, url, "failed"), "error");
+            throw e;
+        }
+    };
+}
+function instrumentXhr(base, crumb) {
+    const proto = XMLHttpRequest.prototype;
+    const open = proto.open;
+    const send = proto.send;
+    const meta = new WeakMap();
+    proto.open = function (method, url, ...rest) {
+        meta.set(this, [method, String(url)]);
+        return open.call(this, method, url, ...rest);
+    };
+    proto.send = function (body) {
+        const m = meta.get(this);
+        if (m && !m[1].startsWith(base)) {
+            this.addEventListener("loadend", () => crumb("fetch", requestLine(m[0], m[1], this.status || "failed"), !this.status || this.status >= 400 ? "error" : undefined));
+        }
+        return send.call(this, body);
+    };
+}
+function instrumentHistory(crumb) {
+    let last = location.href;
+    const record = () => {
+        const to = location.href;
+        if (to === last)
+            return;
+        crumb("navigation", `${scrubUrl(path(last))} → ${scrubUrl(path(to))}`);
+        last = to;
+    };
+    for (const m of ["pushState", "replaceState"]) {
+        const original = history[m];
+        history[m] = function (...args) {
+            const r = original.apply(this, args);
+            record();
+            return r;
+        };
+    }
+    addEventListener("popstate", record);
+}
+function path(href) {
+    try {
+        const u = new URL(href);
+        return u.pathname + u.search;
+    }
+    catch {
+        return href;
+    }
+}
+function instrumentClicks(crumb) {
+    document.addEventListener("click", (e) => {
+        const el = e.target?.closest?.("a,button,[role=button],input,select,label,summary");
+        if (el)
+            crumb("ui", describeElement(el));
+    }, { capture: true, passive: true });
+}
+function describeElement(el) {
+    const tag = el.tagName.toLowerCase();
+    const label = el.getAttribute("aria-label") ??
+        el.getAttribute("data-testid") ??
+        (tag === "input" ? el.getAttribute("name") : el.textContent?.trim().replace(/\s+/g, " ").slice(0, 60));
+    const id = el.id ? `#${el.id}` : "";
+    return label ? `Clicked ${tag}${id} "${label}"` : `Clicked ${tag}${id}`;
+}
+function instrumentConsole(crumb) {
+    for (const level of ["warn", "error"]) {
+        const original = console[level];
+        console[level] = (...args) => {
+            const text = args.map((a) => (typeof a === "string" ? a : a instanceof Error ? a.message : safeJson(a))).join(" ");
+            if (!text.startsWith("[bertha]"))
+                crumb("console", text.slice(0, 500), level === "warn" ? "warning" : "error");
+            original.apply(console, args);
+        };
+    }
+}
+function safeJson(v) {
+    try {
+        return JSON.stringify(v) ?? String(v);
+    }
+    catch {
+        return String(v);
+    }
+}

package/dist/browser/user-agent.d.ts

@@ -0,0 +1,4 @@
+export declare function userAgent(ua: string): {
+    browser?: string;
+    os?: string;
+};

package/dist/browser/user-agent.js

@@ -0,0 +1,38 @@
+// Just enough user-agent reading to tag events by browser and OS.
+const BROWSERS = [
+    [/Edg(?:e|A|iOS)?\/(\d+)/, "Edge"],
+    [/OPR\/(\d+)/, "Opera"],
+    [/SamsungBrowser\/(\d+)/, "Samsung Internet"],
+    [/Firefox\/(\d+)/, "Firefox"],
+    [/FxiOS\/(\d+)/, "Firefox"],
+    [/CriOS\/(\d+)/, "Chrome"],
+    [/Chrome\/(\d+)/, "Chrome"],
+    [/Version\/(\d+)(?:\.\d+)?.*Safari/, "Safari"],
+];
+export function userAgent(ua) {
+    const out = {};
+    for (const [re, name] of BROWSERS) {
+        const m = re.exec(ua);
+        if (m) {
+            out.browser = `${name} ${m[1]}`;
+            break;
+        }
+    }
+    const ios = /(?:iPhone|iPad|iPod).*? OS (\d+)/.exec(ua);
+    const android = /Android (\d+)/.exec(ua);
+    const mac = /Mac OS X (\d+)[._](\d+)/.exec(ua);
+    const win = /Windows NT (\d+\.\d+)/.exec(ua);
+    if (ios)
+        out.os = `iOS ${ios[1]}`;
+    else if (android)
+        out.os = `Android ${android[1]}`;
+    else if (win)
+        out.os = win[1] === "10.0" ? "Windows 10+" : `Windows NT ${win[1]}`;
+    else if (mac)
+        out.os = `macOS ${mac[1] === "10" ? `10.${mac[2]}` : mac[1]}`;
+    else if (/CrOS/.test(ua))
+        out.os = "ChromeOS";
+    else if (/Linux/.test(ua))
+        out.os = "Linux";
+    return out;
+}

package/dist/build/index.d.ts

@@ -0,0 +1,39 @@
+export { detectRelease, lastCommit } from "./release.ts";
+export interface ProcessOptions {
+    /** The build output. */
+    dir: string;
+    release?: string;
+    /** bertha's URL. Without it (or the key) nothing is uploaded. */
+    url?: string;
+    /** The project's upload key (BERTHA_UPLOAD_KEY). */
+    uploadKey?: string;
+    /** Keep the .map files in the output. A function decides per bundle. Default false. */
+    keepMaps?: boolean | ((file: string) => boolean);
+    /** Directory names to skip. */
+    skip?: string[];
+    log?: (message: string) => void;
+    fetch?: typeof fetch;
+}
+export interface Processed {
+    file: string;
+    debugId: string;
+    uploaded: boolean;
+    error?: string;
+}
+export interface Report {
+    files: Processed[];
+    uploaded: number;
+    failed: number;
+    /** Leftover .js.map files removed because no bundle referenced them. */
+    removedOrphans: number;
+    /** Why nothing was uploaded, when nothing was. */
+    skipped?: string;
+}
+export declare function processDirectory(o: ProcessOptions): Promise<Report>;
+/** A stable UUID from the bundle's content, so rebuilding the same code gives the same id. */
+export declare function idFor(code: string): string;
+/** The line appended to a bundle. Runs once when the bundle loads; never throws. */
+export declare function snippet(debugId: string, release?: string): string;
+/** Appends the snippet, before a trailing sourceMappingURL comment if there is one. */
+export declare function stamp(code: string, debugId: string, release?: string): string;
+export declare function reason(res: Response): Promise<string>;

package/dist/build/index.js

@@ -0,0 +1,177 @@
+// After a build: give each bundle that has a source map a debug id, upload the maps
+// to bertha, and take them out of the output so they aren't served.
+//
+// The id goes in a line appended to the bundle. Appending (never prepending) keeps
+// every existing mapping valid. At runtime that line records the bundle's own URL
+// from `new Error().stack` against its id, so events can name the map for each frame
+// wherever the file was served from.
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { gzipSync } from "node:zlib";
+export { detectRelease, lastCommit } from "./release.js";
+const JS = /\.(?:m|c)?js$/;
+const ORPHAN_MAP = /\.(?:m|c)?js\.map$/;
+const MAP_COMMENT = /\n?\/\/[#@] sourceMappingURL=(\S+)[ \t]*\r?\n?$/;
+const DEBUG_ID_COMMENT = /\/\/# debugId=([0-9a-fA-F-]{36})/;
+const CONCURRENCY = 4;
+const UPLOAD_TIMEOUT_MS = 60_000;
+export async function processDirectory(o) {
+    const root = resolve(o.dir);
+    const log = o.log ?? (() => { });
+    const skip = new Set(["node_modules", ...(o.skip ?? [])]);
+    const bundles = (await walk(root, skip)).filter((f) => JS.test(f));
+    const found = [];
+    for (const file of bundles) {
+        const code = await readFile(file, "utf8");
+        const map = await findMap(file, code);
+        if (map)
+            found.push({ file, code, map });
+    }
+    const canUpload = !!(o.url && o.uploadKey);
+    const report = {
+        files: [],
+        uploaded: 0,
+        failed: 0,
+        removedOrphans: 0,
+        skipped: canUpload ? undefined : "No upload key or URL, so the maps stay local.",
+    };
+    await pool(found, CONCURRENCY, async ({ file, code, map }) => {
+        const debugId = DEBUG_ID_COMMENT.exec(code)?.[1]?.toLowerCase() ?? idFor(code);
+        const rel = relative(root, file).split(sep).join("/");
+        const keep = typeof o.keepMaps === "function" ? o.keepMaps(rel) : !!o.keepMaps;
+        const json = JSON.parse(map.text);
+        json.debugId = debugId;
+        const mapText = JSON.stringify(json);
+        let out = DEBUG_ID_COMMENT.test(code) ? code : stamp(code, debugId, o.release);
+        if (keep && map.path)
+            await writeFile(map.path, mapText);
+        else if (!keep) {
+            out = out.replace(MAP_COMMENT, "\n");
+            if (map.path)
+                await rm(map.path, { force: true });
+        }
+        if (out !== code)
+            await writeFile(file, out);
+        const entry = { file: rel, debugId, uploaded: false };
+        if (canUpload) {
+            try {
+                await upload(o, { debugId, file: rel, release: o.release }, mapText);
+                entry.uploaded = true;
+                report.uploaded++;
+            }
+            catch (e) {
+                entry.error = e instanceof Error ? e.message : String(e);
+                report.failed++;
+            }
+        }
+        report.files.push(entry);
+    });
+    // Maps no bundle points at (renamed polyfills and the like) are source code too.
+    if (o.keepMaps !== true) {
+        const keepFn = typeof o.keepMaps === "function" ? o.keepMaps : undefined;
+        for (const f of await walk(root, skip)) {
+            if (!ORPHAN_MAP.test(f) || !existsSync(f))
+                continue;
+            if (keepFn?.(relative(root, f.replace(/\.map$/, "")).split(sep).join("/")))
+                continue;
+            await rm(f, { force: true });
+            report.removedOrphans++;
+        }
+    }
+    report.files.sort((a, b) => a.file.localeCompare(b.file));
+    for (const f of report.files)
+        if (f.error)
+            log(`Couldn't upload the map for ${f.file}: ${f.error}`);
+    if (found.length === 0)
+        log(`No bundles with source maps in ${o.dir}.`);
+    else if (canUpload)
+        log(`Uploaded ${report.uploaded} of ${found.length} source maps${o.release ? ` for ${o.release}` : ""}.`);
+    else
+        log(`Stamped ${found.length} bundles with debug ids. ${report.skipped}`);
+    return report;
+}
+async function findMap(file, code) {
+    const ref = MAP_COMMENT.exec(code)?.[1];
+    if (ref?.startsWith("data:")) {
+        const comma = ref.indexOf(",");
+        const data = ref.slice(comma + 1);
+        const text = ref.slice(0, comma).endsWith(";base64")
+            ? Buffer.from(data, "base64").toString("utf8")
+            : decodeURIComponent(data);
+        return { text };
+    }
+    const candidates = ref && !/^[a-z]+:/i.test(ref) ? [join(dirname(file), decodeURI(ref.split("?")[0]))] : [];
+    candidates.push(`${file}.map`);
+    for (const path of candidates) {
+        if (existsSync(path))
+            return { text: await readFile(path, "utf8"), path };
+    }
+    return undefined;
+}
+/** A stable UUID from the bundle's content, so rebuilding the same code gives the same id. */
+export function idFor(code) {
+    const h = createHash("sha256").update(code).digest("hex");
+    const variant = ((parseInt(h[16], 16) & 0x3) | 0x8).toString(16);
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-${variant}${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+/** The line appended to a bundle. Runs once when the bundle loads; never throws. */
+export function snippet(debugId, release) {
+    const r = release ? `g.__berthaRelease=${JSON.stringify(release)}` : "";
+    return (`;!function(){try{var g=typeof globalThis<"u"?globalThis:self,s=(new Error).stack;` +
+        `s&&((g.__berthaIds=g.__berthaIds||{})[s]="${debugId}");${r}}catch(e){}}();\n//# debugId=${debugId}\n`);
+}
+/** Appends the snippet, before a trailing sourceMappingURL comment if there is one. */
+export function stamp(code, debugId, release) {
+    const m = MAP_COMMENT.exec(code);
+    const body = m ? code.slice(0, m.index) : code;
+    const tail = m ? m[0].replace(/^\n?/, "") : "";
+    return `${body.endsWith("\n") ? body : `${body}\n`}${snippet(debugId, release)}${tail}`;
+}
+async function upload(o, q, map) {
+    const f = o.fetch ?? fetch;
+    const params = new URLSearchParams({ debugId: q.debugId, file: q.file });
+    if (q.release)
+        params.set("release", q.release);
+    const res = await f(`${o.url.replace(/\/+$/, "")}/ingest/v1/sourcemaps?${params}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${o.uploadKey}`, "content-type": "application/json" },
+        body: new Uint8Array(gzipSync(map)),
+        signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+    });
+    if (!res.ok)
+        throw new Error(await reason(res));
+}
+export async function reason(res) {
+    try {
+        const body = (await res.json());
+        if (body.error)
+            return `${body.error} (HTTP ${res.status})`;
+    }
+    catch {
+        // not JSON
+    }
+    return `HTTP ${res.status}`;
+}
+async function walk(dir, skip) {
+    const out = [];
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!skip.has(entry.name))
+                out.push(...(await walk(path, skip)));
+        }
+        else if (entry.isFile())
+            out.push(path);
+    }
+    return out;
+}
+async function pool(items, n, run) {
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length)
+            await run(items[next++]);
+    };
+    await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
+}

package/dist/build/release.d.ts

@@ -0,0 +1,8 @@
+/** The release for this build: env first (CI sets these), then git, then package.json. */
+export declare function detectRelease(cwd?: string): string | undefined;
+export interface Commit {
+    sha: string;
+    message: string;
+    author: string;
+}
+export declare function lastCommit(cwd?: string): Commit | undefined;

package/dist/build/release.js

@@ -0,0 +1,36 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/** The release for this build: env first (CI sets these), then git, then package.json. */
+export function detectRelease(cwd = process.cwd()) {
+    for (const name of ["BERTHA_RELEASE", "VERCEL_GIT_COMMIT_SHA", "GITHUB_SHA", "CF_PAGES_COMMIT_SHA", "COMMIT_SHA"]) {
+        const v = process.env[name]?.trim();
+        if (v)
+            return v;
+    }
+    const sha = git(cwd, ["rev-parse", "HEAD"]);
+    if (sha)
+        return sha;
+    try {
+        const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+        return pkg.version;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function lastCommit(cwd = process.cwd()) {
+    const out = git(cwd, ["log", "-1", "--format=%H%x00%s%x00%an"]);
+    if (!out)
+        return undefined;
+    const [sha, message, author] = out.split("\0");
+    return sha && message !== undefined && author !== undefined ? { sha, message, author } : undefined;
+}
+function git(cwd, args) {
+    try {
+        return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(argv: string[], out?: (s: string) => void): Promise<number>;