@raystack/chronicle 0.7.4 → 0.9.0

package/src/components/ui/search.tsx

@@ -4,7 +4,7 @@ import {
   MagnifyingGlassIcon
 } from '@heroicons/react/24/outline';
 import { Command, IconButton, Text } from '@raystack/apsara';
-import debounce from 'lodash/debounce';
+import { debounce } from 'lodash-es';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useNavigate } from 'react-router';
 import { MethodBadge } from '@/components/api/method-badge';
@@ -16,6 +16,8 @@ interface SearchResult {
   url: string;
   type: string;
   content: string;
+  match?: 'title' | 'heading' | 'body';
+  snippet?: string;
 }
 
 interface SearchProps {
@@ -121,7 +123,7 @@ export function Search({ classNames }: SearchProps) {
 
       <Command.Dialog open={open} onOpenChange={setOpen}>
         <Command.DialogContent className={styles.dialogContent}>
-          <Command>
+          <Command items={displayResults}>
             <Command.Input
               placeholder='Search'
               leadingIcon={<MagnifyingGlassIcon width={16} height={16} />}
@@ -171,23 +173,17 @@ export function Search({ classNames }: SearchProps) {
                     <div className={styles.itemContent}>
                       {getResultIcon(result)}
                       <div className={styles.resultText}>
-                        {result.type === 'heading' ? (
-                          <>
-                            <Text className={styles.headingText}>
-                              <HighlightedText
-                                html={stripMethod(result.content)}
-                              />
-                            </Text>
-                            <Text className={styles.separator}>-</Text>
-                            <Text className={styles.pageText}>
-                              {getPageTitle(result.url)}
-                            </Text>
-                          </>
-                        ) : (
-                          <Text className={styles.pageText}>
-                            <HighlightedText
-                              html={stripMethod(result.content)}
-                            />
+                        <Text className={styles.pageText}>
+                          <HighlightQuery text={stripMethod(result.content)} query={search} />
+                        </Text>
+                        {result.snippet && result.match === 'heading' && (
+                          <Text className={styles.snippetText}>
+                            # <HighlightQuery text={result.snippet} query={search} />
+                          </Text>
+                        )}
+                        {result.snippet && result.match === 'body' && (
+                          <Text className={styles.snippetText}>
+                            <HighlightQuery text={result.snippet} query={search} />
                           </Text>
                         )}
                       </div>
@@ -236,6 +232,19 @@ function HighlightedText({
   );
 }
 
+function HighlightQuery({ text, query }: { text: string; query: string }) {
+  if (!query) return <>{text}</>;
+  const idx = text.toLowerCase().indexOf(query.toLowerCase());
+  if (idx < 0) return <>{text}</>;
+  return (
+    <>
+      {text.slice(0, idx)}
+      <span className={styles.matchHighlight}>{text.slice(idx, idx + query.length)}</span>
+      {text.slice(idx + query.length)}
+    </>
+  );
+}
+
 function getResultIcon(result: SearchResult): React.ReactNode {
   if (!result.url.startsWith('/apis/')) {
     return result.type === 'page' ? (

package/src/lib/api-routes.ts

@@ -7,6 +7,31 @@ export function getSpecSlug(spec: ApiSpec): string {
   return slugify(spec.name, { lower: true, strict: true })
 }
 
+function deriveOperationId(method: string, path: string): string {
+  const slug = path.replace(/[/{}\-]/g, '_').replace(/_+/g, '_').replace(/^_|_$/g, '')
+  return `${method}_${slug || 'root'}`
+}
+
+function getOperationId(op: OpenAPIV3.OperationObject, method: string, path: string): string {
+  return op.operationId || deriveOperationId(method, path)
+}
+
+
+export function getFirstApiUrl(specs: ApiSpec[]): string | null {
+  for (const spec of specs) {
+    const specSlug = getSpecSlug(spec)
+    const paths = spec.document.paths ?? {}
+    for (const [pathStr, pathItem] of Object.entries(paths)) {
+      if (!pathItem) continue
+      for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
+        const op = pathItem[method]
+        if (!op) continue
+        return `/apis/${specSlug}/${encodeURIComponent(getOperationId(op, method, pathStr))}`
+      }
+    }
+  }
+  return null
+}
 
 export function buildApiRoutes(specs: ApiSpec[]): { slug: string[] }[] {
   const routes: { slug: string[] }[] = []
@@ -15,12 +40,13 @@ export function buildApiRoutes(specs: ApiSpec[]): { slug: string[] }[] {
     const specSlug = getSpecSlug(spec)
     const paths = spec.document.paths ?? {}
 
-    for (const [, pathItem] of Object.entries(paths)) {
+    for (const [pathStr, pathItem] of Object.entries(paths)) {
       if (!pathItem) continue
       for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
         const op = pathItem[method]
-        if (!op?.operationId) continue
-        routes.push({ slug: [specSlug, encodeURIComponent(op.operationId)] })
+        if (!op) continue
+        const opId = getOperationId(op, method, pathStr)
+        routes.push({ slug: [specSlug, encodeURIComponent(opId)] })
       }
     }
   }
@@ -47,7 +73,9 @@ export function findApiOperation(specs: ApiSpec[], slug: string[]): ApiRouteMatc
     if (!pathItem) continue
     for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
       const op = pathItem[method]
-      if (op?.operationId && encodeURIComponent(op.operationId) === operationId) {
+      if (!op) continue
+      const opId = getOperationId(op, method, pathStr)
+      if (encodeURIComponent(opId) === operationId) {
         return { spec, operation: op, method: method.toUpperCase(), path: pathStr }
       }
     }
@@ -67,12 +95,13 @@ export function buildApiPageTree(specs: ApiSpec[]): Root {
     const opsByTag = new Map<string, Item[]>()
     const tagDisplayName = new Map<string, string>()
 
-    for (const [, pathItem] of Object.entries(paths)) {
+    for (const [pathStr, pathItem] of Object.entries(paths)) {
       if (!pathItem) continue
       for (const method of ['get', 'post', 'put', 'delete', 'patch'] as const) {
         const op = pathItem[method]
-        if (!op?.operationId) continue
+        if (!op) continue
 
+        const opId = getOperationId(op, method, pathStr)
         const rawTag = op.tags?.[0] ?? 'default'
         const tagKey = rawTag.toLowerCase()
         if (!opsByTag.has(tagKey)) {
@@ -82,8 +111,8 @@ export function buildApiPageTree(specs: ApiSpec[]): Root {
 
         opsByTag.get(tagKey)!.push({
           type: 'page',
-          name: op.summary ?? op.operationId,
-          url: `/apis/${specSlug}/${encodeURIComponent(op.operationId)}`,
+          name: op.summary ?? opId,
+          url: `/apis/${specSlug}/${encodeURIComponent(opId)}`,
           icon: `method-${method}`,
         })
       }

package/src/lib/openapi.ts

@@ -120,12 +120,38 @@ function convertV2toV3(doc: OpenAPIV2.Document): OpenAPIV3.Document {
     v3Paths[pathStr] = v3PathItem
   }
 
+  const securitySchemes = convertV2SecurityDefs(resolved.securityDefinitions as Record<string, OpenAPIV2.SecuritySchemeObject> | undefined)
+
   return {
     openapi: '3.0.0',
     info: resolved.info as unknown as OpenAPIV3.InfoObject,
     paths: v3Paths,
     tags: (resolved.tags ?? []) as unknown as OpenAPIV3.TagObject[],
+    ...(resolved.externalDocs ? { externalDocs: resolved.externalDocs as unknown as OpenAPIV3.ExternalDocumentationObject } : {}),
+    ...(Object.keys(securitySchemes).length > 0 ? { components: { securitySchemes } } : {}),
+  }
+}
+
+function convertV2SecurityDefs(defs: Record<string, OpenAPIV2.SecuritySchemeObject> | undefined): Record<string, OpenAPIV3.SecuritySchemeObject> {
+  if (!defs) return {}
+  const result: Record<string, OpenAPIV3.SecuritySchemeObject> = {}
+  for (const [name, def] of Object.entries(defs)) {
+    if (def.type === 'apiKey') {
+      result[name] = { type: 'apiKey', name: (def as JsonObject).name as string, in: def.in as string } as OpenAPIV3.ApiKeySecurityScheme
+    } else if (def.type === 'basic') {
+      result[name] = { type: 'http', scheme: 'basic' } as OpenAPIV3.HttpSecurityScheme
+    } else if (def.type === 'oauth2') {
+      const v2 = def as unknown as { flow?: string; authorizationUrl?: string; tokenUrl?: string; scopes?: Record<string, string> }
+      const flow = { authorizationUrl: v2.authorizationUrl ?? '', tokenUrl: v2.tokenUrl ?? '', scopes: v2.scopes ?? {} }
+      const flows: OpenAPIV3.OAuth2SecurityScheme['flows'] = {}
+      if (v2.flow === 'implicit') flows.implicit = { authorizationUrl: flow.authorizationUrl, scopes: flow.scopes }
+      else if (v2.flow === 'password') flows.password = { tokenUrl: flow.tokenUrl, scopes: flow.scopes }
+      else if (v2.flow === 'application') flows.clientCredentials = { tokenUrl: flow.tokenUrl, scopes: flow.scopes }
+      else if (v2.flow === 'accessCode') flows.authorizationCode = { authorizationUrl: flow.authorizationUrl, tokenUrl: flow.tokenUrl, scopes: flow.scopes }
+      result[name] = { type: 'oauth2', flows } as OpenAPIV3.OAuth2SecurityScheme
+    }
   }
+  return result
 }
 
 function convertV2Operation(op: OpenAPIV2.OperationObject): OpenAPIV3.OperationObject {

package/src/lib/page-context.tsx

@@ -116,7 +116,7 @@ export function PageProvider({
   const fetchPageData = useCallback(async (slug: string[]): Promise<PageData> => {
     const apiPath = slug.length === 0
       ? '/api/page'
-      : `/api/page?slug=${slug.join(',')}`;
+      : `/api/page?slug=${slug.map(s => encodeURIComponent(s)).join(',')}`;
     const res = await fetch(apiPath);
     if (!res.ok) throw new Error(String(res.status));
     return res.json();

package/src/lib/schema.ts

@@ -1,19 +1,56 @@
 import type { OpenAPIV3 } from 'openapi-types'
 
+const schemaFieldKinds = {
+  string: 'string', integer: 'integer', number: 'number',
+  boolean: 'boolean', array: 'array', object: 'object',
+} as const
+
+export type SchemaFieldKind = keyof typeof schemaFieldKinds
+
+export function toKind(type: unknown): SchemaFieldKind {
+  if (typeof type === 'string' && type in schemaFieldKinds) return type as SchemaFieldKind
+  return 'object'
+}
+
 export interface SchemaField {
   name: string
   type: string
+  kind: SchemaFieldKind
   required: boolean
   description?: string
   default?: unknown
+  example?: unknown
   enum?: unknown[]
   children?: SchemaField[]
 }
 
+function mergeAllOf(schema: OpenAPIV3.SchemaObject): OpenAPIV3.SchemaObject {
+  const composed = schema.allOf ?? schema.oneOf ?? schema.anyOf
+  if (!composed) return schema
+  const merged: OpenAPIV3.SchemaObject = { ...schema }
+  delete merged.allOf
+  delete merged.oneOf
+  delete merged.anyOf
+  for (const sub of composed as OpenAPIV3.SchemaObject[]) {
+    if (sub.type) merged.type = sub.type
+    if (sub.properties) {
+      merged.properties = { ...(merged.properties ?? {}), ...sub.properties }
+    }
+    if (sub.required) {
+      merged.required = [...(merged.required ?? []), ...sub.required]
+    }
+    if (sub.description && !merged.description) merged.description = sub.description
+  }
+  return merged
+}
+
 export function flattenSchema(
   schema: OpenAPIV3.SchemaObject,
   requiredFields: string[] = [],
 ): SchemaField[] {
+  const resolved = mergeAllOf(schema)
+  if (resolved !== schema) return flattenSchema(resolved, requiredFields)
+
   if (schema.type === 'array' && schema.items) {
     const items = schema.items as OpenAPIV3.SchemaObject
     const itemType = inferType(items)
@@ -26,6 +63,7 @@ export function flattenSchema(
     return [{
       name: 'items',
       type: `${itemType}[]`,
+      kind: 'array' as SchemaFieldKind,
       required: true,
       description: items.description,
       children: children?.length ? children : undefined,
@@ -36,7 +74,8 @@ export function flattenSchema(
     const properties = (schema.properties ?? {}) as Record<string, OpenAPIV3.SchemaObject>
     const required = schema.required ?? requiredFields
 
-    return Object.entries(properties).map(([name, prop]) => {
+    return Object.entries(properties).map(([name, rawProp]) => {
+      const prop = mergeAllOf(rawProp)
       const fieldType = inferType(prop)
       const children =
         fieldType === 'object' || prop.properties
@@ -48,9 +87,11 @@ export function flattenSchema(
       return {
         name,
         type: fieldType,
+        kind: toKind(prop.type),
         required: required.includes(name),
-        description: prop.description,
+        description: rawProp.description ?? prop.description,
         default: prop.default,
+        example: prop.example,
         enum: prop.enum,
         children: children?.length ? children : undefined,
       }
@@ -87,7 +128,8 @@ export function generateExampleJson(schema: OpenAPIV3.SchemaObject): unknown {
   return defaults[schema.type as string] ?? null
 }
 
-function inferType(schema: OpenAPIV3.SchemaObject): string {
+function inferType(rawSchema: OpenAPIV3.SchemaObject): string {
+  const schema = mergeAllOf(rawSchema)
   if (schema.type === 'array') {
     const items = schema.items as OpenAPIV3.SchemaObject | undefined
     const itemType = items ? inferType(items) : 'unknown'

package/src/lib/source.ts

@@ -1,3 +1,5 @@
+import fs from 'node:fs/promises';
+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';
@@ -118,41 +120,76 @@ export function invalidate() {
   cachedNavMap = 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);
+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') {
+    const folderPath = getFolderPath(node);
+    if (folderPath) return folderOrderMap.get(folderPath);
+  }
   return undefined;
 }
 
-function sortNodes(nodes: Node[], orderMap: Map<string, number>): Node[] {
+function sortNodes(nodes: Node[], pageOrderMap: Map<string, number>, folderOrderMap: Map<string, number>): Node[] {
   return [...nodes]
     .map(n =>
       n.type === 'folder'
-        ? ({ ...n, children: sortNodes(n.children, orderMap) } as Folder)
+        ? ({ ...n, children: sortNodes(n.children, pageOrderMap, folderOrderMap) } as Folder)
         : n
     )
     .sort(
       (a, b) =>
-        (getOrder(a, orderMap) ?? Number.MAX_SAFE_INTEGER) -
-        (getOrder(b, orderMap) ?? Number.MAX_SAFE_INTEGER)
+        (getOrder(a, pageOrderMap, folderOrderMap) ?? Number.MAX_SAFE_INTEGER) -
+        (getOrder(b, pageOrderMap, folderOrderMap) ?? Number.MAX_SAFE_INTEGER)
     );
 }
 
-function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[]): Root {
-  const orderMap = new Map<string, number>();
+function buildFolderOrderMap(metaFiles: { path: string; data: Record<string, unknown> }[]): Map<string, number> {
+  const map = new Map<string, number>();
+  for (const meta of metaFiles) {
+    const order = meta.data.order as number | undefined;
+    if (order === undefined) continue;
+    const folderUrl = '/' + meta.path.replace(/\/meta\.json$/, '');
+    map.set(folderUrl, order);
+  }
+  return map;
+}
+
+function sortTreeByOrder(tree: Root, pages: { url: string; data: unknown }[], metaFiles: { path: string; data: Record<string, unknown> }[]): Root {
+  const pageOrderMap = 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);
+    if (order !== undefined) pageOrderMap.set(page.url, order);
+    if (page.url === '/') pageOrderMap.set('/', order ?? 0);
   }
-  return { ...tree, children: sortNodes(tree.children, orderMap) };
+  const folderOrderMap = buildFolderOrderMap(metaFiles);
+  return { ...tree, children: sortNodes(tree.children, pageOrderMap, folderOrderMap) };
 }
 
 export async function getPageTree(): Promise<Root> {
   if (cachedTree) return cachedTree;
   const s = await getSource();
-  cachedTree = sortTreeByOrder(s.pageTree as Root, s.getPages());
+  const metaFiles = buildFiles().filter(f => f.type === 'meta') as { path: string; data: Record<string, unknown> }[];
+  cachedTree = sortTreeByOrder(s.pageTree as Root, s.getPages(), metaFiles);
   return cachedTree;
 }
 
@@ -240,6 +277,35 @@ export function getOriginalPath(page: { data: unknown }): string {
   return ((page.data as Record<string, unknown>)._originalPath as string) ?? '';
 }
 
+export async function getPageSearchContent(page: { data: unknown }): Promise<{ headings: string; body: string }> {
+  const originalPath = getOriginalPath(page);
+  if (!originalPath) return { headings: '', body: '' };
+  try {
+    const contentDir = typeof __CHRONICLE_CONTENT_DIR__ !== 'undefined' ? __CHRONICLE_CONTENT_DIR__ : process.cwd();
+    const filePath = path.resolve(contentDir, originalPath);
+    const raw = await fs.readFile(filePath, 'utf-8');
+    const withoutFrontmatter = raw.replace(/^---[\s\S]*?---/m, '');
+    const headings: string[] = [];
+    const lines: string[] = [];
+    for (const line of withoutFrontmatter.split('\n')) {
+      const headingMatch = line.match(/^#{1,6}\s+(.+)/);
+      if (headingMatch) {
+        headings.push(headingMatch[1]);
+      } else if (!line.startsWith('import ') && !line.startsWith('export ') && !line.startsWith('```')) {
+        const cleaned = line
+          .replace(/<[^>]+>/g, '')
+          .replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
+          .replace(/[*_~`]+/g, '')
+          .trim();
+        if (cleaned) lines.push(cleaned);
+      }
+    }
+    return { headings: headings.join('\n'), body: lines.join(' ') };
+  } catch {
+    return { headings: '', body: '' };
+  }
+}
+
 interface ReadingTime {
   text: string;
   minutes: number;

package/src/lib/use-api-operation.ts

@@ -0,0 +1,15 @@
+import { useMemo } from 'react'
+import { useLocation } from 'react-router'
+import { findApiOperation, type ApiRouteMatch } from '@/lib/api-routes'
+import { usePageContext } from '@/lib/page-context'
+
+export function useApiOperation(): ApiRouteMatch | null {
+  const { apiSpecs } = usePageContext()
+  const { pathname } = useLocation()
+
+  return useMemo(() => {
+    const slug = pathname.replace(/^\/apis\//, '').split('/').filter(Boolean)
+    if (slug.length !== 2) return null
+    return findApiOperation(apiSpecs, slug)
+  }, [apiSpecs, pathname])
+}

package/src/pages/ApiLayout.module.css

@@ -14,6 +14,7 @@
 .content {
   height: 100%;
   overflow-y: auto;
+  padding-left: 0;
   padding-right: 0;
 }
 

package/src/pages/ApiPage.tsx

@@ -1,9 +1,8 @@
-import { Flex, Headline, Text } from '@raystack/apsara';
 import type { OpenAPIV3 } from 'openapi-types';
-import { EndpointPage } from '@/components/api';
-import { findApiOperation } from '@/lib/api-routes';
+import { Navigate } from 'react-router';
+import { ApiOverview } from '@/components/api';
+import { findApiOperation, getFirstApiUrl } from '@/lib/api-routes';
 import { Head } from '@/lib/head';
-import type { ApiSpec } from '@/lib/openapi';
 import { usePageContext } from '@/lib/page-context';
 
 interface ApiPageProps {
@@ -14,16 +13,9 @@ export function ApiPage({ slug }: ApiPageProps) {
   const { config, apiSpecs } = usePageContext();
 
   if (slug.length === 0) {
-    return (
-      <>
-        <Head
-          title='API Reference'
-          description={`API documentation for ${config.site.title}`}
-          config={config}
-        />
-        <ApiLanding specs={apiSpecs} />
-      </>
-    );
+    const firstUrl = getFirstApiUrl(apiSpecs);
+    if (firstUrl) return <Navigate to={firstUrl} replace />;
+    return null;
   }
 
   const match = findApiOperation(apiSpecs, slug);
@@ -36,7 +28,7 @@ export function ApiPage({ slug }: ApiPageProps) {
   return (
     <>
       <Head title={title} description={operation.description} config={config} />
-      <EndpointPage
+      <ApiOverview
         method={match.method}
         path={match.path}
         operation={match.operation}
@@ -48,26 +40,3 @@ export function ApiPage({ slug }: ApiPageProps) {
   );
 }
 
-function ApiLanding({ specs }: { specs: ApiSpec[] }) {
-  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>
-  );
-}

package/src/pages/DocsPage.tsx

@@ -1,7 +1,32 @@
+import { Navigate } from 'react-router';
 import { Head } from '@/lib/head';
 import { usePageContext } from '@/lib/page-context';
 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[];
@@ -10,7 +35,21 @@ interface DocsPageProps {
 export function DocsPage({ slug }: DocsPageProps) {
   const { config, tree, page, isLoading, errorStatus } = usePageContext();
 
-  if (errorStatus === 404) return <NotFound />;
+  if (errorStatus === 404) {
+    const pathname = `/${slug.join('/')}`;
+    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 />;
+    return <NotFound />;
+  }
   if (errorStatus) return <NotFound />;
   const { Page, Skeleton } = getTheme(config.theme?.name);
 

package/src/server/api/apis-proxy.ts

@@ -51,10 +51,17 @@ export default defineHandler(async event => {
       ? await response.json()
       : await response.text();
 
+    const sensitiveHeaders = new Set(['set-cookie', 'authorization', 'proxy-authorization', 'cookie']);
+    const responseHeaders: Record<string, string> = {};
+    response.headers.forEach((v, k) => {
+      if (!sensitiveHeaders.has(k.toLowerCase())) responseHeaders[k] = v;
+    });
+
     return Response.json({
       status: response.status,
       statusText: response.statusText,
-      body: responseBody
+      body: responseBody,
+      headers: responseHeaders
     });
   } catch (error) {
     const message =

package/src/server/api/ready.ts

@@ -0,0 +1,15 @@
+import { defineHandler } from 'nitro';
+import { isSearchReady } from './search';
+
+export default defineHandler(() => {
+  const searchReady = isSearchReady();
+
+  if (!searchReady) {
+    return Response.json(
+      { status: 'not_ready', search: false },
+      { status: 503 },
+    );
+  }
+
+  return Response.json({ status: 'ready', search: true });
+});