@apex-actions/cli 0.67.0

package/dist/src/domain/runs.js

@@ -0,0 +1,90 @@
+// domain layer — see ../../../../docs/conventions.md §1
+// What the CLI knows about runs and jobs, and the pure decisions it makes
+// about them. The REST shapes come from control-plane/contracts/openapi.
+/** A run is worth following while anything can still change. */
+export const isLive = (status) => status !== 'completed';
+/** The exit code a completed run should give a shell: 0 only for success. */
+export const exitCodeFor = (conclusion) => (conclusion === 'success' ? 0 : 1);
+/**
+ * Whether a selector is a run **id** rather than a relative selector.
+ *
+ * The distinction is the whole of BUG-0080. `latest` and `#12` are *relative*:
+ * they mean nothing except against a list, and `#12` means nothing except
+ * within one repository. A run id is **absolute and globally unique**, so
+ * resolving it by scanning a list is not a lookup — it is a search with a
+ * horizon, and the runs worth asking about are the ones past it.
+ *
+ * The shape is the control plane's own: `runs.id` is a `uuid` column, so every
+ * run id there has ever been matches this and nothing else does. A selector
+ * that merely *looks* wrong is still handled by the list path, which is where
+ * `#12` and a typo belong.
+ */
+const RUN_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export const isRunId = (selector) => RUN_ID.test(selector.trim());
+/**
+ * Resolve which run the user meant. `latest` picks the newest; an id matches
+ * exactly; `#12` matches a run number, which is what people read off a Check
+ * Run and what they will type.
+ *
+ * Callers should ask {@link isRunId} first and address an id directly: this
+ * function can only ever see the runs it was handed.
+ */
+export const selectRun = (runs, selector) => {
+    if (runs.length === 0)
+        return undefined;
+    if (selector === '' || selector === 'latest')
+        return runs[0];
+    const byId = runs.find((r) => r.id === selector);
+    if (byId)
+        return byId;
+    const number = Number(selector.startsWith('#') ? selector.slice(1) : selector);
+    if (Number.isInteger(number))
+        return runs.find((r) => r.runNumber === number);
+    return undefined;
+};
+/**
+ * What to say when a selector found no run.
+ *
+ * A **run id** that finds nothing is a different failure from a selector that
+ * finds nothing, and one message described only the second: *"pass a run id,
+ * #number, or latest"* tells somebody who passed a perfectly good run id that
+ * their id was the problem. Before BUG-0080 it usually was not — the id was
+ * simply older than the hundred runs being searched — and now that ids are
+ * addressed directly, one reaching here really is absent or unreadable, which
+ * is worth saying rather than hinting at.
+ */
+export const unknownRunMessage = (selector) => isRunId(selector)
+    ? `no run with id ${selector} — it does not exist, or belongs to a repository you cannot read`
+    : `no run matches ${selector} — pass a run id, #number, or "latest"`;
+/** Match a job by id, exact name, or unambiguous prefix — nothing guessy. */
+export const selectJobs = (jobs, selector) => {
+    if (selector === undefined || selector === '')
+        return [...jobs];
+    const exact = jobs.filter((j) => j.id === selector || j.name === selector);
+    if (exact.length > 0)
+        return exact;
+    return jobs.filter((j) => j.name.startsWith(selector));
+};
+/** `owner/repo` from a slug, or undefined when it is not one. */
+export const parseRepository = (slug) => {
+    const match = /^([^/\s]+)\/([^/\s]+)$/.exec(slug.trim());
+    return match && match[1] !== undefined && match[2] !== undefined ? { owner: match[1], repo: match[2] } : undefined;
+};
+/**
+ * `--input name=value`, repeatable. Values stay strings here: the engine types
+ * them from the workflow's own declaration, and guessing in the CLI would
+ * mean two places deciding what `false` is.
+ */
+export const parseInputs = (pairs) => {
+    const inputs = {};
+    const invalid = [];
+    for (const pair of pairs) {
+        const at = pair.indexOf('=');
+        if (at <= 0) {
+            invalid.push(pair);
+            continue;
+        }
+        inputs[pair.slice(0, at)] = pair.slice(at + 1);
+    }
+    return { inputs, invalid };
+};

package/dist/src/domain/secrets.js

@@ -0,0 +1,39 @@
+// domain layer — see ../../../../docs/conventions.md §1
+export const targetLabel = (target) => (target.kind === 'org' ? 'the organisation' : `${target.owner}/${target.repo}`);
+/**
+ * GitHub's naming rule, which the control plane enforces too: letters, digits
+ * and underscores, not starting with a digit, and `GITHUB_` is reserved.
+ * Checked here as well so a typo costs no round trip and no half-applied loop
+ * over repositories.
+ */
+export const nameProblem = (name) => {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        return `invalid name ${JSON.stringify(name)}: use letters, digits and underscores, not starting with a digit`;
+    }
+    if (name.toUpperCase().startsWith('GITHUB_'))
+        return `invalid name ${JSON.stringify(name)}: the GITHUB_ prefix is reserved`;
+    return undefined;
+};
+/**
+ * Exactly one trailing newline off, and nothing else.
+ *
+ * `echo value | apex secret set` and a file an editor saved both end in one,
+ * and nobody means it to be part of the secret. A second newline, or trailing
+ * spaces, might be meant, so they stay.
+ */
+export const trimOneNewline = (value) => {
+    if (value.endsWith('\r\n'))
+        return value.slice(0, -2);
+    if (value.endsWith('\n'))
+        return value.slice(0, -1);
+    return value;
+};
+/**
+ * The command that sets one name, for `migrate scan`'s checklist. A secret's
+ * never carries a value — it is read from stdin; a variable's shows where the
+ * value goes.
+ */
+export const setterCommand = (kind, name, repos) => {
+    const where = repos.length === 0 ? '--repo owner/repo' : repos.map((r) => `--repo ${r}`).join(' ');
+    return kind === 'secret' ? `apex secret set ${name} ${where}` : `apex variable set ${name} --value … ${where}`;
+};

package/dist/src/domain/spend.js

@@ -0,0 +1,50 @@
+// domain layer — see ../../../../docs/conventions.md §1
+// The REST shapes for a spend report, mirroring control-plane/contracts/openapi.yaml,
+// plus the pure decisions the CLI makes about presenting money.
+/**
+ * Money, at a precision that does not pretend.
+ *
+ * A fleet's monthly bill and one job's share of an instance differ by six
+ * orders of magnitude, so a single format is wrong for one of them. Sub-cent
+ * amounts keep enough digits to be distinguishable; everything above a dollar
+ * drops to cents, because nobody reconciles a budget in millionths.
+ */
+export const formatMicros = (micros) => {
+    if (!Number.isFinite(micros))
+        return '—';
+    const sign = micros < 0 ? '-' : '';
+    const abs = Math.abs(micros);
+    if (abs === 0)
+        return '$0.00';
+    if (abs < 10_000)
+        return `${sign}$${(abs / 1_000_000).toFixed(6).replace(/0+$/, '').replace(/\.$/, '.0')}`;
+    if (abs < 1_000_000)
+        return `${sign}$${(abs / 1_000_000).toFixed(4)}`;
+    return `${sign}$${(abs / 1_000_000).toFixed(2)}`;
+};
+/** `6h 12m`, `12m 30s`, `45s` — runner time, which people compare against their patience. */
+export const formatSeconds = (seconds) => {
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return '—';
+    const s = Math.round(seconds);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m ${s % 60}s`;
+    return `${Math.floor(m / 60)}h ${m % 60}m`;
+};
+/**
+ * The saving as a phrase, or an honest refusal.
+ *
+ * Undefined percent means nothing could be priced — which is not "saved
+ * nothing", and must not be printed as 0%.
+ */
+export const savingPhrase = (savedMicros, percent) => {
+    if (percent === undefined)
+        return 'nothing could be priced, so there is nothing to compare';
+    const direction = savedMicros >= 0 ? 'less than GitHub' : 'MORE than GitHub';
+    return `${formatMicros(Math.abs(savedMicros))} ${direction} (${percent >= 0 ? '' : '-'}${Math.abs(percent).toFixed(0)}%)`;
+};
+/** Rows worth printing: everything, but capped so a big org's report stays readable. */
+export const topWorkflows = (workflows, limit) => workflows.slice(0, limit);

package/dist/src/domain/supplychain.js

@@ -0,0 +1,48 @@
+// domain layer — see ../../../../docs/conventions.md §1
+// The REST shapes for the action supply chain, mirroring
+// control-plane/contracts/openapi.yaml, plus the pure decisions the CLI makes
+// about presenting them. No judgement lives here: whether a reference is
+// allowed is the control plane's answer, and a second implementation would be
+// a second answer.
+/**
+ * How a pinning classification reads in a list.
+ *
+ * `movable` is spelled out rather than abbreviated because it is the one that
+ * surprises people: `v4.1.1` looks like a version and is a pointer its owner
+ * can move.
+ */
+const PINNING_LABELS = {
+    sha: 'pinned',
+    digest: 'pinned (digest)',
+    movable: 'movable',
+    local: 'local',
+    unparsable: 'unreadable',
+};
+export const pinningLabel = (p) => PINNING_LABELS[p] ?? p;
+/** Every reference whose pinning could change under the repository's feet. */
+export const movable = (refs) => refs.filter((r) => r.pinning === 'movable');
+/**
+ * The one-line summary of an inventory.
+ *
+ * Counts what is movable rather than what is "unsafe": we cannot tell whether
+ * an action is safe, only whether it can change.
+ */
+export const inventorySummary = (inv) => {
+    const total = inv.references.length;
+    const loose = movable(inv.references).length;
+    const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+    return `${plural(total, 'reference', 'references')}, ${plural(loose, 'movable', 'movable')}`;
+};
+/** `off` reads as a state, not an absence — a policy nobody set is still an answer. */
+export const policyLine = (p) => {
+    if (p.mode === 'off')
+        return 'off — no reference is checked';
+    const parts = [p.mode];
+    parts.push(p.allow.length === 0 ? 'allow: everything not denied' : `allow: ${p.allow.join(', ')}`);
+    if (p.deny.length > 0)
+        parts.push(`deny: ${p.deny.join(', ')}`);
+    parts.push(p.requirePinned ? 'commit SHAs required' : 'tags permitted');
+    return parts.join(' · ');
+};
+/** Parse a comma-or-repeat separated pattern list from the command line. */
+export const patternList = (values) => (values ?? []).flatMap((v) => v.split(',')).map((v) => v.trim()).filter((v) => v !== '');

package/dist/src/domain/terms.js

@@ -0,0 +1,16 @@
+// domain layer — see ../../../../docs/conventions.md §1
+/**
+ * Why one account is outstanding, in the words an operator writing the notice
+ * needs — *never accepted anything* and *accepted words that have since
+ * changed* are different e-mails.
+ */
+export const pendingReason = (row) => row.acceptedVersion === undefined ? 'has never accepted' : `accepted ${row.acceptedVersion}`;
+export const pendingLine = (row) => `${row.owner} (installation ${row.installationId}) — ${pendingReason(row)}`;
+/**
+ * The one sentence worth printing when the list is empty, because an empty
+ * list is the state this is trying to reach and "nothing to show" reads like a
+ * failed query.
+ */
+export const standingSummary = (standing) => standing.pending.length === 0
+    ? `every account has accepted the terms in force (${standing.version})`
+    : `${standing.pending.length} account${standing.pending.length === 1 ? ' owes' : 's owe'} an acceptance of ${standing.version}`;

package/dist/src/domain/validation.js

@@ -0,0 +1,4 @@
+// domain layer — see ../../../../docs/conventions.md §1
+// Workflow validation results as reported by the engine (engine ADR-0004).
+export const hasErrors = (report) => report.files.some((f) => f.diagnostics.some((d) => d.severity === 'error'));
+export const diagnosticCount = (report) => report.files.reduce((n, f) => n + f.diagnostics.length, 0);