@firenet-designs/fnd-cli 2.3.3 → 2.6.0

package/dist/commands/workspace/index.js

@@ -1,18 +1,28 @@
 import { Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
 import { spawn } from 'node:child_process';
-import { browserDebugInstructions, buildContext, buildMutagenCreateArgs, buildMutagenFlushArgs, buildMutagenTerminateArgs, buildRemoteScript, DEFAULT_MOUNT_BASE, hasMutagen, hasSshClient, isLocalDebugPortLive, mutagenInstallInstructions, parseDevtoolsPort, parseSshTarget, runMutagen, runRemoteCleanup, } from '../../lib/workspace.js';
+import { basename } from 'node:path';
+import { hasLocalShell, parseRpcFlag, RPC_FLAG_EXAMPLES, RPC_FLAG_USAGE, startRpcServer } from '../../lib/rpc.js';
+import { browserDebugInstructions, buildContext, buildMutagenCreateArgs, buildMutagenFlushArgs, buildMutagenTerminateArgs, buildMutagenTerminateSelectorArgs, buildRemoteScript, DEFAULT_MOUNT_BASE, hasMutagen, hasSshClient, isLocalDebugPortLive, mutagenInstallInstructions, parsePortPair, parseSshTarget, runMutagen, runRemoteCleanup, slugify, } from '../../lib/workspace.js';
 export default class Workspace extends Command {
     static description = 'Open a remote workspace: two-way sync the current directory to a remote Linux box with Mutagen and drop into a shell there, tearing the sync down on exit.\n\nBoth sides keep a real copy on local disk and only deltas cross the network, so the remote reads files at native speed. Conflicting edits on both ends are flagged rather than silently overwritten; pass --source to auto-resolve them in favour of one side. Mutagen connects the normal direction (this machine → remote over SSH) and auto-deploys its agent to the remote, so no local SSH server, reverse tunnel, or authorized_keys trust is required. You need the Mutagen CLI installed on THIS machine.';
     static examples = [
         '<%= config.bin %> <%= command.id %> --ssh user@203.0.113.4',
         '<%= config.bin %> <%= command.id %> --ssh user@host --source local',
         '<%= config.bin %> <%= command.id %> --ssh user@host --remote-base /home/fnd',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --ignore-vcs',
         '<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9222',
         '<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9333:9222',
+        `<%= config.bin %> <%= command.id %> --ssh user@host --rpc ${RPC_FLAG_EXAMPLES.required}`,
+        `<%= config.bin %> <%= command.id %> --ssh user@host --rpc ${RPC_FLAG_EXAMPLES.full}`,
         '<%= config.bin %> <%= command.id %> --ssh user@host --delete-remote-dir',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --rpc 7700 --cleanup',
     ];
     static flags = {
+        cleanup: Flags.boolean({
+            default: false,
+            description: "tear down a leftover session instead of opening one — don't connect, just terminate this directory's Mutagen sync and (using whatever other flags are set) strip the remote --devtools/--rpc MCP entries and, with --delete-remote-dir, remove the remote dir. Re-run your original command with --cleanup appended after a session that dropped without cleaning up.",
+        }),
         'delete-remote-dir': Flags.boolean({
             default: false,
             description: 'on exit, delete the remote workspace directory instead of leaving the synced copy in place',
@@ -20,10 +30,17 @@ export default class Workspace extends Command {
         devtools: Flags.string({
             description: 'expose your LOCAL browser to Claude on the remote via the chrome-devtools MCP. Value is "port" (same port both ends) or "remote:local" (local = this machine, where the browser runs). Your browser must already be listening with --remote-debugging-port=<local>.',
         }),
+        'ignore-vcs': Flags.boolean({
+            default: false,
+            description: "don't sync paths matched by the project's .gitignore files (node_modules, build output, …) so each side keeps its own platform-specific artifacts. Every .gitignore in the tree is honoured relative to its directory, like git does. The .git directory itself still syncs, so the remote stays a working repo.",
+        }),
         'remote-base': Flags.string({
             default: DEFAULT_MOUNT_BASE,
             description: 'base dir on the remote; the workspace lands at <base>/<local-user>/<dir-name>',
         }),
+        rpc: Flags.string({
+            description: `expose a run_local_command MCP tool to Claude on the remote that executes commands back on THIS machine (the one running fnd workspace). Value is ${RPC_FLAG_USAGE} — port opens a reverse tunnel (ssh -R <remote>:localhost:<local>) to a command server started here; shell defaults to the shell fnd workspace was called from; profile (default true) controls whether the shell loads its startup files — with it on, POSIX shells run interactively (-i) so rc files like ~/.bashrc or ~/.zshrc are sourced and tools such as nvm work.`,
+        }),
         source: Flags.string({
             description: 'which side wins on conflict: "remote" = this server (where the workspace shell runs), "local" = the machine you ran fnd workspace from. Omit to flag conflicts instead of auto-resolving them.',
             options: ['remote', 'local'],
@@ -37,14 +54,28 @@ export default class Workspace extends Command {
         const { flags } = await this.parse(Workspace);
         const target = parseSshTarget(flags.ssh);
         const target2 = `${target.user}@${target.host}`;
-        const devtools = flags.devtools === undefined ? undefined : parseDevtoolsPort(flags.devtools);
+        // --cleanup short-circuits everything: no connection, no sync, just tear down
+        // leftovers from a session that dropped before it could clean up. The other
+        // flags are reused for *what* to clean up (devtools/rpc MCP entries, dir), and
+        // any that don't matter here are ignored — so `↑` + ` --cleanup` just works.
+        if (flags.cleanup) {
+            await this.runCleanup(target2, flags);
+            return;
+        }
+        const devtools = flags.devtools === undefined ? undefined : parsePortPair(flags.devtools, '--devtools');
+        const rpc = flags.rpc === undefined ? undefined : parseRpcFlag(flags.rpc);
+        if (devtools && rpc && devtools.remote === rpc.ports.remote) {
+            this.error(`--devtools and --rpc cannot share remote port ${rpc.ports.remote}.`, { code: '1' });
+        }
         const ctx = buildContext({
             cwd: process.cwd(),
             devtools,
+            ignoreVcs: flags['ignore-vcs'],
             remoteBase: flags['remote-base'],
+            rpc,
             source: flags.source,
         });
-        await this.preflight(devtools);
+        await this.preflight(devtools, rpc);
         this.printPlan(ctx, target2);
         // Start the two-way sync. Mutagen auto-deploys its agent to the remote over SSH.
         this.log(chalk.dim('Starting the Mutagen sync session…'));
@@ -53,6 +84,7 @@ export default class Workspace extends Command {
             this.error(`mutagen sync create failed (exit ${createCode}). Check that the remote is reachable over SSH and try again.`, { code: '1' });
         }
         const deleteRemoteDir = flags['delete-remote-dir'];
+        let rpcServer;
         let code;
         try {
             // Block until the first full sync lands so the files exist before the shell opens.
@@ -61,33 +93,30 @@ export default class Workspace extends Command {
             if (flushCode !== 0) {
                 this.error(`Initial mutagen sync flush failed (exit ${flushCode}).`, { code: '1' });
             }
+            // Start the local command server the --rpc tunnel points back to.
+            if (ctx.rpc) {
+                try {
+                    rpcServer = await startRpcServer(ctx.rpc, ctx.localCwd);
+                    this.log(chalk.dim(`Local RPC command server (${ctx.rpc.shell}) listening on 127.0.0.1:${ctx.rpc.ports.local}.`));
+                }
+                catch (error) {
+                    this.error(`Could not start the local RPC server on 127.0.0.1:${ctx.rpc.ports.local} (${error.message}). Is the port already in use?`, { code: '1' });
+                }
+            }
             const script = buildRemoteScript(ctx);
-            code = await this.runSsh(target2, script, ctx.devtools);
+            code = await this.runSsh(target2, script, ctx);
         }
         finally {
-            // Best-effort: flush the last edits back, then tear the session down.
+            // Best-effort: stop serving local commands, flush the last edits back, then
+            // tear the session down.
+            await rpcServer?.close().catch(() => { });
             this.log('');
             this.log(chalk.dim('Flushing final changes and stopping the sync…'));
             await runMutagen(buildMutagenFlushArgs(ctx.syncName)).catch(() => 1);
             await runMutagen(buildMutagenTerminateArgs(ctx.syncName)).catch(() => 1);
-            // Reach back to the remote if we left a devtools MCP config there to remove,
-            // or if we were asked to delete the synced directory.
-            if (ctx.devtools || deleteRemoteDir) {
-                const actions = [
-                    ctx.devtools ? 'removing the remote chrome-devtools MCP config' : undefined,
-                    deleteRemoteDir ? 'deleting the remote dir' : undefined,
-                ].filter(Boolean);
-                this.log(chalk.dim(`${actions.join(' and ')}…`.replace(/^./, (c) => c.toUpperCase())));
-                try {
-                    await runRemoteCleanup(target2, ctx.remoteDir, {
-                        deleteRemoteDir,
-                        removeDevtoolsMcp: Boolean(ctx.devtools),
-                    });
-                }
-                catch (error) {
-                    this.log(chalk.yellow(`Could not reach the remote to clean up (${error.message}).`));
-                }
-            }
+            // Reach back to the remote if we left MCP config there to remove, or if we
+            // were asked to delete the synced directory.
+            await this.teardownRemote(ctx, target2, deleteRemoteDir);
         }
         this.log('');
         this.log(code === 0
@@ -97,7 +126,7 @@ export default class Workspace extends Command {
             : chalk.yellow(`Session ended with exit code ${code}. Cleanup attempted above.`));
     }
     /** Verify this machine can drive the sync before we connect. */
-    async preflight(devtools) {
+    async preflight(devtools, rpc) {
         if (!hasSshClient()) {
             this.error('No `ssh` client found on PATH. Install OpenSSH client and try again.', { code: '1' });
         }
@@ -120,6 +149,13 @@ export default class Workspace extends Command {
                 this.error('Local browser remote-debugging port is required for --devtools. Aborting.', { code: '1' });
             }
         }
+        // With --rpc, confirm the chosen shell is runnable on THIS machine — it's the
+        // shell the remote AI's commands will execute under, right here.
+        if (rpc && !hasLocalShell(rpc.shell, rpc.profile)) {
+            this.error(`--rpc shell "${rpc.shell}" is not runnable on this machine. Aborting before connecting.`, {
+                code: '1',
+            });
+        }
     }
     printPlan(ctx, target) {
         const sync = ctx.source === undefined
@@ -130,20 +166,72 @@ export default class Workspace extends Command {
         this.log(`  ${chalk.dim('local dir:')}   ${ctx.localCwd}`);
         this.log(`  ${chalk.dim('remote dir:')}  ${ctx.remoteDir}`);
         this.log(`  ${chalk.dim('sync:')}        ${sync}`);
+        if (ctx.ignores) {
+            this.log(`  ${chalk.dim('ignoring:')}    ${ctx.ignores.length} pattern${ctx.ignores.length === 1 ? '' : 's'} from .gitignore files (--ignore-vcs)`);
+        }
         if (ctx.devtools) {
             this.log(`  ${chalk.dim('devtools:')}     remote 127.0.0.1:${ctx.devtools.remote} → local browser 127.0.0.1:${ctx.devtools.local}`);
         }
+        if (ctx.rpc) {
+            this.log(`  ${chalk.dim('rpc:')}         remote 127.0.0.1:${ctx.rpc.ports.remote} → local ${ctx.rpc.shell} commands via 127.0.0.1:${ctx.rpc.ports.local}`);
+        }
         this.log('');
     }
+    /**
+     * Tear down leftovers from a session that dropped before cleaning up (--cleanup).
+     * Terminates this directory's Mutagen sync sessions locally, then reaches the
+     * remote to strip the MCP entries the matching flags imply and, with
+     * --delete-remote-dir, remove the synced dir. devtools/rpc are read for
+     * presence only — their port values are irrelevant to removal.
+     */
+    async runCleanup(target, flags) {
+        if (!hasSshClient()) {
+            this.error('No `ssh` client found on PATH. Install OpenSSH client and try again.', { code: '1' });
+        }
+        const removeDevtoolsMcp = flags.devtools !== undefined;
+        const removeRpcMcp = flags.rpc !== undefined;
+        const deleteRemoteDir = flags['delete-remote-dir'];
+        const { remoteDir } = buildContext({ cwd: process.cwd(), remoteBase: flags['remote-base'] });
+        const slug = slugify(basename(remoteDir));
+        this.log(chalk.bold('Cleaning up workspace'));
+        this.log(`  ${chalk.dim('remote:')}     ${target}`);
+        this.log(`  ${chalk.dim('remote dir:')} ${remoteDir}`);
+        this.log('');
+        // Terminate any lingering sync sessions for this directory (a local Mutagen op).
+        if (hasMutagen()) {
+            this.log(chalk.dim('Terminating any leftover Mutagen sync sessions…'));
+            await runMutagen(buildMutagenTerminateSelectorArgs(slug)).catch(() => 1);
+        }
+        else {
+            this.log(chalk.yellow('Mutagen CLI not found on PATH — skipping sync termination.'));
+        }
+        if (removeDevtoolsMcp) {
+            this.log(chalk.dim('Removing any leftover chrome-devtools MCP config on the remote…'));
+        }
+        if (removeRpcMcp) {
+            this.log(chalk.dim('Removing any leftover local-shell MCP config on the remote…'));
+        }
+        if (deleteRemoteDir) {
+            this.log(chalk.dim('Deleting the remote workspace directory…'));
+        }
+        const code = await runRemoteCleanup(target, remoteDir, { deleteRemoteDir, removeDevtoolsMcp, removeRpcMcp });
+        if (code === 0) {
+            this.log(chalk.green('✓ Done.'));
+        }
+        else {
+            this.error(`Remote cleanup ssh session exited with code ${code}.`, { code: '1' });
+        }
+    }
     /** Run the interactive ssh session, inheriting the TTY so the remote shell is fully interactive. */
-    runSsh(target, script, devtools) {
+    runSsh(target, script, ctx) {
+        // Reverse tunnels: remote 127.0.0.1:<remote> → this machine's 127.0.0.1:<local>.
+        // --devtools points one at the local browser's debug port; --rpc points one at
+        // the local command server, so the remote's MCPs can reach them.
+        const forwards = [ctx.devtools, ctx.rpc?.ports].filter((f) => f !== undefined);
         const args = [
             '-t', // allocate a remote PTY for the interactive shell session
-            // Reverse tunnel for --devtools only: remote 127.0.0.1:<remote> → this
-            // machine's browser at 127.0.0.1:<local>, so the remote's MCP can reach it.
-            ...(devtools
-                ? ['-o', 'ExitOnForwardFailure=yes', '-R', `${devtools.remote}:localhost:${devtools.local}`]
-                : []),
+            ...(forwards.length > 0 ? ['-o', 'ExitOnForwardFailure=yes'] : []),
+            ...forwards.flatMap((f) => ['-R', `${f.remote}:localhost:${f.local}`]),
             target,
             script,
         ];
@@ -153,4 +241,30 @@ export default class Workspace extends Command {
             child.once('close', (code) => resolve(code ?? 0));
         });
     }
+    /**
+     * Best-effort: reach back to the remote after the session to strip any MCP
+     * config this run registered and, with --delete-remote-dir, remove the synced
+     * dir. No-op when the session left nothing behind to clean. A failure here is
+     * logged, not thrown — the local sync is already torn down by this point.
+     */
+    async teardownRemote(ctx, target, deleteRemoteDir) {
+        if (!ctx.devtools && !ctx.rpc && !deleteRemoteDir)
+            return;
+        const actions = [
+            ctx.devtools ? 'removing the remote chrome-devtools MCP config' : undefined,
+            ctx.rpc ? 'removing the remote local-shell MCP config' : undefined,
+            deleteRemoteDir ? 'deleting the remote dir' : undefined,
+        ].filter(Boolean);
+        this.log(chalk.dim(`${actions.join(' and ')}…`.replace(/^./, (c) => c.toUpperCase())));
+        try {
+            await runRemoteCleanup(target, ctx.remoteDir, {
+                deleteRemoteDir,
+                removeDevtoolsMcp: Boolean(ctx.devtools),
+                removeRpcMcp: Boolean(ctx.rpc),
+            });
+        }
+        catch (error) {
+            this.log(chalk.yellow(`Could not reach the remote to clean up (${error.message}).`));
+        }
+    }
 }

package/dist/hooks/init/check-for-updates.js

@@ -9,7 +9,7 @@ const hook = async function (opts) {
         });
     });
     if (newestVersion !== opts.config.pjson.version) {
-        console.log(chalk.yellow('💡 Version', chalk.green(newestVersion), 'available! Run', chalk.green('`npm i -g git@github.com:FireNet-Designs/fnd-cli.git`'), 'to update to the latest version!\n'));
+        console.log(chalk.yellow('💡 Version', chalk.green(newestVersion), 'available! Run', chalk.green('`npm i -g @firenet-designs/fnd-cli`'), 'to update to the latest version!\n'));
     }
 };
 export default hook;

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/kv-flag.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+type KvShape = Record<string, z.ZodType>;
+/** Usage string for the schema, required keys first: `a=<...>,b=<...>[,c=<...>]`. */
+export declare const kvUsage: (schema: z.ZodObject<KvShape>) => string;
+/** Example flag value built from each field's example meta (falls back to its hint), required keys first. */
+export declare const kvExample: (schema: z.ZodObject<KvShape>, opts?: {
+    requiredOnly?: boolean;
+}) => string;
+/**
+ * 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 declare const parseKvFlag: <T extends KvShape>(flag: string, raw: string, schema: z.ZodObject<T>) => z.output<z.ZodObject<T>>;
+export {};