@haystackeditor/cli 0.24.1 → 0.25.1

package/dist/capture/route-pattern.js

@@ -0,0 +1,119 @@
+/** FIXED CONTRACT — mirror of infra/lambda/haystack-design-verifier-shared/capture_route_pattern.ts for the published
+ * CLI, whose build cannot import repository files outside src. Everything below this comment is that file as it is;
+ * the source file wins. */
+const NAME = /^[A-Za-z0-9_]+$/;
+/** A parameter name as the pattern syntax spells it: the framework's own name where it is a plain word. */
+export function paramName(raw) {
+    const cleaned = raw.replace(/[^A-Za-z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
+    return cleaned === '' ? 'param' : cleaned;
+}
+export function formatPattern(pattern) {
+    const body = pattern.segments.map(segment => {
+        if (segment.kind === 'literal')
+            return segment.value;
+        return `${segment.kind === 'param' ? ':' : '*'}${segment.name}${segment.optional ? '?' : ''}`;
+    }).join('/');
+    return `${pattern.hash ? '#' : ''}/${body}`;
+}
+/** The match rule for these segments, with why it is not exact when it is not (route-pattern's syntax above). */
+export function ruleFor(segments, hash = false) {
+    const widened = segments.find(segment => segment.kind !== 'literal' && segment.inexact !== undefined);
+    const splat = segments.findIndex(segment => segment.kind === 'splat');
+    const inexact = widened && widened.kind !== 'literal' ? widened.inexact
+        : splat !== -1 && splat !== segments.length - 1 ? 'a catch-all segment before its end' : null;
+    return { match: formatPattern({ hash, segments }), inexact };
+}
+/** Parses a match rule; throws on anything outside the syntax above (an adapter bug, never the customer's input). */
+export function parsePattern(match) {
+    const hash = match.startsWith('#');
+    const path = hash ? match.slice(1) : match;
+    if (!path.startsWith('/'))
+        throw new Error(`Route pattern ${match} does not start with / or #/.`);
+    const parts = path === '/' ? [] : path.slice(1).split('/');
+    const segments = parts.map((part, index) => {
+        if (part === '')
+            throw new Error(`Route pattern ${match} has an empty segment.`);
+        const sigil = part[0];
+        if (sigil !== ':' && sigil !== '*')
+            return { kind: 'literal', value: part };
+        const optional = part.endsWith('?');
+        const name = part.slice(1, optional ? -1 : undefined);
+        if (!NAME.test(name))
+            throw new Error(`Route pattern ${match} has a parameter without a plain name.`);
+        if (sigil === '*' && index !== parts.length - 1)
+            throw new Error(`Route pattern ${match} has a splat before its end.`);
+        return sigil === ':' ? { kind: 'param', name, optional } : { kind: 'splat', name, optional };
+    });
+    return { hash, segments };
+}
+const END = 5;
+function rank(segment) {
+    if (segment === undefined)
+        return END;
+    if (segment.kind === 'literal')
+        return 4;
+    if (segment.kind === 'param')
+        return segment.optional ? 2 : 3;
+    return segment.optional ? 0 : 1;
+}
+/** Most specific first: pathname patterns before hash patterns, then segment by segment literal > end of pattern is
+ * not a factor between disjoint lengths > param > optional param > splat > optional splat; ties by rule text. */
+export function compareRoutePatterns(a, b) {
+    const pa = parsePattern(a);
+    const pb = parsePattern(b);
+    if (pa.hash !== pb.hash)
+        return pa.hash ? 1 : -1;
+    const length = Math.max(pa.segments.length, pb.segments.length);
+    for (let index = 0; index < length; index += 1) {
+        const difference = rank(pb.segments[index]) - rank(pa.segments[index]);
+        if (difference !== 0)
+            return difference;
+    }
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** parsePattern, answering null where it throws: a rule outside the syntax. */
+function patternOrNull(match) {
+    try {
+        return parsePattern(match);
+    }
+    catch {
+        return null;
+    }
+}
+function decodedSegments(path) {
+    const trimmed = path.replace(/\/+$/, '');
+    if (trimmed === '')
+        return [];
+    try {
+        return trimmed.slice(1).split('/').map(part => decodeURIComponent(part));
+    }
+    catch {
+        return null;
+    }
+}
+function matchFrom(segments, parts, si, pi) {
+    if (si === segments.length)
+        return pi === parts.length;
+    const segment = segments[si];
+    if (segment.kind === 'splat')
+        return parts.length - pi >= (segment.optional ? 0 : 1);
+    if (segment.kind === 'param' && segment.optional && matchFrom(segments, parts, si + 1, pi))
+        return true;
+    if (pi === parts.length)
+        return false;
+    if (segment.kind === 'literal' ? parts[pi] !== segment.value : parts[pi] === '')
+        return false;
+    return matchFrom(segments, parts, si + 1, pi + 1);
+}
+/** The reference matcher the browser tag implements: does `match` match this location? A rule outside the syntax matches
+ * nothing. */
+export function matchRoutePattern(match, location) {
+    const pattern = patternOrNull(match);
+    if (pattern === null)
+        return false;
+    const raw = pattern.hash ? location.hash.replace(/^#/, '').split(/[?]/)[0] : location.pathname;
+    if (!raw.startsWith('/'))
+        return false;
+    const parts = decodedSegments(raw);
+    return parts !== null && matchFrom(pattern.segments, parts, 0, 0);
+}

package/dist/capture/script-release.js

@@ -0,0 +1,47 @@
+/**
+ * The capture script this CLI version installs (CAPTURE-V1 rule 1).
+ *
+ * Release step, one command: `pnpm run release:cli` in packages/haystack-capture writes the built tag into
+ * src/assets/capture/ as `capture.<hash>.js` and `release.json` ({ file, integrity }); the CLI build copies src/assets to
+ * dist/assets. Init copies the file byte for byte into the app's static output and pins it with that integrity, so a
+ * release whose file does not have that digest is refused rather than installed (a mismatched integrity would make every
+ * browser refuse the script).
+ *
+ * No release.json: this CLI version carries no capture script, and init reports capture as unsupported.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { gzipSync } from 'node:zlib';
+import { CAPTURE_SCRIPT_MAX_BYTES } from '../commands/capture-contract.js';
+const FILE_NAME = /^capture\.[0-9a-z]{6,64}\.js$/;
+const INTEGRITY = /^sha384-[A-Za-z0-9+/]{64}$/;
+export function sha384Integrity(bytes) {
+    return `sha384-${createHash('sha384').update(bytes).digest('base64')}`;
+}
+/** The released script, verified against its integrity and the contract's size cap; null when this CLI version carries
+ * none. Throws when the release is inconsistent (a packaging bug, never the customer's problem). */
+export function loadCaptureScript() {
+    // dist/capture/script-release.js → dist/assets/capture/
+    const assets = join(dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'capture');
+    const releaseFile = join(assets, 'release.json');
+    if (!existsSync(releaseFile))
+        return null;
+    const release = JSON.parse(readFileSync(releaseFile, 'utf8'));
+    if (typeof release.file !== 'string' || !FILE_NAME.test(release.file) || typeof release.integrity !== 'string' || !INTEGRITY.test(release.integrity)) {
+        throw new Error(`This CLI's capture release.json does not name a capture.<hash>.js and its sha384 integrity; reinstall @haystackeditor/cli.`);
+    }
+    const bytes = readFileSync(join(assets, release.file));
+    if (sha384Integrity(bytes) !== release.integrity) {
+        throw new Error(`This CLI's capture script ${release.file} does not match its integrity; reinstall @haystackeditor/cli.`);
+    }
+    // Measured as the tag's build measures it (packages/haystack-capture/scripts/build.ts: gzip level 9).
+    if (gzipSync(bytes, { level: 9 }).length > CAPTURE_SCRIPT_MAX_BYTES) {
+        throw new Error(`This CLI's capture script ${release.file} is over ${CAPTURE_SCRIPT_MAX_BYTES} bytes gzipped (CAPTURE-V1 rule 1).`);
+    }
+    const text = bytes.toString('utf8');
+    if (!Buffer.from(text, 'utf8').equals(bytes))
+        throw new Error(`This CLI's capture script ${release.file} is not UTF-8 text.`);
+    return { file: release.file, integrity: release.integrity, text, bytes: bytes.length };
+}

package/dist/capture/tag.js

@@ -0,0 +1,74 @@
+/**
+ * The tags init writes (CAPTURE-V1 rule 1), in each form a framework takes them, and how init recognizes its own tags on
+ * a rerun (by their /_haystack/ path, Haystack's own namespace in the app's static output), so a rerun or a newer script
+ * version replaces them instead of adding more.
+ */
+/** Where the files live in the app's static output; every adapter publishes at the origin root (rule 4 Publishing). */
+export const STATIC_SUBDIR = '_haystack';
+export function staticPath(file) {
+    return `/${STATIC_SUBDIR}/${file}`;
+}
+/** The tag's attributes in order (src first), for every renderer. */
+export function captureAttributes(tags) {
+    return [
+        ['src', staticPath(tags.script.file)],
+        ['integrity', tags.script.integrity],
+        ['data-key', tags.key],
+        ...(tags.consentNotRequired ? [['data-consent', 'not-required']] : []),
+    ];
+}
+export function consentAttributes(consent) {
+    return [['src', staticPath(consent.file)], ['integrity', consent.integrity]];
+}
+function escapeAttribute(value) {
+    return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+function htmlScript(attributes, src) {
+    const rendered = attributes.map(([name, value]) => name === 'src' && src !== undefined ? `src="${src}"` : `${name}="${escapeAttribute(value)}"`);
+    return `<script ${rendered.join(' ')} async></script>`;
+}
+/** Plain HTML (index.html, app.html, Rails layouts). */
+export function htmlTags(tags) {
+    return [htmlScript(captureAttributes(tags)), ...(tags.consent ? [htmlScript(consentAttributes(tags.consent))] : [])];
+}
+/** Django templates: the file is served through the staticfiles app, so its URL comes from {% static %}. */
+export function djangoTags(tags) {
+    const src = (file) => `{% static '${STATIC_SUBDIR}/${file}' %}`;
+    return [htmlScript(captureAttributes(tags), src(tags.script.file)),
+        ...(tags.consent ? [htmlScript(consentAttributes(tags.consent), src(tags.consent.file))] : [])];
+}
+function jsxAttributes(attributes) {
+    return attributes.map(([name, value]) => `${name}=${JSON.stringify(value)}`).join(' ');
+}
+/** Next.js: its Script component with strategy="lazyOnload" runs the script after the page's load event (rule 1). */
+export function nextScriptTags(tags, component) {
+    return [`<${component} ${jsxAttributes(captureAttributes(tags))} strategy="lazyOnload" />`,
+        ...(tags.consent ? [`<${component} ${jsxAttributes(consentAttributes(tags.consent))} strategy="lazyOnload" />`] : [])];
+}
+/** JSX documents rendered by React (React Router / Remix root): a plain async script element. */
+export function jsxScriptTags(tags) {
+    return [`<script ${jsxAttributes(captureAttributes(tags))} async />`,
+        ...(tags.consent ? [`<script ${jsxAttributes(consentAttributes(tags.consent))} async />`] : [])];
+}
+/** Nuxt `app.head.script` entries. */
+export function nuxtScriptEntries(tags) {
+    const entry = (attributes) => `{ ${attributes.map(([name, value]) => `${/^[a-z]+$/.test(name) ? name : `'${name}'`}: '${value}'`).join(', ')}, async: true }`;
+    return [entry(captureAttributes(tags)), ...(tags.consent ? [entry(consentAttributes(tags.consent))] : [])];
+}
+/** Is this script source one of init's own files? 'capture' for the tag (self-hosted, or the hosted copy on
+ * c.haystack.sh), 'consent' for a consent integration, else null. */
+export function ourScriptKind(src) {
+    const staticTemplate = /^\{%\s*static\s+['"]([^'"]+)['"]\s*%\}$/.exec(src.trim());
+    const path = staticTemplate ? `/${staticTemplate[1]}` : src;
+    if (path.startsWith('https://c.haystack.sh/') && path.endsWith('.js'))
+        return 'capture';
+    const index = path.lastIndexOf(`/${STATIC_SUBDIR}/`);
+    if (index === -1)
+        return null;
+    const file = path.slice(index + STATIC_SUBDIR.length + 2);
+    if (/^capture\.[0-9a-z]+\.js$/.test(file))
+        return 'capture';
+    if (/^consent-[a-z]+\.[0-9a-f]+\.js$/.test(file))
+        return 'consent';
+    return null;
+}

package/dist/capture/url-rewrites.js

@@ -0,0 +1,232 @@
+/**
+ * URL rewrites (CAPTURE-V1 rule 4). The tag matches a page's URL against the manifest's routes, so a route's rule must say
+ * which URLs show it. A middleware or proxy that rewrites (Rallly's proxy turns every /x into /<locale>/x) or a config
+ * rewrite into a page makes the URL and the route's path differ in ways only the app's code says. Init reads that code
+ * only where it can read it exactly (a middleware that rewrites nothing and calls nothing it cannot see into, or
+ * next-intl's middleware with a literal routing config); for anything else it never guesses: it asks the coding agent's
+ * user (who can read that code) for one answer, recorded in .haystack/capture.json:
+ *
+ *   none                     rewrites never make a page's URL show another page
+ *   hidden-segment:<name>    the middleware or proxy adds the leading dynamic segment [<name>] to every page path, so
+ *                            URLs never contain it (the manifest drops that segment from the routes under it)
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { keyName, literalValue, parseFile, pathOf, readPathAliases, resolveImport, unwrapTs, UNREADABLE, walk } from './js-ast.js';
+import { isFile } from './adapters/files.js';
+import { repoPath, resolveVersion } from './project.js';
+export function parseUrlRewrites(raw) {
+    const value = raw.trim();
+    if (value === 'none')
+        return { kind: 'none' };
+    const hidden = /^hidden-segment:([A-Za-z0-9_-]+)$/.exec(value);
+    if (hidden)
+        return { kind: 'hidden-segment', name: hidden[1] };
+    throw new Error(`--url-rewrites ${raw} is not an answer: use none, or hidden-segment:<name> for a leading [<name>] segment the app's middleware or proxy adds to every page path.`);
+}
+export const URL_REWRITES_QUESTION = 'Does it make a page\'s URL show another page? Ask your user (or read that code), then run `haystack init` again with'
+    + ' `--url-rewrites none` when its rewrites never do, or `--url-rewrites hidden-segment:<name>` when it adds a leading [<name>] segment to every'
+    + ' page path (so URLs never contain it).';
+const MIDDLEWARE_FILES = ['middleware', 'proxy'].flatMap(name => ['ts', 'js', 'mjs', 'mts', 'cts', 'cjs', 'tsx', 'jsx'].map(extension => `${name}.${extension}`));
+const INTL_MIDDLEWARE = 'next-intl/middleware';
+const INTL_ROUTING = 'next-intl/routing';
+/** next/server and the rest of Next's own modules: what they return init knows (NextResponse.rewrite is caught by name). */
+function nextModule(source) {
+    return source === 'next' || source.startsWith('next/');
+}
+/** The identifier a call's callee starts from (`a.b.c()` → a), or null (a call on a call's result, `(…)()`). */
+function calleeRoot(callee) {
+    let current = unwrapTs(callee);
+    while (current.type === 'MemberExpression' || current.type === 'OptionalMemberExpression')
+        current = unwrapTs(current.object);
+    return current.type === 'Identifier' ? current : null;
+}
+/** The value a routing config names: an object literal, a top-level const bound to one or to defineRouting({...}), or
+ * the same exported from a local module; null when it is not literally there. */
+function routingObject(node, ast, file, ctx, depth = 0) {
+    const current = unwrapTs(node);
+    if (depth > 4)
+        return null;
+    if (current.type === 'ObjectExpression')
+        return { value: current, ast };
+    if (current.type === 'CallExpression' && current.arguments.length === 1) {
+        const root = calleeRoot(current.callee);
+        const source = root ? importOf(ast, root.name) : null;
+        if (source?.module === INTL_ROUTING && source.imported === 'defineRouting')
+            return routingObject(current.arguments[0], ast, file, ctx, depth + 1);
+        return null;
+    }
+    if (current.type !== 'Identifier')
+        return null;
+    for (const statement of ast.program.body) {
+        const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : statement;
+        if (declaration?.type !== 'VariableDeclaration')
+            continue;
+        for (const declarator of declaration.declarations) {
+            if (declarator.id.type === 'Identifier' && declarator.id.name === current.name && declarator.init) {
+                return routingObject(declarator.init, ast, file, ctx, depth + 1);
+            }
+        }
+    }
+    const imported = importOf(ast, current.name);
+    if (!imported)
+        return null;
+    const target = resolveImport(file, imported.module, readPathAliases(ctx.appDir));
+    if (!target)
+        return null;
+    const targetAst = parseFile(readFileSync(target, 'utf8'), target);
+    if (!targetAst)
+        return null;
+    const exported = exportedExpression(targetAst, imported.imported);
+    return exported ? routingObject(exported, targetAst, target, ctx, depth + 1) : null;
+}
+function importOf(ast, local) {
+    for (const statement of ast.program.body) {
+        if (statement.type !== 'ImportDeclaration')
+            continue;
+        for (const specifier of statement.specifiers) {
+            if (specifier.local.name !== local)
+                continue;
+            const imported = specifier.type === 'ImportDefaultSpecifier' ? 'default'
+                : specifier.type === 'ImportNamespaceSpecifier' ? '*' : specifier.imported.name ?? specifier.imported.value;
+            return { module: statement.source.value, imported };
+        }
+    }
+    return null;
+}
+/** The expression a module exports under `name` ('default' for its default export), or null. */
+function exportedExpression(ast, name) {
+    for (const statement of ast.program.body) {
+        if (name === 'default' && statement.type === 'ExportDefaultDeclaration')
+            return statement.declaration;
+        if (statement.type !== 'ExportNamedDeclaration' || statement.source)
+            continue;
+        for (const declarator of statement.declaration?.type === 'VariableDeclaration' ? statement.declaration.declarations : []) {
+            if (declarator.id.type === 'Identifier' && declarator.id.name === name)
+                return declarator.init;
+        }
+        for (const specifier of statement.specifiers ?? []) {
+            if ((specifier.exported?.name ?? specifier.exported?.value) === name)
+                return specifier.local;
+        }
+    }
+    return null;
+}
+/** next-intl's routing, read exactly, or why it cannot be. */
+function intlRouting(config, ast, file, ctx, where) {
+    const unknown = (why) => ({ kind: 'unknown', why: `${where} uses next-intl's middleware, ${why}` });
+    const found = config ? routingObject(config, ast, file, ctx) : null;
+    if (!found)
+        return unknown('whose routing config init cannot read literally');
+    const value = literalValue(found.value, found.ast);
+    if (value === UNREADABLE || typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return unknown('whose routing config is not literal');
+    }
+    const routing = value;
+    if (routing.pathnames !== undefined)
+        return unknown('whose localized pathnames make a URL show a page under another path');
+    if (routing.domains !== undefined)
+        return unknown('whose domains decide the locale by host');
+    const locales = Array.isArray(routing.locales) && routing.locales.every(locale => typeof locale === 'string') ? routing.locales : null;
+    const defaultLocale = typeof routing.defaultLocale === 'string' ? routing.defaultLocale : null;
+    if (!locales || !defaultLocale)
+        return unknown('whose locales or defaultLocale are not a literal list and string');
+    let mode;
+    let prefixes = {};
+    const prefix = routing.localePrefix;
+    if (prefix === undefined) {
+        // next-intl 3 made `always` the default; 2 had `as-needed`.
+        const version = resolveVersion(ctx, 'next-intl');
+        if (!version || version.major === null)
+            return unknown('whose default localePrefix depends on a next-intl version init cannot resolve');
+        mode = version.major >= 3 ? 'always' : 'as-needed';
+    }
+    else if (typeof prefix === 'string') {
+        mode = prefix;
+    }
+    else if (prefix && typeof prefix === 'object' && !Array.isArray(prefix)) {
+        mode = prefix.mode;
+        if (prefix.prefixes !== undefined) {
+            const given = prefix.prefixes;
+            if (!given || typeof given !== 'object' || Array.isArray(given) || !Object.values(given).every(item => typeof item === 'string' && item.startsWith('/'))) {
+                return unknown('whose localePrefix.prefixes are not literal paths');
+            }
+            prefixes = given;
+        }
+    }
+    if (mode !== 'always' && mode !== 'as-needed' && mode !== 'never')
+        return unknown(`whose localePrefix mode (${JSON.stringify(mode)}) init does not know`);
+    return { kind: 'locale-prefix', where, mode, locales, defaultLocale, prefixes };
+}
+/** One middleware or proxy file, read. */
+function readMiddleware(ctx, file) {
+    const where = repoPath(ctx, file);
+    const ast = parseFile(readFileSync(file, 'utf8'), file);
+    if (!ast)
+        return { kind: 'unknown', why: `${where} (which init cannot parse)` };
+    const program = pathOf(ast, ast.program);
+    if (!program)
+        return { kind: 'unknown', why: `${where} (whose names init cannot resolve)` };
+    const reasons = [];
+    walk(ast.program, node => {
+        if (node.type === 'ExportAllDeclaration' || (node.type === 'ExportNamedDeclaration' && node.source)) {
+            reasons.push(`re-exports from ${node.source.value}`);
+        }
+        if (node.type === 'StringLiteral' && node.value.toLowerCase() === 'x-middleware-rewrite')
+            reasons.push('sets the x-middleware-rewrite header');
+        if ((node.type === 'CallExpression' || node.type === 'OptionalCallExpression') && node.callee.type === 'MemberExpression' && !node.callee.computed
+            && node.callee.property.name === 'rewrite')
+            reasons.push('calls rewrite()');
+        if (node.type === 'ObjectProperty' && keyName(node) === 'rewrite')
+            reasons.push('passes a rewrite');
+        if (node.type === 'ImportExpression' || (node.type === 'CallExpression' && (node.callee.type === 'Import'
+            || (node.callee.type === 'Identifier' && node.callee.name === 'require'))))
+            reasons.push('loads a module at runtime');
+    });
+    // Every value imported from outside Next is code init cannot see into, wherever it is used (called, passed to a local
+    // helper that calls it, exported as the middleware), except next-intl's createMiddleware and the routing it is given,
+    // which init reads.
+    const intlCalls = [];
+    for (const [local, binding] of Object.entries(program.scope.bindings)) {
+        const declaration = binding.path.parentPath?.node;
+        if (binding.kind !== 'module' || declaration?.type !== 'ImportDeclaration' || declaration.importKind === 'type'
+            || binding.path.node.importKind === 'type' || nextModule(declaration.source.value))
+            continue;
+        const factory = declaration.source.value === INTL_MIDDLEWARE && binding.path.node.type === 'ImportDefaultSpecifier';
+        for (const reference of binding.referencePaths) {
+            const parent = reference.parentPath?.node;
+            if (factory && parent?.type === 'CallExpression' && parent.callee === reference.node) {
+                intlCalls.push(parent);
+                continue;
+            }
+            const factoryArgument = parent?.type === 'CallExpression' && parent.arguments[0] === reference.node && parent.callee.type === 'Identifier'
+                && program.scope.getBinding(parent.callee.name)?.path.parentPath?.node.source?.value === INTL_MIDDLEWARE;
+            if (factoryArgument)
+                continue;
+            reasons.push(`uses ${local} from ${declaration.source.value}`);
+            break;
+        }
+    }
+    if (reasons.length > 0)
+        return { kind: 'unknown', why: `${where}, which ${reasons[0]} (init cannot read what that does to page paths)` };
+    if (intlCalls.length === 0)
+        return { kind: 'none' };
+    // next-intl: every createMiddleware call must read as the same routing.
+    const readings = intlCalls.map(call => intlRouting(call.arguments[0], ast, file, ctx, where));
+    const first = readings[0];
+    if (first.kind !== 'locale-prefix')
+        return first;
+    return readings.every(reading => JSON.stringify(reading) === JSON.stringify(first)) ? first
+        : { kind: 'unknown', why: `${where}, which calls next-intl's createMiddleware with several routing configs` };
+}
+/** What the app's middleware or proxy does to page paths (the first one found, as Next loads one). Needs loadBabel(). */
+export function middlewareRewrites(ctx) {
+    for (const dir of [ctx.appDir, join(ctx.appDir, 'src')]) {
+        for (const name of MIDDLEWARE_FILES) {
+            const file = join(dir, name);
+            if (isFile(file))
+                return readMiddleware(ctx, file);
+        }
+    }
+    return { kind: 'none' };
+}

package/dist/capture-step.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * `haystack-capture-step`: the build step `haystack init` joins to an app's build script (CAPTURE-V1 rules 4, 13). It runs
+ * `haystack capture manifest --app . --json` (plus any arguments given) in a child process and always exits 0: whatever
+ * happens to the manifest, the CLI failing to load or start included, the customer's build goes on.
+ *
+ * Unless the command reports a manifest written, the step removes current.json from the directories
+ * .haystack/capture.json records as the app's publication locations, so the build never ships the manifest of an earlier
+ * release (rule 4 Publishing; the tag then records nothing on this one). It imports nothing but Node.js built-ins, so
+ * nothing it loads can fail.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** current.json at every recorded publication location, removed; how many were. */
+function withdrawCurrent() {
+    let removed = 0;
+    try {
+        const config = JSON.parse(readFileSync(join('.haystack', 'capture.json'), 'utf8'));
+        const dirs = Array.isArray(config.publish) ? config.publish.filter((dir) => typeof dir === 'string') : [];
+        for (const dir of dirs) {
+            const file = join(resolve(dir), '.well-known', 'haystack-capture', 'current.json');
+            try {
+                if (existsSync(file)) {
+                    unlinkSync(file);
+                    removed += 1;
+                }
+            }
+            catch { /* the next location still gets its chance */ }
+        }
+    }
+    catch { /* no readable record: nothing init published here to withdraw */ }
+    return removed;
+}
+let written = false;
+try {
+    const cli = join(dirname(fileURLToPath(import.meta.url)), 'index.js');
+    const run = spawnSync(process.execPath, [cli, 'capture', 'manifest', '--app', '.', '--json', ...process.argv.slice(2)], { stdio: ['ignore', 'pipe', 'inherit'], encoding: 'utf8' });
+    const result = JSON.parse(run.stdout);
+    written = result.written === true;
+    if (written) {
+        const files = Array.isArray(result.files) ? result.files.join(', ') : '';
+        console.log(`Haystack route manifest ${String(result.release)}: ${files}`);
+        // What the person must still do for it to be reachable (a Next.js basePath): said on every build until done.
+        for (const note of Array.isArray(result.notes) ? result.notes : [])
+            console.warn(`haystack capture manifest: ${String(note)}.`);
+    }
+}
+catch { /* the command did not answer: no manifest was written */ }
+if (!written) {
+    const removed = withdrawCurrent();
+    console.warn(`haystack capture manifest did not write a route manifest${removed > 0 ? ', so the previous current.json was removed' : ''};`
+        + ' the build goes on.');
+}
+process.exitCode = 0;

package/dist/commands/capture-brief.js

@@ -0,0 +1,92 @@
+/** CAPTURE-V1 rule 7b in `haystack pre-verify`: the routes a change touches (the brief's blast-radius files and the changed
+ * files, joined through the route manifest's source entries) with their share of captured sessions over the window, the union
+ * over all of them, freshness and drops; sessions on routes no manifest names are unmapped, never zero. The application is the
+ * one `.haystack/capture.json` names (rule 8b, written by `haystack init`); a checkout without it has no capture and the brief
+ * is exactly as before. A capture read that fails is reported in the block and never fails the command. */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { classifyHttpError } from '../utils/haystack-api.js';
+import { gatewayFetch } from './case-batch.js';
+import { CAPTURE_APPLICATION_ID, CAPTURE_WINDOW_PATH, captureChangedRoutes, } from './capture-contract.js';
+/** Rule 8b: the application identity init commits (key, repository id, application id, adapter). */
+export const CAPTURE_IDENTITY_FILE = '.haystack/capture.json';
+/** The checkout's application id, null without the identity file, or why the file cannot be read. */
+function captureApplication(gitRoot) {
+    const path = join(gitRoot, CAPTURE_IDENTITY_FILE);
+    if (!existsSync(path))
+        return null;
+    let value;
+    try {
+        value = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        return { unreadable: `${CAPTURE_IDENTITY_FILE} is not JSON (${error instanceof Error ? error.message : String(error)})` };
+    }
+    const applicationId = value?.applicationId;
+    if (typeof applicationId !== 'string' || !CAPTURE_APPLICATION_ID.test(applicationId)) {
+        return { unreadable: `${CAPTURE_IDENTITY_FILE} names no valid applicationId` };
+    }
+    return { applicationId };
+}
+/** The pre-verify capture block, or null for a checkout with no capture identity. `files`: the brief's function files and the
+ * changed files. */
+export async function readPreVerifyCapture(gitRoot, repository, token, files, now) {
+    const application = captureApplication(gitRoot);
+    if (application === null)
+        return null;
+    if ('unreadable' in application)
+        return { applicationId: null, state: 'unavailable', reason: application.unreadable };
+    const { applicationId } = application;
+    try {
+        const response = await gatewayFetch(`${CAPTURE_WINDOW_PATH}?repository=${encodeURIComponent(repository)}&app=${encodeURIComponent(applicationId)}`, token);
+        if (!response.ok)
+            throw await classifyHttpError(response, `Haystack API ${CAPTURE_WINDOW_PATH}`);
+        const answer = await response.json();
+        if (answer.version !== 'capture-v1' || answer.applicationId !== applicationId)
+            throw new Error('the capture window answer names another application');
+        if (answer.window === null)
+            return { applicationId, state: 'no-data' };
+        return { applicationId, state: 'ready', window: captureChangedRoutes(answer.window, files, now) };
+    }
+    catch (error) {
+        return { applicationId, state: 'unavailable', reason: error instanceof Error ? error.message : String(error) };
+    }
+}
+const percent = (share) => share === null ? 'n/a' : `${(share * 100).toFixed(1)}%`;
+const plain = (value) => value.replace(/[\u0000-\u001f\u007f-\u009f]/gu, ' '); // eslint-disable-line no-control-regex
+/** The block as a coding agent reads it, after the brief. */
+export function formatCapture(capture) {
+    const lines = [chalk.bold('What real users do where your change is (captured sessions)')];
+    if (capture.state === 'unavailable') {
+        lines.push(`  Captured sessions could not be read${capture.applicationId ? ` for ${plain(capture.applicationId)}` : ''}: ${plain(capture.reason)}`);
+        return lines.join('\n');
+    }
+    if (capture.state === 'no-data') {
+        lines.push(`  No captured sessions for ${plain(capture.applicationId)} yet: none arrived from its registered origins, or none consented.`);
+        return lines.join('\n');
+    }
+    const window = capture.window;
+    const days = window.days.length ? `${window.days[0]} to ${window.days.at(-1)}` : 'the window';
+    lines.push(`  ${window.sessions} captured session(s), ${days}; newest data ${window.newestHour === null ? 'none' : `${window.newestHour}:00 UTC`}`
+        + `${window.stale ? ` (stale: ${window.ageHours === null ? 'no data' : `${Math.round(window.ageHours)} hours old`})` : ''}.`);
+    if (window.routes.length === 0)
+        lines.push('  None of the files this change touches defines a route captured sessions reached.');
+    for (const route of window.routes) {
+        lines.push(`  ${plain(route.match)} (${plain(route.source)}): ${percent(route.share)} of captured sessions (${route.sessions})`);
+    }
+    if (window.routes.length > 1)
+        lines.push(`  Together: ${percent(window.union.share)} of captured sessions (${window.union.sessions}) visited at least one of them.`);
+    if (window.unmapped !== null) {
+        lines.push(`  Unmapped: ${percent(window.unmapped.share)} of sessions (${window.unmapped.sessions}) were on pages no route names; whether they`
+            + ' reach this change is unknown, not zero.');
+    }
+    if (window.releasesWithoutManifest.length) {
+        lines.push(`  Releases whose route list Haystack does not hold (their pages are unmapped): ${window.releasesWithoutManifest.map(plain).join(', ')}`);
+    }
+    const dropped = Object.entries(window.dropped).filter(([, count]) => count > 0);
+    if (dropped.length)
+        lines.push(`  Events dropped at ingest: ${dropped.map(([reason, count]) => `${plain(reason)} ${count}`).join(', ')}.`);
+    lines.push('  Shares are of captured (consenting) sessions only; how many visitors did not consent is unknowable and not claimed.');
+    return lines.join('\n');
+}