@uknows/setup 0.0.0-stage → 0.1.0

package/lib/engine.mjs

@@ -0,0 +1,607 @@
+/*
+ * The setup and remove flows. Everything that reads the repo, runs a
+ * program or asks the user comes in through deps, so tests can use fakes.
+ * Each flow returns {code, report}: the exit code and the --json report.
+ */
+import { spawn as spawnChild } from 'node:child_process'
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs'
+import { dirname, sep } from 'node:path'
+import { runCheck } from './check.mjs'
+import { CLI, EXAMPLE_SERVICE, INGEST_ENDPOINT, SECRET } from './contract.mjs'
+import { detect } from './detect.mjs'
+import { docsUrl, llmsUrl } from './endpoint.mjs'
+import { countLines, unified } from './diff.mjs'
+import { shellWords } from './doc.mjs'
+import { explainApm, findExisting } from './existing.mjs'
+import { gitStatus } from './git.mjs'
+import { keySteps } from './hosts.mjs'
+import { BOM, TOOL, VERSION, changeEntry, manifestPaths, manifestText, mergeManifest, readManifest, sha256, undoChange } from './manifest.mjs'
+import { hasKey, redactKey, settingsPlan } from './settings.mjs'
+import { APPLIERS } from './stacks/index.mjs'
+import { UsageError, frameworkLabel, hostLabel, list, plural, stackLabel, unique } from './ui.mjs'
+import { createWorkspace, repoView } from './workspace.mjs'
+
+const DEFAULTS = { detect, findExisting, explainApm, settingsPlan, keySteps, appliers: APPLIERS, spawn: runCommand, gitStatus, createWorkspace, runCheck }
+/** The language menu, in this order, then 'Something else'. */
+const MENU = ['node', 'python', 'java', 'dotnet', 'go', 'php', 'ruby', 'otel']
+const LOCKFILES = new Set(['package-lock.json', 'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock'])
+const DIFF_LIMIT = 200
+/** On Windows, package managers run through a shell (.cmd files), so every argument must be plain. */
+const SAFE_ARG = /^[@A-Za-z0-9._/=:~+-]+$/
+
+/**
+ * @param {{root: string, dryRun?: boolean, yes?: boolean, all?: boolean, json?: boolean, serviceName?: string|null, force?: boolean}} opts
+ * @param {Partial<typeof DEFAULTS> & {ui: ReturnType<typeof import('./ui.mjs').createUI>}} deps
+ */
+export async function runSetup(opts, deps) {
+  const d = { ...DEFAULTS, ...deps }
+  const report = { schema: 1, tool: TOOL, version: VERSION, command: 'setup', status: 'failed', exitCode: 1,
+    services: [], files: [], hosts: [], keySteps: [], check: null, problems: [], next: CLI.next }
+  return guard(d.ui, report, () => setup(opts, d, report))
+}
+
+/** @param {{root: string, yes?: boolean, json?: boolean, force?: boolean}} opts */
+export async function runRemove(opts, deps) {
+  const d = { ...DEFAULTS, ...deps }
+  const report = { schema: 1, tool: TOOL, version: VERSION, command: 'remove', status: 'failed', exitCode: 1, files: [], commands: [], problems: [] }
+  return guard(d.ui, report, () => remove(opts, d, report))
+}
+
+async function guard(ui, report, flow) {
+  let result
+  try {
+    result = await flow()
+  } catch (error) {
+    if (error instanceof UsageError) {
+      ui.error(error.message)
+      ui.error('Run uknows-setup --help.')
+      result = ['usage-error', 2]
+    } else {
+      ui.error(`Something went wrong: ${error.message}`)
+      report.problems.push({ code: 'error', message: error.message })
+      result = ['failed', 1]
+    }
+  }
+  report.status = result[0]
+  report.exitCode = result[1]
+  return { code: result[1], report }
+}
+
+async function setup(opts, d, report) {
+  const { ui } = d, root = opts.root
+  // --yes never asks anything, so a script in a terminal cannot hang on a question.
+  const ask = ui.interactive && !opts.yes
+  const manifest = readManifest(root)
+  const detection = d.detect(root)
+  const ws = d.createWorkspace(root)
+  const repo = repoView(ws)
+  const known = (s) => manifest?.services.find((m) => m.dir === s.dir)?.stack
+  report.hosts = detection.hosts
+  report.problems.push(...detection.problems)
+  let services = detection.services.map((s) => ({ ...s }))
+  ui.print('UKNOWS setup')
+  ui.print()
+  const endpoint = opts.endpoint ?? INGEST_ENDPOINT
+  const env = opts.env ?? {}
+  const DOCS_URL = docsUrl(env), LLMS_URL = llmsUrl(env)
+  if (endpoint !== INGEST_ENDPOINT) ui.print(`Note: the settings use the test ingest address ${endpoint} from ${CLI.endpointEnv}.`)
+  for (const p of detection.problems.filter((x) => x.code === 'frontend' || x.code === 'skipped')) ui.print(`Note: ${p.message}`)
+
+  if (services.length > 1) {
+    ui.print(`Found ${services.length} services:`)
+    for (const s of services) ui.print(`  ${s.dir}: ${describe(s)}`)
+    ui.print()
+    if (!opts.all) {
+      if (!ask) {
+        report.services = services.map((s) => serviceReport(s))
+        ui.print(`Pick the services to set up. Use --all to set up all of them, or --path <folder> to set up 1. Or run this in a terminal${opts.yes ? ' without --yes' : ''} to pick from a list.`)
+        return ['needs-selection', 2]
+      }
+      const pick = await ui.choose('Which service do you want to set up?', [...services.map((s) => `${s.dir}: ${describe(s)}`), 'All of them'])
+      if (pick < services.length) services = [services[pick]]
+      ui.print()
+    }
+  } else if (services[0].lang) {
+    ui.print(`Found 1 service: ${describe(services[0], true)}`)
+    ui.print()
+  }
+  if (opts.serviceName && services.length > 1) throw new UsageError('Use --service-name with 1 service only. Use --path to pick that service.')
+
+  // A browser app gets no packages and no settings: OpenTelemetry for Node.js runs in a server.
+  const frontend = (s) => s.problems.some((x) => x.code === 'frontend')
+  if (services.some(frontend)) {
+    for (const s of services.filter(frontend)) {
+      ui.print(`${s.dir === '.' ? 'This folder' : s.dir}: ${s.problems.find((x) => x.code === 'frontend').message} This tool changes nothing here.`)
+    }
+    services = services.filter((s) => !frontend(s))
+    if (!services.length) {
+      report.services = detection.services.map((x) => serviceReport(x))
+      ui.print(`Run this tool in the folder of your server app, or use --path <folder>. To set up UKNOWS by hand, see ${DOCS_URL}`)
+      return ['not-found', 3]
+    }
+    ui.print()
+  }
+
+  // A folder with nothing recognized: ask which stack it uses, or stop.
+  const chosen = new Map()
+  for (const s of services.filter((x) => !x.lang && !known(x))) {
+    if (!ask) {
+      ui.print(`No app found in ${where(s.dir)}.`)
+      ui.print(`Run this tool in the folder of your app, or use --path <folder>. To set up UKNOWS by hand, see ${DOCS_URL}`)
+      report.services = services.map((x) => serviceReport(x))
+      return ['not-found', 3]
+    }
+    const pick = await ui.choose(`No app found in ${where(s.dir)}. What does your app use?`, [...MENU.map(stackLabel), 'Something else'])
+    if (pick === MENU.length) {
+      ui.print(`To set up UKNOWS by hand, see ${DOCS_URL}`)
+      ui.print(`AI coding tools can read the same steps at ${LLMS_URL}`)
+      report.services = services.map((x) => serviceReport(x))
+      return ['not-found', 3]
+    }
+    ui.print()
+    chosen.set(s.dir, MENU[pick])
+    if (MENU[pick] !== 'otel') s.lang = MENU[pick]
+  }
+
+  // Another APM agent in any service stops the whole run before anything is planned.
+  const items = services.map((s) => ({ s, name: opts.serviceName || s.name, existing: d.findExisting(s, ws) }))
+  report.services = items.map((it) => serviceReport(it.s, { name: it.name, otel: it.existing.otel, apm: it.existing.apm }))
+  const blocked = items.filter((it) => it.existing.apm.length)
+  if (blocked.length) {
+    for (const it of blocked) ui.block(d.explainApm(it.s, it.existing.apm))
+    ui.print('Nothing changed.')
+    return ['refused', 1]
+  }
+
+  // Plan each service. All edits go into 1 workspace, so each step reads the edits before it.
+  const plans = []
+  for (const it of items) {
+    const { s } = it
+    const stack = known(s) ?? chosen.get(s.dir) ?? (it.existing.otel.length ? 'otel' : s.lang)
+    const applier = Object.prototype.hasOwnProperty.call(d.appliers, stack) ? d.appliers[stack] : null
+    if (!applier) throw new Error(`This tool has no steps for ${stack}.`)
+    report.problems.push(...s.problems)
+    const ambiguous = s.problems.find((x) => x.code === 'dockerfile-ambiguous')
+    if (ambiguous) {
+      // Editing the wrong Dockerfile changes nothing that ships: say so, and change nothing for this service.
+      const manual = [{ title: 'Pick the Dockerfile you deploy', lines: [ambiguous.message, 'Then run npx @uknows/setup again.'] }]
+      plans.push({ ...it, stack, plan: { summary: [], edits: [], commands: [], extraSettings: [], manual, notes: [] },
+        settings: { target: null, edits: [], summary: [], manual: [], notes: [] }, manual, notes: [] })
+      continue
+    }
+    if ((stack === 'node' || stack === 'python') && !s.start && !s.dockerfile && ask) {
+      const raw = await ui.ask('What command starts this app now? For example: node server.js. Press Enter to skip.')
+      if (raw) s.start = { kind: 'answer', file: '', line: 0, form: 'shell', raw, argv: shellWords(raw) }
+    }
+    const ctx = { ws, repo, name: it.name, detection, endpoint }
+    const plan = applier.plan(s, ctx)
+    for (const edit of plan.edits) ws.stage(edit)
+    const settings = plan.stop ? { target: null, edits: [], summary: [], manual: [], notes: [] } : d.settingsPlan(s, ctx, plan.extraSettings ?? [])
+    for (const edit of settings.edits) ws.stage(edit)
+    plans.push({ ...it, stack, plan, settings, manual: [...plan.manual, ...settings.manual].map(tidy),
+      notes: unique([...plan.notes, ...settings.notes].filter(Boolean)) })
+  }
+  report.services = plans.map((p) => serviceReport(p.s, { stack: p.stack, name: p.name, settings: p.settings.target ?? null,
+    summary: steps(p), commands: p.plan.commands.map((c) => ({ cwd: c.cwd, argv: [c.cmd, ...c.args] })),
+    manual: p.manual, notes: p.notes, otel: p.existing.otel }))
+  report.keySteps = d.keySteps(detection.hosts, { envFile: plans.some((p) => p.settings.target?.kind === 'env-file') })
+  // The docs snippets use an example service name. With 1 service, show its real name.
+  if (plans.length === 1) {
+    for (const snippet of report.keySteps.flatMap((b) => b.snippets ?? [])) snippet.code = snippet.code.split(EXAMPLE_SERVICE).join(plans[0].name)
+  }
+  const changes = ws.changes()
+  // A file that holds a key is never changed, so the key cannot reach the diff or the manifest.
+  const keyed = changes.filter((c) => hasKey(c.before) || hasKey(c.after)).map((c) => c.file)
+  if (keyed.length) {
+    ui.block({ title: 'Remove the key from your repo', lines: [
+      ...keyed.map((file) => `${file} sets ${SECRET.name} to a key. This tool does not change a file that holds a key.`),
+      `Remove ${SECRET.name} from ${keyed.length === 1 ? 'that file' : 'those files'}. ${SECRET.summary}`,
+      'Get a new key. The old key stays in your git history.', 'Then run npx @uknows/setup again.'] })
+    ui.print('Nothing changed.')
+    report.problems.push({ code: 'key-in-repo', message: `${plural(keyed.length, 'file')} that this tool would change ${keyed.length === 1 ? 'holds' : 'hold'} a key.` })
+    return ['refused', 1]
+  }
+  const commands = plans.flatMap((p) => p.plan.commands)
+  const manual = plans.flatMap((p) => p.manual)
+  const exit = manual.length ? 3 : 0
+
+  if (!changes.length && !commands.length) {
+    ui.print(manual.length ? 'Nothing for this tool to change. The steps below are yours.' : 'Already set up. Nothing to change.')
+    printManual(ui, manual)
+    return ['nothing-to-change', exit]
+  }
+  printPlan(ui, plans, detection, changes, commands, opts)
+  if (opts.dryRun || (opts.json && !opts.yes)) {
+    printManual(ui, manual)
+    ui.print('This was a dry run. Nothing changed.')
+    return ['planned', exit]
+  }
+
+  if (!opts.force) {
+    const git = d.gitStatus(root, manifestPaths(manifest))
+    if (!git.repo) {
+      const message = git.git ? 'This folder is not in a git repo. Keep a copy, so you can review what this tool changes.'
+        : 'git is not installed, so this tool cannot check for changes that are not committed.'
+      ui.print(`Note: ${message}`)
+      report.problems.push({ code: 'no-git', message })
+    } else if (git.paths.length) {
+      ui.error('This repo has changes that are not committed:')
+      for (const path of git.paths.slice(0, 10)) ui.error(`  ${path}`)
+      if (git.paths.length > 10) ui.error(`  and ${git.paths.length - 10} more`)
+      ui.error('Commit or stash your changes first, so you can review what this tool changes. Or run again with --force.')
+      report.problems.push({ code: 'dirty-tree', message: `${plural(git.paths.length, 'path')} in the repo are not committed.` })
+      return ['refused', 1]
+    }
+  }
+  if (!opts.yes) {
+    if (!ui.interactive) {
+      ui.print('Run again with --yes to apply.')
+      return ['planned', 2]
+    }
+    if (!(await ui.confirm('Apply? (Y/n)'))) {
+      ui.print('Nothing changed.')
+      return ['planned', 0]
+    }
+  }
+
+  const record = plans.map((p) => ({ dir: p.s.dir, stack: p.stack, name: p.name }))
+  const saved = await apply({ root, ws, changes, commands, manifest, services: record, d })
+  if (!saved) return ['failed', 1]
+  report.files = printResult(ui, ws, saved, changes, commands)
+  printManual(ui, manual, false)
+  for (const block of report.keySteps) ui.block(block)
+  ui.print('Never put the key in a file in your repo.')
+  report.check = ask ? await checkKey(ui, d, env) : null
+  if (!report.check) ui.print(`To check your key, set ${SECRET.name} in this terminal, then run ${checkCommand(env)}.`)
+  ui.print(CLI.next)
+  return ['applied', exit]
+}
+
+/**
+ * Write the edits, run the package managers, write the manifest. On any
+ * failure, put every file back and return null. Returns the original bytes
+ * of every path it touched.
+ */
+async function apply({ root, ws, changes, commands, manifest, services, d }) {
+  const { ui } = d
+  // Ctrl-C stops the package manager. Stay alive, so the failed run is rolled back below.
+  const hold = () => {}
+  process.on('SIGINT', hold)
+  /** @type {Map<string, Buffer|null>} */ const saved = new Map()
+  const made = []
+  const save = (file) => { if (!saved.has(file)) saved.set(file, readBytes(ws.abs(file))) }
+  const undo = () => {
+    for (const [file, bytes] of saved) {
+      try { if (bytes === null) removeFile(ws.abs(file)); else writeAtomic(ws.abs(file), bytes) } catch { /* best effort */ }
+    }
+    for (const dir of made.reverse()) try { rmdirSync(dir) } catch { /* not empty */ }
+  }
+  try {
+    for (const c of changes) {
+      save(c.file)
+      if (ws.disk(c.file) !== c.before) {
+        ui.error(`${c.file} changed while this ran. Nothing changed. Run again.`)
+        return null
+      }
+      const bytes = saved.get(c.file)
+      if (bytes && !bytes.equals(Buffer.from((c.bom ? BOM : '') + c.before, 'utf8'))) {
+        ui.error(`${c.file} is not UTF-8 text, so this tool cannot edit it safely. Nothing changed.`)
+        return null
+      }
+    }
+    for (const file of [...changes.map((c) => c.file), CLI.manifest]) inside(ws, file)
+    const written = new Map()
+    for (const c of changes) {
+      const abs = ws.abs(c.file), bytes = Buffer.from((c.bom ? BOM : '') + c.after, 'utf8')
+      makeDirs(dirname(abs), made)
+      writeAtomic(abs, bytes)
+      written.set(c.file, bytes)
+    }
+    for (const command of commands) for (const file of command.touches) save(file)
+    for (const command of commands) {
+      const result = await d.spawn(command.cmd, command.args, { cwd: ws.abs(command.cwd) })
+      if (result.code !== 0) {
+        undo()
+        ui.error(`${command.cmd} failed${result.error ? `: ${result.error}` : ''}. Nothing changed.`)
+        ui.error(`  ${[command.cmd, ...command.args].join(' ')}${command.cwd === '.' ? '' : ` (in ${command.cwd})`}`)
+        return null
+      }
+    }
+    const entries = changes.map((c) => changeEntry(c, saved.get(c.file), written.get(c.file)))
+    const packages = commands.map((c) => ({ cwd: c.cwd, cmd: c.cmd, added: c.added, undo: [c.undo.cmd, ...c.undo.args], touches: c.touches,
+      before: Object.fromEntries(c.touches.map((file) => [file, sha256(saved.get(file))])) }))
+    save(CLI.manifest)
+    const file = ws.abs(CLI.manifest)
+    makeDirs(dirname(file), made)
+    writeAtomic(file, Buffer.from(manifestText(mergeManifest(manifest, { services, changes: entries, packages }))))
+    return saved
+  } catch (error) {
+    undo()
+    ui.error(`Could not apply the changes: ${error.message}. Nothing changed.`)
+    return null
+  } finally {
+    process.off('SIGINT', hold)
+  }
+}
+
+async function remove(opts, d, report) {
+  const { ui } = d, root = opts.root
+  const manifest = readManifest(root)
+  if (!manifest) {
+    ui.print(`Nothing to remove. This folder has no ${CLI.manifest}.`)
+    return ['nothing-to-remove', 0]
+  }
+  const ws = d.createWorkspace(root)
+  const packages = [...manifest.packages].reverse(), changes = [...manifest.changes].reverse()
+  for (const file of [...changes.map((c) => c.file), CLI.manifest]) inside(ws, file)
+  const runLine = (p) => `Run ${p.undo.join(' ')}${p.cwd === '.' ? '' : ` in ${p.cwd}`}.`
+  ui.print('UKNOWS remove')
+  ui.print()
+  ui.print('This undoes what npx @uknows/setup changed:')
+  for (const p of packages) ui.print(`  ${runLine(p)}`)
+  for (const file of unique(changes.map((c) => c.file))) {
+    ui.print(`  ${changes.some((c) => c.file === file && c.created) ? 'Delete' : 'Restore'} ${file}.`)
+  }
+  ui.print(`  Delete ${CLI.manifest}.`)
+  if (opts.json && !opts.yes) return ['planned', 0]
+  if (!opts.yes) {
+    if (!ui.interactive) {
+      ui.print('Run again with --yes to remove.')
+      return ['planned', 2]
+    }
+    if (!(await ui.confirm('Remove? (Y/n)'))) {
+      ui.print('Nothing changed.')
+      return ['planned', 0]
+    }
+  }
+
+  const left = { packages: [], changes: [] }
+  for (const p of packages) {
+    const [cmd, ...args] = p.undo
+    const result = await d.spawn(cmd, args, { cwd: ws.abs(p.cwd) })
+    report.commands.push({ cwd: p.cwd, argv: p.undo, ok: result.code === 0 })
+    if (result.code !== 0) left.packages.unshift(p)
+  }
+  for (const c of changes) {
+    const abs = ws.abs(c.file)
+    const result = undoChange(c, readBytes(abs))
+    if (result.reason) {
+      report.files.push({ file: c.file, result: 'skipped', reason: result.reason })
+      left.changes.unshift(c)
+      continue
+    }
+    if (result.bytes === null) removeFile(abs)
+    else writeAtomic(abs, result.bytes)
+    report.files.push({ file: c.file, result: result.bytes === null ? 'deleted' : 'restored' })
+  }
+
+  // Keep a record of what is left, so remove can try again. --force forgets it.
+  const rest = left.packages.length + left.changes.length
+  const file = ws.abs(CLI.manifest)
+  if (rest && !opts.force) writeAtomic(file, Buffer.from(manifestText({ ...manifest, ...left })))
+  else {
+    removeFile(file)
+    try { rmdirSync(dirname(file)) } catch { /* not empty */ }
+  }
+  ui.print()
+  if (rest) {
+    ui.print('Undo these by hand:')
+    for (const p of left.packages) ui.print(`  ${runLine(p)} It failed here.`)
+    for (const f of report.files.filter((x) => x.result === 'skipped')) ui.print(`  ${f.file}: ${f.reason}`)
+    if (!opts.force) ui.print(`${CLI.manifest} still lists them. Fix them and run remove again, or run remove --force to forget them.`)
+    return ['partial', 3]
+  }
+  ui.print('Removed what setup added.')
+  // Package managers write package.json and lockfiles their own way, so say when one is not byte for byte as before.
+  const original = new Map()
+  for (const p of manifest.packages) for (const [file, sha] of Object.entries(p.before ?? {})) if (!original.has(file)) original.set(file, sha)
+  const differ = [...original].filter(([file, sha]) => sha256(readBytes(ws.abs(file))) !== sha).map(([file]) => file)
+  if (differ.length) {
+    for (const file of differ) report.files.push({ file, result: 'differs', reason: 'The package manager did not write it back byte for byte.' })
+    ui.print(`Your package manager did not write ${differ.join(', ')} back byte for byte. Check the difference with git diff.`)
+  }
+  return ['removed', 0]
+}
+
+/** The check command as the reader should type it, with the test addresses of this run. */
+function checkCommand(env) {
+  const vars = [CLI.siteEnv, CLI.endpointEnv].filter((name) => env[name]).map((name) => `${name}=${env[name]}`)
+  return [...vars, 'npx @uknows/setup check'].join(' ')
+}
+
+/**
+ * Check your key, right after setup: the key from this terminal, or one pasted now. The pasted key is never
+ * written anywhere and never shows on the screen. Returns the --json check entry, or null when skipped.
+ */
+async function checkKey(ui, d, env) {
+  ui.print()
+  ui.print('Check your key')
+  let headers = null
+  if (env[SECRET.name]?.trim()) {
+    if (await ui.confirm(`Check the key in ${SECRET.name} from this terminal now? (Y/n)`)) headers = env[SECRET.name]
+  } else {
+    const key = (await ui.secret('Paste your UKNOWS key to check it now. It does not show on the screen. Press Enter to skip:')).trim()
+    // Accept the key as copied, also with the header name or quotes around it.
+    const bare = key.replace(/^["']|["']$/g, '').replace(new RegExp(`^${SECRET.header}\\s*[=:]\\s*`, 'i'), '').trim()
+    if (bare) headers = `${SECRET.header}=${bare}`
+  }
+  if (!headers) return null
+  const result = await d.runCheck({ env, headers })
+  for (const line of result.lines) (result.ok ? ui.print : ui.error)(`  ${line}`)
+  ui.print()
+  const status = result.ok ? 'reached' : result.status === null ? 'network-error' : 'rejected'
+  return { status, httpStatus: result.status, workspace: result.workspace, environment: result.environment }
+}
+
+function printPlan(ui, plans, detection, changes, commands, opts) {
+  ui.print('Runs on:')
+  for (const h of detection.hosts) {
+    const files = unique(h.evidence.map((e) => e.file))
+    ui.print(`  ${hostLabel(h.id)}. ${files.length ? `Found in ${files.join(', ')}.` : 'No deploy files found, so the steps are the general ones.'}`)
+  }
+  for (const p of plans) {
+    const from = opts.serviceName ? 'from --service-name' : p.s.nameFrom === 'existing' ? 'already set in the repo'
+      : p.s.nameFrom === 'folder' ? 'from the folder name' : `from ${p.s.nameFrom}`
+    ui.print()
+    if (plans.length === 1) {
+      ui.print(`Service name: ${p.name} (${from}).${opts.serviceName ? '' : ' Change it with --service-name.'}`)
+      ui.print(`Plan for ${p.name}:`)
+    } else ui.print(`Plan for ${p.name} in ${p.s.dir} (name ${from}):`)
+    steps(p).forEach((step, i) => ui.print(`  ${i + 1}. ${step}`))
+    if (p.manual.length) ui.print(`  After this, you do ${plural(p.manual.length, 'step')} by hand: ${p.manual.map((b) => b.title).join('. ')}.`)
+    const chosen = p.s.evidence?.find((e) => e.what.startsWith('Dockerfile for this service: '))
+    if (chosen) ui.print(`  Dockerfile: ${chosen.file}, because ${chosen.what.slice('Dockerfile for this service: '.length)}.`)
+    for (const note of [...p.notes, ...p.s.problems.filter((x) => x.code !== 'dockerfile-ambiguous').map((x) => x.message)]) ui.print(`  Note: ${note}`)
+  }
+  ui.print()
+  const edited = changes.filter((c) => c.before !== null).map((c) => c.file)
+  const created = changes.filter((c) => c.before === null).map((c) => c.file)
+  const changed = unique([...edited, ...commands.flatMap((c) => c.touches)])
+  if (changed.length) ui.print(`Files to change: ${changed.join(', ')}`)
+  if (created.length) ui.print(`Files to add: ${created.join(', ')}`)
+  ui.print(`It also writes ${CLI.manifest}, so you can undo this with npx @uknows/setup remove.`)
+  // Exactly what changes, before anything does: the diff of every file edit, and what each package manager adds.
+  const out = [...changes.flatMap((c) => unified(c.file, c.before, c.after).split('\n').map(redactKey)),
+    ...commands.map((c) => `${list(c.touches)}: ${c.cmd} adds ${list(c.added ?? [])}.`)]
+  if (out.length) {
+    ui.print()
+    ui.print('The changes:')
+    ui.print()
+    for (const line of out.slice(0, DIFF_LIMIT)) ui.print(line)
+    if (out.length > DIFF_LIMIT) ui.print(`And ${plural(out.length - DIFF_LIMIT, 'more line')}. Run with --json to see every planned file.`)
+    ui.print()
+  }
+  const tools = unique(commands.map((c) => c.cmd))
+  if (tools.length) {
+    ui.print(`This runs ${tools.join(' and ')} with install scripts turned off. ${commands.every((c) => c.lockOnly)
+      ? `${tools.length === 1 ? 'It writes' : 'They write'} only ${list(unique(commands.flatMap((c) => c.touches)))}.`
+      : `${tools.length === 1 ? 'It downloads' : 'They download'} the packages.`}`)
+  }
+}
+
+/** Print the diff of every file this run changed. Returns the --json files list. */
+function printResult(ui, ws, saved, changes, commands) {
+  const files = [], out = []
+  for (const [file, before] of saved) {
+    if (file === CLI.manifest) continue
+    const after = readBytes(ws.abs(file))
+    if (before === null ? after === null : after !== null && before.equals(after)) continue
+    const a = before === null ? null : text(before), b = after === null ? '' : text(after)
+    const change = changes.find((c) => c.file === file), command = commands.find((c) => c.touches.includes(file))
+    const why = unique([...(change?.why ?? []), ...(command ? [command.why] : [])])
+    if (LOCKFILES.has(file.split('/').pop())) {
+      files.push({ file, created: before === null, added: null, removed: null, why })
+      out.push(`${file}: updated by ${command?.cmd ?? 'the package manager'}.`)
+    } else if (change && change.after === b) {
+      // The plan showed this diff already.
+      const counts = countLines(a, b)
+      files.push({ file, created: before === null, ...counts, why })
+      out.push(`${file}: ${before === null ? 'added' : 'changed'} as shown above (+${counts.added} -${counts.removed}).`)
+    } else {
+      files.push({ file, created: before === null, ...countLines(a, b), why })
+      out.push(...unified(file, a, b).split('\n').map(redactKey))
+    }
+  }
+  ui.print()
+  ui.print(`Done. Changed ${plural(files.length, 'file')}:`)
+  ui.print()
+  for (const line of out.slice(0, DIFF_LIMIT)) ui.print(line)
+  if (out.length > DIFF_LIMIT) ui.print('Run git diff to see the rest.')
+  ui.print()
+  ui.print(`To undo this, run npx @uknows/setup remove. ${CLI.manifest} lists what changed. It has no secrets.`)
+  ui.print()
+  return files
+}
+
+function printManual(ui, manual, gap = true) {
+  if (!manual.length) return
+  if (gap) ui.print()
+  ui.print(`You need to do ${plural(manual.length, 'more step')}:`)
+  ui.print()
+  for (const block of manual) ui.block(block)
+}
+
+const where = (dir) => (dir === '.' ? 'this folder' : dir)
+/** Drop empty lines from a block, so a docs note that is gone never prints as 'undefined'. */
+const tidy = (block) => ({ ...block, lines: block.lines.filter((line) => typeof line === 'string' && line) })
+const steps = (p) => unique([...p.plan.commands.map((c) => c.why), ...p.plan.summary, ...p.settings.summary])
+const text = (bytes) => { const t = bytes.toString('utf8'); return t.startsWith(BOM) ? t.slice(1) : t }
+
+function describe(s, withDir = false) {
+  const frameworks = s.frameworks.length ? ` (${s.frameworks.map(frameworkLabel).join(', ')})` : ''
+  const start = !s.start ? 'Its start command is not clear.'
+    : s.start.kind === 'package.json' ? `It starts from the start script in ${s.start.file}.`
+      : `It starts from ${s.start.file} line ${s.start.line}.`
+  return `${stackLabel(s.lang)}${frameworks}${withDir ? ` in ${where(s.dir)}` : ''}. ${start}`
+}
+
+/** A service in the --json report. start never holds the command text. */
+function serviceReport(s, extra = {}) {
+  return { dir: s.dir, lang: s.lang, stack: null, name: s.name, frameworks: s.frameworks,
+    start: s.start ? { kind: s.start.kind, file: s.start.file, line: s.start.line } : null, settings: null,
+    summary: [], commands: [], manual: [], notes: [], otel: [], apm: [], ...extra }
+}
+
+/** Run a package manager. Its output goes to stderr, so --json stdout stays clean. */
+export function runCommand(cmd, args, { cwd }) {
+  return new Promise((resolve) => {
+    const shell = process.platform === 'win32'
+    if (shell && ![cmd, ...args].every((arg) => SAFE_ARG.test(arg))) return resolve({ code: null, error: 'an argument has characters this tool does not pass to a shell' })
+    let settled = false
+    const finish = (result) => { if (!settled) { settled = true; resolve(result) } }
+    try {
+      const child = spawnChild(cmd, args, { cwd, stdio: ['ignore', 2, 2], shell })
+      child.on('error', (error) => finish({ code: null, error: error.code === 'ENOENT' ? `${cmd} was not found` : error.message }))
+      child.on('close', (code) => finish({ code, error: null }))
+    } catch (error) {
+      finish({ code: null, error: error.message })
+    }
+  })
+}
+
+/** Bytes of a regular file, or null when it is missing, a link or not a file. */
+function readBytes(abs) {
+  try {
+    return lstatSync(abs).isFile() ? readFileSync(abs) : null
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null
+    throw error
+  }
+}
+
+/** Write through a temp file in the same folder, then rename. Keeps the file mode. */
+function writeAtomic(abs, bytes) {
+  const temp = `${abs}.uknows-${process.pid}.tmp`
+  let mode = null
+  try { mode = statSync(abs).mode & 0o7777 } catch { /* a new file */ }
+  try {
+    writeFileSync(temp, bytes)
+    if (mode !== null) chmodSync(temp, mode)
+    renameSync(temp, abs)
+  } catch (error) {
+    try { unlinkSync(temp) } catch { /* not written */ }
+    throw error
+  }
+}
+
+/** Throw unless the real folder of a repo path is inside the repo, so a linked folder cannot lead a write out of it. */
+function inside(ws, file) {
+  let dir = dirname(ws.abs(file))
+  while (!existsSync(dir) && dirname(dir) !== dir) dir = dirname(dir)
+  const base = realpathSync(ws.root), real = realpathSync(dir)
+  if (real !== base && !real.startsWith(base.endsWith(sep) ? base : base + sep)) throw new Error(`${file} is in a folder outside the repo`)
+}
+
+function removeFile(abs) {
+  try { unlinkSync(abs) } catch (error) { if (error.code !== 'ENOENT') throw error }
+}
+
+/** Create a folder and its missing parents. Records the new folders, top first, for rollback. */
+function makeDirs(dir, made) {
+  const missing = []
+  for (let d = dir; !existsSync(d); d = dirname(d)) missing.unshift(d)
+  if (missing.length) {
+    mkdirSync(dir, { recursive: true })
+    made.push(...missing)
+  }
+}