@firenet-designs/fnd-cli 2.4.0 → 2.6.0

package/README.md

@@ -20,7 +20,7 @@ $ npm install -g @firenet-designs/fnd-cli
 $ fnd COMMAND
 running command...
 $ fnd (--version)
-@firenet-designs/fnd-cli/2.4.0 linux-x64 node-v24.18.0
+@firenet-designs/fnd-cli/2.6.0 linux-x64 node-v24.18.0
 $ fnd --help [COMMAND]
 USAGE
   $ fnd COMMAND
@@ -29,13 +29,79 @@ USAGE
 <!-- usagestop -->
 # Commands
 <!-- commands -->
+* [`fnd alt-text`](#fnd-alt-text)
 * [`fnd backfill-project [SHOP]`](#fnd-backfill-project-shop)
+* [`fnd caption`](#fnd-caption)
 * [`fnd create-app`](#fnd-create-app)
 * [`fnd create-project [SHOP]`](#fnd-create-project-shop)
 * [`fnd help [COMMAND]`](#fnd-help-command)
 * [`fnd token`](#fnd-token)
 * [`fnd workspace`](#fnd-workspace)
-* [`fnd workspace cleanup`](#fnd-workspace-cleanup)
+
+## `fnd alt-text`
+
+Generate alt text for a site's images with a local Ollama vision model and write it back.
+
+```
+USAGE
+  $ fnd alt-text [--api-key <value> --webflow] [--filter <value>] [--limit <value>] [--ollama-host <value>]
+    [--ollama-model <value>] [--only <value>... [--cms ]] [--output-stats <value>] [--select ] [--shopify | ] [--site-id
+    <value> ] [--skip]
+
+FLAGS
+  --api-key=<value>       Webflow API token (site-scoped). Prompted for if omitted.
+  --cms                   also add alt text to the images in CMS collection items. Off by default — only the site asset
+                          library is walked.
+  --filter=<value>        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=<value>         stop after this many images have been transcribed (counted across assets and CMS together)
+  --ollama-host=<value>   base URL of the Ollama server. Prompted for if omitted.
+  --ollama-model=<value>  the model used to describe the images. Omit it to pick from the vision-capable models pulled
+                          on the host.
+  --only=<value>...       only touch these CMS collections, matched case-insensitively against a collection's name or
+                          slug. Repeat the flag for more than one.
+  --output-stats=<value>  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.
+  --select                fetch the CMS collections and pick which ones to process interactively
+  --shopify               run against a Shopify store (not implemented yet)
+  --site-id=<value>       Webflow site ID. Prompted for if omitted.
+  --skip                  leave images that already have alt text alone instead of overwriting them
+  --webflow               run against a Webflow site
+
+DESCRIPTION
+  Generate alt text for a site's images with a local Ollama vision model and write it back.
+
+  Walks the Webflow site asset library and (with --cms) the image fields of CMS collection items, describes every image
+  that needs alt text, and PATCHes the description back. Images are fetched and described one at a time — a single local
+  model gains nothing from concurrency, and Webflow rate-limits. Nothing leaves your network except the Webflow API
+  calls.
+
+  CMS writes go to STAGING, so publish the site in Webflow to make them live. Any required flag you omit is prompted
+  for.
+
+ALIASES
+  $ fnd caption
+
+EXAMPLES
+  $ fnd alt-text --webflow --api-key <key> --site-id <id> --ollama-host http://localhost:11434 --ollama-model qwen3-vl:8b
+
+  $ fnd alt-text --webflow --skip --limit 20
+
+  $ fnd alt-text --webflow --cms --select
+
+  $ fnd alt-text --webflow --cms --only products --only sku
+
+  $ fnd alt-text --webflow --output-stats ./alt-text-run.md
+
+  $ fnd alt-text --webflow --filter "fileSize>=sizes.KB(100) && width>=100 && height>=100"
+
+  $ fnd alt-text --webflow --filter "type !== 'svg' && !url.includes('/icons/')"
+```
+
+_See code: [src/commands/alt-text.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.6.0/src/commands/alt-text.ts)_
 
 ## `fnd backfill-project [SHOP]`
 
@@ -62,7 +128,70 @@ EXAMPLES
   $ fnd backfill-project my-store "extra hints"
 ```
 
-_See code: [src/commands/backfill-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.4.0/src/commands/backfill-project.ts)_
+_See code: [src/commands/backfill-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.6.0/src/commands/backfill-project.ts)_
+
+## `fnd caption`
+
+Generate alt text for a site's images with a local Ollama vision model and write it back.
+
+```
+USAGE
+  $ fnd caption [--api-key <value> --webflow] [--filter <value>] [--limit <value>] [--ollama-host <value>]
+    [--ollama-model <value>] [--only <value>... [--cms ]] [--output-stats <value>] [--select ] [--shopify | ] [--site-id
+    <value> ] [--skip]
+
+FLAGS
+  --api-key=<value>       Webflow API token (site-scoped). Prompted for if omitted.
+  --cms                   also add alt text to the images in CMS collection items. Off by default — only the site asset
+                          library is walked.
+  --filter=<value>        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=<value>         stop after this many images have been transcribed (counted across assets and CMS together)
+  --ollama-host=<value>   base URL of the Ollama server. Prompted for if omitted.
+  --ollama-model=<value>  the model used to describe the images. Omit it to pick from the vision-capable models pulled
+                          on the host.
+  --only=<value>...       only touch these CMS collections, matched case-insensitively against a collection's name or
+                          slug. Repeat the flag for more than one.
+  --output-stats=<value>  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.
+  --select                fetch the CMS collections and pick which ones to process interactively
+  --shopify               run against a Shopify store (not implemented yet)
+  --site-id=<value>       Webflow site ID. Prompted for if omitted.
+  --skip                  leave images that already have alt text alone instead of overwriting them
+  --webflow               run against a Webflow site
+
+DESCRIPTION
+  Generate alt text for a site's images with a local Ollama vision model and write it back.
+
+  Walks the Webflow site asset library and (with --cms) the image fields of CMS collection items, describes every image
+  that needs alt text, and PATCHes the description back. Images are fetched and described one at a time — a single local
+  model gains nothing from concurrency, and Webflow rate-limits. Nothing leaves your network except the Webflow API
+  calls.
+
+  CMS writes go to STAGING, so publish the site in Webflow to make them live. Any required flag you omit is prompted
+  for.
+
+ALIASES
+  $ fnd caption
+
+EXAMPLES
+  $ fnd caption --webflow --api-key <key> --site-id <id> --ollama-host http://localhost:11434 --ollama-model qwen3-vl:8b
+
+  $ fnd caption --webflow --skip --limit 20
+
+  $ fnd caption --webflow --cms --select
+
+  $ fnd caption --webflow --cms --only products --only sku
+
+  $ fnd caption --webflow --output-stats ./alt-text-run.md
+
+  $ fnd caption --webflow --filter "fileSize>=sizes.KB(100) && width>=100 && height>=100"
+
+  $ fnd caption --webflow --filter "type !== 'svg' && !url.includes('/icons/')"
+```
 
 ## `fnd create-app`
 
@@ -83,11 +212,11 @@ EXAMPLES
   $ fnd create-app
 ```
 
-_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.4.0/src/commands/create-app.ts)_
+_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.6.0/src/commands/create-app.ts)_
 
 ## `fnd create-project [SHOP]`
 
-Scaffold a new client project: git on branch production, ignore files, Shopify theme pull, a Claude-generated CLAUDE.md, then a private GitHub repo under the FireNet-Designs org.
+Scaffold a new client project: git on branch production, ignore files, Shopify theme pull, a Claude-generated CLAUDE.md, then a private GitHub repo under the FireNet-Designs org with production and staging branches pushed.
 
 ```
 USAGE
@@ -98,7 +227,7 @@ ARGUMENTS
 
 DESCRIPTION
   Scaffold a new client project: git on branch production, ignore files, Shopify theme pull, a Claude-generated
-  CLAUDE.md, then a private GitHub repo under the FireNet-Designs org.
+  CLAUDE.md, then a private GitHub repo under the FireNet-Designs org with production and staging branches pushed.
 
   Requires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.
 
@@ -113,7 +242,7 @@ EXAMPLES
   $ fnd create-project my-store "Acme storefront, Klaviyo"
 ```
 
-_See code: [src/commands/create-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.4.0/src/commands/create-project.ts)_
+_See code: [src/commands/create-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.6.0/src/commands/create-project.ts)_
 
 ## `fnd help [COMMAND]`
 
@@ -165,7 +294,7 @@ EXAMPLES
   $ fnd token -s mystore -i <id> -c <secret> --write ./.mcp.json
 ```
 
-_See code: [src/commands/token.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.4.0/src/commands/token.ts)_
+_See code: [src/commands/token.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.6.0/src/commands/token.ts)_
 
 ## `fnd workspace`
 
@@ -173,10 +302,16 @@ Open a remote workspace: two-way sync the current directory to a remote Linux bo
 
 ```
 USAGE
-  $ fnd workspace --ssh <value> [--delete-remote-dir] [--devtools <value>] [--ignore-vcs] [--remote-base
-    <value>] [--rpc <value>] [--source remote|local]
+  $ fnd workspace --ssh <value> [--cleanup] [--delete-remote-dir] [--devtools <value>] [--ignore-vcs]
+    [--remote-base <value>] [--rpc <value>] [--source remote|local]
 
 FLAGS
+  --cleanup
+      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
       on exit, delete the remote workspace directory instead of leaving the synced copy in place
 
@@ -237,47 +372,9 @@ EXAMPLES
   $ fnd workspace --ssh user@host --rpc port=7777:7700,profile=false,shell=zsh
 
   $ fnd workspace --ssh user@host --delete-remote-dir
-```
-
-_See code: [src/commands/workspace/index.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.4.0/src/commands/workspace/index.ts)_
-
-## `fnd workspace cleanup`
-
-Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.
-
-```
-USAGE
-  $ fnd workspace cleanup --ssh <value> [--delete-remote-dir] [--devtools] [--remote-base <value>] [--remote-dir
-    <value>] [--rpc]
-
-FLAGS
-  --delete-remote-dir    also delete the remote workspace directory (by default the synced files are left in place)
-  --devtools             also strip the chrome-devtools MCP entry from the remote (only if the dropped session used
-                         --devtools)
-  --remote-base=<value>  [default: /home/fnd] base dir on the remote, used to derive the default remote directory path
-  --remote-dir=<value>   exact remote directory to target (defaults to the current dir mapping)
-  --rpc                  also strip the local-shell MCP entry from the remote (only if the dropped session used --rpc)
-  --ssh=<value>          (required) remote to connect to, as user@host
-
-DESCRIPTION
-  Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.
-
-  Terminates any Mutagen sync sessions this machine started for the directory. Pass --devtools or --rpc to also strip
-  the matching MCP entries from the remote (only do this if the dropped session used those flags). With no --remote-dir,
-  it targets the same path `workspace` would use for the current directory. The synced files themselves are left in
-  place unless you pass --delete-remote-dir.
-
-EXAMPLES
-  $ fnd workspace cleanup --ssh user@host
-
-  $ fnd workspace cleanup --ssh user@host --remote-dir /home/fnd/cole/fnd-cli
-
-  $ fnd workspace cleanup --ssh user@host --devtools
-
-  $ fnd workspace cleanup --ssh user@host --rpc
 
-  $ fnd workspace cleanup --ssh user@host --delete-remote-dir
+  $ fnd workspace --ssh user@host --rpc 7700 --cleanup
 ```
 
-_See code: [src/commands/workspace/cleanup.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.4.0/src/commands/workspace/cleanup.ts)_
+_See code: [src/commands/workspace/index.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.6.0/src/commands/workspace/index.ts)_
 <!-- commandsstop -->

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

@@ -0,0 +1,56 @@
+import { Command } from '@oclif/core';
+export default class AltText extends Command {
+    static aliases: string[];
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        cms: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        filter: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        limit: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'ollama-host': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'ollama-model': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        only: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'output-stats': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        select: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        shopify: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'site-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        skip: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        webflow: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    /**
+     * 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.
+     */
+    private describe;
+    /** Which CMS collections this run should walk. */
+    private pickCollections;
+    /**
+     * 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.
+     */
+    private pickModel;
+    /** The site asset library pass. Always runs; --cms only adds work on top of it. */
+    private processAssets;
+    private processCollection;
+    /**
+     * 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.
+     */
+    private processItem;
+    /** Totals and averages only — the per-image rows live in the --output-stats file. */
+    private report;
+    /** --webflow / --shopify, or ask when neither was given. */
+    private resolvePlatform;
+    /**
+     * 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.
+     */
+    private writeStats;
+}