@firenet-designs/fnd-cli 2.6.0 → 2.7.0

package/dist/commands/workspace/index.js

@@ -1,9 +1,11 @@
+import { collectToolSpecs, resolveWorkspaceTools, withToolUsage } from '#lib/mcp/registry.js';
+import { startMcpServer } from '#lib/mcp/server.js';
+import { reconcileShopifyScopes } from '#lib/mcp/tools/shopify-common.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';
 import { Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
 import { spawn } from 'node:child_process';
 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 = [
@@ -13,15 +15,18 @@ export default class Workspace extends Command {
         '<%= 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 --with-tool shopify-file-upload --site-id mystore',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --with-tool shopify-file-upload --with-tool shopify-file-search --with-tool "shopify-file-delete[ask]" --site-id mystore',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --with-tool shopify-file-upload --with-tool shopify-file-replace --with-tool shopify-file-delete --site-id mystore.myshopify.com',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --with-tool "shopify-execute[scopes=read_products+read_orders]" --site-id mystore',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --with-tool "shopify-execute[ask,scopes=all]" --site-id mystore',
         '<%= config.bin %> <%= command.id %> --ssh user@host --delete-remote-dir',
-        '<%= config.bin %> <%= command.id %> --ssh user@host --rpc 7700 --cleanup',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --with-tool shopify-file-upload --site-id mystore --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.",
+            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/--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': Flags.boolean({
             default: false,
@@ -38,8 +43,8 @@ export default class Workspace extends Command {
             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.`,
+        'site-id': Flags.string({
+            description: '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: 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.',
@@ -49,6 +54,10 @@ export default class Workspace extends Command {
             description: 'remote to connect to, as user@host',
             required: true,
         }),
+        'with-tool': Flags.string({
+            description: `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: ${withToolUsage()}. 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.`,
+            multiple: true,
+        }),
     };
     async run() {
         const { flags } = await this.parse(Workspace);
@@ -56,26 +65,52 @@ export default class Workspace extends Command {
         const target2 = `${target.user}@${target.host}`;
         // --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.
+        // flags are reused for *what* to clean up (devtools/with-tool 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' });
+        // Resolve --with-tool selections up front so an unknown tool or a bad argument
+        // fails before we touch the network.
+        let selections = [];
+        try {
+            selections = resolveWorkspaceTools(flags['with-tool'] ?? [], { siteId: flags['site-id'] });
+        }
+        catch (error) {
+            this.error(error.message, { code: '1' });
+        }
+        // Run every prerequisite check (ssh/mutagen, the browser debug port, and each
+        // tool's own setup — auth, scopes) BEFORE connecting, so nothing that needs
+        // interactive setup surprises the user mid-session.
+        await this.preflight(devtools, selections);
+        // With tools selected, start the loopback MCP server now so we know the port
+        // to tunnel and register on the remote. It's closed in the finally below.
+        let mcpServer;
+        let tools;
+        if (selections.length > 0) {
+            const specs = collectToolSpecs(selections, { localCwd: process.cwd() });
+            try {
+                mcpServer = await startMcpServer(specs);
+            }
+            catch (error) {
+                this.error(`Could not start the local tools MCP server (${error.message}).`, { code: '1' });
+            }
+            if (devtools && devtools.remote === mcpServer.port) {
+                await mcpServer.close().catch(() => { });
+                this.error(`--devtools remote port ${devtools.remote} collides with the tools MCP server; use a different --devtools port.`, { code: '1' });
+            }
+            tools = { names: selections.map((s) => s.raw), port: { local: mcpServer.port, remote: mcpServer.port } };
         }
         const ctx = buildContext({
             cwd: process.cwd(),
             devtools,
             ignoreVcs: flags['ignore-vcs'],
             remoteBase: flags['remote-base'],
-            rpc,
             source: flags.source,
+            tools,
         });
-        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…'));
@@ -84,32 +119,24 @@ 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 {
+            if (ctx.tools) {
+                this.log(chalk.dim(`Local tools MCP server listening on 127.0.0.1:${ctx.tools.port.local} (${ctx.tools.names.join(', ')}).`));
+            }
             // Block until the first full sync lands so the files exist before the shell opens.
             this.log(chalk.dim('Performing the initial sync…'));
             const flushCode = await runMutagen(buildMutagenFlushArgs(ctx.syncName));
             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);
         }
         finally {
-            // Best-effort: stop serving local commands, flush the last edits back, then
-            // tear the session down.
-            await rpcServer?.close().catch(() => { });
+            // Best-effort: stop serving tools, flush the last edits back, then tear the
+            // session down.
+            await mcpServer?.close().catch(() => { });
             this.log('');
             this.log(chalk.dim('Flushing final changes and stopping the sync…'));
             await runMutagen(buildMutagenFlushArgs(ctx.syncName)).catch(() => 1);
@@ -125,8 +152,8 @@ export default class Workspace extends Command {
                 : '✓ Workspace closed. Sync stopped; the remote copy is left in place.')
             : chalk.yellow(`Session ended with exit code ${code}. Cleanup attempted above.`));
     }
-    /** Verify this machine can drive the sync before we connect. */
-    async preflight(devtools, rpc) {
+    /** Verify this machine can drive the sync — and each tool's prerequisites — before we connect. */
+    async preflight(devtools, selections) {
         if (!hasSshClient()) {
             this.error('No `ssh` client found on PATH. Install OpenSSH client and try again.', { code: '1' });
         }
@@ -149,12 +176,32 @@ 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',
-            });
+        // Each --with-tool tool checks its own prerequisites here — the same "verify
+        // before we connect" contract as the devtools port above. A tool may do
+        // interactive setup (e.g. opening the browser for `shopify store auth`), so
+        // this runs while the user is still watching, not mid-session. A thrown check
+        // aborts before anything connects.
+        for (const { config, tool } of selections) {
+            try {
+                // eslint-disable-next-line no-await-in-loop -- tools set up sequentially; each may prompt interactively
+                await tool.preflight(config, (message) => this.log(chalk.dim(message)));
+            }
+            catch (error) {
+                this.error(`--with-tool ${tool.name}: ${error.message}`, { code: '1' });
+            }
+        }
+        // Reconcile the Shopify store's scopes ONCE across all the selected tools:
+        // grant the union they need, and — only when shopify-execute is in the run —
+        // revoke anything extra so the arbitrary-GraphQL tool is held to least
+        // privilege. Runs after the per-tool checks (so a missing CLI has already
+        // aborted with a friendly message) and before we connect, so the browser
+        // `shopify store auth` happens while the user is watching. A no-op when no
+        // Shopify tool is selected.
+        try {
+            reconcileShopifyScopes(selections, (message) => this.log(chalk.dim(message)));
+        }
+        catch (error) {
+            this.error(error.message, { code: '1' });
         }
     }
     printPlan(ctx, target) {
@@ -172,8 +219,8 @@ export default class Workspace extends Command {
         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}`);
+        if (ctx.tools) {
+            this.log(`  ${chalk.dim('tools:')}        remote 127.0.0.1:${ctx.tools.port.remote} → local MCP server 127.0.0.1:${ctx.tools.port.local} (${ctx.tools.names.join(', ')})`);
         }
         this.log('');
     }
@@ -189,7 +236,7 @@ export default class Workspace extends Command {
             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 removeToolsMcp = (flags['with-tool']?.length ?? 0) > 0;
         const deleteRemoteDir = flags['delete-remote-dir'];
         const { remoteDir } = buildContext({ cwd: process.cwd(), remoteBase: flags['remote-base'] });
         const slug = slugify(basename(remoteDir));
@@ -208,13 +255,13 @@ export default class Workspace extends Command {
         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 (removeToolsMcp) {
+            this.log(chalk.dim('Removing any leftover fnd-tools 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 });
+        const code = await runRemoteCleanup(target, remoteDir, { deleteRemoteDir, removeDevtoolsMcp, removeToolsMcp });
         if (code === 0) {
             this.log(chalk.green('✓ Done.'));
         }
@@ -225,9 +272,9 @@ export default class Workspace extends Command {
     /** Run the interactive ssh session, inheriting the TTY so the remote shell is fully interactive. */
     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);
+        // --devtools points one at the local browser's debug port; --with-tool points
+        // one at the local tools MCP server, so the remote's MCPs can reach them.
+        const forwards = [ctx.devtools, ctx.tools?.port].filter((f) => f !== undefined);
         const args = [
             '-t', // allocate a remote PTY for the interactive shell session
             ...(forwards.length > 0 ? ['-o', 'ExitOnForwardFailure=yes'] : []),
@@ -248,11 +295,11 @@ export default class Workspace extends Command {
      * logged, not thrown — the local sync is already torn down by this point.
      */
     async teardownRemote(ctx, target, deleteRemoteDir) {
-        if (!ctx.devtools && !ctx.rpc && !deleteRemoteDir)
+        if (!ctx.devtools && !ctx.tools && !deleteRemoteDir)
             return;
         const actions = [
             ctx.devtools ? 'removing the remote chrome-devtools MCP config' : undefined,
-            ctx.rpc ? 'removing the remote local-shell MCP config' : undefined,
+            ctx.tools ? 'removing the remote fnd-tools MCP config' : undefined,
             deleteRemoteDir ? 'deleting the remote dir' : undefined,
         ].filter(Boolean);
         this.log(chalk.dim(`${actions.join(' and ')}…`.replace(/^./, (c) => c.toUpperCase())));
@@ -260,7 +307,7 @@ export default class Workspace extends Command {
             await runRemoteCleanup(target, ctx.remoteDir, {
                 deleteRemoteDir,
                 removeDevtoolsMcp: Boolean(ctx.devtools),
-                removeRpcMcp: Boolean(ctx.rpc),
+                removeToolsMcp: Boolean(ctx.tools),
             });
         }
         catch (error) {

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

@@ -32,7 +32,30 @@ export interface Skipped {
     meta: ImageMeta;
     skipped: true;
 }
-export type Describe = (url: string) => Promise<Description | Skipped>;
+/**
+ * `context`, when given, is free-form usage context for this specific image
+ * (e.g. the Shopify product it's attached to) that the caller has dug up from
+ * somewhere the pixels can't show. It's folded into the prompt as a hint.
+ *
+ * `onDownloaded` fires once the image is fetched and about to go to the model —
+ * the boundary between the two slow phases (download, then inference) — so a
+ * caller can update a spinner from "downloading" to "describing". It does NOT
+ * fire when the image is filtered out or on a dry run, since neither reaches the
+ * model.
+ */
+export type Describe = (url: string, context?: string, onDownloaded?: () => void) => Promise<Description | Skipped>;
+/**
+ * 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.
+ *
+ * Exported so a caller that already knows an image's MIME type (e.g. Shopify's
+ * GraphQL `mimeType`) can produce the same `type` token a downloaded image would
+ * get, without re-fetching the bytes.
+ */
+export declare const detectType: (contentType: string, path: string) => string;
 /**
  * Every model pulled on the host that can actually read an image.
  *
@@ -52,5 +75,13 @@ export declare const listVisionModels: (host: string) => Promise<string[]>;
  * 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.
+ *
+ * `dry` short-circuits right after the download: the image is fetched and
+ * measured (so the caller can filter on real metadata for images whose size or
+ * dimensions weren't known up front) but nothing is sent to the model, and the
+ * filter is NOT applied here — a dry run's filtering is the command's job, so it
+ * can decide uniformly whether the meta came from this download or from an API
+ * that already knew it. The returned Description carries real `meta`/`bytes` and
+ * an empty `alt` the caller never reads.
  */
-export declare const createDescriber: (host: string, model: string, filter?: ImageFilter) => Describe;
+export declare const createDescriber: (host: string, model: string, filter?: ImageFilter, dry?: boolean) => Describe;

package/dist/lib/alt-text.js

@@ -12,6 +12,41 @@ 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.";
+/**
+ * The part of an image URL worth showing the model: the file name, without the
+ * directory, query string, or extension. A name like `sample-normal-wax` says
+ * what the pixels can't — that yellow cube is a wax melt — while the rest of a
+ * CDN URL (shard digits, `?v=…`) is noise the model shouldn't have to wade
+ * through. Returns '' when there's nothing usable to pass along.
+ */
+const urlHint = (url) => {
+    try {
+        const last = new URL(url).pathname.split('/').pop() ?? '';
+        return decodeURIComponent(last).replace(/\.[a-z0-9]+$/i, '').trim();
+    }
+    catch {
+        return '';
+    }
+};
+/**
+ * The prompt for one image: the base instructions, the file name, and whatever
+ * usage context the caller passed. All of it is framed as a hint on purpose —
+ * file names are often stale, generic (`IMG_1234`), or plain wrong, and a
+ * product an image is filed under isn't guaranteed to be what the image shows —
+ * so the model is told to lean on the hints only where they agree with the
+ * pixels, and never to copy them into the alt text verbatim.
+ */
+const buildPrompt = (url, context) => {
+    const hints = [];
+    const hint = urlHint(url);
+    if (hint)
+        hints.push(`Its file name is "${hint}".`);
+    if (context)
+        hints.push(`${context}.`);
+    if (hints.length === 0)
+        return PROMPT;
+    return `${PROMPT} Extra context about this image: ${hints.join(' ')} Use this context only where it agrees with what you see, and never copy the file name, URL, or these details verbatim into the alt text.`;
+};
 /**
  * Everything the model sees is PNG.
  *
@@ -49,8 +84,12 @@ const rasterToPng = async (bytes) => {
  * 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.
+ *
+ * Exported so a caller that already knows an image's MIME type (e.g. Shopify's
+ * GraphQL `mimeType`) can produce the same `type` token a downloaded image would
+ * get, without re-fetching the bytes.
  */
-const detectType = (contentType, path) => {
+export 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() : '');
@@ -110,19 +149,32 @@ export const listVisionModels = async (host) => {
  * 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.
+ *
+ * `dry` short-circuits right after the download: the image is fetched and
+ * measured (so the caller can filter on real metadata for images whose size or
+ * dimensions weren't known up front) but nothing is sent to the model, and the
+ * filter is NOT applied here — a dry run's filtering is the command's job, so it
+ * can decide uniformly whether the meta came from this download or from an API
+ * that already knew it. The returned Description carries real `meta`/`bytes` and
+ * an empty `alt` the caller never reads.
  */
-export const createDescriber = (host, model, filter) => {
+export const createDescriber = (host, model, filter, dry = false) => {
     const ollama = new Ollama({ host });
-    return async (url) => {
+    return async (url, context, onDownloaded) => {
         const started = performance.now();
         const { meta, png } = await fetchImage(url);
+        if (dry) {
+            return { alt: '', bytes: png.byteLength, meta, ms: performance.now() - started, skipped: false, tokens: 0 };
+        }
         if (filter && !filter(meta))
             return { meta, skipped: true };
+        // Downloaded and kept: from here the model runs, which is the slow part.
+        onDownloaded?.();
         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' }],
+            messages: [{ content: buildPrompt(url, context), images, role: 'user' }],
             model,
             stream: false,
             // think: true,

package/dist/lib/mcp/bracket-args.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A small, reusable parser for a `--with-tool` selection's bracketed argument.
+ *
+ * The registry already splits `name[...]` into the tool name and the raw text
+ * between the brackets (see registry.ts `parseSpec`); this turns that raw text
+ * into named options. The grammar is a comma-separated list where each item is
+ * either a bare **flag** (`ask`) or a **key=value** option (`scopes=all`):
+ *
+ *   shopify-file-delete[ask]
+ *   shopify-execute[ask,scopes=read_products+write_orders]
+ *
+ * A tool declares which flags and value-keys it accepts, so a typo (`aks`, or a
+ * value option a tool doesn't understand) fails up front with a clear message
+ * rather than being silently ignored. Multi-valued options (e.g. a scope list)
+ * keep their value as one opaque string here — the tool splits it however it
+ * likes — because comma is already the option separator (so a list uses `+` or
+ * spaces internally, not commas).
+ */
+/** What a tool allows inside its brackets: bare flags and/or key=value options. */
+export interface BracketSpec {
+    /** Allowed bare flags, lower-cased. Present in the parse result => set to true. */
+    flags?: readonly string[];
+    /** Allowed key=value option keys, lower-cased. */
+    values?: readonly string[];
+}
+/** The parsed brackets: which flags were present, and each key=value pair. */
+export interface BracketArgs {
+    flags: Set<string>;
+    values: Map<string, string>;
+}
+/**
+ * Parse a selection's bracket text against `spec`. An undefined/empty arg yields
+ * an empty result (no flags, no values). Throws — with a message the registry
+ * prefixes with the tool name — on an unknown flag/key, a duplicate, or an empty
+ * value (`scopes=`), so the user learns exactly what they mistyped.
+ */
+export declare const parseBracketArgs: (arg: string | undefined, spec?: BracketSpec) => BracketArgs;

package/dist/lib/mcp/bracket-args.js

@@ -0,0 +1,65 @@
+/**
+ * A small, reusable parser for a `--with-tool` selection's bracketed argument.
+ *
+ * The registry already splits `name[...]` into the tool name and the raw text
+ * between the brackets (see registry.ts `parseSpec`); this turns that raw text
+ * into named options. The grammar is a comma-separated list where each item is
+ * either a bare **flag** (`ask`) or a **key=value** option (`scopes=all`):
+ *
+ *   shopify-file-delete[ask]
+ *   shopify-execute[ask,scopes=read_products+write_orders]
+ *
+ * A tool declares which flags and value-keys it accepts, so a typo (`aks`, or a
+ * value option a tool doesn't understand) fails up front with a clear message
+ * rather than being silently ignored. Multi-valued options (e.g. a scope list)
+ * keep their value as one opaque string here — the tool splits it however it
+ * likes — because comma is already the option separator (so a list uses `+` or
+ * spaces internally, not commas).
+ */
+/**
+ * Parse a selection's bracket text against `spec`. An undefined/empty arg yields
+ * an empty result (no flags, no values). Throws — with a message the registry
+ * prefixes with the tool name — on an unknown flag/key, a duplicate, or an empty
+ * value (`scopes=`), so the user learns exactly what they mistyped.
+ */
+export const parseBracketArgs = (arg, spec = {}) => {
+    const flags = new Set();
+    const values = new Map();
+    const allowedFlags = new Set(spec.flags ?? []);
+    const allowedValues = new Set(spec.values ?? []);
+    const raw = arg?.trim();
+    if (!raw)
+        return { flags, values };
+    for (const part of raw.split(',')) {
+        const token = part.trim();
+        if (!token)
+            continue; // tolerate a stray/trailing comma
+        const eq = token.indexOf('=');
+        if (eq === -1) {
+            // A bare flag, e.g. `ask`.
+            const name = token.toLowerCase();
+            if (!allowedFlags.has(name)) {
+                const hint = allowedFlags.size > 0 ? ` supported flags: ${[...allowedFlags].join(', ')}.` : '';
+                throw new Error(`does not support the "${token}" option.${hint}`);
+            }
+            if (flags.has(name))
+                throw new Error(`option "${name}" was given more than once.`);
+            flags.add(name);
+        }
+        else {
+            // A key=value option, e.g. `scopes=all`.
+            const key = token.slice(0, eq).trim().toLowerCase();
+            const value = token.slice(eq + 1).trim();
+            if (!allowedValues.has(key)) {
+                const hint = allowedValues.size > 0 ? ` supported: ${[...allowedValues].map((v) => `${v}=…`).join(', ')}.` : '';
+                throw new Error(`does not support the "${key}=" option.${hint}`);
+            }
+            if (values.has(key))
+                throw new Error(`option "${key}=" was given more than once.`);
+            if (!value)
+                throw new Error(`option "${key}=" needs a value.`);
+            values.set(key, value);
+        }
+    }
+    return { flags, values };
+};

package/dist/lib/mcp/define-tool.d.ts

@@ -0,0 +1,52 @@
+import type { McpToolSpec } from './server.js';
+/**
+ * The defineTool framework for `--with-tool`.
+ *
+ * A tool module builds itself with defineTool() and imports nothing from the
+ * registry — the registry imports the tools, never the other way round. Keeping
+ * the framework here (not in registry.ts) is what breaks that cycle: a tool can
+ * `import { defineTool }` without pulling the registry, and its own tool, back
+ * into its initialization.
+ */
+/** Runtime facts a tool's handler may need — resolved once the workspace is known. */
+export interface ToolRuntime {
+    /** Absolute path of the synced directory on THIS machine (the tool handler's cwd). */
+    localCwd: string;
+}
+/**
+ * Command-level context a tool's `parse` may need, beyond its own bracketed
+ * [arg]. Some tools take a shared flag rather than a per-tool argument — the
+ * Shopify tools read the store from `--site-id`, so they all target one store —
+ * and this is how that flag reaches them.
+ */
+export interface ParseContext {
+    /** The `--site-id` flag value, if given (the Shopify store for the Shopify tools). */
+    siteId?: string;
+}
+/**
+ * A tool selectable via `--with-tool`. `C` is the parsed config a selection
+ * produces (e.g. a normalized store domain). The lifecycle is:
+ *   parse(arg, context)        — validate the [arg] and any command-level flags
+ *                                it depends on, up front, before anything else
+ *   preflight(config, log)     — verify prerequisites & do interactive setup
+ *                                (auth, scope grants) BEFORE the remote connects;
+ *                                throw with a friendly message to abort
+ *   build(config, runtime)     — the MCP tool spec(s) the server serves
+ *
+ * `argHint` is undefined for a tool that takes no bracketed [arg] (the Shopify
+ * tools — their store comes from `--site-id`), which the registry uses both to
+ * reject a stray `[arg]` and to print bare-name usage.
+ */
+export interface WorkspaceTool<C = unknown> {
+    /** What the bracketed argument means, for usage text; undefined if the tool takes no [arg]. */
+    argHint?: string;
+    /** Whether `[arg]` is required. Only meaningful when `argHint` is set. */
+    argRequired?: boolean;
+    build: (config: C, runtime: ToolRuntime) => McpToolSpec[];
+    /** Registry key and the name used in `--with-tool <name>`. */
+    name: string;
+    parse: (arg: string | undefined, context: ParseContext) => C;
+    preflight: (config: C, log: (message: string) => void) => Promise<void> | void;
+}
+/** Identity helper that pins a tool's config type — the defineTool framework. */
+export declare const defineTool: <C>(tool: WorkspaceTool<C>) => WorkspaceTool<C>;

package/dist/lib/mcp/define-tool.js

@@ -0,0 +1,2 @@
+/** Identity helper that pins a tool's config type — the defineTool framework. */
+export const defineTool = (tool) => tool;

package/dist/lib/mcp/registry.d.ts

@@ -0,0 +1,38 @@
+import type { ParseContext, ToolRuntime, WorkspaceTool } from './define-tool.js';
+import type { McpToolSpec } from './server.js';
+/**
+ * The `--with-tool` registry.
+ *
+ * `fnd workspace --with-tool <name>[<arg>]` exposes tools to Claude on the remote
+ * through the loopback MCP server (see server.ts). Each entry here is a
+ * WorkspaceTool built with defineTool (see define-tool.ts): it knows how to parse
+ * its bracketed argument, check its prerequisites BEFORE we connect (the same
+ * shape as the --devtools browser-port check), and build the MCP tool spec(s) the
+ * server actually serves. Adding a tool to the AI is: write one defineTool module
+ * and register it in TOOL_REGISTRY. Nothing else changes.
+ */
+/** Every tool `--with-tool` can name, keyed by tool name. */
+export declare const TOOL_REGISTRY: Record<string, WorkspaceTool>;
+/** A resolved `--with-tool` selection: the tool, its parsed config, and the raw spec. */
+export interface ToolSelection {
+    config: unknown;
+    raw: string;
+    tool: WorkspaceTool;
+}
+/** One-line usage listing the registered tools and their argument shape. */
+export declare const withToolUsage: () => string;
+/**
+ * Resolve each `--with-tool` value into a {tool, config} selection, validating
+ * the tool name and its argument up front. `context` carries command-level flags
+ * a tool's parse may depend on (e.g. `--site-id` for the Shopify tools). Throws
+ * on an unknown tool, a stray/missing argument, a parse failure (a required flag
+ * absent), or the same tool selected twice (its MCP tool names would collide on
+ * the server).
+ */
+export declare const resolveWorkspaceTools: (specs: string[], context: ParseContext) => ToolSelection[];
+/**
+ * The MCP tool specs for a set of selections. Rejects two tools that would
+ * advertise the same MCP tool name — the server dispatches by name, so a
+ * collision would make one unreachable.
+ */
+export declare const collectToolSpecs: (selections: ToolSelection[], runtime: ToolRuntime) => McpToolSpec[];