@firenet-designs/fnd-cli 2.4.0 → 2.6.0

package/dist/lib/alt-text.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Alt-text generation: fetch an image, make it something a vision model can
+ * read, and ask a locally-hosted Ollama model to describe it.
+ *
+ * Everything runs against the user's own Ollama host, so no image ever leaves
+ * their network and there is no per-image API cost — which is also why the
+ * caller drives this strictly sequentially: a single local model gains nothing
+ * from concurrent requests.
+ */
+import type { ImageFilter, ImageMeta } from './image-filter.js';
+export declare const DEFAULT_OLLAMA_HOST = "http://localhost:11434";
+/**
+ * One image's worth of result. The caller already knows the URL, so this is
+ * everything else worth recording about the round trip.
+ *
+ * `bytes` is the size of what was actually sent to the model, i.e. after the
+ * PNG conversion below — not `meta.fileSize`, which is the (usually much
+ * smaller) WebP the site serves. `ms` is wall clock for the whole thing
+ * (download, convert, inference), because that is what a run's duration is
+ * actually made of.
+ */
+export interface Description {
+    alt: string;
+    bytes: number;
+    meta: ImageMeta;
+    ms: number;
+    skipped: false;
+    tokens: number;
+}
+/** An image the filter rejected. It was downloaded, but never sent to the model. */
+export interface Skipped {
+    meta: ImageMeta;
+    skipped: true;
+}
+export type Describe = (url: string) => Promise<Description | Skipped>;
+/**
+ * Every model pulled on the host that can actually read an image.
+ *
+ * /api/tags (`list`) is the only endpoint that enumerates models, but it says
+ * nothing about what a model can do — the capability list lives on /api/show
+ * (`show`), so each tag is asked individually. The calls are local and run
+ * concurrently; a model whose show() fails (pulled but broken, or removed
+ * between the two calls) is simply left out rather than failing the run.
+ */
+export declare const listVisionModels: (host: string) => Promise<string[]>;
+/**
+ * Bind a describer to one Ollama host and model. The client is created once and
+ * reused so the connection (and the loaded model, via keep_alive) survives
+ * across images.
+ *
+ * `filter`, when given, decides whether an image is worth describing — it runs
+ * after the download (see fetchImage) but before inference, and a rejected
+ * image comes back as `{skipped: true}` rather than throwing, because being
+ * filtered out is a normal outcome and not a failure.
+ */
+export declare const createDescriber: (host: string, model: string, filter?: ImageFilter) => Describe;

package/dist/lib/alt-text.js

@@ -0,0 +1,144 @@
+/**
+ * Alt-text generation: fetch an image, make it something a vision model can
+ * read, and ask a locally-hosted Ollama model to describe it.
+ *
+ * Everything runs against the user's own Ollama host, so no image ever leaves
+ * their network and there is no per-image API cost — which is also why the
+ * caller drives this strictly sequentially: a single local model gains nothing
+ * from concurrent requests.
+ */
+import { Ollama } from 'ollama';
+export const DEFAULT_OLLAMA_HOST = 'http://localhost:11434';
+/** How long Ollama keeps the model resident between images, in seconds. */
+const KEEP_ALIVE = 60;
+const PROMPT = "Make alt text for this image. The alt text should be no more than 1 sentence. Don't be overly descriptive. Include any text in the image in your description. Verbs should be in present tense.";
+/**
+ * Everything the model sees is PNG.
+ *
+ * Which formats a vision model can actually decode is not documented and varies
+ * by model — WebP in particular gets accepted and then described as if it were
+ * noise. Re-encoding every image removes the question: the model only ever
+ * receives the one format they all handle. The cost is a decode + encode per
+ * image, which is nothing next to the inference that follows.
+ *
+ * Both converters are native modules with real startup cost, so they're
+ * imported lazily — the first image of a run pays for sharp, and a run with no
+ * SVGs never loads resvg at all.
+ */
+const svgToPng = async (bytes) => {
+    const { Resvg } = await import('@resvg/resvg-js');
+    // Rendered on black: SVG icons are overwhelmingly dark-on-transparent, which
+    // flattens to invisible on the white the model would otherwise see.
+    const rendered = new Resvg(Buffer.from(bytes), { background: '#000000' }).render();
+    // An SVG has no intrinsic pixel size, so `width`/`height` in a filter mean the
+    // size resvg chose to rasterize at — the viewBox, in practice.
+    return { height: rendered.height, png: new Uint8Array(rendered.asPng()), width: rendered.width };
+};
+/** Raster → PNG. Covers WebP, JPEG, AVIF, GIF, TIFF and PNG itself. */
+const rasterToPng = async (bytes) => {
+    const { default: sharp } = await import('sharp');
+    // Alpha is left alone here, unlike the SVG path: a transparent raster image
+    // could be light or dark, so there's no background that's safe to guess.
+    // resolveWithObject gets the dimensions out of the same decode as the encode.
+    const { data, info } = await sharp(Buffer.from(bytes)).png().toBuffer({ resolveWithObject: true });
+    return { height: info.height, png: new Uint8Array(data), width: info.width };
+};
+/**
+ * The `type` a filter expression sees: a bare format token, not a MIME type.
+ *
+ * Content-Type is trusted first and the extension is the fallback, since CDNs
+ * serve plenty of images from extensionless URLs. `jpg` is normalized to `jpeg`
+ * and `svg+xml` to `svg` so an expression doesn't have to spell both.
+ */
+const detectType = (contentType, path) => {
+    const fromHeader = contentType.split(';')[0].trim().toLowerCase();
+    const subtype = fromHeader.startsWith('image/') ? fromHeader.slice('image/'.length) : '';
+    const raw = subtype || (path.includes('.') ? path.split('.').pop() : '');
+    const token = raw.replace('+xml', '');
+    return token === 'jpg' ? 'jpeg' : token;
+};
+/**
+ * Download an image, normalize it to bytes the model accepts, and measure it.
+ *
+ * The measuring has to happen here rather than before the download: width and
+ * height aren't knowable without the image itself, and Content-Length is absent
+ * often enough that fileSize is taken from the bytes we actually received. So a
+ * filter saves inference time — the expensive part — not bandwidth.
+ */
+const fetchImage = async (url) => {
+    const resp = await fetch(url);
+    if (!resp.ok)
+        throw new Error(`Could not download image (${resp.status} ${resp.statusText})`);
+    const bytes = new Uint8Array(await resp.arrayBuffer());
+    const contentType = resp.headers.get('content-type') ?? '';
+    const path = new URL(url).pathname.toLowerCase();
+    const type = detectType(contentType, path);
+    // SVG is vector, so it goes through the rasterizer rather than sharp's decoder.
+    const { height, png, width } = type === 'svg' || contentType.includes('svg') || path.endsWith('.svg')
+        ? await svgToPng(bytes)
+        : await rasterToPng(bytes);
+    return { meta: { fileSize: bytes.byteLength, height, type, url, width }, png };
+};
+/**
+ * Every model pulled on the host that can actually read an image.
+ *
+ * /api/tags (`list`) is the only endpoint that enumerates models, but it says
+ * nothing about what a model can do — the capability list lives on /api/show
+ * (`show`), so each tag is asked individually. The calls are local and run
+ * concurrently; a model whose show() fails (pulled but broken, or removed
+ * between the two calls) is simply left out rather than failing the run.
+ */
+export const listVisionModels = async (host) => {
+    const ollama = new Ollama({ host });
+    const { models } = await ollama.list();
+    const checked = await Promise.all(models.map(async ({ model }) => {
+        try {
+            const { capabilities } = await ollama.show({ model });
+            return capabilities?.includes('vision') ? model : undefined;
+        }
+        catch {
+        }
+    }));
+    return checked.filter((model) => model !== undefined).sort();
+};
+/**
+ * Bind a describer to one Ollama host and model. The client is created once and
+ * reused so the connection (and the loaded model, via keep_alive) survives
+ * across images.
+ *
+ * `filter`, when given, decides whether an image is worth describing — it runs
+ * after the download (see fetchImage) but before inference, and a rejected
+ * image comes back as `{skipped: true}` rather than throwing, because being
+ * filtered out is a normal outcome and not a failure.
+ */
+export const createDescriber = (host, model, filter) => {
+    const ollama = new Ollama({ host });
+    return async (url) => {
+        const started = performance.now();
+        const { meta, png } = await fetchImage(url);
+        if (filter && !filter(meta))
+            return { meta, skipped: true };
+        const images = [Buffer.from(png).toString("base64")];
+        const resp = await ollama.chat({
+            // eslint-disable-next-line camelcase
+            keep_alive: KEEP_ALIVE,
+            messages: [{ content: PROMPT, images, role: 'user' }],
+            model,
+            stream: false,
+            // think: true,
+        });
+        const content = resp.message.content.trim();
+        if (!content)
+            throw new Error(`${model} returned an empty description`);
+        return {
+            alt: content,
+            bytes: png.byteLength,
+            meta,
+            ms: performance.now() - started,
+            skipped: false,
+            // Prompt tokens dominate here — an image is worth hundreds of them, the
+            // sentence that comes back is worth a few dozen — so both halves count.
+            tokens: (resp.prompt_eval_count ?? 0) + (resp.eval_count ?? 0),
+        };
+    };
+};

package/dist/lib/image-filter.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The `--filter` expression for `fnd alt-text`.
+ *
+ * The expression is evaluated with `eval`, deliberately: it comes from the flag
+ * the person is typing into their own shell, so it is already code they are
+ * running on their own machine — there is no privilege boundary to cross and no
+ * mini-language worth inventing when JavaScript's operators are exactly what a
+ * filter needs. It is NOT safe to feed this a string from anywhere else (a
+ * config file pulled off the network, a CI variable someone else controls).
+ *
+ * What the expression can see is the image's metadata plus `sizes`; nothing is
+ * passed in from the surrounding scope, because the eval'd text is a standalone
+ * function expression whose only bindings are its own parameters.
+ */
+/** Everything a filter expression can test. Sizes are bytes, dimensions pixels. */
+export interface ImageMeta {
+    /** Bytes as served by the site — not the size of the PNG we convert it to. */
+    fileSize: number;
+    height: number;
+    /** Short format token: `webp`, `png`, `jpeg`, `svg`, `avif`, `gif`, … */
+    type: string;
+    url: string;
+    width: number;
+}
+export type ImageFilter = (meta: ImageMeta) => boolean;
+/**
+ * Byte-count helpers for filter expressions: `sizes.KB(100)` is 100 * 1024.
+ *
+ * Every casing of every unit is registered (`KB`, `Kb`, `kB`, `kb`) and they all
+ * mean the same thing — kb is NOT kilobits. Nobody filtering image files means
+ * bits, and a silent factor of eight is a worse outcome than a redundant alias.
+ * Multipliers are binary (1024), matching what an OS reports for a file.
+ */
+export declare const sizes: Record<string, (n: number) => number>;
+/**
+ * Compile a filter expression once, up front.
+ *
+ * Building it eagerly means a typo (`filesize`, a stray paren) fails before the
+ * first image is downloaded rather than four hundred images into a run — the
+ * expression is both parsed and run once against a probe here, since a bad
+ * identifier is a runtime ReferenceError, not a syntax error.
+ */
+export declare const createFilter: (expression: string) => ImageFilter;

package/dist/lib/image-filter.js

@@ -0,0 +1,71 @@
+/**
+ * The `--filter` expression for `fnd alt-text`.
+ *
+ * The expression is evaluated with `eval`, deliberately: it comes from the flag
+ * the person is typing into their own shell, so it is already code they are
+ * running on their own machine — there is no privilege boundary to cross and no
+ * mini-language worth inventing when JavaScript's operators are exactly what a
+ * filter needs. It is NOT safe to feed this a string from anywhere else (a
+ * config file pulled off the network, a CI variable someone else controls).
+ *
+ * What the expression can see is the image's metadata plus `sizes`; nothing is
+ * passed in from the surrounding scope, because the eval'd text is a standalone
+ * function expression whose only bindings are its own parameters.
+ */
+const UNITS = {
+    b: 1,
+    gb: 1024 ** 3,
+    kb: 1024,
+    mb: 1024 ** 2,
+    tb: 1024 ** 4,
+};
+/**
+ * Byte-count helpers for filter expressions: `sizes.KB(100)` is 100 * 1024.
+ *
+ * Every casing of every unit is registered (`KB`, `Kb`, `kB`, `kb`) and they all
+ * mean the same thing — kb is NOT kilobits. Nobody filtering image files means
+ * bits, and a silent factor of eight is a worse outcome than a redundant alias.
+ * Multipliers are binary (1024), matching what an OS reports for a file.
+ */
+export const sizes = Object.fromEntries(Object.entries(UNITS).flatMap(([unit, multiplier]) => {
+    const cased = unit.length === 1
+        ? [unit, unit.toUpperCase()]
+        : [unit, unit.toUpperCase(), unit[0].toUpperCase() + unit[1], unit[0] + unit[1].toUpperCase()];
+    return [...new Set(cased)].map((name) => [name, (n) => n * multiplier]);
+}));
+/** A metadata shape used only to smoke-test the expression at startup. */
+const PROBE = {
+    fileSize: 0,
+    height: 0,
+    type: 'png',
+    url: 'https://example.com/probe.png',
+    width: 0,
+};
+/**
+ * Compile a filter expression once, up front.
+ *
+ * Building it eagerly means a typo (`filesize`, a stray paren) fails before the
+ * first image is downloaded rather than four hundred images into a run — the
+ * expression is both parsed and run once against a probe here, since a bad
+ * identifier is a runtime ReferenceError, not a syntax error.
+ */
+export const createFilter = (expression) => {
+    let compiled;
+    try {
+        // Indirect eval: evaluated in global scope, so the expression can't reach
+        // anything local to this module even by accident.
+        // eslint-disable-next-line no-eval
+        compiled = (0, eval)(`(({ fileSize, height, sizes, type, url, width }) => (${expression}))`);
+    }
+    catch (error) {
+        throw new Error(`--filter is not valid JavaScript: ${error.message}`);
+    }
+    const run = (meta) => Boolean(compiled({ ...meta, sizes }));
+    try {
+        run(PROBE);
+    }
+    catch (error) {
+        throw new Error(`--filter could not be evaluated: ${error.message}. Available values: fileSize, width, height, url, type, sizes.`);
+    }
+    return run;
+};

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));

package/dist/lib/workspace.d.ts

@@ -139,7 +139,15 @@ export interface RemoteCleanupOptions {
     /** Strip this project's local-shell MCP entry — only when the workspace registered one (--rpc). */
     removeRpcMcp?: boolean;
 }
-/** Run the remote-side teardown over a fresh ssh connection. */
+/**
+ * Run the remote-side teardown over a fresh ssh connection. Forces a remote PTY
+ * with `-tt`: the MCP-remove step runs under an *interactive* login shell
+ * (`$SHELL -lic`, so `claude2` aliases in rc files resolve — see
+ * `claudeMcpRemoveScript`), and an interactive bash without a PTY prints
+ * "cannot set terminal process group / no job control in this shell". `-tt`
+ * forces allocation even when this cleanup runs without a local TTY, mirroring
+ * the `-t` the interactive session ssh uses.
+ */
 export declare const runRemoteCleanup: (target: string, remoteDir: string, opts?: RemoteCleanupOptions) => Promise<number>;
 /**
  * The remote-side teardown script. Runs from inside the workspace dir so the
@@ -161,7 +169,7 @@ export declare const hasMutagen: () => boolean;
  * winner. When a `source` is given, it becomes the Mutagen alpha endpoint and
  * the mode switches to two-way-resolved (alpha always wins conflicts), so
  * `--source remote` puts the server first and `--source local` puts this
- * machine first. Labels let `workspace cleanup` find and terminate orphans.
+ * machine first. Labels let `workspace --cleanup` find and terminate orphans.
  * `ctx.ignores` (from --ignore-vcs) excludes gitignored paths from the sync so
  * each side keeps its own build artifacts and platform-specific binaries.
  */