@raystack/chronicle 0.1.2

package/next.config.mjs

@@ -0,0 +1,10 @@
+import { createMDX } from 'fumadocs-mdx/next'
+
+const withMDX = createMDX()
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+}
+
+export default withMDX(nextConfig)

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@raystack/chronicle",
+  "version": "0.1.2",
+  "description": "Config-driven documentation framework",
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "templates",
+    "next.config.mjs",
+    "source.config.ts"
+  ],
+  "bin": {
+    "chronicle": "./bin/chronicle.js"
+  },
+  "scripts": {
+    "build:cli": "bun build-cli.ts"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@raystack/tools-config": "0.56.0",
+    "@types/lodash": "^4.17.23",
+    "@types/mdx": "^2.0.13",
+    "@types/node": "^25.1.0",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "@types/semver": "^7.7.1",
+    "openapi-types": "^12.1.3",
+    "semver": "^7.7.4",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/state": "^6.5.4",
+    "@codemirror/theme-one-dark": "^6.1.3",
+    "@codemirror/view": "^6.39.14",
+    "@heroicons/react": "^2.2.0",
+    "@raystack/apsara": "^0.56.0",
+    "chalk": "^5.6.2",
+    "class-variance-authority": "^0.7.1",
+    "codemirror": "^6.0.2",
+    "commander": "^14.0.2",
+    "fumadocs-core": "^16.4.9",
+    "fumadocs-mdx": "^14.2.6",
+    "lodash": "^4.17.23",
+    "mermaid": "^11.13.0",
+    "next": "16.1.6",
+    "react": "^19.0.0",
+    "react-device-detect": "^2.2.3",
+    "react-dom": "^19.0.0",
+    "remark-attr": "^0.11.1",
+    "remark-directive": "^4.0.0",
+    "slugify": "^1.6.6",
+    "unist-util-visit": "^5.1.0",
+    "yaml": "^2.8.2",
+    "zod": "^4.3.6"
+  }
+}

package/source.config.ts

@@ -0,0 +1,43 @@
+import { defineDocs, defineConfig } from 'fumadocs-mdx/config'
+import remarkDirective from 'remark-directive'
+import { remarkDirectiveAdmonition, remarkMdxMermaid } from 'fumadocs-core/mdx-plugins'
+import remarkUnusedDirectives from './src/lib/remark-unused-directives'
+
+const contentDir = process.env.CHRONICLE_CONTENT_DIR || './content'
+
+export const docs = defineDocs({
+  dir: contentDir,
+  docs: {
+    files: ['**/*.mdx', '**/*.md', '!**/node_modules/**'],
+  },
+})
+
+export default defineConfig({
+  mdxOptions: {
+    remarkPlugins: [
+      remarkDirective,
+      [
+        remarkDirectiveAdmonition,
+        {
+          tags: {
+            CalloutContainer: 'Callout',
+            CalloutTitle: 'CalloutTitle',
+            CalloutDescription: 'CalloutDescription',
+          },
+          types: {
+            note: 'accent',
+            tip: 'accent',
+            info: 'accent',
+            warn: 'attention',
+            warning: 'attention',
+            danger: 'alert',
+            caution: 'alert',
+            success: 'success',
+          },
+        },
+      ],
+      remarkUnusedDirectives,
+      remarkMdxMermaid,
+    ],
+  },
+})

package/src/app/[[...slug]]/layout.tsx

@@ -0,0 +1,15 @@
+import { loadConfig } from '@/lib/config'
+import { buildPageTree } from '@/lib/source'
+import { getTheme } from '@/themes/registry'
+
+export default function DocsLayout({ children }: { children: React.ReactNode }) {
+  const config = loadConfig()
+  const tree = buildPageTree()
+  const { Layout, className } = getTheme(config.theme?.name)
+
+  return (
+    <Layout config={config} tree={tree} classNames={{ layout: className }}>
+      {children}
+    </Layout>
+  )
+}

package/src/app/[[...slug]]/page.tsx

@@ -0,0 +1,57 @@
+import { notFound } from 'next/navigation'
+import type { MDXContent } from 'mdx/types'
+import { loadConfig } from '@/lib/config'
+import { source, buildPageTree } from '@/lib/source'
+import { getTheme } from '@/themes/registry'
+import { mdxComponents } from '@/components/mdx'
+
+interface PageProps {
+  params: Promise<{ slug?: string[] }>
+}
+
+interface PageData {
+  title: string
+  description?: string
+  body: MDXContent
+  toc: { title: string; url: string; depth: number }[]
+}
+
+export default async function DocsPage({ params }: PageProps) {
+  const { slug } = await params
+  const config = loadConfig()
+
+  const page = source.getPage(slug)
+
+  if (!page) {
+    notFound()
+  }
+
+  const { Page } = getTheme(config.theme?.name)
+
+  const data = page.data as PageData
+  const MDXBody = data.body
+
+  const tree = buildPageTree()
+
+  return (
+    <Page
+      page={{
+        slug: slug ?? [],
+        frontmatter: {
+          title: data.title,
+          description: data.description,
+        },
+        content: <MDXBody components={mdxComponents} />,
+        toc: data.toc ?? [],
+      }}
+      config={config}
+      tree={tree}
+    />
+  )
+}
+
+export function generateStaticParams() {
+  return source.getPages().map((page) => ({
+    slug: page.slugs,
+  }))
+}

package/src/app/api/apis-proxy/route.ts

@@ -0,0 +1,59 @@
+import { NextRequest, NextResponse } from "next/server";
+import { loadConfig } from "@/lib/config";
+import { loadApiSpecs } from "@/lib/openapi";
+
+export async function POST(request: NextRequest) {
+  const { specName, method, path, headers, body } = await request.json();
+
+  if (!specName || !method || !path) {
+    return NextResponse.json(
+      { error: "Missing specName, method, or path" },
+      { status: 400 },
+    );
+  }
+
+  const config = loadConfig();
+  const specs = loadApiSpecs(config.api ?? []);
+  const spec = specs.find((s) => s.name === specName);
+
+  if (!spec) {
+    return NextResponse.json(
+      { error: `Unknown spec: ${specName}` },
+      { status: 404 },
+    );
+  }
+
+  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 NextResponse.json({
+      status: response.status,
+      statusText: response.statusText,
+      body: responseBody,
+    }, { status: response.status });
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? `${error.message}${error.cause ? `: ${(error.cause as Error).message}` : ""}`
+        : "Request failed";
+    return NextResponse.json(
+      {
+        status: 502,
+        statusText: "Bad Gateway",
+        body: `Could not reach ${url}\n${message}`,
+      },
+      { status: 502 },
+    );
+  }
+}

package/src/app/api/health/route.ts

@@ -0,0 +1,3 @@
+export function GET() {
+  return Response.json({ status: 'ok' })
+}

package/src/app/api/search/route.ts

@@ -0,0 +1,90 @@
+import { source } from '@/lib/source'
+import { createSearchAPI, type AdvancedIndex } from 'fumadocs-core/search/server'
+import type { StructuredData } from 'fumadocs-core/mdx-plugins'
+import type { OpenAPIV3 } from 'openapi-types'
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs, type ApiSpec } from '@/lib/openapi'
+import { getSpecSlug } from '@/lib/api-routes'
+
+interface PageData {
+  title?: string
+  description?: string
+  structuredData?: StructuredData
+  load?: () => Promise<{ structuredData?: StructuredData }>
+}
+
+const HTTP_METHODS = ['get', 'post', 'put', 'delete', 'patch'] as const
+type HttpMethod = (typeof HTTP_METHODS)[number]
+
+function getParamNames(op: OpenAPIV3.OperationObject): string[] {
+  const params = (op.parameters as OpenAPIV3.ParameterObject[] | undefined) ?? []
+  return params.map((p) => p.name)
+}
+
+function buildStructuredData(op: OpenAPIV3.OperationObject, method: string, pathStr: string) {
+  return {
+    headings: [{ id: op.operationId!, content: `${method.toUpperCase()} ${pathStr}` }],
+    contents: [{ heading: op.operationId!, content: `${method.toUpperCase()} ${[op.description, ...getParamNames(op)].filter(Boolean).join(' ')}` }],
+  }
+}
+
+function operationToIndex(specSlug: string, pathStr: string, method: HttpMethod, op: OpenAPIV3.OperationObject): AdvancedIndex {
+  const url = `/apis/${specSlug}/${encodeURIComponent(op.operationId!)}`
+  return {
+    id: url,
+    url,
+    title: `${method.toUpperCase()} ${op.summary ?? op.operationId!}`,
+    description: op.description ?? '',
+    structuredData: buildStructuredData(op, method, pathStr),
+  }
+}
+
+function pathEntryToIndexes(specSlug: string) {
+  return ([pathStr, pathItem]: [string, OpenAPIV3.PathItemObject | undefined]): AdvancedIndex[] => {
+    if (!pathItem) return []
+    const hasOp = (m: HttpMethod) => !!pathItem[m]?.operationId
+    const toIndex = (m: HttpMethod) => operationToIndex(specSlug, pathStr, m, pathItem[m]!)
+    return HTTP_METHODS.filter(hasOp).map(toIndex)
+  }
+}
+
+function specToIndexes(spec: ApiSpec): AdvancedIndex[] {
+  const specSlug = getSpecSlug(spec)
+  return Object.entries(spec.document.paths ?? {}).flatMap(pathEntryToIndexes(specSlug))
+}
+
+function buildApiIndexes(): AdvancedIndex[] {
+  const config = loadConfig()
+  if (!config.api?.length) return []
+  return loadApiSpecs(config.api).flatMap(specToIndexes)
+}
+
+export const { GET } = createSearchAPI('advanced', {
+  indexes: async (): Promise<AdvancedIndex[]> => {
+    const pages = source.getPages()
+    const indexes = await Promise.all(
+      pages.map(async (page): Promise<AdvancedIndex> => {
+        const data = page.data as PageData
+        let structuredData: StructuredData | undefined = data.structuredData
+
+        if (!structuredData && data.load) {
+          try {
+            const loaded = await data.load()
+            structuredData = loaded.structuredData
+          } catch (error) {
+            console.error(`Failed to load structured data for ${page.url}:`, error)
+          }
+        }
+
+        return {
+          id: page.url,
+          url: page.url,
+          title: data.title ?? '',
+          description: data.description ?? '',
+          structuredData: structuredData ?? { headings: [], contents: [] },
+        }
+      })
+    )
+    return [...indexes, ...buildApiIndexes()]
+  },
+})

package/src/app/apis/[[...slug]]/layout.module.css

@@ -0,0 +1,22 @@
+.layout {
+  height: 100vh;
+  overflow: hidden;
+}
+
+.body {
+  overflow: hidden;
+}
+
+.sidebar {
+  height: 100%;
+}
+
+.content {
+  height: 100%;
+  overflow-y: auto;
+  padding-right: 0;
+}
+
+.hiddenSearch {
+  display: none;
+}

package/src/app/apis/[[...slug]]/layout.tsx

@@ -0,0 +1,26 @@
+import { cx } from 'class-variance-authority'
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs } from '@/lib/openapi'
+import { buildApiPageTree } from '@/lib/api-routes'
+import { getTheme } from '@/themes/registry'
+import { Search } from '@/components/ui/search'
+import styles from './layout.module.css'
+
+export default function ApiLayout({ children }: { children: React.ReactNode }) {
+  const config = loadConfig()
+  const { Layout, className } = getTheme(config.theme?.name)
+  const specs = loadApiSpecs(config.api ?? [])
+  const tree = buildApiPageTree(specs)
+
+  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/app/apis/[[...slug]]/page.tsx

@@ -0,0 +1,57 @@
+import { notFound } from 'next/navigation'
+import type { OpenAPIV3 } from 'openapi-types'
+import { Flex, Headline, Text } from '@raystack/apsara'
+import { loadConfig } from '@/lib/config'
+import { loadApiSpecs } from '@/lib/openapi'
+import { buildApiRoutes, findApiOperation } from '@/lib/api-routes'
+import { EndpointPage } from '@/components/api'
+
+interface PageProps {
+  params: Promise<{ slug?: string[] }>
+}
+
+export default async function ApiPage({ params }: PageProps) {
+  const { slug } = await params
+  const config = loadConfig()
+  const specs = loadApiSpecs(config.api ?? [])
+
+  if (!slug || slug.length === 0) {
+    return <ApiLanding specs={specs} />
+  }
+
+  const match = findApiOperation(specs, slug)
+  if (!match) notFound()
+
+  return (
+    <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: { name: string; document: OpenAPIV3.Document }[] }) {
+  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>
+  )
+}
+
+export function generateStaticParams() {
+  const config = loadConfig()
+  const specs = loadApiSpecs(config.api ?? [])
+  return [{ slug: [] }, ...buildApiRoutes(specs)]
+}

package/src/app/layout.tsx

@@ -0,0 +1,26 @@
+import '@raystack/apsara/normalize.css'
+import '@raystack/apsara/style.css'
+import type { Metadata } from 'next'
+import { loadConfig } from '@/lib/config'
+import { Providers } from './providers'
+
+const config = loadConfig()
+
+export const metadata: Metadata = {
+  title: config.title,
+  description: config.description,
+}
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body suppressHydrationWarning>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}

package/src/app/providers.tsx

@@ -0,0 +1,8 @@
+'use client'
+
+import { ThemeProvider } from '@raystack/apsara'
+import type { ReactNode } from 'react'
+
+export function Providers({ children }: { children: ReactNode }) {
+  return <ThemeProvider enableSystem>{children}</ThemeProvider>
+}

package/src/cli/commands/build.ts

@@ -0,0 +1,31 @@
+import { Command } from 'commander'
+import { spawn } from 'child_process'
+import path from 'path'
+import chalk from 'chalk'
+import { resolveContentDir, loadCLIConfig, attachLifecycleHandlers } from '@/cli/utils'
+
+declare const PACKAGE_ROOT: string
+
+const nextBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'next.cmd' : 'next')
+
+export const buildCommand = new Command('build')
+  .description('Build for production')
+  .option('-c, --content <path>', 'Content directory')
+  .action((options) => {
+    const contentDir = resolveContentDir(options.content)
+    loadCLIConfig(contentDir)
+
+    console.log(chalk.cyan('Building for production...'))
+    console.log(chalk.gray(`Content: ${contentDir}`))
+
+    const child = spawn(nextBin, ['build'], {
+      stdio: 'inherit',
+      cwd: PACKAGE_ROOT,
+      env: {
+        ...process.env,
+        CHRONICLE_CONTENT_DIR: contentDir,
+      },
+    })
+
+    attachLifecycleHandlers(child)
+  })

package/src/cli/commands/dev.ts

@@ -0,0 +1,32 @@
+import { Command } from 'commander'
+import { spawn } from 'child_process'
+import path from 'path'
+import chalk from 'chalk'
+import { resolveContentDir, loadCLIConfig, attachLifecycleHandlers } from '@/cli/utils'
+
+declare const PACKAGE_ROOT: string
+
+const nextBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'next.cmd' : 'next')
+
+export const devCommand = new Command('dev')
+  .description('Start development server')
+  .option('-p, --port <port>', 'Port number', '3000')
+  .option('-c, --content <path>', 'Content directory')
+  .action((options) => {
+    const contentDir = resolveContentDir(options.content)
+    loadCLIConfig(contentDir)
+
+    console.log(chalk.cyan('Starting dev server...'))
+    console.log(chalk.gray(`Content: ${contentDir}`))
+
+    const child = spawn(nextBin, ['dev', '-p', options.port], {
+      stdio: 'inherit',
+      cwd: PACKAGE_ROOT,
+      env: {
+        ...process.env,
+        CHRONICLE_CONTENT_DIR: contentDir,
+      },
+    })
+
+    attachLifecycleHandlers(child)
+  })

package/src/cli/commands/init.ts

@@ -0,0 +1,58 @@
+import { Command } from 'commander'
+import fs from 'fs'
+import path from 'path'
+import chalk from 'chalk'
+import { stringify } from 'yaml'
+import type { ChronicleConfig } from '@/types'
+
+function createConfig(): ChronicleConfig {
+  return {
+    title: 'My Documentation',
+    description: 'Documentation powered by Chronicle',
+    theme: { name: 'default' },
+    search: { enabled: true, placeholder: 'Search documentation...' },
+  }
+}
+
+const sampleMdx = `---
+title: Welcome
+description: Getting started with your documentation
+order: 1
+---
+
+# Welcome
+
+This is your documentation home page.
+`
+
+export const initCommand = new Command('init')
+  .description('Initialize a new Chronicle project')
+  .option('-d, --dir <path>', 'Content directory', '.')
+  .action((options) => {
+    const contentDir = path.resolve(options.dir)
+
+    // Create content directory
+    if (!fs.existsSync(contentDir)) {
+      fs.mkdirSync(contentDir, { recursive: true })
+      console.log(chalk.green('✓'), 'Created', contentDir)
+    }
+
+    // Create chronicle.yaml
+    const configPath = path.join(contentDir, 'chronicle.yaml')
+    if (!fs.existsSync(configPath)) {
+      fs.writeFileSync(configPath, stringify(createConfig()))
+      console.log(chalk.green('✓'), 'Created', configPath)
+    } else {
+      console.log(chalk.yellow('⚠'), configPath, 'already exists')
+    }
+
+    // Create sample index.mdx
+    const indexPath = path.join(contentDir, 'index.mdx')
+    if (!fs.existsSync(indexPath)) {
+      fs.writeFileSync(indexPath, sampleMdx)
+      console.log(chalk.green('✓'), 'Created', indexPath)
+    }
+
+    console.log(chalk.green('\n✓ Chronicle initialized!'))
+    console.log('\nRun', chalk.cyan('chronicle dev'), 'to start development server')
+  })

package/src/cli/commands/serve.ts

@@ -0,0 +1,52 @@
+import { Command } from 'commander'
+import { spawn } from 'child_process'
+import path from 'path'
+import chalk from 'chalk'
+import { resolveContentDir, loadCLIConfig, attachLifecycleHandlers } from '@/cli/utils'
+
+declare const PACKAGE_ROOT: string
+
+const nextBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'next.cmd' : 'next')
+
+export const serveCommand = new Command('serve')
+  .description('Build and start production server')
+  .option('-p, --port <port>', 'Port number', '3000')
+  .option('-c, --content <path>', 'Content directory')
+  .action((options) => {
+    const contentDir = resolveContentDir(options.content)
+    loadCLIConfig(contentDir)
+
+    const env = {
+      ...process.env,
+      CHRONICLE_CONTENT_DIR: contentDir,
+    }
+
+    console.log(chalk.cyan('Building for production...'))
+    console.log(chalk.gray(`Content: ${contentDir}`))
+
+    const buildChild = spawn(nextBin, ['build'], {
+      stdio: 'inherit',
+      cwd: PACKAGE_ROOT,
+      env,
+    })
+
+    process.once('SIGINT', () => buildChild.kill('SIGINT'))
+    process.once('SIGTERM', () => buildChild.kill('SIGTERM'))
+
+    buildChild.on('close', (code) => {
+      if (code !== 0) {
+        console.log(chalk.red('Build failed'))
+        process.exit(code ?? 1)
+      }
+
+      console.log(chalk.cyan('Starting production server...'))
+
+      const startChild = spawn(nextBin, ['start', '-p', options.port], {
+        stdio: 'inherit',
+        cwd: PACKAGE_ROOT,
+        env,
+      })
+
+      attachLifecycleHandlers(startChild)
+    })
+  })