@uknows/setup 0.0.0-stage → 0.1.0

package/lib/contract.mjs

@@ -0,0 +1,66 @@
+/*
+ * The UKNOWS install contract. Data only.
+ *
+ * Everything the docs page shows comes from contract-docs.mjs, which
+ * tools/sync-contract.mjs generates from src/docs/install.ts. Import those
+ * values from here and never copy their text into other modules, so a
+ * re-sync updates the whole CLI.
+ *
+ * PINS and CLI below are values the CLI needs that the docs page does not
+ * show. Upstream facts checked on 2026-10-12.
+ */
+
+export * from './contract-docs.mjs'
+import { NODE_REGISTER, PING_URL } from './contract-docs.mjs'
+
+export const PINS = {
+  node: {
+    /** Same 2 packages as the docs install line. The package manager picks the versions. */
+    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}`,
+  },
+  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',
+    /** Version of each opentelemetry-instrumentation-* package that opentelemetry-bootstrap prints. */
+    contrib: '0.66b1',
+    /** opentelemetry-distro 0.66b1 needs Python 3.10 or later. */
+    minPython: [3, 10],
+  },
+  dotnet: {
+    package: 'OpenTelemetry.AutoInstrumentation',
+    version: '1.17.0',
+    /** 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' },
+  },
+  go: {
+    /**
+     * go get takes the latest modules. go.opentelemetry.io/otel v1.47.0 and otelhttp declare go 1.26.0, so older Go
+     * builders fail (golang images set GOTOOLCHAIN=local). Checked upstream on 2026-10-12.
+     */
+    minGo: [1, 26],
+  },
+  php: {
+    /** The 6th setting for PHP. The docs PHP Dockerfile adds it with the 5. */
+    autoload: { name: 'OTEL_PHP_AUTOLOAD_ENABLED', value: 'true' },
+  },
+}
+
+export const CLI = {
+  /** Records what setup changed so remove can undo it exactly. Never holds secrets. */
+  manifest: '.uknows/setup.json',
+  /** Override for the ingest address, for a test environment. setup writes it and check sends to it (endpoint.mjs). */
+  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',
+  /** 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.',
+}

package/lib/detect.mjs

@@ -0,0 +1,575 @@
+/*
+ * Find the services of a repo: their language, frameworks, Dockerfile, start
+ * command, name, runtime version and Kubernetes containers. Static reading
+ * only: nothing runs and nothing goes over the network. The rules come from
+ * the UKNOWS agent kit inspect step.
+ */
+import { basename, posix } from 'node:path'
+import { Doc, shellWords } from './doc.mjs'
+import { dockerStart, parseDockerfile } from './dockerfile.mjs'
+import { SETTINGS_FILE } from './contract.mjs'
+import { detectHosts } from './hosts.mjs'
+import { createWorkspace, repoView } from './workspace.mjs'
+
+const MAX_BYTES = 1_000_000
+/** Tie-break when 1 folder has 2 languages and nothing else decides: Node last, it is often front-end tooling. */
+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']
+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/]],
+  go: [['echo', /github\.com\/labstack\/echo\b/], ['gin', /github\.com\/gin-gonic\/gin\b/], ['chi', /github\.com\/go-chi\/chi\b/]],
+  ruby: [['rails', /^\s*gem\s*\(?\s*['"]rails['"]/m], ['sinatra', /^\s*gem\s*\(?\s*['"]sinatra['"]/m]],
+}
+/** Base images per language, as in the UKNOWS agent kit. The tag gives the runtime version. */
+const IMAGE = {
+  python: /(?:^|\/)python(?:[:@]|$)/, node: /(?:^|\/)node(?:[:@]|$)/, go: /(?:^|\/)golang(?:[:@]|$)/,
+  dotnet: /mcr\.microsoft\.com\/dotnet\/(?:aspnet|sdk|runtime|runtime-deps)(?:[:@]|$)/,
+  java: /(?:^|\/)(?:eclipse-temurin|openjdk|amazoncorretto|ibm-semeru-runtimes|sapmachine)(?:[:@]|$)/,
+  php: /(?:^|\/)php(?:[:@]|$)/, ruby: /(?:^|\/)ruby(?:[:@]|$)/,
+}
+const DOCKERFILE = /^(?:Dockerfile(?:\.[^/]+)?|[^/]+\.[Dd]ockerfile)$/
+/** 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('|'))
+const DOCKERFILE_REF = /(?:^|\s)(?:-f|--file)(?:\s+|=)["']?([^\s"';&|)]+)|^\s*-?\s*(?:dockerfile|file|dockerfilePath)\s*:\s*["']?([^\s"'#]+)/gim
+/** A final image that only serves files, and dependencies of browser apps: such a Node folder is a frontend. */
+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 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
+
+/**
+ * Find the services, stacks, start commands and hosts of the repo. Static reading only.
+ * @param {string} root absolute or relative path of the repo root
+ * @returns {import('./types.mjs').Detection}
+ */
+export function detect(root) {
+  const ws = createWorkspace(root)
+  const view = repoView(ws)
+  const problems = []
+  const read = reader(ws, problems)
+  const files = ws.files()
+  if (ws.truncated) {
+    problems.push({ code: 'too-many-files', message: 'The repo has more than 20000 files. This tool read the first 20000 only.' })
+  }
+
+  // 1. Folders with a manifest, per language.
+  const candidates = new Map()
+  for (const path of files) {
+    const lang = manifestLang(path, read)
+    if (!lang) continue
+    const dir = /(?:^|\/)requirements\/[^/]+\.txt$/.test(path) ? dirOf(dirOf(path)) : dirOf(path)
+    if (!candidates.has(dir)) candidates.set(dir, new Map())
+    const langs = candidates.get(dir)
+    if (!langs.has(lang)) langs.set(lang, [])
+    langs.get(lang).push(path)
+  }
+  for (const [dir, langs] of candidates) {
+    const pkg = langs.has('node') ? json(read(join(dir, 'package.json'))) : null
+    if (pkg && (pkg.workspaces || files.includes(join(dir, 'pnpm-workspace.yaml'))) && !text(pkg.scripts?.start)) langs.delete('node')
+    if (langs.has('java')) {
+      // A Maven parent POM or a Gradle multi-project root only groups the real services below it.
+      const gradleRoot = ['settings.gradle', 'settings.gradle.kts'].some((f) => /^\s*include\b/m.test(read(join(dir, f)) ?? ''))
+      const kept = langs.get('java').filter((p) => (p.endsWith('pom.xml') ? !/<packaging>\s*pom\s*<\/packaging>/.test(read(p) ?? '') : !gradleRoot))
+      if (kept.length) langs.set('java', kept); else langs.delete('java')
+    }
+    if (!langs.size) candidates.delete(dir)
+  }
+
+  // 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) ?? '') }))
+    .filter((d) => d.info.instructions.some((x) => x.keyword === 'FROM'))
+  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)
+    || /^web\s*:/m.test(read(join(dir, 'Procfile')) ?? '') || text(json(read(join(dir, 'package.json')))?.scripts?.start))
+  const pool = likely.length ? likely : dirs
+
+  // 3. Build each service.
+  const k8s = files.filter((p) => /\.ya?ml$/.test(p) && !p.startsWith('.github/') && !/(?:^|\/)pnpm-lock\.yaml$/.test(p))
+    .flatMap((path) => { const t = read(path, true); return t && !t.includes('{{') ? containersOf(path, t) : [] })
+  let refs = null
+  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)
+    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)
+    if (service.lang) {
+      const { paths, fw } = found.get(service.lang)
+      service.manifests = paths
+      service.frameworks = [...new Set(fw.map((f) => f.id))].sort(byCodePoint)
+      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)
+    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)}.` })
+    service.declared = start.declared
+    service.runtimeVersion = runtimeVersion(service, docker, read)
+    if (frontend(service, docker, read)) {
+      service.problems = [...service.problems.filter((p) => p.code !== 'start-unknown'),
+        { code: 'frontend', message: 'Looks like a frontend. UKNOWS traces server apps.' }]
+    }
+    return service
+  }
+  let services = dirs.map((dir) => build(dir, candidates.get(dir)))
+  const qualified = services.filter((s) => s.frameworks.length || s.declared || s.dockerfile)
+  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.` })
+    }
+    services = qualified
+  }
+  else if (services.some((s) => s.dir === '.')) services = services.filter((s) => s.dir === '.')
+  // Frontends are left out when there is a server app. Alone, they stay, so the CLI can say why it does nothing.
+  const isFrontend = (s) => s.problems.some((p) => p.code === 'frontend')
+  if (services.some((s) => !isFrontend(s))) {
+    for (const s of services.filter(isFrontend)) {
+      problems.push({ code: 'frontend', message: `${where(s.dir)} looks like a frontend. UKNOWS traces server apps, so this tool skips it.` })
+    }
+    services = services.filter((s) => !isFrontend(s))
+  }
+  if (!services.length) services = [build('.', new Map())]
+  services.sort((a, b) => byCodePoint(a.dir, b.dir))
+
+  // 4. Names and Kubernetes containers.
+  for (const service of services) {
+    delete service.declared
+    const folder = service.dir === '.' ? basename(ws.root) : posix.basename(service.dir)
+    const proposed = manifestName(service, read) ?? { name: toServiceName(folder) ?? 'app', from: 'folder' }
+    const keys = new Set([proposed.name, folder, toServiceName(folder)])
+    let matches = k8s.filter((c) => keys.has(c.name) || keys.has(imageName(c.image)))
+    if (!matches.length && services.length === 1 && k8s.length === 1) matches = k8s
+    service.k8s = matches.map(({ file, doc, name, env, command, args }) => ({ file, doc, container: name,
+      env: Object.fromEntries([...env].filter(([key]) => key)), command, args }))
+    const existing = existingName(service, matches, read)
+    Object.assign(service, existing ? { name: existing.name, nameFrom: 'existing' } : { name: proposed.name, nameFrom: proposed.from })
+    if (existing) service.evidence.push({ file: existing.file, what: 'OTEL_SERVICE_NAME is already set' })
+  }
+  return { root: ws.root, services, hosts: detectHosts(view), problems }
+}
+
+/**
+ * Turn any text into a valid OTEL_SERVICE_NAME ([a-z0-9-], 1 to 63 chars), or null when nothing is left.
+ * PascalCase is split: OrdersApi becomes orders-api, HTTPServer becomes http-server.
+ */
+export function toServiceName(text) {
+  if (typeof text !== 'string') return null
+  const name = text.replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+    .toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 63).replace(/-+$/, '')
+  return name || null
+}
+
+// --- manifests and frameworks ------------------------------------------------
+
+function manifestLang(path, read) {
+  const name = posix.basename(path)
+  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 === 'pom.xml' || name === 'build.gradle' || name === 'build.gradle.kts') return 'java'
+  if (name === 'composer.json') return 'php'
+  if (name === 'Gemfile') return 'ruby'
+  return null
+}
+
+/** Frameworks from declared dependencies only, never from ordinary words in the text. */
+function frameworks(lang, paths, read) {
+  const out = []
+  for (const file of paths) {
+    const body = read(file) ?? ''
+    const add = (id, dep) => out.push({ id, dep, file })
+    if (lang === 'node') {
+      const pkg = json(body)
+      for (const group of ['dependencies', 'devDependencies', 'peerDependencies']) {
+        for (const dep of Object.keys(object(pkg?.[group]))) if (NODE_FW[dep]) add(NODE_FW[dep], dep)
+      }
+    } else if (lang === 'python') {
+      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 for (const [id, re] of TEXT_FW[lang] ?? []) if (re.test(body.replace(/<!--[\s\S]*?-->|^\s*(?:#|\/\/).*$/gm, ''))) add(id, id)
+  }
+  return out
+}
+
+/** Normalized names (PEP 503) of the requirements in a requirements file, pyproject.toml or Pipfile. */
+function pythonDeps(path, body, read, depth = 0) {
+  const name = posix.basename(path)
+  const norm = (s) => /^\s*([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(s)?.[1].toLowerCase().replace(/[-_.]+/g, '-')
+  if (name === 'pyproject.toml') {
+    const poetry = tomlKeys(tomlTable(body, 'tool.poetry.dependencies')).filter((k) => k !== 'python')
+    return [...tomlArray(tomlTable(body, 'project'), 'dependencies'), ...poetry].map(norm).filter(Boolean)
+  }
+  if (name === 'Pipfile') return tomlKeys(tomlTable(body, 'packages')).map(norm).filter(Boolean)
+  const out = []
+  for (const raw of body.split(/\r?\n/)) {
+    const line = raw.replace(/(?:^|\s)#.*$/, '').trim()
+    const include = /^(?:-r|--requirement)(?:\s+|=)(\S+)$/.exec(line)
+    if (include && depth === 0) {
+      const target = posix.normalize(join(dirOf(path), include[1]))
+      if (!target.startsWith('..')) out.push(...pythonDeps(target, read(target) ?? '', read, 1))
+    } else if (line && !line.startsWith('-')) out.push(norm(line))
+  }
+  return out.filter(Boolean)
+}
+
+// --- Dockerfile, language, start --------------------------------------------
+
+/**
+ * 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) {
+  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(', ')
+    service.problems.push({ code: 'dockerfile-ambiguous', message: `Found ${list.length} Dockerfiles for ${where(dir)}: ${names}. ${same
+      ? 'This tool does not know which one you deploy. Name it with -f in a deploy workflow or script, or keep 1 Dockerfile in the folder.'
+      : 'Use --path to pick a folder, or keep 1 Dockerfile.'}` })
+    return null
+  }
+  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) {
+    // Dockerfile and Dockerfile.production: the deploy files tell which one ships.
+    const named = own.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(own, true)
+  }
+  for (let up = dir; up !== '.';) {
+    up = dirOf(up)
+    const here = dockerfiles.filter((d) => dirOf(d.path) === up)
+    if (!here.length) continue
+    if (here.length === 1 && pool.includes(dir) && pool.filter((d) => inside(up, d)).length === 1) {
+      return pick(here[0], 'it is the only Dockerfile above the service folder')
+    }
+    break
+  }
+  if (dir !== '.') {
+    const free = dockerfiles.filter((d) => !dirs.includes(dirOf(d.path)))
+    const copying = free.filter((d) => copySources(d)
+      .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)
+  }
+  // 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))) {
+    return pick(dockerfiles[0], 'it is the only Dockerfile in the repo')
+  }
+  return null
+}
+
+/** Source paths of the COPY and ADD instructions that read the build context (not --from). */
+function copySources(dockerfile) {
+  const out = []
+  for (const x of dockerfile.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)
+    if (rest.startsWith('[')) { try { const list = JSON.parse(rest); if (Array.isArray(list)) words = list } catch { /* shell form */ } }
+    for (const src of words.slice(0, -1)) {
+      const clean = String(src).replace(/^\.\//, '').replace(/\/(?:\*|\.)?$/, '')
+      if (clean && clean !== '.' && !/^[a-z]+:\/\//i.test(clean)) out.push(clean)
+    }
+  }
+  return out
+}
+
+/** Dockerfile names (basenames) that deploy files pass to docker build -f, or name in compose and CI files -> the first such file. */
+function dockerfileRefs(view) {
+  const refs = new Map()
+  for (const file of view.files().filter((f) => DEPLOY_FILE.test(f))) {
+    let text = null
+    try { text = (view.stat(file)?.size ?? 0) > MAX_BYTES ? null : view.read(file) } catch { /* unreadable */ }
+    for (const m of (text ?? '').matchAll(DOCKERFILE_REF)) {
+      const name = posix.basename(m[1] ?? m[2])
+      if (DOCKERFILE.test(name) && !refs.has(name)) refs.set(name, file)
+    }
+  }
+  return refs
+}
+
+/**
+ * A Node folder that builds a browser app: its final image only serves files (nginx and the like), or it has no
+ * Dockerfile, no server framework and no start other than a dev server, and it uses a browser framework.
+ */
+function frontend(service, docker, read) {
+  if (service.lang !== 'node') return false
+  if (docker) {
+    const start = dockerStart(docker.info)
+    const words = start?.argv ?? start?.raw.split(/[\s"',[\]]+/) ?? []
+    return STATIC_IMAGE.test(stageImages(docker.info).at(-1) ?? '') && !words.some((w) => RUNS_NODE.test(posix.basename(w)))
+  }
+  if (service.frameworks.some((f) => SERVER_FW.has(f))) return false
+  const pkg = json(read(join(service.dir, 'package.json')))
+  if (!Object.keys({ ...object(pkg?.dependencies), ...object(pkg?.devDependencies) }).some((d) => FRONTEND_DEP.test(d))) return false
+  return !service.start || DEV_SERVER.test(posix.basename(service.start.argv?.[0] ?? ''))
+}
+
+/** Resolved FROM images of every stage, in order. The last one is the image that runs. */
+function stageImages(info) {
+  const stages = new Map(), out = []
+  for (const x of info.instructions.filter((i) => i.keyword === 'FROM')) {
+    const words = x.args.split(/\s+/).filter((w) => !w.startsWith('--'))
+    let image = words[0] ?? ''
+    for (let hop = 0; hop < 5 && stages.has(image.toLowerCase()); hop++) image = stages.get(image.toLowerCase())
+    if (words[1]?.toLowerCase() === 'as' && words[2]) stages.set(words[2].toLowerCase(), image)
+    out.push(image)
+  }
+  return out
+}
+
+/** 1 language per folder: the Dockerfile image decides, else the only one with a framework, else LANGS order. */
+function chooseLang(found, docker, service) {
+  const langs = LANGS.filter((lang) => found.has(lang))
+  if (langs.length < 2) return langs[0] ?? null
+  const images = docker ? stageImages(docker.info).reverse() : []
+  const byImage = images.map((image) => langs.find((lang) => IMAGE[lang].test(image))).find(Boolean)
+  const withFw = langs.filter((lang) => found.get(lang).fw.length)
+  const lang = byImage ?? (withFw.length === 1 ? withFw[0] : (withFw[0] ?? langs[0]))
+  const why = byImage ? `the Dockerfile image is ${LABEL[lang]}` : withFw.length === 1 ? 'it has the framework' : 'no file decides'
+  const others = langs.filter((l) => l !== lang).map((l) => LABEL[l]).join(', ')
+  service.evidence.push({ file: found.get(lang).paths[0], what: `${LABEL[lang]} chosen over ${others} because ${why}` })
+  return lang
+}
+
+/** Dockerfile final stage, else exactly 1 Procfile web: line, else package.json scripts.start (Node only). */
+function findStart(service, docker, read) {
+  if (docker) {
+    const start = dockerStart(docker.info)
+    if (start) return { declared: true, start: { kind: 'dockerfile', file: docker.path, ...start } }
+  }
+  const procfile = join(service.dir, 'Procfile')
+  const doc = new Doc(read(procfile) ?? '')
+  const webs = doc.lines.map((line, i) => (/^web\s*:/.test(line) ? i : -1)).filter((i) => i >= 0)
+  if (webs.length > 1) {
+    service.problems.push({ code: 'start-ambiguous', message: `${procfile} has ${webs.length} web: lines. This tool did not pick one.` })
+    return { declared: true, start: null }
+  }
+  if (webs.length === 1) {
+    const raw = doc.get(webs[0]).replace(/^web\s*:\s*/, '').trim()
+    return { declared: true, start: { kind: 'procfile', file: procfile, line: webs[0] + 1, form: 'shell', raw, argv: shellWords(raw) } }
+  }
+  if (service.lang !== 'node') return { declared: false, start: null }
+  const file = join(service.dir, 'package.json')
+  const body = read(file) ?? ''
+  const scripts = object(json(body)?.scripts)
+  if (!text(scripts.start)) return { declared: false, start: null }
+  if (scripts.prestart || scripts.poststart) {
+    service.problems.push({ code: 'start-hooks', message: `${file} has a prestart or poststart script. Check that it still works with OpenTelemetry.` })
+  }
+  const lines = new Doc(body)
+  const line = lines.find(/"start"\s*:/, Math.max(0, lines.find(/"scripts"\s*:/)))
+  return { declared: true, start: { kind: 'package.json', file, line: line + 1, form: 'shell', raw: scripts.start, argv: shellWords(scripts.start) } }
+}
+
+/** Exact versions only: the final FROM tag, else .python-version, TargetFramework, the go directive or .nvmrc. */
+function runtimeVersion(service, docker, read) {
+  const { lang, dir, manifests } = service
+  if (!lang) return null
+  const image = docker ? stageImages(docker.info).at(-1) : ''
+  if (image && IMAGE[lang].test(image)) {
+    const tag = /:v?(\d+(?:\.\d+){0,2})(?![\d.])/.exec(image.replace(/@.*$/, '').split('/').pop())
+    if (tag) return tag[1]
+  }
+  const exact = (file, re) => re.exec((read(join(dir, file)) ?? '').trim())?.[1] ?? null
+  if (lang === 'python') return exact('.python-version', /^(\d+\.\d+(?:\.\d+)?)$/)
+  if (lang === 'node') return exact('.nvmrc', /^v?(\d+(?:\.\d+){0,2})$/) ?? exact('.node-version', /^v?(\d+(?:\.\d+){0,2})$/)
+  if (lang === 'go') return /^go\s+(\d+\.\d+(?:\.\d+)?)\s*$/m.exec(read(manifests[0]) ?? '')?.[1] ?? null
+  if (lang === 'dotnet') {
+    const net = (body) => /<TargetFrameworks?>\s*net(\d+\.\d+)/.exec(body ?? '')?.[1] ?? null
+    let version = net(read(manifests[0]))
+    for (let up = dirOf(manifests[0]); !version; up = dirOf(up)) {
+      version = net(read(join(up, 'Directory.Build.props')))
+      if (up === '.') break
+    }
+    return version
+  }
+  return null
+}
+
+// --- names --------------------------------------------------------------------
+
+function manifestName(service, read) {
+  for (const path of service.manifests) {
+    const body = read(path) ?? ''
+    const file = posix.basename(path)
+    let value = null
+    if (file === 'package.json') value = text(json(body)?.name)?.replace(/^@[^/]+\//, '')
+    else if (file === 'pyproject.toml') value = tomlString(tomlTable(body, 'project'), 'name') ?? tomlString(tomlTable(body, 'tool.poetry'), 'name')
+    else if (file.endsWith('.csproj')) {
+      const assembly = /<AssemblyName>\s*([^<]+?)\s*<\/AssemblyName>/.exec(body)?.[1]
+      value = assembly && !assembly.includes('$') ? assembly : file.slice(0, -'.csproj'.length)
+    } else if (file === 'pom.xml') {
+      const own = body.replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/<(parent|dependencies|dependencyManagement|build|profiles|plugins|reporting|modules)\b[\s\S]*?<\/\1>/g, '')
+      value = /<artifactId>\s*([^<$]+?)\s*<\/artifactId>/.exec(own)?.[1]
+    } else if (file === 'go.mod') value = /^module\s+"?([^"\s]+)/m.exec(body)?.[1].replace(/\/v\d+$/, '').split('/').pop()
+    else if (file === 'composer.json') value = text(json(body)?.name)?.split('/').pop()
+    if (toServiceName(value)) return { name: toServiceName(value), from: file }
+  }
+  const gradle = /rootProject\.name\s*=\s*['"]([^'"]+)['"]/
+  const more = service.lang === 'java' ? [['settings.gradle', gradle], ['settings.gradle.kts', gradle]]
+    : service.lang === 'ruby' ? [['config/application.rb', /^\s*module\s+([A-Z]\w*)/m]] : []
+  for (const [file, re] of more) {
+    const value = re.exec(read(join(service.dir, file)) ?? '')?.[1]
+    if (toServiceName(value)) return { name: toServiceName(value), from: posix.basename(file) }
+  }
+  return null
+}
+
+/** An OTEL_SERVICE_NAME already in the Dockerfile final stage (or a stage it builds on), <dir>/otel.env or the Kubernetes container env. */
+function existingName(service, containers, read) {
+  const found = []
+  if (service.dockerfile) {
+    const info = parseDockerfile(read(service.dockerfile) ?? '')
+    found.push([service.dockerfile, (info.env.get('OTEL_SERVICE_NAME') ?? info.inherited.get('OTEL_SERVICE_NAME'))?.value])
+  }
+  const envFile = join(service.dir, SETTINGS_FILE.path)
+  const line = /^\s*(?:export\s+)?OTEL_SERVICE_NAME\s*=\s*['"]?([^'"\r\n#]*?)['"]?\s*$/m.exec(read(envFile) ?? '')
+  found.push([envFile, line?.[1]])
+  for (const c of containers) found.push([c.file, c.env.get('OTEL_SERVICE_NAME')])
+  for (const [file, value] of found) {
+    if (typeof value === 'string' && !value.includes('$') && toServiceName(value)) return { file, name: toServiceName(value) }
+  }
+  return null
+}
+
+const imageName = (image) => (image ?? '').replace(/@.*$/, '').replace(/:[^/]*$/, '').split('/').pop()
+
+// --- Kubernetes YAML ------------------------------------------------------------
+
+/**
+ * Containers of the workloads in 1 plain YAML file. `doc` is the 0-based
+ * document index: the number of '---' lines above the container. Only
+ * block-style YAML is read.
+ */
+function containersOf(file, body) {
+  const out = []
+  const lines = body.split(/\r?\n/)
+  let doc = 0, from = 0
+  const scan = (to) => {
+    const part = lines.slice(from, to)
+    if (!WORKLOAD.test(part.join('\n')) || !/^apiVersion:/m.test(part.join('\n'))) return
+    const rows = part.filter((l) => l.trim() && !/^\s*#/.test(l)).map((l) => ({ indent: l.length - l.trimStart().length, text: l.trim() }))
+    rows.forEach((row, i) => {
+      if (!/^containers:\s*(?:#.*)?$/.test(row.text)) return
+      for (const item of listItems(rows, i)) {
+        const name = scalar(item, 'name')
+        const envAt = item.findIndex((r) => r.indent === item.top && /^env:\s*(?:#.*)?$/.test(r.text))
+        const env = new Map(envAt < 0 ? [] : listItems(item, envAt).map((e) => [scalar(e, 'name'), scalar(e, 'value')]))
+        const has = (key) => item.some((r) => r.indent === item.top && new RegExp(`^${key}:`).test(r.text))
+        if (name) out.push({ file, doc, name, image: scalar(item, 'image'), env, command: has('command'), args: has('args') })
+      }
+    })
+  }
+  lines.forEach((line, i) => { if (/^---/.test(line)) { scan(i); doc++; from = i + 1 } })
+  scan(lines.length)
+  return out
+}
+
+/** The items of the block list under rows[at]. Each item is its rows, with `top` = the indent of its keys. */
+function listItems(rows, at) {
+  const items = []
+  let dash = -1
+  for (let i = at + 1; i < rows.length; i++) {
+    const { indent, text: line } = rows[i]
+    const isDash = /^-(?:\s|$)/.test(line)
+    if (dash < 0) { if (!isDash || indent < rows[at].indent) break; dash = indent }
+    if (indent < dash || (indent === dash && !isDash)) break
+    if (indent === dash) {
+      const rest = line.slice(1), trimmed = rest.trimStart()
+      const item = trimmed ? [{ indent: indent + 1 + rest.length - trimmed.length, text: trimmed }] : []
+      items.push(Object.assign(item, { top: item[0]?.indent ?? -1 }))
+    } else {
+      const item = items[items.length - 1]
+      if (item.top < 0) item.top = indent
+      item.push(rows[i])
+    }
+  }
+  return items
+}
+
+function scalar(item, key) {
+  const row = item.find((r) => r.indent === item.top && r.text.startsWith(`${key}:`))
+  if (!row) return null
+  const value = row.text.slice(key.length + 1).replace(/\s+#.*$/, '').trim()
+  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 ------------------------------------------------------------------
+
+/**
+ * Reads repo files once. Missing files read as null. Files over 1 MB read as
+ * null too, with a problem unless `quiet` (for files that are only scanned).
+ */
+function reader(ws, problems) {
+  const cache = new Map()
+  return (path, quiet = false) => {
+    if (!cache.has(path)) {
+      let body = null, big = false
+      try { big = (ws.stat(path)?.size ?? 0) > MAX_BYTES; body = big ? null : ws.read(path) } catch { body = null }
+      cache.set(path, { body, big, told: false })
+    }
+    const entry = cache.get(path)
+    if (entry.big && !quiet && !entry.told) {
+      entry.told = true
+      problems.push({ code: 'file-too-large', message: `${path} is larger than 1 MB. This tool did not read it.` })
+    }
+    return entry.body
+  }
+}
+
+const dirOf = (path) => posix.dirname(path)
+const join = (dir, file) => (dir === '.' ? file : `${dir}/${file}`)
+const inside = (dir, path) => dir === '.' || path === dir || path.startsWith(`${dir}/`)
+const where = (dir) => (dir === '.' ? 'the repo root' : dir)
+const text = (value) => (typeof value === 'string' && value.trim() ? value : null)
+const object = (value) => (value && typeof value === 'object' && !Array.isArray(value) ? value : {})
+const byCodePoint = (a, b) => (a < b ? -1 : a > b ? 1 : 0)
+function json(body) {
+  try { const value = JSON.parse(body ?? ''); return value && typeof value === 'object' && !Array.isArray(value) ? value : null } catch { return null }
+}