@theholocron/logger 3.53.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Newton Koumantzelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# `@theholocron/logger`
+
+Structured logging for the Holocron CLI and its plugins. A `Logger` adapter interface backed by [Pino](https://getpino.io), with `pino-pretty` for local dev, plain JSON for CI, and an [Axiom](https://axiom.co) transport for log aggregation.
+
+Call sites depend on the `Logger` interface — never on Pino directly. Swapping the logging library is a one-file change.
+
+> `logger` is the operational-output channel (internal state, debug traces, errors, structured context). It is **not** `print` — the user-facing UX output surface — and does not wrap or replace it. The two are parallel concerns.
+
+## Installation
+
+```sh
+pnpm add @theholocron/logger
+```
+
+## Usage
+
+```ts
+import { createLogger } from "@theholocron/logger";
+
+const { logger, runId } = createLogger({
+  level: "info",
+  axiom: process.env.HOLOCRON_AXIOM_TOKEN
+    ? {
+        dataset: process.env.HOLOCRON_AXIOM_DATASET!,
+        token: process.env.HOLOCRON_AXIOM_TOKEN,
+      }
+    : undefined,
+});
+
+const log = logger.child({ command: "sync-github", repo: "theholocron/configs" });
+log.info({ branch: "main" }, "opening PR");
+// → { level, time, runId, env, command, repo, branch, msg: "opening PR" }
+```
+
+Pass child loggers down into modules so every line carries its context automatically:
+
+```ts
+export async function runSyncGithub(input: { logger: Logger }) {
+  const log = input.logger.child({ module: "sync-github" });
+  log.debug("resolving remote");
+}
+```
+
+## `Logger` interface
+
+```ts
+interface Logger {
+  debug(obj: Record<string, unknown>, msg?: string): void;
+  debug(msg: string): void;
+  info(obj: Record<string, unknown>, msg?: string): void;
+  info(msg: string): void;
+  warn(obj: Record<string, unknown>, msg?: string): void;
+  warn(msg: string): void;
+  error(obj: Record<string, unknown>, msg?: string): void;
+  error(msg: string): void;
+  child(bindings: Record<string, unknown>): Logger;
+}
+```
+
+The overloads mirror Pino: object-first for structured lines, bare string for simple ones.
+
+## `createLogger(config?)`
+
+Returns `{ logger, runId }`. `runId` is a UUID bound to every line the logger and its children emit — surface it via `print` when `--debug` or `--verbose` is set so a whole run can be pulled back out of Axiom.
+
+| `config` field  | Type                                     | Notes                                                      |
+| --------------- | ---------------------------------------- | ---------------------------------------------------------- |
+| `level`         | `"debug" \| "info" \| "warn" \| "error"` | Highest-priority level source. Optional.                   |
+| `axiom.dataset` | `string`                                 | Axiom dataset name. Supply from env vars only.             |
+| `axiom.token`   | `string`                                 | Axiom API token. Supply from env vars only — never config. |
+
+### Level resolution
+
+1. `config.level` — the resolved `--verbose` (`debug`) / `--quiet` (`error`) CLI flag, or `holocron.config` `log.level`, passed by the command layer
+2. `HOLOCRON_LOG_LEVEL` env var
+3. `"info"` (default)
+
+An unrecognised value at any tier is ignored and resolution falls through. The resolved level applies to **every** transport — there is no separate Axiom gate.
+
+## Transports
+
+| Environment             | Output                                        |
+| ----------------------- | --------------------------------------------- |
+| Local, TTY              | `pino-pretty` — colourised, human-readable    |
+| CI (`CI` truthy)        | Newline-delimited JSON to stdout              |
+| `config.axiom` supplied | Axiom, in a Pino worker thread (non-blocking) |
+
+The Axiom transport is added only when `config.axiom` is supplied **and** `HOLOCRON_TELEMETRY` is not `"false"`. When Axiom is the only non-console transport, console JSON is kept alongside it so CI logs stay readable.
+
+### Axiom datasets
+
+Selected by `HOLOCRON_AXIOM_DATASET` — one env var, one value per environment:
+
+| Value            | When             |
+| ---------------- | ---------------- |
+| `holocron-ci`    | CI (org secret)  |
+| `holocron-local` | local (optional) |
+
+If `HOLOCRON_AXIOM_DATASET` is unset locally, local runs write only to `pino-pretty` — no Axiom connection is attempted.
+
+## Redaction
+
+Sensitive field paths are stripped in Pino's serialisation layer, before any transport — pino-pretty, CI stdout, and Axiom alike. Redacted values become `[Redacted]`.
+
+`token`, `secret`, `password`, `apiKey`, `secrets[*].value`, `headers.authorization`, `headers["x-api-key"]`, and the same keys one level down (`*.token`, `*.secret`, …). The full list is exported as `REDACTED_PATHS`.
+
+## Development
+
+| Script               | Description             |
+| -------------------- | ----------------------- |
+| `pnpm build`         | Bundle with tsdown      |
+| `pnpm test`          | Run the vitest suite    |
+| `pnpm test:coverage` | Run tests with coverage |
+| `pnpm typecheck`     | `tsc --noEmit`          |
+| `pnpm lint`          | ESLint                  |
+
+## Releases
+
+Automated via semantic-release. See [CHANGELOG.md](../../CHANGELOG.md).
+
+## Documentation
+
+<https://theholocron.github.io/holocron/logging/>

package/dist/index.d.mts

@@ -0,0 +1,128 @@
+import "pino";
+//#region src/interface.d.ts
+/**
+ * The logging surface every Holocron command and plugin depends on.
+ *
+ * Call sites import `Logger` — never Pino directly. The concrete
+ * implementation ({@link PinoLogger}) is hidden behind this interface so the
+ * logging library can be swapped without touching a single call site.
+ *
+ * The overloads mirror Pino's native API: pass a context object first for
+ * structured logging (`log.info({ repo }, "sync complete")`) or a bare string
+ * for a simple line (`log.info("sync complete")`).
+ */
+interface Logger {
+  debug(obj: Record<string, unknown>, msg?: string): void;
+  debug(msg: string): void;
+  info(obj: Record<string, unknown>, msg?: string): void;
+  info(msg: string): void;
+  warn(obj: Record<string, unknown>, msg?: string): void;
+  warn(msg: string): void;
+  error(obj: Record<string, unknown>, msg?: string): void;
+  error(msg: string): void;
+  /**
+   * Derive a child logger that inherits every binding from its parent and
+   * adds its own. Used to attach per-module context (`module`, `repo`, …)
+   * without threading extra fields through every call.
+   */
+  child(bindings: Record<string, unknown>): Logger;
+}
+/** Log levels, ordered least to most severe. */
+type LogLevel = "debug" | "info" | "warn" | "error";
+/** The four levels, in ascending severity — useful for validation. */
+declare const LOG_LEVELS: readonly LogLevel[];
+/** Runtime environment a logger was constructed in. */
+type LogEnv = "ci" | "local";
+//#endregion
+//#region src/transports.d.ts
+/** Axiom credentials — never read from `holocron.config`, only from env vars. */
+interface AxiomTransportConfig {
+  dataset: string;
+  token: string;
+}
+//#endregion
+//#region src/context.d.ts
+/**
+ * A fresh correlation id for one command invocation. Every log line from a
+ * single `holocron` run carries this `runId`, so a whole run can be pulled
+ * back out of Axiom with one query.
+ */
+declare function generateRunId(): string;
+/**
+ * True when running inside CI. GitHub Actions (and most other providers) set
+ * `CI=true`; we also accept any other non-empty, non-`false` value.
+ */
+declare function isCI(env?: NodeJS.ProcessEnv): boolean;
+/** `"ci"` inside CI, otherwise `"local"` — bound on every root logger. */
+declare function detectEnv(env?: NodeJS.ProcessEnv): LogEnv;
+/** Narrow an arbitrary string to a {@link LogLevel}, or `undefined`. */
+declare function parseLogLevel(value: string | undefined): LogLevel | undefined;
+/**
+ * Resolve the effective log level in priority order:
+ *
+ * 1. `explicit` — already-resolved CLI flag (`--verbose` → `debug`,
+ *    `--quiet` → `error`) or `holocron.config` `log.level`, passed by the
+ *    command layer.
+ * 2. `HOLOCRON_LOG_LEVEL` env var.
+ * 3. `"info"` default.
+ *
+ * An unrecognised value at any tier is ignored and resolution falls through.
+ */
+declare function resolveLevel(explicit?: LogLevel, env?: NodeJS.ProcessEnv): LogLevel;
+/** True when the Axiom transport must be suppressed via `HOLOCRON_TELEMETRY=false`. */
+declare function isTelemetryDisabled(env?: NodeJS.ProcessEnv): boolean;
+//#endregion
+//#region src/redact.d.ts
+/**
+ * Sensitive field paths stripped from every log line before any transport —
+ * pino-pretty, CI stdout, and Axiom alike. Redaction happens in Pino's
+ * serialisation layer, so a raw token never leaves the process.
+ *
+ * Paths use Pino's redaction syntax: dotted access, `[*]` wildcards for
+ * arrays, and bracket-quoted keys for names that are not valid identifiers.
+ *
+ * @see https://getpino.io/#/docs/redaction
+ */
+declare const REDACTED_PATHS: readonly string[];
+/** Replacement string Pino writes in place of a redacted value. */
+declare const REDACT_CENSOR = "[Redacted]";
+//#endregion
+//#region src/index.d.ts
+interface LoggerConfig {
+  /**
+   * Explicit level — the highest-priority source. The command layer passes
+   * the resolved `--verbose` / `--quiet` flag or `holocron.config`
+   * `log.level` here. Falls through to `HOLOCRON_LOG_LEVEL`, then `"info"`.
+   */
+  level?: LogLevel;
+  /**
+   * Axiom credentials. Supply only from env vars (`HOLOCRON_AXIOM_TOKEN` /
+   * `HOLOCRON_AXIOM_DATASET`) — never from config files. Omit to skip the
+   * Axiom transport. Also skipped when `HOLOCRON_TELEMETRY=false`.
+   */
+  axiom?: AxiomTransportConfig;
+}
+interface CreateLoggerResult {
+  /** The logger to thread through commands and modules via `child()`. */
+  logger: Logger;
+  /**
+   * Correlation id bound to every line this logger (and its children) emit.
+   * Surface it to the user via `print` when `--debug` or `--verbose` is set
+   * so they can pull the run out of Axiom.
+   */
+  runId: string;
+}
+/**
+ * The single entry point for building a logger. Generates a `runId`, detects
+ * the environment, resolves the level, wires the right transports, and
+ * returns a ready {@link Logger}.
+ *
+ * ```ts
+ * const { logger, runId } = createLogger({ level, axiom });
+ * const log = logger.child({ command: "sync-github", repo });
+ * log.info({ branch }, "opening PR");
+ * ```
+ */
+declare function createLogger(config?: LoggerConfig): CreateLoggerResult;
+//#endregion
+export { type AxiomTransportConfig, CreateLoggerResult, LOG_LEVELS, type LogEnv, type LogLevel, type Logger, LoggerConfig, REDACTED_PATHS, REDACT_CENSOR, createLogger, detectEnv, generateRunId, isCI, isTelemetryDisabled, parseLogLevel, resolveLevel };

package/dist/index.mjs

@@ -0,0 +1,235 @@
+import { randomUUID } from "node:crypto";
+import pino from "pino";
+//#region src/interface.ts
+/** The four levels, in ascending severity — useful for validation. */
+const LOG_LEVELS = [
+	"debug",
+	"info",
+	"warn",
+	"error"
+];
+//#endregion
+//#region src/context.ts
+/**
+* A fresh correlation id for one command invocation. Every log line from a
+* single `holocron` run carries this `runId`, so a whole run can be pulled
+* back out of Axiom with one query.
+*/
+function generateRunId() {
+	return randomUUID();
+}
+/**
+* True when running inside CI. GitHub Actions (and most other providers) set
+* `CI=true`; we also accept any other non-empty, non-`false` value.
+*/
+function isCI(env = process.env) {
+	const ci = env.CI;
+	if (!ci) return false;
+	return ci !== "false" && ci !== "0";
+}
+/** `"ci"` inside CI, otherwise `"local"` — bound on every root logger. */
+function detectEnv(env = process.env) {
+	return isCI(env) ? "ci" : "local";
+}
+/** Narrow an arbitrary string to a {@link LogLevel}, or `undefined`. */
+function parseLogLevel(value) {
+	return value && LOG_LEVELS.includes(value) ? value : void 0;
+}
+/**
+* Resolve the effective log level in priority order:
+*
+* 1. `explicit` — already-resolved CLI flag (`--verbose` → `debug`,
+*    `--quiet` → `error`) or `holocron.config` `log.level`, passed by the
+*    command layer.
+* 2. `HOLOCRON_LOG_LEVEL` env var.
+* 3. `"info"` default.
+*
+* An unrecognised value at any tier is ignored and resolution falls through.
+*/
+function resolveLevel(explicit, env = process.env) {
+	return explicit ?? parseLogLevel(env.HOLOCRON_LOG_LEVEL) ?? "info";
+}
+/** True when the Axiom transport must be suppressed via `HOLOCRON_TELEMETRY=false`. */
+function isTelemetryDisabled(env = process.env) {
+	return env.HOLOCRON_TELEMETRY === "false";
+}
+//#endregion
+//#region src/redact.ts
+/**
+* Sensitive field paths stripped from every log line before any transport —
+* pino-pretty, CI stdout, and Axiom alike. Redaction happens in Pino's
+* serialisation layer, so a raw token never leaves the process.
+*
+* Paths use Pino's redaction syntax: dotted access, `[*]` wildcards for
+* arrays, and bracket-quoted keys for names that are not valid identifiers.
+*
+* @see https://getpino.io/#/docs/redaction
+*/
+const REDACTED_PATHS = [
+	"token",
+	"secret",
+	"password",
+	"apiKey",
+	"secrets[*].value",
+	"headers.authorization",
+	"headers[\"x-api-key\"]",
+	"*.token",
+	"*.secret",
+	"*.password",
+	"*.apiKey"
+];
+/** Replacement string Pino writes in place of a redacted value. */
+const REDACT_CENSOR = "[Redacted]";
+/** Ready-to-use Pino `redact` option. */
+const redactOptions = {
+	paths: [...REDACTED_PATHS],
+	censor: REDACT_CENSOR
+};
+//#endregion
+//#region src/transports.ts
+const prettyTarget = (level) => ({
+	target: "pino-pretty",
+	level,
+	options: {
+		colorize: true,
+		translateTime: "SYS:HH:MM:ss",
+		ignore: "pid,hostname"
+	}
+});
+const stdoutJsonTarget = (level) => ({
+	target: "pino/file",
+	level,
+	options: { destination: 1 }
+});
+const axiomTarget = (level, axiom) => ({
+	target: "@axiomhq/pino",
+	level,
+	options: {
+		dataset: axiom.dataset,
+		token: axiom.token
+	}
+});
+/**
+* Build the Pino `transport` option for the current environment.
+*
+* | Environment                | Output                                              |
+* | -------------------------- | --------------------------------------------------- |
+* | Local, TTY, no Axiom       | `pino-pretty` only                                  |
+* | CI, no Axiom               | `undefined` — Pino's default NDJSON to stdout       |
+* | Local, TTY, with Axiom     | `pino-pretty` + Axiom                               |
+* | CI, with Axiom             | NDJSON to stdout + Axiom                            |
+*
+* The Axiom transport is dropped entirely when `telemetryDisabled` is set,
+* regardless of whether credentials were supplied. Every transport runs on
+* the same resolved `level` — there is no Axiom-only gate.
+*
+* Returning `undefined` lets `createLogger` fall back to a plain
+* `pino({ ... })` with no worker thread — the cheapest path, and exactly
+* what CI wants.
+*/
+function buildTransport(input) {
+	const { level, axiom, ci, tty, telemetryDisabled } = input;
+	const pretty = !ci && tty;
+	const targets = [];
+	if (pretty) targets.push(prettyTarget(level));
+	if (axiom && !telemetryDisabled) targets.push(axiomTarget(level, axiom));
+	if (targets.length === 0) return void 0;
+	if (!pretty) targets.unshift(stdoutJsonTarget(level));
+	if (targets.length === 1) return targets[0];
+	return { targets };
+}
+//#endregion
+//#region src/pino.ts
+/**
+* The one concrete {@link Logger}. Nothing outside this package should name
+* it — construct loggers with `createLogger`. It is a thin pass-through to a
+* Pino instance; the interface overloads mirror Pino's own, so each method is
+* a single delegated call.
+*/
+var PinoLogger = class PinoLogger {
+	#pino;
+	constructor(instance) {
+		this.#pino = instance;
+	}
+	debug(objOrMsg, msg) {
+		this.#emit("debug", objOrMsg, msg);
+	}
+	info(objOrMsg, msg) {
+		this.#emit("info", objOrMsg, msg);
+	}
+	warn(objOrMsg, msg) {
+		this.#emit("warn", objOrMsg, msg);
+	}
+	error(objOrMsg, msg) {
+		this.#emit("error", objOrMsg, msg);
+	}
+	child(bindings) {
+		return new PinoLogger(this.#pino.child(bindings));
+	}
+	#emit(level, objOrMsg, msg) {
+		if (typeof objOrMsg === "string") this.#pino[level](objOrMsg);
+		else this.#pino[level](objOrMsg, msg);
+	}
+};
+/**
+* Assemble the Pino `LoggerOptions`: resolved level, `runId` / `env` on every
+* line, ISO timestamps, sensitive-field redaction, and — unless a capture
+* `destination` is in play — the environment-appropriate transport from
+* {@link buildTransport}.
+*/
+function buildPinoOptions(input) {
+	const options = {
+		level: input.level,
+		base: input.base,
+		timestamp: pino.stdTimeFunctions.isoTime,
+		redact: {
+			paths: [...redactOptions.paths],
+			censor: redactOptions.censor
+		}
+	};
+	if (input.destination) return options;
+	const transport = buildTransport(input);
+	if (transport) options.transport = transport;
+	return options;
+}
+/**
+* Construct the underlying Pino instance. Writes to `destination` when one is
+* supplied (tests), otherwise to the transports {@link buildPinoOptions} wired.
+*/
+function createPinoInstance(input) {
+	const options = buildPinoOptions(input);
+	return input.destination ? pino(options, input.destination) : pino(options);
+}
+//#endregion
+//#region src/index.ts
+/**
+* The single entry point for building a logger. Generates a `runId`, detects
+* the environment, resolves the level, wires the right transports, and
+* returns a ready {@link Logger}.
+*
+* ```ts
+* const { logger, runId } = createLogger({ level, axiom });
+* const log = logger.child({ command: "sync-github", repo });
+* log.info({ branch }, "opening PR");
+* ```
+*/
+function createLogger(config = {}) {
+	const runId = generateRunId();
+	const env = detectEnv();
+	return {
+		logger: new PinoLogger(createPinoInstance({
+			level: resolveLevel(config.level),
+			axiom: config.axiom,
+			ci: isCI(),
+			tty: Boolean(process.stdout.isTTY),
+			telemetryDisabled: isTelemetryDisabled(),
+			base: {
+				runId,
+				env
+			}
+		})),
+		runId
+	};
+}
+//#endregion
+export { LOG_LEVELS, REDACTED_PATHS, REDACT_CENSOR, createLogger, detectEnv, generateRunId, isCI, isTelemetryDisabled, parseLogLevel, resolveLevel };

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@theholocron/logger",
+  "version": "3.53.0",
+  "description": "Structured logging for Holocron — a Pino-backed Logger adapter interface with pino-pretty, CI JSON, and Axiom transports.",
+  "keywords": [
+    "axiom",
+    "holocron",
+    "logging",
+    "logger",
+    "pino",
+    "structured-logging",
+    "theholocron"
+  ],
+  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/logger#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/logger"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@axiomhq/pino": "^2.0.0",
+    "pino": "^10.3.1",
+    "pino-pretty": "^13.1.3"
+  },
+  "devDependencies": {
+    "@theholocron/eslint-config": "^7.32.1",
+    "@theholocron/tsconfig": "^7.32.1",
+    "@theholocron/tsdown-config": "^7.32.1",
+    "@theholocron/vitest-config": "^7.32.1",
+    "@types/node": "^26",
+    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/eslint-plugin": "^1.6.27",
+    "eslint": "^10.8.1",
+    "eslint-plugin-n": "^18.3.0",
+    "globals": "^17.11.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.11"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
+}