@shykaruu/jarvis-brain 0.4.0

package/src/config/README.md

@@ -0,0 +1,389 @@
+# J.A.R.V.I.S. Configuration System
+
+Type-safe YAML configuration management for Project J.A.R.V.I.S.
+
+## Overview
+
+The configuration system provides:
+- **Type-Safe Config**: Full TypeScript types for all configuration options
+- **YAML Format**: Human-readable YAML files
+- **Deep Merging**: Loaded config merges with defaults for missing values
+- **Path Expansion**: Automatic `~` (tilde) expansion for home directory
+- **Default Values**: Sensible defaults for all settings
+
+## Configuration File
+
+Default location: `~/.jarvis/config.yaml`
+
+See `config.example.yaml` in the project root for a full example.
+
+## Usage
+
+### Loading Configuration
+
+```typescript
+import { loadConfig } from './config/index.ts';
+
+// Load from default location (~/.jarvis/config.yaml)
+const config = await loadConfig();
+
+// Load from custom path
+const config = await loadConfig('/path/to/config.yaml');
+
+// Config is type-safe
+console.log(config.daemon.port);        // number
+console.log(config.llm.primary);        // string
+console.log(config.personality.core_traits);  // string[]
+```
+
+### Saving Configuration
+
+```typescript
+import { saveConfig } from './config/index.ts';
+
+// Modify config
+config.daemon.port = 8888;
+config.llm.primary = 'openai';
+
+// Save to default location
+await saveConfig(config);
+
+// Save to custom path
+await saveConfig(config, '/path/to/config.yaml');
+```
+
+### Using Default Config
+
+```typescript
+import { DEFAULT_CONFIG } from './config/index.ts';
+
+// Get a fresh copy of defaults
+const config = { ...DEFAULT_CONFIG };
+```
+
+## Configuration Schema
+
+### `daemon`
+
+Daemon server configuration.
+
+```typescript
+daemon: {
+  port: number;          // WebSocket server port (default: 7777)
+  data_dir: string;      // Data directory path (default: ~/.jarvis)
+  db_path: string;       // SQLite database path (default: ~/.jarvis/jarvis.db)
+}
+```
+
+### `llm`
+
+LLM provider configuration.
+
+```typescript
+llm: {
+  primary: string;       // Primary provider name ('anthropic' | 'openai' | 'ollama')
+  fallback: string[];    // Fallback providers in order
+
+  // Anthropic (Claude) configuration
+  anthropic?: {
+    api_key: string;
+    model?: string;      // Default: claude-sonnet-4-5-20250929
+  };
+
+  // OpenAI (GPT) configuration
+  openai?: {
+    api_key: string;
+    model?: string;      // Default: gpt-4o
+    base_url?: string;   // Optional OpenAI-compatible API base URL
+  };
+
+  // Ollama (local models) configuration
+  ollama?: {
+    base_url?: string;   // Default: http://localhost:11434
+    model?: string;      // Default: llama3
+  };
+}
+```
+
+### `personality`
+
+Core personality traits that guide J.A.R.V.I.S. behavior.
+
+```typescript
+personality: {
+  core_traits: string[];  // Array of personality traits
+}
+```
+
+Default traits:
+- `loyal`: Committed to serving the user
+- `efficient`: Optimizes for speed and resource usage
+- `proactive`: Anticipates needs and suggests improvements
+- `respectful`: Maintains professional boundaries
+- `adaptive`: Learns from interactions and adjusts behavior
+
+### `authority`
+
+Authority and permission levels.
+
+```typescript
+authority: {
+  default_level: number;  // Default authority level (0-5)
+}
+```
+
+Authority levels:
+- **0**: No permission - ask for everything
+- **1**: Read-only operations
+- **2**: Safe modifications (non-destructive)
+- **3**: Standard operations (default)
+- **4**: System changes (config, settings)
+- **5**: Full control (destructive operations)
+
+### `active_role`
+
+Active role configuration file name.
+
+```typescript
+active_role: string;  // Role file name (e.g., 'default', 'developer', 'assistant')
+```
+
+Roles are loaded from `./roles/` directory.
+
+## Default Configuration
+
+```yaml
+daemon:
+  port: 7777
+  data_dir: "~/.jarvis"
+  db_path: "~/.jarvis/jarvis.db"
+
+llm:
+  primary: "anthropic"
+  fallback:
+    - "openai"
+    - "ollama"
+  anthropic:
+    api_key: ""
+    model: "claude-sonnet-4-5-20250929"
+  openai:
+    api_key: ""
+    model: "gpt-4o"
+    # base_url: "https://your-openai-compatible-api-base"
+  ollama:
+    base_url: "http://localhost:11434"
+    model: "llama3"
+
+personality:
+  core_traits:
+    - "loyal"
+    - "efficient"
+    - "proactive"
+    - "respectful"
+    - "adaptive"
+
+authority:
+  default_level: 3
+
+active_role: "default"
+```
+
+## Example Usage
+
+### Initializing LLM Providers from Config
+
+```typescript
+import { loadConfig } from './config/index.ts';
+import { LLMManager, AnthropicProvider, OpenAIProvider, OllamaProvider } from './llm/index.ts';
+
+const config = await loadConfig();
+const manager = new LLMManager();
+
+// Register providers based on config
+if (config.llm.anthropic?.api_key) {
+  const anthropic = new AnthropicProvider(
+    config.llm.anthropic.api_key,
+    config.llm.anthropic.model
+  );
+  manager.registerProvider(anthropic);
+}
+
+if (config.llm.openai?.api_key) {
+  const openai = new OpenAIProvider(
+    config.llm.openai.api_key,
+    config.llm.openai.model
+  );
+  manager.registerProvider(openai);
+}
+
+if (config.llm.ollama) {
+  const ollama = new OllamaProvider(
+    config.llm.ollama.base_url,
+    config.llm.ollama.model
+  );
+  manager.registerProvider(ollama);
+}
+
+manager.setPrimary(config.llm.primary);
+manager.setFallbackChain(config.llm.fallback);
+```
+
+### Setting Up Data Directory
+
+```typescript
+import { mkdir } from 'node:fs/promises';
+import { loadConfig } from './config/index.ts';
+
+const config = await loadConfig();
+
+// Ensure data directory exists
+await mkdir(config.daemon.data_dir, { recursive: true });
+
+console.log(`Data directory: ${config.daemon.data_dir}`);
+console.log(`Database path: ${config.daemon.db_path}`);
+```
+
+### Dynamic Configuration Updates
+
+```typescript
+import { loadConfig, saveConfig } from './config/index.ts';
+
+// Load current config
+const config = await loadConfig();
+
+// Update settings
+config.daemon.port = 8888;
+config.llm.primary = 'openai';
+config.personality.core_traits.push('humorous');
+
+// Save changes
+await saveConfig(config);
+
+console.log('Configuration updated!');
+```
+
+## Setup Instructions
+
+1. **Copy Example Config**:
+   ```bash
+   mkdir -p ~/.jarvis
+   cp config.example.yaml ~/.jarvis/config.yaml
+   ```
+
+2. **Edit Configuration**:
+   ```bash
+   nano ~/.jarvis/config.yaml
+   ```
+
+3. **Add API Keys**:
+   - Get Anthropic API key from: https://console.anthropic.com/
+   - Get OpenAI API key from: https://platform.openai.com/
+   - Install Ollama from: https://ollama.ai/
+
+4. **Test Configuration**:
+   ```typescript
+   import { loadConfig } from './config/index.ts';
+   const config = await loadConfig();
+   console.log('Config loaded:', config);
+   ```
+
+## Environment Variables
+
+You can also use environment variables for sensitive values:
+
+```yaml
+llm:
+  anthropic:
+    api_key: "${ANTHROPIC_API_KEY}"
+  openai:
+    api_key: "${OPENAI_API_KEY}"
+```
+
+Then set in your shell:
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+export OPENAI_API_KEY="sk-..."
+```
+
+Note: The loader doesn't currently support env var substitution, but you can implement it with:
+
+```typescript
+function substituteEnvVars(value: string): string {
+  return value.replace(/\$\{(\w+)\}/g, (_, key) => process.env[key] || '');
+}
+```
+
+## Migration Guide
+
+If you have an existing config and the schema changes:
+
+1. The deep merge ensures new fields get default values
+2. Old fields remain unchanged
+3. You can manually add new fields from `config.example.yaml`
+
+## Best Practices
+
+1. **Never commit API keys**: Add `~/.jarvis/config.yaml` to `.gitignore`
+2. **Use environment variables**: For CI/CD and production deployments
+3. **Keep backups**: Copy config before major changes
+4. **Validate on load**: Check that required API keys are present
+5. **Document custom settings**: Add comments to your config YAML
+
+## Type Safety
+
+The configuration is fully typed:
+
+```typescript
+import type { JarvisConfig } from './config/index.ts';
+
+function validateConfig(config: JarvisConfig): boolean {
+  // TypeScript ensures all required fields exist
+  if (config.daemon.port < 1024 || config.daemon.port > 65535) {
+    return false;
+  }
+
+  if (config.authority.default_level < 0 || config.authority.default_level > 5) {
+    return false;
+  }
+
+  return true;
+}
+```
+
+## Extending Configuration
+
+To add new configuration sections:
+
+1. **Update Types** (`src/config/types.ts`):
+   ```typescript
+   export type JarvisConfig = {
+     // ... existing fields
+     new_section: {
+       setting1: string;
+       setting2: number;
+     };
+   };
+
+   export const DEFAULT_CONFIG: JarvisConfig = {
+     // ... existing defaults
+     new_section: {
+       setting1: 'default_value',
+       setting2: 42,
+     },
+   };
+   ```
+
+2. **Update Example** (`config.example.yaml`):
+   ```yaml
+   new_section:
+     setting1: "default_value"
+     setting2: 42
+   ```
+
+3. **Use in Code**:
+   ```typescript
+   const config = await loadConfig();
+   console.log(config.new_section.setting1);
+   ```
+
+The deep merge ensures existing configs get new defaults automatically.

package/src/config/index.ts

@@ -0,0 +1,6 @@
+// Config types
+export type { JarvisConfig } from './types.ts';
+export { DEFAULT_CONFIG } from './types.ts';
+
+// Config loader
+export { loadConfig, saveConfig } from './loader.ts';

package/src/config/loader.test.ts

@@ -0,0 +1,183 @@
+import { test, expect, describe, beforeEach, afterEach } from 'bun:test';
+import { loadConfig, saveConfig } from './loader.ts';
+import { DEFAULT_CONFIG } from './types.ts';
+import { existsSync } from 'node:fs';
+import { unlink } from 'node:fs/promises';
+import { join, isAbsolute } from 'node:path';
+
+const TEST_CONFIG_PATH = '/tmp/jarvis-test-config.yaml';
+
+describe('Config Loader', () => {
+  afterEach(async () => {
+    // Clean up test config file
+    if (existsSync(TEST_CONFIG_PATH)) {
+      await unlink(TEST_CONFIG_PATH);
+    }
+  });
+
+  test('returns default config when file does not exist', async () => {
+    const config = await loadConfig('/tmp/nonexistent-config.yaml');
+    // Paths should be tilde-expanded, but all other fields match defaults
+    expect(config.daemon.port).toBe(DEFAULT_CONFIG.daemon.port);
+    expect(config.daemon.data_dir).not.toContain('~');
+    expect(config.daemon.db_path).not.toContain('~');
+    expect(config.llm).toEqual(DEFAULT_CONFIG.llm);
+    expect(config.personality).toEqual(DEFAULT_CONFIG.personality);
+    expect(config.authority).toEqual(DEFAULT_CONFIG.authority);
+    expect(config.active_role).toBe(DEFAULT_CONFIG.active_role);
+  });
+
+  test('can save and load config', async () => {
+    const testConfig = structuredClone(DEFAULT_CONFIG);
+    testConfig.daemon.port = 9999;
+    testConfig.llm.primary = 'openai';
+    testConfig.dashboard = { password_hash: '$2b$test-hash' };
+
+    await saveConfig(testConfig, TEST_CONFIG_PATH);
+    expect(existsSync(TEST_CONFIG_PATH)).toBe(true);
+
+    const loaded = await loadConfig(TEST_CONFIG_PATH);
+    expect(loaded.daemon.port).toBe(9999);
+    expect(loaded.llm.primary).toBe('openai');
+    expect(loaded.dashboard?.password_hash).toBe('$2b$test-hash');
+  });
+
+  test('deep merges partial config with defaults', async () => {
+    // Save a partial config (only some fields)
+    const partialYaml = `
+daemon:
+  port: 8888
+
+llm:
+  primary: "openai"
+`;
+
+    await Bun.write(TEST_CONFIG_PATH, partialYaml);
+
+    const loaded = await loadConfig(TEST_CONFIG_PATH);
+
+    // Should have our custom values
+    expect(loaded.daemon.port).toBe(8888);
+    expect(loaded.llm.primary).toBe('openai');
+
+    // Should have defaults for missing values (paths are tilde-expanded)
+    expect(loaded.daemon.data_dir).not.toContain('~');
+    expect(loaded.personality.core_traits).toEqual(DEFAULT_CONFIG.personality.core_traits);
+    expect(loaded.authority.default_level).toBe(DEFAULT_CONFIG.authority.default_level);
+  });
+
+  test('preserves all config sections', async () => {
+    await saveConfig(DEFAULT_CONFIG, TEST_CONFIG_PATH);
+    const loaded = await loadConfig(TEST_CONFIG_PATH);
+
+    expect(loaded.daemon).toBeDefined();
+    expect(loaded.llm).toBeDefined();
+    expect(loaded.personality).toBeDefined();
+    expect(loaded.authority).toBeDefined();
+    expect(loaded.active_role).toBeDefined();
+  });
+});
+
+describe('Default Config', () => {
+  test('has all required fields', () => {
+    expect(DEFAULT_CONFIG.daemon).toBeDefined();
+    expect(DEFAULT_CONFIG.daemon.port).toBe(3142);
+    expect(DEFAULT_CONFIG.daemon.data_dir).toBe('~/.jarvis');
+    expect(DEFAULT_CONFIG.daemon.db_path).toBe('~/.jarvis/jarvis.db');
+
+    expect(DEFAULT_CONFIG.llm).toBeDefined();
+    expect(DEFAULT_CONFIG.llm.primary).toBe('anthropic');
+    expect(DEFAULT_CONFIG.llm.fallback).toEqual(['openai', 'ollama']);
+
+    expect(DEFAULT_CONFIG.personality).toBeDefined();
+    expect(DEFAULT_CONFIG.personality.core_traits).toBeInstanceOf(Array);
+
+    expect(DEFAULT_CONFIG.authority).toBeDefined();
+    expect(DEFAULT_CONFIG.authority.default_level).toBe(3);
+
+    expect(DEFAULT_CONFIG.active_role).toBe('personal-assistant');
+  });
+
+  test('has correct personality traits', () => {
+    const traits = DEFAULT_CONFIG.personality.core_traits;
+    expect(traits).toContain('loyal');
+    expect(traits).toContain('efficient');
+    expect(traits).toContain('proactive');
+    expect(traits).toContain('respectful');
+    expect(traits).toContain('adaptive');
+  });
+
+  test('has correct LLM defaults', () => {
+    expect(DEFAULT_CONFIG.llm.anthropic?.model).toBe('claude-sonnet-4-6');
+    expect(DEFAULT_CONFIG.llm.openai?.model).toBe('gpt-5.4');
+    expect(DEFAULT_CONFIG.llm.openai?.base_url).toBeUndefined();
+    expect(DEFAULT_CONFIG.llm.gemini?.model).toBe('gemini-3-flash-preview');
+    expect(DEFAULT_CONFIG.llm.ollama?.model).toBe('llama3');
+    expect(DEFAULT_CONFIG.llm.ollama?.base_url).toBe('http://localhost:11434');
+    expect(DEFAULT_CONFIG.dashboard?.password_hash).toBeUndefined();
+  });
+});
+
+describe('Config Parse Errors', () => {
+  afterEach(async () => {
+    if (existsSync(TEST_CONFIG_PATH)) {
+      await unlink(TEST_CONFIG_PATH);
+    }
+  });
+
+  test('throws on malformed YAML when file exists', async () => {
+    const badYaml = `
+daemon:
+  port: 3142
+    bad_indent: true
+  this is: not: valid
+`;
+    await Bun.write(TEST_CONFIG_PATH, badYaml);
+
+    expect(loadConfig(TEST_CONFIG_PATH)).rejects.toThrow();
+  });
+
+  test('uses defaults when file does not exist (no throw)', async () => {
+    const config = await loadConfig('/tmp/jarvis-definitely-not-here.yaml');
+    expect(config.daemon.port).toBe(DEFAULT_CONFIG.daemon.port);
+    expect(config.daemon.data_dir).not.toContain('~');
+    expect(config.daemon.db_path).not.toContain('~');
+  });
+
+  test('expands tildes in parsed config', async () => {
+    const yamlWithTilde = `
+daemon:
+  data_dir: "~/.jarvis"
+  db_path: "~/.jarvis/jarvis.db"
+`;
+    await Bun.write(TEST_CONFIG_PATH, yamlWithTilde);
+
+    const config = await loadConfig(TEST_CONFIG_PATH);
+    expect(config.daemon.data_dir).not.toContain('~');
+    expect(config.daemon.db_path).not.toContain('~');
+    expect(isAbsolute(config.daemon.data_dir)).toBe(true);
+    expect(isAbsolute(config.daemon.db_path)).toBe(true);
+  });
+});
+
+describe('Path Expansion', () => {
+  test('expands tilde in paths', async () => {
+    const config = await loadConfig();
+
+    // Should expand ~ to home directory
+    expect(config.daemon.data_dir).not.toContain('~');
+    expect(config.daemon.db_path).not.toContain('~');
+  });
+
+  test('preserves non-tilde paths', async () => {
+    const testConfig = { ...DEFAULT_CONFIG };
+    testConfig.daemon.data_dir = '/absolute/path';
+    testConfig.daemon.db_path = '/absolute/db.db';
+
+    await saveConfig(testConfig, TEST_CONFIG_PATH);
+    const loaded = await loadConfig(TEST_CONFIG_PATH);
+
+    expect(loaded.daemon.data_dir).toBe('/absolute/path');
+    expect(loaded.daemon.db_path).toBe('/absolute/db.db');
+  });
+});