webflow-mcp 0.3.0

package/dist/src/mcp/tool-registry.js

@@ -0,0 +1,366 @@
+import { z } from 'zod';
+import { FlowRunner } from '../runner/flow-runner.js';
+import { discoverFlows, loadFlowModule } from '../runner/flow-loader.js';
+import { buildProfileLoginCommand } from '../profiles/profile-state.js';
+import { listProfiles, refreshInstanceProfile, resetProfile, startFlowLogin, statusFlowProfile } from '../cli/commands/profiles.js';
+import { logout as clearLogin } from '../cli/commands/login.js';
+import { startBackgroundWorker, stopBackgroundWorker, isWorkerRunning } from '../worker/lifecycle.js';
+import { approvePending, listApprovals, listPending, revokeApproval } from '../security/flow-approvals.js';
+import { readJsonFile } from '../shared/fs.js';
+import { WebFlowError } from '../shared/errors.js';
+import { translateSchema } from '../schema/translator.js';
+import { loadConfig, setDefaultBrowserMode, setDefaultBrowserVisibility, setFlowBrowserMode, setFlowBrowserVisibility } from '../config/webflow-config.js';
+import { registerRelayGatewayTools } from './relay-gateway.js';
+function normalizeStructuredContent(result) {
+    if (typeof result === 'object' && result !== null && !Array.isArray(result)) {
+        return result;
+    }
+    return { result };
+}
+function errorToolResult(code, message, details = {}) {
+    const error = { code, message, ...details };
+    return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(error, null, 2) }],
+        structuredContent: error
+    };
+}
+function caughtErrorToolResult(error, fallbackCode = 'PROFILE_REQUEST_FAILED') {
+    const code = error instanceof WebFlowError ? error.code : fallbackCode;
+    const message = error instanceof Error ? error.message : String(error);
+    return errorToolResult(code, message);
+}
+export async function registerFlowTools(server, projectRoot, options = {}) {
+    const { gateway } = options;
+    const { flows, diagnostics } = gateway ? { flows: [], diagnostics: [] } : await discoverFlows(projectRoot);
+    const runner = gateway ? undefined : new FlowRunner(projectRoot);
+    server.registerTool('get_config', {
+        title: 'get_config',
+        description: 'Read local browser-mode and browser-visibility preferences from this machine.',
+        inputSchema: z.object({})
+    }, async () => {
+        const config = await loadConfig();
+        return { content: [{ type: 'text', text: JSON.stringify(config, null, 2) }], structuredContent: normalizeStructuredContent(config) };
+    });
+    server.registerTool('set_browser_visibility', {
+        title: 'set_browser_visibility',
+        description: 'Persist whether managed Chrome runs visible or hidden. Default scope accepts visible/hidden/inherit; flow scope accepts visible/hidden/null.',
+        inputSchema: z.object({ scope: z.enum(['default', 'flow']), flowName: z.string().min(1).optional(), value: z.enum(['visible', 'hidden', 'inherit']).nullable() })
+    }, async ({ scope, flowName, value }) => {
+        if (scope === 'default') {
+            if (value === null)
+                return errorToolResult('INVALID_ARGUMENT', 'scope:"default" requires value "visible", "hidden", or "inherit".');
+            if (flowName)
+                return errorToolResult('INVALID_ARGUMENT', 'flowName must be omitted when scope is "default".');
+            const config = await setDefaultBrowserVisibility(value);
+            return { content: [{ type: 'text', text: JSON.stringify({ config }, null, 2) }], structuredContent: { config } };
+        }
+        if (!flowName)
+            return errorToolResult('INVALID_ARGUMENT', 'flowName is required when scope is "flow".');
+        if (value === 'inherit')
+            return errorToolResult('INVALID_ARGUMENT', 'scope:"flow" uses value:null to clear the override; "inherit" is only valid for scope:"default".');
+        const config = await setFlowBrowserVisibility(flowName, value);
+        return { content: [{ type: 'text', text: JSON.stringify({ config }, null, 2) }], structuredContent: { config } };
+    });
+    server.registerTool('set_browser_mode', {
+        title: 'set_browser_mode',
+        description: 'Persist whether flows prefer Playwright managed mode or real Chrome CDP. Default scope accepts managed/cdp/inherit; flow scope accepts managed/cdp/null.',
+        inputSchema: z.object({ scope: z.enum(['default', 'flow']), flowName: z.string().min(1).optional(), value: z.enum(['managed', 'cdp', 'inherit']).nullable() })
+    }, async ({ scope, flowName, value }) => {
+        if (scope === 'default') {
+            if (value === null)
+                return errorToolResult('INVALID_ARGUMENT', 'scope:"default" requires value "managed", "cdp", or "inherit".');
+            if (flowName)
+                return errorToolResult('INVALID_ARGUMENT', 'flowName must be omitted when scope is "default".');
+            const config = await setDefaultBrowserMode(value);
+            return { content: [{ type: 'text', text: JSON.stringify({ config }, null, 2) }], structuredContent: { config } };
+        }
+        if (!flowName)
+            return errorToolResult('INVALID_ARGUMENT', 'flowName is required when scope is "flow".');
+        if (value === 'inherit')
+            return errorToolResult('INVALID_ARGUMENT', 'scope:"flow" uses value:null to clear the override; "inherit" is only valid for scope:"default".');
+        const config = await setFlowBrowserMode(flowName, value);
+        return { content: [{ type: 'text', text: JSON.stringify({ config }, null, 2) }], structuredContent: { config } };
+    });
+    if (!gateway) {
+        server.registerTool('run_flow_with_options', {
+            title: 'run_flow_with_options',
+            description: 'Run a local flow once with optional one-off browserMode/browserVisibility overrides. Requires confirmed:true when passing browser options; does not persist config.',
+            inputSchema: z.object({
+                name: z.string().min(1),
+                input: z.record(z.string(), z.unknown()).optional(),
+                browserMode: z.enum(['managed', 'cdp']).optional(),
+                browserVisibility: z.enum(['visible', 'hidden']).optional(),
+                confirmed: z.boolean().optional()
+            })
+        }, async ({ name, input, browserMode, browserVisibility, confirmed }) => {
+            if ((browserMode || browserVisibility) && confirmed !== true) {
+                return errorToolResult('CONFIRMATION_REQUIRED', 'Ask the user for explicit confirmation before running with one-off browser options, then retry with confirmed:true.');
+            }
+            const flow = flows.find((entry) => entry.name === name);
+            if (!flow)
+                return errorToolResult('FLOW_NOT_FOUND', `No flow named "${name}" in this workspace.`);
+            const result = await runner.run(flow, input ?? {}, { browserMode, browserVisibility });
+            if (!result.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: JSON.stringify(result.error, null, 2) }],
+                    structuredContent: normalizeStructuredContent(result.error)
+                };
+            }
+            const structuredContent = result.visibilityNudge
+                ? { ...normalizeStructuredContent(result.result), askUser: result.visibilityNudge }
+                : normalizeStructuredContent(result.result);
+            return { content: [{ type: 'text', text: JSON.stringify(structuredContent, null, 2) }], structuredContent };
+        });
+        server.registerTool('check_profile_status', {
+            title: 'check_profile_status',
+            description: 'Check whether this machine has a probably-valid logged-in session for a flow that requires login. ' +
+                'Call this before running such a flow to avoid a failed run, and again after the user says they ' +
+                'finished a login you started with start_profile_login, to confirm it actually worked.',
+            inputSchema: z.object({ flowName: z.string().min(1) })
+        }, async ({ flowName }) => {
+            try {
+                const status = await statusFlowProfile(projectRoot, flowName);
+                return { content: [{ type: 'text', text: JSON.stringify(status, null, 2) }], structuredContent: normalizeStructuredContent(status) };
+            }
+            catch (error) {
+                return caughtErrorToolResult(error, 'PROFILE_STATUS_REQUEST_FAILED');
+            }
+        });
+        server.registerTool('start_profile_login', {
+            title: 'start_profile_login',
+            description: 'Open a real, visible Chrome window on this machine so the user can log in manually to a flow\'s required ' +
+                'account (e.g. Google/X/Adobe). This only opens the window and returns immediately — it does NOT wait for ' +
+                'the human to finish, and does not log in on your behalf. Only call this when the user has explicitly ' +
+                'asked to log in, or has just agreed after you asked, then call it again with confirmed:true. After they ' +
+                'say they are done, call check_profile_status to verify it actually worked.',
+            inputSchema: z.object({ flowName: z.string().min(1), confirmed: z.boolean().optional() })
+        }, async ({ flowName, confirmed }) => {
+            if (confirmed !== true) {
+                return errorToolResult('CONFIRMATION_REQUIRED', 'Ask the user for explicit confirmation before opening a login window, then retry with confirmed:true.');
+            }
+            try {
+                const status = await startFlowLogin(projectRoot, flowName);
+                const structuredContent = {
+                    ...normalizeStructuredContent(status),
+                    note: 'A Chrome window should now be open on this machine. Ask the user to log in and close the window when done, then call check_profile_status to confirm.'
+                };
+                return { content: [{ type: 'text', text: JSON.stringify(structuredContent, null, 2) }], structuredContent };
+            }
+            catch (error) {
+                return caughtErrorToolResult(error, 'PROFILE_LOGIN_REQUEST_FAILED');
+            }
+        });
+    }
+    server.registerTool('logout', {
+        title: 'logout',
+        description: 'Remove the relay login this machine saved via "webflow login". Does not stop an already-running worker ' +
+            '— call stop_worker first if one is up. Only call this when the user has explicitly asked to log out.',
+        inputSchema: z.object({})
+    }, async () => {
+        const loggedOut = await clearLogin();
+        return { content: [{ type: 'text', text: JSON.stringify({ loggedOut }, null, 2) }], structuredContent: { loggedOut } };
+    });
+    server.registerTool('start_worker', {
+        title: 'start_worker',
+        description: 'Start this machine\'s worker in the background so it connects to the relay and can run flows requested ' +
+            'from any MCP client (not just this session) — it keeps running after this tool call returns. Requires the ' +
+            'user to have already run "webflow login" once and approved browser pairing; never ask them to paste a ' +
+            'worker credential here. If a worker is already running, reports that instead of starting a second one.',
+        inputSchema: z.object({
+            headed: z.boolean().optional(),
+            browserMode: z.enum(['managed', 'cdp']).optional(),
+            browserVisibility: z.enum(['visible', 'hidden']).optional()
+        })
+    }, async (args) => {
+        const result = await startBackgroundWorker(args);
+        if (!result.started) {
+            if (result.alreadyRunning) {
+                return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: normalizeStructuredContent(result) };
+            }
+            return errorToolResult('WORKER_START_FAILED', result.reason);
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: normalizeStructuredContent(result) };
+    });
+    server.registerTool('stop_worker', {
+        title: 'stop_worker',
+        description: 'Stop the worker this machine started with start_worker, if one is running.',
+        inputSchema: z.object({})
+    }, async () => {
+        const result = await stopBackgroundWorker();
+        if (!result.stopped) {
+            return errorToolResult('WORKER_NOT_RUNNING', result.reason);
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: normalizeStructuredContent(result) };
+    });
+    server.registerTool('worker_status', {
+        title: 'worker_status',
+        description: 'Check whether a worker started by start_worker is currently running on this machine.',
+        inputSchema: z.object({})
+    }, async () => {
+        const info = await isWorkerRunning();
+        const result = info ? { running: true, ...info } : { running: false };
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: normalizeStructuredContent(result) };
+    });
+    server.registerTool('list_profiles', {
+        title: 'list_profiles',
+        description: 'List every saved login session (profile) on this machine and its current status.',
+        inputSchema: z.object({})
+    }, async () => {
+        const profiles = await listProfiles();
+        return { content: [{ type: 'text', text: JSON.stringify(profiles, null, 2) }], structuredContent: { profiles } };
+    });
+    server.registerTool('reset_profile', {
+        title: 'reset_profile',
+        description: 'Delete a saved login session on this machine, requiring a fresh manual login next time it is needed. ' +
+            'This cannot be undone — requires confirmed:true after the user explicitly agrees.',
+        inputSchema: z.object({ profileName: z.string().min(1), confirmed: z.boolean().optional() })
+    }, async ({ profileName, confirmed }) => {
+        if (confirmed !== true) {
+            return errorToolResult('CONFIRMATION_REQUIRED', 'Ask the user for explicit confirmation before deleting this login session, then retry with confirmed:true.');
+        }
+        try {
+            const result = await resetProfile(profileName);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: normalizeStructuredContent(result) };
+        }
+        catch (error) {
+            return caughtErrorToolResult(error, 'PROFILE_RESET_FAILED');
+        }
+    });
+    server.registerTool('refresh_profile_instance', {
+        title: 'refresh_profile_instance',
+        description: 'Clone a saved login session into a fresh, separate numbered instance (for running the same login in ' +
+            'parallel or rotating sessions to avoid provider rate limits), overwriting that instance if it already exists.',
+        inputSchema: z.object({ profileName: z.string().min(1), instance: z.string().min(1) })
+    }, async ({ profileName, instance }) => {
+        try {
+            const result = await refreshInstanceProfile(profileName, instance);
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: normalizeStructuredContent(result) };
+        }
+        catch (error) {
+            return caughtErrorToolResult(error, 'PROFILE_REFRESH_FAILED');
+        }
+    });
+    server.registerTool('list_flow_approvals', {
+        title: 'list_flow_approvals',
+        description: 'List signed flow updates that are approved or awaiting approval on this machine. This never returns flow code, schemas, or capabilities.',
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+    }, async () => {
+        try {
+            const [approved, pending] = await Promise.all([listApprovals(), listPending()]);
+            const result = { approved, pending };
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: result };
+        }
+        catch (error) {
+            return caughtErrorToolResult(error, 'FLOW_APPROVAL_LIST_FAILED');
+        }
+    });
+    server.registerTool('approve_flow_update', {
+        title: 'approve_flow_update',
+        description: 'Approve one exact signed flow digest on this machine. First call without confirmed:true to inspect the ' +
+            'version, digest, signer and trust domain. Ask the user, then repeat with confirmed:true plus the exact ' +
+            'flowDigest, releaseId and sequence returned by the first call.',
+        inputSchema: z.object({
+            flowName: z.string().min(1).max(128),
+            trustDomain: z.string().min(1).max(256).optional(),
+            confirmed: z.boolean().optional(),
+            flowDigest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+            releaseId: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+            sequence: z.number().int().positive().optional()
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+    }, async ({ flowName, trustDomain, confirmed, flowDigest, releaseId, sequence }) => {
+        try {
+            const matches = (await listPending()).filter((entry) => entry.flowName === flowName && (!trustDomain || entry.trustDomain === trustDomain));
+            if (matches.length === 0)
+                return errorToolResult('FLOW_APPROVAL_NOT_FOUND', `No pending signed update found for flow "${flowName}".`);
+            if (matches.length > 1)
+                return errorToolResult('FLOW_APPROVAL_AMBIGUOUS', `Specify trustDomain for flow "${flowName}".`);
+            const pending = matches[0];
+            if (confirmed !== true) {
+                return errorToolResult('CONFIRMATION_REQUIRED', 'Show this exact signed update to the user and ask for explicit approval before retrying with confirmed:true and the returned identity fields.', { pending, retryWith: { flowName, trustDomain: pending.trustDomain, flowDigest: pending.flowDigest, releaseId: pending.releaseId, sequence: pending.sequence, confirmed: true } });
+            }
+            if (!flowDigest || !releaseId || sequence === undefined) {
+                return errorToolResult('CONFIRMATION_BINDING_REQUIRED', 'confirmed:true requires the exact flowDigest, releaseId and sequence returned by the inspection call.');
+            }
+            const approved = await approvePending(flowName, pending.trustDomain, { flowDigest, releaseId, sequence });
+            return { content: [{ type: 'text', text: JSON.stringify({ approved }, null, 2) }], structuredContent: { approved } };
+        }
+        catch (error) {
+            return caughtErrorToolResult(error, 'FLOW_APPROVAL_FAILED');
+        }
+    });
+    server.registerTool('revoke_flow_approval', {
+        title: 'revoke_flow_approval',
+        description: 'Revoke one exact local signed-flow approval. First call without confirmed:true to inspect it, ask the ' +
+            'user, then repeat with confirmed:true plus the exact flowDigest, releaseId and sequence returned.',
+        inputSchema: z.object({
+            flowName: z.string().min(1).max(128),
+            trustDomain: z.string().min(1).max(256).optional(),
+            confirmed: z.boolean().optional(),
+            flowDigest: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+            releaseId: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+            sequence: z.number().int().positive().optional()
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }
+    }, async ({ flowName, trustDomain, confirmed, flowDigest, releaseId, sequence }) => {
+        try {
+            const matches = (await listApprovals()).filter((entry) => entry.flowName === flowName && (!trustDomain || entry.trustDomain === trustDomain));
+            if (matches.length === 0)
+                return errorToolResult('FLOW_APPROVAL_NOT_FOUND', `No approval found for flow "${flowName}".`);
+            if (matches.length > 1)
+                return errorToolResult('FLOW_APPROVAL_AMBIGUOUS', `Specify trustDomain for flow "${flowName}".`);
+            const approval = matches[0];
+            if (confirmed !== true) {
+                return errorToolResult('CONFIRMATION_REQUIRED', 'Show this exact approval to the user and ask before retrying with confirmed:true and the returned identity fields.', { approval, retryWith: { flowName, trustDomain: approval.trustDomain, flowDigest: approval.flowDigest, releaseId: approval.releaseId, sequence: approval.sequence, confirmed: true } });
+            }
+            if (!flowDigest || !releaseId || sequence === undefined) {
+                return errorToolResult('CONFIRMATION_BINDING_REQUIRED', 'confirmed:true requires the exact flowDigest, releaseId and sequence returned by the inspection call.');
+            }
+            await revokeApproval(flowName, approval.trustDomain, { flowDigest, releaseId, sequence });
+            const result = { revoked: true, flowName, trustDomain: approval.trustDomain };
+            return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }], structuredContent: result };
+        }
+        catch (error) {
+            return caughtErrorToolResult(error, 'FLOW_APPROVAL_REVOKE_FAILED');
+        }
+    });
+    if (gateway) {
+        registerRelayGatewayTools(server, gateway);
+    }
+    for (const flow of flows) {
+        const compiled = translateSchema(await readJsonFile(flow.schemaFile));
+        const module = await loadFlowModule(flow.entryFile);
+        const baseDescription = compiled.jsonSchema.description ?? `Run the ${flow.name} flow.`;
+        const loginUrl = module.capabilities?.startUrl && module.capabilities.startUrl !== 'about:blank' ? module.capabilities.startUrl : undefined;
+        const loginDescription = module.capabilities?.requiresLogin
+            ? ` Requires logged-in profile "${module.capabilities.profile ?? `${flow.name}-default`}". Check it with "webflow profiles status --flow ${flow.name} --json"; if missing, run "${buildProfileLoginCommand(module.capabilities.profile ?? `${flow.name}-default`, loginUrl)}".`
+            : '';
+        const description = `${baseDescription}${loginDescription}`;
+        server.registerTool(flow.name, {
+            title: flow.name,
+            description,
+            inputSchema: compiled.zodSchema
+        }, async (arguments_) => {
+            const profileName = typeof arguments_.profile === 'string' ? arguments_.profile : undefined;
+            const result = await runner.run(flow, arguments_, { profileName, schema: compiled });
+            if (!result.ok) {
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: JSON.stringify(result.error, null, 2) }],
+                    structuredContent: normalizeStructuredContent(result.error)
+                };
+            }
+            const structuredContent = result.visibilityNudge
+                ? { ...normalizeStructuredContent(result.result), askUser: result.visibilityNudge }
+                : normalizeStructuredContent(result.result);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(structuredContent, null, 2) }],
+                structuredContent
+            };
+        });
+    }
+    return { diagnostics, flows };
+}

package/dist/src/profiles/profile-manager.d.ts

@@ -0,0 +1,33 @@
+export interface ResolvedProfile {
+    id: string;
+    /** Effective directory to launch against (per-instance when an instance is given). */
+    dir: string;
+    /** The shared, logged-in base profile this instance derives from. */
+    baseDir: string;
+    /** Instance suffix when running multiple agents in parallel, otherwise undefined. */
+    instance?: string;
+}
+export interface ProfileManagerOptions {
+    /** Override the global profiles root (used by tests for isolation). */
+    profilesDir?: string;
+}
+export interface ResolveProfileOptions {
+    /**
+     * Instance suffix for parallel agents. Each instance gets its own user-data-dir
+     * (a clone of the logged-in base profile) because a Chrome profile directory can
+     * only be opened by one process at a time. Off by default.
+     */
+    instance?: string;
+}
+export declare class ProfileManager {
+    private readonly profilesRoot;
+    constructor(_projectRoot?: string, options?: ProfileManagerOptions);
+    resolve(profileName?: string, flowName?: string, options?: ResolveProfileOptions): Promise<ResolvedProfile>;
+    /**
+     * Resolve and create the launch directory. When an instance is given and the
+     * per-instance dir does not exist yet, clone the logged-in base profile into it so
+     * the parallel agent inherits the session without fighting over the same directory.
+     */
+    ensure(profileName?: string, flowName?: string, options?: ResolveProfileOptions): Promise<ResolvedProfile>;
+    release(_id: string): Promise<void>;
+}

package/dist/src/profiles/profile-manager.js

@@ -0,0 +1,37 @@
+import { resolve } from 'node:path';
+import { copyDir, ensureDir, pathExists } from '../shared/fs.js';
+import { getProfilesRoot, sanitizeName } from '../shared/paths.js';
+export class ProfileManager {
+    profilesRoot;
+    constructor(_projectRoot, options = {}) {
+        // Sessions are global, decoupled from any single repo. projectRoot is kept for
+        // call-site compatibility but no longer determines where profiles live.
+        this.profilesRoot = options.profilesDir ?? getProfilesRoot();
+    }
+    async resolve(profileName, flowName, options = {}) {
+        const rawName = profileName ?? `${flowName ?? 'flow'}-default`;
+        const id = sanitizeName(rawName);
+        const baseDir = resolve(this.profilesRoot, id);
+        if (options.instance) {
+            const instance = sanitizeName(options.instance);
+            return { id, baseDir, instance, dir: resolve(this.profilesRoot, `${id}__${instance}`) };
+        }
+        return { id, baseDir, dir: baseDir };
+    }
+    /**
+     * Resolve and create the launch directory. When an instance is given and the
+     * per-instance dir does not exist yet, clone the logged-in base profile into it so
+     * the parallel agent inherits the session without fighting over the same directory.
+     */
+    async ensure(profileName, flowName, options = {}) {
+        const resolved = await this.resolve(profileName, flowName, options);
+        if (resolved.instance && !(await pathExists(resolved.dir)) && (await pathExists(resolved.baseDir))) {
+            await copyDir(resolved.baseDir, resolved.dir);
+        }
+        await ensureDir(resolved.dir);
+        return resolved;
+    }
+    async release(_id) {
+        return Promise.resolve();
+    }
+}

package/dist/src/profiles/profile-state.d.ts

@@ -0,0 +1,31 @@
+import type { ResolvedProfile } from './profile-manager.js';
+export type ProfileStatus = 'missing' | 'exists_unverified' | 'setup_completed' | 'verified' | 'login_required';
+export type ProfileValidity = boolean | 'unknown';
+export declare function looksLikeLoginWall(url: string | undefined): boolean;
+export interface StoredProfileState {
+    profileId: string;
+    profileDir: string;
+    lastInteractiveSetupAt?: string;
+    lastSuccessfulRunAt?: string;
+    lastFlow?: string;
+    lastLoginRequiredAt?: string | null;
+    updatedAt: string;
+}
+export interface ProfileStatusInfo extends StoredProfileState {
+    baseDir: string;
+    instance?: string;
+    stateFile: string;
+    exists: boolean;
+    status: ProfileStatus;
+    probablyValid: ProfileValidity;
+    loginUrl?: string;
+    setupCommand: string;
+}
+export declare function buildProfileLoginCommand(profileId: string, loginUrl?: string): string;
+export declare function readProfileState(profile: ResolvedProfile): Promise<StoredProfileState | undefined>;
+export declare function markInteractiveSetup(profile: ResolvedProfile, flowName?: string): Promise<StoredProfileState>;
+export declare function markSuccessfulRun(profile: ResolvedProfile, flowName: string): Promise<StoredProfileState>;
+export declare function markLoginRequired(profile: ResolvedProfile, flowName: string): Promise<StoredProfileState>;
+export declare function getProfileStatus(profile: ResolvedProfile, options?: {
+    loginUrl?: string;
+}): Promise<ProfileStatusInfo>;

package/dist/src/profiles/profile-state.js

@@ -0,0 +1,122 @@
+import { dirname, resolve } from 'node:path';
+import { ensureDir, pathExists, readJsonFile, writeJsonFile } from '../shared/fs.js';
+// Same substrings every login-backed flow already checks by hand against `page.url()`
+// (see gemini-prompt, chatgpt-prompt, twitter, google-speech-generate) after being
+// redirected mid-flow — centralized here so FlowRunner can turn that into a tracked
+// `login_required` state instead of a generic step failure.
+const LOGIN_WALL_MARKERS = ['accounts.google.com', 'signin', '/login', '/auth', '/i/flow/login'];
+export function looksLikeLoginWall(url) {
+    if (!url)
+        return false;
+    const lower = url.toLowerCase();
+    return LOGIN_WALL_MARKERS.some((marker) => lower.includes(marker));
+}
+function profileStateFile(profile) {
+    return resolve(dirname(profile.baseDir), '.webflow-state', `${profile.id}.json`);
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function newerThan(left, right) {
+    if (!left)
+        return false;
+    if (!right)
+        return true;
+    return new Date(left).getTime() > new Date(right).getTime();
+}
+function shellArg(value) {
+    return JSON.stringify(value);
+}
+export function buildProfileLoginCommand(profileId, loginUrl) {
+    const urlPart = loginUrl ? ` --url ${shellArg(loginUrl)}` : '';
+    return `webflow profiles login ${profileId}${urlPart}`;
+}
+export async function readProfileState(profile) {
+    try {
+        return await readJsonFile(profileStateFile(profile));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeProfileState(profile, state) {
+    const stateFile = profileStateFile(profile);
+    await ensureDir(dirname(stateFile));
+    await writeJsonFile(stateFile, state);
+    return state;
+}
+async function patchProfileState(profile, patch) {
+    const current = await readProfileState(profile);
+    return writeProfileState(profile, {
+        profileId: profile.id,
+        profileDir: profile.baseDir,
+        ...current,
+        ...patch,
+        updatedAt: nowIso()
+    });
+}
+export async function markInteractiveSetup(profile, flowName) {
+    return patchProfileState(profile, {
+        lastInteractiveSetupAt: nowIso(),
+        lastFlow: flowName,
+        lastLoginRequiredAt: null
+    });
+}
+export async function markSuccessfulRun(profile, flowName) {
+    return patchProfileState(profile, {
+        lastSuccessfulRunAt: nowIso(),
+        lastFlow: flowName,
+        lastLoginRequiredAt: null
+    });
+}
+export async function markLoginRequired(profile, flowName) {
+    return patchProfileState(profile, {
+        lastLoginRequiredAt: nowIso(),
+        lastFlow: flowName
+    });
+}
+export async function getProfileStatus(profile, options = {}) {
+    const [exists, stored] = await Promise.all([pathExists(profile.dir), readProfileState(profile)]);
+    const latestGood = newerThan(stored?.lastSuccessfulRunAt, stored?.lastInteractiveSetupAt)
+        ? stored?.lastSuccessfulRunAt
+        : stored?.lastInteractiveSetupAt;
+    let status;
+    let probablyValid;
+    if (!exists) {
+        status = 'missing';
+        probablyValid = false;
+    }
+    else if (newerThan(stored?.lastLoginRequiredAt, latestGood)) {
+        status = 'login_required';
+        probablyValid = false;
+    }
+    else if (stored?.lastSuccessfulRunAt) {
+        status = 'verified';
+        probablyValid = true;
+    }
+    else if (stored?.lastInteractiveSetupAt) {
+        status = 'setup_completed';
+        probablyValid = true;
+    }
+    else {
+        status = 'exists_unverified';
+        probablyValid = 'unknown';
+    }
+    return {
+        profileId: profile.id,
+        profileDir: profile.dir,
+        baseDir: profile.baseDir,
+        instance: profile.instance,
+        stateFile: profileStateFile(profile),
+        exists,
+        status,
+        probablyValid,
+        loginUrl: options.loginUrl,
+        setupCommand: buildProfileLoginCommand(profile.id, options.loginUrl),
+        lastInteractiveSetupAt: stored?.lastInteractiveSetupAt,
+        lastSuccessfulRunAt: stored?.lastSuccessfulRunAt,
+        lastFlow: stored?.lastFlow,
+        lastLoginRequiredAt: stored?.lastLoginRequiredAt,
+        updatedAt: stored?.updatedAt ?? nowIso()
+    };
+}

package/dist/src/repertoire/local-repertoire.d.ts

@@ -0,0 +1,3 @@
+export declare function listRepertoire(): Promise<string[]>;
+export declare function addToRepertoire(flowName: string): Promise<string[]>;
+export declare function removeFromRepertoire(flowName: string): Promise<string[]>;

package/dist/src/repertoire/local-repertoire.js

@@ -0,0 +1,59 @@
+import { dirname } from 'node:path';
+import { getRepertoirePath } from '../shared/paths.js';
+import { ensureDir, readJsonFile, writeJsonFile } from '../shared/fs.js';
+function emptyRepertoire() {
+    return { flows: [] };
+}
+/** Corrupt/hand-edited repertoire.json falls back to empty rather than crashing the worker. */
+function sanitizeRepertoire(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return emptyRepertoire();
+    const rawFlows = raw.flows;
+    if (!Array.isArray(rawFlows))
+        return emptyRepertoire();
+    const flows = [];
+    for (const entry of rawFlows) {
+        if (typeof entry === 'object' && entry !== null && typeof entry.name === 'string') {
+            const addedAt = entry.addedAt;
+            flows.push({
+                name: entry.name,
+                addedAt: typeof addedAt === 'string' ? addedAt : new Date().toISOString()
+            });
+        }
+    }
+    return { flows };
+}
+async function loadRepertoire() {
+    try {
+        const raw = await readJsonFile(getRepertoirePath());
+        return sanitizeRepertoire(raw);
+    }
+    catch {
+        return emptyRepertoire();
+    }
+}
+async function saveRepertoire(repertoire) {
+    const path = getRepertoirePath();
+    await ensureDir(dirname(path));
+    await writeJsonFile(path, repertoire);
+}
+export async function listRepertoire() {
+    const repertoire = await loadRepertoire();
+    return repertoire.flows.map((entry) => entry.name);
+}
+export async function addToRepertoire(flowName) {
+    const repertoire = await loadRepertoire();
+    if (!repertoire.flows.some((entry) => entry.name === flowName)) {
+        repertoire.flows.push({ name: flowName, addedAt: new Date().toISOString() });
+        await saveRepertoire(repertoire);
+    }
+    return repertoire.flows.map((entry) => entry.name);
+}
+export async function removeFromRepertoire(flowName) {
+    const repertoire = await loadRepertoire();
+    const filtered = repertoire.flows.filter((entry) => entry.name !== flowName);
+    if (filtered.length !== repertoire.flows.length) {
+        await saveRepertoire({ flows: filtered });
+    }
+    return filtered.map((entry) => entry.name);
+}