@uknows/setup 0.1.0 → 0.2.0

package/lib/stacks/functions-hooks.mjs

@@ -0,0 +1,228 @@
+/*
+ * The UKNOWS worker hooks for Azure Functions: the route for a function app that sends to Application Insights (or
+ * where setup cannot tell). The Functions host stays in its Application Insights mode, so Application Insights keeps the
+ * same requests, names and fields; a small file in the worker opens a server span for each call as a child of the trace
+ * that the host passes on, and sends it and the logs over OTLP. Measured on the bench, 22 and 23 Oct 2026 (install
+ * proof A3): Application Insights the same as without the hooks (request names, the 11 fields, the traces per request),
+ * a server span for every request, the same trace id and InvocationId as Application Insights, error calls with status
+ * error and the exception type and frames, never the message.
+ *
+ * Node.js (v4 programming model): uknows-otel.cjs in the app folder, loaded through the "main" glob of package.json,
+ * and the OpenTelemetry packages at the tested versions. Python (v2 programming model): uknows_otel.py, 2 lines in
+ * function_app.py (the import, and instrument(app) at the end), the packages in requirements.txt, and the app setting
+ * PYTHON_ENABLE_WORKER_EXTENSIONS=1. .NET isolated: UknowsOpenTelemetry.cs, 2 lines in Program.cs, 2 PackageReferences.
+ * Where a part cannot go in by itself (another shape of Program.cs, a package manager that this tool does not run),
+ * the step prints. Where the hooks cannot apply (the v3 Node.js model, the v1 Python model, the .NET in-process model,
+ * an app that has OpenTelemetry or Azure Monitor in its code already), `unsupported` says why.
+ */
+import { readFileSync } from 'node:fs'
+import { FUNCTIONS } from '../contract.mjs'
+import { Doc } from '../doc.mjs'
+import { list } from '../ui.mjs'
+import { addItems } from './dotnet.mjs'
+import { packageManager } from './node.mjs'
+import { appendLines, compiledRequirements } from './python.mjs'
+
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, k) => (k in values ? String(values[k]) : m))
+const join = (dir, file) => (dir === '.' ? file : `${dir}/${file}`)
+const dirOf = (path) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '.')
+const template = (name) => readFileSync(new URL(`../hooks/${name}`, import.meta.url), 'utf8')
+function read(ws, path) {
+  try { return path ? ws.read(path) : null } catch { return null }
+}
+
+export { HOOKS, HOOK_FILES, TESTED_ON } from '../hooks/pins.mjs'
+import { HOOK_FILES, HOOKS, TESTED_ON } from '../hooks/pins.mjs'
+
+const plan0 = () => ({ summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [], unsupported: null, versions: [] })
+const not = (out, reason) => ({ ...out, unsupported: reason })
+
+/**
+ * The hooks for this service: {edits, commands, summary, manual, notes, extraSettings, versions, unsupported}.
+ * versions: [{name, found, tested}] for the check of untested versions (versionCheck).
+ */
+export function hooksPlan(s, ctx) {
+  const existing = ctx.existing ?? {}
+  // OpenTelemetry or Azure Monitor of the app itself; the packages and the file of the hooks are not (a rerun).
+  const ours = new Set(Object.values(HOOKS).flatMap((h) => h.packages.map(([name]) => name.toLowerCase())))
+  const own = (list) => (list ?? []).filter((x) => !ours.has(String(x.what ?? '').toLowerCase()) && !HOOK_FILES.includes(String(x.file ?? '').split('/').pop()))
+  if (own(existing.otel).length || own(existing.azure).length) return not(plan0(), FUNCTIONS.hooks.unsupported.otel)
+  if (s.lang === 'node') return nodeHooks(s, ctx)
+  if (s.lang === 'python') return pythonHooks(s, ctx)
+  if (s.lang === 'dotnet') return dotnetHooks(s, ctx)
+  return not(plan0(), fill(FUNCTIONS.hooks.unsupported.language, { lang: s.lang }))
+}
+
+/** major.minor of a version or range ("^4.16.5" is 4.16), or null. */
+const minor = (v) => { const m = /(\d+)\.(\d+)/.exec(String(v ?? '')); return m ? `${m[1]}.${m[2]}` : null }
+
+function nodeHooks(s, ctx) {
+  const out = plan0()
+  const ws = ctx.ws
+  const pkgFile = join(s.dir, 'package.json')
+  const text = read(ws, pkgFile)
+  let pkg = null
+  try { pkg = JSON.parse(text ?? '') } catch { /* below */ }
+  if (!pkg) return not(out, FUNCTIONS.hooks.unsupported.packageJson)
+  const fnVersion = pkg.dependencies?.['@azure/functions'] ?? pkg.devDependencies?.['@azure/functions'] ?? null
+  const major = Number(/(\d+)/.exec(String(fnVersion ?? ''))?.[1] ?? NaN)
+  if (!(major >= 4)) return not(out, FUNCTIONS.hooks.unsupported.nodeV3)
+  if (typeof pkg.main !== 'string' || !pkg.main.trim()) return not(out, FUNCTIONS.hooks.unsupported.nodeMain)
+  const H = HOOKS.node
+  out.versions.push({ name: '@azure/functions', found: String(fnVersion), tested: H.tested[0][1] })
+  // The hook file, and the main glob that loads it next to the functions (the worker loads every file it matches).
+  const file = join(s.dir, H.file)
+  if (read(ws, file) === null) out.edits.push({ file, before: null, after: template(H.file), why: 'Add the UKNOWS hooks for Azure Functions.' })
+  if (!pkg.main.includes(H.file)) {
+    const main = `{${H.file},${pkg.main}}`
+    const at = new RegExp(`("main"\\s*:\\s*)${JSON.stringify(pkg.main).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`)
+    const after = text.replace(at, `$1${JSON.stringify(main)}`)
+    if (after === text) return not(plan0(), FUNCTIONS.hooks.unsupported.nodeMain)
+    out.edits.push({ file: pkgFile, before: text, after, why: 'Load the UKNOWS hooks with the functions.' })
+    out.summary.push(fill(FUNCTIONS.hooks.summary.node, { file: H.file, main }))
+  } else out.summary.push(fill(FUNCTIONS.hooks.summary.file, { file: H.file }))
+  // The packages, at the versions of the bench, with the package manager of the repo (as the Node.js stack adds them).
+  const wanted = H.packages.filter(([name]) => !pkg.dependencies?.[name])
+  if (!wanted.length) return out
+  const pm = packageManager(s.dir, pkg, ctx.repo ?? ws)
+  const specs = wanted.map(([name, v]) => `${name}@${v}`)
+  if (pm.outside || pm.cmd === 'bun' || pm.cmd === 'other' || pm.pnp) {
+    out.manual.push({ title: FUNCTIONS.hooks.packagesTitle, required: true, verify: true,
+      lines: [FUNCTIONS.hooks.packagesByHand], snippets: [{ caption: 'Packages', language: 'text', code: specs.join('\n') }] })
+    return out
+  }
+  const flags = pm.cmd === 'npm' ? ['--save-exact', '--ignore-scripts', '--no-audit', '--no-fund', pm.lock ? '--package-lock-only' : '--no-package-lock']
+    : pm.cmd === 'pnpm' ? ['--save-exact', '--lockfile-only'] : ['--exact', pm.berry ? '--mode=skip-build' : '--ignore-scripts']
+  const lock = pm.lock ?? (pm.cmd === 'npm' ? null : join(s.dir, { pnpm: 'pnpm-lock.yaml', yarn: 'yarn.lock' }[pm.cmd]))
+  const why = `Add ${list(wanted.map(([name]) => name))} with ${pm.cmd}.`
+  const names = wanted.map(([name]) => name)
+  out.commands.push({ cwd: s.dir, cmd: pm.cmd, why, added: names, lockOnly: pm.cmd === 'pnpm' || (pm.cmd === 'npm' && Boolean(pm.lock)),
+    args: pm.cmd === 'npm' ? ['install', '--save', ...flags, ...specs] : ['add', ...flags, ...specs],
+    undo: { cmd: pm.cmd, args: [pm.cmd === 'npm' ? 'uninstall' : 'remove', ...flags.filter((f) => !/exact/.test(f)), ...names] },
+    touches: [pkgFile, ...(lock ? [lock] : [])] })
+  out.summary.push(why)
+  return out
+}
+
+/** The variable of the FunctionApp in function_app.py, and the line of the azure.functions import. */
+export function pythonApp(text) {
+  const apps = [...text.matchAll(/^(\w+)\s*=\s*(?:[\w.]+\.)?FunctionApp\s*\(/gm)].map((m) => m[1])
+  const imports = new Doc(text).lines.map((line, i) => [line, i]).filter(([line]) => /^(?:import\s+azure\.functions\b|from\s+azure\.functions\s+import\b|from\s+azure\s+import\s+functions\b)/.test(line))
+  return { app: apps.length === 1 ? apps[0] : null, apps: apps.length, importAt: imports.length ? imports[imports.length - 1][1] : -1 }
+}
+
+function pythonHooks(s, ctx) {
+  const out = plan0()
+  const ws = ctx.ws
+  const H = HOOKS.python
+  const appFile = join(s.dir, 'function_app.py')
+  const text = read(ws, appFile)
+  if (text === null || !/FunctionApp\s*\(/.test(text)) return not(out, FUNCTIONS.hooks.unsupported.pythonV1)
+  const reqFile = join(s.dir, 'requirements.txt')
+  const req = read(ws, reqFile)
+  if (req === null) return not(out, FUNCTIONS.hooks.unsupported.pythonRequirements)
+  const fnVersion = /^azure-functions\s*(?:==|~=|>=)\s*([\d.]+)/m.exec(req)?.[1] ?? null
+  out.versions.push({ name: 'azure-functions', found: fnVersion, tested: H.tested[0][1] })
+  const file = join(s.dir, H.file)
+  if (read(ws, file) === null) out.edits.push({ file, before: null, after: template(H.file), why: 'Add the UKNOWS hooks for Azure Functions.' })
+  // 2 lines in function_app.py: the import after the azure.functions import, and instrument(app) at the end.
+  const found = pythonApp(text)
+  if (!/^import uknows_otel\b/m.test(text)) {
+    if (!found.app || found.importAt < 0) {
+      out.manual.push({ title: FUNCTIONS.hooks.pythonTitle, required: true, verify: true,
+        lines: [fill(FUNCTIONS.hooks.pythonByHand, { file: appFile })],
+        snippets: [{ caption: appFile, language: 'python', code: 'import uknows_otel\n\n# ... your functions ...\n\nuknows_otel.instrument(app)' }] })
+    } else {
+      const doc = new Doc(text)
+      doc.insert(found.importAt + 1, 'import uknows_otel  # UKNOWS: a span for each call (npx @uknows/setup)')
+      const after = appendLines(doc.toString(), ['', '', `uknows_otel.instrument(${found.app})  # UKNOWS: after the last function`])
+      out.edits.push({ file: appFile, before: text, after, why: 'Load the UKNOWS hooks with the functions.' })
+    }
+  }
+  // The packages: lines in requirements.txt, which the remote build of Azure installs.
+  const names = new Set([...req.matchAll(/^\s*([A-Za-z0-9_.-]+)/gm)].map((m) => m[1].toLowerCase().replace(/_/g, '-')))
+  const missing = H.packages.filter(([name]) => !names.has(name)).map(([name, v]) => `${name}==${v}`)
+  if (missing.length) {
+    const compiled = compiledRequirements(ws, reqFile)
+    if (compiled) out.manual.push({ title: FUNCTIONS.hooks.packagesTitle, required: true, verify: true, lines: compiled,
+      snippets: [{ caption: 'Packages', language: 'text', code: missing.join('\n') }] })
+    else {
+      out.edits.push({ file: reqFile, before: req, after: appendLines(req, missing), why: 'Add the OpenTelemetry packages of the UKNOWS hooks.' })
+      out.summary.push(`Add ${missing.length} OpenTelemetry packages to ${reqFile}.`)
+    }
+  }
+  out.summary.unshift(fill(FUNCTIONS.hooks.summary.python, { file: H.file, app: appFile }))
+  out.extraSettings.push(...H.settings)
+  return out
+}
+
+/** The Program.cs edit: the middleware and the services, in the 3 shapes of the templates. null: another shape. */
+export function programEdit(text) {
+  const doc = new Doc(text)
+  const lines = doc.lines
+  const T = 'Uknows.AzureFunctions.UknowsOpenTelemetry'
+  // var builder = FunctionsApplication.CreateBuilder(args);
+  const app = lines.findIndex((l) => /^\s*var\s+\w+\s*=\s*FunctionsApplication\.CreateBuilder\s*\(\s*args\s*\)\s*;\s*$/.test(l))
+  if (app >= 0) {
+    const name = /var\s+(\w+)/.exec(lines[app])[1]
+    const indent = /^\s*/.exec(lines[app])[0]
+    doc.insert(app + 1, `${indent}${name}.UseMiddleware<${T}>();  // UKNOWS (npx @uknows/setup)`, `${indent}${T}.AddTo(${name}.Services);`)
+    return doc.toString()
+  }
+  // new HostBuilder().ConfigureFunctionsWorkerDefaults() or .ConfigureFunctionsWebApplication(), with no arguments.
+  const at = lines.findIndex((l) => /\.ConfigureFunctions(?:WorkerDefaults|WebApplication)\(\s*\)/.test(l))
+  const build = lines.findIndex((l, i) => i >= at && /\.Build\(\)/.test(l))
+  if (at < 0 || build < 0 || lines.filter((l) => /\.ConfigureFunctions(?:WorkerDefaults|WebApplication)\(/.test(l)).length !== 1) return null
+  doc.set(at, lines[at].replace(/\.ConfigureFunctions(WorkerDefaults|WebApplication)\(\s*\)/, `.ConfigureFunctions$1(worker => worker.UseMiddleware<${T}>())`))
+  const line = doc.get(build)
+  if (/^\s*\.Build\(\)/.test(line)) doc.insert(build, `${/^\s*/.exec(line)[0]}.ConfigureServices(${T}.AddTo)`)
+  else doc.set(build, line.replace(/\.Build\(\)/, `.ConfigureServices(${T}.AddTo).Build()`))
+  return doc.toString()
+}
+
+function dotnetHooks(s, ctx) {
+  const out = plan0()
+  const ws = ctx.ws
+  const H = HOOKS.dotnet
+  const csproj = (s.manifests ?? []).find((f) => f.endsWith('.csproj') && /Microsoft\.Azure\.Functions\.Worker"/i.test(read(ws, f) ?? ''))
+  const projText = csproj ? read(ws, csproj) : null
+  if (!projText) return not(out, FUNCTIONS.hooks.unsupported.dotnetInProcess)
+  const workerVersion = /<PackageReference\s+Include="Microsoft\.Azure\.Functions\.Worker"\s+Version="([^"]+)"/i.exec(projText)?.[1] ?? null
+  out.versions.push({ name: 'Microsoft.Azure.Functions.Worker', found: workerVersion, tested: H.tested[0][1] })
+  const dir = dirOf(csproj)
+  const file = join(dir, H.file)
+  if (read(ws, file) === null) out.edits.push({ file, before: null, after: template(H.file), why: 'Add the UKNOWS hooks for Azure Functions.' })
+  const program = join(dir, 'Program.cs')
+  const ptext = read(ws, program)
+  if (ptext !== null && !ptext.includes('UknowsOpenTelemetry')) {
+    const after = programEdit(ptext)
+    if (after) out.edits.push({ file: program, before: ptext, after, why: 'Add the UKNOWS middleware and the OpenTelemetry services.' })
+    else out.manual.push({ title: FUNCTIONS.hooks.dotnetTitle, required: true, verify: true, lines: [fill(FUNCTIONS.hooks.dotnetByHand, { file: program })],
+      snippets: [{ caption: program, language: 'csharp', code: 'builder.UseMiddleware<Uknows.AzureFunctions.UknowsOpenTelemetry>();\nUknows.AzureFunctions.UknowsOpenTelemetry.AddTo(builder.Services);' }] })
+  }
+  const missing = H.packages.filter(([name]) => !new RegExp(`<PackageReference\\s+Include="${name.replace(/\./g, '\\.')}"`, 'i').test(projText))
+  const central = /<ManagePackageVersionsCentrally>\s*true\s*</i.test(projText) || [dir, '.'].some((d) => /<ManagePackageVersionsCentrally>\s*true\s*</i.test(read(ws, join(d, 'Directory.Packages.props')) ?? ''))
+  if (missing.length) {
+    const after = central ? null : addItems(projText, missing.map(([name, v]) => `<PackageReference Include="${name}" Version="${v}" />`), /<PackageReference\s/)
+    if (after) {
+      out.edits.push({ file: csproj, before: projText, after, why: 'Add the OpenTelemetry packages of the UKNOWS hooks.' })
+      out.summary.push(`Add ${missing.length} OpenTelemetry packages to ${csproj}.`)
+    }
+    else out.manual.push({ title: FUNCTIONS.hooks.packagesTitle, required: true, verify: true, lines: [FUNCTIONS.hooks.packagesByHand],
+      snippets: [{ caption: 'Packages', language: 'bash', code: missing.map(([name, v]) => `dotnet add package ${name} --version ${v}`).join('\n') }] })
+  }
+  out.summary.unshift(fill(FUNCTIONS.hooks.summary.dotnet, { file: H.file, program }))
+  return out
+}
+
+/**
+ * The check of untested versions: an advice block when the app runs a version of the Functions library other than the
+ * one the bench ran (major.minor), or one that this tool cannot read. null when all match.
+ */
+export function versionCheck(versions) {
+  const off = versions.filter((v) => !v.found || minor(v.found) !== v.tested)
+  if (!off.length) return null
+  return { title: FUNCTIONS.hooks.untested.title, required: false, lines: [
+    ...off.map((v) => fill(v.found ? FUNCTIONS.hooks.untested.other : FUNCTIONS.hooks.untested.unknown, { name: v.name, found: v.found ?? '', tested: v.tested })),
+    fill(FUNCTIONS.hooks.untested.on, { on: TESTED_ON }), ...FUNCTIONS.hooks.untested.lines] }
+}

package/lib/stacks/functions.mjs

@@ -0,0 +1,148 @@
+/*
+ * Azure Functions (Node.js, Python and .NET isolated): the Functions host sends a server span for each call of a function,
+ * and the logs, over OTLP, when host.json has "telemetryMode": "OpenTelemetry" and the app has the OTLP app settings.
+ * Measured on the bench on 22 Oct 2026 (install proof A3): every request had its server span in all 3 languages, with
+ * no package and no code in the app. So the plan is 1 line in host.json. The settings and the key go on the function
+ * app as app settings (settings.mjs and the key steps), never in the repo.
+ *
+ * host.json keeps its own text: the line goes after "version", with the indent and the comma style of the file. A value
+ * of telemetryMode that the app has already is never changed: the step says what to set.
+ *
+ * Application Insights: with telemetryMode OpenTelemetry the host still sends to it, but names each request by its
+ * route instead of the function and leaves out InvocationId (measured 22 Oct 2026), so the portal's function views and
+ * the customer's queries change. So the line goes in only when setup knows the app does not send to Application
+ * Insights: the app settings of the function app have no connection string (az, names only, a run in a terminal) and
+ * no deploy file sets one. Else (or when setup cannot tell) it adds the UKNOWS worker hooks (functions-hooks.mjs),
+ * which keep Application Insights exactly as it is; where the hooks cannot apply, it stands down with a step.
+ * --functions-opentelemetry puts the line in anyway. The host and the worker send to Application Insights only with a
+ * connection string in the app settings, so packages and code that read it are signs to show, not proof: the
+ * templates of Microsoft have them too.
+ */
+import { FUNCTIONS } from '../contract.mjs'
+import { Doc } from '../doc.mjs'
+import { hooksPlan, versionCheck } from './functions-hooks.mjs'
+
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, k) => (k in values ? String(values[k]) : m))
+/** App settings and packages that send to Application Insights. */
+export const APP_INSIGHTS_SETTINGS = ['APPLICATIONINSIGHTS_CONNECTION_STRING', 'APPINSIGHTS_INSTRUMENTATIONKEY']
+/** Source code: a connection string there is read from the app settings. In a deploy file, the deploy sets it. */
+const CODE = /\.(?:[cm]?[jt]sx?|py|cs|fs|vb|java|go)$/i
+const DOTNET_APP_INSIGHTS = /<PackageReference\s+Include\s*=\s*["'](Microsoft\.Azure\.Functions\.Worker\.ApplicationInsights|Microsoft\.ApplicationInsights\.WorkerService)["']/i
+
+/**
+ * The signs in the repo that the app sends to Application Insights, as [{file, what, deploy}]: App Insights or Azure
+ * Monitor packages and code (existing.mjs), the connection string setting in its code or deploy files (deploy: true,
+ * the next deploy sets it), and the .NET Functions App Insights packages. Not the applicationInsights part of host.json:
+ * every Functions template has it, and it does nothing without a connection string.
+ */
+export function appInsightsSigns(s, view, existing = {}) {
+  const signs = []
+  const add = (file, what, deploy = false) => { if (!signs.some((x) => x.file === file && x.what === what)) signs.push({ file, what, deploy }) }
+  for (const x of [...(existing.azure ?? []), ...(existing.classic ?? [])]) add(x.file, x.what)
+  for (const a of existing.anchors ?? []) {
+    if (a.kind === 'connection-string') add(a.file, 'APPLICATIONINSIGHTS_CONNECTION_STRING', !CODE.test(a.file))
+    if (a.kind === 'appinsights-call') add(a.file, 'Application Insights in the code')
+  }
+  for (const file of s.manifests ?? []) {
+    const m = file.endsWith('.csproj') ? DOTNET_APP_INSIGHTS.exec(view.read(file) ?? '') : null
+    if (m) add(file, m[1])
+  }
+  return signs
+}
+
+/**
+ * What az shows of the function apps that the deploy files name, read only: for each {app, group}, the names of the app
+ * settings of the 1 function app of that name (never values). null when az is not installed or not signed in. A value
+ * of null for an app: not found, or found more than once.
+ */
+export async function functionAppSettingNames(cli, { root, env }, lookups) {
+  if (!lookups.length) return null
+  const az = (args) => cli('az', [...args, '--only-show-errors'], { cwd: root, env, timeoutMs: 60000 })
+  const accounts = await az(['account', 'list', '--query', "[?state=='Enabled'].{id:id, name:name}", '-o', 'json'])
+  if (accounts.error === 'missing' || accounts.code !== 0) return null
+  const subs = (parse(accounts.stdout) ?? []).filter((x) => typeof x?.id === 'string' && x.id)
+  if (!subs.length) return null
+  const out = new Map()
+  for (const { app, group } of lookups) {
+    const found = []
+    for (const sub of subs) {
+      const r = await az(['resource', 'list', '--subscription', sub.id, '--name', app, '--resource-type', 'Microsoft.Web/sites', '--query', '[].{name:name, resourceGroup:resourceGroup}', '-o', 'json'])
+      for (const row of (r.code === 0 ? parse(r.stdout) : null) ?? []) {
+        if (row?.name?.toLowerCase() === app.toLowerCase() && (!group || row.resourceGroup?.toLowerCase() === group.toLowerCase())) found.push({ sub: sub.id, group: row.resourceGroup, name: row.name })
+      }
+    }
+    if (found.length !== 1) { out.set(app, null); continue }
+    const f = found[0]
+    const r = await az(['functionapp', 'config', 'appsettings', 'list', '--subscription', f.sub, '-g', f.group, '-n', f.name, '--query', '[].name', '-o', 'json'])
+    const names = r.code === 0 ? parse(r.stdout) : null
+    out.set(app, Array.isArray(names) ? names.map(String) : null)
+  }
+  return out
+}
+const parse = (text) => { try { return JSON.parse(text) } catch { return null } }
+
+/** The edit that adds telemetryMode to host.json, or {already} or {other: value} or {unreadable}. */
+export function hostJsonEdit(text) {
+  const data = parse(text ?? '')
+  if (!data || typeof data !== 'object' || Array.isArray(data)) return { unreadable: true }
+  if (data.telemetryMode === FUNCTIONS.telemetryMode) return { already: true }
+  if (data.telemetryMode !== undefined) return { other: JSON.stringify(data.telemetryMode) }
+  const doc = new Doc(text)
+  // The "version" line at the top level: the first line with that key and the smallest indent of the object.
+  const at = doc.find(/^\s*"version"\s*:/)
+  const pair = `"telemetryMode": "${FUNCTIONS.telemetryMode}"`
+  let after
+  if (at >= 0 && /^\s*"version"\s*:\s*"[^"]*"\s*,?\s*$/.test(doc.get(at))) {
+    const line = doc.get(at)
+    const indent = /^\s*/.exec(line)[0]
+    if (/,\s*$/.test(line)) doc.insert(at + 1, `${indent}${pair},`)
+    else {
+      doc.set(at, line.replace(/\s*$/, ','))
+      doc.insert(at + 1, `${indent}${pair}`)
+    }
+    after = doc.toString()
+  } else {
+    // A host.json on 1 line, or with "version" in another form: the same object, written again with 2 spaces.
+    after = `${JSON.stringify({ version: data.version, telemetryMode: FUNCTIONS.telemetryMode, ...data }, null, 2)}\n`
+  }
+  return parse(after)?.telemetryMode === FUNCTIONS.telemetryMode ? { after } : { unreadable: true }
+}
+
+export const functions = {
+  id: 'functions',
+  /** @param {import('../types.mjs').Service} s */
+  plan(s, ctx) {
+    const plan = { summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [...FUNCTIONS.notes] }
+    const file = s.functions.hostJson
+    const before = ctx.ws.read(file)
+    const r = hostJsonEdit(before)
+    // ctx.functions: the decision of the engine ({route: 'host' or 'hooks', signs, unknown, predicted}). Without one,
+    // the line goes in (unit tests).
+    const decision = ctx.functions ?? { route: 'host', signs: [] }
+    if (r.after && decision.route === 'hooks') {
+      const hooks = hooksPlan(s, ctx)
+      if (!hooks.unsupported) {
+        const check = versionCheck(hooks.versions)
+        return { ...plan, summary: hooks.summary, edits: hooks.edits, commands: hooks.commands, extraSettings: hooks.extraSettings,
+          manual: [...hooks.manual, ...(check ? [check] : [])], notes: [...FUNCTIONS.hooks.notes] }
+      }
+      const S = FUNCTIONS.standDown
+      const first = decision.signs.length ? fill(S.signs, { signs: decision.signs.map((x) => `${x.what} in ${x.file}`).join(', ') }) : S.unknown
+      // Required and checked on each run: until OpenTelemetry is on, this app sends nothing to UKNOWS. stop: no
+      // settings, no record and no pull request for an app that this tool did not set up (engine.mjs).
+      plan.manual.push({ title: S.title, required: true, verify: true, lines: [fill(S.reason, { reason: hooks.unsupported }), first, ...S.lines] })
+      plan.notes = []
+      plan.stop = true
+      return plan
+    }
+    if (r.after && decision.predicted) plan.notes.push(FUNCTIONS.predicted)
+    if (r.after) {
+      plan.edits.push({ file, before, after: r.after, why: 'Turn on OpenTelemetry in the Functions host.' })
+      plan.summary.push(fill(FUNCTIONS.summary, { file }))
+    } else if (r.other || r.unreadable) {
+      const block = r.other ? FUNCTIONS.other : FUNCTIONS.unreadable
+      plan.manual.push({ title: block.title, required: true, verify: true, lines: block.lines.map((l) => fill(l, { file, value: r.other ?? '' })) })
+    }
+    return plan
+  },
+}

package/lib/stacks/guided.mjs

@@ -1,44 +1,152 @@
 // Go, PHP and Ruby: guided in v1. settings.mjs adds the settings as usual, but this tool does not edit
 // go.mod, composer.json, Gemfile or code: without the lock or sum updates the build breaks. It prints
-// the docs steps instead, and none when the SDK is already a dependency.
-import { GO_INIT, GO_MAIN, PINS, RUBY_INITIALIZER, STACKS } from '../contract.mjs'
-import { parseDockerfile } from '../dockerfile.mjs'
+// the docs steps instead. Each step stays until the repo shows it is done (the SDK in go.mod, otel.go, the
+// call in main, and so on), so a committed setup with a step undone stays at steps-left (exit 3).
+import { GO_INIT, GO_LIBRARIES, GO_OLDER, GO_RELEASES, PINS, RUBY_INITIALIZER, STACKS, goInstall, goMain } from '../contract.mjs'
+import { finalImage, finalStages, parseDockerfile } from '../dockerfile.mjs'
 
 const docs = (id) => STACKS.find((s) => s.id === id)
 const at = (dir, name) => (dir === '.' ? name : `${dir}/${name}`)
 const runIn = (dir) => `Run these commands in ${dir === '.' ? 'the root folder of the repo' : dir}.`
 const empty = () => ({ summary: [], edits: [], commands: [], extraSettings: [], manual: [], notes: [] })
+const fill = (text, values) => text.replace(/\{(\w+)\}/g, (m, key) => (key in values ? String(values[key]) : m))
+const goNumber = ([major, minor]) => major * 1000 + minor
 
 /** @type {import('../types.mjs').Applier} */
 export const go = {
   id: 'go',
   plan(service, { ws }) {
     const plan = empty()
-    if (/go\.opentelemetry\.io\/otel\/sdk\s/.test(ws.read(at(service.dir, 'go.mod')) ?? '')) return plan
-    const { install, files, notes, label } = docs('go')
-    // go get raises the go line of go.mod to what the modules need. An older Go builder then fails.
-    const version = /^(\d+)\.(\d+)/.exec(service.runtimeVersion ?? '')
-    const [major, minor] = PINS.go.minGo
-    if (version && Number(version[1]) * 1000 + Number(version[2]) < major * 1000 + minor) {
-      plan.manual.push({ title: `Use Go ${major}.${minor} or later`, lines: [`This app builds with Go ${version[0]}.`,
-        `The OpenTelemetry Go packages that go get adds need Go ${major}.${minor} or later.`,
-        `Update the go line in go.mod and the Go version of the build image to ${major}.${minor} or later. Do this first.`] })
+    const { files, notes, label } = docs('go')
+    // Each step is done when the repo shows it: the SDK in go.mod (go get writes it, also as // indirect), otel.go with
+    // setupOTel, and a call of setupOTel in the code. An app with its own NewTracerProvider set-up counts as done.
+    const done = goDone(service, ws)
+    if (done.packages && done.init && done.main) return plan
+    // go get raises the go line of go.mod to what the modules need, and an older Go builder then fails. So below
+    // Go 1.26 the go get lines name the versions for that Go (GO_RELEASES). Below the oldest row, Go is too old.
+    const version = goVersion(service, ws)
+    let release = null
+    if (version && goNumber(version) < goNumber(PINS.go.minGo)) {
+      release = GO_RELEASES.find((r) => r.go === version.join('.')) ?? null
+      // The Go note and the Go step go with the packages step: once go.mod has the SDK, Go was new enough for it.
+      if (release) { if (!done.packages) plan.notes.push(fill(GO_OLDER.plan, { version: release.go })) }
+      else {
+        release = GO_RELEASES.at(-1)
+        const oldest = PINS.go.oldestGo.join('.')
+        if (!done.packages) {
+          plan.manual.push({ title: `Use Go ${oldest} or later`, verify: true, lines: [`This app builds with Go ${version.join('.')}.`,
+            `The OpenTelemetry Go packages and otel.go need Go ${oldest} or later.`,
+            `Update the go line in go.mod and the Go version of the build image to ${oldest} or later. Do this first.`] })
+        }
+      }
     }
     // The base go get, then only the '# Gin only' or '# Echo v4 only' part for a detected router.
-    const sections = install.split('\n').reduce((all, line) => {
+    const sections = goInstall(release ?? undefined).split('\n').reduce((all, line) => {
       if (line.startsWith('# ')) all.push([line]); else all.at(-1).push(line)
       return all
     }, [[]])
-    const code = sections.filter((s, k) => k === 0 || service.frameworks.some((f) => s[0].toLowerCase().includes(f))).flat().join('\n')
+    const lines = [runIn(service.dir)]
+    const code = [sections.filter((s, k) => k === 0 || service.frameworks.some((f) => s[0].toLowerCase().includes(f))).flat().join('\n')]
+    if (release && service.frameworks.includes('echo') && /otelecho/.test(code[0])) lines.push(GO_OLDER.echo)
+    // Spans for each query and each Redis command, for the libraries in go.mod.
+    // At versions that do not raise the gorm or go-redis of go.mod (a newer go-redis can send a handshake that the Redis server refuses).
+    const mod = ws.read(at(service.dir, 'go.mod')) ?? ''
+    const gorm = requireOf(mod, 'gorm.io/gorm')
+    if (gorm !== undefined) {
+      const fit = GO_LIBRARIES.gorm.versions.find((v) => gorm && semver(v.gorm) <= semver(gorm))
+      if (gorm && !fit) lines.push(fill(GO_LIBRARIES.gorm.tooOld, { gorm }))
+      else {
+        // An unknown gorm version gets the oldest plugin, which raises gorm to the gorm of that plugin.
+        const plugin = fit ?? GO_LIBRARIES.gorm.versions.at(-1)
+        lines.push(GO_LIBRARIES.gorm.note)
+        if (!gorm) lines.push(fill(GO_LIBRARIES.gorm.raises, { gorm: plugin.gorm }))
+        code.push(`go get ${GO_LIBRARIES.gorm.module}@${plugin.version}`)
+      }
+    }
+    const redis = requireOf(mod, 'github.com/redis/go-redis/v9')
+    if (redis !== undefined) {
+      const known = GO_LIBRARIES.redis.versions
+      const at9 = !redis ? null : semver(redis) > semver(known.at(-1)) ? redis : known.filter((v) => semver(v) <= semver(redis)).at(-1) ?? null
+      lines.push(GO_LIBRARIES.redis.note)
+      code.push(`go get ${GO_LIBRARIES.redis.module}${at9 ? `@${at9}` : ''}`)
+    }
+    // main.go with the middleware of the router this app uses, and the address it listens on. Each note once: the
+    // gorm and go-redis notes are in the packages step already, and the notes of other routers do not apply.
+    const routers = ['echo', 'gin', 'chi'].filter((f) => service.frameworks.includes(f)).map((f) => (f === 'echo' && release && goOlder(release) ? 'echoOlder' : f))
+    const older = Boolean(release) || (version && goNumber(version) < goNumber(PINS.go.minGo))
+    // The Echo v5 note only for an app on Echo v5. The net/http note only for an app with no router that this tool knows:
+    // main.go already has the middleware of a known router.
+    const echoV5 = requireOf(mod, 'github.com/labstack/echo/v5') !== undefined
+    const router = (n) => (/^For chi,/.test(n) ? routers.includes('chi') : /^For Echo v5,/.test(n) ? echoV5
+      : /^For another router,/.test(n) || /^Use the middleware for your router\. For net\/http,/.test(n) ? !routers.length : true)
+    const mainNotes = notes.filter((n) => !(older && /^Use Go 1\.\d+ or later/.test(n)) && n !== GO_LIBRARIES.gorm.note && n !== GO_LIBRARIES.redis.note && router(n))
+    const main = goMain(routers.length ? routers : ['nethttp'], listenAddress(service, ws))
     plan.summary.push(`Show the steps to add OpenTelemetry to your ${label} code. You do these steps yourself.`)
-    plan.manual.push(
-      { title: 'Add the OpenTelemetry Go packages', lines: [runIn(service.dir)], snippets: [{ caption: 'go get', language: 'bash', code }] },
-      { title: `Add ${at(service.dir, files[0].path)}`, lines: [files[0].summary], snippets: [{ caption: files[0].path, language: 'go', code: GO_INIT }] },
-      { title: 'Start OpenTelemetry in main', lines: [files[1].summary, ...notes], snippets: [{ caption: files[1].path, language: 'go', code: GO_MAIN }] })
+    plan.manual.push(...[
+      !done.packages && { title: 'Add the OpenTelemetry Go packages', verify: true, lines, snippets: [{ caption: 'go get', language: 'bash', code: code.join('\n') }] },
+      !done.init && { title: `Add ${at(service.dir, files[0].path)}`, verify: true, lines: [files[0].summary], snippets: [{ caption: files[0].path, language: 'go', code: GO_INIT }] },
+      !done.main && { title: 'Start OpenTelemetry in main', verify: true, lines: [routers.length === 1 ? 'Change main like this.' : files[1].summary, ...mainNotes],
+        snippets: [{ caption: files[1].path, language: 'go', code: main }] },
+    ].filter(Boolean))
     return plan
   },
 }
 
+/**
+ * Which Go steps the repo shows as done. packages: go.mod requires the SDK. init: a .go file of the service has
+ * func setupOTel (otel.go) or its own NewTracerProvider. main: a .go file calls setupOTel, or the app has its own
+ * NewTracerProvider and no setupOTel, which this tool cannot follow. Comments do not count. Test files do not count.
+ */
+function goDone(service, ws) {
+  const packages = /go\.opentelemetry\.io\/otel\/sdk\s/.test(ws.read(at(service.dir, 'go.mod')) ?? '')
+  const code = ws.files(service.dir).filter((f) => f.endsWith('.go') && !f.endsWith('_test.go'))
+    .map((f) => (ws.read(f) ?? '').replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, ''))
+  const defines = code.some((t) => /\bfunc\s+setupOTel\s*\(/.test(t))
+  const own = code.some((t) => /\bNewTracerProvider\s*\(/.test(t))
+  const calls = code.some((t) => /\bsetupOTel\s*\(/.test(t.replace(/\bfunc\s+setupOTel\s*\(/g, '')))
+  return { packages, init: defines || own, main: calls || (own && !defines) }
+}
+
+/** Echo v4 with a Go below the Go of echo-otel uses the older contrib middleware otelecho, as goInstall does. */
+const goOlder = (release) => Number(release.go.split('.')[1]) < 25
+
+/**
+ * The address the app listens on, for main.go: the port of the first EXPOSE in the Dockerfile, else the first
+ * ":port" that the Go code passes to a server, else :8080.
+ */
+function listenAddress(service, ws) {
+  const docker = service.dockerfile ? ws.read(service.dockerfile) : null
+  const exposed = docker ? /^\s*EXPOSE\s+(\d{2,5})\b/im.exec(docker)?.[1] : null
+  if (exposed) return `:${exposed}`
+  for (const file of ws.files(service.dir).filter((f) => f.endsWith('.go') && !f.endsWith('_test.go'))) {
+    const m = /(?:\.Start|\.Run|ListenAndServe|Addr\s*:)\s*\(?\s*"([\w.-]*:\d{2,5})"/.exec(ws.read(file) ?? '')
+    if (m) return m[1].slice(m[1].lastIndexOf(':'))
+  }
+  return ':8080'
+}
+
+/** The version that go.mod requires for a module: 'v1.2.3', null when the line has no plain version, undefined when absent. */
+function requireOf(mod, module) {
+  const m = new RegExp(`^\\s*(?:require\\s+)?${module.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s+(\\S+)`, 'm').exec(mod)
+  if (!m) return undefined
+  return /^v\d+\.\d+\.\d+$/.test(m[1]) ? m[1] : null
+}
+
+/** A plain vX.Y.Z as 1 number that sorts like the version. */
+const semver = (v) => { const [a, b, c] = v.slice(1).split('.').map(Number); return (a * 1000 + b) * 1000 + c }
+
+/**
+ * The Go version that builds the app: the golang image of the Dockerfile (the last golang stage), else the go line
+ * of go.mod. [major, minor], or null when unknown.
+ */
+function goVersion(service, ws) {
+  const docker = service.dockerfile ? ws.read(service.dockerfile) : null
+  const images = docker ? parseDockerfile(docker).stages.map((stage) => stage.image) : []
+  const tag = images.map((image) => /(?:^|\/)golang:(\d+)\.(\d+)/.exec(image)).filter(Boolean).at(-1)
+  const m = tag ?? /^(\d+)\.(\d+)/.exec(service.runtimeVersion ?? '')
+  return m ? [Number(m[1]), Number(m[2])] : null
+}
+
 /** The docs RUN lines that install the PHP extension in official php images. */
 const PHP_RUN = (() => {
   const lines = docs('php').dockerfile.split('\n')
@@ -48,6 +156,9 @@ const PHP_RUN = (() => {
   return lines.slice(start, end + 1).join('\n')
 })()
 
+/** A RUN that installs the OpenTelemetry PHP extension: pecl, install-php-extensions or pie. */
+const PHP_EXTENSION = /\bpecl\s+install\b[^&;|\n]*\bopentelemetry\b|\binstall-php-extensions\b[^&;|\n]*\bopentelemetry\b|\bpie\s+install\b[^&;|\n]*\bopen-telemetry\/ext-opentelemetry\b/
+
 /** @type {import('../types.mjs').Applier} */
 export const php = {
   id: 'php',
@@ -56,7 +167,14 @@ export const php = {
     plan.extraSettings.push({ ...PINS.php.autoload })
     let composer = {}
     try { composer = JSON.parse(ws.read(at(service.dir, 'composer.json')) ?? '{}') } catch { /* not JSON: print the steps */ }
-    if (composer.require?.['open-telemetry/sdk']) return plan
+    const packagesDone = Boolean(composer.require?.['open-telemetry/sdk'])
+    const dockerText = (service.dockerfile && ws.read(service.dockerfile)) || ''
+    const info = parseDockerfile(dockerText)
+    // The extension is done when a RUN of the final stage, or of a stage it builds on, installs it. Without a
+    // Dockerfile the repo cannot show it, so it goes with the Composer step.
+    const extensionDone = service.dockerfile ? finalStages(info).some((stage) => stage.instructions.some((x) => x.keyword === 'RUN' && PHP_EXTENSION.test(x.args)))
+      : packagesDone
+    if (packagesDone && extensionDone) return plan
     const { install, files, notes, label } = docs('php')
     const [pecl, allowPlugins, require] = install.split('\n')
     const note = (re) => notes.filter((n) => re.test(n))
@@ -65,8 +183,7 @@ export const php = {
       .find((m) => m && service.frameworks.includes(m[1].toLowerCase()))
     const laravel = service.frameworks.includes('laravel')
     const packages = laravel ? require : require.replace(/\S*opentelemetry-auto-laravel/, swap?.[2] ?? '').trimEnd()
-    const dockerText = (service.dockerfile && ws.read(service.dockerfile)) || ''
-    const image = parseDockerfile(dockerText).image ?? ''
+    const image = finalImage(info) ?? ''
     // composer install in a build stage without the extension stops on the platform check.
     const platform = /composer\s+install\b/.test(dockerText) && !/ignore-platform-req/.test(dockerText) ? note(/--ignore-platform-req option/) : []
     const extension = service.dockerfile
@@ -75,10 +192,10 @@ export const php = {
       : { lines: ['Install the extension on each server.', files[0].summary],
         snippets: [{ caption: 'Install', language: 'bash', code: pecl }, { caption: files[0].path, language: 'ini', code: files[0].content }] }
     plan.summary.push(`Show the steps to add OpenTelemetry to your ${label} app. You do these steps yourself.`)
-    plan.manual.push({ title: 'Add the OpenTelemetry PHP extension', ...extension }, {
-      title: 'Add the OpenTelemetry Composer packages',
+    plan.manual.push(...[!extensionDone && { title: 'Add the OpenTelemetry PHP extension', verify: true, ...extension }, !packagesDone && {
+      title: 'Add the OpenTelemetry Composer packages', verify: true,
       lines: [runIn(service.dir), 'Commit composer.json and composer.lock.', ...(laravel ? [] : note(/PSR-18/)), ...platform, ...(/fpm/i.test(image) ? note(/PHP-FPM/) : [])],
-      snippets: [{ caption: 'composer', language: 'bash', code: [allowPlugins, packages].join('\n') }] })
+      snippets: [{ caption: 'composer', language: 'bash', code: [allowPlugins, packages].join('\n') }] }].filter(Boolean))
     return plan
   },
 }
@@ -88,17 +205,23 @@ export const ruby = {
   id: 'ruby',
   plan(service, { ws }) {
     const plan = empty()
-    if (/^\s*gem\s*\(?\s*["']opentelemetry-sdk["']/m.test(ws.read(at(service.dir, 'Gemfile')) ?? '')) return plan
+    // The gems step is done when the Gemfile has opentelemetry-sdk. The start step is done when config.ru or a .rb file
+    // under config/ (the Rails initializer) configures the SDK. Comment lines do not count.
+    const gemsDone = /^\s*gem\s*\(?\s*["']opentelemetry-sdk["']/m.test(ws.read(at(service.dir, 'Gemfile')) ?? '')
+    const startFiles = [at(service.dir, 'config.ru'), ...ws.files(at(service.dir, 'config')).filter((f) => f.endsWith('.rb'))]
+    const startDone = startFiles.some((f) => /^[^#\n]*\bOpenTelemetry::SDK\.configure\b/m.test(ws.read(f) ?? ''))
+    if (gemsDone && startDone) return plan
     const { install, files, notes, label } = docs('ruby')
     const rails = service.frameworks.includes('rails') || ws.read(at(service.dir, 'config/application.rb')) !== null
     plan.summary.push(`Show the steps to add OpenTelemetry to your ${label} app. You do these steps yourself.`)
-    plan.manual.push(
-      { title: 'Add the OpenTelemetry gems', lines: [runIn(service.dir), notes.find((n) => /Gemfile\.lock/.test(n))],
+    plan.manual.push(...[
+      !gemsDone && { title: 'Add the OpenTelemetry gems', verify: true, lines: [runIn(service.dir), notes.find((n) => /Gemfile\.lock/.test(n))],
         snippets: [{ caption: 'bundle', language: 'bash', code: install }] },
-      rails ? { title: `Add ${at(service.dir, files[0].path)}`, lines: [files[0].summary],
+      startDone ? null : rails ? { title: `Add ${at(service.dir, files[0].path)}`, verify: true, lines: [files[0].summary],
         snippets: [{ caption: files[0].path, language: 'ruby', code: RUBY_INITIALIZER }] }
-        : { title: `Add OpenTelemetry to ${at(service.dir, 'config.ru')}`, lines: [notes.find((n) => /config\.ru/.test(n))],
-          snippets: [{ caption: 'config.ru', language: 'ruby', code: RUBY_INITIALIZER }] })
+        : { title: `Add OpenTelemetry to ${at(service.dir, 'config.ru')}`, verify: true, lines: [notes.find((n) => /config\.ru/.test(n))],
+          snippets: [{ caption: 'config.ru', language: 'ruby', code: RUBY_INITIALIZER }] },
+    ].filter(Boolean))
     return plan
   },
 }