@uknows/setup 0.1.0 → 0.2.0

package/lib/cloudid.mjs

@@ -0,0 +1,456 @@
+/*
+ * The cloud id of a container app, in the command that deploys it. Each deploy then sets OTEL_RESOURCE_ATTRIBUTES on the
+ * app: cloud.provider, cloud.platform, cloud.region (when known) and cloud.resource_id. With cloud.resource_id UKNOWS
+ * links the data of the app to that exact resource, and the gateway keeps only a keyed hash of it. The replica host
+ * name (host.name) still tells the revisions apart.
+ *
+ * Only where setup knows the exact id: the subscription, resource group and app that the deploy command names itself,
+ * written as the command writes them (a value, a shell variable or a workflow expression), so at deploy time the id is
+ * the one of the app that the command deploys. Never a guess, and never over a value the customer set:
+ *   - the command sets OTEL_RESOURCE_ATTRIBUTES itself: the attributes it lacks go at the end of its value, and its own
+ *     ones stay as they are;
+ *   - --replace-env-vars, or environmentVariables of the deploy action: the pair goes on that list. The list holds every
+ *     variable of the app, so nothing set elsewhere is lost;
+ *   - --set-env-vars or no env option: only when az shows that no app the command can deploy has
+ *     OTEL_RESOURCE_ATTRIBUTES (names only, never values), with 1 container or the one that the command names. The pair
+ *     goes on the --set-env-vars list, never in a second --set-env-vars: az keeps only the last list (az 2.87.0, measured
+ *     22 Oct 2026).
+ * Nothing when a Dockerfile of the services sets OTEL_RESOURCE_ATTRIBUTES (the setting on the app would hide it), and
+ * nothing when the subscription is only in a secret: setup never copies a secret into the settings of an app.
+ * cloud.region only when az found the app and the deploy file names its subscription as a value.
+ */
+import { Doc } from './doc.mjs'
+import { unique } from './ui.mjs'
+
+export const RESOURCE_ATTRIBUTES = 'OTEL_RESOURCE_ATTRIBUTES'
+/** cloud.platform of Container Apps in the OpenTelemetry semantic conventions (1.44.0). */
+export const ACA_PLATFORM = 'azure.container_apps'
+const ACA_TYPE = 'Microsoft.App/containerApps'
+const UPDATE = /\baz\s+containerapp\s+update\b/
+/** A shell word as written: workflow expressions, quoted parts, escapes and plain characters. */
+const WORD = /(?:\$\{\{[^}]*\}\}|"(?:[^"\\]|\\.)*"|'[^']*'|\\.|[^\s"'\\])+/g
+const OPERATOR = /^(?:&&|\|\||;|\||&|[0-9]?>.*|<.*|#.*)$/
+const OPTION = /^--?[A-Za-z]/
+const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+const WHY = 'Tell UKNOWS which app in Azure the data comes from.'
+/** facts for a dry run in a terminal: the plan of a real run, as if az showed no OTEL_RESOURCE_ATTRIBUTES on the app. */
+export const PREDICT = 'predict'
+
+/** The attributes for an app: [key, value] pairs, the region only when known. */
+export function cloudAttributes({ subscription, group, app, region = null }) {
+  return [['cloud.provider', 'azure'], ['cloud.platform', ACA_PLATFORM], ...(region ? [['cloud.region', region]] : []),
+    ['cloud.resource_id', `/subscriptions/${subscription}/resourceGroups/${group}/providers/${ACA_TYPE}/${app}`]]
+}
+
+/**
+ * value with the attributes of ours that it lacks at its end. Its own keys and values stay as they are. null when the
+ * value is not a plain list of key=value pairs (a variable, an empty pair), so setup cannot add to it safely.
+ * '' when nothing is missing.
+ */
+export function mergeAttributes(value, ours) {
+  const items = value.replace(/,+\s*$/, '').split(',')
+  if (!items.every((item) => /^\s*[\w.-]+\s*=\s*\S/.test(item))) return null
+  const keys = new Set(items.map((item) => item.slice(0, item.indexOf('=')).trim()))
+  return ours.filter(([key]) => !keys.has(key)).map(([key, v]) => `${key}=${v}`).join(',')
+}
+
+/** The text between matching quotes, or the word itself when it has no quotes. null when the quotes are mixed. */
+function unquote(text) {
+  const m = /^(["'])(.*)\1$/.exec(text)
+  if (m) return { bare: m[2], quote: m[1] }
+  return /["']/.test(text) ? null : { bare: text, quote: '' }
+}
+
+/**
+ * A name as the command writes it, as text to put inside "...": a value, a shell variable ($NAME or ${NAME}, not in a
+ * workflow input) or a workflow expression that is not a secret. null for anything else.
+ */
+function nameText(word, { shell = true } = {}) {
+  const u = unquote(word)
+  if (!u) return null
+  if (/^[A-Za-z0-9][\w.()-]*$/.test(u.bare)) return { text: u.bare, literal: u.bare }
+  const variable = /^\$(?:\{([A-Za-z_]\w*)\}|([A-Za-z_]\w*))$/.exec(u.bare)
+  if (variable && shell && u.quote !== "'") return { text: `\${${variable[1] ?? variable[2]}}`, ref: variable[1] ?? variable[2] }
+  const expression = /^\$\{\{\s*([A-Za-z_][\w.-]*)\s*\}\}$/.exec(u.bare)
+  if (expression && !/^secrets\./.test(expression[1])) return { text: `\${{ ${expression[1]} }}`, ref: /^env\.(\w+)$/.exec(expression[1])?.[1] ?? null }
+  if (expression) return { secret: true }
+  return null
+}
+
+/** The variables that a file sets for itself (KEY: value in YAML, export KEY=value or KEY=value in a script). */
+function fileVariables(doc) {
+  const vars = new Map()
+  for (const line of doc.lines) {
+    const m = /^\s*([A-Z][A-Z0-9_]*)\s*:\s*(.+?)\s*$/.exec(line) ?? /^\s*(?:export\s+)?([A-Z][A-Z0-9_]*)=(\S+)\s*$/.exec(line)
+    if (m && !vars.has(m[1])) vars.set(m[1], m[2].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, ''))
+  }
+  return vars
+}
+
+/** The value that a name has in the file: itself, or the value of the variable it names (3 hops at most). null if unknown. */
+function literalOf(name, vars) {
+  if (!name || name.secret) return null
+  if (name.literal) return name.literal
+  let ref = name.ref
+  for (let hop = 0; hop < 3 && ref; hop++) {
+    const v = vars.get(ref)
+    if (v === undefined) return null
+    if (/^[A-Za-z0-9][\w.()-]*$/.test(v)) return v
+    ref = /^\$\{\{\s*env\.(\w+)\s*\}\}$/.exec(v)?.[1] ?? /^\$\{?([A-Za-z_]\w*)\}?$/.exec(v)?.[1] ?? null
+  }
+  return null
+}
+
+/** The rows of the job that row i is in (a GitHub workflow), as text. null outside a job. */
+function jobText(doc, i) {
+  const indent = (l) => /^\s*/.exec(l)[0].length
+  let top = i
+  while (top > 0 && !/^\s*steps\s*:/.test(doc.get(top))) top--
+  if (!/^\s*steps\s*:/.test(doc.get(top) ?? '')) return null
+  let job = top
+  while (job > 0 && !(doc.get(job).trim() && indent(doc.get(job)) < indent(doc.get(top)))) job--
+  let end = top + 1
+  while (end < doc.length && (!doc.get(end).trim() || indent(doc.get(end)) > indent(doc.get(job)))) end++
+  return doc.lines.slice(job, end).join('\n')
+}
+
+/** The subscription that azure/login signs in to in the job of row i: its subscription-id input. */
+function loginSubscription(doc, i) {
+  const job = jobText(doc, i)
+  const raw = job ? /^\s*subscription-id\s*:\s*(.+?)\s*(?:#.*)?$/m.exec(job)?.[1] : null
+  return raw ? nameText(raw, { shell: false }) : null
+}
+
+/** Each az containerapp update command of a file: its first and last row and its words, with their rows and columns. */
+export function updateCommands(doc) {
+  const out = []
+  for (let i = 0; i < doc.length; i++) {
+    if (/^\s*#/.test(doc.get(i)) || !UPDATE.test(doc.get(i))) continue
+    let end = i
+    while (end + 1 < doc.length && /\\\s*$/.test(doc.get(end))) end++
+    const words = []
+    for (let row = i; row <= end; row++) {
+      const text = doc.get(row).replace(/\\\s*$/, '')
+      for (const m of text.matchAll(WORD)) words.push({ text: m[0], row, start: m.index, end: m.index + m[0].length })
+    }
+    const at = words.findIndex((w, k) => w.text === 'az' && words[k + 1]?.text === 'containerapp' && words[k + 2]?.text === 'update')
+    if (at >= 0) {
+      const stop = words.findIndex((w, k) => k > at && OPERATOR.test(w.text))
+      out.push({ first: i, last: end, rows: doc.lines.slice(i, end + 1), words: words.slice(at, stop < 0 ? words.length : stop) })
+    }
+    i = end
+  }
+  return out
+}
+
+/** The options of a command: name -> {word, values}. --name=value counts too. */
+function optionsOf(words) {
+  const options = new Map()
+  for (let k = 3; k < words.length; k++) {
+    const w = words[k]
+    const eq = /^(--?[A-Za-z][\w-]*)=(.*)$/.exec(w.text)
+    if (eq) {
+      const start = w.start + eq[1].length + 1
+      options.set(eq[1], { word: w, values: [{ ...w, text: eq[2], start }] })
+      continue
+    }
+    if (!OPTION.test(w.text)) continue
+    const values = []
+    let j = k + 1
+    while (j < words.length && !OPTION.test(words[j].text)) values.push(words[j++])
+    options.set(w.text, { word: w, values })
+    k = j - 1
+  }
+  return options
+}
+
+/**
+ * The deploy steps of container apps in the deploy files that the hosts name: each az containerapp update command, and
+ * each deploy action with environmentVariables on 1 line. Each spot: {file, row, kind ('az' or 'action'), names
+ * ({subscription, group, app, container} as nameText), list ('replace', 'set' or null), why (when setup cannot add the
+ * id there)}. Read only.
+ */
+export function cloudIdSpots(view, hosts) {
+  const files = unique((hosts ?? []).filter((h) => h.id === 'azure-container-apps').flatMap((h) => h.evidence ?? [])
+    .filter((e) => e.what === 'Deploy step runs az containerapp' || e.what === 'Azure Container Apps deploy action').map((e) => e.file))
+    .filter((f) => !f.startsWith('../') && !/\.ps1$/i.test(f))
+  const spots = []
+  for (const file of files) {
+    let text = null
+    try { text = view.read(file) } catch { text = null }
+    if (text === null) continue
+    const doc = new Doc(text)
+    const vars = fileVariables(doc)
+    for (const c of updateCommands(doc)) {
+      const options = optionsOf(c.words)
+      const get = (...names) => names.map((n) => options.get(n)).find(Boolean) ?? null
+      const one = (option) => (option && option.values.length === 1 ? nameText(option.values[0].text) : null)
+      const names = { subscription: one(get('--subscription')) ?? loginSubscription(doc, c.first), group: one(get('--resource-group', '-g')),
+        app: one(get('--name', '-n')), container: one(get('--container-name')) }
+      const replace = get('--replace-env-vars'), set = get('--set-env-vars')
+      const why = get('--ids') ? 'ids' : replace && set ? 'both-lists' : names.subscription?.secret ? 'secret-subscription'
+        : !names.subscription ? 'no-subscription' : !names.group || names.group.secret ? 'no-group' : !names.app || names.app.secret ? 'no-app' : null
+      spots.push({ file, row: c.first, kind: 'az', command: c, names, vars, list: replace ? 'replace' : set ? 'set' : null, why,
+        app: literalOf(names.app, vars), group: literalOf(names.group, vars), subscription: literalOf(names.subscription, vars) })
+    }
+    for (let i = 0; i < doc.length; i++) {
+      const m = /^(\s*environmentVariables\s*:\s*)(.*?)((?:\s+#.*)?)\s*$/.exec(doc.get(i))
+      if (!m || /^\s*#/.test(doc.get(i))) continue
+      const step = stepOf(doc, i)
+      if (!step.some((l) => /^\s*(?:-\s+)?uses\s*:\s*['"]?azure\/container-apps-deploy-action@/.test(l))) continue
+      const input = (key) => { const raw = step.map((l) => new RegExp(`^\\s*${key}\\s*:\\s*(.+?)\\s*(?:#.*)?$`).exec(l)?.[1]).find(Boolean); return raw ? nameText(raw, { shell: false }) : null }
+      const names = { subscription: loginSubscription(doc, i), group: input('resourceGroup'), app: input('containerAppName'), container: null }
+      const value = m[2]
+      const why = !value || /^[|>]/.test(value) ? 'value-form' : names.subscription?.secret ? 'secret-subscription' : !names.subscription ? 'no-subscription'
+        : !names.group || names.group.secret ? 'no-group' : !names.app || names.app.secret ? 'no-app' : null
+      spots.push({ file, row: i, kind: 'action', names, vars, list: 'replace', why,
+        app: literalOf(names.app, vars), group: literalOf(names.group, vars), subscription: literalOf(names.subscription, vars) })
+    }
+  }
+  return spots
+}
+
+/** The rows of the workflow step that row i is in. */
+function stepOf(doc, i) {
+  const indent = (l) => /^\s*/.exec(l)[0].length
+  let start = i
+  while (start >= 0 && !/^\s*-\s/.test(doc.get(start))) start--
+  if (start < 0) return []
+  const pad = indent(doc.get(start))
+  const rows = [doc.get(start)]
+  for (let j = start + 1; j < doc.length && (!doc.get(j).trim() || indent(doc.get(j)) > pad); j++) rows.push(doc.get(j))
+  return rows
+}
+
+/** True when the spot needs az to show that the app has no OTEL_RESOURCE_ATTRIBUTES of its own. */
+const needsAzure = (spot) => !spot.why && spot.kind === 'az' && spot.list !== 'replace' && !setsAttributes(spot)
+
+/** The value word of OTEL_RESOURCE_ATTRIBUTES on the env list of an az spot, or null. */
+function attributesWord(spot) {
+  if (spot.kind !== 'az' || !spot.list) return null
+  const options = optionsOf(spot.command.words)
+  const list = options.get(spot.list === 'replace' ? '--replace-env-vars' : '--set-env-vars')
+  return list?.values.find((w) => (unquote(w.text)?.bare ?? w.text.replace(/["']/g, '')).startsWith(`${RESOURCE_ATTRIBUTES}=`)) ?? null
+}
+const setsAttributes = (spot) => Boolean(attributesWord(spot))
+
+/**
+ * The apps that az must look up for the spots, as {app, group, subscription}: group and subscription null when the
+ * deploy file does not name them as values.
+ */
+export function cloudIdLookups(spots) {
+  const out = []
+  for (const spot of spots.filter((s) => !s.why && s.app && (needsAzure(s) || s.subscription))) {
+    if (!out.some((x) => x.app === spot.app && x.group === spot.group && x.subscription === spot.subscription)) {
+      out.push({ app: spot.app, group: spot.group, subscription: spot.subscription })
+    }
+  }
+  return out
+}
+const factKey = (x) => `${x.app}|${x.group}|${x.subscription}`
+
+/** fn for each item, at most n at a time, in order. */
+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 parse = (text) => { try { return JSON.parse(text) } catch { return null } }
+
+/**
+ * What az shows of the container apps that the deploy commands name, read only. For each lookup: the apps of that name
+ * (in that group and subscription when the file names them) in the subscriptions that az can see. Only when that is 1
+ * app, az shows its containers with the names of their settings (never values), in the subscription of that app, as
+ * the key store does. Map of lookup -> {found: [{sub, group, name, id, location}], app: the 1 app with containers, or
+ * null}. null when az is not installed or not signed in. Every call but az account list names the subscription.
+ */
+export async function cloudIdFacts(cli, { root, env }, lookups) {
+  if (!lookups.length) return null
+  const az = (args) => cli('az', [...args, '--only-show-errors'], { cwd: root, env, timeoutMs: 60000 })
+  const accounts = await az(['account', 'list', '--query', "[?state=='Enabled'].{id:id, name:name}", '-o', 'json'])
+  if (accounts.error === 'missing' || accounts.code !== 0) return null
+  const subs = (parse(accounts.stdout) ?? []).filter((s) => typeof s?.id === 'string' && GUID.test(s.id))
+  if (!subs.length) return null
+  const facts = new Map()
+  for (const lookup of lookups) {
+    const { app, group, subscription } = lookup
+    const where = subscription ? subs.filter((s) => s.id.toLowerCase() === subscription.toLowerCase()) : subs
+    const answers = await inTurn(where, 4, (sub) => az(['resource', 'list', '--subscription', sub.id, '--name', app, '--resource-type', ACA_TYPE,
+      '--query', '[].{id:id, name:name, resourceGroup:resourceGroup, location:location}', '-o', 'json']))
+    if (answers.some((a) => a.code !== 0)) { facts.set(factKey(lookup), null); continue }
+    const found = []
+    where.forEach((sub, i) => {
+      for (const row of parse(answers[i].stdout) ?? []) {
+        if (typeof row?.name !== 'string' || row.name.toLowerCase() !== app.toLowerCase() || typeof row.resourceGroup !== 'string') continue
+        if (group && row.resourceGroup.toLowerCase() !== group.toLowerCase()) continue
+        found.push({ sub: sub.id, group: row.resourceGroup, name: row.name, id: row.id, location: typeof row.location === 'string' ? row.location : null })
+      }
+    })
+    let one = null
+    if (found.length === 1) {
+      const f = found[0]
+      const shown = await az(['containerapp', 'show', '--subscription', f.sub, '-g', f.group, '-n', f.name,
+        '--query', 'properties.template.containers[].{name:name, env:env[].name}', '-o', 'json'])
+      const containers = shown.code === 0 ? parse(shown.stdout) : null
+      if (Array.isArray(containers)) one = { ...f, containers: containers.map((c) => ({ name: String(c?.name ?? ''), env: Array.isArray(c?.env) ? c.env.map(String) : [] })) }
+    }
+    facts.set(factKey(lookup), { found, app: one })
+  }
+  return facts
+}
+
+/**
+ * Whether setup may set the variable with --set-env-vars on the apps that az found for a spot. Each app must lack it in
+ * the container that the command updates. {ok, apps} or {ok: false, why}.
+ */
+function azureAllows(spot, facts) {
+  if (facts === PREDICT) return spot.app ? { ok: true, predicted: true } : { ok: false, why: 'not-checked' }
+  const fact = facts?.get?.(factKey(spot))
+  if (!fact) return { ok: false, why: 'not-checked' }
+  if (!fact.found.length) return { ok: false, why: 'not-found' }
+  if (fact.found.length > 1) return { ok: false, why: 'not-unique' }
+  if (!fact.app) return { ok: false, why: 'not-checked' }
+  const container = literalOf(spot.names.container, spot.vars)
+  if (spot.names.container && !container) return { ok: false, why: 'container' }
+  const c = container ? fact.app.containers.find((x) => x.name === container) : fact.app.containers.length === 1 ? fact.app.containers[0] : null
+  if (!c) return { ok: false, why: 'container' }
+  if (c.env.includes(RESOURCE_ATTRIBUTES)) return { ok: false, why: 'has-own' }
+  return { ok: true }
+}
+
+/** The region of the app, when the deploy file names its subscription as a value and az found that 1 app. */
+function regionOf(spot, facts) {
+  if (!spot.subscription || !spot.app || facts === PREDICT) return null
+  const found = facts?.get?.(factKey(spot))?.found ?? []
+  return found.length === 1 && /^[a-z0-9]+$/.test(found[0].location ?? '') ? found[0].location : null
+}
+
+/** The az containerapp update command whose first row is row, or null. */
+export function updateCommandAt(doc, row) {
+  return updateCommands(doc).find((c) => c.first === row) ?? null
+}
+
+/**
+ * The change that puts pair (its text as the shell reads it) on the --set-env-vars list of a command: after the last
+ * value of the list, never in a second --set-env-vars (az keeps only the last list). A command with no list gets one:
+ * on a row of its own after the first row when the command goes over several rows, else after update.
+ */
+export function setEnvChange(command, pair) {
+  const list = optionsOf(command.words).get('--set-env-vars')
+  if (list) {
+    const after = list.values.at(-1) ?? list.word
+    return { row: after.row, start: after.end, end: after.end, text: ` ${pair}` }
+  }
+  if (command.last > command.first && command.rows[1] !== undefined) {
+    return { insertAfter: command.first, text: `${/^\s*/.exec(command.rows[1])[0]}--set-env-vars ${pair} \\` }
+  }
+  const update = command.words[2]
+  return { row: update.row, start: update.end, end: update.end, text: ` --set-env-vars ${pair}` }
+}
+
+/** Apply changes to a Doc, from the end, so the rows and columns of the ones before stay right. */
+export function applyChanges(doc, changes) {
+  const rowOf = (c) => (c.insertAfter ?? c.row)
+  for (const c of [...changes].sort((a, b) => rowOf(b) - rowOf(a) || (b.start ?? 0) - (a.start ?? 0))) {
+    if (c.insertAfter !== undefined) { doc.insert(c.insertAfter + 1, c.text); continue }
+    const line = doc.get(c.row)
+    doc.set(c.row, `${line.slice(0, c.start)}${c.text}${line.slice(c.end)}`)
+  }
+}
+
+/** A pair for the shell: "OTEL_RESOURCE_ATTRIBUTES=...". */
+const shellPair = (attributes) => `"${RESOURCE_ATTRIBUTES}=${attributes.map(([k, v]) => `${k}=${v}`).join(',')}"`
+
+/** The word with the missing attributes added inside it, keeping its quotes. null when setup cannot add them safely. */
+function grownWord(text, missing) {
+  if (/^[^"']*"[^"]*"$/.test(text)) return `${text.slice(0, -1)},${missing}"`
+  if (!/["'\\]/.test(text)) return `"${text},${missing}"`
+  if (/^[^"']*'[^']*'$/.test(text)) return `${text}",${missing}"`
+  return null
+}
+
+/**
+ * The edits that add the cloud id to the deploy steps of container apps, and 1 summary line each. dockerfiles: the
+ * Dockerfiles of the services; when one sets OTEL_RESOURCE_ATTRIBUTES, nothing changes. Returns {edits, summary, skipped}:
+ * skipped lists {file, row, why} for each deploy step that keeps its text.
+ */
+export function cloudIdPlan(view, spots, facts, { dockerfiles = [] } = {}) {
+  const out = { edits: [], summary: [], skipped: [] }
+  const own = dockerfiles.some((file) => { try { return new RegExp(`\\b${RESOURCE_ATTRIBUTES}\\b`).test(view.read(file) ?? '') } catch { return false } })
+  const byFile = new Map()
+  for (const spot of spots) {
+    const skip = (why) => out.skipped.push({ file: spot.file, row: spot.row + 1, why })
+    if (own) { skip('dockerfile-sets-it'); continue }
+    if (spot.why) { skip(spot.why); continue }
+    const attributes = cloudAttributes({ subscription: spot.names.subscription.text, group: spot.names.group.text, app: spot.names.app.text, region: regionOf(spot, facts) })
+    let change = null
+    if (spot.kind === 'action') {
+      change = actionChange(view, spot, attributes)
+      if (change?.none) continue
+    }
+    else {
+      const word = attributesWord(spot)
+      if (word) {
+        const value = (unquote(word.text)?.bare ?? word.text.replace(/["']/g, '')).slice(RESOURCE_ATTRIBUTES.length + 1)
+        const missing = mergeAttributes(value, attributes)
+        if (missing === null) { skip('own-value'); continue }
+        if (missing === '') continue
+        const grown = grownWord(word.text, missing)
+        if (!grown) { skip('own-value'); continue }
+        change = { row: word.row, start: word.start, end: word.end, text: grown }
+      } else if (spot.list === 'replace') {
+        const list = optionsOf(spot.command.words).get('--replace-env-vars')
+        const after = list.values.at(-1) ?? list.word
+        change = { row: after.row, start: after.end, end: after.end, text: ` ${shellPair(attributes)}` }
+      } else {
+        const allowed = azureAllows(spot, facts)
+        if (!allowed.ok) { skip(allowed.why); continue }
+        change = { ...setEnvChange(spot.command, shellPair(attributes)), predicted: Boolean(allowed.predicted) }
+      }
+    }
+    if (!change) { skip('value-form'); continue }
+    if (!byFile.has(spot.file)) byFile.set(spot.file, [])
+    byFile.get(spot.file).push({ ...change, spot })
+  }
+  for (const [file, changes] of byFile) {
+    const before = view.read(file)
+    const doc = new Doc(before)
+    applyChanges(doc, changes)
+    const after = doc.toString()
+    if (after === before) continue
+    out.edits.push({ file, before, after, why: WHY })
+    for (const c of changes) {
+      const app = c.spot.app ? `the container app ${c.spot.app}` : 'the container app that it deploys'
+      const first = c.predicted ? ` A real run first checks in Azure that the app has no ${RESOURCE_ATTRIBUTES} of its own.` : ''
+      out.summary.push(`${file} line ${c.spot.row + 1}: each deploy sets ${RESOURCE_ATTRIBUTES} with the Azure resource id of ${app}, so UKNOWS knows which app in Azure the data comes from.${first}`)
+    }
+  }
+  return out
+}
+
+/** The change for environmentVariables of the deploy action: the pair at the end of its list, or the missing attributes in it. */
+function actionChange(view, spot, attributes) {
+  const doc = new Doc(view.read(spot.file))
+  const line = doc.get(spot.row)
+  const m = /^(\s*environmentVariables\s*:\s*)(.*?)((?:\s+#.*)?)\s*$/.exec(line)
+  if (!m) return null
+  const quoted = /^(["'])(.*)\1$/.exec(m[2])
+  if (!quoted && /["']/.test(m[2])) return null
+  const inner = quoted ? quoted[2] : m[2]
+  const begin = m[1].length + (quoted ? 1 : 0)
+  // The pairs of the list, with their columns in the line.
+  const pairs = [...inner.matchAll(/\S+/g)].map((p) => ({ text: p[0], start: begin + p.index, end: begin + p.index + p[0].length }))
+  const own = pairs.find((p) => p.text.startsWith(`${RESOURCE_ATTRIBUTES}=`))
+  const plain = attributes.map(([k, v]) => `${k}=${v}`).join(',')
+  if (own) {
+    const missing = mergeAttributes(own.text.slice(RESOURCE_ATTRIBUTES.length + 1), attributes)
+    if (missing === null) return null
+    if (missing === '') return { none: true }
+    return { row: spot.row, start: own.end, end: own.end, text: `,${missing}` }
+  }
+  const end = begin + inner.length
+  return { row: spot.row, start: end, end, text: `${inner ? ' ' : ''}${RESOURCE_ATTRIBUTES}=${plain}` }
+}

package/lib/code.mjs

@@ -0,0 +1,147 @@
+/*
+ * Read and edit app source code as text, for the few lines the Azure Monitor mode adds. Strings and comments are
+ * masked first, so a search finds code only. Every edit keeps the other lines byte for byte (doc.mjs), and the
+ * caller refuses anything that is not plain: then the code goes into a printed step instead.
+ */
+import { Doc } from './doc.mjs'
+
+/** Python comments and string literals (any prefix, single, double and triple quotes). */
+const PY_TOKEN = /#[^\r\n]*|(?<![\w])[rRbBuUfFtT]{0,2}(?:'''[\s\S]*?'''|"""[\s\S]*?"""|'(?:\\[\s\S]|[^'\\\r\n])*'|"(?:\\[\s\S]|[^"\\\r\n])*")/g
+/** C# comments, string and char literals: raw """...""", verbatim @"...", interpolated $"..." and plain. */
+const CS_TOKEN = /\/\/[^\r\n]*|\/\*[\s\S]*?\*\/|\$*"""[\s\S]*?"""|(?:@\$?|\$@)"(?:""|[^"])*"|\$?"(?:\\.|[^"\\\r\n])*"|'(?:\\.|[^'\\\r\n])+'/g
+
+/** The text with every comment and string replaced by spaces. Line breaks stay, so offsets and lines still match. */
+export const maskPython = (text) => mask(text, PY_TOKEN)
+export const maskCsharp = (text) => mask(text, CS_TOKEN)
+
+function mask(text, re) {
+  return text.replace(new RegExp(re.source, 'g'), (m) => m.replace(/[^\r\n]/g, ' '))
+}
+
+const lineAt = (text, index) => text.slice(0, index).split('\n').length - 1
+
+/** The offset of the bracket that closes the one at open, in masked text. -1 when there is none. */
+function closing(masked, open) {
+  let depth = 0
+  for (let i = open; i < masked.length; i++) {
+    const c = masked[i]
+    if (c === '(' || c === '[' || c === '{') depth++
+    else if (c === ')' || c === ']' || c === '}') { if (--depth === 0) return i }
+  }
+  return -1
+}
+
+/** Bracket depth at an offset of masked text. */
+function depthAt(masked, end) {
+  let depth = 0
+  for (let i = 0; i < end; i++) {
+    const c = masked[i]
+    if (c === '(' || c === '[' || c === '{') depth++
+    else if (c === ')' || c === ']' || c === '}') depth = Math.max(0, depth - 1)
+  }
+  return depth
+}
+
+/**
+ * Calls of a Python function in code, not its def or a mention in a string or comment.
+ * @returns {{index: number, line: number}[]} index of the first character of the call (with its module prefix), 0-based line
+ */
+export function pythonCalls(text, name) {
+  const masked = maskPython(text)
+  const re = new RegExp(`(^|[^\\w.])((?:[A-Za-z_]\\w*\\s*\\.\\s*)*)${name}\\s*\\(`, 'g')
+  const out = []
+  for (const m of masked.matchAll(re)) {
+    const index = m.index + m[1].length
+    if (/\bdef\s+$/.test(masked.slice(Math.max(0, index - 20), index))) continue
+    out.push({ index, line: lineAt(text, index) })
+  }
+  return out
+}
+
+/**
+ * The statement of 1 call, when it is a whole statement on its own: only indentation (and an optional
+ * `name =`) before it, nothing but a comment after its closing parenthesis, no `;`, no `\` and no open
+ * bracket around it.
+ * @returns {{ok: true, start: number, end: number, indent: string} | {ok: false, reason: string}}  0-based lines.
+ */
+export function pythonStatement(text, call) {
+  const masked = maskPython(text)
+  const lineStart = masked.lastIndexOf('\n', call.index - 1) + 1
+  const before = masked.slice(lineStart, call.index)
+  if (!/^[ \t]*(?:[A-Za-z_]\w*(?:\s*:\s*[\w.[\], ]+)?\s*=\s*)?$/.test(before)) {
+    return { ok: false, reason: before.includes(';') ? 'a ; is on its line' : /:\s*$/.test(before.trim()) || /^\s*(if|elif|else|for|while|with|try|except|finally)\b/.test(before) ? 'it is on the same line as an if or another statement' : 'it is part of a longer statement' }
+  }
+  const prev = masked.slice(0, Math.max(0, lineStart - 1)).replace(/[ \t\r]+$/, '')
+  if (prev.endsWith('\\')) return { ok: false, reason: 'the line before it ends with \\' }
+  if (depthAt(masked, lineStart) > 0) return { ok: false, reason: 'it is inside brackets' }
+  const open = masked.indexOf('(', call.index)
+  const close = closing(masked, open)
+  if (close < 0) return { ok: false, reason: 'its closing parenthesis is missing' }
+  const lineEnd = masked.indexOf('\n', close)
+  const after = masked.slice(close + 1, lineEnd < 0 ? masked.length : lineEnd)
+  if (after.trim()) return { ok: false, reason: after.includes(';') ? 'a ; follows it' : after.includes('\\') ? 'its line ends with \\' : 'more code follows it on the same line' }
+  return { ok: true, start: lineAt(text, call.index), end: lineAt(text, close), indent: /^[ \t]*/.exec(text.slice(lineStart))[0] }
+}
+
+/**
+ * Insert a Python block after a statement, indented to it. At module level it gets 2 blank lines before it and
+ * before its last line (the call), as PEP 8 and the formatters want. In a function or block it gets 1.
+ * block: the docs text, whose last line is the call. quote: '"' or "'".
+ */
+export function insertPythonBlock(text, statement, block, quote = '"') {
+  const doc = new Doc(text)
+  const lines = block.split('\n')
+  const call = lines.pop()
+  while (lines.length && !lines.at(-1).trim()) lines.pop()
+  const gap = statement.indent ? 1 : 2
+  const fix = (line) => (quote === "'" ? line.replace(/"/g, "'") : line)
+  const indented = (line) => (line.trim() ? statement.indent + fix(line) : '')
+  doc.insert(statement.end + 1, ...Array(gap).fill(''), ...lines.map(indented), ...Array(gap).fill(''), indented(call))
+  return doc.toString()
+}
+
+/**
+ * The 1 statement `var builder = WebApplication.CreateBuilder(...);` of a C# file, with the variable name.
+ * @returns {{ok: true, end: number, indent: string, name: string} | {ok: false, reason: string}}
+ */
+export function csharpBuilder(text) {
+  const masked = maskCsharp(text)
+  const hits = [...masked.matchAll(/WebApplication\s*\.\s*Create(?:Slim)?Builder\s*\(/g)]
+  if (hits.length !== 1) return { ok: false, reason: hits.length ? `it calls WebApplication.CreateBuilder ${hits.length} times` : 'it does not call WebApplication.CreateBuilder' }
+  const lineStart = masked.lastIndexOf('\n', hits[0].index - 1) + 1
+  const head = /^([ \t]*)(?:var|WebApplicationBuilder)\s+([A-Za-z_]\w*)\s*=\s*$/.exec(masked.slice(lineStart, hits[0].index))
+  if (!head) return { ok: false, reason: 'the builder is not set in a plain statement' }
+  const close = closing(masked, masked.indexOf('(', hits[0].index))
+  const semi = close < 0 ? -1 : masked.indexOf(';', close)
+  if (semi < 0 || masked.slice(close + 1, semi).trim()) return { ok: false, reason: 'the statement does not end after the call' }
+  const lineEnd = masked.indexOf('\n', semi)
+  if (masked.slice(semi + 1, lineEnd < 0 ? masked.length : lineEnd).trim()) return { ok: false, reason: 'more code follows it on the same line' }
+  return { ok: true, end: lineAt(text, semi), indent: head[1], name: head[2] }
+}
+
+/**
+ * Add a using directive in sorted order (System namespaces first, as dotnet format does), or at the top when the
+ * file has none. Returns the text unchanged when the directive is there.
+ */
+export function addUsing(text, directive) {
+  const ns = /^using\s+([\w.]+)\s*;$/.exec(directive)?.[1]
+  const doc = new Doc(text)
+  const usings = []
+  for (let i = 0; i < doc.length; i++) {
+    const m = /^using\s+([\w.]+)\s*;\s*$/.exec(doc.get(i))
+    if (m) usings.push({ i, ns: m[1] })
+    else if (doc.get(i).trim() && !/^\s*(\/\/|#|global\s+using\b|using\s+(static\s|\w+\s*=))/.test(doc.get(i))) break
+  }
+  if (usings.some((u) => u.ns === ns) || new RegExp(`^\\s*global\\s+using\\s+${ns.replace(/\./g, '\\.')}\\s*;`, 'm').test(text)) return text
+  if (!usings.length) {
+    // At the first line of code, after a file header comment.
+    const first = doc.find((line) => line.trim() && !/^\s*\/\//.test(line))
+    doc.insert(Math.max(0, first), directive, '')
+    return doc.toString()
+  }
+  const key = (name) => [/^System(\.|$)/.test(name) ? 0 : 1, name]
+  const less = (a, b) => { const [x, y] = [key(a), key(b)]; return x[0] !== y[0] ? x[0] < y[0] : x[1].localeCompare(y[1], 'en', { sensitivity: 'base' }) < 0 }
+  const next = usings.find((u) => less(ns, u.ns))
+  doc.insert(next ? next.i : usings.at(-1).i + 1, directive)
+  return doc.toString()
+}