@firenet-designs/fnd-cli 2.0.0 → 2.2.0

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/scaffold.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared scaffolding pieces for `create-project` and `backfill-project`.
+ *
+ * SECURITY: nothing in this module (or the commands that use it) may ever
+ * contain, read into a string, or print a credential. GitHub auth comes from
+ * the user's own environment (GH_TOKEN / GITHUB_TOKEN exported in their shell,
+ * or `gh auth login`) — we only check that SOME auth exists, never the value.
+ */
+export declare const GITIGNORE_CONTENT = ".idea/\nnode_modules/\nconfig.yml\n";
+export declare const SHOPIFYIGNORE_CONTENT = "src/\nscripts/\nsrc\nscripts\nconfig.yml\n";
+/**
+ * Prompt that drives CLAUDE.md generation. Ships with this package in
+ * prompts/ (resolved relative to this module: dist/lib -> <pkg root>/prompts).
+ * Set FND_INIT_PROMPT_PATH to test a local prompt without republishing.
+ */
+export declare const initPromptPath: () => string;
+/**
+ * Runs a command with stdio inherited so the user sees live output and can
+ * answer interactive prompts (shopify auth, claude, gh, git/ssh).
+ */
+export declare const run: (command: string, args: string[], env?: NodeJS.ProcessEnv) => Promise<number>;
+/** Resolves a binary on PATH, or null if not found. */
+export declare const which: (bin: string) => null | string;
+/**
+ * Finds the shopify CLI: PATH first, then nvm node versions (newest wins) —
+ * shopify is often installed per nvm node version that isn't currently active.
+ */
+export declare const findShopifyBin: () => null | string;
+/**
+ * Builds the CLAUDE.md generation prompt and runs `claude -p` with it.
+ * Returns 'claude-not-installed' when the claude CLI isn't on PATH,
+ * 'missing-prompt' when the bundled prompt file is gone (broken install),
+ * otherwise 'written'/'not-written' depending on whether CLAUDE.md appeared.
+ */
+export declare const generateClaudeMd: (shop: string | undefined, extraHints: string) => Promise<"claude-not-installed" | "missing-prompt" | "not-written" | "written">;

package/dist/lib/scaffold.js

@@ -0,0 +1,101 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Shared scaffolding pieces for `create-project` and `backfill-project`.
+ *
+ * SECURITY: nothing in this module (or the commands that use it) may ever
+ * contain, read into a string, or print a credential. GitHub auth comes from
+ * the user's own environment (GH_TOKEN / GITHUB_TOKEN exported in their shell,
+ * or `gh auth login`) — we only check that SOME auth exists, never the value.
+ */
+export const GITIGNORE_CONTENT = `.idea/
+node_modules/
+config.yml
+`;
+export const SHOPIFYIGNORE_CONTENT = `src/
+scripts/
+src
+scripts
+config.yml
+`;
+/**
+ * Prompt that drives CLAUDE.md generation. Ships with this package in
+ * prompts/ (resolved relative to this module: dist/lib -> <pkg root>/prompts).
+ * Set FND_INIT_PROMPT_PATH to test a local prompt without republishing.
+ */
+export const initPromptPath = () => {
+    const override = process.env.FND_INIT_PROMPT_PATH;
+    if (override && existsSync(override))
+        return override;
+    return fileURLToPath(new URL('../../prompts/init-project-auto.md', import.meta.url));
+};
+/**
+ * Runs a command with stdio inherited so the user sees live output and can
+ * answer interactive prompts (shopify auth, claude, gh, git/ssh).
+ */
+export const run = (command, args, env) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, { env: env ?? process.env, stdio: 'inherit' });
+    child.on('error', reject);
+    child.on('close', (code) => resolve(code ?? 1));
+});
+/** Resolves a binary on PATH, or null if not found. */
+export const which = (bin) => {
+    const result = spawnSync('which', [bin], { encoding: 'utf8' });
+    return result.status === 0 ? result.stdout.trim() : null;
+};
+const parseNodeVersion = (v) => v.replace(/^v/, '').split('.').map(Number);
+/** `sort -V` equivalent for nvm dir names like `v24.13.1`. */
+const compareNodeVersions = (a, b) => {
+    const [aParts, bParts] = [parseNodeVersion(a), parseNodeVersion(b)];
+    for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
+        const diff = (aParts[i] ?? 0) - (bParts[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+};
+/**
+ * Finds the shopify CLI: PATH first, then nvm node versions (newest wins) —
+ * shopify is often installed per nvm node version that isn't currently active.
+ */
+export const findShopifyBin = () => {
+    const onPath = which('shopify');
+    if (onPath)
+        return onPath;
+    const nodeVersionsDir = join(homedir(), '.nvm', 'versions', 'node');
+    if (!existsSync(nodeVersionsDir))
+        return null;
+    const versions = readdirSync(nodeVersionsDir)
+        .filter((v) => existsSync(join(nodeVersionsDir, v, 'bin', 'shopify')))
+        .sort(compareNodeVersions);
+    const newest = versions.at(-1);
+    return newest ? join(nodeVersionsDir, newest, 'bin', 'shopify') : null;
+};
+/**
+ * Builds the CLAUDE.md generation prompt and runs `claude -p` with it.
+ * Returns 'claude-not-installed' when the claude CLI isn't on PATH,
+ * 'missing-prompt' when the bundled prompt file is gone (broken install),
+ * otherwise 'written'/'not-written' depending on whether CLAUDE.md appeared.
+ */
+export const generateClaudeMd = async (shop, extraHints) => {
+    if (!which('claude'))
+        return 'claude-not-installed';
+    const promptPath = initPromptPath();
+    if (!existsSync(promptPath))
+        return 'missing-prompt';
+    let prompt = readFileSync(promptPath, 'utf8');
+    let hints = extraHints;
+    if (shop)
+        hints = `Shopify store: ${shop}. ${hints}`;
+    if (hints.trim())
+        prompt += `\n\n## User hints (override inference)\n${hints}`;
+    await run('claude', [
+        '-p', prompt,
+        '--permission-mode', 'acceptEdits',
+        '--allowedTools', 'Read Glob Grep Bash Write Edit',
+    ]);
+    return existsSync(join(process.cwd(), 'CLAUDE.md')) ? 'written' : 'not-written';
+};

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