@uknows/setup 0.0.0-stage → 0.2.0

package/lib/stacks/python.mjs

@@ -0,0 +1,632 @@
+/*
+ * 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.
+ *
+ * Versions: pip apps (requirements.txt, or a pyproject.toml with no lock) get
+ * exact pins from the first known-good set that fits the app (python-sets.mjs).
+ * uv and Poetry apps get floors, and the tool runs their own resolver (uv lock in
+ * the workspace root, poetry lock). The engine records the lock it rewrites as a
+ * text change. The set decides which instrumentation packages exist for them.
+ *
+ * Logs: the OpenTelemetry logging package on the root logger changes what the app prints (Python's last-resort output,
+ * logging.warning() before any setup and Flask's own handler stop: install proof, 22 Oct 2026). So it stays off the
+ * root logger (OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION=false) and the UKNOWS log bridge (PYTHON_LOG_BRIDGE, a folder that
+ * the image copies and PYTHONPATH names) sends the log records instead. Only an image whose start gets
+ * opentelemetry-instrument gets the bridge and the logging package. Without it the app sends no logs.
+ *
+ * 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 (uv sync --package installs only that member), or
+ * (without a Dockerfile) the platform installs it, and its lock has them after
+ * this run. Otherwise the image would fail to start, so the start goes into a
+ * manual step instead. A Procfile is never changed: the hosts this tool supports
+ * do not read it, so its line is a required step.
+ */
+import { buildContext, ignoredBy } from '../context.mjs'
+import { Doc, indentOf } from '../doc.mjs'
+import { dockerStart, formatEnv, insertBeforeStart, insertStart, parseDockerfile, reachingStages } from '../dockerfile.mjs'
+import { PINS, PYTHON_BRIDGE_COPY, PYTHON_BRIDGE_PATH, PYTHON_LOG_BRIDGE, RESOLVE, STACKS } from '../contract.mjs'
+import { pyName, tomlString, tomlTable } from '../toml.mjs'
+import { upFrom } from '../workspace.mjs'
+import { startOverrides } from './k8s.mjs'
+import { bootstrap, normalize } from './python-bootstrap.mjs'
+import { LOCK_TOOLS, lockStep } from './python-lock.mjs'
+import { directLimits, lockedLimit, pickSet, projectPython, requirement, requirementName } from './python-sets.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.'
+const DISTRO = 'opentelemetry-distro', EXPORTER = 'opentelemetry-exporter-otlp-proto-http'
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+
+/**
+ * Options of uv run and poetry run before the command: options that take a value, options that do not, and options
+ * that change what the command is (opentelemetry-instrument cannot go in front of a module or a script).
+ */
+const RUN_OPTIONS = {
+  uv: {
+    value: new Set(['--extra', '--group', '--no-group', '--only-group', '--package', '--with', '--with-editable', '--with-requirements',
+      '--python', '-p', '--env-file', '--index', '--default-index', '--index-url', '-i', '--extra-index-url', '--find-links', '-f',
+      '--upgrade-package', '-P', '--reinstall-package', '--no-build-package', '--no-binary-package', '--index-strategy', '--keyring-provider',
+      '--resolution', '--prerelease', '--fork-strategy', '--exclude-newer', '--exclude-newer-package', '--no-sources-package', '--link-mode',
+      '--config-setting', '-C', '--config-settings-package', '--python-platform', '--directory', '--project', '--config-file', '--cache-dir',
+      '--color', '--python-preference', '--allow-insecure-host', '--refresh-package', '--no-extra']),
+    flag: new Set(['--no-sync', '--frozen', '--locked', '--no-dev', '--dev', '--all-extras', '--all-groups', '--no-default-groups', '--only-dev',
+      '--no-editable', '--exact', '--inexact', '--isolated', '--active', '--no-active', '--no-project', '--no-config', '--offline', '--no-cache', '-n',
+      '-q', '--quiet', '-v', '--verbose', '--native-tls', '--no-progress', '--all-packages', '--no-env-file', '--compile-bytecode',
+      '--no-build-isolation', '--no-build', '--no-binary', '--reinstall', '--upgrade', '-U', '--refresh', '--no-python-downloads',
+      '--managed-python', '--no-managed-python', '--preview', '--no-sources', '--no-install-project', '--no-install-workspace', '--no-install-local']),
+    refuse: new Set(['-m', '--module', '-s', '--script', '--gui-script', '-w']),
+  },
+  poetry: {
+    value: new Set(['-C', '--directory', '-P', '--project']),
+    flag: new Set(['-q', '--quiet', '-v', '-vv', '-vvv', '--verbose', '-n', '--no-interaction', '--ansi', '--no-ansi', '--no-plugins', '--no-cache']),
+    refuse: new Set(),
+  },
+}
+
+/** @type {import('../types.mjs').Applier} */
+export const python = {
+  id: 'python',
+  plan(service, ctx) {
+    const { ws } = ctx
+    const view = ctx.repo ?? ws
+    const out = { summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [] }
+    const docker = service.dockerfile ? read(ws, service.dockerfile) : null
+    const deps = pickDeps(service, ws, docker)
+    const lockFile = deps.kind === 'pep621' || deps.kind === 'poetry' ? findLock(view, dirOf(deps.file)) : null
+    const tool = lockFile ? LOCK_TOOLS[base(lockFile)] ?? null : null
+    const installed = ctx.installed ?? ctx.existing?.installed ?? null
+
+    // The OpenTelemetry versions: the first known-good set that fits the limits and the Python of the app.
+    const files = deps.file ? [deps.file, ...(tool && lockFile ? [join(dirOf(lockFile), 'pyproject.toml')] : [])] : []
+    const limits = [...directLimits(view, [...new Set(files)]), ...(tool ? [lockedLimit(installed, 'protobuf')].filter(Boolean) : [])]
+    const runtime = /^(\d+)\.(\d+)/.exec(service.runtimeVersion ?? '')?.slice(1, 3).map(Number) ?? null
+    const pythonVersion = (tool && projectPython(view, [...new Set(files)])) || runtime
+    const picked = pickSet({ limits, python: pythonVersion, tool: tool && `${tool} lock` })
+    if (picked.block) {
+      out.manual.push(picked.block)
+      out.stop = true
+      return out
+    }
+    const { set } = picked
+    if (picked.why) out.notes.push(picked.why)
+    if (!pythonVersion) out.notes.push(`Check that the app uses Python ${set.minPython.join('.')} or later. ${DISTRO} ${set.contrib} needs it.`)
+
+    // uv and Poetry: floors, and the names in the lock closure count too, as opentelemetry-bootstrap reads what is
+    // installed. Packages that arrive only through OpenTelemetry packages do not count, so a second run adds nothing.
+    const floor = tool ? PINS.python.floors : null
+    const app = (item) => item.direct || !item.via.length || item.via.some((v) => !v.startsWith('opentelemetry-'))
+    const names = new Set([...deps.names, ...(tool && installed ? [...installed.packages].filter(([, item]) => app(item)).map(([key]) => key) : [])])
+    // The log bridge: only where the image installs the packages and its start can get opentelemetry-instrument.
+    const bridge = docker !== null && deps.proven ? placeBridge(service, view, docker, ctx) : null
+    const wanted = [requirement(DISTRO, set.contrib, floor?.contrib), requirement(EXPORTER, set.core, floor?.core),
+      ...bootstrap(names, set.contrib, { floor: floor?.contrib ?? null, logs: Boolean(bridge?.copy) })]
+    const missing = wanted.filter((req) => !deps.names.has(requirementName(req)))
+    const lock = lockFile && { file: lockFile, step: tool ? lockStep({ view, lockFile, tools: ctx.tools, dockerfile: service.dockerfile, docker, packages: 'the OpenTelemetry packages' }) : null }
+    const ready = addPackages(deps, missing, ws, view, out, lock)
+    if (out.stop) return out
+
+    if (ready && deps.proven) {
+      wrapStart(service, ws, docker, out)
+      if (bridge) addBridge(service, ws, docker, bridge, out)
+    } else if (ready) {
+      out.manual.push({ title: `Install ${deps.file} in the image`, verify: true, 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) })
+      }
+    }
+    // The settings of the docs for Python: the logging package off the root logger, and the host name of the app.
+    for (const line of STACK.extraSettings?.lines ?? []) out.extraSettings.push({ name: line.slice(0, line.indexOf('=')), value: line.slice(line.indexOf('=') + 1) })
+    return out
+  },
+}
+
+const BRIDGE_FILES = PYTHON_LOG_BRIDGE.files.map((file) => ({ path: file.path, text: `${file.content}\n` }))
+
+/**
+ * Where the log bridge goes: {dir, copy} with the COPY line from the build context, or {why} when this tool is not sure
+ * that the image would have it. The folder sits next to the dependency file of the service.
+ */
+function placeBridge(service, view, docker, ctx = {}) {
+  const dir = join(service.dir, PYTHON_LOG_BRIDGE.dir)
+  const info = parseDockerfile(docker)
+  const start = dockerStart(info)
+  // The bridge needs opentelemetry-instrument in the start, which wrapStart adds where it can.
+  if (!start || instrumentAt(start.argv ?? start.raw.replace(/^exec\s+/, '').split(/\s+/)) === null) {
+    return { why: `this tool cannot start the app with opentelemetry-instrument in ${service.dockerfile}` }
+  }
+  const context = buildContext(view, service.dockerfile, info, service.dir)
+  if (context === null) return { why: `this tool cannot tell the build context of ${service.dockerfile} from its COPY lines` }
+  if (context !== '.' && !dir.startsWith(`${context}/`)) return { why: `${dir} is outside the build context of ${service.dockerfile}` }
+  const source = context === '.' ? dir : dir.slice(context.length + 1)
+  for (const file of BRIDGE_FILES) {
+    const ignore = ignoredBy(view, context, service.dockerfile, `${source}/${file.path}`)
+    if (ignore) return { why: `${ignore} leaves ${dir} out of the build context` }
+  }
+  if (!read(view, join(dir, BRIDGE_FILES[0].path)) && ctx.ignored?.(join(dir, BRIDGE_FILES[0].path))) {
+    return { why: `.gitignore leaves ${dir} out of git, so the build in your pipeline would not have it` }
+  }
+  return { dir, copy: PYTHON_BRIDGE_COPY.replace(` ${PYTHON_LOG_BRIDGE.dir} `, ` ${source} `) }
+}
+
+/**
+ * The bridge in the repo and in the image: its 3 files (a file that is there stays as it is), the COPY line before the
+ * start of the final stage, and PYTHONPATH. Or, when the image would not have it, a note that the app sends no logs.
+ */
+function addBridge(service, ws, docker, bridge, out) {
+  if (!bridge.copy) {
+    out.notes.push(`This app sends no logs to UKNOWS: ${bridge.why}. Its traces go as usual.`)
+    return
+  }
+  for (const file of BRIDGE_FILES) {
+    const path = join(bridge.dir, file.path)
+    const current = read(ws, path)
+    if (current === null) out.edits.push({ file: path, before: null, after: file.text, why: 'Send the log records of the app without changing what it prints.' })
+    else if (current !== file.text) out.notes.push(`${path} is there already. This tool keeps it as it is.`)
+  }
+  // The COPY line and PYTHONPATH, in 1 block before the start. PYTHONPATH keeps a value that the image has (${...} is
+  // left for Docker to fill in, so it is not escaped).
+  const earlier = out.edits.find((e) => e.file === service.dockerfile)
+  const now = earlier ? earlier.after : docker
+  const lines = now.split('\n').map((l) => l.trim())
+  const path = formatEnv([[PYTHON_BRIDGE_PATH.slice(0, PYTHON_BRIDGE_PATH.indexOf('=')), PYTHON_BRIDGE_PATH.slice(PYTHON_BRIDGE_PATH.indexOf('=') + 1)]],
+    { raw: true, escape: parseDockerfile(now).escape })
+  const missing = [...(lines.includes(bridge.copy) ? [] : [bridge.copy]), ...path.filter((l) => !lines.includes(l.trim()))]
+  const after = missing.length ? insertBeforeStart(now, missing) : now
+  if (after !== now) {
+    if (earlier) earlier.after = after
+    else out.edits.push({ file: service.dockerfile, before: docker, after, why: 'Copy the UKNOWS log bridge into the image.' })
+  }
+  out.summary.push(`Send the log records of the app with the UKNOWS log bridge (${bridge.dir}). What the app prints stays the same.`)
+}
+
+/**
+ * Add the missing packages. Returns true when the dependency list has them after this run, and its lockfile too.
+ * lock: the uv, Poetry or PDM lockfile of the project, and the lock step for it. A uv or Poetry lock that lacks the
+ * packages gets a lock command, which runs after the edits. When the tool cannot run it, nothing changes (stop).
+ */
+function addPackages(deps, missing, ws, view, out, lock) {
+  const lockReady = !lock || /name\s*=\s*"opentelemetry-distro"/.test(read(view, lock.file) ?? '')
+  const relock = Boolean(lock) && (missing.length > 0 || !lockReady)
+  if (relock && lock.step?.block) {
+    out.manual.push(lock.step.block)
+    out.stop = true
+    return false
+  }
+  const refresh = () => {
+    if (!relock) return true
+    if (lock.step?.command) { out.commands.push(lock.step.command); return true }
+    out.manual.push(relockBlock(lock.file, deps.file))
+    return false
+  }
+  if (!missing.length) return refresh()
+  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(' ')}`)
+  }
+  const compiled = deps.kind === 'requirements' ? compiledRequirements(ws, deps.file) : null
+  if (compiled) return stop('Add the OpenTelemetry packages', compiled)
+  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}${lock?.step?.command ? `, as lower limits. ${lock.step.command.cmd} lock picks the versions` : ''}.`)
+  return refresh()
+}
+
+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] }
+}
+
+/**
+ * Where opentelemetry-instrument goes in a start command: 0, or after uv run or poetry run and their options.
+ * null when it cannot go in safely (another runner, a module or script option, an option this tool does not know).
+ */
+export function instrumentAt(words) {
+  if (!words?.length) return null
+  const runner = base(words[0])
+  if (!RUNNERS.test(runner) || words[1] !== 'run') return 0
+  const options = RUN_OPTIONS[runner]
+  if (!options) return null
+  for (let i = 2; i < words.length; i++) {
+    const w = words[i]
+    if (w === '--') return i + 1 < words.length ? i + 1 : null
+    if (!w.startsWith('-')) return i
+    const flag = w.split('=')[0]
+    if (options.refuse.has(flag)) return null
+    if (w.includes('=') && (options.value.has(flag) || options.flag.has(flag))) continue
+    if (options.value.has(flag)) { i++; continue }
+    if (!options.flag.has(flag)) return null
+  }
+  return null
+}
+
+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)
+    const at = instrumentAt(words)
+    if (at !== null && [base(words[at]), base(words[0])].includes(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 = at === 0 && /venv\/bin\/[^/]+$/.test(words[0]) ? words[0].replace(/[^/]+$/, INSTRUMENT) : INSTRUMENT
+    const after = at === null ? null : insertStart(docker, at, [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 }
+  // A Procfile is never changed. The supported hosts do not read it, so the line is a step for platforms that do.
+  const words = web.cmd.trim().split(/\s+/)
+  const at = instrumentAt(words)
+  if (at !== null && base(words[at]) === INSTRUMENT) return
+  const safe = at !== null && words[0] && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]) && !/[;|`]|&&|&\s*$/.test(web.cmd)
+  const lines = RESOLVE.python.procfile.lines.map((l) => fill(l, { file: web.file }))
+  if (!safe) {
+    out.manual.push({ title: RESOLVE.python.procfile.title, verify: true, lines: [lines[0], note(/in front of the command/)].filter(Boolean),
+      snippets: [{ caption: 'Start command', language: 'bash', code: STACK.start }] })
+    return
+  }
+  const line = `${web.head}${[...words.slice(0, at), INSTRUMENT, ...words.slice(at)].join(' ')}`
+  out.manual.push({ title: RESOLVE.python.procfile.title, verify: true, lines, snippets: [{ caption: web.file, language: 'text', code: line }] })
+}
+
+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) => !/\.toml$/.test(f) && read(ws, f) !== null)
+    if (file) return requirements(file, true)
+    // uv sync --package <name> installs that workspace member only: the pyproject.toml of another member is not proven.
+    const own = tomlString(tomlTable(read(ws, join(dir, 'pyproject.toml')) ?? '', 'project'), 'name')
+    const member = installs.packages === null || (own !== null && installs.packages.includes(pyName(own)))
+    const found = (installs.project && member && 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, pip install -r pyproject.toml, poetry
+ * install, uv sync, pdm install, or an export of them), and the Pipfile (pipenv install). Paths are repo paths, found from the WORKDIR.
+ * packages: when every project install is uv sync --package <name>, the names of those workspace members (PEP 503).
+ * uv sync installs only that member and what it depends on. null: the whole project (or every member).
+ * @returns {{files: string[], project: boolean, pipfile: boolean, packages: string[]|null}}
+ */
+export function dockerInstalls(service, docker) {
+  const out = { files: [], project: false, pipfile: false, packages: null }
+  const named = [], whole = []
+  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
+          const member = /\buv\s+(?:sync|export)\b.*?\s--package(?:\s+|=)["']?([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(part)
+          if (member && !/\s--all-packages\b/.test(part)) named.push(pyName(member[1]))
+          else whole.push(part)
+        }
+        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])
+          const file = flag ? flag[1] ?? words[++k] ?? '' : null
+          // uv pip install -r pyproject.toml installs the dependencies of the project, not a requirements file.
+          if (file !== null && /\.toml$/.test(file)) { out.project = true; whole.push(part) }
+          else if (file !== null) out.files.push(...repoPaths(service, workdir, file))
+          else if (/^\.\/?(?:\[[^\]]*\])?$/.test(words[k])) { out.project = true; whole.push(part) }
+        }
+      }
+    }
+  }
+  // An exported list (poetry export -o requirements.txt) is built from the lockfile, not from a file in the repo.
+  if (exported) out.files = []
+  if (named.length && !whole.length) out.packages = [...new Set(named)]
+  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)
+}
+
+/**
+ * Why this tool must not add lines to a requirements file, as the lines to print: it uses --hash (pip then needs a
+ * hash for every line), a .in file next to it builds it (pip-tools), or pip-compile or uv pip compile wrote it (the
+ * next compile drops lines that this tool adds). null when the tool can add lines.
+ */
+export function compiledRequirements(ws, file) {
+  if (requirementNames(ws, file).hashes) {
+    return [`${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 = file.replace(/\.txt$/, '.in')
+  if (source !== file && read(ws, source) !== null) return [`${file} is built from ${source} by pip-tools.`, `Add these lines to ${source}.`, `Run pip-compile ${base(source)}.`]
+  const head = (read(ws, file) ?? '').split(/\r?\n/).slice(0, 12).join('\n')
+  const tool = /^#\s*This file (?:is|was) autogenerated by (pip-compile|uv)\b/m.exec(head)?.[1]
+  if (tool) {
+    const name = tool === 'uv' ? 'uv pip compile' : 'pip-compile'
+    return [`${name} writes ${file}, so the next ${name} run would drop lines that this tool adds.`, `Add these packages to the file that ${name} reads. Then run ${name} again.`]
+  }
+  return null
+}
+
+/** 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. */
+export 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
+}
+
+export 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)) : ''
+    // Poetry writes an exact version as "1.2" and a limit as ">=1.2".
+    const entry = (req) => {
+      const [, name, op, version] = /^([A-Za-z0-9][A-Za-z0-9._-]*)\s*(==|>=|<=|~=|!=|>|<)?\s*(.*)$/.exec(req)
+      return `${indent}${name} = "${!op || op === '==' ? version || '*' : `${op}${version}`}"`
+    }
+    doc.insert(deps.last + 1, ...missing.map(entry))
+    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()
+}
+
+export 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). */
+export 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
+}