specra 0.1.0

package/src/lib/config.server.ts

@@ -0,0 +1,170 @@
+import specraConfigJson from "../specra.config.json"
+import { SpecraConfig, defaultConfig } from "./config.types"
+
+/**
+ * Deep merge two objects
+ */
+function deepMerge<T extends Record<string, any>>(target: T, source: Partial<T>): T {
+  const result = { ...target }
+
+  for (const key in source) {
+    const sourceValue = source[key]
+    const targetValue = result[key]
+
+    if (sourceValue && typeof sourceValue === "object" && !Array.isArray(sourceValue)) {
+      result[key] = deepMerge(
+        targetValue && typeof targetValue === "object" ? targetValue : {},
+        sourceValue,
+      ) as T[Extract<keyof T, string>]
+    } else if (sourceValue !== undefined) {
+      result[key] = sourceValue as T[Extract<keyof T, string>]
+    }
+  }
+
+  return result
+}
+
+/**
+ * Load and parse the Specra configuration file
+ * Falls back to default configuration if file doesn't exist or is invalid
+ */
+export function loadConfig(userConfig: Partial<SpecraConfig>): SpecraConfig {
+  try {
+    // const userConfig = specraConfigJson as unknown as Partial<SpecraConfig>
+
+    // Merge user config with defaults  
+    const config = deepMerge(defaultConfig, userConfig)
+
+    return config
+  } catch (error) {
+    console.error(`❌ Error loading configuration:`, error)
+    console.warn("Using default configuration.")
+    return defaultConfig
+  }
+}
+
+/**
+ * Get a specific configuration value by path (SERVER ONLY)
+ * Example: getConfigValue('site.title') or getConfigValue('theme.defaultMode')
+ */
+export function getConfigValue<T = any>(path: string, config?: SpecraConfig): T | undefined {
+  const cfg = config || loadConfig({})
+  const keys = path.split(".")
+  let value: any = cfg
+
+  for (const key of keys) {
+    if (value && typeof value === "object" && key in value) {
+      value = value[key]
+    } else {
+      return undefined
+    }
+  }
+
+  return value as T
+}
+
+/**
+ * Replace environment variables in a string (SERVER ONLY)
+ * Supports ${ENV_VAR} and {{ENV_VAR}} syntax
+ */
+export function replaceEnvVariables(text: string, config?: SpecraConfig): string {
+  const cfg = config || loadConfig({})
+  const envVars = cfg.env || {}
+
+  let result = text
+
+  // Replace ${VAR} syntax
+  result = result.replace(/\$\{([^}]+)\}/g, (match, varName) => {
+    return envVars[varName] || match
+  })
+
+  // Replace {{VAR}} syntax
+  result = result.replace(/\{\{([^}]+)\}\}/g, (match, varName) => {
+    return envVars[varName] || match
+  })
+
+  return result
+}
+
+/**
+ * Process content and replace all environment variables (SERVER ONLY)
+ */
+export function processContentWithEnv(content: string, config?: SpecraConfig): string {
+  return replaceEnvVariables(content, config)
+}
+
+/**
+ * Validate configuration (basic validation) (SERVER ONLY)
+ */
+export function validateConfig(config: SpecraConfig): { valid: boolean; errors: string[] } {
+  const errors: string[] = []
+
+  // Required fields
+  if (!config.site?.title) {
+    errors.push("site.title is required")
+  }
+
+  // URL validation
+  if (config.site?.url) {
+    try {
+      new URL(config.site.url)
+    } catch {
+      errors.push("site.url must be a valid URL")
+    }
+  }
+
+  // Social links validation
+  if (config.social) {
+    const socialKeys = ["github", "twitter", "discord", "linkedin", "youtube"] as const
+    for (const key of socialKeys) {
+      const url = config.social[key]
+      if (url) {
+        try {
+          new URL(url)
+        } catch {
+          errors.push(`social.${key} must be a valid URL`)
+        }
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  }
+}
+
+// Singleton instance
+let configInstance: SpecraConfig | null = null
+
+export function initConfig(userConfig: Partial<SpecraConfig>): SpecraConfig {
+  if (configInstance) {
+    throw new Error("Specra config has already been initialized")
+  }
+
+  configInstance = loadConfig(userConfig)
+  return configInstance
+}
+
+/**
+ * Get the configuration instance (cached) (SERVER ONLY)
+ */
+export function getConfig(): SpecraConfig {
+  if (!configInstance) {
+    throw new Error("Specra config has not been initialized")
+  }
+  return configInstance
+}
+
+/**
+ * Reload the configuration (useful for development) (SERVER ONLY)
+ */
+export function reloadConfig(userConfig: Partial<SpecraConfig>): SpecraConfig {
+  configInstance = loadConfig(userConfig)
+  return configInstance
+}
+
+/**
+ * Export the loaded config as default (SERVER ONLY)
+ */
+// export default getConfig()

package/src/lib/config.ts

@@ -0,0 +1,20 @@
+/**
+ * Client-safe config access
+ * This file re-exports server functions but is safe to import in client components
+ * The actual config loading happens on the server and is passed as props
+ */
+
+export { defaultConfig } from "./config.types"
+export type { SpecraConfig } from "./config.types"
+
+// For client components, config should be passed as props from server components
+// These are re-exported for convenience but will only work on the server
+export {
+  getConfig,
+  getConfigValue,
+  loadConfig,
+  processContentWithEnv,
+  replaceEnvVariables,
+  validateConfig,
+  reloadConfig,
+} from "./config.server"

package/src/lib/config.types.ts

@@ -0,0 +1,295 @@
+/**
+ * Configuration schema for Specra documentation system
+ */
+
+/**
+ * Site metadata and branding
+ */
+export interface SiteConfig {
+  /** The title of the documentation site */
+  title: string
+  /** Short description of the documentation */
+  description?: string
+  /** URL where the documentation is hosted */
+  url?: string
+  /** Base URL path for the documentation (e.g., '/docs') */
+  baseUrl?: string
+  /** Path to the site logo */
+  logo?: string
+  /** Path to the favicon */
+  favicon?: string
+  /** Default language for the documentation */
+  language?: string
+  /** Organization or author name */
+  organizationName?: string
+  /** Project name */
+  projectName?: string
+  /** Active/default version for the documentation */
+  activeVersion?: string
+}
+
+/**
+ * Theme and appearance settings
+ */
+export interface ThemeConfig {
+  /** Primary color for the theme */
+  primaryColor?: string
+  /** Default theme mode */
+  defaultMode?: "light" | "dark" | "system"
+  /** Whether to respect system preferences */
+  respectPrefersColorScheme?: boolean
+  /** Custom CSS file path */
+  customCss?: string
+}
+
+/**
+ * Tab group for organizing documentation
+ */
+export interface TabGroup {
+  /** Unique identifier for the tab group */
+  id: string
+  /** Display label for the tab */
+  label: string
+  /** Optional icon name (lucide-react icon) */
+  icon?: string
+}
+
+/**
+ * Navigation and sidebar configuration
+ */
+export interface NavigationConfig {
+  /** Whether to show the sidebar by default */
+  showSidebar?: boolean
+  /** Whether the sidebar is collapsible */
+  collapsibleSidebar?: boolean
+  /** Whether to show breadcrumbs */
+  showBreadcrumbs?: boolean
+  /** Whether to show table of contents */
+  showTableOfContents?: boolean
+  /** Position of table of contents */
+  tocPosition?: "left" | "right"
+  /** Maximum depth for table of contents */
+  tocMaxDepth?: number
+  /** Tab groups for organizing documentation sections */
+  tabGroups?: TabGroup[]
+}
+
+/**
+ * Social and external links
+ */
+export interface SocialLinks {
+  /** GitHub repository URL */
+  github?: string
+  /** Twitter/X handle or URL */
+  twitter?: string
+  /** Discord invite URL */
+  discord?: string
+  /** LinkedIn profile or company page */
+  linkedin?: string
+  /** YouTube channel URL */
+  youtube?: string
+  /** Custom social links */
+  custom?: Array<{
+    label: string
+    url: string
+    icon?: string
+  }>
+}
+
+/**
+ * Search configuration
+ */
+export interface SearchConfig {
+  /** Enable/disable search functionality */
+  enabled?: boolean
+  /** Placeholder text for search input */
+  placeholder?: string
+  /** Search provider type */
+  provider?: "meilisearch" | "algolia" | "local"
+  /** Meilisearch configuration */
+  meilisearch?: {
+    /** Meilisearch server URL */
+    host: string
+    /** API key for Meilisearch */
+    apiKey?: string
+    /** Index name */
+    indexName: string
+  }
+}
+
+/**
+ * Analytics configuration
+ */
+export interface AnalyticsConfig {
+  /** Google Analytics tracking ID */
+  googleAnalytics?: string
+  /** Google Tag Manager ID */
+  googleTagManager?: string
+  /** Plausible Analytics domain */
+  plausible?: string
+  /** Custom analytics scripts */
+  custom?: Array<{
+    src: string
+    async?: boolean
+    defer?: boolean
+  }>
+}
+
+/**
+ * Footer configuration
+ */
+export interface FooterConfig {
+  /** Copyright text */
+  copyright?: string
+  /** Footer links organized by columns */
+  links?: Array<{
+    title: string
+    items: Array<{
+      label: string
+      href: string
+    }>
+  }>
+  /** Custom footer content */
+  customContent?: string
+}
+
+/**
+ * Documentation features
+ */
+export interface FeaturesConfig {
+  /** Enable/disable edit this page links */
+  editUrl?: string | false
+  /** Show last updated timestamp */
+  showLastUpdated?: boolean
+  /** Show reading time estimate */
+  showReadingTime?: boolean
+  /** Show author information */
+  showAuthors?: boolean
+  /** Show tags */
+  showTags?: boolean
+  /** Enable version dropdown */
+  versioning?: boolean
+  /** Enable i18n (internationalization) */
+  i18n?: boolean
+}
+
+/**
+ * Site-wide banner configuration
+ */
+export interface BannerConfig {
+  /** Whether the banner is enabled */
+  enabled?: boolean
+  /** Banner message */
+  message?: string
+  /** Banner type */
+  type?: "info" | "warning" | "success" | "error"
+  /** Whether the banner can be dismissed */
+  dismissible?: boolean
+}
+
+/**
+ * Environment variables that can be used in documentation
+ * These will be replaced at build time or runtime
+ */
+export interface EnvironmentVariables {
+  /** API base URL */
+  API_BASE_URL?: string
+  /** API version */
+  API_VERSION?: string
+  /** CDN URL */
+  CDN_URL?: string
+  /** Custom environment variables */
+  [key: string]: string | undefined
+}
+
+/**
+ * Deployment configuration for different hosting scenarios
+ */
+export interface DeploymentConfig {
+  /**
+   * Deployment target
+   * - 'vercel': For Vercel or similar Node.js hosting (uses 'standalone' output)
+   * - 'github-pages': For GitHub Pages static hosting (uses 'export' output)
+   * - 'static': For any static hosting like Netlify, Cloudflare Pages, etc.
+   * - 'custom-domain-static': For static hosting with custom domain (no basePath needed)
+   */
+  target?: "vercel" | "github-pages" | "static" | "custom-domain-static"
+
+  /**
+   * Base path for assets when deploying to GitHub Pages without custom domain
+   * This should be your repository name (e.g., 'my-repo')
+   * Only used when target is 'github-pages' and no custom domain is configured
+   */
+  basePath?: string
+
+  /**
+   * Whether a custom domain is configured
+   * When true, basePath will be ignored even for GitHub Pages
+   */
+  customDomain?: boolean
+}
+
+/**
+ * Main configuration interface
+ */
+export interface SpecraConfig {
+  /** Site metadata and branding */
+  site: SiteConfig
+  /** Theme and appearance settings */
+  theme?: ThemeConfig
+  /** Navigation and sidebar configuration */
+  navigation?: NavigationConfig
+  /** Social and external links */
+  social?: SocialLinks
+  /** Search configuration */
+  search?: SearchConfig
+  /** Analytics configuration */
+  analytics?: AnalyticsConfig
+  /** Footer configuration */
+  footer?: FooterConfig
+  /** Site-wide banner */
+  banner?: BannerConfig
+  /** Documentation features */
+  features?: FeaturesConfig
+  /** Environment variables for use in docs */
+  env?: EnvironmentVariables
+  /** Deployment configuration */
+  deployment?: DeploymentConfig
+}
+
+/**
+ * Default configuration values
+ */
+export const defaultConfig: SpecraConfig = {
+  site: {
+    title: "Documentation",
+    description: "Project documentation",
+    baseUrl: "/",
+    language: "en",
+  },
+  theme: {
+    defaultMode: "system",
+    respectPrefersColorScheme: true,
+  },
+  navigation: {
+    showSidebar: true,
+    collapsibleSidebar: true,
+    showBreadcrumbs: true,
+    showTableOfContents: true,
+    tocPosition: "right",
+    tocMaxDepth: 3,
+  },
+  search: {
+    enabled: true,
+    provider: "local",
+    placeholder: "Search documentation...",
+  },
+  features: {
+    showLastUpdated: true,
+    showReadingTime: true,
+    showAuthors: false,
+    showTags: true,
+    versioning: true,
+    i18n: false,
+  },
+}

package/src/lib/dev-utils.ts

@@ -0,0 +1,75 @@
+/**
+ * Development utilities for debugging and performance monitoring
+ * Only active in development mode
+ */
+
+const isDevelopment = process.env.NODE_ENV === 'development'
+
+/**
+ * Performance timer for measuring operation duration
+ */
+export class PerfTimer {
+  private startTime: number
+  private label: string
+
+  constructor(label: string) {
+    this.label = label
+    this.startTime = isDevelopment ? performance.now() : 0
+  }
+
+  end() {
+    if (!isDevelopment) return
+
+    const duration = performance.now() - this.startTime
+    const color = duration > 1000 ? '\x1b[31m' : duration > 500 ? '\x1b[33m' : '\x1b[32m'
+    const reset = '\x1b[0m'
+
+    console.log(`${color}⏱️  ${this.label}: ${duration.toFixed(2)}ms${reset}`)
+  }
+}
+
+/**
+ * Log file system operations
+ */
+export function logFsOperation(operation: string, path: string, details?: any) {
+  if (!isDevelopment) return
+
+  console.log(`📁 [FS] ${operation}: ${path}`, details || '')
+}
+
+/**
+ * Log cache operations
+ */
+export function logCacheOperation(operation: 'hit' | 'miss' | 'invalidate', key: string) {
+  if (!isDevelopment) return
+
+  const emoji = operation === 'hit' ? '✅' : operation === 'miss' ? '❌' : '🔄'
+  console.log(`${emoji} [Cache] ${operation}: ${key}`)
+}
+
+/**
+ * Memory usage reporter
+ */
+export function logMemoryUsage(label?: string) {
+  if (!isDevelopment) return
+
+  const used = process.memoryUsage()
+  const prefix = label ? `[${label}] ` : ''
+
+  console.log(`💾 ${prefix}Memory Usage:`, {
+    rss: `${Math.round(used.rss / 1024 / 1024)}MB`,
+    heapTotal: `${Math.round(used.heapTotal / 1024 / 1024)}MB`,
+    heapUsed: `${Math.round(used.heapUsed / 1024 / 1024)}MB`,
+  })
+}
+
+/**
+ * Pretty print object for debugging
+ */
+export function debugLog(label: string, data: any) {
+  if (!isDevelopment) return
+
+  console.log(`\n🔍 ${label}:`)
+  console.dir(data, { depth: null, colors: true })
+  console.log('')
+}

package/src/lib/index.ts

@@ -0,0 +1,27 @@
+// MDX Processing
+export * from './mdx'
+export * from './mdx-cache'
+export * from './toc'
+
+// Configuration
+export * from './config.server'
+export * from './config'
+export type * from './config.types'
+
+// API Parsers
+export * from './parsers'
+export type * from './api.types'
+export type {
+  ApiParam,
+  ApiHeader,
+  ApiResponse as SpecraApiResponse,
+  ApiEndpointSpec,
+  SpecraApiSpec
+} from './api-parser.types'
+
+// Utilities
+export * from './utils'
+export * from './sidebar-utils'
+export * from './category'
+export * from './redirects'
+export * from './dev-utils'