@imagina-build/ias-cli 0.2.2 → 0.3.1

package/src/commands/policy/policy.mjs

@@ -0,0 +1,182 @@
+// What ias policy init, check, sign, show, status, diff and simulate share: the source file ias.policy.json (the
+// editable policy, unsigned or with the signature of an earlier attempt), its canonical hash, the team's signing key
+// (from the server, compared with 1Password when it is there), the policy the server serves, its verified form and the
+// diff between two of them. The private key never leaves 1Password: only ias policy sign reads it, in memory.
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Buffer } from 'node:buffer';
+import { IasError } from '../../errors.mjs';
+import { POLICY_LIMITS, isNotAfter, policyHash, validatePolicy, validatePolicyDraft, verifyPolicy } from '../../shared.mjs';
+import { publicKeysOf, vaultItem } from '../../team-vault.mjs';
+
+export const POLICY_FILE = 'ias.policy.json';
+
+export const DAY_MS = 24 * 60 * 60 * 1000;
+
+/** The limits the file shares with the server (docs/technical/vault.md §2.5). */
+export const MAX_VERSION = 2147483647;
+
+/** Where the source file of a command is: --out / --file, or ias.policy.json in the project. */
+export const policyPath = (context, file) => resolve(context.cwd, file ?? POLICY_FILE);
+
+/** The document without its signature: what the file holds and what the team signs. */
+export function unsignedOf(document) {
+  const value = structuredClone(document);
+  delete value.signature;
+  if (value.format === undefined) value.format = 'ias-policy-1';
+  return value;
+}
+
+/** The policy of a file, parsed: { path, document }. */
+export function readPolicyFile(path) {
+  if (!existsSync(path)) {
+    throw new IasError(`there is no ${path}`, { fix: 'ias policy init writes it with a rule equivalent to today', code: 'policy_file_missing' });
+  }
+  const text = readFileSync(path, 'utf8');
+
+  if (Buffer.byteLength(text, 'utf8') > POLICY_LIMITS.bytes) {
+    throw new IasError(`${path} is larger than ${POLICY_LIMITS.bytes} bytes`, { fix: 'a policy has at most 64 rules of 64 members: split the rules or remove members', code: 'policy.too_large' });
+  }
+
+  let document;
+  try {
+    document = JSON.parse(text);
+  } catch (error) {
+    throw new IasError(`${path} is not valid JSON (${error.message})`, { fix: `fix ${path}, or write it again with ias policy init --force`, code: 'policy_file_invalid' });
+  }
+  if (typeof document !== 'object' || document === null || Array.isArray(document)) {
+    throw new IasError(`${path} is not a policy`, { fix: 'it must be a JSON object with format, version, rules and, optionally, not_after; ias policy init --force writes one', code: 'policy_invalid' });
+  }
+  return { path, document };
+}
+
+/** The first problem of a policy file, as the code and message of validatePolicy, or null. */
+export function problemOf(document) {
+  const result = document.signature === undefined ? validatePolicyDraft(unsignedOf(document)) : validatePolicy(document);
+  return result.valid ? null : result;
+}
+
+/** A timestamp of the format from a date the person writes: 2027-04-28 or 2027-04-28T00:00:00Z. */
+export function notAfterOf(value) {
+  const text = /^\d{4}-\d{2}-\d{2}$/.test(value) ? `${value}T00:00:00Z` : value;
+  if (!isNotAfter(text)) {
+    throw new IasError(`«${value}» is not a date the policy takes`, { fix: 'use 2027-04-28, or the whole UTC timestamp 2027-04-28T00:00:00Z', code: 'policy.not_after' });
+  }
+  return text;
+}
+
+/** The default not_after: 180 days from today, at midnight UTC, as the plan recommends. */
+export function defaultNotAfter(now = new Date()) {
+  return `${new Date(now.getTime() + 180 * DAY_MS).toISOString().slice(0, 10)}T00:00:00Z`;
+}
+
+/** The days from now to a not_after, rounded up; negative when it has passed. */
+export const daysUntil = (notAfter, now = new Date()) => Math.ceil((Date.parse(notAfter) - now.getTime()) / DAY_MS);
+
+/** «any app · iOS · production · build · Google Play · track internal». */
+export function scopeOf(rule) {
+  const scope = [
+    rule.app === '*' ? 'any app' : rule.app,
+    rule.platform === '*' ? 'any platform' : rule.platform === 'ios' ? 'iOS' : 'Android',
+    rule.profile === '*' ? 'any profile' : rule.profile,
+    rule.type === '*' ? 'any job' : rule.type === 'build' ? 'build' : 'submission',
+  ];
+  if (rule.target !== '*') scope.push(rule.target === 'google_play' ? 'Google Play' : 'App Store Connect');
+  if (rule.track !== '*') scope.push(`track ${rule.track}`);
+  return scope.join(' · ');
+}
+
+/** The members of a policy, in order, without repeating. */
+export function membersOf(document) {
+  const members = [];
+  for (const rule of document.rules ?? []) for (const member of rule.require?.members ?? []) if (!members.includes(member)) members.push(member);
+  return members;
+}
+
+/** The ids of the members with a passkey in ias-approvers-1, from GET /team/approvers. */
+export function holdersOf(listed) {
+  return [...new Set((listed.data ?? []).map((entry) => entry.member).filter(Boolean))];
+}
+
+/** The names of the members with a passkey, by id. */
+export function namesOf(listed) {
+  return Object.fromEntries((listed.data ?? []).map((entry) => [entry.member, entry.name]).filter(([id]) => id));
+}
+
+/** «2 of 2 (Ana, Efraín)». */
+export function requirementOf(rule, names = {}) {
+  const people = rule.require.members.map((member) => names[member] ?? member);
+  return `${rule.require.count} of ${rule.require.members.length}${people.length > 0 ? ` (${people.join(', ')})` : ''}`;
+}
+
+/** The signing key of the team: the server's, compared with the one in 1Password when op can read it. */
+export async function signingKeyOfTeam(client, context, project) {
+  const { data: vault } = await client.request('GET', '/vault');
+  if (!vault.signing_key) {
+    throw new IasError('the vault has no keys yet', { fix: 'an owner of the team runs ias vault init', code: 'vault_not_ready' });
+  }
+  const server = { kid: vault.signing_key.kid, publicKey: vault.signing_key.public_key };
+  const item = vaultItem(context, project, client.server);
+  let local;
+  try {
+    local = publicKeysOf(item, context.env);
+  } catch (error) {
+    return { key: server, compared: false, warning: `${error.what ?? error.message}: the signature is checked with the key the server gives` };
+  }
+  if (!local) return { key: server, compared: false, warning: `there is no ${item.reference} in 1Password: the signature is checked with the key the server gives` };
+  if (local.signing.kid !== server.kid || local.signing.publicKey !== server.publicKey) {
+    throw new IasError(`the signing key of the server is not the one in ${item.reference}`, { fix: 'do not trust the policy: ias vault status shows both, and someone may be trying to slip in a key of their own', code: 'vault_keys_mismatch' });
+  }
+  return { key: local.signing, compared: true };
+}
+
+/** GET /team/policy as the server answers it. */
+export async function serverPolicy(client) {
+  return (await client.request('GET', '/team/policy')).data;
+}
+
+/** The policy the server serves, verified with the team's key: null when there is none. */
+export function verifiedPolicy(current, key) {
+  if (!current?.document) return null;
+  try {
+    return verifyPolicy(current.document, key, { checkExpiry: false });
+  } catch (error) {
+    throw new IasError(`the policy of the server does not verify with the team's key (${error.code})`, {
+      fix: 'do not rely on it: someone may have changed it on the server; a person should check Sistema › Política, and ias policy sign stores a new one only through an owner\'s passkey',
+      code: 'policy_invalid',
+    });
+  }
+}
+
+/** The rules that appear, change or go, and the members that enter or leave, between two policies. */
+export function diffPolicies(before, after) {
+  const previous = new Map((before?.rules ?? []).map((rule) => [rule.id, rule]));
+  const next = new Map((after?.rules ?? []).map((rule) => [rule.id, rule]));
+  const added = [...next.keys()].filter((id) => !previous.has(id));
+  const removed = [...previous.keys()].filter((id) => !next.has(id));
+  const changed = [...next.keys()].filter((id) => previous.has(id) && JSON.stringify(previous.get(id)) !== JSON.stringify(next.get(id)));
+  const beforeMembers = new Set(membersOf(before ?? { rules: [] }));
+  const afterMembers = new Set(membersOf(after));
+  return {
+    added: added.map((id) => next.get(id)),
+    changed: changed.map((id) => ({ before: previous.get(id), after: next.get(id) })),
+    removed: removed.map((id) => previous.get(id)),
+    members_added: [...afterMembers].filter((member) => !beforeMembers.has(member)),
+    members_removed: [...beforeMembers].filter((member) => !afterMembers.has(member)),
+  };
+}
+
+/** One line for the rules a diff found: +ids, ~ids, −ids and the members that enter or leave. */
+export function diffLine(diff) {
+  const parts = [
+    diff.added.length > 0 ? `+ ${diff.added.map((rule) => rule.id).join(', ')}` : null,
+    diff.changed.length > 0 ? `~ ${diff.changed.map((entry) => entry.after.id).join(', ')}` : null,
+    diff.removed.length > 0 ? `− ${diff.removed.map((rule) => rule.id).join(', ')}` : null,
+    diff.members_added.length > 0 ? `+${diff.members_added.length} member${diff.members_added.length === 1 ? '' : 's'}` : null,
+    diff.members_removed.length > 0 ? `−${diff.members_removed.length} member${diff.members_removed.length === 1 ? '' : 's'}` : null,
+  ];
+  return parts.filter(Boolean).join(' · ') || 'no change in the rules';
+}
+
+/** The hash the CLI shows of a policy: the SHA-256 of its canonical text. */
+export { policyHash };

package/src/commands/policy/progress.mjs

@@ -0,0 +1,20 @@
+// The approval policy of a job (docs/plans/gaps/06-politica-aprobacion.md §3.8): what ias build, ias submit,
+// ias testflight and ias rollout print when the job carries a rule, so nobody waits for an approval that is
+// already there or misses the second one. A job of a team without a policy has none and nothing is said: the
+// common path stays as it was.
+
+/** The line of a job: «policy ios-production · 1 of 2», or null without a rule. */
+export function policyLine(job) {
+  const policy = job?.policy;
+  if (!policy || typeof policy.rule !== 'string' || policy.rule === '') return null;
+  const count = Number.isInteger(policy.count) ? policy.count : 1;
+  const approved = Number.isInteger(policy.approved) ? policy.approved : 0;
+  return `policy ${policy.rule} · ${approved} of ${count}`;
+}
+
+/** Says the rule and the approvals of a job when it has one, and returns that line (or null). */
+export function sayPolicy(output, job) {
+  const line = policyLine(job);
+  if (line !== null) output.progress(`  ${line}`);
+  return line;
+}

package/src/commands/releases/index.mjs

@@ -0,0 +1,225 @@
+// ias releases: the releases of Google Play and the policy of each track (docs/plans/gaps/03-google-play-rollout.md
+// §4.3 and §4.10). `list` and `view` only read the state IAS keeps: no flags needed, no job, no passkey. `--refresh`
+// queues the read-only release_status job and waits for it. `policy` shows a track's policy, and an owner sets it with
+// flags (the same permission the panel edits): without a row, a track only takes drafts.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { applicationOf, connect, sleep } from '../../manage.mjs';
+import { EXIT_CODE } from '../../output.mjs';
+import { buildsClient, isFinished } from '../build/follow.mjs';
+import { PLAY_TRACK } from '../../shared.mjs';
+
+const TRACK = PLAY_TRACK;
+const MODES = Object.freeze(['draft', 'staged', 'full']);
+const MODE_LABELS = Object.freeze({ draft: 'drafts only', staged: 'staged', full: 'full' });
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+const clientOf = (context, project = projectOf(context)) => buildsClient(connect(context, project));
+const trackOf = (context) => {
+  const track = context.positionals[0];
+  if (!TRACK.test(track ?? '')) throw new IasError(`«${track ?? ''}» is not a track of Google Play`, { fix: 'production, beta, alpha, internal, a closed track or a form factor\'s (wear:production)' });
+  return track;
+};
+const date = (value) => (value ? value.slice(0, 16).replace('T', ' ') : 'never');
+const percentText = (release) => (release?.percent === null || release?.percent === undefined ? '' : ` · ${release.percent} %`);
+const stateLine = (release) => `${release.track} · ${release.version ?? '?'} (${release.version_code ?? '?'}) · ${release.status ?? 'unknown'}${percentText(release)}${release.lifecycle ? ` · ${String(release.lifecycle).toLowerCase().replace(/_/g, ' ')}` : ''} · read ${date(release.observed_at)}`;
+
+/** The whole number of a flag, or undefined. */
+function number(value, flag, { min, max }) {
+  if (value === undefined) return undefined;
+  if (!/^[0-9]+$/.test(String(value))) throw new IasError(`--${flag} ${value} is not a whole number`, { fix: `a whole number from ${min} to ${max}` });
+  const parsed = Number(value);
+  if (parsed < min || parsed > max) throw new IasError(`--${flag} ${parsed} is outside ${min}-${max}`, { fix: `use a whole number from ${min} to ${max}` });
+  return parsed;
+}
+
+/** The current state of a track; a 404 names the command that creates it. */
+async function stateOf(client, app, track, { allowMissing = false } = {}) {
+  try {
+    return (await client.request('GET', `/apps/${encodeURIComponent(app)}/releases/${encodeURIComponent(track)}`)).data;
+  } catch (error) {
+    if (allowMissing && (error.code === 'release_not_found' || error.status === 404)) return null;
+    throw error;
+  }
+}
+
+/** Waits for a release/release_status job, polling the state of the track; returns the state it left. */
+async function waitForJob(context, client, app, track, job) {
+  const { output } = context;
+  const wait = context.sleep ?? sleep;
+  let said = job.status;
+  for (let attempt = 0; attempt < 240; attempt += 1) {
+    await wait(5);
+    let state = null;
+    try {
+      state = await stateOf(client, app, track);
+    } catch (error) {
+      // The first read of a track IAS did not know: the answer carries the job, not a release yet.
+      const seen = error.code === 'release_not_found' ? error.data?.job : null;
+      if (seen === null || seen === undefined) throw error;
+      state = { track, job: seen };
+    }
+    const current = state?.job?.id === job.id ? state.job : null;
+    if (current && current.status !== said) {
+      said = current.status;
+      output.progress(`  ${current.status}${current.step ? ` (${current.step})` : ''}${current.runner?.name ? ` on ${current.runner.name}` : ''}`);
+    }
+    if (current && isFinished(current.status)) return { ...state, job: current };
+  }
+  throw new IasError(`the job ${job.id} of ${track} did not end in time`, { fix: `ias releases view ${track} shows the state IAS has; if nothing changed, run it again` });
+}
+
+/** Reads the releases of every track IAS knows of, one job per track. */
+async function refreshAll(context, client, app) {
+  const { data } = await client.request('GET', `/apps/${encodeURIComponent(app)}/releases`);
+  const tracks = (data.data ?? []).map((release) => release.track);
+  for (const track of tracks) {
+    const { data: job } = await client.request('POST', `/apps/${encodeURIComponent(app)}/releases/${encodeURIComponent(track)}/refresh`, { json: {} });
+    context.output.progress(`${track}: reading Play (job ${job.id})`);
+    await waitForJob(context, client, app, track, job);
+  }
+  return tracks;
+}
+
+async function list(context) {
+  const { output, values } = context;
+  const project = projectOf(context);
+  const app = applicationOf(context, project);
+  const client = clientOf(context, project);
+  if (values.refresh) await refreshAll(context, client, app);
+  const { data } = await client.request('GET', `/apps/${encodeURIComponent(app)}/releases`);
+  const releases = data.data ?? [];
+
+  output.log(`releases of ${app}:`);
+  if (releases.length === 0) output.log('  none yet: ias submit <build> sends a build to a track (a draft by default)');
+  for (const release of releases) {
+    output.log(`  ${stateLine(release)}`);
+    output.log(`    next: ${release.next}`);
+  }
+  if (releases.length > 0) output.log(`read one track again: ias releases view <track> --refresh; move one: ias rollout <track>`);
+
+  return { app, releases };
+}
+
+async function view(context) {
+  const { output, values } = context;
+  const project = projectOf(context);
+  const app = applicationOf(context, project);
+  const client = clientOf(context, project);
+  const track = trackOf(context);
+  let state = await stateOf(client, app, track, { allowMissing: true });
+
+  if (values.refresh) {
+    const { data: job } = await client.request('POST', `/apps/${encodeURIComponent(app)}/releases/${encodeURIComponent(track)}/refresh`, { json: {} });
+    output.progress(`${track}: reading Play (job ${job.id}, no passkey: it changes nothing)`);
+    state = await waitForJob(context, client, app, track, job);
+  }
+
+  if (state === null) {
+    throw new IasError(`${app} has no release in ${track} that IAS knows of`,
+      { fix: `send a store Android build first: ias submit <build> --track ${track}; ias releases list shows the tracks IAS knows` });
+  }
+
+  output.log(`release of ${app} in ${track}: ${state.status ?? 'unknown'}${percentText(state)}${state.lifecycle ? ` (${String(state.lifecycle).toLowerCase().replace(/_/g, ' ')})` : ''}`);
+  output.log(`  version     ${state.version ?? '?'} (version code ${state.version_code ?? '?'})${state.release_name ? `, ${state.release_name}` : ''}`);
+  output.log(`  read        ${date(state.observed_at)}${state.edit_id ? ` · edit ${state.edit_id}` : ''}`);
+  output.log(`  policy      ${state.policy ? `${MODE_LABELS[state.policy.mode]} · ceiling ${state.policy.max_percent} % · step ${state.policy.step_limit} % · wait ${state.policy.min_minutes} min` : 'none: only drafts. An owner creates it with ias releases policy ' + track}`);
+  if (state.job) output.log(`  last job    ${state.job.action}: ${state.job.status}${state.job.error ? ` — ${state.job.error.code}` : ''}`);
+  output.log(`  next        ${state.next}`);
+
+  return { app, track, ...state };
+}
+
+async function policy(context) {
+  const { output, values } = context;
+  const project = projectOf(context);
+  const app = applicationOf(context, project);
+  const client = clientOf(context, project);
+  const track = trackOf(context);
+  const { data } = await client.request('GET', `/apps/${encodeURIComponent(app)}/releases/policies`);
+  const current = (data.data ?? []).find((candidate) => candidate.track === track) ?? null;
+  const flags = values.mode !== undefined || values['max-percent'] !== undefined || values.step !== undefined || values['min-minutes'] !== undefined;
+
+  if (!flags) {
+    if (current === null) {
+      output.log(`${track}: no policy: IAS only sends drafts there (as always). An owner can allow a staged rollout with:`);
+      output.log(`  ias releases policy ${track} --mode staged --max-percent 50 --step 20`);
+      return { app, track, policy: null, next: `ias releases policy ${track} --mode staged --max-percent 50 --step 20` };
+    }
+    output.log(`policy of ${app} in ${track}: ${MODE_LABELS[current.mode]} · ceiling ${current.max_percent} % · step ${current.step_limit} % · wait ${current.min_minutes} min`);
+    output.log(`  next        ias rollout ${track} --percent ${Math.min(current.max_percent, current.step_limit)}`);
+    return { app, track, policy: current };
+  }
+
+  if (values.mode !== undefined && !MODES.includes(values.mode)) throw new IasError(`--mode ${values.mode} is not a release mode`, { fix: 'draft, staged or full' });
+  const update = {
+    mode: values.mode ?? current?.mode ?? 'staged',
+    max_percent: number(values['max-percent'], 'max-percent', { min: 1, max: 100 }) ?? current?.max_percent ?? 100,
+    step_limit: number(values.step, 'step', { min: 1, max: 100 }) ?? current?.step_limit ?? 20,
+    min_minutes: number(values['min-minutes'], 'min-minutes', { min: 0, max: 10080 }) ?? current?.min_minutes ?? 0,
+  };
+
+  output.log(`policy of ${app} in ${track}: ${MODE_LABELS[update.mode]} · ceiling ${update.max_percent} % · step ${update.step_limit} % · wait ${update.min_minutes} min (an owner)`);
+  if (values['dry-run']) {
+    output.progress('Nothing was saved: run it again without --dry-run.');
+    return { app, track, policy: update, dry_run: true };
+  }
+
+  const { data: saved } = await client.request('PUT', `/apps/${encodeURIComponent(app)}/releases/policies/${encodeURIComponent(track)}`, { json: update });
+  output.log(`saved: the track now allows a release up to ${saved.max_percent} %, ${saved.step_limit} points per change, ${saved.min_minutes} minutes apart.`);
+  output.log(`next        ias submit <build> --track ${track} --release-status inProgress --rollout ${Math.min(saved.max_percent, saved.step_limit)}, or ias rollout ${track} --percent ${Math.min(saved.max_percent, saved.step_limit)}`);
+  return { app, track, policy: saved };
+}
+
+export default {
+  name: 'releases',
+  summary: 'The releases of Google Play: what each track serves, its history and its policy',
+  description: [
+    'Without a subcommand, ias releases lists the tracks IAS knows of the application. list and view only read the state IAS keeps (no job, no passkey, no flags); --refresh queues the read-only release_status job, lets the runner read Play and waits for it. A track without a policy only takes drafts, as always; an owner allows staged rollouts there with ias releases policy <track> (the panel edits the same policy).',
+    'To move a release that is already in a track, use ias rollout.',
+  ].join('\n'),
+  options: {
+    app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
+    refresh: { type: 'boolean', description: 'Read Play again with the read-only job, and wait for it.' },
+  },
+  subcommands: [
+    {
+      name: 'list',
+      summary: 'The releases of every track, with their next step; --refresh reads Play again',
+      description: 'Only reads: one line per track with the version, version code, status, percentage, review lifecycle and when IAS last read it. It never creates a job unless --refresh is given.',
+      options: {
+        app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
+        refresh: { type: 'boolean', description: 'Read every known track again with the read-only job, and wait for it.' },
+      },
+      run: list,
+    },
+    {
+      name: 'view',
+      summary: 'What one track serves, its policy, its last job and the next step',
+      description: 'Only reads the state IAS keeps. With --refresh it queues the read-only release_status job (no approval), waits for the runner and shows what Play has.',
+      positionals: [{ name: 'track', description: 'The track of Google Play, as ias submit --track names it.' }],
+      options: {
+        app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
+        refresh: { type: 'boolean', description: 'Read Play again with the read-only job, and wait for it.' },
+      },
+      run: view,
+    },
+    {
+      name: 'policy',
+      summary: 'Show the release policy of a track, or set it (an owner)',
+      description: 'Without flags it shows the policy; without a row, it says that the track only takes drafts and gives the command. With flags an owner sets it: it is the permission of every rollout, so production needs one explicitly. The panel (application › Ajustes › Google Play) edits the same policy.',
+      positionals: [{ name: 'track', description: 'The track of Google Play, as ias submit --track names it.' }],
+      options: {
+        app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
+        mode: { type: 'string', value: '<draft|staged|full>', description: 'What the track allows: drafts only, a gradual rollout or completing it to everyone.' },
+        'max-percent': { type: 'string', value: '<1-100>', description: 'The ceiling of the rollout (staged and full).' },
+        step: { type: 'string', value: '<1-100>', description: 'How many points one change may raise the rollout.' },
+        'min-minutes': { type: 'string', value: '<minutes>', description: 'The minimum wait between changes, to protect Play\'s review queue.' },
+        'dry-run': { type: 'boolean', description: 'Show the policy that would be saved, without saving it.' },
+      },
+      run: policy,
+    },
+  ],
+  run: list,
+};

package/src/commands/rollout/index.mjs

@@ -0,0 +1,186 @@
+// ias rollout: moves the release of a Google Play track that is already there (docs/plans/gaps/03-google-play-rollout.md
+// §4.3 and §4.7). It sends no artifact: the binary was approved by its submit. Without an action flag it only reads the
+// state and says the next step; --percent, --halt, --resume or --complete create one job, which an owner approves with a
+// passkey. The server checks the policy of the track (ceiling, step, wait) and the state the caller expected.
+import { resolve } from 'node:path';
+import { loadProject } from '../../config.mjs';
+import { IasError } from '../../errors.mjs';
+import { applicationOf, connect, openUrl, sleep } from '../../manage.mjs';
+import { EXIT_CODE } from '../../output.mjs';
+import { buildsClient, isFinished } from '../build/follow.mjs';
+import { sayPolicy } from '../policy/progress.mjs';
+import { PLAY_TRACK } from '../../shared.mjs';
+
+const TRACK = PLAY_TRACK;
+const MODE_LABELS = Object.freeze({ draft: 'drafts only', staged: 'staged', full: 'full' });
+
+const projectOf = ({ values, cwd }) => loadProject(resolve(cwd, values.project ?? '.'));
+const clientOf = (context, project = projectOf(context)) => buildsClient(connect(context, project));
+const date = (value) => (value ? value.slice(0, 16).replace('T', ' ') : 'never');
+
+function trackOf(context) {
+  const track = context.positionals[0];
+  if (!TRACK.test(track ?? '')) throw new IasError(`«${track ?? ''}» is not a track of Google Play`, { fix: 'production, beta, alpha, internal, a closed track or a form factor\'s (wear:production)' });
+  return track;
+}
+
+/** The state of the track, from the cache; a 404 names the command that sends a release. */
+async function stateOf(client, app, track) {
+  try {
+    return (await client.request('GET', `/apps/${encodeURIComponent(app)}/releases/${encodeURIComponent(track)}`)).data;
+  } catch (error) {
+    if (error.code === 'release_not_found' || error.status === 404) {
+      throw new IasError(`${app} has no release in ${track} that IAS knows of`, {
+        fix: `send a store Android build first: ias submit <build> --track ${track}; ias releases view ${track} --refresh reads what Play has`,
+        code: 'release_not_found',
+      });
+    }
+    throw error;
+  }
+}
+
+/** The action and percentage the flags ask for. */
+function planOf(context, release) {
+  const { values } = context;
+  const actions = [values.halt === true, values.resume === true, values.complete === true].filter(Boolean).length;
+  if (actions > 1) throw new IasError('ias rollout takes one action at a time', { fix: 'one of --percent <n>, --halt, --resume or --complete' });
+
+  let percent;
+  if (values.percent !== undefined) {
+    if (!/^[0-9]+$/.test(String(values.percent))) throw new IasError(`--percent ${values.percent} is not a whole number`, { fix: 'a rollout serves a whole percentage from 1 to 99' });
+    percent = Number(values.percent);
+    if (percent < 1 || percent > 99) throw new IasError(`--percent ${percent} is outside 1-99`, { fix: 'the 100 % is --complete; to stop new users use --halt' });
+  }
+
+  if (values.halt) {
+    if (percent !== undefined) throw new IasError('--halt takes no --percent', { fix: `ias rollout ${context.positionals[0]} --halt pauses the rollout where it is` });
+    return { action: 'halt', percent: null };
+  }
+
+  if (values.complete) {
+    if (percent !== undefined) throw new IasError('--complete takes no --percent', { fix: `ias rollout ${context.positionals[0]} --complete serves it to everyone (100 %)` });
+    return { action: 'complete', percent: null };
+  }
+
+  if (values.resume) return { action: 'resume', percent: percent ?? null };
+
+  if (percent !== undefined) {
+    if (release.status === 'halted') {
+      throw new IasError(`${context.positionals[0]} is halted: ias does not raise it by stealth`, { fix: `ias rollout ${context.positionals[0]} --resume${percent === undefined ? '' : ` --percent ${percent}`} resumes it` });
+    }
+    if (release.status === 'completed') throw new IasError(`${context.positionals[0]} is completed: there is nothing to raise`, { fix: 'send the next version with ias submit --release-status inProgress --rollout <1-99>' });
+    return { action: 'raise', percent };
+  }
+
+  return null;
+}
+
+function printState(output, app, release) {
+  const percent = release.percent === null || release.percent === undefined ? '' : ` · ${release.percent} %`;
+  output.log(`${app} · ${release.track}: ${release.status ?? 'unknown'}${percent}${release.lifecycle ? ` (${String(release.lifecycle).toLowerCase().replace(/_/g, ' ')})` : ''}`);
+  output.log(`  version     ${release.version ?? '?'} (version code ${release.version_code ?? '?'})${release.release_name ? `, ${release.release_name}` : ''}`);
+  output.log(`  policy      ${release.policy ? `${MODE_LABELS[release.policy.mode]} · ceiling ${release.policy.max_percent} % · step ${release.policy.step_limit} % · wait ${release.policy.min_minutes} min` : 'none: only drafts. ias releases policy ' + release.track}`);
+  output.log(`  read        ${date(release.observed_at)}`);
+  output.log(`  next        ${release.next}`);
+}
+
+/** Waits for the job of the rollout, polling the state of the track. */
+async function waitForJob(context, client, app, track, job) {
+  const { output } = context;
+  const wait = context.sleep ?? sleep;
+  let said = job.status;
+  for (let attempt = 0; attempt < 240; attempt += 1) {
+    await wait(5);
+    const state = await stateOf(client, app, track);
+    const current = state.job?.id === job.id ? state.job : null;
+    if (current && current.status !== said) {
+      said = current.status;
+      output.progress(`  ${current.status}${current.step ? ` (${current.step})` : ''}${current.runner?.name ? ` on ${current.runner.name}` : ''}`);
+    }
+    if (current && isFinished(current.status)) return { ...state, job: current };
+  }
+  throw new IasError(`the rollout of ${track} did not end in time`, { fix: `ias releases view ${track} shows the state IAS has; if it did not change, read it with --refresh` });
+}
+
+function outcome(output, state) {
+  const job = state.job;
+  if (job.status !== 'succeeded') {
+    const error = job.error ? `${job.error.code}${job.error.step ? ` at ${job.error.step}` : ''}${job.error.message ? `: ${job.error.message}` : ''}` : '';
+    output.log(`rollout of ${state.track}: ${job.status}${error ? ` — ${error}` : ''}`);
+    return { ...state, [EXIT_CODE]: 1 };
+  }
+  const result = job.result ?? {};
+  const before = result.before ?? {};
+  const after = result.after ?? {};
+  const describe = (state) => `${state.status ?? '?'}${state.percent === null || state.percent === undefined ? '' : ` ${state.percent} %`}`;
+  output.log(`rollout of ${state.track}: ${describe(before)} → ${describe(after)}${result.editId ? ` (edit ${result.editId})` : ''}`);
+  output.log(`next        ${state.next}`);
+  return state;
+}
+
+async function rollout(context) {
+  const { output, values } = context;
+  const project = projectOf(context);
+  const app = applicationOf(context, project);
+  const client = clientOf(context, project);
+  const track = trackOf(context);
+  const release = await stateOf(client, app, track);
+  const plan = planOf(context, release);
+
+  if (plan === null) {
+    printState(output, app, release);
+    return { app, track, release, next: release.next, changed: false };
+  }
+
+  const versionCode = values['version-code'] === undefined ? undefined : Number(values['version-code']);
+  if (versionCode !== undefined && (!Number.isInteger(versionCode) || versionCode < 1)) throw new IasError(`--version-code ${values['version-code']} is not a version code`, { fix: 'the whole number Play assigned to the build: ias releases view <track> shows it' });
+
+  const body = { action: plan.action, ...(plan.percent === null ? {} : { percent: plan.percent }), ...(versionCode === undefined ? {} : { versionCode }) };
+  output.log(`${app} · ${track}: ${plan.action}${plan.percent === null ? '' : ` to ${plan.percent} %`} (version code ${versionCode ?? release.version_code ?? '?'})`);
+
+  if (values['dry-run']) {
+    output.progress('Nothing was created: an owner approves the real one with a passkey.');
+    return { app, track, release, ...body, dry_run: true, job: null };
+  }
+
+  const { data } = await client.request('POST', `/apps/${encodeURIComponent(app)}/releases/${encodeURIComponent(track)}/rollout`, { json: body });
+
+  if (data.changed === false) {
+    output.log(`nothing to do: ${track} already is what you asked for.`);
+    return data;
+  }
+
+  const job = data.job;
+  output.progress(`${track}: job ${job.id}, ${job.status} (version code ${job.version_code ?? '?'})`);
+  sayPolicy(output, job);
+  if (job.approval_url) {
+    const opened = (context.openUrl ?? ((url) => openUrl(url, context.env)))(job.approval_url);
+    output.progress(`${opened ? 'Opened' : 'Open'} ${job.approval_url}: an owner approves it with a passkey (the panel shows the hash ${job.hash}).`);
+  }
+  if (!values.wait) {
+    output.log(`ias releases view ${track} shows how it goes; the runner moves it once it is approved.`);
+    return data;
+  }
+  return outcome(output, await waitForJob(context, client, app, track, job));
+}
+
+export default {
+  name: 'rollout',
+  summary: 'Move the release of a Google Play track: raise its percentage, halt, resume or complete it',
+  description: [
+    'The release has to be in the track already (ias submit put it there, draft, inProgress or completed). Without an action flag this is read-only: it shows the state, the policy and the next step, and creates nothing. With --percent (raise), --halt, --resume [--percent] or --complete it creates one job that an owner approves with a passkey; the runner checks Play and writes the change without sending an artifact again.',
+    'The policy of the track is the permission: an owner sets it with ias releases policy <track>. A rollout never goes down (who has the release keeps it); use --halt to stop new users. Play reviews from the last submission, so the policy can also set a minimum wait.',
+  ].join('\n'),
+  positionals: [{ name: 'track', description: 'The track of Google Play, as ias submit --track names it.' }],
+  options: {
+    app: { type: 'string', value: '<code>', description: 'The application (app of ias.json by default).' },
+    percent: { type: 'string', value: '<1-99>', description: 'Raise the rollout to this whole percentage (never down).' },
+    halt: { type: 'boolean', description: 'Stop serving it to new users; who has it keeps it.' },
+    resume: { type: 'boolean', description: 'Resume a halted rollout, at its percentage or at --percent.' },
+    complete: { type: 'boolean', description: 'Serve it to everyone (100 %); needs a full policy.' },
+    'version-code': { type: 'string', value: '<n>', description: 'The release to move (the track\'s current one by default).' },
+    wait: { type: 'boolean', description: 'Wait until the runner moved it, and say the state before and after.' },
+    'dry-run': { type: 'boolean', description: 'Show what would be approved, without creating anything.' },
+  },
+  run: rollout,
+};

package/src/commands/runners/index.mjs

@@ -0,0 +1,19 @@
+// ias runners: the machines that build. code makes a one-time code to register one with ias-runner, valid for 30
+// minutes and once; the runner stays pending until a member authorizes it with ias vault grant. It needs an owner's
+// personal token.
+import { resolve } from 'node:path';
+import { createRunnerCode } from '../../provisioning.mjs';
+
+export default {
+  name: 'runners',
+  summary: 'The runners of the team: a one-time code to register one',
+  description: 'A runner registers with ias-runner register and the code this prints, and a member authorizes it with ias vault grant. The code is valid for 30 minutes and once.',
+  subcommands: [
+    {
+      name: 'code',
+      summary: 'Make a one-time code to register a runner, and print the command for its Mac',
+      options: { 'dry-run': { type: 'boolean', description: 'Say what it would make and make nothing.' } },
+      run: (context) => createRunnerCode({ dir: resolve(context.cwd, context.values.project ?? '.'), env: context.env, output: context.output, sleep: context.sleep, dryRun: context.values['dry-run'] }),
+    },
+  ],
+};