RemoteForge is a lightweight, reliable VS Code extension for directly editing remote files over SSH/SFTP as if they were local workspace files.
Engineered to resolve common pain points found in existing SFTP extensions, such as silent UI hangs, accidental file overwrites, and slow directory browsing latency.
💡 Key Features
No UI Freezes (Native FileSystemProvider): Integrates remote directories into VS Code using a custom remoteforge:// URI scheme. Keeps the editor responsive even during network hiccups.
Instant Directory Browsing (Smart Stat Cache): Pre-caches child metadata during directory reads (READDIR). Sub-queries for file stats hit RAM instantly (0 ms latency) rather than triggering individual network roundtrips.
Prevents Data Overwrites (Conflict Detection): Compares the server's modification time (mtime) with the version you opened. If the file changed in between, the save is stopped and you choose: overwrite, load the remote version, or compare both.
Production Safety (Manual Sync Mode): Choose between instant auto-upload or queuing changes locally for explicit batch approval (Push Pending Changes).
Credential Security: Passwords and SSH keys are stored in the operating system's native keychain using VS Code SecretStorage — never written to disk or settings.json.
Resilient Connections: SSH protocol keepalives prevent idle disconnects, while guarded exponential-backoff reconnects hold file requests until the transport returns. The log names each handshake step, so a failed connection says where it stalled.
Host Key Verification: The server's fingerprint is confirmed on first use and checked on every later connection.
Integrated SSH Terminal: Opens a shell on the connected server inside VS Code's terminal panel.
Saved Working Folder: Each server profile remembers its default remote directory, so repeat connections do not require retyping a path.
🛠 Architecture & Request Flow
VS Code Explorer ──> RemoteFileSystemProvider ──> Smart Stat Cache ──> SftpClient ──> ConnectionManager (SSH2) ──> Remote Server
ConnectionManager: Handles SSH2 lifecycle and exponential backoff reconnection strategies.
Channel Deduplication: Reuses a single SFTP subsystem channel across concurrent operations to prevent SSH channel open failures.
Connection Gate: Holds incoming file requests synchronously during activation until the SSH handshake resolves.
🚀 Quick Start (Development)
Clone the repository and install dependencies:
git clone git@github.com:FerhatAkkopru/RemoteForge.git
cd RemoteForge
npm install
Compile the extension:
npm run compile
Open the project in VS Code and press F5 to launch the Extension Development Host.
📖 Usage Guide
Add Server Profile: Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P), run RemoteForge: Add Server Profile, and enter host, port, credentials, and profile name.
Connect to Server: Run RemoteForge: Connect to Server, pick your profile, and enter the remote absolute path (e.g. / or /var/www).
View Logs: Run RemoteForge: Show Log to view real-time timestamped connection and SFTP operation logs in the Output panel.
⌨️ Registered Commands
Command
Description
RemoteForge: Connect to Server
Connects to a server and mounts a remote directory as workspace.
RemoteForge: Disconnect
Terminates active SSH connection and unmounts remote folder.
RemoteForge: Add Server Profile
Launches profile setup wizard for new server credentials.
RemoteForge: Change Saved Remote Folder
Changes the default remote directory stored with a server profile.
RemoteForge: Delete Server Profile
Removes saved profile and stored secret key from OS keychain.
RemoteForge: Push Pending Changes
Flushes queued local modifications to remote server (Manual Mode).
RemoteForge: Show Log
Focuses the extension's dedicated log channel in Output view.
RemoteForge: Open SSH Terminal
Opens an interactive shell on the connected server in the terminal panel.
RemoteForge: Refresh (Clear Cache)
Drops cached directory listings and reloads the remote file tree.
⚠️ Known Limitations
One Server at a Time: A window holds a single SSH connection. Tabs left open from another profile are refused instead of being served by the wrong server.
Manual Mode Queue Lives in Memory: Pending changes are not written to disk. RemoteForge asks before disconnecting or switching profiles, but closing or crashing VS Code discards them.
Authentication: Password and private key files are supported. ssh-agent and ~/.ssh/config are not read.
Large File Streaming: Files are currently buffered into memory during read/write operations. Extremely large files (>100MB) may cause memory spikes.
Local Git Integration: VS Code's native Git extension inspects the local filesystem; remote Git operations should be executed via the integrated SSH terminal (RemoteForge: Open SSH Terminal).
Workspace Search: Full-text workspace search relies on local filesystem indexing; remote search across millions of files is constrained by network latency.
RemoteForge (Türkçe)
RemoteForge, uzak sunuculardaki (SSH/SFTP) dosyaları VS Code içerisinden yerel dosya gibi doğrudan ve güvenli bir şekilde düzenlemenizi sağlayan hafif bir VS Code eklentisidir.
Piyasadaki SFTP eklentilerinde sıkça karşılaşılan donma (silent hang), dosya ezilmesi (overwriting) ve yavaş klasör yükleme problemlerini çözmek için geliştirilmiştir.
💡 Neden RemoteForge?
Donma Yok (Native FileSystemProvider): Uzak dosyaları VS Code sanal dosya sistemi (remoteforge://) olarak kaydeder. Ağ kesilse bile VS Code kilitlenmez.
Şak Diye Açılan Klasörler (Smart Stat Cache): Klasör açıldığında tüm alt dosyaların meta verileri tek ağ sorgusunda önbelleğe alınır. Klasör gezintisi 0 ms gecikmeyle çalışır.
Sessiz Veri Kaybını Önler (Conflict Detection): Sunucudaki değiştirilme zamanını (mtime) açtığınız sürümle karşılaştırır. Arada dosya değiştiyse kayıt durdurulur ve siz seçersiniz: üzerine yaz, sunucudakini getir veya ikisini karşılaştır.
Üretim Sunucuları İçin Güvenli (Manual Sync Mode): Dosyaları kaydettiğiniz an sunucuya göndermek yerine biriktirip tek tıkla onaylayarak canlıya push edebilirsiniz.
Güvenlik: Şifreleriniz veya SSH anahtarlarınız settings.json dosyasına yazılmaz; doğrudan işletim sisteminizin güvenli anahtarlığında (VS Code SecretStorage) saklanır.
Dayanıklı Bağlantı: SSH keepalive paketleri boşta kalınca kopmayı önler; kontrollü yeniden bağlanma sırasında dosya istekleri bağlantının dönmesini bekler. Log her el sıkışma adımını yazar; başarısız bağlantı nerede takıldığını söyler.
Sunucu Anahtarı Doğrulama: Sunucunun parmak izi ilk bağlantıda onaylanır, sonraki her bağlantıda kontrol edilir.
Entegre SSH Terminali: Bağlı sunucuda VS Code terminal panelinde kabuk açar.
Kayıtlı Çalışma Klasörü: Her sunucu profili varsayılan uzak dizinini hatırlar; her bağlantıda yolu yeniden yazmanız gerekmez.
🛠 Mimari & Çalışma Mantığı
VS Code Explorer ──> RemoteFileSystemProvider ──> Smart Stat Cache ──> SftpClient ──> ConnectionManager (SSH2) ──> Remote Server
Connection Manager: SSH2 bağlantısını ve yeniden bağlanma (exponential backoff) mantığını yönetir.
Channel Deduplication: Onlarca dosya isteği aynı anda gelse bile SSH kanal kilitlenmesini engellemek için SFTP alt sistemini tekil olarak paylaşır.
Connection Gate: VS Code ilk açıldığında arka plan sorgularının sunucu bağlantısı tamamlanana kadar beklemesini sağlar.
🚀 Hızlı Başlangıç (Geliştirme)
Repoyu klonlayın ve bağımlılıkları yükleyin:
git clone git@github.com:FerhatAkkopru/RemoteForge.git
cd RemoteForge
npm install
Projeyi derleyin:
npm run compile
VS Code'da projeyi açıp F5 tuşuna basarak eklentiyi çalıştırın.
📖 Kullanım Kılavuzu
Profil Ekleme:Cmd+Shift+P (macOS) / Ctrl+Shift+P (Windows/Linux) basın ve RemoteForge: Add Server Profile komutunu seçin. Sunucu IP, port, kullanıcı adı ve şifre/key bilgilerinizi girin.
Sunucuya Bağlanma:RemoteForge: Connect to Server komutunu çalıştırın, eklediğiniz profili seçin ve açmak istediğiniz uzak dizini (örneğin / veya /var/www) girin.
Logları İzleme: Bağlantı ve dosya transfer detaylarını canlı izlemek için RemoteForge: Show Log komutunu kullanabilirsiniz.
⌨️ Komut Listesi
Komut
Açıklama
RemoteForge: Connect to Server
Kayıtlı bir sunucuya bağlanır ve uzak dizini workspace olarak açar.
RemoteForge: Disconnect
Aktif sunucu bağlantısını ve uzak klasörü kapatır.
RemoteForge: Add Server Profile
Yeni sunucu bağlantı profili oluşturur.
RemoteForge: Change Saved Remote Folder
Profilde kayıtlı varsayılan uzak çalışma dizinini değiştirir.
RemoteForge: Delete Server Profile
Kayıtlı profili ve şifreleri sistemden siler.
RemoteForge: Push Pending Changes
Manuel senkronizasyon modunda bekleyen değişiklikleri sunucuya atar.
RemoteForge: Show Log
Detaylı işlem ve hata log panelini açar.
RemoteForge: Open SSH Terminal
Bağlı sunucuda terminal panelinde etkileşimli kabuk açar.
RemoteForge: Refresh (Clear Cache)
Önbellekteki klasör listelerini temizler ve uzak dosya ağacını yeniler.
⚠️ Bilinen Sınırlandırmalar
Aynı Anda Tek Sunucu: Bir pencere tek SSH bağlantısı tutar. Başka profilden açık kalan sekmeler yanlış sunucudan sunulmak yerine reddedilir.
Manuel Mod Kuyruğu Bellekte: Bekleyen değişiklikler diske yazılmaz. Bağlantıyı keserken veya profil değiştirirken RemoteForge sorar, ancak VS Code kapanır veya çökerse bu değişiklikler kaybolur.
Kimlik Doğrulama: Parola ve özel anahtar dosyası desteklenir. ssh-agent ve ~/.ssh/config okunmaz.
Büyük Dosya Yönetimi: Dosya okuma/yazma işlemleri veriyi bellek üzerinde önbellekler. Çok büyük dosyalar (>100MB) RAM kullanımını artırabilir.
Yerel Git Entegrasyonu: VS Code'un yerleşik Git eklentisi yerel dosya sistemini tarar; uzak sunucu üzerindeki Git komutları entegre SSH terminali (RemoteForge: Open SSH Terminal) üzerinden çalıştırılmalıdır.
Tüm Workspace İçi Arama: Proje genelinde kelime araması ağ gecikmesine bağlıdır; devasa projelerde sunucu tarafı arama için SSH terminali kullanılması önerilir.
