@jevitate/cli 0.1.0 → 0.3.0

package/dist/fixture-cli.js

@@ -0,0 +1,292 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { positiveIntArg } from "./cli-args.js";
+import { FixtureSetupError, FixtureSpecError, MissionFixtures, SETUP_REF, UnboundSetupRefError, hookHash, identityNames, loadFixtureFile, parseFixtureSpec, referencedNames, substituteSetupRefs, } from "./mission-fixtures.js";
+/** Adds `--fixtures`, `--before`, `--after`, `--allow-shell-hooks` and `--hook-timeout-ms`. */
+export function withFixtureFlags(cmd) {
+    return cmd
+        .option("--fixtures <file>", "mission fixtures JSON {setup:[...], restore:[...]} (#140/#144): HTTP steps to an --allow origin, authenticated from " +
+        "--storage-state/--secret-field, run before the mission and restored after it — and around every replay. Outputs bind as ${setup.<name>}")
+        .option("--before <cmd>", "operator shell hook run before the mission and every replay (needs --allow-shell-hooks); may print {vars, secret}")
+        .option("--after <cmd>", "operator shell hook run after the mission and every replay (needs --allow-shell-hooks)")
+        .option("--allow-shell-hooks", "opt in to running --before/--after (operator commands; never model-chosen)", false)
+        .option("--hook-timeout-ms <ms>", "timeout for each --before/--after hook (default 60000; the process group is killed)", positiveIntArg)
+        .option("--fixture-identity <name=storageState>", "#243: a named identity fixture steps can authenticate as (`auth.identity`), separate from the mission's own session — e.g. mint an invite as the owner, run the mission cold (repeatable)", (v, prev) => [...prev, v], []);
+}
+const IDENTITY_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+/**
+ * #243: every fixture identity the run can authenticate a step as → its storageState PATH. Lowest to
+ * highest precedence: the origin's targets.json personas, the identities a persisted result recorded,
+ * then `--fixture-identity`. Only paths are kept (the file is read per request, never logged); a
+ * missing file is refused here, before any browser or request.
+ */
+export function resolveFixtureIdentities(flags, ctx, cwd = process.cwd()) {
+    const out = {};
+    for (const [name, p] of Object.entries(ctx.personas ?? {}))
+        if (p.storageState !== undefined)
+            out[name] = p.storageState;
+    for (const [name, path] of Object.entries(ctx.identities ?? {}))
+        out[name] = path;
+    const seen = new Set();
+    for (const spec of flags.fixtureIdentity ?? []) {
+        const eq = spec.indexOf("=");
+        if (eq <= 0)
+            throw new FixtureSpecError(`--fixture-identity must be <name>=<storageState>, got ${JSON.stringify(spec)}`);
+        const name = spec.slice(0, eq);
+        const file = spec.slice(eq + 1).trim();
+        if (!IDENTITY_NAME.test(name))
+            throw new FixtureSpecError(`--fixture-identity name ${JSON.stringify(name)} must be 1-64 of [A-Za-z0-9_.-], starting alphanumeric`);
+        if (seen.has(name))
+            throw new FixtureSpecError(`--fixture-identity ${name} is given twice`);
+        seen.add(name);
+        if (file === "")
+            throw new FixtureSpecError(`--fixture-identity ${name}: storage state path is empty`);
+        out[name] = isAbsolute(file) ? file : resolvePath(cwd, file);
+    }
+    for (const [name, path] of Object.entries(out)) {
+        if (!existsSync(path))
+            throw new FixtureSpecError(`fixture identity ${name}: storage state not found: ${path}`);
+    }
+    return out;
+}
+function hooksOf(flags) {
+    if (flags.before === undefined && flags.after === undefined)
+        return undefined;
+    const timeoutMs = flags.hookTimeoutMs === undefined ? undefined : Number(flags.hookTimeoutMs);
+    if (timeoutMs !== undefined && !(Number.isInteger(timeoutMs) && timeoutMs > 0)) {
+        throw new FixtureSpecError("--hook-timeout-ms must be a positive integer");
+    }
+    return {
+        ...(flags.before === undefined ? {} : { before: flags.before }),
+        ...(flags.after === undefined ? {} : { after: flags.after }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+    };
+}
+/** The run's fixture lifecycle, or `undefined` when none was asked for. Throws `FixtureSpecError`. */
+export function buildMissionFixtures(flags, ctx) {
+    const hooks = hooksOf(flags);
+    const file = flags.fixtures ?? ctx.targetFixtures;
+    const bounds = { allowlist: ctx.allowlist, baseUrl: ctx.baseUrl };
+    const spec = file !== undefined ? loadFixtureFile(file, bounds, { openRefs: hooks?.before !== undefined }) : ctx.spec;
+    const flagged = (flags.fixtureIdentity ?? []).map((x) => x.slice(0, Math.max(0, x.indexOf("="))));
+    if (spec === undefined && hooks === undefined) {
+        if (flagged.length > 0)
+            throw new FixtureSpecError("--fixture-identity names who a fixture step authenticates as: it needs --fixtures");
+        return undefined;
+    }
+    const secretFields = Object.fromEntries((ctx.secretFields ?? []).filter((f) => f.kind === "value").map((f) => [f.name, f.secret]));
+    // A named identity no step uses is a typo, not a no-op.
+    const usedNames = identityNames(spec);
+    for (const name of flagged) {
+        if (name !== "" && !usedNames.includes(name))
+            throw new FixtureSpecError(`--fixture-identity ${name}: no fixture step authenticates as ${name} (auth.identity)`);
+    }
+    // Only the identities the spec uses are checked for a file (an unused persona never blocks a run).
+    const used = new Set(identityNames(spec));
+    const bound = resolveFixtureIdentities(flags, {
+        ...(ctx.personas === undefined ? {} : { personas: Object.fromEntries(Object.entries(ctx.personas).filter(([n]) => used.has(n))) }),
+        ...(ctx.identities === undefined ? {} : { identities: Object.fromEntries(Object.entries(ctx.identities).filter(([n]) => used.has(n))) }),
+    });
+    return new MissionFixtures({
+        ...bounds,
+        ...(spec === undefined ? {} : { spec }),
+        ...(hooks === undefined ? {} : { hooks }),
+        allowShellHooks: flags.allowShellHooks === true,
+        auth: { ...(ctx.storageState === undefined ? {} : { storageStatePath: ctx.storageState }), secretFields, identities: bound },
+        ...(ctx.secrets === undefined ? {} : { secrets: ctx.secrets }),
+    });
+}
+/**
+ * Before any browser or request: every `${setup.x}` in `texts` must be an output the fixture
+ * declares (unless a `--before` hook may bind it), and a run without fixtures may not reference one.
+ */
+export function checkSetupRefs(texts, fx) {
+    // `null`: a `--before` hook may bind more names at run time (still checked when substituted).
+    const declared = fx === undefined ? new Set() : fx.declaredOutputs();
+    const secret = fx?.declaredSecretOutputs() ?? new Set();
+    for (const [where, v] of Object.entries(texts)) {
+        for (const text of v === undefined ? [] : typeof v === "string" ? [v] : v) {
+            for (const name of referencedNames(text)) {
+                if (fx === undefined)
+                    throw new UnboundSetupRefError(`${where} references \${setup.${name}} but the run has no --fixtures/--before`);
+                if (secret.has(name)) {
+                    throw new UnboundSetupRefError(`${where} references the secret output \${setup.${name}}; secret outputs stay inside the fixture's own requests`);
+                }
+                if (declared !== null && !declared.has(name))
+                    throw new UnboundSetupRefError(`${where} references \${setup.${name}}, which the fixture does not output`);
+            }
+        }
+    }
+}
+/** The origin `url` keeps whatever its `${setup.*}` references hold, or null when a value could move it. */
+function fixedOrigin(url) {
+    const originWith = (fill) => {
+        try {
+            return new URL(url.replace(SETUP_REF, fill)).origin;
+        }
+        catch {
+            return null;
+        }
+    };
+    // A reference after a `/` (or in the query) fills the path: any value keeps the origin.
+    const a = originWith("0");
+    if (a !== null && a === originWith("x.evil.test"))
+        return a;
+    // #243: a reference right after the origin (`http://host${setup.link}`) is a root-relative path —
+    // allowed, and its VALUE must start with `/` (checked once bound, by substituteUrlSetupRefs).
+    const b = originWith("/0");
+    if (b !== null && b === originWith("/x.evil.test"))
+        return b;
+    return null;
+}
+/**
+ * `url` with each `${setup.*}` replaced by a placeholder that keeps its origin — what the run's
+ * origin, allowlist and target config are read from before setup binds the real values.
+ */
+export function setupRefFreeUrl(url) {
+    if (!url.includes("${setup."))
+        return url;
+    const pathFill = (() => {
+        try {
+            return new URL(url.replace(SETUP_REF, "0")).origin === new URL(url.replace(SETUP_REF, "x.evil.test")).origin;
+        }
+        catch {
+            return false;
+        }
+    })();
+    return url.replace(SETUP_REF, pathFill || fixedOrigin(url) === null ? "0" : "/0");
+}
+/** Throws unless a `${setup.*}` reference in `url` leaves its origin fixed (the allowlist is decided before setup runs). */
+export function checkUrlRefOrigin(url) {
+    if (!url.includes("${setup."))
+        return;
+    if (fixedOrigin(url) === null) {
+        throw new UnboundSetupRefError("--url: a ${setup.*} reference may fill the path or query, never the origin — put it after a `/` (`http://host:8093/projects/${setup.id}`), or right after the origin for a root-relative path value (`http://host:8093${setup.link}` with a value like `/invite/abc`)");
+    }
+}
+/**
+ * `--url` with its `${setup.*}` references bound — and the bound URL still on the origin
+ * {@link checkUrlRefOrigin} fixed: a value placed right after the origin must be a root-relative path
+ * (`/…`), never `@evil.test`, `:8080` or `.evil.test`.
+ */
+export function substituteUrlSetupRefs(url, b) {
+    const out = substituteSetupRefs(url, b, { where: "--url" });
+    if (!url.includes("${setup."))
+        return out;
+    let origin = null;
+    try {
+        origin = new URL(out).origin;
+    }
+    catch {
+        // refused below
+    }
+    if (origin === null || origin !== fixedOrigin(url)) {
+        throw new UnboundSetupRefError("--url: a bound ${setup.*} value moved the URL off its origin — a value right after the origin must be a root-relative path starting with `/`");
+    }
+    return out;
+}
+/** Every string inside an invariants spec (#187), with the JSON path it sits at. */
+function specStrings(v, path, out) {
+    if (typeof v === "string")
+        out.push([path, v]);
+    else if (Array.isArray(v))
+        v.forEach((x, i) => specStrings(x, `${path}[${i}]`, out));
+    else if (v !== null && typeof v === "object")
+        for (const [k, x] of Object.entries(v))
+            specStrings(x, path === "" ? k : `${path}.${k}`, out);
+    return out;
+}
+/** The `${setup.*}`-bearing strings of an invariants spec, keyed `--invariants <path>`, for {@link checkSetupRefs}. */
+export function invariantSetupTexts(spec) {
+    return Object.fromEntries(specStrings(spec, "", []).filter(([, s]) => s.includes("${setup.")).map(([p, s]) => [`--invariants ${p}`, s]));
+}
+/**
+ * `${setup.x}` in an invariants spec (#187) — probe paths, `deniedAs.open`, capture routes — bound
+ * once setup ran. Origin-fixed like a fixture step: a bound value that moves a string off the origin
+ * it resolved to with the reference unfilled (`//evil.test/…`) is refused, never probed.
+ */
+export function substituteSpecSetupRefs(spec, b, baseUrl) {
+    const walk = (v, path) => {
+        if (typeof v === "string") {
+            if (!v.includes("${setup."))
+                return v;
+            const where = `--invariants ${path}`;
+            const out = substituteSetupRefs(v, b, { where });
+            let before = null;
+            let after = null;
+            try {
+                before = new URL(v.replace(SETUP_REF, "0"), baseUrl).origin;
+                after = new URL(out, baseUrl).origin;
+            }
+            catch {
+                // not a URL — nothing to keep on an origin
+            }
+            if (before !== after)
+                throw new UnboundSetupRefError(`${where}: a \${setup.*} value may fill the path or query, never the origin`);
+            return out;
+        }
+        if (Array.isArray(v))
+            return v.map((x, i) => walk(x, `${path}[${i}]`));
+        if (v !== null && typeof v === "object")
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x, path === "" ? k : `${path}.${k}`)]));
+        return v;
+    };
+    return walk(spec, "");
+}
+export function fixtureSetupFailedResult(err, fx) {
+    const reason = err instanceof FixtureSetupError ? err.message : `fixture setup failed: ${err.message}`;
+    return {
+        outcome: "inconclusive",
+        reason,
+        failure: { kind: "configuration", message: reason },
+        attribution: "configuration",
+        exitCode: 2,
+        fixtures: fx.record(),
+    };
+}
+/**
+ * Regression capture (#144): every reproduce/minimize replay restores + re-runs the fixture the
+ * failing Recording was made from. The spec is `--fixtures`, else the one saved in `--result`
+ * (re-validated against that mission's allowlist); shell hooks must be re-supplied (and match the
+ * mission's by hash). A Recording that carries a fixture identity is never replayed without one.
+ */
+export function regressionFixtures(flags, recording, missionResult, 
+/** `--storage-state` (#129): wins over the one recorded with the mission. */
+storageState) {
+    const result = isObject(missionResult) && isObject(missionResult.result) ? missionResult.result : undefined;
+    const target = isObject(result?.target) ? result.target : undefined;
+    const saved = isObject(result?.fixtures) ? result.fixtures : undefined;
+    const allowlist = Array.isArray(target?.allowlist) ? target.allowlist.filter((a) => typeof a === "string") : [recording.site];
+    const baseUrl = typeof target?.seedUrl === "string" ? target.seedUrl : recording.site;
+    const savedHooks = isObject(saved?.hooks) ? saved.hooks : {};
+    if ((savedHooks.before !== undefined || savedHooks.after !== undefined) &&
+        ((flags.before === undefined ? undefined : hookHash(flags.before)) !== savedHooks.before ||
+            (flags.after === undefined ? undefined : hookHash(flags.after)) !== savedHooks.after)) {
+        throw new FixtureSpecError("the mission ran with --before/--after shell hooks: re-supply the SAME commands with --allow-shell-hooks");
+    }
+    const spec = flags.fixtures === undefined && saved?.spec !== undefined
+        ? parseFixtureSpec(saved.spec, { allowlist, baseUrl }, { openRefs: flags.before !== undefined })
+        : undefined;
+    const fx = buildMissionFixtures(flags, {
+        allowlist,
+        baseUrl,
+        ...(storageState !== undefined
+            ? { storageState }
+            : typeof target?.storageStatePath === "string"
+                ? { storageState: target.storageStatePath }
+                : {}),
+        ...(spec === undefined ? {} : { spec }),
+        // #243: re-mint as the identities the mission's steps used (a --fixture-identity re-binds one).
+        ...(isObject(saved?.identities)
+            ? { identities: Object.fromEntries(Object.entries(saved.identities).filter((e) => typeof e[1] === "string")) }
+            : {}),
+    });
+    if (fx === undefined && recording.fixture !== undefined) {
+        throw new FixtureSpecError(`this Recording started from fixture ${recording.fixture.identity}: pass --fixtures (or --result with its saved fixture) so every replay restores the same state`);
+    }
+    return fx;
+}
+function isObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+//# sourceMappingURL=fixture-cli.js.map

package/dist/fixture-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fixture-cli.js","sourceRoot":"","sources":["../src/fixture-cli.ts"],"names":[],"mappings":"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"}

package/dist/github-issue-filer.d.ts

@@ -0,0 +1,62 @@
+import { type CredentialStore, type RetryDeps } from "@jevitate/ai-core";
+import type { IssueFilerPort, IssueRef, NewIssue } from "@jevitate/domain";
+/**
+ * The GitHub adapter for the domain's `IssueFilerPort` (owner ruling 3). It prefers the `gh` CLI
+ * when it is installed (the user's own authenticated session); otherwise it uses the REST API with
+ * `GITHUB_TOKEN` from jevitate's credential store. The token goes ONLY into the Authorization
+ * header — never into a message, a log line, an error, or an issue — and any error text is
+ * scrubbed of it before it leaves this module.
+ *
+ * Both transports are injectable so tests exercise the exact commands/requests without ever
+ * talking to GitHub.
+ */
+export interface ExecResult {
+    readonly code: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+/** Runs a command with optional stdin. No shell — arguments are passed verbatim (portable). */
+export type Exec = (cmd: string, args: readonly string[], stdin?: string) => Promise<ExecResult>;
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    readonly status: number;
+    text(): Promise<string>;
+}>;
+export declare const defaultExec: Exec;
+export interface GitHubIssueFilerDeps {
+    readonly store: CredentialStore;
+    readonly exec?: Exec;
+    readonly fetch?: FetchLike;
+    readonly apiBase?: string;
+    /** Backoff for transient REST failures (injected clock in tests). */
+    readonly retry?: RetryDeps;
+}
+export declare class GitHubFilingError extends Error {
+    readonly code: "E_ISSUE_FILING";
+    /** The HTTP status, for a REST failure (drives the transient-retry decision). */
+    readonly status?: number;
+    constructor(message: string, status?: number);
+}
+export declare class GitHubIssueFiler implements IssueFilerPort {
+    #private;
+    constructor(deps: GitHubIssueFilerDeps);
+    /** `gh` when it is installed and runnable, else REST (which needs `GITHUB_TOKEN`). */
+    mode(): Promise<"gh" | "rest">;
+    findOpenByMarker(repo: string, marker: string): Promise<IssueRef | null>;
+    /**
+     * Creating an issue is NOT idempotent, so it is never blindly retried: a "failed" create (a 502,
+     * a dropped connection) may well have persisted. After a transient failure the fingerprint
+     * search runs again — if the issue now exists it IS the one this call created and is returned;
+     * only if it is still absent is the create tried again, on the backoff schedule. A body without a
+     * fingerprint marker cannot be checked, so it gets exactly one attempt. Same for both transports.
+     */
+    create(repo: string, issue: NewIssue): Promise<IssueRef>;
+    /**
+     * An occurrence comment is not idempotent either: it gets exactly one attempt (a duplicate
+     * comment is worse than a missing one — the draft on disk keeps the occurrence either way).
+     */
+    comment(repo: string, number: number, body: string): Promise<IssueRef>;
+}

package/dist/github-issue-filer.js

@@ -0,0 +1,189 @@
+import { spawn } from "node:child_process";
+import { BACKOFF_SCHEDULE_MS, isTransientError, jittered, redactText, retryTransient, } from "@jevitate/ai-core";
+import { clock } from "@jevitate/domain";
+export const defaultExec = (cmd, args, stdin) => new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    const child = spawn(cmd, [...args], { stdio: ["pipe", "pipe", "pipe"] });
+    child.stdout.on("data", (d) => (stdout += d.toString("utf8")));
+    child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
+    child.on("error", (e) => resolve({ code: -1, stdout, stderr: e.message }));
+    child.on("close", (code) => resolve({ code: code ?? -1, stdout, stderr }));
+    child.stdin.end(stdin ?? "");
+});
+export class GitHubFilingError extends Error {
+    code = "E_ISSUE_FILING";
+    /** The HTTP status, for a REST failure (drives the transient-retry decision). */
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "GitHubFilingError";
+        if (status !== undefined)
+            this.status = status;
+    }
+}
+const ISSUE_NUMBER = /\/issues\/(\d+)/;
+/** The dedup marker every jevitate draft body carries (see `fingerprintMarker`). */
+const FINGERPRINT_MARKER = /<!-- jevitate-fingerprint: [0-9a-f]+ -->/;
+function parseIssueUrl(url) {
+    const m = ISSUE_NUMBER.exec(url);
+    if (m?.[1] === undefined)
+        throw new GitHubFilingError(`unexpected issue URL: ${url}`);
+    return { number: Number(m[1]), url };
+}
+/** The bare fingerprint inside a `<!-- jevitate-fingerprint: … -->` marker (the searchable token). */
+function markerToken(marker) {
+    return marker.replace(/^<!--\s*jevitate-fingerprint:\s*/, "").replace(/\s*-->$/, "");
+}
+function isRecord(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+export class GitHubIssueFiler {
+    #exec;
+    #fetch;
+    #store;
+    #apiBase;
+    #retry;
+    #mode;
+    constructor(deps) {
+        this.#exec = deps.exec ?? defaultExec;
+        this.#fetch = deps.fetch;
+        this.#store = deps.store;
+        this.#apiBase = deps.apiBase ?? "https://api.github.com";
+        this.#retry = deps.retry ?? {};
+    }
+    /** `gh` when it is installed and runnable, else REST (which needs `GITHUB_TOKEN`). */
+    mode() {
+        this.#mode ??= this.#exec("gh", ["--version"]).then((r) => (r.code === 0 ? "gh" : "rest"));
+        return this.#mode;
+    }
+    #scrub(text) {
+        const token = this.#store.read("GITHUB_TOKEN");
+        return token === undefined ? text : redactText(text, [token]);
+    }
+    async #gh(args, stdin) {
+        const r = await this.#exec("gh", args, stdin);
+        if (r.code !== 0) {
+            // gh reports API failures as "HTTP 502: Bad Gateway (…)": keep the status so the transient
+            // classification is the same as for the REST transport.
+            const status = /\bHTTP (\d{3})\b/.exec(r.stderr)?.[1];
+            throw new GitHubFilingError(this.#scrub(`gh ${args[0] ?? ""} ${args[1] ?? ""} failed: ${r.stderr.trim()}`), status === undefined ? undefined : Number(status));
+        }
+        return r.stdout;
+    }
+    /**
+     * An IDEMPOTENT REST call (a read), retried with backoff on transient failures (429/5xx/network);
+     * typed failure after. Writes never go through here — see `create` / `comment`.
+     */
+    async #rest(method, path) {
+        const r = await retryTransient(() => this.#restOnce(method, path), this.#retry);
+        if (r.ok)
+            return r.value;
+        const e = r.error;
+        throw e instanceof GitHubFilingError
+            ? e
+            : new GitHubFilingError(this.#scrub(`GitHub API ${method} ${path} failed: ${e instanceof Error ? e.message : String(e)}`));
+    }
+    async #restOnce(method, path, body) {
+        const token = this.#store.read("GITHUB_TOKEN");
+        if (token === undefined) {
+            throw new GitHubFilingError("filing needs the gh CLI or a GITHUB_TOKEN in jevitate's credential store");
+        }
+        const doFetch = this.#fetch ?? globalThis.fetch;
+        const res = await doFetch(`${this.#apiBase}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+                "User-Agent": "jevitate",
+                ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const text = await res.text();
+        if (res.status < 200 || res.status >= 300) {
+            throw new GitHubFilingError(this.#scrub(`GitHub API ${res.status} on ${method} ${path}: ${text.slice(0, 300)}`), res.status);
+        }
+        return text === "" ? null : JSON.parse(text);
+    }
+    async findOpenByMarker(repo, marker) {
+        const token = markerToken(marker);
+        if ((await this.mode()) === "gh") {
+            const out = await this.#gh([
+                "issue", "list", "--repo", repo, "--state", "open", "--search", `${token} in:body`,
+                "--json", "number,url,body", "--limit", "20",
+            ]);
+            const list = JSON.parse(out === "" ? "[]" : out);
+            if (!Array.isArray(list))
+                return null;
+            for (const item of list) {
+                if (isRecord(item) && typeof item.body === "string" && item.body.includes(marker) && typeof item.number === "number" && typeof item.url === "string") {
+                    return { number: item.number, url: item.url };
+                }
+            }
+            return null;
+        }
+        const q = encodeURIComponent(`repo:${repo} is:issue is:open in:body ${token}`);
+        const res = await this.#rest("GET", `/search/issues?q=${q}&per_page=20`);
+        const items = isRecord(res) && Array.isArray(res.items) ? res.items : [];
+        for (const item of items) {
+            if (isRecord(item) && typeof item.body === "string" && item.body.includes(marker) && typeof item.number === "number" && typeof item.html_url === "string") {
+                return { number: item.number, url: item.html_url };
+            }
+        }
+        return null;
+    }
+    /** One create attempt, on whichever transport is in use. */
+    async #createOnce(repo, issue) {
+        if ((await this.mode()) === "gh") {
+            const out = await this.#gh(["issue", "create", "--repo", repo, "--title", issue.title, "--body-file", "-"], issue.body);
+            return parseIssueUrl(out.trim());
+        }
+        const res = await this.#restOnce("POST", `/repos/${repo}/issues`, { title: issue.title, body: issue.body });
+        if (!isRecord(res) || typeof res.number !== "number" || typeof res.html_url !== "string") {
+            throw new GitHubFilingError("GitHub API returned no issue");
+        }
+        return { number: res.number, url: res.html_url };
+    }
+    /**
+     * Creating an issue is NOT idempotent, so it is never blindly retried: a "failed" create (a 502,
+     * a dropped connection) may well have persisted. After a transient failure the fingerprint
+     * search runs again — if the issue now exists it IS the one this call created and is returned;
+     * only if it is still absent is the create tried again, on the backoff schedule. A body without a
+     * fingerprint marker cannot be checked, so it gets exactly one attempt. Same for both transports.
+     */
+    async create(repo, issue) {
+        const marker = FINGERPRINT_MARKER.exec(issue.body)?.[0];
+        const schedule = this.#retry.schedule ?? BACKOFF_SCHEDULE_MS;
+        const sleep = this.#retry.sleep ?? ((ms) => clock.sleep(ms));
+        const random = this.#retry.random ?? Math.random;
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await this.#createOnce(repo, issue);
+            }
+            catch (e) {
+                const delay = schedule[attempt];
+                if (marker === undefined || delay === undefined || !isTransientError(e))
+                    throw e;
+                const landed = await this.findOpenByMarker(repo, marker);
+                if (landed !== null)
+                    return landed;
+                await sleep(jittered(delay, random));
+            }
+        }
+    }
+    /**
+     * An occurrence comment is not idempotent either: it gets exactly one attempt (a duplicate
+     * comment is worse than a missing one — the draft on disk keeps the occurrence either way).
+     */
+    async comment(repo, number, body) {
+        if ((await this.mode()) === "gh") {
+            const out = await this.#gh(["issue", "comment", String(number), "--repo", repo, "--body-file", "-"], body);
+            return { number, url: out.trim() };
+        }
+        const res = await this.#restOnce("POST", `/repos/${repo}/issues/${number}/comments`, { body });
+        return { number, url: isRecord(res) && typeof res.html_url === "string" ? res.html_url : "" };
+    }
+}
+//# sourceMappingURL=github-issue-filer.js.map

package/dist/github-issue-filer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github-issue-filer.js","sourceRoot":"","sources":["../src/github-issue-filer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,QAAQ,EACR,UAAU,EACV,cAAc,GAGf,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AA2BzC,MAAM,CAAC,MAAM,WAAW,GAAS,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CACpD,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;IACtB,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;IACzE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACvE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IACvE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC3E,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC3E,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;AAC/B,CAAC,CAAC,CAAC;AAWL,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,IAAI,GAAG,gBAAyB,CAAC;IAC1C,iFAAiF;IACxE,MAAM,CAAU;IACzB,YAAY,OAAe,EAAE,MAAe;QAC1C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACjD,CAAC;CACF;AAED,MAAM,YAAY,GAAG,iBAAiB,CAAC;AACvC,oFAAoF;AACpF,MAAM,kBAAkB,GAAG,0CAA0C,CAAC;AAEtE,SAAS,aAAa,CAAC,GAAW;IAChC,MAAM,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,SAAS;QAAE,MAAM,IAAI,iBAAiB,CAAC,yBAAyB,GAAG,EAAE,CAAC,CAAC;IACtF,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC;AACvC,CAAC;AAED,sGAAsG;AACtG,SAAS,WAAW,CAAC,MAAc;IACjC,OAAO,MAAM,CAAC,OAAO,CAAC,kCAAkC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AACvF,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,OAAO,gBAAgB;IAClB,KAAK,CAAO;IACZ,MAAM,CAAwB;IAC9B,MAAM,CAAkB;IACxB,QAAQ,CAAS;IACjB,MAAM,CAAY;IAC3B,KAAK,CAAqC;IAE1C,YAAY,IAA0B;QACpC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,IAAI,WAAW,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,IAAI,wBAAwB,CAAC;QACzD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;IACjC,CAAC;IAED,sFAAsF;IACtF,IAAI;QACF,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3F,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,MAAM,CAAC,IAAY;QACjB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC/C,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAuB,EAAE,KAAc;QAC/C,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAC9C,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YACjB,2FAA2F;YAC3F,wDAAwD;YACxD,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YACtD,MAAM,IAAI,iBAAiB,CACzB,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,EAC9E,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAClD,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,CAAC,MAAM,CAAC;IAClB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,KAAK,CAAC,MAAa,EAAE,IAAY;QACrC,MAAM,CAAC,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAChF,IAAI,CAAC,CAAC,EAAE;YAAE,OAAO,CAAC,CAAC,KAAK,CAAC;QACzB,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC;QAClB,MAAM,CAAC,YAAY,iBAAiB;YAClC,CAAC,CAAC,CAAC;YACH,CAAC,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,MAAM,IAAI,IAAI,YAAY,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC/H,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,MAAc,EAAE,IAAY,EAAE,IAAc;QAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC/C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,IAAI,iBAAiB,CAAC,0EAA0E,CAAC,CAAC;QAC1G,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,IAAK,UAAU,CAAC,KAA8B,CAAC;QAC1E,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,GAAG,IAAI,EAAE,EAAE;YACnD,MAAM;YACN,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,KAAK,EAAE;gBAChC,MAAM,EAAE,6BAA6B;gBACrC,sBAAsB,EAAE,YAAY;gBACpC,YAAY,EAAE,UAAU;gBACxB,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;aACtE;YACD,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;SAC9D,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,GAAG,CAAC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;YAC1C,MAAM,IAAI,iBAAiB,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,GAAG,CAAC,MAAM,OAAO,MAAM,IAAI,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC/H,CAAC;QACD,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC;IAED,KAAK,CAAC,gBAAgB,CAAC,IAAY,EAAE,MAAc;QACjD,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC;QAClC,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC;gBACzB,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,KAAK,UAAU;gBAClF,QAAQ,EAAE,iBAAiB,EAAE,SAAS,EAAE,IAAI;aAC7C,CAAC,CAAC;YACH,MAAM,IAAI,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAC1D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;YACtC,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;gBACxB,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;oBACrJ,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;gBAChD,CAAC;YACH,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,CAAC,GAAG,kBAAkB,CAAC,QAAQ,IAAI,6BAA6B,KAAK,EAAE,CAAC,CAAC;QAC/E,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,oBAAoB,CAAC,cAAc,CAAC,CAAC;QACzE,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;gBAC1J,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC;YACrD,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,4DAA4D;IAC5D,KAAK,CAAC,WAAW,CAAC,IAAY,EAAE,KAAe;QAC7C,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACxH,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC;QACnC,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,IAAI,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5G,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;YACzF,MAAM,IAAI,iBAAiB,CAAC,8BAA8B,CAAC,CAAC;QAC9D,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,CAAC;IACnD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,KAAe;QACxC,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,mBAAmB,CAAC;QAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,CAAC,EAAU,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;QACrE,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;QACjD,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAC7C,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;gBAChC,IAAI,MAAM,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;oBAAE,MAAM,CAAC,CAAC;gBACjF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;gBACzD,IAAI,MAAM,KAAK,IAAI;oBAAE,OAAO,MAAM,CAAC;gBACnC,MAAM,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;YACvC,CAAC;QACH,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,MAAc,EAAE,IAAY;QACtD,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,EAAE,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;YAC3G,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;QACrC,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,UAAU,IAAI,WAAW,MAAM,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/F,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAChG,CAAC;CACF"}

package/dist/host-health-run.d.ts

@@ -0,0 +1,25 @@
+import { HostHealthSampler, degradedEnvironmentOutcome } from "@jevitate/explore";
+import type { EnvironmentDegraded, HostHealthSummary, MissionFailure } from "@jevitate/domain";
+import { type ResourceGovernor } from "@jevitate/playwright";
+/**
+ * One host-health sampler per mission run (#203), shared by every strategy's runner: started (with
+ * one sample taken) BEFORE the browser opens, fed every transcript entry, handed to the mission so a
+ * hang/no-progress met on a starved host is marked `environment-degraded`, and summarised into the
+ * result's `hostHealth`. `injected` is the test seam (a deterministic fake host).
+ */
+export declare function startHostHealth(injected?: HostHealthSampler): Promise<HostHealthSampler>;
+/** What every result carries from the sampler, and the degraded-environment verdict rule applied. */
+export interface HostHealthVerdict<O extends string> {
+    readonly outcome: O | "inconclusive";
+    /** Set when the rule turned the outcome `inconclusive` (reason `degraded-environment`). */
+    readonly failure?: MissionFailure;
+    readonly fields: {
+        readonly hostHealth: HostHealthSummary;
+        readonly environmentDegraded: EnvironmentDegraded[];
+    };
+}
+/**
+ * Takes the closing sample and applies the run-level rule: most steps starved → `inconclusive`
+ * (`degraded-environment`), never `clean` (see `degradedEnvironmentOutcome`).
+ */
+export declare function finishHostHealth<O extends string>(health: HostHealthSampler, outcome: O, opts?: Parameters<typeof degradedEnvironmentOutcome>[2], governor?: ResourceGovernor): Promise<HostHealthVerdict<O>>;

package/dist/host-health-run.js

@@ -0,0 +1,33 @@
+import { HostHealthSampler, degradedEnvironmentOutcome } from "@jevitate/explore";
+import { sharedResourceGovernor } from "@jevitate/playwright";
+import { clock } from "@jevitate/domain";
+/** When each run's sampler started (#205: the window the governor's summary covers). */
+const runStarts = new WeakMap();
+/**
+ * One host-health sampler per mission run (#203), shared by every strategy's runner: started (with
+ * one sample taken) BEFORE the browser opens, fed every transcript entry, handed to the mission so a
+ * hang/no-progress met on a starved host is marked `environment-degraded`, and summarised into the
+ * result's `hostHealth`. `injected` is the test seam (a deterministic fake host).
+ */
+export async function startHostHealth(injected) {
+    const health = (injected ?? new HostHealthSampler()).start();
+    runStarts.set(health, clock.now());
+    await health.sample();
+    return health;
+}
+/**
+ * Takes the closing sample and applies the run-level rule: most steps starved → `inconclusive`
+ * (`degraded-environment`), never `clean` (see `degradedEnvironmentOutcome`).
+ */
+export async function finishHostHealth(health, outcome, opts = {}, governor = sharedResourceGovernor()) {
+    await health.sample();
+    // #205: what resource governance did during this run (cap, slot, throttling, memory) rides along.
+    const hostHealth = { ...health.summary(), resources: governor.snapshot(runStarts.get(health) ?? 0) };
+    const verdict = degradedEnvironmentOutcome(outcome, hostHealth, opts);
+    return {
+        outcome: verdict.outcome,
+        ...(verdict.failure === undefined ? {} : { failure: verdict.failure }),
+        fields: { hostHealth, environmentDegraded: health.findings() },
+    };
+}
+//# sourceMappingURL=host-health-run.js.map