@browserless/cli 13.16.4 → 14.0.0

package/README.md

@@ -51,6 +51,36 @@ The `@browserless/cli` package allows you to:
 | `ping <url>` | Get response info: status code, redirects, headers |
 | `status <url>` | Get the HTTP status code |
 | `goto <url>` | Navigate to a URL and return page/response info |
+| `exec <file>` | Run a script file against a new page and print what it returns |
+
+### Exec examples
+
+`exec` takes a file instead of a URL. The file exports a function (CommonJS
+`module.exports` or ES module `export default`). The CLI opens a page and calls
+the function with `{ page, browserless, opts }`:
+
+- `page`: a new Puppeteer page in a fresh browser context.
+- `browserless`: the browserless context, for `browserless.goto(page, { url })` and the rest of the API.
+- `opts`: the command-line flags, plus the CLI default `codeScheme`. `--headless` and `--verbose` are consumed by the CLI and not passed. `--timeout` is passed and also sets the browser timeout.
+
+```js
+// title.js
+module.exports = async ({ page, browserless, opts }) => {
+  await browserless.goto(page, { url: opts.url })
+  return { title: await page.title() }
+}
+```
+
+```sh
+browserless exec title.js --url=https://example.com
+```
+
+The file path resolves from the current directory. A returned string is printed
+as is and any other value as indented JSON. `undefined` and binary values
+(buffers and typed arrays, such as the result of `page.screenshot()`) print
+nothing, so write binary output to a file from the script. The file is checked
+before the browser starts. A thrown error is
+printed and the process exits with code 1.
 
 ### Capture examples
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@browserless/cli",
   "description": "Command-line interface for headless browser automation. Take screenshots, generate PDFs, and extract content from websites.",
   "homepage": "https://browserless.js.org",
-  "version": "13.16.4",
+  "version": "14.0.0",
   "bin": {
     "browserless": "src/index.js"
   },
@@ -34,9 +34,9 @@
     "web-scraping"
   ],
   "dependencies": {
-    "@browserless/capture": "13.16.4",
+    "@browserless/capture": "14.0.0",
     "beauty-error": "~1.2.23",
-    "browserless": "13.16.4",
+    "browserless": "14.0.0",
     "dark-mode": "~3.0.0",
     "dset": "~3.1.4",
     "mri": "~1.2.0",
@@ -49,6 +49,9 @@
     "term-img": "~5.0.0",
     "unique-random-array": "~3.0.0"
   },
+  "devDependencies": {
+    "ava": "5"
+  },
   "engines": {
     "node": ">= 24"
   },
@@ -56,8 +59,12 @@
     "src"
   ],
   "scripts": {
-    "test": "exit 0"
+    "test": "ava"
   },
   "license": "MIT",
-  "gitHead": "a47151aed56be56d367cb6e5652434c425ef4f85"
+  "ava": {
+    "timeout": "2m",
+    "workerThreads": false
+  },
+  "gitHead": "bf10b39022a6cc44cccd545756f162bed90dd589"
 }

package/src/commands/exec.js

@@ -0,0 +1,36 @@
+'use strict'
+
+const { pathToFileURL } = require('url')
+const path = require('path')
+const fs = require('fs')
+
+const resolveFile = file => {
+  if (!file) throw new TypeError('exec requires a script file: browserless exec <file>')
+  const filepath = path.resolve(file)
+  if (!fs.existsSync(filepath)) throw new TypeError(`Script file not found: ${filepath}`)
+  return filepath
+}
+
+const loadScript = async filepath => {
+  const { default: script } = await import(pathToFileURL(filepath))
+  const run = typeof script === 'function' ? script : script?.default
+  if (typeof run !== 'function') throw new TypeError(`${filepath} must export a function.`)
+  return run
+}
+
+const toBuffer = view => Buffer.from(view.buffer, view.byteOffset, view.byteLength)
+
+const serialize = result => {
+  if (result === undefined) return ''
+  if (typeof result === 'string') return result
+  if (ArrayBuffer.isView(result)) return toBuffer(result)
+  return JSON.stringify(result, null, 2)
+}
+
+module.exports = async ({ file, browserless, opts }) => {
+  const run = await loadScript(file)
+  const page = await browserless.page()
+  return [serialize(await run({ page, browserless, opts }))]
+}
+
+module.exports.resolveFile = resolveFile

package/src/help.js

@@ -9,6 +9,7 @@ const printCommand = command => `⬩ ${command.replace(path.extname(command), ''
 module.exports = commands => `
 Usage
   $ browserless <command> <url> [flags]
+  $ browserless exec <file> [flags]
 
 Commands
   ${gray(commands.map(printCommand).join(EOL + '  '))}`

package/src/index.js

@@ -62,9 +62,11 @@ const isPageReady = ({ title = '', bodyText = '', url = '', isWhite = false } =
 const run = async () => {
   if (cli.input.length === 0) return cli.showHelp()
   spinner.start()
-  const [command, rawUrl] = cli.input
-  const url = new URL(rawUrl).toString()
+  const [command, input] = cli.input
   const fn = require(`./commands/${command}`)
+  const target = fn.resolveFile
+    ? { file: fn.resolveFile(input) }
+    : { url: new URL(input).toString() }
   const launchOpts = { headless }
 
   if (command === 'capture') {
@@ -87,7 +89,7 @@ const run = async () => {
   const browserless = await browser.createContext(
     launchOpts.timeout != null ? { timeout: launchOpts.timeout } : undefined
   )
-  return fn({ url, browserless, opts: parsedOpts, isPageReady })
+  return fn({ ...target, browserless, opts: parsedOpts, isPageReady })
 }
 
 run()