create-fullstack-scaffold 0.1.1 → 0.2.0

package/template/src/server/core/isr-cache.ts

@@ -0,0 +1,239 @@
+/**
+ * @framework-baseline b820abc546e81b6c
+ *
+ * ISR (Incremental Static Regeneration) cache layer.
+ * Supports Cloudflare Cache API and in-memory fallback.
+ *
+ * @framework-modify
+ * @reason 移除未使用的 fullOptions 变量，修复 TypeScript strict 检查
+ * @impact 不影响功能，仅清理代码
+ */
+
+export interface ISRCacheEntry {
+  html: string
+  createdAt: number
+  revalidateAt: number
+}
+
+export interface ISRLookupResult {
+  status: 'fresh' | 'stale' | 'miss'
+  html: string | null
+  entry?: ISRCacheEntry
+}
+
+export interface ISRCacheOptions {
+  maxAge?: number
+  staleWhileRevalidate?: number
+}
+
+const DEFAULT_MAX_AGE = 60
+const DEFAULT_STALE_WHILE_REVALIDATE = 300
+
+const ISR_ROUTES = ['/', '/todos', '/content', '/notifications', '/websocket']
+
+const ISR_ROUTE_PREFIXES = ['/content/']
+
+export function isISRRoute(pathname: string): boolean {
+  if (ISR_ROUTES.includes(pathname)) return true
+  for (const prefix of ISR_ROUTE_PREFIXES) {
+    if (pathname.startsWith(prefix)) return true
+  }
+  return false
+}
+
+export function generateCacheKey(pathname: string): string {
+  const normalized = pathname === '/' ? '/index' : pathname.replace(/\/$/, '')
+  return `isr:${normalized}`
+}
+
+interface ISRCacheStore {
+  get(key: string): Promise<ISRCacheEntry | null>
+  set(key: string, html: string, options: Required<ISRCacheOptions>): Promise<void>
+  purge(key: string): Promise<void>
+  purgePattern(pattern: string): Promise<void>
+}
+
+class MemoryCacheStore implements ISRCacheStore {
+  private cache = new Map<string, ISRCacheEntry>()
+  private timer: ReturnType<typeof setInterval> | null = null
+
+  constructor() {
+    this.timer = setInterval(() => this.cleanup(), 60000)
+    if (this.timer && typeof this.timer === 'object' && 'unref' in this.timer) {
+      this.timer.unref()
+    }
+  }
+
+  private cleanup(): void {
+    const now = Date.now()
+    for (const [key, entry] of this.cache) {
+      if (now > entry.revalidateAt + 60000) {
+        this.cache.delete(key)
+      }
+    }
+  }
+
+  async get(key: string): Promise<ISRCacheEntry | null> {
+    return this.cache.get(key) ?? null
+  }
+
+  async set(key: string, html: string, options: Required<ISRCacheOptions>): Promise<void> {
+    const now = Date.now()
+    this.cache.set(key, {
+      html,
+      createdAt: now,
+      revalidateAt: now + options.maxAge * 1000,
+    })
+  }
+
+  async purge(key: string): Promise<void> {
+    this.cache.delete(key)
+  }
+
+  async purgePattern(pattern: string): Promise<void> {
+    const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$')
+    for (const key of this.cache.keys()) {
+      if (regex.test(key)) {
+        this.cache.delete(key)
+      }
+    }
+  }
+
+  destroy(): void {
+    if (this.timer) {
+      clearInterval(this.timer)
+      this.timer = null
+    }
+    this.cache.clear()
+  }
+}
+
+class CloudflareCacheStore implements ISRCacheStore {
+  private cache: Cache | null = null
+  private origin = 'https://isr.local'
+
+  private async getCache(): Promise<Cache> {
+    if (!this.cache) {
+      this.cache = await caches.open('isr-pages')
+    }
+    return this.cache
+  }
+
+  private toUrl(key: string): string {
+    return `${this.origin}${key.replace(/^isr:/, '')}`
+  }
+
+  async get(key: string): Promise<ISRCacheEntry | null> {
+    const cache = await this.getCache()
+    const url = this.toUrl(key)
+    const response = await cache.match(url)
+    if (!response) return null
+
+    const html = await response.text()
+    const createdAt = Number(response.headers.get('x-isr-created-at') || '0')
+    const revalidateAt = Number(response.headers.get('x-isr-revalidate-at') || '0')
+
+    return { html, createdAt, revalidateAt }
+  }
+
+  async set(key: string, html: string, options: Required<ISRCacheOptions>): Promise<void> {
+    const cache = await this.getCache()
+    const url = this.toUrl(key)
+    const now = Date.now()
+
+    const response = new Response(html, {
+      headers: {
+        'Content-Type': 'text/html;charset=UTF-8',
+        'x-isr-created-at': String(now),
+        'x-isr-revalidate-at': String(now + options.maxAge * 1000),
+        'x-isr-max-age': String(options.maxAge),
+        'x-isr-stale-while-revalidate': String(options.staleWhileRevalidate),
+        'Cache-Control': `public, max-age=${options.maxAge}, s-maxage=${options.maxAge}, stale-while-revalidate=${options.staleWhileRevalidate}`,
+      },
+    })
+
+    await cache.put(url, response)
+  }
+
+  async purge(key: string): Promise<void> {
+    const cache = await this.getCache()
+    const url = this.toUrl(key)
+    await cache.delete(url)
+  }
+
+  async purgePattern(pattern: string): Promise<void> {
+    const cache = await this.getCache()
+    const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$')
+    const allKeys: Request[] = []
+
+    for (const request of allKeys) {
+      const url = new URL(request.url)
+      const key = `isr:${url.pathname}`
+      if (regex.test(key)) {
+        await cache.delete(request)
+      }
+    }
+  }
+}
+
+export interface ISRCache {
+  lookup(pathname: string): Promise<ISRLookupResult>
+  store(pathname: string, html: string, options?: ISRCacheOptions): Promise<void>
+  purge(pathname: string): Promise<void>
+  purgePattern(pattern: string): Promise<void>
+  getStore(): ISRCacheStore
+}
+
+export function createISRCache(options?: ISRCacheOptions): ISRCache {
+  const maxAge = options?.maxAge ?? DEFAULT_MAX_AGE
+  const staleWhileRevalidate = options?.staleWhileRevalidate ?? DEFAULT_STALE_WHILE_REVALIDATE
+
+  const isCloudflare = typeof caches !== 'undefined' && typeof caches.open === 'function'
+  const store: ISRCacheStore = isCloudflare ? new CloudflareCacheStore() : new MemoryCacheStore()
+
+  return {
+    async lookup(pathname: string): Promise<ISRLookupResult> {
+      const key = generateCacheKey(pathname)
+      const entry = await store.get(key)
+
+      if (!entry) {
+        return { status: 'miss', html: null }
+      }
+
+      const now = Date.now()
+      const staleTime = entry.revalidateAt + staleWhileRevalidate * 1000
+
+      if (now <= entry.revalidateAt) {
+        return { status: 'fresh', html: entry.html, entry }
+      }
+
+      if (now <= staleTime) {
+        return { status: 'stale', html: entry.html, entry }
+      }
+
+      return { status: 'miss', html: null }
+    },
+
+    async store(pathname: string, html: string, opts?: ISRCacheOptions): Promise<void> {
+      const key = generateCacheKey(pathname)
+      const storeOpts = {
+        maxAge: opts?.maxAge ?? maxAge,
+        staleWhileRevalidate: opts?.staleWhileRevalidate ?? staleWhileRevalidate,
+      }
+      await store.set(key, html, storeOpts)
+    },
+
+    async purge(pathname: string): Promise<void> {
+      const key = generateCacheKey(pathname)
+      await store.purge(key)
+    },
+
+    async purgePattern(pattern: string): Promise<void> {
+      await store.purgePattern(pattern)
+    },
+
+    getStore(): ISRCacheStore {
+      return store
+    },
+  }
+}

package/template/src/server/core/isr-invalidation.ts

@@ -0,0 +1,45 @@
+/**
+ * @framework-baseline a124c5bce28416ca
+ *
+ * @framework-modify
+ * @reason 自动生成的基准更新
+ * @impact 无功能影响
+ */
+
+/**
+ * ISR cache invalidation utilities.
+ * Call these from service layer when content changes.
+ */
+
+import type { ISRCache } from './isr-cache'
+
+let _cache: ISRCache | null = null
+
+export function setISRCache(cache: ISRCache): void {
+  _cache = cache
+}
+
+export function getISRCache(): ISRCache | null {
+  return _cache
+}
+
+export async function purgePage(pathname: string): Promise<void> {
+  if (!_cache) return
+  await _cache.purge(pathname)
+}
+
+export async function purgeContentPages(): Promise<void> {
+  if (!_cache) return
+  await _cache.purge('/content')
+  await _cache.purgePattern('isr:/content/*')
+}
+
+export async function purgeAllPages(): Promise<void> {
+  if (!_cache) return
+  await _cache.purge('/')
+  await _cache.purge('/todos')
+  await _cache.purge('/content')
+  await _cache.purge('/notifications')
+  await _cache.purge('/websocket')
+  await _cache.purgePattern('isr:/content/*')
+}

package/template/src/server/core/module-loader.ts

@@ -169,13 +169,20 @@ export async function validateModules(): Promise<{
     const modulePath = join(MODULES_DIR, actualDir)
 
     if (manifest.routes.client) {
-      const filePath = resolve(modulePath, manifest.routes.client.importPath + '.ts')
-      if (!existsSync(filePath)) {
-        errors.push({
-          module: name,
-          type: 'route-file',
-          message: `client route file not found: ${manifest.routes.client.importPath}.ts`,
-        })
+      const clientRoutes = Array.isArray(manifest.routes.client)
+        ? manifest.routes.client
+        : manifest.routes.client
+        ? [manifest.routes.client]
+        : []
+      for (const route of clientRoutes) {
+        const filePath = resolve(modulePath, route.importPath + '.ts')
+        if (!existsSync(filePath)) {
+          errors.push({
+            module: name,
+            type: 'route-file',
+            message: `client route file not found: ${route.importPath}.ts`,
+          })
+        }
       }
     }
 

package/template/src/server/core/ssr-renderer.ts

@@ -0,0 +1,240 @@
+/**
+ * @framework-baseline cabb57f8f865d571
+ *
+ * SSR renderer for ISR. Generates HTML shells with SEO meta tags.
+ * Phase 1: Shell rendering with meta tags (no React renderToString).
+ * Phase 2 (future): Full renderToString with data-driven content.
+ *
+ * @framework-modify
+ * @reason 修复 RouteConfig.pattern 类型从 string 改为 RegExp，修复 TypeScript 类型错误
+ * @impact 不影响运行时行为，仅修复类型定义
+ */
+
+export interface RouteMeta {
+  title: string
+  description: string
+  ogType?: string
+}
+
+export interface RouteConfig {
+  path: string
+  pattern: RegExp
+  meta: RouteMeta
+  loader?: (params: Record<string, string>) => Promise<Record<string, unknown>>
+}
+
+export interface RenderResult {
+  html: string
+  status: number
+  headers: Record<string, string>
+}
+
+const STATIC_ROUTES: RouteConfig[] = [
+  {
+    path: '/',
+    pattern: /^\/$/,
+    meta: {
+      title: 'Todo List - Biomimic App',
+      description: 'A full-stack application template with React and Hono',
+    },
+  },
+  {
+    path: '/todos',
+    pattern: /^\/todos$/,
+    meta: {
+      title: 'Todo List - Biomimic App',
+      description: 'Manage your todos with real-time updates',
+    },
+  },
+  {
+    path: '/notifications',
+    pattern: /^\/notifications$/,
+    meta: {
+      title: 'Notifications - Biomimic App',
+      description: 'Real-time notifications via Server-Sent Events',
+    },
+  },
+  {
+    path: '/websocket',
+    pattern: /^\/websocket$/,
+    meta: {
+      title: 'WebSocket Demo - Biomimic App',
+      description: 'Type-safe WebSocket communication demo',
+    },
+  },
+  {
+    path: '/content',
+    pattern: /^\/content$/,
+    meta: {
+      title: '内容中心 - Biomimic App',
+      description: 'Content management with categories and search',
+    },
+  },
+  {
+    path: '/content/:id',
+    pattern: /^\/content\/([^/]+)$/,
+    meta: {
+      title: '内容详情 - Biomimic App',
+      description: 'View content details',
+    },
+    loader: async params => {
+      try {
+        // Load content module dynamically (may not exist in all presets)
+        // Use require() to avoid TypeScript checking module existence at compile time
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const contentModule = require('@server/module-content/services/content-service') as {
+          getContentById: (
+            id: string
+          ) => Promise<{ id: number; title: string; content?: string } | null>
+        }
+        const content = await contentModule.getContentById(params.id)
+        if (content) {
+          return {
+            __meta: {
+              title: `${content.title} - Biomimic App`,
+              description: content.content?.substring(0, 160) || 'View content details',
+            },
+            content,
+          }
+        }
+      } catch {
+        // DB not available, return default meta
+      }
+      return {}
+    },
+  },
+]
+
+export function matchRoute(
+  pathname: string
+): { route: RouteConfig; params: Record<string, string> } | null {
+  for (const route of STATIC_ROUTES) {
+    const match = pathname.match(route.pattern)
+    if (match) {
+      const params: Record<string, string> = {}
+      if (route.path === '/content/:id' && match[1]) {
+        params.id = match[1]
+      }
+      return { route, params }
+    }
+  }
+  return null
+}
+
+export async function renderPage(
+  pathname: string,
+  options?: {
+    assetHash?: string
+    data?: Record<string, unknown>
+  }
+): Promise<RenderResult> {
+  const matched = matchRoute(pathname)
+
+  if (!matched) {
+    return renderFallback()
+  }
+
+  const { route, params } = matched
+  let meta = { ...route.meta }
+  let pageData: Record<string, unknown> = {}
+
+  if (route.loader) {
+    try {
+      const loaderResult = await route.loader(params)
+      if (loaderResult.__meta) {
+        meta = { ...meta, ...(loaderResult.__meta as RouteMeta) }
+        delete loaderResult.__meta
+      }
+      pageData = loaderResult
+    } catch {
+      // Loader failed, use default meta
+    }
+  }
+
+  if (options?.data) {
+    pageData = { ...pageData, ...options.data }
+  }
+
+  const html = renderShell({
+    title: meta.title,
+    description: meta.description,
+    ogType: meta.ogType || 'website',
+    data: pageData,
+    pathname,
+  })
+
+  return {
+    html,
+    status: 200,
+    headers: {
+      'Content-Type': 'text/html;charset=UTF-8',
+      'X-ISR-Rendered': 'true',
+    },
+  }
+}
+
+interface ShellOptions {
+  title: string
+  description: string
+  ogType: string
+  data: Record<string, unknown>
+  pathname: string
+}
+
+function renderShell(options: ShellOptions): string {
+  const dataJson = JSON.stringify(options.data)
+  const escapedJson = dataJson.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+  return `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${escapeHtml(options.title)}</title>
+    <meta name="description" content="${escapeHtml(options.description)}" />
+    <meta property="og:title" content="${escapeHtml(options.title)}" />
+    <meta property="og:description" content="${escapeHtml(options.description)}" />
+    <meta property="og:type" content="${escapeHtml(options.ogType)}" />
+    <meta property="og:url" content="${escapeHtml(options.pathname)}" />
+    <meta name="generator" content="ISR" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script>window.__SSR_DATA__ = ${escapedJson};window.__SSR_PATH__ = ${JSON.stringify(options.pathname)};</script>
+    <script type="module" src="/src/client/main.tsx"></script>
+  </body>
+</html>`
+}
+
+function renderFallback(): RenderResult {
+  return {
+    html: `<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Biomimic App</title>
+    <meta name="description" content="Biomimic App - A full-stack application template" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/client/main.tsx"></script>
+  </body>
+</html>`,
+    status: 200,
+    headers: {
+      'Content-Type': 'text/html;charset=UTF-8',
+    },
+  }
+}
+
+function escapeHtml(str: string): string {
+  return str
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}