@imagina-build/ias-cli 0.0.0 → 0.1.1

package/src/commands/env/index.mjs

@@ -0,0 +1,163 @@
+// ias env list, set, pull and delete: the variables of an application, per environment (docs/technical/manage-api.md §9).
+// EXPO_PUBLIC_* end up in the bundle, so they are always plain (PLAN §2.5 point 6). Any other variable is secret unless
+// --plain says otherwise: it is sealed here as an environment_variable (docs/technical/vault.md §3.5) for the recovery key and
+// the signed runners, and its value never comes back from the server. pull writes .env.local without the secrets.
+import { Buffer } from 'node:buffer';
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { IasError, UsageError } from '../../errors.mjs';
+import { applicationOf, connect } from '../../manage.mjs';
+import { secretValue } from '../../secret-input.mjs';
+import { encodePlaintext, seal, verifyEnvelope } from '../../shared.mjs';
+import { sealingKeys, vaultItem } from '../../team-vault.mjs';
+
+export const ENVIRONMENTS = Object.freeze(['development', 'preview', 'production']);
+const NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
+const PULL_HEADER = '# Written by ias env pull';
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+const isPublic = (name) => name.startsWith('EXPO_PUBLIC_');
+
+function environmentOf(values, { required = false, fallback } = {}) {
+  const environment = values.environment ?? fallback;
+  if (environment === undefined && required) throw new UsageError('which environment?', { fix: `pass --environment ${ENVIRONMENTS.join('|')}` });
+  if (environment !== undefined && !ENVIRONMENTS.includes(environment)) throw new UsageError(`there is no environment «${environment}»`, { fix: `one of ${ENVIRONMENTS.join(', ')}` });
+  return environment;
+}
+
+async function variables(client, application, environment) {
+  return (await client.request('GET', `/apps/${application}/env${environment ? `?environment=${environment}` : ''}`)).data.data;
+}
+
+async function list(context) {
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const application = applicationOf(context, project);
+  const environment = environmentOf(context.values);
+  const found = await variables(client, application, environment);
+  if (found.length === 0) context.output.log(`No variables in ${application}${environment ? ` (${environment})` : ''}: ias env set adds them.`);
+  for (const variable of found) {
+    context.output.log(`${variable.environment.padEnd(11)}  ${variable.name}=${variable.visibility === 'plain' ? variable.value : `(secret, version ${variable.version})`}`);
+  }
+  return { application, environment: environment ?? null, variables: found };
+}
+
+async function set(context) {
+  const { values, positionals, env, output } = context;
+  const [name, given] = positionals;
+  if (!NAME.test(name)) throw new UsageError(`«${name}» is not a name for a variable`, { fix: 'capitals, digits and underscores, starting with a letter (up to 64)' });
+  const environment = environmentOf(values, { required: true });
+  const secret = isPublic(name) ? false : !values.plain;
+  if (isPublic(name) && values.secret) throw new IasError(`${name} cannot be secret`, { fix: 'EXPO_PUBLIC_ variables end up in the bundle: anyone with the app can read them, so they are always plain', code: 'variable_must_be_plain' });
+  if (given !== undefined && values.from !== undefined) throw new UsageError('the value comes twice', { fix: 'give it as an argument or with --from, not both' });
+  if (secret && given !== undefined) throw new IasError(`${name} is secret, and its value is on the command line`, { fix: 'a secret on the command line is seen by ps and kept in the shell history: use --from op://…, --from env:NAME or --from - (stdin); --plain if it is not a secret', code: 'secret_on_command_line' });
+  const value = given ?? (values.from !== undefined ? secretValue(values.from, { env, option: '--from' }) : undefined);
+  if (value === undefined) throw new UsageError(`what value for ${name}?`, { fix: secret ? 'give it with --from op://…, --from env:NAME or --from - (stdin)' : 'give it as the second argument, or with --from' });
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const application = applicationOf(context, project);
+  const path = `/apps/${application}/env/${environment}/${name}`;
+  if (!secret) {
+    if (Buffer.byteLength(value, 'utf8') > 4096) throw new IasError(`the value of ${name} has more than 4 KB`, { fix: 'a plain variable holds up to 4 KB' });
+    const { data } = await client.request('PUT', path, { json: { visibility: 'plain', value } });
+    output.log(`${application} ${environment}: ${name}=${data.value} (plain, version ${data.version})`);
+    return data;
+  }
+  // A secret keeps the id of the variable it replaces and takes the next version; a new one gets a new id.
+  const existing = (await variables(client, application, environment)).find((variable) => variable.name === name);
+  const credential = { id: existing?.id ?? randomUUID(), type: 'environment_variable', version: existing ? existing.version + 1 : 1 };
+  const sealing = await sealingKeys(client, vaultItem(context, project, client.server), env, output);
+  const plaintext = encodePlaintext('environment_variable', { application, 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 } });
+  output.log(`${application} ${environment}: ${name} (secret, version ${data.version}), sealed for ${envelope.recipients.length} key${envelope.recipients.length === 1 ? '' : 's'}`);
+  return data;
+}
+
+/** A value as dotenv reads it: bare when it is safe, in double quotes with escapes otherwise. */
+export function dotenvValue(value) {
+  return /^[A-Za-z0-9_./:@%+,=-]*$/.test(value) ? value : JSON.stringify(value);
+}
+
+async function pull(context) {
+  const { values, cwd, output } = context;
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const application = applicationOf(context, project);
+  const environment = environmentOf(values, { fallback: 'development' });
+  const file = resolve(project.dir ?? cwd, values.file ?? '.env.local');
+  if (existsSync(file) && !values.force && !readFileSync(file, 'utf8').startsWith(PULL_HEADER)) {
+    throw new IasError(`${file} exists and ias env pull did not write it`, { fix: 'move it away, or pass --force to write over it' });
+  }
+  const found = await variables(client, application, environment);
+  const plain = found.filter((variable) => variable.visibility === 'plain');
+  const secrets = found.filter((variable) => variable.visibility !== 'plain');
+  const lines = [
+    `${PULL_HEADER} --environment ${environment} (${application}, ${client.server}).`,
+    '# Only the plain variables: secrets never leave the vault; the runner opens them when it builds.',
+    ...plain.map((variable) => `${variable.name}=${dotenvValue(variable.value)}`),
+    ...secrets.map((variable) => `# ${variable.name} is secret: not written`),
+  ];
+  writeFileSync(file, `${lines.join('\n')}\n`, { mode: 0o600 });
+  output.log(`wrote ${plain.length} plain variable${plain.length === 1 ? '' : 's'} of ${environment} to ${file}${secrets.length > 0 ? `; left out ${secrets.length} secret${secrets.length === 1 ? '' : 's'}` : ''}`);
+  return { application, environment, file, written: plain.map((variable) => variable.name), secret: secrets.map((variable) => variable.name) };
+}
+
+async function remove(context) {
+  const [name] = context.positionals;
+  const environment = environmentOf(context.values, { required: true });
+  const project = projectOf(context);
+  const client = connect(context, project);
+  const application = applicationOf(context, project);
+  await client.request('DELETE', `/apps/${application}/env/${environment}/${name}`);
+  context.output.log(`${application} ${environment}: ${name} deleted`);
+  return { application, environment, name, deleted: true };
+}
+
+const app = { app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' } };
+const environmentOption = (description) => ({ environment: { type: 'string', value: '<environment>', description } });
+const nameArgument = { name: 'name', description: 'The name: capitals, digits and underscores (EXPO_PUBLIC_… are always plain).' };
+
+export default {
+  name: 'env',
+  summary: 'The variables of an application per environment: list, set, pull and delete',
+  description: 'EXPO_PUBLIC_* are always plain: they end up in the bundle. Any other variable is secret unless --plain: it is sealed on this computer and its value never comes back.',
+  subcommands: [
+    { name: 'list', summary: 'The variables, with the values of the plain ones', options: { ...app, ...environmentOption('development, preview or production (all three by default).') }, run: list },
+    {
+      name: 'set',
+      summary: 'Create or replace a variable',
+      description: 'A plain value can be the second argument. A secret one comes with --from: op://… (1Password), env:NAME (a variable of this shell) or - (stdin), never on the command line.',
+      positionals: [nameArgument, { name: 'value', optional: true, description: 'The value of a plain variable.' }],
+      options: {
+        ...app,
+        ...environmentOption('development, preview or production.'),
+        plain: { type: 'boolean', description: 'Keep it in plain (visible in the panel); EXPO_PUBLIC_* always are.' },
+        secret: { type: 'boolean', description: 'Seal it (the default for any name but EXPO_PUBLIC_*).' },
+        from: { type: 'string', value: '<op://…|env:NAME|->', description: 'Where the value is.' },
+        item: { type: 'string', value: '<op://vault/item>', description: 'The 1Password item of the vault, to seal a secret.' },
+      },
+      run: set,
+    },
+    {
+      name: 'pull',
+      summary: 'Write the plain variables of an environment to .env.local, without the secrets',
+      options: {
+        ...app,
+        ...environmentOption('development (by default), preview or production.'),
+        file: { type: 'string', value: '<file>', description: 'Where to write (.env.local of the app by default).' },
+        force: { type: 'boolean', description: 'Write over a file that ias env pull did not write.' },
+      },
+      run: pull,
+    },
+    { name: 'delete', summary: 'Delete a variable of an environment', positionals: [nameArgument], options: { ...app, ...environmentOption('development, preview or production.') }, run: remove },
+  ],
+};

package/src/commands/github/index.mjs

@@ -0,0 +1,53 @@
+// ias github link (docs/technical/manage-api.md §16.2): link the GitHub repository an application is built from. The server
+// makes the secret of the webhook GitHub will call and gives it once; the token of GitHub is loaded in the panel by an
+// owner with a passkey, never from here.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { UsageError } from '../../errors.mjs';
+import { applicationOf, connect, serverOrigin } from '../../manage.mjs';
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+
+/** owner/name from owner/name, https://github.com/owner/name(.git) or git@github.com:owner/name.git. */
+export function repositoryOf(text) {
+  const match = /^(?:https:\/\/github\.com\/|git@github\.com:)?([A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9._-]{1,100}?)(?:\.git)?\/?$/.exec(text.trim());
+  if (!match) throw new UsageError(`«${text}» is not a GitHub repository`, { fix: 'owner/name, such as imagina/jscheduler' });
+  return match[1];
+}
+
+async function link(context) {
+  const { positionals, output } = context;
+  const project = projectOf(context);
+  const code = applicationOf(context, project);
+  const repository = repositoryOf(positionals[0]);
+  const { status, data } = await connect(context, project).request('PUT', `/apps/${code}/github`, { json: { repository } });
+  const panel = `${serverOrigin(project, context.env)}/admin/applications/${code}/integrations`;
+  output.log(`${code} is linked to github.com/${data.repository}.`);
+  if (data.webhook_secret) {
+    output.log('In the repository on GitHub (Settings › Webhooks › Add webhook):');
+    output.log(`  Payload URL   ${data.webhook_url}`);
+    output.log('  Content type  application/json');
+    output.log(`  Secret        ${data.webhook_secret}`);
+    output.log('  Events        Pushes and Pull requests');
+    output.log('  This is the only time the secret is shown: keep it in 1Password.');
+  } else {
+    output.log(`  The webhook is the one GitHub already has (${data.webhook_url}); the secret is not shown again.`);
+  }
+  output.log(data.token_set ? '  The token of GitHub is loaded.' : `  Next: an owner loads the token of GitHub in the panel, with a passkey: ${panel}`);
+  return { ...data, created: status === 201 };
+}
+
+export default {
+  name: 'github',
+  summary: 'Link the GitHub repository of an application, so its tags, branches and pull requests start workflows',
+  description: 'The tags, branches and pull requests of the repository start the workflows of ias.json, GitHub gets the status of each build on its commit, and the internal builds of a pull request leave their install link in a comment. Only owners link a repository.',
+  subcommands: [
+    {
+      name: 'link',
+      summary: 'Link a repository; the first time, print the secret of the webhook GitHub will call',
+      positionals: [{ name: 'repository', description: 'owner/name, or its https://github.com URL.' }],
+      options: { app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' } },
+      run: link,
+    },
+  ],
+};

package/src/commands/init/index.mjs

@@ -0,0 +1,224 @@
+// ias init: writes the app's ias.json from what it already has: app.json, eas.json (its build and submit profiles),
+// ota.config.json and dist.config.json. Without secrets: only op:// references go in, and what cannot go is said.
+import { existsSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { CONFIG_FILE, DEFAULT_SERVER, LEGACY_FILES, MANIFEST_PATH, readExpo, readJson } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { validate } from '../../schema.mjs';
+import { isReference, writtenSecrets } from '../../secrets.mjs';
+
+const ENVIRONMENTS = ['development', 'preview', 'production'];
+const CODE = /^[a-z0-9][a-z0-9-]{0,31}$/;
+const PROFILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,49}$/;
+
+/** Why a field of eas.json does not go to ias.json. */
+const LEFT_OUT = {
+  env: 'variables go to ias env (track 1D), sealed when they are secret',
+  credentialsSource: 'credentials go to the vault (ias credentials, track 1D)',
+  ascApiKeyPath: 'credentials go to the vault (ias credentials, track 1D)',
+  ascApiKeyId: 'credentials go to the vault (ias credentials, track 1D)',
+  ascApiKeyIssuerId: 'credentials go to the vault (ias credentials, track 1D)',
+  serviceAccountKeyPath: 'credentials go to the vault (ias credentials, track 1D)',
+  appleId: 'credentials go to the vault (ias credentials, track 1D)',
+};
+const leftOutReason = (key) => LEFT_OUT[key] ?? 'ias.json has no field for it yet (phase 2 completes the build and submit profiles)';
+
+/** The code of an application made from a slug: lowercase letters, digits and hyphens, up to 32. */
+const codeFromSlug = (slug) => (typeof slug === 'string' ? slug.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 32) : undefined);
+
+/**
+ * The ias.json of the app in `dir`, from its files: { config, from, leftOut }. `from` says where each part came from;
+ * `leftOut`, what stayed out and why (a secret written in a file, a variable, a field ias.json does not have yet).
+ */
+export function initialConfig(dir, { app: appOption } = {}) {
+  const read = (name) => (existsSync(join(dir, name)) ? readJson(join(dir, name), name, `fix ${name}, or move it away and run ias init again`) : undefined);
+  const expo = readExpo(dir);
+  const ota = read(LEGACY_FILES.updates);
+  const dist = read(LEGACY_FILES.distribution);
+  const eas = read('eas.json');
+  if (!expo && !ota && !dist && !eas) {
+    const dynamic = ['app.config.js', 'app.config.ts'].find((name) => existsSync(join(dir, name)));
+    throw new IasError(dynamic ? `${dynamic} is not read: ias init reads app.json` : `no app.json, eas.json, ota.config.json or dist.config.json in ${dir}`, {
+      fix: dynamic ? 'write the configuration of the app as app.json, or write ias.json by hand (packages/cli/schema/ias.schema.json)' : 'run ias init in the folder of the Expo app, or pass --project <app folder>',
+    });
+  }
+  const from = {};
+  const leftOut = [];
+  const leave = (path, why) => leftOut.push({ path, why });
+
+  // Where the builds look for updates says the server and the OTA project.
+  const updatesUrl = expo?.updates?.url;
+  const manifest = URL.canParse(updatesUrl ?? '') ? new URL(updatesUrl) : undefined;
+  const otaProject = manifest?.pathname.match(MANIFEST_PATH)?.[1];
+  if (updatesUrl && !otaProject) leave('updates', `updates.url of app.json (${updatesUrl}) is not the manifest of an IAS OTA project`);
+
+  const distServer = URL.canParse(dist?.server ?? '') ? new URL(dist.server).origin : undefined;
+  let server = DEFAULT_SERVER;
+  from.server = 'the default, which does not answer yet: until it does, set server (or IAS_SERVER) to https://sync.domibi.com';
+  if (otaProject) {
+    server = manifest.origin;
+    from.server = 'updates.url of app.json';
+    if (distServer && distServer !== server) leave('server', `dist.config.json uploads to ${distServer}, but updates.url is on ${server}: ias.json takes ${server} for both`);
+  } else if (distServer) {
+    server = distServer;
+    from.server = 'dist.config.json';
+  }
+
+  const app = appOption ?? otaProject ?? dist?.project ?? codeFromSlug(expo?.slug);
+  from.app = appOption ? '--app' : otaProject ? 'updates.url of app.json' : dist?.project ? 'project of dist.config.json' : 'the slug of app.json (check it is the code of php artisan apps:create)';
+  if (!app) throw new IasError('there is no code for the application', { fix: 'pass --app <code>, the one of php artisan apps:create' });
+  if (!CODE.test(app)) throw new IasError(`the code of the application (${app}) is not valid`, { fix: 'pass --app <code>: lowercase letters, digits and hyphens, up to 32, as php artisan apps:create takes them' });
+
+  const config = { app, server };
+
+  const build = buildProfiles(eas?.build, leave);
+  if (build) {
+    config.build = build;
+    from.build = 'eas.json';
+  }
+
+  if (otaProject || ota) {
+    const updates = {};
+    const signing = {};
+    const keyId = expo?.updates?.codeSigningMetadata?.keyid;
+    if (keyId) signing.keyId = keyId;
+    if (ota?.privateKey !== undefined) {
+      if (isReference(ota.privateKey)) signing.privateKey = ota.privateKey;
+      else leave('updates.signing.privateKey', 'ota.config.json points at a file, and ias.json only takes op:// references: keep the key in 1Password, or set IAS_UPDATES_PRIVATE_KEY to that file when publishing');
+    }
+    if (Object.keys(signing).length > 0) updates.signing = signing;
+    if (ota?.token !== undefined) {
+      if (isReference(ota.token)) updates.token = ota.token;
+      else leave('updates.token', 'ota.config.json has the token itself, which never goes to the repository: keep it in 1Password (and rotate it with php artisan ota:token)');
+    }
+    if (ota?.envFile) updates.envFile = ota.envFile;
+    if (Array.isArray(ota?.bundleEnv) && ota.bundleEnv.length > 0) updates.bundleEnv = ota.bundleEnv;
+    if (!otaProject) leave('updates', 'app.json has no updates.url of IAS: ias update needs it, and a build that carries it');
+    config.updates = updates;
+    from.updates = [keyId && 'app.json', ota && LEGACY_FILES.updates].filter(Boolean).join(' and ') || 'app.json';
+  }
+
+  if (dist) {
+    const distribution = {};
+    if (dist.project && dist.project !== app) distribution.project = dist.project;
+    if (dist.token !== undefined) {
+      if (isReference(dist.token)) distribution.token = dist.token;
+      else leave('distribution.token', 'dist.config.json has the token itself, which never goes to the repository: keep it in 1Password (and rotate it with php artisan dist:token)');
+    }
+    config.distribution = distribution;
+    from.distribution = LEGACY_FILES.distribution;
+  }
+
+  const submit = submitProfiles(eas?.submit, leave);
+  if (submit) {
+    config.submit = submit;
+    from.submit = 'eas.json';
+  }
+  for (const key of Object.keys(eas ?? {}).filter((candidate) => !['build', 'submit'].includes(candidate))) leave(`eas.json › ${key}`, key === 'cli' ? 'it configures eas-cli (and with appVersionSource remote, EAS keeps the build numbers: phase 2 decides where IAS keeps them)' : leftOutReason(key));
+
+  const secrets = writtenSecrets(config);
+  const errors = validate(config);
+  if (secrets.length > 0 || errors.length > 0) throw new Error(`ias init made an ias.json that is not valid (${[...secrets, ...errors].join('; ')}): this is a bug of the CLI`);
+  return { config, from, leftOut };
+}
+
+/** eas.json › build as ias.json › build: the same profiles, the fields ias.json has, and the defaults of EAS made explicit. */
+function buildProfiles(profiles, leave) {
+  if (!profiles || typeof profiles !== 'object') return undefined;
+  const build = {};
+  for (const [name, profile] of Object.entries(profiles)) {
+    if (!PROFILE.test(name) || !profile || typeof profile !== 'object') {
+      leave(`build.${name}`, 'the name of a profile is letters, digits, dots, hyphens and underscores');
+      continue;
+    }
+    const out = {};
+    const inherits = typeof profile.extends === 'string';
+    if (inherits) out.extends = profile.extends;
+    if (['store', 'internal'].includes(profile.distribution)) out.distribution = profile.distribution;
+    else if (profile.distribution !== undefined) leave(`build.${name}.distribution`, `ias.json takes store or internal, not ${profile.distribution}`);
+    if (!inherits) out.distribution ??= 'store';
+    if (ENVIRONMENTS.includes(profile.environment)) out.environment = profile.environment;
+    else if (!inherits) out.environment = ENVIRONMENTS.includes(name) ? name : profile.developmentClient ? 'development' : out.distribution === 'internal' ? 'preview' : 'production';
+    if (typeof profile.channel === 'string' && PROFILE.test(profile.channel)) out.channel = profile.channel;
+    if (typeof profile.developmentClient === 'boolean') out.developmentClient = profile.developmentClient;
+    if (typeof profile.autoIncrement === 'boolean' || ['version', 'buildNumber', 'versionCode'].includes(profile.autoIncrement)) out.autoIncrement = profile.autoIncrement;
+    const ios = {};
+    if (typeof profile.ios?.simulator === 'boolean') ios.simulator = profile.ios.simulator;
+    if (Object.keys(ios).length > 0) out.ios = ios;
+    const android = {};
+    const buildType = profile.android?.buildType;
+    if (buildType === 'apk' || buildType === 'app-bundle') android.format = buildType === 'apk' ? 'apk' : 'aab';
+    else if (!inherits && !profile.android?.gradleCommand) android.format = out.distribution === 'internal' ? 'apk' : 'aab';
+    if (Object.keys(android).length > 0) out.android = android;
+    const known = ['extends', 'distribution', 'environment', 'channel', 'developmentClient', 'autoIncrement', 'ios', 'android'];
+    for (const key of Object.keys(profile).filter((candidate) => !known.includes(candidate))) leave(`build.${name}.${key}`, leftOutReason(key));
+    for (const platform of ['ios', 'android']) {
+      const taken = platform === 'ios' ? ['simulator'] : ['buildType'];
+      for (const key of Object.keys(profile[platform] ?? {}).filter((candidate) => !taken.includes(candidate))) leave(`build.${name}.${platform}.${key}`, leftOutReason(key));
+    }
+    build[name] = out;
+  }
+  return Object.keys(build).length > 0 ? build : undefined;
+}
+
+/** eas.json › submit as ias.json › submit: the identifiers of the stores, without credentials. */
+function submitProfiles(profiles, leave) {
+  if (!profiles || typeof profiles !== 'object') return undefined;
+  const fields = { ios: ['ascAppId', 'appleTeamId'], android: ['track', 'releaseStatus', 'rollout', 'changesNotSentForReview'] };
+  const submit = {};
+  for (const [name, profile] of Object.entries(profiles)) {
+    if (!PROFILE.test(name) || !profile || typeof profile !== 'object') {
+      leave(`submit.${name}`, 'the name of a profile is letters, digits, dots, hyphens and underscores');
+      continue;
+    }
+    const out = {};
+    for (const [platform, taken] of Object.entries(fields)) {
+      const source = profile[platform] ?? {};
+      const kept = Object.fromEntries(taken.filter((key) => source[key] !== undefined).map((key) => [key, key === 'ascAppId' ? String(source[key]) : source[key]]));
+      if (Object.keys(kept).length > 0) out[platform] = kept;
+      for (const key of Object.keys(source).filter((candidate) => !taken.includes(candidate))) leave(`submit.${name}.${platform}.${key}`, leftOutReason(key));
+    }
+    for (const key of Object.keys(profile).filter((candidate) => !['ios', 'android'].includes(candidate))) leave(`submit.${name}.${key}`, leftOutReason(key));
+    submit[name] = out;
+  }
+  return Object.keys(submit).length > 0 ? submit : undefined;
+}
+
+/** Writes ias.json (unless it exists, or with force) and says where each part came from and what stayed out. */
+export function init(dir, { app, force = false, dryRun = false }, output) {
+  const file = join(dir, CONFIG_FILE);
+  if (existsSync(file) && !force && !dryRun) throw new IasError(`${CONFIG_FILE} already exists in ${dir}`, { fix: 'ias doctor checks it; ias init --force writes it again, and loses what was changed by hand' });
+  const { config, from, leftOut } = initialConfig(dir, { app });
+  const text = `${JSON.stringify(config, null, 2)}\n`;
+  if (dryRun) output.progress(text.trimEnd());
+  else writeFileSync(file, text);
+  output.log(`${output.prefix}: ${dryRun ? 'would write' : 'wrote'} ${file}`);
+  for (const part of Object.keys(config)) output.log(`  ${part.padEnd(13)} ${describe(part, config[part])}, from ${from[part]}`);
+  if (leftOut.length > 0) {
+    output.log('left out:');
+    for (const { path, why } of leftOut) output.log(`  ${path}: ${why}`);
+  }
+  const legacy = Object.values(LEGACY_FILES).filter((name) => existsSync(join(dir, name)));
+  if (legacy.length > 0) output.log(`${legacy.join(' and ')} can go once nothing runs tools/ any more: ias reads ias.json first.`);
+  output.log('ias doctor checks it; ias sdk install puts the SDK @imagina-build/ias in the app, with its plugin, which writes ias.json into the builds.');
+  return { file, written: !dryRun, config, from, left_out: leftOut };
+}
+
+function describe(part, value) {
+  if (part === 'build' || part === 'submit') return Object.keys(value).join(', ');
+  if (part === 'updates') return [value.signing?.keyId && `keyid ${value.signing.keyId}`, value.signing?.privateKey && 'key in 1Password', value.token && 'token in 1Password', value.bundleEnv && `bundleEnv ${value.bundleEnv.join(', ')}`].filter(Boolean).join(', ') || 'no key or token yet';
+  if (part === 'distribution') return [value.project && `project ${value.project}`, value.token && 'token in 1Password'].filter(Boolean).join(', ') || 'no token yet';
+  return String(value);
+}
+
+export default {
+  name: 'init',
+  summary: 'Write ias.json from app.json, eas.json, ota.config.json and dist.config.json, without secrets',
+  description: 'The server comes from updates.url of app.json, or dist.config.json, or is https://ias.imagina.build. The application\'s code, from updates.url, dist.config.json or --app.',
+  options: {
+    app: { type: 'string', value: '<code>', description: 'The code of the application (php artisan apps:create), if it cannot be read from updates.url or dist.config.json.' },
+    force: { type: 'boolean', description: 'Write ias.json again if it exists.' },
+    'dry-run': { type: 'boolean', description: 'Print the ias.json it would write, and write nothing.' },
+  },
+  run: ({ values, cwd, output }) => init(resolve(cwd, values.project ?? '.'), { app: values.app, force: values.force, dryRun: values['dry-run'] }, output),
+};