webflow-mcp 0.3.0

package/dist/src/runner/browser-session.d.ts

@@ -0,0 +1,23 @@
+import { type BrowserContext, type Page } from 'playwright-core';
+export interface BrowserSessionOptions {
+    userDataDir: string;
+    headless?: boolean;
+    startUrl?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    } | null;
+    channel?: string;
+    stealth?: boolean;
+}
+export interface BrowserSession {
+    context: BrowserContext;
+    page: Page;
+    close(): Promise<void>;
+}
+export declare function launchBrowserSession(options: BrowserSessionOptions): Promise<BrowserSession>;
+export declare function captureDomSnapshot(page: Page | undefined): Promise<{
+    html?: string;
+    text?: string;
+    url?: string;
+} | undefined>;

package/dist/src/runner/browser-session.js

@@ -0,0 +1,58 @@
+import { chromium } from 'playwright-core';
+export async function launchBrowserSession(options) {
+    const stealth = options.stealth ?? true;
+    const headless = options.headless ?? true;
+    const args = [
+        '--hide-crash-restore-bubble',
+        '--disable-features=BubbleSessionRestore'
+    ];
+    if (!headless) {
+        args.push('--start-maximized');
+    }
+    const viewport = options.viewport ?? (headless ? { width: 1280, height: 800 } : null);
+    const context = await chromium.launchPersistentContext(options.userDataDir, {
+        channel: options.channel ?? 'chrome',
+        headless,
+        viewport,
+        args,
+        slowMo: headless ? undefined : 800,
+        ignoreDefaultArgs: stealth ? ['--enable-automation', '--no-sandbox'] : ['--no-sandbox']
+    });
+    if (stealth) {
+        await context.addInitScript(() => {
+            Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+        });
+    }
+    const existingPages = context.pages();
+    const page = existingPages[0] ?? (await context.newPage());
+    if (options.startUrl) {
+        await page.goto(options.startUrl, { waitUntil: 'domcontentloaded' });
+    }
+    return {
+        context,
+        page,
+        async close() {
+            try {
+                await context.close();
+            }
+            catch {
+                // best-effort close — context may already be gone
+            }
+        }
+    };
+}
+export async function captureDomSnapshot(page) {
+    if (!page)
+        return undefined;
+    try {
+        const [html, text, url] = await Promise.all([
+            page.content().catch(() => undefined),
+            page.evaluate(() => document.body?.innerText ?? '').catch(() => undefined),
+            Promise.resolve(page.url()).catch(() => undefined)
+        ]);
+        return { html, text, url };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/runner/cdp-session.d.ts

@@ -0,0 +1,25 @@
+import { type Browser, type BrowserContext, type Page } from 'playwright-core';
+export interface CdpSessionOptions {
+    /** Dedicated user-data-dir to launch Chrome against (the global "AI Chrome" profile). */
+    userDataDir: string;
+    startUrl?: string;
+    /** Attach to an already-running Chrome instead of launching one. */
+    cdpUrl?: string;
+    chromePath?: string;
+    /** Override the remote-debugging port; a free port is chosen when omitted. */
+    port?: number;
+}
+export interface CdpSession {
+    browser: Browser;
+    context: BrowserContext;
+    page: Page;
+    cdpUrl: string;
+    /** Detach from Chrome WITHOUT closing the user's browser window. */
+    close(): Promise<void>;
+}
+/**
+ * Connect Playwright to a real Chrome over CDP, launching it against a dedicated
+ * profile dir when needed. Returns a page ready for automation. Closing the session
+ * only disconnects Playwright; it never closes the user's Chrome window.
+ */
+export declare function connectCdpSession(options: CdpSessionOptions): Promise<CdpSession>;

package/dist/src/runner/cdp-session.js

@@ -0,0 +1,156 @@
+import { createServer } from 'node:net';
+import { spawn } from 'node:child_process';
+import { get as httpGet } from 'node:http';
+import { chromium } from 'playwright-core';
+import { resolveChromeExecutable } from './chrome.js';
+function isCdpOpen(cdpUrl) {
+    return new Promise((resolve) => {
+        const req = httpGet(`${cdpUrl.replace(/\/$/, '')}/json/version`, (res) => {
+            resolve(res.statusCode === 200);
+            res.resume();
+        });
+        req.on('error', () => resolve(false));
+        req.setTimeout(800, () => {
+            req.destroy();
+            resolve(false);
+        });
+    });
+}
+async function waitForCdp(cdpUrl, maxWaitMs = 25000) {
+    const start = Date.now();
+    while (Date.now() - start < maxWaitMs) {
+        if (await isCdpOpen(cdpUrl))
+            return true;
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    return false;
+}
+function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.on('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const address = srv.address();
+            const port = typeof address === 'object' && address ? address.port : 0;
+            srv.close(() => resolve(port));
+        });
+    });
+}
+/** Terminate only the specific Chrome process the runner launched (by pid, never by image). */
+function killProcessTree(pid) {
+    return new Promise((resolve) => {
+        if (process.platform === 'win32') {
+            const killer = spawn('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
+            killer.on('exit', () => resolve());
+            killer.on('error', () => resolve());
+            return;
+        }
+        try {
+            process.kill(-pid, 'SIGTERM');
+        }
+        catch {
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch {
+                // process already gone
+            }
+        }
+        resolve();
+    });
+}
+async function ensureChromeCdp(options) {
+    if (options.cdpUrl) {
+        if (await isCdpOpen(options.cdpUrl))
+            return { cdpUrl: options.cdpUrl, launched: false };
+        throw new Error(`No Chrome with remote debugging was found at ${options.cdpUrl}.`);
+    }
+    const port = options.port ?? (await findFreePort());
+    const cdpUrl = `http://127.0.0.1:${port}`;
+    if (await isCdpOpen(cdpUrl))
+        return { cdpUrl, launched: false };
+    // Launch real Chrome against the dedicated profile dir. No automation flags and a
+    // dedicated user-data-dir, so it does not fight the user's everyday Chrome and is
+    // accepted by strict providers.
+    const args = [
+        `--remote-debugging-port=${port}`,
+        '--remote-allow-origins=*',
+        `--user-data-dir=${options.userDataDir}`,
+        '--no-first-run',
+        '--no-default-browser-check'
+    ];
+    if (options.startUrl)
+        args.push(options.startUrl);
+    const child = spawn(resolveChromeExecutable(options.chromePath), args, { detached: true, stdio: 'ignore' });
+    child.unref();
+    if (!(await waitForCdp(cdpUrl))) {
+        throw new Error(`Chrome did not expose remote debugging at ${cdpUrl}. ` +
+            'If a Chrome using this profile is already open without debugging, close it and run again.');
+    }
+    return { cdpUrl, child, launched: true };
+}
+function pickPage(contexts, startUrl) {
+    if (contexts.length === 0) {
+        throw new Error('No Chrome contexts found over CDP. Open Chrome with your signed-in profile and try again.');
+    }
+    if (startUrl) {
+        for (const context of contexts) {
+            const match = context.pages().find((page) => page.url().startsWith(startUrl));
+            if (match)
+                return { context, page: match };
+        }
+        const origin = (() => {
+            try {
+                return new URL(startUrl).origin;
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        if (origin) {
+            for (const context of contexts) {
+                const match = context.pages().find((page) => page.url().startsWith(origin));
+                if (match)
+                    return { context, page: match };
+            }
+        }
+    }
+    return { context: contexts[0], page: contexts[0].pages()[0] };
+}
+/**
+ * Connect Playwright to a real Chrome over CDP, launching it against a dedicated
+ * profile dir when needed. Returns a page ready for automation. Closing the session
+ * only disconnects Playwright; it never closes the user's Chrome window.
+ */
+export async function connectCdpSession(options) {
+    const { cdpUrl, child, launched } = await ensureChromeCdp(options);
+    const browser = await chromium.connectOverCDP(cdpUrl);
+    // Close the browser window ONLY if the runner launched it. When attaching to a
+    // Chrome the user already had open (via cdpUrl), we just disconnect and leave it.
+    const shutdown = async () => {
+        try {
+            await browser.close();
+        }
+        catch {
+            // connectOverCDP's close() only detaches; ignore disconnect errors
+        }
+        if (launched && child?.pid) {
+            await killProcessTree(child.pid);
+        }
+    };
+    try {
+        const { context, page: existing } = pickPage(browser.contexts(), options.startUrl);
+        let page = existing;
+        if (!page) {
+            page = await context.newPage();
+        }
+        if (options.startUrl && !page.url().startsWith(options.startUrl)) {
+            await page.goto(options.startUrl, { waitUntil: 'domcontentloaded' });
+        }
+        return { browser, context, page, cdpUrl, close: shutdown };
+    }
+    catch (error) {
+        await shutdown();
+        throw error;
+    }
+}

package/dist/src/runner/chrome.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Locate a real Google Chrome executable. The user can always override with an
+ * explicit path. We intentionally prefer real Chrome over bundled Chromium because
+ * strict providers (Google, Adobe) reject automation-flavored browsers at login time.
+ */
+export declare function resolveChromeExecutable(inputPath?: string): string;
+export interface LoginLaunchOptions {
+    userDataDir: string;
+    startUrl?: string;
+    executablePath?: string;
+}
+/**
+ * Launch a plain, real Chrome window pointed at a dedicated user-data-dir for a
+ * one-time manual login. No remote-debugging port and no automation flags, so the
+ * OAuth login step is not blocked as an "unsafe browser". The promise resolves when
+ * the user closes the window; the persisted session is then reused by automated runs.
+ */
+export declare function launchChromeForLogin(options: LoginLaunchOptions): Promise<void>;

package/dist/src/runner/chrome.js

@@ -0,0 +1,56 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+/**
+ * Locate a real Google Chrome executable. The user can always override with an
+ * explicit path. We intentionally prefer real Chrome over bundled Chromium because
+ * strict providers (Google, Adobe) reject automation-flavored browsers at login time.
+ */
+export function resolveChromeExecutable(inputPath) {
+    if (inputPath)
+        return inputPath;
+    if (process.platform === 'win32') {
+        const candidates = [
+            process.env.ProgramFiles ? join(process.env.ProgramFiles, 'Google', 'Chrome', 'Application', 'chrome.exe') : undefined,
+            process.env['ProgramFiles(x86)'] ? join(process.env['ProgramFiles(x86)'], 'Google', 'Chrome', 'Application', 'chrome.exe') : undefined,
+            process.env.LOCALAPPDATA ? join(process.env.LOCALAPPDATA, 'Google', 'Chrome', 'Application', 'chrome.exe') : undefined
+        ].filter((candidate) => Boolean(candidate));
+        const found = candidates.find((candidate) => existsSync(candidate));
+        if (found)
+            return found;
+    }
+    return process.platform === 'darwin'
+        ? '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'
+        : 'google-chrome';
+}
+/**
+ * Launch a plain, real Chrome window pointed at a dedicated user-data-dir for a
+ * one-time manual login. No remote-debugging port and no automation flags, so the
+ * OAuth login step is not blocked as an "unsafe browser". The promise resolves when
+ * the user closes the window; the persisted session is then reused by automated runs.
+ */
+export function launchChromeForLogin(options) {
+    const executable = resolveChromeExecutable(options.executablePath);
+    const args = [
+        `--user-data-dir=${options.userDataDir}`,
+        '--no-first-run',
+        '--no-default-browser-check'
+    ];
+    if (options.startUrl)
+        args.push(options.startUrl);
+    return new Promise((resolve, reject) => {
+        const child = spawn(executable, args, { detached: false, stdio: 'ignore' });
+        const startedAt = Date.now();
+        child.on('error', (error) => reject(error));
+        child.on('exit', () => {
+            // If Chrome handed off to an already-running instance it exits immediately and we
+            // cannot observe the window closing. Surface that so the caller can advise the user.
+            if (Date.now() - startedAt < 1500) {
+                reject(new Error('Chrome exited immediately, likely because another Chrome instance is already running. ' +
+                    'Close all Chrome windows and run setup again, or pass an explicit chromePath.'));
+                return;
+            }
+            resolve();
+        });
+    });
+}

package/dist/src/runner/flow-loader.d.ts

@@ -0,0 +1,11 @@
+import type { FlowDiscoveryResult, FlowModule } from './types.js';
+export declare function discoverFlows(projectRoot: string): Promise<FlowDiscoveryResult>;
+export declare function loadFlowModule(entryFile: string): Promise<FlowModule>;
+/**
+ * Loads a flow module from already-bundled JS source text instead of a file on
+ * disk (RFC 0001, Fase 3: relay-pushed flows). The code never lands anywhere
+ * persistent — it's written to a throwaway temp file only because Node's ESM loader
+ * needs a real module specifier to `import()`, then the temp directory is deleted
+ * immediately after the import resolves (the module is already in memory by then).
+ */
+export declare function loadFlowModuleFromSource(code: string, label?: string): Promise<FlowModule>;

package/dist/src/runner/flow-loader.js

@@ -0,0 +1,115 @@
+import { mkdtemp, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { statSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { tmpdir } from 'node:os';
+import { pathExists } from '../shared/fs.js';
+import { getWorkspacePaths, resolveFlowsProjectRoot, sanitizeName } from '../shared/paths.js';
+function isReservedFlowFolder(name) {
+    return name.startsWith('.') || name.startsWith('_');
+}
+export async function discoverFlows(projectRoot) {
+    // Flows come from the resolved flows root (this package by default for cross-repo use);
+    // downloads still target the caller's projectRoot via ctx.projectRoot in the runner.
+    const paths = getWorkspacePaths(resolveFlowsProjectRoot(projectRoot));
+    const diagnostics = [];
+    const flows = [];
+    if (!(await pathExists(paths.flowsDir))) {
+        return {
+            flows: [],
+            diagnostics: [`Workspace flows directory does not exist at ${paths.flowsDir}. Run webflow init in ${paths.projectRoot} or pass the correct projectRoot.`]
+        };
+    }
+    const entries = await readdir(paths.flowsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (isReservedFlowFolder(entry.name)) {
+            continue;
+        }
+        const dir = resolve(paths.flowsDir, entry.name);
+        // Windows reports directory junctions (and some symlinks) as isSymbolicLink()=true,
+        // isDirectory()=false — readdir's dirent type doesn't follow the reparse point. Resolve
+        // with statSync (which does follow it) before deciding whether this entry is a directory.
+        if (!entry.isDirectory()) {
+            if (!entry.isSymbolicLink()) {
+                continue;
+            }
+            const resolved = statSync(dir, { throwIfNoEntry: false });
+            if (!resolved?.isDirectory()) {
+                continue;
+            }
+        }
+        const entryFile = resolve(dir, 'index.ts');
+        const schemaFile = resolve(dir, 'schema.json');
+        const [entryExists, schemaExists] = await Promise.all([pathExists(entryFile), pathExists(schemaFile)]);
+        if (!entryExists || !schemaExists) {
+            diagnostics.push(`Ignored flow "${entry.name}" because it is missing ${!entryExists ? 'index.ts' : 'schema.json'}.`);
+            continue;
+        }
+        flows.push({ name: entry.name, dir, entryFile, schemaFile });
+    }
+    flows.sort((left, right) => left.name.localeCompare(right.name));
+    return { flows, diagnostics };
+}
+async function resolveModuleFromFile(outfile, label) {
+    const module = await import(`${pathToFileURL(outfile).href}?t=${Date.now()}`);
+    const candidate = (module.default ?? module);
+    const namespaceCapabilities = module.capabilities;
+    if (typeof candidate.run !== 'function') {
+        throw new Error(`Flow module ${label} must export an async run(ctx, input) function.`);
+    }
+    return {
+        run: candidate.run.bind(candidate),
+        capabilities: candidate.capabilities ?? namespaceCapabilities
+    };
+}
+// esbuild is only needed for local flow dev (`webflow create flow`/`webflow run`), never
+// for the relay-driven worker path (loadFlowModuleFromSource below, which loads
+// already-bundled source). Loaded lazily so `worker start`/`setup` never need esbuild
+// installed at all — its native postinstall script is known to fail when nested inside a
+// git-based `npm install -g` (npm bug, not ours to fix), which is exactly how the worker
+// gets distributed.
+async function loadEsbuild() {
+    try {
+        return await import('esbuild');
+    }
+    catch {
+        throw new Error('esbuild is required for local flow dev (webflow create flow / webflow run) but is not installed. Run: npm install esbuild');
+    }
+}
+export async function loadFlowModule(entryFile) {
+    await stat(entryFile);
+    const { build } = await loadEsbuild();
+    const tempDir = await mkdtemp(resolve(tmpdir(), 'webflow-flow-'));
+    const outfile = resolve(tempDir, `${basename(entryFile, '.ts')}.mjs`);
+    await build({
+        entryPoints: [entryFile],
+        outfile,
+        bundle: true,
+        format: 'esm',
+        platform: 'node',
+        target: 'node20',
+        packages: 'external'
+    });
+    return resolveModuleFromFile(outfile, entryFile);
+}
+/**
+ * Loads a flow module from already-bundled JS source text instead of a file on
+ * disk (RFC 0001, Fase 3: relay-pushed flows). The code never lands anywhere
+ * persistent — it's written to a throwaway temp file only because Node's ESM loader
+ * needs a real module specifier to `import()`, then the temp directory is deleted
+ * immediately after the import resolves (the module is already in memory by then).
+ */
+export async function loadFlowModuleFromSource(code, label = 'remote') {
+    // The label can come from a relay-supplied flow name — never trust it into a path
+    // unsanitized (RFC 0001, section 5: don't trust the relay blindly).
+    const safeLabel = sanitizeName(label);
+    const tempDir = await mkdtemp(resolve(tmpdir(), `webflow-flow-${safeLabel}-`));
+    const outfile = resolve(tempDir, 'module.mjs');
+    try {
+        await writeFile(outfile, code, 'utf8');
+        return await resolveModuleFromFile(outfile, safeLabel);
+    }
+    finally {
+        await rm(tempDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}

package/dist/src/runner/flow-runner.d.ts

@@ -0,0 +1,70 @@
+import { ProfileManager } from '../profiles/profile-manager.js';
+import type { CompiledSchema, SupportedSchema } from '../schema/types.js';
+import type { BrowserVisibility, WebflowConfig } from '../config/webflow-config.js';
+import type { BrowserCapability, BrowserMode, FlowCapabilities, FlowDefinition, FlowExecutionResult, RunnableFlow } from './types.js';
+export interface FlowRunOptions {
+    profileName?: string;
+    schema?: CompiledSchema;
+    headed?: boolean;
+    browserMode?: BrowserMode;
+    browserVisibility?: BrowserVisibility;
+}
+type ResolvedBrowserMode = 'none' | BrowserMode;
+export declare function resolveBrowserMode(params: {
+    capability: BrowserCapability | undefined;
+    supportedBrowserModes?: BrowserMode[];
+    requestedMode?: BrowserMode;
+    flowName: string;
+    config: WebflowConfig;
+}): ResolvedBrowserMode;
+/**
+ * Visibility precedence (see Project-Context/modules/browser-runner.md):
+ *   1. requiresVisibleBrowser (mandatory, e.g. strict providers) -> visible
+ *   2. --headed / worker --headed (options.headed)                -> visible
+ *   3. one-off browserVisibility option                            -> as set
+ *   4. config.browserVisibility.flows[flowName] (explicit override) -> as set
+ *   5. config.browserVisibility.default, if not 'inherit'           -> as set
+ *   6. capabilities.headless (legacy, per-flow code)                -> as set
+ *   7. fallback                                                     -> hidden
+ * `browser: 'cdp'` never reaches this function — it has no headless concept, it
+ * connects to an already-visible real Chrome by construction.
+ */
+export declare function resolveHeadless(params: {
+    requiresVisibleBrowser: boolean | undefined;
+    optionsHeaded: boolean | undefined;
+    optionsVisibility?: BrowserVisibility;
+    legacyHeadless: boolean | undefined;
+    flowName: string;
+    config: WebflowConfig;
+}): boolean;
+/**
+ * Whether to nudge the calling agent to ask the human for a standing visibility
+ * preference for this specific flow. Never fires for flows with a mandatory-visible
+ * exception (nothing to configure), and never fires again once an explicit per-flow
+ * override already exists.
+ */
+export declare function shouldNudgeVisibility(params: {
+    requiresVisibleBrowser: boolean | undefined;
+    optionsVisibility?: BrowserVisibility;
+    flowName: string;
+    config: WebflowConfig;
+}): boolean;
+export declare class FlowRunner {
+    private readonly projectRoot;
+    readonly profileManager: ProfileManager;
+    private readonly providerGate;
+    private readonly browserSlots;
+    constructor(projectRoot: string, profileManager?: ProfileManager);
+    compile(definition: FlowDefinition): Promise<RunnableFlow>;
+    run(definition: FlowDefinition, input: unknown, options?: FlowRunOptions): Promise<FlowExecutionResult>;
+    /**
+     * Executes a flow whose code was NOT loaded from this machine's disk (RFC 0001,
+     * Fase 3): the relay bundles and pushes the flow's source per job so that no
+     * automation code — free or paid — ever persists on the worker's machine. Reuses
+     * every bit of session/profile/error-handling logic that `run()` uses; the only
+     * difference is where the `FlowModule` comes from.
+     */
+    runRemote(flowName: string, code: string, schemaJson: SupportedSchema, input: unknown, options?: FlowRunOptions, expectedCapabilities?: FlowCapabilities): Promise<FlowExecutionResult>;
+    private executeModule;
+}
+export {};