@opencraw/studio 0.0.10 → 0.0.12

package/dist/index.esm.js

@@ -2,7 +2,7 @@ import { join, dirname, basename, extname, normalize, sep, resolve } from 'node:
 import { createServer } from 'node:http';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { z } from 'zod';
-import { BODY_KINDS, HttpClient, BrowserClient, NODE_ID_ATTRIBUTE, rowsOfCells, parseXml, findDeckTables, findGridTables, analyzeTables, parseRegion, regionText, deckRegionText, isDeckDocument, readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, 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, 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';
@@ -1119,12 +1119,30 @@ async function takeSnapshot(input, stepPath, browser) {
   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`);
-  return input.mode === 'web' ? snapshotWeb(point.url, browser) : snapshotApi(point.url);
+  const storageState = await loginState(input, browser);
+  return input.mode === 'web' ? snapshotWeb(point.url, storageState, browser) : snapshotApi(point.url, storageState);
 }
-async function snapshotWeb(url, browser) {
+/** 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) {
+  if (input.session === undefined) return undefined;
+  let client;
+  try {
+    return await sessionStateOf(input, {
+      browser: async () => {
+        client = await ensureBrowserLaunch(browser, () => BrowserClient.launch(browser));
+        return client;
+      }
+    });
+  } finally {
+    await client?.close();
+  }
+}
+async function snapshotWeb(url, storageState, browser) {
   const client = await ensureBrowserLaunch(browser, () => BrowserClient.launch(browser));
   try {
-    const session = await client.newSession();
+    const session = await client.newSession({
+      storageState
+    });
     try {
       await session.page.goto(url);
       await session.page.evaluate(hiddenMarksScript(HIDDEN_ATTRIBUTE));
@@ -1143,8 +1161,10 @@ async function snapshotWeb(url, browser) {
     await client.close();
   }
 }
-async function snapshotApi(url) {
-  const client = await HttpClient.open({});
+async function snapshotApi(url, storageState) {
+  const client = await HttpClient.open({
+    storageState
+  });
   try {
     const response = await client.send({
       url
@@ -1184,6 +1204,13 @@ function cachedSnapshot(cache, recipeId, path) {
 function putSnapshot(cache, recipeId, path, snapshot) {
   cache.entries.set(keyOf(recipeId, path), snapshot);
 }
+/** Drops every cached snapshot of one recipe — called after a save, since the steps up to any path may now capture something different. */
+function invalidateRecipe(cache, recipeId) {
+  const prefix = `${recipeId}:`;
+  for (const key of cache.entries.keys()) {
+    if (key.startsWith(prefix)) cache.entries.delete(key);
+  }
+}
 function keyOf(recipeId, path) {
   return `${recipeId}:${path}`;
 }
@@ -1239,6 +1266,50 @@ async function rereadCsv(url, override) {
   }
 }
 
+/** The keys of an input recipe that do not change what its start point shows: the steps and mapping run after it, `output` and `$schema` only name things. */
+const AFTER_START = new Set(['steps', 'mapping', 'output', '$schema']);
+/**
+ * Whether an edit changes the page a recipe's start snapshot shows (issue
+ * #159): its start URLs, mode, session, vars, headers… anything but the steps
+ * and mapping that run after it. A pick only adds steps, so it keeps the
+ * snapshot already taken instead of fetching the page again.
+ *
+ * @param before - The recipe as last saved (`undefined` when there was none).
+ * @param after - The recipe being saved.
+ * @returns `true` when the cached start snapshot may now be out of date.
+ */
+function startPointChanged(before, after) {
+  return JSON.stringify(startPartOf(before)) !== JSON.stringify(startPartOf(after));
+}
+function startPartOf(recipe) {
+  if (typeof recipe !== 'object' || recipe === null) return recipe;
+  return Object.fromEntries(Object.entries(recipe).filter(([key]) => !AFTER_START.has(key)).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+/**
+ * Drops a recipe's cached snapshots when the edit about to be saved changes
+ * its start point (issue #159). Call it before the file is written: it reads
+ * the recipe as it is on disk now to compare.
+ *
+ * @param cache - The workspace's snapshot cache.
+ * @param file - The recipe file being saved.
+ * @param next - The recipe being saved.
+ */
+async function invalidateStaleSnapshot(cache, file, next) {
+  const id = next?.id;
+  if (typeof id !== 'string') return;
+  if (startPointChanged(await savedRecipe(file), next)) invalidateRecipe(cache, id);
+}
+/** The recipe as saved on disk now, or `undefined` when there is no such file (or it is not JSON yet). */
+async function savedRecipe(file) {
+  try {
+    const text = await readFile(file, 'utf8');
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
 /** A cell reads as an ISO date (`2026-06-01`), an ISO moment (`2026-06-01T09:30:00`) or a bare time of day (`09:30:00`) — the three shapes `workbook-document`'s `read-xlsx.client.ts` writes for a spreadsheet date. */
 const ISO_DATE_OR_TIME = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2})?$|^\d{2}:\d{2}:\d{2}$/;
 /**
@@ -1968,7 +2039,7 @@ async function runSample(folder, recipeId, budget, callbacks, browser) {
       }
     }
   });
-  const result = runToResult(crawler, set, records, rejectedRecords, steps);
+  const result = runToResult(crawler, set, recipeId, records, rejectedRecords, steps);
   return {
     stop: () => crawler.close(),
     result
@@ -2012,7 +2083,13 @@ function trackStep(steps, event) {
     });
   }
 }
-async function runToResult(crawler, set, records, rejectedRecords, steps) {
+/**
+ * Awaits the run and shapes its result. A throw from `crawler.run` (an unknown
+ * hook, a recipe that cannot start) becomes the run's `error` instead of a
+ * 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) {
   try {
     const report = await crawler.run(set);
     const recipe = report.recipes[0];
@@ -2029,10 +2106,29 @@ async function runToResult(crawler, set, records, rejectedRecords, steps) {
       // eslint-disable-next-line unicorn/prefer-iterator-to-array -- `.toArray()` needs a `lib` newer than this repo's `es2022` (tsconfig.base.json)
       steps: [...steps.values()]
     };
+  } catch (error) {
+    return {
+      recipeId,
+      emitted: 0,
+      rejected: 0,
+      duplicates: 0,
+      durationMs: 0,
+      error: failureMessage(error),
+      records,
+      rejectedRecords,
+      // eslint-disable-next-line unicorn/prefer-iterator-to-array -- `.toArray()` needs a `lib` newer than this repo's `es2022` (tsconfig.base.json)
+      steps: [...steps.values()]
+    };
   } finally {
     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 `${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.`;
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
 
 /** @returns A fresh, empty cache. */
 function createLastRunCache() {
@@ -4415,13 +4511,13 @@ async function detectNavigation(page, urlBefore) {
  */
 async function handleStartRecording(state, command) {
   if (state.folder === undefined) throw new Error('open a workspace first');
-  await state.activeRecording?.stop();
+  await settleRecording(state);
   const {
     input
   } = await loadRecipePair(state.folder, command.recipeId);
   const point = input.start[0];
   if (point === undefined) throw new Error(`recipe "${command.recipeId}" has no start point`);
-  const handle = await openRecorderSession({
+  const opening = openRecorderSession({
     startUrl: point.url,
     profileDir: state.recorderProfileDir,
     browser: state.browser
@@ -4441,7 +4537,12 @@ async function handleStartRecording(state, command) {
       });
     }
   });
-  state.activeRecording = handle;
+  state.openingRecording = opening;
+  try {
+    state.activeRecording = await opening;
+  } finally {
+    state.openingRecording = undefined;
+  }
   return {
     started: true
   };
@@ -4452,21 +4553,22 @@ async function handleStartRecording(state, command) {
  * build "make this the login" (`session.bootstrap`) or "keep as steps"
  * without asking the server again. Also broadcasts `recording-stopped`, so
  * every connected client (not only the one that asked) knows the window
- * closed.
+ * closed, even when nothing was open (a UI waiting on it would stay stuck).
+ * A stop that arrives while the window is still opening waits for it.
  *
  * @param state - The server state holding the active recording, if any.
  * @param _command - The command (carries nothing beyond its type).
  * @returns Every step recorded, in order; empty when nothing was recording.
  */
 async function handleStopRecording(state, _command) {
+  await waitForOpening(state);
   const recording = state.activeRecording;
   state.activeRecording = undefined;
-  if (recording === undefined) return {
-    steps: []
-  };
   const {
     steps
-  } = await recording.stop();
+  } = recording === undefined ? {
+    steps: []
+  } : await recording.stop();
   broadcast(state, {
     type: 'recording-stopped',
     steps
@@ -4475,6 +4577,20 @@ async function handleStopRecording(state, _command) {
     steps
   };
 }
+/** Closes the recording in progress, waiting first for one still opening (issue #174). */
+async function settleRecording(state) {
+  await waitForOpening(state);
+  await state.activeRecording?.stop();
+  state.activeRecording = undefined;
+}
+/** Waits for a window still opening; a failed open is `start-recording`'s own error to report, not the stopper's. */
+async function waitForOpening(state) {
+  try {
+    await state.openingRecording;
+  } catch {
+    // reported to the caller of start-recording
+  }
+}
 
 /**
  * Handles `responses-seen`: the JSON responses observed while a recipe's
@@ -4611,7 +4727,9 @@ async function handleStopRun(state, _command) {
  * @returns `{ saved: true }` once the write has completed.
  */
 async function handleSaveOutline(state, command) {
-  await saveRecipe(command.path, outlineToRecipe(command.outline));
+  const recipe = outlineToRecipe(command.outline);
+  await invalidateStaleSnapshot(state.snapshots, command.path, recipe);
+  await saveRecipe(command.path, recipe);
   broadcast(state, {
     type: 'workspace-changed'
   });
@@ -4630,7 +4748,9 @@ async function handleSaveOutline(state, command) {
  * @returns `{ saved: true }` once the write has completed.
  */
 async function handleSaveRecipe(state, command) {
-  await saveRecipe(command.path, command.recipe);
+  const recipe = command.recipe;
+  await invalidateStaleSnapshot(state.snapshots, command.path, recipe);
+  await saveRecipe(command.path, recipe);
   broadcast(state, {
     type: 'workspace-changed'
   });
@@ -4918,7 +5038,7 @@ async function startStudioServer(options = {}) {
 }
 async function stop(server, state) {
   await state.activeRun?.stop();
-  await state.activeRecording?.stop();
+  await settleRecording(state);
   server.closeAllConnections();
   await new Promise((resolve, reject) => {
     server.close(error => error === undefined ? resolve() : reject(error));

package/dist/src/page-snapshot/index.d.ts

@@ -9,4 +9,5 @@ export type { SnapshotCache } from './snapshot.store.js';
 export { pdfBytes } from './pdf-bytes.use-case.js';
 export { rereadCsv } from './reread-csv.use-case.js';
 export type { CsvOverride } from './reread-csv.use-case.js';
+export { invalidateStaleSnapshot } from './invalidate-stale-snapshot.use-case.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,12 @@
+import type { SnapshotCache } from './snapshot.store.js';
+/**
+ * Drops a recipe's cached snapshots when the edit about to be saved changes
+ * its start point (issue #159). Call it before the file is written: it reads
+ * the recipe as it is on disk now to compare.
+ *
+ * @param cache - The workspace's snapshot cache.
+ * @param file - The recipe file being saved.
+ * @param next - The recipe being saved.
+ */
+export declare function invalidateStaleSnapshot(cache: SnapshotCache, file: string, next: unknown): Promise<void>;
+//# sourceMappingURL=invalidate-stale-snapshot.use-case.d.ts.map

package/dist/src/page-snapshot/start-point.policy.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Whether an edit changes the page a recipe's start snapshot shows (issue
+ * #159): its start URLs, mode, session, vars, headers… anything but the steps
+ * and mapping that run after it. A pick only adds steps, so it keeps the
+ * snapshot already taken instead of fetching the page again.
+ *
+ * @param before - The recipe as last saved (`undefined` when there was none).
+ * @param after - The recipe being saved.
+ * @returns `true` when the cached start snapshot may now be out of date.
+ */
+export declare function startPointChanged(before: unknown, after: unknown): boolean;
+//# sourceMappingURL=start-point.policy.d.ts.map

package/dist/src/studio-server/recording.handler.d.ts

@@ -21,7 +21,8 @@ export declare function handleStartRecording(state: StudioState, command: StartR
  * build "make this the login" (`session.bootstrap`) or "keep as steps"
  * without asking the server again. Also broadcasts `recording-stopped`, so
  * every connected client (not only the one that asked) knows the window
- * closed.
+ * closed, even when nothing was open (a UI waiting on it would stay stuck).
+ * A stop that arrives while the window is still opening waits for it.
  *
  * @param state - The server state holding the active recording, if any.
  * @param _command - The command (carries nothing beyond its type).
@@ -30,4 +31,6 @@ export declare function handleStartRecording(state: StudioState, command: StartR
 export declare function handleStopRecording(state: StudioState, _command: StopRecordingCommand): Promise<{
     steps: Record<string, unknown>[];
 }>;
+/** Closes the recording in progress, waiting first for one still opening (issue #174). */
+export declare function settleRecording(state: StudioState): Promise<void>;
 //# sourceMappingURL=recording.handler.d.ts.map

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

@@ -9,6 +9,8 @@ export interface StudioState {
     folder?: string;
     activeRun?: SampleRunHandle;
     activeRecording?: RecorderSessionHandle;
+    /** A `start-recording` still opening its window: `stop-recording` and the server's own close wait for it, so a window is never left open behind them (issue #174). */
+    openingRecording?: Promise<unknown>;
     sockets: Set<WsConnection>;
     snapshots: SnapshotCache;
     lastRuns: LastRunCache;