@crimsonsunset/jsg-logger 1.2.0 → 1.6.0

package/CHANGELOG.md

@@ -16,6 +16,180 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 - None
 
+## [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**
+
+### 🚀 **BREAKING CHANGES**
+- **Minimal default config**: Only 'core' component included by default
+- **Projects must define components**: Custom components now required in logger-config.json
+- **Legacy component removal**: All 10 hardcoded legacy components removed
+- **Core component rename**: 'cacp' → 'core' throughout functional code
+
+### ✨ **Added**
+- **100% Generic Design**: Zero legacy/project-specific references
+- **Dynamic Alias Generation**: Auto-generate camelCase from kebab-case component names
+- **Smart Component Creation**: Missing components auto-created with sensible defaults
+- **Enhanced Config Normalization**: Better handling of various config formats
+- **Generic Examples**: Updated advanced-config.json with modern component examples
+
+### 🔧 **Changed**  
+- **Default Configuration**: Minimal config with only 'core' component
+- **Component Schemes**: Cleaned to minimal generic set
+- **Class Names**: CACPLogger → JSGLogger throughout (completed in 1.1.4-1.1.7)
+- **Browser Global**: window.CACP_Logger → window.JSG_Logger
+- **Fallback Logic**: Uses 'core' component instead of hardcoded 'cacp'
+
+### 🗑️ **Removed**
+- **Legacy Components**: soundcloud, youtube, site-detector, websocket, popup, background, priority-manager, settings, test
+- **Hardcoded Aliases**: Replaced siteDetector/priorityManager with dynamic generation
+- **Project-Specific Logic**: All hardcoded references to specific use cases
+
+### 📚 **Documentation**
+- **Updated Roadmap**: Phase 9 complete, Phase 10 DX enhancements planned
+- **Migration Guide**: Clear upgrade path for existing projects
+- **Generic Examples**: Modern component examples for common project types
+
+### 🎯 **Migration Notes**
+Existing projects need to update their logger-config.json to define components:
+
+```json
+{
+  "components": {
+    "core": { "emoji": "🎯", "level": "info" },
+    "api": { "emoji": "🌐", "level": "debug" },
+    "ui": { "emoji": "🎨", "level": "info" }
+  }
+}
+```
+
+The logger will auto-create missing components, but explicit definition is recommended.
+
 ## [1.0.8] - 2025-08-06
 
 ### Changed

package/README.md

@@ -1,16 +1,19 @@
 # JSG Logger
 
-**Intelligent Multi-Environment Logger with Advanced Configuration**
+**100% Generic Multi-Environment Logger with Advanced Configuration**
 
-A sophisticated logging system that automatically detects its environment (browser, CLI, server) and provides optimal logging experience for each, with powerful file-level overrides and granular control.
+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.
 
 ## ✨ Features
 
-- 🚀 **Zero-Boilerplate Integration** - *New in v1.1.0!* Eliminates 200+ lines of project setup code
-- 🔧 **Auto-Discovery Components** - *New!* Both camelCase and kebab-case component access
-- ⚡ **Built-in Performance Logging** - *New!* Static utilities with auto-getInstance
-- 🛡️ **Non-Destructive Error Handling** - *New!* Missing components log but don't break apps
-- 🧠 **Smart Environment Detection** - Auto-adapts to browser, CLI, or server
+- 🎯 **100% Generic** - *New in v1.2.0!* 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
+- 🎨 **Custom Component Names** - *New in v1.5.0!* Use ANY component name, auto-generated styling
+- 🔧 **Force Environment Override** - *New in v1.5.0!* Override auto-detection for CLI tools
+- 🧠 **Enhanced Environment Detection** - *New in v1.5.0!* 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
@@ -24,28 +27,66 @@ A sophisticated logging system that automatically detects its environment (brows
 
 ## 🚀 Quick Start
 
-### **New in v1.1.0: Zero-Boilerplate Project Integration** 
+### **v1.5.0: Custom Components & Force Environment - Perfect for CLI Tools!**
+
+> **✨ New in v1.5.0:** Use ANY component name (not just pre-defined ones) and force CLI mode for terminal applications!
+
+```javascript
+import JSGLogger from '@crimsonsunset/jsg-logger';
+
+// ✨ NEW: 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' }
+  }
+});
+
+// ✨ NEW: 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! 🎉
+```
+
+### **v1.2.0: Fully Generic Design - Works with Any Project!**  
+
+> **⚠️ Breaking Change:** v1.2.0 requires defining components in your logger-config.json. The logger is now 100% generic with no hardcoded assumptions. 
 
 ```javascript
 import JSGLogger from '@crimsonsunset/jsg-logger';
 
 // Enhanced singleton with built-in configuration loading
-const logger = JSGLogger.getInstance({
+const logger = await JSGLogger.getInstance({
   configPath: './logger-config.json'
 });
 
-// Auto-discovery component access (both naming conventions)
-logger.components.astroBuild().info('Build started');
-logger.components['astro-build']().info('Same component, different syntax');
+// Use your project-specific components immediately
+logger.api.info('Server started on port 3000');
+logger.database.debug('Query executed', { query: 'SELECT * FROM users' });
+logger.ui.info('Component mounted', { component: 'UserProfile' });
 
-// Built-in static performance logging
+// Built-in static performance logging  
 const startTime = performance.now();
 // ... do work ...
-JSGLogger.logPerformance('Page Generation', startTime, 'astro-build');
+JSGLogger.logPerformance('Page Generation', startTime, 'api');
 
-// Non-destructive error handling
-const maybeLogger = logger.getComponent('missing-component');
-maybeLogger.info('Still works!'); // Logs: [MISSING-COMPONENT] ⚠️ Component not configured - Still works!
+// ✨ NEW: Custom components auto-created on demand
+const dynamicLogger = logger.getComponent('new-feature');
+dynamicLogger.info('Auto-created component!'); // Works immediately
 ```
 
 ### **Traditional Usage (Still Supported)**
@@ -78,10 +119,68 @@ This allows surgical debugging - you can turn on trace logging for just one prob
 
 ## ⚙️ **Advanced Configuration**
 
+### **Force Environment Override** ✨ *New in v1.5.0*
+
+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** ✨ *New in v1.5.0*
+
+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",
@@ -251,6 +350,9 @@ logger.controls.addFileOverride('src/popup.js', {
 ```
 
 ### **Context Data**
+
+✨ **New in v1.5.0:** Context data now displays in CLI/terminal mode with tree formatting!
+
 ```javascript
 logger.api.error('Request failed', {
   url: window.location.href,
@@ -263,7 +365,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"}
@@ -389,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
 
@@ -399,6 +509,26 @@ 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** ✨ *Improved in v1.5.0*
+
+The CLI detection now 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.
+
+### **Force Environment Override** ✨ *New in v1.5.0*
+
+If auto-detection fails, you can force the environment:
+
+```javascript
+const logger = JSGLogger.getInstanceSync({
+  forceEnvironment: 'cli',  // Override auto-detection
+  // ... rest of config
+});
+```
+
 **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

package/config/component-schemes.js

@@ -4,7 +4,19 @@
  */
 
 export const COMPONENT_SCHEME = {
-  'core': { emoji: '🎯', color: '#8E44AD', name: 'JSG-CORE' }
+  'core': { emoji: '🎯', color: '#4A90E2', name: 'JSG-CORE' },
+  'api': { emoji: '🔌', color: '#FF5500', name: 'API' },
+  'ui': { emoji: '🎨', color: '#FF6B6B', name: 'UI' },
+  'database': { emoji: '💾', color: '#00C896', name: 'DATABASE' },
+  'test': { emoji: '🧪', color: '#FFEAA7', name: 'TEST' },
+  'preact': { emoji: '⚛️', color: '#673ab8', name: 'PREACT' },
+  'auth': { emoji: '🔐', color: '#E67E22', name: 'AUTH' },
+  'analytics': { emoji: '📊', color: '#9B59B6', name: 'ANALYTICS' },
+  'performance': { emoji: '⚡', color: '#F39C12', name: 'PERFORMANCE' },
+  'websocket': { emoji: '🔗', color: '#1ABC9C', name: 'WEBSOCKET' },
+  'notification': { emoji: '🔔', color: '#E74C3C', name: 'NOTIFICATION' },
+  'router': { emoji: '🛣️', color: '#3498DB', name: 'ROUTER' },
+  'cache': { emoji: '💨', color: '#95A5A6', name: 'CACHE' }
 };
 
 export const LEVEL_SCHEME = {

package/config/config-manager.js

@@ -406,7 +406,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: componentName.toUpperCase().replace(/-/g, '-'),
+                level: this.config.globalLevel || 'info'
+            };
+        }
 
         // Check for file-specific overrides
         const checkFile = filePath || this.currentFile;

package/config/default-config.json

@@ -29,8 +29,7 @@
     "core": { 
       "emoji": "🎯", 
       "color": "#4A90E2", 
-      "name": "JSG-CORE",
-      "level": "info"
+      "name": "JSG-CORE"
     }
   },
   "fileOverrides": {