@raystack/chronicle 0.1.0-canary.30bf0df

package/src/cli/commands/init.ts

@@ -0,0 +1,163 @@
+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 { loadCLIConfig, scaffoldDir, detectPackageManager } from '@/cli/utils'
+
+
+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': 'latest',
+    },
+    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 it doesn't exist
+    if (!fs.existsSync(contentDir)) {
+      fs.mkdirSync(contentDir, { recursive: true })
+      console.log(chalk.green('✓'), 'Created', contentDir)
+    }
+
+    // Create or update package.json in project root
+    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('✓'), 'Created', packageJsonPath)
+    } else {
+      const existing = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))
+      const template = createPackageJson(dirName)
+      let updated = false
+
+      // Set type to module
+      if (existing.type !== 'module') {
+        existing.type = 'module'
+        updated = true
+      }
+
+      // Merge missing scripts
+      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
+        }
+      }
+
+      // Merge missing dependencies
+      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
+        }
+      }
+
+      // Merge missing devDependencies
+      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('✓'), 'Updated', packageJsonPath, 'with missing scripts/deps')
+      } else {
+        console.log(chalk.yellow('⚠'), packageJsonPath, 'already has all required entries')
+      }
+    }
+
+    // Create chronicle.yaml in project root
+    const configPath = path.join(projectDir, 'chronicle.yaml')
+    if (!fs.existsSync(configPath)) {
+      fs.writeFileSync(configPath, stringify(createConfig()))
+      console.log(chalk.green('✓'), 'Created', configPath)
+    } else {
+      console.log(chalk.yellow('⚠'), configPath, 'already exists')
+    }
+
+    // Create sample index.mdx only if content dir is empty
+    const contentFiles = fs.readdirSync(contentDir)
+    if (contentFiles.length === 0) {
+      const indexPath = path.join(contentDir, 'index.mdx')
+      fs.writeFileSync(indexPath, sampleMdx)
+      console.log(chalk.green('✓'), 'Created', indexPath)
+    }
+
+    // Add entries to .gitignore
+    const gitignorePath = path.join(projectDir, '.gitignore')
+    const gitignoreEntries = ['.chronicle', 'node_modules', '.next']
+    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('✓'), 'Added', missing.join(', '), 'to .gitignore')
+      }
+    } else {
+      fs.writeFileSync(gitignorePath, `${gitignoreEntries.join('\n')}\n`)
+      console.log(chalk.green('✓'), 'Created .gitignore')
+    }
+
+    // Install dependencies
+    const pm = detectPackageManager()
+    console.log(chalk.cyan(`\nInstalling dependencies with ${pm}...`))
+    execSync(`${pm} install`, { cwd: projectDir, stdio: 'inherit' })
+
+    // Scaffold .chronicle/ directory
+    loadCLIConfig(contentDir)
+    scaffoldDir(contentDir)
+
+    const runCmd = pm === 'npm' ? 'npx' : pm === 'bun' ? 'bunx' : `${pm} dlx`
+    console.log(chalk.green('\n✓ Chronicle initialized!'))
+    console.log('\nRun', chalk.cyan(`${runCmd} chronicle dev`), 'to start development server')
+  })

package/src/cli/commands/serve.ts

@@ -0,0 +1,53 @@
+import { Command } from 'commander'
+import { spawn } from 'child_process'
+import path from 'path'
+import fs from 'fs'
+import chalk from 'chalk'
+import { attachLifecycleHandlers, resolveNextCli } from '@/cli/utils'
+
+export const serveCommand = new Command('serve')
+  .description('Build and start production server')
+  .option('-p, --port <port>', 'Port number', '3000')
+  .action((options) => {
+    const scaffoldPath = path.join(process.cwd(), '.chronicle')
+    if (!fs.existsSync(scaffoldPath)) {
+      console.log(chalk.red('Error: .chronicle/ not found. Run'), chalk.cyan('chronicle init'), chalk.red('first.'))
+      process.exit(1)
+    }
+
+    const nextCli = resolveNextCli()
+
+    const env = {
+      ...process.env,
+      CHRONICLE_PROJECT_ROOT: process.cwd(),
+      CHRONICLE_CONTENT_DIR: './content',
+    }
+
+    console.log(chalk.cyan('Building for production...'))
+
+    const buildChild = spawn(process.execPath, [nextCli, 'build'], {
+      stdio: 'inherit',
+      cwd: scaffoldPath,
+      env,
+    })
+
+    process.once('SIGINT', () => buildChild.kill('SIGINT'))
+    process.once('SIGTERM', () => buildChild.kill('SIGTERM'))
+
+    buildChild.on('close', (code) => {
+      if (code !== 0) {
+        console.log(chalk.red('Build failed'))
+        process.exit(code ?? 1)
+      }
+
+      console.log(chalk.cyan('Starting production server...'))
+
+      const startChild = spawn(process.execPath, [nextCli, 'start', '-p', options.port], {
+        stdio: 'inherit',
+        cwd: scaffoldPath,
+        env,
+      })
+
+      attachLifecycleHandlers(startChild)
+    })
+  })

package/src/cli/commands/start.ts

@@ -0,0 +1,33 @@
+import { Command } from 'commander'
+import { spawn } from 'child_process'
+import path from 'path'
+import fs from 'fs'
+import chalk from 'chalk'
+import { attachLifecycleHandlers, resolveNextCli } from '@/cli/utils'
+
+export const startCommand = new Command('start')
+  .description('Start production server')
+  .option('-p, --port <port>', 'Port number', '3000')
+  .action((options) => {
+    const scaffoldPath = path.join(process.cwd(), '.chronicle')
+    if (!fs.existsSync(scaffoldPath)) {
+      console.log(chalk.red('Error: .chronicle/ not found. Run'), chalk.cyan('chronicle init'), chalk.red('first.'))
+      process.exit(1)
+    }
+
+    const nextCli = resolveNextCli()
+
+    console.log(chalk.cyan('Starting production server...'))
+
+    const child = spawn(process.execPath, [nextCli, 'start', '-p', options.port], {
+      stdio: 'inherit',
+      cwd: scaffoldPath,
+      env: {
+        ...process.env,
+        CHRONICLE_PROJECT_ROOT: process.cwd(),
+        CHRONICLE_CONTENT_DIR: './content',
+      },
+    })
+
+    attachLifecycleHandlers(child)
+  })

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,3 @@
+export * from './config'
+export * from './process'
+export * from './scaffold'

package/src/cli/utils/process.ts

@@ -0,0 +1,7 @@
+import type { ChildProcess } from 'child_process'
+
+export function attachLifecycleHandlers(child: ChildProcess) {
+  child.on('close', (code) => process.exit(code ?? 0))
+  process.on('SIGINT', () => child.kill('SIGINT'))
+  process.on('SIGTERM', () => child.kill('SIGTERM'))
+}

package/src/cli/utils/resolve.ts

@@ -0,0 +1,4 @@
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')

package/src/cli/utils/scaffold.ts

@@ -0,0 +1,131 @@
+import { execSync } from 'child_process'
+import { createRequire } from 'module'
+import fs from 'fs'
+import path from 'path'
+import chalk from 'chalk'
+import { PACKAGE_ROOT } from './resolve'
+
+const COPY_FILES = ['src', 'source.config.ts', 'tsconfig.json']
+
+function copyRecursive(src: string, dest: string) {
+  const stat = fs.statSync(src)
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true })
+    for (const entry of fs.readdirSync(src)) {
+      copyRecursive(path.join(src, entry), path.join(dest, entry))
+    }
+  } else {
+    fs.copyFileSync(src, dest)
+  }
+}
+
+function ensureRemoved(targetPath: string) {
+  try {
+    fs.lstatSync(targetPath)
+    fs.rmSync(targetPath, { recursive: true, force: true })
+  } catch {
+    // nothing exists, proceed
+  }
+}
+
+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'
+}
+
+function generateNextConfig(scaffoldPath: string) {
+  const config = `import { createMDX } from 'fumadocs-mdx/next'
+
+const withMDX = createMDX()
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+}
+
+export default withMDX(nextConfig)
+`
+  fs.writeFileSync(path.join(scaffoldPath, 'next.config.mjs'), config)
+}
+
+function createPackageJson(): Record<string, unknown> {
+  return {
+    name: 'chronicle-docs',
+    private: true,
+    dependencies: {
+      '@raystack/chronicle': 'latest',
+    },
+    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',
+    },
+  }
+}
+
+function ensureDeps() {
+  const cwd = process.cwd()
+  const cwdPkgJson = path.join(cwd, 'package.json')
+  const cwdNodeModules = path.join(cwd, 'node_modules')
+
+  if (fs.existsSync(cwdPkgJson) && fs.existsSync(cwdNodeModules)) {
+    // Case 1: existing project with deps installed
+    return
+  }
+
+  // Case 2: no package.json — create in cwd and install
+  if (!fs.existsSync(cwdPkgJson)) {
+    fs.writeFileSync(cwdPkgJson, JSON.stringify(createPackageJson(), null, 2) + '\n')
+  }
+
+  if (!fs.existsSync(cwdNodeModules)) {
+    const pm = detectPackageManager()
+    console.log(chalk.cyan(`Installing dependencies with ${pm}...`))
+    execSync(`${pm} install`, { cwd, stdio: 'inherit' })
+  }
+}
+
+export function resolveNextCli(): string {
+  const cwdRequire = createRequire(path.join(process.cwd(), 'package.json'))
+  return cwdRequire.resolve('next/dist/bin/next')
+}
+
+export function scaffoldDir(contentDir: string): string {
+  const scaffoldPath = path.join(process.cwd(), '.chronicle')
+
+  // Create .chronicle/ if not exists
+  if (!fs.existsSync(scaffoldPath)) {
+    fs.mkdirSync(scaffoldPath, { recursive: true })
+  }
+
+  // Copy package files
+  for (const name of COPY_FILES) {
+    const src = path.join(PACKAGE_ROOT, name)
+    const dest = path.join(scaffoldPath, name)
+    ensureRemoved(dest)
+    copyRecursive(src, dest)
+  }
+
+  // Generate next.config.mjs
+  generateNextConfig(scaffoldPath)
+
+  // Symlink content dir
+  const contentLink = path.join(scaffoldPath, 'content')
+  ensureRemoved(contentLink)
+  fs.symlinkSync(path.resolve(contentDir), contentLink)
+
+  // Ensure dependencies are available
+  ensureDeps()
+
+  console.log(chalk.gray(`Scaffold: ${scaffoldPath}`))
+
+  return scaffoldPath
+}

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;
+  }
+}