@startsimpli/logging 0.1.0

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@startsimpli/logging",
+  "version": "0.1.0",
+  "description": "Structured logging for StartSimpli apps",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": ["src"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.33",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { logger, createLogger } from './logger';
+export type { Logger, LogLevel } from './logger';

package/src/logger.ts

@@ -0,0 +1,203 @@
+/**
+ * Structured logger for StartSimpli applications.
+ *
+ * Usage:
+ *   import { logger, createLogger } from '@startsimpli/logging';
+ *
+ *   // Default instance
+ *   logger.info('Request received', { path: '/api/recipes' });
+ *
+ *   // Named instance
+ *   const log = createLogger('llm-pipeline');
+ *   log.debug('Calling provider', { model: 'gpt-4' });
+ *
+ *   // Child logger with request context
+ *   const reqLog = log.withContext({ requestId: 'abc123', userId: '42' });
+ *   reqLog.warn('Retry attempt', { attempt: 2 });
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+
+export interface Logger {
+  debug(message: string, data?: Record<string, unknown>): void;
+  info(message: string, data?: Record<string, unknown>): void;
+  warn(message: string, data?: Record<string, unknown>): void;
+  error(message: string, data?: Record<string, unknown>): void;
+  withContext(ctx: Record<string, unknown>): Logger;
+}
+
+// ---------------------------------------------------------------------------
+// Internal types
+// ---------------------------------------------------------------------------
+
+type LogData = Record<string, unknown>;
+
+interface LogEntry {
+  level: LogLevel;
+  message: string;
+  timestamp: string;
+  name?: string;
+  data?: LogData;
+  context?: LogData;
+}
+
+// ---------------------------------------------------------------------------
+// Level resolution
+// ---------------------------------------------------------------------------
+
+const LOG_LEVEL_RANK: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4,
+};
+
+function resolveLogLevel(): LogLevel {
+  const envLevel = (process.env['LOG_LEVEL'] ?? '').toLowerCase() as LogLevel;
+  if (envLevel in LOG_LEVEL_RANK) return envLevel;
+  return process.env['NODE_ENV'] === 'development' ? 'debug' : 'info';
+}
+
+function shouldLog(level: LogLevel): boolean {
+  return LOG_LEVEL_RANK[level] >= LOG_LEVEL_RANK[resolveLogLevel()];
+}
+
+// ---------------------------------------------------------------------------
+// Sensitive data sanitization
+// ---------------------------------------------------------------------------
+
+const SENSITIVE_SUBSTRINGS = [
+  'password',
+  'token',
+  'secret',
+  'key',
+  'authorization',
+  'cookie',
+];
+
+function sanitize(data?: LogData): LogData | undefined {
+  if (!data) return undefined;
+
+  const out: LogData = {};
+
+  for (const [k, v] of Object.entries(data)) {
+    const lower = k.toLowerCase();
+    if (SENSITIVE_SUBSTRINGS.some(sub => lower.includes(sub))) {
+      out[k] = '[REDACTED]';
+    } else if (v instanceof Error) {
+      out[k] = {
+        name: v.name,
+        message: v.message,
+        stack: process.env['NODE_ENV'] === 'development' ? v.stack : undefined,
+      };
+    } else {
+      out[k] = v;
+    }
+  }
+
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+
+function format(entry: LogEntry): string {
+  const { level, message, timestamp, name, data, context } = entry;
+  const nameTag = name ? ` [${name}]` : '';
+  const prefix = `[${timestamp}] [${level.toUpperCase()}]${nameTag}`;
+
+  if (process.env['NODE_ENV'] === 'development') {
+    let out = `${prefix} ${message}`;
+    if (context && Object.keys(context).length > 0) {
+      out += ` [ctx: ${JSON.stringify(context)}]`;
+    }
+    if (data && Object.keys(data).length > 0) {
+      out += `\n  ${JSON.stringify(data, null, 2).split('\n').join('\n  ')}`;
+    }
+    return out;
+  }
+
+  return JSON.stringify(entry);
+}
+
+// ---------------------------------------------------------------------------
+// Logger implementation
+// ---------------------------------------------------------------------------
+
+class LoggerImpl implements Logger {
+  private readonly name?: string;
+  private readonly context?: LogData;
+
+  constructor(name?: string, context?: LogData) {
+    this.name = name;
+    this.context = context;
+  }
+
+  withContext(ctx: Record<string, unknown>): Logger {
+    return new LoggerImpl(this.name, { ...this.context, ...ctx });
+  }
+
+  private emit(level: LogLevel, message: string, data?: LogData): void {
+    if (!shouldLog(level)) return;
+
+    const entry: LogEntry = {
+      level,
+      message,
+      timestamp: new Date().toISOString(),
+      name: this.name,
+      data: sanitize(data),
+      context: this.context,
+    };
+
+    const line = format(entry);
+
+    switch (level) {
+      case 'debug':
+      case 'info':
+        // eslint-disable-next-line no-console
+        console.log(line);
+        break;
+      case 'warn':
+        // eslint-disable-next-line no-console
+        console.warn(line);
+        break;
+      case 'error':
+        // eslint-disable-next-line no-console
+        console.error(line);
+        break;
+    }
+  }
+
+  debug(message: string, data?: LogData): void {
+    this.emit('debug', message, data);
+  }
+
+  info(message: string, data?: LogData): void {
+    this.emit('info', message, data);
+  }
+
+  warn(message: string, data?: LogData): void {
+    this.emit('warn', message, data);
+  }
+
+  error(message: string, data?: LogData): void {
+    this.emit('error', message, data);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a named logger instance. The name appears in every log line to make
+ * it easy to filter output by subsystem (e.g. 'llm-pipeline', 'auth').
+ */
+export function createLogger(name?: string): Logger {
+  return new LoggerImpl(name);
+}
+
+/** Default logger with no name prefix, suitable for top-level app code. */
+export const logger: Logger = new LoggerImpl();