@enricai/barnacle 1.0.0

package/dist/plugins/config-plugin.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * Turns a declarative plugin manifest (JSON on disk, no per-site TypeScript)
+ * into a live {@link SitePlugin} at load time. This is what makes a Barnacle
+ * site loadable from configuration alone: the manifest carries the request /
+ * response / extract schemas as JSON Schema and the browser flow as data, and
+ * `buildConfigPlugin` synthesizes the Zod instances + `execute` function the
+ * loader's `validatePluginShape` requires.
+ *
+ * The manifest wears the Kubernetes-style `apiVersion` / `kind` / `metadata` /
+ * `spec` envelope so it reads like every other declarative object operators
+ * already know, and the browser flow reuses the same `RECON_FLOW_STEP_SCHEMA` +
+ * `runHealingFlow` interpreter the recon toolchain and generated plugins use —
+ * this factory is the recon-generate `emitBrowserFlowTs` template made
+ * data-driven instead of frozen into source.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIG_PLUGIN_MANIFEST = void 0;
+exports.buildConfigPlugin = buildConfigPlugin;
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
+const v4_1 = require("zod/v4");
+const schemas_1 = require("../lib/llm/schemas");
+const logging_1 = require("../lib/logging");
+const json_schema_to_zod_1 = require("../plugins/json-schema-to-zod");
+const plugin_api_version_1 = require("../plugins/plugin-api-version");
+const plugin_manifest_envelope_1 = require("../plugins/plugin-manifest-envelope");
+const flow_runner_1 = require("../scraper/flow-runner");
+const navigate_1 = require("../scraper/navigate");
+const stagehand_guard_1 = require("../scraper/stagehand-guard");
+/** JSON-Schema fragment as it appears verbatim in a manifest; converted to Zod at build time. */
+const jsonSchemaFragment = v4_1.z.record(v4_1.z.string(), v4_1.z.unknown());
+const flowSchema = v4_1.z.object({
+    steps: v4_1.z.array(schemas_1.RECON_FLOW_STEP_SCHEMA).min(1),
+    submitEndpointPattern: v4_1.z.string().nullish(),
+    submittedStateSelectors: v4_1.z.array(v4_1.z.string()).optional(),
+    requireSubmitEndpointMatch: v4_1.z.boolean().optional(),
+    advanceTransitionBodyPattern: v4_1.z.string().nullish(),
+    successUrlFragments: v4_1.z.array(v4_1.z.string()).optional(),
+    successPageTitleHints: v4_1.z.array(v4_1.z.string()).optional(),
+    ownBackendHostnames: v4_1.z.array(v4_1.z.string()).optional(),
+    knownErrorClassPrefixes: v4_1.z.array(v4_1.z.string()).optional(),
+    wizardExitButtonLabels: v4_1.z.array(v4_1.z.string()).optional(),
+});
+/**
+ * Structural schema for a config-plugin manifest. Validated before conversion
+ * so a malformed manifest fails at load with a descriptive Zod error rather
+ * than a runtime crash while the plugin is servicing a request.
+ */
+exports.CONFIG_PLUGIN_MANIFEST = v4_1.z.object({
+    apiVersion: v4_1.z.literal(plugin_manifest_envelope_1.CONFIG_PLUGIN_API_VERSION),
+    kind: v4_1.z.literal(plugin_manifest_envelope_1.CONFIG_PLUGIN_KIND),
+    metadata: v4_1.z.object({
+        siteId: v4_1.z.string().min(1),
+        displayName: v4_1.z.string().min(1),
+    }),
+    spec: v4_1.z.object({
+        defaultBaseUrl: v4_1.z.string().optional(),
+        routeOverride: v4_1.z.string().optional(),
+        multipart: v4_1.z.boolean().optional(),
+        advancedStealth: v4_1.z.boolean().optional(),
+        taskTimeoutMs: v4_1.z.number().optional(),
+        request: jsonSchemaFragment,
+        response: jsonSchemaFragment,
+        flow: flowSchema,
+        extract: v4_1.z.object({
+            instruction: v4_1.z.string().min(1),
+            schema: jsonSchemaFragment,
+        }),
+        httpModule: v4_1.z.string().optional(),
+    }),
+});
+/** Matches `{{ .request.FieldName }}` — the only interpolation form a manifest step may use. */
+const TEMPLATE_PATTERN = /\{\{\s*\.request\.([A-Za-z0-9_]+)\s*\}\}/g;
+/**
+ * Resolves `{{ .request.X }}` references in a step instruction against the
+ * validated request payload. Distinguishes two cases via `declaredFields` (the
+ * request schema's property names) so an omitted *optional* field is not
+ * conflated with a typo: a reference to an **undeclared** field throws (the
+ * manifest is wrong), while a **declared** field the caller omitted resolves to
+ * an empty string (a legitimately optional value). Values splice as inert text
+ * (no expression evaluation), so there is no injection surface.
+ */
+function resolveTemplate(instruction, payload, declaredFields) {
+    return instruction.replace(TEMPLATE_PATTERN, (_match, field) => {
+        if (!declaredFields.has(field)) {
+            throw new Error(`flow step references unknown request field "${field}"`);
+        }
+        return field in payload ? String(payload[field]) : "";
+    });
+}
+/** Normalizes one manifest flow step (bare string or object form) into a {@link HealingFlowStep}. */
+function toHealingStep(step, payload, declaredFields) {
+    if (typeof step === "string") {
+        return {
+            instruction: resolveTemplate(step, payload, declaredFields),
+            optional: false,
+            upload: false,
+            submitStep: false,
+        };
+    }
+    return {
+        instruction: resolveTemplate(step.step, payload, declaredFields),
+        optional: step.optional,
+        upload: step.upload,
+        submitStep: step.submitStep,
+    };
+}
+/**
+ * Builds the resume fixture the browser flow uploads, mirroring the rule the
+ * generator's `emitBrowserFlowTs` applies: only when a step uploads AND the
+ * manifest declares itself multipart do the `Resume*` payload fields exist.
+ */
+function buildResumeFixture(payload, hasUploadStep, multipart) {
+    if (!hasUploadStep || !multipart)
+        return null;
+    return {
+        buffer: Buffer.from(payload.Resume ?? "", "base64"),
+        name: payload.ResumeFilename ?? "resume.pdf",
+        mimeType: payload.ResumeContentType ?? "application/pdf",
+    };
+}
+/**
+ * Dynamically loads the optional `executeHttp` escape-hatch module a manifest
+ * may reference. Kept async and separate so a browser-only manifest never pays
+ * for an import it does not use, and a broken `httpModule` disables the plugin
+ * via the loader's normal failure path rather than crashing the factory.
+ *
+ * Resolution mirrors the loader's `resolvePluginSpecifier`: a `.`/`/` specifier
+ * is a filesystem path resolved against `baseDir` (so a relative `httpModule`
+ * resolves against the operator's `BARNACLE_PLUGINS_DIR`, not this module's
+ * location under `dist/`); anything else is a bare package name left for Node's
+ * resolver.
+ */
+async function loadHttpModule(specifier, baseDir) {
+    const resolved = specifier.startsWith(".") || specifier.startsWith("/")
+        ? (0, node_url_1.pathToFileURL)(node_path_1.default.resolve(baseDir, specifier)).href
+        : specifier;
+    const mod = (await import(resolved));
+    const candidate = mod.executeHttp ?? mod.default;
+    if (typeof candidate !== "function") {
+        throw new Error(`httpModule ${specifier} must export an executeHttp function`);
+    }
+    return candidate;
+}
+/**
+ * Synthesizes a {@link SitePlugin} from a validated manifest. The returned
+ * object satisfies the loader's `validatePluginShape` by construction: real Zod
+ * schemas for `bodySchema`/`responseSchema` and a data-driven `execute` that
+ * drives the manifest's flow through the shared self-healing interpreter.
+ *
+ * `baseDir` resolves a relative `spec.httpModule` escape-hatch path against the
+ * operator's plugin directory, matching the loader's specifier resolution; it
+ * defaults to `process.cwd()` for callers (e.g. tests) that build a manifest
+ * without a manifest-file location.
+ */
+async function buildConfigPlugin(raw, baseDir = process.cwd()) {
+    const manifest = exports.CONFIG_PLUGIN_MANIFEST.parse(raw);
+    const { metadata, spec } = manifest;
+    const logger = (0, logging_1.getLogger)({ name: `${metadata.siteId}-config-plugin` });
+    const bodySchema = (0, json_schema_to_zod_1.jsonSchemaToZod)(spec.request);
+    const responseSchema = (0, json_schema_to_zod_1.jsonSchemaToZod)(spec.response);
+    const extractSchema = (0, json_schema_to_zod_1.jsonSchemaToZod)(spec.extract.schema);
+    const executeHttp = spec.httpModule ? await loadHttpModule(spec.httpModule, baseDir) : undefined;
+    const hasUploadStep = spec.flow.steps.some((s) => typeof s !== "string" && s.upload === true);
+    const declaredFields = new Set(Object.keys(spec.request.properties ?? {}));
+    const plugin = {
+        meta: {
+            siteId: metadata.siteId,
+            displayName: metadata.displayName,
+            bodySchema,
+            responseSchema,
+            apiVersion: plugin_api_version_1.PLUGIN_API_VERSION,
+            ...(spec.routeOverride !== undefined && { routeOverride: spec.routeOverride }),
+            ...(spec.defaultBaseUrl !== undefined && { defaultBaseUrl: spec.defaultBaseUrl }),
+            ...(spec.taskTimeoutMs !== undefined && { taskTimeoutMs: spec.taskTimeoutMs }),
+            ...(spec.multipart !== undefined && { multipart: spec.multipart }),
+            ...(spec.advancedStealth !== undefined && { advancedStealth: spec.advancedStealth }),
+        },
+        ...(executeHttp && { executeHttp }),
+        async execute(rawPayload, session, context) {
+            const payload = rawPayload;
+            const { stagehand } = session;
+            const page = await (0, navigate_1.navigateActivePage)(stagehand, context.baseUrl, context.metricsCollector);
+            const steps = spec.flow.steps.map((s) => toHealingStep(s, payload, declaredFields));
+            const anthropic = context.config.scraper.anthropicApiKey
+                ? new sdk_1.default({ apiKey: context.config.scraper.anthropicApiKey })
+                : null;
+            await (0, flow_runner_1.runHealingFlow)({
+                stagehand,
+                page,
+                steps,
+                logger,
+                anthropic,
+                resumeFixture: buildResumeFixture(payload, hasUploadStep, spec.multipart ?? false),
+                submitEndpointPattern: spec.flow.submitEndpointPattern ?? null,
+                submittedStateSelectors: spec.flow.submittedStateSelectors ?? [],
+                requireSubmitEndpointMatch: spec.flow.requireSubmitEndpointMatch ?? false,
+                advanceTransitionBodyPattern: spec.flow.advanceTransitionBodyPattern ?? null,
+                successUrlFragments: spec.flow.successUrlFragments ?? [],
+                successPageTitleHints: spec.flow.successPageTitleHints ?? [],
+                ownBackendHostnames: spec.flow.ownBackendHostnames ?? [],
+                knownErrorClassPrefixes: spec.flow.knownErrorClassPrefixes ?? [],
+                wizardExitButtonLabels: spec.flow.wizardExitButtonLabels ?? [],
+            });
+            const data = await (0, stagehand_guard_1.guardedExtract)(stagehand, spec.extract.instruction, extractSchema);
+            return { data };
+        },
+    };
+    return plugin;
+}
+//# sourceMappingURL=config-plugin.js.map

package/dist/plugins/config-plugin.js.map

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

package/dist/plugins/discover.d.ts

@@ -0,0 +1,72 @@
+import type { AppConfig } from "../config";
+import type { SitePlugin } from "../site-plugin";
+/**
+ * Describes the outcome of attempting to load a single plugin specifier.
+ * Surfaced by `GET /v1/plugins` and emitted to startup logs.
+ */
+export interface PluginLoadRecord {
+    /** `null` when the module failed before `meta.siteId` was readable. */
+    siteId: string | null;
+    displayName: string | null;
+    /** Raw specifier from `BARNACLE_PLUGINS` or `"(builtin)"` for in-tree plugins. */
+    specifier: string;
+    /** Resolved absolute path or package entry point. `null` when resolution failed. */
+    resolvedPath: string | null;
+    route: string | null;
+    apiVersion: string | null;
+    status: "loaded" | "disabled";
+    /** Present only when `status === "disabled"`. */
+    reason?: string;
+}
+/**
+ * Aggregated result of loading a set of plugin specifiers, returned by
+ * `loadPlugins` and `loadAllPlugins`.
+ */
+export interface LoadPluginsResult {
+    plugins: SitePlugin<unknown, unknown>[];
+    report: PluginLoadRecord[];
+}
+/**
+ * Statically-registered in-tree plugins. Empty by default: this engine branch
+ * ships no site plugins, so operators register every plugin at runtime via
+ * `BARNACLE_PLUGINS` (compiled module specifiers) or `*.plugin.json` config
+ * manifests. Kept as a mutable array so tests can push a fixture builtin and so
+ * a downstream branch that vendors sites in-tree can repopulate it.
+ *
+ * @see loadAllPlugins for how built-ins and out-of-tree plugins are composed.
+ */
+export declare const BUILTIN_SITE_PLUGINS: SitePlugin<unknown, unknown>[];
+/**
+ * Resolves a plugin specifier to a `file://` URL string that `import()` can
+ * consume. Follows the Babel plugin-resolution model:
+ *
+ * - Leading `.` or `/` → filesystem path resolved relative to `baseDir`.
+ * - Anything else → npm package resolved via `createRequire` against
+ *   `baseDir/package.json`, so the operator's local `node_modules` wins.
+ *
+ * Throws with the specifier and baseDir in the message when resolution fails,
+ * so callers can build a descriptive disabled record without catching broadly.
+ */
+export declare function resolvePluginSpecifier(spec: string, baseDir: string): string;
+/**
+ * Loads and validates a list of plugin specifiers. Each specifier is resolved,
+ * imported, shape-validated, version-checked, and deduplication-checked before
+ * being added to the result. Failures produce disabled records; under `strict`
+ * mode the first failure re-throws immediately.
+ *
+ * `seenSiteIds` is mutated in place so the caller can pre-seed it with built-in
+ * ids before calling this function (built-ins always win collisions).
+ */
+export declare function loadPlugins(specifiers: readonly string[], opts: {
+    baseDir: string;
+    strict: boolean;
+    seenSiteIds: Set<string>;
+}): Promise<LoadPluginsResult>;
+/**
+ * Composes built-in and out-of-tree plugins into a single result. Built-ins
+ * are always listed first and their `siteId`s seed the deduplication set, so
+ * an out-of-tree plugin that collides with a built-in is disabled rather than
+ * replacing it.
+ */
+export declare function loadAllPlugins(cfg: AppConfig): Promise<LoadPluginsResult>;
+//# sourceMappingURL=discover.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/plugins/discover.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAI1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAIhD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,uEAAuE;IACvE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB,oFAAoF;IACpF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC9B,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;IACxC,MAAM,EAAE,gBAAgB,EAAE,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,EAAO,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAc5E;AA2HD;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,IAAI,EAAE;IACJ,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC1B,GACA,OAAO,CAAC,iBAAiB,CAAC,CAyD5B;AAuBD;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA6B/E"}

package/dist/plugins/discover.js

@@ -0,0 +1,265 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_SITE_PLUGINS = void 0;
+exports.resolvePluginSpecifier = resolvePluginSpecifier;
+exports.loadPlugins = loadPlugins;
+exports.loadAllPlugins = loadAllPlugins;
+const promises_1 = require("node:fs/promises");
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+const v4_1 = require("zod/v4");
+const logging_1 = require("../lib/logging");
+const config_plugin_1 = require("../plugins/config-plugin");
+const plugin_api_version_1 = require("../plugins/plugin-api-version");
+const logger = (0, logging_1.getLogger)({ name: "plugins/discover" });
+/**
+ * Statically-registered in-tree plugins. Empty by default: this engine branch
+ * ships no site plugins, so operators register every plugin at runtime via
+ * `BARNACLE_PLUGINS` (compiled module specifiers) or `*.plugin.json` config
+ * manifests. Kept as a mutable array so tests can push a fixture builtin and so
+ * a downstream branch that vendors sites in-tree can repopulate it.
+ *
+ * @see loadAllPlugins for how built-ins and out-of-tree plugins are composed.
+ */
+exports.BUILTIN_SITE_PLUGINS = [];
+/**
+ * Resolves a plugin specifier to a `file://` URL string that `import()` can
+ * consume. Follows the Babel plugin-resolution model:
+ *
+ * - Leading `.` or `/` → filesystem path resolved relative to `baseDir`.
+ * - Anything else → npm package resolved via `createRequire` against
+ *   `baseDir/package.json`, so the operator's local `node_modules` wins.
+ *
+ * Throws with the specifier and baseDir in the message when resolution fails,
+ * so callers can build a descriptive disabled record without catching broadly.
+ */
+function resolvePluginSpecifier(spec, baseDir) {
+    if (spec.startsWith(".") || spec.startsWith("/")) {
+        return (0, node_url_1.pathToFileURL)(node_path_1.default.resolve(baseDir, spec)).href;
+    }
+    const req = (0, node_module_1.createRequire)((0, node_url_1.pathToFileURL)(node_path_1.default.join(baseDir, "package.json")).href);
+    try {
+        const resolved = req.resolve(spec);
+        return (0, node_url_1.pathToFileURL)(resolved).href;
+    }
+    catch (err) {
+        throw new Error(`cannot resolve plugin specifier ${JSON.stringify(spec)} from baseDir ${JSON.stringify(baseDir)}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Returns true when `s` looks like a Zod schema without relying on `instanceof`. */
+function looksLikeZodSchema(s) {
+    return (typeof s?.safeParse === "function" &&
+        typeof s?.parse === "function");
+}
+const metaSchema = v4_1.z
+    .object({
+    siteId: v4_1.z.string().min(1),
+    displayName: v4_1.z.string().min(1),
+    routeOverride: v4_1.z.string().optional(),
+    defaultBaseUrl: v4_1.z.string().optional(),
+    taskTimeoutMs: v4_1.z.number().optional(),
+    multipart: v4_1.z.boolean().optional(),
+    advancedStealth: v4_1.z.boolean().optional(),
+    apiVersion: v4_1.z.string().optional(),
+    extraRoutes: v4_1.z.array(v4_1.z.unknown()).optional(),
+})
+    .passthrough();
+/**
+ * Duck-typed shape validation for an untrusted module export. Uses Zod for
+ * `meta` field presence/types, but checks `bodySchema`/`responseSchema` via
+ * duck-typing so plugins that bundle their own zod copy are not falsely
+ * rejected.
+ */
+function validatePluginShape(raw) {
+    const obj = raw;
+    metaSchema.parse(obj.meta);
+    if (!looksLikeZodSchema(obj.meta?.bodySchema)) {
+        throw new Error("meta.bodySchema must be a Zod schema");
+    }
+    if (!looksLikeZodSchema(obj.meta?.responseSchema)) {
+        throw new Error("meta.responseSchema must be a Zod schema");
+    }
+    if (typeof obj.execute !== "function") {
+        throw new Error("plugin.execute must be a function");
+    }
+    return raw;
+}
+/**
+ * Parses the leading integer from a semver string, e.g. `"1.2.3"` → `1`.
+ * Returns `null` when the string cannot be parsed as a major version.
+ */
+function parseMajorVersion(version) {
+    const match = /^(\d+)/.exec(version.trim());
+    return match ? parseInt(match[1] ?? "0", 10) : null;
+}
+/**
+ * Creates a disabled `PluginLoadRecord` from minimal information. Used when
+ * a plugin fails at any stage of loading.
+ */
+function disabledRecord(opts) {
+    const meta = opts.plugin?.meta;
+    return {
+        siteId: meta?.siteId ?? null,
+        displayName: meta?.displayName ?? null,
+        specifier: opts.specifier,
+        resolvedPath: opts.resolvedPath,
+        route: meta ? (meta.routeOverride ?? `/v1/${meta.siteId}/run`) : null,
+        apiVersion: meta?.apiVersion ?? null,
+        status: "disabled",
+        reason: opts.reason,
+    };
+}
+/**
+ * Normalizes the three supported module export shapes into a single object.
+ *
+ * When CJS `module.exports = { plugin }` is loaded via dynamic `import()`,
+ * Node exposes the entire exports object as `m.default` AND hoists named
+ * exports so `m.plugin` is the actual plugin. We must resolve the `plugin`
+ * named export before falling back to `default`, otherwise we'd return the
+ * wrapper `{ plugin }` object which fails shape validation.
+ *
+ * Resolution order:
+ *   1. `m.plugin` — named `{ plugin }` export (CJS or ESM)
+ *   2. `m.default` — ESM default export
+ *   3. `m` itself — CJS `module.exports = plugin` (no default wrapping)
+ */
+function normalizeExport(mod) {
+    const m = mod;
+    return m.plugin ?? m.default ?? mod;
+}
+/**
+ * Produces a raw plugin object from a resolved `file://` specifier. A `.json`
+ * specifier is a declarative manifest — read, parse, and run through
+ * `buildConfigPlugin` to synthesize a `SitePlugin` (no per-site TypeScript, no
+ * compile step). Anything else is a compiled module `import()`ed as before. The
+ * synthesized object still flows through the same `validatePluginShape` gate as
+ * a module plugin, so the two sources share one validation path.
+ *
+ * `baseDir` is threaded into `buildConfigPlugin` so a manifest's relative
+ * `spec.httpModule` escape-hatch path resolves against the operator's plugin
+ * directory, consistent with how module specifiers themselves are resolved.
+ */
+async function loadRawPlugin(resolvedPath, baseDir) {
+    if (resolvedPath.endsWith(".json")) {
+        const manifest = JSON.parse(await (0, promises_1.readFile)((0, node_url_1.fileURLToPath)(resolvedPath), "utf8"));
+        return await (0, config_plugin_1.buildConfigPlugin)(manifest, baseDir);
+    }
+    const mod = await import(resolvedPath);
+    return normalizeExport(mod);
+}
+/**
+ * Loads and validates a list of plugin specifiers. Each specifier is resolved,
+ * imported, shape-validated, version-checked, and deduplication-checked before
+ * being added to the result. Failures produce disabled records; under `strict`
+ * mode the first failure re-throws immediately.
+ *
+ * `seenSiteIds` is mutated in place so the caller can pre-seed it with built-in
+ * ids before calling this function (built-ins always win collisions).
+ */
+async function loadPlugins(specifiers, opts) {
+    const { baseDir, strict, seenSiteIds } = opts;
+    const plugins = [];
+    const report = [];
+    for (const spec of specifiers) {
+        let resolvedPath = null;
+        let plugin;
+        try {
+            resolvedPath = resolvePluginSpecifier(spec, baseDir);
+            const raw = await loadRawPlugin(resolvedPath, baseDir);
+            plugin = validatePluginShape(raw);
+            const meta = plugin.meta;
+            if (meta.apiVersion !== undefined) {
+                const pluginMajor = parseMajorVersion(meta.apiVersion);
+                const coreMajor = parseMajorVersion(plugin_api_version_1.PLUGIN_API_VERSION);
+                if (pluginMajor === null || coreMajor === null || pluginMajor !== coreMajor) {
+                    const reason = `apiVersion ${meta.apiVersion} incompatible with core ${plugin_api_version_1.PLUGIN_API_VERSION}`;
+                    logger.warn(`${spec}: ${reason}`);
+                    report.push(disabledRecord({ specifier: spec, resolvedPath, plugin, reason }));
+                    continue;
+                }
+            }
+            if (seenSiteIds.has(meta.siteId)) {
+                const reason = `duplicate siteId "${meta.siteId}" — already registered`;
+                logger.warn(`${spec}: ${reason}`);
+                report.push(disabledRecord({ specifier: spec, resolvedPath, plugin, reason }));
+                continue;
+            }
+            seenSiteIds.add(meta.siteId);
+            plugins.push(plugin);
+            logger.info(`${spec}: loaded siteId "${meta.siteId}" (${plugin_api_version_1.PLUGIN_API_VERSION})`);
+            report.push({
+                siteId: meta.siteId,
+                displayName: meta.displayName,
+                specifier: spec,
+                resolvedPath,
+                route: meta.routeOverride ?? `/v1/${meta.siteId}/run`,
+                apiVersion: meta.apiVersion ?? null,
+                status: "loaded",
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            logger.warn(`${spec}: failed to load — ${reason}`);
+            report.push(disabledRecord({ specifier: spec, resolvedPath, plugin, reason }));
+            if (strict)
+                throw err;
+        }
+    }
+    return { plugins, report };
+}
+/**
+ * Scans `configDir` for `*.plugin.json` manifests and returns their absolute
+ * paths as loader specifiers. Best-effort: an unreadable directory yields an
+ * empty list with a warn log so a misconfigured `BARNACLE_PLUGINS_CONFIG_DIR`
+ * never crashes boot — the same failure-isolation posture as a bad plugin.
+ */
+async function discoverConfigManifests(configDir) {
+    try {
+        const entries = await (0, promises_1.readdir)(configDir);
+        return entries
+            .filter((name) => name.endsWith(".plugin.json"))
+            .sort()
+            .map((name) => node_path_1.default.resolve(configDir, name));
+    }
+    catch (err) {
+        logger.warn(`plugin config dir ${JSON.stringify(configDir)} not scannable — ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+}
+/**
+ * Composes built-in and out-of-tree plugins into a single result. Built-ins
+ * are always listed first and their `siteId`s seed the deduplication set, so
+ * an out-of-tree plugin that collides with a built-in is disabled rather than
+ * replacing it.
+ */
+async function loadAllPlugins(cfg) {
+    const builtins = exports.BUILTIN_SITE_PLUGINS;
+    const seenSiteIds = new Set(builtins.map((p) => p.meta.siteId));
+    const builtinReport = builtins.map((p) => ({
+        siteId: p.meta.siteId,
+        displayName: p.meta.displayName,
+        specifier: "(builtin)",
+        resolvedPath: null,
+        route: p.meta.routeOverride ?? `/v1/${p.meta.siteId}/run`,
+        apiVersion: p.meta.apiVersion ?? null,
+        status: "loaded",
+    }));
+    const configManifests = cfg.plugins.configDir
+        ? await discoverConfigManifests(cfg.plugins.configDir)
+        : [];
+    const specifiers = [...cfg.plugins.specifiers, ...configManifests];
+    const { plugins, report } = await loadPlugins(specifiers, {
+        baseDir: cfg.plugins.baseDir,
+        strict: cfg.plugins.strict,
+        seenSiteIds,
+    });
+    return {
+        plugins: [...builtins, ...plugins],
+        report: [...builtinReport, ...report],
+    };
+}
+//# sourceMappingURL=discover.js.map

package/dist/plugins/discover.js.map

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

package/dist/plugins/json-schema-to-zod.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+import { z } from "zod/v4";
+/** Thrown when a manifest schema uses a JSON-Schema construct this converter does not support. */
+export declare class UnsupportedJsonSchemaError extends Error {
+    constructor(message: string);
+}
+/**
+ * Recursive shape of the JSON-Schema subset this converter accepts. Validated
+ * structurally by {@link JSON_SCHEMA_NODE} before conversion so a malformed
+ * manifest schema is rejected with a Zod error rather than a runtime crash
+ * mid-conversion.
+ */
+export interface JsonSchemaNode {
+    type?: "object" | "string" | "number" | "integer" | "boolean" | "array";
+    properties?: Record<string, JsonSchemaNode>;
+    required?: string[];
+    items?: JsonSchemaNode;
+    enum?: string[];
+    format?: string;
+    description?: string;
+}
+/**
+ * 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.
+ */
+export declare function jsonSchemaToZod(schema: unknown): z.ZodTypeAny;
+//# sourceMappingURL=json-schema-to-zod.d.ts.map

package/dist/plugins/json-schema-to-zod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-schema-to-zod.d.ts","sourceRoot":"","sources":["../../src/plugins/json-schema-to-zod.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,kGAAkG;AAClG,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC5C,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAgDD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,CAAC,CAAC,UAAU,CAQ7D"}