remote ssh

🖥️ Desenvolvimento Remoto via SSH

O Codis suporta edição de arquivos em servidores remotos diretamente pela interface do editor, sem precisar instalar nada no servidor além do SSH padrão.

---

Requisitos

• Binário ssh disponível no PATH local (padrão em Linux, macOS; Git for Windows no Windows)
• Binário scp ou sftp para transferência de arquivos
• Acesso SSH ao servidor (chave privada ou senha)

Nenhuma instalação no servidor é necessária.

---

Configurando um Perfil SSH

Acesse Ferramentas → Remoto & Colaboração → SSH Remoto…, pelo atalho Ctrl+Shift+H, ou pelo ícone 🖧 na barra de atividades (visível quando a chave de configuração ssh_enabled estiver definida como true - não existe por padrão em config.json, sendo necessário adicioná-la manualmente ou usar o menu/atalho).

Clique em + Novo Perfil e preencha:

Campo	Descrição
Nome do perfil	Identificador amigável (ex: "Servidor de Produção")
Host / IP	Endereço do servidor (ex: 192.168.1.10 ou meu.servidor.com)
Porta	Porta SSH (padrão: 22)
Usuário	Login SSH (ex: ubuntu, root)
Chave SSH	Caminho para .pem ou chave privada (deixe vazio para senha)
Diretório remoto	Pasta inicial ao navegar (padrão: ~)
Jump Host	ProxyJump intermediário (ex: bastion.empresa.com)

Os perfis são salvos em ~/.config/codis/ssh_profiles.json.

---

Testando a Conexão

Selecione um perfil e clique em Testar. O Codis executa ssh ... echo ok e exibe o resultado na barra de status. Erros comuns:

• ssh: command not found - instale o cliente SSH
• Connection refused - servidor inacessível ou porta errada
• Permission denied - chave incorreta ou usuário inválido

---

Navegando Arquivos Remotos

O painel Arquivos Remotos funciona igual para SSH/SFTP, FTP/FTPS, HTTP(S) e WebDAV.

Ação	Como
Abrir pasta / arquivo	Duplo clique ou Enter (arquivos abrem no editor com o nome original)
Subir um nível	Backspace ou botão ↑
Voltar / avançar	Alt+← / Alt+→
Editar o caminho	Ctrl+L ou clique na área vazia dos breadcrumbs
Atualizar	F5
Filtrar	Ctrl+F (instantâneo)
Ordenar	Clique no cabeçalho da coluna (pastas sempre primeiro)
Renomear / excluir	F2 / Del (SSH, FTP, WebDAV)
Nova pasta	Ctrl+N

O menu de contexto (botão direito, em arquivo, pasta ou área vazia) oferece abrir, baixar, enviar, nova pasta, renomear, excluir e copiar caminho. Baixar/enviar aceita seleção múltipla e pastas inteiras (recursivo, com limite de segurança). O painel lateral recolhe sozinho em janelas estreitas (botão ☰) e as colunas secundárias somem conforme a largura.

Salvar envia de volta (sync ao salvar)

Qualquer forma de salvar um arquivo aberto do servidor (Ctrl+S, Salvar tudo ou autosave) o reenvia. Se o arquivo mudou no servidor desde que foi aberto, o Codis pergunta antes de sobrescrever. Se o envio falhar, você é avisado e pode tentar de novo (as alterações continuam salvas localmente). Desative com remote_sync_on_save: false.

Protocolos

Protocolo	Listar	Baixar	Enviar	Criar pasta / renomear / excluir
SSH / SFTP	✓	✓	✓	✓
FTP / FTPS (explícito :21, implícito :990)	✓ (MLSD ou LIST Unix/IIS)	✓	✓	✓ (pasta vazia para excluir)
WebDAV / WebDAVS	✓	✓	✓	✓
HTTP / HTTPS (índice Apache/nginx)	✓	✓	–	–

No cadastro da conexão você pode colar uma URL (sftp://user@host:2200/var/www) no campo Host e os demais campos são preenchidos. O botão Testar conexão valida sem fechar o diálogo.

---

Debug Remoto (DAP via Túnel SSH)

O Codis pode criar um túnel SSH para conectar o depurador local a um processo debugpy rodando no servidor.

No servidor, inicie o processo com debugpy:

python -m debugpy --listen 0.0.0.0:5678 meu_script.py

No Codis, abra o painel remoto, conecte ao perfil e clique em Abrir Túnel Debug. O Codis criará um túnel localhost:5678 → servidor:5678, e o cliente DAP local (o mesmo do Painel de Debug) conecta normalmente nesse túnel, como se o processo estivesse rodando na própria máquina.

As portas usadas pelo túnel são informadas diretamente no diálogo Abrir Túnel Debug, e são independentes da configuração debug_dap_port (usada apenas para depuração local, sem SSH). Se a porta local do túnel colidir com outra ferramenta de debug já em uso na sua máquina (ex: VS Code também escutando em 5678), basta escolher outra porta local no diálogo do túnel.

---

Configuração Avançada com Jump Host

Para servidores atrás de um bastion/jump host:

Perfil: Servidor Interno
Host: 10.0.0.50
Porta: 22
Usuário: dev
Jump Host: bastion.empresa.com

O Codis usa ssh -J bastion.empresa.com dev@10.0.0.50 automaticamente.

---

Autenticação

Ordem: chave privada → senha → ssh-agent. A senha vai para o ssh por sshpass -e (Linux/macOS, se instalado) ou por um SSH_ASKPASS temporário, o que faz o login por senha funcionar também no Windows, sem sshpass. A senha nunca aparece na linha de comando. Se a chave tiver passphrase, informe-a no campo Senha. Em Linux/macOS a conexão é reutilizada (ControlMaster): uma única autenticação para listar, baixar e enviar; defina CODIS_SSH_NOMUX=1 para desativar.

Limitações

• O servidor SSH precisa de shell POSIX (ls, cd, mkdir, rm, mv); servidores Windows (cmd/PowerShell) não são suportados para listagem.
• Progresso de transferência é detalhado em FTP/HTTP/WebDAV; em SSH a barra fica indeterminada (usa o sftp do sistema).
• Não há watch remoto de arquivos (mudanças externas só são detectadas ao salvar, pela checagem de conflito).
• Senhas ficam em base64 (ofuscação, não criptografia) em arquivo 0600; prefira chaves ou o ssh-agent.
• O caminho SSH_ASKPASS no Windows ainda não foi validado em máquina Windows real.

---

Configurações

Acesse em Configurações → SSH Remoto (ou Ctrl+, → categoria SSH Remoto):

Chave	Padrão	Descrição
ssh_default_port	22	Porta SSH padrão para novos perfis
ssh_connect_timeout	15	Timeout de conexão (segundos)
ssh_keepalive_interval	30	Intervalo keepalive em segundos (0 = off)
ssh_agent_forwarding	False	Habilita forwarding do agente SSH
ssh_strict_host_key	True	Verifica chave do host strictamente
ssh_sftp_buffer_kb	64	Tamanho do buffer SFTP em KB
ssh_open_in_editor	True	Baixa e abre arquivo remoto no editor
ssh_enabled	False	Exibe ícone SSH na barra de atividades

As configurações debug_dap_enabled/debug_dap_port pertencem à categoria Avançado (depuração local, sem SSH) - veja Debug e Configurações → Avançado. O túnel de debug SSH descrito acima usa portas informadas diretamente no diálogo, não essas chaves.

---

Segurança e robustez

• Caminhos escapados. O caminho navegado é escapado com shlex.quote antes de ir ao shell remoto (preservando a expansão de ~), de modo que nomes com ;, crases ou $() não são executados.
• Senha SSH fora da linha de comando. Com sshpass, a senha é transmitida por variável de ambiente (sshpass -e + SSHPASS), nunca como argumento visível em ps.
• Lote do sftp. Caminhos são citados no estilo do parser do sftp e quebras de linha embutidas são rejeitadas.
• Caminhos iniciados por -. O terminador de opções -- é usado antes dos caminhos no scp.
• Permissões. Perfis de conexão (remote_browser_profiles.json) e demais arquivos com credenciais ofuscadas são salvos com permissão 0600 (Linux/macOS).
• Listagem SSH. O parser ancora no tamanho/data de ls --time-style=long-iso e funciona com GNU, BSD e BusyBox.
• Erros visíveis. Permissão negada e pasta inexistente exibem a mensagem real e um botão Tentar novamente.
• Sync ao salvar. O editor notifica src/editor/save_hooks.py em qualquer gravação; falhas de upload/download são reportadas como erro.
• Arquivos sem extensão conhecida (Makefile, Dockerfile, dotfiles) são inspecionados (byte nulo) em vez de recusados.

Os testes estão em tests/test_remote_adapters.py e tests_gui/test_remote_browser_panel.py.