@hahahhh/sshx 0.0.6-rc.0 → 0.0.6-rc.3

package/README.md

@@ -5,7 +5,7 @@
 **sshx** is a drop-in wrapper around OpenSSH. Wrap it as `alias ssh=sshx` and your existing SSH workflow works exactly as before — every flag, config, and connection passes through verbatim. But when you connect to a host (or Docker container) with sshx-aware features enabled, you unlock a connection-scoped shared remote server that gives you:
 
 - 🔄 **Reverse command bridge** — run `sshx local <cmd>` *on the remote* to execute commands on your local machine, with stdout, stderr, exit code, and stdin all propagated.
-- 📁 **Remote-to-local filesystem** — opt in to let local tools work directly with files from the active remote session.
+- 📁 **Bidirectional workspace mount** — direct CLI sessions can use remote tools on local files, and local tools on remote files.
 - 🔌 **Automatic port forwarding** — remote local listeners (loopback `127.0.0.1` and wildcard `0.0.0.0`; e.g., a dev server on `0.0.0.0:8080` or `localhost:8080`) are automatically detected and forwarded to your local machine.
 - 🌐 **Local domain binding** — access forwarded ports as `<host>.<your-user>.sshx:<port>` in your local browser, no manual `-L` flags needed.
 - 🐳 **Docker container support** — target running containers by name or ID: `sshx my-container`. Command bridge support works inside containers via `docker exec`.
@@ -26,7 +26,7 @@ sshx is designed to be **safe to alias**. Hosts without sshx configuration are u
 
 ## Architecture
 
-![sshx system architecture](docs/architecture.svg)
+![sshx system architecture](docs/assets/architecture.svg)
 
 Each user-visible session remains a normal OpenSSH connection (or a `docker exec` session for container targets). One hidden multiplexed sidecar channel carries control and optional RemoteFS traffic to a shared target-side server, while one on-demand local daemon owns DNS records and TCP forwards across active client terminals. Automatic port forwarding uses SSH `direct-tcpip`; Docker targets support shells and the command bridge but do not use automatic port scanning.
 
@@ -68,17 +68,19 @@ sshx local --timeout=30 npm test
 - Commands have no implicit deadline. Put `--timeout=<duration>` immediately after the target to opt in; bare numbers mean seconds, and values such as `500ms`, `30s`, and `2m` are accepted. Timed-out commands exit with status 124.
 - Policy: a configurable deny list controls which commands are blocked.
 
-### 📁 Remote-to-Local Filesystem (opt-in, beta)
+### 📁 Bidirectional Workspace Mount (opt-in, beta)
 
-Set `features.remoteFs: true` to let a command launched with `sshx local <cmd>` access the remote working tree through a local FUSE mount:
+Set `features.remoteFs: true` to expose the command initiator's workspace through a read-write FUSE mount:
 
+- A direct `sshx remote <cmd>` exports the local home (or the current directory when outside the home), mounts it on the remote Linux target, and starts the remote command in the mapped local working directory.
+- A direct interactive `sshx remote` shell still starts in the remote home; `SSHX_MOUNT_ROOT` and `SSHX_WORKSPACE` point to the mounted local source tree.
 - The remote home is exported lazily on the first local command. A working directory outside the remote home creates a separate lazy export for that root.
 - The local command starts at the corresponding mounted working directory. Absolute command arguments are not rewritten.
 - Mounts are reused for the sidecar session, so detached tools such as `open` and `code` can continue reading files after the bridge request returns.
-- Local files are never exported or mounted on the remote host.
+- VS Code/Cursor Remote-SSH integration sidecars stay remote-to-local only: those application sessions do not export a local workspace to the remote host.
 - With RemoteFS disabled, the command runs from the local home and receives `SSHX_REMOTE_CWD` plus `SSHX_REMOTE_FS=0`.
 
-The mounted remote tree permits reads, writes, and creation, but blocks file/directory deletion and rename. It can include sensitive remote files such as shell configuration and SSH credentials, so enable `remoteFs` only for targets you trust.
+Mounted trees permit reads, writes, and creation, but block file/directory deletion and rename in both directions. They can include sensitive files such as shell configuration and SSH credentials, so enable `remoteFs` only for targets you trust.
 
 Set `FS_READ_ONLY=1` on the client when starting sshx to make the session mounts read-only:
 
@@ -88,13 +90,13 @@ FS_READ_ONLY=1 sshx debian@orb pwd
 
 The value is exported into the remote session, and later `sshx local <cmd>` mounts remain read-only.
 
-FUSE is required only on the local machine receiving the mounted remote tree. A mount failure fails that `sshx local` invocation instead of running it from the wrong directory. Linux needs `/dev/fuse` plus `fusermount`/`fusermount3`; macOS needs a current macFUSE installation and is currently beta.
+FUSE is required on the machine receiving a mounted tree. Direct `sshx remote` sessions therefore require FUSE on the remote Linux target; `sshx local` with RemoteFS requires FUSE on the local client. A mount failure fails the invocation instead of running it from the wrong directory.
 
 #### FUSE setup
 
-The local machine receiving the mounted view needs a working FUSE runtime. The remote Linux host exports files through the sshx protocol and does not need FUSE.
+Each machine that receives a mounted view needs a working FUSE runtime. The remote Linux target needs FUSE for direct local-to-remote workspace mounts; a macOS client needs macFUSE for remote-to-local mounts.
 
-**Linux client**
+**Linux client/target**
 
 Install the FUSE 3 userspace tools (the kernel normally already includes the FUSE driver):
 
@@ -161,7 +163,7 @@ The URL port is the remote port. sshx does not bind `127.0.0.1:<port>`; it binds
 
 ### 🏗️ Shared Server Architecture
 
-- Compatible runtime daemons live under `~/.sshx_server/targets/<TargetID>/runtimes/<RuntimeID>` and serve multiple application contexts and sessions.
+- Compatible runtime daemons live under `~/.sshx_server/runtimes/<RuntimeHomeID>` and serve multiple application contexts and sessions. `RuntimeHomeID` is a stable digest of `TargetID` and `RuntimeID`, keeping Unix socket paths safely below platform limits.
 - Client connects through one hidden multiplexed sidecar SSH channel.
 - Server manages port sniffing, forwarding state, and command bridge routing centrally.
 - Clients renew local and remote leases every 5 seconds. A daemon expires a client after 15 seconds without a heartbeat.
@@ -199,9 +201,9 @@ sshx integrate install vscode
 sshx integrate install cursor
 ```
 
-The command locates OpenSSH, installs paired `ssh`/`scp` shims backed by the same sshx binary, patches JSONC `remote.SSH.path`, and verifies the complete invocation chain. It is idempotent and rolls back settings and shims on failure; run it again to repair the integration after moving the sshx executable. No restart, integration-specific configuration, or extra binary is required.
+The command locates OpenSSH, installs paired `ssh`/`scp` shims backed by the same sshx binary, patches JSONC `remote.SSH.path`, and verifies the complete invocation chain. It is idempotent and rolls back settings and shims on failure; run it again to repair the integration after moving the sshx executable. npm-managed integrations record a management marker and are refreshed automatically by later `npm install` or `npm update` operations, so the install command does not need to be rerun manually. No restart, integration-specific configuration, or extra binary is required.
 
-Remote-SSH remains the user-visible OpenSSH connection. sshx creates a temporary ControlMaster so bootstrap, sidecar, forwarding, and scp reuse the same authentication. Only a stable `SSHX_CONTEXT_ID` and context-launcher path are injected into application terminals. Probe, unknown, and ambiguous calls are exact passthrough; an incompatible or failed sidecar receives the original bootstrap bytes and preserves normal OpenSSH behavior regardless of `strict`.
+Remote-SSH remains the user-visible OpenSSH connection. Every real SSH session through an integration shim receives the same application context wrapper, while information probes remain exact passthrough. The wrapper exports a stable `SSHX_CONTEXT_ID` and context-launcher path before executing the original remote command; stdin is never inspected or buffered. Each live session owns a sidecar, and temporary ControlMaster sockets let concurrent SSH and scp calls reuse authentication without a resident integration daemon.
 
 ### Download Binary
 
@@ -314,8 +316,9 @@ features:
   # <host>.<user>.sshx:<remote-port>.
   autoForward: true
 
-  # Lazily mount remote files for local commands. Default: false.
-  # Requires FUSE only on the local machine.
+  # Bidirectional workspace mounts for direct CLI sessions. Default: false.
+  # VS Code/Cursor integrations remain remote-to-local only.
+  # Requires FUSE on each machine receiving a mount.
   remoteFs: false
 
 commands:
@@ -341,7 +344,7 @@ commands:
 └─────────────────────────────────┘     └─────────────────────────────────┘
 ```
 
-1. **Connection**: `sshx remote` opens a normal SSH session and starts a compatible runtime under `~/.sshx_server/targets/<TargetID>/runtimes/<RuntimeID>`.
+1. **Connection**: `sshx remote` opens a normal SSH session and starts a compatible runtime under `~/.sshx_server/runtimes/<RuntimeHomeID>`.
 2. **Sidecar channel**: One hidden SSH channel multiplexes command, port, heartbeat, and optional RemoteFS traffic. ContextID routes VS Code/Cursor terminals to a healthy live session.
 3. **Port sniffing**: The server reads `/proc/net/tcp*` (Linux) to detect loopback (`127.0.0.1` / `::1`) and wildcard (`0.0.0.0` / `::`) listeners.
 4. **Forwarding**: Detected ports are forwarded through a single shared local daemon using `ssh -W`.
@@ -406,7 +409,7 @@ sshx/
 
 - [x] **v1** — Command bridge (non-interactive), auto port forwarding, domain binding, shared server
 - [ ] **v2** — Streaming stdin for command bridge, GitHub binary releases, Windows client support
-- [x] **remoteFs beta** — Lazy remote-to-local workspace mounting on Linux/macOS clients
+- [x] **remoteFs beta** — Bidirectional direct-CLI workspace mounting, with remote-to-local-only application integrations
 
 ---
 

package/bin/sshx.js

@@ -10,9 +10,13 @@ import {
   writeFileSync,
 } from "node:fs";
 import { homedir, tmpdir } from "node:os";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
+const npmRefreshArgument = "--npm-refresh-integrations";
+const npmManagedMarker = ".npm-managed";
+const integrationProfiles = ["vscode", "cursor"];
+
 const platformByNode = new Map([
   ["darwin", "darwin"],
   ["linux", "linux"],
@@ -42,14 +46,33 @@ const cacheRoot =
     ? join(process.env.LOCALAPPDATA || tmpdir(), "sshx")
     : join(homedir(), ".cache", "sshx"));
 const binaryPath = join(cacheRoot, version, binaryName);
+const refreshOnly =
+  process.argv.length === 3 && process.argv[2] === npmRefreshArgument;
+const integrationsToRefresh = findNpmIntegrationsToRefresh();
+
+// Preserve lazy binary downloads on a first install that has no integrations yet.
+if (refreshOnly && integrationsToRefresh.length === 0) {
+  process.exit(0);
+}
 
 if (!existsSync(binaryPath)) {
   await downloadBinary(binaryPath);
 }
 
+const nativeEnvironment = {
+  ...process.env,
+  SSHX_NPM_LAUNCHER: "1",
+};
+
+refreshNpmIntegrations(integrationsToRefresh);
+
+if (refreshOnly) {
+  process.exit(0);
+}
+
 const result = spawnSync(binaryPath, process.argv.slice(2), {
   stdio: "inherit",
-  env: process.env,
+  env: nativeEnvironment,
 });
 
 if (result.error) {
@@ -59,6 +82,87 @@ if (result.error) {
 
 process.exit(result.status ?? 0);
 
+function findNpmIntegrationsToRefresh() {
+  const integrationRoot =
+    process.env.SSHX_INTEGRATIONS_DIR ||
+    join(homedir(), ".sshx", "integrations");
+
+  const profiles = [];
+
+  for (const profile of integrationProfiles) {
+    const profileRoot = join(integrationRoot, profile);
+    const markerPath = join(profileRoot, npmManagedMarker);
+    const descriptor = readIntegrationDescriptor(profileRoot);
+    const isMarked = existsSync(markerPath);
+    const isLegacyNpmIntegration =
+      descriptor !== null && pathIsInside(descriptor.driverPath, cacheRoot);
+
+    if (!isMarked && !isLegacyNpmIntegration) {
+      continue;
+    }
+    if (
+      isMarked &&
+      descriptor !== null &&
+      samePath(descriptor.driverPath, binaryPath)
+    ) {
+      continue;
+    }
+
+    profiles.push(profile);
+  }
+
+  return profiles;
+}
+
+function refreshNpmIntegrations(profiles) {
+  for (const profile of profiles) {
+    const refresh = spawnSync(binaryPath, ["integrate", "install", profile], {
+      encoding: "utf8",
+      env: nativeEnvironment,
+    });
+    if (refresh.status === 0 && !refresh.error) {
+      console.error(`sshx: refreshed ${profile} integration for npm ${version}`);
+      continue;
+    }
+
+    const detail =
+      refresh.error?.message ||
+      refresh.stderr?.trim() ||
+      `native installer exited with status ${refresh.status ?? "unknown"}`;
+    console.error(
+      `sshx: warning: could not refresh ${profile} integration: ${detail}`,
+    );
+  }
+}
+
+function readIntegrationDescriptor(profileRoot) {
+  try {
+    const value = JSON.parse(
+      readFileSync(join(profileRoot, "integration.json"), "utf8"),
+    );
+    if (typeof value.driverPath === "string" && value.driverPath.length > 0) {
+      return value;
+    }
+  } catch {
+    // A marker without a readable descriptor is repaired by the native installer.
+  }
+  return null;
+}
+
+function samePath(left, right) {
+  return resolve(left) === resolve(right);
+}
+
+function pathIsInside(candidate, rootPath) {
+  const child = relative(resolve(rootPath), resolve(candidate));
+  return (
+    child !== "" &&
+    child !== ".." &&
+    !child.startsWith(`..${sep}`) &&
+    !isAbsolute(child)
+  );
+}
+
 async function downloadBinary(destination) {
   const baseUrl =
     process.env.SSHX_RELEASE_BASE_URL ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hahahhh/sshx",
-  "version": "0.0.6-rc.0",
+  "version": "0.0.6-rc.3",
   "type": "module",
   "description": "Transparent SSH enhancement wrapper for OpenSSH",
   "repository": {
@@ -23,7 +23,8 @@
     "build": "node scripts/build-native.js",
     "build:go": "go build -trimpath -ldflags \"-X github.com/xiaot623/sshx/internal/version.Version=${npm_package_version}\" -o sshx ./cmd/sshx",
     "check": "go vet ./...",
-    "test": "go test ./...",
+    "test": "go test ./... && node --test test/*.test.js",
+    "postinstall": "node ./bin/sshx.js --npm-refresh-integrations",
     "pre_release": "npm version prerelease --preid=rc -m \"chore: pre-release v%s\" && git push origin HEAD --follow-tags",
     "publish:rc": "npm publish --access public --tag next",
     "publish:release": "npm publish --access public --tag latest",