@apex-actions/cli 0.67.0

package/dist/cli/actions/main.js

@@ -0,0 +1,193 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { listActions, proposePins, readPolicy, writePolicy } from '../../src/application/manage-actions.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+import { inventorySummary, patternList, pinningLabel, policyLine, } from '../../src/domain/supplychain.js';
+import { parseRepository } from '../../src/domain/runs.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 repository = (slug) => {
+    const parsed = parseRepository(slug);
+    if (parsed)
+        return parsed;
+    console.error(chalk.red(`expected owner/repo, got ${JSON.stringify(slug)}`));
+    process.exitCode = 2;
+    return undefined;
+};
+const printInventory = (inv) => {
+    console.log(chalk.bold(`${inv.repository} · ${inv.ref.slice(0, 7)}`));
+    console.log(chalk.dim(`  policy  ${policyLine(inv.policy)}`));
+    console.log('');
+    if (inv.references.length === 0) {
+        console.log(chalk.yellow('  This repository pulls in no third-party actions.'));
+    }
+    else {
+        for (const ref of inv.references) {
+            // Movable is the state worth noticing, so it is the one with a colour.
+            const label = ref.pinning === 'movable' ? chalk.yellow(pinningLabel(ref.pinning)) : chalk.dim(pinningLabel(ref.pinning));
+            const from = ref.pinnedFrom === undefined || ref.pinnedFrom === '' ? '' : chalk.dim(` (${ref.pinnedFrom})`);
+            console.log(`  ${ref.ref.padEnd(60)} ${label}${from}`);
+            console.log(chalk.dim(`    ${ref.uses.map((u) => `${u.workflowPath}${u.line === undefined ? '' : `:${u.line}`}`).join(', ')}`));
+        }
+        console.log(chalk.dim(`\n  ${inventorySummary(inv)}`));
+    }
+    const findings = inv.workflows.flatMap((w) => w.findings);
+    if (findings.length > 0) {
+        console.log(chalk.bold('\n  what the policy says'));
+        for (const f of findings) {
+            console.log(`    ${chalk.red(f.code.padEnd(12))} ${f.workflowPath}${f.line === undefined ? '' : `:${f.line}`}  ${f.reason}`);
+        }
+    }
+    // Never behind a flag: what the control does not cover arrives with what it
+    // does, so a clean list cannot be read as a safe repository (ADR-0025).
+    console.log('');
+    for (const caveat of inv.caveats)
+        console.log(chalk.dim(`  note: ${caveat}`));
+};
+const printProposal = (proposal, applied) => {
+    if (proposal.files.length === 0 && proposal.unresolved.length === 0) {
+        console.log(chalk.green(`${proposal.repository} is already pinned to the commits its versions point at.`));
+        return;
+    }
+    console.log(chalk.bold(`${proposal.repository} · against ${proposal.base}`));
+    for (const file of proposal.files) {
+        console.log(`\n  ${chalk.bold(file.path)}`);
+        for (const change of file.changes) {
+            console.log(`    ${change.ref}`);
+            console.log(`      → ${chalk.green(change.to)}${change.from === '' ? '' : chalk.dim(`  # ${change.from}`)}`);
+        }
+    }
+    if (proposal.unresolved.length > 0) {
+        console.log(chalk.bold('\n  left alone'));
+        for (const u of proposal.unresolved)
+            console.log(`    ${u.ref} ${chalk.dim(`in ${u.workflowPath} — ${u.reason}`)}`);
+    }
+    console.log('');
+    if (proposal.pullRequest !== undefined) {
+        const verb = proposal.pullRequest.created ? 'opened' : 'updated';
+        console.log(`${chalk.green('✔')} pull request ${verb}: ${proposal.pullRequest.url}`);
+    }
+    else if (applied) {
+        console.log(chalk.yellow('  nothing to propose, so no pull request was opened'));
+    }
+    else {
+        console.log(chalk.dim('  preview only — rerun with --apply to open the pull request'));
+    }
+    console.log(chalk.dim('\n  note: a new release and a moved tag produce the same diff here. Both change the code this repository runs.'));
+};
+const listCommand = new Command('list')
+    .description('Every action a repository pulls in, least fixed first')
+    .argument('<repository>', 'owner/repo')
+    .option('--json', 'machine-readable output')
+    .action(async (slug, opts) => {
+    const target = repository(slug);
+    if (!target)
+        return;
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await listActions(client, target);
+    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
+        printInventory(outcome.value);
+});
+const policyCommand = new Command('policy')
+    .description("Read or replace an organisation's action policy")
+    .argument('<owner>', 'the organisation')
+    .option('--mode <mode>', 'off · audit · enforce — omit to read the policy rather than change it')
+    .option('--allow <patterns...>', 'patterns that may be used; empty means everything not denied')
+    .option('--deny <patterns...>', 'patterns that may not be used; deny wins over allow')
+    // Deliberately no `--no-require-pinned`: commander gives a flag that has a
+    // `--no-` twin a default of `true`, which would silently turn on the
+    // strictest rule in the policy for anybody who omitted both. Setting a
+    // policy replaces it, so leaving this off is how you allow tags.
+    .option('--require-pinned', 'require a commit SHA (or an image digest); a version tag does not count. Omit to permit tags')
+    .option('--json', 'machine-readable output')
+    .action(async (owner, opts) => {
+    const client = api();
+    if (!client)
+        return;
+    // Reading is the default. Changing an organisation's policy is not
+    // something to fall into by leaving a flag off.
+    if (opts.mode === undefined) {
+        const current = await readPolicy(client, owner);
+        if (current.kind === 'refused') {
+            console.error(chalk.red(current.message));
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.json === true)
+            console.log(JSON.stringify(current.value, null, 2));
+        else {
+            console.log(chalk.bold(owner));
+            console.log(`  ${policyLine(current.value)}`);
+            if (current.value.updatedBy !== undefined)
+                console.log(chalk.dim(`  last changed by ${current.value.updatedBy}`));
+        }
+        return;
+    }
+    if (!['off', 'audit', 'enforce'].includes(opts.mode)) {
+        console.error(chalk.red(`--mode must be off, audit or enforce, got ${opts.mode}`));
+        process.exitCode = 2;
+        return;
+    }
+    const outcome = await writePolicy(client, owner, {
+        mode: opts.mode,
+        allow: patternList(opts.allow),
+        deny: patternList(opts.deny),
+        requirePinned: opts.requirePinned === true,
+    });
+    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('✔')} ${owner}: ${policyLine(outcome.value)}`);
+});
+const pinCommand = new Command('pin')
+    .description('Propose pinning every action to the commit its version points at')
+    .argument('<repository>', 'owner/repo')
+    .option('--apply', 'open the pull request; without this the change is only printed')
+    .option('--json', 'machine-readable output')
+    .action(async (slug, opts) => {
+    const target = repository(slug);
+    if (!target)
+        return;
+    const client = api();
+    if (!client)
+        return;
+    const apply = opts.apply === true;
+    const outcome = await proposePins(client, target, apply);
+    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
+        printProposal(outcome.value, apply);
+});
+export default new Command('actions')
+    .description('The action supply chain: what a repository pulls in, the policy over it, and pinning')
+    .addCommand(listCommand)
+    .addCommand(policyCommand)
+    .addCommand(pinCommand);

package/dist/cli/approval/main.js

@@ -0,0 +1,76 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { decideRun, listWaitingRuns, waitingSummary, } from '../../src/application/manage-approvals.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 printWaiting = (runs) => {
+    if (runs.length === 0) {
+        console.log(chalk.green('Nothing is waiting for approval.'));
+        return;
+    }
+    console.log(chalk.bold(['RUN', 'WHAT', 'WHY'].join('  ')));
+    for (const r of runs)
+        console.log([r.id, waitingSummary(r), r.why].join('  '));
+};
+const listCommand = new Command('list')
+    .description('Runs from a fork waiting for somebody with write access to approve them')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await listWaitingRuns(client);
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.detail));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json === true) {
+        console.log(JSON.stringify({ runs: outcome.runs }, null, 2));
+        return;
+    }
+    printWaiting(outcome.runs);
+});
+const decide = (verb) => new Command(verb)
+    .description(verb === 'approve'
+    ? 'Approve one run from a fork — it starts with no secrets and on a runner of its own'
+    : 'Reject one run from a fork — every job fails and the attempt is closed')
+    .argument('<run-id>', 'run id (apex approval list prints them)')
+    .option('--comment <text>', 'recorded with the decision')
+    .action(async (runId, opts) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await decideRun(client, runId, verb === 'approve' ? 'approved' : 'rejected', opts.comment);
+    switch (outcome.kind) {
+        case 'not-found':
+            console.error(chalk.red(`No run ${runId}.`));
+            process.exitCode = 1;
+            return;
+        case 'refused':
+            console.error(chalk.red(outcome.detail));
+            process.exitCode = 1;
+            return;
+        case 'decided':
+            // Say what approving *did*, not only that it happened: the next
+            // question is always "so does it have my secrets now", and the
+            // answer is no.
+            console.log(verb === 'approve'
+                ? chalk.green(`Approved ${outcome.decision.runId}. It runs with no secrets, a read-only token, and a runner of its own.`)
+                : chalk.yellow(`Rejected ${outcome.decision.runId}. Its jobs are closed as failed.`));
+    }
+});
+export default new Command('approval')
+    .description('Runs from forks: what is waiting, and deciding it (ADR-0024)')
+    .addCommand(listCommand)
+    .addCommand(decide('approve'))
+    .addCommand(decide('reject'));

package/dist/cli/artifact/main.js

@@ -0,0 +1,115 @@
+import { createWriteStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { basename, resolve } from 'node:path';
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { deleteArtifact, downloadArtifact, listArtifacts, untilExpiry, } from '../../src/application/manage-artifacts.js';
+import { humanBytes } from '../../src/application/manage-caches.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.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 printArtifacts = (artifacts, totalSizeBytes) => {
+    if (artifacts.length === 0) {
+        console.log(chalk.yellow('No artifacts. The first workflow to run `actions/upload-artifact` will create one.'));
+        return;
+    }
+    console.log(chalk.bold(['ID', 'SIZE', 'EXPIRES', 'NAME'].join('  ')));
+    for (const a of artifacts) {
+        console.log([String(a.id), humanBytes(a.sizeBytes), untilExpiry(a.expiresAt), a.name].join('  '));
+    }
+    // Nothing renews retention, so the column above is a countdown rather than a
+    // property — say so instead of leaving it to be discovered.
+    console.log(chalk.dim(`\n${artifacts.length} artifact(s), ${humanBytes(totalSizeBytes)}. Retention is not renewed: an expired artifact is deleted with its bytes.`));
+};
+const listCommand = new Command('list')
+    .description('Artifacts a run or a repository holds, newest first')
+    .argument('<target>', 'run id, or owner/repo')
+    .option('--json', 'machine-readable output')
+    .action(async (target, opts) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await listArtifacts(client, target);
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.detail));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json === true) {
+        console.log(JSON.stringify({ artifacts: outcome.artifacts, totalSizeBytes: outcome.totalSizeBytes }, null, 2));
+        return;
+    }
+    printArtifacts(outcome.artifacts, outcome.totalSizeBytes);
+});
+const downloadCommand = new Command('download')
+    .description('Download one artifact of a run as a zip')
+    .argument('<run>', 'run id')
+    .argument('[name]', 'artifact name (optional when the run produced exactly one)')
+    .option('-o, --output <path>', 'where to write the zip (default: <name>.zip here)')
+    .action(async (runId, name, opts) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await downloadArtifact(client, runId, name);
+    switch (outcome.kind) {
+        case 'not-found':
+            console.error(chalk.red(`run ${runId} has no artifact named ${outcome.name}`));
+            process.exitCode = 1;
+            return;
+        case 'ambiguous':
+            // Guessing here would silently write the wrong zip to the right path.
+            console.error(chalk.red(`run ${runId} has ${outcome.names.length} artifacts; name one of: ${outcome.names.join(', ')}`));
+            process.exitCode = 2;
+            return;
+        case 'refused':
+            console.error(chalk.red(outcome.detail));
+            process.exitCode = 1;
+            return;
+        case 'downloaded': {
+            const target = resolve(opts.output ?? `${basename(outcome.artifact.name)}.zip`);
+            await pipeline(Readable.from(outcome.body), createWriteStream(target));
+            console.log(`${chalk.green('✔')} ${outcome.artifact.name} → ${target} (${humanBytes(outcome.artifact.sizeBytes)})`);
+        }
+    }
+});
+const deleteCommand = new Command('delete')
+    .description('Delete one artifact by id')
+    .argument('<run>', 'run id')
+    .argument('<id>', 'artifact id (apex artifact list prints them)')
+    .action(async (runId, id) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await deleteArtifact(client, runId, id);
+    switch (outcome.kind) {
+        case 'bad-id':
+            console.error(chalk.red(`artifact ids are positive whole numbers, got ${JSON.stringify(outcome.given)}`));
+            process.exitCode = 2;
+            return;
+        case 'not-found':
+            console.error(chalk.red(`no artifact ${outcome.id} in run ${runId}`));
+            process.exitCode = 1;
+            return;
+        case 'refused':
+            console.error(chalk.red(outcome.detail));
+            process.exitCode = 1;
+            return;
+        case 'deleted':
+            console.log(`${chalk.green('✔')} artifact ${id} deleted`);
+    }
+});
+export default new Command('artifact')
+    .description('Artifacts: what a run produced, getting it out, and dropping one')
+    .addCommand(listCommand)
+    .addCommand(downloadCommand)
+    .addCommand(deleteCommand);

package/dist/cli/cache/main.js

@@ -0,0 +1,104 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { deleteCache, humanBytes, listCaches, splitRepository } from '../../src/application/manage-caches.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.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 repository = (slug) => {
+    const parsed = splitRepository(slug);
+    if (parsed)
+        return parsed;
+    console.error(chalk.red(`expected owner/repo, got ${JSON.stringify(slug)}`));
+    process.exitCode = 2;
+    return undefined;
+};
+const age = (iso) => {
+    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`;
+    if (seconds < 172_800)
+        return `${Math.round(seconds / 3600)}h`;
+    return `${Math.round(seconds / 86_400)}d`;
+};
+const printCaches = (caches, totalSizeBytes) => {
+    if (caches.length === 0) {
+        console.log(chalk.yellow('No caches. The first workflow to run `actions/cache` will create one.'));
+        return;
+    }
+    console.log(chalk.bold(['ID', 'SIZE', 'USED', 'REF', 'KEY'].join('  ')));
+    for (const c of caches) {
+        console.log([String(c.id), humanBytes(c.sizeBytes), age(c.lastAccessedAt), c.ref, c.key].join('  '));
+    }
+    // The list is newest-used first, so the bottom row is what eviction takes
+    // next. Say so rather than making people infer it from the column.
+    console.log(chalk.dim(`\n${caches.length} cache(s), ${humanBytes(totalSizeBytes)}. Least recently used is last, and goes first when the quota is reached.`));
+};
+const listCommand = new Command('list')
+    .description('Caches a repository holds, most recently used first')
+    .argument('<repository>', 'owner/repo')
+    .option('--json', 'machine-readable output')
+    .action(async (slug, opts) => {
+    const target = repository(slug);
+    if (!target)
+        return;
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await listCaches(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({ caches: outcome.caches, totalSizeBytes: outcome.totalSizeBytes }, null, 2));
+        return;
+    }
+    printCaches(outcome.caches, outcome.totalSizeBytes);
+});
+const deleteCommand = new Command('delete')
+    .description('Delete one cache entry by id')
+    .argument('<repository>', 'owner/repo')
+    .argument('<id>', 'cache id (apex cache list prints them)')
+    .action(async (slug, id) => {
+    const target = repository(slug);
+    if (!target)
+        return;
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await deleteCache(client, target.owner, target.repo, id);
+    switch (outcome.kind) {
+        case 'bad-id':
+            console.error(chalk.red(`cache ids are positive whole numbers, got ${JSON.stringify(outcome.given)}`));
+            process.exitCode = 2;
+            return;
+        case 'not-found':
+            console.error(chalk.red(`no cache ${outcome.id} in ${slug}`));
+            process.exitCode = 1;
+            return;
+        case 'refused':
+            console.error(chalk.red(outcome.detail));
+            process.exitCode = 1;
+            return;
+        case 'deleted':
+            // The stored bytes may survive: another entry can point at the same
+            // content. Saying "deleted" of the entry is the honest claim.
+            console.log(`${chalk.green('✔')} cache ${id} deleted`);
+    }
+});
+export default new Command('cache')
+    .description('Caches: what a repository holds, and dropping an entry')
+    .addCommand(listCommand)
+    .addCommand(deleteCommand);

package/dist/cli/deployment/main.js

@@ -0,0 +1,73 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { decideDeployment, deploymentSummary, listDeployments, } from '../../src/application/manage-environments.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 printDeployments = (deployments, scoped) => {
+    if (deployments.length === 0) {
+        console.log(chalk.yellow(scoped ? 'This run deployed nowhere.' : 'Nothing is waiting for approval.'));
+        return;
+    }
+    console.log(chalk.bold(['ID', 'ENVIRONMENT', 'STATUS', 'WHY'].join('  ')));
+    for (const d of deployments)
+        console.log([d.id, d.environment, d.status, deploymentSummary(d)].join('  '));
+};
+const listCommand = new Command('list')
+    .description('Deployments waiting for approval, or every deployment of one run')
+    .option('--run <id>', 'one run, in the order it deployed')
+    .option('--json', 'machine-readable output')
+    .action(async (opts) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await listDeployments(client, opts.run);
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.detail));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json === true) {
+        console.log(JSON.stringify({ deployments: outcome.deployments }, null, 2));
+        return;
+    }
+    printDeployments(outcome.deployments, opts.run !== undefined);
+});
+const decide = (verb) => new Command(verb)
+    .description(verb === 'approve' ? 'Approve one waiting deployment' : 'Reject one waiting deployment')
+    .argument('<id>', 'deployment id (apex deployment list prints them)')
+    .option('--comment <text>', 'recorded with the decision')
+    .action(async (id, opts) => {
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await decideDeployment(client, id, verb === 'approve' ? 'approved' : 'rejected', opts.comment);
+    switch (outcome.kind) {
+        case 'not-found':
+            console.error(chalk.red(`no deployment ${id}`));
+            process.exitCode = 1;
+            return;
+        case 'refused':
+            // Whether this caller may decide is the environment's question, and
+            // the answer names the environment. Print it as it came.
+            console.error(chalk.red(outcome.detail));
+            process.exitCode = 1;
+            return;
+        case 'decided':
+            console.log(`${chalk.green('✔')} ${outcome.deployment.environment} ${verb === 'approve' ? 'approved' : 'rejected'}`);
+            console.log(chalk.dim(`run ${outcome.deployment.runId}`));
+    }
+});
+export default new Command('deployment')
+    .description('Deployments: what is waiting for an approval, and giving one')
+    .addCommand(listCommand)
+    .addCommand(decide('approve'))
+    .addCommand(decide('reject'));

package/dist/cli/dispatch/main.js

@@ -0,0 +1,47 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { dispatchWorkflow } from '../../src/application/dispatch-workflow.js';
+import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+const handler = async (workflow, options) => {
+    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 dispatchWorkflow(api, {
+        repository: options.repo,
+        workflow,
+        ref: options.ref ?? 'main',
+        inputs: options.input ?? [],
+    });
+    switch (outcome.kind) {
+        case 'bad-repository':
+            console.error(chalk.red(`--repo must be owner/repo, got ${outcome.given}`));
+            process.exitCode = 2;
+            return;
+        case 'bad-inputs':
+            console.error(chalk.red(`--input must be name=value: ${outcome.invalid.join(', ')}`));
+            process.exitCode = 2;
+            return;
+        case 'refused':
+            // The API's own words: unknown repository, disabled workflow, a required
+            // input left out. Nothing is re-worded here.
+            console.error(chalk.red(outcome.detail));
+            process.exitCode = 1;
+            return;
+        case 'dispatched':
+            console.log(`${chalk.green('✔')} dispatched ${workflow} on ${options.ref ?? 'main'}`);
+            console.log(chalk.dim(`delivery ${outcome.deliveryId} — follow it with: apex logs latest --repo ${options.repo} --follow`));
+    }
+};
+export default new Command('dispatch')
+    .description('Trigger workflow_dispatch with typed inputs')
+    .argument('<workflow>', 'workflow file path or name, e.g. .github/workflows/deploy.yml')
+    .requiredOption('--repo <owner/repo>', 'repository to dispatch in')
+    .option('--ref <ref>', 'branch or tag to run against, as on GitHub (a commit SHA is refused)', 'main')
+    .option('--input <name=value...>', 'workflow_dispatch input, repeatable')
+    .action(handler);