@uknows/setup 0.0.0-stage → 0.2.0

package/lib/signin.mjs

@@ -0,0 +1,259 @@
+/*
+ * Sign in from the terminal. When setup runs in a terminal and has no key, it asks UKNOWS for a sign-in link, opens
+ * the browser, and waits while the person signs in and picks the workspace and the environment. The key then comes
+ * to setup by itself: nobody creates, shows, copies or pastes it.
+ *
+ *   1. POST {app}/api/v1/cli/links {client, version, secretHash, app?}: 201 {linkId, userCode, verificationUrl,
+ *      expiresIn, interval}. secretHash is the base64url SHA-256 of a device secret: 32 random bytes that only this
+ *      process holds, in memory. So only this process can collect the key.
+ *   2. POST {app}/api/v1/cli/links/{linkId}/token {deviceSecret}, every interval seconds: 202 waiting, 200 the key,
+ *      403 cancelled in the browser, 410 expired, 429 slow down (Retry-After).
+ *
+ * A UKNOWS without these routes answers the links request with 404 or 405, or with 401 when its sign-in check runs
+ * before its routes (a test copy of UKNOWS older than this sign-in does). The links route itself needs no sign-in, so
+ * all 3 mean the same: this UKNOWS cannot make a sign-in link, and setup asks for the key instead. 5xx answers and
+ * network errors are failures: setup tries again, then says what went wrong.
+ *
+ * The key and the device secret never print and are never written anywhere. A pipeline, --yes, --json and a run
+ * without a terminal never start a sign-in (engine.mjs decides, before it calls signIn).
+ */
+import { createHash, randomBytes } from 'node:crypto'
+import { request } from './check.mjs'
+import { CLI } from './contract.mjs'
+import { VERSION } from './manifest.mjs'
+import { list } from './ui.mjs'
+
+export const LINKS_PATH = '/api/v1/cli/links'
+export const CLIENT = '@uknows/setup'
+/** The answers of a UKNOWS that has no links route: it cannot make a sign-in link, so the person pastes the key. */
+export const NO_LINKS_STATUS = new Set([401, 404, 405])
+/** Network errors and 5xx answers in a row before setup says that it cannot reach UKNOWS. */
+const MAX_FAILURES = 5
+const LOCAL = new Set(['localhost', '127.0.0.1', '[::1]'])
+
+/** The clock of a real run. Tests pass one whose time moves only when something sleeps. */
+export const REAL_CLOCK = {
+  now: () => Date.now(),
+  sleep(ms) {
+    let timer
+    const done = new Promise((resolve) => { timer = setTimeout(resolve, Math.max(0, ms)) })
+    done.cancel = () => clearTimeout(timer)
+    return done
+  },
+}
+
+/** base64url of the SHA-256 of the device secret: what UKNOWS keeps, so only this process can collect the key. */
+export const secretHash = (secret) => createHash('sha256').update(secret).digest('base64url')
+
+/** The words of the sign-in. Exported for the tests and the README. */
+export const SIGN_IN = {
+  opening: 'Sign in to UKNOWS to connect this app. Opening your browser...',
+  noBrowser: 'Sign in to UKNOWS to connect this app. Open this link in a browser:',
+  code: (code) => `Your code: ${code} (check the browser shows the same code)`,
+  keys: 'Press Enter to open the browser again, p to paste a key instead, or Ctrl+C to stop.',
+  waitingPlain: 'Waiting for you to sign in in the browser. The link works for {minutes}.',
+  waiting: 'Waiting for you to sign in... {left} left',
+  slow: ' (UKNOWS is slow to answer, still trying)',
+  signedIn: 'Signed in.',
+  denied: 'The sign-in was cancelled in the browser.',
+  expired: 'The sign-in link expired.',
+  noLinks: (host) => `${host} cannot make a sign-in link, so paste your key instead.`,
+  /** Sign-in is off: a test address is set (names: the settings that are set), but the app address of that UKNOWS is not. */
+  noApp: (names) => [`Setup cannot sign you in from this terminal: ${list(names)} ${names.length > 1 ? 'are' : 'is'} set, but ${CLI.appEnv} is not.`,
+    `To sign in, set ${CLI.appEnv} to the app address of your test copy of UKNOWS, for example ${CLI.appEnv}=https://app-test.example.com, and run setup again. For now, paste your key.`],
+}
+
+/**
+ * Sign in, and come back with the key. Returns one of:
+ *   {approved: true, key, workspace: {id, name}, environment, environmentLabel, keyId, ingestEndpoint, siteUrl}
+ *   {paste: true}      the person chose to paste a key instead (p, or after a failed sign-in). pressed: p while waiting.
+ *   {stopped: true}    q after a failed sign-in, or the end of the input. interrupt: true for Ctrl+C.
+ * ctx: {base: the app address, app?: {name, repo, platform}, env, openUrl(url, env, say) => boolean, request?, clock?}
+ */
+export async function signIn(ui, ctx) {
+  for (let round = 0; ; round++) {
+    const made = await makeLink(ui, ctx)
+    let result = made
+    if (made.link) result = await waitForSignIn(ui, ctx, made.link, made.deviceSecret)
+    if (result.approved || result.paste || result.stopped) return result
+    ui.print(result.why)
+    const next = await whatNext(ui, result.again)
+    if (next !== 'again') return next === 'paste' ? { paste: true } : { stopped: true }
+    ui.print()
+  }
+}
+
+/**
+ * POST /api/v1/cli/links. {link, deviceSecret}, or {why, again} when UKNOWS cannot be reached, or {paste} when this
+ * UKNOWS has no links route (401, 404 or 405).
+ */
+async function makeLink(ui, { base, app, request: send = request, clock = REAL_CLOCK }) {
+  const deviceSecret = randomBytes(32).toString('base64url')
+  const body = { client: CLIENT, version: VERSION, secretHash: secretHash(deviceSecret), ...(app ? { app: clean(app) } : {}) }
+  const url = new URL(`${base}${LINKS_PATH}`)
+  for (let failures = 0, tries = 0; tries < 20; tries++) {
+    const r = await post(send, url, body)
+    if (r.status === 201 || r.status === 200) {
+      const link = readLink(r.json)
+      return link ? { link, deviceSecret } : { why: `${url.hostname} sent a sign-in link that setup cannot read.`, again: 'try again' }
+    }
+    if (NO_LINKS_STATUS.has(r.status)) {
+      ui.print(SIGN_IN.noLinks(url.hostname))
+      return { paste: true }
+    }
+    if (r.status === 429) { await clock.sleep(retryAfter(r.headers, clock) ?? 5000); continue }
+    if (r.error || r.status >= 500) {
+      if (++failures >= 3) return { why: unreachable(url, r), again: 'try again' }
+      await clock.sleep(1000 * 2 ** (failures - 1))
+      continue
+    }
+    return { why: `${url.hostname} did not make a sign-in link (status ${r.status}).`, again: 'try again' }
+  }
+  return { why: `${url.hostname} is busy. It asked setup to wait too many times.`, again: 'try again' }
+}
+
+/**
+ * Show the link and the code, open the browser, and poll until UKNOWS answers. Enter opens the browser again, p goes to
+ * the paste question, Ctrl+C stops. Returns {approved, ...}, {paste}, {stopped}, or {why, again} (cancelled in the
+ * browser, expired, or no answer from UKNOWS).
+ */
+async function waitForSignIn(ui, ctx, link, deviceSecret) {
+  const { env, openUrl, request: send = request, clock = REAL_CLOCK } = ctx
+  const open = () => openUrl(link.verificationUrl, env, () => {})
+  const opened = open()
+  ui.print(opened ? SIGN_IN.opening : SIGN_IN.noBrowser)
+  ui.print(`  ${ui.cyan(link.verificationUrl)}`)
+  ui.print(`  ${SIGN_IN.code(ui.bold(link.userCode))}`)
+  ui.print()
+  const keys = ui.keys()
+  if (keys) {
+    ui.print(ui.dim(`  ${SIGN_IN.keys}`))
+    ui.print()
+  } else ui.print(SIGN_IN.waitingPlain.replace('{minutes}', minutes(link.expiresIn)))
+  const expires = clock.now() + link.expiresIn * 1000
+  const url = new URL(`${new URL(ctx.base).origin}${LINKS_PATH}/${encodeURIComponent(link.linkId)}/token`)
+  let interval = link.interval * 1000, failures = 0, note = ''
+  let nextPoll = clock.now() + interval
+  const left = () => {
+    const s = Math.max(0, Math.ceil((expires - clock.now()) / 1000))
+    return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`
+  }
+  const spin = ui.progress(() => `${SIGN_IN.waiting.replace('{left}', left())}${note}`)
+  let keyWait = null
+  const end = (result, line = null) => { spin.end(line); keys?.close(); return result }
+  try {
+    for (;;) {
+      const now = clock.now()
+      if (now >= expires) return end({ why: SIGN_IN.expired, again: 'start a new sign-in' })
+      if (now >= nextPoll) {
+        const r = await post(send, url, { deviceSecret })
+        if (r.status === 200) {
+          const data = readToken(r.json)
+          if (data) return end({ approved: true, ...data }, `${ui.cyan(ui.marks.done)} ${SIGN_IN.signedIn}`)
+          return end({ why: `${url.hostname} sent an answer that setup cannot read.`, again: 'try again' })
+        }
+        if (r.status === 403) return end({ why: SIGN_IN.denied, again: 'sign in again' })
+        if (r.status === 410 || r.status === 404) return end({ why: SIGN_IN.expired, again: 'start a new sign-in' })
+        if (r.status === 202) { failures = 0; note = ''; nextPoll = clock.now() + interval; continue }
+        if (r.status === 429) {
+          // Slow down: wait as long as UKNOWS asks, and poll less often from now on.
+          const wait = retryAfter(r.headers, clock)
+          interval = Math.min(Math.max(interval, wait ?? interval * 2), 60000)
+          nextPoll = clock.now() + Math.max(interval, wait ?? 0)
+          continue
+        }
+        if (r.error || r.status >= 500) {
+          if (++failures >= MAX_FAILURES) return end({ why: unreachable(url, r), again: 'try again' })
+          note = SIGN_IN.slow
+          nextPoll = clock.now() + Math.min(interval * 2 ** failures, 30000)
+          continue
+        }
+        return end({ why: `${url.hostname} answered the sign-in with status ${r.status}.`, again: 'try again' })
+      }
+      const sleep = clock.sleep(Math.min(nextPoll, expires) - now)
+      if (!keys) { await sleep; continue }
+      keyWait ??= keys.next()
+      const key = await Promise.race([sleep.then(() => undefined), keyWait])
+      sleep.cancel?.()
+      if (key === undefined) continue
+      keyWait = null
+      if (key === 'ctrl-c' || key === null) return end({ stopped: true, interrupt: true }, null)
+      if (key === 'p') {
+        // People often press Enter after p by habit. That Enter belongs to p, not to the paste question.
+        await Promise.race([keys.next(), new Promise((resolve) => setTimeout(resolve, 400))])
+        return end({ paste: true, pressed: true }, null)
+      }
+      if (key === 'enter' && !open()) ui.print(`  ${ui.cyan(link.verificationUrl)}`)
+    }
+  } finally {
+    spin.stop()
+    keys?.close()
+  }
+}
+
+/** After a failed sign-in: again (Enter), paste (p) or stop (q, or the end of the input). */
+async function whatNext(ui, again) {
+  for (let tries = 0; tries < 3; tries++) {
+    const answer = await ui.line(`Press Enter to ${again}, type p to paste a key instead, or type q to stop:`)
+    if (answer === null) return 'stop'
+    const a = answer.toLowerCase()
+    if (a === '') return 'again'
+    if (a === 'p' || a === 'paste') return 'paste'
+    if (a === 'q' || a === 'quit' || a === 'stop') return 'stop'
+    ui.print('Press Enter, or type p or q.')
+  }
+  return 'stop'
+}
+
+/** The link of a 201 answer, checked and tidied, or null. */
+function readLink(json) {
+  if (!json || typeof json !== 'object') return null
+  const { linkId, userCode, verificationUrl } = json
+  if (typeof linkId !== 'string' || !/^[A-Za-z0-9._~-]{1,200}$/.test(linkId)) return null
+  if (typeof userCode !== 'string' || !/^[A-Za-z0-9-]{4,20}$/.test(userCode)) return null
+  let url
+  try { url = new URL(String(verificationUrl)) } catch { return null }
+  const safe = url.protocol === 'https:' || (url.protocol === 'http:' && LOCAL.has(url.hostname))
+  if (!safe || url.username || url.password) return null
+  const number = (value, fallback, min, max) => (Number.isFinite(value) && value > 0 ? Math.min(Math.max(value, min), max) : fallback)
+  return { linkId, userCode, verificationUrl: url.href, expiresIn: number(json.expiresIn, 600, 30, 3600), interval: number(json.interval, 3, 0.05, 60) }
+}
+
+/** The key of a 200 answer, checked, or null. A key fits in a header: printable, no spaces, no commas. */
+function readToken(json) {
+  if (!json || typeof json !== 'object' || typeof json.key !== 'string' || !/^[\x21-\x7e]{8,512}$/.test(json.key) || json.key.includes(',')) return null
+  const text = (value) => (typeof value === 'string' && value.trim() ? value.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim().slice(0, 200) : null)
+  const workspace = json.workspace && typeof json.workspace === 'object' ? { id: text(json.workspace.id), name: text(json.workspace.name) } : { id: null, name: null }
+  return { key: json.key, workspace, environment: text(json.environment), environmentLabel: text(json.environmentLabel),
+    keyId: text(json.keyId), ingestEndpoint: text(json.ingestEndpoint), siteUrl: text(json.siteUrl) }
+}
+
+/** Retry-After in ms: seconds, or an HTTP date. null when missing. */
+function retryAfter(headers = {}, clock = REAL_CLOCK) {
+  const raw = String(headers?.['retry-after'] ?? '').trim()
+  if (!raw) return null
+  if (/^\d+$/.test(raw)) return Math.min(Number(raw), 120) * 1000
+  const at = Date.parse(raw)
+  return Number.isFinite(at) ? Math.min(Math.max(at - clock.now(), 0), 120000) : null
+}
+
+function unreachable(url, r) {
+  return r.error ? `Could not reach ${url.hostname} (${r.error.code || 'network error'}). Check your internet connection.`
+    : `${url.hostname} did not answer the sign-in (status ${r.status}).`
+}
+
+async function post(send, url, body) {
+  const r = await send(url, 'POST', { 'content-type': 'application/json', accept: 'application/json' }, JSON.stringify(body), 10000)
+  let json = null
+  try { json = r.body ? JSON.parse(r.body) : null } catch { json = null }
+  return { ...r, json }
+}
+
+/** The app as UKNOWS shows it in the browser: only text fields that are set. */
+function clean(app) {
+  const out = {}
+  for (const key of ['name', 'repo', 'platform']) if (typeof app[key] === 'string' && app[key].trim()) out[key] = app[key].trim().slice(0, 200)
+  return out
+}
+
+const minutes = (seconds) => (seconds % 60 === 0 ? `${seconds / 60} ${seconds === 60 ? 'minute' : 'minutes'}` : `${Math.round(seconds)} seconds`)

package/lib/stacks/azure.mjs

@@ -0,0 +1,345 @@
+/*
+ * Azure Monitor (App Insights) apps: keep it, and add 1 OTLP exporter to the same tracer provider, so nothing is
+ * traced twice. This mode never adds opentelemetry-instrument, NODE_OPTIONS or instrument.sh.
+ *   Python: the exporter package at the locked opentelemetry-sdk version, a lock refresh (uv lock or poetry lock),
+ *           and the docs block after the 1 configure_azure_monitor(...) statement.
+ *   .NET:   the exporter package at the resolved OpenTelemetry version, the using line and 1 line after CreateBuilder.
+ *   Node.js: printed code and packages (option objects vary, and OpenTelemetry JS 2 cannot add a processor later).
+ * Anything that is not plain becomes a printed step. The text comes from AZURE_MONITOR in the docs file.
+ */
+import { posix } from 'node:path'
+import { AZURE_MONITOR, PINS, RESOLVE } from '../contract.mjs'
+import { Doc } from '../doc.mjs'
+import { addUsing, csharpBuilder, insertPythonBlock, maskCsharp, pythonCalls, pythonStatement } from '../code.mjs'
+import { dependencies, findExisting } from '../existing.mjs'
+import { nearest, packageKey } from '../locks.mjs'
+import { pythonProjectName } from '../members.mjs'
+import { pyName, tomlString, tomlTable } from '../toml.mjs'
+import { upFrom } from '../workspace.mjs'
+import { addItems, offlineRestore, restoreStep } from './dotnet.mjs'
+import { appendLines, compiledRequirements, dockerInstalls, editPyproject, parsePyproject } from './python.mjs'
+import { lockStep } from './python-lock.mjs'
+
+const AM = AZURE_MONITOR
+const at = (dir, name) => (dir === '.' ? name : `${dir}/${name}`)
+const dirOf = (path) => posix.dirname(path)
+const read = (view, path) => { try { return view.read(path) } catch { return null } }
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+const LOCK_CMD = { 'uv.lock': 'uv', 'poetry.lock': 'poetry', 'pdm.lock': 'pdm' }
+
+/** @type {import('../types.mjs').Applier} */
+export const azure = {
+  id: 'azure',
+  plan(service, ctx) {
+    // What this mode is, and what it does not add for this stack.
+    const start = AM.plan.start[service.lang]
+    const out = { summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [AM.plan.mode, ...(start ? [fill(AM.plan.keep, { start })] : [])] }
+    const view = ctx.repo ?? ctx.ws
+    const existing = ctx.existing ?? findExisting(service, view)
+    if (service.lang === 'python') {
+      python(service, ctx, existing, out)
+      if (!out.stop) out.manual.push(...untracedServer(service, view, existing))
+    }
+    else if (service.lang === 'dotnet') dotnet(service, ctx, existing, out)
+    else if (service.lang === 'node') node(service, ctx, existing, out)
+    else out.manual.push(printedBlock('Add UKNOWS beside Azure Monitor', ['This tool has no automatic steps for Azure Monitor in this language.'], []))
+    out.manual.push(samplingAdvice(existing, service.lang))
+    return out
+  },
+}
+
+/**
+ * The sampling that applies, as advice: code arguments, OTEL_TRACES_SAMPLER, or the default of 5 a second. Then why it
+ * matters, the option names of this stack and how to send every trace, each said once.
+ */
+function samplingAdvice(existing, lang) {
+  const anchors = existing.anchors ?? []
+  const code = anchors.find((a) => a.kind === 'sampling')
+  const env = anchors.find((a) => a.kind === 'sampler-env')
+  const line = code ? fill(AM.plan.samplingCode, { file: code.file, line: code.line, value: code.what })
+    : env ? fill(AM.plan.samplingEnv, { file: env.file, value: env.value ?? env.what }) : AM.plan.samplingDefault
+  const options = AM.plan.samplingOptions[lang] ?? AM.plan.samplingOptions.python
+  return { title: 'Check the sampling of Azure Monitor', lines: [line, ...AM.plan.sampling.map((l) => fill(l, { options }))], required: false }
+}
+
+/** A required step with the code to add by hand. The Keep line names only what this stack must not add. */
+function printedBlock(title, reasons, snippets, lang = null) {
+  const start = AM.plan.start[lang]
+  const steps = AM.steps.map((step) => (start && /^Keep APPLICATIONINSIGHTS_CONNECTION_STRING/.test(step) ? fill(AM.plan.keep, { start }) : step))
+  return { title, lines: [...reasons, ...steps], snippets }
+}
+
+// --- Python ----------------------------------------------------------------------------
+
+function python(service, ctx, existing, out) {
+  const { ws } = ctx
+  const view = ctx.repo ?? ws
+  const exporterName = AM.python.package
+  const sdk = existing.installed?.packages.get('opentelemetry-sdk')
+  let requirement = sdk?.version ? `${exporterName}==${sdk.version}` : exporterName
+  const printed = (reasons) => {
+    out.manual.push(printedBlock('Add UKNOWS beside Azure Monitor', reasons, [
+      { caption: 'Package to add', language: 'text', code: requirement },
+      { caption: `Python: after the ${AM.python.call}...) statement`, language: 'python', code: AM.python.code }], 'python'))
+  }
+  // The manifest that lists azure-monitor-opentelemetry: in a uv workspace, the member that declares it.
+  const calls = pythonCallSites(existing, view)
+  const declared = (existing.azure ?? []).filter((e) => /(?:^|\/)(pyproject\.toml|requirements[\w.-]*\.txt)$/.test(e.file))
+  const near = calls[0] && declared.find((e) => calls[0].file === e.file || calls[0].file.startsWith(`${dirOf(e.file)}/`) || dirOf(e.file) === '.')
+  const manifest = (near ?? declared[0])?.file
+  if (!manifest) return printed(['This tool did not find the file that lists azure-monitor-opentelemetry.'])
+
+  // The image must install the file that gets the package, or the import in the block would fail at start.
+  const docker = service.dockerfile ? read(ws, service.dockerfile) : null
+  if (docker !== null && !imageInstalls(service, docker, manifest, view, existing)) {
+    return printed([`${service.dockerfile} does not install ${manifest}, so the image would not have ${exporterName}. This tool changed nothing.`])
+  }
+  // The code goes in automatically only when it is safe: 1 call, a whole statement, no pylint config.
+  const reasons = []
+  if (calls.length !== 1) reasons.push(calls.length ? `The app calls ${AM.python.call}...) ${calls.length} times.` : `This tool did not find the ${AM.python.call}...) call.`)
+  const call = calls.length === 1 ? calls[0] : null
+  const statement = call ? pythonStatement(read(ws, call.file), call) : null
+  if (statement && !statement.ok) reasons.push(`This tool cannot add code after the ${AM.python.call}...) call in ${call.file} line ${call.line + 1}: ${statement.reason}.`)
+  const pylint = pylintConfig(view, call?.file ?? manifest)
+  if (pylint) reasons.push(`${pylint} configures pylint, which can reject the added code.`)
+
+  // The package, then the lock.
+  const text = read(ws, manifest)
+  const listed = dependencies(manifest, text ?? '').some((d) => d.name === exporterName)
+  const lockFile = /pyproject\.toml$/.test(manifest) ? lockFor(view, dirOf(manifest)) : null
+  const lockName = lockFile?.split('/').pop()
+  const member = pythonProjectName(view, dirOf(manifest))
+  const locked = lockFile && existing.installed?.packages.get(member ?? '')?.requires.some((r) => pyName(r.name) === pyName(exporterName))
+  const needsLock = lockFile && (!listed || !locked)
+  // A uv or Poetry project gets a lower limit: its resolver keeps the exporter at the SDK version, now and after a
+  // later Azure Monitor upgrade. An exact pin would hold the SDK at today's version (gate open issue 7).
+  const tool = lockName === 'uv.lock' ? 'uv lock' : lockName === 'poetry.lock' ? 'poetry lock' : null
+  if (tool && sdk?.version) requirement = `${exporterName}>=${sdk.version}`
+  if (needsLock && lockName === 'pdm.lock') return printed([`${manifest} is locked with PDM. Add the package, then run pdm lock.`])
+  // The tool on this computer writes the lock that the image reads: it must be there, and the version the project asks for.
+  const step = needsLock ? lockStep({ view, lockFile, tools: ctx.tools, dockerfile: service.dockerfile, docker, packages: exporterName }) : null
+  if (step?.block) {
+    out.manual.push(step.block)
+    out.stop = true
+    return
+  }
+  // A requirements file that pip-compile or uv writes, or that has hashes, takes no lines from this tool. Then the
+  // code block stays out too: its import would fail at start without the package.
+  const compiled = !listed && /\.txt$/.test(manifest) ? compiledRequirements(ws, manifest) : null
+  if (compiled) return printed([...compiled, 'This tool changed nothing.'])
+  if (!listed) {
+    const deps = parsePyproject(text ?? '')
+    const after = /\.txt$/.test(manifest) ? appendLines(text, [requirement])
+      : deps?.kind === 'poetry' ? editPyproject(text, deps, [sdk?.version ? `${exporterName}>=${sdk.version}` : `${exporterName}==*`]) : deps ? editPyproject(text, deps, [requirement]) : null
+    if (after === null) return printed([`This tool cannot change the dependency list in ${manifest}.`])
+    out.edits.push({ file: manifest, before: text, after, why: `Add ${exporterName}, so Azure Monitor traces also go to UKNOWS.` })
+    out.summary.push(`Add ${requirement} to ${manifest}${sdk?.version ? `, at the opentelemetry-sdk version in ${sdk.file}` : ''}.`)
+    if (sdk?.version) out.notes.push(fill(tool ? AM.plan.floor : AM.plan.pin, { file: manifest, package: exporterName, version: sdk.version, tool }))
+  }
+  if (step?.command) out.commands.push(step.command)
+  if (reasons.length) return printed(reasons)
+  const source = read(ws, call.file)
+  if (/\bdef\s+_send_traces_to_uknows\s*\(/.test(source)) return
+  const after = insertPythonBlock(source, statement, AM.python.code, quoteStyle(view, call.file))
+  out.edits.push({ file: call.file, before: source, after, why: 'Also send the Azure Monitor traces to UKNOWS.' })
+  const count = after.split('\n').length - source.split('\n').length
+  out.summary.push(fill(AM.plan.pythonCode, { count, call: AM.python.call, file: call.file, line: statement.end + 1 }))
+}
+
+/**
+ * A required step when the app serves HTTP with a framework that Azure Monitor does not trace (Starlette, FastMCP,
+ * aiohttp, Tornado, Falcon, Pyramid) and with none that it traces (Django, FastAPI, Flask). Without it, App Insights
+ * and UKNOWS get no request spans. Nothing when the app lists the instrumentation package already.
+ */
+function untracedServer(service, view, existing) {
+  const files = [...new Set([...service.manifests, ...(existing.members ?? []).flatMap((m) => m.manifests ?? []),
+    ...(existing.azure ?? []).map((e) => e.file)])].filter((f) => /(?:^|\/)(pyproject\.toml|requirements[\w.-]*\.txt|Pipfile)$/.test(f))
+  const listed = files.flatMap((file) => dependencies(file, read(view, file) ?? '').map((d) => ({ ...d, name: pyName(d.name), file })))
+  const has = (name) => listed.find((d) => d.name === name)
+  if (AM.python.traced.some(has)) return []
+  const anchors = existing.anchors ?? []
+  const serves = (name) => (name === 'aiohttp' ? anchors.some((a) => a.kind === 'aiohttp-server') : name === 'mcp' ? anchors.some((a) => a.kind === 'mcp-server') : true)
+  const installed = existing.installed?.packages
+  const contrib = installed?.get('opentelemetry-instrumentation')?.version ?? contribOf(installed?.get('opentelemetry-sdk')?.version)
+  const T = AM.python.untraced
+  for (const server of AM.python.servers) {
+    if (has(server.package)) return []
+    const found = server.names.map(has).find((d) => d && serves(d.name))
+    if (!found) continue
+    const values = { ...server, name: found.name, file: found.file, line: found.line, manifest: found.file, version: contrib ? `, here ${contrib}` : '' }
+    return [{ title: fill(T.title, values), verify: true, lines: [fill(T.found, values), ...(found.name !== server.label.toLowerCase() ? [fill(T.builtOn, values)] : []),
+      T.why, fill(T.add, values), fill(T.call, values)],
+    snippets: [{ caption: 'Package to add', language: 'text', code: contrib ? `${server.package}==${contrib}` : server.package },
+      { caption: T.caption, language: 'python', code: `from ${server.module} import ${server.instrumentor}\n\n${server.instrumentor}().instrument()` }] }]
+  }
+  return []
+}
+
+/** The contrib release (opentelemetry-instrumentation-*) of an opentelemetry-sdk release: 1.36.0 -> 0.57b0. */
+const contribOf = (core) => { const m = /^1\.(\d+)\.(\d+)$/.exec(core ?? ''); return m ? `0.${Number(m[1]) + 21}b${m[2]}` : null }
+
+/** Real configure_azure_monitor( calls in the files where the anchor scan found the name. */
+function pythonCallSites(existing, view) {
+  const files = [...new Set((existing.anchors ?? []).filter((a) => a.kind === 'azure-call' && a.file.endsWith('.py')).map((a) => a.file))]
+  return files.flatMap((file) => pythonCalls(read(view, file) ?? '', 'configure_azure_monitor').map((c) => ({ ...c, file })))
+}
+
+/**
+ * The image installs this manifest: uv sync, poetry install or pip install . for a pyproject.toml, pip install -r for
+ * a requirements file. uv sync --package <name> installs that member and the members it depends on, not the others.
+ */
+function imageInstalls(service, docker, manifest, view, existing) {
+  const installs = dockerInstalls(service, docker)
+  if (!/pyproject\.toml$/.test(manifest)) return installs.files.includes(manifest)
+  if (!installs.project || installs.packages === null) return installs.project
+  const name = pythonProjectName(view, dirOf(manifest))
+  return (name !== null && installs.packages.includes(name)) || (existing.members ?? []).some((m) => m.dir === dirOf(manifest))
+}
+
+/** The uv, Poetry or PDM lockfile that covers a folder. */
+function lockFor(view, dir) {
+  for (const name of Object.keys(LOCK_CMD)) { const file = nearest(view, dir, name); if (file) return file }
+  return null
+}
+
+/** A pylint config next to the code or above it: .pylintrc, pylintrc, [tool.pylint] or [pylint] in setup.cfg or tox.ini. */
+function pylintConfig(view, file) {
+  for (const dir of upFrom(dirOf(file), view.top ?? '.')) {
+    for (const name of ['.pylintrc', 'pylintrc']) if (read(view, at(dir, name)) !== null) return at(dir, name)
+    if (/^\s*\[tool\.pylint/m.test(read(view, at(dir, 'pyproject.toml')) ?? '')) return at(dir, 'pyproject.toml')
+    for (const name of ['setup.cfg', 'tox.ini']) if (/^\s*\[(?:tool:)?pylint/m.test(read(view, at(dir, name)) ?? '')) return at(dir, name)
+  }
+  return null
+}
+
+/** Single quotes when ruff format says so: [tool.ruff.format] quote-style, or [format] in ruff.toml. Else double, as black. */
+function quoteStyle(view, file) {
+  for (const dir of upFrom(dirOf(file), view.top ?? '.')) {
+    for (const [name, table] of [['ruff.toml', 'format'], ['.ruff.toml', 'format'], ['pyproject.toml', 'tool.ruff.format']]) {
+      const style = tomlString(tomlTable(read(view, at(dir, name)) ?? '', table), 'quote-style')
+      if (style) return style === 'single' ? "'" : '"'
+    }
+  }
+  return '"'
+}
+
+// --- .NET ------------------------------------------------------------------------------
+
+function dotnet(service, ctx, existing, out) {
+  const { ws } = ctx
+  const view = ctx.repo ?? ws
+  const { package: exporter } = PINS.dotnet.otlpExporter
+  const projects = service.manifests.filter((m) => m.endsWith('.csproj'))
+  const csproj = projects.find((p) => /Microsoft\.NET\.Sdk\.Web/.test(read(ws, p) ?? '')) ?? projects[0]
+  const resolved = existing.installed?.packages.get('opentelemetry')?.version
+  const listed = csproj ? dependencies(csproj, read(ws, csproj) ?? '') : []
+  const direct = listed.find((d) => /^OpenTelemetry(\.Extensions\.Hosting|\.Exporter\.[\w.]+)?$/i.test(d.name) && /^\d+\.\d+\.\d+$/.test(d.spec ?? ''))?.spec
+  const version = resolved ?? direct ?? PINS.dotnet.otlpExporter.version
+  const code = [AM.dotnet.using, '', AM.dotnet.after, AM.dotnet.line].join('\n')
+  const printed = (reasons) => out.manual.push(printedBlock('Add UKNOWS beside Azure Monitor', reasons, [
+    { caption: 'Terminal', language: 'bash', code: `dotnet add package ${exporter} --version ${version}` },
+    { caption: '.NET: Program.cs', language: 'csharp', code }], 'dotnet'))
+  if (!csproj) return printed(['This tool did not find the .csproj file of the web app.'])
+
+  // Program.cs: exactly 1 WebApplication.CreateBuilder in the project that gets the package.
+  const builders = projectSources(ws, csproj).map((file) => ({ file, text: read(ws, file) ?? '' })).filter((f) => /WebApplication\s*\.\s*Create(?:Slim)?Builder\s*\(/.test(maskCsharp(f.text)))
+  const done = builders.some((f) => /ConfigureOpenTelemetryTracerProvider\s*\([^;]*AddOtlpExporter/.test(maskCsharp(f.text)))
+  const program = builders.length === 1 ? builders[0] : null
+  const statement = program ? csharpBuilder(program.text) : null
+  const reasons = []
+  if (!done && builders.length !== 1) reasons.push(builders.length ? `${builders.length} files call WebApplication.CreateBuilder.` : 'This app does not call WebApplication.CreateBuilder, for example because it uses a Startup class.')
+  if (!done && statement && !statement.ok) reasons.push(`This tool cannot add the line in ${program.file}: ${statement.reason}.`)
+
+  // The package, at the OpenTelemetry version the app resolves now.
+  const text = read(ws, csproj)
+  if (!listed.some((d) => d.name.toLowerCase() === exporter.toLowerCase())) {
+    // A locked restore refreshes packages.lock.json after the edit. When it cannot run, nothing changes.
+    const docker = service.dockerfile ? read(ws, service.dockerfile) : null
+    const offline = docker === null ? null : offlineRestore(docker)
+    const framework = /<TargetFrameworks?>\s*net(\d+)\./i.exec(text ?? '')?.[1] ?? null
+    const restore = restoreStep(service, ctx, csproj, framework)
+    if (offline || restore?.block) {
+      const block = offline ? { title: RESOLVE.dotnet.offline.title, lines: [fill(RESOLVE.dotnet.offline.lines[0], { file: service.dockerfile, line: offline.line })] }
+        : restore.block
+      out.manual.push({ ...block, snippets: [{ caption: 'Terminal', language: 'bash', code: `dotnet add package ${exporter} --version ${version}` },
+        { caption: '.NET: Program.cs', language: 'csharp', code }] })
+      out.stop = true
+      return
+    }
+    const central = upFrom(dirOf(csproj), view.top ?? '.').map((d) => at(d, 'Directory.Packages.props')).find((f) => read(view, f) !== null)
+    const centrally = central && /<ManagePackageVersionsCentrally>\s*true\s*</i.test(read(view, central))
+    if (centrally) return printed([`This repo sets package versions in ${central}. Add ${exporter} ${version} there and in ${csproj}.`, ...reasons])
+    const after = addItems(text, [`<PackageReference Include="${exporter}" Version="${version}" />`], /<PackageReference\s/)
+    if (after === null) return printed([`This tool cannot add a package to ${csproj}.`, ...reasons])
+    out.edits.push({ file: csproj, before: text, after, why: `Add the ${exporter} package, so Azure Monitor traces also go to UKNOWS.` })
+    out.summary.push(`Add ${exporter} ${version} to ${csproj}${resolved ? ', at the OpenTelemetry version the app resolves now' : ''}.`)
+    if (!resolved) out.notes.push(`${exporter} ${version} needs OpenTelemetry ${version} or later. If the app uses an older OpenTelemetry, this raises it to ${version}.`)
+    if (restore?.command) out.commands.push(...restore.before, restore.command)
+    if (restore?.command) out.notes.push(...restore.notes)
+    if (restore?.note) out.notes.push(restore.note)
+  }
+  if (done) return
+  if (reasons.length) return printed(reasons)
+  const withUsing = addUsing(program.text, AM.dotnet.using)
+  // The using line can move the builder line down by 1 or 2 lines.
+  const moved = csharpBuilder(withUsing)
+  const doc = new Doc(withUsing)
+  doc.insert(moved.end + 1, `${moved.indent}${AM.dotnet.line.replace(/\bbuilder\.Services\b/, `${moved.name}.Services`)}`)
+  out.edits.push({ file: program.file, before: program.text, after: doc.toString(), why: 'Also send the Azure Monitor traces to UKNOWS.' })
+  out.summary.push(`Also send the Azure Monitor traces to UKNOWS: add ${AM.dotnet.using} and 1 line after the builder in ${program.file}.`)
+}
+
+/**
+ * The .cs files that 1 project compiles: the files under its folder, without obj/ and bin/, without the folders of
+ * other projects below it, and without the <Compile Remove="..."> globs of the project.
+ */
+export function projectSources(ws, csproj) {
+  const dir = dirOf(csproj)
+  const under = (file) => dir === '.' || file.startsWith(`${dir}/`)
+  const rel = (file) => (dir === '.' ? file : file.slice(dir.length + 1))
+  const all = ws.files(dir).filter(under)
+  const nested = all.filter((f) => f.endsWith('.csproj') && dirOf(f) !== dir).map(dirOf)
+  const removed = [...(read(ws, csproj) ?? '').matchAll(/<Compile\s[^>]*?Remove\s*=\s*"([^"]+)"/gi)]
+    .flatMap((m) => m[1].split(';')).map((g) => g.trim().replace(/\\/g, '/').replace(/^\.\//, '')).filter(Boolean).map(globRegex)
+  return all.filter((f) => f.endsWith('.cs') && !/(?:^|\/)(?:obj|bin)\//.test(rel(f))
+    && !nested.some((d) => f.startsWith(`${d}/`)) && !removed.some((re) => re.test(rel(f))))
+}
+
+/** An MSBuild item glob as a regex on a path relative to the project: ** any folders, * and ? within 1 name. */
+function globRegex(glob) {
+  let out = ''
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]
+    if (c === '*' && glob[i + 1] === '*') { out += glob[i + 2] === '/' ? '(?:.*/)?' : '.*'; i += glob[i + 2] === '/' ? 2 : 1 }
+    else if (c === '*') out += '[^/]*'
+    else if (c === '?') out += '[^/]'
+    else out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^${out}$`, 'i')
+}
+
+// --- Node.js ---------------------------------------------------------------------------
+
+function node(service, ctx, existing, out) {
+  const view = ctx.repo ?? ctx.ws
+  const packages = existing.installed?.packages ?? new Map()
+  const versionOf = (name) => packages.get(packageKey('node', name))?.version ?? null
+  // The experimental packages share 1 version line: take the exporter version from one the distro already has.
+  const experimental = versionOf(AM.node.packages[0]) ?? versionOf('@opentelemetry/instrumentation') ?? versionOf('@opentelemetry/sdk-node')
+  const stable = versionOf(AM.node.packages[1])
+  const wanted = [[AM.node.packages[0], experimental], [AM.node.packages[1], stable]]
+  const pkg = (() => { try { return JSON.parse(read(view, at(service.dir, 'package.json')) ?? '') } catch { return null } })()
+  const has = (name) => ['dependencies', 'devDependencies'].some((g) => pkg?.[g]?.[name])
+  const call = (existing.anchors ?? []).find((a) => a.kind === 'azure-call' && /\.(m?[jt]sx?|c[jt]s)$/.test(a.file))
+  const shim = !call && (existing.azure ?? []).some((e) => e.what === 'applicationinsights')
+  const added = call && /OTLPTraceExporter/.test(read(view, call.file) ?? '')
+  if (added && wanted.every(([name]) => has(name))) return
+  const pm = nearest(view, service.dir, 'pnpm-lock.yaml') ? 'pnpm add' : nearest(view, service.dir, 'yarn.lock') ? 'yarn add' : 'npm install --save'
+  const install = `${pm} ${wanted.map(([name, v]) => (v ? `${name}@${v}` : name)).join(' ')}`
+  const where = call ? `Found ${AM.node.call}...) in ${call.file} line ${call.line}.` : null
+  out.manual.push(printedBlock('Add the UKNOWS exporter to Azure Monitor', [where, shim ? AM.node.shim : null,
+    'Node.js apps pass their Azure Monitor options in many ways, so this tool does not change the code.',
+    ...AM.notes.filter((n) => /Node\.js/.test(n))].filter(Boolean), [
+    { caption: 'Terminal', language: 'bash', code: install },
+    { caption: `Node.js: where your app calls ${AM.node.call.slice(0, -1)}`, language: 'javascript', code: AM.node.code }], 'node'))
+}