@raystack/chronicle 0.1.0-canary.e11f924

package/src/cli/commands/serve.ts

@@ -0,0 +1,54 @@
+import { Command } from 'commander'
+import { spawn } from 'child_process'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { createRequire } from 'module'
+import chalk from 'chalk'
+import { resolveContentDir, loadCLIConfig, attachLifecycleHandlers } from '@/cli/utils'
+
+const require = createRequire(import.meta.url)
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const nextCli = require.resolve('next/dist/bin/next')
+
+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')
+  .action((options) => {
+    const contentDir = resolveContentDir(options.content)
+    loadCLIConfig(contentDir)
+
+    const env = {
+      ...process.env,
+      CHRONICLE_CONTENT_DIR: contentDir,
+    }
+
+    console.log(chalk.cyan('Building for production...'))
+    console.log(chalk.gray(`Content: ${contentDir}`))
+
+    const buildChild = spawn(process.execPath, [nextCli, 'build'], {
+      stdio: 'inherit',
+      cwd: PACKAGE_ROOT,
+      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: PACKAGE_ROOT,
+        env,
+      })
+
+      attachLifecycleHandlers(startChild)
+    })
+  })

package/src/cli/commands/start.ts

@@ -0,0 +1,34 @@
+import { Command } from 'commander'
+import { spawn } from 'child_process'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { createRequire } from 'module'
+import chalk from 'chalk'
+import { resolveContentDir, loadCLIConfig, attachLifecycleHandlers } from '@/cli/utils'
+
+const require = createRequire(import.meta.url)
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..')
+const nextCli = require.resolve('next/dist/bin/next')
+
+export const startCommand = new Command('start')
+  .description('Start production server')
+  .option('-p, --port <port>', 'Port number', '3000')
+  .option('-c, --content <path>', 'Content directory')
+  .action((options) => {
+    const contentDir = resolveContentDir(options.content)
+    loadCLIConfig(contentDir)
+
+    console.log(chalk.cyan('Starting production server...'))
+    console.log(chalk.gray(`Content: ${contentDir}`))
+
+    const child = spawn(process.execPath, [nextCli, 'start', '-p', options.port], {
+      stdio: 'inherit',
+      cwd: PACKAGE_ROOT,
+      env: {
+        ...process.env,
+        CHRONICLE_CONTENT_DIR: contentDir,
+      },
+    })
+
+    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 process.cwd()
+}
+
+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 './process'

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

package/src/components/api/endpoint-page.tsx

@@ -0,0 +1,283 @@
+'use client'
+
+import { useState, useCallback } from 'react'
+import type { OpenAPIV3 } from 'openapi-types'
+import { Flex, Text, Headline, Button, CodeBlock } from '@raystack/apsara'
+import { MethodBadge } from './method-badge'
+import { FieldSection } from './field-section'
+import { KeyValueEditor, type KeyValueEntry } from './key-value-editor'
+import { CodeSnippets } from './code-snippets'
+import { ResponsePanel } from './response-panel'
+import { flattenSchema, generateExampleJson, type SchemaField } from '@/lib/schema'
+import styles from './endpoint-page.module.css'
+
+interface EndpointPageProps {
+  method: string
+  path: string
+  operation: OpenAPIV3.OperationObject
+  serverUrl: string
+  specName: string
+  auth?: { type: string; header: string; placeholder?: string }
+}
+
+export function EndpointPage({ method, path, operation, serverUrl, specName, auth }: EndpointPageProps) {
+  const params = (operation.parameters ?? []) as OpenAPIV3.ParameterObject[]
+  const body = getRequestBody(operation.requestBody as OpenAPIV3.RequestBodyObject | undefined)
+
+  const headerFields = paramsToFields(params.filter((p) => p.in === 'header'))
+  const headerLocations = Object.fromEntries(headerFields.map((f) => [f.name, 'header']))
+  const pathFields = paramsToFields(params.filter((p) => p.in === 'path'))
+  const pathLocations = Object.fromEntries(pathFields.map((f) => [f.name, 'path']))
+  const queryFields = paramsToFields(params.filter((p) => p.in === 'query'))
+  const queryLocations = Object.fromEntries(queryFields.map((f) => [f.name, 'query']))
+  const responses = getResponseSections(operation.responses as Record<string, OpenAPIV3.ResponseObject>)
+
+  // State for editable fields
+  const [customHeaders, setCustomHeaders] = useState<KeyValueEntry[]>(() => {
+    const initial: KeyValueEntry[] = []
+    if (auth) initial.push({ key: auth.header, value: '' })
+    return initial
+  })
+  const [headerValues, setHeaderValues] = useState<Record<string, unknown>>({})
+  const [pathValues, setPathValues] = useState<Record<string, unknown>>({})
+  const [queryValues, setQueryValues] = useState<Record<string, unknown>>({})
+  const [bodyValues, setBodyValues] = useState<Record<string, unknown>>(() => {
+    try { return body?.jsonExample ? JSON.parse(body.jsonExample) : {} }
+    catch { return {} }
+  })
+  const [bodyJsonStr, setBodyJsonStr] = useState(body?.jsonExample ?? '{}')
+  const [responseBody, setResponseBody] = useState<{ status: number; statusText: string; body: unknown } | null>(null)
+  const [loading, setLoading] = useState(false)
+
+  // Two-way sync: fields → JSON
+  const handleBodyValuesChange = useCallback((values: Record<string, unknown>) => {
+    setBodyValues(values)
+    setBodyJsonStr(JSON.stringify(values, null, 2))
+  }, [])
+
+  // Two-way sync: JSON → fields
+  const handleBodyJsonChange = useCallback((jsonStr: string) => {
+    setBodyJsonStr(jsonStr)
+    try {
+      setBodyValues(JSON.parse(jsonStr))
+    } catch { /* ignore invalid JSON while typing */ }
+  }, [])
+
+  // Try it handler
+  const handleTryIt = useCallback(async () => {
+    setLoading(true)
+    setResponseBody(null)
+
+    let resolvedPath = path
+    for (const [key, value] of Object.entries(pathValues)) {
+      resolvedPath = resolvedPath.replace(`{${key}}`, encodeURIComponent(String(value)))
+    }
+
+    const queryEntries = Object.entries(queryValues).filter(([, v]) => v !== undefined && v !== '')
+    const queryString = queryEntries
+      .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+      .join('&')
+    const fullPath = queryString ? `${resolvedPath}?${queryString}` : resolvedPath
+
+    const reqHeaders: Record<string, string> = {}
+    for (const [key, value] of Object.entries(headerValues)) {
+      if (value !== undefined && value !== null && value !== '') reqHeaders[key] = String(value)
+    }
+    for (const entry of customHeaders) {
+      if (entry.key && entry.value) reqHeaders[entry.key] = entry.value
+    }
+    if (body && bodyJsonStr) {
+      reqHeaders['Content-Type'] = body.contentType ?? 'application/json'
+    }
+
+    try {
+      const res = await fetch('/api/apis-proxy', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          specName,
+          method,
+          path: fullPath,
+          headers: reqHeaders,
+          body: body ? bodyValues : undefined,
+        }),
+      })
+      const data = await res.json()
+      if (data.status !== undefined) {
+        setResponseBody(data)
+      } else {
+        setResponseBody({ status: res.status, statusText: res.statusText, body: data.error ?? data })
+      }
+    } catch (err) {
+      console.error('API request failed:', err)
+      setResponseBody({ status: 0, statusText: 'Error', body: 'Failed to send request' })
+    } finally {
+      setLoading(false)
+    }
+  }, [specName, method, path, pathValues, queryValues, headerValues, customHeaders, bodyValues, bodyJsonStr, body])
+
+  // Snippet display values
+  const fullUrl = '{domain}' + path
+  const snippetHeaders: Record<string, string> = {}
+  if (auth) {
+    snippetHeaders[auth.header] = auth.placeholder ?? 'YOUR_API_KEY'
+  }
+  if (body) {
+    snippetHeaders['Content-Type'] = body.contentType ?? 'application/json'
+  }
+
+  return (
+    <div className={styles.layout}>
+      <Flex direction="column" className={styles.left}>
+        {operation.summary && (
+          <Headline size="small" as="h1" className={styles.title}>{operation.summary}</Headline>
+        )}
+        {operation.description && (
+          <Text size={3} className={styles.description}>{operation.description}</Text>
+        )}
+
+        <Flex align="center" className={styles.methodPath}>
+          <MethodBadge method={method} />
+          <Text size={3} className={styles.path}>{path}</Text>
+          <Button variant="solid" size="small" className={styles.tryButton} onClick={handleTryIt} disabled={loading}>
+            {loading ? 'Sending...' : 'Send'}
+          </Button>
+        </Flex>
+
+        <FieldSection
+          title="Headers"
+          fields={headerFields}
+          locations={headerLocations}
+          editable
+          values={headerValues}
+          onValuesChange={setHeaderValues}
+        >
+          <KeyValueEditor entries={customHeaders} onChange={setCustomHeaders} />
+        </FieldSection>
+        <FieldSection
+          title="Path"
+          fields={pathFields}
+          locations={pathLocations}
+          editable
+          values={pathValues}
+          onValuesChange={setPathValues}
+        />
+        <FieldSection
+          title="Query Parameters"
+          fields={queryFields}
+          locations={queryLocations}
+          editable
+          values={queryValues}
+          onValuesChange={setQueryValues}
+        />
+        {body && (
+          <FieldSection
+            title="Body"
+            label={body?.contentType}
+            fields={body?.fields ?? []}
+            jsonExample={bodyJsonStr}
+            editableJson
+            onJsonChange={handleBodyJsonChange}
+            alwaysShow
+            editable
+            values={bodyValues}
+            onValuesChange={handleBodyValuesChange}
+          />
+        )}
+
+        {responses.map((resp) => (
+          <FieldSection
+            key={resp.status}
+            title={`${resp.status}${resp.description ? ` — ${resp.description}` : ''}`}
+            fields={resp.fields}
+            jsonExample={resp.jsonExample}
+          />
+        ))}
+      </Flex>
+      <Flex direction="column" className={styles.right}>
+        <CodeSnippets
+          method={method}
+          url={fullUrl}
+          headers={snippetHeaders}
+          body={body ? bodyJsonStr : undefined}
+        />
+        <ResponsePanel responses={responses} />
+        {responseBody && (
+          <Flex direction="column" gap="small">
+            <Text size={3} weight="medium">
+              Response — {responseBody.status} {responseBody.statusText}
+            </Text>
+            <CodeBlock>
+              <CodeBlock.Header>
+                <CodeBlock.CopyButton />
+              </CodeBlock.Header>
+              <CodeBlock.Content>
+                <CodeBlock.Code language="json">
+                  {typeof responseBody.body === 'string'
+                    ? (responseBody.body || 'No response body')
+                    : (JSON.stringify(responseBody.body, null, 2) ?? 'No response body')}
+                </CodeBlock.Code>
+              </CodeBlock.Content>
+            </CodeBlock>
+          </Flex>
+        )}
+      </Flex>
+    </div>
+  )
+}
+
+function paramsToFields(params: OpenAPIV3.ParameterObject[]): SchemaField[] {
+  return params.map((p) => {
+    const schema = (p.schema ?? {}) as OpenAPIV3.SchemaObject
+    return {
+      name: p.name,
+      type: schema.type ? String(schema.type) : 'string',
+      required: p.required ?? false,
+      description: p.description,
+      default: schema.default,
+    }
+  })
+}
+
+interface RequestBody {
+  contentType: string
+  fields: SchemaField[]
+  jsonExample: string
+}
+
+function getRequestBody(body: OpenAPIV3.RequestBodyObject | undefined): RequestBody | null {
+  if (!body?.content) return null
+  const contentType = Object.keys(body.content)[0]
+  if (!contentType) return null
+  const schema = body.content[contentType]?.schema as OpenAPIV3.SchemaObject | undefined
+  if (!schema) return null
+  return {
+    contentType,
+    fields: flattenSchema(schema),
+    jsonExample: JSON.stringify(generateExampleJson(schema), null, 2),
+  }
+}
+
+interface ResponseSection {
+  status: string
+  description?: string
+  fields: SchemaField[]
+  jsonExample?: string
+}
+
+function getResponseSections(responses: Record<string, OpenAPIV3.ResponseObject>): ResponseSection[] {
+  return Object.entries(responses).map(([status, resp]) => {
+    const content = resp.content ?? {}
+    const contentType = Object.keys(content)[0]
+    const schema = contentType
+      ? (content[contentType]?.schema as OpenAPIV3.SchemaObject | undefined)
+      : undefined
+
+    return {
+      status,
+      description: resp.description,
+      fields: schema ? flattenSchema(schema) : [],
+      jsonExample: schema ? JSON.stringify(generateExampleJson(schema), null, 2) : undefined,
+    }
+  })
+}