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

package/src/lib/page-context.tsx

@@ -0,0 +1,114 @@
+import React, {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useState
+} from 'react';
+import { useLocation } from 'react-router';
+import { mdxComponents } from '@/components/mdx';
+import type { ApiSpec } from '@/lib/openapi';
+import type { ChronicleConfig, Frontmatter, PageTree } from '@/types';
+
+interface PageData {
+  slug: string[];
+  frontmatter: Frontmatter;
+  content: ReactNode;
+}
+
+interface PageContextValue {
+  config: ChronicleConfig;
+  tree: PageTree;
+  page: PageData | null;
+  apiSpecs: ApiSpec[];
+}
+
+const PageContext = createContext<PageContextValue | null>(null);
+
+export function usePageContext(): PageContextValue {
+  const ctx = useContext(PageContext);
+  if (!ctx) {
+    console.error('usePageContext: no context found!');
+    return {
+      config: { title: 'Documentation' },
+      tree: { name: 'root', children: [] },
+      page: null,
+      apiSpecs: []
+    };
+  }
+  return ctx;
+}
+
+interface PageProviderProps {
+  initialConfig: ChronicleConfig;
+  initialTree: PageTree;
+  initialPage: PageData | null;
+  initialApiSpecs: ApiSpec[];
+  children: ReactNode;
+}
+
+async function loadMdxComponent(relativePath: string): Promise<ReactNode> {
+  const mod = await import(/* @vite-ignore */ `/.content/${relativePath}`);
+  return mod.default
+    ? React.createElement(mod.default, { components: mdxComponents })
+    : null;
+}
+
+export function PageProvider({
+  initialConfig,
+  initialTree,
+  initialPage,
+  initialApiSpecs,
+  children
+}: PageProviderProps) {
+  const { pathname } = useLocation();
+  const [tree] = useState<PageTree>(initialTree);
+  const [page, setPage] = useState<PageData | null>(initialPage);
+  const [apiSpecs, setApiSpecs] = useState<ApiSpec[]>(initialApiSpecs);
+  const [currentPath, setCurrentPath] = useState(pathname);
+
+  useEffect(() => {
+    if (pathname === currentPath) return;
+    setCurrentPath(pathname);
+
+    const cancelled = { current: false };
+
+    if (pathname.startsWith('/apis')) {
+      if (apiSpecs.length === 0) {
+        fetch('/api/specs')
+          .then(res => res.json())
+          .then(specs => {
+            if (!cancelled.current) setApiSpecs(specs);
+          })
+          .catch(() => {});
+      }
+      return () => { cancelled.current = true; };
+    }
+
+    const slug = pathname === '/'
+      ? []
+      : pathname.slice(1).split('/').filter(Boolean);
+
+    const apiPath = slug.length === 0 ? '/api/page/' : `/api/page/${slug.join('/')}`;
+
+    fetch(apiPath)
+      .then(res => res.json())
+      .then(async (data: { frontmatter: Frontmatter; relativePath: string }) => {
+        if (cancelled.current) return;
+        const content = await loadMdxComponent(data.relativePath);
+        if (cancelled.current) return;
+        setPage({ slug, frontmatter: data.frontmatter, content });
+      })
+      .catch(() => {});
+
+    return () => { cancelled.current = true; };
+  }, [pathname]);
+
+  return (
+    <PageContext.Provider
+      value={{ config: initialConfig, tree, page, apiSpecs }}
+    >
+      {children}
+    </PageContext.Provider>
+  );
+}

package/src/lib/source.ts

@@ -1,67 +1,186 @@
-import { docs } from '@/.source/server'
-import { loader } from 'fumadocs-core/source'
-import type { PageTree, PageTreeItem, Frontmatter } from '@/types'
-
-export const source = loader({
-  baseUrl: '/',
-  source: docs.toFumadocsSource(),
-})
-
-export function sortByOrder<T extends { frontmatter?: Frontmatter }>(
-  items: T[]
-): T[] {
-  return [...items].sort((a, b) => {
-    const orderA = a.frontmatter?.order ?? Number.MAX_SAFE_INTEGER
-    const orderB = b.frontmatter?.order ?? Number.MAX_SAFE_INTEGER
-    return orderA - orderB
-  })
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loader } from 'fumadocs-core/source';
+import matter from 'gray-matter';
+import type { MDXContent } from 'mdx/types';
+import type { Frontmatter, PageTree, PageTreeItem } from '@/types';
+
+export interface SourcePage {
+  url: string;
+  slugs: string[];
+  filePath: string;
+  frontmatter: Frontmatter;
+}
+
+function getContentDir(): string {
+  return __CHRONICLE_CONTENT_DIR__ || path.join(process.cwd(), 'content');
+}
+
+async function scanFiles(contentDir: string) {
+  const files: {
+    type: 'page' | 'meta';
+    path: string;
+    data: Record<string, unknown>;
+  }[] = [];
+
+  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);
+        const relativePath = [...prefix, entry.name].join('/');
+
+        if (entry.isDirectory()) {
+          await scan(fullPath, [...prefix, entry.name]);
+          continue;
+        }
+
+        if (entry.name.endsWith('.mdx') || entry.name.endsWith('.md')) {
+          const raw = await fs.readFile(fullPath, 'utf-8');
+          const { data } = matter(raw);
+          files.push({
+            type: 'page',
+            path: relativePath,
+            data: { ...data, _absolutePath: fullPath }
+          });
+        } else if (entry.name === 'meta.json' || entry.name === 'meta.yaml') {
+          const raw = await fs.readFile(fullPath, 'utf-8');
+          const data = entry.name.endsWith('.json')
+            ? JSON.parse(raw)
+            : matter(raw).data;
+          files.push({ type: 'meta', path: relativePath, data });
+        }
+      }
+    } catch {
+      /* directory not readable */
+    }
+  }
+
+  await scan(contentDir);
+  return files;
 }
 
-export function buildPageTree(): PageTree {
-  const pages = source.getPages()
-  const folders = new Map<string, PageTreeItem[]>()
-  const rootPages: PageTreeItem[] = []
+let cachedSource: ReturnType<typeof loader> | null = null;
+let cachedPages: SourcePage[] | null = null;
 
-  pages.forEach((page) => {
-    const data = page.data as { title?: string; order?: number }
-    const isIndex = page.url === '/'
+async function getSource() {
+  if (cachedSource) return cachedSource;
+  const contentDir = getContentDir();
+  const files = await scanFiles(contentDir);
+  cachedSource = loader({
+    source: { files },
+    baseUrl: '/'
+  });
+  return cachedSource;
+}
+
+export function invalidate() {
+  cachedSource = null;
+  cachedPages = null;
+}
+
+export async function getPages(): Promise<SourcePage[]> {
+  if (cachedPages) return cachedPages;
+
+  const s = await getSource();
+  cachedPages = s.getPages().map(page => {
+    const data = page.data as Record<string, unknown>;
+    return {
+      url: page.url,
+      slugs: page.slugs,
+      filePath: (data._absolutePath as string) ?? '',
+      frontmatter: {
+        title:
+          (data.title as string) ??
+          page.slugs[page.slugs.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
+      }
+    };
+  });
+
+  return cachedPages;
+}
+
+export async function getPage(slug?: string[]): Promise<SourcePage | null> {
+  const pages = await getPages();
+  const targetUrl = !slug || slug.length === 0 ? '/' : `/${slug.join('/')}`;
+  return pages.find(p => p.url === targetUrl) ?? null;
+}
+
+export async function loadPageComponent(
+  page: SourcePage
+): Promise<MDXContent | null> {
+  if (!page.filePath) return null;
+  try {
+    await fs.access(page.filePath);
+  } catch {
+    return null;
+  }
+  const contentDir = getContentDir();
+  const relativePath = path.relative(contentDir, page.filePath);
+  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
+  const mod = relativePath.endsWith('.md')
+    ? await import(`@content/${withoutExt}.md`)
+    : await import(`@content/${withoutExt}.mdx`);
+  return mod.default;
+}
+
+export async function buildPageTree(): Promise<PageTree> {
+  const s = await getSource();
+  const pages = s.getPages();
+  const folders = new Map<string, PageTreeItem[]>();
+  const rootPages: PageTreeItem[] = [];
+
+  for (const page of pages) {
+    const data = page.data as Record<string, unknown>;
+    const isIndex = page.url === '/';
     const item: PageTreeItem = {
       type: 'page',
-      name: data.title ?? page.slugs.join('/') ?? 'Untitled',
+      name: (data.title as string) ?? page.slugs.join('/') ?? 'Untitled',
       url: page.url,
-      order: data.order ?? (isIndex ? 0 : undefined),
-    }
+      order: (data.order as number | undefined) ?? (isIndex ? 0 : undefined)
+    };
 
     if (page.slugs.length > 1) {
-      const folder = page.slugs[0]
+      const folder = page.slugs[0];
       if (!folders.has(folder)) {
-        folders.set(folder, [])
+        folders.set(folder, []);
       }
-      folders.get(folder)?.push(item)
+      folders.get(folder)?.push(item);
     } else {
-      rootPages.push(item)
+      rootPages.push(item);
     }
-  })
+  }
 
   const sortByOrder = (items: PageTreeItem[]) =>
-    items.sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER))
+    items.sort(
+      (a, b) =>
+        (a.order ?? Number.MAX_SAFE_INTEGER) -
+        (b.order ?? Number.MAX_SAFE_INTEGER)
+    );
 
-  const children: PageTreeItem[] = sortByOrder(rootPages)
+  const children: PageTreeItem[] = sortByOrder(rootPages);
 
-  const folderItems: PageTreeItem[] = []
-  folders.forEach((items, folder) => {
-    const sorted = sortByOrder(items)
-    const indexPage = items.find(item => item.url === `/${folder}`)
-    const folderOrder = indexPage?.order ?? sorted[0]?.order
+  const folderItems: PageTreeItem[] = [];
+  for (const [folder, items] of folders) {
+    const sorted = sortByOrder(items);
+    const indexPage = items.find(item => item.url === `/${folder}`);
+    const folderOrder = indexPage?.order ?? sorted[0]?.order;
     folderItems.push({
       type: 'folder',
-      name: folder.charAt(0).toUpperCase() + folder.slice(1),
+      name: `${folder.charAt(0).toUpperCase()}${folder.slice(1)}`,
       order: folderOrder,
-      children: sorted,
-    })
-  })
+      children: sorted
+    });
+  }
 
-  children.push(...sortByOrder(folderItems))
+  children.push(...sortByOrder(folderItems));
 
-  return { name: 'root', children }
+  return { name: 'root', children };
 }

package/src/pages/ApiLayout.tsx

@@ -0,0 +1,33 @@
+import { cx } from 'class-variance-authority';
+import type { ReactNode } from 'react';
+import { Search } from '@/components/ui/search';
+import { buildApiPageTree } from '@/lib/api-routes';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+import styles from './ApiLayout.module.css';
+
+interface ApiLayoutProps {
+  children: ReactNode;
+}
+
+export function ApiLayout({ children }: ApiLayoutProps) {
+  const { config, apiSpecs } = usePageContext();
+  const { Layout, className } = getTheme(config.theme?.name);
+  const tree = buildApiPageTree(apiSpecs);
+
+  return (
+    <Layout
+      config={config}
+      tree={tree}
+      classNames={{
+        layout: cx(styles.layout, className),
+        body: styles.body,
+        sidebar: styles.sidebar,
+        content: styles.content
+      }}
+    >
+      <Search className={styles.hiddenSearch} />
+      {children}
+    </Layout>
+  );
+}

package/src/pages/ApiPage.tsx

@@ -0,0 +1,73 @@
+import { Flex, Headline, Text } from '@raystack/apsara';
+import type { OpenAPIV3 } from 'openapi-types';
+import { EndpointPage } from '@/components/api';
+import { findApiOperation } from '@/lib/api-routes';
+import { Head } from '@/lib/head';
+import type { ApiSpec } from '@/lib/openapi';
+import { usePageContext } from '@/lib/page-context';
+
+interface ApiPageProps {
+  slug: string[];
+}
+
+export function ApiPage({ slug }: ApiPageProps) {
+  const { config, apiSpecs } = usePageContext();
+
+  if (slug.length === 0) {
+    return (
+      <>
+        <Head
+          title='API Reference'
+          description={`API documentation for ${config.title}`}
+          config={config}
+        />
+        <ApiLanding specs={apiSpecs} />
+      </>
+    );
+  }
+
+  const match = findApiOperation(apiSpecs, slug);
+  if (!match) return null;
+
+  const operation = match.operation as OpenAPIV3.OperationObject;
+  const title =
+    operation.summary ?? `${match.method.toUpperCase()} ${match.path}`;
+
+  return (
+    <>
+      <Head title={title} description={operation.description} config={config} />
+      <EndpointPage
+        method={match.method}
+        path={match.path}
+        operation={match.operation}
+        serverUrl={match.spec.server.url}
+        specName={match.spec.name}
+        auth={match.spec.auth}
+      />
+    </>
+  );
+}
+
+function ApiLanding({ specs }: { specs: ApiSpec[] }) {
+  return (
+    <Flex
+      direction='column'
+      gap='large'
+      style={{ padding: 'var(--rs-space-7)' }}
+    >
+      <Headline size='medium' as='h1'>
+        API Reference
+      </Headline>
+      {specs.map(spec => (
+        <Flex key={spec.name} direction='column' gap='small'>
+          <Headline size='small' as='h2'>
+            {spec.name}
+          </Headline>
+          {spec.document.info.description && (
+            <Text size={3}>{spec.document.info.description}</Text>
+          )}
+        </Flex>
+      ))}
+    </Flex>
+  );
+}

package/src/pages/DocsLayout.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+
+interface DocsLayoutProps {
+  children: ReactNode;
+}
+
+export function DocsLayout({ children }: DocsLayoutProps) {
+  const { config, tree } = usePageContext();
+  const { Layout, className } = getTheme(config.theme?.name);
+
+  return (
+    <Layout config={config} tree={tree} classNames={{ layout: className }}>
+      {children}
+    </Layout>
+  );
+}

package/src/pages/DocsPage.tsx

@@ -0,0 +1,43 @@
+import { Head } from '@/lib/head';
+import { usePageContext } from '@/lib/page-context';
+import { getTheme } from '@/themes/registry';
+
+interface DocsPageProps {
+  slug: string[];
+}
+
+export function DocsPage({ slug }: DocsPageProps) {
+  const { config, tree, page } = usePageContext();
+
+  if (!page) return null;
+
+  const { Page } = getTheme(config.theme?.name);
+  const pageUrl = config.url ? `${config.url}/${slug.join('/')}` : undefined;
+
+  return (
+    <>
+      <Head
+        title={page.frontmatter.title}
+        description={page.frontmatter.description}
+        config={config}
+        jsonLd={{
+          '@context': 'https://schema.org',
+          '@type': 'Article',
+          headline: page.frontmatter.title,
+          description: page.frontmatter.description,
+          ...(pageUrl && { url: pageUrl })
+        }}
+      />
+      <Page
+        page={{
+          slug,
+          frontmatter: page.frontmatter,
+          content: page.content,
+          toc: []
+        }}
+        config={config}
+        tree={tree}
+      />
+    </>
+  );
+}

package/src/pages/NotFound.tsx

@@ -0,0 +1,17 @@
+import { Flex, Headline, Text } from '@raystack/apsara';
+
+export function NotFound() {
+  return (
+    <Flex
+      direction='column'
+      align='center'
+      justify='center'
+      style={{ minHeight: '60vh' }}
+    >
+      <Headline size='large' as='h1'>
+        404
+      </Headline>
+      <Text size={3}>Page not found</Text>
+    </Flex>
+  );
+}

package/src/server/App.tsx

@@ -0,0 +1,67 @@
+import '@raystack/apsara/normalize.css';
+import '@raystack/apsara/style.css';
+import { ThemeProvider } from '@raystack/apsara';
+import { useLocation } from 'react-router';
+import { Head } from '@/lib/head';
+import { usePageContext } from '@/lib/page-context';
+import { ApiLayout } from '@/pages/ApiLayout';
+import { ApiPage } from '@/pages/ApiPage';
+import { DocsLayout } from '@/pages/DocsLayout';
+import { DocsPage } from '@/pages/DocsPage';
+import type { ChronicleConfig } from '@/types';
+
+function resolveRoute(pathname: string) {
+  if (pathname.startsWith('/apis')) {
+    const slug = pathname
+      .replace(/^\/apis\/?/, '')
+      .split('/')
+      .filter(Boolean);
+    return { type: 'api' as const, slug };
+  }
+
+  const slug =
+    pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean);
+  return { type: 'docs' as const, slug };
+}
+
+export function App() {
+  const { pathname } = useLocation();
+  const { config } = usePageContext();
+  const route = resolveRoute(pathname);
+
+  return (
+    <ThemeProvider enableSystem>
+      <RootHead config={config} />
+      {route.type === 'api' ? (
+        <ApiLayout>
+          <ApiPage slug={route.slug} />
+        </ApiLayout>
+      ) : (
+        <DocsLayout>
+          <DocsPage slug={route.slug} />
+        </DocsLayout>
+      )}
+    </ThemeProvider>
+  );
+}
+
+function RootHead({ config }: { config: ChronicleConfig }) {
+  return (
+    <Head
+      title={config.title}
+      description={config.description}
+      config={config}
+      jsonLd={
+        config.url
+          ? {
+              '@context': 'https://schema.org',
+              '@type': 'WebSite',
+              name: config.title,
+              description: config.description,
+              url: config.url
+            }
+          : undefined
+      }
+    />
+  );
+}

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' };
+});