@theholocron/logger 3.54.0 → 3.55.0

package/README.md

@@ -17,15 +17,8 @@ pnpm add @theholocron/logger
 ```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,
-});
+// Axiom credentials are picked up from the environment automatically.
+const { logger, runId } = createLogger({ level: "info" });
 
 const log = logger.child({ command: "sync-github", repo: "theholocron/configs" });
 log.info({ branch: "main" }, "opening PR");
@@ -63,11 +56,17 @@ The overloads mirror Pino: object-first for structured lines, bare string for si
 
 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. |
+| `config` field  | Type                                     | Notes                                                                   |
+| --------------- | ---------------------------------------- | ----------------------------------------------------------------------- |
+| `level`         | `"debug" \| "info" \| "warn" \| "error"` | Highest-priority level source. Optional.                                |
+| `axiom.dataset` | `string`                                 | Axiom dataset. Optional — resolved from env by default (see below).     |
+| `axiom.token`   | `string`                                 | Axiom API token. Optional — resolved from env by default. Never config. |
+
+`createLogger` reads Axiom credentials from the environment automatically when
+`config.axiom` is omitted — `HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN` +
+`HOLOCRON_AXIOM_DATASET` / `AXIOM_DATASET`, both required. The same logic is
+exported as `resolveAxiomFromEnv(env?)`. Credentials come only from env vars,
+never a config file.
 
 ### Level resolution
 
@@ -79,13 +78,13 @@ An unrecognised value at any tier is ignored and resolution falls through. The r
 
 ## 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) |
+| Environment          | Output                                        |
+| -------------------- | --------------------------------------------- |
+| Local, TTY           | `pino-pretty` — colourised, human-readable    |
+| CI (`CI` truthy)     | Newline-delimited JSON to stdout              |
+| Axiom creds resolved | 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.
+The Axiom transport is added only when credentials resolve (from `config.axiom` or the env) **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
 

package/dist/index.d.mts

@@ -71,6 +71,21 @@ declare function parseLogLevel(value: string | undefined): LogLevel | undefined;
 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;
+/**
+ * Resolve Axiom credentials from the environment — the canonical fallback
+ * chain from ADR-0007. `createLogger` calls this when no explicit
+ * `config.axiom` is supplied, so every consumer of `@theholocron/logger`
+ * gets Axiom activation from env vars alone. Credentials are read here and
+ * only here — never from a config file.
+ *
+ * Returns `undefined` unless BOTH a token and a dataset are present.
+ *
+ * | Value    | Primary                  | Fallback        |
+ * | -------- | ------------------------ | --------------- |
+ * | token    | `HOLOCRON_AXIOM_TOKEN`   | `AXIOM_TOKEN`   |
+ * | dataset  | `HOLOCRON_AXIOM_DATASET` | `AXIOM_DATASET` |
+ */
+declare function resolveAxiomFromEnv(env?: NodeJS.ProcessEnv): AxiomTransportConfig | undefined;
 //#endregion
 //#region src/redact.d.ts
 /**
@@ -96,9 +111,11 @@ interface LoggerConfig {
    */
   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 credentials. Resolved from env vars by default
+   * (`HOLOCRON_AXIOM_TOKEN` / `AXIOM_TOKEN` + `HOLOCRON_AXIOM_DATASET` /
+   * `AXIOM_DATASET`) — pass this only to override, and only from env vars,
+   * never from a config file. The transport is also skipped entirely when
+   * `HOLOCRON_TELEMETRY=false`.
    */
   axiom?: AxiomTransportConfig;
 }
@@ -125,4 +142,4 @@ interface CreateLoggerResult {
  */
 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 };
+export { type AxiomTransportConfig, CreateLoggerResult, LOG_LEVELS, type LogEnv, type LogLevel, type Logger, LoggerConfig, REDACTED_PATHS, REDACT_CENSOR, createLogger, detectEnv, generateRunId, isCI, isTelemetryDisabled, parseLogLevel, resolveAxiomFromEnv, resolveLevel };

package/dist/index.mjs

@@ -53,6 +53,28 @@ function resolveLevel(explicit, env = process.env) {
 function isTelemetryDisabled(env = process.env) {
 	return env.HOLOCRON_TELEMETRY === "false";
 }
+/**
+* Resolve Axiom credentials from the environment — the canonical fallback
+* chain from ADR-0007. `createLogger` calls this when no explicit
+* `config.axiom` is supplied, so every consumer of `@theholocron/logger`
+* gets Axiom activation from env vars alone. Credentials are read here and
+* only here — never from a config file.
+*
+* Returns `undefined` unless BOTH a token and a dataset are present.
+*
+* | Value    | Primary                  | Fallback        |
+* | -------- | ------------------------ | --------------- |
+* | token    | `HOLOCRON_AXIOM_TOKEN`   | `AXIOM_TOKEN`   |
+* | dataset  | `HOLOCRON_AXIOM_DATASET` | `AXIOM_DATASET` |
+*/
+function resolveAxiomFromEnv(env = process.env) {
+	const token = env.HOLOCRON_AXIOM_TOKEN ?? env.AXIOM_TOKEN;
+	const dataset = env.HOLOCRON_AXIOM_DATASET ?? env.AXIOM_DATASET;
+	return token && dataset ? {
+		token,
+		dataset
+	} : void 0;
+}
 //#endregion
 //#region src/redact.ts
 /**
@@ -219,7 +241,7 @@ function createLogger(config = {}) {
 	return {
 		logger: new PinoLogger(createPinoInstance({
 			level: resolveLevel(config.level),
-			axiom: config.axiom,
+			axiom: config.axiom ?? resolveAxiomFromEnv(),
 			ci: isCI(),
 			tty: Boolean(process.stdout.isTTY),
 			telemetryDisabled: isTelemetryDisabled(),
@@ -232,4 +254,4 @@ function createLogger(config = {}) {
 	};
 }
 //#endregion
-export { LOG_LEVELS, REDACTED_PATHS, REDACT_CENSOR, createLogger, detectEnv, generateRunId, isCI, isTelemetryDisabled, parseLogLevel, resolveLevel };
+export { LOG_LEVELS, REDACTED_PATHS, REDACT_CENSOR, createLogger, detectEnv, generateRunId, isCI, isTelemetryDisabled, parseLogLevel, resolveAxiomFromEnv, resolveLevel };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/logger",
-  "version": "3.54.0",
+  "version": "3.55.0",
   "description": "Structured logging for Holocron — a Pino-backed Logger adapter interface with pino-pretty, CI JSON, and Axiom transports.",
   "keywords": [
     "axiom",