nanos-lint 3.2.0 → 3.3.0

package/README.md

@@ -134,7 +134,8 @@ nanos-lint [command] [options] [paths...]
 
 COMMANDS:
   check [paths...]         Check workspace files or directories (default)
-  init [path]              Scaffold a .luarc.json configuration in the workspace (copies definitions to .nanos-lint/; supports --annotations <path>)
+  init [path]              Scaffold a .luarc.json configuration in the workspace (supports --vendor, --force)
+  copy-annotations [dest]  Copy cached annotations.lua definitions into a target file or directory (alias: export-annotations; targets not ending in .lua are treated as directories)
   warmup, download         Pre-fetch and cache both LuaLS binary and annotations for offline execution
   cache status, cache info Show cache status, installed versions, and disk usage (supports --json)
   cache clean              Clear the nanos-lint cache directory
@@ -153,14 +154,15 @@ OPTIONS:
                            debug adds diagnostic tracing
   --checklevel=<level>     Minimum diagnostic level: Error, Warning, Information, Hint (default: Warning)
   --config=<path>          Path to custom .luarc.json configuration file
-  --annotations=<path>     Path to custom annotations.lua file (applies to both check and init)
+  --annotations=<path>     Path to custom annotations.lua file (applies to check, init --vendor, and copy-annotations)
   --format=<format>        Output format: pretty, json, github (default: pretty)
   --github                 Output in GitHub Actions format (shortcut for --format=github)
   --luals-version=<ver>    Version of LuaLS to use (default: latest, falling back to 3.19.1 when offline)
   --no-fail                Do not exit with code 1 if diagnostics are found
   --realm <realm>          Execution realm to check: all, client, server, shared (default: all)
   --no-progress            Disable the interactive download, extraction and realm derivation progress display
-  -f, --force              (init command only) Overwrite existing .luarc.json
+  --vendor                 (init command only) Vendor annotations.lua into .nanos-lint/ inside workspace
+  -f, --force              (init and copy-annotations only) Overwrite existing files
 ```
 
 ### Progress Display
@@ -223,7 +225,7 @@ If your project already has a `.luarc.json`, `nanos-lint` automatically merges i
 }
 ```
 
-To scaffold a portable `.luarc.json` with vendored type annotations in your project, run:
+To scaffold a `.luarc.json` configuration in your project:
 
 ```bash
 npx nanos-lint init
@@ -231,6 +233,24 @@ npx nanos-lint init
 npx nanos-lint init --force
 ```
 
+By default `init` writes no annotations reference at all: `workspace.library` stays empty and
+`nanos-lint check` injects the managed cache path into its own temporary merged configuration at
+runtime, so a later cache update is picked up without touching repository files. Editors that read
+`.luarc.json` directly need a pinned copy, which is always an explicit opt-in:
+
+```bash
+# Initialize with annotations vendored into .nanos-lint/ and pinned in workspace.library
+npx nanos-lint init --vendor
+
+# Or copy the cached annotations to a custom file, or to any target that does not end in
+# ".lua" (treated as a directory). Copying alone does not pin anything: add the resulting
+# path to workspace.library yourself.
+npx nanos-lint copy-annotations
+npx nanos-lint copy-annotations ./types
+```
+
+`copy-annotations` refuses to overwrite an existing file unless `--force` is passed.
+
 ### Realm Mapping (`nanos.realms`)
 
 nanos world runs two isolated Lua VMs: the server executes `Server/**` + `Shared/**`, the client executes `Client/**` + `Shared/**`. `nanos-lint` mirrors that split and lets you describe a non-standard layout in `.luarc.json`:
@@ -369,7 +389,7 @@ npm run check:all
 npm run format:check    # Prettier code formatting (auto-fix via npm run format:fix)
 npm run lint            # ESLint
 npm run lint:deps       # Dependency architecture & license checks (dependency-cruiser)
-npm run lint:comments   # Comment density limit (<= 15%)
+npm run lint:comments   # Comment density limit (<= 10%)
 npm run lint:docstrings # Docstring coverage (>= 90% top-level/exported function coverage per file in src/)
 npm run typecheck       # TypeScript typecheck
 npm run build           # Build distribution bundle

package/action.yml

@@ -172,5 +172,5 @@ runs:
         else
           # Exact version: a range could run a different release than the pinned
           # tag. Bump together with "version" in package.json.
-          npx --yes nanos-lint@3.2.0 "${ARGS[@]}"
+          npx --yes nanos-lint@3.3.0 "${ARGS[@]}"
         fi

package/dist/{cli-CeNxOiST.js → cli-CsIAHyRZ.js}

@@ -1464,20 +1464,23 @@ function resolveRealmMappings(userConfig) {
 function initWorkspace(workspacePath, options) {
 	const targetFile = path.join(workspacePath, ".luarc.json");
 	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.");
+	if (options?.annotationsPath && !options.vendor) throw new ConfigError("--annotations requires --vendor: nanos-lint init does not pin or vendor annotations.lua by default.", "ERR_ANNOTATIONS_WITHOUT_VENDOR", "Run 'nanos-lint init --vendor --annotations <path>' (or pass vendor: true), or omit the custom path to use the managed annotations cache.");
 	const template = loadConfigFile(getDefaultTemplatePath());
-	const sourceAnnotations = options?.annotationsPath || getDefaultAnnotationsPath();
-	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");
-	fs.copyFileSync(sourceAnnotations, targetAnnotations);
-	template.workspace = template.workspace ?? {};
-	template.workspace.library = [".nanos-lint/annotations.lua"];
-	const existingIgnore = template.workspace.ignoreDir ?? [];
-	if (!existingIgnore.includes(".nanos-lint")) template.workspace.ignoreDir = [".nanos-lint", ...existingIgnore];
-	template.files = template.files ?? {};
-	const existingExclude = template.files.exclude ?? [];
-	if (!existingExclude.includes(".nanos-lint/**")) template.files.exclude = [".nanos-lint/**", ...existingExclude];
+	if (options?.vendor) {
+		const sourceAnnotations = options.annotationsPath || getDefaultAnnotationsPath();
+		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");
+		fs.copyFileSync(sourceAnnotations, targetAnnotations);
+		template.workspace = template.workspace ?? {};
+		template.workspace.library = [".nanos-lint/annotations.lua"];
+		const existingIgnore = template.workspace.ignoreDir ?? [];
+		if (!existingIgnore.includes(".nanos-lint")) template.workspace.ignoreDir = [".nanos-lint", ...existingIgnore];
+		template.files = template.files ?? {};
+		const existingExclude = template.files.exclude ?? [];
+		if (!existingExclude.includes(".nanos-lint/**")) template.files.exclude = [".nanos-lint/**", ...existingExclude];
+	}
 	fs.writeFileSync(targetFile, JSON.stringify(template, null, 2), "utf-8");
 	return targetFile;
 }
@@ -6368,6 +6371,13 @@ async function validateArchiveMembers(archivePath) {
 * user-supplied `LUALS_BIN` may legitimately be a small wrapper script.
 */
 const MIN_DOWNLOADED_BINARY_SIZE_BYTES = 1e5;
+/** Propagates blocked LuaLS execution or cache access without triggering repair. */
+function rethrowLuaLSPermissionError(err, targetPath, operation = "access") {
+	if (err instanceof LuaLSError && (err.code === "ERR_LUALS_EXECUTION_DENIED" || err.code === "ERR_LUALS_CACHE_PERMISSION")) throw err;
+	const code = err?.code;
+	if (code !== "EPERM" && code !== "EACCES") return;
+	throw new LuaLSError(`Cannot ${operation} LuaLS ${operation === "execute" ? "binary" : "cache path"} '${targetPath}': ${code}: ${err instanceof Error ? err.message : String(err)}`, operation === "execute" ? "ERR_LUALS_EXECUTION_DENIED" : "ERR_LUALS_CACHE_PERMISSION", operation === "execute" ? "Run nanos-lint in an environment that permits LuaLS execution and check the binary's execute permissions and sandbox policy. The existing cache has been preserved." : "Allow access to the LuaLS cache directory or use a writable cache directory.", { cause: err });
+}
 /**
 * Runs `binaryPath --version` and checks that it reports a LuaLS version.
 * Shared by every binary validation path; the size heuristic stays separate
@@ -6382,6 +6392,7 @@ function reportsLuaLSVersion(binaryPath) {
 		});
 		return /^\d+\.\d+\.\d+/.test(output.trim());
 	} catch (err) {
+		rethrowLuaLSPermissionError(err, binaryPath, "execute");
 		logger.debug(`[luals] Binary validation check failed for ${binaryPath}: ${err instanceof Error ? err.message : String(err)}`);
 		return false;
 	}
@@ -6397,6 +6408,7 @@ function isBinaryValid(binaryPath) {
 		if (!stats.isFile() || stats.size < 1e5) return false;
 		return reportsLuaLSVersion(binaryPath);
 	} catch (err) {
+		rethrowLuaLSPermissionError(err, binaryPath);
 		logger.debug(`[luals] Binary validation check failed for ${binaryPath}: ${err instanceof Error ? err.message : String(err)}`);
 		return false;
 	}
@@ -6410,6 +6422,7 @@ function isBinaryRunnable(binaryPath) {
 	try {
 		if (!fs.statSync(binaryPath).isFile()) return false;
 	} catch (err) {
+		rethrowLuaLSPermissionError(err, binaryPath);
 		logger.debug(`[luals] Binary validation check failed for ${binaryPath}: ${err instanceof Error ? err.message : String(err)}`);
 		return false;
 	}
@@ -6434,6 +6447,7 @@ function assertValidLuaLSBinary(binaryPath, source) {
 	try {
 		stats = fs.statSync(binaryPath);
 	} catch (err) {
+		rethrowLuaLSPermissionError(err, binaryPath);
 		throw new LuaLSError(`${source} points to '${binaryPath}', which does not exist or cannot be read: ${err instanceof Error ? err.message : String(err)}`, "ERR_LUALS_BIN_INVALID", `Set ${source} to the full path of a lua-language-server executable, or leave it unset so nanos-lint resolves LuaLS automatically.`, { cause: err });
 	}
 	if (!stats.isFile()) throw new LuaLSError(`${source} points to '${binaryPath}', which is not a regular file (a directory or special file was found).`, "ERR_LUALS_BIN_INVALID", `Point ${source} at the lua-language-server executable itself, or leave it unset so nanos-lint resolves LuaLS automatically.`);
@@ -6550,11 +6564,13 @@ function listCachedLuaLSVersions(baseCacheDir = getBaseLuaLSCacheDir()) {
 			if (fs.existsSync(marker) && fs.existsSync(bin)) try {
 				if (fs.readFileSync(marker, "utf-8").trim() === version && isBinaryValid(bin)) versions.push(version);
 			} catch (err) {
+				rethrowLuaLSPermissionError(err, bin);
 				logger.debug(`[luals] Error validating cached version ${version}: ${err instanceof Error ? err.message : String(err)}`);
 			}
 		}
 		return versions;
 	} catch (err) {
+		rethrowLuaLSPermissionError(err, baseCacheDir);
 		logger.debug(`[luals] Failed to list cached LuaLS versions: ${err instanceof Error ? err.message : String(err)}`);
 		return [];
 	}
@@ -6604,6 +6620,7 @@ function findExistingLuaLSDir(version, baseCacheDir = getBaseLuaLSCacheDir()) {
 	if (fs.existsSync(primaryMarker)) try {
 		if (fs.readFileSync(primaryMarker, "utf-8").trim() === version && isBinaryValid(primaryBin)) return primaryCache;
 	} catch (err) {
+		rethrowLuaLSPermissionError(err, primaryMarker);
 		logger.debug(`[luals] Error checking primary LuaLS cache marker at ${primaryMarker}: ${err instanceof Error ? err.message : String(err)}`);
 	}
 	const pkgRoot = getPackageRoot();
@@ -6664,6 +6681,7 @@ function isCompleteLuaLSInstall(binaryPath, completeMarker, version) {
 	try {
 		return fs.readFileSync(completeMarker, "utf-8").trim() === version && isBinaryValid(binaryPath);
 	} catch (err) {
+		rethrowLuaLSPermissionError(err, completeMarker);
 		logger.debug(`[luals] Failed to read complete marker at ${completeMarker}: ${err instanceof Error ? err.message : String(err)}`);
 		return false;
 	}
@@ -6694,6 +6712,7 @@ async function downloadAndPromoteLuaLS(resolvedVersion, info, destDir, binaryPat
 		if (options?.reuseExisting !== false && fs.existsSync(binaryPath) && fs.existsSync(completeMarker)) try {
 			if (fs.readFileSync(completeMarker, "utf-8").trim() === resolvedVersion && isBinaryValid(binaryPath)) return binaryPath;
 		} catch (err) {
+			rethrowLuaLSPermissionError(err, completeMarker);
 			logger.debug(`[luals] Failed to read complete marker at ${completeMarker}: ${err instanceof Error ? err.message : String(err)}`);
 		}
 		try {
@@ -6702,6 +6721,7 @@ async function downloadAndPromoteLuaLS(resolvedVersion, info, destDir, binaryPat
 				force: true
 			});
 		} catch (err) {
+			rethrowLuaLSPermissionError(err, destDir);
 			logger.warn(`[luals] Failed to remove stale or invalid cache dir ${destDir}: ${err instanceof Error ? err.message : String(err)}`);
 		}
 	}
@@ -7310,6 +7330,7 @@ async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
 					if (options?.reuseExisting !== false) return cachedPath;
 				}
 			} catch (err) {
+				rethrowLuaLSPermissionError(err, completeMarker);
 				logger.debug(`[luals] Failed to read complete marker at ${completeMarker}: ${err instanceof Error ? err.message : String(err)}`);
 			}
 			if (!isValid) {
@@ -7322,6 +7343,7 @@ async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
 					force: true
 				});
 			} catch (err) {
+				rethrowLuaLSPermissionError(err, cachedDir);
 				logger.warn(`[luals] Failed to remove corrupted cache directory ${cachedDir}: ${err instanceof Error ? err.message : String(err)}`);
 			}
 		}
@@ -7331,11 +7353,13 @@ async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
 			const found = stdout.trim().split(/\r?\n/)[0];
 			if (found && fs.existsSync(found) && isBinaryValid(found)) return found;
 		} catch (err) {
+			rethrowLuaLSPermissionError(err, "lua-language-server", "execute");
 			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) {
+			rethrowLuaLSPermissionError(err, cachedDir);
 			if (wasCorrupted) {
 				const isOffline = isOfflineError(err);
 				const reason = isOffline ? "while offline" : err instanceof Error ? err.message : String(err);
@@ -7397,12 +7421,14 @@ async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
 		const found = stdout.trim().split(/\r?\n/)[0];
 		if (found && fs.existsSync(found) && isBinaryValid(found)) return found;
 	} catch (err) {
+		rethrowLuaLSPermissionError(err, "lua-language-server", "execute");
 		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) {
+		rethrowLuaLSPermissionError(err, targetCacheDir);
 		if (wasCorrupted) {
 			const isOffline = isOfflineError(err);
 			const reason = isOffline ? "while offline" : err instanceof Error ? err.message : String(err);
@@ -11338,6 +11364,22 @@ async function resolveAnnotations(options = {}) {
 		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 });
 	}
 }
+const DEFAULT_COPY_TARGET = `.nanos-lint/${ANNOTATIONS_FILENAME}`;
+/**
+* Copies nanos world annotations.lua definitions into a target file or directory.
+* A target counts as a directory when it ends with a separator, already is a directory,
+* or does not end in `.lua` (case-insensitively).
+*/
+async function copyAnnotations(targetPath = DEFAULT_COPY_TARGET, options = {}) {
+	let resolvedTarget = path.resolve(targetPath);
+	if (targetPath.endsWith("/") || targetPath.endsWith("\\") || fs.existsSync(resolvedTarget) && fs.statSync(resolvedTarget).isDirectory() || path.extname(resolvedTarget).toLowerCase() !== ".lua") resolvedTarget = path.join(resolvedTarget, ANNOTATIONS_FILENAME);
+	if (fs.existsSync(resolvedTarget) && !options.force) throw new AnnotationsError(`Target annotations file already exists: ${resolvedTarget}. Use --force to overwrite.`, "ERR_ANNOTATIONS_EXISTS", "Pass --force to overwrite the existing annotations file.");
+	const sourcePath = options.annotationsPath ? validateCustomAnnotationsPath(options.annotationsPath, "custom") : await resolveAnnotations({ cacheDir: options.cacheDir });
+	const targetDir = path.dirname(resolvedTarget);
+	fs.mkdirSync(targetDir, { recursive: true });
+	fs.copyFileSync(sourcePath, resolvedTarget);
+	return resolvedTarget;
+}
 //#endregion
 //#region src/cache-status.ts
 /** Collects detailed status and disk usage information for LuaLS and annotations caches. */
@@ -11432,6 +11474,80 @@ function formatCacheStatusPretty(report) {
 	return lines.join("\n");
 }
 //#endregion
+//#region src/output.ts
+/** Writes command results to stdout unless the log level is `silent`. */
+function writeOutput(message) {
+	if (logger.isOutputEnabled()) console.log(message);
+}
+//#endregion
+//#region src/cli-check.ts
+/** Executes the check command on target paths with specified options. */
+async function executeCheckCommand(targetPaths = ["."], opts, setExitCode) {
+	if (opts.logLevel && isValidLogLevel(opts.logLevel)) logger.setLevel(opts.logLevel);
+	const { rootPath, targetPaths: canonicalTargets } = resolveCheckTargets(targetPaths && targetPaths.length > 0 ? targetPaths : ["."]);
+	const format = opts.github ? "github" : opts.format || (process.env.GITHUB_ACTIONS ? "github" : "pretty");
+	if (format === "json") {
+		setProgressMode("off");
+		logger.setDiagnosticStream("stderr");
+	}
+	const checkOptions = {
+		path: rootPath,
+		paths: canonicalTargets,
+		configpath: opts.config,
+		checklevel: opts.checklevel,
+		format,
+		lualsVersion: opts.lualsVersion,
+		failOnError: opts.fail !== false,
+		ignore: opts.ignore,
+		deps: opts.dep
+	};
+	if (opts.config) {
+		const resolvedConfig = path.resolve(opts.config);
+		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 });
+	const userConfig = loadUserConfig(rootPath, checkOptions.configpath);
+	const realmPlan = planRealmCheck({
+		targetPath: rootPath,
+		userConfig,
+		selection: opts.realm ?? "all",
+		annotationsPath,
+		customConfigPath: checkOptions.configpath,
+		ignore: checkOptions.ignore,
+		targetPaths: canonicalTargets,
+		cliDeps: checkOptions.deps
+	});
+	let result;
+	if (realmPlan) try {
+		result = await runRealmAwareCheck(realmPlan, rootPath, checkOptions);
+	} finally {
+		realmPlan.cleanup();
+	}
+	else {
+		const resolvedDeps = resolvePackageDependencies(rootPath, userConfig, checkOptions.deps);
+		const unrequestedExclusions = computeUnrequestedExclusions(rootPath, canonicalTargets);
+		const resolved = resolveWorkspaceConfig(rootPath, checkOptions.configpath, {
+			ignore: checkOptions.ignore,
+			annotationsPath,
+			dependencyLibraries: resolvedDeps.all,
+			unrequestedExclusions
+		});
+		try {
+			result = await runLuaLSCheck(rootPath, resolved.configPath, checkOptions);
+		} finally {
+			if (resolved.isTemp && fs.existsSync(resolved.configPath)) try {
+				fs.unlinkSync(resolved.configPath);
+			} 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) writeOutput(output);
+	if (!result.passed && checkOptions.failOnError) setExitCode(1);
+	else setExitCode(0);
+}
+//#endregion
 //#region src/cli.ts
 /** Retrieves the formatted package name and version string from package.json. */
 function getVersionString() {
@@ -11443,10 +11559,6 @@ function getVersionString() {
 		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);
-}
 /** Accumulates repeatable --ignore pattern arguments, splitting by comma and newline. */
 function collectIgnorePatterns(val, prev) {
 	const parts = val.split(/[\r\n,]+/).map((s) => s.trim()).filter(Boolean);
@@ -11492,75 +11604,22 @@ function createProgram(options) {
 		"server",
 		"shared"
 	]).default("all")).action(async (targetPaths = ["."], opts) => {
-		if (opts.logLevel && isValidLogLevel(opts.logLevel)) logger.setLevel(opts.logLevel);
-		const { rootPath, targetPaths: canonicalTargets } = resolveCheckTargets(targetPaths && targetPaths.length > 0 ? targetPaths : ["."]);
-		const format = opts.github ? "github" : opts.format || (process.env.GITHUB_ACTIONS ? "github" : "pretty");
-		if (format === "json") {
-			setProgressMode("off");
-			logger.setDiagnosticStream("stderr");
-		}
-		const checkOptions = {
-			path: rootPath,
-			paths: canonicalTargets,
-			configpath: opts.config,
-			checklevel: opts.checklevel,
-			format,
-			lualsVersion: opts.lualsVersion,
-			failOnError: opts.fail !== false,
-			ignore: opts.ignore,
-			deps: opts.dep
-		};
-		if (opts.config) {
-			const resolvedConfig = path.resolve(opts.config);
-			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 });
-		const userConfig = loadUserConfig(rootPath, checkOptions.configpath);
-		const realmPlan = planRealmCheck({
-			targetPath: rootPath,
-			userConfig,
-			selection: opts.realm ?? "all",
-			annotationsPath,
-			customConfigPath: checkOptions.configpath,
-			ignore: checkOptions.ignore,
-			targetPaths: canonicalTargets,
-			cliDeps: checkOptions.deps
-		});
-		let result;
-		if (realmPlan) try {
-			result = await runRealmAwareCheck(realmPlan, rootPath, checkOptions);
-		} finally {
-			realmPlan.cleanup();
-		}
-		else {
-			const resolvedDeps = resolvePackageDependencies(rootPath, userConfig, checkOptions.deps);
-			const unrequestedExclusions = computeUnrequestedExclusions(rootPath, canonicalTargets);
-			const resolved = resolveWorkspaceConfig(rootPath, checkOptions.configpath, {
-				ignore: checkOptions.ignore,
-				annotationsPath,
-				dependencyLibraries: resolvedDeps.all,
-				unrequestedExclusions
-			});
-			try {
-				result = await runLuaLSCheck(rootPath, resolved.configPath, checkOptions);
-			} finally {
-				if (resolved.isTemp && fs.existsSync(resolved.configPath)) try {
-					fs.unlinkSync(resolved.configPath);
-				} 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) writeOutput(output);
-		if (!result.passed && checkOptions.failOnError) setExitCode(1);
-		else setExitCode(0);
+		await executeCheckCommand(targetPaths, opts, setExitCode);
 	});
-	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 });
+	program.command("init [path]").description("Scaffold a .luarc.json configuration in the workspace").option("-f, --force", "Overwrite existing .luarc.json configuration").option("--vendor", "Vendor annotations.lua into .nanos-lint/ inside workspace for portable standalone editor setup").option("--annotations <path>", "Path to custom annotations.lua file (requires --vendor)").action(async (targetPath = ".", opts) => {
+		const shouldVendor = Boolean(opts.vendor);
+		const annotationsPath = shouldVendor ? await resolveAnnotations({ customPath: opts.annotations }) : opts.annotations;
 		writeOutput(`[init] Initialized nanos world LuaLS configuration: ${initWorkspace(path.resolve(targetPath), {
 			force: opts.force,
-			annotationsPath
+			annotationsPath,
+			vendor: shouldVendor
+		})}`);
+		setExitCode(0);
+	});
+	program.command("copy-annotations [destination]").alias("export-annotations").description("Copy cached nanos world annotations.lua definitions into a target file or directory (targets not ending in .lua are treated as directories)").option("-f, --force", "Overwrite existing annotations file").option("--annotations <path>", "Path to custom annotations.lua source file").action(async (destination, opts) => {
+		writeOutput(`[copy-annotations] Copied nanos world annotations to: ${await copyAnnotations(destination, {
+			force: opts.force,
+			annotationsPath: opts.annotations
 		})}`);
 		setExitCode(0);
 	});
@@ -11626,6 +11685,7 @@ Examples:
   $ npx nanos-lint check . --realm server
   $ npx nanos-lint check Shared/ Server/ --realm server
   $ npx nanos-lint init
+  $ npx nanos-lint copy-annotations
   $ npx nanos-lint clean-cache
 `);
 	return program;
@@ -11706,6 +11766,6 @@ if (isDirectExecution()) runCLI().then((code) => {
 	process.exit(1);
 });
 //#endregion
-export { DOWNLOAD_TIMEOUT_MS as $, getDefaultAnnotationsPath as $t, formatProblemSummary as A, DEFAULT_LUALS_VERSION as At, resolvePackageDependencies as B, PROGRESS_MILESTONES as Bt, getCachedAnnotationsFilePath as C, DEFAULT_LOG_LEVEL as Cn, isBinaryRunnable as Ct, updateLastCheckedDate as D, isValidLogLevel as Dn, parseTarTvSize as Dt, readAnnotationsMetadata as E, Logger as En, isZipArchive as Et, shouldEnableColor as F, sanitizeLuaLSVersion as Ft, computeUnrequestedExclusions as G, formatTransferSummary as Gt, runLuaLSCheck as H, SPINNER_FRAMES as Ht, collectRealmFiles as I, ALLOWED_DOWNLOAD_DOMAINS as It, findProjectRoot as J, restoreTerminal as Jt, filterReportByTargetPaths as K, getProgressMode as Kt, planRealmCheck as L, isAllowedDownloadUrl as Lt, formatSeverityBadge as M, fetchLatestLuaLSVersionFromGitHub as Mt, getColors as N, resolveLatestLuaLSVersion as Nt, formatGitHubAnnotations as O, logger as On, validateArchiveMembers as Ot, pluralize as P, resolveLuaLSVersion as Pt, resolveCheckTargets as Q, buildWorkspaceConfig as Qt, runRealmAwareCheck as R, deriveRealmAnnotationFiles as Rt, getAnnotationsMetadataFilePath as S, fileUriToPath as Sn, inspectZipMembers as St, isAnnotationsValid as T, LOG_LEVEL_PRIORITY as Tn, isGzipArchive as Tt, countCheckedFiles as U, createProgressBar as Ut, resolveLuaLSBinary as V, PROGRESS_THROTTLE_MS as Vt, listCheckedFiles as W, createSpinner as Wt, isFilesystemRoot as X, DEFAULT_REALM_MAPPINGS as Xt, getCanonicalPath as Y, setProgressMode as Yt, matchesTargetPaths as Z, VALID_LUALS_DIAGNOSTIC_CODES as Zt, MAX_ANNOTATIONS_SIZE_BYTES as _, NanosLintError as _n, MAX_DECOMPRESSED_SIZE_BYTES as _t, formatCacheStatusPretty as a, loadUserConfig as an, LUALS_METADATA_FILENAME as at, MIN_ANNOTATIONS_SIZE_BYTES as b, getDirectorySize as bn, escapePowerShellSingleQuote as bt, DOCGEN_BRANCH as c, resolveRealmMappings as cn, getBaseLuaLSCacheDir as ct, RAW_ANNOTATIONS_URL as d, stripTrailingSlashes as dn, getLuaLSMetadataPath as dt, getDefaultTemplatePath as en, MAX_ARCHIVE_SIZE_BYTES as et, downloadAndCacheAnnotations as f, writeTempConfig as fn, listCachedLuaLSVersionDirs as ft, ANNOTATIONS_FILENAME as g, LuaLSError as gn, MAX_ARCHIVE_MEMBER_COUNT as gt, getRawAnnotationsUrl as h, ConfigError as hn, writeLuaLSMetadata as ht, runCLI as i, loadConfigFile as in, trackDownloadProgress as it, formatReport as j, FALLBACK_LUALS_VERSION as jt, formatPretty as k, parseLogLevel as kn, getPlatformInfo as kt, DOCGEN_REPO as l, resolveWorkspaceConfig as ln, getCacheDir as lt, fetchRawAnnotationsContent as m, CacheError as mn, readLuaLSMetadata as mt, createProgram as n, getPackageRoot as nn, downloadAndExtractLuaLS as nt, getCacheStatus as o, mergeConfigs as on, cleanupOldCachedLuaLSVersions as ot, fetchLatestCommitId as p, AnnotationsError as pn, listCachedLuaLSVersions as pt, findCommonAncestorDirectory as q, isProgressInteractive as qt, isDirectExecution as r, initWorkspace as rn, limitDownloadStream as rt, resolveAnnotations as s, parseJsonc as sn, findExistingLuaLSDir as st, collectIgnorePatterns as t, getDefinitionsDir as tn, computeFileSha256 as tt, GITHUB_COMMITS_API as u, stripJsonComments as un, getIsoWeek as ut, MAX_COMMIT_JSON_SIZE_BYTES as v, cleanCache as vn, MIN_DOWNLOADED_BINARY_SIZE_BYTES as vt, getTodayDateString as w, LOG_LEVELS as wn, isBinaryValid as wt, getAnnotationsCacheDir as x, systemPaths as xn, getTarBinary as xt, METADATA_FILENAME as y, formatBytes as yn, assertValidLuaLSBinary as yt, collectDeps as z, splitAnnotationsByRealm as zt };
+export { resolveCheckTargets as $, VALID_LUALS_DIAGNOSTIC_CODES as $t, formatPretty as A, logger as An, validateArchiveMembers as At, collectDeps as B, deriveRealmAnnotationFiles as Bt, getAnnotationsMetadataFilePath as C, systemPaths as Cn, inspectZipMembers as Ct, readAnnotationsMetadata as D, LOG_LEVEL_PRIORITY as Dn, isZipArchive as Dt, isAnnotationsValid as E, LOG_LEVELS as En, isGzipArchive as Et, pluralize as F, resolveLatestLuaLSVersion as Ft, listCheckedFiles as G, createProgressBar as Gt, resolveLuaLSBinary as H, PROGRESS_MILESTONES as Ht, shouldEnableColor as I, resolveLuaLSVersion as It, findCommonAncestorDirectory as J, getProgressMode as Jt, computeUnrequestedExclusions as K, createSpinner as Kt, collectRealmFiles as L, sanitizeLuaLSVersion as Lt, formatReport as M, DEFAULT_LUALS_VERSION as Mt, formatSeverityBadge as N, FALLBACK_LUALS_VERSION as Nt, updateLastCheckedDate as O, Logger as On, parseTarTvSize as Ot, getColors as P, fetchLatestLuaLSVersionFromGitHub as Pt, matchesTargetPaths as Q, DEFAULT_REALM_MAPPINGS as Qt, planRealmCheck as R, ALLOWED_DOWNLOAD_DOMAINS as Rt, getAnnotationsCacheDir as S, getDirectorySize as Sn, getTarBinary as St, getTodayDateString as T, DEFAULT_LOG_LEVEL as Tn, isBinaryValid as Tt, runLuaLSCheck as U, PROGRESS_THROTTLE_MS as Ut, resolvePackageDependencies as V, splitAnnotationsByRealm as Vt, countCheckedFiles as W, SPINNER_FRAMES as Wt, getCanonicalPath as X, restoreTerminal as Xt, findProjectRoot as Y, isProgressInteractive as Yt, isFilesystemRoot as Z, setProgressMode as Zt, ANNOTATIONS_FILENAME as _, ConfigError as _n, MAX_ARCHIVE_MEMBER_COUNT as _t, formatCacheStatusPretty as a, initWorkspace as an, trackDownloadProgress as at, METADATA_FILENAME as b, cleanCache as bn, assertValidLuaLSBinary as bt, resolveAnnotations as c, mergeConfigs as cn, findExistingLuaLSDir as ct, GITHUB_COMMITS_API as d, resolveWorkspaceConfig as dn, getIsoWeek as dt, buildWorkspaceConfig as en, DOWNLOAD_TIMEOUT_MS as et, RAW_ANNOTATIONS_URL as f, stripJsonComments as fn, getLuaLSMetadataPath as ft, getRawAnnotationsUrl as g, CacheError as gn, writeLuaLSMetadata as gt, fetchRawAnnotationsContent as h, AnnotationsError as hn, readLuaLSMetadata as ht, runCLI as i, getPackageRoot as in, limitDownloadStream as it, formatProblemSummary as j, parseLogLevel as jn, getPlatformInfo as jt, formatGitHubAnnotations as k, isValidLogLevel as kn, rethrowLuaLSPermissionError as kt, DOCGEN_BRANCH as l, parseJsonc as ln, getBaseLuaLSCacheDir as lt, fetchLatestCommitId as m, writeTempConfig as mn, listCachedLuaLSVersions as mt, createProgram as n, getDefaultTemplatePath as nn, computeFileSha256 as nt, getCacheStatus as o, loadConfigFile as on, LUALS_METADATA_FILENAME as ot, downloadAndCacheAnnotations as p, stripTrailingSlashes as pn, listCachedLuaLSVersionDirs as pt, filterReportByTargetPaths as q, formatTransferSummary as qt, isDirectExecution as r, getDefinitionsDir as rn, downloadAndExtractLuaLS as rt, copyAnnotations as s, loadUserConfig as sn, cleanupOldCachedLuaLSVersions as st, collectIgnorePatterns as t, getDefaultAnnotationsPath as tn, MAX_ARCHIVE_SIZE_BYTES as tt, DOCGEN_REPO as u, resolveRealmMappings as un, getCacheDir as ut, MAX_ANNOTATIONS_SIZE_BYTES as v, LuaLSError as vn, MAX_DECOMPRESSED_SIZE_BYTES as vt, getCachedAnnotationsFilePath as w, fileUriToPath as wn, isBinaryRunnable as wt, MIN_ANNOTATIONS_SIZE_BYTES as x, formatBytes as xn, escapePowerShellSingleQuote as xt, MAX_COMMIT_JSON_SIZE_BYTES as y, NanosLintError as yn, MIN_DOWNLOADED_BINARY_SIZE_BYTES as yt, runRealmAwareCheck as z, isAllowedDownloadUrl as zt };
 
-//# sourceMappingURL=cli-CeNxOiST.js.map
+//# sourceMappingURL=cli-CsIAHyRZ.js.map