@apex-actions/cli 0.67.0

package/dist/src/application/manage-environments.js

@@ -0,0 +1,136 @@
+// application layer — see ../../../../docs/conventions.md §1
+const refused = (err) => ({ kind: 'refused', detail: err instanceof Error ? err.message : String(err) });
+export const listEnvironments = async (api, owner, repo) => {
+    try {
+        const { environments } = await api.listEnvironments(owner, repo);
+        return { kind: 'listed', environments: [...environments].sort((a, b) => (a.name < b.name ? -1 : 1)) };
+    }
+    catch (err) {
+        return refused(err);
+    }
+};
+export const saveEnvironment = async (api, owner, repo, name, input) => {
+    try {
+        return { kind: 'saved', environment: await api.putEnvironment(owner, repo, name, input) };
+    }
+    catch (err) {
+        return refused(err);
+    }
+};
+export const deleteEnvironment = async (api, owner, repo, name) => {
+    try {
+        return (await api.deleteEnvironment(owner, repo, name)) ? { kind: 'deleted' } : { kind: 'not-found' };
+    }
+    catch (err) {
+        return refused(err);
+    }
+};
+/**
+ * `user:ana`, `team:acme/platform`, or a bare name (a user, because that is
+ * what people mean when they type one).
+ */
+export const parseReviewer = (raw) => {
+    const [head, ...rest] = raw.split(':');
+    if (head === undefined || head === '')
+        return undefined;
+    if (rest.length === 0)
+        return { type: 'user', name: head };
+    const name = rest.join(':');
+    if (name === '')
+        return undefined;
+    if (head === 'user')
+        return { type: 'user', name };
+    if (head === 'team')
+        return name.includes('/') ? { type: 'team', name } : undefined;
+    return undefined;
+};
+export const listDeployments = async (api, runId) => {
+    try {
+        const { deployments } = runId === undefined ? await api.listWaitingDeployments() : await api.listRunDeployments(runId);
+        return { kind: 'listed', deployments };
+    }
+    catch (err) {
+        return refused(err);
+    }
+};
+export const decideDeployment = async (api, id, decision, comment) => {
+    try {
+        const deployment = await api.decideDeployment(id, decision, comment);
+        return deployment === undefined ? { kind: 'not-found' } : { kind: 'decided', deployment };
+    }
+    catch (err) {
+        return refused(err);
+    }
+};
+export const listSchedules = async (api, owner, repo) => {
+    try {
+        const { schedules } = await api.listSchedules(owner, repo);
+        return { kind: 'listed', schedules: [...schedules].sort((a, b) => Date.parse(a.nextRunAt) - Date.parse(b.nextRunAt)) };
+    }
+    catch (err) {
+        return refused(err);
+    }
+};
+export const oidcDiscovery = async (api) => {
+    try {
+        const document = await api.oidcDiscovery();
+        return document === undefined ? { kind: 'not-an-issuer' } : { kind: 'found', document };
+    }
+    catch (err) {
+        return refused(err);
+    }
+};
+export const oidcSubject = async (api, owner, repo) => {
+    try {
+        const { includeClaimKeys } = await api.getOidcSubject(owner, repo);
+        return { kind: 'read', includeClaimKeys };
+    }
+    catch (err) {
+        return refused(err);
+    }
+};
+export const setOidcSubject = async (api, owner, repo, keys) => {
+    try {
+        const { includeClaimKeys } = await api.putOidcSubject(owner, repo, keys);
+        return { kind: 'read', includeClaimKeys };
+    }
+    catch (err) {
+        return refused(err);
+    }
+};
+/**
+ * How a deployment reads on one line: what it is waiting for, or how it was
+ * decided. The API records a reason for every state that has one; this only
+ * has to cover the states where it does not.
+ */
+export const deploymentSummary = (d) => {
+    if (d.reason !== undefined && d.reason !== '')
+        return d.reason;
+    switch (d.status) {
+        case 'success':
+            return `deployed to ${d.environment}`;
+        case 'failure':
+            return `the deployment to ${d.environment} failed`;
+        case 'cancelled':
+            return `the deployment to ${d.environment} was cancelled`;
+        case 'rejected':
+            return `the deployment to ${d.environment} was rejected`;
+        default:
+            return `deploying to ${d.environment}`;
+    }
+};
+/** An environment's rules on one line, in the order they are applied. */
+export const environmentSummary = (e) => {
+    const parts = [];
+    if (e.branchPatterns.length > 0)
+        parts.push(`branches ${e.branchPatterns.join(', ')}`);
+    if (e.waitTimerMinutes > 0)
+        parts.push(`wait ${e.waitTimerMinutes}m`);
+    if (e.reviewers.length > 0)
+        parts.push(`reviewers ${e.reviewers.map((r) => `${r.type}:${r.name}`).join(', ')}`);
+    if (e.preventSelfReview)
+        parts.push('no self-review');
+    // An environment with no rules is not a gate at all, and saying so beats an
+    // empty line somebody has to interpret.
+    return parts.length > 0 ? parts.join(' · ') : 'no protection rules';
+};

package/dist/src/application/manage-notifications.js

@@ -0,0 +1,20 @@
+const attempt = async (fn) => {
+    try {
+        return { kind: 'ok', value: await fn() };
+    }
+    catch (err) {
+        return { kind: 'refused', message: err instanceof Error ? err.message : String(err) };
+    }
+};
+export const listRules = async (api, repository) => await attempt(() => api.listNotificationRules(repository));
+export const saveRule = async (api, repository, name, input) => await attempt(() => api.putNotificationRule(repository, name, input));
+export const removeRule = async (api, repository, name) => await attempt(() => api.deleteNotificationRule(repository, name));
+/**
+ * Prove a destination now.
+ *
+ * A refusal by the destination is an `ok` outcome carrying `ok: false`: the
+ * call succeeded and its answer *is* the news. Only a failure to reach the
+ * control plane is `refused` here.
+ */
+export const proveRule = async (api, repository, name) => await attempt(() => api.testNotificationRule(repository, name));
+export const readDeliveries = async (api, repository, limit) => await attempt(() => api.listNotificationDeliveries(repository, limit));

package/dist/src/application/manage-runners.js

@@ -0,0 +1,89 @@
+// application layer — see ../../../../docs/conventions.md §1
+import { reconstructFleet } from '../domain/fleet-history.js';
+/**
+ * List runners *and* what is waiting for them.
+ *
+ * The two together, never separately: "six runners" is not an answer to "why is
+ * my job queued", and the pair is — six runners, none of whose labels satisfy
+ * what you asked for.
+ */
+export const listRunners = async (api) => {
+    try {
+        const [runners, fleet] = await Promise.all([api.listRunners(), api.fleetDemand()]);
+        return { kind: 'listed', runners, demand: fleet.demand };
+    }
+    catch (err) {
+        return { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };
+    }
+};
+/**
+ * How big the fleet was, over a window that has already happened.
+ *
+ * The control plane serves the lifetimes; the arithmetic is `reconstructFleet`,
+ * in the domain, so the two can be wrong separately and are tested separately.
+ */
+export const fleetHistory = async (api, window) => {
+    try {
+        const served = await api.fleetHistory({ since: window.since.toISOString(), until: window.until.toISOString() });
+        // The window the server actually served, not the one we asked for: it
+        // clamps, and a reconstruction laid over the wrong window would invent a
+        // zero stretch at the front of it.
+        return {
+            kind: 'reconstructed',
+            history: reconstructFleet(served.runners, { since: served.since, until: served.until }),
+        };
+    }
+    catch (err) {
+        return { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };
+    }
+};
+/** How many registrations one token may ever grant; the API clamps to the same. */
+export const MAX_TOKEN_USES = 64;
+export const mintRegistrationToken = async (api, uses) => {
+    if (!Number.isInteger(uses) || uses < 1 || uses > MAX_TOKEN_USES)
+        return { kind: 'bad-uses', given: uses };
+    try {
+        return { kind: 'minted', token: await api.mintRegistrationToken({ uses }) };
+    }
+    catch (err) {
+        return { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };
+    }
+};
+/**
+ * Attach this machine to the control plane as a self-hosted runner: mint a
+ * one-time token, then hand off to `apex-runner`, which is the process that
+ * actually leases and executes work.
+ *
+ * The token is minted here rather than asked for on the command line because a
+ * registration token is single-use and short-lived — pasting one is a step that
+ * exists only to be got wrong, and a token on a command line ends up in shell
+ * history.
+ */
+export const registerRunner = async (api, agent, request) => {
+    const labels = request.labels.map((l) => l.trim()).filter((l) => l !== '');
+    // A runner with no labels satisfies `runs-on: []` and nothing else — it would
+    // register, look healthy, and never take a job.
+    if (labels.length === 0)
+        return { kind: 'no-labels' };
+    let token;
+    try {
+        token = (await api.mintRegistrationToken({ uses: 1 })).token;
+    }
+    catch (err) {
+        return { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };
+    }
+    return await agent.register({ ...request, labels, token });
+};
+/**
+ * Deregister a runner. A runner id, not a name: names are not unique and
+ * revoking the wrong runner's credential is not a mistake worth making
+ * convenient. `apex runner list` prints the ids.
+ */
+export const removeRunner = async (api, id) => {
+    try {
+        return (await api.removeRunner(id)) ? { kind: 'removed' } : { kind: 'not-found', id };
+    }
+    catch (err) {
+        return { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };
+    }
+};

package/dist/src/application/manage-secrets.js

@@ -0,0 +1,83 @@
+// application layer — see ../../../../docs/conventions.md §1
+import { targetLabel } from '../domain/secrets.js';
+/**
+ * Why the organisation scope refused: it answers only for the operator
+ * organisation (BUG-0112), and a customer token has no scope there at all.
+ * A bare 403 would read as a permissions problem somebody could fix.
+ */
+export const ORG_SCOPE_REFUSAL = 'organisation secrets are not available to customer organisations yet — set it on each repository with --repo';
+const statusOf = (err) => {
+    const status = err?.status;
+    return typeof status === 'number' ? status : undefined;
+};
+const refused = (target, err) => {
+    if (target.kind === 'org' && statusOf(err) === 403)
+        return { kind: 'refused', detail: ORG_SCOPE_REFUSAL };
+    return { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };
+};
+/**
+ * One value, written to every target in order.
+ *
+ * A refusal on one repository does not stop the others: the etsuite case is
+ * one token onto several repositories, and stopping half-way would leave the
+ * person to work out which half. The summary says, per target.
+ */
+export const setEverywhere = async (api, kind, targets, name, value) => {
+    const results = [];
+    for (const target of targets) {
+        try {
+            await (kind === 'secret' ? api.setSecret(target, name, value) : api.setVariable(target, name, value));
+            results.push({ target: targetLabel(target), kind: 'set' });
+        }
+        catch (err) {
+            results.push({ target: targetLabel(target), ...refused(target, err) });
+        }
+    }
+    return results;
+};
+export const deleteEverywhere = async (api, kind, targets, name) => {
+    const results = [];
+    for (const target of targets) {
+        try {
+            const existed = await (kind === 'secret' ? api.deleteSecret(target, name) : api.deleteVariable(target, name));
+            results.push({ target: targetLabel(target), kind: existed ? 'deleted' : 'not-found' });
+        }
+        catch (err) {
+            results.push({ target: targetLabel(target), ...refused(target, err) });
+        }
+    }
+    return results;
+};
+/** §7 exit code for a batch: 0 all done, 3 something was not there to delete, 1 anything refused. */
+export const batchExitCode = (results) => {
+    if (results.some((r) => r.kind === 'refused'))
+        return 1;
+    if (results.some((r) => r.kind === 'not-found'))
+        return 3;
+    return 0;
+};
+export const listSecrets = async (api, target) => {
+    try {
+        const secrets = await api.listSecrets(target);
+        // Names and dates only, rebuilt field by field: a response that grew a
+        // value would still not carry it past here.
+        return {
+            kind: 'listed',
+            secrets: secrets
+                .map((s) => ({ name: s.name, ...(s.updatedAt === undefined ? {} : { updatedAt: s.updatedAt }) }))
+                .sort((a, b) => (a.name < b.name ? -1 : 1)),
+        };
+    }
+    catch (err) {
+        return refused(target, err);
+    }
+};
+export const listVariables = async (api, target) => {
+    try {
+        const variables = await api.listVariables(target);
+        return { kind: 'listed', variables: [...variables].sort((a, b) => (a.name < b.name ? -1 : 1)) };
+    }
+    catch (err) {
+        return refused(target, err);
+    }
+};

package/dist/src/application/manage-terms.js

@@ -0,0 +1,34 @@
+const attempt = async (fn) => {
+    try {
+        return { kind: 'ok', value: await fn() };
+    }
+    catch (err) {
+        return { kind: 'refused', message: err instanceof Error ? err.message : String(err) };
+    }
+};
+/**
+ * Who owes an acceptance of the terms in force.
+ *
+ * The API answers what *this caller* may act for; the CLI authenticates as the
+ * machine principal, which administers every account, so an operator sees the
+ * whole list. Nothing is classified here — outstanding is the control plane's
+ * judgement (control-plane ADR-0039 amendment 1) and a second one would be a
+ * second answer to a question that must have one.
+ */
+export const readTermsStanding = async (api) => await attempt(() => api.termsStanding());
+/**
+ * Accept for one account, **as the machine token**.
+ *
+ * This is the escalation path and nothing else: the customer accepts for
+ * themselves, in the app, at their next sign-in. An operator does it only on a
+ * customer's written instruction — for an account whose only owner has left —
+ * and the row then says the machine token accepted, which is exactly as much
+ * as it should claim.
+ *
+ * The version is read immediately before it is sent, never assumed: the same
+ * rule the screen follows, for the same reason.
+ */
+export const acceptTermsFor = async (api, installationId) => await attempt(async () => {
+    const standing = await api.termsStanding();
+    return await api.acceptTerms(installationId, standing.version);
+});

package/dist/src/application/read-logs.js

@@ -0,0 +1,40 @@
+// application layer — see ../../../../docs/conventions.md §1
+import { isLive, selectJobs } from '../domain/runs.js';
+import { resolveRunId } from './resolve-run.js';
+/**
+ * Fetch (and optionally follow) a run's logs.
+ *
+ * Following re-reads rather than streaming: a job's log is compacted when it
+ * finishes, so the whole text is always the truth, and re-reading it cannot
+ * produce the interleaving bugs that stitching chunks can.
+ */
+export const readLogs = async (api, sleeper, request) => {
+    const resolved = await resolveRunId(api, request);
+    if (resolved.kind !== 'run')
+        return resolved;
+    let detail = await api.getRun(resolved.id);
+    if (!detail)
+        return { kind: 'unknown-run', selector: request.run };
+    const wanted = selectJobs(detail.jobs, request.job);
+    if (wanted.length === 0) {
+        return { kind: 'unknown-job', selector: request.job ?? '', available: detail.jobs.map((j) => j.name) };
+    }
+    while (request.follow === true && isLive(detail.run.status)) {
+        await sleeper.sleep(request.pollMs ?? 3000);
+        const fresh = await api.getRun(resolved.id);
+        if (!fresh)
+            break;
+        detail = fresh;
+    }
+    const jobs = selectJobs(detail.jobs, request.job);
+    const sections = [];
+    for (const job of jobs)
+        sections.push({ job, text: await api.jobLogs(job.id) });
+    return {
+        kind: 'logs',
+        run: detail.run,
+        sections,
+        // A live run has not failed yet; only a finished one sets a failing code.
+        exitCode: isLive(detail.run.status) ? 0 : detail.run.conclusion === 'success' ? 0 : 1,
+    };
+};

package/dist/src/application/report-spend.js

@@ -0,0 +1,15 @@
+/**
+ * Fetch a spend report.
+ *
+ * No selection logic and no arithmetic: the comparison's rules live in the
+ * control plane's domain, and a second implementation here would be a second
+ * answer to a question that must have one.
+ */
+export const reportSpend = async (api, request) => {
+    try {
+        return { kind: 'report', report: await api.spend(request.repository, request.days) };
+    }
+    catch (err) {
+        return { kind: 'refused', message: err instanceof Error ? err.message : String(err) };
+    }
+};

package/dist/src/application/rerun-runs.js

@@ -0,0 +1,34 @@
+import { resolveRunId } from './resolve-run.js';
+/**
+ * Re-run a completed run, optionally resuming each job from the step it failed
+ * at.
+ *
+ * The snapshots are read **before** the re-run rather than reported after it,
+ * so the caller can be told what will actually be skipped. A `--resume` that
+ * silently found nothing to resume from would look identical to one that
+ * worked, and the difference is several minutes of somebody's afternoon.
+ */
+export const rerunRun = async (api, request) => {
+    if (request.mode === 'job' && (request.jobId === undefined || request.jobId === '')) {
+        return { kind: 'needs-job' };
+    }
+    const resolved = await resolveRunId(api, request);
+    if (resolved.kind !== 'run')
+        return resolved;
+    const resuming = request.resume ? await api.runSnapshots(resolved.id) : [];
+    try {
+        const { runId } = await api.rerun(resolved.id, {
+            mode: request.mode,
+            ...(request.jobId !== undefined ? { jobId: request.jobId } : {}),
+            debug: request.debug,
+            resume: request.resume,
+        });
+        return { kind: 'started', runId, resuming };
+    }
+    catch (err) {
+        // Everything the API can refuse — a run still in progress, a job that is
+        // not part of it, a run with no plan — comes back in its words rather than
+        // being re-guessed here.
+        return { kind: 'refused', message: err instanceof Error ? err.message : String(err) };
+    }
+};

package/dist/src/application/resolve-run.js

@@ -0,0 +1,19 @@
+// application layer — see ../../../../docs/conventions.md §1
+import { isRunId, selectRun } from '../domain/runs.js';
+/**
+ * Resolve a selector to a run id.
+ *
+ * An id is returned **without listing anything**. Whether it exists is then
+ * settled by the call the caller was going to make anyway, which 404s on a run
+ * that is really absent — so nothing is lost by not checking twice, and the
+ * horizon is gone.
+ */
+export const resolveRunId = async (api, request) => {
+    if (isRunId(request.run))
+        return { kind: 'run', id: request.run.trim() };
+    const runs = await api.listRuns(request.repository);
+    if (runs.length === 0)
+        return { kind: 'no-runs' };
+    const selected = selectRun(runs, request.run);
+    return selected === undefined ? { kind: 'unknown-run', selector: request.run } : { kind: 'run', id: selected.id };
+};

package/dist/src/application/run-workflow.js

@@ -0,0 +1,17 @@
+/**
+ * Run the given workflow, or the repository's only workflow when none is
+ * named. More than one candidate is an error — the runner executes exactly
+ * one file per invocation.
+ */
+export const runWorkflow = async (runner, locator, workflow, options) => {
+    let target = workflow;
+    if (target === undefined) {
+        const candidates = await locator.defaultWorkflows();
+        if (candidates.length === 0)
+            return { kind: 'no-workflows' };
+        if (candidates.length > 1)
+            return { kind: 'ambiguous', candidates };
+        target = candidates[0];
+    }
+    return await runner.run({ ...options, workflow: target });
+};

package/dist/src/application/scan-migration.js

@@ -0,0 +1,76 @@
+// application layer — see ../../../../docs/conventions.md §1
+import { buildChecklist, migrationVerdict, } from '../domain/migration.js';
+/**
+ * Scan an organization: find its workflows, ask the engine what runs, and turn
+ * the secret and variable names into a checklist.
+ *
+ * The three steps are separate ports because they fail differently and a
+ * migration report is most useful when a partial answer still arrives. No
+ * repositories, no workflows and no engine are each their own outcome rather
+ * than an exception, and the checklist degrades to "could not be read" rather
+ * than to an empty list that looks complete.
+ */
+export const scanOrganization = async (deps, org, options = {}) => {
+    let summaries;
+    try {
+        summaries =
+            options.repos !== undefined && options.repos.length > 0
+                ? options.repos.map((slug) => ({ slug, archived: false }))
+                : await deps.workflows.repositories(org);
+    }
+    catch (err) {
+        return { kind: 'refused', message: message(err) };
+    }
+    if (summaries.length === 0)
+        return { kind: 'no-repositories', organization: org };
+    const archived = summaries.filter((r) => r.archived).map((r) => r.slug);
+    const repositories = summaries.filter((r) => !r.archived).map((r) => r.slug);
+    if (repositories.length === 0)
+        return { kind: 'no-repositories', organization: org };
+    const documents = [];
+    const withoutWorkflows = [];
+    for (const repo of repositories) {
+        let found;
+        try {
+            found = await deps.workflows.workflows(repo);
+        }
+        catch (err) {
+            return { kind: 'refused', message: message(err) };
+        }
+        if (found.length === 0)
+            withoutWorkflows.push(repo);
+        documents.push(...found);
+    }
+    if (documents.length === 0)
+        return { kind: 'no-workflows', organization: org, repositories };
+    const result = await deps.checker.assess(org, documents);
+    if (result.kind === 'engine-missing')
+        return result;
+    const report = result.report;
+    // undefined, not [], when nobody could read them: an empty checklist that
+    // looks complete is the failure this distinction exists to prevent.
+    let configured;
+    if (options.includeNames === true && deps.names !== undefined) {
+        try {
+            configured = await deps.names.configuredNames(org, repositories);
+        }
+        catch {
+            configured = undefined;
+        }
+    }
+    const verdict = migrationVerdict(report);
+    return {
+        kind: 'scan',
+        ok: verdict !== 'blocked' && verdict !== 'incomplete',
+        scan: {
+            organization: org,
+            repositories,
+            report,
+            checklist: buildChecklist(report.references, configured),
+            verdict,
+            withoutWorkflows,
+            archived,
+        },
+    };
+};
+const message = (err) => (err instanceof Error ? err.message : String(err));

package/dist/src/application/search-logs.js

@@ -0,0 +1,24 @@
+/**
+ * Search a repository's logs.
+ *
+ * No filtering and no matching here: the scan's rules and its bounds live in
+ * the control plane, which is the only place that can enforce them, and a
+ * second implementation would be a second answer.
+ */
+export const searchLogs = async (api, repository, query) => {
+    try {
+        return { kind: 'report', report: await api.searchLogs(repository, query) };
+    }
+    catch (err) {
+        return { kind: 'refused', message: err instanceof Error ? err.message : String(err) };
+    }
+};
+/** The structured reading of one job's log, for `apex logs --summary`. */
+export const readLogView = async (api, jobId) => {
+    try {
+        return { kind: 'view', view: await api.jobLogView(jobId) };
+    }
+    catch (err) {
+        return { kind: 'refused', message: err instanceof Error ? err.message : String(err) };
+    }
+};

package/dist/src/application/serve-language-server.js

@@ -0,0 +1,15 @@
+// application layer — see ../../../../docs/conventions.md §1
+/**
+ * Run the language server until the editor closes the connection.
+ *
+ * The one decision here is that a missing engine binary is reported as itself
+ * rather than as a crash: an editor that starts a language server and gets a
+ * non-zero exit shows "the server crashed", which sends somebody looking in the
+ * wrong place. The message names the binary and the variable that overrides it.
+ */
+export const serveLanguageServer = async (host) => {
+    const { code, missing } = await host.serve();
+    if (missing !== undefined)
+        return { kind: 'engine-missing', message: missing };
+    return { kind: 'exited', code };
+};

package/dist/src/application/validate-workflows.js

@@ -0,0 +1,12 @@
+// application layer — see ../../../../docs/conventions.md §1
+import { hasErrors } from '../domain/validation.js';
+/** Validate the given files, or every workflow the locator finds. */
+export const validateWorkflows = async (validator, locator, files) => {
+    const targets = files.length > 0 ? files : await locator.defaultWorkflows();
+    if (targets.length === 0)
+        return { kind: 'no-workflows' };
+    const result = await validator.validate(targets);
+    if (result.kind === 'engine-missing')
+        return result;
+    return { kind: 'report', report: result.report, ok: !hasErrors(result.report) };
+};