@firenet-designs/fnd-cli 2.1.0 → 2.2.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.2.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.2.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.2.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.2.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,74 @@ 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.2.0/src/commands/token.ts)_
+
+## `fnd workspace`
+
+Open a remote workspace: mirror the current directory onto a remote Linux box via reverse SSHFS and drop into a shell there, cleaning everything up on exit.
+
+```
+USAGE
+  $ fnd workspace --ssh <value> [--local-ssh-port <value>] [--mount-base <value>] [-p <value>]
+
+FLAGS
+  -p, --port=<value>            reverse-tunnel port opened on the remote (random 20000-60000 if omitted)
+      --local-ssh-port=<value>  [default: 22] port your LOCAL SSH server listens on (the tunnel forwards back to this)
+      --mount-base=<value>      [default: /home/fnd] base dir on the remote; the mount lands at
+                                <base>/<local-user>/<dir-name>
+      --ssh=<value>             (required) remote to connect to, as user@host
+
+DESCRIPTION
+  Open a remote workspace: mirror the current directory onto a remote Linux box via reverse SSHFS and drop into a shell
+  there, cleaning everything up on exit.
+
+  The remote reaches your machine through the ssh tunnel (-R), so your local SSH server is never exposed to the internet
+  or port-forwarded. For the back-connection the remote authenticates with its OWN SSH key, which is temporarily added
+  to your local authorized_keys and removed again on exit. Locally you need an SSH *server* running (sshd), not sshfs —
+  sshfs runs on the remote.
+
+EXAMPLES
+  $ fnd workspace --ssh user@203.0.113.4
+
+  $ fnd workspace --ssh user@host --port 40222
+
+  $ fnd workspace --ssh user@host --mount-base /home/fnd --local-ssh-port 2222
+```
+
+_See code: [src/commands/workspace/index.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.2.0/src/commands/workspace/index.ts)_
+
+## `fnd workspace cleanup`
+
+Unmount a leftover reverse-SSHFS mount on the remote — use this if a workspace session dropped before it could clean up after itself.
+
+```
+USAGE
+  $ fnd workspace cleanup --ssh <value> [--mount <value>] [--mount-base <value>]
+
+FLAGS
+  --mount=<value>       exact remote mount path to unmount (defaults to the current dir mapping)
+  --mount-base=<value>  [default: /home/fnd] base dir on the remote, used to derive the default mount path
+  --ssh=<value>         (required) remote to connect to, as user@host
+
+DESCRIPTION
+  Unmount a leftover reverse-SSHFS mount on the remote — use this if a workspace session dropped before it could clean
+  up after itself.
+
+  Unmounts the remote mount and removes the matching entry from your local authorized_keys. With no --mount, it targets
+  the same path `workspace` would use for the current directory.
+
+EXAMPLES
+  $ fnd workspace cleanup --ssh user@host
+
+  $ fnd workspace cleanup --ssh user@host --mount /home/fnd/cole/fnd-cli
+```
+
+_See code: [src/commands/workspace/cleanup.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.2.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: {
+        mount: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'mount-base': import("@oclif/core/interfaces").OptionFlag<string, 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,46 @@
+import { Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { buildContext, DEFAULT_MOUNT_BASE, hasSshClient, keyCommentForMount, parseSshTarget, removeAuthorizedKey, runRemoteCleanup, } from '../../lib/workspace.js';
+export default class WorkspaceCleanup extends Command {
+    static description = 'Unmount a leftover reverse-SSHFS mount on the remote — use this if a workspace session dropped before it could clean up after itself.\n\nUnmounts the remote mount and removes the matching entry from your local authorized_keys. With no --mount, it targets the same path `workspace` would use for the current directory.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --ssh user@host',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --mount /home/fnd/cole/fnd-cli',
+    ];
+    static flags = {
+        mount: Flags.string({
+            description: 'exact remote mount path to unmount (defaults to the current dir mapping)',
+        }),
+        'mount-base': Flags.string({
+            default: DEFAULT_MOUNT_BASE,
+            description: 'base dir on the remote, used to derive the default mount path',
+        }),
+        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 mount = flags.mount ?? buildContext({ cwd: process.cwd(), mountBase: flags['mount-base'] }).mount;
+        this.log(chalk.bold('Cleaning up remote mount'));
+        this.log(`  ${chalk.dim('remote:')} ${target.user}@${target.host}`);
+        this.log(`  ${chalk.dim('mount:')}  ${mount}`);
+        this.log('');
+        const code = await runRemoteCleanup(`${target.user}@${target.host}`, mount);
+        // Revoke local trust for this workspace's key regardless of the remote result.
+        removeAuthorizedKey(keyCommentForMount(mount));
+        if (code === 0) {
+            this.log(chalk.green('✓ Done. Local authorized_keys entry removed.'));
+        }
+        else {
+            this.error(`Cleanup ssh session exited with code ${code} (local authorized_keys entry still removed).`, {
+                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: {
+        'local-ssh-port': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'mount-base': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        port: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        ssh: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+    /** Verify the local machine can actually host the tunnel 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,107 @@
+import { Command, Flags } from '@oclif/core';
+import chalk from 'chalk';
+import { spawn } from 'node:child_process';
+import { addAuthorizedKey, buildContext, buildRemoteScript, DEFAULT_LOCAL_SSH_PORT, DEFAULT_MOUNT_BASE, fetchRemotePublicKey, hasSshClient, isLocalSshdReachable, parseSshTarget, removeAuthorizedKey, runRemoteCleanup, sshServerInstructions, } from '../../lib/workspace.js';
+export default class Workspace extends Command {
+    static description = 'Open a remote workspace: mirror the current directory onto a remote Linux box via reverse SSHFS and drop into a shell there, cleaning everything up on exit.\n\nThe remote reaches your machine through the ssh tunnel (-R), so your local SSH server is never exposed to the internet or port-forwarded. For the back-connection the remote authenticates with its OWN SSH key, which is temporarily added to your local authorized_keys and removed again on exit. Locally you need an SSH *server* running (sshd), not sshfs — sshfs runs on the remote.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %> --ssh user@203.0.113.4',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --port 40222',
+        '<%= config.bin %> <%= command.id %> --ssh user@host --mount-base /home/fnd --local-ssh-port 2222',
+    ];
+    static flags = {
+        'local-ssh-port': Flags.integer({
+            default: DEFAULT_LOCAL_SSH_PORT,
+            description: 'port your LOCAL SSH server listens on (the tunnel forwards back to this)',
+        }),
+        'mount-base': Flags.string({
+            default: DEFAULT_MOUNT_BASE,
+            description: 'base dir on the remote; the mount lands at <base>/<local-user>/<dir-name>',
+        }),
+        port: Flags.integer({
+            char: 'p',
+            description: 'reverse-tunnel port opened on the remote (random 20000-60000 if omitted)',
+        }),
+        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 ctx = buildContext({ cwd: process.cwd(), mountBase: flags['mount-base'], port: flags.port });
+        await this.preflight(flags['local-ssh-port']);
+        this.printPlan(ctx, `${target.user}@${target.host}`);
+        // Read the remote's own public key and trust it locally for the back-connection.
+        const target2 = `${target.user}@${target.host}`;
+        this.log(chalk.dim('Fetching the remote SSH key and trusting it locally…'));
+        const remotePublicKey = fetchRemotePublicKey(target2);
+        addAuthorizedKey(remotePublicKey, ctx.keyComment);
+        let code;
+        try {
+            const script = buildRemoteScript(ctx);
+            code = await this.runSsh(target2, ctx.port, flags['local-ssh-port'], script);
+        }
+        finally {
+            // Tear down from the local side (the remote script has no trap). Best-effort:
+            // if the connection is truly gone, unmounting won't reach the remote either.
+            this.log('');
+            this.log(chalk.dim('Cleaning up the remote mount…'));
+            try {
+                await runRemoteCleanup(target2, ctx.mount);
+            }
+            catch (error) {
+                this.log(chalk.yellow(`Could not reach the remote to unmount (${error.message}). ` +
+                    `Run later:\n  fnd workspace cleanup --ssh ${target2} --mount ${ctx.mount}`));
+            }
+            // Always revoke local trust, even if the session crashed or was killed.
+            removeAuthorizedKey(ctx.keyComment);
+        }
+        this.log('');
+        this.log(code === 0
+            ? chalk.green('✓ Workspace closed. Remote mount unmounted and local trust removed.')
+            : chalk.yellow(`Session ended with exit code ${code}. Cleanup attempted above.`));
+    }
+    /** Verify the local machine can actually host the tunnel before we connect. */
+    async preflight(localSshPort) {
+        if (!hasSshClient()) {
+            this.error('No `ssh` client found on PATH. Install OpenSSH client and try again.', { code: '1' });
+        }
+        const reachable = await isLocalSshdReachable(localSshPort);
+        if (!reachable) {
+            this.log(chalk.red(`✗ No local SSH server answering on 127.0.0.1:${localSshPort}.`));
+            this.log(chalk.yellow('The remote mounts your files by sshing back through the tunnel, so your machine must be running an SSH server.'));
+            this.log('');
+            this.log(sshServerInstructions());
+            this.log('');
+            this.log(chalk.dim('If your sshd listens on another port, pass --local-ssh-port <port>.'));
+            this.error('Local SSH server is required. Aborting before connecting.', { code: '1' });
+        }
+    }
+    printPlan(ctx, target) {
+        this.log(chalk.bold('Opening remote workspace'));
+        this.log(`  ${chalk.dim('remote:')}      ${target}`);
+        this.log(`  ${chalk.dim('mirroring:')}   ${ctx.localCwd}`);
+        this.log(`  ${chalk.dim('mounted at:')}  ${ctx.mount}`);
+        this.log(`  ${chalk.dim('tunnel port:')} ${ctx.port}`);
+        this.log('');
+    }
+    /** Run the interactive ssh session, inheriting the TTY so the remote shell is fully interactive. */
+    runSsh(target, port, localSshPort, script) {
+        const args = [
+            '-t', // allocate a remote PTY for the interactive shell session
+            '-o',
+            'ExitOnForwardFailure=yes', // fail loudly if the remote can't open the -R port
+            '-R',
+            `${port}:localhost:${localSshPort}`,
+            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,89 @@
+/**
+ * Reverse-SSHFS workspace helpers.
+ *
+ * The topology this supports:
+ *
+ *   local machine (any OS)                 remote machine (always Linux)
+ *   ┌─────────────────────┐                ┌──────────────────────────────┐
+ *   │ fnd workspace        │  ssh -R  ───►  │ sshd                          │
+ *   │ your cwd is served   │                │  └─ sshfs -p <port> back ──┐  │
+ *   │ by the LOCAL sshd  ◄─┼── tunnel ──────┼─ localhost:<port> ─────────┘  │
+ *   │ (port 22 by default) │                │  mounts your cwd at <mount>   │
+ *   └─────────────────────┘                └──────────────────────────────┘
+ *
+ * Because the remote reaches your machine THROUGH the ssh tunnel (`-R`), your
+ * local SSH server never has to be exposed to the internet or port-forwarded.
+ *
+ * The back-connection authenticates with the REMOTE's own SSH key: we read the
+ * remote's public key, add it to your local authorized_keys (tagged with a
+ * marker comment), and remove exactly that line on cleanup. We never generate
+ * key material and never delete the remote's key.
+ *
+ * IMPORTANT: locally you need an SSH *server* (sshd) running — NOT sshfs. sshfs
+ * runs on the remote, which is why we check for it there, not here.
+ */
+export interface SshTarget {
+    host: string;
+    user: string;
+}
+export interface WorkspaceContext {
+    /** authorized_keys marker tying the trusted key to this workspace (derivable from the mount). */
+    keyComment: string;
+    /** Absolute path of the current dir on the LOCAL machine (what gets mirrored). */
+    localCwd: string;
+    /** Basename of the local cwd — the leaf of the remote mount path. */
+    localDirName: string;
+    /** Username on the LOCAL machine — used both for the mount path and to auth the sshfs back-connection. */
+    localUser: string;
+    /** Where the mirror is mounted on the REMOTE, e.g. /home/fnd/<localUser>/<localDirName>. */
+    mount: string;
+    /** The reverse-tunnel port opened on the remote (`-R <port>:localhost:<localSshPort>`). */
+    port: number;
+}
+export declare const DEFAULT_MOUNT_BASE = "/home/fnd";
+export declare const DEFAULT_LOCAL_SSH_PORT = 22;
+/** Parse a `user@host` string, throwing a friendly error otherwise. */
+export declare const parseSshTarget: (raw: string) => SshTarget;
+/** The authorized_keys marker comment for a given mount — used to add and later remove the key. */
+export declare const keyCommentForMount: (mount: string) => string;
+/** Build the immutable facts for a workspace session from the local environment + flags. */
+export declare const buildContext: (opts: {
+    cwd: string;
+    mountBase: string;
+    port?: number;
+}) => WorkspaceContext;
+/** POSIX single-quote a string so it can be embedded safely in the remote shell script. */
+export declare const shQuote: (value: string) => string;
+/**
+ * Read the remote's SSH public key so we can trust it locally for the back
+ * connection. Ensures an ed25519 key exists on the remote (creating one only if
+ * the remote has none) and prints it. Returns the single public-key line.
+ */
+export declare const fetchRemotePublicKey: (target: string) => string;
+/** Path to the local user's authorized_keys (cross-platform via os.homedir()). */
+export declare const authorizedKeysPath: () => string;
+/**
+ * Trust the remote's public key locally so it can ssh back in. The marker
+ * comment is appended so cleanup can remove exactly this line later.
+ */
+export declare const addAuthorizedKey: (publicKey: string, comment: string) => void;
+/** Remove any authorized_keys line carrying the given marker comment. */
+export declare const removeAuthorizedKey: (comment: string) => void;
+/**
+ * The bash script the remote runs. It mounts the local cwd via reverse sshfs
+ * (authenticating with its own default key) and drops into an interactive
+ * shell. Teardown (unmount + rmdir) is driven from the LOCAL side in
+ * a `finally` via runRemoteCleanup — no in-script trap, which proved brittle
+ * inside the PTY session.
+ */
+export declare const buildRemoteScript: (ctx: WorkspaceContext) => string;
+/** Run the remote-side teardown (unmount + rmdir) over a fresh ssh connection. */
+export declare const runRemoteCleanup: (target: string, mount: string) => Promise<number>;
+/** The remote-side teardown script (unmount only — the key is the remote's own). */
+export declare const buildCleanupScript: (mount: string) => string;
+/** True if an `ssh` client is on PATH (works on Windows, macOS, Linux). */
+export declare const hasSshClient: () => boolean;
+/** Resolve true if a local SSH server is accepting connections on 127.0.0.1:<port>. */
+export declare const isLocalSshdReachable: (port: number, timeoutMs?: number) => Promise<boolean>;
+/** Platform-specific instructions for turning on the local OpenSSH server. */
+export declare const sshServerInstructions: (platform?: NodeJS.Platform) => string;

package/dist/lib/workspace.js

@@ -0,0 +1,214 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { randomInt } from 'node:crypto';
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { homedir, userInfo } from 'node:os';
+import { basename, join } from 'node:path';
+export const DEFAULT_MOUNT_BASE = '/home/fnd';
+export const DEFAULT_LOCAL_SSH_PORT = 22;
+/** 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] };
+};
+/** The authorized_keys marker comment for a given mount — used to add and later remove the key. */
+export const keyCommentForMount = (mount) => `fnd-workspace:${mount}`;
+/** 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.mountBase.replace(/\/+$/, '');
+    const mount = `${base}/${localUser}/${localDirName}`;
+    // Ephemeral-ish range, kept below 65535 and clear of most well-known ports.
+    const port = opts.port ?? randomInt(20_000, 60_000);
+    return {
+        keyComment: keyCommentForMount(mount),
+        localCwd,
+        localDirName,
+        localUser,
+        mount,
+        port,
+    };
+};
+/** POSIX single-quote a string so it can be embedded safely in the remote shell script. */
+export const shQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
+/**
+ * Read the remote's SSH public key so we can trust it locally for the back
+ * connection. Ensures an ed25519 key exists on the remote (creating one only if
+ * the remote has none) and prints it. Returns the single public-key line.
+ */
+export const fetchRemotePublicKey = (target) => {
+    const remoteScript = [
+        'set -e',
+        'KEY="$HOME/.ssh/id_ed25519"',
+        'mkdir -p "$HOME/.ssh" && chmod 700 "$HOME/.ssh"',
+        'if [ ! -f "$KEY.pub" ]; then ssh-keygen -t ed25519 -N "" -f "$KEY" -q; fi',
+        'cat "$KEY.pub"',
+    ].join('\n');
+    // stdout piped (we capture the key); stdin/stderr inherited so any password or
+    // passphrase prompt still reaches the user's terminal.
+    const result = spawnSync('ssh', [target, remoteScript], {
+        encoding: 'utf8',
+        stdio: ['inherit', 'pipe', 'inherit'],
+    });
+    if (result.error)
+        throw new Error(`Could not ssh to ${target}: ${result.error.message}`);
+    if (result.status !== 0)
+        throw new Error(`Could not read the remote's SSH key (ssh exited ${result.status}).`);
+    const key = (result.stdout ?? '').trim();
+    if (!key.startsWith('ssh-'))
+        throw new Error(`Unexpected remote key output: ${key.slice(0, 80)}`);
+    return key;
+};
+/** Path to the local user's authorized_keys (cross-platform via os.homedir()). */
+export const authorizedKeysPath = () => join(homedir(), '.ssh', 'authorized_keys');
+/**
+ * Trust the remote's public key locally so it can ssh back in. The marker
+ * comment is appended so cleanup can remove exactly this line later.
+ */
+export const addAuthorizedKey = (publicKey, comment) => {
+    const sshDir = join(homedir(), '.ssh');
+    const file = authorizedKeysPath();
+    if (!existsSync(sshDir))
+        mkdirSync(sshDir, { mode: 0o700, recursive: true });
+    const line = `${publicKey.trim()} ${comment}`;
+    const existing = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    const prefix = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    appendFileSync(file, `${prefix}${line}\n`);
+    // sshd ignores authorized_keys with loose perms (POSIX); best-effort on Windows.
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        /* Windows uses ACLs, not POSIX modes — nothing to do here. */
+    }
+};
+/** Remove any authorized_keys line carrying the given marker comment. */
+export const removeAuthorizedKey = (comment) => {
+    const file = authorizedKeysPath();
+    if (!existsSync(file))
+        return;
+    const kept = readFileSync(file, 'utf8')
+        .split('\n')
+        .filter((line) => line.length > 0 && !line.includes(comment));
+    writeFileSync(file, kept.length > 0 ? `${kept.join('\n')}\n` : '');
+};
+/**
+ * The bash script the remote runs. It mounts the local cwd via reverse sshfs
+ * (authenticating with its own default key) and drops into an interactive
+ * shell. Teardown (unmount + rmdir) is driven from the LOCAL side in
+ * a `finally` via runRemoteCleanup — no in-script trap, which proved brittle
+ * inside the PTY session.
+ */
+export const buildRemoteScript = (ctx) => {
+    const mount = shQuote(ctx.mount);
+    // `user@localhost:/absolute/local/path` — quoted whole so spaces survive.
+    const remoteSource = shQuote(`${ctx.localUser}@localhost:${ctx.localCwd}`);
+    const sshfsOpts = [
+        // Connect to the -R tunnel's entrance on the REMOTE's loopback (ctx.port),
+        // which forwards back to the local sshd. NOT the local sshd port directly.
+        `port=${ctx.port}`,
+        'StrictHostKeyChecking=accept-new',
+        'ServerAliveInterval=15',
+        'ServerAliveCountMax=3',
+    ].join(',');
+    return [
+        'set -u',
+        `MOUNT=${mount}`,
+        'AGENT_STARTED=0',
+        // Remote must have sshfs — it is always Linux, so give an apt hint.
+        'if ! command -v sshfs >/dev/null 2>&1; then',
+        '  echo "ERROR: sshfs is not installed on the remote. Install it, e.g.: sudo apt install sshfs" >&2',
+        '  exit 1',
+        'fi',
+        // sshfs daemonizes, so its ssh child can't reliably prompt for a key
+        // passphrase. Load the key into an ssh-agent ONCE (ssh-add prompts cleanly
+        // on this PTY); sshfs then authenticates through the agent, no re-prompts.
+        // eslint-disable-next-line no-template-curly-in-string -- shell parameter expansion, not a JS template
+        'if [ -n "${SSH_AUTH_SOCK:-}" ] && ssh-add -l >/dev/null 2>&1; then',
+        '  :', // an agent with keys is already available — reuse it
+        'else',
+        // eslint-disable-next-line no-template-curly-in-string -- shell parameter expansion, not a JS template
+        '  if [ -z "${SSH_AUTH_SOCK:-}" ]; then eval "$(ssh-agent -s)" >/dev/null && AGENT_STARTED=1; fi',
+        '  echo "Loading your SSH key into the agent (enter its passphrase once if prompted)..."',
+        '  ssh-add </dev/tty || echo "WARNING: ssh-add loaded no key; sshfs may fail to authenticate back to your machine." >&2',
+        'fi',
+        // Clear any stale mount left by a previous dropped session, then (re)create.
+        'fusermount -u "$MOUNT" 2>/dev/null || umount "$MOUNT" 2>/dev/null || true',
+        'mkdir -p "$MOUNT" || { echo "ERROR: could not create $MOUNT" >&2; exit 1; }',
+        'echo "Mounting your local directory over the reverse tunnel..."',
+        `sshfs -o ${sshfsOpts} ${remoteSource} "$MOUNT" || { echo "ERROR: sshfs mount failed" >&2; exit 1; }`,
+        // The mount authenticated at this point; if we started an agent just for
+        // that, kill it so the decrypted key doesn't sit in memory during the session.
+        // eslint-disable-next-line no-template-curly-in-string -- shell parameter expansion, not a JS template
+        '[ "$AGENT_STARTED" = 1 ] && kill "${SSH_AGENT_PID:-}" 2>/dev/null || true',
+        'cd "$MOUNT" || { echo "ERROR: could not enter $MOUNT" >&2; exit 1; }',
+        'echo "Workspace ready at $MOUNT — dropping into a shell (exit to clean up)."',
+        // 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 (unmount + rmdir) over a fresh ssh connection. */
+export const runRemoteCleanup = (target, mount) => new Promise((resolve, reject) => {
+    const child = spawn('ssh', [target, buildCleanupScript(mount)], { stdio: 'inherit' });
+    child.once('error', reject);
+    child.once('close', (code) => resolve(code ?? 0));
+});
+/** The remote-side teardown script (unmount only — the key is the remote's own). */
+export const buildCleanupScript = (mount) => {
+    const quotedMount = shQuote(mount);
+    return [
+        `MOUNT=${quotedMount}`,
+        'if fusermount -u "$MOUNT" 2>/dev/null || fusermount3 -u "$MOUNT" 2>/dev/null || umount "$MOUNT" 2>/dev/null; then',
+        '  echo "Unmounted $MOUNT"',
+        'else',
+        '  echo "Nothing mounted at $MOUNT (or already unmounted)"',
+        'fi',
+        'rmdir "$MOUNT" 2>/dev/null && echo "Removed empty $MOUNT" || true',
+    ].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;
+};
+/** Resolve true if a local SSH server is accepting connections on 127.0.0.1:<port>. */
+export const isLocalSshdReachable = (port, timeoutMs = 2000) => new Promise((resolve) => {
+    const socket = connect({ host: '127.0.0.1', port });
+    const done = (ok) => {
+        socket.destroy();
+        resolve(ok);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once('connect', () => done(true));
+    socket.once('timeout', () => done(false));
+    socket.once('error', () => done(false));
+});
+/** Platform-specific instructions for turning on the local OpenSSH server. */
+export const sshServerInstructions = (platform = process.platform) => {
+    if (platform === 'win32') {
+        return [
+            'Windows — enable the OpenSSH Server (run PowerShell as Administrator):',
+            '  Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0',
+            '  Start-Service sshd',
+            "  Set-Service -Name sshd -StartupType 'Automatic'",
+            '  New-NetFirewallRule -Name sshd -DisplayName "OpenSSH Server" -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22',
+        ].join('\n');
+    }
+    if (platform === 'darwin') {
+        return [
+            'macOS — turn on Remote Login (the built-in SSH server):',
+            '  sudo systemsetup -setremotelogin on',
+            '  # or: System Settings → General → Sharing → Remote Login',
+        ].join('\n');
+    }
+    return [
+        'Linux — install and start the OpenSSH server:',
+        '  Debian/Ubuntu:  sudo apt install openssh-server && sudo systemctl enable --now ssh',
+        '  Fedora/RHEL:    sudo dnf install openssh-server && sudo systemctl enable --now sshd',
+        '  Arch:           sudo pacman -S openssh && sudo systemctl enable --now sshd',
+    ].join('\n');
+};

package/oclif.manifest.json

@@ -182,7 +182,115 @@
         "commands",
         "token.js"
       ]
+    },
+    "workspace:cleanup": {
+      "aliases": [],
+      "args": {},
+      "description": "Unmount a leftover reverse-SSHFS mount on the remote — use this if a workspace session dropped before it could clean up after itself.\n\nUnmounts the remote mount and removes the matching entry from your local authorized_keys. With no --mount, it targets the same path `workspace` would use for the current directory.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --ssh user@host",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --mount /home/fnd/cole/fnd-cli"
+      ],
+      "flags": {
+        "mount": {
+          "description": "exact remote mount path to unmount (defaults to the current dir mapping)",
+          "name": "mount",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "mount-base": {
+          "description": "base dir on the remote, used to derive the default mount path",
+          "name": "mount-base",
+          "default": "/home/fnd",
+          "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: mirror the current directory onto a remote Linux box via reverse SSHFS and drop into a shell there, cleaning everything up on exit.\n\nThe remote reaches your machine through the ssh tunnel (-R), so your local SSH server is never exposed to the internet or port-forwarded. For the back-connection the remote authenticates with its OWN SSH key, which is temporarily added to your local authorized_keys and removed again on exit. Locally you need an SSH *server* running (sshd), not sshfs — sshfs runs on the remote.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %> --ssh user@203.0.113.4",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --port 40222",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --mount-base /home/fnd --local-ssh-port 2222"
+      ],
+      "flags": {
+        "local-ssh-port": {
+          "description": "port your LOCAL SSH server listens on (the tunnel forwards back to this)",
+          "name": "local-ssh-port",
+          "default": 22,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "mount-base": {
+          "description": "base dir on the remote; the mount lands at <base>/<local-user>/<dir-name>",
+          "name": "mount-base",
+          "default": "/home/fnd",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "port": {
+          "char": "p",
+          "description": "reverse-tunnel port opened on the remote (random 20000-60000 if omitted)",
+          "name": "port",
+          "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",
+      "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.2.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.2.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.]
 
 ---