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

> Discover Wand Enhancer's logging mechanism in the Bridge layer. Learn how it creates timestamped logs in the OS temp directory and outputs prefixed console messages for diagnostics.

- Repository: [k1tbyte/Wand-Enhancer](https://github.com/k1tbyte/Wand-Enhancer)
- Tags: internals
- Published: 2026-07-13

---

**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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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.

```ts
// 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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/wand/runtime.ts) during trainer setup and [`wand/renderer-scripts.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/wand/renderer-scripts.ts) for script-loading operations. This separation allows installation diagnostics to be tracked distinctly from general bridge activity.

```ts
// 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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/wand/runtime.ts)) imports `writeInstallLog` to record trainer installation steps, while the renderer script loader ([`wand/renderer-scripts.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/wand/runtime.ts) and [`wand/renderer-scripts.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/wand/renderer-scripts.ts).
- The **WebSocket server** ([`server.ts`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/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.