@mcptoolshop/registry-stats 1.2.4 → 2.0.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.
Files changed (9) hide show
  1. package/README.es.md +150 -90
  2. package/README.fr.md +150 -128
  3. package/README.hi.md +150 -90
  4. package/README.it.md +150 -90
  5. package/README.ja.md +150 -90
  6. package/README.md +60 -38
  7. package/README.pt-BR.md +150 -90
  8. package/README.zh.md +150 -90
  9. package/package.json +2 -2
package/README.pt-BR.md CHANGED
@@ -1,46 +1,80 @@
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>
3
- </p>
4
-
1
+ <p align="center">
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
+ </p>
4
+
5
5
  <p align="center">
6
6
  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/registry-stats/readme.png" alt="registry-stats logo" width="400" />
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
-
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.
33
-
34
- Sem dependências. Utiliza a função nativa `fetch()`. Node 18+.
35
-
36
- ## Instalação
37
-
33
+
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. Capturas de tela executivas, análise de crescimento, saúde dos dados, tabela de classificação com gráficos. 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/).
49
+
50
+ - **Captura de tela executiva** — narrativa semanal em uma frase: registro principal, pacote principal, maior crescimento, concentração do portfólio, confiabilidade dos dados.
51
+ - **Análise de crescimento** — pacotes com maior e menor crescimento, e pacotes recém-ativados (npm nos últimos 7 dias vs. os 7 dias anteriores).
52
+ - **Saúde dos dados** — cobertura por registro, selos de confiabilidade (ok / parcial / ausente), detalhes de erros expandíveis.
53
+ - **Deltas de captura de tela** — acompanhamento semanal para registros que mostram apenas dados cumulativos (Docker, VS Code, NuGet).
54
+ - **Tabela de classificação** — todos os pacotes classificados por downloads semanais, com gráficos de 30 dias para cada linha.
55
+ - **Tema claro/escuro** — segue a preferência do sistema.
56
+
57
+ 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`.
58
+
59
+ ## Aplicativo para Desktop
60
+
61
+ Um aplicativo nativo para Windows que encapsula o painel em um shell WebView2 local:
62
+
63
+ - **Funciona offline** — inclui HTML/CSS/JS empacotados; funciona sem internet.
64
+ - **Atualização em tempo real** — busca o arquivo `stats.json` do GitHub Pages sob demanda.
65
+ - **Exportação para CSV** — exporte os dados da tabela de classificação com um clique.
66
+ - **Empacotado como MSIX** — construído e assinado no CI via `desktop-ci.yml`.
67
+
68
+ O código-fonte do aplicativo para desktop está localizado em `desktop/`. Construído com .NET 10 MAUI, direcionado para WinUI 3.
69
+
70
+ ## Instalação
71
+
38
72
  ```bash
39
73
  npm install @mcptoolshop/registry-stats
40
74
  ```
41
-
42
- ## Interface de Linha de Comando (CLI)
43
-
75
+
76
+ ## Interface de Linha de Comando (CLI)
77
+
44
78
  ```bash
45
79
  # Query a single registry
46
80
  registry-stats express -r npm
@@ -52,10 +86,6 @@ registry-stats express
52
86
 
53
87
  # Time series with monthly breakdown + trend
54
88
  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
89
 
60
90
  # Raw JSON output
61
91
  registry-stats express -r npm --json
@@ -74,14 +104,6 @@ registry-stats
74
104
 
75
105
  # Compare across registries
76
106
  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
107
 
86
108
  # Export as CSV or chart-friendly JSON
87
109
  registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
@@ -90,11 +112,11 @@ registry-stats express -r npm --range 2025-01-01:2025-06-30 --format chart
90
112
  # Start a REST API server
91
113
  registry-stats serve --port 3000
92
114
  ```
93
-
94
- ## Arquivo de Configuração
95
-
96
- Crie um arquivo `registry-stats.config.json` na raiz do seu projeto (ou execute `registry-stats --init`):
97
-
115
+
116
+ ## Arquivo de Configuração
117
+
118
+ Crie um arquivo `registry-stats.config.json` na raiz do seu projeto (ou execute `registry-stats --init`):
119
+
98
120
  ```json
99
121
  {
100
122
  "registries": ["npm", "pypi", "nuget", "vscode", "docker"],
@@ -113,11 +135,11 @@ Crie um arquivo `registry-stats.config.json` na raiz do seu projeto (ou execute
113
135
  "concurrency": 5
114
136
  }
115
137
  ```
116
-
117
- 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.
118
-
119
- A configuração também está disponível programaticamente:
120
-
138
+
139
+ 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.
140
+
141
+ A configuração também está disponível programaticamente:
142
+
121
143
  ```typescript
122
144
  import { loadConfig, defaultConfig, starterConfig } from '@mcptoolshop/registry-stats';
123
145
 
@@ -125,9 +147,9 @@ const config = loadConfig(); // finds nearest config file, or null
125
147
  const defaults = defaultConfig(); // returns default Config object
126
148
  const template = starterConfig(); // returns starter JSON string
127
149
  ```
128
-
129
- ## API Programática
130
-
150
+
151
+ ## API Programática
152
+
131
153
  ```typescript
132
154
  import { stats, calc, createCache } from '@mcptoolshop/registry-stats';
133
155
 
@@ -161,7 +183,6 @@ calc.toChartData(daily, 'express'); // { labels: [...], datasets: [{ labe
161
183
 
162
184
  // Comparison — same package across registries
163
185
  const comparison = await stats.compare('express');
164
- // → { package: 'express', registries: { npm: {...}, pypi: {...} }, fetchedAt: '...' }
165
186
  await stats.compare('express', ['npm', 'pypi']); // specific registries only
166
187
 
167
188
  // Caching (5 min TTL, in-memory)
@@ -169,42 +190,41 @@ const cache = createCache();
169
190
  await stats('npm', 'express', { cache }); // fetches
170
191
  await stats('npm', 'express', { cache }); // cache hit
171
192
  ```
172
-
173
- ## Suporte a Registros
174
-
175
- | Registro | Formato do pacote | Séries temporais | Dados disponíveis |
176
- | ---------- | --------------- | ------------- | ---------------- |
177
- | `npm` | `express`, `@scope/pkg` | Sim (549 dias) | último dia, última semana, último mês |
178
- | `pypi` | `requests` | Sim (180 dias) | último dia, última semana, último mês, total |
179
- | `nuget` | `Newtonsoft.Json` | No | total |
180
- | `vscode` | `publisher.extension` | No | total (instalações), avaliação, tendências |
181
- | `docker` | `namespace/repo` | No | total (downloads), estrelas |
182
-
183
- ## Confiabilidade Integrada
184
-
185
- - Tentativa automática com retrocesso exponencial em caso de erros 429/5xx
186
- - Respeita os cabeçalhos `Retry-After`
187
- - Limitação de concorrência para solicitações em lote
188
- - Cache TTL opcional (plugável — utilize seu próprio backend Redis/arquivo através da interface `StatsCache`)
189
-
190
- ## Servidor de API REST
191
-
192
- Execute como um microserviço ou incorpore em seu próprio servidor:
193
-
193
+
194
+ ## Suporte a Registros
195
+
196
+ | Registro | Formato do pacote | Séries temporais | Dados disponíveis |
197
+ |----------|---------------|-------------|----------------|
198
+ | `npm` | `express`, `@scope/pkg` | Sim (549 dias) | último dia, última semana, último mês |
199
+ | `pypi` | `requests` | Sim (180 dias) | último dia, última semana, último mês, total |
200
+ | `nuget` | `Newtonsoft.Json` | No | total |
201
+ | `vscode` | `publisher.extension` | No | total (instalações), avaliação, tendências |
202
+ | `docker` | `namespace/repo` | No | total (downloads), estrelas |
203
+
204
+ ## Confiabilidade Integrada
205
+
206
+ - Tentativa automática com retrocesso exponencial em caso de erros 429/5xx
207
+ - Respeita os cabeçalhos `Retry-After`
208
+ - Limitação de concorrência para solicitações em lote
209
+ - Cache TTL opcional (plugável — utilize seu próprio backend Redis/arquivo através da interface `StatsCache`)
210
+
211
+ ## Servidor de API REST
212
+
213
+ Execute como um microserviço ou incorpore em seu próprio servidor:
214
+
194
215
  ```bash
195
- # CLI
196
216
  registry-stats serve --port 3000
197
217
  ```
198
-
218
+
199
219
  ```
200
220
  GET /stats/:package # all registries
201
221
  GET /stats/:registry/:package # single registry
202
222
  GET /compare/:package?registries=npm,pypi
203
223
  GET /range/:registry/:package?start=YYYY-MM-DD&end=YYYY-MM-DD&format=json|csv|chart
204
224
  ```
205
-
206
- Uso programático para servidores personalizados ou sem servidor:
207
-
225
+
226
+ Uso programático para servidores personalizados ou sem servidor:
227
+
208
228
  ```typescript
209
229
  import { createHandler, serve } from '@mcptoolshop/registry-stats';
210
230
 
@@ -216,9 +236,9 @@ import { createServer } from 'node:http';
216
236
  const handler = createHandler();
217
237
  createServer(handler).listen(3000);
218
238
  ```
219
-
220
- ## Registros Personalizados
221
-
239
+
240
+ ## Registros Personalizados
241
+
222
242
  ```typescript
223
243
  import { registerProvider, type RegistryProvider } from '@mcptoolshop/registry-stats';
224
244
 
@@ -239,19 +259,59 @@ const cargo: RegistryProvider = {
239
259
  registerProvider(cargo);
240
260
  await stats('cargo', 'serde');
241
261
  ```
262
+
263
+ ## Estrutura do Repositório
264
+
265
+ ```
266
+ registry-stats/
267
+ ├── src/ # TypeScript engine (published to npm)
268
+ ├── site/ # Astro dashboard + landing page (deployed to GitHub Pages)
269
+ ├── desktop/ # WinUI 3 desktop app (.NET 10 MAUI)
270
+ └── test/ # Library tests (vitest)
271
+ ```
272
+
273
+ ## Desenvolvimento
274
+
275
+ ```bash
276
+ # Engine
277
+ npm install && npm run build && npm test
242
278
 
243
- ## Website
244
-
245
- A documentação e a página inicial estão localizadas em `site/`.
246
-
247
- - Desenvolvimento: `npm run site:dev`
248
- - Construção: `npm run site:build`
249
- - Visualização: `npm run site:preview`
250
-
251
- ## Licença
252
-
253
- MIT
279
+ # Dashboard (dev server)
280
+ npm run site:dev
254
281
 
282
+ # Dashboard (production build)
283
+ npm run site:build
284
+ ```
285
+
286
+ ## Segurança e Escopo de Dados
287
+
288
+ | Aspecto | Detalhe |
289
+ |--------|--------|
290
+ | **Data touched** | Estatísticas de download públicas do npm, PyPI, NuGet, VS Code Marketplace, Docker Hub. Cache na memória (opcional). |
291
+ | **Data NOT touched** | Sem telemetria. Sem análises. Sem armazenamento de credenciais. Sem dados do usuário. Sem gravações de arquivos. |
292
+ | **Permissions** | Leitura: APIs públicas de registros via HTTPS. Escrita: apenas stdout/stderr. |
293
+ | **Network** | Saída HTTPS para APIs públicas de registros. Servidor REST local opcional. |
294
+ | **Telemetry** | Nenhum dado coletado ou enviado. |
295
+
296
+ Consulte [SECURITY.md](SECURITY.md) para relatar vulnerabilidades.
297
+
298
+ ## Tabela de Pontuação
299
+
300
+ | Categoria | Pontuação |
301
+ |----------|-------|
302
+ | A. Segurança | 10 |
303
+ | B. Tratamento de Erros | 10 |
304
+ | C. Documentação para Operadores | 10 |
305
+ | D. Higiene de Distribuição | 10 |
306
+ | E. Identidade (suave) | 10 |
307
+ | **Overall** | **50/50** |
308
+
309
+ > Auditoria completa: [SHIP_GATE.md](SHIP_GATE.md) · [SCORECARD.md](SCORECARD.md)
310
+
311
+ ## Licença
312
+
313
+ MIT
314
+
255
315
  ---
256
-
257
- Criado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
316
+
317
+ Criado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
package/README.zh.md CHANGED
@@ -1,46 +1,80 @@
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>
3
- </p>
4
-
1
+ <p align="center">
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
+ </p>
4
+
5
5
  <p align="center">
6
6
  <img src="https://raw.githubusercontent.com/mcp-tool-shop-org/brand/main/logos/registry-stats/readme.png" alt="registry-stats logo" width="400" />
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
-
32
- 如果您将软件包发布到 npm、PyPI、NuGet、VS Code Marketplace 或 Docker Hub，目前您需要使用五个不同的 API 来回答“我这个月下载了多少次？”。这个库为您提供一个统一的接口，用于访问所有这些平台，可以通过命令行界面 (CLI) 或编程 API 使用。
33
-
34
- 无任何依赖。使用原生的 `fetch()` 方法。Node 18 及以上版本。
35
-
36
- ## 安装
37
-
33
+
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 应用程序。提供关键指标概览、增长趋势、数据健康状况以及带有折线图的排行榜。每周通过 CI 自动重建。 |
44
+ | **Desktop** | 基于 WinUI 3 + WebView2 的原生 Windows 应用程序。将控制面板打包到本地，按需获取实时统计数据。 |
45
+
46
+ ## 控制面板
47
+
48
+ 一个自动更新的统计信息控制面板位于 [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/)。
49
+
50
+ - **关键指标概览**：每周的简短叙述：顶级注册中心、顶级软件包、增长最快的软件包、软件包组合集中度、数据可靠性。
51
+ - **增长趋势**：增长最快的软件包、下降最快的软件包以及新活跃的软件包（npm 7 天 vs 前 7 天）。
52
+ - **数据健康状况**：每个注册中心的覆盖率、可靠性标识（正常/部分/缺失）、可展开的错误详细信息。
53
+ - **快照差异**：用于仅累积统计数据的注册中心（Docker、VS Code、NuGet）的每周跟踪数据。
54
+ - **排行榜**：所有软件包按每周下载量排序，并显示 30 天的折线图。
55
+ - **深色/浅色主题**：根据系统偏好设置自动切换。
56
+
57
+ 数据在构建时获取，并每周通过 CI 自动重建（每周一 06:00 UTC）。在 `site/src/data/packages.json` 文件中配置要跟踪的软件包。
58
+
59
+ ## 桌面应用程序
60
+
61
+ 一个原生 Windows 应用程序，它将控制面板封装在一个本地 WebView2 容器中：
62
+
63
+ - **离线可用**：包含打包的 HTML/CSS/JS 文件；无需互联网连接即可使用。
64
+ - **实时刷新**：从 GitHub Pages 上的 `stats.json` 文件获取实时统计数据。
65
+ - **CSV 导出**：一键导出排行榜数据。
66
+ - **MSIX 软件包**：通过 `desktop-ci.yml` 在 CI 环境中构建和签名。
67
+
68
+ 桌面应用程序的源代码位于 `desktop/` 目录中。使用 .NET 10 MAUI 构建，目标是 WinUI 3。
69
+
70
+ ## 安装
71
+
38
72
  ```bash
39
73
  npm install @mcptoolshop/registry-stats
40
74
  ```
41
-
42
- ## 命令行界面 (CLI)
43
-
75
+
76
+ ## 命令行界面 (CLI)
77
+
44
78
  ```bash
45
79
  # Query a single registry
46
80
  registry-stats express -r npm
@@ -52,10 +86,6 @@ registry-stats express
52
86
 
53
87
  # Time series with monthly breakdown + trend
54
88
  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
89
 
60
90
  # Raw JSON output
61
91
  registry-stats express -r npm --json
@@ -74,14 +104,6 @@ registry-stats
74
104
 
75
105
  # Compare across registries
76
106
  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
107
 
86
108
  # Export as CSV or chart-friendly JSON
87
109
  registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
@@ -90,11 +112,11 @@ registry-stats express -r npm --range 2025-01-01:2025-06-30 --format chart
90
112
  # Start a REST API server
91
113
  registry-stats serve --port 3000
92
114
  ```
93
-
94
- ## 配置文件
95
-
96
- 在您的项目根目录下创建一个 `registry-stats.config.json` 文件（或者运行 `registry-stats --init` 命令）：
97
-
115
+
116
+ ## 配置文件
117
+
118
+ 在您的项目根目录下创建一个 `registry-stats.config.json` 文件（或者运行 `registry-stats --init` 命令）：
119
+
98
120
  ```json
99
121
  {
100
122
  "registries": ["npm", "pypi", "nuget", "vscode", "docker"],
@@ -113,11 +135,11 @@ registry-stats serve --port 3000
113
135
  "concurrency": 5
114
136
  }
115
137
  ```
116
-
117
- 运行 `registry-stats` 命令，不带任何参数，即可获取所有配置软件包的统计数据。命令行界面会从当前工作目录向上查找最近的配置文件。
118
-
119
- 配置文件也可以通过编程方式访问：
120
-
138
+
139
+ 运行 `registry-stats` 命令，不带任何参数，即可获取所有配置软件包的统计数据。命令行界面会从当前工作目录向上查找最近的配置文件。
140
+
141
+ 配置文件也可以通过编程方式访问：
142
+
121
143
  ```typescript
122
144
  import { loadConfig, defaultConfig, starterConfig } from '@mcptoolshop/registry-stats';
123
145
 
@@ -125,9 +147,9 @@ const config = loadConfig(); // finds nearest config file, or null
125
147
  const defaults = defaultConfig(); // returns default Config object
126
148
  const template = starterConfig(); // returns starter JSON string
127
149
  ```
128
-
129
- ## 编程 API
130
-
150
+
151
+ ## 编程 API
152
+
131
153
  ```typescript
132
154
  import { stats, calc, createCache } from '@mcptoolshop/registry-stats';
133
155
 
@@ -161,7 +183,6 @@ calc.toChartData(daily, 'express'); // { labels: [...], datasets: [{ labe
161
183
 
162
184
  // Comparison — same package across registries
163
185
  const comparison = await stats.compare('express');
164
- // → { package: 'express', registries: { npm: {...}, pypi: {...} }, fetchedAt: '...' }
165
186
  await stats.compare('express', ['npm', 'pypi']); // specific registries only
166
187
 
167
188
  // Caching (5 min TTL, in-memory)
@@ -169,42 +190,41 @@ const cache = createCache();
169
190
  await stats('npm', 'express', { cache }); // fetches
170
191
  await stats('npm', 'express', { cache }); // cache hit
171
192
  ```
172
-
173
- ## 仓库支持
174
-
175
- | 仓库 | 软件包格式 | 时间序列 | 可用数据 |
176
- | ---------- | --------------- | ------------- | ---------------- |
177
- | `npm` | `express`, `@scope/pkg` | 是 (549 天) | 最近一天、最近一周、最近一个月 |
178
- | `pypi` | `requests` | 是 (180 天) | 最近一天、最近一周、最近一个月、总数 |
179
- | `nuget` | `Newtonsoft.Json` | No | 总数 |
180
- | `vscode` | `publisher.extension` | No | 总数（安装量）、评分、趋势 |
181
- | `docker` | `namespace/repo` | No | 总数（拉取次数）、星级 |
182
-
183
- ## 内置可靠性
184
-
185
- - 自动重试，并在遇到 429/5xx 错误时采用指数退避策略
186
- - 尊重 `Retry-After` 头部信息
187
- - 批量请求的并发限制
188
- - 可选的 TTL 缓存（可插拔，通过 `StatsCache` 接口，您可以自定义 Redis 或文件后端）
189
-
190
- ## REST API 服务器
191
-
192
- 可以作为微服务运行，也可以嵌入到您自己的服务器中：
193
-
193
+
194
+ ## 仓库支持
195
+
196
+ | 仓库 | 软件包格式 | 时间序列 | 可用数据 |
197
+ |----------|---------------|-------------|----------------|
198
+ | `npm` | `express`, `@scope/pkg` | 是 (549 天) | 最近一天、最近一周、最近一个月 |
199
+ | `pypi` | `requests` | 是 (180 天) | 最近一天、最近一周、最近一个月、总数 |
200
+ | `nuget` | `Newtonsoft.Json` | No | 总数 |
201
+ | `vscode` | `publisher.extension` | No | 总数（安装量）、评分、趋势 |
202
+ | `docker` | `namespace/repo` | No | 总数（拉取次数）、星级 |
203
+
204
+ ## 内置可靠性
205
+
206
+ - 自动重试，并在遇到 429/5xx 错误时采用指数退避策略
207
+ - 尊重 `Retry-After` 头部信息
208
+ - 批量请求的并发限制
209
+ - 可选的 TTL 缓存（可插拔，通过 `StatsCache` 接口，您可以自定义 Redis 或文件后端）
210
+
211
+ ## REST API 服务器
212
+
213
+ 可以作为微服务运行，也可以嵌入到您自己的服务器中：
214
+
194
215
  ```bash
195
- # CLI
196
216
  registry-stats serve --port 3000
197
217
  ```
198
-
218
+
199
219
  ```
200
220
  GET /stats/:package # all registries
201
221
  GET /stats/:registry/:package # single registry
202
222
  GET /compare/:package?registries=npm,pypi
203
223
  GET /range/:registry/:package?start=YYYY-MM-DD&end=YYYY-MM-DD&format=json|csv|chart
204
224
  ```
205
-
206
- 用于自定义服务器或无服务器环境的编程用法：
207
-
225
+
226
+ 用于自定义服务器或无服务器环境的编程用法：
227
+
208
228
  ```typescript
209
229
  import { createHandler, serve } from '@mcptoolshop/registry-stats';
210
230
 
@@ -216,9 +236,9 @@ import { createServer } from 'node:http';
216
236
  const handler = createHandler();
217
237
  createServer(handler).listen(3000);
218
238
  ```
219
-
220
- ## 自定义仓库
221
-
239
+
240
+ ## 自定义仓库
241
+
222
242
  ```typescript
223
243
  import { registerProvider, type RegistryProvider } from '@mcptoolshop/registry-stats';
224
244
 
@@ -239,19 +259,59 @@ const cargo: RegistryProvider = {
239
259
  registerProvider(cargo);
240
260
  await stats('cargo', 'serde');
241
261
  ```
262
+
263
+ ## 代码仓库结构
264
+
265
+ ```
266
+ registry-stats/
267
+ ├── src/ # TypeScript engine (published to npm)
268
+ ├── site/ # Astro dashboard + landing page (deployed to GitHub Pages)
269
+ ├── desktop/ # WinUI 3 desktop app (.NET 10 MAUI)
270
+ └── test/ # Library tests (vitest)
271
+ ```
272
+
273
+ ## 开发
274
+
275
+ ```bash
276
+ # Engine
277
+ npm install && npm run build && npm test
242
278
 
243
- ## 网站
244
-
245
- 网站和主页位于 `site/` 目录下。
246
-
247
- - 开发：`npm run site:dev`
248
- - 构建：`npm run site:build`
249
- - 预览：`npm run site:preview`
250
-
251
- ## 许可证
252
-
253
- MIT
279
+ # Dashboard (dev server)
280
+ npm run site:dev
254
281
 
282
+ # Dashboard (production build)
283
+ npm run site:build
284
+ ```
285
+
286
+ ## 安全性和数据范围
287
+
288
+ | 方面 | 详细信息 |
289
+ |--------|--------|
290
+ | **Data touched** | 从 npm、PyPI、NuGet、VS Code Marketplace 和 Docker Hub 获取公开的下载统计数据。可选的内存缓存。 |
291
+ | **Data NOT touched** | 没有遥测。没有分析。没有凭证存储。没有用户数据。没有文件写入。 |
292
+ | **Permissions** | 读取：通过 HTTPS 的公开注册中心 API。写入：仅 stdout/stderr。 |
293
+ | **Network** | 向公开注册中心 API 的 HTTPS 出站连接。可选的本地 REST 服务器。 |
294
+ | **Telemetry** | 未收集或发送任何数据。 |
295
+
296
+ 请参阅 [SECURITY.md](SECURITY.md) 以获取漏洞报告。
297
+
298
+ ## 评分卡
299
+
300
+ | 类别 | 评分 |
301
+ |----------|-------|
302
+ | A. 安全性 | 10 |
303
+ | B. 错误处理 | 10 |
304
+ | C. 运维文档 | 10 |
305
+ | D. 发布规范 | 10 |
306
+ | E. 身份验证（软性） | 10 |
307
+ | **Overall** | **50/50** |
308
+
309
+ > 完整审计：[SHIP_GATE.md](SHIP_GATE.md) · [SCORECARD.md](SCORECARD.md)
310
+
311
+ ## 许可证
312
+
313
+ MIT
314
+
255
315
  ---
256
-
257
- 由 <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a> 构建。
316
+
317
+ 由 <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a> 构建。