webflow-mcp 0.3.0

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

@@ -0,0 +1,241 @@
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { chromium } from 'playwright-core';
+import { discoverFlows, loadFlowModule } from '../../runner/flow-loader.js';
+import { translateSchema } from '../../schema/translator.js';
+import { pathExists, readJsonFile } from '../../shared/fs.js';
+import { MIN_NODE_MAJOR, getPackageRoot, getWorkspacePaths, resolveFlowsProjectRoot } from '../../shared/paths.js';
+import { loadTaxonomy, isValidSector, isValidService } from '../../shared/taxonomy.js';
+const dangerousFlowPatterns = [
+    { name: 'absolute Windows path', pattern: /[A-Za-z]:\\/, message: 'contains an absolute Windows path' },
+    { name: 'taskkill', pattern: /\btaskkill\b/i, message: 'kills global processes with taskkill' },
+    { name: 'fixed CDP port', pattern: /--remote-debugging-port=9222/i, message: 'uses fixed CDP port 9222' },
+    { name: 'real Chrome profile', pattern: /Profile 1/, message: 'references a real Chrome Profile 1 directory' },
+    { name: 'process.cwd()', pattern: /process\.cwd\(\)/, message: 'depends on process.cwd()' },
+    { name: 'connectOverCDP', pattern: /connectOverCDP/, message: 'bypasses the central browser runner with connectOverCDP' }
+];
+function add(checks, level, message) {
+    checks.push({ level, message });
+}
+function nodeMajor(version) {
+    return Number.parseInt(version.split('.')[0] ?? '', 10);
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function checkFlowFiles(projectRoot, checks) {
+    const paths = getWorkspacePaths(resolveFlowsProjectRoot(projectRoot));
+    const invalidFlows = [];
+    const taxonomy = await loadTaxonomy();
+    if (!(await isDirectory(paths.flowsDir))) {
+        add(checks, 'error', `Workspace flows directory is missing. Run webflow init in ${projectRoot} or pass the correct projectRoot.`);
+        return invalidFlows;
+    }
+    const entries = await readdir(paths.flowsDir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name.startsWith('_')) {
+            continue;
+        }
+        const flowDir = resolve(paths.flowsDir, entry.name);
+        const entryFile = resolve(flowDir, 'index.ts');
+        const schemaFile = resolve(flowDir, 'schema.json');
+        const entryExists = await pathExists(entryFile);
+        const schemaExists = await pathExists(schemaFile);
+        if (!entryExists || !schemaExists) {
+            invalidFlows.push(entry.name);
+            add(checks, 'error', `Flow ${entry.name} is missing ${!entryExists ? 'index.ts' : 'schema.json'}.`);
+            continue;
+        }
+        try {
+            translateSchema(await readJsonFile(schemaFile));
+        }
+        catch (error) {
+            invalidFlows.push(entry.name);
+            add(checks, 'error', `Flow ${entry.name} has an invalid schema.json: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const source = await readFile(entryFile, 'utf8');
+        for (const dangerous of dangerousFlowPatterns) {
+            if (dangerous.pattern.test(source)) {
+                add(checks, 'warn', `Flow ${entry.name} ${dangerous.message}. Prefer ctx.page/ctx.browser and .webflow/profiles.`);
+            }
+        }
+        let capabilities;
+        try {
+            capabilities = (await loadFlowModule(entryFile)).capabilities;
+        }
+        catch {
+            // Already reported as an invalid flow above; nothing more to check here.
+            continue;
+        }
+        checkLoginNormalization(entry.name, capabilities, checks);
+        checkBrowserModes(entry.name, capabilities, checks);
+        checkTaxonomy(entry.name, capabilities, checks, taxonomy);
+    }
+    return invalidFlows;
+}
+/**
+ * Enforces the explicit `capabilities.requiresLogin` contract (RFC 0001 follow-up,
+ * 2026-07-06): whether a flow needs a real logged-in session must be declared, not
+ * inferred from `profile`/`startUrl`, so the worker catalog and any future
+ * dashboard can rely on it instead of every caller guessing.
+ */
+function checkLoginNormalization(flowName, capabilities, checks) {
+    if (!capabilities?.browser) {
+        return;
+    }
+    if (capabilities.requiresLogin === undefined) {
+        add(checks, 'warn', `Flow ${flowName} uses a browser but does not declare capabilities.requiresLogin (true/false). Declare it explicitly.`);
+        return;
+    }
+    if (capabilities.requiresLogin && capabilities.startUrl === 'about:blank') {
+        add(checks, 'error', `Flow ${flowName} declares requiresLogin: true but startUrl is "about:blank" (no site to log into). This is a contradiction.`);
+    }
+    if (!capabilities.requiresLogin && capabilities.profile) {
+        add(checks, 'warn', `Flow ${flowName} declares requiresLogin: false but also declares capabilities.profile ("${capabilities.profile}"), which normally signals a login-backed session. Double-check which is right.`);
+    }
+}
+function defaultBrowserMode(capability) {
+    if (capability === true || capability === 'managed')
+        return 'managed';
+    if (capability === 'cdp')
+        return 'cdp';
+    return undefined;
+}
+function checkBrowserModes(flowName, capabilities, checks) {
+    const raw = capabilities?.supportedBrowserModes;
+    if (raw === undefined)
+        return;
+    const defaultMode = defaultBrowserMode(capabilities?.browser);
+    if (!defaultMode) {
+        add(checks, 'error', `Flow ${flowName} declares supportedBrowserModes but does not declare a browser mode.`);
+        return;
+    }
+    if (!Array.isArray(raw) || raw.length === 0) {
+        add(checks, 'error', `Flow ${flowName} declares supportedBrowserModes but it is not a non-empty array.`);
+        return;
+    }
+    const invalid = raw.filter((mode) => mode !== 'managed' && mode !== 'cdp');
+    if (invalid.length > 0) {
+        add(checks, 'error', `Flow ${flowName} declares unsupported browser mode(s): ${invalid.map(String).join(', ')}. Use only "managed" and "cdp".`);
+        return;
+    }
+    if (!raw.includes(defaultMode)) {
+        add(checks, 'error', `Flow ${flowName} declares browser default "${defaultMode}" but supportedBrowserModes does not include it.`);
+    }
+}
+/**
+ * Enforces that every flow's sector/service (top two levels of the catalog-browsing hierarchy,
+ * see `browse_catalog` in the relay) resolve against the canonical `taxonomy.json` registry —
+ * unlike login normalization, this applies to every flow, not just browser-driven ones, since
+ * classification should cover future non-browser flows too. Unknown values are blocking errors
+ * (not warnings) to prevent near-duplicate/near-synonymous sectors or services from accumulating
+ * once the catalog has hundreds or thousands of flows; declaring nothing yet is just a warning.
+ */
+function checkTaxonomy(flowName, capabilities, checks, taxonomy) {
+    const category = capabilities?.category;
+    const service = capabilities?.service;
+    if (!category && !service) {
+        add(checks, 'warn', `Flow ${flowName} does not declare capabilities.category/service. It will be filed under "sin-categorizar" until classified.`);
+        return;
+    }
+    if (service && !category) {
+        add(checks, 'error', `Flow ${flowName} declares capabilities.service ("${service}") without capabilities.category.`);
+        return;
+    }
+    if (category && !isValidSector(taxonomy, category)) {
+        add(checks, 'error', `Flow ${flowName} declares capabilities.category "${category}", which is not in the canonical registry (taxonomy.json).`);
+        return;
+    }
+    if (!service) {
+        add(checks, 'warn', `Flow ${flowName} declares capabilities.category ("${category}") but no capabilities.service.`);
+        return;
+    }
+    if (category && !isValidService(taxonomy, category, service)) {
+        add(checks, 'error', `Flow ${flowName} declares capabilities.service "${service}", which is not registered under sector "${category}" in taxonomy.json.`);
+    }
+}
+async function checkPlaywrightInstall(checks) {
+    add(checks, 'ok', 'Playwright module is installed.');
+    const executablePath = chromium.executablePath();
+    if (await pathExists(executablePath)) {
+        add(checks, 'ok', `Chromium executable is available at ${executablePath}.`);
+    }
+    else {
+        add(checks, 'warn', `Chromium executable was not found at ${executablePath}. Run npx playwright install chromium if browser flows fail.`);
+    }
+}
+export async function runDoctor(projectRoot, options = {}) {
+    const root = resolve(projectRoot);
+    const paths = getWorkspacePaths(root);
+    const checks = [];
+    const version = options.nodeVersion ?? process.versions.node;
+    const major = nodeMajor(version);
+    if (!Number.isNaN(major) && major >= MIN_NODE_MAJOR) {
+        add(checks, 'ok', `Node ${version} satisfies >=${MIN_NODE_MAJOR}.`);
+    }
+    else {
+        add(checks, 'error', `Node ${version} is unsupported. WebFlow MCP requires Node ${MIN_NODE_MAJOR}+.`);
+    }
+    if (await isDirectory(root)) {
+        add(checks, 'ok', `Project root exists: ${root}`);
+    }
+    else {
+        add(checks, 'error', `Project root does not exist or is not a directory: ${root}`);
+    }
+    if (await isDirectory(paths.workspaceRoot)) {
+        add(checks, 'ok', `Workspace directory exists: ${paths.workspaceRoot}`);
+    }
+    else {
+        add(checks, 'error', `Workspace directory is missing. Run webflow init in ${root} or pass the correct projectRoot.`);
+    }
+    const invalidFlows = await checkFlowFiles(root, checks);
+    const { flows, diagnostics } = await discoverFlows(root);
+    diagnostics.forEach((diagnostic) => add(checks, 'warn', diagnostic));
+    if (flows.length > 0) {
+        add(checks, 'ok', `Discovered ${flows.length} exposed flow(s).`);
+    }
+    else if (await isDirectory(paths.flowsDir)) {
+        add(checks, 'warn', 'No exposed flows were discovered. Create one with webflow create flow <name>.');
+    }
+    const packageRoot = options.packageRoot ?? getPackageRoot(import.meta.url);
+    const builtCli = resolve(packageRoot, 'dist/src/cli/index.js');
+    if (await pathExists(builtCli)) {
+        add(checks, 'ok', `Build output is available: ${builtCli}`);
+    }
+    else {
+        add(checks, 'warn', `Build output is missing at ${builtCli}. Run npm run build before using the packaged CLI/MCP.`);
+    }
+    if (options.checkPlaywright !== false) {
+        await checkPlaywrightInstall(checks);
+    }
+    return {
+        projectRoot: root,
+        checks,
+        exposedFlows: flows.map((flow) => flow.name),
+        invalidFlows,
+        exitCode: checks.some((check) => check.level === 'error') ? 1 : 0
+    };
+}
+export function formatDoctorResult(result) {
+    const lines = ['WebFlow Doctor', `Project root: ${result.projectRoot}`, '', 'Checks:'];
+    for (const check of result.checks) {
+        lines.push(`[${check.level}] ${check.message}`);
+    }
+    lines.push('', 'Exposed flows:');
+    if (result.exposedFlows.length === 0) {
+        lines.push('- none');
+    }
+    else {
+        result.exposedFlows.forEach((flow) => lines.push(`- ${flow}`));
+    }
+    if (result.invalidFlows.length > 0) {
+        lines.push('', 'Invalid flows:');
+        result.invalidFlows.forEach((flow) => lines.push(`- ${flow}`));
+    }
+    return `${lines.join('\n')}\n`;
+}

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

@@ -0,0 +1,4 @@
+export declare function forkFlow(projectRoot: string, source: string, target: string): Promise<{
+    source: string;
+    target: string;
+}>;

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

@@ -0,0 +1,19 @@
+import { resolve } from 'node:path';
+import { copyDir, pathExists } from '../../shared/fs.js';
+import { WebFlowError } from '../../shared/errors.js';
+import { getWorkspacePaths, sanitizeName } from '../../shared/paths.js';
+export async function forkFlow(projectRoot, source, target) {
+    const paths = getWorkspacePaths(projectRoot);
+    const sourceName = sanitizeName(source);
+    const targetName = sanitizeName(target);
+    const sourceDir = resolve(paths.flowsDir, sourceName);
+    const targetDir = resolve(paths.flowsDir, targetName);
+    if (!(await pathExists(sourceDir))) {
+        throw new WebFlowError('FLOW_NOT_FOUND', `Source flow "${sourceName}" does not exist.`);
+    }
+    if (await pathExists(targetDir)) {
+        throw new WebFlowError('FLOW_ALREADY_EXISTS', `Target flow "${targetName}" already exists.`);
+    }
+    await copyDir(sourceDir, targetDir);
+    return { source: sourceName, target: targetName };
+}

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

@@ -0,0 +1,4 @@
+export declare function initWorkspace(projectRoot: string, metaUrl: string): Promise<{
+    workspaceRoot: string;
+    created: boolean;
+}>;

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

@@ -0,0 +1,22 @@
+import { resolve } from 'node:path';
+import { copyDir, ensureDir, pathExists } from '../../shared/fs.js';
+import { getPackageRoot, getWorkspacePaths } from '../../shared/paths.js';
+export async function initWorkspace(projectRoot, metaUrl) {
+    const paths = getWorkspacePaths(projectRoot);
+    const packageRoot = getPackageRoot(metaUrl);
+    const templateFlows = resolve(packageRoot, '.webflow/flows/_template');
+    const templateSkills = resolve(packageRoot, '.webflow/skills');
+    const flowTarget = resolve(paths.flowsDir, '_template');
+    const alreadyExists = await pathExists(paths.workspaceRoot);
+    await ensureDir(paths.flowsDir);
+    await ensureDir(paths.skillsDir);
+    await ensureDir(paths.profilesDir);
+    await ensureDir(paths.cacheDir);
+    if (!(await pathExists(flowTarget))) {
+        await copyDir(templateFlows, flowTarget);
+    }
+    if (!(await pathExists(resolve(paths.skillsDir, 'README.md')))) {
+        await copyDir(templateSkills, paths.skillsDir);
+    }
+    return { workspaceRoot: paths.workspaceRoot, created: !alreadyExists };
+}

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

@@ -0,0 +1,26 @@
+export declare const DEFAULT_APP_URL = "https://app.webflowmcp.es";
+export interface LoginResult {
+    appUrl: string;
+    relayUrl: string;
+    workerId: string;
+    verificationUriComplete: string;
+    browserOpened: boolean;
+}
+export interface LoginStatus {
+    loggedIn: boolean;
+    appUrl?: string;
+    relayUrl?: string;
+    workerId?: string;
+    credentialId?: string;
+}
+export interface LoginOptions {
+    fetch?: typeof fetch;
+    openBrowser?: (url: string) => Promise<boolean>;
+    sleep?: (milliseconds: number) => Promise<void>;
+    timeoutMs?: number;
+    onVerification?: (verificationUriComplete: string, browserOpened: boolean) => void;
+}
+export declare function openUrlInBrowser(url: string, platform?: NodeJS.Platform): Promise<boolean>;
+export declare function login(appUrl?: string, options?: LoginOptions): Promise<LoginResult>;
+export declare function logout(): Promise<boolean>;
+export declare function loginStatus(): Promise<LoginStatus>;

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

@@ -0,0 +1,145 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { hostname } from 'node:os';
+import { assertSecureRelayUrl, clearCredentials, loadCredentials, loadOrCreateDeviceIdentity, saveCredentials } from '../../shared/credentials.js';
+import { WebFlowError } from '../../shared/errors.js';
+export const DEFAULT_APP_URL = 'https://app.webflowmcp.es';
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const DEFAULT_PAIRING_TIMEOUT_MS = 10 * 60_000;
+function normalizeAppUrl(appUrl) {
+    let parsed;
+    try {
+        parsed = new URL(appUrl);
+    }
+    catch {
+        throw new WebFlowError('INVALID_COMMAND', `Invalid app URL: ${appUrl}`);
+    }
+    const isLoopback = parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1' || parsed.hostname === '[::1]';
+    if (parsed.protocol !== 'https:' && !(parsed.protocol === 'http:' && isLoopback)) {
+        throw new WebFlowError('INVALID_COMMAND', 'The app URL must use https. Plain http is allowed only for local development on loopback.');
+    }
+    return parsed.toString().replace(/\/$/, '');
+}
+async function postJson(fetchImpl, url, body) {
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body)
+        });
+    }
+    catch (error) {
+        throw new WebFlowError('PAIRING_FAILED', `Could not reach ${url}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok) {
+        const detail = await response.text().catch(() => '');
+        throw new WebFlowError('PAIRING_FAILED', `Pairing endpoint returned HTTP ${response.status}${detail ? `: ${detail}` : '.'}`);
+    }
+    try {
+        return await response.json();
+    }
+    catch {
+        throw new WebFlowError('PAIRING_FAILED', 'Pairing endpoint returned invalid JSON.');
+    }
+}
+export function openUrlInBrowser(url, platform = process.platform) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return Promise.resolve(false);
+    }
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:')
+        return Promise.resolve(false);
+    const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'rundll32' : 'xdg-open';
+    const args = platform === 'win32' ? ['url.dll,FileProtocolHandler', parsed.toString()] : [parsed.toString()];
+    return new Promise((resolveOpened) => {
+        let settled = false;
+        const child = spawn(command, args, { detached: true, stdio: 'ignore', shell: false });
+        const finish = (opened) => {
+            if (settled)
+                return;
+            settled = true;
+            resolveOpened(opened);
+        };
+        child.once('error', () => finish(false));
+        child.once('spawn', () => {
+            child.unref();
+            finish(true);
+        });
+    });
+}
+export async function login(appUrl = DEFAULT_APP_URL, options = {}) {
+    const normalizedAppUrl = normalizeAppUrl(appUrl);
+    const fetchImpl = options.fetch ?? fetch;
+    const sleep = options.sleep ?? ((milliseconds) => new Promise((resolveSleep) => setTimeout(resolveSleep, milliseconds)));
+    const identity = await loadOrCreateDeviceIdentity();
+    const credentialId = randomUUID();
+    const secret = randomBytes(32).toString('hex');
+    const secretHash = createHash('sha256').update(secret).digest('hex');
+    const start = await postJson(fetchImpl, `${normalizedAppUrl}/api/device-pairing/start`, {
+        deviceId: identity.deviceId,
+        deviceLabel: hostname(),
+        credentialId,
+        secretHash
+    });
+    if (!start.deviceCode || !start.verificationUriComplete || !start.relayUrl) {
+        throw new WebFlowError('PAIRING_FAILED', 'Pairing start response is missing deviceCode, verificationUriComplete, or relayUrl.');
+    }
+    assertSecureRelayUrl(start.relayUrl);
+    const browserOpened = await (options.openBrowser ?? openUrlInBrowser)(start.verificationUriComplete);
+    options.onVerification?.(start.verificationUriComplete, browserOpened);
+    const timeoutMs = Math.min(options.timeoutMs ?? DEFAULT_PAIRING_TIMEOUT_MS, (start.expiresIn ?? DEFAULT_PAIRING_TIMEOUT_MS / 1000) * 1000);
+    const deadline = Date.now() + timeoutMs;
+    let intervalSeconds = Math.max(1, start.interval ?? DEFAULT_POLL_INTERVAL_SECONDS);
+    while (Date.now() < deadline) {
+        await sleep(intervalSeconds * 1000);
+        if (Date.now() >= deadline)
+            break;
+        const status = await postJson(fetchImpl, `${normalizedAppUrl}/api/device-pairing/status`, { deviceCode: start.deviceCode });
+        if (status.status === 'pending') {
+            if (status.interval !== undefined)
+                intervalSeconds = Math.max(1, status.interval);
+            continue;
+        }
+        if (status.status === 'slow_down') {
+            intervalSeconds = Math.max(intervalSeconds + 5, status.interval ?? 0);
+            continue;
+        }
+        if (status.status === 'denied' || status.status === 'expired') {
+            throw new WebFlowError('PAIRING_FAILED', `Device pairing was ${status.status}. Run "webflow login" to try again.`);
+        }
+        if (status.status === 'approved') {
+            const credentials = {
+                version: 2,
+                appUrl: normalizedAppUrl,
+                relayUrl: start.relayUrl,
+                deviceId: identity.deviceId,
+                workerId: identity.workerId,
+                credentialId,
+                secret
+            };
+            await saveCredentials(credentials);
+            return { appUrl: normalizedAppUrl, relayUrl: start.relayUrl, workerId: identity.workerId, verificationUriComplete: start.verificationUriComplete, browserOpened };
+        }
+        throw new WebFlowError('PAIRING_FAILED', 'Pairing status response was not recognized.');
+    }
+    throw new WebFlowError('PAIRING_FAILED', 'Timed out waiting for device pairing approval. Run "webflow login" to try again.');
+}
+export async function logout() {
+    return clearCredentials();
+}
+export async function loginStatus() {
+    const credentials = await loadCredentials();
+    if (!credentials)
+        return { loggedIn: false };
+    return {
+        loggedIn: true,
+        appUrl: credentials.appUrl,
+        relayUrl: credentials.relayUrl,
+        workerId: credentials.workerId,
+        credentialId: credentials.credentialId
+    };
+}

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

@@ -0,0 +1,40 @@
+import { type ProfileStatusInfo } from '../../profiles/profile-state.js';
+export interface FlowProfileStatus extends ProfileStatusInfo {
+    flow: string;
+    requiresLogin: boolean;
+}
+export interface LoginProfileOptions {
+    startUrl?: string;
+    managed?: boolean;
+    chromePath?: string;
+}
+export interface RefreshInstanceResult {
+    profile: string;
+    instance: string;
+    baseDir: string;
+    instanceDir: string;
+}
+export declare function listProfiles(): Promise<ProfileStatusInfo[]>;
+export declare function statusProfile(profileName: string, options?: {
+    loginUrl?: string;
+}): Promise<ProfileStatusInfo>;
+export declare function statusFlowProfile(projectRoot: string, flowName: string): Promise<FlowProfileStatus>;
+/**
+ * Fire-and-forget variant of loginProfile for the MCP tool path (tool-registry.ts):
+ * opens the browser and returns as soon as it's up, instead of blocking until the
+ * human closes the window (which the CLI's blocking loginProfile does, fine for a
+ * terminal command but far too long for a single MCP tool call). Always uses the
+ * managed launcher since it's the only path with a clean "the window is now open"
+ * checkpoint (launchChromeForLogin's raw spawn only resolves on exit).
+ */
+export declare function startProfileLogin(profileName: string, options?: {
+    startUrl?: string;
+}): Promise<ProfileStatusInfo>;
+export declare function startFlowLogin(projectRoot: string, flowName: string): Promise<FlowProfileStatus>;
+export declare function loginProfile(profileName: string, options?: LoginProfileOptions): Promise<ProfileStatusInfo>;
+export declare function resetProfile(profileName: string): Promise<{
+    profile: string;
+    removed: string[];
+}>;
+export declare function refreshInstanceProfile(profileName: string, instance: string): Promise<RefreshInstanceResult>;
+export declare function formatProfileStatus(status: ProfileStatusInfo | FlowProfileStatus): string;

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

@@ -0,0 +1,142 @@
+import { readdir, rm } from 'node:fs/promises';
+import { dirname, 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 { getProfileStatus, markInteractiveSetup } from '../../profiles/profile-state.js';
+import { pathExists } from '../../shared/fs.js';
+import { getProfilesRoot } from '../../shared/paths.js';
+import { WebFlowError } from '../../shared/errors.js';
+async function resolveFlowProfile(projectRoot, flowName) {
+    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);
+    return {
+        profileName: module.capabilities?.profile ?? `${flowName}-default`,
+        startUrl: module.capabilities?.startUrl,
+        requiresLogin: module.capabilities?.requiresLogin ?? false
+    };
+}
+export async function listProfiles() {
+    const profilesRoot = getProfilesRoot();
+    let entries;
+    try {
+        entries = await readdir(profilesRoot, { withFileTypes: true });
+    }
+    catch {
+        entries = [];
+    }
+    const manager = new ProfileManager(undefined, { profilesDir: profilesRoot });
+    const names = new Set(entries
+        .filter((entry) => entry.isDirectory() && entry.name !== '.webflow-state' && !entry.name.includes('__'))
+        .map((entry) => entry.name));
+    try {
+        const stateEntries = await readdir(resolve(profilesRoot, '.webflow-state'), { withFileTypes: true });
+        for (const entry of stateEntries) {
+            if (entry.isFile() && entry.name.endsWith('.json')) {
+                names.add(entry.name.slice(0, -'.json'.length));
+            }
+        }
+    }
+    catch {
+        // No state dir yet.
+    }
+    const statuses = [];
+    for (const name of [...names].sort((left, right) => left.localeCompare(right))) {
+        statuses.push(await getProfileStatus(await manager.resolve(name)));
+    }
+    return statuses;
+}
+export async function statusProfile(profileName, options = {}) {
+    const manager = new ProfileManager();
+    const profile = await manager.resolve(profileName);
+    return getProfileStatus(profile, { loginUrl: options.loginUrl });
+}
+export async function statusFlowProfile(projectRoot, flowName) {
+    const meta = await resolveFlowProfile(projectRoot, flowName);
+    const status = await statusProfile(meta.profileName, { loginUrl: meta.startUrl });
+    return { ...status, flow: flowName, requiresLogin: meta.requiresLogin };
+}
+/**
+ * Fire-and-forget variant of loginProfile for the MCP tool path (tool-registry.ts):
+ * opens the browser and returns as soon as it's up, instead of blocking until the
+ * human closes the window (which the CLI's blocking loginProfile does, fine for a
+ * terminal command but far too long for a single MCP tool call). Always uses the
+ * managed launcher since it's the only path with a clean "the window is now open"
+ * checkpoint (launchChromeForLogin's raw spawn only resolves on exit).
+ */
+export async function startProfileLogin(profileName, options = {}) {
+    const manager = new ProfileManager();
+    const profile = await manager.ensure(profileName);
+    const session = await launchBrowserSession({ userDataDir: profile.dir, headless: false, startUrl: options.startUrl });
+    session.context.once('close', () => {
+        void markInteractiveSetup(profile);
+    });
+    return getProfileStatus(profile, { loginUrl: options.startUrl });
+}
+export async function startFlowLogin(projectRoot, flowName) {
+    const meta = await resolveFlowProfile(projectRoot, flowName);
+    const status = await startProfileLogin(meta.profileName, { startUrl: meta.startUrl });
+    return { ...status, flow: flowName, requiresLogin: meta.requiresLogin };
+}
+export async function loginProfile(profileName, options = {}) {
+    const manager = new ProfileManager();
+    const profile = await manager.ensure(profileName);
+    if (options.managed) {
+        const session = await launchBrowserSession({ userDataDir: profile.dir, headless: false, startUrl: options.startUrl });
+        await new Promise((done) => {
+            session.context.once('close', () => done());
+        });
+    }
+    else {
+        await launchChromeForLogin({ userDataDir: profile.dir, startUrl: options.startUrl, executablePath: options.chromePath });
+    }
+    await markInteractiveSetup(profile);
+    return getProfileStatus(profile, { loginUrl: options.startUrl });
+}
+export async function resetProfile(profileName) {
+    const manager = new ProfileManager();
+    const profile = await manager.resolve(profileName);
+    const root = dirname(profile.baseDir);
+    const removed = [];
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch {
+        entries = [];
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        if (entry.name === profile.id || entry.name.startsWith(`${profile.id}__`)) {
+            const dir = resolve(root, entry.name);
+            await rm(dir, { recursive: true, force: true });
+            removed.push(dir);
+        }
+    }
+    const status = await getProfileStatus(profile);
+    await rm(status.stateFile, { force: true });
+    return { profile: profile.id, removed };
+}
+export async function refreshInstanceProfile(profileName, instance) {
+    const manager = new ProfileManager();
+    const base = await manager.resolve(profileName);
+    if (!(await pathExists(base.baseDir))) {
+        throw new WebFlowError('PROFILE_NOT_FOUND', `Base profile "${base.id}" does not exist. Run webflow profiles login ${base.id} first.`, {
+            profile: base.id
+        });
+    }
+    const target = await manager.resolve(profileName, undefined, { instance });
+    await rm(target.dir, { recursive: true, force: true });
+    const refreshed = await manager.ensure(profileName, undefined, { instance });
+    return { profile: refreshed.id, instance: refreshed.instance ?? instance, baseDir: refreshed.baseDir, instanceDir: refreshed.dir };
+}
+export function formatProfileStatus(status) {
+    const flow = 'flow' in status ? `Flow: ${status.flow}\nRequires login: ${status.requiresLogin ? 'yes' : 'no'}\n` : '';
+    return `${flow}Profile: ${status.profileId}\nStatus: ${status.status}\nProbably valid: ${status.probablyValid}\nDirectory: ${status.profileDir}\nSetup command: ${status.setupCommand}`;
+}

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

@@ -0,0 +1,10 @@
+import type { FlowExecutionResult } from '../../runner/types.js';
+import type { BrowserVisibility } from '../../config/webflow-config.js';
+import type { BrowserMode } from '../../runner/types.js';
+export interface RunFlowOptions {
+    headed?: boolean;
+    profileName?: string;
+    browserMode?: BrowserMode;
+    browserVisibility?: BrowserVisibility;
+}
+export declare function runFlow(projectRoot: string, flowName: string, input: unknown, options?: RunFlowOptions): Promise<FlowExecutionResult>;