@opencraw/studio 0.0.23 → 0.0.25

package/dist/index.esm.js

@@ -3,7 +3,7 @@ import { createServer } from 'node:http';
 import { promisify, stripVTControlCharacters } from 'node:util';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { z } from 'zod';
-import { BODY_KINDS, HttpClient, BrowserClient, NODE_ID_ATTRIBUTE, sessionStateOf, rowsOfCells, parseXml, findDeckTables, findGridTables, analyzeTables, parseRegion, regionText, deckRegionText, isDeckDocument, readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, UnknownHookError, resolveMissingPolicy, isWorkbookDocument, RecipeBindingError, RecipeValidationError, countMatches, matchesOf, tryParseJson, isPdfDocument, BrowserProfiles } from '@opencraw/core';
+import { BODY_KINDS, HttpClient, BrowserClient, NODE_ID_ATTRIBUTE, sessionStateOf, rowsOfCells, parseXml, findDeckTables, findGridTables, analyzeTables, parseRegion, regionText, deckRegionText, isDeckDocument, readRecipeSource, parseInputRecipe, parseOutputRecipe, calloutLabel, bindRecipeSet, memorySink, createCrawler, traceLine, UnknownHookError, resolveMissingPolicy, isWorkbookDocument, RecipeBindingError, RecipeValidationError, countMatches, matchesOf, tryParseJson, isPdfDocument, BrowserProfiles } from '@opencraw/core';
 import { randomBytes, createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { createRequire } from 'node:module';
@@ -56,7 +56,9 @@ const openWorkspaceCommandSchema = z.object({
 const runSampleCommandSchema = z.object({
   type: z.literal('run-sample'),
   recipeId: z.string().min(1),
-  budget: sampleBudgetSchema.optional()
+  budget: sampleBudgetSchema.optional(),
+  /** Values to answer with instead of calling a hook, by hook name, for this run only: how a sample skips a slow or paid callout. */
+  stubs: z.record(z.string(), z.unknown()).optional()
 });
 /** Closes the crawler of the run in progress, if any; a no-op otherwise. */
 const stopRunCommandSchema = z.object({
@@ -503,10 +505,18 @@ const recipeListingSchema = z.object({
   /** The Steps tab's view of this file's `steps`, from `@opencraw/studio`'s `scope-outline` slice. `input` recipes only; `undefined` for an `output` or `unknown` file, which has no steps to show. */
   outline: outlineViewSchema.optional()
 });
+/** A hook, captcha solver or access plugin that calls outside the process. */
+const remoteCalloutSchema = z.object({
+  kind: z.enum(['hook', 'captcha', 'access']),
+  name: z.string(),
+  label: z.string()
+});
 /** The hooks Studio was started with (`opencraw studio --hooks <file>`, issue #150): where they came from and what they are called, for the warning bar and the hook-name suggestions. */
 const loadedHooksSchema = z.object({
   source: z.string(),
-  names: z.array(z.string())
+  names: z.array(z.string()),
+  /** Which hooks, captcha solvers and access plugins call outside the process (slow, and they may cost): the UI says so, and lets a hook be stubbed for a sample run. */
+  remote: z.array(remoteCalloutSchema).optional()
 });
 /** What `open-workspace` answers with: every recipe file directly inside the folder, and the hooks Studio runs them with, if any. */
 const workspaceViewSchema = z.object({
@@ -1987,6 +1997,39 @@ function idOf(content) {
   return content?.id;
 }
 
+/**
+ * The hooks a sample run uses: the ones Studio was started with, except that
+ *
+ * - a hook the person stubbed returns the stub's value and calls nothing, and
+ * - a hook that calls outside the process says so in the trace, once per call, because it may be slow
+ *   and it may cost money.
+ *
+ * @param hooks - The hooks Studio was started with.
+ * @param stubs - Values to answer with instead of calling a hook, by hook name. A name that is not a hook is ignored.
+ * @param announce - Where the trace lines go.
+ * @returns The hooks to run the sample with.
+ */
+function calloutHooks(hooks, stubs, announce) {
+  if (hooks === undefined) return undefined;
+  const prepared = {};
+  for (const [name, hook] of Object.entries(hooks)) {
+    if (stubs !== undefined && Object.hasOwn(stubs, name)) {
+      const stub = stubs[name];
+      prepared[name] = () => {
+        announce(`☎ hook "${name}" is stubbed: answering ${JSON.stringify(stub) ?? 'undefined'} without calling it`);
+        return stub;
+      };
+      continue;
+    }
+    const label = calloutLabel(hook);
+    prepared[name] = label === undefined ? hook : async (input, args, context) => {
+      announce(`☎ hook "${name}" calls ${label} (slow, and it may cost: stub it to skip the call)`);
+      return await hook(input, args, context);
+    };
+  }
+  return prepared;
+}
+
 /**
  * Runs one input recipe of a workspace folder as a sample: `debug: true` (so
  * each `record:emit` carries its scope snapshot and mapping trace, and each
@@ -2005,10 +2048,11 @@ function idOf(content) {
  * @param callbacks - Where trace lines and records go as the run proceeds.
  * @param browser - Browser launch settings for a web-mode recipe (an executable path override, headless…); the server-wide setting `studio-http.use-case.ts`'s `StudioServerOptions.browser` carries in, e.g. `OPENCRAW_CHROMIUM` in a sandbox with no full Playwright install.
  * @param plugins - Hooks, access plugins and captcha solvers the person started Studio with (`--hooks`, issue #150); none when it was started without.
+ * @param stubs - Values a hook answers with instead of being called, by hook name, for this run only (issue #201): how a sample skips a slow or paid callout.
  * @returns A handle: `stop` closes the crawler cleanly, `result` resolves when the run ends.
  * @throws RecipeValidationError, RecipeBindingError, Error when the recipe or its output cannot be loaded or bound.
  */
-async function runSample(folder, recipeId, budget, callbacks, browser, plugins) {
+async function runSample(folder, recipeId, budget, callbacks, browser, plugins, stubs) {
   const {
     input,
     output
@@ -2023,7 +2067,7 @@ async function runSample(folder, recipeId, budget, callbacks, browser, plugins)
     debug: true,
     sample: budget,
     browser,
-    hooks: plugins?.hooks,
+    hooks: calloutHooks(plugins?.hooks, stubs, callbacks.onTraceLine),
     accessPlugins: plugins?.accessPlugins,
     captchaSolvers: plugins?.captchaSolvers,
     onEvent: event => {
@@ -3816,6 +3860,49 @@ function handleInspectPage(state, command) {
   };
 }
 
+/**
+ * Which of what Studio was started with calls outside the process, for the bar that warns the person and
+ * for the stubs a sample run may use.
+ *
+ * @param plugins - What Studio was started with.
+ * @returns The remote hooks, solvers and plugins, hooks first, each kind sorted by name.
+ */
+function remoteCallouts(plugins) {
+  const found = [];
+  for (const [name, hook] of Object.entries(plugins.hooks)) {
+    const label = calloutLabel(hook);
+    if (label !== undefined) found.push({
+      kind: 'hook',
+      name,
+      label
+    });
+  }
+  const solvers = plugins.captchaSolvers ?? [];
+  for (const solver of solvers) {
+    const label = calloutLabel(solver);
+    if (label !== undefined) found.push({
+      kind: 'captcha',
+      name: solver.name,
+      label
+    });
+  }
+  const access = plugins.accessPlugins ?? [];
+  for (const plugin of access) {
+    const label = calloutLabel(plugin);
+    if (label !== undefined) found.push({
+      kind: 'access',
+      name: plugin.name,
+      label
+    });
+  }
+  const order = {
+    hook: 0,
+    captcha: 1,
+    access: 2
+  };
+  return found.sort((a, b) => order[a.kind] - order[b.kind] || a.name.localeCompare(b.name));
+}
+
 /** Where the studio's own recorder profile lives when `StudioServerOptions.recorderProfileDir` is not given: never a crawl's own `session.browserProfile` directory, never the person's default browser profile. */
 function defaultRecorderProfileDir() {
   return join(tmpdir(), 'opencraw-studio', 'recorder-profile');
@@ -3871,11 +3958,16 @@ async function handleOpenWorkspace(state, command) {
   if (switched) broadcast(state, {
     type: 'workspace-changed'
   });
-  return state.plugins === undefined ? view : {
+  if (state.plugins === undefined) return view;
+  const remote = remoteCallouts(state.plugins);
+  return {
     ...view,
     hooks: {
       source: state.plugins.source,
-      names: Object.keys(state.plugins.hooks).sort((a, b) => a.localeCompare(b))
+      names: Object.keys(state.plugins.hooks).sort((a, b) => a.localeCompare(b)),
+      ...(remote.length > 0 && {
+        remote
+      })
     }
   };
 }
@@ -4727,7 +4819,7 @@ async function handleRunSample(state, command) {
         scope: rejected.scope
       });
     }
-  }, state.browser, state.plugins);
+  }, state.browser, state.plugins, command.stubs);
   state.activeRun = handle;
   void handle.result.then(result => {
     if (state.activeRun === handle) state.activeRun = undefined;

package/dist/sample-run/callout-hooks.use-case.d.ts

@@ -0,0 +1,15 @@
+import type { HookMap } from '@opencraw/core';
+/**
+ * The hooks a sample run uses: the ones Studio was started with, except that
+ *
+ * - a hook the person stubbed returns the stub's value and calls nothing, and
+ * - a hook that calls outside the process says so in the trace, once per call, because it may be slow
+ *   and it may cost money.
+ *
+ * @param hooks - The hooks Studio was started with.
+ * @param stubs - Values to answer with instead of calling a hook, by hook name. A name that is not a hook is ignored.
+ * @param announce - Where the trace lines go.
+ * @returns The hooks to run the sample with.
+ */
+export declare function calloutHooks(hooks: HookMap | undefined, stubs: Record<string, unknown> | undefined, announce: (line: string) => void): HookMap | undefined;
+//# sourceMappingURL=callout-hooks.use-case.d.ts.map

package/dist/sample-run/run-sample.use-case.d.ts

@@ -33,8 +33,9 @@ export interface SampleRunHandle {
  * @param callbacks - Where trace lines and records go as the run proceeds.
  * @param browser - Browser launch settings for a web-mode recipe (an executable path override, headless…); the server-wide setting `studio-http.use-case.ts`'s `StudioServerOptions.browser` carries in, e.g. `OPENCRAW_CHROMIUM` in a sandbox with no full Playwright install.
  * @param plugins - Hooks, access plugins and captcha solvers the person started Studio with (`--hooks`, issue #150); none when it was started without.
+ * @param stubs - Values a hook answers with instead of being called, by hook name, for this run only (issue #201): how a sample skips a slow or paid callout.
  * @returns A handle: `stop` closes the crawler cleanly, `result` resolves when the run ends.
  * @throws RecipeValidationError, RecipeBindingError, Error when the recipe or its output cannot be loaded or bound.
  */
-export declare function runSample(folder: string, recipeId: string, budget: SampleBudget | undefined, callbacks: SampleRunCallbacks, browser?: BrowserSessionConfig, plugins?: TrustedPlugins): Promise<SampleRunHandle>;
+export declare function runSample(folder: string, recipeId: string, budget: SampleBudget | undefined, callbacks: SampleRunCallbacks, browser?: BrowserSessionConfig, plugins?: TrustedPlugins, stubs?: Record<string, unknown>): Promise<SampleRunHandle>;
 //# sourceMappingURL=run-sample.use-case.d.ts.map

package/dist/src/sample-run/callout-hooks.use-case.d.ts

@@ -0,0 +1,15 @@
+import type { HookMap } from '@opencraw/core';
+/**
+ * The hooks a sample run uses: the ones Studio was started with, except that
+ *
+ * - a hook the person stubbed returns the stub's value and calls nothing, and
+ * - a hook that calls outside the process says so in the trace, once per call, because it may be slow
+ *   and it may cost money.
+ *
+ * @param hooks - The hooks Studio was started with.
+ * @param stubs - Values to answer with instead of calling a hook, by hook name. A name that is not a hook is ignored.
+ * @param announce - Where the trace lines go.
+ * @returns The hooks to run the sample with.
+ */
+export declare function calloutHooks(hooks: HookMap | undefined, stubs: Record<string, unknown> | undefined, announce: (line: string) => void): HookMap | undefined;
+//# sourceMappingURL=callout-hooks.use-case.d.ts.map

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

@@ -33,8 +33,9 @@ export interface SampleRunHandle {
  * @param callbacks - Where trace lines and records go as the run proceeds.
  * @param browser - Browser launch settings for a web-mode recipe (an executable path override, headless…); the server-wide setting `studio-http.use-case.ts`'s `StudioServerOptions.browser` carries in, e.g. `OPENCRAW_CHROMIUM` in a sandbox with no full Playwright install.
  * @param plugins - Hooks, access plugins and captcha solvers the person started Studio with (`--hooks`, issue #150); none when it was started without.
+ * @param stubs - Values a hook answers with instead of being called, by hook name, for this run only (issue #201): how a sample skips a slow or paid callout.
  * @returns A handle: `stop` closes the crawler cleanly, `result` resolves when the run ends.
  * @throws RecipeValidationError, RecipeBindingError, Error when the recipe or its output cannot be loaded or bound.
  */
-export declare function runSample(folder: string, recipeId: string, budget: SampleBudget | undefined, callbacks: SampleRunCallbacks, browser?: BrowserSessionConfig, plugins?: TrustedPlugins): Promise<SampleRunHandle>;
+export declare function runSample(folder: string, recipeId: string, budget: SampleBudget | undefined, callbacks: SampleRunCallbacks, browser?: BrowserSessionConfig, plugins?: TrustedPlugins, stubs?: Record<string, unknown>): Promise<SampleRunHandle>;
 //# sourceMappingURL=run-sample.use-case.d.ts.map

package/dist/src/studio-api/command.contract.d.ts

@@ -19,6 +19,7 @@ export declare const runSampleCommandSchema: z.ZodObject<{
         maxPages: z.ZodOptional<z.ZodNumber>;
         maxMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    stubs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 /** Closes the crawler of the run in progress, if any; a no-op otherwise. */
 export declare const stopRunCommandSchema: z.ZodObject<{
@@ -372,6 +373,7 @@ export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         maxPages: z.ZodOptional<z.ZodNumber>;
         maxMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    stubs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"stop-run">;
 }, z.core.$strip>, z.ZodObject<{

package/dist/src/studio-api/workspace-view.contract.d.ts

@@ -32,6 +32,15 @@ export declare const recipeListingSchema: z.ZodObject<{
 export declare const loadedHooksSchema: z.ZodObject<{
     source: z.ZodString;
     names: z.ZodArray<z.ZodString>;
+    remote: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            hook: "hook";
+            captcha: "captcha";
+            access: "access";
+        }>;
+        name: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 /** What `open-workspace` answers with: every recipe file directly inside the folder, and the hooks Studio runs them with, if any. */
 export declare const workspaceViewSchema: z.ZodObject<{
@@ -58,6 +67,15 @@ export declare const workspaceViewSchema: z.ZodObject<{
     hooks: z.ZodOptional<z.ZodObject<{
         source: z.ZodString;
         names: z.ZodArray<z.ZodString>;
+        remote: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                hook: "hook";
+                captcha: "captcha";
+                access: "access";
+            }>;
+            name: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type RecipeIssue = z.infer<typeof recipeIssueSchema>;

package/dist/src/trusted-plugins/index.d.ts

@@ -1,2 +1,4 @@
 export type { TrustedPlugins } from './trusted-plugins.contract.js';
+export { remoteCallouts } from './remote-callouts.mapper.js';
+export type { RemoteCallout } from './remote-callouts.mapper.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/trusted-plugins/remote-callouts.mapper.d.ts

@@ -0,0 +1,17 @@
+import type { TrustedPlugins } from './trusted-plugins.contract.js';
+/** A hook, solver or plugin that is backed by a handler outside the process: it may be slow, and it may cost money. */
+export interface RemoteCallout {
+    kind: 'hook' | 'captcha' | 'access';
+    name: string;
+    /** What it calls (`POST https://svc/price`, `command python3 slug.py`). */
+    label: string;
+}
+/**
+ * Which of what Studio was started with calls outside the process, for the bar that warns the person and
+ * for the stubs a sample run may use.
+ *
+ * @param plugins - What Studio was started with.
+ * @returns The remote hooks, solvers and plugins, hooks first, each kind sorted by name.
+ */
+export declare function remoteCallouts(plugins: TrustedPlugins): RemoteCallout[];
+//# sourceMappingURL=remote-callouts.mapper.d.ts.map

package/dist/studio-api/command.contract.d.ts

@@ -19,6 +19,7 @@ export declare const runSampleCommandSchema: z.ZodObject<{
         maxPages: z.ZodOptional<z.ZodNumber>;
         maxMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    stubs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>;
 /** Closes the crawler of the run in progress, if any; a no-op otherwise. */
 export declare const stopRunCommandSchema: z.ZodObject<{
@@ -372,6 +373,7 @@ export declare const studioCommandSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         maxPages: z.ZodOptional<z.ZodNumber>;
         maxMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    stubs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"stop-run">;
 }, z.core.$strip>, z.ZodObject<{

package/dist/studio-api/workspace-view.contract.d.ts

@@ -32,6 +32,15 @@ export declare const recipeListingSchema: z.ZodObject<{
 export declare const loadedHooksSchema: z.ZodObject<{
     source: z.ZodString;
     names: z.ZodArray<z.ZodString>;
+    remote: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        kind: z.ZodEnum<{
+            access: "access";
+            captcha: "captcha";
+            hook: "hook";
+        }>;
+        name: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 /** What `open-workspace` answers with: every recipe file directly inside the folder, and the hooks Studio runs them with, if any. */
 export declare const workspaceViewSchema: z.ZodObject<{
@@ -58,6 +67,15 @@ export declare const workspaceViewSchema: z.ZodObject<{
     hooks: z.ZodOptional<z.ZodObject<{
         source: z.ZodString;
         names: z.ZodArray<z.ZodString>;
+        remote: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            kind: z.ZodEnum<{
+                access: "access";
+                captcha: "captcha";
+                hook: "hook";
+            }>;
+            name: z.ZodString;
+            label: z.ZodString;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type RecipeIssue = z.infer<typeof recipeIssueSchema>;

package/dist/trusted-plugins/index.d.ts

@@ -1,2 +1,4 @@
 export type { TrustedPlugins } from './trusted-plugins.contract';
+export { remoteCallouts } from './remote-callouts.mapper';
+export type { RemoteCallout } from './remote-callouts.mapper';
 //# sourceMappingURL=index.d.ts.map

package/dist/trusted-plugins/remote-callouts.mapper.d.ts

@@ -0,0 +1,17 @@
+import type { TrustedPlugins } from './trusted-plugins.contract';
+/** A hook, solver or plugin that is backed by a handler outside the process: it may be slow, and it may cost money. */
+export interface RemoteCallout {
+    kind: 'hook' | 'captcha' | 'access';
+    name: string;
+    /** What it calls (`POST https://svc/price`, `command python3 slug.py`). */
+    label: string;
+}
+/**
+ * Which of what Studio was started with calls outside the process, for the bar that warns the person and
+ * for the stubs a sample run may use.
+ *
+ * @param plugins - What Studio was started with.
+ * @returns The remote hooks, solvers and plugins, hooks first, each kind sorted by name.
+ */
+export declare function remoteCallouts(plugins: TrustedPlugins): RemoteCallout[];
+//# sourceMappingURL=remote-callouts.mapper.d.ts.map