@raystack/chronicle 0.1.0-canary.e11f924 → 0.1.0-canary.f0d9bde

package/src/server/handlers/og.ts

@@ -0,0 +1,87 @@
+import satori from 'satori'
+import { loadConfig } from '@/lib/config'
+
+let fontData: ArrayBuffer | null = null
+
+async function loadFont(): Promise<ArrayBuffer> {
+  if (fontData) return fontData
+
+  try {
+    const response = await fetch('https://fonts.gstatic.com/s/inter/v18/UcCO3FwrK3iLTeHuS_nVMrMxCp50SjIw2boKoduKmMEVuLyfAZ9hiA.woff2')
+    fontData = await response.arrayBuffer()
+  } catch {
+    // Fallback: create minimal valid font buffer
+    fontData = new ArrayBuffer(0)
+  }
+
+  return fontData
+}
+
+export async function handleOg(req: Request): Promise<Response> {
+  const url = new URL(req.url)
+  const title = url.searchParams.get('title') ?? loadConfig().title
+  const description = url.searchParams.get('description') ?? ''
+  const siteName = loadConfig().title
+
+  const font = await loadFont()
+
+  const svg = await satori(
+    {
+      type: 'div',
+      props: {
+        style: {
+          height: '100%',
+          width: '100%',
+          display: 'flex',
+          flexDirection: 'column',
+          justifyContent: 'center',
+          padding: '60px 80px',
+          backgroundColor: '#0a0a0a',
+          color: '#fafafa',
+        },
+        children: [
+          {
+            type: 'div',
+            props: {
+              style: { fontSize: 24, color: '#888', marginBottom: 16 },
+              children: siteName,
+            },
+          },
+          {
+            type: 'div',
+            props: {
+              style: { fontSize: 56, fontWeight: 700, lineHeight: 1.2, marginBottom: 24 },
+              children: title,
+            },
+          },
+          ...(description ? [{
+            type: 'div',
+            props: {
+              style: { fontSize: 24, color: '#999', lineHeight: 1.4 },
+              children: description,
+            },
+          }] : []),
+        ],
+      },
+    },
+    {
+      width: 1200,
+      height: 630,
+      fonts: [
+        {
+          name: 'Inter',
+          data: font,
+          weight: 400,
+          style: 'normal' as const,
+        },
+      ],
+    },
+  )
+
+  return new Response(svg, {
+    headers: {
+      'Content-Type': 'image/svg+xml',
+      'Cache-Control': 'public, max-age=86400',
+    },
+  })
+}

package/src/server/handlers/robots.ts

@@ -0,0 +1,11 @@
+import { loadConfig } from '@/lib/config'
+
+export function handleRobots(): Response {
+  const config = loadConfig()
+  const sitemap = config.url ? `\nSitemap: ${config.url}/sitemap.xml` : ''
+  const body = `User-agent: *\nAllow: /${sitemap}`
+
+  return new Response(body, {
+    headers: { 'Content-Type': 'text/plain' },
+  })
+}

package/src/server/handlers/search.ts

@@ -0,0 +1,172 @@
+import fs from 'fs/promises'
+import path from 'path'
+import matter from 'gray-matter'
+import MiniSearch from 'minisearch'
+import type { OpenAPIV3 } from 'openapi-types'
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs, type ApiSpec } from '@/lib/openapi'
+import { getSpecSlug } from '@/lib/api-routes'
+
+interface SearchDocument {
+  id: string
+  url: string
+  title: string
+  content: string
+  type: 'page' | 'api'
+}
+
+let searchIndex: MiniSearch<SearchDocument> | null = null
+let cachedDocs: SearchDocument[] | null = null
+
+function createIndex(docs: SearchDocument[]): MiniSearch<SearchDocument> {
+  const index = new MiniSearch<SearchDocument>({
+    fields: ['title', 'content'],
+    storeFields: ['url', 'title', 'type'],
+    searchOptions: {
+      boost: { title: 2 },
+      fuzzy: 0.2,
+      prefix: true,
+    },
+  })
+  index.addAll(docs)
+  return index
+}
+
+// Try loading pre-built search index (generated at build time)
+async function loadPrebuiltIndex(): Promise<SearchDocument[] | null> {
+  try {
+    // In bundled server, search-index.json is next to the entry file
+    const indexPath = path.resolve(__dirname, 'search-index.json')
+    const raw = await fs.readFile(indexPath, 'utf-8')
+    return JSON.parse(raw)
+  } catch {
+    return null
+  }
+}
+
+// Fallback: scan filesystem at runtime (dev mode)
+function getContentDir(): string {
+  return process.env.CHRONICLE_CONTENT_DIR || path.join(process.cwd(), 'content')
+}
+
+async function scanContent(): Promise<SearchDocument[]> {
+  const contentDir = getContentDir()
+  const docs: SearchDocument[] = []
+
+  async function scan(dir: string, prefix: string[] = []) {
+    let entries
+    try { entries = await fs.readdir(dir, { withFileTypes: true }) }
+    catch { return }
+
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue
+      const fullPath = path.join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        await scan(fullPath, [...prefix, entry.name])
+        continue
+      }
+
+      if (!entry.name.endsWith('.mdx') && !entry.name.endsWith('.md')) continue
+
+      const raw = await fs.readFile(fullPath, 'utf-8')
+      const { data: fm, content } = matter(raw)
+      const baseName = entry.name.replace(/\.(mdx|md)$/, '')
+      const slugs = baseName === 'index' ? prefix : [...prefix, baseName]
+      const url = slugs.length === 0 ? '/' : '/' + slugs.join('/')
+
+      docs.push({
+        id: url,
+        url,
+        title: fm.title ?? baseName,
+        content: content.slice(0, 5000),
+        type: 'page',
+      })
+    }
+  }
+
+  await scan(contentDir)
+  return docs
+}
+
+function buildApiDocs(): SearchDocument[] {
+  const config = loadConfig()
+  if (!config.api?.length) return []
+
+  const docs: SearchDocument[] = []
+  const specs = loadApiSpecs(config.api)
+
+  for (const spec of specs) {
+    const specSlug = getSpecSlug(spec)
+    const paths = spec.document.paths ?? {}
+    for (const [pathStr, pathItem] of Object.entries(paths)) {
+      if (!pathItem) continue
+      for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+        const op = pathItem[method] as OpenAPIV3.OperationObject | undefined
+        if (!op?.operationId) continue
+        const url = `/apis/${specSlug}/${encodeURIComponent(op.operationId)}`
+        docs.push({
+          id: url,
+          url,
+          title: `${method.toUpperCase()} ${op.summary ?? op.operationId}`,
+          content: op.description ?? '',
+          type: 'api',
+        })
+      }
+    }
+  }
+
+  return docs
+}
+
+async function loadDocuments(): Promise<SearchDocument[]> {
+  // Try pre-built index first
+  const prebuilt = await loadPrebuiltIndex()
+  if (prebuilt) return prebuilt
+
+  // Fallback to filesystem scanning (dev mode)
+  const [contentDocs, apiDocs] = await Promise.all([
+    scanContent(),
+    Promise.resolve(buildApiDocs()),
+  ])
+  return [...contentDocs, ...apiDocs]
+}
+
+async function getDocs(): Promise<SearchDocument[]> {
+  if (cachedDocs) return cachedDocs
+  cachedDocs = await loadDocuments()
+  return cachedDocs
+}
+
+async function getIndex(): Promise<MiniSearch<SearchDocument>> {
+  if (searchIndex) return searchIndex
+  const docs = await getDocs()
+  searchIndex = createIndex(docs)
+  return searchIndex
+}
+
+export async function handleSearch(req: Request): Promise<Response> {
+  const url = new URL(req.url)
+  const query = url.searchParams.get('query') ?? ''
+  const index = await getIndex()
+
+  if (!query) {
+    const docs = await getDocs()
+    const suggestions = docs.filter(d => d.type === 'page').slice(0, 8).map((d) => ({
+      id: d.id,
+      url: d.url,
+      type: d.type,
+      content: d.title,
+    }))
+    return Response.json(suggestions)
+  }
+
+  const results = index.search(query).map((r) => ({
+    id: r.id,
+    url: r.url,
+    type: r.type,
+    content: r.title,
+  }))
+
+  return Response.json(results)
+}

package/src/server/handlers/sitemap.ts

@@ -0,0 +1,39 @@
+import { loadConfig } from '@/lib/config'
+import { getPages } from '@/lib/source'
+import { loadApiSpecs } from '@/lib/openapi'
+import { buildApiRoutes } from '@/lib/api-routes'
+
+export async function handleSitemap(): Promise<Response> {
+  const config = loadConfig()
+  if (!config.url) {
+    return new Response('<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"/>', {
+      headers: { 'Content-Type': 'application/xml' },
+    })
+  }
+
+  const baseUrl = config.url.replace(/\/$/, '')
+
+  const pages = await getPages()
+  const docPages = pages.map((page) => {
+    const lastmod = page.frontmatter.lastModified
+      ? `<lastmod>${new Date(page.frontmatter.lastModified).toISOString()}</lastmod>`
+      : ''
+    return `<url><loc>${baseUrl}/${page.slugs.join('/')}</loc>${lastmod}</url>`
+  })
+
+  const apiPages = config.api?.length
+    ? buildApiRoutes(loadApiSpecs(config.api)).map((route) =>
+        `<url><loc>${baseUrl}/apis/${route.slug.join('/')}</loc></url>`
+      )
+    : []
+
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<url><loc>${baseUrl}</loc></url>
+${[...docPages, ...apiPages].join('\n')}
+</urlset>`
+
+  return new Response(xml, {
+    headers: { 'Content-Type': 'application/xml' },
+  })
+}

package/src/server/handlers/specs.ts

@@ -0,0 +1,9 @@
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs } from '@/lib/openapi'
+
+export function handleSpecs(): Response {
+  const config = loadConfig()
+  const specs = config.api?.length ? loadApiSpecs(config.api) : []
+
+  return Response.json(specs)
+}

package/src/server/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <!--head-outlet-->
+  </head>
+  <body>
+    <div id="root"><!--ssr-outlet--></div>
+    <script type="module" src="/src/server/entry-client.tsx"></script>
+  </body>
+</html>

package/src/server/prod.ts

@@ -0,0 +1,18 @@
+import path from 'path'
+import chalk from 'chalk'
+
+export interface ProdServerOptions {
+  port: number
+  root: string
+  distDir: string
+}
+
+export async function startProdServer(options: ProdServerOptions) {
+  const { port, distDir } = options
+
+  const serverEntry = path.resolve(distDir, 'server/entry-prod.js')
+  const { startServer } = await import(serverEntry)
+
+  console.log(chalk.cyan('Starting production server...'))
+  return startServer({ port, distDir })
+}

package/src/server/request-handler.ts

@@ -0,0 +1,64 @@
+// Shared request handler for API routes + SSR rendering
+// Used by entry-prod.ts (Node) and entry-vercel.ts (Vercel)
+import React from 'react'
+import { render } from './entry-server'
+import { matchRoute } from './router'
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs } from '@/lib/openapi'
+import { getPage, loadPageComponent, buildPageTree } from '@/lib/source'
+import { mdxComponents } from '@/components/mdx'
+
+export interface RequestHandlerOptions {
+  template: string
+  baseUrl: string
+}
+
+export async function handleRequest(url: string, options: RequestHandlerOptions): Promise<Response> {
+  const { template, baseUrl } = options
+  const fullUrl = new URL(url, baseUrl).href
+
+  // API routes
+  const routeHandler = matchRoute(fullUrl)
+  if (routeHandler) {
+    return routeHandler(new Request(fullUrl))
+  }
+
+  // SSR render
+  const pathname = new URL(url, baseUrl).pathname
+  const slug = pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean)
+
+  const config = loadConfig()
+  const apiSpecs = config.api?.length ? loadApiSpecs(config.api) : []
+
+  const [tree, sourcePage] = await Promise.all([
+    buildPageTree(),
+    getPage(slug),
+  ])
+
+  let pageData = null
+  let embeddedData: any = { config, tree, slug, frontmatter: null, filePath: null }
+
+  if (sourcePage) {
+    const component = await loadPageComponent(sourcePage)
+    pageData = {
+      slug,
+      frontmatter: sourcePage.frontmatter,
+      content: component ? React.createElement(component, { components: mdxComponents }) : null,
+    }
+    embeddedData.frontmatter = sourcePage.frontmatter
+    embeddedData.filePath = sourcePage.filePath
+  }
+
+  const html = render(url, { config, tree, page: pageData, apiSpecs })
+
+  const safeJson = JSON.stringify(embeddedData).replace(/</g, '\\u003c')
+  const dataScript = `<script>window.__PAGE_DATA__ = ${safeJson}</script>`
+  const finalHtml = template
+    .replace('<!--head-outlet-->', `<!--head-outlet-->${dataScript}`)
+    .replace('<!--ssr-outlet-->', html)
+
+  return new Response(finalHtml, {
+    status: 200,
+    headers: { 'Content-Type': 'text/html' },
+  })
+}

package/src/server/router.ts

@@ -0,0 +1,42 @@
+import { handleHealth } from './handlers/health'
+import { handleSearch } from './handlers/search'
+import { handleApisProxy } from './handlers/apis-proxy'
+import { handleOg } from './handlers/og'
+import { handleLlms } from './handlers/llms'
+import { handleSitemap } from './handlers/sitemap'
+import { handleRobots } from './handlers/robots'
+import { handleSpecs } from './handlers/specs'
+
+export type RouteHandler = (req: Request) => Response | Promise<Response>
+
+interface Route {
+  pattern: URLPattern
+  handler: RouteHandler
+}
+
+const routes: Route[] = []
+
+function addRoute(path: string, handler: RouteHandler) {
+  routes.push({
+    pattern: new URLPattern({ pathname: path }),
+    handler,
+  })
+}
+
+addRoute('/api/health', handleHealth)
+addRoute('/api/search', handleSearch)
+addRoute('/api/apis-proxy', handleApisProxy)
+addRoute('/api/specs', handleSpecs)
+addRoute('/og', handleOg)
+addRoute('/llms.txt', handleLlms)
+addRoute('/sitemap.xml', handleSitemap)
+addRoute('/robots.txt', handleRobots)
+
+export function matchRoute(url: string): RouteHandler | null {
+  for (const route of routes) {
+    if (route.pattern.test(url)) {
+      return route.handler
+    }
+  }
+  return null
+}

package/src/server/utils/safe-path.ts

@@ -0,0 +1,14 @@
+import path from 'path'
+
+/**
+ * Resolve a URL path within a base directory, preventing path traversal.
+ * Returns null if the resolved path escapes the base directory.
+ */
+export function safePath(baseDir: string, urlPath: string): string | null {
+  const decoded = decodeURIComponent(urlPath.split('?')[0])
+  const resolved = path.resolve(baseDir, '.' + decoded)
+  if (!resolved.startsWith(path.resolve(baseDir) + path.sep) && resolved !== path.resolve(baseDir)) {
+    return null
+  }
+  return resolved
+}

package/src/server/vite-config.ts

@@ -0,0 +1,71 @@
+import path from 'path'
+import { type InlineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import mdx from '@mdx-js/rollup'
+import remarkDirective from 'remark-directive'
+import remarkGfm from 'remark-gfm'
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkMdxFrontmatter from 'remark-mdx-frontmatter'
+import rehypeShiki from '@shikijs/rehype'
+
+export interface ViteConfigOptions {
+  root: string
+  contentDir: string
+  isDev?: boolean
+}
+
+export async function createViteConfig(options: ViteConfigOptions): Promise<InlineConfig> {
+  const { root, contentDir, isDev = false } = options
+
+  return {
+    root,
+    configFile: false,
+    resolve: {
+      alias: {
+        '@': path.resolve(root, 'src'),
+        '@content': contentDir,
+      },
+      dedupe: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime'],
+    },
+    server: {
+      fs: {
+        allow: [root, contentDir],
+      },
+    },
+    plugins: [
+      mdx({
+        remarkPlugins: [
+          remarkFrontmatter,
+          remarkMdxFrontmatter,
+          remarkGfm,
+          remarkDirective,
+        ],
+        rehypePlugins: [
+          [rehypeShiki, { themes: { light: 'github-light', dark: 'github-dark' }, defaultColor: false }],
+        ],
+        mdExtensions: ['.md'],
+        mdxExtensions: ['.mdx'],
+      }),
+      react(),
+    ],
+    define: {
+      'process.env.CHRONICLE_CONTENT_DIR': JSON.stringify(contentDir),
+      'process.env.CHRONICLE_PROJECT_ROOT': JSON.stringify(root),
+    },
+    css: {
+      modules: {
+        localsConvention: 'camelCase',
+      },
+    },
+    ssr: {
+      noExternal: ['@raystack/apsara'],
+    },
+    build: {
+      rolldownOptions: {
+        input: isDev ? undefined : {
+          client: path.resolve(root, 'src/server/index.html'),
+        },
+      },
+    },
+  }
+}

package/src/themes/default/Layout.tsx

@@ -1,10 +1,9 @@
 "use client";
 
 import { useMemo, useEffect, useRef } from "react";
-import { usePathname } from "next/navigation";
-import NextLink from "next/link";
+import { useLocation, Link } from "react-router-dom";
 import { cx } from "class-variance-authority";
-import { Flex, Navbar, Headline, Link, Sidebar, Button } from "@raystack/apsara";
+import { Flex, Navbar, Headline, Sidebar, Button } from "@raystack/apsara";
 import { RectangleStackIcon } from "@heroicons/react/24/outline";
 import { ClientThemeSwitcher } from "@/components/ui/client-theme-switcher";
 import { Search } from "@/components/ui/search";
@@ -25,7 +24,7 @@ const iconMap: Record<string, React.ReactNode> = {
 let savedScrollTop = 0;
 
 export function Layout({ children, config, tree, classNames }: ThemeLayoutProps) {
-  const pathname = usePathname();
+  const { pathname } = useLocation();
   const scrollRef = useRef<HTMLDivElement>(null);
 
   useEffect(() => {
@@ -45,21 +44,21 @@ export function Layout({ children, config, tree, classNames }: ThemeLayoutProps)
     <Flex direction="column" className={cx(styles.layout, classNames?.layout)}>
       <Navbar className={styles.header}>
         <Navbar.Start>
-          <NextLink href="/" style={{ textDecoration: 'none', color: 'inherit' }}>
+          <Link to="/" style={{ textDecoration: 'none', color: 'inherit' }}>
             <Headline size="small" weight="medium" as="h1">
               {config.title}
             </Headline>
-          </NextLink>
+          </Link>
         </Navbar.Start>
         <Navbar.End>
           <Flex gap="medium" align="center" className={styles.navActions}>
             {config.api?.map((api) => (
-              <NextLink key={api.basePath} href={api.basePath} className={styles.navButton}>
+              <Link key={api.name} to={api.basePath} className={styles.navButton}>
                 {api.name} API
-              </NextLink>
+              </Link>
             ))}
             {config.navigation?.links?.map((link) => (
-              <Link key={link.href} href={link.href}>
+              <Link key={link.href} to={link.href}>
                 {link.label}
               </Link>
             ))}
@@ -118,7 +117,7 @@ function SidebarNode({
 
   const isActive = pathname === item.url;
   const href = item.url ?? "#";
-  const link = useMemo(() => <NextLink href={href} scroll={false} />, [href]);
+  const link = useMemo(() => <Link to={href} />, [href]);
 
   return (
     <Sidebar.Item

package/src/themes/default/Page.module.css

@@ -38,9 +38,69 @@
   margin-bottom: var(--rs-space-3);
 }
 
+.content :global(pre) {
+  background-color: var(--shiki-light-bg, #fff);
+}
+
+.content :global(pre code span) {
+  color: var(--shiki-light);
+}
+
+:global([data-theme="dark"]) .content :global(pre) {
+  background-color: var(--shiki-dark-bg, #24292e);
+}
+
+:global([data-theme="dark"]) .content :global(pre code span) {
+  color: var(--shiki-dark);
+}
+
+.content img {
+  max-width: 100%;
+  height: auto;
+}
+
 .content table {
   display: block;
   max-width: 100%;
   overflow-x: auto;
   margin-bottom: var(--rs-space-5);
 }
+
+.content details {
+  border: 1px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-2);
+  margin: var(--rs-space-5) 0;
+  overflow: hidden;
+}
+
+.content details summary {
+  padding: var(--rs-space-4) var(--rs-space-5);
+  cursor: pointer;
+  font-weight: 500;
+  font-size: var(--rs-font-size-small);
+  color: var(--rs-color-text-base-primary);
+  background: var(--rs-color-background-base-secondary);
+  list-style: none;
+  display: flex;
+  align-items: center;
+  gap: var(--rs-space-3);
+}
+
+.content details summary::-webkit-details-marker {
+  display: none;
+}
+
+.content details summary::before {
+  content: '▶';
+  font-size: 10px;
+  transition: transform 0.2s ease;
+  color: var(--rs-color-text-base-secondary);
+}
+
+.content details[open] > summary::before {
+  transform: rotate(90deg);
+}
+
+.content details > :not(summary) {
+  padding: var(--rs-space-4) var(--rs-space-5);
+}

package/src/themes/default/font.ts

@@ -1,6 +1,4 @@
-import { Inter } from 'next/font/google'
-
-export const inter = Inter({
-  subsets: ['latin'],
-  display: 'swap',
-})
+export const inter = {
+  className: 'chronicle-inter',
+  style: { fontFamily: "'Inter', system-ui, -apple-system, sans-serif" },
+}