@opencraw/studio 0.0.8 → 0.0.9

package/README.md

@@ -1,11 +1,37 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/russoedu/open.craw/main/docs/assets/opencraw-logo.svg" alt="OpenCraw" width="360">
+</p>
+
 # @opencraw/studio
 
-Generated by [MoNecromanCI](https://github.com/russoedu/MoNecromanCi).
+A visual editor for [OpenCraw](https://github.com/russoedu/open.craw) recipes: open a site or a document,
+click the data you want, and get a recipe that runs — the same engine, the same JSON files, no hidden state.
+
+## Install
+
+```sh
+npm install -g @opencraw/cli @opencraw/studio
+```
+
+## Start
+
+```sh
+opencraw studio recipes/          # the cli delegates to this package when it's installed
+npx @opencraw/studio recipes/     # or run it directly, without the cli
+```
+
+Either opens a local server (`127.0.0.1` only, behind a random access token) and prints the URL to open:
 
-## Building
+```text
+OpenCraw Studio: http://127.0.0.1:52341/?token=8f2a1c9e4b7d3f6a0e5c8b1d2a4f7e9c
+Workspace: /home/you/project/recipes
+```
 
-Run `nx build @opencraw/studio` to build this project.
+`recipes/` can already have `.input.json`/`.output.json` files in it, or be empty — the studio's own
+**+ New recipe** writes a minimal, valid pair to start from.
 
-## Running unit tests
+## Learn more
 
-Run `nx test @opencraw/studio` to execute the unit tests via [Jest](https://jestjs.io).
+[**The OpenCraw Studio manual**](https://github.com/russoedu/open.craw/blob/main/docs/studio/manual.md)
+builds one real recipe end to end, tab by tab: picking on a live page, the Record tab's mapping, the
+document canvases (JSON, PDF, Excel/CSV, PowerPoint), recording a login, and the JSON editor.

package/dist/index.esm.js

@@ -1,9 +1,12 @@
-import { join, normalize, sep, extname, dirname, resolve } from 'node:path';
+import { join, dirname, normalize, sep, extname, resolve } from 'node:path';
 import { createServer } from 'node:http';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
-import { BODY_KINDS, BrowserClient, HttpClient, NODE_ID_ATTRIBUTE, rowsOfCells, parseXml, findDeckTables, findGridTables, analyzeTables, isDeckDocument, readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, resolveMissingPolicy, isWorkbookDocument, countMatches, matchesOf, tryParseJson, RecipeBindingError, RecipeValidationError, isPdfDocument, BrowserProfiles } from '@opencraw/core';
+import { BODY_KINDS, HttpClient, BrowserClient, NODE_ID_ATTRIBUTE, rowsOfCells, parseXml, findDeckTables, findGridTables, analyzeTables, isDeckDocument, readRecipeSource, parseInputRecipe, parseOutputRecipe, bindRecipeSet, memorySink, createCrawler, traceLine, resolveMissingPolicy, isWorkbookDocument, countMatches, matchesOf, tryParseJson, RecipeBindingError, RecipeValidationError, isPdfDocument, BrowserProfiles } from '@opencraw/core';
 import { randomBytes, createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { promisify } from 'node:util';
 import { load } from 'cheerio';
 import { readFile, writeFile } from 'node:fs/promises';
 import { describeJson } from '@opencraw/probe';
@@ -786,6 +789,85 @@ function cookieToken(header) {
   return undefined;
 }
 
+const execFileAsync = promisify(execFile);
+/** `playwright`'s own `exports` map doesn't whitelist a `./cli` subpath, so its CLI is resolved off `playwright/package.json`'s real location — the same technique `@opencraw/captcha-tesseract`'s `bundledLangPath()` uses for a bundled data path. */
+function playwrightCliPath() {
+  const require = createRequire(import.meta.url);
+  return join(dirname(require.resolve('playwright/package.json')), 'cli.js');
+}
+async function runPlaywrightInstall() {
+  await execFileAsync(process.execPath, [playwrightCliPath(), 'install', 'chromium']);
+}
+let installing;
+/**
+ * Runs `playwright install chromium` at most once per process. A failed install clears the memo,
+ * so the next browser launch attempt retries instead of remembering failure forever.
+ */
+async function runOnce(run) {
+  try {
+    await run();
+    console.log('@opencraw/studio: Chromium installed.');
+  } catch (error) {
+    installing = undefined;
+    console.log('@opencraw/studio: "playwright install chromium" failed.');
+    throw error;
+  }
+}
+function installChromiumOnce(run = runPlaywrightInstall) {
+  if (installing === undefined) {
+    console.log('@opencraw/studio: Playwright\'s Chromium is not downloaded yet — running "playwright install chromium" once...');
+    installing = runOnce(run);
+  }
+  return installing;
+}
+
+/** Recognises Playwright's own "no browser downloaded" failure so a launch can be retried after installing one, instead of surfacing Playwright's raw ASCII-art error. */
+function isMissingBrowserError(error) {
+  return error instanceof Error && /Executable doesn't exist at/.test(error.message);
+}
+
+/**
+ * Runs a browser-launching function, and — only when it fails with Playwright's own "no browser
+ * downloaded" error, only for a default chromium launch with no explicit binary configured — installs
+ * Chromium once and retries, instead of letting Playwright's raw error reach the studio's caller.
+ *
+ * An explicit `executablePath` or `OPENCRAW_CHROMIUM` means the person (or this repo's own sandbox)
+ * already chose a specific binary; a missing-browser failure there is their setup to fix, not
+ * something to silently install over.
+ */
+async function ensureBrowserLaunch(browser, launch, installChromium = installChromiumOnce) {
+  try {
+    return await launch();
+  } catch (error) {
+    if (!isMissingBrowserError(error)) throw error;
+    if (browser?.executablePath !== undefined || process.env.OPENCRAW_CHROMIUM !== undefined) {
+      throw new Error('@opencraw/studio: no browser found at the configured executable path. Check it, or unset it and let the studio install Chromium itself.', {
+        cause: error
+      });
+    }
+    if ((browser?.browserType ?? 'chromium') !== 'chromium') {
+      throw new Error(`@opencraw/studio: no ${browser?.browserType} browser found. Run "npx playwright install ${browser?.browserType}" and try again.`, {
+        cause: error
+      });
+    }
+    try {
+      await installChromium();
+    } catch (installError) {
+      throw new Error('@opencraw/studio: could not install Chromium automatically. Run "npx playwright install chromium" yourself and try again.', {
+        cause: installError
+      });
+    }
+    try {
+      return await launch();
+    } catch (retryError) {
+      if (!isMissingBrowserError(retryError)) throw retryError;
+      throw new Error('@opencraw/studio: Chromium was installed but is still not found. Run "npx playwright install chromium" yourself and try again.', {
+        cause: retryError
+      });
+    }
+  }
+}
+
 /**
  * Fetches an input recipe's start page as the engine would see it: a fresh
  * Playwright page in web mode, core's HTTP client in api mode. Returns plain
@@ -809,7 +891,7 @@ async function fetchStartPage(input, browser) {
   return input.mode === 'web' ? fetchWeb(point.url, browser) : fetchApi(point.url);
 }
 async function fetchWeb(url, browser) {
-  const client = await BrowserClient.launch(browser);
+  const client = await ensureBrowserLaunch(browser, () => BrowserClient.launch(browser));
   try {
     const session = await client.newSession();
     try {
@@ -985,7 +1067,7 @@ async function takeSnapshot(input, stepPath, browser) {
   return input.mode === 'web' ? snapshotWeb(point.url, browser) : snapshotApi(point.url);
 }
 async function snapshotWeb(url, browser) {
-  const client = await BrowserClient.launch(browser);
+  const client = await ensureBrowserLaunch(browser, () => BrowserClient.launch(browser));
   try {
     const session = await client.newSession();
     try {
@@ -2969,7 +3051,7 @@ async function responsesSeen(input, stepPath, browser) {
   if (input.mode !== 'web') return [];
   const point = input.start[0];
   if (point === undefined) throw new Error(`recipe "${input.id}" has no start point`);
-  const client = await BrowserClient.launch(browser);
+  const client = await ensureBrowserLaunch(browser, () => BrowserClient.launch(browser));
   try {
     const session = await client.newSession();
     try {
@@ -3957,7 +4039,7 @@ async function openRecorderSession(options, callbacks) {
     ...options.browser,
     headless: false
   });
-  const session = await profiles.open(RECORDER_PROFILE_NAME, {}, {});
+  const session = await ensureBrowserLaunch(options.browser, () => profiles.open(RECORDER_PROFILE_NAME, {}, {}));
   const context = session.context;
   const steps = [];
   let closed = false;

package/dist/src/browser-provisioning/ensure-browser-launch.use-case.d.ts

@@ -0,0 +1,12 @@
+import type { BrowserSessionConfig } from '@opencraw/core';
+/**
+ * Runs a browser-launching function, and — only when it fails with Playwright's own "no browser
+ * downloaded" error, only for a default chromium launch with no explicit binary configured — installs
+ * Chromium once and retries, instead of letting Playwright's raw error reach the studio's caller.
+ *
+ * An explicit `executablePath` or `OPENCRAW_CHROMIUM` means the person (or this repo's own sandbox)
+ * already chose a specific binary; a missing-browser failure there is their setup to fix, not
+ * something to silently install over.
+ */
+export declare function ensureBrowserLaunch<T>(browser: BrowserSessionConfig | undefined, launch: () => Promise<T>, installChromium?: (run?: () => Promise<void>) => Promise<void>): Promise<T>;
+//# sourceMappingURL=ensure-browser-launch.use-case.d.ts.map

package/dist/src/browser-provisioning/index.d.ts

@@ -0,0 +1,2 @@
+export { ensureBrowserLaunch } from './ensure-browser-launch.use-case.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/browser-provisioning/install-chromium.use-case.d.ts

@@ -0,0 +1,2 @@
+export declare function installChromiumOnce(run?: () => Promise<void>): Promise<void>;
+//# sourceMappingURL=install-chromium.use-case.d.ts.map

package/dist/src/browser-provisioning/missing-browser.policy.d.ts

@@ -0,0 +1,3 @@
+/** Recognises Playwright's own "no browser downloaded" failure so a launch can be retried after installing one, instead of surfacing Playwright's raw ASCII-art error. */
+export declare function isMissingBrowserError(error: unknown): boolean;
+//# sourceMappingURL=missing-browser.policy.d.ts.map