@firenet-designs/fnd-cli 2.3.3 → 2.6.0

package/dist/lib/kv-flag.js

@@ -0,0 +1,75 @@
+const fieldMeta = (field) => (field.meta() ?? {});
+const isOptional = (field) => field.def.type === 'default' || field.def.type === 'optional';
+/** Unwrap default/optional/preprocess wrappers down to the schema describing the value. */
+const unwrap = (field) => {
+    const { def } = field;
+    if (def.type === 'default' || def.type === 'optional') {
+        return unwrap(def.innerType);
+    }
+    if (def.type === 'pipe') {
+        return unwrap(def.out);
+    }
+    return field;
+};
+/** The <placeholder> for a field's value: explicit hint meta, enum options, or "value". */
+const fieldHint = (field) => {
+    const { hint } = fieldMeta(field);
+    if (hint)
+        return hint;
+    const inner = unwrap(field);
+    if (inner.def.type === 'enum') {
+        return Object.values(inner.def.entries).join('|');
+    }
+    return 'value';
+};
+/** Usage string for the schema, required keys first: `a=<...>,b=<...>[,c=<...>]`. */
+export const kvUsage = (schema) => {
+    const fields = Object.entries(schema.shape);
+    const required = fields.filter(([, f]) => !isOptional(f));
+    const optional = fields.filter(([, f]) => isOptional(f));
+    const pair = ([key, field]) => `${key}=<${fieldHint(field)}>`;
+    return required.map((f) => pair(f)).join(',') + optional.map((f) => `[,${pair(f)}]`).join('');
+};
+/** Example flag value built from each field's example meta (falls back to its hint), required keys first. */
+export const kvExample = (schema, opts) => {
+    const fields = Object.entries(schema.shape).filter(([, field]) => !(opts?.requiredOnly && isOptional(field)));
+    return [...fields.filter(([, f]) => !isOptional(f)), ...fields.filter(([, f]) => isOptional(f))]
+        .map(([key, field]) => `${key}=${fieldMeta(field).example ?? fieldHint(field)}`)
+        .join(',');
+};
+/**
+ * Parse a key=value flag string against the schema. Keys are case-insensitive
+ * and order-independent; unknown keys, duplicate keys, and missing required
+ * keys are hard errors naming the flag and its usage.
+ */
+export const parseKvFlag = (flag, raw, schema) => {
+    const usage = `${flag} takes comma-separated key=value pairs: ${kvUsage(schema)}`;
+    const known = Object.keys(schema.shape);
+    const pairs = new Map();
+    for (const part of raw.trim().split(',')) {
+        const eq = part.indexOf('=');
+        if (eq === -1) {
+            throw new Error(`${usage} (got "${raw}")`);
+        }
+        const key = part.slice(0, eq).trim().toLowerCase();
+        if (!known.includes(key)) {
+            throw new Error(`${flag} has no "${key}" option. ${usage}`);
+        }
+        if (pairs.has(key)) {
+            throw new Error(`${flag} "${key}" was given more than once (got "${raw}")`);
+        }
+        pairs.set(key, part.slice(eq + 1).trim());
+    }
+    for (const key of known) {
+        if (!isOptional(schema.shape[key]) && !pairs.has(key)) {
+            throw new Error(`${flag} needs "${key}". ${usage}`);
+        }
+    }
+    const result = schema.safeParse(Object.fromEntries(pairs));
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const at = issue.path.join('.');
+        throw new Error(`${flag}${at ? ` ${at}` : ''}: ${issue.message}. ${usage}`);
+    }
+    return result.data;
+};

package/dist/lib/rpc.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { PortPair } from './workspace.js';
+/**
+ * The --rpc local-command server.
+ *
+ * Topology: this machine (the one that ran `fnd workspace`) runs a tiny MCP
+ * server — Streamable HTTP transport, implemented on node:http with no
+ * dependencies — bound to 127.0.0.1:<local>. The workspace's `ssh -R` reverse
+ * tunnel exposes it on the REMOTE at 127.0.0.1:<remote>, where the `claude` CLI
+ * registers it as an HTTP MCP server. When the AI on the remote calls the
+ * `run_local_command` tool, the command executes HERE, on the calling machine,
+ * under the shell chosen in the flag.
+ *
+ * The server binds loopback only; the sole way in from outside is the reverse
+ * tunnel, which lives exactly as long as the ssh session.
+ */
+declare const ShellSchema: z.ZodEnum<{
+    zsh: "zsh";
+    bash: "bash";
+    batch: "batch";
+    powershell: "powershell";
+    sh: "sh";
+}>;
+export declare const RPC_SHELLS: ("zsh" | "bash" | "batch" | "powershell" | "sh")[];
+export type RpcShell = z.infer<typeof ShellSchema>;
+/** Usage and example strings for the --rpc flag, derived from the schema. */
+export declare const RPC_FLAG_USAGE: string;
+export declare const RPC_FLAG_EXAMPLES: {
+    full: string;
+    required: string;
+};
+export interface RpcConfig {
+    /** local = port the server binds on this machine; remote = port opened on the workspace host via `ssh -R`. */
+    ports: PortPair;
+    /** Whether the shell loads its startup files (rc/profile). POSIX shells run with -i, powershell without -NoProfile. */
+    profile: boolean;
+    /** Shell used to execute commands on this machine. */
+    shell: RpcShell;
+}
+/** Handle for a running RPC server. */
+export interface RpcServer {
+    close: () => Promise<void>;
+}
+export declare const RPC_TOOL_NAME = "run_local_command";
+/**
+ * The shell `fnd workspace` was called from: the parent process when it is a
+ * supported shell, else $SHELL, else undefined (e.g. invoked from a script).
+ */
+export declare const detectCallingShell: () => RpcShell | undefined;
+/**
+ * Parse the --rpc value: comma-separated key=value pairs per RpcFlagSchema.
+ *   port=<port> | port=<remote>:<local> — required; `local` is this machine
+ *     (where commands run), `remote` the port opened on the workspace host.
+ *     The single-port form uses the same port on both ends.
+ *   shell=<bash|batch|powershell|sh|zsh> — optional, defaults to the shell
+ *     `fnd workspace` was called from.
+ *   profile=<true|1|false|0> — optional, default true: the shell loads its
+ *     startup files (rc/profile), so tools like nvm are available.
+ */
+export declare const parseRpcFlag: (raw: string) => RpcConfig;
+/** True if the chosen shell is runnable on this machine. */
+export declare const hasLocalShell: (shell: RpcShell, profile: boolean) => boolean;
+/**
+ * Start the local RPC (MCP) server on 127.0.0.1:<ports.local>. Commands execute
+ * with `cwd` as their working directory — the local side of the workspace sync.
+ * Resolves once the port is bound; rejects if binding fails (e.g. port in use).
+ */
+export declare const startRpcServer: (config: RpcConfig, cwd: string) => Promise<RpcServer>;
+export {};

package/dist/lib/rpc.js

@@ -0,0 +1,313 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { createServer } from 'node:http';
+import { z } from 'zod';
+import { kvExample, kvUsage, parseKvFlag } from './kv-flag.js';
+import { parsePortPair } from './workspace.js';
+/**
+ * The --rpc local-command server.
+ *
+ * Topology: this machine (the one that ran `fnd workspace`) runs a tiny MCP
+ * server — Streamable HTTP transport, implemented on node:http with no
+ * dependencies — bound to 127.0.0.1:<local>. The workspace's `ssh -R` reverse
+ * tunnel exposes it on the REMOTE at 127.0.0.1:<remote>, where the `claude` CLI
+ * registers it as an HTTP MCP server. When the AI on the remote calls the
+ * `run_local_command` tool, the command executes HERE, on the calling machine,
+ * under the shell chosen in the flag.
+ *
+ * The server binds loopback only; the sole way in from outside is the reverse
+ * tunnel, which lives exactly as long as the ssh session.
+ */
+const ShellSchema = z.enum(['bash', 'batch', 'powershell', 'sh', 'zsh']);
+export const RPC_SHELLS = ShellSchema.options;
+const RpcFlagSchema = z.object({
+    port: z
+        .string()
+        .transform((v) => parsePortPair(v, '--rpc'))
+        .meta({ example: '7777:7700', hint: 'port|remote:local' }),
+    profile: z
+        .stringbool({ falsy: ['false', '0'], truthy: ['true', '1'] })
+        .default(true)
+        .meta({ example: 'false', hint: 'true|1|false|0' }),
+    shell: z
+        .preprocess((v) => String(v).toLowerCase(), ShellSchema)
+        .optional()
+        .meta({ example: 'zsh' }),
+});
+/** Usage and example strings for the --rpc flag, derived from the schema. */
+export const RPC_FLAG_USAGE = kvUsage(RpcFlagSchema);
+export const RPC_FLAG_EXAMPLES = {
+    full: kvExample(RpcFlagSchema),
+    required: kvExample(RpcFlagSchema, { requiredOnly: true }),
+};
+export const RPC_TOOL_NAME = 'run_local_command';
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const MAX_TIMEOUT_MS = 30 * 60 * 1000;
+const MAX_OUTPUT_CHARS = 200_000;
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+/** Map a process name or path to a supported shell, if it is one. */
+const asRpcShell = (name) => {
+    if (!name)
+        return undefined;
+    // Basename, minus the login-shell dash ("-zsh") and Windows ".exe" suffix.
+    const base = name
+        .split(/[/\\]/)
+        .pop()
+        .toLowerCase()
+        .replace(/^-/, '')
+        .replace(/\.exe$/, '');
+    if (base === 'cmd')
+        return 'batch';
+    if (base === 'pwsh')
+        return 'powershell';
+    const parsed = ShellSchema.safeParse(base);
+    return parsed.success ? parsed.data : undefined;
+};
+/** Name of the process that spawned us, when discoverable. */
+const parentProcessName = () => {
+    const { ppid } = process;
+    if (!ppid)
+        return undefined;
+    const probe = process.platform === 'win32'
+        ? spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', `(Get-Process -Id ${ppid}).ProcessName`], { encoding: 'utf8', windowsHide: true })
+        : spawnSync('ps', ['-p', String(ppid), '-o', 'comm='], { encoding: 'utf8' });
+    if (probe.error || probe.status !== 0)
+        return undefined;
+    return probe.stdout.trim() || undefined;
+};
+/**
+ * The shell `fnd workspace` was called from: the parent process when it is a
+ * supported shell, else $SHELL, else undefined (e.g. invoked from a script).
+ */
+export const detectCallingShell = () => asRpcShell(parentProcessName()) ?? asRpcShell(process.env.SHELL);
+/**
+ * Parse the --rpc value: comma-separated key=value pairs per RpcFlagSchema.
+ *   port=<port> | port=<remote>:<local> — required; `local` is this machine
+ *     (where commands run), `remote` the port opened on the workspace host.
+ *     The single-port form uses the same port on both ends.
+ *   shell=<bash|batch|powershell|sh|zsh> — optional, defaults to the shell
+ *     `fnd workspace` was called from.
+ *   profile=<true|1|false|0> — optional, default true: the shell loads its
+ *     startup files (rc/profile), so tools like nvm are available.
+ */
+export const parseRpcFlag = (raw) => {
+    const parsed = parseKvFlag('--rpc', raw, RpcFlagSchema);
+    const shell = parsed.shell ?? detectCallingShell();
+    if (!shell) {
+        throw new Error(`--rpc could not detect the calling shell; pass shell=<${RPC_SHELLS.join('|')}> explicitly.`);
+    }
+    return { ports: parsed.port, profile: parsed.profile, shell };
+};
+/** How to invoke the chosen shell for a one-shot command string. */
+const shellInvocation = (shell, command, profile) => {
+    switch (shell) {
+        case 'batch': {
+            // /d skips the AutoRun registry commands — cmd's closest analog to a profile.
+            return { args: [...(profile ? [] : ['/d']), '/s', '/c', command], bin: 'cmd.exe' };
+        }
+        case 'powershell': {
+            return { args: [...(profile ? [] : ['-NoProfile']), '-NonInteractive', '-Command', command], bin: 'powershell' };
+        }
+        default: {
+            // -i: interactive, so rc files (~/.bashrc, ~/.zshrc) are sourced and tools
+            // that hook in there (nvm, rbenv, …) work without manual sourcing.
+            return { args: [...(profile ? ['-i'] : []), '-c', command], bin: shell };
+        }
+    }
+};
+/** True if the chosen shell is runnable on this machine. */
+export const hasLocalShell = (shell, profile) => {
+    const { args, bin } = shellInvocation(shell, 'exit 0', profile);
+    const result = spawnSync(bin, args, { stdio: 'ignore' });
+    return !result.error && result.status === 0;
+};
+/** Append a chunk to captured output unless the cap is already reached. */
+const appendCapped = (current, chunk) => current.length >= MAX_OUTPUT_CHARS ? current : current + chunk.toString();
+/**
+ * Interactive bash/dash on a non-TTY stdin print job-control warnings on every
+ * run; drop them so they don't clutter the stderr the model sees.
+ */
+const stripInteractiveShellNoise = (stderr) => stderr
+    .replaceAll(/^bash: cannot set terminal process group \(-?\d+\):[^\n]*\n?/gm, '')
+    .replaceAll(/^bash: no job control in this shell\n?/gm, '')
+    .replaceAll(/^sh: \d+: can't access tty; job control turned off\n?/gm, '');
+/** Execute a command on this machine under the configured shell, capturing output. */
+const runLocalCommand = (config, command, cwd, timeoutMs) => new Promise((resolve) => {
+    const { args, bin } = shellInvocation(config.shell, command, config.profile);
+    const child = spawn(bin, args, { cwd, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    child.stdout.on('data', (chunk) => {
+        stdout = appendCapped(stdout, chunk);
+    });
+    child.stderr.on('data', (chunk) => {
+        stderr = appendCapped(stderr, chunk);
+    });
+    const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill('SIGKILL');
+    }, timeoutMs);
+    child.once('error', (error) => {
+        clearTimeout(timer);
+        resolve({ exitCode: null, stderr: `Could not spawn ${bin}: ${error.message}`, stdout: '', timedOut: false });
+    });
+    child.once('close', (code) => {
+        clearTimeout(timer);
+        resolve({ exitCode: code, stderr: stripInteractiveShellNoise(stderr), stdout, timedOut });
+    });
+});
+/** Clip captured output at the cap, marking the truncation. */
+const clip = (value) => value.length >= MAX_OUTPUT_CHARS ? `${value.slice(0, MAX_OUTPUT_CHARS)}\n[output truncated]` : value;
+/** Render a command result as the text block returned to the model. */
+const formatResult = (result) => {
+    const status = result.timedOut ? 'killed (timed out)' : `exit code ${result.exitCode ?? 'unknown'}`;
+    return [
+        status,
+        '--- stdout ---',
+        clip(result.stdout) || '(empty)',
+        '--- stderr ---',
+        clip(result.stderr) || '(empty)',
+    ].join('\n');
+};
+/** True for the POSIX shells we run with -i (rc files sourced). */
+const isPosixShell = (shell) => shell !== 'batch' && shell !== 'powershell';
+/** The MCP tool definition advertised to the remote AI. */
+const toolDefinition = (config, cwd) => ({
+    description: `Run a shell command on the LOCAL machine — the computer that launched \`fnd workspace\`, NOT this remote box. ` +
+        `The command runs under ${config.shell}${config.profile && isPosixShell(config.shell) ? ' (interactive, so rc files and tools like nvm are already loaded)' : ''} ` +
+        `with working directory ${cwd}, and the result contains the exit code, stdout, and stderr.`,
+    inputSchema: {
+        properties: {
+            command: { description: `Command line to execute via ${config.shell} on the local machine.`, type: 'string' },
+            timeoutMs: {
+                description: `Optional timeout in milliseconds (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS}); the process is killed when it elapses.`,
+                type: 'number',
+            },
+        },
+        required: ['command'],
+        type: 'object',
+    },
+    name: RPC_TOOL_NAME,
+});
+const rpcError = (id, code, message) => ({
+    error: { code, message },
+    id,
+    jsonrpc: '2.0',
+});
+const rpcResult = (id, result) => ({ id, jsonrpc: '2.0', result });
+/**
+ * Handle one JSON-RPC message. Returns the response object for requests, or
+ * undefined for notifications (which get no response body).
+ */
+const handleRpcMessage = async (msg, config, cwd) => {
+    const isRequest = msg.id !== undefined && msg.id !== null;
+    if (msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+        return isRequest ? rpcError(msg.id, -32_600, 'Invalid request') : undefined;
+    }
+    if (!isRequest)
+        return undefined; // notifications (e.g. notifications/initialized) need no reply
+    const id = msg.id;
+    switch (msg.method) {
+        case 'initialize': {
+            const requested = msg.params?.protocolVersion;
+            return rpcResult(id, {
+                capabilities: { tools: {} },
+                protocolVersion: typeof requested === 'string' ? requested : '2025-03-26',
+                serverInfo: { name: 'fnd-local-shell', version: '1.0.0' },
+            });
+        }
+        case 'ping': {
+            return rpcResult(id, {});
+        }
+        case 'tools/call': {
+            const params = msg.params ?? {};
+            if (params.name !== RPC_TOOL_NAME) {
+                return rpcError(id, -32_602, `Unknown tool: ${String(params.name)}`);
+            }
+            const args = (params.arguments ?? {});
+            if (typeof args.command !== 'string' || args.command.length === 0) {
+                return rpcError(id, -32_602, 'The "command" argument must be a non-empty string');
+            }
+            const timeoutMs = typeof args.timeoutMs === 'number' && args.timeoutMs > 0
+                ? Math.min(args.timeoutMs, MAX_TIMEOUT_MS)
+                : DEFAULT_TIMEOUT_MS;
+            const result = await runLocalCommand(config, args.command, cwd, timeoutMs);
+            return rpcResult(id, {
+                content: [{ text: formatResult(result), type: 'text' }],
+                isError: result.timedOut || result.exitCode !== 0,
+            });
+        }
+        case 'tools/list': {
+            return rpcResult(id, { tools: [toolDefinition(config, cwd)] });
+        }
+        default: {
+            return rpcError(id, -32_601, `Method not found: ${msg.method}`);
+        }
+    }
+};
+/** Read a request body, rejecting when it exceeds the size cap. */
+const readBody = (req) => new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > MAX_BODY_BYTES) {
+            reject(new Error('request body too large'));
+            req.destroy();
+            return;
+        }
+        chunks.push(chunk);
+    });
+    req.once('end', () => resolve(Buffer.concat(chunks).toString()));
+    req.once('error', reject);
+});
+const handleHttpRequest = async (req, res, config, cwd) => {
+    // Streamable HTTP: clients POST JSON-RPC messages. We don't offer a
+    // server-initiated SSE stream, so GET (and anything else) gets 405.
+    if (req.method !== 'POST') {
+        res.writeHead(405, { allow: 'POST' }).end();
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readBody(req));
+    }
+    catch {
+        res
+            .writeHead(400, { 'content-type': 'application/json' })
+            .end(JSON.stringify(rpcError(null, -32_700, 'Parse error')));
+        return;
+    }
+    const messages = (Array.isArray(parsed) ? parsed : [parsed]);
+    const responses = (await Promise.all(messages.map((m) => handleRpcMessage(m, config, cwd)))).filter((r) => r !== undefined);
+    // A body of nothing but notifications gets 202 Accepted with no content.
+    if (responses.length === 0) {
+        res.writeHead(202).end();
+        return;
+    }
+    const payload = Array.isArray(parsed) ? responses : responses[0];
+    res.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify(payload));
+};
+/**
+ * Start the local RPC (MCP) server on 127.0.0.1:<ports.local>. Commands execute
+ * with `cwd` as their working directory — the local side of the workspace sync.
+ * Resolves once the port is bound; rejects if binding fails (e.g. port in use).
+ */
+export const startRpcServer = (config, cwd) => new Promise((resolve, reject) => {
+    const server = createServer((req, res) => {
+        handleHttpRequest(req, res, config, cwd).catch(() => {
+            if (!res.headersSent)
+                res.writeHead(500);
+            res.end();
+        });
+    });
+    server.once('error', reject);
+    server.listen(config.ports.local, '127.0.0.1', () => {
+        resolve({
+            close: () => new Promise((done) => {
+                server.closeAllConnections();
+                server.close(() => done());
+            }),
+        });
+    });
+});

package/dist/lib/webflow.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Minimal Webflow Data API v2 client — only what `fnd alt-text` needs.
+ *
+ * Two kinds of images live in a Webflow site and they are updated through
+ * completely different endpoints:
+ *
+ *   site asset library   /v2/sites/:site/assets        -> PATCH /v2/assets/:id  {altText}
+ *   CMS image fields     /v2/collections/:id/items     -> PATCH /v2/collections/:id/items  {items[].fieldData}
+ *
+ * Read endpoints are async generators that paginate internally, so callers just
+ * `for await` and never deal with offsets.
+ *
+ * SECURITY: the API key is a site-wide bearer token. It is only ever put in an
+ * Authorization header — never logged, never included in an error message (we
+ * report the URL pathname, not the full URL, in case a token ever ends up in a
+ * query string).
+ */
+export interface WebflowAuth {
+    apiKey: string;
+    siteId: string;
+}
+export interface Asset {
+    altText: null | string;
+    contentType: string;
+    displayName: string;
+    hostedUrl: string;
+    id: string;
+    originalFileName: string;
+    siteId: string;
+}
+export interface Collection {
+    displayName: string;
+    id: string;
+    singularName: string;
+    slug: string;
+}
+/** A single CMS image value. `alt` is null until someone (or this command) fills it in. */
+export interface ImageField {
+    alt: null | string;
+    fileId: string;
+    url: string;
+}
+export interface CollectionItem {
+    fieldData: Record<string, ImageField | ImageField[] | unknown>;
+    id: string;
+    isArchived: boolean;
+    isDraft: boolean;
+}
+/**
+ * Every asset in the site's asset library, oldest page first.
+ *
+ * @yields each asset, one page of 100 at a time.
+ */
+export declare function getAssets(auth: WebflowAuth, limit?: number): AsyncGenerator<Asset>;
+/** Every CMS collection on the site. Not paginated by Webflow. */
+export declare const getCollections: (auth: WebflowAuth) => Promise<Collection[]>;
+/**
+ * Every item in a collection.
+ *
+ * Reads from STAGING by default (the `/live` endpoint is opt-in) to match
+ * `updateCollectionItem`, which also writes to staging — so a run's changes
+ * need publishing in Webflow before they show on the live site.
+ *
+ * @yields each item in the collection.
+ */
+export declare function getCollectionItems(auth: WebflowAuth, collectionId: string, { limit, staging }?: {
+    limit?: number;
+    staging?: boolean;
+}): AsyncGenerator<CollectionItem>;
+/** Set the alt text on a site asset. */
+export declare const updateAssetAltText: (auth: WebflowAuth, assetId: string, altText: string) => Promise<void>;
+/** Patch one item's fieldData. Only the fields present in `fieldData` are touched. */
+export declare const updateCollectionItem: (auth: WebflowAuth, collectionId: string, itemId: string, fieldData: Record<string, unknown>) => Promise<void>;
+/**
+ * Webflow hands back untyped `fieldData`, so image fields are duck-typed: a
+ * single image is an object with a `url`, a multi-image field is an array of
+ * those (an empty array counts — it is still an image field, just empty).
+ */
+export declare const isImageField: (value: unknown) => value is ImageField;
+export declare const isImagesField: (value: unknown) => value is ImageField[];

package/dist/lib/webflow.js

@@ -0,0 +1,122 @@
+/**
+ * Minimal Webflow Data API v2 client — only what `fnd alt-text` needs.
+ *
+ * Two kinds of images live in a Webflow site and they are updated through
+ * completely different endpoints:
+ *
+ *   site asset library   /v2/sites/:site/assets        -> PATCH /v2/assets/:id  {altText}
+ *   CMS image fields     /v2/collections/:id/items     -> PATCH /v2/collections/:id/items  {items[].fieldData}
+ *
+ * Read endpoints are async generators that paginate internally, so callers just
+ * `for await` and never deal with offsets.
+ *
+ * SECURITY: the API key is a site-wide bearer token. It is only ever put in an
+ * Authorization header — never logged, never included in an error message (we
+ * report the URL pathname, not the full URL, in case a token ever ends up in a
+ * query string).
+ */
+const API = 'https://api.webflow.com/v2';
+/** How many times a 429 is retried before the request is allowed to fail. */
+const RATE_LIMIT_RETRIES = 3;
+/** Fallback wait when Webflow rate-limits us without a Retry-After header. */
+const RATE_LIMIT_FALLBACK_MS = 15_000;
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * One request against the Webflow API, with a bounded retry on 429.
+ *
+ * A full site run is hundreds of sequential requests spread over however long
+ * the vision model takes, so hitting the per-minute cap is a matter of site
+ * size, not of anything the caller did wrong — dying on it would throw away all
+ * the work done so far.
+ */
+const request = async (auth, url, init = {}) => {
+    const { pathname } = new URL(url);
+    const method = init.method ?? 'GET';
+    for (let attempt = 0;; attempt++) {
+        // eslint-disable-next-line no-await-in-loop
+        const resp = await fetch(url, {
+            ...init,
+            headers: { Authorization: `Bearer ${auth.apiKey}`, ...init.headers },
+        });
+        // eslint-disable-next-line no-await-in-loop
+        if (resp.ok)
+            return (await resp.json());
+        if (resp.status === 429 && attempt < RATE_LIMIT_RETRIES) {
+            const retryAfter = Number(resp.headers.get('retry-after'));
+            // eslint-disable-next-line no-await-in-loop
+            await sleep(Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : RATE_LIMIT_FALLBACK_MS);
+            continue;
+        }
+        // eslint-disable-next-line no-await-in-loop
+        const body = await resp.text().catch(() => '');
+        throw new Error(`Webflow ${method} ${pathname} failed (${resp.status} ${resp.statusText})${body ? `: ${body.slice(0, 300)}` : ''}`);
+    }
+};
+/**
+ * Every asset in the site's asset library, oldest page first.
+ *
+ * @yields each asset, one page of 100 at a time.
+ */
+export async function* getAssets(auth, limit = 100) {
+    for (let page = 0;; page++) {
+        const url = new URL(`${API}/sites/${auth.siteId}/assets`);
+        url.searchParams.set('offset', `${page * limit}`);
+        url.searchParams.set('limit', `${limit}`);
+        // eslint-disable-next-line no-await-in-loop
+        const data = await request(auth, url);
+        yield* data.assets;
+        if (page + 1 >= Math.ceil(data.pagination.total / data.pagination.limit))
+            return;
+    }
+}
+/** Every CMS collection on the site. Not paginated by Webflow. */
+export const getCollections = async (auth) => {
+    const data = await request(auth, `${API}/sites/${auth.siteId}/collections`);
+    return data.collections;
+};
+/**
+ * Every item in a collection.
+ *
+ * Reads from STAGING by default (the `/live` endpoint is opt-in) to match
+ * `updateCollectionItem`, which also writes to staging — so a run's changes
+ * need publishing in Webflow before they show on the live site.
+ *
+ * @yields each item in the collection.
+ */
+export async function* getCollectionItems(auth, collectionId, { limit = 100, staging = true } = {}) {
+    for (let page = 0;; page++) {
+        const url = new URL(`${API}/collections/${collectionId}/items${staging ? '' : '/live'}`);
+        url.searchParams.set('offset', `${page * limit}`);
+        url.searchParams.set('limit', `${limit}`);
+        // eslint-disable-next-line no-await-in-loop
+        const data = await request(auth, url);
+        yield* data.items;
+        if (page + 1 >= Math.ceil(data.pagination.total / data.pagination.limit))
+            return;
+    }
+}
+/** Set the alt text on a site asset. */
+export const updateAssetAltText = async (auth, assetId, altText) => {
+    await request(auth, `${API}/assets/${assetId}`, {
+        body: JSON.stringify({ altText }),
+        headers: { 'Content-Type': 'application/json' },
+        method: 'PATCH',
+    });
+};
+/** Patch one item's fieldData. Only the fields present in `fieldData` are touched. */
+export const updateCollectionItem = async (auth, collectionId, itemId, fieldData) => {
+    await request(auth, `${API}/collections/${collectionId}/items`, {
+        body: JSON.stringify({ items: [{ fieldData, id: itemId }] }),
+        headers: { 'Content-Type': 'application/json' },
+        method: 'PATCH',
+    });
+};
+/**
+ * Webflow hands back untyped `fieldData`, so image fields are duck-typed: a
+ * single image is an object with a `url`, a multi-image field is an array of
+ * those (an empty array counts — it is still an image field, just empty).
+ */
+export const isImageField = (value) => typeof value === 'object' && value !== null && !Array.isArray(value) && 'url' in value;
+export const isImagesField = (value) => Array.isArray(value) && value.every((entry) => isImageField(entry));