Logging Mechanism in Wand Enhancer: How the Bridge Layer Handles Diagnostics

Wand Enhancer implements a lightweight, file-based logging system in its Bridge layer (web-panel/bridge/src) that writes timestamped logs to the OS temporary directory while simultaneously outputting prefixed messages to the console.

The logging mechanism in Wand Enhancer provides essential debugging capabilities for the Electron application's bridge component without introducing heavy external dependencies. Located within the web-panel/bridge/src directory, this custom solution leverages Node.js native modules to ensure cross-platform compatibility. The system balances simplicity with functionality, offering both console visibility and persistent file storage for troubleshooting WebSocket connections and wand runtime operations.

Core Architecture of the Logging System

Log File Location and Configuration

The log destination is defined in web-panel/bridge/src/constants.ts through the BRIDGE_LOG_FILE_NAME constant. The actual file path is constructed using os.tmpdir(), ensuring the log file resides in the OS-specific temporary directory (such as /tmp/ on Linux or %TEMP% on Windows). This approach eliminates permissions issues and keeps the application package lightweight by avoiding writes to the installation directory.

The Logger Interface

The primary entry point is createBridgeLogger, exported from web-panel/bridge/src/logger.ts. This factory function returns a logging function with the signature log(level, message, error?), where level accepts 'info', 'warn', or 'error'. The function also exposes a file property containing the absolute path to the current log file, enabling other modules to access log locations programmatically.

// Create a logger for the bridge (e.g., in server.ts)
import { createBridgeLogger } from './logger';

const log = createBridgeLogger({ /* optional custom logFile */ });

log('info', 'Bridge started');                     // → console + log file
log('warn', 'Missing optional config', warning);   // → console.warn + file entry
log('error', 'Unhandled exception', err);          // → console.error + stack trace

// Accessing the log file path (useful for diagnostics)
console.log('Bridge log file:', log.file);

Logging Installation and Runtime Events

The writeInstallLog Helper

For specialized use cases, the module exports writeInstallLog, a thin wrapper around the core logger. This utility is specifically designed for recording installation-related events and is consumed by wand/runtime.ts during trainer setup and wand/renderer-scripts.ts for script-loading operations. This separation allows installation diagnostics to be tracked distinctly from general bridge activity.

// Quick one-off helper used by runtime modules
import { writeInstallLog } from './logger';

function installTrainer() {
  try {
    // …installation logic…
    writeInstallLog('info', 'Trainer installed successfully');
  } catch (e) {
    writeInstallLog('error', 'Trainer installation failed', e);
  }
}

Integration Across the Bridge

WebSocket Server Integration

The WebSocket server (server.ts) initializes a logger instance via createBridgeLogger and propagates it throughout the server runtime. This enables uniform logging for connection events, protocol handling, and error reporting across the bridge's network layer, ensuring that WebSocket diagnostics are captured alongside other bridge operations.

Runtime and Script Loading

The Wand runtime module (wand/runtime.ts) imports writeInstallLog to record trainer installation steps, while the renderer script loader (wand/renderer-scripts.ts) utilizes the same helper for logging script-related actions. This distributed logging approach ensures that critical lifecycle events are persisted regardless of which bridge submodule executes them.

Implementation Details and Design Philosophy

The logging mechanism in Wand Enhancer deliberately avoids external logging libraries to minimize the final Electron ASAR package size. There is no log rotation or complex configuration—just deterministic file appending to a temporary location that works across platforms.

Each log invocation triggers dual output mechanisms. The function forwards messages to console.info, console.warn, or console.error depending on the specified level, prefixing every line with the tag [wand-remote-bridge] for easy filtering. Simultaneously, the internal writeLogLine helper appends a formatted entry to the log file following the pattern [ISO-timestamp] [level] message :: error-stack-if-any, capturing full stack traces when error objects are provided.

This minimalist approach reduces maintenance overhead while providing sufficient visibility for debugging the bridge layer's file system and WebSocket operations.

Summary

• The logging mechanism resides in web-panel/bridge/src/logger.ts and centers on the createBridgeLogger factory function.
• Logs write to the OS temporary directory using os.tmpdir(), with the filename defined in constants.ts as BRIDGE_LOG_FILE_NAME.
• Every log entry outputs to both the console (prefixed with [wand-remote-bridge]) and a timestamped file line via the internal writeLogLine helper.
• Installation events use the specialized writeInstallLog wrapper, consumed by wand/runtime.ts and wand/renderer-scripts.ts.
• The WebSocket server (server.ts) initializes the logger for connection and protocol diagnostics.
• The design prioritizes zero external dependencies and cross-platform compatibility over advanced features like log rotation.

Frequently Asked Questions

Where are Wand Enhancer logs stored?

Logs are stored in the operating system's temporary directory, determined by Node.js's os.tmpdir() function. The specific filename is defined by the BRIDGE_LOG_FILE_NAME constant in web-panel/bridge/src/constants.ts, typically resulting in paths like /tmp/ on Linux or %TEMP% on Windows.

How do I create a logger instance in the Wand Enhancer bridge?

Import createBridgeLogger from web-panel/bridge/src/logger.ts and invoke it to receive a logging function. You can then call this function with a level ('info', 'warn', or 'error'), a message string, and optionally an error object to capture stack traces.

What is the difference between createBridgeLogger and writeInstallLog?

createBridgeLogger returns a full-featured logger instance that tracks both console and file output, while writeInstallLog is a convenience wrapper specifically for installation-related events. The runtime and renderer script modules use writeInstallLog for brevity when logging trainer setup and script loading operations.

Does Wand Enhancer support log rotation or configurable log levels?

No, the logging mechanism is intentionally simple and does not include log rotation, configurable log levels, or external library dependencies. This design keeps the Electron application package lightweight and ensures the bridge layer remains portable across different operating systems without complex configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}