Skip to content

JoniPraia/plugadvpl

BranchesTags

Repository files navigation

plugadvpl

PyPI version Python License: MIT CI PyPI downloads GitHub stars

Plugin Claude Code + CLI Python que indexa fontes ADVPL/TLPP (TOTVS Protheus) em SQLite com FTS5 — para o Claude responder sobre o seu Protheus sem queimar contexto lendo .prw cru.

Por que plugadvpl

  • Economia de tokens. Um .prw médio tem 1.000 a 10.000 linhas. Abrir cru custa de 5k a 50k tokens. Com plugadvpl, a mesma pergunta é respondida via metadados estruturados — ~16× menos contexto em projetos reais.
  • Parser provado em campo. O extrator de funções, tabelas, SQL embarcado e call graph foi portado de um parser interno do autor, validado em aproximadamente 2.000 fontes ADVPL. Não é um experimento de fim de semana.
  • MIT, sem telemetria, 100% local. Índice SQLite mora em .plugadvpl/index.db dentro do seu repo. Nenhum dado sai da máquina. Funciona offline.

Demonstração

Cenário sem plugin — pergunta: "explique a função FATA050":

Claude → Read FATA050.prw            # arquivo inteiro
       → ~12.000 tokens consumidos
       → resposta vaga, sem call graph, sem saber quem usa

Cenário com plugadvpl:

Claude → /plugadvpl:arch FATA050.prw   # capabilities, tabelas, funções, includes
       → /plugadvpl:callers FATA050    # quem chama
       → Read FATA050.prw offset=234 limit=46   # range exato, só se preciso
       → ~730 tokens consumidos       (≈ 16× menor)
       → resposta com contexto: módulo, MVC, tabelas SA1/SC5, PE relacionado

Instalação rápida (one-liner)

Windows (PowerShell):

irm https://raw.githubusercontent.com/JoniPraia/plugadvpl/main/scripts/install.ps1 | iex

macOS / Linux:

curl -sSL https://raw.githubusercontent.com/JoniPraia/plugadvpl/main/scripts/install.sh | sh

O script:

  1. Instala uv (gerenciador de pacotes Python da Astral) se ainda não estiver presente
  2. Instala plugadvpl globalmente via uv tool install
  3. Imprime próximos passos

Depois é só:

cd <pasta-do-seu-projeto-Protheus>
plugadvpl init
plugadvpl ingest
plugadvpl status

Se você prefere usar o plugin via Claude Code (slash commands), instale o marketplace e use /plugadvpl:setup que faz tudo automaticamente (ver "Plugin Claude Code" abaixo).

Atualizando para uma versão nova

A forma simples — funciona em qualquer plataforma — é rodar o one-liner de instalação de novo. Ele detecta uv ausente, instala se preciso, e reinstala plugadvpl apontando para a versão atual do PyPI.

Windows (PowerShell):

irm https://raw.githubusercontent.com/JoniPraia/plugadvpl/main/scripts/install.ps1 | iex

macOS / Linux:

curl -sSL https://raw.githubusercontent.com/JoniPraia/plugadvpl/main/scripts/install.sh | sh

Se já tem uv e quer só forçar pull da versão nova (uv às vezes segura cache):

uv cache clean plugadvpl
uv tool install plugadvpl --reinstall --force
plugadvpl version

O plugin Claude Code é separado da CLI

CLI (plugadvpl, Python) e plugin Claude Code (skills + agents + hook) são duas coisas que se atualizam separadamente. Atualizar uma não toca na outra.

Pra atualizar o plugin:

/plugin marketplace update plugadvpl-marketplace

(no Claude Code CLI; na extensão VSCode use a UI /plugin).

Se algo travar (uv sumiu, plugin atualiza mas slash command parece velho, cache de uvx segurando versão antiga), veja Troubleshooting de atualização no FAQ.

Quick start

# 1. Pré-requisito: uv (gerenciador Python rápido)
winget install astral-sh.uv                              # Windows
# OU: curl -LsSf https://astral.sh/uv/install.sh | sh    # Linux/macOS

# 2. Instale o plugin Claude Code — veja seção abaixo
#    (caminho varia entre CLI nativo e extensão VSCode)

# 3. Abra o seu projeto Protheus e rode:
/plugadvpl:init      # cria .plugadvpl/index.db, fragment CLAUDE.md, .gitignore
/plugadvpl:ingest    # parser paralelo, ~30–60s para 2.000 fontes

Pronto. A partir daqui o Claude já consulta o índice antes de abrir qualquer .prw. Para inspecionar você mesmo:

/plugadvpl:arch FATA050.prw         # visão arquitetural (inclui tabelas via ExecAuto)
/plugadvpl:callers MaFisRef         # quem chama essa função
/plugadvpl:tables SA1               # quem lê/grava/reclock na SA1
/plugadvpl:param MV_LOCALIZA        # onde esse parâmetro é usado
/plugadvpl:lint --severity error    # encontrar problemas críticos
/plugadvpl:impacto A1_COD           # cruza referências a um campo (Universo 2)
/plugadvpl:workflow --kind job_standalone  # jobs daemon do projeto (Universo 3)
/plugadvpl:execauto --routine MATA410 --op inc  # quem inclui Pedido de Venda
/plugadvpl:docs --show MT460FIM     # doc completa em Markdown sem abrir o fonte

Instalando o plugin Claude Code (opcional, para slash commands)

Além da CLI, o plugadvpl também é um plugin Claude Code que adiciona:

  • Slash commands /plugadvpl:arch, /plugadvpl:find, /plugadvpl:callers, etc.
  • 15 knowledge skills temáticas que Claude carrega automaticamente (advpl-mvc, advpl-tlpp, advpl-pontos-entrada, etc.)
  • Hook SessionStart que detecta projetos ADVPL e sugere /plugadvpl:init
  • 4 subagents especializados (analyzer, impact-analyzer, code-generator, reviewer-bot)

A forma de instalar depende de onde você usa o Claude Code:

Opção A — Claude Code CLI (terminal claude)

No chat do CLI:

/plugin marketplace add https://github.com/JoniPraia/plugadvpl.git
/plugin install plugadvpl

Aceite o trust dialog. Pronto.

Opção B — Extensão VSCode do Claude Code

A extensão não suporta /plugin install direto no chat (limitação oficial do Claude Code). Use a UI:

  1. No chat, digite /plugin (sem args) — abre o painel Manage Plugins Alternativa: Ctrl+Shift+P → "Claude Code: Manage Plugins"
  2. Aba Marketplaces → botão Add → cole https://github.com/JoniPraia/plugadvpl.git
  3. Aba Plugins → encontre plugadvpl → clique Install for you (user scope)
  4. Aceite o trust dialog

Reinicie o Claude Code para garantir que skills, hooks e slash commands carregam corretamente.

Verificação

Em qualquer caminho, no chat:

/plugadvpl:status

Se aparecer output com counters do índice, o plugin está instalado e funcionando.

Importante: O plugin precisa da CLI Python instalada também (uv tool install plugadvpl ou via Instalação rápida (one-liner)). O plugin é uma camada fina sobre a CLI — sem ela, os slash commands não funcionam.

Comandos disponíveis

O CLI Python expõe 21 subcomandos (a partir do v0.4.0), espelhados em slash commands do plugin Claude Code.

Universo 1 — Fontes (v0.1)

Comando Função
/plugadvpl:init Cria .plugadvpl/index.db, fragment em CLAUDE.md e entrada no .gitignore
/plugadvpl:ingest Escaneia e indexa todos os fontes (--workers N, --incremental, --no-content, --redact-secrets)
/plugadvpl:reindex <arq> Re-ingest de um arquivo (após edição manual)
/plugadvpl:status Versões, contadores, opcionalmente arquivos stale (--check-stale)
/plugadvpl:find <termo> Busca composta: função → arquivo → conteúdo (FTS)
/plugadvpl:callers <funcao> Quem chama a função (call graph reverso)
/plugadvpl:callees <funcao> O que a função chama (call graph direto)
/plugadvpl:tables <T> Quem usa a tabela T (--mode read/write/reclock)
/plugadvpl:param <MV> Onde o parâmetro MV_* aparece
/plugadvpl:arch <arq> Visão arquitetural — use SEMPRE antes de Read. Inclui tabelas_via_execauto_resolvidas (v0.4.1+)
/plugadvpl:lint [arq] Lint findings (--severity, --regra, --cross-file)
/plugadvpl:doctor Diagnósticos (encoding, órfãos, FTS sync, lookups)
/plugadvpl:grep <pattern> Busca textual nos chunks (--mode fts/literal/identifier)
/plugadvpl:help Lista comandos (atalho do CLI --help)

Universo 2 — Dicionário SX (v0.3)

Comando Função
/plugadvpl:ingest-sx <pasta-csv> Ingere dicionário SX exportado em CSV (sx1..sxg)
/plugadvpl:impacto <campo> Killer feature — cruza referências a um campo em fontes ↔ SX3 ↔ SX7 ↔ SX1 (--depth 1..3)
/plugadvpl:gatilho <campo> Cadeia de gatilhos SX7 origem → destino (--depth 1..3)
/plugadvpl:sx-status Counts por tabela do dicionário SX

Universo 3 — Rastreabilidade (v0.4)

Comando Função
/plugadvpl:workflow (v0.4.0) Lista os 4 mecanismos de execução não-direta: workflow/schedule/job_standalone/mail_send (filtros --kind/--target/--arquivo)
/plugadvpl:execauto (v0.4.1) Resolve MsExecAuto({|x,y,z| MATA410(x,y,z)}, ...) → rotina canônica + módulo + tabelas inferidas (filtros --routine/--modulo/--op/--dynamic)
/plugadvpl:docs [modulo] (v0.4.2) Catálogo de Protheus.doc agregado por módulo/autor/tipo. Modo --show <fn> em Markdown estruturado, --orphans cruza com BP-007

Reference completa: docs/cli-reference.md.

Skills incluídas

Além dos 21 command wrappers (1 por subcomando do CLI + help + setup), o plugin traz 18 knowledge skills carregadas pelo Claude conforme contexto:

Skill Quando carrega
plugadvpl-index-usage Skill-chefe — força consulta ao índice antes de qualquer Read em fonte ADVPL
advpl-fundamentals Notação húngara, naming, prefixos de módulo, 195 funções restritas
advpl-encoding cp1252 (.prw) vs utf-8 (.tlpp) — preserve-by-default
advpl-mvc MenuDef/ModelDef/ViewDef, hooks bCommit/bTudoOk, FWFormStruct
advpl-mvc-avancado Eventos MVC, validações cruzadas, FWMVCRotAuto
advpl-tlpp TLPP moderno — OO, namespaces, annotations
advpl-embedded-sql BeginSql/EndSql, TCQuery, %xfilial%, %notDel%, %table%
advpl-pontos-entrada User Function NOME(PARAMIXB), retorno via PARAMIXB[última]
advpl-webservice REST (WSRESTFUL, @Get/@Post) e SOAP (WSSERVICE/WSMETHOD)
advpl-web Interfaces web — Webex / HTML / WebExpress
advpl-jobs-rpc RpcSetEnv, StartJob, MsRunInThread, funções proibidas em job
advpl-matxfis Família fiscal (NF-e, SPED, ECF, REINF, integração SF2/SD2/SF3)
advpl-advanced Threads, IPC, debug, OO em profundidade
advpl-dicionario-sx Estrutura SX1/SX2/SX3/SX5/SX6/SX7/SIX/SXA/SXB (v0.2.0)
advpl-dicionario-sx-validacoes Expressões ADVPL embutidas em X3_VALID/INIT/WHEN/VLDUSER, X7_REGRA, X1_VALID, X6_VALID/INIT — guia pra análise de impacto (v0.3.0)
advpl-refactoring 6 padrões com before/after (DbSeek loop, Posicione repetido, IFs hardcoded, AxCadastro→MVC, string concat em loop, RecLock sem Begin Transaction) — usar quando o pedido for "melhorar"/"refatorar"/"está lento" (v0.3.3)
advpl-debugging Top 30 erros comuns em produção + métodos de debug (ConOut, MemoWrite, FwLogMsg, varInfo) — usar quando o usuário cola traceback do AppServer.log (v0.3.3)
advpl-code-review 24 regras BP/SEC/PERF/MOD — 13 single-file (v0.1) + 11 cross-file SX-001..SX-011 (v0.3.0)

Também incluídos: 4 agents especializados (advpl-analyzer, advpl-impact-analyzer, advpl-code-generator, advpl-reviewer-bot) e 1 SessionStart hook Node.js que faz onboarding cross-platform do .plugadvpl/.

Como funciona

.prw / .tlpp           parser strip-first         SQLite + FTS5         slash command
(seu projeto)   ───▶   (regex sobre conteúdo  ─▶  25 tabelas físicas  ─▶ /plugadvpl:*
                       sem comentário/string)     + 2 FTS5 virtuais     (Claude consulta)
                       paralelo adaptive          + 7 lookups TOTVS

O plugadvpl ingest escaneia o projeto, parseia cada fonte em paralelo (ProcessPoolExecutor com fallback single-thread para projetos < 200 arquivos), persiste metadados (funções, chamadas, tabelas, MV_*, SQL embarcado, PEs, REST endpoints, jobs, etc.) em SQLite, e rebuilda dois índices FTS5 — um unicode61 com tokenchars '_-' (mantém A1_COD e FW-Browse como um token) e um trigram para busca substring exata (SA1->A1_COD, %xfilial%).

Quando você pergunta algo ao Claude sobre o projeto, o slash command roda uma query barata no SQLite e devolve só o que importa — função, range de linhas, callers, tabelas — em ~700 tokens. Detalhes em docs/architecture.md.

Requisitos

  • Claude Code (CLI ou IDE extension) com suporte a plugins
  • Python 3.11+ instalado via uvx/uv (não precisa criar venv manualmente)
  • Projeto Protheus com fontes .prw, .prx, .tlpp ou .apw
  • SO: Windows, Linux ou macOS (CI rodando matrix 3 OS × 3 Python)

Status

v0.4.3 — Universo 3 (Rastreabilidade) entregue + polish pack.

  • 21 subcomandos, 40 skills (18 knowledge + 21 CLI wrappers + 1 setup helper), 4 agents, 1 hook
  • 25 tabelas físicas (22 fontes/SX + 3 Universo 3) + 2 FTS5 + 7 lookups
  • 489 testes verde (unit + integration + bench + e2e_local)
  • Bench em ~2.000 fontes: ingest <60s com --workers 8; ingest-sx do dicionário completo (~420k rows) <30s
  • Schema v8 — migrations 005/006/007 (Universo 3) + 008 (índices polish)

Roadmap.

  • v0.1 (shipped) — Universo 1: parser de fontes, FTS5, 13 regras lint single-file, 14 subcomandos CLI.
  • v0.2 (shipped) — 21k linhas de referência ADVPL/TLPP embutidas em 5 skills novas + 6 reforçadas.
  • v0.3 (shipped) — Universo 2 (Dicionário SX): ingest SX1..SXG, comandos impacto/gatilho/sx-status, 11 regras cross-file SX-001..SX-011.
  • v0.4 (shipped) — Universo 3 (Rastreabilidade): execução não-direta (workflow/schedule/job/mail), ExecAuto chain (execauto), Protheus.doc agregada (docs). Polish pack v0.4.3 (5 críticos + 4 importantes do code review).
  • v0.5 (próximo) — Universo 4 a definir (candidatos: qualidade & métricas, complexidade ciclomática, hot-paths, ownership analytics).

Detalhes em docs/ROADMAP.md, CHANGELOG.md e specs em docs/universo3/.

Documentação

Créditos

  • Parser de fontes portado de projeto interno anterior do autor (~750 linhas, validado em aproximadamente 2.000 fontes ADVPL).
  • Lookup catalogs (funções nativas, restritas, lint rules, SQL macros, módulos ERP, PEs) extraídos de advpl-specialist por Thalys Augusto (MIT) — crédito em NOTICE.
  • Construído pela e para a comunidade Protheus/ADVPL brasileira. PRs são muito bem-vindos.

Comunidade

Pull requests muito bem-vindas — especialmente para parser, lint rules, skills temáticas e exemplos .prw/.tlpp de produção (sanitizados).

Veja CONTRIBUTING.md para setup de dev.

Disclaimer / Marcas registradas

Protheus, ADVPL, TLPP e TOTVS são produtos e marcas registradas de propriedade da TOTVS S.A. Este plugin é um projeto independente e não possui vínculo com a TOTVS, suas franquias ou representantes.

Sobre o uso e desenvolvimento

  • Este plugin não utiliza, redistribui ou expõe nenhum código-fonte do produto padrão Protheus (rotinas TOTVS internas, RPO, fontes oficiais).
  • A ferramenta foi desenvolvida e validada exclusivamente sobre fontes customizados (User Functions, customizações MVC, pontos de entrada, WebServices, jobs e demais arquivos .prw/.tlpp/.prx escritos pelos próprios clientes em seus ambientes).
  • Os catálogos embarcados (funções nativas, funções restritas, módulos ERP, pontos de entrada padrão) contêm apenas nomes e metadados publicamente documentados na TDN — TOTVS Developers Network. Não há código-fonte proprietário embutido.
  • Os exemplos .prw/.tlpp distribuídos em skills/<x>/exemplos/ são código original do autor, escritos para ilustrar padrões de customização (não derivados de fontes padrão TOTVS).
  • Cabe a cada usuário garantir que possui direito de acesso e análise sobre os fontes que indexar com este plugin (tipicamente customizações da própria empresa ou de cliente sob contrato).

Licença

MIT © 2026 JoniPraia.

About

Plugin Claude Code + CLI Python que indexa fontes ADVPL/TLPP do Protheus em SQLite + FTS5. Claude consulta metadados sem queimar tokens lendo .prw inteiro.

github.com/JoniPraia/plugadvpl

Topics

python erp sqlite code-analysis mit-license advpl totvs protheus fts5 tlpp claude-code claude-code-plugin

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

6 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases 40

v0.4.3 Latest
May 15, 2026
+ 39 releases

Packages

 
 
 

Contributors

Languages