@maeris/maeris-player 0.1.0 → 0.1.2

package/README.md

@@ -1,43 +1,88 @@
 # Maeris Player
 
-Local Playwright-based runner for Maeris "Run in Browser".
+Local Playwright-based runner for Maeris **Run in Browser**.
+Start the runner once, then trigger runs from the Maeris web app.
 
-## Goals
-- Replay recorder steps through the Chrome extension in a local browser window.
-- Mirror the cloud runner as closely as possible (status updates, assertions, screenshots).
-- Provide a lightweight CLI or UI shim that interfaces with the extension via WebSocket messages.
+## Prerequisites
+- Node.js 18+
+- macOS / Windows / Linux
 
-## Architecture
-1. **CLI (`src/cli/run.js`)** starts a WebSocket server and waits for the UI to send `RUN_STEPS`, or replays a local JSON file when `--steps` is provided.
-2. **Runner core (`src/runner/index.js`)** normalizes steps, opens Playwright, streams `STEP_*`/`REPLAY_*` events over WebSocket (port 8090).
-3. **Playwright adapter (`src/runner/playwrightAdapter.js`)** performs clicks, inputs, navigations, assertions; captures screenshots on failure.
-4. **Event contract (`src/runner/events.js`)** defines the message names (`STEP_STARTED`, `STEP_PASSED`, `STEP_FAILED`, `NAVIGATION`, `REPLAY_COMPLETE`, etc.).
-
-## Running locally
+## Quick start
 ```bash
-npm install
+npx @maeris/maeris-player
+```
 
-# listen for Run in Browser traffic from the web app (headed by default)
-npm start
+This starts the local runner on `ws://localhost:8090` (headed by default).  
+Keep it running, then click **Run in Browser** in the Maeris UI.
 
-# replay a recorded JSON file
-npm start -- --steps path/to/recorded.json --url https://demo-app/ --browser chromium
+If you prefer a global install:
+```bash
+npm i -g @maeris/maeris-player
+maeris-player
 ```
 
-## Usage via npm
+## How users run tests
+1. Start the runner:
+   ```bash
+   npx @maeris/maeris-player
+   ```
+2. Open the Maeris app and click **Run in Browser**.
+3. The runner opens a local browser window and executes the steps.
+
+## Production usage options
+### Option A — Extension proxy (recommended)
+Works from `https://` without TLS.  
+The Maeris extension connects to the local runner and proxies events.
+
+1. Install the Maeris Chrome extension.
+2. Start the runner:
+   ```bash
+   npx @maeris/maeris-player
+   ```
+3. Click **Run in Browser** in the Maeris app.
+
+### Option B — TLS direct (no extension)
+Connect directly from an `https://` web app using `wss://localhost`.
+
 ```bash
+npx @maeris/maeris-player setup-cert
+
+# macOS/Linux
+MAERIS_TLS_CERT="$HOME/.maeris-player/certs/localhost.cert.pem" \
+MAERIS_TLS_KEY="$HOME/.maeris-player/certs/localhost.key.pem" \
 npx @maeris/maeris-player
 ```
 
-This starts the local runner on `ws://localhost:8090`. Keep it running, then click **Run in Browser** in the Maeris UI.
+Then trust the certificate as instructed by `setup-cert`.  
+The runner will listen on `wss://localhost:8090`.
+
+Tip: if you used the default cert location, you can also run:
+```bash
+maeris-player --tls
+```
+
+## Troubleshooting
+- If the Maeris web app shows "Extension required" on an `https://` page:
+  - use the Maeris Player (TLS) option in the modal, or
+  - install the extension (Option A).
+- If runs don't start, confirm the runner is listening:
+  - `ws://localhost:8090` for non-TLS
+  - `wss://localhost:8090` for TLS
 
-## HTTPS / WSS support (for prod without extension)
-If you want to connect from an `https://` web app directly to the runner, start it with TLS:
+## Maintainers
+### Publishing
+This is published as a public scoped package (`@maeris/maeris-player`).
 
+If your npm org enforces 2FA, you will need either:
+- an OTP at publish time (`npm publish --otp=123456`), or
+- a granular access token with "bypass 2FA for publish" enabled.
+
+First publish (or if npm requires it for scoped packages):
 ```bash
-npx @maeris/maeris-player setup-cert
-MAERIS_TLS_CERT=/path/to/cert.pem MAERIS_TLS_KEY=/path/to/key.pem npx @maeris/maeris-player
+npm publish --access public
 ```
 
-The runner will listen on `wss://localhost:8090`. You will need to trust the certificate in your OS/browser.
-# maeris-player
+### Architecture (for contributors)
+1. `src/cli/run.js` starts a WebSocket server and waits for the UI to send `RUN_STEPS`, or replays a local JSON file when `--steps` is provided.
+2. `src/runner/index.js` normalizes steps, opens Playwright, and streams `STEP_*` / `REPLAY_*` events over WebSocket (port 8090).
+3. `src/runner/playwrightAdapter.js` performs clicks, inputs, navigations, assertions, and captures screenshots on failure.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maeris/maeris-player",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "description": "Local Playwright-based runner for Maeris",
   "scripts": {
@@ -12,11 +12,17 @@
   "bin": {
     "maeris-player": "src/cli/run.js"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "playwright": "^1.44.0",
     "selfsigned": "^2.4.1",
     "ws": "^8.13.0",
-    "yargs": "^20.0.0"
+    "yargs": "^17.7.2"
   }
 }

package/src/cli/run.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const yargs = require('yargs/yargs');
 const { hideBin } = require('yargs/helpers');
 const { Runner } = require('../runner');
@@ -38,6 +39,12 @@ const argv = yargs(hideBin(process.argv))
     default: true,
     describe: 'Start the runner server and wait for UI commands',
   })
+  .option('tls', {
+    type: 'boolean',
+    default: false,
+    describe:
+      'Start in TLS mode for HTTPS pages (uses ~/.maeris-player/certs unless MAERIS_TLS_* env vars are set)',
+  })
   .option('cert-dir', {
     type: 'string',
     describe: 'Directory to store TLS certs for setup-cert',
@@ -45,6 +52,21 @@ const argv = yargs(hideBin(process.argv))
   .help()
   .parse();
 
+function applyTlsDefaults() {
+  if (process.env.MAERIS_TLS_CERT && process.env.MAERIS_TLS_KEY) return;
+  const baseDir = path.join(os.homedir(), '.maeris-player', 'certs');
+  const certPath = path.join(baseDir, 'localhost.cert.pem');
+  const keyPath = path.join(baseDir, 'localhost.key.pem');
+  if (fs.existsSync(certPath) && fs.existsSync(keyPath)) {
+    process.env.MAERIS_TLS_CERT = certPath;
+    process.env.MAERIS_TLS_KEY = keyPath;
+    return;
+  }
+  throw new Error(
+    `TLS cert not found. Run \"maeris-player setup-cert\" first (expected ${certPath} and ${keyPath}).`
+  );
+}
+
 function loadSteps(filePath) {
   const resolved = path.resolve(filePath);
   if (!fs.existsSync(resolved)) {
@@ -65,6 +87,10 @@ function loadSteps(filePath) {
       return;
     }
 
+    if (argv.tls) {
+      applyTlsDefaults();
+    }
+
     const steps = argv.steps ? loadSteps(argv.steps) : [];
     const options = {
       steps,

package/src/cli/setup-cert.js

@@ -73,6 +73,8 @@ function printInstructions({ certPath, keyPath }) {
   console.log(`  ${linux}`);
   console.log('\nThen start the runner with:');
   console.log(`  MAERIS_TLS_CERT="${certPath}" MAERIS_TLS_KEY="${keyPath}" npx @maeris/maeris-player\n`);
+  console.log('Or (if you installed globally):');
+  console.log('  maeris-player --tls\n');
 }
 
 module.exports = {

package/src/runner/playwrightAdapter.js

@@ -42,7 +42,7 @@ class PlaywrightAdapter extends EventEmitter {
           await this.performStep(this.page, step);
           this.emit('event', createStepPayload(EVENTS.STEP_PASSED, step));
         } catch (error) {
-          const screenshot = await page.screenshot({ fullPage: true });
+          const screenshot = await this.page.screenshot({ fullPage: true });
           this.emit(
             'event',
             createStepPayload(EVENTS.STEP_FAILED, step, {
@@ -119,15 +119,23 @@ class PlaywrightAdapter extends EventEmitter {
   }
 
   applyNth(locator, step) {
+    const parseNth = (value) => {
+      if (typeof value === 'number' && Number.isFinite(value)) return value;
+      if (typeof value === 'string' && value.trim() !== '') {
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isFinite(parsed)) return parsed;
+      }
+      return null;
+    };
+
     const nth =
-      typeof step.nth_appearance === 'number'
-        ? step.nth_appearance
-        : typeof step.nthAppearance === 'number'
-        ? step.nthAppearance
-        : typeof step.step_index === 'number'
-        ? step.step_index
-        : null;
-    return nth !== null ? locator.nth(nth) : locator;
+      parseNth(step.nth_appearance) ??
+      parseNth(step.nthAppearance) ??
+      parseNth(step.step_index);
+
+    // If nth is missing, use first() to avoid strict-mode violations on broad selectors.
+    if (nth === null || nth < 0) return locator.first();
+    return locator.nth(nth);
   }
 
   async performStep(page, step) {