fix: runtime PACKAGE_ROOT, frontmatter ordering, llms.txt support (#19)

rsbh · claude · web-flow · commit 8265e8ed633a · 2026-03-12T12:33:37.000+05:30
* fix: resolve PACKAGE_ROOT at runtime and add order to frontmatter schema

- Replace build-time PACKAGE_ROOT injection with runtime resolution via
  import.meta.url, fixing broken next binary path in published npm package
- Add `order` field to fumadocs frontmatter schema so sidebar ordering works
- Use folder's index page order for group sorting, fallback to lowest child order

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

* fix: add unified and @types/unist deps, fix directive types for strict TS

Adds missing type dependencies that caused Docker production build failures.
Fixes DirectiveNode type to be compatible with strict unist types.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

* feat: add llms.txt support with config toggle

- Add /llms.txt (index) and /llms-full.txt (full content) routes
- Controlled via llms.enabled in chronicle.yaml (default: false)
- Upgrade fumadocs-core to 16.6.15 for native llms() support
- Enable postprocess with includeProcessedMarkdown in source config

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;

---------

Co-authored-by: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/bun.lock b/bun.lock
diff --git a/packages/chronicle/build-cli.ts b/packages/chronicle/build-cli.ts
@@ -5,9 +5,6 @@ const result = await Bun.build({
   outdir: 'dist/cli',
   target: 'node',
   format: 'esm',
-  define: {
-    PACKAGE_ROOT: JSON.stringify(path.resolve(import.meta.dir)),
-  },
 })
 
 if (!result.success) {
diff --git a/packages/chronicle/package.json b/packages/chronicle/package.json
@@ -38,11 +38,12 @@
     "@codemirror/view": "^6.39.14",
     "@heroicons/react": "^2.2.0",
     "@raystack/apsara": "^0.56.0",
+    "@types/unist": "^3.0.3",
     "chalk": "^5.6.2",
     "class-variance-authority": "^0.7.1",
     "codemirror": "^6.0.2",
     "commander": "^14.0.2",
-    "fumadocs-core": "^16.4.9",
+    "fumadocs-core": "16.6.15",
     "fumadocs-mdx": "^14.2.6",
     "lodash": "^4.17.23",
     "mermaid": "^11.13.0",
@@ -53,6 +54,7 @@
     "remark-attr": "^0.11.1",
     "remark-directive": "^4.0.0",
     "slugify": "^1.6.6",
+    "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.6"
diff --git a/packages/chronicle/source.config.ts b/packages/chronicle/source.config.ts
@@ -1,4 +1,5 @@
-import { defineDocs, defineConfig } from 'fumadocs-mdx/config'
+import { defineDocs, defineConfig, frontmatterSchema } from 'fumadocs-mdx/config'
+import { z } from 'zod'
 import remarkDirective from 'remark-directive'
 import { remarkDirectiveAdmonition, remarkMdxMermaid } from 'fumadocs-core/mdx-plugins'
 import remarkUnusedDirectives from './src/lib/remark-unused-directives'
@@ -8,6 +9,12 @@ const contentDir = process.env.CHRONICLE_CONTENT_DIR || './content'
 export const docs = defineDocs({
   dir: contentDir,
   docs: {
+    schema: frontmatterSchema.extend({
+      order: z.number().optional(),
+    }),
+    postprocess: {
+      includeProcessedMarkdown: true,
+    },
     files: ['**/*.mdx', '**/*.md', '!**/node_modules/**'],
   },
 })
diff --git a/packages/chronicle/src/app/llms-full.txt/route.ts b/packages/chronicle/src/app/llms-full.txt/route.ts
@@ -0,0 +1,18 @@
+import { source } from '@/lib/source'
+import { loadConfig } from '@/lib/config'
+import { getLLMText } from '@/lib/get-llm-text'
+
+export const revalidate = false
+
+export async function GET() {
+  const config = loadConfig()
+
+  if (!config.llms?.enabled) {
+    return new Response('Not Found', { status: 404 })
+  }
+
+  const scan = source.getPages().map(getLLMText)
+  const scanned = await Promise.all(scan)
+
+  return new Response(scanned.join('\n\n'))
+}
diff --git a/packages/chronicle/src/app/llms.txt/route.ts b/packages/chronicle/src/app/llms.txt/route.ts
@@ -0,0 +1,15 @@
+import { source } from '@/lib/source'
+import { loadConfig } from '@/lib/config'
+import { llms } from 'fumadocs-core/source'
+
+export const revalidate = false
+
+export function GET() {
+  const config = loadConfig()
+
+  if (!config.llms?.enabled) {
+    return new Response('Not Found', { status: 404 })
+  }
+
+  return new Response(llms(source).index())
+}
diff --git a/packages/chronicle/src/cli/commands/build.ts b/packages/chronicle/src/cli/commands/build.ts
@@ -1,11 +1,11 @@
 import { Command } from 'commander'
 import { spawn } from 'child_process'
 import path from 'path'
+import { fileURLToPath } from 'url'
 import chalk from 'chalk'
 import { resolveContentDir, loadCLIConfig, attachLifecycleHandlers } from '@/cli/utils'
 
-declare const PACKAGE_ROOT: string
-
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
 const nextBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'next.cmd' : 'next')
 
 export const buildCommand = new Command('build')
diff --git a/packages/chronicle/src/cli/commands/dev.ts b/packages/chronicle/src/cli/commands/dev.ts
@@ -1,11 +1,11 @@
 import { Command } from 'commander'
 import { spawn } from 'child_process'
 import path from 'path'
+import { fileURLToPath } from 'url'
 import chalk from 'chalk'
 import { resolveContentDir, loadCLIConfig, attachLifecycleHandlers } from '@/cli/utils'
 
-declare const PACKAGE_ROOT: string
-
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
 const nextBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'next.cmd' : 'next')
 
 export const devCommand = new Command('dev')
diff --git a/packages/chronicle/src/cli/commands/serve.ts b/packages/chronicle/src/cli/commands/serve.ts
@@ -1,11 +1,11 @@
 import { Command } from 'commander'
 import { spawn } from 'child_process'
 import path from 'path'
+import { fileURLToPath } from 'url'
 import chalk from 'chalk'
 import { resolveContentDir, loadCLIConfig, attachLifecycleHandlers } from '@/cli/utils'
 
-declare const PACKAGE_ROOT: string
-
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
 const nextBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'next.cmd' : 'next')
 
 export const serveCommand = new Command('serve')
diff --git a/packages/chronicle/src/cli/commands/start.ts b/packages/chronicle/src/cli/commands/start.ts
@@ -1,11 +1,11 @@
 import { Command } from 'commander'
 import { spawn } from 'child_process'
 import path from 'path'
+import { fileURLToPath } from 'url'
 import chalk from 'chalk'
 import { resolveContentDir, loadCLIConfig, attachLifecycleHandlers } from '@/cli/utils'
 
-declare const PACKAGE_ROOT: string
-
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
 const nextBin = path.join(PACKAGE_ROOT, 'node_modules', '.bin', process.platform === 'win32' ? 'next.cmd' : 'next')
 
 export const startCommand = new Command('start')
diff --git a/packages/chronicle/src/lib/config.ts b/packages/chronicle/src/lib/config.ts
@@ -32,5 +32,6 @@ export function loadConfig(): ChronicleConfig {
     search: { ...defaultConfig.search, ...userConfig.search },
     footer: userConfig.footer,
     api: userConfig.api,
+    llms: { enabled: false, ...userConfig.llms },
   }
 }
diff --git a/packages/chronicle/src/lib/get-llm-text.ts b/packages/chronicle/src/lib/get-llm-text.ts
@@ -0,0 +1,10 @@
+import { source } from '@/lib/source'
+import type { InferPageType } from 'fumadocs-core/source'
+
+export async function getLLMText(page: InferPageType<typeof source>) {
+  const processed = await page.data.getText('processed')
+
+  return `# ${page.data.title} (${page.url})
+
+${processed}`
+}
diff --git a/packages/chronicle/src/lib/remark-unused-directives.ts b/packages/chronicle/src/lib/remark-unused-directives.ts
@@ -2,26 +2,25 @@ import { visit } from 'unist-util-visit'
 import type { Plugin } from 'unified'
 import type { Node } from 'unist'
 
-interface DirectiveNode extends Node {
-  name?: string
-  attributes?: Record<string, string>
-  children?: Node[]
-  data?: unknown
-  [key: string]: unknown
-}
-
 const remarkUnusedDirectives: Plugin = () => {
   return (tree) => {
-    visit(tree, ['textDirective'], (node: DirectiveNode) => {
-      if (!node.data) {
-        const hasAttributes = node.attributes && Object.keys(node.attributes).length > 0
-        const hasChildren = node.children && node.children.length > 0
+    visit(tree, ['textDirective'], (node) => {
+      const directive = node as Node & {
+        name?: string
+        attributes?: Record<string, string>
+        children?: Node[]
+        value?: string
+        [key: string]: unknown
+      }
+      if (!directive.data) {
+        const hasAttributes = directive.attributes && Object.keys(directive.attributes).length > 0
+        const hasChildren = directive.children && directive.children.length > 0
         if (!hasAttributes && !hasChildren) {
-          const name = node.name
+          const name = directive.name
           if (!name) return
-          Object.keys(node).forEach((key) => delete node[key])
-          node.type = 'text'
-          node.value = `:${name}`
+          Object.keys(directive).forEach((key) => delete directive[key])
+          directive.type = 'text'
+          directive.value = `:${name}`
         }
       }
     })
diff --git a/packages/chronicle/src/lib/source.ts b/packages/chronicle/src/lib/source.ts
@@ -51,11 +51,12 @@ export function buildPageTree(): PageTree {
   const folderItems: PageTreeItem[] = []
   folders.forEach((items, folder) => {
     const sorted = sortByOrder(items)
-    const indexPage = sorted[0]
+    const indexPage = items.find(item => item.url === `/${folder}`)
+    const folderOrder = indexPage?.order ?? sorted[0]?.order
     folderItems.push({
       type: 'folder',
       name: folder.charAt(0).toUpperCase() + folder.slice(1),
-      order: indexPage?.order,
+      order: folderOrder,
       children: sorted,
     })
   })
diff --git a/packages/chronicle/src/types/config.ts b/packages/chronicle/src/types/config.ts
@@ -7,6 +7,11 @@ export interface ChronicleConfig {
   search?: SearchConfig
   footer?: FooterConfig
   api?: ApiConfig[]
+  llms?: LlmsConfig
+}
+
+export interface LlmsConfig {
+  enabled?: boolean
 }
 
 export interface ApiConfig {
