/advpl-specialist:generate

Gera novo codigo ADVPL ou TLPP seguindo as convencoes e boas praticas do Protheus.

Uso

/advpl-specialist:generate <type> [name] [--module <module>]

Tipos

Opcoes

Namespace TLPP (obrigatorio para arquivos .tlpp): todo arquivo .tlpp gerado declara uma linha namespace custom.<agrupador>.<servico> logo apos os includes. O gerador deriva o namespace de --module (como agrupador) mais o nome do servico/classe (como servico), tudo em lowercase e sem underscores. Se --module nao for fornecido, o gerador pergunta ao usuario o agrupador durante a Fase de Planejamento.

Processo

OBRIGATORIO: Sempre entra em modo de planejamento antes de gerar codigo. Nunca pula o planejamento.

Sem Varredura de Fontes do Projeto (CRITICO)

NAO varre os arquivos-fonte do projeto do cliente. O plugin e baseado em templates — todo o codigo e gerado a partir dos templates e skills do proprio plugin. Ler arquivos .prw / .tlpp / .prx existentes do projeto do cliente nao e necessario para nenhum cenario de /generate e deve ser evitado porque:

• Projetos Protheus rotineiramente possuem milhares de arquivos-fonte — varre-los e proibitivamente lento e desperdica o tempo do usuario
• O codigo gerado vem dos templates do plugin, nao do codigo-base do cliente
• Convencoes de nomenclatura, estilo e padroes vem da skill (advpl-code-generation), nao de arquivos existentes
• O chamador ja fornece tudo que o gerador precisa: type, name, --module, requisitos de negocio

Usos permitidos de Read / Glob / Grep:

• Leitura de arquivos dentro do proprio plugin — skills/*, templates-*.md, patterns-*.md, agents/code-generator.md
• Write do arquivo .prw / .tlpp final gerado em disco
• Read de um arquivo especifico que o usuario referenciou explicitamente em sua solicitacao (arquivo unico, caminho exato fornecido pelo usuario)

Usos proibidos:

• Glob "**/*.prw", Glob "**/*.tlpp", Glob "src/**/*" — nunca lista arquivos-fonte do cliente
• Grep na arvore de fontes do cliente para "encontrar padroes" ou "checar nomenclatura existente"
• Read de arquivos-fonte do cliente "para entender o codigo-base" — os templates sao auto-suficientes
• Bash ls, Bash find, Bash tree na raiz do projeto do cliente — mesma proibicao

Regra do caminho de saida: Salva o arquivo gerado no diretorio de trabalho atual usando <nome>.<ext> (ou no caminho passado via --output). Nunca usa Glob para descobrir pastas de modulo, nunca "adivinha" o local correto varrendo. Se o usuario tem uma localizacao preferida, ou ele passa --output ou o gerador faz uma pergunta direta.

Unica excecao: O usuario referencia explicitamente um arquivo existente em sua solicitacao (ex.: "gere um REST similar ao que esta em src/fontes/FATA001.prw"). Nesse caso, Read e permitido somente no caminho exato fornecido pelo usuario — nunca expandido para uma varredura completa do projeto.

Fase de Planejamento (OBRIGATORIA)

1. Analisar argumentos - Extrair tipo, nome e flags
2. Pedir detalhes faltantes - Se nome ou modulo nao foram fornecidos, perguntar ao usuario. Para geracao TLPP (saida .tlpp), tambem coleta o agrupador de namespace: se --module <agrupador> for fornecido, infere namespace custom.<agrupador>.<servico> automaticamente; se --module estiver ausente, pergunta ao usuario explicitamente o agrupador antes de entrar em modo de planejamento. Nunca omite o namespace silenciosamente e nunca inventa um padrao. 2a. Validar tamanho do identificador (BLOQUEANTE) - Calcula len(name) e compara com o limite efetivo para a linguagem/construcao escolhida: User Function em .prw deve ter ≤ 8 chars, Static Function em .prw deve ter ≤ 10 chars, TLPP com namespace aceita ate 255 chars. Se o nome exceder o limite, NAO entra em modo de planejamento. Apresenta ao usuario duas opcoes explicitas e aguarda a escolha:
   • (A) Encurtar o nome — sugere 2-3 alternativas seguindo convencoes Protheus (prefixo de modulo + sequencia como FATA100, abreviacao mnemonica, ou abreviacao funcional). Nunca oferece truncamentos aleatorios.
   • (B) Mudar para TLPP com namespace — explica que TLPP com namespace suporta ate 255 chars (disponivel a partir do release 12.1.2410 do Protheus). Pede o agrupador (--module) se ausente. So prossegue para o proximo passo apos o usuario escolher (A) + nome encurtado, ou (B) + agrupador de namespace. Nunca gera codigo que dependa de longnameclass como workaround — TLPP com namespace e a alternativa moderna oficialmente suportada.
3. Pedir requisitos de negocio - O que o codigo deve fazer?
4. Carregar skill - Invocar skill advpl-code-generation
5. Carregar padroes - Ler arquivo de suporte apropriado para o tipo
6. Pesquisar TDN para pontos de entrada - Se o tipo for ponto-entrada, SEMPRE pesquisa o TDN (TOTVS Developer Network) pelo nome do ponto de entrada antes de gerar codigo. Usa WebSearch para encontrar a pagina de documentacao oficial (ex.: pesquisar por "NOME_PONTO_ENTRADA site:tdn.totvs.com"). Extrai da pagina do TDN: parametros PARAMIXB (tipos, posicoes, descricoes), tipo e valor de retorno esperado, qual rotina padrao chama esse ponto de entrada e quaisquer ressalvas ou comportamentos especificos de versao.
7. Entrar em modo de planejamento - Usar EnterPlanMode para criar um plano estruturado de implementacao
8. Apresentar plano - Mostrar ao usuario um plano claro incluindo:
   • Arquivo(s) a serem criados (nome, caminho, extensao)
   • Estrutura do codigo (funcoes, classes, metodos a implementar)
   • Declaracao explicita da palavra-chave da funcao a ser usada para cada funcao no plano: User Function (padrao para codigo chamavel pelo cliente), Static Function (helper interno), ou Method ... Class (classe TLPP). Nunca planeja uma palavra-chave Function pura para codigo de cliente — ela e reservada para o RPO core da TOTVS e nao compila em RPO de cliente.
   • Para cada arquivo .tlpp, a declaracao exata de namespace a ser emitida, seguindo a convencao custom.<agrupador>.<servico> (tudo em lowercase, com pontos como separadores, sem underscores). Mostra como uma linha literal (ex.: namespace custom.compras.purchase) derivada de --module + o nome do servico/classe. Se --module nao foi fornecido, isso deve ter sido resolvido no passo 2.
   • Resultado da verificacao de tamanho do identificador — confirma explicitamente no plano que cada nome de funcao/metodo cabe no limite efetivo da linguagem escolhida: User Function ≤ 8 chars (.prw), Static Function ≤ 10 chars (.prw), TLPP com namespace ≤ 255 chars. Se o nome foi encurtado no passo 2a, tambem menciona o nome original para rastreabilidade (ex.: FATA100 (encurtado de ProcessaValidacaoItens)).
   • Includes e dependencias
   • Padroes-chave a aplicar (MVC, REST, SOAP, etc.)
   • Convencoes de nomenclatura a seguir (notacao hungara, prefixo do modulo)
   • Tratamento de erros e padroes de operacao com banco de dados
   • Para pontos de entrada: Documentacao do TDN encontrada (parametros PARAMIXB, tipo de retorno, rotina chamadora)
   • Para endpoints REST (TLPP baseado em anotacoes): confirma que o plano usa User Function com anotacoes @Get/@Post/@Put/@Patch/@Delete, seguindo o sample oficial TOTVS totvs/tlpp-sample-rest/rest-mod02.tlpp. A variante baseada em classe (rest-mod03.tlpp) tambem e suportada — usa quando multiplos metodos compartilham estado. Ambas as variantes exigem a declaracao de namespace.
9. Aguardar aprovacao - O usuario deve aprovar o plano antes de qualquer codigo ser escrito. Se o usuario solicitar alteracoes, revisar o plano.
10. Sair do modo de planejamento - Usar ExitPlanMode apos aprovacao

Fase de Implementacao (somente apos aprovacao)

11. Gerar codigo - Criar codigo completo, pronto para producao, seguindo o plano aprovado
12. Gravar arquivo - Salvar com extensao correta (.prw ou .tlpp)
13. Relatar - Mostrar o que foi criado e decisoes-chave

Exemplos

# Criar uma User Function para o modulo de faturamento
/advpl-specialist:generate function FATA050 --module FAT

# Criar uma classe de servico TLPP
/advpl-specialist:generate class PedidoService

# Criar CRUD MVC completo
/advpl-specialist:generate mvc CadProduto --module EST

# Criar um endpoint de API REST
/advpl-specialist:generate rest ClienteAPI --lang tlpp

# Criar um ponto de entrada
/advpl-specialist:generate ponto-entrada MT100LOK

# Criar um Web Service SOAP
/advpl-specialist:generate webservice WSPedido

# Criar um relatorio TReport
/advpl-specialist:generate treport RelProdutos --module EST

# Criar uma tela FWFormBrowse
/advpl-specialist:generate fwformbrowse CadFornecedores --module COM

# Criar um job de processamento em lote
/advpl-specialist:generate job JobProcessaNotas --module FAT

# Criar um workflow de aprovacao
/advpl-specialist:generate workflow AprovacaoPedido --module COM

Saida

Um arquivo-fonte completo e compilavel salvo no diretorio do projeto com:

• Cabecalho de documentacao Protheus.doc
• Includes apropriados (TOTVS.CH para .prw, tlpp-core.th / tlpp-rest.th para .tlpp)
• Linha obrigatoria namespace custom.<agrupador>.<servico> para cada arquivo .tlpp gerado
• Implementacao completa seguindo convencoes
• Tratamento de erros
• Save/restore de area para operacoes com banco de dados