Comecou com uma pergunta na sexta-feira a tarde: "sera que da pra fazer o Claude compilar AdvPL?". Tres dias depois eu tinha um repositorio funcional, testado contra um AppServer cloudtotvs em ambiente real, com TLS, autenticacao, upload, compile e rollback automatico funcionando. Esse post conta como cheguei la — e por que essa skill faz sentido pro nosso dia-a-dia.

Spoiler: a TOTVS deixou o motor todo aberto, so ninguem tinha conectado ainda.

O ponto de partida: TDS-VSCode

Quem usa Protheus moderno conhece o TOTVS Developer Studio for VSCode. E uma extensao TypeScript que da pra dev Protheus o que o ERP nunca teve nativo: compilacao remota integrada no editor, debug com SmartClient, gerenciamento de RPO, patches, monitor. Tem ate API publica pra outras extensoes consumirem.

O que pouca gente percebe e que essa extensao e basicamente uma casca. O que ela faz por baixo e disparar um binario chamado advpls.exe, que vem empacotado num pacote NPM (@totvs/tds-ls). Esse binario implementa o protocolo do Language Server Protocol (LSP) da Microsoft, com mensagens customizadas $totvsserver/* que falam com o AppServer da TOTVS via TCP.

Em outras palavras: quem realmente compila e o advpls. O TDS-VSCode so chama. E o advpls tem 4 modos de execucao documentados:

  • language-server — modo LSP padrao (que o TDS-VSCode usa)
  • cli — script INI sequencial pra automacao
  • appre — pre-compile sem AppServer
  • tds-cli — legado compat Eclipse

Se voce esta lendo um post da ArchTec, voce ja entendeu onde isso vai dar.

O experimento

Instalei o pacote em uma pasta isolada:

npm install @totvs/tds-ls

Rodei o binario:

advpls.exe --version
# TDS-LS 2.0 (Rev.: ~18,-1)

Peguei um fonte de teste minimo e tentei o modo appre (pre-compile sem servidor). Erro: File not found PRTOPDEF.CH. Faltavam os includes do Protheus. Como dev veterano tem isso em C:\includes (ou copia do AppServer), apontei e tentei de novo.

Funcionou.

$ advpls appre -I C:/includes -O output/ teste.prw
[INFO] Validado sem erros
# gera teste.ppx_prw com fonte pre-processado

Validei tambem com um fonte propositalmente quebrado (esqueci um EndIf):

$ advpls appre -I C:/includes teste-broken.prw
appre41(8) Error C2024  Unclosed control structures

Linha exata, codigo do erro, descricao em ingles. Suficiente pro Claude ler e me explicar o problema em portugues.

O salto: compilar de verdade

Validacao local e legal, mas o que dev Protheus quer e compilar e gerar RPO. Pra isso preciso de um AppServer real. O modo cli aceita um arquivo INI com credenciais e o caminho do fonte. Tipo isso:

[connect]
action=authentication
server=meu-appserver.cloudtotvs.com.br
port=6701
secure=1
build=AUTO
environment=PROD_VAL
user=admin
psw=...

[compile]
action=compile
program=C:/fontes/MATA010.prw
recompile=T
includes=C:/includes

Fiz o teste contra um ambiente de homologacao real (cloudtotvs com TLS):

[INFO] Starting connection to ...protheus.cloudtotvs.com.br@6701
[INFO] Connection finished.
[INFO] User 'admin' authenticated successfully.
[INFO] Starting build for environment U5JHMZ_TESTE_VALIDADO.
[INFO] Using Includes: g:/.../includes
[INFO] [SUCCESS] Source ...prw compiled successfully.
[INFO] Committing end build. This could take a while...
[INFO] All files compiled successfully.
===OK===

Compilou. RPO atualizado. Sem TDS-VSCode aberto.

Testei tambem o caminho do erro — passei um fonte com EndIf faltando. O servidor detectou, retornou o erro com linha, e fez rollback automatico do build:

[SERVER MESSAGE] arquivo(8) Error C2024  Unclosed control structures
[INFO] Aborting end build (rollback changes).

Nada na producao foi tocado. Perfeito.

De experimento a skill

A essa altura ja era obvio que isso virava feature. Empacotei o conhecimento em quatro skills do Claude Code:

SkillO que fazPrecisa AppServer?
/advpl-setupInstala @totvs/tds-ls, valida includes, configura ambienteNao
/advpl-validatePre-compile local, detecta sintaxe e includesNao
/advpl-serversLista AppServers configurados na sua extensao TDS-VSCodeNao
/advpl-compileCompila remoto no seu AppServer (gera RPO)Sim

A parte que ninguem esperava

O detalhe que muda tudo: o TDS-VSCode persiste todos os servers configurados num arquivo simples — ~/.totvsls/servers.json. Se voce ja usa a extensao, voce ja tem esse arquivo. A skill consome esse JSON direto.

Fluxo zero-config:

voce: /advpl-compile MATA010.prw
Claude: encontrei 3 servers configurados na sua extensao:
        1. Homolog Cloud (homol.cloudtotvs.com.br:6701)
        2. Producao On-Premise (servidor.cliente.local:2078)
        3. Local Dev (localhost:6701)
        qual usar?
voce: 1
Claude: senha do admin no Homolog Cloud?
voce: ********
Claude: compilando...
        ===OK=== Compilado em homolog. RPO atualizado.
        salvar credenciais pra proxima vez?

Zero arquivo de configuracao manual. Reusa o que voce ja tem. Se voce nao usa TDS-VSCode (mais raro), tambem da — configura via JSON do proprio Claude Code.

Onde a IA realmente ajuda

So compilar via terminal nao seria revolucionario — daria pra fazer com um .bat. O que muda e o que vem ao redor de compilar:

flowchart TD Edit[Editar .prw] --> Review{Pedir review
ao Claude?} Review -->|Sim| Issues[Claude detecta:
RecLock sem MsUnlock,
SQL sem D_E_L_E_T_,
escopo errado] Review -->|Nao| Compile Issues --> Fix[Aplicar fix sugerido] Fix --> Compile[/advpl-compile arquivo.prw/] Compile --> Err{Erro?} Err -->|Sim| Diag[Claude explica
o erro em pt-BR
e sugere correcao] Err -->|Nao| Done[RPO atualizado
Debug no TDS-VSCode] Diag --> Fix

Antes de mandar pro compilador, voce pode pedir um review semantico. O Claude le o fonte e identifica padroes problematicos — RecLock sem MsUnlock escondido num Else, SQL sem filtro de D_E_L_E_T_, variaveis usadas sem declaracao virando PUBLIC implicito. Coisas que o linter sintatico do TDS-VSCode nao pega.

Quando o compile falha, voce cola o erro no chat e pede explicacao. Em portugues, com contexto da sua versao do Protheus. Em vez de googlar C2024 advpl e cair num forum de 2014.

O que ela NAO faz (limites honestos)

Pra evitar vender ilusao:

  • Nao substitui debug visual. Pra inspecionar variavel em runtime, breakpoint em loop, navegar stack — voce continua no TDS-VSCode com SmartClient.
  • Nao opera tela do Protheus. Pra cadastrar produto em MATA010, abrir Configurador, etc., voce continua usando o sistema normalmente.
  • Pode alucinar nomes de funcoes. Especialmente em TLPP recente. Sempre confirme no TDN se uma funcao citada existe na sua build.
  • Nao executa rotina batch. Disparar JOB, executar processo em fila — fora do escopo da v0.1.

Casos de uso reais do meu dia-a-dia

Depois de uns dias usando, os 4 cenarios onde mais agregou:

1. Pre-compile antes de subir pra homolog

Em vez de descobrir 5 minutos depois (no console do TDS-VSCode) que um EndIf falta, ja saio do editor com fonte limpo. Roda em <1 segundo.

2. Auditar fonte legado de terceiros

Recebo um .prw de outro consultor pra revisar. Em vez de ler 800 linhas manual, peco review pro Claude. Ele aponta os problemas em segundos, eu confirmo e priorizo.

3. Erro de compilacao sem contexto

Erro C2090 File not found PRTOPDEF.CH no TDS-VSCode? Cola no Claude. Ele explica que e includes nao configurados, mostra qual MV ou variavel ajustar, sugere o comando.

4. Refatorar AdvPL legado pra TLPP moderno

Codigo de 2008 com Function nua, 5 niveis de IF aninhado, variaveis cVar1. Peco refator. Claude entrega versao moderna com User Function, early-return, nomes claros — preservando comportamento. Eu reviso e aplico.

O que vem ai (roadmap v0.2+)

Coisas que ja estao no backlog:

  • /advpl-doc — gera header Protheus.doc automatico
  • /advpl-find-issues — analise estatica em massa (pasta inteira)
  • /advpl-execauto — boilerplate User Function MSExecAuto pra MATA010/030/410, FINA040/070
  • /advpl-mvc-skeleton — gera struct + model + view + viewdef MVC completo
  • /advpl-log — analisa appserver.log, identifica erros e gargalos
  • /advpl-query — conecta direto no MSSQL/Oracle do Protheus pra debug de dados

Por que estou liberando aberto

Tres razoes:

Primeiro: nao da pra construir nada relevante pra comunidade Protheus em silos. O ecossistema e pequeno, a documentacao oficial e dispersa, e o conhecimento ainda vive em grupos de WhatsApp. Codigo aberto e a unica forma de acelerar.

Segundo: o motor e da TOTVS (@totvs/tds-ls com licenca Apache 2.0). A skill so amarra peças que ja existem. Nao tem segredo nem feature exclusiva — o valor esta em fazer funcionar fluidamente, com UX zero-config, integrado ao TDS-VSCode que voce ja usa.

Terceiro: licencas restritivas em ferramenta de produtividade matam adocao. MIT, sem trava, sem call-home, sem nada. Fork, modifica, contribui.

Como baixar e instalar

A v0.1 esta pronta pra download. Pre-requisitos minimos: Node.js 16+ e a pasta de includes do Protheus acessivel (tipicamente C:\includes em Windows ou /opt/protheus/includes em Linux).

Instalacao:

unzip claude-advpl-skill-v0.1.zip
cd claude-advpl-skill
bash install.sh    # Linux/Mac/Git Bash
# ou
.\install.ps1     # Windows nativo

Pronto. Abre uma nova sessao do Claude Code e usa /advpl-validate seu-fonte.prw ou /advpl-compile seu-fonte.prw.

Pra baixar

Coloquei a v0.1 num link unico com formulario rapido — eu queria saber quem esta usando pra evoluir as proximas versoes em direcao ao que voce precisa, nao ao que eu acho legal. Email corporativo, empresa, cargo. Sem spam — o opt-in de marketing e opcional e cobre so updates de skills novas e posts tecnicos.

→ Baixar a claude-advpl-skill v0.1

Codigo no GitHub esta sendo organizado pra publicacao — em breve link direto. Por enquanto: ZIP no link acima.

O caminho daqui

Eu acredito firmemente que o futuro do dev Protheus brasileiro nao e abandonar AdvPL/TLPP. E ter ferramentas decentes ao redor do AdvPL/TLPP — IA pra revisar, validar, refatorar; CLI pra automatizar; IDE moderna pra editar; pipeline pra integrar. A TOTVS finalmente abriu o motor com o tds-ls open source. A comunidade tem que correr atras de empacotar o resto.

Se voce e dev Protheus e quer testar, baixa. Se tiver bug, abre issue. Se quer feature nova, manda PR. Se quer ajuda pra implementar algo do roadmap, me chama.

O resto a gente faz junto.