feat: add CI time refresh for star rating snapshots

Author: ofriw

.github/workflows/deploy.yml

@@ -53,6 +53,12 @@ jobs:
       - name: Run typecheck
         run: npm run typecheck
 
+      - name: Refresh GitHub star counts
+        # Unauthenticated (60 req/hr/IP). The fetcher merges per repo and keeps
+        # the committed snapshot on failure, so a rate-limited deploy still
+        # ships the last known counts instead of failing the build.
+        run: node ../scripts/fetch-github-stars.js
+
       - name: Build website
         run: npm run build
 

scripts/fetch-github-stars.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// Refreshes the committed star snapshot the site renders as its build-time
+// baseline (see github-stars.js). Properties a deploy depends on:
+//   - merge is PER REPO: a repo that fails keeps its previous value, so a
+//     rate-limited or offline runner still ships usable numbers;
+//   - the process always exits 0 and only warns on failure, so GitHub being
+//     unreachable can never fail a build;
+//   - an unchanged snapshot is not rewritten, so a no-op refresh leaves the
+//     working tree clean.
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { PROJECTS, parseStars } from './github-stars.js';
+
+const SNAPSHOT_PATH = fileURLToPath(
+  new URL('../website/src/generated/github-stars.json', import.meta.url)
+);
+
+async function readSnapshot() {
+  try {
+    return JSON.parse(await readFile(SNAPSHOT_PATH, 'utf8'));
+  } catch {
+    return { projects: [] };
+  }
+}
+
+async function fetchStars(repo) {
+  try {
+    const response = await fetch(`https://api.github.com/repos/${repo}`, {
+      headers: { Accept: 'application/vnd.github+json' },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return { repo, stars: null, reason: `HTTP ${response.status}` };
+    const stars = parseStars(await response.json());
+    return stars === null
+      ? { repo, stars: null, reason: 'unexpected payload' }
+      : { repo, stars };
+  } catch (error) {
+    return { repo, stars: null, reason: error.message };
+  }
+}
+
+// Per-repo merge: a failed repo keeps its previous entry — including its own
+// fetchedAt — so a timestamp always describes the number it sits next to. An
+// unchanged count is also left as-is, so a no-op refresh dirties nothing.
+function mergeProjects(previous, results) {
+  const previousByRepo = new Map(previous.map((project) => [project.repo, project]));
+  return results.flatMap(({ repo, stars }) => {
+    const prior = previousByRepo.get(repo);
+    if (stars === null) return prior ? [prior] : [];
+    if (prior && prior.stars === stars) return [prior];
+    const { name } = PROJECTS.find((project) => project.repo === repo);
+    return [{ name, repo, stars, fetchedAt: new Date().toISOString() }];
+  });
+}
+
+// Two-space JSON with a trailing newline is exactly prettier's output, so the
+// generated file passes `format:check` without an ignore entry.
+function serialize(projects) {
+  return `${JSON.stringify({ projects }, null, 2)}\n`;
+}
+
+async function main() {
+  const { projects: previous = [] } = await readSnapshot();
+  const results = await Promise.all(PROJECTS.map(({ repo }) => fetchStars(repo)));
+  for (const { repo, reason } of results.filter(({ stars }) => stars === null)) {
+    console.warn(`[stars] ${repo}: ${reason} — keeping last known value`);
+  }
+
+  const next = serialize(mergeProjects(previous, results));
+  if (next === serialize(previous)) {
+    console.log('[stars] snapshot unchanged');
+    return;
+  }
+  await mkdir(dirname(SNAPSHOT_PATH), { recursive: true });
+  await writeFile(SNAPSHOT_PATH, next, 'utf8');
+  console.log(`[stars] wrote ${SNAPSHOT_PATH}`);
+}
+
+main().catch((error) => {
+  console.warn(`[stars] refresh failed: ${error.message} — keeping committed snapshot`);
+});

scripts/github-stars.js

@@ -0,0 +1,19 @@
+// Canonical inputs for the build-time star snapshot: the open-source projects
+// shown in the homepage trust band. This list is the single source of truth for
+// repo slugs and display names — scripts/fetch-github-stars.js writes it into
+// website/src/generated/github-stars.json, which the site imports. Adding a
+// project means adding it here and to website/docs/intro.mdx;
+// GitHubSocialProof/stars.test.ts fails if those two lists diverge.
+
+export const PROJECTS = [
+  { name: 'Book source', repo: 'agenticoding/agenticoding.github.io' },
+  { name: 'ChunkHound', repo: 'chunkhound/chunkhound' },
+  { name: 'Pi agenticoding extension', repo: 'agenticoding/pi-agenticoding' },
+];
+
+// A star count is trustworthy only as a non-negative safe integer; the /repos
+// payload carries unrelated fields that must not be smuggled into the snapshot.
+export function parseStars(payload) {
+  const stars = payload?.stargazers_count;
+  return Number.isSafeInteger(stars) && stars >= 0 ? stars : null;
+}

scripts/test-responsive-diagrams.cjs

@@ -4,6 +4,7 @@ const http = require("node:http");
 const net = require("node:net");
 const os = require("node:os");
 const path = require("node:path");
+const { pathToFileURL } = require("node:url");
 
 const puppeteer = require(
   path.resolve(__dirname, "..", "website", "node_modules", "puppeteer"),
@@ -37,6 +38,16 @@ const FOUNDATIONS_FIRST_DOC = "/how-llms-work";
 const TRACE_DIR = path.join(path.resolve(__dirname, "..", "website"), "browser-contracts-traces");
 
 const websiteDir = path.resolve(__dirname, "..", "website");
+// The build-time star snapshot and its canonical formatter, read by the
+// no-JavaScript homepage contract below.
+const STARS_SNAPSHOT = path.join(websiteDir, "src", "generated", "github-stars.json");
+const FORMAT_STARS = path.join(
+  websiteDir,
+  "src",
+  "components",
+  "GitHubSocialProof",
+  "formatStars.ts",
+);
 // CI builds once and points us at the artifact; local runs self-build.
 const providedBuildDir = process.env.BROWSER_TEST_BUILD_DIR
   ? path.resolve(process.env.BROWSER_TEST_BUILD_DIR)
@@ -361,17 +372,37 @@ function linksInHtml(html) {
   }));
 }
 
-async function inspectNoJavaScriptSidebar() {
+// The homepage's no-JavaScript contract: navigation works and the trust band's
+// build-time star counts are baked into the HTML. One fetch feeds both checks.
+async function inspectNoJavaScriptHomepage() {
   const response = await fetch(siteUrl());
   if (!response.ok) fail(`no-JavaScript homepage returned ${response.status}`);
-  const foundation = linksInHtml(await response.text()).find(
+  const html = await response.text();
+  inspectNoJavaScriptSidebar(html);
+  await inspectNoJavaScriptStars(html);
+}
+
+function inspectNoJavaScriptSidebar(html) {
+  const foundation = linksInHtml(html).find(
     (link) => link.label === LABEL_FOUNDATIONS,
   );
   if (!foundation) fail("collapsed Foundations group has no SSR fallback link");
   if (new URL(foundation.href, siteUrl()).pathname !== FOUNDATIONS_FIRST_DOC)
     fail(`${LABEL_FOUNDATIONS} SSR fallback points to ${foundation.href}`);
 }
 
+// Asserts each count is rendered server-side from the committed snapshot, tied
+// to its "stars" label so a stray number elsewhere cannot satisfy the check.
+async function inspectNoJavaScriptStars(html) {
+  const { formatStars } = await import(pathToFileURL(FORMAT_STARS).href);
+  const { projects } = JSON.parse(fs.readFileSync(STARS_SNAPSHOT, "utf8"));
+  for (const { repo, stars } of projects) {
+    const count = formatStars(stars).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    if (!new RegExp(`>${count}</span>[^<]*<span[^>]*>stars</span>`).test(html))
+      fail(`SSR homepage is missing the baked-in star count for ${repo}`);
+  }
+}
+
 // Scoped to the desktop docs sidebar. Keep in sync with the theme's canonical
 // scroller selector (DocSidebar/Desktop/index.tsx SIDEBAR_NAV_SELECTOR): the
 // aria-label is a translated theme string, the class is stable markup.
@@ -506,7 +537,6 @@ async function inspectMobileDrawerSidebar() {
 }
 
 async function inspectSidebarNavigation() {
-  await inspectNoJavaScriptSidebar();
   const page = await browser.newPage();
   await page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 1 });
   await page.emulateMediaFeatures([
@@ -668,6 +698,7 @@ async function main() {
 
   fs.mkdirSync(TRACE_DIR, { recursive: true });
   browser = await puppeteer.launch({ headless: true });
+  await withRetry(() => inspectNoJavaScriptHomepage(), "inspectNoJavaScriptHomepage");
   await withRetry(() => inspectSidebarNavigation(), "inspectSidebarNavigation");
   await withRetry(() => inspectMobileDrawerSidebar(), "inspectMobileDrawerSidebar");
   await withRetry(() => inspectActiveChapterScroll(), "inspectActiveChapterScroll");

website/docs/intro.mdx

@@ -25,21 +25,9 @@ That skill is the whole prize. Operate the machine well and the labor moves to i
 
 **Free & open source — nothing to sell.** This book, the tools it references, and everything built around them are 100% open source, community-backed projects with no commercial agenda. No paid tiers. No enterprise licenses. Nothing to buy.
 
-- <GitHubProjectSource
-    name="Book source"
-    repo="agenticoding/agenticoding.github.io"
-    fallbackStars={102}
-  />
-- <GitHubProjectSource
-    name="ChunkHound"
-    repo="chunkhound/chunkhound"
-    fallbackStars={1400}
-  />
-- <GitHubProjectSource
-    name="Pi agenticoding extension"
-    repo="agenticoding/pi-agenticoding"
-    fallbackStars={18}
-  />
+- <GitHubProjectSource repo="agenticoding/agenticoding.github.io" />
+- <GitHubProjectSource repo="chunkhound/chunkhound" />
+- <GitHubProjectSource repo="agenticoding/pi-agenticoding" />
 
 ---
 

website/package.json

@@ -6,6 +6,7 @@
     "docusaurus": "docusaurus",
     "start": "docusaurus start",
     "build": "docusaurus build",
+    "stars:refresh": "node ../scripts/fetch-github-stars.js",
     "test": "find src -name '*.test.ts' -print0 | xargs -0 node --test",
     "audit:breakpoints": "node ../scripts/audit-breakpoints.cjs",
     "audit:responsive-diagrams": "node ../scripts/audit-responsive-diagrams.cjs",

website/src/components/GitHubSocialProof/formatStars.ts

@@ -0,0 +1,7 @@
+// Compact star counts: exact under 1k, one decimal for thousands (dropped at
+// 10k+), so a header-scale number stays scannable. Shared with the browser
+// contract test, which asserts the value is baked into the no-JavaScript HTML.
+export function formatStars(stars: number): string {
+  if (stars < 1_000) return String(stars);
+  return `${(stars / 1_000).toFixed(stars < 10_000 ? 1 : 0).replace('.0', '')}k`;
+}

website/src/components/GitHubSocialProof/index.module.css

@@ -1,4 +1,3 @@
-.hero,
 .project {
   display: inline-flex;
   gap: var(--space-0h);
@@ -9,23 +8,6 @@
   line-height: var(--lh-sm);
 }
 
-.hero {
-  color: var(--text-body);
-  font-family: var(--font-body);
-  font-size: var(--text-lg);
-  font-weight: 400;
-  line-height: var(--lh-lg);
-  vertical-align: baseline;
-  /* Overrides Docusaurus's generic content-link underline. */
-  text-decoration: none !important;
-}
-
-.hero:focus-visible {
-  outline: 2px solid var(--text-heading);
-  outline-offset: var(--space-0h);
-}
-
-.hero svg,
 .project svg {
   flex: 0 0 auto;
   width: var(--icon-sm);
@@ -42,15 +24,6 @@
   align-items: baseline;
 }
 
-.hero svg {
-  width: var(--icon-md);
-  height: var(--icon-md);
-}
-
-.hero .label {
-  font-size: var(--text-sm);
-}
-
 .count {
   color: var(--text-heading);
   font-weight: 700;
@@ -87,12 +60,6 @@
 }
 
 @media (max-width: 576px) {
-  .hero {
-    display: flex;
-    width: fit-content;
-    margin-top: var(--space-2);
-  }
-
   .projectSource {
     display: flex;
     flex-wrap: wrap;