@raystack/chronicle 0.3.0 → 0.5.0

package/src/cli/utils/config.ts

@@ -1,43 +1,71 @@
-import fs from 'fs'
-import path from 'path'
-import { parse } from 'yaml'
-import chalk from 'chalk'
-import type { ChronicleConfig } from '@/types'
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import chalk from 'chalk';
+import { parse } from 'yaml';
+import { chronicleConfigSchema, type ChronicleConfig } from '@/types';
 
 export interface CLIConfig {
-  config: ChronicleConfig
-  configPath: string
-  contentDir: string
+  config: ChronicleConfig;
+  configPath: string;
+  contentDir: string;
+  preset?: string;
 }
 
-export function resolveContentDir(contentFlag?: string): string {
-  if (contentFlag) return path.resolve(contentFlag)
-  if (process.env.CHRONICLE_CONTENT_DIR) return path.resolve(process.env.CHRONICLE_CONTENT_DIR)
-  return path.resolve('content')
+export function resolveConfigPath(configPath?: string): string | undefined {
+  if (configPath) return path.resolve(configPath);
+  return undefined;
 }
 
-function resolveConfigPath(contentDir: string): string | null {
-  const cwdPath = path.join(process.cwd(), 'chronicle.yaml')
-  if (fs.existsSync(cwdPath)) return cwdPath
-  const contentPath = path.join(contentDir, 'chronicle.yaml')
-  if (fs.existsSync(contentPath)) return contentPath
-  return null
+async function readConfig(configPath: string): Promise<string> {
+  return fs.readFile(configPath, 'utf-8').catch((error: NodeJS.ErrnoException) => {
+    if (error.code === 'ENOENT') {
+      console.log(chalk.red(`Error: chronicle.yaml not found at '${configPath}'`));
+      console.log(chalk.gray("Run 'chronicle init' to create one"));
+    } else {
+      console.log(chalk.red(`Error: Failed to read '${configPath}'`));
+      console.log(chalk.gray(error.message));
+    }
+    process.exit(1);
+  });
 }
 
-export function loadCLIConfig(contentDir: string): CLIConfig {
-  const configPath = resolveConfigPath(contentDir)
+function validateConfig(raw: string, configPath: string): ChronicleConfig {
+  const parsed = parse(raw);
+  const result = chronicleConfigSchema.safeParse(parsed);
 
-  if (!configPath) {
-    console.log(chalk.red(`Error: chronicle.yaml not found in '${process.cwd()}' or '${contentDir}'`))
-    console.log(chalk.gray(`Run 'chronicle init' to create one`))
-    process.exit(1)
+  if (!result.success) {
+    console.log(chalk.red(`Error: Invalid chronicle.yaml at '${configPath}'`));
+    for (const issue of result.error.issues) {
+      const path = issue.path.join('.');
+      console.log(chalk.gray(`  ${path ? `${path}: ` : ''}${issue.message}`));
+    }
+    process.exit(1);
   }
 
-  const config = parse(fs.readFileSync(configPath, 'utf-8')) as ChronicleConfig
+  return result.data;
+}
 
-  return {
-    config,
-    configPath,
-    contentDir,
-  }
+export function resolveContentDir(config: ChronicleConfig, configPath: string, contentFlag?: string): string {
+  if (contentFlag) return path.resolve(contentFlag);
+  if (config.content) return path.resolve(path.dirname(configPath), config.content);
+  return path.resolve('content');
+}
+
+export function resolvePreset(config: ChronicleConfig, presetFlag?: string): string | undefined {
+  return presetFlag ?? config.preset;
+}
+
+export async function loadCLIConfig(
+  configPath?: string,
+  options?: { content?: string; preset?: string }
+): Promise<CLIConfig> {
+  const resolvedConfigPath = resolveConfigPath(configPath)
+    ?? path.join(process.cwd(), 'chronicle.yaml');
+
+  const raw = await readConfig(resolvedConfigPath);
+  const config = validateConfig(raw, resolvedConfigPath);
+  const contentDir = resolveContentDir(config, resolvedConfigPath, options?.content);
+  const preset = resolvePreset(config, options?.preset);
+
+  return { config, configPath: resolvedConfigPath, contentDir, preset };
 }

package/src/cli/utils/index.ts

@@ -1,3 +1,3 @@
-export * from './config'
-export * from './process'
-export * from './scaffold'
+export * from './config';
+export * from './resolve';
+export * from './scaffold';

package/src/cli/utils/resolve.ts

@@ -1,6 +1,10 @@
-import path from 'path'
-import { fileURLToPath } from 'url'
+import path from 'path';
+import { fileURLToPath } from 'url';
 
 // After bundling: dist/cli/index.js → ../.. = package root
 // After install: node_modules/@raystack/chronicle/dist/cli/index.js → ../.. = package root
-export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+export const PACKAGE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..'
+);

package/src/cli/utils/scaffold.ts

@@ -1,137 +1,18 @@
-import { execSync } from 'child_process'
-import { createRequire } from 'module'
-import fs from 'fs'
-import path from 'path'
-import chalk from 'chalk'
-import { PACKAGE_ROOT } from './resolve'
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { PACKAGE_ROOT } from './resolve';
 
-const COPY_FILES = ['src', 'source.config.ts', 'tsconfig.json']
+export async function linkContent(contentDir: string): Promise<void> {
+  const linkPath = path.join(PACKAGE_ROOT, '.content');
+  const target = path.resolve(contentDir);
 
-function copyRecursive(src: string, dest: string) {
-  const stat = fs.statSync(src)
-  if (stat.isDirectory()) {
-    fs.mkdirSync(dest, { recursive: true })
-    for (const entry of fs.readdirSync(src)) {
-      copyRecursive(path.join(src, entry), path.join(dest, entry))
-    }
-  } else {
-    fs.copyFileSync(src, dest)
-  }
-}
-
-function ensureRemoved(targetPath: string) {
   try {
-    fs.lstatSync(targetPath)
-    fs.rmSync(targetPath, { recursive: true, force: true })
+    const existing = await fs.readlink(linkPath);
+    if (existing === target) return;
+    await fs.unlink(linkPath);
   } catch {
-    // nothing exists, proceed
-  }
-}
-
-export function detectPackageManager(): string {
-  if (process.env.npm_config_user_agent) {
-    return process.env.npm_config_user_agent.split('/')[0]
-  }
-  const cwd = process.cwd()
-  if (fs.existsSync(path.join(cwd, 'bun.lock')) || fs.existsSync(path.join(cwd, 'bun.lockb'))) return 'bun'
-  if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return 'pnpm'
-  if (fs.existsSync(path.join(cwd, 'yarn.lock'))) return 'yarn'
-  return 'npm'
-}
-
-function generateNextConfig(scaffoldPath: string) {
-  const config = `import { createMDX } from 'fumadocs-mdx/next'
-
-const withMDX = createMDX()
-
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  reactStrictMode: true,
-}
-
-export default withMDX(nextConfig)
-`
-  fs.writeFileSync(path.join(scaffoldPath, 'next.config.mjs'), config)
-}
-
-function createPackageJson(): Record<string, unknown> {
-  return {
-    name: 'chronicle-docs',
-    private: true,
-    dependencies: {
-      '@raystack/chronicle': `^${getChronicleVersion()}`,
-    },
-    devDependencies: {
-      '@raystack/tools-config': '0.56.0',
-      'openapi-types': '^12.1.3',
-      typescript: '5.9.3',
-      '@types/react': '^19.2.10',
-      '@types/node': '^25.1.0',
-    },
-  }
-}
-
-function ensureDeps() {
-  const cwd = process.cwd()
-  const cwdPkgJson = path.join(cwd, 'package.json')
-  const cwdNodeModules = path.join(cwd, 'node_modules')
-
-  if (fs.existsSync(cwdPkgJson) && fs.existsSync(cwdNodeModules)) {
-    // Case 1: existing project with deps installed
-    return
+    // link doesn't exist
   }
 
-  // Case 2: no package.json — create in cwd and install
-  if (!fs.existsSync(cwdPkgJson)) {
-    fs.writeFileSync(cwdPkgJson, JSON.stringify(createPackageJson(), null, 2) + '\n')
-  }
-
-  if (!fs.existsSync(cwdNodeModules)) {
-    const pm = detectPackageManager()
-    console.log(chalk.cyan(`Installing dependencies with ${pm}...`))
-    execSync(`${pm} install`, { cwd, stdio: 'inherit' })
-  }
-}
-
-export function getChronicleVersion(): string {
-  const pkgPath = path.join(PACKAGE_ROOT, 'package.json')
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
-  return pkg.version
-}
-
-export function resolveNextCli(): string {
-  const chronicleRequire = createRequire(path.join(PACKAGE_ROOT, 'package.json'))
-  return chronicleRequire.resolve('next/dist/bin/next')
-}
-
-export function scaffoldDir(contentDir: string): string {
-  const scaffoldPath = path.join(process.cwd(), '.chronicle')
-
-  // Create .chronicle/ if not exists
-  if (!fs.existsSync(scaffoldPath)) {
-    fs.mkdirSync(scaffoldPath, { recursive: true })
-  }
-
-  // Copy package files
-  for (const name of COPY_FILES) {
-    const src = path.join(PACKAGE_ROOT, name)
-    const dest = path.join(scaffoldPath, name)
-    ensureRemoved(dest)
-    copyRecursive(src, dest)
-  }
-
-  // Generate next.config.mjs
-  generateNextConfig(scaffoldPath)
-
-  // Symlink content dir
-  const contentLink = path.join(scaffoldPath, 'content')
-  ensureRemoved(contentLink)
-  fs.symlinkSync(path.resolve(contentDir), contentLink)
-
-  // Ensure dependencies are available
-  ensureDeps()
-
-  console.log(chalk.gray(`Scaffold: ${scaffoldPath}`))
-
-  return scaffoldPath
+  await fs.symlink(target, linkPath);
 }

package/src/components/mdx/code.tsx

@@ -1,6 +1,7 @@
 'use client'
 
-import type { ComponentProps } from 'react'
+import { type ComponentProps, isValidElement, Children } from 'react'
+import { Mermaid } from './mermaid'
 import styles from './code.module.css'
 
 type PreProps = ComponentProps<'pre'> & {
@@ -16,6 +17,14 @@ export function MdxCode({ children, className, ...props }: ComponentProps<'code'
 }
 
 export function MdxPre({ children, title, className, ...props }: PreProps) {
+  // Detect mermaid code blocks
+  if (isValidElement(children)) {
+    const childProps = children.props as { className?: string; children?: string }
+    if (childProps.className?.includes('language-mermaid') && typeof childProps.children === 'string') {
+      return <Mermaid chart={childProps.children} />
+    }
+  }
+
   return (
     <div className={styles.codeBlock}>
       {title && <div className={styles.codeHeader}>{title}</div>}

package/src/components/mdx/details.module.css

@@ -1,35 +1,10 @@
 .details {
-  border: 1px solid var(--rs-color-border-base-primary);
-  border-radius: var(--rs-radius-2);
   margin: var(--rs-space-5) 0;
 }
 
-.summary {
-  padding: var(--rs-space-4) var(--rs-space-5);
-  cursor: pointer;
+.trigger {
   font-weight: 500;
   font-size: var(--rs-font-size-small);
-  color: var(--rs-color-text-base-primary);
-  background: var(--rs-color-background-base-secondary);
-  list-style: none;
-  display: flex;
-  align-items: center;
-  gap: var(--rs-space-3);
-}
-
-.summary::-webkit-details-marker {
-  display: none;
-}
-
-.summary::before {
-  content: '▶';
-  font-size: 10px;
-  transition: transform 0.2s ease;
-  color: var(--rs-color-text-base-secondary);
-}
-
-.details[open] > .summary::before {
-  transform: rotate(90deg);
 }
 
 .content {

package/src/components/mdx/details.tsx

@@ -1,9 +1,8 @@
 import type { ComponentProps } from 'react'
-import styles from './details.module.css'
 
 export function MdxDetails({ children, className, ...props }: ComponentProps<'details'>) {
   return (
-    <details className={`${styles.details} ${className ?? ''}`} {...props}>
+    <details className={className} {...props}>
       {children}
     </details>
   )
@@ -11,7 +10,7 @@ export function MdxDetails({ children, className, ...props }: ComponentProps<'de
 
 export function MdxSummary({ children, className, ...props }: ComponentProps<'summary'>) {
   return (
-    <summary className={`${styles.summary} ${className ?? ''}`} {...props}>
+    <summary className={className} {...props}>
       {children}
     </summary>
   )

package/src/components/mdx/image.tsx

@@ -1,38 +1,9 @@
-'use client'
+import type { ComponentProps } from 'react';
 
-import NextImage from 'next/image'
-import type { ComponentProps } from 'react'
+type ImageProps = ComponentProps<'img'>;
 
-type ImageProps = Omit<ComponentProps<'img'>, 'src'> & {
-  src?: string
-  width?: number | string
-  height?: number | string
-}
-
-export function Image({ src, alt, width, height, ...props }: ImageProps) {
-  if (!src || typeof src !== 'string') return null
-
-  const isExternal = src.startsWith('http://') || src.startsWith('https://')
-
-  if (isExternal) {
-    return (
-      // eslint-disable-next-line @next/next/no-img-element
-      <img
-        src={src}
-        alt={alt ?? ''}
-        width={width}
-        height={height}
-        {...props}
-      />
-    )
-  }
+export function Image({ src, alt, ...props }: ImageProps) {
+  if (!src) return null;
 
-  return (
-    <NextImage
-      src={src}
-      alt={alt ?? ''}
-      width={typeof width === 'string' ? parseInt(width, 10) : (width ?? 800)}
-      height={typeof height === 'string' ? parseInt(height, 10) : (height ?? 400)}
-    />
-  )
+  return <img src={src} alt={alt ?? ''} loading='lazy' {...props} />;
 }

package/src/components/mdx/index.tsx

@@ -8,6 +8,20 @@ import { Mermaid } from './mermaid'
 import { MdxParagraph } from './paragraph'
 import { CalloutContainer, CalloutTitle, CalloutDescription, MdxBlockquote } from '@/components/common/callout'
 import { Tabs } from '@raystack/apsara'
+import { type ComponentProps, useEffect, useState } from 'react'
+
+function ClientOnly({ children }: { children: React.ReactNode }) {
+  const [mounted, setMounted] = useState(false)
+  useEffect(() => setMounted(true), [])
+  return mounted ? <>{children}</> : null
+}
+
+function MdxTabs(props: ComponentProps<typeof Tabs>) {
+  return <ClientOnly><Tabs {...props} /></ClientOnly>
+}
+MdxTabs.List = Tabs.List
+MdxTabs.Trigger = Tabs.Trigger
+MdxTabs.Content = Tabs.Content
 
 export const mdxComponents: MDXComponents = {
   p: MdxParagraph,
@@ -27,7 +41,7 @@ export const mdxComponents: MDXComponents = {
   Callout: CalloutContainer,
   CalloutTitle,
   CalloutDescription,
-  Tabs,
+  Tabs: MdxTabs,
   Mermaid,
 }
 

package/src/components/mdx/link.tsx

@@ -1,38 +1,41 @@
-'use client'
+import { Link as ApsaraLink } from '@raystack/apsara';
+import type { ComponentProps } from 'react';
+import { Link as RouterLink } from 'react-router';
 
-import NextLink from 'next/link'
-import { Link as ApsaraLink } from '@raystack/apsara'
-import type { ComponentProps } from 'react'
-
-type LinkProps = ComponentProps<'a'>
+type LinkProps = ComponentProps<'a'>;
 
 export function Link({ href, children, ...props }: LinkProps) {
   if (!href) {
-    return <span {...props}>{children}</span>
+    return <span {...props}>{children}</span>;
   }
 
-  const isExternal = href.startsWith('http://') || href.startsWith('https://')
-  const isAnchor = href.startsWith('#')
+  const isExternal = href.startsWith('http://') || href.startsWith('https://');
+  const isAnchor = href.startsWith('#');
 
   if (isAnchor) {
     return (
       <ApsaraLink href={href} {...props}>
         {children}
       </ApsaraLink>
-    )
+    );
   }
 
   if (isExternal) {
     return (
-      <ApsaraLink href={href} target="_blank" rel="noopener noreferrer" {...props}>
+      <ApsaraLink
+        href={href}
+        target='_blank'
+        rel='noopener noreferrer'
+        {...props}
+      >
         {children}
       </ApsaraLink>
-    )
+    );
   }
 
   return (
-    <NextLink href={href} className={props.className}>
+    <RouterLink to={href} className={props.className}>
       {children}
-    </NextLink>
-  )
+    </RouterLink>
+  );
 }

package/src/components/ui/breadcrumbs.tsx

@@ -1,53 +1,19 @@
 'use client'
 
 import { Breadcrumb } from '@raystack/apsara'
-import type { PageTree, PageTreeItem } from '@/types'
+import { getBreadcrumbItems } from 'fumadocs-core/breadcrumb'
+import type { Root } from 'fumadocs-core/page-tree'
 
 interface BreadcrumbsProps {
   slug: string[]
-  tree: PageTree
-}
-
-function findInTree(items: PageTreeItem[], targetPath: string): PageTreeItem | undefined {
-  for (const item of items) {
-    const itemUrl = item.url || `/${item.name.toLowerCase().replace(/\s+/g, '-')}`
-    if (itemUrl === targetPath || itemUrl === `/${targetPath}`) {
-      return item
-    }
-    if (item.children) {
-      const found = findInTree(item.children, targetPath)
-      if (found) return found
-    }
-  }
-  return undefined
-}
-
-function getFirstPageUrl(item: PageTreeItem): string | undefined {
-  if (item.type === 'page' && item.url) {
-    return item.url
-  }
-  if (item.children) {
-    for (const child of item.children) {
-      const url = getFirstPageUrl(child)
-      if (url) return url
-    }
-  }
-  return undefined
+  tree: Root
 }
 
 export function Breadcrumbs({ slug, tree }: BreadcrumbsProps) {
-  const items: { label: string; href: string }[] = []
+  const url = slug.length === 0 ? '/' : `/${slug.join('/')}`
+  const items = getBreadcrumbItems(url, tree, { includePage: true })
 
-  for (let i = 0; i < slug.length; i++) {
-    const currentPath = `/${slug.slice(0, i + 1).join('/')}`
-    const node = findInTree(tree.children, currentPath)
-    const href = node?.url || (node && getFirstPageUrl(node)) || currentPath
-    const label = node?.name ?? slug[i]
-    items.push({
-      label: label.charAt(0).toUpperCase() + label.slice(1),
-      href,
-    })
-  }
+  if (items.length === 0) return null
 
   return (
     <Breadcrumb size="small">
@@ -55,10 +21,10 @@ export function Breadcrumbs({ slug, tree }: BreadcrumbsProps) {
         const breadcrumbItem = (
           <Breadcrumb.Item
             key={`item-${index}`}
-            href={item.href}
+            href={item.url}
             current={index === items.length - 1}
           >
-            {item.label}
+            {item.name}
           </Breadcrumb.Item>
         )
         if (index === 0) return [breadcrumbItem]