@haystackeditor/cli 0.24.1 → 0.25.0

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-step.js

@@ -0,0 +1,53 @@
+#!/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}`);
+    }
+}
+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');
+}

package/dist/commands/capture-contract.js

@@ -0,0 +1,46 @@
+/** FIXED CONTRACT — mirror of CAPTURE-V1 (infra/lambda/haystack-design-verifier-shared/capture_contracts.ts, rule 7's
+ * capture_rollup_contracts.ts, and the server-telemetry routes of telemetry_token_contracts.ts) for the published CLI, whose
+ * build cannot import repository files outside src. Only the shapes the CLI reads or sends are mirrored, and
+ * captureChangedRoutes is the source's own join; the source files win. */
+export const CAPTURE_VERSION = 'capture-v1';
+export const CAPTURE_KEY_PATTERN = /^hc_[a-z2-7]{26}$/;
+export const CAPTURE_ORIGIN = 'https://c.haystack.sh';
+export const CAPTURE_SCRIPT_MAX_BYTES = 8 * 1024;
+/** The longest a route id may be, in characters. */
+export const CAPTURE_ROUTE_ID_MAX = 200;
+/** Rule 4 Publishing: the largest route manifest (current.json and <release>.json), in bytes. */
+export const CAPTURE_MANIFEST_MAX_BYTES = 256 * 1024;
+export const CAPTURE_WINDOW_PATH = '/api/agent/cloud-verifier/capture/window';
+/** Rule 8(e): telemetry older than this is reported stale; rule 7b: a capture window older than this is stale. */
+export const CAPTURE_EVIDENCE_FRESH_HOURS = 24;
+export const CAPTURE_ROUTE_UNKNOWN = 'unknown';
+export const CAPTURE_APPLICATION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/u;
+const share = (part, whole) => whole > 0 ? part / whole : null;
+/** Rule 7b: the window's routes whose source entry is one of `files` (repository paths, compared exactly). */
+export function captureChangedRoutes(window, files, now) {
+    const wanted = new Set(files);
+    const index = new Map(window.routes.map((row, at) => [row.route, at]));
+    const mapped = window.manifest.routes.filter(route => wanted.has(route.source));
+    const routes = mapped.map(route => {
+        const row = window.routes[index.get(route.id) ?? -1];
+        const sessions = row?.sessions ?? 0;
+        return { route: route.id, match: route.match, source: route.source, sessions, share: share(sessions, window.sessions) };
+    }).sort((left, right) => right.sessions - left.sessions || left.route.localeCompare(right.route));
+    const changed = new Set(mapped.flatMap(route => index.has(route.id) ? [index.get(route.id)] : []));
+    const union = window.routeSets.reduce((sum, set) => set.routes.some(at => changed.has(at)) ? sum + set.sessions : sum, 0);
+    const unknown = window.routes[index.get(CAPTURE_ROUTE_UNKNOWN) ?? -1];
+    const ageHours = window.newestHour === null ? null
+        : Math.max(0, (now.getTime() - (Date.parse(`${window.newestHour}:00:00Z`) + 3_600_000)) / 3_600_000);
+    return { applicationId: window.applicationId, days: window.days, newestHour: window.newestHour, ageHours,
+        stale: ageHours === null || ageHours > CAPTURE_EVIDENCE_FRESH_HOURS, sessions: window.sessions, routes,
+        union: { sessions: union, share: share(union, window.sessions) },
+        unmapped: unknown ? { sessions: unknown.sessions, share: share(unknown.sessions, window.sessions) } : null,
+        releasesWithoutManifest: window.manifest.missing, dropped: window.dropped };
+}
+export const TELEMETRY_TOKEN_VERSION = 'telemetry-token-v1';
+export const TELEMETRY_ENVIRONMENT = 'production';
+export const TELEMETRY_TOKEN_PATH = '/api/agent/cloud-verifier/telemetry/token';
+export const TELEMETRY_SERVER_STATUS_PATH = '/api/agent/cloud-verifier/telemetry/server';
+export const TELEMETRY_TOKEN_SHA256 = /^[0-9a-f]{64}$/;
+/** Lane A's capture status: GET /api/agent/cloud-verifier/capture/status?repository=&app= (rule 8b's key registration). */
+export const CAPTURE_STATUS_PATH = '/api/agent/cloud-verifier/capture/status';

package/dist/commands/capture-manifest.js

@@ -0,0 +1,78 @@
+/**
+ * `haystack capture manifest` — the build step init adds (CAPTURE-V1 rule 4 Publishing): reads the app's identity from
+ * .haystack/capture.json, lists its routes and its build's chunks through the same framework adapter init chose, and
+ * writes the route manifest into the app's own static output as /.well-known/haystack-capture/<release>.json and
+ * current.json. No credential is involved: whoever deploys the app publishes its manifest.
+ *
+ * It runs inside the customer's build (the package script init extends, or the Rails rake file), from the CLI the app pins
+ * as an exact devDependency. It never fails that build (rule 13): whatever goes wrong, it prints one warning line and exits
+ * 0, because a missing manifest only stops the tag on this release (rule 13a: no manifest, no work). It needs no git
+ * checkout: repository paths come from the app path init recorded.
+ */
+import chalk from 'chalk';
+import { relative, resolve, sep } from 'node:path';
+import { detectApp } from '../capture/adapters/index.js';
+import { isManual } from '../capture/adapters/types.js';
+import { CAPTURE_CONFIG_PATH, readCaptureConfig } from '../capture/app-config.js';
+import { loadBabel } from '../capture/js-ast.js';
+import { buildManifest, exactRoutes, withdrawCurrent, writeManifest } from '../capture/manifest.js';
+import { appContext } from '../capture/project.js';
+export async function captureManifestCommand(options) {
+    // Where this app publishes, once known: a failure withdraws the current.json there, so a build never ships the manifest
+    // of another release (pre-build publication into public/ or static/ would otherwise keep the last one).
+    const locations = [];
+    try {
+        await publish(options, locations);
+    }
+    catch (error) {
+        let withdrawn = [];
+        try {
+            withdrawn = withdrawCurrent(locations);
+        }
+        catch { /* the warning below still says no manifest was written */ }
+        const reason = (error instanceof Error ? error.message : String(error)).replace(/\s+/g, ' ').trim().replace(/\.$/, '');
+        if (options.json)
+            process.stdout.write(`${JSON.stringify({ written: false, reason, withdrawn }, null, 2)}\n`);
+        console.warn(`haystack capture manifest: no route manifest written (${reason})${withdrawn.length > 0 ? ' and the previous current.json removed' : ''};`
+            + ' the build goes on, and the capture tag records nothing on this release.');
+        process.exitCode = 0;
+    }
+}
+async function publish(options, locations) {
+    const appDir = resolve(options.app ?? '.');
+    const config = readCaptureConfig(appDir);
+    if (!config)
+        throw new Error(`${appDir} has no ${CAPTURE_CONFIG_PATH}: run \`haystack init\` in the repository to set capture up.`);
+    locations.push(...config.publish.map(dir => resolve(appDir, dir)));
+    if (config.adapter === null)
+        throw new Error(`${CAPTURE_CONFIG_PATH} names no framework adapter: init left this app's manifest to a manual step.`);
+    // The checkout's root when the app sits at its recorded path; else (a build that sees only the app) the app itself.
+    const suffix = config.app === '.' ? '' : config.app.split('/').join(sep);
+    const repoRoot = suffix !== '' && appDir.endsWith(`${sep}${suffix}`) ? appDir.slice(0, -suffix.length - 1) : appDir;
+    await loadBabel();
+    const ctx = appContext(repoRoot, appDir, config.app);
+    const detected = await detectApp(ctx);
+    if (!detected || detected.id !== config.adapter) {
+        throw new Error(`${CAPTURE_CONFIG_PATH} was written for ${config.adapter}, and this app is now ${detected?.label ?? 'no framework init recognizes'}; run \`haystack init\` again.`);
+    }
+    if (!isManual(detected.publishDirs))
+        locations.push(...detected.publishDirs.map(dir => resolve(appDir, dir)).filter(dir => !locations.includes(dir)));
+    if (detected.blocked)
+        throw new Error(`${detected.label}: ${detected.blocked}.`);
+    const routes = exactRoutes(await detected.routes({ railsRoutes: options.railsRoutes ? resolve(options.railsRoutes) : undefined }));
+    if (isManual(routes))
+        throw new Error(routes.manual);
+    if (isManual(detected.publishDirs))
+        throw new Error(detected.publishDirs.manual);
+    const manifest = buildManifest(config, detected.manifestAdapter, routes, detected.chunks());
+    const written = writeManifest(detected.publishDirs.map(dir => resolve(appDir, dir)), manifest);
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({ written: true, release: manifest.release, routes: manifest.routes.length, chunks: manifest.chunks.length,
+            files: written.map(file => relative(appDir, file)) }, null, 2)}\n`);
+        return;
+    }
+    const count = (n, noun) => `${n} ${noun}${n === 1 ? '' : 's'}`;
+    console.log(chalk.green(`Haystack route manifest ${manifest.release}: ${count(manifest.routes.length, 'route')}, ${count(manifest.chunks.length, 'chunk')} (${detected.label})`));
+    for (const file of written)
+        console.log(chalk.dim(`  ${relative(appDir, file)}`));
+}