@link-assistant/agent 0.5.3 → 0.6.0

package/src/util/log-lazy.ts

@@ -0,0 +1,291 @@
+import makeLog, { levels, LogLevel } from 'log-lazy';
+import { Flag } from '../flag/flag.ts';
+
+/**
+ * JSON Lazy Logger
+ *
+ * Implements lazy logging pattern using log-lazy library.
+ * All log output is JSON formatted and wrapped in { log: { ... } } structure
+ * for easy parsing alongside regular JSON output.
+ *
+ * Key features:
+ * - Lazy evaluation: log arguments are only computed if logging is enabled
+ * - JSON output: all logs are parsable JSON in { log: { ... } } format
+ * - Level control: logs respect --verbose flag and LINK_ASSISTANT_AGENT_VERBOSE env
+ * - Type-safe: full TypeScript support
+ *
+ * Usage:
+ *   import { lazyLog } from './util/log-lazy.ts';
+ *
+ *   // Simple string message
+ *   lazyLog.info(() => 'Starting process');
+ *
+ *   // Object data (preferred - avoids expensive JSON.stringify when disabled)
+ *   lazyLog.debug(() => ({ action: 'fetch', url: someUrl }));
+ *
+ *   // Complex computed message
+ *   lazyLog.verbose(() => `Processed ${items.length} items: ${JSON.stringify(items)}`);
+ */
+
+// Custom log levels using bit flags for fine-grained control
+const LEVEL_DISABLED = 0;
+const LEVEL_ERROR = levels.error;
+const LEVEL_WARN = levels.warn | LEVEL_ERROR;
+const LEVEL_INFO = levels.info | LEVEL_WARN;
+const LEVEL_DEBUG = levels.debug | LEVEL_INFO;
+const LEVEL_VERBOSE = levels.verbose | LEVEL_DEBUG;
+const LEVEL_TRACE = levels.trace | LEVEL_VERBOSE;
+
+// Map of preset level configurations
+const LEVEL_PRESETS = {
+  disabled: LEVEL_DISABLED,
+  error: LEVEL_ERROR,
+  warn: LEVEL_WARN,
+  info: LEVEL_INFO,
+  debug: LEVEL_DEBUG,
+  verbose: LEVEL_VERBOSE,
+  trace: LEVEL_TRACE,
+  // Convenience aliases
+  production: LEVEL_WARN,
+  development: LEVEL_DEBUG,
+} as const;
+
+type LevelPreset = keyof typeof LEVEL_PRESETS;
+
+/**
+ * Format a log entry as JSON object wrapped in { log: { ... } }
+ */
+function formatLogEntry(
+  level: string,
+  data: unknown,
+  tags?: Record<string, unknown>
+): string {
+  const timestamp = new Date().toISOString();
+  const logEntry: Record<string, unknown> = {
+    level,
+    timestamp,
+    ...tags,
+  };
+
+  // Handle different data types
+  if (typeof data === 'string') {
+    logEntry.message = data;
+  } else if (data instanceof Error) {
+    logEntry.message = data.message;
+    logEntry.error = {
+      name: data.name,
+      message: data.message,
+      stack: data.stack,
+    };
+  } else if (typeof data === 'object' && data !== null) {
+    // Spread object properties into the log entry
+    Object.assign(logEntry, data);
+  } else {
+    logEntry.message = String(data);
+  }
+
+  return JSON.stringify({ log: logEntry });
+}
+
+/**
+ * Create the output function that writes to stderr
+ */
+function createOutput(
+  level: string,
+  tags?: Record<string, unknown>
+): (data: unknown) => void {
+  return (data: unknown) => {
+    const json = formatLogEntry(level, data, tags);
+    // Use stderr to avoid interfering with stdout JSON output
+    process.stderr.write(json + '\n');
+  };
+}
+
+/**
+ * LazyLogger interface extending log-lazy with JSON output
+ */
+export interface LazyLogger {
+  // Log at info level (default)
+  (fn: () => unknown): void;
+
+  // Log levels
+  error(fn: () => unknown): void;
+  warn(fn: () => unknown): void;
+  info(fn: () => unknown): void;
+  debug(fn: () => unknown): void;
+  verbose(fn: () => unknown): void;
+  trace(fn: () => unknown): void;
+
+  // Level management
+  enableLevel(level: LogLevel): void;
+  disableLevel(level: LogLevel): void;
+  setLevel(level: LevelPreset | number): void;
+  getEnabledLevels(): LogLevel[];
+  shouldLog(level: LogLevel): boolean;
+
+  // Tag support
+  tag(key: string, value: unknown): LazyLogger;
+  clone(): LazyLogger;
+
+  // Configuration
+  readonly enabled: boolean;
+}
+
+/**
+ * Create a lazy logger with JSON output format
+ */
+export function createLazyLogger(
+  initialTags?: Record<string, unknown>
+): LazyLogger {
+  // Determine initial log level based on verbose flag
+  const initialLevel = Flag.OPENCODE_VERBOSE ? LEVEL_VERBOSE : LEVEL_DISABLED;
+
+  // Create base log-lazy instance
+  const baseLog = makeLog({ level: initialLevel });
+  const tags = { ...initialTags };
+
+  // Custom output functions that format as JSON
+  const outputError = createOutput('error', tags);
+  const outputWarn = createOutput('warn', tags);
+  const outputInfo = createOutput('info', tags);
+  const outputDebug = createOutput('debug', tags);
+  const outputVerbose = createOutput('verbose', tags);
+  const outputTrace = createOutput('trace', tags);
+
+  // Create wrapper that uses JSON output
+  const wrappedLog = function (fn: () => unknown): void {
+    baseLog.info(() => {
+      const result = fn();
+      outputInfo(result);
+      return ''; // Return empty string as the base logger just needs something
+    });
+  } as LazyLogger;
+
+  wrappedLog.error = (fn: () => unknown): void => {
+    baseLog.error(() => {
+      const result = fn();
+      outputError(result);
+      return '';
+    });
+  };
+
+  wrappedLog.warn = (fn: () => unknown): void => {
+    baseLog.warn(() => {
+      const result = fn();
+      outputWarn(result);
+      return '';
+    });
+  };
+
+  wrappedLog.info = (fn: () => unknown): void => {
+    baseLog.info(() => {
+      const result = fn();
+      outputInfo(result);
+      return '';
+    });
+  };
+
+  wrappedLog.debug = (fn: () => unknown): void => {
+    baseLog.debug(() => {
+      const result = fn();
+      outputDebug(result);
+      return '';
+    });
+  };
+
+  wrappedLog.verbose = (fn: () => unknown): void => {
+    baseLog.verbose(() => {
+      const result = fn();
+      outputVerbose(result);
+      return '';
+    });
+  };
+
+  wrappedLog.trace = (fn: () => unknown): void => {
+    baseLog.trace(() => {
+      const result = fn();
+      outputTrace(result);
+      return '';
+    });
+  };
+
+  // Level management
+  wrappedLog.enableLevel = (level: LogLevel): void => {
+    baseLog.enableLevel(level);
+  };
+
+  wrappedLog.disableLevel = (level: LogLevel): void => {
+    baseLog.disableLevel(level);
+  };
+
+  wrappedLog.setLevel = (level: LevelPreset | number): void => {
+    const numericLevel =
+      typeof level === 'string' ? LEVEL_PRESETS[level] : level;
+
+    // Reset all levels and enable the new one
+    Object.values([
+      'error',
+      'warn',
+      'info',
+      'debug',
+      'verbose',
+      'trace',
+    ]).forEach((l) => baseLog.disableLevel(l as LogLevel));
+
+    // Enable appropriate levels based on the numeric level
+    if (numericLevel & levels.error) baseLog.enableLevel('error');
+    if (numericLevel & levels.warn) baseLog.enableLevel('warn');
+    if (numericLevel & levels.info) baseLog.enableLevel('info');
+    if (numericLevel & levels.debug) baseLog.enableLevel('debug');
+    if (numericLevel & levels.verbose) baseLog.enableLevel('verbose');
+    if (numericLevel & levels.trace) baseLog.enableLevel('trace');
+  };
+
+  wrappedLog.getEnabledLevels = (): LogLevel[] => {
+    return baseLog.getEnabledLevels();
+  };
+
+  wrappedLog.shouldLog = (level: LogLevel): boolean => {
+    return baseLog.shouldLog(level);
+  };
+
+  // Tag support
+  wrappedLog.tag = (key: string, value: unknown): LazyLogger => {
+    tags[key] = value;
+    return wrappedLog;
+  };
+
+  wrappedLog.clone = (): LazyLogger => {
+    return createLazyLogger({ ...tags });
+  };
+
+  // Configuration
+  Object.defineProperty(wrappedLog, 'enabled', {
+    get: () => Flag.OPENCODE_VERBOSE,
+    enumerable: true,
+  });
+
+  return wrappedLog;
+}
+
+/**
+ * Default lazy logger instance
+ * Enabled only when --verbose flag or LINK_ASSISTANT_AGENT_VERBOSE env is set
+ */
+export const lazyLog = createLazyLogger({ service: 'agent' });
+
+/**
+ * Utility to update the global logger level at runtime
+ * Call this after Flag.setVerbose() to sync the logger state
+ */
+export function syncLoggerWithVerboseFlag(): void {
+  if (Flag.OPENCODE_VERBOSE) {
+    lazyLog.setLevel('verbose');
+  } else {
+    lazyLog.setLevel('disabled');
+  }
+}
+
+// Export level constants for external use
+export { levels, LEVEL_PRESETS };
+export type { LevelPreset };

package/src/util/log.ts

@@ -2,7 +2,20 @@ import path from 'path';
 import fs from 'fs/promises';
 import { Global } from '../global';
 import z from 'zod';
+import makeLog, { levels } from 'log-lazy';
+import { Flag } from '../flag/flag.ts';
 
+/**
+ * Logging module with JSON output and lazy evaluation support.
+ *
+ * Features:
+ * - JSON formatted output: All logs are wrapped in { log: { ... } } structure
+ * - Lazy evaluation: Use lazy() methods to defer expensive computations
+ * - Level control: Respects --verbose flag and log level settings
+ * - File logging: Writes to file when not in verbose/print mode
+ *
+ * The JSON format ensures all output is parsable, separating logs from regular output.
+ */
 export namespace Log {
   export const Level = z
     .enum(['DEBUG', 'INFO', 'WARN', 'ERROR'])
@@ -17,16 +30,41 @@ export namespace Log {
   };
 
   let level: Level = 'INFO';
+  let jsonOutput = false; // Whether to output JSON format (enabled in verbose mode)
 
   function shouldLog(input: Level): boolean {
     return levelPriority[input] >= levelPriority[level];
   }
 
+  /**
+   * Logger interface with support for both immediate and lazy logging.
+   *
+   * All logging methods accept either:
+   * - A message string/object/Error with optional extra data
+   * - A function that returns the data to log (lazy evaluation)
+   *
+   * Lazy logging: The function is only called if logging is enabled for that level,
+   * avoiding expensive computations when logs are disabled.
+   */
   export type Logger = {
-    debug(message?: any, extra?: Record<string, any>): void;
-    info(message?: any, extra?: Record<string, any>): void;
-    error(message?: any, extra?: Record<string, any>): void;
-    warn(message?: any, extra?: Record<string, any>): void;
+    // Unified logging - supports both immediate and lazy (callback) styles
+    debug(
+      message?: any | (() => { message?: string; [key: string]: any }),
+      extra?: Record<string, any>
+    ): void;
+    info(
+      message?: any | (() => { message?: string; [key: string]: any }),
+      extra?: Record<string, any>
+    ): void;
+    error(
+      message?: any | (() => { message?: string; [key: string]: any }),
+      extra?: Record<string, any>
+    ): void;
+    warn(
+      message?: any | (() => { message?: string; [key: string]: any }),
+      extra?: Record<string, any>
+    ): void;
+
     tag(key: string, value: string): Logger;
     clone(): Logger;
     time(
@@ -54,24 +92,47 @@ export namespace Log {
   }
   let write = (msg: any) => Bun.stderr.write(msg);
 
+  // Initialize log-lazy for controlling lazy log execution
+  let lazyLogInstance = makeLog({ level: 0 }); // Start disabled
+
   export async function init(options: Options) {
     if (options.level) level = options.level;
     cleanup(Global.Path.log);
-    if (options.print) return;
-    logpath = path.join(
-      Global.Path.log,
-      options.dev
-        ? 'dev.log'
-        : new Date().toISOString().split('.')[0].replace(/:/g, '') + '.log'
-    );
-    const logfile = Bun.file(logpath);
-    await fs.truncate(logpath).catch(() => {});
-    const writer = logfile.writer();
-    write = async (msg: any) => {
-      const num = writer.write(msg);
-      writer.flush();
-      return num;
-    };
+
+    // Always use JSON output format for logs
+    jsonOutput = true;
+
+    // Configure lazy logging level based on verbose flag
+    if (Flag.OPENCODE_VERBOSE || options.print) {
+      // Enable all levels for lazy logging when verbose
+      lazyLogInstance = makeLog({
+        level: levels.debug | levels.info | levels.warn | levels.error,
+      });
+    } else {
+      // Disable lazy logging when not verbose
+      lazyLogInstance = makeLog({ level: 0 });
+    }
+
+    if (options.print) {
+      // In print mode, output to stderr
+      // No file logging needed
+    } else {
+      // In normal mode, write to file
+      logpath = path.join(
+        Global.Path.log,
+        options.dev
+          ? 'dev.log'
+          : new Date().toISOString().split('.')[0].replace(/:/g, '') + '.log'
+      );
+      const logfile = Bun.file(logpath);
+      await fs.truncate(logpath).catch(() => {});
+      const writer = logfile.writer();
+      write = async (msg: any) => {
+        const num = writer.write(msg);
+        writer.flush();
+        return num;
+      };
+    }
   }
 
   async function cleanup(dir: string) {
@@ -97,6 +158,43 @@ export namespace Log {
       : result;
   }
 
+  /**
+   * Format log entry as JSON object wrapped in { log: { ... } }
+   */
+  function formatJson(
+    logLevel: Level,
+    message: any,
+    tags: Record<string, any>,
+    extra?: Record<string, any>
+  ): string {
+    const timestamp = new Date().toISOString();
+    const logEntry: Record<string, any> = {
+      level: logLevel.toLowerCase(),
+      timestamp,
+      ...tags,
+      ...extra,
+    };
+
+    if (message !== undefined && message !== null) {
+      if (typeof message === 'string') {
+        logEntry.message = message;
+      } else if (message instanceof Error) {
+        logEntry.message = message.message;
+        logEntry.error = {
+          name: message.name,
+          message: message.message,
+          stack: message.stack,
+        };
+      } else if (typeof message === 'object') {
+        Object.assign(logEntry, message);
+      } else {
+        logEntry.message = String(message);
+      }
+    }
+
+    return JSON.stringify({ log: logEntry });
+  }
+
   let last = Date.now();
   export function create(tags?: Record<string, any>) {
     tags = tags || {};
@@ -109,7 +207,8 @@ export namespace Log {
       }
     }
 
-    function build(message: any, extra?: Record<string, any>) {
+    // Legacy format for file logging (backward compatibility)
+    function buildLegacy(message: any, extra?: Record<string, any>) {
       const prefix = Object.entries({
         ...tags,
         ...extra,
@@ -131,27 +230,83 @@ export namespace Log {
           .join(' ') + '\n'
       );
     }
+
+    // Choose output format based on jsonOutput flag
+    function output(
+      logLevel: Level,
+      message: any,
+      extra?: Record<string, any>
+    ) {
+      if (jsonOutput) {
+        // Use our custom JSON formatting for { log: { ... } } format
+        write(formatJson(logLevel, message, tags || {}, extra) + '\n');
+      } else {
+        write(logLevel.padEnd(5) + ' ' + buildLegacy(message, extra));
+      }
+    }
+
     const result: Logger = {
       debug(message?: any, extra?: Record<string, any>) {
-        if (shouldLog('DEBUG')) {
-          write('DEBUG ' + build(message, extra));
+        if (!shouldLog('DEBUG')) return;
+
+        // Check if message is a function (lazy logging)
+        if (typeof message === 'function') {
+          lazyLogInstance.debug(() => {
+            const data = message();
+            const { message: msg, ...extraData } = data;
+            output('DEBUG', msg, extraData);
+            return '';
+          });
+        } else {
+          output('DEBUG', message, extra);
         }
       },
       info(message?: any, extra?: Record<string, any>) {
-        if (shouldLog('INFO')) {
-          write('INFO  ' + build(message, extra));
+        if (!shouldLog('INFO')) return;
+
+        // Check if message is a function (lazy logging)
+        if (typeof message === 'function') {
+          lazyLogInstance.info(() => {
+            const data = message();
+            const { message: msg, ...extraData } = data;
+            output('INFO', msg, extraData);
+            return '';
+          });
+        } else {
+          output('INFO', message, extra);
         }
       },
       error(message?: any, extra?: Record<string, any>) {
-        if (shouldLog('ERROR')) {
-          write('ERROR ' + build(message, extra));
+        if (!shouldLog('ERROR')) return;
+
+        // Check if message is a function (lazy logging)
+        if (typeof message === 'function') {
+          lazyLogInstance.error(() => {
+            const data = message();
+            const { message: msg, ...extraData } = data;
+            output('ERROR', msg, extraData);
+            return '';
+          });
+        } else {
+          output('ERROR', message, extra);
         }
       },
       warn(message?: any, extra?: Record<string, any>) {
-        if (shouldLog('WARN')) {
-          write('WARN  ' + build(message, extra));
+        if (!shouldLog('WARN')) return;
+
+        // Check if message is a function (lazy logging)
+        if (typeof message === 'function') {
+          lazyLogInstance.warn(() => {
+            const data = message();
+            const { message: msg, ...extraData } = data;
+            output('WARN', msg, extraData);
+            return '';
+          });
+        } else {
+          output('WARN', message, extra);
         }
       },
+
       tag(key: string, value: string) {
         if (tags) tags[key] = value;
         return result;
@@ -184,4 +339,26 @@ export namespace Log {
 
     return result;
   }
+
+  /**
+   * Check if JSON output mode is enabled
+   */
+  export function isJsonOutput(): boolean {
+    return jsonOutput;
+  }
+
+  /**
+   * Sync lazy logging with verbose flag at runtime
+   * Call after Flag.setVerbose() to update lazy logging state
+   */
+  export function syncWithVerboseFlag(): void {
+    if (Flag.OPENCODE_VERBOSE) {
+      jsonOutput = true;
+      lazyLogInstance = makeLog({
+        level: levels.debug | levels.info | levels.warn | levels.error,
+      });
+    } else {
+      lazyLogInstance = makeLog({ level: 0 });
+    }
+  }
 }