@opencraw/driver 0.4.0 → 0.6.0

package/README.md

@@ -60,6 +60,19 @@ stdin at once. Answers may arrive out of order; match them by `id`.
   `-32602` (bad params, the problems listed), `-32000` (a failure to act on: its message says what to do).
 - stdout carries protocol messages only. The driver's own logs go to stderr.
 
+## The runtime: no Node needed
+
+Each driver release carries, as assets of its GitHub release `driver@<version>`, an archive per platform
+(`win32-x64`, `darwin-arm64`, `darwin-x64`, `linux-x64`, `linux-arm64`): a Node binary, the driver and its
+dependencies, and `runtime.json`, whose `command` starts it (both paths relative to the unpacked folder).
+`driver-runtime.json` lists them with their SHA-256 and size; its schema is `schemas/driver-runtime.schema.json`
+and `schemas/driver-runtime.fixture.json` is an example. A client downloads its platform's archive once, refuses
+one whose hash does not match, unpacks it into a per-user cache and starts the driver from there.
+
+`node packages/driver/packaging/stage-runtime.mjs` builds this platform's archive into `dist/drop/driver-runtime`
+(after `smith build -p driver`), and starts the staged driver once with `PATH` emptied, to prove it needs nothing
+else. Browsers are not in it: they are installed through the driver, the Playwright way.
+
 ## Development
 
 `smith run lint typecheck test build -p driver`. After changing a contract in `src/protocol/`, run

package/dist/index.esm.js

@@ -240,8 +240,8 @@ function clientAccessPlugins(names, runId, ask) {
 // src/site-access/resolve-site-access.use-case.ts
 import { resolveAccess } from "@opencraw/cli";
 async function resolveSiteAccess(params, runId, ask, env = process.env) {
-  const file = params.accessConfig ?? env.OPENCRAW_ACCESS;
-  if (file === void 0 && params.access !== void 0) throw new Error(`access profile "${params.access}" needs an access config: give "accessConfig", or set OPENCRAW_ACCESS where the driver runs`);
+  const file = params.accessConfig ?? (env.OPENCRAW_ACCESS === "" ? void 0 : env.OPENCRAW_ACCESS);
+  if (file === void 0 && params.access !== void 0) throw new Error(`access profile "${params.access}" needs an access config, and there is none: no "accessConfig" was given, and OPENCRAW_ACCESS is not set where OpenCraw runs`);
   const access = await resolveAccess({ insecureTls: false, access: file, accessProfile: params.access });
   return { access, accessPlugins: clientAccessPlugins(params.accessPlugins ?? [], runId, ask) };
 }
@@ -344,17 +344,17 @@ function streamingSink() {
 }
 
 // src/session/run-session.use-case.ts
-function runSessions(notify, ask) {
+function runSessions(notify, ask, local = {}) {
   const running = /* @__PURE__ */ new Map();
   let next = 1;
   const crawlerFor = async (runId, params) => {
     const { access, accessPlugins } = await resolveSiteAccess(params, runId, ask);
     return createCrawler({
       sink: params.out === void 0 ? streamingSink() : fileSink2(params.out, { append: params.append, browser: { executablePath: params.browser?.executablePath } }),
-      hooks: clientHooks(params.hooks ?? [], runId, ask),
-      captchaSolvers: clientCaptchaSolvers(params.captchaSolvers ?? [], runId, ask),
+      hooks: { ...local.hooks, ...clientHooks(params.hooks ?? [], runId, ask) },
+      captchaSolvers: [...local.captchaSolvers ?? [], ...clientCaptchaSolvers(params.captchaSolvers ?? [], runId, ask)],
       access,
-      accessPlugins,
+      accessPlugins: [...local.accessPlugins ?? [], ...accessPlugins],
       profilesDir: process.env.OPENCRAW_PROFILES,
       parallel: params.parallel,
       resume: params.resume,
@@ -380,15 +380,16 @@ function runSessions(notify, ask) {
       }
     })();
   };
+  const startLoaded = async (loaded, 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 = await crawlerFor(runId, params);
+    track(runId, crawler, async () => await crawler.run(set));
+    return runId;
+  };
   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 = await crawlerFor(runId, params);
-      track(runId, crawler, async () => await crawler.run(set));
-      return runId;
-    },
+    start: async (params) => await startLoaded(await loadRecipes(params), params),
+    startLoaded,
     startWork: async (params) => {
       const set = await loadRecipes(params);
       const runId = `run-${next++}`;
@@ -574,10 +575,35 @@ async function serveDriver(input, output, identity) {
   await channel.drained();
   await sessions.closeAll();
 }
+
+// src/runtime-manifest/runtime-manifest.contract.ts
+import { z as z3 } from "zod";
+var RUNTIME_PLATFORMS = ["win32-x64", "darwin-arm64", "darwin-x64", "linux-x64", "linux-arm64"];
+var archiveSchema = z3.strictObject({
+  /** The archive's file name, an asset of the same GitHub release as the manifest. */
+  file: z3.string().regex(/^opencraw-driver-[\w.-]+\.tar\.gz$/),
+  /** Its SHA-256, lowercase hex: a client refuses an archive that does not match. */
+  sha256: z3.string().regex(/^[0-9a-f]{64}$/),
+  size: z3.number().int().positive()
+});
+var runtimeManifestSchema = z3.strictObject({
+  driverVersion: z3.string().min(1),
+  protocolVersion: z3.string().regex(/^\d+\.\d+\.\d+$/),
+  /** The Node version every archive carries. */
+  node: z3.string().regex(/^v\d+\.\d+\.\d+$/),
+  archives: z3.partialRecord(z3.enum(RUNTIME_PLATFORMS), archiveSchema)
+});
+
+// src/runtime-manifest/runtime-manifest-json-schema.mapper.ts
+import { z as z4 } from "zod";
+function runtimeManifestJsonSchema() {
+  return { $id: "https://opencraw.dev/schemas/driver-runtime.schema.json", ...z4.toJSONSchema(runtimeManifestSchema, { target: "draft-2020-12" }) };
+}
 export {
   MESSAGES,
   PROTOCOL_VERSION,
   RPC_ERRORS,
+  RUNTIME_PLATFORMS,
   RpcFailure,
   calloutParamsSchema,
   calloutResultSchema,
@@ -606,6 +632,8 @@ export {
   runParamsSchema,
   runResultSchema,
   runSessions,
+  runtimeManifestJsonSchema,
+  runtimeManifestSchema,
   serveDriver,
   streamingSink,
   validateParamsSchema,

package/dist/main.esm.js

@@ -201,8 +201,8 @@ function clientAccessPlugins(names, runId, ask) {
 // src/site-access/resolve-site-access.use-case.ts
 import { resolveAccess } from "@opencraw/cli";
 async function resolveSiteAccess(params, runId, ask, env = process.env) {
-  const file = params.accessConfig ?? env.OPENCRAW_ACCESS;
-  if (file === void 0 && params.access !== void 0) throw new Error(`access profile "${params.access}" needs an access config: give "accessConfig", or set OPENCRAW_ACCESS where the driver runs`);
+  const file = params.accessConfig ?? (env.OPENCRAW_ACCESS === "" ? void 0 : env.OPENCRAW_ACCESS);
+  if (file === void 0 && params.access !== void 0) throw new Error(`access profile "${params.access}" needs an access config, and there is none: no "accessConfig" was given, and OPENCRAW_ACCESS is not set where OpenCraw runs`);
   const access = await resolveAccess({ insecureTls: false, access: file, accessProfile: params.access });
   return { access, accessPlugins: clientAccessPlugins(params.accessPlugins ?? [], runId, ask) };
 }
@@ -305,17 +305,17 @@ function streamingSink() {
 }
 
 // src/session/run-session.use-case.ts
-function runSessions(notify, ask) {
+function runSessions(notify, ask, local = {}) {
   const running = /* @__PURE__ */ new Map();
   let next = 1;
   const crawlerFor = async (runId, params) => {
     const { access, accessPlugins } = await resolveSiteAccess(params, runId, ask);
     return createCrawler({
       sink: params.out === void 0 ? streamingSink() : fileSink2(params.out, { append: params.append, browser: { executablePath: params.browser?.executablePath } }),
-      hooks: clientHooks(params.hooks ?? [], runId, ask),
-      captchaSolvers: clientCaptchaSolvers(params.captchaSolvers ?? [], runId, ask),
+      hooks: { ...local.hooks, ...clientHooks(params.hooks ?? [], runId, ask) },
+      captchaSolvers: [...local.captchaSolvers ?? [], ...clientCaptchaSolvers(params.captchaSolvers ?? [], runId, ask)],
       access,
-      accessPlugins,
+      accessPlugins: [...local.accessPlugins ?? [], ...accessPlugins],
       profilesDir: process.env.OPENCRAW_PROFILES,
       parallel: params.parallel,
       resume: params.resume,
@@ -341,15 +341,16 @@ function runSessions(notify, ask) {
       }
     })();
   };
+  const startLoaded = async (loaded, 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 = await crawlerFor(runId, params);
+    track(runId, crawler, async () => await crawler.run(set));
+    return runId;
+  };
   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 = await crawlerFor(runId, params);
-      track(runId, crawler, async () => await crawler.run(set));
-      return runId;
-    },
+    start: async (params) => await startLoaded(await loadRecipes(params), params),
+    startLoaded,
     startWork: async (params) => {
       const set = await loadRecipes(params);
       const runId = `run-${next++}`;

package/dist/src/index.d.ts

@@ -2,10 +2,12 @@ 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, probeParamsSchema, probeResultSchema, diffParamsSchema, diffResultSchema, exportParamsSchema, exportResultSchema, workParamsSchema, workItemSchema, workNextParamsSchema, workNextResultSchema, workDoneParamsSchema, workFailedParamsSchema, } from './protocol/index.js';
 export type { InitializeParams, InitializeResult, ValidateParams, ValidateResult, RunParams, RunResult, CancelParams, CancelResult, EventParams, RecordParams, FinishedParams, CalloutParams, ProbeParams, DiffParams, DiffResult, ExportParams, ExportResult, WorkParams, WorkItemMessage, WorkNextResult, WorkDoneParams, WorkFailedParams, } from './protocol/index.js';
+export { RUNTIME_PLATFORMS, runtimeManifestSchema, runtimeManifestJsonSchema } from './runtime-manifest/index.js';
+export type { RuntimeManifest, RuntimePlatform } from './runtime-manifest/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 } from './session/index.js';
+export type { LocalPlugins, RunSessions } from './session/index.js';
 export { clientHooks, clientCaptchaSolvers, clientAccessPlugins } from './callout-bridge/index.js';
 export type { AskClient, NotifyClient } from './callout-bridge/index.js';
 export { clientWorkSource } from './work-bridge/index.js';

package/dist/src/runtime-manifest/index.d.ts

@@ -0,0 +1,4 @@
+export { RUNTIME_PLATFORMS, runtimeManifestSchema } from './runtime-manifest.contract.js';
+export type { RuntimeManifest, RuntimePlatform } from './runtime-manifest.contract.js';
+export { runtimeManifestJsonSchema } from './runtime-manifest-json-schema.mapper.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/runtime-manifest/runtime-manifest-json-schema.mapper.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `driver-runtime.json`'s JSON Schema, written to `schemas/driver-runtime.schema.json`: what clients in
+ * other languages generate their manifest model from.
+ *
+ * @returns The schema.
+ */
+export declare function runtimeManifestJsonSchema(): Record<string, unknown>;
+//# sourceMappingURL=runtime-manifest-json-schema.mapper.d.ts.map

package/dist/src/runtime-manifest/runtime-manifest.contract.d.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+/** The platforms the driver's runtime is built for: `<process.platform>-<process.arch>`. */
+export declare const RUNTIME_PLATFORMS: readonly ['win32-x64', 'darwin-arm64', 'darwin-x64', 'linux-x64', 'linux-arm64'];
+export type RuntimePlatform = typeof RUNTIME_PLATFORMS[number];
+/**
+ * `driver-runtime.json`, an asset of each driver release beside the archives: what a client in any
+ * language reads to download the runtime for its platform, check it and start it. The archive holds a
+ * Node binary, the driver and its dependencies, and `runtime.json` (`command`: the Node binary and the
+ * driver's entry, both relative to the folder the archive is unpacked into).
+ */
+export declare const runtimeManifestSchema: z.ZodObject<{
+    driverVersion: z.ZodString;
+    protocolVersion: z.ZodString;
+    node: z.ZodString;
+    archives: z.ZodRecord<z.ZodEnum<{
+        "darwin-arm64": "darwin-arm64";
+        "darwin-x64": "darwin-x64";
+        "linux-arm64": "linux-arm64";
+        "linux-x64": "linux-x64";
+        "win32-x64": "win32-x64";
+    }> & z.core.$partial, z.ZodObject<{
+        file: z.ZodString;
+        sha256: z.ZodString;
+        size: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RuntimeManifest = z.infer<typeof runtimeManifestSchema>;
+//# sourceMappingURL=runtime-manifest.contract.d.ts.map

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

@@ -1,5 +1,5 @@
 export { runSessions } from './run-session.use-case.js';
-export type { RunSessions } from './run-session.use-case.js';
+export type { LocalPlugins, 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

package/dist/src/session/run-session.use-case.d.ts

@@ -1,12 +1,22 @@
+import { RecipeSet } from '@opencraw/core';
+import type { AccessPlugin, CaptchaSolver, HookMap } from '@opencraw/core';
 import type { AskClient, NotifyClient } from '../callout-bridge/index.js';
 import type { RunParams, WorkParams } from '../protocol/index.js';
 /** The runs a driver has going, by id, so `cancel` can reach them and `shutdown` close them all. */
 export interface RunSessions {
     start: (params: RunParams) => Promise<string>;
+    /** As `start`, for recipes the host has already loaded and bound (`params`' recipe source is ignored). */
+    startLoaded: (set: RecipeSet, params: Omit<RunParams, 'paths' | 'recipes'>) => Promise<string>;
     startWork: (params: WorkParams) => Promise<string>;
     cancel: (runId: string) => Promise<boolean>;
     closeAll: () => Promise<void>;
 }
+/** What the host serves itself, in process, besides what the client serves: an MCP server's plugins module. */
+export interface LocalPlugins {
+    hooks?: HookMap;
+    captchaSolvers?: CaptchaSolver[];
+    accessPlugins?: AccessPlugin[];
+}
 /**
  * Starts and tracks runs and worker pools. `start` and `startWork` load and bind the recipes (a bad
  * recipe fails the request itself, with its problems), answer with a run id at once, and crawl in the
@@ -18,7 +28,8 @@ export interface RunSessions {
  *
  * @param notify - The channel's notify.
  * @param ask - The channel's request, for callouts and work.
+ * @param local - Hooks, captcha solvers and access plugins the host serves itself, beside the client's.
  * @returns The sessions.
  */
-export declare function runSessions(notify: NotifyClient, ask: AskClient): RunSessions;
+export declare function runSessions(notify: NotifyClient, ask: AskClient, local?: LocalPlugins): RunSessions;
 //# sourceMappingURL=run-session.use-case.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencraw/driver",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "OpenCraw's driver: the engine over JSON-RPC on stdio, for clients in other languages",
   "license": "MIT",
   "type": "module",

package/schemas/driver-runtime.fixture.json

@@ -0,0 +1,9 @@
+{
+  "driverVersion": "0.6.0",
+  "protocolVersion": "1.2.0",
+  "node": "v24.12.0",
+  "archives": {
+    "linux-x64": { "file": "opencraw-driver-0.6.0-linux-x64.tar.gz", "sha256": "697d28005ed87b2887cf79edca25f06da89ab19bcb48f49c0a67dbdbcb004ad7", "size": 65410362 },
+    "win32-x64": { "file": "opencraw-driver-0.6.0-win32-x64.tar.gz", "sha256": "0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0", "size": 66120448 }
+  }
+}

package/schemas/driver-runtime.schema.json

@@ -0,0 +1,63 @@
+{
+  "$id": "https://opencraw.dev/schemas/driver-runtime.schema.json",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "driverVersion": {
+      "type": "string",
+      "minLength": 1
+    },
+    "protocolVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "node": {
+      "type": "string",
+      "pattern": "^v\\d+\\.\\d+\\.\\d+$"
+    },
+    "archives": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "enum": [
+          "win32-x64",
+          "darwin-arm64",
+          "darwin-x64",
+          "linux-x64",
+          "linux-arm64"
+        ]
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "file": {
+            "type": "string",
+            "pattern": "^opencraw-driver-[\\w.-]+\\.tar\\.gz$"
+          },
+          "sha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "size": {
+            "type": "integer",
+            "exclusiveMinimum": 0,
+            "maximum": 9007199254740991
+          }
+        },
+        "required": [
+          "file",
+          "sha256",
+          "size"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "driverVersion",
+    "protocolVersion",
+    "node",
+    "archives"
+  ],
+  "additionalProperties": false
+}