create-stitchkit 0.1.0

package/template/e2e/starter.spec.ts

@@ -0,0 +1,237 @@
+import AxeBuilder from '@axe-core/playwright';
+import { expect, test } from '@playwright/test';
+
+test('renders the hydrated starter application and catalogue', async ({ page }) => {
+  await page.goto('/en');
+  await expect(page.getByRole('heading', { level: 1 })).toContainText(
+    'Build the product, not the plumbing',
+  );
+  await expect(page.getByText('max-listov/stitchkit')).toBeVisible();
+  await page.getByRole('link', { name: /UI system/ }).click();
+  await expect(page).toHaveURL(/\/en\/ui\/components$/);
+  await expect(page.getByRole('heading', { level: 1 })).toContainText('UI components');
+});
+
+test('publishes complete page metadata and a reachable Open Graph card', async ({
+  page,
+  request,
+}) => {
+  await page.goto('/en/ui/themes');
+  await expect(page).toHaveTitle('Theme system · Stitchkit Starter');
+  await expect(page.locator('link[rel="canonical"]')).toHaveAttribute(
+    'href',
+    /\/en\/ui\/themes$/,
+  );
+  await expect(page.locator('meta[property="og:description"]')).toHaveAttribute(
+    'content',
+    /View Transition/,
+  );
+
+  const imageUrl = await page.locator('meta[property="og:image"]').getAttribute('content');
+  expect(imageUrl).not.toBeNull();
+  if (!imageUrl) throw new Error('Open Graph image URL is missing');
+  const imageResponse = await request.get(imageUrl);
+  expect(imageResponse.status()).toBe(200);
+  expect(imageResponse.headers()['content-type']).toContain('image/png');
+
+  const sitemapResponse = await request.get('/sitemap.xml');
+  expect(sitemapResponse.status()).toBe(200);
+  expect(await sitemapResponse.text()).toContain('/ru/ui/themes');
+});
+
+test('spins the refresh icon in place while its action is pending', async ({ page }) => {
+  await page.route('**/api/repository/refresh', async (route) => {
+    await new Promise((resolve) => setTimeout(resolve, 750));
+    await route.continue();
+  });
+  await page.goto('/en');
+
+  const refresh = page.getByRole('button', { name: 'Refresh repository data' });
+  await expect(refresh).toHaveCSS('height', '32px');
+  await expect(refresh).toHaveCSS('width', '32px');
+  await expect(refresh.locator('.tabler-icon-refresh')).toHaveCount(1);
+  await refresh.click();
+  await expect(refresh).toHaveAttribute('aria-busy', 'true');
+  await expect(refresh.locator('svg')).toHaveCount(1);
+  await expect(refresh.locator('.tabler-icon-refresh')).toHaveClass(/animate-spin/);
+});
+
+test('switches catalogue sections and component tabs', async ({ page }) => {
+  await page.goto('/en/ui');
+  await expect(page).toHaveURL(/\/en\/ui\/components$/);
+
+  const navigationTrigger = page.getByRole('button', { name: 'Open navigation' });
+  const mobileNavigation = await navigationTrigger.isVisible();
+  if (mobileNavigation) await navigationTrigger.click();
+
+  await expect(page.getByRole('link', { name: 'UI components', exact: true })).toHaveAttribute(
+    'aria-current',
+    'page',
+  );
+  if (mobileNavigation) await page.getByRole('button', { name: 'Close navigation' }).click();
+  await page.getByRole('tab', { name: 'Feedback' }).click();
+  await expect(page.getByRole('tab', { name: 'Feedback' })).toHaveAttribute(
+    'aria-selected',
+    'true',
+  );
+  await page.getByRole('button', { name: 'Open project' }).click();
+  await expect(page.getByText('Project opened')).toBeVisible();
+  await page.getByRole('button', { name: 'Success toast' }).click();
+  await expect(page.getByText('Changes saved')).toBeVisible();
+
+  if (mobileNavigation) await navigationTrigger.click();
+  await page.getByRole('link', { name: 'Theme system', exact: true }).click();
+  await expect(page).toHaveURL(/\/en\/ui\/themes$/);
+});
+
+test('uses one matching focus border for inputs and textareas', async ({ page }) => {
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+  await page.goto('/en/ui/components');
+  await page.getByRole('tab', { name: 'Forms' }).click();
+
+  const input = page.getByLabel('Project name');
+  const textarea = page.getByLabel('Description');
+  const inputFocus = await input.evaluate((element) => {
+    element.focus();
+    const style = getComputedStyle(element);
+    return {
+      borderColor: style.borderColor,
+      boxShadow: style.boxShadow,
+      outlineStyle: style.outlineStyle,
+    };
+  });
+  const textareaFocus = await textarea.evaluate((element) => {
+    element.focus();
+    const style = getComputedStyle(element);
+    return {
+      borderColor: style.borderColor,
+      boxShadow: style.boxShadow,
+      outlineStyle: style.outlineStyle,
+    };
+  });
+
+  expect(textareaFocus).toEqual(inputFocus);
+  expect(textareaFocus.boxShadow).toBe('none');
+  expect(textareaFocus.outlineStyle).toBe('none');
+});
+
+test('has no serious accessibility violations on the main surfaces', async ({ page }) => {
+  test.setTimeout(90_000);
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+
+  for (const path of ['/en', '/en/ui/components', '/en/ui/themes', '/en/ui/blocks']) {
+    await page.goto(path);
+    await expect(page.locator('html')).not.toHaveClass(/theme-transitioning/);
+    const results = await new AxeBuilder({ page }).analyze();
+    const blocking = results.violations.filter(
+      (violation) => violation.impact === 'critical' || violation.impact === 'serious',
+    );
+    expect(blocking, `${path}: ${blocking.map((item) => item.id).join(', ')}`).toEqual([]);
+  }
+});
+
+test('keeps the mobile surface inside the viewport', async ({ page }) => {
+  await page.goto('/en/ui/blocks');
+  const viewport = await page.evaluate(() => ({
+    horizontalOverflow: document.documentElement.scrollWidth - window.innerWidth,
+    verticalOverflow: document.documentElement.scrollHeight - window.innerHeight,
+  }));
+  expect(viewport.horizontalOverflow).toBeLessThanOrEqual(1);
+  expect(viewport.verticalOverflow).toBeLessThanOrEqual(1);
+
+  const content = page.getByTestId('catalogue-content');
+  const scrollSurface = await content.evaluate((element) => ({
+    clientHeight: element.clientHeight,
+    scrollHeight: element.scrollHeight,
+  }));
+  expect(scrollSurface.scrollHeight).toBeGreaterThan(scrollSurface.clientHeight);
+});
+
+test('keeps the desktop starter inside one viewport', async ({ page }) => {
+  await page.setViewportSize({ width: 1440, height: 900 });
+  await page.goto('/en');
+  const overflow = await page.evaluate(
+    () => document.documentElement.scrollHeight - window.innerHeight,
+  );
+  expect(overflow).toBeLessThanOrEqual(1);
+});
+
+test('keeps long localized navigation labels inside the mobile drawer', async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto('/ru/ui/components');
+  await page.getByRole('button', { name: 'Open navigation' }).click();
+
+  const drawer = page.getByRole('dialog');
+  await expect(drawer).toBeVisible();
+  const overflow = await drawer.evaluate((element) => ({
+    drawer: element.scrollWidth - element.clientWidth,
+    labels: [...element.querySelectorAll('nav a span')].map(
+      (label) => label.scrollWidth - label.clientWidth,
+    ),
+    page: document.documentElement.scrollWidth - window.innerWidth,
+  }));
+
+  expect(overflow.drawer).toBeLessThanOrEqual(1);
+  expect(overflow.labels.every((value) => value <= 1)).toBe(true);
+  expect(overflow.page).toBeLessThanOrEqual(1);
+});
+
+test('provides a server-first synchronized theme system', async ({ context, page }) => {
+  const consoleProblems: string[] = [];
+  page.on('console', (message) => {
+    if (message.type() === 'error' || message.type() === 'warning') {
+      consoleProblems.push(message.text());
+    }
+  });
+
+  await page.goto('/en/ui/themes');
+  await expect(page.getByTestId('theme-state-selected')).not.toContainText('hydrating');
+  await expect(page.locator('#theme-scope-light')).toHaveClass(/light/);
+  await expect(page.locator('#theme-scope-dark')).toHaveClass(/dark/);
+
+  const supportsViewTransitions = await page.evaluate(
+    () => typeof document.startViewTransition === 'function',
+  );
+  if (supportsViewTransitions) {
+    await page.getByRole('button', { name: 'Radial reveal', exact: true }).click();
+    await page.getByRole('button', { name: '400 ms', exact: true }).click();
+    await page.getByRole('button', { name: 'Dark', exact: true }).click();
+    await expect(page.locator('html')).toHaveAttribute('data-theme-transition', 'radial');
+    await expect(page.locator('html')).not.toHaveAttribute('data-theme-transition', 'radial');
+  }
+
+  await page.getByRole('button', { name: 'Dark', exact: true }).click();
+  await expect(page.locator('html')).toHaveClass(/dark/);
+  await expect(page.locator('meta[name="theme-color"]')).toHaveAttribute('content', '#242428');
+  await expect(
+    page.getByAltText('Application shell selected by the resolved theme'),
+  ).toHaveAttribute('src', '/theme-dark.svg');
+
+  const secondPage = await context.newPage();
+  await secondPage.goto('/en/ui/themes');
+  await expect(secondPage.locator('html')).toHaveClass(/dark/);
+  await page.getByRole('button', { name: 'Light', exact: true }).click();
+  await expect(secondPage.locator('html')).toHaveClass(/light/);
+
+  await page.getByRole('button', { name: 'System', exact: true }).click();
+  await expect(page.getByTestId('theme-state-selected')).toContainText('system');
+  const themeCookie = (await context.cookies()).find(
+    (cookie) => cookie.name === 'stitchkit-starter-theme',
+  );
+  expect(themeCookie?.value).toBe('system');
+  await page.reload();
+  await expect(page.getByTestId('theme-state-server-cookie')).toContainText('system');
+  expect(
+    consoleProblems.filter((message) =>
+      /hydration|useServerInsertedHTML|inline script/i.test(message),
+    ),
+  ).toEqual([]);
+});
+
+test('falls back to an immediate theme update for reduced motion', async ({ page }) => {
+  await page.emulateMedia({ reducedMotion: 'reduce' });
+  await page.goto('/en/ui/themes');
+  await page.getByRole('button', { name: 'Dark', exact: true }).click();
+  await expect(page.locator('html')).toHaveClass(/dark/);
+  await expect(page.locator('html')).not.toHaveAttribute('data-theme-transition');
+});

package/template/ecosystem.config.cjs

@@ -0,0 +1,28 @@
+const path = require('node:path');
+const { config } = require('dotenv');
+
+config({ path: path.join(__dirname, '.env'), quiet: true, override: true });
+
+module.exports = {
+  apps: [
+    {
+      name: 'stitchkit-starter-backend',
+      cwd: path.join(__dirname, 'packages/backend'),
+      script: 'dist/index.js',
+      interpreter: 'bun',
+      autorestart: true,
+      kill_timeout: 15000,
+      env: { NODE_ENV: 'production' },
+    },
+    {
+      name: 'stitchkit-starter-frontend',
+      cwd: path.join(__dirname, 'packages/frontend'),
+      script: 'node_modules/.bin/next',
+      args: ['start', '--port', process.env.WEB_PORT, '--hostname', '0.0.0.0'],
+      interpreter: 'bun',
+      autorestart: true,
+      kill_timeout: 15000,
+      env: { NODE_ENV: 'production' },
+    },
+  ],
+};

package/template/ecosystem.dev.config.cjs

@@ -0,0 +1,29 @@
+const path = require('node:path');
+const { config } = require('dotenv');
+
+config({ path: path.join(__dirname, '.env'), quiet: true, override: true });
+
+module.exports = {
+  apps: [
+    {
+      name: 'stitchkit-starter-backend-dev',
+      cwd: path.join(__dirname, 'packages/backend'),
+      script: 'src/index.ts',
+      interpreter: 'bun',
+      interpreter_args: '--watch',
+      autorestart: true,
+      kill_timeout: 10000,
+      env: { NODE_ENV: 'development' },
+    },
+    {
+      name: 'stitchkit-starter-frontend-dev',
+      cwd: path.join(__dirname, 'packages/frontend'),
+      script: 'node_modules/.bin/next',
+      args: ['dev', '--port', process.env.WEB_PORT, '--hostname', '0.0.0.0'],
+      interpreter: 'bun',
+      autorestart: true,
+      kill_timeout: 10000,
+      env: { NODE_ENV: 'development' },
+    },
+  ],
+};

package/template/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "stitchkit-starter",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "packages/*"
+  ],
+  "catalog": {
+    "stitchkit": "^0.42.0"
+  },
+  "scripts": {
+    "dev": "bun scripts/dev.ts",
+    "check": "bun run db:generate && bun run check:authored && bun run --filter '*' check",
+    "check:authored": "bun scripts/check-authored.ts",
+    "test": "bun run --filter '*' test",
+    "build": "bun run db:generate && bun --filter @app/backend build && bun --filter @app/frontend build",
+    "start:api": "bun --filter @app/backend start",
+    "start:web": "bun --filter @app/frontend start",
+    "env:ensure": "bun scripts/local-env.ts",
+    "db:setup": "bun run db:generate && bun run db:deploy",
+    "db:generate": "bun run env:ensure && bun --filter @app/db db:generate",
+    "db:migrate": "bun --filter @app/db db:migrate",
+    "db:deploy": "bun --filter @app/db db:deploy",
+    "db:studio": "bun --filter @app/db db:studio",
+    "cli": "bun packages/backend/src/cli.ts",
+    "tools": "bun packages/backend/src/tools.ts",
+    "runtime:smoke": "bun scripts/runtime-smoke.ts",
+    "e2e": "playwright test",
+    "lint": "biome check --error-on-warnings .",
+    "lint:fix": "biome check --write .",
+    "pm2:dev": "bun scripts/dev.ts",
+    "pm2:prod": "bun run db:deploy && pm2 startOrReload ecosystem.config.cjs --update-env"
+  },
+  "dependencies": {
+    "dotenv": "^17.4.2"
+  },
+  "devDependencies": {
+    "@app/shared": "workspace:*",
+    "@axe-core/playwright": "^4.11.0",
+    "@biomejs/biome": "^2.5.7",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@playwright/test": "^1.55.0",
+    "@types/bun": "^1.3.14",
+    "oxc-parser": "^0.143.0",
+    "socket.io-client": "^4.8.3",
+    "typescript": "^7.0.2",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "bun": ">=1.2.0",
+    "node": ">=22"
+  },
+  "packageManager": "bun@1.3.14"
+}

package/template/packages/backend/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@app/backend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "build": "rm -rf dist && bun build src/index.ts src/cli.ts src/tools.ts --outdir dist --target bun --packages external",
+    "start": "bun dist/index.js",
+    "check": "bun x tsc --noEmit",
+    "test": "bun test --pass-with-no-tests",
+    "cli": "bun src/cli.ts",
+    "tools": "bun src/tools.ts"
+  },
+  "dependencies": {
+    "@app/config": "workspace:*",
+    "@app/db": "workspace:*",
+    "@app/shared": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@prisma/adapter-pg": "^7.9.1",
+    "@socket.io/bun-engine": "^0.1.1",
+    "ai": "^7.0.58",
+    "socket.io": "^4.8.3",
+    "stitchkit": "catalog:",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14",
+    "typescript": "^7.0.2"
+  }
+}

package/template/packages/backend/src/cli.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env bun
+
+import { createCli } from 'stitchkit/cli';
+import { createSurface } from './surface';
+
+const { services, socket } = await createSurface();
+
+try {
+  await createCli({ name: 'stitchkit-starter', version: '0.1.0', services });
+} finally {
+  await socket.io.close();
+}

package/template/packages/backend/src/domain/errors.ts

@@ -0,0 +1,9 @@
+import { defineErrors } from 'stitchkit';
+import { z } from 'zod';
+
+export const { errors: domainErrors, codes: domainErrorCodes } = defineErrors({
+  GITHUB_UNAVAILABLE: {
+    status: 503,
+    details: z.object({ cause: z.string() }),
+  },
+});

package/template/packages/backend/src/domain/repository/github-cache.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  GitHubRepositoryCache,
+  type RepositorySnapshotStore,
+  type SnapshotRecord,
+} from './github-cache';
+
+function repositoryResponse(): Response {
+  return Response.json({
+    full_name: 'max-listov/stitchkit',
+    description: 'Contract-first framework',
+    html_url: 'https://github.com/max-listov/stitchkit',
+    language: 'TypeScript',
+    visibility: 'public',
+    stargazers_count: 42,
+    forks_count: 7,
+    open_issues_count: 1,
+  });
+}
+
+function commitsResponse(): Response {
+  return Response.json(
+    [
+      {
+        sha: 'abcdef123456',
+        commit: {
+          message: 'Ship the starter\n\nDetails',
+          author: { date: '2026-08-08T00:00:00Z' },
+          committer: { date: '2026-08-08T00:00:00Z' },
+        },
+      },
+    ],
+    {
+      headers: {
+        link: '<https://api.github.com/repositories/1/commits?per_page=1&page=314>; rel="last"',
+      },
+    },
+  );
+}
+
+describe('GitHubRepositoryCache', () => {
+  test('deduplicates refreshes and persists an exact repository snapshot', async () => {
+    const requests: URL[] = [];
+    const fetcher = async (url: URL) => {
+      requests.push(url);
+      return url.pathname.endsWith('/commits') ? commitsResponse() : repositoryResponse();
+    };
+    let stored: SnapshotRecord | null = null;
+    const store: RepositorySnapshotStore = {
+      read: async () => stored,
+      write: async (snapshot) => {
+        stored = snapshot;
+        return snapshot;
+      },
+    };
+
+    const cache = new GitHubRepositoryCache(fetcher, store);
+    const [first, concurrent] = await Promise.all([cache.read(), cache.read()]);
+
+    expect(first).toEqual(concurrent);
+    expect(first.fullName).toBe('max-listov/stitchkit');
+    expect(first.visibility).toBe('PUBLIC');
+    expect(first.commitCount).toBe(314);
+    expect(first.latestCommit?.message).toBe('Ship the starter');
+    expect(first.cache.state).toBe('revalidated');
+    expect(requests).toHaveLength(2);
+
+    const cached = await cache.read();
+    expect(cached.cache.state).toBe('fresh');
+    expect(requests).toHaveLength(2);
+  });
+});

package/template/packages/backend/src/domain/repository/github-cache.ts

@@ -0,0 +1,205 @@
+import { env } from '@app/config';
+import { RepositoryVisibility } from '@app/db';
+import type { RepositorySnapshot } from '@app/shared';
+import { z } from 'zod';
+import { prisma } from '../../lib/db';
+import { domainErrors } from '../errors';
+
+const GitHubRepositoryResponseSchema = z.object({
+  full_name: z.string(),
+  description: z.string().nullable(),
+  html_url: z.url(),
+  language: z.string().nullable(),
+  visibility: z.enum(['public', 'private', 'internal']),
+  stargazers_count: z.number().int().nonnegative(),
+  forks_count: z.number().int().nonnegative(),
+  open_issues_count: z.number().int().nonnegative(),
+});
+
+const GitHubCommitResponseSchema = z.array(
+  z.object({
+    sha: z.string().min(1),
+    commit: z.object({
+      message: z.string().min(1),
+      author: z.object({ date: z.iso.datetime().nullable() }).nullable(),
+      committer: z.object({ date: z.iso.datetime().nullable() }).nullable(),
+    }),
+  }),
+);
+
+const RepositoryNameSchema = z
+  .string()
+  .regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/, 'Expected owner/repository');
+
+type RepositoryFetcher = (url: URL, init: RequestInit) => Promise<Response>;
+export interface SnapshotRecord {
+  fullName: string;
+  description: string | null;
+  htmlUrl: string;
+  language: string | null;
+  visibility: RepositoryVisibility;
+  stars: number;
+  forks: number;
+  openIssues: number;
+  commitCount: number;
+  latestCommitSha: string | null;
+  latestCommitMessage: string | null;
+  latestCommittedAt: Date | null;
+  fetchedAt: Date;
+  expiresAt: Date;
+}
+
+function repositoryVisibility(
+  visibility: z.infer<typeof GitHubRepositoryResponseSchema>['visibility'],
+): RepositoryVisibility {
+  switch (visibility) {
+    case 'public':
+      return RepositoryVisibility.PUBLIC;
+    case 'private':
+      return RepositoryVisibility.PRIVATE;
+    case 'internal':
+      return RepositoryVisibility.INTERNAL;
+  }
+}
+
+export interface RepositorySnapshotStore {
+  read(fullName: string): Promise<SnapshotRecord | null>;
+  write(snapshot: SnapshotRecord): Promise<SnapshotRecord>;
+}
+
+const snapshotStore: RepositorySnapshotStore = {
+  read: (fullName) => prisma.repositorySnapshot.findUnique({ where: { fullName } }),
+  write: (snapshot) =>
+    prisma.repositorySnapshot.upsert({
+      where: { fullName: snapshot.fullName },
+      create: snapshot,
+      update: snapshot,
+    }),
+};
+
+function githubHeaders(): Headers {
+  const headers = new Headers({
+    Accept: 'application/vnd.github+json',
+    'User-Agent': 'stitchkit-starter',
+    'X-GitHub-Api-Version': '2026-03-10',
+  });
+  if (env.GITHUB_TOKEN) headers.set('Authorization', `Bearer ${env.GITHUB_TOKEN}`);
+  return headers;
+}
+
+function commitCount(response: Response, visibleCommits: number): number {
+  const link = response.headers.get('link');
+  const lastPage = link?.match(/<[^>]*[?&]page=(\d+)[^>]*>; rel="last"/)?.[1];
+  return lastPage ? z.coerce.number().int().nonnegative().parse(lastPage) : visibleCommits;
+}
+
+function serialize(
+  record: SnapshotRecord,
+  state: RepositorySnapshot['cache']['state'],
+): RepositorySnapshot {
+  const latestCommit =
+    record.latestCommitSha && record.latestCommitMessage && record.latestCommittedAt
+      ? {
+          sha: record.latestCommitSha,
+          message: record.latestCommitMessage,
+          committedAt: record.latestCommittedAt.toISOString(),
+        }
+      : null;
+
+  return {
+    fullName: record.fullName,
+    description: record.description,
+    htmlUrl: record.htmlUrl,
+    language: record.language,
+    visibility: record.visibility,
+    stars: record.stars,
+    forks: record.forks,
+    openIssues: record.openIssues,
+    commitCount: record.commitCount,
+    latestCommit,
+    cache: {
+      state,
+      fetchedAt: record.fetchedAt.toISOString(),
+      expiresAt: record.expiresAt.toISOString(),
+    },
+  };
+}
+
+export class GitHubRepositoryCache {
+  private refreshPromise?: Promise<RepositorySnapshot>;
+
+  constructor(
+    private readonly fetcher: RepositoryFetcher = (url, init) => fetch(url, init),
+    private readonly store: RepositorySnapshotStore = snapshotStore,
+  ) {}
+
+  async read(): Promise<RepositorySnapshot> {
+    const repository = RepositoryNameSchema.parse(env.GITHUB_REPOSITORY);
+    const snapshot = await this.store.read(repository);
+    if (snapshot && snapshot.expiresAt > new Date()) return serialize(snapshot, 'fresh');
+    return this.refresh();
+  }
+
+  refresh(): Promise<RepositorySnapshot> {
+    if (this.refreshPromise) return this.refreshPromise;
+    this.refreshPromise = this.revalidate().finally(() => {
+      this.refreshPromise = undefined;
+    });
+    return this.refreshPromise;
+  }
+
+  private async revalidate(): Promise<RepositorySnapshot> {
+    const repositoryName = RepositoryNameSchema.parse(env.GITHUB_REPOSITORY);
+    const previous = await this.store.read(repositoryName);
+
+    try {
+      const [repositoryResponse, commitsResponse] = await Promise.all([
+        this.fetcher(new URL(`/repos/${repositoryName}`, 'https://api.github.com'), {
+          headers: githubHeaders(),
+          signal: AbortSignal.timeout(8_000),
+        }),
+        this.fetcher(
+          new URL(`/repos/${repositoryName}/commits?per_page=1`, 'https://api.github.com'),
+          { headers: githubHeaders(), signal: AbortSignal.timeout(8_000) },
+        ),
+      ]);
+      if (!repositoryResponse.ok || !commitsResponse.ok) {
+        throw new Error(
+          `GitHub returned repository=${repositoryResponse.status}, commits=${commitsResponse.status}`,
+        );
+      }
+
+      const repository = GitHubRepositoryResponseSchema.parse(await repositoryResponse.json());
+      const commits = GitHubCommitResponseSchema.parse(await commitsResponse.json());
+      const latest = commits[0];
+      const committedAt = latest?.commit.author?.date ?? latest?.commit.committer?.date;
+      if (latest && !committedAt) throw new Error('The latest GitHub commit has no timestamp');
+
+      const fetchedAt = new Date();
+      const snapshot = await this.store.write({
+        fullName: repository.full_name,
+        description: repository.description,
+        htmlUrl: repository.html_url,
+        language: repository.language,
+        visibility: repositoryVisibility(repository.visibility),
+        stars: repository.stargazers_count,
+        forks: repository.forks_count,
+        openIssues: repository.open_issues_count,
+        commitCount: commitCount(commitsResponse, commits.length),
+        latestCommitSha: latest?.sha ?? null,
+        latestCommitMessage: latest?.commit.message.split('\n')[0] ?? null,
+        latestCommittedAt: committedAt ? new Date(committedAt) : null,
+        fetchedAt,
+        expiresAt: new Date(fetchedAt.getTime() + env.GITHUB_CACHE_TTL_SECONDS * 1_000),
+      });
+      return serialize(snapshot, 'revalidated');
+    } catch (error) {
+      if (previous) return serialize(previous, 'stale');
+      throw domainErrors.GITHUB_UNAVAILABLE({
+        message: 'GitHub repository data is temporarily unavailable',
+        details: { cause: error instanceof Error ? error.message : 'Unknown upstream error' },
+        hint: 'Retry after the upstream service recovers',
+      });
+    }
+  }
+}