@uknows/setup 0.1.0 → 0.2.0

package/lib/automate.mjs

@@ -0,0 +1,1299 @@
+/*
+ * The last steps of a setup run, done for the user in a terminal. Each one has its own question and runs only on a yes:
+ *   1. store the key on the platform (az for Container Apps and App Service, gh for GitHub secrets, kubectl for a
+ *      Kubernetes secret), for the environment that the key check named;
+ *   2. add the key to a deploy file that would drop it on the next deploy;
+ *   3. create a branch, commit the files that setup changed, push it and open a pull request.
+ * Never in a pipeline, never with --yes, --json or --dry-run, never without a terminal (automates()).
+ *
+ * The key never goes in the arguments of a program, and never in a file: every program reads it from stdin. az reads
+ * the value of an argument @- from stdin, gh secret set reads stdin, and kubectl apply reads the Secret from stdin.
+ * Every az command names the subscription where the app was found: setup never uses the default subscription.
+ * Programs run through cli(cmd, args, {cwd, env, input}) (deps.cli), so tests use fakes.
+ */
+import { spawn } from 'node:child_process'
+import { accessSync, constants, readFileSync } from 'node:fs'
+import { delimiter, join } from 'node:path'
+import { ciVariable } from './ci.mjs'
+import { RESOURCE_ATTRIBUTES, applyChanges, setEnvChange, updateCommandAt } from './cloudid.mjs'
+import { ACA_SECRET_REF, CLI, FUNCTIONS, HOSTS, SECRET } from './contract.mjs'
+import { HOOK_FILES } from './hooks/pins.mjs'
+import { unified } from './diff.mjs'
+import { Doc } from './doc.mjs'
+import { appUrl } from './endpoint.mjs'
+import { githubSlug } from './git.mjs'
+import { hasKey } from './settings.mjs'
+import { list, plural, unique } from './ui.mjs'
+
+/** The secret of a container app that holds the key, from the env entry of the docs (secretref:uknows-otlp-headers). */
+export const ACA_SECRET = ACA_SECRET_REF.slice(ACA_SECRET_REF.indexOf('secretref:') + 'secretref:'.length)
+/** The Kubernetes secret and the GitHub secret of the docs steps. */
+export const K8S_SECRET = 'uknows'
+export const GITHUB_SECRET = 'UKNOWS_KEY'
+/** The pull request: its title, the commit message, and the branch name (uknows-setup-2 and so on when taken). */
+export const PULL_REQUEST = { title: 'Add UKNOWS monitoring', branch: 'uknows-setup' }
+/** The page of the app that shows an app connect. The product serves it at exactly this path. */
+export const CONNECT_PATH = '/live/connect'
+const OUTPUT_LIMIT = 1 << 20
+/** For every program: no questions, no colors, and az never installs an extension by itself. */
+const QUIET = { AZURE_EXTENSION_USE_DYNAMIC_INSTALL: 'no', AZURE_CORE_ONLY_SHOW_ERRORS: 'true', AZURE_CORE_NO_COLOR: 'true',
+  GH_PROMPT_DISABLED: '1', GIT_TERMINAL_PROMPT: '0', NO_COLOR: '1' }
+const AZURE = {
+  aca: { type: 'Microsoft.App/containerApps', what: 'container app', effect: 'It restarts the app.' },
+  webapp: { type: 'Microsoft.Web/sites', what: 'web app', effect: 'It restarts the app.' },
+}
+const WORDS = [['production', 'prod', 'prd', 'live'], ['staging', 'stage', 'stg'], ['development', 'dev'], ['test', 'testing', 'qa', 'uat']]
+
+/** True when this run may do the last steps: a terminal that asks, and not --yes, --json, --dry-run or a pipeline. */
+export function automates(opts, ui, env = {}) {
+  return Boolean(ui.interactive && !opts.yes && !opts.json && !opts.dryRun && !ciVariable(env))
+}
+
+/**
+ * Run a program and keep its output, which never goes to the screen. input: text for stdin (else stdin is closed).
+ * Resolves {code, stdout, stderr, error}: error is 'missing' when the program is not installed.
+ */
+export function runProgram(cmd, args, { cwd, env = process.env, input = null, timeoutMs = 300000 } = {}) {
+  return new Promise((resolve) => {
+    let stdout = '', stderr = '', settled = false, timer = null, child
+    const finish = (result) => { if (!settled) { settled = true; clearTimeout(timer); resolve({ stdout, stderr, ...result }) } }
+    try {
+      child = spawn(cmd, args, { cwd, env: { ...env, ...QUIET }, stdio: [input === null ? 'ignore' : 'pipe', 'pipe', 'pipe'], windowsHide: true })
+    } catch (error) {
+      finish({ code: null, error: error.code === 'ENOENT' ? 'missing' : error.message })
+      return
+    }
+    child.stdout.on('data', (chunk) => { if (stdout.length < OUTPUT_LIMIT) stdout += chunk })
+    child.stderr.on('data', (chunk) => { if (stderr.length < OUTPUT_LIMIT) stderr += chunk })
+    child.on('error', (error) => finish({ code: null, error: error.code === 'ENOENT' ? 'missing' : error.message }))
+    child.on('close', (code) => finish({ code, error: null }))
+    if (input !== null) { child.stdin.on('error', () => {}); child.stdin.end(input) }
+    timer = setTimeout(() => { child.kill(); finish({ code: null, error: 'it took too long' }) }, timeoutMs)
+  })
+}
+
+/**
+ * The page where the user watches the app connect, for 1 service and the environment of the key check. base: the app
+ * address (appUrl). null when the run does not know the app (a test copy of UKNOWS without UKNOWS_APP_URL).
+ */
+export function connectUrl(service, environment = null, base = appUrl()) {
+  if (!base) return null
+  const env = String(environment ?? '').trim().toLowerCase().replace(/\s+/g, '-')
+  return `${base}${CONNECT_PATH}?app=${encodeURIComponent(service ?? '')}${env ? `&env=${encodeURIComponent(env)}` : ''}`
+}
+
+/**
+ * The end of the last line: the link to the page where the apps connect, or what to do without one. environment: the
+ * one of the key check. Without it (a skipped check), the link names the app only, and the page watches every
+ * environment of the workspace, so the line says so (F-012-145).
+ */
+export function watchLine(urls, environment = null) {
+  const known = urls.filter(Boolean)
+  if (!known.length) return 'Then watch your app connect in your test copy of UKNOWS. To get the link, set UKNOWS_APP_URL to the address of its app.'
+  const apps = known.length > 1 ? 'apps' : 'app'
+  return String(environment ?? '').trim() ? `Then watch your ${apps} connect: ${list(known)}` : `Then watch your ${apps} connect. The page watches every environment: ${list(known)}`
+}
+
+/**
+ * True when this computer can show a browser to the person at the terminal: macOS and Windows, except in an ssh
+ * session (the browser would open on the other computer), and Linux with a display and xdg-open.
+ */
+export function canOpenBrowser(env = process.env, platform = process.platform) {
+  if (platform !== 'linux' && (env.SSH_CONNECTION || env.SSH_TTY)) return false
+  if (platform === 'win32') return true
+  if (platform !== 'darwin' && !env.DISPLAY && !env.WAYLAND_DISPLAY) return false
+  return onPath(platform === 'darwin' ? 'open' : 'xdg-open', env)
+}
+
+/** True when an executable named cmd is in a folder of PATH. */
+function onPath(cmd, env) {
+  const path = env.PATH ?? env.Path ?? ''
+  return path.split(delimiter).filter(Boolean).some((dir) => {
+    try { accessSync(join(dir, cmd), constants.X_OK); return true } catch { return false }
+  })
+}
+
+/**
+ * Open a link in the browser. say() runs just before, so the screen says that the browser opens. Without a browser,
+ * nothing happens and nothing prints. Never fails. Returns true when it opened the link.
+ */
+export function openBrowser(url, env = process.env, say = () => {}) {
+  if (!canOpenBrowser(env)) return false
+  const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]] : ['xdg-open', [url]]
+  say()
+  try {
+    const child = spawn(cmd, args, { env, stdio: 'ignore', detached: true, windowsHide: true })
+    child.on('error', () => {})
+    child.unref()
+  } catch { /* no browser */ }
+  return true
+}
+
+// --- where the key goes -------------------------------------------------------------
+
+/** The names that mean 1 environment: Production is also prod, Staging also stg. Lower case. */
+export function envWords(environment) {
+  const name = String(environment ?? '').trim().toLowerCase()
+  if (!name) return []
+  return WORDS.find((words) => words.includes(name)) ?? [name]
+}
+const tokens = (name) => String(name).toLowerCase().split(/[^a-z0-9]+/).filter(Boolean)
+
+/**
+ * The 1 app that gets the key of this environment, from the names in the deploy files: the only one, else the ones
+ * whose name says the environment (ca-web-staging), else the ones whose name holds the service name. More or none: [].
+ */
+export function pickApp(names, environment = null, service = null) {
+  let pool = unique(names)
+  if (pool.length > 1 && environment) {
+    const words = envWords(environment)
+    const hit = pool.filter((n) => tokens(n).some((t) => words.includes(t)))
+    if (hit.length) pool = hit
+  }
+  if (pool.length > 1 && service) {
+    const hit = pool.filter((n) => n === service || tokens(n).join('-').includes(service))
+    if (hit.length) pool = hit
+  }
+  return pool
+}
+
+/**
+ * The GitHub secret for the key of this environment: the environment secret of the deploy job of that environment, or
+ * the repository secret when no deploy job has an environment: line. {env} (null: repository secret) or {why}.
+ */
+export function githubSecret(jobs = [], environment = null) {
+  const dynamic = (j) => Boolean(j.environment?.includes('$'))
+  const envs = unique(jobs.flatMap((j) => (!j.environment ? [] : dynamic(j) ? (j.environments ?? []).map((e) => e.name) : [j.environment])))
+  const unknown = jobs.some((j) => dynamic(j) && !(j.environments ?? []).length)
+  if (!jobs.length) return { why: 'Setup found no deploy job in your workflows, so it does not store a GitHub secret.' }
+  if (!envs.length && !unknown) return { env: null }
+  if (!envs.length) return { why: 'Your deploy job picks its GitHub environment when it runs, so setup cannot tell which environment gets this key.' }
+  if (!environment) return { why: 'UKNOWS did not say which environment this key is for, so setup cannot pick the GitHub environment.' }
+  const words = envWords(environment)
+  const match = envs.filter((e) => words.includes(e.toLowerCase()))
+  if (match.length === 1) return { env: match[0], partial: jobs.some((j) => !j.environment) }
+  return { why: `Your deploy jobs use the GitHub environments ${list(envs)}. ${match.length ? 'More than 1' : 'None'} of them is ${environment}, so setup cannot tell where this key goes.` }
+}
+
+/**
+ * What setup can store the key on, for each platform of the repo that has a key script: host id -> target. Only from
+ * the repo, nothing runs. plans: [{name, s}] with s.k8s, for the Kubernetes workloads. repo: owner/name on GitHub.
+ */
+export function keyTargets({ hosts = [], names, view, plans = [], repo = null }) {
+  const ids = new Set(hosts.map((h) => h.id))
+  const out = new Map()
+  if (ids.has('azure-container-apps')) out.set('azure-container-apps', { kind: 'aca', apps: names.aca.apps, groups: names.aca.groups })
+  if (ids.has('azure-app-service')) out.set('azure-app-service', { kind: 'webapp', apps: names.webapp.apps, groups: names.webapp.groups, slots: names.webapp.slots })
+  if (ids.has('kubernetes')) out.set('kubernetes', { kind: 'k8s', workloads: workloads(view, plans) })
+  if (ids.has('github-actions')) out.set('github-actions', { kind: 'github', repo, jobs: names.jobs ?? [], readsKey: readsKey(view) })
+  return out
+}
+
+/** True when a workflow of the repo reads the UKNOWS_KEY secret already. */
+function readsKey(view) {
+  let files = []
+  try { files = view.files() } catch { files = [] }
+  return files.filter((f) => /^(?:\.\.\/)*\.github\/workflows\/[^/]+\.ya?ml$/.test(f)).some((f) => {
+    try { return new RegExp(`\\bsecrets\\.${GITHUB_SECRET}\\b`).test(view.read(f) ?? '') } catch { return false }
+  })
+}
+
+/** The workloads (kind, name, namespace) of the Kubernetes containers of the services of this run. */
+function workloads(view, plans) {
+  const out = []
+  for (const p of plans) {
+    for (const k of p.s?.k8s ?? []) {
+      let text = null
+      try { text = view.read(k.file) } catch { text = null }
+      const w = text === null ? null : workloadOf(text, k.doc)
+      if (w?.kind && w.name && !out.some((x) => x.kind === w.kind && x.name === w.name && x.namespace === w.namespace)) out.push({ ...w, file: k.file })
+    }
+  }
+  return out
+}
+
+/** kind, metadata.name and metadata.namespace of document doc (0-based, split on --- lines) of a YAML file. */
+export function workloadOf(text, doc = 0) {
+  const lines = docLines(new Doc(text), doc).map((i) => text.split(/\r?\n/)[i])
+  const kind = lines.map((l) => /^kind:\s*['"]?([A-Za-z]+)['"]?\s*(?:#.*)?$/.exec(l)?.[1]).find(Boolean) ?? null
+  const at = lines.findIndex((l) => /^metadata:\s*(?:#.*)?$/.test(l))
+  let name = null, namespace = null
+  if (at >= 0) {
+    const rows = []
+    for (let i = at + 1; i < lines.length && (!lines[i].trim() || /^\s/.test(lines[i])); i++) if (lines[i].trim() && !/^\s*#/.test(lines[i])) rows.push(lines[i])
+    const pad = rows.length ? /^\s*/.exec(rows[0])[0].length : 0
+    const value = (key) => {
+      const row = rows.find((r) => /^\s*/.exec(r)[0].length === pad && new RegExp(`^\\s*${key}:`).test(r))
+      const v = row?.replace(new RegExp(`^\\s*${key}:\\s*`), '').replace(/\s+#.*$/, '').trim().replace(/^(['"])(.*)\1$/, '$2')
+      return v && /^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$/.test(v) ? v : null
+    }
+    name = value('name')
+    namespace = value('namespace')
+  }
+  return { kind, name, namespace }
+}
+
+/** The line indexes of document doc of a YAML file, split on --- lines. */
+function docLines(d, doc) {
+  const out = []
+  let n = 0
+  for (let i = 0; i < d.length; i++) {
+    if (/^---/.test(d.get(i))) { n++; continue }
+    if (n === doc) out.push(i)
+  }
+  return out
+}
+
+// --- storing the key ----------------------------------------------------------------
+
+const why = (text) => ({ stored: false, why: text })
+const parse = (text) => { try { return JSON.parse(text) } catch { return null } }
+/** The first line of an error, without the key (also in base64, as a Kubernetes secret holds it) and without the ERROR: prefix of az. */
+const firstLine = (text, key) => {
+  const line = String(text ?? '').split(/\r?\n/).map((l) => l.trim()).find(Boolean) ?? 'no reason given'
+  const forms = key ? [Buffer.from(`${SECRET.header}=${key}`).toString('base64'), key] : []
+  return forms.reduce((out, form) => out.split(form).join(SECRET.placeholder), line).replace(/^ERROR:\s*/, '').slice(0, 300)
+}
+const keyWord = (environment) => (environment ? `this ${environment} key` : 'this key')
+const failed = (r, key) => (r.error ? r.error : firstLine(r.stderr || r.stdout, key))
+/** An error that the same command gives again: a usage error. Then setup never says to try again. */
+const REPEATS = /\busage error\b|\bis required\b|unrecognized arguments/i
+/** A store that failed: why, and whether npx @uknows/setup key can work on a second try. */
+const failure = (prefix, r, key) => { const text = failed(r, key); return { stored: false, failed: true, why: `${prefix}: ${text}`, again: !REPEATS.test(text) } }
+
+/**
+ * Azure Container Apps and App Service, read only: find the 1 app that gets this key, in the subscriptions that the user
+ * can see. {found} or {stored: false, why}. say(line): where the line about the lookup goes.
+ */
+async function findAzure(cli, t, ctx, say = () => {}) {
+  const A = AZURE[t.kind]
+  if (t.kind === 'webapp' && t.slots?.length) return why('Your deploy uses a deployment slot, so set the key on each slot with the steps below.')
+  if (!t.apps.length) return why(`Your deploy files do not name the ${A.what}, so setup cannot tell where the key goes.`)
+  // The deploy files do not say which app runs which service, so 1 store could reach only 1 of them.
+  if ((ctx.services?.length ?? 0) > 1) return why(`You set up ${ctx.services.length} services, so setup cannot tell which ${A.what} runs each one. Set the key on each app with the steps below.`)
+  const apps = pickApp(t.apps.map((a) => a.name), ctx.environment, ctx.service)
+  if (apps.length !== 1) return why(`Your deploy files name ${t.apps.length} ${A.what}s, ${list(t.apps.map((a) => a.name))}, so setup cannot tell which one gets this key.`)
+  if (process.platform === 'win32') return why('On Windows, setup does not run az. Use the steps below in WSL or Azure Cloud Shell.')
+  const app = apps[0]
+  const groups = unique(t.groups.map((g) => g.name.toLowerCase()))
+  const group = groups.length === 1 ? groups[0] : null
+  const az = azure(cli, ctx)
+  const accounts = await az(['account', 'list', '--query', "[?state=='Enabled'].{id:id, name:name}", '-o', 'json'])
+  if (accounts.error === 'missing') return why('az is not installed, so setup cannot store the key. Install the Azure CLI and sign in with az login. Then run npx @uknows/setup key, or use the steps below.')
+  const subs = (accounts.code === 0 ? parse(accounts.stdout) : null)?.filter?.((s) => typeof s?.id === 'string' && s.id) ?? []
+  if (!subs.length) return why('az is not signed in, so setup cannot store the key. Sign in with az login. Then run npx @uknows/setup key, or use the steps below.')
+  say(`Looking for ${app} in the ${plural(subs.length, 'Azure subscription')} that you can see.`)
+  // Read only, 4 subscriptions at a time, in the order az lists them.
+  const answers = await inTurn(subs, 4, (sub) => az(['resource', 'list', '--subscription', sub.id, '--name', app, '--resource-type', A.type,
+    '--query', '[].{id:id, name:name, resourceGroup:resourceGroup}', '-o', 'json'], { timeoutMs: 60000 }))
+  const found = []
+  subs.forEach((sub, i) => {
+    const rows = answers[i].code === 0 ? parse(answers[i].stdout) : null
+    for (const row of Array.isArray(rows) ? rows : []) {
+      if (typeof row?.name !== 'string' || row.name.toLowerCase() !== app.toLowerCase() || typeof row.resourceGroup !== 'string') continue
+      if (group && row.resourceGroup.toLowerCase() !== group) continue
+      found.push({ sub, group: row.resourceGroup, name: row.name })
+    }
+  })
+  const named = group ? ` in the resource group ${t.groups[0].name}` : ''
+  if (!found.length) return why(`Setup did not find the ${A.what} ${app}${named} in your Azure subscriptions, so it does not store the key.`)
+  if (found.length > 1) {
+    return why(`Setup found ${app} in ${found.length} places, ${list(found.map((f) => `${f.group} in ${f.sub.name ?? f.sub.id}`))}, so it cannot tell which one gets this key.`)
+  }
+  const { sub, group: rg, name } = found[0]
+  const at = ['--subscription', sub.id, '-g', rg, '-n', name]
+  if (t.kind === 'aca') {
+    // az containerapp update sets the env entry on the only container. With more, it needs --container-name.
+    const containers = listed(await az(['containerapp', 'show', ...at, '--query', 'properties.template.containers[].name', '-o', 'json']))?.filter((c) => typeof c === 'string')
+    if (containers?.length > 1) {
+      return why(`${name} has ${containers.length} containers, ${list(containers)}, so setup cannot tell which one runs your app. Use the steps below, and add --container-name to the update command.`)
+    }
+  }
+  const mark = t.kind === 'aca' ? ACA_SECRET : ctx.secretName
+  const have = await azureNames(az, t.kind, at)
+  return { found: { kind: t.kind, name, rg, sub, at, mark, replaces: Boolean(have?.includes(mark)) } }
+}
+
+const azure = (cli, ctx) => (args, more = {}) => cli('az', [...args, '--only-show-errors'], { cwd: ctx.root, env: ctx.env, ...more })
+const listed = (r, field = null) => { const v = r.code === 0 ? parse(r.stdout) : null; return Array.isArray(v) ? v.map((x) => (field ? x?.[field] : x)) : null }
+/** The names of the secrets of a container app, or of the settings of a web app. Never their values. */
+const azureNames = async (az, kind, at) => listed(await (kind === 'aca' ? az(['containerapp', 'secret', 'list', ...at, '--query', '[].name', '-o', 'json'])
+  : az(['webapp', 'config', 'appsettings', 'list', ...at, '--query', '[].name', '-o', 'json'])))
+
+/** Set the key on the app that findAzure found, then check that it is there. */
+async function putAzure(cli, f, ctx) {
+  const az = azure(cli, ctx)
+  let r
+  if (f.kind === 'aca') {
+    // az reads the value of an argument @- from stdin, so the key is in no argument and in no file.
+    r = await az(['containerapp', 'secret', 'set', ...f.at, '-o', 'none', '--secrets', '@-'], { input: `${ACA_SECRET}=${SECRET.header}=${ctx.key}` })
+    if (r.code === 0) r = await az(['containerapp', 'update', ...f.at, '-o', 'none', '--set-env-vars', `${ctx.secretName}=secretref:${ACA_SECRET}`])
+  } else {
+    r = await az(['webapp', 'config', 'appsettings', 'set', ...f.at, '-o', 'none', '--settings', '@-'],
+      { input: JSON.stringify([{ name: ctx.secretName, value: `${SECRET.header}=${ctx.key}`, slotSetting: false }]) })
+  }
+  if (r.code !== 0) return failure(`Could not store the key on ${f.name}`, r, ctx.key)
+  if (!(await azureNames(az, f.kind, f.at))?.includes(f.mark)) {
+    return { stored: false, failed: true, why: `Setup set the key, but cannot find ${f.kind === 'aca' ? `the secret ${ACA_SECRET}` : `the setting ${f.mark}`} on ${f.name}. Check the app in the Azure portal.` }
+  }
+  return { stored: true, where: f.name, done: `Stored ${keyWord(ctx.environment).replace(/^this /, 'the ')} on ${f.name} in ${f.rg}.` }
+}
+
+const azureQuestion = (f, ctx) => `Store ${keyWord(ctx.environment)} on ${f.name} in ${f.rg} (subscription ${f.sub.name ?? f.sub.id}, ${f.sub.id.slice(0, 8)}...)? ${AZURE[f.kind].effect}${f.replaces ? ' It replaces the key that the app has now.' : ''} (y/N)`
+
+/** Azure Container Apps and App Service: find the app, ask, then set the key on it. */
+async function storeAzure(ui, cli, t, ctx) {
+  const f = await findAzure(cli, t, ctx, ui.print)
+  if (!f.found) return f
+  if (!(await ui.confirm(azureQuestion(f.found, ctx), false))) return { stored: false, declined: true }
+  ui.print(`Storing the key on ${f.found.name}. This can take a minute.`)
+  return putAzure(cli, f.found, ctx)
+}
+
+/** GitHub Actions, read only: the environment secret of the deploy job of this environment, or the repository secret. */
+async function findGithub(cli, t, ctx) {
+  if (!t.repo) return why('The origin remote of this repo is not on github.com, so setup cannot store the key as a GitHub secret.')
+  const target = githubSecret(t.jobs, ctx.environment)
+  if (target.why) return why(target.why)
+  const gh = github(cli, ctx)
+  const auth = await gh(['auth', 'status', '--hostname', 'github.com'])
+  if (auth.error === 'missing') return why('gh is not installed, so setup cannot store the key as a GitHub secret. Install the GitHub CLI and sign in with gh auth login. Then run npx @uknows/setup key, or use the steps below.')
+  if (auth.code !== 0) return why('gh is not signed in, so setup cannot store the key. Sign in with gh auth login. Then run npx @uknows/setup key, or use the steps below.')
+  const where = target.env ? ['--env', target.env] : []
+  if (target.env) {
+    const env = await gh(['api', `repos/${t.repo}/environments/${encodeURIComponent(target.env)}`, '--silent'])
+    if (env.code !== 0) {
+      return why(/\b404\b|not found/i.test(`${env.stderr}${env.stdout}`)
+        ? `The GitHub environment ${target.env} does not exist yet in ${t.repo}. Create it in the settings of the repo, under Environments. Then run npx @uknows/setup key, or use the steps below.`
+        : `Setup could not read the environments of ${t.repo}: ${failed(env)}`)
+    }
+  }
+  const have = await githubNames(gh, t.repo, where)
+  return { found: { kind: 'github', repo: t.repo, env: target.env, where, partial: target.partial, replaces: Boolean(have?.includes(GITHUB_SECRET)) } }
+}
+
+const github = (cli, ctx) => (args, more = {}) => cli('gh', args, { cwd: ctx.root, env: ctx.env, timeoutMs: 60000, ...more })
+/** The names of the secrets, never their values: --json name, or the first column on a gh without --json. */
+async function githubNames(gh, repo, where) {
+  const json = await gh(['secret', 'list', '--repo', repo, ...where, '--json', 'name'])
+  const v = json.code === 0 ? parse(json.stdout) : null
+  if (Array.isArray(v)) return v.map((x) => x?.name)
+  const plain = await gh(['secret', 'list', '--repo', repo, ...where])
+  return plain.code === 0 ? plain.stdout.split(/\r?\n/).map((l) => l.split(/\s+/)[0]).filter(Boolean) : null
+}
+
+/** Set the GitHub secret that findGithub found, then check that it is there. */
+async function putGithub(cli, f, ctx) {
+  const gh = github(cli, ctx)
+  // gh reads the value from stdin. The secret holds the key only, as the docs steps say.
+  const r = await gh(['secret', 'set', GITHUB_SECRET, '--repo', f.repo, ...f.where], { input: ctx.key })
+  if (r.code !== 0) return failure('Could not store the GitHub secret', r, ctx.key)
+  if (!(await githubNames(gh, f.repo, f.where))?.includes(GITHUB_SECRET)) {
+    return { stored: false, failed: true, why: `Setup set the secret, but cannot find ${GITHUB_SECRET} in ${f.repo}. Check the secrets in the settings of the repo.` }
+  }
+  return { stored: true, partial: f.partial, done: f.env ? `Stored the GitHub secret ${GITHUB_SECRET} of the environment ${f.env}.` : `Stored the repository secret ${GITHUB_SECRET}.` }
+}
+
+const githubQuestion = (f, ctx) => {
+  const replaces = f.replaces ? ' It replaces the secret that is there now.' : ''
+  return f.env
+    ? `Store ${keyWord(ctx.environment)} as the secret ${GITHUB_SECRET} of the GitHub environment ${f.env} in ${f.repo}? The deploy jobs of that environment can read it.${replaces} (y/N)`
+    : `Store ${keyWord(ctx.environment)} as the repository secret ${GITHUB_SECRET} of ${f.repo}? Every workflow of the repo can read it.${replaces} (y/N)`
+}
+
+/** GitHub Actions: find where the secret goes, ask, then set it. */
+async function storeGithub(ui, cli, t, ctx) {
+  const f = await findGithub(cli, t, ctx)
+  if (!f.found) return f
+  if (!(await ui.confirm(githubQuestion(f.found, ctx), false))) return { stored: false, declined: true }
+  return putGithub(cli, f.found, ctx)
+}
+
+/** Kubernetes, read only: the 1 kubectl context that has the workload, and the namespace of the secret uknows. */
+async function findK8s(cli, t, ctx, say = () => {}) {
+  if (!t.workloads.length) return why('Setup did not find the Kubernetes workload of this app, so it does not store the key.')
+  const spaces = unique(t.workloads.map((w) => w.namespace))
+  if (spaces.includes(null)) return why('Your Kubernetes files do not name a namespace, so setup cannot tell where the secret goes.')
+  if (spaces.length > 1) return why(`Your Kubernetes files use ${spaces.length} namespaces, ${list(spaces)}, so setup cannot tell which one gets this key.`)
+  const ns = spaces[0], w = t.workloads[0]
+  const k = kube(cli, ctx)
+  const contexts = await k(['config', 'get-contexts', '-o', 'name'])
+  if (contexts.error === 'missing') return why('kubectl is not installed, so setup cannot store the key. Then run npx @uknows/setup key, or use the steps below.')
+  const all = contexts.code === 0 ? unique(contexts.stdout.split(/\r?\n/).map((l) => l.trim()).filter(Boolean)) : []
+  if (!all.length) return why('kubectl has no cluster set up, so setup cannot store the key. Set up kubectl for your cluster. Then run npx @uknows/setup key, or use the steps below.')
+  const resource = `${w.kind.toLowerCase()}/${w.name}`
+  say(`Looking for ${w.kind} ${w.name} in the namespace ${ns}, in the ${plural(all.length, 'kubectl context')} on this computer.`)
+  const found = []
+  for (const c of all) if ((await k(['--context', c, '-n', ns, 'get', resource, '-o', 'name', '--request-timeout=10s'])).code === 0) found.push(c)
+  if (!found.length) return why(`Setup did not find ${w.kind} ${w.name} in the namespace ${ns} in your kubectl contexts, so it does not store the key.`)
+  if (found.length > 1) return why(`Setup found ${w.kind} ${w.name} in ${found.length} kubectl contexts, ${list(found)}, so it cannot tell which one gets this key.`)
+  const at = ['--context', found[0], '-n', ns]
+  const had = (await k([...at, 'get', 'secret', K8S_SECRET, '-o', 'name', '--request-timeout=10s'])).code === 0
+  return { found: { kind: 'k8s', context: found[0], ns, at, replaces: had } }
+}
+
+// A cluster that wants a new sign-in (a device code) would wait for it: every kubectl call has a time limit.
+const kube = (cli, ctx) => (args, more = {}) => cli('kubectl', args, { cwd: ctx.root, env: ctx.env, timeoutMs: 60000, ...more })
+
+/** Apply the secret uknows that findK8s found, then check that it is there. */
+async function putK8s(cli, f, ctx) {
+  const k = kube(cli, ctx)
+  // The Secret goes to kubectl apply on stdin, so the key is in no argument and in no file.
+  const r = await k([...f.at, 'apply', '-f', '-'], { input: secretYaml(K8S_SECRET, f.ns, ctx.secretName, `${SECRET.header}=${ctx.key}`) })
+  if (r.code !== 0) return failure('Could not store the key', r, ctx.key)
+  if ((await k([...f.at, 'get', 'secret', K8S_SECRET, '-o', 'name', '--request-timeout=10s'])).code !== 0) {
+    return { stored: false, failed: true, why: `Setup applied the secret, but cannot find ${K8S_SECRET} in the namespace ${f.ns}.` }
+  }
+  return { stored: true, where: `the namespace ${f.ns}`, done: `Stored ${keyWord(ctx.environment).replace(/^this /, 'the ')} as the secret ${K8S_SECRET} in the namespace ${f.ns}.` }
+}
+
+const k8sQuestion = (f, ctx) => `Store ${keyWord(ctx.environment)} as the secret ${K8S_SECRET} in the namespace ${f.ns} (kubectl context ${f.context})? Pods that start after this get the key.${f.replaces ? ' It replaces the key in that secret.' : ''} (y/N)`
+
+/** Kubernetes: find the context, ask, then apply the secret. */
+async function storeK8s(ui, cli, t, ctx) {
+  const f = await findK8s(cli, t, ctx, ui.print)
+  if (!f.found) return f
+  if (!(await ui.confirm(k8sQuestion(f.found, ctx), false))) return { stored: false, declined: true }
+  return putK8s(cli, f.found, ctx)
+}
+
+/** A Kubernetes Secret with 1 value: the Secret that kubectl create secret generic makes. */
+export function secretYaml(name, namespace, key, value) {
+  return ['apiVersion: v1', 'kind: Secret', 'metadata:', `  name: ${name}`, `  namespace: ${namespace}`, 'type: Opaque', 'data:',
+    `  ${key}: ${Buffer.from(value, 'utf8').toString('base64')}`, ''].join('\n')
+}
+
+/** Read only lookups, and the writes after a yes, for each kind of place that can hold the key. */
+export const FIND = { aca: findAzure, webapp: findAzure, github: findGithub, k8s: findK8s }
+export const PUT = { aca: putAzure, webapp: putAzure, github: putGithub, k8s: putK8s }
+
+/**
+ * Where a store puts the key, for the plan: a title, the rows (label, value) and 1 line on what happens. Only from what
+ * FIND found, so the plan names the exact app, subscription, repository or cluster.
+ */
+export function storeRows(f) {
+  if (f.kind === 'aca' || f.kind === 'webapp') {
+    // A dry run looks up nothing: it names what the deploy files name, and says what a real run looks up.
+    const sub = f.dry ? 'the one that has this app. A real run looks it up.' : `${f.sub.name ?? f.sub.id} (${f.sub.id.slice(0, 8)}...)`
+    return { title: `Store your key on your ${AZURE[f.kind].what}`, rows: [['App', f.name], ['Resource group', f.rg], ['Subscription', sub]],
+      note: `${AZURE[f.kind].effect.replace('It restarts the app.', 'The app restarts with the key.')}${f.replaces ? ' It replaces the key that the app has now.' : ''}` }
+  }
+  if (f.kind === 'github') {
+    return { title: 'Store your key as a GitHub secret', rows: [['Secret', GITHUB_SECRET], ['Repository', f.repo], ...(f.env ? [['Environment', f.env]] : [])],
+      note: `${f.env ? 'The deploy jobs of that environment can read it.' : 'Every workflow of the repo can read it.'}${f.replaces ? ' It replaces the secret that is there now.' : ''}` }
+  }
+  return { title: 'Store your key as a Kubernetes secret', rows: [['Secret', K8S_SECRET], ['Namespace', f.ns], ['kubectl context', f.context]],
+    note: `Pods that start after this get the key.${f.replaces ? ' It replaces the key in that secret.' : ''}` }
+}
+
+/** The name that a progress line uses for a store: the app, the GitHub secret or the Kubernetes secret. */
+export const storeName = (f) => (f.kind === 'github' ? `the GitHub secret ${GITHUB_SECRET}` : f.kind === 'k8s' ? `the secret ${K8S_SECRET} in ${f.ns}` : f.name)
+
+const STORE = { aca: storeAzure, webapp: storeAzure, github: storeGithub, k8s: storeK8s }
+
+/** fn for each item, at most n at a time. The results keep the order of the items. */
+async function inTurn(items, n, fn) {
+  const out = new Array(items.length)
+  let next = 0
+  const worker = async () => { while (next < items.length) { const i = next++; out[i] = await fn(items[i]) } }
+  await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker))
+  return out
+}
+const keyTitle = (title) => HOSTS.find((h) => title === `Set your key once: ${h.label}`)
+
+/**
+ * The key steps in a terminal. For each "Set your key once" block whose platform setup can store the key on: ask, and
+ * store it. The block prints when the key is not stored. GitHub Actions needs no secret when setup stored the key on
+ * the app itself and no workflow reads the secret. Returns {stored, left, skipped, direct, github}: what is done, the
+ * titles of the blocks that are left, the hosts whose block is not needed, where the key went on the platform itself,
+ * and the GitHub Actions block when its secret is stored but no workflow step reads it yet.
+ * ctx: {key, environment, env, root, secretName, service, services}: service is the 1 service of the run, services every
+ * service of the run. key null: the key was not checked, so nothing is stored.
+ */
+export async function keyStepsInTerminal(ui, cli, blocks, targets, ctx) {
+  const out = { stored: [], left: [], skipped: [], direct: null }
+  const keyBlocks = blocks.filter((b) => keyTitle(b.title))
+  if (!keyBlocks.length) return out
+  if (!ctx.key && keyBlocks.some((b) => targets.has(keyTitle(b.title).id))) {
+    ui.print('Setup stores your key only after UKNOWS accepts it. To store it later, run npx @uknows/setup key. Or use the steps below.')
+    ui.print()
+  } else if (ctx.key && keyBlocks.some((b) => targets.has(keyTitle(b.title).id))) {
+    ui.print('Store your key')
+  }
+  for (const block of keyBlocks) {
+    const host = keyTitle(block.title), t = targets.get(host.id)
+    if (host.id === 'github-actions' && out.direct && !t?.readsKey) {
+      ui.print(`GitHub Actions needs no ${GITHUB_SECRET} secret: setup stored the key on ${out.direct}.`)
+      ui.print()
+      out.skipped.push(host.id)
+      continue
+    }
+    if (!t || !ctx.key) { ui.block(block); out.left.push(block.title); continue }
+    const r = await STORE[t.kind](ui, cli, t, ctx)
+    if (r.stored) {
+      ui.print('Stored.')
+      ui.print()
+      out.stored.push({ host: host.id, done: r.done })
+      if (t.kind !== 'github') out.direct = r.where
+      // A GitHub secret reaches the app only through a step of the deploy job. Without one, that step is left: the deploy
+      // file question can add it (githubStep), else it prints after the deploy files (githubStepBlock).
+      if (t.kind === 'github' && r.partial) { ui.block(block); out.left.push(block.title) } else if (t.kind === 'github' && !t.readsKey) out.github = block
+      continue
+    }
+    if (r.why) (r.failed ? ui.error : ui.print)(r.why)
+    if (r.failed) ui.print(r.again ? 'Use the steps below, or run npx @uknows/setup key to try again.' : 'Use the steps below.')
+    if (r.why || r.failed) ui.print()
+    ui.block(block)
+    out.left.push(block.title)
+  }
+  return out
+}
+
+/**
+ * The key steps of a run with 1 Yes, read only, before the plan. For each "Set your key once" block: a store that setup
+ * can do ({block, host, t, found}), or the block left for the person with why not. GitHub Actions needs no secret when the
+ * key goes on the app itself and no workflow reads the secret (skipped), as in keyStepsInTerminal. ctx as there.
+ * Returns {stores, left: [{block, host, why}], skipped: [{block, host}]}. why null: setup has no way to store it there.
+ */
+export async function planKeyStores(cli, blocks, targets, ctx, say = () => {}) {
+  const out = { stores: [], left: [], skipped: [] }
+  let direct = false
+  for (const block of blocks.filter((b) => keyTitle(b.title))) {
+    const host = keyTitle(block.title), t = targets.get(host.id)
+    if (host.id === 'github-actions' && direct && !t?.readsKey) { out.skipped.push({ block, host: host.id }); continue }
+    if (!t || !ctx.key) { out.left.push({ block, host: host.id, why: t ? 'no-key' : null }); continue }
+    const f = await FIND[t.kind](cli, t, ctx, say)
+    if (!f.found) { out.left.push({ block, host: host.id, why: f.why }); continue }
+    out.stores.push({ block, host: host.id, t, found: f.found })
+    if (t.kind !== 'github') direct = true
+  }
+  return out
+}
+
+/** The step of the GitHub Actions block that is left after the secret is stored: add the key step to the deploy job. */
+export function githubStepBlock(block) {
+  return { title: 'Add the key step to your deploy workflow', lines: block.lines.filter((l) => /^Add the step below|^Your deploy files name \d+ container apps|^The app must load the secret|^On other platforms/.test(l)),
+    snippets: (block.snippets ?? []).filter((x) => /- name: Set the UKNOWS key/.test(x.code)) }
+}
+
+/** The lines of the key step of the GitHub Actions block, from its - name: line to its az line, without comments. */
+export function githubStepLines(block) {
+  const code = (block?.snippets ?? []).find((x) => /- name: Set the UKNOWS key/.test(x.code))?.code
+  if (!code) return null
+  const rows = code.split('\n')
+  const from = rows.findIndex((l) => /^- name: Set the UKNOWS key/.test(l)), to = rows.findIndex((l) => /\baz containerapp secret set\b/.test(l))
+  return from >= 0 && to > from ? rows.slice(from, to + 1).map((l) => l.replace(/\s+#[^'"]*$/, '')) : null
+}
+
+// --- deploy files -------------------------------------------------------------------
+
+/**
+ * The edits that make each deploy keep the key, 1 per file, from the files on disk now. Only the safe cases:
+ *   --replace-env-vars of az containerapp update: the env entry goes after the last pair of the list.
+ *   environmentVariables of the Container Apps deploy action, on 1 line: the env entry goes at its end.
+ *   a container of a plain Kubernetes file with no envFrom: envFrom with the secret uknows, optional.
+ * Anything else stays a printed step. A file that holds a key, or above the setup folder, is never changed.
+ * Each edit: {file, before, after, lines (1-based, in before), checks (the deploy check ids it does), about}.
+ * plans: [{s}] with s.k8s. secretName: the variable that holds the key.
+ */
+export function deployEdits(view, hosts, plans, secretName, { githubStep = null } = {}) {
+  const files = new Map()
+  const evidence = (id, what) => unique(hosts.filter((h) => h.id === id).flatMap((h) => h.evidence ?? []).filter((e) => e.what === what).map((e) => e.file))
+  const add = (file, check, apply) => {
+    if (file.startsWith('../')) return
+    if (!files.has(file)) {
+      let text = null
+      try { text = view.read(file) } catch { text = null }
+      if (text === null || hasKey(text)) return
+      files.set(file, { file, before: text, after: text, lines: [], checks: [], about: [] })
+    }
+    const entry = files.get(file)
+    const result = apply(entry.after)
+    if (!result) return
+    entry.after = result.after
+    entry.lines.push(...result.lines)
+    entry.checks.push(check)
+    entry.about.push(`${file} ${result.lines.length > 1 ? 'lines' : 'line'} ${list(result.lines.map(String))} ${result.about}`)
+  }
+  const pair = `${secretName}=secretref:${ACA_SECRET}`
+  for (const file of evidence('azure-container-apps', 'Deploy step runs az containerapp')) add(file, 'replace-env-vars', (text) => replaceEnvEdit(text, pair, secretName))
+  for (const file of evidence('azure-container-apps', 'Azure Container Apps deploy action')) add(file, 'deploy-action-env', (text) => actionEnvEdit(text, pair, secretName))
+  // The key is in a GitHub secret now: the deploy job sets it on the container app, and its deploy command loads it.
+  if (githubStep && hosts.some((h) => h.id === 'azure-container-apps')) {
+    for (const file of evidence('github-actions', 'GitHub Actions workflow that deploys')) add(file, 'github-step', (text) => githubStepEdit(text, githubStep, pair, secretName))
+  }
+  if (hosts.some((h) => h.id === 'kubernetes')) {
+    for (const p of plans) for (const k of p.s?.k8s ?? []) add(k.file, 'env-from', (text) => envFromEdit(text, k.doc, k.container))
+  }
+  return [...files.values()].filter((e) => e.after !== e.before).map((e) => ({ ...e, lines: unique(e.lines).sort((a, b) => a - b),
+    question: `Add the key to ${e.file} ${e.lines.length > 1 ? 'lines' : 'line'} ${list(unique(e.lines).sort((a, b) => a - b).map(String))}? (y/N)` }))
+}
+
+const setsVar = (name) => new RegExp(`(?:^|[\\s"'])${name}=`)
+
+/** --replace-env-vars of each az containerapp update in text: the pair after the last value. null when nothing to add. */
+export function replaceEnvEdit(text, pair, name) {
+  const d = new Doc(text)
+  const lines = []
+  for (let i = 0; i < d.length; i++) {
+    const line = d.get(i)
+    if (/^\s*#/.test(line)) continue
+    const flag = /(^|\s)--replace-env-vars(?=\s|$)/.exec(line)
+    if (!flag) continue
+    let start = i
+    while (start > 0 && /\\\s*$/.test(d.get(start - 1))) start--
+    let end = i
+    while (end + 1 < d.length && /\\\s*$/.test(d.get(end))) end++
+    const command = Array.from({ length: end - start + 1 }, (_, k) => d.get(start + k)).join('\n')
+    if (!/\baz\s+containerapp\s+update\b/.test(command) || setsVar(name).test(command)) continue
+    // The values after the flag, up to the next option, the end of the command, a comment or a shell operator.
+    let row = i, col = flag.index + flag[0].length, last = null
+    for (;;) {
+      const rest = d.get(row).slice(col)
+      const re = /("[^"]*"|'[^']*'|[^\s"']+)/g
+      let m, stop = false, more = false
+      while ((m = re.exec(rest))) {
+        const token = m[1]
+        if (token === '\\' && !rest.slice(m.index + 1).trim()) { more = true; break }
+        if (/^(?:-|#|&&|\|\||;|\|)/.test(token)) { stop = true; break }
+        if (!/=/.test(token)) { stop = true; break }
+        last = { row, col: col + m.index + token.length }
+      }
+      if (stop || !more || row + 1 >= d.length) break
+      row++
+      col = 0
+    }
+    if (!last) continue
+    const target = d.get(last.row)
+    d.set(last.row, `${target.slice(0, last.col)} ${pair}${target.slice(last.col)}`)
+    lines.push(i + 1)
+  }
+  return lines.length ? { after: d.toString(), lines,
+    about: `runs az containerapp update with --replace-env-vars. That replaces every environment variable of the app, so each deploy would remove the key.` } : null
+}
+
+/**
+ * The key step of the docs before each workflow step that runs az containerapp update, in a job that does not read the
+ * UKNOWS_KEY secret yet, and the env entry that loads the key on that command (unless it has --replace-env-vars, whose
+ * edit adds it). null when nothing to add, and when a command names another app than the APP of the key step: that
+ * step would set the key on 1 app only, so it stays a printed step.
+ */
+export function githubStepEdit(text, stepLines, pair, name) {
+  const d = new Doc(text)
+  const indent = (l) => /^\s*/.exec(l)[0].length
+  const unquote = (v) => v?.replace(/^(["'])(.*)\1$/, '$2') ?? null
+  const app = unquote(stepLines.map((l) => /^\s+APP:\s*(\S+)\s*$/.exec(l)?.[1]).find(Boolean))
+  const spots = []
+  for (let i = 0; i < d.length; i++) {
+    if (/^\s*#/.test(d.get(i)) || !/\baz\s+containerapp\s+update\b/.test(d.get(i))) continue
+    let step = i
+    while (step >= 0 && !(/^\s*-\s+\S/.test(d.get(step)) && indent(d.get(step)) < indent(d.get(i)))) step--
+    if (step < 0) return null
+    // The job of the step: up to the line with less indent than its steps: key.
+    let top = step
+    while (top > 0 && !/^\s*steps\s*:/.test(d.get(top))) top--
+    let job = top
+    while (job > 0 && !(d.get(job).trim() && indent(d.get(job)) < indent(d.get(top)))) job--
+    let end = top + 1
+    while (end < d.length && (!d.get(end).trim() || indent(d.get(end)) > indent(d.get(job)))) end++
+    const body = Array.from({ length: end - job }, (_, k) => d.get(job + k)).join('\n')
+    if (new RegExp(`\\bsecrets\\.${GITHUB_SECRET}\\b`).test(body) || /- name: Set the UKNOWS key/.test(body)) continue
+    let last = i
+    while (last + 1 < d.length && /\\\s*$/.test(d.get(last))) last++
+    const command = Array.from({ length: last - i + 1 }, (_, k) => d.get(i + k)).join('\n')
+    // A literal app name that is not the APP of the key step. A $VARIABLE is the deploy's own: the names came from it.
+    const named = unquote(/(?:^|\s)(?:-n|--name)[\s=]+("[^"]*"|'[^']*'|\S+)/.exec(command)?.[1])
+    if (app && named && !named.includes('$') && named !== app) return null
+    // The subscription of the key step: the one of the deploy command, else the one that azure/login signs in to.
+    const subscription = /--subscription[\s=]+("[^"]*"|'[^']*'|\S+)/.exec(command)?.[1]?.replace(/^(["'])(.*)\1$/, '$2')
+      ?? /^\s*subscription-id\s*:\s*(.+?)\s*$/m.exec(body)?.[1]?.replace(/^(["'])(.*)\1$/, '$2') ?? null
+    spots.push({ step, i, subscription, first: !spots.some((x) => x.step === step),
+      env: !setsVar(name).test(command) && !/(?:^|\s)--replace-env-vars(?=\s|$)/.test(command) })
+  }
+  if (!spots.length) return null
+  for (const spot of [...spots].reverse()) {
+    if (spot.env) {
+      // On the --set-env-vars list of the command if it has one: az keeps only the last --set-env-vars list.
+      const command = updateCommandAt(d, spot.i)
+      if (!command) return null
+      applyChanges(d, [setEnvChange(command, pair)])
+    }
+    if (!spot.first) continue
+    const pad = ' '.repeat(indent(d.get(spot.step)))
+    const lines = stepLines.map((l) => (spot.subscription && /^\s+SUBSCRIPTION:/.test(l) ? `${/^\s*/.exec(l)[0]}SUBSCRIPTION: ${spot.subscription}` : l))
+    d.insert(spot.step, ...lines.map((l) => `${pad}${l}`), '')
+  }
+  // Lines in the text before the edit: the step that the key step goes before.
+  return { after: d.toString(), lines: unique(spots.map((s) => s.step + 1)),
+    about: 'deploys with az containerapp update. This adds the step that sets the key from the UKNOWS_KEY secret before it, and loads the key in the deploy command. Your GitHub secret then reaches the app on each deploy.' }
+}
+
+/** environmentVariables of the Container Apps deploy action, on 1 line: the pair at its end. null when nothing to add. */
+export function actionEnvEdit(text, pair, name) {
+  const d = new Doc(text)
+  const lines = []
+  for (let i = 0; i < d.length; i++) {
+    const m = /^(\s*environmentVariables\s*:\s*)(.*?)((?:\s+#.*)?)\s*$/.exec(d.get(i))
+    if (!m || !inActionStep(d, i)) continue
+    const value = m[2]
+    if (!value || /^[|>]/.test(value) || setsVar(name).test(value)) continue
+    const quoted = /^(["'])(.*)\1$/.exec(value)
+    if (!quoted && /["']/.test(value)) continue
+    const next = quoted ? `${quoted[1]}${quoted[2]} ${pair}${quoted[1]}` : `${value} ${pair}`
+    d.set(i, `${m[1]}${next}${m[3]}`)
+    lines.push(i + 1)
+  }
+  return lines.length ? { after: d.toString(), lines,
+    about: 'gives the Container Apps deploy action its environmentVariables. The action replaces every environment variable, so each deploy would remove the key.' } : null
+}
+
+/** True when line i is in a workflow step that uses azure/container-apps-deploy-action. */
+function inActionStep(d, i) {
+  const indent = (l) => /^\s*/.exec(l)[0].length
+  let start = i
+  while (start >= 0 && !/^\s*-\s/.test(d.get(start))) start--
+  if (start < 0) return false
+  const pad = indent(d.get(start))
+  for (let j = start; j < d.length && (j === start || !d.get(j).trim() || indent(d.get(j)) > pad); j++) {
+    if (/^\s*(?:-\s+)?uses\s*:\s*['"]?azure\/container-apps-deploy-action@/.test(d.get(j))) return true
+  }
+  return false
+}
+
+/** The rows of 1 container of document doc of a YAML file, with top: the indent of its keys. null when not found. */
+function containerItem(d, doc, container) {
+  const rows = docLines(d, doc).filter((i) => d.get(i).trim() && !/^\s*#/.test(d.get(i)))
+    .map((i) => ({ i, indent: /^\s*/.exec(d.get(i))[0].length, text: d.get(i).trim() }))
+  for (let r = 0; r < rows.length; r++) {
+    if (!/^containers:\s*(?:#.*)?$/.test(rows[r].text)) continue
+    for (const item of items(rows, r)) {
+      const name = item.find((x) => x.indent === item.top && /^name:/.test(x.text))?.text.replace(/^name:\s*/, '').replace(/\s+#.*$/, '').replace(/^(['"])(.*)\1$/, '$2')
+      if (name === container) return item
+    }
+  }
+  return null
+}
+
+/** True when the container loads the secret uknows with envFrom. */
+function loadsSecret(item) {
+  const from = item.findIndex((x) => x.indent === item.top && /^envFrom:/.test(x.text))
+  if (from < 0) return false
+  for (let k = from + 1; k < item.length && item[k].indent > item.top; k++) if (new RegExp(`^name:\\s*['"]?${K8S_SECRET}['"]?\\s*(?:#.*)?$`).test(item[k].text)) return true
+  return false
+}
+
+/** True when every Kubernetes container of the services loads the secret uknows (after the deploy file step). */
+export function k8sLoadsKey(view, plans) {
+  for (const p of plans) {
+    for (const k of p.s?.k8s ?? []) {
+      let text = null
+      try { text = view.read(k.file) } catch { text = null }
+      const item = text === null ? null : containerItem(new Doc(text), k.doc, k.container)
+      if (!item || !loadsSecret(item)) return false
+    }
+  }
+  return true
+}
+
+/** envFrom with the secret uknows for 1 container of document doc. null when it has envFrom already, or is not found. */
+export function envFromEdit(text, doc, container) {
+  const d = new Doc(text)
+  const item = containerItem(d, doc, container)
+  if (!item || item.some((x) => x.indent === item.top && /^envFrom:/.test(x.text))) return null
+  const pad = ' '.repeat(item.top)
+  d.insert(item[item.length - 1].i + 1, `${pad}envFrom:`, `${pad}  - secretRef:`, `${pad}      name: ${K8S_SECRET}`, `${pad}      optional: true`)
+  const line = item.find((x) => x.indent === item.top && /^name:/.test(x.text))?.i ?? item[0].i
+  return { after: d.toString(), lines: [line + 1],
+    about: `runs the container ${container}, which does not load the secret ${K8S_SECRET} yet. This adds envFrom, so new pods get the key.` }
+}
+
+/** The items of the block list under rows[at], each with its rows and top: the indent of its keys. */
+function items(rows, at) {
+  const out = []
+  let dash = -1
+  for (let r = at + 1; r < rows.length; r++) {
+    const { indent, text } = rows[r]
+    const isDash = /^-(?:\s|$)/.test(text)
+    if (dash < 0) { if (!isDash || indent < rows[at].indent) break; dash = indent }
+    if (indent < dash || (indent === dash && !isDash)) break
+    if (indent === dash) {
+      const rest = text.slice(1), trimmed = rest.trimStart()
+      const item = trimmed ? [{ i: rows[r].i, indent: indent + 1 + rest.length - trimmed.length, text: trimmed }] : []
+      out.push(Object.assign(item, { top: item[0]?.indent ?? -1 }))
+    } else {
+      const item = out[out.length - 1]
+      if (item.top < 0) item.top = indent
+      item.push(rows[r])
+    }
+  }
+  return out.filter((item) => item.length)
+}
+
+/**
+ * Ask for each deploy file edit, with what it changes and why, and apply it with apply(edit) on a yes. Returns the
+ * edits that were applied.
+ */
+export async function deployFilesInTerminal(ui, edits, apply) {
+  const done = []
+  for (const edit of edits) {
+    for (const about of edit.about) ui.print(about)
+    for (const line of unified(edit.file, edit.before, edit.after).split('\n')) ui.print(line)
+    if (!(await ui.confirm(edit.question, false))) { ui.print(); continue }
+    try {
+      apply(edit)
+      done.push(edit)
+      ui.print(`Changed ${edit.file}. To undo it, run npx @uknows/setup remove.`)
+    } catch (error) {
+      ui.error(`Could not change ${edit.file}: ${error.message}. It is as it was.`)
+    }
+    ui.print()
+  }
+  return done
+}
+
+/**
+ * The deploy check lines that are done: the ones that a deploy file edit did for every file that the line names, the
+ * secret-first line when the key is on the container app, and the GitHub guard when its block is not needed.
+ */
+export function openChecks(blocks, { edits = [], stored = [], skipped = [], secretName = SECRET.name }) {
+  const text = (host, id) => {
+    const t = HOSTS.find((h) => h.id === host)?.checks?.find((c) => c.id === id)?.text
+    return t ? t.split(SECRET.name).join(secretName) : null
+  }
+  const doneBy = new Map([['replace-env-vars', 'azure-container-apps'], ['deploy-action-env', 'azure-container-apps']])
+  return blocks.flatMap((block) => {
+    if (keyTitle(block.title)) return []
+    const host = HOSTS.find((h) => block.title.endsWith(`: ${h.label}`) && block.title.startsWith('Check your deploy files'))
+    if (!host) return [block]
+    if (skipped.includes(host.id)) return []
+    // The key step that the GitHub step edit added sets the secret before the deploy, and fails the job without it.
+    const step = edits.some((e) => e.checks.includes('github-step'))
+    const lines = block.lines.filter((line) => {
+      if (host.id === 'azure-container-apps' && (stored.includes('azure-container-apps') || step) && line === text(host.id, 'secret-first')) return false
+      if (host.id === 'github-actions' && step && line === text(host.id, 'guard')) return false
+      for (const [id, hostId] of doneBy) {
+        const t = text(hostId, id)
+        if (host.id !== hostId || !t || !line.startsWith(t)) continue
+        const files = [...line.slice(t.length).matchAll(/([^\s,]+) line \d+/g)].map((m) => m[1])
+        if (files.length && files.every((f) => edits.some((e) => e.file === f && e.checks.includes(id)))) return false
+      }
+      return true
+    })
+    return lines.length ? [{ ...block, lines }] : []
+  })
+}
+
+// --- the pull request ---------------------------------------------------------------
+
+/** The paths in the porcelain -z output of git status, relative to the folder whose prefix is given. */
+function statusPaths(out, prefix) {
+  const tokens = out.split('\0'), paths = []
+  for (let i = 0; i < tokens.length; i++) {
+    const entry = tokens[i]
+    if (entry.length < 4) continue
+    if (entry[0] === 'R' || entry[0] === 'C') i++
+    const path = entry.slice(3)
+    paths.push(path.startsWith(prefix) ? path.slice(prefix.length) : path)
+  }
+  return paths
+}
+
+/** ssh never asks for a passphrase: the terminal belongs to the questions of setup. A command of the user stays. */
+async function sshEnv(git, env) {
+  return env.GIT_SSH_COMMAND || (await git(['config', '--get', 'core.sshCommand'])).code === 0 ? {} : { GIT_SSH_COMMAND: 'ssh -o BatchMode=yes' }
+}
+
+/** The name after this one: uknows-setup, uknows-setup-2, uknows-setup-3 and so on. */
+const nextBranch = (name) => (name === PULL_REQUEST.branch ? `${name}-2` : name.replace(/-(\d+)$/, (m, n) => `-${Number(n) + 1}`))
+
+/** A commit subject as the question shows it: 1 line, no control characters, at most 72 characters. */
+const subject = (text) => {
+  const line = String(text).replace(/[\u0000-\u001f\u007f]/g, '').trim()
+  return line.length > 72 ? `${line.slice(0, 71)}...` : line
+}
+
+/**
+ * What the pull request step needs to know, before its question. git: (args, more) => result, in the repo.
+ *   from: the branch checked out (null: none). remote: the origin address. slug: owner/name on GitHub.
+ *   base: the branch of origin that the pull request goes to: the branch checked out when origin has it, else the
+ *     default branch of origin (origin/HEAD). null when origin has neither: then setup does not push.
+ *   ahead: {count, subjects}, the commits on HEAD that origin/<base> does not have. A push takes them along.
+ *   branch: the first free name, uknows-setup, then uknows-setup-2 and so on.
+ * network: also ask origin which branches it has (git ls-remote), so a branch that a teammate pushed is never taken.
+ * The dry run passes false and reads only this computer.
+ */
+export async function prFacts(git, { env = {}, network = false } = {}) {
+  const head = await git(['rev-parse', '--abbrev-ref', 'HEAD'])
+  if (head.code !== 0) return null
+  const from = head.stdout.trim()
+  if (from === 'HEAD') return { from: null }
+  const exists = async (ref) => (await git(['rev-parse', '--verify', '--quiet', ref])).code === 0
+  const origin = await git(['config', '--get', 'remote.origin.url'])
+  const remote = origin.code === 0 ? origin.stdout.trim() || null : null
+  let base = null
+  if (remote) {
+    if (await exists(`refs/remotes/origin/${from}`)) base = from
+    else {
+      const def = await git(['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'])
+      const name = def.code === 0 && def.stdout.trim().startsWith('origin/') ? def.stdout.trim().slice('origin/'.length) : null
+      if (name && (await exists(`refs/remotes/origin/${name}`))) base = name
+    }
+  }
+  const ahead = { count: 0, subjects: [] }
+  if (base) {
+    const range = `refs/remotes/origin/${base}..HEAD`
+    ahead.count = Number((await git(['rev-list', '--count', range])).stdout.trim()) || 0
+    if (ahead.count) ahead.subjects = (await git(['log', '-n', '3', '--format=%s', range])).stdout.split('\n').map(subject).filter(Boolean)
+  }
+  const ssh = network && remote ? await sshEnv(git, env) : {}
+  const taken = new Set()
+  if (network && remote) {
+    // The heads of origin, where the push goes. Read only. Without an answer, the local names are all setup knows.
+    const push = await git(['remote', 'get-url', '--push', 'origin'])
+    const heads = await git(['ls-remote', '--heads', push.code === 0 && push.stdout.trim() ? push.stdout.trim() : 'origin'], { timeoutMs: 30000, env: { ...env, ...ssh } })
+    if (heads.code === 0) for (const m of heads.stdout.matchAll(/\trefs\/heads\/(\S+)/g)) taken.add(m[1])
+  }
+  const free = async (name) => !taken.has(name) && !(await exists(`refs/heads/${name}`)) && !(await exists(`refs/remotes/origin/${name}`))
+  let branch = PULL_REQUEST.branch
+  for (let n = 0; n < 100 && !(await free(branch)); n++) branch = nextBranch(branch)
+  return { from, remote, slug: githubSlug(remote), base, ahead, branch, ssh }
+}
+
+/**
+ * The files of the commit, as the questions name them: the files of the app that setup changed, and its record
+ * (.uknows/setup.json), so the count matches the "Changed N files" line of the run. earlier: a rerun names the files
+ * that an earlier run changed.
+ */
+export function commitFiles(files, earlier = false) {
+  const n = files.filter((f) => f !== CLI.manifest).length
+  const changed = `the ${plural(n, 'file')} setup changed${earlier ? ' earlier' : ''}`
+  if (!files.includes(CLI.manifest)) return changed
+  return n ? `${changed} and its record, ${CLI.manifest}` : `the record of setup, ${CLI.manifest}`
+}
+
+/** The paths that git shows as changed and not committed, of the paths given, relative to the folder of git. */
+async function changedPaths(git, paths) {
+  const prefix = (await git(['rev-parse', '--show-prefix'])).stdout.trim()
+  const status = await git(['status', '--porcelain=v1', '-z', '--untracked-files=all', '--', ...paths])
+  return status.code === 0 ? unique(statusPaths(status.stdout, prefix)).sort() : []
+}
+
+/**
+ * The files of setup that are not committed yet: paths is the manifest and its paths. [] when git cannot tell. A rerun
+ * with nothing to change reads it, to say that setup has nothing more to change but its files are not committed yet.
+ */
+export function notCommitted(cli, { root, env, paths }) {
+  return changedPaths((args) => cli('git', ['-C', root, ...args], { cwd: root, env }), paths)
+}
+
+/**
+ * The question of the pull request step. files: the paths of the commit. pr: setup opens the pull request (gh is
+ * signed in, origin is on GitHub and has a base). Commits of the user that origin does not have go along on a push:
+ * the question names them, and no is the default then.
+ */
+export function prQuestion({ branch, files, pr, base = null, ahead = { count: 0, subjects: [] } }) {
+  const what = pr ? `Create branch ${branch}, commit ${commitFiles(files)}, and open a pull request?` : `Create branch ${branch} and commit ${commitFiles(files)}?`
+  if (!ahead.count) return `${what} (Y/n)`
+  const names = ahead.subjects.map((s) => `"${s}"`)
+  const shown = ahead.count > names.length ? `${names.join(', ')} and ${ahead.count - names.length} more` : list(names)
+  return `${what} ${pr ? 'The pull request also gets' : 'The branch also has'} ${plural(ahead.count, 'commit')} of yours that ${ahead.count === 1 ? 'is' : 'are'} not on origin/${base} yet: ${shown}. (y/N)`
+}
+
+/** Why a git push failed: the line of origin or git that says so, and whether the branch name is taken on origin. */
+export function pushFailure(stderr) {
+  const lines = String(stderr ?? '').split(/\r?\n/).map((l) => l.trim().replace(/\s+/g, ' ')).filter(Boolean)
+  const rejected = lines.find((l) => /^! \[(?:remote )?rejected\]/.test(l))
+  const told = lines.map((l) => /^remote:\s*(.+)$/.exec(l)?.[1]?.trim()).find((l) => l && !/^error: failed to push/i.test(l))
+  const other = lines.find((l) => !/^(?:To |hint:|error: failed to push some refs)/.test(l))
+  const reason = (told ?? rejected ?? other ?? 'no reason given').replace(/^(?:fatal|error):\s*/, '').slice(0, 300)
+  return { reason, taken: Boolean(rejected && /\((?:fetch first|non-fast-forward|already exists)\)/.test(rejected)) }
+}
+
+/**
+ * The pull request step, read only: the facts of prFacts (with the network: the branches of origin) and whether gh
+ * can open the pull request. null: not a git repo. {from: null}: no branch checked out.
+ */
+export async function prPlan(cli, { root, env, gh = true }) {
+  const git = (args, more = {}) => cli('git', ['-C', root, ...args], { cwd: root, env, ...more })
+  const facts = await prFacts(git, { env, network: true })
+  if (!facts || !facts.from) return facts
+  return gh ? { ...facts, gh: await ghReady(cli, facts, { root, env }) } : facts
+}
+
+/** True when gh is signed in and origin is on GitHub with a base, so setup can push and open the pull request. */
+const ghReady = async (cli, facts, { root, env }) => (facts.slug && facts.base ? (await cli('gh', ['auth', 'status', '--hostname', 'github.com'], { cwd: root, env })).code === 0 : false)
+
+/**
+ * The pull request step. With a yes: a new branch, 1 commit of exactly the files that setup changed (never git add -A),
+ * then git push and gh pr create when gh is signed in and origin is on GitHub with a base for the pull request. Without
+ * gh, a remote or a base: the commit, then the push command and where to open the pull request. Never a force push.
+ * paths: every path that setup changed (the manifest and its paths), relative to root. left: the titles of the steps
+ * that are left, for the checklist of the pull request. environment: the one of the key check, for the link. rerun: a run
+ * with nothing to change, after a no to this question earlier: it says first that the files are not committed yet.
+ * key: what the pull request says about the key (see prBody). Returns {state: 'pr'|'pushed'|'committed'|'declined'|'none',
+ * branch, url}.
+ */
+export async function pullRequest(ui, cli, { root, env, paths, left = [], done = [], services = [], url, environment = null, rerun = false, key = null, logs = true, cloudId = false, updates = [] }) {
+  const facts = await prPlan(cli, { root, env, gh: false })
+  if (!facts) return { state: 'none' }
+  if (!facts.from) {
+    ui.print('This repo has no branch checked out, so setup does not commit. Commit the change and open a pull request yourself.')
+    ui.print()
+    return { state: 'none' }
+  }
+  const git = (args, more = {}) => cli('git', ['-C', root, ...args], { cwd: root, env, ...more })
+  const files = await changedPaths(git, paths)
+  if (!files.length) return { state: 'none' }
+  facts.gh = await ghReady(cli, facts, { root, env })
+  if (rerun) ui.print()
+  ui.print('Open a pull request')
+  if (rerun) {
+    const earlier = commitFiles(files, true)
+    ui.print(`${earlier[0].toUpperCase()}${earlier.slice(1)}${files.includes(CLI.manifest) ? ',' : ''} ${files.length === 1 ? 'is' : 'are'} not committed yet.`)
+  }
+  if (!(await ui.confirm(prQuestion({ branch: facts.branch, files, pr: facts.gh, base: facts.base, ahead: facts.ahead }), !facts.ahead.count))) {
+    ui.print('Nothing committed.')
+    ui.print()
+    return { state: 'declined' }
+  }
+  const r = await prRun(cli, facts, { root, env, files, body: () => prBody({ services, files, left, done, url, environment, key, logs, cloudId, updates }) }, ui.print, ui.error)
+  ui.print()
+  return r
+}
+
+/**
+ * Create the branch, commit, push and open the pull request, as pullRequest does after its yes. say(line) and
+ * warn(line) get every line it prints. files: the paths of the commit. body(): the text of the pull request.
+ * noPush: why setup only commits, though gh could push (a run with 1 Yes does not push commits of the user).
+ * Returns {state: 'pr'|'pushed'|'committed'|'declined', branch, url, why}.
+ */
+export async function prRun(cli, facts, { root, env, files, body, noPush = null }, say, warn) {
+  const git = (args, more = {}) => cli('git', ['-C', root, ...args], { cwd: root, env, ...more })
+  const { from, remote, slug, base, branch, ssh } = facts
+  const named = commitFiles(files)
+  let r = await git(['switch', '-c', branch])
+  if (r.code !== 0) r = await git(['checkout', '-b', branch])
+  if (r.code !== 0) { const why = `Could not create the branch ${branch}: ${failed(r)}`; warn(why); return { state: 'declined', why } }
+  r = await git(['add', '--', ...files])
+  if (r.code === 0) r = await git(['commit', '-q', '-m', PULL_REQUEST.title, '-m', 'Made with npx @uknows/setup. To undo it, run npx @uknows/setup remove.', '--', ...files])
+  if (r.code !== 0) {
+    const why = `Could not commit: ${failed(r)}`
+    warn(why)
+    await git(['switch', from])
+    await git(['branch', '-d', branch])
+    say('Commit the change yourself, then open a pull request.')
+    return { state: 'declined', why }
+  }
+  say(`Created the branch ${branch} with 1 commit, ${PULL_REQUEST.title}. It has ${named}.`)
+  const newPr = slug ? `https://github.com/${slug}/pull/new/${branch}` : null
+  const here = `You are on the branch ${branch} now.`
+  if (!facts.gh || noPush) {
+    if (noPush) say(noPush)
+    else if (remote && !base) say('Setup cannot tell which branch of origin the pull request goes to, so it does not push.')
+    say(remote ? `Push it with: git push -u origin ${branch}` : `This repo has no remote named origin. Push the branch ${branch} to your git host.`)
+    say(newPr ? `Then open the pull request at ${newPr}` : 'Then open a pull request there.')
+    say(here)
+    return { state: 'committed', branch }
+  }
+  // On GitHub the commit goes up through the GitHub API, so GitHub signs it, and a branch rule that requires signed
+  // commits passes with no key on this computer (owner decision, 22 Oct 2026). The local branch then points at that
+  // commit: the same files, so nothing changes in the folder. When the API does not take it, setup pushes as before.
+  const signed = await apiCommit(git, cli, { root, env, slug, branch })
+  if (signed.ok) {
+    say(`Pushed ${branch} to origin as 1 commit that GitHub signed.`)
+    if (!signed.local) say(`Your local branch ${branch} still has the commit made on this computer. Run git fetch origin and git reset --soft origin/${branch} to match it.`)
+    r = { code: 0 }
+  } else {
+    if (signed.why) say(`GitHub did not take the commit through its API (${signed.why}), so setup pushes it.`)
+    // If the push fails, setup prints the push command (ssh never asks for a passphrase here, see sshEnv).
+    r = await git(['push', '-u', 'origin', branch], { timeoutMs: 180000, env: { ...env, ...ssh } })
+  }
+  if (r.code !== 0) {
+    const why = pushFailure(r.error ?? r.stderr)
+    warn(`Could not push the branch: ${why.reason}`)
+    if (why.taken) {
+      // A teammate pushed this name after setup looked: push under the next name.
+      const next = nextBranch(branch)
+      say(`The branch ${branch} is on origin already. Rename yours with: git branch -m ${branch} ${next}`)
+      say(`Then push it with: git push -u origin ${next}`)
+      say(`Then open the pull request at https://github.com/${slug}/pull/new/${next}`)
+    } else {
+      say(`Fix that, then push it with: git push -u origin ${branch}`)
+      say(`Then open the pull request at ${newPr}`)
+    }
+    say(here)
+    return { state: 'committed', branch, why: `Could not push the branch: ${why.reason}` }
+  }
+  if (!signed.ok) say(`Pushed ${branch} to origin.`)
+  r = await cli('gh', ['pr', 'create', '--repo', slug, '--base', base, '--head', branch, '--title', PULL_REQUEST.title, '--body-file', '-'],
+    { cwd: root, env, input: body(), timeoutMs: 120000 })
+  const link = /https:\/\/\S+/.exec(r.stdout ?? '')?.[0]
+  if (r.code !== 0 || !link) {
+    const why = `Could not open the pull request: ${failed(r)}`
+    warn(why)
+    say(`Open it at ${newPr}`)
+    say(here)
+    return { state: 'pushed', branch, why }
+  }
+  say(`Opened the pull request: ${link}`)
+  say(here)
+  return { state: 'pr', branch, url: link }
+}
+
+const COMMIT_MUTATION = 'mutation($input: CreateCommitOnBranchInput!) { createCommitOnBranch(input: $input) { commit { oid url } } }'
+
+/**
+ * The commit of the pull request through the GitHub API (createCommitOnBranch), which GitHub signs. The local commit is
+ * HEAD and its parent is on origin. Only plain files, whose bytes on disk are the bytes of the commit (no line-ending
+ * filter), can go this way: the API writes every file as a plain file. Returns {ok, local} or {ok: false, why}.
+ */
+async function apiCommit(git, cli, { root, env, slug, branch }) {
+  const gh = (args, more = {}) => cli('gh', args, { cwd: root, env, timeoutMs: 120000, ...more })
+  const rev = async (ref) => { const r = await git(['rev-parse', '--verify', '-q', ref]); return r.code === 0 ? r.stdout.trim() : null }
+  const base = await rev('HEAD~1'), head = await rev('HEAD')
+  if (!base || !head) return { ok: false }
+  const raw = await git(['diff', '--raw', '--no-abbrev', '--no-renames', '-z', base, head])
+  if (raw.code !== 0) return { ok: false }
+  const parts = raw.stdout.split('\0').filter((x) => x !== '')
+  const additions = [], deletions = []
+  for (let i = 0; i + 1 < parts.length; i += 2) {
+    const [src, dst, , blob, status] = parts[i].replace(/^:/, '').split(' ')
+    const path = parts[i + 1]
+    if (status === 'D') { deletions.push({ path }); continue }
+    if (dst !== '100644' || !['100644', '000000'].includes(src)) return { ok: false, why: `${path} is not a plain file` }
+    const disk = await git(['hash-object', '--no-filters', '--', path])
+    if (disk.code !== 0 || disk.stdout.trim() !== blob) return { ok: false, why: `${path} changes when git writes it` }
+    additions.push({ path, contents: readFileSync(join(root, path)).toString('base64') })
+  }
+  if (!additions.length && !deletions.length) return { ok: false }
+  let r = await gh(['api', '-X', 'POST', `repos/${slug}/git/refs`, '-f', `ref=refs/heads/${branch}`, '-f', `sha=${base}`])
+  if (r.code !== 0) return { ok: false, why: failed(r) }
+  const input = { branch: { repositoryNameWithOwner: slug, branchName: branch }, expectedHeadOid: base,
+    message: { headline: PULL_REQUEST.title, body: 'Made with npx @uknows/setup. To undo it, run npx @uknows/setup remove.' },
+    fileChanges: { additions, deletions } }
+  r = await gh(['api', 'graphql', '--input', '-'], { input: JSON.stringify({ query: COMMIT_MUTATION, variables: { input } }) })
+  const oid = parse(r.stdout ?? '')?.data?.createCommitOnBranch?.commit?.oid
+  if (r.code !== 0 || !oid) {
+    await gh(['api', '-X', 'DELETE', `repos/${slug}/git/refs/heads/${branch}`])
+    return { ok: false, why: failed(r) }
+  }
+  // The local branch takes the signed commit. Its tree is the tree of the local commit, so only HEAD moves.
+  r = await git(['fetch', '-q', 'origin', `+refs/heads/${branch}:refs/remotes/origin/${branch}`], { timeoutMs: 180000 })
+  const same = r.code === 0 && (await rev(`refs/remotes/origin/${branch}^{tree}`)) === (await rev('HEAD^{tree}'))
+  if (same) r = await git(['reset', '-q', '--soft', `refs/remotes/origin/${branch}`])
+  if (same && r.code === 0) await git(['branch', '-q', `--set-upstream-to=origin/${branch}`])
+  return { ok: true, oid, local: same && r.code === 0 }
+}
+
+/** The paths that git shows as changed and not committed, of the paths given (the files of setup). */
+export function changedFiles(cli, { root, env, paths }) {
+  return changedPaths((args) => cli('git', ['-C', root, ...args], { cwd: root, env }), paths)
+}
+
+/**
+ * What the last line and the pull request say about the key when it may not be stored. 'left': this run did not store
+ * it (a skipped key check, a no to the store question, a store that failed), and the key steps printed. A deploy without
+ * the key sends nothing, so the app never connects (F-012-153). 'unknown': a rerun, which does not ask for the key.
+ * .uknows/setup.json lists only the files that setup changed, so the rerun cannot tell if an earlier run stored the key.
+ */
+export const KEY_NOTE = {
+  left: {
+    line: 'Your key is not stored yet. Store it before you merge and deploy: run npx @uknows/setup key, or do the key steps above.',
+    pr: 'Your key is not stored yet. Store it before you merge and deploy: run npx @uknows/setup key in the repo, or do the key steps below.',
+  },
+  unknown: {
+    line: 'Setup cannot tell if your key is stored. If it is not stored yet, run npx @uknows/setup key before you merge and deploy.',
+    pr: `Setup cannot tell from ${CLI.manifest} if your key is stored. If it is not stored yet, run npx @uknows/setup key in the repo before you merge and deploy.`,
+  },
+}
+
+/**
+ * The text of the pull request: what it does, the files, and the checklist of what is left. Never the key. key: null when
+ * the key is stored or not asked for, else 'left' or 'unknown' (KEY_NOTE): a line on the key comes first in Left to do.
+ * updates: how the agent stays up to date and why (updates.mjs), 1 paragraph each. Without them (an older record), the
+ * text says what the update bot files in the change do.
+ */
+export function prBody({ services = [], files = [], left = [], done = [], url, environment = null, key = null, logs = true, cloudId = false, updates = [] }) {
+  const names = services.length ? list(services) : 'this app'
+  const dependabot = files.some((f) => /(^|\/)\.github\/workflows\/uknows-updates\.yml$/.test(f))
+  const renovate = files.includes('renovate.json')
+  const hookFiles = files.filter((f) => HOOK_FILES.includes(f.split('/').pop()))
+  return [
+    `Adds OpenTelemetry to ${names}, so ${services.length > 1 ? 'they send' : 'it sends'} ${logs ? 'traces and logs' : 'traces'} to UKNOWS.`,
+    '',
+    ...updates.flatMap((line) => [line, '']),
+    ...(!updates.length && renovate ? ['Adds an update bot too. Renovate proposes the UKNOWS and OpenTelemetry updates in 1 pull request, 3 days after each release, and merges it when your build check passes. Where your branch rules ask for a review, it waits for that review.', ''] : []),
+    ...(!updates.length && dependabot ? ['Adds an update bot too. Dependabot proposes OpenTelemetry updates every day. Each update merges when your build check passes, then deploys. Where your branch rules ask for a review, it waits for that review.', ''] : []),
+    // host.json changes only for Azure Functions (stacks/functions.mjs), the hook files only for its worker hooks.
+    ...(files.some((f) => /(^|\/)host\.json$/.test(f)) ? [FUNCTIONS.pr, ''] : []),
+    ...(hookFiles.length ? [FUNCTIONS.hooks.pr.replace('{files}', hookFiles.join(', ')), '',
+      ...(hookFiles.some((f) => f.endsWith('.py')) ? [FUNCTIONS.hooks.prPython, ''] : [])] : []),
+    ...(cloudId ? [`Your deploy now also sets ${RESOURCE_ATTRIBUTES} with the Azure resource id of the app, so UKNOWS knows which app in Azure the data comes from. Attributes that your app sets there already stay as they are.`, ''] : []),
+    'Made with npx @uknows/setup. To undo it, run npx @uknows/setup remove.',
+    '',
+    '## Files',
+    ...files.map((f) => `- ${f}`),
+    '',
+    '## Left to do',
+    ...(KEY_NOTE[key] ? [KEY_NOTE[key].pr, ''] : []),
+    ...left.map((title) => `- [ ] ${title}`),
+    '- [ ] Merge this pull request and deploy as usual.',
+    url ? `- [ ] ${watchLine([url], environment).replace(/^Then w/, 'W')}` : '- [ ] Watch your app connect in UKNOWS.',
+    '',
+    ...(done.length ? ['## Done', ...done.map((d) => `- [x] ${d}`), ''] : []),
+    'To see the steps again, run npx @uknows/setup --dry-run in the repo.',
+    '',
+  ].join('\n')
+}
+
+/**
+ * The last line: what is left, then the link to the page where the app connects (environment: of the key check). key:
+ * null when the key is stored or not asked for, else 'left' or 'unknown' (KEY_NOTE): the line says it before the merge.
+ */
+export function lastLine({ state, required = 0, urls = [], environment = null, key = null }) {
+  const action = state === 'pr' ? 'Merge the pull request and deploy as usual.'
+    : state === 'pushed' ? 'Open the pull request, merge it and deploy as usual.'
+      : state === 'committed' ? 'Push the branch, open a pull request, merge it and deploy as usual.'
+        : 'Commit, open a pull request, merge it and deploy as usual.'
+  const steps = required ? `Do the ${plural(required, 'step')} above first. ` : ''
+  const stored = KEY_NOTE[key] ? `${KEY_NOTE[key].line} ` : ''
+  return `${steps}${stored}${action} ${watchLine(urls, environment)}`
+}
+
+/**
+ * The questions that a run in a terminal asks after Apply, for the dry run. From the repo and this computer only: no
+ * cloud CLI and no network. Each is {question, after}: after is the question that comes after a no to it. A store
+ * question only where 1 app is known and the run has 1 service (storeAzure). The GitHub secret is a question of its
+ * own when no store on the platform is planned or a workflow reads it already, else it comes after a no.
+ * pr: prFacts of the repo without the network (null or no branch: no pull request question). files: the paths that a
+ * real run commits. services: how many services the run sets up. Returns {questions, hosts}: hosts are the platforms
+ * whose key step a question does, so the dry run can print those steps after the questions, as the steps by hand.
+ */
+export function plannedQuestions({ targets, edits = [], files = [], pr = null, services = 1 }) {
+  const stores = []
+  for (const [host, t] of targets) {
+    if (t.kind === 'aca' || t.kind === 'webapp') {
+      const apps = pickApp(t.apps.map((a) => a.name))
+      if (apps.length !== 1 || services > 1 || (t.kind === 'webapp' && t.slots?.length)) continue
+      const groups = unique(t.groups.map((g) => g.name))
+      stores.push({ host, question: `Store this key on ${apps[0]}${groups.length === 1 ? ` in ${groups[0]}` : ''}? ${AZURE[t.kind].effect} (y/N)` })
+    } else if (t.kind === 'k8s') {
+      const spaces = unique(t.workloads.map((w) => w.namespace))
+      if (spaces.length === 1 && spaces[0]) stores.push({ host, question: `Store this key as the secret ${K8S_SECRET} in the namespace ${spaces[0]}? Pods that start after this get the key. (y/N)` })
+    }
+  }
+  const out = [...stores]
+  const gh = [...targets.values()].find((t) => t.kind === 'github' && t.repo)
+  const hosts = stores.map((q) => q.host)
+  if (gh) {
+    const s = githubSecret(gh.jobs)
+    const question = s.why ? null : s.env === null ? `Store this key as the repository secret ${GITHUB_SECRET} of ${gh.repo}? Every workflow of the repo can read it. (y/N)`
+      : `Store this key as the secret ${GITHUB_SECRET} of its GitHub environment in ${gh.repo}? (y/N)`
+    if (question && (gh.readsKey || !stores.length)) out.push({ question })
+    else if (question) stores.at(-1).after = question
+    if (question) hosts.push('github-actions')
+  }
+  for (const e of edits) out.push({ question: e.question })
+  if (pr?.from && files.length) out.push({ question: prQuestion({ branch: pr.branch, files, pr: Boolean(pr.slug && pr.base), base: pr.base, ahead: pr.ahead }) })
+  return { questions: out, hosts: unique(hosts) }
+}