@haystackeditor/cli 0.24.1 → 0.25.1

package/dist/capture/adapters/vite.js

@@ -0,0 +1,135 @@
+/**
+ * Vite single-page apps and static HTML sites (CAPTURE-V1 rule 8b).
+ *
+ * Vite: the tag goes into <head> of the app's one index.html (an async classic script, which Vite leaves alone because
+ * the file is in publicDir); the files go into publicDir, which Vite copies to the build output. Routes come from the
+ * app's router (React Router library mode or Vue Router, client-routes.ts); an app with no router is one page, `/`; a
+ * router init cannot read is a manual step. Chunks: the JS of build.outDir. A base other than `/`, several HTML entry
+ * points, or a library build are manual steps (the manifest is published at the origin root, and the tag needs one
+ * integration point).
+ *
+ * Static HTML: a directory served as is with exactly one HTML page (index.html) gets the tag and the files beside it, and
+ * init writes the manifest itself (one route, no build).
+ */
+import { readFileSync } from 'node:fs';
+import { join, posix } from 'node:path';
+import { withHeadTags } from '../html.js';
+import { declaredRange, repoPath, resolveVersion, toPosix, appFile } from '../project.js';
+import { htmlTags } from '../tag.js';
+import { reactRouterLibraryRoutes, vueRouterRoutes } from './client-routes.js';
+import { chunkIds, configFile, configValue, filesUnder, isDirectory, isFile } from './files.js';
+const CONFIG_NAMES = ['vite.config.ts', 'vite.config.js', 'vite.config.mjs', 'vite.config.mts', 'vite.config.cjs', 'vite.config.cts'];
+/** Routers whose routes live in generated code or conventions init does not read. */
+const UNREAD_ROUTERS = ['@tanstack/react-router', '@tanstack/router', 'wouter', 'preact-router', '@solidjs/router', 'svelte-routing',
+    'svelte-spa-router', '@reach/router', 'react-location'];
+function htmlEdit(file, tags, where) {
+    const code = readFileSync(file, 'utf8');
+    const edit = withHeadTags(code, htmlTags(tags));
+    return 'manual' in edit ? { manual: `${where}: ${edit.manual}` } : [{ target: file, content: edit.content }];
+}
+export async function detectVite(ctx) {
+    const version = resolveVersion(ctx, 'vite');
+    if (!version)
+        return null;
+    const config = configFile(ctx.appDir, CONFIG_NAMES);
+    const where = config.file ? repoPath(ctx, config.file) : appFile(ctx, 'vite.config.*');
+    // A library build is no app; a config init cannot read may or may not be one, so it is a manual step.
+    const library = configValue(config, ['build', 'lib']);
+    if (library.state === 'value')
+        return null;
+    const blocked = library.state === 'unreadable' ? [`${where} cannot be read to tell whether it builds an app or a library`] : [];
+    const readString = (path, fallback) => {
+        const value = configValue(config, path);
+        if (value.state === 'unreadable') {
+            blocked.push(`${where} sets ${path.join('.')} in a way init cannot read`);
+            return fallback;
+        }
+        if (value.state === 'value' && typeof value.value !== 'string') {
+            blocked.push(`${where} sets ${path.join('.')} to something other than a path`);
+            return fallback;
+        }
+        return value.state === 'value' ? value.value : fallback;
+    };
+    const root = readString(['root'], '.');
+    const index = join(ctx.appDir, root, 'index.html');
+    if (!isFile(index))
+        return null;
+    const base = readString(['base'], '/');
+    const publicDir = readString(['publicDir'], 'public');
+    const outDir = readString(['build', 'outDir'], 'dist');
+    if (base !== '/' && base !== '')
+        blocked.push(`${where} sets base ${base}: the route manifest must be published at the origin root, outside it`);
+    const input = configValue(config, ['build', 'rollupOptions', 'input']);
+    if (input.state === 'unreadable' || (input.state === 'value' && typeof input.value === 'object' && input.value !== null
+        && Object.keys(input.value).length > 1)) {
+        blocked.push(`${where} builds several HTML entry points (build.rollupOptions.input), each needing the tag`);
+    }
+    if (version.major === null || version.major < 2 || version.major > 8)
+        blocked.push(`init knows Vite 2–8, and this app's version is ${version.version} (${version.from})`);
+    const srcDir = isDirectory(join(ctx.appDir, root, 'src')) ? join(ctx.appDir, root, 'src') : join(ctx.appDir, root);
+    const reactRouter = declaredRange(ctx.pkg, 'react-router-dom') !== null || declaredRange(ctx.pkg, 'react-router') !== null;
+    const vueRouter = declaredRange(ctx.pkg, 'vue-router') !== null;
+    const unread = UNREAD_ROUTERS.filter(name => declaredRange(ctx.pkg, name) !== null);
+    const router = reactRouter ? 'React Router' : vueRouter ? 'Vue Router' : unread[0] ?? null;
+    const indexPath = repoPath(ctx, index);
+    const outPath = toPosix(posix.join(toPosix(root), toPosix(outDir)));
+    const scripts = ctx.pkg?.scripts ?? {};
+    return {
+        id: 'vite',
+        label: `Vite ${version.version}${router ? ` with ${router}` : ''}`,
+        manifestAdapter: `vite@${version.version}`,
+        blocked: blocked.length > 0 ? blocked.join('; ') : null,
+        // The routes come from the source, so whatever stops init placing the tag stops the manifest too.
+        manifestBlocked: blocked.length > 0 ? blocked.join('; ') : null,
+        fromBuild: false,
+        rewriting: null,
+        publishNote: null,
+        buildPublishDirs: () => [],
+        buildNotes: () => [],
+        looked: [indexPath, where, repoPath(ctx, srcDir)],
+        staticDir: toPosix(posix.join(toPosix(root), toPosix(publicDir))),
+        integrate: async (tags) => htmlEdit(index, tags, indexPath),
+        manualTag: tags => [`In ${indexPath}, inside <head>:`, ...htmlTags(tags)],
+        build: typeof scripts.build === 'string' ? { kind: 'package-script', script: 'build', phase: 'after' }
+            : { manual: `${appFile(ctx, 'package.json')} has no build script to publish the route manifest after` },
+        async routes() {
+            if (unread.length > 0 && !reactRouter && !vueRouter)
+                return { manual: `the app routes with ${unread.join(', ')}, whose routes init cannot read` };
+            if (reactRouter)
+                return reactRouterLibraryRoutes(ctx, srcDir);
+            if (vueRouter)
+                return vueRouterRoutes(ctx, srcDir, base === '' ? '/' : base);
+            return [{ match: '/', source: indexPath }];
+        },
+        chunks: () => chunkIds(join(ctx.appDir, root, outDir), '/').filter(id => !id.startsWith('/_haystack/')),
+        publishDirs: [outPath],
+    };
+}
+export async function detectStaticHtml(ctx) {
+    const index = join(ctx.appDir, 'index.html');
+    if (!isFile(index))
+        return null;
+    const pages = filesUnder(ctx.appDir).filter(file => file.endsWith('.html') && !file.startsWith('_haystack/'));
+    const indexPath = repoPath(ctx, index);
+    return {
+        id: 'static-html',
+        label: 'a static HTML site',
+        manifestAdapter: 'static-html',
+        blocked: pages.length === 1 ? null : `the site has ${pages.length} HTML pages (${pages.slice(0, 5).join(', ')}${pages.length > 5 ? ', …' : ''}), each needing the tag`,
+        // The routes come from the source, so whatever stops init placing the tag stops the manifest too.
+        manifestBlocked: pages.length === 1 ? null : `the site has ${pages.length} HTML pages (${pages.slice(0, 5).join(', ')}${pages.length > 5 ? ', …' : ''}), each needing the tag`,
+        fromBuild: false,
+        rewriting: null,
+        publishNote: null,
+        buildPublishDirs: () => [],
+        buildNotes: () => [],
+        looked: [indexPath],
+        staticDir: '.',
+        integrate: async (tags) => htmlEdit(index, tags, indexPath),
+        manualTag: tags => ['In every HTML page, inside <head>:', ...htmlTags(tags)],
+        build: { kind: 'init-writes' },
+        routes: async () => [{ match: '/', source: indexPath }],
+        chunks: () => [],
+        publishDirs: ['.'],
+    };
+}

package/dist/capture/app-config.js

@@ -0,0 +1,107 @@
+/**
+ * `.haystack/capture.json` in the app's directory (CAPTURE-V1 rule 8b(ii)): the application's identity, committed by
+ * init and read by the build step that publishes the route manifest. It lives beside the app's package manifest, not at
+ * the repository root, so a build that sees only the app's directory (a Docker context, a monorepo deploy) still finds
+ * it, and a repository with several apps keeps one per app.
+ *
+ * The contract names key, repository id, application id and adapter. Init also keeps:
+ *   app      the app's directory in the repository ('.' at the root), because manifest sources are repository paths and
+ *            a build often has no .git to find the root from;
+ *   origins  the production origins the user gave (public, and registered with the key), and
+ *   consent  the user's consent answer, so a rerun without flags (a newer script version) keeps both instead of asking;
+ *   publish  the directories (relative to the app) the build step publishes the manifest into, so haystack-capture-step,
+ *            which loads nothing of the CLI, can withdraw a stale current.json there when the manifest was not made.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CAPTURE_KEY_PATTERN, CAPTURE_STATUS_PATH, CAPTURE_VERSION } from '../commands/capture-contract.js';
+import { haystackFetch, haystackJson } from '../utils/haystack-api.js';
+export const CAPTURE_CONFIG_PATH = '.haystack/capture.json';
+export function captureConfigFile(appDir) {
+    return join(appDir, CAPTURE_CONFIG_PATH);
+}
+/** The committed identity, or null when init has not set capture up here. Throws on a file that is not one. */
+export function readCaptureConfig(appDir) {
+    const file = captureConfigFile(appDir);
+    if (!existsSync(file))
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`${CAPTURE_CONFIG_PATH} is not valid JSON (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    const strings = ['key', 'repositoryId', 'applicationId', 'app', 'consent'];
+    if (parsed.version !== CAPTURE_VERSION || strings.some(name => typeof parsed[name] !== 'string')
+        || !CAPTURE_KEY_PATTERN.test(parsed.key) || !(parsed.adapter === null || typeof parsed.adapter === 'string')
+        || !Array.isArray(parsed.origins) || !parsed.origins.every(origin => typeof origin === 'string')
+        || !Array.isArray(parsed.publish) || !parsed.publish.every(dir => typeof dir === 'string')
+        || !(parsed.urlRewrites === undefined || parsed.urlRewrites === null || typeof parsed.urlRewrites === 'string')) {
+        throw new Error(`${CAPTURE_CONFIG_PATH} is not a capture configuration init wrote; remove it and run \`haystack init\` again.`);
+    }
+    return parsed;
+}
+export function formatCaptureConfig(config) {
+    return `${JSON.stringify(config, null, 2)}\n`;
+}
+/** Production origins exactly as the user gave them, one per --origin (rule 8b: never inferred): https, no path, no
+ * wildcard, no local host. Throws with the reason for the first one that is not. */
+export function parseOrigins(given) {
+    const origins = given.map(origin => origin.trim()).filter(origin => origin !== '');
+    if (origins.length === 0)
+        throw new Error('--origin needs a production origin, e.g. --origin https://app.example.com.');
+    return [...new Set(origins.map(origin => {
+            let url;
+            try {
+                url = new URL(origin);
+            }
+            catch {
+                throw new Error(`--origin ${origin} is not a URL; give the production origin, e.g. https://app.example.com.`);
+            }
+            if (origin.includes('*'))
+                throw new Error(`--origin ${origin} has a wildcard; name each production origin.`);
+            if (url.protocol !== 'https:')
+                throw new Error(`--origin ${origin} is not https; production origins are https.`);
+            if (url.username || url.password || url.search || url.hash || (url.pathname !== '/' && url.pathname !== '')) {
+                throw new Error(`--origin ${origin} is not an origin (scheme and host only, no path).`);
+            }
+            const host = url.hostname;
+            if (host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local') || host === '127.0.0.1' || host === '[::1]') {
+                throw new Error(`--origin ${origin} is a local address; production origins only (CAPTURE-V1 rule 5).`);
+            }
+            return url.origin;
+        }))].sort();
+}
+/** Registers the application and its production origins (rule 8b): POST /api/agent/cloud-verifier/capture/key, a
+ * repository member's call, idempotent (the same application gets the same key; new origins replace the old). */
+export async function registerCaptureApp(token, repository, app, origins) {
+    const query = new URLSearchParams({ repository, app });
+    const response = await haystackJson(`/api/agent/cloud-verifier/capture/key?${query}`, token, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ origins }),
+    });
+    if (typeof response.key !== 'string' || !CAPTURE_KEY_PATTERN.test(response.key)
+        || typeof response.repositoryId !== 'string' || response.repositoryId === ''
+        || typeof response.applicationId !== 'string' || response.applicationId === '') {
+        throw new Error('Haystack answered the capture registration without a key, repository id and application id.');
+    }
+    return { key: response.key, repositoryId: response.repositoryId, applicationId: response.applicationId };
+}
+/** The application's registration as Haystack holds it now (GET /api/agent/cloud-verifier/capture/status, lane A): its key
+ * and production origins, or null when the application is not registered (404). */
+export async function readCaptureRegistration(token, repository, app) {
+    const query = new URLSearchParams({ repository, app });
+    const response = await haystackFetch(`${CAPTURE_STATUS_PATH}?${query}`, token, {}, [404]);
+    if (response.status === 404) {
+        await response.body?.cancel();
+        return null;
+    }
+    const status = await response.json();
+    if (typeof status.key !== 'string' || !CAPTURE_KEY_PATTERN.test(status.key) || !Array.isArray(status.origins)
+        || !status.origins.every(origin => typeof origin === 'string')) {
+        throw new Error('Haystack answered the capture status without a key and its origins.');
+    }
+    return { key: status.key, origins: [...status.origins].sort() };
+}

package/dist/capture/consent.js

@@ -0,0 +1,127 @@
+/**
+ * Consent wiring (CAPTURE-V1 rules 2 and 8b(i)). The coding agent passes its user's answer (--consent); init never assumes one.
+ *
+ *   not-required        the site's owner decided consent is not required for this measurement: data-consent="not-required"
+ *   manual              the tag stays gated; the site's own banner calls HaystackCapture.consent(true|false)
+ *   cookiebot           Cookiebot's `statistics` category
+ *   onetrust:<group>    OneTrust's category id for performance/analytics cookies (C0002 in OneTrust's default taxonomy, but
+ *                       sites rename and renumber categories, so the user names it; init never picks one)
+ *   anything else       an unknown platform: a manual step, the tag stays gated
+ *
+ * Why these two platforms: OneTrust is the most deployed consent platform on large sites and Cookiebot (Usercentrics) on
+ * small and mid-size ones, and both expose a documented CURRENT state (Cookiebot.consent, OnetrustActiveGroups) and a
+ * change event on window (CookiebotOnConsentReady/OnAccept/OnDecline, OneTrustGroupsUpdated), so the integration can
+ * apply the platform's state whenever it changes without wrapping or replacing any of the platform's globals or
+ * callbacks (OneTrust's OptanonWrapper belongs to the site). Platforms whose consent is per vendor (Usercentrics'
+ * services, IAB TCF vendor lists) need a Haystack entry configured in the platform first, which init cannot check.
+ *
+ * The integration is a static file next to the tag (CSP 'self', no inline script). It reads the platform's current
+ * state at load and on every change event and passes it on: HaystackCapture.consent(granted) once the tag is ready, or
+ * into the tag's pre-load queue (`HaystackCapture.q.push(['consent', granted])`) before it is, in order, so a grant made
+ * before the tag loads is not lost and a withdrawal is never followed by a stale grant. It calls only on a change from
+ * the tag's default (no consent), never throws (rule 13a), writes nothing to the page and keeps no state but the last
+ * value it passed on.
+ */
+import { createHash } from 'node:crypto';
+import { sha384Integrity } from './script-release.js';
+const ONETRUST_GROUP = /^[A-Za-z0-9_-]{1,32}$/;
+const PLATFORM_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+export function parseConsentChoice(raw) {
+    const value = raw.trim().toLowerCase();
+    if (value === 'not-required')
+        return { kind: 'not-required' };
+    if (value === 'manual')
+        return { kind: 'manual' };
+    if (value === 'cookiebot')
+        return { kind: 'cookiebot' };
+    if (value === 'onetrust' || value.startsWith('onetrust:')) {
+        const group = raw.trim().slice('onetrust:'.length);
+        if (value === 'onetrust' || !ONETRUST_GROUP.test(group)) {
+            throw new Error('--consent onetrust needs the OneTrust category id that covers analytics, e.g. `onetrust:C0002`'
+                + ' (OneTrust\'s default id for performance cookies; ask your user which category this site uses).');
+        }
+        return { kind: 'onetrust', group };
+    }
+    if (!PLATFORM_NAME.test(value))
+        throw new Error(`--consent ${raw} is not a consent answer: use not-required, manual, cookiebot or onetrust:<category>.`);
+    return { kind: 'unknown-platform', name: value };
+}
+export function formatConsentChoice(choice) {
+    switch (choice.kind) {
+        case 'onetrust': return `onetrust:${choice.group}`;
+        case 'unknown-platform': return choice.name;
+        default: return choice.kind;
+    }
+}
+/** The answer as people read it: `Cookiebot (statistics)`, `OneTrust (category C0002)`. */
+export function consentLabel(choice) {
+    switch (choice.kind) {
+        case 'cookiebot': return 'Cookiebot (statistics)';
+        case 'onetrust': return `OneTrust (category ${choice.group})`;
+        case 'unknown-platform': return choice.name;
+        default: return choice.kind;
+    }
+}
+/** The pass-on shared by both integrations; `READ` is the platform-specific expression for the current state, or null
+ * while the platform has none. */
+function integration(platform, events, read) {
+    return `/* Haystack capture consent: ${platform} (CAPTURE-V1 rule 2). Written by \`haystack init\`; immutable (its name carries its hash). */
+(function () {
+  try {
+    var w = window;
+    var last = false;
+    var apply = function () {
+      try {
+        var granted = ${read};
+        if (granted === null || granted === last) return;
+        last = granted;
+        var capture = w.HaystackCapture;
+        if (capture && typeof capture.consent === 'function') capture.consent(granted);
+        else {
+          capture = w.HaystackCapture = capture || { q: [] };
+          capture.q.push(['consent', granted]);
+        }
+      } catch (error) { /* telemetry never reaches the page (rule 13a) */ }
+    };
+    var events = ${JSON.stringify(events)};
+    for (var i = 0; i < events.length; i += 1) w.addEventListener(events[i], apply, { passive: true });
+    apply();
+  } catch (error) { /* telemetry never reaches the page (rule 13a) */ }
+})();
+`;
+}
+/** The integration file for a supported platform; null for every other answer. */
+export function consentScript(choice) {
+    let platform;
+    let source;
+    if (choice.kind === 'cookiebot') {
+        platform = 'cookiebot';
+        source = integration('Cookiebot, statistics category', ['CookiebotOnConsentReady', 'CookiebotOnLoad', 'CookiebotOnAccept', 'CookiebotOnDecline'], '(w.Cookiebot && w.Cookiebot.consent) ? w.Cookiebot.consent.statistics === true : null');
+    }
+    else if (choice.kind === 'onetrust') {
+        platform = 'onetrust';
+        source = integration(`OneTrust, category ${choice.group}`, ['OneTrustGroupsUpdated'], `typeof w.OnetrustActiveGroups === 'string' ? w.OnetrustActiveGroups.split(',').indexOf(${JSON.stringify(choice.group)}) !== -1 : null`);
+    }
+    else {
+        return null;
+    }
+    const bytes = Buffer.from(source, 'utf8');
+    const hash = createHash('sha256').update(bytes).digest('hex').slice(0, 12);
+    return { file: `consent-${platform}.${hash}.js`, integrity: sha384Integrity(bytes), bytes };
+}
+const MANUAL_CALL = [
+    '  window.HaystackCapture = window.HaystackCapture || { q: [] };',
+    '  if (typeof HaystackCapture.consent === \'function\') HaystackCapture.consent(granted);',
+    '  else HaystackCapture.q.push([\'consent\', granted]);',
+].join('\n');
+/** The manual consent step for answers init does not wire itself. */
+export function manualConsentStep(choice) {
+    const how = 'From your consent banner, with the visitor\'s current choice as `granted` (true or false), when the page loads'
+        + ` and whenever it changes, run:\n${MANUAL_CALL}\nUntil then the tag records nothing.`;
+    if (choice.kind === 'manual')
+        return `Wire consent. ${how}`;
+    if (choice.kind === 'unknown-platform') {
+        return `Wire consent: init has no integration for ${choice.name} (it has cookiebot and onetrust:<category>), so the tag stays gated. ${how}`;
+    }
+    return null;
+}