@compilr-dev/logger

      \|/
    ╭══════════╮     ___  ___  _ __ ___  _ __ (_) |_ __
    ║'  ▐▌  ▐▌ │    / __|/ _ \| '_ ` _ \| '_ \| | | '__|
    ║          │   | (__| (_) | | | | | | |_) | | | |
    ╰─═──────═─╯    \___|\___/|_| |_| |_| .__/|_|_|_|
      \________\                        | | .dev
                                        |_| logger

Structured logging for the compilr-dev ecosystem

[!WARNING] This package is in beta. APIs may change between minor versions.

Overview

A single, shared logging package used across the entire compilr-dev ecosystem — CLI, Desktop, SDK, agents, and factory. Built on pino, the fastest Node.js logger.

• JSON structured output — cloud-native, parseable by GCP/AWS/Azure log aggregators
• Automatic redaction — API keys, tokens, passwords, and 30+ sensitive field patterns masked at serialization time
• File rotation — 10MB x 5 files via pino-roll, daily rotation
• Pretty-print for development — colored, human-readable output via pino-pretty
• Electron renderer support — IPC-based logger bridge for renderer process
• Zero-overhead level gating — disabled levels cost ~5ns per call
• Child loggers — carry context (conversationId, agentId, component) through call chains

Installation

npm install @compilr-dev/logger

Quick Start

import { createLogger } from '@compilr-dev/logger';

// Create a logger for your package
const log = createLogger({
  package: 'desktop',
  component: 'ipc',
  filePath: '~/.compilr-dev/logs/desktop.log',
});

// Structured logging — data in object, message in string
log.info({ handler: 'files:write', durationMs: 12 }, 'Handler completed');

// Error logging — pino serializes Error objects automatically
try {
  await riskyOperation();
} catch (err) {
  log.error({ err }, 'Operation failed');
}

// Child loggers carry context
const agentLog = log.child({ agentId: 'researcher', conversationId: 'conv-123' });
agentLog.debug('Starting tool execution');

Log Levels

| Level | Value | Usage | |-------|-------|-------| | trace | 10 | Verbose diagnostics. Token counts, raw timing. | | debug | 20 | Tool calls, IPC messages, state transitions. | | info | 30 | Normal operations. Default level. | | warn | 40 | Unexpected but recoverable. Retries, fallbacks. | | error | 50 | Operation failed. Stack traces attached. | | fatal | 60 | App cannot continue. |

Default level by environment:

• NODE_ENV=development → debug
• Production → info
• LOG_LEVEL=trace → override via environment variable

API

createLogger(options?)

Create a configured logger instance.

interface LoggerOptions {
  package?: string;    // Added to every log entry (e.g., "desktop", "cli")
  component?: string;  // Added to every log entry (e.g., "ipc", "agent-manager")
  level?: LogLevel;    // Minimum level (default: from LOG_LEVEL env or 'info')
  filePath?: string;   // Write to file with rotation
  pretty?: boolean;    // Pretty-print to stdout (default: true in development)
  redact?: string[];   // Additional redaction paths (merged with defaults)
  silent?: boolean;    // Disable stdout/stderr output
}

createSilentLogger()

Create a no-op logger. Used as fallback in libraries when no logger is provided.

createRendererLogger(options?)

IPC-based logger for Electron renderer process. Import from @compilr-dev/logger/renderer.

import { createRendererLogger } from '@compilr-dev/logger/renderer';
const log = createRendererLogger({ component: 'chat' });
log.info('Message sent');

scrubSecrets(text)

Scrub accidentally-logged secrets from text. Used when exporting logs for support.

Redaction

These fields are automatically replaced with "[REDACTED]" in all output:

• apiKey, token, password, secret, authorization, credentials
• Nested: *.apiKey, *.token, *.password, etc.
• Headers: headers.authorization, headers.cookie
• Environment: env.ANTHROPIC_API_KEY, env.OPENAI_API_KEY, env.GITHUB_TOKEN

For Libraries (Dependency Injection)

Libraries (SDK, agents) should never import the default logger singleton. Accept a logger via config:

import type { Logger } from '@compilr-dev/logger';

interface MyConfig {
  logger?: Logger;
}

function doWork(config: MyConfig) {
  const log = config.logger ?? createSilentLogger();
  log.info('Working...');
}

License

FSL-1.1-MIT — Functional Source License, converts to MIT after 2 years per version.

Copyright (c) Carmelo Scozzola