@firenet-designs/fnd-cli 2.0.0 → 2.2.0

package/README.md

@@ -17,29 +17,60 @@ 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.0.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 create-app`](#fnd-cli-create-app)
-* [`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 create-app`
+## `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 backfill-project [SHOP...]
+
+ARGUMENTS
+  [SHOP...]  Shopify store handle, passed to Claude as a hint
+
+DESCRIPTION
+  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.
+
+  Requires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.
+
+EXAMPLES
+  $ fnd backfill-project
+
+  $ fnd backfill-project my-store
+
+  $ fnd backfill-project my-store "extra hints"
+```
+
+_See code: [src/commands/backfill-project.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.2.0/src/commands/backfill-project.ts)_
+
+## `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
@@ -49,18 +80,48 @@ 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.2.0/src/commands/create-app.ts)_
+
+## `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 create-project [SHOP...]
+
+ARGUMENTS
+  [SHOP...]  Shopify store handle — pulls the live theme from <shop>.myshopify.com (omit to skip)
+
+DESCRIPTION
+  Scaffold a new client project: git on branch production, ignore files, Shopify theme pull, a Claude-generated
+  CLAUDE.md, then a private GitHub repo under the FireNet-Designs org.
+
+  Requires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.
+
+  GitHub auth comes from YOUR environment — run `gh auth login` once, or export GH_TOKEN in your shell profile. This CLI
+  never stores credentials. Override the org with FND_GH_ORG.
+
+EXAMPLES
+  $ fnd create-project
+
+  $ fnd create-project my-store
+
+  $ fnd create-project my-store "Acme storefront, Klaviyo"
 ```
 
-_See code: [src/commands/create-app.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.0.0/src/commands/create-app.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.
@@ -69,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
@@ -97,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 token -s mystore -i <id> -c <secret> --scopes read_products,read_orders
+
+  $ 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.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
 
-  $ fnd-cli token -s mystore -i <id> -c <secret> --scopes read_products,read_orders
+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-cli token -s mystore -i <id> -c <secret> --write ./.mcp.json
+  $ fnd workspace cleanup --ssh user@host --mount /home/fnd/cole/fnd-cli
 ```
 
-_See code: [src/commands/token.ts](https://github.com/FireNet-Designs/fnd-cli/blob/v2.0.0/src/commands/token.ts)_
+_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/backfill-project.d.ts

@@ -0,0 +1,10 @@
+import { Command } from '@oclif/core';
+export default class BackfillProject extends Command {
+    static args: {
+        shop: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static strict: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/backfill-project.js

@@ -0,0 +1,61 @@
+import { Args, Command } from '@oclif/core';
+import chalk from 'chalk';
+import { existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { generateClaudeMd, GITIGNORE_CONTENT, initPromptPath, SHOPIFYIGNORE_CONTENT, } from '../lib/scaffold.js';
+export default class BackfillProject extends Command {
+    static args = {
+        shop: Args.string({ description: 'Shopify store handle, passed to Claude as a hint', required: false }),
+    };
+    static description = '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.\n\nRequires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> my-store',
+        '<%= config.bin %> <%= command.id %> my-store "extra hints"',
+    ];
+    // Everything after the shop handle is collected as free-form hints for Claude.
+    static strict = false;
+    async run() {
+        const { argv } = await this.parse(BackfillProject);
+        const [shop, ...rest] = argv;
+        const hints = rest.join(' ');
+        if (existsSync('.gitignore')) {
+            this.log(chalk.dim('✓ .gitignore exists — skipping'));
+        }
+        else {
+            writeFileSync('.gitignore', GITIGNORE_CONTENT);
+            this.log(chalk.green('✅ .gitignore created'));
+        }
+        if (existsSync('.shopifyignore')) {
+            this.log(chalk.dim('✓ .shopifyignore exists — skipping'));
+        }
+        else {
+            writeFileSync('.shopifyignore', SHOPIFYIGNORE_CONTENT);
+            this.log(chalk.green('✅ .shopifyignore created'));
+        }
+        if (existsSync(join(process.cwd(), 'CLAUDE.md'))) {
+            this.log(chalk.dim('✓ CLAUDE.md exists — skipping'));
+            return;
+        }
+        this.log(chalk.blue('🤖 Generating CLAUDE.md with Claude…'));
+        const result = await generateClaudeMd(shop, hints);
+        switch (result) {
+            case 'claude-not-installed': {
+                this.error('claude CLI not found — install it with: npm install -g @anthropic-ai/claude-code', { code: '1' });
+                break;
+            }
+            case 'missing-prompt': {
+                this.error(`bundled prompt missing at ${initPromptPath()} — try reinstalling @firenet-designs/fnd-cli`, { code: '1' });
+                break;
+            }
+            case 'not-written': {
+                this.warn('Claude finished but no CLAUDE.md was found — check the output above');
+                break;
+            }
+            case 'written': {
+                this.log(chalk.green(`✅ CLAUDE.md written to ${process.cwd()}`));
+                break;
+            }
+        }
+    }
+}

package/dist/commands/create-project.d.ts

@@ -0,0 +1,10 @@
+import { Command } from '@oclif/core';
+export default class CreateProject extends Command {
+    static args: {
+        shop: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static strict: boolean;
+    run(): Promise<void>;
+}

package/dist/commands/create-project.js

@@ -0,0 +1,122 @@
+import { Args, Command } from '@oclif/core';
+import chalk from 'chalk';
+import { spawnSync } from 'node:child_process';
+import { existsSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { simpleGit } from 'simple-git';
+import { findShopifyBin, generateClaudeMd, GITIGNORE_CONTENT, initPromptPath, run, SHOPIFYIGNORE_CONTENT, which, } from '../lib/scaffold.js';
+export default class CreateProject extends Command {
+    static args = {
+        shop: Args.string({ description: 'Shopify store handle — pulls the live theme from <shop>.myshopify.com (omit to skip)', required: false }),
+    };
+    static description = 'Scaffold a new client project: git on branch production, ignore files, Shopify theme pull, a Claude-generated CLAUDE.md, then a private GitHub repo under the FireNet-Designs org.\n\nRequires the claude CLI (npm install -g @anthropic-ai/claude-code) for the CLAUDE.md step.\n\nGitHub auth comes from YOUR environment — run `gh auth login` once, or export GH_TOKEN in your shell profile. This CLI never stores credentials. Override the org with FND_GH_ORG.';
+    static examples = [
+        '<%= config.bin %> <%= command.id %>',
+        '<%= config.bin %> <%= command.id %> my-store',
+        '<%= config.bin %> <%= command.id %> my-store "Acme storefront, Klaviyo"',
+    ];
+    // Everything after the shop handle is collected as free-form hints for Claude.
+    static strict = false;
+    async run() {
+        const { argv } = await this.parse(CreateProject);
+        const [shop, ...rest] = argv;
+        const hints = rest.join(' ');
+        const git = simpleGit();
+        // 1. git init on branch 'production'
+        if (existsSync(join(process.cwd(), '.git'))) {
+            this.log(chalk.blue('ℹ️  git repo already initialized — leaving the current branch as-is'));
+        }
+        else {
+            await git.raw(['init', '-b', 'production']);
+            this.log(chalk.green("✅ git initialized on branch 'production'"));
+        }
+        // 2. ignore files (always written, matching the original scaffold)
+        writeFileSync('.gitignore', GITIGNORE_CONTENT);
+        writeFileSync('.shopifyignore', SHOPIFYIGNORE_CONTENT);
+        this.log(chalk.green('✅ .gitignore and .shopifyignore created'));
+        // 3. Pull the live Shopify theme so Claude can inspect real files when it
+        // writes CLAUDE.md. Only runs when a shop handle was passed.
+        if (shop) {
+            const shopifyBin = findShopifyBin();
+            if (shopifyBin) {
+                // Prepend the binary's own dir so its `env node` shebang resolves to
+                // the node it was installed with, not an older active version.
+                this.log(chalk.blue(`🎨 Pulling Shopify theme from store '${shop}' (via ${shopifyBin})…`));
+                const env = { ...process.env, PATH: `${dirname(shopifyBin)}:${process.env.PATH}` };
+                await run(shopifyBin, ['theme', 'pull', `--store=${shop}`], env);
+            }
+            else {
+                this.log(chalk.blue(`ℹ️  shopify CLI not found — run manually: shopify theme pull --store=${shop}`));
+            }
+        }
+        // 4. CLAUDE.md via Claude (skipped with a warning when claude isn't
+        // installed — the GitHub step below still runs)
+        this.log(chalk.blue('🤖 Generating CLAUDE.md with Claude…'));
+        const claudeResult = await generateClaudeMd(shop, hints);
+        switch (claudeResult) {
+            case 'claude-not-installed': {
+                this.warn('claude CLI not found — skipping CLAUDE.md. Install it with: npm install -g @anthropic-ai/claude-code');
+                break;
+            }
+            case 'missing-prompt': {
+                this.error(`bundled prompt missing at ${initPromptPath()} — try reinstalling @firenet-designs/fnd-cli`, { code: '1' });
+                break;
+            }
+            case 'not-written': {
+                this.warn('Claude finished but no CLAUDE.md was found — check the output above');
+                break;
+            }
+            case 'written': {
+                this.log(chalk.green(`✅ CLAUDE.md written to ${process.cwd()}`));
+                break;
+            }
+        }
+        // 5. Private GitHub repo. The create-only token (GH_TOKEN) is used by gh
+        // for the API call only; the push goes over SSH with the user's own key.
+        if (!which('gh')) {
+            this.log(chalk.blue('ℹ️  gh not installed — skipping GitHub. Install with: brew install gh'));
+            return;
+        }
+        const hasTokenInEnv = Boolean(process.env.GH_TOKEN || process.env.GITHUB_TOKEN);
+        const ghAuthenticated = spawnSync('gh', ['auth', 'status'], { stdio: 'ignore' }).status === 0;
+        if (!hasTokenInEnv && !ghAuthenticated) {
+            this.log(chalk.yellow('⚠️  No GitHub auth found — skipping repo creation. Set it up once, then re-run:'));
+            this.log(chalk.yellow('   • easiest:  gh auth login'));
+            this.log(chalk.yellow('   • or add to your shell profile (~/.zshrc):  export GH_TOKEN=<fine-grained PAT>'));
+            this.log(chalk.yellow('     (PAT only needs repo-create on the FireNet-Designs org — push goes over your SSH key)'));
+            return;
+        }
+        const remotes = await git.getRemotes();
+        if (remotes.some((r) => r.name === 'origin')) {
+            this.log(chalk.blue("ℹ️  remote 'origin' already set — skipping GitHub repo creation"));
+            return;
+        }
+        const org = process.env.FND_GH_ORG || 'FireNet-Designs';
+        const repo = `${org}/${basename(process.cwd())}`;
+        this.log(chalk.blue('📦 Committing initial scaffold…'));
+        await git.raw(['add', '-A']);
+        try {
+            await git.raw(['commit', '-q', '-m', 'initial commit']);
+        }
+        catch {
+            this.error('nothing to commit — aborting GitHub step', { code: '1' });
+        }
+        this.log(chalk.blue(`🐙 Creating private GitHub repo '${repo}'…`));
+        const createCode = await run('gh', ['repo', 'create', repo, '--private', '--source=.', '--remote=origin']);
+        if (createCode !== 0) {
+            this.error('gh repo create failed — see output above', { code: '1' });
+        }
+        // Force SSH so the push authenticates with the user's key, not the
+        // create-only token.
+        await git.raw(['remote', 'set-url', 'origin', `git@github.com:${repo}.git`]);
+        this.log(chalk.blue("⬆️  Pushing 'production' to origin over SSH…"));
+        const pushCode = await run('git', ['push', '-u', 'origin', 'production']);
+        if (pushCode === 0) {
+            spawnSync('gh', ['repo', 'edit', repo, '--default-branch', 'production'], { stdio: 'ignore' });
+            this.log(chalk.green(`✅ Created + pushed. origin = git@github.com:${repo}.git`));
+        }
+        else {
+            this.warn(`push failed — check your SSH access to the ${org} org`);
+        }
+    }
+}

package/dist/commands/token.d.ts

@@ -13,6 +13,8 @@ export default class Token extends Command {
     };
     run(): Promise<void>;
     private mcpSnippet;
+    /** Loud, boxed reminder of the one-time Dev Dashboard setup. */
+    private printSetupBanner;
     /** Minimal readline prompt — keeps the CLI dependency-free. */
     private prompt;
     private runOAuthFlow;

package/dist/commands/token.js

@@ -50,11 +50,7 @@ export default class Token extends Command {
         const { scopes } = flags;
         const { port } = flags;
         const redirectUri = `http://localhost:${port}/callback`;
-        this.log('');
-        this.log(chalk.dim('Before continuing, the app must list this exact redirect URL:'));
-        this.log('  ' + chalk.cyan(redirectUri));
-        this.log(chalk.dim('and have these scopes released:') + ' ' + chalk.cyan(scopes));
-        this.log('');
+        this.printSetupBanner(redirectUri, scopes);
         const token = await this.runOAuthFlow({ clientId, clientSecret, open: !flags['no-open'], port, redirectUri, scopes, store });
         this.log('');
         this.log(chalk.green('✓ Offline access token (never expires until uninstall/secret rotation):'));
@@ -79,6 +75,37 @@ export default class Token extends Command {
         };
         return chalk.dim(JSON.stringify(config, null, 2));
     }
+    /** Loud, boxed reminder of the one-time Dev Dashboard setup. */
+    printSetupBanner(redirectUri, scopes) {
+        const rows = [
+            { kind: 'header', text: '⚠  ONE-TIME APP SETUP — in the Shopify Dev Dashboard' },
+            { kind: 'body', text: '' },
+            { kind: 'body', text: 'The custom app for this store MUST have BOTH of these,' },
+            { kind: 'body', text: 'or Shopify shows an error instead of an approve screen:' },
+            { kind: 'body', text: '' },
+            { kind: 'body', text: '1) Add this Redirect URL to the app (exactly):' },
+            { kind: 'value', text: `     ${redirectUri}` },
+            { kind: 'body', text: '2) Release a version with this scope:' },
+            { kind: 'value', text: `     ${scopes}` },
+        ];
+        const width = Math.max(...rows.map((r) => r.text.length));
+        const bar = '─'.repeat(width + 2);
+        this.log('');
+        this.log(chalk.yellow.bold(`┌${bar}┐`));
+        for (const row of rows) {
+            const padded = ` ${row.text.padEnd(width)} `;
+            let body;
+            if (row.kind === 'header')
+                body = chalk.bgYellow.black.bold(padded);
+            else if (row.kind === 'value')
+                body = chalk.cyanBright.bold(padded);
+            else
+                body = chalk.yellow(padded);
+            this.log(chalk.yellow.bold('│') + body + chalk.yellow.bold('│'));
+        }
+        this.log(chalk.yellow.bold(`└${bar}┘`));
+        this.log('');
+    }
     /** Minimal readline prompt — keeps the CLI dependency-free. */
     async prompt(label) {
         const rl = createInterface({ input: stdin, output: stdout });
@@ -110,16 +137,30 @@ export default class Token extends Command {
                 }
                 const code = url.searchParams.get('code');
                 const returnedState = url.searchParams.get('state');
+                const oauthError = url.searchParams.get('error');
                 const fail = (message, httpBody) => {
                     res.writeHead(400, { 'Content-Type': 'text/html' }).end(httpBody);
                     spinner.fail(message);
                     server.close();
                     reject(new Error(message));
                 };
-                if (returnedState !== state)
-                    return fail('State mismatch (possible CSRF) — aborting.', '<h2>State mismatch. Restart the flow.</h2>');
+                // Ignore spurious/stale hits — a bare probe, or a leftover browser tab
+                // from a previous run replaying an old callback on this same port.
+                // These must NOT abort the flow; only a callback carrying OUR exact
+                // state is allowed to proceed.
+                if (!code && !oauthError) {
+                    res.writeHead(204).end();
+                    return;
+                }
+                if (returnedState !== state) {
+                    res.writeHead(409, { 'Content-Type': 'text/html' }).end('<h2>Stale authorization tab — ignore this and use the newest link from your terminal.</h2>');
+                    spinner.text = 'Ignored a stale/mismatched callback (likely an old browser tab). Still waiting …';
+                    return;
+                }
+                if (oauthError)
+                    return fail(`Authorization denied: ${oauthError}.`, '<h2>Authorization denied.</h2>');
                 if (!code)
-                    return fail(`Authorization denied: ${url.searchParams.get('error') ?? 'no code returned'}.`, '<h2>No authorization code returned.</h2>');
+                    return fail('No authorization code returned.', '<h2>No authorization code returned.</h2>');
                 try {
                     const tokenRes = await fetch(`https://${store}/admin/oauth/access_token`, {
                         // Shopify's token endpoint requires these exact snake_case keys.
@@ -141,9 +182,18 @@ export default class Token extends Command {
                     fail(`Error during token exchange: ${error.message}`, '<h2>Error. Check the terminal.</h2>');
                 }
             });
+            // Don't wait forever; clear on close so any exit path stops the timer.
+            const timer = setTimeout(() => {
+                spinner.fail('Timed out after 5 minutes waiting for authorization.');
+                server.close();
+                reject(new Error('Timed out waiting for authorization.'));
+            }, 300_000);
+            timer.unref();
+            server.on('close', () => clearTimeout(timer));
             server.on('error', (error) => {
+                clearTimeout(timer);
                 const message = error.code === 'EADDRINUSE'
-                    ? `Port ${port} is already in use. Pass a different --port (and update the app redirect URL).`
+                    ? `Port ${port} is already in use — a previous run may still hold it. Kill it, or pass a different --port (and add that redirect URL to the app).`
                     : error.message;
                 reject(new Error(message));
             });

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;
+}