@firenet-designs/fnd-cli 2.1.0 → 2.3.0

package/README.md

@@ -17,31 +17,33 @@ A new CLI generated with oclif
 <!-- usage -->
 ```sh-session
 $ npm install -g @firenet-designs/fnd-cli
-$ fnd-cli COMMAND
+$ fnd COMMAND
 running command...
-$ fnd-cli (--version)
-@firenet-designs/fnd-cli/2.1.0 linux-x64 node-v24.12.0
-$ fnd-cli --help [COMMAND]
+$ fnd (--version)
+@firenet-designs/fnd-cli/2.3.0 linux-x64 node-v24.18.0
+$ fnd --help [COMMAND]
 USAGE
-  $ fnd-cli COMMAND
+  $ fnd COMMAND
 ...
 ```
 <!-- usagestop -->
 # Commands
 <!-- commands -->
-* [`fnd-cli backfill-project [SHOP]`](#fnd-cli-backfill-project-shop)
-* [`fnd-cli create-app`](#fnd-cli-create-app)
-* [`fnd-cli create-project [SHOP]`](#fnd-cli-create-project-shop)
-* [`fnd-cli help [COMMAND]`](#fnd-cli-help-command)
-* [`fnd-cli token`](#fnd-cli-token)
+* [`fnd backfill-project [SHOP]`](#fnd-backfill-project-shop)
+* [`fnd create-app`](#fnd-create-app)
+* [`fnd create-project [SHOP]`](#fnd-create-project-shop)
+* [`fnd help [COMMAND]`](#fnd-help-command)
+* [`fnd token`](#fnd-token)
+* [`fnd workspace`](#fnd-workspace)
+* [`fnd workspace cleanup`](#fnd-workspace-cleanup)
 
-## `fnd-cli backfill-project [SHOP]`
+## `fnd backfill-project [SHOP]`
 
 Backfill missing scaffold files in an EXISTING repo + theme: .gitignore, .shopifyignore, CLAUDE.md. Each is created only if absent — existing files are left untouched. Does NOT git init, pull the theme, commit, or touch GitHub.
 
 ```
 USAGE
-  $ fnd-cli backfill-project [SHOP...]
+  $ fnd backfill-project [SHOP...]
 
 ARGUMENTS
   [SHOP...]  Shopify store handle, passed to Claude as a hint
@@ -53,22 +55,22 @@ DESCRIPTION
   Requires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.
 
 EXAMPLES
-  $ fnd-cli backfill-project
+  $ fnd backfill-project
 
-  $ fnd-cli backfill-project my-store
+  $ fnd backfill-project my-store
 
-  $ fnd-cli backfill-project my-store "extra hints"
+  $ fnd backfill-project my-store "extra hints"
 ```
 
-_See code: [src/commands/backfill-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.1.0/src/commands/backfill-project.ts)_
+_See code: [src/commands/backfill-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.0/src/commands/backfill-project.ts)_
 
-## `fnd-cli create-app`
+## `fnd create-app`
 
 sets up a preconfigued vite app directory on for a shopify theme
 
 ```
 USAGE
-  $ fnd-cli create-app [-d <value>] [-s]
+  $ fnd create-app [-d <value>] [-s]
 
 FLAGS
   -d, --dir=<value>  [default: src] directory to create the vite app in
@@ -78,18 +80,18 @@ DESCRIPTION
   sets up a preconfigued vite app directory on for a shopify theme
 
 EXAMPLES
-  $ fnd-cli create-app
+  $ fnd create-app
 ```
 
-_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.1.0/src/commands/create-app.ts)_
+_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.0/src/commands/create-app.ts)_
 
-## `fnd-cli create-project [SHOP]`
+## `fnd create-project [SHOP]`
 
 Scaffold a new client project: git on branch production, ignore files, Shopify theme pull, a Claude-generated CLAUDE.md, then a private GitHub repo under the FireNet-Designs org.
 
 ```
 USAGE
-  $ fnd-cli create-project [SHOP...]
+  $ fnd create-project [SHOP...]
 
 ARGUMENTS
   [SHOP...]  Shopify store handle — pulls the live theme from <shop>.myshopify.com (omit to skip)
@@ -104,22 +106,22 @@ DESCRIPTION
   never stores credentials. Override the org with FND_GH_ORG.
 
 EXAMPLES
-  $ fnd-cli create-project
+  $ fnd create-project
 
-  $ fnd-cli create-project my-store
+  $ fnd create-project my-store
 
-  $ fnd-cli create-project my-store "Acme storefront, Klaviyo"
+  $ fnd create-project my-store "Acme storefront, Klaviyo"
 ```
 
-_See code: [src/commands/create-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.1.0/src/commands/create-project.ts)_
+_See code: [src/commands/create-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.0/src/commands/create-project.ts)_
 
-## `fnd-cli help [COMMAND]`
+## `fnd help [COMMAND]`
 
-Display help for fnd-cli.
+Display help for fnd.
 
 ```
 USAGE
-  $ fnd-cli help [COMMAND...] [-n]
+  $ fnd help [COMMAND...] [-n]
 
 ARGUMENTS
   [COMMAND...]  Command to show help for.
@@ -128,18 +130,18 @@ FLAGS
   -n, --nested-commands  Include all nested commands in the output.
 
 DESCRIPTION
-  Display help for fnd-cli.
+  Display help for fnd.
 ```
 
-_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v6.2.37/src/commands/help.ts)_
+_See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/6.2.53/src/commands/help.ts)_
 
-## `fnd-cli token`
+## `fnd token`
 
 Mint an offline Shopify Admin API access token (shpat_) for a custom app via the OAuth authorization-code grant. Works cross-org, unlike client_credentials.
 
 ```
 USAGE
-  $ fnd-cli token [-i <value>] [-c <value>] [--no-open] [-p <value>] [--scopes <value>] [-s <value>] [-w
+  $ fnd token [-i <value>] [-c <value>] [--no-open] [-p <value>] [--scopes <value>] [-s <value>] [-w
     <value>]
 
 FLAGS
@@ -156,12 +158,83 @@ DESCRIPTION
   cross-org, unlike client_credentials.
 
 EXAMPLES
-  $ fnd-cli token --store trafalgar-store --client-id 0b42... --client-secret shpss_...
+  $ fnd token --store trafalgar-store --client-id 0b42... --client-secret shpss_...
 
-  $ fnd-cli token -s mystore -i <id> -c <secret> --scopes read_products,read_orders
+  $ fnd token -s mystore -i <id> -c <secret> --scopes read_products,read_orders
 
-  $ fnd-cli token -s mystore -i <id> -c <secret> --write ./.mcp.json
+  $ 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.1.0/src/commands/token.ts)_
+_See code: [src/commands/token.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.0/src/commands/token.ts)_
+
+## `fnd workspace`
+
+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.
+
+```
+USAGE
+  $ fnd workspace --ssh <value> [--devtools <value>] [--remote-base <value>] [--source remote|local]
+
+FLAGS
+  --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
+
+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.
+
+  Both sides keep a real copy on local disk and only deltas cross the network, so the remote reads files at native speed
+  (unlike reverse SSHFS). 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.
+
+EXAMPLES
+  $ fnd workspace --ssh user@203.0.113.4
+
+  $ fnd workspace --ssh user@host --source local
+
+  $ fnd workspace --ssh user@host --remote-base /home/fnd
+
+  $ fnd workspace --ssh user@host --devtools 9222
+
+  $ fnd workspace --ssh user@host --devtools 9333:9222
+```
+
+_See code: [src/commands/workspace/index.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.0/src/commands/workspace/index.ts)_
+
+## `fnd workspace cleanup`
+
+Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.
+
+```
+USAGE
+  $ fnd workspace cleanup --ssh <value> [--remote-base <value>] [--remote-dir <value>]
+
+FLAGS
+  --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)
+  --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 and strips the matching chrome-devtools
+  MCP entry from the remote. With no --remote-dir, it targets the same path `workspace` would use for the current
+  directory. The synced files themselves are left in place.
+
+EXAMPLES
+  $ fnd workspace cleanup --ssh user@host
+
+  $ fnd workspace cleanup --ssh user@host --remote-dir /home/fnd/cole/fnd-cli
+```
+
+_See code: [src/commands/workspace/cleanup.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.3.0/src/commands/workspace/cleanup.ts)_
 <!-- commandsstop -->

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

@@ -0,0 +1,11 @@
+import { Command } from '@oclif/core';
+export default class WorkspaceCleanup extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        '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>;
+        ssh: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/workspace/cleanup.js

@@ -0,0 +1,56 @@
+import { Command, Flags } from '@oclif/core';
+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 and strips the matching chrome-devtools MCP entry from the remote. With no --remote-dir, it targets the same path `workspace` would use for the current directory. The synced files themselves are left in place.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --ssh user@host',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --remote-dir /home/fnd/cole/fnd-cli',
+    ];
+    static flags = {
+        'remote-base': Flags.string({
+            default: DEFAULT_MOUNT_BASE,
+            description: 'base dir on the remote, used to derive the default remote directory path',
+        }),
+        'remote-dir': Flags.string({
+            description: 'exact remote directory to target (defaults to the current dir mapping)',
+        }),
+        ssh: Flags.string({
+            description: 'remote to connect to, as user@host',
+            required: true,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(WorkspaceCleanup);
+        if (!hasSshClient()) {
+            this.error('No `ssh` client found on PATH. Install OpenSSH client and try again.', { code: '1' });
+        }
+        const target = parseSshTarget(flags.ssh);
+        const target2 = `${target.user}@${target.host}`;
+        const remoteDir = flags['remote-dir'] ??
+            buildContext({ cwd: process.cwd(), remoteBase: flags['remote-base'] }).remoteDir;
+        const slug = slugify(basename(remoteDir));
+        this.log(chalk.bold('Cleaning up workspace'));
+        this.log(`  ${chalk.dim('remote:')}     ${target2}`);
+        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.'));
+        }
+        // Strip any chrome-devtools MCP config this workspace left on the remote.
+        this.log(chalk.dim('Removing any leftover chrome-devtools MCP config on the remote…'));
+        const code = await runRemoteCleanup(target2, remoteDir);
+        if (code === 0) {
+            this.log(chalk.green('✓ Done.'));
+        }
+        else {
+            this.error(`Remote cleanup ssh session exited with code ${code}.`, { code: '1' });
+        }
+    }
+}

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

@@ -0,0 +1,17 @@
+import { Command } from '@oclif/core';
+export default class Workspace extends Command {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        devtools: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'remote-base': import("@oclif/core/interfaces").OptionFlag<string, 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>;
+    };
+    run(): Promise<void>;
+    /** Verify this machine can drive the sync before we connect. */
+    private preflight;
+    private printPlan;
+    /** Run the interactive ssh session, inheriting the TTY so the remote shell is fully interactive. */
+    private runSsh;
+}

package/dist/commands/workspace/index.js

@@ -0,0 +1,140 @@
+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';
+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 (unlike reverse SSHFS). 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 --devtools 9222',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9333:9222',
+    ];
+    static flags = {
+        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>.',
+        }),
+        'remote-base': Flags.string({
+            default: DEFAULT_MOUNT_BASE,
+            description: 'base dir on the remote; the workspace lands at <base>/<local-user>/<dir-name>',
+        }),
+        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'],
+        }),
+        ssh: Flags.string({
+            description: 'remote to connect to, as user@host',
+            required: true,
+        }),
+    };
+    async run() {
+        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 ctx = buildContext({
+            cwd: process.cwd(),
+            devtools,
+            remoteBase: flags['remote-base'],
+            source: flags.source,
+        });
+        await this.preflight(devtools);
+        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…'));
+        const createCode = await runMutagen(buildMutagenCreateArgs(ctx, target2));
+        if (createCode !== 0) {
+            this.error(`mutagen sync create failed (exit ${createCode}). Check that the remote is reachable over SSH and try again.`, { code: '1' });
+        }
+        let code;
+        try {
+            // 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' });
+            }
+            const script = buildRemoteScript(ctx);
+            code = await this.runSsh(target2, script, ctx.devtools);
+        }
+        finally {
+            // Best-effort: flush the last edits back, then tear the session down.
+            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);
+            // Only reach back to the remote if we put a devtools MCP config there to remove.
+            if (ctx.devtools) {
+                this.log(chalk.dim('Removing the remote chrome-devtools MCP config…'));
+                try {
+                    await runRemoteCleanup(target2, ctx.remoteDir);
+                }
+                catch (error) {
+                    this.log(chalk.yellow(`Could not reach the remote to remove the devtools config (${error.message}).`));
+                }
+            }
+        }
+        this.log('');
+        this.log(code === 0
+            ? chalk.green('✓ 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) {
+        if (!hasSshClient()) {
+            this.error('No `ssh` client found on PATH. Install OpenSSH client and try again.', { code: '1' });
+        }
+        if (!hasMutagen()) {
+            this.log(chalk.red('✗ Mutagen CLI not found on PATH.'));
+            this.log(chalk.yellow('`fnd workspace` uses Mutagen to two-way sync your files to the remote.'));
+            this.log('');
+            this.log(mutagenInstallInstructions());
+            this.error('Mutagen is required on this machine. Aborting before connecting.', { code: '1' });
+        }
+        // With --devtools, confirm the local browser's debug port is live BEFORE we
+        // connect — otherwise the tunneled MCP would have nothing to reach.
+        if (devtools) {
+            const live = await isLocalDebugPortLive(devtools.local);
+            if (!live) {
+                this.log(chalk.red(`✗ No browser debug endpoint answering on 127.0.0.1:${devtools.local}.`));
+                this.log(chalk.yellow('The chrome-devtools MCP on the remote drives your LOCAL browser through the tunnel.'));
+                this.log('');
+                this.log(browserDebugInstructions(devtools.local));
+                this.error('Local browser remote-debugging port is required for --devtools. Aborting.', { code: '1' });
+            }
+        }
+    }
+    printPlan(ctx, target) {
+        const sync = ctx.source === undefined
+            ? 'two-way, conflicts flagged (pass --source to auto-resolve)'
+            : `two-way, conflicts resolved in favour of ${ctx.source === 'remote' ? 'the remote (this server)' : 'local (the machine you called from)'}`;
+        this.log(chalk.bold('Opening remote workspace'));
+        this.log(`  ${chalk.dim('remote:')}      ${target}`);
+        this.log(`  ${chalk.dim('local dir:')}   ${ctx.localCwd}`);
+        this.log(`  ${chalk.dim('remote dir:')}  ${ctx.remoteDir}`);
+        this.log(`  ${chalk.dim('sync:')}        ${sync}`);
+        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}`);
+        }
+        this.log('');
+    }
+    /** Run the interactive ssh session, inheriting the TTY so the remote shell is fully interactive. */
+    runSsh(target, script, devtools) {
+        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}`]
+                : []),
+            target,
+            script,
+        ];
+        return new Promise((resolve, reject) => {
+            const child = spawn('ssh', args, { stdio: 'inherit' });
+            child.once('error', reject);
+            child.once('close', (code) => resolve(code ?? 0));
+        });
+    }
+}

package/dist/lib/workspace.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Mutagen-backed workspace helpers.
+ *
+ * The topology this supports:
+ *
+ *   local machine (any OS)    Internet     remote machine (always Linux)
+ *   ┌─────────────────────┐                ┌──────────────────────────────┐
+ *   │ fnd workspace       │                │ sshd                         │
+ *   │  └─ mutagen CLI ────┼── ssh ────────►│  └─ mutagen-agent            │
+ *   │     (orchestrator)  │  (two-way sync)│     real copy on local disk  │
+ *   │  your cwd (a real   │◄───────────────┼─ <base>/<user>/<dir>         │
+ *   │  copy on disk)      │   deltas only  │                              │
+ *   └─────────────────────┘                └──────────────────────────────┘
+ *
+ * Unlike the old reverse-SSHFS approach, BOTH sides hold a real copy on local
+ * disk and Mutagen propagates only the deltas. The remote therefore reads files
+ * at native disk speed (no per-file network round-trips), which is the whole
+ * point — lint/build/test on the remote stop being IO-bound on the tunnel.
+ *
+ * Mutagen connects the normal direction (local → remote over SSH), so — unlike
+ * SSHFS — we need NO local SSH server, NO reverse tunnel, and NO authorized_keys
+ * trust dance. Mutagen auto-deploys its agent to the remote over that same SSH
+ * connection; nothing to install on the remote by hand.
+ *
+ * The one reverse tunnel that remains is optional and unrelated to files: with
+ * --devtools we open `ssh -R` so the remote's chrome-devtools MCP can reach the
+ * caller's LOCAL browser.
+ */
+export interface SshTarget {
+    host: string;
+    user: string;
+}
+export interface DevtoolsPorts {
+    /** Remote-debugging port of the browser on the caller's LOCAL machine. */
+    local: number;
+    /** Port opened on the REMOTE (via `ssh -R`) that tunnels back to the local browser. */
+    remote: number;
+}
+/**
+ * Which side wins when the same path changed on both ends since the last sync.
+ * `remote` = this server (the box where the workspace shell runs); `local` = the
+ * machine `fnd workspace` was invoked from. Maps to Mutagen's alpha endpoint in
+ * two-way-resolved mode (alpha always wins conflicts). When left undefined the
+ * session uses two-way-safe mode, which flags conflicts instead of resolving them.
+ */
+export type SyncSource = 'local' | 'remote';
+export interface WorkspaceContext {
+    /** Chrome DevTools MCP tunnel, when --devtools was passed; undefined otherwise. */
+    devtools?: DevtoolsPorts;
+    /** Absolute path of the current dir on the LOCAL machine (one side of the sync). */
+    localCwd: string;
+    /** Basename of the local cwd — the leaf of the remote directory path. */
+    localDirName: string;
+    /** Username on the LOCAL machine — used to namespace the remote directory path. */
+    localUser: string;
+    /** Where the mirror lives on the REMOTE, e.g. /home/fnd/<localUser>/<localDirName>. */
+    remoteDir: string;
+    /** Which endpoint wins conflicts (the Mutagen alpha in two-way-resolved); undefined flags conflicts instead. */
+    source?: SyncSource;
+    /** Unique Mutagen session name for this workspace. */
+    syncName: string;
+}
+export declare const DEFAULT_MOUNT_BASE = "/home/fnd";
+/** Parse a `user@host` string, throwing a friendly error otherwise. */
+export declare const parseSshTarget: (raw: string) => SshTarget;
+/**
+ * Turn an arbitrary directory name into a Mutagen-safe slug (lowercase, only
+ * letters/digits/hyphens). Used both in the session name and the `dir` label so
+ * cleanup can find sessions for a directory without knowing the random suffix.
+ */
+export declare const slugify: (value: string) => string;
+/** A unique Mutagen session name for a workspace on the given local directory. */
+export declare const buildSyncName: (dirName: string) => string;
+/**
+ * Parse the --devtools value. Accepts `port` (same port on both ends) or
+ * `remote:local`, where `local` is the caller's machine (where the browser runs)
+ * and `remote` is the port opened on the workspace host.
+ */
+export declare const parseDevtoolsPort: (raw: string) => DevtoolsPorts;
+/** Build the immutable facts for a workspace session from the local environment + flags. */
+export declare const buildContext: (opts: {
+    cwd: string;
+    devtools?: DevtoolsPorts;
+    remoteBase: string;
+    source?: SyncSource;
+}) => WorkspaceContext;
+/** POSIX single-quote a string so it can be embedded safely in the remote shell script. */
+export declare const shQuote: (value: string) => string;
+/**
+ * The bash script the remote runs for the interactive session. Mutagen already
+ * keeps the directory in sync, so this just makes sure the directory exists,
+ * optionally wires up the chrome-devtools MCP, and drops into a login shell.
+ */
+export declare const buildRemoteScript: (ctx: WorkspaceContext) => string;
+/** Run the remote-side teardown (strip this project's chrome-devtools MCP) over a fresh ssh connection. */
+export declare const runRemoteCleanup: (target: string, remoteDir: string) => Promise<number>;
+/**
+ * The remote-side teardown script: strip this project's chrome-devtools MCP from
+ * the remote's ~/.claude.json. A no-op if there is nothing to undo. The synced
+ * files themselves are left in place — they are a real copy, not a mount.
+ */
+export declare const buildCleanupScript: (remoteDir: string) => string;
+/** True if an `ssh` client is on PATH (works on Windows, macOS, Linux). */
+export declare const hasSshClient: () => boolean;
+/** True if the Mutagen CLI is on PATH and runnable. */
+export declare const hasMutagen: () => boolean;
+/**
+ * Arguments for `mutagen sync create`. With no `source`, the session runs in
+ * two-way-safe mode, which halts and flags conflicts rather than picking a
+ * winner. When a `source` is given, it becomes the Mutagen alpha endpoint and
+ * the mode switches to two-way-resolved (alpha always wins conflicts), so
+ * `--source remote` puts the server first and `--source local` puts this
+ * machine first. Labels let `workspace cleanup` find and terminate orphans.
+ */
+export declare const buildMutagenCreateArgs: (ctx: WorkspaceContext, target: string) => string[];
+/** Arguments for `mutagen sync flush <name>` — block until one full sync completes. */
+export declare const buildMutagenFlushArgs: (name: string) => string[];
+/** Arguments for `mutagen sync terminate <name>` — stop this exact session. */
+export declare const buildMutagenTerminateArgs: (name: string) => string[];
+/** Arguments for terminating any orphaned workspace sessions for a given directory slug. */
+export declare const buildMutagenTerminateSelectorArgs: (dirSlug: string) => string[];
+/** Run a Mutagen CLI command, inheriting stdio so its progress reaches the user. */
+export declare const runMutagen: (args: string[]) => Promise<number>;
+/**
+ * Resolve true if a Chrome/Chromium remote-debugging endpoint answers on
+ * 127.0.0.1:<port> — GET /json/version returns HTTP 200. This is the caller's
+ * LOCAL browser, checked before we open the workspace.
+ */
+export declare const isLocalDebugPortLive: (port: number, timeoutMs?: number) => Promise<boolean>;
+/** Hint for launching a browser with remote debugging enabled on the given port. */
+export declare const browserDebugInstructions: (port: number) => string;
+/** Platform-specific instructions for installing the Mutagen CLI on the machine running `fnd workspace`. */
+export declare const mutagenInstallInstructions: (platform?: NodeJS.Platform) => string;

package/dist/lib/workspace.js

@@ -0,0 +1,258 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { randomInt } from 'node:crypto';
+import { userInfo } from 'node:os';
+import { basename } from 'node:path';
+export const DEFAULT_MOUNT_BASE = '/home/fnd';
+/** Parse a `user@host` string, throwing a friendly error otherwise. */
+export const parseSshTarget = (raw) => {
+    const match = raw.trim().match(/^([^@\s]+)@([^@\s]+)$/);
+    if (!match)
+        throw new Error(`--ssh must be in the form user@host (got "${raw}")`);
+    return { host: match[2], user: match[1] };
+};
+/**
+ * Turn an arbitrary directory name into a Mutagen-safe slug (lowercase, only
+ * letters/digits/hyphens). Used both in the session name and the `dir` label so
+ * cleanup can find sessions for a directory without knowing the random suffix.
+ */
+export const slugify = (value) => value
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, '-')
+    .replaceAll(/^-+|-+$/g, '')
+    .slice(0, 40) || 'workspace';
+/** A unique Mutagen session name for a workspace on the given local directory. */
+export const buildSyncName = (dirName) => `fnd-ws-${slugify(dirName)}-${randomInt(0, 1_000_000).toString(36)}`;
+/**
+ * Parse the --devtools value. Accepts `port` (same port on both ends) or
+ * `remote:local`, where `local` is the caller's machine (where the browser runs)
+ * and `remote` is the port opened on the workspace host.
+ */
+export const parseDevtoolsPort = (raw) => {
+    const toPort = (value) => {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 1 || n > 65_535) {
+            throw new Error(`--devtools port must be an integer 1-65535 (got "${value}")`);
+        }
+        return n;
+    };
+    const parts = raw.trim().split(':');
+    if (parts.length === 1) {
+        const p = toPort(parts[0]);
+        return { local: p, remote: p };
+    }
+    if (parts.length === 2) {
+        return { local: toPort(parts[1]), remote: toPort(parts[0]) };
+    }
+    throw new Error(`--devtools must be "port" or "remote:local" (got "${raw}")`);
+};
+/** Build the immutable facts for a workspace session from the local environment + flags. */
+export const buildContext = (opts) => {
+    const localUser = userInfo().username;
+    const localCwd = opts.cwd;
+    const localDirName = basename(localCwd);
+    const base = opts.remoteBase.replace(/\/+$/, '');
+    const remoteDir = `${base}/${localUser}/${localDirName}`;
+    return {
+        devtools: opts.devtools,
+        localCwd,
+        localDirName,
+        localUser,
+        remoteDir,
+        source: opts.source,
+        syncName: buildSyncName(localDirName),
+    };
+};
+/** POSIX single-quote a string so it can be embedded safely in the remote shell script. */
+export const shQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
+/**
+ * Node program (run on the REMOTE) that adds the chrome-devtools MCP to the
+ * remote's ~/.claude.json under this project (the remote dir). Project-scoped,
+ * never the top-level mcpServers, so it is not globally exposed. Reads the
+ * remote dir and remote tunnel port from the environment.
+ */
+const claudeDevtoolsAddProgram = () => [
+    "const fs = require('node:fs');",
+    "const os = require('node:os');",
+    "const path = require('node:path');",
+    "const file = path.join(os.homedir(), '.claude.json');",
+    'let data = {};',
+    "try { data = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { data = {}; }",
+    'const mount = process.env.FND_MOUNT;',
+    'const port = process.env.FND_DEVTOOLS_PORT;',
+    'if (!data.projects) data.projects = {};',
+    'if (!data.projects[mount]) data.projects[mount] = {};',
+    'const project = data.projects[mount];',
+    'if (!project.mcpServers) project.mcpServers = {};',
+    "project.mcpServers['chrome-devtools'] = { command: 'npx', args: ['-y', 'chrome-devtools-mcp@latest', '--browserUrl', 'http://127.0.0.1:' + port] };",
+    String.raw `fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');`,
+];
+/**
+ * Node program (run on the REMOTE) that removes the chrome-devtools MCP this
+ * workspace added for its project from ~/.claude.json, dropping an emptied
+ * mcpServers map. No-op if the file or entry is absent.
+ */
+const claudeDevtoolsRemoveProgram = () => [
+    "const fs = require('node:fs');",
+    "const os = require('node:os');",
+    "const path = require('node:path');",
+    "const file = path.join(os.homedir(), '.claude.json');",
+    'let data;',
+    "try { data = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { process.exit(0); }",
+    'const mount = process.env.FND_MOUNT;',
+    'const project = data.projects && data.projects[mount];',
+    "if (project && project.mcpServers && project.mcpServers['chrome-devtools']) {",
+    "  delete project.mcpServers['chrome-devtools'];",
+    '  if (Object.keys(project.mcpServers).length === 0) delete project.mcpServers;',
+    String.raw `  fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');`,
+    "  console.log('Removed chrome-devtools MCP config for ' + mount + '.');",
+    '}',
+];
+/**
+ * Wrap a node program in a bash snippet that runs it on the remote with FND_MOUNT
+ * (and optionally FND_DEVTOOLS_PORT) in the environment, skipping gracefully if
+ * node is missing.
+ */
+const runNodeOnRemote = (program, env, okMessage) => [
+    'if command -v node >/dev/null 2>&1; then',
+    `  ${env} node <<'FND_NODE_EOF'`,
+    ...program,
+    'FND_NODE_EOF',
+    ...(okMessage ? [`  echo ${shQuote(okMessage)}`] : []),
+    'else',
+    '  echo "WARNING: node not found on the remote; skipped chrome-devtools MCP config." >&2',
+    'fi',
+];
+/**
+ * The bash script the remote runs for the interactive session. Mutagen already
+ * keeps the directory in sync, so this just makes sure the directory exists,
+ * optionally wires up the chrome-devtools MCP, and drops into a login shell.
+ */
+export const buildRemoteScript = (ctx) => {
+    const dir = shQuote(ctx.remoteDir);
+    const devtoolsSetup = ctx.devtools
+        ? runNodeOnRemote(claudeDevtoolsAddProgram(), `FND_MOUNT=${dir} FND_DEVTOOLS_PORT=${ctx.devtools.remote}`, `Configured chrome-devtools MCP for this workspace (browser via 127.0.0.1:${ctx.devtools.remote}).`)
+        : [];
+    return [
+        'set -u',
+        `DIR=${dir}`,
+        // Mutagen creates the sync root, but ensure it exists so `cd` never races it.
+        'mkdir -p "$DIR" || { echo "ERROR: could not create $DIR" >&2; exit 1; }',
+        ...devtoolsSetup,
+        'cd "$DIR" || { echo "ERROR: could not enter $DIR" >&2; exit 1; }',
+        'echo "Workspace ready at $DIR — files sync in the background (exit to stop syncing)."',
+        // eslint-disable-next-line no-template-curly-in-string -- shell parameter expansion, not a JS template
+        '"${SHELL:-bash}" -l',
+    ].join('\n');
+};
+/** Run the remote-side teardown (strip this project's chrome-devtools MCP) over a fresh ssh connection. */
+export const runRemoteCleanup = (target, remoteDir) => new Promise((resolve, reject) => {
+    const child = spawn('ssh', [target, buildCleanupScript(remoteDir)], { stdio: 'inherit' });
+    child.once('error', reject);
+    child.once('close', (code) => resolve(code ?? 0));
+});
+/**
+ * The remote-side teardown script: strip this project's chrome-devtools MCP from
+ * the remote's ~/.claude.json. A no-op if there is nothing to undo. The synced
+ * files themselves are left in place — they are a real copy, not a mount.
+ */
+export const buildCleanupScript = (remoteDir) => runNodeOnRemote(claudeDevtoolsRemoveProgram(), `FND_MOUNT=${shQuote(remoteDir)}`).join('\n');
+/** True if an `ssh` client is on PATH (works on Windows, macOS, Linux). */
+export const hasSshClient = () => {
+    const result = spawnSync('ssh', ['-V'], { stdio: 'ignore' });
+    return !result.error;
+};
+/** True if the Mutagen CLI is on PATH and runnable. */
+export const hasMutagen = () => {
+    const result = spawnSync('mutagen', ['version'], { stdio: 'ignore' });
+    return !result.error && result.status === 0;
+};
+/**
+ * Arguments for `mutagen sync create`. With no `source`, the session runs in
+ * two-way-safe mode, which halts and flags conflicts rather than picking a
+ * winner. When a `source` is given, it becomes the Mutagen alpha endpoint and
+ * the mode switches to two-way-resolved (alpha always wins conflicts), so
+ * `--source remote` puts the server first and `--source local` puts this
+ * machine first. Labels let `workspace cleanup` find and terminate orphans.
+ */
+export const buildMutagenCreateArgs = (ctx, target) => {
+    const local = ctx.localCwd;
+    const remote = `${target}:${ctx.remoteDir}`;
+    // Alpha only matters as the conflict winner in resolved mode; in safe mode the
+    // order is cosmetic, so keep local-first for a stable, readable command.
+    const [alpha, beta] = ctx.source === 'remote' ? [remote, local] : [local, remote];
+    const syncMode = ctx.source === undefined ? 'two-way-safe' : 'two-way-resolved';
+    return [
+        'sync',
+        'create',
+        `--name=${ctx.syncName}`,
+        '--label=managed-by=fnd-workspace',
+        `--label=dir=${slugify(ctx.localDirName)}`,
+        `--sync-mode=${syncMode}`,
+        alpha,
+        beta,
+    ];
+};
+/** Arguments for `mutagen sync flush <name>` — block until one full sync completes. */
+export const buildMutagenFlushArgs = (name) => ['sync', 'flush', name];
+/** Arguments for `mutagen sync terminate <name>` — stop this exact session. */
+export const buildMutagenTerminateArgs = (name) => ['sync', 'terminate', name];
+/** Arguments for terminating any orphaned workspace sessions for a given directory slug. */
+export const buildMutagenTerminateSelectorArgs = (dirSlug) => [
+    'sync',
+    'terminate',
+    `--label-selector=managed-by=fnd-workspace,dir=${dirSlug}`,
+];
+/** Run a Mutagen CLI command, inheriting stdio so its progress reaches the user. */
+export const runMutagen = (args) => new Promise((resolve, reject) => {
+    const child = spawn('mutagen', args, { stdio: 'inherit' });
+    child.once('error', reject);
+    child.once('close', (code) => resolve(code ?? 0));
+});
+/**
+ * Resolve true if a Chrome/Chromium remote-debugging endpoint answers on
+ * 127.0.0.1:<port> — GET /json/version returns HTTP 200. This is the caller's
+ * LOCAL browser, checked before we open the workspace.
+ */
+export const isLocalDebugPortLive = async (port, timeoutMs = 2000) => {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/json/version`, { signal: controller.signal });
+        return res.status === 200;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+/** Hint for launching a browser with remote debugging enabled on the given port. */
+export const browserDebugInstructions = (port) => [
+    `Start your browser with remote debugging on port ${port}, e.g.:`,
+    `  Chrome/Chromium:  google-chrome --remote-debugging-port=${port}`,
+    `  macOS:            "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=${port}`,
+    `Then confirm it answers:  curl http://127.0.0.1:${port}/json/version`,
+].join('\n');
+/** Platform-specific instructions for installing the Mutagen CLI on the machine running `fnd workspace`. */
+export const mutagenInstallInstructions = (platform = process.platform) => {
+    if (platform === 'win32') {
+        return [
+            'Windows — install the Mutagen CLI:',
+            '  scoop install mutagen',
+            '  # or: choco install mutagen',
+            '  # or download from https://github.com/mutagen-io/mutagen/releases and put mutagen.exe on PATH',
+        ].join('\n');
+    }
+    if (platform === 'darwin') {
+        return [
+            'macOS — install the Mutagen CLI:',
+            '  brew install mutagen-io/mutagen/mutagen',
+        ].join('\n');
+    }
+    return [
+        'Linux — install the Mutagen CLI:',
+        '  brew install mutagen-io/mutagen/mutagen',
+        '  # or download from https://github.com/mutagen-io/mutagen/releases and put mutagen on PATH',
+    ].join('\n');
+};

package/oclif.manifest.json

@@ -182,7 +182,119 @@
         "commands",
         "token.js"
       ]
+    },
+    "workspace:cleanup": {
+      "aliases": [],
+      "args": {},
+      "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 and strips the matching chrome-devtools MCP entry from the remote. With no --remote-dir, it targets the same path `workspace` would use for the current directory. The synced files themselves are left in place.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --ssh user@host",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --remote-dir /home/fnd/cole/fnd-cli"
+      ],
+      "flags": {
+        "remote-base": {
+          "description": "base dir on the remote, used to derive the default remote directory path",
+          "name": "remote-base",
+          "default": "/home/fnd",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "remote-dir": {
+          "description": "exact remote directory to target (defaults to the current dir mapping)",
+          "name": "remote-dir",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "ssh": {
+          "description": "remote to connect to, as user@host",
+          "name": "ssh",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "workspace:cleanup",
+      "pluginAlias": "@firenet-designs/fnd-cli",
+      "pluginName": "@firenet-designs/fnd-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "workspace",
+        "cleanup.js"
+      ]
+    },
+    "workspace": {
+      "aliases": [],
+      "args": {},
+      "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 (unlike reverse SSHFS). 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.",
+      "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 --devtools 9222",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9333:9222"
+      ],
+      "flags": {
+        "devtools": {
+          "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>.",
+          "name": "devtools",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "remote-base": {
+          "description": "base dir on the remote; the workspace lands at <base>/<local-user>/<dir-name>",
+          "name": "remote-base",
+          "default": "/home/fnd",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "source": {
+          "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.",
+          "name": "source",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "remote",
+            "local"
+          ],
+          "type": "option"
+        },
+        "ssh": {
+          "description": "remote to connect to, as user@host",
+          "name": "ssh",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "workspace",
+      "pluginAlias": "@firenet-designs/fnd-cli",
+      "pluginName": "@firenet-designs/fnd-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "workspace",
+        "index.js"
+      ]
     }
   },
-  "version": "2.1.0"
+  "version": "2.3.0"
 }

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@firenet-designs/fnd-cli",
   "description": "A new CLI generated with oclif",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "author": "Cole Denslow",
+  "contributors": [
+    "Justin Schellenberg"
+  ],
   "bin": {
     "fnd": "bin/run.js"
   },
@@ -26,15 +29,18 @@
     "eslint": "^9",
     "eslint-config-oclif": "^6",
     "eslint-config-prettier": "^10",
-    "mocha": "^10",
+    "mocha": "^11",
     "oclif": "^4",
-    "shx": "^0.3.3",
+    "shx": "^0.4.0",
     "ts-node": "^10",
     "typescript": "^5"
   },
   "engines": {
     "node": ">=24.0.0"
   },
+  "overrides": {
+    "glob": "^13"
+  },
   "files": [
     "./bin",
     "./dist",
@@ -53,7 +59,7 @@
   },
   "type": "module",
   "oclif": {
-    "bin": "fnd-cli",
+    "bin": "fnd",
     "dirname": "fnd-cli",
     "commands": "./dist/commands",
     "hooks": {
@@ -68,6 +74,9 @@
     "topics": {
       "hello": {
         "description": "Say hello to the world and others"
+      },
+      "workspace": {
+        "description": "Open a remote reverse-SSHFS workspace and run Claude on it"
       }
     }
   },

package/prompts/init-project-auto.md

@@ -19,7 +19,7 @@ Look at the current directory to infer the fields. Useful signals:
 - `@shopify/hydrogen` in deps, or `app/routes/` + `remix`/`vite` → **Shopify Hydrogen**.
 - `next.config.*` or `next` in deps → **Next.js**.
 - An Express/Fastify/Hono server entry with no frontend → **Node API**.
-- Anything else → **Custom** (write 4–6 conventions tailored to the actual stack).
+- Anything else → **Custom** (write 4-6 conventions tailored to the actual stack).
 - `tsconfig.json`, lockfile type (`package-lock.json`/`pnpm-lock.yaml`/`yarn.lock`/`bun.lockb`), `.nvmrc`/`engines` → runtime + package manager.
 - `.env.example` / `.env.sample` → external services (Klaviyo, Stripe, Shopify Admin API, a DB URL, etc.).
 - Top two levels of the directory tree → Project Structure block.
@@ -70,7 +70,7 @@ These apply to every file touched in this project.
 
 ## Conventions
 
-[Insert the matching preset block below for the detected type. For Custom, write 4–6 stack-specific rules, one per line, imperative voice.]
+[Insert the matching preset block below for the detected type. For Custom, write 4-6 stack-specific rules, one per line, imperative voice.]
 
 ---