create-top-secret-starter 0.0.1

package/templates/template-router/src/index.css

@@ -0,0 +1,134 @@
+@import 'tailwindcss';
+@import 'tw-animate-css';
+@import 'shadcn/tailwind.css';
+@import '@fontsource-variable/inter';
+
+@custom-variant dark (&:is(.dark *));
+
+@theme inline {
+  --font-heading: var(--font-sans);
+  --font-sans: 'Inter Variable', sans-serif;
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --color-foreground: var(--foreground);
+  --color-background: var(--background);
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) * 1.4);
+  --radius-2xl: calc(var(--radius) * 1.8);
+  --radius-3xl: calc(var(--radius) * 2.2);
+  --radius-4xl: calc(var(--radius) * 2.6);
+}
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.87 0 0);
+  --chart-2: oklch(0.556 0 0);
+  --chart-3: oklch(0.439 0 0);
+  --chart-4: oklch(0.371 0 0);
+  --chart-5: oklch(0.269 0 0);
+  --radius: 0.625rem;
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.205 0 0);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.205 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.269 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.87 0 0);
+  --chart-2: oklch(0.556 0 0);
+  --chart-3: oklch(0.439 0 0);
+  --chart-4: oklch(0.371 0 0);
+  --chart-5: oklch(0.269 0 0);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.556 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+  button:not(:disabled),
+  [role='button']:not(:disabled) {
+    cursor: pointer;
+  }
+  html {
+    @apply font-sans;
+  }
+}

package/templates/template-router/src/lib/query-client.test.ts

@@ -0,0 +1,82 @@
+import { HTTPError } from 'ky'
+import { beforeEach, expect, it, vi } from 'vitest'
+
+import { queryClient } from '@/lib/query-client'
+
+vi.mock('sonner', () => ({ toast: { error: vi.fn() } }))
+const { toast } = await import('sonner')
+
+const httpError = (status: number) =>
+  new HTTPError(
+    new Response(null, { status }),
+    new Request('http://localhost/api/x'),
+    // ky only reads .retry off the options object here
+    { retry: {} } as never
+  )
+
+beforeEach(() => {
+  vi.mocked(toast.error).mockClear()
+  queryClient.clear()
+})
+
+// notifyError imports sonner dynamically, so the toast lands a tick after the
+// query/mutation promise settles
+const flushToasts = () => vi.dynamicImportSettled()
+
+it('stays silent when a query fails with no data on screen', async () => {
+  await queryClient
+    .fetchQuery({
+      queryKey: ['a'],
+      queryFn: () => Promise.reject(httpError(500)),
+      retry: false
+    })
+    .catch(() => {})
+  await flushToasts()
+
+  // the route's error component already tells the user; a toast would double up
+  expect(toast.error).not.toHaveBeenCalled()
+})
+
+it('toasts when a background refetch fails over data already shown', async () => {
+  await queryClient.fetchQuery({ queryKey: ['b'], queryFn: () => Promise.resolve('data') })
+
+  await queryClient
+    .fetchQuery({
+      queryKey: ['b'],
+      queryFn: () => Promise.reject(httpError(500)),
+      staleTime: 0,
+      retry: false
+    })
+    .catch(() => {})
+  await flushToasts()
+
+  expect(toast.error).toHaveBeenCalledTimes(1)
+})
+
+it('always toasts a failed mutation', async () => {
+  await queryClient
+    .getMutationCache()
+    .build(queryClient, { mutationFn: () => Promise.reject(new Error('nope')) })
+    .execute(undefined)
+    .catch(() => {})
+  await flushToasts()
+
+  expect(toast.error).toHaveBeenCalledTimes(1)
+})
+
+it('does not retry a 4xx query', async () => {
+  const queryFn = vi.fn(() => Promise.reject(httpError(404)))
+
+  await queryClient.fetchQuery({ queryKey: ['c'], queryFn }).catch(() => {})
+
+  expect(queryFn).toHaveBeenCalledTimes(1)
+})
+
+it('retries a 5xx query up to the configured limit', async () => {
+  const queryFn = vi.fn(() => Promise.reject(httpError(503)))
+
+  await queryClient.fetchQuery({ queryKey: ['d'], queryFn, retryDelay: 0 }).catch(() => {})
+
+  // initial attempt + 2 retries
+  expect(queryFn).toHaveBeenCalledTimes(3)
+})

package/templates/template-router/src/lib/query-client.ts

@@ -0,0 +1,30 @@
+import { MutationCache, QueryCache, QueryClient } from '@tanstack/react-query'
+import { HTTPError } from 'ky'
+
+const isClientError = (error: unknown) =>
+  error instanceof HTTPError && error.response.status >= 400 && error.response.status < 500
+
+// Dynamic import keeps sonner out of the entry chunk (~8 kB gzip). Safe to fire
+// before <Toaster> mounts: sonner replays active toasts to a new subscriber.
+const notifyError = (error: unknown) => {
+  const message = error instanceof Error ? error.message : 'Something went wrong'
+  void import('sonner').then(({ toast }) => toast.error(message))
+}
+
+export const queryClient = new QueryClient({
+  queryCache: new QueryCache({
+    onError: (error, query) => {
+      if (query.state.data !== undefined) notifyError(error)
+    }
+  }),
+  mutationCache: new MutationCache({ onError: notifyError }),
+  defaultOptions: {
+    queries: {
+      staleTime: 60_000,
+      retry: (failureCount, error) => !isClientError(error) && failureCount < 2
+    },
+    mutations: {
+      retry: false
+    }
+  }
+})

package/templates/template-router/src/lib/single-flight.test.ts

@@ -0,0 +1,48 @@
+import { singleFlight } from '@/lib/single-flight'
+
+const deferred = <T>() => {
+  let resolve!: (value: T) => void
+  let reject!: (reason?: unknown) => void
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  return { promise, resolve, reject }
+}
+
+it('collapses concurrent calls into a single in-flight invocation', async () => {
+  const d = deferred<number>()
+  const fn = vi.fn(() => d.promise)
+  const wrapped = singleFlight(fn)
+
+  const a = wrapped()
+  const b = wrapped()
+
+  expect(fn).toHaveBeenCalledTimes(1)
+  expect(a).toBe(b)
+
+  d.resolve(42)
+  await expect(a).resolves.toBe(42)
+})
+
+it('re-invokes after the previous call settles', async () => {
+  const fn = vi.fn(() => Promise.resolve('ok'))
+  const wrapped = singleFlight(fn)
+
+  await wrapped()
+  await wrapped()
+
+  expect(fn).toHaveBeenCalledTimes(2)
+})
+
+it('clears the pending slot on rejection so the next call retries', async () => {
+  const fn = vi
+    .fn<() => Promise<string>>()
+    .mockRejectedValueOnce(new Error('boom'))
+    .mockResolvedValueOnce('recovered')
+  const wrapped = singleFlight(fn)
+
+  await expect(wrapped()).rejects.toThrow('boom')
+  await expect(wrapped()).resolves.toBe('recovered')
+  expect(fn).toHaveBeenCalledTimes(2)
+})

package/templates/template-router/src/lib/single-flight.ts

@@ -0,0 +1,9 @@
+export const singleFlight = <T>(fn: () => Promise<T>): (() => Promise<T>) => {
+  let pending: Promise<T> | null = null
+  return () => {
+    pending ??= fn().finally(() => {
+      pending = null
+    })
+    return pending
+  }
+}

package/templates/template-router/src/lib/utils.ts

@@ -0,0 +1 @@
+export { cn, type ClassValue } from 'cnfast'

package/templates/template-router/src/main.tsx

@@ -0,0 +1,26 @@
+import { RouterProvider } from '@tanstack/react-router'
+import { createRoot } from 'react-dom/client'
+
+import { mocksEnabled } from '@/env'
+import { Providers } from '@/providers'
+import { router } from '@/router'
+
+import '@/index.css'
+
+// `import.meta.env.DEV` must be the first operand: it is replaced with a literal
+// at build time, so the whole branch — including the dynamic import — is dropped
+// from production builds. `mocksEnabled` alone is a runtime value, and Vite would
+// still emit the mock backend as a lazy chunk.
+if (import.meta.env.DEV && mocksEnabled) {
+  const { installMockServer } = await import('@/mocks/mock-server')
+  installMockServer()
+}
+
+const rootEl = document.getElementById('root')
+if (!rootEl) throw new Error('#root not found')
+
+createRoot(rootEl).render(
+  <Providers>
+    <RouterProvider router={router} />
+  </Providers>
+)

package/templates/template-router/src/mocks/mock-server.ts

@@ -0,0 +1,149 @@
+/**
+ * Throwaway in-memory backend for local dev. Patches global `fetch` for `/api/*`.
+ *
+ * TO REMOVE: delete `src/mocks/`, drop the `mocksEnabled` block in `src/main.tsx`,
+ * and remove `VITE_ENABLE_MOCKS` from `src/env.ts`.
+ *
+ * Seed login — email: demo@example.com  password: demo1234
+ */
+
+import type { Session, Tokens, User } from '@/api/auth/schema'
+
+// Latency makes loading states visible during development. In tests it is pure
+// waiting: it accounted for 5.8s of a 5.9s suite, which slows the Stop-hook gate
+// for no signal. `MODE` is statically replaced, so this costs nothing at runtime.
+const LATENCY_MS = import.meta.env.MODE === 'test' ? 0 : 300
+const ACCESS_TTL_MS = 15 * 60 * 1000
+
+const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))
+const nonce = () => Math.random().toString(36).slice(2)
+
+type MockUser = { id: string; email: string; password: string }
+
+const users = new Map<string, MockUser>([
+  ['demo@example.com', { id: 'u_demo', email: 'demo@example.com', password: 'demo1234' }]
+])
+
+const validRefreshTokens = new Set<string>()
+
+const issueAccess = (userId: string) => `mock.access.${userId}.${Date.now() + ACCESS_TTL_MS}`
+
+const issueRefresh = (userId: string) => {
+  const token = `mock.refresh.${userId}.${nonce()}`
+  validRefreshTokens.add(token)
+  return token
+}
+
+const userIdFromAccess = (token: string | null): string | null => {
+  const [kind, sub, userId, exp] = token?.split('.') ?? []
+  if (kind !== 'mock' || sub !== 'access' || !userId) return null
+  return Number(exp) > Date.now() ? userId : null
+}
+
+// `satisfies` ties the mock's wire shapes to src/api/auth/schema.ts: changing a
+// schema breaks the mock at compile time instead of at the zod boundary at runtime.
+const publicUser = (user: MockUser) => ({ id: user.id, email: user.email }) satisfies User
+
+const json = (data: unknown, status = 200) =>
+  new Response(JSON.stringify(data), {
+    status,
+    headers: { 'content-type': 'application/json' }
+  })
+
+type MockRequest = { method: string; path: string; bearer: string | null; body: unknown }
+
+const handle = async ({ method, path, bearer, body }: MockRequest): Promise<Response> => {
+  const route = `${method} ${path}`
+
+  switch (route) {
+    case 'POST /api/auth/login': {
+      const { email, password } = (body ?? {}) as Partial<MockUser>
+      const user = email ? users.get(email) : undefined
+      if (!user || user.password !== password) return json({ message: 'Invalid credentials' }, 401)
+      return json({
+        user: publicUser(user),
+        accessToken: issueAccess(user.id),
+        refreshToken: issueRefresh(user.id)
+      } satisfies Session)
+    }
+
+    case 'POST /api/auth/refresh': {
+      const { refreshToken } = (body ?? {}) as { refreshToken?: string }
+      const [kind, sub, userId] = refreshToken?.split('.') ?? []
+      if (kind !== 'mock' || sub !== 'refresh' || !userId || !validRefreshTokens.has(refreshToken!))
+        return json({ message: 'Invalid refresh token' }, 401)
+
+      validRefreshTokens.delete(refreshToken!)
+      return json({
+        accessToken: issueAccess(userId),
+        refreshToken: issueRefresh(userId)
+      } satisfies Tokens)
+    }
+
+    case 'POST /api/auth/logout': {
+      const userId = userIdFromAccess(bearer)
+      if (userId) {
+        for (const t of validRefreshTokens)
+          if (t.startsWith(`mock.refresh.${userId}.`)) validRefreshTokens.delete(t)
+      }
+      return new Response(null, { status: 204 })
+    }
+
+    case 'GET /api/auth/me': {
+      const userId = userIdFromAccess(bearer)
+      const user = [...users.values()].find(u => u.id === userId)
+      if (!user) return json({ message: 'Unauthorized' }, 401)
+      return json(publicUser(user))
+    }
+
+    default:
+      return json({ message: `No mock handler for ${route}` }, 404)
+  }
+}
+
+// clone-based reads leave the caller's original Request untouched, so ky can still retry it
+const normalize = async (
+  input: RequestInfo | URL,
+  init: RequestInit | undefined,
+  path: string
+): Promise<MockRequest> => {
+  const request = input instanceof Request ? input : null
+  const method = (init?.method ?? request?.method ?? 'GET').toUpperCase()
+  const headers = new Headers(init?.headers ?? request?.headers)
+
+  let raw: string | null = null
+  if (typeof init?.body === 'string') raw = init.body
+  else if (request)
+    raw = await request
+      .clone()
+      .text()
+      .catch(() => null)
+
+  return {
+    method,
+    path,
+    bearer: headers.get('authorization')?.replace('Bearer ', '') ?? null,
+    body: raw ? JSON.parse(raw) : null
+  }
+}
+
+export const installMockServer = () => {
+  const originalFetch = globalThis.fetch
+
+  globalThis.fetch = async (input, init) => {
+    const href = input instanceof Request ? input.url : input instanceof URL ? input.href : input
+    if (!href.includes('/api/')) return originalFetch(input, init)
+
+    const { pathname } = new URL(href, globalThis.location?.origin ?? 'http://localhost')
+    if (!pathname.startsWith('/api/')) return originalFetch(input, init)
+
+    await sleep(LATENCY_MS)
+    return handle(await normalize(input, init, pathname))
+  }
+
+  console.info('[mock-server] active — login demo@example.com / demo1234')
+
+  return () => {
+    globalThis.fetch = originalFetch
+  }
+}

package/templates/template-router/src/providers/index.tsx

@@ -0,0 +1,27 @@
+import type { PropsWithChildren } from 'react'
+import { lazy, Suspense } from 'react'
+
+import { TooltipProvider } from '@/components/ui/tooltip'
+
+import { queryClient } from '@/lib/query-client'
+import { QueryClientProvider } from '@tanstack/react-query'
+import { ThemeProvider } from './theme'
+
+// Lazy so sonner stays out of the entry chunk (~8 kB gzip). A toast fired in the
+// first frames renders as soon as the chunk lands; sonner queues via its store.
+const Toaster = lazy(() => import('@/components/ui/sonner').then(m => ({ default: m.Toaster })))
+
+export const Providers = ({ children }: PropsWithChildren) => {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ThemeProvider>
+        <TooltipProvider>
+          {children}
+          <Suspense>
+            <Toaster richColors closeButton duration={5_000} />
+          </Suspense>
+        </TooltipProvider>
+      </ThemeProvider>
+    </QueryClientProvider>
+  )
+}

package/templates/template-router/src/providers/theme.test.tsx

@@ -0,0 +1,68 @@
+import { render, screen } from '@testing-library/react'
+import { act } from 'react'
+import { beforeEach, expect, it } from 'vitest'
+
+import { ThemeProvider, useTheme } from '@/providers/theme'
+
+const Probe = () => <span data-testid='theme'>{useTheme().theme}</span>
+
+const theme = () => screen.getByTestId('theme').textContent
+
+const writeFromAnotherTab = (value: string | null) =>
+  act(() => {
+    window.dispatchEvent(new StorageEvent('storage', { key: 'ui-theme:v1', newValue: value }))
+  })
+
+beforeEach(() => {
+  localStorage.clear()
+  document.documentElement.classList.remove('dark')
+})
+
+it('adopts the stored theme on mount', () => {
+  localStorage.setItem('ui-theme:v1', 'dark')
+  render(
+    <ThemeProvider>
+      <Probe />
+    </ThemeProvider>
+  )
+  expect(theme()).toBe('dark')
+})
+
+it('falls back to system for a value it does not recognise', () => {
+  localStorage.setItem('ui-theme:v1', 'neon')
+  render(
+    <ThemeProvider>
+      <Probe />
+    </ThemeProvider>
+  )
+  expect(theme()).toBe('system')
+})
+
+it('follows a theme change made in another tab', () => {
+  render(
+    <ThemeProvider>
+      <Probe />
+    </ThemeProvider>
+  )
+  expect(theme()).toBe('system')
+
+  writeFromAnotherTab('dark')
+
+  expect(theme()).toBe('dark')
+  expect(document.documentElement.classList.contains('dark')).toBe(true)
+})
+
+it('ignores cross-tab writes to unrelated keys', () => {
+  localStorage.setItem('ui-theme:v1', 'dark')
+  render(
+    <ThemeProvider>
+      <Probe />
+    </ThemeProvider>
+  )
+
+  act(() => {
+    window.dispatchEvent(new StorageEvent('storage', { key: 'session', newValue: null }))
+  })
+
+  expect(theme()).toBe('dark')
+})

package/templates/template-router/src/providers/theme.tsx

@@ -0,0 +1,76 @@
+import type { PropsWithChildren } from 'react'
+import { createContext, use, useEffect, useState } from 'react'
+
+export type Theme = 'dark' | 'light' | 'system'
+
+type ThemeProviderState = {
+  theme: Theme
+  setTheme: (theme: Theme) => void
+}
+
+const STORAGE_KEY = 'ui-theme:v1'
+const DEFAULT_THEME: Theme = 'system'
+
+const isTheme = (value: unknown): value is Theme =>
+  value === 'dark' || value === 'light' || value === 'system'
+
+const ThemeProviderContext = createContext<ThemeProviderState | null>(null)
+
+const applyTheme = (theme: Theme) => {
+  const resolved =
+    theme === 'system'
+      ? window.matchMedia('(prefers-color-scheme: dark)').matches
+        ? 'dark'
+        : 'light'
+      : theme
+
+  const style = document.createElement('style')
+  style.textContent = '*,*::before,*::after{transition:none!important}'
+  document.head.appendChild(style)
+  document.documentElement.classList.toggle('dark', resolved === 'dark')
+
+  // flush the transition-disabling style before removing it, so the theme swap doesn't animate
+  void window.getComputedStyle(document.documentElement).transition
+  setTimeout(() => style.remove(), 1)
+}
+
+export const ThemeProvider = ({ children }: PropsWithChildren) => {
+  const [theme, setThemeState] = useState<Theme>(() => {
+    const stored = localStorage.getItem(STORAGE_KEY)
+    return isTheme(stored) ? stored : DEFAULT_THEME
+  })
+
+  useEffect(() => {
+    applyTheme(theme)
+    if (theme !== 'system') return
+
+    const mq = window.matchMedia('(prefers-color-scheme: dark)')
+    const onChange = () => applyTheme('system')
+    mq.addEventListener('change', onChange)
+    return () => mq.removeEventListener('change', onChange)
+  }, [theme])
+
+  // localStorage is read once on mount, but another tab can change it at any
+  // time. Without this the two tabs disagree until one of them reloads.
+  useEffect(() => {
+    const onStorage = (e: StorageEvent) => {
+      if (e.key !== STORAGE_KEY) return
+      setThemeState(isTheme(e.newValue) ? e.newValue : DEFAULT_THEME)
+    }
+    window.addEventListener('storage', onStorage)
+    return () => window.removeEventListener('storage', onStorage)
+  }, [])
+
+  const setTheme = (next: Theme) => {
+    localStorage.setItem(STORAGE_KEY, next)
+    setThemeState(next)
+  }
+
+  return <ThemeProviderContext value={{ theme, setTheme }}>{children}</ThemeProviderContext>
+}
+
+export const useTheme = () => {
+  const ctx = use(ThemeProviderContext)
+  if (!ctx) throw new Error('useTheme must be used within <ThemeProvider>')
+  return ctx
+}