@apex-actions/cli 0.67.0

package/dist/cli/reproduce/main.js

@@ -0,0 +1,73 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { reproduceRun } from '../../src/application/explain-runs.js';
+import { HttpControlPlane, NotConfiguredError, WorkingDirectoryWriter } from '../../src/infrastructure/control-plane-http.js';
+import { commandLine } from '../../src/domain/provenance.js';
+import { parseRepository, unknownRunMessage } from '../../src/domain/runs.js';
+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 reproduceRun(api, new WorkingDirectoryWriter(), {
+            run: run ?? 'latest',
+            repository,
+            job: options.job,
+            write: options.write,
+        });
+    }
+    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 'recipe': {
+            const { recipe } = outcome;
+            if (options.json === true) {
+                console.log(JSON.stringify({ ...recipe, wrote: outcome.wrote }, null, 2));
+                return;
+            }
+            const leg = recipe.job === undefined ? '' : ` · ${recipe.job.name}`;
+            console.log(chalk.bold(`${recipe.repository} · ${recipe.workflowPath} @ ${recipe.sha.slice(0, 7)}${leg}`));
+            if (outcome.wrote !== undefined)
+                console.log(chalk.dim(`wrote ${outcome.wrote}`));
+            if (recipe.payloadUnavailable !== undefined)
+                console.log(chalk.yellow(recipe.payloadUnavailable));
+            // The command goes to stdout on its own line so it survives being piped
+            // into a shell; everything else here is commentary.
+            console.log(`\n${commandLine(recipe.command)}\n`);
+            for (const note of recipe.notes)
+                console.error(chalk.yellow(`note: ${note}`));
+        }
+    }
+};
+export default new Command('reproduce')
+    .description("Print the `apex run` invocation that reproduces a past run locally (secrets by name only)")
+    .argument('[run]', 'run id, #number, or "latest"', 'latest')
+    .option('--repo <owner/repo>', 'limit the run search to one repository')
+    .option('--job <key>', 'reproduce one matrix leg by its key, rather than the whole workflow')
+    .option('--no-write', 'print the command without writing the event payload file it refers to')
+    .option('--json', 'print the recipe as JSON')
+    .action(handler);

package/dist/cli/rerun/main.js

@@ -0,0 +1,100 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { rerunRun } from '../../src/application/rerun-runs.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+import { parseRepository, unknownRunMessage } from '../../src/domain/runs.js';
+const modeFor = (options) => (options.job !== undefined ? 'job' : options.failed === true ? 'failed' : 'all');
+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 rerunRun(api, {
+            run: run ?? 'latest',
+            repository,
+            mode: modeFor(options),
+            jobId: options.job,
+            debug: options.debug === true,
+            resume: options.resume === true,
+        });
+    }
+    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 'needs-job':
+            console.error(chalk.red('--job needs an engine job id'));
+            process.exitCode = 2;
+            return;
+        case 'refused':
+            console.error(chalk.red(outcome.message));
+            process.exitCode = 2;
+            return;
+        case 'started': {
+            if (options.json === true) {
+                console.log(JSON.stringify({ runId: outcome.runId, resuming: outcome.resuming }, null, 2));
+                return;
+            }
+            console.log(chalk.green(`re-run started — ${outcome.runId}`));
+            if (options.resume === true) {
+                if (outcome.resuming.length === 0) {
+                    // A --resume that silently found nothing looks identical to one that
+                    // worked, and the difference is several minutes of somebody's
+                    // afternoon.
+                    console.error(chalk.yellow('nothing to resume from: no snapshot of this run survives, so every job starts from the top'));
+                }
+                else {
+                    for (const snap of outcome.resuming) {
+                        const step = snap.resumeFromName ?? snap.resumeFrom;
+                        console.log(`  ${snap.jobName} resumes at ${chalk.bold(step)} ${chalk.dim(`(${formatSize(snap.sizeBytes)} workspace)`)}`);
+                    }
+                }
+            }
+        }
+    }
+};
+const formatSize = (bytes) => {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    const units = ['KB', 'MB', 'GB'];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit++;
+    }
+    return `${value.toFixed(1)} ${units[unit]}`;
+};
+export default new Command('rerun')
+    .description('Re-run a completed run — all of it, only what failed, or one job — optionally resuming from the step that failed')
+    .argument('[run]', 'run id, #number, or "latest"', 'latest')
+    .option('--repo <owner/repo>', 'limit the run search to one repository')
+    .option('--failed', 'only the jobs that did not succeed, plus everything downstream of one')
+    .option('--job <id>', 'one engine job id and its dependents (matrix legs re-run as a unit, like GitHub)')
+    .option('--resume', 'start each job at the step it failed at, where a snapshot of that failure survives')
+    .option('--debug', 'enable step debug logging for the new attempt')
+    .option('--json', 'print the result as JSON')
+    .action(handler);

package/dist/cli/run/main.js

@@ -0,0 +1,50 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { runWorkflow } from '../../src/application/run-workflow.js';
+import { RunnerBinaryExecutor } from '../../src/infrastructure/runner-binary.js';
+import { GitHubWorkflowLocator } from '../../src/infrastructure/engine-binary.js';
+const collect = (value, previous) => [...previous, value];
+const handler = async (workflow, options) => {
+    const outcome = await runWorkflow(new RunnerBinaryExecutor(), new GitHubWorkflowLocator(), workflow, {
+        ...(options.job !== undefined ? { job: options.job } : {}),
+        ...(options.event !== undefined ? { event: options.event } : {}),
+        ...(options.payload !== undefined ? { payload: options.payload } : {}),
+        ...(options.image !== undefined ? { image: options.image } : {}),
+        secrets: options.secret,
+        vars: options.var,
+        inputs: options.input,
+        changedFiles: options.changedFile,
+        json: options.json === true,
+    });
+    switch (outcome.kind) {
+        case 'no-workflows':
+            console.error(chalk.yellow('no workflow files found (.github/workflows/*.yml) — pass one explicitly'));
+            process.exitCode = 2;
+            return;
+        case 'ambiguous':
+            console.error(chalk.yellow('multiple workflows found — pass one explicitly:'));
+            for (const c of outcome.candidates)
+                console.error(`  ${c}`);
+            process.exitCode = 2;
+            return;
+        case 'runner-missing':
+            console.error(chalk.red(outcome.detail));
+            process.exitCode = 2;
+            return;
+        case 'exit':
+            process.exitCode = outcome.code;
+    }
+};
+export default new Command('run')
+    .description('Run a workflow locally with the same engine and executor as the service (wraps apex-runner --local)')
+    .argument('[workflow]', 'workflow file to run (default: the only file in .github/workflows/)')
+    .option('--job <id>', 'run only this job id (its needs are assumed satisfied)')
+    .option('--event <name>', 'event to plan against (default: push)')
+    .option('--payload <file>', 'JSON file with the event payload')
+    .option('--secret <KEY[=value]>', 'secret (repeatable): KEY alone reads the value from your environment, keeping it out of argv; GITHUB_TOKEN reaches the github context', collect, [])
+    .option('--var <KEY=value>', 'repository variable (repeatable)', collect, [])
+    .option('--input <key=value>', 'workflow_dispatch input (repeatable)', collect, [])
+    .option('--changed-file <path>', 'changed file for paths filters (repeatable)', collect, [])
+    .option('--image <image>', 'default job container image')
+    .option('--json', 'print the run result as JSON on stdout')
+    .action(handler);

package/dist/cli/runner/main.js

@@ -0,0 +1,238 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { fleetHistory, listRunners, mintRegistrationToken, registerRunner, removeRunner, MAX_TOKEN_USES, } from '../../src/application/manage-runners.js';
+import { humanSeconds, parseDuration } from '../../src/domain/fleet-history.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+import { RunnerBinaryExecutor } from '../../src/infrastructure/runner-binary.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 age = (iso) => {
+    if (iso === undefined)
+        return '—';
+    const seconds = Math.max(0, Math.round((Date.now() - Date.parse(iso)) / 1000));
+    if (seconds < 90)
+        return `${seconds}s`;
+    if (seconds < 5400)
+        return `${Math.round(seconds / 60)}m`;
+    return `${Math.round(seconds / 3600)}h`;
+};
+const machineOf = (r) => {
+    if (r.instanceType === undefined)
+        return `${r.os}/${r.arch}`;
+    return `${r.instanceType}${r.instanceLifecycle === 'spot' ? ' (spot)' : ''}`;
+};
+const printRunners = (runners, demand) => {
+    if (runners.length === 0) {
+        console.log(chalk.yellow('No runners are registered.'));
+    }
+    else {
+        console.log(chalk.bold(['ID', 'NAME', 'POOL', 'MACHINE', 'LABELS', 'SEEN'].join('  ')));
+        for (const r of runners) {
+            console.log([r.id, r.name, r.pool ?? '—', machineOf(r), r.labels.join(','), age(r.lastSeenAt ?? r.registeredAt)].join('  '));
+        }
+    }
+    // The half that answers "why is my job still queued".
+    const waiting = demand.filter((d) => d.queued > 0);
+    if (waiting.length === 0) {
+        console.log(chalk.green('\nNothing is queued.'));
+        return;
+    }
+    console.log(chalk.bold('\nQUEUED  WAITING  IDLE  BUSY  RUNS-ON'));
+    for (const d of waiting) {
+        const line = [String(d.queued), `${d.oldestWaitSeconds}s`, String(d.idleRunners), String(d.busyRunners), d.labels.join(',')].join('  ');
+        // Nothing can take it: the single most useful thing to shout about.
+        console.log(d.idleRunners + d.busyRunners === 0 ? chalk.red(line) : line);
+    }
+    if (waiting.some((d) => d.idleRunners + d.busyRunners === 0)) {
+        console.log(chalk.red('\nRed rows have no runner whose labels satisfy them. Nothing will pick them up.'));
+    }
+};
+const listCommand = new Command('list')
+    .description('Registered runners, and the work waiting for them')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await listRunners(client);
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.detail));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json === true) {
+        console.log(JSON.stringify({ runners: outcome.runners, demand: outcome.demand }, null, 2));
+        return;
+    }
+    printRunners(outcome.runners, outcome.demand);
+});
+const tokenCommand = new Command('token')
+    .description('Mint a runner registration token (single-use by default)')
+    .option('--uses <n>', `registrations this token may grant, 1–${MAX_TOKEN_USES}`, '1')
+    .action(async (opts) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await mintRegistrationToken(client, Number(opts.uses));
+    switch (outcome.kind) {
+        case 'bad-uses':
+            console.error(chalk.red(`--uses must be a whole number between 1 and ${MAX_TOKEN_USES}, got ${opts.uses}`));
+            process.exitCode = 2;
+            return;
+        case 'refused':
+            console.error(chalk.red(outcome.detail));
+            process.exitCode = 1;
+            return;
+        case 'minted':
+            // The token itself on stdout and nothing else, so `$(...)` works; the
+            // commentary goes to stderr where it cannot end up in a script's
+            // variable — or in a log of one.
+            console.log(outcome.token.token);
+            console.error(chalk.dim(`${outcome.token.uses} use(s), expires ${outcome.token.expiresAt}. Register with:\n` +
+                `  apex-runner --server <host:50052> --registration-token <token>`));
+    }
+});
+const removeCommand = new Command('remove')
+    .description('Deregister a runner by id, revoking its credential')
+    .argument('<id>', 'runner id (apex runner list prints them)')
+    .action(async (id) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await removeRunner(client, id);
+    switch (outcome.kind) {
+        case 'not-found':
+            console.error(chalk.red(`no runner ${outcome.id}`));
+            process.exitCode = 1;
+            return;
+        case 'refused':
+            console.error(chalk.red(outcome.detail));
+            process.exitCode = 1;
+            return;
+        case 'removed':
+            console.log(`${chalk.green('✔')} runner ${id} deregistered`);
+    }
+});
+const registerCommand = new Command('register')
+    .description('Attach this machine as a self-hosted runner and start leasing work')
+    .requiredOption('--labels <labels>', 'comma-separated labels, e.g. self-hosted,linux,gpu')
+    .option('--server <host:port>', 'runner endpoint (APEX_RUNNER_SERVER)', process.env['APEX_RUNNER_SERVER'])
+    .option('--name <name>', 'display name (default: this hostname)')
+    .option('--work-dir <path>', 'scratch root for job workspaces')
+    .option('--idle-timeout <duration>', 'stop after this long with no job, e.g. 30m (default: never)')
+    .option('--ephemeral', 'take one job, then deregister', false)
+    .action(async (opts) => {
+    if (opts.server === undefined || opts.server === '') {
+        console.error(chalk.red('--server <host:port> is required (or set APEX_RUNNER_SERVER) — this is the runner.v1 endpoint, not the web URL'));
+        process.exitCode = 2;
+        return;
+    }
+    const client = api();
+    if (!client)
+        return;
+    // This process becomes the runner: it runs until stopped, and executes
+    // other people's code on this machine. Say so before it starts.
+    console.error(chalk.dim(`registering ${opts.name ?? 'this machine'} with ${opts.server} as [${opts.labels}]`));
+    const outcome = await registerRunner(client, new RunnerBinaryExecutor(), {
+        server: opts.server,
+        labels: opts.labels.split(','),
+        name: opts.name,
+        workDir: opts.workDir,
+        idleTimeout: opts.idleTimeout,
+        ephemeral: opts.ephemeral,
+    });
+    switch (outcome.kind) {
+        case 'no-labels':
+            console.error(chalk.red('--labels cannot be empty: a runner with no labels would register, look healthy, and never take a job'));
+            process.exitCode = 2;
+            return;
+        case 'runner-missing':
+        case 'refused':
+            console.error(chalk.red(outcome.detail));
+            process.exitCode = 1;
+            return;
+        case 'exit':
+            process.exitCode = outcome.code;
+    }
+});
+const printHistory = (h) => {
+    const span = Math.round((Date.parse(h.until) - Date.parse(h.since)) / 1000);
+    console.log(chalk.bold(`${h.since} → ${h.until}`) + chalk.dim(`  (${humanSeconds(span)})`));
+    console.log(chalk.dim(`${h.counted} runner${h.counted === 1 ? '' : 's'} existed in this window`));
+    if (h.emptyThroughout) {
+        console.log(chalk.green('\nThe fleet held no instances at any point in this window.'));
+    }
+    else {
+        console.log(chalk.bold('\nPeak'));
+        console.log(`  ${chalk.bold(String(h.peak.count))} instances at once, at ${h.peak.at}`);
+        for (const p of h.peakByPool)
+            console.log(chalk.dim(`  ${String(p.count).padStart(3)}  ${p.pool}  (${p.at})`));
+    }
+    console.log(chalk.bold('\nAt zero'));
+    if (h.secondsAtZero === 0) {
+        console.log(chalk.yellow('  never — the fleet held at least one instance throughout'));
+    }
+    else {
+        const share = Math.round((h.secondsAtZero / Math.max(1, span)) * 100);
+        console.log(`  ${humanSeconds(h.secondsAtZero)} of ${humanSeconds(span)} (${share}%), in ${h.zeroWindows.length} stretch${h.zeroWindows.length === 1 ? '' : 'es'}`);
+        if (h.longestZero)
+            console.log(`  longest ${chalk.bold(humanSeconds(h.longestZero.seconds))}: ${h.longestZero.from} → ${h.longestZero.to}`);
+    }
+    if (h.excluded.length > 0) {
+        // Named, never silently dropped: a capacity number that quietly ignores
+        // machines is the kind that gets quoted back later.
+        console.log(chalk.bold('\nNot counted'));
+        for (const e of h.excluded)
+            console.log(chalk.dim(`  ${e.name} — ${e.reason}`));
+    }
+    console.log(chalk.dim(`\nReconstructed from runner lifetimes; an instance's end is accurate to ~${h.resolutionSeconds}s (one long-poll window).`));
+};
+const historyCommand = new Command('history')
+    .description('How big the fleet was, and when it was at zero, over a window that has passed')
+    .option('--since <duration>', 'how far back to look: 24h, 90m, 2d', '24h')
+    .option('--until <iso>', 'end of the window (default: now)')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    const seconds = parseDuration(opts.since);
+    if (seconds === undefined) {
+        console.error(chalk.red(`--since must be a duration like 24h, 90m or 2d, got ${opts.since}`));
+        process.exitCode = 2;
+        return;
+    }
+    const until = opts.until === undefined ? new Date() : new Date(opts.until);
+    if (Number.isNaN(until.getTime())) {
+        console.error(chalk.red(`--until must be an ISO 8601 timestamp, got ${opts.until ?? ''}`));
+        process.exitCode = 2;
+        return;
+    }
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await fleetHistory(client, { since: new Date(until.getTime() - seconds * 1000), until });
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.detail));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json === true) {
+        console.log(JSON.stringify(outcome.history, null, 2));
+        return;
+    }
+    printHistory(outcome.history);
+});
+export default new Command('runner')
+    .description('Runners: attach this machine, list what is registered, mint tokens, deregister, read the fleet’s past')
+    .addCommand(listCommand)
+    .addCommand(historyCommand)
+    .addCommand(tokenCommand)
+    .addCommand(registerCommand)
+    .addCommand(removeCommand);

package/dist/cli/schedule/main.js

@@ -0,0 +1,54 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { listSchedules } from '../../src/application/manage-environments.js';
+import { splitRepository } from '../../src/application/manage-caches.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+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 printSchedules = (schedules) => {
+    if (schedules.length === 0) {
+        console.log(chalk.yellow('Nothing is scheduled.'));
+        // The commonest cause by a distance, and the one nobody guesses.
+        console.log(chalk.dim('A schedule is read from the default branch. A `schedule:` block on any other branch never runs — on GitHub either.'));
+        return;
+    }
+    console.log(chalk.bold(['NEXT (UTC)', 'CRON', 'WORKFLOW'].join('  ')));
+    for (const s of schedules)
+        console.log([s.nextRunAt, s.cron, s.workflowPath].join('  '));
+    console.log(chalk.dim('\nEverything is UTC, as on GitHub. Schedules are derived from the default branch and rebuilt whenever it is read.'));
+};
+const listCommand = new Command('list')
+    .description('What a repository has scheduled, and when each fires next')
+    .argument('<repository>', 'owner/repo')
+    .option('--json', 'machine-readable output')
+    .action(async (slug, opts) => {
+    const target = splitRepository(slug);
+    if (!target) {
+        console.error(chalk.red(`expected owner/repo, got ${JSON.stringify(slug)}`));
+        process.exitCode = 2;
+        return;
+    }
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await listSchedules(client, target.owner, target.repo);
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.detail));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json === true) {
+        console.log(JSON.stringify({ schedules: outcome.schedules }, null, 2));
+        return;
+    }
+    printSchedules(outcome.schedules);
+});
+export default new Command('schedule').description('Schedules: what `on: schedule` will fire, and when').addCommand(listCommand);

package/dist/cli/search/main.js

@@ -0,0 +1,123 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { searchLogs } from '../../src/application/search-logs.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+import { resultRef, resultTitle } from '../../src/domain/logsearch.js';
+import { parseRepository } from '../../src/domain/runs.js';
+/** The matched terms in bold, the rest as written. */
+const highlight = (hit) => {
+    let out = '';
+    let cursor = 0;
+    for (const span of hit.spans) {
+        if (span.start < cursor)
+            continue; // overlapping terms: the first one won
+        out += hit.text.slice(cursor, span.start) + chalk.bold.yellow(hit.text.slice(span.start, span.end));
+        cursor = span.end;
+    }
+    return out + hit.text.slice(cursor) + (hit.clipped === true ? chalk.dim(' …') : '');
+};
+const print = (report) => {
+    console.log(chalk.bold(`${report.repository} · ${JSON.stringify(report.query)} · last ${report.windowDays} day${report.windowDays === 1 ? '' : 's'}`));
+    console.log('');
+    for (const result of report.results) {
+        const state = result.conclusion ?? result.status;
+        const colour = state === 'success' ? chalk.green : state === 'failure' ? chalk.red : chalk.yellow;
+        console.log(`  ${chalk.bold(resultTitle(result))}  ${colour(state)}`);
+        console.log(chalk.dim(`    ${resultRef(result)} · ${result.jobId}`));
+        for (const hit of result.hits) {
+            const where = hit.step === undefined ? '' : chalk.dim(` ${hit.step}`);
+            console.log(`    ${chalk.dim(String(hit.line).padStart(6))}${where}  ${highlight(hit)}`);
+        }
+        if (result.moreHits !== undefined)
+            console.log(chalk.dim(`    … ${result.moreHits} more matching lines in this job`));
+        console.log('');
+    }
+    if (report.results.length === 0)
+        console.log(chalk.yellow('  no matches\n'));
+    console.log(chalk.dim(`  ${report.matchedLines} matching line${report.matchedLines === 1 ? '' : 's'} in ${report.matchedJobs} of ${report.scanned} jobs read`));
+    // Never behind a flag: what a search did not cover reads as an absence of
+    // matches unless it is said out loud (ADR-0026).
+    for (const note of report.notes)
+        console.log(chalk.dim(`  note: ${note}`));
+};
+const handler = async (positional, options) => {
+    // `-flaky error` is a valid query and commander reads any argv token starting
+    // with `-` as an option, so the documented exclusion syntax is unusable as
+    // the *first* term of a positional argument. `-e/--query` is the way past it,
+    // the same way `grep -e` is; `--` works too. Found on dev, v0.24.0.
+    const query = options.query ?? positional;
+    if (query === undefined || query.trim() === '') {
+        console.error(chalk.red('a query is required — pass it as an argument, or with -e when it starts with "-"'));
+        console.error(chalk.dim('  apex search "OOMKilled" --repo owner/repo'));
+        console.error(chalk.dim('  apex search -e "-flaky error" --repo owner/repo'));
+        process.exitCode = 2;
+        return;
+    }
+    if (options.repo === undefined) {
+        console.error(chalk.red('--repo owner/repo is required — a log search is scoped to one repository'));
+        process.exitCode = 2;
+        return;
+    }
+    const repository = parseRepository(options.repo);
+    if (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 limit = options.limit === undefined ? undefined : Number(options.limit);
+    if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
+        console.error(chalk.red(`--limit must be a positive integer, got ${options.limit ?? ''}`));
+        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 searchLogs(api, repository, {
+        query,
+        workflow: options.workflow,
+        branch: options.branch,
+        conclusion: options.conclusion,
+        job: options.job,
+        caseSensitive: options.case,
+        days,
+        limit,
+    });
+    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);
+    // Nothing found is not a failure — a search that answers "no" answered.
+    process.exitCode = 0;
+};
+export default new Command('search')
+    .description('Search a repository’s log text across runs')
+    .argument('[query]', 'terms, "a phrase" to keep words together, -term to exclude; all required terms must be on the same line')
+    .option('-e, --query <query>', 'the query, for one that starts with "-" — an argument beginning with a dash is read as an option')
+    .option('--repo <owner/repo>', 'the repository to search (required)')
+    .option('--workflow <path>', 'one workflow file')
+    .option('--branch <name>', 'one branch, written as a name or a full ref')
+    .option('--conclusion <state>', 'jobs that ended this way, e.g. failure')
+    .option('--job <name>', 'one job by name or matrix key')
+    .option('--case', 'match case (default: fold it)')
+    .option('--days <n>', 'window in days, clamped to 1–365 (default: 30)')
+    .option('--limit <n>', 'jobs whose logs are read, newest first (default: 200)')
+    .option('--json', 'print the report as JSON')
+    .action(handler);