@warlock.js/logger 5.29.0 → 5.31.0

package/cjs/index.cjs

@@ -39,7 +39,7 @@ path = __toESM(path, 1);
 let safe_stable_stringify = require("safe-stable-stringify");
 let _mongez_reinforcements = require("@mongez/reinforcements");
 
-//#region ../logger/src/log-channel.ts
+//#region ../../packages/logger/src/log-channel.ts
 var LogChannel = class {
 	/**
 	* Constructor
@@ -56,6 +56,28 @@ var LogChannel = class {
 		}, 0);
 	}
 	/**
+	* Route this channel's own failures (those outside a `log()` call) to the
+	* given reporter. `Logger` calls this when the channel is added, so the
+	* failures reach `log.onChannelError(...)`.
+	*/
+	setErrorReporter(reporter) {
+		this.errorReporter = reporter;
+	}
+	/**
+	* Report a failure that happened outside a `log()` call. Never throws:
+	* without a reporter it writes one line to stderr.
+	*/
+	reportError(error, entry) {
+		try {
+			if (this.errorReporter) {
+				this.errorReporter(error, entry);
+				return;
+			}
+			const reason = error instanceof Error ? error.message : String(error);
+			process.stderr.write(`[@warlock.js/logger] channel "${this.name}" failed: ${reason}\n`);
+		} catch {}
+	}
+	/**
 	* Get config value
 	*/
 	config(key) {
@@ -112,7 +134,7 @@ var LogChannel = class {
 };
 
 //#endregion
-//#region ../logger/src/channels/console-log.ts
+//#region ../../packages/logger/src/channels/console-log.ts
 /**
 * The longest level name (`success`) sets the tag column width. Padding every
 * level name to this width keeps the timestamp / module / action columns
@@ -195,7 +217,53 @@ var ConsoleLog = class extends LogChannel {
 };
 
 //#endregion
-//#region ../logger/src/channels/file-log.ts
+//#region ../../packages/logger/src/channels/file-name-pattern.ts
+const TOKEN = /\{(YYYY|MM|DD|HH|mm|name)\}/g;
+const pad = (value) => String(value).padStart(2, "0");
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+* Render a file name option for the given date.
+*/
+function renderFileName(option, date, name) {
+	if (typeof option === "function") return option(date);
+	return option.replace(TOKEN, (_match, token) => {
+		switch (token) {
+			case "YYYY": return String(date.getFullYear());
+			case "MM": return pad(date.getMonth() + 1);
+			case "DD": return pad(date.getDate());
+			case "HH": return pad(date.getHours());
+			case "mm": return pad(date.getMinutes());
+			default: return name;
+		}
+	});
+}
+/**
+* Regular-expression source matching every name a pattern string can render:
+* literal text is escaped, date tokens become digit runs and `{name}` the
+* escaped channel name. The source is not anchored.
+*/
+function fileNamePatternSource(pattern, name) {
+	let source = "";
+	let lastIndex = 0;
+	for (const match of pattern.matchAll(TOKEN)) {
+		const index = match.index ?? 0;
+		const token = match[1];
+		source += escapeRegExp(pattern.slice(lastIndex, index));
+		source += token === "YYYY" ? "\\d{4}" : token === "name" ? escapeRegExp(name) : "\\d{2}";
+		lastIndex = index + match[0].length;
+	}
+	return source + escapeRegExp(pattern.slice(lastIndex));
+}
+
+//#endregion
+//#region ../../packages/logger/src/channels/file-log.ts
+/** Default file name of a `daily` chunk: sortable ISO date. */
+const DAILY_FILE_NAME = "{YYYY}-{MM}-{DD}";
+/** Default file name of an `hourly` chunk: sortable ISO date and hour. */
+const HOURLY_FILE_NAME = "{YYYY}-{MM}-{DD}-{HH}";
+/** Default date part of a size-rotated file's name. */
+const ROTATE_FILE_NAME = "{YYYY}-{MM}-{DD}";
+const DAY_MS = 1440 * 60 * 1e3;
 var FileLog = class extends LogChannel {
 	constructor(..._args) {
 		super(..._args);
@@ -211,9 +279,7 @@ var FileLog = class extends LogChannel {
 			maxMessagesToWrite: 100,
 			filter: () => true,
 			maxFileSize: 10 * 1024 * 1024,
-			get rotateFileName() {
-				return (0, dayjs.default)().format("DD-MM-YYYY");
-			},
+			rotateFileName: ROTATE_FILE_NAME,
 			dateFormat: {
 				date: "DD-MM-YYYY",
 				time: "HH:mm:ss"
@@ -221,6 +287,15 @@ var FileLog = class extends LogChannel {
 		};
 		this.lastWriteTime = Date.now();
 		this.isWriting = false;
+		this.retentionDue = false;
+		this.missingMatchReported = false;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	setConfigurations(configurations) {
+		assertRetention(configurations.retention);
+		return super.setConfigurations(configurations);
 	}
 	/**
 	* Check file size for file rotation
@@ -228,19 +303,24 @@ var FileLog = class extends LogChannel {
 	async checkAndRotateFile(filePath = this.filePath) {
 		if (!this.config("rotate")) return;
 		try {
-			if ((await fs.default.promises.stat(filePath)).size >= this.config("maxFileSize")) await this.rotateLogFile();
+			if ((await fs.default.promises.stat(filePath)).size >= this.config("maxFileSize")) await this.rotateLogFile(filePath);
 		} catch (error) {
 			if (error.code !== "ENOENT") console.error("Error checking log file:", error);
 		}
 	}
 	/**
-	* Rotate log file
+	* Rotate the given log file (the active one by default) aside as
+	* `<file name>-<rotateFileName>-<epoch ms>.<extension>` in its directory.
 	*/
-	async rotateLogFile() {
-		const fileName = `${this.fileName}-${this.config("rotateFileName")}-${Date.now()}`;
+	async rotateLogFile(filePath = this.filePath) {
+		const now = /* @__PURE__ */ new Date();
 		const extension = this.extension;
-		const rotatedFilePath = path.default.join(this.storagePath, `${fileName}.${extension}`);
-		await fs.default.promises.rename(this.filePath, rotatedFilePath).catch((error) => {
+		const baseName = path.default.basename(filePath, `.${extension}`);
+		const rotateName = renderFileName(this.config("rotateFileName") ?? "{YYYY}-{MM}-{DD}", now, this.baseName);
+		const rotatedFilePath = path.default.join(path.default.dirname(filePath), `${baseName}-${rotateName}-${now.getTime()}.${extension}`);
+		await fs.default.promises.rename(filePath, rotatedFilePath).then(() => {
+			this.retentionDue = true;
+		}, (error) => {
 			console.error("Error rotating file:", error);
 		});
 	}
@@ -286,17 +366,32 @@ var FileLog = class extends LogChannel {
 		return this.config("maxMessagesToWrite");
 	}
 	/**
-	* Get file name
+	* The configured `name` option.
 	*/
-	get fileName() {
+	get baseName() {
+		return this.config("name") ?? "app";
+	}
+	/**
+	* The `fileName` option, or the chunk's default. `undefined` means the
+	* plain `name` of a `single` chunk, used as is (braces included).
+	*/
+	get fileNamePattern() {
+		const configured = this.config("fileName");
+		if (configured !== void 0) return configured;
 		switch (this.config("chunk")) {
-			case "single":
-			default: return this.config("name");
-			case "daily": return (0, dayjs.default)().format("DD-MM-YYYY");
-			case "hourly": return (0, dayjs.default)().format("DD-MM-YYYY-HH-00-00-a");
+			case "daily": return DAILY_FILE_NAME;
+			case "hourly": return HOURLY_FILE_NAME;
+			default: return;
 		}
 	}
 	/**
+	* Current file name, without extension
+	*/
+	get fileName() {
+		const pattern = this.fileNamePattern;
+		return pattern === void 0 ? this.baseName : renderFileName(pattern, /* @__PURE__ */ new Date(), this.baseName);
+	}
+	/**
 	* Get file extension
 	*/
 	get extension() {
@@ -321,6 +416,138 @@ var FileLog = class extends LogChannel {
 		const logsDirectory = this.storagePath;
 		await (0, _warlock_js_fs.ensureDirectoryAsync)(logsDirectory);
 		this.initMessageFlush();
+		await this.prune();
+	}
+	/**
+	* Remove old log files as configured by `retention`. Runs on boot and
+	* whenever a new file is started; call it yourself to prune on demand.
+	* Never rejects: failures go to the channel error handler.
+	*/
+	prune() {
+		const run = (this.pruning ?? Promise.resolve()).then(() => this.pruneFiles());
+		this.pruning = run;
+		return run;
+	}
+	/**
+	* Prune once a write started a new file: after a size rotation, or when a
+	* dated file name rolled over. Never throws.
+	*/
+	async afterWrite() {
+		let fileName;
+		try {
+			fileName = this.fileName;
+		} catch {
+			return;
+		}
+		const rolledOver = this.lastFileName !== void 0 && this.lastFileName !== fileName;
+		this.lastFileName = fileName;
+		if (!rolledOver && !this.retentionDue) return;
+		this.retentionDue = false;
+		await this.prune();
+	}
+	/**
+	* Apply `retention` to every directory this channel writes to.
+	*/
+	async pruneFiles() {
+		const retention = this.config("retention");
+		if (!retention || retention.maxFiles === void 0 && retention.maxAgeDays === void 0) return;
+		try {
+			const matcher = this.retentionMatcher(retention);
+			if (!matcher) return;
+			const activeFile = `${this.fileName}.${this.extension}`;
+			for (const directory of await this.retentionDirectories()) await this.pruneDirectory(directory, matcher, retention, activeFile);
+		} catch (error) {
+			this.reportRetentionError(error, this.storagePath);
+		}
+	}
+	/**
+	* The expression a file name must match to be pruned, or `undefined` when
+	* none can be derived (a function `fileName` without `retention.match`).
+	*/
+	retentionMatcher(retention) {
+		if (retention.match) return new RegExp(retention.match.source, retention.match.flags.replace(/[gy]/g, ""));
+		const pattern = this.fileNamePattern;
+		if (typeof pattern === "function") {
+			if (!this.missingMatchReported) {
+				this.missingMatchReported = true;
+				this.reportRetentionError(/* @__PURE__ */ new Error("FileLog retention needs `retention.match` when `fileName` is a function; no files were pruned"), this.storagePath);
+			}
+			return;
+		}
+		const name = this.baseName;
+		const fileSource = pattern === void 0 ? escapeRegExp(name) : fileNamePatternSource(pattern, name);
+		const rotateName = this.config("rotateFileName") ?? "{YYYY}-{MM}-{DD}";
+		const rotateSource = typeof rotateName === "function" ? ".+" : fileNamePatternSource(rotateName, name);
+		return new RegExp(`^${fileSource}(?:-${rotateSource}-\\d{13,})?\\.${escapeRegExp(this.extension)}$`);
+	}
+	/**
+	* The log directory, or each group directory when `groupBy` is set.
+	*/
+	async retentionDirectories() {
+		let directories = [this.storagePath];
+		const depth = this.config("groupBy")?.length ?? 0;
+		for (let level = 0; level < depth; level++) {
+			const next = [];
+			for (const directory of directories) {
+				const entries = await fs.default.promises.readdir(directory, { withFileTypes: true }).catch((error) => {
+					if (error.code !== "ENOENT") this.reportRetentionError(error, directory);
+					return [];
+				});
+				for (const entry of entries) if (entry.isDirectory()) next.push(path.default.join(directory, entry.name));
+			}
+			directories = next;
+		}
+		return directories;
+	}
+	/**
+	* Remove the matching files of one directory that `retention` no longer
+	* keeps. Each failure is reported and the rest still run.
+	*/
+	async pruneDirectory(directory, matcher, retention, activeFile) {
+		let names;
+		try {
+			names = await fs.default.promises.readdir(directory);
+		} catch (error) {
+			if (error.code !== "ENOENT") this.reportRetentionError(error, directory);
+			return;
+		}
+		const candidates = [];
+		for (const name of names) {
+			if (name === activeFile || !matcher.test(name)) continue;
+			const filePath = path.default.join(directory, name);
+			try {
+				const stats = await fs.default.promises.stat(filePath);
+				if (stats.isFile()) candidates.push({
+					filePath,
+					name,
+					modifiedAt: stats.mtimeMs
+				});
+			} catch (error) {
+				if (error.code !== "ENOENT") this.reportRetentionError(error, filePath);
+			}
+		}
+		candidates.sort((a, b) => b.modifiedAt - a.modifiedAt || (a.name < b.name ? 1 : -1));
+		const keep = retention.maxFiles === void 0 ? Infinity : retention.maxFiles - (names.includes(activeFile) ? 1 : 0);
+		const oldestKept = retention.maxAgeDays === void 0 ? -Infinity : Date.now() - retention.maxAgeDays * DAY_MS;
+		for (const [index, candidate] of candidates.entries()) {
+			if (index < keep && candidate.modifiedAt >= oldestKept) continue;
+			try {
+				await fs.default.promises.unlink(candidate.filePath);
+			} catch (error) {
+				if (error.code !== "ENOENT") this.reportRetentionError(error, candidate.filePath);
+			}
+		}
+	}
+	/**
+	* Send a retention failure to the channel error handler.
+	*/
+	reportRetentionError(error, target) {
+		this.reportError(error, {
+			type: "error",
+			module: "logger",
+			action: "retention",
+			message: `Log retention failed for ${target}`
+		});
 	}
 	/**
 	* Synchronously flush messages
@@ -412,14 +639,17 @@ var FileLog = class extends LogChannel {
 		if (this.messages.length === 0 || this.isWriting || !this.isInitialized) return;
 		this.isWriting = true;
 		if (this.messagedShouldBeGrouped) return await this.writeGroupedMessagesToFile();
-		await this.checkAndRotateFile();
 		try {
-			await this.write(this.filePath, this.content);
+			const filePath = this.filePath;
+			await this.checkAndRotateFile(filePath);
+			await this.write(filePath, this.content);
 			this.onSave();
 		} catch (error) {
 			console.error("Failed to write log:", error);
 			this.isWriting = false;
+			return;
 		}
+		await this.afterWrite();
 	}
 	/**
 	* Write grouped messages to the file
@@ -428,11 +658,11 @@ var FileLog = class extends LogChannel {
 		this.prepareGroupedMessages();
 		for (const [key, groupMessages] of Object.entries(this.groupedMessages)) {
 			const directoryPath = path.default.join(this.storagePath, key);
-			await (0, _warlock_js_fs.ensureDirectoryAsync)(directoryPath);
-			const filePath = path.default.join(directoryPath, `${this.fileName}.${this.extension}`);
-			await this.checkAndRotateFile(filePath);
-			const content = groupMessages.map((message) => message.content).join(os.EOL) + os.EOL;
 			try {
+				await (0, _warlock_js_fs.ensureDirectoryAsync)(directoryPath);
+				const filePath = path.default.join(directoryPath, `${this.fileName}.${this.extension}`);
+				await this.checkAndRotateFile(filePath);
+				const content = groupMessages.map((message) => message.content).join(os.EOL) + os.EOL;
 				await this.write(filePath, content);
 			} catch (error) {
 				console.error("Failed to write log:", error);
@@ -440,6 +670,7 @@ var FileLog = class extends LogChannel {
 		}
 		this.onSave();
 		this.isWriting = false;
+		await this.afterWrite();
 	}
 	/**
 	* Prepare grouped messages
@@ -465,9 +696,19 @@ var FileLog = class extends LogChannel {
 		});
 	}
 };
+/**
+* Reject a `retention` that could never keep or remove anything sensibly.
+*/
+function assertRetention(retention) {
+	if (!retention) return;
+	const { maxFiles, maxAgeDays, match } = retention;
+	if (maxFiles !== void 0 && (!Number.isInteger(maxFiles) || maxFiles < 1)) throw new TypeError("FileLog retention.maxFiles must be a positive integer");
+	if (maxAgeDays !== void 0 && (!Number.isFinite(maxAgeDays) || maxAgeDays <= 0)) throw new TypeError("FileLog retention.maxAgeDays must be a positive number");
+	if (match !== void 0 && !(match instanceof RegExp)) throw new TypeError("FileLog retention.match must be a RegExp");
+}
 
 //#endregion
-//#region ../logger/src/utils/safe-json-stringify.ts
+//#region ../../packages/logger/src/utils/safe-json-stringify.ts
 /**
 * Replacer that surfaces Error data — `name`, `message`, and `stack` are
 * non-enumerable on `Error`, so neither default JSON serialization nor an
@@ -498,7 +739,7 @@ function safeJsonStringify(value, space) {
 }
 
 //#endregion
-//#region ../logger/src/channels/json-file-log.ts
+//#region ../../packages/logger/src/channels/json-file-log.ts
 var JSONFileLog = class extends FileLog {
 	constructor(..._args) {
 		super(..._args);
@@ -577,10 +818,18 @@ var JSONFileLog = class extends FileLog {
 		if (this.messages.length === 0 || this.isWriting || !this.isInitialized) return;
 		this.isWriting = true;
 		if (this.messagedShouldBeGrouped) return await this.writeGroupedMessagesToFile();
-		await this.checkAndRotateFile();
+		let filePath;
+		try {
+			filePath = this.filePath;
+		} catch (error) {
+			console.error("Failed to write log:", error);
+			this.isWriting = false;
+			return;
+		}
+		await this.checkAndRotateFile(filePath);
 		let fileContents = { messages: [] };
-		if (await (0, _warlock_js_fs.fileExistsAsync)(this.filePath)) try {
-			fileContents = await (0, _warlock_js_fs.getJsonFileAsync)(this.filePath);
+		if (await (0, _warlock_js_fs.fileExistsAsync)(filePath)) try {
+			fileContents = await (0, _warlock_js_fs.getJsonFileAsync)(filePath);
 		} catch (error) {
 			console.error("Error reading log file, reinitializing:", error);
 			fileContents = { messages: [] };
@@ -588,22 +837,32 @@ var JSONFileLog = class extends FileLog {
 		else fileContents = { messages: [] };
 		fileContents.messages.push(...this.messages);
 		try {
-			await fs.default.promises.writeFile(this.filePath, safeJsonStringify(fileContents, 2));
+			await fs.default.promises.writeFile(filePath, safeJsonStringify(fileContents, 2));
 			this.onSave();
 		} catch (error) {
 			console.error("Failed to write log:", error);
 			this.isWriting = false;
+			return;
 		}
+		await this.afterWrite();
 	}
 	/**
 	* Write grouped messages to the file
 	*/
 	async writeGroupedMessagesToFile() {
+		let fileName;
+		try {
+			fileName = this.fileName;
+		} catch (error) {
+			console.error("Failed to write log:", error);
+			this.isWriting = false;
+			return;
+		}
 		this.prepareGroupedMessages();
 		for (const [key, groupMessages] of Object.entries(this.groupedMessages)) {
 			const directoryPath = path.default.join(this.storagePath, key);
 			await (0, _warlock_js_fs.ensureDirectoryAsync)(directoryPath);
-			const filePath = path.default.join(directoryPath, `${this.fileName}.${this.extension}`);
+			const filePath = path.default.join(directoryPath, `${fileName}.${this.extension}`);
 			await this.checkAndRotateFile(filePath);
 			let fileContents = { messages: [] };
 			if (await (0, _warlock_js_fs.fileExistsAsync)(filePath)) try {
@@ -622,11 +881,12 @@ var JSONFileLog = class extends FileLog {
 			}
 		}
 		this.onSave();
+		await this.afterWrite();
 	}
 };
 
 //#endregion
-//#region ../logger/src/channels/sentry-log.ts
+//#region ../../packages/logger/src/channels/sentry-log.ts
 let Sentry;
 let isModuleExists = null;
 let loadingPromise;
@@ -823,7 +1083,7 @@ var SentryLog = class extends LogChannel {
 };
 
 //#endregion
-//#region ../logger/src/redact/default-keys.ts
+//#region ../../packages/logger/src/redact/default-keys.ts
 /**
 * Built-in secret-key denylist — the redaction floor that applies with no
 * configuration at all.
@@ -937,7 +1197,7 @@ const DEFAULT_REDACT_KEYS = [
 const DEFAULT_REDACT_KEY_SET = new Set(DEFAULT_REDACT_KEYS.map(normalizeRedactKey));
 
 //#endregion
-//#region ../logger/src/redact/redact.ts
+//#region ../../packages/logger/src/redact/redact.ts
 const DEFAULT_CENSOR = "[REDACTED]";
 /**
 * Values we copy by reference rather than walking. Expanding these with
@@ -1201,7 +1461,110 @@ function mergeRedact(base, extra) {
 }
 
 //#endregion
-//#region ../logger/src/utils/clear-message.ts
+//#region ../../packages/logger/src/redact/escape-log-value.ts
+/**
+* ANSI escape sequences: CSI (`ESC [ … final`) and the two-character
+* `ESC x` escapes (`ESC c` resets a terminal). Bounded so matching stays linear on long input.
+*/
+const ANSI_ESCAPE = /\u001b(?:\[[0-?]{0,32}[ -/]{0,8}[@-~]|[0-~])/g;
+/** Control characters that are not already handled as `\r`, `\n` or `\t`. */
+const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u2028\u2029]/g;
+/**
+* Make client-controlled text safe to put inside a log line: line breaks and
+* tabs become the visible escapes `\r`, `\n`, `\t`, other control characters
+* (including NUL, DEL, C1 controls and the Unicode line/paragraph separators)
+* become `\uXXXX`, and ANSI terminal escape sequences are removed.
+*
+* Without it, a user agent or form field containing `\n2026-01-01 [info] …`
+* writes a forged entry into a text log, and an ANSI sequence can rewrite what
+* a terminal shows. Structured channels (JSON) are not affected, but console
+* and file channels are.
+*
+* @example
+* log.info("auth", "login", `Login from ${escapeLogValue(request.userAgent)}`);
+*/
+function escapeLogValue(value, options = {}) {
+	let text = typeof value === "string" ? value : String(value);
+	const maxLength = options.maxLength;
+	let truncated = false;
+	if (maxLength !== void 0 && maxLength >= 0 && text.length > maxLength) {
+		text = text.slice(0, maxLength);
+		truncated = true;
+	}
+	const escaped = text.replace(ANSI_ESCAPE, "").replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\t/g, "\\t").replace(CONTROL, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+	return truncated ? `${escaped}…[truncated]` : escaped;
+}
+
+//#endregion
+//#region ../../packages/logger/src/redact/mask-email.ts
+/**
+* Email addresses inside free text: a local part and a dotted domain, letters
+* and digits from any script (`jöhn@exämple.de`). Kept deliberately simple (no
+* quoted local parts, no IP-literal domains, no percent-encoded `@`): it masks
+* the addresses that show up in log messages and cache keys, not every string
+* RFC 5322 allows.
+*
+* Every repetition is bounded (local part 64, label 63, at most 12 labels), so
+* matching stays linear in the input length. Cache keys and messages are often
+* built from request input; an unbounded pattern backtracks quadratically on a
+* long run of address-like characters with no domain.
+*/
+const EMAIL_IN_TEXT = /[\p{L}\p{N}._%+-]{1,64}@[\p{L}\p{N}-]{1,63}(?:\.[\p{L}\p{N}-]{1,63}){0,10}\.\p{L}{2,63}/gu;
+/**
+* Longest text {@link maskEmailsInText} scans. Anything past it is cut off and
+* replaced by a marker, so a huge cache key or message cannot cost more than a
+* bounded amount of time per log line, and nothing past the cut can leak.
+*/
+const MASK_EMAILS_MAX_LENGTH = 16384;
+/**
+* Mask one email address, keeping its first character and its domain:
+* `member@example.com` → `m***@example.com`. A value without an `@` is
+* returned as `***`.
+*
+* Key-based redaction cannot reach an address that sits inside a message
+* string or a cache key; mask it before it is logged.
+*
+* @example
+* log.info("mail", "send", `Sending mail to: ${maskEmail(to)}`);
+*/
+function maskEmail(address) {
+	const at = address.lastIndexOf("@");
+	if (at <= 0) return "***";
+	return `${String.fromCodePoint(address.codePointAt(0))}***${address.slice(at)}`;
+}
+/**
+* Mask every email address the pattern above recognises in a piece of text
+* with {@link maskEmail}. Text longer than {@link MASK_EMAILS_MAX_LENGTH}
+* characters is truncated first (the cut is marked).
+*
+* Dots are valid in the local part of an address, so a dotted prefix that
+* runs into the address is masked with it: in a cache key such as
+* `email.member@example.com` the whole `email.member` reads as the local part.
+*
+* Not recognised (left as they are): quoted local parts (`"john doe"@x.com`),
+* IP-literal domains (`user@[127.0.0.1]`) and percent-encoded addresses
+* (`user%40example.com`).
+*
+* @example
+* maskEmailsInText("sent to member@example.com") // "sent to m***@example.com"
+* maskEmailsInText("email.member@example.com") // "e***@example.com"
+*/
+function maskEmailsInText(text) {
+	let scanned = text;
+	let marker = "";
+	if (scanned.length > 16384) {
+		let cut = MASK_EMAILS_MAX_LENGTH;
+		const last = scanned.charCodeAt(cut - 1);
+		if (last >= 55296 && last <= 56319) cut -= 1;
+		marker = `…[${scanned.length - cut} chars truncated]`;
+		scanned = scanned.slice(0, cut);
+	}
+	if (!scanned.includes("@")) return scanned + marker;
+	return scanned.replace(EMAIL_IN_TEXT, (match) => maskEmail(match)) + marker;
+}
+
+//#endregion
+//#region ../../packages/logger/src/utils/clear-message.ts
 /**
 * Clear message from any terminal codes
 */
@@ -1211,7 +1574,7 @@ function clearMessage(message) {
 }
 
 //#endregion
-//#region ../logger/src/logger.ts
+//#region ../../packages/logger/src/logger.ts
 const SIGNAL_EVENTS = new Set([
 	"SIGINT",
 	"SIGTERM",
@@ -1239,22 +1602,39 @@ var Logger = class {
 		this.channels = [];
 		this.id = "logger-" + _mongez_reinforcements.Random.string(32);
 		this.autoFlushHandlers = /* @__PURE__ */ new Map();
+		this.pendingDeliveries = /* @__PURE__ */ new Map();
+		this.channelErrorHandler = reportChannelError;
 	}
 	/**
 	* Add a new channel
 	*/
 	addChannel(channel) {
-		this.channels.push(channel);
+		this.channels.push(this.attachChannel(channel));
 		return this;
 	}
 	/**
 	* Set base configurations
 	*/
 	configure(config) {
-		if (config.channels) this.channels = config.channels;
+		if (config.channels) this.setChannels(config.channels);
 		if (config.autoFlushOn) this.enableAutoFlush(config.autoFlushOn);
 		if (config.minLevel !== void 0) this.setMinLevel(config.minLevel);
 		if (config.redact !== void 0) this.setRedact(config.redact);
+		if (config.onChannelError) this.onChannelError(config.onChannelError);
+		return this;
+	}
+	/**
+	* Handle a channel's delivery failure. Logging is fire-and-forget, so a
+	* channel that throws or rejects never reaches the call site and never
+	* becomes an unhandled rejection; it goes to this handler instead. The
+	* default writes one line to stderr. The handler must not log through this
+	* logger (a failing channel would loop).
+	*
+	* @example
+	* log.onChannelError((error, channel) => metrics.increment(`log.${channel.name}.failed`));
+	*/
+	onChannelError(handler) {
+		this.channelErrorHandler = handler;
 		return this;
 	}
 	/**
@@ -1303,9 +1683,18 @@ var Logger = class {
 	*/
 	setChannels(channels) {
 		this.channels = channels;
+		for (const channel of channels) this.attachChannel(channel);
 		return this;
 	}
 	/**
+	* Route a channel's own failures (outside `log()`, such as file retention)
+	* to this logger's channel error handler.
+	*/
+	attachChannel(channel) {
+		if (typeof channel.setErrorReporter === "function") channel.setErrorReporter((error, entry) => this.reportChannelError(error, channel, entry));
+		return channel;
+	}
+	/**
 	* Normalize log data to a single object
 	*/
 	normalizeLogData(dataOrModule, action, message = "", level, context) {
@@ -1332,21 +1721,62 @@ var Logger = class {
 	* — each channel sees its own shallow clone so one channel cannot observe
 	* another's mutations (e.g. a later terminal channel still sees the original
 	* colored message).
+	*
+	* Synchronous and fire-and-forget: it returns the logger, not a promise.
+	* Async channel deliveries are tracked and awaited by {@link flush}; a
+	* channel that throws or rejects is isolated from the others and reported
+	* to {@link onChannelError}.
 	*/
-	async log(data) {
+	log(data) {
 		if (this.minLevel && LEVEL_RANK[data.type] < LEVEL_RANK[this.minLevel]) return this;
-		const baseEntry = applyRedact(data, this.redactConfig);
-		for (const channel of this.channels) {
+		let baseEntry;
+		try {
+			baseEntry = applyRedact(data, this.redactConfig);
+		} catch (error) {
+			for (const channel of this.channels) this.reportChannelError(error, channel, redactionFailedEntry(data));
+			return this;
+		}
+		for (const channel of this.channels) this.deliver(channel, data, baseEntry);
+		return this;
+	}
+	/**
+	* Prepare and hand one entry to one channel, isolating its failure (a
+	* channel redaction that throws included) and tracking an async delivery
+	* until it settles.
+	*/
+	deliver(channel, data, baseEntry) {
+		let payload = baseEntry;
+		let result;
+		try {
 			const channelRedact = channel.getRedactConfig?.();
-			const effectiveRedact = channelRedact ? mergeRedact(this.redactConfig, channelRedact) : void 0;
-			let payload = effectiveRedact ? applyRedact(data, effectiveRedact) : baseEntry;
+			if (channelRedact) payload = applyRedact(data, mergeRedact(this.redactConfig, channelRedact));
 			if (channel.terminal === false) payload = {
 				...payload,
 				message: clearMessage(payload.message)
 			};
-			channel.log(payload);
+			result = channel.log(payload);
+		} catch (error) {
+			this.reportChannelError(error, channel, payload);
+			return;
 		}
-		return this;
+		if (!result || typeof result.then !== "function") return;
+		let pending = this.pendingDeliveries.get(channel);
+		if (!pending) {
+			pending = /* @__PURE__ */ new Set();
+			this.pendingDeliveries.set(channel, pending);
+		}
+		const tracked = pending;
+		const delivery = Promise.resolve(result).catch((error) => this.reportChannelError(error, channel, payload)).finally(() => {
+			tracked.delete(delivery);
+			if (tracked.size === 0 && this.pendingDeliveries.get(channel) === tracked) this.pendingDeliveries.delete(channel);
+		});
+		tracked.add(delivery);
+	}
+	reportChannelError(error, channel, entry) {
+		try {
+			const outcome = this.channelErrorHandler(error, channel, entry);
+			if (outcome && typeof outcome.then === "function") outcome.then(void 0, () => {});
+		} catch {}
 	}
 	/**
 	* Make debug log
@@ -1442,7 +1872,9 @@ var Logger = class {
 		for (const channel of this.channels) if (channel.flushSync) channel.flushSync();
 	}
 	/**
-	* Asynchronously drain every channel that implements `flush()`.
+	* Wait for every in-flight async delivery, then drain every channel that
+	* implements `flush()` — bounded by `timeout` (default
+	* {@link DEFAULT_FLUSH_TIMEOUT_MS}).
 	*
 	* Unlike {@link flushSync}, this awaits each channel's async I/O — the
 	* correct call for a graceful shutdown that can afford to wait
@@ -1450,24 +1882,68 @@ var Logger = class {
 	* `process.exit`). A channel whose delivery is async (a network transport,
 	* an async disk write) implements `flush()`, not `flushSync()`.
 	*
-	* Channels are isolated: a channel whose flush rejects can neither prevent
-	* the others from draining nor escape as an unhandled rejection. Channels
-	* without `flush()` are skipped.
+	* Channels drain concurrently and independently: each waits for its own
+	* pending deliveries (including ones logged while the flush runs), then
+	* runs its `flush()`. A channel whose delivery hangs therefore cannot hold
+	* up another channel's drain, and a channel whose flush rejects can neither
+	* stop the others nor escape as an unhandled rejection. When `timeout`
+	* elapses, `flush()` resolves anyway and each channel still draining is
+	* reported to {@link onChannelError}. Channels without `flush()` only wait
+	* for their deliveries.
 	*
 	* @example
 	* async function shutdown() {
 	*   await httpServer.close();
-	*   await log.flush();
+	*   await log.flush({ timeout: 3000 });
 	*   process.exit(0);
 	* }
 	*/
-	async flush() {
-		await Promise.allSettled(this.channels.map(async (channel) => {
-			if (!channel.flush) return;
+	async flush(options = {}) {
+		const timeout = options.timeout ?? 5e3;
+		const draining = new Set(this.channels);
+		for (const channel of this.pendingDeliveries.keys()) draining.add(channel);
+		const unfinished = new Set(draining);
+		const drains = [...draining].map(async (channel) => {
 			try {
-				await channel.flush();
-			} catch {}
-		}));
+				await this.drainChannel(channel);
+			} catch {} finally {
+				unfinished.delete(channel);
+			}
+		});
+		const settled = Promise.allSettled(drains).then(() => false);
+		if (!Number.isFinite(timeout)) {
+			await settled;
+			return;
+		}
+		let resolveTimeout;
+		const timeoutReached = new Promise((resolve) => {
+			resolveTimeout = resolve;
+		});
+		const timer = setTimeout(() => resolveTimeout(true), Math.max(0, timeout));
+		timer.unref?.();
+		const timedOut = await Promise.race([settled, timeoutReached]);
+		clearTimeout(timer);
+		if (!timedOut) return;
+		for (const channel of unfinished) this.reportChannelError(/* @__PURE__ */ new Error(`flush timed out after ${timeout}ms; entries still in flight may be lost`), channel, {
+			type: "warn",
+			module: "logger",
+			action: "flush",
+			message: "flush timed out"
+		});
+	}
+	/**
+	* Wait until the channel has no delivery in flight, run its `flush()`, and
+	* repeat while that flush let new deliveries in.
+	*/
+	async drainChannel(channel) {
+		do {
+			let pending = this.pendingDeliveries.get(channel);
+			while (pending && pending.size > 0) {
+				await Promise.allSettled([...pending]);
+				pending = this.pendingDeliveries.get(channel);
+			}
+			if (channel.flush) await channel.flush();
+		} while ((this.pendingDeliveries.get(channel)?.size ?? 0) > 0);
 	}
 	/**
 	* Register one process-level handler per event that calls `flushSync()`
@@ -1513,6 +1989,34 @@ var Logger = class {
 	}
 };
 /**
+* Default `timeout` of {@link Logger.flush}: long enough for a healthy network
+* channel, short enough that a hung one cannot eat a shutdown budget.
+*/
+const DEFAULT_FLUSH_TIMEOUT_MS = 5e3;
+/**
+* What the error handler receives when the logger-wide redaction itself
+* failed: the entry's identity only, never the unredacted message or context.
+*/
+function redactionFailedEntry(data) {
+	return {
+		type: data.type,
+		module: data.module,
+		action: data.action,
+		message: "[entry dropped: redaction failed]"
+	};
+}
+/**
+* Default {@link ChannelErrorHandler}: one stderr line per failure. Written
+* directly to the stream, never through a logger, so a broken channel cannot
+* recurse.
+*/
+function reportChannelError(error, channel) {
+	const reason = error instanceof Error ? error.message : String(error);
+	try {
+		process.stderr.write(`[@warlock.js/logger] channel "${channel.name}" failed to log: ${reason}\n`);
+	} catch {}
+}
+/**
 * The package singleton. Use this for everyday logging — `log.info(...)`,
 * `log.error(...)`, `log.configure(...)`. Custom logger instances can be
 * created by instantiating `Logger` directly.
@@ -1529,7 +2033,7 @@ var Logger = class {
 const log = new Logger();
 
 //#endregion
-//#region ../logger/src/utils/capture-unhandled-errors.ts
+//#region ../../packages/logger/src/utils/capture-unhandled-errors.ts
 /**
 * Best-effort budget (ms) for draining async channels (file, Sentry, …) before
 * the forced exit. Bounded so a single stuck channel can't hang the process —
@@ -1579,17 +2083,25 @@ function captureAnyUnhandledRejection(options = {}) {
 
 //#endregion
 exports.ConsoleLog = ConsoleLog;
+exports.DAILY_FILE_NAME = DAILY_FILE_NAME;
+exports.DEFAULT_FLUSH_TIMEOUT_MS = DEFAULT_FLUSH_TIMEOUT_MS;
 exports.DEFAULT_REDACT_KEYS = DEFAULT_REDACT_KEYS;
 exports.DEFAULT_REDACT_KEY_SET = DEFAULT_REDACT_KEY_SET;
 exports.FileLog = FileLog;
+exports.HOURLY_FILE_NAME = HOURLY_FILE_NAME;
 exports.JSONFileLog = JSONFileLog;
 exports.LogChannel = LogChannel;
 exports.Logger = Logger;
+exports.MASK_EMAILS_MAX_LENGTH = MASK_EMAILS_MAX_LENGTH;
+exports.ROTATE_FILE_NAME = ROTATE_FILE_NAME;
 exports.SentryLog = SentryLog;
 exports.applyRedact = applyRedact;
 exports.captureAnyUnhandledRejection = captureAnyUnhandledRejection;
 exports.clearMessage = clearMessage;
+exports.escapeLogValue = escapeLogValue;
 exports.log = log;
+exports.maskEmail = maskEmail;
+exports.maskEmailsInText = maskEmailsInText;
 exports.mergeRedact = mergeRedact;
 exports.normalizeRedactKey = normalizeRedactKey;
 exports.resolveRedactKeys = resolveRedactKeys;