FTP/SFTP Sync

Extensão do VS Code para enviar e baixar arquivos de um servidor FTP, FTPS ou SFTP direto pelo menu de contexto, com a configuração guardada no próprio projeto.

• Clique com o botão direito num arquivo ou pasta (no Explorer, no editor ou na aba) e escolha:
  • Comparar com o servidor: mostra lado a lado o que é diferente, o que só existe de um lado e qual está mais atualizado
  • Upload: sobrescrever no servidor
  • Download: sobrescrever local
• Funciona com seleção múltipla e com pastas (recursivo, respeitando ignore).
• Os comandos também ficam na paleta (Cmd+Shift+P → "FTP Sync"), agindo sobre o arquivo aberto.

Configuração

Rode FTP Sync: Criar arquivo de configuração na paleta. A extensão cria .vscode/ftp-sync.json com comentários explicando cada campo:

{
  "protocol": "sftp",            // "sftp" ou "ftp"
  "host": "seu-servidor.com.br",
  "port": 22,                    // padrão: 22 (sftp) / 21 (ftp)
  "username": "usuario",
  // "password": "",             // opcional: sem ela, a senha é pedida e guardada no Keychain
  // "privateKeyPath": "~/.ssh/id_ed25519",

  "localPath": ".",              // pasta local, relativa à raiz do projeto
  "remotePath": "/var/www/html", // pasta no servidor (absoluta)

  "ignore": ["*.log"],           // padrões extras (node_modules, vendor... já são ignorados)
  // "include": ["vendor"]      // libera algo que é ignorado por padrão
}

O editor valida o arquivo e completa os campos enquanto você digita.

Como os caminhos são mapeados

Com "localPath": "public" e "remotePath": "/var/www/html":

O que fica de fora (ignore e include)

Sempre ignorados, em upload, download e comparação: .git, .svn, .hg, .vscode, node_modules, vendor, .DS_Store e Thumbs.db.

• "ignore" soma padrões a essa lista. Escrever "ignore": ["*.log"] não libera o node_modules.
• Só "include" libera um item da lista padrão, ex.: "include": ["vendor"] para enviar e comparar a pasta vendor de um projeto PHP.
• Clicar direto numa pasta ignorada (ou numa pasta dentro dela) é recusado, com uma mensagem explicando como liberar.

Sintaxe dos padrões:

• Padrão sem / vale em qualquer nível: *.log, node_modules.
• Padrão com / é ancorado em localPath: dist/**.
• / no final restringe a pastas: build/.
• Padrões de exceção com ! não são suportados.
• Arquivos selecionados diretamente são sempre transferidos. O ignore vale para o conteúdo de pastas.
• O próprio .vscode/ftp-sync.json nunca é enviado. O download nunca grava em .vscode/ nem em .git/.

Comparar com o servidor

Botão direito → Comparar com o servidor. Nada é transferido; a extensão só lê os dois lados.

• Pasta (ou vários itens): abre um painel com Local e Servidor lado a lado, com tamanho e data de cada arquivo e a situação no meio. O lado mais novo fica destacado.
  • Filtros: Diferenças (padrão), Só local, Só no servidor, Iguais e Todos, mais uma busca por caminho.
  • Em cada linha: Diferenças (abre o diff de conteúdo), Enviar e Baixar. Clicar no nome abre o arquivo.
  • Marque várias linhas para enviar ou baixar de uma vez. Depois de transferir, o painel se atualiza sozinho.
• Arquivo: abre direto o diff do VS Code, com a versão do servidor à esquerda (somente leitura) e a local à direita, e a situação no título. Se o arquivo só existe de um lado, aparece uma notificação com o botão para enviar ou baixar.

Como a extensão sabe qual está mais atualizado

A cada upload ou download, a extensão guarda como ficaram os dois lados (tamanho e data). Esse histórico fica no estado do VS Code, não no projeto nem no servidor, e nenhuma data de arquivo é alterada. Na comparação seguinte ela sabe exatamente o que mudou desde então:

Para arquivos que nunca passaram pela extensão, ela compara as datas de modificação. O status vira Local mais recente ou Servidor mais recente, e diferenças de até 2 segundos contam como iguais. Nesse caso o resultado depende de o relógio do servidor estar certo. Em FTP sem o comando MLSD, a data de cada arquivo que existe nos dois lados é pedida com MDTM. Se o servidor não informar data nenhuma, aparece Sem data no servidor e a comparação fica só pelo tamanho.

Comportamento

• Upload salva antes os arquivos abertos com alterações, cria as pastas que faltarem no servidor e sobrescreve os arquivos remotos.
• Download baixa primeiro para um arquivo temporário e só substitui o local quando a transferência termina. Se a conexão cair no meio, o arquivo original fica intacto. Se algum arquivo que vai ser substituído tiver alterações não salvas, a extensão pede confirmação antes de descartá-las. O download também restaura um arquivo apagado localmente (pela aba ainda aberta ou pela paleta).
• Pastas pedem confirmação antes de transferir, mostrando quantos arquivos são, para qual usuário@host e por qual protocolo.
• O progresso aparece numa notificação. Cancelar fecha a conexão na hora, inclusive no meio de um arquivo grande. O detalhe de cada arquivo fica no painel Output → FTP Sync.
• Arquivo aqui e pasta no servidor (ou o contrário) gera um erro claro antes de qualquer arquivo ser gravado.

Segurança

• Pasta confiável: a extensão fica desativada no Restricted Mode do VS Code. Ela só funciona depois que você confia na pasta, porque um repositório de terceiros poderia trazer uma configuração apontando para outro servidor.
• Senhas: sem password no arquivo, a senha é pedida na primeira conexão e guardada no SecretStorage do VS Code (Keychain no macOS). Se o servidor recusar o login, a senha salva é descartada. A senha fica atrelada ao nível de segurança do transporte: se a configuração trocar FTPS por FTP sem TLS, ou desligar a verificação do certificado, ela é pedida de novo. Para apagar a senha manualmente: FTP Sync: Esquecer senha salva.
• Chave do servidor SSH: na primeira conexão SFTP aparece a impressão digital (SHA256:...) para você confirmar. Se a chave mudar depois, a extensão avisa e não conecta sem uma nova confirmação.
• .gitignore: ao criar a configuração num repositório git, a extensão oferece adicionar .vscode/ftp-sync.json ao .gitignore.
• FTP sem TLS envia senha e arquivos em texto puro, e a extensão avisa no log a cada conexão. Prefira SFTP, ou FTP com "secure": true (TLS 1.2 ou superior).
• Links simbólicos locais: um arquivo ou pasta só é enviado ou gravado se o destino real do link ficar dentro de localPath. Isso impede enviar ou sobrescrever arquivos fora do projeto, como ~/.ssh.
• Downloads: nomes vindos do servidor que tentem sair da pasta (../, /, nomes inválidos no Windows) são ignorados, e links simbólicos para pastas não são seguidos. Uma pasta com mais de 100.000 itens ou mais de 64 níveis de subpastas é recusada.

Comandos

Os itens de menu só aparecem quando algum projeto aberto tem .vscode/ftp-sync.json.

Instalação

npm install
npm run package          # gera ftp-sftp-sync-0.1.0.vsix
code --install-extension ftp-sftp-sync-0.1.0.vsix

Desenvolvimento

npm run watch            # rebuild contínuo; F5 no VS Code abre uma janela com a extensão
npm run typecheck
npm test                 # testes unitários
npm run test:integration # FTP real (ftp-srv) + SFTP real (OpenSSH via Docker; pulado sem Docker)
npm run coverage
npm run test:e2e         # abre um VS Code de teste e roda os comandos de verdade

Estrutura:

src/
  extension.ts        ativação e registro dos comandos
  config/             schema (zod), leitura do JSONC, template, .gitignore
  core/               mapeamento de caminhos, ignore, motor de transferência, conexão/credenciais
  clients/            FTP (basic-ftp) e SFTP (ssh2-sftp-client)
  vscode/             menus, diálogos, progresso, SecretStorage, painel de comparação
  webview/            script e formatação do painel (roda dentro do webview)
media/                CSS do painel
test/
  unit/  integration/  e2e/