ntlogger 3.0.0 → 4.0.0

package/README.md

@@ -1,6 +1,6 @@
 # NightTimeLogger
 
-NightTimeLogger is a custom logging wrapper built on top of the Winston logging library. It provides a ready-to-go solution for integrating advanced logging functionalities into Node.js applications with ease.
+NightTimeLogger provides Winston and Pino logging backends with shared logging conventions. Install the backend your application uses.
 
 [![Node.js Package](https://github.com/NightSquawk/NightTimeLogger/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/NightSquawk/NightTimeLogger/actions/workflows/main.yml)
 
@@ -13,7 +13,7 @@ const logger = require('ntlogger');
 const unregister = logger.setupSignalHandlers({ timeout: 30000 });
 ```
 
-Alternatively, keep your application's own shutdown handlers and `await log.close()` there. Importing the package no longer changes process exception or signal handling. Flush and close reject on delivery errors/timeouts, so callers should handle rejected promises. Close is idempotent, waits for transport cleanup, and removes the logger from its cache. Children share their parent's transports; closing a child flushes but does not close the parent. Log calls after close throw an error.
+Alternatively, keep your application's own shutdown handlers and `await log.close()` there. Importing the package no longer changes process exception or signal handling. Flush and close reject on delivery errors/timeouts, so callers should handle rejected promises. Close is idempotent, waits for transport cleanup, and removes the logger from its cache. Children share their parent's transports; closing a child flushes but does not close the parent. Log calls after close throw on both backends. See the Pino lifecycle note below for its drain result contract.
 
 OpenTelemetry users must upgrade the logs SDK/API/HTTP exporter together to `^0.222.0` and resources to `^2.11.0`. Earlier SDK versions are no longer advertised as compatible. Database transports now own separate pools, use event timestamps in UTC, accept `ssl` configuration, and require simple SQL table identifiers. Existing tables are not altered automatically.
 
@@ -35,14 +35,29 @@ OpenTelemetry users must upgrade the logs SDK/API/HTTP exporter together to `^0.
 
 ## Installation
 
-To install NightTimeLogger, use npm:
+For Pino or Fastify:
 
 ```bash
-npm install ntlogger
+npm install ntlogger pino
 ```
 
-The core package depends only on `winston` and `winston-transport`, so a default
-install stays small.
+Import helpers from `ntlogger/pino`. This installation does not pull in Winston or
+its transports. The small `split2` dependency supports the development formatter.
+
+For the Winston API and its plugins:
+
+```bash
+npm install ntlogger winston winston-transport
+```
+
+Import `ntlogger` as before. Both backends are optional peers, so install the one
+you use; applications using both entry points should install all three peers.
+
+**Upgrade note:** Winston and `winston-transport` were previously installed by
+ntlogger automatically. Existing Winston consumers must add them as direct
+production dependencies using the command above before upgrading. This is a
+breaking installation change in v4.0.0. See [release notes](docs/releases/v4.0.0.md)
+for the complete migration checklist.
 
 ### Optional plugin backends
 
@@ -57,8 +72,8 @@ Install only the ones whose plugins you actually enable:
 | OpenTelemetry | `npm install @opentelemetry/api @opentelemetry/api-logs @opentelemetry/sdk-logs @opentelemetry/exporter-logs-otlp-http @opentelemetry/resources @opentelemetry/semantic-conventions` |
 | Discord, Teams, OpenObserve, Syslog, Jest | none - no extra packages required |
 
-Plugin modules are resolved lazily, so a missing peer never breaks
-`require('ntlogger')`. The loader reports an actionable error naming the package and
+Plugin modules are resolved lazily, so a missing plugin backend never breaks
+`require('ntlogger')` when the Winston peers are installed. The loader reports an actionable error naming the package and
 the install command, skips that one plugin, and keeps every other plugin working.
 See [plugins/README.md](https://github.com/NightSquawk/NightTimeLogger/blob/main/plugins/README.md)
 for per-plugin configuration.
@@ -255,8 +270,8 @@ It provides an NTL-styled transport plus `createLogger()`, which wires the NTL c
 (module label, structured context, secret redaction, sampling, graceful shutdown) onto a real
 Pino logger.
 
-`pino` is an optional peer dependency and `split2` an optional dependency — Winston-only users
-install neither.
+`pino` is an optional peer dependency, so Winston-only users do not install it.
+`split2` is a small optional dependency installed by default for the Pino formatter.
 
 ### Transport only
 
@@ -384,13 +399,13 @@ const log = createLogger({
   deduplication: { enabled: true, threshold: 3, window: 60000 },
 });
 
-log.getStats();    // { sampling: {...}, deduplication: {...} }
+log.getStats();    // { sampling: {...}, deduplication: {...}, levels: {...}, hookErrors: 0 }
 log.resetStats();
 await log.close(); // releases the sampler/dedup timers, then flushes the destination
 ```
 
 `fatal` is never sampled, rate limited or deduplicated unless the configuration names it
-explicitly. Zero-config loggers install no feature hook at all.
+explicitly. Per-level counts are collected even without sampling or deduplication.
 
 ### Silent mode
 
@@ -398,18 +413,226 @@ Resolution order:
 
 1. `opts.silent`, when it is a boolean
 2. `NTLOGGER_SILENT` — `1`/`true`/`yes` → silent, `0`/`false`/`no` → not silent
-3. `NODE_ENV === 'test'` → silent
+3. `NODE_ENV === 'test'` or nonempty `NODE_TEST_CONTEXT` → silent
 
-A silent logger runs at Pino level `silent`, attaches no transport and installs no hooks, so
-test suites pay nothing for logging. `isSilent(opts)` is exported for testing the resolution.
+A silent logger runs at Pino level `silent`, attaches no transport and emits no
+records, counts, or observer callbacks. `isSilent(opts)` is exported for testing the resolution.
 
 ```javascript
 const log = createLogger({ module: 'API' });          // silent under Jest (NODE_ENV=test)
 const log = createLogger({ module: 'API', silent: false }); // force output in a test
 ```
 
-Node's built-in test runner does **not** set `NODE_ENV`, so projects using `node --test` should
-export `NTLOGGER_SILENT=1` in their test script instead.
+Node's built-in test runner is detected through `NODE_TEST_CONTEXT`; `node --test`
+scripts no longer need `NTLOGGER_SILENT=1` for the Pino API.
+
+### Fastify integration
+
+Use the plain options factory to retain Fastify's normal route logger types:
+
+```javascript
+const Fastify = require('fastify');
+const { createPinoOptions } = require('ntlogger/pino');
+
+const app = Fastify({
+  logger: createPinoOptions({
+    service: 'api',
+    contextProvider: () => requestContext.getStore(), // your AsyncLocalStorage
+    serializers: {
+      req: req => ({ method: req.method, url: req.url, headers: req.headers }),
+      res: reply => ({ statusCode: reply.statusCode, headers: reply.getHeaders() }),
+    },
+  }),
+});
+app.addHook('preHandler', async req => {
+  req.log.debug({ body: req.body }, 'parsed request body');
+});
+```
+
+The factory emits JSON options without creating a transport or installing process
+handlers. Fastify owns the logger and shutdown. It shares `createLogger()`'s
+service/module fields, context provider, silent-mode resolution, and redaction.
+Default request/response serializers retain Fastify's summary fields; headers and
+bodies are opt-in. Bodies are available after parsing, not in the initial request
+log. See [Fastify's logging documentation](https://fastify.dev/docs/latest/Reference/Logging/).
+
+Pass custom serializers **into the factory** so redaction runs on their output.
+Replacing returned formatters, hooks, or serializers (including route-level serializer
+overrides) can bypass protection. Ordinary log objects, message strings, and serialized
+request/response/error fields are redacted. Arbitrary child bindings are not covered by
+the factory's general deep redactor: keep them to identifiers such as `reqId` and
+`tenantId`, or protect specific binding paths with `redact: ['account.secret']`.
+`createLogger()` additionally redacts arbitrary child bindings.
+
+Sampling, rate limiting, deduplication, destinations, and process handlers are not
+accepted by this factory; use `createLogger()` for those features. Framework-owned
+loggers do not gain ntlogger's `getStats()`, `resetStats()`, or `close()` methods.
+
+### Capturing test logs
+
+```javascript
+const { createTestLogger } = require('ntlogger/pino');
+const { logger, records } = createTestLogger();
+logger.child({ jobId: 'j1' }).warn({ password: 'secret' }, 'retry');
+// records[0] includes level: 40, jobId: 'j1', password: '[REDACTED]', msg: 'retry'
+await logger.close();
+```
+
+Records are captured synchronously after Pino serialization and redaction, with no
+console output or worker transport. The helper defaults to level `trace` and overrides
+automatic/environment silence; explicit `silent: true` still captures nothing.
+Sampling and level filtering apply normally. Clear captured records with
+`records.length = 0` when needed.
+
+### Pino lifecycle
+
+Pino's `close(timeout?)` marks the logger closed immediately, releases root feature
+timers, and drains the destination and pending observer work. It is idempotent and
+resolves to `{ drained: true }` or `{ drained: false, error }`; inspect that result.
+Winston's close continues to reject on flush failures.
+
+Calls after close throw, including disabled levels, previously extracted log methods,
+and descendants of a closed logger. Closing a child leaves its parent and siblings
+open and keeps shared feature timers running. Changing a closed logger's level does
+not reopen it. Shutdown does not end a caller-supplied destination or shut down an
+application-owned OTel provider.
+
+### Tee callbacks and emitted counts
+
+Both `createLogger()` from `ntlogger/pino` and the Winston configuration accept `onLog`:
+
+```javascript
+const { createLogger } = require('ntlogger/pino');
+const log = createLogger({
+  onLog: record => dashboard.publish(record), // your dashboard/WebSocket adapter
+});
+log.child({ jobId: 'j1' }).warn({ deviceId: 'd1' }, 'retry');
+console.log(log.getStats().levels.warn); // 1
+await log.close();
+```
+
+The callback receives a detached record after redaction, context merging and filtering.
+Pino supplies its final serialized fields, including numeric `level` and `msg`. Winston
+supplies its record before transport-specific formatting, with a level name and `message`. Winston now also applies the default redactor before dispatching to its
+transports; `redact: false` explicitly disables protection on either backend.
+
+`getStats().levels` contains zero-initialized trace/debug/info/warn/error/fatal/internal
+counts shared with children. These count records prepared for output, not successful
+network delivery. Sampling/rate-limit/dedup drops and disabled levels do not count.
+Winston's asynchronous calls are reflected after `await log.flush()`.
+`resetStats()` clears level, sampling, dedup and `hookErrors` counters.
+
+Callback exceptions and rejected promises do not interrupt primary logging; they
+increment `hookErrors`. Logs made by callbacks still reach primary output but do not
+invoke observers again, including across asynchronous continuations. Async callbacks
+are awaited by Pino close and Winston flush/close, bounded by the shutdown timeout.
+`onLogMaxPending` caps in-flight callback promises (default 100; zero disables callbacks).
+At capacity, the newest callback is dropped; the primary log and OTel export continue.
+Already-running promises are never cancelled. `getStats().onLog` reports `pending`,
+`dropped`, and `limit`; reset clears drops but preserves the live pending gauge.
+Callback mutation cannot change the primary log or its OTel export. Return the delivery
+promise if it needs to be included in shutdown; detached background work is not tracked.
+
+Pino **9.14 or newer** is required for the serialized-output hook. This raises the old
+Pino 8 minimum as part of the v4.0.0 installation migration.
+
+### Scoped credential values
+
+Scanner defaults include `community`, `authPassword`, `privPassword`, and `passphrase`,
+including case/hyphen/underscore aliases and short or quoted free-text values. For an
+opaque credential that might appear in an error without a recognizable key:
+
+```javascript
+const { createLogger, withSecretValues } = require('ntlogger/pino');
+const log = createLogger({ module: 'scanner' });
+await withSecretValues([credentialValue], async () => {
+  log.info({ runId, workId }, 'scan started');
+  await runScan();
+});
+```
+
+`withSecretValues` is also exported by the Winston entry point. It scopes literal-value
+redaction to the callback and its async descendants, restores the parent afterward,
+and handles JSON-escaped forms. Use nonempty strings, at most 128 distinct values of
+65536 characters each. Short values can obscure unrelated text. Descendant tasks inherit
+secrets until they finish; avoid unrelated background work inside the scope. Explicit
+`redact: false` disables this protection along with other redaction. Context fields
+`runId`, `workId`, `stageId`, `deviceId`, and `collectionCycleId` now render in Pino's
+pretty context suffix as well as remaining searchable in JSON.
+
+### Python companion and shared contract
+
+A dependency-free Python 3.10+ companion is maintained in [python/](python/README.md).
+It provides `protect_handler`, `NdjsonFormatter`, `SafeFormatter`, `log_context`,
+`secret_values`, `SnapshotFilter`, and `create_test_logger`. Existing agent handlers,
+per-mode filenames, rotation and permissions remain application-owned. The companion
+adds sanitized structured records and exception details without requiring Node.
+Install locally with `python -m pip install ./python`; the new Python package is not
+published. Agent adoption is documented rather than applied to its repository.
+
+Shared redaction snapshots and conformance fixtures are exported at
+`ntlogger/contract/redaction.json` and `ntlogger/contract/conformance.json`. The Python
+wheel bundles the same defaults. `npm run test:contract` verifies generation; both
+language suites run the fixtures, including Python TRACE 5 → Pino 10.
+
+### OpenTelemetry correlation and export
+
+Use your existing logs SDK provider and processors; ntlogger does not create a global
+provider or a second pipeline. With a batch processor and OTLP exporter already attached:
+
+```javascript
+const { createLogger } = require('ntlogger/pino');
+const log = createLogger({ otel: { loggerProvider, name: 'worker' } });
+// Inside your application's active span:
+log.info({ jobId: 'j1' }, 'job started');
+const result = await log.close(); // calls the supplied provider's forceFlush(), if present
+// Shut down the application-owned provider separately when all producers have stopped.
+```
+
+Enable a context manager/tracing SDK in the application so the active span is available.
+The bridge adds `traceId`, `spanId` and `traceFlags` to Pino JSON and supplies the active
+context to the OTel SDK, with correct severity mapping and redacted attributes. Nested
+attributes are JSON strings; Pino error fields also map to OTel exception attributes.
+No active span means no invented trace IDs. `otel: true` uses the globally registered
+logs provider; without a configured SDK provider that provider is a no-op. Install
+`@opentelemetry/api` and `@opentelemetry/api-logs` plus your chosen SDK/exporter packages
+only when enabling this option. Both backends support the option; do not also enable
+the Winston OTel plugin for the same output or records will be exported twice.
+
+`createPinoOptions()` also accepts `onLog` and `otel`. Fastify still owns its lifecycle;
+track async callback promises and flush the provider in your application shutdown hook.
+It does not gain ntlogger's counters or close method. SDK exporters can report delivery
+errors through their own diagnostics rather than rejecting provider flush; a successful
+drain alone is not a delivery acknowledgment.
+
+The library tests verify real SDK records and HTTP OTLP delivery to a local collector.
+The API/worker deployments still need adoption and a check of their own collector routing.
+
+### Structured logging lint rule
+
+The optional ESLint plugin supports ESLint 9+ and has no runtime logger dependencies.
+Enable it for Pino call sites in a flat configuration:
+
+```javascript
+const ntlogger = require('ntlogger/eslint');
+module.exports = [{
+  files: ['src/**/*.js'],
+  plugins: { ntlogger },
+  rules: {
+    'ntlogger/prefer-object-first': ['warn', {
+      loggerNames: ['log', 'logger', 'req.log', 'request.log'],
+    }],
+  },
+}];
+```
+
+It reports interpolated first-argument template strings. `--fix` adds searchable fields
+while retaining the original message only when each expression is a known primitive
+`const` identifier and there are no other arguments. Calls, getters, mutable values and
+complex expressions are reported without a fix. Convert those manually, for example
+`log.info({ deviceId: device.id }, 'scan started')`. Receiver matching is configurable
+and syntactic; scope the rule to Pino code, since Winston's message-first methods have
+a different contract. Consumer call-site migrations are not performed in this repository.
 
 ### Process handlers
 
@@ -467,3 +690,5 @@ NightTimeLogger is licensed under the [GPL-3.0 License](https://opensource.org/l
 Run `npm ci` and `npm run test:coverage` for the complete suite. MySQL and PostgreSQL integration tests start disposable Docker containers; CI sets `REQUIRE_DOCKER_TESTS=1` so they cannot silently skip. `npm run test:unit` excludes those two Docker suites for local work. `npm audit` checks all dependencies; `npm audit --omit=dev` checks production dependencies.
 
 HTTP transports (Discord, Teams, OpenObserve) accept `timeout` (5000 ms per attempt), `maxRetries` (3), `retryDelay` (1000 ms), and `maxPending` (100 outstanding deliveries). They retry connection failures, HTTP 429 and 5xx with bounded backoff. Queue overflow, terminal HTTP errors, and timeouts surface through callbacks/flush. Delivery is best-effort with retries, not durable storage; an ambiguous network failure can lead to a duplicate on retry. OpenObserve retains batching and flush now waits for responses. Increase `shutdownTimeout` if you configure longer retries.
+
+Packed installation checks: run `npm run test:package`. This requires npm registry access and uses temporary consumer directories to verify Pino-only and Winston-only installs.

package/contract/conformance.json

@@ -0,0 +1,133 @@
+{
+  "version": 1,
+  "levels": [
+    {
+      "python": 5,
+      "pino": 10,
+      "name": "trace"
+    },
+    {
+      "python": 10,
+      "pino": 20,
+      "name": "debug"
+    },
+    {
+      "python": 20,
+      "pino": 30,
+      "name": "info"
+    },
+    {
+      "python": 30,
+      "pino": 40,
+      "name": "warn"
+    },
+    {
+      "python": 40,
+      "pino": 50,
+      "name": "error"
+    },
+    {
+      "python": 50,
+      "pino": 60,
+      "name": "fatal"
+    }
+  ],
+  "redaction": [
+    {
+      "input": {
+        "community": "public",
+        "authPassword": "ab",
+        "priv_password": "private",
+        "passphrase": "with spaces",
+        "privateKey": "key",
+        "runId": "r1"
+      },
+      "expected": {
+        "community": "[REDACTED]",
+        "authPassword": "[REDACTED]",
+        "priv_password": "[REDACTED]",
+        "passphrase": "[REDACTED]",
+        "privateKey": "[REDACTED]",
+        "runId": "r1"
+      }
+    },
+    {
+      "input": "community=public authPassword=ab passphrase=\"with spaces\"",
+      "expected": "community=[REDACTED] authPassword=[REDACTED] passphrase=[REDACTED]"
+    },
+    {
+      "input": "{'privPassword': 'ab', 'community': 'x'}",
+      "expected": "{'privPassword': [REDACTED], 'community': [REDACTED]}"
+    },
+    {
+      "input": {
+        "nested": [
+          {
+            "authorization": "Bearer example-secret",
+            "X-Device-Installation-Secret": "key"
+          }
+        ],
+        "agentUuid": "a1",
+        "token": null
+      },
+      "expected": {
+        "nested": [
+          {
+            "authorization": "[REDACTED]",
+            "X-Device-Installation-Secret": "[REDACTED]"
+          }
+        ],
+        "agentUuid": "a1",
+        "token": null
+      }
+    },
+    {
+      "input": "https://user:secret@example.test/path Bearer abcdefghijklmnop",
+      "expected": "https://user:[REDACTED]@example.test/path Bearer [REDACTED]"
+    },
+    {
+      "input": "-----BEGIN PRIVATE KEY-----\nexample\n-----END PRIVATE KEY-----",
+      "expected": "[REDACTED]"
+    },
+    {
+      "input": "password=secret",
+      "expected": "password=[REDACTED]"
+    },
+    {
+      "input": "AKIA1234567890ABCDEF",
+      "expected": "[REDACTED]"
+    },
+    {
+      "input": "eyJabcdef.abcdefgh.abcdefgh",
+      "expected": "[REDACTED]"
+    },
+    {
+      "input": "ghp_aaaaaaaaaaaaaaaaaaaaaaaa",
+      "expected": "[REDACTED]"
+    },
+    {
+      "input": "xoxb-aaaaaaaaaaaa",
+      "expected": "[REDACTED]"
+    },
+    {
+      "input": "sk_live_aaaaaaaaaaaa",
+      "expected": "[REDACTED]"
+    },
+    {
+      "input": "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
+      "expected": "Basic [REDACTED]"
+    },
+    {
+      "input": "https://discord.com/api/webhooks/123456789/abcXYZ-secret",
+      "expected": "https://discord.com/api/webhooks/123456789/[REDACTED]"
+    },
+    {
+      "input": "passphrase=\"unterminated with spaces",
+      "expected": "passphrase=[REDACTED]"
+    },
+    {
+      "input": "community=[private]",
+      "expected": "community=[REDACTED]"
+    }
+  ]
+}

package/contract/redaction.json

@@ -0,0 +1,115 @@
+{
+  "version": 1,
+  "keys": [
+    "password",
+    "passwd",
+    "pass",
+    "pwd",
+    "secret",
+    "token",
+    "apikey",
+    "api_key",
+    "x-api-key",
+    "authorization",
+    "proxy-authorization",
+    "cookie",
+    "set-cookie",
+    "x-device-installation-secret",
+    "installationsecret",
+    "privatekey",
+    "private_key",
+    "clientsecret",
+    "client_secret",
+    "accesstoken",
+    "access_token",
+    "refreshtoken",
+    "refresh_token",
+    "idtoken",
+    "id_token",
+    "sessiontoken",
+    "credential",
+    "credentials",
+    "webhookurl",
+    "snmpcommunity",
+    "community_string",
+    "community",
+    "authPassword",
+    "privPassword",
+    "passphrase"
+  ],
+  "patterns": [
+    {
+      "source": "-----BEGIN (?:[A-Z]+ )*PRIVATE KEY-----[\\s\\S]*?-----END (?:[A-Z]+ )*PRIVATE KEY-----",
+      "flags": "g"
+    },
+    {
+      "source": "\\bAKIA[0-9A-Z]{16}\\b",
+      "flags": "g"
+    },
+    {
+      "source": "\\beyJ[A-Za-z0-9_-]{5,}\\.[A-Za-z0-9_-]{5,}\\.[A-Za-z0-9_-]{5,}",
+      "flags": "g"
+    },
+    {
+      "source": "\\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})",
+      "flags": "g"
+    },
+    {
+      "source": "\\bxox[abpors]-[A-Za-z0-9-]{10,}",
+      "flags": "gi"
+    },
+    {
+      "source": "\\b(?:[sr]k_(?:live|test)_[A-Za-z0-9]{10,}|whsec_[A-Za-z0-9]{10,})",
+      "flags": "g"
+    },
+    {
+      "source": "(?<pre>\\bBearer\\s+)[A-Za-z0-9\\-._~+/]{8,}={0,2}",
+      "flags": "gi"
+    },
+    {
+      "source": "(?<pre>\\bBasic\\s+)(?=[A-Za-z0-9+/]*[A-Z0-9])[A-Za-z0-9+/]{16,}={0,2}",
+      "flags": "g"
+    },
+    {
+      "source": "(?<pre>https?:\\/\\/(?:[a-z]+\\.)?discord(?:app)?\\.com\\/api\\/(?:v\\d+\\/)?webhooks\\/\\d+\\/)[A-Za-z0-9_-]+",
+      "flags": "gi"
+    },
+    {
+      "source": "(?<pre>[\"']?\\b(?:snmp[_-]?community|community(?:[_-]?string)?|auth[_-]?password|priv[_-]?password|passphrase)[\"']?\\s*[:=]\\s*)(?:\"(?:\\\\.|[^\"\\\\])*(?:\"|$)|'(?:\\\\.|[^'\\\\])*(?:'|$)|[^\\s,;}]+)",
+      "flags": "gi"
+    },
+    {
+      "source": "(?<pre>\\b(?:api[_-]?key|apikey|access[_-]?key|access[_-]?token|refresh[_-]?token|secret[_-]?key|client[_-]?secret|password|passwd|pwd|auth[_-]?token|private[_-]?key|token|secret)\\s*[:=]\\s*[\"']?)[^\\s'\",;]{4,}",
+      "flags": "gi"
+    },
+    {
+      "source": "(?<pre>\\b(?:password|passwd|secret|token|api[_-]?key)\\s*[=:]\\s*)(?![\"'[])\\S+",
+      "flags": "gi"
+    },
+    {
+      "source": "(?<pre>\\b[a-z][a-z0-9+.-]*:\\/\\/[^\\s:/?#@]*:)[^\\s/?#@]+(?<post>@)",
+      "flags": "gi"
+    }
+  ],
+  "pythonLevels": {
+    "5": 10,
+    "10": 20,
+    "20": 30,
+    "30": 40,
+    "40": 50,
+    "50": 60
+  },
+  "contextAliases": {
+    "agent_uuid": "agentUuid",
+    "tenant_id": "tenantId",
+    "command_id": "commandId",
+    "collection_cycle_id": "collectionCycleId",
+    "correlation_id": "correlationId",
+    "run_id": "runId",
+    "work_id": "workId",
+    "stage_id": "stageId",
+    "device_id": "deviceId",
+    "trace_id": "traceId",
+    "span_id": "spanId"
+  }
+}

package/eslint-rules/prefer-object-first.js

@@ -0,0 +1,53 @@
+'use strict';
+
+function receiverName(node) {
+    if (node.type === 'Identifier') return node.name;
+    if (node.type === 'ThisExpression') return 'this';
+    if (node.type === 'MemberExpression' && !node.computed) {
+        const prefix = receiverName(node.object);
+        return prefix && `${prefix}.${node.property.name}`;
+    }
+    return null;
+}
+module.exports = {
+    meta: {
+        type: 'suggestion',
+        docs: { description: 'Keep interpolated Pino log fields searchable with an object-first call.' },
+        fixable: 'code',
+        schema: [{ type: 'object', properties: {
+            loggerNames: { type: 'array', items: { type: 'string' }, uniqueItems: true },
+        }, additionalProperties: false }],
+        messages: { structured: 'Pass searchable fields as the first argument to this logger.' },
+    },
+    create(context) {
+        const names = new Set(context.options[0]?.loggerNames || ['log', 'logger', 'req.log', 'request.log', 'app.log', 'fastify.log']);
+        const methods = new Set(['trace', 'debug', 'info', 'warn', 'error', 'fatal']);
+        const source = context.sourceCode;
+        function constantPrimitive(identifier) {
+            let scope = source.getScope(identifier);
+            let variable;
+            while (scope && !variable) { variable = scope.set.get(identifier.name); scope = scope.upper; }
+            const def = variable?.defs[0];
+            return variable?.defs.length === 1 && def?.parent?.kind === 'const'
+                && def.node.id.type === 'Identifier' && def.node.init?.type === 'Literal'
+                && !def.node.init.regex && typeof def.node.init.value !== 'object';
+        }
+        return {
+            CallExpression(node) {
+                const callee = node.callee;
+                if (callee.type !== 'MemberExpression' || callee.computed
+                    || !methods.has(callee.property.name) || !names.has(receiverName(callee.object))) return;
+                const template = node.arguments[0];
+                if (template?.type !== 'TemplateLiteral' || !template.expressions.length) return;
+                const canFix = node.arguments.length === 1 && template.expressions.every(expr =>
+                    expr.type === 'Identifier' && expr.name !== '__proto__' && constantPrimitive(expr));
+                context.report({ node: template, messageId: 'structured',
+                    // Keep the original message and its formatting. Only duplicate reads
+                    // of known primitive consts; calls/getters/mutable bindings need review.
+                    fix: canFix ? fixer => fixer.insertTextBefore(template,
+                        `{ ${[...new Set(template.expressions.map(expr => expr.name))].join(', ')} }, `) : undefined,
+                });
+            },
+        };
+    },
+};

package/eslint.d.ts

@@ -0,0 +1,3 @@
+import type { ESLint } from 'eslint';
+declare const plugin: ESLint.Plugin;
+export = plugin;

package/eslint.js

@@ -0,0 +1,5 @@
+'use strict';
+module.exports = {
+    meta: { name: 'ntlogger' },
+    rules: { 'prefer-object-first': require('./eslint-rules/prefer-object-first') },
+};