v4.4.73

Full Changelog: v4.4.72...v4.4.73

@fjell/logging 4.4.72: Ship npm-packaged integration guides + stabilize masking performance tests

Summary

This release is primarily documentation and packaging-focused: it adds a new guide/ set of “agentic” usage/integration docs and ensures they are included in the published npm package. It also adds and tunes masking performance timing tests to better guard against regressions without being overly flaky in CI.

Scope: 5 commits, 7 files changed (+110/−25). No production src/ code changed in this range.

Documentation: new packaged “Agentic” guides

• Added a new guide/ documentation set:
  • guide/index.md – overview and pointers
  • guide/usage.md – API-oriented usage patterns and examples
  • guide/integration.md – integration placement and composition guidance
• These guides are written to be friendly for AI-assisted/codegen workflows (clear “public API highlights”, consumption rules, and integration checklists).

Why it matters

• Users and internal teams get a canonical, package-adjacent reference for correct imports and integration structure—especially helpful when generating code or scaffolding services.
• The guide content is now part of what gets distributed, not just what lives in the repo.

Packaging: include guide/ in the published artifact

• Updated package.json to publish the guide directory (files: ["dist", "guide"]).
• Updated .npmignore to keep excluding most markdown by default, while explicitly including:
  • guide/
  • guide/*.md
  • guide/**/*.md

Impact

• npm consumers will now receive guide/ alongside dist/. This is additive and does not affect runtime behavior.

Tests: masking performance coverage and CI stability improvements

• Added performance-oriented timing tests for masking utilities and middleware across configurations (tests/masking.timing.test.ts).
• Adjusted assertions to reduce flakiness:
  • The “disabled masking” test now asserts on absolute overhead per call (microseconds) rather than percentage, since percentage becomes unstable when the baseline is extremely small.
  • Thresholds allow for realistic regex/object traversal overhead and CI variance while still catching major regressions.

Impact

• No API/runtime behavior changes, but better protection against accidental masking slowdowns.

Dependency/metadata changes

• Version bumped to 4.4.72.
• Lockfile synced to match.

Breaking changes

• None detected in this release (no public API or runtime code changes in src/).

4.4.71: Tooling dependency refresh and license notice update

Summary

Version 4.4.71 is a maintenance release focused on repository hygiene: it finalizes the 4.4.71 version, updates development tooling dependencies, syncs package-lock.json, and refreshes the Apache 2.0 license copyright notice.

No production/source code changes were included in this release.

Changes in this release

Versioning / release housekeeping

• Bumped @fjell/logging to 4.4.71 in package.json.
• Includes the usual prerelease-to-release progression (a 4.4.71-dev.0 bump occurred during the release process, then finalized to 4.4.71).

Development tooling updates

• Updated devDependencies and synchronized package-lock.json accordingly.
• Tooling versions in package.json now include (not exhaustive): ESLint (eslint, @eslint/*), TypeScript (typescript, @types/node), TypeScript ESLint (@typescript-eslint/*), Vitest (vitest, @vitest/coverage-v8), esbuild, and concurrently.

Impact for contributors: some updated tooling (notably Vitest/Vite in the lockfile) declares higher Node.js engine requirements than older toolchains. Even though this does not affect consumers of the published library at runtime, developers running tests/lint locally or in CI may need to use a newer Node.js version.

Licensing

• Updated the Apache 2.0 license notice to Copyright 2026 Tim O'Brien.

Breaking changes

• No breaking API changes detected (no changes to library source files).
• Potential developer-environment breakage: tooling Node.js requirements may have increased due to dev dependency updates (affects running lint/tests/build in this repo, not consuming the package).

4.4.70 — Consolidate logging safety documentation under `/docs` + version bump

Main story

This release is primarily a documentation and repository-structure cleanup: the “logging safety” docs were consolidated under docs/, large top-level documentation artifacts were removed, and the package version was bumped to 4.4.70 (with a lockfile sync).

There are no runtime/library source changes in this release—changes are limited to docs and release metadata.

Changes in this release

Documentation reorganization

• Moved/centralized key safety and configuration docs into docs/:
  • docs/CIRCULAR_REFERENCE_PROTECTION.md
  • docs/MASKING.md
  • docs/ERROR_HANDLING.md
  • docs/HIERARCHICAL_LOG_LEVELS.md
  • docs/README.md (now includes an “Additional Documentation” index)
• Updated the top-level README.md to link to the new docs/ locations for these topics.
• Updated CHANGELOG.md (still under the Unreleased section) to reflect the documentation additions/locations and describe the documented capabilities.

Repository cleanup (documentation artifacts removed)

The following top-level markdown documents were removed in favor of the consolidated docs/ set:

• CIRCULAR_REFERENCE_PROTECTION.md
• MASKING.md
• ERROR_HANDLING.md
• HIERARCHICAL_CONFIG_IMPLEMENTATION.md
• EXECUTIVE_TEST_SUMMARY.md
• MULTI_LEVEL_TESTING_SUMMARY.md
• TEST_SUMMARY_VISUAL.md
• COMPLETE_IMPLEMENTATION_SUMMARY.md
• COPIOUS_TEST_COVERAGE.md
• CHANGELOG_CIRCULAR_SAFETY.md

Release metadata

• package.json version updated to 4.4.70
• package-lock.json updated (lockfile sync as part of the release bump)

Impact

For users

• No behavior changes to @fjell/logging itself in this release.
• If you link to Fjell Logging docs by GitHub file path (for example in internal wikis), update links from the removed top-level *.md files to their new locations under docs/.

For developers/contributors

• The repo is significantly tidier (large doc/test-summary artifacts removed).
• Documentation now has a clearer entry point at docs/README.md.

Breaking changes

• No breaking API/runtime changes detected.
• Documentation path changes: any consumers referencing the removed top-level markdown files by path will need to update to the corresponding docs/* paths.

4.4.69: LLM-focused logging guides, minor repo housekeeping, and version bump

Main story

This release is primarily a documentation update: it adds a new set of guides on using @fjell/logging in LLM/agent workflows (logging conventions, correlation ID tracing, and masking/safety). There are no production code changes in this release range—behavior should be unchanged from the prior release.

What changed

New: AI/LLM logging guide (documentation)

A new guide/ section was added with practical guidance tailored to LLM applications:

• guide/llm-logging-basics.md

  • Recommended logger structure using hierarchical components (e.g., ingest, retrieval, generation, tools)
  • Suggested conventions for log levels in model pipelines
  • Example LOGGING_CONFIG setup for structured logs and targeted component overrides
  • Guidance on timing expensive operations with time() / end()

• guide/llm-request-tracing.md

  • End-to-end request tracing patterns using correlation IDs
  • Example helper for creating a per-request correlated logger and propagating the correlation ID across boundaries (HTTP headers, queues, internal calls)

• guide/llm-safety-and-masking.md

  • Logging safety principles for prompts/responses
  • How to enable masking via LOGGING_CONFIG.masking
  • Notes on performance overhead and how to keep logs concise

• guide/index.md

  • A landing page that ties the above documents together and explains why these practices matter in LLM systems

Package metadata

• package.json version updated to 4.4.69
• package-lock.json updated accordingly for the release process

Repo housekeeping

• .gitignore updated to ignore .kodrdriv* artifacts
• README.md was touched (no functional documentation changes beyond a minor edit)

Impact

For users of the library

• No runtime/API behavior changes in this release range.
• You get new, concrete guidance on how to apply existing features (correlation IDs, hierarchical components, masking config) specifically in LLM/agent systems.

For developers/maintainers

• Documentation is now structured to better support an AI-oriented docs pipeline and to centralize recommended patterns for observability and safety.

Breaking changes

• None identified. No source changes were included in this release range, and there are no intentional API removals/renames. (Any “new function signatures” detected are present only in documentation examples, not in the exported library code.)

@fjell/logging 4.4.68 — API key/secret masking + correlation ID utilities

Overview

This release focuses on two practical production concerns:

1. Preventing credential leaks in logs by expanding the masking system to detect common API keys, tokens, and secret patterns.
2. Improving request traceability by adding first-class correlation ID utilities and a logger wrapper.

Added

Sensitive data masking: API keys, Bearer tokens, and common secrets

The masking utilities now detect and mask additional sensitive values (replaced with ****), including:

• LLM provider keys
  • OpenAI: sk-*, sk-proj-*
  • Anthropic: sk-ant-*
• Cloud/platform tokens
  • AWS access keys: AKIA*
  • GitHub: ghp_*, gho_*, ghs_*, ghu_*
  • GitLab: glpat-*
  • Slack: xox*-* variants
  • Google Cloud: AIza*
• Generic secret patterns
  • api_key=, api-key=, apikey=
  • password=
  • secret=
  • token=
  • Bearer ... (case-insensitive)

New MaskingConfig flags were added:

• maskApiKeys (default: true when masking is enabled)
• maskBearerTokens (default: true)
• maskPasswords (default: true)
• maskGenericSecrets (default: true)

Notes:

• Masking is still disabled by default via enabled: false.
• When enabled, the default behavior is more security-focused and may mask more content than before.

Correlation ID support

New correlation utilities were added to help trace a request across services/components:

• generateCorrelationId() — generates a timestamp-random base36 ID (e.g. lq2x5k-abc123)
• CorrelatedLogger — wraps an existing Logger and prefixes every message with [correlationId]
• createCorrelatedLogger(logger, correlationId?) — convenience factory

Example:

import { createCorrelatedLogger, generateCorrelationId } from '@fjell/logging';

const correlationId = generateCorrelationId();
const logger = createCorrelatedLogger(baseLogger, correlationId);

logger.info('Processing request');
// => [<id>] Processing request

Types / interfaces

• LogEntry now includes an optional correlationId?: string field (for structured logging / middleware).
• Logger interface adds optional methods for correlation support:
  • withCorrelationId?: (id: string) => Logger
  • getCorrelationId?: () => string

Changed

Public exports

src/index.ts now exports:

• CorrelatedLogger, generateCorrelationId, createCorrelatedLogger
• LogEntry type from maskMiddleware

Documentation

• Added CHANGELOG.md.
• Updated MASKING.md to document API key/secret masking.
• Added docs/CORRELATION.md with usage patterns and best practices.
• Updated README.md to highlight masking + correlation features.

Impact / considerations

Behavior changes when masking is enabled

If you already use masking with enabled: true, you may see more aggressive masking in log output due to the new defaults. This is intentional to reduce accidental leakage of credentials.

If you need to preserve certain values (generally not recommended), you can disable specific categories:

const config = {
  enabled: true,
  maskApiKeys: false,
  maskBearerTokens: false,
  maskPasswords: true,
  maskGenericSecrets: true,
};

Potential over-masking

The Bearer token rule can mask some benign text that matches Bearer <word> (this is called out in tests as a security preference). If this is too aggressive for your environment, set maskBearerTokens: false.

Breaking changes

No explicit breaking changes were detected.

However, there are two compatibility notes:

• TypeScript consumers may notice the Logger interface now includes optional correlation methods. This should be non-breaking, but can surface in strict type checks if you have custom Logger typings.
• Masking output may change (more values replaced with ****) when masking is enabled, which can affect log-based assertions/tests and downstream parsing.

Version

• Bumped package version from 4.4.67 to 4.4.68.

@fjell/logging v4.4.67 — repository metadata update + dev config bump

Summary

This release is a maintenance/metadata update. It does not change the runtime logging API or shipped code; it updates package metadata and development tooling configuration.

Changes

• Package version bump: 4.4.66 → 4.4.67.
• Repository URL corrected/updated:
  • package.json.repository.url now points to https://github.com/fjellgrunn/logging.git (was getfjell/logging.git).
  • This improves accuracy for links shown in npm, tooling, and issue/source lookups.
• Dev tooling/config dependency update:
  • devDependencies[@fjell/common-config] bumped ^1.1.36 → ^1.1.37.
  • Corresponding package-lock.json updates to keep installs reproducible.

Impact

• Library consumers: No expected impact. No functional/logging behavior changes are included in this release.
• Contributors/maintainers: Installing dev dependencies will pick up @fjell/common-config@^1.1.37, which may affect lint/build defaults depending on what changed in that package.

Breaking changes

• None identified. No API surface or runtime dependency changes were included in this range.

Release 4.4.66: stable release bump and removal of local docs build action

Overview

This release finalizes the package from a prerelease identifier to a normal semver release and removes a repository-local composite GitHub Action that wrapped the documentation build. The two visible, related changes are:

• the package.json version field was changed from a prerelease value to the stable 4.4.66 (so registries and consumers will treat this as a stable release), and
• the .github/actions/build-docs composite action (which executed a simple docs build sequence) was deleted.

Both changes are intentional and small in scope, but they have operational implications for publishing and CI workflows. See details and recommended checks below.

Commits

• Bump package version from prerelease to stable in package.json (commit faf5fb8...) — updated version field to "4.4.66" and removed the prerelease identifier.
• Remove repository-local composite GitHub Action for building docs (commit e9212fa...) — deleted .github/actions/build-docs/action.yml, removing a composite action that ran: cd docs; npm install; npm run build.
• Existing prerelease marker commit (commit eb4f42b...) remains in history (message: "4.4.66-dev.0").

Breaking Changes

• Potential CI/workflow break: If any workflow in this repository (or external fork) referenced the removed composite action at ./.github/actions/build-docs, those workflow runs will now fail to find the action. The deleted file was a composite action that performed a docs build sequence (it contained steps to change directory to docs, run npm install, and run npm run build). (See commit e9212fa...)

  What to do:

  • Search repository workflow files for uses of ./.github/actions/build-docs and replace with an explicit job/steps block that runs the same commands, or reference a maintained action or script instead of the removed local composite action.
  • Example replacement (conceptual, based on deleted action steps): run a job step that runs cd docs && npm install && npm run build in the workflow. The exact workflow snippet to use depends on your CI matrix and runner environment.

New Features

• None. The release only contains the version bump and the action deletion as described in the commits above.

Improvements

• Release identification: The version field was changed from a prerelease value to a stable release (commit faf5fb8...). This means package consumers and registries will now treat this as the published 4.4.66 stable release rather than a dev/prerelease artifact. If your automation or dependency resolution logic filters or treats prerelease versions differently, expect different resolution behavior after this change.

Bug Fixes

• None recorded in these commits.

Developer / CI Notes

• Publishing and CI: The package.json change is limited to the top-level "version" field and is intended to mark the package as stable (commit faf5fb8...). Any CI or publish workflows that make decisions based on the presence of a prerelease identifier in package.json should be checked to confirm they behave as intended for a stable release.

• Documentation build action removal: The deleted composite action was a small wrapper around the docs build (it performed cd docs; npm install; npm run build). Removing the local composite simplifies the repository by removing an extra wrapper but moves responsibility to workflows that previously referenced it. If automated documentation builds are required in your CI, ensure those workflows have the equivalent steps directly inlined or reference an alternative action. (See commit e9212fa...)

Migration / Checklist for maintainers

• Verify CI workflows:

  • Search for any workflow referencing ./.github/actions/build-docs and update them to use an inline job or another action that performs the documentation build steps.
  • Confirm publish pipelines that previously detected a prerelease version now handle the stable 4.4.66 version as intended.

• If relying on external forks or automation that expected the prerelease tag (4.4.66-dev.0), update those systems to accept the stable 4.4.66 release instead. The prerelease commit remains in history but is no longer the package version. (See commit eb4f42b... and faf5fb8...)

References

• Commit: Bump package version from prerelease to stable in package.json — faf5fb8
• Commit: Remove repository-local composite GitHub Action for building docs — e9212fa
• Commit: 4.4.66-dev.0 (prerelease marker) — eb4f42b

If you maintain CI that previously used the removed composite action or filtered by prerelease versions, please run through the checklist above and update workflows before the next automated run.

Remove explicit package version fields; bump @fjell/common-config devDependency

Overview

This release removes explicit "version" entries from package metadata and updates a devDependency. All changes are limited to package metadata and devDependencies.

Packaging / metadata

• Remove top-level and duplicate "version" entries from package-lock.json. (commit c4d9f04 — "Remove explicit "version" fields from package-lock.json\n\n* Delete top-level "version": "4.4.65-dev.0" and "version": "4.4.65" entries from package-lock.json\n* Remove duplicate "version" entries under "packages" -> "" in package-lock.json")
• Delete "version" entries from package.json. (commit d6564d3 — "Remove version entries from package.json\n\n* Delete "version": "4.4.65-dev.0" from package.json\n* Delete "version": "4.4.65" from package.json")

Dependencies

• Bump @fjell/common-config in devDependencies from ^1.1.32 to ^1.1.36 in package.json. (commit 30e0735 — "Bump @fjell/common-config devDependency from ^1.1.32 to ^1.1.36 in package.json\n\n* Update version for @fjell/common-config in package.json devDependencies (^1.1.32 -> ^1.1.36)")

Files changed

• package.json: removed explicit "version" fields and updated @fjell/common-config devDependency version.
• package-lock.json: removed top-level and duplicate "version" entries under packages.

Notes

• The commits focus on package metadata cleanup and a devDependency update. If any tooling or release processes read the package.json "version" field, confirm they behave as expected after this change.

Release 4.4.64: package version bump and @fjell/common-config update

This release updates the package version and refreshes the pinned version information for @fjell/common-config in the repository metadata.

Summary

• Bumped the package.json version to 4.4.64 (replaced a development version string).
• Updated the @fjell/common-config dependency declaration in package.json to ^1.1.32.
• Updated package-lock.json metadata to reflect the root package and the @fjell/common-config lock entry.

Changes

• Package version

  • package.json: set the package version to 4.4.64 (commit cef88c8). Commit message: "Bump package version to 4.4.64 in package.json — Replace "version": "4.4.64-dev.0" with "version": "4.4.64" in package.json."

• Dependency declaration

  • package.json: updated dependency constraint for @fjell/common-config to ^1.1.32 (commit 0842ad0). Commit message: "Update @fjell/common-config dependency to ^1.1.32."

• package-lock.json metadata

  • package-lock.json: root package version entry was updated from 4.4.63 to 4.4.64-dev.0 (commit 7f55271). Commit message notes: "Update root package version in package-lock.json from "4.4.63" to "4.4.64-dev.0" (packages[""].version)".
  • package-lock.json: replaced the node_modules/@fjell/common-config lock entry version 1.1.31 -> 1.1.36 and updated its resolved URL and integrity fields (same commit). Commit message: "Replace node_modules/@fjell/common-config entry in package-lock.json: version 1.1.31 -> 1.1.36 and update resolved URL and integrity fields."
  • The package-lock changes were limited to the entries above; the commit message explicitly states that lockfileVersion and devDependencies were left intact.

Developer notes

• Commits included in this release:

  • cef88c8 — "Bump package version to 4.4.64 in package.json"
  • 0842ad0 — "Update @fjell/common-config dependency to ^1.1.32"
  • 7f55271 — "Bump package-lock metadata and update @fjell/common-config entry"

• Files affected (as indicated in the commit messages): package.json, package-lock.json, and the lock entry for node_modules/@fjell/common-config.

• Observed state after these commits:

  • package.json now declares version 4.4.64 (cef88c8).
  • package-lock.json contains a root entry set to 4.4.64-dev.0 and an updated lock entry for @fjell/common-config (7f55271).
  • The dependency declaration in package.json for @fjell/common-config is ^1.1.32 (0842ad0).

Breaking changes

• None flagged in the commit messages.

Notes

• The commit messages are limited to the version bump and dependency/lockfile metadata updates; no other behavioral or API changes are described in the recorded commits for this release. If additional changes are expected (for example, further dependency updates or documentation updates), they are not present in the provided commit messages.