@raystack/chronicle 0.9.0 → 0.10.0

package/dist/cli/index.js

@@ -312,6 +312,18 @@ import { nitro } from "nitro/vite";
 import fs3 from "node:fs/promises";
 import path6 from "node:path";
 import remarkDirective from "remark-directive";
+function getDatabaseConnector(preset) {
+  switch (preset) {
+    case "bun":
+      return { connector: "bun-sqlite", options: { name: "chronicle-search" } };
+    case "cloudflare":
+    case "cloudflare-pages":
+    case "cloudflare-module":
+      return { connector: "cloudflare-d1", options: { bindingName: "CHRONICLE_DB" } };
+    default:
+      return { connector: "sqlite", options: { name: "chronicle-search" } };
+  }
+}
 function resolveOutputDir(projectRoot, preset) {
   if (preset === "vercel" || preset === "vercel-static")
     return path6.resolve(projectRoot, ".vercel/output");
@@ -429,10 +441,7 @@ async function createViteConfig(options) {
         database: true
       },
       database: {
-        default: {
-          connector: "sqlite",
-          options: { name: "chronicle-search" }
-        }
+        default: getDatabaseConnector(preset)
       }
     }
   };
@@ -561,6 +570,11 @@ var RESERVED_ROUTE_SEGMENTS = [
   "robots.txt",
   "sitemap.xml"
 ];
+var redirectSchema = z.object({
+  from: z.string(),
+  to: z.string(),
+  permanent: z.boolean().optional()
+});
 var chronicleConfigSchema = z.object({
   site: siteSchema,
   url: z.string().optional(),
@@ -573,6 +587,7 @@ var chronicleConfigSchema = z.object({
   navigation: navigationSchema.optional(),
   search: searchSchema.optional(),
   api: z.array(apiSchema).optional(),
+  redirects: z.array(redirectSchema).optional(),
   analytics: analyticsSchema.optional(),
   telemetry: telemetrySchema.optional()
 }).strict().refine((cfg) => allUnique(cfg.content, (c) => c.dir), {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raystack/chronicle",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Config-driven documentation framework",
   "license": "Apache-2.0",
   "type": "module",
@@ -59,6 +59,7 @@
     "glob": "^11.0.0",
     "gray-matter": "^4.0.3",
     "h3": "^2.0.1-rc.16",
+    "http-status-codes": "^2.3.0",
     "lodash-es": "^4.17.23",
     "mermaid": "^11.13.0",
     "nitro": "3.0.260311-beta",

package/src/lib/folder-utils.ts

@@ -0,0 +1,26 @@
+import type { Node, Folder } from 'fumadocs-core/page-tree';
+
+const NodeType = {
+  Page: 'page',
+  Folder: 'folder',
+} as const;
+
+export function parentPath(url: string): string {
+  const parts = url.split('/').filter(Boolean);
+  parts.pop();
+  return '/' + parts.join('/');
+}
+
+export function getFolderPath(node: Folder): string | null {
+  if (node.index) return node.index.url;
+  for (const child of node.children) {
+    if (child.type === NodeType.Page) return parentPath(child.url);
+  }
+  for (const child of node.children) {
+    if (child.type === NodeType.Folder) {
+      const childPath = getFolderPath(child as Folder);
+      if (childPath) return parentPath(childPath);
+    }
+  }
+  return null;
+}

package/src/lib/route-resolver.test.ts

@@ -60,7 +60,7 @@ describe('resolveRoute — root', () => {
     expect(resolveRoute('/', singleContent())).toEqual({
       type: RouteType.Redirect,
       to: '/docs',
-      status: 302,
+      status: 307,
     })
   })
 
@@ -75,7 +75,7 @@ describe('resolveRoute — root', () => {
     expect(resolveRoute('/', multiContentNoLanding())).toEqual({
       type: RouteType.Redirect,
       to: '/docs',
-      status: 302,
+      status: 307,
     })
   })
 
@@ -83,7 +83,7 @@ describe('resolveRoute — root', () => {
     expect(resolveRoute('/v2', versioned())).toEqual({
       type: RouteType.Redirect,
       to: '/v2/docs',
-      status: 302,
+      status: 307,
     })
   })
 

package/src/lib/route-resolver.ts

@@ -1,3 +1,4 @@
+import { StatusCodes } from 'http-status-codes'
 import type { ChronicleConfig } from '@/types'
 import { getLatestContentRoots, getVersionContentRoots } from './config'
 import { type VersionContext, resolveVersionFromUrl } from './version-source'
@@ -13,7 +14,7 @@ export const RouteType = {
 export type RouteType = (typeof RouteType)[keyof typeof RouteType]
 
 export type Route =
-  | { type: typeof RouteType.Redirect; to: string; status: 302 }
+  | { type: typeof RouteType.Redirect; to: string; status: StatusCodes.TEMPORARY_REDIRECT | StatusCodes.PERMANENT_REDIRECT }
   | { type: typeof RouteType.DocsIndex; version: VersionContext }
   | { type: typeof RouteType.DocsPage; version: VersionContext; slug: string[] }
   | { type: typeof RouteType.ApiIndex; version: VersionContext }
@@ -45,6 +46,15 @@ export function resolveRoute(
   pathname: string,
   config: ChronicleConfig,
 ): Route {
+  const redirect = config.redirects?.find((r) => r.from === pathname)
+  if (redirect) {
+    return {
+      type: RouteType.Redirect,
+      to: redirect.to,
+      status: redirect.permanent ? StatusCodes.PERMANENT_REDIRECT : StatusCodes.TEMPORARY_REDIRECT,
+    }
+  }
+
   const parts = pathname.split('/').filter(Boolean)
   const version = resolveVersionFromUrl(pathname, config)
   const remainder =
@@ -65,7 +75,7 @@ export function resolveRoute(
     return {
       type: RouteType.Redirect,
       to: `${version.urlPrefix}/${dirs[0]}`,
-      status: 302,
+      status: StatusCodes.TEMPORARY_REDIRECT,
     }
   }
 

package/src/lib/source-utils.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from 'bun:test'
+import type { Node, Folder } from 'fumadocs-core/page-tree'
+import { parentPath, getFolderPath } from './folder-utils'
+
+function page(url: string): Node {
+  return { type: 'page', name: 'Page', url } as Node
+}
+
+function folder(name: string, children: Node[], indexUrl?: string): Folder {
+  return {
+    type: 'folder',
+    name,
+    children,
+    ...(indexUrl ? { index: { url: indexUrl } } : {}),
+  } as Folder
+}
+
+describe('parentPath', () => {
+  test('returns parent of page URL', () => {
+    expect(parentPath('/docs/guides/install')).toBe('/docs/guides')
+  })
+
+  test('returns root for top-level page', () => {
+    expect(parentPath('/docs')).toBe('/')
+  })
+
+  test('handles trailing segments', () => {
+    expect(parentPath('/a/b/c/d')).toBe('/a/b/c')
+  })
+
+  test('handles root', () => {
+    expect(parentPath('/')).toBe('/')
+  })
+})
+
+describe('getFolderPath', () => {
+  test('returns index URL when folder has index', () => {
+    const f = folder('Guides', [page('/docs/guides/install')], '/docs/guides')
+    expect(getFolderPath(f)).toBe('/docs/guides')
+  })
+
+  test('derives path from direct child page', () => {
+    const f = folder('Guides', [page('/docs/guides/install')])
+    expect(getFolderPath(f)).toBe('/docs/guides')
+  })
+
+  test('derives path from subfolder child (not deeply nested)', () => {
+    const f = folder('Tasking', [
+      folder('Via Order Desk', [page('/docs/tasking/via_order_desk/package')])
+    ])
+    expect(getFolderPath(f)).toBe('/docs/tasking')
+  })
+
+  test('handles folder with & in path', () => {
+    const f = folder('Cart & Order', [page('/docs/cart&order/working_with_cart')])
+    expect(getFolderPath(f)).toBe('/docs/cart&order')
+  })
+
+  test('handles folder with space in path', () => {
+    const f = folder('My Folder', [page('/docs/my folder/intro')])
+    expect(getFolderPath(f)).toBe('/docs/my folder')
+  })
+
+  test('returns null for empty folder', () => {
+    const f = folder('Empty', [])
+    expect(getFolderPath(f)).toBeNull()
+  })
+
+  test('prefers direct child page over subfolder', () => {
+    const f = folder('Mixed', [
+      page('/docs/mixed/intro'),
+      folder('Sub', [page('/docs/mixed/sub/deep')])
+    ])
+    expect(getFolderPath(f)).toBe('/docs/mixed')
+  })
+
+  test('deeply nested only-subfolder chain', () => {
+    const f = folder('Root', [
+      folder('Mid', [
+        folder('Deep', [page('/a/b/c/d/page')])
+      ])
+    ])
+    expect(getFolderPath(f)).toBe('/a/b')
+  })
+})

package/src/lib/source.ts

@@ -3,6 +3,13 @@ import path from 'node:path';
 import { loader } from 'fumadocs-core/source';
 import { flattenTree } from 'fumadocs-core/page-tree';
 import type { Root, Node, Folder } from 'fumadocs-core/page-tree';
+
+import { parentPath, getFolderPath } from './folder-utils';
+
+const NodeType = {
+  Page: 'page',
+  Folder: 'folder',
+} as const;
 import type { MDXContent } from 'mdx/types';
 import type { TableOfContents } from 'fumadocs-core/toc';
 import {
@@ -120,28 +127,10 @@ export function invalidate() {
   cachedNavMap = null;
 }
 
-function getFolderPath(node: Folder): string | null {
-  const firstPage = findFirstPage(node);
-  if (!firstPage) return null;
-  const parts = firstPage.url.split('/').filter(Boolean);
-  parts.pop();
-  return '/' + parts.join('/');
-}
-
-function findFirstPage(node: Folder): { url: string } | null {
-  for (const child of node.children) {
-    if (child.type === 'page') return child;
-    if (child.type === 'folder') {
-      const found = findFirstPage(child);
-      if (found) return found;
-    }
-  }
-  return node.index ?? null;
-}
 
 function getOrder(node: Node, pageOrderMap: Map<string, number>, folderOrderMap: Map<string, number>): number | undefined {
-  if (node.type === 'page') return pageOrderMap.get(node.url);
-  if (node.type === 'folder') {
+  if (node.type === NodeType.Page) return pageOrderMap.get(node.url);
+  if (node.type === NodeType.Folder) {
     const folderPath = getFolderPath(node);
     if (folderPath) return folderOrderMap.get(folderPath);
   }

package/src/lib/tree-utils.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from 'bun:test'
+import type { Node } from 'fumadocs-core/page-tree'
+import { getFirstPageUrl, findFolderFirstPage, resolveDocsRedirect } from './tree-utils'
+
+function page(url: string, name = 'Page'): Node {
+  return { type: 'page', name, url } as Node
+}
+
+function folder(name: string, children: Node[], indexUrl?: string): Node {
+  return {
+    type: 'folder',
+    name,
+    children,
+    ...(indexUrl ? { index: { url: indexUrl } } : {}),
+  } as Node
+}
+
+describe('getFirstPageUrl', () => {
+  test('returns first page url', () => {
+    expect(getFirstPageUrl([page('/docs/intro')])).toBe('/docs/intro')
+  })
+
+  test('returns first page from nested folder', () => {
+    const nodes = [folder('Guides', [page('/docs/guides/install')])]
+    expect(getFirstPageUrl(nodes)).toBe('/docs/guides/install')
+  })
+
+  test('skips empty folders', () => {
+    const nodes = [folder('Empty', []), page('/docs/hello')]
+    expect(getFirstPageUrl(nodes)).toBe('/docs/hello')
+  })
+
+  test('returns null for empty list', () => {
+    expect(getFirstPageUrl([])).toBeNull()
+  })
+
+  test('returns null for folders with no pages', () => {
+    expect(getFirstPageUrl([folder('Empty', [])])).toBeNull()
+  })
+})
+
+describe('findFolderFirstPage', () => {
+  test('finds folder by index url', () => {
+    const nodes = [
+      folder('Guides', [page('/docs/guides/install'), page('/docs/guides/config')], '/docs/guides'),
+    ]
+    expect(findFolderFirstPage(nodes, '/docs/guides')).toBe('/docs/guides/install')
+  })
+
+  test('finds folder without index by child page path', () => {
+    const nodes = [
+      folder('Guides', [page('/docs/guides/install'), page('/docs/guides/config')]),
+    ]
+    expect(findFolderFirstPage(nodes, '/docs/guides')).toBe('/docs/guides/install')
+  })
+
+  test('finds nested folder', () => {
+    const nodes = [
+      folder('Docs', [
+        folder('Advanced', [page('/docs/advanced/perf'), page('/docs/advanced/debug')]),
+      ]),
+    ]
+    expect(findFolderFirstPage(nodes, '/docs/advanced')).toBe('/docs/advanced/perf')
+  })
+
+  test('returns null for non-matching path', () => {
+    const nodes = [folder('Guides', [page('/docs/guides/install')])]
+    expect(findFolderFirstPage(nodes, '/docs/api')).toBeNull()
+  })
+
+  test('returns null for empty folder', () => {
+    const nodes = [folder('Empty', [])]
+    expect(findFolderFirstPage(nodes, '/docs/empty')).toBeNull()
+  })
+})
+
+describe('resolveDocsRedirect', () => {
+  const tree = {
+    children: [
+      page('/docs/intro'),
+      folder('Guides', [page('/docs/guides/install')]),
+    ] as Node[],
+  }
+
+  test('redirects to index_page when set', () => {
+    expect(resolveDocsRedirect(['docs'], tree, { dir: 'docs', index_page: 'getting-started' }))
+      .toBe('/docs/getting-started')
+  })
+
+  test('redirects content root to first page', () => {
+    expect(resolveDocsRedirect(['docs'], tree, { dir: 'docs' }))
+      .toBe('/docs/intro')
+  })
+
+  test('redirects folder to first child', () => {
+    expect(resolveDocsRedirect(['docs', 'guides'], tree, { dir: 'docs' }))
+      .toBe('/docs/guides/install')
+  })
+
+  test('returns null for non-matching path', () => {
+    expect(resolveDocsRedirect(['docs', 'nonexistent'], tree, { dir: 'docs' }))
+      .toBeNull()
+  })
+
+  test('returns null without content config', () => {
+    expect(resolveDocsRedirect(['other'], tree)).toBeNull()
+  })
+
+  test('index_page takes priority over first page', () => {
+    expect(resolveDocsRedirect(['docs'], tree, { dir: 'docs', index_page: 'custom' }))
+      .toBe('/docs/custom')
+  })
+})

package/src/lib/tree-utils.ts

@@ -0,0 +1,57 @@
+import type { Node } from 'fumadocs-core/page-tree';
+
+export const NodeType = {
+  Page: 'page',
+  Folder: 'folder',
+  Separator: 'separator',
+} as const;
+
+export function getFirstPageUrl(nodes: Node[]): string | null {
+  for (const node of nodes) {
+    if (node.type === NodeType.Page) return node.url;
+    if (node.type === NodeType.Folder) {
+      const url = getFirstPageUrl(node.children);
+      if (url) return url;
+    }
+  }
+  return null;
+}
+
+function getFolderPath(node: Node): string | null {
+  if (node.type !== NodeType.Folder) return null;
+  if (node.index) return node.index.url;
+  const firstPage = getFirstPageUrl(node.children);
+  if (!firstPage) return null;
+  const parts = firstPage.split('/').filter(Boolean);
+  parts.pop();
+  return '/' + parts.join('/');
+}
+
+export function findFolderFirstPage(nodes: Node[], pathname: string): string | null {
+  for (const node of nodes) {
+    if (node.type === NodeType.Folder) {
+      const folderPath = getFolderPath(node);
+      if (folderPath === pathname) return getFirstPageUrl(node.children);
+      const found = findFolderFirstPage(node.children, pathname);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+export function resolveDocsRedirect(
+  slug: string[],
+  tree: { children: Node[] },
+  contentConfig?: { dir: string; index_page?: string },
+): string | null {
+  const isContentRoot = slug.length === 1 && slug[0] === contentConfig?.dir;
+
+  if (isContentRoot) {
+    if (contentConfig?.index_page) {
+      return `/${contentConfig.dir}/${contentConfig.index_page}`;
+    }
+    return getFirstPageUrl(tree.children);
+  }
+
+  return findFolderFirstPage(tree.children, `/${slug.join('/')}`);
+}

package/src/pages/DocsPage.tsx

@@ -1,32 +1,10 @@
 import { Navigate } from 'react-router';
+import { StatusCodes } from 'http-status-codes';
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
+import { resolveDocsRedirect } from '@/lib/tree-utils';
 import { NotFound } from '@/pages/NotFound';
 import { getTheme } from '@/themes/registry';
-import type { Node } from 'fumadocs-core/page-tree';
-
-function getFirstPageUrl(nodes: Node[]): string | null {
-  for (const node of nodes) {
-    if (node.type === 'page') return node.url;
-    if (node.type === 'folder') {
-      const url = getFirstPageUrl(node.children);
-      if (url) return url;
-    }
-  }
-  return null;
-}
-
-function findFolderFirstPage(nodes: Node[], pathname: string): string | null {
-  for (const node of nodes) {
-    if (node.type === 'folder') {
-      const folderUrl = node.index?.url;
-      if (folderUrl === pathname) return getFirstPageUrl(node.children);
-      const found = findFolderFirstPage(node.children, pathname);
-      if (found) return found;
-    }
-  }
-  return null;
-}
 
 interface DocsPageProps {
   slug: string[];
@@ -35,19 +13,10 @@ interface DocsPageProps {
 export function DocsPage({ slug }: DocsPageProps) {
   const { config, tree, page, isLoading, errorStatus } = usePageContext();
 
-  if (errorStatus === 404) {
-    const pathname = `/${slug.join('/')}`;
+  if (errorStatus === StatusCodes.NOT_FOUND) {
     const contentConfig = config.content?.find(c => c.dir === slug[0]);
-    const isContentRoot = slug.length === 1 && slug[0] === contentConfig?.dir;
-    if (contentConfig?.index_page) {
-      return <Navigate to={`/${contentConfig.dir}/${contentConfig.index_page}`} replace />;
-    }
-    if (isContentRoot) {
-      const firstUrl = getFirstPageUrl(tree.children);
-      if (firstUrl) return <Navigate to={firstUrl} replace />;
-    }
-    const folderFirstUrl = findFolderFirstPage(tree.children, pathname);
-    if (folderFirstUrl) return <Navigate to={folderFirstUrl} replace />;
+    const redirectUrl = resolveDocsRedirect(slug, tree, contentConfig);
+    if (redirectUrl) return <Navigate to={redirectUrl} replace />;
     return <NotFound />;
   }
   if (errorStatus) return <NotFound />;

package/src/server/entry-server.tsx

@@ -10,6 +10,9 @@ import { loadApiSpecs } from '@/lib/openapi';
 import { PageProvider } from '@/lib/page-context';
 import { resolveRoute, RouteType } from '@/lib/route-resolver';
 import { getPageTree, getPage, getPageNav, loadPageModule, extractFrontmatter, getRelativePath, getOriginalPath } from '@/lib/source';
+import { getFirstApiUrl } from '@/lib/api-routes';
+import { StatusCodes } from 'http-status-codes';
+import { resolveDocsRedirect } from '@/lib/tree-utils';
 import { useNitroApp } from 'nitro/app';
 import { App } from './App';
 
@@ -45,6 +48,30 @@ export default {
       getPageTree(),
       route.type === RouteType.DocsPage ? getPage(route.slug) : Promise.resolve(null),
     ]);
+    // SSR redirects for index pages
+    if (route.type === RouteType.ApiIndex) {
+      const firstUrl = getFirstApiUrl(apiSpecs);
+      if (firstUrl) {
+        return new Response(null, { status: StatusCodes.TEMPORARY_REDIRECT, headers: { Location: firstUrl } });
+      }
+    }
+
+    if (route.type === RouteType.DocsPage && !page) {
+      const versionPrefix = route.version.urlPrefix;
+      const slugWithoutVersion = versionPrefix && route.slug[0] === route.version.dir
+        ? route.slug.slice(1)
+        : route.slug;
+      const contentEntries = route.version.dir
+        ? config.versions?.find(v => v.dir === route.version.dir)?.content ?? config.content
+        : config.content;
+      const contentConfig = contentEntries?.find((c: { dir: string }) => c.dir === slugWithoutVersion[0]);
+      const redirectUrl = resolveDocsRedirect(slugWithoutVersion, tree, contentConfig);
+      if (redirectUrl) {
+        const fullUrl = versionPrefix ? `${versionPrefix}${redirectUrl}` : redirectUrl;
+        return new Response(null, { status: StatusCodes.TEMPORARY_REDIRECT, headers: { Location: fullUrl } });
+      }
+    }
+
     const nav = page ? await getPageNav(pageSlug) : { prev: null, next: null };
 
     const relativePath = page ? getRelativePath(page) : null;
@@ -120,7 +147,7 @@ export default {
 
     const renderDuration = performance.now() - renderStart;
 
-    const status = route.type === RouteType.DocsPage && !page ? 404 : 200;
+    const status = route.type === RouteType.DocsPage && !page ? StatusCodes.NOT_FOUND : StatusCodes.OK;
 
     // biome-ignore lint/correctness/useHookAtTopLevel: useNitroApp is a Nitro DI accessor, not a React hook
     useNitroApp().hooks.callHook('chronicle:ssr-rendered', pathname, status, renderDuration);

package/src/server/vite-config.ts

@@ -12,6 +12,19 @@ import remarkResolveLinks from '../lib/remark-resolve-links';
 import remarkReadingTime from 'remark-reading-time';
 import remarkUnusedDirectives from '../lib/remark-unused-directives';
 
+function getDatabaseConnector(preset?: string): { connector: string; options?: Record<string, unknown> } {
+  switch (preset) {
+    case 'bun':
+      return { connector: 'bun-sqlite', options: { name: 'chronicle-search' } };
+    case 'cloudflare':
+    case 'cloudflare-pages':
+    case 'cloudflare-module':
+      return { connector: 'cloudflare-d1', options: { bindingName: 'CHRONICLE_DB' } };
+    default:
+      return { connector: 'sqlite', options: { name: 'chronicle-search' } };
+  }
+}
+
 function resolveOutputDir(projectRoot: string, preset?: string): string {
   if (preset === 'vercel' || preset === 'vercel-static') return path.resolve(projectRoot, '.vercel/output');
   return path.resolve(projectRoot, '.output');
@@ -140,10 +153,7 @@ export async function createViteConfig(
         database: true,
       },
       database: {
-        default: {
-          connector: 'sqlite',
-          options: { name: 'chronicle-search' },
-        },
+        default: getDatabaseConnector(preset),
       },
     },
   };

package/src/types/config.ts

@@ -131,6 +131,12 @@ const RESERVED_ROUTE_SEGMENTS = [
   'sitemap.xml',
 ] as const
 
+const redirectSchema = z.object({
+  from: z.string(),
+  to: z.string(),
+  permanent: z.boolean().optional(),
+})
+
 export const chronicleConfigSchema = z
   .object({
     site: siteSchema,
@@ -144,6 +150,7 @@ export const chronicleConfigSchema = z
     navigation: navigationSchema.optional(),
     search: searchSchema.optional(),
     api: z.array(apiSchema).optional(),
+    redirects: z.array(redirectSchema).optional(),
     analytics: analyticsSchema.optional(),
     telemetry: telemetrySchema.optional(),
   })
@@ -225,6 +232,7 @@ export type SocialLink = z.infer<typeof socialLinkSchema>
 export type SearchConfig = z.infer<typeof searchSchema>
 export type ApiConfig = z.infer<typeof apiSchema>
 export type ApiServerConfig = z.infer<typeof apiServerSchema>
+export type RedirectConfig = z.infer<typeof redirectSchema>
 export type ApiAuthConfig = z.infer<typeof apiAuthSchema>
 export type AnalyticsConfig = z.infer<typeof analyticsSchema>
 export type GoogleAnalyticsConfig = z.infer<typeof googleAnalyticsSchema>