@haystackeditor/cli 0.24.0 → 0.25.0

package/dist/commands/init-telemetry.js

@@ -0,0 +1,1011 @@
+/**
+ * `haystack init --app <dir>`: telemetry (CAPTURE-V1 rule 8, capture_contracts.ts; this file is rules 8c-8e, the capture
+ * part is lane D1's and plugs in at planCapture).
+ *
+ * Every edit is an InitChange: shown first as a diff, made only with --yes (or a yes), and planned again from the files
+ * on a rerun, so a rerun after applying plans nothing. init edits only what it understands and says exactly what to do
+ * with the rest (rule 8: init never guesses):
+ *   - server telemetry (8c). A Next.js app's next.config gains withHaystackTelemetry as its outermost wrapper, in the
+ *     export form it already has (object, function, async function, other plugins; ESM or CommonJS). The edit is made on
+ *     the parsed file: the call and its import are spliced in at the positions Babel reports, so every other byte stays.
+ *     A Node server whose build script is a `tsc` compile with a declared outDir gains `haystack telemetry instrument
+ *     <outDir> --entry <entry>` after that compile, once. The CLI becomes a dependency through the app's own package
+ *     manager (its lockfile stays in step, so a frozen-lockfile CI install keeps working), pinned to this exact version:
+ *     Haystack can never push code into a customer's build (rule 13c);
+ *   - settings (9c). Lane C's `haystack telemetry settings --propose` writes `.haystack/telemetry-settings.proposed.json`,
+ *     left uncommitted for the user to review and approve with `haystack telemetry settings --approve` (which writes
+ *     `.haystack/telemetry-settings.json`); an existing allowlist is the user's reviewed approval and stays as it is;
+ *   - the data profile (8d). The `haystack db profile` command when the onboarding plan's database (or, before a plan
+ *     exists, the database the notes name) is Postgres, the engine the profiler reads;
+ *   - the report (8e). InitTelemetryReport, plus the person's steps beside it: the ingest token (init never mints, prints,
+ *     stores or reads one), production's environment, the start command, the deploy and the off switches (13c).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, extname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { classifyHttpError } from '../utils/haystack-api.js';
+import { gatewayFetch } from './case-batch.js';
+import { CAPTURE_EVIDENCE_FRESH_HOURS, CAPTURE_STATUS_PATH, } from './capture-contract.js';
+import { captureAnswers, planCapture } from './init-capture.js';
+import { discoverApps } from '../capture/adapters/index.js';
+import { loadBabel } from '../capture/js-ast.js';
+import { lineDiff } from './init.js';
+import { readTelemetryServerStatus } from './telemetry-token.js';
+import { readFacts } from './verify-onboarding.js';
+/** Lane D1: with the user's yes, init checks browser capture's registration with Haystack around the writes. */
+export { prepareCapture, withCaptureStep } from './init-capture.js';
+const CLI_PACKAGE = '@haystackeditor/cli';
+const NEXT_ENTRY = '@haystackeditor/cli/next';
+const WRAPPER = 'withHaystackTelemetry';
+/** withHaystackTelemetry relies on compiler.runAfterProductionCompile (packages/haystack-cli/src/telemetry/next.ts). */
+const NEXT_MINIMUM = [15, 4];
+const NEXT_CONFIGS = ['next.config.js', 'next.config.mjs', 'next.config.cjs', 'next.config.ts', 'next.config.mts', 'next.config.cts'];
+const INSTRUMENT_COMMAND = 'haystack telemetry instrument';
+const SETTINGS_FILE = '.haystack/telemetry-settings.json';
+const SETTINGS_PROPOSAL = '.haystack/telemetry-settings.proposed.json';
+/** The variable the db profile command reads; the person sets it to a read-only connection string where they run it. */
+const PROFILE_URL_ENV = 'HAYSTACK_PROFILE_DATABASE_URL';
+const PROFILE_FILE = 'haystack-db-profile.json';
+/* ------------------------------------------------------------------ files */
+function cliVersion() {
+    const path = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    const version = JSON.parse(readFileSync(path, 'utf8')).version;
+    if (typeof version !== 'string' || !/^\d+\.\d+\.\d+$/.test(version))
+        throw new Error(`The CLI's own package.json at ${path} has no release version.`);
+    return version;
+}
+function isFile(path) {
+    try {
+        return lstatSync(path).isFile();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+function inside(gitRoot, target) {
+    const path = relative(gitRoot, target);
+    return path === '' ? '.' : path.split(sep).join('/');
+}
+function change(gitRoot, target, reason, before, content, run) {
+    return { path: inside(gitRoot, target), action: before === null ? 'create' : 'update', reason, diff: lineDiff(before ?? '', content),
+        target, content, ...(run ? { run } : {}) };
+}
+function readPackage(path) {
+    const text = readFileSync(path, 'utf8');
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${path} is not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    if (!json || typeof json !== 'object' || Array.isArray(json))
+        throw new Error(`${path} is not a JSON object.`);
+    return { path, text, json: json, indent: /\n([ \t]+)"/.exec(text)?.[1] ?? '  ' };
+}
+/** A package.json as the planned edits before it leave it. */
+function packageFrom(path, text) {
+    return { path, text, json: JSON.parse(text), indent: /\n([ \t]+)"/.exec(text)?.[1] ?? '  ' };
+}
+function packageText(file, json) {
+    return `${JSON.stringify(json, null, file.indent)}${file.text.endsWith('\n') ? '\n' : ''}`;
+}
+function section(json, name) {
+    const value = json[name];
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+const LOCKFILES = [['pnpm-lock.yaml', 'pnpm'], ['package-lock.json', 'npm'], ['yarn.lock', 'yarn'], ['bun.lock', 'bun'], ['bun.lockb', 'bun']];
+/** The package manager that owns the app's lockfile: the nearest `packageManager` field, else the nearest lockfile, from
+ * the app up to the repository root. null: no lockfile, so the dependency is written into package.json itself. */
+function packageManager(gitRoot, appDir) {
+    for (let directory = appDir;; directory = dirname(directory)) {
+        const manifest = join(directory, 'package.json');
+        if (isFile(manifest)) {
+            const declared = readPackage(manifest).json.packageManager;
+            const name = typeof declared === 'string' ? /^(pnpm|npm|yarn|bun)@/.exec(declared)?.[1] : undefined;
+            if (name)
+                return { name: name, root: directory };
+        }
+        for (const [lockfile, name] of LOCKFILES) {
+            if (isFile(join(directory, lockfile)))
+                return { name, root: directory };
+        }
+        if (directory === gitRoot || dirname(directory) === directory)
+            return null;
+    }
+}
+/** The first release whose sites record repository-relative paths (what a registered tenant's src_prefix '' relies on)
+ * and that ships the `./next` entry: earlier releases are not compatible with either integration. */
+const CLI_COMPATIBLE_SINCE = [0, 24, 0];
+function parseVersion(text) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(text);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+function versionAtLeast(version, minimum) {
+    for (let i = 0; i < 3; i += 1)
+        if (version[i] !== minimum[i])
+            return version[i] > minimum[i];
+    return true;
+}
+/** The CLI the app resolves (its node_modules), and whether it has what the integration uses; null when none is installed. */
+function installedCli(appDir) {
+    let manifestPath;
+    try {
+        manifestPath = createRequire(join(appDir, 'package.json')).resolve(`${CLI_PACKAGE}/package.json`);
+    }
+    catch (error) {
+        if (error.code === 'MODULE_NOT_FOUND')
+            return null;
+        throw error;
+    }
+    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    const exportsMap = manifest.exports && typeof manifest.exports === 'object' ? manifest.exports : {};
+    const bin = manifest.bin && typeof manifest.bin === 'object' ? manifest.bin : {};
+    return { version: typeof manifest.version === 'string' ? parseVersion(manifest.version) : null, next: './next' in exportsMap,
+        bin: typeof bin.haystack === 'string' };
+}
+/** What the app's declared range guarantees at least: `x.y.z`, `^x.y.z` or `~x.y.z`; null for anything else (a tag, a
+ * workspace or file link, an open range), which init cannot check. */
+function declaredMinimum(spec) {
+    const match = /^[\^~]?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/.exec(spec.trim());
+    return match ? parseVersion(match[1]) : null;
+}
+function mergeNeeds(own, extra) {
+    if (extra === null)
+        return own;
+    return {
+        field: own.field === 'dependencies' || extra.field === 'dependencies' ? 'dependencies' : 'devDependencies',
+        next: own.next || extra.next,
+        bin: own.bin || extra.bin,
+        minimum: versionAtLeast(own.minimum, extra.minimum) ? own.minimum : extra.minimum,
+        why: `${own.why} ${extra.why}`,
+    };
+}
+/** Browser capture's need (lane D1): the build runs `haystack capture manifest`, which this CLI version has, and a production
+ * install must have it too, so the build step never runs a CLI that is not there (rule 13). */
+function captureNeed() {
+    return { field: 'dependencies', next: false, bin: true, minimum: parseVersion(cliVersion()),
+        why: 'The build runs `haystack capture manifest` to publish the route manifest, so the CLI is a production dependency (a production-only install keeps it).' };
+}
+/** The CLI as a compatible dependency in `field`, checked rather than assumed (rule 13: an edit that imports the CLI must
+ * never ship without it): an installed copy is checked for the entry the integration uses; without one, the declared
+ * range must guarantee a compatible release. Otherwise this exact version is installed (or, for Next.js, moved from
+ * devDependencies to dependencies) through the app's package manager, and the result is checked after it runs. A
+ * declaration init cannot check is left to the person. */
+function planDependency(gitRoot, appDir, pkg, after, need) {
+    const { field, why } = need;
+    const inProduction = section(pkg.json, 'dependencies')[CLI_PACKAGE];
+    const inDevelopment = section(pkg.json, 'devDependencies')[CLI_PACKAGE];
+    // Next.js loads next.config, and with it the CLI, at `next start`: only `dependencies` survive a production install.
+    const declared = field === 'dependencies' ? inProduction : inDevelopment ?? inProduction;
+    if (declared !== undefined) {
+        const installed = installedCli(appDir);
+        const compatible = installed
+            ? installed.version !== null && versionAtLeast(installed.version, need.minimum)
+                && (!need.next || installed.next) && (!need.bin || installed.bin)
+            : (() => {
+                const minimum = declaredMinimum(declared);
+                return minimum === null ? null : versionAtLeast(minimum, need.minimum);
+            })();
+        if (compatible === true)
+            return { kind: 'ok' };
+        if (compatible === null) {
+            return { kind: 'manual', why: `${inside(gitRoot, pkg.path)} declares ${CLI_PACKAGE} "${declared}", which init cannot check is `
+                    + `${need.minimum.join('.')} or newer. Set it to ${cliVersion()} in ${field}, then run \`haystack init\` again` };
+        }
+    }
+    const version = cliVersion();
+    const json = JSON.parse(after);
+    const entries = { ...section(json, field), [CLI_PACKAGE]: version };
+    json[field] = Object.fromEntries(Object.entries(entries).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    const promoting = field === 'dependencies' && inProduction === undefined && inDevelopment !== undefined;
+    if (promoting) {
+        const development = { ...section(json, 'devDependencies') };
+        delete development[CLI_PACKAGE];
+        json.devDependencies = development;
+    }
+    const content = packageText(pkg, json);
+    const manager = packageManager(gitRoot, appDir);
+    const spec = `${CLI_PACKAGE}@${version}`;
+    const dev = field === 'devDependencies';
+    const workspaceRoot = isFile(join(appDir, 'pnpm-workspace.yaml')) ? ['--workspace-root'] : [];
+    const argv = manager === null ? null : {
+        pnpm: ['pnpm', 'add', '--save-exact', dev ? '--save-dev' : '--save-prod', ...workspaceRoot, spec],
+        npm: ['npm', 'install', '--save-exact', dev ? '--save-dev' : '--save-prod', spec],
+        yarn: ['yarn', 'add', '--exact', ...(dev ? ['--dev'] : []), spec],
+        bun: ['bun', 'add', '--exact', ...(dev ? ['--dev'] : []), spec],
+    }[manager.name];
+    const action = promoting ? `Moved from devDependencies to dependencies at ${version}` : `Pinned to ${version}`;
+    const reason = argv
+        ? `${why} ${action} with \`${argv.join(' ')}\` in ${inside(gitRoot, appDir)}, which updates ${manager?.name}'s lockfile too.`
+        : `${why} ${action}: a newer release never reaches your build unless you change it.`;
+    // The package manager's own word is not taken for it: the manifest must say what the integration needs.
+    const check = () => {
+        const written = readPackage(pkg.path).json;
+        if (section(written, field)[CLI_PACKAGE] !== version)
+            return `${inside(gitRoot, pkg.path)} does not list ${spec} in ${field}`;
+        if (field === 'dependencies' && section(written, 'devDependencies')[CLI_PACKAGE] !== undefined) {
+            return `${inside(gitRoot, pkg.path)} still lists ${CLI_PACKAGE} in devDependencies`;
+        }
+        return null;
+    };
+    const touches = manager === null ? [] : LOCKFILES.map(([lockfile]) => join(manager.root, lockfile));
+    return { kind: 'change', change: change(gitRoot, pkg.path, reason, after, content, argv ? { argv, cwd: appDir, touches, check } : undefined) };
+}
+function isNode(value) {
+    return !!value && typeof value === 'object' && typeof value.type === 'string' && typeof value.start === 'number';
+}
+function walk(node, visit) {
+    visit(node);
+    for (const [key, value] of Object.entries(node)) {
+        if (key === 'leadingComments' || key === 'trailingComments' || key === 'innerComments' || key === 'loc' || key === 'extra')
+            continue;
+        for (const child of Array.isArray(value) ? value : [value])
+            if (isNode(child))
+                walk(child, visit);
+    }
+}
+const named = (node, name) => isNode(node) && node.type === 'Identifier' && node.name === name;
+const stringValue = (node) => isNode(node) && node.type === 'StringLiteral' && typeof node.value === 'string' ? node.value : null;
+function isModuleExports(node) {
+    return isNode(node) && node.type === 'MemberExpression' && node.computed === false && named(node.object, 'module') && named(node.property, 'exports');
+}
+/** `require('<source>')`. */
+function requireOf(node) {
+    if (!isNode(node) || node.type !== 'CallExpression' || !named(node.callee, 'require'))
+        return null;
+    const args = node.arguments;
+    return args.length === 1 ? stringValue(args[0]) : null;
+}
+const STATEMENTS = new Set(['ImportDeclaration', 'ExpressionStatement', 'VariableDeclaration', 'ReturnStatement']);
+/** The exported expression without the type assertions around it (`x satisfies NextConfig`). */
+function unwrapTypes(node) {
+    let current = node;
+    while (current.type === 'TSSatisfiesExpression' || current.type === 'TSAsExpression' || current.type === 'ParenthesizedExpression') {
+        current = current.expression;
+    }
+    return current;
+}
+async function parse(code, file) {
+    const babel = await import('@babel/core');
+    const typescript = /\.[cm]?ts$/.test(file);
+    const ast = babel.parseSync(code, {
+        babelrc: false, configFile: false, filename: file, sourceType: 'unambiguous',
+        parserOpts: { plugins: typescript ? ['typescript'] : ['jsx'], createParenthesizedExpressions: false },
+    });
+    if (!ast?.program)
+        throw new Error('the parser returned no program');
+    return { program: ast.program, comments: ast.comments ?? [] };
+}
+/** Where code init adds at the top of a file goes: after the hashbang, the directives ('use strict') and the comments that
+ * open the file (`// @ts-check`, `/* eslint-disable *\/`, a licence: file-level, so they stay first), but before a JSDoc
+ * block that sits right on the first statement (`/** @type {import('next').NextConfig} *\/`), which documents that
+ * statement and stays with it. Always a line start; null when code shares a line with what must stay above it. */
+function topInsertion(code, parsed) {
+    const firstCode = parsed.program.body[0]?.start ?? code.length;
+    const after = (end) => {
+        const lineEnd = code.indexOf('\n', end);
+        if (lineEnd === -1)
+            return code.length;
+        return lineEnd + 1 > firstCode && firstCode !== code.length ? null : lineEnd + 1;
+    };
+    let position = parsed.program.interpreter ? after(parsed.program.interpreter.end) : 0;
+    const directives = (parsed.program.directives ?? []);
+    if (position !== null && directives.length > 0)
+        position = after(directives[directives.length - 1].end);
+    if (position === null)
+        return null;
+    for (const comment of parsed.comments) {
+        if (comment.end <= position)
+            continue;
+        if (comment.start >= firstCode || code.slice(position, comment.start).trim() !== '')
+            break;
+        if (comment.type === 'CommentBlock' && comment.value.startsWith('*') && code.slice(comment.end, firstCode).trim() === '')
+            break;
+        const next = after(comment.end);
+        if (next === null)
+            return null;
+        position = next;
+    }
+    return position;
+}
+/** The wrapper in one next.config's own export form, or why init leaves the file to the person. */
+function planNextConfigEdit(code, parsed) {
+    const body = parsed.program.body;
+    let cached = false;
+    walk(parsed.program, node => {
+        if (named(node, 'turbopackFileSystemCacheForBuild') || stringValue(node) === 'turbopackFileSystemCacheForBuild')
+            cached = true;
+    });
+    if (cached) {
+        return { kind: 'manual', why: 'it sets experimental.turbopackFileSystemCacheForBuild: a build that reuses cached Turbopack modules skips the '
+                + 'instrumenting loader, so withHaystackTelemetry refuses it. Turn that option off, then run `haystack init` again' };
+    }
+    // The local name the wrapper is imported as, if it is.
+    let local = null;
+    let importNode = null;
+    for (const statement of body) {
+        if (statement.type === 'ImportDeclaration' && stringValue(statement.source) === NEXT_ENTRY) {
+            for (const specifier of statement.specifiers) {
+                if (specifier.type === 'ImportSpecifier' && (named(specifier.imported, WRAPPER) || stringValue(specifier.imported) === WRAPPER)) {
+                    local = specifier.local.name;
+                    importNode = statement;
+                }
+            }
+        }
+        if (statement.type === 'VariableDeclaration') {
+            for (const declarator of statement.declarations) {
+                if (requireOf(declarator.init) !== NEXT_ENTRY || declarator.id.type !== 'ObjectPattern')
+                    continue;
+                for (const property of declarator.id.properties) {
+                    if (property.type === 'ObjectProperty' && named(property.key, WRAPPER) && isNode(property.value) && property.value.type === 'Identifier') {
+                        local = property.value.name;
+                        importNode = statement;
+                    }
+                }
+            }
+        }
+    }
+    const esmDefaults = body.filter(statement => statement.type === 'ExportDefaultDeclaration');
+    const reexportsDefault = body.some(statement => statement.type === 'ExportNamedDeclaration'
+        && statement.specifiers?.some(specifier => named(specifier.exported, 'default') || stringValue(specifier.exported) === 'default'));
+    const cjsExports = body.filter(statement => statement.type === 'ExpressionStatement' && isNode(statement.expression)
+        && statement.expression.type === 'AssignmentExpression' && statement.expression.operator === '=' && isModuleExports(statement.expression.left));
+    let otherCjs = false;
+    walk(parsed.program, node => {
+        // module.exports.x = / exports.x = : the config is assembled in pieces init cannot wrap whole.
+        if (node.type === 'AssignmentExpression' && isNode(node.left) && node.left.type === 'MemberExpression'
+            && (isModuleExports(node.left.object) || named(node.left.object, 'exports')))
+            otherCjs = true;
+    });
+    const forms = esmDefaults.length + cjsExports.length;
+    if (reexportsDefault || otherCjs || forms !== 1) {
+        return { kind: 'manual', why: forms === 0 && !reexportsDefault && !otherCjs
+                ? 'it exports no config init can find (no `export default` and no `module.exports =`)'
+                : 'it exports its config in a form init does not edit (several exports, `export { x as default }` or `module.exports.x =`)' };
+    }
+    const esm = esmDefaults.length === 1;
+    const statement = esm ? esmDefaults[0] : cjsExports[0];
+    const exported = (esm ? statement.declaration : statement.expression.right);
+    if (local !== null) {
+        const core = exported.type === 'FunctionDeclaration' ? exported : unwrapTypes(exported);
+        if (core.type === 'CallExpression' && named(core.callee, local))
+            return { kind: 'installed' };
+        let used = false;
+        walk(parsed.program, node => { if (named(node, local) && !(importNode && node.start >= importNode.start && node.end <= importNode.end))
+            used = true; });
+        if (used) {
+            return { kind: 'manual', why: `it already calls ${WRAPPER}, but not as the outermost wrapper of the exported config. Make it the outermost `
+                    + `(\`export default ${WRAPPER}(<everything else>)\`), then run \`haystack init\` again` };
+        }
+    }
+    if (exported.type === 'ClassDeclaration'
+        || (exported.type.startsWith('TS') && exported.type !== 'TSSatisfiesExpression' && exported.type !== 'TSAsExpression')) {
+        return { kind: 'manual', why: `its default export is a ${exported.type}, not a config object or function` };
+    }
+    // House style for the lines init adds: the quotes of the file's first string, and whether its first simple statement
+    // ends with a semicolon.
+    const strings = [];
+    walk(parsed.program, node => { if (node.type === 'StringLiteral')
+        strings.push(node); });
+    const firstRaw = strings.sort((a, b) => a.start - b.start)[0]?.extra;
+    const quote = typeof firstRaw?.raw === 'string' && firstRaw.raw.startsWith('"') ? '"' : '\'';
+    const simple = [];
+    walk(parsed.program, node => { if (STATEMENTS.has(node.type))
+        simple.push(node); });
+    const first = simple.sort((a, b) => a.start - b.start)[0];
+    const semicolon = first && code[first.end - 1] === ';' ? ';' : '';
+    // A binding no name in the file already uses (any identifier counts, so neither a declaration nor a global it
+    // reads is shadowed).
+    const names = new Set();
+    walk(parsed.program, node => { if (node.type === 'Identifier' && typeof node.name === 'string')
+        names.add(node.name); });
+    let name = local ?? WRAPPER;
+    for (let n = 1; local === null && names.has(name); n += 1)
+        name = `${WRAPPER}_${n}`;
+    const splices = [];
+    if (local === null && esm) {
+        // Imports are hoisted, so after the file's last import (or at its top) the binding is ready wherever it is used.
+        const line = `import { ${name === WRAPPER ? WRAPPER : `${WRAPPER} as ${name}`} } from ${quote}${NEXT_ENTRY}${quote}${semicolon}`;
+        const imports = body.filter(node => node.type === 'ImportDeclaration');
+        const last = imports.length > 0 ? imports[imports.length - 1] : null;
+        if (last)
+            splices.push({ at: last.end, remove: 0, text: `\n${line}` });
+        else {
+            const at = topInsertion(code, parsed);
+            if (at === null)
+                return { kind: 'manual', why: 'code shares a line with its directives or opening comments, so init cannot add a line above it' };
+            const next = code.slice(at);
+            splices.push({ at, remove: 0, text: `${line}\n${/^\s*\n/.test(next) || at === code.length ? '' : '\n'}` });
+        }
+    }
+    else if (local === null) {
+        // A `const` is in its temporal dead zone until it runs, so the require goes directly before the statement that
+        // uses it (above the comments that open that statement, which may type it), wherever the file's other requires are.
+        const line = `const { ${name === WRAPPER ? WRAPPER : `${WRAPPER}: ${name}`} } = require(${quote}${NEXT_ENTRY}${quote});`;
+        const previousEnd = body.filter(node => node.end <= statement.start).reduce((end, node) => Math.max(end, node.end), 0);
+        let at = statement.start;
+        for (const comment of [...parsed.comments].reverse()) {
+            if (comment.end > at || comment.start < previousEnd || code.slice(comment.end, at).trim() !== '')
+                continue;
+            if (code.slice(code.lastIndexOf('\n', comment.start - 1) + 1, comment.start).trim() !== '')
+                break;
+            at = comment.start;
+        }
+        // Never above what opens the file: the hashbang, the directives and file-level comments stay first.
+        const top = topInsertion(code, parsed);
+        if (top === null)
+            return { kind: 'manual', why: 'code shares a line with its directives or opening comments, so init cannot add a line above it' };
+        at = Math.max(at, top);
+        splices.push({ at, remove: 0, text: `${line}\n` });
+    }
+    if (exported.type === 'FunctionDeclaration' && exported.id) {
+        // `export default function config()` stays a declaration (its name is a module binding); the export moves below it.
+        splices.push({ at: statement.start, remove: exported.start - statement.start, text: '' });
+        splices.push({ at: statement.end, remove: 0, text: `\n\nexport default ${name}(${exported.id.name})${semicolon}` });
+    }
+    else {
+        splices.push({ at: exported.start, remove: 0, text: `${name}(` });
+        splices.push({ at: exported.end, remove: 0, text: ')' });
+    }
+    let content = code;
+    for (const splice of splices.sort((a, b) => b.at - a.at || b.remove - a.remove)) {
+        content = content.slice(0, splice.at) + splice.text + content.slice(splice.at + splice.remove);
+    }
+    return { kind: 'edit', content };
+}
+/** [major, minor] of the Next.js this app builds with: the installed package when there is one, else the minimum of the
+ * declared range when it has a plain lower bound; null when neither says. */
+function nextVersion(appDir, declared) {
+    try {
+        const installed = createRequire(join(appDir, 'package.json'))('next/package.json').version;
+        const match = typeof installed === 'string' ? /^(\d+)\.(\d+)\./.exec(installed) : null;
+        if (match)
+            return [Number(match[1]), Number(match[2])];
+    }
+    catch (error) {
+        if (error.code !== 'MODULE_NOT_FOUND')
+            throw error;
+    }
+    const match = /^\s*(?:\^|~|>=|=)?\s*v?(\d+)\.(\d+)(?:\.\d+)?(?:-[0-9A-Za-z.-]+)?\s*$/.exec(declared);
+    return match ? [Number(match[1]), Number(match[2])] : null;
+}
+const atLeast = (version, minimum) => version[0] > minimum[0] || (version[0] === minimum[0] && version[1] >= minimum[1]);
+/** The server part for a Next.js app. `extra`: another part's CLI need, merged into this part's dependency; `covers` says
+ * the returned changes settle it. */
+async function planNext(gitRoot, appDir, pkg, extra) {
+    const declared = section(pkg.json, 'dependencies').next ?? section(pkg.json, 'devDependencies').next;
+    const version = nextVersion(appDir, declared);
+    const wrapperLines = [`import { ${WRAPPER} } from '${NEXT_ENTRY}';`, `export default ${WRAPPER}(nextConfig); // the outermost wrapper`];
+    // The dependency is settled before the config is touched: an import of a CLI production cannot load breaks `next start`.
+    const dependency = planDependency(gitRoot, appDir, pkg, pkg.text, mergeNeeds({ field: 'dependencies', next: true, bin: false,
+        minimum: CLI_COMPATIBLE_SINCE, why: `next.config imports ${NEXT_ENTRY}, and \`next start\` loads next.config in production, so the CLI is a production dependency.` }, extra));
+    const manualSteps = (why, file) => [
+        `init left ${file} alone: ${why}.`,
+        dependency.kind === 'ok' ? `Wrap the exported config in ${file}, outermost:`
+            : `Add ${CLI_PACKAGE}@${cliVersion()} to the app's dependencies (exact version, not devDependencies), then wrap the exported `
+                + `config in ${file}, outermost:`,
+        ...wrapperLines.map(line => `  ${line}`),
+    ];
+    if (dependency.kind === 'manual') {
+        return { changes: [], server: { status: 'manual', kind: 'next', steps: manualSteps(dependency.why, 'next.config') } };
+    }
+    if (version === null) {
+        return { changes: [], server: { status: 'manual', kind: 'next', steps: manualSteps(`it cannot tell which Next.js the app builds with (package.json declares next "${declared}" and none is installed here); `
+                    + `${WRAPPER} needs Next.js ${NEXT_MINIMUM.join('.')} or newer`, 'next.config') } };
+    }
+    if (!atLeast(version, NEXT_MINIMUM)) {
+        return { changes: [], server: { status: 'unsupported',
+                why: `${WRAPPER} needs Next.js ${NEXT_MINIMUM.join('.')} or newer; this app builds with ${version.join('.')}.` } };
+    }
+    const present = NEXT_CONFIGS.filter(name => isFile(join(appDir, name)));
+    if (present.length > 1) {
+        return { changes: [], server: { status: 'manual', kind: 'next', steps: manualSteps(`the app has several next.config files (${present.join(', ')}) and init does not pick one`, 'the one Next.js loads') } };
+    }
+    // The install first: a config edit is never made ahead of the dependency it imports.
+    const changes = dependency.kind === 'change' ? [dependency.change] : [];
+    let distDir = null;
+    if (present.length === 0) {
+        const target = join(appDir, 'next.config.mjs');
+        changes.push(change(gitRoot, target, `Wraps the app's Next.js config so \`next build\` instruments its server code for telemetry (the app had no next.config).`, null, `import { ${WRAPPER} } from '${NEXT_ENTRY}';\n\nexport default ${WRAPPER}({});\n`));
+    }
+    else {
+        const target = join(appDir, present[0]);
+        const code = readFileSync(target, 'utf8');
+        let parsed;
+        try {
+            parsed = await parse(code, target);
+        }
+        catch (error) {
+            return { changes: [], server: { status: 'manual', kind: 'next', steps: manualSteps(`it could not parse it (${error instanceof Error ? error.message.split('\n')[0] : String(error)})`, present[0]) } };
+        }
+        const edit = planNextConfigEdit(code, parsed);
+        if (edit.kind === 'manual')
+            return { changes: [], server: { status: 'manual', kind: 'next', steps: manualSteps(edit.why, present[0]) } };
+        if (edit.kind === 'edit') {
+            changes.push(change(gitRoot, target, `Wraps the exported Next.js config so \`next build\` instruments the app's server code for telemetry `
+                + `(its own export form kept; ${WRAPPER} is the outermost wrapper). Development and \`next start\` get the config unchanged.`, code, edit.content));
+        }
+        // The runtime lands in <distDir>/.haystack-telemetry; a literal distDir is read, anything else is Next's default.
+        walk(parsed.program, node => {
+            if (node.type === 'ObjectProperty' && named(node.key, 'distDir') && stringValue(node.value) !== null)
+                distDir = stringValue(node.value);
+        });
+    }
+    return { changes, server: { status: 'installed', kind: 'next', distDir: distDir ?? '.next' }, covers: true };
+}
+/* ---------------------------------------------------------------- node */
+/** A tsconfig's JSON with comments and trailing commas removed (strings are copied as they are). */
+function jsonc(text) {
+    let out = '';
+    for (let i = 0; i < text.length; i += 1) {
+        const char = text[i];
+        if (char === '"') {
+            let j = i + 1;
+            while (j < text.length && text[j] !== '"')
+                j += text[j] === '\\' ? 2 : 1;
+            out += text.slice(i, j + 1);
+            i = j;
+        }
+        else if (char === '/' && text[i + 1] === '/') {
+            while (i < text.length && text[i] !== '\n')
+                i += 1;
+            out += '\n';
+        }
+        else if (char === '/' && text[i + 1] === '*') {
+            i = text.indexOf('*/', i + 2);
+            if (i === -1)
+                throw new Error('an unterminated comment');
+            i += 1;
+        }
+        else
+            out += char;
+    }
+    return JSON.parse(out.replace(/,(\s*[}\]])/g, '$1'));
+}
+/** A config `extends` names, found as tsc finds it: a path (with or without `.json`), or a package's config. */
+function extendedConfig(from, specifier) {
+    const directory = dirname(from);
+    if (specifier.startsWith('.') || isAbsolute(specifier)) {
+        const path = resolve(directory, specifier);
+        if (isFile(path))
+            return path;
+        if (isFile(`${path}.json`))
+            return `${path}.json`;
+        if (isFile(join(path, 'tsconfig.json')))
+            return join(path, 'tsconfig.json');
+        throw new Error(`${inside(dirname(from), path)} (extended by ${from}) does not exist`);
+    }
+    const resolveFrom = createRequire(from);
+    for (const candidate of [specifier, `${specifier}.json`, `${specifier}/tsconfig.json`]) {
+        try {
+            return resolveFrom.resolve(candidate);
+        }
+        catch (error) {
+            if (error.code !== 'MODULE_NOT_FOUND' && error.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED')
+                throw error;
+        }
+    }
+    throw new Error(`${specifier} (extended by ${from}) is not installed, so its options are unknown`);
+}
+/** The options a tsconfig sets, its `extends` chain first (in order, a later one winning), then its own; only what some
+ * level sets. Throws with the reason when a level cannot be read or found: unknown options are never guessed. */
+function declaredCompile(path, chain) {
+    if (chain.includes(path))
+        throw new Error(`${path} extends itself`);
+    const config = jsonc(readFileSync(path, 'utf8'));
+    if (!config || typeof config !== 'object' || Array.isArray(config))
+        throw new Error(`${path} is not a JSON object`);
+    const object = config;
+    const bases = object.extends === undefined ? [] : Array.isArray(object.extends) ? object.extends : [object.extends];
+    let declared = {};
+    for (const base of bases) {
+        if (typeof base !== 'string')
+            throw new Error(`${path} has an extends entry that is not a string`);
+        declared = { ...declared, ...declaredCompile(extendedConfig(path, base), [...chain, path]) };
+    }
+    const options = section(object, 'compilerOptions');
+    const directory = dirname(path);
+    const own = {};
+    if (typeof options.outDir === 'string')
+        own.outDir = resolve(directory, options.outDir);
+    if (typeof options.rootDir === 'string')
+        own.rootDir = resolve(directory, options.rootDir);
+    for (const name of ['outFile', 'out'])
+        if (typeof options[name] === 'string')
+            own.outFile = resolve(directory, options[name]);
+    if (typeof options.noEmit === 'boolean')
+        own.noEmit = options.noEmit;
+    if (typeof options.emitDeclarationOnly === 'boolean')
+        own.emitDeclarationOnly = options.emitDeclarationOnly;
+    if (object.include !== undefined)
+        own.include = { patterns: object.include, base: directory };
+    return { ...declared, ...own };
+}
+function effectiveCompile(path) {
+    return { outDir: null, rootDir: null, outFile: null, noEmit: false, emitDeclarationOnly: false, include: null, ...declaredCompile(path, []) };
+}
+const SAFE_SCRIPT = /^[A-Za-z0-9_./=:@\s&-]+$/;
+const SAFE_PATH = /^[A-Za-z0-9_./@-]+$/;
+/** How tsc names the output of each source extension. */
+const EMITTED_FROM = { '.js': ['.ts', '.tsx', '.js', '.jsx'], '.mjs': ['.mts', '.mjs'], '.cjs': ['.cts', '.cjs'] };
+function option(argv, ...names) {
+    for (let i = 1; i < argv.length; i += 1) {
+        for (const name of names) {
+            if (argv[i] === name)
+                return argv[i + 1] ?? null;
+            if (argv[i].startsWith(`${name}=`))
+                return argv[i].slice(name.length + 1);
+        }
+    }
+    return undefined;
+}
+/** The server part for a Node server built with `tsc`; `extra` and `covers` as for planNext. */
+function planNode(gitRoot, appDir, pkg, extra) {
+    const scripts = section(pkg.json, 'scripts');
+    const build = scripts.build;
+    const appPath = inside(gitRoot, appDir);
+    // The CLI goes where the app already keeps it; devDependencies otherwise (the build runs it; production needs only the
+    // runtime it copies into the output).
+    const field = section(pkg.json, 'dependencies')[CLI_PACKAGE] !== undefined && section(pkg.json, 'devDependencies')[CLI_PACKAGE] === undefined
+        ? 'dependencies' : 'devDependencies';
+    const need = mergeNeeds({ field, next: false, bin: true, minimum: CLI_COMPATIBLE_SINCE,
+        why: 'The build runs `haystack`; the runtime it copies into the output is all production needs.' }, extra);
+    const manual = (reason) => ({ changes: [], server: { status: 'manual', kind: 'node', steps: [
+                `init left the build alone: ${reason}.`,
+                `If the build's final output is \`tsc\`'s one JavaScript file per source file in a directory, add \`&& ${INSTRUMENT_COMMAND} <that directory> `
+                    + `--entry <the server's entry file, relative to it>\` (and \`--source-root <the sources' directory>\` unless that is the directory's sibling `
+                    + `src/) to the end of the build script in ${appPath}/package.json, and add ${CLI_PACKAGE}@${cliVersion()} to devDependencies. Bundled `
+                    + 'output (esbuild, tsup, webpack, tsc --outFile) cannot be instrumented this way.',
+            ] } });
+    if (typeof build !== 'string' || build.trim() === '') {
+        return { changes: [], server: { status: 'unsupported', why: `${appPath}/package.json has no build script and the app is not Next.js: server `
+                    + 'telemetry instruments a Next.js build or the compiled output of a Node server\'s build.' } };
+    }
+    if (build.includes(INSTRUMENT_COMMAND)) {
+        // Already instrumented: what the build runs must still be installed (a rerun repairs it).
+        const dependency = planDependency(gitRoot, appDir, pkg, pkg.text, need);
+        if (dependency.kind === 'manual')
+            return manual(dependency.why);
+        return { changes: dependency.kind === 'change' ? [dependency.change] : [], server: { status: 'installed', kind: 'node', distDir: null }, covers: true };
+    }
+    // Commands joined by `&&` and nothing else: any other shell syntax could change what "after the compile" means.
+    const segments = build.split('&&').map(segment => segment.trim());
+    if (!SAFE_SCRIPT.test(build) || segments.some(segment => segment === '' || segment.includes('&'))) {
+        return manual('its build script uses shell syntax init does not edit (quotes, pipes, `;`, `||`, redirects or variables)');
+    }
+    const commands = segments.map(segment => segment.split(/\s+/));
+    const compiles = commands.filter(argv => argv[0] === 'tsc');
+    if (compiles.length !== 1)
+        return manual(compiles.length === 0 ? 'its build script runs no `tsc` compile' : 'its build script runs `tsc` more than once');
+    // The output instrumented must be tsc's: nothing may run after the compile (a bundler would replace or repack it).
+    if (commands[commands.length - 1] !== compiles[0])
+        return manual('commands run after its `tsc` compile, so the final output may not be tsc\'s');
+    const tsc = compiles[0];
+    for (const flag of ['-b', '--build', '-w', '--watch', '--noEmit', '--emitDeclarationOnly', '--outFile', '--out']) {
+        if (tsc.some(arg => arg === flag || arg.startsWith(`${flag}=`)))
+            return manual(`its \`tsc\` runs with ${flag}, which emits no per-file JavaScript output`);
+    }
+    const projectOption = option(tsc, '-p', '--project');
+    if (projectOption === null)
+        return manual('its `tsc` names a project without a path');
+    let project = resolve(appDir, projectOption ?? 'tsconfig.json');
+    if (existsSync(project) && statSync(project).isDirectory())
+        project = join(project, 'tsconfig.json');
+    if (!isFile(project))
+        return manual(`its \`tsc\` project ${inside(gitRoot, project)} does not exist`);
+    let compile;
+    try {
+        compile = effectiveCompile(project);
+    }
+    catch (error) {
+        return manual(`the options its compile takes effect with are unknown: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (compile.noEmit || compile.emitDeclarationOnly)
+        return manual(`${inside(gitRoot, project)} (with what it extends) emits no JavaScript`);
+    if (compile.outFile)
+        return manual(`${inside(gitRoot, project)} (with what it extends) bundles the output into one file (outFile)`);
+    const outOption = option(tsc, '--outDir');
+    const outDir = outOption ? resolve(appDir, outOption) : compile.outDir;
+    if (outDir === null)
+        return manual('its compile declares no outDir (in its config or anything it extends), so its output sits beside the sources');
+    // The sources the output mirrors: rootDir when declared, or a single included directory (tsc's inferred root then).
+    const rootOption = option(tsc, '--rootDir');
+    const patterns = compile.include?.patterns;
+    const rootDir = rootOption ? resolve(appDir, rootOption) : compile.rootDir
+        ?? (Array.isArray(patterns) && patterns.length === 1 && typeof patterns[0] === 'string' && !/[*?{]/.test(patterns[0])
+            ? resolve(compile.include.base, patterns[0]) : null);
+    if (rootDir === null)
+        return manual('its compile declares no rootDir (and includes more than one directory), so which sources the output mirrors is not declared');
+    // The server's entry: package.json main, or the start script's `node <file>`; it must be tsc's output of one source file.
+    const start = typeof scripts.start === 'string' ? scripts.start.trim().split(/\s+/) : [];
+    const entryPath = typeof pkg.json.main === 'string' ? resolve(appDir, pkg.json.main)
+        : start.length === 2 && start[0] === 'node' ? resolve(appDir, start[1]) : null;
+    if (entryPath === null || relative(outDir, entryPath).startsWith('..')) {
+        return manual(`neither package.json main nor a \`node <file>\` start script names the server's entry inside ${inside(gitRoot, outDir)}`);
+    }
+    const emitted = relative(outDir, entryPath);
+    const extension = extname(emitted);
+    const sources = (EMITTED_FROM[extension] ?? []).map(source => join(rootDir, emitted.slice(0, -extension.length) + source));
+    if (!sources.some(isFile)) {
+        return manual(`the entry ${inside(gitRoot, entryPath)} is not tsc's output of a source file under ${inside(gitRoot, rootDir)}`);
+    }
+    const outArg = relative(appDir, outDir).split(sep).join('/');
+    const entryArg = emitted.split(sep).join('/');
+    const sourceArg = rootDir === join(dirname(outDir), 'src') ? null : relative(appDir, rootDir).split(sep).join('/') || '.';
+    if (![outArg, entryArg, sourceArg ?? 'src'].every(path => SAFE_PATH.test(path)))
+        return manual('its paths need quoting in a script');
+    const instrument = `${INSTRUMENT_COMMAND} ${outArg} --entry ${entryArg}${sourceArg ? ` --source-root ${sourceArg}` : ''}`;
+    const json = structuredClone(pkg.json);
+    json.scripts = { ...scripts, build: `${build} && ${instrument}` };
+    const edited = packageText(pkg, json);
+    const dependency = planDependency(gitRoot, appDir, pkg, edited, need);
+    if (dependency.kind === 'manual')
+        return manual(dependency.why);
+    const changes = [change(gitRoot, pkg.path, `Instruments the server's compiled output for telemetry after each build (\`${instrument}\`); `
+            + 'application source is not changed.', pkg.text, edited)];
+    // The install runs after this edit (its result is checked, and every file init touched is restored if it fails).
+    if (dependency.kind === 'change')
+        changes.push(dependency.change);
+    return { changes, server: { status: 'installed', kind: 'node', distDir: null }, covers: true };
+}
+/* -------------------------------------------------------------- settings */
+/** The running CLI's own command line (`haystack ...`, whichever way it was invoked). */
+function ownCli() {
+    return [process.execPath, process.argv[1]];
+}
+/* CONNECT(lane C): a proposal is not an approval (rule 9c). `haystack telemetry settings --propose`, run at the repository
+ * root, writes <git root>/.haystack/telemetry-settings.proposed.json; a PERSON promotes it with `haystack telemetry
+ * settings --approve` (which shows the diff) into .haystack/telemetry-settings.json, the only file instrumentation
+ * honours. init runs the proposal and never approves. Until this CLI has both, the settings are a notice. */
+function settingsCommandAvailable() {
+    const [node, cli] = ownCli();
+    const help = spawnSync(node, [cli, 'telemetry', 'settings', '--help'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+    return help.status === 0 && help.stdout.includes('--propose') && help.stdout.includes('--approve');
+}
+function planSettings(gitRoot, notices) {
+    if (existsSync(join(gitRoot, SETTINGS_FILE)))
+        return { changes: [], settings: 'approved' };
+    const target = join(gitRoot, SETTINGS_PROPOSAL);
+    if (existsSync(target))
+        return { changes: [], settings: 'proposed' };
+    if (!settingsCommandAvailable()) {
+        notices.push(`This CLI cannot propose telemetry settings yet (\`haystack telemetry settings --propose\`), so server telemetry records only `
+            + 'shapes and sizes, never a setting\'s value. Run init again after updating the CLI.');
+        return { changes: [], settings: null };
+    }
+    const [node, cli] = ownCli();
+    return { settings: 'proposed', changes: [{
+                path: SETTINGS_PROPOSAL, action: 'create', target, content: '',
+                reason: 'Proposes which settings server telemetry may record by value (each a literal union, enum or `as const` list in the typed source); '
+                    + `everything else is recorded only as its shape and size. A proposal records nothing: your user approves it with \`haystack telemetry `
+                    + `settings --approve\`, which writes ${SETTINGS_FILE}.`,
+                diff: ['+ (the proposal `haystack telemetry settings --propose` writes; shown after it runs)'],
+                run: { argv: [node, cli, 'telemetry', 'settings', '--propose'], cwd: gitRoot, touches: [] },
+            }] };
+}
+/* --------------------------------------------------------------- capture */
+/** What the agent must ask its user before the browser tag can be set up (rules 2 and 8b: origins and consent are the
+ * user's answers, never inferred). */
+function captureQuestions(origins, consent) {
+    return [
+        ...(origins.length === 0 ? ['Ask your user for the app\'s production origins (for example https://app.example.com), then run '
+                + '`haystack init` again with `--origin <origin>` for each.'] : []),
+        ...(consent === undefined ? ['Ask your user whether the site asks visitors for consent, and with which consent platform, or whether '
+                + 'they have decided consent is not required; then run `haystack init` again with `--consent <platform>` or `--consent not-required`.'] : []),
+    ];
+}
+/* ------------------------------------------------------------------ plan */
+/** Everything init would change for telemetry in this checkout; reads only. Planned on every run (telemetry is part of
+ * onboarding): when an answer is missing (which app, in a repository with several; its origins; the consent choice),
+ * only the telemetry parts stop, with steps saying what the agent must ask its user. */
+export async function planTelemetry(gitRoot, repository, options) {
+    const notices = [];
+    let appDir;
+    if (options.app !== undefined) {
+        const requested = resolve(gitRoot, options.app);
+        if (!existsSync(requested) || !statSync(requested).isDirectory())
+            throw new Error(`--app ${options.app} is not a directory.`);
+        appDir = realpathSync(requested);
+        if (inside(gitRoot, appDir).startsWith('..') || isAbsolute(inside(gitRoot, appDir)))
+            throw new Error(`--app ${options.app} is outside this repository.`);
+    }
+    else {
+        // One rule for which directories are apps (capture/adapters/index.ts): a web framework an adapter claims, or a package
+        // with a start script.
+        await loadBabel();
+        const apps = await discoverApps(gitRoot);
+        if (apps.length !== 1) {
+            // Rule 8(a): init never picks among several apps, and never guesses one where it found none.
+            const ask = apps.length === 0
+                ? 'init found no app here (no web framework it recognizes and no package with a start script). If the repository has one that serves production, run '
+                    + '`haystack init` again with `--app <its directory>`.'
+                : `Ask your user which of these apps serves production: ${apps.join(', ')}; then run \`haystack init\` again with \`--app <that directory>\`.`;
+            const questions = [ask, ...captureQuestions(options.origins, options.consent)];
+            // A notice too, so a preview (which reports no telemetry yet) already says what to ask.
+            notices.push(`Telemetry waits for your user's answers: ${questions.join(' ')}`);
+            const waiting = { status: 'manual', steps: questions, received: null };
+            return { app: null, changes: [], notices, server: { status: 'manual', kind: null, steps: [ask] }, settings: null, capture: waiting,
+                captureRegistration: null };
+        }
+        appDir = realpathSync(join(gitRoot, apps[0]));
+    }
+    const app = inside(gitRoot, appDir);
+    const changes = [];
+    let server;
+    const manifest = join(appDir, 'package.json');
+    // CONNECT(lane D1): browser capture (init-capture.ts) plans with the answers in effect (flags, else the ones init recorded
+    // for this app); a missing answer is a question, never a guess.
+    const answers = captureAnswers(appDir, options.origins, options.consent);
+    const questions = captureQuestions(answers.origins, answers.consent);
+    const capture = questions.length > 0 ? null
+        : await planCapture({ gitRoot, appDir, repository, answers, registration: options.registration });
+    let capturePart = capture?.part ?? { status: 'manual', steps: questions, received: null };
+    if (capture) {
+        changes.push(...capture.changes);
+        notices.push(...capture.notices);
+    }
+    if (!isFile(manifest)) {
+        server = { status: 'unsupported', why: `${app} has no package.json: server telemetry supports Node.js apps (Next.js, or a Node server built with \`tsc\`).` };
+    }
+    else {
+        let pkg = readPackage(manifest);
+        // Capture's build step joins package.json first, the server part's edits build on it, and the CLI is pinned once for
+        // every part that runs it (a failed install restores every file, so no build step outlives its CLI).
+        let extra = null;
+        if (capture?.needsCli) {
+            const text = capture.packageText ?? pkg.text;
+            const probe = planDependency(gitRoot, appDir, packageFrom(manifest, text), text, captureNeed());
+            if (probe.kind === 'manual') {
+                capturePart = capturePart.status === 'unsupported' ? capturePart
+                    : { status: 'manual', steps: [...(capturePart.status === 'manual' ? capturePart.steps : []), `Publish the route manifest: ${probe.why}.`], received: null };
+            }
+            else {
+                if (capture.packageText !== null) {
+                    changes.push(change(gitRoot, manifest, 'Publishes the route manifest after (or, for frameworks that assemble their output inside the build, before) '
+                        + 'each build with the CLI the app pins (CAPTURE-V1 rule 4).', pkg.text, capture.packageText));
+                    pkg = packageFrom(manifest, capture.packageText);
+                }
+                extra = captureNeed();
+            }
+        }
+        const isNext = section(pkg.json, 'dependencies').next !== undefined || section(pkg.json, 'devDependencies').next !== undefined;
+        const planned = isNext ? await planNext(gitRoot, appDir, pkg, extra) : planNode(gitRoot, appDir, pkg, extra);
+        server = planned.server;
+        changes.push(...planned.changes);
+        if (extra !== null && !planned.covers) {
+            const dependency = planDependency(gitRoot, appDir, pkg, pkg.text, extra);
+            if (dependency.kind === 'change')
+                changes.push(dependency.change);
+        }
+    }
+    let settings = null;
+    if (server.status !== 'unsupported') {
+        const proposed = planSettings(gitRoot, notices);
+        changes.push(...proposed.changes);
+        settings = proposed.settings;
+    }
+    if (questions.length > 0)
+        notices.push(`Telemetry waits for your user's answers: ${questions.join(' ')}`);
+    return { app, changes, notices, server, settings, capture: capturePart, captureRegistration: capture?.registration ?? null };
+}
+/* ---------------------------------------------------------------- report */
+function received(lastSeenAt, release) {
+    if (lastSeenAt === null)
+        return null;
+    const at = Date.parse(lastSeenAt);
+    if (!Number.isFinite(at))
+        throw new Error(`Telemetry evidence has an unreadable time ${lastSeenAt}.`);
+    return { lastSeenAt, release, stale: Date.now() - at > CAPTURE_EVIDENCE_FRESH_HOURS * 3_600_000 };
+}
+async function readJson(path, token) {
+    const response = await gatewayFetch(path, token);
+    if (response.status === 404) {
+        await response.body?.cancel();
+        return null;
+    }
+    if (!response.ok)
+        throw await classifyHttpError(response, `Haystack API ${path.split('?')[0]}`);
+    return response.json();
+}
+/** Lane A's registration of the application: its newest capture event, or null when it is not registered (404) or has none. */
+async function captureReceived(repository, app, token) {
+    const status = await readJson(`${CAPTURE_STATUS_PATH}?repository=${encodeURIComponent(repository)}&app=${encodeURIComponent(app)}`, token);
+    return status === null ? null : received(status.lastSeenAt, status.release);
+}
+function withReceived(part, evidence) {
+    return part.status === 'unsupported' ? part : { ...part, received: evidence };
+}
+const POSTGRES_WORD = /\bpostgres(?:ql)?\b/i;
+/** Rule 8(d): the profiler reads Postgres. The plan is the proof once onboarding has one; before that, the database the
+ * coding agent's own notes name (a word match on its run note against the one engine name, nothing looser). */
+function dbProfile(repository, onboarding, notes) {
+    const planned = onboarding?.state === 'ready' ? onboarding.services.filter(service => service.engine === 'postgres') : null;
+    if (planned ? planned.length === 0 : !(notes && POSTGRES_WORD.test(notes.run)))
+        return null;
+    const command = `haystack db profile --url-env ${PROFILE_URL_ENV} --out ${PROFILE_FILE}`;
+    return { command, steps: [
+            `Ask your user to profile production's data (a person's action: it needs read access to production's Postgres, which you never hold). `
+                + `With ${PROFILE_URL_ENV} set to a read-only connection string for it (a read replica is best), they run:`,
+            `  ${command}`,
+            `  haystack db profile show ${PROFILE_FILE}`,
+            `  haystack db profile upload ${PROFILE_FILE} --repo ${repository}`,
+            ...(planned && planned.length > 1
+                ? [`The onboarding plan has ${planned.length} Postgres databases (${planned.map(service => service.id).join(', ')}); `
+                        + '`haystack db profile upload --help` says how a profile names the one it describes.'] : []),
+        ] };
+}
+/** Rule 8(e): the report, and what the person does for telemetry to arrive (the token, production's environment, the start,
+ * the deploy) with the off switches (rule 13c). `onboarding` and `notes` feed the data profile. */
+export async function telemetryReport(plan, context) {
+    const { repository, token } = context;
+    const steps = [];
+    const serverPart = plan.server.status === 'unsupported' ? { status: 'unsupported', why: plan.server.why }
+        : plan.server.status === 'manual' ? { status: 'manual', steps: plan.server.steps, received: null } : { status: 'installed', received: null };
+    let server = serverPart;
+    // Answers only the user can give come first: until then the rest of telemetry waits (rule 8: init never guesses).
+    if (plan.app === null || plan.capture.status === 'manual') {
+        steps.push('Telemetry waits for answers only your user can give: ask what the `steps` of each `manual` part say, then run `haystack init` '
+            + 'again with them.');
+    }
+    if (plan.app !== null && plan.server.status !== 'unsupported') {
+        const status = await readTelemetryServerStatus(repository, token);
+        server = withReceived(serverPart, status.newestFlush === null ? null : received(status.newestFlush.storedAt, status.newestFlush.buildId));
+        if (plan.settings === 'proposed') {
+            // A proposal is not an approval (rule 9c): only the user approves, with the command that shows them the diff.
+            steps.push(`Show your user ${SETTINGS_PROPOSAL}: the settings whose values server telemetry would record (every other value is recorded only `
+                + 'as its shape and size). Nothing is recorded until THEY approve it by running `haystack telemetry settings --approve` themselves '
+                + `(it shows the diff and writes ${SETTINGS_FILE}); never approve it yourself. Then commit ${SETTINGS_FILE}.`);
+        }
+        steps.push(status.token === null
+            ? `Ask your user to run \`haystack telemetry token --repo ${status.repository}\` in their own terminal (it needs admin or maintain `
+                + 'permission on the repository). Never run it yourself: it creates a production credential, writes it to a file only they can read, and never prints it.'
+            : `A telemetry token is already active for ${status.repository} (minted ${status.token.createdAt}). If production does not have it, ask your `
+                + `user to run \`haystack telemetry token --repo ${status.repository}\` in their own terminal: it says which file holds it, and \`--rotate\` replaces a lost one.`);
+        steps.push('Have your user set these in production\'s server environment, never as public or client-side variables: HAYSTACK_TELEMETRY=1, '
+            + `HAYSTACK_TELEMETRY_ENDPOINT=${status.endpoint}, and HAYSTACK_TELEMETRY_TOKEN set to the contents of the token file.`);
+        if (plan.server.status === 'installed' && plan.server.kind === 'next') {
+            const runtime = posix.join(plan.app, plan.server.distDir ?? '.next', '.haystack-telemetry', 'register.cjs');
+            steps.push(`Start the production server (\`next start\` or a standalone server.js) with NODE_OPTIONS=--require=<absolute path of ${runtime} `
+                + 'where the app runs>; `next build` prints the exact line. A standalone image must also copy that .haystack-telemetry directory. Set it only '
+                + 'where a build with the wrapper produced that file: Node refuses to start when a --require file is missing.');
+        }
+        steps.push(`Deploy. Then run \`haystack init --json\` again with the same --app, --origin and --consent: \`telemetry.server.received\` `
+            + 'shows the newest flush Haystack holds.');
+    }
+    // Rule 13(c): the switches that need nothing of Haystack's, for each part set up.
+    const switches = [
+        ...(plan.app !== null && plan.server.status !== 'unsupported'
+            ? ['HAYSTACK_TELEMETRY=0 in production\'s environment turns server telemetry off at the next restart'] : []),
+        ...(plan.app !== null && plan.capture.status !== 'unsupported' ? ['removing the tag turns browser capture off'] : []),
+    ];
+    if (switches.length > 0)
+        steps.push(`Off switches your user controls without Haystack: ${switches.join(', and ')}.`);
+    const capture = plan.capture.status === 'unsupported' || plan.app === null ? plan.capture
+        : withReceived(plan.capture, await captureReceived(repository, plan.app, token));
+    // Before a plan, the notes this run gave, else the ones the repository already has.
+    const notes = context.onboarding?.state === 'ready' ? null
+        : context.notes ?? (await readFacts(repository, token)).facts.notes ?? null;
+    const profile = dbProfile(repository, context.onboarding, notes);
+    if (profile)
+        steps.push(...profile.steps);
+    return { telemetry: { capture, server, dbProfileCommand: profile?.command ?? null }, steps };
+}
+/** The report as lines for a person. */
+export function formatTelemetry(telemetry, steps) {
+    const part = (name, value) => {
+        if (value.status === 'unsupported')
+            return [`${name}: unsupported. ${value.why}`];
+        const evidence = value.received === null ? 'nothing received yet'
+            : `last received ${value.received.lastSeenAt}${value.received.release ? ` (release ${value.received.release})` : ''}${value.received.stale ? ', stale' : ''}`;
+        return [`${name}: ${value.status === 'installed' ? 'set up' : 'needs a manual step'}; ${evidence}.`,
+            ...(value.status === 'manual' ? value.steps.map(step => `  ${step}`) : [])];
+    };
+    return [chalk.bold('Telemetry'), ...part('Browser capture', telemetry.capture), ...part('Server telemetry', telemetry.server),
+        ...(steps.length > 0 ? ['', chalk.bold('Next, for telemetry to arrive:'), ...steps.map(step => (step.startsWith('  ') ? step : `• ${step}`))] : [])];
+}