first commit

docs/observability/monitor/logger/src/sink/console-sink.md

@@ -0,0 +1,89 @@
+# console-sink
+
+## Purpose
+
+`ConsoleSink` is the human-readable terminal output sink for `@suaveplan/logger`. It formats each `LogRecord` into a single coloured, prefixed line and dispatches it to the appropriate `console` method (`console.debug`, `console.info`, `console.warn`, or `console.error`) so that log output appears at the correct severity level in browser DevTools and Node.js terminals alike.
+
+The sink is intentionally synchronous — `write` returns `void`, not `Promise<void>` — because `console.*` is itself synchronous and any async wrapper would introduce misleading latency for a purely I/O-synchronous operation.
+
+## Features
+
+- ANSI colour codes per log level: cyan for `debug`, green for `info`, yellow for `warn`, red for `error`
+- Optional ISO timestamp prefix, dimmed for contrast in colour mode
+- Optional `#tag` rendering when the log record carries `ctx.__tags`
+- Optional compact JSON metadata block printed below the message line
+- All formatting options can be toggled at construction time or by mutating public fields after construction
+- Delegates to the correct `console` method for each log level, preserving browser DevTools severity grouping
+- No external dependencies beyond the `Sink` interface and `LogRecord` types
+
+## Usage: Basic Example
+
+```ts
+import { ConsoleSink } from "@suaveplan/logger/sink";
+
+const sink = new ConsoleSink(); // colors + timestamp enabled by default
+
+sink.write({
+  ts: new Date().toISOString(),
+  level: "info",
+  msg: "Server started",
+  ctx: {},
+});
+// Output: [2024-01-01T00:00:00.000Z] [INFO] Server started
+```
+
+## Usage: Advanced Example
+
+```ts
+import { ConsoleSink } from "@suaveplan/logger/sink";
+import { ConsoleLogger } from "@suaveplan/logger/console";
+
+// Plain text for CI environments (no ANSI codes in log files)
+const sink = new ConsoleSink({
+  colors: false,
+  timestamp: true,
+  includeMetadata: true,
+  includeTags: true,
+});
+
+const logger = new ConsoleLogger({ sink });
+logger.info("Request completed", {
+  __tags: ["http", "perf"],
+  duration: 42,
+  status: 200,
+});
+// Output:
+// [2024-01-01T00:00:00.000Z] [INFO] [#http #perf] Request completed
+// {
+//   "__tags": ["http", "perf"],
+//   "duration": 42,
+//   "status": 200
+// }
+```
+
+## API Reference
+
+### `class ConsoleSink implements Sink`
+
+**Constructor**: `new ConsoleSink(options?: ConsoleSinkOptions)`
+
+All options are also exposed as mutable public fields so they can be toggled after construction (e.g., to disable colours when a terminal is detected as non-interactive).
+
+| Option / Field | Type | Default | Description |
+|---|---|---|---|
+| `colors` | `boolean` | `true` | Wrap level and timestamp tokens in ANSI colour escapes |
+| `timestamp` | `boolean` | `true` | Prefix each line with the record's `ts` value |
+| `includeMetadata` | `boolean` | `false` | Append `ctx` as a formatted JSON block below the message |
+| `includeTags` | `boolean` | `true` | Inline `ctx.__tags` values as `#tag` tokens |
+
+**Methods**
+
+- `write(record: LogRecord): void` — Format and print the record synchronously. Never throws; `console.*` errors (which are vanishingly rare) surface as uncaught exceptions in the host environment.
+
+## Implementation Notes
+
+ANSI escape codes are defined as a small static map keyed by `LogLevel` plus `"reset"` and `"dim"` sentinels. The formatter builds a `parts: string[]` array and joins once at the end to minimise string concatenation allocations per record.
+
+The sink checks `console[method]` at call time rather than caching the reference at construction, which means it respects any `console` mocking that test frameworks install. This is deliberate — `ConsoleSink` is commonly used in test environments where `console.error` is wrapped to assert that no unexpected errors are logged.
+
+Colour mode does not auto-detect `process.stdout.isTTY`; that decision is left to the caller (typically the factory or the logger bootstrap) so the sink itself remains environment-agnostic and testable without process environment manipulation.