Add lambda-based delegated interceptor and writer interfaces (#19)

* Add delegated implementations for interceptor, writer, and formatter

Add three new classes that allow using lambdas instead of defining full
classes when implementing the core interfaces:

- DelegatedChirpInterceptor: Wraps (LogRecord) => LogRecord? function
- DelegatedChirpWriter: Wraps (LogRecord) => void function
- DelegatedConsoleMessageFormatter: Wraps (LogRecord, ConsoleMessageBuffer) => void function

Each class:
- Is const constructible for compile-time constants
- Supports the requiresCallerInfo parameter for stack trace capture
- Includes comprehensive documentation with usage examples
- Has full test coverage (59 tests total for the new classes)

This enables simpler inline usage patterns:

  // Before: Create a class
  class LevelFilter extends ChirpInterceptor {
    @OverRide
    LogRecord? intercept(LogRecord r) => r.level >= ChirpLogLevel.warning ? r : null;
  }

  // After: Use a lambda
  final filter = DelegatedChirpInterceptor(
    (r) => r.level >= ChirpLogLevel.warning ? r : null,
  );

* Add creation site capture for debugging delegated classes

All delegated classes now automatically capture the stack trace at
construction time, making them easier to identify during debugging:

  print(writer); // DelegatedChirpWriter(my_service.dart:42)

Features:
- creationSite property returns StackFrameInfo with file, line, method
- toString() includes the creation location (file:line format)
- captureCreationSite: false parameter to disable (saves memory/CPU)
- Consistent API across all three delegated classes

This addresses the debugging concern where DelegatedChirpWriter showed
a generic type name instead of meaningful context like named classes do.

* Simplify debugging API: expose StackTrace instead of StackFrameInfo

Change the public API to expose only standard Dart types:
- Rename creationSite to creationStackTrace (returns StackTrace?)
- Keep internal use of getCallerInfo for toString() formatting
- StackFrameInfo is no longer part of the public interface

This keeps the debugging functionality (toString shows file:line) while
not exposing internal types in the public API.

* Capture creation stack trace only in debug mode

Use a shared debugCaptureStackTrace() function that only captures
stack traces when assertions are enabled, avoiding the overhead
in release builds.

* Remove InterceptorFunction typedef

Use inline function type instead of typedef for cleaner API.

* Remove FormatterFunction typedef

Use inline function type instead of typedef for cleaner API.

* Remove WriterFunction typedef

Use inline function type instead of typedef for cleaner API.

* Simplify delegated class tests

Tests now only verify delegation behavior, not base class
functionality which is already tested elsewhere.

* Fix analyzer warning: remove redundant argument

* Fix formatting

* Override puro_sidekick_plugin to handle rate limits

* Enable verbose logging for puro sidekick plugin in CI

* Add puro config to root pubspec to avoid ls-versions call

* Update puro_sidekick_plugin to latest handle-rate-limits commit

Now includes disk caching for puro version responses to prevent
hitting GitHub API rate limits.

* Update puro_sidekick_plugin to latest commit

* Update puro_sidekick_plugin to latest commit

* Add PURO_LOG_LEVEL=4 for debugging CI puro issue

* Use official release

* Update cli deps

* dartfmt

* Remove debug logging

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: passsy

packages/chirp/lib/chirp.dart

@@ -32,6 +32,9 @@ export 'package:chirp/src/core/chirp_logger.dart' show ChirpLogger;
 export 'package:chirp/src/core/chirp_root.dart'
     show Chirp, ChirpInstanceLogger, ChirpLoggerConsoleWriterExt, LogRecordExt;
 export 'package:chirp/src/core/chirp_writer.dart' show ChirpWriter;
+export 'package:chirp/src/core/delegated_interceptor.dart'
+    show DelegatedChirpInterceptor;
+export 'package:chirp/src/core/delegated_writer.dart' show DelegatedChirpWriter;
 export 'package:chirp/src/core/format_option.dart' show FormatOptions;
 export 'package:chirp/src/core/log_level.dart' show ChirpLogLevel;
 export 'package:chirp/src/core/log_record.dart' show LogRecord;
@@ -60,5 +63,7 @@ export 'package:chirp/src/writers/console_writer.dart'
         PrintConsoleWriter,
         splitIntoChunks,
         stripAnsiCodes;
+export 'package:chirp/src/writers/delegated_formatter.dart'
+    show DelegatedConsoleMessageFormatter;
 export 'package:chirp/src/writers/developer_log_console_writer.dart'
     show DeveloperLogConsoleWriter;

packages/chirp/lib/src/core/delegated_interceptor.dart

@@ -0,0 +1,94 @@
+import 'package:chirp/src/core/chirp_interceptor.dart';
+import 'package:chirp/src/core/log_record.dart';
+import 'package:chirp/src/utils/stack_trace_util.dart';
+
+/// {@template chirp.DelegatedChirpInterceptor}
+/// A [ChirpInterceptor] implementation that delegates to a function.
+///
+/// This allows creating interceptors inline without defining a class:
+///
+/// ```dart
+/// // Filter logs by level
+/// final levelFilter = DelegatedChirpInterceptor(
+///   (record) => record.level >= ChirpLogLevel.warning ? record : null,
+/// );
+///
+/// // Redact sensitive data
+/// final redactor = DelegatedChirpInterceptor((record) {
+///   final message = record.message.toString();
+///   if (message.contains('password')) {
+///     return record.copyWith(
+///       message: message.replaceAll(RegExp(r'password=\S+'), 'password=***'),
+///     );
+///   }
+///   return record;
+/// });
+///
+/// // Add context from zone
+/// final contextEnricher = DelegatedChirpInterceptor((record) {
+///   final requestId = Zone.current['requestId'];
+///   if (requestId != null) {
+///     return record.copyWith(data: {...record.data, 'requestId': requestId});
+///   }
+///   return record;
+/// });
+/// ```
+///
+/// ## Debugging
+///
+/// By default, the creation site is captured for debugging. This helps
+/// identify which delegated interceptor is which when inspecting in a debugger:
+///
+/// ```dart
+/// print(interceptor); // DelegatedChirpInterceptor(my_service.dart:42)
+/// ```
+///
+/// For more complex interceptors with state or configuration, consider
+/// extending [ChirpInterceptor] directly.
+/// {@endtemplate}
+class DelegatedChirpInterceptor extends ChirpInterceptor {
+  /// The function that intercepts log records.
+  final LogRecord? Function(LogRecord record) _intercept;
+
+  final bool _requiresCallerInfo;
+
+  /// Stack trace captured at construction time, for debugging.
+  ///
+  /// Only captured when assertions are enabled (debug mode).
+  final StackTrace? creationStackTrace;
+
+  /// {@macro chirp.DelegatedChirpInterceptor}
+  ///
+  /// The [intercept] function receives a [LogRecord] and should return:
+  /// - The record unchanged to pass through
+  /// - A modified copy (via [LogRecord.copyWith]) to transform
+  /// - `null` to reject the record and prevent it from being written
+  ///
+  /// Set [requiresCallerInfo] to `true` if your interceptor needs access to
+  /// caller information (file, line, class, method). This triggers stack trace
+  /// capture which has a performance cost.
+  DelegatedChirpInterceptor(
+    LogRecord? Function(LogRecord record) intercept, {
+    bool requiresCallerInfo = false,
+  })  : _intercept = intercept,
+        _requiresCallerInfo = requiresCallerInfo,
+        creationStackTrace = debugCaptureStackTrace();
+
+  @override
+  bool get requiresCallerInfo => _requiresCallerInfo;
+
+  @override
+  LogRecord? intercept(LogRecord record) => _intercept(record);
+
+  @override
+  String toString() {
+    final stackTrace = creationStackTrace;
+    if (stackTrace != null) {
+      final info = getCallerInfo(stackTrace);
+      if (info != null) {
+        return 'DelegatedChirpInterceptor(${info.callerLocation})';
+      }
+    }
+    return 'DelegatedChirpInterceptor';
+  }
+}

packages/chirp/lib/src/core/delegated_writer.dart

@@ -0,0 +1,109 @@
+import 'package:chirp/src/core/chirp_writer.dart';
+import 'package:chirp/src/core/log_record.dart';
+import 'package:chirp/src/utils/stack_trace_util.dart';
+
+/// {@template chirp.DelegatedChirpWriter}
+/// A [ChirpWriter] implementation that delegates to a function.
+///
+/// This allows creating writers inline without defining a class:
+///
+/// ```dart
+/// // Simple writer that collects logs
+/// final logs = <LogRecord>[];
+/// final collector = DelegatedChirpWriter((record) => logs.add(record));
+///
+/// // Writer that sends to external service
+/// final analyticsWriter = DelegatedChirpWriter((record) {
+///   if (record.level >= ChirpLogLevel.error) {
+///     analytics.logError(
+///       message: record.message.toString(),
+///       error: record.error,
+///       stackTrace: record.stackTrace,
+///     );
+///   }
+/// });
+///
+/// // Writer that appends to a file
+/// final fileWriter = DelegatedChirpWriter((record) {
+///   final line = '${record.timestamp.toIso8601String()} '
+///       '[${record.level.name}] ${record.message}\n';
+///   logFile.writeAsStringSync(line, mode: FileMode.append);
+/// });
+///
+/// // Use with a logger
+/// final logger = ChirpLogger(name: 'MyLogger')
+///   .addWriter(collector)
+///   .addWriter(analyticsWriter);
+/// ```
+///
+/// ## Interceptors and Filtering
+///
+/// [DelegatedChirpWriter] inherits interceptor and minimum log level support
+/// from [ChirpWriter]:
+///
+/// ```dart
+/// final writer = DelegatedChirpWriter((record) => print(record.message))
+///   .setMinLogLevel(ChirpLogLevel.warning)
+///   .addInterceptor(myInterceptor);
+/// ```
+///
+/// ## Debugging
+///
+/// By default, the creation site is captured for debugging. This helps
+/// identify which delegated writer is which when inspecting in a debugger:
+///
+/// ```dart
+/// print(writer); // DelegatedChirpWriter(my_service.dart:42)
+/// ```
+///
+/// For more complex writers with state, configuration, or cleanup logic,
+/// consider extending [ChirpWriter] directly.
+/// {@endtemplate}
+class DelegatedChirpWriter extends ChirpWriter {
+  /// The function that writes log records.
+  final void Function(LogRecord record) _write;
+
+  final bool _requiresCallerInfo;
+
+  /// Stack trace captured at construction time, for debugging.
+  ///
+  /// Only captured when assertions are enabled (debug mode).
+  final StackTrace? creationStackTrace;
+
+  /// {@macro chirp.DelegatedChirpWriter}
+  ///
+  /// The [write] function receives a [LogRecord] and should output it to the
+  /// desired destination (console, file, network, monitoring service, etc.).
+  ///
+  /// Set [requiresCallerInfo] to `true` if your writer needs access to caller
+  /// information (file, line, class, method). This triggers stack trace
+  /// capture which has a performance cost.
+  ///
+  /// **Performance note**: The [write] function is called synchronously for
+  /// each log event. For slow operations (network, disk), consider buffering
+  /// or handling async operations within your function.
+  DelegatedChirpWriter(
+    void Function(LogRecord record) write, {
+    bool requiresCallerInfo = false,
+  })  : _write = write,
+        _requiresCallerInfo = requiresCallerInfo,
+        creationStackTrace = debugCaptureStackTrace();
+
+  @override
+  bool get requiresCallerInfo => _requiresCallerInfo;
+
+  @override
+  void write(LogRecord record) => _write(record);
+
+  @override
+  String toString() {
+    final stackTrace = creationStackTrace;
+    if (stackTrace != null) {
+      final info = getCallerInfo(stackTrace);
+      if (info != null) {
+        return 'DelegatedChirpWriter(${info.callerLocation})';
+      }
+    }
+    return 'DelegatedChirpWriter';
+  }
+}

packages/chirp/lib/src/utils/stack_trace_util.dart

@@ -1,3 +1,19 @@
+/// Captures stack trace only when assertions are enabled (debug mode).
+///
+/// Returns `null` in release mode to avoid the performance overhead of
+/// capturing stack traces in production.
+///
+/// This is useful for debugging delegated implementations where the
+/// creation site helps identify which instance is which.
+StackTrace? debugCaptureStackTrace() {
+  StackTrace? result;
+  assert(() {
+    result = StackTrace.current;
+    return true;
+  }());
+  return result;
+}
+
 /// Information extracted from a stack frame
 class StackFrameInfo {
   /// The raw caller method (e.g., `UserService.processUser.<anonymous closure>`)

packages/chirp/lib/src/writers/delegated_formatter.dart

@@ -0,0 +1,108 @@
+import 'package:chirp/src/core/log_record.dart';
+import 'package:chirp/src/utils/stack_trace_util.dart';
+import 'package:chirp/src/writers/console_writer.dart';
+
+/// {@template chirp.DelegatedConsoleMessageFormatter}
+/// A [ConsoleMessageFormatter] implementation that delegates to a function.
+///
+/// This allows creating formatters inline without defining a class:
+///
+/// ```dart
+/// // Simple formatter
+/// final simpleFormatter = DelegatedConsoleMessageFormatter((record, buffer) {
+///   buffer.write('[${record.level.name}] ${record.message}');
+/// });
+///
+/// // Formatter with colors
+/// final colorFormatter = DelegatedConsoleMessageFormatter((record, buffer) {
+///   buffer.pushStyle(foreground: Ansi256.cyan_6);
+///   buffer.write(record.timestamp.toIso8601String());
+///   buffer.popStyle();
+///   buffer.write(' ');
+///   buffer.pushStyle(foreground: Ansi256.yellow_3, bold: true);
+///   buffer.write('[${record.level.name.toUpperCase()}]');
+///   buffer.popStyle();
+///   buffer.write(' ${record.message}');
+/// });
+///
+/// // Formatter that includes structured data
+/// final dataFormatter = DelegatedConsoleMessageFormatter((record, buffer) {
+///   buffer.write('${record.message}');
+///   if (record.data.isNotEmpty) {
+///     buffer.write(' | ');
+///     buffer.pushStyle(dim: true);
+///     buffer.write(record.data.entries
+///         .map((e) => '${e.key}=${e.value}')
+///         .join(', '));
+///     buffer.popStyle();
+///   }
+/// });
+///
+/// // Use with PrintConsoleWriter
+/// final writer = PrintConsoleWriter(formatter: simpleFormatter);
+/// ```
+///
+/// ## Using the Buffer
+///
+/// The [ConsoleMessageBuffer] provides methods for building styled output:
+/// - [ConsoleMessageBuffer.write] - Write text with optional inline colors
+/// - [ConsoleMessageBuffer.pushStyle] / [ConsoleMessageBuffer.popStyle] - Manage nested styles
+/// - [ConsoleMessageBuffer.capabilities] - Query terminal capabilities
+///
+/// ## Debugging
+///
+/// By default, the creation site is captured for debugging. This helps
+/// identify which delegated formatter is which when inspecting in a debugger:
+///
+/// ```dart
+/// print(formatter); // DelegatedConsoleMessageFormatter(my_service.dart:42)
+/// ```
+///
+/// For more complex formatters with configuration or state, consider extending
+/// [ConsoleMessageFormatter] directly.
+/// {@endtemplate}
+class DelegatedConsoleMessageFormatter extends ConsoleMessageFormatter {
+  /// The function that formats log records.
+  final void Function(LogRecord record, ConsoleMessageBuffer buffer) _format;
+
+  final bool _requiresCallerInfo;
+
+  /// Stack trace captured at construction time, for debugging.
+  ///
+  /// Only captured when assertions are enabled (debug mode).
+  final StackTrace? creationStackTrace;
+
+  /// {@macro chirp.DelegatedConsoleMessageFormatter}
+  ///
+  /// The [format] function receives a [LogRecord] and a [ConsoleMessageBuffer].
+  /// Write the formatted output to the buffer using its methods.
+  ///
+  /// Set [requiresCallerInfo] to `true` if your formatter needs access to
+  /// caller information (file, line, class, method). This triggers stack trace
+  /// capture which has a performance cost.
+  DelegatedConsoleMessageFormatter(
+    void Function(LogRecord record, ConsoleMessageBuffer buffer) format, {
+    bool requiresCallerInfo = false,
+  })  : _format = format,
+        _requiresCallerInfo = requiresCallerInfo,
+        creationStackTrace = debugCaptureStackTrace();
+
+  @override
+  bool get requiresCallerInfo => _requiresCallerInfo;
+
+  @override
+  void format(LogRecord record, ConsoleMessageBuffer buffer) =>
+      _format(record, buffer);
+
+  @override
+  String toString() {
+    final stackTrace = creationStackTrace;
+    if (stackTrace != null) {
+      final info = getCallerInfo(stackTrace);
+      if (info != null) {
+        return 'DelegatedConsoleMessageFormatter(${info.callerLocation})';
+      }
+    }
+    return 'DelegatedConsoleMessageFormatter';
+  }
+}

packages/chirp/test/delegated_formatter_test.dart

@@ -0,0 +1,44 @@
+import 'package:chirp/chirp.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('DelegatedConsoleMessageFormatter', () {
+    test('calls the provided function with record and buffer', () {
+      LogRecord? receivedRecord;
+      ConsoleMessageBuffer? receivedBuffer;
+
+      final formatter = DelegatedConsoleMessageFormatter((record, buffer) {
+        receivedRecord = record;
+        receivedBuffer = buffer;
+      });
+
+      final record = LogRecord(message: 'Test', timestamp: DateTime.now());
+      final buffer = ConsoleMessageBuffer(
+        capabilities: const TerminalCapabilities(),
+      );
+
+      formatter.format(record, buffer);
+
+      expect(receivedRecord, same(record));
+      expect(receivedBuffer, same(buffer));
+    });
+
+    test('requiresCallerInfo defaults to false', () {
+      final formatter = DelegatedConsoleMessageFormatter((record, buffer) {});
+      expect(formatter.requiresCallerInfo, isFalse);
+    });
+
+    test('requiresCallerInfo can be set to true', () {
+      final formatter = DelegatedConsoleMessageFormatter(
+        (record, buffer) {},
+        requiresCallerInfo: true,
+      );
+      expect(formatter.requiresCallerInfo, isTrue);
+    });
+
+    test('toString includes creation site in debug mode', () {
+      final formatter = DelegatedConsoleMessageFormatter((record, buffer) {});
+      expect(formatter.toString(), contains('delegated_formatter_test'));
+    });
+  });
+}