@warlock.js/logger 5.30.0 → 5.31.0

package/CHANGELOG.md

@@ -4,15 +4,35 @@ All notable changes to `@warlock.js/logger` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.31.0 - 2026-10-18
+
+### Upgrading
+
+- **BREAKING:** `FileLog`/`JSONFileLog` dated file names are ISO dates that sort by name: `chunk: "daily"` writes `YYYY-MM-DD.log` (was `DD-MM-YYYY.log`) and `chunk: "hourly"` writes `YYYY-MM-DD-HH.log` (was `DD-MM-YYYY-HH-00-00-am.log`). Size-rotated archives default to `<file name>-YYYY-MM-DD-<epoch ms>`. After upgrading, a running daily channel starts a new file under the new name. To keep the old names, set `fileName: "{DD}-{MM}-{YYYY}"` (daily) and `rotateFileName: "{DD}-{MM}-{YYYY}"`. Tools that find logs by name (shippers, cron cleanups) need the new pattern; `retention` does not remove files with the old names.
+- `rotateFileName` is now a `{YYYY}`/`{MM}`/`{DD}`/`{HH}`/`{mm}`/`{name}` pattern or a function of the rotation date, not a Day.js format. A value without tokens is used as is, as before; a Day.js format such as `"DD-MM-YYYY"` was always written literally and still is — use `"{DD}-{MM}-{YYYY}"`.
+
+### Added
+
+- `FileLog` `fileName` option: a pattern (`"app-{YYYY}-{MM}-{DD}"`, tokens `{YYYY}` `{MM}` `{DD}` `{HH}` `{mm}` `{name}` in local time) or a `(date) => string` function, evaluated at every write; it replaces the chunk's default name. `rotateFileName` takes the same forms and is rendered at each rotation (a getter passed in the config was read once, at construction, so every archive kept the boot date). Exported `FileNameOption`, `FileLogRetention`, `DAILY_FILE_NAME`, `HOURLY_FILE_NAME` and `ROTATE_FILE_NAME`.
+- `FileLog` `retention: { maxFiles?, maxAgeDays?, match? }`: removes old log files on boot and whenever the channel starts a new file (a size rotation or a dated name rolling over), plus `channel.prune()` on demand. It only considers files in the log directory (each group directory with `groupBy`) whose names match the channel's file name pattern, keeps the file being written, and reports failures to `onChannelError` instead of throwing. A function `fileName` needs `retention.match`. Invalid `maxFiles`/`maxAgeDays` throw a `TypeError` at construction.
+- `LogChannel.reportError(error, entry)` and `setErrorReporter(reporter)` (type `ChannelErrorReporter`): a channel reports failures outside `log()` to the `onChannelError` handler of the logger it was added to (`addChannel`, `setChannels`, `configure({ channels })`), or one stderr line without one.
+- `escapeLogValue(value, { maxLength? })` makes client-controlled text safe inside a log line: CR/LF/tab become visible `\r`/`\n`/`\t`, other control characters (NUL, DEL, C1, U+2028/U+2029) become `\uXXXX`, ANSI escape sequences are removed, and `maxLength` cuts with a `…[truncated]` marker. A user agent or form field can no longer forge entries in console or file logs.
+- Skills demonstrate email masking inside text, channel-error observation and bounded asynchronous log drains.
+
+### Fixed
+
+- With `groupBy`, size rotation renames the group file that grew too large instead of the ungrouped top-level file.
+- A file name that throws while a buffer is written (a `fileName` function, or an overridden `fileName` getter) is reported as a failed write instead of leaving the channel stuck in its writing state; later writes go through.
+
 ## 5.30.0 - 2026-10-16
 
 ### Upgrading
 
-- **BREAKING (types):** `log.info/warn/error/debug/success/fatal/log/assert` and the function `timer()` returns now return the logger synchronously instead of `Promise<this>`. Remove `await` before log calls (it is harmless but pointless) and any `.then()` chained on one; code that needs the write to finish calls `await log.flush()`.
+- **BREAKING (types):** `log.info/warn/error/debug/success/fatal/log/assert` and the function `timer()` returns now return the logger synchronously instead of `Promise<this>`. Remove `await` before log calls (it is harmless but pointless) and any `.then()` chained on one; code that needs the write to finish calls `await log.flush()`. `warlock upgrade --from 5.29 --to 5.31.0` removes the `await`s and lists chained `.then()` calls (codemod `logger-sync-calls`).
 
 ### Changed
 
-- Logging is fire-and-forget: level methods no longer return a promise, so `@typescript-eslint/no-floating-promises` no longer flags every call site (WR-019).
+- Logging is fire-and-forget: level methods no longer return a promise, so `@typescript-eslint/no-floating-promises` no longer flags every call site.
 - `log.flush()` drains every channel concurrently: each waits for its own in-flight async deliveries (including entries logged while the flush runs), then runs its `flush()`, so a hung network channel no longer holds up the file channel.
 - `log.flush({ timeout })` is bounded: it resolves after `timeout` ms (default 5000, `DEFAULT_FLUSH_TIMEOUT_MS`; `Infinity` waits without a limit) and reports each channel still draining to the channel error handler. Before, one delivery that never settled made `flush()` (and a graceful shutdown awaiting it) wait forever.
 - `maskEmailsInText` cuts text longer than `MASK_EMAILS_MAX_LENGTH` (16,384 characters) and marks the cut, so masking a huge cache key or message has a bounded cost.
@@ -20,7 +40,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Added
 
 - `log.onChannelError(handler)` / `configure({ onChannelError })` and the `ChannelErrorHandler` type: receives a channel's sync throw or async rejection from `log()`, a redaction that threw, or a timed-out `flush()`. Default: one stderr line. The handler may be async; a rejection is swallowed.
-- `maskEmail(address)` and `maskEmailsInText(text)`: mask email addresses (`m***@example.com`) inside message strings and cache keys, which key-based redaction cannot reach. Core's mail logs and the cache drivers' key logs use them (FW-04).
+- `maskEmail(address)` and `maskEmailsInText(text)`: mask email addresses (`m***@example.com`) inside message strings and cache keys, which key-based redaction cannot reach. Core's mail logs and the cache drivers' key logs use them.
 
 ### Fixed
 
@@ -100,6 +120,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Changed
 
 - Lockstep release maintenance and dependency refresh.
+
 ## 5.20.0 - 2026-09-24
 
 ### Changed
@@ -189,7 +210,7 @@ changelogs.
 
 ### Security
 
-- **Secrets are now redacted by default. This is a behavior change — logs that previously showed these values in cleartext will now show `[REDACTED]`.** Redaction used to be a *tool* (`redact.paths`, entirely opt-in): unless an application configured it, a `password` in `context`, an `authorization` header, or an `apiKey` on a logged `Error` reached every sink — console, log file, JSON log file, Sentry — verbatim. Protection existed only where every call site had been configured correctly, with no signal when one hadn't. It is now a *default*.
+- **Secrets are now redacted by default. This is a behavior change — logs that previously showed these values in cleartext will now show `[REDACTED]`.** Redaction used to be a _tool_ (`redact.paths`, entirely opt-in): unless an application configured it, a `password` in `context`, an `authorization` header, or an `apiKey` on a logged `Error` reached every sink — console, log file, JSON log file, Sentry — verbatim. Protection existed only where every call site had been configured correctly, with no signal when one hadn't. It is now a _default_.
 
   A built-in denylist (`DEFAULT_REDACT_KEYS`) censors matching keys at any depth of `context`, `message`, and an `Error`'s own enumerable properties, applied at the same logger-wide choke point as `redact.paths` — so every channel inherits it, including custom ones. The set covers passwords, shared secrets, tokens (access/refresh/id/CSRF/session), API and private keys, HTTP credential headers (`authorization`, `x-api-key`, `cookie`, `set-cookie`), session IDs, connection strings, and high-sensitivity financial PII (card numbers, CVV, SSN, IBAN).
 
@@ -204,7 +225,7 @@ changelogs.
 
   Paths are evaluated before keys, so a function `censor` on an explicit path still receives the original value rather than a mask, and that leaf is not censored twice.
 
-  Known residual gaps, unchanged by this release and documented on `applyRedact`: secrets interpolated into a `message` *string* (`` `token=${t}` ``) cannot be reached by either matcher; `Map` / `Set` / `Buffer` contents are not traversed; and properties exposed only via getters or non-enumerable descriptors are not walked, so an HTTP client that hides its request config behind a getter can still slip through. Enumerable ones — axios's `.config` / `.response`, which carry the outgoing `Authorization` header — *are* now covered.
+  Known residual gaps, unchanged by this release and documented on `applyRedact`: secrets interpolated into a `message` _string_ (`` `token=${t}` ``) cannot be reached by either matcher; `Map` / `Set` / `Buffer` contents are not traversed; and properties exposed only via getters or non-enumerable descriptors are not walked, so an HTTP client that hides its request config behind a getter can still slip through. Enumerable ones — axios's `.config` / `.response`, which carry the outgoing `Authorization` header — _are_ now covered.
 
 ### Fixed
 

package/README.md

@@ -23,10 +23,7 @@ yarn add @warlock.js/logger
 ```ts
 import { log, ConsoleLog, FileLog } from "@warlock.js/logger";
 
-log.setChannels([
-  new ConsoleLog(),
-  new FileLog({ chunk: "daily" }),
-]);
+log.setChannels([new ConsoleLog(), new FileLog({ chunk: "daily" })]);
 
 log.info("users", "register", "New user created");
 log.error("payments", "charge", new Error("Card declined"));
@@ -61,12 +58,12 @@ log.error({
 
 ## Built-in channels
 
-| Channel | Name | Purpose |
-|---|---|---|
-| `ConsoleLog` | `"console"` | Colorized terminal output |
-| `FileLog` | `"file"` | Plain-text files, optional chunking + rotation + grouping |
-| `JSONFileLog` | `"fileJson"` | Structured JSON files — ideal for aggregators |
-| `SentryLog` | `"sentry"` | Forwards to Sentry (events + breadcrumbs); needs the optional `@sentry/node` peer |
+| Channel       | Name         | Purpose                                                                           |
+| ------------- | ------------ | --------------------------------------------------------------------------------- |
+| `ConsoleLog`  | `"console"`  | Colorized terminal output                                                         |
+| `FileLog`     | `"file"`     | Plain-text files, optional chunking + rotation + grouping                         |
+| `JSONFileLog` | `"fileJson"` | Structured JSON files — ideal for aggregators                                     |
+| `SentryLog`   | `"sentry"`   | Forwards to Sentry (events + breadcrumbs); needs the optional `@sentry/node` peer |
 
 All channels share the `BasicLogConfigurations` options (`levels`, `filter`, `dateFormat`); `FileLog` / `JSONFileLog` add storage, chunking, rotation, and grouping options, and `SentryLog` adds `client` / `options` / `eventLevels`.
 
@@ -74,7 +71,7 @@ All channels share the `BasicLogConfigurations` options (`levels`, `filter`, `da
 
 The package exports one default singleton and one class:
 
-- **`log`** — a pre-instantiated `Logger`. Day-to-day logging *and* configuration both go through it: `log.info(...)`, `log.configure(...)`, `log.flush()` / `log.flushSync()`, `log.addChannel(...)`.
+- **`log`** — a pre-instantiated `Logger`. Day-to-day logging _and_ configuration both go through it: `log.info(...)`, `log.configure(...)`, `log.flush()` / `log.flushSync()`, `log.addChannel(...)`.
 - **`Logger`** — the class. Use it when you need an isolated logger (libraries, sandboxes, parallel test suites).
 
 `log` is a `Logger` instance, not a function — every level shortcut and configuration method is reachable on it. The bare-callable `log(data)` form was removed; use `log.log(data)` for the data-object form, or `log.info(...)` / `log.error(...)` / etc. for the positional form.

package/cjs/index.cjs

@@ -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) {
@@ -194,8 +216,54 @@ var ConsoleLog = class extends LogChannel {
 	}
 };
 
+//#endregion
+//#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,6 +696,16 @@ 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 ../../packages/logger/src/utils/safe-json-stringify.ts
@@ -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,6 +881,7 @@ var JSONFileLog = class extends FileLog {
 			}
 		}
 		this.onSave();
+		await this.afterWrite();
 	}
 };
 
@@ -1200,6 +1460,41 @@ function mergeRedact(base, extra) {
 	};
 }
 
+//#endregion
+//#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
 /**
@@ -1314,14 +1609,14 @@ var Logger = class {
 	* 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);
@@ -1388,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) {
@@ -1779,18 +2083,22 @@ 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;