@uknows/setup 0.1.0 → 0.2.0

package/lib/stacks/python-sets.mjs

@@ -0,0 +1,143 @@
+/*
+ * Which OpenTelemetry set (PINS.python.sets, newest first) a Python app gets. The first set that fits the direct
+ * limits of the app (protobuf and opentelemetry-* in its dependency files) and its Python version wins. pip apps get
+ * exact pins from that set. uv and Poetry apps get floors, and the set only decides which instrumentation packages
+ * exist for them (bootstrap SINCE). The plan says why when it is not the newest set.
+ */
+import { PINS, RESOLVE } from '../contract.mjs'
+import { tomlArray, tomlEntries, tomlTable } from '../toml.mjs'
+import { clauses, compareVersion, lowestRelease, overlaps, satisfies } from '../versions.mjs'
+import { normalize } from './python-bootstrap.mjs'
+
+/** opentelemetry-* packages on the core release line (1.x), and on the contrib line (0.xb). Other names are ignored. */
+const CORE = /^opentelemetry-(?:api|sdk|proto|exporter-otlp(?:-proto-(?:http|grpc|common))?)$/
+const CONTRIB = /^opentelemetry-(?:distro|instrumentation(?:-[\w-]+)?|semantic-conventions|util-http)$/
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+const read = (ws, path) => { try { return ws.read(path) } catch { return null } }
+
+/**
+ * @typedef {{name: string, spec: string, style: 'python'|'poetry', file: string, line: number, value: string}} Limit
+ */
+
+/**
+ * The direct limits that decide the set: protobuf and opentelemetry-* entries with a version limit, in requirements
+ * files (1 level of -r), [project] dependencies and [tool.poetry.dependencies] of these pyproject.toml files.
+ * @param {any} ws
+ * @param {string[]} files  dependency files: requirements*.txt or pyproject.toml
+ * @returns {Limit[]}
+ */
+export function directLimits(ws, files) {
+  const out = []
+  const relevant = (name) => name === 'protobuf' || CORE.test(name) || CONTRIB.test(name)
+  const seen = new Set()
+  const fromRequirements = (file, depth) => {
+    if (seen.has(file)) return
+    seen.add(file)
+    const text = read(ws, file)
+    if (text === null) return
+    text.split(/\r?\n/).forEach((raw, i) => {
+      const line = raw.replace(/(^|\s)#.*$/, '').trim()
+      const include = /^(?:-r|--requirement)(?:\s+|=)(\S+)/.exec(line)
+      if (include && depth === 0) return fromRequirements(join(dirOf(file), include[1]), 1)
+      const m = /^([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]*\])?\s*([<>=!~][^;]*)?/.exec(line)
+      if (m?.[2] && relevant(normalize(m[1]))) out.push({ name: normalize(m[1]), spec: m[2].trim(), style: 'python', file, line: i + 1, value: line.split(';')[0].trim() })
+    })
+  }
+  for (const file of files) {
+    if (/\.txt$/.test(file)) { fromRequirements(file, 0); continue }
+    const text = read(ws, file)
+    if (text === null) continue
+    const lines = text.split(/\r?\n/)
+    for (const req of tomlArray(tomlTable(text, 'project'), 'dependencies')) {
+      const m = /^\s*([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]*\])?\s*([<>=!~][^;]*)?/.exec(req)
+      if (!m?.[2] || !relevant(normalize(m[1]))) continue
+      const line = lines.findIndex((l) => l.includes(req)) + 1
+      out.push({ name: normalize(m[1]), spec: m[2].trim(), style: 'python', file, line, value: req.split(';')[0].trim() })
+    }
+    for (const { key, value, line } of tomlEntries(text, 'tool.poetry.dependencies')) {
+      const name = normalize(key)
+      const spec = /^["']([^"']*)["']/.exec(value)?.[1] ?? /\bversion\s*=\s*["']([^"']*)["']/.exec(value)?.[1]
+      if (spec && spec !== '*' && relevant(name)) out.push({ name, spec, style: 'poetry', file, line, value: `${key} = ${value}` })
+    }
+  }
+  return out
+}
+
+/** The Python versions a uv or Poetry project must support: the lowest of requires-python, or python in Poetry. */
+export function projectPython(ws, files) {
+  for (const file of files.filter((f) => /pyproject\.toml$/.test(f))) {
+    const text = read(ws, file) ?? ''
+    const requires = /^\s*requires-python\s*=\s*["']([^"']+)["']/m.exec(tomlTable(text, 'project'))?.[1]
+    const low = requires ? lowestRelease(requires) : null
+    if (low) return low
+    const poetry = tomlEntries(text, 'tool.poetry.dependencies').find((e) => e.key === 'python')
+    const spec = poetry && /^["']([^"']*)["']/.exec(poetry.value)?.[1]
+    const lowPoetry = spec ? lowestRelease(spec, 'poetry') : null
+    if (lowPoetry) return lowPoetry
+  }
+  return null
+}
+
+/** True when the set allows the limit. */
+function fits(set, limit) {
+  if (limit.name === 'protobuf') return overlaps(limit.spec, set.protobuf, limit.style)
+  if (CORE.test(limit.name)) return satisfies(set.core, limit.spec, limit.style)
+  if (CONTRIB.test(limit.name)) return satisfies(set.contrib, limit.spec, limit.style)
+  return true
+}
+
+/**
+ * The first set that fits. why: the plan sentence when it is not the newest set. When none fits: the required step.
+ * @param {{limits: Limit[], python: [number, number]|null, tool?: string|null}} opts  tool: uv or poetry for floors, else pins.
+ * @returns {{set: typeof PINS.python.sets[number], why: string|null}|{block: import('../types.mjs').Block}}
+ */
+export function pickSet({ limits, python, tool = null }) {
+  const sets = PINS.python.sets
+  const pyOk = (set) => !python || python[0] * 1000 + python[1] >= set.minPython[0] * 1000 + set.minPython[1]
+  const index = sets.findIndex((set) => pyOk(set) && limits.every((l) => fits(set, l)))
+  if (index < 0) {
+    const limit = limits.find((l) => sets.filter(pyOk).every((set) => !fits(set, l)))
+    if (!limit) return { block: oldPython(python) }
+    return { block: { title: RESOLVE.python.noSet.title, lines: RESOLVE.python.noSet.lines.map((l) => fill(l, limit)) } }
+  }
+  const set = sets[index]
+  if (index === 0) return { set, why: null }
+  const newest = sets[0]
+  const limit = limits.find((l) => !fits(newest, l))
+  const values = { ...limit, python: python?.join('.'), newest: newest.core, need: newest.minPython.join('.'), core: set.core, contrib: set.contrib, tool }
+  const text = limit ? (tool ? RESOLVE.python.floorLimit : RESOLVE.python.olderLimit) : tool ? RESOLVE.python.floorPython : RESOLVE.python.olderPython
+  return { set, why: fill(text, values) }
+}
+
+/** The step for a Python version below every set. */
+function oldPython(python) {
+  const oldest = PINS.python.sets.at(-1)
+  const need = oldest.minPython.join('.')
+  return { title: `Use Python ${need} or later`, lines: [`This app uses Python ${python.join('.')}.`,
+    `opentelemetry-distro ${oldest.contrib} needs Python ${need} or later.`, 'Update the Python version of the app. Then run npx @uknows/setup again.'] }
+}
+
+/** Requirement text of 1 package: name==version or name>=floor. */
+export const requirement = (name, version, floor = null) => (floor ? `${name}>=${floor}` : `${name}==${version}`)
+
+/** The package name of a requirement text. */
+export const requirementName = (req) => normalize(/^[A-Za-z0-9][A-Za-z0-9._-]*/.exec(req)?.[0] ?? req)
+
+/** The lowest protobuf release a lock has, as a limit, so the set fits a lock that keeps protobuf below 5. */
+export function lockedLimit(installed, name) {
+  const item = installed?.packages?.get(name)
+  if (!item?.version || !clauses(`==${item.version}`).length) return null
+  return { name, spec: `==${item.version}`, style: 'python', file: item.file, line: item.line ?? 0, value: `${item.name} ${item.version}` }
+}
+
+export { compareVersion }
+
+const dirOf = (path) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '.')
+function join(dir, rel) {
+  const parts = dir === '.' ? [] : dir.split('/')
+  for (const part of rel.split('/')) {
+    if (part === '..') parts.pop()
+    else if (part && part !== '.') parts.push(part)
+  }
+  return parts.join('/') || '.'
+}

package/lib/stacks/python.mjs

@@ -3,18 +3,36 @@
  * 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, or (without a Dockerfile) the platform installs
- * it. Otherwise the image would fail to start, so the start goes into a
- * manual step instead.
+ * 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, parseDockerfile, prefixStart, reachingStages } from '../dockerfile.mjs'
-import { PINS, STACKS } from '../contract.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'
@@ -22,32 +40,82 @@ 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 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.'] })
+    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
     }
-    if (!service.runtimeVersion) out.notes.push(`Check that the app uses Python ${major}.${minor} or later. ${PINS.python.distro.split('==')[0]} needs it.`)
+    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.`)
 
-    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)
+    // 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)
-    else if (ready) {
-      out.manual.push({ title: `Install ${deps.file} in the image`, lines: [
+    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] })
@@ -70,21 +138,91 @@ export const python = {
           '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.
- * view reads lockfiles above the --path folder.
+ * 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) {
-  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
+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] })
@@ -98,22 +236,14 @@ function addPackages(deps, missing, ws, view, out) {
     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 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}.`)
-  if (!lockReady) out.manual.push(relockBlock(lock, deps.file))
-  return lockReady
+  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) {
@@ -123,6 +253,29 @@ function relockBlock(lock, file) {
     ...(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.' })
@@ -135,11 +288,12 @@ function wrapStart(service, ws, docker, out) {
     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 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 = /venv\/bin\/[^/]+$/.test(words[0]) ? words[0].replace(/[^/]+$/, INSTRUMENT) : INSTRUMENT
-    const after = RUNNERS.test(base(words[0])) && words[1] === 'run' ? null : prefixStart(docker, [word])
+    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)
@@ -149,16 +303,19 @@ function wrapStart(service, ws, docker, out) {
   }
   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+/)
-  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}`))
+  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 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}`)
+  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) {
@@ -195,9 +352,12 @@ function pickDeps(service, ws, docker) {
   }
   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)
+    const file = installs.files.find((f) => !/\.toml$/.test(f) && read(ws, f) !== null)
     if (file) return requirements(file, true)
-    const found = (installs.project && project(true)) || (installs.pipfile && pipfile(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.
@@ -208,11 +368,15 @@ function pickDeps(service, ws, docker) {
 
 /**
  * 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.
+ * 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}}
  */
-function dockerInstalls(service, docker) {
-  const out = { files: [], project: false, pipfile: false }
+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 = ''
@@ -224,20 +388,29 @@ function dockerInstalls(service, docker) {
       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 (/\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])
-          if (flag) out.files.push(...repoPaths(service, workdir, flag[1] ?? words[++k] ?? ''))
-          else if (/^\.\/?(?:\[[^\]]*\])?$/.test(words[k])) out.project = true
+          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
 }
 
@@ -249,6 +422,26 @@ function repoPaths(service, workdir, raw) {
   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) ?? ''
@@ -271,7 +464,7 @@ function requirementNames(ws, file, depth = 0) {
 }
 
 /** The PEP 621 [project] dependencies array, else the [tool.poetry.dependencies] table. null when neither. */
-function parsePyproject(text) {
+export function parsePyproject(text) {
   const doc = new Doc(text)
   const table = (re) => {
     const head = doc.find((line) => re.test(line.replace(/#.*$/, '').trim()))
@@ -320,11 +513,16 @@ function scanArray(doc, line, col) {
   return null
 }
 
-function editPyproject(text, deps, missing) {
+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)) : ''
-    doc.insert(deps.last + 1, ...missing.map((req) => `${indent}${req.split('==')[0]} = "${req.split('==')[1]}"`))
+    // 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
@@ -352,13 +550,13 @@ function editPyproject(text, deps, missing) {
   return doc.toString()
 }
 
-function appendLines(text, lines) {
+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). */
-function findLock(view, dir) {
+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)
   }