nanos-lint 3.2.1 → 3.4.0

package/dist/{cli-I16SeKRK.js → cli-DN7ZhC9e.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.");
-	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?.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(path.resolve(options?.templatePath ?? getDefaultTemplatePath()));
+	if (!template || typeof template !== "object" || Array.isArray(template)) throw new ConfigError("Init template must contain a configuration object.", "ERR_CONFIG_PARSE");
+	template.nanos ??= {};
+	template.nanos.realms ??= Object.fromEntries(DEFAULT_REALM_MAPPINGS.map(({ pattern, realm }) => [pattern, realm]));
+	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 targetAnnotations = path.join(workspacePath, ".nanos-lint", "annotations.lua");
+		fs.mkdirSync(path.dirname(targetAnnotations), { recursive: true });
+		fs.copyFileSync(sourceAnnotations, targetAnnotations);
+		template.workspace = template.workspace ?? {};
+		template.workspace.library = [.../* @__PURE__ */ new Set([...template.workspace.library ?? [], ".nanos-lint/annotations.lua"])];
+		template.workspace.ignoreDir = [.../* @__PURE__ */ new Set([".nanos-lint", ...template.workspace.ignoreDir ?? []])];
+		template.files = template.files ?? {};
+		template.files.exclude = [.../* @__PURE__ */ new Set([".nanos-lint/**", ...template.files.exclude ?? []])];
+	}
 	fs.writeFileSync(targetFile, JSON.stringify(template, null, 2), "utf-8");
 	return targetFile;
 }
@@ -7132,6 +7135,40 @@ function resolveCheckTargets(rawPaths) {
 	};
 }
 //#endregion
+//#region src/luals/offline.ts
+/** Validates an explicit local executable and checks a requested version against its output. */
+function validateOfflineBinary(binary, version) {
+	const resolved = assertValidLuaLSBinary(binary, "offline local binary");
+	if (version !== "latest") {
+		if (!execFileSync(resolved, ["--version"], {
+			encoding: "utf-8",
+			timeout: 5e3
+		}).split(/\s+/).some((part) => sanitizeLuaLSVersion(part) === version)) throw new LuaLSError(`Offline LuaLS binary ${resolved} does not match requested version ${version}.`, "ERR_LUALS_OFFLINE", `Run 'nanos-lint warmup --luals-version ${version}' online or set LUALS_BIN to a matching binary.`);
+	}
+	return resolved;
+}
+/** Resolves local LuaLS assets without changing cache entries or discovering remote releases. */
+function resolveOfflineLuaLS(version, cacheDir = getBaseLuaLSCacheDir()) {
+	const requested = version === "latest" ? version : sanitizeLuaLSVersion(version);
+	if (!requested) throw new LuaLSError(`Invalid LuaLS version: "${version}".`, "ERR_LUALS_INVALID_VERSION");
+	if (process.env.LUALS_BIN) return validateOfflineBinary(process.env.LUALS_BIN, requested);
+	const versions = listCachedLuaLSVersions(cacheDir).sort((a, b) => b.localeCompare(a, "en", { numeric: true }));
+	const selected = requested === "latest" ? versions[0] : versions.find((v) => v === requested);
+	if (selected) {
+		logger.info(`[luals] Offline: using cached LuaLS ${selected}.`);
+		return path.join(getCacheDir(selected, cacheDir), getPlatformInfo(selected).binaryRelativePath);
+	}
+	const bundled = path.join(getPackageRoot(), getPlatformInfo(FALLBACK_LUALS_VERSION).binaryRelativePath);
+	if (fs.existsSync(bundled)) return validateOfflineBinary(bundled, requested);
+	try {
+		const found = execFileSync(process.platform === "win32" ? "where.exe" : "which", ["lua-language-server"], { encoding: "utf-8" }).trim().split(/\r?\n/)[0];
+		if (found) return validateOfflineBinary(found, requested);
+	} catch (err) {
+		rethrowLuaLSPermissionError(err, "lua-language-server", "execute");
+	}
+	throw new LuaLSError(`Offline: no usable local LuaLS binary for ${requested}.`, "ERR_LUALS_OFFLINE", `Run 'nanos-lint warmup${requested === "latest" ? "" : ` --luals-version ${requested}`}' online or set LUALS_BIN to a matching local executable.`);
+}
+//#endregion
 //#region src/luals/files.ts
 /** Directories skipped unless the workspace config overrides `workspace.ignoreDir`. */
 const DEFAULT_IGNORE_DIRS = [
@@ -7300,6 +7337,7 @@ function isOfflineError(err) {
 }
 /** Resolves the executable path of a LuaLS binary from env, bundle, cache, or network download. */
 async function resolveLuaLSBinary(version = DEFAULT_LUALS_VERSION, options) {
+	if (options?.offline) return resolveOfflineLuaLS(version, options.cacheDir);
 	if (process.env.LUALS_BIN) return assertValidLuaLSBinary(process.env.LUALS_BIN, "LUALS_BIN");
 	if (options?.reuseExisting !== false && (!version || version === "latest")) {
 		const defaultInfo = getPlatformInfo(FALLBACK_LUALS_VERSION);
@@ -7445,7 +7483,7 @@ async function runLuaLSCheck(targetPath, configPath, options) {
 		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 ? assertValidLuaLSBinary(options.lualsBin, "--luals-bin") : await resolveLuaLSBinary(options.lualsVersion);
+	const binary = options.lualsBin ? options.offline ? validateOfflineBinary(options.lualsBin, options.lualsVersion ?? "latest") : assertValidLuaLSBinary(options.lualsBin, "--luals-bin") : await resolveLuaLSBinary(options.lualsVersion, { offline: options.offline });
 	let checkDir = absoluteTarget;
 	let targetFileOnly = null;
 	if (fs.statSync(absoluteTarget).isFile()) {
@@ -7987,7 +8025,7 @@ function formatPretty(result, cwd = process.cwd(), useColor = shouldEnableColor(
 	const c = getColors(useColor);
 	const symCross = "✖  ";
 	const symCheck = "✔  ";
-	if (result.passed) {
+	if (result.passed && !result.baselineSummary) {
 		const fileStr = pluralize(result.totalFilesChecked ?? result.totalFiles, "file");
 		return `${c.green}${c.bold}${symCheck}Diagnosis completed, no problems found across ${fileStr}.${c.reset}`;
 	}
@@ -8003,6 +8041,7 @@ function formatPretty(result, cwd = process.cwd(), useColor = shouldEnableColor(
 			logger.debug(`Failed to read file snippet for ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
 		}
 		for (const d of diags) {
+			if (d.baseline) continue;
 			const line = d.range.start.line + 1;
 			const col = d.range.start.character + 1;
 			const badge = formatSeverityBadge(d.severity, useColor);
@@ -8028,8 +8067,10 @@ function formatPretty(result, cwd = process.cwd(), useColor = shouldEnableColor(
 		else if (d.severity === 2) warnings++;
 	}
 	lines.push("");
-	const summary = formatProblemSummary(result.totalProblems, errors, warnings, result.totalFiles);
-	lines.push(`${c.red}${c.bold}${symCross}${summary}${c.reset}`);
+	const counts = result.baselineSummary;
+	const summary = counts ? `Diagnosis complete: ${counts.new} new, ${counts.baselined} baselined, ${counts.total} total (${counts.stale} stale baseline entries).` : formatProblemSummary(result.totalProblems, errors, warnings, result.totalFiles);
+	const color = result.passed ? c.green : c.red;
+	lines.push(`${color}${c.bold}${result.passed ? symCheck : symCross}${summary}${c.reset}`);
 	return lines.join("\n");
 }
 /** Formats check diagnostics into GitHub Actions workflow annotation commands. */
@@ -8040,6 +8081,7 @@ function formatGitHubAnnotations(result, cwd = process.cwd()) {
 		const filePath = fileUriToPath(rawUri);
 		const escapedFile = (path.isAbsolute(filePath) ? path.relative(cwd, filePath).replace(/\\/g, "/") : filePath.replace(/\\/g, "/")).replace(/%/g, "%25").replace(/,/g, "%2C");
 		for (const d of diags) {
+			if (d.baseline) continue;
 			const line = d.range.start.line + 1;
 			const col = d.range.start.character + 1;
 			const endLine = d.range.end.line + 1;
@@ -11316,6 +11358,10 @@ async function resolveAnnotations(options = {}) {
 	if (fs.existsSync(bundled) && isAnnotationsValid(bundled)) return bundled;
 	const cacheDir = options.cacheDir ?? getAnnotationsCacheDir();
 	const cachedAnnotationsFile = path.join(cacheDir, ANNOTATIONS_FILENAME);
+	if (options.offline) {
+		if (isAnnotationsValid(cachedAnnotationsFile)) return cachedAnnotationsFile;
+		throw new AnnotationsError(`Offline: no usable local annotations.lua at ${cachedAnnotationsFile}.`, "ERR_ANNOTATIONS_OFFLINE", "Run 'nanos-lint warmup' online or specify --annotations <path>.");
+	}
 	const metadata = readAnnotationsMetadata(cacheDir);
 	const { dateStr } = getTodayDateString();
 	if (fs.existsSync(cachedAnnotationsFile) && !isAnnotationsValid(cachedAnnotationsFile)) {
@@ -11361,6 +11407,25 @@ 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,
+		offline: options.offline
+	});
+	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. */
@@ -11455,6 +11520,190 @@ 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/baseline.ts
+/** Builds a line-independent diagnostic identity relative to the checked workspace root. */
+function entryFor(root, uri, diagnostic) {
+	const file = fileUriToPath(uri);
+	return {
+		path: path.relative(root, path.isAbsolute(file) ? file : path.resolve(root, file)).replace(/\\/g, "/"),
+		code: diagnostic.code ?? "",
+		message: diagnostic.message.replace(/\s+/g, " ").trim(),
+		severity: diagnostic.severity,
+		count: 1
+	};
+}
+/** Serializes the fields defining a diagnostic identity, excluding occurrence count. */
+function keyFor(entry) {
+	return JSON.stringify([
+		entry.path,
+		entry.code,
+		entry.message,
+		entry.severity
+	]);
+}
+/** Records sorted diagnostic identities and multiplicities without source positions. */
+function createBaseline(result, root) {
+	const entries = /* @__PURE__ */ new Map();
+	for (const [uri, diagnostics] of Object.entries(result.diagnostics)) for (const diagnostic of diagnostics) {
+		const entry = entryFor(root, uri, diagnostic);
+		const key = keyFor(entry);
+		const previous = entries.get(key);
+		if (previous) previous.count++;
+		else entries.set(key, entry);
+	}
+	return {
+		version: 1,
+		entries: [...entries.values()].sort((a, b) => {
+			const left = keyFor(a);
+			const right = keyFor(b);
+			return left < right ? -1 : left > right ? 1 : 0;
+		})
+	};
+}
+/** Validates a persisted baseline and rejects ambiguous or incompatible entries. */
+function readBaseline(file) {
+	try {
+		const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+		if (parsed?.version !== 1 || !Array.isArray(parsed.entries)) throw new Error("Unsupported baseline schema (expected version 1).");
+		const keys = /* @__PURE__ */ new Set();
+		for (const entry of parsed.entries) {
+			if (!entry || typeof entry.path !== "string" || !entry.path || typeof entry.code !== "string" || typeof entry.message !== "string" || !Number.isInteger(entry.severity) || entry.severity < 1 || entry.severity > 4 || !Number.isSafeInteger(entry.count) || entry.count < 1) throw new Error("Invalid baseline diagnostic entry.");
+			const key = keyFor(entry);
+			if (keys.has(key)) throw new Error("Duplicate baseline diagnostic entry.");
+			keys.add(key);
+		}
+		return parsed;
+	} catch (cause) {
+		throw new ConfigError(`Cannot read diagnostic baseline ${file}: ${cause instanceof Error ? cause.message : String(cause)}`, "ERR_BASELINE_READ", "Regenerate with 'nanos-lint check <targets> --write-baseline <path>' using the same targets and options.", { cause });
+	}
+}
+/** Atomically writes a deterministic baseline, creating its parent directory if needed. */
+function writeBaseline(file, result, root) {
+	try {
+		writeAtomicFileSync(path.resolve(file), `${JSON.stringify(createBaseline(result, root), null, 2)}\n`);
+	} catch (cause) {
+		throw new ConfigError(`Cannot write diagnostic baseline ${file}: ${cause instanceof Error ? cause.message : String(cause)}`, "ERR_BASELINE_WRITE", "Choose a writable baseline path.", { cause });
+	}
+}
+/** Classifies each diagnostic against an occurrence budget and computes strict staleness. */
+function compareBaseline(result, baseline, root, strict = false) {
+	const remaining = new Map(baseline.entries.map((entry) => [keyFor(entry), entry.count]));
+	const diagnostics = {};
+	let baselined = 0;
+	let total = 0;
+	for (const [uri, items] of Object.entries(result.diagnostics)) diagnostics[uri] = [...items].sort((a, b) => a.range.start.line - b.range.start.line || a.range.start.character - b.range.start.character).map((diagnostic) => {
+		const key = keyFor(entryFor(root, uri, diagnostic));
+		const count = remaining.get(key) ?? 0;
+		const matched = count > 0;
+		if (matched) {
+			remaining.set(key, count - 1);
+			baselined++;
+		}
+		total++;
+		return {
+			...diagnostic,
+			baseline: matched
+		};
+	});
+	const stale = [...remaining.values()].reduce((sum, count) => sum + count, 0);
+	const newProblems = total - baselined;
+	return {
+		...result,
+		diagnostics,
+		passed: newProblems === 0 && (!strict || stale === 0),
+		baselineSummary: {
+			new: newProblems,
+			baselined,
+			total,
+			stale
+		}
+	};
+}
+//#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");
+	}
+	if (opts.baseline && opts.writeBaseline || opts.baselineStrict && !opts.baseline) throw new ConfigError("Use either --baseline or --write-baseline; --baseline-strict requires --baseline.", "ERR_BASELINE_OPTIONS");
+	const baseline = opts.baseline ? readBaseline(path.resolve(opts.baseline)) : void 0;
+	const checkOptions = {
+		offline: opts.offline,
+		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,
+		offline: opts.offline
+	});
+	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)}`);
+			}
+		}
+	}
+	if (opts.writeBaseline) {
+		writeBaseline(opts.writeBaseline, result, rootPath);
+		result = compareBaseline(result, createBaseline(result, rootPath), rootPath);
+	} else if (baseline) result = compareBaseline(result, baseline, rootPath, opts.baselineStrict);
+	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() {
@@ -11466,10 +11715,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);
@@ -11485,7 +11730,7 @@ function createProgram(options) {
 		"info",
 		"debug",
 		"silent"
-	]).default(DEFAULT_LOG_LEVEL)).option("--no-progress", "Disable the interactive download, extraction and realm derivation progress display").hook("preAction", (thisCommand, actionCommand) => {
+	]).default(DEFAULT_LOG_LEVEL)).option("--offline", "Use local dependencies only; never access the network").option("--no-progress", "Disable the interactive download, extraction and realm derivation progress display").hook("preAction", (thisCommand, actionCommand) => {
 		const target = actionCommand || thisCommand;
 		const opts = target.optsWithGlobals ? target.optsWithGlobals() : target.opts();
 		if (opts.logLevel && isValidLogLevel(opts.logLevel)) logger.setLevel(opts.logLevel);
@@ -11503,7 +11748,7 @@ function createProgram(options) {
 		"pretty",
 		"json",
 		"github"
-	])).option("-i, --ignore <pattern>", "Files or directories to ignore (supports glob patterns, repeatable)", collectIgnorePatterns).option("-d, --dep <path>", "Path to package dependency or Lua definition file (repeatable)", collectDeps).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").addOption(new Option("-l, --log-level <level>", "Logging level: error, warn, info, debug, silent").choices([
+	])).option("-i, --ignore <pattern>", "Files or directories to ignore (supports glob patterns, repeatable)", collectIgnorePatterns).option("-d, --dep <path>", "Path to package dependency or Lua definition file (repeatable)", collectDeps).option("--luals-version <ver>", `Version of LuaLS to use (default: ${DEFAULT_LUALS_VERSION})`, DEFAULT_LUALS_VERSION).option("--baseline <path>", "Report and fail only on diagnostics absent from a saved baseline").option("--write-baseline <path>", "Record current diagnostics as a baseline and exit successfully").option("--baseline-strict", "Also fail on stale baseline entries (requires --baseline)").option("--no-fail", "Do not exit with code 1 if diagnostics are found").addOption(new Option("-l, --log-level <level>", "Logging level: error, warn, info, debug, silent").choices([
 		"error",
 		"warn",
 		"info",
@@ -11514,91 +11759,48 @@ function createProgram(options) {
 		"client",
 		"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);
+	]).default("all")).action(async (targetPaths = ["."], opts, cmd) => {
+		opts.offline = cmd.optsWithGlobals().offline;
+		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("-t, --template <path>", "Custom JSONC .luarc.json scaffold template").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, cmd) => {
+		opts.offline = cmd.optsWithGlobals().offline;
+		const shouldVendor = Boolean(opts.vendor);
+		const annotationsPath = shouldVendor ? await resolveAnnotations({
+			customPath: opts.annotations,
+			offline: opts.offline
+		}) : opts.annotations;
 		writeOutput(`[init] Initialized nanos world LuaLS configuration: ${initWorkspace(path.resolve(targetPath), {
 			force: opts.force,
-			annotationsPath
+			annotationsPath,
+			vendor: shouldVendor,
+			templatePath: opts.template
+		})}`);
+		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, cmd) => {
+		writeOutput(`[copy-annotations] Copied nanos world annotations to: ${await copyAnnotations(destination, {
+			force: opts.force,
+			annotationsPath: opts.annotations,
+			offline: cmd.optsWithGlobals().offline
 		})}`);
 		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").action(async (opts) => {
-		writeOutput(`[warmup] LuaLS binary ready: ${await resolveLuaLSBinary(opts?.lualsVersion || "latest")}`);
-		const annotationsPath = await resolveAnnotations({ customPath: opts?.annotations });
+	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").action(async (opts, cmd) => {
+		writeOutput(`[warmup] LuaLS binary ready: ${await resolveLuaLSBinary(opts?.lualsVersion || "latest", { offline: cmd.optsWithGlobals().offline })}`);
+		const annotationsPath = await resolveAnnotations({
+			customPath: opts?.annotations,
+			offline: cmd.optsWithGlobals().offline
+		});
 		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) => {
+	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, cmd) => {
 		const ver = version || opts?.lualsVersion || "latest";
 		writeOutput(`[luals] Downloading LuaLS ${ver}...`);
-		writeOutput(`[luals] Ready at: ${await resolveLuaLSBinary(ver)}`);
+		writeOutput(`[luals] Ready at: ${await resolveLuaLSBinary(ver, { offline: cmd.optsWithGlobals().offline })}`);
 		setExitCode(0);
 	});
 	const handleCleanCache = () => {
@@ -11649,6 +11851,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;
@@ -11729,6 +11932,6 @@ if (isDirectExecution()) runCLI().then((code) => {
 	process.exit(1);
 });
 //#endregion
-export { DOWNLOAD_TIMEOUT_MS as $, buildWorkspaceConfig as $t, formatProblemSummary as A, parseLogLevel as An, getPlatformInfo as At, resolvePackageDependencies as B, splitAnnotationsByRealm as Bt, getCachedAnnotationsFilePath as C, fileUriToPath as Cn, isBinaryRunnable as Ct, updateLastCheckedDate as D, Logger as Dn, parseTarTvSize as Dt, readAnnotationsMetadata as E, LOG_LEVEL_PRIORITY as En, isZipArchive as Et, shouldEnableColor as F, resolveLuaLSVersion as Ft, computeUnrequestedExclusions as G, createSpinner as Gt, runLuaLSCheck as H, PROGRESS_THROTTLE_MS as Ht, collectRealmFiles as I, sanitizeLuaLSVersion as It, findProjectRoot as J, isProgressInteractive as Jt, filterReportByTargetPaths as K, formatTransferSummary as Kt, planRealmCheck as L, ALLOWED_DOWNLOAD_DOMAINS as Lt, formatSeverityBadge as M, FALLBACK_LUALS_VERSION as Mt, getColors as N, fetchLatestLuaLSVersionFromGitHub as Nt, formatGitHubAnnotations as O, isValidLogLevel as On, rethrowLuaLSPermissionError as Ot, pluralize as P, resolveLatestLuaLSVersion as Pt, resolveCheckTargets as Q, VALID_LUALS_DIAGNOSTIC_CODES as Qt, runRealmAwareCheck as R, isAllowedDownloadUrl as Rt, getAnnotationsMetadataFilePath as S, systemPaths as Sn, inspectZipMembers as St, isAnnotationsValid as T, LOG_LEVELS as Tn, isGzipArchive as Tt, countCheckedFiles as U, SPINNER_FRAMES as Ut, resolveLuaLSBinary as V, PROGRESS_MILESTONES as Vt, listCheckedFiles as W, createProgressBar as Wt, isFilesystemRoot as X, setProgressMode as Xt, getCanonicalPath as Y, restoreTerminal as Yt, matchesTargetPaths as Z, DEFAULT_REALM_MAPPINGS as Zt, MAX_ANNOTATIONS_SIZE_BYTES as _, LuaLSError as _n, MAX_DECOMPRESSED_SIZE_BYTES as _t, formatCacheStatusPretty as a, loadConfigFile as an, LUALS_METADATA_FILENAME as at, MIN_ANNOTATIONS_SIZE_BYTES as b, formatBytes as bn, escapePowerShellSingleQuote as bt, DOCGEN_BRANCH as c, parseJsonc as cn, getBaseLuaLSCacheDir as ct, RAW_ANNOTATIONS_URL as d, stripJsonComments as dn, getLuaLSMetadataPath as dt, getDefaultAnnotationsPath as en, MAX_ARCHIVE_SIZE_BYTES as et, downloadAndCacheAnnotations as f, stripTrailingSlashes as fn, listCachedLuaLSVersionDirs as ft, ANNOTATIONS_FILENAME as g, ConfigError as gn, MAX_ARCHIVE_MEMBER_COUNT as gt, getRawAnnotationsUrl as h, CacheError as hn, writeLuaLSMetadata as ht, runCLI as i, initWorkspace as in, trackDownloadProgress as it, formatReport as j, DEFAULT_LUALS_VERSION as jt, formatPretty as k, logger as kn, validateArchiveMembers as kt, DOCGEN_REPO as l, resolveRealmMappings as ln, getCacheDir as lt, fetchRawAnnotationsContent as m, AnnotationsError as mn, readLuaLSMetadata as mt, createProgram as n, getDefinitionsDir as nn, downloadAndExtractLuaLS as nt, getCacheStatus as o, loadUserConfig as on, cleanupOldCachedLuaLSVersions as ot, fetchLatestCommitId as p, writeTempConfig as pn, listCachedLuaLSVersions as pt, findCommonAncestorDirectory as q, getProgressMode as qt, isDirectExecution as r, getPackageRoot as rn, limitDownloadStream as rt, resolveAnnotations as s, mergeConfigs as sn, findExistingLuaLSDir as st, collectIgnorePatterns as t, getDefaultTemplatePath as tn, computeFileSha256 as tt, GITHUB_COMMITS_API as u, resolveWorkspaceConfig as un, getIsoWeek as ut, MAX_COMMIT_JSON_SIZE_BYTES as v, NanosLintError as vn, MIN_DOWNLOADED_BINARY_SIZE_BYTES as vt, getTodayDateString as w, DEFAULT_LOG_LEVEL as wn, isBinaryValid as wt, getAnnotationsCacheDir as x, getDirectorySize as xn, getTarBinary as xt, METADATA_FILENAME as y, cleanCache as yn, assertValidLuaLSBinary as yt, collectDeps as z, deriveRealmAnnotationFiles as zt };
+export { findProjectRoot as $, isProgressInteractive as $t, isAnnotationsValid as A, LOG_LEVELS as An, isGzipArchive as At, shouldEnableColor as B, resolveLuaLSVersion as Bt, MAX_COMMIT_JSON_SIZE_BYTES as C, NanosLintError as Cn, MIN_DOWNLOADED_BINARY_SIZE_BYTES as Ct, getAnnotationsMetadataFilePath as D, systemPaths as Dn, inspectZipMembers as Dt, getAnnotationsCacheDir as E, getDirectorySize as En, getTarBinary as Et, formatProblemSummary as F, parseLogLevel as Fn, getPlatformInfo as Ft, resolvePackageDependencies as G, splitAnnotationsByRealm as Gt, planRealmCheck as H, ALLOWED_DOWNLOAD_DOMAINS as Ht, formatReport as I, DEFAULT_LUALS_VERSION as It, countCheckedFiles as J, SPINNER_FRAMES as Jt, resolveLuaLSBinary as K, PROGRESS_MILESTONES as Kt, formatSeverityBadge as L, FALLBACK_LUALS_VERSION as Lt, updateLastCheckedDate as M, Logger as Mn, parseTarTvSize as Mt, formatGitHubAnnotations as N, isValidLogLevel as Nn, rethrowLuaLSPermissionError as Nt, getCachedAnnotationsFilePath as O, fileUriToPath as On, isBinaryRunnable as Ot, formatPretty as P, logger as Pn, validateArchiveMembers as Pt, findCommonAncestorDirectory as Q, getProgressMode as Qt, getColors as R, fetchLatestLuaLSVersionFromGitHub as Rt, MAX_ANNOTATIONS_SIZE_BYTES as S, LuaLSError as Sn, MAX_DECOMPRESSED_SIZE_BYTES as St, MIN_ANNOTATIONS_SIZE_BYTES as T, formatBytes as Tn, escapePowerShellSingleQuote as Tt, runRealmAwareCheck as U, isAllowedDownloadUrl as Ut, collectRealmFiles as V, sanitizeLuaLSVersion as Vt, collectDeps as W, deriveRealmAnnotationFiles as Wt, computeUnrequestedExclusions as X, createSpinner as Xt, listCheckedFiles as Y, createProgressBar as Yt, filterReportByTargetPaths as Z, formatTransferSummary as Zt, downloadAndCacheAnnotations as _, stripTrailingSlashes as _n, listCachedLuaLSVersionDirs as _t, compareBaseline as a, getDefaultAnnotationsPath as an, MAX_ARCHIVE_SIZE_BYTES as at, getRawAnnotationsUrl as b, CacheError as bn, writeLuaLSMetadata as bt, writeBaseline as c, getPackageRoot as cn, limitDownloadStream as ct, copyAnnotations as d, loadUserConfig as dn, cleanupOldCachedLuaLSVersions as dt, restoreTerminal as en, getCanonicalPath as et, resolveAnnotations as f, mergeConfigs as fn, findExistingLuaLSDir as ft, RAW_ANNOTATIONS_URL as g, stripJsonComments as gn, getLuaLSMetadataPath as gt, GITHUB_COMMITS_API as h, resolveWorkspaceConfig as hn, getIsoWeek as ht, runCLI as i, buildWorkspaceConfig as in, DOWNLOAD_TIMEOUT_MS as it, readAnnotationsMetadata as j, LOG_LEVEL_PRIORITY as jn, isZipArchive as jt, getTodayDateString as k, DEFAULT_LOG_LEVEL as kn, isBinaryValid as kt, formatCacheStatusPretty as l, initWorkspace as ln, trackDownloadProgress as lt, DOCGEN_REPO as m, resolveRealmMappings as mn, getCacheDir as mt, createProgram as n, DEFAULT_REALM_MAPPINGS as nn, matchesTargetPaths as nt, createBaseline as o, getDefaultTemplatePath as on, computeFileSha256 as ot, DOCGEN_BRANCH as p, parseJsonc as pn, getBaseLuaLSCacheDir as pt, runLuaLSCheck as q, PROGRESS_THROTTLE_MS as qt, isDirectExecution as r, VALID_LUALS_DIAGNOSTIC_CODES as rn, resolveCheckTargets as rt, readBaseline as s, getDefinitionsDir as sn, downloadAndExtractLuaLS as st, collectIgnorePatterns as t, setProgressMode as tn, isFilesystemRoot as tt, getCacheStatus as u, loadConfigFile as un, LUALS_METADATA_FILENAME as ut, fetchLatestCommitId as v, writeTempConfig as vn, listCachedLuaLSVersions as vt, METADATA_FILENAME as w, cleanCache as wn, assertValidLuaLSBinary as wt, ANNOTATIONS_FILENAME as x, ConfigError as xn, MAX_ARCHIVE_MEMBER_COUNT as xt, fetchRawAnnotationsContent as y, AnnotationsError as yn, readLuaLSMetadata as yt, pluralize as z, resolveLatestLuaLSVersion as zt };
 
-//# sourceMappingURL=cli-I16SeKRK.js.map
+//# sourceMappingURL=cli-DN7ZhC9e.js.map