@uknows/setup 0.1.0 → 0.2.0

package/lib/updates.mjs

@@ -0,0 +1,398 @@
+// How setup keeps the UKNOWS agent and its OpenTelemetry packages up to date. On by default, so nobody has to do it:
+//
+//   1. The agent channel, for a Java, .NET or Node.js service that builds from a Dockerfile, when the store of the UKNOWS
+//      agent images is known (contract DEFAULT_AGENT_REGISTRY, or UKNOWS_AGENT_REGISTRY). Each build copies the newest
+//      stable agent (stacks/channel.mjs), so the repo needs no update bot for it. The engine picks this before it plans.
+//   2. Renovate, for the services on the package route, when the repo already uses Renovate: a config file that Renovate
+//      reads, or a "renovate" key in package.json.
+//   3. Otherwise Dependabot and the workflow that merges its pull requests, when the repo is on GitHub. On GitLab, Azure
+//      DevOps, Bitbucket or another host with no Renovate, setup adds renovate.json and says that automatic updates need
+//      Renovate there, and how to add it in 1 step. With no origin remote, it adds nothing and says how to choose.
+//
+// --update-bot renovate, dependabot or none, and --channel, are explicit choices that skip this order. Choosing an
+// update method never stops setup and never changes its exit code. The plan and the pull request say which method was
+// chosen and why. Azure Functions apps get no update bot: their hooks stay on the versions that UKNOWS tested.
+//
+// Renovate (renovate.json at the top of the repo): only UKNOWS and OpenTelemetry packages, in 1 pull request, 3 days
+// after each release (minimumReleaseAge, the cooldown), merged by Renovate when the checks pass, where the branch rules
+// let it. It updates the whole group in 1 resolve, so the OpenTelemetry packages of Poetry, uv, pip, npm and NuGet
+// projects move together (Dependabot moves 1 package at a time, and on Poetry it finds "No update possible"). Its merges
+// are made by the Renovate app, so they start the deploy workflows like any push. For uv projects, a new version inside
+// the range of pyproject.toml refreshes uv.lock (rangeStrategy update-lockfile). It needs the Renovate app (or a Renovate
+// run) on the repo.
+//
+// Dependabot (GitHub only) adds:
+//   .github/dependabot.yml                  1 entry per service folder: only OpenTelemetry packages, grouped in 1 pull
+//                                           request, checked every day
+//   .github/workflows/uknows-updates.yml    merges those Dependabot pull requests when the checks that the branch rules
+//                                           ask for pass (GitHub auto-merge), then starts the deploy workflows
+// Dependabot's "daily" runs Monday to Friday only, so a release on a Friday would wait until Monday. A cron schedule runs
+// every day. Dependabot allows at most 1 run in 24 hours (measured: a cronjob of "30 1,13 * * *" is refused), so an
+// update is proposed at most 24 hours after a release.
+// The job has no checkout, so every gh command names the repo (gh workflow run reads it from git otherwise: measured).
+// A merge made with the workflow's own token starts no other workflow (GitHub's rule), except workflow_dispatch. So the
+// workflow waits for the merge and then starts the deploy workflows that it found here: those with workflow_dispatch
+// that also run on a push to the default branch. Where the branch rules ask for a review, the workflow stops at
+// "waits for a review" and runs again when the review is in.
+// An update is never merged on a branch without a required check: gh merges a pull request with no unmet rule at once,
+// even while its build still runs.
+import { posix } from 'node:path'
+
+/** What Dependabot calls the package manager of a service, and the names of the OpenTelemetry packages there. */
+export function ecosystemOf(service, view) {
+  const at = (name) => (service.dir === '.' ? name : `${service.dir}/${name}`)
+  if (service.lang === 'node') return { ecosystem: 'npm', patterns: ['@opentelemetry/*'] }
+  if (service.lang === 'python') {
+    const uv = view.exists(at('uv.lock')) || view.exists('uv.lock')
+    return { ecosystem: uv ? 'uv' : 'pip', patterns: ['opentelemetry-*'] }
+  }
+  if (service.lang === 'dotnet') return { ecosystem: 'nuget', patterns: ['OpenTelemetry', 'OpenTelemetry.*'] }
+  return null
+}
+
+const WORKFLOW = '.github/workflows/uknows-updates.yml'
+const CONFIG = '.github/dependabot.yml'
+/** The commit of dependabot/fetch-metadata v3.1.0 (20 Apr 2026). */
+const FETCH_METADATA = 'dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0'
+/** Every day at 01:30 UTC. */
+export const CRON = '30 1 * * *'
+
+/** What --update-bot takes: an update bot, or none for no automatic updates. Without it, setup picks (see above). */
+export const UPDATE_BOTS = ['renovate', 'dependabot', 'none']
+const RENOVATE = 'renovate.json'
+/**
+ * Files where a repo keeps its own Renovate config, in the order Renovate reads them (docs.renovatebot.com, configuration
+ * options, "Locations for configuration filenames"), before package.json with a "renovate" key.
+ */
+export const RENOVATE_FILES = ['renovate.json', 'renovate.jsonc', 'renovate.json5', '.github/renovate.json', '.github/renovate.jsonc',
+  '.github/renovate.json5', '.gitlab/renovate.json', '.gitlab/renovate.jsonc', '.gitlab/renovate.json5', '.renovaterc', '.renovaterc.json',
+  '.renovaterc.jsonc', '.renovaterc.json5']
+
+/** The Renovate config of the repo: the first file that Renovate would read, or package.json with a "renovate" key, or null. */
+export function renovateConfigOf(read) {
+  const file = RENOVATE_FILES.find((f) => read(f) !== null)
+  if (file) return file
+  try {
+    const pkg = JSON.parse(read('package.json') ?? 'null')
+    return pkg && typeof pkg === 'object' && 'renovate' in pkg ? 'package.json' : null
+  } catch { return null }
+}
+
+/**
+ * The text of a Renovate config, to look for a rule of OpenTelemetry in it. In package.json only the "renovate" key
+ * counts: the dependencies there name the OpenTelemetry packages after setup, and that is no Renovate rule.
+ */
+function renovateTextOf(file, text) {
+  if (file !== 'package.json') return text ?? ''
+  try { return JSON.stringify(JSON.parse(text ?? 'null')?.renovate ?? null) } catch { return '' }
+}
+
+/** The names of the git hosts, as the plan says them. */
+const HOST_NAMES = { github: 'GitHub', gitlab: 'GitLab', 'azure-devops': 'Azure DevOps', bitbucket: 'Bitbucket', other: 'your git host' }
+
+/** Where to add Renovate in 1 step, for a host with no Renovate (Mend Renovate Community Cloud is free). */
+const RENOVATE_APP = {
+  gitlab: 'Install the free Mend Renovate app for the group of this repository at https://developer.mend.io.',
+  'azure-devops': 'Install the free Mend Renovate app for this repository at https://developer.mend.io.',
+  bitbucket: 'Install the free Mend Renovate app for this repository at https://developer.mend.io.',
+  other: 'Run Renovate for this repository, as https://docs.renovatebot.com describes for your git host.',
+}
+/** The cooldown: an update is proposed when the release is 3 days old (owner decision, 22 Oct 2026). */
+export const MINIMUM_RELEASE_AGE = '3 days'
+/** The UKNOWS packages, beside the OpenTelemetry ones. */
+const UKNOWS_PATTERNS = ['@uknows/**']
+
+/** renovate.json: every other package stays as it is; UKNOWS and OpenTelemetry in 1 group that merges itself. */
+export function renovateConfig(patterns) {
+  const names = [...new Set([...patterns.map((p) => p.replace(/^@opentelemetry\/\*$/, '@opentelemetry/**')), ...UKNOWS_PATTERNS])]
+  return `${JSON.stringify({
+    $schema: 'https://docs.renovatebot.com/renovate-schema.json',
+    description: 'Added by npx @uknows/setup: UKNOWS and OpenTelemetry updates only, in 1 pull request, 3 days after each release. Renovate merges it when your checks pass, where your branch rules let it.',
+    dependencyDashboard: false,
+    packageRules: [
+      { description: 'Other packages: this config proposes nothing for them.', matchPackageNames: ['*'], enabled: false },
+      { description: 'UKNOWS and OpenTelemetry: 1 pull request, 3 days after each release, merged when the checks pass.',
+        matchPackageNames: names, enabled: true, groupName: 'OpenTelemetry', minimumReleaseAge: MINIMUM_RELEASE_AGE,
+        automerge: true, platformAutomerge: false },
+      // The OpenTelemetry instrumentation packages of Python have beta versions only (0.66b1). Renovate skips beta
+      // versions by default, so it moved the core packages alone, and pip could not install the mix (bench, 23 Oct
+      // 2026). A package whose current version is a beta takes the next beta.
+      { description: 'OpenTelemetry for Python: a package on a beta version (such as 0.65b0) takes the next beta, with the others.',
+        matchDatasources: ['pypi'], matchPackageNames: names, matchCurrentVersion: '/b[0-9]+$/', ignoreUnstable: false },
+      // uv projects: Renovate's pep621 manager defaults to "replace", which leaves the >= ranges that setup writes in
+      // pyproject.toml alone and never refreshes uv.lock, so a uv project got no update at all (Renovate runner, 25 Oct
+      // 2026: none with the default, all 13 packages with update-lockfile). update-lockfile refreshes uv.lock for a version
+      // inside the range, and replaces the range for a version outside it. Only for pep621: npm and Poetry refresh their
+      // lock files this way by default, pip requirements hold exact versions, and with update-lockfile Renovate finds no
+      // NuGet update at all (local Renovate 44.176.3 lookups, 25 Oct 2026).
+      { description: 'OpenTelemetry for uv: a new version inside the range of pyproject.toml refreshes uv.lock.',
+        matchManagers: ['pep621'], matchPackageNames: names, rangeStrategy: 'update-lockfile' },
+    ],
+  }, null, 2)}\n`
+}
+
+export function dependabotEntries(services, view) {
+  const entries = []
+  for (const s of services) {
+    const e = ecosystemOf(s, view)
+    if (!e) continue
+    const directory = s.dir === '.' ? '/' : `/${posix.normalize(s.dir)}`
+    if (entries.some((x) => x.ecosystem === e.ecosystem && x.directory === directory)) continue
+    entries.push({ ...e, directory })
+  }
+  return entries
+}
+
+export function dependabotYaml(entries) {
+  return [
+    '# Added by npx @uknows/setup: OpenTelemetry package updates, in 1 pull request per folder, checked every day.',
+    '# .github/workflows/uknows-updates.yml merges them when the checks pass, then starts the deploy.',
+    'version: 2',
+    'updates:',
+    ...entries.flatMap((e) => [
+      `  - package-ecosystem: ${e.ecosystem}`,
+      `    directory: "${e.directory}"`,
+      '    schedule:',
+      '      interval: cron',
+      `      cronjob: "${CRON}"`,
+      '    allow:',
+      ...e.patterns.map((p) => `      - dependency-name: "${p}"`),
+      '    groups:',
+      '      opentelemetry:',
+      '        patterns: ["*"]',
+    ]),
+    '',
+  ].join('\n')
+}
+
+/** The deploy workflows to start after a merge: workflow_dispatch, and a push to the default branch (or any push). */
+export function deployWorkflows(view) {
+  const out = []
+  for (const file of view.files().filter((f) => /^\.github\/workflows\/[^/]+\.ya?ml$/.test(f))) {
+    if (file === WORKFLOW) continue
+    const text = view.read(file) ?? ''
+    if (!/^\s*workflow_dispatch\s*:/m.test(text) || !/^\s*push\s*:/m.test(text)) continue
+    out.push(posix.basename(file))
+  }
+  return out
+}
+
+export function updatesWorkflow(deploy, patterns) {
+  const cases = [...new Set(patterns)].join('|')
+  return `name: UKNOWS updates
+
+# Added by npx @uknows/setup. Merges the Dependabot pull requests that update only OpenTelemetry packages when
+# the checks that your branch rules ask for pass (GitHub auto-merge), then starts the deploy. Other pull requests are left
+# alone. Needs "Allow auto-merge" in the repository settings, and a branch rule that requires your build check: without
+# a required check, nothing is merged. Where your rules ask for a review, the update waits for it.
+
+on:
+  pull_request:
+  pull_request_review:
+    types: [submitted]
+
+permissions:
+  contents: write
+  pull-requests: write
+  actions: write
+
+concurrency:
+  group: uknows-updates-\${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  merge:
+    if: github.event.pull_request.user.login == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    env:
+      GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+      PR: \${{ github.event.pull_request.html_url }}
+      BASE: \${{ github.event.pull_request.base.ref }}
+      REPO: \${{ github.repository }}
+      DEPLOY_WORKFLOWS: "${deploy.join(' ')}"
+    steps:
+      - id: meta
+        uses: ${FETCH_METADATA}
+
+      - name: Check that the pull request updates only OpenTelemetry packages
+        id: only
+        env:
+          NAMES: \${{ steps.meta.outputs.dependency-names }}
+        run: |
+          ok=true
+          for name in $(printf '%s' "$NAMES" | tr ',' ' '); do
+            case "$name" in ${cases}) ;; *) ok=false; echo "Not an OpenTelemetry package: $name" ;; esac
+          done
+          echo "ok=$ok" >> "$GITHUB_OUTPUT"
+
+      - name: Check that the branch asks for a passing check
+        id: rule
+        if: steps.only.outputs.ok == 'true'
+        run: |
+          classic=$(gh api "repos/$REPO/branches/$BASE" --jq '.protection.required_status_checks.contexts // [] | length' || echo 0)
+          rules=$(gh api "repos/$REPO/rules/branches/$BASE" --jq '[.[] | select(.type == "required_status_checks")] | length' || echo 0)
+          echo "Required checks on $BASE: \${classic:-0} from branch protection, \${rules:-0} from rulesets."
+          if [ "\${classic:-0}" -gt 0 ] || [ "\${rules:-0}" -gt 0 ]; then echo "ok=true" >> "$GITHUB_OUTPUT"; exit 0; fi
+          echo "::warning::$BASE has no required check, so this update is not merged by itself. Add a branch rule that requires your build check."
+          echo "ok=false" >> "$GITHUB_OUTPUT"
+
+      - name: Merge when the checks pass, then deploy
+        if: steps.only.outputs.ok == 'true' && steps.rule.outputs.ok == 'true'
+        run: |
+          now() { gh pr view "$PR" --json state,reviewDecision,autoMergeRequest --jq '[.state, (if (.reviewDecision // "") == "" then "NONE" else .reviewDecision end), (if .autoMergeRequest then "AUTO" else "MANUAL" end)] | join(" ")'; }
+          read -r state review auto <<< "$(now)"
+          if [ "$state" = OPEN ] && [ "$auto" = MANUAL ]; then
+            gh pr merge --auto --squash "$PR" || { echo "::error::Could not turn on auto-merge. Turn on Allow auto-merge in the repository settings."; exit 1; }
+          fi
+          for i in $(seq 1 110); do
+            read -r state review auto <<< "$(now)"
+            [ "$state" = OPEN ] || break
+            if [ "$review" = REVIEW_REQUIRED ] || [ "$review" = CHANGES_REQUESTED ]; then
+              echo "::notice::The update waits for a review: $PR"; exit 0
+            fi
+            sleep 30
+          done
+          if [ "$state" != MERGED ]; then echo "The pull request is $state. Nothing to deploy now."; exit 0; fi
+          [ -n "$DEPLOY_WORKFLOWS" ] || { echo "Merged. No deploy workflow with workflow_dispatch was found: the next push deploys."; exit 0; }
+          for wf in $DEPLOY_WORKFLOWS; do gh workflow run "$wf" --repo "$REPO" --ref "$BASE" && echo "Merged, and started $wf."; done
+`
+}
+
+/**
+ * How this run keeps the agent up to date. Returns {edits, summary, manual, notes, methods, pr, homes, channelLine}:
+ * methods is the list of {method, why, services} for the plan and the JSON report, pr the sentences for the pull
+ * request. homes names the services that the lines are about: channelLine about homes.channel, every other line about
+ * homes.packages, so a plan shows each line with the service it is about.
+ *   bot   --update-bot: 'renovate', 'dependabot' or 'none'. null: setup picks (the order at the top of this file).
+ *   recorded  the bot that .uknows/setup.json records from an earlier run: a rerun keeps it, unless --update-bot chose.
+ *   host  where the origin remote is (git.mjs gitHost): 'github', 'gitlab', 'azure-devops', 'bitbucket', 'other' or null.
+ * Never throws: an update method is never a reason to stop setup.
+ * @param {{s: object, stack: string, mode: string, name?: string, channel?: {name: string}}[]} plans
+ */
+export function updatesPlan(plans, { ws, repo, bot = null, recorded = null, host = null }) {
+  const out = { edits: [], summary: [], manual: [], notes: [], methods: [], pr: [], bot: null, homes: { channel: [], packages: [] }, channelLine: null }
+  try {
+    return planUpdates(plans, { ws, repo, bot, recorded, host }, out)
+  } catch (error) {
+    out.notes.push(`Setup could not add automatic updates (${error.message}). Your app is set up. To add them, run npx @uknows/setup --update-bot renovate or --update-bot dependabot.`)
+    return out
+  }
+}
+
+const listNames = (names) => (names.length > 1 ? `${names.slice(0, -1).join(', ')} and ${names.at(-1)}` : names[0] ?? '')
+
+function planUpdates(plans, { ws, repo, bot, recorded, host }, out) {
+  const chosen = bot ? `you chose --update-bot ${bot}` : recorded ? 'setup chose it before (.uknows/setup.json)' : null
+  bot ??= recorded
+  if (bot === 'none') {
+    out.summary.push(`Keep the agent up to date: off, because ${chosen}. To get new versions, run npx @uknows/setup again.`)
+    out.methods.push({ method: 'none', why: chosen, services: plans.map((p) => p.name ?? p.s.name) })
+    out.homes.packages = out.methods[0].services
+    out.bot = 'none'
+    return out
+  }
+  // 1. The agent channel: each build copies the newest agent of its channel.
+  const channel = plans.filter((p) => p.mode === 'channel')
+  if (channel.length) {
+    const names = channel.map((p) => p.name ?? p.s.name)
+    const which = [...new Set(channel.map((p) => p.channel?.name ?? 'stable'))].join(' and ')
+    const why = bot === null && channel.every((p) => p.channelDefault) ? `${listNames(names)} ${names.length > 1 ? 'build' : 'builds'} from a Dockerfile` : 'you chose --channel'
+    out.channelLine = `Keep the agent up to date: the UKNOWS agent channel (${which}) for ${listNames(names)}, because ${why}. Each build copies the newest ${which} agent, so no update pull request is needed.`
+    out.summary.push(out.channelLine)
+    out.homes.channel = names
+    out.methods.push({ method: 'channel', why, services: names })
+    out.pr.push(`Keeps the UKNOWS agent up to date with the agent channel (${which}): each build of ${listNames(names)} copies the newest ${which} agent, because ${why}. No update pull request is needed.`)
+  }
+  // 2 and 3. The services on the package route. Azure Functions apps keep the versions that UKNOWS tested.
+  const packaged = plans.filter((p) => p.mode === 'standard' && !p.s.functions)
+  const entries = dependabotEntries(packaged.map((p) => p.s), repo)
+  if (!entries.length) return out
+  const names = packaged.filter((p) => ecosystemOf(p.s, repo)).map((p) => p.name ?? p.s.name)
+  out.homes.packages = names
+  const own = renovateConfigOf((f) => ws.read(f))
+  let method, why
+  if (bot === 'renovate' || bot === 'dependabot') { method = bot; why = chosen }
+  else if (own) { method = 'renovate'; why = `this repo already uses Renovate (${own})` }
+  else if (host === 'github') { method = 'dependabot'; why = 'this repo is on GitHub and does not use Renovate' }
+  else if (host) { method = 'renovate-app'; why = `automatic updates on ${HOST_NAMES[host] ?? HOST_NAMES.other} need Renovate, and this repo does not use it yet` }
+  else {
+    out.summary.push(`Keep the agent up to date: not added for ${listNames(names)}, because this repo has no origin remote, so setup cannot tell where it is hosted.`)
+    out.notes.push('To add automatic updates: on GitHub, run npx @uknows/setup --update-bot dependabot. Anywhere else, run npx @uknows/setup --update-bot renovate and add Renovate to the repository.')
+    out.methods.push({ method: 'not-added', why: 'this repo has no origin remote', services: names })
+    return out
+  }
+  const label = method === 'dependabot' ? 'Dependabot' : 'Renovate'
+  out.summary.push(`Keep the agent up to date: ${label} for ${listNames(names)}, because ${why}.`)
+  out.methods.push({ method, why, services: names })
+  out.bot = method === 'dependabot' ? 'dependabot' : 'renovate'
+  if (method === 'dependabot') {
+    dependabotPlan(entries, { ws, repo }, out)
+    out.pr.push(`Keeps the OpenTelemetry packages up to date with Dependabot, because ${why}. Dependabot proposes OpenTelemetry updates every day. Each update merges when your build check passes, then deploys. Where your branch rules ask for a review, it waits for that review.`)
+    return out
+  }
+  renovatePlan(entries, { ws, repo, own, app: method === 'renovate' && !own }, out)
+  if (method === 'renovate-app') {
+    out.manual.push({ title: `Add Renovate in 1 step: automatic updates on ${HOST_NAMES[host] ?? HOST_NAMES.other} need it`, required: false,
+      lines: [RENOVATE_APP[host] ?? RENOVATE_APP.other, `${RENOVATE} is in this change, so Renovate opens no onboarding pull request and proposes only the UKNOWS and OpenTelemetry updates.`] })
+    out.pr.push(`Keeps the UKNOWS and OpenTelemetry packages up to date with Renovate, because ${why}. ${RENOVATE_APP[host] ?? RENOVATE_APP.other} Renovate then proposes these updates in 1 pull request, 3 days after each release, and merges it when your build check passes.`)
+    return out
+  }
+  out.pr.push(`Keeps the UKNOWS and OpenTelemetry packages up to date with Renovate, because ${why}. Renovate proposes these updates in 1 pull request, 3 days after each release, and merges it when your build check passes. Where your branch rules ask for a review, it waits for that review.`)
+  return out
+}
+
+/** Dependabot: .github/dependabot.yml and the workflow that merges its pull requests, then deploys. */
+function dependabotPlan(entries, { ws, repo }, out) {
+  if ((repo.top ?? '.') !== '.') {
+    out.manual.push({ title: 'Add the update bot at the top of your repo', required: false, lines: [
+      `This run is in a folder of the repo, and the update bot files go in .github at its top. Run npx @uknows/setup --update-bot dependabot in the repo root, or add ${CONFIG} with these lines.`],
+    snippets: [{ caption: CONFIG, language: 'yaml', code: dependabotYaml(entries) }] })
+    return out
+  }
+  const current = ws.read(CONFIG)
+  if (current === null) {
+    out.edits.push({ file: CONFIG, before: null, after: dependabotYaml(entries), why: 'Propose OpenTelemetry package updates every day.' })
+    out.summary.push(`Add ${CONFIG}: Dependabot proposes OpenTelemetry package updates every day (${entries.map((e) => `${e.ecosystem} in ${e.directory}`).join(', ')}).`)
+  } else if (!/uknows|opentelemetry/i.test(current)) {
+    out.manual.push({ title: `Add the OpenTelemetry updates to ${CONFIG}`, required: false, lines: [
+      `${CONFIG} is there already. This tool does not change it. Add these entries to its updates list.`],
+    snippets: [{ caption: CONFIG, language: 'yaml', code: dependabotYaml(entries).split('\n').filter((l) => /^  /.test(l)).join('\n') }] })
+  }
+  const deploy = deployWorkflows(repo)
+  if (ws.read(WORKFLOW) === null) {
+    out.edits.push({ file: WORKFLOW, before: null, after: updatesWorkflow(deploy, entries.flatMap((e) => e.patterns)),
+      why: 'Merge the OpenTelemetry update pull requests when the checks pass, then deploy.' })
+    out.summary.push(`Add ${WORKFLOW}: it merges those pull requests when the checks pass, then starts ${deploy.length ? deploy.join(', ') : 'nothing (no deploy workflow with workflow_dispatch was found)'}.`)
+  }
+  out.manual.push({ title: 'Let the update pull requests merge themselves', required: false, lines: [
+    'In the repository settings, turn on Allow auto-merge.',
+    'Add a branch rule for your default branch that requires your build check to pass. Then an update merges only when your build passes.',
+    'Where your rules ask for a review, an update waits for that review.'] })
+  return out
+}
+
+/** Renovate: renovate.json at the top of the repo, or the rules to add to the Renovate config that the repo has (own). */
+function renovatePlan(entries, { ws, repo, own = null, app = true }, out) {
+  const config = renovateConfig(entries.flatMap((e) => e.patterns))
+  if ((repo.top ?? '.') !== '.') {
+    out.manual.push({ title: 'Add the update bot at the top of your repo', required: false, lines: [
+      `This run is in a folder of the repo, and renovate.json goes at its top. Run npx @uknows/setup --update-bot renovate in the repo root, or add ${RENOVATE} with these lines.`],
+    snippets: [{ caption: RENOVATE, language: 'json', code: config }] })
+    return out
+  }
+  if (own === null) {
+    out.edits.push({ file: RENOVATE, before: null, after: config, why: 'Propose UKNOWS and OpenTelemetry updates, 3 days after each release.' })
+    out.summary.push(`Add ${RENOVATE}: Renovate proposes UKNOWS and OpenTelemetry updates in 1 pull request, 3 days after each release, and merges it when your checks pass (${entries.map((e) => `${e.ecosystem} in ${e.directory}`).join(', ')}).`)
+  } else if (!/opentelemetry/i.test(renovateTextOf(own, ws.read(own)))) {
+    const rules = JSON.parse(config).packageRules.slice(1)
+    out.manual.push({ title: `Add the OpenTelemetry updates to ${own}`, required: false, lines: [
+      `${own} has your Renovate config already. This tool does not change it. Add this rule to its packageRules.`],
+    snippets: [{ caption: own, language: 'json', code: JSON.stringify(rules, null, 2) }] })
+  }
+  out.manual.push({ title: 'Let the update pull requests merge themselves', required: false, lines: [
+    ...(app ? ['Install the Renovate app on this repository, or run Renovate for it. With renovate.json in the repo, the app opens no onboarding pull request.'] : []),
+    'Add a branch rule for your default branch that requires your build check to pass. Renovate merges an update only when its checks pass.',
+    'Where your rules ask for a review, an update waits for that review.'] })
+  return out
+}

package/lib/versions.mjs

@@ -0,0 +1,115 @@
+/*
+ * Version numbers and version limits, as Python (PEP 440), Poetry and NuGet write them. Only what this tool needs:
+ * releases with an a, b or rc pre-release, the operators == != < <= > >= ~= and ==1.2.*, Poetry ^ and ~, and NuGet
+ * ranges such as [1.17.0, 1.19.0). Local and dev parts are ignored.
+ */
+
+/** [release numbers, pre-release rank (a 0, b 1, rc 2, final 3), pre-release number]. */
+function parse(version) {
+  const m = /^\s*v?(\d+(?:\.\d+)*)(?:[-_.]?(a|alpha|b|beta|rc|c|pre|preview)[-_.]?(\d*))?/i.exec(String(version ?? ''))
+  if (!m) return null
+  const tag = (m[2] ?? '').toLowerCase()
+  const rank = !tag ? 3 : /^a/.test(tag) ? 0 : /^b/.test(tag) ? 1 : 2
+  return { release: m[1].split('.').map(Number), rank, n: Number(m[3] || 0) }
+}
+
+/** -1, 0 or 1. Missing release parts count as 0, so 1.2 equals 1.2.0. A version that does not parse sorts first. */
+export function compareVersion(a, b) {
+  const x = parse(a), y = parse(b)
+  if (!x || !y) return x ? 1 : y ? -1 : 0
+  for (let i = 0; i < Math.max(x.release.length, y.release.length); i++) {
+    const d = (x.release[i] ?? 0) - (y.release[i] ?? 0)
+    if (d) return d < 0 ? -1 : 1
+  }
+  if (x.rank !== y.rank) return x.rank < y.rank ? -1 : 1
+  return x.n === y.n ? 0 : x.n < y.n ? -1 : 1
+}
+
+/** The next release after a prefix: 1.4 -> 1.5, 2 -> 3. */
+const bump = (parts) => [...parts.slice(0, -1), parts.at(-1) + 1].join('.')
+
+/**
+ * The clauses of a version limit, as [{op, version}]. Python: '>=1.2,<2', '==1.2.*', '~=1.4.2'. Poetry: '^1.2',
+ * '~1.2', '1.2' (exact), '*' (any). NuGet: '[1.17.0, 1.19.0)', '1.2.3' (that version or later). Wildcards and the
+ * compatible release become 2 clauses. Unknown text gives no clauses.
+ * @param {string|null} spec
+ * @param {'python'|'poetry'|'nuget'} [style]
+ * @returns {{op: string, version: string}[]}
+ */
+export function clauses(spec, style = 'python') {
+  const text = String(spec ?? '').trim()
+  if (!text || text === '*') return []
+  if (style === 'nuget') {
+    const range = /^([[(])\s*([^,\])]*?)\s*(?:,\s*([^\])]*?)\s*)?([\])])$/.exec(text)
+    if (!range) return parse(text) ? [{ op: '>=', version: text }] : []
+    if (range[3] === undefined) return range[2] ? [{ op: '==', version: range[2] }] : []
+    const out = []
+    if (range[2]) out.push({ op: range[1] === '[' ? '>=' : '>', version: range[2] })
+    if (range[3]) out.push({ op: range[4] === ']' ? '<=' : '<', version: range[3] })
+    return out
+  }
+  const out = []
+  for (const raw of text.split(/\s*,\s*|\s+(?=[<>=!~^])/)) {
+    const part = raw.trim()
+    if (!part || part === '*') continue
+    const m = /^(===|==|!=|~=|<=|>=|<|>|\^|~|=)?\s*v?([0-9][0-9A-Za-z.*+_-]*)$/.exec(part)
+    if (!m) continue
+    let op = m[1] ?? (style === 'poetry' ? '==' : '==')
+    const version = m[2]
+    if (op === '=' || op === '===') op = '=='
+    const release = version.replace(/\.\*$/, '').split('.').map((p) => Number.parseInt(p, 10))
+    if (op === '==' && version.endsWith('.*')) {
+      out.push({ op: '>=', version: release.join('.') }, { op: '<', version: bump(release) })
+    } else if (op === '~=') {
+      out.push({ op: '>=', version }, { op: '<', version: bump(release.length > 1 ? release.slice(0, -1) : release) })
+    } else if (op === '^') {
+      const first = release.findIndex((n) => n !== 0)
+      const keep = first < 0 ? release.length : first + 1
+      out.push({ op: '>=', version }, { op: '<', version: bump(release.slice(0, Math.min(keep, release.length))) })
+    } else if (op === '~') {
+      out.push({ op: '>=', version }, { op: '<', version: bump(release.length > 1 ? release.slice(0, 2) : release) })
+    } else out.push({ op, version })
+  }
+  return out
+}
+
+/** True when the version meets every clause of the limit. No clauses: any version. */
+export function satisfies(version, spec, style = 'python') {
+  return clauses(spec, style).every(({ op, version: v }) => {
+    const c = compareVersion(version, v)
+    return op === '==' ? c === 0 : op === '!=' ? c !== 0 : op === '<' ? c < 0 : op === '<=' ? c <= 0 : op === '>' ? c > 0 : c >= 0
+  })
+}
+
+/**
+ * True when some version meets the limit and lies in [lowest, below). For a protobuf limit against the protobuf
+ * range of 1 OpenTelemetry release. != clauses are ignored.
+ */
+export function overlaps(spec, [lowest, below], style = 'python') {
+  let lo = { v: lowest, incl: true }, hi = { v: below, incl: false }
+  for (const { op, version } of clauses(spec, style)) {
+    if (op === '==') { lo = tighterLow(lo, { v: version, incl: true }); hi = tighterHigh(hi, { v: version, incl: true }) }
+    else if (op === '>=' || op === '>') lo = tighterLow(lo, { v: version, incl: op === '>=' })
+    else if (op === '<=' || op === '<') hi = tighterHigh(hi, { v: version, incl: op === '<=' })
+  }
+  const c = compareVersion(lo.v, hi.v)
+  return c < 0 || (c === 0 && lo.incl && hi.incl)
+}
+
+function tighterLow(a, b) {
+  const c = compareVersion(a.v, b.v)
+  return c > 0 ? a : c < 0 ? b : { v: a.v, incl: a.incl && b.incl }
+}
+
+function tighterHigh(a, b) {
+  const c = compareVersion(a.v, b.v)
+  return c < 0 ? a : c > 0 ? b : { v: a.v, incl: a.incl && b.incl }
+}
+
+/** The lowest version a limit allows, as [major, minor], for requires-python = ">=3.12" or python = "^3.11". null when open. */
+export function lowestRelease(spec, style = 'python') {
+  const low = clauses(spec, style).filter((c) => c.op === '>=' || c.op === '>' || c.op === '==' || c.op === '~=')
+    .map((c) => c.version).sort(compareVersion).at(-1)
+  const parts = low ? parse(low)?.release : null
+  return parts ? [parts[0], parts[1] ?? 0] : null
+}

package/lib/workspace.mjs

@@ -144,6 +144,7 @@ export const createWorkspace = (root) => new Workspace(root)
  * @property {(path: string) => string|null} read
  * @property {(path: string) => boolean} exists
  * @property {(path: string) => import('node:fs').Stats|null} stat
+ * @property {(dir?: string) => string[]} list   Names in 1 folder, as Workspace.list. A folder above the root reads as '../x'.
  * @property {string} top   The repo top, relative to the root: '.', '..' or '../..'.
  */
 
@@ -162,7 +163,8 @@ export function repoView(ws) {
     if (existsSync(join(dir, '.git'))) { top = dir; break }
     if (dirname(dir) === dir) break
   }
-  const view = { files: () => ws.files(), read: (path) => ws.read(path), exists: (path) => ws.exists(path), stat: (path) => ws.stat(path), top: '.' }
+  const view = { files: () => ws.files(), read: (path) => ws.read(path), exists: (path) => ws.exists(path), stat: (path) => ws.stat(path),
+    list: (dir = '.') => ws.list(dir), top: '.' }
   if (!top || top === ws.root) return view
   const outer = createWorkspace(top)
   const prefix = relative(top, ws.root).split(sep).join('/')
@@ -174,6 +176,7 @@ export function repoView(ws) {
     read: (path) => (above(path) ? outer.read(toTop(path)) : ws.read(path)),
     exists: (path) => (above(path) ? outer.exists(toTop(path)) : ws.exists(path)),
     stat: (path) => (above(path) ? outer.stat(toTop(path)) : ws.stat(path)),
+    list: (dir = '.') => (dir === '..' || above(dir) ? outer.list(toTop(dir)) : ws.list(dir)),
     top: prefix.split('/').map(() => '..').join('/'),
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uknows/setup",
-  "version": "0.1.0",
-  "description": "Add standard OpenTelemetry to your app in 1 command, so it sends traces to UKNOWS. Shows the change, asks once, can undo.",
+  "version": "0.2.0",
+  "description": "Add standard OpenTelemetry to your app in 1 command, so it sends traces and logs to UKNOWS. Shows the change, asks first, can undo.",
   "keywords": [
     "uknows",
     "opentelemetry",
@@ -12,12 +12,7 @@
     "setup",
     "cli"
   ],
-  "homepage": "https://uknows.defacloud.my/docs",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MohammediYunus/uknows.git",
-    "directory": "packages/uknows-setup"
-  },
+  "homepage": "https://uknows.my/docs",
   "license": "Apache-2.0",
   "author": "UKNOWS",
   "type": "module",