@firenet-designs/fnd-cli 2.4.0 → 2.7.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.7.0 node-v24.18.0
 $ fnd --help [COMMAND]
 USAGE
   $ fnd COMMAND
@@ -29,13 +29,90 @@ 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>] [--dry] [--filter <value>] [--limit <value>] [--ollama-host <value>]
+    [--ollama-model <value>] [--only <value>... --cms] [--output-stats <value>] [--platform webflow|shopify] [--select ]
+    [--site-id <value>] [--skip]
+
+FLAGS
+  --api-key=<value>       Webflow API token (site-scoped). Webflow only — Shopify auth comes from the Shopify CLI.
+                          Prompted for if omitted.
+  --cms                   also add alt text to the images in CMS collection items. Webflow only. Off by default — only
+                          the site asset library is walked.
+  --dry                   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=<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.
+  --platform=<option>     which platform to run against. Prompted for if omitted.
+                          <options: webflow|shopify>
+  --select                fetch the CMS collections and pick which ones to process interactively
+  --site-id=<value>       Webflow site ID, or the Shopify store (mystore or mystore.myshopify.com). Prompted for if
+                          omitted.
+  --skip                  leave images that already have alt text alone instead of overwriting them
+
+DESCRIPTION
+  Generate alt text for a site's images with a local Ollama vision model and write it back.
+
+  Pick 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.
+
+  Webflow 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 --platform webflow --api-key <key> --site-id <id> --ollama-host http://localhost:11434 --ollama-model qwen3-vl:8b
+
+  $ fnd alt-text --platform shopify --site-id mystore
+
+  $ fnd alt-text --platform shopify --site-id mystore --dry
+
+  $ fnd alt-text --platform webflow --skip --limit 20
+
+  $ fnd alt-text --platform webflow --cms --select
+
+  $ fnd alt-text --platform webflow --cms --only products --only sku
+
+  $ fnd alt-text --platform webflow --output-stats ./alt-text-run.md
+
+  $ fnd alt-text --platform webflow --filter "fileSize>=sizes.KB(100) && width>=100 && height>=100"
+
+  $ fnd alt-text --platform webflow --filter "type !== 'svg' && !url.includes('/icons/')"
+```
+
+_See code: [src/commands/alt-text.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.7.0/src/commands/alt-text.ts)_
 
 ## `fnd backfill-project [SHOP]`
 
@@ -62,7 +139,81 @@ 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.7.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>] [--dry] [--filter <value>] [--limit <value>] [--ollama-host <value>]
+    [--ollama-model <value>] [--only <value>... --cms] [--output-stats <value>] [--platform webflow|shopify] [--select ]
+    [--site-id <value>] [--skip]
+
+FLAGS
+  --api-key=<value>       Webflow API token (site-scoped). Webflow only — Shopify auth comes from the Shopify CLI.
+                          Prompted for if omitted.
+  --cms                   also add alt text to the images in CMS collection items. Webflow only. Off by default — only
+                          the site asset library is walked.
+  --dry                   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=<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.
+  --platform=<option>     which platform to run against. Prompted for if omitted.
+                          <options: webflow|shopify>
+  --select                fetch the CMS collections and pick which ones to process interactively
+  --site-id=<value>       Webflow site ID, or the Shopify store (mystore or mystore.myshopify.com). Prompted for if
+                          omitted.
+  --skip                  leave images that already have alt text alone instead of overwriting them
+
+DESCRIPTION
+  Generate alt text for a site's images with a local Ollama vision model and write it back.
+
+  Pick 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.
+
+  Webflow 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 --platform webflow --api-key <key> --site-id <id> --ollama-host http://localhost:11434 --ollama-model qwen3-vl:8b
+
+  $ fnd caption --platform shopify --site-id mystore
+
+  $ fnd caption --platform shopify --site-id mystore --dry
+
+  $ fnd caption --platform webflow --skip --limit 20
+
+  $ fnd caption --platform webflow --cms --select
+
+  $ fnd caption --platform webflow --cms --only products --only sku
+
+  $ fnd caption --platform webflow --output-stats ./alt-text-run.md
+
+  $ fnd caption --platform webflow --filter "fileSize>=sizes.KB(100) && width>=100 && height>=100"
+
+  $ fnd caption --platform webflow --filter "type !== 'svg' && !url.includes('/icons/')"
+```
 
 ## `fnd create-app`
 
@@ -83,11 +234,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.7.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 +249,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 +264,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.7.0/src/commands/create-project.ts)_
 
 ## `fnd help [COMMAND]`
 
@@ -165,7 +316,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.7.0/src/commands/token.ts)_
 
 ## `fnd workspace`
 
@@ -173,10 +324,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>] [--site-id <value>] [--source remote|local] [--with-tool <value>...]
 
 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/--with-tool 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
 
@@ -193,13 +350,10 @@ FLAGS
   --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.
+  --site-id=<value>
+      the Shopify store (mystore or mystore.myshopify.com) the Shopify --with-tool tools operate on. Required when any
+      Shopify tool (shopify-file-* or shopify-execute) is selected; fixing the store here is a safety boundary — the
+      remote AI cannot target another store.
 
   --source=<option>
       which side wins on conflict: "remote" = this server (where the workspace shell runs), "local" = the machine you ran
@@ -209,6 +363,21 @@ FLAGS
   --ssh=<value>
       (required) remote to connect to, as user@host
 
+  --with-tool=<value>...
+      expose an fnd tool to Claude on the remote via a loopback MCP server on THIS machine (the one running fnd
+      workspace), reached through a reverse tunnel. Repeatable. Value is <name> or <name>[options]; available:
+      shopify-execute[<scopes=all|<list>[,ask]>], shopify-file-delete[[<ask>]], shopify-file-replace[[<ask>]],
+      shopify-file-search[[<ask>]], shopify-file-upload[[<ask>]]. e.g. shopify-file-upload (with --site-id mystore) lets
+      the remote AI upload files from the workspace into that Shopify store using your local Shopify CLI;
+      shopify-file-replace and shopify-file-delete add in-place replace and delete; shopify-file-search looks up files by
+      name/size/type/url (metadata only, no image bytes) to dedupe before upload or find oversized images; shopify-execute
+      runs arbitrary Admin GraphQL and REQUIRES a scopes option — shopify-execute[scopes=all] for broad access or
+      shopify-execute[scopes=read_products+write_orders] for an explicit set (which the store is then trimmed to, revoking
+      anything extra, so the AI is held to least privilege). Append ,ask (e.g. shopify-file-delete[ask],
+      shopify-execute[ask,scopes=all]) to make that tool prompt for confirmation before EVERY call, even under the
+      remote's auto-accept/bypass permissions — use it to gate the powerful/destructive tools. Prerequisites (auth,
+      scopes) are checked and set up before connecting.
+
 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.
@@ -232,52 +401,20 @@ EXAMPLES
 
   $ fnd workspace --ssh user@host --devtools 9333:9222
 
-  $ fnd workspace --ssh user@host --rpc port=7777:7700
+  $ fnd workspace --ssh user@host --with-tool shopify-file-upload --site-id mystore
 
-  $ fnd workspace --ssh user@host --rpc port=7777:7700,profile=false,shell=zsh
+  $ fnd workspace --ssh user@host --with-tool shopify-file-upload --with-tool shopify-file-search --with-tool "shopify-file-delete[ask]" --site-id mystore
 
-  $ 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]
+  $ fnd workspace --ssh user@host --with-tool shopify-file-upload --with-tool shopify-file-replace --with-tool shopify-file-delete --site-id mystore.myshopify.com
 
-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.
+  $ fnd workspace --ssh user@host --with-tool "shopify-execute[scopes=read_products+read_orders]" --site-id mystore
 
-EXAMPLES
-  $ fnd workspace cleanup --ssh user@host
-
-  $ fnd workspace cleanup --ssh user@host --remote-dir /home/fnd/cole/fnd-cli
+  $ fnd workspace --ssh user@host --with-tool "shopify-execute[ask,scopes=all]" --site-id mystore
 
-  $ fnd workspace cleanup --ssh user@host --devtools
-
-  $ fnd workspace cleanup --ssh user@host --rpc
+  $ fnd workspace --ssh user@host --delete-remote-dir
 
-  $ fnd workspace cleanup --ssh user@host --delete-remote-dir
+  $ fnd workspace --ssh user@host --with-tool shopify-file-upload --site-id mystore --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.7.0/src/commands/workspace/index.ts)_
 <!-- commandsstop -->

package/bin/dev.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning
+#!/usr/bin/env -S node --loader ts-node/esm --conditions=development --disable-warning=ExperimentalWarning
 
 import {execute} from '@oclif/core'
 

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

@@ -0,0 +1,105 @@
+import { Command, Interfaces } from '@oclif/core';
+export default class AltText extends Command {
+    static aliases: string[];
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'api-key': Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
+        cms: Interfaces.BooleanFlag<boolean>;
+        dry: Interfaces.BooleanFlag<boolean>;
+        filter: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
+        limit: Interfaces.OptionFlag<number | undefined, Interfaces.CustomOptions>;
+        'ollama-host': Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
+        'ollama-model': Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
+        only: Interfaces.OptionFlag<string[] | undefined, Interfaces.CustomOptions>;
+        'output-stats': Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
+        platform: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
+        select: Interfaces.BooleanFlag<boolean>;
+        'site-id': Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
+        skip: 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.
+     *
+     * 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.
+     */
+    private describe;
+    /**
+     * 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.
+     */
+    private ensureShopifyScopes;
+    /** The `[n/limit] label — file` progress line, shared by real and dry counting. */
+    private logImageLine;
+    /** 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;
+    /**
+     * 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.
+     */
+    private processShopify;
+    /**
+     * 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.
+     */
+    private processWebflow;
+    /**
+     * 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.
+     */
+    private recordDry;
+    /** Totals and averages only — the per-image rows live in the --output-stats file. */
+    private report;
+    /**
+     * 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.
+     */
+    private reportDry;
+    /** The --platform value, or ask when it was omitted. */
+    private resolvePlatform;
+    /**
+     * 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.
+     */
+    private stopSpinner;
+    /**
+     * 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;
+}