webflow-mcp 0.3.0

package/dist/src/cli/commands/run.js

@@ -0,0 +1,13 @@
+import { resolve } from 'node:path';
+import { discoverFlows } from '../../runner/flow-loader.js';
+import { FlowRunner } from '../../runner/flow-runner.js';
+import { WebFlowError } from '../../shared/errors.js';
+export async function runFlow(projectRoot, flowName, input, options = {}) {
+    const { flows } = await discoverFlows(resolve(projectRoot));
+    const definition = flows.find((flow) => flow.name === flowName);
+    if (!definition) {
+        throw new WebFlowError('UNKNOWN_FLOW', `Flow "${flowName}" not found in .webflow/flows.`);
+    }
+    const runner = new FlowRunner(projectRoot);
+    return runner.run(definition, input, options);
+}

package/dist/src/cli/commands/setup.d.ts

@@ -0,0 +1,11 @@
+export interface SetupFlowOptions {
+    startUrl?: string;
+    profileName?: string;
+    /** Use a Playwright-managed headed window instead of plain real Chrome. */
+    managed?: boolean;
+    /** Explicit Chrome executable path (real-Chrome login only). */
+    chromePath?: string;
+}
+export declare function setupFlow(projectRoot: string, flowName: string, options?: SetupFlowOptions): Promise<{
+    profileDir: string;
+}>;

package/dist/src/cli/commands/setup.js

@@ -0,0 +1,46 @@
+import { resolve } from 'node:path';
+import { discoverFlows, loadFlowModule } from '../../runner/flow-loader.js';
+import { launchBrowserSession } from '../../runner/browser-session.js';
+import { launchChromeForLogin } from '../../runner/chrome.js';
+import { ProfileManager } from '../../profiles/profile-manager.js';
+import { markInteractiveSetup } from '../../profiles/profile-state.js';
+import { WebFlowError } from '../../shared/errors.js';
+export async function setupFlow(projectRoot, flowName, options = {}) {
+    const { flows } = await discoverFlows(resolve(projectRoot));
+    const definition = flows.find((flow) => flow.name === flowName);
+    if (!definition) {
+        throw new WebFlowError('UNKNOWN_FLOW', `Flow "${flowName}" not found in .webflow/flows.`);
+    }
+    const module = await loadFlowModule(definition.entryFile);
+    if (!module.capabilities?.browser) {
+        throw new WebFlowError('FLOW_NOT_BROWSER_AWARE', `Flow "${flowName}" does not declare a browser capability. Add export const capabilities = { browser: true } to its index.ts.`);
+    }
+    const profileManager = new ProfileManager(projectRoot);
+    const profile = await profileManager.ensure(options.profileName ?? module.capabilities.profile, flowName);
+    const startUrl = options.startUrl ?? module.capabilities.startUrl;
+    console.log(`\nProfile (global, shared across repos): ${profile.dir}`);
+    if (options.managed) {
+        // Playwright-managed headed window. Some providers block their OAuth login here.
+        const session = await launchBrowserSession({
+            userDataDir: profile.dir,
+            headless: false,
+            startUrl,
+            channel: module.capabilities.channel,
+            stealth: module.capabilities.stealth
+        });
+        console.log('Managed browser opened for manual setup (login, accept cookies, etc.).');
+        console.log('Close the browser window when you are done — your session will persist for this flow.\n');
+        await new Promise((done) => {
+            session.context.once('close', () => done());
+        });
+        await markInteractiveSetup(profile, flowName);
+        return { profileDir: profile.dir };
+    }
+    // Default: a plain real Chrome window with no automation flags, so strict providers
+    // (Google, Adobe) accept the login. The session persists in the dedicated profile dir.
+    console.log('Opening a real Chrome window for one-time login (no automation flags).');
+    console.log('Log in and accept any prompts, then CLOSE the Chrome window to finish.\n');
+    await launchChromeForLogin({ userDataDir: profile.dir, startUrl, executablePath: options.chromePath });
+    await markInteractiveSetup(profile, flowName);
+    return { profileDir: profile.dir };
+}

package/dist/src/cli/commands/worker.d.ts

@@ -0,0 +1,29 @@
+import { WorkerConnection } from '../../worker/connection.js';
+import type { BrowserVisibility } from '../../config/webflow-config.js';
+import type { BrowserMode } from '../../runner/types.js';
+import type { FlowTrustPolicyEntry } from '../../security/flow-release.js';
+export interface WorkerStartOptions {
+    relayUrl: string;
+    credential: string;
+    workerId: string;
+    /** Watch mode: run this worker's flows with a visible Chrome window instead of headless. */
+    headed?: boolean;
+    /** Process-local default for this worker run; does not persist to ~/.webflow/config.json. */
+    browserMode?: BrowserMode;
+    /** Process-local default for this worker run; does not persist to ~/.webflow/config.json. */
+    browserVisibility?: BrowserVisibility;
+    trustPolicy?: readonly FlowTrustPolicyEntry[];
+    onLog?: (message: string) => void;
+}
+export interface WorkerHandle {
+    connection: WorkerConnection;
+    workerId: string;
+    stop(): void;
+}
+/**
+ * Wires WorkerService (local flow execution) to WorkerConnection (outbound socket
+ * to the relay) and starts connecting. Returns a handle immediately; the connection
+ * runs in the background until `stop()` is called (RFC 0001, Fase 1). The CLI
+ * dispatcher is the only caller that blocks the process on this indefinitely.
+ */
+export declare function startWorker(projectRoot: string, options: WorkerStartOptions): WorkerHandle;

package/dist/src/cli/commands/worker.js

@@ -0,0 +1,30 @@
+import { WebFlowError } from '../../shared/errors.js';
+import { WorkerConnection } from '../../worker/connection.js';
+import { WorkerService } from '../../worker/worker-service.js';
+import { loadFlowTrustPolicy } from '../../security/trusted-flow-keys.js';
+/**
+ * Wires WorkerService (local flow execution) to WorkerConnection (outbound socket
+ * to the relay) and starts connecting. Returns a handle immediately; the connection
+ * runs in the background until `stop()` is called (RFC 0001, Fase 1). The CLI
+ * dispatcher is the only caller that blocks the process on this indefinitely.
+ */
+export function startWorker(projectRoot, options) {
+    if (!options.relayUrl) {
+        throw new WebFlowError('INVALID_COMMAND', 'webflow worker start requires --relay <wss://...>');
+    }
+    if (!options.credential) {
+        throw new WebFlowError('INVALID_COMMAND', 'webflow worker start requires saved v2 credentials. Run "webflow login" to pair this device.');
+    }
+    const workerId = options.workerId;
+    const service = new WorkerService(projectRoot, { headed: options.headed, browserMode: options.browserMode, browserVisibility: options.browserVisibility });
+    const connection = new WorkerConnection({
+        relayUrl: options.relayUrl,
+        credential: options.credential,
+        workerId,
+        service,
+        trustPolicy: options.trustPolicy ?? loadFlowTrustPolicy(options.relayUrl),
+        onLog: options.onLog
+    });
+    connection.start();
+    return { connection, workerId, stop: () => connection.stop() };
+}

package/dist/src/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runCli(argv?: string[], projectRoot?: string, nodeVersion?: string): Promise<number>;

package/dist/src/cli/index.js

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createFlow } from './commands/create-flow.js';
+import { forkFlow } from './commands/fork.js';
+import { initWorkspace } from './commands/init.js';
+import { setupFlow } from './commands/setup.js';
+import { runFlow } from './commands/run.js';
+import { formatConfig, getConfig, setConfigPreference } from './commands/config.js';
+import { formatDoctorResult, runDoctor } from './commands/doctor.js';
+import { startWorker } from './commands/worker.js';
+import { approveFlow, formatApprovalState, revokeFlow } from './commands/approvals.js';
+import { login, loginStatus, logout } from './commands/login.js';
+import { formatProfileStatus, listProfiles, loginProfile, refreshInstanceProfile, resetProfile, statusFlowProfile, statusProfile } from './commands/profiles.js';
+import { getWireCredential, loadCredentials } from '../shared/credentials.js';
+import { toErrorMessage, WebFlowError } from '../shared/errors.js';
+import { assertSupportedNode, isAuthorEnvironment } from '../shared/paths.js';
+/**
+ * `init`/`create flow`/`fork`/`doctor` are flow-AUTHORING commands (scaffolding and
+ * diagnosing flows for the catalog) — not something an end user running automations
+ * should ever see, let alone reach. They only appear in the usage text (and only
+ * dispatch at all, see runCli()) inside the maintainer's own git checkout; an
+ * installed package never has them, see isAuthorEnvironment().
+ */
+function printUsage(authorMode) {
+    const authorLines = authorMode
+        ? `  webflow init
+  webflow create flow <name>
+  webflow fork <source> <target>
+  webflow doctor [projectRoot]
+`
+        : '';
+    console.log(`Usage:
+${authorLines}  webflow config get [--json]
+  webflow config browser-mode <default|flow> ...
+  webflow config browser-visibility <default|flow> ...
+  webflow setup <flow> [--profile <name>] [--managed] [--url <url>] [--chrome-path <path>]
+  webflow profiles list [--json]
+  webflow profiles status <profile> [--json]
+  webflow profiles status --flow <flow> [--json]
+  webflow profiles login <profile> [--url <url>] [--managed] [--chrome-path <path>]
+  webflow profiles reset <profile> --yes
+  webflow profiles refresh-instance <profile> --instance <id> --yes
+  webflow run <flow> [--headed] [--browser-mode <managed|cdp>] [--browser-visibility <visible|hidden>] [--profile <name>] [--input '<json>']
+  webflow login [--app <https://app.webflowmcp.es>]
+  webflow login --status
+  webflow logout
+  webflow approvals list [--json]
+  webflow approvals approve <flow> [--trust-domain <domain>]
+  webflow approvals revoke <flow> [--trust-domain <domain>]
+  webflow worker start [--headed] [--browser-mode <managed|cdp>] [--browser-visibility <visible|hidden>]
+    (relay, stable worker identity, and credential are loaded from "webflow login")`);
+}
+function parseBrowserMode(value) {
+    if (!value)
+        return undefined;
+    if (value === 'managed' || value === 'cdp')
+        return value;
+    throw new WebFlowError('INVALID_COMMAND', '--browser-mode must be "managed" or "cdp".');
+}
+function parseBrowserVisibility(value) {
+    if (!value)
+        return undefined;
+    if (value === 'visible' || value === 'hidden')
+        return value;
+    throw new WebFlowError('INVALID_COMMAND', '--browser-visibility must be "visible" or "hidden".');
+}
+function getFlagValue(args, flag) {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+export async function runCli(argv = process.argv.slice(2), projectRoot = process.cwd(), nodeVersion = process.versions.node) {
+    assertSupportedNode(nodeVersion);
+    const [command, subcommand, ...rest] = argv;
+    const authorMode = isAuthorEnvironment(import.meta.url);
+    if (!command) {
+        printUsage(authorMode);
+        return 0;
+    }
+    switch (command) {
+        case 'init': {
+            if (!authorMode)
+                throw new WebFlowError('INVALID_COMMAND', `Unknown command: ${command}`);
+            const result = await initWorkspace(resolve(projectRoot), import.meta.url);
+            console.log(result.created ? `Initialized ${result.workspaceRoot}` : `Workspace already initialized at ${result.workspaceRoot}`);
+            return 0;
+        }
+        case 'create': {
+            if (!authorMode)
+                throw new WebFlowError('INVALID_COMMAND', `Unknown command: ${command}`);
+            if (subcommand !== 'flow' || rest.length !== 1) {
+                throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow create flow <name>');
+            }
+            const result = await createFlow(resolve(projectRoot), rest[0]);
+            console.log(`Created flow ${result.name} at ${result.dir}`);
+            return 0;
+        }
+        case 'fork': {
+            if (!authorMode)
+                throw new WebFlowError('INVALID_COMMAND', `Unknown command: ${command}`);
+            if (!subcommand || rest.length !== 1) {
+                throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow fork <source> <target>');
+            }
+            const result = await forkFlow(resolve(projectRoot), subcommand, rest[0]);
+            console.log(`Forked flow ${result.source} -> ${result.target}`);
+            return 0;
+        }
+        case 'config': {
+            if (!subcommand) {
+                throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow config <get|browser-mode|browser-visibility> ...');
+            }
+            const json = rest.includes('--json');
+            const config = subcommand === 'get'
+                ? await getConfig()
+                : await setConfigPreference(subcommand, rest[0], rest[1], rest[2]);
+            console.log(json ? JSON.stringify(config, null, 2) : formatConfig(config));
+            return 0;
+        }
+        case 'setup': {
+            if (!subcommand) {
+                throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow setup <flow> [--profile <name>]');
+            }
+            const profileName = getFlagValue(rest, '--profile');
+            const startUrl = getFlagValue(rest, '--url');
+            const chromePath = getFlagValue(rest, '--chrome-path');
+            const managed = rest.includes('--managed');
+            const result = await setupFlow(resolve(projectRoot), subcommand, { profileName, startUrl, chromePath, managed });
+            console.log(`Setup complete. Profile saved at ${result.profileDir}`);
+            return 0;
+        }
+        case 'profiles': {
+            if (!subcommand) {
+                throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow profiles <list|status|login|reset|refresh-instance>');
+            }
+            const json = rest.includes('--json');
+            const print = (value, text) => {
+                console.log(json ? JSON.stringify(value, null, 2) : text ?? JSON.stringify(value, null, 2));
+            };
+            switch (subcommand) {
+                case 'list': {
+                    const profiles = await listProfiles();
+                    print(profiles, profiles.length ? profiles.map(formatProfileStatus).join('\n\n') : 'No profiles found.');
+                    return 0;
+                }
+                case 'status': {
+                    const flowIndex = rest.indexOf('--flow');
+                    if (flowIndex >= 0) {
+                        const flowName = rest[flowIndex + 1];
+                        if (!flowName)
+                            throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow profiles status --flow <flow> [--json]');
+                        const status = await statusFlowProfile(resolve(projectRoot), flowName);
+                        print(status, formatProfileStatus(status));
+                        return status.requiresLogin && status.probablyValid === false ? 1 : 0;
+                    }
+                    const profileName = rest.find((item) => !item.startsWith('--'));
+                    if (!profileName)
+                        throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow profiles status <profile> [--json]');
+                    const status = await statusProfile(profileName);
+                    print(status, formatProfileStatus(status));
+                    return status.probablyValid === false ? 1 : 0;
+                }
+                case 'login': {
+                    const profileName = rest.find((item) => !item.startsWith('--'));
+                    if (!profileName)
+                        throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow profiles login <profile> [--url <url>] [--managed] [--chrome-path <path>]');
+                    const startUrl = getFlagValue(rest, '--url');
+                    const chromePath = getFlagValue(rest, '--chrome-path');
+                    const managed = rest.includes('--managed');
+                    if (!json)
+                        console.log(`Opening ${managed ? 'managed browser' : 'real Chrome'} for profile "${profileName}". Log in, then close the window to finish.`);
+                    const status = await loginProfile(profileName, { startUrl, chromePath, managed });
+                    print(status, formatProfileStatus(status));
+                    return 0;
+                }
+                case 'reset': {
+                    const profileName = rest.find((item) => !item.startsWith('--'));
+                    if (!profileName || !rest.includes('--yes'))
+                        throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow profiles reset <profile> --yes');
+                    const result = await resetProfile(profileName);
+                    print(result, `Removed profile ${result.profile} (${result.removed.length} director${result.removed.length === 1 ? 'y' : 'ies'}).`);
+                    return 0;
+                }
+                case 'refresh-instance': {
+                    const profileName = rest.find((item) => !item.startsWith('--'));
+                    const instanceIndex = rest.indexOf('--instance');
+                    const instance = instanceIndex >= 0 ? rest[instanceIndex + 1] : undefined;
+                    if (!profileName || !instance || !rest.includes('--yes')) {
+                        throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow profiles refresh-instance <profile> --instance <id> --yes');
+                    }
+                    const result = await refreshInstanceProfile(profileName, instance);
+                    print(result, `Refreshed ${result.profile}__${result.instance} from ${result.baseDir}.`);
+                    return 0;
+                }
+                default:
+                    throw new WebFlowError('INVALID_COMMAND', `Unknown profiles command: ${subcommand}`);
+            }
+        }
+        case 'doctor': {
+            if (!authorMode)
+                throw new WebFlowError('INVALID_COMMAND', `Unknown command: ${command}`);
+            const targetRoot = subcommand ? resolve(subcommand) : resolve(projectRoot);
+            const result = await runDoctor(targetRoot);
+            console.log(formatDoctorResult(result));
+            return result.exitCode;
+        }
+        case 'run': {
+            if (!subcommand) {
+                throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow run <flow> [--headed] [--browser-mode <managed|cdp>] [--browser-visibility <visible|hidden>] [--profile <name>] [--input \'<json>\']');
+            }
+            const headed = rest.includes('--headed');
+            const inputJson = getFlagValue(rest, '--input');
+            const input = inputJson ? JSON.parse(inputJson) : {};
+            const profileName = getFlagValue(rest, '--profile');
+            const browserMode = parseBrowserMode(getFlagValue(rest, '--browser-mode'));
+            const browserVisibility = parseBrowserVisibility(getFlagValue(rest, '--browser-visibility'));
+            const result = await runFlow(resolve(projectRoot), subcommand, input, { headed, profileName, browserMode, browserVisibility });
+            console.log(JSON.stringify(result, null, 2));
+            return result.ok ? 0 : 1;
+        }
+        case 'login': {
+            const loginRest = [subcommand, ...rest].filter((value) => value !== undefined);
+            if (loginRest.includes('--status')) {
+                const status = await loginStatus();
+                console.log(status.loggedIn
+                    ? `Paired worker "${status.workerId}" with ${status.appUrl} (relay ${status.relayUrl}).`
+                    : 'Not paired. Run: webflow login');
+                return 0;
+            }
+            if (loginRest.includes('--token') || loginRest.includes('--token-file')) {
+                throw new WebFlowError('INVALID_COMMAND', 'webflow login no longer accepts tokens. Run "webflow login" and approve the device pairing in your browser.');
+            }
+            const appUrl = getFlagValue(loginRest, '--app');
+            if (loginRest.includes('--app') && !appUrl) {
+                throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow login [--app <https://app.webflowmcp.es>]');
+            }
+            const result = await login(appUrl, {
+                onVerification: (url, opened) => {
+                    console.log(opened ? `Complete pairing in your browser: ${url}` : `Could not open a browser. Open this URL to complete pairing: ${url}`);
+                }
+            });
+            console.log(`Paired worker "${result.workerId}" with ${result.appUrl}. "webflow worker start" will use this credential automatically.`);
+            return 0;
+        }
+        case 'logout': {
+            const cleared = await logout();
+            console.log(cleared ? 'Logged out — removed the saved relay login.' : 'Nothing to log out of — no saved login found.');
+            return 0;
+        }
+        case 'approvals': {
+            if (subcommand === 'list') {
+                if (rest.some((argument) => argument !== '--json') || rest.filter((argument) => argument === '--json').length > 1) {
+                    throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow approvals list [--json]');
+                }
+                console.log(await formatApprovalState(rest.includes('--json')));
+                return 0;
+            }
+            if (subcommand !== 'approve' && subcommand !== 'revoke') {
+                throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow approvals <list|approve|revoke> [flow] [--trust-domain <domain>]');
+            }
+            const trustDomainIndex = rest.indexOf('--trust-domain');
+            const trustDomain = trustDomainIndex >= 0 ? rest[trustDomainIndex + 1] : undefined;
+            if (trustDomainIndex >= 0 && (!trustDomain || trustDomain.startsWith('--'))) {
+                throw new WebFlowError('INVALID_COMMAND', `Usage: webflow approvals ${subcommand} <flow> [--trust-domain <domain>]`);
+            }
+            const positional = rest.filter((_, index) => trustDomainIndex < 0 || (index !== trustDomainIndex && index !== trustDomainIndex + 1));
+            if (positional.length !== 1 || positional[0].startsWith('--') || rest.filter((argument) => argument === '--trust-domain').length > 1) {
+                throw new WebFlowError('INVALID_COMMAND', `Usage: webflow approvals ${subcommand} <flow> [--trust-domain <domain>]`);
+            }
+            const flowName = positional[0];
+            console.log(subcommand === 'approve' ? await approveFlow(flowName, trustDomain) : await revokeFlow(flowName, trustDomain));
+            return 0;
+        }
+        case 'worker': {
+            if (subcommand !== 'start') {
+                throw new WebFlowError('INVALID_COMMAND', 'Usage: webflow worker start [--headed] [--browser-mode <managed|cdp>] [--browser-visibility <visible|hidden>]');
+            }
+            if (rest.includes('--token') || rest.includes('--token-file') || rest.includes('--relay') || rest.includes('--worker-id')) {
+                throw new WebFlowError('INVALID_COMMAND', 'Worker connection and identity overrides are no longer supported. Run "webflow login" to pair this device.');
+            }
+            const credentials = await loadCredentials();
+            const headed = rest.includes('--headed');
+            const browserMode = parseBrowserMode(getFlagValue(rest, '--browser-mode'));
+            const browserVisibility = parseBrowserVisibility(getFlagValue(rest, '--browser-visibility'));
+            if (!credentials) {
+                throw new WebFlowError('INVALID_COMMAND', 'No saved v2 worker credential found. Run "webflow login" to pair this device first.');
+            }
+            const handle = startWorker(resolve(projectRoot), {
+                relayUrl: credentials.relayUrl,
+                credential: getWireCredential(credentials),
+                workerId: credentials.workerId,
+                headed,
+                browserMode,
+                browserVisibility,
+                onLog: (message) => console.error(`[worker] ${message}`)
+            });
+            console.log(`Worker "${handle.workerId}" connecting to ${credentials.relayUrl} (${headed ? 'headed — you will see Chrome' : 'headless — Chrome runs hidden'}). Press Ctrl+C to stop.`);
+            const shutdown = () => {
+                handle.stop();
+                process.exit(0);
+            };
+            process.on('SIGINT', shutdown);
+            process.on('SIGTERM', shutdown);
+            // This command is a long-running daemon by design, unlike every other CLI
+            // command here: it stays connected until the process is killed.
+            await new Promise(() => { });
+            return 0;
+        }
+        default:
+            throw new WebFlowError('INVALID_COMMAND', `Unknown command: ${command}`);
+    }
+}
+// `npm install -g` invokes this file through a symlink on macOS/Linux (bin/webflow ->
+// .../dist/src/cli/index.js) or a generated shim on Windows. import.meta.url is always the
+// resolved real path; process.argv[1] isn't (symlink case) or uses backslashes (Windows case).
+// Building the file:// URL by hand breaks on Windows (drive-letter paths need
+// file:///C:/... — three slashes — not file://C:/...); pathToFileURL handles both platforms
+// correctly. Without this, the guard below silently never fires for any real end user (exits
+// 0, prints nothing).
+const invokedRealFileUrl = (() => {
+    try {
+        return process.argv[1] ? pathToFileURL(realpathSync(process.argv[1])).href : undefined;
+    }
+    catch {
+        return undefined;
+    }
+})();
+if (invokedRealFileUrl && import.meta.url === invokedRealFileUrl) {
+    runCli().then((code) => {
+        process.exitCode = code;
+    }, (error) => {
+        const message = error instanceof WebFlowError ? `[${error.code}] ${error.message}` : toErrorMessage(error);
+        console.error(message);
+        process.exitCode = 1;
+    });
+}

package/dist/src/config/webflow-config.d.ts

@@ -0,0 +1,35 @@
+import type { BrowserMode } from '../runner/types.js';
+export type BrowserVisibility = 'visible' | 'hidden';
+/** 'inherit' means the user has never set a global default — capabilities.headless
+ * (per-flow, legacy) still decides in that case. Never inferred, only set explicitly
+ * via setDefaultBrowserVisibility(). */
+export type GlobalVisibilityPreference = BrowserVisibility | 'inherit';
+/** Same persistence model as browser visibility: 'inherit' means no global mode preference. */
+export type GlobalBrowserModePreference = BrowserMode | 'inherit';
+export interface WebflowConfig {
+    browserVisibility: {
+        default: GlobalVisibilityPreference;
+        /** Explicit per-flow overrides. Absence of a key means "no override" — falls
+         * through to the global default, never treated as 'inherit' itself. */
+        flows: Record<string, BrowserVisibility>;
+    };
+    browserMode: {
+        default: GlobalBrowserModePreference;
+        /** Explicit per-flow browser-mode overrides. Absence means fall through to the global default. */
+        flows: Record<string, BrowserMode>;
+    };
+}
+export declare function loadConfig(): Promise<WebflowConfig>;
+export declare function saveConfig(config: WebflowConfig): Promise<void>;
+export declare function setDefaultBrowserVisibility(value: GlobalVisibilityPreference): Promise<WebflowConfig>;
+/** value:null clears the per-flow override, falling back to the global default. */
+export declare function setFlowBrowserVisibility(flowName: string, value: BrowserVisibility | null): Promise<WebflowConfig>;
+export declare function setDefaultBrowserMode(value: GlobalBrowserModePreference): Promise<WebflowConfig>;
+/** value:null clears the per-flow override, falling back to the global default. */
+export declare function setFlowBrowserMode(flowName: string, value: BrowserMode | null): Promise<WebflowConfig>;
+/** Pure resolution, no I/O — flow-runner.ts calls this against an already-loaded config.
+ * Returns 'inherit' when neither a per-flow override nor a global default apply, leaving
+ * the legacy capabilities.headless field free to decide. */
+export declare function resolveBrowserVisibility(config: WebflowConfig, flowName: string): GlobalVisibilityPreference;
+/** Pure resolution for browser mode preference. 'inherit' means the flow's own default mode decides. */
+export declare function resolveBrowserModePreference(config: WebflowConfig, flowName: string): GlobalBrowserModePreference;

package/dist/src/config/webflow-config.js

@@ -0,0 +1,119 @@
+import { dirname } from 'node:path';
+import { getConfigPath } from '../shared/paths.js';
+import { ensureDir, readJsonFile, writeJsonFile } from '../shared/fs.js';
+function defaultConfig() {
+    return { browserVisibility: { default: 'inherit', flows: {} }, browserMode: { default: 'inherit', flows: {} } };
+}
+function isBrowserVisibility(value) {
+    return value === 'visible' || value === 'hidden';
+}
+function isBrowserMode(value) {
+    return value === 'managed' || value === 'cdp';
+}
+/** Never trusts a config.json blindly — a corrupt or hand-edited file falls back to
+ * defaults instead of crashing the worker. */
+function sanitizeConfig(raw) {
+    const fallback = defaultConfig();
+    if (typeof raw !== 'object' || raw === null)
+        return fallback;
+    const record = raw;
+    const browserVisibility = record.browserVisibility;
+    let browserVisibilityConfig = fallback.browserVisibility;
+    if (typeof browserVisibility === 'object' && browserVisibility !== null) {
+        const rawDefault = browserVisibility.default;
+        const globalDefault = rawDefault === 'inherit' || isBrowserVisibility(rawDefault) ? rawDefault : 'inherit';
+        const rawFlows = browserVisibility.flows;
+        const flows = {};
+        if (typeof rawFlows === 'object' && rawFlows !== null) {
+            for (const [name, value] of Object.entries(rawFlows)) {
+                if (isBrowserVisibility(value)) {
+                    flows[name] = value;
+                }
+            }
+        }
+        browserVisibilityConfig = { default: globalDefault, flows };
+    }
+    const browserMode = record.browserMode;
+    let browserModeConfig = fallback.browserMode;
+    if (typeof browserMode === 'object' && browserMode !== null) {
+        const rawDefault = browserMode.default;
+        const globalDefault = rawDefault === 'inherit' || isBrowserMode(rawDefault) ? rawDefault : 'inherit';
+        const rawFlows = browserMode.flows;
+        const flows = {};
+        if (typeof rawFlows === 'object' && rawFlows !== null) {
+            for (const [name, value] of Object.entries(rawFlows)) {
+                if (isBrowserMode(value)) {
+                    flows[name] = value;
+                }
+            }
+        }
+        browserModeConfig = { default: globalDefault, flows };
+    }
+    return { browserVisibility: browserVisibilityConfig, browserMode: browserModeConfig };
+}
+export async function loadConfig() {
+    try {
+        const raw = await readJsonFile(getConfigPath());
+        return sanitizeConfig(raw);
+    }
+    catch {
+        return defaultConfig();
+    }
+}
+export async function saveConfig(config) {
+    const path = getConfigPath();
+    await ensureDir(dirname(path));
+    await writeJsonFile(path, config);
+}
+export async function setDefaultBrowserVisibility(value) {
+    const config = await loadConfig();
+    config.browserVisibility.default = value;
+    await saveConfig(config);
+    return config;
+}
+/** value:null clears the per-flow override, falling back to the global default. */
+export async function setFlowBrowserVisibility(flowName, value) {
+    const config = await loadConfig();
+    if (value === null) {
+        delete config.browserVisibility.flows[flowName];
+    }
+    else {
+        config.browserVisibility.flows[flowName] = value;
+    }
+    await saveConfig(config);
+    return config;
+}
+export async function setDefaultBrowserMode(value) {
+    const config = await loadConfig();
+    config.browserMode.default = value;
+    await saveConfig(config);
+    return config;
+}
+/** value:null clears the per-flow override, falling back to the global default. */
+export async function setFlowBrowserMode(flowName, value) {
+    const config = await loadConfig();
+    if (value === null) {
+        delete config.browserMode.flows[flowName];
+    }
+    else {
+        config.browserMode.flows[flowName] = value;
+    }
+    await saveConfig(config);
+    return config;
+}
+/** Pure resolution, no I/O — flow-runner.ts calls this against an already-loaded config.
+ * Returns 'inherit' when neither a per-flow override nor a global default apply, leaving
+ * the legacy capabilities.headless field free to decide. */
+export function resolveBrowserVisibility(config, flowName) {
+    const override = config.browserVisibility.flows[flowName];
+    if (override)
+        return override;
+    return config.browserVisibility.default;
+}
+/** Pure resolution for browser mode preference. 'inherit' means the flow's own default mode decides. */
+export function resolveBrowserModePreference(config, flowName) {
+    const override = config.browserMode.flows[flowName];
+    if (override)
+        return override;
+    return config.browserMode.default;
+}