@uknows/setup 0.0.0-stage → 0.2.0

package/lib/check.mjs

@@ -0,0 +1,327 @@
+/*
+ * The check command: check the key from OTEL_EXPORTER_OTLP_HEADERS (or the
+ * key pasted after setup), and say what happened. 2 steps, the only network
+ * calls the CLI makes:
+ *   1. Ask the site which workspace and environment the key sends to (the
+ *      ping route that "Check your key" on /docs uses). A refused key stops here.
+ *   2. Send 1 test span to the ingest address, as the app will.
+ * It uses node:http and node:https (fetch prints a warning on Node 18). The key
+ * never appears in the output.
+ */
+import { randomBytes } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import http from 'node:http'
+import https from 'node:https'
+import { CHECK_NETWORK, CLI, KEY_CHECK, SECRET, SETUP_NEXT, TROUBLESHOOTING, keyCheckLine } from './contract.mjs'
+import { ingestEndpoint, sameUknows, siteUrl } from './endpoint.mjs'
+
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+const CERT = /^(?:CERT_|ERR_TLS_CERT|UNABLE_TO_(?:VERIFY_LEAF_SIGNATURE|GET_ISSUER_CERT)|SELF_SIGNED_CERT_IN_CHAIN|DEPTH_ZERO_SELF_SIGNED_CERT|ERR_SSL_)/
+const MAX_BODY = 65536
+const ACCEPTED = 'UKNOWS accepted 1 test span.'
+/** What each refusal of the ping route means, from the docs list ("ingest_key_invalid" and so on). */
+const MEANING = new Map(KEY_CHECK.answers.map((a) => [/^[a-z_]+$/.test(a.answer) ? a.answer : null, a.meaning]).filter(([code]) => code))
+
+/** The key variable of apps that keep their own metrics and logs. check reads it when OTEL_EXPORTER_OTLP_HEADERS is not set. */
+const TRACES_HEADERS = 'OTEL_EXPORTER_OTLP_TRACES_HEADERS'
+
+/** A timeout gets 1 more try, for this many times as long: UKNOWS can take about 16 seconds to answer after a quiet time. */
+const RETRY_FACTOR = 3
+
+/**
+ * A new key: one that UKNOWS made a moment ago. That is the key of the sign-in of this run, or a key that the site says
+ * is under 5 minutes old (createdAt in its answer). The site knows a new key at once. The data intake (the ingest
+ * address) learns new keys by itself, about every 30 seconds (the key sync of its gateway; measured 26 Oct 2026: about
+ * 30 seconds). So for a new key, a 401 means "not ready yet": the check asks again, every 5 seconds for the first 30
+ * seconds and then every 10 seconds, for up to 2 minutes, with 1 line that says so. A pasted or older key gets 1 try.
+ */
+export const NEW_KEY = {
+  waitMs: 120000, fastMs: 30000, fastEveryMs: 5000, everyMs: 10000, youngMs: 300000,
+  /** The line while the check waits. On a terminal, the time since the wait began follows it, for example 0:35. */
+  waiting: 'UKNOWS is getting your new key ready on the data intake...',
+  /** The same in a pipe or a log, printed once. */
+  waitingPlain: 'UKNOWS is getting your new key ready on the data intake. This can take up to 2 minutes.',
+  ready: (took) => `Your new key is ready on the data intake. It took ${took}.`,
+  /** After 2 minutes. where: " for Your Company, environment Production" when the site named them, else "". */
+  late: (where, siteKnows) => (siteKnows
+    ? `UKNOWS made your new key${where}, but its data intake did not take the key within 2 minutes. This is on the UKNOWS side, not in your app.`
+    : 'UKNOWS did not get your new key ready within 2 minutes. This is on the UKNOWS side, not in your app.'),
+  /** The last line after that: of a run with 1 Yes, of the key command, and of a run that changed the files already. */
+  again: 'Run npx @uknows/setup again in a few minutes. Nothing changed.',
+  againKey: 'Run npx @uknows/setup key again in a few minutes. Nothing changed.',
+  againFiles: 'Next: in a few minutes, run npx @uknows/setup key. It signs you in again, checks the new key and stores it.',
+}
+
+/** Time as the person reads it: 35 seconds, 1 minute 5 seconds, 2 minutes. */
+export function duration(ms) {
+  const s = Math.max(0, Math.round(ms / 1000)), m = Math.floor(s / 60), rest = s % 60
+  const part = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`
+  return m ? `${part(m, 'minute')}${rest ? ` ${part(rest, 'second')}` : ''}` : part(rest, 'second')
+}
+
+/** The clock of a real check. Tests pass one whose time moves only when something sleeps. */
+const SYSTEM_CLOCK = { now: () => Date.now(), sleep: (ms) => new Promise((resolve) => setTimeout(resolve, Math.max(0, ms))) }
+
+/**
+ * Check the key in OTEL_EXPORTER_OTLP_HEADERS (or OTEL_EXPORTER_OTLP_TRACES_HEADERS) from env, or options.headers,
+ * then send 1 test span. serviceName: the name of the service that setup found, for the test span. A request with no
+ * answer in timeoutMs is tried once more, for up to 3 times as long. onRetry(line) gets 1 line that says so, before it.
+ * newKey: the key came from the sign-in of this run, so a 401 waits for it (NEW_KEY), with clock (now and sleep).
+ * onWait() is called once, when that wait begins. It returns end(line): line is NEW_KEY.ready when the key works after
+ * the wait, else null. A new key that still gets 401 after 2 minutes gives notReady: true and the NEW_KEY.late line.
+ * @param {{env?: Record<string, string|undefined>, headers?: string, timeoutMs?: number, serviceName?: string|null,
+ *   onRetry?: (line: string) => void, newKey?: boolean, clock?: {now: () => number, sleep: (ms: number) => Promise<void>},
+ *   onWait?: () => ((line: string|null) => void)}} [options]
+ * @returns {Promise<import('./types.mjs').CheckResult>}
+ */
+export async function runCheck(options = {}) {
+  const { env = process.env, timeoutMs = 10000, onRetry = () => {}, clock = SYSTEM_CLOCK, onWait = () => () => {} } = options
+  const ask = (url, method, headers, body) => requestWithRetry(url, method, headers, body, timeoutMs, onRetry)
+  const raw = options.headers ?? (env[SECRET.name]?.trim() ? env[SECRET.name] : env[TRACES_HEADERS])
+  if (!raw || !raw.trim()) {
+    // 1 line, safe to paste at once: read takes the key from the next line, and nothing stays set in the terminal.
+    const vars = [CLI.siteEnv, CLI.endpointEnv].filter((name) => env[name]).map((name) => `${name}=${env[name]}`)
+    return result(2, null, [`${SECRET.name} is not set in this terminal.`, SETUP_NEXT.skipped, `  ${keyCheckLine(vars)}`, CHECK_NETWORK.where])
+  }
+  const headers = parseHeaders(raw)
+  // Hide each header value as written and as decoded. A part without '=' may be a bare key: hide it whole.
+  const redact = redactor([...raw.split(',').map((part) => part.slice(part.indexOf('=') + 1)), ...Object.values(headers)])
+  const keyName = Object.keys(headers).find((name) => name.toLowerCase() === SECRET.header)
+  if (!keyName) {
+    return result(2, null, [`${SECRET.name} has no ${SECRET.header}. Use the format ${SECRET.value}. Remove spaces and quotes.`])
+  }
+  const endpoint = ingestEndpoint(env)
+  if (!endpoint) return result(1, null, [`${CLI.endpointEnv} must be an https address.`])
+  const site = siteUrl(env)
+  if (!site) return result(1, null, [`${CLI.siteEnv} must be an https address with no path, for example https://uknows.example.com.`])
+
+  let ping = null
+  const lines = [], after = []
+  // A new key waits while UKNOWS gets it ready (NEW_KEY): 1 wait for both steps, with 1 line.
+  const wait = waiter(clock, onWait)
+  let fresh = Boolean(options.newKey)
+  const late = (siteKnows) => {
+    wait.end(null)
+    const where = ping?.workspace ? ` for ${ping.workspace}${ping.environment ? `, environment ${ping.environment}` : ''}` : ''
+    return { ...result(1, 401, [NEW_KEY.late(where, siteKnows)]), ...named(ping), notReady: true }
+  }
+
+  // 1. Which workspace and environment the key sends to.
+  if (sameUknows(env)) {
+    const pingUrl = new URL(`${site}${CLI.pingPath}`)
+    const askPing = () => ask(pingUrl, 'GET', { [SECRET.header]: headers[keyName] }, null)
+    let answer = await askPing()
+    // A key the site does not know yet. Revoked, paused and the other answers are no wait.
+    const unknown = (a) => a.status === 401 && parse(a.body)?.error === 'ingest_key_invalid'
+    while (fresh && unknown(answer) && await wait.more()) answer = await askPing()
+    if (fresh && unknown(answer)) return late(false)
+    ping = explainPing(answer, site, redact, clock.now())
+    if (ping.stop) {
+      wait.end(null)
+      return { ...result(1, answer.status ?? null, ping.lines), keyState: ping.keyState ?? null }
+    }
+    lines.push(...ping.lines)
+    fresh ||= typeof ping.ageMs === 'number' && ping.ageMs < NEW_KEY.youngMs
+  } else {
+    after.push(`To also see which workspace the key sends to, set ${CLI.siteEnv} with ${CLI.endpointEnv}.`)
+  }
+
+  // 2. 1 test span to the ingest address. A new key that the data intake does not know yet gets 401 there.
+  const url = new URL(`${endpoint}/v1/traces`)
+  const send = () => ask(url, 'POST', { ...headers, 'content-type': 'application/json' }, testSpan(env, options.serviceName))
+  let response = await send()
+  while (fresh && response.status === 401 && await wait.more()) response = await send()
+  if (fresh && response.status === 401) return late(true)
+  wait.end(wait.started && response.status >= 200 && response.status < 300 ? NEW_KEY.ready(duration(wait.elapsed())) : null)
+  if (response.error) {
+    // The site said the key works, but the upload to the ingest address failed: say both plainly, with the next step.
+    // After a second timeout, the advice names the longer wait.
+    const keyFine = Boolean(ping?.workspace) && !CERT.test(response.error?.code ?? '')
+    const waited = timedOut(response.error) ? timeoutMs * RETRY_FACTOR : timeoutMs
+    return { ...result(1, null, [...lines, ...(keyFine ? [CHECK_NETWORK.keyFine] : []), ...explainNetworkError(response.error, url, waited, env).map(redact), ...after]), ...named(ping) }
+  }
+  const sent = explainResponse(response, redact)
+  // Without the site's answer, the accepted span is what shows that the key works.
+  const spanLines = sent.lines.map((line) => (line === ACCEPTED && !ping?.workspace ? `${ACCEPTED} Your key works.` : line))
+  return { ...sent, ...named(ping, sent), lines: [...lines, ...spanLines, ...(sent.ok ? after : [])] }
+}
+
+/** The workspace and environment from the ping, when the ingest answer did not name them. */
+function named(ping, sent = {}) {
+  return { workspace: sent.workspace ?? ping?.workspace ?? null, environment: sent.environment ?? ping?.environment ?? null, keyState: ping?.keyState ?? null }
+}
+
+/**
+ * What the ping route said. stop: true when the key is refused, so no span is sent. ageMs: how old the key is, when
+ * the answer says when it was made (createdAt), measured at now. null when it does not say.
+ */
+export function explainPing({ status, error, body }, site, redact = (x) => x, now = Date.now()) {
+  const host = new URL(site).hostname
+  if (error) return { stop: false, lines: [`Could not ask ${host} which workspace the key sends to (${error.code || 'network error'}). Sending the test span anyway.`] }
+  const data = parse(body)
+  if (status === 200 && data?.workspace) {
+    const workspace = clean(data.workspace.name ?? data.workspace.id, redact)
+    const environment = clean(data.environmentLabel ?? data.environment, redact)
+    const lines = [`Your key works. It sends data to ${workspace}${environment ? `, environment ${environment}` : ''}.`]
+    if (data.keyState === 'retiring') lines.push(`A new key replaced this key. It stops working${data.retiresAt ? ` at ${clean(String(data.retiresAt), redact)}` : ' soon'}. Set the new key.`)
+    if (data.status === 'paused') lines.push('Your workspace is paused.')
+    const made = typeof data.createdAt === 'string' ? Date.parse(data.createdAt) : NaN
+    return { stop: false, workspace, environment, keyState: clean(data.keyState, redact), ageMs: Number.isFinite(made) ? Math.max(0, now - made) : null, lines }
+  }
+  const code = typeof data?.error === 'string' ? data.error : null
+  if ((status === 401 || status === 403) && code) {
+    const why = code === 'ingest_key_missing' ? 'The key is empty.' : MEANING.get(code) ?? `UKNOWS refused the key (${code}).`
+    return { stop: true, keyState: code === 'ingest_key_revoked' ? 'revoked' : null, lines: [`UKNOWS did not accept the key (${code}).`, why] }
+  }
+  if (status === 429) return { stop: false, lines: [`${host} says: too many checks from your address. Sending the test span anyway.`] }
+  return { stop: false, lines: [`${host} did not say which workspace the key sends to (status ${status}). Sending the test span anyway.`] }
+}
+
+/** Header pairs from 'k=v,k2=v2'. Each part splits on its first '=' and is percent-decoded, as the OTLP spec says. */
+export function parseHeaders(value) {
+  const out = {}
+  for (const part of String(value).split(',')) {
+    const at = part.indexOf('=')
+    if (at < 1) continue
+    const name = decode(part.slice(0, at).trim())
+    if (name) out[name] = decode(part.slice(at + 1).trim())
+  }
+  return out
+}
+
+/**
+ * What to print for a network error: what failed, with the host and port, and what to do. The same words as the
+ * answers in "Check your key" (CHECK_NETWORK). Exported for tests: DNS and TLS failures are hard to cause offline.
+ */
+export function explainNetworkError(error, url, timeoutMs, env = {}) {
+  const code = error?.code ?? ''
+  const port = url.port || (url.protocol === 'https:' ? '443' : '80')
+  const host = url.hostname
+  const proxy = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy'].some((k) => env[k])
+  if (CERT.test(code)) return [`Cannot check the TLS certificate of ${host} (${code}).`, 'A proxy may be in the way. This tool does not use HTTPS_PROXY.']
+  if (/^ERR_INVALID_(?:CHAR|HTTP_TOKEN)/.test(code)) return [`${SECRET.name} has a character that is not allowed in a header.`]
+  const seconds = Math.round(timeoutMs / 100) / 10
+  const values = { host, port, seconds: seconds === 1 ? '1' : String(seconds), code: code || 'unknown error' }
+  const fill = (t) => t.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+  const dns = code === 'ENOTFOUND' || code === 'EAI_AGAIN'
+  const what = dns ? CHECK_NETWORK.dns : code === 'ECONNREFUSED' ? CHECK_NETWORK.refused
+    : code === 'UKNOWS_TIMEOUT' || code === 'ETIMEDOUT' ? CHECK_NETWORK.timeout.replace('{seconds} seconds', seconds === 1 ? '1 second' : '{seconds} seconds')
+      : code === 'ECONNRESET' || code === 'EPIPE' ? CHECK_NETWORK.reset
+        : code === 'EHOSTUNREACH' || code === 'ENETUNREACH' ? CHECK_NETWORK.unreachable : CHECK_NETWORK.other
+  const lines = [fill(what), ...(dns ? [] : [fill(CHECK_NETWORK.ask)]), CHECK_NETWORK.where]
+  if (proxy) lines.push(CHECK_NETWORK.proxy)
+  return lines
+}
+
+// --- request and response ---------------------------------------------------------
+
+const timedOut = (error) => error?.code === 'UKNOWS_TIMEOUT' || error?.code === 'ETIMEDOUT'
+const secondsOf = (ms) => { const s = Math.round(ms / 100) / 10; return s === 1 ? '1 second' : `${s} seconds` }
+
+/** 1 request. With no answer in timeoutMs, 1 more try for up to RETRY_FACTOR times as long, after 1 line to onRetry. */
+async function requestWithRetry(url, method, headers, body, timeoutMs, onRetry) {
+  const first = await request(url, method, headers, body, timeoutMs)
+  if (!timedOut(first.error)) return first
+  onRetry(`No answer from ${url.hostname} in ${secondsOf(timeoutMs)}. Trying again, for up to ${secondsOf(timeoutMs * RETRY_FACTOR)}.`)
+  return request(url, method, headers, body, timeoutMs * RETRY_FACTOR)
+}
+
+/** 1 HTTP request with node:http or node:https. Resolves {status, headers, body} or {error}. Never rejects. */
+export function request(url, method, headers, body, timeoutMs) {
+  return new Promise((resolve) => {
+    let done = false, timer = null, req
+    const finish = (value) => { if (!done) { done = true; clearTimeout(timer); resolve(value) } }
+    try {
+      req = (url.protocol === 'https:' ? https : http).request(url, {
+        method, agent: false,
+        headers: { ...headers, ...(body === null ? {} : { 'content-length': Buffer.byteLength(body) }), 'user-agent': `uknows-setup/${VERSION}` },
+      }, (res) => {
+        const chunks = []
+        let size = 0
+        res.on('data', (chunk) => { if (size < MAX_BODY) { chunks.push(chunk); size += chunk.length } })
+        res.on('end', () => finish({ status: res.statusCode, headers: res.headers, body: Buffer.concat(chunks).toString('utf8').slice(0, MAX_BODY) }))
+        res.on('error', (error) => finish({ error }))
+      })
+    } catch (error) { resolve({ error }); return }
+    timer = setTimeout(() => { finish({ error: { code: 'UKNOWS_TIMEOUT' } }); req.destroy() }, timeoutMs)
+    req.on('error', (error) => finish({ error }))
+    req.end(body ?? undefined)
+  })
+}
+
+function explainResponse({ status, headers, body }, redact) {
+  const data = parse(body)
+  if (status >= 200 && status < 300) {
+    const workspace = clean(data?.workspace, redact) ?? clean(headers['x-uknows-workspace'], redact)
+    const environment = clean(data?.environment, redact) ?? clean(headers['x-uknows-environment'], redact)
+    const lines = [workspace && environment ? `Reached ${workspace} / ${environment}.` : workspace ? `Reached ${workspace}.` : ACCEPTED]
+    const rejected = Number(data?.partialSuccess?.rejectedSpans ?? 0)
+    if (rejected > 0) lines.push(`UKNOWS did not keep the test span: ${clean(data.partialSuccess.errorMessage, redact) ?? 'no reason given'}.`)
+    return { ok: true, status, workspace, environment, lines, exit: 0 }
+  }
+  const steps = (id) => TROUBLESHOOTING.find((t) => t.id === id)?.steps ?? []
+  if (status === 401) return result(1, status, [`UKNOWS did not accept the key (status 401).`, ...steps('unauthorized')])
+  if (status === 403) return result(1, status, [`UKNOWS refused the data (status 403). ${TROUBLESHOOTING.find((t) => t.id === 'forbidden')?.cause ?? ''}`.trim(), ...steps('forbidden')])
+  const textual = !data && /json|text/i.test(String(headers['content-type'] ?? ''))
+  const message = clean(typeof data?.message === 'string' ? data.message : textual ? body : null, redact)
+  const lines = [`UKNOWS answered with status ${status}.`]
+  if (message) lines.push(message.length > 200 ? `${message.slice(0, 197)}...` : message)
+  if ([429, 502, 503, 504].includes(status)) lines.push('Try again in 1 minute.')
+  return result(1, status, lines)
+}
+
+/** 1 span in OTLP/JSON: hex ids, integer enums, int64 values as decimal strings. */
+function testSpan(env, serviceName = null) {
+  const hex = (bytes) => { let id; do id = randomBytes(bytes).toString('hex'); while (/^0+$/.test(id)); return id }
+  const start = BigInt(Date.now()) * 1000000n
+  return JSON.stringify({ resourceSpans: [{
+    resource: { attributes: [{ key: 'service.name', value: { stringValue: env.OTEL_SERVICE_NAME || serviceName || 'uknows-setup-check' } }] },
+    scopeSpans: [{ scope: { name: '@uknows/setup', version: VERSION }, spans: [{
+      traceId: hex(16), spanId: hex(8), name: 'uknows setup check', kind: 1,
+      startTimeUnixNano: String(start), endTimeUnixNano: String(start + 1000000n),
+      attributes: [{ key: 'uknows.check', value: { boolValue: true } }],
+    }] }],
+  }] })
+}
+
+// --- helpers ------------------------------------------------------------------------
+
+/**
+ * The wait for a new key (NEW_KEY). more() starts it at the first call (onWait() shows its line), sleeps until the next
+ * try, and is false once 2 minutes have passed since the start. end(line) ends the line once, with line or nothing.
+ */
+function waiter(clock, onWait) {
+  let started = null, finish = null
+  return {
+    get started() { return started !== null },
+    elapsed: () => (started === null ? 0 : clock.now() - started),
+    async more() {
+      if (started === null) { started = clock.now(); finish = onWait() ?? (() => {}) }
+      const waited = clock.now() - started
+      if (waited >= NEW_KEY.waitMs) return false
+      await clock.sleep(Math.min(waited < NEW_KEY.fastMs ? NEW_KEY.fastEveryMs : NEW_KEY.everyMs, NEW_KEY.waitMs - waited))
+      return true
+    },
+    end(line) { if (finish) { const done = finish; finish = null; done(line) } },
+  }
+}
+
+function result(exit, status, lines) {
+  return { ok: false, status, workspace: null, environment: null, lines, exit }
+}
+
+/** Replaces every form of the key with <key>, longest first, so a server that echoes it back cannot leak it. */
+function redactor(values) {
+  const secrets = [...new Set(values.map((v) => String(v ?? '').trim()))].filter((v) => v.length >= 4).sort((a, b) => b.length - a.length)
+  return (line) => secrets.reduce((out, secret) => out.split(secret).join(SECRET.placeholder), line)
+}
+
+/** A short single-line text from the server, or null. */
+function clean(value, redact) {
+  if (typeof value !== 'string') return null
+  const out = redact(value.replace(/[\u0000-\u001f\u007f]+/g, ' ').trim())
+  return out ? out.slice(0, 200) : null
+}
+
+function decode(text) { try { return decodeURIComponent(text) } catch { return text } }
+function parse(body) { try { return JSON.parse(body) } catch { return null } }

package/lib/ci.mjs

@@ -0,0 +1,21 @@
+/*
+ * Does this run in a pipeline? Setup and remove change a repo once, on a
+ * computer, so in a pipeline they stop with exit 2 unless --allow-ci is set.
+ * The variables come from contract.mjs CLI.ciEnv.
+ */
+import { CLI } from './contract.mjs'
+
+/**
+ * The name of the first CI variable that is set, or null. CI counts when it is not empty, 0 or false.
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function ciVariable(env = {}) {
+  for (const name of CLI.ciEnv) {
+    const value = String(env[name] ?? '').trim()
+    if (!value) continue
+    if (name === 'CI' && /^(?:0|false)$/i.test(value)) continue
+    return name
+  }
+  return null
+}

package/lib/cli.mjs

@@ -0,0 +1,251 @@
+/*
+ * Command line: parse the arguments, then run setup, remove or check.
+ * A hand-written parser, because util.parseArgs is experimental on Node 18.
+ */
+import { statSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { runCheck } from './check.mjs'
+import { CI_CD, CLI, DEFAULT_AGENT_REGISTRY, DOCS_URL, SECRET, SETUP_NEEDS } from './contract.mjs'
+import { toServiceName } from './detect.mjs'
+import { ingestEndpoint, siteUrl, validAppUrl } from './endpoint.mjs'
+import { CHANNELS, validRegistry } from './stacks/channel.mjs'
+import { UPDATE_BOTS } from './updates.mjs'
+import { runKey, runRemove, runSetup } from './engine.mjs'
+import { TOOL, VERSION, readManifest } from './manifest.mjs'
+import { UsageError, createUI } from './ui.mjs'
+
+const FLAGS = { '--dry-run': 'dryRun', '--yes': 'yes', '-y': 'yes', '--all': 'all', '--json': 'json', '--force': 'force', '--updates': 'updates',
+  '--allow-ci': 'allowCi', '--check': 'check', '--help': 'help', '-h': 'help', '--version': 'version', '--step-by-step': 'stepByStep', '--paste-key': 'pasteKey',
+  '--functions-opentelemetry': 'functionsOpenTelemetry' }
+const VALUES = { '--path': 'path', '--service-name': 'serviceName', '--channel': 'channel', '--update-bot': 'updateBot' }
+const COMMANDS = { setup: ['dryRun', 'yes', 'path', 'all', 'json', 'serviceName', 'force', 'allowCi', 'stepByStep', 'pasteKey', 'channel', 'updates', 'updateBot', 'functionsOpenTelemetry'], key: ['path', 'pasteKey'],
+  remove: ['yes', 'path', 'json', 'force', 'allowCi'], check: ['json'] }
+/** Flags that only mean something when setup asks questions in a terminal. */
+const ASKS = { stepByStep: '--step-by-step', pasteKey: '--paste-key' }
+
+export const HELP = `uknows-setup adds OpenTelemetry to your app, so it sends traces and logs to UKNOWS.
+
+Usage:
+  npx @uknows/setup [setup] [options]   Find your app, show the plan, then apply it.
+  npx @uknows/setup key [options]       Check and store the key of another environment, for example Production.
+  npx @uknows/setup remove [options]    Undo what setup changed.
+  npx @uknows/setup check               Send 1 test span with the key in ${SECRET.name}.
+
+Options:
+  --dry-run               Show the plan. Change nothing.
+  --yes, -y               Apply without asking. Never asks any question.
+  --step-by-step          Ask before each step, instead of 1 question for the whole plan.
+  --paste-key             Paste your key instead of signing in to UKNOWS in your browser.
+  --path <folder>         The folder to set up. The default is this folder. key takes only this option and --paste-key.
+  --all                   Set up every service folder. Each one gets its own OTEL_SERVICE_NAME.
+  --service-name <name>   The name of the service in UKNOWS.
+  --channel <name>        Java, .NET and Node.js apps with a Dockerfile: copy the UKNOWS agent from the
+                          agent image of a channel, stable or early, at each build. Then a new agent
+                          reaches the app at its next build, with no change to your repo.
+  --update-bot <name>     How the OpenTelemetry packages of your app stay up to date: renovate,
+                          dependabot (GitHub only, with a workflow that merges the updates and starts
+                          the deploy) or none. Without it, setup picks, as below.
+  --functions-opentelemetry
+                          Azure Functions apps: turn on OpenTelemetry in host.json, instead of the UKNOWS hooks
+                          that setup adds when the app sends to Application Insights or it cannot look.
+  --json                  Print a JSON report. Without --yes, setup only plans.
+  --force                 Run even when the repo has changes that are not committed.
+  --allow-ci              Apply in a pipeline. Only for a bot or an AI agent that opens a pull request.
+  --check                 The same as the check command.
+  --help, -h              Show this help.
+  --version               Show the version.
+
+Setup keeps the UKNOWS agent up to date by itself, and the plan says how and why:
+  1. Java, .NET and Node.js apps that build from a Dockerfile get the agent channel: each build
+     copies the newest stable agent, so no update pull request is needed.
+  2. Other apps get Renovate when your repo uses Renovate already.
+  3. Else Dependabot on GitHub. On GitLab, Azure DevOps or Bitbucket, setup adds renovate.json
+     and says how to add Renovate in 1 step.
+--update-bot and --channel choose instead.
+
+Run setup once on your computer, not in your pipeline. In a pipeline, setup and remove
+change nothing and exit 2, or exit 0 when the repo is already set up. --dry-run, a --json plan,
+check, --help and --version still work.
+To check in a pipeline that a repo is set up ("status": "nothing-to-change", "exitCode": 0):
+  ${CI_CD.snippet.code}
+
+In a terminal, setup opens your browser so you sign in to UKNOWS and pick the workspace and
+the environment. Your key then comes to setup by itself. Setup checks it, then shows the whole
+plan and asks 1 question: Do all of this? (Y/n). On a yes, it changes the files and also:
+  Stores the key on your platform with az, gh or kubectl, for the environment of the key.
+  Adds the key to a deploy file that would remove it on the next deploy.
+  Creates a branch, commits the files that setup changed, pushes it and opens a pull request.
+To show this plan, it reads your Azure subscriptions, your GitHub repo or your kubectl
+contexts. It changes nothing there until you say yes. With --step-by-step, it asks before each
+of these steps instead, after the change to the files.
+Then it opens the page where you watch your app connect. With --yes or --json, in a pipeline
+or without a terminal, it does none of these and prints the steps for you.
+
+Exit codes of setup and remove (they describe your repo):
+  0  Done, already set up, or nothing to do. Only the key steps on your platform are left.
+     Merging the pull request and deploying are left too.
+  1  Stopped or failed. Nothing changed. For example, no app found or another APM agent.
+     In a terminal, also when UKNOWS refuses the key. With --step-by-step, the changes to your repo stay.
+  2  Needs your input. Nothing changed. For example, pick a service, or a pipeline without --allow-ci.
+  3  Done, but you must do 1 or more steps in your repo before traces flow.
+Ctrl+C while setup waits for your sign-in stops it with exit code 130.
+check exits 0 when UKNOWS takes the test span, 1 when UKNOWS refuses the key or cannot be
+reached, and 2 when ${SECRET.name} is not set.
+key exits 0 when it stored the key or printed its steps, 1 when the folder is not set up or UKNOWS
+refuses the key or cannot be reached, and 2 without a terminal or a key.
+
+You need on this computer (setup updates the lock file of your app with its own tools):
+${SETUP_NEEDS.map((line) => `  ${line}`).join('\n')}
+
+Environment:
+  ${SECRET.name}
+      Your key, for check, as ${SECRET.value}. Set it only in your terminal.
+  ${CLI.agentRegistryEnv}
+      Another store of the UKNOWS agent images for the agent channel, as a registry and path, for example
+      registry.example.com/uknows.
+
+In a terminal, the tool gets your key when you sign in, or uses the key in ${SECRET.name}.
+With --paste-key, it asks you to paste it. The key does not show on the screen.
+With --yes in a terminal, it checks the key in ${SECRET.name} if it is set.
+This tool never writes your key to a file. To store it, az, gh and kubectl read it from
+a pipe, so it is in no command line.
+Docs: ${DOCS_URL}
+`
+
+/** @returns {{command: 'setup'|'key'|'remove'|'check', dryRun: boolean, yes: boolean, all: boolean, json: boolean, force: boolean, allowCi: boolean, help: boolean, version: boolean, path: string|null, serviceName: string|null, stepByStep: boolean, pasteKey: boolean, channel: string|null, updates: boolean, updateBot: string|null}} */
+export function parseArgs(argv) {
+  const opts = { command: null, dryRun: false, yes: false, all: false, json: false, force: false, allowCi: false, help: false, version: false, path: null, serviceName: null,
+    stepByStep: false, pasteKey: false, channel: null, updates: false, updateBot: null, functionsOpenTelemetry: false }
+  const given = []
+  let check = false
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if (!arg.startsWith('-') || arg === '-') {
+      if (opts.command) throw new UsageError(`Unexpected argument: ${arg}.`)
+      if (!(arg in COMMANDS)) throw new UsageError(`Unknown command: ${arg}.`)
+      opts.command = arg
+      continue
+    }
+    const eq = arg.startsWith('--') ? arg.indexOf('=') : -1
+    const flag = eq > 0 ? arg.slice(0, eq) : arg
+    if (flag in VALUES) {
+      let value = eq > 0 ? arg.slice(eq + 1) : argv[i + 1]
+      if (eq < 0) {
+        if (value === undefined || value.startsWith('-')) throw new UsageError(`${flag} needs a value.`)
+        i++
+      }
+      if (!value) throw new UsageError(`${flag} needs a value.`)
+      opts[VALUES[flag]] = value
+      given.push([VALUES[flag], flag])
+    } else if (flag in FLAGS) {
+      if (eq > 0) throw new UsageError(`${flag} does not take a value.`)
+      if (FLAGS[flag] === 'check') check = true
+      else opts[FLAGS[flag]] = true
+      if (!['help', 'version', 'check'].includes(FLAGS[flag])) given.push([FLAGS[flag], flag])
+    } else throw new UsageError(`Unknown option: ${flag}.`)
+  }
+  if (check && opts.command && opts.command !== 'check') throw new UsageError(`--check does not work with ${opts.command}.`)
+  if (opts.channel !== null && !CHANNELS.includes(opts.channel)) throw new UsageError(`--channel is ${CHANNELS.join(' or ')}.`)
+  if (opts.updateBot !== null) {
+    if (!UPDATE_BOTS.includes(opts.updateBot)) throw new UsageError(`--update-bot is ${UPDATE_BOTS.slice(0, -1).join(', ')} or ${UPDATE_BOTS.at(-1)}.`)
+    opts.updates = true
+  }
+  opts.command = check ? 'check' : opts.command ?? 'setup'
+  for (const [key, flag] of given) {
+    if (!COMMANDS[opts.command].includes(key)) throw new UsageError(`${flag} does not work with ${opts.command}.`)
+  }
+  // --yes and --json never ask, and a dry run asks for no key: the flags that change the questions do not fit them.
+  for (const [key, flag] of Object.entries(ASKS)) {
+    const other = opts.yes ? '--yes' : opts.json ? '--json' : opts.dryRun && key === 'pasteKey' ? '--dry-run' : null
+    if (opts[key] && other) throw new UsageError(`${flag} does not work with ${other}.`)
+  }
+  return opts
+}
+
+/**
+ * Run the CLI. Returns the exit code.
+ * @param {string[]} argv
+ * @param {{stdin?: any, stdout?: any, stderr?: any, cwd?: string, env?: Record<string, string|undefined>, interactive?: boolean, terminal?: boolean, deps?: object}} [io]
+ */
+export async function main(argv, io = {}) {
+  const { stdin = process.stdin, stdout = process.stdout, stderr = process.stderr, cwd = process.cwd(), env = process.env, deps = {} } = io
+  const json = argv.includes('--json')
+  const usage = (message) => {
+    stderr.write(`${message}\nRun uknows-setup --help.\n`)
+    if (json) stdout.write(`${JSON.stringify({ schema: 1, tool: TOOL, version: VERSION, command: null, status: 'usage-error', exitCode: 2, problems: [{ code: 'usage', message }] }, null, 2)}\n`)
+    return 2
+  }
+  let args
+  try {
+    args = parseArgs(argv)
+  } catch (error) {
+    if (error instanceof UsageError) return usage(error.message)
+    throw error
+  }
+  if (args.help) { stdout.write(HELP); return 0 }
+  if (args.version) { stdout.write(`${VERSION}\n`); return 0 }
+  if (args.command === 'check') return check(args, { stdout, stderr, env, cwd }, deps.runCheck ?? runCheck)
+  const run = { setup: runSetup, key: runKey, remove: runRemove }[args.command]
+
+  // setup writes the same ingest address that check sends to.
+  const endpoint = ingestEndpoint(env)
+  if (!endpoint) return usage(`${CLI.endpointEnv} must be an https address.`)
+  if (!siteUrl(env)) return usage(`${CLI.siteEnv} must be an https address with no path, for example https://uknows.example.com.`)
+  if (!validAppUrl(env)) return usage(`${CLI.appEnv} must be an https address with no path, for example https://app.uknows.example.com.`)
+  // The agent channel: the store of the UKNOWS agent images, UKNOWS_AGENT_REGISTRY or the one of this release.
+  const given = String(env[CLI.agentRegistryEnv] ?? '').trim().replace(/\/+$/, '')
+  if (given && !validRegistry(given)) return usage(`${CLI.agentRegistryEnv} must be the registry and path of the UKNOWS agent images, for example registry.example.com/uknows.`)
+  const registry = given || (validRegistry(DEFAULT_AGENT_REGISTRY) ? DEFAULT_AGENT_REGISTRY : null)
+  let channel = null
+  if (args.channel) {
+    if (!registry) return usage(`--channel needs ${CLI.agentRegistryEnv}: the registry and path of the UKNOWS agent images, for example registry.example.com/uknows.`)
+    channel = { name: args.channel, registry }
+  }
+  // The default (updates.mjs, step 1): the stable channel for the apps that fit, unless --update-bot or --channel chose.
+  const defaultChannel = !args.channel && !args.updateBot && registry ? { name: 'stable', registry } : null
+  const root = resolve(cwd, args.path ?? '.')
+  let folder = false
+  try { folder = statSync(root).isDirectory() } catch { /* missing */ }
+  if (!folder) return usage(`${args.path ?? root} is not a folder.`)
+  if (args.serviceName !== null && (deps.toServiceName ?? toServiceName)(args.serviceName) !== args.serviceName) {
+    return usage(`${args.serviceName} is not a valid service name. Use lowercase letters, digits and -, up to 63 characters.`)
+  }
+  const ui = createUI({ stdin, stdout, stderr, json: args.json, interactive: io.interactive, terminal: io.terminal, env })
+  try {
+    const { code, report } = await run({ ...args, channel, defaultChannel, root, endpoint, env }, { ...deps, ui })
+    if (args.json) stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+    return code
+  } finally {
+    ui.close()
+  }
+}
+
+async function check(args, { stdout, stderr, env, cwd }, run) {
+  // The test span carries the service name that setup recorded here, so the workspace never lists a made-up app.
+  let serviceName = null
+  try { serviceName = readManifest(cwd)?.services?.[0]?.name ?? null } catch { /* not valid: no name */ }
+  // The retry line goes to stderr, so --json stays 1 JSON document on stdout.
+  const result = await run({ env, serviceName, onRetry: (line) => stderr.write(`${line}\n`) })
+  const status = result.exit === 2 ? 'no-key' : result.ok ? 'reached' : result.status === null ? 'network-error' : 'rejected'
+  const lines = redact(result.lines, env[SECRET.name])
+  if (args.json) {
+    stdout.write(`${JSON.stringify({ schema: 1, tool: TOOL, version: VERSION, command: 'check', status, exitCode: result.exit,
+      httpStatus: result.status, workspace: result.workspace, environment: result.environment, lines }, null, 2)}\n`)
+  } else {
+    (result.exit === 1 ? stderr : stdout).write(lines.map((line) => `${line}\n`).join(''))
+  }
+  return result.exit
+}
+
+/** Belt and braces: take every header value out of the lines, even if the server echoed it. */
+function redact(lines, headers) {
+  const secrets = []
+  for (const pair of String(headers ?? '').split(',')) {
+    const value = pair.slice(pair.indexOf('=') + 1).trim()
+    if (pair.includes('=') && value.length >= 4) {
+      secrets.push(value)
+      try { secrets.push(decodeURIComponent(value)) } catch { /* not encoded */ }
+    }
+  }
+  return lines.map((line) => secrets.reduce((out, secret) => out.split(secret).join('***'), String(line)))
+}