@raystack/chronicle 0.1.0-canary.a638730 → 0.1.0-canary.bd7f9af

package/src/server/entry-client.tsx

@@ -1,74 +1,82 @@
-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'
+import '@vitejs/plugin-react/preamble';
+import React from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router';
+import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
+import { mdxComponents } from '@/components/mdx';
+import { PageProvider } from '@/lib/page-context';
+import type { ChronicleConfig, Frontmatter, Root } from '@/types';
+import type { ApiSpec } from '@/lib/openapi';
+import type { ReactNode } from 'react';
+import { App } from './App';
 
 interface EmbeddedData {
-  config: ChronicleConfig
-  tree: PageTree
-  slug: string[]
-  frontmatter: { title: string; description?: string; order?: number }
-  filePath: string
+  config: ChronicleConfig;
+  tree: Root;
+  slug: string[];
+  frontmatter: Frontmatter;
+  relativePath: string;
 }
 
 async function hydrate() {
   try {
-    const embedded: EmbeddedData | undefined = (window as any).__PAGE_DATA__
+    const embedded = (
+      window as unknown as { __PAGE_DATA__?: EmbeddedData }
+    ).__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[] = []
+    const config: ChronicleConfig = embedded?.config ?? {
+      title: 'Documentation'
+    };
+    const tree: Root = embedded?.tree ?? { name: 'root', children: [] };
+    const isApiPage =
+      window.location.pathname.startsWith('/apis') && !!config.api?.length;
+    const apiSpecs: ApiSpec[] = isApiPage
+      ? await fetch('/api/specs')
+          .then(r => r.json())
+          .catch(() => [])
+      : [];
 
-    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()
-    }
+    const page = embedded?.relativePath
+      ? await loadPage(embedded)
+      : null;
 
     hydrateRoot(
       document.getElementById('root') as HTMLElement,
       <BrowserRouter>
-        <PageProvider initialConfig={config} initialTree={tree} initialPage={page} initialApiSpecs={apiSpecs}>
-          <App />
-        </PageProvider>
-      </BrowserRouter>,
-    )
+        <ReactRouterProvider>
+          <PageProvider
+            initialConfig={config}
+            initialTree={tree}
+            initialPage={page}
+            initialApiSpecs={apiSpecs}
+          >
+            <App />
+          </PageProvider>
+        </ReactRouterProvider>
+      </BrowserRouter>
+    );
   } catch (err) {
-    console.error('Hydration failed:', err)
+    console.error('Hydration failed:', err);
   }
 }
 
-hydrate()
+const contentModules = import.meta.glob<{ default?: React.ComponentType<any> }>(
+  '../../.content/**/*.{mdx,md}'
+);
+
+async function loadPage(
+  embedded: EmbeddedData
+): Promise<{ slug: string[]; frontmatter: Frontmatter; content: ReactNode }> {
+  const withoutExt = embedded.relativePath.replace(/\.(mdx|md)$/, '');
+  const key = embedded.relativePath.endsWith('.md')
+    ? `../../.content/${withoutExt}.md`
+    : `../../.content/${withoutExt}.mdx`;
+  const loader = contentModules[key];
+  const mod = loader ? await loader() : null;
+  const content = mod?.default
+    ? React.createElement(mod.default, { components: mdxComponents })
+    : null;
+  return { slug: embedded.slug, frontmatter: embedded.frontmatter, content };
+}
+
+hydrate();

package/src/server/entry-server.tsx

@@ -1,35 +1,104 @@
-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>,
-  )
-}
+import '@raystack/apsara/normalize.css';
+import '@raystack/apsara/style.css';
+import React from 'react';
+import { renderToReadableStream } from 'react-dom/server.edge';
+import { StaticRouter } from 'react-router';
+import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
+import { mdxComponents } from '@/components/mdx';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
+import { PageProvider } from '@/lib/page-context';
+import { getPageTree, getPage, loadPageComponent } from '@/lib/source';
+import { App } from './App';
+
+// @ts-expect-error virtual import from Nitro
+import clientAssets from './entry-client?assets=client';
+// @ts-expect-error virtual import from Nitro
+import serverAssets from './entry-server?assets=ssr';
+
+export default {
+  async fetch(req: Request) {
+    const url = new URL(req.url);
+    const pathname = url.pathname;
+    const slug = pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean);
+
+    const config = loadConfig();
+    const apiSpecs = config.api?.length
+      ? await loadApiSpecs(config.api).catch(() => [])
+      : [];
+
+    const [tree, page] = await Promise.all([
+      getPageTree(),
+      getPage(slug),
+    ]);
+
+    const data = page?.data as Record<string, unknown> | undefined;
+    const relativePath = (data?._relativePath as string) ?? null;
+
+    const pageData = page
+      ? {
+          slug,
+          frontmatter: {
+            title: (data?.title as string) ?? slug[slug.length - 1] ?? 'Untitled',
+            description: data?.description as string | undefined,
+            order: data?.order as number | undefined,
+            icon: data?.icon as string | undefined,
+            lastModified: data?.lastModified as string | undefined,
+          },
+          content: relativePath
+            ? await loadPageComponent(relativePath).then(component =>
+                component ? React.createElement(component, { components: mdxComponents }) : null
+              )
+            : null,
+        }
+      : null;
+
+    const embeddedData = {
+      config,
+      tree,
+      slug,
+      frontmatter: pageData?.frontmatter ?? null,
+      relativePath,
+    };
+    const safeJson = JSON.stringify(embeddedData).replace(/</g, '\\u003c');
+
+    const assets = clientAssets.merge(serverAssets);
+
+    const stream = await renderToReadableStream(
+      <html lang="en">
+        <head>
+          <meta charSet="UTF-8" />
+          <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+          {assets.css.map((attr: { href: string }) => (
+            <link key={attr.href} rel="stylesheet" {...attr} />
+          ))}
+          {assets.js.map((attr: { href: string }) => (
+            <link key={attr.href} rel="modulepreload" {...attr} />
+          ))}
+          <script type="module" src={assets.entry} />
+          <script dangerouslySetInnerHTML={{ __html: `window.__PAGE_DATA__ = ${safeJson}` }} />
+        </head>
+        <body>
+          <div id="root">
+            <StaticRouter location={pathname}>
+              <ReactRouterProvider>
+                <PageProvider
+                  initialConfig={config}
+                  initialTree={tree}
+                  initialPage={pageData}
+                  initialApiSpecs={apiSpecs}
+                >
+                  <App />
+                </PageProvider>
+              </ReactRouterProvider>
+            </StaticRouter>
+          </div>
+        </body>
+      </html>,
+    );
+
+    return new Response(stream, {
+      headers: { 'Content-Type': 'text/html;charset=utf-8' },
+    });
+  },
+};

package/src/server/routes/llms.txt.ts

@@ -0,0 +1,61 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { defineHandler, HTTPError } from 'nitro';
+import { loadConfig } from '@/lib/config';
+
+function getContentDir(): string {
+  return __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[] = []) {
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      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 });
+      }
+    } catch {
+      /* directory not readable */
+    }
+  }
+
+  await scan(contentDir);
+  return pages;
+}
+
+export default defineHandler(async event => {
+  const config = loadConfig();
+
+  if (!config.llms?.enabled) {
+    throw new HTTPError({ status: 404, message: 'Not Found' });
+  }
+
+  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}`;
+
+  event.res.headers.set('Content-Type', 'text/plain');
+  return body;
+});

package/src/server/routes/og.tsx

@@ -0,0 +1,75 @@
+import { defineHandler } from 'nitro';
+import React from 'react';
+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 {
+    fontData = new ArrayBuffer(0);
+  }
+
+  return fontData;
+}
+
+export default defineHandler(async event => {
+  const config = loadConfig();
+  const title = event.url.searchParams.get('title') ?? config.title;
+  const description = event.url.searchParams.get('description') ?? '';
+  const siteName = config.title;
+
+  const font = await loadFont();
+
+  const svg = await satori(
+    <div
+      style={{
+        height: '100%',
+        width: '100%',
+        display: 'flex',
+        flexDirection: 'column',
+        justifyContent: 'center',
+        padding: '60px 80px',
+        backgroundColor: '#0a0a0a',
+        color: '#fafafa',
+      }}
+    >
+      <div style={{ fontSize: 24, color: '#888', marginBottom: 16 }}>
+        {siteName}
+      </div>
+      <div
+        style={{
+          fontSize: 56,
+          fontWeight: 700,
+          lineHeight: 1.2,
+          marginBottom: 24,
+        }}
+      >
+        {title}
+      </div>
+      {description && (
+        <div style={{ fontSize: 24, color: '#999', lineHeight: 1.4 }}>
+          {description}
+        </div>
+      )}
+    </div>,
+    {
+      width: 1200,
+      height: 630,
+      fonts: [
+        { name: 'Inter', data: font, weight: 400, style: 'normal' as const },
+      ],
+    },
+  );
+
+  event.res.headers.set('Content-Type', 'image/svg+xml');
+  event.res.headers.set('Cache-Control', 'public, max-age=86400');
+  return svg;
+});

package/src/server/routes/robots.txt.ts

@@ -0,0 +1,11 @@
+import { defineHandler } from 'nitro';
+import { loadConfig } from '@/lib/config';
+
+export default defineHandler(event => {
+  const config = loadConfig();
+  const sitemap = config.url ? `\nSitemap: ${config.url}/sitemap.xml` : '';
+  const body = `User-agent: *\nAllow: /${sitemap}`;
+
+  event.res.headers.set('Content-Type', 'text/plain');
+  return body;
+});

package/src/server/routes/sitemap.xml.ts

@@ -0,0 +1,40 @@
+import { defineHandler } from 'nitro';
+import { buildApiRoutes } from '@/lib/api-routes';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
+import { getPages } from '@/lib/source';
+
+export default defineHandler(async event => {
+  const config = loadConfig();
+
+  if (!config.url) {
+    event.res.headers.set('Content-Type', 'application/xml');
+    return '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"/>';
+  }
+
+  const baseUrl = config.url.replace(/\/$/, '');
+
+  const pages = await getPages();
+  const docPages = pages.map(page => {
+    const data = page.data as Record<string, unknown>;
+    const lastmod = data.lastModified
+      ? `<lastmod>${new Date(data.lastModified as string).toISOString()}</lastmod>`
+      : '';
+    return `<url><loc>${baseUrl}/${page.slugs.join('/')}</loc>${lastmod}</url>`;
+  });
+
+  const apiPages = config.api?.length
+    ? buildApiRoutes(await 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>`;
+
+  event.res.headers.set('Content-Type', 'application/xml');
+  return xml;
+});

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

@@ -0,0 +1,17 @@
+import path from 'node: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

@@ -1,71 +1,101 @@
-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'
+import react from '@vitejs/plugin-react';
+import { remarkDirectiveAdmonition, remarkMdxMermaid } from 'fumadocs-core/mdx-plugins';
+import { defineConfig as defineFumadocsConfig } from 'fumadocs-mdx/config';
+import mdx from 'fumadocs-mdx/vite';
+import { nitro } from 'nitro/vite';
+import path from 'node:path';
+import remarkDirective from 'remark-directive';
+import { type InlineConfig } from 'vite';
+import remarkUnusedDirectives from '../lib/remark-unused-directives';
 
 export interface ViteConfigOptions {
-  root: string
-  contentDir: string
-  isDev?: boolean
+  packageRoot: string;
+  projectRoot: string;
+  contentDir: string;
+  preset?: string;
 }
 
-export async function createViteConfig(options: ViteConfigOptions): Promise<InlineConfig> {
-  const { root, contentDir, isDev = false } = options
+export async function createViteConfig(
+  options: ViteConfigOptions
+): Promise<InlineConfig> {
+  const { packageRoot, projectRoot, contentDir, preset } = options;
 
   return {
-    root,
+    root: packageRoot,
     configFile: false,
+    plugins: [
+      nitro({
+        serverDir: path.resolve(packageRoot, 'src/server'),
+        ...(preset && { preset }),
+      }),
+      mdx({
+        default: defineFumadocsConfig({
+          mdxOptions: {
+            remarkPlugins: [
+              remarkDirective,
+              [remarkDirectiveAdmonition, {
+                tags: {
+                  CalloutContainer: 'Callout',
+                  CalloutTitle: 'CalloutTitle',
+                  CalloutDescription: 'CalloutDescription',
+                },
+                types: {
+                  note: 'accent',
+                  tip: 'accent',
+                  info: 'accent',
+                  warn: 'attention',
+                  warning: 'attention',
+                  danger: 'alert',
+                  caution: 'alert',
+                  success: 'success',
+                },
+              }],
+              remarkUnusedDirectives,
+              remarkMdxMermaid,
+            ],
+          },
+        }),
+      }, { index: false }),
+      react()
+    ],
     resolve: {
       alias: {
-        '@': path.resolve(root, 'src'),
-        '@content': contentDir,
+        '@': path.resolve(packageRoot, 'src'),
       },
-      dedupe: ['react', 'react-dom', 'react/jsx-runtime', 'react/jsx-dev-runtime'],
+      conditions: ['module-sync', 'import', 'node'],
+      dedupe: [
+        'react',
+        'react-dom',
+        'react/jsx-runtime',
+        'react/jsx-dev-runtime',
+        'react-router',
+      ]
     },
     server: {
       fs: {
-        allow: [root, contentDir],
-      },
+        allow: [packageRoot, projectRoot, 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),
+      __CHRONICLE_CONTENT_DIR__: JSON.stringify(contentDir),
+      __CHRONICLE_PROJECT_ROOT__: JSON.stringify(projectRoot)
     },
     css: {
       modules: {
-        localsConvention: 'camelCase',
-      },
+        localsConvention: 'camelCase'
+      }
     },
     ssr: {
-      noExternal: ['@raystack/apsara'],
-    },
-    build: {
-      rolldownOptions: {
-        input: isDev ? undefined : {
-          client: path.resolve(root, 'src/server/index.html'),
-        },
-      },
+      noExternal: ['@raystack/apsara', 'dayjs', 'fumadocs-core']
     },
-  }
+    environments: {
+      client: {
+        build: {
+          rollupOptions: {
+            input: path.resolve(packageRoot, 'src/server/entry-client.tsx')
+          }
+        }
+      }
+    }
+  };
 }