@uknows/setup 0.0.0-stage → 0.1.0

package/lib/stacks/python.mjs

@@ -0,0 +1,434 @@
+/*
+ * Python: add opentelemetry-distro, the OTLP/HTTP exporter and the
+ * instrumentation packages that `opentelemetry-bootstrap -a requirements`
+ * would print, then start the app with opentelemetry-instrument.
+ *
+ * Safety rule: the start command gets opentelemetry-instrument only when the
+ * current build surely installs the packages: a RUN line of the image installs
+ * the file this tool changed, or (without a Dockerfile) the platform installs
+ * it. Otherwise the image would fail to start, so the start goes into a
+ * manual step instead.
+ */
+import { Doc, indentOf } from '../doc.mjs'
+import { dockerStart, parseDockerfile, prefixStart, reachingStages } from '../dockerfile.mjs'
+import { PINS, STACKS } from '../contract.mjs'
+import { upFrom } from '../workspace.mjs'
+import { startOverrides } from './k8s.mjs'
+import { bootstrap, normalize } from './python-bootstrap.mjs'
+
+const STACK = STACKS.find((s) => s.id === 'python')
+const INSTRUMENT = 'opentelemetry-instrument'
+const RUNNERS = /^(poetry|uv|pipenv|pdm|hatch|rye)$/
+const LOCKS = { 'uv.lock': 'uv lock', 'poetry.lock': 'poetry lock', 'pdm.lock': 'pdm lock' }
+const SECRET = /(password|passwd|token|secret|credential|authorization|api[-_]?key|connection[-_]?string)/i
+const AGAIN = 'Then run npx @uknows/setup again. It puts opentelemetry-instrument in front of the start command.'
+
+/** @type {import('../types.mjs').Applier} */
+export const python = {
+  id: 'python',
+  plan(service, ctx) {
+    const { ws } = ctx
+    const out = { summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [] }
+    const version = /^(\d+)\.(\d+)/.exec(service.runtimeVersion ?? '')
+    const [major, minor] = PINS.python.minPython
+    if (version && Number(version[1]) * 1000 + Number(version[2]) < major * 1000 + minor) {
+      out.manual.push({ title: `Use Python ${major}.${minor} or later`, lines: [`This app uses Python ${version[0]}.`,
+        `${PINS.python.distro.split('==').join(' ')} needs Python ${major}.${minor} or later.`,
+        'Update the Python version of the app. Then run npx @uknows/setup again.'] })
+      return out
+    }
+    if (!service.runtimeVersion) out.notes.push(`Check that the app uses Python ${major}.${minor} or later. ${PINS.python.distro.split('==')[0]} needs it.`)
+
+    const docker = service.dockerfile ? read(ws, service.dockerfile) : null
+    const deps = pickDeps(service, ws, docker)
+    const wanted = [PINS.python.distro, PINS.python.exporter, ...bootstrap(deps.names, PINS.python.contrib)]
+    const missing = wanted.filter((req) => !deps.names.has(normalize(req.split('==')[0])))
+    const ready = addPackages(deps, missing, ws, ctx.repo ?? ws, out)
+
+    if (ready && deps.proven) wrapStart(service, ws, docker, out)
+    else if (ready) {
+      out.manual.push({ title: `Install ${deps.file} in the image`, lines: [
+        `${service.dockerfile} does not install ${deps.file}, so the image would not have opentelemetry-instrument. This tool did not change the start command.`,
+        `Install ${deps.file} in the final image, for example with ${deps.kind === 'requirements' ? `RUN pip install -r ${base(deps.file)}` : 'RUN pip install .'}.`,
+        AGAIN] })
+    }
+    const startText = docker !== null ? (dockerStart(parseDockerfile(docker))?.raw ?? '') : (service.start?.raw ?? procfileWeb(ws, service)?.cmd ?? '')
+    startNotes(startText, out)
+
+    // Django: the instrumentation reads the settings at startup, so DJANGO_SETTINGS_MODULE must be set.
+    // Keep a value that the app sets already. Else use the value of the module that the start command loads.
+    const django = deps.names.has('django') || service.frameworks.includes('django')
+    if (django && !alreadySet('DJANGO_SETTINGS_MODULE', service, ws)) {
+      const found = djangoSettings(service, ws, startText)
+      if (found) {
+        out.extraSettings.push({ name: 'DJANGO_SETTINGS_MODULE', value: found.value })
+        out.notes.push(`Set DJANGO_SETTINGS_MODULE to ${found.value}, the value that ${found.file} uses.`)
+      } else {
+        out.manual.push({ title: 'Set DJANGO_SETTINGS_MODULE', lines: [note(/DJANGO_SETTINGS_MODULE/),
+          'This tool cannot tell which settings module the app uses in production.',
+          'The module that the start command loads, or manage.py, wsgi.py and asgi.py together, must give 1 value.',
+          'Add the production value with the 5 UKNOWS settings.'].filter(Boolean) })
+      }
+    }
+    return out
+  },
+}
+
+/**
+ * Add the missing packages. Returns true when the dependency list has them after this run, and its lockfile too.
+ * view reads lockfiles above the --path folder.
+ */
+function addPackages(deps, missing, ws, view, out) {
+  const lock = deps.kind === 'pep621' || deps.kind === 'poetry' ? findLock(view, dirOf(deps.file)) : null
+  const lockReady = !lock || /name\s*=\s*"opentelemetry-distro"/.test(read(view, lock) ?? '')
+  if (!missing.length) {
+    if (!lockReady) out.manual.push(relockBlock(lock, deps.file))
+    return lockReady
+  }
+  const snippet = { caption: 'Packages to add', language: 'text', code: missing.join('\n') }
+  const stop = (title, lines, code) => {
+    out.manual.push({ title, lines: [...lines, AGAIN], snippets: [code ? { ...snippet, code } : snippet] })
+    return false
+  }
+  if (!deps.file) {
+    return stop('Add the OpenTelemetry packages', ['This tool did not find a dependency list that it can change, such as requirements.txt.',
+      'Add these packages to the file that lists the app dependencies.'])
+  }
+  if (deps.kind === 'pipfile') {
+    return stop('Add the OpenTelemetry packages', ['This app uses Pipenv. Add the packages with pipenv install.'],
+      `pipenv install ${missing.join(' ')}`)
+  }
+  if (deps.hashes) {
+    return stop('Add the OpenTelemetry packages', [`${deps.file} uses --hash, so this tool cannot add lines to it.`,
+      'Add these packages with the tool that writes the file, such as pip-compile --generate-hashes.'])
+  }
+  const source = deps.kind === 'requirements' ? deps.file.replace(/\.txt$/, '.in') : null
+  if (source && source !== deps.file && read(ws, source) !== null) {
+    return stop('Add the OpenTelemetry packages', [`${deps.file} is built from ${source} by pip-tools.`,
+      `Add these lines to ${source}.`, `Run pip-compile ${source.split('/').pop()}.`])
+  }
+  const before = read(ws, deps.file)
+  const after = deps.kind === 'requirements' ? appendLines(before, missing) : editPyproject(before, deps, missing)
+  if (after === null) return stop('Add the OpenTelemetry packages', [`This tool cannot change the dependency list in ${deps.file}.`, 'Add these packages to it.'])
+  out.edits.push({ file: deps.file, before, after, why: 'Add the OpenTelemetry packages.' })
+  out.summary.push(`Add ${missing.length} OpenTelemetry packages to ${deps.file}.`)
+  if (!lockReady) out.manual.push(relockBlock(lock, deps.file))
+  return lockReady
+}
+
+function relockBlock(lock, file) {
+  const name = lock.split('/').pop()
+  return { title: `Update ${name}`, lines: [`${file} lists the OpenTelemetry packages, but ${name} does not have them yet.`,
+    `Run ${LOCKS[name]} in ${dirOf(lock) === '.' ? 'the repo root' : dirOf(lock)}.`,
+    ...(name === 'poetry.lock' ? ['On Poetry 1, run poetry lock --no-update instead.'] : []), `Commit ${name}.`, AGAIN] }
+}
+
+function wrapStart(service, ws, docker, out) {
+  const done = (file, before, after, where) => {
+    out.edits.push({ file, before, after, why: 'Start the app with opentelemetry-instrument.' })
+    out.summary.push(`Start the app with opentelemetry-instrument (${where}).`)
+  }
+  if (docker !== null) {
+    const info = parseDockerfile(docker)
+    const start = dockerStart(info)
+    if (!start) { out.manual.push(startBlock(null)); return }
+    const words = start.argv ?? start.raw.replace(/^exec\s+/, '').split(/\s+/)
+    const instruction = info.entrypoint ? 'ENTRYPOINT' : 'CMD'
+    const overrides = startOverrides(service, instruction, INSTRUMENT)
+    if (base(words[0]) === INSTRUMENT) { out.manual.push(...overrides); return }
+    const where = `${instruction} in ${service.dockerfile}`
+    // A venv that is not on PATH: use the opentelemetry-instrument next to the start program.
+    const word = /venv\/bin\/[^/]+$/.test(words[0]) ? words[0].replace(/[^/]+$/, INSTRUMENT) : INSTRUMENT
+    const after = RUNNERS.test(base(words[0])) && words[1] === 'run' ? null : prefixStart(docker, [word])
+    if (after === null) out.manual.push(startBlock(`the ${where}`))
+    else {
+      if (after !== docker) done(service.dockerfile, docker, after, where)
+      out.manual.push(...overrides)
+    }
+    return
+  }
+  const web = !service.start || service.start.kind === 'procfile' ? procfileWeb(ws, service) : null
+  if (!web) { out.manual.push(startBlock(null, service.start?.kind === 'answer' ? service.start.raw : null)); return }
+  const words = web.cmd.trim().split(/\s+/)
+  if (base(words[0]) === INSTRUMENT) return
+  // Same limits as prefixStart: no leading NAME=value, no command lists or pipes.
+  if (!words[0] || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]) || /[;|`]|&&|&\s*$/.test(web.cmd) || (RUNNERS.test(words[0]) && words[1] === 'run')) {
+    out.manual.push(startBlock(`the web line in ${web.file}`))
+    return
+  }
+  const doc = new Doc(web.text)
+  doc.set(web.index, `${web.head}${INSTRUMENT} ${web.cmd}`)
+  done(web.file, web.text, doc.toString(), `web line in ${web.file}`)
+}
+
+function startBlock(where, answer = null) {
+  const code = answer && !SECRET.test(answer) ? `${INSTRUMENT} ${answer}` : STACK.start
+  return { title: 'Start the app with opentelemetry-instrument',
+    lines: [where ? `This tool cannot change ${where} safely.` : 'This tool did not find the command that starts the app.',
+      note(/in front of the command/)].filter(Boolean), snippets: [{ caption: 'Start command', language: 'bash', code }] }
+}
+
+/** Docs notes for start commands that opentelemetry-instrument does not handle well. */
+function startNotes(text, out) {
+  const words = text.split(/[\s"',[\]]+/).filter(Boolean)
+  const flag = words.findIndex((w) => w === '-w' || w === '--workers')
+  const workers = flag >= 0 ? Number(words[flag + 1]) : Number(/(?:^|\s|")(?:--workers=|-w)(\d+)/.exec(text)?.[1] ?? 1)
+  const dev = (words.includes('flask') && words.includes('run')) || (words.includes('runserver') && words.some((w) => base(w) === 'manage.py'))
+  out.notes.push(...[workers > 1 && note(/worker/), words.includes('--reload') && note(/--reload/),
+    dev && !words.some((w) => /^--no-?reload$/.test(w))
+      && 'The development server restarts the app when files change, and that stops OpenTelemetry. Use Gunicorn or uvicorn in production.',
+  ].filter(Boolean))
+}
+
+/**
+ * The dependency file the build uses, and the requirement names in it. proven: the build surely installs it.
+ * With a Dockerfile, only its RUN lines prove that. Without one, the platform installs the usual files.
+ */
+function pickDeps(service, ws, docker) {
+  const dir = service.dir
+  const installs = docker === null ? null : dockerInstalls(service, docker)
+  const requirements = (file, proven) => ({ kind: 'requirements', file, proven, ...requirementNames(ws, file) })
+  const project = (proven) => {
+    const text = read(ws, join(dir, 'pyproject.toml'))
+    const parsed = text === null ? null : parsePyproject(text)
+    return parsed && { file: join(dir, 'pyproject.toml'), hashes: false, proven, ...parsed }
+  }
+  const pipfile = (proven) => read(ws, join(dir, 'Pipfile')) !== null && { kind: 'pipfile', file: join(dir, 'Pipfile'), names: new Set(), hashes: false, proven }
+  if (installs) {
+    const file = installs.files.find((f) => read(ws, f) !== null)
+    if (file) return requirements(file, true)
+    const found = (installs.project && project(true)) || (installs.pipfile && pipfile(true))
+    if (found) return found
+  }
+  // Not installed by a RUN line (or no Dockerfile): the usual files.
+  const platform = docker === null
+  if (read(ws, join(dir, 'requirements.txt')) !== null) return requirements(join(dir, 'requirements.txt'), platform)
+  return project(platform) || pipfile(platform) || { kind: null, file: null, names: new Set(), hashes: false, proven: false }
+}
+
+/**
+ * The dependency files that the image surely installs, from the RUN lines of the stages that reach the final image:
+ * files given to pip install -r, the project (pip install . with any flags, poetry install, uv sync, pdm install,
+ * or an export of them), and the Pipfile (pipenv install). Paths are repo paths, found from the WORKDIR.
+ */
+function dockerInstalls(service, docker) {
+  const out = { files: [], project: false, pipfile: false }
+  let exported = false
+  for (const stage of reachingStages(parseDockerfile(docker))) {
+    let workdir = ''
+    for (const x of stage.instructions) {
+      if (x.keyword === 'WORKDIR') {
+        const w = x.args.replace(/^["']|["']$/g, '').replace(/\/+$/, '')
+        workdir = w.startsWith('/') ? w : `${workdir}/${w}`
+      }
+      if (x.keyword !== 'RUN') continue
+      for (const part of (x.argv ? x.argv.join(' ') : x.args).split(/&&|\|\||[;|\n]/)) {
+        if (/\b(?:poetry|uv|pdm)\s+export\b/.test(part)) exported = true
+        if (/\b(?:poetry\s+(?:install|export)|uv\s+(?:sync|export)|pdm\s+(?:install|sync|export))\b/.test(part)) out.project = true
+        if (/\bpipenv\s+(?:install|sync)\b/.test(part)) out.pipfile = true
+        if (!/\bpip3?\s+install\b/.test(part)) continue
+        const words = part.trim().split(/\s+/).map((w) => w.replace(/^["']|["']$/g, ''))
+        for (let k = 0; k < words.length; k++) {
+          const flag = /^(?:-r|--requirement)(?:=(.+))?$/.exec(words[k])
+          if (flag) out.files.push(...repoPaths(service, workdir, flag[1] ?? words[++k] ?? ''))
+          else if (/^\.\/?(?:\[[^\]]*\])?$/.test(words[k])) out.project = true
+        }
+      }
+    }
+  }
+  // An exported list (poetry export -o requirements.txt) is built from the lockfile, not from a file in the repo.
+  if (exported) out.files = []
+  return out
+}
+
+/** Repo paths that a path in the image can be: relative to the service folder and to the Dockerfile folder. */
+function repoPaths(service, workdir, raw) {
+  let path = raw.replace(/^\.\//, '')
+  if (!path) return []
+  if (path.startsWith('/')) path = workdir && path.startsWith(`${workdir}/`) ? path.slice(workdir.length + 1) : path.split('/').pop()
+  return [resolvePath(service.dir, path), resolvePath(dirOf(service.dockerfile), path)].filter(Boolean)
+}
+
+/** Requirement names in a requirements file, following -r includes 1 level deep. */
+function requirementNames(ws, file, depth = 0) {
+  const text = read(ws, file) ?? ''
+  const names = new Set()
+  let hashes = /(^|\s)--hash[=\s]/.test(text)
+  for (const raw of text.replace(/\\\r?\n/g, ' ').split(/\r?\n/)) {
+    const line = raw.replace(/(^|\s)#.*$/, '').trim()
+    const include = /^(?:-r|--requirement)(?:\s+|=)(\S+)/.exec(line)
+    if (include && depth === 0) {
+      const path = resolvePath(dirOf(file), include[1])
+      const sub = path ? requirementNames(ws, path, 1) : { names: [], hashes: false }
+      for (const name of sub.names) names.add(name)
+      hashes ||= sub.hashes
+    } else if (line && !line.startsWith('-')) {
+      const m = /^([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(line)
+      if (m) names.add(normalize(m[1]))
+    }
+  }
+  return { names, hashes }
+}
+
+/** The PEP 621 [project] dependencies array, else the [tool.poetry.dependencies] table. null when neither. */
+function parsePyproject(text) {
+  const doc = new Doc(text)
+  const table = (re) => {
+    const head = doc.find((line) => re.test(line.replace(/#.*$/, '').trim()))
+    if (head < 0) return null
+    const next = doc.find(/^\s*\[/, head + 1)
+    return { head, end: next < 0 ? doc.length : next }
+  }
+  const project = table(/^\[project\]$/)
+  const at = project ? doc.find((line, i) => i < project.end && /^\s*dependencies\s*=\s*\[/.test(line), project.head + 1) : -1
+  if (at >= 0) {
+    const array = scanArray(doc, at, doc.get(at).indexOf('[', doc.get(at).indexOf('=')))
+    if (!array) return null
+    const names = new Set(array.items.map((item) => /^\s*([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(item.value)?.[1]).filter(Boolean).map(normalize))
+    return { kind: 'pep621', names, array, at }
+  }
+  const poetry = table(/^\[tool\.poetry\.dependencies\]$/)
+  if (!poetry) return null
+  const names = new Set()
+  let last = poetry.head
+  for (let i = poetry.head + 1; i < poetry.end; i++) {
+    const m = /^\s*["']?([A-Za-z0-9][A-Za-z0-9._-]*)["']?\s*=/.exec(doc.get(i))
+    if (m) names.add(normalize(m[1]))
+    if (doc.get(i).trim()) last = i
+  }
+  return { kind: 'poetry', names, head: poetry.head, last }
+}
+
+/** Items and the closing bracket of the TOML array whose '[' is at (line, col). Strings and comments are skipped. */
+function scanArray(doc, line, col) {
+  const items = []
+  let depth = 0
+  for (let i = line, j = col; i < doc.length; i++, j = 0) {
+    const s = doc.get(i)
+    for (; j < s.length; j++) {
+      const c = s[j]
+      if (c === '#') break
+      if (c === '"' || c === "'") {
+        let k = j + 1
+        while (k < s.length && s[k] !== c) k += c === '"' && s[k] === '\\' ? 2 : 1
+        if (depth === 1) items.push({ line: i, end: k + 1, quote: c, value: s.slice(j + 1, k) })
+        j = k
+      } else if (c === '[' || c === '{') depth++
+      else if ((c === ']' || c === '}') && --depth === 0) return { items, close: { line: i, col: j } }
+    }
+  }
+  return null
+}
+
+function editPyproject(text, deps, missing) {
+  const doc = new Doc(text)
+  if (deps.kind === 'poetry') {
+    const indent = deps.last > deps.head ? indentOf(doc.get(deps.last)) : ''
+    doc.insert(deps.last + 1, ...missing.map((req) => `${indent}${req.split('==')[0]} = "${req.split('==')[1]}"`))
+    return doc.toString()
+  }
+  const { items, close } = deps.array
+  const last = items[items.length - 1]
+  const q = (req) => `${last?.quote ?? '"'}${req}${last?.quote ?? '"'}`
+  const closeLine = doc.get(close.line)
+  // Text between the last item and the closing bracket, without comments: does it hold a trailing comma?
+  const between = []
+  for (let i = last ? last.line : close.line; i <= close.line; i++) {
+    const s = doc.get(i).slice(last && i === last.line ? last.end : 0, i === close.line ? close.col : undefined)
+    between.push(s.replace(/#.*$/, ''))
+  }
+  const trailing = between.join(' ').includes(',')
+  if (close.line > deps.at && !closeLine.slice(0, close.col).trim()) {
+    // Multi-line array: 1 item per line, before the closing bracket, in the same style.
+    const indent = last && last.line > deps.at ? indentOf(doc.get(last.line)) : `${indentOf(closeLine)}    `
+    if (last && !trailing) doc.set(last.line, doc.get(last.line).slice(0, last.end) + ',' + doc.get(last.line).slice(last.end))
+    doc.insert(close.line, ...missing.map((req, k) => `${indent}${q(req)}${trailing || !last || k < missing.length - 1 ? ',' : ''}`))
+  } else {
+    // Inline array: append inside the brackets.
+    const head = closeLine.slice(0, close.col)
+    const lead = !items.length ? head : `${head.replace(/\s+$/, '')}${trailing ? ' ' : ', '}`
+    doc.set(close.line, lead + missing.map(q).join(', ') + closeLine.slice(close.col))
+  }
+  return doc.toString()
+}
+
+function appendLines(text, lines) {
+  const eol = new Doc(text).eol
+  return (text === '' || text.endsWith('\n') ? text : text + eol) + lines.map((line) => line + eol).join('')
+}
+
+/** The nearest uv, Poetry or PDM lockfile, up to the top of the git repo (above the --path folder too). */
+function findLock(view, dir) {
+  for (const d of upFrom(dir, view.top ?? '.')) {
+    for (const name of Object.keys(LOCKS)) if (read(view, join(d, name)) !== null) return join(d, name)
+  }
+  return null
+}
+
+/** The web: line of the service Procfile. */
+function procfileWeb(ws, service) {
+  const file = service.start?.kind === 'procfile' && service.start.file ? service.start.file : join(service.dir, 'Procfile')
+  const text = read(ws, file)
+  if (text === null) return null
+  const doc = new Doc(text)
+  const index = doc.find(/^web:/)
+  if (index < 0) return null
+  const m = /^(web:\s*)(.*)$/.exec(doc.get(index))
+  return { file, text, index, head: m[1], cmd: m[2] }
+}
+
+/**
+ * The settings module that production picks: the setdefault in the wsgi or asgi module that the start command
+ * loads (gunicorn config.wsgi, uvicorn config.asgi:application, --wsgi-file config/wsgi.py), or in manage.py for
+ * runserver. When the start shows none, manage.py, wsgi.py and asgi.py must agree. null when unclear.
+ * @returns {{value: string, file: string}|null}
+ */
+function djangoSettings(service, ws, startText) {
+  const files = ws.files(service.dir)
+  const valueIn = (file) => /DJANGO_SETTINGS_MODULE["']\s*,\s*["']([\w.]+)["']/.exec(read(ws, file) ?? '')?.[1] ?? null
+  const found = (file) => { const value = file && valueIn(file); return value ? { value, file } : null }
+  const path = /(?:^|[\s"'=,[])(\/?(?:[\w.-]+\/)*)(wsgi|asgi)\.py(?=$|[\s"',\]])/.exec(startText)
+  const dotted = /(?:^|[\s"'=,[])((?:[A-Za-z_]\w*\.)*)(wsgi|asgi)(?::[\w.]+)?(?=$|[\s"',\]])/.exec(startText)
+  const entry = path ? `${path[1]}${path[2]}.py` : dotted ? `${dotted[1].replace(/\./g, '/')}${dotted[2]}.py` : null
+  if (entry) {
+    // The module path can start with folders of the image (/app/config/wsgi.py): match the longest tail that names 1 file.
+    const parts = entry.split('/').filter(Boolean)
+    for (let k = 0; k <= parts.length - Math.min(2, parts.length); k++) {
+      const tail = parts.slice(k).join('/')
+      const hits = files.filter((f) => f === join(service.dir, tail) || f.endsWith(`/${tail}`))
+      const exact = hits.find((f) => f === join(service.dir, tail))
+      if (exact || hits.length === 1) return found(exact ?? hits[0])
+    }
+    return null
+  }
+  if (/\bmanage\.py\b/.test(startText)) return found(join(service.dir, 'manage.py'))
+  const all = files.filter((f) => /(?:^|\/)(?:manage|wsgi|asgi)\.py$/.test(f)).map(found).filter(Boolean)
+  return all.length && all.every((x) => x.value === all[0].value) ? all.find((x) => /wsgi|asgi/.test(x.file)) ?? all[0] : null
+}
+
+/** The setting is set already where the app keeps its settings. */
+function alreadySet(name, service, ws) {
+  const docker = service.dockerfile ? read(ws, service.dockerfile) : null
+  const info = docker === null ? null : parseDockerfile(docker)
+  if (info && (info.env.has(name) || info.inherited.has(name))) return true
+  if (new RegExp(`^\\s*(export\\s+)?${name}=`, 'm').test(read(ws, join(service.dir, 'otel.env')) ?? '')) return true
+  return service.k8s.some((k) => new RegExp(`name:\\s*["']?${name}\\b`).test(read(ws, k.file) ?? ''))
+}
+
+const note = (re) => STACK.notes.find((text) => re.test(text)) ?? null
+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 ws.read(path) } catch { return null }
+}
+
+/** dir + a relative path, with . and .. resolved. null when it leaves the repo. */
+function resolvePath(dir, rel) {
+  const parts = dir === '.' ? [] : dir.split('/')
+  for (const part of rel.split('/')) {
+    if (part === '..') { if (!parts.length) return null; parts.pop() } else if (part && part !== '.') parts.push(part)
+  }
+  return parts.length ? parts.join('/') : null
+}

package/lib/types.mjs

@@ -0,0 +1,161 @@
+/*
+ * Shared types for @uknows/setup. JSDoc only: this module has no runtime code.
+ * Import types with: @typedef {import('./types.mjs').Service} Service
+ *
+ * Path rule: every path in these types, in the manifest and in the --json
+ * report is relative to the repo root (the --path folder, default the current
+ * folder) and uses '/' on every OS. The root folder itself is '.'.
+ */
+
+/** @typedef {'node'|'python'|'dotnet'|'java'|'go'|'php'|'ruby'} Lang */
+/** @typedef {Lang|'otel'} StackId  Same ids as contract STACKS. 'otel' = the app already uses OpenTelemetry: settings only. */
+/** @typedef {'azure-container-apps'|'kubernetes'|'alibaba-sae'|'vm-docker'|'github-actions'} HostId  Same ids as contract HOSTS. */
+
+/**
+ * @typedef {{file: string, line?: number, what: string}} Evidence  `what` is plain English, e.g. 'express in dependencies'.
+ *   Host evidence can name a file above the --path folder in the same git repo, as '../../k8s/api.yaml'. It is shown, never written.
+ */
+/** @typedef {{code: string, message: string}} Problem  `message` is 1 plain-English sentence. */
+
+/**
+ * @typedef {Object} Start  How the service starts, as the repo declares it.
+ * @property {'dockerfile'|'package.json'|'procfile'|'answer'} kind  'answer' = the user typed it at the prompt (file '', line 0).
+ * @property {string} file
+ * @property {number} line          1-based line of the ENTRYPOINT/CMD (ENTRYPOINT when both), the "start" key, or the web: line.
+ * @property {'exec'|'shell'} form  exec = Dockerfile JSON array. Everything else is shell.
+ * @property {string} raw           The command text. Dockerfile: ENTRYPOINT then CMD args, as written.
+ * @property {string[]|null} argv   Literal argv when the text has no shell syntax, else null.
+ */
+
+/**
+ * @typedef {Object} K8sTarget  A container in a plain Kubernetes manifest that runs this service.
+ * @property {string} file          e.g. 'k8s/api.yaml'
+ * @property {number} doc           0-based index of the YAML document in the file ('---' separated)
+ * @property {string} container     the container name
+ * @property {Record<string, string|null>} env  Its env list: name -> value, null for valueFrom. It replaces the image ENV.
+ * @property {boolean} command      It sets command:, which replaces the image ENTRYPOINT and CMD.
+ * @property {boolean} args         It sets args:, which replaces the image CMD.
+ */
+
+/**
+ * @typedef {Object} Service  One deployable app folder.
+ * @property {string} dir                 '.' or 'services/api'
+ * @property {Lang|null} lang             null = nothing recognized. The CLI then shows the language menu.
+ * @property {string[]} frameworks        Canonical ids, sorted:
+ *   node: express fastify nestjs koa hapi nitro nuxt next | python: fastapi django flask starlette falcon tornado
+ *   dotnet: aspnetcore | java: spring-boot quarkus micronaut | go: echo gin chi | php: laravel symfony slim | ruby: rails sinatra
+ * @property {string[]} manifests         Manifest paths in this folder, sorted.
+ * @property {string} name                Proposed OTEL_SERVICE_NAME: [a-z0-9-], 1 to 63 chars, no leading or trailing '-'.
+ * @property {string} nameFrom            'existing' (an OTEL_SERVICE_NAME already in the repo), a manifest basename, or 'folder'.
+ * @property {string|null} dockerfile     The Dockerfile that builds this service.
+ * @property {Start|null} start           The single start declaration. null when there is none or it is ambiguous (see problems).
+ * @property {string|null} runtimeVersion Version from the final FROM image tag ('3.12', '8.0', '22'), else from an exact declaration
+ *                                        (.python-version, TargetFramework 'net8.0' -> '8.0', go directive). Ranges such as
+ *                                        requires-python do not count. null when unknown.
+ * @property {K8sTarget[]} k8s            Plain k8s containers that run this service. Files with '{{' (Helm) are never listed.
+ * @property {Problem[]} problems         codes: start-ambiguous, start-hooks, start-unknown, dockerfile-ambiguous, frontend
+ * @property {Evidence[]} evidence        Why this folder is a service.
+ */
+
+/**
+ * @typedef {Object} Host
+ * @property {HostId} id
+ * @property {Evidence[]} evidence        Empty for the vm-docker fallback.
+ */
+
+/**
+ * @typedef {Object} Detection  What detect() returns. Static reading only: no commands, no network.
+ * @property {string} root                Absolute native path of the repo root.
+ * @property {Service[]} services         Sorted by dir. When nothing is recognized: 1 service {dir: '.', lang: null}.
+ * @property {Host[]} hosts               Runtime hosts in HOSTS order, then 'github-actions'. Never empty ('vm-docker' fallback).
+ * @property {Problem[]} problems         Repo-level notes, such as skipped large files.
+ */
+
+/** @typedef {{vendor: string, evidence: Evidence[]}} Apm  vendor: Datadog, New Relic, Elastic APM, Azure Monitor, Dynatrace, Instana or Sentry. */
+
+/**
+ * @typedef {Object} Existing  What findExisting() returns for 1 service.
+ * @property {Evidence[]} otel            OpenTelemetry SDK-level packages or agents already in use.
+ * @property {Apm[]} apm                  Other APM agents. Any entry stops the run (exit 1).
+ */
+
+/**
+ * @typedef {Object} Edit  One change to one text file.
+ * @property {string} file                Repo-relative path.
+ * @property {string|null} before         Exactly ctx.ws.read(file) when the producer read it (BOM removed). null = new file.
+ * @property {string} after               The full new text, without BOM. The engine puts the original BOM back.
+ * @property {string} why                 1 plain-English sentence, e.g. 'Load OpenTelemetry when node starts.'
+ */
+
+/**
+ * @typedef {Object} Command  A package manager run. The engine runs it after it writes the edits, only on apply.
+ * @property {string} cwd                 Repo-relative folder to run in.
+ * @property {string} cmd                 'npm' | 'pnpm' | 'yarn'
+ * @property {string[]} args              Exact argv, e.g. ['install', '--save', '@opentelemetry/api', '@opentelemetry/auto-instrumentations-node'].
+ * @property {string[]} touches           Repo-relative files it changes. The engine restores them when any step fails.
+ * @property {string[]} added             Packages it adds that were not there before. The manifest records them.
+ * @property {boolean} [lockOnly]         It writes only the files in touches (no node_modules).
+ * @property {{cmd: string, args: string[]}} undo   Removes `added`. The remove command runs it.
+ * @property {string} why                 Plan sentence, e.g. 'Add @opentelemetry/api and @opentelemetry/auto-instrumentations-node with npm.'
+ */
+
+/** @typedef {{caption: string, language: string, code: string}} Snippet  Same shape as contract snippets. */
+
+/**
+ * @typedef {Object} Block  A printable section: a manual step, a key step or a stop reason.
+ * @property {string} title               Sentence case, no final period, e.g. 'Set your key once on Kubernetes'.
+ * @property {string[]} lines             Plain-English sentences. The CLI prints them as a numbered list.
+ * @property {Snippet[]} [snippets]
+ */
+
+/** @typedef {{name: string, value: string}} Setting */
+
+/**
+ * @typedef {Object} Ctx  What appliers and settingsPlan() get.
+ * @property {import('./workspace.mjs').Workspace} ws   Reads include the edits staged earlier in this run.
+ * @property {string} name                The final OTEL_SERVICE_NAME of this service.
+ * @property {Detection} detection
+ * @property {import('./workspace.mjs').RepoView} [repo]  Reads files above the root too ('../x'), for --path runs. Never written.
+ * @property {string} [endpoint]          The ingest address for OTEL_EXPORTER_OTLP_ENDPOINT. Default: INGEST_ENDPOINT.
+ */
+
+/**
+ * @typedef {Object} StackPlan  What Applier.plan() returns.
+ * @property {string[]} summary           Plan sentences, e.g. 'Load OpenTelemetry when node starts (NODE_OPTIONS in Dockerfile).'
+ * @property {Edit[]} edits
+ * @property {Command[]} commands
+ * @property {Setting[]} extraSettings    Settings to place with the 5, e.g. DJANGO_SETTINGS_MODULE or OTEL_PHP_AUTOLOAD_ENABLED.
+ * @property {Block[]} manual             Steps the user must do. Any entry makes the run exit 3.
+ * @property {string[]} notes             Warnings and tips, 1 sentence each.
+ * @property {boolean} [stop]             Change nothing for this service, settings included: the user must run this tool elsewhere.
+ */
+
+/**
+ * @typedef {Object} Applier
+ * @property {StackId} id
+ * @property {(service: Service, ctx: Ctx) => StackPlan} plan
+ *   Pure: reads ctx.ws only. Never writes, runs, prompts or reads process.env.
+ *   Idempotent: planning its own output returns no edits and no commands.
+ */
+
+/**
+ * @typedef {Object} SettingsPlan  What settingsPlan() returns.
+ * @property {{kind: 'dockerfile'|'k8s'|'env-file', file: string}} target
+ * @property {Edit[]} edits               Empty when every setting is already there with the right value.
+ * @property {string[]} summary
+ * @property {Block[]} manual             e.g. a key committed in the repo, or an endpoint that points at another collector. Any entry: exit 3.
+ * @property {string[]} notes
+ */
+
+/**
+ * @typedef {Object} CheckResult  What runCheck() returns.
+ * @property {boolean} ok
+ * @property {number|null} status         HTTP status. null on a network error.
+ * @property {string|null} workspace
+ * @property {string|null} environment
+ * @property {string|null} [keyState]     From the site: active, retiring, or revoked. null when the site was not asked.
+ * @property {string[]} lines             What to print. Never contains the key.
+ * @property {0|1|2} exit                 0 reached, 1 rejected or network error, 2 OTEL_EXPORTER_OTLP_HEADERS is not set.
+ */
+
+export {}