@opencraw/driver 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,354 @@
+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.1.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<{
+    accessConfig: z.ZodOptional<z.ZodString>;
+    access: z.ZodOptional<z.ZodString>;
+    accessPlugins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    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>>;
+    captchaSolvers: 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 probeParamsSchema: z.ZodObject<{
+    accessConfig: z.ZodOptional<z.ZodString>;
+    access: z.ZodOptional<z.ZodString>;
+    accessPlugins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    url: z.ZodString;
+    browser: z.ZodOptional<z.ZodBoolean>;
+    browserPath: z.ZodOptional<z.ZodString>;
+    insecureTls: z.ZodOptional<z.ZodBoolean>;
+    userAgent: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type ProbeParams = z.infer<typeof probeParamsSchema>;
+/** What the page holds and how a recipe could reach it (`ProbeResult`); its shape is the probe's, versioned with it. */
+export declare const probeResultSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const diffParamsSchema: z.ZodObject<{
+    previous: z.ZodString;
+    current: z.ZodString;
+    key: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type DiffParams = z.infer<typeof diffParamsSchema>;
+export declare const diffResultSchema: z.ZodObject<{
+    added: z.ZodNumber;
+    removed: z.ZodNumber;
+    changed: z.ZodNumber;
+    unchanged: z.ZodNumber;
+    shrunk: z.ZodOptional<z.ZodObject<{
+        previous: z.ZodNumber;
+        current: z.ZodNumber;
+    }, z.core.$strict>>;
+    summary: z.ZodArray<z.ZodString>;
+    changes: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    truncated: z.ZodBoolean;
+}, z.core.$strict>;
+export type DiffResult = z.infer<typeof diffResultSchema>;
+export declare const exportParamsSchema: z.ZodObject<{
+    records: z.ZodString;
+    output: z.ZodString;
+    out: z.ZodString;
+}, z.core.$strict>;
+export type ExportParams = z.infer<typeof exportParamsSchema>;
+export declare const exportResultSchema: z.ZodObject<{
+    written: z.ZodNumber;
+    location: z.ZodString;
+}, z.core.$strict>;
+export type ExportResult = z.infer<typeof exportResultSchema>;
+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, captcha solver or access plugin the client serves (`request.kind`): 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<{
+            accessConfig: z.ZodOptional<z.ZodString>;
+            access: z.ZodOptional<z.ZodString>;
+            accessPlugins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            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>>;
+            captchaSolvers: 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 probe: {
+        readonly direction: 'client-to-driver';
+        readonly params: z.ZodObject<{
+            accessConfig: z.ZodOptional<z.ZodString>;
+            access: z.ZodOptional<z.ZodString>;
+            accessPlugins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            url: z.ZodString;
+            browser: z.ZodOptional<z.ZodBoolean>;
+            browserPath: z.ZodOptional<z.ZodString>;
+            insecureTls: z.ZodOptional<z.ZodBoolean>;
+            userAgent: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        readonly result: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    };
+    readonly diff: {
+        readonly direction: 'client-to-driver';
+        readonly params: z.ZodObject<{
+            previous: z.ZodString;
+            current: z.ZodString;
+            key: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            limit: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            added: z.ZodNumber;
+            removed: z.ZodNumber;
+            changed: z.ZodNumber;
+            unchanged: z.ZodNumber;
+            shrunk: z.ZodOptional<z.ZodObject<{
+                previous: z.ZodNumber;
+                current: z.ZodNumber;
+            }, z.core.$strict>>;
+            summary: z.ZodArray<z.ZodString>;
+            changes: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+            truncated: z.ZodBoolean;
+        }, z.core.$strict>;
+    };
+    readonly export: {
+        readonly direction: 'client-to-driver';
+        readonly params: z.ZodObject<{
+            records: z.ZodString;
+            output: z.ZodString;
+            out: z.ZodString;
+        }, z.core.$strict>;
+        readonly result: z.ZodObject<{
+            written: z.ZodNumber;
+            location: z.ZodString;
+        }, 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, probeParamsSchema, probeResultSchema, diffParamsSchema, diffResultSchema, exportParamsSchema, exportResultSchema, } from './driver-message.contract.js';
+export type { InitializeParams, InitializeResult, ValidateParams, ValidateResult, RunParams, RunResult, CancelParams, CancelResult, EventParams, RecordParams, FinishedParams, CalloutParams, ProbeParams, DiffParams, DiffResult, ExportParams, ExportResult, } from './driver-message.contract.js';
+export { driverProtocolJsonSchema } from './driver-json-schema.mapper.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/record-files/diff-record-files.use-case.d.ts

@@ -0,0 +1,10 @@
+import type { DiffParams, DiffResult } from '../protocol/index.js';
+/**
+ * Compares two runs' JSON Lines files by key: how many records were added, removed, changed and left
+ * alone, the report a person reads, and the changes themselves, up to `limit`.
+ *
+ * @param params - The two files, the key fields, the fields to ignore and the limit.
+ * @returns The comparison.
+ */
+export declare function diffRecordFiles(params: DiffParams): Promise<DiffResult>;
+//# sourceMappingURL=diff-record-files.use-case.d.ts.map

package/dist/src/record-files/export-record-files.use-case.d.ts

@@ -0,0 +1,11 @@
+import type { ExportParams, ExportResult } from '../protocol/index.js';
+/**
+ * Writes a finished run's JSON Lines file again in another format, the extension of `out` naming it, as
+ * the CLI's `export` does. The output recipe gives the columns: its fields, in order, with their types.
+ *
+ * @param params - The records, the output recipe and the file to write.
+ * @returns How many records were written, and where.
+ * @throws RecipeValidationError When `output` is not an output recipe.
+ */
+export declare function exportRecordFiles(params: ExportParams): Promise<ExportResult>;
+//# sourceMappingURL=export-record-files.use-case.d.ts.map

package/dist/src/record-files/index.d.ts

@@ -0,0 +1,3 @@
+export { diffRecordFiles } from './diff-record-files.use-case.js';
+export { exportRecordFiles } from './export-record-files.use-case.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

package/dist/src/session/recipe-loading.use-case.d.ts

@@ -0,0 +1,23 @@
+import type { RecipeSet, RecipeSource } from '@opencraw/core';
+import type { ValidateParams, ValidateResult } from '../protocol/index.js';
+/** The recipes a method names: files and folders, or the recipes themselves. Exactly one of the two. */
+export declare function sourceOf(params: {
+    paths?: string[];
+    recipes?: Record<string, unknown>[];
+}): RecipeSource;
+/** Loads and binds a method's recipes, keeping the input ids in `only`. */
+export declare function loadRecipes(params: {
+    paths?: string[];
+    recipes?: Record<string, unknown>[];
+    only?: string[];
+}): Promise<RecipeSet>;
+/** Every hook the set's input recipes call, once each, sorted. */
+export declare function hooksOf(set: RecipeSet): string[];
+/**
+ * Checks recipes the way `run` would load them, without running them.
+ *
+ * @param params - The recipes and the input ids to keep.
+ * @returns Whether they load, the inputs and hooks a run would have, and every problem with its path.
+ */
+export declare function validateRecipes(params: ValidateParams): Promise<ValidateResult>;
+//# sourceMappingURL=recipe-loading.use-case.d.ts.map

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

@@ -0,0 +1,24 @@
+import type { AskClient } from '../callout-bridge/index.js';
+import type { RunParams } from '../protocol/index.js';
+/** Sends a notification to the client. */
+export type NotifyClient = (method: string, params: unknown) => void;
+/** 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>;
+    cancel: (runId: string) => Promise<boolean>;
+    closeAll: () => Promise<void>;
+}
+/**
+ * Starts and tracks runs. `start` loads and binds the recipes (a bad recipe fails the `run` request
+ * itself, with its problems), answers with a run id at once, and crawls in the background: every crawl
+ * event goes to the client as an `event` notification, every record as a `record` one unless `out`
+ * names a file, and the end as `finished` with the report. A hook the client serves is asked back with
+ * a `callout` request, and so are the captcha solvers and access plugins it serves. `cancel` closes the run's crawler, which stops its recipes; the run still ends
+ * with `finished`.
+ *
+ * @param notify - The channel's notify.
+ * @param ask - The channel's request, for callouts.
+ * @returns The sessions.
+ */
+export declare function runSessions(notify: NotifyClient, ask: AskClient): RunSessions;
+//# sourceMappingURL=run-session.use-case.d.ts.map

package/dist/src/session/streaming-sink.repository.d.ts

@@ -0,0 +1,8 @@
+import type { RecordSink } from '@opencraw/core';
+/**
+ * The sink of a run with no `out` file: it keeps nothing, since each record already reached the client
+ * as a `record` notification from its `record:emit` event, and only counts them for the report. A long
+ * crawl therefore streams in constant memory.
+ */
+export declare function streamingSink(): RecordSink;
+//# sourceMappingURL=streaming-sink.repository.d.ts.map

package/dist/src/site-access/index.d.ts

@@ -0,0 +1,3 @@
+export { resolveSiteAccess } from './resolve-site-access.use-case.js';
+export type { SiteAccess, SiteAccessParams } from './resolve-site-access.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/site-access/resolve-site-access.use-case.d.ts

@@ -0,0 +1,26 @@
+import type { AccessConfig, AccessPlugin } from '@opencraw/core';
+import type { AskClient } from '../callout-bridge/index.js';
+/** What a run or a probe asks of access: the config file, the profile, and the plugins the client serves. */
+export interface SiteAccessParams {
+    accessConfig?: string;
+    access?: string;
+    accessPlugins?: string[];
+}
+/** How a run or a probe reaches sites. */
+export interface SiteAccess {
+    access?: AccessConfig;
+    accessPlugins: AccessPlugin[];
+}
+/**
+ * Loads the access config (the file the client names, else `OPENCRAW_ACCESS`), with `access` as its
+ * default profile, and builds a plugin for each one the client serves.
+ *
+ * @param params - The method's access fields.
+ * @param runId - The run, or the probe, the plugins' callouts belong to.
+ * @param ask - The channel's request.
+ * @param env - Where `OPENCRAW_ACCESS` is read.
+ * @returns The config and the plugins.
+ * @throws Error When a profile is named without a config, or the config has no such profile.
+ */
+export declare function resolveSiteAccess(params: SiteAccessParams, runId: string, ask: AskClient, env?: NodeJS.ProcessEnv): Promise<SiteAccess>;
+//# sourceMappingURL=resolve-site-access.use-case.d.ts.map

package/dist/src/site-probe/index.d.ts

@@ -0,0 +1,2 @@
+export { probeSite } from './probe-site.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/site-probe/probe-site.use-case.d.ts

@@ -0,0 +1,13 @@
+import type { AskClient } from '../callout-bridge/index.js';
+import type { ProbeParams } from '../protocol/index.js';
+/**
+ * Fetches a page, or renders it with `browser`, and says where its data lives: the probe the CLI and the
+ * MCP server use, through the access the client names (its plugins served by the client).
+ *
+ * @param params - The page and how to reach it.
+ * @param probeId - What the plugins' callouts carry as their `runId`.
+ * @param ask - The channel's request.
+ * @returns The probe's findings.
+ */
+export declare function probeSite(params: ProbeParams, probeId: string, ask: AskClient): Promise<Record<string, unknown>>;
+//# sourceMappingURL=probe-site.use-case.d.ts.map

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

@@ -0,0 +1,5 @@
+export { openLineChannel } from './line-channel.client.js';
+export type { LineChannel, RequestHandler } from './line-channel.client.js';
+export { RPC_ERRORS, RpcFailure } from './json-rpc.contract.js';
+export type { RpcError, RpcMessage } from './json-rpc.contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/transport/json-rpc.contract.d.ts

@@ -0,0 +1,31 @@
+/** JSON-RPC 2.0 error codes the driver answers with. */
+export declare const RPC_ERRORS: {
+    readonly parse: -32700;
+    readonly invalidRequest: -32600;
+    readonly methodNotFound: -32601;
+    readonly invalidParams: -32602;
+    readonly internal: -32603;
+    /** A failure the caller must act on: the message says what to do. */
+    readonly server: -32000;
+};
+export interface RpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/** A request (it has an id and wants a response) or a notification (no id). */
+export interface RpcMessage {
+    jsonrpc: '2.0';
+    id?: number | string | null;
+    method?: string;
+    params?: unknown;
+    result?: unknown;
+    error?: RpcError;
+}
+/** An error a method handler throws to answer with a code other than `server`. */
+export declare class RpcFailure extends Error {
+    readonly code: number;
+    readonly data: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+//# sourceMappingURL=json-rpc.contract.d.ts.map

package/dist/src/transport/line-channel.client.d.ts

@@ -0,0 +1,27 @@
+import type { Readable, Writable } from 'node:stream';
+/** Answers a request: its result, or a thrown error (an `RpcFailure` for a specific code). */
+export type RequestHandler = (method: string, params: unknown) => Promise<unknown>;
+/** JSON-RPC 2.0 both ways over a stream pair, one message per line. */
+export interface LineChannel {
+    /** Sends a request to the other side and waits for its result; rejects with its error. */
+    request: (method: string, params: unknown) => Promise<unknown>;
+    /** Sends a notification: no answer is expected. */
+    notify: (method: string, params: unknown) => void;
+    /** Settles when the input ends (the other side closed it, or went away). */
+    closed: Promise<void>;
+    /** Settles once every request read so far has been answered: what to wait for before stopping. */
+    drained: () => Promise<void>;
+}
+/**
+ * Opens a channel: every line read from `input` is a JSON-RPC message. A request goes to `handle` and its
+ * answer is written back; a response settles the matching `request`. A line that is not JSON gets a parse
+ * error, a message without `jsonrpc: "2.0"` an invalid-request error, and nothing it does stops the channel.
+ * Writes are one line each, never interleaved.
+ *
+ * @param input - Where messages arrive (the driver's stdin).
+ * @param output - Where they go (the driver's stdout).
+ * @param handle - What answers the other side's requests and notifications.
+ * @returns The channel.
+ */
+export declare function openLineChannel(input: Readable, output: Writable, handle: RequestHandler): LineChannel;
+//# sourceMappingURL=line-channel.client.d.ts.map

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@opencraw/driver",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "OpenCraw's driver: the engine over JSON-RPC on stdio, for clients in other languages",
+  "license": "MIT",
+  "type": "module",
+  "smith": {
+    "kind": "package",
+    "stack": "node-vitest"
+  },
+  "main": "./dist/index.esm.js",
+  "module": "./dist/index.esm.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.esm.js",
+      "default": "./dist/index.esm.js"
+    }
+  },
+  "bin": {
+    "opencraw-driver": "./dist/main.esm.js"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "!**/*.tsbuildinfo",
+    "!**/*.d.ts.map",
+    "!**/*.js.map"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts src/main.ts --bundle --packages=external --platform=node --format=esm --outdir=dist --out-extension:.js=.esm.js --sourcemap && tsc -p tsconfig.build.json && node ../../declaration-specifiers.mjs dist/src",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "schemas": "node tools/emit-protocol-schema.mjs"
+  },
+  "dependencies": {
+    "@opencraw/cli": "^0.1.56",
+    "@opencraw/core": "^0.3.0",
+    "zod": "^4.6.5"
+  }
+}