@kici-dev/shared 0.1.3 → 0.1.5

package/dist/idempotency-files.d.ts

@@ -29,6 +29,16 @@
  */
 export type FileChangeCategory = 'new' | 'content' | 'mode' | 'time-only';
 export type ContentSkipReason = 'binary' | 'too-large' | 'read-failed' | 'sensitive';
+/**
+ * Renderer hint for the diff body. The default `'unified-text'` produces
+ * a `createTwoFilesPatch`-style block (the v1 shape). `'env-semantic'`
+ * routes through the env-file diff renderer (keys + classification, with
+ * value masking by default). `'yaml-semantic'` routes through the yaml
+ * deep-diff renderer (dotted-path leaf entries, with masking on sensitive
+ * paths). `'suppressed'` hides the body and prints a skip-reason marker —
+ * used for genuinely-opaque content the caller refuses to capture.
+ */
+export type FileDiffMode = 'unified-text' | 'env-semantic' | 'yaml-semantic' | 'suppressed';
 /**
  * Per-file drift entry as carried inside a phase's Drift value.
  * `localPath` and `remotePath` are filled in by the caller that owns the
@@ -53,7 +63,23 @@ export interface FileDriftEntry {
     remoteContent?: string;
     /** Set when content capture was intentionally skipped — used by the renderer to explain the gap. */
     contentSkipped?: ContentSkipReason;
+    /**
+     * Renderer hint. When omitted, the renderer auto-detects from
+     * `remotePath`: `.env` → `'env-semantic'`, `.yaml` / `.yml` →
+     * `'yaml-semantic'`, otherwise → `'unified-text'`. Explicit values
+     * override the auto-detect. Set to `'suppressed'` to opt out of any
+     * inline body and rely on `contentSkipped` for the explanation row.
+     */
+    diffMode?: FileDiffMode;
 }
+/**
+ * Auto-detect the diff mode for a given entry. Explicit `entry.diffMode`
+ * always wins. Otherwise the suffix of `remotePath` is the only signal —
+ * we deliberately do NOT sniff `localContent` bytes because the goal of
+ * the helper is to produce a deterministic, callsite-readable hint that
+ * matches the caller's intent.
+ */
+export declare function resolveDiffMode(entry: FileDriftEntry): FileDiffMode;
 /** Low-level parse output: category + the relative path rsync printed. */
 export interface ItemizeRecord {
     itemizeCode: string;
@@ -80,6 +106,21 @@ export interface RenderDriftOpts {
     color?: boolean;
     /** Cap on diff body lines per entry (excluding header). Default 200. */
     maxLines?: number;
+    /**
+     * When true, env-semantic and yaml-semantic renderers will print the
+     * actual values instead of masking them. Off by default so the confirm
+     * prompt and the tee'd log file never carry plaintext credentials
+     * without an explicit operator opt-in.
+     */
+    revealEnvValues?: boolean;
+    /**
+     * Restrict which categories get a diff body rendered. Entries whose
+     * category is NOT in this set show only the per-file row, no diff.
+     * Default: `['new', 'content']` (every visible drift body). Useful for
+     * `--diff-only=content` operator workflows that want to suppress the
+     * potentially-huge full-file body of newly-introduced files.
+     */
+    diffOnlyCategories?: FileChangeCategory[];
 }
 /**
  * Render the unified-diff block for a single FileDriftEntry. Returns an
@@ -92,8 +133,37 @@ export interface RenderDriftOpts {
  * skip reason. Entries with no content captured (older callers that
  * didn't fill the fields) also return empty — the caller falls back to
  * the label-only row.
+ *
+ * This function ALWAYS renders the unified-text shape regardless of the
+ * entry's `diffMode` — it's the v1 path. The renderer dispatch in
+ * `renderFileDrifts` decides which shape to invoke per entry; this
+ * helper stays the unified-text branch for callers that want to render
+ * a single entry in unified shape.
  */
 export declare function renderFileDriftWithDiff(entry: FileDriftEntry, opts?: Pick<RenderDriftOpts, 'color' | 'maxLines'>): string[];
+/**
+ * Dispatch helper: given a single entry and the render opts, pick the
+ * right renderer based on `resolveDiffMode(entry)`. Returns the diff body
+ * lines (no surrounding indent applied) — same shape as
+ * `renderFileDriftWithDiff` so the caller can nest each line identically
+ * regardless of which renderer fired.
+ *
+ * The placeholder `yaml-semantic` branch deliberately falls back to the
+ * unified-text rendering when this entry hasn't been routed through a
+ * yaml-aware caller. The dedicated `renderYamlDiff` lives in
+ * `idempotency-yaml-diff.ts`; the dispatch wire-up happens here once it's
+ * imported.
+ */
+export declare function renderFileDriftBody(entry: FileDriftEntry, opts?: RenderDriftOpts): string[];
+/**
+ * Yaml renderer registration. The yaml module (`idempotency-yaml-diff.ts`)
+ * calls `setYamlDiffRenderer` at its own load time so the file-drift
+ * renderer can dispatch to it without taking a static dependency on the
+ * `yaml` npm package. Callers that never import the yaml module fall
+ * through to unified-text rendering, which is the safe default.
+ */
+type YamlDiffRenderer = (entry: FileDriftEntry, opts: RenderDriftOpts) => string[];
+export declare function setYamlDiffRenderer(renderer: YamlDiffRenderer | null): void;
 /**
  * Render a FileDriftEntry[] as an aligned multi-line block suitable for
  * inclusion in a confirm-prompt summary.
@@ -110,4 +180,5 @@ export declare function renderFileDriftWithDiff(entry: FileDriftEntry, opts?: Pi
  * decides how to nest the block in a wider prompt.
  */
 export declare function renderFileDrifts(entries: FileDriftEntry[], opts?: RenderDriftOpts): string[];
+export {};
 //# sourceMappingURL=idempotency-files.d.ts.map

package/dist/idempotency-files.js

@@ -1,4 +1,5 @@
 import "./chunk-gOLHoazu.js";
+import { diffEnvFiles, renderEnvDiff } from "./idempotency-env-diff.js";
 import { createTwoFilesPatch } from "diff";
 //#region src/idempotency-files.ts
 /**
@@ -36,6 +37,20 @@ const ANSI_CYAN = "\x1B[36m";
 const ANSI_BOLD = "\x1B[1m";
 const ANSI_RESET = "\x1B[0m";
 /**
+* Auto-detect the diff mode for a given entry. Explicit `entry.diffMode`
+* always wins. Otherwise the suffix of `remotePath` is the only signal —
+* we deliberately do NOT sniff `localContent` bytes because the goal of
+* the helper is to produce a deterministic, callsite-readable hint that
+* matches the caller's intent.
+*/
+function resolveDiffMode(entry) {
+	if (entry.diffMode) return entry.diffMode;
+	const remote = entry.remotePath.toLowerCase();
+	if (remote.endsWith(".env")) return "env-semantic";
+	if (remote.endsWith(".yaml") || remote.endsWith(".yml")) return "yaml-semantic";
+	return "unified-text";
+}
+/**
 * Parse one line of `rsync --itemize-changes` output. Returns null for
 * lines that are not actionable file drift entries:
 *   - "sending incremental file list" header line
@@ -118,6 +133,12 @@ const SKIP_REASON_DISPLAY = {
 * skip reason. Entries with no content captured (older callers that
 * didn't fill the fields) also return empty — the caller falls back to
 * the label-only row.
+*
+* This function ALWAYS renders the unified-text shape regardless of the
+* entry's `diffMode` — it's the v1 path. The renderer dispatch in
+* `renderFileDrifts` decides which shape to invoke per entry; this
+* helper stays the unified-text branch for callers that want to render
+* a single entry in unified shape.
 */
 function renderFileDriftWithDiff(entry, opts = {}) {
 	if (entry.category === "mode" || entry.category === "time-only") return [];
@@ -135,6 +156,54 @@ function renderFileDriftWithDiff(entry, opts = {}) {
 	if (truncated) lines.push(`… (${body.length - maxLines} more lines truncated; raw patch in log file)`);
 	return lines;
 }
+/**
+* Dispatch helper: given a single entry and the render opts, pick the
+* right renderer based on `resolveDiffMode(entry)`. Returns the diff body
+* lines (no surrounding indent applied) — same shape as
+* `renderFileDriftWithDiff` so the caller can nest each line identically
+* regardless of which renderer fired.
+*
+* The placeholder `yaml-semantic` branch deliberately falls back to the
+* unified-text rendering when this entry hasn't been routed through a
+* yaml-aware caller. The dedicated `renderYamlDiff` lives in
+* `idempotency-yaml-diff.ts`; the dispatch wire-up happens here once it's
+* imported.
+*/
+function renderFileDriftBody(entry, opts = {}) {
+	if (entry.category === "mode" || entry.category === "time-only") return [];
+	const mode = resolveDiffMode(entry);
+	if (mode === "suppressed") return [SKIP_REASON_DISPLAY[entry.contentSkipped ?? "sensitive"]];
+	if (entry.contentSkipped) return [SKIP_REASON_DISPLAY[entry.contentSkipped]];
+	if (mode === "env-semantic") return renderEnvDiffBody(entry, opts);
+	if (mode === "yaml-semantic") {
+		if (yamlDiffRenderer) return yamlDiffRenderer(entry, opts);
+	}
+	return renderFileDriftWithDiff(entry, {
+		color: opts.color,
+		maxLines: opts.maxLines
+	});
+}
+/**
+* Bridge between the env-diff module and the file-drift renderer. Reads
+* `localContent` + `remoteContent` from the entry and delegates to
+* `diffEnvFiles` + `renderEnvDiff` from `idempotency-env-diff.ts`.
+*
+* NEW entries (no `remoteContent`) treat the remote side as an empty file
+* — every local key becomes an `added` entry.
+*/
+function renderEnvDiffBody(entry, opts) {
+	const local = entry.localContent ?? "";
+	const remote = entry.category === "new" ? "" : entry.remoteContent ?? "";
+	if (local === "" && remote === "" && entry.category !== "new") return [];
+	return renderEnvDiff(diffEnvFiles(local, remote), {
+		reveal: opts.revealEnvValues ?? false,
+		color: opts.color ?? false
+	});
+}
+let yamlDiffRenderer = null;
+function setYamlDiffRenderer(renderer) {
+	yamlDiffRenderer = renderer;
+}
 function colorize(line, color) {
 	if (!color) return line;
 	if (line.startsWith("+++") || line.startsWith("---")) return `${ANSI_BOLD}${line}${ANSI_RESET}`;
@@ -170,21 +239,19 @@ function renderFileDrifts(entries, opts = {}) {
 		if (ai !== bi) return ai - bi;
 		return a.localPath.localeCompare(b.localPath);
 	});
+	const diffOnly = new Set(opts.diffOnlyCategories ?? ["new", "content"]);
 	const lines = [`${entries.length} file(s) drifted: ${summary}`];
 	for (const e of sorted) {
 		const label = CATEGORY_DISPLAY[e.category].padEnd(widest);
 		lines.push(`  ${label}  ${e.localPath}`);
-		if (opts.withContent) {
-			const diff = renderFileDriftWithDiff(e, {
-				color: opts.color,
-				maxLines: opts.maxLines
-			});
+		if (opts.withContent && diffOnly.has(e.category)) {
+			const diff = renderFileDriftBody(e, opts);
 			for (const dl of diff) lines.push(`      ${dl}`);
 		}
 	}
 	return lines;
 }
 //#endregion
-export { parseItemizeLine, renderFileDriftWithDiff, renderFileDrifts };
+export { parseItemizeLine, renderFileDriftBody, renderFileDriftWithDiff, renderFileDrifts, resolveDiffMode, setYamlDiffRenderer };
 
 //# sourceMappingURL=idempotency-files.js.map

package/dist/idempotency-yaml-diff.d.ts

@@ -0,0 +1,74 @@
+/**
+ * YAML-file semantic diff for the idempotent-step preview path. Parses
+ * both sides with the `yaml` npm package, deep-walks the resulting JS
+ * trees, and emits one `YamlDiffEntry` per leaf-level path that differs.
+ *
+ * "Leaf" means the smallest scalar inside the tree: a string, number,
+ * boolean, or null. Arrays compare element-by-element by index; objects
+ * recurse into their fields. The dotted path follows the JS-property
+ * convention (`Database.postgres.User.Password`, `clients[2].name`).
+ *
+ * The renderer masks every entry whose path contains a sensitive
+ * segment (`/password|passwd|secret|api[_-]?key|token|credentials?/i`)
+ * unless the operator passes `reveal: true` via the
+ * `--reveal-env-values` CLI flag. Non-sensitive entries print their
+ * values inline so the operator can see config drift at a glance.
+ */
+export type YamlDiffKind = 'added' | 'removed' | 'changed';
+export interface YamlDiffEntry {
+    /** Dotted path to the leaf, e.g. "Database.postgres.User.Password" or "auth.clients[0].secret". */
+    path: string;
+    kind: YamlDiffKind;
+    /** Populated for `changed` / `removed`. Scalar leaf value. */
+    oldValue?: unknown;
+    /** Populated for `added` / `changed`. Scalar leaf value. */
+    newValue?: unknown;
+    /** True when any segment in `path` matches the sensitive-keyword heuristic. */
+    sensitive: boolean;
+}
+/**
+ * Returns true when any segment of the dotted path matches the
+ * sensitive-keyword heuristic. Numeric array indices (`[0]`) are
+ * stripped before the match so a path like `clients[3].token` still
+ * matches via the `token` segment.
+ */
+export declare function isPathSensitive(dottedPath: string): boolean;
+/**
+ * Deep-diff two YAML bodies. Both sides are parsed with the `yaml`
+ * package, then a recursive walk emits one entry per leaf that differs.
+ * Returns an empty array when the documents are structurally equivalent.
+ *
+ * Throws when either side fails to parse — the caller (the renderer
+ * dispatch) catches and falls back to unified-text rendering on a parse
+ * failure so a stray template tag in a yaml-by-suffix file doesn't lose
+ * the operator's diff.
+ */
+export declare function diffYamlContent(local: string, remote: string): YamlDiffEntry[];
+export interface YamlDiffRenderOpts {
+    /** When true, sensitive paths show their values inline; otherwise masked. */
+    reveal?: boolean;
+    /** When true, color the kind label + values via ANSI escapes. */
+    color?: boolean;
+}
+/**
+ * Render the yaml-semantic diff body. Returns one entry's worth of
+ * lines per `YamlDiffEntry`, plus an empty-state fallback line when
+ * there's nothing to show. No surrounding indent applied — the caller
+ * decides nesting.
+ *
+ * Layout:
+ *
+ *   Database.postgres.User.Password: changed (masked — pass --reveal-env-values to show)
+ *   server.listen: changed
+ *     - old=80
+ *     + new=8080
+ *   features.beta: added
+ *     + new=true
+ *
+ * The CLI flag is named `--reveal-env-values` because the same flag
+ * governs env-semantic + yaml-semantic value reveals; calling the flag
+ * "env-values" reflects the most common case (sops-derived env files)
+ * but it activates yaml-side reveal too.
+ */
+export declare function renderYamlDiff(entries: YamlDiffEntry[], opts?: YamlDiffRenderOpts): string[];
+//# sourceMappingURL=idempotency-yaml-diff.d.ts.map

package/dist/idempotency-yaml-diff.js

@@ -0,0 +1,241 @@
+import "./chunk-gOLHoazu.js";
+import { setYamlDiffRenderer } from "./idempotency-files.js";
+import { parse } from "yaml";
+//#region src/idempotency-yaml-diff.ts
+/**
+* YAML-file semantic diff for the idempotent-step preview path. Parses
+* both sides with the `yaml` npm package, deep-walks the resulting JS
+* trees, and emits one `YamlDiffEntry` per leaf-level path that differs.
+*
+* "Leaf" means the smallest scalar inside the tree: a string, number,
+* boolean, or null. Arrays compare element-by-element by index; objects
+* recurse into their fields. The dotted path follows the JS-property
+* convention (`Database.postgres.User.Password`, `clients[2].name`).
+*
+* The renderer masks every entry whose path contains a sensitive
+* segment (`/password|passwd|secret|api[_-]?key|token|credentials?/i`)
+* unless the operator passes `reveal: true` via the
+* `--reveal-env-values` CLI flag. Non-sensitive entries print their
+* values inline so the operator can see config drift at a glance.
+*/
+const ANSI_RED = "\x1B[31m";
+const ANSI_GREEN = "\x1B[32m";
+const ANSI_CYAN = "\x1B[36m";
+const ANSI_RESET = "\x1B[0m";
+const SENSITIVE_SEGMENT_RE = /^(password|passwd|secret|secrets|api[_-]?key|token|credentials?)$/i;
+/**
+* Returns true when any segment of the dotted path matches the
+* sensitive-keyword heuristic. Numeric array indices (`[0]`) are
+* stripped before the match so a path like `clients[3].token` still
+* matches via the `token` segment.
+*/
+function isPathSensitive(dottedPath) {
+	return dottedPath.split(/[.[\]]+/).filter((s) => s !== "").filter((s) => !/^\d+$/.test(s)).some((s) => SENSITIVE_SEGMENT_RE.test(s));
+}
+/**
+* Deep-diff two YAML bodies. Both sides are parsed with the `yaml`
+* package, then a recursive walk emits one entry per leaf that differs.
+* Returns an empty array when the documents are structurally equivalent.
+*
+* Throws when either side fails to parse — the caller (the renderer
+* dispatch) catches and falls back to unified-text rendering on a parse
+* failure so a stray template tag in a yaml-by-suffix file doesn't lose
+* the operator's diff.
+*/
+function diffYamlContent(local, remote) {
+	const localTree = local === "" ? void 0 : parse(local);
+	const remoteTree = remote === "" ? void 0 : parse(remote);
+	const entries = [];
+	walkDiff("", localTree, remoteTree, entries);
+	entries.sort((a, b) => {
+		if (a.kind !== b.kind) {
+			const ORDER = {
+				added: 0,
+				changed: 1,
+				removed: 2
+			};
+			return ORDER[a.kind] - ORDER[b.kind];
+		}
+		return a.path.localeCompare(b.path);
+	});
+	return entries;
+}
+/**
+* Recursive walk over `local` and `remote`. For each pair of values at
+* `path`:
+*   - Both undefined → emit nothing (key missing in both).
+*   - Only local defined → recurse / emit `added`.
+*   - Only remote defined → recurse / emit `removed`.
+*   - Both defined, structurally compatible (both objects / both arrays)
+*     → recurse into children.
+*   - Both defined, scalar or shape-mismatched → emit `changed`.
+*/
+function walkDiff(path, local, remote, out) {
+	const lDefined = local !== void 0;
+	const rDefined = remote !== void 0;
+	if (!lDefined && !rDefined) return;
+	if (lDefined && !rDefined) {
+		emitLeafOrTree(path, local, "added", out);
+		return;
+	}
+	if (!lDefined && rDefined) {
+		emitLeafOrTree(path, remote, "removed", out);
+		return;
+	}
+	const lObj = isPlainObject(local);
+	const rObj = isPlainObject(remote);
+	const lArr = Array.isArray(local);
+	const rArr = Array.isArray(remote);
+	if (lObj && rObj) {
+		const lRec = local;
+		const rRec = remote;
+		const keys = new Set([...Object.keys(lRec), ...Object.keys(rRec)]);
+		for (const key of keys) walkDiff(path === "" ? key : `${path}.${key}`, lRec[key], rRec[key], out);
+		return;
+	}
+	if (lArr && rArr) {
+		const lArrTyped = local;
+		const rArrTyped = remote;
+		const len = Math.max(lArrTyped.length, rArrTyped.length);
+		for (let i = 0; i < len; i++) walkDiff(`${path}[${i}]`, lArrTyped[i], rArrTyped[i], out);
+		return;
+	}
+	if (deepEqual(local, remote)) return;
+	out.push({
+		path,
+		kind: "changed",
+		oldValue: remote,
+		newValue: local,
+		sensitive: isPathSensitive(path)
+	});
+}
+/**
+* When a whole subtree is added or removed, we collapse it into a
+* single entry rather than emitting one per descendant leaf. The
+* value is the entire subtree; the renderer prints it inline (masked
+* when the path is sensitive) or via a JSON one-liner.
+*/
+function emitLeafOrTree(path, value, kind, out) {
+	const reportedPath = path === "" ? "<root>" : path;
+	if (kind === "added") out.push({
+		path: reportedPath,
+		kind,
+		newValue: value,
+		sensitive: isPathSensitive(path)
+	});
+	else out.push({
+		path: reportedPath,
+		kind,
+		oldValue: value,
+		sensitive: isPathSensitive(path)
+	});
+}
+function isPlainObject(value) {
+	if (value === null || typeof value !== "object") return false;
+	if (Array.isArray(value)) return false;
+	const proto = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* Cheap structural equality check. Only used as a tie-breaker for the
+* "neither object nor array" branch — scalar leaves go through
+* `===` after a JSON-stringify-equiv comparison. Functions / Dates /
+* other class instances fall back to `Object.is`, which is fine
+* because the `yaml` package only emits plain values for the tag set
+* we use (scalar, sequence, mapping).
+*/
+function deepEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+/**
+* Render the yaml-semantic diff body. Returns one entry's worth of
+* lines per `YamlDiffEntry`, plus an empty-state fallback line when
+* there's nothing to show. No surrounding indent applied — the caller
+* decides nesting.
+*
+* Layout:
+*
+*   Database.postgres.User.Password: changed (masked — pass --reveal-env-values to show)
+*   server.listen: changed
+*     - old=80
+*     + new=8080
+*   features.beta: added
+*     + new=true
+*
+* The CLI flag is named `--reveal-env-values` because the same flag
+* governs env-semantic + yaml-semantic value reveals; calling the flag
+* "env-values" reflects the most common case (sops-derived env files)
+* but it activates yaml-side reveal too.
+*/
+function renderYamlDiff(entries, opts = {}) {
+	const reveal = opts.reveal ?? false;
+	const color = opts.color ?? false;
+	if (entries.length === 0) return ["0 yaml leaf(s) drifted (structure matches)"];
+	const lines = [];
+	for (const entry of entries) {
+		const mask = entry.sensitive && !reveal;
+		const headTail = mask ? " (masked — pass --reveal-env-values to show)" : "";
+		lines.push(`${entry.path}: ${colorizeKind(entry.kind, color)}${headTail}`);
+		if (mask) continue;
+		if (entry.kind === "changed" || entry.kind === "removed") lines.push(`  ${colorize("- old=" + formatValue(entry.oldValue), "old", color)}`);
+		if (entry.kind === "changed" || entry.kind === "added") lines.push(`  ${colorize("+ new=" + formatValue(entry.newValue), "new", color)}`);
+	}
+	return lines;
+}
+function formatValue(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	try {
+		const json = JSON.stringify(value);
+		if (json.length <= 240) return json;
+		return json.slice(0, 240) + `… (${json.length - 240} more bytes)`;
+	} catch {
+		return String(value);
+	}
+}
+function colorizeKind(kind, color) {
+	if (!color) return kind;
+	switch (kind) {
+		case "added": return `${ANSI_GREEN}${kind}${ANSI_RESET}`;
+		case "removed": return `${ANSI_RED}${kind}${ANSI_RESET}`;
+		case "changed": return `${ANSI_CYAN}${kind}${ANSI_RESET}`;
+	}
+}
+function colorize(text, side, color) {
+	if (!color) return text;
+	return side === "new" ? `${ANSI_GREEN}${text}${ANSI_RESET}` : `${ANSI_RED}${text}${ANSI_RESET}`;
+}
+/**
+* Bridge between the FileDriftEntry / RenderDriftOpts API surface and
+* the yaml diff renderer. Registered at module load time via
+* `setYamlDiffRenderer` so `renderFileDriftBody` can dispatch yaml
+* entries without a hard dependency on the `yaml` package in
+* `idempotency-files.ts`.
+*
+* On a yaml-parse failure, the renderer returns a single explanatory
+* line and the dispatch falls through (caller-side) to the unified-text
+* body so the operator still sees something useful.
+*/
+function renderYamlDiffEntry(entry, opts) {
+	const local = entry.localContent ?? "";
+	const remote = entry.category === "new" ? "" : entry.remoteContent ?? "";
+	if (local === "" && remote === "" && entry.category !== "new") return [];
+	let diffs;
+	try {
+		diffs = diffYamlContent(local, remote);
+	} catch (err) {
+		return [`(yaml parse failed — ${err.message})`];
+	}
+	return renderYamlDiff(diffs, {
+		reveal: opts.revealEnvValues ?? false,
+		color: opts.color ?? false
+	});
+}
+setYamlDiffRenderer(renderYamlDiffEntry);
+//#endregion
+export { diffYamlContent, isPathSensitive, renderYamlDiff };
+
+//# sourceMappingURL=idempotency-yaml-diff.js.map

package/dist/idempotency-yaml-diff.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=idempotency-yaml-diff.test.d.ts.map

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { RingBuffer } from './ring-buffer.js';
 export { toErrorMessage, serializeError } from './error.js';
 export { createPool, createDb } from './db.js';
-export { parseDatabaseUrl, maskDatabaseUrl, dropAndCreateDatabase, dropDatabaseDirect, ensureDatabase, createDbRole, createReadOnlyDbUser, computeMigrationsHash, storeMigrationContentHash, readStoredMigrationContentHash, isSchemaCurrent, clearDispatchQueueDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, purgeScopedSecretsDirect, seedEnvironmentDirect, seedEnvironmentBindingDirect, setEnvironmentPolicyDirect, listEnvironmentsDirect, showEnvironmentDirect, createEnvironmentTemplateDirect, setEnvironmentSecretDirect, listQueueDirect, showQueueEntryDirect, listExecutionRunsDirect, showExecutionRunDirect, listExecutionJobsDirect, listRegistrationsDirect, showRegistrationDirect, registerWorkflowManualDirect, resetRaftStateDirect, emitKiciEventDirect, seedGenericWebhookSourceDirect, purgeSecretBackendsDirect, apiKeyExistsDirect, seedApiKeyInlineDirect, platformConnectionExistsDirect, countWebhookSourcesByConnectionIdDirect, findAnyUserApiKeyIdDirect, seedSyntheticGithubSourceDirect, seedWebhookSecretDirect, seedSourcePrivateKeyDirect, bumpRegistryVersionDirect, pollKiciEventsDirect, waitForPostgresDirect, waitForRunCompletionDirect, cleanupExecutionRowsDirect, isSchemaCurrentFromFilesDirect, storeMigrationContentHashInTableDirect, createJoinTokenDirect, updateSourceRoutingKeyDirect, prunePeerCredentialsDirect, waitForPlatformRegistrationsDirect, seedUniversalGitSourceDirect, seedCiSecurityFixturesDirect, waitForExecutionRunStatusSinceDirect, latestExecutionRunByStatusDirect, waitForLatestExecutionJobStatusDirect, describeTableColumnsDirect, tableExistsDirect, insertKiciEventRawDirect, showKiciEventDirect, listKiciEventsDirect, deleteKiciEventsDirect, verifyKiciEventNotifyDirect, seedCrossRepoTrustDirect, listCrossRepoTrustBySourceRoutingKeyDirect, deleteCrossRepoTrustDirect, insertCrossRepoTrustStrictDirect, deleteWorkflowRegistrationsDirect, getWorkflowRegistrationByIdDirect, listRegistrationsByRoutingKeyDirect, waitForRegistrationsByRoutingKeyDirect, waitForRegistrationsUpdatedAtAdvanceDirect, updateWorkflowRegistrationCommitShaDirect, insertWorkflowRegistrationRawDirect, insertWorkflowRegistrationStrictDirect, getRegistryVersionDirect, bumpRegistryVersionSimpleDirect, upsertCronLastFiredDirect, countCronLastFiredDirect, insertCronLastFiredNowDirect, deleteCronLastFiredDirect, deleteExecutionRunsByWorkflowNameDirect, getGenericWebhookSourceByRoutingKeyDirect, listActiveGenericWebhookSourcesDirect, updateGenericWebhookVerificationConfigDirect, deleteGenericWebhookSourcesByNameDirect, restoreSoftDeletedGenericWebhookSourceDirect, upsertOrgSettingsGlobalWorkflowsDirect, updateOrgSettingsDeniedReposDirect, deleteOrgSettingsByCustomerIdDirect, getExecutionRunSecurityDirect, getHeldRunByIdDirect, countHeldRunsByRunIdDirect, waitForPlatformExecutionRunStatusDirect, waitForPlatformEventLogDistinctRoutedDirect, waitForEventLogRowByDeliveryIdDirect, resolvePlatformWebhookSourceRoutingKeyDirect, ensureOrgOwnerMemberDirect, deletePeerCredentialsByInstanceIdLikeDirect, insertPeerCredentialExpiredDirect, getPeerCredentialRevokedAtDirect, listActivePeerCredentialsExcludingDirect, clearPeerCredentialsRevokedAtByIdsDirect, countActivePeerCredentialsByInstanceDirect, type ColumnInfo, type KiciEventRow, type CrossRepoTrustRow, type WorkflowRegistrationFullRow, type RegistrationsScopedResult, type LatestExecutionRunResult, type WaitForLatestJobResult, type ExecutionRunSecurityRow, type HeldRunSecurityRow, type EventLogRow as PlatformEventLogRow, type UpsertOrgSettingsOpts, type OrgSettingsRepoPatternEntry, type InsertKiciEventRawOpts, type EmitKiciEventOpts, type SeedGenericWebhookSourceOpts, REGISTERABLE_TRIGGER_TYPES, MIGRATION_HASH_TABLE, type PurgeStaleExecutionResult, type PurgeStaleSourcesResult, type SeedEnvironmentOpts, type SeedEnvironmentResult, type SeedEnvironmentBindingOpts, type SetEnvironmentPolicyOpts, type EnvironmentRow, type EnvironmentVariableRow, type EnvironmentBindingRow, type ShowEnvironmentResult, type CreateEnvironmentTemplateOpts, type SetEnvironmentSecretOpts, type DispatchQueueRow, type ListQueueOpts, type ExecutionRunRow, type ExecutionJobRow, type ListExecutionRunsOpts, type WorkflowRegistrationRow, type ListRegistrationsOpts, type ListRegistrationsResult, type ShowRegistrationResult, type RegisterWorkflowManualOpts, type RegisterWorkflowManualResult, } from './db-admin.js';
+export { parseDatabaseUrl, maskDatabaseUrl, dropAndCreateDatabase, dropDatabaseDirect, ensureDatabase, type EnsureDatabaseOpts, createDbRole, createReadOnlyDbUser, computeMigrationsHash, storeMigrationContentHash, readStoredMigrationContentHash, isSchemaCurrent, clearDispatchQueueDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, purgeScopedSecretsDirect, seedEnvironmentDirect, seedEnvironmentBindingDirect, setEnvironmentPolicyDirect, listEnvironmentsDirect, showEnvironmentDirect, createEnvironmentTemplateDirect, setEnvironmentSecretDirect, listQueueDirect, showQueueEntryDirect, listExecutionRunsDirect, showExecutionRunDirect, listExecutionJobsDirect, listRegistrationsDirect, showRegistrationDirect, registerWorkflowManualDirect, resetRaftStateDirect, emitKiciEventDirect, seedGenericWebhookSourceDirect, purgeSecretBackendsDirect, apiKeyExistsDirect, seedApiKeyInlineDirect, platformConnectionExistsDirect, countWebhookSourcesByConnectionIdDirect, findAnyUserApiKeyIdDirect, seedSyntheticGithubSourceDirect, seedWebhookSecretDirect, seedSourcePrivateKeyDirect, bumpRegistryVersionDirect, pollKiciEventsDirect, waitForPostgresDirect, waitForRunCompletionDirect, cleanupExecutionRowsDirect, isSchemaCurrentFromFilesDirect, storeMigrationContentHashInTableDirect, createJoinTokenDirect, updateSourceRoutingKeyDirect, prunePeerCredentialsDirect, waitForPlatformRegistrationsDirect, seedUniversalGitSourceDirect, seedCiSecurityFixturesDirect, waitForExecutionRunStatusSinceDirect, latestExecutionRunByStatusDirect, waitForLatestExecutionJobStatusDirect, describeTableColumnsDirect, tableExistsDirect, insertKiciEventRawDirect, showKiciEventDirect, listKiciEventsDirect, deleteKiciEventsDirect, verifyKiciEventNotifyDirect, seedCrossRepoTrustDirect, listCrossRepoTrustBySourceRoutingKeyDirect, deleteCrossRepoTrustDirect, insertCrossRepoTrustStrictDirect, deleteWorkflowRegistrationsDirect, getWorkflowRegistrationByIdDirect, listRegistrationsByRoutingKeyDirect, waitForRegistrationsByRoutingKeyDirect, waitForRegistrationsUpdatedAtAdvanceDirect, updateWorkflowRegistrationCommitShaDirect, insertWorkflowRegistrationRawDirect, insertWorkflowRegistrationStrictDirect, getRegistryVersionDirect, bumpRegistryVersionSimpleDirect, upsertCronLastFiredDirect, countCronLastFiredDirect, insertCronLastFiredNowDirect, deleteCronLastFiredDirect, deleteExecutionRunsByWorkflowNameDirect, getGenericWebhookSourceByRoutingKeyDirect, listActiveGenericWebhookSourcesDirect, updateGenericWebhookVerificationConfigDirect, deleteGenericWebhookSourcesByNameDirect, restoreSoftDeletedGenericWebhookSourceDirect, upsertOrgSettingsGlobalWorkflowsDirect, updateOrgSettingsDeniedReposDirect, deleteOrgSettingsByCustomerIdDirect, getExecutionRunSecurityDirect, getHeldRunByIdDirect, countHeldRunsByRunIdDirect, waitForPlatformExecutionRunStatusDirect, waitForPlatformEventLogDistinctRoutedDirect, waitForEventLogRowByDeliveryIdDirect, resolvePlatformWebhookSourceRoutingKeyDirect, ensureOrgOwnerMemberDirect, deletePeerCredentialsByInstanceIdLikeDirect, insertPeerCredentialExpiredDirect, getPeerCredentialRevokedAtDirect, listActivePeerCredentialsExcludingDirect, clearPeerCredentialsRevokedAtByIdsDirect, countActivePeerCredentialsByInstanceDirect, type ColumnInfo, type KiciEventRow, type CrossRepoTrustRow, type WorkflowRegistrationFullRow, type RegistrationsScopedResult, type LatestExecutionRunResult, type WaitForLatestJobResult, type ExecutionRunSecurityRow, type HeldRunSecurityRow, type EventLogRow as PlatformEventLogRow, type UpsertOrgSettingsOpts, type OrgSettingsRepoPatternEntry, type InsertKiciEventRawOpts, type EmitKiciEventOpts, type SeedGenericWebhookSourceOpts, REGISTERABLE_TRIGGER_TYPES, MIGRATION_HASH_TABLE, type PurgeStaleExecutionResult, type PurgeStaleSourcesResult, type SeedEnvironmentOpts, type SeedEnvironmentResult, type SeedEnvironmentBindingOpts, type SetEnvironmentPolicyOpts, type EnvironmentRow, type EnvironmentVariableRow, type EnvironmentBindingRow, type ShowEnvironmentResult, type CreateEnvironmentTemplateOpts, type SetEnvironmentSecretOpts, type DispatchQueueRow, type ListQueueOpts, type ExecutionRunRow, type ExecutionJobRow, type ListExecutionRunsOpts, type WorkflowRegistrationRow, type ListRegistrationsOpts, type ListRegistrationsResult, type ShowRegistrationResult, type RegisterWorkflowManualOpts, type RegisterWorkflowManualResult, } from './db-admin.js';
 export { createMetricsRoutes, type MetricsRoutesDeps } from './routes/metrics.js';
 export { createHealthRoutes, type HealthRoutesDeps } from './routes/health.js';
 export { initZx } from './zx.js';
@@ -11,7 +11,7 @@ export { getReconnectDelay } from './reconnect-delay.js';
 export { formatBytes } from './format-bytes.js';
 export { formatDuration, formatUptime } from './format-duration.js';
 export { sha256, sha256File, deriveSharedSecret, normalizeLineEndings } from './crypto.js';
-export { initTelemetry, getPrometheusExporter, createMeter, type TelemetryConfig, } from './telemetry/index.js';
+export { initTelemetry, getPrometheusExporter, collectRuntimeMetricNames, createMeter, type TelemetryConfig, } from './telemetry/index.js';
 export { setupGracefulShutdown, type ShutdownStep, type ShutdownLogger, type ShutdownHandle, type GracefulShutdownOptions, } from './graceful-shutdown.js';
 export { validateRequiredTools, type ToolRequirement } from './tool-check.js';
 export { createS3Client, type CreateS3ClientOptions, type SharedS3Config } from './s3-client.js';

package/dist/index.js

@@ -13,7 +13,7 @@ import { initZx } from "./zx.js";
 import { enrichRequestContext, getRequestContext, requestContext } from "./request-context.js";
 import { createLogger, guardStartup, logger, setServiceName } from "./logger.js";
 import { getReconnectDelay } from "./reconnect-delay.js";
-import { getPrometheusExporter, initTelemetry } from "./telemetry/init.js";
+import { collectRuntimeMetricNames, getPrometheusExporter, initTelemetry } from "./telemetry/init.js";
 import { createMeter } from "./telemetry/metrics.js";
 import "./telemetry/index.js";
 import { validateRequiredTools } from "./tool-check.js";
@@ -28,4 +28,4 @@ import { BaseColdStore } from "./cold-store/cold-store.js";
 import { ChunkLru } from "./cold-store/lru.js";
 import { DEFAULT_TABLE_CONFIG, resolveTableConfig } from "./cold-store/config.js";
 import "./cold-store/index.js";
-export { BaseColdStore, COLD_BUCKET_NAMES, ChunkLru, DEFAULT_TABLE_CONFIG, MIGRATION_HASH_TABLE, REGISTERABLE_TRIGGER_TYPES, RingBuffer, apiKeyExistsDirect, bumpRegistryVersionDirect, bumpRegistryVersionSimpleDirect, chunkObjectKey, cleanupExecutionRowsDirect, clearDispatchQueueDirect, clearPeerCredentialsRevokedAtByIdsDirect, coldDaysToBucket, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, computeChunkId, computeMigrationsHash, countActivePeerCredentialsByInstanceDirect, countCronLastFiredDirect, countHeldRunsByRunIdDirect, countWebhookSourcesByConnectionIdDirect, createDb, createDbRole, createEnvironmentTemplateDirect, createHealthRoutes, createJoinTokenDirect, createLogger, createMeter, createMetricsRoutes, createPool, createReadOnlyDbUser, createS3Client, decodeChunk, deleteCronLastFiredDirect, deleteCrossRepoTrustDirect, deleteExecutionRunsByWorkflowNameDirect, deleteGenericWebhookSourcesByNameDirect, deleteKiciEventsDirect, deleteOrgSettingsByCustomerIdDirect, deletePeerCredentialsByInstanceIdLikeDirect, deleteWorkflowRegistrationsDirect, deriveSharedSecret, describeTableColumnsDirect, dropAndCreateDatabase, dropDatabaseDirect, emitKiciEventDirect, encodeChunk, encodeKeySegment, enrichRequestContext, ensureDatabase, ensureOrgOwnerMemberDirect, findAnyUserApiKeyIdDirect, formatBytes, formatDuration, formatUptime, getExecutionRunSecurityDirect, getGenericWebhookSourceByRoutingKeyDirect, getHeldRunByIdDirect, getPeerCredentialRevokedAtDirect, getPrometheusExporter, getReconnectDelay, getRegistryVersionDirect, getRequestContext, getWorkflowRegistrationByIdDirect, guardStartup, initTelemetry, initZx, insertCronLastFiredNowDirect, insertCrossRepoTrustStrictDirect, insertKiciEventRawDirect, insertPeerCredentialExpiredDirect, insertWorkflowRegistrationRawDirect, insertWorkflowRegistrationStrictDirect, isLongerColdRetention, isSchemaCurrent, isSchemaCurrentFromFilesDirect, latestExecutionRunByStatusDirect, listActiveGenericWebhookSourcesDirect, listActivePeerCredentialsExcludingDirect, listCrossRepoTrustBySourceRoutingKeyDirect, listEnvironmentsDirect, listExecutionJobsDirect, listExecutionRunsDirect, listKiciEventsDirect, listQueueDirect, listRegistrationsByRoutingKeyDirect, listRegistrationsDirect, logger, maskDatabaseUrl, normalizeLineEndings, parseDatabaseUrl, parseManifest, platformConnectionExistsDirect, pollKiciEventsDirect, prunePeerCredentialsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, readStoredMigrationContentHash, registerWorkflowManualDirect, requestContext, resetRaftStateDirect, resolvePlatformWebhookSourceRoutingKeyDirect, resolveTableConfig, restoreSoftDeletedGenericWebhookSourceDirect, seedApiKeyInlineDirect, seedCiSecurityFixturesDirect, seedCrossRepoTrustDirect, seedEnvironmentBindingDirect, seedEnvironmentDirect, seedGenericWebhookSourceDirect, seedSourcePrivateKeyDirect, seedSyntheticGithubSourceDirect, seedUniversalGitSourceDirect, seedWebhookSecretDirect, serializeError, serializeManifest, setEnvironmentPolicyDirect, setEnvironmentSecretDirect, setServiceName, setupGracefulShutdown, sha256, sha256File, showEnvironmentDirect, showExecutionRunDirect, showKiciEventDirect, showQueueEntryDirect, showRegistrationDirect, storeMigrationContentHash, storeMigrationContentHashInTableDirect, tableExistsDirect, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix, toErrorMessage, updateGenericWebhookVerificationConfigDirect, updateOrgSettingsDeniedReposDirect, updateSourceRoutingKeyDirect, updateWorkflowRegistrationCommitShaDirect, upsertCronLastFiredDirect, upsertOrgSettingsGlobalWorkflowsDirect, validateRequiredTools, verifyKiciEventNotifyDirect, waitForEventLogRowByDeliveryIdDirect, waitForExecutionRunStatusSinceDirect, waitForLatestExecutionJobStatusDirect, waitForPlatformEventLogDistinctRoutedDirect, waitForPlatformExecutionRunStatusDirect, waitForPlatformRegistrationsDirect, waitForPostgresDirect, waitForRegistrationsByRoutingKeyDirect, waitForRegistrationsUpdatedAtAdvanceDirect, waitForRunCompletionDirect };
+export { BaseColdStore, COLD_BUCKET_NAMES, ChunkLru, DEFAULT_TABLE_CONFIG, MIGRATION_HASH_TABLE, REGISTERABLE_TRIGGER_TYPES, RingBuffer, apiKeyExistsDirect, bumpRegistryVersionDirect, bumpRegistryVersionSimpleDirect, chunkObjectKey, cleanupExecutionRowsDirect, clearDispatchQueueDirect, clearPeerCredentialsRevokedAtByIdsDirect, coldDaysToBucket, coldStoreArchiveBytesTotal, coldStoreArchiveCyclesTotal, coldStoreArchiveDurationSeconds, coldStoreArchiveRowsTotal, coldStorePurgeBytesTotal, coldStorePurgeChunksTotal, coldStorePurgeDurationSeconds, coldStoreRehydrateBytesTotal, coldStoreRehydrateDurationSeconds, coldStoreRehydrateRequestsTotal, coldStoreReplayDurationSeconds, coldStoreReplayRowsTotal, coldStoreVerifyFailuresTotal, collectRuntimeMetricNames, computeChunkId, computeMigrationsHash, countActivePeerCredentialsByInstanceDirect, countCronLastFiredDirect, countHeldRunsByRunIdDirect, countWebhookSourcesByConnectionIdDirect, createDb, createDbRole, createEnvironmentTemplateDirect, createHealthRoutes, createJoinTokenDirect, createLogger, createMeter, createMetricsRoutes, createPool, createReadOnlyDbUser, createS3Client, decodeChunk, deleteCronLastFiredDirect, deleteCrossRepoTrustDirect, deleteExecutionRunsByWorkflowNameDirect, deleteGenericWebhookSourcesByNameDirect, deleteKiciEventsDirect, deleteOrgSettingsByCustomerIdDirect, deletePeerCredentialsByInstanceIdLikeDirect, deleteWorkflowRegistrationsDirect, deriveSharedSecret, describeTableColumnsDirect, dropAndCreateDatabase, dropDatabaseDirect, emitKiciEventDirect, encodeChunk, encodeKeySegment, enrichRequestContext, ensureDatabase, ensureOrgOwnerMemberDirect, findAnyUserApiKeyIdDirect, formatBytes, formatDuration, formatUptime, getExecutionRunSecurityDirect, getGenericWebhookSourceByRoutingKeyDirect, getHeldRunByIdDirect, getPeerCredentialRevokedAtDirect, getPrometheusExporter, getReconnectDelay, getRegistryVersionDirect, getRequestContext, getWorkflowRegistrationByIdDirect, guardStartup, initTelemetry, initZx, insertCronLastFiredNowDirect, insertCrossRepoTrustStrictDirect, insertKiciEventRawDirect, insertPeerCredentialExpiredDirect, insertWorkflowRegistrationRawDirect, insertWorkflowRegistrationStrictDirect, isLongerColdRetention, isSchemaCurrent, isSchemaCurrentFromFilesDirect, latestExecutionRunByStatusDirect, listActiveGenericWebhookSourcesDirect, listActivePeerCredentialsExcludingDirect, listCrossRepoTrustBySourceRoutingKeyDirect, listEnvironmentsDirect, listExecutionJobsDirect, listExecutionRunsDirect, listKiciEventsDirect, listQueueDirect, listRegistrationsByRoutingKeyDirect, listRegistrationsDirect, logger, maskDatabaseUrl, normalizeLineEndings, parseDatabaseUrl, parseManifest, platformConnectionExistsDirect, pollKiciEventsDirect, prunePeerCredentialsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, readStoredMigrationContentHash, registerWorkflowManualDirect, requestContext, resetRaftStateDirect, resolvePlatformWebhookSourceRoutingKeyDirect, resolveTableConfig, restoreSoftDeletedGenericWebhookSourceDirect, seedApiKeyInlineDirect, seedCiSecurityFixturesDirect, seedCrossRepoTrustDirect, seedEnvironmentBindingDirect, seedEnvironmentDirect, seedGenericWebhookSourceDirect, seedSourcePrivateKeyDirect, seedSyntheticGithubSourceDirect, seedUniversalGitSourceDirect, seedWebhookSecretDirect, serializeError, serializeManifest, setEnvironmentPolicyDirect, setEnvironmentSecretDirect, setServiceName, setupGracefulShutdown, sha256, sha256File, showEnvironmentDirect, showExecutionRunDirect, showKiciEventDirect, showQueueEntryDirect, showRegistrationDirect, storeMigrationContentHash, storeMigrationContentHashInTableDirect, tableExistsDirect, tablePrefix, tenantDayBucketPrefix, tenantDayPrefix, toErrorMessage, updateGenericWebhookVerificationConfigDirect, updateOrgSettingsDeniedReposDirect, updateSourceRoutingKeyDirect, updateWorkflowRegistrationCommitShaDirect, upsertCronLastFiredDirect, upsertOrgSettingsGlobalWorkflowsDirect, validateRequiredTools, verifyKiciEventNotifyDirect, waitForEventLogRowByDeliveryIdDirect, waitForExecutionRunStatusSinceDirect, waitForLatestExecutionJobStatusDirect, waitForPlatformEventLogDistinctRoutedDirect, waitForPlatformExecutionRunStatusDirect, waitForPlatformRegistrationsDirect, waitForPostgresDirect, waitForRegistrationsByRoutingKeyDirect, waitForRegistrationsUpdatedAtAdvanceDirect, waitForRunCompletionDirect };

package/dist/logger.d.ts

@@ -23,7 +23,10 @@ export interface Logger {
 }
 /** Logger creation options */
 interface LoggerOptions {
-    /** Use JSON format (default: auto-detect based on TTY) */
+    /**
+     * Use JSON format (default: auto-detected from KICI_LOG_FORMAT env var, with
+     * a TTY fallback). Passing an explicit boolean wins over the env var.
+     */
     json?: boolean;
     /** Log level (default: 'info') */
     level?: LogLevel;