@netoalmanca/advpl-sensei 1.1.2 → 1.1.5

package/commands/entrypoint.md

@@ -0,0 +1,26 @@
+---
+description: Busca informações técnicas detalhadas sobre um Entry Point (Ponto de Entrada) diretamente no TDN da TOTVS
+parameters:
+  name:
+    type: string
+    description: "Nome do Entry Point (ex: MT100LOK, MATA010, etc.)"
+---
+
+# /advpl-sensei:entrypoint
+
+Busca a documentação oficial do Entry Point no TOTVS Developer Network (TDN) e retorna os parâmetros `PARAMIXB`, tipos de retorno e rotinas envolvidas.
+
+## O que esta ferramenta retorna:
+
+- **PARAMIXB**: Lista detalhada de todos os parâmetros recebidos.
+- **Return Type**: Qual o tipo de retorno esperado pelo sistema.
+- **Routine**: Qual programa padrão aciona este ponto de entrada.
+- **URL**: Link oficial para conferência.
+
+## Uso
+
+```bash
+/advpl-sensei:entrypoint MT100LOK
+```
+
+Esta ferramenta é essencial antes de gerar código para pontos de entrada, garantindo que a assinatura da função esteja correta de acordo com a versão atual do Protheus.

package/commands/lint.md

@@ -0,0 +1,27 @@
+---
+description: Valida o código ADVPL/TLPP seguindo as regras de ouro do Sensei (Locals no topo, Notação Húngara, sem Privates)
+parameters:
+  source:
+    type: string
+    description: "Código fonte ADVPL/TLPP para validar"
+  filename:
+    type: string
+    description: "Nome do arquivo (opcional)"
+    required: false
+---
+
+# /advpl-sensei:lint
+
+Valida o código fonte fornecido contra as regras de ouro do Advpl Sensei.
+
+## Regras Verificadas
+
+| Código | Regra | Severidade |
+|--------|-------|------------|
+| `L001` | Variáveis `Local` no topo da função | Erro |
+| `L002` | Proibido uso de `Private` ou `Public` | Erro |
+| `L003` | Notação Húngara obrigatória | Aviso |
+
+## Uso
+
+Forneça o código fonte completo ou parcial para análise.

package/commands/snippets.md

@@ -0,0 +1,207 @@
+---
+name: Snippets Generator
+description: Gera snippets VS Code baseado nas regras de ouro do Sensei. Facilita a escrita de código ADVPL/TLPP seguindo os padrões.
+parameters:
+  action:
+    type: string
+    description: "Ação a executar: list, generate_vscode, export_json, export_markdown"
+    required: true
+  output:
+    type: string
+    description: "Caminho de saída para o arquivo de snippets (opcional)"
+    required: false
+  outputDir:
+    type: string
+    description: "Diretório para salvar o arquivo (padrão: diretório atual)"
+    required: false
+---
+
+# Snippets Generator - Templates para VS Code
+
+Gerador de snippets VS Code que facilitam a escrita de código ADVPL/TLPP seguindo as regras de ouro do Sensei.
+
+## Funcionalidades
+
+### 1. **list** - Lista todos os snippets disponíveis
+Exibe todos os snippets com seus prefixos e descrições
+
+**Exemplo:**
+```
+action: list
+```
+
+**Snippets Disponíveis:**
+
+- `advpl_func` - Função ADVPL com estrutura padrão
+- `advpl_func_array` - Função que retorna array
+- `tlpp_class` - Classe TLPP com namespaces
+- `advpl_report` - Report com Pergunte() para parâmetros
+- `advpl_rest` - REST API ADVPL
+- `advpl_validation` - Função de validação
+- `advpl_mvc` - Estrutura MVC
+- `advpl_job` - Job de processamento
+- `advpl_try_catch` - Begin Sequence/Except padrão
+- `advpl_db_select` - Acesso seguro a área de dados
+
+### 2. **generate_vscode** - Gera arquivo de snippets para VS Code
+Cria o arquivo `.code-snippets` na estrutura do projeto
+
+**Exemplo:**
+```
+action: generate_vscode
+output: .vscode/advpl-sensei.code-snippets
+outputDir: /path/to/project
+```
+
+Resultado: Cria arquivo JSON pronto para usar como snippets globais do VS Code
+
+### 3. **export_json** - Exporta snippets em JSON
+Exporta todos os snippets em formato JSON
+
+**Exemplo:**
+```
+action: export_json
+```
+
+### 4. **export_markdown** - Exporta referência em Markdown
+Gera documentação Markdown com todos os snippets
+
+**Exemplo:**
+```
+action: export_markdown
+```
+
+## Estrutura dos Snippets
+
+Todos os snippets seguem estas regras de ouro do Sensei:
+
+✅ **Includes corretos** - `#Include "TOTVS.CH"` e `#Include "PROTHEUS.CH"`
+✅ **Protheus.doc header** - Documentação padrão
+✅ **Begin Sequence com tratamento de erro** - Tratamento de exceções
+✅ **Locals no topo** - Variáveis declaradas corretamente
+✅ **Notação Húngara** - Nomenclatura de variáveis
+✅ **RestArea** - Preservação de área de dados
+
+## Exemplos de Uso
+
+### Snippet: `advpl_func`
+Função completa com estrutura padrão
+
+```advpl
+#Include "TOTVS.CH"
+#Include "PROTHEUS.CH"
+
+/*/{Protheus.doc} NomeFuncao
+Descrição breve da função
+@type function
+@author Seu Nome
+@since Data
+@version 1.0
+/*/
+User Function NomeFuncao()
+    // Declarações de variáveis locais
+    Local nRetorno := 0
+    Local cMsg := ""
+    Local aArea := GetArea()
+
+    Begin Sequence
+        // Lógica da função aqui
+        
+    Except
+        cMsg := "Erro em NomeFuncao: " + AllTrim(OldNotation(GetErrorMessage(GetException())))
+        ConOut(cMsg)
+        nRetorno := 0
+
+    End Sequence
+
+    RestArea(aArea)
+Return nRetorno
+```
+
+### Snippet: `tlpp_class`
+Classe TLPP com namespace e métodos
+
+```tlpp
+#Include "TOTVS.CH"
+#Include "PROTHEUS.CH"
+
+Namespace NomeNamespace
+
+/*/{Protheus.doc} NomeClasse
+Descrição da classe
+@type class
+@author Seu Nome
+@since Data
+@version 1.0
+/*/
+Class NomeClasse
+    Data cPropriedade := ""
+    Data nValor := 0
+    
+    Method New() Constructor
+    Method Execute() As Logical
+EndClass
+
+Method New() Class NomeClasse
+    ::cPropriedade := ""
+    ::nValor := 0
+Return Self
+
+Method Execute() As Logical Class NomeClasse
+    Local lRetorno := .T.
+    Local cMsg := ""
+
+    Begin Sequence
+        // Implementação aqui
+        
+    Except
+        cMsg := "Erro em Execute: " + AllTrim(OldNotation(GetErrorMessage(GetException())))
+        ConOut(cMsg)
+        lRetorno := .F.
+
+    End Sequence
+
+Return lRetorno
+
+EndClass
+
+End Namespace
+```
+
+## Como Usar no VS Code
+
+### 1. **Gerar e instalar os snippets**
+```
+Ação: generate_vscode
+Output: .vscode/advpl-sensei.code-snippets
+```
+
+### 2. **Usar um snippet**
+- Abra um arquivo `.prw` ou `.tlpp`
+- Digite o prefixo (ex: `advpl_func`)
+- Pressione Tab ou Enter para expandir
+- Preencha os placeholders (${1:texto}, ${2:texto}, etc)
+
+### 3. **Exemplo prático**
+1. Digite `advpl_func` e pressione Tab
+2. VS Code expande para a estrutura completa
+3. Seu nome fica destacado para preenchimento
+4. Pressione Tab para ir para próximo placeholder
+5. Continue até completar todos os campos
+
+## Benefícios
+
+✨ **Consistência** - Garante uso das regras de ouro em todo projeto
+📝 **Agilidade** - Economiza tempo na escrita de boilerplate
+🎓 **Educação** - Demonstra padrões corretos para novos desenvolvedores
+🔍 **Rastreabilidade** - Facilita análise e linting de código
+
+## Customização
+
+Para adicionar novos snippets ou modificar existentes:
+
+1. Mantenha a estrutura de Begin Sequence...Except
+2. Use Notação Húngara em variáveis
+3. Inclua Protheus.doc header
+4. Adicione RestArea para preservar área de dados
+5. Siga as convenções de naming do Sensei

package/commands/sx.md

@@ -0,0 +1,110 @@
+---
+name: SX Tool
+description: Consulta estruturada ao dicionário Protheus (SX tables). Busque tabelas, campos, parâmetros do sistema e tabelas genéricas.
+parameters:
+  action:
+    type: string
+    description: "Ação a executar: list_tables, get_table, search_fields, get_parameters, get_generic_table, export"
+    required: true
+  query:
+    type: string
+    description: "Parâmetro da consulta (nome da tabela, padrão de busca, código de parâmetro, etc)"
+    required: false
+  format:
+    type: string
+    description: "Formato de resposta: markdown ou json (padrão: markdown)"
+    required: false
+---
+
+# SX Tool - Consulta ao Dicionário Protheus
+
+Ferramenta especializada em fornecer acesso rápido e estruturado ao dicionário de dados Protheus (tabelas SX).
+
+## Funcionalidades
+
+### 1. **list_tables** - Lista todas as tabelas
+Exibe todas as tabelas disponíveis com suas descrições
+
+**Exemplo de uso:**
+```
+action: list_tables
+```
+
+### 2. **get_table** - Obtém detalhes de uma tabela
+Retorna a estrutura completa de uma tabela com todos os campos
+
+**Exemplo de uso:**
+```
+action: get_table
+query: SA1
+```
+
+### 3. **search_fields** - Busca campos por padrão
+Busca campos em uma tabela usando wildcards (*)
+
+**Exemplo de uso:**
+```
+action: search_fields
+query: SA1|*COD
+```
+Busca todos os campos contendo "COD" na tabela SA1
+
+### 4. **get_parameters** - Lista parâmetros do sistema
+Retorna parâmetros MV_* organizados por módulo
+
+**Exemplo de uso:**
+```
+action: get_parameters
+query: Financeiro
+```
+
+### 5. **get_generic_table** - Consulta tabelas genéricas (SX5)
+Retorna valores de uma tabela genérica com códigos e descrições
+
+**Exemplo de uso:**
+```
+action: get_generic_table
+query: 13
+```
+
+### 6. **export** - Exporta dados em JSON
+Exporta os dados do dicionário em formato JSON
+
+**Exemplo de uso:**
+```
+action: export
+query: tables
+```
+
+## Tabelas Disponíveis para Consulta
+
+- **SA1** - Clientes
+- **SA3** - Vendedores
+- **SC5** - Pedidos de Vendas
+- **SX3** - Dicionário de Campos
+
+## Tabelas Genéricas (SX5)
+
+- **01** - Condições de Pagamento
+- **13** - Estados/Províncias
+- **AB** - Possíveis UF
+
+## Parâmetros por Módulo
+
+- Geral: MV_ESTADO
+- Financeiro: MV_MOEDA1, MV_JUROS, MV_MULTA
+- Faturamento: MV_USARFT
+
+## Exemplo de Fluxo
+
+1. Usuário: "Quais são os campos da tabela SA1?"
+   - SX Tool executa: `get_table | SA1`
+   - Retorna estrutura completa com tipos, tamanhos e descrições
+
+2. Usuário: "Como validar um estado?"
+   - SX Tool executa: `get_generic_table | 13`
+   - Retorna lista de estados válidos
+
+3. Usuário: "Qual é a taxa de juros padrão?"
+   - SX Tool executa: `get_parameters | Financeiro`
+   - Retorna valor do parâmetro MV_JUROS

package/commands/validate-tdn.md

@@ -0,0 +1,202 @@
+---
+name: validate-tdn
+description: Valida código ADVPL/TLPP ou funções individuais contra TDN (TOTVS Developer Network). Detecta funções fictícias, incompatibilidades de linguagem e cobertura TDN.
+parameters:
+  code:
+    type: string
+    required: false
+    description: "Código ADVPL/TLPP a validar. Análise de funções usadas. Exemplo: 'Local x := Upper(\"test\")'"
+  function:
+    type: string
+    required: false
+    description: "Nome de função individual a validar. Exemplo: 'DbSeek'"
+  language:
+    type: string
+    required: false
+    description: "Linguagem do código. Valores: 'advpl', 'tlpp', 'both'. Padrão: 'advpl'"
+    enum: ["advpl", "tlpp", "both"]
+  filename:
+    type: string
+    required: false
+    description: "Nome do arquivo para contexto. Exemplo: 'meu-programa.prw'. Padrão: 'code.prw'"
+  detailed:
+    type: boolean
+    required: false
+    description: "Se true, retorna detalhes completos incluindo sugestões. Padrão: false"
+  forceRefresh:
+    type: boolean
+    required: false
+    description: "Se true, busca dados TDN atualizados (ignora cache de 24h). Padrão: false"
+---
+
+# Validação TDN - Comando ADVPL Sensei
+
+## Descrição
+
+Valida código ADVPL/TLPP ou funções individuais contra o banco de dados de funções TDN (TOTVS Developer Network).
+
+**Funcionalidades:**
+- ✅ Validação de funções contra TDN
+- ✅ Detecção automática de funções fictícias
+- ✅ Verificação de compatibilidade ADVPL/TLPP
+- ✅ Relatórios formatados com severity
+- ✅ Cache inteligente de 24 horas
+- ✅ Sugestões de correção
+
+## Uso
+
+### Validar Função Individual
+
+```
+advpl_validate_tdn function="DbSeek" language="advpl"
+```
+
+**Resultado:**
+```
+✅ Status: VALID
+📝 Message: Function 'DbSeek' verified in TDN ✅
+⚠️  Severity: info
+```
+
+### Validar Bloco de Código
+
+```
+advpl_validate_tdn code="Local x := Upper('hello')" language="advpl"
+```
+
+**Resultado:**
+```
+✅ No issues found - Code is valid!
+
+🎯 TDN Coverage: 100%
+📊 Functions Found: 0 (none to validate)
+```
+
+### Validar com Detalhes
+
+```
+advpl_validate_tdn code="Local y := FakeFunc()" language="advpl" detailed=true
+```
+
+**Resultado mostrará:**
+- Informações completas sobre funções
+- Sugestões de correção
+- Links para documentação TDN
+
+## Fases
+
+- **Phase 6:** TdnFunctionValidator criado (base)
+- **Phase 8:** Integração com snippets (validação de código)
+- **Phase 9:** TdnFunctionScraper (76 funções catalogadas)
+- **Phase 10:**  `advpl_validate_tdn` command (NEW)
+
+## TDN Coverage
+
+**76 funções verificadas em 9 categorias:**
+
+| Categoria | Funções | Exemplos |
+|-----------|---------|----------|
+| Database | 20 | DbSeek, DbSkip, Eof, GetArea, RestArea |
+| Type | 17 | Val, Str, Date, Empty, Int, Round |
+| String | 13 | Upper, Lower, SubStr, StrTran, Len |
+| Math | 6 | Min, Max, Mod, Sqrt, Exp, Log |
+| Array | 6 | AClone, AAdd, ADel, ASize, AScan, ASort |
+| Date | 4 | Month, Year, Day, Time |
+| Parameters | 4 | GetMV, GetSX3, GetSX5, PutMV |
+| Interface | 3 | Alert, MsgBox, ConOut |
+| Framework | 3 | GetException, GetErrorMessage, OldNotation |
+
+## Exemplos
+
+### Exemplo 1: Detectar Ficção
+
+```
+advpl_validate_tdn code="oServer := HttpServer():New()"
+```
+
+Resultado: **❌ HttpServer is fictitious** (não existe em TDN)
+
+### Exemplo 2: Compatibilidade ADVPL/TLPP
+
+```
+advpl_validate_tdn code="DbSeek(...)" language="tlpp"
+```
+
+Resultado: **⚠️ Incompatibility** (DbSeek é ADVPL-only)
+
+### Exemplo 3: Validação Completa
+
+```
+advpl_validate_tdn code="
+Local aArea := GetArea()
+DbSeek(cCodigo)
+If !Eof()
+  RecLock()
+  ...
+  RestArea(aArea)
+EndIf
+" language="advpl" detailed=true
+```
+
+Resultado: **✅ All functions verified**
+
+## Fluxo de Validação
+
+```
+1. Code Input
+   ↓
+2. Parse Functions
+   ↓
+3. Check against TdnFunctionValidator
+   ↓
+4. Verify with TdnFunctionScraper (76 functions)
+   ↓
+5. Check Registry (78 functions)
+   ↓
+6. Generate Report with Severity
+```
+
+## Relatórios
+
+### Formato: Problema Encontrado
+
+```
+⚠️  Issues Found: 2
+
+🔴 TDN Validation Issues:
+
+  ERRORS (1):
+    • HttpServer: Function 'HttpServer' is fictitious or deprecated
+
+  WARNINGS (0):
+
+🟡 Structure Validation Issues:
+  • [ERROR] Missing return statement
+```
+
+### Formato: Sem Problemas
+
+```
+✅ No issues found - Code is valid!
+
+🎯 TDN Coverage: 100%
+📊 Functions Found: 0 (none to validate)
+```
+
+## Cache
+
+- **Duração:** 24 horas
+- **Bypass:** Use `forceRefresh=true`
+- **Rastreamento:** Campo `"Cache Hit"` no relatório
+
+## Próximas Melhorias
+
+- [ ] Web scraper real de TDN
+- [ ] Persistência de cache em arquivo
+- [ ] Integração com IDE real
+- [ ] Análise de padrões de uso
+
+---
+
+**Versão:** Phase 10 - MCP Integration  
+**Status:** ✅ Production Ready