@firenet-designs/fnd-cli 2.3.3 → 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.3.3 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.3.3/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.3.3/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.3.3/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.3.3/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,20 +302,47 @@ 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>] [--remote-base <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
-  --delete-remote-dir    on exit, delete the remote workspace directory instead of leaving the synced copy in place
-  --devtools=<value>     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>.
-  --remote-base=<value>  [default: /home/fnd] base dir on the remote; the workspace lands at
-                         <base>/<local-user>/<dir-name>
-  --source=<option>      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>
-  --ssh=<value>          (required) remote to connect to, as user@host
+  --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
+
+  --devtools=<value>
+      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
+      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=<value>
+      [default: /home/fnd] base dir on the remote; the workspace lands at <base>/<local-user>/<dir-name>
+
+  --rpc=<value>
+      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
+      port=<port|remote:local>[,profile=<true|1|false|0>][,shell=<bash|batch|powershell|sh|zsh>] — 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=<option>
+      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>
+
+  --ssh=<value>
+      (required) remote to connect to, as user@host
 
 DESCRIPTION
   Open a remote workspace: two-way sync the current directory to a remote Linux box with Mutagen and drop into a shell
@@ -205,49 +361,20 @@ EXAMPLES
 
   $ fnd workspace --ssh user@host --remote-base /home/fnd
 
+  $ fnd workspace --ssh user@host --ignore-vcs
+
   $ fnd workspace --ssh user@host --devtools 9222
 
   $ fnd workspace --ssh user@host --devtools 9333:9222
 
-  $ fnd workspace --ssh user@host --delete-remote-dir
-```
-
-_See code: [src/commands/workspace/index.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.3/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>]
+  $ fnd workspace --ssh user@host --rpc port=7777:7700
 
-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)
-  --ssh=<value>          (required) remote to connect to, as user@host
+  $ fnd workspace --ssh user@host --rpc port=7777:7700,profile=false,shell=zsh
 
-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 to also strip the
-  matching chrome-devtools MCP entry from the remote (only do this if the dropped session used --devtools). 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 --ssh user@host --delete-remote-dir
 
-  $ 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.3.3/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;
+}