nanos-lint 2.6.1 → 2.8.0

package/dist/{cli-5LLXRlN7.js → cli-DGez8MSI.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);
@@ -865,6 +929,77 @@ function cleanCache(targetDir = systemPaths.cache) {
 	}
 	return null;
 }
+/**
+* Recursively calculates total disk usage of a file or directory in bytes.
+* Handles missing paths and inaccessible files gracefully.
+*/
+function getDirectorySize(targetPath) {
+	if (!fs.existsSync(targetPath)) return 0;
+	let total = 0;
+	try {
+		const stat = fs.statSync(targetPath);
+		if (!stat.isDirectory()) return stat.size;
+		const entries = fs.readdirSync(targetPath, { withFileTypes: true });
+		for (const entry of entries) {
+			const fullPath = `${targetPath}/${entry.name}`;
+			try {
+				if (entry.isDirectory()) total += getDirectorySize(fullPath);
+				else if (entry.isFile()) total += fs.statSync(fullPath).size;
+			} catch (err) {
+				logger.debug(`[paths] Failed to stat entry ${fullPath}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}
+	} catch (err) {
+		logger.debug(`[paths] Failed to calculate directory size for ${targetPath}: ${err instanceof Error ? err.message : String(err)}`);
+		return 0;
+	}
+	return total;
+}
+/**
+* Formats byte values into human-readable strings (e.g. "86.4 MB", "1.42 MB", "42.5 MB").
+*/
+function formatBytes(bytes) {
+	if (bytes <= 0 || !Number.isFinite(bytes)) return "0 B";
+	if (bytes < 1) return `${Math.round(bytes)} B`;
+	const units = [
+		"B",
+		"KB",
+		"MB",
+		"GB",
+		"TB"
+	];
+	let i = Math.max(0, Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1));
+	let val = bytes / Math.pow(1024, i);
+	if (Math.round(val) >= 1024 && i < units.length - 1) {
+		i++;
+		val /= 1024;
+	}
+	return `${i === 0 ? val.toFixed(0) : val < 10 ? val.toFixed(2) : val < 100 ? val.toFixed(1) : val.toFixed(0)} ${units[i]}`;
+}
+//#endregion
+//#region src/errors.ts
+var NanosLintError = class extends Error {
+	code;
+	remedy;
+	name = "NanosLintError";
+	constructor(message, code, remedy, options) {
+		super(message, options);
+		this.code = code;
+		this.remedy = remedy;
+	}
+};
+var ConfigError = class extends NanosLintError {
+	name = "ConfigError";
+};
+var LuaLSError = class extends NanosLintError {
+	name = "LuaLSError";
+};
+var AnnotationsError = class extends NanosLintError {
+	name = "AnnotationsError";
+};
+var CacheError = class extends NanosLintError {
+	name = "CacheError";
+};
 //#endregion
 //#region src/config.ts
 const __filename = fileURLToPath(import.meta.url);
@@ -916,8 +1051,14 @@ function parseJsonc(text) {
 	return result;
 }
 function loadConfigFile(filePath) {
-	if (!fs.existsSync(filePath)) throw new Error(`Configuration file not found: ${filePath}`);
-	return parseJsonc(fs.readFileSync(filePath, "utf-8"));
+	if (!fs.existsSync(filePath)) throw new ConfigError(`Configuration file not found: ${filePath}`, "ERR_CONFIG_NOT_FOUND", "Ensure the configuration file path is correct or run 'nanos-lint init' to generate a default config.");
+	const content = fs.readFileSync(filePath, "utf-8");
+	try {
+		return parseJsonc(content);
+	} catch (err) {
+		if (err instanceof ConfigError) throw err;
+		throw new ConfigError(`Failed to parse configuration file at ${filePath}: ${err instanceof Error ? err.message : String(err)}`, "ERR_CONFIG_PARSE", "Check your .luarc.json syntax or run 'nanos-lint init --force' to scaffold a clean template.", { cause: err });
+	}
 }
 /**
 * Removes trailing `/` characters from a path-like string.
@@ -933,6 +1074,76 @@ function stripTrailingSlashes(value) {
 	return end === value.length ? value : value.slice(0, end);
 }
 /**
+* Set of recognized diagnostic codes supported by Lua Language Server (LuaLS).
+* LuaLS discards the entire `diagnostics.severity` object if it contains a single
+* unrecognized key (such as obsolete 'syntax-error'). nanos-lint filters severity
+* and neededFileStatus maps against this allow-list to ensure valid configuration.
+*/
+const VALID_LUALS_DIAGNOSTIC_CODES = /* @__PURE__ */ new Set([
+	"ambiguity-1",
+	"assign-type-mismatch",
+	"await-in-sync",
+	"cast-local-type",
+	"cast-type-mismatch",
+	"circle-doc-class",
+	"close-non-object",
+	"code-after-break",
+	"codestyle-check",
+	"count-down-loop",
+	"deprecated",
+	"different-requires",
+	"discard-returns",
+	"doc-field-no-class",
+	"duplicate-doc-alias",
+	"duplicate-doc-field",
+	"duplicate-doc-param",
+	"duplicate-index",
+	"duplicate-set-field",
+	"empty-block",
+	"global-element",
+	"global-in-nil-env",
+	"incomplete-signature-doc",
+	"inject-field",
+	"invisible",
+	"lowercase-global",
+	"missing-fields",
+	"missing-global-doc",
+	"missing-local-export-doc",
+	"missing-parameter",
+	"missing-return",
+	"missing-return-value",
+	"name-style-check",
+	"need-check-nil",
+	"newfield-call",
+	"newline-call",
+	"no-unknown",
+	"not-yieldable",
+	"param-type-mismatch",
+	"redefined-local",
+	"redundant-parameter",
+	"redundant-return",
+	"redundant-return-value",
+	"redundant-value",
+	"return-type-mismatch",
+	"spell-check",
+	"trailing-space",
+	"unbalanced-assignments",
+	"undefined-doc-class",
+	"undefined-doc-name",
+	"undefined-doc-param",
+	"undefined-env-child",
+	"undefined-field",
+	"undefined-global",
+	"unknown-cast-variable",
+	"unknown-diag-code",
+	"unknown-operator",
+	"unreachable-code",
+	"unused-function",
+	"unused-label",
+	"unused-local",
+	"unused-vararg"
+]);
+/**
 * Merges a base nanos configuration with a workspace override configuration.
 * Guarantees that nanos API annotations are included in workspace.library,
 * and standardizes paths for LuaLS.
@@ -949,7 +1160,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 ?? [];
@@ -961,10 +1174,20 @@ function mergeConfigs(base, override = {}, definitionsPath = getDefaultAnnotatio
 	const baseGlobals = base.diagnostics?.globals ?? [];
 	const overrideGlobals = override.diagnostics?.globals ?? [];
 	const globalsSet = /* @__PURE__ */ new Set([...baseGlobals, ...overrideGlobals]);
-	const mergedSeverity = {
+	const rawSeverity = {
 		...base.diagnostics?.severity ?? {},
 		...override.diagnostics?.severity ?? {}
 	};
+	const mergedSeverity = {};
+	for (const [code, level] of Object.entries(rawSeverity)) if (VALID_LUALS_DIAGNOSTIC_CODES.has(code)) mergedSeverity[code] = level;
+	else logger.warn(`[config] Unrecognized diagnostic code "${code}" in diagnostics.severity was dropped to prevent LuaLS from discarding the severity configuration.`);
+	const rawNeededFileStatus = {
+		...base.diagnostics?.neededFileStatus ?? {},
+		...override.diagnostics?.neededFileStatus ?? {}
+	};
+	const mergedNeededFileStatus = {};
+	for (const [code, status] of Object.entries(rawNeededFileStatus)) if (VALID_LUALS_DIAGNOSTIC_CODES.has(code)) mergedNeededFileStatus[code] = status;
+	else logger.warn(`[config] Unrecognized diagnostic code "${code}" in diagnostics.neededFileStatus was dropped.`);
 	const hasCliIgnore = Boolean(options?.cliIgnore && options.cliIgnore.length > 0);
 	let mergedIgnoreDir;
 	let mergedFilesExclude;
@@ -1037,7 +1260,8 @@ function mergeConfigs(base, override = {}, definitionsPath = getDefaultAnnotatio
 			...base.diagnostics ?? {},
 			...override.diagnostics ?? {},
 			globals: Array.from(globalsSet),
-			severity: mergedSeverity
+			severity: mergedSeverity,
+			...Object.keys(mergedNeededFileStatus).length > 0 ? { neededFileStatus: mergedNeededFileStatus } : {}
 		}
 	};
 }
@@ -1099,10 +1323,10 @@ function resolveWorkspaceConfig(workspacePath, customConfigPath, options) {
 */
 function initWorkspace(workspacePath, options) {
 	const targetFile = path.join(workspacePath, ".luarc.json");
-	if (fs.existsSync(targetFile) && !options?.force) throw new Error(`.luarc.json already exists at ${targetFile}. Use --force to overwrite.`);
+	if (fs.existsSync(targetFile) && !options?.force) throw new ConfigError(`.luarc.json already exists at ${targetFile}. Use --force to overwrite.`, "ERR_CONFIG_EXISTS", "Pass --force to overwrite the existing .luarc.json file.");
 	const template = loadConfigFile(getDefaultTemplatePath());
 	const sourceAnnotations = options?.annotationsPath || getDefaultAnnotationsPath();
-	if (!fs.existsSync(sourceAnnotations)) throw new Error(`Definitions file not found at ${sourceAnnotations}. Make sure annotations have been downloaded or pass a valid file with --annotations.`);
+	if (!fs.existsSync(sourceAnnotations)) throw new ConfigError(`Definitions file not found at ${sourceAnnotations}. Make sure annotations have been downloaded or pass a valid file with --annotations.`, "ERR_ANNOTATIONS_NOT_FOUND", "Run 'nanos-lint warmup' to download annotations or provide --annotations <path>.");
 	const targetNanosDir = path.join(workspacePath, ".nanos-lint");
 	fs.mkdirSync(targetNanosDir, { recursive: true });
 	const targetAnnotations = path.join(targetNanosDir, "annotations.lua");
@@ -1118,8 +1342,7 @@ function initWorkspace(workspacePath, options) {
 	return targetFile;
 }
 //#endregion
-//#region src/luals.ts
-const execFileAsync = promisify(execFile);
+//#region src/luals/version.ts
 const FALLBACK_LUALS_VERSION = "3.19.1";
 const DEFAULT_LUALS_VERSION = "latest";
 /**
@@ -1156,15 +1379,10 @@ function sanitizeLuaLSVersion(raw) {
 	return first >= 48 && first <= 57 || first >= 65 && first <= 90 || first >= 97 && first <= 122 ? version : null;
 }
 /**
-* Escapes single quotes for safe PowerShell single-quoted string interpolation.
+* Fetches the latest available LuaLS release tag from the GitHub API.
+* Returns null if the request fails, times out, or receives an invalid tag.
 */
-function escapePowerShellSingleQuote(str) {
-	return str.replace(/'/g, "''");
-}
-/**
-* Resolves the latest available LuaLS release tag from the GitHub API.
-*/
-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 +1395,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).
@@ -1188,9 +1415,11 @@ async function resolveLatestLuaLSVersion() {
 async function resolveLuaLSVersion(version) {
 	if (!version || version === "latest") return await resolveLatestLuaLSVersion();
 	const sanitized = sanitizeLuaLSVersion(version);
-	if (!sanitized) throw new Error(`Invalid LuaLS version: "${version}". Expected a release tag such as "3.19.1", or "latest".`);
+	if (!sanitized) throw new LuaLSError(`Invalid LuaLS version: "${version}". Expected a release tag such as "3.19.1", or "latest".`, "ERR_LUALS_INVALID_VERSION", "Provide a valid release tag like '3.19.1' or use 'latest'.");
 	return sanitized;
 }
+//#endregion
+//#region src/luals/platform.ts
 function getPlatformInfo(version = FALLBACK_LUALS_VERSION) {
 	const platform = process.platform;
 	const arch = process.arch;
@@ -1201,7 +1430,7 @@ function getPlatformInfo(version = FALLBACK_LUALS_VERSION) {
 			assetName: `lua-language-server-${version}-win32-x64.zip`,
 			binaryRelativePath: path.join("bin", "lua-language-server.exe")
 		};
-		throw new Error(`Unsupported Windows architecture: ${arch}. Supported: x64`);
+		throw new LuaLSError(`Unsupported Windows architecture: ${arch}. Supported: x64`, "ERR_LUALS_UNSUPPORTED_ARCH", "LuaLS provides pre-built binaries for Windows x64. Use a compatible system or set LUALS_BIN to a custom binary.");
 	}
 	if (platform === "linux") {
 		if (arch === "x64") return {
@@ -1216,7 +1445,7 @@ function getPlatformInfo(version = FALLBACK_LUALS_VERSION) {
 			assetName: `lua-language-server-${version}-linux-arm64.tar.gz`,
 			binaryRelativePath: path.join("bin", "lua-language-server")
 		};
-		throw new Error(`Unsupported Linux architecture: ${arch}. Supported: x64, arm64`);
+		throw new LuaLSError(`Unsupported Linux architecture: ${arch}. Supported: x64, arm64`, "ERR_LUALS_UNSUPPORTED_ARCH", "LuaLS provides pre-built binaries for Linux x64 and arm64. Use LUALS_BIN to specify a custom build.");
 	}
 	if (platform === "darwin") return {
 		platform: "darwin",
@@ -1224,18 +1453,10 @@ function getPlatformInfo(version = FALLBACK_LUALS_VERSION) {
 		assetName: `lua-language-server-${version}-darwin-${arch === "arm64" ? "arm64" : "x64"}.tar.gz`,
 		binaryRelativePath: path.join("bin", "lua-language-server")
 	};
-	throw new Error(`Unsupported platform: ${platform}`);
-}
-function getCacheDir(version = FALLBACK_LUALS_VERSION) {
-	return path.join(systemPaths.cache, "luals", version);
-}
-/**
-* Returns the legacy cache directory used in nanos-lint <= 2.2.1.
-*/
-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);
+	throw new LuaLSError(`Unsupported platform: ${platform}`, "ERR_LUALS_UNSUPPORTED_PLATFORM", "LuaLS provides pre-built binaries for Windows, Linux, and macOS. Use LUALS_BIN to specify a custom build.");
 }
+//#endregion
+//#region src/luals/validation.ts
 /**
 * Verifies that a LuaLS binary exists, has non-trivial size, and is executable.
 */
@@ -1250,10 +1471,198 @@ 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;
 	}
 }
+//#endregion
+//#region src/luals/cache.ts
+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.
+*/
+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;
+		try {
+			fs.unlinkSync(metaPath);
+			logger.warn(`[luals] Stale or invalid LuaLS metadata at ${metaPath} purged.`);
+		} catch (unlinkErr) {
+			logger.debug(`[luals] Failed to unlink invalid metadata: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}`);
+		}
+	} catch (err) {
+		logger.debug(`[luals] Failed to parse LuaLS metadata: ${err instanceof Error ? err.message : String(err)}`);
+		try {
+			fs.unlinkSync(metaPath);
+			logger.warn(`[luals] Corrupted LuaLS metadata at ${metaPath} purged.`);
+		} catch (unlinkErr) {
+			logger.debug(`[luals] Failed to unlink corrupted metadata: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}`);
+		}
+	}
+	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 candidate LuaLS version directories under baseCacheDir without running
+* execution smoke tests on the binaries.
+*/
+function listCachedLuaLSVersionDirs(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) versions.push(version);
+		}
+		return versions;
+	} catch (err) {
+		logger.debug(`[luals] Failed to list cached LuaLS version directories: ${err instanceof Error ? err.message : String(err)}`);
+		return [];
+	}
+}
+/**
+* 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);
+	if (path.resolve(legacyCache) !== path.resolve(primaryCache)) {
+		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;
+}
+//#endregion
+//#region src/luals/download.ts
+const execFileAsync$1 = promisify(execFile);
+/**
+* Escapes single quotes for safe PowerShell single-quoted string interpolation.
+*/
+function escapePowerShellSingleQuote(str) {
+	return str.replace(/'/g, "''");
+}
 async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDir, options) {
 	const resolvedVersion = await resolveLuaLSVersion(version);
 	const info = getPlatformInfo(resolvedVersion);
@@ -1261,76 +1670,86 @@ async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDi
 	const binaryPath = path.join(destDir, info.binaryRelativePath);
 	const completeMarker = path.join(destDir, ".complete");
 	if (fs.existsSync(destDir)) {
-		if (fs.existsSync(binaryPath) && fs.existsSync(completeMarker)) try {
+		if (options?.reuseExisting !== false && 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) {
+				if (lastErr instanceof LuaLSError) throw lastErr;
+				throw new LuaLSError(`Failed to download LuaLS from ${url}${lastErr ? `: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}` : ""}`, "ERR_LUALS_DOWNLOAD", "Check your network connection or specify a custom binary with LUALS_BIN.", { cause: lastErr });
+			}
+			const arrayBuffer = await response.arrayBuffer();
+			fs.writeFileSync(archivePath, Buffer.from(arrayBuffer));
+			if (!options?.quiet) logger.info(`[luals] Extracting to ${destDir}...`);
+			try {
+				await execFileAsync$1("tar", [
+					"-xf",
+					archivePath,
+					"-C",
+					tempDir
+				]);
+			} catch (tarErr) {
+				if (process.platform === "win32" && info.assetName.endsWith(".zip")) await execFileAsync$1("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 {}
-		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.`);
+		} 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 LuaLSError(`Failed to extract valid LuaLS binary to expected path: ${tempBinaryPath}`, "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and ensure there is sufficient disk space.");
+		if (!isBinaryValid(tempBinaryPath)) throw new LuaLSError(`Extracted LuaLS binary at ${tempBinaryPath} is invalid or non-functional.`, "ERR_LUALS_INVALID_BINARY", "Run 'nanos-lint clean-cache' to remove corrupted downloads or set LUALS_BIN to a custom binary.");
 		fs.writeFileSync(path.join(tempDir, ".complete"), resolvedVersion, "utf-8");
 		for (let attempt = 0; attempt < 5; attempt++) try {
 			fs.renameSync(tempDir, destDir);
@@ -1342,8 +1761,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 +1774,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,137 +1788,13 @@ async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDi
 				recursive: true,
 				force: true
 			});
-		} catch {}
-	}
-}
-async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
-	if (process.env.LUALS_BIN && fs.existsSync(process.env.LUALS_BIN)) return process.env.LUALS_BIN;
-	if (!version || version === "latest") {
-		const defaultInfo = getPlatformInfo(FALLBACK_LUALS_VERSION);
-		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...`);
-		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;
-		}
-	}
-	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);
-}
-async function runLuaLSCheck(targetPath, configPath, options) {
-	const absoluteTarget = path.resolve(targetPath);
-	if (!fs.existsSync(absoluteTarget)) throw new Error(`Target path does not exist: ${targetPath}`);
-	const binary = options.lualsBin || await resolveLuaLSBinary(options.lualsVersion, { quiet: options.quiet });
-	let checkDir = absoluteTarget;
-	let targetFileOnly = null;
-	if (fs.statSync(absoluteTarget).isFile()) {
-		checkDir = path.dirname(absoluteTarget);
-		targetFileOnly = absoluteTarget;
-	}
-	const tempOutputDir = systemPaths.temp;
-	fs.mkdirSync(tempOutputDir, { recursive: true });
-	const checkOutPath = path.join(tempOutputDir, `check-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`);
-	const args = [
-		`--check=${checkDir}`,
-		`--configpath=${path.resolve(configPath)}`,
-		`--check_out_path=${checkOutPath}`,
-		"--check_format=json"
-	];
-	if (options.checklevel) args.push(`--checklevel=${options.checklevel}`);
-	let execError = null;
-	try {
-		await execFileAsync(binary, args, {
-			maxBuffer: 104857600,
-			timeout: 12e4
-		});
-	} catch (err) {
-		execError = err;
-	}
-	let diagnostics = {};
-	let parseSucceeded = false;
-	if (fs.existsSync(checkOutPath)) try {
-		const content = fs.readFileSync(checkOutPath, "utf-8");
-		diagnostics = JSON.parse(content);
-		parseSucceeded = true;
-	} catch {} finally {
-		try {
-			fs.unlinkSync(checkOutPath);
-		} catch {}
-	}
-	if (!parseSucceeded) {
-		const cacheHint = `(Cache location: ${getCacheDir()})`;
-		if (execError) throw new Error(`LuaLS check failed to execute or produce diagnostic output: ${execError instanceof Error ? execError.message : String(execError)}. ${cacheHint}`);
-		throw new Error(`LuaLS check failed to produce diagnostic output at: ${checkOutPath}. ${cacheHint}`);
-	}
-	if (targetFileOnly) {
-		const filtered = {};
-		const normTarget = path.resolve(targetFileOnly).toLowerCase();
-		for (const [rawUri, diags] of Object.entries(diagnostics)) {
-			const filePath = fileUriToPath(rawUri);
-			if (path.resolve(filePath).toLowerCase() === normTarget) filtered[rawUri] = diags;
+		} catch (err) {
+			logger.debug(`[luals] Failed to clean up temporary directory ${tempDir}: ${err instanceof Error ? err.message : String(err)}`);
 		}
-		diagnostics = filtered;
 	}
-	let totalProblems = 0;
-	let totalErrors = 0;
-	let totalWarnings = 0;
-	let problemFiles = 0;
-	for (const [_, diags] of Object.entries(diagnostics)) if (diags.length > 0) {
-		problemFiles += 1;
-		totalProblems += diags.length;
-		for (const d of diags) if (d.severity === 1) totalErrors += 1;
-		else if (d.severity === 2) totalWarnings += 1;
-	}
-	const passed = totalProblems === 0;
-	const filesChecked = countCheckedFiles(targetPath, configPath);
-	return {
-		passed,
-		totalProblems,
-		totalErrors,
-		totalWarnings,
-		totalFiles: passed ? filesChecked : problemFiles,
-		totalFilesChecked: filesChecked,
-		diagnostics
-	};
 }
+//#endregion
+//#region src/luals/files.ts
 /**
 * Counts candidate Lua files within targetPath, taking ignoreDir and files.exclude into account.
 */
@@ -1514,7 +1813,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 +1833,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 +1847,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 +1859,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 +1870,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;
 				}
 			})()) {
@@ -1581,6 +1888,257 @@ function countCheckedFiles(targetPath, configPath) {
 	return count;
 }
 //#endregion
+//#region src/luals/runner.ts
+const execFileAsync = promisify(execFile);
+function isOfflineError(err) {
+	if (!err) return false;
+	const msg = err instanceof Error ? err.message : String(err);
+	return /offline|enotfound|eai_again|econnrefused|etimedout|fetch failed/i.test(msg);
+}
+async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
+	if (process.env.LUALS_BIN && fs.existsSync(process.env.LUALS_BIN)) return process.env.LUALS_BIN;
+	if (options?.reuseExisting !== false && (!version || version === "latest")) {
+		const defaultInfo = getPlatformInfo(FALLBACK_LUALS_VERSION);
+		const defaultBundledPath = path.join(getPackageRoot(), defaultInfo.binaryRelativePath);
+		if (fs.existsSync(defaultBundledPath) && isBinaryValid(defaultBundledPath)) return defaultBundledPath;
+	}
+	const isDefaultOrLatest = !version || version === "latest";
+	const baseCacheDir = options?.cacheDir ?? getBaseLuaLSCacheDir();
+	if (!isDefaultOrLatest) {
+		const resolvedVersion = await resolveLuaLSVersion(version);
+		const info = getPlatformInfo(resolvedVersion);
+		if (options?.reuseExisting !== false) {
+			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");
+		let wasCorrupted = false;
+		if (fs.existsSync(cachedPath)) {
+			let isValid = false;
+			if (fs.existsSync(completeMarker)) try {
+				if (fs.readFileSync(completeMarker, "utf-8").trim() === resolvedVersion && isBinaryValid(cachedPath)) {
+					isValid = true;
+					if (options?.reuseExisting !== false) return cachedPath;
+				}
+			} catch (err) {
+				logger.debug(`[luals] Failed to read complete marker at ${completeMarker}: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			if (!isValid) {
+				wasCorrupted = true;
+				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)}`);
+			}
+		}
+		if (options?.reuseExisting !== false) {
+			const legacyDir = getLegacyCacheDir(resolvedVersion);
+			if (path.resolve(legacyDir) !== path.resolve(cachedDir)) {
+				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) {
+						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;
+					}
+				}
+			}
+		}
+		if (options?.reuseExisting !== false) 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 (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);
+		} catch (err) {
+			if (wasCorrupted) {
+				const isOffline = isOfflineError(err);
+				const reason = isOffline ? "while offline" : err instanceof Error ? err.message : String(err);
+				throw new LuaLSError(`Cached LuaLS binary at '${cachedPath}' is corrupted (failed execution/size check) and cannot be re-downloaded ${isOffline ? reason : `: ${reason}`}. Please ${isOffline ? "connect to the internet" : "verify your network connection"} to repair or run 'nanos-lint clean-cache'.`, "ERR_LUALS_CORRUPTED_CACHE", "Connect to the internet to repair the corrupted binary or run 'nanos-lint clean-cache'.", { cause: err });
+			}
+			throw err;
+		}
+	}
+	const currentWeek = getIsoWeek();
+	const metadata = readLuaLSMetadata(baseCacheDir);
+	if (options?.reuseExisting !== false && 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 = options?.reuseExisting !== false ? listCachedLuaLSVersions(baseCacheDir) : [];
+	const firstCachedVersion = cachedVersions[0];
+	if (options?.reuseExisting !== false && metadata && metadata.lastCheckedWeek === currentWeek && firstCachedVersion) {
+		const info = getPlatformInfo(firstCachedVersion);
+		return path.join(getCacheDir(firstCachedVersion, 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 (firstCachedVersion) {
+		logger.info(`[luals] Network unreachable or rate limited; using cached LuaLS ${firstCachedVersion}.`);
+		targetVersion = firstCachedVersion;
+	} 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");
+	let wasCorrupted = false;
+	if (fs.existsSync(targetBinaryPath)) {
+		if (fs.existsSync(completeMarker) && isBinaryValid(targetBinaryPath)) {
+			if (options?.reuseExisting !== false) {
+				cleanupOldCachedLuaLSVersions(targetVersion, baseCacheDir);
+				return targetBinaryPath;
+			}
+		} else wasCorrupted = true;
+	}
+	if (options?.reuseExisting !== false && !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 (err) {
+		logger.debug(`[luals] LuaLS binary not found in PATH: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	let downloadedBinary;
+	try {
+		downloadedBinary = await downloadAndExtractLuaLS(targetVersion, targetCacheDir, options);
+	} catch (err) {
+		if (wasCorrupted) {
+			const isOffline = isOfflineError(err);
+			const reason = isOffline ? "while offline" : err instanceof Error ? err.message : String(err);
+			throw new LuaLSError(`Cached LuaLS binary at '${targetBinaryPath}' is corrupted (failed execution/size check) and cannot be re-downloaded ${isOffline ? reason : `: ${reason}`}. Please ${isOffline ? "connect to the internet" : "verify your network connection"} to repair or run 'nanos-lint clean-cache'.`, "ERR_LUALS_CORRUPTED_CACHE", "Connect to the internet to repair the corrupted binary or run 'nanos-lint clean-cache'.", { cause: err });
+		}
+		throw err;
+	}
+	cleanupOldCachedLuaLSVersions(targetVersion, baseCacheDir);
+	return downloadedBinary;
+}
+async function runLuaLSCheck(targetPath, configPath, options) {
+	let absoluteTarget = path.resolve(targetPath);
+	try {
+		if (fs.existsSync(absoluteTarget)) absoluteTarget = fs.realpathSync.native(absoluteTarget);
+	} catch (err) {
+		logger.debug(`[luals] Failed to resolve native realpath for target: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	if (!fs.existsSync(absoluteTarget)) throw new LuaLSError(`Target path does not exist: ${targetPath}`, "ERR_TARGET_NOT_FOUND", "Verify that the target path exists and is accessible.");
+	const binary = options.lualsBin || await resolveLuaLSBinary(options.lualsVersion, { quiet: options.quiet });
+	let checkDir = absoluteTarget;
+	let targetFileOnly = null;
+	if (fs.statSync(absoluteTarget).isFile()) {
+		checkDir = path.dirname(absoluteTarget);
+		targetFileOnly = absoluteTarget;
+	}
+	const tempOutputDir = systemPaths.temp;
+	fs.mkdirSync(tempOutputDir, { recursive: true });
+	const checkOutPath = path.join(tempOutputDir, `check-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`);
+	const args = [
+		`--check=${checkDir}`,
+		`--configpath=${path.resolve(configPath)}`,
+		`--check_out_path=${checkOutPath}`,
+		"--check_format=json"
+	];
+	if (options.checklevel) args.push(`--checklevel=${options.checklevel}`);
+	let execError = null;
+	try {
+		await execFileAsync(binary, args, {
+			maxBuffer: 104857600,
+			timeout: 12e4
+		});
+	} 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;
+	if (fs.existsSync(checkOutPath)) try {
+		const content = fs.readFileSync(checkOutPath, "utf-8");
+		diagnostics = JSON.parse(content);
+		parseSucceeded = true;
+	} 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 (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()})`;
+		if (execError) throw new LuaLSError(`LuaLS check failed to execute or produce diagnostic output: ${execError instanceof Error ? execError.message : String(execError)}. ${cacheHint}`, "ERR_LUALS_EXECUTION", "Inspect the debug log with --log-level=debug or run 'nanos-lint clean-cache' to re-fetch LuaLS.", { cause: execError });
+		throw new LuaLSError(`LuaLS check failed to produce diagnostic output at: ${checkOutPath}. ${cacheHint}`, "ERR_LUALS_NO_OUTPUT", "Ensure the temporary directory is writable and sufficient disk space is available.");
+	}
+	if (targetFileOnly) {
+		const filtered = {};
+		const normalizeComparable = (p) => {
+			try {
+				if (fs.existsSync(p)) return fs.realpathSync.native(p).replace(/\\/g, "/").toLowerCase();
+			} catch (err) {
+				logger.debug(`[luals] Failed to resolve native realpath for comparison: ${err instanceof Error ? err.message : String(err)}`);
+			}
+			return path.resolve(p).replace(/\\/g, "/").toLowerCase();
+		};
+		const normTarget = normalizeComparable(targetFileOnly);
+		for (const [rawUri, diags] of Object.entries(diagnostics)) if (normalizeComparable(fileUriToPath(rawUri)) === normTarget) filtered[rawUri] = diags;
+		diagnostics = filtered;
+	}
+	let totalProblems = 0;
+	let totalErrors = 0;
+	let totalWarnings = 0;
+	let problemFiles = 0;
+	for (const [_, diags] of Object.entries(diagnostics)) if (diags.length > 0) {
+		problemFiles += 1;
+		totalProblems += diags.length;
+		for (const d of diags) if (d.severity === 1) totalErrors += 1;
+		else if (d.severity === 2) totalWarnings += 1;
+	}
+	const passed = totalProblems === 0;
+	const filesChecked = countCheckedFiles(targetPath, configPath);
+	return {
+		passed,
+		totalProblems,
+		totalErrors,
+		totalWarnings,
+		totalFiles: passed ? filesChecked : problemFiles,
+		totalFilesChecked: filesChecked,
+		diagnostics
+	};
+}
+//#endregion
 //#region src/reporter.ts
 const SEVERITY_NAMES = {
 	1: "Error",
@@ -1661,7 +2219,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,9 +5274,43 @@ 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 {}
+		try {
+			fs.unlinkSync(metaPath);
+			logger.warn(`[annotations] Stale or invalid annotations metadata at ${metaPath} purged.`);
+		} catch (unlinkErr) {
+			logger.debug(`[annotations] Failed to unlink invalid metadata: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}`);
+		}
+	} catch (err) {
+		logger.debug(`Failed to parse annotations metadata: ${err instanceof Error ? err.message : String(err)}`);
+		try {
+			fs.unlinkSync(metaPath);
+			logger.warn(`[annotations] Corrupted annotations metadata at ${metaPath} purged.`);
+		} catch (unlinkErr) {
+			logger.debug(`[annotations] Failed to unlink corrupted metadata: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}`);
+		}
+	}
 	return null;
 }
+/**
+* Verifies that an annotations file exists, is a regular file, is of non-trivial size (>= 1000 bytes),
+* and begins with valid Lua comments or nanos world definitions.
+*/
+function isAnnotationsValid(filePath) {
+	if (!fs.existsSync(filePath)) return false;
+	try {
+		const stat = fs.statSync(filePath);
+		if (!stat.isFile() || stat.size < 1e3) return false;
+		const fd = fs.openSync(filePath, "r");
+		const buffer = Buffer.alloc(256);
+		const bytesRead = fs.readSync(fd, buffer, 0, 256, 0);
+		fs.closeSync(fd);
+		const header = buffer.toString("utf-8", 0, bytesRead).trimStart();
+		return header.startsWith("--") || header.includes("nanos world");
+	} catch (err) {
+		logger.debug(`[annotations] Annotation validation failed for ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+		return false;
+	}
+}
 async function fetchLatestCommitId() {
 	try {
 		const headers = { "User-Agent": "nanos-lint" };
@@ -4729,7 +5323,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() {
@@ -4737,9 +5333,9 @@ async function fetchRawAnnotationsContent() {
 		headers: { "User-Agent": "nanos-lint" },
 		signal: AbortSignal.timeout(15e3)
 	});
-	if (!res.ok) throw new Error(`Failed to download annotations.lua: ${res.status} ${res.statusText}`);
+	if (!res.ok) throw new AnnotationsError(`Failed to download annotations.lua: ${res.status} ${res.statusText}`, "ERR_ANNOTATIONS_DOWNLOAD", "Verify your internet connection and that GitHub raw endpoints are accessible.");
 	const text = await res.text();
-	if (!text || text.length < 1e3) throw new Error("Downloaded annotations.lua appears truncated or invalid");
+	if (!text || text.length < 1e3) throw new AnnotationsError("Downloaded annotations.lua appears truncated or invalid", "ERR_ANNOTATIONS_INVALID", "Retry downloading or pass a local annotations file via --annotations <path>.");
 	return text;
 }
 async function copyFileWithRetry(src, dest, maxRetries = 10) {
@@ -4774,7 +5370,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 +5390,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 +5417,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 +5427,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 +5441,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)}`);
+		}
 	}
 }
 /**
@@ -4855,39 +5457,53 @@ async function downloadAndCacheAnnotations(commitId, cacheDir = getAnnotationsCa
 async function resolveAnnotations(options = {}) {
 	if (options.customPath) {
 		const resolved = path.resolve(options.customPath);
-		if (!fs.existsSync(resolved)) throw new Error(`Custom annotations file not found: ${resolved}`);
+		if (!fs.existsSync(resolved)) throw new AnnotationsError(`Custom annotations file not found: ${resolved}`, "ERR_ANNOTATIONS_NOT_FOUND", "Verify that the path specified in --annotations exists and is accessible.");
 		return resolved;
 	}
 	const envPath = process.env.NANOS_ANNOTATIONS_PATH || process.env.NANOS_ANNOTATIONS;
 	if (envPath) {
 		const resolved = path.resolve(envPath);
-		if (!fs.existsSync(resolved)) throw new Error(`Annotations file specified in environment not found: ${resolved}`);
+		if (!fs.existsSync(resolved)) throw new AnnotationsError(`Annotations file specified in environment not found: ${resolved}`, "ERR_ANNOTATIONS_ENV_NOT_FOUND", "Verify that the path specified in NANOS_ANNOTATIONS_PATH or NANOS_ANNOTATIONS exists.");
 		return resolved;
 	}
 	const bundled = path.join(getPackageRoot(), "annotations.lua");
-	if (fs.existsSync(bundled)) return bundled;
+	if (fs.existsSync(bundled) && isAnnotationsValid(bundled)) return bundled;
 	const cacheDir = options.cacheDir ?? getAnnotationsCacheDir();
 	const cachedAnnotationsFile = path.join(cacheDir, ANNOTATIONS_FILENAME);
 	const metadata = readAnnotationsMetadata(cacheDir);
 	const { dateStr } = getTodayDateString();
-	if (metadata && metadata.lastChecked === dateStr && fs.existsSync(cachedAnnotationsFile)) return cachedAnnotationsFile;
+	if (fs.existsSync(cachedAnnotationsFile) && !isAnnotationsValid(cachedAnnotationsFile)) {
+		logger.warn("[annotations] Cached annotations.lua is corrupted or empty. Purging and refreshing...");
+		try {
+			fs.unlinkSync(cachedAnnotationsFile);
+		} catch (err) {
+			logger.warn(`[annotations] Failed to remove corrupted cached annotations: ${err instanceof Error ? err.message : String(err)}`);
+		}
+	}
+	if (metadata && metadata.lastChecked === dateStr && fs.existsSync(cachedAnnotationsFile) && isAnnotationsValid(cachedAnnotationsFile)) return cachedAnnotationsFile;
 	const latestCommitId = await fetchLatestCommitId();
 	if (latestCommitId) {
-		if (metadata && metadata.commitId === latestCommitId && fs.existsSync(cachedAnnotationsFile)) {
+		if (metadata && metadata.commitId === latestCommitId && fs.existsSync(cachedAnnotationsFile) && isAnnotationsValid(cachedAnnotationsFile)) {
 			updateLastCheckedDate(latestCommitId, cacheDir);
 			return cachedAnnotationsFile;
 		}
 		return await downloadAndCacheAnnotations(latestCommitId, cacheDir, options);
 	}
-	if (fs.existsSync(cachedAnnotationsFile)) {
+	if (fs.existsSync(cachedAnnotationsFile) && isAnnotationsValid(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 {
 		return await downloadAndCacheAnnotations("unknown", cacheDir, options);
 	} catch (err) {
+		if (fs.existsSync(bundled) && isAnnotationsValid(bundled)) {
+			logger.info("[annotations] Network offline and cache unavailable. Falling back to bundled annotations.");
+			return bundled;
+		}
 		if (Boolean(err && typeof err === "object" && "code" in err && typeof err.code === "string" && [
 			"EACCES",
 			"EPERM",
@@ -4895,20 +5511,116 @@ async function resolveAnnotations(options = {}) {
 			"EROFS",
 			"EEXIST",
 			"ENOENT"
-		].includes(err.code)) || err instanceof Error && /permission denied|read-only|no space left/i.test(err.message)) throw new Error(`Failed to resolve nanos world API annotations due to a filesystem error: ${err instanceof Error ? err.message : String(err)}. Please check directory permissions or pass a custom file with --annotations.`, { cause: err });
-		throw new Error(`Failed to resolve nanos world API annotations. Please check your network connection or pass a custom file with --annotations. (${err instanceof Error ? err.message : String(err)})`, { cause: err });
+		].includes(err.code)) || err instanceof Error && /permission denied|read-only|no space left/i.test(err.message)) throw new AnnotationsError(`Failed to resolve nanos world API annotations due to a filesystem error: ${err instanceof Error ? err.message : String(err)}. Please check directory permissions or pass a custom file with --annotations.`, "ERR_ANNOTATIONS_FS", "Check directory permissions for the cache directory or specify --annotations <path>.", { cause: err });
+		throw new AnnotationsError(`Failed to resolve nanos world API annotations. Please check your network connection or pass a custom file with --annotations. (${err instanceof Error ? err.message : String(err)})`, "ERR_ANNOTATIONS_NETWORK", "Check your network connection, run 'nanos-lint warmup' when online, or specify --annotations <path>.", { cause: err });
 	}
 }
 //#endregion
+//#region src/cache-status.ts
+function getCacheStatus(baseCacheDir = systemPaths.cache) {
+	const totalSize = getDirectorySize(baseCacheDir);
+	const totalSizeFormatted = formatBytes(totalSize);
+	const lualsBaseDir = path.join(baseCacheDir, "luals");
+	const lualsMeta = readLuaLSMetadata(lualsBaseDir);
+	const candidateVersions = listCachedLuaLSVersionDirs(lualsBaseDir);
+	const versionInfos = [];
+	for (const ver of candidateVersions) {
+		const versionDir = getCacheDir(ver, lualsBaseDir);
+		const marker = path.join(versionDir, ".complete");
+		const info = getPlatformInfo(ver);
+		const binPath = path.join(versionDir, info.binaryRelativePath);
+		let isValid = false;
+		if (fs.existsSync(marker) && fs.existsSync(binPath)) try {
+			isValid = fs.readFileSync(marker, "utf-8").trim() === ver && isBinaryValid(binPath);
+		} catch {
+			isValid = false;
+		}
+		const dirSize = getDirectorySize(versionDir);
+		versionInfos.push({
+			version: ver,
+			status: isValid ? "valid" : "corrupted",
+			size: dirSize,
+			sizeFormatted: formatBytes(dirSize),
+			path: versionDir
+		});
+	}
+	const lualsStatus = {
+		weeklyCheck: lualsMeta?.lastCheckedWeek ?? null,
+		lastCheckedDate: lualsMeta?.lastCheckedDate ?? null,
+		targetVersion: lualsMeta?.latestVersion ?? null,
+		versions: versionInfos
+	};
+	const annotationsDir = path.join(baseCacheDir, "annotations");
+	const annotationsFile = path.join(annotationsDir, "annotations.lua");
+	const annMeta = readAnnotationsMetadata(annotationsDir);
+	let annStatus = "missing";
+	let annSize = 0;
+	if (fs.existsSync(annotationsFile)) {
+		annSize = getDirectorySize(annotationsFile);
+		annStatus = isAnnotationsValid(annotationsFile) ? "valid" : "corrupted";
+	}
+	return {
+		cacheDirectory: baseCacheDir,
+		totalSize,
+		totalSizeFormatted,
+		luals: lualsStatus,
+		annotations: {
+			status: annStatus,
+			size: annSize,
+			sizeFormatted: formatBytes(annSize),
+			path: annotationsFile,
+			commitId: annMeta?.commitId ?? null,
+			lastChecked: annMeta?.lastChecked ?? null
+		}
+	};
+}
+function formatCacheStatusPretty(report) {
+	const lines = [];
+	lines.push("nanos-lint Cache Status");
+	lines.push("");
+	lines.push(`Cache Directory:   ${report.cacheDirectory}`);
+	lines.push(`Total Disk Usage:  ${report.totalSizeFormatted}`);
+	lines.push("");
+	lines.push("Lua Language Server (LuaLS):");
+	const weeklyStr = report.luals.weeklyCheck ? `${report.luals.weeklyCheck}${report.luals.lastCheckedDate ? ` (last checked: ${report.luals.lastCheckedDate})` : ""}` : "none";
+	lines.push(`  - Weekly Check:   ${weeklyStr}`);
+	const targetVer = report.luals.targetVersion ?? "none";
+	lines.push(`  - Target Version: ${targetVer}`);
+	if (report.luals.versions.length === 0) lines.push("  - Cached Copies:  none");
+	else {
+		lines.push("  - Cached Copies:");
+		for (const v of report.luals.versions) lines.push(`      * ${v.version} (status: ${v.status}, size: ${v.sizeFormatted})`);
+	}
+	lines.push("");
+	lines.push("nanos world Annotations:");
+	if (report.annotations.status === "missing") lines.push("  - Status:         Not cached");
+	else {
+		const statusCap = report.annotations.status === "valid" ? "Valid" : "Corrupted";
+		lines.push(`  - Status:         ${statusCap} (${report.annotations.sizeFormatted})`);
+		if (report.annotations.commitId) {
+			const sha = report.annotations.commitId;
+			const shaDisplay = sha.length >= 7 && sha !== "unknown" ? `${sha.slice(0, 8)} (docgen-output)` : sha;
+			lines.push(`  - Commit SHA:     ${shaDisplay}`);
+		}
+		if (report.annotations.lastChecked) lines.push(`  - Last Checked:   ${report.annotations.lastChecked}`);
+	}
+	return lines.join("\n");
+}
+//#endregion
 //#region src/cli.ts
 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 +5628,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 +5652,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,
@@ -4943,7 +5674,7 @@ function createProgram(options) {
 		};
 		if (opts.config) {
 			const resolvedConfig = path.resolve(opts.config);
-			if (!fs.existsSync(resolvedConfig)) throw new Error(`Configuration file not found: ${resolvedConfig}`);
+			if (!fs.existsSync(resolvedConfig)) throw new ConfigError(`Configuration file not found: ${resolvedConfig}`, "ERR_CONFIG_NOT_FOUND", "Verify the path passed to --config exists and is readable.");
 		}
 		const annotationsPath = await resolveAnnotations({
 			customPath: opts.annotations,
@@ -4959,48 +5690,81 @@ 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
+		})}`);
+		setExitCode(0);
+	});
+	program.command("warmup").alias("download").description("Pre-fetch and cache both LuaLS binary and annotations for offline execution").option("--luals-version <ver>", `Version of LuaLS to use (default: ${DEFAULT_LUALS_VERSION})`).option("--annotations <path>", "Path to custom annotations.lua file").option("-q, --quiet", "Suppress download progress logging").action(async (opts) => {
+		writeOutput(`[warmup] LuaLS binary ready: ${await resolveLuaLSBinary(opts?.lualsVersion || "latest", { quiet: opts?.quiet })}`);
+		const annotationsPath = await resolveAnnotations({
+			customPath: opts?.annotations,
+			quiet: opts?.quiet
 		});
-		console.log(`[init] Initialized nanos world LuaLS configuration: ${created}`);
+		const meta = readAnnotationsMetadata();
+		writeOutput(`[warmup] nanos world annotations ready: ${annotationsPath}${meta?.commitId && meta.commitId !== "unknown" ? ` (commit ${meta.commitId.slice(0, 7)})` : ""}`);
+		writeOutput("[warmup] Cache pre-warmed successfully. Ready for offline execution.");
 		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(() => {
+	const handleCleanCache = () => {
 		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);
 		}
+	};
+	const handleCacheStatus = (opts) => {
+		const report = getCacheStatus();
+		if (opts?.json) writeOutput(JSON.stringify(report, null, 2));
+		else writeOutput(formatCacheStatusPretty(report));
+		setExitCode(0);
+	};
+	const cacheCmd = program.command("cache").description("Inspect or manage the nanos-lint cache").option("--json", "Output cache state in JSON format");
+	cacheCmd.command("status", { isDefault: true }).alias("info").description("Show cache status, installed versions, and disk usage").option("--json", "Output cache state in JSON format").action((opts, cmd) => {
+		const json = opts?.json || (cmd.parent ? Boolean(cmd.parent.opts()?.json) : false);
+		handleCacheStatus({ json });
+	});
+	cacheCmd.command("clean").description("Clear the nanos-lint cache").action(() => {
+		handleCleanCache();
+	});
+	program.command("cache-status").description("Show cache status, installed versions, and disk usage").option("--json", "Output cache state in JSON format").action((opts) => {
+		handleCacheStatus(opts);
+	});
+	program.command("clean-cache").alias("clean").description("Clear the nanos-lint cache").action(() => {
+		handleCleanCache();
 	});
 	program.command("version").description("Show version information").action(() => {
-		console.log(getVersionString());
+		writeOutput(getVersionString());
 		setExitCode(0);
 	});
 	program.helpCommand("help [command]", "Show this help message");
 	program.addHelpText("after", `
 Examples:
   $ npx nanos-lint
+  $ npx nanos-lint warmup
+  $ npx nanos-lint cache status
   $ npx nanos-lint check ./my-package
   $ npx nanos-lint check . --checklevel=Error
   $ npx nanos-lint check . --ignore "myfolder/hello-*.lua"
@@ -5010,6 +5774,17 @@ 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) continue;
+		if (arg === "-l" || arg === "--log-level") {
+			const nextArg = args[i + 1];
+			if (nextArg && isValidLogLevel(nextArg)) logger.setLevel(nextArg);
+		} 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;
@@ -5019,9 +5794,18 @@ async function runCLI(args = process.argv.slice(2)) {
 		return exitCode;
 	} catch (err) {
 		if (err instanceof CommanderError) return err.exitCode;
+		if (err instanceof NanosLintError) {
+			logger.error(`error: ${err.message}`);
+			if (err.remedy) logger.error(`hint: ${err.remedy}`);
+			if ((logger.getLevel() === "debug" || process.env.DEBUG) && err.stack) {
+				logger.error(err.stack);
+				if (err.cause) logger.error(`cause: ${err.cause instanceof Error ? err.cause.stack || err.cause.message : String(err.cause)}`);
+			}
+			return 1;
+		}
 		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 ((logger.getLevel() === "debug" || process.env.DEBUG) && err instanceof Error && err.stack) logger.error(err.stack);
 		return 1;
 	}
 }
@@ -5031,7 +5815,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 +5828,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 +5841,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 { fetchLatestLuaLSVersionFromGitHub as $, pluralize as A, logger as At, getBaseLuaLSCacheDir as B, updateLastCheckedDate as C, systemPaths as Ct, formatReport as D, LOG_LEVEL_PRIORITY as Dt, formatProblemSummary as E, LOG_LEVELS as Et, downloadAndExtractLuaLS as F, listCachedLuaLSVersionDirs as G, getIsoWeek as H, escapePowerShellSingleQuote as I, writeLuaLSMetadata as J, listCachedLuaLSVersions as K, LUALS_METADATA_FILENAME as L, resolveLuaLSBinary as M, runLuaLSCheck as N, formatSeverityBadge as O, Logger as Ot, countCheckedFiles as P, FALLBACK_LUALS_VERSION as Q, cleanupOldCachedLuaLSVersions as R, resolveAnnotations as S, getDirectorySize as St, formatPretty as T, DEFAULT_LOG_LEVEL as Tt, getLegacyCacheDir as U, getCacheDir as V, getLuaLSMetadataPath as W, getPlatformInfo as X, isBinaryValid as Y, DEFAULT_LUALS_VERSION as Z, getAnnotationsMetadataFilePath as _, ConfigError as _t, formatCacheStatusPretty as a, getDefaultTemplatePath as at, isAnnotationsValid as b, cleanCache as bt, DOCGEN_BRANCH as c, initWorkspace as ct, METADATA_FILENAME as d, parseJsonc as dt, resolveLatestLuaLSVersion as et, RAW_ANNOTATIONS_URL as f, resolveWorkspaceConfig as ft, getAnnotationsCacheDir as g, CacheError as gt, fetchRawAnnotationsContent as h, AnnotationsError as ht, runCLI as i, getDefaultAnnotationsPath as it, shouldEnableColor as j, parseLogLevel as jt, getColors as k, isValidLogLevel as kt, DOCGEN_REPO as l, loadConfigFile as lt, fetchLatestCommitId as m, stripTrailingSlashes as mt, createProgram as n, sanitizeLuaLSVersion as nt, getCacheStatus as o, getDefinitionsDir as ot, downloadAndCacheAnnotations as p, stripJsonComments as pt, readLuaLSMetadata as q, isDirectExecution as r, VALID_LUALS_DIAGNOSTIC_CODES as rt, ANNOTATIONS_FILENAME as s, getPackageRoot as st, collectIgnorePatterns as t, resolveLuaLSVersion as tt, GITHUB_COMMITS_API as u, mergeConfigs as ut, getCachedAnnotationsFilePath as v, LuaLSError as vt, formatGitHubAnnotations as w, fileUriToPath as wt, readAnnotationsMetadata as x, formatBytes as xt, getTodayDateString as y, NanosLintError as yt, findExistingLuaLSDir as z };
 
-//# sourceMappingURL=cli-5LLXRlN7.js.map
+//# sourceMappingURL=cli-DGez8MSI.js.map