@mcptoolshop/registry-stats 2.2.0 → 3.0.0

package/README.pt-BR.md

@@ -1,15 +1,15 @@
-<p align="center">
-  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.md">English</a>
-</p>
-
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.md">English</a>
+</p>
+
 <p align="center">
   <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/registry-stats/readme.png" alt="registry-stats logo" width="400" />
 </p>
-
+
 <p align="center">
   Five registries. One engine. Dashboard included.
 </p>
-
+
 <p align="center">
   <a href="https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml"><img src="https://github.com/mcp-tool-shop-org/registry-stats/actions/workflows/pages.yml/badge.svg" alt="CI"></a>
   <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a>
@@ -17,7 +17,7 @@
   <a href="https://mcp-tool-shop-org.github.io/registry-stats/dashboard/"><img src="https://img.shields.io/badge/Dashboard-live-green" alt="Dashboard"></a>
   <a href="https://mcp-tool-shop-org.github.io/registry-stats/"><img src="https://img.shields.io/badge/Landing_Page-live-blue" alt="Landing Page"></a>
 </p>
-
+
 <p align="center">
   <a href="#dashboard">Dashboard</a> &middot;
   <a href="#desktop-app">Desktop App</a> &middot;
@@ -28,57 +28,60 @@
   <a href="#config-file">Config</a> &middot;
   <a href="#license">License</a>
 </p>
-
+
 ---
-
-Você publica no npm, PyPI, NuGet, na loja do VS Code e no Docker Hub. Atualmente, responder à pergunta "como estão indo meus pacotes?" significa verificar cinco sites diferentes. **registry-stats** é a plataforma completa: um motor TypeScript (CLI + API + servidor REST), um painel web interativo e um aplicativo nativo para Windows — tudo em um único repositório.
-
-Sem dependências de tempo de execução. Utiliza a função nativa `fetch()`. Node 18+.
-
-## O que está incluído
-
-| Camada | O que ele faz |
-|-------|-------------|
-| **Engine** | Biblioteca TypeScript + CLI + servidor REST. Consulte cinco registros com uma única interface. Publicado no npm como `@mcptoolshop/registry-stats`. |
-| **Dashboard** | Aplicativo web alimentado por Astro. Assistente de chat com IA, seis gráficos interativos, motor de crescimento inteligente e guia de ajuda com abas. Reconstruído semanalmente pelo CI. |
-| **Desktop** | Aplicativo nativo para Windows, construído com WinUI 3 + WebView2. Inclui o painel offline e busca as estatísticas em tempo real sob demanda. |
-
-## Painel
-
-Um painel de estatísticas que se atualiza automaticamente está disponível em [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/).
-
-- **Interface com abas** — Abas Home, Analytics, Leaderboard e Help
-- **Assistente de chat com IA** — Registry Assistant alimentado por Ollama com contexto RAG, respostas em streaming, seletor de modelos e memória de conversação
-- **Resumo executivo** — pontuação de saúde (0–100), índice de diversidade, variação semanal, downloads totais de todos os registros
-- **Seis gráficos interativos** — tendência de 30 dias (vista agregada / por registro / top 5), participação do registro (área polar), risco do portfólio (histograma + Gini & P90), top 10 momentum, rastreador de velocidade com sparklines e mapa de calor de 30 dias com detecção de picos (>2σ)
-- **Motor de crescimento inteligente** — lida com a distorção de denominadores pequenos com limite base, teto de porcentagem e fórmula de velocidade amortecida
-- **Insights acionáveis** — recomendações autogeradas e alertas de atenção para pacotes em declínio
-- **Tabela de classificação** — todos os pacotes classificados por downloads semanais com sparklines de 30 dias e badges de tendência inteligentes
-- **Página de configuração** — editor de portfólio com validação, seção registry-sync e visão geral do pipeline
-- **Aba de ajuda** — guia amigável cobrindo cada aba, conceitos-chave, dicas do assistente de IA, pipeline de dados e links úteis
-- **Tema claro/escuro** — segue a preferência do sistema
-
-Os dados são buscados durante a compilação e reconstruídos semanalmente pelo CI (segundas-feiras às 06:00 UTC). Configure os pacotes a serem monitorados em `site/src/data/packages.json`.
-
-## Aplicativo para Desktop
-
-Um aplicativo nativo para Windows que encapsula o painel em um shell WebView2 local:
-
-- **Funciona offline** — inclui HTML/CSS/JS empacotados; funciona sem internet.
-- **Atualização em tempo real** — busca o arquivo `stats.json` do GitHub Pages sob demanda.
-- **Exportação para CSV** — exporte os dados da tabela de classificação com um clique.
-- **Empacotado como MSIX** — construído e assinado no CI via `desktop-ci.yml`.
-
-O código-fonte do aplicativo para desktop está localizado em `desktop/`. Construído com .NET 10 MAUI, direcionado para WinUI 3.
-
-## Instalação
-
+
+Você publica no npm, PyPI, NuGet, na loja do VS Code e no Docker Hub. Atualmente, responder à pergunta "como estão indo meus pacotes?" significa verificar cinco sites diferentes. **registry-stats** é a plataforma completa: um motor TypeScript (CLI + API + servidor REST), um painel web interativo e um aplicativo nativo para Windows — tudo em um único repositório.
+
+Sem dependências de tempo de execução. Utiliza a função nativa `fetch()`. Node 18+.
+
+## O que está incluído
+
+| Camada | O que ele faz |
+|-------|-------------|
+| **Engine** | Biblioteca TypeScript + CLI + servidor REST. Consulte cinco registros com uma única interface. Publicado no npm como `@mcptoolshop/registry-stats`. |
+| **Dashboard** | Aplicação web com tecnologia Astro e assistente de IA Pulse (reconhecimento de voz, pesquisa na web, tela cheia, conectores de dados do GitHub), seis gráficos interativos, atualização em tempo real, exportação de relatórios (PDF / JSONL / Markdown) e um guia de ajuda em abas. Reconstruída semanalmente por CI; atualizável sob demanda. |
+| **Desktop** | Aplicativo nativo para Windows, construído com WinUI 3 + WebView2. Inclui o painel offline e busca as estatísticas em tempo real sob demanda. |
+
+## Painel
+
+Um painel de estatísticas que se atualiza automaticamente está disponível em [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/).
+
+- **Interface em abas** — Abas "Início", "Análise", "Ranking" e "Ajuda".
+- **Assistente de IA Pulse** — Assistente conversacional alimentado por Ollama, com síntese de voz em tempo real (o assistente fala enquanto o modelo de linguagem gera a resposta, com 4 vozes disponíveis através de [mcp-voice-soundboard](https://github.com/mcp-tool-shop-org/mcp-voice-soundboard)), pesquisa na web (Wikipedia + SearXNG opcional), reprodução automática, modo de tela cheia, conector de dados de organizações do GitHub, seletor de modelo e memória de conversação.
+- **Visão geral executiva** — pontuação de saúde (0–100), índice de diversidade, variação semanal, número total de downloads em todos os repositórios.
+- **Seis gráficos interativos** — tendência de 30 dias (agregação / por repositório / top-5), participação no repositório (área polar), risco do portfólio (histograma + Gini e P90), top 10 em ascensão, rastreador de velocidade com gráficos de linha, e mapa de calor de 30 dias com detecção de picos (>2σ).
+- **Motor de crescimento inteligente** — corrige distorções de pequenas amostras com um limite mínimo, um limite percentual e uma fórmula de velocidade amortecida.
+- **Informações acionáveis** — recomendações geradas automaticamente e alertas para pacotes com desempenho decrescente.
+- **Painel Pulse** — visualização dividida de pacotes estabelecidos (≥ 50 downloads/semana) e pacotes emergentes e novos, com gráficos de linha de 7 dias, variações absolutas e percentuais, contexto de referência e um resumo executivo em uma linha.
+- **Atualização em tempo real** — busca sob demanda dos dados das APIs do npm e PyPI, com indicador de progresso; os resultados são armazenados em cache na sessionStorage (TTL de 5 minutos), para que a troca de abas seja instantânea.
+- **Exportação de relatórios** — menu suspenso próximo ao botão de atualização, oferecendo três formatos: **PDF Executivo** (via jsPDF), **JSONL do Modelo de Linguagem** (registros formatados para ingestão por IA) e **Markdown para Desenvolvedores** (tabelas GFM).
+- **Ranking** — 132 pacotes classificados por downloads semanais, com gráficos de linha de 30 dias e indicadores de tendência inteligentes.
+- **Página de configuração** — editor de portfólio com validação, seção de sincronização de repositórios e visão geral do pipeline.
+- **Aba de ajuda** — guia amigável que cobre todas as abas, conceitos-chave, dicas para o assistente de IA, pipeline de dados e links úteis.
+- **Tema claro / escuro** — segue a preferência do sistema.
+
+Os dados são coletados no momento da compilação e reconstruídos semanalmente por meio de CI (segundas-feiras às 06:00 UTC). A atualização em tempo real busca os dados mais recentes diretamente das APIs dos registros. Configure os pacotes a serem monitorados em `site/src/data/packages.json` (132 pacotes em 5 registros).
+
+## Aplicativo para Desktop
+
+Um aplicativo nativo para Windows que encapsula o painel em um shell WebView2 local:
+
+- **Funciona offline** — inclui HTML/CSS/JS empacotados; funciona sem internet.
+- **Atualização em tempo real** — busca o arquivo `stats.json` do GitHub Pages sob demanda.
+- **Exportação para CSV** — exporte os dados da tabela de classificação com um clique.
+- **Empacotado como MSIX** — construído e assinado no CI via `desktop-ci.yml`.
+
+O código-fonte do aplicativo para desktop está localizado em `desktop/`. Construído com .NET 10 MAUI, direcionado para WinUI 3.
+
+## Instalação
+
 ```bash
 npm install @mcptoolshop/registry-stats
 ```
-
-## Interface de Linha de Comando (CLI)
-
+
+## Interface de Linha de Comando (CLI)
+
 ```bash
 # Query a single registry
 registry-stats express -r npm
@@ -116,11 +119,11 @@ registry-stats express -r npm --range 2025-01-01:2025-06-30 --format chart
 # Start a REST API server
 registry-stats serve --port 3000
 ```
-
-## Arquivo de Configuração
-
-Crie um arquivo `registry-stats.config.json` na raiz do seu projeto (ou execute `registry-stats --init`):
-
+
+## Arquivo de Configuração
+
+Crie um arquivo `registry-stats.config.json` na raiz do seu projeto (ou execute `registry-stats --init`):
+
 ```json
 {
   "registries": ["npm", "pypi", "nuget", "vscode", "docker"],
@@ -139,11 +142,11 @@ Crie um arquivo `registry-stats.config.json` na raiz do seu projeto (ou execute
   "concurrency": 5
 }
 ```
-
-Execute `registry-stats` sem argumentos para obter as estatísticas de todos os pacotes configurados. A CLI procura o arquivo de configuração a partir do diretório atual.
-
-A configuração também está disponível programaticamente:
-
+
+Execute `registry-stats` sem argumentos para obter as estatísticas de todos os pacotes configurados. A CLI procura o arquivo de configuração a partir do diretório atual.
+
+A configuração também está disponível programaticamente:
+
 ```typescript
 import { loadConfig, defaultConfig, starterConfig } from '@mcptoolshop/registry-stats';
 
@@ -151,9 +154,9 @@ const config = loadConfig();          // finds nearest config file, or null
 const defaults = defaultConfig();     // returns default Config object
 const template = starterConfig();     // returns starter JSON string
 ```
-
-## API Programática
-
+
+## API Programática
+
 ```typescript
 import { stats, calc, createCache } from '@mcptoolshop/registry-stats';
 
@@ -194,41 +197,41 @@ const cache = createCache();
 await stats('npm', 'express', { cache });  // fetches
 await stats('npm', 'express', { cache });  // cache hit
 ```
-
-## Suporte a Registros
-
-| Registro | Formato do pacote | Séries temporais | Dados disponíveis |
-|----------|---------------|-------------|----------------|
-| `npm` | `express`, `@scope/pkg` | Sim (549 dias) | último dia, última semana, último mês |
-| `pypi` | `requests` | Sim (180 dias) | último dia, última semana, último mês, total |
-| `nuget` | `Newtonsoft.Json` | No | total |
-| `vscode` | `publisher.extension` | No | total (instalações), avaliação, tendências |
-| `docker` | `namespace/repo` | No | total (downloads), estrelas |
-
-## Confiabilidade Integrada
-
-- Tentativa automática com retrocesso exponencial em caso de erros 429/5xx
-- Respeita os cabeçalhos `Retry-After`
-- Limitação de concorrência para solicitações em lote
-- Cache TTL opcional (plugável — utilize seu próprio backend Redis/arquivo através da interface `StatsCache`)
-
-## Servidor de API REST
-
-Execute como um microserviço ou incorpore em seu próprio servidor:
-
+
+## Suporte a Registros
+
+| Registro | Formato do pacote | Séries temporais | Dados disponíveis |
+|----------|---------------|-------------|----------------|
+| `npm` | `express`, `@scope/pkg` | Sim (549 dias) | último dia, última semana, último mês |
+| `pypi` | `requests` | Sim (180 dias) | último dia, última semana, último mês, total |
+| `nuget` | `Newtonsoft.Json` | No | total |
+| `vscode` | `publisher.extension` | No | total (instalações), avaliação, tendências |
+| `docker` | `namespace/repo` | No | total (downloads), estrelas |
+
+## Confiabilidade Integrada
+
+- Tentativa automática com retrocesso exponencial em caso de erros 429/5xx
+- Respeita os cabeçalhos `Retry-After`
+- Limitação de concorrência para solicitações em lote
+- Cache TTL opcional (plugável — utilize seu próprio backend Redis/arquivo através da interface `StatsCache`)
+
+## Servidor de API REST
+
+Execute como um microserviço ou incorpore em seu próprio servidor:
+
 ```bash
 registry-stats serve --port 3000
 ```
-
+
 ```
 GET /stats/:package              # all registries
 GET /stats/:registry/:package    # single registry
 GET /compare/:package?registries=npm,pypi
 GET /range/:registry/:package?start=YYYY-MM-DD&end=YYYY-MM-DD&format=json|csv|chart
 ```
-
-Uso programático para servidores personalizados ou sem servidor:
-
+
+Uso programático para servidores personalizados ou sem servidor:
+
 ```typescript
 import { createHandler, serve } from '@mcptoolshop/registry-stats';
 
@@ -240,9 +243,9 @@ import { createServer } from 'node:http';
 const handler = createHandler();
 createServer(handler).listen(3000);
 ```
-
-## Registros Personalizados
-
+
+## Registros Personalizados
+
 ```typescript
 import { registerProvider, type RegistryProvider } from '@mcptoolshop/registry-stats';
 
@@ -263,9 +266,9 @@ const cargo: RegistryProvider = {
 registerProvider(cargo);
 await stats('cargo', 'serde');
 ```
-
-## Estrutura do Repositório
-
+
+## Estrutura do Repositório
+
 ```
 registry-stats/
 ├── src/        # TypeScript engine (published to npm)
@@ -273,9 +276,9 @@ registry-stats/
 ├── desktop/    # WinUI 3 desktop app (.NET 10 MAUI)
 └── test/       # Library tests (vitest)
 ```
-
-## Desenvolvimento
-
+
+## Desenvolvimento
+
 ```bash
 # Engine
 npm install && npm run build && npm test
@@ -286,36 +289,36 @@ npm run site:dev
 # Dashboard (production build)
 npm run site:build
 ```
-
-## Segurança e Escopo de Dados
-
-| Aspecto | Detalhe |
-|--------|--------|
-| **Data touched** | Estatísticas de download públicas do npm, PyPI, NuGet, VS Code Marketplace, Docker Hub. Cache na memória (opcional). |
-| **Data NOT touched** | Sem telemetria. Sem análises. Sem armazenamento de credenciais. Sem dados do usuário. Sem gravações de arquivos. |
-| **Permissions** | Leitura: APIs públicas de registros via HTTPS. Escrita: apenas stdout/stderr. |
-| **Network** | Saída HTTPS para APIs públicas de registros. Servidor REST local opcional. |
-| **Telemetry** | Nenhum dado coletado ou enviado. |
-
-Consulte [SECURITY.md](SECURITY.md) para relatar vulnerabilidades.
-
-## Tabela de Pontuação
-
-| Categoria | Pontuação |
-|----------|-------|
-| A. Segurança | 10 |
-| B. Tratamento de Erros | 10 |
-| C. Documentação para Operadores | 10 |
-| D. Higiene de Distribuição | 10 |
-| E. Identidade (suave) | 10 |
-| **Overall** | **50/50** |
-
-> Auditoria completa: [SHIP_GATE.md](SHIP_GATE.md) · [SCORECARD.md](SCORECARD.md)
-
-## Licença
-
-MIT
-
+
+## Segurança e Escopo de Dados
+
+| Aspecto | Detalhe |
+|--------|--------|
+| **Data touched** | Estatísticas de download públicas do npm, PyPI, NuGet, VS Code Marketplace, Docker Hub. Cache na memória (opcional). |
+| **Data NOT touched** | Sem telemetria. Sem análises. Sem armazenamento de credenciais. Sem dados do usuário. Sem gravações de arquivos. |
+| **Permissions** | Leitura: APIs públicas de registros via HTTPS. Escrita: apenas stdout/stderr. |
+| **Network** | Saída HTTPS para APIs públicas de registros. Servidor REST local opcional. |
+| **Telemetry** | Nenhum dado coletado ou enviado. |
+
+Consulte [SECURITY.md](SECURITY.md) para relatar vulnerabilidades.
+
+## Tabela de Pontuação
+
+| Categoria | Pontuação |
+|----------|-------|
+| A. Segurança | 10 |
+| B. Tratamento de Erros | 10 |
+| C. Documentação para Operadores | 10 |
+| D. Higiene de Distribuição | 10 |
+| E. Identidade (suave) | 10 |
+| **Overall** | **50/50** |
+
+> Auditoria completa: [SHIP_GATE.md](SHIP_GATE.md) · [SCORECARD.md](SCORECARD.md)
+
+## Licença
+
+MIT
+
 ---
-
-Criado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
+
+Criado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>