@maeris/maeris-player 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# Maeris Player
+
+Local Playwright-based runner for Maeris "Run in Browser".
+
+## 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.
+
+## 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
+```bash
+npm install
+
+# listen for Run in Browser traffic from the web app (headed by default)
+npm start
+
+# replay a recorded JSON file
+npm start -- --steps path/to/recorded.json --url https://demo-app/ --browser chromium
+```
+
+## Usage via npm
+```bash
+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.
+
+## 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:
+
+```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
+```
+
+The runner will listen on `wss://localhost:8090`. You will need to trust the certificate in your OS/browser.
+# maeris-player

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@maeris/maeris-player",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Local Playwright-based runner for Maeris",
+  "scripts": {
+    "start": "node src/cli/run.js",
+    "serve": "node src/runner/server.js",
+    "lint": "echo \"No lint yet\"",
+    "test": "echo \"No tests yet\""
+  },
+  "bin": {
+    "maeris-player": "src/cli/run.js"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "playwright": "^1.44.0",
+    "selfsigned": "^2.4.1",
+    "ws": "^8.13.0",
+    "yargs": "^20.0.0"
+  }
+}

package/src/cli/run.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+const yargs = require('yargs/yargs');
+const { hideBin } = require('yargs/helpers');
+const { Runner } = require('../runner');
+const { setupCert, printInstructions } = require('./setup-cert');
+
+const argv = yargs(hideBin(process.argv))
+  .option('steps', {
+    alias: 's',
+    type: 'string',
+    describe: 'Path to the recorded step payload (JSON format)',
+  })
+  .option('url', {
+    alias: 'u',
+    type: 'string',
+    describe: 'Starting URL for the run',
+  })
+  .option('browser', {
+    alias: 'b',
+    type: 'string',
+    default: 'chromium',
+    describe: 'Playwright browser to launch',
+  })
+  .option('headed', {
+    type: 'boolean',
+    default: true,
+    describe: 'Run browser in headed (visible) mode',
+  })
+  .option('run-id', {
+    alias: 'r',
+    type: 'string',
+    describe: 'External run identifier for tracking',
+  })
+  .option('serve', {
+    type: 'boolean',
+    default: true,
+    describe: 'Start the runner server and wait for UI commands',
+  })
+  .option('cert-dir', {
+    type: 'string',
+    describe: 'Directory to store TLS certs for setup-cert',
+  })
+  .help()
+  .parse();
+
+function loadSteps(filePath) {
+  const resolved = path.resolve(filePath);
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`Step file not found: ${resolved}`);
+  }
+  const raw = fs.readFileSync(resolved, 'utf8');
+  const parsed = JSON.parse(raw);
+  if (Array.isArray(parsed)) return parsed;
+  if (parsed && Array.isArray(parsed.steps)) return parsed.steps;
+  return [];
+}
+
+(async () => {
+  try {
+    if (argv._?.[0] === 'setup-cert') {
+      const result = await setupCert({ certDir: argv['cert-dir'] });
+      printInstructions(result);
+      return;
+    }
+
+    const steps = argv.steps ? loadSteps(argv.steps) : [];
+    const options = {
+      steps,
+      startUrl: argv.url,
+      browser: argv.browser,
+      headless: !argv.headed,
+      runId: argv['run-id'] || `local_${Date.now()}`,
+    };
+    console.log('Runner starting with', steps.length, 'steps');
+    const runner = new Runner(options);
+    runner.on('event', (payload) => {
+      console.log('[runner event]', payload.type, payload.stepIndex ?? '', payload.message || payload.url || '');
+    });
+    if (argv.serve) {
+      runner.startServer();
+    }
+    if (steps.length > 0) {
+      await runner.startRun({
+        steps,
+        startUrl: argv.url,
+        browser: argv.browser,
+        runId: options.runId,
+        headless: options.headless,
+      });
+    } else if (argv.serve) {
+      console.log('Waiting for UI RUN_STEPS command...');
+    } else {
+      console.log('No steps provided. Exiting.');
+    }
+  } catch (error) {
+    console.error('Runner failed:', error);
+    process.exit(1);
+  }
+})();

package/src/cli/setup-cert.js

@@ -0,0 +1,81 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const selfsigned = require('selfsigned');
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+function writeFile(filepath, contents) {
+  fs.writeFileSync(filepath, contents, { encoding: 'utf8', mode: 0o600 });
+}
+
+function buildCertOptions() {
+  return {
+    keySize: 2048,
+    days: 3650,
+    algorithm: 'sha256',
+    extensions: [
+      { name: 'basicConstraints', cA: true },
+      { name: 'keyUsage', keyCertSign: true, digitalSignature: true, keyEncipherment: true },
+      { name: 'extKeyUsage', serverAuth: true },
+      {
+        name: 'subjectAltName',
+        altNames: [
+          { type: 2, value: 'localhost' },
+          { type: 7, ip: '127.0.0.1' }
+        ]
+      }
+    ]
+  };
+}
+
+function buildAttrs() {
+  return [
+    { name: 'commonName', value: 'maeris-player.local' },
+    { name: 'organizationName', value: 'Maeris' },
+    { name: 'organizationalUnitName', value: 'Local Runner' }
+  ];
+}
+
+async function setupCert({ certDir }) {
+  const baseDir = certDir || path.join(os.homedir(), '.maeris-player', 'certs');
+  ensureDir(baseDir);
+
+  const keyPath = path.join(baseDir, 'localhost.key.pem');
+  const certPath = path.join(baseDir, 'localhost.cert.pem');
+
+  const attrs = buildAttrs();
+  const opts = buildCertOptions();
+  const { private: key, cert } = selfsigned.generate(attrs, opts);
+
+  writeFile(keyPath, key);
+  writeFile(certPath, cert);
+
+  return { certPath, keyPath, baseDir };
+}
+
+function printInstructions({ certPath, keyPath }) {
+  const mac = `sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain "${certPath}"`;
+  const win = `certutil -addstore -f "ROOT" "${certPath}"`;
+  const linux = `sudo cp "${certPath}" /usr/local/share/ca-certificates/maeris-player.crt && sudo update-ca-certificates`;
+
+  console.log('\n✅ Local TLS cert generated.');
+  console.log(`   cert: ${certPath}`);
+  console.log(`   key:  ${keyPath}\n`);
+  console.log('Next: trust the cert in your OS (one-time).');
+  console.log('\nmacOS:');
+  console.log(`  ${mac}`);
+  console.log('\nWindows (Admin PowerShell):');
+  console.log(`  ${win}`);
+  console.log('\nLinux (Debian/Ubuntu):');
+  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`);
+}
+
+module.exports = {
+  setupCert,
+  printInstructions,
+};

package/src/extension/bridge.js

@@ -0,0 +1,17 @@
+const WebSocket = require('ws');
+const { EVENTS } = require('../runner/events');
+
+module.exports = function attachExtensionBridge({ url = 'ws://localhost:8090' }) {
+  const socket = new WebSocket(url);
+  socket.on('open', () => {
+    console.log('[extension bridge] connected to runner');
+  });
+  socket.on('message', (message) => {
+    const payload = JSON.parse(message);
+    console.log('[extension bridge] event', payload.type);
+    if (payload.type === EVENTS.SERVER_READY) {
+      // handshake with extension UI if needed
+    }
+  });
+  return socket;
+};

package/src/runner/events.js

@@ -0,0 +1,31 @@
+const EVENTS = {
+  SERVER_READY: 'SERVER_READY',
+  REPLAY_STARTED: 'REPLAY_STARTED',
+  REPLAY_COMPLETE: 'REPLAY_COMPLETE',
+  REPLAY_ERROR: 'REPLAY_ERROR',
+  STEP_STARTED: 'STEP_STARTED',
+  STEP_PASSED: 'STEP_PASSED',
+  STEP_FAILED: 'STEP_FAILED',
+  NAVIGATION: 'NAVIGATION',
+  RUN_STEPS: 'RUN_STEPS',
+  STOP_RUN: 'STOP_RUN',
+};
+
+function createStepPayload(type, step, meta = {}) {
+  return {
+    type,
+    timestamp: Date.now(),
+    stepIndex: step.index,
+    stepId: step.id,
+    fluId: step.flu_id,
+    componentId: step.component_id,
+    selector: step.selector,
+    stepLabel: step.name || step.label || step.component_label,
+    ...meta,
+  };
+}
+
+module.exports = {
+  EVENTS,
+  createStepPayload,
+};

package/src/runner/index.js

@@ -0,0 +1,133 @@
+const EventEmitter = require('events');
+const fs = require('fs');
+const https = require('https');
+const WebSocket = require('ws');
+const PlaywrightAdapter = require('./playwrightAdapter');
+const { EVENTS } = require('./events');
+const normalizeSteps = require('../utils/normalizeSteps');
+
+const EVENT_PORT = process.env.MAERIS_RUNNER_PORT || 8090;
+
+class Runner extends EventEmitter {
+  constructor(options = {}) {
+    super();
+    this.options = options;
+    this.adapter = new PlaywrightAdapter(options.browser);
+    this.server = null;
+    this.isRunning = false;
+  }
+
+  async startRun(options) {
+    if (this.isRunning) {
+      throw new Error('Runner already executing a test');
+    }
+    this.isRunning = true;
+    this.adapter.removeAllListeners('event');
+    this.adapter.on('event', (event) => {
+      this.broadcast(event);
+    });
+    this.broadcast({ type: EVENTS.REPLAY_STARTED, runId: options.runId });
+    const normalizedSteps = normalizeSteps(options.steps);
+    try {
+      await this.adapter.play(normalizedSteps, {
+        startUrl: options.startUrl,
+        runId: options.runId,
+        headless: options.headless !== undefined ? options.headless : true,
+        stepDelayMs: options.stepDelayMs,
+      });
+      this.broadcast({ type: EVENTS.REPLAY_COMPLETE, runId: options.runId });
+    } catch (error) {
+      this.broadcast({ type: EVENTS.REPLAY_ERROR, error: error.message });
+      throw error;
+    } finally {
+      this.isRunning = false;
+    }
+  }
+
+  broadcast(payload) {
+    const wsPayload = JSON.stringify(payload);
+    this.emit('event', payload);
+    if (this.server && this.server.clients) {
+      this.server.clients.forEach((client) => {
+        if (client.readyState === WebSocket.OPEN) {
+          client.send(wsPayload);
+        }
+      });
+    }
+  }
+
+  startServer() {
+    if (this.server) return;
+    const tlsKeyPath = process.env.MAERIS_TLS_KEY;
+    const tlsCertPath = process.env.MAERIS_TLS_CERT;
+    const useTls = Boolean(tlsKeyPath && tlsCertPath);
+
+    if (useTls) {
+      const key = fs.readFileSync(tlsKeyPath);
+      const cert = fs.readFileSync(tlsCertPath);
+      const httpsServer = https.createServer({ key, cert });
+      this.server = new WebSocket.Server({ server: httpsServer });
+      httpsServer.listen(EVENT_PORT);
+      console.log(`[Runner] WSS server listening on wss://localhost:${EVENT_PORT}`);
+    } else {
+      this.server = new WebSocket.Server({ port: EVENT_PORT });
+      console.log(`[Runner] WebSocket server listening on ws://localhost:${EVENT_PORT}`);
+    }
+    this.server.on('connection', (socket) => {
+      console.log("[Runner] Client connected");
+      socket.send(JSON.stringify({ type: EVENTS.SERVER_READY }));
+      socket.on('message', (message) => this.handleCommand(socket, message));
+      socket.on('close', () => {
+        // keep server alive for future runs
+      });
+    });
+  }
+
+  async handleCommand(socket, message) {
+    let parsed;
+    try {
+      parsed = JSON.parse(message);
+    } catch (err) {
+      console.error('[Runner] Invalid message', err);
+      return;
+    }
+    console.log('[Runner] command payload', parsed);
+    console.log('[Runner] received message', parsed.type);
+    const { type, steps, startUrl, browser, runId, headless, stepDelayMs } = parsed;
+    if (type === EVENTS.RUN_STEPS) {
+      try {
+        console.log(`[Runner] starting run ${runId || 'generated'} with ${steps?.length || 0} steps`);
+        await this.startRun({
+          steps,
+          startUrl,
+          browser: browser || this.options.browser,
+          runId: runId || `local_${Date.now()}`,
+          headless,
+          stepDelayMs,
+        });
+        socket.send(JSON.stringify({ type: EVENTS.REPLAY_COMPLETE }));
+      } catch (err) {
+        socket.send(JSON.stringify({ type: EVENTS.REPLAY_ERROR, error: err.message }));
+      }
+    } else if (type === EVENTS.STOP_RUN) {
+      this.adapter.cancel();
+      socket.send(JSON.stringify({ type: EVENTS.REPLAY_ERROR, error: 'Run stopped' }));
+    }
+  }
+
+  closeServer() {
+    if (this.server) {
+      this.server.close();
+      this.server = null;
+    }
+  }
+}
+
+module.exports = {
+  Runner,
+  run: async (options) => {
+    const instance = new Runner(options);
+    instance.startServer();
+    await instance.startRun(options);
+  },
+};

package/src/runner/playwrightAdapter.js

@@ -0,0 +1,203 @@
+const EventEmitter = require('events');
+const playwright = require('playwright');
+const { EVENTS, createStepPayload } = require('./events');
+
+const DEFAULT_VIEWPORT = { width: 1280, height: 720 };
+const DEFAULT_STEP_DELAY_MS = 2000;
+
+class PlaywrightAdapter extends EventEmitter {
+  constructor(browserName = 'chromium') {
+    super();
+    this.browserName = browserName;
+    this.browser = null;
+    this.context = null;
+    this.page = null;
+    this.cancelled = false;
+  }
+
+  async play(steps, options = {}) {
+    this.cancelled = false;
+    const browserType = playwright[this.browserName] || playwright.chromium;
+    this.browser = await browserType.launch({
+      headless: options.headless !== undefined ? options.headless : true,
+    });
+    this.context = await this.browser.newContext({ viewport: DEFAULT_VIEWPORT });
+    this.page = await this.context.newPage();
+    const stepDelayMs = this.resolveStepDelay(options);
+
+    if (options.startUrl) {
+      await this.page.goto(options.startUrl, { waitUntil: 'networkidle' });
+      this.emit('event', {
+        type: EVENTS.NAVIGATION,
+        timestamp: Date.now(),
+        url: options.startUrl,
+      });
+    }
+
+    try {
+      for (let index = 0; index < steps.length; index += 1) {
+        const step = steps[index];
+        this.emit('event', createStepPayload(EVENTS.STEP_STARTED, step));
+        try {
+          await this.performStep(this.page, step);
+          this.emit('event', createStepPayload(EVENTS.STEP_PASSED, step));
+        } catch (error) {
+          const screenshot = await page.screenshot({ fullPage: true });
+          this.emit(
+            'event',
+            createStepPayload(EVENTS.STEP_FAILED, step, {
+              message: error.message,
+              screenshot: screenshot.toString('base64'),
+            })
+          );
+          throw error;
+        }
+        if (index < steps.length - 1 && stepDelayMs > 0) {
+          await this.sleep(stepDelayMs);
+        }
+      }
+    } finally {
+      if (this.browser) {
+        await this.browser.close().catch(() => {});
+        this.browser = null;
+      }
+      this.context = null;
+      this.page = null;
+    }
+  }
+
+  resolveStepDelay(options) {
+    if (Number.isFinite(options.stepDelayMs)) {
+      return options.stepDelayMs;
+    }
+    const envDelay = Number.parseInt(process.env.MAERIS_STEP_DELAY_MS, 10);
+    if (Number.isFinite(envDelay)) {
+      return envDelay;
+    }
+    return DEFAULT_STEP_DELAY_MS;
+  }
+
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  getPreferredSelector(step) {
+    const selectors = [
+      step.css_selector,
+      step.selector,
+      step.raw_selector,
+      step.original_css_selector,
+      step.selector_value,
+    ];
+    const firstValid = selectors.find(
+      (value) => typeof value === 'string' && value.trim().length > 0
+    );
+    if (firstValid) return firstValid.trim();
+    if (step.xpath) return step.xpath.trim();
+    return null;
+  }
+
+  getLocator(page, step) {
+    const selector = this.getPreferredSelector(step);
+    if (selector) {
+      if (selector.startsWith('//') || selector.startsWith('(')) {
+        return page.locator(`xpath=${selector}`);
+      }
+      return page.locator(selector);
+    }
+
+    if (step.metaText) {
+      return page.locator(`:text("${step.metaText}")`).first();
+    }
+    if (step.metaTag) {
+      return page.locator(step.metaTag).first();
+    }
+    if (step.element_tag) {
+      return page.locator(step.element_tag).first();
+    }
+    return page.locator('*').first();
+  }
+
+  applyNth(locator, step) {
+    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;
+  }
+
+  async performStep(page, step) {
+    const action = (step.action || 'click').toLowerCase();
+    const label = step.label || step.name || step.component_label || step.metaText;
+    const stepIdentifier = `#${step.index ?? '??'} ${label || 'Step'}`;
+    console.log(
+      `[PlaywrightAdapter] Performing step ${stepIdentifier} -> action '${action}'`
+    );
+    if (action.includes('navigate') || action.includes('goto')) {
+      const target = step.value || step.page_url || step.metaUrl;
+      if (!target) {
+        throw new Error('Navigation target missing');
+      }
+      await page.goto(target, { waitUntil: 'networkidle' });
+      this.emit('event', {
+        type: EVENTS.NAVIGATION,
+        timestamp: Date.now(),
+        url: target,
+      });
+      return;
+    }
+
+    if (this.cancelled) {
+      throw new Error("Run cancelled");
+    }
+    const locator = this.applyNth(this.getLocator(page, step), step);
+    await locator.waitFor({ state: 'visible', timeout: 10000 });
+
+    if (action.includes('click')) {
+      await locator.click({ force: true });
+    } else if (action.includes('send') || action.includes('input') || action.includes('type')) {
+      const value = step.value || step.mock_input || '';
+      await locator.fill('');
+      if (value) {
+        await locator.fill(value);
+      }
+    } else if (action.includes('assert')) {
+      await this.handleAssertion(locator, step);
+    } else {
+      await locator.click({ force: true });
+    }
+  }
+
+  async handleAssertion(locator, step) {
+    const assertionType = (step.assertion_type || '').toLowerCase();
+    const assertionValue = step.assertion_value;
+    if (assertionType.includes('visible')) {
+      await locator.waitFor({ state: 'visible', timeout: 10000 });
+    } else if (assertionType.includes('value')) {
+      const value = await locator.inputValue();
+      if (assertionValue && !value.includes(assertionValue)) {
+        throw new Error(`Expected value to include "${assertionValue}", got "${value}"`);
+      }
+    } else if (assertionValue) {
+      const text = await locator.innerText();
+      if (!text.includes(assertionValue)) {
+        throw new Error(`Expected text to include "${assertionValue}", got "${text}"`);
+      }
+    } else {
+      await locator.waitFor({ state: 'visible', timeout: 10000 });
+    }
+  }
+
+  cancel() {
+    this.cancelled = true;
+    if (this.browser) {
+      this.browser.close().catch(() => {});
+    }
+  }
+}
+
+module.exports = PlaywrightAdapter;

package/src/runner/server.js

@@ -0,0 +1,5 @@
+const { Runner } = require('./index');
+
+const runner = new Runner({});
+runner.startServer();
+console.log('Runner server started');

package/src/utils/normalizeSteps.js

@@ -0,0 +1,13 @@
+module.exports = function normalizeSteps(rawSteps = []) {
+  const stepsArray = Array.isArray(rawSteps)
+    ? rawSteps
+    : rawSteps.steps || rawSteps.components || [];
+  return stepsArray.map((step, index) => ({
+    ...step,
+    index,
+    selector: step.css_selector || step.xpath || step.selector || null,
+    action: step.action_taken || step.type || 'click',
+    flu_id: step.flu_id || step.id,
+    component_id: step.component_id || step.id,
+  }));
+};