peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/playwright-commands.js

@@ -27,154 +27,84 @@
  * The CLI does NOT bundle `playwright-mcp`; it shells out to
  * `npx playwright-mcp@latest` (G22 / NG3). peaks-loop is the lifecycle
  * orchestrator, not the install medium.
+ *
+ * The verb implementations live beside this file: `playwright-session-store.ts`
+ * (port range, terminal-id derivation, session records, spawn),
+ * `playwright-ls-stop-commands.ts` (`ls` / `stop`) and
+ * `playwright-browser-command.ts` (`peaks browser action`). Every symbol this
+ * path used to export is still exported from it, so importers are unaffected.
  */
-import { createHash } from 'node:crypto';
-import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
 import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
-import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { getErrorMessage } from '../cli-helpers.js';
-import { runBrowserAction } from '../../services/qa/browser-wrapper-service.js';
-export const DEFAULT_PORT = 8931;
-export const MAX_PORT = 8949;
-const BROWSERS = ['chromium', 'firefox', 'webkit'];
-export const PLAYWRIGHT_SESSIONS_DIR = 'playwright-sessions';
-export function playwrightSessionsDir(projectRoot) {
-    return join(projectRoot, '.peaks', '_runtime', PLAYWRIGHT_SESSIONS_DIR);
-}
-export function sessionFilePath(projectRoot, terminalId) {
-    // Terminal-id axis. The derived id is already sanitised (`deriveTerminalId`),
-    // but `--terminal` is caller-supplied and reaches this join unsanitised.
-    // Measured (repair cycle 1, item 1): `playwright stop --terminal ../../../../X`
-    // read a session record planted OUTSIDE the project root, sent SIGTERM to the
-    // pid it named, unlinked that file, and returned `ok: true` — arbitrary
-    // process termination plus an arbitrary file delete, one flag away. This is
-    // the join every reader/writer of a session record goes through, so this is
-    // where the invariant lives.
-    if (isUnsafePathInput(terminalId)) {
-        throw new Error(`Invalid terminal id: ${terminalId} (must be a single path segment)`);
-    }
-    return join(playwrightSessionsDir(projectRoot), `${terminalId}.json`);
-}
-/**
- * Derive a stable terminal id from the process environment. Prefers
- * the platform's own terminal-session id (macOS Terminal, Windows
- * Terminal) and falls back to a hash of (ppid, tty).
- */
-export function deriveTerminalId(env = process.env, ppid = process.ppid) {
-    const termSession = env.TERM_SESSION_ID;
-    if (termSession && termSession.length > 0) {
-        return sanitizeTerminalId(termSession);
-    }
-    const wtSession = env.WT_SESSION;
-    if (wtSession && wtSession.length > 0) {
-        return sanitizeTerminalId(`wt-${wtSession}`);
-    }
-    const tty = env.SSH_TTY ?? 'no-tty';
-    const hash = createHash('sha256').update(`${ppid}-${tty}`).digest('hex').slice(0, 16);
-    return `tty-${hash}`;
-}
-function sanitizeTerminalId(raw) {
-    return raw.replace(/[^a-zA-Z0-9_.-]/g, '_').slice(0, 64);
-}
+import { BROWSERS, DEFAULT_PORT, MAX_PORT, MAX_TCP_PORT, MIN_PORT, defaultUserDataDir, deriveTerminalId, findFreePort, readSession, resolveUserDataDir, sessionFilePath, spawnPlaywrightMcp, writeSession } from './playwright-session-store.js';
+import { registerBrowserActionCommand } from './playwright-browser-command.js';
+import { registerPlaywrightLsCommand, registerPlaywrightStopCommand } from './playwright-ls-stop-commands.js';
+import { emitFailure, emitSuccess } from './playwright-envelope.js';
+// Re-exported so the split is invisible to importers of THIS path.
+export { DEFAULT_PORT, MAX_PORT, PLAYWRIGHT_SESSIONS_DIR, playwrightSessionsDir, sessionFilePath, deriveTerminalId, findFreePort, listSessions, readSession, writeSession, removeSession, spawnPlaywrightMcp, resolveUserDataDir } from './playwright-session-store.js';
+export { registerBrowserActionCommand } from './playwright-browser-command.js';
 /**
- * Walk port range starting at `start` and return the first port
- * that is NOT bound. Defaults: 8931 → 8949. If the range is exhausted,
- * returns null.
+ * Report an already-running session for this terminal. True when the caller
+ * must stop: either the reuse arm returned the existing port, or the conflict
+ * arm refused. Conflict: G21 / AC18.
  */
-export async function findFreePort(start = DEFAULT_PORT, max = MAX_PORT, probe = defaultPortProbe) {
-    for (let p = start; p <= max; p += 1) {
-        if (await probe(p))
-            return p;
+function reportExistingSession(json, reuse, existing, terminalId) {
+    if (reuse) {
+        emitSuccess(json, { reused: true, session: existing }, `reusing existing playwright session on port ${existing.port} (terminal ${terminalId})`);
+        return true;
     }
-    return null;
-}
-async function defaultPortProbe(port) {
-    return new Promise((resolveProbe) => {
-        const net = require('node:net');
-        const server = net.createServer();
-        server.once('error', () => resolveProbe(false));
-        server.once('listening', () => {
-            server.close(() => resolveProbe(true));
-        });
-        server.listen(port, '127.0.0.1');
-    });
+    emitFailure(json, `CONFLICT: another playwright MCP is already running on port ${existing.port} (terminal ${terminalId}). Reuse it (--reuse) or pick a new port (--port <n>).`, 'CONFLICT');
+    return true;
 }
-export function listSessions(projectRoot) {
-    const dir = playwrightSessionsDir(projectRoot);
-    if (!existsSync(dir))
-        return [];
-    const out = [];
-    for (const entry of readdirSync(dir)) {
-        if (!entry.endsWith('.json'))
-            continue;
-        try {
-            const raw = readFileSync(join(dir, entry), 'utf8');
-            const session = JSON.parse(raw);
-            out.push(session);
-        }
-        catch {
-            // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-            // skip malformed session file
-        }
+/** Resolve the starting port; null (+ envelope) when `--port` is out of range. */
+function resolveStartPort(json, raw) {
+    const startPort = typeof raw === 'number' && Number.isFinite(raw) ? raw : DEFAULT_PORT;
+    if (startPort < MIN_PORT || startPort > MAX_TCP_PORT) {
+        emitFailure(json, `INVALID_PORT: --port must be between ${MIN_PORT} and ${MAX_TCP_PORT} (got ${startPort})`);
+        return null;
     }
-    return out;
+    return startPort;
 }
-export function readSession(projectRoot, terminalId) {
-    const path = sessionFilePath(projectRoot, terminalId);
-    if (!existsSync(path))
-        return null;
+async function runPlaywrightStart(opts) {
     try {
-        return JSON.parse(readFileSync(path, 'utf8'));
-    }
-    catch {
-        // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return null;
+        const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
+        const browser = BROWSERS.includes(opts.browser)
+            ? opts.browser
+            : 'chromium';
+        const terminalId = deriveTerminalId();
+        const existing = readSession(projectRoot, terminalId);
+        if (existing && reportExistingSession(opts.json, opts.reuse, existing, terminalId))
+            return;
+        const startPort = resolveStartPort(opts.json, opts.port);
+        if (startPort === null)
+            return;
+        const port = await findFreePort(startPort, MAX_PORT);
+        if (port === null) {
+            emitFailure(opts.json, `PORT_EXHAUSTED: no free port in ${startPort}..${MAX_PORT} range`, 'PORT_EXHAUSTED');
+            return;
+        }
+        const userDataDir = opts.userDataDir
+            ? resolveUserDataDir(opts.userDataDir, projectRoot)
+            : defaultUserDataDir(projectRoot, terminalId);
+        // Spawn the MCP via npx. Detached so it survives our exit.
+        const { pid, child } = spawnPlaywrightMcp(port, browser, userDataDir, projectRoot);
+        child.unref();
+        const session = {
+            terminalId,
+            port,
+            browser,
+            userDataDir,
+            startedAt: new Date().toISOString(),
+            ...(pid !== undefined ? { pid } : {})
+        };
+        writeSession(projectRoot, session);
+        emitSuccess(opts.json, { session, sessionFile: sessionFilePath(projectRoot, terminalId) }, `playwright MCP started on port ${port} (browser=${browser}, terminal=${terminalId})`);
     }
-}
-export function writeSession(projectRoot, session) {
-    const path = sessionFilePath(projectRoot, session.terminalId);
-    const dir = dirname(path);
-    if (!existsSync(dir)) {
-        mkdirSync(dir, { recursive: true });
+    catch (error) {
+        emitFailure(opts.json, getErrorMessage(error));
     }
-    writeFileSync(path, JSON.stringify(session, null, 2) + '\n', 'utf8');
-}
-export function removeSession(projectRoot, terminalId) {
-    const path = sessionFilePath(projectRoot, terminalId);
-    if (!existsSync(path))
-        return false;
-    unlinkSync(path);
-    return true;
-}
-/**
- * Spawn the playwright MCP via npx. We do NOT bundle the binary;
- * we just orchestrate the lifecycle. Returns the child PID so the
- * session file can record it.
- */
-export function spawnPlaywrightMcp(port, browser, userDataDir, projectRoot) {
-    const child = spawn('npx', [
-        'playwright-mcp@latest',
-        `--port=${port}`,
-        `--browser=${browser}`,
-        `--user-data-dir=${userDataDir}`
-    ], {
-        cwd: projectRoot,
-        env: process.env,
-        stdio: 'ignore',
-        detached: true,
-        windowsHide: true
-    });
-    return { pid: child.pid, child };
 }
-export function registerPlaywrightCommands(program, _io) {
-    const playwright = program
-        .command('playwright')
-        .description('Multi-terminal Playwright MCP lifecycle. `peaks playwright start` allocates a unique port ' +
-        '(8931→8949) and writes a session file; `ls` lists running sessions; `stop` tears them down. ' +
-        'Does NOT bundle the playwright-mcp binary (uses `npx playwright-mcp@latest`). ' +
-        '(slice 2.5.0 sub-fix C)');
+function registerPlaywrightStartCommand(playwright) {
     playwright
         .command('start')
         .description('Start a Playwright MCP server on a free port; write a session record.')
@@ -184,273 +114,20 @@ export function registerPlaywrightCommands(program, _io) {
         .option('--reuse', 'if a session is already running for this terminal, return its port instead of erroring')
         .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
         .option('--json', 'emit a JSON envelope { ok, data } to stdout')
-        .action(async (opts) => {
-        try {
-            const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
-            const browser = BROWSERS.includes(opts.browser)
-                ? opts.browser
-                : 'chromium';
-            const terminalId = deriveTerminalId();
-            // Existing session for this terminal?
-            const existing = readSession(projectRoot, terminalId);
-            if (existing) {
-                if (opts.reuse) {
-                    if (opts.json === true) {
-                        process.stdout.write(JSON.stringify({
-                            ok: true,
-                            data: { reused: true, session: existing }
-                        }) + '\n');
-                    }
-                    else {
-                        process.stdout.write(`reusing existing playwright session on port ${existing.port} (terminal ${terminalId})\n`);
-                    }
-                    return;
-                }
-                // Conflict: G21 / AC18
-                const msg = `CONFLICT: another playwright MCP is already running on port ${existing.port} (terminal ${terminalId}). Reuse it (--reuse) or pick a new port (--port <n>).`;
-                if (opts.json === true) {
-                    process.stdout.write(JSON.stringify({ ok: false, error: msg, code: 'CONFLICT' }) + '\n');
-                }
-                else {
-                    process.stderr.write(msg + '\n');
-                }
-                process.exitCode = 1;
-                return;
-            }
-            // Port allocation
-            const startPort = typeof opts.port === 'number' && Number.isFinite(opts.port) ? opts.port : DEFAULT_PORT;
-            if (startPort < 1024 || startPort > 65535) {
-                const msg = `INVALID_PORT: --port must be between 1024 and 65535 (got ${startPort})`;
-                if (opts.json === true) {
-                    process.stdout.write(JSON.stringify({ ok: false, error: msg }) + '\n');
-                }
-                else {
-                    process.stderr.write(msg + '\n');
-                }
-                process.exitCode = 1;
-                return;
-            }
-            const port = await findFreePort(startPort, MAX_PORT);
-            if (port === null) {
-                const msg = `PORT_EXHAUSTED: no free port in ${startPort}..${MAX_PORT} range`;
-                if (opts.json === true) {
-                    process.stdout.write(JSON.stringify({ ok: false, error: msg, code: 'PORT_EXHAUSTED' }) + '\n');
-                }
-                else {
-                    process.stderr.write(msg + '\n');
-                }
-                process.exitCode = 1;
-                return;
-            }
-            // userDataDir default
-            const userDataDir = opts.userDataDir
-                ? resolveUserDataDir(opts.userDataDir, projectRoot)
-                : join(projectRoot, '.peaks', '_runtime', 'playwright-userdata', terminalId);
-            // Spawn the MCP via npx. Detached so it survives our exit.
-            const { pid, child } = spawnPlaywrightMcp(port, browser, userDataDir, projectRoot);
-            // Detach: do not wait for it.
-            child.unref();
-            const session = {
-                terminalId,
-                port,
-                browser,
-                userDataDir,
-                startedAt: new Date().toISOString(),
-                ...(pid !== undefined ? { pid } : {})
-            };
-            writeSession(projectRoot, session);
-            if (opts.json === true) {
-                process.stdout.write(JSON.stringify({
-                    ok: true,
-                    data: { session, sessionFile: sessionFilePath(projectRoot, terminalId) }
-                }) + '\n');
-            }
-            else {
-                process.stdout.write(`playwright MCP started on port ${port} (browser=${browser}, terminal=${terminalId})\n`);
-            }
-        }
-        catch (error) {
-            if (opts.json === true) {
-                process.stdout.write(JSON.stringify({ ok: false, error: getErrorMessage(error) }) + '\n');
-            }
-            else {
-                process.stderr.write(getErrorMessage(error) + '\n');
-            }
-            process.exitCode = 1;
-        }
-    });
-    playwright
-        .command('ls')
-        .description('List running Playwright MCP sessions from .peaks/_runtime/playwright-sessions/*.json')
-        .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
-        .option('--json', 'emit a JSON envelope { ok, data: { sessions } }')
-        .action((opts) => {
-        try {
-            const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
-            const sessions = listSessions(projectRoot);
-            if (opts.json === true) {
-                process.stdout.write(JSON.stringify({ ok: true, data: { sessions } }) + '\n');
-            }
-            else if (sessions.length === 0) {
-                process.stdout.write('no playwright sessions running\n');
-            }
-            else {
-                for (const s of sessions) {
-                    process.stdout.write(`port=${s.port}\tbrowser=${s.browser}\tterminal=${s.terminalId}\tpid=${s.pid ?? '?'}\tstarted=${s.startedAt}\n`);
-                }
-            }
-        }
-        catch (error) {
-            if (opts.json === true) {
-                process.stdout.write(JSON.stringify({ ok: false, error: getErrorMessage(error) }) + '\n');
-            }
-            else {
-                process.stderr.write(getErrorMessage(error) + '\n');
-            }
-            process.exitCode = 1;
-        }
-    });
-    playwright
-        .command('stop')
-        .description('Stop a running Playwright MCP session (best-effort kill + remove session file).')
-        .option('--terminal <id>', "terminal id to stop (default: this shell's derived terminal id)")
-        .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
-        .option('--json', 'emit a JSON envelope { ok, data }')
-        .action((opts) => {
-        try {
-            const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
-            const terminalId = opts.terminal ?? deriveTerminalId();
-            const session = readSession(projectRoot, terminalId);
-            if (!session) {
-                const msg = `NO_SESSION: no playwright session for terminal ${terminalId}`;
-                if (opts.json === true) {
-                    process.stdout.write(JSON.stringify({ ok: false, error: msg }) + '\n');
-                }
-                else {
-                    process.stderr.write(msg + '\n');
-                }
-                process.exitCode = 1;
-                return;
-            }
-            // Best-effort kill
-            if (session.pid !== undefined && session.pid !== null) {
-                try {
-                    process.kill(session.pid, 'SIGTERM');
-                }
-                catch {
-                    // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                    /* process may have already exited */
-                }
-            }
-            removeSession(projectRoot, terminalId);
-            if (opts.json === true) {
-                process.stdout.write(JSON.stringify({ ok: true, data: { stopped: session } }) + '\n');
-            }
-            else {
-                process.stdout.write(`stopped playwright session on port ${session.port} (terminal ${terminalId})\n`);
-            }
-        }
-        catch (error) {
-            if (opts.json === true) {
-                process.stdout.write(JSON.stringify({ ok: false, error: getErrorMessage(error) }) + '\n');
-            }
-            else {
-                process.stderr.write(getErrorMessage(error) + '\n');
-            }
-            process.exitCode = 1;
-        }
-    });
+        .action((opts) => runPlaywrightStart(opts));
+}
+export function registerPlaywrightCommands(program, io) {
+    const playwright = program
+        .command('playwright')
+        .description('Multi-terminal Playwright MCP lifecycle. `peaks playwright start` allocates a unique port ' +
+        '(8931→8949) and writes a session file; `ls` lists running sessions; `stop` tears them down. ' +
+        'Does NOT bundle the playwright-mcp binary (uses `npx playwright-mcp@latest`). ' +
+        '(slice 2.5.0 sub-fix C)');
+    registerPlaywrightStartCommand(playwright);
+    registerPlaywrightLsCommand(playwright, io);
+    registerPlaywrightStopCommand(playwright, io);
     // Slice 3: `peaks browser action <intent> [args...]` — thin wrapper
     // around 5 Playwright MCP intents. One MCP call per invocation; no
     // auto-snapshot between intents. See src/services/qa/browser-wrapper-service.ts.
     registerBrowserActionCommand(program);
 }
-/**
- * Wire `peaks browser action <intent>`. The wrapper is a thin adapter
- * for the 5 intents. The real MCP caller is provided by the IDE / agent
- * harness — this CLI surface is invoked by tests and skills to drive
- * browser flows without hand-shelling the MCP protocol.
- */
-export function registerBrowserActionCommand(program) {
-    const browser = program
-        .command('browser')
-        .description('Browser action helpers (slice 3: thin Playwright MCP wrapper, 5 intents only)');
-    browser
-        .command('action')
-        .description('Run one of 5 browser intents: navigate, click, fill, snapshot, extract')
-        .argument('<intent>', 'one of: navigate, click, fill, snapshot, extract')
-        .option('--url <url>', 'URL (navigate)')
-        .option('--selector <selector>', 'simple selector: #id, .class, tag, tag#id, tag.class')
-        .option('--value <value>', 'value to fill')
-        .option('--expression <expr>', 'JS expression to evaluate (extract)')
-        .option('--json', 'emit JSON envelope')
-        .action(async (intent, opts) => {
-        try {
-            if (!isSupportedIntent(intent)) {
-                throw new Error(`unknown intent "${intent}" — fall back to raw MCP (supported: navigate, click, fill, snapshot, extract)`);
-            }
-            // The IDE/agent harness bridges `mcp__playwright__browser_*` tools.
-            // Outside the harness, we use a pass-through caller that records
-            // the intent + args so skills and tests can route the call.
-            const result = await runBrowserAction(intent, {
-                url: opts.url,
-                selector: opts.selector,
-                value: opts.value,
-                expression: opts.expression
-            }, mockOrPassThroughCaller);
-            if (opts.json === true) {
-                process.stdout.write(JSON.stringify({ ok: true, data: result }) + '\n');
-            }
-            else {
-                process.stdout.write(`intent=${result.intent} ok=${result.ok} elapsedMs=${result.elapsedMs}\n`);
-            }
-        }
-        catch (error) {
-            if (opts.json === true) {
-                process.stdout.write(JSON.stringify({ ok: false, error: getErrorMessage(error) }) + '\n');
-            }
-            else {
-                process.stderr.write(getErrorMessage(error) + '\n');
-            }
-            process.exitCode = 1;
-        }
-    });
-}
-function isSupportedIntent(value) {
-    return (value === 'navigate' ||
-        value === 'click' ||
-        value === 'fill' ||
-        value === 'snapshot' ||
-        value === 'extract');
-}
-/**
- * Resolve and validate a caller-supplied `--user-data-dir`. The dir must
- * live under `projectRoot` so a malicious `--user-data-dir /etc/foo`
- * cannot coerce the playwright-mcp browser into writing state to an
- *
- * Resolves `..` segments before checking, so a path like
- * `<projectRoot>/../escape` is correctly normalized and rejected.
- *
- * Throws `Error('INVALID_USER_DATA_DIR: ...')` on validation failure;
- * the action handler catches and emits the JSON envelope.
- */
-export function resolveUserDataDir(raw, projectRoot) {
-    const resolved = resolve(projectRoot, raw);
-    const rootResolved = resolve(projectRoot) + (projectRoot.endsWith('/') || projectRoot.endsWith('\\') ? '' : '/');
-    // Use the projectRoot + sep as the prefix; require either an exact
-    // match or a child path. The `+ '/'` guard prevents sibling-prefix
-    // collisions (e.g. /home/A/proj2 passes the check for /home/A/proj).
-    if (resolved !== resolve(projectRoot) && !resolved.startsWith(rootResolved)) {
-        throw new Error(`INVALID_USER_DATA_DIR: --user-data-dir must resolve to a path under project root ${projectRoot} (got ${resolved})`);
-    }
-    return resolved;
-}
-/**
- * Pass-through caller used when the CLI surface is invoked outside the
- * harness. In production the IDE/agent harness intercepts the wrapper's
- * output and routes the underlying MCP call. Tests inject a stub via
- * the `runBrowserAction(..., caller)` overload.
- */
-async function mockOrPassThroughCaller(tool, args) {
-    return { tool, args, routedBy: 'peaks-loop-browser-wrapper' };
-}

package/dist/cli/commands/playwright-envelope.d.ts

@@ -0,0 +1,8 @@
+/** `{ ok: true, data }` on `--json`, the human line otherwise. */
+export declare function emitSuccess(json: boolean | undefined, data: unknown, text: string): void;
+/**
+ * `{ ok: false, error, code? }` on `--json`, the message on stderr otherwise.
+ * Always marks the run failed — every call site in the playwright verbs is a
+ * failure path.
+ */
+export declare function emitFailure(json: boolean | undefined, message: string, code?: string): void;

package/dist/cli/commands/playwright-envelope.js

@@ -0,0 +1,29 @@
+// src/cli/commands/playwright-envelope.ts
+//
+// The two envelope writers every `peaks playwright` action handler shares.
+// Split out of `playwright-commands.ts` so the extracted verb modules emit
+// byte-identical envelopes without repeating the branch.
+/** `{ ok: true, data }` on `--json`, the human line otherwise. */
+export function emitSuccess(json, data, text) {
+    if (json === true) {
+        process.stdout.write(JSON.stringify({ ok: true, data }) + '\n');
+    }
+    else {
+        process.stdout.write(text + '\n');
+    }
+}
+/**
+ * `{ ok: false, error, code? }` on `--json`, the message on stderr otherwise.
+ * Always marks the run failed — every call site in the playwright verbs is a
+ * failure path.
+ */
+export function emitFailure(json, message, code) {
+    if (json === true) {
+        const payload = code === undefined ? { ok: false, error: message } : { ok: false, error: message, code };
+        process.stdout.write(JSON.stringify(payload) + '\n');
+    }
+    else {
+        process.stderr.write(message + '\n');
+    }
+    process.exitCode = 1;
+}

package/dist/cli/commands/playwright-ls-stop-commands.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerPlaywrightLsCommand(playwright: Command, io: ProgramIO): void;
+export declare function registerPlaywrightStopCommand(playwright: Command, io: ProgramIO): void;

package/dist/cli/commands/playwright-ls-stop-commands.js

@@ -0,0 +1,74 @@
+// src/cli/commands/playwright-ls-stop-commands.ts
+//
+// `peaks playwright ls` and `peaks playwright stop`. Split out of
+// `playwright-commands.ts`; the registered names, descriptions, options and
+// envelopes are unchanged.
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { getErrorMessage } from '../cli-helpers.js';
+import { deriveTerminalId, listSessions, readSession, removeSession } from './playwright-session-store.js';
+import { emitFailure, emitSuccess } from './playwright-envelope.js';
+export function registerPlaywrightLsCommand(playwright, io) {
+    // These two verbs write straight to the process streams — a caller-supplied
+    // `io` must not intercept a session listing. `io` stays in the signature for
+    // the two-argument registrar contract `_register.ts` selects on.
+    void io;
+    playwright
+        .command('ls')
+        .description('List running Playwright MCP sessions from .peaks/_runtime/playwright-sessions/*.json')
+        .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
+        .option('--json', 'emit a JSON envelope { ok, data: { sessions } }')
+        .action((opts) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
+            const sessions = listSessions(projectRoot);
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: true, data: { sessions } }) + '\n');
+            }
+            else if (sessions.length === 0) {
+                process.stdout.write('no playwright sessions running\n');
+            }
+            else {
+                for (const s of sessions) {
+                    process.stdout.write(`port=${s.port}\tbrowser=${s.browser}\tterminal=${s.terminalId}\tpid=${s.pid ?? '?'}\tstarted=${s.startedAt}\n`);
+                }
+            }
+        }
+        catch (error) {
+            emitFailure(opts.json, getErrorMessage(error));
+        }
+    });
+}
+export function registerPlaywrightStopCommand(playwright, io) {
+    void io;
+    playwright
+        .command('stop')
+        .description('Stop a running Playwright MCP session (best-effort kill + remove session file).')
+        .option('--terminal <id>', "terminal id to stop (default: this shell's derived terminal id)")
+        .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
+        .option('--json', 'emit a JSON envelope { ok, data }')
+        .action((opts) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(opts.project ?? process.cwd());
+            const terminalId = opts.terminal ?? deriveTerminalId();
+            const session = readSession(projectRoot, terminalId);
+            if (!session) {
+                emitFailure(opts.json, `NO_SESSION: no playwright session for terminal ${terminalId}`);
+                return;
+            }
+            if (session.pid !== undefined && session.pid !== null) {
+                try {
+                    process.kill(session.pid, 'SIGTERM');
+                }
+                catch {
+                    // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                    /* process may have already exited */
+                }
+            }
+            removeSession(projectRoot, terminalId);
+            emitSuccess(opts.json, { stopped: session }, `stopped playwright session on port ${session.port} (terminal ${terminalId})`);
+        }
+        catch (error) {
+            emitFailure(opts.json, getErrorMessage(error));
+        }
+    });
+}