@ontrails/pino 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## 0.2.0
+
+### Patch Changes
+
+- [`664e8bb`](https://github.com/outfitter-dev/trails/commit/664e8bb049e61f1d47cec1dd246606707af5d1a8): Point public installation examples at exact approved 0.2.0 versions and distinguish the prepared source release from pending npm publication.
+- [`b3ddf91`](https://github.com/outfitter-dev/trails/commit/b3ddf918ada8211f44983512e2bbdfbc5b66d722): Prepare the first normal Trails release at `0.2.0` on `latest`, replacing the unpublished 1.0.0 source release. The target advances the original `0.1.0` source minor, which was never published under the current package names. Public packages remain in lockstep. Update consumer installation guidance and provide a temporary manifest bridge for old 1.0 beta sources. Published beta versions remain unchanged; minor 0.x releases may carry documented breaking changes.
+
+  The `1.0.0` section retained below records an unpublished preparation, not an npm release. Its accumulated changes are included in `0.2.0`; the section remains as source history alongside the published beta entries.
+
+## 1.0.0
+
+### Minor Changes
+
+- [`50e2779`](https://github.com/outfitter-dev/trails/commit/50e27796d074851bccd57d7df009db749757b457): Extract the real `@ontrails/logtape` and `@ontrails/pino` adapters from the
+  temporary observability subpaths. The new packages own their namesake foreign
+  dependencies and preserve Trails record metadata, levels, redaction boundaries,
+  and lifecycle behavior; the old subpaths are removed in the pre-v1 hard cut.
+
+  Add governed Regrade transitions for both exact import replacements and expose
+  the observability adapter target through the shared adapter readiness check.
+
+### Patch Changes
+
+- [`47297d9`](https://github.com/outfitter-dev/trails/commit/47297d98230a4adb25b99b3c8a71217113379398): Treat both `null` and `undefined` Pino flush callback results as success, and verify asynchronous buffered destinations finish writing before the sink resolves.
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+
+## 1.0.0-beta.50
+
+## 1.0.0-beta.49
+
+## 1.0.0-beta.48
+
+## 1.0.0-beta.47
+
+## 1.0.0-beta.46
+
+## 1.0.0-beta.45
+
+## 1.0.0-beta.44
+
+### Patch Changes
+
+- [`b1fbe57`](https://github.com/outfitter-dev/trails/commit/b1fbe574e6f44d1fecb5e3a000270955c0a77b7b): Publish Bun-validated package tarballs through an npm trusted-publishing adapter
+  binding, add exact repository metadata for each public workspace package, and
+  correct the native Bun release descriptor to its pack-only runtime boundary.
+
+## 1.0.0-beta.43
+
+### Minor Changes
+
+- [`50e2779`](https://github.com/outfitter-dev/trails/commit/50e27796d074851bccd57d7df009db749757b457): Extract the real `@ontrails/logtape` and `@ontrails/pino` adapters from the
+  temporary observability subpaths. The new packages own their namesake foreign
+  dependencies and preserve Trails record metadata, levels, redaction boundaries,
+  and lifecycle behavior; the old subpaths are removed in the pre-v1 hard cut.
+
+  Add governed Regrade transitions for both exact import replacements and expose
+  the observability adapter target through the shared adapter readiness check.
+
+All notable changes to this package are documented through the Trails release process.

package/README.md

@@ -0,0 +1,37 @@
+# @ontrails/pino
+
+Real Pino adapter for Trails observability. This extracted package owns the Pino dependency boundary, keeping `@ontrails/observability` limited to Trails-native records, sink contracts, redaction, formatters, and built-ins.
+
+## Usage
+
+```typescript
+import pino from 'pino';
+import { createPinoSink } from '@ontrails/pino';
+
+const logger = pino({ level: 'info' });
+const sink = createPinoSink({ logger });
+
+sink.write({
+  category: 'app.http',
+  level: 'info',
+  message: 'request received',
+  metadata: { requestId: 'req_123' },
+  timestamp: new Date(),
+});
+
+await sink.flush();
+```
+
+Pass `pinoOptions` and an optional Pino destination when the adapter should construct the logger. For an asynchronously buffered destination, await `sink.flush()` before shutdown so accepted records reach Pino's destination. Trails records arrive after Trails-owned redaction, retain their category and timestamp as structured fields, and map `trace` through `fatal` directly to Pino levels. `silent` records do not reach Pino.
+
+## Installation
+
+These commands target stable `0.2.0`. Run them after that version is published to npm.
+
+```bash
+bun add --exact @ontrails/observability@0.2.0 @ontrails/pino@0.2.0
+```
+
+## Migration
+
+This package is the final Pino adapter in the pre-v1 hard cut. No compatibility subpath remains; see the logging migration guide for the explicit historical import map.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ontrails/pino",
+  "version": "0.2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "adapters/pino"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "pino": "^10.3.1"
+  },
+  "peerDependencies": {
+    "@ontrails/observability": "^0.2.0",
+    "zod": "^4.3.5"
+  },
+  "trails": {
+    "adapter": {
+      "target": "observability"
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,82 @@
+import pino from 'pino';
+import type { DestinationStream, Logger, LoggerOptions } from 'pino';
+
+import type { LogLevel, LogRecord, LogSink } from '@ontrails/observability';
+
+export interface PinoSinkOptions {
+  /** Destination used only when this adapter constructs the Pino logger itself. */
+  readonly destination?: DestinationStream | undefined;
+  /** Existing configured Pino logger to receive Trails records. */
+  readonly logger?: Logger | undefined;
+  /** Options used only when this adapter constructs the Pino logger itself. */
+  readonly pinoOptions?: LoggerOptions | undefined;
+  /** Sink name exposed to Trails observe configuration. Defaults to `pino`. */
+  readonly name?: string | undefined;
+}
+
+export interface PinoLogSink extends LogSink {
+  /** Flush an asynchronously buffered Pino destination, when one is present. */
+  flush(): Promise<void>;
+}
+
+type ForwardMethod = Exclude<LogLevel, 'silent'>;
+
+const LEVEL_MAP: Record<LogLevel, ForwardMethod | undefined> = {
+  debug: 'debug',
+  error: 'error',
+  fatal: 'fatal',
+  info: 'info',
+  silent: undefined,
+  trace: 'trace',
+  warn: 'warn',
+};
+
+const buildPayload = (record: LogRecord): Record<string, unknown> => ({
+  ...record.metadata,
+  category: record.category,
+  timestamp: record.timestamp.toISOString(),
+});
+
+/* oxlint-disable eslint-plugin-promise/avoid-new, eslint-plugin-promise/prefer-await-to-callbacks -- Pino exposes callback-only flush completion; the Trails sink contract is promise-based. */
+const flush = (logger: Logger): Promise<void> =>
+  new Promise((resolve, reject) => {
+    logger.flush((error) => {
+      if (error === null || error === undefined) {
+        resolve();
+        return;
+      }
+      reject(error);
+    });
+  });
+/* oxlint-enable eslint-plugin-promise/avoid-new, eslint-plugin-promise/prefer-await-to-callbacks */
+
+const resolveLogger = (options: PinoSinkOptions): Logger => {
+  if (options.logger !== undefined) {
+    return options.logger;
+  }
+  if (options.destination !== undefined) {
+    return pino(options.pinoOptions ?? {}, options.destination);
+  }
+  return options.pinoOptions === undefined ? pino() : pino(options.pinoOptions);
+};
+
+/**
+ * Create a Trails sink backed by a real Pino logger. If no logger is supplied,
+ * the adapter constructs one from `pinoOptions`; applications remain free to
+ * own destinations, transports, and richer Pino configuration directly.
+ */
+export const createPinoSink = (options: PinoSinkOptions = {}): PinoLogSink => {
+  const logger = resolveLogger(options);
+
+  return {
+    flush: async (): Promise<void> => await flush(logger),
+    name: options.name ?? 'pino',
+    write(record: LogRecord): void {
+      const method = LEVEL_MAP[record.level];
+      if (method === undefined) {
+        return;
+      }
+      logger[method](buildPayload(record), record.message);
+    },
+  };
+};