@uknows/setup 0.0.0-stage → 0.1.0

package/lib/existing.mjs

@@ -0,0 +1,168 @@
+// OpenTelemetry and other APM agents already in 1 service, from its manifests and Dockerfile.
+// Sentry counts only when its tracing is on, so for Sentry this also reads the source files.
+import { TROUBLESHOOTING } from './contract.mjs'
+
+const at = (dir, name) => (dir === '.' ? name : `${dir}/${name}`)
+
+/** Manifest name -> ecosystem. */
+const ECOSYSTEM = [
+  [/^package\.json$/, 'node'], [/^(requirements[\w.-]*\.txt|pyproject\.toml|Pipfile)$/, 'python'], [/\.csproj$/, 'dotnet'],
+  [/^(pom\.xml|build\.gradle(\.kts)?)$/, 'java'], [/^go\.mod$/, 'go'], [/^composer\.json$/, 'php'], [/^Gemfile$/, 'ruby'],
+]
+
+/** Per ecosystem: OpenTelemetry at SDK level (never the API package alone), other APM agents, and Sentry. */
+const RULES = {
+  node: { otel: /^(@opentelemetry\/(sdk-node|sdk-trace-.+|auto-instrumentations-node|exporter-trace-otlp-.+)|@vercel\/otel)$/,
+    apm: { Datadog: /^dd-trace$/, 'New Relic': /^newrelic$/, 'Elastic APM': /^elastic-apm-node$/,
+      'Azure Monitor': /^(applicationinsights|@azure\/monitor-opentelemetry.*)$/, Dynatrace: /^@dynatrace\//, Instana: /^@instana\/collector$/ },
+    sentry: /^@sentry\// },
+  python: { otel: /^opentelemetry-(sdk|distro|instrumentation.*)$/,
+    apm: { Datadog: /^ddtrace$/, 'New Relic': /^newrelic$/, 'Elastic APM': /^elastic-apm$/,
+      'Azure Monitor': /^(azure-monitor-opentelemetry.*|opencensus-ext-azure)$/ },
+    sentry: /^sentry-sdk$/ },
+  dotnet: { otel: /^OpenTelemetry(\.Extensions\.Hosting|\.AutoInstrumentation|\.Exporter\..+)?$/i,
+    apm: { Datadog: /^Datadog\.Trace/i, 'New Relic': /^NewRelic\./i, 'Elastic APM': /^Elastic\.Apm/i,
+      'Azure Monitor': /^(Microsoft\.ApplicationInsights|Azure\.Monitor\.OpenTelemetry)/i },
+    sentry: /^Sentry(\.|$)/ },
+  java: { otel: /^io\.opentelemetry[\w.]*:opentelemetry-[\w-]*(sdk|starter|exporter|javaagent)/,
+    apm: { Datadog: /^com\.datadoghq:dd-/, 'New Relic': /^com\.newrelic\./, 'Elastic APM': /^co\.elastic\.apm:/,
+      'Azure Monitor': /^(com\.microsoft\.azure:applicationinsights-|com\.azure:azure-monitor-opentelemetry)/ },
+    sentry: /^io\.sentry:/ },
+  go: { otel: /^go\.opentelemetry\.io\/otel\/sdk(\/|$)/,
+    apm: { Datadog: /dd-trace-go/, 'New Relic': /^github\.com\/newrelic\/go-agent/, 'Elastic APM': /^go\.elastic\.co\/apm/ },
+    sentry: /^github\.com\/getsentry\/sentry-go/ },
+  php: { otel: /^open-telemetry\/sdk$/,
+    apm: { Datadog: /^datadog\//, 'New Relic': /newrelic/, 'Elastic APM': /^elastic\/apm-agent/ }, sentry: /^sentry\// },
+  ruby: { otel: /^opentelemetry-sdk$/,
+    apm: { Datadog: /^(ddtrace|datadog)$/, 'New Relic': /^newrelic_rpm$/, 'Elastic APM': /^elastic-apm$/,
+      'Scout APM': /^scout_apm$/, Skylight: /^skylight$/ },
+    sentry: /^sentry-(ruby|rails|raven)$/ },
+}
+
+/** Agents that a Dockerfile loads (comment lines are ignored). */
+const DOCKER_APM = { Datadog: /\bdd-trace\b|\bddtrace(-run)?\b|dd-java-agent|datadog-dotnet-apm|datadog-setup\.php/,
+  'New Relic': /\bnewrelic(-admin|\.jar|-php5?)?\b/i, 'Elastic APM': /elastic-apm-agent|elastic-apm-node|\belasticapm\b/i,
+  'Azure Monitor': /applicationinsights-agent/i, Dynatrace: /\bdynatrace\b|\boneagent\b/i, Instana: /\binstana\b/i }
+const DOCKER_OTEL = /-javaagent:\S*opentelemetry/
+const TRACING = /tracesSampleRate|traces_sample_rate|TracesSampleRate|enableTracing|traces-sample-rate|tracesSampler|traces_sampler/
+const SOURCE = /\.(m?[jt]sx?|c[jt]s|py|cs|rb|go|php|java|kt|properties|ya?ml|json|exs?)$/
+const LOCKS = /(^|\/)(package-lock|npm-shrinkwrap|composer\.lock|packages\.lock)\.json$/
+
+/**
+ * @param {import('./types.mjs').Service} service
+ * @param {import('./workspace.mjs').Workspace} ws
+ * @returns {import('./types.mjs').Existing}
+ */
+export function findExisting(service, ws) {
+  const otel = [], apm = new Map(), sentry = []
+  const add = (vendor, evidence) => {
+    const list = apm.get(vendor) ?? apm.set(vendor, []).get(vendor)
+    if (!list.some((e) => e.file === evidence.file && e.what === evidence.what)) list.push(evidence)
+  }
+  const manifests = new Set(service.manifests)
+  for (const name of ws.list(service.dir)) if (ECOSYSTEM.some(([re]) => re.test(name))) manifests.add(at(service.dir, name))
+  for (const file of [...manifests].sort()) {
+    const text = ws.read(file)
+    const eco = ECOSYSTEM.find(([re]) => re.test(file.split('/').pop()))?.[1]
+    if (text === null || !eco) continue
+    const rules = RULES[eco]
+    for (const { name, line } of dependencies(file, text)) {
+      const evidence = { file, line, what: name }
+      if (rules.otel.test(name)) otel.push(evidence)
+      for (const [vendor, re] of Object.entries(rules.apm)) if (re.test(name)) add(vendor, evidence)
+      if (rules.sentry.test(name)) sentry.push(evidence)
+    }
+  }
+  const dockerfile = (service.dockerfile && ws.read(service.dockerfile)) || ''
+  dockerfile.split('\n').forEach((text, i) => {
+    const found = (re) => (/^\s*#/.test(text) || !re.test(text) ? null : { file: service.dockerfile, line: i + 1, what: re.exec(text)[0] })
+    for (const [vendor, re] of Object.entries(DOCKER_APM)) if (found(re)) add(vendor, found(re))
+    if (found(DOCKER_OTEL)) otel.push(found(DOCKER_OTEL))
+  })
+  if (sentry.length) {
+    const hit = tracingIn(service, ws)
+    if (hit) for (const evidence of [...sentry, hit]) add('Sentry', evidence)
+  }
+  return { otel, apm: [...apm].map(([vendor, evidence]) => ({ vendor, evidence })) }
+}
+
+/**
+ * Why the run stops for a service with another APM agent, and the options.
+ * @param {import('./types.mjs').Service} service
+ * @param {import('./types.mjs').Apm[]} apm
+ * @returns {import('./types.mjs').Block}
+ */
+export function explainApm(service, apm) {
+  const vendors = [...new Set(apm.map((a) => a.vendor))]
+  const names = vendors.length > 1 ? `${vendors.slice(0, -1).join(', ')} and ${vendors.at(-1)}` : vendors[0]
+  const steps = TROUBLESHOOTING.find((t) => t.id === 'other-apm')?.steps ?? []
+  return {
+    title: `${service.dir === '.' ? 'This app' : service.dir} already uses ${names}`,
+    lines: [...apm.flatMap((a) => a.evidence.map((e) => `Found ${e.what} in ${e.file}${e.line ? ` line ${e.line}` : ''}.`)),
+      ...steps, 'Then run npx @uknows/setup again.'],
+  }
+}
+
+/** Package names a manifest lists, with 1-based lines. */
+export function dependencies(file, text) {
+  const base = file.split('/').pop()
+  const lines = text.split('\n')
+  const lineOf = (needle) => lines.findIndex((l) => l.includes(needle)) + 1 || undefined
+  const out = []
+  const push = (name, line) => { if (name && !out.some((d) => d.name === name)) out.push({ name, line }) }
+  if (base === 'package.json' || base === 'composer.json') {
+    let json
+    try { json = JSON.parse(text) } catch { return out }
+    const groups = base === 'package.json' ? ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'] : ['require', 'require-dev']
+    for (const group of groups) {
+      for (const name of Object.keys(json?.[group] ?? {})) push(name, lineOf(`${JSON.stringify(name)}`))
+    }
+  } else if (/\.csproj$/.test(base)) {
+    for (const m of text.matchAll(/<PackageReference\s[^>]*?Include\s*=\s*"([^"]+)"/gi)) push(m[1], lineOf(m[0]))
+  } else if (base === 'pom.xml') {
+    for (const m of text.matchAll(/<dependency>([\s\S]*?)<\/dependency>/g)) {
+      const group = /<groupId>\s*([^<\s]+)/.exec(m[1])?.[1], artifact = /<artifactId>\s*([^<\s]+)/.exec(m[1])?.[1]
+      if (group && artifact) push(`${group}:${artifact}`, lineOf(`<artifactId>${artifact}`))
+    }
+  } else if (/^build\.gradle/.test(base)) {
+    for (const m of text.matchAll(/['"]([\w.-]+):([\w.-]+)(?::[^'"]*)?['"]/g)) push(`${m[1]}:${m[2]}`, lineOf(m[0]))
+  } else if (base === 'go.mod') {
+    lines.forEach((l, i) => { const m = /^\s*(?:require\s+)?([\w.-]+\.[\w-]+\/\S+)\s+v\d/.exec(l); if (m) push(m[1], i + 1) })
+  } else if (base === 'Gemfile') {
+    lines.forEach((l, i) => { const m = /^\s*gem\s*\(?\s*["']([^"']+)["']/.exec(l); if (m) push(m[1], i + 1) })
+  } else if (/\.txt$/.test(base)) {
+    lines.forEach((l, i) => { const m = /^\s*([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(l.replace(/#.*/, '')); if (m) push(pyName(m[1]), i + 1) })
+  } else {
+    // pyproject.toml and Pipfile: dependency arrays and dependency tables.
+    let table = '', array = false
+    lines.forEach((raw, i) => {
+      const l = raw.replace(/\s#.*$/, '')
+      const closes = () => l.replace(/"[^"]*"|'[^']*'/g, '').includes(']')
+      const quoted = () => { for (const m of l.matchAll(/["']([A-Za-z0-9][A-Za-z0-9._-]*)[^"']*["']/g)) push(pyName(m[1]), i + 1) }
+      if (array) { quoted(); array = !closes(); return }
+      const header = /^\s*\[+([^\]]+)\]/.exec(l)
+      if (header) { table = header[1]; return }
+      const kv = /^\s*["']?([A-Za-z0-9_.-]+)["']?\s*=\s*(.*)$/.exec(l)
+      if (!kv) return
+      if (kv[2].startsWith('[')) {
+        if (/dependencies|requires/.test(kv[1]) || /dependencies|dependency-groups/.test(table)) { quoted(); array = !closes() }
+      } else if (/dependencies|packages/.test(table) && kv[1] !== 'python') push(pyName(kv[1]), i + 1)
+    })
+  }
+  return out
+}
+
+const pyName = (name) => name.toLowerCase().replace(/[-_.]+/g, '-')
+
+/** The first source line that turns Sentry tracing on, as evidence. */
+function tracingIn(service, ws) {
+  let count = 0
+  for (const file of ws.files(service.dir)) {
+    if (!SOURCE.test(file) || LOCKS.test(file) || ++count > 5000) continue
+    if ((ws.stat(file)?.size ?? 0) > 1_000_000) continue
+    const text = ws.read(file) ?? ''
+    const m = TRACING.exec(text)
+    if (m) return { file, line: text.slice(0, m.index).split('\n').length, what: `Sentry tracing (${m[0]})` }
+  }
+  return null
+}

package/lib/git.mjs

@@ -0,0 +1,47 @@
+/*
+ * The dirty-tree check. Setup refuses to edit a repo with uncommitted
+ * changes (untracked files count), so the user can review exactly what this
+ * tool changed with git diff. Paths that an earlier setup run changed are
+ * ignored, so running setup again before a commit works.
+ */
+import { spawnSync } from 'node:child_process'
+import { readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * @param {string} root  absolute path of the folder setup works in
+ * @param {Set<string>} ignore  repo-relative paths to leave out
+ * @returns {{git: boolean, repo: boolean, paths: string[]}}  paths are relative to root, '/' separated
+ */
+export function gitStatus(root, ignore = new Set()) {
+  const run = (...args) => spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+  const prefix = run('rev-parse', '--show-prefix')
+  if (prefix.error) return { git: false, repo: false, paths: [] }
+  if (prefix.status !== 0) return { git: true, repo: false, paths: [] }
+  const status = run('status', '--porcelain=v1', '-z', '--untracked-files=normal', '--', '.')
+  if (status.status !== 0) return { git: true, repo: false, paths: [] }
+  const base = prefix.stdout.trim()
+  const tokens = status.stdout.split('\0')
+  const paths = []
+  for (let i = 0; i < tokens.length; i++) {
+    const entry = tokens[i]
+    if (entry.length < 4) continue
+    if (entry[0] === 'R' || entry[0] === 'C') i++ // the next token is the old path
+    const path = entry.slice(3).startsWith(base) ? entry.slice(3 + base.length) : entry.slice(3)
+    if (ignore.has(path) || (path.endsWith('/') && onlyIgnored(root, path.slice(0, -1), ignore))) continue
+    paths.push(path)
+  }
+  return { git: true, repo: true, paths }
+}
+
+/** True when every file under an untracked folder is in ignore. */
+function onlyIgnored(root, dir, ignore, budget = { left: 2000 }) {
+  let entries
+  try { entries = readdirSync(join(root, ...dir.split('/')), { withFileTypes: true }) } catch { return false }
+  for (const entry of entries) {
+    if (--budget.left < 0) return false
+    const path = `${dir}/${entry.name}`
+    if (entry.isDirectory() ? !onlyIgnored(root, path, ignore, budget) : !ignore.has(path)) return false
+  }
+  return true
+}

package/lib/hosts.mjs

@@ -0,0 +1,145 @@
+/*
+ * Where the app runs, read from deploy files in the repo, and the "set your
+ * key once" steps for those hosts. Source cues and precedence come from
+ * instrumentation/agents/setup-cli/lib/hosting.mjs. Environment variables of
+ * this computer are never used: the CLI runs on a laptop, not on the host.
+ */
+import { DOCS_URL, HOSTS, SETTINGS_FILE, SETTINGS_FILE_LOADERS } from './contract.mjs'
+
+const MAX_BYTES = 262144
+const RUNTIME = ['azure-container-apps', 'azure-app-service', 'aws-ecs', 'kubernetes', 'alibaba-sae', 'vm-docker']
+/** hosting.mjs adapter ids -> docs host ids. */
+const DOCS_ID = { 'azure-aca': 'azure-container-apps', 'azure-app-service': 'azure-app-service', 'aws-ecs': 'aws-ecs',
+  kubernetes: 'kubernetes', 'alibaba-ack': 'kubernetes',
+  'alibaba-sae': 'alibaba-sae', 'alibaba-ecs': 'vm-docker', vm: 'vm-docker', docker: 'vm-docker' }
+
+const DOCKERFILE = /(?:^|\/)(?:Dockerfile(?:\.[^/]+)?|[^/]+\.[Dd]ockerfile)$/
+const COMPOSE = /(?:^|\/)(?:docker-)?compose(?:\.[^/]+)?\.ya?ml$/
+/** Compose files for local work, by file name (compose.dev.yaml) or folder (local/compose.yaml). They are not deploy targets. */
+const COMPOSE_DEV = /(?:^|[./-])(?:dev|development|local|test|tests|ci|override|sandbox|example|examples)(?:\.ya?ml$|\/)/
+const YAML = /\.ya?ml$/
+const SCRIPT = /\.(?:ya?ml|sh|ps1)$/
+const TF = /\.tf$/
+const API = /^[ \t]*apiVersion[ \t]*:/m
+const WORKFLOW = /^(?:\.\.\/)*\.github\/workflows\/[^/]+\.ya?ml$/
+const DEPLOY_CUE = /deploy(?![._-]?tests?\b)|kubectl|containerapp|webapp|docker push|aliyun|aws ecs|helm upgrade/i
+/** An ECS task definition file: a JSON file with containerDefinitions. */
+const TASK_DEF = /(?:^|\/)[^/]*task[-_.]?def(?:inition)?[^/]*\.json$/i
+
+/** [adapter, evidence text, path test or null for any file, regexes that must all match]. The first regex gives the line. */
+const RULES = [
+  ['docker', 'Dockerfile builds an image', DOCKERFILE, /^[ \t]*FROM[ \t]+\S+/im],
+  ['docker', 'Docker Compose services', COMPOSE, /^services[ \t]*:/m],
+  ['kubernetes', 'Kubernetes workload', YAML, /^[ \t]*kind[ \t]*:[ \t]*['"]?(?:Deployment|StatefulSet|DaemonSet|Pod|Job|CronJob)['"]?[ \t]*$/m, API],
+  ['kubernetes', 'Helm chart', /(?:^|\/)Chart\.ya?ml$/, API, /^[ \t]*name[ \t]*:/m],
+  ['kubernetes', 'Deploy step runs kubectl or helm', SCRIPT, /\bkubectl[ \t]+(?:apply|set[ \t]+image|rollout)\b|\bhelm[ \t]+(?:upgrade|install)\b/],
+  ['vm', 'systemd service', /\.service$/, /^[ \t]*ExecStart[ \t]*=/m, /^[ \t]*\[Service\][ \t]*$/m],
+  ['vm', 'cloud-init config', null, /^#cloud-config\b/m, /^[ \t]*(?:runcmd|bootcmd|write_files)[ \t]*:/m],
+  ['azure-aca', 'Azure Container App in Terraform', TF, /\bresource\s+"azurerm_container_app"\s+"[^"\r\n]+"/],
+  ['azure-aca', 'Azure Container App in Bicep or ARM', null, /Microsoft\.App\/containerApps(?:@|["'\s])/],
+  ['azure-aca', 'Azure Container Apps deploy action', null, /azure\/container-apps-deploy-action@/],
+  ['azure-aca', 'azure.yaml deploys to Container Apps', /(?:^|\/)azure\.ya?ml$/, /^[ \t]*host[ \t]*:[ \t]*['"]?containerapp\b/m],
+  ['azure-aca', 'Deploy step runs az containerapp', SCRIPT, /\baz[ \t]+containerapp[ \t]+(?:create|update|up|revision)\b/],
+  ['azure-app-service', 'Azure App Service in Terraform', TF, /\bresource\s+"azurerm_(?:linux_web_app|windows_web_app|app_service)"\s+"[^"\r\n]+"/],
+  ['azure-app-service', 'Azure App Service in Bicep or ARM', null, /Microsoft\.Web\/sites(?:@|["'\s])/],
+  ['azure-app-service', 'Azure App Service deploy action', null, /azure\/webapps-deploy@/],
+  ['azure-app-service', 'azure.yaml deploys to App Service', /(?:^|\/)azure\.ya?ml$/, /^[ \t]*host[ \t]*:[ \t]*['"]?appservice\b/m],
+  ['azure-app-service', 'Deploy step runs az webapp', SCRIPT, /\baz[ \t]+webapp[ \t]+(?:create|up|deploy|config[ \t]+(?:container|appsettings))\b/],
+  ['aws-ecs', 'AWS ECS in Terraform', TF, /\bresource\s+"aws_ecs_(?:service|task_definition)"\s+"[^"\r\n]+"/],
+  ['aws-ecs', 'AWS ECS in CloudFormation or CDK output', null, /\bAWS::ECS::(?:TaskDefinition|Service)\b/],
+  ['aws-ecs', 'ECS task definition', TASK_DEF, /"containerDefinitions"\s*:/],
+  ['aws-ecs', 'ECS deploy action', null, /aws-actions\/amazon-ecs-deploy-task-definition@/],
+  ['aws-ecs', 'Deploy step runs aws ecs', SCRIPT, /\baws[ \t]+ecs[ \t]+(?:update-service|create-service|register-task-definition|deploy)\b/],
+  ['aws-ecs', 'AWS Copilot service manifest', /(?:^|\/)copilot\/[^/]+\/manifest\.ya?ml$/, /^[ \t]*type[ \t]*:[ \t]*['"]?(?:Load Balanced Web Service|Backend Service|Worker Service)/m],
+  ['alibaba-ecs', 'Alibaba ECS instance in Terraform', TF, /\bresource\s+"alicloud_instance"\s+"[^"\r\n]+"/],
+  ['alibaba-ack', 'Alibaba ACK cluster in Terraform', TF, /\bresource\s+"alicloud_cs_(?:managed_kubernetes|kubernetes)"\s+"[^"\r\n]+"/],
+  ['alibaba-ack', 'Alibaba Cloud settings in a Kubernetes file', YAML, /(?:alibabacloud\.com|aliyun\.com)\//, API],
+  ['alibaba-sae', 'Alibaba SAE application in Terraform', TF, /\bresource\s+"alicloud_sae_application"/],
+  ['alibaba-sae', 'Alibaba SAE address', null, /\bsae\.(?:[a-z0-9-]+\.)?aliyuncs\.com\b/],
+  ['alibaba-sae', 'Deploy step runs aliyun sae', SCRIPT, /\baliyun[ \t]+sae\b/],
+]
+
+const deployFile = (path) => DOCKERFILE.test(path) || /\.(?:ya?ml|tf|bicep|service|sh|ps1)$/.test(path) || TASK_DEF.test(path)
+  || /(?:^|\/)(?:containerapp|azure-container-app|azuredeploy|template|ecs|ack|sae|webapp|appservice)\.json$/.test(path)
+
+/**
+ * Where the app runs, from deploy files in the repo.
+ * @param {Pick<import('./workspace.mjs').Workspace, 'files'|'read'|'stat'>} ws  Paths may start with '../' (files above a --path folder).
+ * @returns {import('./types.mjs').Host[]}
+ */
+export function detectHosts(ws) {
+  /** @type {Map<string, {evidence: import('./types.mjs').Evidence[], buildOnly: boolean}>} */
+  const seen = new Map()
+  const cue = (adapter, file, line, what) => {
+    if (!seen.has(adapter)) seen.set(adapter, { evidence: [], buildOnly: true })
+    const entry = seen.get(adapter)
+    if (!entry.evidence.some((e) => e.file === file && e.what === what)) entry.evidence.push({ file, line, what })
+    if (what !== RULES[0][1]) entry.buildOnly = false
+  }
+  for (const file of ws.files()) {
+    if (!deployFile(file) || /(?:^|\/)pnpm-lock\.ya?ml$/.test(file)) continue
+    let body = null
+    try { body = (ws.stat(file)?.size ?? 0) <= MAX_BYTES ? ws.read(file) : null } catch { body = null }
+    if (!body) continue
+    // Comment lines never count, so a commented-out resource is not a host. Line numbers stay the same.
+    const code = body.replace(/^[ \t]*(?:#(?!cloud-config\b)|\/\/).*$/gm, '')
+    for (const [adapter, what, path, ...need] of RULES) {
+      if ((path && !path.test(file)) || (adapter === 'docker' && COMPOSE.test(file) && COMPOSE_DEV.test(file))) continue
+      if (need.every((re) => re.test(code))) cue(adapter, file, lineOf(code, need[0]), what)
+    }
+    if (WORKFLOW.test(file) && /^jobs[ \t]*:/m.test(code) && DEPLOY_CUE.test(code)) {
+      cue('github-actions', file, lineOf(code, DEPLOY_CUE), 'GitHub Actions workflow that deploys')
+    }
+  }
+  // A Dockerfile is a build, not a host of its own: it does not compete with a real deploy target.
+  const runtime = [...seen.keys()].filter((id) => id !== 'github-actions')
+  if (seen.get('docker')?.buildOnly && runtime.some((id) => id !== 'docker')) seen.delete('docker')
+  const hosts = []
+  for (const id of RUNTIME) {
+    const evidence = [...seen].filter(([adapter]) => DOCS_ID[adapter] === id).flatMap(([, entry]) => entry.evidence)
+    if (evidence.length) hosts.push({ id, evidence: evidence.sort(byStrength) })
+  }
+  if (!hosts.length) hosts.push({ id: 'vm-docker', evidence: [] })
+  if (seen.has('github-actions')) hosts.push({ id: 'github-actions', evidence: seen.get('github-actions').evidence })
+  return hosts
+}
+
+/**
+ * The 'set your key once' steps for the detected hosts, from contract HOSTS.
+ * envFile: true when a service got otel.env, so the steps also say how to load it.
+ * Fields are read defensively: the docs file keeps changing.
+ * @param {import('./types.mjs').Host[]} hosts
+ * @param {{envFile?: boolean}} [options]
+ * @returns {import('./types.mjs').Block[]}
+ */
+export function keySteps(hosts, options = {}) {
+  const ids = [...new Set((Array.isArray(hosts) ? hosts : []).map((h) => h?.id))]
+  const blocks = []
+  for (const id of ids) {
+    const host = (Array.isArray(HOSTS) ? HOSTS : []).find((h) => h?.id === id)
+    if (!host) continue
+    const lines = [...strings(host.steps), ...strings(host.notes)]
+    if (typeof host.stricter?.title === 'string') lines.push(`${host.stricter.title}. See ${DOCS_URL}.`)
+    blocks.push({ title: `Set your key once: ${host.label ?? id}`, lines, snippets: snippets(host.snippets) })
+  }
+  if (options.envFile) {
+    const loaders = (Array.isArray(SETTINGS_FILE_LOADERS) ? SETTINGS_FILE_LOADERS : [])
+      .filter((l) => l && (l.id !== 'alibaba-sae' || ids.includes('alibaba-sae')))
+    blocks.push({ title: `Load ${SETTINGS_FILE?.path ?? 'otel.env'} when your app starts`,
+      lines: loaders.filter((l) => l.summary).map((l) => `${l.label ?? l.id}: ${l.summary}`),
+      snippets: snippets(loaders.map((l) => l.snippet)) })
+  }
+  return blocks
+}
+
+/** Deploy files before deploy steps (RULES order), then by path and line. */
+const rank = (e) => RULES.findIndex((rule) => rule[1] === e.what)
+const byStrength = (a, b) => rank(a) - rank(b) || (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line)
+const strings = (list) => (Array.isArray(list) ? list.filter((s) => typeof s === 'string') : [])
+const snippets = (list) => (Array.isArray(list) ? list : [])
+  .filter((s) => s && typeof s.code === 'string')
+  .map((s) => ({ caption: String(s.caption ?? ''), language: String(s.language ?? 'text'), code: s.code }))
+const lineOf = (body, re) => {
+  const m = new RegExp(re.source, re.flags.replace('g', '')).exec(body)
+  return m ? body.slice(0, m.index).split('\n').length : 1
+}

package/lib/manifest.mjs

@@ -0,0 +1,112 @@
+/*
+ * .uknows/setup.json: what setup changed, so remove can undo it exactly.
+ * It keeps hashes and the changed lines only, never whole files, so it
+ * cannot copy a secret that is already in the repo.
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { CLI, PINS } from './contract.mjs'
+import { hunks, reverseAt, reverseByContent, splitLines } from './diff.mjs'
+import { checkPath } from './workspace.mjs'
+
+export const TOOL = '@uknows/setup'
+export const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+export const BOM = '\uFEFF'
+const NOTE = 'Written by npx @uknows/setup. To undo these changes, run npx @uknows/setup remove. This file has no secrets.'
+const STACKS = ['node', 'python', 'dotnet', 'java', 'go', 'php', 'ruby', 'otel']
+const UNDO = { npm: 'uninstall', pnpm: 'remove', yarn: 'remove' }
+/** The only flags an undo command may have: the ones setup itself writes. Everything else must be a package setup adds. */
+const UNDO_FLAGS = new Set(['-w', '--no-package-lock', '--package-lock-only', '--lockfile-only', '--ignore-scripts', '--mode=skip-build'])
+const PACKAGES = new Set([...PINS.node.packages, PINS.node.esmPackage])
+const SHA = /^[0-9a-f]{64}$/
+
+/** @param {Buffer|null} bytes */
+export const sha256 = (bytes) => (bytes === null ? null : createHash('sha256').update(bytes).digest('hex'))
+
+/**
+ * The manifest of the repo at root, or null. Throws when it is not valid.
+ * The file comes from the repo, so it is checked before remove trusts it:
+ * paths stay inside the repo and undo commands only remove packages.
+ */
+export function readManifest(root) {
+  const file = join(root, ...CLI.manifest.split('/'))
+  if (!existsSync(file)) return null
+  let data = null
+  try { data = JSON.parse(readFileSync(file, 'utf8')) } catch { /* reported below */ }
+  if (!valid(data)) throw new Error(`${CLI.manifest} is not valid. Fix it or delete it.`)
+  return data
+}
+
+function valid(m) {
+  try {
+    if (m?.schema !== 1 || ![m.services, m.changes, m.packages].every(Array.isArray)) return false
+    for (const s of m.services) { checkPath(s.dir); if (!STACKS.includes(s.stack)) return false }
+    for (const c of m.changes) {
+      checkPath(c.file)
+      if (!c.hunks.every((h) => Number.isInteger(h.at) && [...h.before, ...h.after].every((l) => typeof l === 'string'))) return false
+    }
+    for (const p of m.packages) {
+      checkPath(p.cwd)
+      p.touches.forEach(checkPath)
+      // Only the exact packages that setup added, never other flags (-g, --prefix) or other packages.
+      const [cmd, verb, ...rest] = p.undo
+      const names = rest.filter((arg) => !UNDO_FLAGS.has(arg))
+      if (UNDO[cmd] !== verb || p.cmd !== cmd || !Array.isArray(p.added) || !names.length || new Set(names).size !== names.length
+        || !names.every((name) => PACKAGES.has(name)) || names.length !== p.added.length || !p.added.every((name) => names.includes(name))) return false
+      // before: the sha256 of each file the package manager touched, as it was before that run. Optional.
+      for (const [file, sha] of Object.entries(p.before ?? {})) { checkPath(file); if (sha !== null && !SHA.test(sha)) return false }
+    }
+    return true
+  } catch {
+    return false
+  }
+}
+
+export const manifestText = (manifest) => `${JSON.stringify(manifest, null, 2)}\n`
+
+/**
+ * The record of 1 text edit. Hashes cover the bytes on disk, BOM included.
+ * Hunks are on the text without BOM.
+ */
+export function changeEntry({ file, before, after, bom }, beforeBytes, afterBytes) {
+  return { file, created: before === null, bom, beforeSha256: sha256(beforeBytes), afterSha256: sha256(afterBytes),
+    hunks: before === null ? [] : hunks(before, after) }
+}
+
+/** Add 1 run to a manifest (or start one). Services are merged by dir. */
+export function mergeManifest(old, { services, changes, packages }) {
+  const kept = (old?.services ?? []).filter((s) => !services.some((n) => n.dir === s.dir))
+  return { schema: 1, tool: TOOL, version: VERSION, note: NOTE,
+    services: [...kept, ...services].sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0)),
+    changes: [...(old?.changes ?? []), ...changes], packages: [...(old?.packages ?? []), ...packages] }
+}
+
+/** Paths the dirty-tree check ignores: the manifest and every path it lists. */
+export function manifestPaths(manifest) {
+  const paths = new Set([CLI.manifest])
+  for (const c of manifest?.changes ?? []) paths.add(c.file)
+  for (const p of manifest?.packages ?? []) for (const t of p.touches ?? []) paths.add(t)
+  return paths
+}
+
+/**
+ * How to undo 1 change, given the bytes on disk now (null = missing).
+ * Returns {bytes} to write, {bytes: null} to delete, or {reason} to skip.
+ */
+export function undoChange(entry, current) {
+  if (current === null) return { reason: 'The file is gone.' }
+  const sha = sha256(current)
+  if (entry.created) return sha === entry.afterSha256 ? { bytes: null } : { reason: 'The file changed after setup.' }
+  let text = current.toString('utf8')
+  const bom = text.startsWith(BOM)
+  if (bom) text = text.slice(1)
+  const lines = splitLines(text)
+  const pack = (out) => Buffer.from((bom ? BOM : '') + out.join(''), 'utf8')
+  if (sha === entry.afterSha256) {
+    const out = reverseAt(lines, entry.hunks)
+    if (out && sha256(pack(out)) === entry.beforeSha256) return { bytes: pack(out) }
+  }
+  const out = reverseByContent(lines, entry.hunks)
+  return out ? { bytes: pack(out) } : { reason: 'The lines that setup added changed, so they cannot be found exactly once.' }
+}