@uknows/setup 0.0.0-stage → 0.1.0

package/lib/settings.mjs

@@ -0,0 +1,280 @@
+// Where the 5 UKNOWS settings go for 1 service, and the edits that put them there: the final stage of
+// the Dockerfile, else the env of the Kubernetes container, else <dir>/otel.env. Never the key.
+// Settings that would keep traces away from UKNOWS (another address, a traces-only override, a Kubernetes
+// env that replaces the image value) become manual steps, never silent successes.
+import { INGEST_ENDPOINT, SECRET, SETTINGS, SETTINGS_FILE, STACKS } from './contract.mjs'
+import { Doc, indentOf } from './doc.mjs'
+import { parseDockerfile, setEnv } from './dockerfile.mjs'
+import { list } from './ui.mjs'
+
+const NAMES = SETTINGS.map((s) => s.name)
+const [SERVICE, ENDPOINT] = NAMES
+const COLLECTOR = STACKS.find((s) => s.id === 'otel').notes.find((n) => /Collector/.test(n))
+const at = (dir, name) => (dir === '.' ? name : `${dir}/${name}`)
+const blank = (line) => !line.trim() || /^\s*#/.test(line)
+const quote = (value) => `"${value.replace(/["\\]/g, '\\$&')}"`
+const unquote = (raw) => /^\s*(["'])(.*)\1\s*(#.*)?$/.exec(raw)?.[2] ?? raw.trim().replace(/\s+#.*$/, '')
+const KEY_NAME = new RegExp(`name:\\s*["']?${SECRET.name}["']?\\s*(#.*)?$`)
+const KEY_LINE = new RegExp(`${SECRET.name}["']?\\s*[=:]\\s*(.*)$|^\\s*ENV\\s+${SECRET.name}\\s+(.*)$`, 'i')
+/** Flow style: - {name: OTEL_EXPORTER_OTLP_HEADERS, value: "..."} */
+const KEY_FLOW = new RegExp(`name:\\s*["']?${SECRET.name}["']?\\s*,\\s*value:\\s*(["']?)([^"'},]*)\\1`)
+/** The key header anywhere, for any other way to write it. */
+const KEY_HEADER = new RegExp(`${SECRET.header}\\s*=\\s*([^\\s"',}\\]]+)`, 'gi')
+const PLACEHOLDER = /[<>$]|\{\{|secretref:|secretKeyRef|=$|^\*+$/
+const sameAs = (endpoint) => (value) => value.replace(/\/+$/, '') === endpoint
+const hideUser = (url) => url.replace(/\/\/[^/@]*@/, '//')
+/**
+ * OpenTelemetry settings that win over the 5 for traces, or turn the SDK off: [name, bad(value), fix].
+ * Values are never printed for headers, which can hold a key.
+ */
+const overrideRules = (endpoint) => [
+  ['OTEL_EXPORTER_OTLP_TRACES_ENDPOINT', (v) => !sameAs(endpoint)(v.replace(/\/v1\/traces\/?$/, '')), `Remove it, or set it to ${endpoint}/v1/traces.`],
+  ['OTEL_EXPORTER_OTLP_TRACES_PROTOCOL', (v) => v !== 'http/protobuf', 'Remove it, or set it to http/protobuf.'],
+  ['OTEL_EXPORTER_OTLP_TRACES_HEADERS', () => true, `Remove it, so traces use the key in ${SECRET.name}.`],
+  ['OTEL_TRACES_EXPORTER', (v) => !v.split(',').map((x) => x.trim()).includes('otlp'), 'Remove it, or set it to otlp.'],
+  ['OTEL_SDK_DISABLED', (v) => v.trim().toLowerCase() === 'true', 'Remove it, or set it to false.'],
+]
+
+/**
+ * @param {import('./types.mjs').Service} service
+ * @param {import('./types.mjs').Ctx} ctx
+ * @param {import('./types.mjs').Setting[]} [extra]
+ * @returns {import('./types.mjs').SettingsPlan}
+ */
+export function settingsPlan(service, ctx, extra = []) {
+  const { ws } = ctx
+  const ingest = ctx.endpoint ?? INGEST_ENDPOINT
+  const sameEndpoint = sameAs(ingest)
+  const pairs = [...SETTINGS.map((s) => [s.name, s.name === SERVICE ? ctx.name : s.name === ENDPOINT ? ingest : s.value]),
+    ...extra.filter((s) => s.name !== SECRET.name && !NAMES.includes(s.name)).map((s) => [s.name, String(s.value)])]
+  const target = (service.dockerfile && ws.read(service.dockerfile) !== null && dockerTarget(ws, service.dockerfile))
+    || (service.k8s ?? []).map((k) => k8sTarget(ws, k)).find(Boolean)
+    || envTarget(ws, at(service.dir, SETTINGS_FILE.path))
+  const plan = { target: { kind: target.kind, file: target.file }, edits: [], summary: [], manual: [], notes: [] }
+
+  const keyFiles = [...new Set([service.dockerfile, ...(service.k8s ?? []).map((k) => k.file),
+    at(service.dir, SETTINGS_FILE.path), at(service.dir, '.env.example')])].filter((f) => f && hasKey(ws.read(f)))
+  // A file that holds a key is never edited: the diff and the manifest hunks must not show it.
+  const keyInTarget = keyFiles.includes(target.file)
+  if (keyFiles.length) {
+    plan.manual.push({ title: 'Remove the key from your repo', lines: [...keyFiles.map((f) => `Remove ${SECRET.name} from ${f}.`),
+      'Get a new key. The old key stays in your git history.', SECRET.summary,
+      ...(keyInTarget ? [`Then run npx @uknows/setup again. It adds the settings to ${target.file}.`] : [])] })
+  }
+  if (keyInTarget) return plan
+  if (target.flow) {
+    plan.manual.push({ title: `Add the UKNOWS settings to ${target.file}`,
+      lines: [`The env of ${target.where} is on 1 line. This tool does not change that format.`, 'Add these settings to the env of the container.'],
+      snippets: [{ caption: target.file, language: 'yaml', code: ['env:', ...envItems(pairs, 2, 4)].join('\n') }] })
+    return plan
+  }
+
+  // Another address is kept. Then its protocol and exporters belong to that pipeline: keep them, add none.
+  const endpoint = target.current.get(ENDPOINT)
+  const kept = endpoint !== undefined && !(endpoint !== null && sameEndpoint(endpoint))
+  if (kept) {
+    plan.manual.push({ title: 'Check where this app sends data', lines: [
+      endpoint === null ? `${target.where} sets ${ENDPOINT} from another source.` : `${target.where} sends data to ${hideUser(endpoint)}.`,
+      'This tool keeps that address and the other OpenTelemetry settings of the app.', COLLECTOR,
+      'To send data to UKNOWS directly, set these settings instead.'],
+    snippets: [{ caption: 'Settings for UKNOWS', language: 'text', code: pairs.filter(([name]) => NAMES.includes(name) && name !== SERVICE)
+      .map(([name, value]) => `${name}=${value}`).join('\n') }] })
+  }
+  const set = []
+  for (const [name, value] of pairs) {
+    const current = target.current.get(name)
+    if (current === undefined) { if (!kept || !NAMES.includes(name) || name === SERVICE) set.push([name, value]) }
+    else if (current === value || name === ENDPOINT) continue
+    else if (current === null) plan.notes.push(`${target.where} sets ${name} from another source. This tool keeps it.`)
+    else if (!NAMES.includes(name) || kept) plan.notes.push(`${target.where} already sets ${name}. This tool keeps that value.`)
+    else {
+      if (name !== SERVICE) plan.notes.push(`${target.where} sets ${name} to ${current}. This tool changes it to ${value}.`)
+      set.push([name, value])
+    }
+  }
+  plan.manual.push(...overrides(service, target, pairs, ingest))
+  if (!set.length) return plan
+  const added = set.every(([name]) => target.current.get(name) === undefined) && NAMES.every((n) => set.some(([name]) => name === n))
+  const extras = set.map(([name]) => name).filter((name) => !NAMES.includes(name))
+  plan.summary.push(added ? `Add the 5 UKNOWS settings${extras.length ? ` and ${list(extras)}` : ''} to ${target.where}.`
+    : `Set ${list(set.map(([name]) => name))} in ${target.where}.`)
+  plan.edits.push({ file: target.file, before: target.before, after: target.write(set), why: added ? 'Add the UKNOWS settings.' : 'Set the UKNOWS settings.' })
+  return plan
+}
+
+/**
+ * True when the text sets OTEL_EXPORTER_OTLP_HEADERS to something that is not a placeholder (in any env format,
+ * Kubernetes flow style too), or holds x-uknows-key=<a real value> anywhere. Never returns the value.
+ */
+export function hasKey(text) {
+  const lines = text?.includes(SECRET.name) || text?.toLowerCase().includes(SECRET.header) ? text.split(/\r?\n/) : []
+  return lines.some((line, i) => {
+    if (/^\s*#/.test(line)) return false
+    if ([...line.matchAll(KEY_HEADER)].some((m) => !PLACEHOLDER.test(m[1]))) return true
+    let m = KEY_LINE.exec(line), value = null
+    if (KEY_FLOW.test(line)) value = KEY_FLOW.exec(line)[2].trim()
+    else if (!m && KEY_NAME.test(line)) {
+      for (const next of lines.slice(i + 1, i + 4)) if ((m = /^\s*value:\s*(.*)$/.exec(next)) || /^\s*-/.test(next)) break
+    }
+    value ??= m ? unquote((m[1] ?? m[2]).replace(/\s*\\$/, '')) : ''
+    return Boolean(value) && !PLACEHOLDER.test(value)
+  })
+}
+
+/** Take the key value out of a line, for anything this tool prints from a repo file. */
+export const redactKey = (line) => line.replace(KEY_HEADER, (m, value) => m.slice(0, m.length - value.length) + '***')
+
+/**
+ * Manual steps for settings that keep traces from UKNOWS: an overrideRules() value where the settings go, and a
+ * Kubernetes container env that replaces the image values with something else.
+ */
+function overrides(service, target, pairs, endpoint) {
+  const sameEndpoint = sameAs(endpoint)
+  const sources = [{ where: target.where, file: target.file, env: target.current }]
+  if (target.kind !== 'k8s') {
+    for (const k of (service.k8s ?? []).filter((x) => x.env)) {
+      sources.push({ where: `${k.file} (container ${k.container})`, file: k.file, env: new Map(Object.entries(k.env)), k8s: true })
+    }
+  }
+  const blocks = []
+  for (const { where, file, env, k8s } of sources) {
+    for (const [name, bad, fix] of overrideRules(endpoint)) {
+      if (!env.has(name) || (env.get(name) !== null && !bad(env.get(name)))) continue
+      const value = env.get(name)
+      const shown = value === null ? ' from another source' : /HEADERS/.test(name) ? '' : ` to ${hideUser(value)}`
+      blocks.push({ title: `Check ${name}`, lines: [`${where} sets ${name}${shown}.`,
+        name === 'OTEL_SDK_DISABLED' ? 'That turns OpenTelemetry off.' : 'It wins over the UKNOWS settings, so traces would not reach UKNOWS.', fix] })
+    }
+    if (!k8s) continue
+    // The container env replaces the ENV of the image for the same names.
+    const differs = (name, value, current) => current === null || (current !== value && !(name === ENDPOINT && sameEndpoint(current)))
+    const differ = pairs.filter(([name, value]) => NAMES.includes(name) && env.has(name) && differs(name, value, env.get(name)))
+    if (differ.length) {
+      blocks.push({ title: `Check the UKNOWS settings in ${file}`, lines: [
+        `${where} sets ${list(differ.map(([name]) => name))}. The container env replaces the values in ${target.file}.`,
+        'Set them to the values below there, or remove them.'],
+      snippets: [{ caption: file, language: 'text', code: differ.map(([name, value]) => `${name}=${value}`).join('\n') }] })
+    }
+  }
+  return blocks
+}
+
+function dockerTarget(ws, file) {
+  const before = ws.read(file)
+  const info = parseDockerfile(before)
+  // Values from the stages the final stage builds on count too: the image has them.
+  const current = new Map([...info.inherited, ...info.env].map(([name, entry]) => [name, entry.value]))
+  return { kind: 'dockerfile', file, where: file, before, current, write: (set) => setEnv(before, set) }
+}
+
+function envTarget(ws, file) {
+  const before = ws.read(file)
+  const doc = new Doc(before ?? '')
+  const lines = doc.lines.map((line) => /^\s*(?:export\s+)?([A-Za-z_]\w*)\s*=(.*)$/.exec(line)).filter(Boolean)
+  const current = new Map(lines.map((m) => [m[1], unquote(m[2])]))
+  return { kind: 'env-file', file, where: file, before, current, write(set) {
+    for (const [name, value] of set) {
+      const i = doc.find(new RegExp(`^\\s*(export\\s+)?${name}\\s*=`))
+      if (i >= 0) doc.set(i, doc.get(i).replace(/=.*$/, `=${value}`))
+      else doc.insert(doc.length, `${name}=${value}`)
+    }
+    return doc.toString()
+  } }
+}
+
+/** The env list of 1 container in a plain Kubernetes manifest. null when the container is not there. */
+function k8sTarget(ws, k) {
+  const before = ws.read(k.file)
+  if (before === null || before.includes('{{')) return null
+  const doc = new Doc(before)
+  const item = findContainer(doc, k)
+  if (!item) return null
+  const target = { kind: 'k8s', file: k.file, where: `${k.file} (container ${k.container})`, before, current: new Map() }
+  const envAt = doc.find((line, i) => i > item.start && i <= item.end && new RegExp(`^ {${item.key}}env:`).test(line))
+  let dash = item.key + 2, itemKey = item.key + 4, last = envAt
+  const entries = []
+  if (envAt >= 0) {
+    if (doc.get(envAt).slice(item.key + 4).replace(/(^|\s)#.*$/, '').trim()) return { ...target, flow: true }
+    for (let i = envAt + 1; i <= item.end; i++) {
+      const line = doc.get(i)
+      if (blank(line)) continue
+      const indent = indentOf(line).length, isDash = /^\s*-\s/.test(line)
+      if (last === envAt) {
+        if (!isDash) break
+        dash = indent
+        itemKey = indent + /^-\s+/.exec(line.trimStart())[0].length
+      }
+      if (indent < dash || (indent === dash && !isDash)) break
+      last = i
+      if (indent === dash) entries.push({ name: null, value: -1, raw: null })
+      const entry = entries.at(-1), keyed = indent === dash ? line.slice(itemKey) : indent === itemKey ? line.trim() : ''
+      const m = /^(name|value|valueFrom):\s*(.*)$/.exec(keyed)
+      if (!m) continue
+      if (m[1] === 'name') entry.name = unquote(m[2])
+      else if (m[1] === 'value') Object.assign(entry, { value: i, raw: unquote(m[2]) })
+    }
+    for (const e of entries) if (e.name) target.current.set(e.name, e.value >= 0 ? e.raw : null)
+  } else {
+    const image = doc.find((line, i) => i >= item.start && i <= item.end && new RegExp(`^ {${item.key}}image:\\s*\\S`).test(line))
+    last = image >= 0 ? image : item.nameLine
+  }
+  target.write = (set) => {
+    const missing = []
+    for (const [name, value] of set) {
+      const entry = entries.find((e) => e.name === name && e.value >= 0)
+      if (!entry) { missing.push([name, value]); continue }
+      const line = doc.get(entry.value)
+      doc.set(entry.value, `${line.slice(0, line.indexOf('value:') + 6)} ${quote(value)}`)
+    }
+    const lines = envItems(missing, dash, itemKey)
+    doc.insert(last + 1, ...(envAt >= 0 ? lines : [`${' '.repeat(item.key)}env:`, ...lines]))
+    return doc.toString()
+  }
+  return target
+}
+
+function envItems(pairs, dash, key) {
+  return pairs.flatMap(([name, value]) => [`${' '.repeat(dash)}- name: ${name}`, `${' '.repeat(key)}value: ${quote(value)}`])
+}
+
+/** The list item of the container named k.container under a containers: key. */
+function findContainer(doc, k) {
+  const name = k.container.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const re = new RegExp(`^(\\s*)(-\\s+)?name:\\s*(["']?)${name}\\3\\s*(#.*)?$`)
+  const found = []
+  let docNo = 0
+  for (let i = 0; i < doc.length; i++) {
+    if (/^---/.test(doc.get(i))) { docNo++; continue }
+    const m = re.exec(doc.get(i))
+    if (!m) continue
+    const key = m[1].length + (m[2]?.length ?? 0)
+    let start = m[2] ? i : -1
+    for (let j = i - 1; start < 0 && j >= 0; j--) {
+      const line = doc.get(j)
+      if (blank(line)) continue
+      if (/^\s*-\s+/.exec(line)?.[0].length === key) start = j
+      else if (indentOf(line).length < key) break
+    }
+    if (start < 0 || !underContainers(doc, start)) continue
+    let end = start
+    for (let j = start + 1; j < doc.length && !/^---/.test(doc.get(j)); j++) {
+      if (blank(doc.get(j))) continue
+      if (indentOf(doc.get(j)).length < key) break
+      end = j
+    }
+    found.push({ start, end, key, nameLine: i, doc: docNo })
+  }
+  return found.length === 1 ? found[0] : found.find((f) => f.doc === k.doc) ?? null
+}
+
+function underContainers(doc, start) {
+  const dash = indentOf(doc.get(start)).length
+  for (let j = start - 1; j >= 0; j--) {
+    const line = doc.get(j)
+    if (blank(line)) continue
+    const indent = indentOf(line).length
+    if (indent > dash || (indent === dash && /^\s*-\s/.test(line))) continue
+    return /^\s*containers:\s*(#.*)?$/.test(line)
+  }
+  return false
+}

package/lib/stacks/dotnet.mjs

@@ -0,0 +1,165 @@
+// .NET: add the OpenTelemetry.AutoInstrumentation package to the web project and start the app with instrument.sh.
+// The csproj is edited as text (no dotnet add), so its BOM, line endings and layout stay. Directory.*.props files
+// above the --path folder count too: with central package versions there, the step is manual.
+import { PINS, STACKS } from '../contract.mjs'
+import { Doc } from '../doc.mjs'
+import { dockerStart, parseDockerfile, prefixStart } from '../dockerfile.mjs'
+import { upFrom } from '../workspace.mjs'
+import { startOverrides } from './k8s.mjs'
+
+const DOCS = STACKS.find((s) => s.id === 'dotnet')
+const { package: PACKAGE, version: VERSION, minNet, redis: REDIS } = PINS.dotnet
+const USE_NET8 = DOCS.notes.find((n) => /\.NET 8/.test(n))
+const ENTRYPOINT = DOCS.dockerfile.split('\n').find((l) => l.startsWith('ENTRYPOINT'))
+const SCRIPT_NOTE = DOCS.notes.find((n) => /instrument\.sh/.test(n))
+const at = (dir, name) => (dir === '.' ? name : `${dir}/${name}`)
+const dirOf = (path) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '.')
+const above = (path) => path.startsWith('../')
+const read = (view, path) => { try { return view.read(path) } catch { return null } }
+const tag = (text, name) => new RegExp(`<${name}>\\s*([^<]*?)\\s*</${name}>`, 'i').exec(text)?.[1] ?? null
+
+/** @type {import('../types.mjs').Applier} */
+export const dotnet = {
+  id: 'dotnet',
+  plan(service, ctx) {
+    const { ws } = ctx
+    const plan = { summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [] }
+    const projects = [...service.manifests, ...ws.list(service.dir).map((n) => at(service.dir, n))].filter((p) => p.endsWith('.csproj'))
+    const csproj = projects.find((p) => /Microsoft\.NET\.Sdk\.Web/.test(ws.read(p) ?? '')) ?? projects[0]
+    if (!csproj) {
+      plan.manual.push({ title: 'Add OpenTelemetry to your .NET app', lines: ['This tool did not find the .csproj file of the web app.',
+        `Run dotnet add package ${PACKAGE} in the folder of the web app.`, 'Then start the app with instrument.sh.', SCRIPT_NOTE] })
+      return plan
+    }
+    const text = ws.read(csproj)
+    const view = ctx.repo ?? ws
+    const folders = upFrom(dirOf(csproj), view.top ?? '.')
+    const props = (name) => folders.map((dir) => at(dir, name)).map((file) => ({ file, text: read(view, file) })).filter((p) => p.text !== null)
+    const framework = targetFramework(text, props('Directory.Build.props'))
+    const major = /^net(?:coreapp)?(\d+)\./.exec(framework ?? '')?.[1] ?? (/^net\d+$/.test(framework ?? '') ? '4' : null)
+    if (major !== null && Number(major) < minNet) {
+      plan.manual.push({ title: USE_NET8.replace(/\.$/, ''), lines: [`${csproj} targets ${framework}.`,
+        `${PACKAGE} ${VERSION} needs .NET ${minNet} or later.`, `Change the target framework to net${minNet}.0 or later. Then run npx @uknows/setup again.`] })
+      return plan
+    }
+    if (major === null) plan.notes.push(`This tool could not read the target framework of ${csproj}. ${USE_NET8}`)
+    const added = addPackages(csproj, text, props, plan)
+    if (added !== true) {
+      plan.stop = added === 'outside'
+      return plan
+    }
+    const dll = `${tag(text, 'AssemblyName') ?? csproj.split('/').pop().replace(/\.csproj$/, '')}.dll`
+    // The docs settings for .NET add a log folder that the app can write. Without it, the app can stop at start.
+    for (const line of DOCS.extraSettings?.lines ?? []) {
+      const at = line.indexOf('=')
+      plan.extraSettings.push({ name: line.slice(0, at), value: line.slice(at + 1) })
+    }
+    addStart(ws, service, dll, plan)
+    return plan
+  },
+}
+
+function targetFramework(text, buildProps) {
+  for (const source of [text, ...buildProps.map((p) => p.text)]) {
+    const found = source && (tag(source, 'TargetFramework') ?? tag(source, 'TargetFrameworks')?.split(';')[0])
+    if (found) return found.includes('$(') ? null : found
+  }
+  return null
+}
+
+/**
+ * Add the package references. Returns true when they are there after this run. Else the start must not change:
+ * 'outside' when the versions live in a file above the --path folder (run from the repo root), else false.
+ */
+function addPackages(csproj, text, findProps, plan) {
+  const refs = [...text.matchAll(/<PackageReference\s[^>]*?Include\s*=\s*"([^"]+)"[^>]*?(?:\/>|>([\s\S]*?)<\/PackageReference>)/gi)]
+  const has = (name) => refs.some((m) => m[1].toLowerCase() === name.toLowerCase())
+  const { file: propsFile = null, text: props = null } = findProps('Directory.Packages.props')[0] ?? {}
+  const central = [text, props, ...findProps('Directory.Build.props').map((p) => p.text)]
+    .some((t) => /<ManagePackageVersionsCentrally>\s*true\s*</i.test(t ?? ''))
+  const add = has(PACKAGE) ? [] : [[PACKAGE, VERSION]]
+  const redis = refs.find((m) => m[1].toLowerCase() === REDIS.library.toLowerCase())
+  if (redis && !has(REDIS.package)) {
+    const version = /Version\s*=\s*"([^"]+)"/i.exec(redis[0])?.[1] ?? tag(redis[2] ?? '', 'Version')
+      ?? new RegExp(`<PackageVersion\\s+Include="${REDIS.library}"\\s+Version="([^"]+)"`, 'i').exec(props ?? '')?.[1]
+    const v = /^(\d+)\.(\d+)\.(\d+)/.exec(version ?? '')?.slice(1).map(Number)
+    if (!v) plan.notes.push(`This app uses ${REDIS.library}. If the build fails, add ${REDIS.package} ${REDIS.version}.`)
+    else if (v[0] < 4 && (v[0] > 2 || (v[0] === 2 && (v[1] > 6 || (v[1] === 6 && v[2] >= 122))))) add.push([REDIS.package, REDIS.version])
+  }
+  if (!add.length) return true
+  const reference = ([name, version]) => `<PackageReference Include="${name}"${central ? '' : ` Version="${version}"`} />`
+  const version = ([name, v]) => `<PackageVersion Include="${name}" Version="${v}" />`
+  if (central && (!propsFile || above(propsFile))) {
+    plan.manual.push({ title: `Add ${PACKAGE} to ${csproj}`, lines: [
+      propsFile ? `This repo sets package versions in ${propsFile}, outside the folder this tool works in, so this tool cannot change it.`
+        : 'This project sets package versions centrally, but this tool did not find Directory.Packages.props.',
+      'Run npx @uknows/setup in the repo root without --path, and pick this service. Or add these lines by hand. Then run it again for the start command.'],
+    snippets: [{ caption: propsFile ?? 'Directory.Packages.props', language: 'xml', code: add.map(version).join('\n') },
+      { caption: csproj, language: 'xml', code: add.map(reference).join('\n') }] })
+    return propsFile ? 'outside' : false
+  }
+  const after = addItems(text, add.map(reference), /<PackageReference\s/)
+  if (after === null) {
+    plan.manual.push({ title: `Add ${PACKAGE} to ${csproj}`, lines: [`Run dotnet add package ${PACKAGE} in ${dirOf(csproj)}.`] })
+    return false
+  }
+  plan.edits.push({ file: csproj, before: text, after, why: `Add the ${PACKAGE} package.` })
+  if (central) {
+    const versions = add.filter(([name]) => !new RegExp(`<PackageVersion\\s+Include="${name}"`, 'i').test(props))
+    if (versions.length) {
+      plan.edits.push({ file: propsFile, before: props, why: `Set the version of the ${PACKAGE} package.`,
+        after: addItems(props, versions.map(version), /<PackageVersion\s/) ?? props })
+    }
+  }
+  add.forEach(([name, version]) => plan.summary.push(`Add ${name} ${version} to ${csproj}${name === PACKAGE ? '' : `, because the app uses ${REDIS.library}`}.`))
+  if (findProps('packages.lock.json')[0]?.file === at(dirOf(csproj), 'packages.lock.json')) {
+    plan.manual.push({ title: 'Update packages.lock.json', lines: ['Run dotnet restore --force-evaluate.', 'Then commit packages.lock.json.'] })
+  }
+  return true
+}
+
+/** Add item lines after the last single-line item like them (not in a conditional ItemGroup), else in a new ItemGroup before </Project>. */
+function addItems(text, items, like) {
+  const doc = new Doc(text)
+  const lines = doc.lines
+  const lastItem = lines.findLastIndex((l) => like.test(l) && /\/>\s*$/.test(l))
+  const group = lines.slice(0, lastItem + 1).findLast((l) => /<ItemGroup\b/.test(l)) ?? ''
+  if (lastItem >= 0 && !/Condition/.test(group)) {
+    const indent = /^\s*/.exec(lines[lastItem])[0]
+    doc.insert(lastItem + 1, ...items.map((item) => indent + item))
+    return doc.toString()
+  }
+  const end = lines.findLastIndex((l) => /^\s*<\/Project>\s*$/.test(l))
+  if (end < 0) return null
+  const unit = lines.map((l) => /^(\s+)</.exec(l)?.[1]).find(Boolean) ?? '  '
+  const block = [`${unit}<ItemGroup>`, ...items.map((item) => unit + unit + item), `${unit}</ItemGroup>`]
+  if (end > 0 && !lines[end - 1].trim()) doc.insert(end, ...block, '')
+  else doc.insert(end, '', ...block)
+  return doc.toString()
+}
+
+function addStart(ws, service, dll, plan) {
+  const entrypoint = ENTRYPOINT.replace('OrdersApi.dll', dll)
+  const manual = (lines) => plan.manual.push({ title: 'Start the app with instrument.sh', lines: [...lines, SCRIPT_NOTE],
+    snippets: [{ caption: service.dockerfile ? 'Dockerfile' : 'Start', language: service.dockerfile ? 'dockerfile' : 'bash',
+      code: service.dockerfile ? entrypoint : DOCS.start.replace('OrdersApi.dll', dll) }] })
+  const text = service.dockerfile && ws.read(service.dockerfile)
+  if (!text) return manual(['This app does not start from a Dockerfile. Start it with the command below.'])
+  const info = parseDockerfile(text)
+  if (/chiseled|distroless|nanoserver|windowsservercore/i.test(info.image ?? '')) {
+    return manual([`The final image ${info.image} has no /bin/sh. instrument.sh needs it.`,
+      'Use a final image with a shell, such as mcr.microsoft.com/dotnet/aspnet. Then start the app like this.'])
+  }
+  const argv = dockerStart(info)?.argv ?? []
+  const target = argv.find((a) => /\.dll$/i.test(a)) ?? (/^\.{0,2}\//.test(argv[0] ?? '') ? argv[0] : null)
+  // instrument.sh sits next to the dll in the publish output.
+  const script = argv[1]?.endsWith('instrument.sh') ? argv[1]
+    : target && (target.includes('/') ? `${dirOf(target)}/instrument.sh` : './instrument.sh')
+  const after = script && prefixStart(text, ['sh', script])
+  if (!after) return manual([`This tool cannot change the start command in ${service.dockerfile}.`, 'Put sh ./instrument.sh in front of the command that starts your app.'])
+  if (/alpine/i.test(info.image ?? '')) plan.notes.push('The final image uses Alpine. If monitoring does not start, publish with -r linux-musl-x64.')
+  plan.manual.push(...startOverrides(service, info.entrypoint ? 'ENTRYPOINT' : 'CMD', `sh ${script}`))
+  if (after === text) return
+  plan.edits.push({ file: service.dockerfile, before: text, after, why: 'Start the app with instrument.sh.' })
+  plan.summary.push(`Start the app with instrument.sh (${info.entrypoint ? 'ENTRYPOINT' : 'CMD'} in ${service.dockerfile}).`)
+}

package/lib/stacks/guided.mjs

@@ -0,0 +1,104 @@
+// Go, PHP and Ruby: guided in v1. settings.mjs adds the settings as usual, but this tool does not edit
+// go.mod, composer.json, Gemfile or code: without the lock or sum updates the build breaks. It prints
+// the docs steps instead, and none when the SDK is already a dependency.
+import { GO_INIT, GO_MAIN, PINS, RUBY_INITIALIZER, STACKS } from '../contract.mjs'
+import { parseDockerfile } from '../dockerfile.mjs'
+
+const docs = (id) => STACKS.find((s) => s.id === id)
+const at = (dir, name) => (dir === '.' ? name : `${dir}/${name}`)
+const runIn = (dir) => `Run these commands in ${dir === '.' ? 'the root folder of the repo' : dir}.`
+const empty = () => ({ summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [] })
+
+/** @type {import('../types.mjs').Applier} */
+export const go = {
+  id: 'go',
+  plan(service, { ws }) {
+    const plan = empty()
+    if (/go\.opentelemetry\.io\/otel\/sdk\s/.test(ws.read(at(service.dir, 'go.mod')) ?? '')) return plan
+    const { install, files, notes, label } = docs('go')
+    // go get raises the go line of go.mod to what the modules need. An older Go builder then fails.
+    const version = /^(\d+)\.(\d+)/.exec(service.runtimeVersion ?? '')
+    const [major, minor] = PINS.go.minGo
+    if (version && Number(version[1]) * 1000 + Number(version[2]) < major * 1000 + minor) {
+      plan.manual.push({ title: `Use Go ${major}.${minor} or later`, lines: [`This app builds with Go ${version[0]}.`,
+        `The OpenTelemetry Go packages that go get adds need Go ${major}.${minor} or later.`,
+        `Update the go line in go.mod and the Go version of the build image to ${major}.${minor} or later. Do this first.`] })
+    }
+    // The base go get, then only the '# Gin only' or '# Echo v4 only' part for a detected router.
+    const sections = install.split('\n').reduce((all, line) => {
+      if (line.startsWith('# ')) all.push([line]); else all.at(-1).push(line)
+      return all
+    }, [[]])
+    const code = sections.filter((s, k) => k === 0 || service.frameworks.some((f) => s[0].toLowerCase().includes(f))).flat().join('\n')
+    plan.summary.push(`Show the steps to add OpenTelemetry to your ${label} code. You do these steps yourself.`)
+    plan.manual.push(
+      { title: 'Add the OpenTelemetry Go packages', lines: [runIn(service.dir)], snippets: [{ caption: 'go get', language: 'bash', code }] },
+      { title: `Add ${at(service.dir, files[0].path)}`, lines: [files[0].summary], snippets: [{ caption: files[0].path, language: 'go', code: GO_INIT }] },
+      { title: 'Start OpenTelemetry in main', lines: [files[1].summary, ...notes], snippets: [{ caption: files[1].path, language: 'go', code: GO_MAIN }] })
+    return plan
+  },
+}
+
+/** The docs RUN lines that install the PHP extension in official php images. */
+const PHP_RUN = (() => {
+  const lines = docs('php').dockerfile.split('\n')
+  const start = lines.findIndex((l) => l.startsWith('RUN '))
+  let end = start
+  while (lines[end].endsWith('\\')) end++
+  return lines.slice(start, end + 1).join('\n')
+})()
+
+/** @type {import('../types.mjs').Applier} */
+export const php = {
+  id: 'php',
+  plan(service, { ws }) {
+    const plan = empty()
+    plan.extraSettings.push({ ...PINS.php.autoload })
+    let composer = {}
+    try { composer = JSON.parse(ws.read(at(service.dir, 'composer.json')) ?? '{}') } catch { /* not JSON: print the steps */ }
+    if (composer.require?.['open-telemetry/sdk']) return plan
+    const { install, files, notes, label } = docs('php')
+    const [pecl, allowPlugins, require] = install.split('\n')
+    const note = (re) => notes.filter((n) => re.test(n))
+    // Laravel keeps the docs line. Symfony and Slim swap the Laravel package, as the docs notes say. Plain PHP drops it.
+    const swap = notes.map((n) => /^For (\w+), use (\S+) instead of the Laravel package/.exec(n))
+      .find((m) => m && service.frameworks.includes(m[1].toLowerCase()))
+    const laravel = service.frameworks.includes('laravel')
+    const packages = laravel ? require : require.replace(/\S*opentelemetry-auto-laravel/, swap?.[2] ?? '').trimEnd()
+    const dockerText = (service.dockerfile && ws.read(service.dockerfile)) || ''
+    const image = parseDockerfile(dockerText).image ?? ''
+    // composer install in a build stage without the extension stops on the platform check.
+    const platform = /composer\s+install\b/.test(dockerText) && !/ignore-platform-req/.test(dockerText) ? note(/--ignore-platform-req option/) : []
+    const extension = service.dockerfile
+      ? { lines: [`Add these lines to the final stage of ${service.dockerfile}, after its FROM line.`, ...(/alpine/i.test(image) ? note(/Alpine/) : [])],
+        snippets: [{ caption: service.dockerfile, language: 'dockerfile', code: PHP_RUN }] }
+      : { lines: ['Install the extension on each server.', files[0].summary],
+        snippets: [{ caption: 'Install', language: 'bash', code: pecl }, { caption: files[0].path, language: 'ini', code: files[0].content }] }
+    plan.summary.push(`Show the steps to add OpenTelemetry to your ${label} app. You do these steps yourself.`)
+    plan.manual.push({ title: 'Add the OpenTelemetry PHP extension', ...extension }, {
+      title: 'Add the OpenTelemetry Composer packages',
+      lines: [runIn(service.dir), 'Commit composer.json and composer.lock.', ...(laravel ? [] : note(/PSR-18/)), ...platform, ...(/fpm/i.test(image) ? note(/PHP-FPM/) : [])],
+      snippets: [{ caption: 'composer', language: 'bash', code: [allowPlugins, packages].join('\n') }] })
+    return plan
+  },
+}
+
+/** @type {import('../types.mjs').Applier} */
+export const ruby = {
+  id: 'ruby',
+  plan(service, { ws }) {
+    const plan = empty()
+    if (/^\s*gem\s*\(?\s*["']opentelemetry-sdk["']/m.test(ws.read(at(service.dir, 'Gemfile')) ?? '')) return plan
+    const { install, files, notes, label } = docs('ruby')
+    const rails = service.frameworks.includes('rails') || ws.read(at(service.dir, 'config/application.rb')) !== null
+    plan.summary.push(`Show the steps to add OpenTelemetry to your ${label} app. You do these steps yourself.`)
+    plan.manual.push(
+      { title: 'Add the OpenTelemetry gems', lines: [runIn(service.dir), notes.find((n) => /Gemfile\.lock/.test(n))],
+        snippets: [{ caption: 'bundle', language: 'bash', code: install }] },
+      rails ? { title: `Add ${at(service.dir, files[0].path)}`, lines: [files[0].summary],
+        snippets: [{ caption: files[0].path, language: 'ruby', code: RUBY_INITIALIZER }] }
+        : { title: `Add OpenTelemetry to ${at(service.dir, 'config.ru')}`, lines: [notes.find((n) => /config\.ru/.test(n))],
+          snippets: [{ caption: 'config.ru', language: 'ruby', code: RUBY_INITIALIZER }] })
+    return plan
+  },
+}

package/lib/stacks/index.mjs

@@ -0,0 +1,10 @@
+// Registry: stack id -> applier. The engine looks appliers up here.
+import { node } from './node.mjs'
+import { python } from './python.mjs'
+import { dotnet } from './dotnet.mjs'
+import { java } from './java.mjs'
+import { go, php, ruby } from './guided.mjs'
+import { otel } from './otel.mjs'
+
+/** @type {Record<import('../types.mjs').StackId, import('../types.mjs').Applier>} */
+export const APPLIERS = { node, python, dotnet, java, go, php, ruby, otel }

package/lib/stacks/java.mjs

@@ -0,0 +1,56 @@
+// Java: add the pinned OpenTelemetry Java agent to the final image with the docs ADD line (Docker checks
+// the checksum) 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 ADD_LINE = DOCS.dockerfile.split('\n').find((l) => l.startsWith('ADD '))
+// Earlier /docs gave --chmod=644. BuildKit also gives that mode to the /otel folder it creates, so a
+// non-root USER cannot load the agent and the JVM stops. A Dockerfile with that exact line gets the new one.
+const OLD_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 = text.split(OLD_ADD_LINE).join(ADD_LINE)
+    const added = fixed.includes(JAVA_AGENT.url) || fixed.includes(AGENT_PATH) ? fixed : insertBeforeStart(fixed, [ADD_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: 'Let a non-root user load the OpenTelemetry Java agent.' })
+      plan.summary.push(`Give the agent folder in ${service.dockerfile} mode 755, so an app that runs as a non-root user can load the agent.`)
+      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}. Docker checks its checksum.`,
+      `Load the agent when the JVM starts (JAVA_TOOL_OPTIONS in ${service.dockerfile}).`)
+    plan.notes.push(note(/Docker 25/))
+    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.`] }))
+}