playwright-repl 0.1.1 → 0.2.1

package/{RELEASES.md → CHANGELOG.md}

@@ -1,4 +1,48 @@
-# Releases
+# Changelog
+
+## v0.2.1 — Ghost Completion
+
+**2026-02-17**
+
+### Features
+
+- **Ghost completion**: Fish-shell style inline suggestions — type a prefix and see dimmed suggestion text after the cursor
+  - **Tab** cycles through matches (e.g., `go` → goto, go-back, go-forward)
+  - **Right Arrow** accepts the current suggestion
+  - **Tab on empty line** cycles through all commands
+- Aliases excluded from ghost suggestions (still work when typed)
+
+### Removed
+
+- Removed readline's built-in Tab completer (replaced entirely by ghost completion)
+
+---
+
+## v0.2.0 — MCP Server
+
+**2026-02-16**
+
+### Features
+
+- **MCP Server**: Ships a stdio MCP server (`playwright-mcp-server`) that exposes Playwright's full browser automation toolkit to AI agents (Claude, Cursor, etc.)
+- Supports `--headed` flag for visible browser mode
+
+### Configuration
+
+VS Code / Cursor — add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-p", "playwright-repl", "playwright-mcp-server", "--headed"]
+    }
+  }
+}
+```
+
+---
 
 ## v0.1.1 — Bug Fixes
 

package/README.md

@@ -1,5 +1,7 @@
 # playwright-repl
 
+![playwright-repl](cover-image.png)
+
 Interactive REPL for Playwright browser automation — keyword-driven testing from your terminal.
 
 Inspired by [playwright-cli](https://github.com/anthropics/playwright-cli), reusing its command vocabulary and Playwright MCP daemon. Where playwright-cli is designed for AI agents (one command per process), playwright-repl is designed for **humans** — a persistent session with recording, replay, and instant feedback.
@@ -128,6 +130,52 @@ playwright-repl --session checkout-flow --headed
 | `-q, --silent` | Suppress banner and status messages |
 | `-h, --help` | Show help |
 
+## MCP Server
+
+`playwright-repl` also ships an MCP server that exposes Playwright's full browser automation toolkit to AI agents (Claude, Cursor, etc.) over stdio.
+
+```bash
+# Run directly
+npx -p playwright-repl playwright-mcp-server
+
+# With visible browser
+npx -p playwright-repl playwright-mcp-server --headed
+```
+
+### VS Code / Cursor Configuration
+
+Add to `.vscode/mcp.json` in your project:
+
+```json
+{
+  "servers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-p", "playwright-repl", "playwright-mcp-server"]
+    }
+  }
+}
+```
+
+Or with a visible browser:
+
+```json
+{
+  "servers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-p", "playwright-repl", "playwright-mcp-server", "--headed"]
+    }
+  }
+}
+```
+
+### MCP Server Options
+
+| Option | Description |
+|--------|-------------|
+| `--headed` | Run browser in headed (visible) mode |
+
 ## Commands
 
 ### Navigation
@@ -336,13 +384,7 @@ playwright-repl --replay examples/05-ci-pipe.pw --silent
 
 ## Architecture
 
-```
-┌──────────────┐     Unix Socket      ┌──────────────────┐     CDP      ┌─────────┐
-│ playwright-  │◄──── JSON/newline ───►│  Daemon Process  │◄────────────►│ Browser │
-│ repl         │                       │  (Playwright     │              │(Chrome/ │
-│              │                       │   MCP backend)   │              │ FF/WK)  │
-└──────────────┘                       └──────────────────┘              └─────────┘
-```
+![Architecture](architecture-diagram.png)
 
 The REPL replaces only the **client half** of playwright-cli. The daemon, browser, and all tool handlers are unchanged — both CLI and REPL produce identical wire messages.
 

package/bin/mcp-server.cjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+/**
+ * Thin MCP server entrypoint — uses Playwright's built-in MCP infrastructure.
+ * Starts a stdio MCP server with all browser tools available.
+ *
+ * Uses only publicly exported paths:
+ *   - playwright/lib/mcp/index        → createConnection()
+ *   - playwright-core/lib/mcpBundle   → StdioServerTransport
+ */
+
+const { createConnection } = require('playwright/lib/mcp/index');
+const { StdioServerTransport } = require('playwright-core/lib/mcpBundle');
+
+// ─── Parse CLI args ───
+
+const args = process.argv.slice(2);
+const headed = args.includes('--headed');
+
+(async () => {
+  const server = await createConnection({
+    browser: {
+      launchOptions: { headless: !headed },
+    },
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+})().catch(e => {
+  console.error(e.message);
+  process.exit(1);
+});

package/examples/ghost-completion-demo.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * Ghost completion demo — standalone test for inline suggestions.
+ *
+ * Run:  node examples/ghost-completion-demo.mjs
+ *
+ * Type a prefix (e.g. "go") and see dimmed suggestion text.
+ * Tab cycles through matches, Right Arrow accepts.
+ */
+
+import readline from 'node:readline';
+
+const COMMANDS = [
+  'click', 'check', 'close', 'console', 'cookie-get', 'cookie-list',
+  'dblclick', 'drag', 'eval', 'fill', 'goto', 'go-back', 'go-forward',
+  'hover', 'network', 'open', 'press', 'reload', 'screenshot', 'select',
+  'snapshot', 'type', 'uncheck', 'upload',
+  '.help', '.aliases', '.status', '.exit',
+];
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  prompt: '\x1b[36mpw>\x1b[0m ',
+});
+
+// ─── Ghost completion via _ttyWrite ─────────────────────────────────────────
+
+let ghost = '';
+let matches = [];
+let matchIdx = 0;
+
+function getMatches(input) {
+  if (input.length > 0 && !input.includes(' ')) {
+    return COMMANDS.filter(cmd => cmd.startsWith(input) && cmd !== input);
+  }
+  return [];
+}
+
+function renderGhost(suffix) {
+  ghost = suffix;
+  rl.output.write(`\x1b[2m${ghost}\x1b[0m\x1b[${ghost.length}D`);
+}
+
+const origTtyWrite = rl._ttyWrite.bind(rl);
+rl._ttyWrite = function (s, key) {
+  if (ghost && key) {
+    // Right-arrow-at-end accepts ghost suggestion
+    if (key.name === 'right' && rl.cursor === rl.line.length) {
+      const text = ghost;
+      rl.output.write('\x1b[K');
+      ghost = '';
+      matches = [];
+      rl._insertString(text);
+      return;
+    }
+
+    // Tab cycles through matches (or accepts if only one)
+    if (key.name === 'tab') {
+      if (matches.length > 1) {
+        rl.output.write('\x1b[K');
+        matchIdx = (matchIdx + 1) % matches.length;
+        const input = rl.line || '';
+        renderGhost(matches[matchIdx].slice(input.length));
+        return;
+      }
+      // Single match — accept it
+      const text = ghost;
+      rl.output.write('\x1b[K');
+      ghost = '';
+      matches = [];
+      rl._insertString(text);
+      return;
+    }
+  }
+
+  // Tab on empty input — show all commands as ghost suggestions
+  if (key && key.name === 'tab') {
+    if ((rl.line || '') === '') {
+      matches = COMMANDS;
+      matchIdx = 0;
+      renderGhost(matches[0]);
+    }
+    return;
+  }
+
+  // Clear existing ghost text before readline processes the key
+  if (ghost) {
+    rl.output.write('\x1b[K');
+    ghost = '';
+  }
+
+  // Let readline handle the key normally
+  origTtyWrite(s, key);
+
+  // Render new ghost text if cursor is at end of line
+  const input = rl.line || '';
+  matches = getMatches(input);
+  matchIdx = 0;
+  if (matches.length > 0 && rl.cursor === rl.line.length) {
+    renderGhost(matches[0].slice(input.length));
+  }
+};
+
+// ─── REPL loop ──────────────────────────────────────────────────────────────
+
+console.log('Ghost completion demo — Tab cycles matches, Right Arrow accepts\n');
+rl.prompt();
+
+rl.on('line', (line) => {
+  if (line.trim() === '.exit') {
+    rl.close();
+    return;
+  }
+  console.log(`  → ${line.trim() || '(empty)'}`);
+  rl.prompt();
+});
+
+rl.on('close', () => {
+  console.log('\nBye!');
+  process.exit(0);
+});

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "playwright-repl",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Interactive REPL for Playwright browser automation — keyword-driven testing from your terminal",
   "type": "module",
   "bin": {
-    "playwright-repl": "./bin/playwright-repl.mjs"
+    "playwright-repl": "./bin/playwright-repl.mjs",
+    "playwright-mcp-server": "./bin/mcp-server.cjs"
   },
   "main": "./src/index.mjs",
   "exports": {
@@ -36,7 +37,7 @@
     "examples/",
     "LICENSE",
     "README.md",
-    "RELEASES.md"
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18.0.0"

package/src/completion-data.mjs

@@ -0,0 +1,50 @@
+/**
+ * Completion data — builds the list of items for dropdown autocomplete.
+ *
+ * Sources: COMMANDS from resolve.mjs, ALIASES from parser.mjs,
+ * plus REPL meta-commands (.help, .exit, etc.).
+ */
+
+import { COMMANDS } from './resolve.mjs';
+import { ALIASES } from './parser.mjs';
+
+// ─── Meta-commands ───────────────────────────────────────────────────────────
+
+const META_COMMANDS = [
+  { cmd: '.help',      desc: 'Show available commands' },
+  { cmd: '.aliases',   desc: 'Show command aliases' },
+  { cmd: '.status',    desc: 'Show connection status' },
+  { cmd: '.reconnect', desc: 'Reconnect to daemon' },
+  { cmd: '.record',    desc: 'Start recording commands' },
+  { cmd: '.save',      desc: 'Stop recording and save' },
+  { cmd: '.pause',     desc: 'Pause/resume recording' },
+  { cmd: '.discard',   desc: 'Discard current recording' },
+  { cmd: '.replay',    desc: 'Replay a recorded session' },
+  { cmd: '.exit',      desc: 'Exit REPL' },
+];
+
+// ─── Build completion items ──────────────────────────────────────────────────
+
+/**
+ * Returns a sorted array of `{ cmd, desc }` for all completable items:
+ * commands, aliases (with "→ target" description), and meta-commands.
+ */
+export function buildCompletionItems() {
+  const items = [];
+
+  // Primary commands
+  for (const [name, info] of Object.entries(COMMANDS)) {
+    items.push({ cmd: name, desc: info.desc });
+  }
+
+  // Aliases — show "→ target" as description
+  for (const [alias, target] of Object.entries(ALIASES)) {
+    items.push({ cmd: alias, desc: `→ ${target}` });
+  }
+
+  // Meta-commands
+  items.push(...META_COMMANDS);
+
+  items.sort((a, b) => a.cmd.localeCompare(b.cmd));
+  return items;
+}

package/src/index.mjs

@@ -1,15 +1,16 @@
-/**
- * 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';
+/**
+ * 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';
+export { buildCompletionItems } from './completion-data.mjs';

package/src/repl.mjs

@@ -9,11 +9,12 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { execSync } from 'node:child_process';
 
-import { replVersion, COMMANDS } from './resolve.mjs';
+import { replVersion } from './resolve.mjs';
 import { DaemonConnection } from './connection.mjs';
 import { socketPath, daemonProfilesDir, isDaemonRunning, startDaemon } from './workspace.mjs';
 import { parseInput, ALIASES, ALL_COMMANDS } from './parser.mjs';
 import { SessionManager } from './recorder.mjs';
+import { buildCompletionItems } from './completion-data.mjs';
 import { c } from './colors.mjs';
 
 // ─── Verify commands → run-code translation ─────────────────────────────────
@@ -518,26 +519,98 @@ export function promptStr(ctx) {
   return `${prefix}${c.cyan}pw>${c.reset} `;
 }
 
-// ─── Tab completer ──────────────────────────────────────────────────────────
-
-export function completer(line) {
-  const parts = line.split(/\s+/);
-  if (parts.length <= 1) {
-    const prefix = parts[0] || '';
-    const allNames = [...ALL_COMMANDS, ...Object.keys(ALIASES)];
-    const metas = ['.help', '.aliases', '.status', '.reconnect', '.exit',
-                   '.record', '.save', '.replay', '.pause', '.discard'];
-    const hits = [...allNames, ...metas].filter(n => n.startsWith(prefix));
-    return [hits.length ? hits : allNames, prefix];
+// ─── Ghost completion (inline suggestion) ───────────────────────────────────
+
+/**
+ * Attaches ghost-text completion to a readline interface.
+ * Shows dimmed inline suggestion after the cursor; Tab or Right Arrow accepts it.
+ *
+ * Uses _ttyWrite wrapper instead of _writeToOutput because Node 22+ optimizes
+ * single-character appends and doesn't always trigger a full line refresh.
+ *
+ * @param {readline.Interface} rl
+ * @param {Array<{cmd: string, desc: string}>} items - from buildCompletionItems()
+ */
+function attachGhostCompletion(rl, items) {
+  if (!process.stdin.isTTY) return;  // no ghost text for piped input
+
+  const cmds = items.filter(i => !i.desc.startsWith('→')).map(i => i.cmd);
+  let ghost = '';
+  let matches = [];   // all matching commands for current input
+  let matchIdx = 0;   // which match is currently shown
+
+  function getMatches(input) {
+    if (input.length > 0 && !input.includes(' ')) {
+      return cmds.filter(cmd => cmd.startsWith(input) && cmd !== input);
+    }
+    return [];
   }
-  const cmd = ALIASES[parts[0]] || parts[0];
-  const helpText = COMMANDS[cmd]?.options || [];
-  const lastPart = parts[parts.length - 1];
-  if (lastPart.startsWith('--')) {
-    const hits = helpText.filter(o => o.startsWith(lastPart));
-    return [hits, lastPart];
+
+  function renderGhost(suffix) {
+    ghost = suffix;
+    rl.output.write(`\x1b[2m${ghost}\x1b[0m\x1b[${ghost.length}D`);
   }
-  return [[], line];
+
+  const origTtyWrite = rl._ttyWrite.bind(rl);
+  rl._ttyWrite = function (s, key) {
+    if (ghost && key) {
+      // Right-arrow-at-end accepts ghost suggestion
+      if (key.name === 'right' && rl.cursor === rl.line.length) {
+        const text = ghost;
+        rl.output.write('\x1b[K');
+        ghost = '';
+        matches = [];
+        rl._insertString(text);
+        return;
+      }
+
+      // Tab cycles through matches
+      if (key.name === 'tab' && matches.length > 1) {
+        rl.output.write('\x1b[K');
+        matchIdx = (matchIdx + 1) % matches.length;
+        const input = rl.line || '';
+        renderGhost(matches[matchIdx].slice(input.length));
+        return;
+      }
+
+      // Tab with single match accepts it
+      if (key.name === 'tab' && matches.length === 1) {
+        const text = ghost;
+        rl.output.write('\x1b[K');
+        ghost = '';
+        matches = [];
+        rl._insertString(text);
+        return;
+      }
+    }
+
+    // Tab on empty input — show all commands as ghost suggestions
+    if (key && key.name === 'tab') {
+      if ((rl.line || '') === '') {
+        matches = cmds;
+        matchIdx = 0;
+        renderGhost(matches[0]);
+      }
+      return;
+    }
+
+    // Clear existing ghost text before readline processes the key
+    if (ghost) {
+      rl.output.write('\x1b[K');
+      ghost = '';
+    }
+
+    // Let readline handle the key normally
+    origTtyWrite(s, key);
+
+    // Render new ghost text if cursor is at end of line
+    const input = rl.line || '';
+    matches = getMatches(input);
+    matchIdx = 0;
+    if (matches.length > 0 && rl.cursor === rl.line.length) {
+      renderGhost(matches[0].slice(input.length));
+    }
+  };
 }
 
 // ─── REPL ────────────────────────────────────────────────────────────────────
@@ -585,7 +658,6 @@ export async function startRepl(opts = {}) {
     output: process.stdout,
     prompt: promptStr(ctx),
     historySize: 500,
-    completer,
   });
   ctx.rl = rl;
 
@@ -594,6 +666,8 @@ export async function startRepl(opts = {}) {
     for (const line of hist) rl.history.push(line);
   } catch {}
 
+  attachGhostCompletion(rl, buildCompletionItems());
+
   // ─── Start ───────────────────────────────────────────────────────
 
   if (opts.replay) {