@firenet-designs/fnd-cli 2.3.2 → 2.4.0

package/dist/lib/workspace.js

@@ -1,7 +1,8 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { randomInt } from 'node:crypto';
+import { readdirSync, readFileSync } from 'node:fs';
 import { userInfo } from 'node:os';
-import { basename } from 'node:path';
+import { basename, join } from 'node:path';
 export const DEFAULT_MOUNT_BASE = '/home/fnd';
 /** Parse a `user@host` string, throwing a friendly error otherwise. */
 export const parseSshTarget = (raw) => {
@@ -23,15 +24,15 @@ export const slugify = (value) => value
 /** A unique Mutagen session name for a workspace on the given local directory. */
 export const buildSyncName = (dirName) => `fnd-ws-${slugify(dirName)}-${randomInt(0, 1_000_000).toString(36)}`;
 /**
- * Parse the --devtools value. Accepts `port` (same port on both ends) or
- * `remote:local`, where `local` is the caller's machine (where the browser runs)
- * and `remote` is the port opened on the workspace host.
+ * Parse a reverse-tunnel port value. Accepts `port` (same port on both ends) or
+ * `remote:local`, where `local` is the caller's machine and `remote` is the
+ * port opened on the workspace host. `flag` names the flag in error messages.
  */
-export const parseDevtoolsPort = (raw) => {
+export const parsePortPair = (raw, flag) => {
     const toPort = (value) => {
         const n = Number(value);
         if (!Number.isInteger(n) || n < 1 || n > 65_535) {
-            throw new Error(`--devtools port must be an integer 1-65535 (got "${value}")`);
+            throw new Error(`${flag} port must be an integer 1-65535 (got "${value}")`);
         }
         return n;
     };
@@ -43,7 +44,7 @@ export const parseDevtoolsPort = (raw) => {
     if (parts.length === 2) {
         return { local: toPort(parts[1]), remote: toPort(parts[0]) };
     }
-    throw new Error(`--devtools must be "port" or "remote:local" (got "${raw}")`);
+    throw new Error(`${flag} port must be "port" or "remote:local" (got "${raw}")`);
 };
 /** Build the immutable facts for a workspace session from the local environment + flags. */
 export const buildContext = (opts) => {
@@ -54,18 +55,108 @@ export const buildContext = (opts) => {
     const remoteDir = `${base}/${localUser}/${localDirName}`;
     return {
         devtools: opts.devtools,
+        ignores: opts.ignoreVcs ? collectVcsIgnores(localCwd) : undefined,
         localCwd,
         localDirName,
         localUser,
         remoteDir,
+        rpc: opts.rpc,
         source: opts.source,
         syncName: buildSyncName(localDirName),
     };
 };
+/**
+ * Translate one .gitignore line into Mutagen ignore patterns. `base` is the
+ * directory holding the .gitignore, as a posix path relative to the sync root
+ * ('' for the root file). Mutagen's syntax already matches gitignore's for the
+ * pieces that pass through untouched (`*`, `**`, `?`, `[...]`, `!` negation,
+ * trailing `/` for directory-only) — what needs translating is scope:
+ *
+ * - A pattern with a slash is anchored to the .gitignore's own directory, so it
+ *   becomes an absolute pattern under `base` (`/dist` in src/.gitignore →
+ *   `/src/dist`).
+ * - A slashless pattern matches at any depth AT OR BELOW `base`. At the root
+ *   that is exactly Mutagen's unanchored behavior, so it passes through as-is;
+ *   under a subdirectory it becomes `/base/p` plus `/base/**\/p` (both forms, so
+ *   the match doesn't depend on `**` matching zero segments).
+ *
+ * Returns [] for blanks and comments.
+ */
+export const translateGitignoreLine = (line, base) => {
+    // Trailing whitespace is meaningless unless backslash-escaped.
+    let p = line.replace(/(?<![\\])[ \t]+$/, '');
+    if (p === '' || p.startsWith('#'))
+        return [];
+    let negated = false;
+    if (p.startsWith('!')) {
+        negated = true;
+        p = p.slice(1);
+    }
+    else if (p.startsWith(String.raw `\!`) || p.startsWith(String.raw `\#`)) {
+        p = p.slice(1);
+    }
+    let dirOnly = false;
+    if (p.endsWith('/')) {
+        dirOnly = true;
+        p = p.replace(/\/+$/, '');
+    }
+    const anchored = p.includes('/');
+    p = p.replace(/^\/+/, '');
+    if (p === '')
+        return [];
+    const withBase = (rel) => `/${[base, rel].filter(Boolean).join('/')}`;
+    const targets = anchored ? [withBase(p)] : base === '' ? [p] : [withBase(p), withBase(`**/${p}`)];
+    return targets.map((t) => `${negated ? '!' : ''}${t}${dirOnly ? '/' : ''}`);
+};
+/**
+ * Walk the project and turn every .gitignore into Mutagen ignore patterns, each
+ * resolved relative to the directory of the .gitignore that declared it. Files
+ * are ordered root-first so deeper .gitignore patterns come later — Mutagen
+ * gives later patterns precedence, which mirrors git. `.git` and `node_modules`
+ * are never descended into (git does not consult .gitignore files inside
+ * ignored or metadata directories), and symlinked directories are skipped to
+ * avoid cycles.
+ */
+export const collectVcsIgnores = (rootDir) => {
+    const found = [];
+    const walk = (dir, base) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return; // unreadable dir — nothing to collect there
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (entry.name === '.git' || entry.name === 'node_modules')
+                    continue;
+                walk(join(dir, entry.name), base === '' ? entry.name : `${base}/${entry.name}`);
+            }
+            else if (entry.name === '.gitignore') {
+                found.push({ base });
+            }
+        }
+    };
+    walk(rootDir, '');
+    found.sort((a, b) => a.base.split('/').filter(Boolean).length - b.base.split('/').filter(Boolean).length);
+    return found.flatMap(({ base }) => {
+        let content;
+        try {
+            content = readFileSync(join(rootDir, ...base.split('/').filter(Boolean), '.gitignore'), 'utf8');
+        }
+        catch {
+            return [];
+        }
+        return content.split('\n').flatMap((line) => translateGitignoreLine(line, base));
+    });
+};
 /** POSIX single-quote a string so it can be embedded safely in the remote shell script. */
 export const shQuote = (value) => `'${value.replaceAll("'", `'\\''`)}'`;
 /** MCP server name registered for the workspace's chrome-devtools tunnel. */
 const DEVTOOLS_MCP_NAME = 'chrome-devtools';
+/** MCP server name registered for the --rpc local-command tunnel. */
+const RPC_MCP_NAME = 'local-shell';
 /**
  * Bash lines (run on the REMOTE, from inside the workspace dir) that register the
  * chrome-devtools MCP with the `claude` CLI. Local scope keys off the current
@@ -91,14 +182,37 @@ const claudeDevtoolsAddScript = (remotePort, okMessage) => {
     return [`"\${SHELL:-bash}" -lc ${shQuote(body)}`];
 };
 /**
- * Bash lines (run on the REMOTE, from inside the workspace dir) that remove the
- * chrome-devtools MCP this workspace registered. Local scope keys off the current
+ * Bash lines (run on the REMOTE, from inside the workspace dir) that register the
+ * --rpc local-shell MCP with the `claude` CLI as a Streamable HTTP server. The
+ * URL points at the reverse-tunnelled port, which the workspace's `ssh -R`
+ * forwards back to the RPC server on the calling machine. Same login-shell and
+ * idempotency reasoning as `claudeDevtoolsAddScript`.
+ */
+const claudeRpcAddScript = (remotePort, okMessage) => {
+    const body = [
+        'if command -v claude >/dev/null 2>&1; then',
+        `  claude mcp remove ${RPC_MCP_NAME} >/dev/null 2>&1 || true`,
+        `  claude mcp add --transport http ${RPC_MCP_NAME} http://127.0.0.1:${remotePort}/mcp`,
+        `  echo ${shQuote(okMessage)}`,
+        'else',
+        '  echo "WARNING: claude CLI not found on the remote; skipped local-shell MCP config." >&2',
+        'fi',
+    ].join('\n');
+    return [`"\${SHELL:-bash}" -lc ${shQuote(body)}`];
+};
+/**
+ * Bash lines (run on the REMOTE, from inside the workspace dir) that remove an
+ * MCP entry this workspace registered. Local scope keys off the current
  * directory, so it targets only the workspace project. No-op if the entry or the
  * claude CLI is absent. Runs under a login shell for the same PATH reason as
  * `claudeDevtoolsAddScript`.
  */
-const claudeDevtoolsRemoveScript = () => {
-    const body = ['if command -v claude >/dev/null 2>&1; then', `  claude mcp remove ${DEVTOOLS_MCP_NAME}`, 'fi'].join('\n');
+const claudeMcpRemoveScript = (name) => {
+    const body = [
+        'if command -v claude >/dev/null 2>&1; then',
+        `  claude mcp remove ${name}`,
+        'fi'
+    ].join('\n');
     return [`"\${SHELL:-bash}" -lc ${shQuote(body)}`];
 };
 /**
@@ -111,35 +225,51 @@ export const buildRemoteScript = (ctx) => {
     const devtoolsSetup = ctx.devtools
         ? claudeDevtoolsAddScript(ctx.devtools.remote, `Configured chrome-devtools MCP for this workspace (browser via 127.0.0.1:${ctx.devtools.remote}).`)
         : [];
+    const rpcSetup = ctx.rpc
+        ? claudeRpcAddScript(ctx.rpc.ports.remote, `Configured local-shell MCP for this workspace (runs ${ctx.rpc.shell} commands on the calling machine via 127.0.0.1:${ctx.rpc.ports.remote}).`)
+        : [];
     return [
         'set -u',
         `DIR=${dir}`,
         // Mutagen creates the sync root, but ensure it exists so `cd` never races it.
         'mkdir -p "$DIR" || { echo "ERROR: could not create $DIR" >&2; exit 1; }',
         'cd "$DIR" || { echo "ERROR: could not enter $DIR" >&2; exit 1; }',
-        // Register the MCP from inside $DIR: `claude mcp add` local scope keys off cwd.
+        // Register the MCPs from inside $DIR: `claude mcp add` local scope keys off cwd.
         ...devtoolsSetup,
+        ...rpcSetup,
         'echo "Workspace ready at $DIR — files sync in the background (exit to stop syncing)."',
         // eslint-disable-next-line no-template-curly-in-string -- shell parameter expansion, not a JS template
         '"${SHELL:-bash}" -l',
     ].join('\n');
 };
-/** Run the remote-side teardown (strip this project's chrome-devtools MCP) over a fresh ssh connection. */
-export const runRemoteCleanup = (target, remoteDir) => new Promise((resolve, reject) => {
-    const child = spawn('ssh', [target, buildCleanupScript(remoteDir)], { stdio: 'inherit' });
+/** Run the remote-side teardown over a fresh ssh connection. */
+export const runRemoteCleanup = (target, remoteDir, opts = {}) => new Promise((resolve, reject) => {
+    const child = spawn('ssh', [target, buildCleanupScript(remoteDir, opts)], { stdio: 'inherit' });
     child.once('error', reject);
     child.once('close', (code) => resolve(code ?? 0));
 });
 /**
- * The remote-side teardown script: strip this project's chrome-devtools MCP via
- * the `claude` CLI. Runs from inside the workspace dir so local scope resolves to
- * the right project. A no-op if there is nothing to undo. The synced files
- * themselves are left in place — they are a real copy, not a mount.
+ * The remote-side teardown script. Runs from inside the workspace dir so the
+ * `claude` CLI's local scope resolves to the right project. The chrome-devtools
+ * and local-shell MCP entries are stripped only when their flags are set — i.e.
+ * when the workspace registered them via --devtools / --rpc; without them we
+ * never touch the user's MCP config. The synced files themselves are left in
+ * place — they are a real copy, not a mount — unless `deleteRemoteDir` is set,
+ * in which case the workspace dir is removed after any MCP config is stripped.
  */
-export const buildCleanupScript = (remoteDir) => [
+export const buildCleanupScript = (remoteDir, opts = {}) => [
     `DIR=${shQuote(remoteDir)}`,
     'cd "$DIR" 2>/dev/null || { echo "Nothing to clean up: $DIR is gone." >&2; exit 0; }',
-    ...claudeDevtoolsRemoveScript(),
+    ...(opts.removeDevtoolsMcp ? claudeMcpRemoveScript(DEVTOOLS_MCP_NAME) : []),
+    ...(opts.removeRpcMcp ? claudeMcpRemoveScript(RPC_MCP_NAME) : []),
+    // Remove the workspace dir last: cd out first so we don't rm the cwd out from
+    // under the shell, then delete it. Only when explicitly requested.
+    ...(opts.deleteRemoteDir
+        ? [
+            'cd / || exit 1',
+            'rm -rf "$DIR" && echo "Removed remote dir $DIR." || { echo "ERROR: could not remove $DIR" >&2; exit 1; }',
+        ]
+        : []),
 ].join('\n');
 /** True if an `ssh` client is on PATH (works on Windows, macOS, Linux). */
 export const hasSshClient = () => {
@@ -158,6 +288,8 @@ export const hasMutagen = () => {
  * the mode switches to two-way-resolved (alpha always wins conflicts), so
  * `--source remote` puts the server first and `--source local` puts this
  * machine first. Labels let `workspace cleanup` find and terminate orphans.
+ * `ctx.ignores` (from --ignore-vcs) excludes gitignored paths from the sync so
+ * each side keeps its own build artifacts and platform-specific binaries.
  */
 export const buildMutagenCreateArgs = (ctx, target) => {
     const local = ctx.localCwd;
@@ -173,6 +305,7 @@ export const buildMutagenCreateArgs = (ctx, target) => {
         '--label=managed-by=fnd-workspace',
         `--label=dir=${slugify(ctx.localDirName)}`,
         `--sync-mode=${syncMode}`,
+        ...(ctx.ignores ?? []).map((p) => `--ignore=${p}`),
         alpha,
         beta,
     ];

package/oclif.manifest.json

@@ -186,12 +186,27 @@
     "workspace:cleanup": {
       "aliases": [],
       "args": {},
-      "description": "Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.\n\nTerminates any Mutagen sync sessions this machine started for the directory and strips the matching chrome-devtools MCP entry from the remote. With no --remote-dir, it targets the same path `workspace` would use for the current directory. The synced files themselves are left in place.",
+      "description": "Tear down a leftover workspace — use this if a `workspace` session dropped before it could clean up after itself.\n\nTerminates any Mutagen sync sessions this machine started for the directory. Pass --devtools or --rpc to also strip the matching MCP entries from the remote (only do this if the dropped session used those flags). With no --remote-dir, it targets the same path `workspace` would use for the current directory. The synced files themselves are left in place unless you pass --delete-remote-dir.",
       "examples": [
         "<%= config.bin %> <%= command.id %> --ssh user@host",
-        "<%= config.bin %> <%= command.id %> --ssh user@host --remote-dir /home/fnd/cole/fnd-cli"
+        "<%= config.bin %> <%= command.id %> --ssh user@host --remote-dir /home/fnd/cole/fnd-cli",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --devtools",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --rpc",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --delete-remote-dir"
       ],
       "flags": {
+        "delete-remote-dir": {
+          "description": "also delete the remote workspace directory (by default the synced files are left in place)",
+          "name": "delete-remote-dir",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "devtools": {
+          "description": "also strip the chrome-devtools MCP entry from the remote (only if the dropped session used --devtools)",
+          "name": "devtools",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "remote-base": {
           "description": "base dir on the remote, used to derive the default remote directory path",
           "name": "remote-base",
@@ -207,6 +222,12 @@
           "multiple": false,
           "type": "option"
         },
+        "rpc": {
+          "description": "also strip the local-shell MCP entry from the remote (only if the dropped session used --rpc)",
+          "name": "rpc",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "ssh": {
           "description": "remote to connect to, as user@host",
           "name": "ssh",
@@ -240,10 +261,20 @@
         "<%= config.bin %> <%= command.id %> --ssh user@203.0.113.4",
         "<%= config.bin %> <%= command.id %> --ssh user@host --source local",
         "<%= config.bin %> <%= command.id %> --ssh user@host --remote-base /home/fnd",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --ignore-vcs",
         "<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9222",
-        "<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9333:9222"
+        "<%= config.bin %> <%= command.id %> --ssh user@host --devtools 9333:9222",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --rpc port=7777:7700",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --rpc port=7777:7700,profile=false,shell=zsh",
+        "<%= config.bin %> <%= command.id %> --ssh user@host --delete-remote-dir"
       ],
       "flags": {
+        "delete-remote-dir": {
+          "description": "on exit, delete the remote workspace directory instead of leaving the synced copy in place",
+          "name": "delete-remote-dir",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "devtools": {
           "description": "expose your LOCAL browser to Claude on the remote via the chrome-devtools MCP. Value is \"port\" (same port both ends) or \"remote:local\" (local = this machine, where the browser runs). Your browser must already be listening with --remote-debugging-port=<local>.",
           "name": "devtools",
@@ -251,6 +282,12 @@
           "multiple": false,
           "type": "option"
         },
+        "ignore-vcs": {
+          "description": "don't sync paths matched by the project's .gitignore files (node_modules, build output, …) so each side keeps its own platform-specific artifacts. Every .gitignore in the tree is honoured relative to its directory, like git does. The .git directory itself still syncs, so the remote stays a working repo.",
+          "name": "ignore-vcs",
+          "allowNo": false,
+          "type": "boolean"
+        },
         "remote-base": {
           "description": "base dir on the remote; the workspace lands at <base>/<local-user>/<dir-name>",
           "name": "remote-base",
@@ -259,6 +296,13 @@
           "multiple": false,
           "type": "option"
         },
+        "rpc": {
+          "description": "expose a run_local_command MCP tool to Claude on the remote that executes commands back on THIS machine (the one running fnd workspace). Value is port=<port|remote:local>[,profile=<true|1|false|0>][,shell=<bash|batch|powershell|sh|zsh>] — port opens a reverse tunnel (ssh -R <remote>:localhost:<local>) to a command server started here; shell defaults to the shell fnd workspace was called from; profile (default true) controls whether the shell loads its startup files — with it on, POSIX shells run interactively (-i) so rc files like ~/.bashrc or ~/.zshrc are sourced and tools such as nvm work.",
+          "name": "rpc",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "source": {
           "description": "which side wins on conflict: \"remote\" = this server (where the workspace shell runs), \"local\" = the machine you ran fnd workspace from. Omit to flag conflicts instead of auto-resolving them.",
           "name": "source",
@@ -296,5 +340,5 @@
       ]
     }
   },
-  "version": "2.3.2"
+  "version": "2.4.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@firenet-designs/fnd-cli",
   "description": "A new CLI generated with oclif",
-  "version": "2.3.2",
+  "version": "2.4.0",
   "author": "Cole Denslow",
   "contributors": [
     "Justin Schellenberg"
@@ -16,7 +16,8 @@
     "@oclif/plugin-plugins": "^5",
     "chalk": "^5.6.2",
     "ora": "^9.3.0",
-    "simple-git": "^3.32.2"
+    "simple-git": "^3.32.2",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@eslint/compat": "^1",
@@ -91,7 +92,7 @@
     "postpack": "shx rm -f oclif.manifest.json",
     "posttest": "npm run lint",
     "prepack": "oclif manifest && oclif readme",
-    "version": "oclif readme && git add README.md",
+    "version": "oclif readme",
     "prerelease": "npm run build && npm run prepack",
     "release": "npm run build && npm run prepack && npm publish"
   },