@mcptoolshop/registry-stats 1.2.4 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.pt-BR.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <p align="center">
2
- <a href="README.md">English</a> | <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> | <strong>Português</strong>
2
+ <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>
3
3
  </p>
4
4
 
5
5
  <p align="center">
@@ -7,31 +7,69 @@
7
7
  </p>
8
8
 
9
9
  <p align="center">
10
- One command. Five registries. All your download stats.
10
+ Five registries. One engine. Dashboard included.
11
11
  </p>
12
12
 
13
13
  <p align="center">
14
14
  <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>
15
15
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a>
16
16
  <a href="https://www.npmjs.com/package/@mcptoolshop/registry-stats"><img src="https://img.shields.io/npm/v/@mcptoolshop/registry-stats" alt="npm version"></a>
17
+ <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>
17
18
  <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>
18
19
  </p>
19
20
 
20
21
  <p align="center">
21
- <a href="https://mcp-tool-shop-org.github.io/registry-stats/">Docs</a> &middot;
22
+ <a href="#dashboard">Dashboard</a> &middot;
23
+ <a href="#desktop-app">Desktop App</a> &middot;
22
24
  <a href="#install">Install</a> &middot;
23
25
  <a href="#cli">CLI</a> &middot;
24
- <a href="#config-file">Config</a> &middot;
25
26
  <a href="#programmatic-api">API</a> &middot;
26
27
  <a href="#rest-api-server">REST Server</a> &middot;
28
+ <a href="#config-file">Config</a> &middot;
27
29
  <a href="#license">License</a>
28
30
  </p>
29
31
 
30
32
  ---
31
33
 
32
- Se você publica no npm, PyPI, NuGet, VS Code Marketplace ou Docker Hub, atualmente você precisa de cinco APIs diferentes para responder à pergunta "quantos downloads eu obtive este mês?". Esta biblioteca oferece uma única interface para todas elas como uma interface de linha de comando (CLI) ou uma API programática.
34
+ 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.
35
+
36
+ Sem dependências de tempo de execução. Utiliza a função nativa `fetch()`. Node 18+.
37
+
38
+ ## O que está incluído
39
+
40
+ | Camada | O que ele faz |
41
+ |-------|-------------|
42
+ | **Engine** | Biblioteca TypeScript + CLI + servidor REST. Consulte cinco registros com uma única interface. Publicado no npm como `@mcptoolshop/registry-stats`. |
43
+ | **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. |
44
+ | **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. |
45
+
46
+ ## Painel
47
+
48
+ Um painel de estatísticas que se atualiza automaticamente está disponível em [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/).
33
49
 
34
- Sem dependências. Utiliza a função nativa `fetch()`. Node 18+.
50
+ - **Interface com abas** Abas Home, Analytics, Leaderboard e Help
51
+ - **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
52
+ - **Resumo executivo** — pontuação de saúde (0–100), índice de diversidade, variação semanal, downloads totais de todos os registros
53
+ - **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σ)
54
+ - **Motor de crescimento inteligente** — lida com a distorção de denominadores pequenos com limite base, teto de porcentagem e fórmula de velocidade amortecida
55
+ - **Insights acionáveis** — recomendações autogeradas e alertas de atenção para pacotes em declínio
56
+ - **Tabela de classificação** — todos os pacotes classificados por downloads semanais com sparklines de 30 dias e badges de tendência inteligentes
57
+ - **Página de configuração** — editor de portfólio com validação, seção registry-sync e visão geral do pipeline
58
+ - **Aba de ajuda** — guia amigável cobrindo cada aba, conceitos-chave, dicas do assistente de IA, pipeline de dados e links úteis
59
+ - **Tema claro/escuro** — segue a preferência do sistema
60
+
61
+ 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`.
62
+
63
+ ## Aplicativo para Desktop
64
+
65
+ Um aplicativo nativo para Windows que encapsula o painel em um shell WebView2 local:
66
+
67
+ - **Funciona offline** — inclui HTML/CSS/JS empacotados; funciona sem internet.
68
+ - **Atualização em tempo real** — busca o arquivo `stats.json` do GitHub Pages sob demanda.
69
+ - **Exportação para CSV** — exporte os dados da tabela de classificação com um clique.
70
+ - **Empacotado como MSIX** — construído e assinado no CI via `desktop-ci.yml`.
71
+
72
+ O código-fonte do aplicativo para desktop está localizado em `desktop/`. Construído com .NET 10 MAUI, direcionado para WinUI 3.
35
73
 
36
74
  ## Instalação
37
75
 
@@ -52,10 +90,6 @@ registry-stats express
52
90
 
53
91
  # Time series with monthly breakdown + trend
54
92
  registry-stats express -r npm --range 2025-01-01:2025-06-30
55
- # 2025-01 142,359,021
56
- # 2025-02 147,522,528
57
- # ...
58
- # Total: 448,383,383 Avg/day: 4,982,038 Trend: flat (-0.46%)
59
93
 
60
94
  # Raw JSON output
61
95
  registry-stats express -r npm --json
@@ -74,14 +108,6 @@ registry-stats
74
108
 
75
109
  # Compare across registries
76
110
  registry-stats express --compare
77
- # express — comparison
78
- #
79
- # Metric npm pypi
80
- # ─────────────────────────────────
81
- # Total - -
82
- # Month 283,472 47,201
83
- # Week 67,367 11,800
84
- # Day 11,566 1,686
85
111
 
86
112
  # Export as CSV or chart-friendly JSON
87
113
  registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
@@ -161,7 +187,6 @@ calc.toChartData(daily, 'express'); // { labels: [...], datasets: [{ labe
161
187
 
162
188
  // Comparison — same package across registries
163
189
  const comparison = await stats.compare('express');
164
- // → { package: 'express', registries: { npm: {...}, pypi: {...} }, fetchedAt: '...' }
165
190
  await stats.compare('express', ['npm', 'pypi']); // specific registries only
166
191
 
167
192
  // Caching (5 min TTL, in-memory)
@@ -173,7 +198,7 @@ await stats('npm', 'express', { cache }); // cache hit
173
198
  ## Suporte a Registros
174
199
 
175
200
  | Registro | Formato do pacote | Séries temporais | Dados disponíveis |
176
- | ---------- | --------------- | ------------- | ---------------- |
201
+ |----------|---------------|-------------|----------------|
177
202
  | `npm` | `express`, `@scope/pkg` | Sim (549 dias) | último dia, última semana, último mês |
178
203
  | `pypi` | `requests` | Sim (180 dias) | último dia, última semana, último mês, total |
179
204
  | `nuget` | `Newtonsoft.Json` | No | total |
@@ -192,7 +217,6 @@ await stats('npm', 'express', { cache }); // cache hit
192
217
  Execute como um microserviço ou incorpore em seu próprio servidor:
193
218
 
194
219
  ```bash
195
- # CLI
196
220
  registry-stats serve --port 3000
197
221
  ```
198
222
 
@@ -240,13 +264,53 @@ registerProvider(cargo);
240
264
  await stats('cargo', 'serde');
241
265
  ```
242
266
 
243
- ## Website
267
+ ## Estrutura do Repositório
268
+
269
+ ```
270
+ registry-stats/
271
+ ├── src/ # TypeScript engine (published to npm)
272
+ ├── site/ # Astro dashboard + landing page (deployed to GitHub Pages)
273
+ ├── desktop/ # WinUI 3 desktop app (.NET 10 MAUI)
274
+ └── test/ # Library tests (vitest)
275
+ ```
276
+
277
+ ## Desenvolvimento
278
+
279
+ ```bash
280
+ # Engine
281
+ npm install && npm run build && npm test
282
+
283
+ # Dashboard (dev server)
284
+ npm run site:dev
285
+
286
+ # Dashboard (production build)
287
+ npm run site:build
288
+ ```
289
+
290
+ ## Segurança e Escopo de Dados
291
+
292
+ | Aspecto | Detalhe |
293
+ |--------|--------|
294
+ | **Data touched** | Estatísticas de download públicas do npm, PyPI, NuGet, VS Code Marketplace, Docker Hub. Cache na memória (opcional). |
295
+ | **Data NOT touched** | Sem telemetria. Sem análises. Sem armazenamento de credenciais. Sem dados do usuário. Sem gravações de arquivos. |
296
+ | **Permissions** | Leitura: APIs públicas de registros via HTTPS. Escrita: apenas stdout/stderr. |
297
+ | **Network** | Saída HTTPS para APIs públicas de registros. Servidor REST local opcional. |
298
+ | **Telemetry** | Nenhum dado coletado ou enviado. |
299
+
300
+ Consulte [SECURITY.md](SECURITY.md) para relatar vulnerabilidades.
301
+
302
+ ## Tabela de Pontuação
244
303
 
245
- A documentação e a página inicial estão localizadas em `site/`.
304
+ | Categoria | Pontuação |
305
+ |----------|-------|
306
+ | A. Segurança | 10 |
307
+ | B. Tratamento de Erros | 10 |
308
+ | C. Documentação para Operadores | 10 |
309
+ | D. Higiene de Distribuição | 10 |
310
+ | E. Identidade (suave) | 10 |
311
+ | **Overall** | **50/50** |
246
312
 
247
- - Desenvolvimento: `npm run site:dev`
248
- - Construção: `npm run site:build`
249
- - Visualização: `npm run site:preview`
313
+ > Auditoria completa: [SHIP_GATE.md](SHIP_GATE.md) · [SCORECARD.md](SCORECARD.md)
250
314
 
251
315
  ## Licença
252
316
 
package/README.zh.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <p align="center">
2
- <a href="README.md">English</a> | <a href="README.ja.md">日本語</a> | <strong>中文</strong> | <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.pt-BR.md">Português</a>
2
+ <a href="README.ja.md">日本語</a> | <a href="README.md">English</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.pt-BR.md">Português (BR)</a>
3
3
  </p>
4
4
 
5
5
  <p align="center">
@@ -7,31 +7,69 @@
7
7
  </p>
8
8
 
9
9
  <p align="center">
10
- One command. Five registries. All your download stats.
10
+ Five registries. One engine. Dashboard included.
11
11
  </p>
12
12
 
13
13
  <p align="center">
14
14
  <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>
15
15
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"></a>
16
16
  <a href="https://www.npmjs.com/package/@mcptoolshop/registry-stats"><img src="https://img.shields.io/npm/v/@mcptoolshop/registry-stats" alt="npm version"></a>
17
+ <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>
17
18
  <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>
18
19
  </p>
19
20
 
20
21
  <p align="center">
21
- <a href="https://mcp-tool-shop-org.github.io/registry-stats/">Docs</a> &middot;
22
+ <a href="#dashboard">Dashboard</a> &middot;
23
+ <a href="#desktop-app">Desktop App</a> &middot;
22
24
  <a href="#install">Install</a> &middot;
23
25
  <a href="#cli">CLI</a> &middot;
24
- <a href="#config-file">Config</a> &middot;
25
26
  <a href="#programmatic-api">API</a> &middot;
26
27
  <a href="#rest-api-server">REST Server</a> &middot;
28
+ <a href="#config-file">Config</a> &middot;
27
29
  <a href="#license">License</a>
28
30
  </p>
29
31
 
30
32
  ---
31
33
 
32
- 如果您将软件包发布到 npm、PyPI、NuGet、VS Code Marketplace Docker Hub,目前您需要使用五个不同的 API 来回答“我这个月下载了多少次?”。这个库为您提供一个统一的接口,用于访问所有这些平台,可以通过命令行界面 (CLI) 或编程 API 使用。
34
+ 您可以在 npm、PyPI、NuGet、VS Code Marketplace 以及 Docker Hub 上发布。目前,要了解“我的软件包表现如何?”,您需要查看五个不同的网站。**registry-stats** 是一个完整的平台:一个 TypeScript 引擎(命令行工具 + API + REST 服务器),一个实时 Web 控制面板,以及一个原生 Windows 桌面应用程序——所有这些都来自一个代码仓库。
35
+
36
+ 没有运行时依赖。使用原生的 `fetch()` 方法。Node 18 或更高版本。
37
+
38
+ ## 包含内容
39
+
40
+ | 层级 | 功能 |
41
+ |-------|-------------|
42
+ | **Engine** | TypeScript 库 + 命令行工具 + REST 服务器。使用一个界面查询五个注册中心。已在 npm 上发布为 `@mcptoolshop/registry-stats`。 |
43
+ | **Dashboard** | 基于 Astro 的 Web 应用程序。提供 AI 聊天助手、6 个交互式图表、智能增长引擎和带选项卡的帮助指南。每周通过 CI 自动重建。 |
44
+ | **Desktop** | 基于 WinUI 3 + WebView2 的原生 Windows 应用程序。将控制面板打包到本地,按需获取实时统计数据。 |
45
+
46
+ ## 控制面板
47
+
48
+ 一个自动更新的统计信息控制面板位于 [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/)。
33
49
 
34
- 无任何依赖。使用原生的 `fetch()` 方法。Node 18 及以上版本。
50
+ - **选项卡界面** Home、Analytics、Leaderboard 和 Help 选项卡
51
+ - **AI 聊天助手** — 基于 Ollama 的 Registry Assistant,支持 RAG 上下文注入、流式响应、模型选择器和对话记忆
52
+ - **执行摘要** — 健康分数(0–100)、多样性指数、周变化、所有注册中心的总下载量
53
+ - **6 个交互式图表** — 30 天趋势(汇总 / 按注册中心 / Top 5 切换)、注册中心份额(极坐标图)、组合风险(分布直方图 + Gini & P90)、Top 10 动量、带迷你图的速度追踪器、以及 30 天热力图(尖峰检测 >2σ)
54
+ - **智能增长引擎** — 处理小分母失真,提供基线阈值、百分比上限和阻尼速度公式
55
+ - **可操作洞察** — 自动生成的建议和下降软件包的注意警报
56
+ - **排行榜** — 所有软件包按周下载量排序,带有 30 天迷你图和智能趋势标记
57
+ - **设置页面** — 组合编辑器、验证功能、registry-sync 配套部分和管道概览
58
+ - **帮助选项卡** — 涵盖每个选项卡、关键概念、AI 助手使用技巧、数据管道和有用链接的友好指南
59
+ - **深色/浅色主题** — 根据系统偏好设置自动切换
60
+
61
+ 数据在构建时获取,并每周通过 CI 自动重建(每周一 06:00 UTC)。在 `site/src/data/packages.json` 文件中配置要跟踪的软件包。
62
+
63
+ ## 桌面应用程序
64
+
65
+ 一个原生 Windows 应用程序,它将控制面板封装在一个本地 WebView2 容器中:
66
+
67
+ - **离线可用**:包含打包的 HTML/CSS/JS 文件;无需互联网连接即可使用。
68
+ - **实时刷新**:从 GitHub Pages 上的 `stats.json` 文件获取实时统计数据。
69
+ - **CSV 导出**:一键导出排行榜数据。
70
+ - **MSIX 软件包**:通过 `desktop-ci.yml` 在 CI 环境中构建和签名。
71
+
72
+ 桌面应用程序的源代码位于 `desktop/` 目录中。使用 .NET 10 MAUI 构建,目标是 WinUI 3。
35
73
 
36
74
  ## 安装
37
75
 
@@ -52,10 +90,6 @@ registry-stats express
52
90
 
53
91
  # Time series with monthly breakdown + trend
54
92
  registry-stats express -r npm --range 2025-01-01:2025-06-30
55
- # 2025-01 142,359,021
56
- # 2025-02 147,522,528
57
- # ...
58
- # Total: 448,383,383 Avg/day: 4,982,038 Trend: flat (-0.46%)
59
93
 
60
94
  # Raw JSON output
61
95
  registry-stats express -r npm --json
@@ -74,14 +108,6 @@ registry-stats
74
108
 
75
109
  # Compare across registries
76
110
  registry-stats express --compare
77
- # express — comparison
78
- #
79
- # Metric npm pypi
80
- # ─────────────────────────────────
81
- # Total - -
82
- # Month 283,472 47,201
83
- # Week 67,367 11,800
84
- # Day 11,566 1,686
85
111
 
86
112
  # Export as CSV or chart-friendly JSON
87
113
  registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
@@ -161,7 +187,6 @@ calc.toChartData(daily, 'express'); // { labels: [...], datasets: [{ labe
161
187
 
162
188
  // Comparison — same package across registries
163
189
  const comparison = await stats.compare('express');
164
- // → { package: 'express', registries: { npm: {...}, pypi: {...} }, fetchedAt: '...' }
165
190
  await stats.compare('express', ['npm', 'pypi']); // specific registries only
166
191
 
167
192
  // Caching (5 min TTL, in-memory)
@@ -173,7 +198,7 @@ await stats('npm', 'express', { cache }); // cache hit
173
198
  ## 仓库支持
174
199
 
175
200
  | 仓库 | 软件包格式 | 时间序列 | 可用数据 |
176
- | ---------- | --------------- | ------------- | ---------------- |
201
+ |----------|---------------|-------------|----------------|
177
202
  | `npm` | `express`, `@scope/pkg` | 是 (549 天) | 最近一天、最近一周、最近一个月 |
178
203
  | `pypi` | `requests` | 是 (180 天) | 最近一天、最近一周、最近一个月、总数 |
179
204
  | `nuget` | `Newtonsoft.Json` | No | 总数 |
@@ -192,7 +217,6 @@ await stats('npm', 'express', { cache }); // cache hit
192
217
  可以作为微服务运行,也可以嵌入到您自己的服务器中:
193
218
 
194
219
  ```bash
195
- # CLI
196
220
  registry-stats serve --port 3000
197
221
  ```
198
222
 
@@ -240,13 +264,53 @@ registerProvider(cargo);
240
264
  await stats('cargo', 'serde');
241
265
  ```
242
266
 
243
- ## 网站
267
+ ## 代码仓库结构
268
+
269
+ ```
270
+ registry-stats/
271
+ ├── src/ # TypeScript engine (published to npm)
272
+ ├── site/ # Astro dashboard + landing page (deployed to GitHub Pages)
273
+ ├── desktop/ # WinUI 3 desktop app (.NET 10 MAUI)
274
+ └── test/ # Library tests (vitest)
275
+ ```
276
+
277
+ ## 开发
278
+
279
+ ```bash
280
+ # Engine
281
+ npm install && npm run build && npm test
282
+
283
+ # Dashboard (dev server)
284
+ npm run site:dev
285
+
286
+ # Dashboard (production build)
287
+ npm run site:build
288
+ ```
289
+
290
+ ## 安全性和数据范围
291
+
292
+ | 方面 | 详细信息 |
293
+ |--------|--------|
294
+ | **Data touched** | 从 npm、PyPI、NuGet、VS Code Marketplace 和 Docker Hub 获取公开的下载统计数据。可选的内存缓存。 |
295
+ | **Data NOT touched** | 没有遥测。没有分析。没有凭证存储。没有用户数据。没有文件写入。 |
296
+ | **Permissions** | 读取:通过 HTTPS 的公开注册中心 API。写入:仅 stdout/stderr。 |
297
+ | **Network** | 向公开注册中心 API 的 HTTPS 出站连接。可选的本地 REST 服务器。 |
298
+ | **Telemetry** | 未收集或发送任何数据。 |
299
+
300
+ 请参阅 [SECURITY.md](SECURITY.md) 以获取漏洞报告。
301
+
302
+ ## 评分卡
244
303
 
245
- 网站和主页位于 `site/` 目录下。
304
+ | 类别 | 评分 |
305
+ |----------|-------|
306
+ | A. 安全性 | 10 |
307
+ | B. 错误处理 | 10 |
308
+ | C. 运维文档 | 10 |
309
+ | D. 发布规范 | 10 |
310
+ | E. 身份验证(软性) | 10 |
311
+ | **Overall** | **50/50** |
246
312
 
247
- - 开发:`npm run site:dev`
248
- - 构建:`npm run site:build`
249
- - 预览:`npm run site:preview`
313
+ > 完整审计:[SHIP_GATE.md](SHIP_GATE.md) · [SCORECARD.md](SCORECARD.md)
250
314
 
251
315
  ## 许可证
252
316
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@mcptoolshop/registry-stats",
3
- "version": "1.2.4",
4
- "description": "Multi-registry download stats for npm, PyPI, NuGet, VS Code Marketplace, and Docker Hub",
3
+ "version": "2.1.0",
4
+ "description": "Multi-registry download stats — engine, AI-powered dashboard, and desktop app for npm, PyPI, NuGet, VS Code Marketplace, and Docker Hub",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
7
7
  "module": "./dist/index.js",