@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/runtime/poll.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared exponential backoff for values that arrive outside the request that needs them.
+ *
+ * Mail catchers, TOTP harvest pages, and human OAuth clicks are eventually consistent. The API tester
+ * owns the sleep schedule so a hook only has to read the store and return `null` until a
+ * value is there.
+ */
+export interface BackoffConfig {
+    /** Inclusive probe count. Defaults to 6. */
+    attempts: number;
+    /** First sleep after a miss, in ms. Defaults to 200. */
+    initialMs: number;
+    /** Ceiling for the doubled sleep, in ms. Defaults to 3000. */
+    maxMs: number;
+}
+export declare const DEFAULT_OUT_OF_BAND: BackoffConfig;
+export declare function resolveBackoff(config?: Partial<BackoffConfig>): BackoffConfig;
+/**
+ * Sleep after every failed probe, including the last — that is the 0.6.2 schedule, so an
+ * unchanged config still waits ~9s worst case (200+400+800+1600+3000+3000).
+ */
+export declare function backoffDelays(config: BackoffConfig): number[];
+/** Sum of every sleep in the schedule. Hook work is not included. */
+export declare function worstCaseWaitMs(config?: Partial<BackoffConfig>): number;
+/** `null` and `""` mean "not yet" — the store is empty, not that delivery failed. */
+export declare function isAbsentValue(value: unknown): boolean;
+export declare function pollWithBackoff<T>(probe: (attempt: number) => Promise<T>, config: BackoffConfig, absent?: (value: T) => boolean): Promise<T | undefined>;
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=poll.d.ts.map

package/dist/api/runtime/poll.js

@@ -0,0 +1,59 @@
+/**
+ * Shared exponential backoff for values that arrive outside the request that needs them.
+ *
+ * Mail catchers, TOTP harvest pages, and human OAuth clicks are eventually consistent. The API tester
+ * owns the sleep schedule so a hook only has to read the store and return `null` until a
+ * value is there.
+ */
+export const DEFAULT_OUT_OF_BAND = {
+    attempts: 6,
+    initialMs: 200,
+    maxMs: 3000,
+};
+export function resolveBackoff(config) {
+    return {
+        attempts: positiveInt(config?.attempts, DEFAULT_OUT_OF_BAND.attempts),
+        initialMs: positiveInt(config?.initialMs, DEFAULT_OUT_OF_BAND.initialMs),
+        maxMs: positiveInt(config?.maxMs, DEFAULT_OUT_OF_BAND.maxMs),
+    };
+}
+function positiveInt(value, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.floor(value);
+}
+/**
+ * Sleep after every failed probe, including the last — that is the 0.6.2 schedule, so an
+ * unchanged config still waits ~9s worst case (200+400+800+1600+3000+3000).
+ */
+export function backoffDelays(config) {
+    const delays = [];
+    let delay = config.initialMs;
+    for (let i = 0; i < config.attempts; i++) {
+        delays.push(delay);
+        delay = Math.min(delay * 2, config.maxMs);
+    }
+    return delays;
+}
+/** Sum of every sleep in the schedule. Hook work is not included. */
+export function worstCaseWaitMs(config) {
+    return backoffDelays(resolveBackoff(config)).reduce((sum, delay) => sum + delay, 0);
+}
+/** `null` and `""` mean "not yet" — the store is empty, not that delivery failed. */
+export function isAbsentValue(value) {
+    return value === null || value === "";
+}
+export async function pollWithBackoff(probe, config, absent = isAbsentValue) {
+    const delays = backoffDelays(config);
+    for (const [index, wait] of delays.entries()) {
+        const value = await probe(index + 1);
+        if (!absent(value))
+            return value;
+        await sleep(wait);
+    }
+    return undefined;
+}
+export function sleep(ms) {
+    return new Promise((done) => setTimeout(done, ms));
+}
+//# sourceMappingURL=poll.js.map

package/dist/api/runtime/principals.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A run's principals as it leaves them, for `principals.json`: who each is, its tenant, rank and
+ * scope, and what it held, so a second config (a CDN host, a second document) can reuse them. No
+ * credential value is ever written there; the next run acquires its own by the same recipes. Values
+ * leave the run only for `--keep-credentials`, which writes them outside the output directory.
+ * Identity secrets stay out too: a credential-named key (`password`, `apiKey`) or a value the run
+ * holds as a secret is omitted, so a recipe that signs in with one reads it from the config, never the file.
+ */
+import type { PrincipalsConfig } from "../config/types/security.ts";
+import type { HeldCredential } from "../credentials/store.ts";
+import type { Redactor } from "../security/redact.ts";
+/** A credential a principal held when the run ended: which, and until when, never its value. */
+export interface PersistedCredential {
+    scheme: string;
+    scopes: string[];
+    /** Epoch ms it lapses, or null when it never does as far as the API tester could tell. */
+    expiresAt: number | null;
+}
+export interface PersistedPrincipal {
+    id: string;
+    /** The data recipes interpolate as `{principal.<key>}`: from config, a fresh signup or a login's claims. */
+    identity: Record<string, unknown>;
+    tenant?: string;
+    rank: number;
+    scope: Record<string, string>;
+    inviteAs?: string;
+    credentials: PersistedCredential[];
+    /** Why the run went on without it: what blocked its signup or login. Absent for a principal that signed in. */
+    blocked?: string;
+}
+export interface PersistedPrincipalsFile {
+    principals: PersistedPrincipal[];
+}
+/** A credential value the run held, kept by `--keep-credentials` for later commands such as teardown replay. */
+export interface KeptCredential extends PersistedCredential {
+    principal: string;
+    value: string;
+}
+/** What a principal is when the run ends. */
+export interface SnapshotInput {
+    id: string;
+    identity: Readonly<Record<string, unknown>>;
+    tenant?: string;
+    rank: number;
+    scope: Readonly<Record<string, string>>;
+    inviteAs?: string;
+    blocked?: string;
+}
+/** What the run knows when it ends: the credentials it held, and the redactor that names its secrets. */
+export interface SnapshotRun {
+    held: readonly HeldCredential[];
+    redactor: Pick<Redactor, "holdsSecret">;
+}
+/** The principal as `principals.json` keeps it, with the credentials `held` lists for it and no identity secret. */
+export declare function snapshotPrincipal(input: SnapshotInput, { held, redactor }: SnapshotRun): PersistedPrincipal;
+/** Every value `held` lists, for `--keep-credentials`. */
+export declare function keptCredentials(held: readonly HeldCredential[]): KeptCredential[];
+/** `principals.json` read back into the config's principals map. */
+export declare function parsePersistedPrincipals(raw: string, source?: string): PrincipalsConfig;
+/**
+ * Synchronous so a config file can call it at module load. The file never holds an identity secret,
+ * so a principal that signs in with one takes it from the config: spread the config's own entry over
+ * the persisted one, `{ ...persisted.alpha, ...principals.alpha }`.
+ */
+export declare function loadPersistedPrincipals(path: string): PrincipalsConfig;
+//# sourceMappingURL=principals.d.ts.map

package/dist/api/runtime/principals.js

@@ -0,0 +1,133 @@
+/**
+ * A run's principals as it leaves them, for `principals.json`: who each is, its tenant, rank and
+ * scope, and what it held, so a second config (a CDN host, a second document) can reuse them. No
+ * credential value is ever written there; the next run acquires its own by the same recipes. Values
+ * leave the run only for `--keep-credentials`, which writes them outside the output directory.
+ * Identity secrets stay out too: a credential-named key (`password`, `apiKey`) or a value the run
+ * holds as a secret is omitted, so a recipe that signs in with one reads it from the config, never the file.
+ */
+import { readFileSync } from "node:fs";
+import { isSecretJsonKey } from "../security/credential-names.js";
+/* Keys a principal entry grades or authenticates by: never taken from persisted identity data. */
+const RESERVED = /* @__PURE__ */ new Set([
+    "fresh",
+    "inviteAs",
+    "rank",
+    "scope",
+    "security",
+    "tenant",
+]);
+/** The principal as `principals.json` keeps it, with the credentials `held` lists for it and no identity secret. */
+export function snapshotPrincipal(input, { held, redactor }) {
+    const snap = {
+        credentials: held
+            .filter((entry) => entry.principal === input.id)
+            .map(({ credential, scheme, scopes }) => ({ expiresAt: credential.expiresAt, scheme, scopes: [...scopes] })),
+        id: input.id,
+        identity: withoutSecrets(input.identity, redactor),
+        rank: input.rank,
+        scope: { ...input.scope },
+    };
+    if (input.tenant !== undefined)
+        snap.tenant = input.tenant;
+    if (input.inviteAs !== undefined && !redactor.holdsSecret(input.inviteAs))
+        snap.inviteAs = input.inviteAs;
+    if (input.blocked !== undefined)
+        snap.blocked = input.blocked;
+    return snap;
+}
+/* `data` without a credential-named key or a value the run holds as a secret, at any depth. */
+function withoutSecrets(data, redactor) {
+    const kept = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (isSecretJsonKey(key))
+            continue;
+        if (typeof value === "string" && redactor.holdsSecret(value))
+            continue;
+        kept[key] = isObject(value) ? withoutSecrets(value, redactor) : value;
+    }
+    return kept;
+}
+/** Every value `held` lists, for `--keep-credentials`. */
+export function keptCredentials(held) {
+    return held.map(({ credential, principal, scheme, scopes }) => ({
+        expiresAt: credential.expiresAt,
+        principal,
+        scheme,
+        scopes: [...scopes],
+        value: credential.value,
+    }));
+}
+/** The principal entries of a parsed file: `{ principals: [...] }` or a bare array. */
+function listOf(parsed) {
+    if (Array.isArray(parsed))
+        return parsed;
+    if (parsed === null || typeof parsed !== "object")
+        return null;
+    const { principals } = parsed;
+    return Array.isArray(principals) ? principals : null;
+}
+/** One entry as an id and a config principal, or undefined when it has no id to go by. */
+function entryOf(item) {
+    if (item === null || typeof item !== "object")
+        return undefined;
+    const rec = item;
+    if (typeof rec.id !== "string" || rec.id === "")
+        return undefined;
+    const identity = isObject(rec.identity) ? rec.identity : {};
+    const entry = {
+        ...Object.fromEntries(Object.entries(identity).filter(([key]) => !RESERVED.has(key))),
+        scope: stringMap(rec.scope),
+    };
+    if (typeof rec.tenant === "string")
+        entry.tenant = rec.tenant;
+    if (typeof rec.rank === "number")
+        entry.rank = rec.rank;
+    if (typeof rec.inviteAs === "string")
+        entry.inviteAs = rec.inviteAs;
+    return [rec.id, entry];
+}
+/** `principals.json` read back into the config's principals map. */
+export function parsePersistedPrincipals(raw, source = "principals.json") {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`testing api: ${source} is not valid JSON: ${String(error)}`, { cause: error });
+    }
+    const list = listOf(parsed);
+    if (list === null) {
+        throw new Error(`testing api: ${source} must be { principals: [...] } or an array of principals`);
+    }
+    const entries = list.map(entryOf).filter((entry) => entry !== undefined);
+    if (entries.length === 0) {
+        throw new Error(`testing api: ${source} contains no usable principals`);
+    }
+    return Object.fromEntries(entries);
+}
+/**
+ * Synchronous so a config file can call it at module load. The file never holds an identity secret,
+ * so a principal that signs in with one takes it from the config: spread the config's own entry over
+ * the persisted one, `{ ...persisted.alpha, ...principals.alpha }`.
+ */
+export function loadPersistedPrincipals(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        throw new Error(`testing api: cannot read persisted principals from ${path}: ${String(error)}`, { cause: error });
+    }
+    return parsePersistedPrincipals(raw, path);
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** The string entries of a plain object; anything else holds none. */
+function stringMap(value) {
+    if (!isObject(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"));
+}
+//# sourceMappingURL=principals.js.map

package/dist/api/runtime/privileged-create.d.ts

@@ -0,0 +1,13 @@
+import type { OperationModel } from "../spec/graph/types.ts";
+/** A principal as the rule reads it. */
+export interface Ranked {
+    id: string;
+    rank: number;
+    tenant?: string | undefined;
+}
+/**
+ * Why `sender` must not send `createOp`, or undefined when it may: the body requires an x-privileged
+ * property and a principal of the sender's tenant outranks it.
+ */
+export declare function privilegedBar(createOp: Pick<OperationModel, "operationId" | "privilegedRequired">, sender: Ranked, principals: readonly Ranked[]): string | undefined;
+//# sourceMappingURL=privileged-create.d.ts.map

package/dist/api/runtime/privileged-create.js

@@ -0,0 +1,21 @@
+/*
+ * A create whose body requires a property marked `x-privileged` can be sent by the highest rank alone:
+ * an ordinary body leaves an optional one out, but a required one must go, and only that rank may set
+ * it. Anyone else's create is a guaranteed refusal, so it is never sent; it is untested with the reason.
+ */
+/**
+ * Why `sender` must not send `createOp`, or undefined when it may: the body requires an x-privileged
+ * property and a principal of the sender's tenant outranks it.
+ */
+export function privilegedBar(createOp, sender, principals) {
+    if (createOp.privilegedRequired.length === 0)
+        return undefined;
+    const top = principals
+        .filter((principal) => principal.tenant === sender.tenant)
+        .reduce((highest, principal) => (principal.rank > highest.rank ? principal : highest), sender);
+    if (top.rank <= sender.rank)
+        return undefined;
+    return (`${createOp.operationId} requires ${createOp.privilegedRequired.join(", ")}, marked x-privileged, which ` +
+        `only ${top.id} (rank ${top.rank}) may set; ${sender.id} (rank ${sender.rank}) does not send it`);
+}
+//# sourceMappingURL=privileged-create.js.map

package/dist/api/runtime/probe-judging.d.ts

@@ -0,0 +1,9 @@
+import type { CheckId } from "./check-ids.ts";
+import type { Exchange } from "./exchange.ts";
+/** The documentation-conformance judges: each compares an answer with what the document says. */
+export declare const DOCUMENTATION_JUDGES: readonly CheckId[];
+/** Whether the exchange was a probe: sent as one, or with a forged credential. */
+export declare function isProbeExchange(exchange: Pick<Exchange, "probe" | "forged">): boolean;
+/** Whether `judge` grades `exchange`: anything but a probe, unless the judge is not a documentation judge. */
+export declare function judges(judge: CheckId, exchange: Pick<Exchange, "probe" | "forged">): boolean;
+//# sourceMappingURL=probe-judging.d.ts.map

package/dist/api/runtime/probe-judging.js

@@ -0,0 +1,26 @@
+/*
+ * A probe is deliberately abnormal: sent with no credential, a forged one, or one made to be
+ * refused. What it is answered is the security checks' to judge. Judges whose verdict is "the answer
+ * differs from the document" leave it alone: a correct 401 to an anonymous probe, on an API that
+ * documents no 401, is noise of the API tester's own making. Every other judge still reads it, so a 5xx a probe
+ * provokes is reported: a judge not named here judges probes by default.
+ */
+/** The documentation-conformance judges: each compares an answer with what the document says. */
+export const DOCUMENTATION_JUDGES = [
+    "create.status-matches-document",
+    "response.contract-call",
+    "response.status-is-documented",
+    "schema.error-response-matches-document",
+    "schema.read-response-matches-document",
+    "schema.success-response-matches-document",
+];
+/** Whether the exchange was a probe: sent as one, or with a forged credential. */
+export function isProbeExchange(exchange) {
+    return exchange.probe === true || exchange.forged === true;
+}
+/** Whether `judge` grades `exchange`: anything but a probe, unless the judge is not a documentation judge. */
+export function judges(judge, exchange) {
+    const documentation = DOCUMENTATION_JUDGES;
+    return !isProbeExchange(exchange) || !documentation.includes(judge);
+}
+//# sourceMappingURL=probe-judging.js.map

package/dist/api/runtime/profile.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Cost gating: which operations a run is allowed to touch.
+ *
+ * `x-cost` and `x-destructive` are parsed onto every `OperationModel` regardless of whether a
+ * profile is active — this module is the only thing that reads them for gating. Everything else
+ * about an excluded operation reuses the run's existing degraded-mode machinery: nulling the op
+ * out of the check context and reporting a named `COVERAGE_GAP`, the same path a genuinely broken
+ * create already takes. An excluded operation must never look like a passed check.
+ */
+import type { ProfileSpec } from "../config/types/config.ts";
+import type { Scenario } from "../config/types/steps.ts";
+import type { OperationModel } from "../spec/graph/types.ts";
+export declare const BUILTIN_PROFILES: Record<string, ProfileSpec>;
+export interface ResolvedProfile {
+    name: string;
+    spec: ProfileSpec;
+}
+/**
+ * Picks the active profile by name, falling back to `"full"` — the same shape as today's
+ * behavior, so a config that never mentions a profile runs identically to before this existed.
+ */
+export declare function resolveProfile(name: string | undefined, configured: Record<string, ProfileSpec> | undefined): ResolvedProfile;
+/**
+ * Why a profile excludes this operation, or `null` when it does not.
+ *
+ * Checked in order of specificity: an explicit `exclude` entry always wins, `excludeDestructive`
+ * next, then the cost ceiling — so a reason a reader sees is always the most direct one, not
+ * whichever rule happened to be checked first.
+ */
+export declare function excludedByProfile(op: OperationModel, spec: ProfileSpec): string | null;
+/**
+ * Why a profile leaves `scenario` out, or `null` when it runs: the first step whose external has a
+ * kind the profile excludes. An external `kinds` does not name is never excluded.
+ */
+export declare function externalExcluded(scenario: Scenario, kinds: Readonly<Record<string, string>> | undefined, profile: ResolvedProfile): string | null;
+//# sourceMappingURL=profile.d.ts.map

package/dist/api/runtime/profile.js

@@ -0,0 +1,63 @@
+/**
+ * Cost gating: which operations a run is allowed to touch.
+ *
+ * `x-cost` and `x-destructive` are parsed onto every `OperationModel` regardless of whether a
+ * profile is active — this module is the only thing that reads them for gating. Everything else
+ * about an excluded operation reuses the run's existing degraded-mode machinery: nulling the op
+ * out of the check context and reporting a named `COVERAGE_GAP`, the same path a genuinely broken
+ * create already takes. An excluded operation must never look like a passed check.
+ */
+import { UsageError } from "../errors/usage-error.js";
+export const BUILTIN_PROFILES = {
+    cheap: { maxCost: "low" },
+    full: {},
+};
+const COST_RANK = { high: 2, low: 0, medium: 1 };
+/**
+ * Picks the active profile by name, falling back to `"full"` — the same shape as today's
+ * behavior, so a config that never mentions a profile runs identically to before this existed.
+ */
+export function resolveProfile(name, configured) {
+    const activeName = name ?? "full";
+    const spec = configured?.[activeName] ?? BUILTIN_PROFILES[activeName];
+    if (spec === undefined) {
+        const known = [...new Set([...Object.keys(BUILTIN_PROFILES), ...Object.keys(configured ?? {})])];
+        throw new UsageError(`testing api: profile "${activeName}" is not defined. Known: ${known.join(", ")}`);
+    }
+    return { name: activeName, spec };
+}
+/**
+ * Why a profile excludes this operation, or `null` when it does not.
+ *
+ * Checked in order of specificity: an explicit `exclude` entry always wins, `excludeDestructive`
+ * next, then the cost ceiling — so a reason a reader sees is always the most direct one, not
+ * whichever rule happened to be checked first.
+ */
+export function excludedByProfile(op, spec) {
+    if (spec.exclude?.includes(op.operationId) === true) {
+        return `excluded by name (operationId: ${op.operationId})`;
+    }
+    if (spec.excludeDestructive === true && op.destructive)
+        return "x-destructive";
+    if (spec.maxCost !== undefined && COST_RANK[op.cost] > COST_RANK[spec.maxCost]) {
+        return `x-cost: ${op.cost}`;
+    }
+    return null;
+}
+/**
+ * Why a profile leaves `scenario` out, or `null` when it runs: the first step whose external has a
+ * kind the profile excludes. An external `kinds` does not name is never excluded.
+ */
+export function externalExcluded(scenario, kinds, profile) {
+    const excluded = profile.spec.excludeExternalKinds ?? [];
+    for (const step of scenario.steps) {
+        if (!("external" in step))
+            continue;
+        const kind = kinds?.[step.external];
+        if (kind !== undefined && excluded.includes(kind)) {
+            return `external "${step.external}" is kind "${kind}", which profile "${profile.name}" excludes`;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=profile.js.map

package/dist/api/runtime/progress/columns.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The progress columns, as the TSV header names them and the glossary explains them.
+ *
+ * Logs are logfmt (key=value, one event per line) — the usual shape for
+ * machines and people. Values are never truncated: a fixed-width table
+ * forced "…" on check names and URLs, and wrapped the header in a normal
+ * editor so the columns stopped lining up.
+ *
+ * stderr and progress.log are the same format. progress.jsonl is the same
+ * events as JSON. progress.tsv is the same columns, tab-separated.
+ */
+export declare const PROGRESS_TSV_HEADER: string;
+export declare const PROGRESS_GLOSSARY: string;
+//# sourceMappingURL=columns.d.ts.map

package/dist/api/runtime/progress/columns.js

@@ -0,0 +1,49 @@
+/**
+ * The progress columns, as the TSV header names them and the glossary explains them.
+ *
+ * Logs are logfmt (key=value, one event per line) — the usual shape for
+ * machines and people. Values are never truncated: a fixed-width table
+ * forced "…" on check names and URLs, and wrapped the header in a normal
+ * editor so the columns stopped lining up.
+ *
+ * stderr and progress.log are the same format. progress.jsonl is the same
+ * events as JSON. progress.tsv is the same columns, tab-separated.
+ */
+export const PROGRESS_TSV_HEADER = /* @__PURE__ */ [
+    "ts_ms",
+    "status",
+    "done",
+    "total",
+    "phase",
+    "entity",
+    "check",
+    "msg",
+    "req",
+    "find",
+    "method",
+    "path",
+    "http",
+    "req_id",
+    "last_at",
+    "last_ms",
+    "req_b",
+    "res_b",
+    "idle_ms",
+    "elapsed_ms",
+].join("\t");
+export const PROGRESS_GLOSSARY = /* @__PURE__ */ [
+    "# logfmt — one event per line, full values, no truncation",
+    "# ts               when this line was written (ISO-8601 UTC). ts_ms is the same instant as unix ms",
+    "# status=ok|stall|in_flight|network  in_flight = on the wire; stall = idle after a completed call; network = fetch threw (offline/dns/reset/…)",
+    "# done/total       entity index / how many entities",
+    "# phase            load|auth|seed|test|scenario|contract|teardown|done (teardown only while records are removed)",
+    "# check            check id (empty when not in a check)",
+    "# msg              phase note (seeding, spec URL, teardown count). Not set to in-flight — that is status",
+    "# req_id           x-request-id / request-id / x-correlation-id / correlation-id on that call (empty if none)",
+    "# last_at          wall clock of that call (ISO-8601 UTC). While in_flight, when fetch started",
+    "# last_ms          duration of the last completed HTTP call. Empty (-) while in_flight",
+    "# req_b / res_b    reconstructed HTTP/1.1 size (start line + headers + body) of that call. res_b is empty while in_flight",
+    "# idle_ms          while in_flight: ms since this request started. otherwise ms since the last call returned",
+    "# elapsed_ms       wall clock since the API tester started",
+].join("\n");
+//# sourceMappingURL=columns.js.map

package/dist/api/runtime/progress/fields.d.ts

@@ -0,0 +1,27 @@
+/** One progress snapshot as the column values every format prints. */
+import type { ProgressSnapshot } from "./types.ts";
+/** Idle this long after a completed call reads as a stall. */
+export declare const STALL_MS = 15000;
+export interface ProgressFields {
+    status: string;
+    done: string;
+    total: string;
+    phase: string;
+    entity: string;
+    check: string;
+    msg: string;
+    req: string;
+    find: string;
+    method: string;
+    path: string;
+    http: string;
+    req_id: string;
+    last_at: string;
+    last_ms: string;
+    req_b: string;
+    res_b: string;
+    idle_ms: string;
+    elapsed_ms: string;
+}
+export declare function progressFields(snap: ProgressSnapshot, now: number): ProgressFields;
+//# sourceMappingURL=fields.d.ts.map

package/dist/api/runtime/progress/fields.js

@@ -0,0 +1,78 @@
+/** One progress snapshot as the column values every format prints. */
+/** Idle this long after a completed call reads as a stall. */
+export const STALL_MS = 15_000;
+/** Path + query, never truncated. Origin is already in the report backend field. */
+function requestPath(url) {
+    try {
+        const parsed = new URL(url);
+        return `${parsed.pathname}${parsed.search}`;
+    }
+    catch {
+        return url;
+    }
+}
+/** The columns that describe the run, whatever the last call was. */
+function runFields(snap) {
+    return {
+        check: snap.check ?? "-",
+        done: snap.entityIndex === undefined ? "-" : String(snap.entityIndex),
+        elapsed_ms: String(Math.max(0, Math.round(snap.elapsedMs))),
+        entity: snap.entity ?? "-",
+        find: String(snap.findings),
+        msg: snap.message ?? "-",
+        phase: snap.phase,
+        req: String(snap.requests),
+        total: snap.entityTotal === undefined ? "-" : String(snap.entityTotal),
+    };
+}
+/** A call still on the wire: idle counts from when it started, and it has no answer yet. */
+function inflightFields(inflight, now) {
+    const requestId = inflight.requestId;
+    return {
+        http: "-",
+        idle_ms: String(Math.max(0, now - inflight.at)),
+        last_at: new Date(inflight.at).toISOString(),
+        last_ms: "-",
+        method: inflight.method,
+        path: requestPath(inflight.url),
+        req_b: inflight.requestBytes === undefined ? "-" : String(inflight.requestBytes),
+        req_id: requestId === undefined || requestId === "" ? "-" : requestId,
+        res_b: "-",
+        status: "in_flight",
+    };
+}
+const NO_CALL = {
+    http: "-",
+    idle_ms: "-",
+    last_at: "-",
+    last_ms: "-",
+    method: "-",
+    path: "-",
+    req_b: "-",
+    req_id: "-",
+    res_b: "-",
+    status: "ok",
+};
+/** The last completed call, or dashes before the first one. */
+function lastFields(last, now) {
+    if (last === undefined)
+        return NO_CALL;
+    const stalled = now - last.at >= STALL_MS;
+    return {
+        http: String(last.status),
+        idle_ms: String(Math.max(0, now - last.at)),
+        last_at: new Date(last.at).toISOString(),
+        last_ms: String(last.durationMs),
+        method: last.method,
+        path: requestPath(last.url),
+        req_b: String(last.requestBytes),
+        req_id: last.requestId,
+        res_b: String(last.responseBytes),
+        status: last.network !== undefined ? "network" : stalled ? "stall" : "ok",
+    };
+}
+export function progressFields(snap, now) {
+    const call = snap.inflight === undefined ? lastFields(snap.last, now) : inflightFields(snap.inflight, now);
+    return { ...runFields(snap), ...call };
+}
+//# sourceMappingURL=fields.js.map

package/dist/api/runtime/progress/format.d.ts

@@ -0,0 +1,6 @@
+/** A progress snapshot as one logfmt line, one TSV row, or one JSON line. */
+import type { ProgressSnapshot } from "./types.ts";
+export declare function formatProgressLine(snap: ProgressSnapshot, now?: number): string;
+export declare function formatProgressTsv(snap: ProgressSnapshot, now?: number): string;
+export declare function formatProgressJsonl(snap: ProgressSnapshot, now?: number): string;
+//# sourceMappingURL=format.d.ts.map