@imagina-build/ias-cli 0.2.2 → 0.3.0

package/src/setup.mjs

@@ -0,0 +1,698 @@
+// ias setup: the checklist that takes an Expo app from nothing to its first build and its first update, one step at a
+// time (docs/plans/PLAN-ONBOARDING.md). Every step is checked against the files and the server, so it says what is done
+// and not what someone remembers. The steps that can be done here (ias.json, the SDK, the login) are done here; the
+// ones that need a person (the app in the panel, the credentials, the runner) say exactly what to do and stay locked
+// until the check passes. A step cannot run while the one it needs is not done.
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import process from 'node:process';
+import { CONFIG_FILE, loadProject, readExpo, serverOf } from './config.mjs';
+import { IasError } from './errors.mjs';
+import { ensurePush, applicationPlan, createApplication, printApplicationPlan } from './applications.mjs';
+import { connect, manageToken, serverOrigin, sleep as manageSleep } from './manage.mjs';
+import { createRunnerCode, provisionDistribution, provisionOta } from './provisioning.mjs';
+import { probe as systemProbe } from './process.mjs';
+import { SDK_PACKAGE, sdkState } from './sdk.mjs';
+import { SERVICES, inferServices } from './setup-state.mjs';
+import { diagnose } from './commands/doctor/index.mjs';
+import { init } from './commands/init/index.mjs';
+import { expoModulesFor, installSdk } from './commands/sdk/index.mjs';
+
+const CODE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const PLATFORMS = ['ios', 'android'];
+const STATUS = Object.freeze({ DONE: 'done', READY: 'ready', LOCKED: 'locked', OPTIONAL: 'optional', FAILED: 'failed' });
+
+const ok = (detail, extra = {}) => ({ ok: true, detail, ...extra });
+const no = (detail, fix, extra = {}) => ({ ok: false, detail, fix, ...extra });
+
+function projectSafe(dir) {
+  try {
+    return loadProject(dir);
+  } catch (error) {
+    return { dir, source: 'error', config: undefined, error };
+  }
+}
+
+function serverOfDir(dir, env) {
+  const project = projectSafe(dir);
+  return project.error ? serverOf({ config: undefined }, env) : serverOf(project, env);
+}
+
+function originOf(dir, env) {
+  try {
+    return serverOrigin(projectSafe(dir), env);
+  } catch {
+    return serverOfDir(dir, env);
+  }
+}
+
+/** The management API, with the token of this computer. Throws not_logged_in, which the checks turn into a fix. */
+async function api(ctx) {
+  if (ctx.client) return ctx.client;
+  if (!ctx.session) {
+    const project = projectSafe(ctx.dir);
+    if (project.error) throw project.error;
+    ctx.session = connect({ env: ctx.env, sleep: ctx.sleep ?? manageSleep }, project);
+  }
+  return ctx.session;
+}
+
+/** GET, with the app and the vault kept for the checks that need them again. */
+async function getApp(ctx) {
+  if (ctx.appData) return ctx.appData;
+  const client = await api(ctx);
+  const code = ctx.config?.app;
+  if (!code) throw new IasError('ias.json has no app', { fix: 'run ias init, or write app in ias.json' });
+  const { data } = await client.request('GET', `/apps/${encodeURIComponent(code)}`);
+  ctx.appData = data;
+  return data;
+}
+
+async function getVault(ctx) {
+  if (ctx.vaultData) return ctx.vaultData;
+  const client = await api(ctx);
+  const { data } = await client.request('GET', '/vault');
+  ctx.vaultData = data;
+  return data;
+}
+
+function expoOf(dir) {
+  try {
+    return readExpo(dir) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function platformsOf(ctx) {
+  const app = ctx.appData ?? {};
+  const expo = expoOf(ctx.dir);
+  const platforms = [];
+  if (app.ios || expo.ios?.bundleIdentifier) platforms.push('ios');
+  if (app.android || expo.android?.package) platforms.push('android');
+  return platforms.length > 0 ? platforms : PLATFORMS;
+}
+
+const panel = (ctx, path) => `${originOf(ctx.dir, ctx.env)}/admin${path}`;
+
+/** The commands that import (or make) the signing credentials, per platform, for the fix of a check. */
+const CREDENTIAL_COMMANDS = {
+  ios: [
+    'ias credentials generate ios (the certificate and the App Store profile, reusing what is valid)',
+    'ias credentials import apple_distribution_certificate --p12 <certificate.p12> --password op://…',
+    'ias credentials import apple_provisioning_profile --profile <profile.mobileprovision>',
+  ],
+  android: ['ias credentials import android_upload_keystore --keystore <upload.jks> --store-password op://… --key-alias <alias>'],
+};
+
+const REQUIRED_CREDENTIALS = {
+  ios: ['apple_distribution_certificate', 'apple_provisioning_profile'],
+  android: ['android_upload_keystore'],
+};
+
+/** The steps, in order. `service` means the step belongs to that service; `optional` means it does not block. */
+function buildSteps(ctx) {
+  const selected = (service) => ctx.services.includes(service);
+
+  return [
+    {
+      id: 'environment',
+      title: 'This computer has what ias needs',
+      description: 'Node 22, git and the 1Password CLI (op). Xcode and the Android SDK are warnings until a local build.',
+      check: () => {
+        const checks = diagnose({ dir: ctx.dir, env: ctx.env, platform: ctx.platform, nodeVersion: ctx.nodeVersion, probe: ctx.probe, aapt2: ctx.aapt2 });
+        const byName = Object.fromEntries(checks.map((check) => [check.name, check]));
+        const required = ['node', 'git', 'op'].map((name) => byName[name]).filter(Boolean);
+        const failing = required.filter((check) => check.status === 'fail');
+        const warnings = ['xcode', 'aapt2', 'macos-tools'].map((name) => byName[name]).filter((check) => check?.status === 'fail' || check?.status === 'warn');
+        if (failing.length > 0) return no(failing.map((check) => `${check.name}: ${check.detail}`).join('; '), failing.map((check) => check.fix).join('; '));
+        return ok([...required.map((check) => check.detail), ...warnings.map((check) => `${check.name}: ${check.detail}`)].join(', '));
+      },
+    },
+    {
+      id: 'project',
+      title: 'The app has an ias.json',
+      description: 'ias.json goes in git and holds no secrets: the tokens and keys are op:// references.',
+      check: () => {
+        const project = projectSafe(ctx.dir);
+        if (project.error) return no(project.error.message, project.error.fix, { code: project.error.code });
+        if (!project.config) return no(`no ${CONFIG_FILE} in ${ctx.dir}`, 'ias setup next writes it from app.json (ias init)', { command: 'ias init' });
+        const config = project.config;
+        if (!CODE.test(config.app ?? '')) return no(`${CONFIG_FILE} has no valid app (${config.app ?? 'none'})`, 'write the code of the application in app, or run ias init --app <code>');
+        ctx.config = config;
+        return ok(`${CONFIG_FILE}: app ${config.app} on ${config.server ?? 'https://ias.imagina.build (the default)'}`);
+      },
+      async run() {
+        const project = projectSafe(ctx.dir);
+        if (project.error) throw project.error;
+        if (project.config) return { changed: false };
+        init(ctx.dir, { app: ctx.values.app, dryRun: ctx.values['dry-run'] === true }, ctx.output);
+        ctx.config = projectSafe(ctx.dir).config;
+        return { changed: true };
+      },
+    },
+    {
+      id: 'login',
+      title: 'This computer is authorized',
+      description: 'A passkey approves this computer and keeps a personal token (iasp_…). On CI, IAS_TOKEN is the token and this step is done.',
+      requires: ['project'],
+      check: () => {
+        const server = originOf(ctx.dir, ctx.env);
+        try {
+          const { token, source } = manageToken(server, ctx.env);
+          return ok(`token from ${source}`);
+        } catch (error) {
+          return no(`not logged in to ${server}`, 'ias setup next runs ias login (a passkey approves the code it shows)', { code: error.code });
+        }
+      },
+      async run() {
+        if (ctx.values['dry-run']) {
+          ctx.output.progress(`${ctx.output.prefix}: would run ias login`);
+          return { dry_run: true };
+        }
+        const { login } = await import('./commands/auth/index.mjs');
+        return login({ values: { project: ctx.dir, team: ctx.values.team }, cwd: ctx.dir, env: ctx.env, output: ctx.output, sleep: ctx.sleep, openUrl: ctx.openUrl });
+      },
+    },
+    {
+      id: 'application',
+      title: 'The application exists in IAS',
+      description: 'An owner creates the application here with ias setup --create-app (or ias apps --create), or in the panel. Its code is the one of ias.json, and its bundle id and package must be the ones of app.json.',
+      requires: ['login'],
+      check: async () => {
+        const project = projectSafe(ctx.dir);
+        if (project.config) ctx.config = project.config;
+        if (!ctx.config) return no('there is no ias.json', 'ias setup next writes it first', { command: 'ias init' });
+        let app;
+        try {
+          app = await getApp(ctx);
+        } catch (error) {
+          if (error.code === 'application_not_found' || error.status === 404) {
+            return no(`the application ${ctx.config.app} is not in IAS`, `create it with ias setup --create-app (an owner with a personal token), or in the panel: ${panel(ctx, '/applications')}`, { url: panel(ctx, '/applications'), command: 'ias setup --create-app' });
+          }
+          throw error;
+        }
+        const expo = expoOf(ctx.dir);
+        const mismatches = [];
+        const pairs = { ios: ['bundle_id', expo.ios?.bundleIdentifier], android: ['package', expo.android?.package] };
+        for (const [platform, [field, expected]] of Object.entries(pairs)) {
+          const actual = app[platform]?.[field];
+          if (expected && actual && actual !== expected) mismatches.push(`${platform}: IAS has ${actual}, app.json has ${expected}`);
+        }
+        if (mismatches.length > 0) return no(`the application ${app.code} does not match app.json (${mismatches.join('; ')})`, `fix it in the panel: ${panel(ctx, `/applications/${app.code}/settings`)}`, { url: panel(ctx, `/applications/${app.code}/settings`) });
+        return ok(`application ${app.code} (${(app.services ?? []).length > 0 ? app.services.join(', ') : 'no services yet'})`);
+      },
+      ...(ctx.values['create-app'] ? {
+        async run() {
+          const expo = expoOf(ctx.dir);
+          const details = {
+            code: ctx.config.app,
+            name: ctx.values.name ?? expo.name ?? ctx.config.app,
+            iosBundleId: ctx.values['ios-bundle-id'] ?? expo.ios?.bundleIdentifier,
+            androidPackage: ctx.values['android-package'] ?? expo.android?.package,
+            appleTeamId: ctx.values['apple-team-id'] ?? expo.ios?.appleTeamId,
+            services: ctx.services,
+          };
+          if (ctx.values['dry-run']) {
+            const plan = applicationPlan(details);
+            printApplicationPlan(plan, ctx.output);
+            return plan;
+          }
+          return createApplication(await api(ctx), details);
+        },
+      } : {}),
+    },
+    {
+      id: 'services',
+      title: 'The services the app uses are on',
+      description: 'Updates, distribution and push are optional per application. ias setup next makes the OTA and distribution projects here (an owner with a personal token) and turns push on with its install key.',
+      requires: ['application'],
+      optional: () => ctx.services.length === 0,
+      check: async () => {
+        const app = await getApp(ctx);
+        const missing = [];
+        if (selected('updates') && !app.updates) missing.push('updates');
+        if (selected('distribution') && !app.distribution) missing.push('distribution');
+        if (selected('push') && !(app.services ?? []).includes('push')) missing.push('push');
+        if (missing.length > 0) {
+          return no(`missing in ${app.code}: ${missing.join(', ')}`, `ias setup next makes ${missing.join(' and ')} here (an owner with a personal token), or turn them on in the panel: ${panel(ctx, `/applications/${app.code}/settings`)}`, { url: panel(ctx, `/applications/${app.code}/settings`), command: 'ias setup next' });
+        }
+        if (selected('push') && !projectSafe(ctx.dir).config?.push?.installKey) {
+          return no(`${app.code} has push on but ias.json has no push.installKey`, 'ias setup next reads it from the API or makes one; the install key is not a secret', { command: 'ias setup next' });
+        }
+        const parts = [];
+        if (app.updates) parts.push(`updates ${app.updates.project} (${app.updates.manifest_url})`);
+        if (app.distribution) parts.push(`distribution ${app.distribution.project} (${app.distribution.install_url})`);
+        if ((app.services ?? []).includes('push')) parts.push('push');
+        return ok(parts.length > 0 ? parts.join(', ') : 'no service');
+      },
+      async run() {
+        const app = await getApp(ctx);
+        const client = await api(ctx);
+        const made = [];
+        if (selected('updates') && !app.updates) {
+          made.push(await provisionOta({ dir: ctx.dir, env: ctx.env, output: ctx.output, values: ctx.values, client, sleep: ctx.sleep, dryRun: ctx.values['dry-run'] === true }));
+        }
+        if (selected('distribution') && !app.distribution) {
+          made.push(await provisionDistribution({ dir: ctx.dir, env: ctx.env, output: ctx.output, values: ctx.values, client, sleep: ctx.sleep, dryRun: ctx.values['dry-run'] === true }));
+        }
+        if (selected('push') && (!(app.services ?? []).includes('push') || !projectSafe(ctx.dir).config?.push?.installKey)) {
+          made.push(await ensurePush({ client, dir: ctx.dir, app: app.code, output: ctx.output, dryRun: ctx.values['dry-run'] === true }));
+        }
+        return { made };
+      },
+    },
+    {
+      id: 'stores',
+      title: 'The app exists in the stores',
+      description: 'The bundle id and the App Store Connect app record, and the Google Play package. IAS creates neither the app record nor the Play app: a person does it on the web, and this checks what IAS keeps. It blocks neither builds nor updates.',
+      requires: ['application'],
+      optional: () => true,
+      check: async () => {
+        const app = await getApp(ctx);
+        const panels = panel(ctx, `/applications/${app.code}/settings`);
+        if (!app.ios?.bundle_id && !app.android?.package) {
+          return no(`the application ${app.code} has no iOS bundle id and no Android package`, `set them in the panel: ${panels}`, { url: panels });
+        }
+        if (app.ios?.bundle_id && !app.ios.asc_app_id) {
+          const sku = `IAS-${app.code.toUpperCase()}`;
+          return no(
+            `iOS: the bundle id ${app.ios.bundle_id} has no app record in IAS; once it exists: ias apps store ${app.code} --check`,
+            `a person creates it in https://appstoreconnect.apple.com/apps (name ${app.name}, bundle id ${app.ios.bundle_id}, SKU ${sku}; the SKU cannot change afterwards) and then runs: ias apps store ${app.code} --check`,
+            { command: `ias apps store ${app.code} --check`, code: 'asc_app_missing' },
+          );
+        }
+        const parts = [];
+        if (app.ios?.bundle_id) parts.push(`iOS: ${app.ios.bundle_id}, app record ${app.ios.asc_app_id}${app.ios.asc_app_checked_at ? ` (checked ${app.ios.asc_app_checked_at.slice(0, 10)})` : ' (not checked against Apple)'}`);
+        if (app.android?.package) parts.push(`Android: ${app.android.package} (in Play: confirmed by the first release)`);
+        return ok(parts.join(', '));
+      },
+    },
+    {
+      id: 'sdk',
+      title: `The SDK ${SDK_PACKAGE} is in the app`,
+      description: 'It brings ias.sync and ias.push, and its config plugin writes the updates URL, the certificate and the push configuration from ias.json into the builds.',
+      requires: ['application'],
+      optional: () => !selected('updates') && !selected('push'),
+      check: () => {
+        let state;
+        try {
+          state = sdkState(ctx.dir);
+        } catch (error) {
+          return no(error.message, error.fix);
+        }
+        const wanted = expoModulesFor({ updates: selected('updates'), push: selected('push') });
+        const missing = wanted.filter((name) => !state.dependencies[name]);
+        if (!state.declared && !state.installed) return no(`${SDK_PACKAGE} is not installed`, 'ias setup next runs ias sdk install, with its plugin and the Expo modules of the services');
+        if (!state.installed) return no(`${SDK_PACKAGE} ${state.declared} is in package.json, but not installed`, 'ias setup next runs ias sdk install');
+        if (state.plugin !== 'yes') {
+          return no(`app.json does not have the plugin of ${SDK_PACKAGE}${state.plugin === 'dynamic' ? ` (${state.dynamic} is code)` : ''}`, state.plugin === 'dynamic' ? `add "${SDK_PACKAGE}" to the plugins of ${state.dynamic}, for a new build` : 'ias setup next runs ias sdk install, which adds it');
+        }
+        if (missing.length > 0) return no(`${SDK_PACKAGE} ${state.installed}; missing ${missing.join(', ')}`, `ias setup next runs npx expo install ${missing.join(' ')}`);
+        return ok(`${SDK_PACKAGE} ${state.installed}, plugin in app.json${wanted.length > 0 ? `, ${wanted.join(', ')}` : ''}`);
+      },
+      async run() {
+        const wanted = expoModulesFor({ updates: selected('updates'), push: selected('push') });
+        installSdk(ctx.dir, { dryRun: ctx.values['dry-run'], modules: wanted }, { output: ctx.output, env: ctx.env });
+        return { installed: true };
+      },
+    },
+    {
+      id: 'vault',
+      title: 'The team vault has its keys',
+      description: 'The recovery key opens every sealed credential and the signing key signs its envelope. Their private halves live only in 1Password.',
+      requires: ['login'],
+      check: async () => {
+        let vault;
+        try {
+          vault = await getVault(ctx);
+        } catch (error) {
+          return no(error.message, error.fix, { code: error.code });
+        }
+        if (!vault.recovery_key || !vault.signing_key) {
+          return no(`the vault of ${originOf(ctx.dir, ctx.env)} has no keys`, 'an owner runs ias setup next (ias vault init) and approves it with a passkey in the panel', { command: 'ias vault init' });
+        }
+        return ok(`recovery ${vault.recovery_key.kid.slice(0, 12)}…, signing ${vault.signing_key.kid.slice(0, 12)}…`);
+      },
+      async run() {
+        if (ctx.values['dry-run']) {
+          ctx.output.progress(`${ctx.output.prefix}: would run ias vault init`);
+          return { dry_run: true };
+        }
+        const { init: vaultInit } = await import('./commands/vault/index.mjs');
+        return vaultInit({ values: { project: ctx.dir, item: ctx.values.item }, cwd: ctx.dir, env: ctx.env, output: ctx.output, sleep: ctx.sleep, openUrl: ctx.openUrl });
+      },
+    },
+    {
+      id: 'credentials',
+      title: 'The signing credentials are in the vault',
+      description: 'The certificates, profiles and keystores of the app, sealed on this computer. The files come from Apple and Google; ias never prints a password.',
+      requires: ['vault', 'services'],
+      optional: () => !selected('updates') && !selected('distribution') && !selected('push'),
+      check: async () => {
+        const app = await getApp(ctx);
+        const client = await api(ctx);
+        const found = new Set((await client.request('GET', `/apps/${app.code}/credentials`)).data.data.map((credential) => credential.type));
+        try {
+          for (const credential of (await client.request('GET', '/team/credentials')).data.data) found.add(credential.type);
+        } catch (error) {
+          if (error.code !== 'role_forbidden') throw error;
+        }
+        const needed = platformsOf(ctx).flatMap((platform) => REQUIRED_CREDENTIALS[platform] ?? []);
+        const missing = needed.filter((type) => !found.has(type));
+        if (missing.length > 0) {
+          const commands = platformsOf(ctx).flatMap((platform) => CREDENTIAL_COMMANDS[platform] ?? []).join('\n  ');
+          return no(`missing ${missing.join(', ')}`, `make or import them with ias credentials (the short path for iOS is ias credentials generate ios), or with ias migrate eas if the app comes from EAS:
+  ${commands}`, { command: missing.some((type) => type.startsWith('apple_')) ? 'ias credentials generate ios' : 'ias credentials list' });
+        }
+        return ok(`${needed.length} credential types in the app and the team`);
+      },
+    },
+    {
+      id: 'signing',
+      title: 'The iOS signing material is generated or reused',
+      description: 'The team\'s distribution certificate and the App Store profile of the bundle id, in the vault. The short path is ias credentials generate ios: it reuses what is valid and makes only what is missing. This check is read-only and offline (the server\'s credentials only): whether Apple still lists the certificate is what the command says when it runs.',
+      requires: ['credentials'],
+      optional: () => true,
+      check: async () => {
+        const app = await getApp(ctx);
+        const command = 'ias credentials generate ios';
+        if (!platformsOf(ctx).includes('ios')) return ok('the app does not use iOS: there is no iOS signing material to prepare');
+        if (!app.ios?.bundle_id) {
+          return no(`the application ${app.code} has no iOS bundle id (${command})`, `set it in the panel: ${panel(ctx, `/applications/${app.code}/settings`)}`, { url: panel(ctx, `/applications/${app.code}/settings`), code: 'application_without_ios' });
+        }
+        const client = await api(ctx);
+        const own = (await client.request('GET', `/apps/${app.code}/credentials`)).data.data;
+        let team = [];
+        try {
+          team = (await client.request('GET', '/team/credentials')).data.data;
+        } catch (error) {
+          if (error.code !== 'role_forbidden') throw error;
+        }
+        const now = Date.now();
+        const live = (credential) => !credential.retired_at && (!credential.expires_at || Date.parse(credential.expires_at) > now);
+        const latest = (list) => [...list].sort((a, b) => (Date.parse(b.expires_at ?? '9999') || 0) - (Date.parse(a.expires_at ?? '9999') || 0))[0];
+
+        if (!team.some((credential) => credential.type === 'asc_api_key' && live(credential))) {
+          return no(`the vault has no App Store Connect key (${command})`, `import it with ias credentials import asc_api_key --p8 <AuthKey_….p8> --key-id <id> --issuer-id <uuid>; then: ${command}`, { command, code: 'credentials_missing' });
+        }
+        const certificates = team.filter((credential) => credential.type === 'apple_distribution_certificate' && credential.metadata?.kind === 'distribution' && (!app.ios.team_id || credential.metadata?.team === app.ios.team_id));
+        const usable = certificates.filter(live);
+        if (usable.length === 0) {
+          const expired = certificates.filter((credential) => !credential.retired_at && credential.expires_at).sort((a, b) => Date.parse(b.expires_at) - Date.parse(a.expires_at))[0];
+          if (expired && Date.parse(expired.expires_at) <= now) return no(`the distribution certificate expired on ${expired.expires_at.slice(0, 10)} (${command})`, `${command} makes a new one and regenerates the App Store profile; the ad hoc one, afterwards, with ias devices sync --force`, { command, code: 'certificate_expired' });
+          const retired = certificates.find((credential) => credential.retired_at);
+          if (retired) return no(`the distribution certificate was retired on ${retired.retired_at.slice(0, 10)} (${command})`, `${command} makes a new one and regenerates the App Store profile`, { command, code: 'certificate_retired' });
+          return no(`the vault has no distribution certificate of the team ${app.ios.team_id ?? ''} (${command})`.trim(), `${command} makes it on this Mac with the App Store Connect key of the vault, without the server ever seeing the private key`, { command, code: 'certificate_missing' });
+        }
+        const certificate = latest(usable);
+        const sha1 = String(certificate.metadata?.sha1 ?? '').toUpperCase();
+        const profiles = own.filter((credential) => live(credential) && credential.type === 'apple_provisioning_profile' && credential.metadata?.type === 'app-store' && credential.metadata?.bundleId === app.ios.bundle_id);
+        const valid = profiles.filter((credential) => (credential.metadata?.certificates ?? []).map((value) => String(value).toUpperCase()).includes(sha1));
+        const profile = latest(valid);
+        if (!profile) {
+          const expired = profiles.filter((credential) => credential.expires_at && Date.parse(credential.expires_at) <= now).sort((a, b) => Date.parse(b.expires_at) - Date.parse(a.expires_at))[0];
+          if (expired) return no(`the App Store profile expired on ${expired.expires_at.slice(0, 10)} (${command})`, `${command} makes another one with the current certificate and seals it; the ad hoc one is untouched`, { command, code: 'profile_expired' });
+          return no(`the vault has no App Store profile of ${app.ios.bundle_id}, or it does not contain the current certificate (${sha1}) (${command})`, `${command} makes it and seals it as the next version; the ad hoc profile of ias devices sync is untouched`, { command, code: 'profile_missing' });
+        }
+        const origin = certificate.metadata?.appleCertificateId ? 'generated by ias' : 'imported';
+        const note = certificate.expires_at && Date.parse(certificate.expires_at) - now < 30 * 86400000 ? ' · the certificate expires within 30 days: the command renews it if Apple allows' : '';
+        return ok(`certificate ${sha1} until ${String(certificate.expires_at ?? '').slice(0, 10)} (${origin}), App Store profile ${profile.metadata.uuid} until ${String(profile.expires_at ?? '').slice(0, 10)}${note}; this check does not call Apple: ${command} checks that Apple still has both and reuses them`);
+      },
+    },
+    {
+      id: 'runner',
+      title: 'A runner compiles the app',
+      description: 'A runner is a machine of the team with the toolchain. ias setup next asks for a one-time code, prints the ias-runner register command for that Mac and leaves it pending until a member authorizes it with ias vault grant.',
+      requires: ['vault'],
+      optional: () => ctx.values['local-builds'] === true,
+      check: async () => {
+        let vault;
+        try {
+          vault = await getVault(ctx);
+        } catch (error) {
+          return no(error.message, error.fix, { code: error.code });
+        }
+        const runners = (vault.runner_list?.runners ?? vault.runners ?? []).filter((runner) => runner.status !== 'revoked');
+        if (!vault.runner_list || vault.runner_list.serial === null || runners.length === 0) {
+          return no('the team has no runner in the list it signed', `ias setup next asks for a one-time code (or ias runners code) and prints the ias-runner register command for the runner Mac; then authorize it here with ias vault grant "<its name>" (the panel also makes codes: ${panel(ctx, '/runners')})`, { url: panel(ctx, '/runners'), command: 'ias setup next' });
+        }
+        return ok(`${runners.length} runner${runners.length === 1 ? '' : 's'} in the signed list (serial ${vault.runner_list.serial})`);
+      },
+      async run() {
+        return createRunnerCode({ dir: ctx.dir, env: ctx.env, output: ctx.output, client: await api(ctx), sleep: ctx.sleep, dryRun: ctx.values['dry-run'] === true });
+      },
+    },
+    {
+      id: 'build',
+      title: 'The first build works',
+      description: 'A build is made from a clean commit. An internal build (preview) needs no approval; a store build waits for an owner with a passkey.',
+      requires: ['credentials', 'runner'],
+      optional: () => ctx.services.length === 0,
+      check: async () => {
+        if (ctx.values['local-builds']) {
+          const folder = join(ctx.env.HOME ?? '', 'ias-builds', ctx.config?.app ?? '');
+          if (existsSync(folder)) return ok(`local builds in ${folder}`);
+          return no(`no local builds in ${folder}`, 'ias build --local --profile preview --platform all', { command: 'ias build --local --profile preview --platform all' });
+        }
+        const app = await getApp(ctx);
+        const client = await api(ctx);
+        const { data } = await client.request('GET', `/apps/${app.code}/builds`);
+        const builds = data.data ?? [];
+        const succeeded = builds.filter((build) => build.status === 'succeeded');
+        if (succeeded.length === 0) {
+          const latest = builds[0];
+          return no(latest ? `the latest build is ${latest.status}` : 'the application has no builds', 'ias build --profile preview --platform all', { command: 'ias build --profile preview --platform all' });
+        }
+        return ok(`${succeeded.length} build${succeeded.length === 1 ? '' : 's'} succeeded; the latest is ${succeeded[0].platform} ${succeeded[0].version} (${succeeded[0].build_number ?? '?'})`);
+      },
+    },
+    {
+      id: 'testflight',
+      title: 'TestFlight is optional: the build can reach its testers',
+      description: 'A store iOS build that ias submit sent to App Store Connect is distributed to TestFlight groups with ias testflight, and only if external testers need it, sent to Beta App Review with ias testflight review: two commands and two passkeys. This step never runs in ias setup next --all.',
+      requires: ['build'],
+      optional: () => true,
+      check: async () => {
+        if (!platformsOf(ctx).includes('ios')) return ok('the app does not use iOS: TestFlight does not apply');
+        const app = await getApp(ctx);
+        const client = await api(ctx);
+        const builds = (await client.request('GET', `/apps/${app.code}/builds?platform=ios`)).data.data ?? [];
+        const sent = builds.find((build) => build.status === 'succeeded' && build.distribution === 'store' && (build.submissions ?? []).some((submission) => submission.target === 'app_store_connect' && submission.status === 'succeeded'));
+        if (!sent) {
+          return no('no iOS store build is in App Store Connect yet', 'ias build --platform ios --profile production, then ias submit <build> --wait', { command: 'ias build --platform ios --profile production' });
+        }
+        return ok(`build ${sent.version} (${sent.build_number ?? '?'}) is in TestFlight; ias testflight ${sent.id} distributes it`, { command: `ias testflight ${sent.id}` });
+      },
+    },
+    {
+      id: 'updates',
+      title: 'The app is ready to publish OTA updates',
+      description: 'The project, the signing key and the token are in place. The first update is signed on this Mac with the key of 1Password; the server only checks the signature.',
+      requires: ['build', 'sdk', 'services'],
+      service: 'updates',
+      check: async () => {
+        const app = await getApp(ctx);
+        const project = projectSafe(ctx.dir);
+        const signing = project.config?.updates?.signing;
+        if (!app.updates) return no(`the application ${app.code} has no OTA project`, `run ias update init (an owner with a personal token); the guide (docs/guide/actualizaciones.md#alta-del-proyecto-una-vez) has the artisan command if the API is not available`);
+        if (!signing?.keyId || !signing?.privateKey || !signing?.certificate) {
+          return no(`ias.json has no updates.signing (keyId, privateKey and certificate)`, 'keep the private key in 1Password and set its op:// reference, the keyid and the certificate in ias.json; docs/guide/actualizaciones.md#alta-del-proyecto-una-vez has the openssl command that makes them');
+        }
+        const certificate = join(ctx.dir, signing.certificate);
+        if (!existsSync(certificate)) return no(`no certificate at ${signing.certificate}`, 'restore it from git: it is the public half of the key, and every build carries it');
+        return ok(`project ${app.updates.project}, keyid ${signing.keyId}, certificate ${signing.certificate}; publish with ias update publish --message "…"`);
+      },
+    },
+    {
+      id: 'distribution',
+      title: 'The install page is ready',
+      description: 'A preview build (an ad hoc IPA or an APK) is published by itself, with an install page and a stable link.',
+      requires: ['build', 'services'],
+      service: 'distribution',
+      check: async () => {
+        const app = await getApp(ctx);
+        if (!app.distribution) return no(`the application ${app.code} has no distribution project`, `run ias dist init (an owner with a personal token), or turn distribution on in the panel: ${panel(ctx, `/applications/${app.code}/settings`)}`, { url: panel(ctx, `/applications/${app.code}/settings`) });
+        return ok(`project ${app.distribution.project}, stable link ${app.distribution.install_url}; ias dist list shows the builds`);
+      },
+    },
+    {
+      id: 'push',
+      title: 'The app sends push notifications',
+      description: 'ias.push registers the device and receives the sync notices. The install key is not a secret; the APNs and FCM credentials are, and a member approves them.',
+      requires: ['build', 'sdk', 'services'],
+      service: 'push',
+      check: async () => {
+        const app = await getApp(ctx);
+        const config = projectSafe(ctx.dir).config;
+        if (!(app.services ?? []).includes('push')) return no(`push is not on for ${app.code}`, `ias setup next turns it on; or in the panel: ${panel(ctx, `/applications/${app.code}/settings`)}`, { url: panel(ctx, `/applications/${app.code}/settings`) });
+        if (!config?.push?.installKey) return no('ias.json has no push.installKey', 'ias setup next reads it from the API and writes it; it is not a secret');
+        const googleServices = config.push?.android?.googleServicesFile;
+        if (googleServices && !existsSync(join(ctx.dir, googleServices))) return no(`no ${googleServices}`, 'download it from the Firebase project of the app, or remove push.android.googleServicesFile');
+        return ok('push is on and ias.json has its install key; ias push credentials loads the APNs and FCM keys');
+      },
+    },
+    {
+      id: 'ci',
+      title: 'CI has its robot token',
+      description: 'Optional: a robot token of the application (iasr_…) in IAS_TOKEN, made by an owner with ias tokens create (or in the panel). It is what CI uses instead of a person.',
+      requires: ['build'],
+      optional: () => true,
+      check: () => (ctx.env.IAS_TOKEN ? ok('IAS_TOKEN is set') : no('IAS_TOKEN is not set', `make one with ias tokens create --app ${ctx.config?.app ?? '<app>'} (an owner with a personal token), or in the panel (${panel(ctx, '/applications/' + (ctx.config?.app ?? '<app>') + '/access')}), and set IAS_TOKEN in CI`, { url: panel(ctx, `/applications/${ctx.config?.app ?? ''}/access`), command: `ias tokens create --app ${ctx.config?.app ?? '<app>'}` })),
+    },
+  ];
+}
+
+/** A context with what the checks read; the tests pass their own client, probe and sleep. */
+export function createSetupContext({ dir, env = process.env, output, values = {}, state = {}, services, probe = systemProbe, platform = process.platform, nodeVersion = process.versions.node, sleep, openUrl, client, aapt2 }) {
+  const project = projectSafe(resolve(dir));
+  const config = project.config;
+  const chosen = services ?? state.services ?? inferServices({ config, expo: expoOf(resolve(dir)), dependencies: sdkDependencies(resolve(dir)) });
+  return { dir: resolve(dir), env, output, values, state, services: chosen.filter((service) => SERVICES.includes(service)), probe, platform, nodeVersion, sleep, openUrl, client, aapt2, config, appData: undefined, vaultData: undefined, session: undefined };
+}
+
+function sdkDependencies(dir) {
+  try {
+    return sdkState(dir).dependencies;
+  } catch {
+    return {};
+  }
+}
+
+/** One check, never a throw: an error becomes a step that says what happened and how to fix it. */
+async function checkStep(step, ctx) {
+  try {
+    const result = await step.check(ctx);
+    return result ?? ok('done');
+  } catch (error) {
+    if (error.code === 'not_logged_in') return no('not logged in', 'ias setup next runs ias login', { code: error.code });
+    if (error instanceof IasError) return no(error.message, error.fix, { code: error.code });
+    return no(error.message ?? String(error), 'run ias doctor to check this computer and the app');
+  }
+}
+
+/** The checklist: every step with its status, detail and what is next. */
+export async function setupPlan(ctx) {
+  const steps = buildSteps(ctx);
+  const results = [];
+  const byId = new Map();
+  ctx.appData = undefined;
+  ctx.vaultData = undefined;
+  for (const step of steps) {
+    const selected = !step.service || ctx.services.includes(step.service);
+    const optional = step.optional?.(ctx) === true || !selected;
+    let result;
+    if (!selected) {
+      result = { ok: false, optional: true, detail: `not part of this setup (${step.service} is off)`, fix: null };
+    } else {
+      const missing = (step.requires ?? []).filter((id) => {
+        const required = byId.get(id);
+        return required && !required.optional && required.status !== STATUS.DONE;
+      });
+      if (missing.length > 0) result = { ok: false, optional, detail: optional ? `optional, after ${missing.join(', ')}` : `finish ${missing.join(', ')} first`, fix: null };
+      else result = { ...(await checkStep(step, ctx)), optional };
+    }
+    const entry = {
+      id: step.id,
+      title: step.title,
+      description: step.description,
+      requires: step.requires ?? [],
+      kind: step.run ? 'auto' : 'manual',
+      optional: result.optional,
+      status: !selected ? STATUS.OPTIONAL : result.optional && !result.ok ? STATUS.OPTIONAL : result.ok ? STATUS.DONE : result.detail?.startsWith('finish ') ? STATUS.LOCKED : STATUS.READY,
+      detail: result.detail,
+      ...(result.fix ? { fix: result.fix } : {}),
+      ...(result.command ? { command: result.command } : {}),
+      ...(result.url ? { url: result.url } : {}),
+      ...(result.code ? { code: result.code } : {}),
+    };
+    byId.set(step.id, entry);
+    results.push(entry);
+  }
+  const required = results.filter((step) => !step.optional);
+  const done = required.filter((step) => step.status === STATUS.DONE);
+  const next = results.find((step) => !step.optional && step.status !== STATUS.DONE) ?? null;
+  return { steps: results, complete: required.every((step) => step.status === STATUS.DONE), counts: { done: done.length, required: required.length }, next: next?.id ?? null };
+}
+
+/** Runs the step `id` (the first one not done by default) if it is its turn, and returns what it did. */
+export async function setupNext(ctx, { id, all = false, plan } = {}) {
+  const current = plan ?? (await setupPlan(ctx));
+  const step = id ? current.steps.find((candidate) => candidate.id === id) : current.steps.find((candidate) => !candidate.optional && candidate.status !== STATUS.DONE);
+  if (!step) return { plan: current, ran: null, complete: current.complete };
+  const definition = buildSteps(ctx).find((candidate) => candidate.id === step.id);
+  if (step.status === STATUS.DONE) return { plan: current, ran: null, complete: current.complete };
+  if (step.status === STATUS.LOCKED) {
+    throw new IasError(`ias setup cannot run ${step.id} yet: ${step.detail}`, { fix: `run ias setup next first` });
+  }
+  if (!definition.run) return { plan: current, ran: null, complete: false, waiting: step };
+  const run = await definition.run(ctx);
+  const after = await setupPlan(ctx);
+  if (!all) return { plan: after, ran: step.id, result: run, complete: after.complete, waiting: after.steps.find((candidate) => !candidate.optional && candidate.status !== STATUS.DONE && candidate.kind === 'manual') ?? null };
+  const last = after.steps.find((candidate) => candidate.id === step.id);
+  if (last?.status !== STATUS.DONE) return { plan: after, ran: step.id, result: run, complete: after.complete, waiting: last };
+  if (after.complete || after.next === null) return { plan: after, ran: step.id, result: run, complete: after.complete };
+  return setupNext(ctx, { all, plan: after });
+}
+
+const SYMBOL = { [STATUS.DONE]: '[x]', [STATUS.READY]: '[>]', [STATUS.LOCKED]: '[ ]', [STATUS.OPTIONAL]: '[-]' };
+
+/** The checklist for people, the lines of `ias setup`. */
+export function printPlan(plan, ctx, output) {
+  const app = ctx.config?.app ?? '(no ias.json)';
+  const server = originOf(ctx.dir, ctx.env);
+  output.log(`${output.prefix} setup: ${app} on ${server} — ${plan.counts.done} of ${plan.counts.required} steps${plan.complete ? ', complete' : ''}`);
+  output.log('');
+  const width = Math.max(...plan.steps.map((step) => step.id.length));
+  for (const step of plan.steps) {
+    output.log(`  ${SYMBOL[step.status]} ${step.id.padEnd(width)}  ${step.detail}`);
+    if (step.fix && step.status !== STATUS.DONE && step.status !== STATUS.LOCKED && (step.status !== STATUS.OPTIONAL || step.command)) {
+      const indent = `      ${' '.repeat(width)}  → `;
+      output.log(step.fix.split('\n').map((line, index) => (index === 0 ? `${indent}${line}` : `      ${' '.repeat(width)}    ${line}`)).join('\n'));
+    }
+  }
+  const waiting = plan.steps.find((step) => !step.optional && step.status !== STATUS.DONE);
+  if (waiting) output.log(`\nnext: ias setup next  (${waiting.id}${waiting.kind === 'manual' ? ': a person' : ''})`);
+  else output.log('\nthe checklist is complete: ias build, ias update publish and ias push are next.');
+}
+
+
+
+/** The first build, opt-in with `ias setup next --build <profile>`: it runs ias build on the runner or this Mac. */
+export async function runSetupBuild(ctx) {
+  const plan = await setupPlan(ctx);
+  const step = plan.steps.find((candidate) => candidate.id === 'build');
+  if (!step || step.status === STATUS.LOCKED) throw new IasError(`ias setup cannot build yet: ${step?.detail ?? 'the checklist has no build step'}`, { fix: 'finish the steps before it, or run ias setup next first' });
+  const { default: buildCommand } = await import('./commands/build/index.mjs');
+  const profile = typeof ctx.values.build === 'string' ? ctx.values.build : 'preview';
+  return buildCommand.run({
+    values: {
+      project: ctx.dir,
+      profile,
+      platform: 'all',
+      ...(ctx.values['local-builds'] ? { local: true } : {}),
+      ...(ctx.values.message ? { message: ctx.values.message } : {}),
+      ...(ctx.values.wait ? { wait: true } : {}),
+    },
+    cwd: ctx.dir,
+    env: ctx.env,
+    output: ctx.output,
+    openUrl: ctx.openUrl,
+  });
+}
+
+/** The first OTA update, opt-in with `ias setup next --publish`: it signs with the key of 1Password. */
+export async function runSetupPublish(ctx) {
+  const plan = await setupPlan(ctx);
+  const build = plan.steps.find((candidate) => candidate.id === 'build');
+  const updates = plan.steps.find((candidate) => candidate.id === 'updates');
+  if (!build || build.status !== STATUS.DONE) throw new IasError('there is no build to publish: run ias setup next --build preview first', { fix: 'a build has to carry the updates URL and certificate, and be built before the update' });
+  if (!updates || updates.status !== STATUS.DONE) throw new IasError(`the app is not ready to publish: ${updates?.detail ?? 'there is no updates step'}`, { fix: updates?.fix ?? 'finish the updates step first' });
+  const { projectFor, updateSettings } = await import('./config.mjs');
+  const { publish, withChannels } = await import('./commands/update/index.mjs');
+  const project = projectFor(ctx.dir, 'updates');
+  const settings = withChannels(updateSettings(project, ctx.env), project);
+  return publish(settings, { message: ctx.values.message ?? 'First update', platforms: ['ios', 'android'], rollout: 100, dryRun: ctx.values['dry-run'] === true }, ctx.output);
+}
+
+export { STATUS };