@haystackeditor/cli 0.24.1 → 0.25.1

package/dist/commands/verify-onboarding.js

@@ -28,6 +28,7 @@ const STATES = ['ready', 'onboarding', 'blocked', 'incomplete', 'cancelled', 'no
 const BLOCK_KINDS = ['not-enabled', 'no-web-app', 'unsupported', 'question', 'outside-credential',
     'outside-dependency', 'evidence-too-large', 'budget', 'proof-failed'];
 const STAGE_STATUSES = ['pending', 'running', 'ok', 'reused', 'failed', 'blocked'];
+const SERVICE_ENGINES = ['postgres', 'mysql', 'redis', 'mongodb', 'convex'];
 const STAGE_WORDS = {
     inventory: 'reading the repository', plan: 'planning how to run the app', runtime: 'building its runtime',
     boot: 'starting the app', data: 'preparing its data', accounts: 'creating test accounts', workflow: 'proving a workflow',
@@ -99,6 +100,15 @@ export function parseOnboardingStatus(value, expected) {
         invalid('its stand-ins');
     if (!(value.worldMemoryMib === null || (typeof value.worldMemoryMib === 'number' && Number.isInteger(value.worldMemoryMib))))
         invalid('its world memory');
+    if (!Array.isArray(value.services) || !value.services.every(service => isRecord(service) && typeof service.id === 'string'
+        && SERVICE_ENGINES.includes(service.engine)))
+        invalid('its services');
+    const review = value.review;
+    if (!(review === null || (isRecord(review) && (review.verdict === 'accept'
+        || (review.verdict === 'skipped' && typeof review.reason === 'string' && review.reason.length > 0)))))
+        invalid('its review');
+    if (value.state !== 'ready' && review !== null)
+        invalid('its review');
     if (value.block !== null)
         parseOnboardingBlock(value.block);
     const checkpoint = value.checkpoint;
@@ -307,8 +317,18 @@ export function formatOnboarding(status) {
     const outside = [...status.standIns, ...status.unsetProviders, ...standInGapNotes(status.standInGaps)];
     if (outside.length)
         lines.push('', ...outside.map(note => chalk.yellow(`Note: ${safe(note)}`)));
+    const unreviewed = reviewNotes(status.review);
+    if (unreviewed.length)
+        lines.push('', ...unreviewed.map(note => chalk.yellow(`Note: ${safe(note)}`)));
     return lines.join('\n');
 }
+/** Rule 17 (amendment 32): an onboarding the independent review skipped, as the sentence every result shows; none otherwise. */
+export function reviewNotes(review) {
+    if (review?.verdict !== 'skipped')
+        return [];
+    return [`This onboarding was NOT reviewed: the independent review that checks the setup did not cheat is turned off for this `
+            + `team (${review.reason}).`];
+}
 /** Rule 15(g), amendment 3: a stand-in gap as the sentence every result shows. */
 export function standInGapNotes(gaps) {
     return gaps.map(gap => `A stand-in could not serve ${gap} while onboarding signed in and did the workflow; the crawl may meet it too.`);
@@ -336,7 +356,7 @@ function repositoryOf(value) {
     const origin = resolveOriginRepository(gitRoot);
     return `${origin.owner}/${origin.repository}`;
 }
-async function readFacts(repository, token) {
+export async function readFacts(repository, token) {
     const response = await gatewayFetch(`${FACTS_PATH}?repository=${encodeURIComponent(repository)}`, token);
     if (!response.ok)
         throw await classifyHttpError(response, `Haystack API ${FACTS_PATH}`);

package/dist/commands/verify.js

@@ -31,7 +31,8 @@ import { classifyHttpError, readWithRetries, SERVICE_SILENCE_LIMIT_MS, ServiceSi
 import { GATEWAY_TIMEOUT_MS, gatewayFetch } from './case-batch.js';
 import { CRAWL_BRIEF_MAX_FUNCTIONS, CRAWL_BRIEF_MAX_GROUPS, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_MAX_FINDINGS, CRAWL_MAX_FINDING_STEPS, CRAWL_MAX_IDEAS, CRAWL_MAX_STAND_IN_LINES, CRAWL_MAX_STAND_IN_ROWS, CRAWL_MAX_TEXT_CHARS, CRAWL_WAIT_MAX_MS, CRAWL_POOLS, } from './crawl-contract.js';
 import { captureCheckout, crawlUnavailableText, EXPLICIT_WALL_MS, normalModeFailure, postPrecomputeCapture, } from './verify-precompute.js';
-import { formatOnboarding, onboardingExitCode, readOnboardingStatus, reportOnboardingState, standInGapNotes, waitForOnboarding } from './verify-onboarding.js';
+import { formatOnboarding, onboardingExitCode, readOnboardingStatus, reportOnboardingState, reviewNotes, standInGapNotes, waitForOnboarding, } from './verify-onboarding.js';
+import { formatCapture, readPreVerifyCapture } from './capture-brief.js';
 const CRAWLS_PATH = '/api/agent/cloud-verifier/crawls';
 /** A held read (waitAfter): the service's hold, then the time any read gets. */
 const HELD_READ_TIMEOUT_MS = CRAWL_WAIT_MAX_MS + GATEWAY_TIMEOUT_MS;
@@ -256,13 +257,23 @@ function checkBrief(value) {
     // Amendment 19: each production row names a function the brief holds.
     const production = value.production;
     const line = (item) => isCount(item) && item >= 1;
+    const shares = (item) => records(item, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, row => text(row.category)
+        && typeof row.share === 'number' && Number.isFinite(row.share) && row.share >= 0);
+    // CAPTURE-V1 rule 9(d): sampler-5 estimates. A worker from before them sends none; that reads as none.
+    const estimates = (fn) => fn.estimates === undefined
+        || (isCount(fn.estimatesOmitted) && records(fn.estimates, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, estimate => line(estimate.line)
+            && (estimate.kind === 'branch' || estimate.kind === 'setting' || estimate.kind === 'value') && text(estimate.what)
+            && isCount(estimate.calls) && isCount(estimate.classified) && typeof estimate.partial === 'boolean' && isCount(estimate.partialCalls)
+            && shares(estimate.shares) && records(estimate.fields, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, field => text(field.field)
+            && isCount(field.objectCalls) && shares(field.shares))));
     if (production !== undefined && (!isRecord(production) || !isCount(production.windowDays) || !isCount(production.payloads)
         || !text(production.newestAt, true) || typeof production.partial !== 'boolean' || !records(production.functions, CRAWL_BRIEF_MAX_FUNCTIONS, fn => isCount(fn.index)
         && fn.index < value.functions.length && isCount(fn.branchesOmitted) && isCount(fn.valuesOmitted)
         && records(fn.branches, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, branch => line(branch.line) && isCount(branch.whenTrue)
             && isCount(branch.whenFalse) && typeof branch.capped === 'boolean')
         && records(fn.values, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, observed => line(observed.line) && text(observed.what)
-            && records(observed.shapes, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, shape => text(shape.shape) && isCount(shape.count))))))
+            && records(observed.shapes, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, shape => text(shape.shape) && isCount(shape.count)))
+        && estimates(fn))))
         invalid('its brief');
 }
 function checkManifest(value, view) {
@@ -742,7 +753,7 @@ async function submitCapture(capture, token, found) {
     }
     if (crawl.status === 'unavailable') {
         return { runId: null, onboarding: null,
-            line: `${before}, and ${found === null ? 'none' : 'another'} could not be started: ${crawlUnavailableText(crawl.reason)}.` };
+            line: `${before}, and ${found === null ? 'one' : 'another'} could not be started: ${crawlUnavailableText(crawl.reason)}.` };
     }
     if (crawl.status === 'onboarding') {
         return { runId: null, onboarding: 'onboarding', line: `${before}. The app is not onboarded for this base yet: `
@@ -833,6 +844,32 @@ async function waitForBrief(first, identity, token) {
         process.removeListener('SIGINT', interrupted);
     }
 }
+/** A share as the brief says it: rounded, a share too small to round still visible, and an estimate past 1 (sampling
+ * error) said as about all of them; the data keeps the estimate itself. */
+function percent(share) {
+    return share > 0 && share < 0.005 ? '<1%' : `~${Math.round(Math.min(share, 1) * 100)}%`;
+}
+const SHOWN_SHARES = 8;
+/** CAPTURE-V1 rule 9(d): "undefined ~12% (4,180 classified of 41,200)" per site, of observed calls, never users. */
+function describeEstimate(estimate) {
+    const number = (value) => value.toLocaleString('en-US');
+    const sample = `${number(estimate.classified)} classified of ${number(estimate.calls)}`
+        + (estimate.partial ? '; partial: classification was skipped in every window, so these are shares of the classified calls'
+            : estimate.partialCalls > 0 ? `; ${number(estimate.partialCalls)} calls in windows that skipped classification not included` : '');
+    const listed = (shares) => shares.slice(0, SHOWN_SHARES)
+        .map(row => `${safe(row.category)} ${percent(row.share)}`).join(', ')
+        + (shares.length > SHOWN_SHARES ? `, ${shares.length - SHOWN_SHARES} more (in --json)` : '');
+    if (estimate.kind === 'branch') {
+        const whenTrue = estimate.shares.find(row => row.category === 'true')?.share ?? 0;
+        return [`      in production: line ${estimate.line} was true in ${percent(whenTrue)} of observed calls (${sample})`];
+    }
+    const lines = [`      in production: line ${estimate.line} ${safe(estimate.what)}${estimate.kind === 'setting' ? ' (an approved setting)' : ''}`
+            + ` in observed calls: ${listed(estimate.shares)} (${sample})`];
+    for (const field of estimate.fields) {
+        lines.push(`        .${safe(field.field)} where it was an object (~${number(field.objectCalls)} calls): ${listed(field.shares)}`);
+    }
+    return lines;
+}
 /** The brief as a coding agent reads it: what the change touches, then Haystack's own ideas, then how to hand back intent and
  * ideas. Every function is in --json; the text shows the changed ones and those one step away, and says how many more. */
 export function formatBrief(brief) {
@@ -860,12 +897,18 @@ export function formatBrief(brief) {
                 + observed.shapes.map(shape => `${safe(shape.shape)} (${shape.count})`).join(', '));
         if (row.valuesOmitted)
             lines.push(`      and ${plural(row.valuesOmitted, 'more observed value')} (in --json)`);
+        for (const estimate of row.estimates ?? [])
+            lines.push(...describeEstimate(estimate));
+        if (row.estimatesOmitted)
+            lines.push(`      and ${plural(row.estimatesOmitted, 'more estimated site')} (in --json)`);
     });
     if (brief.production) {
         const shownSeen = brief.production.functions.filter(row => brief.functions[row.index].distance <= 1).length;
         lines.push(`  Production telemetry: the last ${brief.production.windowDays} days, newest ${safe(brief.production.newestAt)};`
             + ` ${plural(brief.production.functions.length, 'function')} seen running (${shownSeen} above). Counts marked + are lower bounds`
-            + `${brief.production.partial ? '; the read stopped at its budget, so every count is a lower bound' : ''}.`);
+            + `${brief.production.partial ? '; the read stopped at its budget, so every count is a lower bound' : ''}.`
+            + `${brief.production.functions.some(row => (row.estimates ?? []).length > 0)
+                ? ' Shares are estimates of the observed calls at each site (heavier users make more calls), never of users.' : ''}`);
     }
     else
         lines.push('  No production telemetry for this repository: set it up to see how this code runs for real users.');
@@ -887,7 +930,7 @@ export function formatBrief(brief) {
                 lines.push(`    ${safe(change.changeKey)}: ${safe(change.reason)}`);
         }
     }
-    lines.push('', 'Next: pick the ideas worth trying, add your own, and say what the change is for:', '  haystack verify --intent "<what the change is for>" --idea "<something to try>" [--idea ...]', 'Your ideas are explored first; the ideas above are explored in every crawl too.');
+    lines.push('', 'Next: pick the ideas worth trying, add your own, and say what you were asked to do (the task in the user\'s words, not what your code does):', '  haystack verify --intent "<what you were asked to do>" --idea "<something to try>" [--idea ...]', 'Your ideas are explored first; the ideas above are explored in every crawl too.');
     return lines.join('\n');
 }
 /** `haystack pre-verify` (CRAWL-V1 amendment 18): the brief of the current change, before any crawl. It captures the checkout as
@@ -901,10 +944,10 @@ export async function preVerifyCommand(options) {
     const capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, 'prepare', repositoryOverride(options.repo));
     const request = capture.derivation.request;
     const change = checkedChange(request.baseCommit, request.workCommit);
-    const finish = (onboarding, view) => {
+    const finish = (onboarding, view, captured = null) => {
         if (options.json)
             process.stdout.write(`${JSON.stringify(withSchema('pre-verify', { change, onboarding,
-                run: view === null ? null : { runId: view.runId, status: view.status }, brief: view === null ? null : briefOf(view) }), null, 2)}\n`);
+                run: view === null ? null : { runId: view.runId, status: view.status }, brief: view === null ? null : briefOf(view), capture: captured }), null, 2)}\n`);
     };
     if (!request.crawl) {
         note(`Nothing to check: this checkout has no changes against ${request.baseCommit.slice(0, 12)}.`);
@@ -954,8 +997,10 @@ export async function preVerifyCommand(options) {
     if (options.wait !== false && briefOf(view) === null && !TERMINAL.has(reportedStatus(view)))
         view = await waitForBrief(view, identity, auth.token);
     const brief = briefOf(view);
+    // CAPTURE-V1 rule 7b: the routes the change touches, with their share of captured sessions; null without capture set up.
+    const captured = await readPreVerifyCapture(findGitRoot(), identity.repository, auth.token, [...new Set([...(brief?.functions.map(fn => fn.file) ?? []), ...change.files])], new Date());
     if (options.json)
-        finish(onboarding, view);
+        finish(onboarding, view, captured);
     else if (brief !== null)
         console.log(formatBrief(brief));
     else if (!TERMINAL.has(reportedStatus(view)))
@@ -968,6 +1013,8 @@ export async function preVerifyCommand(options) {
             + (view.status === 'prepared' ? 'Run `haystack verify` to crawl the change; its results carry the brief.'
                 : view.status === 'completed' ? 'It was checked before briefs existed and is not run again: change anything in the checkout and run `haystack pre-verify` again.'
                     : 'Run `haystack pre-verify` again to prepare it again.'));
+    if (!options.json && captured !== null)
+        console.log(`\n${formatCapture(captured)}`);
     if (brief === null && TERMINAL.has(reportedStatus(view)))
         process.exitCode = 2;
 }
@@ -1047,7 +1094,7 @@ export async function verifyCommand(options) {
     else {
         console.log(formatCrawl(view));
         const notes = [...(onboarding?.dataAbsences ?? []), ...(onboarding?.versionChoices ?? []), ...(onboarding?.standIns ?? []),
-            ...(onboarding?.unsetProviders ?? []), ...standInGapNotes(onboarding?.standInGaps ?? [])];
+            ...(onboarding?.unsetProviders ?? []), ...standInGapNotes(onboarding?.standInGaps ?? []), ...reviewNotes(onboarding?.review ?? null)];
         if (notes.length)
             console.log(['', ...notes.map(note => `Note: ${safe(note)}`)].join('\n'));
     }

package/dist/index.js

@@ -31,6 +31,7 @@ import { lazy } from './lazy.js';
 // the startup path of every invocation, including --version and --help.
 const statusCommand = lazy(() => import('./commands/status.js'), 'statusCommand');
 const initCommand = lazy(() => import('./commands/init.js'), 'initCommand');
+const captureManifestCommand = lazy(() => import('./commands/capture-manifest.js'), 'captureManifestCommand');
 const authListCommand = lazy(() => import('./commands/login.js'), 'authListCommand');
 const authUseCommand = lazy(() => import('./commands/login.js'), 'authUseCommand');
 const loginCommand = lazy(() => import('./commands/login.js'), 'loginCommand');
@@ -72,6 +73,8 @@ const prReadCommand = lazy(() => import('./commands/pr.js'), 'prReadCommand');
 const inboxListCommand = lazy(() => import('./commands/inbox.js'), 'inboxListCommand');
 const askHaystackCommand = lazy(() => import('./commands/ask.js'), 'askHaystackCommand');
 const telemetryInstrumentCommand = lazy(() => import('./commands/telemetry.js'), 'telemetryInstrumentCommand');
+const telemetrySettingsCommand = lazy(() => import('./commands/telemetry.js'), 'telemetrySettingsCommand');
+const telemetryTokenCommand = lazy(() => import('./commands/telemetry-token.js'), 'telemetryTokenCommand');
 const setupCommand = lazy(() => import('./commands/setup.js'), 'setupCommand');
 const schemaCommand = lazy(() => import('./commands/schema-cmd.js'), 'schemaCommand');
 const listSchemas = lazy(() => import('./commands/schema-cmd.js'), 'listSchemas');
@@ -148,6 +151,10 @@ program
     .description('Set this repository up for `haystack verify` and start onboarding the app')
     .option('-y, --yes', 'Make the changes without asking')
     .option('--notes <file>', 'A JSON file (- for stdin) of what you know about running the app; see below')
+    .option('--app <dir>', 'The app whose telemetry init sets up, when the repository has several; see below')
+    .option('--origin <url>', 'A production origin of the app (repeat for several): browser capture accepts events only from these', (value, previous = []) => [...previous, value])
+    .option('--consent <choice>', 'How the site asks visitors for consent: its consent platform, or not-required when your user decided so')
+    .option('--url-rewrites <answer>', 'When init asks: none, or hidden-segment:<name> when the app\'s middleware adds a leading [<name>] segment to page paths')
     .option('--json', 'The result as one JSON document on stdout (see `haystack schema init`)')
     .addHelpText('after', `
 There is no setup file: Haystack works out how to run the app from what the
@@ -175,6 +182,28 @@ an hour). The file is JSON with any of three notes, each plain text:
 Leave out what you do not know. Onboarding still proves everything it takes
 from the notes. New notes start a new onboarding; the same notes again do not.
 
+Every run also plans telemetry for the app: --app names it when the repository
+has several (init never picks one), --origin its production origins and
+--consent the consent choice; until they are given, only telemetry waits and
+its report says what to ask. Server telemetry: a Next.js app's next.config
+gains the withHaystackTelemetry wrapper in its own export form; a Node server
+whose build ends in a \`tsc\` compile gains \`haystack telemetry instrument\`
+after it; the CLI becomes a checked, exact-version dependency through the
+app's package manager; \`haystack telemetry settings --propose\` writes a
+settings proposal that only your user approves (\`--approve\`). Each is a
+change shown first like the others, and a failed install restores every file.
+init never mints the ingest token: a repository admin runs
+\`haystack telemetry token\` themselves. \`--json\` reports \`telemetry\`
+(each part installed, manual or unsupported, and what Haystack last received)
+and \`telemetrySteps\` (what the person does next, including the off switch
+HAYSTACK_TELEMETRY=0).
+
+Browser capture: --consent is cookiebot, onetrust:<category id>, not-required
+or manual. init adds the self-hosted tag, its consent wiring and the build
+step that publishes the route manifest (\`haystack capture manifest\`, which
+never fails the build), registers the app for its key only with --yes, and
+reports the Content-Security-Policy lines the tag needs without editing them.
+
 Exit codes:
   0  set up: onboarding is running or the app is ready
   1  the command failed
@@ -245,7 +274,7 @@ const verify = program
     .option('--no-wait', 'Print the crawl\'s current state and return without waiting')
     .option('--minutes <n>', 'How long the crawl may take, 1-30 (default: .haystack.json crawl.minutes, else 3)')
     .addOption(new Option('--pool <pool>', 'Where the crawl\'s clones are created: fleet, freestyle or auto (default auto)').hideHelp())
-    .option('--intent <sentence>', 'What your change is for, in a sentence: the judge reads it so a difference you meant is not called a bug')
+    .option('--intent <sentence>', 'What you were asked to do, in the user\'s words (the task, not what your code does): the judge checks the app against it')
     .option('--idea <text>', 'Something to try in the app, said as you would to a tester (repeat for more); each is explored first', (value, previous = []) => [...previous, value])
     .option('--ideas-file <path>', 'A JSON array of more ideas')
     .option('--json', 'The crawl as one JSON document on stdout (see `haystack schema verify`)')
@@ -259,8 +288,8 @@ one it finds was cancelled, stopped before finishing or is being cancelled, it
 submits the capture (the service starts the crawl, or runs the stopped one
 again), says so, and follows that crawl.
 
-The coding agent that made the change can say what it is for (--intent) and
-what to try (--idea, as many as it likes, or --ideas-file). Each idea is
+The coding agent that made the change can say what it was asked to do (--intent:
+the task in the user's words, not a description of its code) and what to try (--idea, as many as it likes, or --ideas-file). Each idea is
 explored before anything else, and the answer says what became of it: tried,
 could not try (and why), or not finished in time. Other ideas make another
 crawl of the same code; the same ones again follow the same crawl.
@@ -318,10 +347,12 @@ same way, builds and prepares the change when nothing has yet (the turn-end
 hook usually has), and prints its brief: the functions the change touches, the
 changed ones and those one step away first (every one is in --json), and
 Haystack's own ideas of what could break, each with what to set up, what to do
-and what to watch. It never starts a crawl.
+and what to watch. With capture set up (.haystack/capture.json), it also shows
+the routes the change touches with their share of real users' sessions. It
+never starts a crawl.
 
-Then hand back what the change is for and what to try:
-  haystack verify --intent "<what the change is for>" --idea "<something to try>"
+Then hand back what you were asked to do and what to try:
+  haystack verify --intent "<what you were asked to do, in the user's words>" --idea "<something to try>"
 
 Exit codes: 0 with a brief; 2 when the run ended without one; 3 when the app's
 onboarding is blocked; 1 when the command failed.
@@ -970,6 +1001,54 @@ Example:
     includeSymbolsFile: options.includeSymbols,
     includeSymbols: undefined,
 }), options.json));
+telemetry
+    .command('settings')
+    .description('Propose .haystack/telemetry-settings.json: the settings whose values telemetry may record as themselves')
+    .option('--propose', 'Write candidates read from the typed source to .haystack/telemetry-settings.proposed.json for review')
+    .option('--approve', 'Show the reviewed proposal\'s change to .haystack/telemetry-settings.json and make it the allowlist')
+    .option('--dry-run', 'Print what would be written without writing')
+    .option('--json', 'Machine-readable proposal')
+    .addHelpText('after', `
+Server telemetry records every value as its shape and size only. A setting
+(a parameter or binding whose TypeScript type is a closed set of literals:
+'light' | 'dark', an enum, a boolean, an as-const array) is recorded as its
+literal only when it is in .haystack/telemetry-settings.json. --propose writes
+every candidate it finds to .haystack/telemetry-settings.proposed.json (approved
+entries kept as they are), refusing names and literals that look like identity
+or secrets (id, email, name, token, password, key, secret, address, phone).
+A proposal approves nothing: review it, then --approve shows the change to
+.haystack/telemetry-settings.json, writes it, and you commit it.
+`)
+    .action((options) => runPublicCommand(() => telemetrySettingsCommand(options), options.json));
+telemetry
+    .command('token')
+    .description('Mint the server-telemetry ingest token for a repository\'s production (run it yourself, in your own terminal)')
+    .option('--repo <owner/name>', 'GitHub repository whose production sends telemetry')
+    .option('--rotate', 'Replace the active token; the old one stops working at once')
+    .option('--out <file>', 'Where to write the token (default ~/.haystack/telemetry-ingest-tokens/<owner>__<name>-production.token)')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .addHelpText('after', `
+It needs admin or maintain permission on the repository and an interactive
+terminal: a coding agent or a script never runs it. The token is generated
+here and written to a file only you can read; it is never printed, and
+Haystack keeps only its SHA-256. Running it again mints nothing while a token
+is active and says whether that file holds it. Then set HAYSTACK_TELEMETRY=1,
+HAYSTACK_TELEMETRY_ENDPOINT and HAYSTACK_TELEMETRY_TOKEN in production's server
+environment (never a public or client-side variable).
+
+Exit codes: 0 minted, or the file holds the active token; 1 failed;
+2 declined at the prompt; 3 another token is active and this file does not
+hold it (--rotate replaces it).
+`)
+    .action((options) => runPublicCommand(() => telemetryTokenCommand(options)));
+program.command('capture').description('Real users\' journeys and devices: the tag `haystack init` adds')
+    .command('manifest')
+    .description('Publish the app\'s route manifest into its static output (the build step `haystack init` adds)')
+    .option('--app <dir>', 'The app directory (default: the current directory)')
+    .option('--rails-routes <file>', 'Rails: the routes file the rake task wrote')
+    .option('--adapter <id>', 'The framework adapter to use instead of the one init recorded in .haystack/capture.json')
+    .option('--json', 'The release, counts and files written as JSON')
+    .action((options) => runPublicCommand(() => captureManifestCommand(options), options.json));
 // ─── db ──────────────────────────────────────────────────────────────────────
 const dbProgram = program
     .command('db')

package/dist/schema.js

@@ -21,10 +21,10 @@ export const SCHEMA_VERSIONS = {
     'cloud-verifier': '1.0.0',
     'case-batch': '1.0.1',
     verify: '1.0.4',
-    'pre-verify': '1.0.1',
+    'pre-verify': '1.0.2',
     'verify-answer': '1.0.1',
     'verify-onboarding': '1.0.0',
-    init: '1.0.1',
+    init: '1.0.2',
     login: '1.0.0',
     error: '1.0.0',
 };

package/dist/telemetry/next-loader.cjs

@@ -6,9 +6,12 @@
  * require() it; the instrumenter itself is ESM and is imported on first use.
  *
  * Per module: leave it alone unless it is git-tracked repository source
- * outside node_modules; otherwise instrument it at its repository path and
- * record its sites in this build's session directory for the post-compile
- * step. A module that is not instrumented is returned byte-for-byte.
+ * outside node_modules (and not middleware); otherwise instrument it at its
+ * repository path and record its sites in this build's session directory for
+ * the post-compile step. A module that is not instrumented is returned
+ * byte-for-byte with the map it came with. Rule 13(b): an instrumented module's
+ * map is composed through the previous loader's, and nothing this loader does
+ * can fail the build.
  */
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
@@ -42,18 +45,44 @@ function trackedFiles(sourceRoot) {
     }
     return tracked;
 }
-async function instrument(context, source, options) {
+/** Middleware (`middleware.*`, and Next 16's `proxy.*`) at the project root or in `src/`. Next may compile it for the
+ * Node runtime, where the bundler's own conditions would let it through; rule 13(b) says it is never instrumented. */
+function isMiddleware(resourcePath, projectDirectory) {
+    const fromProject = (0, node_path_1.relative)(projectDirectory, resourcePath).split(node_path_1.sep).join('/');
+    const stem = fromProject.replace(/\.[cm]?[jt]sx?$/, '');
+    return stem !== fromProject && ['middleware', 'src/middleware', 'proxy', 'src/proxy'].includes(stem);
+}
+/** A previous loader's map: webpack hands an object or its JSON text. */
+function inputMap(sourceMap) {
+    if (typeof sourceMap === 'string') {
+        try {
+            const parsed = JSON.parse(sourceMap);
+            return parsed && typeof parsed === 'object' ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return sourceMap && typeof sourceMap === 'object' ? sourceMap : null;
+}
+async function instrument(context, source, sourceMap, options) {
     const relativePath = (0, node_path_1.relative)(options.sourceRoot, context.resourcePath);
     if (!relativePath || relativePath.startsWith('..') || (0, node_path_1.isAbsolute)(relativePath))
         return null;
     const sourcePath = relativePath.split(node_path_1.sep).join('/');
-    if (sourcePath.split('/').includes('node_modules') || !trackedFiles(options.sourceRoot).has(sourcePath)) {
+    if (sourcePath.split('/').includes('node_modules') ||
+        (options.tracked && !trackedFiles(options.sourceRoot).has(sourcePath))) {
         return null;
     }
+    if (isMiddleware(context.resourcePath, options.projectDirectory))
+        return null;
     const result = (await loadTelemetry()).instrumentBundledModule(source, {
         sourcePath,
+        absolutePath: context.resourcePath,
+        sourceRoot: options.sourceRoot,
         controlChannel: options.controlChannel,
         runtimeIntegrity: options.runtimeIntegrity,
+        inputSourceMap: inputMap(sourceMap),
     });
     if (result.kind === 'unchanged')
         return null;
@@ -68,9 +97,15 @@ async function instrument(context, source, options) {
     // ships unchanged and adds nothing to the manifest.
     if (result.sites.length === 0)
         return null;
-    const record = { sourcePath, probes: result.probes, sites: result.sites };
+    const record = {
+        sourcePath,
+        probes: result.probes,
+        sites: result.sites,
+        typed: result.typed,
+        settings: result.settings,
+    };
     writeSessionRecord(context, options, MODULES_DIRECTORY, sourcePath, source, record);
-    return result.code;
+    return { code: result.code, map: result.map };
 }
 function writeSessionRecord(context, options, directoryName, sourcePath, source, record) {
     // The record must be written by every build that ships this module, so a
@@ -86,8 +121,30 @@ function writeSessionRecord(context, options, directoryName, sourcePath, source,
     (0, node_fs_1.writeFileSync)(temporary, JSON.stringify(record));
     (0, node_fs_1.renameSync)(temporary, (0, node_path_1.join)(directory, `${name}.json`));
 }
+function load(context, source, sourceMap) {
+    const callback = context.async();
+    let options;
+    try {
+        options = context.getOptions();
+    }
+    catch {
+        callback(null, source, sourceMap);
+        return;
+    }
+    instrument(context, source, sourceMap, options).then(result => result === null ? callback(null, source, sourceMap) : callback(null, result.code, result.map ?? undefined), (error) => {
+        // Ours failed (git, the transform, the session directory): the module ships exactly as it came.
+        try {
+            const sourcePath = (0, node_path_1.relative)(options.sourceRoot, context.resourcePath).split(node_path_1.sep).join('/');
+            const reason = String(error instanceof Error ? error.message : error).split('\n')[0].slice(0, 300);
+            writeSessionRecord(context, options, UNPARSED_DIRECTORY, sourcePath, source, { sourcePath, reason });
+        }
+        catch {
+            // The report is best effort; the build is not.
+        }
+        callback(null, source, sourceMap);
+    });
+}
 function haystackTelemetryNextLoader(source, sourceMap) {
-    const callback = this.async();
-    instrument(this, source, this.getOptions()).then(code => code === null ? callback(null, source, sourceMap) : callback(null, code), (error) => callback(error instanceof Error ? error : new Error(String(error))));
+    load(this, source, sourceMap);
 }
 module.exports = haystackTelemetryNextLoader;

package/dist/telemetry/next.d.ts

@@ -1,8 +1,13 @@
-import { type FileProbeCounts, type InstrumentedSite } from '../commands/telemetry.js';
+import { type BundledSettingsRecord, type BundledSourceIdentity, type FileProbeCounts, type InstrumentedSite } from '../commands/telemetry.js';
 /** Options the config hands every loader invocation; JSON for Turbopack. */
 export interface NextTelemetryLoaderOptions {
-    /** Repository root (git top level); every site path is relative to it. */
+    /** Repository root (git top level); every site path is relative to it. Without git: the Next project. */
     sourceRoot: string;
+    /** Instrument only git-tracked files (false in a build without git: every non-node_modules source under sourceRoot). */
+    tracked: boolean;
+    sourceIdentity: BundledSourceIdentity;
+    /** The Next project (where next.config is): its middleware is never instrumented. */
+    projectDirectory: string;
     /** This build's hand-off directory between loaders and the post-compile step. */
     sessionDirectory: string;
     controlChannel: string;
@@ -13,8 +18,11 @@ export interface NextTelemetryModuleRecord {
     sourcePath: string;
     probes: FileProbeCounts;
     sites: InstrumentedSite[];
+    /** Rule 9(b)/(c): read with its types (declared fields, setting literals); false: shape-only. */
+    typed: boolean;
+    settings: BundledSettingsRecord;
 }
-/** A server module shipped uninstrumented because Babel could not parse it. */
+/** A server module shipped uninstrumented because Babel could not parse it or the transform failed. */
 export interface NextTelemetryUnparsedRecord {
     sourcePath: string;
     reason: string;