@testkase/visual 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# @testkase/visual
+
+Upload your test suite's screenshots to [TestKase Visual](https://visual.testkase.com)
+and get told what changed.
+
+```bash
+npx @testkase/visual upload ./screenshots --project "Marketing"
+```
+
+Your tests take the pictures. This uploads them, compares each one against the
+last approved version, and exits 1 when something needs a person to look at it.
+It works with Playwright, Cypress, Puppeteer, Selenium or anything else, because
+a folder of PNGs is not a framework.
+
+## Setup
+
+1. Make a project in TestKase and note its name.
+2. Create a personal access token and put it in your CI as `TESTKASE_TOKEN`.
+3. Take **full-page** screenshots in your tests:
+
+   ```js
+   await page.screenshot({ path: "shots/home.png", fullPage: true }); // Playwright, Puppeteer
+   cy.screenshot("home", { capture: "fullPage" });                    // Cypress
+   ```
+
+4. Upload the folder after the suite has run:
+
+   ```yaml
+   - run: npx playwright test
+   - run: npx @testkase/visual upload ./shots --project "Marketing"
+     env:
+       TESTKASE_TOKEN: ${{ secrets.TESTKASE_TOKEN }}
+   ```
+
+## The filename is the screen name
+
+`shots/home.png` is the screen "home", and next week's `shots/home.png` is
+compared against it. **Keep filenames stable.** If they change, every picture
+looks new — new baselines, nothing compared, build green — and this tool has
+quietly stopped working. Run `--dry-run` first to see the names it will use, and
+watch for the warning it prints when a build matches nothing.
+
+To name screens yourself, use `--name` for one file or `--map` for a folder.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Nothing to review |
+| 1 | Something changed, or a picture could not be uploaded |
+| 2 | The command was wrong — nothing was created |
+
+`npx @testkase/visual --help` is the full reference.

package/dist/api.js

@@ -0,0 +1,114 @@
+"use strict";
+// api.ts — the four calls, over fetch.
+//
+// ⚠️ The token goes in a header and NOWHERE else. Not in a URL, not in a log
+// line, not in an error message — a CI log is a file a lot of people can read,
+// and a leaked personal access token is every project in the org.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Api = exports.ApiError = void 0;
+exports.retryAfterMs = retryAfterMs;
+/**
+ * How many times to wait out a "slow down" before giving up on a picture.
+ *
+ * Four, because the window a rate limit is counted over is a minute: waiting
+ * one out is the whole fix, and a fifth attempt means something else is wrong.
+ */
+const MAX_RETRIES = 4;
+const MAX_BACKOFF_MS = 60_000;
+/**
+ * How long to wait. The server's own `Retry-After` when it sent one — it knows
+ * when its window resets and we are guessing — otherwise a doubling backoff.
+ */
+function retryAfterMs(res, attempt) {
+    const header = res.headers.get("retry-after");
+    const seconds = header ? Number(header) : NaN;
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.min(seconds * 1000 + 250, MAX_BACKOFF_MS);
+    return Math.min(2 ** attempt * 1000, MAX_BACKOFF_MS);
+}
+/** A refusal from the Hub, already phrased for a person. */
+class ApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+exports.ApiError = ApiError;
+class Api {
+    opts;
+    fetch;
+    constructor(opts) {
+        this.opts = opts;
+        this.fetch = opts.fetchImpl ?? globalThis.fetch;
+    }
+    async post(path, body) {
+        for (let attempt = 0;; attempt++) {
+            const res = await this.fetch(`${this.opts.apiUrl}/api/v1/visual/uploads${path}`, {
+                method: "POST",
+                headers: {
+                    "content-type": "application/json",
+                    authorization: `Bearer ${this.opts.token}`,
+                },
+                body: JSON.stringify(body),
+            });
+            if (res.ok)
+                return (await res.json());
+            // ⚠️ Being asked to slow down is not a failed screen. Found on QA: a
+            // 50-picture run 429'd its last seven and then the finish call, and each
+            // one was reported to the customer as a picture that could not be
+            // uploaded. Wait the server's own Retry-After and go again.
+            if (res.status === 429 && attempt < MAX_RETRIES) {
+                await this.wait(retryAfterMs(res, attempt));
+                continue;
+            }
+            const detail = await readError(res);
+            throw new ApiError(res.status, detail.code, detail.message);
+        }
+    }
+    wait(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    startBuild(project, name, from = {}) {
+        // A UUID is a project id; anything else is a name the Hub looks up. Both
+        // work, because CI has a name in a YAML file and the dashboard has an id.
+        const key = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(project)
+            ? { projectId: project }
+            : { project };
+        return this.post("/builds", { ...key, name, ...from });
+    }
+    requestSlot(input) {
+        return this.post("", input);
+    }
+    /** ⚠️ Straight to R2. These bytes never touch our Hub — see the route's header. */
+    async putImage(uploadUrl, bytes) {
+        const res = await this.fetch(uploadUrl, {
+            method: "PUT",
+            headers: { "content-type": "image/png" },
+            body: new Uint8Array(bytes),
+        });
+        if (!res.ok)
+            throw new ApiError(res.status, "UPLOAD_FAILED", `The upload was refused (${res.status}).`);
+    }
+    confirm(snapshotId, slot) {
+        return this.post(`/${snapshotId}/done`, { slot });
+    }
+    finishBuild(buildId) {
+        return this.post(`/builds/${buildId}/finish`, {});
+    }
+}
+exports.Api = Api;
+async function readError(res) {
+    try {
+        const body = (await res.json());
+        return {
+            code: body.error?.code ?? "REQUEST_FAILED",
+            message: body.error?.message ?? `The request failed (${res.status}).`,
+        };
+    }
+    catch {
+        return { code: "REQUEST_FAILED", message: `The request failed (${res.status}).` };
+    }
+}

package/dist/args.js

@@ -0,0 +1,120 @@
+"use strict";
+// args.ts — the flags, and the refusals that happen before anything is created.
+//
+// Everything here is pure: argv in, a decision out. The point is that a bad
+// command line fails BEFORE a build exists, because a build created and then
+// abandoned is one a reviewer has to look at and close by hand.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UsageError = exports.DEFAULT_APP_URL = exports.DEFAULT_API_URL = exports.MAX_CONCURRENCY = exports.MIN_CONCURRENCY = exports.DEFAULT_CONCURRENCY = void 0;
+exports.clampConcurrency = clampConcurrency;
+exports.parseArgs = parseArgs;
+exports.exitCodeFor = exitCodeFor;
+exports.DEFAULT_CONCURRENCY = 5;
+exports.MIN_CONCURRENCY = 1;
+exports.MAX_CONCURRENCY = 10;
+exports.DEFAULT_API_URL = "https://hub.testkase.com";
+exports.DEFAULT_APP_URL = "https://visual.testkase.com";
+/** A refusal a person can act on, with the exit code CI should see. */
+class UsageError extends Error {
+    exitCode = 2;
+}
+exports.UsageError = UsageError;
+const FLAGS_WITH_VALUES = new Set([
+    "--project", "--token", "--build", "--build-name", "--name", "--map",
+    "--browser", "--os", "--files", "--ignore", "--concurrency", "--api-url",
+    "--branch", "--commit", "--pr", "--app-url",
+]);
+/**
+ * ⚠️ `--concurrency` is clamped, not rejected. Somebody who writes `--concurrency 200`
+ * wants "as fast as you can", and refusing the command over it would fail a
+ * pipeline for a number that has no wrong answer. Ten is where R2 stops going
+ * faster and starts returning 503s.
+ */
+function clampConcurrency(n) {
+    if (!Number.isFinite(n))
+        return exports.DEFAULT_CONCURRENCY;
+    return Math.min(exports.MAX_CONCURRENCY, Math.max(exports.MIN_CONCURRENCY, Math.floor(n)));
+}
+function splitList(value) {
+    return value.split(",").map((s) => s.trim()).filter(Boolean);
+}
+function parseArgs(argv, env = {}) {
+    const positional = [];
+    const flags = {};
+    const bools = new Set();
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith("--")) {
+            positional.push(arg);
+            continue;
+        }
+        const eq = arg.indexOf("=");
+        const key = eq < 0 ? arg : arg.slice(0, eq);
+        if (FLAGS_WITH_VALUES.has(key)) {
+            const value = eq < 0 ? argv[++i] : arg.slice(eq + 1);
+            if (value === undefined)
+                throw new UsageError(`${key} needs a value.`);
+            // Repeatable, so --files a --files b reads the way it looks.
+            flags[key] = flags[key] ? `${flags[key]},${value}` : value;
+        }
+        else {
+            bools.add(key);
+        }
+    }
+    const unknown = [...bools].filter((f) => !["--dry-run", "--exit-zero-on-changes", "--no-finish", "--no-github", "--help", "-h", "--version"].includes(f));
+    if (unknown.length)
+        throw new UsageError(`I don't know the flag ${unknown[0]}.`);
+    const folder = positional[0];
+    if (!folder)
+        throw new UsageError("Tell me which folder to upload: testkase-visual upload ./screenshots --project <name>");
+    // ⚠️ Required, never guessed. The New run dialog made this mistake once: it
+    // quietly used whichever project was to hand, so a run compared against
+    // another project's baselines with nothing on screen saying which. In CI
+    // nobody is looking at all.
+    const project = flags["--project"] ?? env.TESTKASE_PROJECT;
+    if (!project)
+        throw new UsageError("--project is required. It's the project in TestKase these screens belong to.");
+    const token = flags["--token"] ?? env.TESTKASE_TOKEN;
+    if (!token)
+        throw new UsageError("No access token. Set TESTKASE_TOKEN, or pass --token.");
+    return {
+        folder,
+        project,
+        token,
+        build: flags["--build"],
+        buildName: flags["--build-name"] ?? env.TESTKASE_BUILD_NAME,
+        // Overrides for a setup we do not recognise. Left undefined, ci.ts reads
+        // the environment; it never guesses when it cannot tell.
+        branch: flags["--branch"],
+        commit: flags["--commit"],
+        pullRequest: flags["--pr"],
+        name: flags["--name"],
+        mapFile: flags["--map"],
+        browser: flags["--browser"] ?? "upload",
+        os: flags["--os"] ?? "ci",
+        files: splitList(flags["--files"] ?? "**/*.png"),
+        ignore: splitList(flags["--ignore"] ?? ""),
+        concurrency: flags["--concurrency"] ? clampConcurrency(Number(flags["--concurrency"])) : exports.DEFAULT_CONCURRENCY,
+        dryRun: bools.has("--dry-run"),
+        exitZeroOnChanges: bools.has("--exit-zero-on-changes"),
+        // A sharded suite runs this on five machines and finishes ONCE, on the last.
+        finish: !bools.has("--no-finish"),
+        apiUrl: (flags["--api-url"] ?? env.TESTKASE_API_URL ?? exports.DEFAULT_API_URL).replace(/\/+$/, ""),
+        // ⚠️ Where the "Details" link points. A constant rather than something the
+        // Hub tells us: the Hub does not reliably know its own public address —
+        // PUBLIC_APP_URL is set by nothing today — so asking it would be a guess
+        // dressed up as an answer.
+        appUrl: (flags["--app-url"] ?? env.TESTKASE_APP_URL ?? exports.DEFAULT_APP_URL).replace(/\/+$/, ""),
+        github: !bools.has("--no-github"),
+    };
+}
+/**
+ * ⚠️ The exit code IS the integration. 1 when anything needs a person to look at
+ * it, 0 otherwise — a pipeline that only prints a warning is a pipeline that
+ * ships the change.
+ */
+function exitCodeFor(summary, opts) {
+    if (opts.exitZeroOnChanges)
+        return 0;
+    return summary.unreviewed > 0 ? 1 : 0;
+}

package/dist/ci.js

@@ -0,0 +1,167 @@
+"use strict";
+// ci.ts — where did this build come from?
+//
+// Every CI system already knows the branch, the commit and the pull request. It
+// puts them in the environment under a different name each time, which is the
+// only reason this file exists.
+//
+// ⚠️ Nothing here GUESSES. If we cannot tell which branch a run came from, the
+// answer is nothing at all — never a plausible-looking default. A build labelled
+// with the wrong branch is worse than one labelled with none, because somebody
+// will believe it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectCi = detectCi;
+exports.provenance = provenance;
+exports.describe = describe;
+const first = (env, ...names) => {
+    for (const n of names) {
+        const v = env[n]?.trim();
+        if (v)
+            return v;
+    }
+    return undefined;
+};
+/**
+ * GitHub Actions names the branch differently depending on the event.
+ *
+ * On a pull request, GITHUB_REF_NAME is "214/merge" — the synthetic merge ref,
+ * not a branch anybody has. GITHUB_HEAD_REF is the actual source branch and is
+ * set ONLY on pull_request events, which is exactly the signal we want: prefer
+ * it, fall back to GITHUB_REF_NAME for a push.
+ */
+function github(env) {
+    const pr = first(env, "GITHUB_PR_NUMBER") ?? prFromRef(env.GITHUB_REF);
+    return {
+        branch: first(env, "GITHUB_HEAD_REF", "GITHUB_REF_NAME") ?? stripRef(env.GITHUB_REF),
+        commit: first(env, "GITHUB_SHA"),
+        pullRequest: pr,
+    };
+}
+/** "refs/pull/214/merge" → "214". Nothing else in the environment carries it. */
+function prFromRef(ref) {
+    const m = /^refs\/pull\/(\d+)\//.exec(ref ?? "");
+    return m ? m[1] : undefined;
+}
+/** "refs/heads/main" → "main". Left alone if it is not a ref. */
+function stripRef(ref) {
+    if (!ref)
+        return undefined;
+    return ref.replace(/^refs\/heads\//, "") || undefined;
+}
+/**
+ * Each detector is tried in order and the FIRST whose marker variable is set
+ * wins. Order matters where they overlap: several tools set CI=true, and
+ * Jenkins-style GIT_BRANCH appears in other places too, so the generic
+ * fallbacks come last.
+ */
+const DETECTORS = [
+    { name: "github", when: (e) => Boolean(e.GITHUB_ACTIONS), read: github },
+    {
+        name: "gitlab",
+        when: (e) => Boolean(e.GITLAB_CI),
+        read: (e) => ({
+            branch: first(e, "CI_COMMIT_REF_NAME", "CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"),
+            commit: first(e, "CI_COMMIT_SHA"),
+            pullRequest: first(e, "CI_MERGE_REQUEST_IID"),
+        }),
+    },
+    {
+        name: "circleci",
+        when: (e) => Boolean(e.CIRCLECI),
+        read: (e) => ({
+            branch: first(e, "CIRCLE_BRANCH"),
+            commit: first(e, "CIRCLE_SHA1"),
+            // CircleCI gives the PR's URL, not its number.
+            pullRequest: prFromUrl(first(e, "CIRCLE_PULL_REQUEST")),
+        }),
+    },
+    {
+        name: "bitbucket",
+        when: (e) => Boolean(e.BITBUCKET_BUILD_NUMBER),
+        read: (e) => ({
+            branch: first(e, "BITBUCKET_BRANCH"),
+            commit: first(e, "BITBUCKET_COMMIT"),
+            pullRequest: first(e, "BITBUCKET_PR_ID"),
+        }),
+    },
+    {
+        name: "buildkite",
+        when: (e) => Boolean(e.BUILDKITE),
+        read: (e) => ({
+            branch: first(e, "BUILDKITE_BRANCH"),
+            commit: first(e, "BUILDKITE_COMMIT"),
+            // Buildkite sets this to the literal string "false" when there is no PR.
+            pullRequest: notFalse(first(e, "BUILDKITE_PULL_REQUEST")),
+        }),
+    },
+    {
+        name: "jenkins",
+        when: (e) => Boolean(e.JENKINS_URL || e.BUILD_NUMBER),
+        read: (e) => ({
+            branch: stripOrigin(first(e, "BRANCH_NAME", "GIT_BRANCH")),
+            commit: first(e, "GIT_COMMIT"),
+            pullRequest: first(e, "CHANGE_ID"),
+        }),
+    },
+    {
+        // Anything else that sets CI, plus the variables people wire up by hand.
+        name: "generic",
+        when: (e) => Boolean(e.CI),
+        read: (e) => ({
+            branch: stripRef(first(e, "GIT_BRANCH", "BRANCH_NAME", "BRANCH")),
+            commit: first(e, "GIT_COMMIT", "COMMIT_SHA", "SHA"),
+            pullRequest: first(e, "PULL_REQUEST", "PR_NUMBER"),
+        }),
+    },
+];
+function prFromUrl(url) {
+    const m = /\/(\d+)\/?$/.exec(url ?? "");
+    return m ? m[1] : undefined;
+}
+/** Buildkite says "false"; Jenkins-style vars sometimes say "null". */
+function notFalse(v) {
+    return v && v !== "false" && v !== "null" ? v : undefined;
+}
+/** Jenkins reports "origin/main" for a checkout of main. */
+function stripOrigin(v) {
+    return v?.replace(/^origin\//, "") || undefined;
+}
+/**
+ * What the environment says about this run, and which system said it.
+ *
+ * Returns `{}` when nothing recognisable is set — running on a laptop is a
+ * perfectly ordinary thing to do, and it is not an error.
+ */
+function detectCi(env = process.env) {
+    for (const d of DETECTORS) {
+        if (!d.when(env))
+            continue;
+        const p = d.read(env);
+        // A detector that matched but found nothing useful should not stop the
+        // search — a stray CI=true would otherwise shadow a real one behind it.
+        if (p.branch || p.commit || p.pullRequest)
+            return { ...p, ci: d.name };
+    }
+    return {};
+}
+/** What the flags say, then what the environment says. A flag always wins. */
+function provenance(flags, env = process.env) {
+    const found = detectCi(env);
+    return {
+        ci: found.ci,
+        branch: flags.branch ?? found.branch,
+        commit: flags.commit ?? found.commit,
+        pullRequest: flags.pullRequest ?? found.pullRequest,
+    };
+}
+/** "feature/blue-button · a1b2c3d · PR #214", or nothing at all. */
+function describe(p) {
+    const parts = [];
+    if (p.branch)
+        parts.push(p.branch);
+    if (p.commit)
+        parts.push(p.commit.slice(0, 7));
+    if (p.pullRequest)
+        parts.push(`PR #${p.pullRequest}`);
+    return parts.join(" · ");
+}

package/dist/github.js

@@ -0,0 +1,196 @@
+"use strict";
+// github.ts — telling the pull request what changed.
+//
+// A visual tool nobody looks at is a visual tool that is not working. Today a
+// changed screen shows up as `exit code 1` in a CI log, and the developer has to
+// guess it was us, open the dashboard, find the project, find the build. Most
+// will assume the suite is flaky and press re-run.
+//
+// So we post the result where they are already looking: a check in the pull
+// request's list, and one comment.
+//
+// ⚠️ WE HOLD NO CREDENTIALS. This runs inside the customer's own pipeline, which
+// is already logged in to their repository. The alternative — storing a GitHub
+// token per customer — is a far bigger security surface for the same outcome.
+//
+// ⚠️ AND IT NEVER FAILS THEIR BUILD. Every call here is best-effort. If GitHub
+// refuses, we print one line and carry on with the real result: a visual tool
+// that breaks a pipeline because it could not leave a comment is worse than one
+// that stays quiet.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMENT_MARKER = void 0;
+exports.headSha = headSha;
+exports.githubTarget = githubTarget;
+exports.checkState = checkState;
+exports.checkDescription = checkDescription;
+exports.commentBody = commentBody;
+exports.postToPullRequest = postToPullRequest;
+const fs_1 = require("fs");
+/** Ours, so we can edit our own comment instead of adding another one. */
+exports.COMMENT_MARKER = "<!-- testkase-visual -->";
+/**
+ * The commit a check must be attached to.
+ *
+ * ⚠️ On a pull request, GITHUB_SHA is a MERGE COMMIT GitHub invents for the
+ * run — it is not on either branch, and a status posted there appears nowhere.
+ * The head commit is in the event payload GitHub writes to disk, which is the
+ * only place it is available.
+ *
+ * Getting this wrong does not error. It posts happily to a commit nobody looks
+ * at, and the feature silently does nothing — the worst way for it to fail.
+ */
+function headSha(env, readFile = fs_1.readFileSync) {
+    const path = env.GITHUB_EVENT_PATH;
+    if (path) {
+        try {
+            const event = JSON.parse(String(readFile(path, "utf8")));
+            const head = event.pull_request?.head?.sha;
+            if (head)
+                return head;
+        }
+        catch {
+            // A push event has no pull_request, and an unreadable file is not worth
+            // failing over. GITHUB_SHA is correct for a push.
+        }
+    }
+    return env.GITHUB_SHA;
+}
+/**
+ * Everything needed to post, or nothing.
+ *
+ * ⚠️ All four parts or none. A token without a repository, or a repository
+ * without a commit, cannot post anything — and half-configured must behave
+ * exactly like not configured, silently, because running on a laptop is
+ * ordinary.
+ */
+function githubTarget(env, pullRequest, readFile = fs_1.readFileSync) {
+    const token = env.GITHUB_TOKEN ?? env.GH_TOKEN;
+    const repo = env.GITHUB_REPOSITORY;
+    const sha = headSha(env, readFile);
+    if (!token || !repo || !sha)
+        return null;
+    return { token, repo, sha, pullRequest };
+}
+/** Red when somebody has to look, green when nobody does. */
+function checkState(o) {
+    return o.unreviewed > 0 || o.failed > 0 ? "failure" : "success";
+}
+/** The one line that shows in the checks list. It has to say the number. */
+function checkDescription(o) {
+    if (o.failed > 0 && o.unreviewed === 0) {
+        return `${o.failed} ${o.failed === 1 ? "picture" : "pictures"} could not be compared`;
+    }
+    if (o.unreviewed > 0) {
+        const s = `${o.unreviewed} ${o.unreviewed === 1 ? "screen" : "screens"} to review`;
+        return o.failed > 0 ? `${s}, ${o.failed} could not be compared` : s;
+    }
+    if (o.newBaselines > 0 && o.total === o.newBaselines) {
+        return `${o.newBaselines} new ${o.newBaselines === 1 ? "screen" : "screens"}, nothing to compare yet`;
+    }
+    return `${o.total} ${o.total === 1 ? "screen" : "screens"} checked, no changes`;
+}
+/** The comment body. Markdown, short, and led by the thing that needs doing. */
+function commentBody(o) {
+    const lines = [exports.COMMENT_MARKER, "### TestKase Visual", ""];
+    if (o.unreviewed > 0) {
+        lines.push(`**${o.unreviewed} ${o.unreviewed === 1 ? "screen needs" : "screens need"} a look.** [Review ${o.unreviewed === 1 ? "it" : "them"}](${o.reviewUrl})`);
+    }
+    else if (o.failed > 0) {
+        lines.push(`**${o.failed} ${o.failed === 1 ? "picture" : "pictures"} could not be compared.** The ${o.failed === 1 ? "picture is" : "pictures are"} saved — running the build again is enough.`);
+    }
+    else {
+        lines.push(`No visual changes. [See the build](${o.reviewUrl})`);
+    }
+    lines.push("", `${o.total} screens · ${o.changed} changed · ${o.newBaselines} new`);
+    return lines.join("\n");
+}
+const API = "https://api.github.com";
+async function call(target, path, init, f) {
+    return f(`${API}${path}`, {
+        method: init.method,
+        headers: {
+            accept: "application/vnd.github+json",
+            authorization: `Bearer ${target.token}`,
+            "x-github-api-version": "2022-11-28",
+            "content-type": "application/json",
+        },
+        body: init.body === undefined ? undefined : JSON.stringify(init.body),
+    });
+}
+/**
+ * Post the check and the comment. Never throws.
+ *
+ * The two are independent on purpose: a repository may allow one and not the
+ * other, and getting half of it is better than getting none.
+ */
+async function postToPullRequest(target, outcome, deps = {}) {
+    const f = deps.fetchImpl ?? globalThis.fetch;
+    const warn = deps.warn ?? (() => { });
+    const result = { status: false, comment: false };
+    try {
+        const res = await call(target, `/repos/${target.repo}/statuses/${target.sha}`, {
+            method: "POST",
+            body: {
+                state: checkState(outcome),
+                context: "TestKase Visual",
+                description: checkDescription(outcome),
+                target_url: outcome.reviewUrl,
+            },
+        }, f);
+        result.status = res.ok;
+        if (!res.ok)
+            warn(explain("post the check", res.status));
+    }
+    catch {
+        warn("Couldn't reach GitHub to post the check.");
+    }
+    if (target.pullRequest) {
+        try {
+            result.comment = await upsertComment(target, outcome, f, warn);
+        }
+        catch {
+            warn("Couldn't reach GitHub to leave a comment.");
+        }
+    }
+    return result;
+}
+/**
+ * One comment, edited.
+ *
+ * ⚠️ A branch with twelve pushes must not collect twelve comments — that is how
+ * a useful tool becomes one people mute. We find our own by a hidden marker and
+ * edit it; a new one is posted only the first time.
+ */
+async function upsertComment(target, outcome, f, warn) {
+    const body = commentBody(outcome);
+    const list = await call(target, `/repos/${target.repo}/issues/${target.pullRequest}/comments?per_page=100`, { method: "GET" }, f);
+    if (list.ok) {
+        const comments = (await list.json());
+        const mine = comments.find((c) => c.body?.includes(exports.COMMENT_MARKER));
+        if (mine) {
+            const patched = await call(target, `/repos/${target.repo}/issues/comments/${mine.id}`, { method: "PATCH", body: { body } }, f);
+            if (!patched.ok)
+                warn(explain("update the comment", patched.status));
+            return patched.ok;
+        }
+    }
+    const posted = await call(target, `/repos/${target.repo}/issues/${target.pullRequest}/comments`, { method: "POST", body: { body } }, f);
+    if (!posted.ok)
+        warn(explain("leave a comment", posted.status));
+    return posted.ok;
+}
+/**
+ * Why GitHub said no, in words a person can act on.
+ *
+ * ⚠️ 403 is the one that will actually happen, and "403" tells nobody anything.
+ * The workflow needs permissions granted explicitly, and that line is what they
+ * are missing.
+ */
+function explain(what, status) {
+    if (status === 403 || status === 404) {
+        return `Couldn't ${what} on GitHub — the workflow needs "permissions: statuses: write, pull-requests: write".`;
+    }
+    if (status === 401)
+        return `Couldn't ${what} on GitHub — the token was refused.`;
+    return `Couldn't ${what} on GitHub (${status}).`;
+}

package/dist/glob.js

@@ -0,0 +1,58 @@
+"use strict";
+// glob.ts — just enough globbing for --files and --ignore.
+//
+// A dependency for this would be a supply-chain risk in a package customers run
+// inside their CI with a token in the environment. The patterns people actually
+// write here are `**/*.png`, `shots/**`, `**/*-mobile.png`, so that is what this
+// supports: `**` across directories, `*` within one, `?` for a character.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globToRegExp = globToRegExp;
+exports.matchesAny = matchesAny;
+exports.selectFiles = selectFiles;
+function escapeLiteral(text) {
+    return text.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+}
+/** A glob as a regular expression, anchored, matching forward-slash paths. */
+function globToRegExp(pattern) {
+    let out = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            if (pattern[i + 1] === "*") {
+                i++;
+                // `a/**/b` should also match `a/b`, so swallow the slash with the stars.
+                if (pattern[i + 1] === "/") {
+                    i++;
+                    out += "(?:.*/)?";
+                }
+                else {
+                    out += ".*";
+                }
+            }
+            else {
+                out += "[^/]*";
+            }
+        }
+        else if (ch === "?") {
+            out += "[^/]";
+        }
+        else if (ch === "/") {
+            out += "/";
+        }
+        else {
+            out += escapeLiteral(ch);
+        }
+    }
+    return new RegExp(`^${out}$`, "i");
+}
+function matchesAny(path, patterns) {
+    const normalised = path.replace(/\\/g, "/").replace(/^\.\//, "");
+    return patterns.some((p) => globToRegExp(p.replace(/^\.\//, "")).test(normalised));
+}
+/** The files to upload: everything `--files` picks, minus everything `--ignore` does. */
+function selectFiles(paths, include, ignore) {
+    return paths
+        .filter((p) => matchesAny(p, include))
+        .filter((p) => ignore.length === 0 || !matchesAny(p, ignore))
+        .sort();
+}

package/dist/help.js

@@ -0,0 +1,96 @@
+"use strict";
+// help.ts — the first thing anyone runs, so it is written to be read.
+//
+// Two things in here are not decoration. The full-page one-liners, because we
+// do NOT take the picture in this model and a customer who uploads
+// viewport-sized shots gets a tool that only ever checks the top of a page. And
+// the sentence about filenames, because a suite whose filenames drift gets a
+// tool that compares nothing at all and says everything is fine.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.HELP = `
+@testkase/visual — upload your test suite's screenshots and get told what changed.
+
+  npx @testkase/visual upload ./screenshots --project "Marketing"
+
+Your tests take the pictures; this uploads them, compares each one against the
+last approved version, and fails the build when something needs a person to look
+at it. It works with any framework, because a folder of PNGs is not a framework.
+
+REQUIRED
+  --project <name|id>   The TestKase project these screens belong to. Never
+                        guessed: the wrong project compares against the wrong
+                        baselines and nobody notices for weeks.
+  TESTKASE_TOKEN        Your access token, in the environment. Or --token.
+
+THE FILENAME IS THE SCREEN NAME
+  shots/home.png is the screen "home", and next week's shots/home.png is
+  compared against it. Keep filenames stable. If they change, every picture
+  looks new: new baselines, nothing compared, build green, and this tool has
+  quietly stopped working. Run --dry-run first to see the names it will use.
+
+TAKE THE WHOLE PAGE, NOT THE FIRST SCREENFUL
+  Playwright   await page.screenshot({ path: "shots/home.png", fullPage: true })
+  Puppeteer    await page.screenshot({ path: "shots/home.png", fullPage: true })
+  Cypress      cy.screenshot("home", { capture: "fullPage" })
+  Selenium     needs a helper, or CDP captureBeyondViewport
+  A page that grows taller still compares against its baseline: we match on the
+  picture's WIDTH, not its height, so adding a row to a table is a change to
+  review rather than a brand-new screen.
+
+OPTIONS
+  --dry-run             Print the names and upload nothing.
+  --name <name>         Name a single file yourself.
+  --map <file>          Name many: one "file = screen name" per line (or JSON).
+                        Anything not listed keeps its filename.
+  --files <glob>        Which files to upload. Default **/*.png
+  --ignore <glob>       Which to skip. Repeatable, or comma-separated.
+  --browser <name>      Default "upload". Pass it if you run the same suite on
+                        two browsers — you want two sets of baselines.
+  --os <name>           Default "ci".
+  --concurrency <n>     Uploads at once. Default 5, most 10.
+  --build <id>          Add to an existing build, for a sharded suite.
+  --build-name <name>   Label the build.
+  --branch / --commit / --pr
+                        Where this run came from. Read automatically from your
+                        CI (GitHub Actions, GitLab, CircleCI, Bitbucket,
+                        Buildkite, Jenkins) — pass these only if yours is not
+                        recognised. Outside CI we say nothing rather than guess.
+  --no-finish           Leave the build open. Shards 1..4 use this; the last one
+                        doesn't, and that is the run that reports the result.
+  --exit-zero-on-changes
+                        Always exit 0. For the first pipeline you add this to,
+                        before anyone has approved anything.
+  --no-github           Do not post the result to the pull request.
+  --api-url <url>       Point at another Hub. You will not need this.
+  --app-url <url>       Where the "Details" link should point.
+
+ON A PULL REQUEST
+  Running inside GitHub Actions, this posts the result where the developer is
+  already looking: a check in the pull request's list, and one comment that is
+  edited on each run rather than added to. Give the job permission:
+
+    permissions:
+      statuses: write
+      pull-requests: write
+    env:
+      GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+
+  We hold no credentials of yours — this runs inside your own pipeline, which is
+  already logged in. If GitHub refuses, you get one line and the real result;
+  it will never fail your build on our behalf.
+
+EXIT CODES
+  0  nothing to review
+  1  something changed, or a picture could not be uploaded
+  2  the command was wrong — nothing was created
+
+A SHARDED SUITE
+  The first machine starts the build and leaves it open. It prints the id:
+    npx @testkase/visual upload ./shot-1 --project Marketing --no-finish
+  The rest join it, and the last one finishes it — that run is the one that
+  reports the result and sets the exit code:
+    npx @testkase/visual upload ./shot-2 --project Marketing --build <id> --no-finish
+    npx @testkase/visual upload ./shot-3 --project Marketing --build <id>
+  Without this, five machines make five builds and the reviewer sees five lists.
+`.trim();

package/dist/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+"use strict";
+// index.ts — the command.
+//
+// Everything real happens in upload.ts; this is the part that talks to the
+// operating system: reads the folder, prints the lines, picks the exit code.
+Object.defineProperty(exports, "__esModule", { value: true });
+const promises_1 = require("fs/promises");
+const path_1 = require("path");
+const args_1 = require("./args");
+const api_1 = require("./api");
+const upload_1 = require("./upload");
+const help_1 = require("./help");
+async function walk(folder) {
+    const out = [];
+    async function visit(dir) {
+        const entries = await (0, promises_1.readdir)(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = (0, path_1.join)(dir, entry.name);
+            if (entry.isDirectory())
+                await visit(full);
+            else if (entry.isFile())
+                out.push((0, path_1.relative)(folder, full).split(path_1.sep).join("/"));
+        }
+    }
+    await visit(folder);
+    return out;
+}
+async function main(argv) {
+    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write(`${help_1.HELP}\n`);
+        return 0;
+    }
+    if (argv.includes("--version")) {
+        process.stdout.write(`${require("../package.json").version}\n`);
+        return 0;
+    }
+    // `upload` is the only verb today, and optional, so both of these work:
+    //   testkase-visual upload ./shots --project X
+    //   testkase-visual ./shots --project X
+    const args = argv[0] === "upload" ? argv.slice(1) : argv;
+    const opts = (0, args_1.parseArgs)(args, process.env);
+    const api = new api_1.Api({ apiUrl: opts.apiUrl, token: opts.token });
+    const result = await (0, upload_1.run)(opts, {
+        api,
+        list: walk,
+        read: (path) => (0, promises_1.readFile)(path),
+        readText: (path) => (0, promises_1.readFile)(path, "utf8"),
+        out: (line) => process.stdout.write(`${line}\n`),
+    });
+    return result.exitCode;
+}
+main(process.argv.slice(2))
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((err) => {
+    // ⚠️ The message only. A stack trace in a CI log tells a reader our file
+    // layout, and tells the person running it nothing they can act on.
+    if (err instanceof args_1.UsageError) {
+        process.stderr.write(`${err.message}\n\nRun testkase-visual --help.\n`);
+        process.exitCode = err.exitCode;
+        return;
+    }
+    if (err instanceof api_1.ApiError) {
+        process.stderr.write(`${err.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const code = err.code;
+    if (code === "ENOENT") {
+        process.stderr.write("I couldn't find that folder.\n");
+        process.exitCode = 2;
+        return;
+    }
+    process.stderr.write(`${err instanceof Error ? err.message : "Something went wrong."}\n`);
+    process.exitCode = 1;
+});

package/dist/names.js

@@ -0,0 +1,77 @@
+"use strict";
+// names.ts — which screen a file is.
+//
+// ⚠️ In this model the FILENAME is the identity. `shots/home.png` is the screen
+// "home", and next week's `shots/home.png` is compared against it. That makes a
+// renamed file the dangerous failure — forty new baselines, nothing compared,
+// build green, and the tool has quietly stopped working.
+//
+// Which is why the transform below is deliberately boring: strip the directory,
+// strip the extension, and stop. Anything cleverer — lower-casing, replacing
+// dashes with spaces, trimming a numeric suffix — is a name that CHANGES when we
+// improve it, and every baseline in every customer's project is orphaned by the
+// improvement. `cart--empty.png` is the screen `cart--empty`.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.screenNameFor = screenNameFor;
+exports.parseNameMap = parseNameMap;
+exports.resolveName = resolveName;
+const path_1 = require("path");
+/** The screen name a file gets when nobody has said otherwise. */
+function screenNameFor(file) {
+    const base = (0, path_1.basename)(file.replace(/\\/g, "/"));
+    const ext = (0, path_1.extname)(base);
+    return ext ? base.slice(0, -ext.length) : base;
+}
+/**
+ * A map file: one `path = screen name` per line, `#` comments, blank lines
+ * ignored. Also accepts JSON, because half of CI writes JSON and being strict
+ * about which buys nothing.
+ *
+ * Keys are matched against the path AS GIVEN and against its bare filename, so
+ * both `shots/home.png` and `home.png` work in the file.
+ */
+function parseNameMap(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{")) {
+        const parsed = JSON.parse(trimmed);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("The map file must be an object of file → screen name.");
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(parsed)) {
+            if (typeof v !== "string")
+                throw new Error(`The map file's "${k}" is not a name.`);
+            out[normaliseKey(k)] = v.trim();
+        }
+        return out;
+    }
+    const out = {};
+    for (const line of trimmed.split(/\r?\n/)) {
+        const row = line.trim();
+        if (!row || row.startsWith("#"))
+            continue;
+        const at = row.indexOf("=");
+        if (at < 0)
+            throw new Error(`The map file's line "${row}" is not "file = name".`);
+        const key = row.slice(0, at).trim();
+        const value = row.slice(at + 1).trim();
+        if (!key || !value)
+            throw new Error(`The map file's line "${row}" is not "file = name".`);
+        out[normaliseKey(key)] = value;
+    }
+    return out;
+}
+function normaliseKey(key) {
+    return key.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/**
+ * The name for one file, in the order the flags are documented:
+ * `--name` (a single file), then the map, then the filename.
+ */
+function resolveName(file, opts) {
+    if (opts.name)
+        return opts.name;
+    const map = opts.map ?? {};
+    const key = normaliseKey(file);
+    return map[key] ?? map[(0, path_1.basename)(key)] ?? screenNameFor(file);
+}

package/dist/png.js

@@ -0,0 +1,26 @@
+"use strict";
+// png.ts — how big is this picture?
+//
+// The viewport a baseline is keyed on (migration 113) is, for an uploaded
+// image, the image's own size — so we have to read it before we can ask for a
+// slot. A PNG's width and height are the two 32-bit integers at the start of the
+// IHDR chunk, always the first chunk, always at the same offset. That is eight
+// bytes of a file we already have in memory, which is the entire reason this
+// tool has no image dependency.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pngSize = pngSize;
+const MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** The picture's size, or an explanation of why it isn't a PNG. */
+function pngSize(buf) {
+    if (buf.length < 24 || !buf.subarray(0, 8).equals(MAGIC)) {
+        throw new Error("that isn't a PNG");
+    }
+    if (buf.subarray(12, 16).toString("ascii") !== "IHDR") {
+        throw new Error("that PNG is damaged");
+    }
+    const width = buf.readUInt32BE(16);
+    const height = buf.readUInt32BE(20);
+    if (width < 1 || height < 1)
+        throw new Error("that PNG has no size");
+    return { width, height };
+}

package/dist/upload.js

@@ -0,0 +1,207 @@
+"use strict";
+// upload.ts — the run itself, with everything it touches injected.
+//
+// The file system, the clock, the API and where output goes all arrive as
+// arguments, so the whole loop is testable without a network, a folder or a
+// Hub — which matters because the interesting cases here are the failures.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const api_1 = require("./api");
+const png_1 = require("./png");
+const names_1 = require("./names");
+const glob_1 = require("./glob");
+const ci_1 = require("./ci");
+const github_1 = require("./github");
+/** How many pictures are in flight at once. Bounded, so a big folder cannot open
+ *  a thousand sockets and be throttled into looking broken. */
+async function inParallel(items, limit, work) {
+    let next = 0;
+    const runners = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            await work(items[index]);
+        }
+    });
+    await Promise.all(runners);
+}
+async function run(opts, deps) {
+    const all = await deps.list(opts.folder);
+    const files = (0, glob_1.selectFiles)(all, opts.files, opts.ignore);
+    if (files.length === 0) {
+        deps.out(`No pictures matched ${opts.files.join(", ")} in ${opts.folder}.`);
+        return { outcomes: [], exitCode: 0 };
+    }
+    const map = opts.mapFile ? (0, names_1.parseNameMap)(await deps.readText(opts.mapFile)) : undefined;
+    // --name is for ONE file. Applying it to forty would give forty pictures the
+    // same identity and the last one uploaded would win, silently.
+    if (opts.name && files.length > 1) {
+        throw new api_1.ApiError(0, "NAME_FOR_ONE", "--name works on a single file. For a folder, use --map.");
+    }
+    const named = files.map((file) => ({ file, screenName: (0, names_1.resolveName)(file, { name: opts.name, map }) }));
+    const duplicates = findDuplicates(named);
+    if (duplicates.length) {
+        // Two files, one identity: the second overwrites the first's comparison and
+        // the build looks complete. Better to stop than to report a lie.
+        throw new api_1.ApiError(0, "DUPLICATE_NAME", `Two files would be the same screen: ${duplicates[0]}. Rename one, or use --map.`);
+    }
+    if (opts.dryRun) {
+        deps.out(`${named.length} pictures would be uploaded to project "${opts.project}":`);
+        for (const item of named)
+            deps.out(`  ${item.file}  →  ${item.screenName}`);
+        deps.out("");
+        deps.out("Nothing was uploaded. Check the names on the right: they are what a");
+        deps.out("screen is matched by, so they must stay the same between runs.");
+        return { outcomes: [], exitCode: 0 };
+    }
+    // Where this run came from. Recorded on the build, and shown so a person
+    // can see at a glance which code produced these pictures.
+    const from = (0, ci_1.provenance)({ branch: opts.branch, commit: opts.commit, pullRequest: opts.pullRequest }, deps.env ?? process.env);
+    const build = opts.build
+        ? { buildId: opts.build, number: null, projectName: opts.project, remaining: NaN }
+        : await deps.api.startBuild(opts.project, opts.buildName, from);
+    deps.out(build.number == null
+        ? `Adding to build ${build.buildId}.`
+        : `Build ${build.number} of "${build.projectName}" — ${named.length} pictures.`);
+    const where = (0, ci_1.describe)(from);
+    if (where)
+        deps.out(`  ${where}`);
+    const outcomes = [];
+    await inParallel(named, opts.concurrency, async (item) => {
+        try {
+            const bytes = await deps.read(joinPath(opts.folder, item.file));
+            const size = (0, png_1.pngSize)(bytes);
+            const slot = await deps.api.requestSlot({
+                buildId: build.buildId,
+                screenName: item.screenName,
+                width: size.width,
+                height: size.height,
+                browser: opts.browser,
+                os: opts.os,
+            });
+            await deps.api.putImage(slot.uploadUrl, bytes);
+            const result = await deps.api.confirm(slot.snapshotId, slot.slot);
+            outcomes.push({
+                file: item.file,
+                screenName: item.screenName,
+                status: result.status,
+                diffRatio: result.diffRatio,
+                // A "failed" line with nothing after it tells nobody anything. The
+                // first QA run printed three of them.
+                error: result.status === "failed" ? explain(result.failure) : undefined,
+            });
+        }
+        catch (err) {
+            // One bad picture does not abandon thirty-nine good ones. It is reported,
+            // and it makes the run fail at the end.
+            outcomes.push({
+                file: item.file,
+                screenName: item.screenName,
+                status: "error",
+                error: err instanceof Error ? err.message : "something went wrong",
+            });
+        }
+    });
+    outcomes.sort((a, b) => a.screenName.localeCompare(b.screenName));
+    report(outcomes, deps.out);
+    if (!opts.finish) {
+        deps.out("");
+        deps.out(`Build ${build.buildId} is still open — finish it on the last shard.`);
+        return { buildId: build.buildId, outcomes, exitCode: failures(outcomes) > 0 ? 1 : 0 };
+    }
+    const summary = await deps.api.finishBuild(build.buildId);
+    deps.out("");
+    deps.out(`${summary.total} screens · ${summary.changed} changed · ${summary.newBaselines} new · ${summary.unreviewed} to review`);
+    // ⚠️ The silent failure this tool is most likely to have. Loud on purpose.
+    if (summary.renamedFilesSuspected) {
+        deps.out("");
+        deps.out(`⚠ ${summary.newBaselines} new screens, 0 matched an existing one.`);
+        deps.out("  If your test filenames changed, these are new baselines and nothing");
+        deps.out("  was compared. The filename is the screen's identity — keep it stable,");
+        deps.out("  or pin the names with --map.");
+    }
+    const failed = failures(outcomes);
+    if (failed > 0)
+        deps.out(`${failed} could not be uploaded.`);
+    // Tell the pull request, if this run is one. Best-effort in every direction:
+    // a tool that broke a pipeline because it could not leave a comment would be
+    // worse than one that stayed quiet.
+    if (opts.github) {
+        const target = (0, github_1.githubTarget)(deps.env ?? process.env, from.pullRequest);
+        if (target) {
+            const posted = await (0, github_1.postToPullRequest)(target, {
+                total: summary.total,
+                changed: summary.changed,
+                newBaselines: summary.newBaselines,
+                unreviewed: summary.unreviewed,
+                failed,
+                reviewUrl: `${opts.appUrl}/visual/builds?buildId=${build.buildId}`,
+            }, { fetchImpl: deps.fetchImpl, warn: deps.out });
+            if (posted.status || posted.comment)
+                deps.out("Posted the result to GitHub.");
+        }
+    }
+    const needsReview = summary.unreviewed > 0 || failed > 0;
+    return {
+        buildId: build.buildId,
+        outcomes,
+        summary,
+        exitCode: opts.exitZeroOnChanges ? (failed > 0 ? 1 : 0) : needsReview ? 1 : 0,
+    };
+}
+/**
+ * A comparison that did not happen, in words.
+ *
+ * The picture is safely stored in every one of these cases, which is the part
+ * worth saying — the run can simply be repeated.
+ */
+function explain(reason) {
+    switch (reason) {
+        case "size_mismatch":
+            return "different width to its baseline — approve it as a new baseline in Review";
+        case "compare_unavailable":
+        case "no_node_available":
+            return "we couldn't compare it just now; the picture is saved, try the run again";
+        default:
+            return reason ? `couldn't compare it (${reason})` : "couldn't compare it";
+    }
+}
+function failures(outcomes) {
+    return outcomes.filter((o) => o.status === "error" || o.status === "failed").length;
+}
+function findDuplicates(named) {
+    const seen = new Map();
+    const clashes = [];
+    for (const item of named) {
+        const first = seen.get(item.screenName);
+        if (first)
+            clashes.push(`"${item.screenName}" (${first} and ${item.file})`);
+        else
+            seen.set(item.screenName, item.file);
+    }
+    return clashes;
+}
+const LABEL = {
+    baseline: "new",
+    identical: "same",
+    changed: "CHANGED",
+    failed: "failed",
+    error: "error",
+};
+function report(outcomes, out) {
+    const width = Math.min(48, Math.max(...outcomes.map((o) => o.screenName.length), 6));
+    for (const o of outcomes) {
+        const name = o.screenName.padEnd(width);
+        const detail = o.status === "changed" && typeof o.diffRatio === "number"
+            ? `  ${(o.diffRatio * 100).toFixed(2)}% different`
+            : o.error
+                ? `  ${o.error}`
+                : "";
+        out(`  ${name}  ${LABEL[o.status]}${detail}`);
+    }
+}
+function joinPath(folder, file) {
+    const base = folder.replace(/[\\/]+$/, "");
+    return `${base}/${file}`;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@testkase/visual",
+  "version": "0.1.0",
+  "description": "Upload your test suite's screenshots to TestKase Visual and get told what changed.",
+  "license": "MIT",
+  "type": "commonjs",
+  "bin": {
+    "testkase-visual": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SolvionIT/testkase-visual.git"
+  },
+  "homepage": "https://testkase.com/docs/visual/ci-uploads",
+  "keywords": [
+    "testkase",
+    "visual-regression",
+    "visual-testing",
+    "screenshot-testing",
+    "playwright",
+    "cypress",
+    "puppeteer",
+    "selenium",
+    "ci-cd"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}