@uknows/setup 0.0.0-stage → 0.2.0

package/lib/stacks/channel.mjs

@@ -0,0 +1,125 @@
+// The agent channel (--channel stable|early): for a Java, .NET or Node.js service that builds from a Dockerfile, the
+// agent comes from the UKNOWS agent image at every build. The change is 1 COPY line and the start settings in the
+// final stage, after the last RUN. Packages, lock files and the start command do not change.
+//
+//   COPY --from=<registry>/agent-<lang>:<channel> /uknows/ /uknows/
+//   Java     JAVA_TOOL_OPTIONS  -javaagent:/uknows/java/uknows-loader.jar
+//   Node.js  NODE_OPTIONS       --require /uknows/node/register.cjs   (ES modules: --import /uknows/node/register.mjs)
+//   .NET     CORECLR_* (the OpenTelemetry profiler for glibc or musl), OTEL_DOTNET_AUTO_HOME, DOTNET_STARTUP_HOOKS
+//
+// Each language starts through a small UKNOWS loader in the image. It checks the agent files (size and checksum)
+// and starts the agent, or prints 1 line and lets the app start without it. So an agent file that is missing or
+// broken never stops the app.
+import { AGENT_CHANNELS, AGENT_REGISTRY, STACKS } from '../contract.mjs'
+import { addOption, dockerStart, insertBeforeStart, parseDockerfile, setEnv } from '../dockerfile.mjs'
+import { entryOf } from './node.mjs'
+import { targetFramework, webProject } from './dotnet.mjs'
+
+export const CHANNELS = AGENT_CHANNELS
+export const LANGS = ['java', 'dotnet', 'node']
+const DOTNET_PROFILER = '{918728DD-259F-4A6A-AC2B-B85E1B658318}'
+const WINDOWS = /windows|nanoserver|servercore/i
+
+/** The registry and path that hold the agent images, for example registry.example.com/uknows. No scheme, no tag. */
+export function validRegistry(value) {
+  return typeof value === 'string' && AGENT_REGISTRY.test(value)
+}
+
+export const image = (registry, lang, channel) => `${registry}/agent-${lang}:${channel}`
+export const copyLine = (registry, lang, channel) => `COPY --from=${image(registry, lang, channel)} /uknows/ /uknows/`
+
+/** The settings that start the agent of 1 language. */
+export function startSettings(lang, { esm = false, musl = false } = {}) {
+  if (lang === 'java') return { option: ['JAVA_TOOL_OPTIONS', '-javaagent:/uknows/java/uknows-loader.jar'] }
+  if (lang === 'node') return { option: ['NODE_OPTIONS', esm ? '--import /uknows/node/register.mjs' : '--require /uknows/node/register.cjs'] }
+  return { env: [
+    ['CORECLR_ENABLE_PROFILING', '1'],
+    ['CORECLR_PROFILER', DOTNET_PROFILER],
+    ['CORECLR_PROFILER_PATH', `/uknows/dotnet/${musl ? 'musl' : 'glibc'}/OpenTelemetry.AutoInstrumentation.Native.so`],
+    ['OTEL_DOTNET_AUTO_HOME', '/uknows/dotnet'],
+    ['DOTNET_STARTUP_HOOKS', '/uknows/dotnet/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll'],
+  ] }
+}
+
+/** Does this service fit the channel? null when it does, else the reason (it then keeps the package route). */
+export function channelMisfit(service) {
+  if (!LANGS.includes(service.lang)) return 'The agent channel has Java, .NET and Node.js.'
+  if (!service.dockerfile) return 'The agent channel needs a Dockerfile, and this service does not build from one.'
+  return null
+}
+
+const read = (ws, path) => { try { return ws.read(path) } catch { return null } }
+
+/** @type {import('../types.mjs').Applier} */
+export const channel = {
+  id: 'channel',
+  plan(service, ctx) {
+    const plan = { summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [] }
+    const { registry, name: channelName } = ctx.channel ?? {}
+    if (!validRegistry(registry) || !CHANNELS.includes(channelName)) throw new Error('The agent channel needs its registry and its name.')
+    const lang = service.lang
+    const text = read(ctx.ws, service.dockerfile)
+    const info = text === null ? null : parseDockerfile(text)
+    const base = info?.image ?? ''
+    if (!info) {
+      plan.manual.push({ title: 'Add the UKNOWS agent', lines: [`This tool cannot read ${service.dockerfile}.`] })
+      return plan
+    }
+    if (WINDOWS.test(base)) {
+      plan.manual.push({ title: 'Add the UKNOWS agent', lines: [`The final image ${base} is a Windows image. The agent channel has Linux images only.`] })
+      return plan
+    }
+    const musl = /alpine/i.test(base)
+    let esm = false
+    if (lang === 'node') {
+      const v = /^(\d+)(?:\.(\d+))?/.exec(service.runtimeVersion ?? '')
+      const [major, minor] = v ? [Number(v[1]), v[2] === undefined ? 99 : Number(v[2])] : [99, 99]
+      if (major < 18 || major === 19 || (major === 18 && minor < 19) || (major === 20 && minor < 6)) {
+        plan.manual.push({ title: 'Use Node.js 18.19 or later', lines: [`This app uses Node.js ${service.runtimeVersion}.`,
+          'The UKNOWS agent needs Node.js 18.19 or later on version 18, or 20.6 or later.', 'Update the Node.js version of the app. Then run npx @uknows/setup again.'] })
+        return plan
+      }
+      let pkg = {}
+      try { pkg = JSON.parse(read(ctx.ws, service.dir === '.' ? 'package.json' : `${service.dir}/package.json`) ?? '{}') } catch { /* not JSON: CommonJS */ }
+      const entry = entryOf(dockerStart(info)?.argv, typeof pkg.scripts?.start === 'string' ? pkg.scripts.start : null)
+      esm = /\.m[jt]s$/.test(entry ?? '') || (pkg.type === 'module' && !/\.c[jt]s$/.test(entry ?? ''))
+    }
+    if (lang === 'dotnet') {
+      const csproj = webProject(service, ctx.ws)
+      const framework = csproj ? targetFramework(read(ctx.ws, csproj) ?? '', []) : null
+      const major = /^net(?:coreapp)?(\d+)\./.exec(framework ?? '')?.[1] ?? (/^net\d+$/.test(framework ?? '') ? '4' : null)
+      if (major !== null && Number(major) < 8) {
+        plan.manual.push({ title: 'Use .NET 8 or later', lines: [`${csproj} targets ${framework}.`, 'The UKNOWS agent needs .NET 8 or later.',
+          'Change the target framework to net8.0 or later. Then run npx @uknows/setup again.'] })
+        return plan
+      }
+    }
+
+    const line = copyLine(registry, lang, channelName)
+    const has = (l) => l.trim().startsWith(`COPY --from=${registry}/agent-${lang}:`)
+    let after = text.split('\n').some(has) ? text : insertBeforeStart(text, [line])
+    const settings = startSettings(lang, { esm, musl })
+    if (settings.option) {
+      const [name, option] = settings.option
+      after = addOption(after, name, option)
+      if (info.env.has(name) || info.inherited.has(name)) plan.notes.push(`${service.dockerfile} already sets ${name}. A new ENV line before the start keeps that value and adds the agent.`)
+    } else {
+      const hooks = info.env.get('DOTNET_STARTUP_HOOKS') ?? info.inherited.get('DOTNET_STARTUP_HOOKS')
+      const pairs = settings.env.map(([n, v]) => (n === 'DOTNET_STARTUP_HOOKS' && hooks?.value && !hooks.value.includes(v) ? [n, `${v}:${hooks.value}`] : [n, v]))
+      after = setEnv(after, pairs)
+      // The docs settings for .NET add a log folder that the app can write.
+      for (const l of STACKS.find((s) => s.id === 'dotnet').extraSettings?.lines ?? []) plan.extraSettings.push({ name: l.slice(0, l.indexOf('=')), value: l.slice(l.indexOf('=') + 1) })
+    }
+    if (lang === 'node') {
+      for (const l of STACKS.find((s) => s.id === 'node').extraSettings?.lines ?? []) plan.extraSettings.push({ name: l.slice(0, l.indexOf('=')), value: l.slice(l.indexOf('=') + 1) })
+    }
+    if (after === text) return plan
+    plan.edits.push({ file: service.dockerfile, before: text, after, why: 'Add the UKNOWS agent from the agent image, and start it.' })
+    plan.summary.push(`Copy the UKNOWS agent into the image at each build, from ${image(registry, lang, channelName)} (the ${channelName} channel).`,
+      `Start the agent with the app (${settings.option ? settings.option[0] : `the .NET profiler settings${musl ? ' for musl (Alpine)' : ''}`} in ${service.dockerfile}).`)
+    plan.notes.push(`Each build copies the current agent of the ${channelName} channel. A new agent reaches the app at its next build and deploy, with no change to this repo.`,
+      'If an agent file is missing or broken, the app starts without the agent and prints 1 line that starts with "UKNOWS agent:". UKNOWS_AGENT=off turns the agent off.')
+    if (lang === 'node' && esm) plan.notes.push('This app runs as ES modules, so node loads the agent with --import.')
+    return plan
+  },
+}

package/lib/stacks/dotnet.mjs

@@ -0,0 +1,472 @@
+// .NET: add the OpenTelemetry.AutoInstrumentation package to the web project and start the app with instrument.sh.
+// The csproj is edited as text (no dotnet add), so its BOM, line endings and layout stay. Directory.*.props files
+// above the --path folder count too: with central package versions there, the step is manual.
+//
+// StackExchange.Redis in [2.6.122, 4.0.0) needs 1 more package, or the build check of the package fails. It counts
+// when the lock or obj/project.assets.json resolves it (also through NRedisStack), else when the project references it
+// or a package that is known to bring it (PINS.dotnet.redis.carriers).
+//
+// Locked restore (packages.lock.json, RestorePackagesWithLockFile, RestoreLockedMode, or --locked-mode in the
+// Dockerfile or a workflow): the tool runs dotnet restore <csproj> --force-evaluate, as a lock command, with the -r of
+// the runtime that the lock has packages for (none when the lock has none). With no lock yet, the -r of the Dockerfile
+// restore. The engine records the lock it rewrites as a text change, runs it after the edits and
+// rolls every file back when it fails, so the start changes only with a lock that has the packages. After the
+// restore, obj/project.assets.json shows the packages the build check sees: a Redis that the plan did not know about
+// rolls the run back, and the next run plans it. A Dockerfile that restores with --network=none cannot get new
+// packages: the run changes nothing and prints the steps.
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join as joinPath, posix, relative, resolve } from 'node:path'
+import { PINS, RESOLVE, STACKS } from '../contract.mjs'
+import { Doc } from '../doc.mjs'
+import { dockerStart, finalImage, parseDockerfile, prefixStart } from '../dockerfile.mjs'
+import { nugetAssets } from '../locks.mjs'
+import { compareVersion } from '../versions.mjs'
+import { upFrom } from '../workspace.mjs'
+import { startOverrides } from './k8s.mjs'
+
+const DOCS = STACKS.find((s) => s.id === 'dotnet')
+const { package: PACKAGE, version: VERSION, minNet, redis: REDIS } = PINS.dotnet
+const USE_NET8 = DOCS.notes.find((n) => /\.NET 8/.test(n))
+const ENTRYPOINT = DOCS.dockerfile.split('\n').find((l) => l.startsWith('ENTRYPOINT'))
+const SCRIPT_NOTE = DOCS.notes.find((n) => /instrument\.sh/.test(n))
+const at = (dir, name) => (dir === '.' ? name : `${dir}/${name}`)
+const dirOf = (path) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '.')
+const base = (path) => path.split('/').pop()
+const above = (path) => path.startsWith('../')
+const read = (view, path) => { try { return view.read(path) } catch { return null } }
+const tag = (text, name) => new RegExp(`<${name}>\\s*([^<]*?)\\s*</${name}>`, 'i').exec(text)?.[1] ?? null
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+const inRedisRange = (v) => compareVersion(v, REDIS.range[0]) >= 0 && compareVersion(v, REDIS.range[1]) < 0
+const LOCK = 'packages.lock.json'
+
+/** @type {import('../types.mjs').Applier} */
+export const dotnet = {
+  id: 'dotnet',
+  plan(service, ctx) {
+    const { ws } = ctx
+    const plan = { summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [] }
+    const csproj = webProject(service, ws)
+    if (!csproj) {
+      plan.manual.push({ title: 'Add OpenTelemetry to your .NET app', lines: ['This tool did not find the .csproj file of the web app.',
+        `Run dotnet add package ${PACKAGE} in the folder of the web app.`, 'Then start the app with instrument.sh.', SCRIPT_NOTE] })
+      return plan
+    }
+    const text = ws.read(csproj)
+    const view = ctx.repo ?? ws
+    const folders = upFrom(dirOf(csproj), view.top ?? '.')
+    const props = (name) => folders.map((dir) => at(dir, name)).map((file) => ({ file, text: read(view, file) })).filter((p) => p.text !== null)
+    const framework = targetFramework(text, props('Directory.Build.props'))
+    const major = /^net(?:coreapp)?(\d+)\./.exec(framework ?? '')?.[1] ?? (/^net\d+$/.test(framework ?? '') ? '4' : null)
+    if (major !== null && Number(major) < minNet) {
+      plan.manual.push({ title: USE_NET8.replace(/\.$/, ''), lines: [`${csproj} targets ${framework}.`,
+        `${PACKAGE} ${VERSION} needs .NET ${minNet} or later.`, `Change the target framework to net${minNet}.0 or later. Then run npx @uknows/setup again.`] })
+      return plan
+    }
+    if (major === null) plan.notes.push(`This tool could not read the target framework of ${csproj}. ${USE_NET8}`)
+    const dll = `${tag(text, 'AssemblyName') ?? csproj.split('/').pop().replace(/\.csproj$/, '')}.dll`
+    const redis = redisNeed(text, ctx.installed ?? ctx.existing?.installed ?? null, props('Directory.Packages.props')[0]?.text ?? null)
+    const wanted = [[PACKAGE, VERSION], ...(redis.add ? [[REDIS.package, REDIS.version]] : [])]
+    if (redis.note) plan.notes.push(redis.note)
+
+    // A restore that cannot run, or cannot get the packages, changes nothing: the steps are printed instead.
+    const guided = (block) => {
+      const code = [...wanted.map(([name, v]) => `dotnet add package ${name} --version ${v}`)]
+      plan.manual.push({ ...block, snippets: [{ caption: 'Terminal', language: 'bash', code: code.join('\n') },
+        { caption: service.dockerfile ? 'Dockerfile' : 'Start', language: service.dockerfile ? 'dockerfile' : 'bash',
+          code: service.dockerfile ? ENTRYPOINT.replace('OrdersApi.dll', dll) : DOCS.start.replace('OrdersApi.dll', dll) }] })
+      plan.stop = true
+      return plan
+    }
+    const docker = service.dockerfile ? read(ws, service.dockerfile) : null
+    const offline = docker === null ? null : offlineRestore(docker)
+    // New packages need a restore: they are not in the csproj yet, or not in its packages.lock.json yet.
+    const lockText = read(view, at(dirOf(csproj), LOCK))
+    const stale = wanted.some(([name]) => !hasReference(text, name) || (lockText !== null && !new RegExp(`"${name.replace(/\./g, '\\.')}"\\s*:`, 'i').test(lockText)))
+    if (offline && stale) {
+      return guided({ title: RESOLVE.dotnet.offline.title, lines: RESOLVE.dotnet.offline.lines.map((l) => fill(l, { file: service.dockerfile, line: offline.line, csproj })) })
+    }
+    const restore = stale ? restoreStep(service, ctx, csproj, major) : null
+    if (restore?.block) return guided(restore.block)
+
+    const added = addPackages(csproj, text, props, plan, wanted, redis)
+    if (added !== true) {
+      plan.stop = added === 'outside'
+      return plan
+    }
+    if (restore?.command) {
+      // After the restore, a Redis that the plan did not know about must stop the run (the build check would fail).
+      if (!redis.add && !hasReference(text, REDIS.package)) {
+        restore.command.verify = { assets: at(dirOf(csproj), 'obj/project.assets.json'), library: REDIS.library, range: REDIS.range,
+          package: REDIS.package, version: REDIS.version }
+      }
+      plan.commands.push(...restore.before, restore.command)
+      plan.notes.push(...restore.notes)
+      if (restore.note) plan.notes.push(restore.note)
+    }
+    // The docs settings for .NET add a log folder that the app can write. Without it, the app can stop at start.
+    for (const line of DOCS.extraSettings?.lines ?? []) {
+      const at = line.indexOf('=')
+      plan.extraSettings.push({ name: line.slice(0, at), value: line.slice(at + 1) })
+    }
+    addStart(ws, service, dll, plan, { csproj, text })
+    return plan
+  },
+}
+
+/** The web project of the service: the csproj with Microsoft.NET.Sdk.Web, else the first one. */
+export function webProject(service, ws) {
+  const projects = [...service.manifests, ...ws.list(service.dir).map((n) => at(service.dir, n))].filter((p) => p.endsWith('.csproj'))
+  return projects.find((p) => /Microsoft\.NET\.Sdk\.Web/.test(read(ws, p) ?? '')) ?? projects[0] ?? null
+}
+
+const hasReference = (text, name) => new RegExp(`<PackageReference\\s[^>]*?Include\\s*=\\s*"${name.replace(/\./g, '\\.')}"`, 'i').test(text)
+
+/**
+ * Does the build check need the Redis package? From the lock or assets file when there is one (the resolved
+ * StackExchange.Redis, also through another package), else from the project: a StackExchange.Redis reference in the
+ * range, or a package that brings it in.
+ * @returns {{add: boolean, version: string|null, via: string[], note: string|null}}
+ */
+function redisNeed(text, installed, props) {
+  const no = { add: false, version: null, via: [], note: null }
+  if (hasReference(text, REDIS.package)) return no
+  const resolved = installed?.packages.get(REDIS.library.toLowerCase())
+  if (resolved?.version) {
+    const via = resolved.direct ? [] : resolved.via.map((k) => installed.packages.get(k)?.name ?? k)
+    return { add: inRedisRange(resolved.version), version: resolved.version, via, note: null }
+  }
+  if (installed?.files.length) return no
+  const refs = [...text.matchAll(/<PackageReference\s[^>]*?Include\s*=\s*"([^"]+)"[^>]*?(?:\/>|>([\s\S]*?)<\/PackageReference>)/gi)]
+  const redis = refs.find((m) => m[1].toLowerCase() === REDIS.library.toLowerCase())
+  if (redis) {
+    const version = /Version\s*=\s*"([^"]+)"/i.exec(redis[0])?.[1] ?? tag(redis[2] ?? '', 'Version')
+      ?? new RegExp(`<PackageVersion\\s+Include="${REDIS.library}"\\s+Version="([^"]+)"`, 'i').exec(props ?? '')?.[1]
+    if (!/^\d+\.\d+\.\d+/.test(version ?? '')) return { ...no, note: `This app uses ${REDIS.library}. If the build fails, add ${REDIS.package} ${REDIS.version}.` }
+    return { add: inRedisRange(version), version, via: [], note: null }
+  }
+  const carrier = refs.find((m) => REDIS.carriers.some((c) => c.toLowerCase() === m[1].toLowerCase()))
+  return carrier ? { add: true, version: null, via: [carrier[1]], note: null } : no
+}
+
+/**
+ * Locked restore is on: a packages.lock.json next to the project, RestorePackagesWithLockFile or RestoreLockedMode in
+ * the project or a Directory.Build.props above it, or --locked-mode in the Dockerfile or a workflow.
+ */
+export function lockedMode(service, view, csproj = webProject(service, view)) {
+  if (!csproj) return false
+  if (read(view, at(dirOf(csproj), LOCK)) !== null) return true
+  const on = (t) => /<(RestorePackagesWithLockFile|RestoreLockedMode)>\s*true\s*</i.test(t ?? '')
+  if (on(read(view, csproj)) || upFrom(dirOf(csproj), view.top ?? '.').some((d) => on(read(view, at(d, 'Directory.Build.props'))))) return true
+  const docker = service.dockerfile ? read(view, service.dockerfile) : null
+  if (/\bdotnet\s+restore\b[^\n]*--locked-mode\b/.test(docker ?? '')) return true
+  let files = []
+  try { files = view.files() } catch { /* unreadable */ }
+  return files.filter((f) => /^\.github\/workflows\/[^/]+\.ya?ml$|(?:^|\/)azure-pipelines[^/]*\.ya?ml$/.test(f))
+    .some((f) => /\bdotnet\s+restore\b[^\n]*--locked-mode\b/.test(read(view, f) ?? ''))
+}
+
+/**
+ * The restore that refreshes packages.lock.json after the csproj edit, or the required step when it cannot run:
+ * no .NET SDK of the target major version or later on this computer (ctx.tools.dotnet), or the Dockerfile restores
+ * for more than 1 runtime or for one this tool cannot read ($TARGETARCH). null when restore is not locked.
+ * @returns {{command: import('../types.mjs').Command}|{block: import('../types.mjs').Block}|null}
+ */
+export function restoreStep(service, ctx, csproj, major) {
+  const view = ctx.repo ?? ctx.ws
+  if (!lockedMode(service, view, csproj)) return null
+  const lock = at(dirOf(csproj), LOCK)
+  const sdk = ctx.tools && Object.prototype.hasOwnProperty.call(ctx.tools, 'dotnet') ? ctx.tools.dotnet : undefined
+  const need = major !== null ? Number(major) : null
+  if (sdk === null || (sdk && need !== null && Number(/^(\d+)/.exec(sdk)?.[1] ?? 0) < need)) {
+    return { block: { title: fill(RESOLVE.dotnet.sdk.title, { need: need ?? minNet }),
+      lines: RESOLVE.dotnet.sdk.lines.map((l) => fill(l, { lock, need: need ?? minNet, have: sdk ?? 'none' })) } }
+  }
+  // NuGet checks a locked restore against the runtimes in the lock. So a lock decides the -r, never a publish line:
+  // a runtime that the lock does not have would break every other locked restore of the project (NU1004).
+  const fromLock = lockRuntimes(read(view, lock))
+  const docker = service.dockerfile ? read(view, service.dockerfile) : null
+  const rid = fromLock ?? (docker === null ? { rids: [] } : runtimes(docker))
+  if (rid.unknown || rid.rids.length > 1) {
+    const where = rid.unknown ?? rid.at
+    const lines = RESOLVE.dotnet.runtimes.lines.map((l) => fill(l, { file: service.dockerfile, line: where?.line, value: rid.unknown?.value ?? rid.rids.join(' and ') }))
+    if (fromLock) lines[0] = fill(RESOLVE.dotnet.runtimes.lock, { lock, value: rid.rids.join(' and ') })
+    return { block: { title: RESOLVE.dotnet.runtimes.title, lines } }
+  }
+  const args = ['restore', base(csproj), '--force-evaluate', ...(rid.rids.length ? ['-r', rid.rids[0]] : [])]
+  // A restore rewrites the lock of every project in the graph: the lockfiles of the referenced projects count too.
+  const members = (ctx.existing?.members ?? []).map((m) => at(m.dir, LOCK)).filter((f) => f !== lock && read(view, f) !== null)
+  // Projects that reference this one (a test project) and have their own lock list its packages too, so a locked
+  // restore of the solution fails (NU1004) unless their locks are refreshed as well. Each with the runtime of its own
+  // lock. They run first: a restore of such a project also rewrites the lock of this one, and this restore, last,
+  // writes it with its own runtime again.
+  const before = [], notes = []
+  for (const dependent of referencingProjects(ctx, csproj)) {
+    const values = { lock: dependent.lock, project: dependent.csproj, csproj }
+    if (dependent.csproj.startsWith('../')) {
+      return { block: { title: RESOLVE.dotnet.dependentOutside.title, lines: RESOLVE.dotnet.dependentOutside.lines.map((l) => fill(l, values)) } }
+    }
+    const theirs = lockRuntimes(read(view, dependent.lock)) ?? { rids: [] }
+    if (theirs.rids.length > 1) {
+      return { block: { title: RESOLVE.dotnet.runtimes.title, lines: [fill(RESOLVE.dotnet.runtimes.lock, { lock: dependent.lock, value: theirs.rids.join(' and ') }),
+        RESOLVE.dotnet.runtimes.lines[1]] } }
+    }
+    const depArgs = ['restore', base(dependent.csproj), '--force-evaluate', ...(theirs.rids.length ? ['-r', theirs.rids[0]] : [])]
+    const command = ['dotnet', ...depArgs].join(' ')
+    before.push({ cwd: dirOf(dependent.csproj), cmd: 'dotnet', args: depArgs, touches: [...new Set([dependent.lock, lock, ...members, ...dependent.locks])],
+      added: [], kind: 'lock', undo: null, keep: [], why: fill(RESOLVE.dotnet.dependentUpdate, { ...values, command }) })
+    notes.push(fill(RESOLVE.dotnet.dependent, { ...values, command }))
+  }
+  // The restore leaves obj/ folders. Without a .dockerignore that keeps them out, a local docker build copies them in.
+  const ignored = service.dockerfile && [dirOf(service.dockerfile), '.'].some((d) => /^\s*(?:\*\*\/)?obj\/?\s*$/m.test(read(view, at(d, '.dockerignore')) ?? ''))
+  return { before, notes, command: { cwd: dirOf(csproj), cmd: 'dotnet', args, touches: [lock, ...members], added: [], kind: 'lock', undo: null, keep: [],
+    why: fill(RESOLVE.update, { lock, command: ['dotnet', ...args].join(' ') }) }, note: service.dockerfile && !ignored ? RESOLVE.dotnet.dockerignore : null }
+}
+
+const WALK_SKIP = new Set(['node_modules', 'bin', 'obj', 'packages', 'vendor'])
+const WALK_LIMIT = 20000
+
+/**
+ * The projects of the git repo that reference csproj, directly or through other projects, and have a
+ * packages.lock.json: {csproj, lock, locks}, as paths from the root of this run ('../' for a project above a --path
+ * folder). locks: the lockfiles of the projects that each one references, which its restore rewrites too. Test
+ * folders count here, unlike for the services. Reads the files on disk only.
+ */
+export function referencingProjects(ctx, csproj) {
+  const root = ctx.ws?.root
+  if (!root) return []
+  const top = resolve(root, ctx.repo?.top ?? '.')
+  const rel = relative(top, root).split(/[\\/]/).filter(Boolean).join('/')
+  const toTop = (p) => posix.normalize(rel ? `${rel}/${p}` : p)
+  const toRoot = (p) => (rel ? posix.relative(rel, p) : p) || '.'
+  const projects = []
+  let seen = 0
+  const walk = (dir) => {
+    let entries = []
+    try { entries = readdirSync(joinPath(top, ...dir.split('/').filter(Boolean)), { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      if (++seen > WALK_LIMIT) return
+      const path = dir ? `${dir}/${entry.name}` : entry.name
+      if (entry.isDirectory()) { if (!entry.name.startsWith('.') && !WALK_SKIP.has(entry.name)) walk(path) }
+      else if (entry.isFile() && entry.name.endsWith('.csproj')) projects.push(path)
+    }
+  }
+  walk('')
+  const text = (p) => { try { return readFileSync(joinPath(top, ...p.split('/')), 'utf8') } catch { return '' } }
+  const refs = new Map(projects.map((p) => [p, [...text(p).matchAll(/<ProjectReference\s[^>]*?Include\s*=\s*"([^"]+)"/gi)]
+    .map((m) => posix.normalize(posix.join(posix.dirname(p), m[1].replace(/\\/g, '/'))))]))
+  const closure = (start) => {
+    const out = new Set(), queue = [...(refs.get(start) ?? [])]
+    while (queue.length) { const p = queue.shift(); if (out.has(p)) continue; out.add(p); queue.push(...(refs.get(p) ?? [])) }
+    return out
+  }
+  const app = toTop(csproj)
+  const lockOf = (p) => `${posix.dirname(p) === '.' ? '' : `${posix.dirname(p)}/`}${LOCK}`
+  return projects.filter((p) => p !== app && closure(p).has(app) && existsSync(joinPath(top, ...lockOf(p).split('/'))))
+    .map((p) => ({ csproj: toRoot(p), lock: toRoot(lockOf(p)),
+      locks: [...closure(p)].filter((q) => existsSync(joinPath(top, ...lockOf(q).split('/')))).map((q) => toRoot(lockOf(q))) }))
+}
+
+/**
+ * The runtime identifiers that a packages.lock.json has packages for: its targets named <framework>/<rid>.
+ * null when there is no lock, or it is not JSON with a dependencies object.
+ * @returns {{rids: string[]}|null}
+ */
+export function lockRuntimes(text) {
+  if (text === null) return null
+  let json
+  try { json = JSON.parse(text.replace(/^\uFEFF/, '')) } catch { return null }
+  if (!json?.dependencies || typeof json.dependencies !== 'object') return null
+  const targets = Object.keys(json.dependencies)
+  return { rids: [...new Set(targets.filter((t) => t.includes('/')).map((t) => t.slice(t.indexOf('/') + 1)))].sort() }
+}
+
+/**
+ * The runtime identifiers of the restore in the Dockerfile (when there is no lock yet): its dotnet restore lines, else the dotnet publish or
+ * build lines that restore on their own. -r, --runtime, and --os with --arch (or -a) count. A $ value is unknown.
+ * @returns {{rids: string[], at?: {line: number}, unknown?: {line: number, value: string}}}
+ */
+export function runtimes(docker) {
+  const runs = parseDockerfile(docker).instructions.filter((x) => x.keyword === 'RUN')
+  const parts = runs.flatMap((x) => (x.argv ? x.argv.join(' ') : x.args).split(/&&|\|\||[;\n]/).map((part) => ({ part, line: x.start + 1 })))
+  const restores = parts.filter((p) => /\bdotnet\s+restore\b/.test(p.part))
+  const lines = restores.length ? restores : parts.filter((p) => /\bdotnet\s+(?:publish|build)\b/.test(p.part) && !/--no-restore\b/.test(p.part))
+  const rids = new Set()
+  let first = null
+  for (const { part, line } of lines) {
+    const words = part.trim().split(/\s+/)
+    const value = (names) => {
+      for (let k = 0; k < words.length; k++) {
+        const m = new RegExp(`^(?:${names})(?:=(.+))?$`).exec(words[k])
+        if (m) return m[1] ?? words[k + 1] ?? ''
+      }
+      return null
+    }
+    const r = value('-r|--runtime'), os = value('--os'), arch = value('-a|--arch')
+    const raw = [r, os, arch].find((v) => v !== null && (v.includes('$') || !/^[\w.-]+$/.test(v)))
+    if (raw !== undefined) return { rids: [...rids], unknown: { line, value: raw } }
+    const found = r ?? (os || arch ? `${os ?? 'linux'}-${arch === 'amd64' ? 'x64' : arch ?? 'x64'}` : null)
+    if (found === null) continue
+    rids.add(found)
+    first ??= { line }
+  }
+  return { rids: [...rids], at: first ?? undefined }
+}
+
+/**
+ * The runtime that the Dockerfile publishes for: -r (or --runtime) of its dotnet publish line, else of its dotnet build
+ * line, else the 1 RuntimeIdentifier of the project. null with none: then the publish holds the native files of every
+ * platform. {rid, where}.
+ */
+export function publishRuntime(docker, csprojText = null, csproj = null) {
+  const runs = parseDockerfile(docker).instructions.filter((x) => x.keyword === 'RUN')
+  const parts = runs.flatMap((x) => (x.argv ? x.argv.join(' ') : x.args).split(/&&|\|\||[;\n]/).map((part) => ({ part, line: x.start + 1 })))
+  for (const verb of ['publish', 'build']) {
+    for (const { part, line } of parts.filter((p) => new RegExp(`\\bdotnet\\s+${verb}\\b`).test(p.part))) {
+      const m = /(?:^|\s)(?:-r|--runtime)(?:=|\s+)([\w.-]+)(?=\s|$)/.exec(part)
+      if (m) return { rid: m[1], where: `line ${line}` }
+    }
+  }
+  const own = csprojText ? tag(csprojText, 'RuntimeIdentifier') : null
+  return own && /^[\w.-]+$/.test(own) ? { rid: own, where: csproj, project: true } : null
+}
+
+/**
+ * Advice when the publish names a Linux runtime for another C library than the final image (glibc on Alpine, or musl
+ * on a glibc image): the native profiler of OpenTelemetry does not load there. No advice without a runtime (proven on
+ * glibc and Alpine images: instrument.sh then picks runtimes/<os>-<arch>/native), and none for a runtime that fits.
+ */
+function libcAdvice(service, docker, info, { csproj = null, text = null } = {}) {
+  const found = publishRuntime(docker, text, csproj)
+  if (!found || !/^linux-/.test(found.rid)) return null
+  // The image of the final stage through the stage names: FROM base AS final runs on the image of base.
+  const image = finalImage(info)
+  const alpine = /alpine/i.test(image ?? '')
+  const musl = /^linux-musl-/.test(found.rid)
+  if (alpine === musl) return null
+  const values = { where: found.project ? found.where : `${service.dockerfile} ${found.where}`, rid: found.rid, libc: musl ? 'musl (Alpine)' : 'glibc',
+    image, imageLibc: alpine ? 'musl (Alpine)' : 'glibc', want: musl ? found.rid.replace(/^linux-musl-/, 'linux-') : found.rid.replace(/^linux-/, 'linux-musl-') }
+  const L = RESOLVE.dotnet.libc
+  return { title: L.title, required: false, lines: L.lines.map((l) => fill(l, values)) }
+}
+
+/** The RUN line that restores with --network=none: dotnet restore, or a publish or build that restores on its own. */
+export function offlineRestore(docker) {
+  for (const x of parseDockerfile(docker).instructions.filter((i) => i.keyword === 'RUN')) {
+    const flags = /^((?:--[\w-]+(?:=\S+)?\s+)*)/.exec(x.args)[1]
+    if (!/--network=none\b/.test(flags)) continue
+    const command = x.args.slice(flags.length)
+    if (/\bdotnet\s+restore\b/.test(command) || (/\bdotnet\s+(?:publish|build)\b/.test(command) && !/--no-restore\b/.test(command))) return { line: x.start + 1 }
+  }
+  return null
+}
+
+/**
+ * After the restore: obj/project.assets.json shows a StackExchange.Redis in the range that the plan did not add the
+ * package for. Returns the block to print (the engine rolls back), or null. No assets file: nothing to check.
+ * @param {{assets: string, library: string, range: string[], package: string, version: string}} verify
+ * @param {(file: string) => string|null} readText
+ */
+export function verifyRestore(verify, readText) {
+  const text = readText(verify.assets)
+  const set = text === null ? null : nugetAssets(verify.assets, text)
+  const item = set?.packages.get(verify.library.toLowerCase())
+  if (!item?.version || compareVersion(item.version, verify.range[0]) < 0 || compareVersion(item.version, verify.range[1]) >= 0) return null
+  const via = item.direct ? [verify.library] : item.via.map((k) => set.packages.get(k)?.name ?? k)
+  const values = { assets: verify.assets, library: verify.library, version: item.version, via: via.join(', '), package: verify.package, need: verify.version }
+  return { title: fill(RESOLVE.dotnet.assets.title, values), lines: RESOLVE.dotnet.assets.lines.map((l) => fill(l, values)) }
+}
+
+export function targetFramework(text, buildProps) {
+  for (const source of [text, ...buildProps.map((p) => p.text)]) {
+    const found = source && (tag(source, 'TargetFramework') ?? tag(source, 'TargetFrameworks')?.split(';')[0])
+    if (found) return found.includes('$(') ? null : found
+  }
+  return null
+}
+
+/**
+ * Add the package references. Returns true when they are there after this run. Else the start must not change:
+ * 'outside' when the versions live in a file above the --path folder (run from the repo root), else false.
+ */
+function addPackages(csproj, text, findProps, plan, wanted, redis) {
+  const { file: propsFile = null, text: props = null } = findProps('Directory.Packages.props')[0] ?? {}
+  const central = [text, props, ...findProps('Directory.Build.props').map((p) => p.text)]
+    .some((t) => /<ManagePackageVersionsCentrally>\s*true\s*</i.test(t ?? ''))
+  const add = wanted.filter(([name]) => !hasReference(text, name))
+  if (!add.length) return true
+  const reference = ([name, version]) => `<PackageReference Include="${name}"${central ? '' : ` Version="${version}"`} />`
+  const version = ([name, v]) => `<PackageVersion Include="${name}" Version="${v}" />`
+  if (central && (!propsFile || above(propsFile))) {
+    plan.manual.push({ title: `Add ${PACKAGE} to ${csproj}`, lines: [
+      propsFile ? `This repo sets package versions in ${propsFile}, outside the folder this tool works in, so this tool cannot change it.`
+        : 'This project sets package versions centrally, but this tool did not find Directory.Packages.props.',
+      'Run npx @uknows/setup in the repo root without --path, and pick this service. Or add these lines by hand. Then run it again for the start command.'],
+    snippets: [{ caption: propsFile ?? 'Directory.Packages.props', language: 'xml', code: add.map(version).join('\n') },
+      { caption: csproj, language: 'xml', code: add.map(reference).join('\n') }] })
+    return propsFile ? 'outside' : false
+  }
+  const after = addItems(text, add.map(reference), /<PackageReference\s/)
+  if (after === null) {
+    plan.manual.push({ title: `Add ${PACKAGE} to ${csproj}`, lines: [`Run dotnet add package ${PACKAGE} in ${dirOf(csproj)}.`] })
+    return false
+  }
+  plan.edits.push({ file: csproj, before: text, after, why: `Add the ${PACKAGE} package.` })
+  if (central) {
+    const versions = add.filter(([name]) => !new RegExp(`<PackageVersion\\s+Include="${name}"`, 'i').test(props))
+    if (versions.length) {
+      plan.edits.push({ file: propsFile, before: props, why: `Set the version of the ${PACKAGE} package.`,
+        after: addItems(props, versions.map(version), /<PackageVersion\s/) ?? props })
+    }
+  }
+  const because = redis.via.length ? `${REDIS.library}${redis.version ? ` ${redis.version}` : ''} through ${redis.via.join(', ')}` : REDIS.library
+  add.forEach(([name, v]) => plan.summary.push(`Add ${name} ${v} to ${csproj}${name === PACKAGE ? '' : `, because the app uses ${because}`}.`))
+  return true
+}
+
+/** Add item lines after the last single-line item like them (not in a conditional ItemGroup), else in a new ItemGroup before </Project>. */
+export function addItems(text, items, like) {
+  const doc = new Doc(text)
+  const lines = doc.lines
+  const lastItem = lines.findLastIndex((l) => like.test(l) && /\/>\s*$/.test(l))
+  const group = lines.slice(0, lastItem + 1).findLast((l) => /<ItemGroup\b/.test(l)) ?? ''
+  if (lastItem >= 0 && !/Condition/.test(group)) {
+    const indent = /^\s*/.exec(lines[lastItem])[0]
+    doc.insert(lastItem + 1, ...items.map((item) => indent + item))
+    return doc.toString()
+  }
+  const end = lines.findLastIndex((l) => /^\s*<\/Project>\s*$/.test(l))
+  if (end < 0) return null
+  const unit = lines.map((l) => /^(\s+)</.exec(l)?.[1]).find(Boolean) ?? '  '
+  const block = [`${unit}<ItemGroup>`, ...items.map((item) => unit + unit + item), `${unit}</ItemGroup>`]
+  if (end > 0 && !lines[end - 1].trim()) doc.insert(end, ...block, '')
+  else doc.insert(end, '', ...block)
+  return doc.toString()
+}
+
+function addStart(ws, service, dll, plan, project = {}) {
+  const entrypoint = ENTRYPOINT.replace('OrdersApi.dll', dll)
+  const manual = (lines) => plan.manual.push({ title: 'Start the app with instrument.sh', lines: [...lines, SCRIPT_NOTE],
+    snippets: [{ caption: service.dockerfile ? 'Dockerfile' : 'Start', language: service.dockerfile ? 'dockerfile' : 'bash',
+      code: service.dockerfile ? entrypoint : DOCS.start.replace('OrdersApi.dll', dll) }] })
+  const text = service.dockerfile && ws.read(service.dockerfile)
+  if (!text) return manual(['This app does not start from a Dockerfile. Start it with the command below.'])
+  const info = parseDockerfile(text)
+  const image = finalImage(info)
+  if (/chiseled|distroless|nanoserver|windowsservercore/i.test(image ?? '')) {
+    return manual([`The final image ${image} has no /bin/sh. instrument.sh needs it.`,
+      'Use a final image with a shell, such as mcr.microsoft.com/dotnet/aspnet. Then start the app like this.'])
+  }
+  const argv = dockerStart(info)?.argv ?? []
+  const target = argv.find((a) => /\.dll$/i.test(a)) ?? (/^\.{0,2}\//.test(argv[0] ?? '') ? argv[0] : null)
+  // instrument.sh sits next to the dll in the publish output.
+  const script = argv[1]?.endsWith('instrument.sh') ? argv[1]
+    : target && (target.includes('/') ? `${dirOf(target)}/instrument.sh` : './instrument.sh')
+  const after = script && prefixStart(text, ['sh', script])
+  if (!after) return manual([`This tool cannot change the start command in ${service.dockerfile}.`, 'Put sh ./instrument.sh in front of the command that starts your app.'])
+  const libc = libcAdvice(service, text, info, project)
+  if (libc) plan.manual.push(libc)
+  plan.manual.push(...startOverrides(service, info.entrypoint ? 'ENTRYPOINT' : 'CMD', `sh ${script}`))
+  if (after === text) return
+  plan.edits.push({ file: service.dockerfile, before: text, after, why: 'Start the app with instrument.sh.' })
+  plan.summary.push(`Start the app with instrument.sh (${info.entrypoint ? 'ENTRYPOINT' : 'CMD'} in ${service.dockerfile}).`)
+}