@imagina-build/ias-cli 0.2.1 → 0.3.0

package/src/commands/testflight/index.mjs

@@ -0,0 +1,309 @@
+// ias testflight: what happens after `ias submit` on iOS (docs/plans/gaps/04-testflight.md §3.6 and
+// docs/technical/manage-api.md § TestFlight). A build that is in App Store Connect is distributed to TestFlight groups
+// with its «What to Test», or — separately, with its own passkey — sent to Beta App Review. `status` only reads: it never
+// talks to Apple and never creates a job. The groups come from ias.json when no flag is given, and if there is nothing to
+// use the command lists the groups the app has and says exactly what to run; it never creates one.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { ApiError, IasError } from '../../errors.mjs';
+import { connect, openUrl, sleep } from '../../manage.mjs';
+import { EXIT_CODE } from '../../output.mjs';
+import { buildsClient, isFinished } from '../build/follow.mjs';
+import { policyLine, sayPolicy } from '../policy/progress.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 DEFAULT_LOCALE = 'es-ES';
+/** The locales of a beta build localization (App Store Connect API, BetaBuildLocalization): the same list the server checks. */
+const LOCALES = ['ar-SA', 'ca', 'cs', 'da', 'de-DE', 'el', 'en-AU', 'en-CA', 'en-GB', 'en-US', 'es-ES', 'es-MX', 'fi', 'fr-CA', 'fr-FR', 'he', 'hi', 'hr', 'hu', 'id', 'it', 'ja', 'ko', 'ms', 'nl-NL', 'no', 'pl', 'pt-BR', 'pt-PT', 'ro', 'ru', 'sk', 'sv', 'th', 'tr', 'uk', 'vi', 'zh-Hans', 'zh-Hant'];
+const MAX_GROUPS = 20;
+const MAX_NOTE = 4000;
+
+const quote = (name) => `"${name}"`;
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+const clientOf = (context, project = projectOf(context)) => buildsClient(connect(context, project));
+
+/** The configuration of TestFlight of a submit profile of ias.json. */
+const settingsOf = (project, build) => project?.config?.submit?.[build.profile]?.ios?.testflight ?? {};
+
+/** The groups of the flags, of ias.json, or null (the command then says how to choose one). */
+function groupsOf(context, build, project) {
+  const flags = [context.values.groups ?? []].flat().map((group) => String(group).trim()).filter(Boolean);
+  if (flags.length > 0) return flags;
+  const configured = settingsOf(project, build).groups;
+  return Array.isArray(configured) && configured.length > 0 ? configured.map((group) => String(group)) : null;
+}
+
+/** The «What to Test» by locale: --notes-file, --what-to-test, ias.json, or the message of the build. */
+function notesOf(context, build, project) {
+  const { values } = context;
+  if (values['notes-file']) {
+    const path = resolve(context.cwd, values['notes-file']);
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(path, 'utf8'));
+    } catch (error) {
+      throw new IasError(`--notes-file ${values['notes-file']} cannot be read as JSON (${error.message})`, { fix: 'it is an object of locale: text, as { "es-ES": "Prueba el alta" }' });
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed) || Object.values(parsed).some((note) => typeof note !== 'string')) {
+      throw new IasError(`--notes-file ${values['notes-file']} is not an object of locale: text`, { fix: 'as { "es-ES": "Prueba el alta", "en-US": "Try signup" }' });
+    }
+    return parsed;
+  }
+  if (values['what-to-test']) return { [values.locale ?? DEFAULT_LOCALE]: values['what-to-test'] };
+  const configured = settingsOf(project, build).notes;
+  if (configured && typeof configured === 'object' && Object.keys(configured).length > 0) return configured;
+  const message = String(build.message ?? '').trim();
+  return { [values.locale ?? DEFAULT_LOCALE]: message || `Build ${build.version} (${build.build_number ?? '?'}) from ${String(build.commit ?? '').slice(0, 7)}` };
+}
+
+/** The plan as the server would check it, so a typo fails here with the command that fixes it and nothing is created. */
+function checkPlan(context) {
+  const { values } = context;
+  if (values.locale !== undefined && !LOCALES.includes(values.locale)) throw new IasError(`--locale ${values.locale} is not a locale App Store Connect takes`, { fix: `one of ${LOCALES.join(', ')}` });
+  if (values.groups !== undefined) {
+    const groups = [values.groups].flat();
+    if (groups.length > MAX_GROUPS) throw new IasError(`--groups takes at most ${MAX_GROUPS} groups`, { fix: 'distribute in two rounds, or join the testers in App Store Connect' });
+    if (groups.some((group) => String(group).trim() === '')) throw new IasError('--groups takes the name of a group, not an empty one', { fix: 'ias testflight status <build> lists the groups the app has' });
+  }
+}
+
+/** The state TestFlight has of the build: GET /builds/{id}/testflight, read-only. */
+async function stateOf(client, build) {
+  try {
+    return (await client.request('GET', `/builds/${build.id}/testflight`)).data;
+  } catch (error) {
+    if (error instanceof ApiError && error.status === 404) return null;
+    throw error;
+  }
+}
+
+/** The build, checked to be an iOS store build before anything is sent. */
+async function buildOf(client, id) {
+  const { data: build } = await client.request('GET', `/builds/${id}`);
+  if (build.platform !== 'ios' || build.distribution !== 'store') {
+    throw new IasError(`${build.id} is ${build.distribution === 'store' ? 'an Android' : 'an internal'} build (${build.profile})`, {
+      fix: 'TestFlight is for a store iOS build that is in App Store Connect: ias builds list --platform ios',
+      code: 'testflight_not_ready',
+    });
+  }
+  return build;
+}
+
+/** TestFlight distributes a build App Store Connect already has: the submission has to have reached it. */
+function ensureInStore(build) {
+  const sent = (build.submissions ?? []).some((submission) => submission.target === 'app_store_connect' && submission.status === 'succeeded');
+  if (!sent) {
+    throw new IasError(`${build.id} is not in App Store Connect yet`, {
+      fix: `ias submit ${build.id} --wait sends it first: TestFlight distributes a build Apple already has`,
+      code: 'testflight_not_ready',
+    });
+  }
+}
+
+/** The line of the plan, for people and --dry-run. */
+function printPlan(output, build, plan) {
+  output.log(`TestFlight of ${build.id}: ${build.app} ${build.version} (${build.build_number ?? '?'})`);
+  output.log(`  groups   ${plan.groups.map(quote).join(', ')}`);
+  for (const [locale, note] of Object.entries(plan.notes)) output.log(`  notes    ${locale}: ${note}`);
+  output.log(`  notify   ${plan.notify ? 'yes: the testers are notified' : 'no'}`);
+}
+
+/** Opens the approval, or says where it is. */
+function openApproval(context, output, job) {
+  if (!job.approval_url) return;
+  const opened = (context.openUrl ?? ((url) => openUrl(url, context.env)))(job.approval_url);
+  output.progress(`${opened ? 'Opened' : 'Open'} ${job.approval_url}: an owner approves it with a passkey (the panel shows the hash ${job.hash}).`);
+}
+
+/** Follows the job through GET /builds/{id}/testflight until it ends. */
+async function follow(context, client, build, job) {
+  const { output } = context;
+  const wait = context.sleep ?? sleep;
+  let current = job;
+  let said = current.status;
+  while (!isFinished(current.status)) {
+    await wait(5);
+    const state = await stateOf(client, build);
+    current = state?.job?.id === job.id ? state.job : current;
+    if (current.status !== said) {
+      said = current.status;
+      output.progress(`  ${current.status}${current.step ? ` (${current.step})` : ''}${current.runner?.name ? ` on ${current.runner.name}` : ''}`);
+    }
+  }
+  return current;
+}
+
+/** What to say, and the next command, when the job ended. */
+function outcome(output, build, job) {
+  if (job.status !== 'succeeded') {
+    const error = job.error ? `${job.error.code}${job.error.step ? ` at ${job.error.step}` : ''}${job.error.message ? `: ${job.error.message}` : ''}` : '';
+    output.log(`TestFlight ${job.action} of ${build.id}: ${job.status}${error ? ` — ${error}` : ''}`);
+    return { ...job, [EXIT_CODE]: 1 };
+  }
+  const result = job.result ?? {};
+  if (job.action === 'review') {
+    output.log(`The build is in Beta App Review: ${result.reviewState ?? result.review_state ?? 'WAITING_FOR_REVIEW'} (state ${result.reviewSubmissionId ?? '—'}).`);
+    output.log(`ias testflight status ${build.id} reads what Apple says of it; a rejection is not sent again by itself.`);
+    return job;
+  }
+  const groups = (result.groups ?? []).map((group) => group.name).filter(Boolean);
+  output.log(`The build is in TestFlight${groups.length > 0 ? ` for ${groups.map(quote).join(', ')}` : ''}${result.notified ? ', and the testers were notified' : ''}.`);
+  output.log(`For external testers: ias testflight review ${build.id} sends it to Beta App Review (a separate approval).`);
+  return job;
+}
+
+async function distribute(context) {
+  const { values, output } = context;
+  checkPlan(context);
+  const project = projectOf(context);
+  const client = clientOf(context, project);
+  const build = await buildOf(client, context.positionals[0]);
+  ensureInStore(build);
+  const groups = groupsOf(context, build, project);
+
+  if (groups === null) {
+    const state = await stateOf(client, build);
+    const existing = [...new Set((state?.groups ?? []).map((group) => group.name).filter(Boolean))];
+    throw new IasError(`ias testflight ${build.id} has no groups to distribute to`, {
+      code: 'testflight_groups_missing',
+      fix: existing.length > 0
+        ? `the app has these TestFlight groups: ${existing.map(quote).join(', ')}. Run ias testflight ${build.id} --groups ${quote(existing[0])}${existing.length > 1 ? ` --groups ${quote(existing[1])}` : ''}, or add submit.${build.profile}.ios.testflight.groups to ias.json`
+        : `a person creates a group in App Store Connect › TestFlight › Groups; then ias testflight ${build.id} --groups "<name>" (IAS does not create groups)`,
+    });
+  }
+
+  const notes = notesOf(context, build, project);
+  const configured = settingsOf(project, build).notify;
+  const notify = values.notify === true || configured === true;
+  const long = Object.entries(notes).find(([, note]) => [...String(note)].length > MAX_NOTE);
+  if (long) throw new IasError(`the note of ${long[0]} has ${[...String(long[1])].length} characters`, { fix: `a beta note has at most ${MAX_NOTE}: shorten it` });
+  const unknown = Object.keys(notes).filter((locale) => !LOCALES.includes(locale));
+  if (unknown.length > 0) throw new IasError(`«${unknown[0]}» is not a locale App Store Connect takes`, { fix: `one of ${LOCALES.join(', ')}` });
+
+  const plan = { action: 'distribute', groups, notes, notify };
+  printPlan(output, build, plan);
+
+  if (values['dry-run']) {
+    output.progress('Nothing was created: an owner approves the real one with a passkey.');
+    return { build: build.id, ...plan, dry_run: true, job: null };
+  }
+
+  const { data: job } = await client.request('POST', `/builds/${build.id}/testflight`, { json: { groups, notes, notify } });
+  output.progress(`distribute ${build.version} (${build.build_number ?? '?'}) to ${groups.map(quote).join(', ')}: job ${job.id}, ${job.status}`);
+  sayPolicy(output, job);
+  openApproval(context, output, job);
+  if (!values.wait) {
+    output.log(`ias testflight status ${build.id} shows how it goes; the runner distributes it once it is approved.`);
+    return { build: build.id, ...plan, job };
+  }
+  return outcome(output, build, await follow(context, client, build, job));
+}
+
+async function review(context) {
+  const { values, output } = context;
+  const project = projectOf(context);
+  const client = clientOf(context, project);
+  const build = await buildOf(client, context.positionals[0]);
+  ensureInStore(build);
+
+  output.progress(`This sends ${build.version} (${build.build_number ?? '?'}) to Beta App Review: it is a second approval, separate from distributing. Apple can reject it, and IAS does not send it again by itself.`);
+
+  if (values['dry-run']) {
+    output.progress('Nothing was created: an owner approves the real one with a passkey.');
+    return { build: build.id, action: 'review', dry_run: true, job: null };
+  }
+
+  const { data: job } = await client.request('POST', `/builds/${build.id}/testflight/review`, { json: {} });
+  output.progress(`review of ${build.id}: job ${job.id}, ${job.status}`);
+  sayPolicy(output, job);
+  openApproval(context, output, job);
+  if (!values.wait) {
+    output.log(`ias testflight status ${build.id} shows what Apple says; the runner sends it once it is approved.`);
+    return { build: build.id, action: 'review', job };
+  }
+  return outcome(output, build, await follow(context, client, build, job));
+}
+
+async function status(context) {
+  const { output } = context;
+  const client = clientOf(context);
+  const build = await buildOf(client, context.positionals[0]);
+  const state = await stateOf(client, build);
+  const job = state?.job ?? null;
+
+  output.log(`TestFlight of ${build.id}: ${build.app} ${build.version} (${build.build_number ?? '?'}), ${build.status}`);
+  if (!state) {
+    output.log('  state       not read yet: ias testflight ' + build.id + ' distributes it');
+    return { build: build.id, state: null, next: `ias testflight ${build.id} --groups "<name>"` };
+  }
+  output.log(`  App Store   app ${state.asc_app_id ?? '?'}, build ${state.asc_build_id ?? 'not found yet'}${state.asc_prerelease_version ? ` (${state.asc_prerelease_version} / ${state.asc_build_version ?? '?'})` : ''}`);
+  output.log(`  processing  ${state.processing_state ?? '—'}${state.internal_beta_state ? `, internal ${state.internal_beta_state}` : ''}${state.external_beta_state ? `, external ${state.external_beta_state}` : ''}`);
+  output.log(`  groups      ${(state.groups ?? []).length > 0 ? state.groups.map((group) => `${quote(group.name)}${group.internal ? '' : ' (external)'}`).join(', ') : 'none yet'}`);
+  output.log(`  notes       ${(state.localizations ?? []).length > 0 ? state.localizations.map((localization) => localization.locale).join(', ') : 'none yet'}${job?.action === 'distribute' ? ` — ${Object.keys(job.notes ?? {}).join(', ')}` : ''}`);
+  output.log(`  notified    ${state.notified_at ? state.notified_at.slice(0, 16).replace('T', ' ') : 'no'}`);
+  output.log(`  review      ${state.review?.state ?? 'not sent'}${state.review?.submitted_at ? ` (sent ${state.review.submitted_at.slice(0, 16).replace('T', ' ')})` : ''}`);
+  output.log(`  checked     ${state.last_checked_at ? state.last_checked_at.slice(0, 16).replace('T', ' ') : 'never'}`);
+  const policy = policyLine(job);
+  if (job) output.log(`  last job    ${job.action}: ${job.status}${policy ? ` · ${policy}` : ''}${job.approval_url ? ` (approve at ${job.approval_url})` : ''}${job.error ? ` — ${job.error.code}` : ''}`);
+
+  const next = state.review?.state === null || state.review?.state === undefined
+    ? (state.groups ?? []).length > 0 ? `ias testflight review ${build.id}` : `ias testflight ${build.id} --groups "<name>"`
+    : `ias testflight status ${build.id}`;
+  output.log(`  next        ${next}`);
+
+  return { build: build.id, state, next };
+}
+
+const buildId = { name: 'build', description: 'The id of a store iOS build that is in App Store Connect, from ias builds list.', pattern: BUILD_ID };
+
+const distributeOptions = {
+  groups: { type: 'string', value: '<name>', multiple: true, description: 'A TestFlight group by name; repeat it for more (ias.json › submit.<profile>.ios.testflight.groups by default).' },
+  'what-to-test': { type: 'string', value: '"…"', description: 'The «What to Test» of the build, in the locale of --locale.' },
+  locale: { type: 'string', value: '<locale>', description: `The locale of --what-to-test (${DEFAULT_LOCALE} by default).` },
+  'notes-file': { type: 'string', value: '<file.json>', description: 'A JSON object of locale: text, for several locales (at most 8).' },
+  notify: { type: 'boolean', description: 'Notify the testers when the build is added (off by default).' },
+  wait: { type: 'boolean', description: 'Wait until the runner finished, and say what Apple answered.' },
+  'dry-run': { type: 'boolean', description: 'Show what would be approved, without creating anything.' },
+};
+
+export default {
+  name: 'testflight',
+  summary: 'Distribute a build that is in App Store Connect to TestFlight groups, or send it to Beta App Review',
+  description: [
+    'The build has to be a store iOS build that succeeded and whose ias submit reached App Store Connect: TestFlight distributes a build Apple already has. Both actions are a job of the runner with its own approval: the runner opens the App Store Connect key (the server never sees it) and the owner approves the plan with a passkey.',
+    'Without --groups, the groups come from ias.json › submit.<profile>.ios.testflight.groups; the «What to Test» from --what-to-test with --locale (es-ES by default), --notes-file, ias.json or the message of the build. If there are no groups and none is configured, it lists the groups the app has and the exact command: it never creates one.',
+    'ias testflight <build> and ias testflight distribute <build> are the same command. ias testflight review is a separate command, with its own approval: it sends the build to Beta App Review (Apple). ias testflight status only reads.',
+  ].join('\n'),
+  positionals: [buildId],
+  options: distributeOptions,
+  subcommands: [
+    {
+      name: 'distribute',
+      summary: 'Distribute the build to its TestFlight groups; the same as ias testflight <build>',
+      description: 'The explicit form of the positional one, for scripts that read better with a verb: it takes the same options and does exactly the same, with the same approval.',
+      positionals: [buildId],
+      options: distributeOptions,
+      run: distribute,
+    },
+    {
+      name: 'review',
+      summary: 'Send the build to Beta App Review, with its own passkey (a separate approval)',
+      description: 'Beta App Review is what external testers need: it is not done by distributing, it is not App Review, and Apple can reject it. The runner checks the test information of the app first and sends the build once; it does not wait for the review, which is human.',
+      positionals: [buildId],
+      options: {
+        wait: { type: 'boolean', description: 'Wait until the runner has sent it, and say the state Apple gave.' },
+        'dry-run': { type: 'boolean', description: 'Show what would be approved, without creating anything.' },
+      },
+      run: review,
+    },
+    {
+      name: 'status',
+      summary: 'What TestFlight and Beta App Review say of the build; it only reads',
+      description: 'Reads the state IAS has of the build: Apple\'s processing, the groups it is in, the locales with notes and the state of Beta App Review. It never creates a job nor calls Apple.',
+      positionals: [buildId],
+      run: status,
+    },
+  ],
+  run: distribute,
+};

package/src/commands/tokens/index.mjs

@@ -0,0 +1,99 @@
+// ias tokens: the robot tokens of an application for CI (docs/technical/manage-api.md §5). create makes one and keeps
+// it in 1Password; list shows them without their value; revoke kills one. A robot token works without a person, so only
+// an owner's personal token can make one, and the value is shown by nobody after it is stored.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { applicationOf, connect } from '../../manage.mjs';
+import { createRobotToken } from '../../provisioning.mjs';
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+
+async function create(context) {
+  return createRobotToken({ dir: resolve(context.cwd, context.values.project ?? '.'), env: context.env, output: context.output, values: context.values, sleep: context.sleep, dryRun: context.values['dry-run'] });
+}
+
+async function list(context) {
+  const project = projectOf(context);
+  const app = applicationOf(context, project);
+  const client = connect(context, project);
+  const { data } = await client.request('GET', `/apps/${app}/tokens`);
+  if (data.data.length === 0) context.output.log(`No tokens of ${app}: ias tokens create --name CI --scopes apps:read,builds:create`);
+  const width = Math.max(0, ...data.data.map((token) => token.name.length));
+  for (const token of data.data) {
+    context.output.log(`${token.id}  ${token.name.padEnd(width)}  ${(token.scopes ?? []).join(',')}  ${token.legacy ? 'legacy' : token.expires_at?.slice(0, 10) ?? 'no expiry'}`);
+  }
+  return data;
+}
+
+/** The token `wanted` names: its id, or its name when only one has it (two with the same name are never picked). */
+async function tokenNamed(client, app, wanted) {
+  const { data } = await client.request('GET', `/apps/${app}/tokens`);
+  const tokens = data.data ?? [];
+  const byId = tokens.find((token) => token.id === wanted);
+  if (byId) return byId;
+  const byName = tokens.filter((token) => token.name === wanted);
+  if (byName.length === 1) return byName[0];
+  if (byName.length > 1) {
+    throw new IasError(`«${wanted}» names ${byName.length} tokens of ${app}`, {
+      fix: `pass the id of one: ${byName.map((token) => `${token.id} (${token.expires_at?.slice(0, 10) ?? 'no expiry'})`).join(', ')}`,
+      code: 'token_ambiguous',
+      details: { candidates: byName.map((token) => ({ id: token.id, name: token.name })) },
+    });
+  }
+  throw new IasError(`there is no token «${wanted}» of ${app}`, { fix: 'ias tokens list shows them', code: 'token_not_found' });
+}
+
+async function revoke(context) {
+  const { values, output } = context;
+  const project = projectOf(context);
+  const app = applicationOf(context, project);
+  const wanted = context.positionals[0];
+  const client = connect(context, project);
+  const token = await tokenNamed(client, app, wanted);
+  if (values['dry-run']) {
+    output.progress(`dry run: would revoke the token «${token.name}» (${token.id}) of ${app}: it would stop working`);
+    return { dry_run: true, id: token.id, name: token.name, revoked: false };
+  }
+  await client.request('DELETE', `/apps/${app}/tokens/${token.id}`);
+  output.log(`${output.prefix}: token ${token.id} revoked: it no longer works`);
+  return { id: token.id, name: token.name, revoked: true };
+}
+
+export default {
+  name: 'tokens',
+  summary: 'The robot tokens of an application for CI: create one, list them and revoke one',
+  description: 'A robot token (iasr_…) works without a person, with the scopes it is given. create needs an owner\'s personal token and keeps the value in 1Password, with its op:// reference; list never shows a value. In CI, set IAS_TOKEN from the item.',
+  subcommands: [
+    {
+      name: 'create',
+      summary: 'Make a robot token, keep it in 1Password and print its item and scopes',
+      options: {
+        name: { type: 'string', value: '"…"', description: 'The name of the token, such as «GitHub Actions» (CI by default).' },
+        scopes: { type: 'string', value: '<list>', description: 'Comma-separated scopes: apps:read,builds:create by default. The values: apps:read, builds:create, credentials:read, credentials:write, distribution:upload, env:read, env:write, push:send, updates:publish.' },
+        days: { type: 'string', value: '<30|90|180|365>', description: 'How long it lasts (90 by default).' },
+        item: { type: 'string', value: 'op://vault/item', description: 'The 1Password item for the token (op://IAS/<app> CI by default).' },
+        app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
+        'dry-run': { type: 'boolean', description: 'Say what it would make and change, and make nothing.' },
+      },
+      run: create,
+    },
+    {
+      name: 'list',
+      summary: 'The robot tokens of the application, without their value',
+      options: { app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' } },
+      run: list,
+    },
+    {
+      name: 'revoke',
+      summary: 'Revoke a robot token or a legacy publishing token',
+      description: 'Takes its id, or its name when only one token has it: two with the same name are never picked silently, it lists them and asks for the id. --dry-run says what it would revoke and revokes nothing.',
+      positionals: [{ name: 'token', description: 'The id of the token (ias tokens list), or its name when only one has it.' }],
+      options: {
+        app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
+        'dry-run': { type: 'boolean', description: 'Say what it would revoke, and revoke nothing.' },
+      },
+      run: revoke,
+    },
+  ],
+};

package/src/commands/update/index.mjs

@@ -15,13 +15,18 @@ import { api, download } from '../../http.mjs';
 import { INSTALLS, buildManifests, firstPart, installationInside, promoted, publicKeyOf, readEnvFile, rollbackDirectives, sha256, signatureHeader, verifySignature } from '../../ota.mjs';
 import { gently, run, temporary } from '../../process.mjs';
 import { readSecret, readSecretFile, isReference, tokenKind } from '../../secrets.mjs';
+import { provisionOta } from '../../provisioning.mjs';
 
 export const PLATFORMS = ['ios', 'android'];
 
-/** The environment of the app's tools: none of this shell's EXPO_PUBLIC_* (they would go into the bundle) or secrets. */
-function appEnv() {
+/**
+ * The environment of the app's tools: none of this shell's EXPO_PUBLIC_* (they would go into the bundle) or secrets.
+ * With `tmp`, TMPDIR is a folder of this run: Metro keeps its cache in TMPDIR (metro-cache) and a cache from another
+ * run brings the paths of its folder into the bundle. The runner does the same for each build.
+ */
+function appEnv(tmp) {
   const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^(EXPO_PUBLIC_|OTA_|IAS_)/.test(key) && !['EXPO_TOKEN', 'NODE_ENV'].includes(key)));
-  return { ...env, CI: '1', EXPO_NO_TELEMETRY: '1' };
+  return { ...env, CI: '1', EXPO_NO_TELEMETRY: '1', ...(tmp === undefined ? {} : { TMPDIR: tmp }) };
 }
 
 /**
@@ -134,11 +139,13 @@ function copyOf(settings, ref, output) {
   run('git', ['archive', '--format=tar', '-o', join(dir, 'source.tar'), commit], { cwd: settings.projectDir });
   const app = join(dir, 'app');
   run('mkdir', [app]);
+  const tmp = join(dir, 'tmp');
+  run('mkdir', [tmp]);
   run('tar', ['-xf', join(dir, 'source.tar'), '-C', app]);
   const install = INSTALLS.find(([lockfile]) => existsSync(join(app, lockfile)));
   if (!install) throw new Error('the commit has no lockfile (package-lock.json, yarn.lock, pnpm-lock.yaml or bun.lock): the copy could not install the same dependencies');
   output.progress(`${install[1]} ${install[2][0]} in a copy of ${commit.slice(0, 10)}…`);
-  gently(install[1], install[2], { cwd: app, env: appEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+  gently(install[1], install[2], { cwd: app, env: appEnv(tmp), stdio: ['ignore', 'pipe', 'pipe'] });
   const mustContain = [];
   if (settings.envFile) {
     const envFile = join(settings.projectDir, settings.envFile);
@@ -152,11 +159,11 @@ function copyOf(settings, ref, output) {
   } else if (settings.bundleEnv.length > 0) {
     throw new Error(`${settings.names.config} lists bundleEnv but no envFile to take them from`);
   }
-  return { app, commit, mustContain };
+  return { app, tmp, commit, mustContain };
 }
 
-function runtimeVersion(cwd, platform) {
-  const output = run('npx', ['expo-updates', 'runtimeversion:resolve', '--platform', platform], { cwd, env: appEnv(), label: 'expo-updates runtimeversion:resolve' });
+function runtimeVersion(cwd, platform, tmp) {
+  const output = run('npx', ['expo-updates', 'runtimeversion:resolve', '--platform', platform], { cwd, env: appEnv(tmp), label: 'expo-updates runtimeversion:resolve' });
   return JSON.parse(output.slice(output.indexOf('{'))).runtimeVersion;
 }
 
@@ -174,13 +181,13 @@ export async function publish(settings, { ref = 'HEAD', message, platforms = PLA
   const copy = copyOf(settings, ref, output);
   const dist = join(dirname(copy.app), 'dist');
   output.progress(`exporting ${copy.commit.slice(0, 10)} (${platforms.join(', ')})…`);
-  gently('npx', ['expo', 'export', ...platforms.flatMap((platform) => ['--platform', platform]), '--output-dir', dist], { cwd: copy.app, env: appEnv(), stdio: ['ignore', 'pipe', 'pipe'] });
+  gently('npx', ['expo', 'export', ...platforms.flatMap((platform) => ['--platform', platform]), '--output-dir', dist], { cwd: copy.app, env: appEnv(copy.tmp), stdio: ['ignore', 'pipe', 'pipe'] });
   const { manifests, files } = buildManifests({
     dist,
     metadata: JSON.parse(readFileSync(join(dist, 'metadata.json'), 'utf8')),
     platforms,
-    runtimes: Object.fromEntries(platforms.map((platform) => [platform, runtimeVersion(copy.app, platform)])),
-    expoClient: JSON.parse(run('npx', ['expo', 'config', '--type', 'public', '--json'], { cwd: copy.app, env: appEnv(), label: 'expo config' })),
+    runtimes: Object.fromEntries(platforms.map((platform) => [platform, runtimeVersion(copy.app, platform, copy.tmp)])),
+    expoClient: JSON.parse(run('npx', ['expo', 'config', '--type', 'public', '--json'], { cwd: copy.app, env: appEnv(copy.tmp), label: 'expo config' })),
     assetPath: settings.assetPath,
     createdAt: new Date().toISOString(),
     mustContain: copy.mustContain,
@@ -380,10 +387,14 @@ export async function list(settings, { channel }, output) {
   return data;
 }
 
-/** What a phone with the app's runtime gets now, checked end to end. It needs no key and no token. */
-export async function check(settings, { platforms = PLATFORMS }, output) {
+/**
+ * What a phone with the app's runtime gets now, checked end to end. It needs no key and no token. `channel` asks as a
+ * build of that channel (the header the phone sends) and checks the signature with its certificate in ias.json;
+ * without it, it asks for the default channel.
+ */
+export async function check(settings, { platforms = PLATFORMS, channel }, output) {
   const checks = [];
-  for (const platform of platforms) checks.push(await checkServed(settings, platform, runtimeVersion(settings.projectDir, platform), undefined, output));
+  for (const platform of platforms) checks.push(await checkServed(settings, platform, runtimeVersion(settings.projectDir, platform), undefined, output, channel === undefined ? {} : { channel }));
   return { checks };
 }
 
@@ -463,6 +474,18 @@ export default {
   summary: 'Signed OTA updates (expo-updates): publish, go back, retire and check',
   description: 'Signs on this Mac with the key of 1Password (updates.signing.privateKey, or updates.channels.<channel>.privateKey for another channel) and publishes to the server of updates.url in app.json. The token is the OTA project\'s (ota_…): IAS_TOKEN or updates.token.',
   subcommands: [
+    {
+      name: 'init',
+      summary: 'Make the OTA project, its signing key and its publishing token, and write them to ias.json',
+      description: 'Makes an RSA key and a self-signed certificate on this Mac, creates the OTA project on the server with the certificate and the keyid, and keeps the private key and the publishing token in 1Password. It writes their op:// references in ias.json and prints the manifest URL. It never prints a key or a token. It needs an owner\'s personal token (ias login) and the 1Password CLI; a project that already exists with the same certificate is left as it is.',
+      options: {
+        name: { type: 'string', value: '"…"', description: 'The name of the project in the panel (the app name by default).' },
+        keyid: { type: 'string', value: '<keyid>', description: 'The keyid the builds carry (the app code + -ota-1 by default).' },
+        item: { type: 'string', value: 'op://vault/item', description: 'The 1Password item for the key and the token (op://IAS/<app> OTA by default).' },
+        'dry-run': { type: 'boolean', description: 'Say what it would make and change, and make nothing.' },
+      },
+      run: (context) => provisionOta({ dir: resolve(context.cwd, context.values.project ?? '.'), env: context.env, output: context.output, values: context.values, sleep: context.sleep, dryRun: context.values['dry-run'] }),
+    },
     {
       name: 'publish',
       summary: 'Publish a commit (HEAD by default) for both platforms or one',
@@ -525,8 +548,12 @@ export default {
     {
       name: 'check',
       summary: 'What a phone with the app\'s runtime gets now, checked end to end',
-      options: pick('platform'),
-      run: (context) => check(settingsOf(context), { platforms: platformsOf(context.values) }, context.output),
+      description: 'Asks for the manifest as a phone would, verifies its signature and every file it points to, and needs no key and no token. Without --channel it checks the default channel of the project (the one of app.json); --channel asks as a build of that channel and checks the signature with its certificate in ias.json › updates.channels.',
+      options: {
+        ...pick('platform'),
+        channel: { type: 'string', value: '<channel>', description: 'The channel to check, as a build of it would (the default channel by default), signed with its certificate in ias.json.' },
+      },
+      run: (context) => check(settingsOf(context), { platforms: platformsOf(context.values), channel: context.values.channel }, context.output),
     },
   ],
 };

package/src/commands/vault/approvers.mjs

@@ -105,13 +105,17 @@ export async function approvers(context, client, item) {
   };
   if (unchanged) {
     output.log(`\nThe team already signed these ${rows.length} passkey${rows.length === 1 ? '' : 's'} (version ${previous.version}): nothing to sign.`);
-    return { ...result, version: previous.version, signed: false, in_sync: current.in_sync ?? null };
+    return { ...result, version: previous.version, signed: false, in_sync: current.in_sync ?? null, ...(context.values['dry-run'] ? { dry_run: true } : {}) };
   }
 
   const version = Math.max(previousVersion, Number.isInteger(listed.document_version) ? listed.document_version : 0) + 1;
   output.progress('');
   output.progress('Check that each passkey is one of an owner you know, above all the NEW and CHANGED ones: from now on, the runners');
   output.progress('build for the stores only what one of these passkeys approves. The server could have added one of its own.');
+  if (context.values['dry-run']) {
+    output.progress(`dry run: it would sign version ${version} with these ${rows.length} passkey${rows.length === 1 ? '' : 's'} and upload it (PUT /team/approvers-document); nothing was signed and nothing was uploaded.`);
+    return { ...result, dry_run: true, version, signed: false, in_sync: current.in_sync ?? null };
+  }
   // Signed in memory first, so that a target the document cannot hold stops it before asking; uploaded after the yes.
   let document;
   try {

package/src/commands/vault/index.mjs

@@ -29,7 +29,7 @@ function checkPrivateKeys(item, keys, env) {
   signingKeyOf(item, keys, env);
 }
 
-async function init(context) {
+export async function init(context) {
   const { env, output } = context;
   const project = projectOf(context);
   const client = connect(context, project);
@@ -39,6 +39,25 @@ async function init(context) {
     throw new IasError(`the vault of ${client.server} already has its keys`, { fix: 'ias vault status compares them with the ones in 1Password (changing them is not in v1 of the API)', code: 'vault_keys_exist' });
   }
   let keys = publicKeysOf(item, env);
+  if (context.values['dry-run']) {
+    if (keys) {
+      output.progress(`${item.reference} already has the keys of the vault (an earlier ias vault init that was not approved): it would register those.`);
+      output.progress(`recovery key  ${keys.recovery.kid}`);
+      output.progress(`signing key   ${keys.signing.kid}`);
+    } else {
+      output.progress(`It would create ${item.reference} with a new recovery key and a new signing key: their private halves would only live there.`);
+    }
+    output.progress(`It would register the public keys on ${client.server} (POST /vault/keys), and an owner would approve it with a passkey.`);
+    output.progress('dry run: nothing was created in 1Password and nothing was registered.');
+    return {
+      dry_run: true,
+      server: client.server,
+      item: item.reference,
+      action: keys ? 'register_existing_keys' : 'create_keys',
+      recovery_key: keys?.recovery ?? null,
+      signing_key: keys?.signing ?? null,
+    };
+  }
   if (keys) {
     output.progress(`${item.reference} already has the keys of the vault (an earlier ias vault init that was not approved): registering those.`);
   } else {
@@ -102,8 +121,9 @@ async function status(context) {
   return result;
 }
 
-const itemOption = { item: { type: 'string', value: '<op://vault/item>', description: 'The 1Password item of the vault (IAS_VAULT_ITEM, vault.item of ias.json, or op://Private/IAS vault <host>).' } };
+const itemOption = { item: { type: 'string', value: '<op://vault/item>', description: 'The 1Password item of the vault (IAS_VAULT_ITEM, vault.item of ias.json, or op://IAS/IAS vault <host>).' } };
 const yesOption = { yes: { type: 'boolean', short: 'y', description: 'Do not ask: you have already compared what it prints (without a terminal it is needed).' } };
+const dryRunOption = { 'dry-run': { type: 'boolean', description: 'Show the plan and change nothing: no 1Password write, no signed document, no runner list and no envelope changed.' } };
 const runnerArgument = { name: 'runner', description: 'The runner: its id, its name (in quotes if it has spaces) or its vault kid, as ias vault status and the panel list them.' };
 
 /** Runs a command that signs with the team's key: the client, the 1Password item and then `run`. */
@@ -122,7 +142,7 @@ export default {
       name: 'init',
       summary: 'Create the recovery and signing keys in 1Password and register them (owner, with a passkey)',
       description: 'Makes both keys, creates the 1Password item with op (the private keys go through stdin and are never printed), and asks the server to register the public keys. A member approves it with a passkey in the panel, after checking that it shows the two kids printed here. If the item already exists from an attempt that was not approved, its keys are registered.',
-      options: itemOption,
+      options: { ...itemOption, ...dryRunOption },
       run: init,
     },
     {
@@ -136,7 +156,7 @@ export default {
       name: 'approvers',
       summary: 'Sign the passkeys of the owners that may approve a store build (owner)',
       description: 'Reads the owners\' passkeys from the server and shows each one with its member and fingerprint, marking what changes from the version the team signed before (verified with the team\'s key). After you confirm, it signs the next version of the ias-approvers-1 document with the team\'s key of 1Password and uploads it: the runners only build for the stores what one of these passkeys approved. Run it again after an owner adds or removes a passkey; the panel says so in Today.',
-      options: { ...itemOption, ...yesOption, replace: { type: 'boolean', description: 'Sign over a document of the server that does not verify with the team\'s key (after checking why).' } },
+      options: { ...itemOption, ...yesOption, ...dryRunOption, replace: { type: 'boolean', description: 'Sign over a document of the server that does not verify with the team\'s key (after checking why).' } },
       run: signing(approvers),
     },
     {
@@ -144,7 +164,7 @@ export default {
       summary: 'Let a registered runner open the team\'s credentials: the signed list and a wrap in each envelope',
       description: 'Shows the runner\'s vault kid for you to compare with the one ias-runner register printed on its Mac. Then it signs a runner list with it, uploads it, and wraps every envelope of the team (credentials and secret variables) for it, opening each one with the recovery key of 1Password and signing it again. Envelopes that do not verify are never signed again: it says which.',
       positionals: [runnerArgument],
-      options: { ...itemOption, ...yesOption },
+      options: { ...itemOption, ...yesOption, ...dryRunOption },
       run: signing(grant),
     },
     {
@@ -152,7 +172,7 @@ export default {
       summary: 'Take a runner revoked in the panel out of the signed list and of every envelope',
       description: 'Revoke it in the panel first (System › Runners): the server stops serving it at once. This signs a runner list without it and removes its wrap from every envelope, signing each one again, and lists what it could read, which is what to renew if its Mac may have been compromised (docs/technical/vault.md §10).',
       positionals: [runnerArgument],
-      options: { ...itemOption, ...yesOption },
+      options: { ...itemOption, ...yesOption, ...dryRunOption },
       run: signing(revoke),
     },
   ],