@firenet-designs/fnd-cli 2.4.0 → 2.7.0

package/dist/commands/create-project.js

@@ -1,15 +1,15 @@
+import { findShopifyBin, generateClaudeMd, GITIGNORE_CONTENT, initPromptPath, run, SHOPIFYIGNORE_CONTENT, which, } from '#lib/scaffold.js';
 import { Args, Command } from '@oclif/core';
 import chalk from 'chalk';
 import { spawnSync } from 'node:child_process';
 import { existsSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { simpleGit } from 'simple-git';
-import { findShopifyBin, generateClaudeMd, GITIGNORE_CONTENT, initPromptPath, run, SHOPIFYIGNORE_CONTENT, which, } from '../lib/scaffold.js';
 export default class CreateProject extends Command {
     static args = {
         shop: Args.string({ description: 'Shopify store handle — pulls the live theme from <shop>.myshopify.com (omit to skip)', required: false }),
     };
-    static 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.\n\nRequires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.\n\nGitHub auth comes from YOUR environment — run `gh auth login` once, or export GH_TOKEN in your shell profile. This CLI never stores credentials. Override the org with FND_GH_ORG.';
+    static 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 with production and staging branches pushed.\n\nRequires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.\n\nGitHub auth comes from YOUR environment — run `gh auth login` once, or export GH_TOKEN in your shell profile. This CLI never stores credentials. Override the org with FND_GH_ORG.';
     static examples = [
         '<%= config.bin %> <%= command.id %>',
         '<%= config.bin %> <%= command.id %> my-store',
@@ -106,17 +106,60 @@ export default class CreateProject extends Command {
         if (createCode !== 0) {
             this.error('gh repo create failed — see output above', { code: '1' });
         }
+        // gh pointed 'origin' at the URL GitHub returned, which carries the name
+        // the repo was ACTUALLY created under — GitHub normalizes names
+        // server-side ('my client' → 'my-client'). Recover it before forcing SSH
+        // so the remote, the default-branch edit, and the printed link all track
+        // the real repo, not the raw directory name.
+        const originUrl = (await git.raw(['remote', 'get-url', 'origin']).catch(() => '')).trim();
+        const canonicalRepo = /github\.com[/:](.+?)(?:\.git)?$/.exec(originUrl)?.[1] ?? repo;
         // Force SSH so the push authenticates with the user's key, not the
         // create-only token.
-        await git.raw(['remote', 'set-url', 'origin', `git@github.com:${repo}.git`]);
+        await git.raw(['remote', 'set-url', 'origin', `git@github.com:${canonicalRepo}.git`]);
         this.log(chalk.blue("⬆️  Pushing 'production' to origin over SSH…"));
         const pushCode = await run('git', ['push', '-u', 'origin', 'production']);
         if (pushCode === 0) {
-            spawnSync('gh', ['repo', 'edit', repo, '--default-branch', 'production'], { stdio: 'ignore' });
-            this.log(chalk.green(`✅ Created + pushed. origin = git@github.com:${repo}.git`));
+            spawnSync('gh', ['repo', 'edit', canonicalRepo, '--default-branch', 'production'], { stdio: 'ignore' });
+            this.log(chalk.green(`✅ Created + pushed. origin = git@github.com:${canonicalRepo}.git`));
+            // 6. Staging branch cut explicitly from 'production' — HEAD isn't a safe
+            // start point because a pre-existing repo (init step skipped) may be
+            // checked out elsewhere. No checkout, so the working tree stays put.
+            // A pre-existing 'staging' is pushed as-is (force-resetting it could
+            // destroy work), with divergence from production called out instead of
+            // silently published. try/catch so a git failure here can't swallow the
+            // URL line below — the repo exists either way.
+            try {
+                const { all: localBranches } = await git.branchLocal();
+                const stagingExisted = localBranches.includes('staging');
+                if (!stagingExisted) {
+                    await git.raw(['branch', 'staging', 'production']);
+                }
+                this.log(chalk.blue("⬆️  Pushing 'staging' to origin over SSH…"));
+                const stagingPushCode = await run('git', ['push', '-u', 'origin', 'staging']);
+                if (stagingPushCode !== 0) {
+                    this.warn("push of 'staging' failed — create it manually: git push -u origin staging");
+                }
+                else if (stagingExisted) {
+                    this.log(chalk.green("✅ pre-existing 'staging' branch pushed"));
+                    const [stagingSha, productionSha] = (await git.raw(['rev-parse', 'staging', 'production'])).trim().split('\n');
+                    if (stagingSha !== productionSha) {
+                        this.warn("'staging' does not match 'production' — it was pushed at its current commit");
+                    }
+                }
+                else {
+                    this.log(chalk.green("✅ 'staging' branch created + pushed"));
+                }
+            }
+            catch {
+                this.warn("could not create 'staging' — create it manually: git branch staging production && git push -u origin staging");
+            }
         }
         else {
             this.warn(`push failed — check your SSH access to the ${org} org`);
         }
+        // https form, not the SSH remote, and printed even when a push failed (the
+        // repo itself exists by now) — this line is for copy-pasting into Jira
+        // tickets and browsers.
+        this.log(`🔗 GitHub: ${chalk.green(`https://github.com/${canonicalRepo}`)}`);
     }
 }

package/dist/commands/workspace/index.d.ts

@@ -3,18 +3,35 @@ export default class Workspace extends Command {
     static description: string;
     static examples: string[];
     static flags: {
+        cleanup: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'delete-remote-dir': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         devtools: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'ignore-vcs': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'remote-base': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
-        rpc: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'site-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         source: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         ssh: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'with-tool': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
-    /** Verify this machine can drive the sync before we connect. */
+    /** Verify this machine can drive the sync — and each tool's prerequisites — before we connect. */
     private preflight;
     private printPlan;
+    /**
+     * Tear down leftovers from a session that dropped before cleaning up (--cleanup).
+     * Terminates this directory's Mutagen sync sessions locally, then reaches the
+     * remote to strip the MCP entries the matching flags imply and, with
+     * --delete-remote-dir, remove the synced dir. devtools/rpc are read for
+     * presence only — their port values are irrelevant to removal.
+     */
+    private runCleanup;
     /** Run the interactive ssh session, inheriting the TTY so the remote shell is fully interactive. */
     private runSsh;
+    /**
+     * Best-effort: reach back to the remote after the session to strip any MCP
+     * config this run registered and, with --delete-remote-dir, remove the synced
+     * dir. No-op when the session left nothing behind to clean. A failure here is
+     * logged, not thrown — the local sync is already torn down by this point.
+     */
+    private teardownRemote;
 }

package/dist/commands/workspace/index.js

@@ -1,8 +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 { hasLocalShell, parseRpcFlag, RPC_FLAG_EXAMPLES, RPC_FLAG_USAGE, startRpcServer } from '../../lib/rpc.js';
-import { browserDebugInstructions, buildContext, buildMutagenCreateArgs, buildMutagenFlushArgs, buildMutagenTerminateArgs, buildRemoteScript, DEFAULT_MOUNT_BASE, hasMutagen, hasSshClient, isLocalDebugPortLive, mutagenInstallInstructions, parsePortPair, parseSshTarget, runMutagen, runRemoteCleanup, } from '../../lib/workspace.js';
+import { basename } from 'node:path';
 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 = [
@@ -12,11 +15,19 @@ 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 --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/--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,
             description: 'on exit, delete the remote workspace directory instead of leaving the synced copy in place',
@@ -32,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.',
@@ -43,25 +54,63 @@ 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);
         const target = parseSshTarget(flags.ssh);
         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/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…'));
@@ -70,56 +119,31 @@ 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);
             await runMutagen(buildMutagenTerminateArgs(ctx.syncName)).catch(() => 1);
             // Reach back to the remote if we left MCP config there to remove, or if we
             // were asked to delete the synced directory.
-            if (ctx.devtools || ctx.rpc || deleteRemoteDir) {
-                const actions = [
-                    ctx.devtools ? 'removing the remote chrome-devtools MCP config' : undefined,
-                    ctx.rpc ? 'removing the remote local-shell MCP config' : undefined,
-                    deleteRemoteDir ? 'deleting the remote dir' : undefined,
-                ].filter(Boolean);
-                this.log(chalk.dim(`${actions.join(' and ')}…`.replace(/^./, (c) => c.toUpperCase())));
-                try {
-                    await runRemoteCleanup(target2, ctx.remoteDir, {
-                        deleteRemoteDir,
-                        removeDevtoolsMcp: Boolean(ctx.devtools),
-                        removeRpcMcp: Boolean(ctx.rpc),
-                    });
-                }
-                catch (error) {
-                    this.log(chalk.yellow(`Could not reach the remote to clean up (${error.message}).`));
-                }
-            }
+            await this.teardownRemote(ctx, target2, deleteRemoteDir);
         }
         this.log('');
         this.log(code === 0
@@ -128,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' });
         }
@@ -152,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) {
@@ -175,17 +219,62 @@ 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('');
     }
+    /**
+     * Tear down leftovers from a session that dropped before cleaning up (--cleanup).
+     * Terminates this directory's Mutagen sync sessions locally, then reaches the
+     * remote to strip the MCP entries the matching flags imply and, with
+     * --delete-remote-dir, remove the synced dir. devtools/rpc are read for
+     * presence only — their port values are irrelevant to removal.
+     */
+    async runCleanup(target, flags) {
+        if (!hasSshClient()) {
+            this.error('No `ssh` client found on PATH. Install OpenSSH client and try again.', { code: '1' });
+        }
+        const removeDevtoolsMcp = flags.devtools !== 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));
+        this.log(chalk.bold('Cleaning up workspace'));
+        this.log(`  ${chalk.dim('remote:')}     ${target}`);
+        this.log(`  ${chalk.dim('remote dir:')} ${remoteDir}`);
+        this.log('');
+        // Terminate any lingering sync sessions for this directory (a local Mutagen op).
+        if (hasMutagen()) {
+            this.log(chalk.dim('Terminating any leftover Mutagen sync sessions…'));
+            await runMutagen(buildMutagenTerminateSelectorArgs(slug)).catch(() => 1);
+        }
+        else {
+            this.log(chalk.yellow('Mutagen CLI not found on PATH — skipping sync termination.'));
+        }
+        if (removeDevtoolsMcp) {
+            this.log(chalk.dim('Removing any leftover chrome-devtools 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, removeToolsMcp });
+        if (code === 0) {
+            this.log(chalk.green('✓ Done.'));
+        }
+        else {
+            this.error(`Remote cleanup ssh session exited with code ${code}.`, { code: '1' });
+        }
+    }
     /** 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'] : []),
@@ -199,4 +288,30 @@ export default class Workspace extends Command {
             child.once('close', (code) => resolve(code ?? 0));
         });
     }
+    /**
+     * Best-effort: reach back to the remote after the session to strip any MCP
+     * config this run registered and, with --delete-remote-dir, remove the synced
+     * dir. No-op when the session left nothing behind to clean. A failure here is
+     * logged, not thrown — the local sync is already torn down by this point.
+     */
+    async teardownRemote(ctx, target, deleteRemoteDir) {
+        if (!ctx.devtools && !ctx.tools && !deleteRemoteDir)
+            return;
+        const actions = [
+            ctx.devtools ? 'removing the remote chrome-devtools 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())));
+        try {
+            await runRemoteCleanup(target, ctx.remoteDir, {
+                deleteRemoteDir,
+                removeDevtoolsMcp: Boolean(ctx.devtools),
+                removeToolsMcp: Boolean(ctx.tools),
+            });
+        }
+        catch (error) {
+            this.log(chalk.yellow(`Could not reach the remote to clean up (${error.message}).`));
+        }
+    }
 }

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

@@ -0,0 +1,87 @@
+/**
+ * Alt-text generation: fetch an image, make it something a vision model can
+ * read, and ask a locally-hosted Ollama model to describe it.
+ *
+ * Everything runs against the user's own Ollama host, so no image ever leaves
+ * their network and there is no per-image API cost — which is also why the
+ * caller drives this strictly sequentially: a single local model gains nothing
+ * from concurrent requests.
+ */
+import type { ImageFilter, ImageMeta } from './image-filter.js';
+export declare const DEFAULT_OLLAMA_HOST = "http://localhost:11434";
+/**
+ * One image's worth of result. The caller already knows the URL, so this is
+ * everything else worth recording about the round trip.
+ *
+ * `bytes` is the size of what was actually sent to the model, i.e. after the
+ * PNG conversion below — not `meta.fileSize`, which is the (usually much
+ * smaller) WebP the site serves. `ms` is wall clock for the whole thing
+ * (download, convert, inference), because that is what a run's duration is
+ * actually made of.
+ */
+export interface Description {
+    alt: string;
+    bytes: number;
+    meta: ImageMeta;
+    ms: number;
+    skipped: false;
+    tokens: number;
+}
+/** An image the filter rejected. It was downloaded, but never sent to the model. */
+export interface Skipped {
+    meta: ImageMeta;
+    skipped: true;
+}
+/**
+ * `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.
+ *
+ * /api/tags (`list`) is the only endpoint that enumerates models, but it says
+ * nothing about what a model can do — the capability list lives on /api/show
+ * (`show`), so each tag is asked individually. The calls are local and run
+ * concurrently; a model whose show() fails (pulled but broken, or removed
+ * between the two calls) is simply left out rather than failing the run.
+ */
+export declare const listVisionModels: (host: string) => Promise<string[]>;
+/**
+ * Bind a describer to one Ollama host and model. The client is created once and
+ * reused so the connection (and the loaded model, via keep_alive) survives
+ * across images.
+ *
+ * `filter`, when given, decides whether an image is worth describing — it runs
+ * 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, dry?: boolean) => Describe;