@uknows/setup 0.1.0 → 0.2.0

package/lib/contract.mjs

@@ -11,7 +11,24 @@
  */
 
 export * from './contract-docs.mjs'
-import { NODE_REGISTER, PING_URL } from './contract-docs.mjs'
+import { GO_RELEASES, NODE_REGISTER, PING_URL } from './contract-docs.mjs'
+
+/** The node options that load a register file: --require, or for ES modules the loader hook and --import. */
+const nodeFlag = (esm, register = NODE_REGISTER) => (esm ? `--experimental-loader=@opentelemetry/instrumentation/hook.mjs --import ${register}`
+  : `--require ${register}`)
+
+/**
+ * Known-good OpenTelemetry sets for Python, newest first. core: opentelemetry-sdk and the OTLP exporter. contrib:
+ * opentelemetry-distro and each opentelemetry-instrumentation-* package. minPython: the lowest Python of that
+ * release. protobuf: [lowest, below] that opentelemetry-proto of that release allows. Checked on PyPI on
+ * 2026-10-18 with tools/check-python-sets.mjs (not shipped). 1.27.0 is the last release for protobuf below 5:
+ * uv pip compile with protobuf<5 picks 1.27.0 and 0.48b0.
+ */
+const PYTHON_SETS = [
+  { core: '1.45.1', contrib: '0.66b1', minPython: [3, 10], protobuf: ['5.0', '8.0'] },
+  { core: '1.41.1', contrib: '0.62b1', minPython: [3, 9], protobuf: ['5.0', '7.0'] },
+  { core: '1.27.0', contrib: '0.48b0', minPython: [3, 8], protobuf: ['3.19', '5.0'] },
+]
 
 export const PINS = {
   node: {
@@ -19,17 +36,39 @@ export const PINS = {
     packages: ['@opentelemetry/api', '@opentelemetry/auto-instrumentations-node'],
     /** ESM apps also need this one as a direct dependency (pnpm cannot resolve hook.mjs otherwise). */
     esmPackage: '@opentelemetry/instrumentation',
-    requireFlag: `--require ${NODE_REGISTER}`,
-    esmFlag: `--experimental-loader=@opentelemetry/instrumentation/hook.mjs --import ${NODE_REGISTER}`,
+    /** The upstream register line: for a start that this tool cannot give the start file, and in printed steps. */
+    requireFlag: nodeFlag(false),
+    esmFlag: nodeFlag(true),
+    /**
+     * The same options with the start file of this tool (install.ts NODE_REGISTER_FILE): its absolute path in an
+     * image, or ./uknows-otel.cjs in a start script. The ESM loader hook stays: it gives each request its route.
+     */
+    flag: nodeFlag,
+    /**
+     * The npm major version that each Node.js release comes with, from https://nodejs.org/dist/index.json on 18 Oct
+     * 2026: [lowest Node.js version, npm major], newest first. The official node images use that npm. npm on this
+     * computer writes package-lock.json, and npm ci in the image reads it, so a newer npm here stops the run.
+     */
+    npm: [[[24, 0], 11], [[20, 7], 10], [[20, 0], 9], [[19, 3], 9], [[19, 0], 8], [[18, 19], 10], [[18, 14], 9], [[18, 0], 8]],
   },
   python: {
-    /** Same 2 packages as the docs install line, pinned like pip freeze would. */
-    distro: 'opentelemetry-distro==0.66b1',
-    exporter: 'opentelemetry-exporter-otlp-proto-http==1.45.1',
+    /** Same 2 packages as the docs install line, pinned like pip freeze would: the newest set. */
+    distro: `opentelemetry-distro==${PYTHON_SETS[0].contrib}`,
+    exporter: `opentelemetry-exporter-otlp-proto-http==${PYTHON_SETS[0].core}`,
     /** Version of each opentelemetry-instrumentation-* package that opentelemetry-bootstrap prints. */
-    contrib: '0.66b1',
+    contrib: PYTHON_SETS[0].contrib,
     /** opentelemetry-distro 0.66b1 needs Python 3.10 or later. */
-    minPython: [3, 10],
+    minPython: PYTHON_SETS[0].minPython,
+    /**
+     * requirements.txt and other files with no lock: exact pins from the first set that fits the direct limits of
+     * the file (protobuf, opentelemetry-*) and the Python of the image. The plan says why it is not the newest.
+     */
+    sets: PYTHON_SETS,
+    /**
+     * uv and Poetry projects: floors, not pins, so their resolver picks the newest release that the app allows.
+     * The floors are the oldest set and name a pre-release on purpose, so uv and Poetry allow the b releases.
+     */
+    floors: { core: PYTHON_SETS.at(-1).core, contrib: PYTHON_SETS.at(-1).contrib },
   },
   dotnet: {
     package: 'OpenTelemetry.AutoInstrumentation',
@@ -37,7 +76,30 @@ export const PINS = {
     /** 1.17.0 targets net8.0 and net462 only. */
     minNet: 8,
     /** The build fails when an app uses StackExchange.Redis [2.6.122, 4.0.0) without this package. */
-    redis: { library: 'StackExchange.Redis', package: 'OpenTelemetry.Instrumentation.StackExchangeRedis', version: '1.19.0-beta.1' },
+    redis: { library: 'StackExchange.Redis', package: 'OpenTelemetry.Instrumentation.StackExchangeRedis', version: '1.19.0-beta.1',
+      /** The range of StackExchange.Redis that the build check of OpenTelemetry.AutoInstrumentation 1.17.0 asks for: [min, below). */
+      range: ['2.6.122', '4.0.0'],
+      /**
+       * Packages that bring StackExchange.Redis in. With no packages.lock.json or obj/project.assets.json, 1 of them
+       * in the project counts as StackExchange.Redis. With a lock or assets file, the resolved version decides.
+       */
+      carriers: ['NRedisStack', 'Microsoft.Extensions.Caching.StackExchangeRedis', 'Microsoft.AspNetCore.SignalR.StackExchangeRedis',
+        'Microsoft.AspNetCore.DataProtection.StackExchangeRedis', 'Hangfire.Redis.StackExchange'] },
+    /**
+     * For apps with Azure Monitor and no lock or assets file: the OTLP exporter at the OpenTelemetry version that
+     * OpenTelemetry.AutoInstrumentation 1.17.0 uses. With a lock, the exporter takes the resolved OpenTelemetry version.
+     */
+    otlpExporter: { package: 'OpenTelemetry.Exporter.OpenTelemetryProtocol', version: '1.19.1' },
+  },
+  /**
+   * The OpenTelemetry SDK package of each language, and the lowest version of it that the packages of this tool
+   * need. A package that limits the SDK below this version stops the run (the wrapper stop). Checked on 2026-10-18:
+   * OpenTelemetry.AutoInstrumentation.Runtime.Managed 1.17.0 needs OpenTelemetry 1.19.1.
+   */
+  sdk: {
+    python: { package: 'opentelemetry-sdk', need: '1.45.1' },
+    dotnet: { package: 'OpenTelemetry', need: '1.19.1' },
+    node: { package: '@opentelemetry/sdk-trace-base', need: null },
   },
   go: {
     /**
@@ -45,6 +107,8 @@ export const PINS = {
      * builders fail (golang images set GOTOOLCHAIN=local). Checked upstream on 2026-10-12.
      */
     minGo: [1, 26],
+    /** Below minGo, the go get lines name the versions of install.ts GO_RELEASES. Below the oldest row, Go is too old. */
+    oldestGo: GO_RELEASES.at(-1).go.split('.').map(Number),
   },
   php: {
     /** The 6th setting for PHP. The docs PHP Dockerfile adds it with the 5. */
@@ -52,6 +116,17 @@ export const PINS = {
   },
 }
 
+/** The agent channels (--channel), and the form of the registry setting: a host and a path, no scheme and no tag. */
+export const AGENT_CHANNELS = ['stable', 'early']
+/**
+ * The public store of the UKNOWS agent images, a host and a path under a uknows.my name: setup builds
+ * <registry>/agent-<lang>:<channel> from it, for example registry.uknows.my/uknows/agent-node:stable. Anyone can pull
+ * from it without signing in. UKNOWS_AGENT_REGISTRY overrides it. If it were empty, setup would use the agent channel
+ * only when UKNOWS_AGENT_REGISTRY is set, and the publish gate (tools/prepublish.mjs) would stop.
+ */
+export const DEFAULT_AGENT_REGISTRY = 'registry.uknows.my/uknows'
+export const AGENT_REGISTRY = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:\d{1,5})?(\/[a-z0-9]+([._-][a-z0-9]+)*)*$/
+
 export const CLI = {
   /** Records what setup changed so remove can undo it exactly. Never holds secrets. */
   manifest: '.uknows/setup.json',
@@ -59,8 +134,16 @@ export const CLI = {
   endpointEnv: 'UKNOWS_INGEST_ENDPOINT',
   /** Override for the site address (where check asks which workspace a key sends to), for a test environment. */
   siteEnv: 'UKNOWS_SITE_URL',
+  /** Override for the app address (where the user watches an app connect), for a test environment. */
+  appEnv: 'UKNOWS_APP_URL',
+  /** The registry and path of the UKNOWS agent images, for --channel. For example registry.example.com/uknows. */
+  agentRegistryEnv: 'UKNOWS_AGENT_REGISTRY',
   /** The route of the site that says which workspace and environment a key sends to. */
   pingPath: new URL(PING_URL).pathname,
   exit: { ok: 0, error: 1, usage: 2, manual: 3 },
-  next: 'Next: commit, open a PR, deploy as usual.',
+  /**
+   * A run counts as CI when one of these is set and not empty. CI also must not be 0 or false.
+   * --allow-ci lets a bot or an AI agent that opens a pull request apply anyway.
+   */
+  ciEnv: ['CI', 'GITHUB_ACTIONS', 'TF_BUILD', 'GITLAB_CI', 'BUILDKITE', 'CIRCLECI', 'JENKINS_URL', 'TEAMCITY_VERSION', 'BITBUCKET_BUILD_NUMBER', 'CODEBUILD_BUILD_ID'],
 }

package/lib/detect.mjs

@@ -9,6 +9,8 @@ import { Doc, shellWords } from './doc.mjs'
 import { dockerStart, parseDockerfile } from './dockerfile.mjs'
 import { SETTINGS_FILE } from './contract.mjs'
 import { detectHosts } from './hosts.mjs'
+import { pythonProjectName, uvWorkspace } from './members.mjs'
+import { pyName, tomlArray, tomlKeys, tomlString, tomlTable } from './toml.mjs'
 import { createWorkspace, repoView } from './workspace.mjs'
 
 const MAX_BYTES = 1_000_000
@@ -16,8 +18,10 @@ const MAX_BYTES = 1_000_000
 const LANGS = ['python', 'java', 'dotnet', 'go', 'php', 'ruby', 'node']
 const LABEL = { node: 'Node.js', python: 'Python', dotnet: '.NET', java: 'Java', go: 'Go', php: 'PHP', ruby: 'Ruby' }
 const NODE_FW = { express: 'express', fastify: 'fastify', '@nestjs/core': 'nestjs', koa: 'koa', '@hapi/hapi': 'hapi',
-  nitropack: 'nitro', nitro: 'nitro', nuxt: 'nuxt', next: 'next' }
-const PY_FW = ['fastapi', 'django', 'flask', 'starlette', 'falcon', 'tornado']
+  nitropack: 'nitro', nitro: 'nitro', nuxt: 'nuxt', next: 'next', '@azure/functions': 'azure-functions' }
+const PY_FW = ['fastapi', 'django', 'flask', 'starlette', 'falcon', 'tornado', 'azure-functions']
+/** A .NET project of the Azure Functions isolated worker: the worker package or the Functions version of the SDK. */
+const DOTNET_FUNCTIONS = /<PackageReference\s+Include\s*=\s*["']Microsoft\.Azure\.Functions\.Worker["']|<AzureFunctionsVersion>/i
 const PHP_FW = { 'laravel/framework': 'laravel', 'symfony/framework-bundle': 'symfony', 'slim/slim': 'slim' }
 const TEXT_FW = {
   java: [['spring-boot', /spring-boot|org\.springframework\.boot/], ['quarkus', /io\.quarkus/], ['micronaut', /io\.micronaut/]],
@@ -32,6 +36,8 @@ const IMAGE = {
   php: /(?:^|\/)php(?:[:@]|$)/, ruby: /(?:^|\/)ruby(?:[:@]|$)/,
 }
 const DOCKERFILE = /^(?:Dockerfile(?:\.[^/]+)?|[^/]+\.[Dd]ockerfile)$/
+/** Any file that docker build or podman build can take: Dockerfile, Dockerfile.*, *.Dockerfile, Containerfile. Dev variants too. */
+export const isDockerfile = (path) => DOCKERFILE.test(posix.basename(path)) || /^Containerfile(?:\.[^/]+)?$/.test(posix.basename(path))
 /** Files that build or deploy images: workflows, compose files, scripts. A Dockerfile named in them with -f is the one that ships. */
 const DEPLOY_FILE = new RegExp(['^(?:\\.\\./)*\\.github/workflows/[^/]+\\.ya?ml$', '(?:^|/)(?:docker-)?compose[^/]*\\.ya?ml$', '(?:^|/)(?:Makefile|Jenkinsfile)$',
   '(?:^|/)[^/]+\\.(?:sh|ps1)$', '(?:^|/)(?:azure-pipelines|cloudbuild|buildspec|skaffold|\\.gitlab-ci|bitbucket-pipelines)\\.ya?ml$'].join('|'))
@@ -40,10 +46,14 @@ const DOCKERFILE_REF = /(?:^|\s)(?:-f|--file)(?:\s+|=)["']?([^\s"';&|)]+)|^\s*-?
 const STATIC_IMAGE = /(?:^|\/)(?:nginx|nginx-unprivileged|httpd|caddy|lighttpd|openresty)(?:[:@]|$)/
 const FRONTEND_DEP = /^(?:react|react-dom|vue|svelte|@angular\/core|vite|preact|solid-js|react-scripts|parcel|@vue\/cli-service)$/
 const DEV_SERVER = /^(?:vite|react-scripts|ng|vue-cli-service|parcel|webpack|webpack-dev-server|serve|http-server)$/
-const SERVER_FW = new Set(['express', 'fastify', 'nestjs', 'koa', 'hapi', 'nitro', 'nuxt', 'next'])
+const SERVER_FW = new Set(['express', 'fastify', 'nestjs', 'koa', 'hapi', 'nitro', 'nuxt', 'next', 'azure-functions'])
 const RUNS_NODE = /^(?:node|nodejs|npm|npx|yarn|pnpm)$|\.[cm]?js$/
 const DEV_VARIANT = /(?:^|[.-])(?:dev|development|test|testing|local|debug|ci)(?:[.-]|$)/i
 const WORKLOAD = /^kind:\s*['"]?(?:Deployment|StatefulSet|DaemonSet|Pod|Job|CronJob)['"]?\s*(?:#.*)?$/m
+/** Off-the-shelf JVM products that ship as an image, with no manifest in the repo: final image -> framework. */
+const JVM_PRODUCTS = [[/(?:^|\/)keycloak\/keycloak(?:[:@]|$)/, 'keycloak']]
+/** uv sync --package <name> in a RUN line: the image installs that workspace member. */
+const UV_PACKAGE = /\buv\s+sync\b[^&|;\n]*?\s--package(?:\s+|=)["']?([A-Za-z0-9][A-Za-z0-9._-]*)/g
 
 /**
  * Find the services, stacks, start commands and hosts of the repo. Static reading only.
@@ -86,8 +96,27 @@ export function detect(root) {
   // 2. Dockerfiles, then 1 per candidate folder.
   const dockerfiles = files
     .filter((p) => DOCKERFILE.test(posix.basename(p)) && !DEV_VARIANT.test(posix.basename(p).replace(/dockerfile/i, '')))
-    .map((path) => ({ path, info: parseDockerfile(read(path) ?? '') }))
+    .map((path) => ({ path, text: read(path) ?? '', info: parseDockerfile(read(path) ?? '') }))
     .filter((d) => d.info.instructions.some((x) => x.keyword === 'FROM'))
+  for (const d of dockerfiles) d.packages = [...new Set(d.info.instructions.filter((x) => x.keyword === 'RUN')
+    .flatMap((x) => [...(x.argv ? x.argv.join(' ') : x.args).matchAll(UV_PACKAGE)].map((m) => pyName(m[1]))))]
+  // A Dockerfile of a JVM product (Keycloak) with no manifest in its folder is a Java service of that product.
+  const products = new Map()
+  for (const d of dockerfiles) {
+    const product = JVM_PRODUCTS.find(([re]) => re.test(stageImages(d.info).at(-1) ?? ''))?.[1]
+    if (product && !candidates.has(dirOf(d.path))) { candidates.set(dirOf(d.path), new Map([['java', []]])); products.set(dirOf(d.path), { product, file: d.path }) }
+  }
+  // uv workspace members: name -> folder, and the folders that are members or the workspace root.
+  const members = new Map(), inWorkspace = new Set()
+  for (const [dir, langs] of candidates) {
+    if (!langs.has('python')) continue
+    const name = pythonProjectName(view, dir)
+    if (name && !members.has(name)) members.set(name, dir)
+    const workspace = uvWorkspace(view, dir)
+    if (workspace && [...workspace.members.values()].includes(dir) && dir !== workspace.root) inWorkspace.add(dir)
+    // A virtual workspace root (no [project]) only groups the members.
+    if (workspace && dir === workspace.root && !name) inWorkspace.add(dir)
+  }
   const dirs = [...candidates.keys()]
   // Folders that look like services before any Dockerfile is assigned: a framework or a start. Libraries do not count.
   const likely = dirs.filter((dir) => [...candidates.get(dir)].some(([lang, paths]) => frameworks(lang, paths, read).length)
@@ -101,7 +130,7 @@ export function detect(root) {
   const build = (dir, langs) => {
     const service = { dir, lang: null, frameworks: [], manifests: [], name: '', nameFrom: 'folder', dockerfile: null, start: null,
       runtimeVersion: null, k8s: [], problems: [], evidence: [] }
-    const docker = assignDockerfile(dir, { dirs, pool, refs: () => (refs ??= dockerfileRefs(view)) }, dockerfiles, service)
+    const docker = assignDockerfile(dir, { dirs, pool, refs: () => (refs ??= dockerfileRefs(view)), members, manifests: [...langs.values()].flat() }, dockerfiles, service)
     service.dockerfile = docker?.path ?? null
     const found = new Map([...langs].map(([lang, paths]) => [lang, { paths: paths.sort(byCodePoint), fw: frameworks(lang, paths, read) }]))
     service.lang = chooseLang(found, docker, service)
@@ -109,10 +138,22 @@ export function detect(root) {
       const { paths, fw } = found.get(service.lang)
       service.manifests = paths
       service.frameworks = [...new Set(fw.map((f) => f.id))].sort(byCodePoint)
+      const product = products.get(dir)
+      if (product && service.lang === 'java') {
+        service.frameworks = [product.product]
+        service.evidence.push({ file: product.file, what: `${product.product} image` })
+      }
       for (const path of paths) service.evidence.push({ file: path, what: `${LABEL[service.lang]} manifest` })
       for (const f of fw) service.evidence.push({ file: f.file, what: `${f.dep} in dependencies` })
     }
-    const start = findStart(service, docker, read)
+    // An Azure Functions app: the Functions framework of its stack and host.json in its folder. The Functions host
+    // starts it, so it has no start command of its own, and a Dockerfile builds a Functions image only (not handled).
+    const hostJson = join(dir, 'host.json')
+    if (service.frameworks.includes('azure-functions') && !docker && read(hostJson) !== null) {
+      service.functions = { hostJson }
+      service.evidence.push({ file: hostJson, what: 'host.json of an Azure Functions app' })
+    }
+    const start = service.functions ? { start: null, declared: true } : findStart(service, docker, read)
     service.start = start.start
     if (start.start) service.evidence.push({ file: start.start.file, line: start.start.line, what: 'start command' })
     else if (service.lang && !start.declared) service.problems.push({ code: 'start-unknown', message: `Found no start command for ${where(dir)}.` })
@@ -125,11 +166,19 @@ export function detect(root) {
     return service
   }
   let services = dirs.map((dir) => build(dir, candidates.get(dir)))
-  const qualified = services.filter((s) => s.frameworks.length || s.declared || s.dockerfile)
+  // A uv workspace member with no Dockerfile and no start is a library of the other members, even with a framework.
+  // When no member has a Dockerfile or a start at all, the members with a framework stay services, as before.
+  const serviceLike = (s) => s.frameworks.length || s.declared || s.dockerfile
+  const library = (s) => inWorkspace.has(s.dir) && !s.declared && !s.dockerfile && !s.problems.some((p) => p.code === 'dockerfile-ambiguous')
+  let qualified = services.filter((s) => serviceLike(s) && !library(s))
+  if (!qualified.length) qualified = services.filter((s) => serviceLike(s) && (s.dir !== '.' || !inWorkspace.has(s.dir)))
   if (qualified.length) {
     // Say which folders are left out and why, so a Go net/http service without a Dockerfile is never skipped silently.
     for (const s of services.filter((x) => x.lang && !qualified.includes(x))) {
-      problems.push({ code: 'skipped', message: `${where(s.dir)} has ${LABEL[s.lang]} files but no web framework, Dockerfile or start command, so this tool skips it. If it is a service, run npx @uknows/setup --path ${s.dir}, or follow the manual steps.` })
+      problems.push({ code: 'skipped', message: library(s) && qualified.every((q) => !library(q))
+        ? (s.dir === '.' || !pythonProjectName(view, s.dir) ? `${where(s.dir)} is the root of a uv workspace and has no app of its own, so this tool skips it.`
+          : `${where(s.dir)} is a uv workspace member with no Dockerfile or start command. This tool treats it as a library and skips it.`)
+        : `${where(s.dir)} has ${LABEL[s.lang]} files but no web framework, Dockerfile or start command, so this tool skips it. If it is a service, run npx @uknows/setup --path ${s.dir}, or follow the manual steps.` })
     }
     services = qualified
   }
@@ -180,7 +229,7 @@ function manifestLang(path, read) {
   if (name === 'package.json') return 'node'
   if (name === 'pyproject.toml' || name === 'Pipfile' || /^requirements.*\.txt$/.test(name) || /(?:^|\/)requirements\/[^/]+\.txt$/.test(path)) return 'python'
   if (name === 'go.mod') return 'go'
-  if (name.endsWith('.csproj')) return /Microsoft\.NET\.Sdk\.Web/.test(read(path) ?? '') ? 'dotnet' : null
+  if (name.endsWith('.csproj')) { const body = read(path) ?? ''; return /Microsoft\.NET\.Sdk\.Web/.test(body) || DOTNET_FUNCTIONS.test(body) ? 'dotnet' : null }
   if (name === 'pom.xml' || name === 'build.gradle' || name === 'build.gradle.kts') return 'java'
   if (name === 'composer.json') return 'php'
   if (name === 'Gemfile') return 'ruby'
@@ -202,7 +251,10 @@ function frameworks(lang, paths, read) {
       for (const dep of new Set(pythonDeps(file, body, read))) if (PY_FW.includes(dep)) add(dep, dep)
     } else if (lang === 'php') {
       for (const dep of Object.keys(object(json(body)?.require))) if (PHP_FW[dep]) add(PHP_FW[dep], dep)
-    } else if (lang === 'dotnet') add('aspnetcore', 'Microsoft.NET.Sdk.Web')
+    } else if (lang === 'dotnet') {
+      if (DOTNET_FUNCTIONS.test(body)) add('azure-functions', 'Microsoft.Azure.Functions.Worker')
+      else add('aspnetcore', 'Microsoft.NET.Sdk.Web')
+    }
     else for (const [id, re] of TEXT_FW[lang] ?? []) if (re.test(body.replace(/<!--[\s\S]*?-->|^\s*(?:#|\/\/).*$/gm, ''))) add(id, id)
   }
   return out
@@ -235,7 +287,7 @@ function pythonDeps(path, body, read, depth = 0) {
  * The Dockerfile that builds the service in dir, by the 4 rules in order. Adds dockerfile-ambiguous when it cannot tell.
  * dirs: every folder with a manifest. pool: the folders that look like services. refs: Dockerfile names that deploy files pass to -f.
  */
-function assignDockerfile(dir, { dirs, pool, refs }, dockerfiles, service) {
+function assignDockerfile(dir, { dirs, pool, refs, members, manifests = [] }, dockerfiles, service) {
   const pick = (d, why) => { service.evidence.push({ file: d.path, what: `Dockerfile for this service: ${why}` }); return d }
   const ambiguous = (list, same = false) => {
     const names = list.map((d) => d.path).join(', ')
@@ -244,6 +296,16 @@ function assignDockerfile(dir, { dirs, pool, refs }, dockerfiles, service) {
       : 'Use --path to pick a folder, or keep 1 Dockerfile.'}` })
     return null
   }
+  // uv sync --package <name>: the Dockerfile builds the workspace member with that name, wherever the Dockerfile is.
+  const name = [...members].find(([, d]) => d === dir)?.[0]
+  const installs = name ? dockerfiles.filter((d) => d.packages.includes(name)) : []
+  if (installs.length === 1) return pick(installs[0], `it runs uv sync --package ${name}`)
+  if (installs.length > 1) {
+    const named = installs.filter((d) => refs().has(posix.basename(d.path)))
+    return named.length === 1 ? pick(named[0], `${refs().get(posix.basename(named[0].path))} builds it with -f`) : ambiguous(installs, true)
+  }
+  // A Dockerfile that installs another member is not the Dockerfile of the folder it sits in.
+  dockerfiles = dockerfiles.filter((d) => !d.packages.some((p) => members.has(p) && members.get(p) !== dir))
   const own = dockerfiles.filter((d) => dirOf(d.path) === dir)
   if (own.length === 1) return pick(own[0], 'it is in the service folder')
   if (own.length > 1) {
@@ -260,12 +322,26 @@ function assignDockerfile(dir, { dirs, pool, refs }, dockerfiles, service) {
     }
     break
   }
+  // Dockerfiles in a folder of their own (docker/), built from the repo root as monorepos do.
+  const free = dockerfiles.filter((d) => !dirs.includes(dirOf(d.path)))
+  const byRef = (list) => list.filter((d) => refs().has(posix.basename(d.path)))
   if (dir !== '.') {
-    const free = dockerfiles.filter((d) => !dirs.includes(dirOf(d.path)))
-    const copying = free.filter((d) => copySources(d)
+    const copying = free.filter((d) => copySources(d.info)
       .some((src) => inside(dir, src) || inside(dir, posix.normalize(join(dirOf(d.path), src)))))
     if (copying.length === 1) return pick(copying[0], 'it copies the service folder')
     if (copying.length > 1) return ambiguous(copying)
+    // It copies a folder above the service (csharp/src/ for csharp/src/EdgeProxy) and names a manifest of the service,
+    // or no other service is in that folder.
+    const parent = free.filter((d) => copySources(d.info).some((src) => src !== '.' && dir.startsWith(`${src.replace(/\/+$/, '')}/`)
+      && (manifests.some((m) => d.text.includes(m)) || pool.filter((x) => x !== dir && inside(src, x)).length === 0)))
+    if (parent.length === 1) return pick(parent[0], `it copies a folder above the service folder and builds ${manifests.find((m) => parent[0].text.includes(m)) ?? 'it'}`)
+    if (parent.length > 1) return byRef(parent).length === 1 ? pick(byRef(parent)[0], `${refs().get(posix.basename(byRef(parent)[0].path))} builds it with -f`) : ambiguous(parent, true)
+  } else if (manifests.length) {
+    // The root service: a Dockerfile elsewhere that copies a manifest from the repo root (COPY pyproject.toml uv.lock ./).
+    const names = manifests.filter((m) => !m.includes('/'))
+    const root = free.filter((d) => copySources(d.info).some((src) => names.includes(src.replace(/^\.\//, ''))))
+    if (root.length === 1) return pick(root[0], `it copies ${names.find((m) => copySources(root[0].info).includes(m)) ?? 'the manifest'} from the repo root`)
+    if (root.length > 1) return byRef(root).length === 1 ? pick(byRef(root)[0], `${refs().get(posix.basename(byRef(root)[0].path))} builds it with -f`) : ambiguous(root, true)
   }
   // The only Dockerfile, unless it sits in the folder of another manifest: then it builds that one.
   if (dockerfiles.length === 1 && !dirs.includes(dirOf(dockerfiles[0].path)) && (pool.length === 0 || (pool.length === 1 && pool[0] === dir))) {
@@ -274,10 +350,14 @@ function assignDockerfile(dir, { dirs, pool, refs }, dockerfiles, service) {
   return null
 }
 
-/** Source paths of the COPY and ADD instructions that read the build context (not --from). */
-function copySources(dockerfile) {
+/**
+ * Source paths of the COPY and ADD instructions that read the build context (not --from), relative to the context.
+ * @param {import('./dockerfile.mjs').DockerfileInfo} info
+ * @returns {string[]}
+ */
+export function copySources(info) {
   const out = []
-  for (const x of dockerfile.info.instructions) {
+  for (const x of info.instructions) {
     if ((x.keyword !== 'COPY' && x.keyword !== 'ADD') || /(?:^|\s)--from=/.test(x.args)) continue
     const rest = x.args.replace(/^(?:--\S+\s+)*/, '')
     let words = rest.split(/\s+/).filter(Boolean)
@@ -512,34 +592,6 @@ function scalar(item, key) {
   return /^(['"])(.*)\1$/.exec(value)?.[2] ?? (value || null)
 }
 
-// --- small TOML reader (tables, strings, string arrays, keys) -----------------
-
-function tomlTable(body, header) {
-  const out = []
-  let on = false
-  for (const line of body.split(/\r?\n/)) {
-    const h = /^\s*\[([^\][]+)\]\s*(?:#.*)?$/.exec(line)
-    if (h) { on = h[1].trim() === header; continue }
-    if (/^\s*\[\[/.test(line)) { on = false; continue }
-    if (on) out.push(line)
-  }
-  return out.join('\n')
-}
-const tomlString = (table, key) => new RegExp(`^\\s*${key}\\s*=\\s*(["'])([^"'\\n]*)\\1`, 'm').exec(table)?.[2] ?? null
-const tomlKeys = (table) => table.split('\n').map((l) => /^\s*"?([A-Za-z0-9_.-]+)"?\s*=/.exec(l)?.[1]).filter(Boolean)
-function tomlArray(table, key) {
-  const m = new RegExp(`^\\s*${key}\\s*=\\s*\\[`, 'm').exec(table)
-  if (!m) return []
-  const out = []
-  let quote = '', value = ''
-  for (const c of table.slice(m.index + m[0].length)) {
-    if (quote) { if (c === quote) { out.push(value); quote = ''; value = '' } else value += c }
-    else if (c === '"' || c === "'") quote = c
-    else if (c === ']') break
-  }
-  return out
-}
-
 // --- helpers ------------------------------------------------------------------
 
 /**

package/lib/dockerfile.mjs

@@ -128,6 +128,29 @@ function parents(stages, i) {
   return out
 }
 
+/**
+ * The image that the final stage runs on. FROM base AS final (the Visual Studio layout) names an earlier stage, so
+ * follow the stage names to the image of the first one: mcr.microsoft.com/dotnet/aspnet:8.0-alpine, not base.
+ * @param {DockerfileInfo} info
+ * @returns {string|null}
+ */
+export function finalImage(info) {
+  const { stages } = info
+  if (!stages.length) return info.image ?? null
+  return parents(stages, stages.length - 1).at(-1)?.image ?? stages.at(-1).image
+}
+
+/**
+ * The final stage and the earlier stages it builds on (FROM <stage>), final stage first. Their RUN lines are in the image.
+ * @param {DockerfileInfo} info
+ * @returns {Stage[]}
+ */
+export function finalStages(info) {
+  const { stages } = info
+  if (!stages.length) return [{ image: '', name: null, instructions: info.instructions }]
+  return [stages.at(-1), ...parents(stages, stages.length - 1)]
+}
+
 /**
  * The stages whose files reach the final image: the final stage, the stages it
  * builds on, and the stages they COPY --from, again and again.
@@ -296,6 +319,66 @@ export function prefixStart(text, words) {
   return doc.toString()
 }
 
+/**
+ * Put words at position `at` of the start command, counted as dockerStart counts it (ENTRYPOINT, then CMD), for a
+ * runner such as uv run --no-sync uvicorn: the words go after the runner and its options. at 0 is prefixStart.
+ * Only a 1-line exec form, or a 1-line shell form without quotes. Returns the text unchanged when the words are
+ * already there, and null when it cannot be changed safely.
+ * @param {string} text
+ * @param {number} at
+ * @param {string[]} words
+ * @returns {string|null}
+ */
+export function insertStart(text, at, words) {
+  if (at === 0) return prefixStart(text, words)
+  const { entrypoint, cmd } = parseDockerfile(text)
+  const parts = entrypoint && !entrypoint.argv ? [entrypoint] : [entrypoint, cmd].filter(Boolean)
+  const doc = new Doc(text)
+  let offset = 0
+  for (const [n, part] of parts.entries()) {
+    const shell = !part.argv && !/["']/.test(part.args)
+    const argv = part.argv ?? (shell && parts.length === 1 ? shellWords(part.args.replace(/^exec\s+/, '')) : null)
+    if (!argv) return null
+    const k = at - offset
+    offset += argv.length
+    if (k > argv.length || (k === argv.length && n < parts.length - 1)) continue
+    if (words.every((w, j) => argv[k + j] === w)) return text
+    if (part.start !== part.end) return null
+    const line = doc.get(part.start)
+    const keywordEnd = /^\s*[A-Za-z]+\s*/.exec(line)[0].length
+    if (part.argv) {
+      const tokens = jsonStrings(line, keywordEnd)
+      if (tokens.length !== argv.length) return null
+      const sep = argv.length < 2 || /",\s+"/.test(part.args) ? ', ' : ','
+      const inserted = words.map((w) => JSON.stringify(w)).join(sep)
+      doc.set(part.start, k < tokens.length ? line.slice(0, tokens[k].start) + inserted + sep + line.slice(tokens[k].start)
+        : line.slice(0, tokens.at(-1).end) + sep + inserted + line.slice(tokens.at(-1).end))
+    } else {
+      const head = keywordEnd + (/^exec\s+/.exec(line.slice(keywordEnd))?.[0].length ?? 0)
+      const starts = [...line.slice(head).matchAll(/\S+/g)].map((m) => head + m.index)
+      if (starts.length !== argv.length) return null
+      const pos = k < starts.length ? starts[k] : line.trimEnd().length + 1
+      const insert = words.map(shellQuote).join(' ')
+      doc.set(part.start, k < starts.length ? `${line.slice(0, pos)}${insert} ${line.slice(pos)}` : `${line.trimEnd()} ${insert}${line.slice(line.trimEnd().length)}`)
+    }
+    return doc.toString()
+  }
+  return null
+}
+
+/** Start and end columns of the JSON strings in an exec-form line, from the '['. */
+function jsonStrings(line, from) {
+  const out = []
+  for (let i = line.indexOf('[', from); i >= 0 && i < line.length; i++) {
+    if (line[i] === ']') break
+    if (line[i] !== '"') continue
+    const start = i
+    for (i++; i < line.length && line[i] !== '"'; i++) if (line[i] === '\\') i++
+    out.push({ start, end: i + 1 })
+  }
+  return out
+}
+
 // --- helpers ---------------------------------------------------------------
 
 /** A value for an ENV token. escape is the escape character of the Dockerfile. raw keeps $ references. */

package/lib/endpoint.mjs

@@ -4,9 +4,10 @@
  * workspace a key sends to, and where the docs links point. Both are the
  * addresses of this build (contract-docs.mjs), unless UKNOWS_INGEST_ENDPOINT
  * or UKNOWS_SITE_URL names another one, for example a test copy of UKNOWS.
+ * The app address (the link where an app connects) follows UKNOWS_APP_URL.
  * Setup and check use these same rules, so a test run writes the address it checks.
  */
-import { CLI, INGEST_ENDPOINT, SITE_URL } from './contract.mjs'
+import { APP_URL, CLI, INGEST_ENDPOINT, SETUP_NEXT, SITE_URL, openLive } from './contract.mjs'
 
 const LOCAL = new Set(['localhost', '127.0.0.1', '[::1]'])
 const safe = (url) => url.protocol === 'https:' || (url.protocol === 'http:' && LOCAL.has(url.hostname))
@@ -23,16 +24,46 @@ export function ingestEndpoint(env = {}) {
   return safe(url) && !url.username && !url.password ? raw : null
 }
 
+/** An origin (https, or http on this computer), no path, no user: the origin, else null. */
+function origin(raw) {
+  let url
+  try { url = new URL(String(raw).trim().replace(/\/+$/, '')) } catch { return null }
+  return safe(url) && !url.username && !url.password && url.pathname === '/' && !url.search && !url.hash ? url.origin : null
+}
+
 /**
  * The site address (origin only, no trailing slash), or null when the override is not https or has a path.
  * @param {Record<string, string|undefined>} [env]
  * @returns {string|null}
  */
 export function siteUrl(env = {}) {
-  const raw = String(env[CLI.siteEnv] || SITE_URL).trim().replace(/\/+$/, '')
-  let url
-  try { url = new URL(raw) } catch { return null }
-  return safe(url) && !url.username && !url.password && url.pathname === '/' && !url.search && !url.hash ? url.origin : null
+  return origin(env[CLI.siteEnv] || SITE_URL)
+}
+
+/** True when UKNOWS_APP_URL is not set, or is an origin as siteUrl wants it. */
+export const validAppUrl = (env = {}) => !env[CLI.appEnv] || origin(env[CLI.appEnv]) !== null
+
+/**
+ * The app address, where people sign in and watch an app connect: UKNOWS_APP_URL, else the one of this build. A run
+ * against a test copy (UKNOWS_SITE_URL or UKNOWS_INGEST_ENDPOINT) without UKNOWS_APP_URL does not know the app of that
+ * copy: null, so setup never sends the user to the production app.
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function appUrl(env = {}) {
+  if (env[CLI.appEnv]) return origin(env[CLI.appEnv])
+  return env[CLI.siteEnv] || env[CLI.endpointEnv] ? null : APP_URL
+}
+
+/**
+ * The last line when only the deploy is left, with the app address of this run (F-012-146): where to sign in, from
+ * UKNOWS_APP_URL, else from this build. A test copy without UKNOWS_APP_URL gets no address, never the production one.
+ * The same line goes in the "next" field of --json.
+ * @param {Record<string, string|undefined>} [env]
+ */
+export function nextData(env = {}) {
+  const app = appUrl(env)
+  return SETUP_NEXT.data.replace('{open}', app ? openLive(app) : SETUP_NEXT.testCopy)
 }
 
 /**