@uknows/setup 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 the UKNOWS authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# @uknows/setup
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Add standard OpenTelemetry to your app, so it sends traces to UKNOWS.
+
+Run it in the root folder of your repo:
+
+```sh
+npx @uknows/setup
+```
+
+1. It finds each service in your repo: its language, its framework, its Dockerfile or start command, and where it runs.
+2. It shows the plan: the diff of every file it will change and the packages it will add. Nothing changes yet.
+3. You approve once. Press Enter, or type n to stop.
+4. It makes the change with your own files and your own package manager.
+5. It asks for your key and checks it: UKNOWS says which workspace and environment the key sends to, and the tool sends 1 test span. The key does not show on the screen and the tool never writes it to a file.
+
+Then commit, open a pull request and deploy as usual. `npx @uknows/setup remove` undoes the change.
+
+Full docs: https://uknows.defacloud.my/docs
+
+## What it supports
+
+| Stack | What setup does |
+|---|---|
+| Node.js (CommonJS and ES modules) | Adds the OpenTelemetry packages with npm, pnpm or yarn, loads them with `NODE_OPTIONS`, adds the 5 settings. |
+| Python | Adds the packages to `requirements.txt` or `pyproject.toml`, starts the app with `opentelemetry-instrument`, adds the 5 settings. |
+| Java | Adds the pinned OpenTelemetry Java agent to the Dockerfile (Docker checks its checksum), loads it with `JAVA_TOOL_OPTIONS`, adds the 5 settings. |
+| .NET | Adds `OpenTelemetry.AutoInstrumentation` to the project file, starts the app with `instrument.sh`, adds the 5 settings. |
+| Go, PHP, Ruby | Adds the 5 settings, then prints the code steps for you to do. |
+| Already uses OpenTelemetry | Adds only the settings. Keeps a Collector address and shows what to change. |
+
+| Where it runs | Found from |
+|---|---|
+| Docker and VMs (Amazon EC2, Azure VMs, Alibaba ECS and others) | Dockerfile, Compose, systemd, cloud-init, Alibaba ECS in Terraform |
+| Kubernetes (AKS, EKS, GKE, Alibaba ACK) | Kubernetes manifests, Helm charts, kubectl and helm deploy steps, Alibaba ACK in Terraform |
+| Azure Container Apps | Terraform, Bicep, `az containerapp`, the deploy action, `azure.yaml` |
+| Azure App Service | Terraform, Bicep, `az webapp`, the deploy action, `azure.yaml` |
+| AWS ECS and Fargate | Terraform, CloudFormation, task definition files, `aws ecs`, the deploy action, Copilot |
+| Alibaba SAE | Terraform, `aliyun sae`, SAE addresses |
+
+For each place it finds, it prints the steps to set your key once as a secret there.
+
+## What it changes
+
+- **Packages.** It adds the upstream OpenTelemetry packages for your stack:
+  - Node.js: `@opentelemetry/api` and `@opentelemetry/auto-instrumentations-node`, with npm, pnpm or yarn.
+  - Python: `opentelemetry-distro`, the OTLP exporter and the packages for your libraries, in your requirements file or `pyproject.toml`.
+  - .NET: `OpenTelemetry.AutoInstrumentation` in your project file.
+  - Java: the OpenTelemetry Java agent, added to your Dockerfile with a pinned checksum.
+- **Startup.** It loads OpenTelemetry when your app starts, in your Dockerfile or start script. New Dockerfile lines go after your last `RUN`, so build steps never load OpenTelemetry. Lines you already have, such as `NODE_OPTIONS`, stay as they are. For Python, it changes the start command only when your image installs the file that it changed.
+- **Settings.** It adds 5 settings where your app keeps settings: your Dockerfile, your Kubernetes manifest or `otel.env`.
+  - `OTEL_SERVICE_NAME`
+  - `OTEL_EXPORTER_OTLP_ENDPOINT`
+  - `OTEL_EXPORTER_OTLP_PROTOCOL`
+  - `OTEL_METRICS_EXPORTER`
+  - `OTEL_LOGS_EXPORTER`
+- **A record.** It writes `.uknows/setup.json`, so `remove` can undo exactly what it changed. This file has no secrets. Commit it.
+
+For Go, PHP and Ruby, it adds the settings and prints the steps to do by hand.
+
+If your app already uses OpenTelemetry, it adds only the settings. If your app sends data to another address, such as an OpenTelemetry Collector, it keeps that address and its settings and shows you what to change. If your app uses another APM agent, such as Datadog or New Relic, it stops and explains your options.
+
+A frontend, such as a React app that nginx serves, gets no change. UKNOWS traces server apps.
+
+## Your key
+
+Your key goes in `OTEL_EXPORTER_OTLP_HEADERS`. Set it once for each environment as a secret on your platform. After setup, the tool prints the steps for the platform it found in your repo.
+
+Never put the key in a file in your repo.
+
+Right after setup, the tool asks for your key and checks it. To check it again later, run these 3 lines in bash. Paste your key when it asks. The key does not show on the screen and does not go in your shell history.
+
+```sh
+read -rsp 'Paste your UKNOWS key: ' UKNOWS_KEY; echo
+export OTEL_EXPORTER_OTLP_HEADERS="x-uknows-key=$UKNOWS_KEY"
+npx @uknows/setup check
+```
+
+`check` asks UKNOWS which workspace and environment the key sends to, then sends 1 test span. A key that UKNOWS refuses gets its reason: not known, revoked, or a paused workspace. Apart from your package manager, the check is the only part of the tool that uses the network. Setup runs your package manager with install scripts turned off, so no code from your project or its packages runs. With a lockfile, npm and pnpm change only `package.json` and the lockfile.
+
+## Commands and options
+
+```text
+npx @uknows/setup [setup] [options]   Find your app, show the plan, then apply it.
+npx @uknows/setup remove [options]    Undo what setup changed.
+npx @uknows/setup check [--json]      Check your key and send 1 test span.
+```
+
+| Option | What it does |
+|---|---|
+| `--dry-run` | Show the plan. Change nothing. |
+| `--yes`, `-y` | Apply without asking. It never asks any question and does not check the key, so it is safe in scripts. |
+| `--path <folder>` | The folder to set up. The default is the current folder. |
+| `--all` | Set up every service folder in a monorepo. Each one gets its own `OTEL_SERVICE_NAME`. |
+| `--service-name <name>` | The name of the service in UKNOWS. Use lowercase letters, digits and `-`. |
+| `--json` | Print a JSON report. Without `--yes`, setup only plans. |
+| `--force` | Run even when the repo has changes that are not committed. With `remove`, delete the record even when some changes could not be undone. |
+| `--check` | The same as the `check` command. |
+
+Setup stops when your repo has changes that are not committed, so you can review exactly what it changed with `git diff`. Commit or stash your changes first, or use `--force`.
+
+With `--path`, setup still reads the deploy files at the top of the git repo, such as `k8s/` and `.github/workflows/`, to find where your app runs. If the folder is part of a JavaScript workspace, or its .NET package versions are set in a file above it, setup changes nothing and asks you to run it from the repo root. There, pick the service from the list, or use `--all`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Done, or nothing to do. |
+| 1 | Stopped or failed. Nothing changed. For example, another APM agent, a dirty repo, a key in a file that setup would change, or a package manager error. |
+| 2 | Usage error, or you need to pick a service. In a script, pass `--yes`, and `--all` or `--path` for a monorepo. |
+| 3 | You need to do 1 or more steps by hand. The tool prints them. |
+
+## Undo
+
+```sh
+npx @uknows/setup remove
+```
+
+`remove` runs your package manager to remove the packages that setup added. Then it puts back every line that setup changed and deletes the files that setup created. If you changed those lines after setup, it skips that file, tells you, and keeps the record so you can run `remove` again. If your package manager does not write `package.json` or the lockfile back byte for byte, `remove` names the file, so you can check it with `git diff`.
+
+## Requirements
+
+Node.js 18 or later, on macOS, Linux or Windows. The tool has no dependencies.
+
+## Test addresses
+
+Setup writes `OTEL_EXPORTER_OTLP_ENDPOINT` with the UKNOWS ingest address, and check asks the UKNOWS site about your key. To use a test copy of UKNOWS, set both addresses. The test copy's `/docs` page gives the command with them:
+
+```sh
+UKNOWS_SITE_URL=https://uknows-test.example.com UKNOWS_INGEST_ENDPOINT=https://ingest-test.example.com/otlp npx @uknows/setup
+```
+
+Both must be https addresses. On your own computer, `http://127.0.0.1` and `http://localhost` work too. With only `UKNOWS_INGEST_ENDPOINT`, check sends the test span but does not ask which workspace the key sends to.
+
+To build a package for a test environment, bake its addresses in, the same build settings that `/docs` uses. Do not commit the result:
+
+```sh
+VITE_UKNOWS_SITE_URL=https://uknows-test.example.com \
+VITE_UKNOWS_INGEST_HOST=ingest-test.example.com \
+node tools/sync-contract.mjs
+npm pack
+git checkout lib/contract-docs.mjs
+```

package/bin/uknows-setup.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// npx @uknows/setup: add OpenTelemetry to an app so it sends traces to UKNOWS.
+const major = Number(process.versions.node.split('.')[0])
+if (major < 18) {
+  console.error(`uknows-setup needs Node.js 18 or later. This is Node.js ${process.versions.node}.`)
+  process.exit(1)
+}
+try {
+  const { main } = await import('../lib/cli.mjs')
+  process.exitCode = await main(process.argv.slice(2))
+} catch (error) {
+  console.error(`Something went wrong: ${error?.message ?? error}`)
+  process.exitCode = 1
+}

package/lib/check.mjs

@@ -0,0 +1,211 @@
+/*
+ * 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 { BASH_STEP, CLI, KEY_CHECK, KEY_PROMPT, SECRET, TROUBLESHOOTING } 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))
+
+/**
+ * Check the key in OTEL_EXPORTER_OTLP_HEADERS from env (or options.headers), then send 1 test span.
+ * @param {{env?: Record<string, string|undefined>, headers?: string, timeoutMs?: number}} [options]
+ * @returns {Promise<import('./types.mjs').CheckResult>}
+ */
+export async function runCheck(options = {}) {
+  const { env = process.env, timeoutMs = 10000 } = options
+  const raw = options.headers ?? env[SECRET.name]
+  if (!raw || !raw.trim()) {
+    return result(2, null, [`${SECRET.name} is not set in this terminal.`, BASH_STEP,
+      'Run these 3 lines. Paste your key when it asks. The key does not show on the screen.',
+      `  ${KEY_PROMPT}`, `  export ${SECRET.name}="${SECRET.header}=$UKNOWS_KEY"`, '  npx @uknows/setup check'])
+  }
+  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.`])
+
+  // 1. Which workspace and environment the key sends to.
+  let ping = null
+  const lines = [], after = []
+  if (sameUknows(env)) {
+    const answer = await request(new URL(`${site}${CLI.pingPath}`), 'GET', { [SECRET.header]: headers[keyName] }, null, timeoutMs)
+    ping = explainPing(answer, site, redact)
+    if (ping.stop) return { ...result(1, answer.status ?? null, ping.lines), keyState: ping.keyState ?? null }
+    lines.push(...ping.lines)
+  } 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.
+  const url = new URL(`${endpoint}/v1/traces`)
+  const response = await request(url, 'POST', { ...headers, 'content-type': 'application/json' }, testSpan(env), timeoutMs)
+  if (response.error) return { ...result(1, null, [...lines, ...explainNetworkError(response.error, url, timeoutMs, 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. */
+export function explainPing({ status, error, body }, site, redact = (x) => x) {
+  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.')
+    return { stop: false, workspace, environment, keyState: clean(data.keyState, redact), 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. 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.']
+  const seconds = Math.round(timeoutMs / 100) / 10
+  const lines = [
+    code === 'ENOTFOUND' || code === 'EAI_AGAIN' ? `Cannot find ${host}. Check DNS.`
+      : code === 'ECONNREFUSED' ? `${host} refused the connection on port ${port}.`
+      : code === 'UKNOWS_TIMEOUT' || code === 'ETIMEDOUT' ? `No answer in ${seconds} ${seconds === 1 ? 'second' : 'seconds'}.`
+      : code === 'ECONNRESET' || code === 'EPIPE' ? `The connection to ${host} closed before UKNOWS answered.`
+      : code === 'EHOSTUNREACH' || code === 'ENETUNREACH' ? `Cannot reach ${host}. Check your network.`
+      : /^ERR_INVALID_(?:CHAR|HTTP_TOKEN)/.test(code) ? `${SECRET.name} has a character that is not allowed in a header.`
+      : `Cannot reach ${host} (${code || 'unknown error'}).`,
+  ]
+  if (proxy) lines.push('This tool does not use HTTPS_PROXY. Run the check on a network that can reach UKNOWS directly.')
+  return lines
+}
+
+// --- request and response ---------------------------------------------------------
+
+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 key (status 403).`, ...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) {
+  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 || '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 ------------------------------------------------------------------------
+
+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 } }