@apex-actions/cli 0.86.0 → 0.87.0

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/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/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/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/package.json

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