@enricai/barnacle 1.0.0

package/dist/plugins/json-schema-to-zod.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Converts a JSON-Schema fragment into a live Zod schema instance built from
+ * the project's own `zod/v4` import. Config plugins declare their request,
+ * response, and extract shapes as inert JSON Schema in the manifest; the loader
+ * needs real Zod instances because `validatePluginShape`
+ * (`src/plugins/discover.ts`) duck-types `meta.bodySchema`/`meta.responseSchema`
+ * for `safeParse`/`parse`, and `guardedExtract` constrains its schema argument
+ * to `z.ZodTypeAny`.
+ *
+ * Why in-house and not a library: `z.fromJSONSchema` does not exist on the
+ * pinned `zod@3.25.76` (only the reverse `z.toJSONSchema`), and any third-party
+ * converter would emit an instance from a *different* Zod copy — failing both
+ * the loader duck-type and Stagehand's `StagehandZodSchema` union. Building from
+ * this module's own `z` is the only instance-safe route.
+ *
+ * Scope is deliberately the flat form real form-field payloads need
+ * (object/string/number/integer/boolean/array/enum + `required`). Anything
+ * outside that surface throws at load time rather than silently degrading, so a
+ * manifest that leans on unsupported JSON-Schema features fails loudly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsupportedJsonSchemaError = void 0;
+exports.jsonSchemaToZod = jsonSchemaToZod;
+const v4_1 = require("zod/v4");
+/** Thrown when a manifest schema uses a JSON-Schema construct this converter does not support. */
+class UnsupportedJsonSchemaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UnsupportedJsonSchemaError";
+    }
+}
+exports.UnsupportedJsonSchemaError = UnsupportedJsonSchemaError;
+const JSON_SCHEMA_NODE = v4_1.z.lazy(() => v4_1.z
+    .object({
+    type: v4_1.z.enum(["object", "string", "number", "integer", "boolean", "array"]).optional(),
+    properties: v4_1.z.record(v4_1.z.string(), JSON_SCHEMA_NODE).optional(),
+    required: v4_1.z.array(v4_1.z.string()).optional(),
+    items: JSON_SCHEMA_NODE.optional(),
+    enum: v4_1.z.array(v4_1.z.string()).min(1).optional(),
+    format: v4_1.z.string().optional(),
+    description: v4_1.z.string().optional(),
+})
+    .strict());
+/** Builds the Zod leaf/branch for one already-validated JSON-Schema node. */
+function nodeToZod(node) {
+    if (node.enum) {
+        return v4_1.z.enum(node.enum);
+    }
+    switch (node.type) {
+        case "string":
+            return v4_1.z.string();
+        case "number":
+        case "integer":
+            return v4_1.z.number();
+        case "boolean":
+            return v4_1.z.boolean();
+        case "array":
+            return v4_1.z.array(node.items ? nodeToZod(node.items) : v4_1.z.unknown());
+        case "object": {
+            const required = new Set(node.required ?? []);
+            const shape = {};
+            for (const [key, child] of Object.entries(node.properties ?? {})) {
+                const childSchema = nodeToZod(child);
+                shape[key] = required.has(key) ? childSchema : childSchema.optional();
+            }
+            return v4_1.z.object(shape);
+        }
+        default:
+            throw new UnsupportedJsonSchemaError(`unsupported JSON-Schema node: ${JSON.stringify(node).slice(0, 120)}`);
+    }
+}
+/**
+ * Converts a manifest's JSON-Schema fragment into a Zod schema instance.
+ * Validates the fragment's structure first so unsupported constructs surface as
+ * a descriptive error at plugin-load time instead of a downstream parse crash.
+ */
+function jsonSchemaToZod(schema) {
+    const parsed = JSON_SCHEMA_NODE.safeParse(schema);
+    if (!parsed.success) {
+        throw new UnsupportedJsonSchemaError(`invalid or unsupported JSON schema: ${parsed.error.message}`);
+    }
+    return nodeToZod(parsed.data);
+}
+//# sourceMappingURL=json-schema-to-zod.js.map

package/dist/plugins/json-schema-to-zod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema-to-zod.js","sourceRoot":"","sources":["../../src/plugins/json-schema-to-zod.ts"],"names":[],"mappings":"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"}

package/dist/plugins/loader.d.ts

@@ -0,0 +1,34 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { FastifyInstance, RawServerDefault } from "fastify";
+import type { AppConfig } from "../config";
+import type { SitePlugin, SitePluginContext, SitePluginResult } from "../site-plugin";
+import type { Logger } from "../types/logging";
+/**
+ * Alias for `BUILTIN_SITE_PLUGINS` kept for backwards compatibility with
+ * tests that import `SITE_PLUGINS` directly from this module. New code
+ * should reference `BUILTIN_SITE_PLUGINS` from `discover.ts` directly or
+ * call `loadAllPlugins` for the composed set.
+ */
+export declare const SITE_PLUGINS: SitePlugin<unknown, unknown>[];
+/**
+ * Runs a single plugin submission end-to-end. Tries the direct-HTTP hot path
+ * first when the plugin supplies `executeHttp`; on `HttpSchemaError`,
+ * `HttpBotChallengeError`, or `HttpServerError` falls back to the Stagehand
+ * browser path. Records metrics on each branch so ops dashboards can alert on
+ * rising fallback rates. Emits a `submission-envelope` telemetry record on
+ * both success and failure — the durable source-of-truth for "what did we
+ * submit for jobId X and did it succeed." Maps scraper errors to the API
+ * error hierarchy so callers receive typed, client-readable errors instead
+ * of raw scraper internals.
+ */
+export declare function dispatch<TResult>(plugin: SitePlugin<unknown, unknown>, payload: unknown, context: SitePluginContext, options?: {
+    forceFallback?: boolean;
+}): Promise<SitePluginResult<TResult>>;
+/**
+ * Registers one Fastify POST route per plugin plus any extra routes declared
+ * in `plugin.meta.extraRoutes`. Called from `buildServer()` so `server.ts`
+ * stays site-agnostic — it delegates all plugin-specific route knowledge
+ * (path, schema, dispatch) to this module instead of maintaining an inline loop.
+ */
+export declare function registerRoutes(app: FastifyInstance<RawServerDefault, IncomingMessage, ServerResponse, Logger>, cfg: AppConfig, plugins: SitePlugin<unknown, unknown>[]): Promise<void>;
+//# sourceMappingURL=loader.d.ts.map

package/dist/plugins/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/plugins/loader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAejE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAkC1C,OAAO,KAAK,EACV,UAAU,EACV,iBAAiB,EAEjB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAW9C;;;;;GAKG;AACH,eAAO,MAAM,YAAY,gCAAuB,CAAC;AAiHjD;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EACpC,MAAM,EAAE,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,EACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GACxC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAuEpC;AA+BD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,eAAe,CAAC,gBAAgB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,CAAC,EAC/E,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,GACtC,OAAO,CAAC,IAAI,CAAC,CA4Cf"}

package/dist/plugins/loader.js

@@ -0,0 +1,348 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SITE_PLUGINS = void 0;
+exports.dispatch = dispatch;
+exports.registerRoutes = registerRoutes;
+const multipart_1 = __importDefault(require("@fastify/multipart"));
+const v4_1 = require("zod/v4");
+const errors_1 = require("../api/errors");
+const envelope_1 = require("../api/helpers/envelope");
+const response_cache_1 = require("../cache/response-cache");
+const dd_metrics_1 = require("../lib/dd-metrics");
+const dispatch_metrics_1 = require("../lib/dispatch-metrics");
+const errors_2 = require("../lib/errors");
+const logging_1 = require("../lib/logging");
+const submission_capture_1 = require("../lib/telemetry/submission-capture");
+const tracking_click_1 = require("../lib/tracking-click");
+const discover_1 = require("../plugins/discover");
+const errors_3 = require("../scraper/errors");
+const metrics_1 = require("../scraper/metrics");
+const pool_1 = require("../scraper/pool");
+const dispatch_metrics_2 = require("../types/dispatch-metrics");
+const logger = (0, logging_1.getLogger)({ name: "plugins/loader" });
+/**
+ * Params schema for shared `:siteId`-parameterized extra routes. Core validates
+ * only the site discriminator; each plugin's own body contract is enforced in
+ * the handler after the owning plugin is resolved.
+ */
+const siteIdRouteParamsSchema = v4_1.z.object({ siteId: v4_1.z.string().min(1) });
+/**
+ * Alias for `BUILTIN_SITE_PLUGINS` kept for backwards compatibility with
+ * tests that import `SITE_PLUGINS` directly from this module. New code
+ * should reference `BUILTIN_SITE_PLUGINS` from `discover.ts` directly or
+ * call `loadAllPlugins` for the composed set.
+ */
+exports.SITE_PLUGINS = discover_1.BUILTIN_SITE_PLUGINS;
+/**
+ * Pure mapping from scraper-internal errors to the public ApiError hierarchy.
+ *
+ * Exists so dispatch()'s catch block stays a short tail of guard clauses —
+ * the if-instanceof chain captures the entire scraper-to-wire error contract
+ * in one place. Returns `undefined` when the caller should re-throw the
+ * original error (plain Error or anything outside the ScraperError tree).
+ */
+function toApiError(err) {
+    if (err instanceof errors_3.CaptchaError)
+        return new errors_1.CaptchaEncounteredError(err.message);
+    if (err instanceof errors_3.EmptyResultsError)
+        return new errors_1.EmptyResultsApiError(err.message);
+    if (err instanceof errors_3.HttpRateLimitError)
+        return new errors_1.ThrottledRequestError(err.message);
+    if (err instanceof errors_3.HttpUrlLockedError)
+        return new errors_1.UrlLockedError(err.message);
+    if (err instanceof errors_3.ScraperError)
+        return new errors_1.ScrapeFailureError(err.message);
+    return undefined;
+}
+/**
+ * Runs the hot path (when available) + fallback pipeline for a single
+ * submission. Extracted so dispatch() reads as a linear "run pipeline,
+ * record audit, return" sequence rather than a `let result` mutated across
+ * three branches.
+ */
+async function runPluginPipeline(plugin, payload, context, options) {
+    if (!plugin.executeHttp || options.forceFallback) {
+        if (options.forceFallback) {
+            (0, metrics_1.recordFallbackActivation)(plugin.meta.siteId);
+            (0, dd_metrics_1.recordDdFallback)(plugin.meta.siteId);
+        }
+        return (await (0, pool_1.runWithSession)((session) => plugin.execute(payload, session, context), { onRetry: plugin.onRetry }, plugin.meta.taskTimeoutMs, { advancedStealth: plugin.meta.advancedStealth }));
+    }
+    try {
+        const { value: cached, key } = (0, response_cache_1.getCachedResponse)(`${context.baseUrl}:${plugin.meta.siteId}`, payload);
+        if (cached) {
+            (0, metrics_1.recordHotPathSuccess)(plugin.meta.siteId);
+            return cached;
+        }
+        const t0 = Date.now();
+        const fresh = await (0, response_cache_1.getOrCreateInFlight)(key, 
+        // biome-ignore lint/style/noNonNullAssertion: guarded by !plugin.executeHttp above
+        () => plugin.executeHttp(payload, context));
+        (0, metrics_1.recordHotPathLatency)(plugin.meta.siteId, Date.now() - t0);
+        (0, metrics_1.recordHotPathSuccess)(plugin.meta.siteId);
+        return fresh;
+    }
+    catch (httpErr) {
+        if (httpErr instanceof errors_3.HttpSchemaError ||
+            httpErr instanceof errors_3.HttpBotChallengeError ||
+            httpErr instanceof errors_3.HttpServerError) {
+            logger.warn(`hot path failed for ${plugin.meta.siteId} (${httpErr.constructor.name}): ${httpErr.message} — engaging browser fallback`);
+            (0, metrics_1.recordFallbackActivation)(plugin.meta.siteId);
+            (0, dd_metrics_1.recordDdFallback)(plugin.meta.siteId);
+            return (await (0, pool_1.runWithSession)((session) => plugin.execute(payload, session, context), { onRetry: plugin.onRetry }, plugin.meta.taskTimeoutMs, { advancedStealth: plugin.meta.advancedStealth }));
+        }
+        if (httpErr instanceof errors_3.HttpRateLimitError) {
+            logger.warn(`hot path rate-limited for ${plugin.meta.siteId}: ${httpErr.message} — not falling back`);
+            (0, metrics_1.recordRateLimitRejection)(plugin.meta.siteId);
+            (0, dd_metrics_1.recordDdRateLimit)(plugin.meta.siteId);
+        }
+        if (httpErr instanceof errors_3.HttpUrlLockedError) {
+            logger.warn(`hot path url-locked for ${plugin.meta.siteId}: ${httpErr.message} — not falling back`);
+        }
+        throw httpErr;
+    }
+}
+/**
+ * Best-effort wrapper around `captureSubmissionEnvelope`. The helper itself
+ * already swallows write errors, but defending dispatch against a misbehaving
+ * sink (or a test mock that bypasses the helper's internal try/catch) keeps
+ * the audit emission contractually non-breaking: a sink failure must never
+ * propagate into the request path.
+ */
+async function emitEnvelopeSafely(input) {
+    try {
+        await (0, submission_capture_1.captureSubmissionEnvelope)(input);
+    }
+    catch (err) {
+        logger.warn(`submission envelope emit failed: ${(0, errors_2.toErrorMessage)(err)}`);
+    }
+}
+/**
+ * Runs a single plugin submission end-to-end. Tries the direct-HTTP hot path
+ * first when the plugin supplies `executeHttp`; on `HttpSchemaError`,
+ * `HttpBotChallengeError`, or `HttpServerError` falls back to the Stagehand
+ * browser path. Records metrics on each branch so ops dashboards can alert on
+ * rising fallback rates. Emits a `submission-envelope` telemetry record on
+ * both success and failure — the durable source-of-truth for "what did we
+ * submit for jobId X and did it succeed." Maps scraper errors to the API
+ * error hierarchy so callers receive typed, client-readable errors instead
+ * of raw scraper internals.
+ */
+async function dispatch(plugin, payload, context, options = {}) {
+    const startedAt = Date.now();
+    const hasHttpPath = !!plugin.executeHttp && !options.forceFallback;
+    const pathTag = hasHttpPath ? "http" : "browser";
+    const ddTags = { site: plugin.meta.siteId, path: pathTag };
+    (0, dd_metrics_1.recordDdAttempt)(ddTags);
+    try {
+        const result = await runPluginPipeline(plugin, payload, context, options);
+        const durationMs = Date.now() - startedAt;
+        // Short-circuit: the hot path signalled that the user must supply additional
+        // information (OTP or missing profile fields). This is not a success — skip
+        // the submission envelope and tracking click so the challenge state is not
+        // recorded as a completed application.
+        if (result.data.needsUserInfo === true) {
+            result.metrics = context.metricsCollector.finalize(pathTag);
+            return result;
+        }
+        (0, dd_metrics_1.recordDdSuccess)(ddTags);
+        (0, dd_metrics_1.recordDdDuration)(ddTags, durationMs);
+        const metrics = context.metricsCollector.finalize(pathTag);
+        result.metrics = metrics;
+        await emitEnvelopeSafely({
+            siteId: plugin.meta.siteId,
+            requestId: context.requestId,
+            inboundPayload: payload,
+            status: "submitted",
+            auditPayload: result.auditPayload ?? result.data,
+            errorMessage: null,
+            durationMs,
+        });
+        const trackingUrl = payload?.TrackingUrl;
+        if (typeof trackingUrl === "string" && trackingUrl.length > 0) {
+            (0, tracking_click_1.fireTrackingClick)(trackingUrl, plugin.meta.siteId);
+        }
+        return result;
+    }
+    catch (err) {
+        const durationMs = Date.now() - startedAt;
+        const errorType = classifyDispatchError(err);
+        const failureTags = { ...ddTags, error_type: errorType };
+        (0, dd_metrics_1.recordDdFailure)(failureTags);
+        (0, dd_metrics_1.recordDdDuration)(ddTags, durationMs);
+        const metrics = context.metricsCollector.finalize(pathTag);
+        await emitEnvelopeSafely({
+            siteId: plugin.meta.siteId,
+            requestId: context.requestId,
+            inboundPayload: payload,
+            status: "error",
+            auditPayload: null,
+            errorMessage: (0, errors_2.toErrorMessage)(err),
+            durationMs,
+        });
+        const apiErr = toApiError(err);
+        if (apiErr) {
+            apiErr.metrics = metrics;
+            throw apiErr;
+        }
+        err.metrics = metrics;
+        throw err;
+    }
+}
+/** Maps errors to DogStatsD-friendly classification strings. */
+function classifyDispatchError(err) {
+    if (err instanceof errors_3.HttpBotChallengeError)
+        return "bot_challenge";
+    if (err instanceof errors_3.HttpRateLimitError)
+        return "rate_limit";
+    if (err instanceof errors_3.HttpUrlLockedError)
+        return "url_locked";
+    if (err instanceof errors_3.HttpSchemaError)
+        return "schema_drift";
+    if (err instanceof errors_3.HttpServerError)
+        return "server_error";
+    if (err instanceof errors_3.CaptchaError)
+        return "captcha";
+    if (err instanceof errors_3.EmptyResultsError)
+        return "empty_results";
+    if (err instanceof errors_3.ScraperError)
+        return "scraper_generic";
+    return "unknown";
+}
+const ResponseEnvelopeSchema = v4_1.z.object({
+    status: v4_1.z.object({
+        httpStatus: v4_1.z.string(),
+        dateTime: v4_1.z.string(),
+        details: v4_1.z.array(v4_1.z.unknown()),
+    }),
+    metrics: dispatch_metrics_2.DispatchMetricsSchema.optional(),
+});
+function buildEnvelopedResponseSchema(pluginSchema) {
+    if (pluginSchema instanceof v4_1.z.ZodObject) {
+        return ResponseEnvelopeSchema.extend(pluginSchema.shape).passthrough();
+    }
+    return v4_1.z.unknown();
+}
+/**
+ * Registers one Fastify POST route per plugin plus any extra routes declared
+ * in `plugin.meta.extraRoutes`. Called from `buildServer()` so `server.ts`
+ * stays site-agnostic — it delegates all plugin-specific route knowledge
+ * (path, schema, dispatch) to this module instead of maintaining an inline loop.
+ */
+async function registerRoutes(app, cfg, plugins) {
+    const needsMultipart = plugins.some((p) => p.meta.multipart === true || p.meta.extraRoutes?.some((r) => r.multipart === true));
+    if (needsMultipart) {
+        await app.register(multipart_1.default, { attachFieldsToBody: "keyValues" });
+    }
+    for (const plugin of plugins) {
+        const routePath = plugin.meta.routeOverride ?? `/v1/${plugin.meta.siteId}/run`;
+        const baseUrl = cfg.scraper.siteBaseUrls[plugin.meta.siteId] ?? plugin.meta.defaultBaseUrl ?? "";
+        app.post(routePath, {
+            onRequest: [app.authenticate],
+            schema: {
+                body: plugin.meta.bodySchema,
+                response: { 200: buildEnvelopedResponseSchema(plugin.meta.responseSchema) },
+                ...(plugin.meta.multipart === true ? { consumes: ["multipart/form-data"] } : {}),
+            },
+        }, async (request) => {
+            const forceFallback = request.headers["x-barnacle-force-fallback"] === "true";
+            const context = {
+                baseUrl,
+                logger: (0, logging_1.extendLogger)(request.log),
+                config: cfg,
+                requestId: request.id,
+                metricsCollector: new dispatch_metrics_1.MetricsCollector(),
+            };
+            const result = await dispatch(plugin, request.body, context, { forceFallback });
+            return (0, envelope_1.successEnvelope)({
+                ...result.data,
+                ...(result.metrics && { metrics: result.metrics }),
+            });
+        });
+        logger.info(`${plugin.meta.siteId} → ${routePath} (loaded)`);
+    }
+    registerExtraRoutes(app, cfg, plugins);
+}
+/**
+ * Fastify registers each `method+url` exactly once, but several plugins declare
+ * the SAME parameterized extra route (e.g. `POST /v1/:siteId/resume` for both
+ * appcast and encompasshealth). Registering per-plugin throws
+ * `FST_ERR_DUPLICATED_ROUTE` and crashes boot.
+ *
+ * We group extra routes by `method+path` and register each unique path once.
+ * A path claimed by a single plugin registers with that plugin's own body/params
+ * schema and handler (unchanged behavior). A path shared by multiple plugins is
+ * necessarily `:siteId`-parameterized: core validates only the `:siteId` param,
+ * then resolves the owning plugin from it at request time and validates the body
+ * against that plugin's own `bodySchema`, because sibling plugins sharing a path
+ * carry different body contracts.
+ */
+function registerExtraRoutes(app, cfg, plugins) {
+    const byMethodPath = new Map();
+    for (const plugin of plugins) {
+        for (const route of plugin.meta.extraRoutes ?? []) {
+            const method = route.method.toUpperCase();
+            const key = `${method} ${route.path}`;
+            const entry = byMethodPath.get(key) ?? {
+                method,
+                path: route.path,
+                multipart: false,
+                owners: new Map(),
+            };
+            entry.multipart = entry.multipart || route.multipart === true;
+            entry.owners.set(plugin.meta.siteId, plugin);
+            byMethodPath.set(key, entry);
+        }
+    }
+    for (const entry of byMethodPath.values()) {
+        const shared = entry.owners.size > 1;
+        const findRoute = (plugin) => plugin.meta.extraRoutes?.find((r) => r.method.toUpperCase() === entry.method && r.path === entry.path);
+        const soleOwner = shared ? undefined : [...entry.owners.values()][0];
+        const soleRoute = soleOwner ? findRoute(soleOwner) : undefined;
+        app.route({
+            method: entry.method,
+            url: entry.path,
+            onRequest: [app.authenticate],
+            schema: {
+                ...(shared ? { params: siteIdRouteParamsSchema } : {}),
+                ...(!shared && soleRoute?.bodySchema ? { body: soleRoute.bodySchema } : {}),
+                ...(!shared && soleRoute?.paramsSchema ? { params: soleRoute.paramsSchema } : {}),
+                ...(entry.multipart ? { consumes: ["multipart/form-data"] } : {}),
+            },
+            handler: async (request) => {
+                const siteId = request.params.siteId ?? "";
+                const plugin = shared ? entry.owners.get(siteId) : soleOwner;
+                if (!plugin) {
+                    throw new errors_1.FieldViolationError(`no plugin registered for siteId ${JSON.stringify(siteId)} on ${entry.method} ${entry.path}`);
+                }
+                const route = findRoute(plugin);
+                if (!route) {
+                    throw new errors_1.FieldViolationError(`plugin ${plugin.meta.siteId} has no handler for ${entry.method} ${entry.path}`);
+                }
+                // Fastify already validated the body for single-owner routes (schema.body
+                // above); shared routes defer body validation to here, against the
+                // resolved plugin's own contract.
+                const body = shared && route.bodySchema ? route.bodySchema.parse(request.body) : request.body;
+                const baseUrl = cfg.scraper.siteBaseUrls[plugin.meta.siteId] ?? plugin.meta.defaultBaseUrl ?? "";
+                const context = {
+                    baseUrl,
+                    logger: (0, logging_1.extendLogger)(request.log),
+                    config: cfg,
+                    requestId: request.id,
+                    metricsCollector: new dispatch_metrics_1.MetricsCollector(),
+                };
+                const result = await route.handler({
+                    body,
+                    params: request.params,
+                    log: request.log,
+                }, context);
+                return route.envelope === false ? result : (0, envelope_1.successEnvelope)(result);
+            },
+        });
+        logger.info(`${entry.path} → [${[...entry.owners.keys()].join(", ")}] via ${entry.method} (loaded)`);
+    }
+}
+//# sourceMappingURL=loader.js.map

package/dist/plugins/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/plugins/loader.ts"],"names":[],"mappings":"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"}

package/dist/plugins/plugin-api-version.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Runtime version of the plugin API contract that core enforces at load time.
+ * Kept separate from `site-plugin.ts` because that file is strictly type-only
+ * and must have zero runtime side effects; a `const` value would break that
+ * guarantee.
+ */
+export declare const PLUGIN_API_VERSION: "1.0.0";
+//# sourceMappingURL=plugin-api-version.d.ts.map

package/dist/plugins/plugin-api-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-api-version.d.ts","sourceRoot":"","sources":["../../src/plugins/plugin-api-version.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAG,OAAgB,CAAC"}

package/dist/plugins/plugin-api-version.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_API_VERSION = void 0;
+/**
+ * Runtime version of the plugin API contract that core enforces at load time.
+ * Kept separate from `site-plugin.ts` because that file is strictly type-only
+ * and must have zero runtime side effects; a `const` value would break that
+ * guarantee.
+ */
+exports.PLUGIN_API_VERSION = "1.0.0";
+//# sourceMappingURL=plugin-api-version.js.map

package/dist/plugins/plugin-api-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-api-version.js","sourceRoot":"","sources":["../../src/plugins/plugin-api-version.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACU,QAAA,kBAAkB,GAAG,OAAgB,CAAC"}

package/dist/plugins/plugin-manifest-envelope.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Kubernetes-style envelope constants for config-plugin manifests. Kept in a
+ * tiny leaf module (no heavy imports) so both the runtime loader
+ * (`config-plugin.ts`, which validates with `z.literal`) and the build-time
+ * emitter (`recon-generate.ts`, which writes manifests) share one source of
+ * truth — a version bump can't silently desync the emitter from the gate.
+ */
+/**
+ * Manifest `apiVersion` the config-plugin factory understands (K8s
+ * `group/version`). Its major segment tracks `PLUGIN_API_VERSION`, the runtime
+ * plugin-API contract in `plugin-api-version.ts`.
+ */
+export declare const CONFIG_PLUGIN_API_VERSION: "barnacle.dev/v1";
+/** Manifest `kind` the config-plugin factory understands. */
+export declare const CONFIG_PLUGIN_KIND: "SitePlugin";
+//# sourceMappingURL=plugin-manifest-envelope.d.ts.map

package/dist/plugins/plugin-manifest-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-manifest-envelope.d.ts","sourceRoot":"","sources":["../../src/plugins/plugin-manifest-envelope.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAG,iBAA0B,CAAC;AAEpE,6DAA6D;AAC7D,eAAO,MAAM,kBAAkB,EAAG,YAAqB,CAAC"}

package/dist/plugins/plugin-manifest-envelope.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Kubernetes-style envelope constants for config-plugin manifests. Kept in a
+ * tiny leaf module (no heavy imports) so both the runtime loader
+ * (`config-plugin.ts`, which validates with `z.literal`) and the build-time
+ * emitter (`recon-generate.ts`, which writes manifests) share one source of
+ * truth — a version bump can't silently desync the emitter from the gate.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_PLUGIN_KIND = exports.CONFIG_PLUGIN_API_VERSION = void 0;
+/**
+ * Manifest `apiVersion` the config-plugin factory understands (K8s
+ * `group/version`). Its major segment tracks `PLUGIN_API_VERSION`, the runtime
+ * plugin-API contract in `plugin-api-version.ts`.
+ */
+exports.CONFIG_PLUGIN_API_VERSION = "barnacle.dev/v1";
+/** Manifest `kind` the config-plugin factory understands. */
+exports.CONFIG_PLUGIN_KIND = "SitePlugin";
+//# sourceMappingURL=plugin-manifest-envelope.js.map

package/dist/plugins/plugin-manifest-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-manifest-envelope.js","sourceRoot":"","sources":["../../src/plugins/plugin-manifest-envelope.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH;;;;GAIG;AACU,QAAA,yBAAyB,GAAG,iBAA0B,CAAC;AAEpE,6DAA6D;AAChD,QAAA,kBAAkB,GAAG,YAAqB,CAAC"}

package/dist/scraper/behavioral-signals.d.ts

@@ -0,0 +1,16 @@
+/**
+ * CDP behavioral-signal dispatcher. Sends synthetic mouse-move and scroll
+ * events to give bot-detection scripts (e.g. DataDome's tags.js) the UI
+ * signals they need to complete fingerprint computation. Without these,
+ * passive page loads produce zero events, causing tags.js to delay or refuse
+ * fingerprint resolution. Verified 2026-06-20: 0% resolution without signals
+ * → 67%+ with CDP mouseMoved + scroll dispatched during the poll loop.
+ */
+import type { Page } from "@browserbasehq/stagehand";
+/**
+ * Dispatches two synthetic mouseMoved CDP events and a window.scrollBy(0,50)
+ * on `page`. Call once per poll iteration inside any warmup loop that needs
+ * DataDome (or similar) fingerprint resolution.
+ */
+export declare function dispatchBehavioralSignals(page: Page): Promise<void>;
+//# sourceMappingURL=behavioral-signals.d.ts.map

package/dist/scraper/behavioral-signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavioral-signals.d.ts","sourceRoot":"","sources":["../../src/scraper/behavioral-signals.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,0BAA0B,CAAC;AAErD;;;;GAIG;AACH,wBAAsB,yBAAyB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAYzE"}

package/dist/scraper/behavioral-signals.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * CDP behavioral-signal dispatcher. Sends synthetic mouse-move and scroll
+ * events to give bot-detection scripts (e.g. DataDome's tags.js) the UI
+ * signals they need to complete fingerprint computation. Without these,
+ * passive page loads produce zero events, causing tags.js to delay or refuse
+ * fingerprint resolution. Verified 2026-06-20: 0% resolution without signals
+ * → 67%+ with CDP mouseMoved + scroll dispatched during the poll loop.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchBehavioralSignals = dispatchBehavioralSignals;
+/**
+ * Dispatches two synthetic mouseMoved CDP events and a window.scrollBy(0,50)
+ * on `page`. Call once per poll iteration inside any warmup loop that needs
+ * DataDome (or similar) fingerprint resolution.
+ */
+async function dispatchBehavioralSignals(page) {
+    await page.sendCDP("Input.dispatchMouseEvent", {
+        type: "mouseMoved",
+        x: 100 + Math.random() * 400,
+        y: 200 + Math.random() * 300,
+    });
+    await page.sendCDP("Input.dispatchMouseEvent", {
+        type: "mouseMoved",
+        x: 300 + Math.random() * 200,
+        y: 100 + Math.random() * 400,
+    });
+    await page.evaluate("window.scrollBy(0, 50)");
+}
+//# sourceMappingURL=behavioral-signals.js.map

package/dist/scraper/behavioral-signals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavioral-signals.js","sourceRoot":"","sources":["../../src/scraper/behavioral-signals.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AASH,8DAYC;AAjBD;;;;GAIG;AACI,KAAK,UAAU,yBAAyB,CAAC,IAAU;IACxD,MAAM,IAAI,CAAC,OAAO,CAAC,0BAA0B,EAAE;QAC7C,IAAI,EAAE,YAAY;QAClB,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG;QAC5B,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG;KAC7B,CAAC,CAAC;IACH,MAAM,IAAI,CAAC,OAAO,CAAC,0BAA0B,EAAE;QAC7C,IAAI,EAAE,YAAY;QAClB,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG;QAC5B,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,GAAG;KAC7B,CAAC,CAAC;IACH,MAAM,IAAI,CAAC,QAAQ,CAAC,wBAAwB,CAAC,CAAC;AAChD,CAAC"}