`/plugadvpl:compile`

/plugadvpl:compile

🤖 Para o agente: este skill tem um workflow obrigatório de 4 passos. NUNCA tente compilar direto. Sempre rode --doctor primeiro.

Se o usuário não sabe o que precisa fornecer, aponte pra docs/compile-checklist.md — explica os 5 dados (advpls, includes, host/port, build/env, credenciais) que ele precisa reunir, com instruções de onde achar cada um.

Workflow obrigatório

Passo 1 — Diagnóstico (sempre primeiro)

plugadvpl --format json compile --doctor

Output traz status (ready | needs_setup) e next_actions (lista ordenada do que falta).

Passo 2 — Se needs_setup: processar cada next_action

Para cada item em next_actions, agir conforme action:

set_advpls_binary

Caminho preferido: orientar o user a rodar:

plugadvpl compile --install-advpls

Comando interativo que pergunta "copiar de local existente" ou "baixar do Marketplace", mostra plano (tamanho, paths, se precisa rede) + pede confirmação antes de cada ação. Instala em ~/.plugadvpl/advpls/bin/<os>/ — --doctor detecta automaticamente nas próximas chamadas. Não precisa configurar nada após --install-advpls.

Se o user quiser fazer manual:

• Path de advpls existente → export PLUGADVPL_ADVPLS_BINARY=<path> ou editar [tds_ls].binary no runtime.toml
• Baixar manual → instruções em docs/compile-checklist.md §1

set_includes

• Se candidates não-vazio: mostre ao usuário ("Detectei estas pastas com PRTOPDEF.CH e protheus.ch, qual usar?")
• Se vazio: peça o path da pasta Include/ Protheus. Se usuário não tem (sem AppServer/SDK), informe que --mode appre não funciona — apenas --mode cli (que compila no AppServer remoto)
• Salvar: passar via --includes <path> nas próximas execuções OU editar [compile].includes = ["<path>"] no runtime.toml

create_runtime_toml

• CAMINHO PREFERIDO (se já há servers cadastrados ou TDS-VSCode disponível): use --use-server <nome> em vez de criar runtime.toml. Mais rápido e cobre múltiplos AppServers (dev/hml/prod) sem editar arquivo a cada compilação.
• Rode: plugadvpl compile --init-config
• Edite <root>/.plugadvpl/runtime.toml preenchendo:
  • [tds_ls].binary — path do advpls
  • [appserver] — host, port, build, environment do AppServer alvo
  • [auth] — user_env/password_env (nome das env vars, NUNCA valor)
  • [compile].includes — pasta com includes
• Mostre o conteúdo final ao usuário pra confirmação ANTES de gravar

use_server

• PREFERIDO sobre create_runtime_toml quando user já tem servers cadastrados.
• candidates = nomes de servers já registrados em ~/.plugadvpl/servers.json
• Mostre lista, pergunte qual usar
• Comando: plugadvpl compile --use-server <nome> --mode cli <fonte.prw>
• User pode também especificar environment alternativo: --use-environment TEST

import_tds_servers

• Aparece quando ~/.totvsls/servers.json (TDS-VSCode) existe mas registry plugadvpl está vazio
• Comando: plugadvpl compile --import-tds-servers (interativo, pede confirmação)
• Lê servers do TDS-VSCode + adiciona ao registry plugadvpl
• Depois usa --use-server <nome> normalmente

set_env_var

• Se secret: true (PROTHEUS_PASS): NUNCA logue valor. Oriente:

  $env:PROTHEUS_PASS = "<sua-senha>"   # PowerShell
  export PROTHEUS_PASS='<sua-senha>'   # bash
  

• Se secret: false (PROTHEUS_USER): pode pedir valor direto ao user
• Em CI use secrets (GitHub Actions / GitLab CI variables)

start_appserver

• Não temos controle programático. Informe ao usuário:
  • Local: iniciar appserver.exe na pasta Protheus
  • Remoto: subir SSH tunnel ssh -L 1234:localhost:1234 user@host -N + host = "127.0.0.1" no runtime.toml

Passo 3 — Re-rodar --doctor até status = "ready"

plugadvpl --format json compile --doctor

Loop: cada vez que resolver um next_action, re-rode pra confirmar e ver se sobrou mais alguma coisa.

Passo 4 — Compilar

Quando status: "ready", o mode_supported diz quais modos funcionam:

• Só appre (sem AppServer): plugadvpl compile --mode appre --includes <pasta> FONTE.PRW
• Inclui cli: pode escolher --mode cli (full compile semântico) ou --mode appre (rápido)

Convenção crítica: flags --xxx SEMPRE antes do nome do arquivo (positional variadic).

# ✅ Certo
plugadvpl --format json compile --mode appre --includes "D:\Protheus\Include" MEUFONTE.PRW

# ❌ Errado (typer consome --mode como nome de arquivo)
plugadvpl compile MEUFONTE.PRW --mode appre

Quando NÃO usar este skill

• Para entender erros de lint (não-compile): use /plugadvpl:lint
• Para visão arquitetural ANTES de compilar: /plugadvpl:arch <arquivo>
• Para descobrir quem chama uma função: /plugadvpl:callers <funcao>

Schema do output de compile (não --doctor)

{
  "rows": [
    {"arquivo", "ok", "mode", "duration_ms", "exit_code",
     "counts": {"error", "warning", "info", "unknown"},
     "diagnostics": [{"severidade", "arquivo", "linha", "coluna",
                      "mensagem", "codigo", "raw"}]}
  ],
  "next_steps": [...]
}

Bucket __unmatched__ aparece se advpls reportar arquivo fora do requested_files.

Exit codes

• 0 — sucesso (zero errors)
• 1 — error parseado OU subprocess falhou
• 2 — config/setup inválido OU --doctor retornou needs_setup
• 130 — Ctrl-C (POSIX SIGINT)

Modos — limitações importantes

Modo	Pega	NÃO pega
appre	sintaxe básica, #include faltando, macro inválida, define duplicado	erros semânticos (If sem EndIf, tipo incompatível, função inexistente)
cli	tudo (pré-processador + semântica + binding) — full compile	nada relevante

Pra usuário aprender ADVPL via plugin, appre já entrega 60% do valor (C2090/C2006/C2090 família). Pra CI rigoroso, exigir cli.

Documentação completa

docs/setup-compile.md — guia passo-a-passo de instalação (binário, includes, AppServer, CI YAML pronto, SSH tunnel, 6 troubleshooting comuns).