@raystack/chronicle 0.1.0-canary.1f5227c

package/src/server/dev.ts

@@ -0,0 +1,156 @@
+import { createServer as createViteServer } from 'vite'
+import { createServer } from 'http'
+import fsPromises from 'fs/promises'
+import { createReadStream } from 'fs'
+import path from 'path'
+import chalk from 'chalk'
+import { createViteConfig } from './vite-config'
+
+export interface DevServerOptions {
+  port: number
+  root: string
+  contentDir: string
+}
+
+export async function startDevServer(options: DevServerOptions) {
+  const { port, root, contentDir } = options
+
+  const viteConfig = await createViteConfig({ root, contentDir, isDev: true })
+  const vite = await createViteServer({
+    ...viteConfig,
+    server: { middlewareMode: true },
+    appType: 'custom',
+  })
+
+  const templatePath = path.resolve(root, 'src/server/index.html')
+
+  const server = createServer(async (req, res) => {
+    const url = req.url || '/'
+
+    try {
+      // Let Vite handle its own requests (HMR, modules)
+      if (url.startsWith('/@') || url.startsWith('/__vite') || url.startsWith('/node_modules/')) {
+        vite.middlewares(req, res, () => {
+          res.statusCode = 404
+          res.end()
+        })
+        return
+      }
+
+      // Serve static files from content dir (skip .md/.mdx)
+      const contentFile = path.join(contentDir, decodeURIComponent(url.split('?')[0]))
+      if (!url.endsWith('.md') && !url.endsWith('.mdx')) {
+        try {
+          const stat = await fsPromises.stat(contentFile)
+          if (stat.isFile()) {
+            const ext = path.extname(contentFile).toLowerCase()
+            const mimeTypes: Record<string, string> = {
+              '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+              '.gif': 'image/gif', '.svg': 'image/svg+xml', '.webp': 'image/webp',
+              '.ico': 'image/x-icon', '.pdf': 'application/pdf', '.json': 'application/json',
+              '.yaml': 'text/yaml', '.yml': 'text/yaml', '.txt': 'text/plain',
+            }
+            res.setHeader('Content-Type', mimeTypes[ext] || 'application/octet-stream')
+            createReadStream(contentFile).pipe(res)
+            return
+          }
+        } catch { /* fall through to SSR */ }
+      }
+
+      // Let Vite handle JS/CSS/TS module requests and other static assets
+      if (/\.(js|ts|tsx|css|map)(\?|$)/.test(url)) {
+        vite.middlewares(req, res, () => {
+          res.statusCode = 404
+          res.end()
+        })
+        return
+      }
+
+      // Check API/static routes (load through Vite SSR for import.meta.glob support)
+      const { matchRoute } = await vite.ssrLoadModule(path.resolve(root, 'src/server/router.ts'))
+      const routeHandler = matchRoute(new URL(url, `http://localhost:${port}`).href)
+      if (routeHandler) {
+        const request = new Request(new URL(url, `http://localhost:${port}`))
+        const response = await routeHandler(request)
+        res.statusCode = response.status
+        response.headers.forEach((value: string, key: string) => res.setHeader(key, value))
+        const body = await response.text()
+        res.end(body)
+        return
+      }
+
+      // Resolve page data before SSR render
+      const pathname = new URL(url, `http://localhost:${port}`).pathname
+      const slug = pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean)
+
+      const source = await vite.ssrLoadModule(path.resolve(root, 'src/lib/source.ts'))
+      const { mdxComponents } = await vite.ssrLoadModule(path.resolve(root, 'src/components/mdx/index.tsx'))
+      const { loadConfig } = await vite.ssrLoadModule(path.resolve(root, 'src/lib/config.ts'))
+
+      const config = loadConfig()
+
+      const { loadApiSpecs } = await vite.ssrLoadModule(path.resolve(root, 'src/lib/openapi.ts'))
+      const apiSpecs = config.api?.length ? loadApiSpecs(config.api) : []
+
+      const [tree, sourcePage] = await Promise.all([
+        source.buildPageTree(),
+        source.getPage(slug),
+      ])
+
+      let pageData = null
+      // Don't embed apiSpecs — too large. Client fetches via /api/specs
+      let embeddedData: any = { config, tree, slug, frontmatter: null, filePath: null }
+
+      if (sourcePage) {
+        const component = await source.loadPageComponent(sourcePage)
+        const React = await import('react')
+        const MDXBody = component
+        pageData = {
+          slug,
+          frontmatter: sourcePage.frontmatter,
+          content: MDXBody ? React.createElement(MDXBody, { components: mdxComponents }) : null,
+        }
+        embeddedData.frontmatter = sourcePage.frontmatter
+        embeddedData.filePath = sourcePage.filePath
+      }
+
+      // SSR render
+      let template = await fsPromises.readFile(templatePath, 'utf-8')
+      template = await vite.transformIndexHtml(url, template)
+
+      // Embed page data for client hydration
+      const dataScript = `<script>window.__PAGE_DATA__ = ${JSON.stringify(embeddedData)}</script>`
+      template = template.replace('<!--head-outlet-->', `<!--head-outlet-->${dataScript}`)
+
+      const { render } = await vite.ssrLoadModule(path.resolve(root, 'src/server/entry-server.tsx'))
+
+      const html = render(url, { config, tree, page: pageData, apiSpecs })
+      const finalHtml = template.replace('<!--ssr-outlet-->', html)
+
+      res.setHeader('Content-Type', 'text/html')
+      res.statusCode = 200
+      res.end(finalHtml)
+    } catch (e) {
+      vite.ssrFixStacktrace(e as Error)
+      console.error(e)
+      res.statusCode = 500
+      res.end((e as Error).message)
+    }
+  })
+
+  server.listen(port, () => {
+    console.log(chalk.cyan(`\n  Chronicle dev server running at:`))
+    console.log(chalk.green(`  http://localhost:${port}\n`))
+  })
+
+  // Graceful shutdown
+  const shutdown = () => {
+    vite.close()
+    server.close()
+    process.exit(0)
+  }
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
+
+  return { server, vite }
+}

package/src/server/entry-client.tsx

@@ -0,0 +1,74 @@
+import { hydrateRoot } from 'react-dom/client'
+import { BrowserRouter } from 'react-router-dom'
+import { PageProvider } from '@/lib/page-context'
+import { App } from './App'
+import { getPage, loadPageComponent, buildPageTree } from '@/lib/source'
+import { mdxComponents } from '@/components/mdx'
+import type { ChronicleConfig, PageTree } from '@/types'
+import type { ApiSpec } from '@/lib/openapi'
+import type { ReactNode } from 'react'
+import React from 'react'
+
+interface EmbeddedData {
+  config: ChronicleConfig
+  tree: PageTree
+  slug: string[]
+  frontmatter: { title: string; description?: string; order?: number }
+  filePath: string
+}
+
+async function hydrate() {
+  try {
+    const embedded: EmbeddedData | undefined = (window as any).__PAGE_DATA__
+
+    let config: ChronicleConfig = { title: 'Documentation' }
+    let tree: PageTree = { name: 'root', children: [] }
+    let page: { slug: string[]; frontmatter: any; content: ReactNode } | null = null
+    let apiSpecs: ApiSpec[] = []
+
+    if (embedded) {
+      config = embedded.config
+      tree = embedded.tree
+
+      // Fetch API specs if on /apis route
+      const isApiRoute = window.location.pathname.startsWith('/apis')
+      if (isApiRoute && config.api?.length) {
+        try {
+          const res = await fetch('/api/specs')
+          apiSpecs = await res.json()
+        } catch { /* will load on demand */ }
+      }
+
+      const sourcePage = await getPage(embedded.slug)
+      if (sourcePage) {
+        const component = await loadPageComponent(sourcePage)
+        page = {
+          slug: embedded.slug,
+          frontmatter: embedded.frontmatter,
+          content: component ? React.createElement(component, { components: mdxComponents }) : null,
+        }
+      } else {
+        page = {
+          slug: embedded.slug,
+          frontmatter: embedded.frontmatter,
+          content: null,
+        }
+      }
+    } else {
+      tree = await buildPageTree()
+    }
+
+    hydrateRoot(
+      document.getElementById('root') as HTMLElement,
+      <BrowserRouter>
+        <PageProvider initialConfig={config} initialTree={tree} initialPage={page} initialApiSpecs={apiSpecs}>
+          <App />
+        </PageProvider>
+      </BrowserRouter>,
+    )
+  } catch (err) {
+    console.error('Hydration failed:', err)
+  }
+}
+
+hydrate()

package/src/server/entry-prod.ts

@@ -0,0 +1,127 @@
+// Production server entry — built by Vite, loaded by prod.ts at runtime
+import { createServer } from 'http'
+import { readFileSync, createReadStream } from 'fs'
+import fsPromises from 'fs/promises'
+import path from 'path'
+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 { render, matchRoute, loadConfig, loadApiSpecs, getPage, loadPageComponent, buildPageTree }
+
+export async function startServer(options: { port: number; distDir: string }) {
+  const { port, distDir } = options
+
+  const clientDir = path.resolve(distDir, 'client')
+  const templatePath = path.resolve(clientDir, 'src/server/index.html')
+  const template = readFileSync(templatePath, 'utf-8')
+
+  const sirv = (await import('sirv')).default
+  const assets = sirv(clientDir, { gzip: true })
+
+  const server = createServer(async (req, res) => {
+    const url = req.url || '/'
+
+    try {
+      // API routes
+      const routeHandler = matchRoute(new URL(url, `http://localhost:${port}`).href)
+      if (routeHandler) {
+        const request = new Request(new URL(url, `http://localhost:${port}`))
+        const response = await routeHandler(request)
+        res.statusCode = response.status
+        response.headers.forEach((value: string, key: string) => res.setHeader(key, value))
+        const body = await response.text()
+        res.end(body)
+        return
+      }
+
+      // Serve static files from content dir (skip .md/.mdx)
+      const contentDir = process.env.CHRONICLE_CONTENT_DIR || process.cwd()
+      const contentFile = path.join(contentDir, decodeURIComponent(url.split('?')[0]))
+      if (!url.endsWith('.md') && !url.endsWith('.mdx')) {
+        try {
+          const stat = await fsPromises.stat(contentFile)
+          if (stat.isFile()) {
+            const ext = path.extname(contentFile).toLowerCase()
+            const mimeTypes: Record<string, string> = {
+              '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+              '.gif': 'image/gif', '.svg': 'image/svg+xml', '.webp': 'image/webp',
+              '.ico': 'image/x-icon', '.pdf': 'application/pdf', '.json': 'application/json',
+              '.yaml': 'text/yaml', '.yml': 'text/yaml', '.txt': 'text/plain',
+            }
+            res.setHeader('Content-Type', mimeTypes[ext] || 'application/octet-stream')
+            createReadStream(contentFile).pipe(res)
+            return
+          }
+        } catch { /* fall through */ }
+      }
+
+      // Static assets from dist/client
+      const assetHandled = await new Promise<boolean>((resolve) => {
+        assets(req, res, () => resolve(false))
+        res.on('close', () => resolve(true))
+      })
+      if (assetHandled) return
+
+      // Resolve page data
+      const pathname = new URL(url, `http://localhost:${port}`).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
+      }
+
+      // SSR render
+      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)
+
+      res.setHeader('Content-Type', 'text/html')
+      res.statusCode = 200
+      res.end(finalHtml)
+    } catch (e) {
+      console.error(e)
+      res.statusCode = 500
+      res.end((e as Error).message)
+    }
+  })
+
+  server.listen(port, () => {
+    console.log(`\n  Chronicle production server running at:`)
+    console.log(`  http://localhost:${port}\n`)
+  })
+
+  const shutdown = () => {
+    server.close()
+    process.exit(0)
+  }
+  process.on('SIGINT', shutdown)
+  process.on('SIGTERM', shutdown)
+
+  return server
+}

package/src/server/entry-server.tsx

@@ -0,0 +1,35 @@
+import { renderToString } from 'react-dom/server'
+import { StaticRouter } from 'react-router-dom'
+import { PageProvider } from '@/lib/page-context'
+import { App } from './App'
+import type { ReactNode } from 'react'
+import type { ChronicleConfig, Frontmatter, PageTree } from '@/types'
+import type { ApiSpec } from '@/lib/openapi'
+
+export interface SSRData {
+  config: ChronicleConfig
+  tree: PageTree
+  page: {
+    slug: string[]
+    frontmatter: Frontmatter
+    content: ReactNode
+  } | null
+  apiSpecs: ApiSpec[]
+}
+
+export function render(url: string, data: SSRData): string {
+  const pathname = new URL(url, 'http://localhost').pathname
+
+  return renderToString(
+    <StaticRouter location={pathname}>
+      <PageProvider
+        initialConfig={data.config}
+        initialTree={data.tree}
+        initialPage={data.page}
+        initialApiSpecs={data.apiSpecs}
+      >
+        <App />
+      </PageProvider>
+    </StaticRouter>,
+  )
+}

package/src/server/handlers/apis-proxy.ts

@@ -0,0 +1,52 @@
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs } from '@/lib/openapi'
+
+export async function handleApisProxy(req: Request): Promise<Response> {
+  if (req.method !== 'POST') {
+    return Response.json({ error: 'Method not allowed' }, { status: 405 })
+  }
+
+  const { specName, method, path, headers, body } = await req.json()
+
+  if (!specName || !method || !path) {
+    return Response.json({ error: 'Missing specName, method, or path' }, { status: 400 })
+  }
+
+  const config = loadConfig()
+  const specs = loadApiSpecs(config.api ?? [])
+  const spec = specs.find((s) => s.name === specName)
+
+  if (!spec) {
+    return Response.json({ error: `Unknown spec: ${specName}` }, { status: 404 })
+  }
+
+  const url = spec.server.url + path
+
+  try {
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    })
+
+    const contentType = response.headers.get('content-type') ?? ''
+    const responseBody = contentType.includes('application/json')
+      ? await response.json()
+      : await response.text()
+
+    return Response.json({
+      status: response.status,
+      statusText: response.statusText,
+      body: responseBody,
+    }, { status: response.status })
+  } catch (error) {
+    const message = error instanceof Error
+      ? `${error.message}${error.cause ? `: ${(error.cause as Error).message}` : ''}`
+      : 'Request failed'
+    return Response.json({
+      status: 502,
+      statusText: 'Bad Gateway',
+      body: `Could not reach ${url}\n${message}`,
+    }, { status: 502 })
+  }
+}

package/src/server/handlers/health.ts

@@ -0,0 +1,3 @@
+export function handleHealth(): Response {
+  return Response.json({ status: 'ok' })
+}

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' },
+  })
+}