@apex-actions/cli 0.67.0

package/dist/cli/environment/main.js

@@ -0,0 +1,139 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { deleteEnvironment, environmentSummary, listEnvironments, parseReviewer, saveEnvironment, } from '../../src/application/manage-environments.js';
+import { 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 printEnvironments = (environments) => {
+    if (environments.length === 0) {
+        console.log(chalk.yellow('No environments are protected. A workflow may still name one; nothing will gate it.'));
+        return;
+    }
+    console.log(chalk.bold(['ENVIRONMENT', 'RULES'].join('  ')));
+    for (const e of environments)
+        console.log([e.name, environmentSummary(e)].join('  '));
+};
+const listCommand = new Command('list')
+    .description('Environments this repository protects, and how')
+    .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 listEnvironments(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({ environments: outcome.environments }, null, 2));
+        return;
+    }
+    printEnvironments(outcome.environments);
+});
+const setCommand = new Command('set')
+    .description('Create or update an environment protection rule (repository admin)')
+    .argument('<repository>', 'owner/repo')
+    .argument('<name>', 'environment name, as the workflow spells it')
+    .option('--wait-timer <minutes>', 'delay before the job may start; 0 removes it', (v) => Number(v))
+    .option('--reviewer <who...>', 'user:<login>, team:<org/slug>, or a bare login (a user)')
+    .option('--branch-pattern <glob...>', 'refs permitted to deploy here (main, releases/*, v?.0)')
+    .option('--prevent-self-review', 'refuse an approval from whoever triggered the run')
+    .option('--allow-self-review', 'permit it (the default)')
+    .action(async (slug, name, opts) => {
+    const target = repository(slug);
+    if (!target)
+        return;
+    if (opts.waitTimer !== undefined && (!Number.isSafeInteger(opts.waitTimer) || opts.waitTimer < 0)) {
+        console.error(chalk.red('--wait-timer takes a whole number of minutes'));
+        process.exitCode = 2;
+        return;
+    }
+    let reviewers;
+    if (opts.reviewer !== undefined) {
+        reviewers = [];
+        for (const raw of opts.reviewer) {
+            const parsed = parseReviewer(raw);
+            if (!parsed) {
+                console.error(chalk.red(`expected user:<login>, team:<org/slug> or a bare login, got ${JSON.stringify(raw)}`));
+                process.exitCode = 2;
+                return;
+            }
+            reviewers.push(parsed);
+        }
+    }
+    // Unspecified stays unspecified: the API keeps whatever is stored, so
+    // adding a wait timer does not silently clear the reviewers.
+    const input = {
+        ...(opts.waitTimer !== undefined ? { waitTimerMinutes: opts.waitTimer } : {}),
+        ...(reviewers !== undefined ? { reviewers } : {}),
+        ...(opts.branchPattern !== undefined ? { branchPatterns: opts.branchPattern } : {}),
+        ...(opts.preventSelfReview === true ? { preventSelfReview: true } : opts.allowSelfReview === true ? { preventSelfReview: false } : {}),
+    };
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await saveEnvironment(client, target.owner, target.repo, name, input);
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.detail));
+        process.exitCode = 1;
+        return;
+    }
+    console.log(`${chalk.green('✔')} ${outcome.environment.name}: ${environmentSummary(outcome.environment)}`);
+});
+const deleteCommand = new Command('delete')
+    .description('Remove an environment protection rule (repository admin)')
+    .argument('<repository>', 'owner/repo')
+    .argument('<name>', 'environment name')
+    .action(async (slug, name) => {
+    const target = repository(slug);
+    if (!target)
+        return;
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await deleteEnvironment(client, target.owner, target.repo, name);
+    switch (outcome.kind) {
+        case 'not-found':
+            console.error(chalk.red(`no environment ${name} in ${slug}`));
+            process.exitCode = 1;
+            return;
+        case 'refused':
+            console.error(chalk.red(outcome.detail));
+            process.exitCode = 1;
+            return;
+        case 'deleted':
+            // Anything already waiting stays waiting: it was gated by rules that
+            // existed when it was gated (control-plane ADR-0018).
+            console.log(`${chalk.green('✔')} ${name} is no longer protected`);
+            console.log(chalk.dim('Deployments already waiting stay waiting; approve or reject them.'));
+    }
+});
+export default new Command('environment')
+    .description('Environments: the protection rules a workflow can only name')
+    .addCommand(listCommand)
+    .addCommand(setCommand)
+    .addCommand(deleteCommand);

package/dist/cli/login/main.js

@@ -0,0 +1,73 @@
+import { hostname } from 'node:os';
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { login } from '../../src/application/authenticate.js';
+import { TOKENS_PAGE, webBaseFor } from '../../src/domain/credentials.js';
+import { FileCredentialStore, TOKEN_ENV, WEB_URL_ENV, apiUrlFrom, credentialsPath } from '../../src/infrastructure/credentials.js';
+import { HttpLoginExchange, listenForCallback, newPkcePair, openInBrowser } from '../../src/infrastructure/loopback-login.js';
+/**
+ * `apex login`: sign the CLI in with the browser a person already uses
+ * (control-plane ADR-0064, RFC 8252 + PKCE). The token it mints is the same
+ * one the dashboard mints, saved `0600` for this user alone.
+ *
+ * It opens a browser only because it was asked to — this command is the
+ * asking — and prints the URL either way, for a machine where none opens.
+ */
+export default new Command('login')
+    .description('Sign the CLI in through the browser; the token is saved for this user only')
+    .option('--no-browser', 'print the URL to open instead of opening a browser')
+    .action(async (opts) => {
+    const apiUrl = apiUrlFrom();
+    const webBase = webBaseFor(apiUrl, process.env[WEB_URL_ENV]);
+    const store = new FileCredentialStore(credentialsPath());
+    let outcome;
+    try {
+        outcome = await login({
+            pkce: newPkcePair,
+            listen: (state) => listenForCallback(state),
+            openBrowser: opts.browser ? (url) => openInBrowser(url) : undefined,
+            announce: (url) => {
+                console.log(opts.browser ? 'Opening the browser to approve this login. If it does not open, visit:' : 'Open this URL to approve this login:');
+                console.log(`  ${url}`);
+                console.log(chalk.dim('Waiting for the approval (5 minutes)…'));
+            },
+            exchange: new HttpLoginExchange(apiUrl),
+            store,
+            apiUrl,
+            webBase,
+            name: hostname().slice(0, 100) || 'apex CLI',
+        });
+    }
+    catch (err) {
+        console.error(chalk.red(`login failed: ${err instanceof Error ? err.message : String(err)}`));
+        process.exitCode = 1;
+        return;
+    }
+    switch (outcome.kind) {
+        case 'logged-in':
+            console.log(`${chalk.green('✔')} signed in as ${outcome.login} — the token expires ${outcome.expiresAt}`);
+            console.log(chalk.dim(`Saved to ${outcome.location}. Revoke it any time at ${webBase}${TOKENS_PAGE}.`));
+            if (process.env[TOKEN_ENV])
+                console.log(chalk.yellow(`${TOKEN_ENV} is set in this shell and is used before the saved login.`));
+            return;
+        case 'denied':
+            console.error(chalk.red(`the login was not approved: ${outcome.detail}`));
+            process.exitCode = 1;
+            return;
+        case 'state-mismatch':
+            console.error(chalk.red('a callback arrived that this login did not ask for (its state did not match), so nothing was saved; run `apex login` again'));
+            process.exitCode = 1;
+            return;
+        case 'malformed':
+            console.error(chalk.red('the callback carried no code, so nothing was saved; run `apex login` again'));
+            process.exitCode = 1;
+            return;
+        case 'timeout':
+            console.error(chalk.red('no approval arrived within 5 minutes; run `apex login` again'));
+            process.exitCode = 1;
+            return;
+        case 'refused':
+            console.error(chalk.red(`the control plane refused the login code: ${outcome.detail}`));
+            process.exitCode = 1;
+    }
+});

package/dist/cli/logout/main.js

@@ -0,0 +1,43 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { logout } from '../../src/application/authenticate.js';
+import { TOKENS_PAGE, webBaseFor } from '../../src/domain/credentials.js';
+import { HttpControlPlane } from '../../src/infrastructure/control-plane-http.js';
+import { FileCredentialStore, TOKEN_ENV, WEB_URL_ENV, apiUrlFrom, credentialsPath } from '../../src/infrastructure/credentials.js';
+/**
+ * `apex logout`: revoke the token `apex login` saved, then forget it.
+ *
+ * The token is revoked at the control plane that minted it — never at whatever
+ * `APEX_API_URL` says now — with `DELETE /api/v1/me/token`, the one thing a
+ * token may do to itself (control-plane ADR-0064). The file goes whether or not
+ * the server could be reached; when it could not, the command says the token
+ * may still be valid and where to revoke it, rather than implying it is dead.
+ */
+export default new Command('logout')
+    .description('Revoke the token `apex login` saved, and forget it')
+    .action(async () => {
+    const store = new FileCredentialStore(credentialsPath());
+    const tokensPage = `${webBaseFor(apiUrlFrom(), process.env[WEB_URL_ENV])}${TOKENS_PAGE}`;
+    let outcome;
+    try {
+        outcome = await logout(store, (saved) => new HttpControlPlane({ baseUrl: saved.apiUrl, token: saved.token }).revokeCurrentToken());
+    }
+    catch (err) {
+        console.error(chalk.red(`could not remove ${store.location}: ${err instanceof Error ? err.message : String(err)}`));
+        process.exitCode = 1;
+        return;
+    }
+    if (outcome.kind === 'nothing') {
+        console.log(`No saved login at ${outcome.location}; nothing to forget.`);
+    }
+    else if (outcome.revoked === true) {
+        console.log(`${chalk.green('✔')} revoked the saved token and removed ${outcome.location}`);
+    }
+    else {
+        console.log(`${chalk.green('✔')} removed ${outcome.location}`);
+        console.log(chalk.yellow(`The token could not be revoked (${outcome.revoked.failed}) and may still be valid — revoke it at ${tokensPage}.`));
+        process.exitCode = 1;
+    }
+    if (process.env[TOKEN_ENV])
+        console.log(chalk.yellow(`${TOKEN_ENV} is still set in this shell, and the CLI still uses it.`));
+});

package/dist/cli/logs/main.js

@@ -0,0 +1,125 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { readLogs } from '../../src/application/read-logs.js';
+import { readLogView } from '../../src/application/search-logs.js';
+import { HttpControlPlane, NotConfiguredError, RealSleeper } from '../../src/infrastructure/control-plane-http.js';
+import { authorityNote, totalsPhrase } from '../../src/domain/logsearch.js';
+import { parseRepository, unknownRunMessage } from '../../src/domain/runs.js';
+/**
+ * The structured reading of one job's log.
+ *
+ * Every line printed here carries the log line it was read from, because this
+ * is a table of contents into the log rather than a replacement for it: it can
+ * be wrong, and `apex logs --job … | sed -n 'Np'` is the check.
+ */
+const printView = (name, view) => {
+    console.log(chalk.bold(`\n── ${name} ──`));
+    if (view.views.length === 0) {
+        // No summary line from any runner we know: saying nothing is the answer,
+        // because a structured summary that is wrong looks authoritative.
+        console.log(chalk.dim('  no test runner recognised in this log'));
+        return;
+    }
+    for (const tool of view.views) {
+        console.log(`  ${chalk.bold(tool.tool)}  ${totalsPhrase(tool)}  ${chalk.dim(`log line ${tool.line}`)}`);
+        for (const failure of tool.failures) {
+            const where = failure.where === undefined ? '' : chalk.dim(` ${failure.where}`);
+            console.log(`    ${chalk.red('×')} ${failure.name}${where}  ${chalk.dim(`L${failure.line}`)}`);
+            if (failure.message !== undefined)
+                console.log(chalk.dim(`        ${failure.message}`));
+        }
+        if (tool.moreFailures !== undefined)
+            console.log(chalk.dim(`    … ${tool.moreFailures} more failures`));
+    }
+    const note = authorityNote(view);
+    if (note !== undefined)
+        console.log(chalk.dim(`  note: ${note}`));
+};
+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 readLogs(api, new RealSleeper(), {
+            run: run ?? 'latest',
+            repository,
+            job: options.job,
+            follow: options.follow,
+        });
+    }
+    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 'unknown-job':
+            console.error(chalk.red(`no job matches ${outcome.selector}`));
+            console.error(chalk.dim(`jobs in this run: ${outcome.available.join(', ')}`));
+            process.exitCode = 2;
+            return;
+        case 'logs': {
+            if (options.summary === true) {
+                const views = [];
+                for (const section of outcome.sections) {
+                    const read = await readLogView(api, section.job.id);
+                    if (read.kind === 'refused') {
+                        console.error(chalk.red(read.message));
+                        process.exitCode = 2;
+                        return;
+                    }
+                    views.push(read.view);
+                    if (options.json !== true)
+                        printView(section.job.name, read.view);
+                }
+                if (options.json === true)
+                    console.log(JSON.stringify({ run: outcome.run, views }, null, 2));
+                process.exitCode = outcome.exitCode;
+                return;
+            }
+            if (options.json === true) {
+                console.log(JSON.stringify({ run: outcome.run, jobs: outcome.sections.map((s) => ({ job: s.job, log: s.text })) }, null, 2));
+            }
+            else {
+                const many = outcome.sections.length > 1;
+                for (const section of outcome.sections) {
+                    // A header only where it disambiguates; one job's log stays pipeable.
+                    if (many)
+                        console.log(chalk.bold(`\n── ${section.job.name} (${section.job.conclusion ?? section.job.status}) ──`));
+                    process.stdout.write(section.text);
+                }
+            }
+            process.exitCode = outcome.exitCode;
+        }
+    }
+};
+export default new Command('logs')
+    .description('Stream or fetch logs for a run or job')
+    .argument('[run]', 'run id, #number, or "latest"', 'latest')
+    .option('--repo <owner/repo>', 'limit the run search to one repository')
+    .option('--job <name>', 'one job by id, name, or name prefix (default: every job)')
+    .option('--follow', 'keep reading until the run completes')
+    .option('--summary', 'print what the log says about the tests it ran, instead of the log')
+    .option('--json', 'print the run and its logs as JSON')
+    .action(handler);

package/dist/cli/lsp/main.js

@@ -0,0 +1,46 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { serveLanguageServer } from '../../src/application/serve-language-server.js';
+import { EngineBinaryLanguageServer } from '../../src/infrastructure/engine-binary.js';
+/**
+ * `apex lsp` — the language server, for an editor to start.
+ *
+ * It takes no arguments and prints nothing to stdout, because stdout *is* the
+ * protocol: an editor spawns this and talks JSON-RPC down the pipe. Every
+ * message a person is meant to read goes to stderr, which the editor collects
+ * as the server's log.
+ *
+ * There is no `--port`: a language server is a child process, not a service.
+ * Running one for a whole machine would mean deciding whose file it is looking
+ * at, which is a question editors already answered by not asking it.
+ */
+/**
+ * How to wire it in. Exported so a test can hold it to its promises: this is
+ * the only documentation most people will read about the feature, and an
+ * editor name that stops being right is worse than no example.
+ */
+export const EDITOR_HELP = `
+Configure your editor to run this for YAML files under .github/workflows.
+It needs no control plane and no network: the engine parses the buffer in
+front of you.
+
+  VS Code   contributes.languages + a client that spawns \`apex lsp\`
+  Neovim    vim.lsp.start({ cmd = { 'apex', 'lsp' } })
+  Helix     [language-server.apex] command = "apex", args = ["lsp"]
+
+Set APEX_ENGINE_BIN if apex-engine is not on your PATH.`;
+export default new Command('lsp')
+    .description('Run the workflow language server on stdio, for an editor to start as a child process')
+    .addHelpText('after', EDITOR_HELP)
+    .action(async () => {
+    const outcome = await serveLanguageServer(new EngineBinaryLanguageServer());
+    if (outcome.kind === 'engine-missing') {
+        // Named as itself: an editor shows a non-zero exit as "the server
+        // crashed", which sends somebody looking in entirely the wrong place.
+        console.error(chalk.red(outcome.message));
+        process.exitCode = 2;
+        return;
+    }
+    if (outcome.code !== 0)
+        process.exitCode = outcome.code;
+});

package/dist/cli/main.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { Command } from 'commander';
+import Run from './run/main.js';
+import Validate from './validate/main.js';
+import Migrate from './migrate/main.js';
+import Logs from './logs/main.js';
+import Search from './search/main.js';
+import Why from './why/main.js';
+import Reproduce from './reproduce/main.js';
+import Timing from './timing/main.js';
+import Tests from './tests/main.js';
+import Rerun from './rerun/main.js';
+import Spend from './spend/main.js';
+import Dispatch from './dispatch/main.js';
+import Runner from './runner/main.js';
+import Cache from './cache/main.js';
+import Artifact from './artifact/main.js';
+import Environment from './environment/main.js';
+import Deployment from './deployment/main.js';
+import Approval from './approval/main.js';
+import Schedule from './schedule/main.js';
+import Oidc from './oidc/main.js';
+import Actions from './actions/main.js';
+import Terms from './terms/main.js';
+import Notify from './notify/main.js';
+import Lsp from './lsp/main.js';
+import Login from './login/main.js';
+import Logout from './logout/main.js';
+import Whoami from './whoami/main.js';
+import Secret from './secret/main.js';
+import Variable from './variable/main.js';
+/**
+ * The version, from the nearest `package.json` rather than from `VERSION`.
+ *
+ * `VERSION` is the source of truth in the repository, and it is not in the published package —
+ * nor should it be. What ships is `package.json`, npm guarantees it is there, and `version:check`
+ * guarantees it agrees with `VERSION`. Reading it by walking up also survives the layout changing
+ * underfoot: `cli/main.ts` under tsx and `dist/cli/main.js` from a tarball sit at different depths,
+ * and the previous `../VERSION` was correct for exactly one of them.
+ */
+const readVersion = () => {
+    for (let dir = import.meta.dirname;; dir = dirname(dir)) {
+        try {
+            return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version;
+        }
+        catch {
+            if (dirname(dir) === dir)
+                return '0.0.0-unknown';
+        }
+    }
+};
+const version = readVersion();
+const program = new Command()
+    .name('apex')
+    .description('Apex Actions — developer and operator CLI')
+    .version(version)
+    .addCommand(Run)
+    .addCommand(Validate)
+    .addCommand(Migrate)
+    .addCommand(Logs)
+    .addCommand(Search)
+    .addCommand(Why)
+    .addCommand(Reproduce)
+    .addCommand(Timing)
+    .addCommand(Tests)
+    .addCommand(Rerun)
+    .addCommand(Spend)
+    .addCommand(Dispatch)
+    .addCommand(Runner)
+    .addCommand(Cache)
+    .addCommand(Artifact)
+    .addCommand(Environment)
+    .addCommand(Deployment)
+    .addCommand(Approval)
+    .addCommand(Schedule)
+    .addCommand(Oidc)
+    .addCommand(Actions)
+    .addCommand(Terms)
+    .addCommand(Notify)
+    .addCommand(Login)
+    .addCommand(Logout)
+    .addCommand(Whoami)
+    .addCommand(Secret)
+    .addCommand(Variable)
+    .addCommand(Lsp);
+program.parse(process.argv);