@raystack/chronicle 0.3.0 → 0.5.0

package/src/server/api/specs.ts

@@ -0,0 +1,9 @@
+import { defineHandler } from 'nitro';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
+
+export default defineHandler(async () => {
+  const config = loadConfig();
+  const specs = config.api?.length ? await loadApiSpecs(config.api) : [];
+  return specs;
+});

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

@@ -0,0 +1,117 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import matter from 'gray-matter';
+import type { OpenAPIV3 } from 'openapi-types';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { visit } from 'unist-util-visit';
+import type { Heading, Text } from 'mdast';
+import { getSpecSlug } from '@/lib/api-routes';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
+
+interface SearchDocument {
+  id: string;
+  url: string;
+  title: string;
+  content: string;
+  type: 'page' | 'api';
+}
+
+function extractHeadings(markdown: string): string {
+  const tree = unified().use(remarkParse).parse(markdown);
+  const headings: string[] = [];
+  visit(tree, 'heading', (node: Heading) => {
+    const text = node.children
+      .filter((child): child is Text => child.type === 'text')
+      .map(child => child.value)
+      .join('');
+    if (text) headings.push(text);
+  });
+  return headings.join(' ');
+}
+
+async function scanContent(contentDir: string): Promise<SearchDocument[]> {
+  const docs: SearchDocument[] = [];
+
+  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, 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'
+        });
+      }
+    } catch {
+      /* directory not readable */
+    }
+  }
+
+  await scan(contentDir);
+  return docs;
+}
+
+async function buildApiDocs(): Promise<SearchDocument[]> {
+  const config = loadConfig();
+  if (!config.api?.length) return [];
+
+  const docs: SearchDocument[] = [];
+  const specs = await 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),
+    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/entry-client.tsx

@@ -0,0 +1,88 @@
+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, TableOfContents } from '@/types';
+import type { ApiSpec } from '@/lib/openapi';
+import type { ReactNode } from 'react';
+import { App } from './App';
+
+interface EmbeddedData {
+  config: ChronicleConfig;
+  tree: Root;
+  slug: string[];
+  frontmatter: Frontmatter;
+  relativePath: string;
+  originalPath?: string;
+}
+
+const contentModules = import.meta.glob<{ default?: React.ComponentType<any>; toc?: TableOfContents }>(
+  '../../.content/**/*.{mdx,md}'
+);
+
+async function loadMdxModule(relativePath: string): Promise<{ content: ReactNode; toc: TableOfContents }> {
+  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
+  const key = relativePath.endsWith('.md')
+    ? `../../.content/${withoutExt}.md`
+    : `../../.content/${withoutExt}.mdx`;
+  const loader = contentModules[key];
+  if (!loader) return { content: null, toc: [] };
+  const mod = await loader();
+  const content = mod.default
+    ? React.createElement(mod.default, { components: mdxComponents })
+    : null;
+  return { content, toc: mod.toc ?? [] };
+}
+
+async function hydrate() {
+  try {
+    const embedded = (
+      window as unknown as { __PAGE_DATA__?: EmbeddedData }
+    ).__PAGE_DATA__;
+
+    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(() => [])
+      : [];
+
+    const mdxPath = embedded?.originalPath || embedded?.relativePath;
+    const page = mdxPath
+      ? {
+          slug: embedded!.slug,
+          frontmatter: embedded!.frontmatter,
+          ...(await loadMdxModule(mdxPath)),
+        }
+      : null;
+
+    hydrateRoot(
+      document.getElementById('root') as HTMLElement,
+      <BrowserRouter>
+        <ReactRouterProvider>
+          <PageProvider
+            initialConfig={config}
+            initialTree={tree}
+            initialPage={page}
+            initialApiSpecs={apiSpecs}
+            loadMdx={loadMdxModule}
+          >
+            <App />
+          </PageProvider>
+        </ReactRouterProvider>
+      </BrowserRouter>
+    );
+  } catch (err) {
+    console.error('Hydration failed:', err);
+  }
+}
+
+hydrate();

package/src/server/entry-server.tsx

@@ -0,0 +1,102 @@
+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, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
+import { App } from './App';
+
+import clientAssets from './entry-client?assets=client';
+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 relativePath = page ? getRelativePath(page) : null;
+    const originalPath = page ? getOriginalPath(page) : null;
+    const mdxModule = (originalPath || relativePath) ? await loadPageModule(originalPath || relativePath!) : null;
+
+    const pageData = page
+      ? {
+          slug,
+          frontmatter: extractFrontmatter(page, slug[slug.length - 1]),
+          content: mdxModule?.default
+            ? React.createElement(mdxModule.default, { components: mdxComponents })
+            : null,
+          toc: mdxModule?.toc ?? [],
+        }
+      : null;
+
+    const embeddedData = {
+      config,
+      tree,
+      slug,
+      frontmatter: pageData?.frontmatter ?? null,
+      relativePath,
+      originalPath,
+    };
+    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}
+                  loadMdx={async () => ({ content: null, toc: [] })}
+                >
+                  <App />
+                </PageProvider>
+              </ReactRouterProvider>
+            </StaticRouter>
+          </div>
+        </body>
+      </html>,
+    );
+
+    const isApiRoute = pathname.startsWith('/apis');
+    const status = !page && !isApiRoute && slug.length > 0 ? 404 : 200;
+
+    return new Response(stream, {
+      status,
+      headers: { 'Content-Type': 'text/html;charset=utf-8' },
+    });
+  },
+};

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

@@ -0,0 +1,21 @@
+import { defineHandler, HTTPError } from 'nitro';
+import { loadConfig } from '@/lib/config';
+import { getPages, extractFrontmatter } from '@/lib/source';
+
+export default defineHandler(async event => {
+  const config = loadConfig();
+
+  if (!config.llms?.enabled) {
+    throw new HTTPError({ status: 404, message: 'Not Found' });
+  }
+
+  const pages = await getPages();
+  const index = pages.map(p => {
+    const fm = extractFrontmatter(p);
+    return `- [${fm.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

@@ -0,0 +1,133 @@
+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 fs from 'node:fs/promises';
+import path from 'node:path';
+import remarkDirective from 'remark-directive';
+import { type InlineConfig } from 'vite';
+import remarkStripMdExtensions from '../lib/remark-strip-md-extensions';
+import remarkUnusedDirectives from '../lib/remark-unused-directives';
+
+function resolveOutputDir(projectRoot: string, preset?: string): string {
+  if (preset === 'vercel' || preset === 'vercel-static') return path.resolve(projectRoot, '.vercel/output');
+  return path.resolve(projectRoot, '.output');
+}
+
+export interface ViteConfigOptions {
+  packageRoot: string;
+  projectRoot: string;
+  contentDir: string;
+  configPath?: string;
+  preset?: string;
+}
+
+async function readChronicleConfig(projectRoot: string, configPath?: string): Promise<string | null> {
+  if (configPath) {
+    try {
+      return await fs.readFile(configPath, 'utf-8');
+    } catch (error) {
+      throw new Error(`Failed to read config file '${configPath}': ${(error as Error).message}`);
+    }
+  }
+  try {
+    return await fs.readFile(path.join(projectRoot, 'chronicle.yaml'), 'utf-8');
+  } catch {
+    return null;
+  }
+}
+
+export async function createViteConfig(
+  options: ViteConfigOptions
+): Promise<InlineConfig> {
+  const { packageRoot, projectRoot, contentDir, configPath, preset } = options;
+  const rawConfig = await readChronicleConfig(projectRoot, configPath);
+
+  return {
+    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,
+              remarkStripMdExtensions,
+              remarkMdxMermaid,
+            ],
+          },
+        }),
+      }, { index: false }),
+      react()
+    ],
+    resolve: {
+      alias: {
+        '@': path.resolve(packageRoot, 'src'),
+      },
+      conditions: ['module-sync', 'import', 'node'],
+      dedupe: [
+        'react',
+        'react-dom',
+        'react/jsx-runtime',
+        'react/jsx-dev-runtime',
+        'react-router',
+      ]
+    },
+    server: {
+      fs: {
+        allow: [packageRoot, projectRoot, contentDir]
+      }
+    },
+    define: {
+      __CHRONICLE_CONTENT_DIR__: JSON.stringify(contentDir),
+      __CHRONICLE_PROJECT_ROOT__: JSON.stringify(projectRoot),
+      __CHRONICLE_CONFIG_RAW__: JSON.stringify(rawConfig),
+    },
+    css: {
+      modules: {
+        localsConvention: 'camelCase'
+      }
+    },
+    ssr: {
+      noExternal: ['@raystack/apsara', 'dayjs', 'fumadocs-core']
+    },
+    environments: {
+      client: {
+        build: {
+          rollupOptions: {
+            input: path.resolve(packageRoot, 'src/server/entry-client.tsx')
+          }
+        }
+      }
+    },
+    nitro: {
+      logLevel: 2,
+      output: {
+        dir: resolveOutputDir(projectRoot, preset),
+      },
+    },
+  };
+}