playwright-repl 0.1.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "playwright-repl",
+  "version": "0.1.0",
+  "description": "Interactive REPL for Playwright browser automation — keyword-driven testing from your terminal",
+  "type": "module",
+  "bin": {
+    "playwright-repl": "./bin/playwright-repl.mjs"
+  },
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs"
+  },
+  "scripts": {
+    "start": "node bin/playwright-repl.mjs",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  },
+  "keywords": [
+    "playwright",
+    "repl",
+    "browser",
+    "automation",
+    "testing",
+    "mcp",
+    "keyword-driven"
+  ],
+  "author": "Steve Zhang",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stevez/playwright-repl.git"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "examples/",
+    "LICENSE",
+    "README.md",
+    "RELEASES.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "minimist": "^1.2.8",
+    "playwright": ">=1.59.0-alpha-2026-02-01"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.18",
+    "vitest": "^4.0.18"
+  }
+}

package/src/colors.mjs

@@ -0,0 +1,17 @@
+/**
+ * Terminal color helpers.
+ * No dependency — just ANSI escape codes.
+ */
+
+export const c = {
+  reset:   '\x1b[0m',
+  bold:    '\x1b[1m',
+  dim:     '\x1b[2m',
+  red:     '\x1b[31m',
+  green:   '\x1b[32m',
+  yellow:  '\x1b[33m',
+  blue:    '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan:    '\x1b[36m',
+  gray:    '\x1b[90m',
+};

package/src/connection.mjs

@@ -0,0 +1,119 @@
+/**
+ * DaemonConnection — persistent Unix socket client.
+ *
+ * Wire protocol: newline-delimited JSON.
+ *
+ * Send:    {"id":1,"method":"run","params":{"args":{...},"cwd":"/"},"version":"0.1.0"}\n
+ * Receive: {"id":1,"result":{"text":"..."},"version":"0.1.0"}\n
+ */
+
+import net from 'node:net';
+
+export class DaemonConnection {
+  constructor(sockPath, version) {
+    this.sockPath = sockPath;
+    this.version = version;
+    this.socket = null;
+    this.nextId = 1;
+    this.callbacks = new Map();
+    this.pendingBuffers = [];
+  }
+
+  async connect() {
+    return new Promise((resolve, reject) => {
+      const sock = net.createConnection(this.sockPath, () => {
+        this.socket = sock;
+        resolve(true);
+      });
+      sock.on('data', (buf) => this._onData(buf));
+      sock.on('error', (err) => {
+        if (!this.socket) reject(err);
+        else this._handleError(err);
+      });
+      sock.on('close', () => {
+        this.socket = null;
+        for (const cb of this.callbacks.values()) {
+          cb.reject(new Error('Connection closed'));
+        }
+        this.callbacks.clear();
+      });
+    });
+  }
+
+  get connected() {
+    return this.socket !== null && !this.socket.destroyed;
+  }
+
+  /**
+   * Send a raw message to the daemon.
+   * Returns the result from the daemon response.
+   */
+  async send(method, params = {}) {
+    if (!this.connected) throw new Error('Not connected to daemon');
+    const id = this.nextId++;
+    const msg = { id, method, params, version: this.version };
+    return new Promise((resolve, reject) => {
+      this.callbacks.set(id, { resolve, reject });
+      this.socket.write(JSON.stringify(msg) + '\n', (err) => {
+        if (err) {
+          this.callbacks.delete(id);
+          reject(err);
+        }
+      });
+    });
+  }
+
+  /**
+   * Send a "run" command — the standard way to execute CLI commands.
+   * `minimistArgs` is a pre-parsed minimist object, e.g. { _: ["click", "e5"] }
+   */
+  async run(minimistArgs) {
+    return this.send('run', { args: minimistArgs, cwd: process.cwd() });
+  }
+
+  close() {
+    if (this.socket) {
+      this.socket.destroy();
+      this.socket = null;
+    }
+  }
+
+  // ─── Internal: newline-delimited JSON parsing ────────────────────────
+
+  _onData(buffer) {
+    let end = buffer.indexOf('\n');
+    if (end === -1) {
+      this.pendingBuffers.push(buffer);
+      return;
+    }
+    this.pendingBuffers.push(buffer.slice(0, end));
+    this._dispatch(Buffer.concat(this.pendingBuffers).toString());
+    let start = end + 1;
+    end = buffer.indexOf('\n', start);
+    while (end !== -1) {
+      this._dispatch(buffer.toString(undefined, start, end));
+      start = end + 1;
+      end = buffer.indexOf('\n', start);
+    }
+    this.pendingBuffers = [buffer.slice(start)];
+  }
+
+  _dispatch(message) {
+    try {
+      const obj = JSON.parse(message);
+      if (obj.id && this.callbacks.has(obj.id)) {
+        const cb = this.callbacks.get(obj.id);
+        this.callbacks.delete(obj.id);
+        if (obj.error) cb.reject(new Error(obj.error));
+        else cb.resolve(obj.result);
+      }
+    } catch {
+      // Ignore parse errors on partial messages
+    }
+  }
+
+  _handleError(err) {
+    if (err.code !== 'EPIPE')
+      console.error(`\n⚠️  Socket error: ${err.message}`);
+  }
+}

package/src/index.mjs

@@ -0,0 +1,15 @@
+/**
+ * playwright-repl — public API
+ *
+ * Usage as CLI:
+ *   npx playwright-repl [options]
+ *
+ * Usage as library:
+ *   import { DaemonConnection, parseInput, SessionRecorder } from 'playwright-repl';
+ */
+
+export { DaemonConnection } from './connection.mjs';
+export { parseInput, ALIASES, ALL_COMMANDS } from './parser.mjs';
+export { SessionRecorder, SessionPlayer } from './recorder.mjs';
+export { socketPath, isDaemonRunning, startDaemon, findWorkspaceDir } from './workspace.mjs';
+export { startRepl } from './repl.mjs';

package/src/parser.mjs

@@ -0,0 +1,141 @@
+/**
+ * Input parser — transforms human input into minimist-style args.
+ *
+ * Flow: "c e5" → alias resolve → ["click", "e5"] → minimist → { _: ["click", "e5"] }
+ *
+ * The resulting object is sent to the daemon as-is. The daemon runs
+ * parseCliCommand() which maps it to a tool call.
+ */
+
+import { minimist, COMMANDS } from './resolve.mjs';
+
+// ─── Command aliases ─────────────────────────────────────────────────────────
+
+export const ALIASES = {
+  // Navigation
+  'o':    'open',
+  'g':    'goto',
+  'go':   'goto',
+  'back': 'go-back',
+  'fwd':  'go-forward',
+  'r':    'reload',
+
+  // Interaction
+  'c':    'click',
+  'dc':   'dblclick',
+  't':    'type',
+  'f':    'fill',
+  'h':    'hover',
+  'p':    'press',
+  'sel':  'select',
+  'chk':  'check',
+  'unchk':'uncheck',
+
+  // Inspection
+  's':    'snapshot',
+  'snap': 'snapshot',
+  'ss':   'screenshot',
+  'e':    'eval',
+  'con':  'console',
+  'net':  'network',
+
+  // Tabs
+  'tl':   'tab-list',
+  'tn':   'tab-new',
+  'tc':   'tab-close',
+  'ts':   'tab-select',
+
+  // Assertions (Phase 2 — mapped to daemon tools that exist but have no CLI keywords)
+  'vt':   'verify-text',
+  've':   'verify-element',
+  'vv':   'verify-value',
+  'vl':   'verify-list',
+
+  // Session
+  'q':    'close',
+  'ls':   'list',
+};
+
+// ─── Known boolean options ───────────────────────────────────────────────────
+
+export const booleanOptions = new Set([
+  'headed', 'persistent', 'extension', 'submit', 'clear',
+  'fullPage', 'includeStatic',
+]);
+
+// ─── All known commands ──────────────────────────────────────────────────────
+
+export const ALL_COMMANDS = Object.keys(COMMANDS);
+
+// ─── Tokenizer ───────────────────────────────────────────────────────────────
+
+/**
+ * Tokenize input respecting quoted strings.
+ * "fill e7 'hello world'" → ["fill", "e7", "hello world"]
+ */
+function tokenize(line) {
+  const tokens = [];
+  let current = '';
+  let inQuote = null;
+
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (inQuote) {
+      if (ch === inQuote) {
+        inQuote = null;
+      } else {
+        current += ch;
+      }
+    } else if (ch === '"' || ch === "'") {
+      inQuote = ch;
+    } else if (ch === ' ' || ch === '\t') {
+      if (current) {
+        tokens.push(current);
+        current = '';
+      }
+    } else {
+      current += ch;
+    }
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+// ─── Main parse function ─────────────────────────────────────────────────────
+
+/**
+ * Parse a REPL input line into a minimist args object ready for the daemon.
+ * Returns null if the line is empty.
+ */
+export function parseInput(line) {
+  const tokens = tokenize(line);
+  if (tokens.length === 0) return null;
+
+  // Resolve alias
+  const cmd = tokens[0].toLowerCase();
+  if (ALIASES[cmd]) tokens[0] = ALIASES[cmd];
+
+  // Parse with minimist (same lib and boolean set as playwright-cli)
+  const args = minimist(tokens, { boolean: [...booleanOptions] });
+
+  // Stringify non-boolean values (playwright-cli does this)
+  for (const key of Object.keys(args)) {
+    if (key === '_') continue;
+    if (typeof args[key] !== 'boolean')
+      args[key] = String(args[key]);
+  }
+  for (let i = 0; i < args._.length; i++)
+    args._[i] = String(args._[i]);
+
+  // Remove boolean options set to false that weren't explicitly passed.
+  // minimist sets all declared booleans to false by default, but the
+  // daemon rejects unknown options like --headed false.
+  for (const opt of booleanOptions) {
+    if (args[opt] === false) {
+      const hasExplicitNo = tokens.some(t => t === `--no-${opt}`);
+      if (!hasExplicitNo) delete args[opt];
+    }
+  }
+
+  return args;
+}

package/src/recorder.mjs

@@ -0,0 +1,241 @@
+/**
+ * Session recorder and player.
+ *
+ * Records REPL commands to .pw files and replays them.
+ *
+ * File format (.pw):
+ *   - One command per line (exactly as typed in REPL)
+ *   - Comments start with #
+ *   - Blank lines are ignored
+ *   - First line is a metadata comment with timestamp
+ *
+ * Example:
+ *   # Login test
+ *   # recorded 2026-02-09T19:30:00Z
+ *
+ *   open https://myapp.com
+ *   snapshot
+ *   click e5
+ *   fill e7 admin@test.com
+ *   fill e9 password123
+ *   click e12
+ *   verify-text Welcome back
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+// ─── Session Recorder ────────────────────────────────────────────────────────
+
+export class SessionRecorder {
+  constructor() {
+    this.commands = [];
+    this.recording = false;
+    this.filename = null;
+    this.paused = false;
+  }
+
+  /**
+   * Start recording commands.
+   * @param {string} [filename] - Output file path. If not provided, uses a timestamp.
+   */
+  start(filename) {
+    this.filename = filename || `session-${new Date().toISOString().replace(/[:.]/g, '-')}.pw`;
+    this.commands = [];
+    this.recording = true;
+    this.paused = false;
+    return this.filename;
+  }
+
+  /**
+   * Record a command (called after each successful REPL command).
+   * Skips meta-commands (lines starting with .).
+   */
+  record(line) {
+    if (!this.recording || this.paused) return;
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('.')) return;
+    this.commands.push(trimmed);
+  }
+
+  /**
+   * Pause recording (toggle).
+   */
+  pause() {
+    this.paused = !this.paused;
+    return this.paused;
+  }
+
+  /**
+   * Stop recording and save to file.
+   * @returns {{ filename: string, count: number }}
+   */
+  save() {
+    if (!this.recording) throw new Error('Not recording');
+
+    const header = [
+      `# Playwright REPL session`,
+      `# recorded ${new Date().toISOString()}`,
+      ``,
+    ];
+
+    const content = [...header, ...this.commands, ''].join('\n');
+
+    // Ensure directory exists
+    const dir = path.dirname(this.filename);
+    if (dir && dir !== '.') {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(this.filename, content, 'utf-8');
+
+    const result = { filename: this.filename, count: this.commands.length };
+
+    this.recording = false;
+    this.commands = [];
+    this.filename = null;
+    this.paused = false;
+
+    return result;
+  }
+
+  /**
+   * Discard recording without saving.
+   */
+  discard() {
+    this.recording = false;
+    this.commands = [];
+    this.filename = null;
+    this.paused = false;
+  }
+
+  get status() {
+    if (!this.recording) return 'idle';
+    if (this.paused) return 'paused';
+    return 'recording';
+  }
+
+  get commandCount() {
+    return this.commands.length;
+  }
+}
+
+// ─── Session Player ──────────────────────────────────────────────────────────
+
+export class SessionPlayer {
+  /**
+   * Load commands from a .pw file.
+   * @param {string} filename
+   * @returns {string[]} Array of command lines
+   */
+  static load(filename) {
+    if (!fs.existsSync(filename)) {
+      throw new Error(`File not found: ${filename}`);
+    }
+
+    const content = fs.readFileSync(filename, 'utf-8');
+    return content
+      .split('\n')
+      .map(line => line.trim())
+      .filter(line => line && !line.startsWith('#'));
+  }
+
+  /**
+   * Create a player that yields commands one at a time.
+   * Supports step-through mode where it pauses between commands.
+   */
+  constructor(filename) {
+    this.filename = filename;
+    this.commands = SessionPlayer.load(filename);
+    this.index = 0;
+  }
+
+  get done() {
+    return this.index >= this.commands.length;
+  }
+
+  get current() {
+    return this.commands[this.index] || null;
+  }
+
+  get progress() {
+    return `[${this.index}/${this.commands.length}]`;
+  }
+
+  next() {
+    if (this.done) return null;
+    return this.commands[this.index++];
+  }
+
+  reset() {
+    this.index = 0;
+  }
+}
+
+// ─── Session Manager (state machine) ────────────────────────────────────────
+//
+//  States: idle → recording ⇄ paused → idle
+//                                       idle → replaying → idle
+//
+
+export class SessionManager {
+  #recorder = new SessionRecorder();
+  #player = null;
+  #step = false;
+
+  /** Current mode: 'idle' | 'recording' | 'paused' | 'replaying' */
+  get mode() {
+    if (this.#player && !this.#player.done) return 'replaying';
+    return this.#recorder.status;
+  }
+
+  // ── Recording ──────────────────────────────────────────────────
+
+  startRecording(filename) {
+    if (this.mode !== 'idle') throw new Error(`Cannot record while ${this.mode}`);
+    return this.#recorder.start(filename);
+  }
+
+  save() {
+    if (this.mode !== 'recording' && this.mode !== 'paused')
+      throw new Error('Not recording');
+    return this.#recorder.save();
+  }
+
+  togglePause() {
+    if (this.mode !== 'recording' && this.mode !== 'paused')
+      throw new Error('Not recording');
+    return this.#recorder.pause();
+  }
+
+  discard() {
+    if (this.mode !== 'recording' && this.mode !== 'paused')
+      throw new Error('Not recording');
+    this.#recorder.discard();
+  }
+
+  /** Called after each successful command — records if active. */
+  record(line) {
+    this.#recorder.record(line);
+  }
+
+  get recordingFilename() { return this.#recorder.filename; }
+  get recordedCount() { return this.#recorder.commandCount; }
+
+  // ── Playback ───────────────────────────────────────────────────
+
+  startReplay(filename, step = false) {
+    if (this.mode !== 'idle') throw new Error(`Cannot replay while ${this.mode}`);
+    this.#player = new SessionPlayer(filename);
+    this.#step = step;
+    return this.#player;
+  }
+
+  endReplay() {
+    this.#player = null;
+    this.#step = false;
+  }
+
+  get player() { return this.#player; }
+  get step() { return this.#step; }
+}