@apex-actions/cli 0.67.0

package/dist/src/domain/credentials.js

@@ -0,0 +1,82 @@
+// domain layer — see ../../../../docs/conventions.md §1
+/**
+ * A customer's terminal credential, and the browser login that mints one
+ * (control-plane ADR-0064).
+ *
+ * Pure decisions only: where the consent page is, whether a loopback callback
+ * is the one this login asked for, whether a file mode is private enough to
+ * hold a token. The randomness, the socket and the file live in
+ * infrastructure.
+ */
+/** Where the CLI goes when nobody says otherwise: the hosted control plane. */
+export const DEFAULT_API_URL = 'https://app.apexactions.com';
+/** The dashboard page that lists, mints and revokes terminal tokens. */
+export const TOKENS_PAGE = '/settings/tokens';
+export const describeSource = (source) => {
+    switch (source) {
+        case 'env':
+            return 'APEX_TOKEN in the environment';
+        case 'login':
+            return 'the token `apex login` saved';
+        case 'operator':
+            return 'APEX_ADMIN_TOKEN, the operator token';
+    }
+};
+/** A URL without its trailing slash, so two spellings of one origin compare equal. */
+export const normaliseUrl = (url) => url.replace(/\/+$/, '');
+/**
+ * The web app's base URL. The consent page lives there, not in the API; on the
+ * hosted service one origin serves both, so the API's is the right default.
+ */
+export const webBaseFor = (apiUrl, webUrl) => normaliseUrl(webUrl !== undefined && webUrl !== '' ? webUrl : apiUrl);
+/**
+ * `ssh`'s rule: a file holding a credential that anybody but its owner can
+ * read is refused, not used. The group and other bits must all be clear.
+ */
+export const isPrivateMode = (mode) => (mode & 0o077) === 0;
+/** Whether a saved credential has run out, so it is not offered to the server. */
+export const hasExpired = (credential, now) => {
+    const at = Date.parse(credential.expiresAt);
+    return Number.isFinite(at) && at <= now.getTime();
+};
+/** A parsed credentials file, or undefined when it is not one — never a partial. */
+export const parseSavedCredential = (raw) => {
+    if (raw === null || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    const fields = ['token', 'login', 'apiUrl', 'expiresAt'];
+    for (const f of fields)
+        if (typeof r[f] !== 'string' || r[f] === '')
+            return undefined;
+    return { token: r['token'], login: r['login'], apiUrl: r['apiUrl'], expiresAt: r['expiresAt'] };
+};
+/** The consent page `apex login` opens (RFC 8252 loopback, RFC 7636 S256). */
+export const authorizeUrl = (webBase, request) => {
+    const query = new URLSearchParams({
+        port: String(request.port),
+        state: request.state,
+        code_challenge: request.codeChallenge,
+        name: request.name,
+    });
+    return `${normaliseUrl(webBase)}/cli/authorize?${query.toString()}`;
+};
+/**
+ * Judge what arrived at the loopback callback.
+ *
+ * The `state` is checked before anything else, the denial included: a request
+ * this login did not cause — another page on this machine guessing the port —
+ * must not be able to end it with a message of its choosing either.
+ */
+export const judgeCallback = (params, expectedState) => {
+    if (params.get('state') !== expectedState)
+        return { kind: 'state-mismatch' };
+    const error = params.get('error');
+    if (error !== null && error !== '') {
+        const description = params.get('error_description');
+        return { kind: 'denied', detail: description !== null && description !== '' ? `${error}: ${description}` : error };
+    }
+    const code = params.get('code');
+    if (code === null || code === '')
+        return { kind: 'malformed' };
+    return { kind: 'code', code };
+};

package/dist/src/domain/fleet-history.js

@@ -0,0 +1,136 @@
+// domain layer — see ../../../../docs/conventions.md §1
+//
+// How big was the fleet, and when was it nothing?
+//
+// The control plane serves runner *lifetimes* — `registeredAt` to `lastSeenAt`,
+// departed runners included (control-plane ADR-0041). Everything below is the
+// pure arithmetic that turns a pile of intervals into the two answers a capacity
+// question actually wants: the peak, and the time at zero. It is here rather
+// than in the control plane so that it can be tested without a server, and so
+// the endpoint stays a statement of fact rather than of judgement.
+//
+// **What this can and cannot say.** A runner touches its row on every long-poll,
+// at most `POLL_WINDOW_SECONDS` apart, so each interval's end is right to within
+// that. It is therefore honest about an idle night — the question is whether the
+// count was zero for hours — and dishonest about anything measured in seconds.
+/** The control plane's cap on the acquire long-poll: the resolution of an end. */
+export const POLL_WINDOW_SECONDS = 30;
+/**
+ * The end of a runner's life.
+ *
+ * A runner that registered and never polled ends where it began — the same
+ * COALESCE the control plane reaps by. A runner still alive has no end inside
+ * the window, so it is clipped to `until` rather than treated as departed:
+ * `lastSeenAt` on a live runner is "a moment ago", not "gone since".
+ */
+const endOf = (r, until) => {
+    const last = r.lastSeenAt === undefined ? Date.parse(r.registeredAt) : Date.parse(r.lastSeenAt);
+    return r.deleted ? last : Math.max(last, until);
+};
+/**
+ * Reconstruct the fleet's size across the window.
+ *
+ * **Only pooled runners count.** A runner without a pool is not fleet capacity —
+ * on this deployment it is the dogfooding runner on the control-plane host, which
+ * never goes away and would make "the fleet was at zero" impossible to ever
+ * observe. They are reported as excluded rather than dropped in silence, because
+ * a count that quietly ignores machines is the kind of number that gets believed.
+ */
+export const reconstructFleet = (runners, window) => {
+    const since = Date.parse(window.since);
+    const until = Date.parse(window.until);
+    const counted = [];
+    const excluded = [];
+    for (const r of runners) {
+        if (r.pool === undefined || r.pool === '') {
+            excluded.push({ name: r.name, reason: 'no pool — not fleet capacity' });
+            continue;
+        }
+        counted.push(r);
+    }
+    const edges = [];
+    for (const r of counted) {
+        const from = Math.max(Date.parse(r.registeredAt), since);
+        const to = Math.min(endOf(r, until), until);
+        if (to <= from)
+            continue; // lived entirely outside the window after clipping
+        edges.push({ at: from, delta: +1, pool: r.pool });
+        edges.push({ at: to, delta: -1, pool: r.pool });
+    }
+    // Departures before arrivals at the same instant: an instance replaced at a
+    // tick boundary must not be counted as two.
+    edges.sort((a, b) => a.at - b.at || a.delta - b.delta);
+    let count = 0;
+    let peak = { count: 0, at: window.since };
+    const perPool = new Map();
+    const poolPeak = new Map();
+    const zeroWindows = [];
+    let zeroFrom = since;
+    for (const edge of edges) {
+        if (count === 0 && edge.delta > 0 && zeroFrom !== undefined && edge.at > zeroFrom) {
+            zeroWindows.push({
+                from: new Date(zeroFrom).toISOString(),
+                to: new Date(edge.at).toISOString(),
+                seconds: Math.round((edge.at - zeroFrom) / 1000),
+            });
+            zeroFrom = undefined;
+        }
+        count += edge.delta;
+        if (count > peak.count)
+            peak = { count, at: new Date(edge.at).toISOString() };
+        if (edge.pool !== undefined) {
+            const next = (perPool.get(edge.pool) ?? 0) + edge.delta;
+            perPool.set(edge.pool, next);
+            const best = poolPeak.get(edge.pool);
+            if (best === undefined || next > best.count)
+                poolPeak.set(edge.pool, { count: next, at: new Date(edge.at).toISOString() });
+        }
+        if (count === 0)
+            zeroFrom = edge.at;
+    }
+    if (zeroFrom !== undefined && until > zeroFrom) {
+        zeroWindows.push({
+            from: new Date(zeroFrom).toISOString(),
+            to: new Date(until).toISOString(),
+            seconds: Math.round((until - zeroFrom) / 1000),
+        });
+    }
+    const secondsAtZero = zeroWindows.reduce((sum, w) => sum + w.seconds, 0);
+    const longestZero = [...zeroWindows].sort((a, b) => b.seconds - a.seconds)[0];
+    return {
+        since: window.since,
+        until: window.until,
+        counted: counted.length,
+        excluded,
+        peak,
+        peakByPool: [...poolPeak.entries()]
+            .map(([pool, p]) => ({ pool, count: p.count, at: p.at }))
+            .sort((a, b) => b.count - a.count || a.pool.localeCompare(b.pool)),
+        zeroWindows,
+        secondsAtZero,
+        longestZero,
+        emptyThroughout: peak.count === 0,
+        resolutionSeconds: POLL_WINDOW_SECONDS,
+    };
+};
+/** `24h`, `90m`, `2d`, `3600` (seconds) — what an operator types for a window. */
+export const parseDuration = (input) => {
+    const m = /^(\d+(?:\.\d+)?)([smhd]?)$/.exec(input.trim());
+    if (!m)
+        return undefined;
+    const value = Number(m[1]);
+    if (!Number.isFinite(value) || value <= 0)
+        return undefined;
+    const unit = m[2] === '' ? 's' : m[2];
+    const scale = { s: 1, m: 60, h: 3600, d: 86_400 }[unit];
+    return Math.round(value * scale);
+};
+export const humanSeconds = (seconds) => {
+    if (seconds < 90)
+        return `${seconds}s`;
+    if (seconds < 5400)
+        return `${Math.round(seconds / 60)}m`;
+    if (seconds < 172_800)
+        return `${(seconds / 3600).toFixed(1)}h`;
+    return `${(seconds / 86_400).toFixed(1)}d`;
+};

package/dist/src/domain/index.js

@@ -0,0 +1,2 @@
+export {};
+// domain layer — see ../../../../docs/conventions.md §1

package/dist/src/domain/insight.js

@@ -0,0 +1,42 @@
+// domain layer — see ../../../../docs/conventions.md §1
+// The REST shapes for "what got slower" and "what is flaky", mirroring
+// control-plane/contracts/openapi.yaml, plus the pure decisions the CLI makes
+// about presenting them.
+/**
+ * A duration a person can compare at a glance.
+ *
+ * Sub-second work is rounded to milliseconds and everything above a minute
+ * loses its milliseconds entirely: nobody reading "which step got slower"
+ * needs three decimal places on four minutes, and the extra digits make two
+ * numbers harder to compare rather than easier.
+ */
+export const humanDuration = (ms) => {
+    if (!Number.isFinite(ms) || ms < 0)
+        return '—';
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const seconds = ms / 1000;
+    if (seconds < 60)
+        return `${seconds.toFixed(1)}s`;
+    const whole = Math.round(seconds);
+    const minutes = Math.floor(whole / 60);
+    if (minutes < 60)
+        return `${minutes}m ${whole % 60}s`;
+    return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+};
+/** `+2.4× (was 10.0s)`, or nothing when there is no baseline to compare to. */
+export const trendNote = (t) => {
+    if (t.baselineMs === undefined || t.ratio === undefined)
+        return undefined;
+    return `${t.ratio.toFixed(1)}× (was ${humanDuration(t.baselineMs)})`;
+};
+/**
+ * A run's steps, slowest first, for a listing that has room for only a few.
+ *
+ * Sorted by duration rather than by document order because the question this
+ * answers is "where did the time go" — and a step that took four minutes is
+ * the answer whether it ran first or last.
+ */
+export const slowestFirst = (steps, limit) => [...steps].sort((a, b) => b.durationMs - a.durationMs).slice(0, limit);
+/** A one-word marker per outcome, so a scan down the column reads. */
+export const testMarker = (outcome) => outcome === 'passed' ? '✓' : outcome === 'skipped' ? '−' : '✗';

package/dist/src/domain/logsearch.js

@@ -0,0 +1,40 @@
+// domain layer — see ../../../../docs/conventions.md §1
+// The REST shapes for a log search and a structured log view, mirroring
+// control-plane/contracts/openapi.yaml, plus the pure decisions the CLI makes
+// about presenting them.
+/**
+ * `ci.yml #12 · build` — how a result names the job it found.
+ *
+ * The workflow's file name rather than its display name: the reader's next act
+ * is to open that file, and two workflows may share a `name:`.
+ */
+export const resultTitle = (result) => {
+    const file = result.workflowPath.split('/').pop() ?? result.workflowPath;
+    const attempt = result.attempt > 1 ? ` (attempt ${result.attempt})` : '';
+    return `${file} #${result.runNumber}${attempt} · ${result.jobName}`;
+};
+/** `main · a1b2c3d` — the branch as people write it, and the commit. */
+export const resultRef = (result) => `${result.ref.replace(/^refs\/heads\//, '')} · ${result.sha.slice(0, 7)}`;
+/** Only what the tool itself stated. A missing count is missing, never zero. */
+export const totalsPhrase = (view) => {
+    const parts = [];
+    if (view.totals.failed !== undefined)
+        parts.push(`${view.totals.failed} failed`);
+    if (view.totals.passed !== undefined)
+        parts.push(`${view.totals.passed} passed`);
+    if (view.totals.skipped !== undefined && view.totals.skipped > 0)
+        parts.push(`${view.totals.skipped} skipped`);
+    if (view.totals.total !== undefined)
+        parts.push(`${view.totals.total} total`);
+    return parts.length === 0 ? 'no counts reported' : parts.join(', ');
+};
+/**
+ * What the reader should trust, in a sentence.
+ *
+ * `report` is the only case that needs saying: the numbers on screen came from
+ * reading the runner's prose, and a machine-readable statement of the same run
+ * exists and outranks them.
+ */
+export const authorityNote = (view) => view.authority === 'report'
+    ? 'this job also left a test report, which is the runner’s own statement — `apex tests` reads that; the counts here are read from the console output and the line numbers are what they add'
+    : undefined;

package/dist/src/domain/migration.js

@@ -0,0 +1,122 @@
+// domain layer — see ../../../../docs/conventions.md §1
+// The migration report as the engine produces it (engine ADR-0013,
+// engine/docs/compat-format.md), plus the re-entry checklist built on top.
+//
+// Nothing here decides what is supported. Every verdict is a row of the
+// engine's conformance corpus, and a second opinion in this file would be a
+// second answer to a question that must have one — it would agree on the day
+// it was written and drift, silently, the first time a fixture changed.
+/**
+ * Secrets nobody configures, because the platform mints them per job.
+ *
+ * `secrets.GITHUB_TOKEN` is in every second workflow on GitHub and is in no
+ * organization's secret list, so a checklist that did not know this would open
+ * every real scan by telling somebody to go and find a secret that does not
+ * exist — which is how a list stops being read. Found by running the scan
+ * against a real organization; every path had been tested against a fake.
+ */
+export const AUTOMATIC_SECRETS = ['GITHUB_TOKEN'];
+const dedupe = (values) => [...new Set(values)].sort();
+/**
+ * Build the re-entry checklist: what must be set in Apex before a first run,
+ * what the workflows read that GitHub cannot account for, and what can be left
+ * behind.
+ *
+ * `configured` may be empty because there was nothing, or because nobody could
+ * read it. Those are different states and the second one is recorded, because
+ * an empty checklist that looks complete is exactly the failure this list
+ * exists to prevent.
+ */
+export const buildChecklist = (referenced, configured) => {
+    const entries = [];
+    const byKind = (kind, names) => {
+        const configuredOfKind = (configured ?? []).filter((c) => c.kind === kind);
+        const referencedNames = dedupe(names);
+        for (const name of referencedNames) {
+            const matches = configuredOfKind.filter((c) => c.name === name);
+            const action = kind === 'secret' && AUTOMATIC_SECRETS.includes(name)
+                ? 'automatic'
+                : configured === undefined || matches.length > 0
+                    ? 're-enter'
+                    : 'unaccounted';
+            entries.push({
+                name,
+                kind,
+                action,
+                ...(matches[0]?.scope === undefined ? {} : { scope: matches[0].scope }),
+                ...(matches.some((m) => m.repo !== undefined)
+                    ? { repos: dedupe(matches.flatMap((m) => (m.repo === undefined ? [] : [m.repo]))) }
+                    : {}),
+            });
+        }
+        for (const name of dedupe(configuredOfKind.map((c) => c.name))) {
+            if (referencedNames.includes(name))
+                continue;
+            const matches = configuredOfKind.filter((c) => c.name === name);
+            entries.push({
+                name,
+                kind,
+                action: 'not-needed',
+                ...(matches[0]?.scope === undefined ? {} : { scope: matches[0].scope }),
+                ...(matches.some((m) => m.repo !== undefined)
+                    ? { repos: dedupe(matches.flatMap((m) => (m.repo === undefined ? [] : [m.repo]))) }
+                    : {}),
+            });
+        }
+    };
+    byKind('secret', referenced.secrets ?? []);
+    byKind('variable', referenced.vars ?? []);
+    return { entries, configuredNamesRead: configured !== undefined };
+};
+/**
+ * Where this organization stands.
+ *
+ * `incomplete` wins over everything: a file we could not read is not a file
+ * that runs, and a report that called an organization ready while three of its
+ * workflows failed to parse would be worse than no report.
+ */
+export const migrationVerdict = (report) => {
+    if (report.summary.unreadable > 0)
+        return 'incomplete';
+    if (report.summary.blockers > 0)
+        return 'blocked';
+    if (report.summary.partial > 0 || report.summary.unknown > 0 || report.caveats.length > 0)
+        return 'ready-with-caveats';
+    return 'ready';
+};
+export const verdictHeadline = (verdict) => {
+    switch (verdict) {
+        case 'ready':
+            return 'Every feature these workflows use runs on Apex Actions, and a fixture proves each one.';
+        case 'ready-with-caveats':
+            return 'These workflows run, with limits worth reading before you move them.';
+        case 'blocked':
+            return 'Something these workflows use does not run on Apex Actions.';
+        case 'incomplete':
+            return 'Some workflows could not be read, so this report does not cover them.';
+    }
+};
+/** `n thing` / `n things`, because a report that says "1 files" is not read carefully. */
+export const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+/**
+ * How a verdict's proof reads in the report.
+ *
+ * A verdict with no fixture never says "proved by" anything. "Supported" and
+ * "proved supported" are different sentences, and the whole point of the
+ * corpus is that only the second one is the product's claim.
+ */
+export const proofLine = (verdict) => {
+    if (verdict.status === 'unknown')
+        return 'no row of the compatibility matrix claims this';
+    if (verdict.proven && verdict.fixtures !== undefined && verdict.fixtures.length > 0) {
+        return `proved by ${verdict.fixtures.join(', ')}`;
+    }
+    return verdict.status === 'supported'
+        ? 'claimed, with no conformance fixture behind the claim'
+        : 'recorded in the matrix; no fixture demonstrates the limit';
+};
+/** Where a use is, as a reader would go and look at it. */
+export const useLocation = (use) => {
+    const at = use.path === undefined ? use.where : `${use.path}${use.line === undefined ? '' : `:${use.line}`}`;
+    return use.detail === undefined || use.detail === '' ? at : `${at} — ${use.detail}`;
+};

package/dist/src/domain/notify.js

@@ -0,0 +1,64 @@
+// domain layer — see ../../../../docs/conventions.md §1
+// The REST shapes for notification routing, mirroring
+// control-plane/contracts/openapi.yaml, plus the pure presentation decisions
+// the CLI makes about them.
+//
+// There is no destination URL in any of these types, and that is not an
+// oversight: the control plane never returns one (control-plane ADR-0029), so
+// a field for it here would be a field that is always empty and would invite
+// somebody to try to fill it.
+export const TRIGGERS = ['broke', 'recovered', 'failed', 'succeeded'];
+export const DESTINATION_KINDS = ['slack', 'teams', 'webhook'];
+/** `slack · hooks.slack.com · #a41f9c0d1e2f` — how a destination is recognised without being readable. */
+export const destinationLine = (rule) => `${rule.kind} ${rule.urlOrigin.replace(/^https:\/\//, '')} #${rule.urlFingerprint}`;
+/** Empty filters mean everything, and saying so beats printing a blank. */
+export const filterLine = (patterns) => (patterns.length === 0 ? '(all)' : patterns.join(', '));
+/** What a comma-or-repeated option means. Empty entries are dropped, not preserved as blanks. */
+export const listOption = (raw) => (raw ?? []).flatMap((v) => v.split(',')).map((v) => v.trim()).filter((v) => v !== '');
+export const invalidTriggers = (values) => values.filter((v) => !TRIGGERS.includes(v));
+/**
+ * One line summarising the last attempt.
+ *
+ * A rule that has never been used says so rather than reading as healthy: an
+ * empty status is the state a rule is in before anybody has proved it, and
+ * that is exactly what somebody debugging a silent channel needs to see.
+ */
+export const lastAttemptLine = (rule) => {
+    if (rule.lastStatus === undefined)
+        return 'never used — try `apex notify test`';
+    const when = rule.lastAttemptAt === undefined ? '' : ` ${rule.lastAttemptAt}`;
+    const detail = rule.lastDetail === undefined || rule.lastDetail === '' ? '' : ` · ${rule.lastDetail}`;
+    return `${rule.lastStatus}${when}${detail}`;
+};
+/**
+ * How one attempt went, in the words somebody acts on.
+ *
+ * Three outcomes, not two. A refusal is ours and a rejection is theirs, and
+ * that distinction was already drawn — but a send that never got an answer at
+ * all is neither, and calling it a rejection points the reader at the
+ * destination when the fault is on this side of the socket. It read as Slack
+ * turning us away while the real cause was a `TypeError` in our own resolver
+ * (control-plane ADR-0036), which is a day of somebody's time in the wrong
+ * logs.
+ */
+export const sendOutcomeLine = (outcome) => {
+    if (outcome.refused === true)
+        return 'refused before connecting';
+    if (outcome.status === undefined)
+        return 'never reached the destination';
+    return `rejected by the destination (HTTP ${String(outcome.status)})`;
+};
+/**
+ * What a rule will actually do, in one sentence.
+ *
+ * Written out because the default subscription is the thing people misread:
+ * "broke, recovered" looks like it might mean *every* failure, and it does not
+ * (control-plane ADR-0028).
+ */
+export const subscriptionLine = (rule) => {
+    const transitions = rule.on.filter((t) => t === 'broke' || t === 'recovered');
+    const everyTime = rule.on.filter((t) => t === 'failed' || t === 'succeeded');
+    if (everyTime.length > 0)
+        return `${rule.on.join(', ')} — ${everyTime.join(' and ')} fire on every run of that kind`;
+    return `${transitions.join(', ')} — only when the outcome changes`;
+};

package/dist/src/domain/outcomediff.js

@@ -0,0 +1,40 @@
+// domain layer — see ../../../../docs/conventions.md §1
+//
+// How the coexistence outcome diff reads to a person. The comparison itself is
+// the control plane's (ADR-0047); this is the sentence it deserves.
+/** One line per workflow, saying what happened and — when it matters — why not. */
+export const comparisonLine = (c) => {
+    const both = `${c.ours ?? '—'} / ${c.theirs ?? '—'}`;
+    switch (c.verdict) {
+        case 'agree':
+            return `both ${c.ours ?? '—'}`;
+        case 'differ':
+            return `apex ${c.ours ?? '—'}, github ${c.theirs ?? '—'}`;
+        case 'not-run-here':
+            return 'not run here — opt it in to compare it';
+        case 'not-run-there':
+            return 'GitHub Actions has no run for this commit';
+        case 'in-flight':
+            return `still running (${both})`;
+        case 'incomparable-secrets':
+            return `not comparable: this workflow reads ${c.missingSecrets.join(', ')}, which we do not hold`;
+    }
+};
+/**
+ * The headline, and the only honest denominator.
+ *
+ * `comparable` is `agree + differ`. A repository whose workflows all need
+ * secrets we lack has **nothing** to report, and saying "100%" of an empty set
+ * is the failure this whole feature is built to avoid — so that case gets a
+ * sentence rather than a number.
+ */
+export const diffHeadline = (s) => {
+    if (s.comparable === 0) {
+        return s.incomparable === 0
+            ? 'nothing ran on either platform for this commit'
+            : `nothing could be compared for this commit (${s.incomparable} not comparable)`;
+    }
+    const pct = Math.round((s.agree / s.comparable) * 100);
+    const tail = s.incomparable === 0 ? '' : `, ${s.incomparable} not comparable`;
+    return `${s.agree} of ${s.comparable} comparable workflows agree (${pct}%)${tail}`;
+};

package/dist/src/domain/provenance.js

@@ -0,0 +1,63 @@
+// domain layer — see ../../../../docs/conventions.md §1
+// The REST shapes for "why did this run" and "how do I run it here", mirroring
+// control-plane/contracts/openapi.yaml, plus the pure decisions the CLI makes
+// about presenting them.
+/**
+ * The retry note for one job, or `undefined` when it ran first time.
+ *
+ * Shown even on a job that succeeded, because that is the interesting case: a
+ * Spot reclaim that cost a delay rather than a run is the thing GA gate G3 asks
+ * somebody to witness, and by then the job's own `reason` is about its
+ * conclusion.
+ */
+export const retryNote = (job) => {
+    const attempt = job.attempt ?? 1;
+    if (attempt < 2 && job.requeueReason === undefined)
+        return undefined;
+    const why = job.requeueReason === 'spot-interruption'
+        ? 'instance reclaimed by Spot'
+        : job.requeueReason === 'lease-expired'
+            ? 'runner stopped reporting'
+            : job.requeueReason === 'shutdown'
+                ? 'runner shutting down'
+                : job.requeueReason;
+    return why === undefined ? `attempt ${attempt}` : `attempt ${attempt} — ${why}`;
+};
+/**
+ * A verdict worth printing under "and here is what else this delivery
+ * decided". `planned` is the run the reader is already looking at, and
+ * `already-planned` is bookkeeping about a reclaimed claim — neither answers
+ * the question that brought them here.
+ */
+export const worthShowing = (t) => t.outcome !== 'planned' && t.outcome !== 'already-planned';
+/**
+ * One line describing a verdict, ending in the filter list when there is one.
+ *
+ * The filter is printed as the workflow wrote it, because the next thing the
+ * reader does is open that file and change that line — quoting our paraphrase
+ * of it would send them looking for words that are not there.
+ */
+export const verdictLine = (t) => {
+    const head = t.reason ?? t.summary ?? t.outcome;
+    const filter = t.filter ?? [];
+    return filter.length === 0 ? head : `${head} — the trigger allows ${filter.join(', ')}`;
+};
+/** A one-word status marker for a job, chosen so a scan down the column reads. */
+export const jobMarker = (job) => {
+    if (job.status !== 'completed')
+        return job.status === 'in_progress' ? '›' : '·';
+    switch (job.conclusion) {
+        case 'success':
+            return '✓';
+        case 'skipped':
+            return '−';
+        case 'cancelled':
+            return '⨯';
+        default:
+            return '✗';
+    }
+};
+/** Shell-quote one argument of a generated command, so it can be pasted as-is. */
+export const shellQuote = (arg) => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'\\''`)}'`);
+/** The generated invocation as one pasteable line. */
+export const commandLine = (command) => command.map(shellQuote).join(' ');