@imagina-build/ias-cli 0.0.0 → 0.1.0

package/src/cli.mjs

@@ -0,0 +1,231 @@
+// The router of ias: ias <command> [<subcommand>] [options]. Each command is a folder of src/commands with an index.mjs
+// whose default export is the command, or a list of them, so a new one (vault, credentials, env…) needs no change here:
+//   { name, summary, description?, aliases?, pending?, options?, positionals?, run(context) }
+//   { name, summary, description?, subcommands: [<the same, without subcommands>] }
+// run gets { values, positionals, output, env, cwd, sleep?, openUrl? } and returns the result, which --json prints; the
+// tests pass sleep and openUrl so that waiting for a passkey takes no time and no browser opens.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import process from 'node:process';
+import { parseArgs } from 'node:util';
+import { UsageError } from './errors.mjs';
+import { EXIT_CODE, createOutput } from './output.mjs';
+import { cleanup } from './process.mjs';
+
+const COMMANDS_DIR = new URL('./commands/', import.meta.url);
+
+export { EXIT_CODE };
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+
+/** The order of the commands in the help; the rest follow by name. */
+const ORDER = ['login', 'logout', 'whoami', 'apps', 'init', 'doctor', 'sdk', 'update', 'dist', 'credentials', 'env', 'vault'];
+
+/** The options of every command. */
+export const GLOBAL_OPTIONS = {
+  project: { type: 'string', value: '<folder>', description: 'The folder of the app (the current one by default).' },
+  json: { type: 'boolean', description: 'The result as one JSON document on stdout; the progress goes to stderr.' },
+  help: { type: 'boolean', short: 'h', description: 'The help of the command.' },
+};
+
+/** The commands of src/commands, in the order of the help. */
+export async function loadCommands() {
+  const folders = readdirSync(COMMANDS_DIR, { withFileTypes: true }).filter((entry) => entry.isDirectory() && existsSync(new URL(`${entry.name}/index.mjs`, COMMANDS_DIR)));
+  const commands = [];
+  for (const folder of folders) commands.push(...[(await import(new URL(`${folder.name}/index.mjs`, COMMANDS_DIR))).default].flat().filter(Boolean));
+  const rank = (command) => (command.pending ? 1000 : ORDER.includes(command.name) ? ORDER.indexOf(command.name) : 100);
+  return commands.sort((a, b) => rank(a) - rank(b) || a.name.localeCompare(b.name));
+}
+
+const named = (list, name) => list.find((command) => command.name === name || command.aliases?.includes(name));
+
+/** The closest name, for «did you mean»: at most two letters away. */
+function closest(name, names) {
+  const distance = (a, b) => {
+    const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i += 1) {
+      let previous = row[0];
+      row[0] = i;
+      for (let j = 1; j <= b.length; j += 1) {
+        const current = row[j];
+        row[j] = Math.min(row[j] + 1, row[j - 1] + 1, previous + (a[i - 1] === b[j - 1] ? 0 : 1));
+        previous = current;
+      }
+    }
+    return row[b.length];
+  };
+  return names.map((candidate) => [candidate, distance(name, candidate)]).filter(([, score]) => score <= 2).sort((a, b) => a[1] - b[1])[0]?.[0];
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Help.
+
+const optionLabel = (name, option) => `${option.short ? `-${option.short}, ` : ''}--${name}${option.value ? ` ${option.value}` : ''}`;
+
+function table(rows) {
+  const width = Math.max(...rows.map(([left]) => left.length));
+  return rows.map(([left, right]) => `  ${left.padEnd(width)}  ${right}`).join('\n');
+}
+
+function usageLine(path, leaf) {
+  const positionals = (leaf.positionals ?? []).map((positional) => (positional.optional ? `[<${positional.name}>]` : `<${positional.name}>`));
+  const options = Object.entries(leaf.options ?? {}).map(([name, option]) => `[--${name}${option.value ? ` ${option.value}` : ''}]`);
+  return ['ias', ...path, ...positionals, ...options, '[--project <folder>]', '[--json]'].join(' ');
+}
+
+export function generalHelp(commands) {
+  const ready = commands.filter((command) => !command.pending);
+  const pending = commands.filter((command) => command.pending);
+  return [
+    `ias ${VERSION}: Imagina Application Services from the terminal`,
+    '',
+    'usage: ias <command> [<subcommand>] [options]',
+    '',
+    'commands:',
+    table(ready.map((command) => [command.name, command.summary])),
+    ...(pending.length > 0 ? ['', 'coming:', table(pending.map((command) => [command.name, command.summary]))] : []),
+    '',
+    'options:',
+    table([...Object.entries(GLOBAL_OPTIONS).map(([name, option]) => [optionLabel(name, option), option.description]), ['-v, --version', 'The version of ias.']]),
+    '',
+    'ias <command> --help says more; packages/cli/README.md explains ias.json and the move from tools/.',
+  ].join('\n');
+}
+
+export function commandHelp(command) {
+  if (!command.subcommands) return leafHelp([command.name], command);
+  return [
+    `ias ${command.name}: ${command.summary}`,
+    ...(command.description ? ['', command.description] : []),
+    '',
+    `usage: ias ${command.name} <subcommand> [options]`,
+    '',
+    'subcommands:',
+    table(command.subcommands.map((subcommand) => [[subcommand.name, ...(subcommand.aliases ?? [])].join(', '), subcommand.summary])),
+    '',
+    `ias ${command.name} <subcommand> --help says more.`,
+  ].join('\n');
+}
+
+export function leafHelp(path, leaf) {
+  const positionals = leaf.positionals ?? [];
+  const options = { ...(leaf.options ?? {}), ...GLOBAL_OPTIONS };
+  return [
+    `ias ${path.join(' ')}: ${leaf.summary}`,
+    ...(leaf.description ? ['', leaf.description] : []),
+    '',
+    `usage: ${usageLine(path, leaf)}`,
+    ...(positionals.length > 0 ? ['', 'arguments:', table(positionals.map((positional) => [`<${positional.name}>`, positional.description ?? '']))] : []),
+    '',
+    'options:',
+    table(Object.entries(options).map(([name, option]) => [optionLabel(name, option), option.description ?? ''])),
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------------------------------------------------
+// Running a command.
+
+/** The arguments of `leaf`, parsed strictly: an unknown option or a missing argument is a UsageError. */
+export function parseCommandLine(path, leaf, args) {
+  const spec = Object.fromEntries(Object.entries({ ...(leaf.options ?? {}), ...GLOBAL_OPTIONS }).map(([name, { type, short, multiple }]) => [name, { type, ...(short ? { short } : {}), ...(multiple ? { multiple } : {}) }]));
+  const help = `ias ${path.join(' ')} --help lists them`;
+  let parsed;
+  try {
+    parsed = parseArgs({ args, options: spec, allowPositionals: true, strict: true });
+  } catch (error) {
+    const option = error.message.match(/'([^']+)'/)?.[1] ?? '';
+    if (error.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') throw new UsageError(`unknown option ${option}`, { fix: help });
+    if (error.code === 'ERR_PARSE_ARGS_INVALID_OPTION_VALUE') throw new UsageError(`${option.replace(/ <value>$/, '')} needs a value`, { fix: help });
+    throw new UsageError(error.message, { fix: help });
+  }
+  const { values, positionals } = parsed;
+  if (values.help) return { values, positionals };
+  const declared = leaf.positionals ?? [];
+  const usage = `usage: ${usageLine(path, leaf)}`;
+  if (positionals.length > declared.length) throw new UsageError(`ias ${path.join(' ')} takes ${declared.length === 0 ? 'no arguments' : declared.map((positional) => `<${positional.name}>`).join(' ')}, not «${positionals.slice(declared.length).join(' ')}»`, { fix: usage });
+  for (const [index, positional] of declared.entries()) {
+    const value = positionals[index];
+    if (value === undefined && !positional.optional) throw new UsageError(`ias ${path.join(' ')} needs <${positional.name}>`, { fix: `${positional.description ?? ''} ${usage}`.trim() });
+    if (value !== undefined && positional.pattern && !positional.pattern.test(value)) throw new UsageError(`<${positional.name}> is not valid («${value}»)`, { fix: positional.description ?? usage });
+  }
+  return { values, positionals };
+}
+
+/** The index of the first argument that is not an option (nor the value of --project), or -1. */
+function firstWord(args) {
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === '--project') index += 1;
+    else if (!args[index].startsWith('-')) return index;
+  }
+  return -1;
+}
+
+/**
+ * Runs ias with `argv` and returns the exit code: 0 when it worked, 1 when it failed and 2 when the command line does
+ * not parse. Errors are printed as «ias: what: how», or as { error } with --json.
+ */
+export async function main(argv = process.argv.slice(2), { env = process.env, cwd = process.cwd(), stdout = process.stdout, stderr = process.stderr, sleep, openUrl } = {}) {
+  const output = createOutput({ json: argv.includes('--json'), stdout, stderr });
+  const print = (text) => stdout.write(`${text}\n`);
+  try {
+    const commands = await loadCommands();
+    const at = firstWord(argv);
+    if (at === -1) {
+      if (argv.includes('-v') || argv.includes('--version')) {
+        print(output.json ? JSON.stringify({ version: VERSION }) : `ias ${VERSION}`);
+        return 0;
+      }
+      print(generalHelp(commands));
+      return argv.length === 0 || argv.includes('-h') || argv.includes('--help') ? 0 : 2;
+    }
+    // Options before the command (ias --json doctor) go after it and its subcommand.
+    let args = [...argv.slice(at + 1), ...argv.slice(0, at)];
+    const name = argv[at];
+    if (name === 'help') {
+      const words = args.filter((arg) => !arg.startsWith('-'));
+      const command = named(commands, words[0]);
+      if (!command) {
+        print(generalHelp(commands));
+        return words.length === 0 ? 0 : 2;
+      }
+      const subcommand = command.subcommands && named(command.subcommands, words[1]);
+      print(subcommand ? leafHelp([command.name, subcommand.name], subcommand) : commandHelp(command));
+      return 0;
+    }
+    const command = named(commands, name);
+    if (!command) {
+      const guess = closest(name, commands.map((candidate) => candidate.name));
+      throw new UsageError(`there is no command «${name}»`, { fix: guess ? `did you mean ias ${guess}? ias --help lists them` : 'ias --help lists them' });
+    }
+    let leaf = command;
+    const path = [command.name];
+    if (command.subcommands) {
+      const word = args[0];
+      if (word === undefined || word.startsWith('-')) {
+        if (args.includes('--help') || args.includes('-h')) {
+          print(commandHelp(command));
+          return 0;
+        }
+        throw new UsageError(`ias ${command.name} needs a subcommand`, { fix: `one of ${command.subcommands.map((subcommand) => subcommand.name).join(', ')}; ias ${command.name} --help says what each does` });
+      }
+      leaf = named(command.subcommands, word);
+      if (!leaf) {
+        const guess = closest(word, command.subcommands.map((subcommand) => subcommand.name));
+        throw new UsageError(`ias ${command.name} has no subcommand «${word}»`, { fix: guess ? `did you mean ias ${command.name} ${guess}? ias ${command.name} --help lists them` : `ias ${command.name} --help lists them` });
+      }
+      path.push(leaf.name);
+      args = args.slice(1);
+    }
+    const { values, positionals } = parseCommandLine(path, leaf, args);
+    if (values.help) {
+      print(leafHelp(path, leaf));
+      return 0;
+    }
+    const result = await leaf.run({ values, positionals, output, env, cwd, ...(sleep ? { sleep } : {}), ...(openUrl ? { openUrl } : {}) });
+    output.result(result);
+    return typeof result?.[EXIT_CODE] === 'number' ? result[EXIT_CODE] : 0;
+  } catch (error) {
+    output.fail(error);
+    return error instanceof UsageError ? 2 : 1;
+  } finally {
+    cleanup();
+  }
+}

package/src/commands/apps/index.mjs

@@ -0,0 +1,36 @@
+// ias apps: the applications the token can see (docs/technical/manage-api.md §4), or one of them. A robot token sees only its own.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { connect } from '../../manage.mjs';
+
+/** The lines that describe an application for people. */
+export function describeApplication(app) {
+  const lines = [`${app.code}  ${app.name}`, `  services      ${app.services.length > 0 ? app.services.join(', ') : 'none'}`];
+  if (app.ios) lines.push(`  ios           ${app.ios.bundle_id ?? '—'} (team ${app.ios.team_id ?? '—'})`);
+  if (app.android) lines.push(`  android       ${app.android.package ?? '—'}`);
+  if (app.updates) lines.push(`  updates       project ${app.updates.project}, channel ${app.updates.default_channel}, ${app.updates.manifest_url}`);
+  if (app.distribution) lines.push(`  distribution  project ${app.distribution.project}, ${app.distribution.install_url}`);
+  return lines;
+}
+
+async function apps(context) {
+  const client = connect(context, loadProject(resolve(context.cwd, context.values.project ?? '.')));
+  const [code] = context.positionals;
+  if (code) {
+    const { data } = await client.request('GET', `/apps/${encodeURIComponent(code)}`);
+    for (const line of describeApplication(data)) context.output.log(line);
+    return data;
+  }
+  const { data } = await client.request('GET', '/apps');
+  if (data.data.length === 0) context.output.log('No applications: create one in the panel (Aplicaciones › Crear aplicación).');
+  const width = Math.max(0, ...data.data.map((app) => app.code.length));
+  for (const app of data.data) context.output.log(`${app.code.padEnd(width)}  ${app.name}  (${app.services.join(', ') || 'no services'})`);
+  return data;
+}
+
+export default {
+  name: 'apps',
+  summary: 'The applications the token can see, or one of them in detail',
+  positionals: [{ name: 'code', optional: true, description: 'The code of one application, to see it in detail.', pattern: /^[a-z0-9][a-z0-9-]{0,31}$/ }],
+  run: apps,
+};

package/src/commands/auth/index.mjs

@@ -0,0 +1,141 @@
+// ias login, logout, whoami and teams: the personal token (iasp_…) of the management API (docs/technical/manage-api.md §2 and §3).
+// login authorizes this computer with the device flow (RFC 8628): it shows a code, opens the panel, where a member
+// approves it with a passkey, and asks for the token every `interval` seconds. The token goes to the macOS keychain, to
+// a file with mode 600 elsewhere, or nowhere on CI, where IAS_TOKEN is the token (token-store.mjs). It is never printed.
+// A personal token is of one team (docs/technical/phase-5.md §1.4): --team preselects it in the panel, where the member chooses
+// among theirs; a token for another team is another login, and `ias teams` lists the ones the person is in.
+import { spawnSync } from 'node:child_process';
+import { hostname } from 'node:os';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { loadProject } from '../../config.mjs';
+import { ApiError, IasError } from '../../errors.mjs';
+import { connect, manageClient, openUrl, serverOrigin, sleep } from '../../manage.mjs';
+import { forgetToken, saveToken, storeKind, storeLabel, storedToken } from '../../token-store.mjs';
+import { VERSION } from '../../cli.mjs';
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+
+/** The code of a team: lowercase letters, digits and hyphens, 2 to 32 (App\\Models\\Team::SLUG_PATTERN). */
+const TEAM_SLUG = /^[a-z0-9][a-z0-9-]{1,31}$/;
+
+/** The name of this computer, as the panel shows it: the one of System Settings on macOS. */
+function deviceName(env) {
+  if (process.platform === 'darwin') {
+    const result = spawnSync('scutil', ['--get', 'ComputerName'], { encoding: 'utf8', env });
+    if (result.status === 0 && result.stdout.trim()) return result.stdout.trim().slice(0, 100);
+  }
+  return hostname().slice(0, 100);
+}
+
+/**
+ * The device flow, from asking for a code to the token: { token, token_id, expires_at, member, team }. `team` is the
+ * code of the team to preselect in the panel. `wait` sleeps (seconds) and `open` opens the browser; both are injected
+ * by the tests.
+ */
+export async function authorize(client, { name, team, wait = sleep, open = () => false, output }) {
+  const { data: device } = await client.request('POST', '/auth/device', { auth: false, json: { client: 'ias-cli', client_version: VERSION, device_name: name, ...(team ? { team } : {}) } });
+  output.progress(`Your code: ${device.user_code}`);
+  const opened = open(device.verification_uri_complete);
+  output.progress(`${opened ? 'Opened' : 'Open'} ${device.verification_uri_complete}, check that the panel shows the same code, and approve it with a passkey.`);
+  let interval = Number(device.interval) || 5;
+  const deadline = Date.now() + (Number(device.expires_in) || 600) * 1000;
+  for (;;) {
+    await wait(interval);
+    try {
+      const { data } = await client.request('POST', '/auth/token', { auth: false, json: { device_code: device.device_code } });
+      return data;
+    } catch (error) {
+      if (!(error instanceof ApiError)) throw error;
+      if (error.code === 'authorization_pending' && Date.now() < deadline) continue;
+      if (error.code === 'slow_down') {
+        interval += 5;
+        continue;
+      }
+      if (error.code === 'access_denied') throw new IasError('a member of the team rejected this authorization', { fix: 'run ias login again if it was a mistake', code: 'access_denied' });
+      if (error.code === 'expired_token' || error.code === 'authorization_pending') throw new IasError('the code expired before anyone approved it', { fix: 'run ias login again and approve it within 10 minutes', code: 'expired_token' });
+      throw error;
+    }
+  }
+}
+
+async function login(context) {
+  const { env, output } = context;
+  const server = serverOrigin(projectOf(context), env);
+  const kind = storeKind(env);
+  const team = context.values.team;
+  if (team !== undefined && !TEAM_SLUG.test(team)) throw new IasError(`«${team}» is not the code of a team`, { fix: 'use the code the panel shows (Plataforma › Equipos, or ias teams): lowercase letters, digits and hyphens', code: 'usage' });
+  if (kind === 'none') throw new IasError('ias login keeps no token on CI', { fix: 'set IAS_TOKEN to a robot token of the application (iasr_…, created in the panel: the application › Settings › Access)', code: 'no_token_store' });
+  if (env.IAS_TOKEN) output.warn('IAS_TOKEN is set and wins over the token of ias login: unset it to use this one');
+  const client = manageClient(server, undefined, { wait: context.sleep ?? sleep });
+  const granted = await authorize(client, { name: context.values.name ?? deviceName(env), team, wait: context.sleep ?? sleep, open: context.values['no-browser'] ? () => false : (context.openUrl ?? ((url) => openUrl(url, env))), output });
+  const where = saveToken(server, granted.token, { env, kind });
+  const { member } = granted;
+  const role = granted.team ? `${member.role} of ${granted.team.slug}` : member.role;
+  output.log(`Logged in to ${server} as ${member.name} <${member.email}> (${role}). The token, valid until ${granted.expires_at}, is in ${where}.`);
+  return { server, member, team: granted.team ?? null, token: { id: granted.token_id, expires_at: granted.expires_at }, store: kind };
+}
+
+async function logout(context) {
+  const { env, output } = context;
+  const server = serverOrigin(projectOf(context), env);
+  const kind = storeKind(env);
+  const token = storedToken(server, { env, kind });
+  if (!token) {
+    output.log(`Not logged in to ${server}: there is no token in ${storeLabel(kind, env)}.`);
+    if (env.IAS_TOKEN) output.warn('IAS_TOKEN is set: ias logout does not revoke it; revoke a robot token in the panel');
+    return { server, revoked: false, forgotten: false };
+  }
+  let revoked = true;
+  try {
+    await manageClient(server, token, { wait: context.sleep ?? sleep }).request('DELETE', '/me/token');
+  } catch (error) {
+    if (!(error instanceof ApiError) || error.code !== 'token_invalid') throw error;
+    revoked = false; // already expired or revoked: forgetting it is all that is left
+  }
+  forgetToken(server, { env, kind });
+  output.log(revoked ? `Logged out of ${server}: the token is revoked and gone from ${storeLabel(kind, env)}.` : `The token of ${server} was no longer valid; it is gone from ${storeLabel(kind, env)}.`);
+  if (env.IAS_TOKEN) output.warn('IAS_TOKEN is still set and still works');
+  return { server, revoked, forgotten: true };
+}
+
+async function whoami(context) {
+  const { output } = context;
+  const client = connect(context, projectOf(context));
+  const { data } = await client.request('GET', '/me');
+  const { member, token, team } = data;
+  output.log(member ? `${member.name} <${member.email}>, ${member.role} of the team${team ? ` ${team.slug}` : ''}` : `A robot token of ${token.application}`);
+  output.log(`server   ${client.server}`);
+  if (team) output.log(`team     ${team.name} (${team.slug})`);
+  output.log(`token    ${token.kind} «${token.name}» from ${client.tokenSource}, until ${token.expires_at ?? 'it is revoked'}`);
+  output.log(`scopes   ${token.scopes.join(', ')}`);
+  return { server: client.server, source: client.tokenSource, ...data };
+}
+
+async function teams(context) {
+  const { output } = context;
+  const client = connect(context, projectOf(context));
+  const { data } = await client.request('GET', '/teams');
+  if (data.data.length === 0) output.log('You are not in any team.');
+  const width = Math.max(0, ...data.data.map((team) => team.slug.length));
+  for (const team of data.data) output.log(`${team.current ? '*' : ' '} ${team.slug.padEnd(width)}  ${team.name}  (${team.role})`);
+  if (data.data.length > 1) output.log('* is the team of this token: for another, run ias login --team <code>');
+  return data;
+}
+
+export default [
+  {
+    name: 'login',
+    summary: 'Authorize this computer with a passkey and keep its personal token',
+    description: 'Shows a code and opens the panel (Authorize the CLI), where a member of the team approves it with a passkey. The token (iasp_…, 90 days) goes to the macOS keychain, or to a file with mode 600 ($XDG_CONFIG_HOME/ias/tokens.json) elsewhere; IAS_TOKEN_STORE (keychain, file) chooses. A token is of one team: --team preselects it in the panel, where you choose among yours (ias teams lists them); logging in for another team replaces the token of this server. On CI there is no login: IAS_TOKEN holds a robot token. The server is IAS_SERVER, server of ias.json or ias.imagina.build.',
+    options: {
+      name: { type: 'string', value: '"…"', description: 'The name the panel shows for this computer (its name by default).' },
+      team: { type: 'string', value: '<code>', description: 'The code of the team the token is for (the panel asks if you have several and it is not given).' },
+      'no-browser': { type: 'boolean', description: 'Do not open the browser: print the link only.' },
+    },
+    run: login,
+  },
+  { name: 'logout', summary: 'Revoke the token of this computer and forget it', run: logout },
+  { name: 'whoami', summary: 'Who the token belongs to, its team, where it comes from and its scopes', run: whoami },
+  { name: 'teams', summary: 'The teams you are in, and which one the token is of', run: teams },
+];

package/src/commands/build/follow.mjs

@@ -0,0 +1,168 @@
+// Following builds on the server (docs/technical/runner-api.md §4): their status every 5 s and their log as it comes, and the
+// download of their artifacts with the SHA-256 checked. ias build, ias builds and ias submit share it. The upload and
+// download URLs are presigned: they are never printed and never get the token.
+import { createHash } from 'node:crypto';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { ApiError, IasError } from '../../errors.mjs';
+import { sleep } from '../../manage.mjs';
+
+const BUILD_NOT_FOUND = 'ias builds list shows the builds of the application (a robot token sees only its own); ias dist list, the install pages\'';
+
+/**
+ * The management client with the hint of a build of IAS for build_not_found, which HINTS gives to the distribution
+ * API of ias dist.
+ */
+export function buildsClient(client) {
+  return {
+    ...client,
+    async request(...args) {
+      try {
+        return await client.request(...args);
+      } catch (error) {
+        if (error instanceof ApiError && error.code === 'build_not_found') error.hint = BUILD_NOT_FOUND;
+        throw error;
+      }
+    },
+  };
+}
+
+/** The states a build or a submission ends in. */
+export const FINISHED = Object.freeze(['succeeded', 'failed', 'canceled', 'expired', 'rejected']);
+export const isFinished = (status) => FINISHED.includes(status);
+
+const FILE = /^[A-Za-z0-9][A-Za-z0-9 ._()+-]{0,199}$/;
+const LOCAL = (hostname) => ['localhost', '127.0.0.1', '[::1]'].includes(hostname) || hostname.endsWith('.test');
+
+/** A URL the server gave to upload or download a file: https, or a local host to try it. */
+export function transferUrl(text) {
+  const url = URL.canParse(text) ? new URL(text) : null;
+  if (!url || !(url.protocol === 'https:' || (url.protocol === 'http:' && LOCAL(url.hostname)))) throw new IasError('the server gave a transfer URL that is not https', { fix: 'the code and the builds only travel over https: check the server (FILESYSTEM_DISK and the bucket of the builds)', code: 'transfer_url_invalid' });
+  return url;
+}
+
+/** PUTs the tarball of the code to the presigned URL of a new build. */
+export async function uploadSource(upload, source) {
+  const url = transferUrl(upload.url);
+  let response;
+  try {
+    response = await fetch(url, { method: upload.method ?? 'PUT', headers: { ...(upload.headers ?? {}), 'content-length': String(source.bytes) }, body: readFileSync(source.file) });
+  } catch (error) {
+    throw new IasError(`uploading the code failed (${error.cause?.code ?? error.message})`, { fix: 'check the connection and run ias build again: the build waits for its code for 60 minutes' });
+  }
+  if (!response.ok) throw new IasError(`uploading the code failed: the bucket answered ${response.status}`, { fix: 'run ias build again (the upload URL lasts 60 minutes); if it goes on, check the bucket of the builds' });
+}
+
+/** One line about a build: platform, profile, version, number and status. */
+export function buildLine(build) {
+  const number = build.build_number === null || build.build_number === undefined ? '' : ` (${build.build_number})`;
+  const runner = build.runner?.name ? ` on ${build.runner.name}` : '';
+  return `${build.platform} ${build.profile} ${build.version}${number}: ${build.status}${build.step ? ` (${build.step})` : ''}${runner}`;
+}
+
+/** What to say when a build reaches a status. */
+function statusLine(build) {
+  if (build.status === 'awaiting_approval') return `${buildLine(build)}: an owner approves it with a passkey at ${build.approval_url}`;
+  if (build.status === 'failed' && build.error) return `${buildLine(build)}: ${build.error.code}${build.error.step ? ` at ${build.error.step}` : ''}${build.error.message ? `: ${build.error.message}` : ''}`;
+  return buildLine(build);
+}
+
+/**
+ * Follows `builds` until each one ends: the status every `interval` seconds and the new chunks of its log, the step as
+ * a header. With several builds, each line says its platform. Returns the builds as they ended.
+ */
+export async function follow(context, client, builds, { interval = 5, logs = true } = {}) {
+  const { output } = context;
+  const wait = context.sleep ?? sleep;
+  const many = builds.length > 1;
+  const state = builds.map((build) => ({ build, next: -1, step: undefined, said: `${build.status}|${build.step}`, logsDone: !logs }));
+  const prefix = (build) => (many ? `[${build.platform}] ` : '');
+  for (;;) {
+    for (const entry of state) {
+      if (isFinished(entry.build.status) && entry.logsDone) continue;
+      let ended = null;
+      if (!isFinished(entry.build.status)) {
+        entry.build = (await client.request('GET', `/builds/${entry.build.id}`)).data;
+        const said = `${entry.build.status}|${entry.build.step}`;
+        if (said !== entry.said) {
+          entry.said = said;
+          // The status a build ends in goes after the last lines of its log.
+          if (isFinished(entry.build.status)) ended = entry.build;
+          else output.progress(`${prefix(entry.build)}${statusLine(entry.build)}`);
+        }
+      }
+      if (!entry.logsDone) {
+        const { data: page } = await client.request('GET', `/builds/${entry.build.id}/logs?after=${entry.next}`);
+        for (const chunk of page.data ?? []) {
+          if (chunk.step && chunk.step !== entry.step) {
+            entry.step = chunk.step;
+            output.progress(`${prefix(entry.build)}── ${chunk.step}`);
+          }
+          for (const line of String(chunk.text).replace(/\n$/, '').split('\n')) output.progress(`${prefix(entry.build)}${line}`);
+        }
+        if (Number.isInteger(page.next)) entry.next = page.next;
+        entry.logsDone = page.finished === true || (isFinished(entry.build.status) && (page.data ?? []).length === 0);
+      }
+      if (ended) output.progress(`${prefix(ended)}${statusLine(ended)}`);
+    }
+    if (state.every((entry) => isFinished(entry.build.status) && entry.logsDone)) return state.map((entry) => entry.build);
+    await wait(interval);
+  }
+}
+
+/** The folder the artifacts of `build` go to by default: ~/ias-builds/<app>/<platform>-<version>-<number>. */
+export function defaultFolder(context, build) {
+  return join(context.env.HOME || homedir(), 'ias-builds', build.app, `${build.platform}-${build.version}-${build.build_number ?? build.id.slice(0, 8)}`);
+}
+
+/** Streams `url` to `path` while hashing it; the file appears only if its size and SHA-256 are the expected ones. */
+async function downloadTo(url, path, { bytes, sha256 }) {
+  const response = await fetch(transferUrl(url));
+  if (!response.ok || !response.body) throw new IasError(`downloading ${path} failed: ${response.status}`, { fix: 'run it again: the download links last 15 minutes' });
+  const hash = createHash('sha256');
+  let size = 0;
+  const counted = new Transform({
+    transform(chunk, _encoding, done) {
+      hash.update(chunk);
+      size += chunk.length;
+      done(null, chunk);
+    },
+  });
+  const part = `${path}.part`;
+  try {
+    await pipeline(Readable.fromWeb(response.body), counted, createWriteStream(part, { mode: 0o644 }));
+    const got = hash.digest('hex');
+    if (size !== bytes || got !== sha256) throw new IasError(`${path} is not the file the server describes (${size} bytes, SHA-256 ${got.slice(0, 12)}…)`, { fix: 'download it again; if it goes on, the file in the bucket was altered', code: 'artifact_mismatch' });
+    renameSync(part, path);
+  } finally {
+    rmSync(part, { force: true });
+  }
+}
+
+/**
+ * Downloads the artifacts of `build` (those of `kinds`, or all) into `folder`, each checked against its size and
+ * SHA-256. A file already there with that SHA-256 is kept. Returns [{ kind, file, path, bytes, sha256, kept }].
+ */
+export async function downloadArtifacts(context, client, build, { folder = defaultFolder(context, build), kinds } = {}) {
+  const { output } = context;
+  const { data } = await client.request('GET', `/builds/${build.id}/artifacts`);
+  const wanted = (data.data ?? []).filter((artifact) => !kinds || kinds.includes(artifact.kind));
+  if (wanted.length === 0) {
+    output.progress(`${build.platform}: no artifacts${kinds ? ` of kind ${kinds.join(', ')}` : ''} to download`);
+    return [];
+  }
+  mkdirSync(folder, { recursive: true });
+  const saved = [];
+  for (const artifact of wanted) {
+    if (typeof artifact.file !== 'string' || !FILE.test(artifact.file)) throw new IasError(`the server names an artifact «${artifact.file}», which is not a file name`, { fix: 'nothing was written outside the folder; report it', code: 'artifact_name_invalid' });
+    const path = join(folder, artifact.file);
+    const kept = existsSync(path) && createHash('sha256').update(readFileSync(path)).digest('hex') === artifact.sha256;
+    if (!kept) await downloadTo(artifact.download_url, path, artifact);
+    output.progress(`  ${artifact.kind.padEnd(8)} ${path}${kept ? ' (already there)' : ''}`);
+    saved.push({ kind: artifact.kind, file: artifact.file, path, bytes: artifact.bytes, sha256: artifact.sha256, kept });
+  }
+  return saved;
+}