Merge branch 'main' into chore/installs-update-ghcr-note

Author: amavashev

.vitepress/theme/installs-cache.json

@@ -91,5 +91,5 @@
   "ghPackages": 2951,
   "maven": 0,
   "total": 9048,
-  "fetchedAt": "2026-05-05T14:15:00.000Z"
+  "fetchedAt": "2026-05-05T14:49:53.940Z"
 }

.vitepress/theme/installs.data.ts

@@ -373,10 +373,29 @@ async function fetchGithubReleaseDownloads(
 }
 
 // ── Maven Central ────────────────────────────────────────────────────
-async function fetchMavenDownloads(): Promise<number> {
-  // Maven Central has no public downloads API. The search API only
-  // exposes versionCount, not download stats.
-  return 0
+// Maven Central has no public downloads API. The search API only
+// exposes versionCount, not download stats. Sonatype Central exposes
+// downloads to publishers via an authenticated CSV export, but that's
+// not available at build time.
+//
+// Until publisher-credential access lands, we use the same manual-file
+// pattern as ghPackages: maintainers paste current download counts from
+// the Sonatype Central publisher portal into manual-package-counts.json
+// under `maven` (keyed by `groupId:artifactId`). HWM still applies, so
+// values only grow.
+//
+// TODO: replace with an authenticated Sonatype Central API call once a
+// service-account credential is available — search the portal for
+// "download statistics export" or use the s01.oss.sonatype.org REST API
+// if the artifact is hosted there.
+function fetchMavenDownloads(): number {
+  try {
+    const raw = JSON.parse(readFileSync(MANUAL_PATH, 'utf-8'))
+    const map = raw.maven ?? {}
+    return Object.values(map).reduce<number>((a, b) => a + (typeof b === 'number' ? b : 0), 0)
+  } catch {
+    return 0
+  }
 }
 
 // ── Loader ───────────────────────────────────────────────────────────
@@ -397,7 +416,7 @@ export default {
       fetchCratesDownloads(),
       fetchGithubClones(cached.clonesByRepo),
       fetchGithubReleaseDownloads(cached.releasesByRepo),
-      fetchMavenDownloads(),
+      Promise.resolve(fetchMavenDownloads()),
     ])
 
     // Per-source high-water marks: each source never decreases independently.

.vitepress/theme/manual-package-counts.json

@@ -7,5 +7,11 @@
     "cycles-server":         917,
     "cycles-dashboard":      517,
     "cycles-server-events":  319
+  },
+  "_mavenNote": "Maven Central has no public downloads API. Sonatype Central exposes per-artifact download counts to the publisher via the Central Portal (https://central.sonatype.com/) under 'Statistics'. Update these numbers manually after each release (typical cadence: monthly), keyed by groupId:artifactId. Leave 0 if the artifact has not been published yet.",
+  "_mavenSource": "https://central.sonatype.com/ → Statistics → Downloads",
+  "mavenLastVerifiedAt": "2026-05-05",
+  "maven": {
+    "io.runcycles:cycles-spring-boot-starter": 0
   }
 }

scripts/update-github-counts.mjs

@@ -126,6 +126,34 @@ async function updateClones(repos, byRepo) {
   return { byRepo: updated, total }
 }
 
+// ── Stale-cursor guard ───────────────────────────────────────────────
+// /traffic/clones is a 14-day rolling window. If this script doesn't run
+// for >14 days, days fall off the end of the API window and are lost
+// permanently. Warn loudly when any repo's cursor slips beyond a safety
+// threshold (default 7 days) so the issue is visible before data loss.
+const STALE_DAYS_THRESHOLD = 7
+function checkStaleClones(byRepo) {
+  const today = new Date().toISOString().slice(0, 10)
+  const todayMs = Date.parse(today + 'T00:00:00Z')
+  const stale = []
+  for (const [repo, info] of Object.entries(byRepo)) {
+    if (!info?.lastSeenDay || info.lastSeenDay === '1970-01-01') continue
+    const lastMs = Date.parse(info.lastSeenDay + 'T00:00:00Z')
+    const daysBehind = Math.floor((todayMs - lastMs) / 86_400_000)
+    if (daysBehind > STALE_DAYS_THRESHOLD) {
+      stale.push({ repo, lastSeenDay: info.lastSeenDay, daysBehind })
+    }
+  }
+  if (stale.length === 0) {
+    console.log(`stale-cursor check: all ${Object.keys(byRepo).length} repos within ${STALE_DAYS_THRESHOLD}d of today (${today})`)
+    return
+  }
+  for (const { repo, lastSeenDay, daysBehind } of stale) {
+    console.warn(`::warning::stale clones cursor: ${repo} lastSeenDay=${lastSeenDay} (${daysBehind}d behind today=${today})`)
+  }
+  console.warn(`::warning::${stale.length}/${Object.keys(byRepo).length} repo(s) have stale clones cursors. /traffic/clones is a 14d rolling window — fix the scheduled workflow before days fall off.`)
+}
+
 // ── Releases: HWM on asset download_count per repo ───────────────────
 // For runcycles, every release exists as a tag-only release with no
 // attached assets (Java services publish to GHCR; SDKs publish to PyPI/
@@ -189,6 +217,7 @@ async function main() {
   console.log(`  repos: ${repos.length}`)
 
   const clonesResult = await updateClones(repos, cache.clonesByRepo)
+  checkStaleClones(clonesResult.byRepo)
   const releasesResult = await updateReleases(repos, cache.releasesByRepo)
   const ghpkgResult = await updateGhPackages()