@raystack/chronicle 0.1.0-canary.111b55a

package/src/server/adapters/vercel.ts

@@ -0,0 +1,133 @@
+import path from 'path'
+import fs from 'fs/promises'
+import { existsSync } from 'fs'
+import chalk from 'chalk'
+
+interface VercelAdapterOptions {
+  distDir: string
+  contentDir: string
+  projectRoot: string
+}
+
+const CONTENT_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.svg', '.webp', '.ico',
+  '.pdf', '.json', '.yaml', '.yml', '.txt',
+])
+
+export async function buildVercelOutput(options: VercelAdapterOptions) {
+  const { distDir, contentDir, projectRoot } = options
+  const outputDir = path.resolve(projectRoot, '.vercel/output')
+
+  console.log(chalk.gray('Generating Vercel output...'))
+
+  // Clean previous output
+  await fs.rm(outputDir, { recursive: true, force: true })
+
+  // Create output directories
+  const staticDir = path.resolve(outputDir, 'static')
+  const funcDir = path.resolve(outputDir, 'functions/index.func')
+  await fs.mkdir(staticDir, { recursive: true })
+  await fs.mkdir(funcDir, { recursive: true })
+
+  // 1. Copy client assets → .vercel/output/static/
+  const clientDir = path.resolve(distDir, 'client')
+  await copyDir(clientDir, staticDir)
+  console.log(chalk.gray('  Copied client assets to static/'))
+
+  // 2. Copy content dir assets (images, etc.) → .vercel/output/static/
+  if (existsSync(contentDir)) {
+    await copyContentAssets(contentDir, staticDir)
+    console.log(chalk.gray('  Copied content assets to static/'))
+  }
+
+  // 3. Copy server bundle → .vercel/output/functions/index.func/
+  const serverDir = path.resolve(distDir, 'server')
+  await copyDir(serverDir, funcDir)
+  console.log(chalk.gray('  Copied server bundle to functions/'))
+
+  // 4. Copy HTML template into function dir (not accessible from static/ at runtime)
+  const templateSrc = path.resolve(clientDir, 'src/server/index.html')
+  await fs.copyFile(templateSrc, path.resolve(funcDir, 'index.html'))
+
+  // 5. Write package.json for ESM support
+  await fs.writeFile(
+    path.resolve(funcDir, 'package.json'),
+    JSON.stringify({ type: 'module' }, null, 2),
+  )
+
+  // 6. Write .vc-config.json
+  await fs.writeFile(
+    path.resolve(funcDir, '.vc-config.json'),
+    JSON.stringify({
+      runtime: 'nodejs24.x',
+      handler: 'entry-vercel.js',
+      launcherType: 'Nodejs',
+    }, null, 2),
+  )
+
+  // 7. Write config.json
+  await fs.writeFile(
+    path.resolve(outputDir, 'config.json'),
+    JSON.stringify({
+      version: 3,
+      routes: [
+        { handle: 'filesystem' },
+        { src: '/(.*)', dest: '/index' },
+      ],
+    }, null, 2),
+  )
+
+  console.log(chalk.green('Vercel output generated →'), outputDir)
+}
+
+async function copyDir(src: string, dest: string) {
+  await fs.mkdir(dest, { recursive: true })
+  const entries = await fs.readdir(src, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath)
+    } else {
+      await fs.copyFile(srcPath, destPath)
+    }
+  }
+}
+
+async function copyContentAssets(contentDir: string, staticDir: string) {
+  const entries = await fs.readdir(contentDir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const srcPath = path.join(contentDir, entry.name)
+
+    if (entry.isDirectory()) {
+      const destSubDir = path.join(staticDir, entry.name)
+      await copyContentAssetsRecursive(srcPath, destSubDir)
+    } else {
+      const ext = path.extname(entry.name).toLowerCase()
+      if (CONTENT_EXTENSIONS.has(ext)) {
+        await fs.copyFile(srcPath, path.join(staticDir, entry.name))
+      }
+    }
+  }
+}
+
+async function copyContentAssetsRecursive(srcDir: string, destDir: string) {
+  const entries = await fs.readdir(srcDir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name)
+
+    if (entry.isDirectory()) {
+      await copyContentAssetsRecursive(srcPath, path.join(destDir, entry.name))
+    } else {
+      const ext = path.extname(entry.name).toLowerCase()
+      if (CONTENT_EXTENSIONS.has(ext)) {
+        await fs.mkdir(destDir, { recursive: true })
+        await fs.copyFile(srcPath, path.join(destDir, entry.name))
+      }
+    }
+  }
+}

package/src/server/build-search-index.ts

@@ -0,0 +1,107 @@
+import fs from 'fs/promises'
+import path from 'path'
+import matter from 'gray-matter'
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs } from '@/lib/openapi'
+import { getSpecSlug } from '@/lib/api-routes'
+import type { OpenAPIV3 } from 'openapi-types'
+
+interface SearchDocument {
+  id: string
+  url: string
+  title: string
+  content: string
+  type: 'page' | 'api'
+}
+
+function extractHeadings(markdown: string): string {
+  const headingRegex = /^#{1,6}\s+(.+)$/gm
+  const headings: string[] = []
+  let match
+  while ((match = headingRegex.exec(markdown)) !== null) {
+    headings.push(match[1].trim())
+  }
+  return headings.join(' ')
+}
+
+async function scanContent(contentDir: string): Promise<SearchDocument[]> {
+  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: extractHeadings(content),
+        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 [, 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
+}
+
+export async function generateSearchIndex(contentDir: string, outDir: string) {
+  const [contentDocs, apiDocs] = await Promise.all([
+    scanContent(contentDir),
+    Promise.resolve(buildApiDocs()),
+  ])
+
+  const documents = [...contentDocs, ...apiDocs]
+  const outPath = path.join(outDir, 'search-index.json')
+  await fs.writeFile(outPath, JSON.stringify(documents))
+
+  return documents.length
+}

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,97 @@
+// 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 { 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 { handleRequest } from './request-handler'
+
+export { render, matchRoute, loadConfig, loadApiSpecs, getPage, loadPageComponent, buildPageTree }
+
+async function writeResponse(res: import('http').ServerResponse, response: Response) {
+  res.statusCode = response.status
+  response.headers.forEach((value: string, key: string) => res.setHeader(key, value))
+  const body = await response.text()
+  res.end(body)
+}
+
+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 baseUrl = `http://localhost:${port}`
+
+  const server = createServer(async (req, res) => {
+    const url = req.url || '/'
+
+    try {
+      // API routes — handled by shared request handler
+      const routeHandler = matchRoute(new URL(url, baseUrl).href)
+      if (routeHandler) {
+        const response = await routeHandler(new Request(new URL(url, baseUrl)))
+        await writeResponse(res, response)
+        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
+
+      // SSR render — handled by shared request handler
+      const response = await handleRequest(url, { template, baseUrl })
+      await writeResponse(res, response)
+    } 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/entry-vercel.ts

@@ -0,0 +1,28 @@
+// Vercel serverless function entry — built by Vite, deployed as catch-all function
+import type { IncomingMessage, ServerResponse } from 'http'
+import { readFileSync } from 'fs'
+import { fileURLToPath } from 'url'
+import path from 'path'
+import { handleRequest } from './request-handler'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const templatePath = path.resolve(__dirname, 'index.html')
+const template = readFileSync(templatePath, 'utf-8')
+
+export default async function handler(req: IncomingMessage, res: ServerResponse) {
+  const url = req.url || '/'
+  const baseUrl = `https://${req.headers.host || 'localhost'}`
+
+  try {
+    const response = await handleRequest(url, { template, baseUrl })
+
+    res.statusCode = response.status
+    response.headers.forEach((value: string, key: string) => res.setHeader(key, value))
+    const body = await response.text()
+    res.end(body)
+  } catch (e) {
+    console.error(e)
+    res.statusCode = 500
+    res.end((e as Error).message)
+  }
+}

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