@raystack/chronicle 0.1.0-canary.111b55a

package/src/server/handlers/llms.ts

@@ -0,0 +1,58 @@
+import fs from 'fs/promises'
+import path from 'path'
+import matter from 'gray-matter'
+import { loadConfig } from '@/lib/config'
+
+function getContentDir(): string {
+  return process.env.CHRONICLE_CONTENT_DIR || path.join(process.cwd(), 'content')
+}
+
+async function scanPages(): Promise<{ title: string; url: string }[]> {
+  const contentDir = getContentDir()
+  const pages: { title: string; url: string }[] = []
+
+  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 } = matter(raw)
+      const baseName = entry.name.replace(/\.(mdx|md)$/, '')
+      const slugs = baseName === 'index' ? prefix : [...prefix, baseName]
+      const url = slugs.length === 0 ? '/' : '/' + slugs.join('/')
+
+      pages.push({ title: fm.title ?? baseName, url })
+    }
+  }
+
+  await scan(contentDir)
+  return pages
+}
+
+export async function handleLlms(): Promise<Response> {
+  const config = loadConfig()
+
+  if (!config.llms?.enabled) {
+    return new Response('Not Found', { status: 404 })
+  }
+
+  const pages = await scanPages()
+  const index = pages.map((p) => `- [${p.title}](${p.url})`).join('\n')
+  const body = `# ${config.title}\n\n${config.description ?? ''}\n\n${index}`
+
+  return new Response(body, {
+    headers: { 'Content-Type': 'text/plain' },
+  })
+}

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,63 @@
+// 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 dataScript = `<script>window.__PAGE_DATA__ = ${JSON.stringify(embeddedData)}</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/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.module.css

@@ -0,0 +1,81 @@
+.layout {
+  min-height: 100vh;
+}
+
+.header {
+  border-bottom: 1px solid var(--rs-color-border-base-primary);
+}
+
+.search {
+  margin-left: var(--rs-space-5);
+}
+
+.body {
+  flex: 1;
+}
+
+.sidebar {
+  width: 260px;
+  position: sticky;
+  top: 0;
+  height: 100vh;
+}
+
+.content {
+  flex: 1;
+  padding: var(--rs-space-9);
+}
+
+.sidebarList {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.separator {
+  height: 1px;
+  background: var(--rs-color-border-base-primary);
+  margin: var(--rs-space-3) 0;
+}
+
+.folder {
+  margin-bottom: var(--rs-space-3);
+}
+
+.folderLabel {
+  font-weight: 500;
+  font-size: 0.875rem;
+  color: var(--rs-color-text-base-secondary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.folder > .sidebarList {
+  margin-top: var(--rs-space-2);
+  padding-left: var(--rs-space-4);
+}
+
+.navButton {
+  display: flex;
+  align-items: center;
+  height: 32px;
+  padding: 0 var(--rs-space-4);
+  border: 1px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-2);
+  font-size: var(--rs-font-size-small);
+  font-weight: var(--rs-font-weight-medium);
+  color: var(--rs-color-foreground-base-primary);
+  text-decoration: none;
+}
+
+.navButton:hover {
+  background: var(--rs-color-background-base-primary-hover);
+}
+
+.groupItems {
+  padding-left: var(--rs-space-4);
+}
+
+.page {
+  padding: var(--rs-space-2) 0;
+}