@apex-actions/cli 0.67.0

package/dist/cli/secret/main.js

@@ -0,0 +1,102 @@
+import { Command, Option } from 'commander';
+import chalk from 'chalk';
+import { batchExitCode, listSecrets, setEverywhere } from '../../src/application/manage-secrets.js';
+import { ValueInputError, promptHidden, readToEnd, readValueFile } from '../../src/infrastructure/secret-input.js';
+import { api, collect, deleteAction, printResults, targetsFrom, usage, validName } from './shared.js';
+/**
+ * The refusal, in full, because the person who typed `--value` deserves the
+ * reason and the alternative in one breath (BUG-0157).
+ */
+const ARGV_REFUSAL = 'a secret is never taken from the command line: argv is visible to every user in `ps` and is saved in shell history. ' +
+    'Pipe it (`printf %s "$VALUE" | apex secret set NAME --repo owner/repo`), pass --from-file, or run it on a terminal to be prompted';
+/**
+ * The value, from anywhere but argv: a file, a pipe read to EOF, or a no-echo
+ * prompt when stdin is a terminal. Never echoed, never in an error.
+ */
+const readSecretValue = async (name, fromFile) => {
+    try {
+        if (fromFile !== undefined)
+            return await readValueFile(fromFile);
+        if (process.stdin.isTTY !== true)
+            return await readToEnd(process.stdin);
+        return await promptHidden(name);
+    }
+    catch (err) {
+        usage(err instanceof ValueInputError ? err.message : `could not read the value: ${err instanceof Error ? err.message : String(err)}`);
+        return undefined;
+    }
+};
+const setCommand = new Command('set')
+    .description('Set a secret on one or more repositories; the value is read from stdin, a file or a no-echo prompt')
+    .argument('<name>', 'secret name, as a workflow reads it: secrets.NAME')
+    .option('--repo <owner/repo>', 'repository to set it on (repeatable: one value, many repositories)', collect, [])
+    .option('--org', 'the organisation scope (the operator organisation only)')
+    .option('--from-file <path>', 'read the value from this file (one trailing newline is dropped)')
+    // Declared so the refusal is ours, with the reason, and not commander's "unknown option".
+    .addOption(new Option('--value [value]', 'refused: a secret never goes on the command line').hideHelp())
+    .action(async (name, opts) => {
+    if (opts.value !== undefined) {
+        usage(ARGV_REFUSAL);
+        return;
+    }
+    if (!validName(name))
+        return;
+    const targets = targetsFrom(opts);
+    if (!targets)
+        return;
+    const client = api();
+    if (!client)
+        return;
+    const value = await readSecretValue(name, opts.fromFile);
+    if (value === undefined)
+        return;
+    if (value === '') {
+        usage('the value is empty; nothing was set');
+        return;
+    }
+    const results = await setEverywhere(client, 'secret', targets, name, value);
+    printResults(name, results);
+    process.exitCode = batchExitCode(results);
+});
+const listCommand = new Command('list')
+    .description("A repository's secret names — never values: the API has none to give")
+    .option('--repo <owner/repo>', 'repository', collect, [])
+    .option('--org', 'the organisation scope (the operator organisation only)')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    const targets = targetsFrom(opts, true);
+    if (!targets?.[0])
+        return;
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await listSecrets(client, targets[0]);
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.detail));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json === true) {
+        console.log(JSON.stringify({ secrets: outcome.secrets }, null, 2));
+        return;
+    }
+    if (outcome.secrets.length === 0) {
+        console.log(chalk.yellow('No secrets are set here.'));
+        return;
+    }
+    console.log(chalk.bold(['NAME'.padEnd(32), 'UPDATED'].join('  ')));
+    for (const s of outcome.secrets)
+        console.log([s.name.padEnd(32), s.updatedAt ?? ''].join('  '));
+});
+const deleteCommand = new Command('delete')
+    .description('Delete a secret from one or more repositories')
+    .argument('<name>', 'secret name')
+    .option('--repo <owner/repo>', 'repository (repeatable)', collect, [])
+    .option('--org', 'the organisation scope (the operator organisation only)')
+    .option('-y, --yes', 'do not ask; required when not on a terminal')
+    .action(deleteAction('secret'));
+export default new Command('secret')
+    .description("Secrets: set a repository's secrets from the terminal, values write-only")
+    .addCommand(setCommand)
+    .addCommand(listCommand)
+    .addCommand(deleteCommand);

package/dist/cli/secret/shared.js

@@ -0,0 +1,104 @@
+import chalk from 'chalk';
+import { splitRepository } from '../../src/application/manage-caches.js';
+import { batchExitCode, deleteEverywhere } from '../../src/application/manage-secrets.js';
+import { confirm } from '../../src/infrastructure/secret-input.js';
+import { nameProblem } from '../../src/domain/secrets.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+export const collect = (value, previous) => [...previous, value];
+export const usage = (message) => {
+    console.error(chalk.red(message));
+    process.exitCode = 2;
+};
+/** Build the API client, or explain what is missing and stop. */
+export const api = () => {
+    try {
+        return new HttpControlPlane();
+    }
+    catch (err) {
+        usage(err instanceof NotConfiguredError ? err.message : String(err));
+        return undefined;
+    }
+};
+export const validName = (name) => {
+    const problem = nameProblem(name);
+    if (problem === undefined)
+        return true;
+    usage(problem);
+    return false;
+};
+/**
+ * `--repo` (repeatable) or `--org`, never both and never neither. `single`
+ * is for `list`, which answers about one place at a time.
+ */
+export const targetsFrom = (opts, single = false) => {
+    if (opts.org === true && opts.repo.length > 0) {
+        usage('pass --repo or --org, not both');
+        return undefined;
+    }
+    if (opts.org === true)
+        return [{ kind: 'org' }];
+    if (opts.repo.length === 0) {
+        usage('name a repository with --repo owner/repo');
+        return undefined;
+    }
+    if (single && opts.repo.length > 1) {
+        usage('list answers for one repository at a time: pass one --repo');
+        return undefined;
+    }
+    const targets = [];
+    for (const slug of opts.repo) {
+        const parsed = splitRepository(slug);
+        if (parsed === undefined) {
+            usage(`expected owner/repo, got ${JSON.stringify(slug)}`);
+            return undefined;
+        }
+        targets.push({ kind: 'repo', ...parsed });
+    }
+    return targets;
+};
+/** One line per target, then nothing else: the summary is the whole output. */
+export const printResults = (name, results) => {
+    for (const r of results) {
+        switch (r.kind) {
+            case 'set':
+                console.log(`${chalk.green('✔')} ${name} set on ${r.target}`);
+                break;
+            case 'deleted':
+                console.log(`${chalk.green('✔')} ${name} deleted from ${r.target}`);
+                break;
+            case 'not-found':
+                console.error(`${chalk.yellow('·')} ${r.target} has no ${name}`);
+                break;
+            case 'refused':
+                console.error(`${chalk.red('✖')} ${r.target}: ${r.detail}`);
+                break;
+        }
+    }
+};
+/**
+ * Delete from each target. Off a terminal it needs `--yes` (§7: nothing
+ * destructive without it); on one it asks.
+ */
+export const deleteAction = (kind) => async (name, opts) => {
+    if (!validName(name))
+        return;
+    const targets = targetsFrom(opts);
+    if (!targets)
+        return;
+    if (opts.yes !== true) {
+        if (process.stdin.isTTY !== true) {
+            usage(`deleting a ${kind} needs --yes when not run on a terminal`);
+            return;
+        }
+        if (!(await confirm(`delete ${kind} ${name} from ${targets.length === 1 ? 'this target' : `${targets.length} targets`}?`))) {
+            usage('nothing was deleted');
+            return;
+        }
+    }
+    const client = api();
+    if (!client)
+        return;
+    const results = await deleteEverywhere(client, kind, targets, name);
+    printResults(name, results);
+    process.exitCode = batchExitCode(results);
+};

package/dist/cli/spend/main.js

@@ -0,0 +1,81 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { reportSpend } from '../../src/application/report-spend.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+import { formatMicros, formatSeconds, savingPhrase, topWorkflows } from '../../src/domain/spend.js';
+import { parseRepository } from '../../src/domain/runs.js';
+const DEFAULT_ROWS = 10;
+const print = (report, rows) => {
+    const scope = report.repository ?? 'every repository';
+    console.log(chalk.bold(`${scope} · last ${report.windowDays} day${report.windowDays === 1 ? '' : 's'}`));
+    console.log('');
+    console.log(`  jobs            ${report.total.jobs}`);
+    console.log(`  runner time     ${formatSeconds(report.total.seconds)}`);
+    console.log(`  our estimate    ${chalk.bold(formatMicros(report.total.ours))}`);
+    console.log(`  GitHub would    ${formatMicros(report.total.github)}`);
+    const saving = savingPhrase(report.total.savedMicros, report.totalSavedPercent);
+    console.log(`  difference      ${report.total.savedMicros >= 0 ? chalk.green(saving) : chalk.yellow(saving)}`);
+    const shown = topWorkflows(report.workflows, rows);
+    if (shown.length > 0) {
+        // Ordered by what each cost *us*: the question is where the money goes,
+        // and a workflow that saves 99% of very little is not the one to look at.
+        console.log(chalk.bold('\n  where the time goes'));
+        for (const w of shown) {
+            console.log(`    ${w.name.padEnd(38)} ${formatSeconds(w.seconds).padStart(9)} ${formatMicros(w.ours).padStart(11)} ${chalk.dim(formatMicros(w.github).padStart(11))}`);
+        }
+        if (report.workflows.length > shown.length) {
+            console.log(chalk.dim(`    … ${report.workflows.length - shown.length} more`));
+        }
+    }
+    // Never behind a flag: the caveats arrive with the numbers and are printed
+    // with them (ADR-0024).
+    console.log('');
+    for (const caveat of report.caveats)
+        console.log(chalk.dim(`  note: ${caveat}`));
+};
+const handler = async (options) => {
+    const repository = options.repo === undefined ? undefined : parseRepository(options.repo);
+    if (options.repo !== undefined && repository === undefined) {
+        console.error(chalk.red(`--repo must be owner/repo, got ${options.repo}`));
+        process.exitCode = 2;
+        return;
+    }
+    const days = options.days === undefined ? undefined : Number(options.days);
+    if (days !== undefined && (!Number.isInteger(days) || days < 1)) {
+        console.error(chalk.red(`--days must be a positive integer, got ${options.days ?? ''}`));
+        process.exitCode = 2;
+        return;
+    }
+    const rows = options.workflows === undefined ? DEFAULT_ROWS : Number(options.workflows);
+    if (!Number.isInteger(rows) || rows < 1) {
+        console.error(chalk.red(`--workflows must be a positive integer, got ${options.workflows ?? ''}`));
+        process.exitCode = 2;
+        return;
+    }
+    let api;
+    try {
+        api = new HttpControlPlane();
+    }
+    catch (err) {
+        console.error(chalk.red(err instanceof NotConfiguredError ? err.message : String(err)));
+        process.exitCode = 2;
+        return;
+    }
+    const outcome = await reportSpend(api, { repository, days });
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.message));
+        process.exitCode = 2;
+        return;
+    }
+    if (options.json === true)
+        console.log(JSON.stringify(outcome.report, null, 2));
+    else
+        print(outcome.report, rows);
+};
+export default new Command('spend')
+    .description('Show what the fleet cost, next to what the same work would have cost on GitHub')
+    .option('--repo <owner/repo>', 'one repository (default: every repository)')
+    .option('--days <n>', 'window in days, clamped to 1–365 (default: 30)')
+    .option('--workflows <n>', `workflows to list (default: ${DEFAULT_ROWS})`)
+    .option('--json', 'print the report as JSON')
+    .action(handler);

package/dist/cli/terms/main.js

@@ -0,0 +1,85 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { acceptTermsFor, readTermsStanding } from '../../src/application/manage-terms.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+import { pendingLine, standingSummary } from '../../src/domain/terms.js';
+/** Build the API client, or explain what is missing and stop. */
+const api = () => {
+    try {
+        return new HttpControlPlane();
+    }
+    catch (err) {
+        console.error(chalk.red(err instanceof NotConfiguredError ? err.message : String(err)));
+        process.exitCode = 2;
+        return undefined;
+    }
+};
+const pendingCommand = new Command('pending')
+    .description('Accounts that owe an acceptance of the customer terms in force')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await readTermsStanding(client);
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.message));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json === true) {
+        console.log(JSON.stringify(outcome.value, null, 2));
+        return;
+    }
+    console.log(chalk.bold(`terms in force: ${outcome.value.version}`));
+    for (const row of outcome.value.pending)
+        console.log(`  ${pendingLine(row)}`);
+    console.log('');
+    console.log(outcome.value.pending.length === 0 ? chalk.green(standingSummary(outcome.value)) : chalk.yellow(standingSummary(outcome.value)));
+    // Never behind a flag: an operator reading this list is about to write to
+    // the people on it, and the product asks them anyway.
+    if (outcome.value.pending.length > 0) {
+        console.log(chalk.dim('  they are asked at their next sign-in; the notice by e-mail is yours — docs/run-book/customer-agreement.md'));
+    }
+});
+const acceptCommand = new Command('accept')
+    .description('Accept for one account as the machine token — the escalation path, not the normal one')
+    .argument('<installationId>', 'the installation the account is on')
+    .option('--confirm', "record the acceptance; without it nothing is written")
+    .option('--json', 'machine-readable output')
+    .action(async (raw, opts) => {
+    const installationId = Number(raw);
+    if (!Number.isSafeInteger(installationId) || installationId <= 0) {
+        console.error(chalk.red(`expected a positive installation id, got ${JSON.stringify(raw)}`));
+        process.exitCode = 2;
+        return;
+    }
+    // `--confirm` rather than a prompt, and refusing rather than defaulting:
+    // the customer accepts for themselves in the app, and an operator doing it
+    // for them is only right when a customer has asked in writing — for an
+    // account whose only owner has left. It must not be reachable by leaving a
+    // flag off.
+    if (opts.confirm !== true) {
+        console.error(chalk.yellow(`nothing written. The customer accepts for themselves at their next sign-in.\n` +
+            `Re-run with --confirm only on a customer's written instruction; the row will say the machine token accepted.`));
+        process.exitCode = 2;
+        return;
+    }
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await acceptTermsFor(client, installationId);
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.message));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json === true)
+        console.log(JSON.stringify(outcome.value, null, 2));
+    else
+        console.log(`${chalk.green('✔')} ${outcome.value.owner} accepted ${outcome.value.version} at ${outcome.value.at}`);
+});
+export default new Command('terms')
+    .description('The customer agreement: who owes an acceptance of the terms in force, and the escalation path')
+    .addCommand(pendingCommand)
+    .addCommand(acceptCommand);

package/dist/cli/tests/main.js

@@ -0,0 +1,122 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { inspectTests } from '../../src/application/inspect-runs.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+import { humanDuration, testMarker } from '../../src/domain/insight.js';
+import { parseRepository, unknownRunMessage } from '../../src/domain/runs.js';
+const printRun = (tests, all) => {
+    const { summary } = tests;
+    if (summary.total === 0) {
+        // Absence of reports is not absence of failures, and saying "0 tests"
+        // would let a job that wrote nothing read as a job that passed everything.
+        console.log(chalk.dim('no test reports were found in this run’s workspaces'));
+        return;
+    }
+    const parts = [chalk.green(`${summary.passed} passed`)];
+    if (summary.failed > 0)
+        parts.push(chalk.red(`${summary.failed} failed`));
+    if (summary.skipped > 0)
+        parts.push(chalk.dim(`${summary.skipped} skipped`));
+    console.log(parts.join(' · '));
+    const flaky = new Set(tests.flaky);
+    // A green suite is a number; only the failures are worth a line each,
+    // unless the reader asks for everything.
+    const shown = all ? tests.cases : tests.cases.filter((c) => c.outcome === 'failed');
+    if (shown.length > 0)
+        console.log('');
+    for (const c of shown) {
+        const suite = c.suite === undefined || c.suite === '' ? '' : chalk.dim(`${c.suite} · `);
+        const took = c.durationMs === undefined ? '' : chalk.dim(` (${humanDuration(c.durationMs)})`);
+        const mark = c.outcome === 'failed' ? chalk.red(testMarker(c.outcome)) : c.outcome === 'passed' ? chalk.green('✓') : chalk.dim('−');
+        const note = flaky.has(c.name) ? chalk.yellow(' [flaky]') : '';
+        console.log(`  ${mark} ${suite}${c.name}${took}${note}`);
+        if (c.outcome === 'failed' && c.message !== undefined && c.message !== '') {
+            console.log(chalk.dim(`      ${c.message.split('\n')[0]}`));
+        }
+    }
+    if (!all && summary.total > shown.length) {
+        console.log(chalk.dim(`\n${summary.total - shown.length} more — pass --all to list every test`));
+    }
+    if (flaky.size > 0) {
+        console.log(chalk.yellow(`\n${flaky.size} of these failures recently passed and failed at the same commit.`));
+    }
+};
+const printFlaky = (tests, repository) => {
+    if (tests.length === 0) {
+        console.log(chalk.dim(`no test in ${repository} has passed and failed at the same commit recently`));
+        return;
+    }
+    console.log(chalk.bold(`${tests.length} unreliable test${tests.length === 1 ? '' : 's'} in ${repository}`));
+    for (const t of tests) {
+        const suite = t.suite === '' ? '' : chalk.dim(`${t.suite} · `);
+        // The number of *commits* it disagreed at, which is the ranking — forty
+        // failures at one commit is one bad afternoon.
+        const commits = `${t.disagreements.length} commit${t.disagreements.length === 1 ? '' : 's'}`;
+        console.log(`  ${chalk.yellow(commits.padStart(10))}  ${suite}${t.name} ${chalk.dim(`in ${t.jobKey}`)}`);
+    }
+};
+const handler = async (run, options) => {
+    const repository = options.repo === undefined ? undefined : parseRepository(options.repo);
+    if (options.repo !== undefined && repository === undefined) {
+        console.error(chalk.red(`--repo must be owner/repo, got ${options.repo}`));
+        process.exitCode = 2;
+        return;
+    }
+    let api;
+    try {
+        api = new HttpControlPlane();
+    }
+    catch (err) {
+        console.error(chalk.red(err instanceof NotConfiguredError ? err.message : String(err)));
+        process.exitCode = 2;
+        return;
+    }
+    let outcome;
+    try {
+        outcome = await inspectTests(api, { run: run ?? 'latest', repository, flaky: options.flaky === true });
+    }
+    catch (err) {
+        console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 2;
+        return;
+    }
+    switch (outcome.kind) {
+        case 'needs-repo':
+            // A flake list belongs to a repository, not to a run. Guessing one from
+            // the newest run would answer about the wrong repository.
+            console.error(chalk.red('--flaky needs --repo owner/repo: unreliable tests are a property of a repository, not of one run'));
+            process.exitCode = 2;
+            return;
+        case 'no-runs':
+            console.error(chalk.yellow('no runs found'));
+            process.exitCode = 2;
+            return;
+        case 'unknown-run':
+            console.error(chalk.red(unknownRunMessage(outcome.selector)));
+            process.exitCode = 2;
+            return;
+        case 'flaky':
+            if (options.json === true)
+                console.log(JSON.stringify(outcome.tests, null, 2));
+            else
+                printFlaky(outcome.tests, outcome.repository);
+            return;
+        case 'tests':
+            if (options.json === true)
+                console.log(JSON.stringify(outcome.tests, null, 2));
+            else
+                printRun(outcome.tests, options.all === true);
+            // A run whose tests failed exits non-zero, so this composes in a script
+            // the same way the run's own conclusion does.
+            if (outcome.tests.summary.failed > 0)
+                process.exitCode = 1;
+    }
+};
+export default new Command('tests')
+    .description('Show a run’s test results, or a repository’s unreliable tests with --flaky')
+    .argument('[run]', 'run id, #number, or "latest"', 'latest')
+    .option('--repo <owner/repo>', 'limit the run search to one repository; required with --flaky')
+    .option('--flaky', 'list the repository’s tests that passed and failed at the same commit')
+    .option('--all', 'list every test, not only the failures')
+    .option('--json', 'print the results as JSON')
+    .action(handler);

package/dist/cli/timing/main.js

@@ -0,0 +1,90 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { inspectTiming } from '../../src/application/inspect-runs.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+import { humanDuration, slowestFirst, trendNote } from '../../src/domain/insight.js';
+import { parseRepository, unknownRunMessage } from '../../src/domain/runs.js';
+const DEFAULT_STEPS = 5;
+const print = (timing, perJob) => {
+    console.log(chalk.bold(timing.workflowPath));
+    // What got slower goes first, and on its own, because it is the only part of
+    // this output that is news. The per-job breakdown below is reference.
+    if (timing.slower.length > 0) {
+        console.log(chalk.bold('\nSlower than usual'));
+        for (const step of timing.slower) {
+            const where = step.jobKey === undefined ? '' : chalk.dim(` in ${step.jobKey}`);
+            console.log(`  ${chalk.yellow(step.name)}${where}  ${humanDuration(step.durationMs)}  ${chalk.yellow(trendNote(step) ?? '')}`);
+        }
+    }
+    for (const job of timing.jobs) {
+        const total = job.durationMs === undefined ? '' : chalk.dim(` · ${humanDuration(job.durationMs)}`);
+        console.log(chalk.bold(`\n${job.name}`) + total);
+        if (job.steps.length === 0) {
+            // A job whose runner predates step timings has none, and printing an
+            // empty list would read as "this job had no steps".
+            console.log(chalk.dim('  no step timings recorded'));
+            continue;
+        }
+        for (const step of slowestFirst(job.steps, perJob)) {
+            const note = trendNote(step);
+            const suffix = note === undefined ? chalk.dim(`  (${step.samples} previous)`) : chalk.dim(`  ${note}`);
+            console.log(`  ${humanDuration(step.durationMs).padStart(8)}  ${step.slower ? chalk.yellow(step.name) : step.name}${suffix}`);
+        }
+        if (job.steps.length > perJob)
+            console.log(chalk.dim(`  … ${job.steps.length - perJob} faster steps not shown`));
+    }
+};
+const handler = async (run, options) => {
+    const repository = options.repo === undefined ? undefined : parseRepository(options.repo);
+    if (options.repo !== undefined && repository === undefined) {
+        console.error(chalk.red(`--repo must be owner/repo, got ${options.repo}`));
+        process.exitCode = 2;
+        return;
+    }
+    const perJob = Number(options.steps ?? DEFAULT_STEPS);
+    if (!Number.isInteger(perJob) || perJob < 1) {
+        console.error(chalk.red(`--steps must be a positive integer, got ${String(options.steps)}`));
+        process.exitCode = 2;
+        return;
+    }
+    let api;
+    try {
+        api = new HttpControlPlane();
+    }
+    catch (err) {
+        console.error(chalk.red(err instanceof NotConfiguredError ? err.message : String(err)));
+        process.exitCode = 2;
+        return;
+    }
+    let outcome;
+    try {
+        outcome = await inspectTiming(api, { run: run ?? 'latest', repository });
+    }
+    catch (err) {
+        console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+        process.exitCode = 2;
+        return;
+    }
+    switch (outcome.kind) {
+        case 'no-runs':
+            console.error(chalk.yellow('no runs found'));
+            process.exitCode = 2;
+            return;
+        case 'unknown-run':
+            console.error(chalk.red(unknownRunMessage(outcome.selector)));
+            process.exitCode = 2;
+            return;
+        case 'timing':
+            if (options.json === true)
+                console.log(JSON.stringify(outcome.timing, null, 2));
+            else
+                print(outcome.timing, perJob);
+    }
+};
+export default new Command('timing')
+    .description('Show where a run spent its time, and which steps got slower than usual')
+    .argument('[run]', 'run id, #number, or "latest"', 'latest')
+    .option('--repo <owner/repo>', 'limit the run search to one repository')
+    .option('--steps <n>', `slowest steps to show per job (default: ${DEFAULT_STEPS})`)
+    .option('--json', 'print the timings as JSON')
+    .action(handler);

package/dist/cli/validate/main.js

@@ -0,0 +1,48 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { validateWorkflows } from '../../src/application/validate-workflows.js';
+import { EngineBinaryValidator, GitHubWorkflowLocator } from '../../src/infrastructure/engine-binary.js';
+import { diagnosticCount } from '../../src/domain/validation.js';
+const printHuman = (report) => {
+    for (const file of report.files) {
+        if (file.diagnostics.length === 0) {
+            console.log(`${chalk.green('✔')} ${file.path}`);
+            continue;
+        }
+        for (const d of file.diagnostics) {
+            const where = d.line ? `:${d.line}:${d.column ?? 1}` : '';
+            const sev = d.severity === 'error' ? chalk.red(d.severity) : chalk.yellow(d.severity);
+            const at = d.path ? chalk.dim(` (${d.path})`) : '';
+            console.log(`${file.path}${where} ${sev} ${d.message}${at}`);
+        }
+    }
+    const n = diagnosticCount(report);
+    if (n > 0)
+        console.log(chalk.dim(`${n} diagnostic${n === 1 ? '' : 's'}`));
+};
+const handler = async (files, options) => {
+    const outcome = await validateWorkflows(new EngineBinaryValidator(), new GitHubWorkflowLocator(), files);
+    switch (outcome.kind) {
+        case 'no-workflows':
+            console.error(chalk.yellow('no workflow files found (.github/workflows/*.yml) — pass files explicitly'));
+            process.exitCode = 2;
+            return;
+        case 'engine-missing':
+            console.error(chalk.red(outcome.detail));
+            process.exitCode = 2;
+            return;
+        case 'report':
+            if (options.json) {
+                console.log(JSON.stringify(outcome.report, null, 2));
+            }
+            else {
+                printHuman(outcome.report);
+            }
+            process.exitCode = outcome.ok ? 0 : 1;
+    }
+};
+export default new Command('validate')
+    .description('Validate workflow files against the engine (defaults to .github/workflows/*.yml)')
+    .argument('[files...]', 'workflow files to validate ("-" reads stdin)')
+    .option('--json', 'print diagnostics as JSON')
+    .action(handler);