@imagina-build/ias-cli 0.0.0 → 0.1.1

package/src/commands/migrate/variables.mjs

@@ -0,0 +1,183 @@
+// ias migrate eas env: the variables of EAS's environments into those of IAS (docs/technical/manage-api.md §9), as ias env set
+// stores them: EXPO_PUBLIC_* in plain, because they end up in the bundle, and any other sealed on this Mac for the
+// recovery key and the signed runners. They come from eas env:list, which ias runs without a terminal and reads here,
+// or from the .env of eas env:pull (--env-file). A secret variable of EAS cannot be read outside its builders: those
+// are listed for ias env set. A variable already in IAS is kept unless --force. Only plain values are ever printed.
+import { Buffer } from 'node:buffer';
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, rmSync, rmdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { IasError, UsageError } from '../../errors.mjs';
+import { applicationOf, connect } from '../../manage.mjs';
+import { encodePlaintext, seal, verifyEnvelope } from '../../shared.mjs';
+import { sealingKeys, vaultItem } from '../../team-vault.mjs';
+import { ENVIRONMENTS } from '../env/index.mjs';
+import { parseEnvFile, parseVariableList, runEas } from './eas-cli.mjs';
+import { easFolder } from './numbers.mjs';
+import { iasCommand, isInside, preparedFolders, projectDir, readApp } from './project.mjs';
+
+const NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
+const isPublic = (name) => name.startsWith('EXPO_PUBLIC_');
+
+/** The variables of an environment from the .env that eas env:pull wrote. */
+function fromFile(context) {
+  const { values, cwd } = context;
+  if (!values.environment) throw new UsageError('which environment is the file of?', { fix: '--environment development|preview|production: the one given to eas env:pull' });
+  const file = resolve(cwd, values['env-file']);
+  if (!existsSync(file)) throw new IasError(`there is no file ${values['env-file']}`, { fix: 'eas env:pull --environment <environment> --path <file> writes it, run in the folder of ias migrate eas prepare' });
+  const parsed = parseEnvFile(readFileSync(file, 'utf8'));
+  if (parsed.environment && parsed.environment !== values.environment) throw new IasError(`${values['env-file']} holds the environment ${parsed.environment}, not ${values.environment}`, { fix: `pass --environment ${parsed.environment}, or pull that one` });
+  return [{ environment: values.environment, from: file, file, variables: parsed.variables, secret: parsed.secret, files: parsed.files, unread: parsed.unread, shared: [] }];
+}
+
+/** The variables of each environment from eas env:list (--format long; eas-cli 24 has no --json there). */
+function fromEas(context, app) {
+  const { values, env } = context;
+  const fix = 'run eas env:pull --environment <environment> --path <file> yourself, in the folder of ias migrate eas prepare, and pass --env-file <file> --environment <environment>';
+  const folder = easFolder(app, env);
+  if (!folder) throw new IasError('app.json does not name its EAS project, so eas cannot read its variables here', { fix: `ias migrate eas prepare --eas-project <id> makes a folder where it can; or ${fix}` });
+  return (values.environment ? [values.environment] : ENVIRONMENTS).map((environment) => {
+    const list = parseVariableList(runEas(['env:list', '--environment', environment, '--include-sensitive', '--format', 'long'], { cwd: folder.dir, env, noVcs: folder.noVcs, fix }));
+    return {
+      environment,
+      from: 'eas env:list',
+      variables: list.filter((variable) => !variable.file && variable.value !== null),
+      secret: list.filter((variable) => !variable.file && variable.value === null).map((variable) => variable.name),
+      files: list.filter((variable) => variable.file).map((variable) => ({ name: variable.name })),
+      unread: 0,
+      shared: list.filter((variable) => variable.scope !== 'project').map((variable) => variable.name),
+    };
+  });
+}
+
+/**
+ * Deletes the .env of eas env:pull, and the files of its file variables, when they are in a folder of prepare: they
+ * hold the values. One elsewhere is the person's, and only named. Returns the paths deleted.
+ */
+function removePulled(source, folders) {
+  const folder = folders.find((candidate) => isInside(candidate.dir, source.file));
+  if (!folder) return null;
+  const removed = [];
+  for (const path of [source.file, ...source.files.map((file) => resolve(dirname(source.file), file.path))]) {
+    if (!existsSync(path) || !isInside(folder.dir, path) || isInside(join(folder.dir, 'node_modules'), path)) continue;
+    rmSync(path, { force: true });
+    removed.push(path);
+  }
+  for (const empty of [join(folder.dir, '.eas', '.env'), join(folder.dir, '.eas')]) {
+    try {
+      rmdirSync(empty);
+    } catch {
+      // not empty, or not there
+    }
+  }
+  return removed;
+}
+
+export async function variables(context) {
+  const { values, env, output } = context;
+  if (values.environment !== undefined && !ENVIRONMENTS.includes(values.environment)) throw new UsageError(`there is no environment «${values.environment}»`, { fix: `one of ${ENVIRONMENTS.join(', ')}` });
+  const dir = projectDir(context);
+  const app = readApp(dir);
+  const project = loadProject(dir);
+  const application = applicationOf(context, project);
+  const client = connect(context, project);
+  const sources = values['env-file'] ? fromFile(context) : fromEas(context, app);
+  const dryRun = Boolean(values['dry-run']);
+  let sealing;
+  const report = [];
+  let failure;
+  try {
+    for (const source of sources) {
+      const entry = { environment: source.environment, from: source.from, set: [], same: [], kept: [], pending: [], files: source.files.map((file) => file.name), left_out: [] };
+      report.push(entry);
+      if (source.variables.length + source.secret.length + source.files.length === 0) {
+        output.log(`${source.environment}: no variables in EAS`);
+        continue;
+      }
+      output.log(`${source.environment}, from ${source.from}:`);
+      const existing = (await client.request('GET', `/apps/${application}/env?environment=${source.environment}`)).data.data;
+      for (const { name, value } of source.variables) {
+        if (!NAME.test(name)) {
+          entry.left_out.push(name);
+          output.log(`  ${name}: IAS takes capitals, digits and _ (up to 64): left out; set it under another name with ias env set`);
+          continue;
+        }
+        const plain = isPublic(name);
+        const there = existing.find((variable) => variable.name === name);
+        const shown = plain ? `${name}=${value}` : name;
+        if (plain && there?.visibility === 'plain' && there.value === value) {
+          entry.same.push(name);
+          output.log(`  ${shown}: already in IAS`);
+          continue;
+        }
+        if (there && !values.force) {
+          entry.kept.push(name);
+          output.log(`  ${name}: already in IAS (${there.visibility}, version ${there.version}); kept, since ${plain ? 'its value differs' : 'a sealed value cannot be compared'} (--force takes EAS's as version ${there.version + 1})`);
+          continue;
+        }
+        if (plain && Buffer.byteLength(value, 'utf8') > 4096) {
+          entry.left_out.push(name);
+          output.warn(`${source.environment} ${name}: more than 4 KB, and a plain variable holds up to 4 KB: left out`);
+          continue;
+        }
+        if (dryRun) {
+          entry.set.push(name);
+          output.log(`  ${shown}: would be ${plain ? 'plain' : 'sealed'}`);
+          continue;
+        }
+        const path = `/apps/${application}/env/${source.environment}/${name}`;
+        if (plain) {
+          const { data } = await client.request('PUT', path, { json: { visibility: 'plain', value } });
+          entry.set.push(name);
+          output.log(`  ${shown}: plain, version ${data.version}`);
+          continue;
+        }
+        sealing ??= await sealingKeys(client, vaultItem(context, project, client.server), env, output);
+        const credential = { id: there?.id ?? randomUUID(), type: 'environment_variable', version: there ? there.version + 1 : 1 };
+        const plaintext = encodePlaintext('environment_variable', { application, environment: source.environment, name, value });
+        let envelope;
+        try {
+          envelope = seal(plaintext, { credential, recipients: sealing.recipients, signingKey: sealing.signingKey });
+          verifyEnvelope(envelope, sealing.keys.signing.publicKey);
+        } finally {
+          plaintext.fill(0);
+        }
+        const { data } = await client.request('PUT', path, { json: { visibility: 'secret', id: credential.id, envelope } });
+        entry.set.push(name);
+        output.log(`  ${name}: sealed for ${envelope.recipients.length} key${envelope.recipients.length === 1 ? '' : 's'}, version ${data.version}`);
+      }
+      for (const name of source.secret) {
+        if (existing.some((variable) => variable.name === name)) {
+          entry.kept.push(name);
+          output.log(`  ${name}: secret in EAS, and already in IAS`);
+          continue;
+        }
+        entry.pending.push(name);
+        output.log(`  ${name}: secret in EAS, where only its builders read it: ias env set ${name} --from op://… --environment ${source.environment}`);
+      }
+      for (const { name } of source.files) output.log(`  ${name}: a file variable of EAS; IAS has none: keep the file in 1Password, or in the app if it is not secret`);
+      for (const name of source.shared) output.log(`  ${name}: an account-wide variable of EAS, now this application's only`);
+      if (source.unread > 0) output.warn(`${source.unread} line${source.unread === 1 ? '' : 's'} of ${source.from} ${source.unread === 1 ? 'is' : 'are'} not NAME=value (a value with line breaks?): check ${source.unread === 1 ? 'it' : 'them'} with ias env list`);
+    }
+  } catch (error) {
+    failure = error;
+  } finally {
+    const source = values['env-file'] ? sources[0] : undefined;
+    if (source && !dryRun) {
+      const removed = removePulled(source, preparedFolders(dir, env));
+      if (removed) output.log(`deleted ${removed.join(', ')}: ${removed.length === 1 ? 'it held' : 'they held'} the values of EAS${failure ? ', although the import stopped: pull it again to go on' : ''}.`);
+      else if (isInside(dir, source.file)) output.warn(`${source.file} holds values of EAS inside the project: check that git ignores it, and delete it when the app no longer reads it`);
+      else output.warn(`${source.file} holds values of EAS: delete it when you are done`);
+    }
+  }
+  if (failure) {
+    const done = report.flatMap((entry) => entry.set.map((name) => `${entry.environment} ${name}`));
+    output.warn(`env stopped: ${done.length > 0 ? `set ${done.join(', ')}` : 'nothing was set'}; run it again to go on: what is in IAS already is kept.`);
+    throw failure;
+  }
+  const pending = report.flatMap((entry) => entry.pending.map((name) => `${entry.environment} ${name}`));
+  if (pending.length > 0) output.log(`Left for you: ${pending.join(', ')} (ias env set … --from op://…).`);
+  if (!dryRun) output.log(`Next: ${iasCommand(context, 'checklist')}: what is left in expo.dev and the stores.`);
+  return { application, dry_run: dryRun, environments: report };
+}

package/src/commands/push/index.mjs

@@ -0,0 +1,334 @@
+// ias push send, messages, cancel, devices and credentials (docs/technical/manage-api.md §14): notifications of an application,
+// straight to APNs and FCM through the server. send builds the notification from its options (or a JSON file with
+// --from) and sends it now, schedules it with --at, or counts whom it would reach with --dry-run. The credentials of
+// APNs and FCM are the exception to the sealed vault, because the server sends with them: they go to the server as
+// they are, over https, and an owner approves them with a passkey; nothing here prints or keeps them.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { ApiError, IasError, UsageError } from '../../errors.mjs';
+import { applicationOf, connect, openUrl, sleep, waitForApproval } from '../../manage.mjs';
+import { filePath } from '../../secret-input.mjs';
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+
+/** The audiences of --to: «all», or a kind and what it names. */
+const TO_KINDS = { topic: 'topics', user: 'users', organization: 'organizations', space: 'spaces', group: 'groups', device: 'devices' };
+const PLATFORMS = ['ios', 'android'];
+const DURATION = /^(\d+)([smhd]?)$/;
+const SECONDS = { '': 1, s: 1, m: 60, h: 3600, d: 86400 };
+
+/** The audience of the --to options: all of one kind (topics, users…), or every device. */
+export function audienceOf(values) {
+  const targets = values.to ?? [];
+  if (targets.length === 0 || (targets.length === 1 && targets[0] === 'all')) return { type: 'all' };
+  const kinds = new Set();
+  const names = [];
+  for (const target of targets) {
+    const [kind, ...rest] = target.split(':');
+    const name = rest.join(':');
+    if (!TO_KINDS[kind] || name === '') throw new UsageError(`--to ${target} is not an audience`, { fix: `--to all, or --to <kind>:<id> with a kind of ${Object.keys(TO_KINDS).join(', ')} (repeat it for more of the same kind)` });
+    kinds.add(kind);
+    names.push(name);
+  }
+  if (kinds.size > 1) throw new UsageError(`--to mixes ${[...kinds].join(' and ')}`, { fix: 'a notification goes to one kind of audience: send one per kind' });
+  const type = TO_KINDS[[...kinds][0]];
+  return type === 'topics' ? { type, topics: names } : { type, ids: names };
+}
+
+/** The segment of --platform, --app-version, --runtime, --channel and --language, or nothing. */
+export function segmentOf(values) {
+  const segment = {};
+  for (const platform of values.platform ?? []) if (!PLATFORMS.includes(platform)) throw new UsageError(`--platform ${platform} is not a platform`, { fix: 'ios or android' });
+  if (values.platform?.length) segment.platforms = values.platform;
+  if (values['app-version']?.length) segment.app_versions = values['app-version'];
+  if (values.runtime?.length) segment.runtime_versions = values.runtime;
+  if (values.channel?.length) segment.channels = values.channel;
+  if (values.language?.length) segment.locales = values.language;
+  return Object.keys(segment).length ? segment : undefined;
+}
+
+/** Seconds of «3600», «90m», «12h» or «7d». */
+export function secondsOf(text, option) {
+  const match = DURATION.exec(String(text));
+  if (!match) throw new UsageError(`${option} ${text} is not a duration`, { fix: 'seconds, or a number with s, m, h or d (12h, 7d)' });
+  return Number(match[1]) * SECONDS[match[2]];
+}
+
+/** The data of --data name=value, as texts. */
+function dataOf(values) {
+  const data = {};
+  for (const pair of values.data ?? []) {
+    const at = pair.indexOf('=');
+    if (at < 1) throw new UsageError(`--data ${pair} is not name=value`, { fix: 'repeat --data name=value for each value the app gets with the notification' });
+    data[pair.slice(0, at)] = pair.slice(at + 1);
+  }
+  return data;
+}
+
+/** The notification: --from's JSON, with the options given on top. */
+export function messageOf(context) {
+  const { values, cwd } = context;
+  let message = {};
+  if (values.from !== undefined) {
+    const path = resolve(cwd, values.from);
+    if (!existsSync(path) || !statSync(path).isFile()) throw new IasError(`there is no file at ${values.from}`, { fix: 'give the path of a JSON file with the notification (docs/technical/manage-api.md §14.2)' });
+    try {
+      message = JSON.parse(readFileSync(path, 'utf8'));
+    } catch (error) {
+      throw new IasError(`${values.from} is not JSON: ${error.message}`, { fix: 'check its quotes and commas' });
+    }
+    if (!message || typeof message !== 'object' || Array.isArray(message)) throw new IasError(`${values.from} is not a JSON object`, { fix: 'write the notification as in docs/technical/manage-api.md §14.2' });
+  }
+  if (values.to !== undefined || values.platform || values['app-version'] || values.runtime || values.channel || values.language || !message.audience) {
+    const audience = values.to !== undefined || !message.audience ? audienceOf(values) : message.audience;
+    const segment = segmentOf(values);
+    message.audience = { ...audience, ...(segment ? { segment } : {}) };
+  }
+  for (const [option, field] of [['title', 'title'], ['body', 'body'], ['locale', 'locale'], ['collapse-id', 'collapse_id'], ['android-channel', 'android_channel'], ['priority', 'priority']]) {
+    if (values[option] !== undefined) message[field] = values[option];
+  }
+  if (values.badge !== undefined) message.badge = Number(values.badge);
+  if (values.ttl !== undefined) message.ttl = secondsOf(values.ttl, '--ttl');
+  if (values.background) message.background = true;
+  if (values.data?.length) message.data = { ...(message.data ?? {}), ...dataOf(values) };
+  if (values.at !== undefined) {
+    const at = new Date(values.at);
+    if (Number.isNaN(at.getTime())) throw new UsageError(`--at ${values.at} is not a date`, { fix: 'ISO 8601 with its offset, such as 2026-10-22T08:00:00+02:00' });
+    message.scheduled_at = at.toISOString().replace(/\.\d{3}Z$/, '+00:00');
+  }
+  if (values['dry-run']) message.dry_run = true;
+  if (!message.background && !message.title && !message.body) throw new UsageError('the notification says nothing', { fix: 'give --title or --body (or --background with --data)' });
+  return message;
+}
+
+/** The figures of a notification in one line. */
+export function describeFigures({ figures }) {
+  const extra = [figures.failed > 0 && `${figures.failed} failed`, figures.retired > 0 && `${figures.retired} retired`, figures.pending > 0 && `${figures.pending} pending`].filter(Boolean);
+  return `${figures.accepted} of ${figures.devices} accepted${extra.length ? ` (${extra.join(', ')})` : ''}`;
+}
+
+/** The audience in a few words. */
+export function describeAudience(audience) {
+  const target = audience.type === 'all' ? 'every device' : audience.type === 'topics' ? `topics ${audience.topics.join(', ')}` : `${audience.ids.length} ${audience.ids.length === 1 ? audience.type.replace(/s$/, '') : audience.type}`;
+  const segment = Object.entries(audience.segment ?? {}).map(([filter, list]) => `${filter.replace(/_/g, ' ')} ${list.join(', ')}`);
+  return [target, ...segment].join(' · ');
+}
+
+async function send(context) {
+  const { values, output } = context;
+  const message = messageOf(context);
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const application = applicationOf(context, project);
+  let data;
+  try {
+    ({ data } = await client.request('POST', `/apps/${application}/push/messages`, { json: message }));
+  } catch (error) {
+    if (error instanceof ApiError && error.code === 'audience_not_found') {
+      throw new IasError(`some of the audience is not of ${application}: ${(error.data?.missing ?? []).join(', ')}`, { fix: 'check the ids: users, spaces and groups by their public id, organizations by their code; nothing was sent', code: error.code });
+    }
+    throw error;
+  }
+  if (data.dry_run) {
+    const platforms = Object.entries(data.platforms).map(([platform, count]) => `${platform} ${count}`).join(', ');
+    const locales = Object.entries(data.locales).map(([locale, count]) => `${locale} ${count}`).join(', ');
+    output.log(`${application}: it would reach ${data.devices} device${data.devices === 1 ? '' : 's'} now${platforms ? ` (${platforms}; ${locales})` : ''}. Nothing was sent.`);
+    return data;
+  }
+  if (data.status === 'scheduled') {
+    output.log(`${application}: notification ${data.id} scheduled for ${data.scheduled_at}, to ${describeAudience(data.audience)}. ias push cancel ${data.id} stops it.`);
+    return data;
+  }
+  output.progress(`${application}: notification ${data.id} going out to ${describeAudience(data.audience)}`);
+  if (!values.wait) {
+    output.log(`ias push messages ${data.id} shows its figures in a few seconds.`);
+    return data;
+  }
+  let current = data;
+  for (let attempt = 0; current.status === 'sending' && attempt < 60; attempt += 1) {
+    await (context.sleep ?? sleep)(2);
+    current = (await client.request('GET', `/apps/${application}/push/messages/${data.id}`)).data;
+  }
+  output.log(`${data.id}: ${current.status === 'sending' ? 'still sending' : current.status}, ${describeFigures(current)}`);
+  return current;
+}
+
+async function messages(context) {
+  const { values, positionals, output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const application = applicationOf(context, project);
+  const [id] = positionals;
+  if (id) {
+    const { data } = await client.request('GET', `/apps/${application}/push/messages/${encodeURIComponent(id)}`);
+    output.log(`${data.id}  ${data.status}  ${data.background ? '(background)' : (data.title ?? data.body)}`);
+    output.log(`  to          ${describeAudience(data.audience)}`);
+    output.log(`  figures     ${describeFigures(data)}`);
+    for (const [platform, figures] of Object.entries(data.platforms)) {
+      const reasons = Object.entries(figures.reasons).map(([reason, count]) => `${reason} ${count}`).join(', ');
+      output.log(`  ${platform.padEnd(10)}  ${figures.accepted} of ${figures.devices} accepted${reasons ? `; ${reasons}` : ''}`);
+    }
+    return data;
+  }
+  const query = new URLSearchParams({ ...(values.status ? { status: values.status } : {}), ...(values.limit ? { limit: values.limit } : {}) }).toString();
+  const { data } = await client.request('GET', `/apps/${application}/push/messages${query ? `?${query}` : ''}`);
+  if (data.data.length === 0) output.log(`No notifications in ${application} yet: ias push send sends one.`);
+  for (const message of data.data) {
+    const when = message.status === 'scheduled' ? `at ${message.scheduled_at}` : (message.sent_at ?? message.created_at);
+    output.log(`${message.id}  ${message.status.padEnd(9)}  ${when}  ${message.status === 'scheduled' || message.status === 'canceled' ? '' : `${describeFigures(message)}  `}${message.background ? '(background)' : (message.title ?? message.body)}`);
+  }
+  return data;
+}
+
+async function cancel(context) {
+  const [id] = context.positionals;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const application = applicationOf(context, project);
+  const { data } = await client.request('POST', `/apps/${application}/push/messages/${encodeURIComponent(id)}/cancel`);
+  context.output.log(`${application}: notification ${data.id} canceled; it will not go out.`);
+  return data;
+}
+
+async function devices(context) {
+  const { values, output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const application = applicationOf(context, project);
+  if (values.platform !== undefined && !PLATFORMS.includes(values.platform)) throw new UsageError(`--platform ${values.platform} is not a platform`, { fix: 'ios or android' });
+  const query = new URLSearchParams(Object.fromEntries(['platform', 'user', 'topic', 'status', 'limit'].filter((name) => values[name] !== undefined).map((name) => [name, values[name]]))).toString();
+  const { data } = await client.request('GET', `/apps/${application}/push/devices${query ? `?${query}` : ''}`);
+  if (data.total === 0) output.log(`No devices in ${application}${query ? ' with these filters' : ''}: the app registers them when it starts (API.md §38).`);
+  for (const device of data.data) {
+    const who = device.user ? `user ${device.user}${device.signed_in ? '' : ' (signed out)'}` : 'no user';
+    const state = device.retired_at ? `retired: ${device.retired_reason}` : `seen ${device.last_seen_at}`;
+    output.log(`${device.id}  ${device.platform.padEnd(7)}  ${device.token_hint}  ${[device.app_version, device.channel, device.locale].filter(Boolean).join(' · ')}  ${who}  ${state}`);
+  }
+  if (data.total > data.data.length) output.log(`… and ${data.total - data.data.length} more: --limit shows up to 500.`);
+  return data;
+}
+
+async function credentials(context) {
+  const { values, positionals, output, env } = context;
+  const [platform, file] = positionals;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const application = applicationOf(context, project);
+  if (platform === undefined) {
+    const { data } = await client.request('GET', `/apps/${application}/push/credentials`);
+    if (data.data.length === 0) output.log(`${application} has no push credentials: ias push credentials ios <AuthKey_….p8> or android <service-account.json> loads them.`);
+    for (const credential of data.data) output.log(describeCredential(credential));
+    return data;
+  }
+  if (!PLATFORMS.includes(platform)) throw new UsageError(`there is no platform «${platform}»`, { fix: 'ios (the .p8 key of APNs) or android (the JSON of the FCM service account)' });
+  if (file === undefined) throw new UsageError(`which file for ${platform}?`, { fix: platform === 'ios' ? 'ias push credentials ios <AuthKey_XXXXXXXXXX.p8 or op://…>' : 'ias push credentials android <service-account.json or op://…>' });
+  if (platform === 'android' && (values['key-id'] || values['team-id'])) throw new UsageError('--key-id and --team-id are for the APNs key', { fix: 'the FCM service account carries its own' });
+  const path = filePath(file, { env, cwd: context.cwd, name: platform === 'ios' ? 'AuthKey.p8' : 'service-account.json' });
+  const contents = readFileSync(path, 'utf8');
+  const fileName = file.startsWith('op://') ? undefined : basename(path);
+  const body = { file: contents, ...(platform === 'ios' && fileName ? { file_name: fileName } : {}), ...(values['key-id'] ? { key_id: values['key-id'] } : {}), ...(values['team-id'] ? { team_id: values['team-id'] } : {}) };
+  let data;
+  try {
+    ({ data } = await client.request('PUT', `/apps/${application}/push/credentials/${platform}`, { json: body }));
+  } catch (error) {
+    if (error instanceof ApiError && error.code === 'push_credential_invalid') {
+      throw new IasError(`the file is not a usable ${platform === 'ios' ? 'APNs key' : 'FCM service account'}`, { fix: error.data?.detail ?? 'check the file', code: error.code });
+    }
+    throw error;
+  }
+  const { approval } = data;
+  const opened = (context.openUrl ?? ((url) => openUrl(url, env)))(approval.url);
+  output.progress(`${opened ? 'Opened' : 'Open'} ${approval.url}: an owner checks the key's id there and approves it with a passkey (until ${approval.expires_at}).`);
+  const stored = await waitForApproval(client, approval, { wait: context.sleep ?? sleep, output });
+  output.log(`${application}: ${describeCredential(stored)}, stored sealed with PUSH_CREDENTIALS_KEY. Keep the file in 1Password and delete it from here.`);
+  return stored;
+}
+
+/** A credential in one line, without anything secret (there is nothing secret in the answer). */
+export function describeCredential(credential) {
+  const what = credential.platform === 'ios'
+    ? `ios      APNs key ${credential.key_id}, team ${credential.team_id}, topic ${credential.topic ?? '(no iOS bundle id!)'}`
+    : `android  FCM ${credential.client_email} (project ${credential.project_id}, key ${credential.key_id.slice(0, 8)}…)`;
+  return `${what}${credential.problem ? `; refused in the last send: ${credential.problem.reason}` : ''}`;
+}
+
+const app = { app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' } };
+const idArgument = { name: 'id', description: 'The id of a notification (ias push messages lists them).' };
+
+export default {
+  name: 'push',
+  summary: 'Push notifications: send, the history, the devices and the APNs and FCM credentials',
+  description: 'Notifications go straight to APNs and FCM through the server (docs/technical/manage-api.md §14). The token needs push:send; loading a credential needs an owner and a passkey.',
+  subcommands: [
+    {
+      name: 'send',
+      summary: 'Send a notification now, schedule it with --at, or count whom it reaches with --dry-run',
+      description: 'The audience: --to all (by default), or --to topic:<name>, user:<id>, organization:<code>, space:<id>, group:<id> or device:<id>, repeated for more of the same kind; narrowed with --platform, --app-version, --runtime, --channel and --language. Translations and the rest of docs/technical/manage-api.md §14.2 go in a JSON file with --from; the options override it.',
+      options: {
+        ...app,
+        to: { type: 'string', multiple: true, value: '<kind:id>', description: 'Whom it goes to (all, topic:…, user:…, organization:…, space:…, group:…, device:…).' },
+        title: { type: 'string', value: '<text>', description: 'The title.' },
+        body: { type: 'string', value: '<text>', description: 'The text.' },
+        locale: { type: 'string', value: '<language>', description: 'The language of the title and the text (es, en, pt-BR); needed with translations.' },
+        data: { type: 'string', multiple: true, value: '<name=value>', description: 'Data the app gets with it, repeated for each value.' },
+        platform: { type: 'string', multiple: true, value: '<ios|android>', description: 'Only these platforms.' },
+        'app-version': { type: 'string', multiple: true, value: '<version>', description: 'Only these versions of the app.' },
+        runtime: { type: 'string', multiple: true, value: '<runtime>', description: 'Only these runtimes of expo-updates.' },
+        channel: { type: 'string', multiple: true, value: '<channel>', description: 'Only these channels of expo-updates.' },
+        language: { type: 'string', multiple: true, value: '<language>', description: 'Only devices in this language (es takes es-ES and es-MX).' },
+        priority: { type: 'string', value: '<high|normal>', description: 'high (by default) delivers at once; normal when it suits the device.' },
+        ttl: { type: 'string', value: '<duration>', description: 'How long APNs and FCM keep it for an unreachable device (0, 1h, 1d…; 28 days by default).' },
+        'collapse-id': { type: 'string', value: '<id>', description: 'A newer one with the same id replaces this one if not yet delivered.' },
+        badge: { type: 'string', value: '<number>', description: 'The number of the icon on iOS.' },
+        'android-channel': { type: 'string', value: '<channel>', description: 'The notification channel on Android.' },
+        background: { type: 'boolean', description: 'A silent push that only wakes the app with its --data.' },
+        at: { type: 'string', value: '<date>', description: 'Schedule it (ISO 8601, between 1 minute and 30 days ahead).' },
+        from: { type: 'string', value: '<file.json>', description: 'The notification as JSON (docs/technical/manage-api.md §14.2), with translations.' },
+        'dry-run': { type: 'boolean', description: 'Count whom it would reach now, by platform and language, and send nothing.' },
+        wait: { type: 'boolean', description: 'Wait until every device has its result, and print the figures.' },
+      },
+      run: send,
+    },
+    {
+      name: 'messages',
+      summary: 'The notifications sent and scheduled, with their figures, or one of them',
+      positionals: [{ ...idArgument, optional: true }],
+      options: {
+        ...app,
+        status: { type: 'string', value: '<status>', description: 'scheduled, sending, sent or canceled.' },
+        limit: { type: 'string', value: '<n>', description: 'How many (20 by default, up to 100).' },
+      },
+      run: messages,
+    },
+    { name: 'cancel', summary: 'Cancel a scheduled notification', positionals: [idArgument], options: app, run: cancel },
+    {
+      name: 'devices',
+      summary: 'The devices registered for notifications, with the hint of their token',
+      options: {
+        ...app,
+        platform: { type: 'string', value: '<ios|android>', description: 'Only this platform.' },
+        user: { type: 'string', value: '<id>', description: 'Only the devices of this user.' },
+        topic: { type: 'string', value: '<topic>', description: 'Only the devices subscribed to this topic.' },
+        status: { type: 'string', value: '<active|retired|all>', description: 'active (by default), retired or all.' },
+        limit: { type: 'string', value: '<n>', description: 'How many (50 by default, up to 500).' },
+      },
+      run: devices,
+    },
+    {
+      name: 'credentials',
+      summary: 'The APNs and FCM credentials, or load one (an owner approves it with a passkey)',
+      description: 'Without arguments, their metadata. With a platform and a file (a path or an op:// reference), it loads the .p8 key of APNs (ios) or the JSON of the FCM service account (android): the server checks it, an owner approves it with a passkey, and it is kept sealed with PUSH_CREDENTIALS_KEY.',
+      positionals: [
+        { name: 'platform', optional: true, description: 'ios or android.' },
+        { name: 'file', optional: true, description: 'The .p8 key or the JSON of the service account: a path or an op:// reference.' },
+      ],
+      options: {
+        ...app,
+        'key-id': { type: 'string', value: '<id>', description: 'The id of the APNs key, if the file is not called AuthKey_<id>.p8.' },
+        'team-id': { type: 'string', value: '<team>', description: 'The Apple team of the key (the application\'s by default).' },
+      },
+      run: credentials,
+    },
+  ],
+};

package/src/commands/sdk/index.mjs

@@ -0,0 +1,81 @@
+// ias sdk install: puts the SDK @imagina-build/ias in an Expo app: the package with the app's package manager, its config
+// plugin in the plugins of app.json, and what is left to do by hand (the Expo modules it uses and a new build).
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import process from 'node:process';
+import { CONFIG_FILE, DYNAMIC_CONFIGS, loadProject } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { gently, run } from '../../process.mjs';
+import { SDK_PACKAGE, addCommand, addPlugin, packageManager, sdkSource, sdkState } from '../../sdk.mjs';
+
+/** Runs the install with its output on stderr, so --json keeps stdout whole; at a low priority on macOS. */
+const systemExec = (command, commandArgs, options) => (process.platform === 'darwin' ? gently : run)(command, commandArgs, { stdio: ['inherit', 2, 'inherit'], ...options });
+
+/** The steps left after the install, from ias.json and the dependencies of the app: [{ step, why }]. */
+export function nextSteps(dir, { plugin, dependencies }) {
+  const steps = [];
+  let config;
+  try {
+    config = loadProject(dir).config;
+  } catch {
+    config = undefined;
+  }
+  if (plugin.reason === 'dynamic') steps.push({ step: `add "${SDK_PACKAGE}" to the plugins that ${plugin.file} returns, such as plugins: [...(config.plugins ?? []), '${SDK_PACKAGE}']`, why: `ias does not rewrite ${plugin.file}` });
+  if (!config) steps.push({ step: 'ias init', why: `the plugin reads ${CONFIG_FILE}, and there is none yet` });
+  if (!dependencies['expo-updates']) steps.push({ step: 'npx expo install expo-updates', why: config?.updates ? `${CONFIG_FILE} has updates: the builds need it to take the OTA updates of ias update, and ias.updates uses it` : 'if the app takes the OTA updates of ias update or uses ias.updates' });
+  const push = ['expo-notifications', 'expo-task-manager'].filter((name) => !dependencies[name]);
+  if (push.length > 0) steps.push({ step: `npx expo install ${push.join(' ')}`, why: config?.push ? `${CONFIG_FILE} has push: ias.push needs them for the notifications and the sync notices` : 'if the app uses push notifications (ias.push)' });
+  steps.push({ step: 'npx expo prebuild --clean, or a new build (ias build)', why: 'the plugin writes the native configuration when Expo makes the native projects: an update over the air does not carry it' });
+  return steps;
+}
+
+/** Installs the SDK in the app in `dir` and adds its plugin. `exec` runs the package manager (the tests pass their own). */
+export function installSdk(dir, { from, dryRun = false, repository } = {}, { output, env = process.env, exec = systemExec } = {}) {
+  if (!existsSync(join(dir, 'package.json'))) throw new IasError(`no package.json in ${dir}`, { fix: 'run it in the folder of the Expo app, or pass --project <app folder>' });
+  if (!existsSync(join(dir, 'app.json')) && !DYNAMIC_CONFIGS.some((name) => existsSync(join(dir, name)))) throw new IasError(`no app.json nor app.config.* in ${dir}: it is not an Expo app`, { fix: 'run it in the folder of the Expo app, or pass --project <app folder>' });
+  const source = sdkSource(dir, { from, env, ...(repository !== undefined ? { repository } : {}) });
+  if (source.folder && !existsSync(join(source.folder, 'dist/index.js'))) {
+    throw new IasError(`the SDK of ${source.folder} is not built`, { fix: `npm run build --prefix ${source.folder}, then run ias sdk install again; or pass --from <the .tgz of a release>` });
+  }
+  const manager = packageManager(dir);
+  const [program, programArgs] = addCommand(manager.name, source.spec);
+  const command = [program, ...programArgs].join(' ');
+  output.progress(`${output.prefix}: ${dryRun ? 'would run' : 'running'} ${command} (${manager.name} from ${manager.from}; ${SDK_PACKAGE} from ${source.origin})`);
+  if (!dryRun) exec(program, programArgs, { cwd: dir, label: command });
+
+  const plugin = addPlugin(dir, { dryRun });
+  if (plugin.reason === 'added') output.log(`${output.prefix}: ${dryRun ? 'would add' : 'added'} "${SDK_PACKAGE}" to the plugins of app.json`);
+  else if (plugin.reason === 'present') output.log(`${output.prefix}: app.json already has the plugin of ${SDK_PACKAGE}`);
+  else output.log(`${output.prefix}: ${plugin.file} is code, and ias leaves it alone: add the plugin by hand (below)`);
+
+  const steps = nextSteps(dir, { plugin, dependencies: sdkState(dir).dependencies });
+  output.log('left to do:');
+  for (const [index, { step, why }] of steps.entries()) output.log(`  ${index + 1}. ${step}\n     ${why}`);
+  output.log('ias doctor checks the SDK; docs/guide/sdk.md explains how to configure it.');
+  return { package: SDK_PACKAGE, spec: source.spec, source: source.origin, package_manager: manager.name, command, installed: !dryRun, plugin: plugin.reason, next: steps };
+}
+
+export default {
+  name: 'sdk',
+  summary: `Put the SDK ${SDK_PACKAGE} in an Expo app`,
+  subcommands: [
+    {
+      name: 'install',
+      summary: `Install ${SDK_PACKAGE} with the app's package manager and add its config plugin to app.json`,
+      description: [
+        'The package manager is the one of packageManager in package.json or of the lockfile (npm, yarn, pnpm or bun); npm without either.',
+        `${SDK_PACKAGE} comes from --from, from IAS_SDK_SOURCE, from the packages/sdk of the repository when ias runs from a clone, or from npm as ${SDK_PACKAGE}@^<version of ias>.`,
+        'With app.config.js (or .ts), ias does not touch it and says what to add. Then it lists what is left: expo-updates, expo-notifications if the app uses push, and a prebuild or a new build.',
+      ].join('\n'),
+      options: {
+        from: { type: 'string', value: '<source>', description: `Where ${SDK_PACKAGE} comes from: a .tgz of a release (a file or its URL), a folder, or a version of the registry.` },
+        'dry-run': { type: 'boolean', description: 'Say what it would run and change, and change nothing.' },
+      },
+      run: ({ values, cwd, env, output }) => {
+        // A file or folder of --from is relative to where ias runs, as the shell completes it.
+        const from = values.from && existsSync(resolve(cwd, values.from)) ? resolve(cwd, values.from) : values.from;
+        return installSdk(resolve(cwd, values.project ?? '.'), { from, dryRun: values['dry-run'] }, { output, env });
+      },
+    },
+  ],
+};