@firenet-designs/fnd-cli 2.6.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.6.0 linux-x64 node-v24.18.0
+@firenet-designs/fnd-cli/2.7.0 node-v24.18.0
 $ fnd --help [COMMAND]
 USAGE
   $ fnd COMMAND
@@ -44,14 +44,20 @@ Generate alt text for a site's images with a local Ollama vision model and write
 
 ```
 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]
+  $ 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). 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.
+  --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.
@@ -65,43 +71,48 @@ FLAGS
                           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
-  --shopify               run against a Shopify store (not implemented yet)
-  --site-id=<value>       Webflow site ID. Prompted for if omitted.
+  --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
-  --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.
+  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.
 
-  CMS writes go to STAGING, so publish the site in Webflow to make them live. Any required flag you omit is prompted
-  for.
+  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 --webflow --api-key <key> --site-id <id> --ollama-host http://localhost:11434 --ollama-model qwen3-vl:8b
+  $ fnd alt-text --platform 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 --platform shopify --site-id mystore
 
-  $ fnd alt-text --webflow --cms --select
+  $ fnd alt-text --platform shopify --site-id mystore --dry
 
-  $ fnd alt-text --webflow --cms --only products --only sku
+  $ fnd alt-text --platform webflow --skip --limit 20
 
-  $ fnd alt-text --webflow --output-stats ./alt-text-run.md
+  $ fnd alt-text --platform webflow --cms --select
 
-  $ fnd alt-text --webflow --filter "fileSize>=sizes.KB(100) && width>=100 && height>=100"
+  $ fnd alt-text --platform webflow --cms --only products --only sku
 
-  $ fnd alt-text --webflow --filter "type !== 'svg' && !url.includes('/icons/')"
+  $ 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.6.0/src/commands/alt-text.ts)_
+_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]`
 
@@ -128,7 +139,7 @@ EXAMPLES
   $ fnd backfill-project my-store "extra hints"
 ```
 
-_See code: [src/commands/backfill-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.6.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`
 
@@ -136,14 +147,20 @@ Generate alt text for a site's images with a local Ollama vision model and write
 
 ```
 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]
+  $ 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). 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.
+  --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.
@@ -157,40 +174,45 @@ FLAGS
                           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
-  --shopify               run against a Shopify store (not implemented yet)
-  --site-id=<value>       Webflow site ID. Prompted for if omitted.
+  --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
-  --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.
+  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.
 
-  CMS writes go to STAGING, so publish the site in Webflow to make them live. Any required flag you omit is prompted
-  for.
+  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 --webflow --api-key <key> --site-id <id> --ollama-host http://localhost:11434 --ollama-model qwen3-vl:8b
+  $ 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 --webflow --skip --limit 20
+  $ fnd caption --platform webflow --skip --limit 20
 
-  $ fnd caption --webflow --cms --select
+  $ fnd caption --platform webflow --cms --select
 
-  $ fnd caption --webflow --cms --only products --only sku
+  $ fnd caption --platform webflow --cms --only products --only sku
 
-  $ fnd caption --webflow --output-stats ./alt-text-run.md
+  $ fnd caption --platform webflow --output-stats ./alt-text-run.md
 
-  $ fnd caption --webflow --filter "fileSize>=sizes.KB(100) && width>=100 && height>=100"
+  $ fnd caption --platform webflow --filter "fileSize>=sizes.KB(100) && width>=100 && height>=100"
 
-  $ fnd caption --webflow --filter "type !== 'svg' && !url.includes('/icons/')"
+  $ fnd caption --platform webflow --filter "type !== 'svg' && !url.includes('/icons/')"
 ```
 
 ## `fnd create-app`
@@ -212,7 +234,7 @@ EXAMPLES
   $ fnd create-app
 ```
 
-_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.6.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]`
 
@@ -242,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.6.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]`
 
@@ -294,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.6.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`
 
@@ -303,12 +325,12 @@ Open a remote workspace: two-way sync the current directory to a remote Linux bo
 ```
 USAGE
   $ fnd workspace --ssh <value> [--cleanup] [--delete-remote-dir] [--devtools <value>] [--ignore-vcs]
-    [--remote-base <value>] [--rpc <value>] [--source remote|local]
+    [--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/--rpc MCP entries and, with
+      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.
 
@@ -328,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
@@ -344,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.
@@ -367,14 +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 --with-tool shopify-file-upload --with-tool shopify-file-search --with-tool "shopify-file-delete[ask]" --site-id mystore
+
+  $ 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
+
+  $ fnd workspace --ssh user@host --with-tool "shopify-execute[scopes=read_products+read_orders]" --site-id mystore
 
-  $ fnd workspace --ssh user@host --rpc port=7777:7700,profile=false,shell=zsh
+  $ fnd workspace --ssh user@host --with-tool "shopify-execute[ask,scopes=all]" --site-id mystore
 
   $ fnd workspace --ssh user@host --delete-remote-dir
 
-  $ fnd workspace --ssh user@host --rpc 7700 --cleanup
+  $ fnd workspace --ssh user@host --with-tool shopify-file-upload --site-id mystore --cleanup
 ```
 
-_See code: [src/commands/workspace/index.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.6.0/src/commands/workspace/index.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

@@ -1,30 +1,47 @@
-import { Command } from '@oclif/core';
+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': 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>;
+        '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;
     /**
@@ -43,10 +60,42 @@ export default class AltText extends Command {
      * 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;
-    /** --webflow / --shopify, or ask when neither was given. */
+    /**
+     * 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