@mcptoolshop/registry-stats 3.2.1 → 3.2.3

package/dist/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { writeFileSync, existsSync as existsSync2 } from "fs";
-import { resolve as resolve2 } from "path";
+import { writeFileSync, readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import { resolve as resolve2, dirname as dirname2, join } from "path";
+import { fileURLToPath } from "url";
 
 // src/types.ts
 var RegistryError = class extends Error {
@@ -20,9 +21,10 @@ var RETRYABLE = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
 var MAX_RETRIES = 3;
 var BASE_DELAY = 1e3;
 var registryLocks = /* @__PURE__ */ new Map();
+var MAX_LOCK_ENTRIES = 50;
 var REGISTRY_DELAYS = {
-  npm: 400,
-  // ~2.5 req/s — safe for 54+ scoped packages
+  npm: 800,
+  // ~1.25 req/s — safe for 91+ scoped packages (429s at 400ms)
   pypi: 2200,
   // 30 req/60s = 1 per 2s, with headroom
   docker: 4e3
@@ -34,13 +36,27 @@ function acquireSlot(registry) {
   const prev = registryLocks.get(registry) ?? Promise.resolve();
   const slot = prev.then(() => new Promise((r) => setTimeout(r, minDelay)));
   registryLocks.set(registry, slot);
+  if (registryLocks.size > MAX_LOCK_ENTRIES) {
+    const oldest = registryLocks.keys().next().value;
+    if (oldest !== void 0) registryLocks.delete(oldest);
+  }
   return prev;
 }
-async function fetchWithRetry(url, registry, init) {
+async function fetchRetryCore(url, registry, init, preRequest) {
   let lastError;
   for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    await acquireSlot(registry);
-    const res = await fetch(url, { signal: AbortSignal.timeout(3e4), ...init });
+    if (preRequest) await preRequest();
+    let res;
+    try {
+      res = await fetch(url, { signal: AbortSignal.timeout(3e4), ...init });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      lastError = new RegistryError(registry, 0, `Network error: ${message} \u2014 ${url}`);
+      if (attempt === MAX_RETRIES) break;
+      const backoff2 = BASE_DELAY * Math.pow(2, attempt);
+      await new Promise((r) => setTimeout(r, backoff2));
+      continue;
+    }
     if (res.status === 404) return null;
     if (res.ok) return res.json();
     const retryAfter = res.headers.get("retry-after");
@@ -57,41 +73,25 @@ async function fetchWithRetry(url, registry, init) {
     const delay = Math.max(backoff, retryAfterMs);
     await new Promise((r) => setTimeout(r, delay));
   }
-  throw lastError;
+  throw lastError ?? new RegistryError(registry, 0, `Fetch failed after ${MAX_RETRIES} retries: ${url}`);
+}
+async function fetchWithRetry(url, registry, init) {
+  return fetchRetryCore(url, registry, init, () => acquireSlot(registry));
 }
 async function fetchDirect(url, registry, init) {
-  let lastError;
-  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
-    const res = await fetch(url, { signal: AbortSignal.timeout(3e4), ...init });
-    if (res.status === 404) return null;
-    if (res.ok) return res.json();
-    const retryAfter = res.headers.get("retry-after");
-    const retryAfterSeconds = retryAfter ? parseInt(retryAfter, 10) : void 0;
-    lastError = new RegistryError(
-      registry,
-      res.status,
-      `${res.statusText}: ${url}`,
-      retryAfterSeconds
-    );
-    if (!RETRYABLE.has(res.status) || attempt === MAX_RETRIES) break;
-    const backoff = BASE_DELAY * Math.pow(2, attempt);
-    const retryAfterMs = retryAfterSeconds ? retryAfterSeconds * 1e3 : 0;
-    const delay = Math.max(backoff, retryAfterMs);
-    await new Promise((r) => setTimeout(r, delay));
-  }
-  throw lastError;
+  return fetchRetryCore(url, registry, init);
 }
 
 // src/providers/npm.ts
 var API = "https://api.npmjs.org/downloads";
 var npm = {
   name: "npm",
-  async getStats(pkg) {
+  async getStats(pkg2) {
     const end = /* @__PURE__ */ new Date();
     const start = new Date(end);
     start.setDate(start.getDate() - 30);
     const data = await fetchWithRetry(
-      `${API}/range/${fmt(start)}:${fmt(end)}/${pkg}`,
+      `${API}/range/${fmt(start)}:${fmt(end)}/${encodeNpmPackage(pkg2)}`,
       "npm"
     );
     if (!data || !data.downloads || data.downloads.length === 0) return null;
@@ -101,12 +101,12 @@ var npm = {
     const lastMonth = days.reduce((s, d) => s + d.downloads, 0);
     return {
       registry: "npm",
-      package: pkg,
+      package: pkg2,
       downloads: { lastDay, lastWeek, lastMonth },
       fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
   },
-  async getRange(pkg, start, end) {
+  async getRange(pkg2, start, end) {
     const startDate = new Date(start);
     const endDate = new Date(end);
     const maxDays = 549;
@@ -118,7 +118,7 @@ var npm = {
       const actualEnd = chunkEnd > endDate ? endDate : chunkEnd;
       const s = fmt(cursor);
       const e = fmt(actualEnd);
-      const data = await fetchWithRetry(`${API}/range/${s}:${e}/${pkg}`, "npm");
+      const data = await fetchWithRetry(`${API}/range/${s}:${e}/${encodeNpmPackage(pkg2)}`, "npm");
       if (data) {
         for (const d of data.downloads) {
           chunks.push({ date: d.day, downloads: d.downloads });
@@ -154,22 +154,26 @@ async function npmBulkPoint(packages, period = "last-month") {
 function fmt(d) {
   return d.toISOString().slice(0, 10);
 }
+function encodeNpmPackage(pkg2) {
+  return encodeURIComponent(pkg2);
+}
 
 // src/providers/pypi.ts
 var API2 = "https://pypistats.org/api";
 var pypi = {
   name: "pypi",
   rateLimit: { maxRequests: 30, windowSeconds: 60, authRaisesLimit: false },
-  async getStats(pkg) {
+  async getStats(pkg2) {
+    const safePkg = encodeURIComponent(pkg2);
     const [recent, overall] = await Promise.all([
-      fetchWithRetry(`${API2}/packages/${pkg}/recent`, "pypi"),
-      fetchWithRetry(`${API2}/packages/${pkg}/overall?mirrors=false`, "pypi")
+      fetchWithRetry(`${API2}/packages/${safePkg}/recent`, "pypi"),
+      fetchWithRetry(`${API2}/packages/${safePkg}/overall?mirrors=false`, "pypi")
     ]);
     if (!recent && !overall) return null;
     const total = overall?.data?.filter((d) => d.category === "without_mirrors")?.reduce((sum, d) => sum + d.downloads, 0);
     return {
       registry: "pypi",
-      package: pkg,
+      package: pkg2,
       downloads: {
         total: total || void 0,
         lastDay: recent?.data.last_day,
@@ -179,9 +183,10 @@ var pypi = {
       fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
   },
-  async getRange(pkg, start, end) {
+  async getRange(pkg2, start, end) {
+    const safePkg = encodeURIComponent(pkg2);
     const data = await fetchWithRetry(
-      `${API2}/packages/${pkg}/overall?mirrors=false`,
+      `${API2}/packages/${safePkg}/overall?mirrors=false`,
       "pypi"
     );
     if (!data) return [];
@@ -199,12 +204,12 @@ var pypi = {
 var SEARCH_API = "https://azuresearch-usnc.nuget.org/query";
 var nuget = {
   name: "nuget",
-  async getStats(pkg) {
-    const url = `${SEARCH_API}?q=packageid:${encodeURIComponent(pkg)}&take=1`;
+  async getStats(pkg2) {
+    const url = `${SEARCH_API}?q=packageid:${encodeURIComponent(pkg2)}&take=1`;
     const json2 = await fetchWithRetry(url, "nuget");
     if (!json2) return null;
     const match = json2.data.find(
-      (d) => d.id.toLowerCase() === pkg.toLowerCase()
+      (d) => d.id.toLowerCase() === pkg2.toLowerCase()
     );
     if (!match) return null;
     return {
@@ -228,7 +233,7 @@ function getStat(stats2, name) {
 }
 var vscode = {
   name: "vscode",
-  async getStats(pkg) {
+  async getStats(pkg2) {
     let json2;
     try {
       json2 = await fetchWithRetry(API3, "vscode", {
@@ -240,7 +245,7 @@ var vscode = {
         body: JSON.stringify({
           filters: [
             {
-              criteria: [{ filterType: 7, value: pkg }]
+              criteria: [{ filterType: 7, value: pkg2 }]
             }
           ],
           flags: 256
@@ -279,12 +284,12 @@ var API4 = "https://hub.docker.com/v2/repositories";
 var docker = {
   name: "docker",
   rateLimit: { maxRequests: 10, windowSeconds: 3600, authRaisesLimit: true },
-  async getStats(pkg, options) {
+  async getStats(pkg2, options) {
     const headers = {};
     if (options?.dockerToken) {
       headers["Authorization"] = `Bearer ${options.dockerToken}`;
     }
-    const safePkg = pkg.split("/").map((s) => encodeURIComponent(s)).join("/");
+    const safePkg = pkg2.split("/").map((s) => encodeURIComponent(s)).join("/");
     const json2 = await fetchWithRetry(`${API4}/${safePkg}`, "docker", { headers });
     if (!json2 || !json2.name || !json2.namespace) return null;
     return {
@@ -304,13 +309,16 @@ var docker = {
 
 // src/calc.ts
 var calc = {
+  /** Sum all downloads in the given records. */
   total(records) {
     return records.reduce((sum, r) => sum + r.downloads, 0);
   },
+  /** Compute average daily downloads. Returns 0 for empty input. */
   avg(records) {
     if (records.length === 0) return 0;
     return calc.total(records) / records.length;
   },
+  /** Group records by a custom key function. */
   group(records, fn) {
     const groups = {};
     for (const r of records) {
@@ -319,12 +327,15 @@ var calc = {
     }
     return groups;
   },
+  /** Group records by month (YYYY-MM keys). */
   monthly(records) {
     return calc.group(records, (r) => r.date.slice(0, 7));
   },
+  /** Group records by year (YYYY keys). */
   yearly(records) {
     return calc.group(records, (r) => r.date.slice(0, 4));
   },
+  /** Sum downloads within each group. */
   groupTotals(grouped) {
     const result = {};
     for (const [key, records] of Object.entries(grouped)) {
@@ -332,6 +343,7 @@ var calc = {
     }
     return result;
   },
+  /** Average downloads within each group. */
   groupAvgs(grouped) {
     const result = {};
     for (const [key, records] of Object.entries(grouped)) {
@@ -339,6 +351,7 @@ var calc = {
     }
     return result;
   },
+  /** Detect trend direction (up/down/flat) by comparing recent vs previous window averages. */
   trend(records, windowDays = 7) {
     if (records.length < windowDays * 2) {
       return { slope: 0, direction: "flat", changePercent: 0 };
@@ -354,6 +367,7 @@ var calc = {
     const direction = slope > threshold ? "up" : slope < -threshold ? "down" : "flat";
     return { slope: Math.round(slope * 100) / 100, direction, changePercent: Math.round(changePercent * 100) / 100 };
   },
+  /** Compute a simple moving average over a sliding window. */
   movingAvg(records, windowDays = 7) {
     if (records.length < windowDays) return [];
     const sorted = [...records].sort((a, b) => a.date.localeCompare(b.date));
@@ -370,6 +384,7 @@ var calc = {
     }
     return result;
   },
+  /** Compute a 0-100 popularity score based on log-scaled recent daily downloads. */
   popularity(records) {
     if (records.length === 0) return 0;
     const sorted = [...records].sort((a, b) => a.date.localeCompare(b.date));
@@ -379,6 +394,7 @@ var calc = {
     const score = Math.max(0, Math.min(100, Math.log10(Math.max(1, avgDaily)) / 6 * 100));
     return Math.round(score * 10) / 10;
   },
+  /** Convert records to CSV string with date,downloads columns. */
   toCSV(records) {
     const sorted = [...records].sort((a, b) => a.date.localeCompare(b.date));
     const lines = ["date,downloads"];
@@ -387,6 +403,7 @@ var calc = {
     }
     return lines.join("\n");
   },
+  /** Convert records to a ChartData object suitable for chart libraries. */
   toChartData(records, label = "downloads") {
     const sorted = [...records].sort((a, b) => a.date.localeCompare(b.date));
     return {
@@ -406,7 +423,14 @@ function loadConfig(startDir) {
     const configPath = resolve(dir, CONFIG_NAME);
     if (existsSync(configPath)) {
       const raw = readFileSync(configPath, "utf-8");
-      return JSON.parse(raw);
+      let parsed;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid JSON in ${configPath}: ${message}`);
+      }
+      return validateConfig(parsed, configPath);
     }
     const parent = dirname(dir);
     if (parent === dir) break;
@@ -414,6 +438,50 @@ function loadConfig(startDir) {
   }
   return null;
 }
+function validateConfig(raw, source) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`Config in ${source} must be a JSON object, got ${Array.isArray(raw) ? "array" : typeof raw}`);
+  }
+  const obj = raw;
+  const config = {};
+  if (obj.registries !== void 0) {
+    if (!Array.isArray(obj.registries) || !obj.registries.every((r) => typeof r === "string")) {
+      throw new Error(`Config "registries" must be an array of strings in ${source}`);
+    }
+    config.registries = obj.registries;
+  }
+  if (obj.packages !== void 0) {
+    if (typeof obj.packages !== "object" || obj.packages === null || Array.isArray(obj.packages)) {
+      throw new Error(`Config "packages" must be an object in ${source}`);
+    }
+    config.packages = obj.packages;
+  }
+  if (obj.cache !== void 0) {
+    if (typeof obj.cache !== "boolean") {
+      throw new Error(`Config "cache" must be a boolean in ${source}`);
+    }
+    config.cache = obj.cache;
+  }
+  if (obj.cacheTtlMs !== void 0) {
+    if (typeof obj.cacheTtlMs !== "number" || obj.cacheTtlMs <= 0 || !Number.isFinite(obj.cacheTtlMs)) {
+      throw new Error(`Config "cacheTtlMs" must be a positive number in ${source}`);
+    }
+    config.cacheTtlMs = obj.cacheTtlMs;
+  }
+  if (obj.concurrency !== void 0) {
+    if (typeof obj.concurrency !== "number" || obj.concurrency < 1 || !Number.isInteger(obj.concurrency)) {
+      throw new Error(`Config "concurrency" must be a positive integer in ${source}`);
+    }
+    config.concurrency = obj.concurrency;
+  }
+  if (obj.dockerToken !== void 0) {
+    if (typeof obj.dockerToken !== "string") {
+      throw new Error(`Config "dockerToken" must be a string in ${source}`);
+    }
+    config.dockerToken = obj.dockerToken;
+  }
+  return config;
+}
 var STARTER = `{
   "registries": ["npm", "pypi", "nuget", "vscode", "docker"],
   "packages": {
@@ -433,6 +501,36 @@ function starterConfig() {
 
 // src/server.ts
 import { createServer as httpCreateServer } from "http";
+function createRateLimiter(maxRequests, windowSeconds) {
+  const buckets = /* @__PURE__ */ new Map();
+  const cleanup = setInterval(() => {
+    const now = Date.now();
+    for (const [ip, bucket] of buckets) {
+      if (now > bucket.resetAt) buckets.delete(ip);
+    }
+  }, 6e4);
+  cleanup.unref();
+  return {
+    /** Returns true if the request is allowed, false if rate-limited. */
+    allow(ip) {
+      const now = Date.now();
+      const bucket = buckets.get(ip);
+      if (!bucket || now > bucket.resetAt) {
+        buckets.set(ip, { count: 1, resetAt: now + windowSeconds * 1e3 });
+        return true;
+      }
+      bucket.count++;
+      return bucket.count <= maxRequests;
+    },
+    /** Exposed for testing — clear all buckets. */
+    reset() {
+      buckets.clear();
+    }
+  };
+}
+function sanitizeFilename(value) {
+  return value.replace(/[^a-zA-Z0-9._@/-]/g, "_").slice(0, 200);
+}
 function json(res, data, status = 200) {
   res.writeHead(status, { "Content-Type": "application/json" });
   res.end(JSON.stringify(data));
@@ -452,13 +550,43 @@ function parseUrl(url) {
   }
   return { path, query };
 }
+function withTimeout(promise, ms) {
+  return new Promise((resolve3, reject) => {
+    const timer = setTimeout(() => reject(new Error("__TIMEOUT__")), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve3(v);
+      },
+      (e) => {
+        clearTimeout(timer);
+        reject(e);
+      }
+    );
+  });
+}
+function getClientIp(req) {
+  const forwarded = req.headers["x-forwarded-for"];
+  if (typeof forwarded === "string") return forwarded.split(",")[0].trim();
+  return req.socket.remoteAddress ?? "0.0.0.0";
+}
 function createHandler(opts) {
   const options = { ...opts };
   if (!options.cache) {
     options.cache = createCache();
   }
+  const corsOrigin = opts?.corsOrigin ?? "*";
+  const timeoutMs = opts?.requestTimeoutMs ?? 3e4;
+  const limiter = createRateLimiter(
+    opts?.rateLimitMax ?? 60,
+    opts?.rateLimitWindowSeconds ?? 60
+  );
   return async (req, res) => {
-    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("X-Frame-Options", "DENY");
+    res.setHeader("X-XSS-Protection", "1; mode=block");
+    res.setHeader("Cache-Control", "no-store");
+    res.setHeader("Access-Control-Allow-Origin", corsOrigin);
     res.setHeader("Access-Control-Allow-Methods", "GET, OPTIONS");
     res.setHeader("Access-Control-Allow-Headers", "Content-Type");
     if (req.method === "OPTIONS") {
@@ -466,6 +594,11 @@ function createHandler(opts) {
       res.end();
       return;
     }
+    const clientIp = getClientIp(req);
+    if (!limiter.allow(clientIp)) {
+      error(res, "Too many requests", 429);
+      return;
+    }
     if (req.method !== "GET") {
       error(res, "Method not allowed", 405);
       return;
@@ -474,17 +607,17 @@ function createHandler(opts) {
     try {
       if (path[0] === "stats") {
         if (path.length === 2) {
-          const pkg = decodeURIComponent(path[1]);
-          const results = await stats.all(pkg, options);
+          const pkg2 = decodeURIComponent(path[1]);
+          const results = await withTimeout(stats.all(pkg2, options), timeoutMs);
           json(res, results);
           return;
         }
         if (path.length >= 3) {
           const registry = path[1];
-          const pkg = path.slice(2).join("/");
-          const result = await stats(registry, pkg, options);
+          const pkg2 = path.slice(2).join("/");
+          const result = await withTimeout(stats(registry, pkg2, options), timeoutMs);
           if (!result) {
-            error(res, `Package "${pkg}" not found on ${registry}`, 404);
+            error(res, `Package "${pkg2}" not found on ${registry}`, 404);
             return;
           }
           json(res, result);
@@ -492,31 +625,34 @@ function createHandler(opts) {
         }
       }
       if (path[0] === "compare" && path.length >= 2) {
-        const pkg = decodeURIComponent(path[1]);
+        const pkg2 = decodeURIComponent(path[1]);
         const registries = query.registries ? query.registries.split(",") : void 0;
-        const result = await stats.compare(pkg, registries, options);
+        const result = await withTimeout(stats.compare(pkg2, registries, options), timeoutMs);
         json(res, result);
         return;
       }
       if (path[0] === "range" && path.length >= 3) {
         const registry = path[1];
-        const pkg = path.slice(2).join("/");
+        const pkg2 = path.slice(2).join("/");
         const { start, end, format } = query;
         if (!start || !end) {
           error(res, "Missing start and end query parameters");
           return;
         }
-        const data = await stats.range(registry, pkg, start, end, options);
+        const data = await withTimeout(stats.range(registry, pkg2, start, end, options), timeoutMs);
         if (format === "csv") {
+          const safePkg = sanitizeFilename(pkg2);
+          const safeStart = sanitizeFilename(start);
+          const safeEnd = sanitizeFilename(end);
           res.writeHead(200, {
             "Content-Type": "text/csv",
-            "Content-Disposition": `attachment; filename="${pkg}-${start}-${end}.csv"`
+            "Content-Disposition": `attachment; filename="${safePkg}-${safeStart}-${safeEnd}.csv"`
           });
           res.end(calc.toCSV(data));
           return;
         }
         if (format === "chart") {
-          json(res, calc.toChartData(data, `${pkg} (${registry})`));
+          json(res, calc.toChartData(data, `${pkg2} (${registry})`));
           return;
         }
         json(res, data);
@@ -536,11 +672,13 @@ function createHandler(opts) {
       }
       error(res, "Not found", 404);
     } catch (e) {
-      if (e instanceof RegistryError) {
+      if (e?.message === "__TIMEOUT__") {
+        error(res, "Gateway timeout", 504);
+      } else if (e instanceof RegistryError) {
         const status = e.statusCode === 429 ? 429 : e.statusCode === 404 ? 404 : e.statusCode >= 500 ? 502 : 500;
         error(res, e.message, status);
       } else {
-        error(res, e.message, 500);
+        error(res, "Internal server error", 500);
       }
     }
   };
@@ -548,7 +686,11 @@ function createHandler(opts) {
 function serve(opts) {
   const port = opts?.port ?? 3e3;
   const handler = createHandler({
-    cache: opts?.cache !== false ? createCache() : void 0
+    cache: opts?.cache !== false ? createCache() : void 0,
+    corsOrigin: opts?.corsOrigin,
+    rateLimitMax: opts?.rateLimitMax,
+    rateLimitWindowSeconds: opts?.rateLimitWindowSeconds,
+    requestTimeoutMs: opts?.requestTimeoutMs
   });
   const server = httpCreateServer(handler);
   server.listen(port, () => {
@@ -564,6 +706,18 @@ Endpoints:`);
 }
 
 // src/index.ts
+var VALID_PKG_NAME = /^[@a-zA-Z0-9][\w./@-]*$/;
+function validatePackageName(pkg2, registry) {
+  if (!pkg2 || typeof pkg2 !== "string") {
+    throw new RegistryError(registry, 0, `Invalid package name: must be a non-empty string`);
+  }
+  if (pkg2.includes("..") || pkg2.includes("\\")) {
+    throw new RegistryError(registry, 0, `Invalid package name "${pkg2}": path traversal not allowed`);
+  }
+  if (!VALID_PKG_NAME.test(pkg2)) {
+    throw new RegistryError(registry, 0, `Invalid package name "${pkg2}": contains illegal characters`);
+  }
+}
 function createCache() {
   const store = /* @__PURE__ */ new Map();
   return {
@@ -608,25 +762,26 @@ var providers = {
   docker
 };
 var DEFAULT_TTL = 3e5;
-async function stats(registry, pkg, options) {
+async function stats(registry, pkg2, options) {
+  validatePackageName(pkg2, registry);
   const provider = providers[registry];
   if (!provider) {
     throw new RegistryError(registry, 0, `Unknown registry "${registry}". Use registerProvider() to add custom registries.`);
   }
   const cache = options?.cache;
   if (cache) {
-    const key = `stats:${registry}:${pkg}`;
+    const key = `stats:${registry}:${pkg2}`;
     const cached = cache.get(key);
     if (cached) return cached;
-    const result = await provider.getStats(pkg, options);
+    const result = await provider.getStats(pkg2, options);
     if (result) cache.set(key, result, options?.cacheTtlMs ?? DEFAULT_TTL);
     return result;
   }
-  return provider.getStats(pkg, options);
+  return provider.getStats(pkg2, options);
 }
-stats.all = async function all(pkg, options) {
+stats.all = async function all(pkg2, options) {
   const results = await Promise.allSettled(
-    Object.values(providers).map((p) => p.getStats(pkg, options))
+    Object.values(providers).map((p) => p.getStats(pkg2, options))
   );
   return results.filter(
     (r) => r.status === "fulfilled" && r.value !== null
@@ -642,32 +797,32 @@ stats.bulk = async function bulk(registry, packages, options) {
   }
   const concurrency = options?.concurrency ?? 5;
   const limit = pLimit(concurrency);
-  return Promise.all(packages.map((pkg) => limit(() => stats(registry, pkg, options))));
+  return Promise.all(packages.map((pkg2) => limit(() => stats(registry, pkg2, options))));
 };
 async function npmBulkStats(packages, options) {
   const scoped = [];
   const unscoped = [];
-  for (const pkg of packages) {
-    if (pkg.startsWith("@")) {
-      scoped.push(pkg);
+  for (const pkg2 of packages) {
+    if (pkg2.startsWith("@")) {
+      scoped.push(pkg2);
     } else {
-      unscoped.push(pkg);
+      unscoped.push(pkg2);
     }
   }
   const bulkMonth = unscoped.length > 0 ? await npmBulkPoint(unscoped, "last-month") : /* @__PURE__ */ new Map();
   const bulkWeek = unscoped.length > 0 ? await npmBulkPoint(unscoped, "last-week") : /* @__PURE__ */ new Map();
   const bulkDay = unscoped.length > 0 ? await npmBulkPoint(unscoped, "last-day") : /* @__PURE__ */ new Map();
   const unscopedResults = /* @__PURE__ */ new Map();
-  for (const pkg of unscoped) {
-    const month = bulkMonth.get(pkg);
-    const week = bulkWeek.get(pkg);
-    const day = bulkDay.get(pkg);
+  for (const pkg2 of unscoped) {
+    const month = bulkMonth.get(pkg2);
+    const week = bulkWeek.get(pkg2);
+    const day = bulkDay.get(pkg2);
     if (month === void 0 && week === void 0 && day === void 0) {
-      unscopedResults.set(pkg, null);
+      unscopedResults.set(pkg2, null);
     } else {
-      unscopedResults.set(pkg, {
+      unscopedResults.set(pkg2, {
         registry: "npm",
-        package: pkg,
+        package: pkg2,
         downloads: {
           lastDay: day,
           lastWeek: week,
@@ -679,13 +834,13 @@ async function npmBulkStats(packages, options) {
   }
   const limit = pLimit(1);
   const scopedResults = await Promise.all(
-    scoped.map((pkg) => limit(() => stats("npm", pkg, options)))
+    scoped.map((pkg2) => limit(() => stats("npm", pkg2, options)))
   );
   const scopedMap = /* @__PURE__ */ new Map();
-  scoped.forEach((pkg, i) => scopedMap.set(pkg, scopedResults[i]));
-  return packages.map((pkg) => unscopedResults.get(pkg) ?? scopedMap.get(pkg) ?? null);
+  scoped.forEach((pkg2, i) => scopedMap.set(pkg2, scopedResults[i]));
+  return packages.map((pkg2) => unscopedResults.get(pkg2) ?? scopedMap.get(pkg2) ?? null);
 }
-stats.range = async function range(registry, pkg, start, end, options) {
+stats.range = async function range(registry, pkg2, start, end, options) {
   const provider = providers[registry];
   if (!provider) {
     throw new RegistryError(registry, 0, `Unknown registry "${registry}".`);
@@ -699,20 +854,20 @@ stats.range = async function range(registry, pkg, start, end, options) {
   }
   const cache = options?.cache;
   if (cache) {
-    const key = `range:${registry}:${pkg}:${start}:${end}`;
+    const key = `range:${registry}:${pkg2}:${start}:${end}`;
     const cached = cache.get(key);
     if (cached) return cached;
-    const result = await provider.getRange(pkg, start, end);
+    const result = await provider.getRange(pkg2, start, end);
     cache.set(key, result, options?.cacheTtlMs ?? DEFAULT_TTL);
     return result;
   }
-  return provider.getRange(pkg, start, end);
+  return provider.getRange(pkg2, start, end);
 };
-stats.compare = async function compare(pkg, registries, options) {
+stats.compare = async function compare(pkg2, registries, options) {
   const regs = registries ?? Object.keys(providers);
   const results = await Promise.allSettled(
     regs.map(async (reg) => {
-      const result = await stats(reg, pkg, options);
+      const result = await stats(reg, pkg2, options);
       return result ? { reg, result } : null;
     })
   );
@@ -723,7 +878,7 @@ stats.compare = async function compare(pkg, registries, options) {
     }
   }
   return {
-    package: pkg,
+    package: pkg2,
     registries: registryMap,
     fetchedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
@@ -755,6 +910,9 @@ stats.mine = async function mine(maintainer, options) {
 };
 
 // src/cli.ts
+var __dirname = dirname2(fileURLToPath(import.meta.url));
+var pkg = JSON.parse(readFileSync2(join(__dirname, "..", "package.json"), "utf-8"));
+var VERSION = pkg.version;
 function usage() {
   console.log(`
 Usage: registry-stats [package] [options]
@@ -771,7 +929,9 @@ Options:
                   Only npm and pypi support this
   --compare       Compare package across registries side-by-side
   --format        Output format: table (default), json, csv, chart
+  --json          Shorthand for --format json
   --init          Create a starter registry-stats.config.json
+  --version, -V   Show version
   --help, -h      Show this help
 
 Subcommands:
@@ -902,7 +1062,8 @@ async function runConfigPackages(config, format) {
       try {
         const result = await stats(registry, pkgId, opts);
         if (result) results.push(result);
-      } catch {
+      } catch (e) {
+        console.error(`Warning: failed to fetch ${registry} for ${displayName}: ${e.message}`);
       }
     });
     await Promise.all(fetches);
@@ -931,8 +1092,8 @@ async function runMine(maintainer, format, config) {
   process.stderr.write(`  Discovering packages for ${maintainer}...`);
   const results = await stats.mine(maintainer, {
     ...opts,
-    onProgress(done, total, pkg) {
-      process.stderr.write(`\r  Fetching stats... ${done}/${total} (${pkg})${"".padEnd(20)}`);
+    onProgress(done, total, pkg2) {
+      process.stderr.write(`\r  Fetching stats... ${done}/${total} (${pkg2})${"".padEnd(20)}`);
     }
   });
   process.stderr.write("\r" + " ".repeat(80) + "\r");
@@ -948,6 +1109,10 @@ async function runMine(maintainer, format, config) {
 }
 async function main() {
   const args = process.argv.slice(2);
+  if (args.includes("--version") || args.includes("-V")) {
+    console.log(`registry-stats ${VERSION}`);
+    process.exit(0);
+  }
   if (args.includes("--help") || args.includes("-h")) {
     usage();
     process.exit(0);
@@ -967,17 +1132,22 @@ async function main() {
     for (let i = 1; i < args.length; i++) {
       if (args[i] === "--port" && args[i + 1]) {
         port = parseInt(args[++i], 10);
+        if (Number.isNaN(port) || port < 1 || port > 65535) {
+          console.error("Error: --port must be a number between 1 and 65535");
+          process.exit(1);
+        }
       }
     }
     serve({ port });
     return;
   }
-  let pkg;
+  let pkg2;
   let registry;
   let range2;
   let format = "table";
   let compare2 = false;
   let mineUser;
+  const unknownFlags = [];
   for (let i = 0; i < args.length; i++) {
     if ((args[i] === "--registry" || args[i] === "-r") && args[i + 1]) {
       registry = args[++i];
@@ -991,16 +1161,25 @@ async function main() {
       compare2 = true;
     } else if (args[i] === "--mine" && args[i + 1]) {
       mineUser = args[++i];
-    } else if (!args[i].startsWith("-") && !pkg) {
-      pkg = args[i];
+    } else if (!args[i].startsWith("-") && !pkg2) {
+      pkg2 = args[i];
+    } else if (args[i].startsWith("-")) {
+      unknownFlags.push(args[i]);
     }
   }
+  if (unknownFlags.length > 0) {
+    console.error(`Warning: unknown option(s): ${unknownFlags.join(", ")}`);
+  }
   const config = loadConfig();
+  if ((format === "csv" || format === "chart") && !range2) {
+    console.error(`Warning: --format ${format} only produces meaningful output with --range. Falling back to table.`);
+    format = "table";
+  }
   if (mineUser) {
     await runMine(mineUser, format, config);
     return;
   }
-  if (!pkg) {
+  if (!pkg2) {
     if (!config) {
       usage();
       process.exit(0);
@@ -1012,7 +1191,7 @@ async function main() {
   try {
     if (compare2) {
       const registries = registry ? [registry] : void 0;
-      const result = await stats.compare(pkg, registries, opts);
+      const result = await stats.compare(pkg2, registries, opts);
       if (format === "json") {
         console.log(JSON.stringify(result, null, 2));
       } else {
@@ -1027,18 +1206,18 @@ async function main() {
         console.error("Error: --range must be start:end (e.g. 2025-01-01:2025-06-30)");
         process.exit(1);
       }
-      const data = await stats.range(reg, pkg, start, end, opts);
+      const data = await stats.range(reg, pkg2, start, end, opts);
       if (format === "json") {
         console.log(JSON.stringify(data, null, 2));
       } else if (format === "csv") {
         console.log(calc.toCSV(data));
       } else if (format === "chart") {
-        console.log(JSON.stringify(calc.toChartData(data, `${pkg} (${reg})`), null, 2));
+        console.log(JSON.stringify(calc.toChartData(data, `${pkg2} (${reg})`), null, 2));
       } else {
         const monthly = calc.groupTotals(calc.monthly(data));
         const t = calc.trend(data);
         console.log(`
-${pkg} (${reg}) \u2014 ${start} to ${end}
+${pkg2} (${reg}) \u2014 ${start} to ${end}
 `);
         for (const [month, total] of Object.entries(monthly)) {
           console.log(`  ${month}  ${formatNumber(total)}`);
@@ -1047,9 +1226,9 @@ ${pkg} (${reg}) \u2014 ${start} to ${end}
   Total: ${formatNumber(calc.total(data))}  Avg/day: ${formatNumber(Math.round(calc.avg(data)))}  Trend: ${t.direction} (${t.changePercent > 0 ? "+" : ""}${t.changePercent}%)`);
       }
     } else if (registry) {
-      const result = await stats(registry, pkg, opts);
+      const result = await stats(registry, pkg2, opts);
       if (!result) {
-        console.error(`Package "${pkg}" not found on ${registry}`);
+        console.error(`Package "${pkg2}" not found on ${registry}`);
         process.exit(1);
       }
       if (format === "json") {
@@ -1059,9 +1238,9 @@ ${pkg} (${reg}) \u2014 ${start} to ${end}
         printStats(result);
       }
     } else {
-      const results = await stats.all(pkg, opts);
+      const results = await stats.all(pkg2, opts);
       if (results.length === 0) {
-        console.error(`Package "${pkg}" not found on any registry`);
+        console.error(`Package "${pkg2}" not found on any registry`);
         process.exit(1);
       }
       if (format === "json") {
@@ -1079,4 +1258,7 @@ ${pkg} (${reg}) \u2014 ${start} to ${end}
     process.exit(1);
   }
 }
-main();
+main().catch((e) => {
+  console.error(`Error: ${e.message}`);
+  process.exit(1);
+});