hazo_config 1.0.0

package/src/lib/README.md

@@ -0,0 +1,160 @@
+# HazoConfig
+
+A lightweight, independent configuration management utility for INI files. Provides a unified interface for reading and writing configuration files with in-memory caching and sync operations.
+
+## Features
+
+- **Sync Operations**: All read/write operations are synchronous
+- **In-Memory Caching**: Configuration is cached in memory for fast access
+- **ConfigProvider Interface**: Standardized interface for dependency injection
+- **File Validation**: Throws error if configuration file doesn't exist on initialization
+- **Zero Dependencies**: Only uses Node.js built-ins and the `ini` package
+- **Logger Support**: Optional logger injection for debugging
+
+## Installation
+
+This component is designed to be extracted as a standalone library. To use it in your project:
+
+1. Copy the `hazo_config` directory to your project
+2. Install the `ini` package: `npm install ini`
+3. Import and use as shown below
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { HazoConfig } from './hazo_config'
+
+// Initialize with file path
+const config = new HazoConfig({
+  filePath: 'config.ini'
+})
+
+// Read a value
+const apiKey = config.get('gemini', 'api_key')
+
+// Read an entire section
+const geminiConfig = config.getSection('gemini')
+
+// Set a value
+config.set('gemini', 'api_key', 'new-api-key')
+
+// Save changes to disk
+config.save()
+
+// Refresh from disk (reloads file)
+config.refresh()
+```
+
+### With Logger
+
+```typescript
+import { HazoConfig } from './hazo_config'
+
+const logger = {
+  info: (msg, data) => console.log(msg, data),
+  warn: (msg, data) => console.warn(msg, data),
+  error: (msg, data) => console.error(msg, data)
+}
+
+const config = new HazoConfig({
+  filePath: 'config.ini',
+  logger
+})
+```
+
+### Using ConfigProvider Interface
+
+The `ConfigProvider` interface allows other components to consume configuration without knowing the implementation:
+
+```typescript
+import type { ConfigProvider } from './hazo_config'
+
+function myFunction(configProvider: ConfigProvider) {
+  const value = configProvider.get('section', 'key')
+  // Use value...
+}
+```
+
+## API Reference
+
+### HazoConfig Class
+
+#### Constructor
+
+```typescript
+constructor(options: HazoConfigOptions)
+```
+
+- `options.filePath` (required): Path to the INI configuration file
+- `options.logger` (optional): Logger instance implementing the Logger interface
+
+Throws error if file doesn't exist.
+
+#### Methods
+
+- `get(section: string, key: string): string | undefined` - Get a configuration value
+- `getSection(section: string): Record<string, string> | undefined` - Get an entire section
+- `set(section: string, key: string, value: string): void` - Set a configuration value
+- `save(): void` - Save all changes to disk immediately
+- `refresh(): void` - Reload configuration from disk
+- `getFilePath(): string` - Get the resolved file path
+- `getAllSections(): Record<string, Record<string, string>>` - Get all configuration sections
+
+### ConfigProvider Interface
+
+```typescript
+interface ConfigProvider {
+  get(section: string, key: string): string | undefined
+  getSection(section: string): Record<string, string> | undefined
+  set(section: string, key: string, value: string): void
+  save(): void
+  refresh(): void
+}
+```
+
+## Error Handling
+
+HazoConfig throws errors with the following error codes:
+
+- `HAZO_CONFIG_FILE_NOT_FOUND`: Configuration file doesn't exist
+- `HAZO_CONFIG_READ_ERROR`: Failed to read configuration file
+- `HAZO_CONFIG_WRITE_ERROR`: Failed to write configuration file
+- `HAZO_CONFIG_PARSE_ERROR`: Failed to parse INI content
+- `HAZO_CONFIG_VALIDATION_ERROR`: Configuration validation failed
+
+## Extraction Guide
+
+To extract this component as a standalone library:
+
+1. Copy the entire `hazo_config` directory
+2. Create a `package.json` with:
+   ```json
+   {
+     "name": "hazo-config",
+     "version": "1.0.0",
+     "main": "index.ts",
+     "dependencies": {
+       "ini": "^4.0.0"
+     }
+   }
+   ```
+3. The component has zero dependencies on the parent project
+4. All types and interfaces are self-contained
+
+## Integration with Other Components
+
+This component is designed to work with other Hazo components like `hazo_connect`. The `ConfigProvider` interface allows components to accept configuration without tight coupling:
+
+```typescript
+import type { ConfigProvider } from 'hazo-config'
+import { createHazoConnect } from 'hazo-connect'
+
+const config = new HazoConfig({ filePath: 'config.ini' })
+const adapter = createHazoConnect({
+  configProvider: config,  // Pass ConfigProvider
+  // ... other options
+})
+```
+

package/src/lib/config-loader.ts

@@ -0,0 +1,186 @@
+/**
+ * Purpose: Main implementation of HazoConfig
+ *
+ * This file provides the HazoConfig class that implements the ConfigProvider
+ * interface. It handles reading and writing INI configuration files with
+ * in-memory caching, sync operations, and preservation of file formatting.
+ * Zero dependencies - only Node.js built-ins and the 'ini' package.
+ */
+
+import fs from 'fs'
+import path from 'path'
+import ini from 'ini'
+import type { ConfigProvider, HazoConfigOptions, Logger } from './types'
+import { ConfigErrorCode as EC } from './types'
+
+/**
+ * No-op logger implementation (default when no logger provided)
+ */
+const noOpLogger: Logger = {
+  info: () => {},
+  warn: () => {},
+  error: () => {}
+}
+
+/**
+ * HazoConfig class
+ * 
+ * Implements ConfigProvider interface for managing INI configuration files.
+ * Provides sync read/write operations with in-memory caching.
+ */
+export class HazoConfig implements ConfigProvider {
+  private filePath: string
+  private logger: Logger
+  private config: Record<string, Record<string, string>> = {}
+  private originalContent: string = ''
+
+  /**
+   * Constructor
+   * @param options - Configuration options including filePath and optional logger
+   * @throws Error if file doesn't exist
+   */
+  constructor(options: HazoConfigOptions) {
+    this.filePath = path.resolve(options.filePath)
+    this.logger = options.logger || noOpLogger
+
+    // Validate file exists
+    if (!fs.existsSync(this.filePath)) {
+      const error: any = new Error(`Configuration file not found: ${this.filePath}`)
+      error.code = EC.FILE_NOT_FOUND
+      this.logger.error(`[HazoConfig] Configuration file not found: ${this.filePath}`)
+      throw error
+    }
+
+    // Load initial configuration
+    this.refresh()
+  }
+
+  /**
+   * Get a configuration value by section and key
+   * @param section - The configuration section name
+   * @param key - The configuration key name
+   * @returns The configuration value, or undefined if not found
+   */
+  get(section: string, key: string): string | undefined {
+    return this.config[section]?.[key]
+  }
+
+  /**
+   * Get an entire configuration section
+   * @param section - The configuration section name
+   * @returns A record of key-value pairs for the section, or undefined if section doesn't exist
+   */
+  getSection(section: string): Record<string, string> | undefined {
+    return this.config[section] ? { ...this.config[section] } : undefined
+  }
+
+  /**
+   * Set a configuration value
+   * @param section - The configuration section name
+   * @param key - The configuration key name
+   * @param value - The value to set
+   */
+  set(section: string, key: string, value: string): void {
+    if (!this.config[section]) {
+      this.config[section] = {}
+    }
+    this.config[section][key] = value
+    this.logger.info(`[HazoConfig] Set config value: ${section}.${key}`, { value })
+  }
+
+  /**
+   * Save the current configuration to disk
+   * Writes all changes immediately to the configuration file
+   */
+  save(): void {
+    try {
+      // Convert config object back to INI format
+      const iniContent = ini.stringify(this.config, {
+        section: '[',
+        whitespace: true,
+        newline: '\n'
+      })
+
+      // Write to file
+      fs.writeFileSync(this.filePath, iniContent, 'utf-8')
+      
+      // Update original content for future reference
+      this.originalContent = iniContent
+      
+      this.logger.info(`[HazoConfig] Configuration saved to: ${this.filePath}`)
+    } catch (error: any) {
+      const configError: any = new Error(`Failed to save configuration: ${error.message || String(error)}`)
+      configError.code = EC.WRITE_ERROR
+      configError.originalError = error
+      this.logger.error(`[HazoConfig] Failed to save configuration: ${this.filePath}`, { error: String(error) })
+      throw configError
+    }
+  }
+
+  /**
+   * Refresh the configuration from disk
+   * Reloads the configuration file and updates the in-memory cache
+   */
+  refresh(): void {
+    try {
+      // Read file content
+      const content = fs.readFileSync(this.filePath, 'utf-8')
+      this.originalContent = content
+
+      // Parse INI content
+      const parsed = ini.parse(content)
+      
+      // Convert to our internal format (ensure all values are strings)
+      this.config = {}
+      for (const [section, values] of Object.entries(parsed)) {
+        if (typeof values === 'object' && values !== null) {
+          this.config[section] = {}
+          for (const [key, value] of Object.entries(values)) {
+            this.config[section][key] = String(value)
+          }
+        }
+      }
+
+      this.logger.info(`[HazoConfig] Configuration refreshed from: ${this.filePath}`, {
+        sections: Object.keys(this.config)
+      })
+    } catch (error: any) {
+      // Handle file read errors
+      if (error.code === 'ENOENT') {
+        const configError: any = new Error(`Configuration file not found: ${this.filePath}`)
+        configError.code = EC.FILE_NOT_FOUND
+        this.logger.error(`[HazoConfig] Configuration file not found: ${this.filePath}`)
+        throw configError
+      }
+
+      // Handle parse errors
+      const configError: any = new Error(`Failed to parse configuration: ${error.message || String(error)}`)
+      configError.code = EC.PARSE_ERROR
+      configError.originalError = error
+      this.logger.error(`[HazoConfig] Failed to parse configuration: ${this.filePath}`, { error: String(error) })
+      throw configError
+    }
+  }
+
+  /**
+   * Get the file path being managed
+   * @returns The resolved file path
+   */
+  getFilePath(): string {
+    return this.filePath
+  }
+
+  /**
+   * Get all configuration sections
+   * @returns A record of all sections and their key-value pairs
+   */
+  getAllSections(): Record<string, Record<string, string>> {
+    // Return a deep copy to prevent external modification
+    const result: Record<string, Record<string, string>> = {}
+    for (const [section, values] of Object.entries(this.config)) {
+      result[section] = { ...values }
+    }
+    return result
+  }
+}
+

package/src/lib/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Purpose: Main export for the HazoConfig library.
+ *
+ * This file re-exports all public interfaces and classes for the HazoConfig
+ * configuration management utility. It serves as the primary entry point
+ * for consumers of the library.
+ */
+
+export { HazoConfig } from './config-loader'
+export { MockConfigProvider } from './mock_config_provider'
+export { ConfigErrorCode } from './types'
+export type {
+  ConfigProvider,
+  HazoConfigOptions,
+  Logger,
+  HazoConfigError
+} from './types'
+

package/src/lib/mock_config_provider.ts

@@ -0,0 +1,93 @@
+// Mock config provider for browser/Storybook testing
+// Implements ConfigProvider interface using in-memory storage instead of file system
+
+import type { ConfigProvider } from './types'
+
+/**
+ * Mock config provider that stores configuration in memory
+ * Useful for testing and Storybook demonstrations where file system is not available
+ */
+export class MockConfigProvider implements ConfigProvider {
+  private config: Record<string, Record<string, string>> = {}
+
+  /**
+   * Constructor
+   * @param initial_config - Optional initial configuration data
+   */
+  constructor(initial_config?: Record<string, Record<string, string>>) {
+    if (initial_config) {
+      this.config = JSON.parse(JSON.stringify(initial_config)) // Deep copy
+    }
+  }
+
+  /**
+   * Get a configuration value by section and key
+   * @param section - The configuration section name
+   * @param key - The configuration key name
+   * @returns The configuration value, or undefined if not found
+   */
+  get(section: string, key: string): string | undefined {
+    return this.config[section]?.[key]
+  }
+
+  /**
+   * Get an entire configuration section
+   * @param section - The configuration section name
+   * @returns A record of key-value pairs for the section, or undefined if section doesn't exist
+   */
+  getSection(section: string): Record<string, string> | undefined {
+    return this.config[section] ? { ...this.config[section] } : undefined
+  }
+
+  /**
+   * Set a configuration value
+   * @param section - The configuration section name
+   * @param key - The configuration key name
+   * @param value - The value to set
+   */
+  set(section: string, key: string, value: string): void {
+    if (!this.config[section]) {
+      this.config[section] = {}
+    }
+    this.config[section][key] = value
+  }
+
+  /**
+   * Save the current configuration (no-op for mock, but maintains interface compatibility)
+   */
+  save(): void {
+    // No-op for mock provider
+  }
+
+  /**
+   * Refresh the configuration (no-op for mock, but maintains interface compatibility)
+   */
+  refresh(): void {
+    // No-op for mock provider
+  }
+
+  /**
+   * Get all configuration sections
+   * @returns A record of all sections and their key-value pairs
+   */
+  getAllSections(): Record<string, Record<string, string>> {
+    const result: Record<string, Record<string, string>> = {}
+    for (const [section, values] of Object.entries(this.config)) {
+      result[section] = { ...values }
+    }
+    return result
+  }
+
+  /**
+   * Reset the configuration to initial state or empty
+   * @param new_config - Optional new configuration to set
+   */
+  reset(new_config?: Record<string, Record<string, string>>): void {
+    if (new_config) {
+      this.config = JSON.parse(JSON.stringify(new_config))
+    } else {
+      this.config = {}
+    }
+  }
+}
+

package/src/lib/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Purpose: Core interfaces and types for the HazoConfig component.
+ *
+ * This file defines the fundamental building blocks for creating a flexible and
+ * extensible configuration management utility. It includes interfaces for the
+ * ConfigProvider pattern, configuration options, and error types, ensuring
+ * loose coupling and reusability across different projects.
+ */
+
+/**
+ * Logger interface for dependency injection
+ * Matches the Logger interface from hazo_connect for consistency
+ */
+export interface Logger {
+  info(message: string, data?: any): void
+  warn(message: string, data?: any): void
+  error(message: string, data?: any): void
+}
+
+/**
+ * ConfigProvider interface
+ * 
+ * Defines the contract for configuration providers that can be used
+ * by other components (like hazo_connect) to access configuration values.
+ * This allows for dependency injection and makes components testable.
+ */
+export interface ConfigProvider {
+  /**
+   * Get a configuration value by section and key
+   * @param section - The configuration section name
+   * @param key - The configuration key name
+   * @returns The configuration value, or undefined if not found
+   */
+  get(section: string, key: string): string | undefined
+
+  /**
+   * Get an entire configuration section
+   * @param section - The configuration section name
+   * @returns A record of key-value pairs for the section, or undefined if section doesn't exist
+   */
+  getSection(section: string): Record<string, string> | undefined
+
+  /**
+   * Set a configuration value
+   * @param section - The configuration section name
+   * @param key - The configuration key name
+   * @param value - The value to set
+   */
+  set(section: string, key: string, value: string): void
+
+  /**
+   * Save the current configuration to disk
+   * Writes all changes immediately to the configuration file
+   */
+  save(): void
+
+  /**
+   * Refresh the configuration from disk
+   * Reloads the configuration file and updates the in-memory cache
+   */
+  refresh(): void
+}
+
+/**
+ * Options for initializing HazoConfig
+ */
+export interface HazoConfigOptions {
+  /**
+   * Path to the configuration file (required)
+   * Can be absolute or relative to process.cwd()
+   */
+  filePath: string
+
+  /**
+   * Optional logger instance for logging operations
+   */
+  logger?: Logger
+}
+
+/**
+ * Error codes for configuration operations
+ */
+export enum ConfigErrorCode {
+  FILE_NOT_FOUND = 'HAZO_CONFIG_FILE_NOT_FOUND',
+  READ_ERROR = 'HAZO_CONFIG_READ_ERROR',
+  WRITE_ERROR = 'HAZO_CONFIG_WRITE_ERROR',
+  PARSE_ERROR = 'HAZO_CONFIG_PARSE_ERROR',
+  VALIDATION_ERROR = 'HAZO_CONFIG_VALIDATION_ERROR'
+}
+
+/**
+ * Standardized error response for configuration operations
+ */
+export interface HazoConfigError {
+  code: string
+  message: string
+  filePath?: string
+  originalError?: any
+}
+

package/src/lib/utils.ts

@@ -0,0 +1,15 @@
+// Utility functions for the component library
+// Provides class name merging functionality using clsx and tailwind-merge
+
+import { type ClassValue, clsx } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+/**
+ * Merges class names using clsx and tailwind-merge
+ * @param inputs - Class values to merge
+ * @returns Merged class string
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+

package/src/styles/globals.css

@@ -0,0 +1,61 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 222.2 84% 4.9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 222.2 84% 4.9%;
+    --primary: 222.2 47.4% 11.2%;
+    --primary-foreground: 210 40% 98%;
+    --secondary: 210 40% 96.1%;
+    --secondary-foreground: 222.2 47.4% 11.2%;
+    --muted: 210 40% 96.1%;
+    --muted-foreground: 215.4 16.3% 46.9%;
+    --accent: 210 40% 96.1%;
+    --accent-foreground: 222.2 47.4% 11.2%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 214.3 31.8% 91.4%;
+    --input: 214.3 31.8% 91.4%;
+    --ring: 222.2 84% 4.9%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    --card: 222.2 84% 4.9%;
+    --card-foreground: 210 40% 98%;
+    --popover: 222.2 84% 4.9%;
+    --popover-foreground: 210 40% 98%;
+    --primary: 210 40% 98%;
+    --primary-foreground: 222.2 47.4% 11.2%;
+    --secondary: 217.2 32.6% 17.5%;
+    --secondary-foreground: 210 40% 98%;
+    --muted: 217.2 32.6% 17.5%;
+    --muted-foreground: 215 20.2% 65.1%;
+    --accent: 217.2 32.6% 17.5%;
+    --accent-foreground: 210 40% 98%;
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 217.2 32.6% 17.5%;
+    --input: 217.2 32.6% 17.5%;
+    --ring: 212.7 26.8% 83.9%;
+  }
+}
+
+@layer base {
+  * {
+    border-color: hsl(var(--border));
+  }
+  body {
+    background-color: hsl(var(--background));
+    color: hsl(var(--foreground));
+  }
+}
+

package/tailwind.config.js

@@ -0,0 +1,13 @@
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  darkMode: ["class"],
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx}",
+    "./.storybook/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+

package/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src"],
+  "exclude": ["**/*.stories.tsx", "**/*.test.tsx", "**/*.test.ts"]
+}
+

package/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}
+