nanos-lint 2.5.0 → 2.6.0

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

@@ -2,10 +2,10 @@ import { fileURLToPath } from "node:url";
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
+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";
-import process$1 from "node:process";
 //#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`)
@@ -778,6 +778,93 @@ function printParseErrorCode(code) {
 	}
 	return "<unknown ParseErrorCode>";
 }
+Object.freeze([
+	"",
+	"   ",
+	".",
+	"..",
+	" .",
+	". ",
+	" ..",
+	".. ",
+	"../",
+	"../foo",
+	"foo/../bar",
+	"foo/bar",
+	"foo\\bar",
+	"foo\0bar"
+]);
+function isSafeFilename(filename) {
+	if (typeof filename !== "string") return false;
+	const trimmed = filename.trim();
+	return trimmed !== "" && trimmed !== "." && trimmed !== ".." && !filename.includes("/") && !filename.includes("\\") && !filename.includes("\0");
+}
+function assertSafeFilename(filename) {
+	if (typeof filename !== "string") throw new TypeError("Expected a string");
+	if (!isSafeFilename(filename)) throw new Error(`Unsafe filename: ${JSON.stringify(filename)}`);
+}
+//#endregion
+//#region node_modules/env-paths/index.js
+const homedir = os.homedir();
+const tmpdir = os.tmpdir();
+const { env } = process$1;
+const macos = (name) => {
+	const library = path.join(homedir, "Library");
+	return {
+		data: path.join(library, "Application Support", name),
+		config: path.join(library, "Preferences", name),
+		cache: path.join(library, "Caches", name),
+		log: path.join(library, "Logs", name),
+		temp: path.join(tmpdir, name)
+	};
+};
+const windows = (name) => {
+	const appData = env.APPDATA || path.join(homedir, "AppData", "Roaming");
+	const localAppData = env.LOCALAPPDATA || path.join(homedir, "AppData", "Local");
+	return {
+		data: path.join(localAppData, name, "Data"),
+		config: path.join(appData, name, "Config"),
+		cache: path.join(localAppData, name, "Cache"),
+		log: path.join(localAppData, name, "Log"),
+		temp: path.join(tmpdir, name)
+	};
+};
+const linux = (name) => {
+	const username = path.basename(homedir);
+	return {
+		data: path.join(env.XDG_DATA_HOME || path.join(homedir, ".local", "share"), name),
+		config: path.join(env.XDG_CONFIG_HOME || path.join(homedir, ".config"), name),
+		cache: path.join(env.XDG_CACHE_HOME || path.join(homedir, ".cache"), name),
+		log: path.join(env.XDG_STATE_HOME || path.join(homedir, ".local", "state"), name),
+		temp: path.join(tmpdir, username, name)
+	};
+};
+function envPaths(name, { suffix = "nodejs" } = {}) {
+	assertSafeFilename(name);
+	if (suffix) name += `-${suffix}`;
+	assertSafeFilename(name);
+	if (process$1.platform === "darwin") return macos(name);
+	if (process$1.platform === "win32") return windows(name);
+	return linux(name);
+}
+//#endregion
+//#region src/paths.ts
+/**
+* System paths resolved for nanos-lint using cross-platform conventions
+* provided by env-paths (XDG on Linux, %LOCALAPPDATA%/%APPDATA% on Windows, ~/Library on macOS).
+*/
+const systemPaths = envPaths("nanos-lint", { suffix: "" });
+/**
+* Clears the nanos-lint cache directory.
+* Returns the path of the cleared cache directory, or null if it did not exist.
+*/
+function cleanCache(targetDir = systemPaths.cache) {
+	if (fs.existsSync(targetDir)) {
+		fs.rmSync(targetDir, { recursive: true });
+		return targetDir;
+	}
+	return null;
+}
 //#endregion
 //#region src/config.ts
 const __filename = fileURLToPath(import.meta.url);
@@ -793,9 +880,19 @@ function getPackageRoot() {
 	}
 	return path.resolve(__dirname, "..");
 }
+function getDefaultAnnotationsPath() {
+	const envPath = process.env.NANOS_ANNOTATIONS_PATH || process.env.NANOS_ANNOTATIONS;
+	if (envPath && fs.existsSync(envPath)) return path.resolve(envPath);
+	const bundled = path.join(getPackageRoot(), "annotations.lua");
+	if (fs.existsSync(bundled)) return bundled;
+	return path.join(systemPaths.cache, "annotations", "annotations.lua");
+}
+/**
+* @deprecated Use getDefaultAnnotationsPath() instead.
+* Returns the directory containing the resolved annotations.lua file.
+*/
 function getDefinitionsDir() {
-	const root = getPackageRoot();
-	return path.join(root, "vendor", "nanos-world-vscode-extension");
+	return path.dirname(getDefaultAnnotationsPath());
 }
 function getDefaultTemplatePath() {
 	const root = getPackageRoot();
@@ -837,15 +934,27 @@ function stripTrailingSlashes(value) {
 }
 /**
 * Merges a base nanos configuration with a workspace override configuration.
-* Guarantees that the nanos definitions directory is included in workspace.library,
+* Guarantees that nanos API annotations are included in workspace.library,
 * and standardizes paths for LuaLS.
+*
+* @param base Base configuration template
+* @param override Workspace override configuration
+* @param definitionsPath Path to annotations.lua file or directory containing it
+* @param options Additional merge options
 */
-function mergeConfigs(base, override = {}, definitionsDir = getDefinitionsDir(), options) {
-	const normalizedDefDir = definitionsDir.split(path.sep).join("/");
+function mergeConfigs(base, override = {}, definitionsPath = getDefaultAnnotationsPath(), options) {
+	let resolvedPath = definitionsPath;
+	if (fs.existsSync(definitionsPath)) try {
+		if (fs.statSync(definitionsPath).isDirectory()) {
+			const candidate = path.join(definitionsPath, "annotations.lua");
+			if (fs.existsSync(candidate)) resolvedPath = candidate;
+		}
+	} catch {}
+	const normalizedDefPath = resolvedPath.split(path.sep).join("/");
 	const baseLibraries = base.workspace?.library ?? [];
 	const overrideLibraries = override.workspace?.library ?? [];
 	const librarySet = /* @__PURE__ */ new Set([
-		normalizedDefDir,
+		normalizedDefPath,
 		...baseLibraries,
 		...overrideLibraries
 	]);
@@ -938,7 +1047,7 @@ function mergeConfigs(base, override = {}, definitionsDir = getDefinitionsDir(),
 */
 function resolveWorkspaceConfig(workspacePath, customConfigPath, options) {
 	const defaultTemplate = loadConfigFile(getDefaultTemplatePath());
-	const definitionsDir = getDefinitionsDir();
+	const activeAnnotationsPath = options?.annotationsPath || getDefaultAnnotationsPath();
 	let userConfig = {};
 	if (customConfigPath) userConfig = loadConfigFile(path.resolve(customConfigPath));
 	else {
@@ -961,7 +1070,7 @@ function resolveWorkspaceConfig(workspacePath, customConfigPath, options) {
 		}
 		cliIgnore = expanded;
 	}
-	const merged = mergeConfigs(defaultTemplate, userConfig, definitionsDir, { cliIgnore });
+	const merged = mergeConfigs(defaultTemplate, userConfig, activeAnnotationsPath, { cliIgnore });
 	if (!hasCliIgnore) {
 		const resolvedTarget = path.resolve(workspacePath);
 		if (fs.existsSync(path.join(resolvedTarget, "main.lua")) && (fs.existsSync(path.join(resolvedTarget, "bin", "lua-language-server.exe")) || fs.existsSync(path.join(resolvedTarget, "bin", "lua-language-server")))) {
@@ -976,7 +1085,7 @@ function resolveWorkspaceConfig(workspacePath, customConfigPath, options) {
 			])];
 		}
 	}
-	const tempDir = path.join(os.tmpdir(), "nanos-lint");
+	const tempDir = systemPaths.temp;
 	fs.mkdirSync(tempDir, { recursive: true });
 	const tempConfigFile = path.join(tempDir, `luarc-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.json`);
 	fs.writeFileSync(tempConfigFile, JSON.stringify(merged, null, 2), "utf-8");
@@ -992,9 +1101,8 @@ 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.`);
 	const template = loadConfigFile(getDefaultTemplatePath());
-	const definitionsDir = getDefinitionsDir();
-	const sourceAnnotations = path.join(definitionsDir, "annotations.lua");
-	if (!fs.existsSync(sourceAnnotations)) throw new Error(`Definitions file not found at ${sourceAnnotations}. Make sure submodules are initialized.`);
+	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.`);
 	const targetNanosDir = path.join(workspacePath, ".nanos-lint");
 	fs.mkdirSync(targetNanosDir, { recursive: true });
 	const targetAnnotations = path.join(targetNanosDir, "annotations.lua");
@@ -1119,6 +1227,12 @@ 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);
+}
+/**
+* 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);
 }
@@ -1147,12 +1261,9 @@ 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) && isBinaryValid(binaryPath)) {
-			if (!fs.existsSync(completeMarker)) try {
-				fs.writeFileSync(completeMarker, resolvedVersion, "utf-8");
-			} catch {}
-			return binaryPath;
-		}
+		if (fs.existsSync(binaryPath) && fs.existsSync(completeMarker)) try {
+			if (fs.readFileSync(completeMarker, "utf-8").trim() === resolvedVersion && isBinaryValid(binaryPath)) return binaryPath;
+		} catch {}
 		try {
 			fs.rmSync(destDir, {
 				recursive: true,
@@ -1219,6 +1330,7 @@ async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDi
 			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.`);
 		fs.writeFileSync(path.join(tempDir, ".complete"), resolvedVersion, "utf-8");
 		for (let attempt = 0; attempt < 5; attempt++) try {
 			fs.renameSync(tempDir, destDir);
@@ -1235,9 +1347,16 @@ async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDi
 				return binaryPath;
 			}
 			if (attempt < 4) await new Promise((resolve) => setTimeout(resolve, 100 * (attempt + 1)));
-			else throw renameErr;
+			else {
+				if (fs.existsSync(destDir) && (!fs.existsSync(binaryPath) || !fs.existsSync(completeMarker))) try {
+					fs.rmSync(destDir, {
+						recursive: true,
+						force: true
+					});
+				} catch {}
+				throw renameErr;
+			}
 		}
-		if (!isBinaryValid(binaryPath)) throw new Error(`Extracted LuaLS binary at ${binaryPath} is invalid or non-functional.`);
 		if (!options?.quiet) console.log(`[luals] Ready: ${binaryPath}`);
 		return binaryPath;
 	} finally {
@@ -1251,6 +1370,11 @@ async function downloadAndExtractLuaLS(version = DEFAULT_LUALS_VERSION, targetDi
 }
 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);
@@ -1259,12 +1383,9 @@ async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
 	const cachedPath = path.join(cachedDir, info.binaryRelativePath);
 	const completeMarker = path.join(cachedDir, ".complete");
 	if (fs.existsSync(cachedPath)) {
-		if (isBinaryValid(cachedPath)) {
-			if (!fs.existsSync(completeMarker)) try {
-				fs.writeFileSync(completeMarker, resolvedVersion, "utf-8");
-			} catch {}
-			return 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, {
@@ -1273,6 +1394,24 @@ async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
 			});
 		} 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"]);
@@ -1291,7 +1430,7 @@ async function runLuaLSCheck(targetPath, configPath, options) {
 		checkDir = path.dirname(absoluteTarget);
 		targetFileOnly = absoluteTarget;
 	}
-	const tempOutputDir = path.join(os.tmpdir(), "nanos-lint");
+	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 = [
@@ -4539,6 +4678,228 @@ function useColor() {
 }
 new Command();
 //#endregion
+//#region src/annotations.ts
+const DOCGEN_REPO = "nanos-world/vscode-extension";
+const DOCGEN_BRANCH = "docgen-output";
+const RAW_ANNOTATIONS_URL = "https://raw.githubusercontent.com/nanos-world/vscode-extension/refs/heads/docgen-output/annotations.lua";
+const GITHUB_COMMITS_API = "https://api.github.com/repos/nanos-world/vscode-extension/commits/docgen-output";
+const ANNOTATIONS_FILENAME = "annotations.lua";
+const METADATA_FILENAME = "metadata.json";
+function getTodayDateString(d = /* @__PURE__ */ new Date()) {
+	const year = d.getFullYear();
+	const month = d.getMonth() + 1;
+	const day = d.getDate();
+	return {
+		dateStr: `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`,
+		dateObj: {
+			year,
+			month,
+			day
+		}
+	};
+}
+function getAnnotationsCacheDir() {
+	return path.join(systemPaths.cache, "annotations");
+}
+function getCachedAnnotationsFilePath() {
+	return path.join(getAnnotationsCacheDir(), ANNOTATIONS_FILENAME);
+}
+function getAnnotationsMetadataFilePath() {
+	return path.join(getAnnotationsCacheDir(), METADATA_FILENAME);
+}
+function readAnnotationsMetadata(cacheDir = getAnnotationsCacheDir()) {
+	const metaPath = path.join(cacheDir, "metadata.json");
+	if (!fs.existsSync(metaPath)) return null;
+	try {
+		const content = fs.readFileSync(metaPath, "utf-8");
+		const parsed = JSON.parse(content);
+		if (typeof parsed?.commitId === "string" && typeof parsed?.lastChecked === "string") return parsed;
+	} catch {}
+	return null;
+}
+async function fetchLatestCommitId() {
+	try {
+		const headers = { "User-Agent": "nanos-lint" };
+		if (process.env.GITHUB_TOKEN) headers["Authorization"] = `token ${process.env.GITHUB_TOKEN}`;
+		const res = await fetch(GITHUB_COMMITS_API, {
+			headers,
+			signal: AbortSignal.timeout(5e3)
+		});
+		if (res.ok) {
+			const data = await res.json();
+			if (typeof data.sha === "string" && /^[0-9a-fA-F]{7,40}$/.test(data.sha)) return data.sha;
+		}
+	} catch {}
+	return null;
+}
+async function fetchRawAnnotationsContent() {
+	const res = await fetch(RAW_ANNOTATIONS_URL, {
+		headers: { "User-Agent": "nanos-lint" },
+		signal: AbortSignal.timeout(15e3)
+	});
+	if (!res.ok) throw new Error(`Failed to download annotations.lua: ${res.status} ${res.statusText}`);
+	const text = await res.text();
+	if (!text || text.length < 1e3) throw new Error("Downloaded annotations.lua appears truncated or invalid");
+	return text;
+}
+async function copyFileWithRetry(src, dest, maxRetries = 10) {
+	for (let attempt = 0; attempt < maxRetries; attempt++) try {
+		fs.copyFileSync(src, dest);
+		return;
+	} catch (err) {
+		const code = err?.code;
+		if ((code === "EBUSY" || code === "EPERM") && attempt < maxRetries - 1) {
+			await new Promise((resolve) => setTimeout(resolve, 50 * (attempt + 1)));
+			continue;
+		}
+		throw err;
+	}
+}
+/**
+* Updates the metadata lastChecked date atomically without modifying annotations.lua.
+*/
+function updateLastCheckedDate(commitId, cacheDir = getAnnotationsCacheDir()) {
+	const { dateStr, dateObj } = getTodayDateString();
+	const metadata = {
+		commitId,
+		lastChecked: dateStr,
+		date: dateObj
+	};
+	fs.mkdirSync(cacheDir, { recursive: true });
+	const metaPath = path.join(cacheDir, METADATA_FILENAME);
+	const tempMetaPath = path.join(os.tmpdir(), `.metadata-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.tmp`);
+	try {
+		fs.writeFileSync(tempMetaPath, JSON.stringify(metadata, null, 2), "utf-8");
+		fs.copyFileSync(tempMetaPath, metaPath);
+	} finally {
+		try {
+			if (fs.existsSync(tempMetaPath)) fs.unlinkSync(tempMetaPath);
+		} catch {}
+	}
+	return metadata;
+}
+/**
+* Downloads annotations.lua, writes it and the new metadata in a chained atomic transaction.
+* If any step fails, the previous cache state is reverted.
+*/
+async function downloadAndCacheAnnotations(commitId, cacheDir = getAnnotationsCacheDir(), options) {
+	fs.mkdirSync(cacheDir, { recursive: true });
+	const finalAnnotationsPath = path.join(cacheDir, ANNOTATIONS_FILENAME);
+	const finalMetaPath = path.join(cacheDir, METADATA_FILENAME);
+	const tempDir = path.join(os.tmpdir(), `nanos-ann-tmp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+	const backupDir = path.join(os.tmpdir(), `nanos-ann-bak-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+	let hasBackup = false;
+	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...");
+		}
+		const content = await fetchRawAnnotationsContent();
+		const tempAnnotationsPath = path.join(tempDir, ANNOTATIONS_FILENAME);
+		fs.writeFileSync(tempAnnotationsPath, content, "utf-8");
+		const { dateStr, dateObj } = getTodayDateString();
+		const metadata = {
+			commitId,
+			lastChecked: dateStr,
+			date: dateObj
+		};
+		const tempMetaPath = path.join(tempDir, METADATA_FILENAME);
+		fs.writeFileSync(tempMetaPath, JSON.stringify(metadata, null, 2), "utf-8");
+		const existingMeta = readAnnotationsMetadata(cacheDir);
+		if (existingMeta && existingMeta.commitId === commitId && fs.existsSync(finalAnnotationsPath) && fs.statSync(finalAnnotationsPath).size >= 1e3) return finalAnnotationsPath;
+		const oldAnnotationsExists = fs.existsSync(finalAnnotationsPath);
+		const oldMetaExists = fs.existsSync(finalMetaPath);
+		if (oldAnnotationsExists || oldMetaExists) {
+			fs.mkdirSync(backupDir, { recursive: true });
+			if (oldAnnotationsExists) await copyFileWithRetry(finalAnnotationsPath, path.join(backupDir, ANNOTATIONS_FILENAME));
+			if (oldMetaExists) await copyFileWithRetry(finalMetaPath, path.join(backupDir, METADATA_FILENAME));
+			hasBackup = true;
+		}
+		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.");
+		}
+		return finalAnnotationsPath;
+	} catch (err) {
+		if (hasBackup && fs.existsSync(backupDir)) try {
+			const backupAnnotations = path.join(backupDir, ANNOTATIONS_FILENAME);
+			const backupMeta = path.join(backupDir, METADATA_FILENAME);
+			if (fs.existsSync(backupAnnotations)) await copyFileWithRetry(backupAnnotations, finalAnnotationsPath);
+			if (fs.existsSync(backupMeta)) await copyFileWithRetry(backupMeta, finalMetaPath);
+		} catch {}
+		throw err;
+	} finally {
+		try {
+			if (fs.existsSync(tempDir)) fs.rmSync(tempDir, {
+				recursive: true,
+				force: true
+			});
+			if (fs.existsSync(backupDir)) fs.rmSync(backupDir, {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+	}
+}
+/**
+* Resolves the nanos world annotations.lua definitions file path.
+* Resolution precedence:
+* 1. CLI option (`customPath`)
+* 2. Environment variable (`NANOS_ANNOTATIONS_PATH` or `NANOS_ANNOTATIONS`)
+* 3. Bundled inside package root (`annotations.lua`)
+* 4. User cache (checked once per day from upstream GitHub)
+*/
+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}`);
+		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}`);
+		return resolved;
+	}
+	const bundled = path.join(getPackageRoot(), "annotations.lua");
+	if (fs.existsSync(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;
+	const latestCommitId = await fetchLatestCommitId();
+	if (latestCommitId) {
+		if (metadata && metadata.commitId === latestCommitId && fs.existsSync(cachedAnnotationsFile)) {
+			updateLastCheckedDate(latestCommitId, cacheDir);
+			return cachedAnnotationsFile;
+		}
+		return await downloadAndCacheAnnotations(latestCommitId, cacheDir, options);
+	}
+	if (fs.existsSync(cachedAnnotationsFile)) {
+		try {
+			updateLastCheckedDate(metadata?.commitId || "unknown", cacheDir);
+		} catch {}
+		return cachedAnnotationsFile;
+	}
+	try {
+		return await downloadAndCacheAnnotations("unknown", cacheDir, options);
+	} catch (err) {
+		if (Boolean(err && typeof err === "object" && "code" in err && typeof err.code === "string" && [
+			"EACCES",
+			"EPERM",
+			"ENOSPC",
+			"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 });
+	}
+}
+//#endregion
 //#region src/cli.ts
 function getVersionString() {
 	const root = getPackageRoot();
@@ -4564,7 +4925,7 @@ function createProgram(options) {
 		"Warning",
 		"Information",
 		"Hint"
-	]).default("Warning")).option("--config <path>", "Path to custom .luarc.json configuration file").addOption(new Option("--format <format>", "Output format: pretty, json, github (default: pretty, auto-detects GitHub Actions)").choices([
+	]).default("Warning")).option("--config <path>", "Path to custom .luarc.json configuration file").option("--annotations <path>", "Path to custom annotations.lua file").addOption(new Option("--format <format>", "Output format: pretty, json, github (default: pretty, auto-detects GitHub Actions)").choices([
 		"pretty",
 		"json",
 		"github"
@@ -4580,7 +4941,18 @@ function createProgram(options) {
 			quiet: opts.quiet,
 			ignore: opts.ignore
 		};
-		const resolved = resolveWorkspaceConfig(targetPath, checkOptions.configpath, { ignore: checkOptions.ignore });
+		if (opts.config) {
+			const resolvedConfig = path.resolve(opts.config);
+			if (!fs.existsSync(resolvedConfig)) throw new Error(`Configuration file not found: ${resolvedConfig}`);
+		}
+		const annotationsPath = await resolveAnnotations({
+			customPath: opts.annotations,
+			quiet: opts.quiet
+		});
+		const resolved = resolveWorkspaceConfig(targetPath, checkOptions.configpath, {
+			ignore: checkOptions.ignore,
+			annotationsPath
+		});
 		let result;
 		try {
 			result = await runLuaLSCheck(targetPath, resolved.configPath, checkOptions);
@@ -4594,8 +4966,12 @@ function createProgram(options) {
 		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").action((targetPath = ".", opts) => {
-		const created = initWorkspace(path.resolve(targetPath), { force: opts.force });
+	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), {
+			force: opts.force,
+			annotationsPath
+		});
 		console.log(`[init] Initialized nanos world LuaLS configuration: ${created}`);
 		setExitCode(0);
 	});
@@ -4606,6 +4982,17 @@ function createProgram(options) {
 		console.log(`[luals] Ready at: ${bin}`);
 		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})`);
+			setExitCode(0);
+		} catch (err) {
+			console.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());
 		setExitCode(0);
@@ -4618,6 +5005,7 @@ Examples:
   $ npx nanos-lint check . --checklevel=Error
   $ npx nanos-lint check . --ignore "myfolder/hello-*.lua"
   $ npx nanos-lint init
+  $ npx nanos-lint clean-cache
 `);
 	return program;
 }
@@ -4671,6 +5059,6 @@ if (isDirectExecution()) runCLI().then((code) => {
 	process.exit(1);
 });
 //#endregion
-export { loadConfigFile as A, resolveLuaLSVersion as C, getDefinitionsDir as D, getDefaultTemplatePath as E, stripTrailingSlashes as F, fileUriToPath as I, parseJsonc as M, resolveWorkspaceConfig as N, getPackageRoot as O, stripJsonComments as P, resolveLuaLSBinary as S, sanitizeLuaLSVersion as T, escapePowerShellSingleQuote as _, formatGitHubAnnotations as a, isBinaryValid as b, formatReport as c, pluralize as d, shouldEnableColor as f, downloadAndExtractLuaLS as g, countCheckedFiles as h, runCLI as i, mergeConfigs as j, initWorkspace as k, formatSeverityBadge as l, FALLBACK_LUALS_VERSION as m, createProgram as n, formatPretty as o, DEFAULT_LUALS_VERSION as p, isDirectExecution as r, formatProblemSummary as s, collectIgnorePatterns as t, getColors as u, getCacheDir as v, runLuaLSCheck as w, resolveLatestLuaLSVersion as x, getPlatformInfo as y };
+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 };
 
-//# sourceMappingURL=cli-BVXk8XmH.js.map
+//# sourceMappingURL=cli-5LLXRlN7.js.map