@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.it.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> | <strong>Italiano</strong> | <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.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.md">English</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
- Se pubblicate su npm, PyPI, NuGet, VS Code Marketplace o Docker Hub, attualmente avete bisogno di cinque API diverse per rispondere alla domanda "quanti download ho avuto questo mese?". Questa libreria vi offre un'unica interfaccia per tutte, sia come interfaccia a riga di comando (CLI) che come API programmatica.
33
-
34
- Nessuna dipendenza. Utilizza la funzione nativa `fetch()`. Node 18 o superiore.
35
-
36
- ## Installazione
37
-
33
+
34
+ Pubblica su npm, PyPI, NuGet, il Marketplace di VS Code e Docker Hub. Attualmente, rispondere alla domanda "come stanno andando i miei pacchetti?" significa controllare cinque siti diversi. **registry-stats** è la piattaforma completa: un motore TypeScript (CLI + API + server REST), una dashboard web interattiva e un'applicazione desktop nativa per Windows, il tutto proveniente da un unico repository.
35
+
36
+ Nessuna dipendenza a runtime. Utilizza la funzione nativa `fetch()`. Node 18 o superiore.
37
+
38
+ ## Cosa c'è all'interno
39
+
40
+ | Livello | Cosa fa |
41
+ |-------|-------------|
42
+ | **Engine** | Libreria TypeScript + CLI + server REST. Interroga cinque registri con un'unica interfaccia. Pubblicato su npm come `@mcptoolshop/registry-stats`. |
43
+ | **Dashboard** | Applicazione web basata su Astro. Panoramica, andamento, stato dei dati, classifica con grafici a linee. Ricostruita settimanalmente tramite CI. |
44
+ | **Desktop** | Applicazione nativa per Windows realizzata con WinUI 3 + WebView2. Include la dashboard offline e scarica le statistiche in tempo reale su richiesta. |
45
+
46
+ ## Dashboard
47
+
48
+ Una dashboard con aggiornamenti automatici è disponibile all'indirizzo [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/).
49
+
50
+ - **Panoramica** — breve resoconto settimanale: registro principale, pacchetto principale, pacchetto con maggiore crescita, concentrazione del portafoglio, affidabilità dei dati.
51
+ - **Andamento** — pacchetti con maggiore crescita, pacchetti in calo e nuovi pacchetti attivi (npm degli ultimi 7 giorni rispetto ai 7 giorni precedenti).
52
+ - **Stato dei dati** — copertura per ogni registro, badge di affidabilità (ok / parziale / mancante), dettagli degli errori espandibili.
53
+ - **Variazioni** — monitoraggio settimana per settimana per i registri con dati cumulativi (Docker, VS Code, NuGet).
54
+ - **Classifica** — tutti i pacchetti classificati per download settimanali con grafici a linee a 30 giorni per ogni riga.
55
+ - **Tema chiaro/scuro** — segue le preferenze del sistema.
56
+
57
+ I dati vengono scaricati al momento della compilazione e la dashboard viene ricostruita settimanalmente tramite CI (il lunedì alle 06:00 UTC). Configura i pacchetti da monitorare in `site/src/data/packages.json`.
58
+
59
+ ## Applicazione Desktop
60
+
61
+ Un'applicazione nativa per Windows che integra la dashboard in un ambiente WebView2 locale:
62
+
63
+ - **Funziona offline** — include file HTML/CSS/JS; funziona senza connessione a Internet.
64
+ - **Aggiornamento in tempo reale** — scarica `stats.json` da GitHub Pages su richiesta.
65
+ - **Esportazione CSV** — esporta i dati della classifica con un solo clic.
66
+ - **Pacchetto MSIX** — creato e firmato tramite CI utilizzando `desktop-ci.yml`.
67
+
68
+ Il codice sorgente dell'applicazione desktop si trova nella cartella `desktop/`. Realizzata con .NET 10 MAUI e destinata a WinUI 3.
69
+
70
+ ## Installazione
71
+
38
72
  ```bash
39
73
  npm install @mcptoolshop/registry-stats
40
74
  ```
41
-
42
- ## CLI (Interfaccia a riga di comando)
43
-
75
+
76
+ ## CLI (Interfaccia a riga di comando)
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
- ## File di configurazione
95
-
96
- Create un file `registry-stats.config.json` nella directory principale del vostro progetto (oppure eseguite `registry-stats --init`):
97
-
115
+
116
+ ## File di configurazione
117
+
118
+ Create un file `registry-stats.config.json` nella directory principale del vostro progetto (oppure eseguite `registry-stats --init`):
119
+
98
120
  ```json
99
121
  {
100
122
  "registries": ["npm", "pypi", "nuget", "vscode", "docker"],
@@ -113,11 +135,11 @@ Create un file `registry-stats.config.json` nella directory principale del vostr
113
135
  "concurrency": 5
114
136
  }
115
137
  ```
116
-
117
- Eseguite `registry-stats` senza argomenti per ottenere le statistiche per tutti i pacchetti configurati. La CLI cerca il file di configurazione a partire dalla directory corrente.
118
-
119
- La configurazione è disponibile anche tramite API programmatica:
120
-
138
+
139
+ Eseguite `registry-stats` senza argomenti per ottenere le statistiche per tutti i pacchetti configurati. La CLI cerca il file di configurazione a partire dalla directory corrente.
140
+
141
+ La configurazione è disponibile anche tramite API programmatica:
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 programmatica
130
-
150
+
151
+ ## API programmatica
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
- ## Supporto per i registri
174
-
175
- | Registro | Formato del pacchetto | Serie temporali | Dati disponibili |
176
- | ---------- | --------------- | ------------- | ---------------- |
177
- | `npm` | `express`, `@scope/pkg` | Sì (549 giorni) | giorno precedente, settimana precedente, mese precedente |
178
- | `pypi` | `requests` | Sì (180 giorni) | giorno precedente, settimana precedente, mese precedente, totale |
179
- | `nuget` | `Newtonsoft.Json` | No | totale |
180
- | `vscode` | `publisher.extension` | No | totale (installazioni), valutazione, tendenze |
181
- | `docker` | `namespace/repo` | No | totale (download), stelle |
182
-
183
- ## Affidabilità integrata
184
-
185
- - Tentativi automatici con backoff esponenziale in caso di errori 429/5xx
186
- - Rispetta le intestazioni `Retry-After`
187
- - Limitazione della concorrenza per richieste di massa
188
- - Cache TTL opzionale (configurabile: potete fornire la vostra implementazione Redis/file tramite l'interfaccia `StatsCache`)
189
-
190
- ## Server API REST
191
-
192
- Eseguite come microservizio o integrate nel vostro server:
193
-
193
+
194
+ ## Supporto per i registri
195
+
196
+ | Registro | Formato del pacchetto | Serie temporali | Dati disponibili |
197
+ |----------|---------------|-------------|----------------|
198
+ | `npm` | `express`, `@scope/pkg` | Sì (549 giorni) | giorno precedente, settimana precedente, mese precedente |
199
+ | `pypi` | `requests` | Sì (180 giorni) | giorno precedente, settimana precedente, mese precedente, totale |
200
+ | `nuget` | `Newtonsoft.Json` | No | totale |
201
+ | `vscode` | `publisher.extension` | No | totale (installazioni), valutazione, tendenze |
202
+ | `docker` | `namespace/repo` | No | totale (download), stelle |
203
+
204
+ ## Affidabilità integrata
205
+
206
+ - Tentativi automatici con backoff esponenziale in caso di errori 429/5xx
207
+ - Rispetta le intestazioni `Retry-After`
208
+ - Limitazione della concorrenza per richieste di massa
209
+ - Cache TTL opzionale (configurabile: potete fornire la vostra implementazione Redis/file tramite l'interfaccia `StatsCache`)
210
+
211
+ ## Server API REST
212
+
213
+ Eseguite come microservizio o integrate nel vostro server:
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
- Utilizzo programmatica per server personalizzati o serverless:
207
-
225
+
226
+ Utilizzo programmatica per server personalizzati o serverless:
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
- ## Registri personalizzati
221
-
239
+
240
+ ## Registri personalizzati
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
+ ## Struttura del Repository
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
+ ## Sviluppo
274
+
275
+ ```bash
276
+ # Engine
277
+ npm install && npm run build && npm test
242
278
 
243
- ## Sito web
244
-
245
- Il sito web e la documentazione si trovano nella directory `site/`.
246
-
247
- - Sviluppo: `npm run site:dev`
248
- - Build: `npm run site:build`
249
- - Anteprima: `npm run site:preview`
250
-
251
- ## Licenza
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
+ ## Sicurezza e ambito dei dati
287
+
288
+ | Aspetto | Dettaglio |
289
+ |--------|--------|
290
+ | **Data touched** | Statistiche di download pubbliche da npm, PyPI, NuGet, VS Code Marketplace, Docker Hub. Cache in memoria (opzionale). |
291
+ | **Data NOT touched** | Nessuna telemetria. Nessuna analisi. Nessun archivio di credenziali. Nessun dato utente. Nessuna scrittura di file. |
292
+ | **Permissions** | Lettura: API pubbliche dei registri tramite HTTPS. Scrittura: solo stdout/stderr. |
293
+ | **Network** | Uscite HTTPS verso le API pubbliche dei registri. Server REST locale opzionale. |
294
+ | **Telemetry** | Nessuno raccolto o inviato. |
295
+
296
+ Consulta [SECURITY.md](SECURITY.md) per la segnalazione di vulnerabilità.
297
+
298
+ ## Tabella di valutazione
299
+
300
+ | Categoria | Punteggio |
301
+ |----------|-------|
302
+ | A. Sicurezza | 10 |
303
+ | B. Gestione degli errori | 10 |
304
+ | C. Documentazione per gli operatori | 10 |
305
+ | D. Igiene della distribuzione | 10 |
306
+ | E. Identità (soft) | 10 |
307
+ | **Overall** | **50/50** |
308
+
309
+ > Analisi completa: [SHIP_GATE.md](SHIP_GATE.md) · [SCORECARD.md](SCORECARD.md)
310
+
311
+ ## Licenza
312
+
313
+ MIT
314
+
255
315
  ---
256
-
257
- Creato da <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>
316
+
317
+ Creato da <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a>