nanos-lint 2.6.1 → 2.7.0

package/dist/{cli-5LLXRlN7.js → cli-sEO_MZ-K.js}

@@ -6,6 +6,67 @@ import process$1 from "node:process";
 import childProcess, { execFile, execFileSync } from "node:child_process";
 import { promisify, stripVTControlCharacters } from "node:util";
 import { EventEmitter } from "node:events";
+//#region src/logger.ts
+const LOG_LEVELS = [
+	"silent",
+	"error",
+	"warn",
+	"info",
+	"debug"
+];
+const LOG_LEVEL_PRIORITY = {
+	silent: 0,
+	error: 1,
+	warn: 2,
+	info: 3,
+	debug: 4
+};
+const DEFAULT_LOG_LEVEL = "warn";
+function isValidLogLevel(level) {
+	return level in LOG_LEVEL_PRIORITY;
+}
+function parseLogLevel(raw) {
+	if (!raw) return DEFAULT_LOG_LEVEL;
+	const lower = raw.trim().toLowerCase();
+	return isValidLogLevel(lower) ? lower : DEFAULT_LOG_LEVEL;
+}
+var Logger = class {
+	level = DEFAULT_LOG_LEVEL;
+	constructor(initialLevel) {
+		if (initialLevel && isValidLogLevel(initialLevel)) this.level = initialLevel;
+		else {
+			const envLevel = process.env.NANOS_LOG_LEVEL;
+			if (envLevel && isValidLogLevel(envLevel.trim().toLowerCase())) this.level = envLevel.trim().toLowerCase();
+		}
+	}
+	setLevel(level) {
+		if (isValidLogLevel(level)) this.level = level;
+	}
+	getLevel() {
+		return this.level;
+	}
+	isEnabledFor(level) {
+		return LOG_LEVEL_PRIORITY[this.level] >= LOG_LEVEL_PRIORITY[level];
+	}
+	/** Whether command results should be written; only `silent` disables them. */
+	isOutputEnabled() {
+		return this.level !== "silent";
+	}
+	error(...args) {
+		if (this.isEnabledFor("error")) console.error(...args);
+	}
+	warn(...args) {
+		if (this.isEnabledFor("warn")) console.warn(...args);
+	}
+	info(...args) {
+		if (this.isEnabledFor("info")) console.log(...args);
+	}
+	debug(...args) {
+		if (this.isEnabledFor("debug")) console.debug(...args);
+	}
+};
+const logger = new Logger();
+//#endregion
 //#region src/types.ts
 /**
 * Converts a URI (e.g. `file:///path/to/file` or `file:///C:/path/to/file` or `file:///c%3A/path` or `file://server/share/file`)
@@ -18,11 +79,14 @@ function fileUriToPath(uri) {
 		if (/^\/[a-zA-Z]:/.test(res)) res = res.slice(1);
 		if (/^[a-zA-Z]:/.test(res)) res = res.charAt(0).toUpperCase() + res.slice(1);
 		return res;
-	} catch {
+	} catch (err) {
+		logger.debug(`fileURLToPath fallback for URI "${uri}": ${err instanceof Error ? err.message : String(err)}`);
 		let decoded = uri.slice(7);
 		try {
 			decoded = decodeURIComponent(decoded);
-		} catch {}
+		} catch (decodeErr) {
+			logger.warn(`decodeURIComponent failed for path "${decoded}": ${decodeErr instanceof Error ? decodeErr.message : String(decodeErr)}`);
+		}
 		if (decoded.startsWith("//")) return decoded;
 		if (!decoded.startsWith("/") && uri.startsWith("file://") && !uri.startsWith("file:///")) return `//${decoded}`;
 		if (/^\/[a-zA-Z]:/.test(decoded)) decoded = decoded.slice(1);
@@ -949,7 +1013,9 @@ function mergeConfigs(base, override = {}, definitionsPath = getDefaultAnnotatio
 			const candidate = path.join(definitionsPath, "annotations.lua");
 			if (fs.existsSync(candidate)) resolvedPath = candidate;
 		}
-	} catch {}
+	} catch (err) {
+		logger.debug(`Error checking annotations definitionsPath directory (${definitionsPath}): ${err instanceof Error ? err.message : String(err)}`);
+	}
 	const normalizedDefPath = resolvedPath.split(path.sep).join("/");
 	const baseLibraries = base.workspace?.library ?? [];
 	const overrideLibraries = override.workspace?.library ?? [];
@@ -1162,9 +1228,10 @@ function escapePowerShellSingleQuote(str) {
 	return str.replace(/'/g, "''");
 }
 /**
-* Resolves the latest available LuaLS release tag from the GitHub API.
+* Fetches the latest available LuaLS release tag from the GitHub API.
+* Returns null if the request fails, times out, or receives an invalid tag.
 */
-async function resolveLatestLuaLSVersion() {
+async function fetchLatestLuaLSVersionFromGitHub() {
 	try {
 		const headers = { "User-Agent": "nanos-lint" };
 		if (process.env.GITHUB_TOKEN) headers["Authorization"] = `token ${process.env.GITHUB_TOKEN}`;
@@ -1177,8 +1244,17 @@ async function resolveLatestLuaLSVersion() {
 			const version = typeof data.tag_name === "string" ? sanitizeLuaLSVersion(data.tag_name) : null;
 			if (version) return version;
 		}
-	} catch {}
-	return FALLBACK_LUALS_VERSION;
+	} catch (err) {
+		logger.debug(`[luals] Failed to resolve latest LuaLS version from GitHub API: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return null;
+}
+/**
+* Resolves the latest available LuaLS release tag from the GitHub API,
+* falling back to FALLBACK_LUALS_VERSION if offline or unreachable.
+*/
+async function resolveLatestLuaLSVersion() {
+	return await fetchLatestLuaLSVersionFromGitHub() || "3.19.1";
 }
 /**
 * Resolves a version string ("latest" -> actual tag).
@@ -1226,8 +1302,15 @@ function getPlatformInfo(version = FALLBACK_LUALS_VERSION) {
 	};
 	throw new Error(`Unsupported platform: ${platform}`);
 }
-function getCacheDir(version = FALLBACK_LUALS_VERSION) {
-	return path.join(systemPaths.cache, "luals", version);
+function getBaseLuaLSCacheDir() {
+	return path.join(systemPaths.cache, "luals");
+}
+/**
+* Cache directory of a LuaLS version. `baseCacheDir` defaults to the system
+* cache and can be overridden to keep a caller isolated from it.
+*/
+function getCacheDir(version = FALLBACK_LUALS_VERSION, baseCacheDir = getBaseLuaLSCacheDir()) {
+	return path.join(baseCacheDir, version);
 }
 /**
 * Returns the legacy cache directory used in nanos-lint <= 2.2.1.
@@ -1236,6 +1319,131 @@ function getLegacyCacheDir(version = FALLBACK_LUALS_VERSION) {
 	const base = process.platform === "win32" ? process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local") : process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
 	return path.join(base, "nanos-lint", "luals", version);
 }
+const LUALS_METADATA_FILENAME = "metadata.json";
+/**
+* Calculates the ISO 8601 week string for a given date in the format 'YYYY-Www' (e.g. '2026-W39').
+*/
+function getIsoWeek(d = /* @__PURE__ */ new Date()) {
+	const date = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+	const dayNum = date.getUTCDay() || 7;
+	date.setUTCDate(date.getUTCDate() + 4 - dayNum);
+	const yearStart = new Date(Date.UTC(date.getUTCFullYear(), 0, 1));
+	const weekNo = Math.ceil(((date.getTime() - yearStart.getTime()) / 864e5 + 1) / 7);
+	return `${date.getUTCFullYear()}-W${String(weekNo).padStart(2, "0")}`;
+}
+function getLuaLSMetadataPath(baseCacheDir = getBaseLuaLSCacheDir()) {
+	return path.join(baseCacheDir, LUALS_METADATA_FILENAME);
+}
+function readLuaLSMetadata(baseCacheDir = getBaseLuaLSCacheDir()) {
+	const metaPath = getLuaLSMetadataPath(baseCacheDir);
+	if (!fs.existsSync(metaPath)) return null;
+	try {
+		const content = fs.readFileSync(metaPath, "utf-8");
+		const parsed = JSON.parse(content);
+		if (typeof parsed?.lastCheckedWeek === "string" && typeof parsed?.latestVersion === "string") return parsed;
+	} catch (err) {
+		logger.debug(`[luals] Failed to parse LuaLS metadata: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return null;
+}
+function writeLuaLSMetadata(metadata, baseCacheDir = getBaseLuaLSCacheDir()) {
+	try {
+		fs.mkdirSync(baseCacheDir, { recursive: true });
+		const metaPath = getLuaLSMetadataPath(baseCacheDir);
+		fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2), "utf-8");
+	} catch (err) {
+		logger.warn(`[luals] Failed to write LuaLS metadata: ${err instanceof Error ? err.message : String(err)}`);
+	}
+}
+/**
+* Lists all cached LuaLS versions in baseCacheDir that have a valid .complete marker
+* and a functional executable binary.
+*/
+function listCachedLuaLSVersions(baseCacheDir = getBaseLuaLSCacheDir()) {
+	if (!fs.existsSync(baseCacheDir)) return [];
+	try {
+		const entries = fs.readdirSync(baseCacheDir, { withFileTypes: true });
+		const versions = [];
+		for (const entry of entries) {
+			if (!entry.isDirectory() || entry.name.startsWith(".")) continue;
+			const version = sanitizeLuaLSVersion(entry.name);
+			if (!version) continue;
+			const dirPath = path.join(baseCacheDir, entry.name);
+			const marker = path.join(dirPath, ".complete");
+			const info = getPlatformInfo(version);
+			const bin = path.join(dirPath, info.binaryRelativePath);
+			if (fs.existsSync(marker) && fs.existsSync(bin)) try {
+				if (fs.readFileSync(marker, "utf-8").trim() === version && isBinaryValid(bin)) versions.push(version);
+			} catch (err) {
+				logger.debug(`[luals] Error validating cached version ${version}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}
+		return versions;
+	} catch (err) {
+		logger.debug(`[luals] Failed to list cached LuaLS versions: ${err instanceof Error ? err.message : String(err)}`);
+		return [];
+	}
+}
+/**
+* Removes older cached LuaLS version directories, preserving keepVersion,
+* hidden/temporary directories, and metadata files.
+*/
+function cleanupOldCachedLuaLSVersions(keepVersion, baseCacheDir = getBaseLuaLSCacheDir()) {
+	if (!fs.existsSync(baseCacheDir)) return [];
+	const removed = [];
+	try {
+		const entries = fs.readdirSync(baseCacheDir, { withFileTypes: true });
+		for (const entry of entries) {
+			if (!entry.isDirectory()) continue;
+			if (entry.name.startsWith(".")) continue;
+			if (entry.name !== keepVersion) {
+				const dirPath = path.join(baseCacheDir, entry.name);
+				try {
+					fs.rmSync(dirPath, {
+						recursive: true,
+						force: true,
+						maxRetries: 5,
+						retryDelay: 100
+					});
+					removed.push(entry.name);
+					logger.info(`[luals] Cleaned up older cached LuaLS version: ${entry.name}`);
+				} catch (err) {
+					logger.warn(`[luals] Failed to remove older cached LuaLS version at ${dirPath}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+			}
+		}
+	} catch (err) {
+		logger.debug(`[luals] Failed to clean up old LuaLS versions: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	return removed;
+}
+/**
+* Locates an existing, valid LuaLS directory for the specified version in the
+* primary cache (`baseCacheDir`), the legacy cache, or the package root.
+*/
+function findExistingLuaLSDir(version, baseCacheDir = getBaseLuaLSCacheDir()) {
+	const info = getPlatformInfo(version);
+	const primaryCache = getCacheDir(version, baseCacheDir);
+	const primaryBin = path.join(primaryCache, info.binaryRelativePath);
+	const primaryMarker = path.join(primaryCache, ".complete");
+	if (fs.existsSync(primaryMarker)) try {
+		if (fs.readFileSync(primaryMarker, "utf-8").trim() === version && isBinaryValid(primaryBin)) return primaryCache;
+	} catch (err) {
+		logger.debug(`[luals] Error checking primary LuaLS cache marker at ${primaryMarker}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const legacyCache = getLegacyCacheDir(version);
+	const legacyBin = path.join(legacyCache, info.binaryRelativePath);
+	const legacyMarker = path.join(legacyCache, ".complete");
+	if (fs.existsSync(legacyMarker)) try {
+		if (fs.readFileSync(legacyMarker, "utf-8").trim() === version && isBinaryValid(legacyBin)) return legacyCache;
+	} catch (err) {
+		logger.debug(`[luals] Error checking legacy LuaLS cache marker at ${legacyMarker}: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const pkgRoot = getPackageRoot();
+	const pkgBin = path.join(pkgRoot, info.binaryRelativePath);
+	if (fs.existsSync(pkgBin) && isBinaryValid(pkgBin)) return pkgRoot;
+	return null;
+}
 /**
 * Verifies that a LuaLS binary exists, has non-trivial size, and is executable.
 */
@@ -1250,7 +1458,8 @@ function isBinaryValid(binaryPath) {
 			encoding: "utf-8"
 		});
 		return /^\d+\.\d+\.\d+/.test(output.trim());
-	} catch {
+	} catch (err) {
+		logger.debug(`[luals] Binary validation check failed for ${binaryPath}: ${err instanceof Error ? err.message : String(err)}`);
 		return false;
 	}
 }
@@ -1263,72 +1472,79 @@ async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDi
 	if (fs.existsSync(destDir)) {
 		if (fs.existsSync(binaryPath) && fs.existsSync(completeMarker)) try {
 			if (fs.readFileSync(completeMarker, "utf-8").trim() === resolvedVersion && isBinaryValid(binaryPath)) return binaryPath;
-		} catch {}
+		} catch (err) {
+			logger.debug(`[luals] Failed to read complete marker at ${completeMarker}: ${err instanceof Error ? err.message : String(err)}`);
+		}
 		try {
 			fs.rmSync(destDir, {
 				recursive: true,
 				force: true
 			});
-		} catch {}
+		} catch (err) {
+			logger.warn(`[luals] Failed to remove stale or invalid cache dir ${destDir}: ${err instanceof Error ? err.message : String(err)}`);
+		}
 	}
 	const parentDir = path.dirname(destDir);
 	fs.mkdirSync(parentDir, { recursive: true });
 	const tempDir = path.join(parentDir, `.${path.basename(destDir)}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
 	fs.mkdirSync(tempDir, { recursive: true });
+	const existingSourceDir = options?.reuseExisting !== false ? findExistingLuaLSDir(resolvedVersion, options?.cacheDir ?? getBaseLuaLSCacheDir()) : null;
+	const shouldCopyFromExisting = existingSourceDir !== null && path.resolve(existingSourceDir) !== path.resolve(destDir);
 	const url = `https://github.com/LuaLS/lua-language-server/releases/download/${resolvedVersion}/${info.assetName}`;
 	const archivePath = path.join(tempDir, info.assetName);
-	if (!options?.quiet) console.log(`[luals] Downloading LuaLS ${resolvedVersion} from ${url}...`);
-	let response = null;
-	let lastErr = null;
-	for (let attempt = 1; attempt <= 3; attempt++) {
-		try {
-			const res = await fetch(url);
-			if (res.ok && res.body) {
-				response = res;
-				break;
-			}
-			await res.body?.cancel();
-			lastErr = /* @__PURE__ */ new Error(`Failed to download ${url}: ${res.status} ${res.statusText}`);
-		} catch (err) {
-			lastErr = err;
-		}
-		if (attempt < 3) await new Promise((resolve) => setTimeout(resolve, attempt * 1e3));
-	}
-	if (!response || !response.body) {
-		try {
-			fs.rmSync(tempDir, {
-				recursive: true,
-				force: true
-			});
-		} catch {}
-		throw lastErr || /* @__PURE__ */ new Error(`Failed to download ${url}`);
-	}
 	try {
-		const arrayBuffer = await response.arrayBuffer();
-		fs.writeFileSync(archivePath, Buffer.from(arrayBuffer));
-		if (!options?.quiet) console.log(`[luals] Extracting to ${destDir}...`);
-		try {
-			await execFileAsync("tar", [
-				"-xf",
-				archivePath,
-				"-C",
-				tempDir
-			]);
-		} catch (tarErr) {
-			if (process.platform === "win32" && info.assetName.endsWith(".zip")) await execFileAsync("powershell.exe", [
-				"-NoProfile",
-				"-Command",
-				`Expand-Archive -Path '${escapePowerShellSingleQuote(archivePath)}' -DestinationPath '${escapePowerShellSingleQuote(tempDir)}' -Force`
-			]);
-			else throw tarErr;
+		if (shouldCopyFromExisting) {
+			if (!options?.quiet) logger.info(`[luals] Reusing existing LuaLS ${resolvedVersion} installation from ${existingSourceDir}...`);
+			fs.cpSync(existingSourceDir, tempDir, { recursive: true });
+		} else {
+			if (!options?.quiet) logger.info(`[luals] Downloading LuaLS ${resolvedVersion} from ${url}...`);
+			let response = null;
+			let lastErr = null;
+			for (let attempt = 1; attempt <= 3; attempt++) {
+				try {
+					const res = await fetch(url);
+					if (res.ok && res.body) {
+						response = res;
+						break;
+					}
+					await res.body?.cancel();
+					lastErr = /* @__PURE__ */ new Error(`Failed to download ${url}: ${res.status} ${res.statusText}`);
+				} catch (err) {
+					lastErr = err;
+				}
+				if (attempt < 3) await new Promise((resolve) => setTimeout(resolve, attempt * 1e3));
+			}
+			if (!response || !response.body) throw lastErr || /* @__PURE__ */ new Error(`Failed to download ${url}`);
+			const arrayBuffer = await response.arrayBuffer();
+			fs.writeFileSync(archivePath, Buffer.from(arrayBuffer));
+			if (!options?.quiet) logger.info(`[luals] Extracting to ${destDir}...`);
+			try {
+				await execFileAsync("tar", [
+					"-xf",
+					archivePath,
+					"-C",
+					tempDir
+				]);
+			} catch (tarErr) {
+				if (process.platform === "win32" && info.assetName.endsWith(".zip")) await execFileAsync("powershell.exe", [
+					"-NoProfile",
+					"-Command",
+					`Expand-Archive -Path '${escapePowerShellSingleQuote(archivePath)}' -DestinationPath '${escapePowerShellSingleQuote(tempDir)}' -Force`
+				]);
+				else throw tarErr;
+			}
+			try {
+				fs.unlinkSync(archivePath);
+			} catch (err) {
+				logger.debug(`[luals] Failed to delete temporary archive ${archivePath}: ${err instanceof Error ? err.message : String(err)}`);
+			}
 		}
-		try {
-			fs.unlinkSync(archivePath);
-		} catch {}
 		const tempBinaryPath = path.join(tempDir, info.binaryRelativePath);
 		if (process.platform !== "win32") try {
 			fs.chmodSync(tempBinaryPath, 493);
-		} catch {}
+		} catch (err) {
+			logger.warn(`[luals] Failed to chmod binary at ${tempBinaryPath}: ${err instanceof Error ? err.message : String(err)}`);
+		}
 		if (!fs.existsSync(tempBinaryPath) || fs.statSync(tempBinaryPath).size < 1e5) throw new Error(`Failed to extract valid LuaLS binary to expected path: ${tempBinaryPath}`);
 		if (!isBinaryValid(tempBinaryPath)) throw new Error(`Extracted LuaLS binary at ${tempBinaryPath} is invalid or non-functional.`);
 		fs.writeFileSync(path.join(tempDir, ".complete"), resolvedVersion, "utf-8");
@@ -1342,8 +1558,10 @@ async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDi
 						recursive: true,
 						force: true
 					});
-				} catch {}
-				if (!options?.quiet) console.log(`[luals] Ready: ${binaryPath}`);
+				} catch (err) {
+					logger.debug(`[luals] Failed to remove temp directory after concurrent promotion: ${err instanceof Error ? err.message : String(err)}`);
+				}
+				if (!options?.quiet) logger.info(`[luals] Ready: ${binaryPath}`);
 				return binaryPath;
 			}
 			if (attempt < 4) await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
@@ -1353,11 +1571,13 @@ async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDi
 						recursive: true,
 						force: true
 					});
-				} catch {}
+				} catch (err) {
+					logger.warn(`[luals] Failed to clean up broken destination directory ${destDir}: ${err instanceof Error ? err.message : String(err)}`);
+				}
 				throw renameErr;
 			}
 		}
-		if (!options?.quiet) console.log(`[luals] Ready: ${binaryPath}`);
+		if (!options?.quiet) logger.info(`[luals] Ready: ${binaryPath}`);
 		return binaryPath;
 	} finally {
 		if (fs.existsSync(tempDir)) try {
@@ -1365,7 +1585,9 @@ async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDi
 				recursive: true,
 				force: true
 			});
-		} catch {}
+		} catch (err) {
+			logger.debug(`[luals] Failed to clean up temporary directory ${tempDir}: ${err instanceof Error ? err.message : String(err)}`);
+		}
 	}
 }
 async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
@@ -1375,50 +1597,112 @@ async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
 		const defaultBundledPath = path.join(getPackageRoot(), defaultInfo.binaryRelativePath);
 		if (fs.existsSync(defaultBundledPath) && isBinaryValid(defaultBundledPath)) return defaultBundledPath;
 	}
-	const resolvedVersion = await resolveLuaLSVersion(version);
-	const info = getPlatformInfo(resolvedVersion);
-	const bundledPath = path.join(getPackageRoot(), info.binaryRelativePath);
-	if (fs.existsSync(bundledPath) && isBinaryValid(bundledPath)) return bundledPath;
-	const cachedDir = getCacheDir(resolvedVersion);
-	const cachedPath = path.join(cachedDir, info.binaryRelativePath);
-	const completeMarker = path.join(cachedDir, ".complete");
-	if (fs.existsSync(cachedPath)) {
-		if (fs.existsSync(completeMarker)) try {
-			if (fs.readFileSync(completeMarker, "utf-8").trim() === resolvedVersion && isBinaryValid(cachedPath)) return cachedPath;
-		} catch {}
-		if (!options?.quiet) console.warn(`[luals] Cached LuaLS binary at ${cachedPath} is corrupted or incomplete. Repairing...`);
+	const isDefaultOrLatest = !version || version === "latest";
+	const baseCacheDir = options?.cacheDir ?? getBaseLuaLSCacheDir();
+	if (!isDefaultOrLatest) {
+		const resolvedVersion = await resolveLuaLSVersion(version);
+		const info = getPlatformInfo(resolvedVersion);
+		const bundledPath = path.join(getPackageRoot(), info.binaryRelativePath);
+		if (fs.existsSync(bundledPath) && isBinaryValid(bundledPath)) return bundledPath;
+		const cachedDir = getCacheDir(resolvedVersion, baseCacheDir);
+		const cachedPath = path.join(cachedDir, info.binaryRelativePath);
+		const completeMarker = path.join(cachedDir, ".complete");
+		if (fs.existsSync(cachedPath)) {
+			if (fs.existsSync(completeMarker)) try {
+				if (fs.readFileSync(completeMarker, "utf-8").trim() === resolvedVersion && isBinaryValid(cachedPath)) return cachedPath;
+			} catch (err) {
+				logger.debug(`[luals] Failed to read complete marker at ${completeMarker}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			if (!options?.quiet) logger.warn(`[luals] Cached LuaLS binary at ${cachedPath} is corrupted or incomplete. Repairing...`);
+			try {
+				fs.rmSync(cachedDir, {
+					recursive: true,
+					force: true
+				});
+			} catch (err) {
+				logger.warn(`[luals] Failed to remove corrupted cache directory ${cachedDir}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}
+		const legacyDir = getLegacyCacheDir(resolvedVersion);
+		const legacyPath = path.join(legacyDir, info.binaryRelativePath);
+		const legacyMarker = path.join(legacyDir, ".complete");
+		if (fs.existsSync(legacyPath)) {
+			let validLegacy = false;
+			if (fs.existsSync(legacyMarker)) try {
+				if (fs.readFileSync(legacyMarker, "utf-8").trim() === resolvedVersion && isBinaryValid(legacyPath)) validLegacy = true;
+			} catch (err) {
+				logger.debug(`[luals] Failed to read legacy complete marker at ${legacyMarker}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			else if (isBinaryValid(legacyPath)) validLegacy = true;
+			if (validLegacy) {
+				if (path.resolve(legacyDir) !== path.resolve(cachedDir)) try {
+					fs.mkdirSync(path.dirname(cachedDir), { recursive: true });
+					fs.cpSync(legacyDir, cachedDir, { recursive: true });
+					if (fs.existsSync(cachedPath) && isBinaryValid(cachedPath)) return cachedPath;
+				} catch (err) {
+					logger.warn(`[luals] Failed to migrate legacy cache from ${legacyDir} to ${cachedDir}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+				return legacyPath;
+			}
+		}
 		try {
-			fs.rmSync(cachedDir, {
-				recursive: true,
-				force: true
-			});
-		} catch {}
-	}
-	const legacyDir = getLegacyCacheDir(resolvedVersion);
-	const legacyPath = path.join(legacyDir, info.binaryRelativePath);
-	const legacyMarker = path.join(legacyDir, ".complete");
-	if (fs.existsSync(legacyPath)) {
-		let validLegacy = false;
-		if (fs.existsSync(legacyMarker)) try {
-			if (fs.readFileSync(legacyMarker, "utf-8").trim() === resolvedVersion && isBinaryValid(legacyPath)) validLegacy = true;
-		} catch {}
-		else if (isBinaryValid(legacyPath)) validLegacy = true;
-		if (validLegacy) {
-			if (path.resolve(legacyDir) !== path.resolve(cachedDir)) try {
-				fs.mkdirSync(path.dirname(cachedDir), { recursive: true });
-				fs.cpSync(legacyDir, cachedDir, { recursive: true });
-				if (fs.existsSync(cachedPath) && isBinaryValid(cachedPath)) return cachedPath;
-			} catch {}
-			return legacyPath;
+			const cmd = process.platform === "win32" ? "where.exe" : "which";
+			const { stdout } = await execFileAsync(cmd, ["lua-language-server"]);
+			const found = stdout.trim().split(/\r?\n/)[0];
+			if (found && fs.existsSync(found) && isBinaryValid(found)) return found;
+		} catch (err) {
+			logger.debug(`[luals] LuaLS binary not found in PATH: ${err instanceof Error ? err.message : String(err)}`);
 		}
-	}
-	try {
+		return await downloadAndExtractLuaLS(resolvedVersion, getCacheDir(resolvedVersion, baseCacheDir), options);
+	}
+	const currentWeek = getIsoWeek();
+	const metadata = readLuaLSMetadata(baseCacheDir);
+	if (metadata && metadata.lastCheckedWeek === currentWeek && metadata.latestVersion) {
+		const info = getPlatformInfo(metadata.latestVersion);
+		const cachedPath = path.join(getCacheDir(metadata.latestVersion, baseCacheDir), info.binaryRelativePath);
+		if (isBinaryValid(cachedPath)) return cachedPath;
+	}
+	const cachedVersions = listCachedLuaLSVersions(baseCacheDir);
+	if (metadata && metadata.lastCheckedWeek === currentWeek && cachedVersions.length > 0) {
+		const fallbackVersion = cachedVersions[0];
+		const info = getPlatformInfo(fallbackVersion);
+		return path.join(getCacheDir(fallbackVersion, baseCacheDir), info.binaryRelativePath);
+	}
+	const onlineTag = await fetchLatestLuaLSVersionFromGitHub();
+	const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+	let targetVersion;
+	if (onlineTag) targetVersion = onlineTag;
+	else if (metadata?.latestVersion && cachedVersions.includes(metadata.latestVersion)) {
+		logger.info(`[luals] Network unreachable or rate limited; using cached LuaLS ${metadata.latestVersion}.`);
+		targetVersion = metadata.latestVersion;
+	} else if (cachedVersions.length > 0) {
+		logger.info(`[luals] Network unreachable or rate limited; using cached LuaLS ${cachedVersions[0]}.`);
+		targetVersion = cachedVersions[0];
+	} else targetVersion = FALLBACK_LUALS_VERSION;
+	writeLuaLSMetadata({
+		lastCheckedWeek: currentWeek,
+		latestVersion: targetVersion,
+		lastCheckedDate: today
+	}, baseCacheDir);
+	const info = getPlatformInfo(targetVersion);
+	const targetCacheDir = getCacheDir(targetVersion, baseCacheDir);
+	const targetBinaryPath = path.join(targetCacheDir, info.binaryRelativePath);
+	const completeMarker = path.join(targetCacheDir, ".complete");
+	if (fs.existsSync(completeMarker) && isBinaryValid(targetBinaryPath)) {
+		cleanupOldCachedLuaLSVersions(targetVersion, baseCacheDir);
+		return targetBinaryPath;
+	}
+	if (!onlineTag) try {
 		const cmd = process.platform === "win32" ? "where.exe" : "which";
 		const { stdout } = await execFileAsync(cmd, ["lua-language-server"]);
 		const found = stdout.trim().split(/\r?\n/)[0];
 		if (found && fs.existsSync(found) && isBinaryValid(found)) return found;
-	} catch {}
-	return await downloadAndExtractLuaLS(resolvedVersion, void 0, options);
+	} catch (err) {
+		logger.debug(`[luals] LuaLS binary not found in PATH: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const downloadedBinary = await downloadAndExtractLuaLS(targetVersion, targetCacheDir, options);
+	cleanupOldCachedLuaLSVersions(targetVersion, baseCacheDir);
+	return downloadedBinary;
 }
 async function runLuaLSCheck(targetPath, configPath, options) {
 	const absoluteTarget = path.resolve(targetPath);
@@ -1448,6 +1732,7 @@ async function runLuaLSCheck(targetPath, configPath, options) {
 		});
 	} catch (err) {
 		execError = err;
+		logger.debug(`[luals] LuaLS process exited with error or non-zero status: ${err instanceof Error ? err.message : String(err)}`);
 	}
 	let diagnostics = {};
 	let parseSucceeded = false;
@@ -1455,10 +1740,14 @@ async function runLuaLSCheck(targetPath, configPath, options) {
 		const content = fs.readFileSync(checkOutPath, "utf-8");
 		diagnostics = JSON.parse(content);
 		parseSucceeded = true;
-	} catch {} finally {
+	} catch (err) {
+		logger.error(`[luals] Failed to read or parse diagnostic output from ${checkOutPath}: ${err instanceof Error ? err.message : String(err)}`);
+	} finally {
 		try {
 			fs.unlinkSync(checkOutPath);
-		} catch {}
+		} catch (err) {
+			logger.debug(`[luals] Failed to delete check output file ${checkOutPath}: ${err instanceof Error ? err.message : String(err)}`);
+		}
 	}
 	if (!parseSucceeded) {
 		const cacheHint = `(Cache location: ${getCacheDir()})`;
@@ -1514,7 +1803,9 @@ function countCheckedFiles(targetPath, configPath) {
 		const cfg = JSON.parse(fs.readFileSync(configPath, "utf-8"));
 		if (cfg.workspace?.ignoreDir) ignoreDirs = cfg.workspace.ignoreDir;
 		if (cfg.files?.exclude) excludePatterns = cfg.files.exclude;
-	} catch {}
+	} catch (err) {
+		logger.warn(`[luals] Failed to parse config file for file counting at ${configPath}: ${err instanceof Error ? err.message : String(err)}`);
+	}
 	const normIgnoreDirs = new Set(ignoreDirs.map((d) => d.replace(/\\/g, "/").toLowerCase()));
 	function isExcluded(relPath) {
 		const norm = relPath.replace(/\\/g, "/");
@@ -1532,7 +1823,9 @@ function countCheckedFiles(targetPath, configPath) {
 					const baseRegexStr = "^" + normPat.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".") + "$";
 					try {
 						if (new RegExp(baseRegexStr, "i").test(baseName)) return true;
-					} catch {}
+					} catch (err) {
+						logger.debug(`[luals] Invalid regex for pattern "${normPat}": ${err instanceof Error ? err.message : String(err)}`);
+					}
 				}
 				let regexStr = normPat;
 				const hasLeadingDoubleStar = regexStr.startsWith("**/");
@@ -1544,7 +1837,9 @@ function countCheckedFiles(targetPath, configPath) {
 				if (hasTrailingDoubleStar) escaped = `${escaped}(?:/.*)?`;
 				try {
 					if (new RegExp(`^${escaped}$`, "i").test(norm)) return true;
-				} catch {}
+				} catch (err) {
+					logger.debug(`[luals] Invalid glob regex for pattern "${normPat}": ${err instanceof Error ? err.message : String(err)}`);
+				}
 			}
 		}
 		return false;
@@ -1554,7 +1849,8 @@ function countCheckedFiles(targetPath, configPath) {
 		let entries;
 		try {
 			entries = fs.readdirSync(currentDir, { withFileTypes: true });
-		} catch {
+		} catch (err) {
+			logger.debug(`[luals] Failed to read directory ${currentDir}: ${err instanceof Error ? err.message : String(err)}`);
 			return;
 		}
 		for (const entry of entries) {
@@ -1564,7 +1860,8 @@ function countCheckedFiles(targetPath, configPath) {
 			if (entry.isDirectory() || entry.isSymbolicLink() && (() => {
 				try {
 					return fs.statSync(fullPath).isDirectory();
-				} catch {
+				} catch (err) {
+					logger.debug(`[luals] Failed to stat symlink target ${fullPath}: ${err instanceof Error ? err.message : String(err)}`);
 					return false;
 				}
 			})()) {
@@ -1661,7 +1958,9 @@ function formatPretty(result, cwd = process.cwd(), useColor = shouldEnableColor(
 		let fileContent = [];
 		try {
 			if (fs.existsSync(filePath)) fileContent = fs.readFileSync(filePath, "utf-8").split(/\r?\n/);
-		} catch {}
+		} catch (err) {
+			logger.debug(`Failed to read file snippet for ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+		}
 		for (const d of diags) {
 			const line = d.range.start.line + 1;
 			const col = d.range.start.character + 1;
@@ -4714,7 +5013,9 @@ function readAnnotationsMetadata(cacheDir = getAnnotationsCacheDir()) {
 		const content = fs.readFileSync(metaPath, "utf-8");
 		const parsed = JSON.parse(content);
 		if (typeof parsed?.commitId === "string" && typeof parsed?.lastChecked === "string") return parsed;
-	} catch {}
+	} catch (err) {
+		logger.debug(`Failed to parse annotations metadata: ${err instanceof Error ? err.message : String(err)}`);
+	}
 	return null;
 }
 async function fetchLatestCommitId() {
@@ -4729,7 +5030,9 @@ async function fetchLatestCommitId() {
 			const data = await res.json();
 			if (typeof data.sha === "string" && /^[0-9a-fA-F]{7,40}$/.test(data.sha)) return data.sha;
 		}
-	} catch {}
+	} catch (err) {
+		logger.warn(`Failed to resolve latest annotations commit from GitHub: ${err instanceof Error ? err.message : String(err)}`);
+	}
 	return null;
 }
 async function fetchRawAnnotationsContent() {
@@ -4774,7 +5077,9 @@ function updateLastCheckedDate(commitId, cacheDir = getAnnotationsCacheDir()) {
 	} finally {
 		try {
 			if (fs.existsSync(tempMetaPath)) fs.unlinkSync(tempMetaPath);
-		} catch {}
+		} catch (err) {
+			logger.warn(`Failed to clean up temporary metadata file ${tempMetaPath}: ${err instanceof Error ? err.message : String(err)}`);
+		}
 	}
 	return metadata;
 }
@@ -4792,8 +5097,8 @@ async function downloadAndCacheAnnotations(commitId, cacheDir = getAnnotationsCa
 	try {
 		fs.mkdirSync(tempDir, { recursive: true });
 		if (!options?.quiet) {
-			if (commitId && commitId !== "unknown") console.log(`[annotations] Downloading nanos world API annotations (${commitId.slice(0, 7)})...`);
-			else console.log("[annotations] Downloading nanos world API annotations...");
+			if (commitId && commitId !== "unknown") logger.info(`[annotations] Downloading nanos world API annotations (${commitId.slice(0, 7)})...`);
+			else logger.info("[annotations] Downloading nanos world API annotations...");
 		}
 		const content = await fetchRawAnnotationsContent();
 		const tempAnnotationsPath = path.join(tempDir, ANNOTATIONS_FILENAME);
@@ -4819,8 +5124,8 @@ async function downloadAndCacheAnnotations(commitId, cacheDir = getAnnotationsCa
 		await copyFileWithRetry(tempAnnotationsPath, finalAnnotationsPath);
 		await copyFileWithRetry(tempMetaPath, finalMetaPath);
 		if (!options?.quiet) {
-			if (commitId && commitId !== "unknown") console.log(`[annotations] Updated annotations.lua to commit ${commitId.slice(0, 7)}.`);
-			else console.log("[annotations] Updated annotations.lua.");
+			if (commitId && commitId !== "unknown") logger.info(`[annotations] Updated annotations.lua to commit ${commitId.slice(0, 7)}.`);
+			else logger.info("[annotations] Updated annotations.lua.");
 		}
 		return finalAnnotationsPath;
 	} catch (err) {
@@ -4829,7 +5134,9 @@ async function downloadAndCacheAnnotations(commitId, cacheDir = getAnnotationsCa
 			const backupMeta = path.join(backupDir, METADATA_FILENAME);
 			if (fs.existsSync(backupAnnotations)) await copyFileWithRetry(backupAnnotations, finalAnnotationsPath);
 			if (fs.existsSync(backupMeta)) await copyFileWithRetry(backupMeta, finalMetaPath);
-		} catch {}
+		} catch (rollbackErr) {
+			logger.error(`Failed to restore annotations from backup during rollback: ${rollbackErr instanceof Error ? rollbackErr.message : String(rollbackErr)}`);
+		}
 		throw err;
 	} finally {
 		try {
@@ -4841,7 +5148,9 @@ async function downloadAndCacheAnnotations(commitId, cacheDir = getAnnotationsCa
 				recursive: true,
 				force: true
 			});
-		} catch {}
+		} catch (err) {
+			logger.warn(`Failed to clean up annotations temporary or backup directory: ${err instanceof Error ? err.message : String(err)}`);
+		}
 	}
 }
 /**
@@ -4882,7 +5191,9 @@ async function resolveAnnotations(options = {}) {
 	if (fs.existsSync(cachedAnnotationsFile)) {
 		try {
 			updateLastCheckedDate(metadata?.commitId || "unknown", cacheDir);
-		} catch {}
+		} catch (err) {
+			logger.warn(`Failed to update lastChecked date for cached annotations: ${err instanceof Error ? err.message : String(err)}`);
+		}
 		return cachedAnnotationsFile;
 	}
 	try {
@@ -4905,10 +5216,15 @@ function getVersionString() {
 	const root = getPackageRoot();
 	try {
 		return `nanos-lint v${JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf-8")).version}`;
-	} catch {
+	} catch (err) {
+		logger.debug(`Could not read version from package.json: ${err instanceof Error ? err.message : String(err)}`);
 		return "nanos-lint v1.0.0";
 	}
 }
+/** Writes command results to stdout unless the level is `silent`. */
+function writeOutput(message) {
+	if (logger.isOutputEnabled()) console.log(message);
+}
 function collectIgnorePatterns(val, prev) {
 	const parts = val.split(/[\r\n,]+/).map((s) => s.trim()).filter(Boolean);
 	return (prev ?? []).concat(parts);
@@ -4916,9 +5232,20 @@ function collectIgnorePatterns(val, prev) {
 function createProgram(options) {
 	const setExitCode = options?.setExitCode ?? (() => {});
 	const program = new Command("nanos-lint");
-	program.description("Linter and type-checker for nanos world Lua scripts").version(getVersionString(), "-v, --version", "Show version information").exitOverride().configureOutput({
+	program.description("Linter and type-checker for nanos world Lua scripts").version(getVersionString(), "-v, --version", "Show version information").addOption(new Option("-l, --log-level <level>", "Logging level: error, warn, info, debug, silent").choices([
+		"error",
+		"warn",
+		"info",
+		"debug",
+		"silent"
+	]).default(DEFAULT_LOG_LEVEL)).hook("preAction", (thisCommand, actionCommand) => {
+		const target = actionCommand || thisCommand;
+		const opts = target.optsWithGlobals ? target.optsWithGlobals() : target.opts();
+		if (opts.quiet) logger.setLevel("error");
+		else if (opts.logLevel && isValidLogLevel(opts.logLevel)) logger.setLevel(opts.logLevel);
+	}).exitOverride().configureOutput({
 		writeOut: (str) => console.log(str.trimEnd()),
-		writeErr: (str) => console.error(str.trimEnd())
+		writeErr: (str) => logger.error(str.trimEnd())
 	});
 	program.command("check [path]", { isDefault: true }).description("Check a workspace or Lua file (default command)").addOption(new Option("--checklevel <level>", "Minimum diagnostic level: Error, Warning, Information, Hint").choices([
 		"Error",
@@ -4929,7 +5256,15 @@ function createProgram(options) {
 		"pretty",
 		"json",
 		"github"
-	])).option("-i, --ignore <pattern>", "Files or directories to ignore (supports glob patterns, repeatable)", collectIgnorePatterns).option("--luals-version <ver>", `Version of LuaLS to use (default: ${DEFAULT_LUALS_VERSION})`, DEFAULT_LUALS_VERSION).option("--no-fail", "Do not exit with code 1 if diagnostics are found").option("--quiet", "Suppress progress output").option("--github", "Output in GitHub Actions format (shortcut for --format=github)").action(async (targetPath = ".", opts) => {
+	])).option("-i, --ignore <pattern>", "Files or directories to ignore (supports glob patterns, repeatable)", collectIgnorePatterns).option("--luals-version <ver>", `Version of LuaLS to use (default: ${DEFAULT_LUALS_VERSION})`, DEFAULT_LUALS_VERSION).option("--no-fail", "Do not exit with code 1 if diagnostics are found").option("--quiet", "Suppress progress output").addOption(new Option("-l, --log-level <level>", "Logging level: error, warn, info, debug, silent").choices([
+		"error",
+		"warn",
+		"info",
+		"debug",
+		"silent"
+	])).option("--github", "Output in GitHub Actions format (shortcut for --format=github)").action(async (targetPath = ".", opts) => {
+		if (opts.quiet) logger.setLevel("error");
+		else if (opts.logLevel && isValidLogLevel(opts.logLevel)) logger.setLevel(opts.logLevel);
 		const format = opts.github ? "github" : opts.format || (process.env.GITHUB_ACTIONS ? "github" : "pretty");
 		const checkOptions = {
 			path: targetPath,
@@ -4959,42 +5294,42 @@ function createProgram(options) {
 		} finally {
 			if (resolved.isTemp && fs.existsSync(resolved.configPath)) try {
 				fs.unlinkSync(resolved.configPath);
-			} catch {}
+			} catch (err) {
+				logger.warn(`Failed to clean up temporary config file ${resolved.configPath}: ${err instanceof Error ? err.message : String(err)}`);
+			}
 		}
 		const output = formatReport(result, checkOptions.format, process.cwd());
-		if (output) console.log(output);
+		if (output) writeOutput(output);
 		if (!result.passed && checkOptions.failOnError) setExitCode(1);
 		else setExitCode(0);
 	});
 	program.command("init [path]").description("Scaffold a .luarc.json configuration in the workspace").option("-f, --force", "Overwrite existing .luarc.json configuration").option("--annotations <path>", "Path to custom annotations.lua file").action(async (targetPath = ".", opts) => {
 		const annotationsPath = await resolveAnnotations({ customPath: opts.annotations });
-		const created = initWorkspace(path.resolve(targetPath), {
+		writeOutput(`[init] Initialized nanos world LuaLS configuration: ${initWorkspace(path.resolve(targetPath), {
 			force: opts.force,
 			annotationsPath
-		});
-		console.log(`[init] Initialized nanos world LuaLS configuration: ${created}`);
+		})}`);
 		setExitCode(0);
 	});
 	program.command("download-luals [version]").description("Download and cache the LuaLS binary").option("--luals-version <ver>", `Version of LuaLS to use (default: ${DEFAULT_LUALS_VERSION})`).action(async (version, opts) => {
 		const ver = version || opts?.lualsVersion || "latest";
-		console.log(`[luals] Downloading LuaLS ${ver}...`);
-		const bin = await resolveLuaLSBinary(ver);
-		console.log(`[luals] Ready at: ${bin}`);
+		writeOutput(`[luals] Downloading LuaLS ${ver}...`);
+		writeOutput(`[luals] Ready at: ${await resolveLuaLSBinary(ver)}`);
 		setExitCode(0);
 	});
 	program.command("clean-cache").alias("clean").description("Clear the nanos-lint cache").action(() => {
 		try {
 			const cleared = cleanCache();
-			if (cleared) console.log(`[cache] Cleared cache at: ${cleared}`);
-			else console.log(`[cache] Cache is already empty (${systemPaths.cache})`);
+			if (cleared) writeOutput(`[cache] Cleared cache at: ${cleared}`);
+			else writeOutput(`[cache] Cache is already empty (${systemPaths.cache})`);
 			setExitCode(0);
 		} catch (err) {
-			console.error(`[cache] Failed to clear cache: ${err instanceof Error ? err.message : String(err)}`);
+			logger.error(`[cache] Failed to clear cache: ${err instanceof Error ? err.message : String(err)}`);
 			setExitCode(1);
 		}
 	});
 	program.command("version").description("Show version information").action(() => {
-		console.log(getVersionString());
+		writeOutput(getVersionString());
 		setExitCode(0);
 	});
 	program.helpCommand("help [command]", "Show this help message");
@@ -5010,6 +5345,15 @@ Examples:
 	return program;
 }
 async function runCLI(args = process.argv.slice(2)) {
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "-l" || arg === "--log-level") {
+			if (i + 1 < args.length && isValidLogLevel(args[i + 1])) logger.setLevel(args[i + 1]);
+		} else if (arg.startsWith("--log-level=")) {
+			const val = arg.split("=")[1];
+			if (val && isValidLogLevel(val)) logger.setLevel(val);
+		}
+	}
 	let exitCode = 0;
 	const program = createProgram({ setExitCode: (code) => {
 		exitCode = code;
@@ -5020,8 +5364,8 @@ async function runCLI(args = process.argv.slice(2)) {
 	} catch (err) {
 		if (err instanceof CommanderError) return err.exitCode;
 		const message = err instanceof Error ? err.message : String(err);
-		console.error(`error: ${message}`);
-		if (process.env.DEBUG && err instanceof Error && err.stack) console.error(err.stack);
+		logger.error(`error: ${message}`);
+		if (process.env.DEBUG && err instanceof Error && err.stack) logger.error(err.stack);
 		return 1;
 	}
 }
@@ -5031,7 +5375,8 @@ function isDirectExecution(importMetaUrl = import.meta.url, argv1 = process.argv
 		try {
 			if (urlStr.startsWith("file:")) return fileURLToPath(urlStr);
 			return urlStr;
-		} catch {
+		} catch (err) {
+			logger.debug(`[cli] Failed to convert URL "${urlStr}" using fileURLToPath: ${err instanceof Error ? err.message : String(err)}`);
 			return urlStr.replace(/^file:\/\/\/?/, "");
 		}
 	};
@@ -5043,7 +5388,8 @@ function isDirectExecution(importMetaUrl = import.meta.url, argv1 = process.argv
 		const cliJsPath = path.join(moduleDir, "cli.js").toLowerCase();
 		const cliTsPath = path.join(moduleDir, "cli.ts").toLowerCase();
 		if (scriptPath === cliJsPath || scriptPath === cliTsPath) return true;
-	} catch {
+	} catch (err) {
+		logger.debug(`[cli] Failed to resolve realpath for entry detection: ${err instanceof Error ? err.message : String(err)}`);
 		const normArgv = path.resolve(argv1).toLowerCase();
 		const normMeta = toPath(importMetaUrl).toLowerCase();
 		if (normArgv === normMeta) return true;
@@ -5055,10 +5401,10 @@ function isDirectExecution(importMetaUrl = import.meta.url, argv1 = process.argv
 if (isDirectExecution()) runCLI().then((code) => {
 	process.exit(code);
 }).catch((err) => {
-	console.error(err);
+	logger.error(err);
 	process.exit(1);
 });
 //#endregion
-export { stripTrailingSlashes as $, FALLBACK_LUALS_VERSION as A, resolveLuaLSVersion as B, formatProblemSummary as C, pluralize as D, getColors as E, getLegacyCacheDir as F, getDefinitionsDir as G, sanitizeLuaLSVersion as H, getPlatformInfo as I, loadConfigFile as J, getPackageRoot as K, isBinaryValid as L, downloadAndExtractLuaLS as M, escapePowerShellSingleQuote as N, shouldEnableColor as O, getCacheDir as P, stripJsonComments as Q, resolveLatestLuaLSVersion as R, formatPretty as S, formatSeverityBadge as T, getDefaultAnnotationsPath as U, runLuaLSCheck as V, getDefaultTemplatePath as W, parseJsonc as X, mergeConfigs as Y, resolveWorkspaceConfig as Z, getTodayDateString as _, ANNOTATIONS_FILENAME as a, updateLastCheckedDate as b, GITHUB_COMMITS_API as c, downloadAndCacheAnnotations as d, cleanCache as et, fetchLatestCommitId as f, getCachedAnnotationsFilePath as g, getAnnotationsMetadataFilePath as h, runCLI as i, countCheckedFiles as j, DEFAULT_LUALS_VERSION as k, METADATA_FILENAME as l, getAnnotationsCacheDir as m, createProgram as n, fileUriToPath as nt, DOCGEN_BRANCH as o, fetchRawAnnotationsContent as p, initWorkspace as q, isDirectExecution as r, DOCGEN_REPO as s, collectIgnorePatterns as t, systemPaths as tt, RAW_ANNOTATIONS_URL as u, readAnnotationsMetadata as v, formatReport as w, formatGitHubAnnotations as x, resolveAnnotations as y, resolveLuaLSBinary as z };
+export { getDefaultAnnotationsPath as $, FALLBACK_LUALS_VERSION as A, getIsoWeek as B, formatProblemSummary as C, pluralize as D, getColors as E, escapePowerShellSingleQuote as F, listCachedLuaLSVersions as G, getLuaLSMetadataPath as H, fetchLatestLuaLSVersionFromGitHub as I, resolveLuaLSBinary as J, readLuaLSMetadata as K, findExistingLuaLSDir as L, cleanupOldCachedLuaLSVersions as M, countCheckedFiles as N, shouldEnableColor as O, downloadAndExtractLuaLS as P, writeLuaLSMetadata as Q, getBaseLuaLSCacheDir as R, formatPretty as S, formatSeverityBadge as T, getPlatformInfo as U, getLegacyCacheDir as V, isBinaryValid as W, runLuaLSCheck as X, resolveLuaLSVersion as Y, sanitizeLuaLSVersion as Z, getTodayDateString as _, isValidLogLevel as _t, ANNOTATIONS_FILENAME as a, mergeConfigs as at, updateLastCheckedDate as b, GITHUB_COMMITS_API as c, stripJsonComments as ct, downloadAndCacheAnnotations as d, systemPaths as dt, getDefaultTemplatePath as et, fetchLatestCommitId as f, fileUriToPath as ft, getCachedAnnotationsFilePath as g, Logger as gt, getAnnotationsMetadataFilePath as h, LOG_LEVEL_PRIORITY as ht, runCLI as i, loadConfigFile as it, LUALS_METADATA_FILENAME as j, DEFAULT_LUALS_VERSION as k, METADATA_FILENAME as l, stripTrailingSlashes as lt, getAnnotationsCacheDir as m, LOG_LEVELS as mt, createProgram as n, getPackageRoot as nt, DOCGEN_BRANCH as o, parseJsonc as ot, fetchRawAnnotationsContent as p, DEFAULT_LOG_LEVEL as pt, resolveLatestLuaLSVersion as q, isDirectExecution as r, initWorkspace as rt, DOCGEN_REPO as s, resolveWorkspaceConfig as st, collectIgnorePatterns as t, getDefinitionsDir as tt, RAW_ANNOTATIONS_URL as u, cleanCache as ut, readAnnotationsMetadata as v, logger as vt, formatReport as w, formatGitHubAnnotations as x, resolveAnnotations as y, parseLogLevel as yt, getCacheDir as z };
 
-//# sourceMappingURL=cli-5LLXRlN7.js.map
+//# sourceMappingURL=cli-sEO_MZ-K.js.map