@raystack/chronicle 0.1.0-canary.30bf0df → 0.1.0-canary.49fe67c

package/src/server/api/page/[...slug].ts

@@ -0,0 +1,18 @@
+import path from 'node:path';
+import { defineHandler, HTTPError } from 'nitro';
+import { getPage } from '@/lib/source';
+
+export default defineHandler(async event => {
+  const slugParam = event.context.params?.slug ?? '';
+  const slug = slugParam ? slugParam.split('/') : [];
+  const page = await getPage(slug);
+
+  if (!page) {
+    throw new HTTPError({ status: 404, message: 'Page not found' });
+  }
+
+  const contentDir = __CHRONICLE_CONTENT_DIR__;
+  const relativePath = path.relative(contentDir, page.filePath);
+
+  return { frontmatter: page.frontmatter, relativePath };
+});

package/src/server/api/search.ts

@@ -0,0 +1,170 @@
+import fs from 'node:fs/promises';
+import matter from 'gray-matter';
+import MiniSearch from 'minisearch';
+import { defineHandler } from 'nitro';
+import type { OpenAPIV3 } from 'openapi-types';
+import path from 'node:path';
+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';
+}
+
+let searchIndex: MiniSearch<SearchDocument> | null = null;
+let cachedDocs: SearchDocument[] | null = null;
+
+function createIndex(docs: SearchDocument[]): MiniSearch<SearchDocument> {
+  const index = new MiniSearch<SearchDocument>({
+    fields: ['title', 'content'],
+    storeFields: ['url', 'title', 'type'],
+    searchOptions: {
+      boost: { title: 2 },
+      fuzzy: 0.2,
+      prefix: true
+    }
+  });
+  index.addAll(docs);
+  return index;
+}
+
+async function loadPrebuiltIndex(): Promise<SearchDocument[] | null> {
+  try {
+    const indexPath = path.resolve(__dirname, 'search-index.json');
+    const raw = await fs.readFile(indexPath, 'utf-8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function getContentDir(): string {
+  return __CHRONICLE_CONTENT_DIR__ || path.join(process.cwd(), 'content');
+}
+
+async function scanContent(): Promise<SearchDocument[]> {
+  const contentDir = getContentDir();
+  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: content.slice(0, 5000),
+          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;
+}
+
+async function loadDocuments(): Promise<SearchDocument[]> {
+  const prebuilt = await loadPrebuiltIndex();
+  if (prebuilt) return prebuilt;
+
+  const [contentDocs, apiDocs] = await Promise.all([
+    scanContent(),
+    buildApiDocs()
+  ]);
+  return [...contentDocs, ...apiDocs];
+}
+
+async function getDocs(): Promise<SearchDocument[]> {
+  if (cachedDocs) return cachedDocs;
+  cachedDocs = await loadDocuments();
+  return cachedDocs;
+}
+
+async function getIndex(): Promise<MiniSearch<SearchDocument>> {
+  if (searchIndex) return searchIndex;
+  const docs = await getDocs();
+  searchIndex = createIndex(docs);
+  return searchIndex;
+}
+
+export default defineHandler(async event => {
+  const query = event.url.searchParams.get('query') ?? '';
+  const index = await getIndex();
+
+  if (!query) {
+    const docs = await getDocs();
+    return docs
+      .filter(d => d.type === 'page')
+      .slice(0, 8)
+      .map(d => ({
+        id: d.id,
+        url: d.url,
+        type: d.type,
+        content: d.title
+      }));
+  }
+
+  return index.search(query).map(r => ({
+    id: r.id,
+    url: r.url,
+    type: r.type,
+    content: r.title
+  }));
+});

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,70 @@
+import '@vitejs/plugin-react/preamble';
+import React from 'react';
+import { hydrateRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router';
+import { mdxComponents } from '@/components/mdx';
+import { PageProvider } from '@/lib/page-context';
+import type { ChronicleConfig, Frontmatter, PageTree } 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: Frontmatter;
+  relativePath: string;
+}
+
+async function hydrate() {
+  try {
+    const embedded = (
+      window as unknown as { __PAGE_DATA__?: EmbeddedData }
+    ).__PAGE_DATA__;
+
+    const config: ChronicleConfig = embedded?.config ?? {
+      title: 'Documentation'
+    };
+    const tree: PageTree = 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 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>
+    );
+  } catch (err) {
+    console.error('Hydration failed:', err);
+  }
+}
+
+async function loadPage(
+  embedded: EmbeddedData
+): Promise<{ slug: string[]; frontmatter: Frontmatter; content: ReactNode }> {
+  const mod = await import(/* @vite-ignore */ `/.content/${embedded.relativePath}`);
+  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

@@ -0,0 +1,95 @@
+import '@raystack/apsara/normalize.css';
+import '@raystack/apsara/style.css';
+import path from 'node:path';
+import React from 'react';
+import { renderToReadableStream } from 'react-dom/server.edge';
+import { StaticRouter } from 'react-router';
+import { mdxComponents } from '@/components/mdx';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
+import { PageProvider } from '@/lib/page-context';
+import { buildPageTree, 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, sourcePage] = await Promise.all([
+      buildPageTree(),
+      getPage(slug),
+    ]);
+
+    const pageData = sourcePage
+      ? {
+          slug,
+          frontmatter: sourcePage.frontmatter,
+          content: await loadPageComponent(sourcePage).then(component =>
+            component ? React.createElement(component, { components: mdxComponents }) : null
+          ),
+        }
+      : null;
+
+    const relativePath = sourcePage
+      ? path.relative(__CHRONICLE_CONTENT_DIR__, sourcePage.filePath)
+      : 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}>
+              <PageProvider
+                initialConfig={config}
+                initialTree={tree}
+                initialPage={pageData}
+                initialApiSpecs={apiSpecs}
+              >
+                <App />
+              </PageProvider>
+            </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,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;
+}