@firenet-designs/fnd-cli 2.3.3 → 2.4.0

package/README.md

@@ -20,7 +20,7 @@ $ npm install -g @firenet-designs/fnd-cli
 $ fnd COMMAND
 running command...
 $ fnd (--version)
-@firenet-designs/fnd-cli/2.3.3 linux-x64 node-v24.18.0
+@firenet-designs/fnd-cli/2.4.0 linux-x64 node-v24.18.0
 $ fnd --help [COMMAND]
 USAGE
   $ fnd COMMAND
@@ -62,7 +62,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.3.3/src/commands/backfill-project.ts)_
+_See code: [src/commands/backfill-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.4.0/src/commands/backfill-project.ts)_
 
 ## `fnd create-app`
 
@@ -83,7 +83,7 @@ EXAMPLES
   $ fnd create-app
 ```
 
-_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.3/src/commands/create-app.ts)_
+_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.4.0/src/commands/create-app.ts)_
 
 ## `fnd create-project [SHOP]`
 
@@ -113,7 +113,7 @@ EXAMPLES
   $ fnd create-project my-store "Acme storefront, Klaviyo"
 ```
 
-_See code: [src/commands/create-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.3/src/commands/create-project.ts)_
+_See code: [src/commands/create-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.4.0/src/commands/create-project.ts)_
 
 ## `fnd help [COMMAND]`
 
@@ -165,7 +165,7 @@ EXAMPLES
   $ fnd token -s mystore -i <id> -c <secret> --write ./.mcp.json
 ```
 
-_See code: [src/commands/token.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.3/src/commands/token.ts)_
+_See code: [src/commands/token.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.4.0/src/commands/token.ts)_
 
 ## `fnd workspace`
 
@@ -173,20 +173,41 @@ Open a remote workspace: two-way sync the current directory to a remote Linux bo
 
 ```
 USAGE
-  $ fnd workspace --ssh <value> [--delete-remote-dir] [--devtools <value>] [--remote-base <value>] [--source
-    remote|local]
+  $ fnd workspace --ssh <value> [--delete-remote-dir] [--devtools <value>] [--ignore-vcs] [--remote-base
+    <value>] [--rpc <value>] [--source remote|local]
 
 FLAGS
-  --delete-remote-dir    on exit, delete the remote workspace directory instead of leaving the synced copy in place
-  --devtools=<value>     expose your LOCAL browser to Claude on the remote via the chrome-devtools MCP. Value is "port"
-                         (same port both ends) or "remote:local" (local = this machine, where the browser runs). Your
-                         browser must already be listening with --remote-debugging-port=<local>.
-  --remote-base=<value>  [default: /home/fnd] base dir on the remote; the workspace lands at
-                         <base>/<local-user>/<dir-name>
-  --source=<option>      which side wins on conflict: "remote" = this server (where the workspace shell runs), "local" =
-                         the machine you ran fnd workspace from. Omit to flag conflicts instead of auto-resolving them.
-                         <options: remote|local>
-  --ssh=<value>          (required) remote to connect to, as user@host
+  --delete-remote-dir
+      on exit, delete the remote workspace directory instead of leaving the synced copy in place
+
+  --devtools=<value>
+      expose your LOCAL browser to Claude on the remote via the chrome-devtools MCP. Value is "port" (same port both ends)
+      or "remote:local" (local = this machine, where the browser runs). Your browser must already be listening with
+      --remote-debugging-port=<local>.
+
+  --ignore-vcs
+      don't sync paths matched by the project's .gitignore files (node_modules, build output, …) so each side keeps its
+      own platform-specific artifacts. Every .gitignore in the tree is honoured relative to its directory, like git does.
+      The .git directory itself still syncs, so the remote stays a working repo.
+
+  --remote-base=<value>
+      [default: /home/fnd] base dir on the remote; the workspace lands at <base>/<local-user>/<dir-name>
+
+  --rpc=<value>
+      expose a run_local_command MCP tool to Claude on the remote that executes commands back on THIS machine (the one
+      running fnd workspace). Value is
+      port=<port|remote:local>[,profile=<true|1|false|0>][,shell=<bash|batch|powershell|sh|zsh>] — port opens a reverse
+      tunnel (ssh -R <remote>:localhost:<local>) to a command server started here; shell defaults to the shell fnd
+      workspace was called from; profile (default true) controls whether the shell loads its startup files — with it on,
+      POSIX shells run interactively (-i) so rc files like ~/.bashrc or ~/.zshrc are sourced and tools such as nvm work.
+
+  --source=<option>
+      which side wins on conflict: "remote" = this server (where the workspace shell runs), "local" = the machine you ran
+      fnd workspace from. Omit to flag conflicts instead of auto-resolving them.
+      <options: remote|local>
+
+  --ssh=<value>
+      (required) remote to connect to, as user@host
 
 DESCRIPTION
   Open a remote workspace: two-way sync the current directory to a remote Linux box with Mutagen and drop into a shell
@@ -205,14 +226,20 @@ EXAMPLES
 
   $ fnd workspace --ssh user@host --remote-base /home/fnd
 
+  $ fnd workspace --ssh user@host --ignore-vcs
+
   $ fnd workspace --ssh user@host --devtools 9222
 
   $ fnd workspace --ssh user@host --devtools 9333:9222
 
+  $ fnd workspace --ssh user@host --rpc port=7777:7700
+
+  $ fnd workspace --ssh user@host --rpc port=7777:7700,profile=false,shell=zsh
+
   $ fnd workspace --ssh user@host --delete-remote-dir
 ```
 
-_See code: [src/commands/workspace/index.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.3/src/commands/workspace/index.ts)_
+_See code: [src/commands/workspace/index.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.4.0/src/commands/workspace/index.ts)_
 
 ## `fnd workspace cleanup`
 
@@ -221,7 +248,7 @@ Tear down a leftover workspace — use this if a `workspace` session dropped bef
 ```
 USAGE
   $ fnd workspace cleanup --ssh <value> [--delete-remote-dir] [--devtools] [--remote-base <value>] [--remote-dir
-    <value>]
+    <value>] [--rpc]
 
 FLAGS
   --delete-remote-dir    also delete the remote workspace directory (by default the synced files are left in place)
@@ -229,15 +256,16 @@ FLAGS
                          --devtools)
   --remote-base=<value>  [default: /home/fnd] base dir on the remote, used to derive the default remote directory path
   --remote-dir=<value>   exact remote directory to target (defaults to the current dir mapping)
+  --rpc                  also strip the local-shell MCP entry from the remote (only if the dropped session used --rpc)
   --ssh=<value>          (required) remote to connect to, as user@host
 
 DESCRIPTION
   Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.
 
-  Terminates any Mutagen sync sessions this machine started for the directory. Pass --devtools to also strip the
-  matching chrome-devtools MCP entry from the remote (only do this if the dropped session used --devtools). With no
-  --remote-dir, it targets the same path `workspace` would use for the current directory. The synced files themselves
-  are left in place unless you pass --delete-remote-dir.
+  Terminates any Mutagen sync sessions this machine started for the directory. Pass --devtools or --rpc to also strip
+  the matching MCP entries from the remote (only do this if the dropped session used those flags). With no --remote-dir,
+  it targets the same path `workspace` would use for the current directory. The synced files themselves are left in
+  place unless you pass --delete-remote-dir.
 
 EXAMPLES
   $ fnd workspace cleanup --ssh user@host
@@ -246,8 +274,10 @@ EXAMPLES
 
   $ fnd workspace cleanup --ssh user@host --devtools
 
+  $ fnd workspace cleanup --ssh user@host --rpc
+
   $ fnd workspace cleanup --ssh user@host --delete-remote-dir
 ```
 
-_See code: [src/commands/workspace/cleanup.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.3/src/commands/workspace/cleanup.ts)_
+_See code: [src/commands/workspace/cleanup.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.4.0/src/commands/workspace/cleanup.ts)_
 <!-- commandsstop -->

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

@@ -7,6 +7,7 @@ export default class WorkspaceCleanup extends Command {
         devtools: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'remote-base': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'remote-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        rpc: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         ssh: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;

package/dist/commands/workspace/cleanup.js

@@ -3,11 +3,12 @@ import chalk from 'chalk';
 import { basename } from 'node:path';
 import { buildContext, buildMutagenTerminateSelectorArgs, DEFAULT_MOUNT_BASE, hasMutagen, hasSshClient, parseSshTarget, runMutagen, runRemoteCleanup, slugify, } from '../../lib/workspace.js';
 export default class WorkspaceCleanup extends Command {
-    static description = 'Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.\n\nTerminates any Mutagen sync sessions this machine started for the directory. Pass --devtools to also strip the matching chrome-devtools MCP entry from the remote (only do this if the dropped session used --devtools). With no --remote-dir, it targets the same path `workspace` would use for the current directory. The synced files themselves are left in place unless you pass --delete-remote-dir.';
+    static description = 'Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.\n\nTerminates any Mutagen sync sessions this machine started for the directory. Pass --devtools or --rpc to also strip the matching MCP entries from the remote (only do this if the dropped session used those flags). With no --remote-dir, it targets the same path `workspace` would use for the current directory. The synced files themselves are left in place unless you pass --delete-remote-dir.';
     static examples = [
         '<%= config.bin %> <%= command.id %> --ssh user@host',
         '<%= config.bin %> <%= command.id %> --ssh user@host --remote-dir /home/fnd/cole/fnd-cli',
         '<%= config.bin %> <%= command.id %> --ssh user@host --devtools',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --rpc',
         '<%= config.bin %> <%= command.id %> --ssh user@host --delete-remote-dir',
     ];
     static flags = {
@@ -26,6 +27,10 @@ export default class WorkspaceCleanup extends Command {
         'remote-dir': Flags.string({
             description: 'exact remote directory to target (defaults to the current dir mapping)',
         }),
+        rpc: Flags.boolean({
+            default: false,
+            description: 'also strip the local-shell MCP entry from the remote (only if the dropped session used --rpc)',
+        }),
         ssh: Flags.string({
             description: 'remote to connect to, as user@host',
             required: true,
@@ -53,17 +58,21 @@ export default class WorkspaceCleanup extends Command {
         else {
             this.log(chalk.yellow('Mutagen CLI not found on PATH — skipping sync termination.'));
         }
-        // Strip any chrome-devtools MCP config this workspace left on the remote
-        // (only when asked), and optionally delete the synced directory itself.
+        // Strip any MCP config this workspace left on the remote (only when asked),
+        // and optionally delete the synced directory itself.
         if (flags.devtools) {
             this.log(chalk.dim('Removing any leftover chrome-devtools MCP config on the remote…'));
         }
+        if (flags.rpc) {
+            this.log(chalk.dim('Removing any leftover local-shell MCP config on the remote…'));
+        }
         if (flags['delete-remote-dir']) {
             this.log(chalk.dim('Deleting the remote workspace directory…'));
         }
         const code = await runRemoteCleanup(target2, remoteDir, {
             deleteRemoteDir: flags['delete-remote-dir'],
             removeDevtoolsMcp: flags.devtools,
+            removeRpcMcp: flags.rpc,
         });
         if (code === 0) {
             this.log(chalk.green('✓ Done.'));

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

@@ -5,7 +5,9 @@ export default class Workspace extends Command {
     static flags: {
         '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>;
         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>;
     };

package/dist/commands/workspace/index.js

@@ -1,15 +1,19 @@
 import { Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
 import { spawn } from 'node:child_process';
-import { browserDebugInstructions, buildContext, buildMutagenCreateArgs, buildMutagenFlushArgs, buildMutagenTerminateArgs, buildRemoteScript, DEFAULT_MOUNT_BASE, hasMutagen, hasSshClient, isLocalDebugPortLive, mutagenInstallInstructions, parseDevtoolsPort, parseSshTarget, runMutagen, runRemoteCleanup, } from '../../lib/workspace.js';
+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';
 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 = [
         '<%= config.bin %> <%= command.id %> --ssh user@203.0.113.4',
         '<%= config.bin %> <%= command.id %> --ssh user@host --source local',
         '<%= config.bin %> <%= command.id %> --ssh user@host --remote-base /home/fnd',
+        '<%= 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 --delete-remote-dir',
     ];
     static flags = {
@@ -20,10 +24,17 @@ export default class Workspace extends Command {
         devtools: Flags.string({
             description: 'expose your LOCAL browser to Claude on the remote via the chrome-devtools MCP. Value is "port" (same port both ends) or "remote:local" (local = this machine, where the browser runs). Your browser must already be listening with --remote-debugging-port=<local>.',
         }),
+        'ignore-vcs': Flags.boolean({
+            default: false,
+            description: "don't sync paths matched by the project's .gitignore files (node_modules, build output, …) so each side keeps its own platform-specific artifacts. Every .gitignore in the tree is honoured relative to its directory, like git does. The .git directory itself still syncs, so the remote stays a working repo.",
+        }),
         'remote-base': Flags.string({
             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.`,
+        }),
         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.',
             options: ['remote', 'local'],
@@ -37,14 +48,20 @@ export default class Workspace extends Command {
         const { flags } = await this.parse(Workspace);
         const target = parseSshTarget(flags.ssh);
         const target2 = `${target.user}@${target.host}`;
-        const devtools = flags.devtools === undefined ? undefined : parseDevtoolsPort(flags.devtools);
+        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' });
+        }
         const ctx = buildContext({
             cwd: process.cwd(),
             devtools,
+            ignoreVcs: flags['ignore-vcs'],
             remoteBase: flags['remote-base'],
+            rpc,
             source: flags.source,
         });
-        await this.preflight(devtools);
+        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…'));
@@ -53,6 +70,7 @@ 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 {
             // Block until the first full sync lands so the files exist before the shell opens.
@@ -61,20 +79,33 @@ export default class Workspace extends Command {
             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.devtools);
+            code = await this.runSsh(target2, script, ctx);
         }
         finally {
-            // Best-effort: flush the last edits back, then tear the session down.
+            // Best-effort: stop serving local commands, flush the last edits back, then
+            // tear the session down.
+            await rpcServer?.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 a devtools MCP config there to remove,
-            // or if we were asked to delete the synced directory.
-            if (ctx.devtools || deleteRemoteDir) {
+            // 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())));
@@ -82,6 +113,7 @@ export default class Workspace extends Command {
                     await runRemoteCleanup(target2, ctx.remoteDir, {
                         deleteRemoteDir,
                         removeDevtoolsMcp: Boolean(ctx.devtools),
+                        removeRpcMcp: Boolean(ctx.rpc),
                     });
                 }
                 catch (error) {
@@ -97,7 +129,7 @@ export default class Workspace extends Command {
             : chalk.yellow(`Session ended with exit code ${code}. Cleanup attempted above.`));
     }
     /** Verify this machine can drive the sync before we connect. */
-    async preflight(devtools) {
+    async preflight(devtools, rpc) {
         if (!hasSshClient()) {
             this.error('No `ssh` client found on PATH. Install OpenSSH client and try again.', { code: '1' });
         }
@@ -120,6 +152,13 @@ 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',
+            });
+        }
     }
     printPlan(ctx, target) {
         const sync = ctx.source === undefined
@@ -130,20 +169,27 @@ export default class Workspace extends Command {
         this.log(`  ${chalk.dim('local dir:')}   ${ctx.localCwd}`);
         this.log(`  ${chalk.dim('remote dir:')}  ${ctx.remoteDir}`);
         this.log(`  ${chalk.dim('sync:')}        ${sync}`);
+        if (ctx.ignores) {
+            this.log(`  ${chalk.dim('ignoring:')}    ${ctx.ignores.length} pattern${ctx.ignores.length === 1 ? '' : 's'} from .gitignore files (--ignore-vcs)`);
+        }
         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}`);
+        }
         this.log('');
     }
     /** Run the interactive ssh session, inheriting the TTY so the remote shell is fully interactive. */
-    runSsh(target, script, devtools) {
+    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);
         const args = [
             '-t', // allocate a remote PTY for the interactive shell session
-            // Reverse tunnel for --devtools only: remote 127.0.0.1:<remote> → this
-            // machine's browser at 127.0.0.1:<local>, so the remote's MCP can reach it.
-            ...(devtools
-                ? ['-o', 'ExitOnForwardFailure=yes', '-R', `${devtools.remote}:localhost:${devtools.local}`]
-                : []),
+            ...(forwards.length > 0 ? ['-o', 'ExitOnForwardFailure=yes'] : []),
+            ...forwards.flatMap((f) => ['-R', `${f.remote}:localhost:${f.local}`]),
             target,
             script,
         ];

package/dist/hooks/init/check-for-updates.js

@@ -9,7 +9,7 @@ const hook = async function (opts) {
         });
     });
     if (newestVersion !== opts.config.pjson.version) {
-        console.log(chalk.yellow('💡 Version', chalk.green(newestVersion), 'available! Run', chalk.green('`npm i -g git@github.com:FireNet-Designs/fnd-cli.git`'), 'to update to the latest version!\n'));
+        console.log(chalk.yellow('💡 Version', chalk.green(newestVersion), 'available! Run', chalk.green('`npm i -g @firenet-designs/fnd-cli`'), 'to update to the latest version!\n'));
     }
 };
 export default hook;

package/dist/lib/kv-flag.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+type KvShape = Record<string, z.ZodType>;
+/** Usage string for the schema, required keys first: `a=<...>,b=<...>[,c=<...>]`. */
+export declare const kvUsage: (schema: z.ZodObject<KvShape>) => string;
+/** Example flag value built from each field's example meta (falls back to its hint), required keys first. */
+export declare const kvExample: (schema: z.ZodObject<KvShape>, opts?: {
+    requiredOnly?: boolean;
+}) => string;
+/**
+ * Parse a key=value flag string against the schema. Keys are case-insensitive
+ * and order-independent; unknown keys, duplicate keys, and missing required
+ * keys are hard errors naming the flag and its usage.
+ */
+export declare const parseKvFlag: <T extends KvShape>(flag: string, raw: string, schema: z.ZodObject<T>) => z.output<z.ZodObject<T>>;
+export {};

package/dist/lib/kv-flag.js

@@ -0,0 +1,75 @@
+const fieldMeta = (field) => (field.meta() ?? {});
+const isOptional = (field) => field.def.type === 'default' || field.def.type === 'optional';
+/** Unwrap default/optional/preprocess wrappers down to the schema describing the value. */
+const unwrap = (field) => {
+    const { def } = field;
+    if (def.type === 'default' || def.type === 'optional') {
+        return unwrap(def.innerType);
+    }
+    if (def.type === 'pipe') {
+        return unwrap(def.out);
+    }
+    return field;
+};
+/** The <placeholder> for a field's value: explicit hint meta, enum options, or "value". */
+const fieldHint = (field) => {
+    const { hint } = fieldMeta(field);
+    if (hint)
+        return hint;
+    const inner = unwrap(field);
+    if (inner.def.type === 'enum') {
+        return Object.values(inner.def.entries).join('|');
+    }
+    return 'value';
+};
+/** Usage string for the schema, required keys first: `a=<...>,b=<...>[,c=<...>]`. */
+export const kvUsage = (schema) => {
+    const fields = Object.entries(schema.shape);
+    const required = fields.filter(([, f]) => !isOptional(f));
+    const optional = fields.filter(([, f]) => isOptional(f));
+    const pair = ([key, field]) => `${key}=<${fieldHint(field)}>`;
+    return required.map((f) => pair(f)).join(',') + optional.map((f) => `[,${pair(f)}]`).join('');
+};
+/** Example flag value built from each field's example meta (falls back to its hint), required keys first. */
+export const kvExample = (schema, opts) => {
+    const fields = Object.entries(schema.shape).filter(([, field]) => !(opts?.requiredOnly && isOptional(field)));
+    return [...fields.filter(([, f]) => !isOptional(f)), ...fields.filter(([, f]) => isOptional(f))]
+        .map(([key, field]) => `${key}=${fieldMeta(field).example ?? fieldHint(field)}`)
+        .join(',');
+};
+/**
+ * Parse a key=value flag string against the schema. Keys are case-insensitive
+ * and order-independent; unknown keys, duplicate keys, and missing required
+ * keys are hard errors naming the flag and its usage.
+ */
+export const parseKvFlag = (flag, raw, schema) => {
+    const usage = `${flag} takes comma-separated key=value pairs: ${kvUsage(schema)}`;
+    const known = Object.keys(schema.shape);
+    const pairs = new Map();
+    for (const part of raw.trim().split(',')) {
+        const eq = part.indexOf('=');
+        if (eq === -1) {
+            throw new Error(`${usage} (got "${raw}")`);
+        }
+        const key = part.slice(0, eq).trim().toLowerCase();
+        if (!known.includes(key)) {
+            throw new Error(`${flag} has no "${key}" option. ${usage}`);
+        }
+        if (pairs.has(key)) {
+            throw new Error(`${flag} "${key}" was given more than once (got "${raw}")`);
+        }
+        pairs.set(key, part.slice(eq + 1).trim());
+    }
+    for (const key of known) {
+        if (!isOptional(schema.shape[key]) && !pairs.has(key)) {
+            throw new Error(`${flag} needs "${key}". ${usage}`);
+        }
+    }
+    const result = schema.safeParse(Object.fromEntries(pairs));
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const at = issue.path.join('.');
+        throw new Error(`${flag}${at ? ` ${at}` : ''}: ${issue.message}. ${usage}`);
+    }
+    return result.data;
+};

package/dist/lib/rpc.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { PortPair } from './workspace.js';
+/**
+ * The --rpc local-command server.
+ *
+ * Topology: this machine (the one that ran `fnd workspace`) runs a tiny MCP
+ * server — Streamable HTTP transport, implemented on node:http with no
+ * dependencies — bound to 127.0.0.1:<local>. The workspace's `ssh -R` reverse
+ * tunnel exposes it on the REMOTE at 127.0.0.1:<remote>, where the `claude` CLI
+ * registers it as an HTTP MCP server. When the AI on the remote calls the
+ * `run_local_command` tool, the command executes HERE, on the calling machine,
+ * under the shell chosen in the flag.
+ *
+ * The server binds loopback only; the sole way in from outside is the reverse
+ * tunnel, which lives exactly as long as the ssh session.
+ */
+declare const ShellSchema: z.ZodEnum<{
+    zsh: "zsh";
+    bash: "bash";
+    batch: "batch";
+    powershell: "powershell";
+    sh: "sh";
+}>;
+export declare const RPC_SHELLS: ("zsh" | "bash" | "batch" | "powershell" | "sh")[];
+export type RpcShell = z.infer<typeof ShellSchema>;
+/** Usage and example strings for the --rpc flag, derived from the schema. */
+export declare const RPC_FLAG_USAGE: string;
+export declare const RPC_FLAG_EXAMPLES: {
+    full: string;
+    required: string;
+};
+export interface RpcConfig {
+    /** local = port the server binds on this machine; remote = port opened on the workspace host via `ssh -R`. */
+    ports: PortPair;
+    /** Whether the shell loads its startup files (rc/profile). POSIX shells run with -i, powershell without -NoProfile. */
+    profile: boolean;
+    /** Shell used to execute commands on this machine. */
+    shell: RpcShell;
+}
+/** Handle for a running RPC server. */
+export interface RpcServer {
+    close: () => Promise<void>;
+}
+export declare const RPC_TOOL_NAME = "run_local_command";
+/**
+ * The shell `fnd workspace` was called from: the parent process when it is a
+ * supported shell, else $SHELL, else undefined (e.g. invoked from a script).
+ */
+export declare const detectCallingShell: () => RpcShell | undefined;
+/**
+ * Parse the --rpc value: comma-separated key=value pairs per RpcFlagSchema.
+ *   port=<port> | port=<remote>:<local> — required; `local` is this machine
+ *     (where commands run), `remote` the port opened on the workspace host.
+ *     The single-port form uses the same port on both ends.
+ *   shell=<bash|batch|powershell|sh|zsh> — optional, defaults to the shell
+ *     `fnd workspace` was called from.
+ *   profile=<true|1|false|0> — optional, default true: the shell loads its
+ *     startup files (rc/profile), so tools like nvm are available.
+ */
+export declare const parseRpcFlag: (raw: string) => RpcConfig;
+/** True if the chosen shell is runnable on this machine. */
+export declare const hasLocalShell: (shell: RpcShell, profile: boolean) => boolean;
+/**
+ * Start the local RPC (MCP) server on 127.0.0.1:<ports.local>. Commands execute
+ * with `cwd` as their working directory — the local side of the workspace sync.
+ * Resolves once the port is bound; rejects if binding fails (e.g. port in use).
+ */
+export declare const startRpcServer: (config: RpcConfig, cwd: string) => Promise<RpcServer>;
+export {};