@uknows/setup 0.0.0-stage → 0.2.0

package/lib/dockerfile.mjs

@@ -0,0 +1,455 @@
+/*
+ * 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 image that the final stage runs on. FROM base AS final (the Visual Studio layout) names an earlier stage, so
+ * follow the stage names to the image of the first one: mcr.microsoft.com/dotnet/aspnet:8.0-alpine, not base.
+ * @param {DockerfileInfo} info
+ * @returns {string|null}
+ */
+export function finalImage(info) {
+  const { stages } = info
+  if (!stages.length) return info.image ?? null
+  return parents(stages, stages.length - 1).at(-1)?.image ?? stages.at(-1).image
+}
+
+/**
+ * The final stage and the earlier stages it builds on (FROM <stage>), final stage first. Their RUN lines are in the image.
+ * @param {DockerfileInfo} info
+ * @returns {Stage[]}
+ */
+export function finalStages(info) {
+  const { stages } = info
+  if (!stages.length) return [{ image: '', name: null, instructions: info.instructions }]
+  return [stages.at(-1), ...parents(stages, stages.length - 1)]
+}
+
+/**
+ * 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()
+}
+
+/**
+ * Put words at position `at` of the start command, counted as dockerStart counts it (ENTRYPOINT, then CMD), for a
+ * runner such as uv run --no-sync uvicorn: the words go after the runner and its options. at 0 is prefixStart.
+ * Only a 1-line exec form, or a 1-line shell form without quotes. Returns the text unchanged when the words are
+ * already there, and null when it cannot be changed safely.
+ * @param {string} text
+ * @param {number} at
+ * @param {string[]} words
+ * @returns {string|null}
+ */
+export function insertStart(text, at, words) {
+  if (at === 0) return prefixStart(text, words)
+  const { entrypoint, cmd } = parseDockerfile(text)
+  const parts = entrypoint && !entrypoint.argv ? [entrypoint] : [entrypoint, cmd].filter(Boolean)
+  const doc = new Doc(text)
+  let offset = 0
+  for (const [n, part] of parts.entries()) {
+    const shell = !part.argv && !/["']/.test(part.args)
+    const argv = part.argv ?? (shell && parts.length === 1 ? shellWords(part.args.replace(/^exec\s+/, '')) : null)
+    if (!argv) return null
+    const k = at - offset
+    offset += argv.length
+    if (k > argv.length || (k === argv.length && n < parts.length - 1)) continue
+    if (words.every((w, j) => argv[k + j] === w)) return text
+    if (part.start !== part.end) return null
+    const line = doc.get(part.start)
+    const keywordEnd = /^\s*[A-Za-z]+\s*/.exec(line)[0].length
+    if (part.argv) {
+      const tokens = jsonStrings(line, keywordEnd)
+      if (tokens.length !== argv.length) return null
+      const sep = argv.length < 2 || /",\s+"/.test(part.args) ? ', ' : ','
+      const inserted = words.map((w) => JSON.stringify(w)).join(sep)
+      doc.set(part.start, k < tokens.length ? line.slice(0, tokens[k].start) + inserted + sep + line.slice(tokens[k].start)
+        : line.slice(0, tokens.at(-1).end) + sep + inserted + line.slice(tokens.at(-1).end))
+    } else {
+      const head = keywordEnd + (/^exec\s+/.exec(line.slice(keywordEnd))?.[0].length ?? 0)
+      const starts = [...line.slice(head).matchAll(/\S+/g)].map((m) => head + m.index)
+      if (starts.length !== argv.length) return null
+      const pos = k < starts.length ? starts[k] : line.trimEnd().length + 1
+      const insert = words.map(shellQuote).join(' ')
+      doc.set(part.start, k < starts.length ? `${line.slice(0, pos)}${insert} ${line.slice(pos)}` : `${line.trimEnd()} ${insert}${line.slice(line.trimEnd().length)}`)
+    }
+    return doc.toString()
+  }
+  return null
+}
+
+/** Start and end columns of the JSON strings in an exec-form line, from the '['. */
+function jsonStrings(line, from) {
+  const out = []
+  for (let i = line.indexOf('[', from); i >= 0 && i < line.length; i++) {
+    if (line[i] === ']') break
+    if (line[i] !== '"') continue
+    const start = i
+    for (i++; i < line.length && line[i] !== '"'; i++) if (line[i] === '\\') i++
+    out.push({ start, end: i + 1 })
+  }
+  return out
+}
+
+// --- 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,81 @@
+/*
+ * 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.
+ * The app address (the link where an app connects) follows UKNOWS_APP_URL.
+ * Setup and check use these same rules, so a test run writes the address it checks.
+ */
+import { APP_URL, CLI, INGEST_ENDPOINT, SETUP_NEXT, SITE_URL, openLive } 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
+}
+
+/** An origin (https, or http on this computer), no path, no user: the origin, else null. */
+function origin(raw) {
+  let url
+  try { url = new URL(String(raw).trim().replace(/\/+$/, '')) } catch { return null }
+  return safe(url) && !url.username && !url.password && url.pathname === '/' && !url.search && !url.hash ? url.origin : 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 = {}) {
+  return origin(env[CLI.siteEnv] || SITE_URL)
+}
+
+/** True when UKNOWS_APP_URL is not set, or is an origin as siteUrl wants it. */
+export const validAppUrl = (env = {}) => !env[CLI.appEnv] || origin(env[CLI.appEnv]) !== null
+
+/**
+ * The app address, where people sign in and watch an app connect: UKNOWS_APP_URL, else the one of this build. A run
+ * against a test copy (UKNOWS_SITE_URL or UKNOWS_INGEST_ENDPOINT) without UKNOWS_APP_URL does not know the app of that
+ * copy: null, so setup never sends the user to the production app.
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {string|null}
+ */
+export function appUrl(env = {}) {
+  if (env[CLI.appEnv]) return origin(env[CLI.appEnv])
+  return env[CLI.siteEnv] || env[CLI.endpointEnv] ? null : APP_URL
+}
+
+/**
+ * The last line when only the deploy is left, with the app address of this run (F-012-146): where to sign in, from
+ * UKNOWS_APP_URL, else from this build. A test copy without UKNOWS_APP_URL gets no address, never the production one.
+ * The same line goes in the "next" field of --json.
+ * @param {Record<string, string|undefined>} [env]
+ */
+export function nextData(env = {}) {
+  const app = appUrl(env)
+  return SETUP_NEXT.data.replace('{open}', app ? openLive(app) : SETUP_NEXT.testCopy)
+}
+
+/**
+ * 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`