@firenet-designs/fnd-cli 2.4.0 → 2.7.0

package/dist/commands/alt-text.js

@@ -0,0 +1,616 @@
+import { createDescriber, DEFAULT_OLLAMA_HOST, detectType, listVisionModels } from '#lib/alt-text.js';
+import { createFilter } from '#lib/image-filter.js';
+import { findShopifyBin } from '#lib/scaffold.js';
+import { authenticate, DRY_RUN_SCOPES, formatProductContext, getImageFiles, getImageProductContext, getInstalledScopes, missingScopes, normalizeStore, REQUIRED_SCOPES, updateFileAlt, } from '#lib/shopify/shopify.js';
+import { getAssets, getCollectionItems, getCollections, isImageField, isImagesField, updateAssetAltText, updateCollectionItem, } from '#lib/webflow.js';
+import { checkbox, input, password, select } from '@inquirer/prompts';
+import { Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import ora from 'ora';
+const atLimit = (state) => state.transcribed >= state.limit;
+/**
+ * Build filter metadata from what Shopify's GraphQL already told us about a file,
+ * so a --dry run can judge it without downloading. Returns undefined when any of
+ * the four fields is missing (a MediaImage still processing) — the caller's cue
+ * to fall back to the download. Only used for --dry; a real run measures the
+ * downloaded bytes instead, so a stale CDN value can never reach the model.
+ */
+const shopifyImageMeta = (file) => {
+    if (file.mimeType === null || file.width === null || file.height === null || file.fileSize === null)
+        return undefined;
+    return {
+        fileSize: file.fileSize,
+        height: file.height,
+        type: detectType(file.mimeType, file.url),
+        url: file.url,
+        width: file.width,
+    };
+};
+/** Non-empty validator for the @inquirer prompts that stand in for required flags. */
+const required = (value) => (value.trim().length > 0 ? true : 'Required');
+/** Trim a URL down to something that fits a terminal line. */
+const shortUrl = (url) => {
+    const name = url.split('?')[0].split('/').pop() ?? url;
+    return name.length > 60 ? `${name.slice(0, 57)}…` : name;
+};
+const formatMs = (ms) => (ms < 1000 ? `${Math.round(ms)}ms` : `${(ms / 1000).toFixed(1)}s`);
+const formatBytes = (bytes) => bytes < 1024 * 1024 ? `${Math.round(bytes / 1024)} KB` : `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+const formatCount = (n) => n.toLocaleString('en-US');
+/**
+ * Make a value safe to drop in a Markdown table cell: pipes would end the cell
+ * early and a newline would end the row. Descriptions are model output, so both
+ * are possible even though the prompt asks for one plain sentence.
+ */
+const cell = (value) => value.replaceAll('|', String.raw `\|`).replaceAll(/\s*\n\s*/g, ' ').trim();
+const sum = (values) => values.reduce((total, value) => total + value, 0);
+/** The thumbnail that stands in for a URL in every table. */
+const thumbnail = (url) => cell(`<img src="${url}" style="object-fit: contain; object-position: center; max-width: 256px; max-height: 256px" />`);
+/**
+ * The --output-stats report: totals, a row per image, the filtered-out images,
+ * then the failures.
+ *
+ * Sizes throughout are the file as the site serves it (`meta.fileSize`) — the
+ * same number the --filter sees, so a report can be read against the expression
+ * that produced it. The PNG we actually send the model gets its own column.
+ */
+const buildStatsMarkdown = (state, model, host, totalMs) => {
+    const tokens = sum(state.images.map((image) => image.tokens));
+    const described = sum(state.images.map((image) => image.ms));
+    const count = state.images.length;
+    const skippedBytes = sum(state.skipped.map((meta) => meta.fileSize));
+    const skippedCount = state.skipped.length;
+    const lines = [
+        '# Alt text run',
+        '',
+        `- Model: \`${model}\` on \`${host}\``,
+        `- Run duration: ${formatMs(totalMs)}`,
+        '',
+        '## Summary',
+        '',
+        '| Metric | Value |',
+        '| --- | --- |',
+        `| Images modified | ${formatCount(count)} |`,
+        `| Images skipped by filter | ${formatCount(skippedCount)} |`,
+        `| Images failed | ${formatCount(state.failures.length)} |`,
+        `| Tokens used | ${formatCount(tokens)} |`,
+        `| Average tokens per image | ${count > 0 ? formatCount(Math.round(tokens / count)) : '—'} |`,
+        `| Average time per image | ${count > 0 ? formatMs(described / count) : '—'} |`,
+        `| Skipped image total size | ${formatBytes(skippedBytes)} |`,
+        `| Skipped image average size | ${skippedCount > 0 ? formatBytes(skippedBytes / skippedCount) : '—'} |`,
+        '',
+        '## Images',
+        '',
+    ];
+    if (count === 0) {
+        lines.push('_No images were transcribed._', '');
+    }
+    else {
+        lines.push('| URL | Description | Tokens | Time | Size | Sent | Type | Dimensions |', '| --- | --- | --- | --- | --- | --- | --- | --- |', ...state.images.map((image) => `| ${thumbnail(image.url)} | ${cell(image.description)} | ${formatCount(image.tokens)} | ${formatMs(image.ms)} | ${formatBytes(image.meta.fileSize)} | ${formatBytes(image.bytes)} | ${cell(image.meta.type)} | ${image.meta.width}x${image.meta.height} |`), '');
+    }
+    lines.push('## Skipped by filter', '');
+    if (skippedCount === 0) {
+        lines.push('_None._', '');
+    }
+    else {
+        lines.push('| URL | Size | Type | Dimensions |', '| --- | --- | --- | --- |', ...state.skipped.map((meta) => `| ${thumbnail(meta.url)} | ${formatBytes(meta.fileSize)} | ${cell(meta.type)} | ${meta.width}x${meta.height} |`), '');
+    }
+    lines.push('## Failures', '');
+    if (state.failures.length === 0) {
+        lines.push('_None._', '');
+    }
+    else {
+        lines.push('| URL | Reason |', '| --- | --- |', ...state.failures.map((failure) => `| ${cell(failure.url)} | ${cell(failure.reason)} |`), '');
+    }
+    return lines.join('\n');
+};
+export default class AltText extends Command {
+    static aliases = ['caption'];
+    static description = 'Generate alt text for a site\'s images with a local Ollama vision model and write it back.\n\nPick a platform with --platform (webflow or shopify). For Webflow, walks the site asset library and (with --cms) the image fields of CMS collection items and PATCHes each description back through the Data API. For Shopify, walks the store\'s file library and writes alt text back through the Shopify CLI (which owns the auth — no --api-key). Images are fetched and described one at a time; nothing but the platform API calls leaves your network.\n\nWebflow CMS writes go to STAGING, so publish the site in Webflow to make them live. Any required flag you omit is prompted for.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --platform webflow --api-key <key> --site-id <id> --ollama-host http://localhost:11434 --ollama-model qwen3-vl:8b',
+        '<%= config.bin %> <%= command.id %> --platform shopify --site-id mystore',
+        '<%= config.bin %> <%= command.id %> --platform shopify --site-id mystore --dry',
+        '<%= config.bin %> <%= command.id %> --platform webflow --skip --limit 20',
+        '<%= config.bin %> <%= command.id %> --platform webflow --cms --select',
+        '<%= config.bin %> <%= command.id %> --platform webflow --cms --only products --only sku',
+        '<%= config.bin %> <%= command.id %> --platform webflow --output-stats ./alt-text-run.md',
+        '<%= config.bin %> <%= command.id %> --platform webflow --filter "fileSize>=sizes.KB(100) && width>=100 && height>=100"',
+        '<%= config.bin %> <%= command.id %> --platform webflow --filter "type !== \'svg\' && !url.includes(\'/icons/\')"',
+    ];
+    static flags = {
+        'api-key': Flags.string({
+            description: 'Webflow API token (site-scoped). Webflow only — Shopify auth comes from the Shopify CLI. Prompted for if omitted.',
+        }),
+        cms: Flags.boolean({
+            description: 'also add alt text to the images in CMS collection items. Webflow only. Off by default — only the site asset library is walked.',
+        }),
+        dry: Flags.boolean({
+            description: 'report how many images the run would caption without describing or writing anything. Every image is still downloaded and run through --filter so the count is accurate, but nothing reaches the model. The --ollama-host/--ollama-model and --output-stats flags are ignored in this mode, so --dry can be added to (and removed from) a full command without changing the rest.',
+        }),
+        filter: Flags.string({
+            description: 'a JavaScript expression deciding which images are worth describing, e.g. "fileSize>=sizes.KB(100) && width>=100 && height>=100". Available: fileSize (bytes), width, height (pixels), url, type ("webp", "png", "jpeg", "svg", …), and sizes.KB/MB/GB helpers. Images that fail it are skipped and reported separately. Evaluated after the download, since dimensions can\'t be known before it.',
+        }),
+        limit: Flags.integer({
+            description: 'stop after this many images have been transcribed (counted across assets and CMS together)',
+            min: 1,
+        }),
+        'ollama-host': Flags.string({
+            description: `base URL of the Ollama server. Prompted for if omitted.`,
+        }),
+        'ollama-model': Flags.string({
+            description: 'the model used to describe the images. Omit it to pick from the vision-capable models pulled on the host.',
+        }),
+        only: Flags.string({
+            dependsOn: ['cms'],
+            description: 'only touch these CMS collections, matched case-insensitively against a collection\'s name or slug. Repeat the flag for more than one.',
+            exclusive: ['select'],
+            multiple: true,
+        }),
+        'output-stats': Flags.string({
+            description: 'also write the run stats to this file as Markdown: totals, a row per image (url, description, tokens, time, size), and the failures. Parent directories are created.',
+        }),
+        platform: Flags.string({
+            description: 'which platform to run against. Prompted for if omitted.',
+            options: ['webflow', 'shopify'],
+        }),
+        select: Flags.boolean({
+            dependsOn: ['cms'],
+            description: 'fetch the CMS collections and pick which ones to process interactively',
+            exclusive: ['only'],
+        }),
+        'site-id': Flags.string({
+            description: 'Webflow site ID, or the Shopify store (mystore or mystore.myshopify.com). Prompted for if omitted.',
+        }),
+        skip: Flags.boolean({
+            description: 'leave images that already have alt text alone instead of overwriting them',
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(AltText);
+        const platform = await this.resolvePlatform(flags);
+        const dry = flags.dry ?? false;
+        // --api-key and --cms are Webflow concepts. Shopify auth (and everything
+        // else) comes from the Shopify CLI, so reject them rather than ignore them
+        // silently — a passed flag that does nothing is a bug from the user's seat.
+        if (platform === 'shopify') {
+            const stray = ['api-key', 'cms', 'select', 'only'].find((name) => flags[name]);
+            if (stray)
+                this.error(`--${stray} is a Webflow option and can't be used with --platform shopify.`, { code: '1' });
+        }
+        // A dry run never reaches the model and never writes stats, so the model
+        // flags and --output-stats simply do nothing here — deliberately NOT an
+        // error (like --cleanup on `workspace`), so you can drop --dry onto a full
+        // command and pull it back off without touching the rest of the flags.
+        //
+        // Only needed when a real run will actually describe images.
+        const host = dry
+            ? ''
+            : flags['ollama-host'] ??
+                (await input({ default: DEFAULT_OLLAMA_HOST, message: 'Ollama host', validate: required }));
+        const model = dry ? '' : flags['ollama-model'] ?? (await this.pickModel(host));
+        // Compiled here, not at first use, so a broken expression costs nothing.
+        let filter;
+        if (flags.filter) {
+            try {
+                filter = createFilter(flags.filter);
+            }
+            catch (error) {
+                this.error(error.message, { code: '1' });
+            }
+        }
+        const state = {
+            describe: createDescriber(host, model, filter, dry),
+            dry,
+            failures: [],
+            filter,
+            images: [],
+            limit: flags.limit ?? Number.POSITIVE_INFINITY,
+            skip: flags.skip ?? false,
+            skipped: [],
+            transcribed: 0,
+        };
+        this.log(chalk.dim(dry ? 'Dry run — counting which images would be captioned, describing none' : `Describing images with ${model} on ${host}`));
+        if (flags.filter)
+            this.log(chalk.dim(`Only images matching: ${flags.filter}`));
+        const started = performance.now();
+        const touchedCms = platform === 'shopify' ? await this.processShopify(flags, state) : await this.processWebflow(flags, state);
+        const totalMs = performance.now() - started;
+        if (dry) {
+            this.reportDry(state, totalMs);
+            return;
+        }
+        this.report(state, touchedCms, totalMs);
+        if (flags['output-stats']) {
+            await this.writeStats(flags['output-stats'], state, model, host, totalMs);
+        }
+    }
+    /**
+     * Describe one image and account for it. Returns undefined when the model or
+     * the download failed — one bad image must not abort a run that may have
+     * hundreds of good ones behind it.
+     *
+     * Also the fallback for a --dry run: when an image's metadata wasn't known up
+     * front (so the caller couldn't filter it cheaply), the describer downloads it
+     * just far enough to measure it, and this counts it via recordDry.
+     */
+    async describe(state, label, url, context) {
+        this.logImageLine(state, label, url);
+        // A spinner over the two silent, slow phases: the download, then (for a real
+        // run) the model. onDownloaded flips the text at the boundary between them.
+        // Indented one level under the image line; each result line sits at the same 4.
+        const spinner = ora({ indent: 4, text: 'Downloading…' }).start();
+        try {
+            const result = await state.describe(url, context, () => {
+                spinner.text = 'Generating alt text…';
+            });
+            this.stopSpinner(spinner);
+            // Real run only: the describer applies --filter after the download. A
+            // filtered image spends no tokens and no --limit budget.
+            if (result.skipped) {
+                state.skipped.push(result.meta);
+                this.log(chalk.dim(`    – filtered out (${formatBytes(result.meta.fileSize)}, ${result.meta.width}x${result.meta.height}, ${result.meta.type})`));
+                return undefined;
+            }
+            // Dry run: the download only served to learn the metadata this image
+            // didn't carry up front. Count it here and write nothing back.
+            if (state.dry) {
+                this.recordDry(state, result.meta);
+                return undefined;
+            }
+            const { alt, bytes, meta, ms, tokens } = result;
+            state.transcribed++;
+            state.images.push({ bytes, description: alt, meta, ms, tokens, url });
+            this.log(`    ${chalk.green('✓')} ${alt}`);
+            this.log(chalk.dim(`      ${formatCount(tokens)} tokens · ${formatMs(ms)} · ${formatBytes(bytes)} sent`));
+            return alt;
+        }
+        catch (error) {
+            this.stopSpinner(spinner);
+            const reason = error.message;
+            state.failures.push({ reason, url });
+            this.log(chalk.yellow(`    ⚠ skipped: ${reason}`));
+            return undefined;
+        }
+    }
+    /**
+     * Guarantee the store's app installation has the scopes this run needs before
+     * any captioning. `required` is the minimal set for the run — the full
+     * REQUIRED_SCOPES for a real run, just DRY_RUN_SCOPES (read_files) for a --dry
+     * one, which never writes or maps product context. A non-zero exit from the
+     * scope probe is the CLI's way of saying the store isn't authenticated at all;
+     * a clean exit with a scope missing means it's authenticated but under-scoped.
+     * Either way `shopify store auth` with `required` fixes it — it adds only
+     * what's missing, and a write scope already covers its read counterpart.
+     */
+    ensureShopifyScopes(bin, store, required) {
+        this.log(chalk.dim(`Checking Shopify access for ${store}…`));
+        const { authenticated, scopes } = getInstalledScopes(bin, store);
+        const missing = missingScopes(scopes, required);
+        if (authenticated && missing.length === 0) {
+            this.log(chalk.dim(`  ${chalk.green('✓')} ${required.join(', ')} already granted`));
+            return;
+        }
+        const reason = authenticated ? `missing ${missing.join(', ')}` : 'not authenticated';
+        this.log(chalk.dim(`  ${reason} — running shopify store auth`));
+        if (!authenticate(bin, store, required)) {
+            this.error(`Could not authenticate ${store}. Try it directly: shopify store auth --store ${store} --scopes ${required.join(',')}`, { code: '1' });
+        }
+    }
+    /** The `[n/limit] label — file` progress line, shared by real and dry counting. */
+    logImageLine(state, label, url) {
+        const counter = Number.isFinite(state.limit)
+            ? `${state.transcribed + 1}/${state.limit}`
+            : `${state.transcribed + 1}`;
+        this.log(chalk.dim(`  [${counter}] ${label} — ${shortUrl(url)}`));
+    }
+    /** Which CMS collections this run should walk. */
+    async pickCollections(auth, useSelect, only) {
+        const collections = await getCollections(auth);
+        if (collections.length === 0) {
+            this.log(chalk.yellow('This site has no CMS collections.'));
+            return [];
+        }
+        const label = (collection) => `${collection.displayName} (${collection.slug})`;
+        if (only) {
+            const wanted = only.map((name) => name.trim().toLowerCase());
+            const matches = (collection, name) => collection.displayName.toLowerCase() === name ||
+                collection.singularName.toLowerCase() === name ||
+                collection.slug.toLowerCase() === name;
+            const missing = wanted.filter((name) => !collections.some((collection) => matches(collection, name)));
+            if (missing.length > 0) {
+                this.error(`No CMS collection named ${missing.map((name) => `"${name}"`).join(', ')}. This site has: ${collections
+                    .map((collection) => label(collection))
+                    .join(', ')}.`, { code: '1' });
+            }
+            return collections.filter((collection) => wanted.some((name) => matches(collection, name)));
+        }
+        if (useSelect) {
+            return checkbox({
+                choices: collections.map((collection) => ({ name: label(collection), value: collection })),
+                message: 'Which CMS collections should get alt text?',
+            });
+        }
+        return collections;
+    }
+    /**
+     * Ask which model to use, offering only the vision-capable models the host has
+     * already pulled — a text-only model would happily accept the request and
+     * describe nothing, and a model that isn't pulled would stall the run behind a
+     * silent download.
+     */
+    async pickModel(host) {
+        let models;
+        try {
+            models = await listVisionModels(host);
+        }
+        catch (error) {
+            this.error(`Could not list models on ${host}: ${error.message}`, { code: '1' });
+        }
+        if (models.length === 0) {
+            this.error(`No vision-capable models are pulled on ${host}. Pull one (e.g. "ollama pull qwen3-vl:8b") or pass --ollama-model.`, { code: '1' });
+        }
+        return select({ choices: models, message: 'Which Ollama model should describe the images?' });
+    }
+    /** The site asset library pass. Always runs; --cms only adds work on top of it. */
+    async processAssets(auth, state) {
+        this.log(chalk.bold('\nSite assets'));
+        for await (const asset of getAssets(auth)) {
+            if (atLimit(state))
+                return;
+            // The asset library also holds PDFs, fonts and the like.
+            if (!asset.contentType.startsWith('image/'))
+                continue;
+            if (state.skip && asset.altText)
+                continue;
+            const alt = await this.describe(state, asset.displayName || asset.originalFileName, asset.hostedUrl);
+            if (alt !== undefined)
+                await updateAssetAltText(auth, asset.id, alt);
+        }
+    }
+    async processCollection(auth, collection, state) {
+        this.log(chalk.bold(`\nCollection: ${collection.displayName}`));
+        for await (const item of getCollectionItems(auth, collection.id)) {
+            if (atLimit(state))
+                return;
+            await this.processItem(auth, collection, item, state);
+        }
+    }
+    /**
+     * Fill in every image field on one item, then PATCH the item once. Fields that
+     * didn't change are left out of the payload entirely, and an item with no
+     * changed fields is never PATCHed.
+     */
+    async processItem(auth, collection, item, state) {
+        const fieldData = {};
+        for (const [fieldName, value] of Object.entries(item.fieldData)) {
+            if (atLimit(state))
+                break;
+            if (isImageField(value)) {
+                if (state.skip && value.alt)
+                    continue;
+                // eslint-disable-next-line no-await-in-loop
+                const alt = await this.describe(state, `${collection.displayName} > ${fieldName}`, value.url);
+                if (alt !== undefined)
+                    fieldData[fieldName] = { ...value, alt };
+            }
+            else if (isImagesField(value)) {
+                // A multi-image field has to be written back whole, so every image is
+                // carried over — only the ones we actually described come back changed.
+                const next = [];
+                let changed = false;
+                for (const image of value) {
+                    if (atLimit(state) || (state.skip && image.alt)) {
+                        next.push(image);
+                        continue;
+                    }
+                    // eslint-disable-next-line no-await-in-loop
+                    const alt = await this.describe(state, `${collection.displayName} > ${fieldName}`, image.url);
+                    next.push(alt === undefined ? image : { ...image, alt });
+                    changed ||= alt !== undefined;
+                }
+                if (changed)
+                    fieldData[fieldName] = next;
+            }
+        }
+        if (Object.keys(fieldData).length === 0)
+            return;
+        await updateCollectionItem(auth, collection.id, item.id, fieldData);
+    }
+    /**
+     * The Shopify path: make sure the CLI is present and the store is authenticated
+     * with the file scopes, then caption every image in the file library. Always
+     * returns false — there's no separate staging step to warn about.
+     */
+    async processShopify(flags, state) {
+        const bin = findShopifyBin();
+        if (!bin) {
+            this.error('The Shopify CLI is required for --platform shopify but was not found. Install it and run `shopify login` first: https://shopify.dev/docs/api/shopify-cli', { code: '1' });
+        }
+        const store = normalizeStore(flags['site-id'] ?? (await input({ message: 'Shopify store (e.g. mystore)', validate: required })));
+        this.ensureShopifyScopes(bin, store, state.dry ? DRY_RUN_SCOPES : REQUIRED_SCOPES);
+        // Best-effort: the product a file is attached to is the strongest context
+        // for a caption, but a hiccup mapping it shouldn't cost the whole run — a
+        // file with no product just falls back to its file-name hint. A dry run
+        // never captions, so the context would never be used — skip the (costly)
+        // bulk-operation mapping entirely.
+        let context = new Map();
+        if (!state.dry) {
+            // The mapping is a bulk operation that can take a while — spin while it runs.
+            const spinner = ora('Mapping product context…').start();
+            try {
+                context = await getImageProductContext(bin, store);
+                spinner.succeed(`${context.size} product image${context.size === 1 ? '' : 's'} mapped`);
+            }
+            catch (error) {
+                spinner.warn(`product context unavailable: ${error.message}`);
+            }
+        }
+        this.log(chalk.bold('\nStore files'));
+        // getImageFiles runs a bulk export before it yields anything; spin until the
+        // first file lands (or the stream ends), then let each image's own spinner take over.
+        const listing = ora('Exporting file library…').start();
+        try {
+            for await (const file of getImageFiles(bin, store)) {
+                if (listing.isSpinning)
+                    listing.stop();
+                if (atLimit(state))
+                    return false;
+                if (state.skip && file.alt)
+                    continue;
+                // Dry run fast path: Shopify already told us the mimeType, dimensions and
+                // size, so we can filter and count without fetching a single byte. Only
+                // when a field is missing (an image still processing) do we fall through
+                // to the download. A real run skips this entirely — see the note below.
+                if (state.dry) {
+                    const meta = shopifyImageMeta(file);
+                    if (meta) {
+                        this.logImageLine(state, file.name, file.url);
+                        this.recordDry(state, meta);
+                        continue;
+                    }
+                }
+                // A real run always downloads: the bytes are needed for the model anyway,
+                // so they're the source of truth for the filter too, and a stale CDN value
+                // never decides anything. (In --dry this is only the metadata-missing
+                // fallback; describe() counts it without describing.)
+                const product = context.get(file.id);
+                const alt = await this.describe(state, file.name, file.url, product ? formatProductContext(product) : undefined);
+                if (alt !== undefined)
+                    updateFileAlt(bin, store, file.id, alt);
+            }
+        }
+        finally {
+            // Reached with the spinner still up only when the library had no images.
+            if (listing.isSpinning)
+                listing.stop();
+        }
+        return false;
+    }
+    /**
+     * The Webflow path: the site asset library, then (with --cms) whichever CMS
+     * collections the flags select. Returns whether any CMS work was done, so the
+     * summary can remind the user to publish staging.
+     */
+    async processWebflow(flags, state) {
+        const auth = {
+            apiKey: flags['api-key'] ?? (await password({ mask: true, message: 'Webflow API token', validate: required })),
+            siteId: flags['site-id'] ?? (await input({ message: 'Webflow site ID', validate: required })),
+        };
+        // Resolved up front so a bad --only value fails before any transcription.
+        const collections = flags.cms ? await this.pickCollections(auth, flags.select, flags.only) : [];
+        await this.processAssets(auth, state);
+        for (const collection of collections) {
+            if (atLimit(state))
+                break;
+            // eslint-disable-next-line no-await-in-loop
+            await this.processCollection(auth, collection, state);
+        }
+        return collections.length > 0;
+    }
+    /**
+     * Count one image toward a --dry total from metadata already in hand — no
+     * download, no model. Applies --filter to decide caption-vs-skip; the caller
+     * has already logged the image line.
+     */
+    recordDry(state, meta) {
+        const detail = `${formatBytes(meta.fileSize)}, ${meta.width}x${meta.height}, ${meta.type}`;
+        // Bound locally so this reads as calling the filter, not Array#filter.
+        const { filter } = state;
+        if (filter && !filter(meta)) {
+            state.skipped.push(meta);
+            this.log(chalk.dim(`    – filtered out (${detail})`));
+            return;
+        }
+        state.transcribed++;
+        this.log(chalk.dim(`    ${chalk.green('✓')} would be captioned (${detail})`));
+    }
+    /** Totals and averages only — the per-image rows live in the --output-stats file. */
+    report(state, touchedCms, totalMs) {
+        const count = state.images.length;
+        const tokens = sum(state.images.map((image) => image.tokens));
+        const described = sum(state.images.map((image) => image.ms));
+        this.log('');
+        this.log(chalk.green(`✓ ${count} image${count === 1 ? '' : 's'} transcribed in ${formatMs(totalMs)}`));
+        if (count > 0) {
+            this.log(chalk.dim(`  ${formatCount(tokens)} tokens total, ${formatCount(Math.round(tokens / count))} avg`));
+            this.log(chalk.dim(`  ${formatMs(described / count)} avg per image`));
+            this.log(chalk.dim(`  ${formatBytes(sum(state.images.map((image) => image.meta.fileSize)) / count)} avg source size`));
+        }
+        if (state.skipped.length > 0) {
+            const skippedBytes = sum(state.skipped.map((meta) => meta.fileSize));
+            this.log(chalk.dim(`↷ ${state.skipped.length} image${state.skipped.length === 1 ? '' : 's'} skipped by filter`));
+            this.log(chalk.dim(`  ${formatBytes(skippedBytes)} total, ${formatBytes(skippedBytes / state.skipped.length)} avg source size`));
+        }
+        if (state.failures.length > 0) {
+            this.log(chalk.yellow(`⚠ ${state.failures.length} image${state.failures.length === 1 ? '' : 's'} could not be described`));
+        }
+        if (touchedCms) {
+            this.log(chalk.dim('CMS items were written to staging — publish the site in Webflow to make them live.'));
+        }
+    }
+    /**
+     * The --dry summary: how many images a real run would caption, the ones the
+     * --filter would skip, and any that couldn't even be downloaded. No tokens,
+     * time, or descriptions to report — nothing was described.
+     */
+    reportDry(state, totalMs) {
+        const count = state.transcribed;
+        this.log('');
+        this.log(chalk.green(`✓ ${formatCount(count)} image${count === 1 ? '' : 's'} would be captioned (dry run, ${formatMs(totalMs)})`));
+        if (Number.isFinite(state.limit) && count >= state.limit) {
+            this.log(chalk.dim(`  stopped at --limit ${state.limit}; a run without it may caption more`));
+        }
+        if (state.skipped.length > 0) {
+            const skippedBytes = sum(state.skipped.map((meta) => meta.fileSize));
+            this.log(chalk.dim(`↷ ${state.skipped.length} image${state.skipped.length === 1 ? '' : 's'} skipped by filter`));
+            this.log(chalk.dim(`  ${formatBytes(skippedBytes)} total, ${formatBytes(skippedBytes / state.skipped.length)} avg source size`));
+        }
+        if (state.failures.length > 0) {
+            this.log(chalk.yellow(`⚠ ${state.failures.length} image${state.failures.length === 1 ? '' : 's'} could not be downloaded`));
+        }
+    }
+    /** The --platform value, or ask when it was omitted. */
+    async resolvePlatform(flags) {
+        if (flags.platform === 'shopify' || flags.platform === 'webflow')
+            return flags.platform;
+        return select({
+            choices: [
+                { name: 'Webflow', value: 'webflow' },
+                { name: 'Shopify', value: 'shopify' },
+            ],
+            message: 'Which platform?',
+        });
+    }
+    /**
+     * Stop a spinner and undo ora's parting cursor move. On stop, ora's clear()
+     * runs cursorTo(indent) on its stream (stderr) — and since stdout shares the
+     * terminal's cursor, the very next this.log would start at that column and be
+     * pushed right by `indent` spaces. Resetting to column 0 keeps the following
+     * line at exactly the indent it asks for.
+     */
+    stopSpinner(spinner) {
+        spinner.stop();
+        if (process.stderr.isTTY)
+            process.stderr.cursorTo(0);
+    }
+    /**
+     * Write the Markdown report. This runs after everything else, so a run that
+     * gets this far has already written its alt text back to Webflow — failing to
+     * save the report loses the record, not the work, and the message says so.
+     */
+    async writeStats(path, state, model, host, totalMs) {
+        const target = resolve(path);
+        try {
+            await mkdir(dirname(target), { recursive: true });
+            await writeFile(target, buildStatsMarkdown(state, model, host, totalMs), 'utf8');
+        }
+        catch (error) {
+            this.error(`Alt text was written to Webflow, but the stats file could not be saved: ${error.message}`, {
+                code: '1',
+            });
+        }
+        this.log(chalk.dim(`Stats written to ${target}`));
+    }
+}

package/dist/commands/backfill-project.js

@@ -1,8 +1,8 @@
+import { generateClaudeMd, GITIGNORE_CONTENT, initPromptPath, SHOPIFYIGNORE_CONTENT, } from '#lib/scaffold.js';
 import { Args, Command } from '@oclif/core';
 import chalk from 'chalk';
 import { existsSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { generateClaudeMd, GITIGNORE_CONTENT, initPromptPath, SHOPIFYIGNORE_CONTENT, } from '../lib/scaffold.js';
 export default class BackfillProject extends Command {
     static args = {
         shop: Args.string({ description: 'Shopify store handle, passed to Claude as a hint', required: false }),