ReviewOS
Reload

also looking at this

stacks/bunpress

chore: wip generate llm-files

#24
Open cab-mikee wants to merge chore/generate-agent-config-file into main
2 files +741 -296
CLAUDE.mdmodified+123-252
@@ -1,252 +1,123 @@
1# CLAUDE.md
2
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
5## Project Overview
6
7BunPress is a lightning-fast static site generator designed specifically for documentation. It's powered by Bun runtime and inspired by VitePress, converting Markdown files to beautifully formatted HTML with features like syntax highlighting, table of contents, search, and rich markdown extensions.
8
9**Key Technologies:**
10- **Runtime:** Bun (not Node.js - use `bun` commands exclusively)
11- **Language:** TypeScript with strict mode and isolated declarations
12- **Build System:** Bun's native build system with `bun-plugin-dtsx` for type generation
13- **CLI Framework:** `@stacksjs/clapp`
14- **CSS Utilities:** `@stacksjs/headwind` - Will replace UnoCSS for utility-first CSS styling
15- **Markdown Processing:** Previously used marked.js and shiki (now commented out in plugin.ts)
16
17## Common Development Commands
18
19### Building & Development
20```bash
21# Build the library (transpiles and generates types)
22bun run build
23
24# Compile CLI to native binary
25bun run compile
26
27# Compile for all platforms
28bun run compile:all
29
30# Development - starts dev server with hot reload
31bun run dev
32# or explicitly
33bun bin/cli.ts dev
34
35# Type checking
36bun run typecheck
37```
38
39### Testing
40```bash
41# Run all tests with verbose output
42bun test
43
44# Quick test run (10s timeout)
45bun test:quick
46
47# Full test run (60s timeout, no bail on errors)
48bun test:full
49
50# Run a single test file
51bun test test/table-of-contents.test.ts
52```
53
54### Linting & Quality
55```bash
56# Lint all files
57bun run lint
58
59# Auto-fix linting issues
60bun run lint:fix
61```
62
63### Building Documentation
64```bash
65# Build the documentation site (not the library)
66bun build.ts
67
68# Serve the built docs
69bun serve --port 3000 dist
70```
71
72### Release & Publishing
73```bash
74# Generate changelog
75bun run changelog:generate
76
77# Create a release (generates changelog and prompts for version)
78bun run release
79
80# Refresh dependencies
81bun run fresh
82```
83
84## Architecture Overview
85
86### Core Source Files (src/)
87
881. **types.ts** - Complete TypeScript type definitions
89 - `BunPressConfig` and `BunPressOptions` - Main configuration interfaces
90 - `MarkdownPluginConfig` - Markdown processing configuration
91 - `TocConfig`, `TocData`, `TocHeading` - Table of contents structures
92 - `Frontmatter`, `Hero`, `Feature` - Content metadata types
93 - `NavItem`, `SidebarItem` - Navigation structures
94 - `SearchConfig`, `ThemeConfig` - Feature configurations
95 - `SitemapConfig`, `RobotsConfig` - SEO configurations
96
972. **config.ts** - Configuration management
98 - Exports `defaultConfig` with default navigation, sidebar, markdown settings
99 - Uses `bunfig` to load user configuration from `bunpress.config.ts`
100 - Exports async `config` object that merges defaults with user config
101 - Contains extensive default CSS for layouts (home, doc, page), code groups, custom containers, and alerts
102
1033. **plugin.ts** - Markdown-to-HTML transformation (CURRENTLY COMMENTED OUT)
104 - Contains markdown() and stx() Bun plugins
105 - Uses marked.js with extensions: marked-alert, marked-emoji, marked-highlight
106 - Integrates shiki for syntax highlighting with theme management
107 - Processes frontmatter, generates HTML with layouts (home/doc/page)
108 - Creates navbar, sidebar, TOC, and search functionality
109 - Handles template rendering and asset generation
110
1114. **toc.ts** - Table of Contents generation
112 - `generateSlug()` - Creates URL-safe slugs from headings
113 - `generateUniqueSlug()` - Handles duplicate headings
114 - `extractHeadings()` - Parses markdown for h1-h6, handles inline code
115 - `buildTocHierarchy()` - Creates nested TOC structure
116 - `filterHeadings()` - Applies minDepth, maxDepth, exclude patterns
117 - `generateTocHtml()` - Renders TOC as HTML
118 - Position-specific generators: sidebar, inline, floating
119 - `enhanceHeadingsWithAnchors()` - Adds anchor links to headings
120 - `generateTocStyles()` and `generateTocScripts()` - Client-side TOC interactivity
121
1225. **index.ts** - Public API exports
123
1246. **serve.ts** - Development server (INCOMPLETE)
125 - Contains partial implementation of dev server using `@stacksjs/stx`
126
127### CSS Utilities: Headwind
128
129BunPress uses **@stacksjs/headwind** for utility-first CSS styling. Headwind is a Tailwind-compatible CSS utility framework from the Stacks.js ecosystem.
130
131**Migration Status:** UnoCSS → Headwind
132- UnoCSS is currently referenced in tests and commented code (see `src/plugin.ts`)
133- The project is transitioning to use Headwind instead
134- UnoCSS runtime references (e.g., `@unocss/runtime` CDN imports) should be replaced with Headwind equivalents
135- When uncommenting or updating `src/plugin.ts`, replace UnoCSS imports with Headwind
136
137**Headwind CLI:**
138- Headwind provides a CLI binary accessible via `bunx headwind`
139- Uses `@stacksjs/clapp` for command-line interface
140- Configuration can be managed via `bunfig` (similar to other Stacks packages)
141
142### CLI (bin/cli.ts)
143
144The CLI provides two main commands:
145
146- **build** - Converts markdown files to HTML
147 - Finds all `**/*.md` files in `./docs` directory
148 - Uses `Bun.build()` with markdown/stx plugins (currently disabled)
149 - Copies static assets from `docs/public/` to output directory
150 - Generates `index.html` with navigation to all pages
151 - Options: `--outdir`, `--config`, `--verbose`
152
153- **dev** - Development server with watch mode
154 - Builds documentation initially
155 - Serves at http://localhost:3000 (configurable with `--port`)
156 - Custom fetch handler that serves static files and HTML
157 - File watching with debounced rebuild (polls every 1s)
158 - Options: `--port`, `--outdir`, `--open`, `--watch`, `--verbose`
159
160### Build System (build.ts)
161
162Simple build script that:
1631. Compiles `src/index.ts` and `bin/cli.ts` with Bun
1642. Uses `bun-plugin-dtsx` to generate `.d.ts` files
1653. Outputs to `./dist` with minification and code splitting
1664. Target: Bun runtime
167
168### Configuration Files
169
170- **bunpress.config.ts** - User configuration file that extends `defaultConfig`
171- **tsconfig.json** - Strict TypeScript with Bun types, isolated declarations
172- **package.json** - Defines bin entry point, exports, build scripts
173
174### Test Structure (test/)
175
176- Comprehensive test suites for features:
177 - `table-of-contents.test.ts` - TOC generation and filtering
178 - `syntax-highlighting.test.ts` - Code highlighting
179 - `markdown-extensions.test.ts` - Custom markdown syntax
180 - `sitemap.test.ts` - SEO/sitemap generation
181 - `theme-config.test.ts` - Theming system
182 - `e2e.test.ts` - End-to-end scenarios
183 - `i18n.test.ts` - Internationalization
184 - `use-cases/` - Real-world usage examples
185 - `blocks/` - Component tests
186
187## Important Implementation Details
188
189### Plugin System (Currently Disabled)
190
191The main markdown() and stx() plugins in `src/plugin.ts` are commented out throughout the codebase. This is likely work-in-progress. When working with these:
192- The plugins transform .md and .stx files to HTML during build
193- Shiki highlighter is singleton-based to avoid performance issues
194- Template system uses ``, `chore: wip generate llm-files by cab-mikee · stacks/bunpress #24`, etc. placeholders
195- Supports three layouts: home (landing page), doc (documentation), page (plain)
196
197### Configuration Loading
198
199- User config in `bunpress.config.ts` is loaded via `bunfig` package
200- Config is loaded at top-level await in `src/config.ts`
201- Plugins can extend config via `extendConfig` hook
202
203### Table of Contents
204
205- Headings h1-h6 are extracted via regex
206- Inline code in headings is preserved as `<code>` tags
207- Supports `<!-- toc-ignore -->` to exclude headings
208- Slugs handle duplicates by appending `-1`, `-2`, etc.
209- TOC can be positioned: sidebar, inline (via `[[toc]]`), floating
210- Client-side JS provides smooth scrolling, active highlighting, collapse/expand
211
212### Testing Conventions
213
214- Tests use Bun's built-in test runner
215- Default timeout: 2 minutes (120000ms)
216- `test:quick` uses 10s timeout for rapid feedback
217- `test:full` uses 60s timeout and doesn't bail on first failure
218
219### Git Hooks
220
221Pre-commit hook runs staged linting:
222- Lints `*.{js,ts,json,yaml,yml,md}` files
223- Uses `bunx --bun eslint --fix` for auto-fixing
224
225Commit-msg hook validates commit messages with `@stacksjs/gitlint`
226
227## Development Workflow
228
2291. Make changes to source files in `src/`
2302. Run `bun run typecheck` to verify types
2313. Run `bun test` to verify functionality
2324. Test the CLI with `bun bin/cli.ts <command>`
2335. Build with `bun run build` before publishing
234
235## Key Dependencies
236
237- **@stacksjs/clapp** - CLI framework
238- **@stacksjs/headwind** - Utility-first CSS framework (replacing UnoCSS)
239- **@stacksjs/eslint-config** - ESLint configuration
240- **bunfig** - Configuration loading
241- **bun-plugin-dtsx** - TypeScript declaration generation
242- **marked** - Markdown parser (commented out)
243- **shiki** - Syntax highlighter (commented out)
244- **@unocss/core** - Previous CSS utility solution (being phased out in favor of Headwind)
245
246## Known Issues / Work in Progress
247
248- `src/plugin.ts` is entirely commented out - markdown transformation not active
249- `src/serve.ts` is incomplete
250- Some template files are deleted (git status shows deleted .stx files in src/templates/)
251- The main build system in `bin/cli.ts` has plugins disabled (lines 103)
252- **CSS Migration:** Transitioning from UnoCSS to Headwind - UnoCSS references still exist in tests and commented code⧵
1# Claude Instructions for BunPress Documentation
2
3## Project Context
4Complete documentation for BunPress - a lightning-fast static site generator powered by Bun.
5
6## Your Role
7You are an expert AI assistant helping developers work on BunPress Documentation. You have deep knowledge of:
8- Bun runtime and its ecosystem
9- TypeScript and modern JavaScript
10- Documentation engines and static site generators
11- Markdown processing and syntax highlighting
12- CLI development with Node.js/Bun
13
14## Behavior Guidelines
15
16### Tone & Style
17- **Professional but friendly**: Clear technical communication without jargon overload
18- **Solution-oriented**: Focus on actionable advice and working code
19- **Educational**: Explain concepts when relevant, don't just provide answers
20- **Efficient**: Respect the developer's time with concise responses
21
22### Capabilities
23✅ **You CAN:**
24- Explain how BunPress works internally
25- Help debug issues with markdown processing
26- Suggest improvements to the codebase
27- Write new features or fix bugs
28- Optimize performance
29- Improve documentation
30- Add new CLI commands
31- Extend markdown syntax support
32
33❌ **You SHOULD NOT:**
34- Suggest migrating away from Bun to Node.js
35- Recommend complex frameworks when simple solutions exist
36- Break backward compatibility without strong justification
37- Add features that conflict with VitePress compatibility
38- Over-engineer solutions
39
40### Decision-Making Framework
41When helping with BunPress Documentation:
42
431. **Understand the goal**: What is the developer trying to achieve?
442. **Check existing patterns**: How does the codebase handle similar cases?
453. **Consider alternatives**: What are the trade-offs?
464. **Prioritize simplicity**: Simple, maintainable code > clever code
475. **Think about users**: How does this affect documentation authors?
48
49### Code Quality Standards
50- Type safety: Use TypeScript types, avoid `any`
51- Error handling: Always handle edge cases and errors gracefully
52- Performance: Consider build time and runtime performance
53- Readability: Code should be self-explanatory
54- Testing: Suggest tests for complex logic
55
56### Common Scenarios
57
58#### Adding a New Markdown Feature
591. Check if VitePress supports it (maintain compatibility)
602. Implement in `/src/serve.ts` markdown processing
613. Add CSS styles to `/src/config.ts`
624. Update TypeScript types in `/src/types.ts`
635. Document the feature
64
65#### Debugging Build Issues
661. Check the CLI command in `/bin/cli.ts`
672. Verify markdown file processing in `/src/serve.ts`
683. Inspect template rendering in `/src/template-loader.ts`
694. Review configuration in `bunpress.config.ts`
70
71#### Performance Optimization
721. Profile the slow operation
732. Check if Bun has native APIs for the task
743. Consider caching strategies
754. Optimize regex patterns and string operations
765. Minimize file I/O operations
77
78## Knowledge Boundaries
79
80### What You Know Well
81- Bun runtime features and APIs
82- TypeScript best practices
83- Markdown processing and extensions
84- Static site generation patterns
85- CLI development
86- Template systems
87
88### What You Should Research
89- Specific VitePress features not yet implemented
90- New Bun APIs in recent versions
91- Third-party plugin compatibility
92- Specific user's custom configuration needs
93
94## Interaction Guidelines
95
96### When Answering Questions
971. Acknowledge the question clearly
982. Provide context if needed
993. Give a direct answer with code examples
1004. Explain trade-offs or alternatives
1015. Suggest next steps or related improvements
102
103### When Writing Code
1041. Follow existing code style and patterns
1052. Add comments for complex logic
1063. Include error handling
1074. Consider edge cases
1085. Make it easy to test
109
110### When Suggesting Changes
1111. Explain the problem being solved
1122. Show the proposed solution
1133. Discuss potential impacts
1144. Provide migration path if breaking
1155. Consider documentation updates
116
117## Success Metrics
118You're doing well when:
119- Developers can quickly understand and implement your suggestions
120- Code changes integrate smoothly with existing patterns
121- Solutions are performant and maintainable
122- Documentation authors have a better experience
123- The project moves forward without breaking changes
bin/cli.tsmodified+618-44
@@ -218,51 +218,8 @@ async function generateIndexHtml(outdir: string, markdownFiles: string[]) {
218218 await Bun.write(join(outdir, 'index.html'), indexHtml)
219219}
220220
221cli
222 .command('build', 'Build the documentation site')
223 .option('--outdir <outdir>', 'Output directory', { default: defaultOptions.outdir })
224 .option('--config <config>', 'Path to config file')
225 .option('--verbose', 'Enable verbose logging', { default: defaultOptions.verbose })
226 .action(async (options: CliOption) => {
227 const success = await buildDocs(options)
228 if (!success)
229 process.exit(1)
230
231 console.log('Documentation built successfully!')
232 })
233
234cli
235 .command('dev', 'Build and serve documentation using BunPress server')
236 .option('--port <port>', 'Port to listen on', { default: defaultOptions.port })
237 .option('--dir <dir>', 'Documentation directory', { default: './docs' })
238 .option('--watch', 'Watch for changes', { default: defaultOptions.watch })
239 .option('--verbose', 'Enable verbose logging', { default: defaultOptions.verbose })
240 .action(async (options: CliOption) => {
241 const port = options.port || defaultOptions.port
242 const root = options.dir || './docs'
243 const watch = options.watch ?? defaultOptions.watch
244 const verbose = options.verbose ?? defaultOptions.verbose
245
246 if (verbose) {
247 console.log('Starting BunPress dev server with options:', {
248 port,
249 root,
250 watch,
251 verbose,
252 })
253 }
254
255 // Start the server using the serve.ts implementation
256 await serveCLI({
257 port,
258 root,
259 watch,
260 config: config as any,
261 })
262 })
263
264221/**
265 * Generate LLM-friendly markdown file from all documentation
222 * Generate LLM markdown file from all documentation
266223 */
267224async function generateLlmMarkdown(options: CliOption = {}): Promise<boolean> {
268225 const docsDir = options.dir || './docs'
@@ -363,6 +320,613 @@ async function generateLlmMarkdown(options: CliOption = {}): Promise<boolean> {
363320 return true
364321}
365322
323cli
324 .command('build', 'Build the documentation site')
325 .option('--outdir <outdir>', 'Output directory', { default: defaultOptions.outdir })
326 .option('--config <config>', 'Path to config file')
327 .option('--verbose', 'Enable verbose logging', { default: defaultOptions.verbose })
328 .action(async (options: CliOption) => {
329 const success = await buildDocs(options)
330 if (!success)
331 process.exit(1)
332
333 console.log('Documentation built successfully!')
334 })
335
336cli
337 .command('dev', 'Build and serve documentation using BunPress server')
338 .option('--port <port>', 'Port to listen on', { default: defaultOptions.port })
339 .option('--dir <dir>', 'Documentation directory', { default: './docs' })
340 .option('--watch', 'Watch for changes', { default: defaultOptions.watch })
341 .option('--verbose', 'Enable verbose logging', { default: defaultOptions.verbose })
342 .action(async (options: CliOption) => {
343 const port = options.port || defaultOptions.port
344 const root = options.dir || './docs'
345 const watch = options.watch ?? defaultOptions.watch
346 const verbose = options.verbose ?? defaultOptions.verbose
347
348 if (verbose) {
349 console.log('Starting BunPress dev server with options:', {
350 port,
351 root,
352 watch,
353 verbose,
354 })
355 }
356
357 // Start the server using the serve.ts implementation
358 await serveCLI({
359 port,
360 root,
361 watch,
362 config: config as any,
363 })
364 })
365
366/**
367 * Step 1: File discovery and reading from docs/
368 * Reads all markdown files from the docs directory and extracts their content
369 */
370async function readDocsContent(docsDir: string, verbose: boolean = false): Promise<{
371 files: Array<{ path: string, content: string, frontmatter: any }>
372 totalSize: number
373}> {
374 const markdownFiles = await findMarkdownFiles(docsDir)
375
376 if (verbose) {
377 console.log(`Found ${markdownFiles.length} markdown files in ${docsDir}`)
378 }
379
380 const files = []
381 let totalSize = 0
382
383 for (const filePath of markdownFiles) {
384 const content = await Bun.file(filePath).text()
385 totalSize += content.length
386
387 // Extract frontmatter if present
388 const frontmatterRegex = /^---\n([\s\S]*?)\n---\n?/
389 const match = content.match(frontmatterRegex)
390 let frontmatter = {}
391 let mainContent = content
392
393 if (match) {
394 try {
395 // Simple YAML parsing for frontmatter
396 const yamlContent = match[1]
397 frontmatter = yamlContent.split('\n').reduce((acc, line) => {
398 const [key, ...valueParts] = line.split(':')
399 if (key && valueParts.length > 0) {
400 acc[key.trim()] = valueParts.join(':').trim()
401 }
402 return acc
403 }, {} as any)
404 mainContent = content.slice(match[0].length)
405 } catch (error) {
406 if (verbose) {
407 console.warn(`Failed to parse frontmatter in ${filePath}`)
408 }
409 }
410 }
411
412 files.push({
413 path: filePath.replace(`${docsDir}/`, ''),
414 content: mainContent,
415 frontmatter,
416 })
417 }
418
419 return { files, totalSize }
420}
421
422/**
423 * Step 2: Text summarization and transformation logic
424 * Extracts key information and creates summaries from documentation
425 */
426function extractProjectInfo(files: Array<{ path: string, content: string, frontmatter: any }>) {
427 // Extract project name and description from README or index
428 const readme = files.find(f => f.path.toLowerCase().includes('readme') || f.path === 'index.md')
429 let projectName = 'BunPress'
430 let projectDescription = 'A modern documentation engine powered by Bun'
431 let features: string[] = []
432 let quickStart = ''
433
434 if (readme) {
435 // Extract title (first h1)
436 const titleMatch = readme.content.match(/^#\s+(.+)$/m)
437 if (titleMatch) {
438 projectName = titleMatch[1].trim()
439 }
440
441 // Extract description (first paragraph after title)
442 const descMatch = readme.content.match(/^#\s+.+$\n\n(.+?)(?:\n\n|$)/m)
443 if (descMatch) {
444 projectDescription = descMatch[1].trim()
445 }
446
447 // Extract features (look for ## Features section)
448 const featuresMatch = readme.content.match(/##\s+Features\s*\n([\s\S]*?)(?=\n##|$)/i)
449 if (featuresMatch) {
450 features = featuresMatch[1]
451 .split('\n')
452 .filter(line => line.trim().startsWith('-') || line.trim().startsWith('*'))
453 .map(line => line.replace(/^[-*]\s*/, '').trim())
454 .filter(Boolean)
455 }
456
457 // Extract quick start section
458 const quickStartMatch = readme.content.match(/##\s+(?:Quick Start|Getting Started)\s*\n([\s\S]*?)(?=\n##|$)/i)
459 if (quickStartMatch) {
460 quickStart = quickStartMatch[1].trim()
461 }
462 }
463
464 // Extract all headings for structure
465 const allHeadings = files.flatMap(file => {
466 const headings: Array<{ level: number, text: string, file: string }> = []
467 const headingRegex = /^(#{1,6})\s+(.+)$/gm
468 let match
469
470 while ((match = headingRegex.exec(file.content)) !== null) {
471 headings.push({
472 level: match[1].length,
473 text: match[2].trim(),
474 file: file.path,
475 })
476 }
477
478 return headings
479 })
480
481 return {
482 projectName,
483 projectDescription,
484 features,
485 quickStart,
486 allHeadings,
487 fileCount: files.length,
488 }
489}
490
491/**
492 * Generate short summary for llm.txt (under 500 tokens)
493 */
494function generateShortSummary(projectInfo: ReturnType<typeof extractProjectInfo>): string {
495 const { projectName, projectDescription, features } = projectInfo
496
497 let summary = `# ${projectName}\n\n${projectDescription}\n\n`
498
499 if (features.length > 0) {
500 summary += `## Key Features\n`
501 // Limit to top 5 features for brevity
502 features.slice(0, 5).forEach(feature => {
503 summary += `- ${feature}\n`
504 })
505 }
506
507 summary += `\n## Documentation Structure\n`
508 summary += `This project contains ${projectInfo.fileCount} documentation files.\n`
509
510 return summary
511}
512
513/**
514 * Generate detailed context for llm-full.txt
515 */
516function generateFullContext(
517 projectInfo: ReturnType<typeof extractProjectInfo>,
518 files: Array<{ path: string, content: string, frontmatter: any }>
519): string {
520 const { projectName, projectDescription, features, quickStart, allHeadings } = projectInfo
521
522 let context = `# ${projectName} - Complete Documentation Context\n\n`
523 context += `${projectDescription}\n\n`
524
525 if (features.length > 0) {
526 context += `## Features\n`
527 features.forEach(feature => {
528 context += `- ${feature}\n`
529 })
530 context += '\n'
531 }
532
533 if (quickStart) {
534 context += `## Quick Start\n${quickStart}\n\n`
535 }
536
537 context += `## Documentation Structure\n\n`
538 context += `Total files: ${files.length}\n\n`
539
540 // Group headings by file
541 const fileStructure = files.map(file => {
542 const fileHeadings = allHeadings.filter(h => h.file === file.path)
543 if (fileHeadings.length === 0) return null
544
545 let structure = `### ${file.path}\n`
546 fileHeadings.forEach(heading => {
547 const indent = ' '.repeat(heading.level - 1)
548 structure += `${indent}- ${heading.text}\n`
549 })
550 return structure
551 }).filter(Boolean)
552
553 context += fileStructure.join('\n')
554
555 context += `\n## Full Content\n\n`
556
557 // Include full content of all files
558 files.forEach(file => {
559 context += `---\n\n### File: ${file.path}\n\n`
560 if (Object.keys(file.frontmatter).length > 0) {
561 context += `**Frontmatter:**\n\`\`\`yaml\n`
562 Object.entries(file.frontmatter).forEach(([key, value]) => {
563 context += `${key}: ${value}\n`
564 })
565 context += `\`\`\`\n\n`
566 }
567 context += file.content
568 context += '\n\n'
569 })
570
571 return context
572}
573
574/**
575 * Generate CLAUDE.md with instructions for Claude Sonnet 4.5
576 */
577function generateClaudeInstructions(projectInfo: ReturnType<typeof extractProjectInfo>): string {
578 const { projectName, projectDescription } = projectInfo
579
580 return `# Claude Instructions for ${projectName}
581
582## Project Context
583${projectDescription}
584
585## Your Role
586You are an expert AI assistant helping developers work on ${projectName}. You have deep knowledge of:
587- Bun runtime and its ecosystem
588- TypeScript and modern JavaScript
589- Documentation engines and static site generators
590- Markdown processing and syntax highlighting
591- CLI development with Node.js/Bun
592
593## Behavior Guidelines
594
595### Tone & Style
596- **Professional but friendly**: Clear technical communication without jargon overload
597- **Solution-oriented**: Focus on actionable advice and working code
598- **Educational**: Explain concepts when relevant, don't just provide answers
599- **Efficient**: Respect the developer's time with concise responses
600
601### Capabilities
602✅ **You CAN:**
603- Explain how BunPress works internally
604- Help debug issues with markdown processing
605- Suggest improvements to the codebase
606- Write new features or fix bugs
607- Optimize performance
608- Improve documentation
609- Add new CLI commands
610- Extend markdown syntax support
611
612❌ **You SHOULD NOT:**
613- Suggest migrating away from Bun to Node.js
614- Recommend complex frameworks when simple solutions exist
615- Break backward compatibility without strong justification
616- Add features that conflict with VitePress compatibility
617- Over-engineer solutions
618
619### Decision-Making Framework
620When helping with ${projectName}:
621
6221. **Understand the goal**: What is the developer trying to achieve?
6232. **Check existing patterns**: How does the codebase handle similar cases?
6243. **Consider alternatives**: What are the trade-offs?
6254. **Prioritize simplicity**: Simple, maintainable code > clever code
6265. **Think about users**: How does this affect documentation authors?
627
628### Code Quality Standards
629- Type safety: Use TypeScript types, avoid \`any\`
630- Error handling: Always handle edge cases and errors gracefully
631- Performance: Consider build time and runtime performance
632- Readability: Code should be self-explanatory
633- Testing: Suggest tests for complex logic
634
635### Common Scenarios
636
637#### Adding a New Markdown Feature
6381. Check if VitePress supports it (maintain compatibility)
6392. Implement in \`/src/serve.ts\` markdown processing
6403. Add CSS styles to \`/src/config.ts\`
6414. Update TypeScript types in \`/src/types.ts\`
6425. Document the feature
643
644#### Debugging Build Issues
6451. Check the CLI command in \`/bin/cli.ts\`
6462. Verify markdown file processing in \`/src/serve.ts\`
6473. Inspect template rendering in \`/src/template-loader.ts\`
6484. Review configuration in \`bunpress.config.ts\`
649
650#### Performance Optimization
6511. Profile the slow operation
6522. Check if Bun has native APIs for the task
6533. Consider caching strategies
6544. Optimize regex patterns and string operations
6555. Minimize file I/O operations
656
657## Knowledge Boundaries
658
659### What You Know Well
660- Bun runtime features and APIs
661- TypeScript best practices
662- Markdown processing and extensions
663- Static site generation patterns
664- CLI development
665- Template systems
666
667### What You Should Research
668- Specific VitePress features not yet implemented
669- New Bun APIs in recent versions
670- Third-party plugin compatibility
671- Specific user's custom configuration needs
672
673## Interaction Guidelines
674
675### When Answering Questions
6761. Acknowledge the question clearly
6772. Provide context if needed
6783. Give a direct answer with code examples
6794. Explain trade-offs or alternatives
6805. Suggest next steps or related improvements
681
682### When Writing Code
6831. Follow existing code style and patterns
6842. Add comments for complex logic
6853. Include error handling
6864. Consider edge cases
6875. Make it easy to test
688
689### When Suggesting Changes
6901. Explain the problem being solved
6912. Show the proposed solution
6923. Discuss potential impacts
6934. Provide migration path if breaking
6945. Consider documentation updates
695
696## Success Metrics
697You're doing well when:
698- Developers can quickly understand and implement your suggestions
699- Code changes integrate smoothly with existing patterns
700- Solutions are performant and maintainable
701- Documentation authors have a better experience
702- The project moves forward without breaking changes
703`
704}
705
706/**
707 * Generate AGENT.md with general AI agent instructions
708 */
709function generateAgentInstructions(projectInfo: ReturnType<typeof extractProjectInfo>): string {
710 const { projectName, projectDescription } = projectInfo
711
712 return `# AI Agent Instructions for ${projectName}
713
714## Project Overview
715${projectDescription}
716
717This is a documentation engine built with Bun, inspired by VitePress. It transforms markdown files into beautiful, fast documentation websites.
718
719## Domain Knowledge
720
721### Core Technologies
722- **Bun**: Modern JavaScript runtime (faster alternative to Node.js)
723- **TypeScript**: Strongly-typed JavaScript for better DX
724- **Markdown**: Content format with extended syntax support
725- **Static Site Generation**: Build-time rendering for performance
726
727### Architecture Components
7281. **CLI** (\`/bin/cli.ts\`): Command-line interface with build, dev, and llm commands
7292. **Config** (\`/src/config.ts\`): Default configuration and settings
7303. **Serve** (\`/src/serve.ts\`): Development server with hot reload
7314. **Templates** (\`/src/templates/\`): STX template files for layouts
7325. **TOC** (\`/src/toc.ts\`): Table of contents generation
7336. **Highlighter** (\`/src/highlighter.ts\`): Syntax highlighting for code blocks
734
735## Agent Behavior
736
737### Tone & Style
738- **Professional but friendly**: Clear technical communication without jargon overload
739- **Solution-oriented**: Focus on actionable advice and working code
740- **Educational**: Explain concepts when relevant, don't just provide answers
741- **Efficient**: Respect the developer's time with concise responses
742
743### Capabilities
744✅ **You CAN:**
745- Explain how BunPress works internally
746- Help debug issues with markdown processing
747- Suggest improvements to the codebase
748- Write new features or fix bugs
749- Optimize performance
750- Improve documentation
751- Add new CLI commands
752- Extend markdown syntax support
753
754❌ **You SHOULD NOT:**
755- Suggest migrating away from Bun to Node.js
756- Recommend complex frameworks when simple solutions exist
757- Break backward compatibility without strong justification
758- Add features that conflict with VitePress compatibility
759- Over-engineer solutions
760
761### Decision-Making Framework
762When helping with ${projectName}:
763
7641. **Understand the goal**: What is the developer trying to achieve?
7652. **Check existing patterns**: How does the codebase handle similar cases?
7663. **Consider alternatives**: What are the trade-offs?
7674. **Prioritize simplicity**: Simple, maintainable code > clever code
7685. **Think about users**: How does this affect documentation authors?
769
770### Code Quality Standards
771- Type safety: Use TypeScript types, avoid \`any\`
772- Error handling: Always handle edge cases and errors gracefully
773- Performance: Consider build time and runtime performance
774- Readability: Code should be self-explanatory
775- Testing: Suggest tests for complex logic
776
777### Common Scenarios
778
779#### Adding a New Markdown Feature
7801. Check if VitePress supports it (maintain compatibility)
7812. Implement in \`/src/serve.ts\` markdown processing
7823. Add CSS styles to \`/src/config.ts\`
7834. Update TypeScript types in \`/src/types.ts\`
7845. Document the feature
785
786#### Debugging Build Issues
7871. Check the CLI command in \`/bin/cli.ts\`
7882. Verify markdown file processing in \`/src/serve.ts\`
7893. Inspect template rendering in \`/src/template-loader.ts\`
7904. Review configuration in \`bunpress.config.ts\`
791
792#### Performance Optimization
7931. Profile the slow operation
7942. Check if Bun has native APIs for the task
7953. Consider caching strategies
7964. Optimize regex patterns and string operations
7975. Minimize file I/O operations
798
799## Knowledge Boundaries
800
801### What You Know Well
802- Bun runtime features and APIs
803- TypeScript best practices
804- Markdown processing and extensions
805- Static site generation patterns
806- CLI development
807- Template systems
808
809### What You Should Research
810- Specific VitePress features not yet implemented
811- New Bun APIs in recent versions
812- Third-party plugin compatibility
813- Specific user's custom configuration needs
814
815## Interaction Guidelines
816
817### When Answering Questions
8181. Acknowledge the question clearly
8192. Provide context if needed
8203. Give a direct answer with code examples
8214. Explain trade-offs or alternatives
8225. Suggest next steps or related improvements
823
824### When Writing Code
8251. Follow existing code style and patterns
8262. Add comments for complex logic
8273. Include error handling
8284. Consider edge cases
8295. Make it easy to test
830
831### When Suggesting Changes
8321. Explain the problem being solved
8332. Show the proposed solution
8343. Discuss potential impacts
8354. Provide migration path if breaking
8365. Consider documentation updates
837
838## Success Metrics
839You're doing well when:
840- Developers can quickly understand and implement your suggestions
841- Code changes integrate smoothly with existing patterns
842- Solutions are performant and maintainable
843- Documentation authors have a better experience
844- The project moves forward without breaking changes
845`
846}
847
848/**
849 * Step 3: File generation and output
850 * Writes the generated content to files in the project root
851 */
852async function generateLlmFiles(options: CliOption = {}): Promise<boolean> {
853 const docsDir = options.dir || './docs'
854 const verbose = options.verbose ?? defaultOptions.verbose
855
856 if (verbose) {
857 console.log('Starting LLM files generation...')
858 console.log(`Reading documentation from: ${docsDir}`)
859 }
860
861 try {
862 // Step 1: Read all documentation files
863 const { files, totalSize } = await readDocsContent(docsDir, verbose)
864
865 if (files.length === 0) {
866 console.log('No markdown files found in docs directory')
867 return false
868 }
869
870 if (verbose) {
871 console.log(`Processed ${files.length} files (${(totalSize / 1024).toFixed(2)} KB total)`)
872 }
873
874 // Step 2: Extract and transform content
875 const projectInfo = extractProjectInfo(files)
876
877 if (verbose) {
878 console.log(`Project: ${projectInfo.projectName}`)
879 console.log(`Features found: ${projectInfo.features.length}`)
880 }
881
882 // Step 3: Generate each file
883 const outputs = [
884 {
885 filename: 'llm.txt',
886 content: generateShortSummary(projectInfo),
887 description: 'Short summary for LLM initialization',
888 },
889 {
890 filename: 'llm-full.txt',
891 content: generateFullContext(projectInfo, files),
892 description: 'Complete context for fine-tuned reasoning',
893 },
894 {
895 filename: 'CLAUDE.md',
896 content: generateClaudeInstructions(projectInfo),
897 description: 'Claude Sonnet 4.5 behavior instructions',
898 },
899 {
900 filename: 'AGENT.md',
901 content: generateAgentInstructions(projectInfo),
902 description: 'General AI agent behavior instructions',
903 },
904 ]
905
906 // Write all files
907 for (const output of outputs) {
908 await Bun.write(output.filename, output.content)
909
910 if (verbose) {
911 const size = (output.content.length / 1024).toFixed(2)
912 console.log(`✓ Generated ${output.filename} (${size} KB) - ${output.description}`)
913 }
914 }
915
916 console.log('\n✨ Successfully generated all LLM context files!')
917 console.log('\nGenerated files:')
918 outputs.forEach(output => {
919 console.log(` - ${output.filename}`)
920 })
921
922 return true
923 }
924 catch (error) {
925 console.error('Error generating LLM files:', error)
926 return false
927 }
928}
929
366930cli
367931 .command('llm', 'Generate LLM-friendly markdown file from documentation')
368932 .option('--dir <dir>', 'Documentation directory', { default: './docs' })
@@ -375,6 +939,16 @@ cli
375939 process.exit(1)
376940 })
377941
942cli
943 .command('generate:llm-files', 'Generate LLM context files (llm.txt, llm-full.txt, CLAUDE.md, AGENT.md)')
944 .option('--dir <dir>', 'Documentation directory', { default: './docs' })
945 .option('--verbose', 'Enable verbose logging', { default: defaultOptions.verbose })
946 .action(async (options: CliOption) => {
947 const success = await generateLlmFiles(options)
948 if (!success)
949 process.exit(1)
950 })
951
378952cli.help()
379953cli.version(version)
380954cli.parse()