@opencraw/driver 0.0.0-stage → 0.1.0

package/dist/main.esm.js

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+
+// src/main.ts
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/server/serve-driver.use-case.ts
+import { once } from "node:events";
+
+// src/protocol/driver-message.contract.ts
+import { calloutRequestSchema, calloutResponseSchema } from "@opencraw/core";
+import { z } from "zod";
+var PROTOCOL_VERSION = "1.0.0";
+var recipeObject = z.record(z.string(), z.unknown());
+var recipeSource = {
+  paths: z.array(z.string()).min(1).optional(),
+  recipes: z.array(recipeObject).min(1).optional()
+};
+var initializeParamsSchema = z.strictObject({
+  clientName: z.string().min(1),
+  clientVersion: z.string().min(1),
+  protocolVersion: z.string().regex(/^\d+\.\d+\.\d+$/)
+});
+var initializeResultSchema = z.strictObject({
+  driverVersion: z.string(),
+  protocolVersion: z.string(),
+  methods: z.array(z.string())
+});
+var validateParamsSchema = z.strictObject({ ...recipeSource, only: z.array(z.string()).optional() });
+var issueSchema = z.strictObject({ source: z.string().optional(), recipeId: z.string().optional(), path: z.string(), message: z.string() });
+var validateResultSchema = z.strictObject({
+  ok: z.boolean(),
+  /** The input recipes that would run, when ok. */
+  inputs: z.array(z.string()),
+  /** Every hook the recipes call, which a `run` must serve. */
+  hooks: z.array(z.string()),
+  issues: z.array(issueSchema)
+});
+var runParamsSchema = z.strictObject({
+  ...recipeSource,
+  only: z.array(z.string()).optional(),
+  /** A file to write the records to, its extension naming the format; without it, each record is sent as a `record` notification. */
+  out: z.string().optional(),
+  append: z.boolean().optional(),
+  resume: z.boolean().optional(),
+  dryRun: z.boolean().optional(),
+  parallel: z.number().int().min(1).max(16).optional(),
+  browser: z.strictObject({ headless: z.boolean().optional(), executablePath: z.string().optional(), ignoreHTTPSErrors: z.boolean().optional() }).optional(),
+  /** The hooks the client answers itself: each becomes a `callout` request to the client when a recipe calls it. */
+  hooks: z.array(z.string()).optional()
+});
+var runResultSchema = z.strictObject({ runId: z.string() });
+var cancelParamsSchema = z.strictObject({ runId: z.string() });
+var cancelResultSchema = z.strictObject({ cancelled: z.boolean() });
+var shutdownResultSchema = z.strictObject({});
+var eventParamsSchema = z.strictObject({ runId: z.string(), event: z.record(z.string(), z.unknown()) });
+var recordParamsSchema = z.strictObject({ runId: z.string(), recipeId: z.string(), key: z.string().nullable(), data: z.record(z.string(), z.unknown()) });
+var finishedParamsSchema = z.strictObject({
+  runId: z.string(),
+  /** The crawl report (`CrawlReport`), absent when the run could not start. */
+  report: z.record(z.string(), z.unknown()).optional(),
+  /** Why the run could not start, or stopped as a whole. */
+  error: z.string().optional()
+});
+var calloutParamsSchema = z.strictObject({ runId: z.string(), request: calloutRequestSchema });
+
+// src/protocol/driver-json-schema.mapper.ts
+import { z as z2 } from "zod";
+
+// src/session/run-session.use-case.ts
+import { createCrawler, fileSink, RecipeSet } from "@opencraw/core";
+
+// src/callout-bridge/client-hooks.client.ts
+import { calloutHook, calloutResponseSchema as calloutResponseSchema2 } from "@opencraw/core";
+function clientTransport(hookName, runId, ask) {
+  return {
+    label: `client hook ${hookName}`,
+    call: async (request) => calloutResponseSchema2.parse(await ask("callout", { runId, request }))
+  };
+}
+function clientHooks(names, runId, ask) {
+  return Object.fromEntries(names.map((name) => [name, calloutHook(name, clientTransport(name, runId, ask))]));
+}
+
+// src/session/recipe-loading.use-case.ts
+import { loadForRun } from "@opencraw/cli";
+import { hookUses, RecipeBindingError, RecipeValidationError } from "@opencraw/core";
+function sourceOf(params) {
+  if (params.paths === void 0 === (params.recipes === void 0)) throw new Error('give exactly one of "paths" or "recipes"');
+  return params.paths ?? params.recipes ?? [];
+}
+async function loadRecipes(params) {
+  return await loadForRun(sourceOf(params), params.only ?? []);
+}
+function hooksOf(set) {
+  return [...new Set(set.inputs.flatMap((input) => hookUses(input).map((use) => use.name)))].sort((x, y) => x.localeCompare(y));
+}
+async function validateRecipes(params) {
+  try {
+    const set = await loadRecipes(params);
+    return { ok: true, inputs: set.inputs.map((input) => input.id), hooks: hooksOf(set), issues: [] };
+  } catch (error) {
+    if (error instanceof RecipeValidationError) return { ok: false, inputs: [], hooks: [], issues: error.issues.map((issue) => ({ source: error.source, path: issue.path, message: issue.message })) };
+    if (error instanceof RecipeBindingError) return { ok: false, inputs: [], hooks: [], issues: error.issues.map((issue) => ({ recipeId: issue.recipeId, path: issue.path, message: issue.message })) };
+    return { ok: false, inputs: [], hooks: [], issues: [{ path: "", message: error instanceof Error ? error.message : String(error) }] };
+  }
+}
+
+// src/session/streaming-sink.repository.ts
+function streamingSink() {
+  let written = 0;
+  return {
+    open: async () => {
+    },
+    write: async () => {
+      written += 1;
+    },
+    close: async () => ({ written })
+  };
+}
+
+// src/session/run-session.use-case.ts
+function runSessions(notify, ask) {
+  const running = /* @__PURE__ */ new Map();
+  let next = 1;
+  const crawl = async (runId, crawler, set) => {
+    try {
+      const report = await crawler.run(set);
+      notify("finished", { runId, report });
+    } catch (error) {
+      notify("finished", { runId, error: error instanceof Error ? error.message : String(error) });
+    } finally {
+      running.delete(runId);
+      await crawler.close();
+    }
+  };
+  return {
+    start: async (params) => {
+      const loaded = await loadRecipes(params);
+      const set = params.dryRun === true ? new RecipeSet(loaded.output, loaded.inputs.map((input) => ({ ...input, limits: { ...input.limits, maxRecords: 1 } }))) : loaded;
+      const runId = `run-${next++}`;
+      const crawler = createCrawler({
+        sink: params.out === void 0 ? streamingSink() : fileSink(params.out, { append: params.append, browser: { executablePath: params.browser?.executablePath } }),
+        hooks: clientHooks(params.hooks ?? [], runId, ask),
+        parallel: params.parallel,
+        resume: params.resume,
+        debug: params.dryRun,
+        browser: { headless: params.browser?.headless ?? true, executablePath: params.browser?.executablePath, ignoreHTTPSErrors: params.browser?.ignoreHTTPSErrors },
+        onEvent: (event) => {
+          notify("event", { runId, event });
+          if (event.type === "record:emit" && params.out === void 0) notify("record", { runId, recipeId: event.recipeId, key: event.key, data: event.data });
+        }
+      });
+      running.set(runId, crawler);
+      void crawl(runId, crawler, set);
+      return runId;
+    },
+    cancel: async (runId) => {
+      const crawler = running.get(runId);
+      if (crawler === void 0) return false;
+      running.delete(runId);
+      await crawler.close();
+      return true;
+    },
+    closeAll: async () => {
+      const crawlers = running.values().toArray();
+      running.clear();
+      await Promise.all(crawlers.map(async (crawler) => {
+        await crawler.close();
+      }));
+    }
+  };
+}
+
+// src/transport/line-channel.client.ts
+import { createInterface } from "node:readline";
+
+// src/transport/json-rpc.contract.ts
+var RPC_ERRORS = {
+  parse: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internal: -32603,
+  /** A failure the caller must act on: the message says what to do. */
+  server: -32e3
+};
+var RpcFailure = class extends Error {
+  code;
+  data;
+  constructor(code, message, data) {
+    super(message);
+    this.name = "RpcFailure";
+    this.code = code;
+    this.data = data;
+  }
+};
+
+// src/transport/line-channel.client.ts
+var isRequestId = (id) => typeof id === "number" || typeof id === "string";
+function openLineChannel(input, output, handle) {
+  const pending = /* @__PURE__ */ new Map();
+  const answering = /* @__PURE__ */ new Set();
+  const track = (answered) => {
+    answering.add(answered);
+    void (async () => {
+      try {
+        await answered;
+      } finally {
+        answering.delete(answered);
+      }
+    })();
+  };
+  let nextId = 1;
+  const write = (message) => {
+    output.write(`${JSON.stringify(message)}
+`);
+  };
+  const fail = (id, error) => {
+    write({ jsonrpc: "2.0", id, error });
+  };
+  const answer = async (message) => {
+    const method = message.method;
+    try {
+      const result = await handle(method, message.params);
+      if (isRequestId(message.id)) write({ jsonrpc: "2.0", id: message.id, result: result ?? null });
+    } catch (error) {
+      if (!isRequestId(message.id)) return;
+      if (error instanceof RpcFailure) fail(message.id, { code: error.code, message: error.message, ...error.data !== void 0 && { data: error.data } });
+      else fail(message.id, { code: RPC_ERRORS.server, message: error instanceof Error ? error.message : String(error) });
+    }
+  };
+  const settle = (message) => {
+    const waiting = typeof message.id === "number" ? pending.get(message.id) : void 0;
+    if (waiting === void 0) return;
+    pending.delete(message.id);
+    if (message.error === void 0) waiting.resolve(message.result);
+    else waiting.reject(new RpcFailure(message.error.code, message.error.message, message.error.data));
+  };
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  lines.on("line", (line) => {
+    if (line.trim() === "") return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      fail(null, { code: RPC_ERRORS.parse, message: "the line is not JSON" });
+      return;
+    }
+    if (message === null || typeof message !== "object" || message.jsonrpc !== "2.0") {
+      fail(isRequestId(message?.id) ? message.id : null, { code: RPC_ERRORS.invalidRequest, message: "not a JSON-RPC 2.0 message" });
+      return;
+    }
+    if (typeof message.method === "string") track(answer(message));
+    else settle(message);
+  });
+  const closed = new Promise((resolve) => {
+    lines.on("close", () => {
+      for (const waiting of pending.values()) waiting.reject(new Error("the client closed the channel"));
+      pending.clear();
+      resolve();
+    });
+  });
+  return {
+    request: async (method, params) => await new Promise((resolve, reject) => {
+      const id = nextId++;
+      pending.set(id, { resolve, reject });
+      write({ jsonrpc: "2.0", id, method, params });
+    }),
+    notify: (method, params) => {
+      write({ jsonrpc: "2.0", method, params });
+    },
+    closed,
+    drained: async () => {
+      while (answering.size > 0) await Promise.allSettled(answering);
+    }
+  };
+}
+
+// src/server/serve-driver.use-case.ts
+var METHODS = ["initialize", "validate", "run", "cancel", "shutdown"];
+var major = (version) => version.split(".", 1)[0];
+function parsed(schema, params) {
+  const result = schema.safeParse(params ?? {});
+  if (!result.success) throw new RpcFailure(RPC_ERRORS.invalidParams, result.error.issues.map((issue) => `${issue.path.join(".") || "(params)"}: ${issue.message}`).join("; "), result.error.issues);
+  return result.data;
+}
+async function serveDriver(input, output, identity) {
+  let initialized = false;
+  const stopping = new AbortController();
+  const channel = openLineChannel(input, output, async (method, params) => {
+    if (method === "initialize") {
+      const hello = parsed(initializeParamsSchema, params);
+      if (major(hello.protocolVersion) !== major(PROTOCOL_VERSION)) throw new RpcFailure(RPC_ERRORS.server, `this driver speaks protocol ${PROTOCOL_VERSION}; ${hello.clientName} ${hello.clientVersion} asked for ${hello.protocolVersion}: use a client for protocol ${major(PROTOCOL_VERSION)}.x`);
+      initialized = true;
+      const result = { driverVersion: identity.driverVersion, protocolVersion: PROTOCOL_VERSION, methods: METHODS };
+      return result;
+    }
+    if (!METHODS.includes(method)) throw new RpcFailure(RPC_ERRORS.methodNotFound, `no method "${method}": the driver has ${METHODS.join(", ")}`);
+    if (!initialized) throw new RpcFailure(RPC_ERRORS.server, "call initialize first");
+    if (method === "validate") return await validateRecipes(parsed(validateParamsSchema, params));
+    if (method === "run") return { runId: await sessions.start(parsed(runParamsSchema, params)) };
+    if (method === "cancel") return { cancelled: await sessions.cancel(parsed(cancelParamsSchema, params).runId) };
+    await sessions.closeAll();
+    setImmediate(() => {
+      stopping.abort();
+    });
+    return {};
+  });
+  const sessions = runSessions(channel.notify, channel.request);
+  await Promise.race([channel.closed, once(stopping.signal, "abort")]);
+  await channel.drained();
+  await sessions.closeAll();
+}
+
+// src/main.ts
+console.log = console.error;
+console.info = console.error;
+function driverVersion() {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+      if (manifest.name === "@opencraw/driver" && manifest.version !== void 0) return manifest.version;
+    } catch {
+    }
+    dir = dirname(dir);
+  }
+  return "0.0.0";
+}
+await serveDriver(process.stdin, process.stdout, { driverVersion: driverVersion() });
+process.exit(0);
+//# sourceMappingURL=main.esm.js.map

package/dist/src/callout-bridge/client-hooks.client.d.ts

@@ -0,0 +1,19 @@
+import type { CalloutTransport, HookMap } from '@opencraw/core';
+/** Sends one request to the client and waits for its answer: the channel's `request`. */
+export type AskClient = (method: string, params: unknown) => Promise<unknown>;
+/**
+ * A transport whose handler is the client: each call is a `callout` request carrying core's own
+ * `CalloutRequest`, and the client answers with a `CalloutResponse`, so `pending` and idempotency keys
+ * work exactly as they do for a command or an HTTP hook.
+ */
+export declare function clientTransport(hookName: string, runId: string, ask: AskClient): CalloutTransport;
+/**
+ * The hooks a run's client serves, each answered by the client over the channel.
+ *
+ * @param names - The hooks the client said it serves.
+ * @param runId - The run they belong to, sent with every callout.
+ * @param ask - The channel's request.
+ * @returns A hook map for `createCrawler`.
+ */
+export declare function clientHooks(names: readonly string[], runId: string, ask: AskClient): HookMap;
+//# sourceMappingURL=client-hooks.client.d.ts.map

package/dist/src/callout-bridge/index.d.ts

@@ -0,0 +1,3 @@
+export { clientHooks, clientTransport } from './client-hooks.client.js';
+export type { AskClient } from './client-hooks.client.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+export { serveDriver } from './server/index.js';
+export type { DriverIdentity } from './server/index.js';
+export { PROTOCOL_VERSION, MESSAGES, driverProtocolJsonSchema, initializeParamsSchema, initializeResultSchema, validateParamsSchema, validateResultSchema, runParamsSchema, runResultSchema, cancelParamsSchema, cancelResultSchema, eventParamsSchema, recordParamsSchema, finishedParamsSchema, calloutParamsSchema, calloutResultSchema, } from './protocol/index.js';
+export type { InitializeParams, InitializeResult, ValidateParams, ValidateResult, RunParams, RunResult, CancelParams, CancelResult, EventParams, RecordParams, FinishedParams, CalloutParams, } from './protocol/index.js';
+export { openLineChannel, RPC_ERRORS, RpcFailure } from './transport/index.js';
+export type { LineChannel, RequestHandler, RpcError, RpcMessage } from './transport/index.js';
+export { runSessions, validateRecipes, streamingSink } from './session/index.js';
+export type { RunSessions, NotifyClient } from './session/index.js';
+export { clientHooks } from './callout-bridge/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/main.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/src/protocol/driver-json-schema.mapper.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The driver protocol as one JSON Schema document (`schemas/driver-protocol.schema.json`): every method's
+ * params and result, every notification's params, by name under `$defs`. A client in another language
+ * generates its models from it instead of typing them by hand.
+ *
+ * @returns A draft 2020-12 document.
+ */
+export declare function driverProtocolJsonSchema(): Record<string, unknown>;
+//# sourceMappingURL=driver-json-schema.mapper.d.ts.map

package/dist/src/protocol/driver-message.contract.d.ts

@@ -0,0 +1,251 @@
+import { z } from 'zod';
+/**
+ * The driver protocol's version, separate from the package's: a client pins a major and the driver refuses
+ * another. Additions (methods, optional fields) raise the minor; anything a client could break on, the major.
+ */
+export declare const PROTOCOL_VERSION = "1.0.0";
+export declare const initializeParamsSchema: z.ZodObject<{
+    clientName: z.ZodString;
+    clientVersion: z.ZodString;
+    protocolVersion: z.ZodString;
+}, z.core.$strict>;
+export type InitializeParams = z.infer<typeof initializeParamsSchema>;
+export declare const initializeResultSchema: z.ZodObject<{
+    driverVersion: z.ZodString;
+    protocolVersion: z.ZodString;
+    methods: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type InitializeResult = z.infer<typeof initializeResultSchema>;
+export declare const validateParamsSchema: z.ZodObject<{
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    recipes: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type ValidateParams = z.infer<typeof validateParamsSchema>;
+export declare const validateResultSchema: z.ZodObject<{
+    ok: z.ZodBoolean;
+    inputs: z.ZodArray<z.ZodString>;
+    hooks: z.ZodArray<z.ZodString>;
+    issues: z.ZodArray<z.ZodObject<{
+        source: z.ZodOptional<z.ZodString>;
+        recipeId: z.ZodOptional<z.ZodString>;
+        path: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ValidateResult = z.infer<typeof validateResultSchema>;
+export declare const runParamsSchema: z.ZodObject<{
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    recipes: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    out: z.ZodOptional<z.ZodString>;
+    append: z.ZodOptional<z.ZodBoolean>;
+    resume: z.ZodOptional<z.ZodBoolean>;
+    dryRun: z.ZodOptional<z.ZodBoolean>;
+    parallel: z.ZodOptional<z.ZodNumber>;
+    browser: z.ZodOptional<z.ZodObject<{
+        headless: z.ZodOptional<z.ZodBoolean>;
+        executablePath: z.ZodOptional<z.ZodString>;
+        ignoreHTTPSErrors: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    hooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type RunParams = z.infer<typeof runParamsSchema>;
+export declare const runResultSchema: z.ZodObject<{
+    runId: z.ZodString;
+}, z.core.$strict>;
+export type RunResult = z.infer<typeof runResultSchema>;
+export declare const cancelParamsSchema: z.ZodObject<{
+    runId: z.ZodString;
+}, z.core.$strict>;
+export type CancelParams = z.infer<typeof cancelParamsSchema>;
+export declare const cancelResultSchema: z.ZodObject<{
+    cancelled: z.ZodBoolean;
+}, z.core.$strict>;
+export type CancelResult = z.infer<typeof cancelResultSchema>;
+export declare const shutdownResultSchema: z.ZodObject<{}, z.core.$strict>;
+/** Every crawl event, as core reports it (`CrawlEvent`); its shape is core's, versioned with core. */
+export declare const eventParamsSchema: z.ZodObject<{
+    runId: z.ZodString;
+    event: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export type EventParams = z.infer<typeof eventParamsSchema>;
+export declare const recordParamsSchema: z.ZodObject<{
+    runId: z.ZodString;
+    recipeId: z.ZodString;
+    key: z.ZodNullable<z.ZodString>;
+    data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export type RecordParams = z.infer<typeof recordParamsSchema>;
+export declare const finishedParamsSchema: z.ZodObject<{
+    runId: z.ZodString;
+    report: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    error: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type FinishedParams = z.infer<typeof finishedParamsSchema>;
+/** A hook the client serves: core's own callout request, answered with core's callout response. */
+export declare const calloutParamsSchema: z.ZodObject<{
+    runId: z.ZodString;
+    request: z.ZodObject<{
+        kind: z.ZodEnum<{
+            access: "access";
+            captcha: "captcha";
+            hook: "hook";
+        }>;
+        name: z.ZodString;
+        input: z.ZodOptional<z.ZodUnknown>;
+        args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        context: z.ZodObject<{
+            recipeId: z.ZodString;
+            scope: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strict>;
+        idempotencyKey: z.ZodString;
+        callback: z.ZodOptional<z.ZodObject<{
+            url: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type CalloutParams = z.infer<typeof calloutParamsSchema>;
+export declare const calloutResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    status: z.ZodLiteral<"ok">;
+    output: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"error">;
+    error: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    status: z.ZodLiteral<"pending">;
+    retryAfterMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>], "status">;
+/** Every method and notification, by name: what the generated schema and the clients' models are made from. */
+export declare const MESSAGES: {
+    readonly initialize: {
+        readonly direction: 'client-to-driver';
+        readonly params: z.ZodObject<{
+            clientName: z.ZodString;
+            clientVersion: z.ZodString;
+            protocolVersion: z.ZodString;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            driverVersion: z.ZodString;
+            protocolVersion: z.ZodString;
+            methods: z.ZodArray<z.ZodString>;
+        }, z.core.$strict>;
+    };
+    readonly validate: {
+        readonly direction: 'client-to-driver';
+        readonly params: z.ZodObject<{
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            recipes: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            ok: z.ZodBoolean;
+            inputs: z.ZodArray<z.ZodString>;
+            hooks: z.ZodArray<z.ZodString>;
+            issues: z.ZodArray<z.ZodObject<{
+                source: z.ZodOptional<z.ZodString>;
+                recipeId: z.ZodOptional<z.ZodString>;
+                path: z.ZodString;
+                message: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+    };
+    readonly run: {
+        readonly direction: 'client-to-driver';
+        readonly params: z.ZodObject<{
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            recipes: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            out: z.ZodOptional<z.ZodString>;
+            append: z.ZodOptional<z.ZodBoolean>;
+            resume: z.ZodOptional<z.ZodBoolean>;
+            dryRun: z.ZodOptional<z.ZodBoolean>;
+            parallel: z.ZodOptional<z.ZodNumber>;
+            browser: z.ZodOptional<z.ZodObject<{
+                headless: z.ZodOptional<z.ZodBoolean>;
+                executablePath: z.ZodOptional<z.ZodString>;
+                ignoreHTTPSErrors: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strict>>;
+            hooks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            runId: z.ZodString;
+        }, z.core.$strict>;
+    };
+    readonly cancel: {
+        readonly direction: 'client-to-driver';
+        readonly params: z.ZodObject<{
+            runId: z.ZodString;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            cancelled: z.ZodBoolean;
+        }, z.core.$strict>;
+    };
+    readonly shutdown: {
+        readonly direction: 'client-to-driver';
+        readonly params: undefined;
+        readonly result: z.ZodObject<{}, z.core.$strict>;
+    };
+    readonly callout: {
+        readonly direction: 'driver-to-client';
+        readonly params: z.ZodObject<{
+            runId: z.ZodString;
+            request: z.ZodObject<{
+                kind: z.ZodEnum<{
+                    access: "access";
+                    captcha: "captcha";
+                    hook: "hook";
+                }>;
+                name: z.ZodString;
+                input: z.ZodOptional<z.ZodUnknown>;
+                args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                context: z.ZodObject<{
+                    recipeId: z.ZodString;
+                    scope: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                }, z.core.$strict>;
+                idempotencyKey: z.ZodString;
+                callback: z.ZodOptional<z.ZodObject<{
+                    url: z.ZodString;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        readonly result: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            status: z.ZodLiteral<"ok">;
+            output: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strict>, z.ZodObject<{
+            status: z.ZodLiteral<"error">;
+            error: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            status: z.ZodLiteral<"pending">;
+            retryAfterMs: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>], "status">;
+    };
+    readonly event: {
+        readonly direction: 'driver-to-client';
+        readonly params: z.ZodObject<{
+            runId: z.ZodString;
+            event: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strict>;
+        readonly result: undefined;
+    };
+    readonly record: {
+        readonly direction: 'driver-to-client';
+        readonly params: z.ZodObject<{
+            runId: z.ZodString;
+            recipeId: z.ZodString;
+            key: z.ZodNullable<z.ZodString>;
+            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strict>;
+        readonly result: undefined;
+    };
+    readonly finished: {
+        readonly direction: 'driver-to-client';
+        readonly params: z.ZodObject<{
+            runId: z.ZodString;
+            report: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            error: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        readonly result: undefined;
+    };
+};
+//# sourceMappingURL=driver-message.contract.d.ts.map

package/dist/src/protocol/index.d.ts

@@ -0,0 +1,4 @@
+export { PROTOCOL_VERSION, MESSAGES, initializeParamsSchema, initializeResultSchema, validateParamsSchema, validateResultSchema, runParamsSchema, runResultSchema, cancelParamsSchema, cancelResultSchema, shutdownResultSchema, eventParamsSchema, recordParamsSchema, finishedParamsSchema, calloutParamsSchema, calloutResultSchema, } from './driver-message.contract.js';
+export type { InitializeParams, InitializeResult, ValidateParams, ValidateResult, RunParams, RunResult, CancelParams, CancelResult, EventParams, RecordParams, FinishedParams, CalloutParams, } from './driver-message.contract.js';
+export { driverProtocolJsonSchema } from './driver-json-schema.mapper.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/server/index.d.ts

@@ -0,0 +1,3 @@
+export { serveDriver } from './serve-driver.use-case.js';
+export type { DriverIdentity } from './serve-driver.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/server/serve-driver.use-case.d.ts

@@ -0,0 +1,17 @@
+import type { Readable, Writable } from 'node:stream';
+/** What the driver says about itself in `initialize`. */
+export interface DriverIdentity {
+    driverVersion: string;
+}
+/**
+ * Serves the driver protocol on a stream pair until the client closes its end or asks for `shutdown`.
+ * Every method but `initialize` is refused until the client has initialized with a protocol of the same
+ * major. On close, every run still going is closed.
+ *
+ * @param input - Where the client's messages arrive (stdin).
+ * @param output - Where the driver's go (stdout). Nothing else may write to it.
+ * @param identity - The driver's version, for `initialize`.
+ * @returns Settles once the driver has stopped.
+ */
+export declare function serveDriver(input: Readable, output: Writable, identity: DriverIdentity): Promise<void>;
+//# sourceMappingURL=serve-driver.use-case.d.ts.map

package/dist/src/session/index.d.ts

@@ -0,0 +1,5 @@
+export { runSessions } from './run-session.use-case.js';
+export type { NotifyClient, RunSessions } from './run-session.use-case.js';
+export { validateRecipes, hooksOf, loadRecipes, sourceOf } from './recipe-loading.use-case.js';
+export { streamingSink } from './streaming-sink.repository.js';
+//# sourceMappingURL=index.d.ts.map