@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.ja.md CHANGED
@@ -1,46 +1,80 @@
1
- <p align="center">
2
- <a href="README.md">English</a> | <strong>日本語</strong> | <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.pt-BR.md">Português</a>
3
- </p>
4
-
1
+ <p align="center">
2
+ <a href="README.md">English</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.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に公開している場合、現在、"今月ダウンロード数は何件ですか？"という質問に答えるために、5つの異なるAPIが必要になります。このライブラリは、それらすべてに対して、CLIまたはプログラムAPIとして、単一のインターフェースを提供します。
33
-
34
- 依存関係はゼロです。ネイティブの`fetch()`を使用します。Node 18以降が必要です。
35
-
36
- ## インストール
37
-
33
+
34
+ npm、PyPI、NuGet、Visual Studio Code Marketplace、Docker Hub などのプラットフォームに公開できます。現在、「私のパッケージの状況はどうなっているか？」を知るには、5つの異なるサイトを確認する必要があります。**registry-stats** は、それらを統合したプラットフォームです。TypeScript で構築されたエンジン（CLI + API + REST サーバー）、リアルタイムの Web ダッシュボード、そしてネイティブの Windows デスクトップ アプリケーション。これらはすべて、1つのリポジトリから提供されます。
35
+
36
+ 実行時の依存関係はありません。ネイティブの `fetch()` を使用します。Node 18 以降が必要です。
37
+
38
+ ## 構成要素
39
+
40
+ | レイヤー | 機能 |
41
+ |-------|-------------|
42
+ | **Engine** | TypeScript ライブラリ + CLI + REST サーバー。1つのインターフェースで、5つのレジストリをクエリできます。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
+ - **主要な指標**：毎週の状況を1文でまとめた情報。トップのレジストリ、パッケージ、成長率、ポートフォリオの集中度、データの信頼性。
51
+ - **成長状況**：トップの成長パッケージ、減少パッケージ、新規アクティブパッケージ（npm の過去 7 日と現在の 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
+ ダッシュボードをローカルの WebView2 シェルでラップした、ネイティブの Windows アプリケーションです。
62
+
63
+ - **オフライン対応**：HTML/CSS/JS がバンドルされているため、インターネット接続なしで動作します。
64
+ - **リアルタイム更新**：GitHub Pages から `stats.json` をオンデマンドで取得します。
65
+ - **CSV エクスポート**：ランキングデータをワンクリックで CSV 形式でエクスポートできます。
66
+ - **MSIX パッケージ**：CI で `desktop-ci.yml` を使用してビルドおよび署名されます。
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`を実行します。CLIは、現在の作業ディレクトリから上位のディレクトリを検索し、最も近い設定ファイルを見つけます。
118
-
119
- 設定ファイルは、プログラム的に利用することも可能です。
120
-
138
+
139
+ 設定されたすべてのパッケージの統計情報を取得するには、引数なしで`registry-stats`を実行します。CLIは、現在の作業ディレクトリから上位のディレクトリを検索し、最も近い設定ファイルを見つけます。
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日間) | lastDay (直近1日), lastWeek (直近1週間), lastMonth (直近1ヶ月) |
178
- | `pypi` | `requests` | はい (180日間) | lastDay (直近1日), lastWeek (直近1週間), lastMonth (直近1ヶ月), total (合計) |
179
- | `nuget` | `Newtonsoft.Json` | No | total (合計) |
180
- | `vscode` | `publisher.extension` | No | total (インストール数), rating (評価), trends (傾向) |
181
- | `docker` | `namespace/repo` | No | total (ダウンロード数), stars (スター数) |
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日間) | lastDay (直近1日), lastWeek (直近1週間), lastMonth (直近1ヶ月) |
199
+ | `pypi` | `requests` | はい (180日間) | lastDay (直近1日), lastWeek (直近1週間), lastMonth (直近1ヶ月), total (合計) |
200
+ | `nuget` | `Newtonsoft.Json` | No | total (合計) |
201
+ | `vscode` | `publisher.extension` | No | total (インストール数), rating (評価), trends (傾向) |
202
+ | `docker` | `namespace/repo` | No | total (ダウンロード数), stars (スター数) |
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、Visual Studio Code Marketplace、Docker Hub から取得する公開ダウンロード統計。オプションで、メモリ内キャッシュを使用します。 |
291
+ | **Data NOT touched** | テレメトリー、分析、認証情報の保存、ユーザーデータ、ファイル書き込みは一切行いません。 |
292
+ | **Permissions** | 読み込み：HTTPS を使用した公開レジストリ API。書き込み：標準出力/標準エラー出力のみ。 |
293
+ | **Network** | HTTPS を使用して公開レジストリ API にアクセスします。オプションで、ローカルの 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>によって作成されました。
package/README.md CHANGED
@@ -1,38 +1,71 @@
1
- <p align="center">
2
- <strong>English</strong> | <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.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.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;
27
- <a href="#dashboard">Dashboard</a> &middot;
28
+ <a href="#config-file">Config</a> &middot;
28
29
  <a href="#license">License</a>
29
30
  </p>
30
31
 
31
32
  ---
32
33
 
33
- If you publish to npm, PyPI, NuGet, VS Code Marketplace, or Docker Hub, you currently need five different APIs to answer "how many downloads did I get this month?" This library gives you one interface for all of them — as a CLI or programmatic API.
34
+ You publish to npm, PyPI, NuGet, the VS Code Marketplace, and Docker Hub. Right now, answering "how are my packages doing?" means checking five different sites. **registry-stats** is the complete platform: a TypeScript engine (CLI + API + REST server), a live web dashboard, and a native Windows desktop app — all from one repo.
35
+
36
+ Zero runtime dependencies. Uses native `fetch()`. Node 18+.
37
+
38
+ ## What's inside
39
+
40
+ | Layer | What it does |
41
+ |-------|-------------|
42
+ | **Engine** | TypeScript library + CLI + REST server. Query five registries with one interface. Published to npm as `@mcptoolshop/registry-stats`. |
43
+ | **Dashboard** | Astro-powered web app. Executive snapshots, growth pulse, data health, leaderboard with sparklines. Rebuilt weekly by CI. |
44
+ | **Desktop** | WinUI 3 + WebView2 native Windows app. Bundles the dashboard offline, fetches live stats on demand. |
45
+
46
+ ## Dashboard
47
+
48
+ A self-updating stats dashboard lives at [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/).
34
49
 
35
- Zero dependencies. Uses native `fetch()`. Node 18+.
50
+ - **Executive snapshot** — one-sentence weekly narrative: top registry, top package, top gainer, portfolio concentration, data confidence
51
+ - **Growth Pulse** — top gainers, decliners, and newly active packages (npm 7d vs prior 7d)
52
+ - **Data Health** — per-registry coverage, confidence badges (ok / partial / missing), expandable error details
53
+ - **Snapshot deltas** — week-over-week tracking for cumulative-only registries (Docker, VS Code, NuGet)
54
+ - **Leaderboard** — all packages ranked by weekly downloads with per-row 30-day sparklines
55
+ - **Dark / light theme** — follows system preference
56
+
57
+ Data is fetched at build time and rebuilt weekly by CI (Mondays 06:00 UTC). Configure tracked packages in `site/src/data/packages.json`.
58
+
59
+ ## Desktop App
60
+
61
+ A native Windows app that wraps the dashboard in a local WebView2 shell:
62
+
63
+ - **Offline-capable** — ships bundled HTML/CSS/JS; works without internet
64
+ - **Live refresh** — fetches `stats.json` from GitHub Pages on demand
65
+ - **CSV export** — export leaderboard data with one click
66
+ - **MSIX packaged** — built and signed in CI via `desktop-ci.yml`
67
+
68
+ The desktop source lives in `desktop/`. Built with .NET 10 MAUI targeting WinUI 3.
36
69
 
37
70
  ## Install
38
71
 
@@ -53,10 +86,6 @@ registry-stats express
53
86
 
54
87
  # Time series with monthly breakdown + trend
55
88
  registry-stats express -r npm --range 2025-01-01:2025-06-30
56
- # 2025-01 142,359,021
57
- # 2025-02 147,522,528
58
- # ...
59
- # Total: 448,383,383 Avg/day: 4,982,038 Trend: flat (-0.46%)
60
89
 
61
90
  # Raw JSON output
62
91
  registry-stats express -r npm --json
@@ -75,14 +104,6 @@ registry-stats
75
104
 
76
105
  # Compare across registries
77
106
  registry-stats express --compare
78
- # express — comparison
79
- #
80
- # Metric npm pypi
81
- # ─────────────────────────────────
82
- # Total - -
83
- # Month 283,472 47,201
84
- # Week 67,367 11,800
85
- # Day 11,566 1,686
86
107
 
87
108
  # Export as CSV or chart-friendly JSON
88
109
  registry-stats express -r npm --range 2025-01-01:2025-06-30 --format csv
@@ -162,7 +183,6 @@ calc.toChartData(daily, 'express'); // { labels: [...], datasets: [{ labe
162
183
 
163
184
  // Comparison — same package across registries
164
185
  const comparison = await stats.compare('express');
165
- // → { package: 'express', registries: { npm: {...}, pypi: {...} }, fetchedAt: '...' }
166
186
  await stats.compare('express', ['npm', 'pypi']); // specific registries only
167
187
 
168
188
  // Caching (5 min TTL, in-memory)
@@ -193,7 +213,6 @@ await stats('npm', 'express', { cache }); // cache hit
193
213
  Run as a microservice or embed in your own server:
194
214
 
195
215
  ```bash
196
- # CLI
197
216
  registry-stats serve --port 3000
198
217
  ```
199
218
 
@@ -241,25 +260,28 @@ registerProvider(cargo);
241
260
  await stats('cargo', 'serde');
242
261
  ```
243
262
 
244
- ## Dashboard
263
+ ## Repo Structure
245
264
 
246
- A self-updating stats dashboard ships with the library at [`/dashboard/`](https://mcp-tool-shop-org.github.io/registry-stats/dashboard/).
247
-
248
- - **Executive snapshot** — one-sentence weekly narrative (top registry, top package, top gainer, concentration, data confidence)
249
- - **Growth Pulse** — top gainers, decliners, and newly active packages (npm 7d vs prior 7d)
250
- - **Data Health** — per-registry coverage, confidence badges, expandable error details
251
- - **Breakdown** — per-registry bars and 30-day aggregate sparkline
252
- - **Leaderboard** — all packages ranked by weekly downloads with per-row 30d sparklines
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
+ ```
253
272
 
254
- Data is fetched at build time via `npm run fetch-stats` and rebuilt weekly by CI (Mondays 06:00 UTC). Dark and light themes supported.
273
+ ## Development
255
274
 
256
- ## Website
275
+ ```bash
276
+ # Engine
277
+ npm install && npm run build && npm test
257
278
 
258
- Docs / landing page lives in `site/`.
279
+ # Dashboard (dev server)
280
+ npm run site:dev
259
281
 
260
- - Dev: `npm run site:dev`
261
- - Build: `npm run site:build`
262
- - Preview: `npm run site:preview`
282
+ # Dashboard (production build)
283
+ npm run site:build
284
+ ```
263
285
 
264
286
  ## Security & Data Scope
265
287