@uknows/setup 0.0.0-stage → 0.1.0

package/lib/diff.mjs

@@ -0,0 +1,147 @@
+/*
+ * Line diffs. Lines keep their endings, so a diff of CRLF, mixed or
+ * unterminated text is byte exact. The common prefix and suffix are cut off
+ * first, then a Myers O(ND) diff runs on the middle. When the middle is too
+ * different, it becomes 1 change, which is still correct, just less tidy.
+ */
+
+const MAX_D = 1000
+
+/** Lines with their endings. '' has no lines. */
+export const splitLines = (text) => (text ? text.split(/(?<=\n)/) : [])
+
+/** Changed regions between 2 line arrays: [{a, aEnd, b, bEnd}], 0-based, ends exclusive. */
+export function regions(a, b) {
+  let pre = 0
+  while (pre < a.length && pre < b.length && a[pre] === b[pre]) pre++
+  let suf = 0
+  while (suf < a.length - pre && suf < b.length - pre && a[a.length - 1 - suf] === b[b.length - 1 - suf]) suf++
+  const A = a.slice(pre, a.length - suf), B = b.slice(pre, b.length - suf)
+  const out = []
+  let i = 0, j = 0
+  for (const [mi, mj] of [...(matches(A, B) ?? []), [A.length, B.length]]) {
+    if (mi > i || mj > j) out.push({ a: pre + i, aEnd: pre + mi, b: pre + j, bEnd: pre + mj })
+    i = mi + 1
+    j = mj + 1
+  }
+  return out
+}
+
+/** Matched line pairs [i, j] in order (Myers), or null when more than MAX_D edits apart. */
+function matches(A, B) {
+  const n = A.length, m = B.length, max = n + m, off = max + 1
+  if (!n || !m) return []
+  const v = new Int32Array(2 * max + 3)
+  const trace = []
+  for (let d = 0; d <= Math.min(max, MAX_D); d++) {
+    trace.push(v.slice(off - d - 1, off + d + 2))
+    for (let k = -d; k <= d; k += 2) {
+      let x = k === -d || (k !== d && v[off + k - 1] < v[off + k + 1]) ? v[off + k + 1] : v[off + k - 1] + 1
+      let y = x - k
+      while (x < n && y < m && A[x] === B[y]) { x++; y++ }
+      v[off + k] = x
+      if (x >= n && y >= m) return backtrack(trace, n, m)
+    }
+  }
+  return null
+}
+
+function backtrack(trace, n, m) {
+  const pairs = []
+  let x = n, y = m
+  for (let d = trace.length - 1; d >= 0; d--) {
+    const snap = trace[d], at = (k) => snap[k + d + 1]
+    const k = x - y
+    const prevK = k === -d || (k !== d && at(k - 1) < at(k + 1)) ? k + 1 : k - 1
+    const prevX = at(prevK), prevY = prevX - prevK
+    while (x > prevX && y > prevY) pairs.push([--x, --y])
+    x = prevX
+    y = prevY
+  }
+  return pairs.reverse()
+}
+
+/**
+ * Zero-context hunks for the manifest. `at` is the 0-based line in the
+ * after-text. before null means a new file.
+ */
+export function hunks(before, after) {
+  const a = splitLines(before ?? ''), b = splitLines(after)
+  return regions(a, b).map((r) => ({ at: r.b, before: a.slice(r.a, r.aEnd), after: b.slice(r.b, r.bEnd) }))
+}
+
+/** Undo hunks by position. Returns the lines, or null when a hunk does not sit where it should. */
+export function reverseAt(lines, list) {
+  const out = [...lines]
+  for (const h of [...list].sort((p, q) => q.at - p.at)) {
+    if (!sameAt(out, h.at, h.after)) return null
+    out.splice(h.at, h.after.length, ...h.before)
+  }
+  return out
+}
+
+/**
+ * Undo hunks by content: each hunk's added lines must appear exactly once.
+ * Returns the lines, or null when a hunk is missing, ambiguous or overlaps another.
+ */
+export function reverseByContent(lines, list) {
+  const found = []
+  for (const h of list) {
+    if (!h.after.length) return null
+    const spots = []
+    for (let i = 0; i + h.after.length <= lines.length; i++) if (sameAt(lines, i, h.after)) spots.push(i)
+    if (spots.length !== 1) return null
+    found.push({ at: spots[0], h })
+  }
+  found.sort((p, q) => q.at - p.at)
+  for (let i = 1; i < found.length; i++) if (found[i].at + found[i].h.after.length > found[i - 1].at) return null
+  const out = [...lines]
+  for (const { at, h } of found) out.splice(at, h.after.length, ...h.before)
+  return out
+}
+
+function sameAt(lines, at, want) {
+  if (at < 0 || at + want.length > lines.length) return false
+  return want.every((line, i) => lines[at + i] === line)
+}
+
+/** Lines added and removed. */
+export function countLines(before, after) {
+  let added = 0, removed = 0
+  for (const r of regions(splitLines(before ?? ''), splitLines(after ?? ''))) {
+    added += r.bEnd - r.b
+    removed += r.aEnd - r.a
+  }
+  return { added, removed }
+}
+
+/** A unified diff for display. before null = new file. '' when nothing changed. */
+export function unified(file, before, after, context = 3) {
+  const a = splitLines(before ?? ''), b = splitLines(after ?? '')
+  const rs = regions(a, b)
+  if (!rs.length) return ''
+  const out = [`--- ${before === null ? '/dev/null' : `a/${file}`}`, `+++ b/${file}`]
+  const line = (sign, text) => {
+    out.push(sign + text.replace(/\r?\n$/, ''))
+    if (!text.endsWith('\n')) out.push('\')
+  }
+  for (let g = 0; g < rs.length;) {
+    let h = g
+    while (h + 1 < rs.length && rs[h + 1].a - rs[h].aEnd <= 2 * context) h++
+    const aS = Math.max(0, rs[g].a - context), aE = Math.min(a.length, rs[h].aEnd + context)
+    const bS = rs[g].b - (rs[g].a - aS), bE = rs[h].bEnd + (aE - rs[h].aEnd)
+    out.push(`@@ -${span(aS, aE - aS)} +${span(bS, bE - bS)} @@`)
+    let i = aS
+    for (let r = g; r <= h; r++) {
+      for (; i < rs[r].a; i++) line(' ', a[i])
+      for (let x = rs[r].a; x < rs[r].aEnd; x++) line('-', a[x])
+      for (let y = rs[r].b; y < rs[r].bEnd; y++) line('+', b[y])
+      i = rs[r].aEnd
+    }
+    for (; i < aE; i++) line(' ', a[i])
+    g = h + 1
+  }
+  return out.join('\n')
+}
+
+const span = (start, length) => (length === 1 ? `${start + 1}` : `${length ? start + 1 : start},${length}`)

package/lib/doc.mjs

@@ -0,0 +1,98 @@
+/*
+ * A text file as lines. Each line keeps its own line ending, so an edit
+ * changes only the lines it touches: CRLF, LF, mixed endings and a missing
+ * final newline all survive byte for byte. New lines use the dominant ending.
+ */
+
+export class Doc {
+  /** @param {string} text */
+  constructor(text = '') {
+    const parts = text === '' ? [] : text.split(/(?<=\n)/)
+    /** @type {string[]} line content without the ending */
+    this.lines = []
+    /** @type {string[]} '\n', '\r\n' or '' (last line without a newline) */
+    this.ends = []
+    for (const part of parts) {
+      const end = part.endsWith('\r\n') ? '\r\n' : part.endsWith('\n') ? '\n' : ''
+      this.lines.push(part.slice(0, part.length - end.length))
+      this.ends.push(end)
+    }
+    const crlf = this.ends.filter((e) => e === '\r\n').length
+    const lf = this.ends.filter((e) => e === '\n').length
+    /** The dominant line ending. */
+    this.eol = crlf > lf ? '\r\n' : '\n'
+  }
+
+  get length() { return this.lines.length }
+
+  /** @param {number} i */
+  get(i) { return this.lines[i] }
+
+  /** Replace the content of line i. Keeps its line ending. */
+  set(i, content) {
+    if (i < 0 || i >= this.lines.length) throw new RangeError(`no line ${i}`)
+    this.lines[i] = content
+  }
+
+  /** Insert lines before index i. i === length appends. */
+  insert(i, ...contents) {
+    if (i < 0 || i > this.lines.length) throw new RangeError(`no line ${i}`)
+    if (!contents.length) return
+    const last = this.lines.length - 1
+    if (i === this.lines.length && last >= 0 && this.ends[last] === '') {
+      // Appending after a final line without a newline: keep the file without a final newline.
+      this.ends[last] = this.eol
+      this.lines.push(...contents)
+      this.ends.push(...contents.map((_, k) => (k === contents.length - 1 ? '' : this.eol)))
+      return
+    }
+    this.lines.splice(i, 0, ...contents)
+    this.ends.splice(i, 0, ...contents.map(() => this.eol))
+  }
+
+  /** Remove count lines from index i. */
+  remove(i, count = 1) {
+    this.lines.splice(i, count)
+    this.ends.splice(i, count)
+  }
+
+  /** First index >= from whose line matches. test is a RegExp or a function. */
+  find(test, from = 0) {
+    for (let i = from; i < this.lines.length; i++) {
+      if (typeof test === 'function' ? test(this.lines[i], i) : test.test(this.lines[i])) return i
+    }
+    return -1
+  }
+
+  toString() {
+    let out = ''
+    for (let i = 0; i < this.lines.length; i++) out += this.lines[i] + this.ends[i]
+    return out
+  }
+}
+
+/** Indentation (leading spaces or tabs) of a line. */
+export const indentOf = (line) => /^[ \t]*/.exec(line)[0]
+
+/**
+ * Split a command into words when it is a plain literal command. Returns null
+ * when it has shell syntax this tool must not guess at: variables,
+ * substitution, globs, redirects, pipes, lists, a leading NAME=value, an
+ * unclosed quote or a newline. Quotes are removed.
+ * @param {string} text
+ * @returns {string[]|null}
+ */
+export function shellWords(text) {
+  if (typeof text !== 'string' || !text.trim() || /[\r\n\0$`;&|<>*?{}\\]/.test(text)) return null
+  const words = []
+  let word = '', quote = '', started = false
+  for (const c of text.trim()) {
+    if (quote) { if (c === quote) quote = ''; else word += c; started = true }
+    else if (c === '"' || c === "'") { quote = c; started = true }
+    else if (/\s/.test(c)) { if (started) { words.push(word); word = ''; started = false } }
+    else { word += c; started = true }
+  }
+  if (quote) return null
+  if (started) words.push(word)
+  return words.length && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0]) ? words : null
+}

package/lib/dockerfile.mjs

@@ -0,0 +1,372 @@
+/*
+ * Read and edit Dockerfiles as text. Only the final stage matters: it is the
+ * image that runs. Edits keep every other line byte for byte (see doc.mjs).
+ * Handles line continuations, comment lines inside them, heredoc bodies and
+ * the # escape= directive. New lines go after the last RUN of the final
+ * stage, so build steps never see them.
+ */
+import { Doc, indentOf, shellWords } from './doc.mjs'
+
+/**
+ * @typedef {Object} Instruction
+ * @property {string} keyword        Upper case, e.g. 'ENV'.
+ * @property {number} start          0-based index of its first line.
+ * @property {number} end            0-based index of its last line (continuations and heredoc bodies included).
+ * @property {string} args           Logical argument text: continuations joined, inner comment lines removed.
+ * @property {string[]|null} argv    The JSON array of an exec-form instruction, else null.
+ */
+
+/**
+ * @typedef {Object} EnvEntry
+ * @property {string} value          Unquoted value.
+ * @property {Instruction} instruction
+ * @property {number} line           0-based line of the NAME=value token.
+ * @property {number} col            Token start column in that line.
+ * @property {number} endCol         Token end column (exclusive).
+ * @property {boolean} quoted        The value was written in quotes.
+ * @property {boolean} legacy        Old 'ENV NAME value' form.
+ */
+
+/**
+ * @typedef {Object} DockerfileInfo
+ * @property {Instruction[]} instructions   All instructions, in order.
+ * @property {Instruction[]} final          The final stage, starting with its FROM. All instructions when there is no FROM.
+ * @property {string|null} image            Final FROM image, e.g. 'python:3.12-slim'.
+ * @property {string|null} stageName        Final stage name from 'FROM ... AS name'.
+ * @property {string|null} workdir          Last WORKDIR of the final stage.
+ * @property {Instruction|null} cmd         Last CMD of the final stage.
+ * @property {Instruction|null} entrypoint  Last ENTRYPOINT of the final stage.
+ * @property {Map<string, EnvEntry>} env    ENV of the final stage. The last one wins.
+ * @property {Map<string, EnvEntry>} inherited  ENV of the earlier stages that the final stage builds on (FROM <stage>).
+ * @property {Stage[]} stages               Every stage, in order. Empty when there is no FROM.
+ * @property {string} escape                '\\' or '`'.
+ * @property {boolean} syntax               Has a '# syntax=' directive.
+ */
+
+/** @typedef {{image: string, name: string|null, instructions: Instruction[]}} Stage */
+
+const EXEC_FORM = new Set(['CMD', 'ENTRYPOINT', 'RUN', 'SHELL', 'HEALTHCHECK'])
+
+/** @param {string} text @returns {DockerfileInfo} */
+export function parseDockerfile(text) {
+  const doc = new Doc(text)
+  let escape = '\\', syntax = false, i = 0
+  // Parser directives: only at the very top.
+  for (; i < doc.length; i++) {
+    const m = /^\s*#\s*([a-zA-Z]+)\s*=\s*(\S+)\s*$/.exec(doc.get(i))
+    if (!m) break
+    const name = m[1].toLowerCase()
+    if (name === 'escape' && (m[2] === '`' || m[2] === '\\')) escape = m[2]
+    else if (name === 'syntax') syntax = true
+    else if (name !== 'check') break
+  }
+  const continues = (line) => line.trimEnd().endsWith(escape)
+  const comment = (line) => /^\s*#/.test(line)
+  const instructions = []
+  for (; i < doc.length; i++) {
+    const first = doc.get(i)
+    const m = /^\s*([A-Za-z]+)(?:\s+(.*))?$/.exec(first)
+    if (!m || comment(first)) continue
+    const start = i
+    let piece = m[2] ?? '', args = ''
+    while (continues(piece) && i + 1 < doc.length) {
+      args += piece.trimEnd().slice(0, -1)
+      i++
+      while (i < doc.length && (comment(doc.get(i)) || doc.get(i).trim() === '') && i + 1 < doc.length) i++
+      piece = doc.get(i)
+    }
+    args = (args + piece).trim()
+    const keyword = m[1].toUpperCase()
+    // Heredoc bodies (RUN <<EOF ... EOF) are not instructions.
+    if (['RUN', 'COPY', 'ADD'].includes(keyword)) {
+      for (const h of args.matchAll(/<<(-?)\s*(["']?)([A-Za-z_][A-Za-z0-9_]*)\2/g)) {
+        while (i + 1 < doc.length && doc.get(++i).trim() !== h[3]);
+      }
+    }
+    let argv = null
+    if (EXEC_FORM.has(keyword) && args.startsWith('[')) {
+      try {
+        const value = JSON.parse(args)
+        if (Array.isArray(value) && value.every((v) => typeof v === 'string')) argv = value
+      } catch { /* shell form after all */ }
+    }
+    instructions.push({ keyword, start, end: i, args, argv })
+  }
+  const stages = []
+  for (const x of instructions) {
+    if (x.keyword === 'FROM') {
+      const words = x.args.split(/\s+/).filter((w) => !w.startsWith('--'))
+      stages.push({ image: words[0] ?? '', name: words[1]?.toLowerCase() === 'as' ? words[2] ?? null : null, instructions: [] })
+    }
+    stages.at(-1)?.instructions.push(x)
+  }
+  const final = stages.at(-1)?.instructions ?? instructions
+  const last = (k) => final.filter((x) => x.keyword === k).at(-1) ?? null
+  const envOf = (list) => {
+    const env = new Map()
+    for (const instruction of list.filter((x) => x.keyword === 'ENV')) {
+      for (const entry of envEntries(doc, instruction, escape)) env.set(entry.name, entry)
+    }
+    return env
+  }
+  const inherited = new Map()
+  for (const stage of parents(stages, stages.length - 1).reverse()) for (const [name, entry] of envOf(stage.instructions)) inherited.set(name, entry)
+  const workdir = last('WORKDIR')
+  return { instructions, final, stages, image: stages.at(-1)?.image ?? null, stageName: stages.at(-1)?.name ?? null,
+    workdir: workdir ? workdir.args : null, cmd: last('CMD'), entrypoint: last('ENTRYPOINT'), env: envOf(final), inherited, escape, syntax }
+}
+
+/** The earlier stages that stage i builds on (FROM <name>), nearest first. */
+function parents(stages, i) {
+  const out = []
+  for (let k = i, hops = 0; k > 0 && hops < 20; hops++) {
+    const base = stages[k].image.toLowerCase()
+    k = stages.findLastIndex((s, j) => j < k && s.name?.toLowerCase() === base)
+    if (k < 0) break
+    out.push(stages[k])
+  }
+  return out
+}
+
+/**
+ * The stages whose files reach the final image: the final stage, the stages it
+ * builds on, and the stages they COPY --from, again and again.
+ * @param {DockerfileInfo} info
+ * @returns {Stage[]}
+ */
+export function reachingStages(info) {
+  const { stages } = info
+  if (!stages.length) return [{ image: '', name: null, instructions: info.instructions }]
+  const index = (ref) => (/^\d+$/.test(ref) ? Number(ref) : stages.findIndex((s) => s.name?.toLowerCase() === ref.toLowerCase()))
+  const seen = new Set(), queue = [stages.length - 1]
+  while (queue.length) {
+    const i = queue.pop()
+    if (i < 0 || i >= stages.length || seen.has(i)) continue
+    seen.add(i)
+    queue.push(...parents(stages, i).map((s) => stages.indexOf(s)))
+    for (const x of stages[i].instructions) {
+      const from = (x.keyword === 'COPY' || x.keyword === 'ADD') && /(?:^|\s)--from=["']?([^\s"']+)/.exec(x.args)
+      if (from) queue.push(index(from[1]))
+    }
+  }
+  return [...seen].sort((a, b) => a - b).map((i) => stages[i])
+}
+
+/**
+ * The start command of the final image: ENTRYPOINT then CMD. A shell-form
+ * ENTRYPOINT ignores CMD, as Docker does.
+ * @returns {{line: number, form: 'exec'|'shell', raw: string, argv: string[]|null}|null}  line is 1-based
+ */
+export function dockerStart(info) {
+  const { entrypoint, cmd } = info
+  if (!entrypoint && !cmd) return null
+  const parts = entrypoint && !entrypoint.argv ? [entrypoint] : [entrypoint, cmd].filter(Boolean)
+  const exec = parts.every((p) => p.argv)
+  const argv = exec ? parts.flatMap((p) => p.argv) : parts.length === 1 ? shellWords(parts[0].args) : null
+  return { line: (entrypoint ?? cmd).start + 1, form: exec ? 'exec' : 'shell', raw: parts.map((p) => p.args).join(' '), argv }
+}
+
+/**
+ * ENV lines in the docs format: 'ENV A=1 \' then '    B=2'. The line
+ * continuation uses the escape character of the Dockerfile.
+ * @param {[string, string][]} pairs
+ * @param {{quote?: 'auto'|'always', escape?: string, raw?: boolean}} [options]  'always' quotes every value, as the docs
+ *   do for NODE_OPTIONS. raw keeps $ references, so Docker expands them.
+ * @returns {string[]}
+ */
+export function formatEnv(pairs, { quote = 'auto', escape = '\\', raw = false } = {}) {
+  const items = pairs.map(([name, value]) => `${name}=${quoteValue(value, quote === 'always', escape, raw)}`)
+  return items.map((item, k) => `${k === 0 ? 'ENV ' : '    '}${item}${k < items.length - 1 ? ` ${escape}` : ''}`)
+}
+
+/**
+ * Set ENV values in the final stage. A name that the final stage sets with
+ * another value is changed in place. Missing names, and names that only an
+ * earlier stage sets, go in 1 new ENV block (formatEnv) before the start
+ * instruction. Equal values change nothing.
+ * @param {string} text
+ * @param {[string, string][]} pairs
+ * @param {{quote?: 'auto'|'always'}} [options]
+ */
+export function setEnv(text, pairs, options = {}) {
+  let out = text
+  const missing = []
+  const { escape } = parseDockerfile(text)
+  for (const [name, value] of pairs) {
+    const info = parseDockerfile(out)
+    const entry = info.env.get(name)
+    if (!entry) { if (info.inherited.get(name)?.value !== value) missing.push([name, value]); continue }
+    if (entry.value === value) continue
+    const doc = new Doc(out)
+    const token = `${name}=${quoteValue(value, entry.quoted || options.quote === 'always', escape)}`
+    if (entry.legacy) {
+      const { start, end } = entry.instruction
+      doc.remove(start + 1, end - start)
+      doc.set(start, `${indentOf(doc.get(start))}ENV ${token}`)
+    } else {
+      const line = doc.get(entry.line)
+      doc.set(entry.line, line.slice(0, entry.col) + token + line.slice(entry.endCol))
+    }
+    out = doc.toString()
+  }
+  return missing.length ? insertBeforeStart(out, formatEnv(missing, { ...options, escape })) : out
+}
+
+/**
+ * Add an option to a list setting such as NODE_OPTIONS or JAVA_TOOL_OPTIONS.
+ * Lines that set it already stay as they are: build steps run with them, and
+ * their value can use $ references. A new ENV line goes after the last RUN,
+ * just before the start. When the final stage or an earlier stage sets a
+ * value, the new line keeps it with ${NAME}. Unchanged when has(value).
+ * @param {string} text
+ * @param {string} name
+ * @param {string} option
+ * @param {(value: string) => boolean} [has]
+ */
+export function addOption(text, name, option, has = (value) => value.includes(option)) {
+  const info = parseDockerfile(text)
+  const current = info.env.get(name) ?? info.inherited.get(name)
+  if (current && has(current.value)) return text
+  const value = current ? `\${${name}} ${option}` : option
+  return insertBeforeStart(text, formatEnv([[name, value]], { quote: 'always', escape: info.escape, raw: true }))
+}
+
+/**
+ * Insert lines in the final stage, just before the first CMD or ENTRYPOINT
+ * after its last RUN (above any comment lines attached to it). Without one,
+ * after the last instruction. So no RUN of the final stage sees the lines.
+ * Lines get the indentation of the line they go before.
+ * @param {string} text
+ * @param {string[]} lines
+ */
+export function insertBeforeStart(text, lines) {
+  const info = parseDockerfile(text)
+  const doc = new Doc(text)
+  const lastRun = info.final.findLastIndex((x) => x.keyword === 'RUN')
+  const start = info.final.find((x, k) => k > lastRun && (x.keyword === 'CMD' || x.keyword === 'ENTRYPOINT'))
+  let at, indent = ''
+  if (start) {
+    at = start.start
+    indent = indentOf(doc.get(at))
+    while (at > 0 && /^\s*#/.test(doc.get(at - 1)) && at - 1 > (info.final[0]?.end ?? -1)) at--
+  } else {
+    at = info.instructions.length ? info.instructions.at(-1).end + 1 : doc.length
+  }
+  doc.insert(at, ...lines.map((line) => indent + line))
+  return doc.toString()
+}
+
+/**
+ * Put words in front of the start command of the final stage: the
+ * ENTRYPOINT when there is one, else the CMD. Exec form gets JSON strings
+ * in the same comma style. Shell form gets plain words after the keyword
+ * (or after 'exec'). Returns the text unchanged when the words are already
+ * there, and null when there is no start or it cannot be changed safely
+ * (shell lists, pipes, a leading NAME=value, or '[' not on the first line).
+ * @param {string} text
+ * @param {string[]} words
+ * @returns {string|null}
+ */
+export function prefixStart(text, words) {
+  const info = parseDockerfile(text)
+  const target = info.entrypoint ?? info.cmd
+  if (!target) return null
+  const doc = new Doc(text)
+  const line = doc.get(target.start)
+  const keywordEnd = /^\s*[A-Za-z]+\s*/.exec(line)[0].length
+  if (target.argv) {
+    if (words.every((w, k) => target.argv[k] === w)) return text
+    if (line[keywordEnd] !== '[') return null
+    // Keep the comma style of the array. With fewer than 2 items there is none: use the docs style.
+    const sep = target.argv.length < 2 || /",\s+"/.test(target.args) ? ', ' : ','
+    let pos = keywordEnd + 1
+    while (line[pos] === ' ') pos++
+    const inserted = words.map((w) => JSON.stringify(w)).join(sep) + (target.argv.length ? sep : '')
+    doc.set(target.start, line.slice(0, pos) + inserted + line.slice(pos))
+    return doc.toString()
+  }
+  const execWord = /^exec\s+/.exec(target.args)?.[0] ?? ''
+  const command = target.args.slice(execWord.length)
+  if (command.startsWith(words.join(' ') + ' ')) return text
+  if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(command) || /[;|]|&&|&\s*$/.test(command)) return null
+  const head = /^exec\s+/.exec(line.slice(keywordEnd))
+  if (execWord && !head) return null
+  const pos = keywordEnd + (head ? head[0].length : 0)
+  doc.set(target.start, line.slice(0, pos) + words.map(shellQuote).join(' ') + ' ' + line.slice(pos))
+  return doc.toString()
+}
+
+// --- helpers ---------------------------------------------------------------
+
+/** A value for an ENV token. escape is the escape character of the Dockerfile. raw keeps $ references. */
+function quoteValue(value, always, escape = '\\', raw = false) {
+  if (!always && value !== '' && /^[A-Za-z0-9_.,:/@%+=-]+$/.test(value)) return value
+  const special = new Set(['"', escape, ...(raw ? [] : ['$'])])
+  return `"${[...value].map((c) => (special.has(c) ? escape + c : c)).join('')}"`
+}
+
+function shellQuote(word) {
+  return /^[A-Za-z0-9_.,:/@%+=-]+$/.test(word) ? word : `'${word.replace(/'/g, `'\\''`)}'`
+}
+
+/** NAME=value tokens of 1 ENV instruction, with their positions. */
+function envEntries(doc, instruction, escape) {
+  const entries = []
+  const tokens = []
+  for (let n = instruction.start; n <= instruction.end; n++) {
+    let line = doc.get(n)
+    if (n > instruction.start && (/^\s*#/.test(line) || !line.trim())) continue
+    let from = 0
+    if (n === instruction.start) from = /^\s*ENV\s*/i.exec(line)[0].length
+    let to = line.length
+    const trimmed = line.trimEnd()
+    if (n < instruction.end && trimmed.endsWith(escape)) to = trimmed.length - 1
+    for (const t of tokenize(line, from, to, escape)) tokens.push({ ...t, line: n })
+  }
+  if (!tokens.length) return entries
+  if (!/^[A-Za-z_][A-Za-z0-9_.-]*=/.test(tokens[0].text)) {
+    // Legacy form: ENV NAME the rest is the value
+    const name = tokens[0].text
+    const value = instruction.args.slice(instruction.args.indexOf(name) + name.length).trim()
+    return [{ name, value: unquote(value, escape), instruction, line: tokens[0].line, col: tokens[0].start, endCol: tokens[0].end, quoted: false, legacy: true }]
+  }
+  for (const t of tokens) {
+    const eq = t.text.indexOf('=')
+    if (eq < 1) continue
+    const raw = t.text.slice(eq + 1)
+    entries.push({ name: t.text.slice(0, eq), value: unquote(raw, escape), instruction, line: t.line, col: t.start, endCol: t.end,
+      quoted: raw.startsWith('"') || raw.startsWith("'"), legacy: false })
+  }
+  return entries
+}
+
+/** Whitespace-separated tokens of line[from, to), respecting quotes and the escape character. */
+function tokenize(line, from, to, escape) {
+  const out = []
+  let i = from
+  while (i < to) {
+    while (i < to && /\s/.test(line[i])) i++
+    if (i >= to) break
+    const start = i
+    let quote = ''
+    while (i < to && (quote || !/\s/.test(line[i]))) {
+      const c = line[i]
+      if (c === escape && quote !== "'") i += 2
+      else { if (quote && c === quote) quote = ''; else if (!quote && (c === '"' || c === "'")) quote = c; i++ }
+    }
+    out.push({ text: line.slice(start, Math.min(i, to)), start, end: Math.min(i, to) })
+  }
+  return out
+}
+
+function unquote(raw, escape) {
+  let out = '', quote = ''
+  for (let i = 0; i < raw.length; i++) {
+    const c = raw[i]
+    if (c === escape && quote !== "'" && i + 1 < raw.length) out += raw[++i]
+    else if (quote && c === quote) quote = ''
+    else if (!quote && (c === '"' || c === "'")) quote = c
+    else out += c
+  }
+  return out
+}

package/lib/endpoint.mjs

@@ -0,0 +1,50 @@
+/*
+ * The addresses this run uses. The ingest address is what setup writes and
+ * check sends the test span to. The site address is where check asks which
+ * workspace a key sends to, and where the docs links point. Both are the
+ * addresses of this build (contract-docs.mjs), unless UKNOWS_INGEST_ENDPOINT
+ * or UKNOWS_SITE_URL names another one, for example a test copy of UKNOWS.
+ * Setup and check use these same rules, so a test run writes the address it checks.
+ */
+import { CLI, INGEST_ENDPOINT, SITE_URL } from './contract.mjs'
+
+const LOCAL = new Set(['localhost', '127.0.0.1', '[::1]'])
+const safe = (url) => url.protocol === 'https:' || (url.protocol === 'http:' && LOCAL.has(url.hostname))
+
+/**
+ * The ingest address without a trailing slash, or null when the override is not https (http on this computer only).
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function ingestEndpoint(env = {}) {
+  const raw = String(env[CLI.endpointEnv] || INGEST_ENDPOINT).trim().replace(/\/+$/, '')
+  let url
+  try { url = new URL(`${raw}/v1/traces`) } catch { return null }
+  return safe(url) && !url.username && !url.password ? raw : null
+}
+
+/**
+ * The site address (origin only, no trailing slash), or null when the override is not https or has a path.
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function siteUrl(env = {}) {
+  const raw = String(env[CLI.siteEnv] || SITE_URL).trim().replace(/\/+$/, '')
+  let url
+  try { url = new URL(raw) } catch { return null }
+  return safe(url) && !url.username && !url.password && url.pathname === '/' && !url.search && !url.hash ? url.origin : null
+}
+
+/**
+ * True when check may ask the site about the key: the site and the ingest address belong to the same UKNOWS.
+ * A test ingest address with the production site would ask the wrong UKNOWS, which does not know the test key.
+ * @param {Record<string, string|undefined>} [env]
+ */
+export function sameUknows(env = {}) {
+  return Boolean(env[CLI.siteEnv]) || !env[CLI.endpointEnv]
+}
+
+/** The docs page of the site this run uses. */
+export const docsUrl = (env = {}) => `${siteUrl(env) ?? SITE_URL}/docs`
+/** The llms.txt of the site this run uses. */
+export const llmsUrl = (env = {}) => `${siteUrl(env) ?? SITE_URL}/llms.txt`