@raystack/chronicle 0.1.0-canary.5a2be79 → 0.1.0-canary.6511afe

package/src/cli/utils/resolve.ts

@@ -1,4 +1,10 @@
-import path from 'path'
-import { fileURLToPath } from 'url'
+import path from 'path';
+import { fileURLToPath } from 'url';
 
-export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.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)),
+  '..',
+  '..'
+);

package/src/cli/utils/scaffold.ts

@@ -1,131 +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': 'latest',
-    },
-    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',
-    },
+    // link doesn't exist
   }
-}
-
-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
-  }
-
-  // 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 resolveNextCli(): string {
-  const cwdRequire = createRequire(path.join(process.cwd(), 'package.json'))
-  return cwdRequire.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/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/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/search.module.css

@@ -102,3 +102,10 @@
 .item[data-selected="true"] .icon {
   color: var(--rs-color-foreground-accent-primary-hover);
 }
+
+.pageText :global(mark),
+.headingText :global(mark) {
+  background: transparent;
+  color: var(--rs-color-foreground-accent-primary);
+  font-weight: 600;
+}

package/src/components/ui/search.tsx

@@ -1,21 +1,19 @@
-"use client";
-
-import { useState, useEffect, useCallback } from "react";
-import { useRouter } from "next/navigation";
-import { Button, Command, Dialog, Text } from "@raystack/apsara";
-import { cx } from "class-variance-authority";
-import { useDocsSearch } from "fumadocs-core/search/client";
-import type { SortedResult } from "fumadocs-core/search";
-import { DocumentIcon, HashtagIcon } from "@heroicons/react/24/outline";
-import { isMacOs } from "react-device-detect";
-import { MethodBadge } from "@/components/api/method-badge";
-import styles from "./search.module.css";
+import { DocumentIcon, HashtagIcon } from '@heroicons/react/24/outline';
+import { Button, Command, Dialog, Text } from '@raystack/apsara';
+import { cx } from 'class-variance-authority';
+import type { SortedResult } from 'fumadocs-core/search';
+import { useDocsSearch } from 'fumadocs-core/search/client';
+import { useCallback, useEffect, useState } from 'react';
+import { useNavigate } from 'react-router';
+import { MethodBadge } from '@/components/api/method-badge';
+import styles from './search.module.css';
 
 function SearchShortcutKey({ className }: { className?: string }) {
-  const [key, setKey] = useState("⌘");
+  const [key, setKey] = useState('⌘');
 
   useEffect(() => {
-    setKey(isMacOs ? "⌘" : "Ctrl");
+    const isMac = navigator.platform?.toUpperCase().includes('MAC');
+    setKey(isMac ? '⌘' : 'Ctrl');
   }, []);
 
   return (
@@ -26,50 +24,50 @@ function SearchShortcutKey({ className }: { className?: string }) {
 }
 
 interface SearchProps {
-  className?: string
+  className?: string;
 }
 
 export function Search({ className }: SearchProps) {
   const [open, setOpen] = useState(false);
-  const router = useRouter();
+  const navigate = useNavigate();
 
   const { search, setSearch, query } = useDocsSearch({
-    type: "fetch",
-    api: "/api/search",
+    type: 'fetch',
+    api: '/api/search',
     delayMs: 100,
-    allowEmpty: true,
+    allowEmpty: true
   });
 
   const onSelect = useCallback(
     (url: string) => {
       setOpen(false);
-      router.push(url);
+      navigate(url);
     },
-    [router],
+    [navigate]
   );
 
   useEffect(() => {
     const down = (e: KeyboardEvent) => {
-      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+      if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
         e.preventDefault();
-        setOpen((open) => !open);
+        setOpen(open => !open);
       }
     };
 
-    document.addEventListener("keydown", down);
-    return () => document.removeEventListener("keydown", down);
+    document.addEventListener('keydown', down);
+    return () => document.removeEventListener('keydown', down);
   }, []);
 
   const results = deduplicateByUrl(
-    query.data === "empty" ? [] : (query.data ?? []),
+    query.data === 'empty' ? [] : (query.data ?? [])
   );
 
   return (
     <>
       <Button
-        variant="outline"
-        color="neutral"
-        size="small"
+        variant='outline'
+        color='neutral'
+        size='small'
         onClick={() => setOpen(true)}
         className={cx(styles.trigger, className)}
         trailingIcon={<SearchShortcutKey className={styles.kbd} />}
@@ -84,7 +82,7 @@ export function Search({ className }: SearchProps) {
           </Dialog.Title>
           <Command loop>
             <Command.Input
-              placeholder="Search"
+              placeholder='Search'
               value={search}
               onValueChange={setSearch}
               className={styles.input}
@@ -100,7 +98,7 @@ export function Search({ className }: SearchProps) {
               {!query.isLoading &&
                 search.length === 0 &&
                 results.length > 0 && (
-                  <Command.Group heading="Suggestions">
+                  <Command.Group heading='Suggestions'>
                     {results.slice(0, 8).map((result: SortedResult) => (
                       <Command.Item
                         key={result.id}
@@ -111,7 +109,9 @@ export function Search({ className }: SearchProps) {
                         <div className={styles.itemContent}>
                           {getResultIcon(result)}
                           <Text className={styles.pageText}>
-                            {stripMethod(result.content)}
+                            <HighlightedText
+                              html={stripMethod(result.content)}
+                            />
                           </Text>
                         </div>
                       </Command.Item>
@@ -129,10 +129,12 @@ export function Search({ className }: SearchProps) {
                     <div className={styles.itemContent}>
                       {getResultIcon(result)}
                       <div className={styles.resultText}>
-                        {result.type === "heading" ? (
+                        {result.type === 'heading' ? (
                           <>
                             <Text className={styles.headingText}>
-                              {stripMethod(result.content)}
+                              <HighlightedText
+                                html={stripMethod(result.content)}
+                              />
                             </Text>
                             <Text className={styles.separator}>-</Text>
                             <Text className={styles.pageText}>
@@ -141,7 +143,9 @@ export function Search({ className }: SearchProps) {
                           </>
                         ) : (
                           <Text className={styles.pageText}>
-                            {stripMethod(result.content)}
+                            <HighlightedText
+                              html={stripMethod(result.content)}
+                            />
                           </Text>
                         )}
                       </div>
@@ -158,45 +162,57 @@ export function Search({ className }: SearchProps) {
 
 function deduplicateByUrl(results: SortedResult[]): SortedResult[] {
   const seen = new Set<string>();
-  return results.filter((r) => {
-    const base = r.url.split("#")[0];
+  return results.filter(r => {
+    const base = r.url.split('#')[0];
     if (seen.has(base)) return false;
     seen.add(base);
     return true;
   });
 }
 
-const API_METHODS = new Set(["GET", "POST", "PUT", "DELETE", "PATCH"]);
+const API_METHODS = new Set(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']);
 
 function extractMethod(content: string): string | null {
-  const first = content.split(" ")[0];
+  const first = content.split(' ')[0];
   return API_METHODS.has(first) ? first : null;
 }
 
 function stripMethod(content: string): string {
-  const first = content.split(" ")[0];
+  const first = content.split(' ')[0];
   return API_METHODS.has(first) ? content.slice(first.length + 1) : content;
 }
 
+function HighlightedText({
+  html,
+  className
+}: {
+  html: string;
+  className?: string;
+}) {
+  return (
+    <span className={className} dangerouslySetInnerHTML={{ __html: html }} />
+  );
+}
+
 function getResultIcon(result: SortedResult): React.ReactNode {
-  if (!result.url.startsWith("/apis/")) {
-    return result.type === "page" ? (
+  if (!result.url.startsWith('/apis/')) {
+    return result.type === 'page' ? (
       <DocumentIcon className={styles.icon} />
     ) : (
       <HashtagIcon className={styles.icon} />
     );
   }
   const method = extractMethod(result.content);
-  return method ? <MethodBadge method={method} size="micro" /> : null;
+  return method ? <MethodBadge method={method} size='micro' /> : null;
 }
 
 function getPageTitle(url: string): string {
-  const path = url.split("#")[0];
-  const segments = path.split("/").filter(Boolean);
+  const path = url.split('#')[0];
+  const segments = path.split('/').filter(Boolean);
   const lastSegment = segments[segments.length - 1];
-  if (!lastSegment) return "Home";
+  if (!lastSegment) return 'Home';
   return lastSegment
-    .split("-")
-    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-    .join(" ");
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
 }

package/src/lib/config.ts

@@ -1,55 +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 }
+  };
+}

package/src/lib/head.tsx

@@ -0,0 +1,49 @@
+import type { ChronicleConfig } from '@/types';
+
+export interface HeadProps {
+  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);
+
+  return (
+    <>
+      <title>{fullTitle}</title>
+      {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 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'
+          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