@imagina-build/ias-cli 0.0.0 → 0.1.0

package/src/commands/build/index.mjs

@@ -0,0 +1,110 @@
+// ias build: a build of the app on a runner of IAS (docs/technical/runner-api.md §4), or on this Mac with --local. It sends the
+// commit of a clean working tree: the tarball of git archive, its SHA-256 and size, and the build profile of ias.json
+// resolved; uploads the code to the presigned URL; and completes it. A store build then waits for an owner's approval
+// with a passkey, so ias build opens its page. It follows the status and the log until the build ends, and with --wait
+// downloads its artifacts, checked against their SHA-256. Nothing secret travels: the credentials are sealed in the
+// vault and only the runner opens them.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { connect, openUrl } from '../../manage.mjs';
+import { EXIT_CODE } from '../../output.mjs';
+import { buildLine, buildsClient, downloadArtifacts, follow, uploadSource } from './follow.mjs';
+import { localBuilds } from './local.mjs';
+import { platformsOf, profileConfig, remoteProblem } from './profile.mjs';
+import { appConfigOf, archive, buildNumberOf, repository } from './source.mjs';
+
+const MESSAGE_LENGTH = 1000;
+
+/** The ias.json of the app, which a build needs: its app and its build profiles. */
+function configOf(context) {
+  const project = loadProject(resolve(context.cwd, context.values.project ?? '.'));
+  if (!project.config) throw new IasError(`there is no ias.json in ${project.dir}`, { fix: 'ias init writes it, with the build profiles of eas.json' });
+  if (!project.config.app) throw new IasError('ias.json has no app', { fix: 'set app to the code of the application in IAS (ias apps lists them)' });
+  return project;
+}
+
+async function build(context) {
+  const { values, env, output } = context;
+  const project = configOf(context);
+  const platforms = platformsOf(values.platform);
+  const profileName = values.profile ?? 'production';
+  const profile = profileConfig(project.config, profileName);
+  if (values.message !== undefined && values.message.length > MESSAGE_LENGTH) throw new IasError(`--message has ${values.message.length} characters`, { fix: `keep it under ${MESSAGE_LENGTH}` });
+  const repo = repository(project.dir);
+
+  if (values.local) {
+    if (values.detach) throw new IasError('--detach is for builds on the server', { fix: 'a local build runs here until it ends' });
+    const results = await localBuilds(context, { root: repo.root, platforms, profileName });
+    return { local: true, commit: repo.commit, builds: results };
+  }
+  for (const platform of platforms) {
+    const problem = remoteProblem(profile, platform);
+    if (problem) throw new IasError(`the profile ${profileName} is ${problem}, which the runners of IAS do not build yet`, { fix: `build it on this Mac: ias build --local --platform ${platform} --profile ${profileName}`, code: 'profile_not_remote' });
+  }
+  const expo = appConfigOf(repo.root, repo.commit);
+  const client = buildsClient(connect(context, project));
+  const source = await archive(repo.root, repo.commit);
+  output.progress(`${project.config.app} ${profileName} (${profile.distribution}, ${profile.environment}) ${expo.version} from ${repo.commit.slice(0, 10)}: ${source.bytes} bytes of code, SHA-256 ${source.sha256}`);
+  const message = (values.message ?? repo.subject).slice(0, MESSAGE_LENGTH) || null;
+
+  const launched = [];
+  for (const platform of platforms) {
+    const body = {
+      platform,
+      profile: profileName,
+      profile_config: profile,
+      commit: repo.commit,
+      source: { sha256: source.sha256, bytes: source.bytes },
+      version: expo.version,
+      build_number: buildNumberOf(expo, platform),
+      message,
+      bundle_env: project.config.updates?.bundleEnv ?? [],
+    };
+    const { data: created } = await client.request('POST', `/apps/${project.config.app}/builds`, { json: body });
+    const { upload, ...made } = created;
+    output.progress(`${platform}: build ${made.id}, number ${made.build_number ?? 'of the runner'}; uploading the code…`);
+    await uploadSource(upload, source);
+    const { data: completed } = await client.request('POST', `/builds/${made.id}/source/complete`);
+    if (completed.status === 'awaiting_approval') {
+      const opened = (context.openUrl ?? ((url) => openUrl(url, env)))(completed.approval_url);
+      output.progress(`${platform}: ${opened ? 'opened' : 'open'} ${completed.approval_url}`);
+      output.progress(`  an owner checks it and approves it with a passkey; the panel shows the hash ${completed.hash}`);
+    } else {
+      output.progress(`${platform}: ${buildLine(completed)}`);
+    }
+    launched.push(completed);
+  }
+
+  if (values.detach) {
+    for (const made of launched) output.log(`${made.id}  ${buildLine(made)}  (ias builds logs ${made.id} --follow)`);
+    return { commit: repo.commit, source: { sha256: source.sha256, bytes: source.bytes }, builds: launched };
+  }
+  output.progress('Following the build (Ctrl-C stops following, not the build: ias builds cancel <id> cancels it)…');
+  const finished = await follow(context, client, launched);
+  const downloads = [];
+  for (const done of finished) {
+    output.log(`${done.id}  ${buildLine(done)}`);
+    if (values.wait && done.status === 'succeeded') downloads.push(...(await downloadArtifacts(context, client, done, values.out ? { folder: resolve(context.cwd, values.out, done.platform) } : {})).map((file) => ({ build: done.id, ...file })));
+  }
+  const result = { commit: repo.commit, source: { sha256: source.sha256, bytes: source.bytes }, builds: finished, ...(values.wait ? { downloads } : {}) };
+  if (finished.some((done) => done.status !== 'succeeded')) result[EXIT_CODE] = 1;
+  return result;
+}
+
+export default {
+  name: 'build',
+  summary: 'Build the app on a runner of IAS (or on this Mac with --local), from the commit of a clean working tree',
+  description: 'Sends the commit (git archive), its SHA-256 and the build profile of ias.json resolved, and waits: a store build for the approval of an owner with a passkey (it opens the page), then the runner. It follows the status and the log until the build ends; Ctrl-C stops following, not the build. The version and the build number come from app.json; with autoIncrement, the server gives the next number (ias version). A store build needs a personal token (ias login); an internal one also takes a robot token with builds:create.',
+  options: {
+    platform: { type: 'string', value: 'ios|android|all', description: 'The platforms (all by default: one build each, iOS first).' },
+    profile: { type: 'string', value: '<name>', description: 'The build profile of ias.json (production by default).' },
+    message: { type: 'string', value: '"…"', description: 'What the build is (the subject of the commit by default); internal builds show it as their notes.' },
+    wait: { type: 'boolean', description: 'When it succeeds, download its artifacts (to ~/ias-builds/<app>/… or --out). With --local, wait for a build of this Mac that holds the lock.' },
+    out: { type: 'string', value: '<folder>', description: 'Where the artifacts go (one folder per platform), or the output of --local.' },
+    detach: { type: 'boolean', description: 'Do not follow the build: launch it, open the approval and leave (ias builds logs <id> --follow follows it later).' },
+    local: { type: 'boolean', description: 'Build on this Mac with @imagina/ias-runner, one platform after the other: nothing goes to the server.' },
+    credentials: { type: 'string', value: '<op://vault/item|folder>', description: 'With --local: the signing material (IAS_IOS_CREDENTIALS or IAS_ANDROID_CREDENTIALS by default).' },
+  },
+  run: build,
+};

package/src/commands/build/local.mjs

@@ -0,0 +1,69 @@
+// ias build --local: the build on this Mac, by @imagina/ias-runner imported here (it is the same pipeline the runners
+// use), one platform after the other, never two at a time. The signing material is the runner's CredentialSource
+// (op://vault/item or a 700 folder); nothing goes to the server. IAS_RUNNER_MODULE points at another copy of the runner.
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { IasError } from '../../errors.mjs';
+
+const RUNNER = new URL('../../../../runner/src/index.mjs', import.meta.url);
+
+/** The runner module: IAS_RUNNER_MODULE, or the one of this repository (packages/runner). */
+async function runnerModule(context) {
+  const where = context.env.IAS_RUNNER_MODULE ? pathToFileURL(resolve(context.cwd, context.env.IAS_RUNNER_MODULE)) : RUNNER;
+  try {
+    return await import(where.href);
+  } catch (error) {
+    throw new IasError(`@imagina/ias-runner is not at ${where.pathname} (${error.code ?? error.message})`, { fix: 'ias build --local needs the runner of packages/runner beside the CLI, or IAS_RUNNER_MODULE pointing at its src/index.mjs', code: 'runner_missing' });
+  }
+}
+
+/** The errors of the runner that a person fixes, with their message and a code; others go on as they are. */
+const FIXES = {
+  ProjectError: 'fix ias.json or app.json and commit them',
+  CredentialSourceError: 'pass --credentials op://<vault>/<item> or a 700 folder, or set IAS_IOS_CREDENTIALS and IAS_ANDROID_CREDENTIALS',
+  BuildLockedError: 'wait for it to end, or pass --wait to wait for it here',
+  BuildError: 'the log of each step is in the folder of the build; fix it and run it again',
+};
+
+/** Builds each platform of `platforms` with profile `profileName` on this Mac. Returns [{ platform, ...result }]. */
+export async function localBuilds(context, { root, platforms, profileName }) {
+  const { values, env, output } = context;
+  const runner = await runnerModule(context);
+  const results = [];
+  for (const platform of platforms) {
+    const controller = new AbortController();
+    const stop = (signal) => {
+      if (controller.signal.aborted) return;
+      output.warn(`${signal}: stopping the build and cleaning up`);
+      controller.abort();
+    };
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+    for (const signal of signals) process.on(signal, stop);
+    try {
+      const { job, warnings } = runner.createLocalJob({ projectDir: root, platform, profileName });
+      for (const warning of warnings) output.warn(warning);
+      const shell = runner.createShell();
+      const spec = values.credentials ?? env[platform === 'ios' ? 'IAS_IOS_CREDENTIALS' : 'IAS_ANDROID_CREDENTIALS'];
+      const credentials = runner.credentialSource(spec, { shell, projectDir: root });
+      const out = values.out ? resolve(context.cwd, values.out) : runner.defaultOut(job.app);
+      const jobs = runner.defaultJobs();
+      output.progress(`${job.app} ${platform} ${job.profile} (${job.distribution}, ${job.environment}, ${job.format}) from ${job.source.commit.slice(0, 10)} on this Mac, ${jobs} jobs, low priority`);
+      const reporter = {
+        step: ({ index, total, title }) => output.progress(`  ${index + 1}/${total} ${title}`),
+        info: (text) => output.progress(`      ${text}`),
+        warn: (text) => output.warn(text),
+      };
+      const result = await runner.runBuild(job, { shell, credentials, out, jobs, wait: values.wait === true, reporter, signal: controller.signal });
+      const artifact = result.artifacts?.find((file) => file.kind === job.format);
+      output.log(`${platform}: ${artifact ? `${result.folder}/${artifact.file}` : result.folder} — ${result.identifier} ${result.version} (${result.buildNumber})`);
+      results.push({ platform, folder: result.folder, artifacts: result.artifacts ?? [], identifier: result.identifier, version: result.version, buildNumber: result.buildNumber, resultFile: result.resultFile ?? null });
+    } catch (error) {
+      if (FIXES[error.name]) throw new IasError(`${platform}: ${error.message}`, { fix: FIXES[error.name], code: `local_${error.name.replace(/Error$/, '').replace(/[A-Z]/g, (letter, at) => `${at ? '_' : ''}${letter.toLowerCase()}`)}` });
+      throw error;
+    } finally {
+      for (const signal of signals) process.removeListener(signal, stop);
+    }
+  }
+  return results;
+}

package/src/commands/build/profile.mjs

@@ -0,0 +1,50 @@
+// The build profile of ias.json that a build sends (docs/technical/runner-api.md §4.2): `extends` followed and merged, as eas.json
+// does (ios and android key by key), with distribution and environment made explicit. The server validates it against
+// packages/cli/schema/ias.schema.json and keeps it in the job; the runner reads the same profile from the commit.
+import { IasError } from '../../errors.mjs';
+
+export const PLATFORMS = Object.freeze(['ios', 'android']);
+const ENVIRONMENTS = ['development', 'preview', 'production'];
+
+/** The platforms of --platform: ios, android or all (both, iOS first). */
+export function platformsOf(value = 'all') {
+  if (value === 'all') return [...PLATFORMS];
+  if (PLATFORMS.includes(value)) return [value];
+  throw new IasError(`--platform is ios, android or all, not «${value}»`, { fix: 'ias build --platform ios builds only for iOS' });
+}
+
+/**
+ * The profile `name` of `config` as the server takes it: what it extends merged under it, without `extends`, and its
+ * distribution (store by default) and environment (the profile's name if it is one, else by its distribution) filled.
+ */
+export function profileConfig(config, name) {
+  const profiles = config?.build ?? {};
+  const chain = [];
+  for (let current = name; current !== undefined; current = profiles[current].extends) {
+    if (!profiles[current]) {
+      throw new IasError(chain.length === 0 ? `ias.json has no build profile «${name}»` : `the build profile ${chain.at(-1)} extends ${current}, which does not exist`, {
+        fix: Object.keys(profiles).length > 0 ? `the profiles are ${Object.keys(profiles).join(', ')}: pass one with --profile` : 'add the build profiles to ias.json (ias init writes development, preview and production)',
+        code: 'profile_not_found',
+      });
+    }
+    if (chain.includes(current)) throw new IasError(`the build profile ${name} extends itself (${[...chain, current].join(' → ')})`, { fix: 'fix the extends of ias.json' });
+    chain.push(current);
+  }
+  const merged = {};
+  for (const profile of chain.map((key) => profiles[key]).reverse()) {
+    const { extends: _, ios, android, ...rest } = profile;
+    Object.assign(merged, rest);
+    if (ios) merged.ios = { ...merged.ios, ...ios };
+    if (android) merged.android = { ...merged.android, ...android };
+  }
+  const distribution = merged.distribution ?? 'store';
+  const environment = merged.environment ?? (ENVIRONMENTS.includes(name) ? name : merged.developmentClient ? 'development' : distribution === 'internal' ? 'preview' : 'production');
+  return { ...merged, distribution, environment };
+}
+
+/** Why the runners of the server cannot make this build yet (a development client, the Simulator), or null. */
+export function remoteProblem(profile, platform) {
+  if (profile.developmentClient === true) return 'a development build (developmentClient)';
+  if (platform === 'ios' && profile.ios?.simulator === true) return 'a build for the iOS Simulator';
+  return null;
+}

package/src/commands/build/source.mjs

@@ -0,0 +1,71 @@
+// The code a build sends: the commit of a clean working tree at the root of its repository, as the tarball of git
+// archive, with its SHA-256 and size (docs/technical/runner-api.md §4.2), and the version and build number of its app.json.
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createReadStream, realpathSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { IasError } from '../../errors.mjs';
+import { temporary } from '../../process.mjs';
+
+const git = (cwd, args) => spawnSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+
+/**
+ * The repository of the app: { root, commit, subject }. Stops unless the app is at the root of a git repository (the
+ * build sends the whole commit and the runner reads ias.json at its root) and the working tree is clean (the server
+ * only sees the commit, so a change that is not committed would not be in the build).
+ */
+export function repository(projectDir) {
+  const top = git(projectDir, ['rev-parse', '--show-toplevel']);
+  if (top.error) throw new IasError('git is not installed', { fix: 'install the command line tools of Xcode (xcode-select --install)' });
+  if (top.status !== 0) throw new IasError(`${projectDir} is not in a git repository`, { fix: 'a build is made from a commit: git init, and commit the app' });
+  const root = top.stdout.trim();
+  if (realpathSync(root) !== realpathSync(projectDir)) {
+    throw new IasError(`the app is not at the root of its repository (${root})`, { fix: 'ias build sends the whole commit and the runner reads ias.json at its root: run it there, or give the app a repository of its own', code: 'not_repository_root' });
+  }
+  const head = git(root, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}']);
+  if (head.status !== 0) throw new IasError('the repository has no commit yet', { fix: 'commit the app first: the build is made from the commit' });
+  const status = git(root, ['status', '--porcelain']);
+  const changes = status.stdout.split('\n').filter(Boolean);
+  if (changes.length > 0) {
+    throw new IasError(`the working tree has ${changes.length} change${changes.length === 1 ? '' : 's'} that ${changes.length === 1 ? 'is' : 'are'} not committed (${changes.slice(0, 3).map((line) => line.slice(3)).join(', ')}${changes.length > 3 ? ', …' : ''})`, {
+      fix: 'commit them, stash them or add them to .gitignore: the build is made from the commit, and what is not in it would not be in the build',
+      code: 'working_tree_dirty',
+      details: changes,
+    });
+  }
+  return { root: projectDir, commit: head.stdout.trim(), subject: git(root, ['log', '-1', '--format=%s', 'HEAD']).stdout.trim() };
+}
+
+/** The expo object of app.json in `commit`: the version and build numbers the build takes. */
+export function appConfigOf(root, commit) {
+  const shown = git(root, ['show', `${commit}:app.json`]);
+  if (shown.status !== 0) throw new IasError(`the commit ${commit.slice(0, 10)} has no app.json`, { fix: 'ias build reads the version and the build numbers from app.json (an app.config.js is not read yet)' });
+  let expo;
+  try {
+    expo = JSON.parse(shown.stdout).expo;
+  } catch (error) {
+    throw new IasError(`app.json of ${commit.slice(0, 10)} is not valid JSON (${error.message})`, { fix: 'fix it and commit it' });
+  }
+  if (typeof expo?.version !== 'string' || expo.version === '') throw new IasError('app.json has no expo.version', { fix: 'set the version of the app in app.json, such as "1.3.0"' });
+  return expo;
+}
+
+/**
+ * The build number of app.json for `platform` (ios.buildNumber, android.versionCode), or null: the server takes its
+ * own with autoIncrement, and needs this one otherwise.
+ */
+export function buildNumberOf(expo, platform) {
+  const value = platform === 'ios' ? expo.ios?.buildNumber : expo.android?.versionCode;
+  const number = typeof value === 'string' && /^[1-9][0-9]{0,9}$/.test(value) ? Number(value) : value;
+  return Number.isInteger(number) && number >= 1 && number <= 2147483647 ? number : null;
+}
+
+/** The tarball of `commit` (git archive), in a temporary folder of this run: { file, sha256, bytes }. */
+export async function archive(root, commit) {
+  const file = join(temporary('ias-build-'), 'source.tar');
+  const result = git(root, ['archive', '--format=tar', '-o', file, commit]);
+  if (result.status !== 0) throw new IasError(`git archive of ${commit.slice(0, 10)} failed: ${result.stderr.trim().split('\n').at(-1)}`, { fix: 'check the repository with git fsck' });
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(file)) hash.update(chunk);
+  return { file, sha256: hash.digest('hex'), bytes: statSync(file).size };
+}

package/src/commands/builds/index.mjs

@@ -0,0 +1,148 @@
+// ias builds list, view, logs, cancel and download: the builds of an application on the server (docs/technical/runner-api.md
+// §4.3 and §4.4). The log is the one the runner sent, already cleaned of secrets; artifacts are downloaded through
+// links of 15 minutes and checked against their SHA-256.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { applicationOf, connect } from '../../manage.mjs';
+import { EXIT_CODE } from '../../output.mjs';
+import { buildLine, buildsClient, downloadArtifacts, follow, isFinished } from '../build/follow.mjs';
+
+const BUILD_ID = /^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$/;
+const STATUSES = ['uploading', 'awaiting_approval', 'queued', 'assigned', 'running', 'uploading_artifacts', 'succeeded', 'failed', 'rejected', 'canceled', 'expired'];
+const KINDS = ['ipa', 'aab', 'apk', 'dsyms', 'mapping', 'result', 'logs'];
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+const clientOf = (context, project = projectOf(context)) => buildsClient(connect(context, project));
+const day = (iso) => (iso ? iso.slice(0, 16).replace('T', ' ') : '—');
+
+async function list(context) {
+  const { values, output } = context;
+  const project = projectOf(context);
+  const client = clientOf(context, project);
+  const application = applicationOf(context, project);
+  if (values.status && !STATUSES.includes(values.status)) throw new IasError(`--status is one of ${STATUSES.join(', ')}`, { fix: 'ias builds list --status awaiting_approval lists those waiting for an approval' });
+  if (values.platform && !['ios', 'android'].includes(values.platform)) throw new IasError('--platform is ios or android', { fix: 'leave it out for both' });
+  const query = new URLSearchParams(Object.entries({ status: values.status, platform: values.platform }).filter(([, value]) => value)).toString();
+  const { data } = await client.request('GET', `/apps/${application}/builds${query ? `?${query}` : ''}`);
+  const builds = data.data ?? [];
+  if (builds.length === 0) output.log(`No builds${values.status ? ` ${values.status}` : ''} of ${application}: ias build launches one.`);
+  for (const build of builds) {
+    output.log(`${build.id}  ${build.platform.padEnd(7)}  ${build.profile.padEnd(11)}  ${`${build.version} (${build.build_number ?? '?'})`.padEnd(13)}  ${build.status.padEnd(19)}  ${day(build.created_at)}  ${build.message ?? ''}`);
+  }
+  return { builds };
+}
+
+async function view(context) {
+  const { output } = context;
+  const client = clientOf(context);
+  const { data: build } = await client.request('GET', `/builds/${context.positionals[0]}`);
+  output.log(`${build.id}  ${build.app}  ${buildLine(build)}`);
+  output.log(`  profile     ${build.profile} (${build.distribution}, ${build.environment}, ${build.format}${build.channel ? `, channel ${build.channel}` : ''})`);
+  output.log(`  commit      ${build.commit}${build.message ? `  ${build.message}` : ''}`);
+  output.log(`  code        ${build.source?.bytes ?? '?'} bytes, SHA-256 ${build.source?.sha256 ?? '?'}`);
+  output.log(`  launched    ${day(build.created_at)} by ${build.created_by ?? '?'}`);
+  if (build.status === 'awaiting_approval') output.log(`  approve at  ${build.approval_url} (hash ${build.hash})`);
+  if (build.approved_by) output.log(`  approved    ${day(build.approved_at)} by ${build.approved_by}`);
+  if (build.runner) output.log(`  runner      ${build.runner.name} (${build.runner.id})`);
+  output.log(`  times       queued ${day(build.queued_at)}, started ${day(build.started_at)}, finished ${day(build.finished_at)}`);
+  if (build.error) output.log(`  error       ${build.error.code}${build.error.step ? ` at ${build.error.step}` : ''}${build.error.message ? `: ${build.error.message}` : ''}`);
+  for (const artifact of build.artifacts ?? []) output.log(`  artifact    ${artifact.kind.padEnd(8)} ${artifact.file} (${artifact.bytes} bytes)`);
+  for (const submission of build.submissions ?? []) output.log(`  submission  ${submission.id} ${submission.target}${submission.track ? ` ${submission.track}` : ''}: ${submission.status}${submission.approval_url ? ` (approve at ${submission.approval_url})` : ''}${submission.error ? ` — ${submission.error.code}` : ''}`);
+  return build;
+}
+
+async function logs(context) {
+  const { values, output } = context;
+  const client = clientOf(context);
+  const { data: build } = await client.request('GET', `/builds/${context.positionals[0]}`);
+  if (values.follow) {
+    const [done] = await follow(context, client, [build]);
+    output.log(buildLine(done));
+    return done.status === 'succeeded' ? done : { ...done, [EXIT_CODE]: 1 };
+  }
+  const chunks = [];
+  let after = -1;
+  for (;;) {
+    const { data: page } = await client.request('GET', `/builds/${build.id}/logs?after=${after}`);
+    let step;
+    for (const chunk of page.data ?? []) {
+      if (chunk.step && chunk.step !== step) {
+        step = chunk.step;
+        output.log(`── ${chunk.step}`);
+      }
+      output.log(String(chunk.text).replace(/\n$/, ''));
+      chunks.push(chunk);
+    }
+    if ((page.data ?? []).length === 0 || !Number.isInteger(page.next) || page.next === after) break;
+    after = page.next;
+  }
+  if (chunks.length === 0) output.log(isFinished(build.status) ? 'The build has no log.' : `No log yet (${build.status}): ias builds logs ${build.id} --follow waits for it.`);
+  return { build: build.id, status: build.status, logs: chunks };
+}
+
+async function cancel(context) {
+  const { data: build } = await clientOf(context).request('POST', `/builds/${context.positionals[0]}/cancel`);
+  context.output.log(build.status === 'canceled' ? `Canceled ${build.id} (${buildLine(build)}).` : `Asked the runner to stop ${build.id}: ${buildLine(build)}.`);
+  return build;
+}
+
+async function download(context) {
+  const { values, output } = context;
+  const client = clientOf(context);
+  const { data: build } = await client.request('GET', `/builds/${context.positionals[0]}`);
+  const kinds = values.kind ? values.kind.split(',').map((kind) => kind.trim()) : undefined;
+  const unknown = kinds?.filter((kind) => !KINDS.includes(kind)) ?? [];
+  if (unknown.length > 0) throw new IasError(`--kind takes ${KINDS.join(', ')}, not ${unknown.join(', ')}`, { fix: 'separate several with commas: --kind ipa,dsyms' });
+  if (build.status !== 'succeeded') output.warn(`the build is ${build.status}: it may have no artifacts`);
+  const saved = await downloadArtifacts(context, client, build, { ...(values.out ? { folder: resolve(context.cwd, values.out) } : {}), kinds });
+  return { build: build.id, downloads: saved };
+}
+
+const buildId = { name: 'build', description: 'The id of the build, from ias builds list.', pattern: BUILD_ID };
+
+export default {
+  name: 'builds',
+  summary: 'The builds of the application on IAS: list, view, logs, cancel and download',
+  subcommands: [
+    {
+      name: 'list',
+      summary: 'The builds of the application, the newest first',
+      options: {
+        app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
+        status: { type: 'string', value: '<status>', description: `Only those in a status: ${STATUSES.join(', ')}.` },
+        platform: { type: 'string', value: 'ios|android', description: 'Only those of a platform.' },
+      },
+      run: list,
+    },
+    {
+      name: 'view',
+      summary: 'One build: its profile, commit, status, runner, error, artifacts and submissions',
+      positionals: [buildId],
+      run: view,
+    },
+    {
+      name: 'logs',
+      summary: 'The log of a build, as the runner sent it',
+      positionals: [buildId],
+      options: { follow: { type: 'boolean', short: 'f', description: 'Follow the status and the log until the build ends.' } },
+      run: logs,
+    },
+    {
+      name: 'cancel',
+      summary: 'Cancel a build (who launched it, or an owner); one in progress stops on its runner',
+      positionals: [buildId],
+      run: cancel,
+    },
+    {
+      name: 'download',
+      summary: 'Download the artifacts of a build, each checked against its SHA-256',
+      positionals: [buildId],
+      options: {
+        kind: { type: 'string', value: '<kinds>', description: `Only these kinds, separated by commas: ${KINDS.join(', ')}.` },
+        out: { type: 'string', value: '<folder>', description: 'Where they go (~/ias-builds/<app>/<platform>-<version>-<number> by default).' },
+      },
+      run: download,
+    },
+  ],
+};