@raystack/chronicle 0.1.0-canary.111b55a

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@raystack/chronicle",
+  "version": "0.1.0-canary.111b55a",
+  "description": "Config-driven documentation framework",
+  "license": "Apache-2.0",
+  "type": "module",
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "templates",
+    "tsconfig.json"
+  ],
+  "bin": {
+    "chronicle": "./bin/chronicle.js"
+  },
+  "scripts": {
+    "build:cli": "bun build-cli.ts"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.13",
+    "@raystack/tools-config": "0.56.0",
+    "@types/lodash": "^4.17.23",
+    "@types/mdx": "^2.0.13",
+    "@types/node": "^25.1.0",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "@types/semver": "^7.7.1",
+    "semver": "^7.7.4",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/state": "^6.5.4",
+    "@codemirror/theme-one-dark": "^6.1.3",
+    "@codemirror/view": "^6.39.14",
+    "@heroicons/react": "^2.2.0",
+    "@mdx-js/rollup": "^3.1.1",
+    "@raystack/apsara": "^0.56.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "chalk": "^5.6.2",
+    "class-variance-authority": "^0.7.1",
+    "codemirror": "^6.0.2",
+    "commander": "^14.0.2",
+    "glob": "^11.0.0",
+    "gray-matter": "^4.0.3",
+    "lodash": "^4.17.23",
+    "mermaid": "^11.13.0",
+    "openapi-types": "^12.1.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.13.1",
+    "remark-directive": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "@shikijs/rehype": "^4.0.2",
+    "remark-frontmatter": "^5.0.0",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "satori": "^0.25.0",
+    "sirv": "^3.0.1",
+    "slugify": "^1.6.6",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
+    "minisearch": "^7.2.0",
+    "vite": "^8.0.0",
+    "yaml": "^2.8.2"
+  }
+}

package/src/cli/__tests__/config.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from 'vitest'
+import { resolveContentDir } from '../utils/config'
+
+describe('resolveContentDir', () => {
+  it('returns flag value when provided', () => {
+    const result = resolveContentDir('/custom/path')
+    expect(result).toBe('/custom/path')
+  })
+
+  it('returns env var when set', () => {
+    const original = process.env.CHRONICLE_CONTENT_DIR
+    process.env.CHRONICLE_CONTENT_DIR = '/env/content'
+    const result = resolveContentDir()
+    expect(result).toContain('env/content')
+    process.env.CHRONICLE_CONTENT_DIR = original
+  })
+
+  it('defaults to content directory', () => {
+    const original = process.env.CHRONICLE_CONTENT_DIR
+    delete process.env.CHRONICLE_CONTENT_DIR
+    const result = resolveContentDir()
+    expect(result).toContain('content')
+    process.env.CHRONICLE_CONTENT_DIR = original
+  })
+})

package/src/cli/__tests__/scaffold.test.ts

@@ -0,0 +1,10 @@
+import { describe, it, expect } from 'vitest'
+import { detectPackageManager } from '../utils/scaffold'
+
+describe('detectPackageManager', () => {
+  it('returns a string', () => {
+    const result = detectPackageManager()
+    expect(typeof result).toBe('string')
+    expect(['npm', 'bun', 'pnpm', 'yarn']).toContain(result)
+  })
+})

package/src/cli/commands/build.ts

@@ -0,0 +1,74 @@
+import { Command } from 'commander'
+import path from 'path'
+import chalk from 'chalk'
+import { resolveContentDir } from '@/cli/utils/config'
+import { PACKAGE_ROOT } from '@/cli/utils/resolve'
+
+export const buildCommand = new Command('build')
+  .description('Build for production')
+  .option('-c, --content <path>', 'Content directory')
+  .option('-o, --outDir <path>', 'Output directory', 'dist')
+  .option('--adapter <adapter>', 'Deploy adapter (vercel)')
+  .action(async (options) => {
+    const contentDir = resolveContentDir(options.content)
+    const outDir = path.resolve(options.outDir)
+
+    process.env.CHRONICLE_PROJECT_ROOT = process.cwd()
+    process.env.CHRONICLE_CONTENT_DIR = contentDir
+
+    console.log(chalk.cyan('Building for production...'))
+
+    const { build } = await import('vite')
+    const { createViteConfig } = await import('@/server/vite-config')
+
+    const baseConfig = await createViteConfig({ root: PACKAGE_ROOT, contentDir })
+
+    // Build client bundle
+    console.log(chalk.gray('Building client...'))
+    await build({
+      ...baseConfig,
+      build: {
+        outDir: path.join(outDir, 'client'),
+        ssrManifest: true,
+        rolldownOptions: {
+          input: path.resolve(PACKAGE_ROOT, 'src/server/index.html'),
+        },
+      },
+    })
+
+    // Build server bundle
+    const serverEntry = options.adapter === 'vercel'
+      ? path.resolve(PACKAGE_ROOT, 'src/server/entry-vercel.ts')
+      : path.resolve(PACKAGE_ROOT, 'src/server/entry-prod.ts')
+
+    console.log(chalk.gray('Building server...'))
+    await build({
+      ...baseConfig,
+      ssr: {
+        noExternal: true,
+      },
+      build: {
+        outDir: path.join(outDir, 'server'),
+        ssr: serverEntry,
+        target: 'node22',
+      },
+    })
+
+    // Generate search index
+    console.log(chalk.gray('Building search index...'))
+    const { generateSearchIndex } = await import('@/server/build-search-index')
+    const docCount = await generateSearchIndex(contentDir, path.join(outDir, 'server'))
+    console.log(chalk.gray(`  Indexed ${docCount} documents`))
+
+    console.log(chalk.green('Build complete →'), outDir)
+
+    // Run Vercel adapter post-build
+    if (options.adapter === 'vercel') {
+      const { buildVercelOutput } = await import('@/server/adapters/vercel')
+      await buildVercelOutput({
+        distDir: outDir,
+        contentDir,
+        projectRoot: process.cwd(),
+      })
+    }
+  })

package/src/cli/commands/dev.ts

@@ -0,0 +1,21 @@
+import { Command } from 'commander'
+import chalk from 'chalk'
+import { resolveContentDir } from '@/cli/utils/config'
+import { PACKAGE_ROOT } from '@/cli/utils/resolve'
+
+export const devCommand = new Command('dev')
+  .description('Start development server')
+  .option('-p, --port <port>', 'Port number', '3000')
+  .option('-c, --content <path>', 'Content directory')
+  .action(async (options) => {
+    const contentDir = resolveContentDir(options.content)
+    const port = parseInt(options.port, 10)
+
+    process.env.CHRONICLE_PROJECT_ROOT = process.cwd()
+    process.env.CHRONICLE_CONTENT_DIR = contentDir
+
+    console.log(chalk.cyan('Starting dev server...'))
+
+    const { startDevServer } = await import('@/server/dev')
+    await startDevServer({ port, root: PACKAGE_ROOT, contentDir })
+  })

package/src/cli/commands/init.ts

@@ -0,0 +1,154 @@
+import { Command } from 'commander'
+import { execSync } from 'child_process'
+import fs from 'fs'
+import path from 'path'
+import chalk from 'chalk'
+import { stringify } from 'yaml'
+import type { ChronicleConfig } from '@/types'
+import { detectPackageManager, getChronicleVersion } from '@/cli/utils/scaffold'
+
+function createConfig(): ChronicleConfig {
+  return {
+    title: 'My Documentation',
+    description: 'Documentation powered by Chronicle',
+    theme: { name: 'default' },
+    search: { enabled: true, placeholder: 'Search documentation...' },
+  }
+}
+
+function createPackageJson(name: string): Record<string, unknown> {
+  return {
+    name,
+    private: true,
+    type: 'module',
+    scripts: {
+      dev: 'chronicle dev',
+      build: 'chronicle build',
+      start: 'chronicle start',
+    },
+    dependencies: {
+      '@raystack/chronicle': `^${getChronicleVersion()}`,
+    },
+    devDependencies: {
+      '@raystack/tools-config': '0.56.0',
+      'openapi-types': '^12.1.3',
+      typescript: '5.9.3',
+      '@types/react': '^19.2.10',
+      '@types/node': '^25.1.0',
+    },
+  }
+}
+
+const sampleMdx = `---
+title: Welcome
+description: Getting started with your documentation
+order: 1
+---
+
+# Welcome
+
+This is your documentation home page.
+`
+
+export const initCommand = new Command('init')
+  .description('Initialize a new Chronicle project')
+  .option('-c, --content <path>', 'Content directory name', 'content')
+  .action((options) => {
+    const projectDir = process.cwd()
+    const dirName = path.basename(projectDir) || 'docs'
+    const contentDir = path.join(projectDir, options.content)
+
+    // Create content directory
+    if (!fs.existsSync(contentDir)) {
+      fs.mkdirSync(contentDir, { recursive: true })
+      console.log(chalk.green('\u2713'), 'Created', contentDir)
+    }
+
+    // Create or update package.json
+    const packageJsonPath = path.join(projectDir, 'package.json')
+    if (!fs.existsSync(packageJsonPath)) {
+      fs.writeFileSync(packageJsonPath, JSON.stringify(createPackageJson(dirName), null, 2) + '\n')
+      console.log(chalk.green('\u2713'), 'Created', packageJsonPath)
+    } else {
+      const existing = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))
+      const template = createPackageJson(dirName)
+      let updated = false
+
+      if (existing.type !== 'module') {
+        existing.type = 'module'
+        updated = true
+      }
+
+      if (!existing.scripts) existing.scripts = {}
+      for (const [key, value] of Object.entries(template.scripts as Record<string, string>)) {
+        if (!existing.scripts[key]) {
+          existing.scripts[key] = value
+          updated = true
+        }
+      }
+
+      if (!existing.dependencies) existing.dependencies = {}
+      for (const [key, value] of Object.entries(template.dependencies as Record<string, string>)) {
+        if (!existing.dependencies[key]) {
+          existing.dependencies[key] = value
+          updated = true
+        }
+      }
+
+      if (!existing.devDependencies) existing.devDependencies = {}
+      for (const [key, value] of Object.entries(template.devDependencies as Record<string, string>)) {
+        if (!existing.devDependencies[key]) {
+          existing.devDependencies[key] = value
+          updated = true
+        }
+      }
+
+      if (updated) {
+        fs.writeFileSync(packageJsonPath, JSON.stringify(existing, null, 2) + '\n')
+        console.log(chalk.green('\u2713'), 'Updated', packageJsonPath)
+      } else {
+        console.log(chalk.yellow('\u26a0'), packageJsonPath, 'already has all required entries')
+      }
+    }
+
+    // Create chronicle.yaml
+    const configPath = path.join(projectDir, 'chronicle.yaml')
+    if (!fs.existsSync(configPath)) {
+      fs.writeFileSync(configPath, stringify(createConfig()))
+      console.log(chalk.green('\u2713'), 'Created', configPath)
+    } else {
+      console.log(chalk.yellow('\u26a0'), configPath, 'already exists')
+    }
+
+    // Create sample index.mdx
+    const contentFiles = fs.readdirSync(contentDir)
+    if (contentFiles.length === 0) {
+      const indexPath = path.join(contentDir, 'index.mdx')
+      fs.writeFileSync(indexPath, sampleMdx)
+      console.log(chalk.green('\u2713'), 'Created', indexPath)
+    }
+
+    // Update .gitignore
+    const gitignorePath = path.join(projectDir, '.gitignore')
+    const gitignoreEntries = ['node_modules', 'dist']
+    if (fs.existsSync(gitignorePath)) {
+      const existing = fs.readFileSync(gitignorePath, 'utf-8')
+      const missing = gitignoreEntries.filter(e => !existing.includes(e))
+      if (missing.length > 0) {
+        fs.appendFileSync(gitignorePath, `\n${missing.join('\n')}\n`)
+        console.log(chalk.green('\u2713'), 'Added', missing.join(', '), 'to .gitignore')
+      }
+    } else {
+      fs.writeFileSync(gitignorePath, `${gitignoreEntries.join('\n')}\n`)
+      console.log(chalk.green('\u2713'), 'Created .gitignore')
+    }
+
+    // Install dependencies
+    const pm = detectPackageManager()
+    console.log(chalk.cyan(`\nInstalling dependencies with ${pm}...`))
+    execSync(`${pm} install`, { cwd: projectDir, stdio: 'inherit' })
+
+    const runCmd = pm === 'npm' ? 'npx' : pm === 'bun' ? 'bunx' : `${pm} dlx`
+    console.log(chalk.green('\n\u2713 Chronicle initialized!'))
+    console.log('\nRun', chalk.cyan(`${runCmd} chronicle dev`), 'to start development server')
+  })

package/src/cli/commands/serve.ts

@@ -0,0 +1,55 @@
+import { Command } from 'commander'
+import path from 'path'
+import chalk from 'chalk'
+import { resolveContentDir } from '@/cli/utils/config'
+import { PACKAGE_ROOT } from '@/cli/utils/resolve'
+
+export const serveCommand = new Command('serve')
+  .description('Build and start production server')
+  .option('-p, --port <port>', 'Port number', '3000')
+  .option('-c, --content <path>', 'Content directory')
+  .option('-o, --outDir <path>', 'Output directory', 'dist')
+  .action(async (options) => {
+    const contentDir = resolveContentDir(options.content)
+    const port = parseInt(options.port, 10)
+    const outDir = path.resolve(options.outDir)
+
+    process.env.CHRONICLE_PROJECT_ROOT = process.cwd()
+    process.env.CHRONICLE_CONTENT_DIR = contentDir
+
+    // Build
+    console.log(chalk.cyan('Building for production...'))
+
+    const { build } = await import('vite')
+    const { createViteConfig } = await import('@/server/vite-config')
+
+    const baseConfig = await createViteConfig({ root: PACKAGE_ROOT, contentDir })
+
+    await build({
+      ...baseConfig,
+      build: {
+        outDir: path.join(outDir, 'client'),
+        ssrManifest: true,
+        rolldownOptions: {
+          input: path.resolve(PACKAGE_ROOT, 'src/server/index.html'),
+        },
+      },
+    })
+
+    await build({
+      ...baseConfig,
+      ssr: {
+        noExternal: true,
+      },
+      build: {
+        outDir: path.join(outDir, 'server'),
+        ssr: path.resolve(PACKAGE_ROOT, 'src/server/entry-prod.ts'),
+      },
+    })
+
+    // Start
+    console.log(chalk.cyan('Starting production server...'))
+
+    const { startProdServer } = await import('@/server/prod')
+    await startProdServer({ port, root: PACKAGE_ROOT, distDir: outDir })
+  })

package/src/cli/commands/start.ts

@@ -0,0 +1,24 @@
+import { Command } from 'commander'
+import path from 'path'
+import chalk from 'chalk'
+import { resolveContentDir } from '@/cli/utils/config'
+import { PACKAGE_ROOT } from '@/cli/utils/resolve'
+
+export const startCommand = new Command('start')
+  .description('Start production server')
+  .option('-p, --port <port>', 'Port number', '3000')
+  .option('-c, --content <path>', 'Content directory')
+  .option('-d, --dist <path>', 'Dist directory', 'dist')
+  .action(async (options) => {
+    const contentDir = resolveContentDir(options.content)
+    const port = parseInt(options.port, 10)
+    const distDir = path.resolve(options.dist)
+
+    process.env.CHRONICLE_PROJECT_ROOT = process.cwd()
+    process.env.CHRONICLE_CONTENT_DIR = contentDir
+
+    console.log(chalk.cyan('Starting production server...'))
+
+    const { startProdServer } = await import('@/server/prod')
+    await startProdServer({ port, root: PACKAGE_ROOT, distDir })
+  })

package/src/cli/index.ts

@@ -0,0 +1,21 @@
+import { Command } from 'commander'
+import { initCommand } from './commands/init'
+import { devCommand } from './commands/dev'
+import { buildCommand } from './commands/build'
+import { startCommand } from './commands/start'
+import { serveCommand } from './commands/serve'
+
+const program = new Command()
+
+program
+  .name('chronicle')
+  .description('Config-driven documentation framework')
+  .version('0.1.0')
+
+program.addCommand(initCommand)
+program.addCommand(devCommand)
+program.addCommand(buildCommand)
+program.addCommand(startCommand)
+program.addCommand(serveCommand)
+
+program.parse()

package/src/cli/utils/config.ts

@@ -0,0 +1,43 @@
+import fs from 'fs'
+import path from 'path'
+import { parse } from 'yaml'
+import chalk from 'chalk'
+import type { ChronicleConfig } from '@/types'
+
+export interface CLIConfig {
+  config: ChronicleConfig
+  configPath: string
+  contentDir: string
+}
+
+export function resolveContentDir(contentFlag?: string): string {
+  if (contentFlag) return path.resolve(contentFlag)
+  if (process.env.CHRONICLE_CONTENT_DIR) return path.resolve(process.env.CHRONICLE_CONTENT_DIR)
+  return path.resolve('content')
+}
+
+function resolveConfigPath(contentDir: string): string | null {
+  const cwdPath = path.join(process.cwd(), 'chronicle.yaml')
+  if (fs.existsSync(cwdPath)) return cwdPath
+  const contentPath = path.join(contentDir, 'chronicle.yaml')
+  if (fs.existsSync(contentPath)) return contentPath
+  return null
+}
+
+export function loadCLIConfig(contentDir: string): CLIConfig {
+  const configPath = resolveConfigPath(contentDir)
+
+  if (!configPath) {
+    console.log(chalk.red(`Error: chronicle.yaml not found in '${process.cwd()}' or '${contentDir}'`))
+    console.log(chalk.gray(`Run 'chronicle init' to create one`))
+    process.exit(1)
+  }
+
+  const config = parse(fs.readFileSync(configPath, 'utf-8')) as ChronicleConfig
+
+  return {
+    config,
+    configPath,
+    contentDir,
+  }
+}

package/src/cli/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './config'
+export * from './resolve'

package/src/cli/utils/resolve.ts

@@ -0,0 +1,6 @@
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+// After bundling: dist/cli/index.js → ../.. = package root
+// After install: node_modules/@raystack/chronicle/dist/cli/index.js → ../.. = package root
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')

package/src/cli/utils/scaffold.ts

@@ -0,0 +1,20 @@
+import fs from 'fs'
+import path from 'path'
+import { PACKAGE_ROOT } from './resolve'
+
+export function detectPackageManager(): string {
+  if (process.env.npm_config_user_agent) {
+    return process.env.npm_config_user_agent.split('/')[0]
+  }
+  const cwd = process.cwd()
+  if (fs.existsSync(path.join(cwd, 'bun.lock')) || fs.existsSync(path.join(cwd, 'bun.lockb'))) return 'bun'
+  if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return 'pnpm'
+  if (fs.existsSync(path.join(cwd, 'yarn.lock'))) return 'yarn'
+  return 'npm'
+}
+
+export function getChronicleVersion(): string {
+  const pkgPath = path.join(PACKAGE_ROOT, 'package.json')
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+  return pkg.version
+}

package/src/components/api/code-snippets.module.css

@@ -0,0 +1,7 @@
+.snippets {
+  width: 100%;
+}
+
+.snippets :global([class*="code-block-module_header"]) {
+  justify-content: space-between;
+}

package/src/components/api/code-snippets.tsx

@@ -0,0 +1,76 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import { CodeBlock } from "@raystack/apsara";
+import {
+  generateCurl,
+  generatePython,
+  generateGo,
+  generateTypeScript,
+} from "@/lib/snippet-generators";
+import styles from "./code-snippets.module.css";
+
+interface CodeSnippetsProps {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: string;
+}
+
+const languages = [
+  { value: "curl", label: "cURL", lang: "curl", generate: generateCurl },
+  {
+    value: "python",
+    label: "Python",
+    lang: "python",
+    generate: generatePython,
+  },
+  { value: "go", label: "Go", lang: "go", generate: generateGo },
+  {
+    value: "typescript",
+    label: "TypeScript",
+    lang: "typescript",
+    generate: generateTypeScript,
+  },
+];
+
+export function CodeSnippets({
+  method,
+  url,
+  headers,
+  body,
+}: CodeSnippetsProps) {
+  const opts = { method, url, headers, body };
+  const [selected, setSelected] = useState("curl");
+  const current = languages.find((l) => l.value === selected) ?? languages[0];
+
+  const code = useMemo(
+    () => current.generate(opts),
+    [selected, method, url, headers, body],
+  );
+
+  return (
+    <CodeBlock
+      value={selected}
+      onValueChange={setSelected}
+      className={styles.snippets}
+    >
+      <CodeBlock.Header>
+        <CodeBlock.LanguageSelect>
+          <CodeBlock.LanguageSelectTrigger />
+          <CodeBlock.LanguageSelectContent>
+            {languages.map((l) => (
+              <CodeBlock.LanguageSelectItem key={l.value} value={l.value}>
+                {l.label}
+              </CodeBlock.LanguageSelectItem>
+            ))}
+          </CodeBlock.LanguageSelectContent>
+        </CodeBlock.LanguageSelect>
+        <CodeBlock.CopyButton />
+      </CodeBlock.Header>
+      <CodeBlock.Content>
+        <CodeBlock.Code language={current.lang}>{code}</CodeBlock.Code>
+      </CodeBlock.Content>
+    </CodeBlock>
+  );
+}

package/src/components/api/endpoint-page.module.css

@@ -0,0 +1,58 @@
+.layout {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: var(--rs-space-9);
+  padding: var(--rs-space-7);
+  max-width: 1400px;
+}
+
+.left {
+  gap: var(--rs-space-7);
+  min-width: 0;
+}
+
+.right {
+  gap: var(--rs-space-5);
+  min-width: 0;
+}
+
+.title {
+  margin: 0;
+}
+
+.description {
+  color: var(--rs-color-foreground-base-secondary);
+}
+
+.methodPath {
+  gap: var(--rs-space-3);
+  padding: var(--rs-space-4) var(--rs-space-5);
+  border: 1px solid var(--rs-color-border-base-primary);
+  border-radius: 8px;
+  background: var(--rs-color-background-base-secondary);
+  overflow: hidden;
+}
+
+.path {
+  font-family: monospace;
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.tryButton {
+  margin-left: auto;
+  flex-shrink: 0;
+}
+
+@media (max-width: 900px) {
+  .layout {
+    grid-template-columns: 1fr;
+  }
+
+  .right {
+    position: static;
+  }
+}