@uknows/setup 0.0.0-stage → 0.2.0

package/lib/contract.mjs

@@ -0,0 +1,149 @@
+/*
+ * The UKNOWS install contract. Data only.
+ *
+ * Everything the docs page shows comes from contract-docs.mjs, which
+ * tools/sync-contract.mjs generates from src/docs/install.ts. Import those
+ * values from here and never copy their text into other modules, so a
+ * re-sync updates the whole CLI.
+ *
+ * PINS and CLI below are values the CLI needs that the docs page does not
+ * show. Upstream facts checked on 2026-10-12.
+ */
+
+export * from './contract-docs.mjs'
+import { GO_RELEASES, NODE_REGISTER, PING_URL } from './contract-docs.mjs'
+
+/** The node options that load a register file: --require, or for ES modules the loader hook and --import. */
+const nodeFlag = (esm, register = NODE_REGISTER) => (esm ? `--experimental-loader=@opentelemetry/instrumentation/hook.mjs --import ${register}`
+  : `--require ${register}`)
+
+/**
+ * Known-good OpenTelemetry sets for Python, newest first. core: opentelemetry-sdk and the OTLP exporter. contrib:
+ * opentelemetry-distro and each opentelemetry-instrumentation-* package. minPython: the lowest Python of that
+ * release. protobuf: [lowest, below] that opentelemetry-proto of that release allows. Checked on PyPI on
+ * 2026-10-18 with tools/check-python-sets.mjs (not shipped). 1.27.0 is the last release for protobuf below 5:
+ * uv pip compile with protobuf<5 picks 1.27.0 and 0.48b0.
+ */
+const PYTHON_SETS = [
+  { core: '1.45.1', contrib: '0.66b1', minPython: [3, 10], protobuf: ['5.0', '8.0'] },
+  { core: '1.41.1', contrib: '0.62b1', minPython: [3, 9], protobuf: ['5.0', '7.0'] },
+  { core: '1.27.0', contrib: '0.48b0', minPython: [3, 8], protobuf: ['3.19', '5.0'] },
+]
+
+export const PINS = {
+  node: {
+    /** Same 2 packages as the docs install line. The package manager picks the versions. */
+    packages: ['@opentelemetry/api', '@opentelemetry/auto-instrumentations-node'],
+    /** ESM apps also need this one as a direct dependency (pnpm cannot resolve hook.mjs otherwise). */
+    esmPackage: '@opentelemetry/instrumentation',
+    /** The upstream register line: for a start that this tool cannot give the start file, and in printed steps. */
+    requireFlag: nodeFlag(false),
+    esmFlag: nodeFlag(true),
+    /**
+     * The same options with the start file of this tool (install.ts NODE_REGISTER_FILE): its absolute path in an
+     * image, or ./uknows-otel.cjs in a start script. The ESM loader hook stays: it gives each request its route.
+     */
+    flag: nodeFlag,
+    /**
+     * The npm major version that each Node.js release comes with, from https://nodejs.org/dist/index.json on 18 Oct
+     * 2026: [lowest Node.js version, npm major], newest first. The official node images use that npm. npm on this
+     * computer writes package-lock.json, and npm ci in the image reads it, so a newer npm here stops the run.
+     */
+    npm: [[[24, 0], 11], [[20, 7], 10], [[20, 0], 9], [[19, 3], 9], [[19, 0], 8], [[18, 19], 10], [[18, 14], 9], [[18, 0], 8]],
+  },
+  python: {
+    /** Same 2 packages as the docs install line, pinned like pip freeze would: the newest set. */
+    distro: `opentelemetry-distro==${PYTHON_SETS[0].contrib}`,
+    exporter: `opentelemetry-exporter-otlp-proto-http==${PYTHON_SETS[0].core}`,
+    /** Version of each opentelemetry-instrumentation-* package that opentelemetry-bootstrap prints. */
+    contrib: PYTHON_SETS[0].contrib,
+    /** opentelemetry-distro 0.66b1 needs Python 3.10 or later. */
+    minPython: PYTHON_SETS[0].minPython,
+    /**
+     * requirements.txt and other files with no lock: exact pins from the first set that fits the direct limits of
+     * the file (protobuf, opentelemetry-*) and the Python of the image. The plan says why it is not the newest.
+     */
+    sets: PYTHON_SETS,
+    /**
+     * uv and Poetry projects: floors, not pins, so their resolver picks the newest release that the app allows.
+     * The floors are the oldest set and name a pre-release on purpose, so uv and Poetry allow the b releases.
+     */
+    floors: { core: PYTHON_SETS.at(-1).core, contrib: PYTHON_SETS.at(-1).contrib },
+  },
+  dotnet: {
+    package: 'OpenTelemetry.AutoInstrumentation',
+    version: '1.17.0',
+    /** 1.17.0 targets net8.0 and net462 only. */
+    minNet: 8,
+    /** The build fails when an app uses StackExchange.Redis [2.6.122, 4.0.0) without this package. */
+    redis: { library: 'StackExchange.Redis', package: 'OpenTelemetry.Instrumentation.StackExchangeRedis', version: '1.19.0-beta.1',
+      /** The range of StackExchange.Redis that the build check of OpenTelemetry.AutoInstrumentation 1.17.0 asks for: [min, below). */
+      range: ['2.6.122', '4.0.0'],
+      /**
+       * Packages that bring StackExchange.Redis in. With no packages.lock.json or obj/project.assets.json, 1 of them
+       * in the project counts as StackExchange.Redis. With a lock or assets file, the resolved version decides.
+       */
+      carriers: ['NRedisStack', 'Microsoft.Extensions.Caching.StackExchangeRedis', 'Microsoft.AspNetCore.SignalR.StackExchangeRedis',
+        'Microsoft.AspNetCore.DataProtection.StackExchangeRedis', 'Hangfire.Redis.StackExchange'] },
+    /**
+     * For apps with Azure Monitor and no lock or assets file: the OTLP exporter at the OpenTelemetry version that
+     * OpenTelemetry.AutoInstrumentation 1.17.0 uses. With a lock, the exporter takes the resolved OpenTelemetry version.
+     */
+    otlpExporter: { package: 'OpenTelemetry.Exporter.OpenTelemetryProtocol', version: '1.19.1' },
+  },
+  /**
+   * The OpenTelemetry SDK package of each language, and the lowest version of it that the packages of this tool
+   * need. A package that limits the SDK below this version stops the run (the wrapper stop). Checked on 2026-10-18:
+   * OpenTelemetry.AutoInstrumentation.Runtime.Managed 1.17.0 needs OpenTelemetry 1.19.1.
+   */
+  sdk: {
+    python: { package: 'opentelemetry-sdk', need: '1.45.1' },
+    dotnet: { package: 'OpenTelemetry', need: '1.19.1' },
+    node: { package: '@opentelemetry/sdk-trace-base', need: null },
+  },
+  go: {
+    /**
+     * go get takes the latest modules. go.opentelemetry.io/otel v1.47.0 and otelhttp declare go 1.26.0, so older Go
+     * builders fail (golang images set GOTOOLCHAIN=local). Checked upstream on 2026-10-12.
+     */
+    minGo: [1, 26],
+    /** Below minGo, the go get lines name the versions of install.ts GO_RELEASES. Below the oldest row, Go is too old. */
+    oldestGo: GO_RELEASES.at(-1).go.split('.').map(Number),
+  },
+  php: {
+    /** The 6th setting for PHP. The docs PHP Dockerfile adds it with the 5. */
+    autoload: { name: 'OTEL_PHP_AUTOLOAD_ENABLED', value: 'true' },
+  },
+}
+
+/** The agent channels (--channel), and the form of the registry setting: a host and a path, no scheme and no tag. */
+export const AGENT_CHANNELS = ['stable', 'early']
+/**
+ * The public store of the UKNOWS agent images, a host and a path under a uknows.my name: setup builds
+ * <registry>/agent-<lang>:<channel> from it, for example registry.uknows.my/uknows/agent-node:stable. Anyone can pull
+ * from it without signing in. UKNOWS_AGENT_REGISTRY overrides it. If it were empty, setup would use the agent channel
+ * only when UKNOWS_AGENT_REGISTRY is set, and the publish gate (tools/prepublish.mjs) would stop.
+ */
+export const DEFAULT_AGENT_REGISTRY = 'registry.uknows.my/uknows'
+export const AGENT_REGISTRY = /^[a-z0-9]([a-z0-9.-]*[a-z0-9])?(:\d{1,5})?(\/[a-z0-9]+([._-][a-z0-9]+)*)*$/
+
+export const CLI = {
+  /** Records what setup changed so remove can undo it exactly. Never holds secrets. */
+  manifest: '.uknows/setup.json',
+  /** Override for the ingest address, for a test environment. setup writes it and check sends to it (endpoint.mjs). */
+  endpointEnv: 'UKNOWS_INGEST_ENDPOINT',
+  /** Override for the site address (where check asks which workspace a key sends to), for a test environment. */
+  siteEnv: 'UKNOWS_SITE_URL',
+  /** Override for the app address (where the user watches an app connect), for a test environment. */
+  appEnv: 'UKNOWS_APP_URL',
+  /** The registry and path of the UKNOWS agent images, for --channel. For example registry.example.com/uknows. */
+  agentRegistryEnv: 'UKNOWS_AGENT_REGISTRY',
+  /** The route of the site that says which workspace and environment a key sends to. */
+  pingPath: new URL(PING_URL).pathname,
+  exit: { ok: 0, error: 1, usage: 2, manual: 3 },
+  /**
+   * A run counts as CI when one of these is set and not empty. CI also must not be 0 or false.
+   * --allow-ci lets a bot or an AI agent that opens a pull request apply anyway.
+   */
+  ciEnv: ['CI', 'GITHUB_ACTIONS', 'TF_BUILD', 'GITLAB_CI', 'BUILDKITE', 'CIRCLECI', 'JENKINS_URL', 'TEAMCITY_VERSION', 'BITBUCKET_BUILD_NUMBER', 'CODEBUILD_BUILD_ID'],
+}