@crimsonsunset/jsg-logger 1.4.0 → 1.5.3

package/CHANGELOG.md

@@ -8,13 +8,169 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- None
+- **Conditional DevTools Bundling** - DevTools panel now optional via config, with tree-shaking support
+  - Added `devtools.enabled` config flag (default: `false`)
+  - Moved Preact & Evergreen UI to optional peerDependencies
+  - When disabled, devtools code is tree-shaken out (zero bundle impact)
+  - When enabled, requires peer dependencies: `npm install preact evergreen-ui`
+  - Function constructor used for dynamic imports to bypass Vite static analysis
 
-### Changed  
-- None
+### Changed
+- **DevTools Dependencies** - Preact and Evergreen UI moved to peerDependencies for optional installation
+- **DevTools Import** - Uses Function constructor instead of template literals to prevent Vite static analysis failures
+
+### Fixed
+- **Vite Build Failures** - Fixed dynamic import issues that caused Vite dev server startup failures
+- **DevTools Bundle Size** - Zero impact when disabled (default), only loads when explicitly enabled
+
+## [1.5.2] - 2025-10-25 🐛 **PATCH: CLI Formatter Custom Component Display**
+
+### Fixed
+- **CLI formatter custom component names** - Formatter was using hardcoded `COMPONENT_SCHEME` instead of `configManager`, causing custom component names to display as `[JSG-CORE]` instead of user-defined names like `[SETUP]`
+- **Browser formatter** - Removed redundant component name transformation
+
+### Technical Changes
+- `formatters/cli-formatter.js` - Use `configManager.getComponentConfig()` instead of static `COMPONENT_SCHEME`
+- `formatters/browser-formatter.js` - Remove redundant name transformation
+- `tests/custom-components.test.js` - Added Test 6 for formatter output validation
+
+## [1.5.1] - 2025-10-25 🔧 **PATCH: Component Initialization Optimization**
 
 ### Fixed
-- None
+- **Component initialization pollution** - `getAvailableComponents()` no longer initializes all 13 default COMPONENT_SCHEME components when user defines custom components (3 defined → 3 initialized instead of 16)
+- **Component name formatting** - Changed from PascalCase (`MyComponent`) to uppercase with separators (`MY-COMPONENT`)
+
+### Technical Changes
+- `config/config-manager.js` - Return only user components when defined, fallback to COMPONENT_SCHEME if empty; components replaced instead of merged; enhanced `_formatComponentName()`
+- `index.js` - Clean reinitialization: reset config, clear loggers, normalize inline config
+- `tests/custom-components.test.js` - New comprehensive test suite (5 tests)
+
+## [1.5.0] - 2025-10-25 🎯 **CRITICAL FIX: CLI Tool Support**
+
+### 🚨 **Critical Fixes**
+These fixes resolve major blockers for CLI tool usage reported in production.
+
+#### **Fixed: CLI Formatter Context Data Display** (Critical)
+- **Replaced pino-colada** with custom formatter that displays context data
+- Context objects now render as indented tree format in terminal
+- Example output:
+  ```
+  21:32:11.6 ✨ [SYSTEM] ✓ macOS version compatible
+     ├─ version: 14.2
+     ├─ build: 23C64
+     └─ command: sw_vers
+  ```
+- **Problem solved**: Context data was being silently ignored by pino-colada
+- **Impact**: Terminal applications now show full diagnostic information, not just messages
+
+#### **Fixed: Environment Detection for CLI Tools** (Critical)
+- **Enhanced `isCLI()` detection** - Now checks multiple signals:
+  - `process.stdout.isTTY` OR `process.stderr.isTTY` (not just stdout)
+  - `process.env.TERM` or `process.env.COLORTERM` environment variables
+  - Not running in CI/GitHub Actions context
+- **Problem solved**: CLI tools were being detected as "server" mode → outputting JSON instead of pretty terminal formatting
+- **Impact**: Terminal applications now properly display colored, formatted output instead of raw JSON blobs
+
+#### **Added: Force Environment Override** (Critical)
+- **New config option**: `forceEnvironment: 'cli' | 'browser' | 'server'`
+- Allows explicit environment override when auto-detection fails
+- Works in both inline config and `logger-config.json`
+- **Use case**: Essential for CLI tools in non-TTY contexts (piped output, automation scripts, etc.)
+
+#### **Added: Custom Component Name Support** (High Priority)
+- **Auto-create loggers for ANY component name** - No longer restricted to `COMPONENT_SCHEME` 
+- Components not in config get auto-generated with sensible defaults:
+  - Default emoji: 📦
+  - Default color: #999999
+  - Uppercase display name
+  - Global level inheritance
+- **Problem solved**: Custom components like 'system', 'installer', 'nvm' now work without pre-definition
+- **Impact**: True zero-configuration for component names
+
+### ✨ **API Enhancements**
+
+#### **Updated: `getComponent()` Method**
+- Now auto-creates loggers for undefined components instead of returning error loggers
+- Adds new components to auto-discovery getters dynamically
+- Seamless experience for custom component names
+
+#### **Updated: `getComponentConfig()` Method**
+- Added 3-tier priority system:
+  1. Config components (project-defined)
+  2. COMPONENT_SCHEME defaults (built-in)
+  3. Auto-generated (for custom components)
+- Always returns valid config, never null/undefined
+
+#### **Updated: `init()` and `initSync()` Methods**
+- Now load config BEFORE environment detection
+- Apply `forceEnvironment` config before determining environment
+- `initSync()` properly handles inline config objects
+
+### 📚 **Documentation**
+- **Updated README** - New v1.5.0 Quick Start section highlighting CLI tool fixes
+- **Added Force Environment docs** - When and how to override environment detection
+- **Added Custom Components docs** - Examples of using arbitrary component names
+- **Updated Environment Detection section** - Document enhanced CLI detection logic
+
+### 🎯 **Real-World Impact**
+**Before v1.5.0 (Broken for CLI tools):**
+```javascript
+const logger = JSGLogger.getInstanceSync({ components: { system: {...} } });
+logger.getComponent('system').info('✓ macOS compatible', { version: '14.2', build: '23C64' });
+// Output: {"level":30,"time":...,"msg":"✓ macOS compatible"}  ❌ JSON blob
+// Component 'system' not found error ❌
+// Context data not visible ❌
+```
+
+**After v1.5.0 (All Fixed!):**
+```javascript
+const logger = JSGLogger.getInstanceSync({ 
+  forceEnvironment: 'cli',
+  components: { system: { emoji: '⚙️' } }
+});
+logger.getComponent('system').info('✓ macOS compatible', { version: '14.2', build: '23C64' });
+// Output: 
+// 21:32:11.6 ⚙️ [SYSTEM] ✓ macOS compatible  ✅ Pretty formatted
+//    ├─ version: 14.2                        ✅ Context data visible
+//    └─ build: 23C64                         ✅ Tree formatting
+// Custom component works ✅
+```
+
+### 🔧 **Technical Changes**
+- **File**: `formatters/cli-formatter.js` ⭐ NEW FIX
+  - Removed pino-colada dependency (wasn't showing context data)
+  - Implemented custom formatter with context tree rendering
+  - Context data now displays with tree formatting (├─ and └─)
+  - Filters out pino internal fields (level, time, msg, pid, hostname, name, v, environment)
+  
+- **File**: `utils/environment-detector.js`
+  - Added `forceEnvironment()` function for manual override
+  - Enhanced `isCLI()` with multi-signal detection
+  - All detection functions now respect forced environment
+  
+- **File**: `config/config-manager.js`
+  - `getComponentConfig()` now has 3-tier fallback with auto-generation
+  
+- **File**: `index.js`
+  - Import `forceEnvironment` from environment detector
+  - Config loading moved BEFORE environment detection
+  - `getComponent()` auto-creates loggers instead of error loggers
+  - Added dynamic auto-discovery getter registration
+
+- **File**: `package.json`
+  - Removed pino-colada from dependencies (no longer required)
+
+### 📋 **Migration Guide**
+**No breaking changes** - This is a backward-compatible enhancement.
+
+**Recommended for CLI tools:**
+```javascript
+// Add this to your config for reliable terminal output
+const logger = JSGLogger.getInstanceSync({
+  forceEnvironment: 'cli',  // ← Add this line
+  // ... rest of your config
+});
+```
 
 ## [1.2.0] - 2025-08-21 🎯 **MAJOR: Fully Generic Logger**
 

package/README.md

@@ -4,14 +4,19 @@
 
 A sophisticated, fully generic logging system that automatically detects its environment (browser, CLI, server) and provides optimal logging experience for any JavaScript project, with powerful file-level overrides and granular control.
 
+> 🎮 **[Try the Interactive DevTools Playground →](https://logger.joesangiorgio.com/)**  
+> Test all features in your browser with live examples and real-time controls!
+
 ## ✨ Features
 
-- 🎯 **100% Generic** - *New in v1.2.0!* Zero hardcoded assumptions, works with any project type
+- 🎯 **100% Generic** - Zero hardcoded assumptions, works with any project type
 - 🚀 **Zero-Boilerplate Integration** - Eliminates 200+ lines of project setup code
 - 🔧 **Auto-Discovery Components** - Both camelCase and kebab-case component access  
 - ⚡ **Built-in Performance Logging** - Static utilities with auto-getInstance
 - 🛡️ **Non-Destructive Error Handling** - Missing components log but don't break apps
-- 🧠 **Smart Environment Detection** - Auto-adapts to browser, CLI, or server
+- 🎨 **Custom Component Names** - Use ANY component name, auto-generated styling
+- 🔧 **Force Environment Override** - Override auto-detection for CLI tools
+- 🧠 **Enhanced Environment Detection** - Robust CLI detection with fallbacks
 - 🎨 **Beautiful Visual Output** - Emoji, colors, and structured context display
 - 📱 **Multi-Environment** - Browser console, terminal, and production JSON
 - 🏪 **Log Store** - In-memory storage for debugging and popup interfaces
@@ -25,9 +30,40 @@ A sophisticated, fully generic logging system that automatically detects its env
 
 ## 🚀 Quick Start
 
-### **v1.2.0: Fully Generic Design - Works with Any Project!**  
+### **Custom Components & Force Environment for CLI Tools**
+
+```javascript
+import JSGLogger from '@crimsonsunset/jsg-logger';
+
+// Force environment for CLI tools (fixes terminal detection)
+const logger = JSGLogger.getInstanceSync({
+  forceEnvironment: 'cli',  // Forces pretty terminal output
+  globalLevel: 'info',
+  components: {
+    system: { emoji: '⚙️', level: 'info' },      // Custom component names!
+    installer: { emoji: '📦', level: 'info' },   // No need to pre-define
+    ssh: { emoji: '🔑', level: 'info' },         // Auto-generated styling
+    nvm: { emoji: '🟢', level: 'info' }
+  }
+});
+
+// Custom components work immediately
+const sysLog = logger.getComponent('system');
+sysLog.info('✓ macOS version compatible', { version: '14.2', build: '23C64' });
+// Output: Pretty formatted terminal output with colors AND context data!
+// 21:32:11.6 ⚙️ [SYSTEM] ✓ macOS version compatible
+//    ├─ version: 14.2
+//    └─ build: 23C64
+
+const installLog = logger.getComponent('installer');
+installLog.info('✓ Applications installed', { installed: 25, duration: '5m' });
+// 21:32:11.8 📦 [INSTALLER] ✓ Applications installed
+//    ├─ installed: 25
+//    └─ duration: 5m
+// No more JSON blobs in terminal!
+```
 
-> **⚠️ Breaking Change:** v1.2.0 requires defining components in your logger-config.json. The logger is now 100% generic with no hardcoded assumptions. 
+### **Standard Usage**
 
 ```javascript
 import JSGLogger from '@crimsonsunset/jsg-logger';
@@ -47,12 +83,12 @@ const startTime = performance.now();
 // ... do work ...
 JSGLogger.logPerformance('Page Generation', startTime, 'api');
 
-// Non-destructive error handling - missing components auto-created
+// Custom components auto-created on demand
 const dynamicLogger = logger.getComponent('new-feature');
 dynamicLogger.info('Auto-created component!'); // Works immediately
 ```
 
-### **Traditional Usage (Still Supported)**
+### **Alternative Usage**
 
 ```javascript
 import logger from '@crimsonsunset/jsg-logger';
@@ -82,10 +118,68 @@ This allows surgical debugging - you can turn on trace logging for just one prob
 
 ## ⚙️ **Advanced Configuration**
 
+### **Force Environment Override**
+
+Perfect for CLI tools that get mis-detected as "server" mode:
+
+```javascript
+// Inline config approach (recommended for CLI tools)
+const logger = JSGLogger.getInstanceSync({
+  forceEnvironment: 'cli',  // Options: 'browser', 'cli', 'server'
+  globalLevel: 'info',
+  components: {
+    system: { emoji: '⚙️', level: 'info' }
+  }
+});
+```
+
+Or in `logger-config.json`:
+
+```json
+{
+  "forceEnvironment": "cli",
+  "projectName": "My CLI Tool",
+  "globalLevel": "info",
+  "components": {
+    "system": { "emoji": "⚙️", "level": "info" }
+  }
+}
+```
+
+**When to use `forceEnvironment`:**
+- CLI tools running in non-TTY contexts (CI, piped output, etc.)
+- Override incorrect environment detection
+- Testing different output formats
+- Production deployments with specific requirements
+
+### **Custom Component Names**
+
+Use ANY component name - no need to pre-define in COMPONENT_SCHEME:
+
+```javascript
+const logger = JSGLogger.getInstanceSync({
+  components: {
+    'my-custom-component': { emoji: '🎯', level: 'debug' },
+    'another-one': { emoji: '🚀', level: 'info' },
+    'system-checker': { emoji: '⚙️', level: 'trace' }
+  }
+});
+
+// All these work immediately - auto-created with sensible defaults
+const log1 = logger.getComponent('my-custom-component');
+const log2 = logger.getComponent('another-one');
+const log3 = logger.getComponent('system-checker');
+
+// Even undefined components work (auto-generated with 📦 emoji)
+const log4 = logger.getComponent('undefined-component');
+log4.info('This works!'); // Uses auto-generated styling
+```
+
 ### **Full Configuration Example**
 
 ```json
 {
+  "forceEnvironment": "cli",
   "projectName": "My Advanced Project",
   "globalLevel": "info",
   "timestampMode": "absolute",
@@ -134,6 +228,9 @@ This allows surgical debugging - you can turn on trace logging for just one prob
         "jsonPayload": false
       }
     }
+  },
+  "devtools": {
+    "enabled": false
   }
 }
 ```
@@ -255,6 +352,9 @@ logger.controls.addFileOverride('src/popup.js', {
 ```
 
 ### **Context Data**
+
+Context data displays in CLI/terminal mode with tree formatting:
+
 ```javascript
 logger.api.error('Request failed', {
   url: window.location.href,
@@ -267,7 +367,15 @@ logger.api.error('Request failed', {
   userAgent: navigator.userAgent
 });
 
-// With file override for src/sites/soundcloud.js level: "trace":
+// CLI/Terminal output (v1.5.0+):
+// 22:15:30.1 🚨 [API] Request failed
+//    ├─ url: https://soundcloud.com/track/example
+//    ├─ selectors: {"title":".track-title","artist":".track-artist"}
+//    ├─ retryCount: 3
+//    ├─ lastError: Element not found
+//    └─ userAgent: Mozilla/5.0...
+
+// Browser Console output:
 // 22:15:30.123 🚨 [API] Request failed
 //    ├─ url: https://soundcloud.com/track/example
 //    ├─ selectors: {title: ".track-title", artist: ".track-artist"}
@@ -308,12 +416,10 @@ logger.controls.getTimestampMode()                   // Get current mode
 logger.controls.getTimestampModes()                  // List available modes
 ```
 
-### **System Controls**
+### **DevTools Panel Controls**
 ```javascript
-logger.controls.refresh()                            // Refresh all loggers
-logger.controls.reset()                              // Reset to defaults
-logger.controls.getConfigSummary()                   // Get config summary
-logger.controls.getStats()                           // Get logging stats
+logger.controls.enableDevPanel()   // Enable DevTools panel (requires devtools.enabled: true)
+logger.controls.disableDevPanel()   // Disable DevTools panel
 ```
 
 ## 📊 **Log Store & Statistics**
@@ -393,7 +499,7 @@ const stats = logger.controls.getStats();
 npm install @crimsonsunset/jsg-logger
 ```
 
-**Latest**: v1.1.0 includes major project simplification enhancements!
+**Latest**: v1.5.0 includes critical CLI tool fixes and custom component support!
 
 ## 🎯 Environment Detection
 
@@ -403,6 +509,15 @@ The logger automatically detects its environment and uses optimal implementation
 - **CLI**: Uses pino-colada for beautiful terminal output  
 - **Server**: Uses structured JSON for production logging
 
+### **Enhanced CLI Detection**
+
+The CLI detection checks multiple signals:
+1. **TTY Check**: `process.stdout.isTTY` or `process.stderr.isTTY`
+2. **Terminal Environment**: `process.env.TERM` or `process.env.COLORTERM`
+3. **Non-CI Context**: Not running in CI/GitHub Actions
+
+This fixes detection issues in various terminal contexts where `isTTY` may be undefined.
+
 **Why Browser is Different:**
 Our testing revealed that Pino's browser detection was interfering with custom formatters, especially in Chrome extensions. By creating a custom direct browser logger that bypasses Pino entirely, we achieved:
 - Perfect emoji and color display
@@ -441,6 +556,42 @@ logger.controls.addFileOverride('src/popup.js', {           // Debug popup
 });
 ```
 
+## 🎛️ **DevTools Panel (Optional)**
+
+JSG Logger includes an optional DevTools panel for visual debugging. The panel is **disabled by default** to keep bundle size minimal.
+
+### **Enabling DevTools**
+
+1. **Enable in config:**
+```json
+{
+  "devtools": {
+    "enabled": true
+  }
+}
+```
+
+2. **Install peer dependencies** (only needed when devtools enabled):
+```bash
+npm install preact evergreen-ui
+```
+
+3. **Enable the panel:**
+```javascript
+// Enable DevTools panel (only works if devtools.enabled: true in config)
+await logger.controls.enableDevPanel();
+```
+
+### **DevTools Features**
+
+- 🎛️ Visual component filter controls
+- 📊 Real-time log statistics
+- 🔧 Runtime level adjustment
+- ⚙️ Display option toggles
+- 📈 Component-level monitoring
+
+**Note:** When `devtools.enabled: false` (default), devtools dependencies are completely tree-shaken out, resulting in zero bundle impact. Only enable when you need the visual debugging interface.
+
 ## 🔧 **Browser Developer Tools**
 
 In browser environments, runtime controls are available globally:
@@ -451,6 +602,7 @@ JSG_Logger.enableDebugMode();
 JSG_Logger.setDisplayOption('level', true);
 JSG_Logger.addFileOverride('src/popup.js', { level: 'trace' });
 JSG_Logger.getStats();
+JSG_Logger.enableDevPanel(); // Enable DevTools panel (requires devtools.enabled: true)
 ```
 
 ## ⚠️ **Disclaimer**

package/config/config-manager.js

@@ -133,7 +133,7 @@ export class ConfigManager {
         
         try {
             // Try dynamic import first (works with ES modules)
-            const module = await import(path, { assert: { type: 'json' } });
+            const module = await import(/* @vite-ignore */ path, { assert: { type: 'json' } });
             return module.default || module;
         } catch (error) {
             try {
@@ -156,7 +156,7 @@ export class ConfigManager {
     async _loadConfigBrowserImport(path) {
         try {
             // Some bundlers can handle dynamic imports of JSON files
-            const module = await import(path);
+            const module = await import(/* @vite-ignore */ path);
             return module.default || module;
         } catch (error) {
             return null;
@@ -292,10 +292,16 @@ export class ConfigManager {
      * @private
      */
     _formatComponentName(componentName) {
+        // If already uppercase, return as-is
+        if (componentName === componentName.toUpperCase()) {
+            return componentName;
+        }
+        
+        // Convert to uppercase and preserve separators for readability
         return componentName
-            .split('-')
-            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
-            .join('');
+            .replace(/([a-z])([A-Z])/g, '$1-$2')  // camelCase → kebab-case
+            .replace(/_/g, '-')  // snake_case → kebab-case
+            .toUpperCase();
     }
 
     /**
@@ -315,7 +321,11 @@ export class ConfigManager {
 
         for (const key in override) {
             if (override.hasOwnProperty(key)) {
-                if (typeof override[key] === 'object' && !Array.isArray(override[key])) {
+                // Special case: 'components' should be replaced, not merged
+                // This allows users to define their own components without getting defaults
+                if (key === 'components' && typeof override[key] === 'object') {
+                    merged[key] = override[key];
+                } else if (typeof override[key] === 'object' && !Array.isArray(override[key])) {
                     merged[key] = this.mergeConfigs(merged[key] || {}, override[key]);
                 } else {
                     merged[key] = override[key];
@@ -406,7 +416,23 @@ export class ConfigManager {
      * @returns {Object} Component configuration
      */
     getComponentConfig(componentName, filePath = null) {
-        const baseComponent = this.config.components?.[componentName] || COMPONENT_SCHEME[componentName] || COMPONENT_SCHEME['core'];
+        // Priority 1: Config components
+        let baseComponent = this.config.components?.[componentName];
+        
+        // Priority 2: COMPONENT_SCHEME defaults
+        if (!baseComponent) {
+            baseComponent = COMPONENT_SCHEME[componentName];
+        }
+        
+        // Priority 3: Auto-generate for custom components
+        if (!baseComponent) {
+            baseComponent = {
+                emoji: '📦',
+                color: '#999999',
+                name: this._formatComponentName(componentName),
+                level: this.config.globalLevel || 'info'
+            };
+        }
 
         // Check for file-specific overrides
         const checkFile = filePath || this.currentFile;
@@ -523,10 +549,14 @@ export class ConfigManager {
      */
     getAvailableComponents() {
         const configComponents = Object.keys(this.config.components || {});
-        const schemeComponents = Object.keys(COMPONENT_SCHEME);
-
-        // Combine and deduplicate
-        return [...new Set([...configComponents, ...schemeComponents])];
+        
+        // If user has defined components, only return those
+        if (configComponents.length > 0) {
+            return configComponents;
+        }
+        
+        // Fallback to COMPONENT_SCHEME if no components configured (backward compatibility)
+        return Object.keys(COMPONENT_SCHEME);
     }
 
     /**

package/config/default-config.json

@@ -29,10 +29,12 @@
     "core": { 
       "emoji": "🎯", 
       "color": "#4A90E2", 
-      "name": "JSG-CORE",
-      "level": "info"
+      "name": "JSG-CORE"
     }
   },
   "fileOverrides": {
+  },
+  "devtools": {
+    "enabled": false
   }
 }