@raystack/chronicle 0.1.0-canary.111b55a

package/src/lib/source.ts

@@ -0,0 +1,138 @@
+import type { MDXContent } from 'mdx/types'
+import type { Frontmatter, PageTree, PageTreeItem } from '@/types'
+
+const meta: Record<string, Frontmatter> = import.meta.glob(
+  '@content/**/*.{mdx,md}',
+  { eager: true, import: 'frontmatter' }
+)
+
+const loaders: Record<string, () => Promise<{ default: MDXContent }>> = import.meta.glob(
+  '@content/**/*.{mdx,md}'
+)
+
+export interface SourcePage {
+  url: string
+  slugs: string[]
+  filePath: string
+  frontmatter: Frontmatter
+}
+
+// Compute common directory prefix of all glob keys once
+function computePrefix(keys: string[]): string {
+  if (keys.length === 0) return ''
+  const dirs = keys.map((k) => k.split('/').slice(0, -1)) // drop filename
+  const first = dirs[0]
+  let depth = 0
+  for (let i = 0; i < first.length; i++) {
+    if (dirs.every((d) => d[i] === first[i])) {
+      depth = i + 1
+    } else {
+      break
+    }
+  }
+  return first.slice(0, depth).join('/') + '/'
+}
+
+const prefix = computePrefix(Object.keys(meta))
+
+function filePathToSlugs(filePath: string): string[] {
+  const relative = filePath.slice(prefix.length)
+  const withoutExt = relative.replace(/\.(mdx|md)$/, '')
+  const parts = withoutExt.split('/').filter(Boolean)
+  if (parts[parts.length - 1] === 'index') parts.pop()
+  return parts
+}
+
+function slugsToUrl(slugs: string[]): string {
+  return slugs.length === 0 ? '/' : '/' + slugs.join('/')
+}
+
+let cachedPages: SourcePage[] | null = null
+
+export async function getPages(): Promise<SourcePage[]> {
+  if (cachedPages) return cachedPages
+
+  cachedPages = Object.entries(meta).map(([filePath, fm]) => {
+    const slugs = filePathToSlugs(filePath)
+    const baseName = slugs[slugs.length - 1] ?? 'index'
+    return {
+      url: slugsToUrl(slugs),
+      slugs,
+      filePath,
+      frontmatter: {
+        title: fm?.title ?? baseName,
+        description: fm?.description,
+        order: fm?.order,
+        icon: fm?.icon,
+        lastModified: fm?.lastModified,
+      },
+    }
+  })
+
+  return cachedPages
+}
+
+export async function getPage(slug?: string[]): Promise<SourcePage | null> {
+  const pages = await getPages()
+  const targetUrl = !slug || slug.length === 0 ? '/' : '/' + slug.join('/')
+  return pages.find((p) => p.url === targetUrl) ?? null
+}
+
+export async function loadPageComponent(page: SourcePage): Promise<MDXContent | null> {
+  const loader = loaders[page.filePath]
+  if (!loader) return null
+  const mod = await loader()
+  return mod.default
+}
+
+export function invalidate() {
+  cachedPages = null
+}
+
+export async function buildPageTree(): Promise<PageTree> {
+  const pages = await getPages()
+  const folders = new Map<string, PageTreeItem[]>()
+  const rootPages: PageTreeItem[] = []
+
+  pages.forEach((page) => {
+    const isIndex = page.url === '/'
+    const item: PageTreeItem = {
+      type: 'page',
+      name: page.frontmatter.title,
+      url: page.url,
+      order: page.frontmatter.order ?? (isIndex ? 0 : undefined),
+    }
+
+    if (page.slugs.length > 1) {
+      const folder = page.slugs[0]
+      if (!folders.has(folder)) {
+        folders.set(folder, [])
+      }
+      folders.get(folder)?.push(item)
+    } else {
+      rootPages.push(item)
+    }
+  })
+
+  const sortByOrder = (items: PageTreeItem[]) =>
+    items.sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER))
+
+  const children: PageTreeItem[] = sortByOrder(rootPages)
+
+  const folderItems: PageTreeItem[] = []
+  folders.forEach((items, folder) => {
+    const sorted = sortByOrder(items)
+    const indexPage = items.find(item => item.url === `/${folder}`)
+    const folderOrder = indexPage?.order ?? sorted[0]?.order
+    folderItems.push({
+      type: 'folder',
+      name: folder.charAt(0).toUpperCase() + folder.slice(1),
+      order: folderOrder,
+      children: sorted,
+    })
+  })
+
+  children.push(...sortByOrder(folderItems))
+
+  return { name: 'root', children }
+}

package/src/pages/ApiLayout.module.css

@@ -0,0 +1,22 @@
+.layout {
+  height: 100vh;
+  overflow: hidden;
+}
+
+.body {
+  overflow: hidden;
+}
+
+.sidebar {
+  height: 100%;
+}
+
+.content {
+  height: 100%;
+  overflow-y: auto;
+  padding-right: 0;
+}
+
+.hiddenSearch {
+  display: none;
+}

package/src/pages/ApiLayout.tsx

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react'
+import { cx } from 'class-variance-authority'
+import { usePageContext } from '@/lib/page-context'
+import { buildApiPageTree } from '@/lib/api-routes'
+import { getTheme } from '@/themes/registry'
+import { Search } from '@/components/ui/search'
+import styles from './ApiLayout.module.css'
+
+interface ApiLayoutProps {
+  children: ReactNode
+}
+
+export function ApiLayout({ children }: ApiLayoutProps) {
+  const { config, apiSpecs } = usePageContext()
+  const { Layout, className } = getTheme(config.theme?.name)
+  const tree = buildApiPageTree(apiSpecs)
+
+  return (
+    <Layout config={config} tree={tree} classNames={{
+      layout: cx(styles.layout, className),
+      body: styles.body,
+      sidebar: styles.sidebar,
+      content: styles.content,
+    }}>
+      <Search className={styles.hiddenSearch} />
+      {children}
+    </Layout>
+  )
+}

package/src/pages/ApiPage.tsx

@@ -0,0 +1,68 @@
+import type { OpenAPIV3 } from 'openapi-types'
+import { Flex, Headline, Text } from '@raystack/apsara'
+import { usePageContext } from '@/lib/page-context'
+import { findApiOperation } from '@/lib/api-routes'
+import { EndpointPage } from '@/components/api'
+import { Head } from '@/lib/head'
+import type { ApiSpec } from '@/lib/openapi'
+
+interface ApiPageProps {
+  slug: string[]
+}
+
+export function ApiPage({ slug }: ApiPageProps) {
+  const { config, apiSpecs } = usePageContext()
+
+  if (slug.length === 0) {
+    return (
+      <>
+        <Head
+          title="API Reference"
+          description={`API documentation for ${config.title}`}
+          config={config}
+        />
+        <ApiLanding specs={apiSpecs} />
+      </>
+    )
+  }
+
+  const match = findApiOperation(apiSpecs, slug)
+  if (!match) return null
+
+  const operation = match.operation as OpenAPIV3.OperationObject
+  const title = operation.summary ?? `${match.method.toUpperCase()} ${match.path}`
+
+  return (
+    <>
+      <Head
+        title={title}
+        description={operation.description}
+        config={config}
+      />
+      <EndpointPage
+        method={match.method}
+        path={match.path}
+        operation={match.operation}
+        serverUrl={match.spec.server.url}
+        specName={match.spec.name}
+        auth={match.spec.auth}
+      />
+    </>
+  )
+}
+
+function ApiLanding({ specs }: { specs: ApiSpec[] }) {
+  return (
+    <Flex direction="column" gap="large" style={{ padding: 'var(--rs-space-7)' }}>
+      <Headline size="medium" as="h1">API Reference</Headline>
+      {specs.map((spec) => (
+        <Flex key={spec.name} direction="column" gap="small">
+          <Headline size="small" as="h2">{spec.name}</Headline>
+          {spec.document.info.description && (
+            <Text size={3}>{spec.document.info.description}</Text>
+          )}
+        </Flex>
+      ))}
+    </Flex>
+  )
+}

package/src/pages/DocsLayout.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react'
+import { usePageContext } from '@/lib/page-context'
+import { getTheme } from '@/themes/registry'
+
+interface DocsLayoutProps {
+  children: ReactNode
+}
+
+export function DocsLayout({ children }: DocsLayoutProps) {
+  const { config, tree } = usePageContext()
+  const { Layout, className } = getTheme(config.theme?.name)
+
+  return (
+    <Layout config={config} tree={tree} classNames={{ layout: className }}>
+      {children}
+    </Layout>
+  )
+}

package/src/pages/DocsPage.tsx

@@ -0,0 +1,43 @@
+import { usePageContext } from '@/lib/page-context'
+import { getTheme } from '@/themes/registry'
+import { Head } from '@/lib/head'
+
+interface DocsPageProps {
+  slug: string[]
+}
+
+export function DocsPage({ slug }: DocsPageProps) {
+  const { config, tree, page } = usePageContext()
+
+  if (!page) return null
+
+  const { Page } = getTheme(config.theme?.name)
+  const pageUrl = config.url ? `${config.url}/${slug.join('/')}` : undefined
+
+  return (
+    <>
+      <Head
+        title={page.frontmatter.title}
+        description={page.frontmatter.description}
+        config={config}
+        jsonLd={{
+          '@context': 'https://schema.org',
+          '@type': 'Article',
+          headline: page.frontmatter.title,
+          description: page.frontmatter.description,
+          ...(pageUrl && { url: pageUrl }),
+        }}
+      />
+      <Page
+        page={{
+          slug,
+          frontmatter: page.frontmatter,
+          content: page.content,
+          toc: [],
+        }}
+        config={config}
+        tree={tree}
+      />
+    </>
+  )
+}

package/src/pages/NotFound.tsx

@@ -0,0 +1,10 @@
+import { Flex, Headline, Text } from '@raystack/apsara'
+
+export function NotFound() {
+  return (
+    <Flex direction="column" align="center" justify="center" style={{ minHeight: '60vh' }}>
+      <Headline size="large" as="h1">404</Headline>
+      <Text size={3}>Page not found</Text>
+    </Flex>
+  )
+}

package/src/pages/__tests__/head.test.tsx

@@ -0,0 +1,57 @@
+import { describe, it, expect } from 'vitest'
+import { renderToString } from 'react-dom/server'
+import { Head } from '@/lib/head'
+
+describe('Head component', () => {
+  const baseConfig = {
+    title: 'Test Docs',
+    theme: { name: 'default' as const },
+    search: { enabled: true, placeholder: 'Search...' },
+  }
+
+  it('renders title tag', () => {
+    const html = renderToString(
+      <Head title="Page Title" config={baseConfig} />
+    )
+    expect(html).toContain('Page Title | Test Docs')
+  })
+
+  it('renders description meta tag', () => {
+    const html = renderToString(
+      <Head title="Page" description="A description" config={baseConfig} />
+    )
+    expect(html).toContain('A description')
+  })
+
+  it('renders OG tags when config.url is set', () => {
+    const html = renderToString(
+      <Head
+        title="Page"
+        description="Desc"
+        config={{ ...baseConfig, url: 'https://docs.example.com' }}
+      />
+    )
+    expect(html).toContain('og:title')
+    expect(html).toContain('og:description')
+    expect(html).toContain('twitter:card')
+  })
+
+  it('skips OG tags when no url in config', () => {
+    const html = renderToString(
+      <Head title="Page" config={baseConfig} />
+    )
+    expect(html).not.toContain('og:title')
+  })
+
+  it('renders JSON-LD script', () => {
+    const html = renderToString(
+      <Head
+        title="Page"
+        config={baseConfig}
+        jsonLd={{ '@context': 'https://schema.org', '@type': 'Article' }}
+      />
+    )
+    expect(html).toContain('application/ld+json')
+    expect(html).toContain('schema.org')
+  })
+})

package/src/server/App.tsx

@@ -0,0 +1,59 @@
+import '@raystack/apsara/normalize.css'
+import '@raystack/apsara/style.css'
+import { ThemeProvider } from '@raystack/apsara'
+import { useLocation } from 'react-router-dom'
+import { usePageContext } from '@/lib/page-context'
+import { Head } from '@/lib/head'
+import { DocsLayout } from '@/pages/DocsLayout'
+import { DocsPage } from '@/pages/DocsPage'
+import { ApiLayout } from '@/pages/ApiLayout'
+import { ApiPage } from '@/pages/ApiPage'
+import type { ChronicleConfig } from '@/types'
+
+function resolveRoute(pathname: string) {
+  if (pathname.startsWith('/apis')) {
+    const slug = pathname.replace(/^\/apis\/?/, '').split('/').filter(Boolean)
+    return { type: 'api' as const, slug }
+  }
+
+  const slug = pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean)
+  return { type: 'docs' as const, slug }
+}
+
+export function App() {
+  const { pathname } = useLocation()
+  const { config } = usePageContext()
+  const route = resolveRoute(pathname)
+
+  return (
+    <ThemeProvider enableSystem>
+      <RootHead config={config} />
+      {route.type === 'api' ? (
+        <ApiLayout>
+          <ApiPage slug={route.slug} />
+        </ApiLayout>
+      ) : (
+        <DocsLayout>
+          <DocsPage slug={route.slug} />
+        </DocsLayout>
+      )}
+    </ThemeProvider>
+  )
+}
+
+function RootHead({ config }: { config: ChronicleConfig }) {
+  return (
+    <Head
+      title={config.title}
+      description={config.description}
+      config={config}
+      jsonLd={config.url ? {
+        '@context': 'https://schema.org',
+        '@type': 'WebSite',
+        name: config.title,
+        description: config.description,
+        url: config.url,
+      } : undefined}
+    />
+  )
+}

package/src/server/__tests__/entry-server.test.tsx

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest'
+import { render, type SSRData } from '../entry-server'
+
+const mockData: SSRData = {
+  config: { title: 'Test Site' },
+  tree: { name: 'root', children: [] },
+  page: {
+    slug: [],
+    frontmatter: { title: 'Test' },
+    content: null,
+  },
+  apiSpecs: [],
+}
+
+describe('entry-server', () => {
+  it('exports a render function', () => {
+    expect(typeof render).toBe('function')
+  })
+
+  it('returns an HTML string', () => {
+    const html = render('http://localhost:3000/', mockData)
+    expect(typeof html).toBe('string')
+    expect(html.length).toBeGreaterThan(0)
+  })
+
+  it('renders docs route for root URL', () => {
+    const html = render('http://localhost:3000/', mockData)
+    expect(html).toBeTruthy()
+  })
+
+  it('renders api route for /apis URL', () => {
+    const html = render('http://localhost:3000/apis', mockData)
+    expect(html).toBeTruthy()
+  })
+})

package/src/server/__tests__/handlers.test.ts

@@ -0,0 +1,77 @@
+import { describe, it, expect } from 'vitest'
+import { handleHealth } from '../handlers/health'
+import { handleRobots } from '../handlers/robots'
+import { handleSitemap } from '../handlers/sitemap'
+import { handleApisProxy } from '../handlers/apis-proxy'
+import { handleLlms } from '../handlers/llms'
+
+describe('handleHealth', () => {
+  it('returns 200 with status ok', async () => {
+    const response = handleHealth()
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    expect(body).toEqual({ status: 'ok' })
+  })
+})
+
+describe('handleRobots', () => {
+  it('returns text/plain content type', async () => {
+    const response = handleRobots()
+    expect(response.headers.get('content-type')).toBe('text/plain')
+  })
+
+  it('includes User-agent directive', async () => {
+    const response = handleRobots()
+    const text = await response.text()
+    expect(text).toContain('User-agent: *')
+    expect(text).toContain('Allow: /')
+  })
+})
+
+describe('handleSitemap', () => {
+  it('returns application/xml content type', async () => {
+    const response = await handleSitemap()
+    expect(response.headers.get('content-type')).toBe('application/xml')
+  })
+
+  it('returns valid XML structure', async () => {
+    const response = await handleSitemap()
+    const xml = await response.text()
+    expect(xml).toContain('<urlset')
+  })
+})
+
+describe('handleApisProxy', () => {
+  it('returns 405 for GET requests', async () => {
+    const req = new Request('http://localhost:3000/api/apis-proxy', { method: 'GET' })
+    const response = await handleApisProxy(req)
+    expect(response.status).toBe(405)
+  })
+
+  it('returns 400 for POST without required fields', async () => {
+    const req = new Request('http://localhost:3000/api/apis-proxy', {
+      method: 'POST',
+      body: JSON.stringify({}),
+      headers: { 'Content-Type': 'application/json' },
+    })
+    const response = await handleApisProxy(req)
+    expect(response.status).toBe(400)
+  })
+
+  it('returns 404 for unknown spec', async () => {
+    const req = new Request('http://localhost:3000/api/apis-proxy', {
+      method: 'POST',
+      body: JSON.stringify({ specName: 'nonexistent', method: 'GET', path: '/test' }),
+      headers: { 'Content-Type': 'application/json' },
+    })
+    const response = await handleApisProxy(req)
+    expect(response.status).toBe(404)
+  })
+})
+
+describe('handleLlms', () => {
+  it('returns 404 when llms not enabled', async () => {
+    const response = await handleLlms()
+    expect(response.status).toBe(404)
+  })
+})

package/src/server/__tests__/og.test.ts

@@ -0,0 +1,23 @@
+import { describe, it, expect } from 'vitest'
+import { handleOg } from '../handlers/og'
+
+// OG handler requires network to fetch fonts, skip in CI-like environments
+describe.skipIf(!process.env.TEST_OG)('handleOg', () => {
+  it('returns SVG content type', async () => {
+    const req = new Request('http://localhost:3000/og?title=Test')
+    const response = await handleOg(req)
+    expect(response.headers.get('content-type')).toBe('image/svg+xml')
+  })
+
+  it('returns cache-control header', async () => {
+    const req = new Request('http://localhost:3000/og?title=Test')
+    const response = await handleOg(req)
+    expect(response.headers.get('cache-control')).toContain('max-age')
+  })
+})
+
+describe('handleOg export', () => {
+  it('exports a function', () => {
+    expect(typeof handleOg).toBe('function')
+  })
+})

package/src/server/__tests__/router.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest'
+import { matchRoute } from '../router'
+
+describe('router', () => {
+  it('matches /api/health route', () => {
+    const handler = matchRoute('http://localhost:3000/api/health')
+    expect(handler).not.toBeNull()
+  })
+
+  it('returns ok for /api/health', async () => {
+    const handler = matchRoute('http://localhost:3000/api/health')
+    const response = await handler!(new Request('http://localhost:3000/api/health'))
+    expect(response.status).toBe(200)
+    const body = await response.json()
+    expect(body).toEqual({ status: 'ok' })
+  })
+
+  it('matches /api/search route', () => {
+    const handler = matchRoute('http://localhost:3000/api/search')
+    expect(handler).not.toBeNull()
+  })
+
+  it('matches /robots.txt route', () => {
+    const handler = matchRoute('http://localhost:3000/robots.txt')
+    expect(handler).not.toBeNull()
+  })
+
+  it('returns robots.txt with correct content', async () => {
+    const handler = matchRoute('http://localhost:3000/robots.txt')
+    const response = await handler!(new Request('http://localhost:3000/robots.txt'))
+    expect(response.headers.get('content-type')).toBe('text/plain')
+    const text = await response.text()
+    expect(text).toContain('User-agent')
+  })
+
+  it('matches /sitemap.xml route', () => {
+    const handler = matchRoute('http://localhost:3000/sitemap.xml')
+    expect(handler).not.toBeNull()
+  })
+
+  it('returns sitemap.xml with xml content type', async () => {
+    const handler = matchRoute('http://localhost:3000/sitemap.xml')
+    const response = await handler!(new Request('http://localhost:3000/sitemap.xml'))
+    expect(response.headers.get('content-type')).toBe('application/xml')
+  })
+
+  it('returns null for unknown routes', () => {
+    const handler = matchRoute('http://localhost:3000/some/random/path')
+    expect(handler).toBeNull()
+  })
+
+  it('matches /llms.txt route', () => {
+    const handler = matchRoute('http://localhost:3000/llms.txt')
+    expect(handler).not.toBeNull()
+  })
+
+  it('matches /og route', () => {
+    const handler = matchRoute('http://localhost:3000/og')
+    expect(handler).not.toBeNull()
+  })
+
+  it('matches /api/apis-proxy route', () => {
+    const handler = matchRoute('http://localhost:3000/api/apis-proxy')
+    expect(handler).not.toBeNull()
+  })
+
+  it('returns 405 for non-POST to apis-proxy', async () => {
+    const handler = matchRoute('http://localhost:3000/api/apis-proxy')
+    const response = await handler!(new Request('http://localhost:3000/api/apis-proxy'))
+    expect(response.status).toBe(405)
+  })
+})

package/src/server/__tests__/vite-config.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest'
+import { createViteConfig } from '../vite-config'
+
+describe('createViteConfig', () => {
+  it('returns a valid vite config object', async () => {
+    const config = await createViteConfig({
+      root: '/tmp/test',
+      contentDir: '/tmp/test/content',
+      isDev: true,
+    })
+
+    expect(config.root).toBe('/tmp/test')
+    expect(config.configFile).toBe(false)
+  })
+
+  it('accepts isDev option', async () => {
+    const config = await createViteConfig({
+      root: '/tmp/test',
+      contentDir: '/tmp/test/content',
+      isDev: false,
+    })
+
+    expect(config.root).toBe('/tmp/test')
+  })
+})