VibeCoding Logger - TypeScript/Node.js Implementation

AI-Native Logging for LLM Agent Development

This is the TypeScript/Node.js implementation of VibeCoding Logger, designed to maintain full JSON compatibility with the Python version while following TypeScript best practices.

✨ Features

- 🤖 AI-Optimized JSON Logging - Structured format perfect for LLM consumption
- 🔗 Correlation Tracking - Link related operations across your application
- 💬 Human Annotations - Embed AI instructions directly in logs
- 🧵 Thread-Safe Operations - Safe for concurrent Node.js applications
- 📁 Automatic File Management - Timestamped files with rotation
- 💾 Memory Management - Configurable limits to prevent memory issues
- 🌍 Environment Detection - Automatic runtime environment information
- 📊 Zero Dependencies - Minimal footprint, maximum compatibility

🚀 Quick Start

$3

``bash
npm install vibe-logger
`

$3

`typescript
import { createFileLogger } from 'vibe-logger';

// Create logger with auto-save to timestamped file
const logger = createFileLogger('my-project');

// Log with rich context for AI analysis
await logger.info('user_login', 'User authentication started', {
context: {
userId: '123',
method: 'oauth',
ipAddress: '192.168.1.100'
},
humanNote: 'Monitor for suspicious patterns',
aiTodo: 'Check if multiple failed attempts from this IP'
});

// Log exceptions with full context
try {
await riskyOperation();
} catch (error) {
await logger.logException('payment_processing', error, {
context: { orderId: 'order-123', amount: 99.99 },
aiTodo: 'Suggest error handling improvements'
});
}

// Get logs formatted for AI analysis
const aiContext = await logger.getLogsForAI();
console.log(aiContext); // Send this to your LLM
`

📖 API Reference

$3

`typescript
import { createLogger, createFileLogger, createEnvLogger } from 'vibe-logger';

// Basic logger
const logger = createLogger({
correlationId: 'custom-id',
keepLogsInMemory: true,
autoSave: false
});

// File logger (recommended)
const fileLogger = createFileLogger('project-name');

// Environment-configured logger
const envLogger = createEnvLogger(); // Uses VIBE_* env vars
`

$3

`typescript
// All methods return Promise
await logger.debug(operation, message, options?);
await logger.info(operation, message, options?);
await logger.warning(operation, message, options?);
await logger.error(operation, message, options?);
await logger.critical(operation, message, options?);

// Exception logging
await logger.logException(operation, error, options?);
`

$3

`typescript
interface LogOptions {
context?: Record; // Rich context data
humanNote?: string; // Instructions for AI
aiTodo?: string; // Specific AI tasks
includeStack?: boolean; // Force stack trace inclusion
}
`

⚙️ Configuration

$3

`typescript
import { createLogger, type VibeLoggerConfig } from 'vibe-logger';

const config: VibeLoggerConfig = {
correlationId: 'custom-correlation-id',
logFile: './logs/app.log',
autoSave: true,
maxFileSizeMb: 50,
keepLogsInMemory: true,
maxMemoryLogs: 1000,
createDirs: true
};

const logger = createLogger(config);
`

$3

`bash
export VIBE_LOG_FILE=./logs/app.log
export VIBE_MAX_FILE_SIZE_MB=25
export VIBE_AUTO_SAVE=true
export VIBE_KEEP_LOGS_IN_MEMORY=true
export VIBE_MAX_MEMORY_LOGS=500
export VIBE_CORRELATION_ID=my-service-id
`

🔧 Advanced Usage

$3

`typescript
// For long-running services - minimize memory usage
const logger = createLogger({
keepLogsInMemory: false, // Don't store in memory
autoSave: true, // Save directly to file
maxFileSizeMb: 100 // Rotate at 100MB
});
`

$3

`typescript
// Use same correlation ID across related operations
const correlationId = request-${Date.now()};
const logger = createLogger({ correlationId });

await logger.info('request_start', 'Processing API request');
await logger.info('auth_check', 'Validating credentials');
await logger.info('business_logic', 'Executing core logic');
await logger.info('request_end', 'Request completed');

// All logs will have the same correlation_id
`

$3

`typescript
// Handles all JavaScript error types
const errors = [
new Error('Standard error'),
'String error',
{ custom: 'object error' },
42,
null
];

for (const error of errors) {
await logger.logException('error_handling', error);
}
`

📊 Log Format

Logs are structured JSON compatible with the Python implementation:

`json
{
"timestamp": "2025-07-07T10:30:45.123Z",
"level": "ERROR",
"correlation_id": "req-abc-123",
"operation": "payment_processing",
"message": "Payment gateway timeout",
"context": {
"orderId": "order-123",
"amount": 99.99,
"gateway": "stripe"
},
"environment": {
"node_version": "v20.10.0",
"os": "darwin",
"platform": "Darwin",
"architecture": "arm64",
"runtime": "node"
},
"source": "payment.ts:42 in processPayment()",
"stack_trace": "Error: Payment gateway timeout\n at processPayment...",
"human_note": "Payment timeouts have increased lately",
"ai_todo": "Analyze payment gateway performance trends"
}
`

🧪 Testing

`bash


Build the project

npm run build

Run tests

npm test

Run tests in watch mode

npm run test:watch

Type checking

npm run lint
`

📁 File Organization

Logs are automatically organized with timestamps in your project folder:

`
./logs/
├── my-project/
│ ├── vibe_20250707_143052.log
│ ├── vibe_20250707_151230.log
│ └── vibe_20250707_163045.log.20250707_170000 # Rotated
└── other-project/
└── vibe_20250707_144521.log
`

🎯 AI Integration Workflow

1. Code with VibeCoding Logger - Add rich logging throughout your application
2. Run Your Code - Logger captures detailed context automatically
3. Get AI Analysis - Use getLogsForAI() to get formatted data
4. Send to LLM - Paste structured logs into ChatGPT, Claude, etc.
5. Get Precise Solutions - LLM provides targeted fixes with full context

🔗 Cross-Language Compatibility

This TypeScript implementation maintains 100% JSON format compatibility with:
- Python (reference implementation)
- Future languages (Go, Rust, etc.)

📚 Examples

See the examples/` directory for:
- Basic usage patterns
- Advanced configuration
- Error handling
- Memory management
- Correlation tracking

🤝 Contributing

Contributions welcome! Please see the main repository guidelines and:

1. Follow TypeScript best practices
2. Maintain JSON compatibility with Python version
3. Add tests for new features
4. Update documentation

📄 License

MIT License - see LICENSE file for details.

---

Built for the VibeCoding era - where humans design and AI implements. 🚀