@uknows/setup 0.0.0-stage → 0.2.0

package/lib/stacks/java.mjs

@@ -0,0 +1,57 @@
+// Java: copy the pinned OpenTelemetry Java agent into the final image with the docs COPY --from line
+// (the image digest pins the jar) and load it with JAVA_TOOL_OPTIONS. Build files are never touched.
+// Both lines go after the last RUN, so build steps (mvn, gradle) never load the agent.
+import { JAVA_AGENT, STACKS } from '../contract.mjs'
+import { addOption, insertBeforeStart, parseDockerfile } from '../dockerfile.mjs'
+import { envOverrides } from './k8s.mjs'
+
+const DOCS = STACKS.find((s) => s.id === 'java')
+const COPY_LINE = DOCS.dockerfile.split('\n').find((l) => l.startsWith('COPY --from='))
+// 0.1.0 wrote an ADD line with --checksum and --chmod, which need BuildKit. Earlier /docs gave --chmod=644.
+// A Dockerfile with one of those exact lines gets the COPY line instead.
+const ADD_LINE = `ADD --checksum=sha256:${JAVA_AGENT.sha256} --chmod=755 ${JAVA_AGENT.url} /otel/${JAVA_AGENT.file}`
+const OLD_LINES = [ADD_LINE, ADD_LINE.replace('--chmod=755', '--chmod=644')]
+const AGENT_OPTION = /JAVA_TOOL_OPTIONS="([^"]+)"/.exec(DOCS.dockerfile)[1]
+const AGENT_PATH = AGENT_OPTION.replace(/^-javaagent:/, '')
+const note = (re) => DOCS.notes.find((n) => re.test(n))
+
+/** @type {import('../types.mjs').Applier} */
+export const java = {
+  id: 'java',
+  plan(service, ctx) {
+    const plan = { summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [] }
+    const text = service.dockerfile && ctx.ws.read(service.dockerfile)
+    const info = text ? parseDockerfile(text) : null
+    const image = info?.image ?? ''
+    if (!text || /windows|nanoserver|servercore/i.test(image)) {
+      plan.manual.push({ title: `Add the OpenTelemetry Java agent ${JAVA_AGENT.version}`, lines: [
+        text ? `The final image ${image} is a Windows image. This tool adds the agent to Linux images only.`
+          : 'This app does not build from a Dockerfile, so this tool cannot add the agent.',
+        'Download the agent and check its checksum with the commands below.', note(/macOS/),
+        `Start the JVM with ${AGENT_OPTION.replace(AGENT_PATH, `<path to ${JAVA_AGENT.file}>`)}, or set it in JAVA_TOOL_OPTIONS.`,
+        note(/Put -javaagent before -jar/)],
+      snippets: [{ caption: 'Download and check the agent', language: 'bash', code: DOCS.install },
+        { caption: 'Start', language: 'bash', code: DOCS.start }] })
+      return plan
+    }
+    const has = (value) => value.includes(AGENT_OPTION)
+    plan.manual.push(...envOverrides(service, 'JAVA_TOOL_OPTIONS', AGENT_OPTION, has))
+    const fixed = OLD_LINES.reduce((out, line) => out.split(line).join(COPY_LINE), text)
+    const added = [JAVA_AGENT.url, JAVA_AGENT.image, AGENT_PATH].some((s) => fixed.includes(s)) ? fixed : insertBeforeStart(fixed, [COPY_LINE])
+    const after = addOption(added, 'JAVA_TOOL_OPTIONS', AGENT_OPTION, has)
+    if (after === text) return plan
+    if (after === fixed) {
+      plan.edits.push({ file: service.dockerfile, before: text, after, why: 'Copy the OpenTelemetry Java agent from the pinned image.' })
+      plan.summary.push(`Replace the ADD line of the agent in ${service.dockerfile} with a COPY line from the pinned OpenTelemetry image. It needs no BuildKit.`)
+      return plan
+    }
+    plan.edits.push({ file: service.dockerfile, before: text, after, why: 'Add the OpenTelemetry Java agent and load it when the JVM starts.' })
+    plan.summary.push(`Add the OpenTelemetry Java agent ${JAVA_AGENT.version} to ${service.dockerfile}, from the image pinned by its digest.`,
+      `Load the agent when the JVM starts (JAVA_TOOL_OPTIONS in ${service.dockerfile}).`)
+    plan.notes.push(note(/digest pins/))
+    if (info.env.has('JAVA_TOOL_OPTIONS') || info.inherited.has('JAVA_TOOL_OPTIONS')) {
+      plan.notes.push(`${service.dockerfile} already sets JAVA_TOOL_OPTIONS. A new ENV line before the start keeps that value and adds the agent.`)
+    }
+    return plan
+  },
+}

package/lib/stacks/k8s.mjs

@@ -0,0 +1,31 @@
+// Kubernetes containers that replace what this tool sets in the image: an env value, or the start command.
+// The image edit stays (it works with docker run). These steps say what to change in the manifest too.
+
+/**
+ * Manual steps for containers whose env sets `name`, which replaces the image value that loads OpenTelemetry.
+ * @param {import('../types.mjs').Service} service
+ * @param {string} name     e.g. NODE_OPTIONS
+ * @param {string} option   what the value needs, e.g. --require ...
+ * @param {(value: string) => boolean} has  true when a value already has it
+ * @returns {import('../types.mjs').Block[]}
+ */
+export function envOverrides(service, name, option, has) {
+  return (service.k8s ?? []).filter((k) => k.env && Object.prototype.hasOwnProperty.call(k.env, name) && !(k.env[name] !== null && has(k.env[name])))
+    .map((k) => ({ title: `Add the option to ${name} in ${k.file}`, lines: [
+      `${k.file} sets ${name} for the container ${k.container}. That value replaces the one in the image, so OpenTelemetry would not load.`,
+      `Add ${option} to the end of that value.`] }))
+}
+
+/**
+ * Manual steps for containers whose command (or args, for a CMD) replaces the image start that this tool changed.
+ * @param {import('../types.mjs').Service} service
+ * @param {'ENTRYPOINT'|'CMD'} instruction  the instruction that got the words
+ * @param {string} words    e.g. opentelemetry-instrument
+ * @returns {import('../types.mjs').Block[]}
+ */
+export function startOverrides(service, instruction, words) {
+  return (service.k8s ?? []).filter((k) => k.command || (k.args && instruction === 'CMD')).map((k) => ({
+    title: `Start the app with ${words} in ${k.file}`, lines: [
+      `${k.file} sets ${k.command ? 'command' : 'args'} for the container ${k.container}. That replaces the ${instruction} of the image.`,
+      `Put ${words} in front of the command there.`] }))
+}

package/lib/stacks/node.mjs

@@ -0,0 +1,358 @@
+/*
+ * Node.js: add @opentelemetry/api and @opentelemetry/auto-instrumentations-node
+ * with the package manager of the repo, then load OpenTelemetry when node
+ * starts: NODE_OPTIONS in the Dockerfile, or the option right after `node` in
+ * scripts.start.
+ *
+ * It loads the start file uknows-otel.cjs (install.ts NODE_REGISTER_FILE), which
+ * this tool adds next to package.json: it stops the app cleanly on SIGTERM after
+ * the last data. In an image, a COPY line in the final stage puts it in the
+ * WORKDIR. When the build context, the WORKDIR or .dockerignore makes that
+ * unsure, it loads the upstream register line instead and says why.
+ *
+ * Safety rule: node crashes at start when the register module is missing, so
+ * the start changes only when the packages surely reach the running app.
+ * Package managers run with install scripts turned off, so no code of the
+ * project or its dependencies runs.
+ */
+import { buildContext, finalWorkdir, ignoredBy } from '../context.mjs'
+import { unpicked } from '../settings.mjs'
+import { Doc, shellWords } from '../doc.mjs'
+import { addOption, dockerStart, insertBeforeStart, parseDockerfile } from '../dockerfile.mjs'
+import { NODE_REGISTER, NODE_REGISTER_FILE, NODE_START_FILE, PINS, RESOLVE, STACKS } from '../contract.mjs'
+import { list } from '../ui.mjs'
+import { upFrom } from '../workspace.mjs'
+import { envOverrides } from './k8s.mjs'
+
+const STACK = STACKS.find((s) => s.id === 'node')
+const START_FILE = NODE_REGISTER_FILE.path
+const START_TEXT = `${NODE_REGISTER_FILE.content}\n`
+/** The docs option for the start file. Its steps go in the advice when this tool cannot add the file. */
+const SIGTERM = STACK.options.find((o) => o.title.startsWith('Stops cleanly on SIGTERM'))
+/** A NODE_OPTIONS value or a start script that loads OpenTelemetry already: the upstream register or the start file. */
+const loads = (value) => value.includes(NODE_REGISTER) || value.includes(START_FILE)
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+const LOCKS = [['package-lock.json', 'npm'], ['npm-shrinkwrap.json', 'npm'], ['pnpm-lock.yaml', 'pnpm'], ['yarn.lock', 'yarn'],
+  ['bun.lockb', 'bun'], ['bun.lock', 'bun']]
+const DEFAULT_LOCK = { npm: 'package-lock.json', pnpm: 'pnpm-lock.yaml', yarn: 'yarn.lock' }
+const RUNS_NODE = /^(node|nodejs|npm|npx|yarn|pnpm)$|\.[cm]?js$/
+const BUNDLER = /\b(esbuild|webpack|rollup|tsup|ncc)\b/
+const VALUE_FLAGS = new Set(['-r', '--require', '--import', '--loader', '--experimental-loader', '--env-file', '-C', '--conditions'])
+
+/** @type {import('../types.mjs').Applier} */
+export const node = {
+  id: 'node',
+  plan(service, ctx) {
+    const { ws } = ctx
+    const out = { summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [] }
+    const pkgFile = join(service.dir, 'package.json')
+    const pkgText = read(ws, pkgFile)
+    let pkg = null
+    try { pkg = JSON.parse(pkgText) } catch { /* handled below */ }
+    if (pkgText === null) {
+      out.manual.push({ title: 'Add OpenTelemetry to your Node.js app', lines: [`This tool did not find ${pkgFile}.`,
+        'Add the packages with your package manager. Then start node with the option below.'],
+      snippets: [{ caption: 'Install', language: 'bash', code: STACK.install }, { caption: 'Start command', language: 'bash', code: STACK.start }] })
+      return out
+    }
+    if (!pkg || typeof pkg !== 'object' || Array.isArray(pkg)) {
+      out.manual.push({ title: `Fix ${pkgFile}`, lines: [`This tool cannot read ${pkgFile} as JSON.`, 'Fix the file. Then run npx @uknows/setup again.'] })
+      return out
+    }
+    // Too old for the packages: with --import or --require of the register module, node would not start.
+    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)) {
+      out.manual.push({ title: 'Use Node.js 18.19 or later', lines: [`This app uses Node.js ${service.runtimeVersion}.`,
+        'The OpenTelemetry packages need 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 out
+    }
+    const docker = service.dockerfile ? read(ws, service.dockerfile) : null
+    const info = docker !== null ? parseDockerfile(docker) : null
+    const start = info ? dockerStart(info) : null
+    const script = typeof pkg.scripts?.start === 'string' ? pkg.scripts.start : null
+    const entry = entryOf(info ? start?.argv : service.start?.argv ?? shellWords(script ?? ''), script)
+    const esm = /\.m[jt]s$/.test(entry ?? '') || (pkg.type === 'module' && !/\.c[jt]s$/.test(entry ?? ''))
+    const flag = PINS.node.flag(esm)
+
+    const guided = guidedBlock(service, ws, pkg, info, entry, flag)
+    if (guided) { out.manual.push(guided); return out }
+    // The docs settings for Node.js: only the resource detectors that ask no cloud metadata address (NETWORK.node).
+    for (const line of STACK.extraSettings?.lines ?? []) {
+      const at = line.indexOf('=')
+      out.extraSettings.push({ name: line.slice(0, at), value: line.slice(at + 1) })
+    }
+    const pm = packageManager(service.dir, pkg, ctx.repo ?? ws)
+    if (pm.outside) {
+      out.manual.push({ title: 'Run setup from the repo root', lines: [
+        `${service.dir === '.' ? 'This folder' : service.dir} is part of a workspace. Its ${base(pm.outside)} is in ${dirOf(pm.outside)}, `
+          + 'outside the folder this tool works in, so this tool cannot update it.',
+        'Run npx @uknows/setup in the repo root without --path. Then pick this service from the list, or use --all.'] })
+      out.stop = true
+      return out
+    }
+    const wanted = [...PINS.node.packages, ...(esm ? [PINS.node.esmPackage] : [])]
+    if (pm.cmd === 'bun' || pm.cmd === 'other' || pm.pnp) {
+      out.manual.push({ title: 'Add OpenTelemetry with your package manager',
+        lines: [pm.pnp ? 'This repo uses Yarn Plug\'n\'Play, so node cannot load the packages with --require alone.'
+          : 'This tool adds packages with npm, pnpm or yarn only.', 'Add the packages below as normal dependencies.',
+        pm.pnp ? 'Start the app with yarn node and the option below.' : 'Start node with the option below.'],
+        snippets: [{ caption: 'Packages', language: 'text', code: wanted.join('\n') },
+          { caption: 'Start command', language: 'bash', code: `${pm.pnp ? 'yarn ' : ''}${startLine(flag, entry)}` }] })
+      return out
+    }
+    const added = wanted.filter((name) => !pkg.dependencies?.[name])
+    // npm here writes the lock that npm ci in the image reads: a newer npm than the image has stops the run.
+    const npmBlock = added.length && pm.cmd === 'npm' && pm.lock && info ? npmGuard(service, info, ctx.tools?.npm) : null
+    if (npmBlock) {
+      out.manual.push(npmBlock)
+      out.stop = true
+      return out
+    }
+    if (added.length) {
+      const lock = pm.lock ?? (pm.cmd === 'npm' ? null : join(service.dir, DEFAULT_LOCK[pm.cmd]))
+      // No install scripts, no audit and no funding lines (they are about the app, not this change). npm with a
+      // lockfile and pnpm write only package.json and the lockfile.
+      const flags = pm.cmd === 'npm' ? ['--ignore-scripts', '--no-audit', '--no-fund', pm.lock ? '--package-lock-only' : '--no-package-lock']
+        : pm.cmd === 'pnpm' ? ['--lockfile-only', ...(ws.exists(join(service.dir, 'pnpm-workspace.yaml')) ? ['-w'] : [])]
+          : [pm.berry ? '--mode=skip-build' : '--ignore-scripts']
+      const why = `Add ${list(added)} with ${pm.cmd}.`
+      const lockOnly = pm.cmd === 'pnpm' || (pm.cmd === 'npm' && Boolean(pm.lock))
+      out.commands.push({ cwd: service.dir, cmd: pm.cmd, why, added, lockOnly,
+        args: pm.cmd === 'npm' ? ['install', '--save', ...flags, ...added] : ['add', ...flags, ...added],
+        undo: { cmd: pm.cmd, args: [pm.cmd === 'npm' ? 'uninstall' : 'remove', ...flags, ...added] },
+        touches: [pkgFile, ...(lock ? [lock] : [])] })
+      out.summary.push(why)
+      if (lockOnly) out.notes.push(`${pm.cmd} updates only package.json and ${base(lock)} here, so node_modules on this computer does not have the new packages yet. Run ${pm.cmd} install before you start the app on this computer. Your build installs them from ${base(lock)}.`)
+    }
+
+    if (info) {
+      const runsNode = start && (start.argv ?? [start.raw]).flatMap((w) => w.split(/\s+/)).some((w) => RUNS_NODE.test(base(w.replace(/^["']|["']$/g, ''))))
+      if (!runsNode) out.manual.push(startBlock(flag, entry, `the start command in ${service.dockerfile}`))
+      else {
+        const current = info.env.get('NODE_OPTIONS') ?? info.inherited.get('NODE_OPTIONS')
+        const done = Boolean(current && loads(current.value))
+        const place = done ? null : placeStartFile(service, ctx.repo ?? ws, info, ctx)
+        const option = place?.path ? PINS.node.flag(esm, place.path) : flag
+        let after = docker
+        if (place?.path) {
+          addStartFile(out, ws, place.file)
+          const copied = info.final.some((x) => (x.keyword === 'COPY' || x.keyword === 'ADD') && x.args.includes(START_FILE))
+          if (!copied) after = insertBeforeStart(after, [place.copy])
+        } else if (place) {
+          out.manual.push({ title: SIGTERM.title, required: false, lines: [place.why, NODE_START_FILE.fallback, ...SIGTERM.steps], snippets: SIGTERM.snippets })
+        }
+        after = addOption(after, 'NODE_OPTIONS', option, loads)
+        if (after !== docker) {
+          out.edits.push({ file: service.dockerfile, before: docker, after, why: place?.path ? `Load OpenTelemetry when node starts. ${NODE_START_FILE.copy}` : 'Load OpenTelemetry when node starts.' })
+          out.summary.push(`Load OpenTelemetry when node starts (NODE_OPTIONS in ${service.dockerfile}).`)
+          if (current) {
+            out.notes.push(`${service.dockerfile} already sets NODE_OPTIONS. A new ENV line before the start keeps that value and adds the option.`)
+          }
+        }
+        out.manual.push(...envOverrides(service, 'NODE_OPTIONS', option, loads))
+      }
+    } else if (script !== null && service.start?.kind !== 'procfile' && shellWords(script)?.[0] === 'node') {
+      if (!loads(script)) {
+        // npm start runs the script in the package folder, so ./uknows-otel.cjs is the file next to package.json.
+        // The start file is only for a start that surely has it: no Dockerfile that could build this app without it, not ignored by git.
+        const unsure = scriptStartUnsure(service, ctx)
+        const after = editStartScript(pkgText, unsure ? flag : PINS.node.flag(esm, `./${START_FILE}`))
+        if (after === null) out.manual.push(startBlock(flag, entry, `scripts.start in ${pkgFile}`))
+        else {
+          if (unsure) out.manual.push({ title: SIGTERM.title, required: false, lines: [unsure, NODE_START_FILE.fallback, ...SIGTERM.steps], snippets: SIGTERM.snippets })
+          else addStartFile(out, ws, join(service.dir, START_FILE))
+          out.edits.push({ file: pkgFile, before: pkgText, after, why: 'Load OpenTelemetry when node starts.' })
+          out.summary.push(`Load OpenTelemetry when node starts (start script in ${pkgFile}).`)
+        }
+      }
+    } else {
+      out.manual.push(startBlock(flag, entry, script !== null ? `scripts.start in ${pkgFile}` : null))
+    }
+    return out
+  },
+}
+
+/**
+ * Where the start file goes in the image: {file, path, copy}, or {why} when this tool is not sure. The file sits
+ * next to package.json. The COPY line takes it from the build context into the WORKDIR of the final stage.
+ */
+function placeStartFile(service, view, info, ctx = {}) {
+  const file = join(service.dir, START_FILE)
+  const values = { file, dockerfile: service.dockerfile }
+  const workdir = finalWorkdir(info)
+  if (!workdir) return { why: fill(NODE_START_FILE.noWorkdir, values) }
+  const context = buildContext(view, service.dockerfile, info, service.dir)
+  if (context === null) return { why: fill(NODE_START_FILE.noContext, values) }
+  if (context !== '.' && !file.startsWith(`${context}/`)) return { why: fill(NODE_START_FILE.outside, values) }
+  const source = context === '.' ? file : file.slice(context.length + 1)
+  const ignore = ignoredBy(view, context, service.dockerfile, source)
+  if (ignore) return { why: fill(NODE_START_FILE.ignored, { ...values, ignore }) }
+  // The pipeline builds from a checkout: a file that git ignores never reaches it, and the COPY line fails there.
+  if (!read(view, file) && ctx.ignored?.(file)) return { why: fill(NODE_START_FILE.gitignored, values) }
+  const dir = workdir === '/' ? '' : workdir
+  return { file, path: `${dir}/${START_FILE}`, copy: `COPY ${source} ${dir}/` }
+}
+
+/**
+ * Why a start script must not load the start file, or null when it can: git ignores the file, so a checkout lacks it,
+ * or the repo has a Dockerfile that this tool did not pick for any service (an image built from it would not copy the
+ * file, and node stops at start when a --require file is missing). The upstream register line has no such file.
+ */
+function scriptStartUnsure(service, ctx) {
+  const view = ctx.repo ?? ctx.ws
+  const file = join(service.dir, START_FILE)
+  if (!read(view, file) && ctx.ignored?.(file)) return fill(NODE_START_FILE.gitignored, { file })
+  const others = unpicked(ctx)
+  return others.length ? fill(NODE_START_FILE.dockerfiles, { file, dockerfiles: list(others.slice(0, 5)) }) : null
+}
+
+/** Add the start file when it is not there. A file that is there stays as it is: it can be the user's own copy. */
+function addStartFile(out, ws, file) {
+  const current = read(ws, file)
+  if (current === null) {
+    out.edits.push({ file, before: null, after: START_TEXT, why: fill(NODE_START_FILE.add, { file }) })
+    out.summary.push(fill(NODE_START_FILE.add, { file }))
+  } else if (current !== START_TEXT) out.notes.push(fill(NODE_START_FILE.keep, { file }))
+}
+
+/**
+ * A required step when npm on this computer is newer (by major version) than the npm of the image that runs npm ci:
+ * the npm of a RUN npm install -g npm@X line, else the npm that the node image of that stage comes with (PINS.node.npm).
+ * null when the versions fit or are not known.
+ */
+export function npmGuard(service, info, have) {
+  const haveMajor = Number(/^(\d+)\./.exec(have ?? '')?.[1] ?? NaN)
+  if (!Number.isFinite(haveMajor)) return null
+  const runs = (stage) => stage.instructions.filter((x) => x.keyword === 'RUN')
+  const text = (x) => (x.argv ? x.argv.join(' ') : x.args)
+  let image = null, line = null, need = null
+  for (const stage of info.stages) {
+    for (const x of runs(stage)) {
+      const pin = /\bnpm\s+(?:install|i)\s+(?:-g|--global)\s+npm@(\d+)/.exec(text(x))
+      if (pin) { need = Number(pin[1]); image = `npm@${pin[1]}`; line = x.start + 1 }
+    }
+  }
+  if (need === null) {
+    const stages = info.stages, byName = new Map(stages.filter((st) => st.name).map((st) => [st.name.toLowerCase(), st]))
+    const stage = stages.find((st) => runs(st).some((x) => /\bnpm\s+(?:ci|install|i)\b/.test(text(x)))) ?? stages.at(-1)
+    if (!stage) return null
+    let from = stage.image
+    for (let hop = 0; hop < 5 && byName.has(from.toLowerCase()); hop++) from = byName.get(from.toLowerCase()).image
+    const m = /(?:^|\/)node:(\d+)(?:\.(\d+))?/.exec(from)
+    if (!m) return null
+    const v = [Number(m[1]), m[2] === undefined ? 99 : Number(m[2])]
+    need = PINS.node.npm.find(([[a, b]]) => v[0] > a || (v[0] === a && v[1] >= b))?.[1] ?? null
+    image = from
+    line = (info.instructions.find((x) => x.keyword === 'FROM' && x.args.split(/\s+/).includes(stage.image))?.start ?? 0) + 1
+  }
+  if (need === null || haveMajor <= need) return null
+  const values = { file: service.dockerfile, line, image, need, have }
+  const fill = (t) => t.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+  return { title: fill(RESOLVE.npm.title), lines: RESOLVE.npm.lines.map(fill) }
+}
+
+/** Cases where loading the register module cannot work: guided only, no packages. */
+function guidedBlock(service, ws, pkg, info, entry, flag) {
+  if (service.frameworks.includes('next')) {
+    return { title: 'Next.js needs its own OpenTelemetry setup', lines: ['Next.js builds its server code, so the --require option cannot load OpenTelemetry.',
+      'Follow the OpenTelemetry guide in the Next.js docs. It adds an instrumentation.ts file.', 'Keep the 5 UKNOWS settings. That setup reads them.'] }
+  }
+  if (info && (service.frameworks.includes('nitro') || service.frameworks.includes('nuxt'))) {
+    const install = info.final.some((x) => x.keyword === 'RUN' && /\b(npm (ci|install|i)|pnpm (install|i)|yarn)\b/.test(x.args))
+    const copies = info.final.filter((x) => x.keyword === 'COPY' || x.keyword === 'ADD')
+    if (!install && !copies.some((x) => /node_modules/.test(x.args) || !/\.output/.test(x.args))) {
+      return { title: 'Put node_modules in the final image', verify: true, lines: [`The final stage of ${service.dockerfile} copies only the built server, so node cannot load OpenTelemetry.`,
+        'Install the packages in the final stage, or copy node_modules into it.', 'Then run npx @uknows/setup again.'] }
+    }
+  }
+  const bundler = BUNDLER.exec(typeof pkg.scripts?.build === 'string' ? pkg.scripts.build : '')
+  if (bundler && !(entry && ws.exists(join(service.dir, entry.replace(/^\.\//, ''))))) {
+    return { title: 'Load OpenTelemetry in a bundled app', lines: [`The build script bundles the app with ${bundler[1]}. OpenTelemetry cannot change bundled packages.`,
+      'Add the packages below as normal dependencies. In the bundler config, mark them and the libraries to trace as external.',
+      'Start node with the option below.'],
+    snippets: [{ caption: 'Install', language: 'bash', code: STACK.install }, { caption: 'Start command', language: 'bash', code: startLine(flag, entry) }] }
+  }
+  return null
+}
+
+/**
+ * The package manager from the packageManager field, else from the lockfile of the service folder or of
+ * the workspace root above it (a parent folder whose package.json has workspaces, or with pnpm-workspace.yaml).
+ * The search goes on above the --path folder, up to the top of the git repo (view.top). A workspace root or
+ * its lockfile up there is `outside`: this tool cannot update it.
+ */
+export function packageManager(dir, pkg, view) {
+  const field = typeof pkg.packageManager === 'string' ? /^(npm|pnpm|yarn|bun)@(\d+)/.exec(pkg.packageManager) : null
+  let cmd = field ? field[1] : typeof pkg.packageManager === 'string' ? 'other' : null
+  let lock = null, outside = null
+  for (const d of upFrom(dir, view.top ?? '.')) {
+    const pnpmRoot = view.exists(join(d, 'pnpm-workspace.yaml'))
+    const marker = pnpmRoot || /"workspaces"\s*:/.test(read(view, join(d, 'package.json')) ?? '')
+    const hit = (d === dir || marker) && LOCKS.find(([file, owner]) => (!cmd || cmd === owner) && read(view, join(d, file)) !== null)
+    if ((d === '..' || d.startsWith('../')) && (marker || hit)) { outside = join(d, hit ? hit[0] : pnpmRoot ? 'pnpm-workspace.yaml' : 'package.json'); break }
+    if (hit) { lock = join(d, hit[0]); cmd = hit[1]; break }
+  }
+  cmd ??= 'npm'
+  const home = lock ? dirOf(lock) : dir
+  const rc = read(view, join(home, '.yarnrc.yml'))
+  const berry = cmd === 'yarn' && (field ? Number(field[2]) >= 2 : rc !== null || /^__metadata:/m.test(read(view, lock ?? '') ?? ''))
+  const pnp = cmd === 'yarn' && (view.exists(join(home, '.pnp.cjs')) || view.exists(join(home, '.pnp.js'))
+    || (berry && !/^\s*nodeLinker\s*:\s*["']?(node-modules|pnpm)/m.test(rc ?? '')))
+  return { cmd, lock, pnp, berry, outside }
+}
+
+/** The JS file that node runs, from a start argv. `npm start` and friends read scripts.start. */
+export function entryOf(argv, script) {
+  let words = argv ?? null
+  if (words && /^(npm|yarn|pnpm)$/.test(base(words[0])) && (words[1] === 'start' || (words[1] === 'run' && words[2] === 'start'))) words = shellWords(script ?? '')
+  if (!words?.length) return null
+  if (/\.[cm]?[jt]s$/.test(words[0])) return words[0]
+  if (base(words[0]) !== 'node') return null
+  for (let i = 1; i < words.length; i++) {
+    if (!words[i].startsWith('-')) return words[i]
+    if (VALUE_FLAGS.has(words[i])) i++
+  }
+  return null
+}
+
+/** Insert the option right after `node` in scripts.start. Changes only that JSON string. null when unsure. */
+function editStartScript(text, flag) {
+  const doc = new Doc(text)
+  const from = doc.find(/"scripts"\s*:/)
+  const i = from < 0 ? -1 : doc.find(/"start"\s*:\s*"/, from)
+  if (i < 0) return null
+  const line = doc.get(i)
+  const m = /("start"\s*:\s*)("(?:[^"\\]|\\.)*")/.exec(line)
+  if (!m) return null
+  const value = JSON.parse(m[2]).replace(/^(\s*node)(?=\s|$)/, `$1 ${flag}`)
+  doc.set(i, line.slice(0, m.index + m[1].length) + JSON.stringify(value) + line.slice(m.index + m[0].length))
+  const after = doc.toString()
+  try {
+    const expected = JSON.parse(text)
+    expected.scripts.start = value
+    return JSON.stringify(JSON.parse(after)) === JSON.stringify(expected) ? after : null
+  } catch { return null }
+}
+
+function startLine(flag, entry) {
+  return STACK.start.replace(PINS.node.requireFlag, flag).replace(/server\.js$/, entry ?? 'server.js')
+}
+
+function startBlock(flag, entry, where) {
+  return { title: 'Load OpenTelemetry when node starts',
+    lines: [where ? `This tool cannot change ${where} safely.` : 'This tool did not find the command that starts the app.',
+      'Add the option below to the node command that starts the app. Or set NODE_OPTIONS to it where the app runs.',
+      ...STACK.notes.filter((n) => !entry && /server\.js/.test(n))],
+    snippets: [{ caption: 'Start command', language: 'bash', code: startLine(flag, entry) },
+      { caption: 'Or set NODE_OPTIONS', language: 'bash', code: `NODE_OPTIONS="${flag}"` }] }
+}
+
+const base = (word) => (word ?? '').split('/').pop()
+const join = (dir, file) => (dir === '.' ? file : `${dir}/${file}`)
+const dirOf = (path) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '.')
+
+function read(ws, path) {
+  try { return path ? ws.read(path) : null } catch { return null }
+}

package/lib/stacks/otel.mjs

@@ -0,0 +1,63 @@
+// The app already uses OpenTelemetry: keep its packages and start command. settings.mjs adds the 3 shared
+// settings (no none lines, so the metrics and logs of the app keep going where they go now).
+import { AZURE_MONITOR, DOCS_URL, DOTNET_TRACES_ONLY, INGEST_ENDPOINT, OTHER_EXPORTERS_NOTE, STACKS, TRACES_ONLY_NOTE, TRACES_ONLY_PLAN } from '../contract.mjs'
+
+const STACK = STACKS.find((s) => s.id === 'otel')
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+
+/**
+ * The notes of the docs page, and after its .NET note the 2 notes that only setup prints: the pages name UKNOWS only,
+ * and these name products that setup finds in a repo.
+ */
+export const OTEL_NOTES = STACK.notes.flatMap((n) => (n === DOTNET_TRACES_ONLY.note ? [n, AZURE_MONITOR.otelNote, OTHER_EXPORTERS_NOTE] : [n]))
+
+/** The notes that name languages or features. A run keeps the parts that fit what it found. */
+const NOTE = {
+  /** "For Python, use ... For Go, use ...": 1 sentence for each language. */
+  exporter: OTEL_NOTES.find((n) => /^For Python, use /.test(n)),
+  collector: OTEL_NOTES.find((n) => /Collector/.test(n)),
+  azure: AZURE_MONITOR.otelNote,
+}
+/** The label that each sentence of NOTE.exporter starts with. */
+const EXPORTER_LANG = { python: 'Python', go: 'Go' }
+/** The SDKs that send metrics and logs over OTLP by default. settings.mjs uses the traces-only settings for them. */
+const SDK_SIGNALS = new Set(['node', 'python', 'java'])
+
+/**
+ * The notes of the docs page for this run. With no language known (the menu pick "I already use OpenTelemetry"),
+ * every note stays. Else only the notes for this language and for what the repo uses:
+ *   - the exporter sentence of this language only (Python, Go),
+ *   - the traces-only note only when settings.mjs did not already say what this run does with traces only,
+ *     and in a form for this language,
+ *   - the .NET note only for .NET, and only when this run does not use the traces-only settings,
+ *   - the Azure Monitor note only when the code calls Azure Monitor,
+ *   - the other-exporters note never: existing.mjs gives it as advice when the repo has another exporter.
+ * @param {string[]} notes
+ * @param {{lang?: string|null, existing?: Partial<import('../types.mjs').Existing>, tracesOnly?: boolean, endpoint?: string, docs?: string}} found
+ *   endpoint and docs: the ingest address and the docs page of this run.
+ * @returns {string[]}
+ */
+export function otelNotes(notes, { lang = null, existing = {}, tracesOnly = false, endpoint = INGEST_ENDPOINT, docs = DOCS_URL } = {}) {
+  if (!lang) return notes
+  const anchors = existing.anchors ?? []
+  return notes.flatMap((note) => {
+    if (note === NOTE.exporter) {
+      const label = EXPORTER_LANG[lang]
+      return note.split(/(?<=\.) (?=For )/).filter((sentence) => label && sentence.startsWith(`For ${label}, `))
+    }
+    if (note === NOTE.collector) return [`${note} See ${docs}?method=manual&stack=otel#install-app.`]
+    if (note === TRACES_ONLY_NOTE) return tracesOnly || SDK_SIGNALS.has(lang) ? [] : [fill(TRACES_ONLY_PLAN.none, { endpoint })]
+    if (note === DOTNET_TRACES_ONLY.note) return lang === 'dotnet' && !tracesOnly ? [note] : []
+    if (note === NOTE.azure) return anchors.some((a) => a.kind === 'azure-call' || a.kind === 'appinsights-call') ? [note] : []
+    if (note === OTHER_EXPORTERS_NOTE) return []
+    return [note]
+  })
+}
+
+/** @type {import('../types.mjs').Applier} */
+export const otel = {
+  id: 'otel',
+  plan() {
+    return { summary: [STACK.summary], edits: [], commands: [], extraSettings: [], manual: [], notes: [...OTEL_NOTES] }
+  },
+}

package/lib/stacks/python-bootstrap.mjs

@@ -0,0 +1,71 @@
+/*
+ * What `opentelemetry-bootstrap -a requirements` prints, without a Python
+ * environment. Source: bootstrap_gen.py of opentelemetry-python-contrib
+ * v0.66b1. Upstream checks the installed packages; this tool reads the
+ * requirement names instead, plus a few packages that the common frameworks
+ * always pull in (IMPLIED).
+ *
+ * Left out on purpose: openai-v2 and vertexai (not pinned to 0.66b1),
+ * psutil -> system-metrics (metrics are off) and the upstream quirk that maps
+ * pydantic to tortoiseorm. The default logging package comes only with the UKNOWS
+ * log bridge (logs: true). On its own, in 0.66b1, it adds an OpenTelemetry
+ * LoggingHandler to the root logger, also with OTEL_LOGS_EXPORTER=none. Then Python
+ * never uses its last-resort handler, so the warnings and errors of loggers with no
+ * handler no longer reach stderr. With the bridge, OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION
+ * =false keeps it off the root logger and the package gives only its LoggingHandler.
+ */
+import { compareVersion } from '../versions.mjs'
+
+/** Always printed. */
+export const DEFAULTS = ['asyncio', 'dbapi', 'exceptions', 'sqlite3', 'threading', 'urllib', 'wsgi']
+
+/** [normalized library name, instrumentation suffixes], in upstream order. */
+export const LIBRARIES = [
+  ['aio-pika', ['aio-pika']], ['aiohttp', ['aiohttp-client', 'aiohttp-server']], ['aiokafka', ['aiokafka']],
+  ['aiopg', ['aiopg']], ['asgiref', ['asgi']], ['asyncclick', ['asyncclick']], ['asyncpg', ['asyncpg']],
+  ['boto3', ['boto3sqs']], ['botocore', ['botocore']], ['aiobotocore', ['botocore']],
+  ['cassandra-driver', ['cassandra']], ['scylla-driver', ['cassandra']], ['celery', ['celery']], ['click', ['click']],
+  ['confluent-kafka', ['confluent-kafka']], ['django', ['django']], ['falcon', ['falcon']], ['fastapi', ['fastapi']],
+  ['flask', ['flask']], ['grpcio', ['grpc']], ['httpx', ['httpx']], ['httpx2', ['httpx']], ['jinja2', ['jinja2']],
+  ['kafka-python', ['kafka-python']], ['mysql-connector-python', ['mysql']], ['mysqlclient', ['mysqlclient']],
+  ['pika', ['pika']], ['psycopg', ['psycopg']], ['psycopg2', ['psycopg2']], ['psycopg2-binary', ['psycopg2']],
+  ['pymemcache', ['pymemcache']], ['pymongo', ['pymongo']], ['pymssql', ['pymssql']], ['pymysql', ['pymysql']],
+  ['pyramid', ['pyramid']], ['redis', ['redis']], ['remoulade', ['remoulade']], ['requests', ['requests']],
+  ['sqlalchemy', ['sqlalchemy']], ['starlette', ['starlette']], ['structlog', ['structlog']], ['tornado', ['tornado']],
+  ['tortoise-orm', ['tortoiseorm']], ['urllib3', ['urllib3']],
+]
+
+/**
+ * The first contrib release of each instrumentation package on PyPI (tools/check-python-sets.mjs). A set older than
+ * this leaves the package out, because it does not exist there. Packages missing here are older than every set.
+ */
+export const SINCE = { exceptions: '0.64b0', structlog: '0.65b0', asyncclick: '0.53b0', pymssql: '0.51b0', click: '0.50b0',
+  aiokafka: '0.49b0', threading: '0.46b0', psycopg: '0.45b0', asyncio: '0.44b0', 'aiohttp-server': '0.42b0', cassandra: '0.41b0',
+  mysqlclient: '0.40b0', tortoiseorm: '0.36b0', 'aio-pika': '0.32b0', boto3sqs: '0.32b0', 'confluent-kafka': '0.32b0',
+  remoulade: '0.32b0', 'kafka-python': '0.28b0', pika: '0.25b0', httpx: '0.23b0', urllib3: '0.20b0', urllib: '0.17b0' }
+
+/** Packages that a framework always installs, so upstream would see them too. */
+export const IMPLIED = { fastapi: ['starlette'], django: ['asgiref'], flask: ['jinja2'], requests: ['urllib3'], boto3: ['botocore'] }
+
+/** PEP 503 name: lower case, runs of - _ . become -. */
+export const normalize = (name) => name.toLowerCase().replace(/[-_.]+/g, '-')
+
+/**
+ * The instrumentation packages for these requirement names: the defaults,
+ * then 1 per matching library in table order, without repeats. Packages that
+ * are newer than version (SINCE) are left out.
+ * @param {Iterable<string>} names  normalized requirement names
+ * @param {string} version          the contrib release of the set, e.g. '0.66b1'
+ * @param {{floor?: string|null, logs?: boolean}} [options]  floor: write '>=' limits from this release (or the first
+ *   release of the package, when it is newer) instead of '==' pins, for uv and Poetry projects. logs: add the logging
+ *   package, for the UKNOWS log bridge
+ * @returns {string[]} e.g. ['opentelemetry-instrumentation-asyncio==0.66b1', ...]
+ */
+export function bootstrap(names, version, { floor = null, logs = false } = {}) {
+  const have = new Set(names)
+  for (const name of [...have]) for (const extra of IMPLIED[name] ?? []) have.add(extra)
+  const suffixes = [...DEFAULTS, ...(logs ? ['logging'] : [])]
+  for (const [library, list] of LIBRARIES) if (have.has(library)) suffixes.push(...list)
+  return [...new Set(suffixes)].filter((x) => !SINCE[x] || compareVersion(SINCE[x], version) <= 0)
+    .map((x) => `opentelemetry-instrumentation-${x}${floor ? `>=${[floor, SINCE[x] ?? floor].sort(compareVersion).at(-1)}` : `==${version}`}`)
+}