@uknows/setup 0.0.0-stage → 0.2.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,210 @@
-# 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 and logs 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 opens your browser. You sign in to UKNOWS and pick the workspace and the environment. Check that the browser shows the same code as the terminal. Your key then comes to the tool by itself: you never create, copy or paste it. The tool checks the key: UKNOWS says which workspace and environment the key sends to, and the tool sends 1 test span. A new key can take up to 2 minutes to reach the data intake of UKNOWS. The tool waits for it.
+3. It shows the whole plan: each file it changes and how many lines, how the agent stays up to date and why, where it stores your key (the app, the resource group and the subscription, a GitHub secret or a Kubernetes secret), the deploy file that would remove the key on the next deploy, the branch and the pull request, and the link where you watch your app connect. To show this, it reads your Azure subscriptions, your GitHub repo or your kubectl contexts. Nothing changes yet.
+4. It asks 1 question: `Do all of this? (Y/n)`. Type d to see every line that changes first. Press Enter to go ahead, or type n to stop.
+5. It does every step and shows 1 line for each, done or failed: it changes the files with your own package manager, stores the key (az, gh and kubectl read it from a pipe, never from a file or a command line), adds the key to the deploy file, and creates a branch with 1 commit of exactly the files it changed, pushes it and opens a pull request. On GitHub, the commit goes up through the GitHub API, so GitHub signs it and a branch rule that requires signed commits passes.
+6. The last line says what is left: merge the pull request and deploy as usual. It ends with the link to the page where you watch your app connect, and the tool opens it in your browser.
+
+While the tool waits for your sign-in, press Enter to open the browser again, p to paste a key instead, or Ctrl+C to stop. Over ssh, or on a computer with no browser, open the link that it prints on any device. If the sign-in is cancelled in the browser or the link expires, it asks if you want to try again or paste a key. With `--paste-key`, it asks for the key instead of opening the browser. The key does not show on the screen, and the tool never writes it to a file in your repo.
+
+If a step cannot be done, for example `az` is not signed in, the plan says why, and the tool prints that step for you at the end. If the tool did not store your key, the last line says so: store the key before you merge, with `npx @uknows/setup key` or the key steps that the tool printed. If your branch has commits that are not on origin yet, the tool creates the branch and the commit but does not push, so your own commits never go out with the 1 yes. It prints the push command. `npx @uknows/setup remove` undoes the change.
+
+With `--step-by-step`, the tool changes the files first, then asks before each of the other steps, one at a time.
+
+The sign-in and the questions come only in a terminal. With `--yes` or `--json`, in a pipeline or without a terminal, the tool signs in to nothing, asks nothing, stores no key and opens no pull request. It prints the steps for you instead.
+
+Run it once on your computer, not in your pipeline. Your pipeline only builds and deploys the change, and sets your key on your app. See "CI/CD and pipelines" below.
+
+Full docs: https://uknows.my/docs
+
+## What it supports
+
+| Stack | What setup does |
+|---|---|
+| Node.js (CommonJS and ES modules) | Adds the OpenTelemetry packages with npm, pnpm or yarn, adds the start file `uknows-otel.cjs` and loads it with `NODE_OPTIONS` or the start script, adds the 5 settings. |
+| Python | Adds the packages to `requirements.txt` or `pyproject.toml`, refreshes `uv.lock` or `poetry.lock` with your own uv or Poetry, starts the app with `opentelemetry-instrument`, adds the 5 settings. In a Dockerfile, it also adds the UKNOWS log bridge, so the logs go to UKNOWS and the app prints exactly what it printed before. |
+| Java (also Keycloak images) | Copies the OpenTelemetry Java agent from its image, pinned by digest, into the Dockerfile, loads it with `JAVA_TOOL_OPTIONS`, adds the 5 settings. |
+| .NET | Adds `OpenTelemetry.AutoInstrumentation` to the project file, refreshes `packages.lock.json` with `dotnet restore`, 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. For Go 1.23, 1.24 and 1.25, the `go get` lines name the OpenTelemetry versions for that Go. |
+| Azure Functions (Node.js v4 model, Python v2 model, .NET isolated) | If the function app does not send to Application Insights, adds 1 line to `host.json`. If it does, or setup cannot tell, adds small UKNOWS hooks to the code of the app instead, so Application Insights stays exactly as it is. The settings and the key go on the function app as app settings. |
+| 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` |
+| Azure Functions | Terraform, Bicep, `az functionapp`, the deploy action, `azure.yaml`, `host.json` |
+| 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, or in a terminal asks to do them for you. Then it checks your deploy files, so the next deploy keeps the key: `--replace-env-vars`, the `environmentVariables` or `yamlConfigPath` of the Container Apps deploy action, Bicep and Terraform templates, App Service slots, ECS task definition files, Kubernetes and GitHub Actions. Each check names the file and line.
+
+For a container app, setup also adds `OTEL_RESOURCE_ATTRIBUTES` with the Azure resource id of the app to the command that deploys it, so UKNOWS links the data to that exact app. It does this only when the deploy command names the subscription, the resource group and the app, and it never changes a value that you set. For an Azure VM, the key steps end with Mark each deploy: a step for the end of each deploy that sends 1 log record with the service name and the resource id of the VM, so UKNOWS knows when a deploy happened.
+
+## 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`. A requirements file gets exact versions that fit your app: for example, `protobuf<5` gets OpenTelemetry 1.27.0, and the plan says why. A uv or Poetry project gets lower limits, and the tool runs `uv lock` (in the workspace root) or `poetry lock` on your computer, so your own resolver picks the versions. Your uv must be the version that your project or your image asks for.
+  - .NET: `OpenTelemetry.AutoInstrumentation` in your project file, plus `OpenTelemetry.Instrumentation.StackExchangeRedis` when your app uses StackExchange.Redis, also through a package such as NRedisStack. With `packages.lock.json`, the tool runs `dotnet restore --force-evaluate` with the `-r` of your Dockerfile. It needs a .NET SDK for your target framework on your computer.
+  - Java: the OpenTelemetry Java agent, copied into your image from the OpenTelemetry image, pinned by its digest. It needs no BuildKit.
+  - Azure Functions with the UKNOWS hooks: the OpenTelemetry packages of the hooks, at the versions that UKNOWS tested. If your app uses another version of the Functions library, the plan says so and asks you to check UKNOWS after the deploy.
+- **Lockfiles.** The tool records the lockfile that uv, Poetry or dotnet rewrites, so `remove` gives it back byte for byte without running the tool again. If the resolver finds no versions that fit, or the lockfile format changes, the tool puts every file back and says why.
+- **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.
+  - Node.js: it adds `uknows-otel.cjs` next to `package.json`. The file starts OpenTelemetry. On SIGTERM it sends the last data, then stops the app, also as PID 1 in a container. An app with its own SIGTERM handler keeps it. In a Dockerfile, a `COPY` line puts the file in the `WORKDIR` of the final stage. If the tool cannot tell the build context or the `WORKDIR`, or `.dockerignore` leaves the file out, it loads the OpenTelemetry register line instead and tells you why. For Python, it changes the start command only when your image installs the file that it changed. With `uv run` or `poetry run`, `opentelemetry-instrument` goes after `run` and its options. A `Procfile` never changes: the tool prints its new line as a step.
+  - Azure Functions: 1 line in `host.json`, `"telemetryMode": "OpenTelemetry"`, when the function app does not send to Application Insights. Otherwise the UKNOWS hooks: `uknows-otel.cjs` for Node.js, loaded through `"main"` in `package.json`; `uknows_otel.py` and 2 lines in `function_app.py` for Python; `UknowsOpenTelemetry.cs` and 2 lines in `Program.cs` for .NET. A Python function app also needs the app setting `PYTHON_ENABLE_WORKER_EXTENSIONS=1`, which setup lists with the other app settings. If the hooks are needed but cannot apply, for example to the Node.js v3 model or the .NET in-process model, setup changes nothing for that app and says why. `--functions-opentelemetry` puts the line in `host.json` instead of the hooks.
+- **Logs.** The setting `OTEL_LOGS_EXPORTER=otlp` sends the logs of your app to UKNOWS. A log line written during a request carries the trace id of that request.
+  - Python: the OpenTelemetry logging handler stays off the root logger (`OTEL_PYTHON_LOG_AUTO_INSTRUMENTATION=false`), and the UKNOWS log bridge sends the log records instead. The bridge is a small folder, `uknows-otel`, that your image copies. Your app prints exactly what it printed before. A Python app that does not start with `opentelemetry-instrument` in its image sends traces only.
+  - .NET: `OTEL_DOTNET_AUTO_LOGS_INCLUDE_FORMATTED_MESSAGE=true`, so a log line keeps its values.
+- **Settings.** It adds 5 settings where your app keeps settings: your Dockerfile, your Kubernetes manifest, or `otel.env` when your repo has it or a file in your repo loads it (a systemd `EnvironmentFile=`, a Compose `env_file:`, `--env-file` or `. ./otel.env`). Otherwise it adds no file and prints the settings in the form of your platform, as a step for you.
+  - `OTEL_SERVICE_NAME`
+  - `OTEL_EXPORTER_OTLP_ENDPOINT`
+  - `OTEL_EXPORTER_OTLP_PROTOCOL`
+  - `OTEL_METRICS_EXPORTER`
+  - `OTEL_LOGS_EXPORTER`
+
+  Some stacks get 1 or 2 more, and the plan lists them: for example, the resource detectors that send the host name of a Node.js or Python app, and the log settings of .NET above.
+- **Updates.** Setup keeps the UKNOWS agent up to date by itself. The plan and the pull request say which way it picked and why:
+  1. **The agent channel**, for Java, .NET and Node.js apps that build from a Dockerfile: 1 `COPY` line that takes the UKNOWS agent from the agent image of the stable channel at each build, and the settings that start it. Packages, lockfiles and the start command stay as they are, and a new agent reaches the app at its next build, so no update pull request is needed. If the agent files are missing or damaged, the app starts without the agent. The agent images are in `registry.uknows.my/uknows`, and your build pulls them without signing in, so a firewall in front of your builds must let them reach `registry.uknows.my` on port 443.
+  2. **Renovate**, for the other apps, when your repo uses Renovate already: a Renovate config file, or a `"renovate"` key in `package.json`. Setup never changes your config. It prints the rule to add for the UKNOWS and OpenTelemetry packages.
+  3. **Dependabot**, on GitHub, when your repo does not use Renovate: `.github/dependabot.yml` and the workflow `.github/workflows/uknows-updates.yml`. Dependabot proposes the OpenTelemetry updates, and the workflow merges them when the checks that your branch rules require pass, then starts your deploy.
+  4. On GitLab, Azure DevOps or Bitbucket, when your repo does not use Renovate: `renovate.json`, and 1 step for you: install the free Mend Renovate app for the repository. Renovate then proposes the UKNOWS and OpenTelemetry updates in 1 pull request, 3 days after each release, and merges it when your checks pass.
+
+  Azure Functions apps get no update bot: the UKNOWS hooks stay on the versions that UKNOWS tested. A repo with no `origin` remote gets none either, and the plan says how to add one. `--update-bot renovate`, `--update-bot dependabot`, `--update-bot none` and `--channel` choose instead of setup, and a rerun keeps the choice. Choosing never stops setup.
+- **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 Azure Monitor, it keeps it and adds UKNOWS beside it. If your app already uses another APM agent, 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. In a terminal, setup stores the key of the environment that you picked when you signed in, or prints the steps for the platform it found in your repo. If `OTEL_EXPORTER_OTLP_HEADERS` is set in your terminal, setup uses that key instead of signing you in, and the plan names its workspace and environment.
+
+For another environment, for example Production, run `npx @uknows/setup key` in the repo. It signs you in again, so you pick that environment, then checks the key and asks to store it in the same way. With `--paste-key`, it asks you to paste that key instead. It changes no file.
+
+Never put the key in a file in your repo.
+
+The tool checks your key as soon as it gets 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 tool uses the network for the sign-in, the check and the steps after it. In a terminal, it reads your Azure subscriptions, your GitHub repo or your kubectl contexts to show the plan. It changes nothing there until you say yes. Setup runs your package manager with install scripts turned off, so no install script of your project or its packages runs. uv lock and dotnet restore can run your own project's build code to read its metadata. 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 key [--path <dir>]  Sign in, check and store the key of another environment.
+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 never signs in. In a terminal with `OTEL_EXPORTER_OTLP_HEADERS` set, it checks that key. |
+| `--step-by-step` | Ask before each step, instead of 1 question for the whole plan. The files change first. |
+| `--paste-key` | Paste your key instead of signing in to UKNOWS in your browser. Also works with `key`. |
+| `--allow-ci` | Apply in a pipeline. Use it only for a bot or an AI agent that opens a pull request. |
+| `--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 `-`. |
+| `--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. |
+| `--update-bot <name>` | `renovate`, `dependabot` or `none`: how the OpenTelemetry packages of your app stay up to date. Dependabot works on GitHub only. Without it, setup picks, as "Updates" says. |
+| `--functions-opentelemetry` | Azure Functions apps: turn on OpenTelemetry in `host.json` instead of adding the UKNOWS hooks. Application Insights then names each request by its route instead of the name of the function. |
+| `--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`.
+
+## CI/CD and pipelines
+
+Run setup once, on your computer, in your repo. Do not run it in your pipeline.
+
+1. Run `npx @uknows/setup` in your repo. Review the diff. Commit the change and open a pull request.
+2. Your pipeline builds and deploys the change as usual. It needs no UKNOWS step to build.
+3. Store your key in the secret store of your pipeline, once for each environment.
+4. In your deploy job, check that the secret is not empty. Set the key on your app before the deploy that uses it.
+5. If your deploy replaces all environment variables, add the key to that list. Otherwise each deploy removes the key.
+
+Setup and remove stop with exit code 2 when they run in a pipeline. A run counts as a pipeline when `CI` (not `0` or `false`), `GITHUB_ACTIONS`, `TF_BUILD`, `GITLAB_CI`, `BUILDKITE`, `CIRCLECI`, `JENKINS_URL`, `TEAMCITY_VERSION`, `BITBUCKET_BUILD_NUMBER` or `CODEBUILD_BUILD_ID` is set. `--dry-run`, `--json` without `--yes`, `check`, `--help` and `--version` still work there.
+
+To check in a pipeline that a repo is set up, run this step. It changes nothing, and it fails unless the repo is set up:
+
+```bash
+npx @uknows/setup --dry-run --json | jq -e '.status == "nothing-to-change" and .exitCode == 0'
+```
+
+A repo is set up when `"status"` is `"nothing-to-change"` and `"exitCode"` is `0`. That needs a commit with `.uknows/setup.json`, which lists every service, or a repo with no step left. Steps that the repo cannot show, such as the settings on your platform, are then listed in `manual[]` but do not change the exit code. In a monorepo, the check plans the services that `.uknows/setup.json` lists, so it needs no `--all`. Other statuses mean that the repo is not set up yet: `"planned"` (setup has changes to make), `"needs-steps"` (exit code 3: setup can change nothing, and the listed steps are yours, such as installing uv), and `"needs-selection"` (exit code 2: pick the services with `--all` or `--path`).
+
+## Exit codes
+
+The exit code describes your repo. Setting your key on your platform, merging the pull request and deploying never change it. In a terminal, a key that UKNOWS refuses ends setup with exit code 1 before anything changes. With `--step-by-step`, the key comes after the files, so the changes to your repo stay. Ctrl+C while setup waits for your sign-in stops it with exit code 130, and nothing changes.
+
+| Code | setup | remove | check |
+|---|---|---|---|
+| 0 | Applied, already set up, or a dry run with no required step. Only the key steps on your platform are left. A frontend-only repo also gets 0. A repo that setup set up gets 0 on the next run, also when steps that the repo cannot show are listed. | Removed, or nothing to remove. | The key works and UKNOWS accepted the test span. |
+| 1 | Stopped or failed, and nothing changed. For example, a dirty repo, a key in a file, another APM agent, a package manager error, or no app found. In a terminal, also a key that UKNOWS refuses. | Failed. | Refused, or a network error. |
+| 2 | Needs your input, and nothing changed. For example, a usage error, a service to pick, no terminal and no `--yes`, or a pipeline without `--allow-ci`. | The same. | No key. |
+| 3 | Applied or planned, but you must do 1 or more steps in your repo before traces flow. The tool prints them. With nothing to change and no `.uknows/setup.json` yet, the status is `"needs-steps"`. | Partial. Some changes are left. | |
+
+`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 without a key.
+
+In `--json`, `ci` says if the run counts as a pipeline, `services[].mode` says how the tool sets up each service, and `manual[].required` says if a step counts toward exit code 3. Advice never does.
+
+## 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. The last line links to the UKNOWS app, where you watch your app connect. To use a test copy of UKNOWS, set its addresses. The test copy's `/docs` page gives the command with them:
+
+```sh
+UKNOWS_SITE_URL=https://uknows-test.example.com UKNOWS_APP_URL=https://app-test.example.com UKNOWS_INGEST_ENDPOINT=https://ingest-test.example.com/otlp npx @uknows/setup
+```
+
+They 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. Setup signs you in at the app address. Without `UKNOWS_APP_URL`, a run with a test address cannot sign you in: it tells you to set `UKNOWS_APP_URL`, asks you to paste the key, prints no link to the app and opens no browser. If the test copy cannot make a sign-in link, setup says so and asks you to paste the key.
+
+`UKNOWS_AGENT_REGISTRY` sets another store of the UKNOWS agent images for the agent channel, as a registry and path, for example `registry.example.com/uknows`.
+
+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_APP_URL=https://app-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
+}