🌐 Net Remote Panel (SSH / SFTP / SCP)

An official Nuclr Commander plugin that adds a Net file panel root for browsing and managing remote servers over SSH. Built on Apache MINA SSHD, it shares a single SSH session per server for both SFTP (filesystem operations) and SCP (transfers).

✨ What it does

⌨️ Keyboard shortcuts

Server-list view (Net root):

Remote-folder view:

🖥️ Server profile fields

📁 Server configuration file

Profiles are stored at ~/.nuclr/net/servers.json. Passwords and key passphrases are not part of this file at all — there is no blank placeholder field, the schema simply has nowhere to put a secret:

[
  {
    "id": "a1b2c3d4-...",
    "name": "Production Box",
    "host": "example.com",
    "port": 22,
    "username": "alice",
    "authMethod": "KEY",
    "privateKeyPath": "/home/alice/.ssh/id_ed25519",
    "initialPath": "/var/www"
  }
]

Host keys are recorded in the standard OpenSSH known_hosts format at ~/.nuclr/net/known_hosts.

📥 Installation

Copy the signed plugin archive and detached signature into the Nuclr Commander plugins/ directory:

filepanel-net-<version>.zip
filepanel-net-<version>.zip.sig

Nuclr Commander verifies the RSA-SHA256 signature against nuclr-cert.pem on load. The plugin becomes available immediately without a restart.

⚙️ How it works

• NetConnection (in ssh/) wraps one Apache MINA SSHD ClientSession per server: it authenticates (password or key, via KeyLoader), mounts the SFTP filesystem, and lazily creates SCP clients and exec channels on the same session. ensureOpen() transparently rebuilds a dropped session, so every panel operation reconnects on demand rather than failing outright.
• ConnectionRegistry is a process-wide, connection-per-server-id map, so both panels (and any number of plugin instances created while navigating) share one SSH session to a given server, plus the in-memory password/passphrase cache for that session.
• NetResource wraps entries from the mounted SFTP filesystem as ordinary NuclrResources backed by a real java.nio.file.Path. Because the path is genuinely on a java.nio.file.FileSystem, the host's existing copy engines, quick-view plugins, and viewers work against it with no special-casing — only F4 Edit needs plugin-specific handling (see NetEditService), since editors need a fast local scratch file with conflict detection rather than reading/writing over the network on every keystroke.
• NetTransferEngine copies files into a remote directory: local sources upload via SCP (fast, matches the task's "SCP for transfers" requirement); sources on another virtual filesystem (a different server, an archive mount, …) fall back to a generic stream copy, since SCP is a single-host protocol.
• NetFindService streams find -print0 output from an exec channel for glob searches, or walks the tree over SFTP (used for regex searches, and as the fallback when the remote find is missing or fails outright).
• NetEditService downloads the remote file via SCP, hands a mainpanel.edit event pointing at the local temp copy to the host (which shows the usual text/hex editor chooser), and polls the temp copy on a background thread. On a save it re-stats the remote file; if it changed since download/last-upload, the user is asked before overwriting. Otherwise it uploads to a hidden temp sibling (.name.nuclr-<token>.tmp) via SCP and renames it over the target with SFTP's overwriting rename (falling back to delete-then-rename if the server rejects that).
• NetTerminalSession implements the SDK's NuclrTerminalSession over a ChannelShell on the already-open NetConnection, so Ctrl+O costs neither a new TCP connection nor a second authentication. Closing it closes only the channel, leaving the shared session up for SFTP/SCP. The shell is made to publish its working directory in the terminal title (CWD_TITLE_PREFIX); the panel follows that title so the console and the listing stay on the same folder.
• NetDirectoryCache caches each folder's listing (per server id + remote path) so repeat navigation doesn't re-run SFTP readDir. It's invalidated automatically whenever this plugin performs a write against the cached folder (mkdir, create file, delete, rename, copy/move destination, or a completed F4 upload) and by the user's explicit Ctrl+R; changes made outside the plugin's knowledge (another SSH client, a cron job) are only picked up on that explicit refresh.
• SCP path safety — Apache MINA's ScpClient builds its scp -t/scp -f exec command by concatenating the remote path into the command string with no shell quoting, and the same string is also used verbatim as the literal filename recorded in the SCP protocol stream, so it can't simply be quoted after the fact either. A path with spaces, parentheses or other shell-significant characters breaks the remote invocation outright (surfacing as EOFException: readAck - EOF before ACK). ShellEscape.isSafeForUnquotedScp checks the target path before every SCP upload/download (copy-into-Net, F4 edit download/upload) and falls back to a plain SFTP read/write for anything that isn't plain ASCII-ish — slower, but always correct.

🗂️ Source layout

src/main/java/dev/nuclr/plugin/core/panel/net/
├── NetFilePanelPlugin.java     plugin entry point: navigation, actions, function-key bar
├── NetResource.java            a remote file/folder entry (real SFTP-backed Path)
├── NetVirtualResource.java     the "Net" root and server-list entries (path-less)
├── find/                       Alt+F7 Find: remote find + SFTP-walk fallback, dialog, results window
├── service/                    copy/move/delete/mkdir/edit engines and shared dialog helpers
├── NetDirectoryCache.java      per-server+path listing cache
├── ssh/                        SSH session, SFTP/SCP access, remote shell channel, server profiles, key loading, host-key gate
├── tail/                       tail -F viewer window
└── ui/                         connection/go-to-folder dialogs, credential/host-key prompts, shared text-field editing (undo/redo, cut/copy/paste/select-all with icons)

📚 Dependencies

⚠️ Known limitations

• Hex/quick-view writes bypass the atomic-upload flow. F4 Edit routes through the temp-copy-and-atomic-rename workflow described above, so both the text and hex editors get conflict detection there. Quick View (Ctrl+Q) and any other code path that writes directly to the SFTP-backed Path (rather than going through F4) writes straight to the remote file with a plain SFTP write — no atomicity, no conflict check.
• Same-server copies are not server-side. Copying between two folders of the same connection currently downloads-then-uploads over SFTP rather than issuing a server-side copy command; correct, but not as fast as it could be.
• tail -F reconnect resumes from "now", not from the exact byte offset. If the SSH session drops mid-tail, a couple of lines written during the gap could be missed (the new tail invocation starts with -n 0).
• Remote find regex dialects vary too much to target directly (GNU vs BusyBox vs macOS), so regex searches always use the slower SFTP-walk fallback, even when the server's find would have supported an equivalent flag.
• No FTP/FTPS support — only SFTP/SCP over SSH, per the task scope.
• Deleting a remote file is always permanent — there is no server-side trash to move it to.
• The directory-listing cache has no cross-server-mutation awareness. A move's destination folder is invalidated by the plugin instance that receives it, but if the source side of a cross-panel move is also a Net panel, its own cached listing isn't proactively invalidated (mirrors a pre-existing gap in the equivalent local-filesystem/move flow) — an explicit Ctrl+R on that side clears it.
• Context-menu icons (NuclrContextMenuItem.iconKey) are set but not yet rendered by the commander. Nothing in the host currently resolves iconKey into an actual icon for any plugin's context menu, so the New/Edit/Remove Server, Delete and Tail -F entries carry a sensible key (e.g. "delete", "terminal") for forward compatibility, but show no icon today. The one context menu this plugin fully renders itself — the text-field Cut/Copy/Paste/Undo/Redo/Select All menu in the connection dialog — does show icons, bundled with the plugin.

📜 License

Apache License 2.0 — see LICENSE.