webflow-mcp 0.3.0

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

@@ -0,0 +1,378 @@
+import { ZodError } from 'zod';
+import { buildSelfHealingPayload } from '../errors/self-healing.js';
+import { ProfileManager } from '../profiles/profile-manager.js';
+import { buildProfileLoginCommand, getProfileStatus, looksLikeLoginWall, markLoginRequired, markSuccessfulRun } from '../profiles/profile-state.js';
+import { readJsonFile } from '../shared/fs.js';
+import { Semaphore } from '../shared/semaphore.js';
+import { WebFlowError } from '../shared/errors.js';
+import { translateSchema } from '../schema/translator.js';
+import { loadConfig, resolveBrowserModePreference, resolveBrowserVisibility } from '../config/webflow-config.js';
+import { classifyProviderSignal, deriveProviderKey, ProviderGate } from '../anti-block/provider-gate.js';
+import { loadFlowModule, loadFlowModuleFromSource } from './flow-loader.js';
+function defaultBrowserMode(capability) {
+    if (capability === 'cdp')
+        return 'cdp';
+    if (capability === 'managed' || capability === true)
+        return 'managed';
+    return 'none';
+}
+function supportedBrowserModes(capability, declared) {
+    if (declared && declared.length > 0) {
+        return [...new Set(declared)];
+    }
+    const fallback = defaultBrowserMode(capability);
+    return fallback === 'none' ? [] : [fallback];
+}
+function unsupportedBrowserModeError(flowName, requested, supported, source) {
+    return new WebFlowError('BROWSER_MODE_UNSUPPORTED', `Flow "${flowName}" cannot run in browser mode "${requested}" requested by ${source}. Supported mode(s): ${supported.length ? supported.join(', ') : 'none'}.`, { flow: flowName, requestedBrowserMode: requested, supportedBrowserModes: supported, source });
+}
+export function resolveBrowserMode(params) {
+    const defaultMode = defaultBrowserMode(params.capability);
+    const supported = supportedBrowserModes(params.capability, params.supportedBrowserModes);
+    if (params.requestedMode) {
+        if (!supported.includes(params.requestedMode)) {
+            throw unsupportedBrowserModeError(params.flowName, params.requestedMode, supported, 'one-off run options');
+        }
+        return params.requestedMode;
+    }
+    const flowOverride = params.config.browserMode.flows[params.flowName];
+    if (flowOverride) {
+        if (!supported.includes(flowOverride)) {
+            throw unsupportedBrowserModeError(params.flowName, flowOverride, supported, 'per-flow config');
+        }
+        return flowOverride;
+    }
+    const preference = resolveBrowserModePreference(params.config, params.flowName);
+    if (preference !== 'inherit' && supported.includes(preference)) {
+        return preference;
+    }
+    // Verification hook kept for compatibility: force legacy CDP-only flows through
+    // the managed path without editing flow code. Normal users should prefer config.
+    if (defaultMode === 'cdp' && process.env.WEBFLOW_CDP_AS_MANAGED === '1') {
+        return 'managed';
+    }
+    if (defaultMode !== 'none' && !supported.includes(defaultMode)) {
+        throw unsupportedBrowserModeError(params.flowName, defaultMode, supported, 'flow default');
+    }
+    return defaultMode;
+}
+/**
+ * Visibility precedence (see Project-Context/modules/browser-runner.md):
+ *   1. requiresVisibleBrowser (mandatory, e.g. strict providers) -> visible
+ *   2. --headed / worker --headed (options.headed)                -> visible
+ *   3. one-off browserVisibility option                            -> as set
+ *   4. config.browserVisibility.flows[flowName] (explicit override) -> as set
+ *   5. config.browserVisibility.default, if not 'inherit'           -> as set
+ *   6. capabilities.headless (legacy, per-flow code)                -> as set
+ *   7. fallback                                                     -> hidden
+ * `browser: 'cdp'` never reaches this function — it has no headless concept, it
+ * connects to an already-visible real Chrome by construction.
+ */
+export function resolveHeadless(params) {
+    if (params.requiresVisibleBrowser)
+        return false;
+    if (params.optionsHeaded)
+        return false;
+    if (params.optionsVisibility === 'visible')
+        return false;
+    if (params.optionsVisibility === 'hidden')
+        return true;
+    const visibility = resolveBrowserVisibility(params.config, params.flowName);
+    if (visibility === 'visible')
+        return false;
+    if (visibility === 'hidden')
+        return true;
+    return params.legacyHeadless ?? true;
+}
+/**
+ * Whether to nudge the calling agent to ask the human for a standing visibility
+ * preference for this specific flow. Never fires for flows with a mandatory-visible
+ * exception (nothing to configure), and never fires again once an explicit per-flow
+ * override already exists.
+ */
+export function shouldNudgeVisibility(params) {
+    if (params.requiresVisibleBrowser)
+        return false;
+    if (params.optionsVisibility)
+        return false;
+    return params.config.browserVisibility.flows[params.flowName] === undefined;
+}
+/**
+ * Defense-in-depth against a single worker process launching too many Chrome instances
+ * at once (audit item 5) — a modest default appropriate for an average machine, since
+ * each persistent-profile Chrome instance can realistically use several hundred MB.
+ * Complementary to ProviderGate above (which only serializes calls to the SAME
+ * provider/anti-block key): different providers still run fully in parallel without
+ * this. Jobs beyond this wait their turn rather than being rejected: nothing here is a
+ * synchronous HTTP caller, and the relay's own job timeout (20 min) comfortably
+ * tolerates a short wait for a slot.
+ */
+const DEFAULT_MAX_CONCURRENT_BROWSERS = 3;
+function resolveMaxConcurrentBrowsers() {
+    const raw = process.env.WEBFLOW_MAX_CONCURRENT_BROWSERS?.trim();
+    if (!raw)
+        return DEFAULT_MAX_CONCURRENT_BROWSERS;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_CONCURRENT_BROWSERS;
+}
+export class FlowRunner {
+    projectRoot;
+    profileManager;
+    providerGate = new ProviderGate();
+    browserSlots;
+    constructor(projectRoot, profileManager) {
+        this.projectRoot = projectRoot;
+        this.profileManager = profileManager ?? new ProfileManager(projectRoot);
+        this.browserSlots = new Semaphore(resolveMaxConcurrentBrowsers());
+    }
+    async compile(definition) {
+        const schemaJson = await readJsonFile(definition.schemaFile);
+        const schema = translateSchema(schemaJson);
+        return { definition, schema };
+    }
+    async run(definition, input, options) {
+        const schema = options?.schema ?? (await this.compile(definition)).schema;
+        return this.executeModule(definition.name, definition.dir, input, schema, () => loadFlowModule(definition.entryFile), options);
+    }
+    /**
+     * Executes a flow whose code was NOT loaded from this machine's disk (RFC 0001,
+     * Fase 3): the relay bundles and pushes the flow's source per job so that no
+     * automation code — free or paid — ever persists on the worker's machine. Reuses
+     * every bit of session/profile/error-handling logic that `run()` uses; the only
+     * difference is where the `FlowModule` comes from.
+     */
+    async runRemote(flowName, code, schemaJson, input, options, expectedCapabilities) {
+        const schema = options?.schema ?? translateSchema(schemaJson);
+        return this.executeModule(flowName, this.projectRoot, input, schema, () => loadFlowModuleFromSource(code, flowName), options, expectedCapabilities);
+    }
+    async executeModule(flowName, flowDir, input, schema, loadModule, options, expectedCapabilities) {
+        let session;
+        // Hoisted out of the try block so the catch's login-wall check (below) can see them
+        // even when the failure happens after they were assigned but before the flow returns.
+        let profile;
+        let requiresLogin = false;
+        let loginUrl;
+        let providerKey;
+        let antiBlockPolicy;
+        let releaseProvider;
+        let acquiredBrowserSlot = false;
+        try {
+            const parsedInput = await schema.zodSchema.parseAsync(input);
+            const module = await loadModule();
+            if (expectedCapabilities && stableJson(module.capabilities ?? {}) !== stableJson(expectedCapabilities)) {
+                throw new WebFlowError('FLOW_CAPABILITIES_MISMATCH', `Flow "${flowName}" exports capabilities that differ from its signed release metadata.`);
+            }
+            const inputProfile = parsedInput?.profile;
+            const profileName = options?.profileName
+                ?? (typeof inputProfile === 'string' && inputProfile.length > 0 ? inputProfile : undefined)
+                ?? module.capabilities?.profile;
+            const config = await loadConfig();
+            const browserMode = resolveBrowserMode({
+                capability: module.capabilities?.browser,
+                supportedBrowserModes: module.capabilities?.supportedBrowserModes,
+                requestedMode: options?.browserMode,
+                flowName,
+                config
+            });
+            if (browserMode !== 'none') {
+                antiBlockPolicy = module.capabilities?.antiBlock;
+                providerKey = deriveProviderKey(flowName, module.capabilities);
+                releaseProvider = await this.providerGate.enter(providerKey, antiBlockPolicy);
+            }
+            requiresLogin = module.capabilities?.requiresLogin ?? false;
+            loginUrl = module.capabilities?.startUrl && module.capabilities.startUrl !== 'about:blank'
+                ? module.capabilities.startUrl
+                : undefined;
+            // Multi-agent (Fase 5): WEBFLOW_PROFILE_INSTANCE makes this run use a per-instance
+            // clone of the logged-in profile, since one Chrome user-data-dir = one process.
+            // Off by default, so a single agent reuses the shared base profile.
+            const instanceEnv = process.env.WEBFLOW_PROFILE_INSTANCE?.trim();
+            const profileOptions = instanceEnv ? { instance: instanceEnv } : {};
+            // Only browser flows need a real on-disk profile directory; non-browser flows
+            // just resolve their identity so we don't create empty dirs in the global store.
+            const resolvedProfile = await this.profileManager.resolve(profileName, flowName, profileOptions);
+            const status = browserMode !== 'none' && requiresLogin
+                ? await getProfileStatus(resolvedProfile, { loginUrl })
+                : undefined;
+            if (status && status.probablyValid === false) {
+                if (status.status === 'missing') {
+                    await markLoginRequired(resolvedProfile, flowName);
+                }
+                throw new WebFlowError('LOGIN_REQUIRED', `Flow "${flowName}" requires a logged-in session for profile "${resolvedProfile.id}", but none was found. Run "${status.setupCommand}" on this machine first.`, {
+                    flow: flowName,
+                    profile: resolvedProfile.id,
+                    profileStatus: status.status,
+                    loginUrl,
+                    setupCommand: status.setupCommand
+                });
+            }
+            profile = browserMode !== 'none'
+                ? await this.profileManager.ensure(profileName, flowName, profileOptions)
+                : resolvedProfile;
+            if (browserMode === 'managed') {
+                await this.browserSlots.acquire();
+                acquiredBrowserSlot = true;
+                const { launchBrowserSession } = await import('./browser-session.js');
+                session = await launchBrowserSession({
+                    userDataDir: profile.dir,
+                    headless: resolveHeadless({
+                        requiresVisibleBrowser: module.capabilities?.requiresVisibleBrowser,
+                        optionsHeaded: options?.headed,
+                        optionsVisibility: options?.browserVisibility,
+                        legacyHeadless: module.capabilities?.headless,
+                        flowName,
+                        config
+                    }),
+                    startUrl: module.capabilities?.startUrl,
+                    channel: module.capabilities?.channel,
+                    stealth: module.capabilities?.stealth
+                });
+            }
+            else if (browserMode === 'cdp') {
+                await this.browserSlots.acquire();
+                acquiredBrowserSlot = true;
+                const { connectCdpSession } = await import('./cdp-session.js');
+                const cdpInput = parsedInput;
+                session = await connectCdpSession({
+                    userDataDir: cdpInput?.userDataDir ?? profile.dir,
+                    startUrl: module.capabilities?.startUrl,
+                    cdpUrl: cdpInput?.cdpUrl,
+                    chromePath: cdpInput?.chromePath
+                });
+            }
+            const result = await module.run({
+                projectRoot: this.projectRoot,
+                flowName,
+                flowDir,
+                profile,
+                browser: session?.context,
+                page: session?.page
+            }, parsedInput);
+            if (providerKey)
+                await this.providerGate.record(providerKey, 'ok', antiBlockPolicy);
+            if (requiresLogin) {
+                await markSuccessfulRun(profile, flowName);
+            }
+            const visibilityNudge = browserMode === 'managed'
+                && shouldNudgeVisibility({ requiresVisibleBrowser: module.capabilities?.requiresVisibleBrowser, optionsVisibility: options?.browserVisibility, flowName, config })
+                ? 'This flow just ran using the current browser-visibility setting. If the user wants this specific flow to always run visible (see Chrome working) or always hidden (background), ask them, then call set_browser_visibility with scope:"flow".'
+                : undefined;
+            return { ok: true, result, profile, visibilityNudge };
+        }
+        catch (error) {
+            if (error instanceof WebFlowError && error.code === 'PROVIDER_COOLDOWN') {
+                const details = error.details;
+                return {
+                    ok: false,
+                    error: buildSelfHealingPayload(error, {
+                        code: 'PROVIDER_COOLDOWN',
+                        flow: flowName,
+                        retryable: false,
+                        suggestedAction: `Do not retry before ${details?.retryAfter ?? 'the provider cooldown expires'}.`,
+                    })
+                };
+            }
+            const providerSignal = classifyProviderSignal(error, antiBlockPolicy?.tripOnPageNotFound);
+            if (providerKey)
+                await this.providerGate.record(providerKey, providerSignal, antiBlockPolicy);
+            if (error instanceof ZodError) {
+                return {
+                    ok: false,
+                    error: buildSelfHealingPayload(error, {
+                        code: 'FLOW_VALIDATION_FAILED',
+                        flow: flowName,
+                        retryable: false,
+                        suggestedAction: 'Provide arguments matching schema.json.',
+                        validationErrors: error.issues.map((issue) => ({ path: issue.path.join('.'), message: issue.message }))
+                    })
+                };
+            }
+            if (error instanceof WebFlowError && error.code === 'LOGIN_REQUIRED') {
+                const details = error.details;
+                return {
+                    ok: false,
+                    error: buildSelfHealingPayload(error, {
+                        code: 'LOGIN_REQUIRED',
+                        flow: flowName,
+                        profile: details?.profile,
+                        profileStatus: details?.profileStatus,
+                        loginUrl: details?.loginUrl,
+                        setupCommand: details?.setupCommand,
+                        retryable: false,
+                        suggestedAction: 'Ask the user to run the setup command, log in in the opened Chrome window, close it, then retry the flow.'
+                    })
+                };
+            }
+            if (error instanceof WebFlowError && error.code === 'BROWSER_MODE_UNSUPPORTED') {
+                return {
+                    ok: false,
+                    error: buildSelfHealingPayload(error, {
+                        code: 'BROWSER_MODE_UNSUPPORTED',
+                        flow: flowName,
+                        retryable: false,
+                        suggestedAction: 'Choose a browser mode supported by this flow, or update the flow capabilities only after verifying it works in that mode.'
+                    })
+                };
+            }
+            const context = error;
+            let autoSnapshot;
+            if (!context.domSnapshot && session?.page) {
+                const { captureDomSnapshot } = await import('./browser-session.js');
+                autoSnapshot = await captureDomSnapshot(session.page);
+            }
+            const failureUrl = context.url ?? autoSnapshot?.url;
+            // A profile that was `verified`/`setup_completed` (dir exists, prior good run) can
+            // still go stale — the site expires the session and redirects to its login wall
+            // mid-flow. Flows already detect this by hand (gemini-prompt, chatgpt-prompt, twitter,
+            // ...) and throw a plain Error; without this check that error just fell into the
+            // generic FLOW_STEP_FAILED path below and the profile kept reporting probablyValid:
+            // true forever, so the agent had no structured signal to ask for a fresh login.
+            if (requiresLogin && profile && looksLikeLoginWall(failureUrl)) {
+                await markLoginRequired(profile, flowName);
+                const setupCommand = buildProfileLoginCommand(profile.id, loginUrl);
+                return {
+                    ok: false,
+                    error: buildSelfHealingPayload(error, {
+                        code: 'LOGIN_REQUIRED',
+                        flow: flowName,
+                        profile: profile.id,
+                        profileStatus: 'login_required',
+                        loginUrl,
+                        setupCommand,
+                        retryable: false,
+                        suggestedAction: 'Ask the user to run the setup command, log in in the opened Chrome window, close it, then retry the flow.'
+                    })
+                };
+            }
+            return {
+                ok: false,
+                error: buildSelfHealingPayload(error, {
+                    code: 'FLOW_STEP_FAILED',
+                    flow: flowName,
+                    retryable: providerSignal === 'unknown' ? context.retryable : false,
+                    suggestedAction: context.suggestedAction ?? 'Inspect the step context and retry after fixing the flow or inputs.',
+                    step: context.step,
+                    url: failureUrl,
+                    domSnapshot: context.domSnapshot ?? (autoSnapshot ? { html: autoSnapshot.html, text: autoSnapshot.text } : undefined)
+                })
+            };
+        }
+        finally {
+            if (session) {
+                await session.close();
+            }
+            releaseProvider?.();
+            if (acquiredBrowserSlot) {
+                this.browserSlots.release();
+            }
+        }
+    }
+}
+function stableJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}

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

@@ -0,0 +1,112 @@
+import type { BrowserContext, Page } from 'playwright-core';
+import type { CompiledSchema } from '../schema/types.js';
+import type { ResolvedProfile } from '../profiles/profile-manager.js';
+import type { SelfHealingPayload } from '../errors/self-healing.js';
+import type { AntiBlockPolicy } from '../anti-block/provider-gate.js';
+/**
+ * How a flow drives the browser:
+ * - `true`/`'managed'`: Playwright-managed persistent profile (default, clean, isolated).
+ * - `'cdp'`: attach to a real Chrome over CDP (for strict providers like Google AI Studio / Adobe).
+ * - falsy: no browser.
+ */
+export type BrowserMode = 'managed' | 'cdp';
+export type BrowserCapability = boolean | BrowserMode;
+export interface FlowCapabilities {
+    browser?: BrowserCapability;
+    headless?: boolean;
+    startUrl?: string;
+    channel?: string;
+    stealth?: boolean;
+    profile?: string;
+    /**
+     * Browser modes this flow is known to support. If omitted, the runner assumes the
+     * flow supports only its default mode from `browser` (managed for true/'managed',
+     * cdp for 'cdp'). Declare ['managed', 'cdp'] only after confirming the flow uses
+     * the central ctx.page/ctx.browser contract and works in both launch modes.
+     */
+    supportedBrowserModes?: BrowserMode[];
+    /**
+     * Declares whether this flow needs a previously-logged-in session to work (vs. a
+     * plain/anonymous browser or no browser at all). Must be explicit, not inferred
+     * from `profile`/`startUrl`, so `webflow doctor` and the worker catalog can rely on
+     * it instead of every caller guessing. Flows with `requiresLogin: true` must not use
+     * `startUrl: 'about:blank'` (contradiction) and should declare `profile` (falls back
+     * to `<flow>-default` otherwise, which is almost always wrong for a flow that needs
+     * a real account). Defaults to `false` when omitted.
+     */
+    requiresLogin?: boolean;
+    /**
+     * Hard requirement that this flow's browser be visible (not headless) — for providers
+     * whose automation detection breaks under a headless Chrome. Overrides the user's
+     * config.browserVisibility entirely (both the global default and any per-flow override),
+     * the same way `browser: 'cdp'` is always visible by construction. This is an escape
+     * hatch for technical correctness, not a user preference — leave it unset and let config
+     * decide whenever headless genuinely works, so the person running the worker keeps
+     * control over what they see.
+     */
+    requiresVisibleBrowser?: boolean;
+    /**
+     * Sector this flow belongs to (top of the catalog-browsing hierarchy: sector -> service ->
+     * flow, see `browse_catalog` in the relay). Must be explicit, not inferred from the flow's
+     * name or description, and must be a key present in the canonical `taxonomy.json` registry
+     * shipped with this package — `webflow doctor` and `relay/scripts/sync-catalog.ts` both
+     * reject an unknown value instead of silently minting a near-duplicate sector once the
+     * catalog has hundreds/thousands of flows. Omit only while a flow is still unclassified.
+     */
+    category?: string;
+    /**
+     * Which website/service within `category` this flow automates (e.g. "chatgpt" inside sector
+     * "productividad-e-ia"). Must be a service key registered under that sector in `taxonomy.json`.
+     * For a flow with no single canonical site (a multi-source scraper), use whichever source it
+     * defaults to if it has one, or a descriptive generic bucket if it genuinely aggregates
+     * several sources with none dominant. Requires `category` to also be set.
+     */
+    service?: string;
+    /** Provider-level pacing and circuit-breaker overrides. Defaults remain conservative. */
+    antiBlock?: AntiBlockPolicy;
+}
+export interface FlowContext {
+    projectRoot: string;
+    flowName: string;
+    flowDir: string;
+    profile: ResolvedProfile;
+    browser?: BrowserContext;
+    page?: Page;
+}
+export interface FlowModule {
+    run(ctx: FlowContext, input: unknown): Promise<unknown>;
+    capabilities?: FlowCapabilities;
+}
+export interface FlowDefinition {
+    name: string;
+    dir: string;
+    entryFile: string;
+    schemaFile: string;
+}
+export interface FlowDiscoveryResult {
+    flows: FlowDefinition[];
+    diagnostics: string[];
+}
+export interface FlowExecutionSuccess {
+    ok: true;
+    result: unknown;
+    profile: ResolvedProfile;
+    /**
+     * Present only the first time a `managed`-browser flow runs with no explicit
+     * per-flow visibility override in config.browserVisibility.flows yet, and only
+     * when the flow has no mandatory-visible exception (`requiresVisibleBrowser` /
+     * `browser: 'cdp'`) — those must never suggest a visibility change. Callers
+     * (relay's mcp-endpoint.ts) surface this as an `askUser` hint so the agent asks
+     * the human once, then calls set_browser_visibility instead of assuming.
+     */
+    visibilityNudge?: string;
+}
+export interface FlowExecutionFailure {
+    ok: false;
+    error: SelfHealingPayload;
+}
+export type FlowExecutionResult = FlowExecutionSuccess | FlowExecutionFailure;
+export interface RunnableFlow {
+    definition: FlowDefinition;
+    schema: CompiledSchema;
+}

package/dist/src/runner/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/schema/translator.d.ts

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+import type { CompiledSchema, SupportedSchema } from './types.js';
+export declare function compileZodSchema(schema: SupportedSchema): z.ZodTypeAny;
+export declare function normalizeSchema(schema: unknown): SupportedSchema;
+export declare function translateSchema(schema: unknown): CompiledSchema;

package/dist/src/schema/translator.js

@@ -0,0 +1,104 @@
+import { z } from 'zod';
+import { WebFlowError } from '../shared/errors.js';
+/**
+ * Applied when a flow's schema.json doesn't declare its own maxLength/maxItems, so
+ * every flow gets a safety net against unbounded input without hand-editing every
+ * JSON file (audit item 5). A flow only needs an explicit value if it legitimately
+ * needs more than this.
+ */
+const DEFAULT_MAX_STRING_LENGTH = 5000;
+const DEFAULT_MAX_ARRAY_ITEMS = 50;
+function isSupportedSchema(input) {
+    return typeof input === 'object' && input !== null && 'type' in input;
+}
+function withMetadata(schema, descriptor) {
+    let next = schema;
+    if (descriptor.description) {
+        next = next.describe(descriptor.description);
+    }
+    if (descriptor.default !== undefined) {
+        next = next.default(descriptor.default);
+    }
+    return next;
+}
+function compileArray(schema) {
+    return withMetadata(z.array(compileZodSchema(schema.items)).max(schema.maxItems ?? DEFAULT_MAX_ARRAY_ITEMS), schema);
+}
+function compileObject(schema) {
+    const shape = {};
+    const required = new Set(schema.required ?? []);
+    for (const [key, value] of Object.entries(schema.properties ?? {})) {
+        let compiled = compileZodSchema(value);
+        if (!required.has(key) && value.default === undefined) {
+            compiled = compiled.optional();
+        }
+        shape[key] = compiled;
+    }
+    return withMetadata(z.object(shape).strict(), schema);
+}
+export function compileZodSchema(schema) {
+    switch (schema.type) {
+        case 'object':
+            return compileObject(schema);
+        case 'array':
+            return compileArray(schema);
+        case 'string': {
+            // An enum is already bounded to its fixed value set, so maxLength doesn't apply there.
+            const base = schema.enum ? z.enum(schema.enum) : z.string().max(schema.maxLength ?? DEFAULT_MAX_STRING_LENGTH);
+            return withMetadata(base, schema);
+        }
+        case 'number':
+            return withMetadata(z.number(), schema);
+        case 'boolean':
+            return withMetadata(z.boolean(), schema);
+        default:
+            throw new WebFlowError('UNSUPPORTED_SCHEMA', `Unsupported schema type: ${schema.type ?? 'unknown'}`);
+    }
+}
+export function normalizeSchema(schema) {
+    if (!isSupportedSchema(schema)) {
+        throw new WebFlowError('INVALID_SCHEMA', 'schema.json must be a supported JSON object schema.');
+    }
+    switch (schema.type) {
+        case 'object':
+            return {
+                type: 'object',
+                description: schema.description,
+                default: schema.default,
+                required: schema.required,
+                properties: Object.fromEntries(Object.entries(schema.properties ?? {}).map(([key, value]) => [key, normalizeSchema(value)]))
+            };
+        case 'array':
+            if (!('items' in schema) || !schema.items) {
+                throw new WebFlowError('INVALID_SCHEMA', 'Array schema requires an items field.');
+            }
+            return {
+                type: 'array',
+                description: schema.description,
+                default: schema.default,
+                items: normalizeSchema(schema.items),
+                maxItems: typeof schema.maxItems === 'number' ? schema.maxItems : undefined
+            };
+        case 'string':
+            return {
+                type: 'string',
+                description: schema.description,
+                default: schema.default,
+                enum: Array.isArray(schema.enum) ? schema.enum.map(String) : undefined,
+                maxLength: typeof schema.maxLength === 'number' ? schema.maxLength : undefined
+            };
+        case 'number':
+            return { type: 'number', description: schema.description, default: schema.default };
+        case 'boolean':
+            return { type: 'boolean', description: schema.description, default: schema.default };
+        default:
+            throw new WebFlowError('UNSUPPORTED_SCHEMA', `Unsupported schema type: ${schema.type ?? 'unknown'}`);
+    }
+}
+export function translateSchema(schema) {
+    const normalized = normalizeSchema(schema);
+    return {
+        jsonSchema: normalized,
+        zodSchema: compileZodSchema(normalized)
+    };
+}

package/dist/src/schema/types.d.ts

@@ -0,0 +1,32 @@
+import type { ZodTypeAny } from 'zod';
+export type SupportedSchema = ObjectSchema | StringSchema | NumberSchema | BooleanSchema | ArraySchema;
+interface BaseSchema {
+    description?: string;
+    default?: unknown;
+}
+export interface ObjectSchema extends BaseSchema {
+    type: 'object';
+    properties?: Record<string, SupportedSchema>;
+    required?: string[];
+}
+export interface StringSchema extends BaseSchema {
+    type: 'string';
+    enum?: string[];
+    maxLength?: number;
+}
+export interface NumberSchema extends BaseSchema {
+    type: 'number';
+}
+export interface BooleanSchema extends BaseSchema {
+    type: 'boolean';
+}
+export interface ArraySchema extends BaseSchema {
+    type: 'array';
+    items: SupportedSchema;
+    maxItems?: number;
+}
+export interface CompiledSchema {
+    zodSchema: ZodTypeAny;
+    jsonSchema: SupportedSchema;
+}
+export {};

package/dist/src/schema/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/security/flow-approvals.d.ts

@@ -0,0 +1,34 @@
+import { type VerifiedRemoteFlow } from './flow-release.js';
+export interface FlowApproval {
+    trustDomain: string;
+    flowName: string;
+    flowDigest: string;
+    sequence: number;
+    version: string;
+    releaseId: string;
+    keyId: string;
+    approvedAt: string;
+    updatedAt: string;
+}
+export interface PendingFlowApproval {
+    trustDomain: string;
+    flowName: string;
+    flowDigest: string;
+    sequence: number;
+    version: string;
+    releaseId: string;
+    keyId: string;
+    receivedAt: string;
+}
+export type FlowApprovalAssessment = {
+    status: 'approved';
+    approval: FlowApproval;
+} | {
+    status: 'pending';
+    pending: PendingFlowApproval;
+};
+export declare function assessAndRecordPending(verified: VerifiedRemoteFlow): Promise<FlowApprovalAssessment>;
+export declare function listPending(): Promise<PendingFlowApproval[]>;
+export declare function approvePending(flowName: string, trustDomain?: string, expected?: Pick<PendingFlowApproval, 'flowDigest' | 'releaseId' | 'sequence'>): Promise<FlowApproval>;
+export declare function revokeApproval(flowName: string, trustDomain?: string, expected?: Pick<FlowApproval, 'flowDigest' | 'releaseId' | 'sequence'>): Promise<boolean>;
+export declare function listApprovals(): Promise<FlowApproval[]>;