@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.es.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> | <strong>Español</strong> | <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.zh.md">中文</a> | <a href="README.md">English</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
- Si publicas en npm, PyPI, NuGet, el Marketplace de VS Code o Docker Hub, actualmente necesitas cinco API diferentes para responder a la pregunta "¿cuántas descargas he tenido este mes?". Esta biblioteca te proporciona una única interfaz para todas ellas, ya sea como una herramienta de línea de comandos (CLI) o como una API programática.
33
-
34
- Sin dependencias. Utiliza la función nativa `fetch()`. Node 18+.
35
-
36
- ## Instalación
37
-
33
+
34
+ Publica en npm, PyPI, NuGet, el Marketplace de VS Code y Docker Hub. Actualmente, responder a la pregunta "¿cómo le están yendo a mis paquetes?" implica consultar cinco sitios diferentes. **registry-stats** es la plataforma completa: un motor de TypeScript (CLI + API + servidor REST), un panel web en tiempo real y una aplicación de escritorio nativa para Windows, todo desde un único repositorio.
35
+
36
+ No tiene dependencias de tiempo de ejecución. Utiliza `fetch()` nativo. Node 18+.
37
+
38
+ ## ¿Qué hay dentro?
39
+
40
+ | Capa | ¿Qué hace? |
41
+ |-------|-------------|
42
+ | **Engine** | Biblioteca de TypeScript + CLI + servidor REST. Consulta cinco registros con una única interfaz. Publicado en npm como `@mcptoolshop/registry-stats`. |
43
+ | **Dashboard** | Aplicación web impulsada por Astro. Resúmenes ejecutivos, indicadores de crecimiento, estado de los datos, tabla de clasificación con gráficos. Se reconstruye semanalmente mediante CI. |
44
+ | **Desktop** | Aplicación nativa para Windows con WinUI 3 + WebView2. Incluye el panel sin conexión y descarga las estadísticas en tiempo real bajo demanda. |
45
+
46
+ ## Panel
47
+
48
+ Un panel de estadísticas que se actualiza automáticamente se encuentra en [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/).
49
+
50
+ - **Resumen ejecutivo** — Narrativa semanal en una frase: registro principal, paquete principal, mayor crecimiento, concentración de la cartera, confianza de los datos.
51
+ - **Indicador de crecimiento** — Paquetes con mayor crecimiento, mayor disminución y nuevos paquetes activos (npm 7 días vs. los 7 días anteriores).
52
+ - **Estado de los datos** — Cobertura por registro, insignias de confianza (correcto / parcial / faltante), detalles de errores ampliables.
53
+ - **Deltas de instantáneas** — Seguimiento semanal para registros solo acumulativos (Docker, VS Code, NuGet).
54
+ - **Tabla de clasificación** — Todos los paquetes clasificados por descargas semanales con gráficos de 30 días por fila.
55
+ - **Tema claro/oscuro** — Sigue la preferencia del sistema.
56
+
57
+ Los datos se obtienen en el momento de la compilación y se reconstruyen semanalmente mediante CI (los lunes a las 06:00 UTC). Configure los paquetes rastreados en `site/src/data/packages.json`.
58
+
59
+ ## Aplicación de escritorio
60
+
61
+ Una aplicación nativa para Windows que integra el panel en un entorno WebView2 local:
62
+
63
+ - **Funciona sin conexión** — Incluye HTML/CSS/JS empaquetados; funciona sin internet.
64
+ - **Actualización en tiempo real** — Descarga `stats.json` de GitHub Pages bajo demanda.
65
+ - **Exportación a CSV** — Exporta los datos de la tabla de clasificación con un solo clic.
66
+ - **Empaquetado MSIX** — Se construye y firma en CI mediante `desktop-ci.yml`.
67
+
68
+ El código fuente de la aplicación de escritorio se encuentra en `desktop/`. Se construyó con .NET 10 MAUI y apunta a WinUI 3.
69
+
70
+ ## Instalación
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
- ## Archivo de configuración
95
-
96
- Crea un archivo `registry-stats.config.json` en la raíz de tu proyecto (o ejecuta `registry-stats --init`):
97
-
115
+
116
+ ## Archivo de configuración
117
+
118
+ Crea un archivo `registry-stats.config.json` en la raíz de tu proyecto (o ejecuta `registry-stats --init`):
119
+
98
120
  ```json
99
121
  {
100
122
  "registries": ["npm", "pypi", "nuget", "vscode", "docker"],
@@ -113,11 +135,11 @@ Crea un archivo `registry-stats.config.json` en la raíz de tu proyecto (o ejecu
113
135
  "concurrency": 5
114
136
  }
115
137
  ```
116
-
117
- Ejecuta `registry-stats` sin argumentos para obtener las estadísticas de todos los paquetes configurados. La CLI busca el archivo de configuración desde el directorio actual.
118
-
119
- La configuración también está disponible de forma programática:
120
-
138
+
139
+ Ejecuta `registry-stats` sin argumentos para obtener las estadísticas de todos los paquetes configurados. La CLI busca el archivo de configuración desde el directorio actual.
140
+
141
+ La configuración también está disponible de forma programática:
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
- ## Soporte para registros
174
-
175
- | Registro | Formato del paquete | Series de tiempo | Datos disponibles |
176
- | ---------- | --------------- | ------------- | ---------------- |
177
- | `npm` | `express`, `@scope/pkg` | Sí (549 días) | último día, última semana, último mes |
178
- | `pypi` | `requests` | Sí (180 días) | último día, última semana, último mes, total |
179
- | `nuget` | `Newtonsoft.Json` | No | total |
180
- | `vscode` | `publisher.extension` | No | total (instalaciones), calificación, tendencias |
181
- | `docker` | `namespace/repo` | No | total (descargas), estrellas |
182
-
183
- ## Fiabilidad integrada
184
-
185
- - Reintentos automáticos con retroceso exponencial en caso de errores 429/5xx.
186
- - Respeta los encabezados `Retry-After`.
187
- - Limitación de concurrencia para solicitudes masivas.
188
- - Caché TTL opcional (plug-in: proporciona tu propio backend de Redis/archivo a través de la interfaz `StatsCache`).
189
-
190
- ## Servidor de API REST
191
-
192
- Ejecútalo como un microservicio o intégralo en tu propio servidor:
193
-
193
+
194
+ ## Soporte para registros
195
+
196
+ | Registro | Formato del paquete | Series de tiempo | Datos disponibles |
197
+ |----------|---------------|-------------|----------------|
198
+ | `npm` | `express`, `@scope/pkg` | Sí (549 días) | último día, última semana, último mes |
199
+ | `pypi` | `requests` | Sí (180 días) | último día, última semana, último mes, total |
200
+ | `nuget` | `Newtonsoft.Json` | No | total |
201
+ | `vscode` | `publisher.extension` | No | total (instalaciones), calificación, tendencias |
202
+ | `docker` | `namespace/repo` | No | total (descargas), estrellas |
203
+
204
+ ## Fiabilidad integrada
205
+
206
+ - Reintentos automáticos con retroceso exponencial en caso de errores 429/5xx.
207
+ - Respeta los encabezados `Retry-After`.
208
+ - Limitación de concurrencia para solicitudes masivas.
209
+ - Caché TTL opcional (plug-in: proporciona tu propio backend de Redis/archivo a través de la interfaz `StatsCache`).
210
+
211
+ ## Servidor de API REST
212
+
213
+ Ejecútalo como un microservicio o intégralo en tu propio 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 o sin servidor:
207
-
225
+
226
+ Uso programático para servidores personalizados o sin 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
+ ## Estructura del repositorio
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
+ ## Desarrollo
274
+
275
+ ```bash
276
+ # Engine
277
+ npm install && npm run build && npm test
242
278
 
243
- ## Sitio web
244
-
245
- La documentación y la página de inicio se encuentran en el directorio `site/`.
246
-
247
- - Desarrollo: `npm run site:dev`
248
- - Compilación: `npm run site:build`
249
- - Previsualización: `npm run site:preview`
250
-
251
- ## Licencia
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
+ ## Seguridad y alcance de los datos
287
+
288
+ | Aspecto | Detalle |
289
+ |--------|--------|
290
+ | **Data touched** | Estadísticas de descarga pública de npm, PyPI, NuGet, Marketplace de VS Code, Docker Hub. Caché en memoria (opcional). |
291
+ | **Data NOT touched** | Sin telemetría. Sin análisis. Sin almacenamiento de credenciales. Sin datos de usuario. Sin escrituras de archivos. |
292
+ | **Permissions** | Lectura: APIs públicas de registros a través de HTTPS. Escritura: solo stdout/stderr. |
293
+ | **Network** | Conexiones HTTPS salientes a APIs públicas de registros. Servidor REST opcional en localhost. |
294
+ | **Telemetry** | Ninguno recopilado ni enviado. |
295
+
296
+ Consulte [SECURITY.md](SECURITY.md) para informar sobre vulnerabilidades.
297
+
298
+ ## Tabla de puntuación
299
+
300
+ | Categoría | Puntuación |
301
+ |----------|-------|
302
+ | A. Seguridad | 10 |
303
+ | B. Manejo de errores | 10 |
304
+ | C. Documentación para operadores | 10 |
305
+ | D. Higiene de implementación | 10 |
306
+ | E. Identidad (suave) | 10 |
307
+ | **Overall** | **50/50** |
308
+
309
+ > Auditoría completa: [SHIP_GATE.md](SHIP_GATE.md) · [SCORECARD.md](SCORECARD.md)
310
+
311
+ ## Licencia
312
+
313
+ MIT
314
+
255
315
  ---
256
-
257
- Creado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
316
+
317
+ Creado por <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>