@uknows/setup 0.1.0 → 0.2.0

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'))
+}

package/lib/stacks/channel.mjs

@@ -0,0 +1,125 @@
+// The agent channel (--channel stable|early): for a Java, .NET or Node.js service that builds from a Dockerfile, the
+// agent comes from the UKNOWS agent image at every build. The change is 1 COPY line and the start settings in the
+// final stage, after the last RUN. Packages, lock files and the start command do not change.
+//
+//   COPY --from=<registry>/agent-<lang>:<channel> /uknows/ /uknows/
+//   Java     JAVA_TOOL_OPTIONS  -javaagent:/uknows/java/uknows-loader.jar
+//   Node.js  NODE_OPTIONS       --require /uknows/node/register.cjs   (ES modules: --import /uknows/node/register.mjs)
+//   .NET     CORECLR_* (the OpenTelemetry profiler for glibc or musl), OTEL_DOTNET_AUTO_HOME, DOTNET_STARTUP_HOOKS
+//
+// Each language starts through a small UKNOWS loader in the image. It checks the agent files (size and checksum)
+// and starts the agent, or prints 1 line and lets the app start without it. So an agent file that is missing or
+// broken never stops the app.
+import { AGENT_CHANNELS, AGENT_REGISTRY, STACKS } from '../contract.mjs'
+import { addOption, dockerStart, insertBeforeStart, parseDockerfile, setEnv } from '../dockerfile.mjs'
+import { entryOf } from './node.mjs'
+import { targetFramework, webProject } from './dotnet.mjs'
+
+export const CHANNELS = AGENT_CHANNELS
+export const LANGS = ['java', 'dotnet', 'node']
+const DOTNET_PROFILER = '{918728DD-259F-4A6A-AC2B-B85E1B658318}'
+const WINDOWS = /windows|nanoserver|servercore/i
+
+/** The registry and path that hold the agent images, for example registry.example.com/uknows. No scheme, no tag. */
+export function validRegistry(value) {
+  return typeof value === 'string' && AGENT_REGISTRY.test(value)
+}
+
+export const image = (registry, lang, channel) => `${registry}/agent-${lang}:${channel}`
+export const copyLine = (registry, lang, channel) => `COPY --from=${image(registry, lang, channel)} /uknows/ /uknows/`
+
+/** The settings that start the agent of 1 language. */
+export function startSettings(lang, { esm = false, musl = false } = {}) {
+  if (lang === 'java') return { option: ['JAVA_TOOL_OPTIONS', '-javaagent:/uknows/java/uknows-loader.jar'] }
+  if (lang === 'node') return { option: ['NODE_OPTIONS', esm ? '--import /uknows/node/register.mjs' : '--require /uknows/node/register.cjs'] }
+  return { env: [
+    ['CORECLR_ENABLE_PROFILING', '1'],
+    ['CORECLR_PROFILER', DOTNET_PROFILER],
+    ['CORECLR_PROFILER_PATH', `/uknows/dotnet/${musl ? 'musl' : 'glibc'}/OpenTelemetry.AutoInstrumentation.Native.so`],
+    ['OTEL_DOTNET_AUTO_HOME', '/uknows/dotnet'],
+    ['DOTNET_STARTUP_HOOKS', '/uknows/dotnet/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll'],
+  ] }
+}
+
+/** Does this service fit the channel? null when it does, else the reason (it then keeps the package route). */
+export function channelMisfit(service) {
+  if (!LANGS.includes(service.lang)) return 'The agent channel has Java, .NET and Node.js.'
+  if (!service.dockerfile) return 'The agent channel needs a Dockerfile, and this service does not build from one.'
+  return null
+}
+
+const read = (ws, path) => { try { return ws.read(path) } catch { return null } }
+
+/** @type {import('../types.mjs').Applier} */
+export const channel = {
+  id: 'channel',
+  plan(service, ctx) {
+    const plan = { summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [] }
+    const { registry, name: channelName } = ctx.channel ?? {}
+    if (!validRegistry(registry) || !CHANNELS.includes(channelName)) throw new Error('The agent channel needs its registry and its name.')
+    const lang = service.lang
+    const text = read(ctx.ws, service.dockerfile)
+    const info = text === null ? null : parseDockerfile(text)
+    const base = info?.image ?? ''
+    if (!info) {
+      plan.manual.push({ title: 'Add the UKNOWS agent', lines: [`This tool cannot read ${service.dockerfile}.`] })
+      return plan
+    }
+    if (WINDOWS.test(base)) {
+      plan.manual.push({ title: 'Add the UKNOWS agent', lines: [`The final image ${base} is a Windows image. The agent channel has Linux images only.`] })
+      return plan
+    }
+    const musl = /alpine/i.test(base)
+    let esm = false
+    if (lang === 'node') {
+      const v = /^(\d+)(?:\.(\d+))?/.exec(service.runtimeVersion ?? '')
+      const [major, minor] = v ? [Number(v[1]), v[2] === undefined ? 99 : Number(v[2])] : [99, 99]
+      if (major < 18 || major === 19 || (major === 18 && minor < 19) || (major === 20 && minor < 6)) {
+        plan.manual.push({ title: 'Use Node.js 18.19 or later', lines: [`This app uses Node.js ${service.runtimeVersion}.`,
+          'The UKNOWS agent needs Node.js 18.19 or later on version 18, or 20.6 or later.', 'Update the Node.js version of the app. Then run npx @uknows/setup again.'] })
+        return plan
+      }
+      let pkg = {}
+      try { pkg = JSON.parse(read(ctx.ws, service.dir === '.' ? 'package.json' : `${service.dir}/package.json`) ?? '{}') } catch { /* not JSON: CommonJS */ }
+      const entry = entryOf(dockerStart(info)?.argv, typeof pkg.scripts?.start === 'string' ? pkg.scripts.start : null)
+      esm = /\.m[jt]s$/.test(entry ?? '') || (pkg.type === 'module' && !/\.c[jt]s$/.test(entry ?? ''))
+    }
+    if (lang === 'dotnet') {
+      const csproj = webProject(service, ctx.ws)
+      const framework = csproj ? targetFramework(read(ctx.ws, csproj) ?? '', []) : null
+      const major = /^net(?:coreapp)?(\d+)\./.exec(framework ?? '')?.[1] ?? (/^net\d+$/.test(framework ?? '') ? '4' : null)
+      if (major !== null && Number(major) < 8) {
+        plan.manual.push({ title: 'Use .NET 8 or later', lines: [`${csproj} targets ${framework}.`, 'The UKNOWS agent needs .NET 8 or later.',
+          'Change the target framework to net8.0 or later. Then run npx @uknows/setup again.'] })
+        return plan
+      }
+    }
+
+    const line = copyLine(registry, lang, channelName)
+    const has = (l) => l.trim().startsWith(`COPY --from=${registry}/agent-${lang}:`)
+    let after = text.split('\n').some(has) ? text : insertBeforeStart(text, [line])
+    const settings = startSettings(lang, { esm, musl })
+    if (settings.option) {
+      const [name, option] = settings.option
+      after = addOption(after, name, option)
+      if (info.env.has(name) || info.inherited.has(name)) plan.notes.push(`${service.dockerfile} already sets ${name}. A new ENV line before the start keeps that value and adds the agent.`)
+    } else {
+      const hooks = info.env.get('DOTNET_STARTUP_HOOKS') ?? info.inherited.get('DOTNET_STARTUP_HOOKS')
+      const pairs = settings.env.map(([n, v]) => (n === 'DOTNET_STARTUP_HOOKS' && hooks?.value && !hooks.value.includes(v) ? [n, `${v}:${hooks.value}`] : [n, v]))
+      after = setEnv(after, pairs)
+      // The docs settings for .NET add a log folder that the app can write.
+      for (const l of STACKS.find((s) => s.id === 'dotnet').extraSettings?.lines ?? []) plan.extraSettings.push({ name: l.slice(0, l.indexOf('=')), value: l.slice(l.indexOf('=') + 1) })
+    }
+    if (lang === 'node') {
+      for (const l of STACKS.find((s) => s.id === 'node').extraSettings?.lines ?? []) plan.extraSettings.push({ name: l.slice(0, l.indexOf('=')), value: l.slice(l.indexOf('=') + 1) })
+    }
+    if (after === text) return plan
+    plan.edits.push({ file: service.dockerfile, before: text, after, why: 'Add the UKNOWS agent from the agent image, and start it.' })
+    plan.summary.push(`Copy the UKNOWS agent into the image at each build, from ${image(registry, lang, channelName)} (the ${channelName} channel).`,
+      `Start the agent with the app (${settings.option ? settings.option[0] : `the .NET profiler settings${musl ? ' for musl (Alpine)' : ''}`} in ${service.dockerfile}).`)
+    plan.notes.push(`Each build copies the current agent of the ${channelName} channel. A new agent reaches the app at its next build and deploy, with no change to this repo.`,
+      'If an agent file is missing or broken, the app starts without the agent and prints 1 line that starts with "UKNOWS agent:". UKNOWS_AGENT=off turns the agent off.')
+    if (lang === 'node' && esm) plan.notes.push('This app runs as ES modules, so node loads the agent with --import.')
+    return plan
+  },
+}