@xcanwin/manyoyo 5.8.5 → 5.8.9

package/lib/plugin/playwright.js

@@ -5,8 +5,17 @@ const net = require('net');
 const os = require('os');
 const path = require('path');
 const crypto = require('crypto');
-const { spawn, spawnSync } = require('child_process');
+const { spawnSync } = require('child_process');
 const { playwrightCliVersion: PLAYWRIGHT_CLI_VERSION } = require('../../package.json');
+const { PlaywrightExtensionManager } = require('./playwright-extension-manager');
+const { createPlaywrightCommandOutputManager } = require('./playwright-command-output');
+const { createPlaywrightContainerRuntimeManager } = require('./playwright-container-runtime');
+const { createPlaywrightExtensionPathManager } = require('./playwright-extension-paths');
+const { createPlaywrightHostRuntimeManager } = require('./playwright-host-runtime');
+const { createPlaywrightBootstrapManager } = require('./playwright-bootstrap');
+const { createPlaywrightSceneConfigManager } = require('./playwright-scene-config');
+const { createPlaywrightSceneDrivers } = require('./playwright-scene-drivers');
+const { createPlaywrightSceneStateManager } = require('./playwright-scene-state');
 
 const EXTENSIONS = [
     ['ublock-origin-lite', 'ddkjiahejlhfcafbddmgiahcphecmpfh'],
@@ -77,6 +86,12 @@ const SCENE_DEFS = {
 
 const VALID_RUNTIME = new Set(['container', 'host', 'mixed']);
 const VALID_ACTIONS = new Set(['up', 'down', 'status', 'health', 'logs']);
+const DIRECT_ACTION_HANDLERS = {
+    ls: (plugin) => plugin.printSummary(),
+    'mcp-add': (plugin, options) => plugin.printMcpAdd(options.host),
+    'cli-add': (plugin) => plugin.printCliAdd(),
+    'ext-download': (plugin, options) => plugin.downloadExtensions({ prodversion: options.prodversion })
+};
 const CONTAINER_EXTENSION_ROOT = '/app/extensions';
 const DEFAULT_FINGERPRINT_PROFILE = {
     userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36',
@@ -154,129 +169,6 @@ function asBoolean(value, fallback = false) {
     return fallback;
 }
 
-function isHostPermission(value) {
-    if (value === '<all_urls>') {
-        return true;
-    }
-    return /^(?:\*|http|https|file|ftp):\/\//.test(value);
-}
-
-function scriptSourcesFromHtml(htmlFile) {
-    const content = fs.readFileSync(htmlFile, { encoding: 'utf8' });
-    const scripts = [...content.matchAll(/<script[^>]+src=["']([^"']+)["']/gi)].map(m => m[1]);
-    return scripts.filter(src => !/^(?:https?:)?\/\//.test(src));
-}
-
-function convertManifestV2ToV3(extDir) {
-    const manifestFile = path.join(extDir, 'manifest.json');
-    const manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
-    if (manifest.manifest_version !== 2) {
-        return false;
-    }
-
-    manifest.manifest_version = 3;
-
-    if (manifest.browser_action && !manifest.action) {
-        manifest.action = manifest.browser_action;
-        delete manifest.browser_action;
-    }
-    if (manifest.page_action && !manifest.action) {
-        manifest.action = manifest.page_action;
-        delete manifest.page_action;
-    }
-
-    const background = manifest.background;
-    if (background && typeof background === 'object' && !Array.isArray(background)) {
-        let scripts = [];
-        if (Array.isArray(background.scripts)) {
-            scripts = background.scripts.filter(s => typeof s === 'string');
-        } else if (typeof background.page === 'string') {
-            const pagePath = path.join(extDir, background.page);
-            if (fs.existsSync(pagePath)) {
-                scripts = scriptSourcesFromHtml(pagePath);
-            }
-        }
-
-        if (scripts.length > 0) {
-            const swName = 'generated_background_sw.js';
-            const swFile = path.join(extDir, swName);
-            const swLines = [
-                '// Auto-generated by manyoyo playwright ext-download for MV3.',
-                `importScripts(${scripts.map(s => JSON.stringify(s)).join(', ')});`,
-                ''
-            ];
-            fs.writeFileSync(swFile, swLines.join('\n'), 'utf8');
-            manifest.background = { service_worker: swName };
-        } else {
-            delete manifest.background;
-        }
-    }
-
-    if (typeof manifest.content_security_policy === 'string') {
-        manifest.content_security_policy = { extension_pages: manifest.content_security_policy };
-    }
-
-    if (Array.isArray(manifest.permissions)) {
-        const hostPermissions = Array.isArray(manifest.host_permissions) ? [...manifest.host_permissions] : [];
-        const keptPermissions = [];
-
-        for (const perm of manifest.permissions) {
-            if (typeof perm === 'string' && isHostPermission(perm)) {
-                if (!hostPermissions.includes(perm)) {
-                    hostPermissions.push(perm);
-                }
-            } else {
-                keptPermissions.push(perm);
-            }
-        }
-
-        manifest.permissions = keptPermissions;
-        if (hostPermissions.length > 0) {
-            manifest.host_permissions = hostPermissions;
-        }
-    }
-
-    const war = manifest.web_accessible_resources;
-    if (Array.isArray(war) && war.length > 0 && war.every(v => typeof v === 'string')) {
-        manifest.web_accessible_resources = [
-            {
-                resources: war,
-                matches: ['<all_urls>']
-            }
-        ];
-    }
-
-    fs.writeFileSync(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
-    return true;
-}
-
-function buildCrxUrl(extId, prodversion) {
-    return (
-        'https://clients2.google.com/service/update2/crx' +
-        `?response=redirect&prodversion=${prodversion}` +
-        '&acceptformat=crx2,crx3' +
-        `&x=id%3D${extId}%26installsource%3Dondemand%26uc`
-    );
-}
-
-function crxZipOffset(data) {
-    if (data.subarray(0, 4).toString('ascii') !== 'Cr24') {
-        throw new Error('not a CRX file');
-    }
-
-    const version = data.readUInt32LE(4);
-    if (version === 2) {
-        const pubLen = data.readUInt32LE(8);
-        const sigLen = data.readUInt32LE(12);
-        return 16 + pubLen + sigLen;
-    }
-    if (version === 3) {
-        const headerLen = data.readUInt32LE(8);
-        return 12 + headerLen;
-    }
-    throw new Error(`unsupported CRX version: ${version}`);
-}
-
 class PlaywrightPlugin {
     constructor(options = {}) {
         this.projectRoot = options.projectRoot || path.join(__dirname, '..', '..');
@@ -285,6 +177,58 @@ class PlaywrightPlugin {
         this.globalConfig = asObject(options.globalConfig);
         this.runConfig = asObject(options.runConfig);
         this.config = this.resolveConfig();
+        this.extensionManager = new PlaywrightExtensionManager({
+            extensions: EXTENSIONS,
+            ensureCommandAvailable: this.ensureCommandAvailable.bind(this),
+            runCmd: this.runCmd.bind(this),
+            writeStdout: this.writeStdout.bind(this),
+            writeStderr: this.writeStderr.bind(this),
+            extensionDirPath: this.extensionDirPath.bind(this),
+            extensionTmpDirPath: this.extensionTmpDirPath.bind(this),
+            defaultProdversion: this.config.extensionProdversion
+        });
+        this.containerRuntimeManager = createPlaywrightContainerRuntimeManager({
+            plugin: this,
+            sceneDefs: SCENE_DEFS
+        });
+        this.commandOutputManager = createPlaywrightCommandOutputManager({
+            plugin: this,
+            isMcpScene,
+            playwrightCliVersion: PLAYWRIGHT_CLI_VERSION
+        });
+        this.hostRuntimeManager = createPlaywrightHostRuntimeManager({
+            plugin: this,
+            isCliScene,
+            sleep
+        });
+        this.extensionPathManager = createPlaywrightExtensionPathManager({
+            plugin: this,
+            asStringArray,
+            containerExtensionRoot: CONTAINER_EXTENSION_ROOT
+        });
+        this.bootstrapManager = createPlaywrightBootstrapManager({
+            plugin: this,
+            isCliScene
+        });
+        this.sceneConfigManager = createPlaywrightSceneConfigManager({
+            plugin: this,
+            sceneDefs: SCENE_DEFS,
+            isCliScene,
+            asStringArray,
+            defaultFingerprintProfile: DEFAULT_FINGERPRINT_PROFILE,
+            disableWebRtcLaunchArgs: DISABLE_WEBRTC_LAUNCH_ARGS
+        });
+        this.sceneStateManager = createPlaywrightSceneStateManager({
+            plugin: this
+        });
+        this.sceneDrivers = createPlaywrightSceneDrivers({
+            plugin: this,
+            sceneDefs: SCENE_DEFS,
+            isCliScene,
+            asStringArray,
+            tailText,
+            sleep
+        });
     }
 
     resolveConfig() {
@@ -472,41 +416,31 @@ class PlaywrightPlugin {
     }
 
     sceneEndpointPath(sceneName) {
-        return path.join(this.config.runDir, `${sceneName}.endpoint.json`);
+        return this.sceneStateManager.sceneEndpointPath(sceneName);
     }
 
     readSceneEndpoint(sceneName) {
-        const filePath = this.sceneEndpointPath(sceneName);
-        if (!fs.existsSync(filePath)) {
-            return null;
-        }
-        try {
-            return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-        } catch {
-            return null;
-        }
+        return this.sceneStateManager.readSceneEndpoint(sceneName);
     }
 
     writeSceneEndpoint(sceneName, payload) {
-        fs.mkdirSync(this.config.runDir, { recursive: true });
-        fs.writeFileSync(this.sceneEndpointPath(sceneName), `${JSON.stringify(payload, null, 4)}\n`, 'utf8');
+        this.sceneStateManager.writeSceneEndpoint(sceneName, payload);
     }
 
     removeSceneEndpoint(sceneName) {
-        fs.rmSync(this.sceneEndpointPath(sceneName), { force: true });
+        this.sceneStateManager.removeSceneEndpoint(sceneName);
     }
 
     sceneCliAttachConfigPath(sceneName) {
-        return path.join(this.config.runDir, `${sceneName}.cli-attach.json`);
+        return this.sceneStateManager.sceneCliAttachConfigPath(sceneName);
     }
 
     writeSceneCliAttachConfig(sceneName, payload) {
-        fs.mkdirSync(this.config.runDir, { recursive: true });
-        fs.writeFileSync(this.sceneCliAttachConfigPath(sceneName), `${JSON.stringify(payload, null, 4)}\n`, 'utf8');
+        this.sceneStateManager.writeSceneCliAttachConfig(sceneName, payload);
     }
 
     removeSceneCliAttachConfig(sceneName) {
-        fs.rmSync(this.sceneCliAttachConfigPath(sceneName), { force: true });
+        this.sceneStateManager.removeSceneCliAttachConfig(sceneName);
     }
 
     sceneInitScriptPath(sceneName) {
@@ -515,81 +449,23 @@ class PlaywrightPlugin {
     }
 
     buildInitScriptContent() {
-        const lines = [
-            "'use strict';",
-            '(function () {',
-            `    const platformValue = ${JSON.stringify(this.config.navigatorPlatform)};`,
-            '    try {',
-            '        const navProto = Object.getPrototypeOf(navigator);',
-            "        Object.defineProperty(navProto, 'platform', {",
-            '            configurable: true,',
-            '            get: () => platformValue',
-            '        });',
-            '    } catch (_) {}'
-        ];
-
-        if (this.config.disableWebRTC) {
-            lines.push(
-                '    try {',
-                '        const scope = globalThis;',
-                "        const blocked = ['RTCPeerConnection', 'webkitRTCPeerConnection', 'RTCIceCandidate', 'RTCRtpSender', 'RTCRtpReceiver', 'RTCRtpTransceiver', 'RTCDataChannel'];",
-                '        for (const name of blocked) {',
-                "            Object.defineProperty(scope, name, { configurable: true, writable: true, value: undefined });",
-                '        }',
-                '        if (navigator.mediaDevices) {',
-                '            const errorFactory = () => {',
-                '                try {',
-                "                    return new DOMException('WebRTC is disabled', 'NotAllowedError');",
-                '                } catch (_) {',
-                "                    const error = new Error('WebRTC is disabled');",
-                "                    error.name = 'NotAllowedError';",
-                '                    return error;',
-                '                }',
-                '            };',
-                "            Object.defineProperty(navigator.mediaDevices, 'getUserMedia', {",
-                '                configurable: true,',
-                '                writable: true,',
-                '                value: async () => { throw errorFactory(); }',
-                '            });',
-                '        }',
-                '    } catch (_) {}'
-            );
-        }
-
-        lines.push('})();', '');
-        return lines.join('\n');
+        return this.bootstrapManager.buildInitScriptContent();
     }
 
     ensureSceneInitScript(sceneName) {
-        const filePath = this.sceneInitScriptPath(sceneName);
-        const content = this.buildInitScriptContent();
-        fs.writeFileSync(filePath, content, 'utf8');
-        return filePath;
+        return this.bootstrapManager.ensureSceneInitScript(sceneName);
     }
 
     defaultBrowserName(sceneName) {
-        if (isCliScene(sceneName)) {
-            return 'chromium';
-        }
-        const cfg = this.buildSceneConfig(sceneName);
-        const browserName = cfg && cfg.browser && cfg.browser.browserName;
-        return String(browserName || 'chromium');
+        return this.bootstrapManager.defaultBrowserName(sceneName);
     }
 
     ensureContainerScenePrerequisites(sceneName) {
-        if (!this.sceneConfigMissing(sceneName)) {
-            return;
-        }
-        const tag = String(this.config.dockerTag || 'latest').trim() || 'latest';
-        const image = `mcr.microsoft.com/playwright/mcp:${tag}`;
-        this.runCmd([this.config.containerRuntime, 'pull', image], { check: true });
+        this.bootstrapManager.ensureContainerScenePrerequisites(sceneName);
     }
 
     ensureHostScenePrerequisites(sceneName) {
-        if (!isCliScene(sceneName) && !this.sceneConfigMissing(sceneName)) {
-            return;
-        }
-        this.runCmd([this.playwrightBinPath(sceneName), 'install', '--with-deps', this.defaultBrowserName(sceneName)], { check: true });
+        this.bootstrapManager.ensureHostScenePrerequisites(sceneName);
     }
 
     scenePidFile(sceneName) {
@@ -601,32 +477,11 @@ class PlaywrightPlugin {
     }
 
     localBinPath(binName) {
-        const filename = process.platform === 'win32' ? `${binName}.cmd` : binName;
-        const binPath = path.join(this.projectRoot, 'node_modules', '.bin', filename);
-        if (!fs.existsSync(binPath)) {
-            throw new Error(`local binary not found: ${binPath}. Run npm install first.`);
-        }
-        return binPath;
+        return this.bootstrapManager.localBinPath(binName);
     }
 
     playwrightBinPath(sceneName) {
-        if (!isCliScene(sceneName)) {
-            return this.localBinPath('playwright');
-        }
-
-        const filename = process.platform === 'win32' ? 'playwright.cmd' : 'playwright';
-        const candidates = [
-            path.join(this.projectRoot, 'node_modules', '@playwright', 'mcp', 'node_modules', '.bin', filename),
-            path.join(this.projectRoot, 'node_modules', '.bin', filename)
-        ];
-
-        for (const candidate of candidates) {
-            if (fs.existsSync(candidate)) {
-                return candidate;
-            }
-        }
-
-        throw new Error(`local binary not found for ${sceneName}. Run npm install first.`);
+        return this.bootstrapManager.playwrightBinPath(sceneName);
     }
 
     extensionDirPath() {
@@ -680,216 +535,55 @@ class PlaywrightPlugin {
     }
 
     resolveExtensionPaths(extensionArgs = []) {
-        const inputs = asStringArray(extensionArgs, []);
-        const uniquePaths = [];
-        const seen = new Set();
-
-        for (const item of inputs) {
-            const absPath = path.resolve(item);
-            if (!fs.existsSync(absPath)) {
-                throw new Error(`扩展路径不存在: ${absPath}`);
-            }
-            const stat = fs.statSync(absPath);
-            if (!stat.isDirectory()) {
-                throw new Error(`扩展路径必须是目录: ${absPath}`);
-            }
-
-            const manifestPath = path.join(absPath, 'manifest.json');
-            if (fs.existsSync(manifestPath)) {
-                if (!seen.has(absPath)) {
-                    seen.add(absPath);
-                    uniquePaths.push(absPath);
-                }
-                continue;
-            }
-
-            const children = fs.readdirSync(absPath, { withFileTypes: true })
-                .filter(dirent => dirent.isDirectory())
-                .map(dirent => path.join(absPath, dirent.name))
-                .filter(child => fs.existsSync(path.join(child, 'manifest.json')));
-
-            if (children.length === 0) {
-                throw new Error(`目录下未找到扩展(manifest.json): ${absPath}`);
-            }
-
-            for (const childPath of children) {
-                if (!seen.has(childPath)) {
-                    seen.add(childPath);
-                    uniquePaths.push(childPath);
-                }
-            }
-        }
-
-        return uniquePaths;
+        return this.extensionPathManager.resolveExtensionPaths(extensionArgs);
     }
 
     resolveNamedExtensionPaths(extensionNames = []) {
-        const names = asStringArray(extensionNames, []);
-        const extensionRoot = path.resolve(this.extensionDirPath());
-
-        return names.map(name => {
-            if (name.includes('/') || name.includes('\\') || name === '.' || name === '..') {
-                throw new Error(`扩展名称无效: ${name}`);
-            }
-            return path.join(extensionRoot, name);
-        });
+        return this.extensionPathManager.resolveNamedExtensionPaths(extensionNames);
     }
 
     resolveExtensionInputs(options = {}) {
-        const extensionPaths = asStringArray(options.extensionPaths, []);
-        const namedPaths = this.resolveNamedExtensionPaths(options.extensionNames || []);
-        return this.resolveExtensionPaths([...extensionPaths, ...namedPaths]);
+        return this.extensionPathManager.resolveExtensionInputs(options);
     }
 
     buildExtensionLaunchArgs(extensionPaths) {
-        const joined = extensionPaths.join(',');
-        return [
-            `--disable-extensions-except=${joined}`,
-            `--load-extension=${joined}`
-        ];
+        return this.sceneConfigManager.buildExtensionLaunchArgs(extensionPaths);
     }
 
     sanitizeExtensionMountName(value) {
-        const sanitized = String(value || '')
-            .trim()
-            .replace(/[^A-Za-z0-9._-]/g, '-')
-            .replace(/-+/g, '-')
-            .replace(/^-|-$/g, '');
-        return sanitized || 'ext';
+        return this.extensionPathManager.sanitizeExtensionMountName(value);
     }
 
     buildContainerExtensionMounts(extensionPaths = []) {
-        const hostPaths = asStringArray(extensionPaths, []);
-        const containerPaths = [];
-        const volumeMounts = [];
-
-        hostPaths.forEach((hostPath, idx) => {
-            const safeName = this.sanitizeExtensionMountName(path.basename(hostPath));
-            const containerPath = path.posix.join(CONTAINER_EXTENSION_ROOT, `ext-${idx + 1}-${safeName}`);
-            containerPaths.push(containerPath);
-            volumeMounts.push(`${hostPath}:${containerPath}:ro`);
-        });
-
-        return { containerPaths, volumeMounts };
+        return this.extensionPathManager.buildContainerExtensionMounts(extensionPaths);
     }
 
     baseLaunchArgs() {
-        return [
-            `--user-agent=${DEFAULT_FINGERPRINT_PROFILE.userAgent}`,
-            `--lang=${DEFAULT_FINGERPRINT_PROFILE.locale}`,
-            `--window-size=${DEFAULT_FINGERPRINT_PROFILE.width},${DEFAULT_FINGERPRINT_PROFILE.height}`,
-            '--disable-blink-features=AutomationControlled',
-            '--force-webrtc-ip-handling-policy=disable_non_proxied_udp'
-        ];
+        return this.sceneConfigManager.baseLaunchArgs();
     }
 
-    buildMcpSceneConfig(sceneName, options = {}) {
-        const def = SCENE_DEFS[sceneName];
-        const port = this.scenePort(sceneName);
-        const extensionPaths = asStringArray(options.extensionPaths, []);
-        const initScript = asStringArray(options.initScript, []);
-        const launchOptions = {
-            channel: 'chromium',
-            headless: def.headless,
-            args: [...this.baseLaunchArgs()]
-        };
-
-        if (extensionPaths.length > 0) {
-            launchOptions.args.push(...this.buildExtensionLaunchArgs(extensionPaths));
-        }
-        if (this.config.disableWebRTC) {
-            launchOptions.args.push(...DISABLE_WEBRTC_LAUNCH_ARGS);
-        }
-
-        const contextOptions = {
-            userAgent: DEFAULT_FINGERPRINT_PROFILE.userAgent,
-            locale: DEFAULT_FINGERPRINT_PROFILE.locale,
-            timezoneId: DEFAULT_FINGERPRINT_PROFILE.timezoneId,
-            extraHTTPHeaders: {
-                'Accept-Language': DEFAULT_FINGERPRINT_PROFILE.acceptLanguage
-            }
-        };
-        if (sceneName !== 'mcp-host-headed') {
-            contextOptions.viewport = {
-                width: DEFAULT_FINGERPRINT_PROFILE.width,
-                height: DEFAULT_FINGERPRINT_PROFILE.height
-            };
-            contextOptions.screen = {
-                width: DEFAULT_FINGERPRINT_PROFILE.width,
-                height: DEFAULT_FINGERPRINT_PROFILE.height
-            };
-        }
+    buildSceneLaunchArgs(extensionPaths = []) {
+        return this.sceneConfigManager.buildSceneLaunchArgs(extensionPaths);
+    }
 
-        return {
-            outputDir: '/tmp/.playwright-mcp',
-            server: {
-                host: def.listenHost,
-                port,
-                allowedHosts: [
-                    `localhost:${port}`,
-                    `127.0.0.1:${port}`,
-                    `host.docker.internal:${port}`,
-                    `host.containers.internal:${port}`
-                ]
-            },
-            browser: {
-                chromiumSandbox: true,
-                browserName: 'chromium',
-                initScript,
-                launchOptions,
-                contextOptions
-            }
-        };
+    buildMcpSceneConfig(sceneName, options = {}) {
+        return this.sceneConfigManager.buildMcpSceneConfig(sceneName, options);
     }
 
     buildCliSceneConfig(sceneName, options = {}) {
-        const def = SCENE_DEFS[sceneName];
-        const extensionPaths = asStringArray(options.extensionPaths, []);
-        const payload = {
-            host: def.listenHost,
-            port: this.scenePort(sceneName),
-            wsPath: `/${sceneName}-${crypto.randomBytes(8).toString('hex')}`,
-            headless: def.headless,
-            channel: 'chromium',
-            chromiumSandbox: true,
-            args: [...this.baseLaunchArgs()]
-        };
-
-        if (extensionPaths.length > 0) {
-            payload.args.push(...this.buildExtensionLaunchArgs(extensionPaths));
-        }
-        if (this.config.disableWebRTC) {
-            payload.args.push(...DISABLE_WEBRTC_LAUNCH_ARGS);
-        }
-
-        return payload;
+        return this.sceneConfigManager.buildCliSceneConfig(sceneName, options);
     }
 
     buildSceneConfig(sceneName, options = {}) {
-        if (isCliScene(sceneName)) {
-            return this.buildCliSceneConfig(sceneName, options);
-        }
-        return this.buildMcpSceneConfig(sceneName, options);
+        return this.sceneConfigManager.buildSceneConfig(sceneName, options);
+    }
+
+    writeSceneConfigFile(sceneName, payload) {
+        return this.sceneConfigManager.writeSceneConfigFile(sceneName, payload);
     }
 
     ensureSceneConfig(sceneName, options = {}) {
-        fs.mkdirSync(this.config.configDir, { recursive: true });
-        if (isCliScene(sceneName)) {
-            const payload = this.buildCliSceneConfig(sceneName, options);
-            const filePath = this.sceneConfigPath(sceneName);
-            fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 4)}\n`, 'utf8');
-            return filePath;
-        }
-        const initScriptPath = this.ensureSceneInitScript(sceneName);
-        const configuredInitScript = asStringArray(options.initScript, []);
-        const initScript = configuredInitScript.length > 0 ? configuredInitScript : [initScriptPath];
-        const payload = this.buildSceneConfig(sceneName, {
-            ...options,
-            initScript
-        });
-        const filePath = this.sceneConfigPath(sceneName);
-        fs.writeFileSync(filePath, `${JSON.stringify(payload, null, 4)}\n`, 'utf8');
-        return filePath;
+        return this.sceneConfigManager.ensureSceneConfig(sceneName, options);
     }
 
     async portReady(port) {
@@ -926,465 +620,99 @@ class PlaywrightPlugin {
     }
 
     containerEnv(sceneName, cfgPath, options = {}) {
-        const def = SCENE_DEFS[sceneName];
-        const requireVncPassword = options.requireVncPassword === true;
-        const env = {
-            ...process.env,
-            PLAYWRIGHT_MCP_DOCKER_TAG: this.config.dockerTag,
-            PLAYWRIGHT_MCP_PORT: String(this.scenePort(sceneName)),
-            PLAYWRIGHT_MCP_CONFIG_PATH: cfgPath,
-            PLAYWRIGHT_MCP_CONTAINER_NAME: def.containerName,
-            PLAYWRIGHT_MCP_IMAGE: this.config.headedImage,
-            PLAYWRIGHT_MCP_NOVNC_PORT: String(this.config.ports.mcpContHeadedNoVnc)
-        };
-
-        if (sceneName === 'mcp-cont-headed') {
-            const envKey = this.config.vncPasswordEnvKey;
-            let password = process.env[envKey];
-            if (!password) {
-                password = this.randomAlnum(16);
-                if (requireVncPassword) {
-                    this.writeStdout(`[up] mcp-cont-headed ${envKey} not set; generated random 16-char password: ${password}`);
-                }
-            }
-            env.VNC_PASSWORD = password;
-        }
-
-        return env;
+        return this.containerRuntimeManager.containerEnv(sceneName, cfgPath, options);
     }
 
     containerComposePath(sceneName) {
-        const def = SCENE_DEFS[sceneName];
-        return path.join(this.config.composeDir, def.composeFile);
+        return this.containerRuntimeManager.containerComposePath(sceneName);
     }
 
     sceneComposeOverridePath(sceneName) {
-        return path.join(this.config.runDir, `${sceneName}.compose.override.yaml`);
+        return this.containerRuntimeManager.sceneComposeOverridePath(sceneName);
     }
 
     ensureContainerComposeOverride(sceneName, volumeMounts = []) {
-        const overridePath = this.sceneComposeOverridePath(sceneName);
-        if (!Array.isArray(volumeMounts) || volumeMounts.length === 0) {
-            fs.rmSync(overridePath, { force: true });
-            return '';
-        }
-
-        fs.mkdirSync(this.config.runDir, { recursive: true });
-        const lines = [
-            'services:',
-            '  playwright:',
-            '    volumes:'
-        ];
-        volumeMounts.forEach(item => {
-            lines.push(`      - ${JSON.stringify(String(item))}`);
-        });
-        fs.writeFileSync(overridePath, `${lines.join('\n')}\n`, 'utf8');
-        return overridePath;
+        return this.containerRuntimeManager.ensureContainerComposeOverride(sceneName, volumeMounts);
     }
 
     buildCliSessionIntegration(dockerCmd) {
-        const sceneName = this.config.cliSessionScene;
-        if (!sceneName) {
-            return { envEntries: [], extraArgs: [], volumeEntries: [] };
-        }
-
-        const endpoint = this.readSceneEndpoint(sceneName);
-        if (!endpoint || !Number.isInteger(endpoint.port) || endpoint.port <= 0 || typeof endpoint.wsPath !== 'string' || !endpoint.wsPath) {
-            return { envEntries: [], extraArgs: [], volumeEntries: [] };
-        }
-
-        const normalizedDockerCmd = String(dockerCmd || '').trim().toLowerCase();
-        const connectHost = normalizedDockerCmd === 'podman' ? 'host.containers.internal' : 'host.docker.internal';
-        const remoteEndpoint = `ws://${connectHost}:${endpoint.port}${endpoint.wsPath}`;
-        const hostConfigPath = this.sceneCliAttachConfigPath(sceneName);
-        const containerConfigPath = `/tmp/manyoyo-playwright/${sceneName}.cli-attach.json`;
-        this.writeSceneCliAttachConfig(sceneName, {
-            browser: {
-                remoteEndpoint
-            }
-        });
-        const envEntries = [
-            `PLAYWRIGHT_MCP_CONFIG=${containerConfigPath}`
-        ];
-        const extraArgs = normalizedDockerCmd === 'docker'
-            ? ['--add-host', 'host.docker.internal:host-gateway']
-            : [];
-        const volumeEntries = ['--volume', `${hostConfigPath}:${containerConfigPath}:ro`];
-        return { envEntries, extraArgs, volumeEntries };
+        return this.sceneStateManager.buildCliSessionIntegration(dockerCmd);
     }
 
     async startContainer(sceneName, options = {}) {
-        const runtime = this.config.containerRuntime;
-        if (!this.ensureCommandAvailable(runtime)) {
-            this.writeStderr(`[up] ${sceneName} failed: ${runtime} command not found.`);
-            return 1;
-        }
-
-        try {
-            this.ensureContainerScenePrerequisites(sceneName);
-        } catch (error) {
-            return error.returncode || 1;
-        }
-
-        const incomingExtensionPaths = asStringArray(options.extensionPaths, []);
-        const hostInitScriptPath = this.sceneInitScriptPath(sceneName);
-        const containerInitScriptPath = path.posix.join('/app/config', path.basename(hostInitScriptPath));
-        let configOptions = {
-            ...options,
-            extensionPaths: incomingExtensionPaths,
-            initScript: [containerInitScriptPath]
-        };
-        const composeFiles = [this.containerComposePath(sceneName)];
-        const volumeMounts = [`${hostInitScriptPath}:${containerInitScriptPath}:ro`];
-
-        if (incomingExtensionPaths.length > 0) {
-            const mapped = this.buildContainerExtensionMounts(incomingExtensionPaths);
-            volumeMounts.push(...mapped.volumeMounts);
-            configOptions = {
-                ...options,
-                extensionPaths: mapped.containerPaths,
-                initScript: [containerInitScriptPath]
-            };
-        }
-        const cfgPath = this.ensureSceneConfig(sceneName, configOptions);
-        const overridePath = this.ensureContainerComposeOverride(sceneName, volumeMounts);
-        if (overridePath) {
-            composeFiles.push(overridePath);
-        }
-
-        const env = this.containerEnv(sceneName, cfgPath, { requireVncPassword: true });
-        const def = SCENE_DEFS[sceneName];
-
-        try {
-            const args = [
-                runtime,
-                'compose',
-                '-p',
-                def.projectName
-            ];
-            composeFiles.forEach(filePath => {
-                args.push('-f', filePath);
-            });
-            args.push('up', '-d');
-            this.runCmd(args, { env, check: true });
-        } catch (error) {
-            return error.returncode || 1;
-        }
-
-        const port = this.scenePort(sceneName);
-        if (await this.waitForPort(port)) {
-            this.writeStdout(`[up] ${sceneName} ready on 127.0.0.1:${port}`);
-            return 0;
-        }
-
-        this.writeStderr(`[up] ${sceneName} did not become ready on 127.0.0.1:${port}`);
-        return 1;
+        return await this.sceneDrivers.container.up(sceneName, options);
     }
 
     stopContainer(sceneName) {
-        const runtime = this.config.containerRuntime;
-        if (!this.ensureCommandAvailable(runtime)) {
-            this.writeStderr(`[down] ${sceneName} failed: ${runtime} command not found.`);
-            return 1;
-        }
-
-        this.ensureContainerComposeOverride(sceneName, []);
-        const cfgPath = this.sceneConfigPath(sceneName);
-        const env = this.containerEnv(sceneName, cfgPath);
-        const def = SCENE_DEFS[sceneName];
-
-        try {
-            this.runCmd([
-                runtime,
-                'compose',
-                '-p',
-                def.projectName,
-                '-f',
-                this.containerComposePath(sceneName),
-                'down'
-            ], { env, check: true });
-        } catch (error) {
-            return error.returncode || 1;
-        }
-
-        this.writeStdout(`[down] ${sceneName}`);
-        return 0;
+        return this.sceneDrivers.container.down(sceneName);
     }
 
     statusContainer(sceneName) {
-        const runtime = this.config.containerRuntime;
-        if (!this.ensureCommandAvailable(runtime)) {
-            this.writeStderr(`[status] ${sceneName} failed: ${runtime} command not found.`);
-            return 1;
-        }
-
-        const def = SCENE_DEFS[sceneName];
-        const cp = this.runCmd([
-            runtime,
-            'ps',
-            '--filter',
-            `name=${def.containerName}`,
-            '--format',
-            '{{.Names}}'
-        ], { captureOutput: true, check: false });
-
-        const names = new Set(
-            cp.stdout
-                .split(/\r?\n/)
-                .map(line => line.trim())
-                .filter(Boolean)
-        );
-
-        if (names.has(def.containerName)) {
-            this.writeStdout(`[status] ${sceneName} running`);
-        } else {
-            this.writeStdout(`[status] ${sceneName} stopped`);
-        }
-        return 0;
+        return this.sceneDrivers.container.status(sceneName);
     }
 
     logsContainer(sceneName) {
-        const runtime = this.config.containerRuntime;
-        if (!this.ensureCommandAvailable(runtime)) {
-            this.writeStderr(`[logs] ${sceneName} failed: ${runtime} command not found.`);
-            return 1;
-        }
+        return this.sceneDrivers.container.logs(sceneName);
+    }
 
-        const def = SCENE_DEFS[sceneName];
-        const cp = this.runCmd([
-            runtime,
-            'logs',
-            '--tail',
-            '80',
-            def.containerName
-        ], { captureOutput: true, check: false });
-
-        const output = cp.stdout || cp.stderr;
-        if (output.trim()) {
-            this.writeStdout(output.trimEnd());
-        } else {
-            this.writeStdout(`[logs] ${sceneName} no logs`);
-        }
+    ensureContainerRuntimeAvailable(action, sceneName) {
+        return this.containerRuntimeManager.ensureContainerRuntimeAvailable(action, sceneName);
+    }
 
-        return cp.returncode === 0 ? 0 : 1;
+    buildContainerComposeCommand(sceneName, composeFiles = [], trailingArgs = []) {
+        return this.containerRuntimeManager.buildContainerComposeCommand(sceneName, composeFiles, trailingArgs);
     }
 
     hostLaunchCommand(sceneName, cfgPath) {
-        if (isCliScene(sceneName)) {
-            return {
-                command: this.playwrightBinPath(sceneName),
-                args: ['launch-server', '--browser', this.defaultBrowserName(sceneName), '--config', String(cfgPath)]
-            };
-        }
-        return {
-            command: this.localBinPath('playwright-mcp'),
-            args: ['--config', String(cfgPath)]
-        };
+        return this.hostRuntimeManager.hostLaunchCommand(sceneName, cfgPath);
     }
 
     spawnHostProcess(command, args, logFd) {
-        return spawn(command, args, {
-            detached: true,
-            stdio: ['ignore', logFd, logFd]
-        });
+        return this.hostRuntimeManager.spawnHostProcess(command, args, logFd);
     }
 
     stopHostStarter(pid) {
-        if (!Number.isInteger(pid) || pid <= 0) {
-            return;
-        }
-        try {
-            process.kill(-pid, 'SIGTERM');
-            return;
-        } catch {
-            // no-op
-        }
-        try {
-            process.kill(pid, 'SIGTERM');
-        } catch {
-            // no-op
-        }
+        this.hostRuntimeManager.stopHostStarter(pid);
     }
 
     hostScenePids(sceneName) {
-        const cfgPath = this.sceneConfigPath(sceneName);
-        const pattern = isCliScene(sceneName)
-            ? `playwright.*launch-server.*--config ${cfgPath}`
-            : `playwright-mcp.*--config ${cfgPath}`;
-        const cp = this.runCmd(['pgrep', '-f', pattern], { captureOutput: true, check: false });
-
-        if (cp.returncode !== 0 || !cp.stdout.trim()) {
-            return [];
-        }
-
-        const pids = [];
-        for (const line of cp.stdout.split(/\r?\n/)) {
-            const text = line.trim();
-            if (/^\d+$/.test(text)) {
-                pids.push(Number(text));
-            }
-        }
-        return pids;
+        return this.hostRuntimeManager.hostScenePids(sceneName);
     }
 
     async waitForHostPids(sceneName, fallbackPid) {
-        for (let i = 0; i < 5; i += 1) {
-            const pids = this.hostScenePids(sceneName);
-            if (pids.length > 0) {
-                return pids;
-            }
-            // eslint-disable-next-line no-await-in-loop
-            await sleep(100);
-        }
-        if (Number.isInteger(fallbackPid) && fallbackPid > 0) {
-            return [fallbackPid];
-        }
-        return [];
+        return await this.hostRuntimeManager.waitForHostPids(sceneName, fallbackPid);
     }
 
-    async startHost(sceneName, options = {}) {
-        try {
-            this.ensureCliHostHeadedCacheDir(sceneName);
-            this.ensureHostScenePrerequisites(sceneName);
-        } catch (error) {
-            this.writeStderr(`[up] ${sceneName} failed: ${error.message || String(error)}`);
-            return error.returncode || 1;
-        }
-
-        fs.mkdirSync(this.config.runDir, { recursive: true });
-        const cfgPath = this.ensureSceneConfig(sceneName, options);
-        const pidFile = this.scenePidFile(sceneName);
-        const logFile = this.sceneLogFile(sceneName);
-        const port = this.scenePort(sceneName);
-        this.removeSceneEndpoint(sceneName);
-        this.removeSceneCliAttachConfig(sceneName);
-
-        let managedPids = this.hostScenePids(sceneName);
-        if (managedPids.length > 0 && (await this.portReady(port))) {
-            this.writeStdout(`[up] ${sceneName} already running (pid(s) ${managedPids.join(' ')})`);
-            return 0;
-        }
-
-        if (await this.portReady(port)) {
-            this.writeStderr(`[up] ${sceneName} failed: port ${port} is already in use by another process.`);
-            this.writeStderr('Stop the conflicting process first, then retry.');
-            return 1;
-        }
-
-        fs.rmSync(pidFile, { force: true });
-        const logFd = fs.openSync(logFile, 'a');
-        let launchCommand = null;
-        try {
-            launchCommand = this.hostLaunchCommand(sceneName, cfgPath);
-        } catch (error) {
-            fs.closeSync(logFd);
-            this.writeStderr(`[up] ${sceneName} failed: ${error.message || String(error)}`);
-            return 1;
-        }
+    clearHostSceneRuntimeState(sceneName) {
+        this.sceneStateManager.clearHostSceneRuntimeState(sceneName);
+    }
 
-        const starter = this.spawnHostProcess(launchCommand.command, launchCommand.args, logFd);
-        fs.closeSync(logFd);
-        if (typeof starter.unref === 'function') {
-            starter.unref();
-        }
+    async getHostSceneRuntimeInfo(sceneName) {
+        return await this.hostRuntimeManager.getHostSceneRuntimeInfo(sceneName);
+    }
 
-        if (await this.waitForPort(port)) {
-            if (isCliScene(sceneName)) {
-                const cfg = JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
-                this.writeSceneEndpoint(sceneName, {
-                    port,
-                    wsPath: String(cfg.wsPath || '')
-                });
-            }
-            managedPids = await this.waitForHostPids(sceneName, starter.pid);
-            if (managedPids.length > 0) {
-                fs.writeFileSync(pidFile, `${managedPids[0]}`, 'utf8');
-                this.writeStdout(`[up] ${sceneName} ready on 127.0.0.1:${port} (pid(s) ${managedPids.join(' ')})`);
-                this.remindCliSessionScene(sceneName);
-                return 0;
-            }
-        }
+    signalPids(pids, signal = 'SIGTERM') {
+        this.hostRuntimeManager.signalPids(pids, signal);
+    }
 
-        this.writeStderr(`[up] ${sceneName} failed to start. tail ${logFile}:`);
-        const tail = tailText(logFile, 30);
-        if (tail) {
-            this.writeStderr(tail);
-        }
+    readPidFilePid(pidFile) {
+        return this.hostRuntimeManager.readPidFilePid(pidFile);
+    }
 
-        if (starter.exitCode === null && !starter.killed) {
-            this.stopHostStarter(starter.pid);
-        }
+    writeScenePidFile(pidFile, pid) {
+        this.hostRuntimeManager.writeScenePidFile(pidFile, pid);
+    }
 
-        return 1;
+    async startHost(sceneName, options = {}) {
+        return await this.sceneDrivers.host.up(sceneName, options);
     }
 
     async stopHost(sceneName) {
-        const pidFile = this.scenePidFile(sceneName);
-        const port = this.scenePort(sceneName);
-        const managedPids = this.hostScenePids(sceneName);
-        this.removeSceneEndpoint(sceneName);
-        this.removeSceneCliAttachConfig(sceneName);
-
-        for (const pid of managedPids) {
-            try {
-                process.kill(pid, 'SIGTERM');
-            } catch {
-                // no-op
-            }
-        }
-
-        if (managedPids.length > 0) {
-            await sleep(300);
-        }
-
-        if (fs.existsSync(pidFile)) {
-            const text = fs.readFileSync(pidFile, 'utf8').trim();
-            if (/^\d+$/.test(text)) {
-                try {
-                    process.kill(Number(text), 'SIGTERM');
-                } catch {
-                    // no-op
-                }
-            }
-            fs.rmSync(pidFile, { force: true });
-        }
-
-        if (await this.portReady(port)) {
-            this.writeStderr(`[down] ${sceneName} warning: port ${port} is still in use (possibly unmanaged process)`);
-            return 1;
-        }
-
-        this.writeStdout(`[down] ${sceneName}`);
-        return 0;
+        return await this.sceneDrivers.host.down(sceneName);
     }
 
     async statusHost(sceneName) {
-        const pidFile = this.scenePidFile(sceneName);
-        const port = this.scenePort(sceneName);
-        const managedPids = this.hostScenePids(sceneName);
-
-        if (managedPids.length > 0 && (await this.portReady(port))) {
-            this.writeStdout(`[status] ${sceneName} running (pid(s) ${managedPids.join(' ')})`);
-            const pidfileValid = fs.existsSync(pidFile) && /^\d+$/.test(fs.readFileSync(pidFile, 'utf8').trim());
-            if (!pidfileValid) {
-                fs.mkdirSync(path.dirname(pidFile), { recursive: true });
-                fs.writeFileSync(pidFile, `${managedPids[0]}`, 'utf8');
-            }
-            return 0;
-        }
-
-        if (managedPids.length > 0 && !(await this.portReady(port))) {
-            this.writeStdout(`[status] ${sceneName} degraded (pid(s) ${managedPids.join(' ')}, port ${port} not reachable)`);
-            return 0;
-        }
-
-        fs.rmSync(pidFile, { force: true });
-        if (await this.portReady(port)) {
-            this.writeStdout(`[status] ${sceneName} conflict (port ${port} in use by unmanaged process)`);
-        } else {
-            this.writeStdout(`[status] ${sceneName} stopped`);
-        }
-        return 0;
+        return await this.sceneDrivers.host.status(sceneName);
     }
 
     async healthScene(sceneName) {
@@ -1398,259 +726,61 @@ class PlaywrightPlugin {
     }
 
     logsHost(sceneName) {
-        const logFile = this.sceneLogFile(sceneName);
-        if (!fs.existsSync(logFile)) {
-            this.writeStdout(`[logs] ${sceneName} no log file: ${logFile}`);
-            return 0;
-        }
-
-        const tail = tailText(logFile, 80);
-        if (tail) {
-            this.writeStdout(tail);
-        }
-        return 0;
-    }
-
-    async downloadFile(url, output, retries = 3, timeoutMs = 60_000) {
-        const timeoutSec = Math.max(1, Math.ceil(timeoutMs / 1000));
-        if (!this.ensureCommandAvailable('curl')) {
-            throw new Error('curl command not found');
-        }
-
-        let lastError = null;
-        for (let i = 1; i <= retries; i += 1) {
-            try {
-                const result = this.runCmd([
-                    'curl',
-                    '--fail',
-                    '--location',
-                    '--silent',
-                    '--show-error',
-                    '--connect-timeout',
-                    String(timeoutSec),
-                    '--max-time',
-                    String(timeoutSec),
-                    '--output',
-                    output,
-                    url
-                ], { captureOutput: true, check: false });
-                if (result.returncode !== 0) {
-                    throw new Error(result.stderr || `curl failed with exit code ${result.returncode}`);
-                }
-                return;
-            } catch (error) {
-                lastError = error;
-                if (i < retries) {
-                    // eslint-disable-next-line no-await-in-loop
-                    await sleep(1000);
-                }
-            }
-        }
-
-        throw new Error(`download failed after ${retries} attempts: ${url}; ${String(lastError)}`);
-    }
-
-    extractZipBuffer(zipBuffer, outDir) {
-        fs.mkdirSync(outDir, { recursive: true });
-        const tempZip = path.join(os.tmpdir(), `manyoyo-playwright-ext-${process.pid}-${Date.now()}.zip`);
-        fs.writeFileSync(tempZip, zipBuffer);
-
-        const result = spawnSync('unzip', ['-oq', tempZip, '-d', outDir], { encoding: 'utf8' });
-        fs.rmSync(tempZip, { force: true });
-
-        if (result.error) {
-            throw result.error;
-        }
-        if (result.status !== 0) {
-            throw new Error(result.stderr || `unzip failed with exit code ${result.status}`);
-        }
-    }
-
-    extractCrx(crxFile, outDir) {
-        const data = fs.readFileSync(crxFile);
-        const offset = crxZipOffset(data);
-        const zipBuffer = data.subarray(offset);
-
-        this.extractZipBuffer(zipBuffer, outDir);
-
-        const manifest = path.join(outDir, 'manifest.json');
-        if (!fs.existsSync(manifest)) {
-            throw new Error(`${crxFile} extracted but manifest.json missing`);
-        }
-
-        if (convertManifestV2ToV3(outDir)) {
-            this.writeStdout(`[manifest] upgraded to MV3: ${path.basename(outDir)}`);
-        }
+        return this.sceneDrivers.host.logs(sceneName);
     }
 
     async downloadExtensions(options = {}) {
-        if (!this.ensureCommandAvailable('unzip')) {
-            this.writeStderr('[ext-download] failed: unzip command not found.');
-            return 1;
-        }
-
-        const prodversion = String(options.prodversion || this.config.extensionProdversion || '132.0.0.0').trim();
-        const extDir = path.resolve(this.extensionDirPath());
-        const tmpDir = path.resolve(this.extensionTmpDirPath());
-
-        fs.rmSync(tmpDir, { recursive: true, force: true });
-        fs.mkdirSync(extDir, { recursive: true });
-        fs.mkdirSync(tmpDir, { recursive: true });
-
-        try {
-            this.writeStdout(`[info] ext dir: ${extDir}`);
-            this.writeStdout(`[info] tmp dir: ${tmpDir}`);
-
-            for (const [name, extId] of EXTENSIONS) {
-                const url = buildCrxUrl(extId, prodversion);
-                const crxFile = path.join(tmpDir, `${name}.crx`);
-                const outDir = path.join(extDir, name);
-
-                this.writeStdout(`[download] ${name}`);
-                // eslint-disable-next-line no-await-in-loop
-                await this.downloadFile(url, crxFile);
-
-                this.writeStdout(`[extract] ${name}`);
-                fs.rmSync(outDir, { recursive: true, force: true });
-                this.extractCrx(crxFile, outDir);
-            }
-        } finally {
-            fs.rmSync(tmpDir, { recursive: true, force: true });
-            this.writeStdout(`[cleanup] removed ${tmpDir}`);
-        }
-
-        this.writeStdout(`[done] all extensions are ready: ${extDir}`);
-        return 0;
+        return await this.extensionManager.downloadExtensions(options);
     }
 
     detectCurrentIPv4() {
-        const interfaces = os.networkInterfaces();
-        for (const values of Object.values(interfaces)) {
-            if (!Array.isArray(values)) {
-                continue;
-            }
-            for (const item of values) {
-                if (!item || item.internal) {
-                    continue;
-                }
-                if (item.family === 'IPv4') {
-                    return item.address;
-                }
-            }
-        }
-        return '';
+        return this.commandOutputManager.detectCurrentIPv4();
     }
 
     resolveMcpAddHost(hostArg) {
-        if (!hostArg) {
-            return this.config.mcpDefaultHost;
-        }
-        const value = String(hostArg).trim();
-        if (!value) {
-            return '';
-        }
-        if (value === 'current-ip') {
-            return this.detectCurrentIPv4();
-        }
-        return value;
+        return this.commandOutputManager.resolveMcpAddHost(hostArg);
     }
 
     printMcpAdd(hostArg) {
-        const host = this.resolveMcpAddHost(hostArg);
-        if (!host) {
-            this.writeStderr('[mcp-add] failed: cannot determine host. Use --host <host> to set one explicitly.');
-            return 1;
-        }
-
-        const scenes = this.resolveTargets('all').filter(sceneName => isMcpScene(sceneName));
-        for (const sceneName of scenes) {
-            const url = `http://${host}:${this.scenePort(sceneName)}/mcp`;
-            this.writeStdout(`claude mcp add -t http -s user playwright-${sceneName} ${url}`);
-        }
-        this.writeStdout('');
-        for (const sceneName of scenes) {
-            const url = `http://${host}:${this.scenePort(sceneName)}/mcp`;
-            this.writeStdout(`codex mcp add playwright-${sceneName} --url ${url}`);
-        }
-        this.writeStdout('');
-        for (const sceneName of scenes) {
-            const url = `http://${host}:${this.scenePort(sceneName)}/mcp`;
-            this.writeStdout(`gemini mcp add -t http -s user playwright-${sceneName} ${url}`);
-        }
-
-        return 0;
+        return this.commandOutputManager.printMcpAdd(hostArg);
     }
 
     printCliAdd() {
-        const lines = [
-            'PLAYWRIGHT_CLI_INSTALL_DIR="${TMPDIR:-/tmp}/manyoyo-playwright-cli-install-$$"',
-            'mkdir -p "$PLAYWRIGHT_CLI_INSTALL_DIR/.playwright"',
-            'echo \'{"browser":{"browserName":"chromium","launchOptions":{"channel":"chromium"}}}\' > "$PLAYWRIGHT_CLI_INSTALL_DIR/.playwright/cli.config.json"',
-            'cd "$PLAYWRIGHT_CLI_INSTALL_DIR"',
-            `npm install -g @playwright/cli@${PLAYWRIGHT_CLI_VERSION}`,
-            'playwright-cli install --skills',
-            'PLAYWRIGHT_CLI_SKILL_SOURCE="$PLAYWRIGHT_CLI_INSTALL_DIR/.claude/skills/playwright-cli"',
-            'for target in ~/.claude/skills/playwright-cli ~/.codex/skills/playwright-cli ~/.gemini/skills/playwright-cli; do',
-            '    mkdir -p "$target"',
-            '    cp -R "$PLAYWRIGHT_CLI_SKILL_SOURCE/." "$target/"',
-            'done',
-            'cd "$OLDPWD"',
-            'rm -rf "$PLAYWRIGHT_CLI_INSTALL_DIR"'
-        ];
-        this.writeStdout(lines.join('\n'));
-        return 0;
+        return this.commandOutputManager.printCliAdd();
     }
 
     printSummary() {
-        const scenes = this.resolveTargets('all');
-        this.writeStdout(`playwright\truntime=${this.config.runtime}\tscenes=${scenes.join(',')}`);
-        return 0;
+        return this.commandOutputManager.printSummary();
     }
 
     async runOnScene(action, sceneName, options = {}) {
         const def = SCENE_DEFS[sceneName];
-        if (action === 'up') {
-            return def.type === 'container'
-                ? await this.startContainer(sceneName, options)
-                : await this.startHost(sceneName, options);
-        }
-        if (action === 'down') {
-            return def.type === 'container'
-                ? this.stopContainer(sceneName)
-                : await this.stopHost(sceneName);
-        }
-        if (action === 'status') {
-            return def.type === 'container'
-                ? this.statusContainer(sceneName)
-                : await this.statusHost(sceneName);
-        }
-        if (action === 'health') {
-            return await this.healthScene(sceneName);
-        }
-        if (action === 'logs') {
-            return def.type === 'container'
-                ? this.logsContainer(sceneName)
-                : this.logsHost(sceneName);
+        const handler = action === 'health'
+            ? () => this.healthScene(sceneName)
+            : this.sceneDrivers[def.type] && this.sceneDrivers[def.type][action];
+        if (!handler) {
+            this.writeStderr(`unknown action: ${action}`);
+            return 1;
         }
-        this.writeStderr(`unknown action: ${action}`);
-        return 1;
+        return await handler(sceneName, options);
     }
 
-    async run({ action, scene = 'mcp-host-headless', host = '', extensionPaths = [], extensionNames = [], prodversion = '' }) {
-        if (action === 'ls') {
-            return this.printSummary();
-        }
-
-        if (action === 'mcp-add') {
-            return this.printMcpAdd(host);
-        }
-
-        if (action === 'cli-add') {
-            return this.printCliAdd();
+    async runOnTargets(action, targets, options = {}) {
+        let rc = 0;
+        for (const sceneName of targets) {
+            // eslint-disable-next-line no-await-in-loop
+            const code = await this.runOnScene(action, sceneName, options);
+            if (code !== 0) {
+                rc = 1;
+            }
         }
+        return rc;
+    }
 
-        if (action === 'ext-download') {
-            return await this.downloadExtensions({ prodversion });
+    async run({ action, scene = 'mcp-host-headless', host = '', extensionPaths = [], extensionNames = [], prodversion = '' }) {
+        const directHandler = DIRECT_ACTION_HANDLERS[action];
+        if (directHandler) {
+            return await directHandler(this, { host, prodversion });
         }
 
         if (!VALID_ACTIONS.has(action)) {
@@ -1666,17 +796,7 @@ class PlaywrightPlugin {
         const resolvedExtensionPaths = action === 'up'
             ? this.resolveExtensionInputs({ extensionPaths, extensionNames })
             : [];
-
-        let rc = 0;
-        for (const sceneName of targets) {
-            // eslint-disable-next-line no-await-in-loop
-            const code = await this.runOnScene(action, sceneName, { extensionPaths: resolvedExtensionPaths });
-            if (code !== 0) {
-                rc = 1;
-            }
-        }
-
-        return rc;
+        return await this.runOnTargets(action, targets, { extensionPaths: resolvedExtensionPaths });
     }
 }