@crimsonsunset/jsg-logger 1.8.3 → 1.8.4

package/README.md

@@ -642,6 +642,68 @@ Our testing revealed that Pino's browser detection was interfering with custom f
 - Seamless Chrome extension integration
 - Zero compromises on functionality
 
+## 🔌 **External Transport Integration**
+
+Connect any external log service (PostHog, Datadog, Sentry, etc.) by implementing the `LogTransport` interface and registering it with the singleton.
+
+### **Implementing a Transport**
+
+```typescript
+import type { LogEntry, LogTransport } from '@crimsonsunset/jsg-logger';
+
+class MyServiceTransport implements LogTransport {
+  level = 'warn' as const; // Only receive warn/error/fatal entries
+
+  send(entry: LogEntry): void {
+    if (!entry.isError || !entry.error) return;
+    myService.captureException(entry.error, {
+      component: entry.component,
+      message: entry.message,
+      ...entry.data,
+    });
+  }
+}
+```
+
+### **Registering a Transport**
+
+Use `JSGLogger.addTransport()` — safe to call at any point, including after module-level initialization:
+
+```typescript
+import JSGLogger from '@crimsonsunset/jsg-logger';
+
+// Works in Next.js instrumentation.ts, app startup, etc.
+JSGLogger.addTransport(new MyServiceTransport());
+```
+
+> **Why not `getInstanceSync(options)`?** The logger initializes itself at module evaluation time. Passing `transports` via `getInstanceSync()` after that point hits the reinit guard, which silently drops the options to protect already-registered transports. `addTransport()` bypasses this entirely.
+
+### **`LogEntry` Shape**
+
+```typescript
+interface LogEntry {
+  level: LogLevel;        // 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal'
+  levelNum: number;       // 10 | 20 | 30 | 40 | 50 | 60
+  message: string;
+  component: string;
+  data?: Record<string, unknown>;
+  timestamp: number;
+  isError: boolean;       // true when levelNum >= 50
+  error?: Error;          // Extracted from data, data.err, or data.error
+}
+```
+
+The `error` field is auto-extracted: if you call `logger.error('msg', { error: new Error(...) })`, `entry.error` is set automatically.
+
+### **Post-Init Config Updates**
+
+To update config (not transports) after initialization, use `configure()`:
+
+```typescript
+logger.configure({ globalLevel: 'debug' });
+// Merges config without touching registered transports
+```
+
 ## 🚀 Advanced Features
 
 ### **Automatic File Detection**

package/docs/next-session.md

@@ -14,227 +14,44 @@
 
 ---
 
-**Date:** October 28, 2025  
-**Session Goal:** 🎨 **Phase 7.1: Display Controls Panel** - Real-time preview with display toggles  
-**Status:** ✅ **COMPLETE** - All display controls implemented and working
-
-## 🎉 MAJOR ACCOMPLISHMENTS THIS SESSION
-
-### ✅ Phase 7.1 Display Controls Complete (October 28, 2025) 🎨→✅
-- **📊 Live Preview in Sticky Header** - Real-time log preview that updates instantly
-  - Shows sample log with all elements (timestamp, emoji, component, level, message, JSON, stack trace)
-  - Updates immediately as controls are toggled
-  - Stays visible while scrolling through other controls
-  - Professional monospace styling matching console output
-- **⏱️ Timestamp Mode Control** - Button group with 4 modes
-  - Absolute: `22:15:30.1` (milliseconds precision)
-  - Readable: `10:15 PM` (12-hour format)
-  - Relative: `2s ago` (time since)
-  - Off: Hidden (no timestamp)
-  - Active button highlighted with primary appearance
-- **🎛️ 6 Display Toggle Switches** - Granular control over log elements
-  - Emoji: Show/hide level emoji (🌐, 🚨, etc.)
-  - Component: Show/hide [COMPONENT-NAME] tags
-  - Level Name: Show/hide level text (INFO, DEBUG, etc.)
-  - Message: Always on (disabled - can't hide messages)
-  - JSON Data: Show/hide context data trees
-  - Stack Trace: Show/hide error stack traces
-- **✅ Bulk Operations** - Quick control actions
-  - All On: Enable all display options
-  - All Off: Disable all (except message)
-  - Reset: Restore default settings
-- **🏗️ Clean Architecture** - Simplified layout with no sections
-  - Removed all subheadings and dividers
-  - Everything in one sticky container
-  - Only Component Filters and Global Controls scroll
-  - Single divider at the bottom of scrolling content
-- **🔧 API Integration** - Full logger.controls integration
-  - `getDisplayConfig()` loads initial state
-  - `getTimestampMode()` loads timestamp setting
-  - `setDisplayOption()` applies changes to console
-  - `setTimestampMode()` updates timestamp format
-  - State managed via parent component callback
-
-### **Technical Implementation**
-- **DisplayControls.jsx** (~350 lines)
-  - Exported LogPreview component for header use
-  - State management with `onStateChange` callback
-  - Timestamp button group (replaced SegmentedControl)
-  - 6 toggle switches in 2-column grid
-  - Bulk control buttons
-- **PanelContainer.jsx** (updated)
-  - LogPreview and DisplayControls in sticky header
-  - State management for preview rendering
-  - Single scrolling content area
-  - Clean layout with one border at bottom
-- **ComponentFilters.jsx** (simplified)
-  - Removed "🎚️ Log Levels" heading
-  - Reduced spacing for compact layout
-- **GlobalControls.jsx** (simplified)
-  - Removed "🌐 Global Controls" heading
-  - Cleaner integration with overall layout
-
-### **Real-World Impact**
-Phase 7.1 completes the foundation for comprehensive DevTools UI:
-- **Before**: Only basic component filtering, missing 80% of logger capabilities
-- **After**: Display controls expose all visual formatting options with live preview
-- **Next**: Phase 7.2 will add component management (emoji/color pickers, bulk operations)
-
-## 🎉 PREVIOUS SESSION ACCOMPLISHMENTS
-
-### ✅ Critical CLI Tool Fixes Complete (October 25, 2025) 🚨→✅
-- **🎨 CLI Context Data Display Fixed** - Replaced pino-colada with custom formatter
-  - Context data now renders as indented tree in terminal
-  - Shows all diagnostic information, not just messages
-  - Example: version, build, command data visible with ├─ and └─ formatting
-- **🔧 Environment Detection Fixed** - Enhanced `isCLI()` with multi-signal detection
-  - Now checks TTY, TERM env vars, and CI context
-  - CLI tools no longer mis-detected as "server" mode
-  - Fixes JSON output in terminal applications
-- **✨ Force Environment Override** - New `forceEnvironment` config option
-  - Allows manual override of auto-detection
-  - Works in inline config and logger-config.json
-  - Essential for non-TTY contexts (piped output, automation)
-- **🎯 Custom Component Names** - Any component name now works
-  - Auto-creation for undefined components
-  - Sensible default styling (📦 emoji, gray color)
-  - No longer restricted to COMPONENT_SCHEME
-- **📦 Version Bump** - Published v1.5.0 with all fixes
-- **🗑️ Dependency Cleanup** - Removed pino-colada (no longer needed)
-- **📚 Comprehensive Documentation** - Updated README, CHANGELOG
-  - New Quick Start section for v1.5.0
-  - Detailed forceEnvironment examples
-  - Custom component usage patterns
-  - Context data rendering examples
-
-### **Real-World Impact**
-Fixed production blocker in macOS setup automation tool:
-- **Before**: JSON blobs in 30-minute terminal script → unusable
-- **After**: Pretty colored output with component organization → perfect UX
-
-## 🎉 PREVIOUS SESSION ACCOMPLISHMENTS
-
-### ✅ DevTools Integration Blocker RESOLVED (October 24, 2025)
-- **🔧 Import Path Fixed** - Installed JSG Logger as local file dependency
-- **📦 Dependencies Complete** - All parent dependencies installed (pino, pino-colada)
-- **🎯 ThemeProvider Fixed** - Corrected Evergreen UI ThemeProvider syntax
-- **🎛️ Panel Renders** - Floating button successfully appears on screen
-- **✅ Initialization Success** - DevTools panel loads without crashes
-
-## 🎉 PREVIOUS SESSION ACCOMPLISHMENTS
-
-### ✅ DevTools Phase 2 Infrastructure Complete
-- **🏗️ Dual Architecture** - Separated DevTools test app (`devtools/`) from main logger
-- **⚛️ Preact Application** - Complete test harness with comprehensive UI
-- **🎨 Evergreen UI Integration** - Professional design system with dark theme
-- **🔧 Build Pipeline** - Vite library mode with minification and source maps
-- **🎛️ Professional UI** - Beautiful gradient interface with glass-morphism cards
-
-### ✅ Theme System & Component Migration
-- **🌙 Dark DevTools Theme** - Custom theme matching JSG Logger branding colors
-- **🎯 Component Replacement** - FloatingButton migrated to Evergreen Button + Badge
-- **📦 Theme Provider** - Proper Evergreen ThemeProvider integration
-- **🎨 Design Tokens** - Comprehensive color system and typography scales
-- **📱 Component Architecture** - Clean component structure with proper props
-
-### ✅ Development Environment
-- **📂 Separate Package** - Independent devtools package.json with proper dependencies
-- **🔥 Hot Reload** - Vite dev server on port 5556 with live updates
-- **🔗 React Compatibility** - Evergreen UI working with Preact via compat aliases
-- **🛠️ Build Tools** - Complete development and production build pipeline
+**Date:** March 28, 2026  
+**Session Goal:** 🔌 Add `addTransport()` API to fix reinit guard blocking transport registration  
+**Status:** ✅ **COMPLETE** - Published as v1.8.4
+
+## 🎉 ACCOMPLISHMENTS THIS SESSION
+
+### ✅ `addTransport()` API — v1.8.3 → v1.8.4
+
+**Problem:** `jsg-logger` calls `getInstanceSync()` at module evaluation time (no options), initializing the singleton. When Next.js `instrumentation.ts` later called `getInstanceSync({ transports: [...] })`, the reinit guard (introduced in v1.8.2) silently dropped the options — including the transports. The PostHog transport was never registered.
+
+**Fix:**
+- Added `JSGLogger.addTransport(transport: LogTransport): void` static method
+- Exposed on default export as `enhancedLoggers.addTransport`
+- Updated `index.d.ts` with typings for both `JSGLogger` and `LoggerInstanceType`
+- Updated CHANGELOG and README (`## 🔌 External Transport Integration` section)
+
+**Consumer change in `set-times-app/src/instrumentation.ts`:**
+```typescript
+// Before (broken - reinit guard silently dropped transports):
+JSGLogger.getInstanceSync({ ...loggerConfig, transports: [new PostHogServerTransport(...)] });
+
+// After (works at any lifecycle point):
+JSGLogger.addTransport(new PostHogServerTransport(posthogServer, { level: 'warn' }));
+```
 
 ## 🎯 Current Status
 
-### **DevTools Panel: WORKING with Minor Theme Issues** 🎉
-- **Panel Loads**: Successfully initializes and renders floating button
-- **Logger Integration**: JSG Logger imports and initializes correctly
-- **API Confirmed**: `enableDevPanel()` works, all 13 components loaded
-- **Theme Issue**: Text components missing theme.colors (non-blocking)
-
-### **What's Working**
-- ✅ **JSG Logger** - Loads from `@crimsonsunset/jsg-logger` package (file: dependency)
-- ✅ **DevTools Panel** - Initializes and renders floating 🎛️ button
-- ✅ **Vite Dev Server** - Running on port 5556 with hot reload
-- ✅ **Test App** - All logger testing features functional
-- ✅ **Console Logging** - Beautiful formatted output with 13 components
-
-### **Minor Issues Remaining** ⚠️
-- ⚠️ **Text Theme**: Evergreen Text components throw `undefined.colors` errors
-- ⚠️ **Panel Content**: May not be fully visible due to theme data issues
-
-## 📋 IMMEDIATE PRIORITIES
-
-### **🚀 Ready to Publish v1.5.0:**
-- [x] **Environment Detection** - Enhanced CLI detection with multi-signal check
-- [x] **Force Environment** - Config option to override auto-detection
-- [x] **Custom Components** - Auto-create loggers for any component name
-- [x] **Documentation** - README, CHANGELOG updated with v1.5.0 features
-- [x] **Version Bump** - Package version updated to 1.5.0
-- [ ] **Publish to NPM** - `npm run release:minor` when ready
-
-### **🔧 DevTools Theme Fixes (Optional, Low Priority):**
-- [ ] **Fix Text Components** - Pass theme data correctly to Evergreen UI Text components
-- [ ] **Test Panel Interaction** - Click floating button and verify panel opens
-- [ ] **Verify Filtering** - Test component toggles affect console output
-- [ ] **Apply Custom Theme** - Implement devtools-theme.js once basic theme works
-
-### **✅ COMPLETED THIS SESSION:**
-- [x] **CLI Context Data Display** - Custom formatter with tree rendering
-- [x] **Environment Detection Fixed** - Multi-signal CLI detection (TTY, TERM, CI check)
-- [x] **forceEnvironment Config** - Override auto-detection via config
-- [x] **Custom Component Names** - getComponent() auto-creates loggers
-- [x] **Config Loading Order** - Load config BEFORE environment detection
-- [x] **Dependency Cleanup** - Removed pino-colada from package
-- [x] **Documentation Complete** - README, CHANGELOG, version bump
-
-## 🔮 Future Possibilities (Phase 10)
-
-### **Developer Experience Enhancements** (Optional)
-**Current friction points identified:**
-- Manual logger-config.json creation
-- Component definition setup
-- New project onboarding
-
-**Potential solutions:**
-- **CLI Generator**: `npx create-jsg-logger-config`
-- **Project Templates**: Pre-built configs for React, Node.js, Chrome extensions
-- **Quick Start**: `JSGLogger.quickStart()` with auto-detection
-- **Better Errors**: Helpful validation and suggestions
-
-### **Success Metrics for Phase 10:**
-- New project setup in < 30 seconds
-- Zero manual config creation needed
-- Out-of-the-box support for common project types
-
-## 🎯 Next Session Possibilities
-
-### **Option 1: Ship v1.2.0 and Monitor** (Recommended)
-- Publish the fully generic logger
-- Monitor adoption and gather feedback
-- Address any issues that emerge from real-world usage
-
-### **Option 2: Phase 10 DX Enhancements** (Nice-to-have)
-- Build CLI config generator
-- Create project templates
-- Add quick-start modes
-
-### **Option 3: Maintenance Mode**
-- JSG Logger is feature-complete for core logging needs
-- Focus on other projects while monitoring for bug reports
-
-## 📊 Phase 9 Impact Summary
-
-### **Generic Transformation:**
-- **Before**: 10+ hardcoded legacy components, CACP-specific references
-- **After**: 1 minimal 'core' component, 100% project-agnostic
-- **Breaking Changes**: Projects must define components in config
-- **Migration**: Simple config file creation for existing users
-
-### **Code Quality:**
-- **Zero Legacy References**: Exhaustive cleanup completed
-- **Clean Architecture**: No hardcoded project assumptions
-- **Dynamic Systems**: Auto-generation replaces hardcoded logic
-- **Semantic Versioning**: v1.2.0 properly indicates breaking changes
-
-### **Deployment Readiness:** ✅ PRODUCTION READY
-**The JSG Logger is now a completely generic, professional logging package that can be deployed in any JavaScript project with minimal configuration.**
+- **v1.8.4 published** to npm
+- `set-times-app` updated to `@crimsonsunset/jsg-logger@1.8.4`
+- Server-side PostHog transport verified working
+
+## 📋 Immediate Priorities
+
+- [ ] Verify no edge cases with `addTransport()` when called before any `getInstanceSync()`
+- [ ] Consider adding transport removal API (`removeTransport`) if needed
+
+## 🔮 Future Possibilities
+
+- **Transport removal**: `JSGLogger.removeTransport(transport)` for hot-unload scenarios
+- **Transport listing**: `JSGLogger.getTransports()` for debugging
+- **Typed transport levels**: Enforce `level` is a valid `LogLevel` at compile time

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crimsonsunset/jsg-logger",
-  "version": "1.8.3",
+  "version": "1.8.4",
   "type": "module",
   "description": "Multi-environment logger with smart detection, file-level overrides, and beautiful console formatting. Test it live: https://logger.joesangiorgio.com/",
   "main": "index.js",