scenescout 3.15.0 → 3.16.0

package/dist/engine/unload.js

@@ -60,7 +60,8 @@ export function unseenWriteSource(input) {
  * interception can know about it. Same rules in the same order: a write
  * another site's frame sends outside the app is refused; so is one sent from
  * a page an embed moved off the app, a sign-in excepted; a sign-in passes;
- * then the mode decides. `foreign` and `offApp` come from
+ * then a POST the user named as a read (observe only), then the mode
+ * decides. `foreign` and `offApp` come from
  * `unseenWriteSource`, since the sending frame may no longer exist.
  * The one step it does not take is safe-write's short wait for a creation
  * still in flight: a page being left has nothing more to wait for.
@@ -74,7 +75,7 @@ export function judgeUnseenWrite(input) {
     const authExempt = isAuthExempt(mode, method, pathname, destructiveWire);
     if (input.offApp && !authExempt)
         return { allow: false, why: `sent from a page of ${input.offApp}, outside the app` };
-    if (authExempt)
+    if (authExempt || input.readPost)
         return { allow: true };
     return allowsWrite(mode, method, destructiveWire, input.owned) ? { allow: true } : { allow: false };
 }

package/dist/export-run.js

@@ -0,0 +1,633 @@
+/**
+ * Runs `scenescout export`: reads the project's findings, asks the tracker
+ * which of them it already holds, and files the rest. The rules (which
+ * findings, what an issue says, the marker, the plan) live in
+ * engine/export.ts; this file only reads the project's files and talks HTTP.
+ * It writes nothing to the project, and the credentials it sends are never
+ * printed: every line goes out through a redactor that knows them.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { redactKeys } from "./engine/ci.js";
+import { credentialSecrets, EXIT_EXPORT, failedCriteriaByFinding, findingIdsInGithubBody, findingIdsInJiraDescription, findingLine, findingPicture, frameIsOriginal, framesFor, githubIssue, jiraEditFields, jiraIssueFields, MARKER_LABEL, MAX_RATE_WAIT_MS, oneLine, planExport, planJiraUpdate, rateLimit, rememberFiled, selectFindings, ticketsToLink, trackerCredentials, trackerMessage, TRACKER_LABEL, uploadName, } from "./engine/export.js";
+import { MEMORY_DIRNAME } from "./engine/memory.js";
+import { backoffMs } from "./engine/provider.js";
+import { resolveFrame } from "./engine/replay.js";
+/**
+ * A failure that ends the export. `uncertain`: the tracker may have acted on
+ * the request before it failed (a create that timed out or got a 5xx), so
+ * whether the issue exists has to be asked again rather than assumed.
+ */
+export class ExportError extends Error {
+    uncertain;
+    constructor(message, uncertain = false) {
+        super(message);
+        this.uncertain = uncertain;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 20_000;
+const DEFAULT_RETRIES = 3;
+/** Pages of 100 issues read to find what is already filed. More than this and an export refuses rather than file blind. */
+const MAX_PAGES = 50;
+/** A frame larger than this is not uploaded: a recorded frame is a JPEG of a page, far smaller. */
+const MAX_FRAME_BYTES = 10_000_000;
+async function readBody(res) {
+    const text = await res.text();
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Not JSON: an HTML error page from a proxy, say. The text is still what the message quotes.
+        return { message: text.slice(0, 300) };
+    }
+}
+const REFUSAL_HINT = {
+    400: " (a field was refused: in Jira, check --jira-issue-type and the --severity-map priorities)",
+    401: " (the credentials were not accepted)",
+    403: " (the credentials lack a permission this needs)",
+    404: " (no such repository or project, or the credentials cannot see it)",
+    410: " (issues are turned off for this repository)",
+};
+/** Why a request got no usable answer, as one line: Node's fetch says only "fetch failed" and keeps the reason in `cause`. */
+function failureOf(err, timeoutMs) {
+    if (err instanceof Error && err.name === "TimeoutError")
+        return `no answer within ${timeoutMs / 1000} s`;
+    if (!(err instanceof Error))
+        return oneLine(err, 200);
+    const cause = err.cause instanceof Error ? err.cause : null;
+    const code = cause && typeof cause.code === "string" ? `${cause.code} ` : "";
+    return oneLine(cause ? `${err.message}: ${code}${cause.message}` : err.message, 300);
+}
+/**
+ * One tracker's requests: its base address, its credentials, a timeout on
+ * every request (reading the answer included), no redirect followed (the
+ * credentials would go with it), a rate limit waited out when it asks for a
+ * minute or less, and a 5xx, a dropped connection or an answer cut off
+ * retried with backoff when the request is safe to send twice. When it is
+ * not, the failure is marked uncertain: the tracker may have acted on it.
+ */
+function client(base, headers, h) {
+    return async (r) => {
+        const what = `${r.method} ${r.path.split("?")[0]}`;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            let body;
+            try {
+                res = await h.fetchImpl(`${base}${r.path}`, {
+                    method: r.method,
+                    headers: { accept: "application/json", ...headers, ...(r.json !== undefined ? { "content-type": "application/json" } : {}), ...r.headers },
+                    body: r.json !== undefined ? JSON.stringify(r.json) : r.form,
+                    redirect: "manual",
+                    signal: AbortSignal.timeout(h.timeoutMs),
+                });
+                body = await readBody(res);
+            }
+            catch (err) {
+                if (r.idempotent && attempt < h.retries) {
+                    await h.wait(backoffMs(attempt + 1, h.random));
+                    continue;
+                }
+                throw new ExportError(`${what} failed: ${failureOf(err, h.timeoutMs)}`, !r.idempotent);
+            }
+            if (res.status >= 300 && res.status < 400)
+                throw new ExportError(`${what} was answered with a redirect (HTTP ${res.status}), which is refused: credentials are never sent on to another address. A repository or site that moved needs its new address`);
+            const said = trackerMessage(body);
+            const limit = rateLimit(res.status, (name) => res.headers.get(name), h.now(), said);
+            if (limit.limited) {
+                const waitMs = limit.waitMs ?? backoffMs(attempt + 1, h.random);
+                if (waitMs > MAX_RATE_WAIT_MS)
+                    throw new ExportError(`${what} hit the tracker's rate limit, which asks to wait ${Math.ceil(waitMs / 1000)} s; export again after that`);
+                if (attempt >= h.retries)
+                    throw new ExportError(`${what} hit the tracker's rate limit ${attempt + 1} times; export again later`);
+                await h.wait(waitMs);
+                continue;
+            }
+            if (res.status >= 500) {
+                if (r.idempotent && attempt < h.retries) {
+                    await h.wait(backoffMs(attempt + 1, h.random));
+                    continue;
+                }
+                throw new ExportError(`${what} failed: HTTP ${res.status}${said ? `: ${said}` : ""}`, !r.idempotent);
+            }
+            if (!res.ok)
+                throw new ExportError(`${what} was refused: HTTP ${res.status}${REFUSAL_HINT[res.status] ?? ""}${said ? `: ${said}` : ""}`);
+            return body;
+        }
+    };
+}
+const isRecord = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+function githubApi({ repo }, send) {
+    const root = `/repos/${repo
+        .split("/")
+        .map((p) => encodeURIComponent(p))
+        .join("/")}/issues`;
+    return {
+        label: `GitHub ${repo}`,
+        consistentListing: true,
+        // Listed by label rather than found through the search API: search is
+        // indexed with a delay, so an export run right after another would not
+        // see the issues it had just filed and would file them again.
+        async existing(includeClosed) {
+            const map = new Map();
+            let issues = 0;
+            let unmarked = 0;
+            for (let page = 1; page <= MAX_PAGES; page++) {
+                const body = await send({
+                    method: "GET",
+                    path: `${root}?labels=${encodeURIComponent(MARKER_LABEL)}&state=${includeClosed ? "all" : "open"}&per_page=100&page=${page}`,
+                    idempotent: true,
+                });
+                if (!Array.isArray(body))
+                    throw new ExportError("GitHub's list of issues was not a list");
+                for (const issue of body) {
+                    // The issues API lists pull requests too.
+                    if (isRecord(issue) && issue.pull_request)
+                        continue;
+                    const number = isRecord(issue) ? Number(issue.number) : NaN;
+                    // An entry that cannot be read, or one without its body, could be a filed finding: guessing "not filed" files it twice.
+                    if (!isRecord(issue) || !Number.isInteger(number) || !("body" in issue))
+                        throw new ExportError("GitHub listed an issue without its number or its body, so which findings are filed cannot be told");
+                    issues++;
+                    const ids = findingIdsInGithubBody(issue.body);
+                    if (ids.length === 0)
+                        unmarked++;
+                    for (const id of ids)
+                        rememberFiled(map, id, { ref: `#${number}`, number, url: oneLine(issue.html_url, 300), open: issue.state !== "closed" });
+                }
+                if (body.length < 100)
+                    return { map, issues, unmarked };
+            }
+            throw new ExportError(`${MAX_PAGES * 100} or more issues carry the ${MARKER_LABEL} label, too many to check them all for this export's findings`);
+        },
+        async create(f, ctx) {
+            const body = await send({ method: "POST", path: root, json: githubIssue(f, ctx), idempotent: false });
+            const number = isRecord(body) ? Number(body.number) : NaN;
+            if (!isRecord(body) || !Number.isInteger(number))
+                throw new ExportError("GitHub answered the create without an issue number", true);
+            const issue = { ref: `#${number}`, number, url: oneLine(body.html_url, 300), open: true };
+            const labels = Array.isArray(body.labels) ? body.labels : [];
+            const names = labels.map((l) => (typeof l === "string" ? l : isRecord(l) ? String(l.name ?? "") : "").toLowerCase());
+            // GitHub drops the labels of an issue created by an account that cannot set them, and says nothing.
+            if (!names.includes(MARKER_LABEL))
+                return {
+                    issue,
+                    problems: [],
+                    stop: `GitHub filed ${issue.ref} without its ${MARKER_LABEL} label, so a later export could not find it. Stopping before filing more: GitHub drops the labels of an issue created by an account that may not set them, so give the token's account write access to the repository (and create the ${MARKER_LABEL} label if it has none), then add the label to ${issue.ref} by hand`,
+                };
+            return { issue, problems: [] };
+        },
+    };
+}
+function jiraApi({ baseUrl, projectKey, issueType, linkType }, send) {
+    const keyNumber = (key) => {
+        const m = /^[A-Z][A-Z0-9_]*-(\d+)$/.exec(key);
+        return m ? Number(m[1]) : null;
+    };
+    const issuePath = (key) => `/rest/api/3/issue/${encodeURIComponent(key)}`;
+    /** Attach each file; what could not be attached is returned, not thrown, since the issue itself stands. */
+    const attach = async (key, files, again) => {
+        const done = [];
+        const problems = [];
+        for (const frame of files) {
+            const name = frame.upload;
+            try {
+                const form = new FormData();
+                form.append("file", new Blob([fs.readFileSync(frame.file)], { type: name.endsWith(".png") ? "image/png" : "image/jpeg" }), name);
+                await send({
+                    method: "POST",
+                    path: `${issuePath(key)}/attachments`,
+                    form,
+                    // Jira refuses an upload without it, as protection against cross-site requests.
+                    headers: { "x-atlassian-token": "no-check" },
+                    idempotent: true,
+                });
+                done.push(name);
+            }
+            catch (err) {
+                problems.push(`${name} was not attached (${err instanceof Error ? err.message : String(err)}). It is at ${frame.file}; ${again}`);
+            }
+        }
+        return { done, problems };
+    };
+    /**
+     * Link the issue to each ticket whose criterion it fails, so the issue reads
+     * as the subject of the link type's outward words ("blocks", "relates to")
+     * and the ticket as their object. Jira's API gives those words to the issue
+     * sent as `inwardIssue`, the reverse of what the field names suggest. Jira
+     * answers a link that already exists as made, so sending one twice is harmless.
+     */
+    const link = async (key, tickets) => {
+        const done = [];
+        const problems = [];
+        if (!linkType)
+            return { done, problems };
+        for (const ticket of tickets) {
+            try {
+                await send({
+                    method: "POST",
+                    path: "/rest/api/3/issueLink",
+                    json: { type: { name: linkType }, inwardIssue: { key }, outwardIssue: { key: ticket } },
+                    idempotent: true,
+                });
+                done.push(ticket);
+            }
+            catch (err) {
+                problems.push(`not linked to ${ticket} (${err instanceof Error ? err.message : String(err)}); check that ${ticket} is an issue on this site and that "${linkType}" is a link type it has (--jira-link-type), and a later export links it`);
+            }
+        }
+        return { done, problems };
+    };
+    const keysOf = (links) => (Array.isArray(links) ? links : []).flatMap((l) => isRecord(l) ? [l.inwardIssue, l.outwardIssue].flatMap((i) => (isRecord(i) && typeof i.key === "string" ? [i.key] : [])) : []);
+    const namesOf = (attachments) => (Array.isArray(attachments) ? attachments : []).flatMap((a) => (isRecord(a) && typeof a.filename === "string" ? [a.filename] : []));
+    return {
+        label: `Jira ${projectKey}`,
+        consistentListing: false,
+        async existing(includeClosed) {
+            // The key was checked to be capitals, digits and underscores; the label is ours. Nothing else goes into the query.
+            const jql = `project = "${projectKey}" AND labels = "${MARKER_LABEL}"${includeClosed ? "" : " AND statusCategory != Done"} ORDER BY created ASC`;
+            const map = new Map();
+            let issues = 0;
+            let unmarked = 0;
+            let nextPageToken;
+            for (let page = 1; page <= MAX_PAGES; page++) {
+                const body = await send({
+                    method: "POST",
+                    path: "/rest/api/3/search/jql",
+                    json: { jql, fields: ["summary", "description", "status", "attachment", "issuelinks"], maxResults: 100, ...(nextPageToken ? { nextPageToken } : {}) },
+                    idempotent: true,
+                });
+                if (!isRecord(body) || !Array.isArray(body.issues))
+                    throw new ExportError("Jira's search answered without a list of issues");
+                for (const issue of body.issues) {
+                    const key = isRecord(issue) ? String(issue.key ?? "") : "";
+                    const number = keyNumber(key);
+                    const fields = isRecord(issue) && isRecord(issue.fields) ? issue.fields : null;
+                    // A field configuration can hide the description; without it, every finding would read as unfiled and be filed again.
+                    if (number === null || !fields || !("description" in fields))
+                        throw new ExportError(`Jira listed an issue without its key or its description, so which findings are filed cannot be told`);
+                    issues++;
+                    const status = isRecord(fields.status) && isRecord(fields.status.statusCategory) ? fields.status.statusCategory.key : undefined;
+                    const ids = findingIdsInJiraDescription(fields.description);
+                    if (ids.length === 0)
+                        unmarked++;
+                    const jira = { summary: fields.summary, description: fields.description, attachments: namesOf(fields.attachment), links: keysOf(fields.issuelinks) };
+                    for (const id of ids)
+                        rememberFiled(map, id, { ref: key, number, url: `${baseUrl}/browse/${key}`, open: status !== "done", jira });
+                }
+                nextPageToken = typeof body.nextPageToken === "string" && body.nextPageToken ? body.nextPageToken : undefined;
+                if (!nextPageToken || body.isLast === true)
+                    return { map, issues, unmarked };
+            }
+            throw new ExportError(`more than ${MAX_PAGES} pages of issues in ${projectKey} carry the ${MARKER_LABEL} label, too many to check them all for this export's findings`);
+        },
+        async create(f, ctx, extras) {
+            const body = await send({
+                method: "POST",
+                path: "/rest/api/3/issue",
+                json: { fields: jiraIssueFields(f, { ...ctx, projectKey, issueType }) },
+                idempotent: false,
+            });
+            const key = isRecord(body) ? String(body.key ?? "") : "";
+            const number = keyNumber(key);
+            if (number === null)
+                throw new ExportError("Jira answered the create without an issue key", true);
+            const issue = { ref: key, number, url: `${baseUrl}/browse/${key}`, open: true };
+            const attached = await attach(key, extras.files, "a later export attaches it while the issue is open, unless --jira-update is off");
+            const linked = await link(key, extras.tickets);
+            return { issue, problems: [...attached.problems, ...linked.problems] };
+        },
+        async update(f, ctx, issue, plan, extras) {
+            const rewrote = plan.fields === "change";
+            if (rewrote)
+                // Summary and description only: an edit, so Jira notifies the issue's watchers as it does for any other.
+                await send({ method: "PUT", path: issuePath(issue.ref), json: { fields: jiraEditFields(f, ctx) }, idempotent: true });
+            const wanted = new Set(plan.attach);
+            const attached = await attach(issue.ref, extras.files.filter((x) => wanted.has(x.upload)), "a later export tries again");
+            const linked = await link(issue.ref, plan.link);
+            return { rewrote, attached: attached.done, linked: linked.done, problems: [...attached.problems, ...linked.problems] };
+        },
+    };
+}
+// ── the project's files ─────────────────────────────────────────────────────
+/** The project's memory, refused unless it is one this version reads: a file it cannot read exported nothing and said so with exit 0. */
+function readMemory(memoryPath) {
+    if (!fs.existsSync(memoryPath))
+        throw new ExportError(`no findings to export: ${memoryPath} does not exist. Run SceneScout on this project first, or pass --project`);
+    let memory;
+    try {
+        memory = JSON.parse(fs.readFileSync(memoryPath, "utf8"));
+    }
+    catch (err) {
+        throw new ExportError(`could not read ${memoryPath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!isRecord(memory) || memory.version !== 1)
+        throw new ExportError(`${memoryPath} is not a memory file this version reads (version ${isRecord(memory) ? oneLine(memory.version, 20) : "unknown"})`);
+    if (!Array.isArray(memory.findings))
+        throw new ExportError(`${memoryPath} holds no list of findings`);
+    return memory;
+}
+/** Every step with a frame, from every session log in the memory directory. Logs and lines that cannot be read are counted, not fatal. */
+function framedSteps(memoryDir) {
+    const steps = [];
+    let unreadable = 0;
+    if (!fs.existsSync(path.join(memoryDir, "recordings")))
+        return { steps, unreadable };
+    for (const name of fs.readdirSync(memoryDir)) {
+        if (!/^session-.*\.jsonl$/.test(name))
+            continue;
+        let text;
+        try {
+            text = fs.readFileSync(path.join(memoryDir, name), "utf8");
+        }
+        catch {
+            // A log that cannot be read costs only its screenshots; it is counted with the lines that do not parse.
+            unreadable++;
+            continue;
+        }
+        for (const line of text.split("\n")) {
+            if (!line.includes('"frame"'))
+                continue;
+            try {
+                const e = JSON.parse(line);
+                if (typeof e.at === "string" && typeof e.frame === "string")
+                    steps.push({ at: e.at, session: e.session, frame: e.frame });
+            }
+            catch {
+                unreadable++;
+            }
+        }
+    }
+    return { steps, unreadable };
+}
+/** A frame's file, when it really is inside the recordings folder: links are followed first, so a link to elsewhere, or a linked folder, is not. */
+function frameFile(root, rel) {
+    const named = resolveFrame(root, rel);
+    if (!named)
+        return null;
+    try {
+        const realRoot = fs.realpathSync(root);
+        const file = fs.realpathSync(named);
+        if (!file.startsWith(realRoot + path.sep))
+            return null;
+        const stat = fs.statSync(file);
+        return stat.isFile() ? { file, stat } : null;
+    }
+    catch {
+        // Missing, or unreadable: this frame is left out and counted, like any other that cannot be attached.
+        return null;
+    }
+}
+/** The frames an issue names or attaches: inside the recordings folder, small enough, and still the picture of that step. */
+function framesOf(f, steps, memoryDir) {
+    const frames = [];
+    let dropped = 0;
+    for (const { frame, at } of framesFor(f, steps)) {
+        const found = frameFile(path.join(memoryDir, "recordings"), frame);
+        if (!found || found.stat.size > MAX_FRAME_BYTES || !frameIsOriginal(at, found.stat.mtimeMs)) {
+            dropped++;
+            continue;
+        }
+        frames.push({ rel: frame, file: found.file, at, upload: uploadName(frame, at) });
+    }
+    return { frames, dropped };
+}
+/** The finding's own picture, when its path is one the engine writes and the file is inside the recordings folder and small enough. */
+function pictureOf(f, memoryDir) {
+    const picture = findingPicture(f);
+    if (!picture)
+        return null;
+    const found = frameFile(path.join(memoryDir, "recordings"), picture.rel);
+    return found && found.stat.size <= MAX_FRAME_BYTES ? { ...picture, file: found.file, upload: uploadName(picture.rel, picture.at) } : null;
+}
+// ── the export ──────────────────────────────────────────────────────────────
+const OUTCOME_WORDS = { file: "would file", "already-filed": "already filed", "over-cap": "over the cap" };
+export async function runExport(o, deps) {
+    const credentials = trackerCredentials(o.to, deps.env);
+    // Every credential that is set, not only the tracker's: one echoed back from anywhere is never printed.
+    const secrets = credentialSecrets(deps.env);
+    const say = (line) => deps.log(redactKeys(line, secrets));
+    const complain = (line) => (deps.error ?? deps.log)(redactKeys(line, secrets));
+    const http = {
+        fetchImpl: deps.fetchImpl ?? fetch,
+        wait: deps.wait ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
+        timeoutMs: deps.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        retries: deps.retries ?? DEFAULT_RETRIES,
+        now: deps.now ?? Date.now,
+        random: deps.random ?? Math.random,
+    };
+    const pauseMs = deps.pauseMs ?? (o.to === "github" ? 1000 : 250);
+    const where = o.to === "github" ? `GitHub ${o.github.repo}` : `Jira ${o.jira.projectKey} at ${o.jira.baseUrl}`;
+    const filed = [];
+    const updated = [];
+    let plan = [];
+    // Kept outside the try, so an export that stops part-way still says what went wrong before it stopped.
+    const problems = [];
+    let droppedFrames = 0;
+    const reportFrames = () => {
+        if (droppedFrames > 0)
+            say(`Left out ${droppedFrames} frame(s) that are missing, too large, or were rewritten by a later run.`);
+    };
+    try {
+        const memoryDir = path.join(o.projectDir, MEMORY_DIRNAME);
+        const memoryPath = path.join(memoryDir, "memory.json");
+        const memory = readMemory(memoryPath);
+        const selection = selectFindings(memory, o);
+        const criteria = failedCriteriaByFinding(memory);
+        if (selection.unknownOnly.length > 0)
+            throw new ExportError(`--only names no finding of this project: ${selection.unknownOnly.join(", ")}`);
+        say(o.dryRun ? `SceneScout export to ${where}: a dry run, so nothing is filed. Pass --yes to file.` : `SceneScout export to ${where}.`);
+        const c = selection.counts;
+        const left = [
+            c.belowSeverity ? `${c.belowSeverity} below --min-severity ${o.minSeverity}` : "",
+            c.worthALook ? `${c.worthALook} worth a look (--include-worth-a-look exports them)` : "",
+        ].filter(Boolean);
+        say(`Findings in ${memoryPath}: ${c.open} open, ${c.resolved} resolved${selection.unreadable.length ? `, ${selection.unreadable.length} unreadable` : ""}. ` +
+            `${selection.candidates.length} to export${left.length ? `; left out: ${left.join(", ")}` : ""}.`);
+        if (selection.unreadable.length > 0)
+            say(`  Not exported, as this version cannot read them: ${selection.unreadable.slice(0, 20).join(", ")}${selection.unreadable.length > 20 ? " …" : ""}`);
+        for (const { id, reason } of selection.leftOut)
+            say(`  not exported  ${id}: ${reason}`);
+        if (selection.candidates.length === 0) {
+            say("Nothing to export.");
+            return { exitCode: EXIT_EXPORT.done, plan, filed, updated };
+        }
+        if (!credentials.ok && !o.dryRun)
+            throw new ExportError(credentials.error);
+        const tracker = !credentials.ok
+            ? null
+            : o.to === "github"
+                ? githubApi(o.github, client(o.github.apiUrl, { ...credentials.headers, ...GITHUB_HEADERS }, http))
+                : jiraApi(o.jira, client(o.jira.baseUrl, credentials.headers, http));
+        // A closed issue counts as filed unless --refile-closed.
+        const includeClosed = !o.refileClosed;
+        let existing = null;
+        if (tracker) {
+            const found = await tracker.existing(includeClosed);
+            existing = found.map;
+            say(`Compared with ${tracker.label}: ${found.issues} ${includeClosed ? "" : "open "}issue(s) carry the ${MARKER_LABEL} label` +
+                `${includeClosed ? " (open or closed)" : ""}${found.unmarked ? `, ${found.unmarked} of them with no marker` : ""}` +
+                `${includeClosed ? "" : "; a finding whose issue was closed is filed again (--refile-closed)"}.`);
+        }
+        else if (!credentials.ok) {
+            say(`Not compared with ${TRACKER_LABEL[o.to]}: ${credentials.error}. A finding filed earlier is listed below as one to file.`);
+        }
+        plan = planExport(selection.candidates, existing, o.maxIssues);
+        const steps = o.screenshots ? framedSteps(memoryDir) : { steps: [], unreadable: 0 };
+        if (steps.unreadable > 0)
+            say(`Skipped ${steps.unreadable} session-log line(s) or file(s) that could not be read while looking for screenshots.`);
+        const contextOf = (f) => {
+            const found = o.screenshots ? framesOf(f, steps.steps, memoryDir) : { frames: [], dropped: 0 };
+            droppedFrames += found.dropped;
+            const picture = o.screenshots ? pictureOf(f, memoryDir) : null;
+            const failed = criteria.get(f.id) ?? [];
+            return {
+                ctx: {
+                    severityName: o.severityMap[f.severity],
+                    labels: o.labels,
+                    screenshots: o.screenshots ? found.frames.map((x) => x.rel) : "off",
+                    framesLeftOut: found.dropped,
+                    picture: picture?.rel ?? null,
+                    ...(picture?.at ? { pictureAt: picture.at } : {}),
+                    screenshotTimes: found.frames.map((x) => x.at ?? ""),
+                    criteria: failed,
+                },
+                // GitHub takes no uploads and has no links between trackers: its body names both instead.
+                extras: o.to === "jira"
+                    ? { files: [...(picture ? [picture] : []), ...found.frames], tickets: o.jira.linkType ? ticketsToLink(failed) : [] }
+                    : { files: [], tickets: [] },
+            };
+        };
+        let writes = 0;
+        for (const entry of plan) {
+            const f = entry.finding;
+            if (entry.outcome === "already-filed") {
+                const issue = entry.issue;
+                const already = `  ${OUTCOME_WORDS[entry.outcome].padEnd(13)}  ${findingLine(f)}  as ${issue.ref}${issue.open ? "" : " (closed)"}`;
+                // Only an open Jira issue filed earlier is brought up to date; a closed one is the team's decision and left alone.
+                if (o.to !== "jira" || !o.jira.update || !issue.open || !issue.jira || !tracker?.update) {
+                    say(already);
+                    continue;
+                }
+                const { ctx, extras } = contextOf(f);
+                const wanted = jiraEditFields(f, ctx);
+                const upd = planJiraUpdate(f, issue.jira, {
+                    ...wanted,
+                    files: extras.files.map((x) => x.upload),
+                    tickets: extras.tickets,
+                });
+                const changesOf = (rewrite, attach, link, tense) => [
+                    rewrite ? (tense === "would" ? "rewrite its summary and description" : "rewrote its summary and description") : "",
+                    attach.length ? `${tense === "would" ? "attach" : "attached"} ${attach.join(", ")}` : "",
+                    link.length ? `${tense === "would" ? "link it to" : "linked it to"} ${link.join(", ")}` : "",
+                ].filter(Boolean);
+                const changes = changesOf(upd.fields === "change", upd.attach, upd.link, "would");
+                const kept = upd.fields === "edited"
+                    ? "; its summary or description was edited in Jira, so it is left as written"
+                    : upd.fields === "no-revision"
+                        ? "; it was filed by an earlier version, so its summary and description are left as they are"
+                        : "";
+                if (changes.length === 0 || o.dryRun) {
+                    const would = changes.length ? `; would ${changes.join(", ")}` : upd.fields === "same" ? ", up to date" : "";
+                    say(`${already}${would}${kept}`);
+                    continue;
+                }
+                if (writes > 0 && pauseMs > 0)
+                    await http.wait(pauseMs);
+                writes++;
+                const did = await tracker.update(f, ctx, issue, upd, extras);
+                const done = changesOf(did.rewrote, did.attached, did.linked, "did");
+                // Said only of what Jira took: an update whose every attachment and link failed changed nothing.
+                if (done.length > 0) {
+                    updated.push({ id: f.id, issue });
+                    say(`  ${`updated ${issue.ref}`.padEnd(13)}  ${findingLine(f)}  ${issue.url}: ${done.join(", ")}${kept}`);
+                }
+                else
+                    say(`${already}; nothing could be updated${kept}`);
+                for (const p of did.problems)
+                    problems.push(`${issue.ref}: ${p}`);
+                continue;
+            }
+            // Listed, not filed: over the cap, or a dry run (the only way to be here with no tracker, as --yes needs credentials).
+            if (entry.outcome === "over-cap" || o.dryRun || !tracker) {
+                const shown = entry.outcome === "file" && o.screenshots ? contextOf(f).ctx : null;
+                const shots = shown && shown.screenshots !== "off" ? shown.screenshots.length + (shown.picture ? 1 : 0) : 0;
+                say(`  ${OUTCOME_WORDS[entry.outcome].padEnd(13)}  ${findingLine(f)}${shots ? `  with ${shots} screenshot(s)` : ""}`);
+                continue;
+            }
+            if (writes > 0 && pauseMs > 0)
+                await http.wait(pauseMs);
+            const { ctx, extras } = contextOf(f);
+            const done = await fileOne(tracker, f, ctx, extras, includeClosed, http);
+            writes++;
+            filed.push({ id: f.id, issue: done.issue });
+            say(`  ${`filed ${done.issue.ref}`.padEnd(13)}  ${findingLine(f)}  ${done.issue.url}${done.confirmed ? " (found by its marker after the tracker's error)" : ""}`);
+            for (const p of done.problems)
+                problems.push(`${done.issue.ref}: ${p}`);
+            if (done.stop)
+                throw new ExportError(done.stop);
+        }
+        reportFrames();
+        const count = (outcome) => plan.filter((e) => e.outcome === outcome).length;
+        const over = count("over-cap");
+        const overText = over ? `; ${over} over the cap of ${o.maxIssues} (--max-issues): export again to file them` : "";
+        say(o.dryRun
+            ? `Would file ${count("file")}; ${count("already-filed")} already filed${overText}.`
+            : `Filed ${filed.length}; ${count("already-filed")} already filed${updated.length ? `, ${updated.length} of them updated` : ""}${overText}.`);
+        if (problems.length > 0) {
+            for (const p of problems)
+                complain(`scenescout export: ${p}`);
+            return { exitCode: EXIT_EXPORT.couldNotExport, plan, filed, updated };
+        }
+        return { exitCode: EXIT_EXPORT.done, plan, filed, updated };
+    }
+    catch (err) {
+        reportFrames();
+        complain(`scenescout export: ${err instanceof Error ? err.message : String(err)}`);
+        if (err instanceof ExportError && err.uncertain)
+            complain(o.to === "jira"
+                ? "Jira may have made that issue before the error, and its search can take minutes to show a new one, so it was not sent again. Export again later: the issue is found by its marker if it exists, and filed if it does not."
+                : "The tracker may have made that issue before the error. The next export finds it by its marker and does not file it again.");
+        for (const p of problems)
+            complain(`scenescout export: ${p}`);
+        if (filed.length > 0)
+            complain(`Filed before it stopped: ${filed.map((x) => x.issue.ref).join(", ")}.`);
+        if (updated.length > 0)
+            complain(`Updated before it stopped: ${updated.map((x) => x.issue.ref).join(", ")}.`);
+        return { exitCode: EXIT_EXPORT.couldNotExport, plan, filed, updated };
+    }
+}
+const GITHUB_HEADERS = { accept: "application/vnd.github+json", "x-github-api-version": "2022-11-28" };
+/**
+ * Create one issue. A create that failed in a way the tracker may have acted
+ * on (a timeout, a 5xx, an answer cut off) is not simply sent again: the
+ * issues are listed again first, and if one already carries this finding's
+ * marker, that is the issue. Only when none does is the create repeated, and
+ * only where the listing shows a new issue at once (GitHub); in Jira, whose
+ * search lags, the export stops instead.
+ */
+async function fileOne(tracker, f, ctx, extras, includeClosed, http) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await tracker.create(f, ctx, extras);
+        }
+        catch (err) {
+            if (!(err instanceof ExportError) || !err.uncertain)
+                throw err;
+            const which = `the issue for finding ${f.id} (${oneLine(f.title, 80)})`;
+            if (!tracker.consistentListing || attempt >= http.retries)
+                throw new ExportError(`${err.message}, creating ${which}`, true);
+            await http.wait(backoffMs(attempt + 1, http.random));
+            let issue;
+            try {
+                issue = (await tracker.existing(includeClosed)).map.get(f.id);
+            }
+            catch (listing) {
+                throw new ExportError(`${err.message}, creating ${which}; listing the issues again to look for it failed too: ${listing instanceof Error ? listing.message : String(listing)}`, true);
+            }
+            if (issue)
+                return { issue, problems: [], confirmed: true };
+        }
+    }
+}