@opencraw/studio 0.0.14 → 0.0.16

package/dist/index.esm.js

@@ -503,10 +503,16 @@ 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()
 });
-/** What `open-workspace` answers with: every recipe file directly inside the folder. */
+/** 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())
+});
+/** 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({
   folder: z.string(),
-  recipes: z.array(recipeListingSchema)
+  recipes: z.array(recipeListingSchema),
+  hooks: loadedHooksSchema.optional()
 });
 
 /** `import-document`'s answer: where the copy landed, and the `file:` URL a recipe's `start.url` points at it with. */
@@ -1112,22 +1118,24 @@ function escapeAttribute(value) {
  * @param input - The input recipe; only `mode` and the first `start` point are used.
  * @param stepPath - The step to snapshot after, e.g. `"start"` or `"steps.2"` (`scope-outline`'s path format).
  * @param browser - Browser launch settings for web mode.
+ * @param hooks - The hooks a login bootstrap may call (the ones Studio was started with, issue #150).
  * @returns The rewritten snapshot.
  * @throws Error when the recipe has no start point, or `stepPath` is not `"start"`.
  */
-async function takeSnapshot(input, stepPath, browser) {
+async function takeSnapshot(input, stepPath, browser, hooks) {
   if (stepPath !== 'start') throw new Error(`takeSnapshot: "${stepPath}" is not supported yet — only "start" (the first start point, before any step runs) is; see this function's doc comment`);
   const point = input.start[0];
   if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
-  const storageState = await loginState(input, browser);
+  const storageState = await loginState(input, browser, hooks);
   return input.mode === 'web' ? snapshotWeb(point.url, storageState, browser) : snapshotApi(point.url, storageState);
 }
 /** What the recipe's own login leaves behind, so the snapshot shows the page as the crawl sees it (issue #185); nothing when it declares no login. */
-async function loginState(input, browser) {
+async function loginState(input, browser, hooks) {
   if (input.session === undefined) return undefined;
   let client;
   try {
     return await sessionStateOf(input, {
+      hooks,
       browser: async () => {
         client = await ensureBrowserLaunch(browser, () => BrowserClient.launch(browser));
         return client;
@@ -1996,10 +2004,11 @@ function idOf(content) {
  * @param budget - The sample budget; unset runs the recipe to completion (still capped by its own `limits`).
  * @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.
  * @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) {
+async function runSample(folder, recipeId, budget, callbacks, browser, plugins) {
   const {
     input,
     output
@@ -2014,6 +2023,9 @@ async function runSample(folder, recipeId, budget, callbacks, browser) {
     debug: true,
     sample: budget,
     browser,
+    hooks: plugins?.hooks,
+    accessPlugins: plugins?.accessPlugins,
+    captchaSolvers: plugins?.captchaSolvers,
     onEvent: event => {
       const line = traceLine(event);
       if (line !== undefined) callbacks.onTraceLine(line);
@@ -2039,7 +2051,7 @@ async function runSample(folder, recipeId, budget, callbacks, browser) {
       }
     }
   });
-  const result = runToResult(crawler, set, recipeId, records, rejectedRecords, steps);
+  const result = runToResult(crawler, set, recipeId, records, rejectedRecords, steps, plugins);
   return {
     stop: () => crawler.close(),
     result
@@ -2089,7 +2101,7 @@ function trackStep(steps, event) {
  * rejection: nothing awaits `result` but a `.then`, and an unhandled rejection
  * would take the whole Studio server down (issue #148).
  */
-async function runToResult(crawler, set, recipeId, records, rejectedRecords, steps) {
+async function runToResult(crawler, set, recipeId, records, rejectedRecords, steps, plugins) {
   try {
     const report = await crawler.run(set);
     const recipe = report.recipes[0];
@@ -2113,7 +2125,7 @@ async function runToResult(crawler, set, recipeId, records, rejectedRecords, ste
       rejected: 0,
       duplicates: 0,
       durationMs: 0,
-      error: failureMessage(error),
+      error: failureMessage(error, plugins),
       records,
       rejectedRecords,
       // eslint-disable-next-line unicorn/prefer-iterator-to-array -- `.toArray()` needs a `lib` newer than this repo's `es2022` (tsconfig.base.json)
@@ -2123,9 +2135,13 @@ async function runToResult(crawler, set, recipeId, records, rejectedRecords, ste
     await crawler.close();
   }
 }
-/** What a run that could not start reports. A hook is the author's own code, which Studio never loads (issue #150): say so, instead of leaving "unknown hook" to read as a typo. */
-function failureMessage(error) {
-  if (error instanceof UnknownHookError) return `${stripVTControlCharacters(error.message)}. Studio does not load hooks, so a recipe that uses one cannot be sample-run here; run it with the cli or the mcp server, or temporarily replace the hook step to preview the rest.`;
+/** What a run that could not start reports. A hook is the author's own code, which Studio only runs when it was started with `--hooks` (issue #150): say which case this is, instead of leaving "unknown hook" to read as a typo. */
+function failureMessage(error, plugins) {
+  if (error instanceof UnknownHookError) {
+    const message = stripVTControlCharacters(error.message);
+    if (plugins !== undefined) return `${message}. It is not one of the hooks in ${plugins.source}: ${Object.keys(plugins.hooks).join(', ') || 'none exported'}.`;
+    return `${message}. Studio was started without hooks: restart it with \`opencraw studio --hooks <file>\` (a module you trust; it runs as your code), or temporarily replace the hook step to preview the rest.`;
+  }
   if (error instanceof Error) return stripVTControlCharacters(error.message);
   return stripVTControlCharacters(String(error));
 }
@@ -3854,7 +3870,13 @@ async function handleOpenWorkspace(state, command) {
   if (switched) broadcast(state, {
     type: 'workspace-changed'
   });
-  return view;
+  return state.plugins === undefined ? view : {
+    ...view,
+    hooks: {
+      source: state.plugins.source,
+      names: Object.keys(state.plugins.hooks).sort((a, b) => a.localeCompare(b))
+    }
+  };
 }
 
 /**
@@ -4704,7 +4726,7 @@ async function handleRunSample(state, command) {
         scope: rejected.scope
       });
     }
-  }, state.browser);
+  }, state.browser, state.plugins);
   state.activeRun = handle;
   void handle.result.then(result => {
     if (state.activeRun === handle) state.activeRun = undefined;
@@ -4866,7 +4888,7 @@ async function handleTakeSnapshot(state, command) {
   const {
     input
   } = await loadRecipePair(state.folder, command.recipeId);
-  const snapshot = await takeSnapshot(input, command.path, state.browser);
+  const snapshot = await takeSnapshot(input, command.path, state.browser, state.plugins?.hooks);
   putSnapshot(state.snapshots, command.recipeId, command.path, snapshot);
   return snapshotView(snapshot);
 }
@@ -5045,6 +5067,7 @@ async function startStudioServer(options = {}) {
   const state = createStudioState();
   if (options.initialFolder !== undefined) state.folder = options.initialFolder;
   state.browser = options.browser;
+  state.plugins = options.plugins;
   if (options.recorderProfileDir !== undefined) state.recorderProfileDir = options.recorderProfileDir;
   const server = createServer((request, response) => {
     void handleRequest(request, response, token, state, uiRoot);
@@ -5288,14 +5311,17 @@ function messageOf(error) {
  * interrupted (Ctrl+C).
  *
  * @param argv - Arguments after the program name: an optional recipe folder, `.` when omitted.
+ * @param options - What the caller loaded beforehand: the trusted plugins, if any.
  */
-async function main(argv) {
+async function main(argv, options = {}) {
   const folder = resolve(argv[0] ?? '.');
   const server = await startStudioServer({
-    initialFolder: folder
+    initialFolder: folder,
+    plugins: options.plugins
   });
   process.stdout.write(`OpenCraw Studio: ${server.url}\n`);
   process.stdout.write(`Workspace: ${folder}\n`);
+  if (options.plugins !== undefined) process.stdout.write(`Hooks: ${options.plugins.source} (runs as your code)\n`);
   const shutdown = () => {
     void server.close();
   };
@@ -5303,5 +5329,5 @@ async function main(argv) {
   process.on('SIGTERM', shutdown);
 }
 
-export { deckChartSeriesViewSchema, deckChartViewSchema, deckDocumentViewSchema, deckPreviewCommandSchema, deckPreviewOptionsSchema, deckShapeViewSchema, deckSlideViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, deckViewCommandSchema, documentTreeCommandSchema, documentTreeNodeViewSchema, documentTreeViewSchema, domTreeNodeViewSchema, explainWhyCommandSchema, fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, fieldTraceSchema, gridCellViewSchema, gridMergeViewSchema, gridPreviewCommandSchema, gridPreviewOptionsSchema, gridSheetViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, gridViewCommandSchema, importDocument, importDocumentCommandSchema, importDocumentViewSchema, inferSelectorCommandSchema, inferSelectorViewSchema, inspectPageCommandSchema, inspectViewSchema, loadRecipePair, main, missingWhyTargetSchema, observedResponseSchema, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, pageDataFindingSchema, pdfCellViewSchema, pdfDocumentViewSchema, pdfPageViewSchema, pdfRowViewSchema, pdfViewCommandSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, recordRejectedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, rejectedWhyTargetSchema, responsesSeenCommandSchema, responsesSeenViewSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, snapshotViewSchema, startPageViewSchema, startRecordingCommandSchema, startStudioServer, stopRecordingCommandSchema, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, tablePreviewBandSchema, tablePreviewCommandSchema, tablePreviewMatchSchema, tablePreviewOptionsSchema, tablePreviewTableSchema, tablePreviewViewSchema, takeSnapshotCommandSchema, traceLineEventSchema, verifySelectorCommandSchema, verifySelectorViewSchema, whyTargetSchema, whyViewSchema, workbookDocumentViewSchema, workspaceChangedEventSchema, workspaceViewSchema };
+export { deckChartSeriesViewSchema, deckChartViewSchema, deckDocumentViewSchema, deckPreviewCommandSchema, deckPreviewOptionsSchema, deckShapeViewSchema, deckSlideViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, deckViewCommandSchema, documentTreeCommandSchema, documentTreeNodeViewSchema, documentTreeViewSchema, domTreeNodeViewSchema, explainWhyCommandSchema, fetchStartPage, fetchStartPageCommandSchema, fieldPickSchema, fieldTraceSchema, gridCellViewSchema, gridMergeViewSchema, gridPreviewCommandSchema, gridPreviewOptionsSchema, gridSheetViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, gridViewCommandSchema, importDocument, importDocumentCommandSchema, importDocumentViewSchema, inferSelectorCommandSchema, inferSelectorViewSchema, inspectPageCommandSchema, inspectViewSchema, loadRecipePair, loadedHooksSchema, main, missingWhyTargetSchema, observedResponseSchema, openWorkspace, openWorkspaceCommandSchema, outlineBracketSchema, outlineCardSchema, outlineNodeSchema, outlineViewSchema, pageDataFindingSchema, pdfCellViewSchema, pdfDocumentViewSchema, pdfPageViewSchema, pdfRowViewSchema, pdfViewCommandSchema, recipeIssueSchema, recipeListingSchema, recordEventSchema, recordRejectedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, rejectedWhyTargetSchema, responsesSeenCommandSchema, responsesSeenViewSchema, runFinishedEventSchema, runSample, runSampleCommandSchema, sampleBudgetSchema, sampleRunRecordSchema, sampleRunViewSchema, saveOutlineCommandSchema, saveRecipe, saveRecipeCommandSchema, sentencePartSchema, snapshotViewSchema, startPageViewSchema, startRecordingCommandSchema, startStudioServer, stopRecordingCommandSchema, stopRunCommandSchema, stoppedBySchema, studioCommandSchema, studioEventSchema, tablePreviewBandSchema, tablePreviewCommandSchema, tablePreviewMatchSchema, tablePreviewOptionsSchema, tablePreviewTableSchema, tablePreviewViewSchema, takeSnapshotCommandSchema, traceLineEventSchema, verifySelectorCommandSchema, verifySelectorViewSchema, whyTargetSchema, whyViewSchema, workbookDocumentViewSchema, workspaceChangedEventSchema, workspaceViewSchema };
 //# sourceMappingURL=index.esm.js.map

package/dist/src/index.d.ts

@@ -1,4 +1,6 @@
 export { main } from './main.js';
+export type { StudioMainOptions } from './main.js';
+export type { TrustedPlugins } from './trusted-plugins/index.js';
 export { startStudioServer } from './studio-server/index.js';
 export type { StudioServer, StudioServerOptions } from './studio-server/index.js';
 export { openWorkspace, saveRecipe, importDocument } from './recipe-workspace/index.js';
@@ -7,6 +9,6 @@ export { runSample, loadRecipePair } from './sample-run/index.js';
 export type { RecipePair, SampleRunCallbacks, SampleRunHandle, SampleRunRecord, SampleRunRejected, SampleRunResult, SampleStepSummary, SampleStoppedBy } from './sample-run/index.js';
 export { fetchStartPage } from './page-snapshot/index.js';
 export type { WhyFacts, WhyStepFact } from './explain-why/index.js';
-export { sampleBudgetSchema, openWorkspaceCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, studioCommandSchema, importDocumentViewSchema, stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, snapshotViewSchema, verifySelectorViewSchema, fieldPickSchema, inferSelectorViewSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, whyViewSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, gridViewCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, domTreeNodeViewSchema, pageDataFindingSchema, inspectViewSchema, observedResponseSchema, responsesSeenViewSchema, documentTreeNodeViewSchema, documentTreeViewSchema, pdfCellViewSchema, pdfRowViewSchema, pdfPageViewSchema, pdfDocumentViewSchema, tablePreviewTableSchema, tablePreviewBandSchema, tablePreviewMatchSchema, tablePreviewViewSchema, gridCellViewSchema, gridMergeViewSchema, gridSheetViewSchema, workbookDocumentViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, deckShapeViewSchema, deckChartSeriesViewSchema, deckChartViewSchema, deckSlideViewSchema, deckDocumentViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, startRecordingCommandSchema, stopRecordingCommandSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, } from './studio-api/index.js';
-export type { SampleBudget, OpenWorkspaceCommand, ImportDocumentCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, RegionPreviewCommand, GridViewCommand, GridPreviewOptions, GridPreviewCommand, DeckViewCommand, DeckPreviewOptions, DeckPreviewCommand, StudioCommand, ImportDocumentView, RegionPreviewMatchView, RegionPreviewView, StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, SnapshotView, VerifySelectorView, FieldPick, InferSelectorView, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, WhyView, DomTreeNodeView, PageDataKind, PageDataFindingView, InspectView, ObservedResponseView, ResponsesSeenView, DocumentTreeNodeView, DocumentTreeView, PdfCellView, PdfRowView, PdfPageView, PdfDocumentView, TablePreviewTableView, TablePreviewBandView, TablePreviewMatchView, TablePreviewView, GridCellView, GridMergeView, GridSheetView, WorkbookDocumentView, GridTablePreviewMatchView, GridTablePreviewView, DeckShapeView, DeckChartSeriesView, DeckChartView, DeckSlideView, DeckDocumentView, DeckTablePreviewMatchView, DeckTablePreviewView, StartRecordingCommand, StopRecordingCommand, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, } from './studio-api/index.js';
+export { sampleBudgetSchema, openWorkspaceCommandSchema, importDocumentCommandSchema, runSampleCommandSchema, stopRunCommandSchema, saveRecipeCommandSchema, fetchStartPageCommandSchema, saveOutlineCommandSchema, takeSnapshotCommandSchema, verifySelectorCommandSchema, inferSelectorCommandSchema, missingWhyTargetSchema, rejectedWhyTargetSchema, whyTargetSchema, explainWhyCommandSchema, studioCommandSchema, importDocumentViewSchema, stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, studioEventSchema, loadedHooksSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema, sampleRunRecordSchema, sampleRunViewSchema, startPageViewSchema, snapshotViewSchema, verifySelectorViewSchema, fieldPickSchema, inferSelectorViewSchema, sentencePartSchema, outlineCardSchema, outlineBracketSchema, outlineNodeSchema, outlineViewSchema, whyViewSchema, inspectPageCommandSchema, responsesSeenCommandSchema, documentTreeCommandSchema, pdfViewCommandSchema, tablePreviewOptionsSchema, tablePreviewCommandSchema, regionPreviewCommandSchema, regionPreviewMatchSchema, regionPreviewViewSchema, gridViewCommandSchema, gridPreviewOptionsSchema, gridPreviewCommandSchema, deckViewCommandSchema, deckPreviewOptionsSchema, deckPreviewCommandSchema, domTreeNodeViewSchema, pageDataFindingSchema, inspectViewSchema, observedResponseSchema, responsesSeenViewSchema, documentTreeNodeViewSchema, documentTreeViewSchema, pdfCellViewSchema, pdfRowViewSchema, pdfPageViewSchema, pdfDocumentViewSchema, tablePreviewTableSchema, tablePreviewBandSchema, tablePreviewMatchSchema, tablePreviewViewSchema, gridCellViewSchema, gridMergeViewSchema, gridSheetViewSchema, workbookDocumentViewSchema, gridTablePreviewMatchSchema, gridTablePreviewViewSchema, deckShapeViewSchema, deckChartSeriesViewSchema, deckChartViewSchema, deckSlideViewSchema, deckDocumentViewSchema, deckTablePreviewMatchSchema, deckTablePreviewViewSchema, startRecordingCommandSchema, stopRecordingCommandSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, } from './studio-api/index.js';
+export type { SampleBudget, OpenWorkspaceCommand, ImportDocumentCommand, RunSampleCommand, StopRunCommand, SaveRecipeCommand, FetchStartPageCommand, SaveOutlineCommand, TakeSnapshotCommand, VerifySelectorCommand, InferSelectorCommand, MissingWhyTarget, RejectedWhyTarget, WhyTarget, ExplainWhyCommand, InspectPageCommand, ResponsesSeenCommand, DocumentTreeCommand, PdfViewCommand, TablePreviewOptions, TablePreviewCommand, RegionPreviewCommand, GridViewCommand, GridPreviewOptions, GridPreviewCommand, DeckViewCommand, DeckPreviewOptions, DeckPreviewCommand, StudioCommand, ImportDocumentView, RegionPreviewMatchView, RegionPreviewView, StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, StudioEvent, LoadedHooks, RecipeIssue, RecipeListing, WorkspaceView, SampleRunView, StartPageView, SnapshotView, VerifySelectorView, FieldPick, InferSelectorView, SentencePart, OutlineCard, OutlineBracket, OutlineNode, OutlineView, WhyView, DomTreeNodeView, PageDataKind, PageDataFindingView, InspectView, ObservedResponseView, ResponsesSeenView, DocumentTreeNodeView, DocumentTreeView, PdfCellView, PdfRowView, PdfPageView, PdfDocumentView, TablePreviewTableView, TablePreviewBandView, TablePreviewMatchView, TablePreviewView, GridCellView, GridMergeView, GridSheetView, WorkbookDocumentView, GridTablePreviewMatchView, GridTablePreviewView, DeckShapeView, DeckChartSeriesView, DeckChartView, DeckSlideView, DeckDocumentView, DeckTablePreviewMatchView, DeckTablePreviewView, StartRecordingCommand, StopRecordingCommand, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, } from './studio-api/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/main.d.ts

@@ -1,3 +1,9 @@
+import type { TrustedPlugins } from './trusted-plugins/index.js';
+/** What the caller of `main` decided beyond the command-line arguments. */
+export interface StudioMainOptions {
+    /** Hooks and plugins loaded from a file the person named at launch (`opencraw studio --hooks <file>`, issue #150). `main` never loads code itself. */
+    plugins?: TrustedPlugins;
+}
 /**
  * Runs `opencraw-studio`: starts the server, opens `folder` (if given) as
  * the workspace right away, and prints the URL with the token, the way
@@ -6,6 +12,7 @@
  * interrupted (Ctrl+C).
  *
  * @param argv - Arguments after the program name: an optional recipe folder, `.` when omitted.
+ * @param options - What the caller loaded beforehand: the trusted plugins, if any.
  */
-export declare function main(argv: readonly string[]): Promise<void>;
+export declare function main(argv: readonly string[], options?: StudioMainOptions): Promise<void>;
 //# sourceMappingURL=main.d.ts.map

package/dist/src/page-snapshot/take-snapshot.use-case.d.ts

@@ -1,4 +1,4 @@
-import type { BodyKind, BrowserSessionConfig, HttpBody, InputRecipe } from '@opencraw/core';
+import type { BodyKind, BrowserSessionConfig, HookMap, HttpBody, InputRecipe } from '@opencraw/core';
 export interface SnapshotResult {
     /** The rewritten document, ready for the content pane's sandboxed iframe. */
     html: string;
@@ -52,8 +52,9 @@ export interface SnapshotResult {
  * @param input - The input recipe; only `mode` and the first `start` point are used.
  * @param stepPath - The step to snapshot after, e.g. `"start"` or `"steps.2"` (`scope-outline`'s path format).
  * @param browser - Browser launch settings for web mode.
+ * @param hooks - The hooks a login bootstrap may call (the ones Studio was started with, issue #150).
  * @returns The rewritten snapshot.
  * @throws Error when the recipe has no start point, or `stepPath` is not `"start"`.
  */
-export declare function takeSnapshot(input: InputRecipe, stepPath: string, browser?: BrowserSessionConfig): Promise<SnapshotResult>;
+export declare function takeSnapshot(input: InputRecipe, stepPath: string, browser?: BrowserSessionConfig, hooks?: HookMap): Promise<SnapshotResult>;
 //# sourceMappingURL=take-snapshot.use-case.d.ts.map

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

@@ -1,5 +1,6 @@
 import type { BrowserSessionConfig } from '@opencraw/core';
 import type { SampleBudget } from '../studio-api/index.js';
+import type { TrustedPlugins } from '../trusted-plugins/index.js';
 import type { SampleRunRecord, SampleRunRejected, SampleRunResult } from './sample-run-record.contract.js';
 /** Where trace lines and records go as a sample run proceeds. */
 export interface SampleRunCallbacks {
@@ -31,8 +32,9 @@ export interface SampleRunHandle {
  * @param budget - The sample budget; unset runs the recipe to completion (still capped by its own `limits`).
  * @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.
  * @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): Promise<SampleRunHandle>;
+export declare function runSample(folder: string, recipeId: string, budget: SampleBudget | undefined, callbacks: SampleRunCallbacks, browser?: BrowserSessionConfig, plugins?: TrustedPlugins): Promise<SampleRunHandle>;
 //# sourceMappingURL=run-sample.use-case.d.ts.map

package/dist/src/studio-api/index.d.ts

@@ -8,8 +8,8 @@ export { fieldPickSchema, inferSelectorViewSchema } from './infer-selector-view.
 export type { FieldPick, InferSelectorView } from './infer-selector-view.contract.js';
 export { stoppedBySchema, fieldTraceSchema, traceLineEventSchema, recordEventSchema, recordRejectedEventSchema, runFinishedEventSchema, workspaceChangedEventSchema, recordingCardEventSchema, recordingNoteEventSchema, recordingStoppedEventSchema, studioEventSchema } from './event.contract.js';
 export type { StoppedBy, FieldTraceView, TraceLineEvent, RecordEvent, RecordRejectedEvent, RunFinishedEvent, WorkspaceChangedEvent, RecordingCardEvent, RecordingNoteEvent, RecordingStoppedEvent, StudioEvent } from './event.contract.js';
-export { recipeIssueSchema, recipeListingSchema, workspaceViewSchema } from './workspace-view.contract.js';
-export type { RecipeIssue, RecipeListing, WorkspaceView } from './workspace-view.contract.js';
+export { loadedHooksSchema, recipeIssueSchema, recipeListingSchema, workspaceViewSchema } from './workspace-view.contract.js';
+export type { LoadedHooks, RecipeIssue, RecipeListing, WorkspaceView } from './workspace-view.contract.js';
 export { importDocumentViewSchema } from './import-document-view.contract.js';
 export type { ImportDocumentView } from './import-document-view.contract.js';
 export { sampleRunRecordSchema, sampleRunViewSchema } from './sample-run-view.contract.js';

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

@@ -28,7 +28,12 @@ export declare const recipeListingSchema: z.ZodObject<{
     text: z.ZodString;
     outline: z.ZodOptional<z.ZodType<import("./outline-view.contract").OutlineView, unknown, z.core.$ZodTypeInternals<import("./outline-view.contract").OutlineView, unknown>>>;
 }, z.core.$strip>;
-/** What `open-workspace` answers with: every recipe file directly inside the folder. */
+/** 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. */
+export declare const loadedHooksSchema: z.ZodObject<{
+    source: z.ZodString;
+    names: z.ZodArray<z.ZodString>;
+}, 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<{
     folder: z.ZodString;
     recipes: z.ZodArray<z.ZodObject<{
@@ -50,8 +55,13 @@ export declare const workspaceViewSchema: z.ZodObject<{
         text: z.ZodString;
         outline: z.ZodOptional<z.ZodType<import("./outline-view.contract").OutlineView, unknown, z.core.$ZodTypeInternals<import("./outline-view.contract").OutlineView, unknown>>>;
     }, z.core.$strip>>;
+    hooks: z.ZodOptional<z.ZodObject<{
+        source: z.ZodString;
+        names: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type RecipeIssue = z.infer<typeof recipeIssueSchema>;
 export type RecipeListing = z.infer<typeof recipeListingSchema>;
+export type LoadedHooks = z.infer<typeof loadedHooksSchema>;
 export type WorkspaceView = z.infer<typeof workspaceViewSchema>;
 //# sourceMappingURL=workspace-view.contract.d.ts.map

package/dist/src/studio-server/studio-http.use-case.d.ts

@@ -1,4 +1,5 @@
 import type { BrowserSessionConfig } from '@opencraw/core';
+import type { TrustedPlugins } from '../trusted-plugins/index.js';
 export interface StudioServerOptions {
     /** Where the built UI lives; default: `dist/ui` next to the running server code. */
     uiRoot?: string;
@@ -14,6 +15,8 @@ export interface StudioServerOptions {
     initialFolder?: string;
     /** Browser launch settings every web-mode command shares (`take-snapshot`, `verify-selector`, `run-sample`, `start-recording`); an executable path override (e.g. `OPENCRAW_CHROMIUM`, read by the caller — the server itself has no opinion on env vars) for a sandbox with no full Playwright install. Default: Playwright's own bundled browser. `start-recording` always forces `headless: false` regardless of what this sets. */
     browser?: BrowserSessionConfig;
+    /** Hooks, access plugins and captcha solvers to run recipes with, loaded by the caller from a file the person named at launch (`opencraw studio --hooks`, issue #150). The server never loads code itself and no request can set this. Default: none. */
+    plugins?: TrustedPlugins;
     /** Where the studio's own recorder profile lives (issue #95); default: a fixed directory under the OS temp folder, never a crawl's own profile directory, never the person's default browser. */
     recorderProfileDir?: string;
 }

package/dist/src/studio-server/workspace.store.d.ts

@@ -3,6 +3,7 @@ import type { RecorderSessionHandle } from '../flow-recording/index.js';
 import type { SnapshotCache } from '../page-snapshot/index.js';
 import type { LastRunCache, SampleRunHandle } from '../sample-run/index.js';
 import type { StudioEvent } from '../studio-api/index.js';
+import type { TrustedPlugins } from '../trusted-plugins/index.js';
 import type { WsConnection } from './websocket.client.js';
 /** The server's mutable state: the opened folder, the run in progress (if any), the recording in progress (if any, issue #95), the connected event sockets, the per-recipe snapshot cache `take-snapshot`/`verify-selector`/`infer-selector` share, each recipe's last finished sample run (`explain-why`, issue #92), the browser launch settings every web-mode command (`take-snapshot`, `verify-selector`, `run-sample`, `start-recording`) shares, and where the studio's own recorder profile lives. */
 export interface StudioState {
@@ -16,6 +17,8 @@ export interface StudioState {
     lastRuns: LastRunCache;
     /** Set once at server start (`StudioServerOptions.browser`); every web-mode command reads it from here rather than each accepting its own. */
     browser?: BrowserSessionConfig;
+    /** Set once at server start (`StudioServerOptions.plugins`): the hooks and plugins the person started Studio with (issue #150). Never set by a request. */
+    plugins?: TrustedPlugins;
     /** Set once at server start (`StudioServerOptions.recorderProfileDir`), else `defaultRecorderProfileDir()`. */
     recorderProfileDir: string;
 }

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

@@ -0,0 +1,2 @@
+export type { TrustedPlugins } from './trusted-plugins.contract.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,14 @@
+import type { AccessPlugin, CaptchaSolver, HookMap } from '@opencraw/core';
+/**
+ * Code the person who started Studio chose to run (`opencraw studio --hooks <file>`, issue #150): the
+ * hooks, access plugins and captcha solvers a recipe names. It is loaded once at launch, never at a
+ * recipe's or a browser request's say-so, so it has the trust of the command line it came from.
+ */
+export interface TrustedPlugins {
+    /** The file it was loaded from, shown to the person in the UI and in errors. */
+    source: string;
+    hooks: HookMap;
+    accessPlugins?: AccessPlugin[];
+    captchaSolvers?: CaptchaSolver[];
+}
+//# sourceMappingURL=trusted-plugins.contract.d.ts.map