@raystack/chronicle 0.1.0-canary.111b55a → 0.1.0-canary.1e5fdae

package/src/lib/config.ts

@@ -1,56 +1,58 @@
-import fs from 'fs'
-import path from 'path'
-import { parse } from 'yaml'
-import type { ChronicleConfig } from '@/types'
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'yaml';
+import type { ChronicleConfig } from '@/types';
 
-const CONFIG_FILE = 'chronicle.yaml'
+const CONFIG_FILE = 'chronicle.yaml';
 
 const defaultConfig: ChronicleConfig = {
   title: 'Documentation',
   theme: { name: 'default' },
-  search: { enabled: true, placeholder: 'Search...' },
-}
+  search: { enabled: true, placeholder: 'Search...' }
+};
 
 function resolveConfigPath(): string | null {
-  // Check project root via env var
-  const projectRoot = process.env.CHRONICLE_PROJECT_ROOT
-  if (projectRoot) {
-    const rootPath = path.join(projectRoot, CONFIG_FILE)
-    if (fs.existsSync(rootPath)) return rootPath
-  }
-  // Check cwd
-  const cwdPath = path.join(process.cwd(), CONFIG_FILE)
-  if (fs.existsSync(cwdPath)) return cwdPath
-  // Check content dir
-  const contentDir = process.env.CHRONICLE_CONTENT_DIR
+  const projectRoot =
+    typeof __CHRONICLE_PROJECT_ROOT__ !== 'undefined'
+      ? __CHRONICLE_PROJECT_ROOT__
+      : process.cwd();
+
+  const rootPath = path.join(projectRoot, CONFIG_FILE);
+  if (fs.existsSync(rootPath)) return rootPath;
+
+  const contentDir =
+    typeof __CHRONICLE_CONTENT_DIR__ !== 'undefined'
+      ? __CHRONICLE_CONTENT_DIR__
+      : undefined;
   if (contentDir) {
-    const contentPath = path.join(contentDir, CONFIG_FILE)
-    if (fs.existsSync(contentPath)) return contentPath
+    const contentPath = path.join(contentDir, CONFIG_FILE);
+    if (fs.existsSync(contentPath)) return contentPath;
   }
-  return null
+
+  return null;
 }
 
 export function loadConfig(): ChronicleConfig {
-  const configPath = resolveConfigPath()
+  const configPath = resolveConfigPath();
 
   if (!configPath) {
-    return defaultConfig
+    return defaultConfig;
   }
 
-  const raw = fs.readFileSync(configPath, 'utf-8')
-  const userConfig = parse(raw) as Partial<ChronicleConfig>
+  const raw = fs.readFileSync(configPath, 'utf-8');
+  const userConfig = parse(raw) as Partial<ChronicleConfig>;
 
   return {
     ...defaultConfig,
     ...userConfig,
     theme: {
       name: userConfig.theme?.name ?? defaultConfig.theme!.name,
-      colors: { ...defaultConfig.theme?.colors, ...userConfig.theme?.colors },
+      colors: { ...defaultConfig.theme?.colors, ...userConfig.theme?.colors }
     },
     search: { ...defaultConfig.search, ...userConfig.search },
     footer: userConfig.footer,
     api: userConfig.api,
     llms: { enabled: false, ...userConfig.llms },
-    analytics: { enabled: false, ...userConfig.analytics },
-  }
-}
+    analytics: { enabled: false, ...userConfig.analytics }
+  };
+}

package/src/lib/get-llm-text.ts

@@ -0,0 +1,10 @@
+import { source } from '@/lib/source'
+import type { InferPageType } from 'fumadocs-core/source'
+
+export async function getLLMText(page: InferPageType<typeof source>) {
+  const processed = await page.data.getText('processed')
+
+  return `# ${page.data.title} (${page.url})
+
+${processed}`
+}

package/src/lib/head.tsx

@@ -1,45 +1,49 @@
-import type { ChronicleConfig } from '@/types'
+import type { ChronicleConfig } from '@/types';
 
 export interface HeadProps {
-  title: string
-  description?: string
-  config: ChronicleConfig
-  jsonLd?: Record<string, unknown>
+  title: string;
+  description?: string;
+  config: ChronicleConfig;
+  jsonLd?: Record<string, unknown>;
 }
 
 export function Head({ title, description, config, jsonLd }: HeadProps) {
-  const fullTitle = `${title} | ${config.title}`
-  const ogParams = new URLSearchParams({ title })
-  if (description) ogParams.set('description', description)
+  const fullTitle = `${title} | ${config.title}`;
+  const ogParams = new URLSearchParams({ title });
+  if (description) ogParams.set('description', description);
 
   return (
     <>
       <title>{fullTitle}</title>
-      {description && <meta name="description" content={description} />}
+      {description && <meta name='description' content={description} />}
 
       {config.url && (
         <>
-          <meta property="og:title" content={title} />
-          {description && <meta property="og:description" content={description} />}
-          <meta property="og:site_name" content={config.title} />
-          <meta property="og:type" content="website" />
-          <meta property="og:image" content={`/og?${ogParams.toString()}`} />
-          <meta property="og:image:width" content="1200" />
-          <meta property="og:image:height" content="630" />
+          <meta property='og:title' content={title} />
+          {description && (
+            <meta property='og:description' content={description} />
+          )}
+          <meta property='og:site_name' content={config.title} />
+          <meta property='og:type' content='website' />
+          <meta property='og:image' content={`/og?${ogParams.toString()}`} />
+          <meta property='og:image:width' content='1200' />
+          <meta property='og:image:height' content='630' />
 
-          <meta name="twitter:card" content="summary_large_image" />
-          <meta name="twitter:title" content={title} />
-          {description && <meta name="twitter:description" content={description} />}
-          <meta name="twitter:image" content={`/og?${ogParams.toString()}`} />
+          <meta name='twitter:card' content='summary_large_image' />
+          <meta name='twitter:title' content={title} />
+          {description && (
+            <meta name='twitter:description' content={description} />
+          )}
+          <meta name='twitter:image' content={`/og?${ogParams.toString()}`} />
         </>
       )}
 
       {jsonLd && (
         <script
-          type="application/ld+json"
+          type='application/ld+json'
           dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd, null, 2) }}
         />
       )}
     </>
-  )
+  );
 }

package/src/lib/openapi.ts

@@ -1,5 +1,5 @@
-import fs from 'fs'
-import path from 'path'
+import fs from 'node:fs/promises'
+import path from 'node:path'
 import { parse as parseYaml } from 'yaml'
 import type { OpenAPIV2, OpenAPIV3 } from 'openapi-types'
 import type { ApiConfig, ApiServerConfig, ApiAuthConfig } from '@/types/config'
@@ -17,14 +17,14 @@ export interface ApiSpec {
 export type { SchemaField } from './schema'
 export { flattenSchema } from './schema'
 
-export function loadApiSpecs(apiConfigs: ApiConfig[]): ApiSpec[] {
-  const contentDir = process.env.CHRONICLE_CONTENT_DIR ?? process.cwd()
-  return apiConfigs.map((config) => loadApiSpec(config, contentDir))
+export async function loadApiSpecs(apiConfigs: ApiConfig[]): Promise<ApiSpec[]> {
+  const projectRoot = typeof __CHRONICLE_PROJECT_ROOT__ !== 'undefined' ? __CHRONICLE_PROJECT_ROOT__ : process.cwd()
+  return Promise.all(apiConfigs.map((config) => loadApiSpec(config, projectRoot)))
 }
 
-export function loadApiSpec(config: ApiConfig, contentDir: string): ApiSpec {
-  const specPath = path.resolve(contentDir, config.spec)
-  const raw = fs.readFileSync(specPath, 'utf-8')
+export async function loadApiSpec(config: ApiConfig, projectRoot: string): Promise<ApiSpec> {
+  const specPath = path.resolve(projectRoot, config.spec)
+  const raw = await fs.readFile(specPath, 'utf-8')
   const isYaml = specPath.endsWith('.yaml') || specPath.endsWith('.yml')
   const doc = (isYaml ? parseYaml(raw) : JSON.parse(raw)) as OpenAPIV2.Document | OpenAPIV3.Document
 

package/src/lib/page-context.tsx

@@ -1,95 +1,111 @@
-import { createContext, useContext, useState, useEffect, type ReactNode } from 'react'
-import { useLocation } from 'react-router-dom'
-import type { ChronicleConfig, Frontmatter, PageTree } from '@/types'
-import type { ApiSpec } from '@/lib/openapi'
-import { getPage, loadPageComponent, buildPageTree } from '@/lib/source'
-import { mdxComponents } from '@/components/mdx'
-import React from 'react'
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useState
+} from 'react';
+import { useLocation } from 'react-router';
+import type { ApiSpec } from '@/lib/openapi';
+import type { ChronicleConfig, Frontmatter, Root, TableOfContents } from '@/types';
+
+export type MdxLoader = (relativePath: string) => Promise<{ content: ReactNode; toc: TableOfContents }>;
 
 interface PageData {
-  slug: string[]
-  frontmatter: Frontmatter
-  content: ReactNode
+  slug: string[];
+  frontmatter: Frontmatter;
+  content: ReactNode;
+  toc: TableOfContents;
 }
 
 interface PageContextValue {
-  config: ChronicleConfig
-  tree: PageTree
-  page: PageData | null
-  apiSpecs: ApiSpec[]
+  config: ChronicleConfig;
+  tree: Root;
+  page: PageData | null;
+  apiSpecs: ApiSpec[];
 }
 
-const PageContext = createContext<PageContextValue | null>(null)
+const PageContext = createContext<PageContextValue | null>(null);
 
 export function usePageContext(): PageContextValue {
-  const ctx = useContext(PageContext)
+  const ctx = useContext(PageContext);
   if (!ctx) {
-    console.error('usePageContext: no context found!')
+    console.error('usePageContext: no context found!');
     return {
       config: { title: 'Documentation' },
-      tree: { name: 'root', children: [] },
+      tree: { name: 'root', children: [] } as Root,
       page: null,
-      apiSpecs: [],
-    }
+      apiSpecs: []
+    };
   }
-  return ctx
+  return ctx;
 }
 
 interface PageProviderProps {
-  initialConfig: ChronicleConfig
-  initialTree: PageTree
-  initialPage: PageData | null
-  initialApiSpecs: ApiSpec[]
-  children: ReactNode
+  initialConfig: ChronicleConfig;
+  initialTree: Root;
+  initialPage: PageData | null;
+  initialApiSpecs: ApiSpec[];
+  loadMdx: MdxLoader;
+  children: ReactNode;
 }
 
-export function PageProvider({ initialConfig, initialTree, initialPage, initialApiSpecs, children }: PageProviderProps) {
-  const { pathname } = useLocation()
-  const [tree, setTree] = useState<PageTree>(initialTree)
-  const [page, setPage] = useState<PageData | null>(initialPage)
-  const [apiSpecs, setApiSpecs] = useState<ApiSpec[]>(initialApiSpecs)
-  const [currentPath, setCurrentPath] = useState(pathname)
+export function PageProvider({
+  initialConfig,
+  initialTree,
+  initialPage,
+  initialApiSpecs,
+  loadMdx,
+  children
+}: PageProviderProps) {
+  const { pathname } = useLocation();
+  const [tree] = useState<Root>(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)
+    if (pathname === currentPath) return;
+    setCurrentPath(pathname);
 
-    let cancelled = false
+    const cancelled = { current: false };
 
     if (pathname.startsWith('/apis')) {
-      // Fetch API specs if not already loaded
       if (apiSpecs.length === 0) {
         fetch('/api/specs')
-          .then((res) => res.json())
-          .then((specs) => { if (!cancelled) setApiSpecs(specs) })
-          .catch(() => {})
+          .then(res => res.json())
+          .then(specs => {
+            if (!cancelled.current) setApiSpecs(specs);
+          })
+          .catch(() => {});
       }
-      return () => { cancelled = true }
+      return () => { cancelled.current = true; };
     }
 
-    async function load() {
-      const slug = pathname === '/' ? [] : pathname.slice(1).split('/').filter(Boolean)
-
-      const [sourcePage, newTree] = await Promise.all([getPage(slug), buildPageTree()])
-      if (cancelled || !sourcePage) return
+    const slug = pathname === '/'
+      ? []
+      : pathname.slice(1).split('/').filter(Boolean);
 
-      const component = await loadPageComponent(sourcePage)
-      if (cancelled) return
+    const apiPath = slug.length === 0 ? '/api/page/' : `/api/page/${slug.join('/')}`;
 
-      setTree(newTree)
-      setPage({
-        slug,
-        frontmatter: sourcePage.frontmatter,
-        content: component ? React.createElement(component, { components: mdxComponents }) : null,
+    fetch(apiPath)
+      .then(res => res.json())
+      .then(async (data: { frontmatter: Frontmatter; relativePath: string }) => {
+        if (cancelled.current) return;
+        const { content, toc } = await loadMdx(data.relativePath);
+        if (cancelled.current) return;
+        setPage({ slug, frontmatter: data.frontmatter, content, toc });
       })
-    }
-    load()
-    return () => { cancelled = true }
-  }, [pathname])
+      .catch(() => {});
+
+    return () => { cancelled.current = true; };
+  }, [pathname]);
 
   return (
-    <PageContext.Provider value={{ config: initialConfig, tree, page, apiSpecs }}>
+    <PageContext.Provider
+      value={{ config: initialConfig, tree, page, apiSpecs }}
+    >
       {children}
     </PageContext.Provider>
-  )
+  );
 }

package/src/lib/source.ts

@@ -1,138 +1,160 @@
-import type { MDXContent } from 'mdx/types'
-import type { Frontmatter, PageTree, PageTreeItem } from '@/types'
-
-const meta: Record<string, Frontmatter> = import.meta.glob(
-  '@content/**/*.{mdx,md}',
-  { eager: true, import: 'frontmatter' }
-)
-
-const loaders: Record<string, () => Promise<{ default: MDXContent }>> = import.meta.glob(
-  '@content/**/*.{mdx,md}'
-)
-
-export interface SourcePage {
-  url: string
-  slugs: string[]
-  filePath: string
-  frontmatter: Frontmatter
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loader } from 'fumadocs-core/source';
+import type { Root, Node, Folder } from 'fumadocs-core/page-tree';
+import matter from 'gray-matter';
+import type { MDXContent } from 'mdx/types';
+import type { TableOfContents } from 'fumadocs-core/toc';
+import type { Frontmatter } from '@/types';
+
+function getContentDir(): string {
+  return __CHRONICLE_CONTENT_DIR__ || path.join(process.cwd(), 'content');
 }
 
-// Compute common directory prefix of all glob keys once
-function computePrefix(keys: string[]): string {
-  if (keys.length === 0) return ''
-  const dirs = keys.map((k) => k.split('/').slice(0, -1)) // drop filename
-  const first = dirs[0]
-  let depth = 0
-  for (let i = 0; i < first.length; i++) {
-    if (dirs.every((d) => d[i] === first[i])) {
-      depth = i + 1
-    } else {
-      break
+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, _relativePath: relativePath }
+          });
+        } else if (entry.name === 'meta.json' || entry.name === 'meta.yaml') {
+          try {
+            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 {
+            /* malformed meta file */
+          }
+        }
+      }
+    } catch {
+      /* directory not readable */
     }
   }
-  return first.slice(0, depth).join('/') + '/'
-}
 
-const prefix = computePrefix(Object.keys(meta))
-
-function filePathToSlugs(filePath: string): string[] {
-  const relative = filePath.slice(prefix.length)
-  const withoutExt = relative.replace(/\.(mdx|md)$/, '')
-  const parts = withoutExt.split('/').filter(Boolean)
-  if (parts[parts.length - 1] === 'index') parts.pop()
-  return parts
+  await scan(contentDir);
+  return files;
 }
 
-function slugsToUrl(slugs: string[]): string {
-  return slugs.length === 0 ? '/' : '/' + slugs.join('/')
+let cachedSource: ReturnType<typeof loader> | null = null;
+
+async function getSource() {
+  if (cachedSource) return cachedSource;
+  const contentDir = getContentDir();
+  const files = await scanFiles(contentDir);
+  cachedSource = loader({
+    source: { files },
+    baseUrl: '/'
+  });
+  return cachedSource;
 }
 
-let cachedPages: SourcePage[] | null = null
-
-export async function getPages(): Promise<SourcePage[]> {
-  if (cachedPages) return cachedPages
-
-  cachedPages = Object.entries(meta).map(([filePath, fm]) => {
-    const slugs = filePathToSlugs(filePath)
-    const baseName = slugs[slugs.length - 1] ?? 'index'
-    return {
-      url: slugsToUrl(slugs),
-      slugs,
-      filePath,
-      frontmatter: {
-        title: fm?.title ?? baseName,
-        description: fm?.description,
-        order: fm?.order,
-        icon: fm?.icon,
-        lastModified: fm?.lastModified,
-      },
-    }
-  })
+export { getSource as source };
 
-  return cachedPages
+export function invalidate() {
+  cachedSource = null;
 }
 
-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
+function getOrder(node: Node, orderMap: Map<string, number>): number | undefined {
+  if (node.type === 'page') return orderMap.get(node.url);
+  if (node.type === 'folder' && node.index) return orderMap.get(node.index.url);
+  return undefined;
 }
 
-export async function loadPageComponent(page: SourcePage): Promise<MDXContent | null> {
-  const loader = loaders[page.filePath]
-  if (!loader) return null
-  const mod = await loader()
-  return mod.default
+function sortNodes(nodes: Node[], orderMap: Map<string, number>): Node[] {
+  return [...nodes]
+    .map(n =>
+      n.type === 'folder'
+        ? ({ ...n, children: sortNodes(n.children, orderMap) } as Folder)
+        : n
+    )
+    .sort(
+      (a, b) =>
+        (getOrder(a, orderMap) ?? Number.MAX_SAFE_INTEGER) -
+        (getOrder(b, orderMap) ?? Number.MAX_SAFE_INTEGER)
+    );
 }
 
-export function invalidate() {
-  cachedPages = null
+function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[]): Root {
+  const orderMap = new Map<string, number>();
+  for (const page of pages) {
+    const d = page.data as Record<string, unknown>;
+    const order = d.order as number | undefined;
+    if (order !== undefined) orderMap.set(page.url, order);
+    if (page.url === '/') orderMap.set('/', order ?? 0);
+  }
+  return { ...tree, children: sortNodes(tree.children, orderMap) };
 }
 
-export async function buildPageTree(): Promise<PageTree> {
-  const pages = await getPages()
-  const folders = new Map<string, PageTreeItem[]>()
-  const rootPages: PageTreeItem[] = []
-
-  pages.forEach((page) => {
-    const isIndex = page.url === '/'
-    const item: PageTreeItem = {
-      type: 'page',
-      name: page.frontmatter.title,
-      url: page.url,
-      order: page.frontmatter.order ?? (isIndex ? 0 : undefined),
-    }
-
-    if (page.slugs.length > 1) {
-      const folder = page.slugs[0]
-      if (!folders.has(folder)) {
-        folders.set(folder, [])
-      }
-      folders.get(folder)?.push(item)
-    } else {
-      rootPages.push(item)
-    }
-  })
+export async function getPageTree(): Promise<Root> {
+  const s = await getSource();
+  return sortTreeByOrder(s.pageTree as Root, s.getPages());
+}
 
-  const sortByOrder = (items: PageTreeItem[]) =>
-    items.sort((a, b) => (a.order ?? Number.MAX_SAFE_INTEGER) - (b.order ?? Number.MAX_SAFE_INTEGER))
+export async function getPages() {
+  const s = await getSource();
+  return s.getPages();
+}
 
-  const children: PageTreeItem[] = sortByOrder(rootPages)
+export async function getPage(slugs?: string[]) {
+  const s = await getSource();
+  return s.getPage(slugs);
+}
 
-  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
-    folderItems.push({
-      type: 'folder',
-      name: folder.charAt(0).toUpperCase() + folder.slice(1),
-      order: folderOrder,
-      children: sorted,
-    })
-  })
+export function extractFrontmatter(page: { data: unknown }, fallbackTitle?: string): Frontmatter {
+  const d = page.data as Record<string, unknown>;
+  return {
+    title: (d.title as string) ?? fallbackTitle ?? 'Untitled',
+    description: d.description as string | undefined,
+    order: d.order as number | undefined,
+    icon: d.icon as string | undefined,
+    lastModified: d.lastModified as string | undefined,
+  };
+}
 
-  children.push(...sortByOrder(folderItems))
+export function getRelativePath(page: { data: unknown }): string {
+  return ((page.data as Record<string, unknown>)._relativePath as string) ?? '';
+}
 
-  return { name: 'root', children }
+const ssrModules = import.meta.glob<{ default?: MDXContent; toc?: TableOfContents }>(
+  '../../.content/**/*.{mdx,md}'
+);
+
+export async function loadPageModule(
+  relativePath: string
+): Promise<{ default: MDXContent | null; toc: TableOfContents }> {
+  if (!relativePath || relativePath.includes('..')) return { default: null, toc: [] };
+  const withoutExt = relativePath.replace(/\.(mdx|md)$/, '');
+  const key = relativePath.endsWith('.md')
+    ? `../../.content/${withoutExt}.md`
+    : `../../.content/${withoutExt}.mdx`;
+  const loader = ssrModules[key];
+  if (!loader) return { default: null, toc: [] };
+  const mod = await loader();
+  return { default: mod.default ?? null, toc: mod.toc ?? [] };
 }