@glassops/scribe 1.0.2 → 1.0.4

package/README.md

@@ -20,35 +20,42 @@ This ensures production, staging, and development never collide, and that multi
 ### Structured, operationally meaningful logs
 
 - JSON‑structured entries with timestamps.
-- Daily‑rotated files with configurable retention.
-- Semantic log levels (critical, change, http, etc.) mapped to dedicated transports.
-- Request‑scoped metadata (tenant, service, environment, user, correlationId, requestId).
+- Daily-rotated files with configurable retention (default: 14 days).
+- Semantic log levels (`critical`, `change`, `http`, etc.) mapped to dedicated transports.
+- Request-scoped metadata (`tenant`, `service`, `environment`, `user`, `correlationId`, `requestId`).
 
 ### Deep, case‑insensitive redaction
 
 Sensitive keys are removed at any depth, regardless of casing:
 
-- password, Password, PASSWORD.
-- authorization, Authorization, etc.
+- `password`, `Password`, `PASSWORD`
+- `authorization`, `Authorization`, etc.
 
-Circular references become "[Circular]". Buffers become "[Binary]".
+Other behaviors:
+
+- Circular references → `"[Circular]"`
+- Buffers → `"[Binary]"`
 
 ### Transport‑agnostic architecture
 
 File transports are enabled by default, but Scribe supports:
 
-- Console‑only mode.
-- Cloud‑only mode.
-- Hybrid mode.
+- Console‑only mode
+- Cloud‑only mode
+- Hybrid mode
 
-Using:
+Configurable through:
 
 - `disableFileTransports`
 - `extraTransports`
 
 ### Pure, re‑entrant API
 
-No global state, no shared mutable configuration, no hidden defaults. Every logger instance is fully deterministic and scoped.
+- No global state
+- No shared mutable configuration
+- No hidden defaults
+
+Every logger instance is fully deterministic and scoped.
 
 ## Installation
 
@@ -60,18 +67,16 @@ npm install @glassops/scribe
 
 Scribe is built around three principles:
 
-- Identity is explicit — every log entry carries a complete scope describing tenant, environment, service, and correlation identifiers.
-- Streams are semantic — incidents, changes, HTTP traffic, and application logs are treated as distinct operational categories.
-- Safety is mandatory — redaction, sanitization, and directory grammar are enforced before logs reach any transport.
+- **Identity is explicit**: Every log entry carries a complete scope describing tenant, environment, service, and correlation identifiers.
+- **Streams are semantic**: Incidents, changes, HTTP traffic, and application logs are treated as distinct operational categories.
+- **Safety is mandatory**: Redaction, sanitization, and directory grammar are enforced before logs reach any transport.
 
 ## Directory structure
 
-Scribe derives the log directory from the LoggerScope:
+All segments of the directory path are sanitized to prevent traversal or invalid characters.
 
-With service: `<target>/<service>/<tenant>`
-Without service: `<target>/<tenant>/<environment>`
-
-All segments are sanitized to prevent traversal or invalid characters.
+- With service: `<target>/<service>/<tenant>`
+- Without service: `<target>/<tenant>/<environment>`
 
 ## Usage
 
@@ -92,20 +97,24 @@ const directory = createDirectory("/var/logs", {
 ```ts
 import { createLogger } from "@glassops/scribe";
 
-const logger = createLogger(directory, {
-  tenant: "acme",
-  environment: "production",
-  service: "billing",
-  correlationId: "abc123",
-}, {
-  level: "info",
-  requestLog: "requests-%DATE%.log",
-  appLog: "app-%DATE%.log",
-  incidentLog: "incident-%DATE%.log",
-  changeLog: "change-%DATE%.log",
-  logToConsole: true,
-  sensitiveKeys: ["password", "token"],
-});
+const logger = createLogger(
+  directory,
+  {
+    tenant: "acme",
+    environment: "production",
+    service: "billing",
+    correlationId: "abc123",
+  },
+  {
+    level: "info",
+    requestLog: "requests-%DATE%.log",
+    appLog: "app-%DATE%.log",
+    incidentLog: "incident-%DATE%.log",
+    changeLog: "change-%DATE%.log",
+    logToConsole: true,
+    sensitiveKeys: ["password", "token"],
+  }
+);
 ```
 
 ## Logging methods
@@ -124,47 +133,62 @@ Example:
 ```ts
 logger.logInfo("User updated profile", {
   userId: "123",
-  password: "secret", // redacted
+  password: "secret", // redacted automatically
 });
 ```
 
 ## HTTP logging (Morgan integration)
 
+Scribe supports direct integration with Morgan. ANSI sequences are stripped before writing to ensure clean JSON logs:
+
 ```ts
 app.use(morgan("combined", { stream: logger.createLoggerStream() }));
 ```
 
-ANSI sequences are stripped before writing, ensuring clean machine‑readable logs.
-
 ## Redaction behavior
 
-Scribe removes sensitive keys at any depth:
+- Case-insensitive key matching
+- Nested sensitive fields are recursively redacted
+- **Circular references**: `"[Circular]"`
+- **Buffers**: `"[Binary]"`
+
+## Scoping
+
+You can derive a new logger with additional metadata:
 
 ```ts
-{
-  password: "[REDACTED]",
-  nested: {
-    token: "[REDACTED]"
-  }
-}
+const userLogger = await logger.scope({ user: "steven" });
+userLogger.logInfo("User action");
 ```
 
-- Case‑insensitive matching
-- Circular references → "[Circular]"
-- Buffers → "[Binary]"
+Produces a new logger instance with merged scope. Logger directory may change if scope affects service or environment.
 
-## Scoping
+Existing transports are closed and rebuilt automatically if necessary.
 
-You can derive a new logger with additional metadata:
-const userLogger = logger.scope({ user: "steven" });
-userLogger.logInfo("User action");
+## Logger API
+
+```ts
+interface ScribeLogger {
+    logError(error: string | Error, context?: Record<string, unknown>): void;
+    logWarn(message: string, context?: Record<string, unknown>): void;
+    logInfo(message: string, context?: Record<string, unknown>): void;
+    logDebug(message: string, context?: Record<string, unknown>): void;
+    logIncident(message: string, context?: Record<string, unknown>): void;
+    logChange(message: string, context?: Record<string, unknown>): void;
+    createLoggerStream(): { write: (message: string) => void };
+    scope(partial: Partial<LoggerScope>): Promise<void>;
+    close(): Promise<void>;
+    logger: Logger;
+}
+```
 
-This produces a new logger instance with merged scope.
+- `createLoggerStream()`: Returns a Morgan-compatible writable stream.
+- `scope()`: Returns a `Promise<void>`; merges partial metadata into current logger.
+- `close()`: Gracefully shuts down transports.
+- `logger`: Exposes underlying Winston Logger instance.
 
 ## Transport configuration
 
-Scribe supports file‑based, console‑only, cloud‑only, and hybrid modes.
-
 ```ts
 interface LoggerOptions {
   level: LogLevel;
@@ -175,7 +199,6 @@ interface LoggerOptions {
   logToConsole?: boolean;
   sensitiveKeys?: string[];
   retention?: string;
-
   disableFileTransports?: boolean;
   extraTransports?: Transport[];
 }
@@ -191,11 +214,13 @@ interface LoggerOptions {
 - `change`
 - `debug`
 
+Each level is treated as a separate operational stream rather than a severity threshold.
+
 ## Build and publish
 
-Scribe uses a strict file whitelist and a deterministic build pipeline.
+Scribe uses a strict file whitelist and deterministic build pipeline.
 
-## Scripts
+### Scripts
 
 ```json
 {
@@ -207,13 +232,13 @@ Scribe uses a strict file whitelist and a deterministic build pipeline.
 }
 ```
 
-Prepack ensures `dist/` is always built before:
+Prepack ensures dist/ is always built before:
 
 - `npm publish`
 - `npm publish --dry-run`
 - `npm pack`
 
-Files included in the package
+Files included in the package:
 
 ```json
 {
@@ -221,29 +246,21 @@ Files included in the package
 }
 ```
 
-This guarantees only compiled output and documentation are published.
+Guarantees only compiled output and documentation are published.
 
 ## Design rationale
 
-- Directory grammar prevents cross‑environment and cross‑tenant collisions.
+- Directory grammar prevents cross-environment and cross-tenant collisions.
 - Semantic log levels allow operational tooling to treat incidents, changes, and HTTP traffic as distinct streams.
-- Deep, case‑insensitive redaction prevents credential leakage.
-- Pure, re‑entrant API ensures deterministic behavior across multi‑tenant and multi‑service deployments.
+- Deep, case-insensitive redaction prevents credential leakage.
+- Pure, re-entrant API ensures deterministic behavior across multi-tenant and multi-service deployments.
 - Daily rotation keeps log files predictable for ingestion pipelines.
-- Transport‑agnostic design supports file, console, cloud, and hybrid logging.
+- Transport-agnostic design supports file, console, cloud, and hybrid logging.
 
 ## License
 
 Copyright [2026] [GlassOps Limited]
 
-Licensed under the Apache License, Version 2.0 (the ["License"](LICENSE));
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-<http://www.apache.org/licenses/LICENSE-2.0>
+Licensed under the Apache License, Version 2.0 (["License"](LICENSE)).
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.

package/dist/index.d.ts

@@ -13,7 +13,7 @@
 /**
  * Public authoring contracts for configuring logger scope and behavior.
  */
-export type { LoggerScope, LoggerOptions, LogLevel } from './types.js';
+export type { LoggerScope, LoggerOptions, LogLevel, ScribeLogger } from './types.js';
 /**
  * Pure, deterministic entrypoints for initializing the log directory and
  * constructing a scoped logger instance. These are the primary runtime APIs.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;gFAWgF;AAKhF;;GAEG;AACH,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAKvE;;;GAGG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKlD;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;gFAWgF;AAKhF;;GAEG;AACH,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAKrF;;;GAGG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAKlD;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/types.d.ts

@@ -6,7 +6,22 @@
 /* --------------------------------------------------------------------------
 |* NPM Dependencies
 \* -------------------------------------------------------------------------- */
-import type Transport from "winston-transport";
+import type { Logger } from 'winston';
+import type Transport from 'winston-transport';
+export interface ScribeLogger {
+    logError: (error: string | Error, context?: Record<string, unknown>) => void;
+    logWarn: (message: string, context?: Record<string, unknown>) => void;
+    logInfo: (message: string, context?: Record<string, unknown>) => void;
+    logDebug: (message: string, context?: Record<string, unknown>) => void;
+    logIncident: (message: string, context?: Record<string, unknown>) => void;
+    logChange: (message: string, context?: Record<string, unknown>) => void;
+    createLoggerStream: () => {
+        write: (message: string) => void;
+    };
+    scope: (partial: Partial<LoggerScope>) => Promise<void>;
+    close: () => Promise<void>;
+    logger: Logger;
+}
 /**
  * Describes the identity of the log stream. Every log entry is tagged with
  * these fields to ensure deterministic partitioning across tenants,
@@ -62,5 +77,5 @@ export interface LoggerOptions {
  * Supported semantic log levels. These map directly to Scribe's custom
  * level hierarchy and determine which transport receives each log entry.
  */
-export type LogLevel = "critical" | "error" | "warn" | "info" | "http" | "change" | "debug";
+export type LogLevel = 'critical' | 'error' | 'warn' | 'info' | 'http' | 'change' | 'debug';
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;gFAOgF;AAChF,OAAO,KAAK,SAAS,MAAM,mBAAmB,CAAC;AAK/C;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAKD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,QAAQ,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,SAAS,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACnC;AAKD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GACd,UAAU,GACV,OAAO,GACP,MAAM,GACN,MAAM,GACN,MAAM,GACN,QAAQ,GACR,OAAO,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;gFAOgF;AAChF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACtC,OAAO,KAAK,SAAS,MAAM,mBAAmB,CAAC;AAK/C,MAAM,WAAW,YAAY;IACzB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC7E,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACtE,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACtE,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACvE,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC1E,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACxE,kBAAkB,EAAE,MAAM;QAAE,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;IAC/D,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;CAClB;AAKD;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAKD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,QAAQ,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,SAAS,EAAE,CAAC;IAC9B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACnC;AAKD;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@glassops/scribe",
-    "version": "1.0.2",
+    "version": "1.0.4",
     "description": "Deterministic, multi-tenant logging subsystem for GlassOps services.",
     "license": "Apache-2.0",
     "author": "GlassOps Limited",