@apex-actions/cli 0.86.0 → 0.88.0

package/dist/cli/approval/main.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { decideRun, listWaitingRuns, waitingSummary, } from '../../src/application/manage-approvals.js';
+import { FORK_APPROVAL_DESCRIPTIONS, FORK_APPROVAL_POLICIES, decideRun, forkApprovalPolicy, isForkApprovalPolicy, listWaitingRuns, setForkApprovalPolicy, waitingSummary, } from '../../src/application/manage-approvals.js';
+import { splitRepository } from '../../src/application/manage-caches.js';
 import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
 const api = () => {
     try {
@@ -22,7 +23,7 @@ const printWaiting = (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')
+    .description('Runs from a fork waiting for an Owner or Admin to approve them')
     .option('--json', 'machine-readable output')
     .action(async (opts) => {
     const client = api();
@@ -69,8 +70,52 @@ const decide = (verb) => new Command(verb)
                 : chalk.yellow(`Rejected ${outcome.decision.runId}. Its jobs are closed as failed.`));
     }
 });
+/**
+ * `apex approval policy <owner/repo> [policy]` (TASK-0355): which pull requests from forks wait. Beside `list`,
+ * `approve` and `reject` because it decides what reaches that queue. No policy prints it; one sets it, which takes
+ * an Owner or Admin (administration:write) — it decides whose code starts unread — and is audited by the control plane.
+ */
+const policyCommand = new Command('policy')
+    .description('Which pull requests from forks wait for approval on a repository; with a policy, set it (an Owner or Admin)')
+    .argument('<repository>', 'owner/repo')
+    .argument('[policy]', `one of ${FORK_APPROVAL_POLICIES.join(', ')}`)
+    .option('--json', 'machine-readable output')
+    .action(async (slug, policy, opts) => {
+    const target = splitRepository(slug);
+    if (!target) {
+        console.error(chalk.red(`expected owner/repo, got ${JSON.stringify(slug)}`));
+        process.exitCode = 2;
+        return;
+    }
+    if (policy !== undefined && !isForkApprovalPolicy(policy)) {
+        console.error(chalk.red(`unknown policy ${JSON.stringify(policy)}: expected one of ${FORK_APPROVAL_POLICIES.join(', ')}`));
+        process.exitCode = 2;
+        return;
+    }
+    const client = api();
+    if (!client)
+        return;
+    const outcome = policy === undefined
+        ? await forkApprovalPolicy(client, target.owner, target.repo)
+        : await setForkApprovalPolicy(client, target.owner, target.repo, policy);
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.detail));
+        process.exitCode = 1;
+        return;
+    }
+    if (opts.json === true) {
+        console.log(JSON.stringify({ forkApproval: outcome.policy }, null, 2));
+        return;
+    }
+    // A server newer than this CLI may name a policy it does not know; say so rather than print `undefined`.
+    const described = FORK_APPROVAL_DESCRIPTIONS[outcome.policy] ?? 'a policy this version of apex does not describe';
+    console.log(`${policy === undefined ? '' : `${chalk.green('✔')} `}${slug}: ${chalk.bold(outcome.policy)} — ${described}`);
+    // The question behind every change to this: it is not about secrets, and saying so costs one line.
+    console.log('A run from a fork never gets secrets, whichever policy is set.');
+});
 export default new Command('approval')
-    .description('Runs from forks: what is waiting for approval, and deciding it')
+    .description('Runs from forks: what is waiting for approval, deciding it, and which ones wait')
     .addCommand(listCommand)
     .addCommand(decide('approve'))
-    .addCommand(decide('reject'));
+    .addCommand(decide('reject'))
+    .addCommand(policyCommand);

package/dist/cli/artifact/main.js

@@ -1,10 +1,10 @@
 import { createWriteStream } from 'node:fs';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { basename, resolve } from 'node:path';
+import { resolve } from 'node:path';
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { deleteArtifact, downloadArtifact, listArtifacts, untilExpiry, } from '../../src/application/manage-artifacts.js';
+import { artifactFileName, 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. */
@@ -52,10 +52,10 @@ const listCommand = new Command('list')
     printArtifacts(outcome.artifacts, outcome.totalSizeBytes);
 });
 const downloadCommand = new Command('download')
-    .description('Download one artifact of a run as a zip')
+    .description('Download one artifact of a run — a zip, or the file itself when it was uploaded with archive: false')
     .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)')
+    .option('-o, --output <path>', 'where to write it (default: <name>.zip here, or the file\'s own name)')
     .action(async (runId, name, opts) => {
     const client = api();
     if (!client)
@@ -76,8 +76,20 @@ const downloadCommand = new Command('download')
             process.exitCode = 1;
             return;
         case 'downloaded': {
-            const target = resolve(opts.output ?? `${basename(outcome.artifact.name)}.zip`);
-            await pipeline(Readable.from(outcome.body), createWriteStream(target));
+            const target = resolve(opts.output ?? artifactFileName(outcome.artifact));
+            // The default name comes from the workflow — an unarchived `.env` or
+            // `Makefile` is a legal artifact — so it never replaces a file that is
+            // already here. A path given with -o is the person's own choice.
+            try {
+                await pipeline(Readable.from(outcome.body), createWriteStream(target, { flags: opts.output === undefined ? 'wx' : 'w' }));
+            }
+            catch (err) {
+                if (err.code !== 'EEXIST')
+                    throw err;
+                console.error(chalk.red(`${target} already exists; choose where to write it with -o`));
+                process.exitCode = 1;
+                return;
+            }
             console.log(`${chalk.green('✔')} ${outcome.artifact.name} → ${target} (${humanBytes(outcome.artifact.sizeBytes)})`);
         }
     }

package/dist/cli/logs/main.js

@@ -4,7 +4,7 @@ import { deleteLogs, 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';
+import { parseRepository, policyLines, unknownRunMessage } from '../../src/domain/runs.js';
 /**
  * The structured reading of one job's log.
  *
@@ -97,6 +97,13 @@ const handler = async (run, options) => {
                     if (options.json !== true)
                         printView(section.job.name, read.view);
                 }
+                // What the action policy found in the plan that ran (TASK-0343): in `audit` the run went ahead regardless.
+                const findings = policyLines(outcome.run);
+                if (options.json !== true && findings.length > 0) {
+                    console.log(chalk.bold('\n── action policy ──'));
+                    for (const line of findings)
+                        console.log(`  ${chalk.yellow('!')} ${line}`);
+                }
                 if (options.json === true)
                     console.log(JSON.stringify({ run: outcome.run, views }, null, 2));
                 process.exitCode = outcome.exitCode;

package/dist/cli/lsp/main.js

@@ -2,6 +2,7 @@ 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';
+import { resolveBinary } from '../../src/infrastructure/binary-install.js';
 /**
  * `apex lsp` — the language server, for an editor to start.
  *
@@ -33,7 +34,7 @@ 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());
+    const outcome = await serveLanguageServer(new EngineBinaryLanguageServer(await resolveBinary('apex-engine', 'APEX_ENGINE_BIN')));
     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.

package/dist/cli/main.js

@@ -1,25 +1,6 @@
 #!/usr/bin/env node
-import { readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { packageVersion } from '../src/infrastructure/binary-install.js';
 import { buildProgram } from './program.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';
-        }
-    }
-};
-buildProgram(readVersion()).parse(process.argv);
+// The version from the nearest `package.json` — what ships, and what `version:check` keeps equal to
+// `VERSION` (see `packageVersion`); it also names which engine and runner the CLI downloads.
+buildProgram(packageVersion()).parse(process.argv);

package/dist/cli/migrate/main.js

@@ -3,6 +3,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { scanOrganization } from '../../src/application/scan-migration.js';
 import { EngineBinaryCompat, LocalWorkflowSource } from '../../src/infrastructure/engine-binary.js';
+import { resolveBinary } from '../../src/infrastructure/binary-install.js';
 import { GitHubApi, NoTokenError } from '../../src/infrastructure/github-api.js';
 import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
 import { parseRepository } from '../../src/domain/runs.js';
@@ -118,8 +119,8 @@ const printScan = (scan, limit) => {
  * first thing somebody evaluating a migration wants: an answer about a
  * repository they already have, without handing anybody credentials.
  */
-const deps = (options) => {
-    const checker = new EngineBinaryCompat();
+const deps = (options, engine) => {
+    const checker = new EngineBinaryCompat(engine);
     if (options.path !== undefined)
         return { workflows: new LocalWorkflowSource(options.path), checker };
     try {
@@ -138,7 +139,7 @@ const handler = async (org, options) => {
         process.exitCode = 2;
         return;
     }
-    const built = deps(options);
+    const built = deps(options, await resolveBinary('apex-engine', 'APEX_ENGINE_BIN'));
     if (built === undefined)
         return;
     // A local scan has no organization. The directory's name is what the person

package/dist/cli/reference.js

@@ -126,23 +126,27 @@ export const REFERENCE = {
     secret: {
         group: 'config',
         audience: 'customer',
-        // The organisation scope answers only for the operator's own organisation.
-        operatorOptions: ['--org'],
+        // `--org <organization>` asks for organization:read|write in that Organization instead (control-plane ADR-0084).
         subcommandPermissions: { list: 'secrets:read', set: 'secrets:write', delete: 'secrets:write' },
         examples: [
             { command: 'printf %s "$NPM_TOKEN" | apex secret set NPM_TOKEN --repo acme/web', description: 'Set a secret from a pipe; a value never goes on the command line.' },
             { command: 'apex secret set DEPLOY_KEY --repo acme/web --repo acme/api --from-file key.pem', description: 'Set one value on two repositories, from a file.' },
             { command: 'apex secret list --repo acme/web', description: "A repository's secret names — never values." },
+            {
+                command: 'printf %s "$NPM_TOKEN" | apex secret set NPM_TOKEN --org acme --repos web,api',
+                description: "Set an organization secret once, for the repositories named; it needs organization:write, which an Owner or Account Admin holds.",
+            },
+            { command: 'apex secret list --org acme', description: "An organization's secret names, and which repositories each reaches." },
         ],
     },
     variable: {
         group: 'config',
         audience: 'customer',
-        operatorOptions: ['--org'],
         subcommandPermissions: { list: 'variables:read', set: 'variables:write', delete: 'variables:write' },
         examples: [
             { command: 'apex variable set NODE_VERSION --value 24 --repo acme/web', description: 'Set a repository variable; a variable is not secret, so --value is allowed.' },
             { command: 'apex variable list --repo acme/web --json', description: "A repository's variables and their values, as JSON." },
+            { command: 'apex variable set REGION --value eu-west-1 --org acme --visibility private', description: "Set an organization variable for its private repositories." },
         ],
     },
     // Runs and logs: a run's repository decides, by the token's `actions` grant.
@@ -230,10 +234,12 @@ export const REFERENCE = {
     approval: {
         group: 'config',
         audience: 'customer',
-        subcommandPermissions: { list: 'approvals:read', approve: 'approvals:write', reject: 'approvals:write' },
+        // `policy` reads with administration:read and sets with administration:write; the reference names what setting needs.
+        subcommandPermissions: { list: 'approvals:read', approve: 'approvals:write', reject: 'approvals:write', policy: 'administration:write' },
         examples: [
             { command: 'apex approval list', description: 'Runs from forks waiting for somebody to approve them.' },
             { command: 'apex approval approve 4812', description: 'Approve one: it runs without secrets, on a runner of its own.' },
+            { command: 'apex approval policy acme/web first-time', description: 'Hold only first-time contributors’ pull requests from forks, as GitHub does by default.' },
         ],
     },
     schedule: {
@@ -260,11 +266,11 @@ export const REFERENCE = {
     actions: {
         group: 'config',
         audience: 'customer',
-        // An organisation's action policy is still the operator's.
-        operatorSubcommands: ['policy'],
-        subcommandPermissions: { list: 'actions:read', pin: 'administration:write' },
+        // An organisation's action policy asks for organization:* in that Organization (control-plane ADR-0084, TASK-0279).
+        subcommandPermissions: { list: 'actions:read', pin: 'administration:write', policy: 'organization:read' },
         examples: [
             { command: 'apex actions list acme/web', description: 'Every action a repository pulls in, least fixed first.' },
+            { command: 'apex actions policy acme --mode enforce --allow "actions/*"', description: "Allow only GitHub's own actions in an organization's workflows; changing it needs organization:write." },
             { command: 'apex actions pin acme/web --apply', description: 'Open a pull request pinning each action to the commit its version points at.' },
         ],
     },

package/dist/cli/run/main.js

@@ -2,10 +2,11 @@ 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 { resolveBinary } from '../../src/infrastructure/binary-install.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, {
+    const outcome = await runWorkflow(new RunnerBinaryExecutor(await resolveBinary('apex-runner', 'APEX_RUNNER_BIN')), new GitHubWorkflowLocator(), workflow, {
         ...(options.job !== undefined ? { job: options.job } : {}),
         ...(options.event !== undefined ? { event: options.event } : {}),
         ...(options.payload !== undefined ? { payload: options.payload } : {}),

package/dist/cli/runner/main.js

@@ -4,6 +4,7 @@ import { fleetHistory, listRunners, mintRegistrationToken, registerRunner, remov
 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';
+import { resolveBinary } from '../../src/infrastructure/binary-install.js';
 /** Build the API client, or explain what is missing and stop. */
 const api = () => {
     try {
@@ -142,7 +143,7 @@ const registerCommand = new Command('register')
     // 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(), {
+    const outcome = await registerRunner(client, new RunnerBinaryExecutor(await resolveBinary('apex-runner', 'APEX_RUNNER_BIN')), {
         server: opts.server,
         labels: opts.labels.split(','),
         name: opts.name,

package/dist/cli/secret/main.js

@@ -2,7 +2,7 @@ import { Command, Option } from 'commander';
 import chalk from 'chalk';
 import { batchExitCode, listSecrets, setEverywhere } from '../../src/application/manage-secrets.js';
 import { ValueInputError, promptHidden, readToEnd, readValueFile } from '../../src/infrastructure/secret-input.js';
-import { api, collect, deleteAction, printResults, targetsFrom, usage, validName } from './shared.js';
+import { api, collect, deleteAction, ORG_OPTION, printResults, reachLabel, reachOf, targetsFrom, usage, validName } from './shared.js';
 /**
  * The refusal, in full, because the person who typed `--value` deserves the
  * reason and the alternative in one breath (BUG-0157).
@@ -30,7 +30,9 @@ const setCommand = new Command('set')
     .description('Set a secret on one or more repositories; the value is read from stdin, a file or a no-echo prompt')
     .argument('<name>', 'secret name, as a workflow reads it: secrets.NAME')
     .option('--repo <owner/repo>', 'repository to set it on (repeatable: one value, many repositories)', collect, [])
-    .option('--org', 'the organisation scope (the operator organisation only)')
+    .option(...ORG_OPTION)
+    .option('--visibility <visibility>', 'with --org <organization>: which repositories reach it — all (default), private or selected')
+    .option('--repos <names>', 'with --org <organization>: the repositories that reach it, comma-separated (implies --visibility selected)')
     .option('--from-file <path>', 'read the value from this file (one trailing newline is dropped)')
     // Declared so the refusal is ours, with the reason, and not commander's "unknown option".
     .addOption(new Option('--value [value]', 'refused: a secret never goes on the command line').hideHelp())
@@ -44,6 +46,9 @@ const setCommand = new Command('set')
     const targets = targetsFrom(opts);
     if (!targets)
         return;
+    const reach = reachOf(opts);
+    if (reach === null)
+        return;
     const client = api();
     if (!client)
         return;
@@ -54,14 +59,14 @@ const setCommand = new Command('set')
         usage('the value is empty; nothing was set');
         return;
     }
-    const results = await setEverywhere(client, 'secret', targets, name, value);
+    const results = await setEverywhere(client, 'secret', targets, name, value, reach);
     printResults(name, results);
     process.exitCode = batchExitCode(results);
 });
 const listCommand = new Command('list')
     .description("A repository's secret names — never values: the API has none to give")
     .option('--repo <owner/repo>', 'repository', collect, [])
-    .option('--org', 'the organisation scope (the operator organisation only)')
+    .option(...ORG_OPTION)
     .option('--json', 'machine-readable output')
     .action(async (opts) => {
     const targets = targetsFrom(opts, true);
@@ -84,15 +89,17 @@ const listCommand = new Command('list')
         console.log(chalk.yellow('No secrets are set here.'));
         return;
     }
-    console.log(chalk.bold(['NAME'.padEnd(32), 'UPDATED'].join('  ')));
-    for (const s of outcome.secrets)
-        console.log([s.name.padEnd(32), s.updatedAt ?? ''].join('  '));
+    const reaches = outcome.secrets.some((s) => s.visibility !== undefined);
+    console.log(chalk.bold(['NAME'.padEnd(32), 'UPDATED'.padEnd(reaches ? 26 : 0), ...(reaches ? ['REACHES'] : [])].join('  ').trimEnd()));
+    for (const s of outcome.secrets) {
+        console.log([s.name.padEnd(32), (s.updatedAt ?? '').padEnd(reaches ? 26 : 0), ...(reaches ? [reachLabel(s)] : [])].join('  ').trimEnd());
+    }
 });
 const deleteCommand = new Command('delete')
     .description('Delete a secret from one or more repositories')
     .argument('<name>', 'secret name')
     .option('--repo <owner/repo>', 'repository (repeatable)', collect, [])
-    .option('--org', 'the organisation scope (the operator organisation only)')
+    .option(...ORG_OPTION)
     .option('-y, --yes', 'do not ask; required when not on a terminal')
     .action(deleteAction('secret'));
 export default new Command('secret')

package/dist/cli/secret/shared.js

@@ -2,8 +2,10 @@ import chalk from 'chalk';
 import { splitRepository } from '../../src/application/manage-caches.js';
 import { batchExitCode, deleteEverywhere } from '../../src/application/manage-secrets.js';
 import { confirm } from '../../src/infrastructure/secret-input.js';
-import { nameProblem } from '../../src/domain/secrets.js';
+import { nameProblem, reachFrom } from '../../src/domain/secrets.js';
 import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
+/** What `--org` says in every subcommand's help. */
+export const ORG_OPTION = ['--org [organization]', 'an organization’s scope, by its GitHub login (bare: the operator organization)'];
 export const collect = (value, previous) => [...previous, value];
 export const usage = (message) => {
     console.error(chalk.red(message));
@@ -31,12 +33,14 @@ export const validName = (name) => {
  * is for `list`, which answers about one place at a time.
  */
 export const targetsFrom = (opts, single = false) => {
-    if (opts.org === true && opts.repo.length > 0) {
+    if (opts.org !== undefined && opts.org !== false && opts.repo.length > 0) {
         usage('pass --repo or --org, not both');
         return undefined;
     }
     if (opts.org === true)
         return [{ kind: 'org' }];
+    if (typeof opts.org === 'string')
+        return [{ kind: 'org', org: opts.org }];
     if (opts.repo.length === 0) {
         usage('name a repository with --repo owner/repo');
         return undefined;
@@ -56,6 +60,26 @@ export const targetsFrom = (opts, single = false) => {
     }
     return targets;
 };
+/**
+ * `--visibility` and `--repos`, which say which of a named Organization's repositories an entry reaches; `null` after
+ * a usage error, `undefined` for the API's default (every repository).
+ */
+export const reachOf = (opts) => {
+    if (opts.visibility === undefined && opts.repos === undefined)
+        return undefined;
+    if (typeof opts.org !== 'string') {
+        usage('--visibility and --repos say which repositories of an organization reach it: use them with --org <organization>');
+        return null;
+    }
+    const reach = reachFrom(opts.visibility, opts.repos);
+    if (reach !== undefined && 'problem' in reach) {
+        usage(reach.problem);
+        return null;
+    }
+    return reach;
+};
+/** An Organization's entry: which repositories reach it, as a person reads it. */
+export const reachLabel = (r) => r.visibility === 'selected' ? `selected: ${(r.selectedRepositories ?? []).join(', ') || 'none'}` : r.visibility === 'private' ? 'private repositories' : 'all repositories';
 /** One line per target, then nothing else: the summary is the whole output. */
 export const printResults = (name, results) => {
     for (const r of results) {

package/dist/cli/tenant/main.js

@@ -1,10 +1,10 @@
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { listDepartures, purgeDeparture } from '../../src/application/manage-departures.js';
+import { listDepartures, listRepositoryDepartures, purgeDeparture, purgeRepositoryDeparture } from '../../src/application/manage-departures.js';
 import { backfillAccounts, connectInstallation, listUnconnected } from '../../src/application/manage-accounts.js';
 import { backfillLines, connectLine, unconnectedLine } from '../../src/domain/accounts.js';
 import { HttpControlPlane, NotConfiguredError } from '../../src/infrastructure/control-plane-http.js';
-import { countsLine, departureLine } from '../../src/domain/departures.js';
+import { countsLine, departureLine, repositoryDepartureLine } from '../../src/domain/departures.js';
 import { listInstallations } from '../../src/application/manage-grants.js';
 import { installationLine } from '../../src/domain/grants.js';
 /** Build the API client, or explain what is missing and stop. */
@@ -20,11 +20,31 @@ const api = () => {
 };
 const departuresCommand = new Command('departures')
     .description('Every tenant that uninstalled, newest first, and when its data is deleted')
+    .option('--repositories', 'repositories removed from an installation that stays, instead (ADR-0069 amendment)')
     .option('--json', 'machine-readable output')
     .action(async (opts) => {
     const client = api();
     if (!client)
         return;
+    if (opts.repositories === true) {
+        const removed = await listRepositoryDepartures(client);
+        if (removed.kind === 'refused') {
+            console.error(chalk.red(removed.message));
+            process.exitCode = 1;
+            return;
+        }
+        if (opts.json === true) {
+            console.log(JSON.stringify(removed.value, null, 2));
+            return;
+        }
+        if (removed.value.length === 0) {
+            console.log(chalk.green('no repository has been removed'));
+            return;
+        }
+        for (const d of removed.value)
+            console.log(`  ${repositoryDepartureLine(d)}`);
+        return;
+    }
     const outcome = await listDepartures(client);
     if (outcome.kind === 'refused') {
         console.error(chalk.red(outcome.message));
@@ -42,12 +62,55 @@ const departuresCommand = new Command('departures')
     for (const d of outcome.value)
         console.log(`  ${departureLine(d)}`);
 });
+/** `apex tenant purge --repository <repoId>` (context TASK-0331). */
+const purgeRemovedRepository = async (raw, opts) => {
+    const repoId = Number(raw);
+    if (!Number.isSafeInteger(repoId) || repoId <= 0) {
+        console.error(chalk.red(`expected a positive repository id, got ${JSON.stringify(raw)}`));
+        process.exitCode = 2;
+        return;
+    }
+    const client = api();
+    if (!client)
+        return;
+    const outcome = await purgeRepositoryDeparture(client, repoId, opts.apply === true);
+    if (outcome.kind === 'refused') {
+        console.error(chalk.red(outcome.message));
+        process.exitCode = 1;
+        return;
+    }
+    const report = outcome.value;
+    if (opts.json === true) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(repositoryDepartureLine(report.departure));
+    if (report.applied && report.counts !== null) {
+        console.log(`${chalk.green('✔')} purged: ${countsLine(report.counts)}`);
+        return;
+    }
+    if (report.departure.purgedAt !== null) {
+        console.log(chalk.dim(`already purged${report.counts === null ? '' : `: ${countsLine(report.counts)}`}`));
+        return;
+    }
+    console.log(chalk.yellow(`the repository and everything under it would be deleted, with the deliveries that name it. Re-run with --apply.`));
+};
 const purgeCommand = new Command('purge')
     .description("Delete one departed tenant's data now, whatever its window — a dry run unless --apply")
-    .argument('<installationId>', 'the installation that left')
+    .argument('[installationId]', 'the installation that left')
+    .option('--repository <repoId>', 'a repository removed from an installation that stays, instead (ADR-0069 amendment)')
     .option('--apply', 'delete it (default: report what would be deleted)')
     .option('--json', 'machine-readable output')
     .action(async (raw, opts) => {
+    if ((raw === undefined) === (opts.repository === undefined)) {
+        console.error(chalk.red('name one: an installation id, or --repository <repoId>'));
+        process.exitCode = 2;
+        return;
+    }
+    if (opts.repository !== undefined) {
+        await purgeRemovedRepository(opts.repository, opts);
+        return;
+    }
     const installationId = Number(raw);
     if (!Number.isSafeInteger(installationId) || installationId <= 0) {
         console.error(chalk.red(`expected a positive installation id, got ${JSON.stringify(raw)}`));

package/dist/cli/validate/main.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { validateWorkflows } from '../../src/application/validate-workflows.js';
 import { EngineBinaryValidator, GitHubWorkflowLocator } from '../../src/infrastructure/engine-binary.js';
+import { resolveBinary } from '../../src/infrastructure/binary-install.js';
 import { diagnosticCount } from '../../src/domain/validation.js';
 const printHuman = (report) => {
     for (const file of report.files) {
@@ -21,7 +22,7 @@ const printHuman = (report) => {
         console.log(chalk.dim(`${n} diagnostic${n === 1 ? '' : 's'}`));
 };
 const handler = async (files, options) => {
-    const outcome = await validateWorkflows(new EngineBinaryValidator(), new GitHubWorkflowLocator(), files);
+    const outcome = await validateWorkflows(new EngineBinaryValidator(await resolveBinary('apex-engine', 'APEX_ENGINE_BIN')), new GitHubWorkflowLocator(), files);
     switch (outcome.kind) {
         case 'no-workflows':
             console.error(chalk.yellow('no workflow files found (.github/workflows/*.yml) — pass files explicitly'));

package/dist/cli/variable/main.js

@@ -2,7 +2,7 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { batchExitCode, listVariables, setEverywhere } from '../../src/application/manage-secrets.js';
 import { readToEnd } from '../../src/infrastructure/secret-input.js';
-import { api, collect, deleteAction, printResults, targetsFrom, usage, validName } from '../secret/shared.js';
+import { api, collect, deleteAction, ORG_OPTION, printResults, reachLabel, reachOf, targetsFrom, usage, validName } from '../secret/shared.js';
 /**
  * `apex variable`: the same routes as `apex secret`, for values that are not
  * secret. A variable is readable back — `list` prints it — so `--value` on the
@@ -12,14 +12,19 @@ const setCommand = new Command('set')
     .description('Set a variable on one or more repositories, from --value or stdin')
     .argument('<name>', 'variable name, as a workflow reads it: vars.NAME')
     .option('--value <value>', 'the value (not secret, so a flag is allowed); otherwise read from stdin')
+    .option('--visibility <visibility>', 'with --org <organization>: which repositories reach it — all (default), private or selected')
+    .option('--repos <names>', 'with --org <organization>: the repositories that reach it, comma-separated (implies --visibility selected)')
     .option('--repo <owner/repo>', 'repository to set it on (repeatable)', collect, [])
-    .option('--org', 'the organisation scope (the operator organisation only)')
+    .option(...ORG_OPTION)
     .action(async (name, opts) => {
     if (!validName(name))
         return;
     const targets = targetsFrom(opts);
     if (!targets)
         return;
+    const reach = reachOf(opts);
+    if (reach === null)
+        return;
     let value = opts.value;
     if (value === undefined) {
         if (process.stdin.isTTY === true) {
@@ -35,14 +40,14 @@ const setCommand = new Command('set')
     const client = api();
     if (!client)
         return;
-    const results = await setEverywhere(client, 'variable', targets, name, value);
+    const results = await setEverywhere(client, 'variable', targets, name, value, reach);
     printResults(name, results);
     process.exitCode = batchExitCode(results);
 });
 const listCommand = new Command('list')
     .description("A repository's variables, names and values")
     .option('--repo <owner/repo>', 'repository', collect, [])
-    .option('--org', 'the organisation scope (the operator organisation only)')
+    .option(...ORG_OPTION)
     .option('--json', 'machine-readable output')
     .action(async (opts) => {
     const targets = targetsFrom(opts, true);
@@ -65,15 +70,17 @@ const listCommand = new Command('list')
         console.log(chalk.yellow('No variables are set here.'));
         return;
     }
-    console.log(chalk.bold(['NAME'.padEnd(32), 'VALUE'].join('  ')));
-    for (const v of outcome.variables)
-        console.log([v.name.padEnd(32), v.value].join('  '));
+    const reaches = outcome.variables.some((v) => v.visibility !== undefined);
+    console.log(chalk.bold(['NAME'.padEnd(32), 'VALUE'.padEnd(reaches ? 32 : 0), ...(reaches ? ['REACHES'] : [])].join('  ').trimEnd()));
+    for (const v of outcome.variables) {
+        console.log([v.name.padEnd(32), v.value.padEnd(reaches ? 32 : 0), ...(reaches ? [reachLabel(v)] : [])].join('  ').trimEnd());
+    }
 });
 const deleteCommand = new Command('delete')
     .description('Delete a variable from one or more repositories')
     .argument('<name>', 'variable name')
     .option('--repo <owner/repo>', 'repository (repeatable)', collect, [])
-    .option('--org', 'the organisation scope (the operator organisation only)')
+    .option(...ORG_OPTION)
     .option('-y, --yes', 'do not ask; required when not on a terminal')
     .action(deleteAction('variable'));
 export default new Command('variable')

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

@@ -1,4 +1,17 @@
 // application layer — see ../../../../docs/conventions.md §1
+/**
+ * Which pull requests from forks wait for approval — a repository's choice (TASK-0355). `every-fork` is ours and the
+ * default; the other three are GitHub's. Whatever is chosen, a fork's run gets no secrets.
+ */
+export const FORK_APPROVAL_POLICIES = ['every-fork', 'external', 'first-time', 'first-time-new-to-github'];
+/** Each policy in GitHub's words, and who waits under it. */
+export const FORK_APPROVAL_DESCRIPTIONS = {
+    'every-fork': 'every pull request from a fork waits for approval, whoever opened it (the default)',
+    external: 'require approval for all external contributors — anybody not an owner, member or collaborator waits',
+    'first-time': 'require approval for first-time contributors — anybody never merged into this repository waits',
+    'first-time-new-to-github': 'require approval for first-time contributors who are new to GitHub',
+};
+export const isForkApprovalPolicy = (v) => FORK_APPROVAL_POLICIES.includes(v);
 const refused = (err) => ({ kind: 'refused', detail: err instanceof Error ? err.message : String(err) });
 export const listWaitingRuns = async (api) => {
     try {
@@ -22,3 +35,21 @@ export const decideRun = async (api, runId, decision, comment) => {
 };
 /** One waiting run on one line: what it is, and where it came from. */
 export const waitingSummary = (r) => `${r.repository} #${r.runNumber} ${r.workflowName} (${r.event} ${r.sha.slice(0, 7)})`;
+/** The repository's fork-approval policy — the effective one, so a repository that never chose reads `every-fork`. */
+export const forkApprovalPolicy = async (api, owner, repo) => {
+    try {
+        return { kind: 'read', policy: (await api.getForkApproval(owner, repo)).forkApproval };
+    }
+    catch (err) {
+        return refused(err);
+    }
+};
+/** Choose the policy (repository admin). The control plane audits it and answers with what it stored. */
+export const setForkApprovalPolicy = async (api, owner, repo, policy) => {
+    try {
+        return { kind: 'read', policy: (await api.setForkApproval(owner, repo, policy)).forkApproval };
+    }
+    catch (err) {
+        return refused(err);
+    }
+};

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

@@ -77,3 +77,13 @@ export const untilExpiry = (iso, now = Date.now()) => {
     const days = Math.floor(ms / 86_400_000);
     return days === 0 ? 'today' : `${days}d`;
 };
+/**
+ * Where a download is written when nobody says: the server's `fileName`, else
+ * `<name>.zip`, which is all a server before raw uploads ever stored. Only the
+ * last path segment — a name never steers the write elsewhere.
+ */
+export const artifactFileName = (artifact) => {
+    const last = (artifact.fileName ?? `${artifact.name}.zip`).split(/[\\/]/).pop() ?? '';
+    // `artifact` is what `@actions/artifact` itself falls back to.
+    return last === '' || last === '.' || last === '..' ? 'artifact' : last;
+};

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

@@ -16,3 +16,7 @@ export const listDepartures = async (api) => await attempt(() => api.departures(
  * left to ask.
  */
 export const purgeDeparture = async (api, installationId, apply) => await attempt(() => api.purgeDeparture(installationId, apply));
+/** Every repository the App was removed from, newest first (control-plane ADR-0069 amendment). */
+export const listRepositoryDepartures = async (api) => await attempt(() => api.repositoryDepartures());
+/** Purge one removed repository's data now, whatever its window — a dry run unless `apply`; machine token only. */
+export const purgeRepositoryDeparture = async (api, repoId, apply) => await attempt(() => api.purgeRepositoryDeparture(repoId, apply));

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

@@ -1,17 +1,17 @@
 // 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.
+ * Why the unnamed organisation scope refused: it is the operator organisation's
+ * (BUG-0112). A customer names theirs — `--org <login>` (ADR-0084) — and that
+ * route's refusal explains itself, so it is relayed as worded.
  */
-export const ORG_SCOPE_REFUSAL = 'organisation secrets are not available to customer organisations yet — set it on each repository with --repo';
+export const ORG_SCOPE_REFUSAL = 'the bare --org scope is the operator organisation’s — name yours: --org <your-organization>';
 const statusOf = (err) => {
     const status = err?.status;
     return typeof status === 'number' ? status : undefined;
 };
 const refused = (target, err) => {
-    if (target.kind === 'org' && statusOf(err) === 403)
+    if (target.kind === 'org' && target.org === undefined && statusOf(err) === 403)
         return { kind: 'refused', detail: ORG_SCOPE_REFUSAL };
     return { kind: 'refused', detail: err instanceof Error ? err.message : String(err) };
 };
@@ -22,11 +22,11 @@ const refused = (target, err) => {
  * 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) => {
+export const setEverywhere = async (api, kind, targets, name, value, reach) => {
     const results = [];
     for (const target of targets) {
         try {
-            await (kind === 'secret' ? api.setSecret(target, name, value) : api.setVariable(target, name, value));
+            await (kind === 'secret' ? api.setSecret(target, name, value, reach) : api.setVariable(target, name, value, reach));
             results.push({ target: targetLabel(target), kind: 'set' });
         }
         catch (err) {
@@ -64,7 +64,12 @@ export const listSecrets = async (api, target) => {
         return {
             kind: 'listed',
             secrets: secrets
-                .map((s) => ({ name: s.name, ...(s.updatedAt === undefined ? {} : { updatedAt: s.updatedAt }) }))
+                .map((s) => ({
+                name: s.name,
+                ...(s.updatedAt === undefined ? {} : { updatedAt: s.updatedAt }),
+                ...(s.visibility === undefined ? {} : { visibility: s.visibility }),
+                ...(s.selectedRepositories === undefined ? {} : { selectedRepositories: s.selectedRepositories }),
+            }))
                 .sort((a, b) => (a.name < b.name ? -1 : 1)),
         };
     }

package/dist/src/domain/accounts.js

@@ -1,6 +1,6 @@
 /**
  * The Accounts backfill as the control plane reports it (control-plane
- * `POST /api/v1/admin/accounts/backfill`, TASK-0195), and how a person reads it.
+ * `POST /api/v1/console/accounts/backfill`, TASK-0195), and how a person reads it.
  */
 const ORG_VERB = {
     connect: ['would join', 'joined'],

package/dist/src/domain/credentials.js

@@ -131,7 +131,7 @@ const REPO = /^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/;
  * What a token may be granted (context ADR-0038): `resource:read|write`, write implying read. The control plane's
  * `RepoPermission`, in the order a person reads them.
  */
-export const TOKEN_RESOURCES = ['actions', 'approvals', 'deployments', 'secrets', 'variables', 'environments', 'notifications', 'administration'];
+export const TOKEN_RESOURCES = ['actions', 'approvals', 'deployments', 'secrets', 'variables', 'environments', 'notifications', 'administration', 'organization'];
 export const TOKEN_PERMISSIONS = TOKEN_RESOURCES.flatMap((r) => [`${r}:read`, `${r}:write`]);
 /** `--permission`'s values: at least one when `required`, each one a known grant. */
 export const permissionsProblem = (permissions, required) => {

package/dist/src/domain/departures.js

@@ -1,4 +1,9 @@
 // domain layer — see ../../../../docs/conventions.md §1
+/** Where a removed repository's clock stands: gone, kept because it was added back, or still waiting. */
+export const repositoryDepartureLine = (d) => {
+    const state = d.purgedAt !== null ? `purged ${d.purgedAt}` : d.withdrawnAt !== null ? `kept — added back ${d.withdrawnAt}` : `due ${d.purgeAfter}`;
+    return `${d.repository} (repository ${d.repoId}) — removed from installation ${d.installationId} ${d.departedAt}; ${state}`;
+};
 /**
  * Where a departure stands, in the words an operator answering a deletion
  * request needs: gone, kept because the account came back, or still waiting —

package/dist/src/domain/runs.js

@@ -1,6 +1,8 @@
 // domain layer — see ../../../../docs/conventions.md §1
 // What the CLI knows about runs and jobs, and the pure decisions it makes
 // about them. The REST shapes come from control-plane/contracts/openapi.
+/** The run's action-policy findings as `apex logs --summary` prints them: where, which job, the policy's sentence. */
+export const policyLines = (run) => (run.policyFindings ?? []).map((f) => `${f.workflowPath}${f.line === undefined || f.line <= 0 ? '' : `:${String(f.line)}`} (job ${f.jobId}): ${f.reason}`);
 /** A run is worth following while anything can still change. */
 export const isLive = (status) => status !== 'completed';
 /** The exit code a completed run should give a shell: 0 only for success. */

package/dist/src/domain/secrets.js

@@ -1,5 +1,26 @@
 // domain layer — see ../../../../docs/conventions.md §1
-export const targetLabel = (target) => (target.kind === 'org' ? 'the organisation' : `${target.owner}/${target.repo}`);
+export const targetLabel = (target) => target.kind === 'repo' ? `${target.owner}/${target.repo}` : target.org === undefined ? 'the organisation' : `the ${target.org} organization`;
+/** Which of an Organization's repositories an organisation entry reaches — GitHub's three. */
+export const VISIBILITIES = ['all', 'private', 'selected'];
+/**
+ * `--visibility` and `--repos` into a reach, or the reason they do not make one. `--repos` alone means `selected`,
+ * as on `gh secret set`; neither means the API's default, every repository.
+ */
+export const reachFrom = (visibility, repos) => {
+    const names = (repos ?? '')
+        .split(',')
+        .map((r) => r.trim())
+        .filter((r) => r !== '');
+    if (visibility === undefined && names.length === 0)
+        return undefined;
+    if (visibility !== undefined && !VISIBILITIES.includes(visibility)) {
+        return { problem: `--visibility is one of ${VISIBILITIES.join(', ')}, not ${JSON.stringify(visibility)}` };
+    }
+    const v = (visibility ?? 'selected');
+    if (v !== 'selected' && names.length > 0)
+        return { problem: `--repos goes with --visibility selected, not ${v}` };
+    return { visibility: v, repos: names };
+};
 /**
  * GitHub's naming rule, which the control plane enforces too: letters, digits
  * and underscores, not starting with a digit, and `GITHUB_` is reserved.

package/dist/src/infrastructure/binary-install.js

@@ -0,0 +1,147 @@
+// infrastructure layer — see ../../../../docs/conventions.md §1
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { access, chmod, mkdir, mkdtemp, rename, rm, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+/**
+ * Where `engine` and `runner` publish their binaries on a release tag (context ADR-0040): one archive per
+ * platform and a SHA256SUMS file per command, under the lockstep version.
+ */
+export const DIST_BASE = 'https://apexactions.com/dl';
+/**
+ * The CLI's version, from the nearest `package.json` above this file.
+ *
+ * `VERSION` is the source of truth in the repository and is not in the published package; what ships is
+ * `package.json`, and `version:check` guarantees the two agree. Walking up survives the layout differing
+ * between `tsx` (`src/…`) and a tarball (`dist/src/…`).
+ */
+export const packageVersion = (from = import.meta.dirname) => {
+    for (let dir = from;; dir = dirname(dir)) {
+        try {
+            return JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version;
+        }
+        catch {
+            if (dirname(dir) === dir)
+                return '0.0.0-unknown';
+        }
+    }
+};
+/** Node's names to Go's, for the four targets that are published; anything else has no download. */
+export const platformOf = (platform, arch) => {
+    const os = platform === 'darwin' ? 'darwin' : platform === 'linux' ? 'linux' : undefined;
+    const goArch = arch === 'arm64' ? 'arm64' : arch === 'x64' ? 'amd64' : undefined;
+    return os !== undefined && goArch !== undefined ? { os, arch: goArch } : undefined;
+};
+export const archiveName = (command, version, p) => `${command}_${version}_${p.os}_${p.arch}.tar.gz`;
+export const sumsName = (command, version) => `${command}_${version}_SHA256SUMS`;
+/** The checksum `sha256sum` printed for one file, or undefined when the file is not listed. */
+export const expectedSum = (sums, file) => {
+    for (const line of sums.split('\n')) {
+        const match = /^([0-9a-f]{64})\s+\*?(\S+)$/.exec(line.trim());
+        if (match?.[2] === file)
+            return match[1];
+    }
+    return undefined;
+};
+/** A release version has a download; a development build (`0.0.0-unknown`, a prerelease) does not. */
+const published = (version) => /^\d+\.\d+\.\d+$/.test(version);
+const isExecutable = async (path) => {
+    try {
+        await access(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const onPath = async (command, env) => {
+    for (const dir of (env.PATH ?? '').split(delimiter)) {
+        if (dir !== '' && (await isExecutable(join(dir, command))))
+            return true;
+    }
+    return false;
+};
+const run = promisify(execFile);
+export const defaultInstallDeps = () => ({
+    env: process.env,
+    version: packageVersion(),
+    platform: platformOf(process.platform, process.arch),
+    cacheDir: join(process.env.APEX_HOME ?? join(homedir(), '.apex'), 'bin'),
+    distBase: process.env.APEX_DIST_URL ?? DIST_BASE,
+    fetch: async (url) => {
+        const res = await fetch(url);
+        return { ok: res.ok, status: res.status, bytes: async () => new Uint8Array(await res.arrayBuffer()) };
+    },
+    extract: async (archive, into) => {
+        await run('tar', ['-xzf', archive, '-C', into]);
+    },
+    notice: (message) => process.stderr.write(`${message}\n`),
+});
+/**
+ * The path to run for `command` (`apex-engine`, `apex-runner`), installing it when nothing else provides one.
+ *
+ * In order: the override in `envVar`; the command on `PATH`; this version's copy in the cache
+ * (`~/.apex/bin/<version>/`); and otherwise this version's archive from {@link DIST_BASE}, checked against the
+ * published SHA256SUMS before it is unpacked. The version is the CLI's own, so the CLI never runs an engine
+ * from another release. When nothing works the bare command is returned and the adapter reports it missing,
+ * after a notice that says why the download did not happen.
+ */
+export const resolveBinary = async (command, envVar, deps = defaultInstallDeps()) => {
+    const override = deps.env[envVar];
+    if (override !== undefined && override !== '')
+        return override;
+    if (await onPath(command, deps.env))
+        return command;
+    const dir = join(deps.cacheDir, deps.version);
+    const cached = join(dir, command);
+    if (await isExecutable(cached))
+        return cached;
+    if (!published(deps.version))
+        return command;
+    if (deps.platform === undefined) {
+        deps.notice(`${command} is published for macOS and Linux on arm64 and x64 only; install it yourself and set ${envVar}`);
+        return command;
+    }
+    const archive = archiveName(command, deps.version, deps.platform);
+    const base = `${deps.distBase.replace(/\/+$/, '')}/${deps.version}`;
+    try {
+        deps.notice(`Installing ${command} ${deps.version} for ${deps.platform.os}/${deps.platform.arch} into ${dir}`);
+        const sums = await deps.fetch(`${base}/${sumsName(command, deps.version)}`);
+        if (!sums.ok)
+            throw new Error(`checksums: HTTP ${sums.status}`);
+        const want = expectedSum(new TextDecoder().decode(await sums.bytes()), archive);
+        if (want === undefined)
+            throw new Error(`${archive} is not in the published checksums`);
+        const body = await deps.fetch(`${base}/${archive}`);
+        if (!body.ok)
+            throw new Error(`${archive}: HTTP ${body.status}`);
+        const bytes = await body.bytes();
+        const got = createHash('sha256').update(bytes).digest('hex');
+        if (got !== want)
+            throw new Error(`${archive} does not match its published checksum`);
+        // Unpack inside the cache (one filesystem, so the move is a rename) and move into place, so a
+        // half-written install is never found as a cached one.
+        await mkdir(deps.cacheDir, { recursive: true });
+        const work = await mkdtemp(join(deps.cacheDir, `.${command}-`));
+        try {
+            const file = join(work, archive);
+            await writeFile(file, bytes);
+            await deps.extract(file, work);
+            await chmod(join(work, command), 0o755);
+            await mkdir(dir, { recursive: true });
+            await rename(join(work, command), cached);
+        }
+        finally {
+            await rm(work, { recursive: true, force: true });
+        }
+        return cached;
+    }
+    catch (error) {
+        deps.notice(`Could not install ${command} from ${base}/: ${error.message}`);
+        return command;
+    }
+};

package/dist/src/infrastructure/binary-install.test.js

@@ -0,0 +1,114 @@
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { archiveName, defaultInstallDeps, DIST_BASE, expectedSum, packageVersion, platformOf, resolveBinary, sumsName, } from './binary-install.js';
+const VERSION = '0.87.0';
+const PLATFORM = { os: 'darwin', arch: 'arm64' };
+/** A real archive, laid out the way binary-publish packs one: the command, the licence and the notices. */
+const makeArchive = (command) => {
+    const stage = mkdtempSync(join(tmpdir(), 'stage-'));
+    writeFileSync(join(stage, command), '#!/bin/sh\necho engine\n');
+    chmodSync(join(stage, command), 0o755);
+    writeFileSync(join(stage, 'LICENSE'), 'licence');
+    writeFileSync(join(stage, 'THIRD-PARTY-NOTICES.md'), 'notices');
+    const out = join(stage, 'a.tar.gz');
+    execFileSync('tar', ['-czf', out, '-C', stage, command, 'LICENSE', 'THIRD-PARTY-NOTICES.md']);
+    return new Uint8Array(readFileSync(out));
+};
+const sha = (b) => createHash('sha256').update(b).digest('hex');
+const harness = (over = {}) => {
+    const notices = [];
+    const fetched = [];
+    const files = over.files ?? {};
+    const deps = {
+        ...defaultInstallDeps(),
+        env: { PATH: '' },
+        version: VERSION,
+        platform: PLATFORM,
+        cacheDir: mkdtempSync(join(tmpdir(), 'apex-bin-')),
+        fetch: async (url) => {
+            fetched.push(url);
+            const body = files[url];
+            if (body === undefined)
+                return { ok: false, status: 404, bytes: async () => new Uint8Array() };
+            return { ok: true, status: 200, bytes: async () => (typeof body === 'string' ? new TextEncoder().encode(body) : body) };
+        },
+        notice: (m) => notices.push(m),
+        ...over,
+    };
+    return { deps, notices, fetched };
+};
+const published = (command, archive, sum = sha(archive)) => ({
+    [`${DIST_BASE}/${VERSION}/${sumsName(command, VERSION)}`]: `${sum}  ${archiveName(command, VERSION, PLATFORM)}\n`,
+    [`${DIST_BASE}/${VERSION}/${archiveName(command, VERSION, PLATFORM)}`]: archive,
+});
+describe('resolveBinary', () => {
+    it('prefers the override, then PATH, and downloads nothing for either', async () => {
+        const { deps, fetched } = harness({ env: { APEX_ENGINE_BIN: '/opt/engine', PATH: '' } });
+        expect(await resolveBinary('apex-engine', 'APEX_ENGINE_BIN', deps)).toBe('/opt/engine');
+        const bin = mkdtempSync(join(tmpdir(), 'path-'));
+        writeFileSync(join(bin, 'apex-engine'), '');
+        chmodSync(join(bin, 'apex-engine'), 0o755);
+        const onPath = harness({ env: { PATH: bin } });
+        expect(await resolveBinary('apex-engine', 'APEX_ENGINE_BIN', onPath.deps)).toBe('apex-engine');
+        expect([...fetched, ...onPath.fetched]).toEqual([]);
+    });
+    it('downloads this version for this platform, checks it, unpacks it executable, and reuses it', async () => {
+        const archive = makeArchive('apex-engine');
+        const { deps, fetched } = harness({ files: published('apex-engine', archive) });
+        const path = await resolveBinary('apex-engine', 'APEX_ENGINE_BIN', deps);
+        expect(path).toBe(join(deps.cacheDir, VERSION, 'apex-engine'));
+        expect(statSync(path).mode & 0o111).not.toBe(0);
+        expect(execFileSync(path).toString()).toBe('engine\n');
+        expect(fetched).toEqual([
+            `${DIST_BASE}/${VERSION}/apex-engine_${VERSION}_SHA256SUMS`,
+            `${DIST_BASE}/${VERSION}/apex-engine_${VERSION}_darwin_arm64.tar.gz`,
+        ]);
+        // The second call finds the cached copy and fetches nothing.
+        expect(await resolveBinary('apex-engine', 'APEX_ENGINE_BIN', deps)).toBe(path);
+        expect(fetched).toHaveLength(2);
+    });
+    it('refuses an archive that does not match its published checksum, and installs nothing', async () => {
+        const archive = makeArchive('apex-engine');
+        const { deps, notices } = harness({ files: published('apex-engine', archive, 'f'.repeat(64)) });
+        expect(await resolveBinary('apex-engine', 'APEX_ENGINE_BIN', deps)).toBe('apex-engine');
+        expect(notices.at(-1)).toMatch(/does not match its published checksum/);
+        expect(() => statSync(join(deps.cacheDir, VERSION, 'apex-engine'))).toThrow();
+    });
+    it('says why when the release has no download, and falls back to the bare command', async () => {
+        const { deps, notices } = harness();
+        expect(await resolveBinary('apex-runner', 'APEX_RUNNER_BIN', deps)).toBe('apex-runner');
+        expect(notices.at(-1)).toMatch(/Could not install apex-runner .*checksums: HTTP 404/);
+    });
+    it('never downloads for a development build or an unpublished platform', async () => {
+        const dev = harness({ version: '0.0.0-unknown' });
+        expect(await resolveBinary('apex-engine', 'APEX_ENGINE_BIN', dev.deps)).toBe('apex-engine');
+        expect(dev.fetched).toEqual([]);
+        const windows = harness({ platform: undefined });
+        expect(await resolveBinary('apex-engine', 'APEX_ENGINE_BIN', windows.deps)).toBe('apex-engine');
+        expect(windows.fetched).toEqual([]);
+        expect(windows.notices.at(-1)).toMatch(/macOS and Linux on arm64 and x64 only/);
+    });
+});
+describe('the names', () => {
+    it('maps Node platforms to the published Go targets', () => {
+        expect(platformOf('darwin', 'arm64')).toEqual({ os: 'darwin', arch: 'arm64' });
+        expect(platformOf('linux', 'x64')).toEqual({ os: 'linux', arch: 'amd64' });
+        expect(platformOf('win32', 'x64')).toBeUndefined();
+        expect(platformOf('linux', 'ia32')).toBeUndefined();
+    });
+    it('reads one line of sha256sum output, with or without the binary-mode star', () => {
+        const sums = `${'a'.repeat(64)}  apex-engine_1.0.0_linux_amd64.tar.gz\n${'b'.repeat(64)} *apex-engine_1.0.0_darwin_arm64.tar.gz\n`;
+        expect(expectedSum(sums, 'apex-engine_1.0.0_darwin_arm64.tar.gz')).toBe('b'.repeat(64));
+        expect(expectedSum(sums, 'missing.tar.gz')).toBeUndefined();
+    });
+    it('reads the version from the nearest package.json', () => {
+        const root = mkdtempSync(join(tmpdir(), 'pkg-'));
+        mkdirSync(join(root, 'dist', 'src'), { recursive: true });
+        writeFileSync(join(root, 'package.json'), JSON.stringify({ version: '9.8.7' }));
+        expect(packageVersion(join(root, 'dist', 'src'))).toBe('9.8.7');
+    });
+});

package/dist/src/infrastructure/control-plane-http.js

@@ -14,6 +14,10 @@ export class HttpError extends Error {
         this.status = status;
     }
 }
+/** A named Organization's reach, as the API takes it (control-plane ADR-0084); nothing for any other scope. */
+const reachBody = (target, reach) => target.kind === 'org' && target.org !== undefined && reach !== undefined
+    ? { visibility: reach.visibility, ...(reach.visibility === 'selected' ? { selectedRepositories: [...reach.repos] } : {}) }
+    : {};
 /**
  * Adapter: the control-plane REST API over the platform's `fetch`.
  *
@@ -94,8 +98,8 @@ export class HttpControlPlane {
         const body = await this.#json('GET', `${this.#scopePath(target)}/secrets`);
         return body.secrets;
     }
-    async setSecret(target, name, value) {
-        await this.#noContent('PUT', `${this.#scopePath(target)}/secrets/${encodeURIComponent(name)}`, { value });
+    async setSecret(target, name, value, reach) {
+        await this.#noContent('PUT', `${this.#scopePath(target)}/secrets/${encodeURIComponent(name)}`, { value, ...reachBody(target, reach) });
     }
     /**
      * `apex logout`: revoke the token this client authenticates with. A 401 means
@@ -115,14 +119,16 @@ export class HttpControlPlane {
         const body = await this.#json('GET', `${this.#scopePath(target)}/variables`);
         return body.variables;
     }
-    async setVariable(target, name, value) {
-        await this.#noContent('PUT', `${this.#scopePath(target)}/variables/${encodeURIComponent(name)}`, { value });
+    async setVariable(target, name, value, reach) {
+        await this.#noContent('PUT', `${this.#scopePath(target)}/variables/${encodeURIComponent(name)}`, { value, ...reachBody(target, reach) });
     }
     async deleteVariable(target, name) {
         return await this.#deleted(`${this.#scopePath(target)}/variables/${encodeURIComponent(name)}`);
     }
     #scopePath(target) {
-        return target.kind === 'org' ? '/api/v1/org' : this.#repoPath(target.owner, target.repo);
+        if (target.kind === 'repo')
+            return this.#repoPath(target.owner, target.repo);
+        return target.org === undefined ? '/api/v1/org' : `/api/v1/orgs/${encodeURIComponent(target.org)}`;
     }
     async #noContent(method, path, body) {
         const response = await this.#request(method, path, body);
@@ -239,13 +245,19 @@ export class HttpControlPlane {
         return body.accepted;
     }
     async departures() {
-        return (await this.#json('GET', '/api/v1/admin/departures')).departures;
+        return (await this.#json('GET', '/api/v1/console/departures')).departures;
     }
     async purgeDeparture(installationId, apply) {
         return await this.#json('POST', `/api/v1/departures/${installationId}/purge${apply ? '?apply=true' : ''}`);
     }
+    async repositoryDepartures() {
+        return (await this.#json('GET', '/api/v1/console/repository-departures')).departures;
+    }
+    async purgeRepositoryDeparture(repoId, apply) {
+        return await this.#json('POST', `/api/v1/repository-departures/${repoId}/purge${apply ? '?apply=true' : ''}`);
+    }
     async accountsBackfill(input, apply) {
-        return await this.#json('POST', `/api/v1/admin/accounts/backfill${apply ? '?apply=true' : ''}`, input);
+        return await this.#json('POST', `/api/v1/console/accounts/backfill${apply ? '?apply=true' : ''}`, input);
     }
     // ── complimentary access (control-plane ADR-0056, ADR-0079): the admin API's shapes, unchanged ──
     /**
@@ -259,7 +271,7 @@ export class HttpControlPlane {
             const query = new URLSearchParams({ limit: '200' });
             if (cursor !== undefined)
                 query.set('cursor', cursor);
-            const body = await this.#json('GET', `/api/v1/admin/grants?${query.toString()}`);
+            const body = await this.#json('GET', `/api/v1/console/grants?${query.toString()}`);
             all.push(...body.grants);
             cursor = body.page?.nextCursor;
             if (cursor === undefined)
@@ -268,22 +280,22 @@ export class HttpControlPlane {
         return all;
     }
     async createGrant(body) {
-        return await this.#json('POST', '/api/v1/admin/grants', body);
+        return await this.#json('POST', '/api/v1/console/grants', body);
     }
     async updateGrant(id, body) {
-        return (await this.#json('PATCH', `/api/v1/admin/grants/${encodeURIComponent(id)}`, body)).grant;
+        return (await this.#json('PATCH', `/api/v1/console/grants/${encodeURIComponent(id)}`, body)).grant;
     }
     async revokeGrant(id) {
-        return await this.#json('DELETE', `/api/v1/admin/grants/${encodeURIComponent(id)}`);
+        return await this.#json('DELETE', `/api/v1/console/grants/${encodeURIComponent(id)}`);
     }
     async listInstallations() {
-        return (await this.#json('GET', '/api/v1/admin/installations')).installations;
+        return (await this.#json('GET', '/api/v1/console/installations')).installations;
     }
     async accountsUnconnected() {
-        return (await this.#json('GET', '/api/v1/admin/accounts/unconnected')).installations;
+        return (await this.#json('GET', '/api/v1/console/accounts/unconnected')).installations;
     }
     async accountsConnect(input) {
-        return await this.#json('POST', '/api/v1/admin/accounts/connect', input);
+        return await this.#json('POST', '/api/v1/console/accounts/connect', input);
     }
     async actionPolicy(owner) {
         return await this.#json('GET', `/api/v1/orgs/${encodeURIComponent(owner)}/action-policy`);
@@ -511,6 +523,12 @@ export class HttpControlPlane {
             throw new Error(await this.#errorMessage(response));
         return (await this.#decode(response));
     }
+    async getForkApproval(owner, repo) {
+        return await this.#json('GET', `${this.#repoPath(owner, repo)}/fork-approval`);
+    }
+    async setForkApproval(owner, repo, policy) {
+        return await this.#json('PUT', `${this.#repoPath(owner, repo)}/fork-approval`, { policy });
+    }
     async listSchedules(owner, repo) {
         return await this.#json('GET', `${this.#repoPath(owner, repo)}/schedules`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apex-actions/cli",
-  "version": "0.86.0",
+  "version": "0.88.0",
   "license": "SEE LICENSE IN LICENSE",
   "//files": "Without this npm ships src, test and the CI config alongside the binary a user installs.",
   "files": [