@raystack/chronicle 0.1.0-canary.5a730d4 → 0.1.0-canary.67113f8

package/src/server/api/apis-proxy.ts

@@ -0,0 +1,69 @@
+import { defineHandler, HTTPError } from 'nitro';
+import { loadConfig } from '@/lib/config';
+import { loadApiSpecs } from '@/lib/openapi';
+
+interface ProxyRequest {
+  specName: string;
+  method: string;
+  path: string;
+  headers?: Record<string, string>;
+  body?: unknown;
+}
+
+export default defineHandler(async event => {
+  if (event.req.method !== 'POST') {
+    throw new HTTPError({ status: 405, message: 'Method not allowed' });
+  }
+
+  const { specName, method, path, headers, body } =
+    (await event.req.json()) as ProxyRequest;
+
+  if (!specName || !method || !path) {
+    throw new HTTPError({
+      status: 400,
+      message: 'Missing specName, method, or path'
+    });
+  }
+
+  const config = loadConfig();
+  const specs = await loadApiSpecs(config.api ?? []);
+  const spec = specs.find(s => s.name === specName);
+
+  if (!spec) {
+    throw new HTTPError({ status: 404, message: `Unknown spec: ${specName}` });
+  }
+
+  if (/^[a-z]+:\/\//i.test(path) || path.includes('..')) {
+    throw new HTTPError({ status: 400, message: 'Invalid path' });
+  }
+
+  const url = spec.server.url + path;
+
+  try {
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined
+    });
+
+    const contentType = response.headers.get('content-type') ?? '';
+    const responseBody = contentType.includes('application/json')
+      ? await response.json()
+      : await response.text();
+
+    return {
+      status: response.status,
+      statusText: response.statusText,
+      body: responseBody
+    };
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? `${error.message}${error.cause ? `: ${(error.cause as Error).message}` : ''}`
+        : 'Request failed';
+    throw new HTTPError({
+      status: 502,
+      message: `Could not reach ${url}\n${message}`
+    });
+  }
+});

package/src/server/api/health.ts

@@ -0,0 +1,5 @@
+import { defineHandler } from 'nitro';
+
+export default defineHandler(() => {
+  return { status: 'ok' };
+});

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

@@ -0,0 +1,17 @@
+import { defineHandler, HTTPError } from 'nitro';
+import { getPage, extractFrontmatter, getRelativePath } 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' });
+  }
+
+  return {
+    frontmatter: extractFrontmatter(page, slug[slug.length - 1]),
+    relativePath: getRelativePath(page),
+  };
+});

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

@@ -1,74 +1,66 @@
-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 { hydrateRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router';
+import { ReactRouterProvider } from 'fumadocs-core/framework/react-router';
+import { loadMdxModule } from '@/lib/mdx-loader';
+import { PageProvider } from '@/lib/page-context';
+import type { ChronicleConfig, Frontmatter, Root } from '@/types';
+import type { ApiSpec } from '@/lib/openapi';
+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 = {
+    const page = embedded?.relativePath
+      ? {
           slug: embedded.slug,
           frontmatter: embedded.frontmatter,
-          content: null,
+          ...(await loadMdxModule(embedded.relativePath)),
         }
-      }
-    } else {
-      tree = await buildPageTree()
-    }
+      : 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}
+            loadMdx={loadMdxModule}
+          >
+            <App />
+          </PageProvider>
+        </ReactRouterProvider>
+      </BrowserRouter>
+    );
   } catch (err) {
-    console.error('Hydration failed:', err)
+    console.error('Hydration failed:', err);
   }
 }
 
-hydrate()
+hydrate();

package/src/server/entry-server.tsx

@@ -1,35 +1,100 @@
-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, loadPageModule, extractFrontmatter, getRelativePath } 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 mdxModule = relativePath ? await loadPageModule(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,
+    };
+    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' },
+    });
+  },
+};