@provide-io/telemetry 0.2.2

package/src/pretty.ts

@@ -0,0 +1,93 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Pretty ANSI log renderer for CLI / terminal output.
+ *
+ * Mirrors Python provide.telemetry.logger.pretty.PrettyRenderer.
+ * Same color scheme, same layout: timestamp [level] event key=value pairs.
+ */
+
+const RESET = '\x1b[0m';
+const DIM = '\x1b[2m';
+
+const LEVEL_COLORS: Record<string, string> = {
+  fatal: '\x1b[31;1m', // bold red
+  error: '\x1b[31m', // red
+  warn: '\x1b[33m', // yellow
+  info: '\x1b[32m', // green
+  debug: '\x1b[34m', // blue
+  trace: '\x1b[36m', // cyan
+};
+
+// pino level number → name
+const LEVEL_NAMES: Record<number, string> = {
+  10: 'trace',
+  20: 'debug',
+  30: 'info',
+  40: 'warn',
+  50: 'error',
+  60: 'fatal',
+};
+
+const LEVEL_PAD = 6; // "fatal" = 5, pad to 6
+
+// Keys to exclude from the key=value tail (already rendered or internal)
+const SKIP_KEYS = new Set(['level', 'time', 'msg', 'event', 'v', 'pid', 'hostname']);
+
+/**
+ * Detect whether stdout supports color.
+ * Returns false in browsers, CI without FORCE_COLOR, or piped output.
+ */
+export function supportsColor(): boolean {
+  // Stryker disable next-line ConditionalExpression,StringLiteral,BooleanLiteral -- browser-only guard
+  /* v8 ignore next -- browser-only path, untestable in Node */
+  if (typeof process === 'undefined') return false;
+  if (process.env['FORCE_COLOR'] === '1' || process.env['FORCE_COLOR'] === 'true') return true;
+  if (process.env['NO_COLOR'] !== undefined) return false;
+  // Stryker disable next-line OptionalChaining -- process.stdout is always defined in Node/test env
+  if (typeof process.stdout?.isTTY === 'boolean') return process.stdout.isTTY;
+  return false;
+}
+
+/**
+ * Format a pino log object as a pretty ANSI string.
+ *
+ * Layout: `timestamp [level   ] event  key=value key=value`
+ */
+export function formatPretty(obj: Record<string, unknown>, colors: boolean): string {
+  const parts: string[] = [];
+
+  // 1. Timestamp
+  const time = obj['time'];
+  if (time !== undefined) {
+    const ts = typeof time === 'number' ? new Date(time).toISOString() : String(time);
+    parts.push(colors ? DIM + ts + RESET : ts);
+  }
+
+  // 2. Level
+  const levelNum = obj['level'] as number;
+  const levelName = LEVEL_NAMES[levelNum] ?? 'log';
+  const padded = levelName.padEnd(LEVEL_PAD);
+  if (colors) {
+    const c = LEVEL_COLORS[levelName] ?? '';
+    parts.push('[' + c + padded + RESET + ']');
+  } else {
+    parts.push('[' + padded + ']');
+  }
+
+  // 3. Event / message
+  const event = obj['event'] ?? obj['msg'] ?? '';
+  parts.push(String(event));
+
+  // 4. Remaining key=value pairs (sorted, skip internal keys)
+  const keys = Object.keys(obj)
+    .filter((k) => !SKIP_KEYS.has(k))
+    .sort();
+  for (const k of keys) {
+    const v = JSON.stringify(obj[k]);
+    parts.push(colors ? DIM + k + RESET + '=' + v : k + '=' + v);
+  }
+
+  return parts.join(' ');
+}

package/src/propagation.ts

@@ -0,0 +1,222 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * W3C trace context propagation helpers.
+ * Mirrors Python provide.telemetry.propagation.
+ */
+
+export interface PropagationContext {
+  traceparent?: string;
+  tracestate?: string;
+  baggage?: string;
+  traceId?: string;
+  spanId?: string;
+}
+
+/** Maximum length (in characters) for traceparent or tracestate header values. */
+export const MAX_HEADER_LENGTH = 512;
+/** Maximum number of comma-separated key=value pairs in tracestate. */
+export const MAX_TRACESTATE_PAIRS = 32;
+/** Maximum length (in characters) for the baggage header value. */
+export const MAX_BAGGAGE_LENGTH = 8192;
+
+// ── AsyncLocalStorage type (Node.js / Cloudflare Workers) ─────────────────────
+type PropagationStore = {
+  active: PropagationContext;
+  stack: PropagationContext[];
+  otelCtxStack: unknown[];
+};
+
+export type PropagationALS = {
+  getStore(): PropagationStore | undefined;
+  run<T>(store: PropagationStore, fn: () => T): T;
+  enterWith(store: PropagationStore): void;
+};
+
+// ── AsyncLocalStorage (Node.js / Cloudflare Workers) ──────────────────────────
+let _als: PropagationALS | null = null;
+let _AlsConstructor: (new () => PropagationALS) | null = null;
+// Stryker disable BlockStatement: module-level try/catch runs once at import time — cannot be tested by unit tests
+try {
+  // Dynamic require so the import doesn't break browser bundles.
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const als = require('node:async_hooks') as {
+    AsyncLocalStorage: new () => PropagationALS;
+  };
+  _AlsConstructor = als.AsyncLocalStorage;
+  _als = new _AlsConstructor();
+} catch {
+  // Not available — fall back to module-level store below.
+}
+// Stryker restore BlockStatement
+
+// ── Fallback: module-level store (browser / single-thread) ────────────────────
+// Stryker disable next-line ArrayDeclaration: initial empty arrays are overwritten by _resetPropagationForTests in every test beforeEach
+let _fallbackStore: PropagationStore = { active: {}, stack: [], otelCtxStack: [] };
+
+function _getStore(): PropagationStore {
+  if (_als) {
+    return _als.getStore() ?? _fallbackStore;
+  }
+  return _fallbackStore;
+}
+
+// Stryker disable ConditionalExpression,BlockStatement,ArrayDeclaration: _ensureStore ALS-to-fallback clone path — tested by "clones fallback stack" test; remaining mutants are equivalent because _resetPropagationForTests empties both stores
+function _ensureStore(): PropagationStore {
+  if (_als) {
+    const store = _als.getStore();
+    if (store) return store;
+    const next: PropagationStore = {
+      active: { ..._fallbackStore.active },
+      stack: _fallbackStore.stack.map((entry) => ({ ...entry })),
+      otelCtxStack: [..._fallbackStore.otelCtxStack],
+    };
+    _als.enterWith(next);
+    return next;
+  }
+  return _fallbackStore;
+}
+// Stryker restore ConditionalExpression,BlockStatement,ArrayDeclaration
+
+function _parseTraceparent(value: string): { traceId?: string; spanId?: string } {
+  const parts = value.split('-');
+  if (parts.length !== 4) return {};
+  const [version, traceId, spanId] = parts;
+  if (version.length !== 2 || traceId.length !== 32 || spanId.length !== 16) return {};
+  if (version.toLowerCase() === 'ff') return {};
+  if (traceId === '0'.repeat(32) || spanId === '0'.repeat(16)) return {};
+  // Validate that all fields are valid hex strings.
+  if (
+    !/^[0-9a-fA-F]+$/.test(version) ||
+    !/^[0-9a-fA-F]+$/.test(traceId) ||
+    !/^[0-9a-fA-F]+$/.test(spanId)
+  ) {
+    return {};
+  }
+  return { traceId: traceId.toLowerCase(), spanId: spanId.toLowerCase() };
+}
+
+/**
+ * Extract W3C trace context from an HTTP headers object.
+ */
+export function extractW3cContext(headers: Record<string, string>): PropagationContext {
+  const lower: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) lower[k.toLowerCase()] = v;
+
+  let rawTraceparent: string | undefined = lower['traceparent'];
+  let tracestate: string | undefined = lower['tracestate'];
+  let baggage: string | undefined = lower['baggage'];
+
+  // Stryker disable next-line ConditionalExpression,EqualityOperator,BlockStatement: size guard — >= vs > on boundary is equivalent (512-char valid traceparent doesn't exist)
+  if (rawTraceparent !== undefined && rawTraceparent.length > MAX_HEADER_LENGTH) {
+    rawTraceparent = undefined;
+  }
+  if (tracestate !== undefined) {
+    if (tracestate.length > MAX_HEADER_LENGTH) {
+      tracestate = undefined;
+    } else if (tracestate.split(',').length > MAX_TRACESTATE_PAIRS) {
+      tracestate = undefined;
+    }
+  }
+  if (baggage !== undefined && baggage.length > MAX_BAGGAGE_LENGTH) {
+    baggage = undefined;
+  }
+
+  const { traceId, spanId } = rawTraceparent ? _parseTraceparent(rawTraceparent) : {};
+  // Stryker disable next-line LogicalOperator: traceId and spanId are always both defined or both undefined (from _parseTraceparent) — && and || give identical results
+  const traceparent = traceId && spanId ? rawTraceparent : undefined;
+
+  return {
+    ...(traceparent !== undefined && { traceparent }),
+    ...(tracestate !== undefined && { tracestate }),
+    ...(baggage !== undefined && { baggage }),
+    ...(traceId !== undefined && { traceId }),
+    ...(spanId !== undefined && { spanId }),
+  };
+}
+
+/**
+ * Push ctx onto the propagation stack, making it the active context.
+ * When traceparent is present and OTel API is available, extracts an OTel
+ * context so that child spans created via withTrace() inherit the parent.
+ */
+export function bindPropagationContext(ctx: PropagationContext): void {
+  const store = _ensureStore();
+  store.stack.push({ ...store.active });
+  store.active = { ...store.active, ...ctx };
+
+  // Wire into OTel context chain when traceparent is present.
+  if (ctx.traceparent) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const otelApi = require('@opentelemetry/api') as {
+        propagation: { extract: (ctx: unknown, carrier: Record<string, string>) => unknown };
+        context: { active: () => unknown };
+      };
+      /* Stryker disable all: OTel context wiring — carrier key, extract call, catch/else sentinels are equivalent when OTel SDK behavior varies */
+      const carrier: Record<string, string> = { traceparent: ctx.traceparent };
+      if (ctx.tracestate) carrier['tracestate'] = ctx.tracestate;
+      const extracted = otelApi.propagation.extract(otelApi.context.active(), carrier);
+      store.otelCtxStack.push(extracted);
+    } catch {
+      store.otelCtxStack.push(undefined);
+    }
+  } else {
+    store.otelCtxStack.push(undefined);
+  }
+  /* Stryker restore all */
+}
+
+/**
+ * Pop the last saved context, restoring the previous state.
+ */
+// Stryker disable BlockStatement
+export function clearPropagationContext(): void {
+  const store = _ensureStore();
+  // Stryker disable next-line ConditionalExpression,EqualityOperator
+  if (store.stack.length > 0) {
+    // Stryker enable BlockStatement
+    const restored = store.stack.pop();
+    /* v8 ignore next */
+    store.active = restored ?? {};
+  } else {
+    // Stryker disable BlockStatement: empty else body is equivalent — active is always {} here because pop() restores prior state
+    store.active = {};
+  }
+  store.otelCtxStack.pop();
+}
+// Stryker enable BlockStatement
+
+/** Return the currently active propagation context. */
+export function getActivePropagationContext(): PropagationContext {
+  return { ..._getStore().active };
+}
+
+/** Return the top of the OTel context stack, or undefined if empty/no OTel wiring. */
+export function getActiveOtelContext(): unknown | undefined {
+  const stack = _getStore().otelCtxStack;
+  // Stryker disable next-line ConditionalExpression: empty stack returns undefined; removing returns undefined from array[-1] which is also undefined
+  if (stack.length === 0) return undefined;
+  return stack[stack.length - 1];
+}
+
+export function _resetPropagationForTests(): void {
+  // Recreate the ALS instance so no enterWith-seeded store leaks between tests.
+  // The null branch is only reachable in environments without node:async_hooks (e.g. browsers).
+  /* v8 ignore next */
+  _als = _AlsConstructor ? new _AlsConstructor() : null;
+  _fallbackStore = { active: {}, stack: [], otelCtxStack: [] };
+}
+
+/** Disable AsyncLocalStorage for testing the module-level fallback path. */
+export function _disablePropagationALSForTest(): PropagationALS | null {
+  const prev = _als;
+  _als = null;
+  return prev;
+}
+
+/** Re-enable AsyncLocalStorage after testing (pass value from _disable call). */
+export function _restorePropagationALSForTest(saved: PropagationALS | null): void {
+  _als = saved;
+}

package/src/react.ts

@@ -0,0 +1,98 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * React 18+ helpers for @provide-io/telemetry.
+ *
+ * Import from '@provide-io/telemetry/react'.
+ * React must be installed as a peer dependency (>=18).
+ */
+
+import { Component, useEffect } from 'react';
+import type { ErrorInfo, ReactNode } from 'react';
+import { bindContext, unbindContext } from './context';
+import { getLogger } from './logger';
+
+// ── useTelemetryContext ──────────────────────────────────────────────────────
+
+/**
+ * Bind key/value pairs into telemetry context for the lifetime of the component.
+ * Cleans up on unmount. Re-runs when values change (content-compared, not by reference).
+ */
+export function useTelemetryContext(values: Record<string, unknown>): void {
+  // Content-stable dep: avoids re-running when the object reference changes but values are equal.
+  // Note: key insertion order affects JSON.stringify — { b:1, a:2 } !== { a:2, b:1 }.
+  // Callers that build `values` via dynamic spread should keep key order consistent.
+  const serialized = JSON.stringify(values);
+
+  useEffect(() => {
+    const keys = Object.keys(values);
+    bindContext(values);
+    return () => {
+      unbindContext(...keys);
+    };
+    // `serialized` is the intentional dep — avoids re-running for referentially-new-but-equal
+    // objects. `values` is deliberately omitted; the serialized string is the stable proxy.
+  }, [serialized]);
+}
+
+// ── TelemetryErrorBoundary ───────────────────────────────────────────────────
+
+interface TelemetryErrorBoundaryProps {
+  children: ReactNode;
+  fallback: ReactNode | ((error: Error, reset: () => void) => ReactNode);
+  onError?: (error: Error, info: ErrorInfo) => void;
+}
+
+interface TelemetryErrorBoundaryState {
+  error: Error | null;
+}
+
+/**
+ * React error boundary that logs caught render errors via getLogger and renders
+ * a fallback UI. Accepts a static ReactNode or a render-prop that receives the
+ * caught error and a reset callback.
+ *
+ * Auto-logs to getLogger('react.error_boundary') on every catch. Call onError
+ * for any additional handling (alerting, Sentry, etc.).
+ */
+export class TelemetryErrorBoundary extends Component<
+  TelemetryErrorBoundaryProps,
+  TelemetryErrorBoundaryState
+> {
+  constructor(props: TelemetryErrorBoundaryProps) {
+    super(props);
+    this.state = { error: null };
+    this.reset = this.reset.bind(this);
+  }
+
+  static getDerivedStateFromError(error: Error): TelemetryErrorBoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    getLogger('react.error_boundary').error({
+      event: 'react_error_caught',
+      error_message: error.message,
+      error_stack: error.stack ?? '',
+      component_stack: info.componentStack ?? '',
+    });
+    this.props.onError?.(error, info);
+  }
+
+  reset(): void {
+    this.setState({ error: null });
+  }
+
+  render(): ReactNode {
+    const { error } = this.state;
+    if (error !== null) {
+      const { fallback } = this.props;
+      if (typeof fallback === 'function') {
+        return fallback(error, this.reset);
+      }
+      return fallback;
+    }
+    return this.props.children;
+  }
+}

package/src/receipts.ts

@@ -0,0 +1,97 @@
+// SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Cryptographic redaction receipts — strippable governance module.
+ *
+ * Registers a receipt hook on the PII engine when enabled.
+ * If this file is deleted, the PII engine runs unchanged (hook stays null).
+ */
+
+import { createHash, createHmac, randomUUID } from 'crypto';
+import { setReceiptHook } from './pii';
+
+/** An immutable audit record for a single PII redaction event. */
+export interface RedactionReceipt {
+  receiptId: string;
+  timestamp: string;
+  serviceName: string;
+  fieldPath: string;
+  action: string;
+  originalHash: string;
+  hmac: string;
+}
+
+let _enabled = false;
+let _signingKey: string | undefined;
+let _serviceName = 'unknown';
+let _testMode = false;
+// Stryker disable next-line ArrayDeclaration
+const _testReceipts: RedactionReceipt[] = [];
+
+/** Options for enabling receipt generation. */
+export interface EnableReceiptsOptions {
+  enabled: boolean;
+  signingKey?: string;
+  serviceName?: string;
+}
+
+/**
+ * Enable or disable receipt generation.
+ * When enabled, a hook is registered on the PII engine to capture redaction events.
+ */
+export function enableReceipts(options: EnableReceiptsOptions): void {
+  _enabled = options.enabled;
+  _signingKey = options.signingKey;
+  _serviceName = options.serviceName ?? 'unknown';
+
+  if (_enabled) {
+    setReceiptHook(_onRedaction);
+  } else {
+    setReceiptHook(null);
+  }
+}
+
+function _onRedaction(fieldPath: string, action: string, originalValue: unknown): void {
+  const receiptId = randomUUID();
+  const timestamp = new Date().toISOString();
+  const originalHash = createHash('sha256').update(String(originalValue)).digest('hex');
+
+  let hmacValue = '';
+  if (_signingKey) {
+    const payload = `${receiptId}|${timestamp}|${fieldPath}|${action}|${originalHash}`;
+    hmacValue = createHmac('sha256', _signingKey).update(payload).digest('hex');
+  }
+
+  const receipt: RedactionReceipt = {
+    receiptId,
+    timestamp,
+    serviceName: _serviceName,
+    fieldPath,
+    action,
+    originalHash,
+    hmac: hmacValue,
+  };
+
+  /* v8 ignore next 3: production-mode receipt emission — not exercised in test mode */
+  if (_testMode) {
+    _testReceipts.push(receipt);
+  }
+  // In production mode, receipts would be emitted via the logger.
+  // (No-op here when not in test mode — callers integrate with their logging pipeline.)
+}
+
+/** Returns receipts collected during test mode. */
+export function getEmittedReceiptsForTests(): RedactionReceipt[] {
+  return [..._testReceipts];
+}
+
+/** Resets all receipt state and enables test-mode collection. */
+export function resetReceiptsForTests(): void {
+  _enabled = false;
+  _signingKey = undefined;
+  _serviceName = 'unknown';
+  _testMode = true;
+  _testReceipts.length = 0;
+  setReceiptHook(null);
+}