@opencraw/cli 0.1.12 → 0.1.14

package/dist/index.esm.js

@@ -12,6 +12,8 @@ Commands
   run <recipe files or directories...>        Crawl. Records go to --out as JSON Lines, or to stdout.
   probe <url>                                 Fetch a page and report where its data lives.
   diff <previous.jsonl> <current.jsonl>       Compare two runs' records by key: added, removed, changed.
+  studio [folder]                             Open a recipe folder in the browser: run samples, read
+                                               the trace next to the page (needs @opencraw/studio).
 
 Options for run
   --out <file>        Write records to this JSON Lines file (default: stdout).
@@ -236,6 +238,14 @@ function parseArguments(argv, env = {}) {
           options
         };
       }
+    case 'studio':
+      {
+        if (rest.length > 1) throw new Error('studio takes at most one folder');
+        return {
+          name: 'studio',
+          folder: rest[0]
+        };
+      }
     default:
       {
         throw new Error(`unknown command "${name}"`);
@@ -1403,6 +1413,37 @@ function loadErrorLines(error) {
   return [error instanceof Error ? error.message : String(error)];
 }
 
+/**
+ * Runs `opencraw studio [folder]`: imports `@opencraw/studio` lazily and
+ * delegates to its own `main`, which starts the server, prints the URL with
+ * the token, and keeps running until interrupted (Ctrl+C) — the cli's own
+ * call does not return before that. `@opencraw/studio` is an optional peer
+ * dependency (`peerDependenciesMeta`), never a hard one: the cli stays light
+ * for callers who only need to crawl. When it is not installed, this prints
+ * how to add it instead of letting a raw `ERR_MODULE_NOT_FOUND` stack trace
+ * through.
+ *
+ * @param folder - The recipe folder to open; `@opencraw/studio`'s own default (the current directory) when omitted.
+ * @param terminal - Where output goes.
+ * @param importStudio - How the module is loaded; the real dynamic `import()` by default, replaced in tests.
+ * @returns The exit code: 0 once the server has stopped, 1 when `@opencraw/studio` is missing.
+ */
+async function runStudio(folder, terminal, importStudio = () => import('@opencraw/studio')) {
+  let studio;
+  try {
+    studio = await importStudio();
+  } catch (error) {
+    if (!isModuleNotFound(error)) throw error;
+    terminal.err('the studio is not installed: run `npm install @opencraw/studio`, then try again');
+    return 1;
+  }
+  await studio.main(folder === undefined ? [] : [folder]);
+  return 0;
+}
+function isModuleNotFound(error) {
+  return error instanceof Error && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND';
+}
+
 /**
  * Loads and binds recipe files, printing every problem with its JSON path.
  *
@@ -1496,6 +1537,10 @@ async function main(argv, terminal) {
       {
         return diffFiles(command, terminal);
       }
+    case 'studio':
+      {
+        return runStudio(command.folder, terminal);
+      }
   }
 }
 
@@ -1511,5 +1556,5 @@ function processTerminal() {
   };
 }
 
-export { USAGE, diffReport, findData, loadForRun, loadHooks, loadPlugins, main, parseArguments, probeReport, probeUrl, processTerminal, readRecipeFiles, resolveAccess, writeChanges };
+export { USAGE, diffReport, findData, loadForRun, loadHooks, loadPlugins, main, parseArguments, probeReport, probeUrl, processTerminal, readRecipeFiles, resolveAccess, runStudio, writeChanges };
 //# sourceMappingURL=index.esm.js.map

package/dist/src/arguments/command.contract.d.ts

@@ -65,5 +65,9 @@ export type Command = {
     /** Also render the page in a browser and watch the JSON it fetches. */
     browser: boolean;
     options: CommonOptions;
+} | {
+    name: 'studio';
+    /** The recipe folder to open; the current directory when not given. */
+    folder?: string;
 };
 //# sourceMappingURL=command.contract.d.ts.map

package/dist/src/arguments/parse-arguments.algorithm.d.ts

@@ -1,5 +1,5 @@
 import type { Command } from './command.contract.js';
-export declare const USAGE = "opencraw <command> [options]\n\nCommands\n  validate <recipe files or directories...>   Parse and bind the recipes; list every problem with its path.\n  run <recipe files or directories...>        Crawl. Records go to --out as JSON Lines, or to stdout.\n  probe <url>                                 Fetch a page and report where its data lives.\n  diff <previous.jsonl> <current.jsonl>       Compare two runs' records by key: added, removed, changed.\n\nOptions for run\n  --out <file>        Write records to this JSON Lines file (default: stdout).\n  --append            Keep what --out holds and add to it (each line carries _key).\n  --resume            Skip records --out already has (needs --append).\n  --only <id>         Run only this input recipe (repeatable).\n  --dry-run           One record per input, printed with the scope it was mapped from.\n  --trace             Print the crawl trace to stderr.\n  --headed            Show the browser.\n  --parallel <n>      Run this many input recipes at once (default 1). Iterations inside a recipe\n                      follow its limits.concurrency.\n  --retries <n>       Tries per request that fails in passing (connection, timeout, 429, 5xx), for\n                      recipes whose limits.retry says nothing. Default 3; 1 turns retrying off.\n  --profiles <dir>    Where recipes' session.browserProfile profiles live (or OPENCRAW_PROFILES;\n                      default .opencraw/profiles).\n  --diff <file>       Compare this run's records with a previous run's JSON Lines file (it may be\n                      --out itself: it is read before the crawl). Keys come from the output recipe.\n  --host-delay <ms>   At least this long between two requests to one site, across every recipe.\n  --host-concurrency <n>\n                      At most this many requests to one site in flight, across every recipe.\n                      Both override the access config's \"throttle\" defaults.\n\nOptions for diff\n  --key <a,b>         The fields that identify a record (default: each line's _key).\n  --ignore <a,b>      Fields left out of the comparison (a date the crawl stamps, say).\n  --changes <file>    Also write every change as a JSON line (run --diff takes it too).\n\nOptions for probe\n  --browser           Also render the page in a browser and list the JSON it fetches.\n\nOptions for both\n  --browser-path <p>  A browser binary other than the one Playwright installed (or OPENCRAW_CHROMIUM).\n  --insecure-tls      Accept an intercepting proxy's certificate (or OPENCRAW_INSECURE_TLS=1).\n  --user-agent <ua>   The user agent to send.\n  --access <file>     An access config: proxy profiles, credentials as {{env.NAME}} (or OPENCRAW_ACCESS).\n  --access-profile <name>\n                      The access profile to use when a recipe names none.\n  --plugins <file>    A JavaScript module exporting hooks (the recipes' hook steps and transforms),\n                      accessPlugins (for { kind: \"plugin\" } access profiles) and captchaSolvers\n                      (for session.captcha and captcha steps); --hooks, or OPENCRAW_PLUGINS /\n                      OPENCRAW_HOOKS. It runs as your code: trust it.\n  --help, --version";
+export declare const USAGE = "opencraw <command> [options]\n\nCommands\n  validate <recipe files or directories...>   Parse and bind the recipes; list every problem with its path.\n  run <recipe files or directories...>        Crawl. Records go to --out as JSON Lines, or to stdout.\n  probe <url>                                 Fetch a page and report where its data lives.\n  diff <previous.jsonl> <current.jsonl>       Compare two runs' records by key: added, removed, changed.\n  studio [folder]                             Open a recipe folder in the browser: run samples, read\n                                               the trace next to the page (needs @opencraw/studio).\n\nOptions for run\n  --out <file>        Write records to this JSON Lines file (default: stdout).\n  --append            Keep what --out holds and add to it (each line carries _key).\n  --resume            Skip records --out already has (needs --append).\n  --only <id>         Run only this input recipe (repeatable).\n  --dry-run           One record per input, printed with the scope it was mapped from.\n  --trace             Print the crawl trace to stderr.\n  --headed            Show the browser.\n  --parallel <n>      Run this many input recipes at once (default 1). Iterations inside a recipe\n                      follow its limits.concurrency.\n  --retries <n>       Tries per request that fails in passing (connection, timeout, 429, 5xx), for\n                      recipes whose limits.retry says nothing. Default 3; 1 turns retrying off.\n  --profiles <dir>    Where recipes' session.browserProfile profiles live (or OPENCRAW_PROFILES;\n                      default .opencraw/profiles).\n  --diff <file>       Compare this run's records with a previous run's JSON Lines file (it may be\n                      --out itself: it is read before the crawl). Keys come from the output recipe.\n  --host-delay <ms>   At least this long between two requests to one site, across every recipe.\n  --host-concurrency <n>\n                      At most this many requests to one site in flight, across every recipe.\n                      Both override the access config's \"throttle\" defaults.\n\nOptions for diff\n  --key <a,b>         The fields that identify a record (default: each line's _key).\n  --ignore <a,b>      Fields left out of the comparison (a date the crawl stamps, say).\n  --changes <file>    Also write every change as a JSON line (run --diff takes it too).\n\nOptions for probe\n  --browser           Also render the page in a browser and list the JSON it fetches.\n\nOptions for both\n  --browser-path <p>  A browser binary other than the one Playwright installed (or OPENCRAW_CHROMIUM).\n  --insecure-tls      Accept an intercepting proxy's certificate (or OPENCRAW_INSECURE_TLS=1).\n  --user-agent <ua>   The user agent to send.\n  --access <file>     An access config: proxy profiles, credentials as {{env.NAME}} (or OPENCRAW_ACCESS).\n  --access-profile <name>\n                      The access profile to use when a recipe names none.\n  --plugins <file>    A JavaScript module exporting hooks (the recipes' hook steps and transforms),\n                      accessPlugins (for { kind: \"plugin\" } access profiles) and captchaSolvers\n                      (for session.captcha and captcha steps); --hooks, or OPENCRAW_PLUGINS /\n                      OPENCRAW_HOOKS. It runs as your code: trust it.\n  --help, --version";
 /**
  * Turns argv into a command.
  *

package/dist/src/index.d.ts

@@ -13,4 +13,6 @@ export type { CommonOptions } from './arguments/index.js';
 export { resolveAccess } from './access/index.js';
 export { loadHooks, loadPlugins } from './hooks-module/index.js';
 export type { PluginModule } from './hooks-module/index.js';
+export { runStudio } from './studio/index.js';
+export type { StudioModule } from './studio/index.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,3 @@
+export { runStudio } from './run-studio.use-case.js';
+export type { StudioModule } from './run-studio.use-case.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,22 @@
+import type { Terminal } from '../terminal/index.js';
+/** The one export the cli needs from `@opencraw/studio`. */
+export interface StudioModule {
+    main: (argv: readonly string[]) => Promise<void>;
+}
+/**
+ * Runs `opencraw studio [folder]`: imports `@opencraw/studio` lazily and
+ * delegates to its own `main`, which starts the server, prints the URL with
+ * the token, and keeps running until interrupted (Ctrl+C) — the cli's own
+ * call does not return before that. `@opencraw/studio` is an optional peer
+ * dependency (`peerDependenciesMeta`), never a hard one: the cli stays light
+ * for callers who only need to crawl. When it is not installed, this prints
+ * how to add it instead of letting a raw `ERR_MODULE_NOT_FOUND` stack trace
+ * through.
+ *
+ * @param folder - The recipe folder to open; `@opencraw/studio`'s own default (the current directory) when omitted.
+ * @param terminal - Where output goes.
+ * @param importStudio - How the module is loaded; the real dynamic `import()` by default, replaced in tests.
+ * @returns The exit code: 0 once the server has stopped, 1 when `@opencraw/studio` is missing.
+ */
+export declare function runStudio(folder: string | undefined, terminal: Terminal, importStudio?: () => Promise<StudioModule>): Promise<number>;
+//# sourceMappingURL=run-studio.use-case.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencraw/cli",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "type": "module",
   "main": "./dist/index.esm.js",
   "module": "./dist/index.esm.js",
@@ -24,9 +24,17 @@
     "!**/*.js.map"
   ],
   "dependencies": {
-    "@opencraw/core": "^0.1.12",
+    "@opencraw/core": "^0.1.14",
     "playwright": "^1.63.0"
   },
+  "peerDependencies": {
+    "@opencraw/studio": "^0.0.3"
+  },
+  "peerDependenciesMeta": {
+    "@opencraw/studio": {
+      "optional": true
+    }
+  },
   "publishConfig": {
     "access": "public"
   },