tessl/npm-web-ext

A command line tool to help build, run, and test web extensions

—

Pending

Overview

Eval results

Files

Logging System

Name: tessl/npm-web-ext
Author: tessl

Configurable logging infrastructure with console output, verbose modes, log capture capabilities, and integration with the pino logging library for structured logging.

Capabilities

Logger Creation

Create module-specific loggers with consistent formatting and configuration.

/**
 * Create a logger instance for a specific module
 * @param moduleURL - Module URL (typically import.meta.url)
 * @param options - Logger configuration options
 * @returns Configured pino logger instance
 */
function createLogger(moduleURL: string, options?: LoggerOptions): Logger;

interface LoggerOptions {
  /** Custom pino logger factory */
  createPinoLog?: Function;
}

interface Logger {
  /** Log debug messages (only shown in verbose mode) */
  debug(message: string, ...args: any[]): void;
  /** Log informational messages */
  info(message: string, ...args: any[]): void;
  /** Log warning messages */
  warn(message: string, ...args: any[]): void;
  /** Log error messages */
  error(message: string, ...args: any[]): void;
  /** Log fatal error messages */
  fatal(message: string, ...args: any[]): void;
}

Usage Examples:

import { createLogger } from "web-ext/util/logger";

// Create module-specific logger
const log = createLogger(import.meta.url);

// Log at different levels
log.info('Extension build started');
log.debug('Processing file:', filePath);
log.warn('Deprecated API usage detected');
log.error('Build failed:', error.message);

// Logger with custom options
const customLog = createLogger(import.meta.url, {
  createPinoLog: customPinoFactory
});

Console Stream

Custom stream implementation for handling log output with verbose mode support and log capture capabilities.

class ConsoleStream {
  constructor(options?: ConsoleStreamOptions);
  /** Format log message for console output */
  format(logData: LogData): string;
  /** Enable verbose logging mode */
  makeVerbose(): void;
  /** Write log data to appropriate output stream */
  write(jsonString: string, options?: WriteOptions): void;
  /** Start capturing logs in memory */
  startCapturing(): void;
  /** Stop capturing and clear buffer */
  stopCapturing(): void;
  /** Output captured logs to console */
  flushCapturedLogs(options?: FlushOptions): void;
}

interface ConsoleStreamOptions {
  /** Start in verbose mode */
  verbose?: boolean;
}

interface LogData {
  /** Logger name/module identifier */
  name: string;
  /** Log message */
  msg: string;
  /** Log level (10=debug, 20=info, 30=warn, 40=error, 50=fatal) */
  level: number;
  /** Timestamp */
  time: number;
  /** Additional log properties */
  [key: string]: any;
}

interface WriteOptions {
  /** Character encoding */
  encoding?: string;
}

interface FlushOptions {
  /** Output stream to flush to */
  stream?: NodeJS.WritableStream;
}

Usage Examples:

import { ConsoleStream } from "web-ext/util/logger";

// Create custom console stream
const stream = new ConsoleStream({ verbose: true });

// Capture logs for processing
stream.startCapturing();

// ... perform operations that generate logs ...

// Output captured logs
stream.flushCapturedLogs();
stream.stopCapturing();

Shared Console Stream

Pre-configured console stream instance used throughout web-ext.

/** Shared console stream instance for consistent logging */
const consoleStream: ConsoleStream;

Usage Example:

import { consoleStream } from "web-ext/util/logger";

// Enable verbose mode globally
consoleStream.makeVerbose();

// Start capturing for later analysis
consoleStream.startCapturing();

Log Formatting

The logging system provides structured, readable output with consistent formatting.

Standard Format

[timestamp] LEVEL (module): message

Example output:

[14:23:45] INFO (cmd/build): Building extension from ./my-extension
[14:23:45] DEBUG (util/manifest): Reading manifest.json
[14:23:46] WARN (cmd/build): File ignored: node_modules/package.json
[14:23:46] INFO (cmd/build): Extension built successfully: ./web-ext-artifacts/extension.zip

Verbose Format

In verbose mode, additional context and stack traces are included:

[14:23:45] DEBUG (util/file-filter): Processing file: src/content.js
  → File matches pattern: **/*.js
  → File size: 2.1KB
  → Including in package

Log Levels

The logging system supports standard log levels with appropriate console output:

enum LogLevel {
  /** Debug information (verbose mode only) */
  DEBUG = 10,
  /** General information */
  INFO = 20,
  /** Warning messages */
  WARN = 30,
  /** Error messages */
  ERROR = 40,
  /** Fatal errors */
  FATAL = 50
}

Level Behavior:

DEBUG: Only shown in verbose mode, useful for troubleshooting
INFO: Standard operational messages, always shown
WARN: Potential issues that don't prevent operation
ERROR: Serious problems that may cause failures
FATAL: Critical errors that prevent continued operation

Log Capture and Replay

Capture logs in memory for testing, analysis, or delayed output.

/**
 * Start capturing log messages in memory
 * @returns void
 */
function startCapturing(): void;

/**
 * Stop capturing and clear the capture buffer
 * @returns void
 */
function stopCapturing(): void;

/**
 * Output all captured logs to console
 * @param options - Flush configuration
 * @returns void
 */
function flushCapturedLogs(options?: FlushOptions): void;

Usage Example:

import { consoleStream } from "web-ext/util/logger";

// Capture logs during operation
consoleStream.startCapturing();

try {
  await performOperation();
  // Only show logs if operation succeeded
  consoleStream.flushCapturedLogs();
} catch (error) {
  // Don't show captured logs on error
  console.error('Operation failed:', error.message);
} finally {
  consoleStream.stopCapturing();
}

Integration with Pino

web-ext uses the pino logging library for structured logging with performance and flexibility benefits.

interface PinoLogger {
  /** Log at debug level */
  debug(obj: object, msg?: string): void;
  debug(msg: string, ...args: any[]): void;
  
  /** Log at info level */
  info(obj: object, msg?: string): void;
  info(msg: string, ...args: any[]): void;
  
  /** Log at warn level */
  warn(obj: object, msg?: string): void;
  warn(msg: string, ...args: any[]): void;
  
  /** Log at error level */
  error(obj: object, msg?: string): void;
  error(msg: string, ...args: any[]): void;
  
  /** Log at fatal level */
  fatal(obj: object, msg?: string): void;
  fatal(msg: string, ...args: any[]): void;
}

Module-Specific Logging

Each web-ext module creates its own logger instance for better organization and debugging.

Module Examples:

// In build.js
const log = createLogger(import.meta.url);
log.info('Starting extension build process');

// In run.js  
const log = createLogger(import.meta.url);
log.debug('Configuring Firefox profile');

// In lint.js
const log = createLogger(import.meta.url);
log.warn('Deprecated API usage detected in manifest');

This creates organized log output like:

[14:23:45] INFO (cmd/build): Starting extension build process
[14:23:45] DEBUG (cmd/run): Configuring Firefox profile  
[14:23:46] WARN (cmd/lint): Deprecated API usage detected in manifest

Verbose Mode Integration

The logging system integrates with web-ext's global verbose mode:

/**
 * Enable verbose mode for enhanced logging output
 * @param logStream - Console stream to make verbose
 * @param version - web-ext version for context
 * @returns void
 */
function enableVerboseMode(logStream: ConsoleStream, version: string): void;

When verbose mode is enabled:

Debug messages are shown
Additional context is included
Stack traces are displayed for errors
File operation details are logged
Network request/response information is shown

Error Logging

Enhanced error logging with stack traces and context:

try {
  await riskyOperation();
} catch (error) {
  // In normal mode: shows error message
  // In verbose mode: shows full stack trace and context
  log.error('Operation failed:', error);
}

Performance Considerations

The logging system is designed for minimal performance impact:

Debug messages are completely skipped when not in verbose mode
Log formatting is lazy (only when needed)
Structured logging reduces string concatenation overhead
Console stream buffering reduces I/O operations

Usage Example for Performance:

// Efficient: debug message skipped entirely when not verbose
log.debug('Processing file: %s', expensiveComputation());

// Inefficient: always computes even when not verbose
log.debug(`Processing file: ${expensiveComputation()}`);

Install with Tessl CLI