@compilr-dev/logger 0.1.0

package/LICENSE

@@ -0,0 +1,108 @@
+Functional Source License, Version 1.1, MIT Future License
+
+Abbreviation: FSL-1.1-MIT
+
+Notice
+
+Copyright 2026 Carmelo Scozzola
+
+Terms and Conditions
+
+Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the MIT license that is effective on the second anniversary of the date we make
+the Software available. On or after that date, you may use the Software under
+the MIT license, in which case the following will apply:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# @compilr-dev/logger
+
+```
+      \|/
+    ╭══════════╮     ___  ___  _ __ ___  _ __ (_) |_ __
+    ║'  ▐▌  ▐▌ │    / __|/ _ \| '_ ` _ \| '_ \| | | '__|
+    ║          │   | (__| (_) | | | | | | |_) | | | |
+    ╰─═──────═─╯    \___|\___/|_| |_| |_| .__/|_|_|_|
+      \________\                        | | .dev
+                                        |_| logger
+```
+
+> Structured logging for the compilr-dev ecosystem
+
+[![npm version](https://img.shields.io/npm/v/@compilr-dev/logger.svg)](https://www.npmjs.com/package/@compilr-dev/logger)
+[![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](https://fsl.software/)
+
+> [!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](https://github.com/pinojs/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
+
+```bash
+npm install @compilr-dev/logger
+```
+
+## Quick Start
+
+```typescript
+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.
+
+```typescript
+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`.
+
+```typescript
+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:
+
+```typescript
+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](https://fsl.software/) — Functional Source License, converts to MIT after 2 years per version.
+
+Copyright (c) Carmelo Scozzola

package/dist/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Config — Environment-based logger configuration.
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
+export interface LoggerOptions {
+    /** Package name added to every log entry (e.g., "desktop", "cli", "sdk") */
+    package?: string;
+    /** Component name added to every log entry (e.g., "ipc", "agent-manager") */
+    component?: string;
+    /** Minimum log level (default: from LOG_LEVEL env or 'info') */
+    level?: LogLevel;
+    /** Write logs to file (absolute path). Enables rotation. */
+    filePath?: string;
+    /** Pretty-print to stdout (default: true when NODE_ENV=development and no filePath) */
+    pretty?: boolean;
+    /** Additional redaction paths (merged with defaults) */
+    redact?: string[];
+    /** Disable stdout/stderr output (useful when only writing to file) */
+    silent?: boolean;
+}
+/**
+ * Resolve the effective log level from options and environment.
+ */
+export declare function resolveLevel(options?: LoggerOptions): LogLevel;
+/**
+ * Determine if pretty-printing should be enabled.
+ */
+export declare function resolvePretty(options?: LoggerOptions): boolean;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1F,MAAM,WAAW,aAAa;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uFAAuF;IACvF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,sEAAsE;IACtE,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,QAAQ,CAa9D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAI9D"}

package/dist/config.js

@@ -0,0 +1,32 @@
+/**
+ * Config — Environment-based logger configuration.
+ */
+const VALID_LEVELS = new Set([
+    'trace', 'debug', 'info', 'warn', 'error', 'fatal', 'silent',
+]);
+/**
+ * Resolve the effective log level from options and environment.
+ */
+export function resolveLevel(options) {
+    // Explicit option takes precedence
+    if (options?.level)
+        return options.level;
+    // Environment variable
+    const envLevel = process.env['LOG_LEVEL']?.toLowerCase();
+    if (envLevel && VALID_LEVELS.has(envLevel))
+        return envLevel;
+    // Development default
+    if (process.env['NODE_ENV'] === 'development')
+        return 'debug';
+    // Production default
+    return 'info';
+}
+/**
+ * Determine if pretty-printing should be enabled.
+ */
+export function resolvePretty(options) {
+    if (options?.pretty !== undefined)
+        return options.pretty;
+    // Pretty in development when outputting to terminal (no file-only mode)
+    return process.env['NODE_ENV'] === 'development' && !options?.silent;
+}

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @compilr-dev/logger — Structured logging for the compilr-dev ecosystem.
+ *
+ * Built on pino. JSON output by default, automatic redaction of sensitive
+ * fields, file rotation, pretty-printing for development.
+ *
+ * Usage:
+ *   import { createLogger } from '@compilr-dev/logger';
+ *   const log = createLogger({ package: 'desktop', component: 'ipc' });
+ *   log.info({ handler: 'files:write', durationMs: 12 }, 'Handler completed');
+ *
+ * For Electron renderer process, use the separate entry point:
+ *   import { createRendererLogger } from '@compilr-dev/logger/renderer';
+ */
+import type { Logger as PinoLogger } from 'pino';
+import { type LoggerOptions } from './config.js';
+/** Logger instance type (pino logger) */
+export type Logger = PinoLogger;
+export type { LoggerOptions, LogLevel } from './config.js';
+export { REDACT_PATHS, SCRUB_PATTERNS, scrubSecrets } from './redaction.js';
+/**
+ * Create a configured logger instance.
+ *
+ * @param options - Logger configuration
+ * @returns A pino logger with redaction, transports, and base fields
+ */
+export declare function createLogger(options?: LoggerOptions): Logger;
+/**
+ * Create a no-op logger that discards all output.
+ * Used as fallback in libraries when no logger is provided.
+ */
+export declare function createSilentLogger(): Logger;
+/**
+ * Default shared logger instance, configured from environment variables.
+ *
+ * For applications, prefer creating your own logger with `createLogger()`
+ * to set package/component context. This default is a convenience for
+ * quick use and testing.
+ */
+export declare const logger: Logger;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAA0B,MAAM,MAAM,CAAC;AAEzE,OAAO,EAA+B,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAK9E,yCAAyC;AACzC,MAAM,MAAM,MAAM,GAAG,UAAU,CAAC;AAGhC,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAI5E;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAoD5D;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAID;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,EAAE,MAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,91 @@
+/**
+ * @compilr-dev/logger — Structured logging for the compilr-dev ecosystem.
+ *
+ * Built on pino. JSON output by default, automatic redaction of sensitive
+ * fields, file rotation, pretty-printing for development.
+ *
+ * Usage:
+ *   import { createLogger } from '@compilr-dev/logger';
+ *   const log = createLogger({ package: 'desktop', component: 'ipc' });
+ *   log.info({ handler: 'files:write', durationMs: 12 }, 'Handler completed');
+ *
+ * For Electron renderer process, use the separate entry point:
+ *   import { createRendererLogger } from '@compilr-dev/logger/renderer';
+ */
+import pino from 'pino';
+import { REDACT_PATHS } from './redaction.js';
+import { resolveLevel, resolvePretty } from './config.js';
+import { prettyTarget, fileTarget } from './transports.js';
+export { REDACT_PATHS, SCRUB_PATTERNS, scrubSecrets } from './redaction.js';
+// ─── Factory ────────────────────────────────────────────────────────────────
+/**
+ * Create a configured logger instance.
+ *
+ * @param options - Logger configuration
+ * @returns A pino logger with redaction, transports, and base fields
+ */
+export function createLogger(options) {
+    const level = resolveLevel(options);
+    const pretty = resolvePretty(options);
+    // Merge default redaction paths with any additional ones
+    const redactPaths = options?.redact
+        ? [...REDACT_PATHS, ...options.redact]
+        : REDACT_PATHS;
+    // Base fields attached to every log entry
+    const base = {};
+    if (options?.package)
+        base['package'] = options.package;
+    if (options?.component)
+        base['component'] = options.component;
+    // Build transport targets
+    const targets = [];
+    if (options?.filePath) {
+        targets.push(fileTarget(options.filePath));
+    }
+    if (!options?.silent) {
+        if (pretty) {
+            targets.push(prettyTarget());
+        }
+        else if (!options?.filePath) {
+            // JSON to stdout (production, no file configured)
+            targets.push({ target: 'pino/file', options: { destination: 1 } }); // fd 1 = stdout
+        }
+    }
+    // If we have both file and stdout, use multi-transport
+    // If we have only one target, use single transport
+    // If no targets (silent + no file), use destination /dev/null equivalent
+    const transport = targets.length > 0
+        ? { targets }
+        : undefined;
+    // When no transport is configured (silent + no file), disable output
+    if (targets.length === 0) {
+        return pino({ level: 'silent' });
+    }
+    return pino({
+        level,
+        base,
+        timestamp: pino.stdTimeFunctions.isoTime,
+        redact: {
+            paths: redactPaths,
+            censor: '[REDACTED]',
+        },
+        transport,
+    });
+}
+// ─── Silent Logger ──────────────────────────────────────────────────────────
+/**
+ * Create a no-op logger that discards all output.
+ * Used as fallback in libraries when no logger is provided.
+ */
+export function createSilentLogger() {
+    return pino({ level: 'silent' });
+}
+// ─── Default Instance ───────────────────────────────────────────────────────
+/**
+ * Default shared logger instance, configured from environment variables.
+ *
+ * For applications, prefer creating your own logger with `createLogger()`
+ * to set package/component context. This default is a convenience for
+ * quick use and testing.
+ */
+export const logger = createLogger();

package/dist/redaction.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Redaction — Sensitive data paths that are automatically masked in log output.
+ *
+ * pino replaces these field values with "[REDACTED]" at serialization time.
+ * This is a safety net — callers should also avoid logging content/bodies.
+ */
+/** Paths automatically redacted in all log output */
+export declare const REDACT_PATHS: string[];
+/**
+ * Patterns for scrubbing log files on export.
+ * These catch secrets that bypassed redaction (e.g., embedded in a string).
+ */
+export declare const SCRUB_PATTERNS: RegExp[];
+/**
+ * Scrub a string of accidentally-included secrets.
+ * Used when exporting logs for user support.
+ */
+export declare function scrubSecrets(text: string): string;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../src/redaction.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,qDAAqD;AACrD,eAAO,MAAM,YAAY,EAAE,MAAM,EAgDhC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,EAiBlC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQjD"}

package/dist/redaction.js

@@ -0,0 +1,88 @@
+/**
+ * Redaction — Sensitive data paths that are automatically masked in log output.
+ *
+ * pino replaces these field values with "[REDACTED]" at serialization time.
+ * This is a safety net — callers should also avoid logging content/bodies.
+ */
+/** Paths automatically redacted in all log output */
+export const REDACT_PATHS = [
+    // Auth tokens & keys (top-level)
+    'apiKey',
+    'api_key',
+    'token',
+    'accessToken',
+    'access_token',
+    'refreshToken',
+    'refresh_token',
+    'secret',
+    'password',
+    'passwd',
+    'authorization',
+    'cookie',
+    'session',
+    'jwt',
+    'credentials',
+    // Nested (one level deep — covers most structured objects)
+    '*.apiKey',
+    '*.api_key',
+    '*.token',
+    '*.accessToken',
+    '*.access_token',
+    '*.refreshToken',
+    '*.refresh_token',
+    '*.secret',
+    '*.password',
+    '*.passwd',
+    '*.authorization',
+    '*.cookie',
+    '*.credentials',
+    // HTTP headers
+    'headers.authorization',
+    'headers.cookie',
+    'headers.set-cookie',
+    'headers.x-api-key',
+    // Environment variables (when accidentally logged)
+    'env.ANTHROPIC_API_KEY',
+    'env.OPENAI_API_KEY',
+    'env.GEMINI_API_KEY',
+    'env.SUPABASE_SERVICE_ROLE_KEY',
+    'env.GITHUB_TOKEN',
+    'env.GH_TOKEN',
+    'env.NPM_TOKEN',
+    'env.DATABASE_URL',
+];
+/**
+ * Patterns for scrubbing log files on export.
+ * These catch secrets that bypassed redaction (e.g., embedded in a string).
+ */
+export const SCRUB_PATTERNS = [
+    // Anthropic API keys
+    /sk-ant-[a-zA-Z0-9_-]{20,}/g,
+    // OpenAI API keys
+    /sk-[a-zA-Z0-9]{20,}/g,
+    // GitHub tokens
+    /ghp_[a-zA-Z0-9]{36}/g,
+    /gho_[a-zA-Z0-9]{36}/g,
+    /ghs_[a-zA-Z0-9]{36}/g,
+    /ghu_[a-zA-Z0-9]{36}/g,
+    /github_pat_[a-zA-Z0-9_]{22,}/g,
+    // npm tokens
+    /npm_[a-zA-Z0-9]{36}/g,
+    // Generic bearer tokens
+    /Bearer [a-zA-Z0-9._-]{20,}/gi,
+    // compilr-dev API tokens
+    /tok_[a-zA-Z0-9]{32,}/g,
+];
+/**
+ * Scrub a string of accidentally-included secrets.
+ * Used when exporting logs for user support.
+ */
+export function scrubSecrets(text) {
+    let result = text;
+    for (const pattern of SCRUB_PATTERNS) {
+        // Reset lastIndex for global regexes
+        pattern.lastIndex = 0;
+        result = result.replace(pattern, '[SCRUBBED]');
+    }
+    return result;
+}

package/dist/renderer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Renderer Logger — IPC-based logger for Electron renderer process.
+ *
+ * The renderer can't write files directly. This module creates a logger-like
+ * interface that sends structured log entries to the main process via IPC,
+ * where they're written to the same log file.
+ *
+ * Usage:
+ *   import { createRendererLogger } from '@compilr-dev/logger/renderer';
+ *   const log = createRendererLogger({ component: 'chat' });
+ *   log.info('Message sent');
+ *
+ * The main process must register the IPC handler:
+ *   ipcMain.on('log:write', (_event, entry) => mainLogger[entry.level](entry, entry.msg));
+ */
+import type { LogLevel } from './config.js';
+export interface RendererLoggerOptions {
+    /** Component name added to every log entry */
+    component?: string;
+    /** Package name (default: "desktop-renderer") */
+    package?: string;
+    /** Minimum log level (default: 'info') */
+    level?: LogLevel;
+}
+type LogFn = (msgOrObj: string | Record<string, unknown>, msg?: string) => void;
+export interface RendererLogger {
+    trace: LogFn;
+    debug: LogFn;
+    info: LogFn;
+    warn: LogFn;
+    error: LogFn;
+    fatal: LogFn;
+    child: (bindings: Record<string, unknown>) => RendererLogger;
+    level: string;
+}
+/**
+ * Create a renderer-side logger that sends entries to the main process.
+ */
+export declare function createRendererLogger(options?: RendererLoggerOptions): RendererLogger;
+export {};
+//# sourceMappingURL=renderer.d.ts.map

package/dist/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAI5C,MAAM,WAAW,qBAAqB;IACpC,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,QAAQ,CAAC;CAClB;AAWD,KAAK,KAAK,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AAEhF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,IAAI,EAAE,KAAK,CAAC;IACZ,IAAI,EAAE,KAAK,CAAC;IACZ,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,cAAc,CAAC;IAC7D,KAAK,EAAE,MAAM,CAAC;CACf;AA0CD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,CAAC,EAAE,qBAAqB,GAAG,cAAc,CAiDpF"}

package/dist/renderer.js

@@ -0,0 +1,99 @@
+/**
+ * Renderer Logger — IPC-based logger for Electron renderer process.
+ *
+ * The renderer can't write files directly. This module creates a logger-like
+ * interface that sends structured log entries to the main process via IPC,
+ * where they're written to the same log file.
+ *
+ * Usage:
+ *   import { createRendererLogger } from '@compilr-dev/logger/renderer';
+ *   const log = createRendererLogger({ component: 'chat' });
+ *   log.info('Message sent');
+ *
+ * The main process must register the IPC handler:
+ *   ipcMain.on('log:write', (_event, entry) => mainLogger[entry.level](entry, entry.msg));
+ */
+// ─── Level Gating ───────────────────────────────────────────────────────────
+const LEVEL_VALUES = {
+    trace: 10,
+    debug: 20,
+    info: 30,
+    warn: 40,
+    error: 50,
+    fatal: 60,
+    silent: Infinity,
+};
+// ─── IPC Send ───────────────────────────────────────────────────────────────
+/**
+ * Send a log entry to the main process via IPC.
+ * Uses window.compilr.log.write if available, falls back to console.
+ */
+function sendToMain(entry) {
+    // Check if the IPC bridge is available (Electron preload)
+    const w = globalThis;
+    const compilr = w['compilr'];
+    const logBridge = compilr?.['log'];
+    const writeFn = logBridge?.['write'];
+    if (writeFn) {
+        writeFn(entry);
+    }
+    else {
+        // Fallback: browser console (development, or IPC not yet ready)
+        const consoleFn = entry.level === 'error' || entry.level === 'fatal'
+            ? console.error // eslint-disable-line no-console
+            : entry.level === 'warn'
+                ? console.warn // eslint-disable-line no-console
+                : console.log; // eslint-disable-line no-console
+        consoleFn(`[${entry.component ?? entry.package ?? 'renderer'}] ${entry.msg}`, entry);
+    }
+}
+// ─── Factory ────────────────────────────────────────────────────────────────
+/**
+ * Create a renderer-side logger that sends entries to the main process.
+ */
+export function createRendererLogger(options) {
+    const pkg = options?.package ?? 'desktop-renderer';
+    const component = options?.component;
+    const minLevel = LEVEL_VALUES[options?.level ?? 'info'] ?? 30;
+    function makeLogFn(level) {
+        const levelValue = LEVEL_VALUES[level] ?? 30;
+        return (msgOrObj, msg) => {
+            // Level gating — skip if below threshold
+            if (levelValue < minLevel)
+                return;
+            const entry = {
+                level,
+                package: pkg,
+                time: new Date().toISOString(),
+                msg: '',
+            };
+            if (component)
+                entry['component'] = component;
+            if (typeof msgOrObj === 'string') {
+                entry.msg = msgOrObj;
+            }
+            else {
+                Object.assign(entry, msgOrObj);
+                entry.msg = msg ?? '';
+            }
+            sendToMain(entry);
+        };
+    }
+    const loggerInstance = {
+        trace: makeLogFn('trace'),
+        debug: makeLogFn('debug'),
+        info: makeLogFn('info'),
+        warn: makeLogFn('warn'),
+        error: makeLogFn('error'),
+        fatal: makeLogFn('fatal'),
+        level: options?.level ?? 'info',
+        child: (bindings) => {
+            return createRendererLogger({
+                ...options,
+                package: bindings['package'] ?? pkg,
+                component: bindings['component'] ?? component,
+            });
+        },
+    };
+    return loggerInstance;
+}

package/dist/transports.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Transports — pino transport configurations for file, pretty, and multi-target.
+ */
+import type { TransportTargetOptions } from 'pino';
+/**
+ * Build a pretty-print transport target (for development).
+ */
+export declare function prettyTarget(): TransportTargetOptions;
+/**
+ * Build a file rotation transport target.
+ *
+ * Uses pino-roll: rotates daily or at 10MB, keeps last 5 files.
+ */
+export declare function fileTarget(filePath: string): TransportTargetOptions;
+//# sourceMappingURL=transports.d.ts.map

package/dist/transports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transports.d.ts","sourceRoot":"","sources":["../src/transports.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,MAAM,CAAC;AAEnD;;GAEG;AACH,wBAAgB,YAAY,IAAI,sBAAsB,CAUrD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAYnE"}

package/dist/transports.js

@@ -0,0 +1,35 @@
+/**
+ * Transports — pino transport configurations for file, pretty, and multi-target.
+ */
+/**
+ * Build a pretty-print transport target (for development).
+ */
+export function prettyTarget() {
+    return {
+        target: 'pino-pretty',
+        options: {
+            colorize: true,
+            translateTime: 'HH:MM:ss.l',
+            ignore: 'pid,hostname',
+            messageFormat: '{if package}[{package}]{end}{if component}.{component}{end} {msg}',
+        },
+    };
+}
+/**
+ * Build a file rotation transport target.
+ *
+ * Uses pino-roll: rotates daily or at 10MB, keeps last 5 files.
+ */
+export function fileTarget(filePath) {
+    return {
+        target: 'pino-roll',
+        options: {
+            file: filePath,
+            frequency: 'daily',
+            size: '10m',
+            limit: { count: 5 },
+            dateFormat: 'yyyy-MM-dd',
+            mkdir: true,
+        },
+    };
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@compilr-dev/logger",
+  "version": "0.1.0",
+  "description": "Structured logging for the compilr-dev ecosystem",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./renderer": {
+      "import": "./dist/renderer.js",
+      "types": "./dist/renderer.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src/",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "test": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "pino": "^9.6.0",
+    "pino-pretty": "^13.0.0",
+    "pino-roll": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Carmelo Scozzola",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scozzola/compilr-dev-logger.git"
+  },
+  "keywords": [
+    "logging",
+    "pino",
+    "structured-logging",
+    "compilr-dev"
+  ]
+}