stelo 1.0.1

package/dist/logger.d.ts

@@ -0,0 +1,198 @@
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'silent';
+export interface LogEntry {
+    /** ISO timestamp */
+    timestamp: string;
+    /** Log level */
+    level: LogLevel;
+    /** Human-readable message */
+    message: string;
+    /** Module/component that created the log */
+    module?: string;
+    /** Arbitrary structured data */
+    data?: Record<string, unknown>;
+    /** Duration in ms (for performance logs) */
+    durationMs?: number;
+    /** Error details */
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+        code?: string;
+    };
+    /** Correlation/trace ID for linking related operations */
+    traceId?: string;
+    /** Span ID for nested operation tracking */
+    spanId?: string;
+    /** Parent span ID */
+    parentSpanId?: string;
+    /** Tags for filtering */
+    tags?: string[];
+}
+/** Transport — destination for log entries */
+export interface LogTransport {
+    /** Transport name */
+    name: string;
+    /** Minimum level this transport handles */
+    level: LogLevel;
+    /** Write a log entry */
+    write(entry: LogEntry): void;
+    /** Flush buffered entries (optional) */
+    flush?(): void | Promise<void>;
+    /** Teardown (optional) */
+    close?(): void | Promise<void>;
+}
+export interface LoggerOptions {
+    /** Global minimum log level (default: 'info') */
+    level?: LogLevel;
+    /** Default module name */
+    module?: string;
+    /** Enable performance timing helpers (default: true) */
+    timing?: boolean;
+    /** Transports to write to */
+    transports?: LogTransport[];
+    /** Emit log events to event bus (default: true) */
+    emitEvents?: boolean;
+    /** Default tags applied to all entries */
+    defaultTags?: string[];
+    /** Redact sensitive fields from data (default: true) */
+    redactSensitive?: boolean;
+    /** Fields to redact (default: password, secret, token, key, auth, cookie) */
+    redactFields?: string[];
+}
+/** Console transport with color-coded output */
+export declare class ConsoleTransport implements LogTransport {
+    name: string;
+    level: LogLevel;
+    private _json;
+    constructor(options?: {
+        level?: LogLevel;
+        json?: boolean;
+    });
+    write(entry: LogEntry): void;
+}
+/** In-memory transport for testing / inspection */
+export declare class MemoryTransport implements LogTransport {
+    name: string;
+    level: LogLevel;
+    entries: LogEntry[];
+    maxEntries: number;
+    constructor(options?: {
+        level?: LogLevel;
+        maxEntries?: number;
+    });
+    write(entry: LogEntry): void;
+    query(filter: Partial<Pick<LogEntry, 'level' | 'module' | 'traceId'>>): LogEntry[];
+    clear(): void;
+}
+/** Callback transport — route logs to a custom function */
+export declare class CallbackTransport implements LogTransport {
+    name: string;
+    level: LogLevel;
+    private _callback;
+    constructor(name: string, callback: (entry: LogEntry) => void, level?: LogLevel);
+    write(entry: LogEntry): void;
+}
+export declare const logger: {
+    configure(options: LoggerOptions): void;
+    /** Get current log level */
+    getLevel(): LogLevel;
+    /** Set log level at runtime */
+    setLevel(level: LogLevel): void;
+    /** Add a transport */
+    addTransport(transport: LogTransport): void;
+    /** Remove a transport by name */
+    removeTransport(name: string): void;
+    /** Get all transports */
+    getTransports(): LogTransport[];
+    trace(message: string, data?: Record<string, unknown>, extra?: Partial<LogEntry>): void;
+    debug(message: string, data?: Record<string, unknown>, extra?: Partial<LogEntry>): void;
+    info(message: string, data?: Record<string, unknown>, extra?: Partial<LogEntry>): void;
+    warn(message: string, data?: Record<string, unknown>, extra?: Partial<LogEntry>): void;
+    error(message: string, error?: Error | unknown, data?: Record<string, unknown>, extra?: Partial<LogEntry>): void;
+    fatal(message: string, error?: Error | unknown, data?: Record<string, unknown>): void;
+    /**
+     * Time a synchronous operation and log its duration.
+     *
+     * @example
+     * ```ts
+     * const result = logger.time('screen.capture', 'screen', () => screen.capture());
+     * ```
+     */
+    time<T>(operation: string, module: string, fn: () => T, data?: Record<string, unknown>): T;
+    /**
+     * Time an async operation and log its duration.
+     */
+    timeAsync<T>(operation: string, module: string, fn: () => Promise<T>, data?: Record<string, unknown>): Promise<T>;
+    /**
+     * Create a new trace context for correlating related operations.
+     *
+     * @example
+     * ```ts
+     * const trace = logger.startTrace('user-login-flow');
+     * logger.info('Starting login', {}, { traceId: trace.traceId });
+     * const span = trace.startSpan('validate-credentials');
+     * // ... do work ...
+     * span.end();
+     * trace.end();
+     * ```
+     */
+    startTrace(name: string): TraceContext;
+    /**
+     * Set a global trace context (all subsequent logs will include it).
+     */
+    setContext(traceId?: string, spanId?: string): void;
+    /** Clear the global trace context */
+    clearContext(): void;
+    /**
+     * Create a child logger with a fixed module name and optional default data.
+     *
+     * @example
+     * ```ts
+     * const log = logger.child('mouse');
+     * log.info('Moving to position', { x: 100, y: 200 });
+     * // → [INFO] [mouse] Moving to position { x: 100, y: 200 }
+     * ```
+     */
+    child(module: string, defaultData?: Record<string, unknown>): ChildLogger;
+    /** Flush all transports */
+    flush(): Promise<void>;
+    /** Close all transports */
+    close(): Promise<void>;
+    /** Reset logger to defaults */
+    reset(): void;
+};
+export declare class TraceContext {
+    readonly traceId: string;
+    readonly name: string;
+    private _startTime;
+    private _spans;
+    private _ended;
+    constructor(name: string);
+    startSpan(name: string): SpanContext;
+    end(): void;
+}
+export declare class SpanContext {
+    readonly spanId: string;
+    readonly name: string;
+    readonly traceId: string;
+    private _startTime;
+    private _ended;
+    constructor(name: string, traceId: string, parentSpanId?: string);
+    end(data?: Record<string, unknown>): void;
+    child(name: string): SpanContext;
+}
+export declare class ChildLogger {
+    private _module;
+    private _defaultData?;
+    constructor(_module: string, _defaultData?: Record<string, unknown> | undefined);
+    private _merge;
+    trace(message: string, data?: Record<string, unknown>): void;
+    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, error?: Error | unknown, data?: Record<string, unknown>): void;
+    fatal(message: string, error?: Error | unknown, data?: Record<string, unknown>): void;
+    time<T>(operation: string, fn: () => T, data?: Record<string, unknown>): T;
+    timeAsync<T>(operation: string, fn: () => Promise<T>, data?: Record<string, unknown>): Promise<T>;
+}
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../ts/logger.ts"],"names":[],"mappings":"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"}