feat(server): add runtime package stats helper

Every Humanspeak docs site documents a published npm package and wants
live size + version numbers in its UI. Baking those values in at
deploy time means the docs go stale every time the library publishes
without a paired docs change. This helper breaks that coupling by
fetching `{ name, version, tarballBytes, unpackedBytes, updatedAt }`
from the npm registry at request time, with an in-memory cache and
HTTP `cache-control` headers so Cloudflare's edge holds the rendered
response.

Exported via a new `@humanspeak/docs-kit/server` subpath so consumer
client bundles never pull in server-only code.

Two entry points:

- `fetchPackageStats(name, version, opts?)` — low-level: returns
  `PackageStats | null`. Use for one-off lookups (other surfaces,
  scripts).
- `createPackageStatsLoad({ pkg, ttlMs?, devFallback?, dev? })` —
  factory that returns a SvelteKit `PageServerLoad`. Consumer wires
  it in two lines:

  ```ts
  import { createPackageStatsLoad } from '@humanspeak/docs-kit/server'
  import rootPkg from '../../../package.json'
  export const prerender = false
  export const load = createPackageStatsLoad({ pkg: rootPkg })
  ```

Registry failures fall back to the workspace `package.json` version
with `null` sizes (rendered as `—`); in dev, optional `devFallback`
substitutes representative numbers so the design previews correctly
without a network round-trip. Production never displays incorrect
values — only missing ones.

IMPORTANT: routes using `createPackageStatsLoad` must NOT set
`export const prerender = true` — prerendering would freeze the
stats at build time and reintroduce the staleness problem the
helper exists to solve. Inline comments in the source flag this.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jaysin586

package.json

@@ -24,6 +24,10 @@
             "types": "./dist/hooks/index.d.ts",
             "default": "./dist/hooks/index.js"
         },
+        "./server": {
+            "types": "./dist/server/index.d.ts",
+            "default": "./dist/server/index.js"
+        },
         "./scripts/fetch-github-stats": {
             "types": "./dist/scripts/fetch-github-stats.d.ts",
             "default": "./dist/scripts/fetch-github-stats.js"

src/lib/server/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Server-only utilities for SvelteKit `+page.server.ts` / `+layout.server.ts`
+ * files. Importing from this subpath signals to Vite that the module
+ * must not be bundled into client code.
+ */
+
+export {
+    createPackageStatsLoad,
+    fetchPackageStats,
+    type FetchPackageStatsOptions,
+    type PackageStats,
+    type PackageStatsLoadOptions
+} from './package-stats.js'

src/lib/server/package-stats.ts

@@ -0,0 +1,183 @@
+import type { ServerLoadEvent } from '@sveltejs/kit'
+
+/**
+ * Runtime package stats helper — fetches `{ name, version, tarballBytes,
+ * unpackedBytes, updatedAt }` from the npm registry at request time, with
+ * an in-memory cache and HTTP `cache-control` headers so Cloudflare's
+ * edge holds the response.
+ *
+ * Why this exists:
+ *
+ * Every Humanspeak docs site documents a published npm package and wants
+ * to surface live size + version stats in its UI. Baking those values in
+ * at deploy time means the docs go stale every time the library
+ * publishes without a paired docs change. Fetching them at request time
+ * with a sensible cache breaks that coupling entirely.
+ *
+ * Typical consumer wiring:
+ *
+ * ```ts
+ * // docs/src/routes/+page.server.ts
+ * import rootPkg from '../../../package.json'
+ * import { createPackageStatsLoad } from '@humanspeak/docs-kit/server'
+ *
+ * export const prerender = false
+ * export const load = createPackageStatsLoad({
+ *     pkg: rootPkg,
+ *     devFallback: { tarballBytes: 81458, unpackedBytes: 324332 }
+ * })
+ * ```
+ *
+ * IMPORTANT: do not add `export const prerender = true` to a route that
+ * uses this loader — prerendering would freeze the stats at build time
+ * and reintroduce the staleness problem this helper exists to solve.
+ */
+
+export interface PackageStats {
+    name: string
+    version: string
+    /** Packed tarball size in bytes (gzipped). `null` when registry was unreachable. */
+    tarballBytes: number | null
+    /** Unpacked install size in bytes. `null` when registry was unreachable. */
+    unpackedBytes: number | null
+    /** ISO timestamp of the last successful registry fetch. */
+    updatedAt: string
+}
+
+interface RegistryDist {
+    fileCount?: number
+    unpackedSize?: number
+    tarball?: string
+}
+
+interface RegistryVersionRecord {
+    name?: string
+    version?: string
+    dist?: RegistryDist
+}
+
+const DEFAULT_TIMEOUT_MS = 4000
+
+const fetchWithTimeout = async (url: string, timeoutMs: number): Promise<Response> => {
+    const ctrl = new AbortController()
+    const t = setTimeout(() => ctrl.abort(), timeoutMs)
+    try {
+        return await fetch(url, { signal: ctrl.signal })
+    } finally {
+        clearTimeout(t)
+    }
+}
+
+export interface FetchPackageStatsOptions {
+    /** Network timeout in milliseconds. Defaults to 4000ms. */
+    timeoutMs?: number
+    /** Alternative npm registry base URL (mirrors, private registries). */
+    registryBase?: string
+}
+
+/**
+ * Hits the npm registry for `<name>@<version>` and returns the size
+ * metadata, or `null` on any error (network failure, 404, timeout, malformed
+ * response). Safe to call from a Cloudflare Worker or any other edge
+ * runtime that exposes `fetch`.
+ */
+export const fetchPackageStats = async (
+    name: string,
+    version: string,
+    opts: FetchPackageStatsOptions = {}
+): Promise<PackageStats | null> => {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS
+    const registryBase = opts.registryBase ?? 'https://registry.npmjs.org'
+    try {
+        const url = `${registryBase}/${encodeURIComponent(name)}/${encodeURIComponent(version)}`
+        const res = await fetchWithTimeout(url, timeoutMs)
+        if (!res.ok) return null
+        const record = (await res.json()) as RegistryVersionRecord
+        const dist = record.dist
+        let tarballBytes: number | null = null
+        if (dist?.tarball) {
+            try {
+                const head = await fetchWithTimeout(dist.tarball, timeoutMs)
+                const len = head.headers.get('content-length')
+                if (head.ok && len) tarballBytes = Number(len)
+            } catch {
+                /* tarball HEAD is optional — fall back to null */
+            }
+        }
+        return {
+            name,
+            version,
+            tarballBytes,
+            unpackedBytes: dist?.unpackedSize ?? null,
+            updatedAt: new Date().toISOString()
+        }
+    } catch {
+        return null
+    }
+}
+
+export interface PackageStatsLoadOptions {
+    /** Workspace `package.json` import (or any `{ name, version }` shape). */
+    pkg: { name: string; version: string }
+    /** Cache TTL in milliseconds. Defaults to 1 hour. */
+    ttlMs?: number
+    /** Network timeout in milliseconds. Defaults to 4000ms. */
+    timeoutMs?: number
+    /** Alternative npm registry base URL. */
+    registryBase?: string
+    /**
+     * Values to substitute when the registry can't be reached AND we're
+     * running in dev. Lets the design preview properly without a network
+     * round-trip. In production, registry failures still surface as
+     * `null` so we never display incorrect numbers.
+     */
+    devFallback?: {
+        tarballBytes: number | null
+        unpackedBytes: number | null
+    }
+    /** True when running under `vite dev`. Pass `import { dev } from '$app/environment'`. */
+    dev?: boolean
+}
+
+interface CacheEntry {
+    fetchedAt: number
+    data: PackageStats
+}
+
+/**
+ * Builds a SvelteKit `PageServerLoad` (or `LayoutServerLoad`) that
+ * resolves `{ packageStats }` to PageData. Memoised per-worker-instance
+ * for `ttlMs`, and sets HTTP cache-control headers matching the same TTL
+ * so the edge can share one rendered HTML response across requests.
+ */
+export const createPackageStatsLoad = (opts: PackageStatsLoadOptions) => {
+    const ttlMs = opts.ttlMs ?? 60 * 60 * 1000
+
+    let memo: CacheEntry | null = null
+
+    const fallback = (): PackageStats => ({
+        name: opts.pkg.name,
+        version: opts.pkg.version,
+        tarballBytes: opts.dev ? (opts.devFallback?.tarballBytes ?? null) : null,
+        unpackedBytes: opts.dev ? (opts.devFallback?.unpackedBytes ?? null) : null,
+        updatedAt: new Date(0).toISOString()
+    })
+
+    return async (event: Pick<ServerLoadEvent, 'setHeaders'>) => {
+        event.setHeaders({
+            'cache-control': `public, max-age=${ttlMs / 1000}, s-maxage=${ttlMs / 1000}`
+        })
+
+        if (memo && Date.now() - memo.fetchedAt < ttlMs) {
+            return { packageStats: memo.data }
+        }
+
+        const fresh = await fetchPackageStats(opts.pkg.name, opts.pkg.version, {
+            timeoutMs: opts.timeoutMs,
+            registryBase: opts.registryBase
+        })
+        const data = fresh ?? fallback()
+        memo = { fetchedAt: Date.now(), data }
+        return { packageStats: data }
+    }
+}