@raystack/chronicle 0.1.0-canary.0efaef0

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,39 @@
+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 lastmod = page.frontmatter.lastModified
+      ? `<lastmod>${new Date(page.frontmatter.lastModified).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,71 @@
+import react from '@vitejs/plugin-react';
+import mdx from 'fumadocs-mdx/vite';
+import { nitro } from 'nitro/vite';
+import path from 'node:path';
+import { type InlineConfig } from 'vite';
+
+export interface ViteConfigOptions {
+  packageRoot: string;
+  projectRoot: string;
+  contentDir: string;
+  preset?: string;
+}
+
+export async function createViteConfig(
+  options: ViteConfigOptions
+): Promise<InlineConfig> {
+  const { packageRoot, projectRoot, contentDir, preset } = options;
+
+  return {
+    root: packageRoot,
+    configFile: false,
+    plugins: [
+      nitro({
+        serverDir: path.resolve(packageRoot, 'src/server'),
+        ...(preset && { preset }),
+      }),
+      mdx({}, { 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_PACKAGE_ROOT__: JSON.stringify(packageRoot)
+    },
+    css: {
+      modules: {
+        localsConvention: 'camelCase'
+      }
+    },
+    ssr: {
+      noExternal: ['@raystack/apsara', 'dayjs', 'fumadocs-core']
+    },
+    environments: {
+      client: {
+        build: {
+          rollupOptions: {
+            input: path.resolve(packageRoot, 'src/server/entry-client.tsx')
+          }
+        }
+      }
+    }
+  };
+}

package/src/themes/default/Layout.module.css

@@ -0,0 +1,81 @@
+.layout {
+  min-height: 100vh;
+}
+
+.header {
+  border-bottom: 1px solid var(--rs-color-border-base-primary);
+}
+
+.search {
+  margin-left: var(--rs-space-5);
+}
+
+.body {
+  flex: 1;
+}
+
+.sidebar {
+  width: 260px;
+  position: sticky;
+  top: 0;
+  height: 100vh;
+}
+
+.content {
+  flex: 1;
+  padding: var(--rs-space-9);
+}
+
+.sidebarList {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.separator {
+  height: 1px;
+  background: var(--rs-color-border-base-primary);
+  margin: var(--rs-space-3) 0;
+}
+
+.folder {
+  margin-bottom: var(--rs-space-3);
+}
+
+.folderLabel {
+  font-weight: 500;
+  font-size: 0.875rem;
+  color: var(--rs-color-text-base-secondary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.folder > .sidebarList {
+  margin-top: var(--rs-space-2);
+  padding-left: var(--rs-space-4);
+}
+
+.navButton {
+  display: flex;
+  align-items: center;
+  height: 32px;
+  padding: 0 var(--rs-space-4);
+  border: 1px solid var(--rs-color-border-base-primary);
+  border-radius: var(--rs-radius-2);
+  font-size: var(--rs-font-size-small);
+  font-weight: var(--rs-font-weight-medium);
+  color: var(--rs-color-foreground-base-primary);
+  text-decoration: none;
+}
+
+.navButton:hover {
+  background: var(--rs-color-background-base-primary-hover);
+}
+
+.groupItems {
+  padding-left: var(--rs-space-4);
+}
+
+.page {
+  padding: var(--rs-space-2) 0;
+}

package/src/themes/default/Layout.tsx

@@ -0,0 +1,160 @@
+import { RectangleStackIcon } from '@heroicons/react/24/outline';
+import {
+  Button,
+  Flex,
+  Headline,
+  Link,
+  Navbar,
+  Sidebar
+} from '@raystack/apsara';
+import { cx } from 'class-variance-authority';
+import { useEffect, useMemo, useRef } from 'react';
+import { Link as RouterLink, useLocation } from 'react-router';
+import { MethodBadge } from '@/components/api/method-badge';
+import { ClientThemeSwitcher } from '@/components/ui/client-theme-switcher';
+import { Footer } from '@/components/ui/footer';
+import { Search } from '@/components/ui/search';
+import type { PageTreeItem, ThemeLayoutProps } from '@/types';
+import styles from './Layout.module.css';
+
+const iconMap: Record<string, React.ReactNode> = {
+  'rectangle-stack': <RectangleStackIcon width={16} height={16} />,
+  'method-get': <MethodBadge method='GET' size='micro' />,
+  'method-post': <MethodBadge method='POST' size='micro' />,
+  'method-put': <MethodBadge method='PUT' size='micro' />,
+  'method-delete': <MethodBadge method='DELETE' size='micro' />,
+  'method-patch': <MethodBadge method='PATCH' size='micro' />
+};
+
+let savedScrollTop = 0;
+
+export function Layout({
+  children,
+  config,
+  tree,
+  classNames
+}: ThemeLayoutProps) {
+  const { pathname } = useLocation();
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    const onScroll = () => {
+      savedScrollTop = el.scrollTop;
+    };
+    el.addEventListener('scroll', onScroll);
+    return () => el.removeEventListener('scroll', onScroll);
+  }, []);
+
+  useEffect(() => {
+    const el = scrollRef.current;
+    if (el)
+      requestAnimationFrame(() => {
+        el.scrollTop = savedScrollTop;
+      });
+  }, [pathname]);
+
+  return (
+    <Flex direction='column' className={cx(styles.layout, classNames?.layout)}>
+      <Navbar className={styles.header}>
+        <Navbar.Start>
+          <RouterLink
+            to='/'
+            style={{ textDecoration: 'none', color: 'inherit' }}
+          >
+            <Headline size='small' weight='medium' as='h1'>
+              {config.title}
+            </Headline>
+          </RouterLink>
+        </Navbar.Start>
+        <Navbar.End>
+          <Flex gap='medium' align='center' className={styles.navActions}>
+            {config.api?.map(api => (
+              <RouterLink
+                key={api.basePath}
+                to={api.basePath}
+                className={styles.navButton}
+              >
+                {api.name} API
+              </RouterLink>
+            ))}
+            {config.navigation?.links?.map(link => (
+              <Link key={link.href} href={link.href}>
+                {link.label}
+              </Link>
+            ))}
+            {config.search?.enabled && <Search />}
+          </Flex>
+          <ClientThemeSwitcher size={16} />
+        </Navbar.End>
+      </Navbar>
+      <Flex className={cx(styles.body, classNames?.body)}>
+        <Sidebar
+          defaultOpen
+          collapsible={false}
+          className={cx(styles.sidebar, classNames?.sidebar)}
+        >
+          <Sidebar.Main ref={scrollRef}>
+            {tree.children.map(item => (
+              <SidebarNode
+                key={item.url ?? item.name}
+                item={item}
+                pathname={pathname}
+              />
+            ))}
+          </Sidebar.Main>
+        </Sidebar>
+        <main className={cx(styles.content, classNames?.content)}>
+          {children}
+        </main>
+      </Flex>
+      <Footer config={config.footer} />
+    </Flex>
+  );
+}
+
+function SidebarNode({
+  item,
+  pathname
+}: {
+  item: PageTreeItem;
+  pathname: string;
+}) {
+  if (item.type === 'separator') {
+    return null;
+  }
+
+  if (item.type === 'folder' && item.children) {
+    return (
+      <Sidebar.Group
+        label={item.name}
+        leadingIcon={item.icon ? iconMap[item.icon] : undefined}
+        classNames={{ items: styles.groupItems }}
+      >
+        {item.children.map(child => (
+          <SidebarNode
+            key={child.url ?? child.name}
+            item={child}
+            pathname={pathname}
+          />
+        ))}
+      </Sidebar.Group>
+    );
+  }
+
+  const isActive = pathname === item.url;
+  const href = item.url ?? '#';
+  const link = useMemo(() => <RouterLink to={href} />, [href]);
+
+  return (
+    <Sidebar.Item
+      href={href}
+      active={isActive}
+      leadingIcon={item.icon ? iconMap[item.icon] : undefined}
+      as={link}
+    >
+      {item.name}
+    </Sidebar.Item>
+  );
+}

package/src/themes/default/Page.module.css

@@ -0,0 +1,46 @@
+.page {
+  gap: var(--rs-space-9);
+}
+
+.article {
+  flex: 1;
+  min-width: 0;
+  max-width: 768px;
+}
+
+.content {
+  line-height: 1.7;
+}
+
+.content h1,
+.content h2,
+.content h3,
+.content h4,
+.content h5,
+.content h6 {
+  margin-top: var(--rs-space-8);
+  margin-bottom: var(--rs-space-5);
+  line-height: 1.4;
+}
+
+.content ul,
+.content ol {
+  padding-left: var(--rs-space-5);
+  margin-bottom: var(--rs-space-5);
+}
+
+.content li {
+  font-size: var(--rs-font-size-regular);
+  margin: var(--rs-space-2) 0;
+}
+
+.content [role="tablist"] {
+  margin-bottom: var(--rs-space-3);
+}
+
+.content table {
+  display: block;
+  max-width: 100%;
+  overflow-x: auto;
+  margin-bottom: var(--rs-space-5);
+}

package/src/themes/default/Page.tsx

@@ -0,0 +1,19 @@
+'use client';
+
+import { Flex } from '@raystack/apsara';
+import { Breadcrumbs } from '@/components/ui/breadcrumbs';
+import type { ThemePageProps } from '@/types';
+import styles from './Page.module.css';
+import { Toc } from './Toc';
+
+export function Page({ page, tree }: ThemePageProps) {
+  return (
+    <Flex className={styles.page}>
+      <article className={styles.article} data-article-content>
+        <Breadcrumbs slug={page.slug} tree={tree} />
+        <div className={styles.content}>{page.content}</div>
+      </article>
+      <Toc items={page.toc} />
+    </Flex>
+  );
+}

package/src/themes/default/Toc.module.css

@@ -0,0 +1,48 @@
+.toc {
+  width: 200px;
+  flex-shrink: 0;
+  position: sticky;
+  top: var(--rs-space-9);
+  max-height: calc(100vh - var(--rs-space-17));
+  overflow-y: auto;
+}
+
+.title {
+  display: block;
+  color: var(--rs-color-foreground-base-secondary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin-bottom: var(--rs-space-3);
+  font-size: var(--rs-font-size-mini);
+}
+
+.nav {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+  border-left: 1px solid var(--rs-color-border-base-primary);
+  padding-left: var(--rs-space-3);
+  margin-bottom: var(--rs-space-6);
+}
+
+.link {
+  color: var(--rs-color-foreground-base-tertiary);
+  text-decoration: none;
+  font-size: var(--rs-font-size-small);
+  line-height: 1.4;
+  padding: var(--rs-space-1) 0;
+  transition: color 0.15s ease;
+}
+
+.link:hover {
+  color: var(--rs-color-foreground-base-primary);
+}
+
+.active {
+  color: var(--rs-color-foreground-base-primary);
+  font-weight: 500;
+}
+
+.nested {
+  padding-left: var(--rs-space-3);
+}

package/src/themes/default/Toc.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+import { Text } from '@raystack/apsara';
+import { useEffect, useState } from 'react';
+import type { TocItem } from '@/types';
+import styles from './Toc.module.css';
+
+interface TocProps {
+  items: TocItem[];
+}
+
+export function Toc({ items }: TocProps) {
+  const [activeId, setActiveId] = useState<string>('');
+
+  // Filter to only show h2 and h3 headings
+  const filteredItems = items.filter(
+    item => item.depth >= 2 && item.depth <= 3
+  );
+
+  useEffect(() => {
+    const headingIds = filteredItems.map(item => item.url.replace('#', ''));
+
+    const observer = new IntersectionObserver(
+      entries => {
+        entries.forEach(entry => {
+          if (entry.isIntersecting) {
+            setActiveId(entry.target.id);
+          }
+        });
+      },
+      // -80px top: offset for fixed header, -80% bottom: trigger when heading is in top 20% of viewport
+      { rootMargin: '-80px 0px -80% 0px' }
+    );
+
+    headingIds.forEach(id => {
+      const element = document.getElementById(id);
+      if (element) observer.observe(element);
+    });
+
+    return () => observer.disconnect();
+  }, [filteredItems]);
+
+  if (filteredItems.length === 0) return null;
+
+  return (
+    <aside className={styles.toc}>
+      <Text size={1} weight='medium' className={styles.title}>
+        On this page
+      </Text>
+      <nav className={styles.nav}>
+        {filteredItems.map(item => {
+          const id = item.url.replace('#', '');
+          const isActive = activeId === id;
+          const isNested = item.depth > 2;
+          return (
+            <a
+              key={item.url}
+              href={item.url}
+              className={`${styles.link} ${isActive ? styles.active : ''} ${isNested ? styles.nested : ''}`}
+            >
+              {item.title}
+            </a>
+          );
+        })}
+      </nav>
+    </aside>
+  );
+}