@imagina-build/ias-cli 0.2.1 → 0.3.0

package/src/commands/apps/store.mjs

@@ -0,0 +1,367 @@
+// ias apps store <code> (docs/plans/gaps/05-bundle-id-app-record.md §3.5): the identity of an application in App
+// Store Connect, and the way to close the gap that the store APIs cannot. Read-only by default: it shows the bundle
+// id, the app record IAS knows (and when a Mac checked it) and what a person has to do. --register-bundle-id creates
+// the App ID when it does not exist (idempotent), --check asks Apple for the app record and saves its Apple ID with
+// PATCH /apps/{code}, and --set-asc-app-id saves one by hand. The App Store Connect key is the team's sealed one,
+// opened in memory on this computer, as ias devices sync does: the server never sees it, and neither the key nor a
+// token is printed or written.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { applicationOf, connect } from '../../manage.mjs';
+import { vaultItem } from '../../team-vault.mjs';
+import { ascClient } from '../devices/asc.mjs';
+import { openAscKey } from '../devices/sync.mjs';
+import { confirm, teamKeys } from '../vault/team.mjs';
+
+/** The Apple ID of an app record: up to 20 digits, as the API validates it. */
+const ASC_APP_ID = /^[0-9]{1,20}$/;
+
+/** Where a person creates the app record: the public API cannot. */
+export const ASC_APPS_URL = 'https://appstoreconnect.apple.com/apps';
+
+/** The SKU IAS proposes for an application: deterministic, and it cannot change once the app exists. */
+export const skuOf = (code) => `IAS-${String(code).toUpperCase()}`;
+
+/** The line of the stored app record, for ias apps <code> (no network). */
+export function appRecordLine(app) {
+  if (!app.ios?.asc_app_id) return null;
+  const checked = app.ios.asc_app_checked_at ? ` · checked ${app.ios.asc_app_checked_at.slice(0, 10)}` : ' · not checked against Apple';
+  return `  app record    Apple ID ${app.ios.asc_app_id} · SKU ${skuOf(app.code)}${checked}`;
+}
+
+/** The team's App Store Connect API key in the vault, or credentials_missing. */
+async function teamAscKey(client) {
+  const { data } = await client.request('GET', '/team/credentials');
+  const key = data.data
+    .filter((credential) => !credential.retired_at && credential.type === 'asc_api_key' && (!credential.expires_at || Date.parse(credential.expires_at) > Date.now()))
+    .sort((a, b) => (b.updated_at ?? '').localeCompare(a.updated_at ?? ''))[0];
+
+  if (!key) {
+    throw new IasError('the vault has no App Store Connect key', {
+      fix: 'import it with ias credentials import asc_api_key --p8 <AuthKey_….p8> --key-id <id> --issuer-id <uuid>',
+      code: 'credentials_missing',
+    });
+  }
+
+  return key;
+}
+
+/**
+ * Opens the team's key in memory, makes the ASC client and runs `work` with it; the .p8 is wiped however it ends.
+ * The key and a token are never printed.
+ */
+async function withApple(context, project, client, work) {
+  const item = vaultItem(context, project, client.server);
+  const { keys, recoveryKey } = await teamKeys(client, item, context.env, { recovery: true });
+  const credential = await teamAscKey(client);
+  const key = await openAscKey(client, credential, { recoveryKey, keys });
+  try {
+    return await work(ascClient(key, { env: context.env, fetch: context.fetch ?? fetch }), { credential, key });
+  } finally {
+    key.p8?.fill?.(0);
+  }
+}
+
+/** What Apple answered, as an IAS error of its own: the role of the key, or a bundle id taken. */
+function appleErrorOf(error, bundleId) {
+  if (error.code === 'apple_api_error' && error.details?.status === 403) {
+    return new IasError('the App Store Connect key cannot touch identifiers', {
+      fix: 'a team key needs the Admin or App Manager role in App Store Connect; an Individual Key does not work here',
+      code: 'asc_key_forbidden',
+      details: error.details,
+    });
+  }
+  if (error.code === 'apple_api_error' && error.details?.status === 409) {
+    return new IasError(`Apple does not let the bundle id ${bundleId} be registered: it already exists in this team or another`, {
+      fix: 'use the existing App ID, or choose another bundle id; the API only sees the App IDs of this team',
+      code: 'bundle_id_taken',
+      details: error.details,
+    });
+  }
+  return error;
+}
+
+/** The block a person follows to create the app record, already filled with what the form asks. */
+function printGuided(app, output) {
+  output.log('  app record    missing in App Store Connect');
+  output.log(`    → a person with the Account Holder, App Manager or Admin role creates it in ${ASC_APPS_URL}`);
+  output.log(`      platform iOS · name ${app.name} · language es-ES (Spanish)`);
+  output.log(`      bundle id ${app.ios.bundle_id} · SKU ${skuOf(app.code)} · full access`);
+  output.log('      the SKU cannot change afterwards; the name has to be free in the account');
+  output.log(`    when it is there: ias apps store ${app.code} --check`);
+  output.log('    and the iOS signing material: ias credentials generate ios (certificate and App Store profile)');
+}
+
+/** The Apple state without saving anything: { bundle, record }, or null when this Mac cannot ask (no vault, no op). */
+async function inspectApple(context, project, client, app) {
+  try {
+    return await withApple(context, project, client, async (asc, material) => {
+      context.output.progress(`App Store Connect: key ${material.key.key_id}, from the vault (${material.credential.id} v${material.credential.version})`);
+      const bundle = await asc.bundleId(app.ios.bundle_id);
+      const record = bundle ? await asc.appByBundleId(app.ios.bundle_id) : null;
+      return { bundle, record };
+    });
+  } catch (error) {
+    context.output.warn(`Apple could not be asked (${error.message}); this is the state IAS keeps`);
+    return null;
+  }
+}
+
+/** The line of what Apple answered, for the read-only inventory. */
+function printAppleState(app, state, output) {
+  if (state === null) {
+    output.log('  Apple         not checked: --check asks Apple for the App ID and the app record');
+    return;
+  }
+  if (!state.bundle) {
+    output.log(`  Apple         the App ID ${app.ios.bundle_id} is not in Apple: ias apps store ${app.code} --register-bundle-id registers it`);
+    return;
+  }
+  if (!state.record) {
+    output.log(`  Apple         App ID registered (${state.bundle.id}) · no app record`);
+    return;
+  }
+  const name = state.record.attributes?.name ?? app.name;
+  const sku = state.record.attributes?.sku ?? skuOf(app.code);
+  output.log(`  Apple         App ID registered (${state.bundle.id}) · app record ${name} · Apple ID ${state.record.id} · SKU ${sku}`);
+}
+
+/** The block and the error when Apple (or IAS) has no app record for the bundle id. */
+function missingAppRecord(app, output) {
+  printGuided(app, output);
+  throw new IasError(`App Store Connect has no app record for ${app.ios.bundle_id}`, {
+    fix: `a person creates it in ${ASC_APPS_URL} (name ${app.name}, bundle id ${app.ios.bundle_id}, SKU ${skuOf(app.code)}); when it is there: ias apps store ${app.code} --check`,
+    code: 'asc_app_missing',
+    details: { bundle_id: app.ios.bundle_id, sku: skuOf(app.code) },
+  });
+}
+
+/** The state for --json: stable keys, never the key or a token. */
+function reportOf(app, { apple = null, changed = false, action = 'none' } = {}) {
+  return {
+    app: app.code,
+    name: app.name,
+    ios: app.ios ?? null,
+    sku: app.ios ? skuOf(app.code) : null,
+    apple,
+    android: app.android ? { package: app.android.package, checked: false } : null,
+    changed,
+    action,
+    next: app.ios && !app.ios.asc_app_id ? `ias apps store ${app.code} --check` : null,
+  };
+}
+
+/** Creates the App ID when Apple does not have it; { registered, bundle }. */
+async function registerBundleId(context, project, client, app) {
+  const { values, output } = context;
+
+  return withApple(context, project, client, async (asc, material) => {
+    output.progress(`App Store Connect: key ${material.key.key_id}, from the vault (${material.credential.id} v${material.credential.version})`);
+    let bundle;
+    try {
+      bundle = await asc.bundleId(app.ios.bundle_id);
+    } catch (error) {
+      throw appleErrorOf(error, app.ios.bundle_id);
+    }
+
+    if (bundle) {
+      output.log(`  Apple already has the App ID ${app.ios.bundle_id} (${bundle.id}): nothing to register.`);
+      return { registered: false, bundle };
+    }
+
+    output.log(`  It would register in Apple the App ID ${app.ios.bundle_id} as «${app.name}» (IOS).`);
+    if (values['dry-run']) {
+      output.log('  --dry-run: nothing was registered.');
+      return { registered: false, bundle: null };
+    }
+    await confirm(context, `Register the App ID ${app.ios.bundle_id} in the Apple team?`);
+    let created;
+    try {
+      created = await asc.createBundleId({ identifier: app.ios.bundle_id, name: app.name });
+    } catch (error) {
+      throw appleErrorOf(error, app.ios.bundle_id);
+    }
+    output.log(`  App ID ${created.attributes?.identifier ?? app.ios.bundle_id} registered in Apple (${created.id}).`);
+    output.log(`  The app record is missing: ${ASC_APPS_URL} (name ${app.name}, bundle id ${app.ios.bundle_id}, SKU ${skuOf(app.code)}).`);
+    output.log(`  when it is there: ias apps store ${app.code} --check`);
+    return { registered: true, bundle: created };
+  });
+}
+
+/** Asks Apple for the app record and saves its Apple ID; throws asc_app_missing when it does not exist. */
+async function checkAppRecord(context, project, client, app) {
+  const { values, output } = context;
+
+  return withApple(context, project, client, async (asc, material) => {
+    output.progress(`App Store Connect: key ${material.key.key_id}, from the vault (${material.credential.id} v${material.credential.version})`);
+    let bundle;
+    try {
+      bundle = await asc.bundleId(app.ios.bundle_id);
+    } catch (error) {
+      throw appleErrorOf(error, app.ios.bundle_id);
+    }
+    output.log(`  App ID        ${bundle ? `registered in Apple (${bundle.id})` : 'not in Apple: ias apps store --register-bundle-id registers it'}`);
+
+    let record = null;
+    if (bundle) {
+      try {
+        record = await asc.appByBundleId(app.ios.bundle_id);
+      } catch (error) {
+        throw appleErrorOf(error, app.ios.bundle_id);
+      }
+    }
+
+    if (!record) {
+      missingAppRecord(app, output);
+    }
+
+    const name = record.attributes?.name ?? app.name;
+    const sku = record.attributes?.sku ?? skuOf(app.code);
+    if (name !== app.name) output.warn(`the name in App Store Connect is «${name}», not «${app.name}»: it does not stop a submission, but they should match`);
+
+    if (values['dry-run']) {
+      output.log(`  app record    ${name} · Apple ID ${record.id} · SKU ${sku} (--dry-run: nothing is saved)`);
+      return { saved: null, record };
+    }
+
+    const { data: saved } = await client.request('PATCH', `/apps/${encodeURIComponent(app.code)}`, { json: { asc_app_id: record.id, asc_app_checked_at: new Date().toISOString() } });
+    output.log(`  app record    ${name} · Apple ID ${record.id} · SKU ${sku} · checked now`);
+    output.log(`  Saved in IAS (${saved.code}): ias submit uses the Apple ID ${record.id} without --asc-app-id.`);
+    return { saved, record };
+  });
+}
+
+async function store(context) {
+  const { values, output } = context;
+  const project = loadProject(resolve(context.cwd, values.project ?? '.'));
+  const code = context.positionals[0] ?? applicationOf(context, project);
+
+  if (values.check && values['set-asc-app-id'] !== undefined) {
+    throw new IasError('--check and --set-asc-app-id do not go together', { fix: 'use --check to ask Apple, or --set-asc-app-id <id> to paste it by hand' });
+  }
+
+  const client = connect(context, project);
+  const { data: initial } = await client.request('GET', `/apps/${encodeURIComponent(code)}`);
+  let app = initial;
+
+  // A person pasted the Apple ID: no Apple call, and it stays unchecked until --check sees it.
+  if (values['set-asc-app-id'] !== undefined) {
+    const ascAppId = String(values['set-asc-app-id']).trim();
+    if (!ASC_APP_ID.test(ascAppId)) {
+      throw new IasError(`«${ascAppId}» is not an Apple ID`, { fix: 'it is the number App Store Connect shows in App Information, such as 6822051274' });
+    }
+    if (values['dry-run']) {
+      output.log(`It would save the Apple ID ${ascAppId} of ${code}, without checking it against Apple.`);
+      return reportOf(app, { action: 'save_app_record' });
+    }
+    const { data: saved } = await client.request('PATCH', `/apps/${encodeURIComponent(code)}`, { json: { asc_app_id: ascAppId } });
+    output.log(`${saved.code}: Apple ID ${ascAppId} saved (not checked against Apple yet: ias apps store ${code} --check).`);
+    return reportOf(saved, { changed: true, action: 'save_app_record' });
+  }
+
+  // Everything else starts from the inventory, as the command does without flags.
+  output.log(`${app.code}  ${app.name}`);
+  if (app.ios?.bundle_id) {
+    output.log(`  ios           ${app.ios.bundle_id} (team ${app.ios.team_id ?? '—'})`);
+    if (app.ios.asc_app_id) {
+      const checked = app.ios.asc_app_checked_at ? `checked ${app.ios.asc_app_checked_at.slice(0, 10)}` : 'not checked against Apple';
+      output.log(`  app record    Apple ID ${app.ios.asc_app_id} · SKU ${skuOf(app.code)} · ${checked}`);
+    } else {
+      output.log('  app record    missing in App Store Connect');
+    }
+  } else {
+    output.log('  no iOS bundle id: there is nothing to check in Apple (add it in the panel › Ajustes)');
+  }
+  if (app.android) output.log(`  android       ${app.android.package} (in Play: to be confirmed)`);
+
+  // Without a bundle id there is nothing in Apple to look at, whatever else was asked.
+  if (!app.ios?.bundle_id) {
+    if (values['register-bundle-id'] || values.check) {
+      throw new IasError(`${app.code} has no iOS bundle id`, { fix: 'set it in the panel (the application › Ajustes) and run the command again', code: 'application_without_ios' });
+    }
+    return reportOf(app);
+  }
+
+  // Without flags it is read-only, but it still asks Apple when this Mac has the key; if it cannot, the stored state counts.
+  if (!values.check && !values['register-bundle-id']) {
+    const state = await inspectApple(context, project, client, app);
+    printAppleState(app, state, output);
+
+    if (state !== null) {
+      if (!state.record) missingAppRecord(app, output);
+      const appleReport = {
+        bundle_id_registered: true,
+        app_record: {
+          id: state.record.id,
+          name: state.record.attributes?.name ?? null,
+          sku: state.record.attributes?.sku ?? null,
+          primary_locale: state.record.attributes?.primaryLocale ?? null,
+        },
+      };
+      if (!app.ios.asc_app_id) {
+        output.log(`  IAS does not have it saved: ias apps store ${app.code} --check saves it.`);
+      } else if (app.ios.asc_app_id !== state.record.id) {
+        output.warn(`the saved Apple ID (${app.ios.asc_app_id}) is not the one Apple has (${state.record.id}): ias apps store ${app.code} --check fixes it`);
+      }
+      return reportOf(app, { apple: appleReport });
+    }
+  }
+
+  let registered = false;
+  if (values['register-bundle-id']) {
+    const outcome = await registerBundleId(context, project, client, app);
+    registered = outcome.registered;
+  }
+
+  let apple = null;
+  let saved = null;
+  if (values.check) {
+    const outcome = await checkAppRecord(context, project, client, app);
+    saved = outcome.saved;
+    apple = {
+      bundle_id_registered: true,
+      app_record: {
+        id: outcome.record.id,
+        name: outcome.record.attributes?.name ?? null,
+        sku: outcome.record.attributes?.sku ?? null,
+        primary_locale: outcome.record.attributes?.primaryLocale ?? null,
+      },
+    };
+    if (saved) {
+      app = saved;
+      output.log(`  ${app.code}: ias apps store ${app.code} has nothing pending in Apple any more.`);
+    }
+  }
+
+  const report = reportOf(app, {
+    apple,
+    changed: registered || saved !== null,
+    action: saved ? 'save_app_record' : registered ? 'register_bundle_id' : 'none',
+  });
+
+  if (!app.ios.asc_app_id && !values.check) {
+    missingAppRecord(app, output);
+  }
+
+  return report;
+}
+
+export default {
+  name: 'store',
+  summary: 'The identity of the app in App Store Connect: bundle id, app record and the next step',
+  description: [
+    'Without flags it only reads: it shows the bundle id, the app record IAS knows (Apple ID and when it was checked) and what is missing, with the creation form already filled in (name, bundle id, language and SKU).',
+    '--register-bundle-id registers the App ID in Apple only when it does not exist (idempotent, asks for confirmation unless --yes); --check asks Apple for the app record and saves its Apple ID with PATCH /apps/{code}; --set-asc-app-id <id> saves one by hand, without calling Apple. The App Store Connect key comes from the vault and is opened in memory on this Mac: it is never printed, and the server never sees it.',
+  ].join('\n'),
+  positionals: [{ name: 'code', optional: true, description: 'The code of the application (app of ias.json by default).', pattern: /^[a-z0-9][a-z0-9-]{0,31}$/ }],
+  options: {
+    check: { type: 'boolean', description: 'Ask Apple for the app record and, when it exists, save its Apple ID in IAS.' },
+    'register-bundle-id': { type: 'boolean', description: 'Register the App ID in Apple when it does not exist yet (idempotent; asks for confirmation).' },
+    'set-asc-app-id': { type: 'string', value: '<id>', description: 'Save this Apple ID by hand, without calling Apple.' },
+    yes: { type: 'boolean', description: 'Do not ask before registering the App ID in Apple.' },
+    item: { type: 'string', value: '<op://vault/item>', description: 'The 1Password item of the vault (IAS_VAULT_ITEM, vault.item of ias.json or op://IAS/IAS vault <host>).' },
+    'dry-run': { type: 'boolean', description: 'Register nothing in Apple and save nothing: say what it would do.' },
+  },
+  run: store,
+};

package/src/commands/auth/index.mjs

@@ -59,13 +59,13 @@ export async function authorize(client, { name, team, wait = sleep, open = () =>
   }
 }
 
-async function login(context) {
+export async function login(context) {
   const { env, output } = context;
   const server = serverOrigin(projectOf(context), env);
   const kind = storeKind(env);
   const team = context.values.team;
   if (team !== undefined && !TEAM_SLUG.test(team)) throw new IasError(`«${team}» is not the code of a team`, { fix: 'use the code the panel shows (Plataforma › Equipos, or ias teams): lowercase letters, digits and hyphens', code: 'usage' });
-  if (kind === 'none') throw new IasError('ias login keeps no token on CI', { fix: 'set IAS_TOKEN to a robot token of the application (iasr_…, created in the panel: the application › Settings › Access)', code: 'no_token_store' });
+  if (kind === 'none') throw new IasError('ias login keeps no token on CI', { fix: 'set IAS_TOKEN to a robot token of the application (iasr_…): ias tokens create makes one, or the panel (the application › Settings › Access)', code: 'no_token_store' });
   if (env.IAS_TOKEN) output.warn('IAS_TOKEN is set and wins over the token of ias login: unset it to use this one');
   const client = manageClient(server, undefined, { wait: context.sleep ?? sleep });
   const granted = await authorize(client, { name: context.values.name ?? deviceName(env), team, wait: context.sleep ?? sleep, open: context.values['no-browser'] ? () => false : (context.openUrl ?? ((url) => openUrl(url, env))), output });
@@ -127,7 +127,7 @@ export default [
   {
     name: 'login',
     summary: 'Authorize this computer with a passkey and keep its personal token',
-    description: 'Shows a code and opens the panel (Authorize the CLI), where a member of the team approves it with a passkey. The token (iasp_…, 90 days) goes to the macOS keychain, or to a file with mode 600 ($XDG_CONFIG_HOME/ias/tokens.json) elsewhere; IAS_TOKEN_STORE (keychain, file) chooses. A token is of one team: --team preselects it in the panel, where you choose among yours (ias teams lists them); logging in for another team replaces the token of this server. On CI there is no login: IAS_TOKEN holds a robot token. The server is IAS_SERVER, server of ias.json or ias.imagina.build.',
+    description: 'Shows a code and opens the panel (Authorize the CLI), where a member of the team approves it with a passkey. The token (iasp_…, 90 days) goes to the macOS keychain, or to a file with mode 600 ($XDG_CONFIG_HOME/ias/tokens.json) elsewhere; IAS_TOKEN_STORE (keychain, file, none) chooses; none is the default on CI, where IAS_TOKEN holds a robot token. A token is of one team: --team preselects it in the panel, where you choose among yours (ias teams lists them); logging in for another team replaces the token of this server. The server is IAS_SERVER, server of ias.json or ias.imagina.build.',
     options: {
       name: { type: 'string', value: '"…"', description: 'The name the panel shows for this computer (its name by default).' },
       team: { type: 'string', value: '<code>', description: 'The code of the team the token is for (the panel asks if you have several and it is not given).' },

package/src/commands/build/index.mjs

@@ -13,6 +13,7 @@ import { buildLine, buildsClient, downloadArtifacts, follow, uploadSource } from
 import { localBuilds } from './local.mjs';
 import { platformsOf, profileConfig, remoteProblem } from './profile.mjs';
 import { appConfigOf, archive, buildNumberOf, repository } from './source.mjs';
+import { sayPolicy } from '../policy/progress.mjs';
 
 const MESSAGE_LENGTH = 1000;
 
@@ -66,6 +67,7 @@ async function build(context) {
     output.progress(`${platform}: build ${made.id}, number ${made.build_number ?? 'of the runner'}; uploading the code…`);
     await uploadSource(upload, source);
     const { data: completed } = await client.request('POST', `/builds/${made.id}/source/complete`);
+    sayPolicy(output, completed);
     if (completed.status === 'awaiting_approval') {
       const opened = (context.openUrl ?? ((url) => openUrl(url, env)))(completed.approval_url);
       output.progress(`${platform}: ${opened ? 'opened' : 'open'} ${completed.approval_url}`);

package/src/commands/builds/index.mjs

@@ -49,9 +49,29 @@ async function view(context) {
   if (build.error) output.log(`  error       ${build.error.code}${build.error.step ? ` at ${build.error.step}` : ''}${build.error.message ? `: ${build.error.message}` : ''}`);
   for (const artifact of build.artifacts ?? []) output.log(`  artifact    ${artifact.kind.padEnd(8)} ${artifact.file} (${artifact.bytes} bytes)`);
   for (const submission of build.submissions ?? []) output.log(`  submission  ${submission.id} ${submission.target}${submission.track ? ` ${submission.track}` : ''}: ${submission.status}${submission.approval_url ? ` (approve at ${submission.approval_url})` : ''}${submission.error ? ` — ${submission.error.code}` : ''}`);
+  if (build.platform === 'ios' && build.distribution === 'store') {
+    const testflight = await testflightLine(client, build);
+    if (testflight) output.log(`  testflight  ${testflight}`);
+  }
   return build;
 }
 
+/**
+ * What TestFlight says of an iOS store build, if it knows anything: the processing, its groups and Beta App Review, with
+ * the command that goes on. Read-only, and a failure never hides the build (GET /builds/{id}/testflight is optional here).
+ */
+async function testflightLine(client, build) {
+  try {
+    const { data: state } = await client.request('GET', `/builds/${build.id}/testflight`);
+    const groups = (state.groups ?? []).map((group) => group.name).filter(Boolean);
+    const parts = [state.processing_state ?? 'not read yet', groups.length > 0 ? `groups ${groups.join(', ')}` : 'no groups'];
+    if (state.review?.state) parts.push(`Beta App Review ${state.review.state}`);
+    return `${parts.join('; ')} — ias testflight status ${build.id}`;
+  } catch {
+    return null;
+  }
+}
+
 async function logs(context) {
   const { values, output } = context;
   const client = clientOf(context);