nanos-lint 3.1.0 → 3.2.1

package/dist/{cli-Cb3wLBCr.js → cli-I16SeKRK.js}

@@ -41,6 +41,7 @@ function parseLogLevel(raw) {
 }
 var Logger = class {
 	level = DEFAULT_LOG_LEVEL;
+	diagnosticStream = "stdout";
 	constructor(initialLevel) {
 		if (initialLevel && isValidLogLevel(initialLevel)) this.level = initialLevel;
 		else {
@@ -56,6 +57,17 @@ var Logger = class {
 	getLevel() {
 		return this.level;
 	}
+	/**
+	* Selects the stream used by `info`/`debug`. Machine-readable formats switch this to
+	* `stderr`, so a report on stdout is never interleaved with diagnostic lines.
+	*/
+	setDiagnosticStream(stream) {
+		this.diagnosticStream = stream;
+	}
+	/** Returns the stream used by `info`/`debug`. */
+	getDiagnosticStream() {
+		return this.diagnosticStream;
+	}
 	/** Checks if a message at the specified level should be emitted. */
 	isEnabledFor(level) {
 		return LOG_LEVEL_PRIORITY[this.level] >= LOG_LEVEL_PRIORITY[level];
@@ -72,13 +84,22 @@ var Logger = class {
 	warn(...args) {
 		if (this.isEnabledFor("warn")) console.warn(...args);
 	}
-	/** Logs an informational message to stdout. */
+	/** Logs an informational message to stdout, or to stderr when stdout carries a report. */
 	info(...args) {
-		if (this.isEnabledFor("info")) console.log(...args);
+		if (this.isEnabledFor("info")) this.emitDiagnostic(args, "log");
 	}
-	/** Logs a debug-level diagnostic message to stdout. */
+	/** Logs a debug-level diagnostic message to stdout, or to stderr when stdout carries a report. */
 	debug(...args) {
-		if (this.isEnabledFor("debug")) console.debug(...args);
+		if (this.isEnabledFor("debug")) this.emitDiagnostic(args, "debug");
+	}
+	/** Writes an `info`/`debug` diagnostic on the configured stream. */
+	emitDiagnostic(args, stdoutMethod) {
+		if (this.diagnosticStream === "stderr") {
+			console.error(...args);
+			return;
+		}
+		if (stdoutMethod === "debug") console.debug(...args);
+		else console.log(...args);
 	}
 };
 const logger = new Logger();
@@ -5056,6 +5077,294 @@ async function writeAtomicFile(targetPath, data, options = {}) {
 	}
 }
 //#endregion
+//#region src/terminal-progress.ts
+/** Minimum delay between two terminal redraws (about ten frames per second). */
+const PROGRESS_THROTTLE_MS = 100;
+/** Braille frames cycled while an indeterminate operation runs. */
+const SPINNER_FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+/** Fractions of a transfer logged as milestones when no terminal can be redrawn. */
+const PROGRESS_MILESTONES = [
+	.25,
+	.5,
+	.75
+];
+const CURSOR_HIDE = "\x1B[?25l";
+const CURSOR_SHOW = "\x1B[?25h";
+const CLEAR_LINE = "\r\x1B[2K";
+const FRAME_TAIL = "  ";
+const DEFAULT_COLUMNS = 80;
+const MIN_BAR_WIDTH = 8;
+const MAX_BAR_WIDTH = 28;
+const TRUNCATION = "...";
+let progressMode = "auto";
+let cursorHidden = false;
+let guardsInstalled = false;
+let activeDynamicRenders = 0;
+/** Sets the redraw policy used by every progress display created afterwards. */
+function setProgressMode(mode) {
+	progressMode = mode;
+}
+/** Returns the current redraw policy. */
+function getProgressMode() {
+	return progressMode;
+}
+/** Returns whether an environment value is set to anything but an explicit false. */
+function isEnvFlagSet(value) {
+	if (value === void 0) return false;
+	const normalized = value.trim().toLowerCase();
+	return normalized !== "" && normalized !== "0" && normalized !== "false" && normalized !== "no" && normalized !== "off";
+}
+/**
+* Returns whether dynamic redrawing is allowed for the given environment and terminal.
+* Non-interactive environments get single-line milestones instead of carriage returns.
+*/
+function isProgressInteractive(env = process.env, isTTY = process.stderr.isTTY) {
+	if (progressMode === "off" || !logger.isOutputEnabled() || !isTTY) return false;
+	if ((env.TERM ?? "").trim().toLowerCase() === "dumb") return false;
+	return !(isEnvFlagSet(env.CI) || isEnvFlagSet(env.NO_COLOR) || isEnvFlagSet(env.NANOS_NO_PROGRESS));
+}
+/** Writes a control sequence straight to file descriptor 2, tolerating a closed stderr. */
+function writeToStderr(sequence) {
+	try {
+		fs.writeSync(2, sequence);
+	} catch (err) {}
+}
+/**
+* Writes a progress line to stderr, so stdout keeps carrying only the command report.
+*
+* Without a terminal the displays fall back to these discrete milestones, which are just as
+* much part of the progress display as an in-place redraw and therefore share its stream.
+*/
+function logProgressLine(message) {
+	if (logger.isEnabledFor("info")) console.error(message);
+}
+/** Writes a settle message on the stream matching its severity. */
+function logSettle(message, level) {
+	if (level === "warn") {
+		logger.warn(message);
+		return;
+	}
+	logProgressLine(message);
+}
+/** Restores the cursor and abandons the active progress line; safe to call at any time. */
+function restoreTerminal() {
+	if (!cursorHidden) return;
+	cursorHidden = false;
+	writeToStderr(`${CLEAR_LINE}${CURSOR_SHOW}`);
+}
+/** Restores the cursor, then re-raises the signal with the default disposition. */
+function handleTerminationSignal(signal) {
+	restoreTerminal();
+	removeTerminalGuards();
+	process.kill(process.pid, signal);
+}
+/** Installs exit, crash and signal hooks so a hidden cursor is always restored. */
+function installTerminalGuards() {
+	if (guardsInstalled) return;
+	guardsInstalled = true;
+	process.on("exit", restoreTerminal);
+	process.on("uncaughtExceptionMonitor", restoreTerminal);
+	process.on("SIGINT", handleTerminationSignal);
+	process.on("SIGTERM", handleTerminationSignal);
+}
+/** Removes the cursor guards once no dynamic render is active. */
+function removeTerminalGuards() {
+	if (!guardsInstalled) return;
+	guardsInstalled = false;
+	process.off("exit", restoreTerminal);
+	process.off("uncaughtExceptionMonitor", restoreTerminal);
+	process.off("SIGINT", handleTerminationSignal);
+	process.off("SIGTERM", handleTerminationSignal);
+}
+/** Builds the mutable rendering state shared by bars and spinners. */
+function createRenderState(options) {
+	const stream = options.stream ?? process.stderr;
+	const now = options.now ?? Date.now;
+	return {
+		stream,
+		interactive: options.interactive ?? isProgressInteractive(process.env, stream.isTTY),
+		ownsProcessStderr: options.stream === void 0,
+		label: options.label,
+		now,
+		throttleMs: Math.max(1, options.throttleMs ?? 100),
+		startedAt: now(),
+		lastFrameAt: Number.NEGATIVE_INFINITY,
+		active: false
+	};
+}
+/** Truncates a frame so it never wraps onto a second terminal line. */
+function fitToWidth(state, line) {
+	const limit = Math.max(1, (state.stream.columns ?? DEFAULT_COLUMNS) - 1);
+	if (line.length <= limit) return line;
+	if (limit <= 3) return TRUNCATION.slice(0, limit);
+	return `${line.slice(0, limit - 3)}${TRUNCATION}`;
+}
+/** Hides the cursor and arms the exit guards when a dynamic render starts. */
+function beginFrame(state) {
+	if (state.active) return;
+	state.active = true;
+	if (!state.ownsProcessStderr) {
+		state.stream.write(CURSOR_HIDE);
+		return;
+	}
+	activeDynamicRenders += 1;
+	if (activeDynamicRenders > 1) return;
+	cursorHidden = true;
+	installTerminalGuards();
+	state.stream.write(CURSOR_HIDE);
+}
+/** Clears the dynamic line and reveals the cursor once the render stops. */
+function endFrame(state) {
+	if (!state.interactive || !state.active) return;
+	state.active = false;
+	state.stream.write(CLEAR_LINE);
+	if (!state.ownsProcessStderr) {
+		state.stream.write(CURSOR_SHOW);
+		return;
+	}
+	activeDynamicRenders = Math.max(0, activeDynamicRenders - 1);
+	if (activeDynamicRenders === 0) {
+		cursorHidden = false;
+		removeTerminalGuards();
+		state.stream.write(CURSOR_SHOW);
+	}
+}
+/** Draws one frame, throttled unless `force`d, replacing whatever the line held. */
+function drawFrame(state, line, force = false) {
+	if (!state.interactive) return;
+	const now = state.now();
+	if (!force && now - state.lastFrameAt < state.throttleMs) return;
+	state.lastFrameAt = now;
+	beginFrame(state);
+	state.stream.write(`${CLEAR_LINE}${fitToWidth(state, line)}${FRAME_TAIL}`);
+}
+/** Formats a duration in milliseconds as seconds. */
+function formatDuration(ms) {
+	const seconds = Math.max(0, ms) / 1e3;
+	return seconds < 10 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`;
+}
+/** Formats a completed transfer as size, duration and average speed. */
+function formatTransferSummary(bytes, elapsedMs) {
+	const elapsed = Math.max(elapsedMs, 1);
+	return `${formatBytes(bytes)} in ${formatDuration(elapsed)} (${formatBytes(bytes / (elapsed / 1e3))}/s)`;
+}
+/** Builds the `[====>   ]` fill for a completion ratio. */
+function buildBar(ratio, width) {
+	const filled = Math.max(0, Math.min(width, Math.round(ratio * width)));
+	if (filled >= width) return "=".repeat(width);
+	return `${"=".repeat(filled)}>${" ".repeat(width - filled - 1)}`;
+}
+/** Picks a bar width that keeps the whole frame inside the terminal. */
+function barWidthFor(state, reserved) {
+	const columns = state.stream.columns ?? DEFAULT_COLUMNS;
+	return Math.max(MIN_BAR_WIDTH, Math.min(MAX_BAR_WIDTH, columns - reserved));
+}
+/** Renders one deterministic transfer frame. */
+function renderBarFrame(state, transferred, total) {
+	const elapsedMs = state.now() - state.startedAt;
+	const speed = transferred / (Math.max(elapsedMs, 1) / 1e3);
+	const speedText = `${formatBytes(speed)}/s`;
+	if (!total || total <= 0) return `${state.label} ${formatBytes(transferred)} (${speedText}, ${formatDuration(elapsedMs)})`;
+	const ratio = Math.max(0, Math.min(1, transferred / total));
+	const percent = Math.floor(ratio * 100);
+	const eta = speed > 0 && transferred < total ? `, ETA ${formatDuration((total - transferred) / speed * 1e3)}` : "";
+	const tail = ` ${percent}% (${formatBytes(transferred)} / ${formatBytes(total)}, ${speedText}${eta})`;
+	const width = barWidthFor(state, state.label.length + tail.length + 2 + 4);
+	return `${state.label} [${buildBar(ratio, width)}]${tail}`;
+}
+/** Renders one indeterminate spinner frame. */
+function renderSpinnerFrame(state, frame) {
+	const glyph = SPINNER_FRAMES[frame % SPINNER_FRAMES.length] ?? "|";
+	return `${state.label} ${glyph} (${formatDuration(state.now() - state.startedAt)})`;
+}
+/** Creates a byte progress bar; without a terminal it logs start, milestones and completion. */
+function createProgressBar(options) {
+	const state = createRenderState(options);
+	let transferred = 0;
+	let total = options.total !== void 0 && options.total > 0 ? options.total : void 0;
+	let milestone = 0;
+	if (!state.interactive && options.announce !== false) logProgressLine(`${state.label}${total ? ` (${formatBytes(total)})` : ""}...`);
+	if (state.interactive) drawFrame(state, renderBarFrame(state, 0, total), true);
+	const settle = (message, level) => {
+		endFrame(state);
+		if (message) logSettle(message, level);
+	};
+	return {
+		update: (next, nextTotal) => {
+			transferred = Math.max(transferred, next);
+			if (nextTotal !== void 0 && nextTotal > 0) total = nextTotal;
+			if (total !== void 0 && transferred > total) total = void 0;
+			if (state.interactive) {
+				drawFrame(state, renderBarFrame(state, transferred, total));
+				return;
+			}
+			if (!total) return;
+			const ratio = transferred / total;
+			while (milestone < PROGRESS_MILESTONES.length && ratio >= (PROGRESS_MILESTONES[milestone] ?? 1)) {
+				const reached = PROGRESS_MILESTONES[milestone] ?? 1;
+				milestone += 1;
+				logProgressLine(`${state.label}: ${Math.round(reached * 100)}% (${formatBytes(transferred)} / ${formatBytes(total)})`);
+			}
+		},
+		finish: (message) => settle(message, "info"),
+		fail: (message) => settle(message, "warn")
+	};
+}
+/** Creates an indeterminate spinner driven by a timer and by manual ticks from sync loops. */
+function createSpinner(options) {
+	const state = createRenderState(options);
+	let frame = 0;
+	let timer;
+	const clearTimer = () => {
+		if (timer !== void 0) {
+			clearInterval(timer);
+			timer = void 0;
+		}
+	};
+	const settle = (message, level) => {
+		clearTimer();
+		endFrame(state);
+		if (message) logSettle(message, level);
+	};
+	return {
+		start: () => {
+			if (!state.interactive) {
+				if (options.announce !== false) logProgressLine(`${state.label}...`);
+				return;
+			}
+			drawFrame(state, renderSpinnerFrame(state, frame), true);
+			if (timer === void 0) {
+				timer = setInterval(() => {
+					frame += 1;
+					drawFrame(state, renderSpinnerFrame(state, frame), true);
+				}, state.throttleMs);
+				timer.unref();
+			}
+		},
+		tick: () => {
+			frame += 1;
+			drawFrame(state, renderSpinnerFrame(state, frame));
+		},
+		updateText: (label) => {
+			state.label = label;
+			drawFrame(state, renderSpinnerFrame(state, frame), true);
+		},
+		stop: (message) => settle(message, "info"),
+		fail: (message) => settle(message, "warn")
+	};
+}
+//#endregion
 //#region src/annotations-realms.ts
 /** Side markers emitted by the upstream docgen, mapped to the realm that owns them. */
 const SIDE_MARKERS = [
@@ -5065,6 +5374,8 @@ const SIDE_MARKERS = [
 	["authority-only", "shared"],
 	["network-authority", "shared"]
 ];
+/** Number of source lines parsed between two spinner ticks while splitting realms. */
+const PARSE_PROGRESS_STEP_LINES = 2e3;
 /** Finds the realm declared by the side marker of a documentation block. */
 function realmOfDocBlock(doc) {
 	for (const line of doc) for (const [image, realm] of SIDE_MARKERS) if (line.includes(`assets/${image}.png`)) return realm;
@@ -5095,10 +5406,17 @@ function kindOf(declaration) {
 	return "other";
 }
 /** Segments annotations into comment runs plus their optional declaration statement. */
-function parseAnnotationUnits(text) {
+function parseAnnotationUnits(text, onProgress) {
 	const lines = text.split(/\r?\n/);
 	const units = [];
 	let index = 0;
+	let nextTick = PARSE_PROGRESS_STEP_LINES;
+	const tick = () => {
+		if (onProgress !== void 0 && index >= nextTick) {
+			nextTick = index + PARSE_PROGRESS_STEP_LINES;
+			onProgress();
+		}
+	};
 	const push = (doc, decl) => {
 		const first = decl?.[0] ?? null;
 		units.push({
@@ -5112,6 +5430,7 @@ function parseAnnotationUnits(text) {
 		});
 	};
 	while (index < lines.length) {
+		tick();
 		const doc = [];
 		while (index < lines.length && (lines[index].startsWith("---") || lines[index].trim() === "")) {
 			if (lines[index].startsWith("---")) doc.push(lines[index]);
@@ -5210,11 +5529,12 @@ function renderRealm(units, realm) {
 * and a realm-specific class table is dropped from the other realm unless it still has
 * instance members there.
 */
-function splitAnnotationsByRealm(text) {
-	const units = parseAnnotationUnits(text);
+function splitAnnotationsByRealm(text, onProgress) {
+	const units = parseAnnotationUnits(text, onProgress);
 	const classRealms = classRealmsOf(units);
 	const crossRealm = crossRealmClasses(units);
 	const memberRealms = markedMemberRealms(units);
+	onProgress?.();
 	for (const unit of units) {
 		if (unit.owner) {
 			unit.realm = unit.owner;
@@ -5228,8 +5548,11 @@ function splitAnnotationsByRealm(text) {
 		const classRealm = unit.receiver ? classRealms.get(unit.receiver) : void 0;
 		unit.realm = classRealm && classRealm !== "shared" && !crossRealm.has(unit.receiver) ? classRealm : "shared";
 	}
+	onProgress?.();
+	const client = renderRealm(units, "client");
+	onProgress?.();
 	return {
-		client: renderRealm(units, "client"),
+		client,
 		server: renderRealm(units, "server")
 	};
 }
@@ -5259,17 +5582,204 @@ function deriveRealmAnnotationFiles(annotationsPath, cacheDir) {
 		client: clientPath,
 		server: serverPath
 	};
-	const split = splitAnnotationsByRealm(fs.readFileSync(annotationsPath, "utf-8"));
-	fs.mkdirSync(targetDir, { recursive: true });
-	writeAtomicFileSync(clientPath, split.client);
-	writeAtomicFileSync(serverPath, split.server);
-	logger.debug(`[realms] Derived realm annotations in ${targetDir}.`);
+	const spinner = createSpinner({ label: "[realms] Deriving client/server annotations" });
+	spinner.start();
+	try {
+		const split = splitAnnotationsByRealm(fs.readFileSync(annotationsPath, "utf-8"), () => spinner.tick());
+		spinner.updateText("[realms] Writing derived annotations");
+		fs.mkdirSync(targetDir, { recursive: true });
+		writeAtomicFileSync(clientPath, split.client);
+		writeAtomicFileSync(serverPath, split.server);
+		logger.debug(`[realms] Derived realm annotations in ${targetDir}.`);
+		spinner.stop(`[realms] Derived client/server annotations in ${targetDir}.`);
+	} catch (err) {
+		spinner.fail();
+		throw err;
+	}
 	return {
 		client: clientPath,
 		server: serverPath
 	};
 }
 //#endregion
+//#region src/download-guard.ts
+/**
+* Shared transport policy for every outbound download performed by nanos-lint.
+*
+* `SECURITY.md` requires download requests *and* HTTP redirects to use HTTPS and to stay on
+* GitHub infrastructure. Redirects are therefore resolved hop by hop in `"manual"` mode: the
+* default `"follow"` mode contacts the redirect target before any check can run, which would
+* let a redirect downgrade to plaintext `http://` or reach an internal address.
+*/
+const ALLOWED_DOWNLOAD_DOMAINS = ["github.com", "githubusercontent.com"];
+/** Headers that must never follow a redirect to another origin. */
+const CREDENTIAL_HEADERS = [
+	"authorization",
+	"cookie",
+	"proxy-authorization"
+];
+/** Returns the origin of an already validated URL, or null when it cannot be parsed. */
+function originOf(urlString) {
+	try {
+		return new URL(urlString).origin;
+	} catch {
+		return null;
+	}
+}
+/**
+* Returns the caller's headers with credentials removed.
+*
+* The runtime strips `Authorization` when it follows a redirect by itself, so dropping it here
+* keeps that guarantee once the guard re-issues each hop manually instead of following it.
+*/
+function withoutCredentialHeaders(headers) {
+	if (headers === void 0) return;
+	const stripped = new Headers(headers);
+	for (const name of CREDENTIAL_HEADERS) stripped.delete(name);
+	return stripped;
+}
+/** Validates that a URL uses HTTPS and targets an allowlisted GitHub host. */
+function isAllowedDownloadUrl(urlString) {
+	try {
+		const parsed = new URL(urlString);
+		if (parsed.protocol !== "https:") return false;
+		const hostname = parsed.hostname.toLowerCase();
+		return ALLOWED_DOWNLOAD_DOMAINS.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
+	} catch {
+		return false;
+	}
+}
+/**
+* Releases a response body without letting cleanup failures mask the block reason.
+*
+* Every failure mode is swallowed on purpose: a missing body, a double that exposes no
+* `cancel()`, and a `cancel()` that rejects or returns a non-promise must all leave the
+* caller free to report why the response was refused.
+*/
+async function cancelResponseBody(res) {
+	try {
+		if (typeof res.body?.cancel === "function") await res.body.cancel();
+	} catch (err) {}
+}
+/** Reads the `Location` header of a redirect response, tolerating minimal test doubles. */
+function getRedirectLocation(res) {
+	if (typeof res.headers?.get !== "function") return null;
+	return res.headers.get("location");
+}
+/**
+* Reads the `content-length` of a response whose bytes are streamed as received.
+*
+* A content-encoded response (`content-encoding: gzip`, `br`, ...) is decoded by the runtime
+* while its `content-length` still counts the compressed payload, so that value describes
+* neither the byte stream a progress bar counts nor the text that reaches the cache. Such a
+* response reports no usable length and progress falls back to transferred bytes and speed.
+*/
+function parseDeclaredContentLength(res) {
+	const encoding = (res.headers?.get?.("content-encoding") ?? "").trim().toLowerCase();
+	if (encoding !== "" && encoding !== "identity") return;
+	const header = res.headers?.get?.("content-length");
+	if (!header) return;
+	const declared = parseInt(header, 10);
+	return Number.isFinite(declared) && declared > 0 ? declared : void 0;
+}
+/** Classifies a response the runtime followed by itself despite `redirect: "manual"`. */
+function isOpaqueRedirect(res) {
+	return res.type === "opaqueredirect";
+}
+/**
+* Performs a fetch with hop-by-hop redirect validation against the allowlist.
+*
+* Each hop must use HTTPS and stay on an allowlisted GitHub host; a hop that does not is never
+* contacted, because `redirect: "manual"` surfaces the 3xx response instead of following it.
+* The final response URL is validated as well, which keeps the policy enforced even on a
+* runtime that ignores `"manual"` and follows redirects on its own.
+*/
+async function guardedFetch(url, init = {}) {
+	if (!isAllowedDownloadUrl(url)) return {
+		ok: false,
+		reason: "disallowed-url",
+		url
+	};
+	let currentUrl = url;
+	let currentInit = init;
+	let followed = 0;
+	const requestOrigin = originOf(url);
+	for (;;) {
+		let response;
+		try {
+			response = await fetch(currentUrl, {
+				...currentInit,
+				redirect: "manual"
+			});
+		} catch (err) {
+			return {
+				ok: false,
+				reason: "network-error",
+				url: currentUrl,
+				error: err
+			};
+		}
+		if (isOpaqueRedirect(response)) {
+			await cancelResponseBody(response);
+			return {
+				ok: false,
+				reason: "disallowed-redirect",
+				url: currentUrl
+			};
+		}
+		if (!(response.status >= 300 && response.status < 400)) {
+			if (response.url && !isAllowedDownloadUrl(response.url)) {
+				await cancelResponseBody(response);
+				return {
+					ok: false,
+					reason: "disallowed-redirect",
+					url: response.url
+				};
+			}
+			return {
+				ok: true,
+				response
+			};
+		}
+		const location = getRedirectLocation(response);
+		if (location === null || location.trim() === "") {
+			await cancelResponseBody(response);
+			return {
+				ok: false,
+				reason: "missing-location",
+				url: currentUrl
+			};
+		}
+		let nextUrl;
+		try {
+			nextUrl = new URL(location, currentUrl).href;
+		} catch (err) {
+			nextUrl = "";
+		}
+		if (!isAllowedDownloadUrl(nextUrl)) {
+			await cancelResponseBody(response);
+			return {
+				ok: false,
+				reason: "disallowed-redirect",
+				url: nextUrl || location
+			};
+		}
+		await cancelResponseBody(response);
+		followed++;
+		if (followed > 5) return {
+			ok: false,
+			reason: "too-many-redirects",
+			url: nextUrl
+		};
+		const nextOrigin = originOf(nextUrl);
+		if (requestOrigin !== null && nextOrigin !== null && nextOrigin !== requestOrigin) currentInit = {
+			...init,
+			headers: withoutCredentialHeaders(init.headers)
+		};
+		currentUrl = nextUrl;
+	}
+}
+//#endregion
 //#region src/luals/version.ts
 const FALLBACK_LUALS_VERSION = "3.19.1";
 const DEFAULT_LUALS_VERSION = "latest";
@@ -5301,10 +5811,15 @@ async function fetchLatestLuaLSVersionFromGitHub() {
 	try {
 		const headers = { "User-Agent": "nanos-lint" };
 		if (process.env.GITHUB_TOKEN) headers["Authorization"] = `token ${process.env.GITHUB_TOKEN}`;
-		const res = await fetch("https://api.github.com/repos/LuaLS/lua-language-server/releases/latest", {
+		const result = await guardedFetch("https://api.github.com/repos/LuaLS/lua-language-server/releases/latest", {
 			headers,
 			signal: AbortSignal.timeout(5e3)
 		});
+		if (!result.ok || !result.response) {
+			if (result.reason && result.reason !== "network-error") logger.warn(`[luals] Refused LuaLS release lookup: requests must stay on allowlisted GitHub infrastructure over HTTPS (${result.url ?? "unknown URL"}).`);
+			return null;
+		}
+		const res = result.response;
 		if (res.ok) {
 			const data = await res.json();
 			const version = typeof data.tag_name === "string" ? sanitizeLuaLSVersion(data.tag_name) : null;
@@ -5853,6 +6368,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
@@ -5867,6 +6389,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;
 	}
@@ -5882,6 +6405,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;
 	}
@@ -5895,6 +6419,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;
 	}
@@ -5919,6 +6444,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.`);
@@ -6035,11 +6561,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 [];
 	}
@@ -6089,6 +6617,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();
@@ -6100,20 +6629,6 @@ function findExistingLuaLSDir(version, baseCacheDir = getBaseLuaLSCacheDir()) {
 //#region src/luals/download.ts
 const DOWNLOAD_TIMEOUT_MS = 12e4;
 const MAX_ARCHIVE_SIZE_BYTES = 157286400;
-const ALLOWED_DOWNLOAD_DOMAINS = ["github.com", "githubusercontent.com"];
-/**
-* Validates that a download URL uses HTTPS and targets an allowlisted host.
-*/
-function isAllowedDownloadUrl(urlString) {
-	try {
-		const parsed = new URL(urlString);
-		if (parsed.protocol !== "https:") return false;
-		const hostname = parsed.hostname.toLowerCase();
-		return ALLOWED_DOWNLOAD_DOMAINS.some((domain) => hostname === domain || hostname.endsWith(`.${domain}`));
-	} catch {
-		return false;
-	}
-}
 /** Chunk size used when hashing an archive, so a 150 MB asset is never buffered whole. */
 const HASH_CHUNK_SIZE_BYTES = 1048576;
 /**
@@ -6148,12 +6663,22 @@ async function* limitDownloadStream(source) {
 		yield chunk;
 	}
 }
+/** Reports cumulative transferred bytes while passing a download stream through unchanged. */
+async function* trackDownloadProgress(source, onProgress) {
+	let transferred = 0;
+	for await (const chunk of source) {
+		transferred += chunk.length;
+		onProgress(transferred);
+		yield chunk;
+	}
+}
 /** Returns whether a cache directory holds a complete, executable LuaLS installation. */
 function isCompleteLuaLSInstall(binaryPath, completeMarker, version) {
 	if (!fs.existsSync(binaryPath) || !fs.existsSync(completeMarker)) return false;
 	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;
 	}
@@ -6184,6 +6709,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 {
@@ -6192,6 +6718,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)}`);
 		}
 	}
@@ -6208,28 +6735,27 @@ async function downloadAndPromoteLuaLS(resolvedVersion, info, destDir, binaryPat
 			logger.info(`[luals] Reusing existing LuaLS ${resolvedVersion} installation from ${existingSourceDir}...`);
 			fs.cpSync(existingSourceDir, tempDir, { recursive: true });
 		} else {
-			if (!isAllowedDownloadUrl(url)) throw new LuaLSError(`Refusing to download LuaLS from untrusted URL: ${url}`, "ERR_LUALS_DOWNLOAD", "Download URLs must use HTTPS and target an allowlisted GitHub host.");
 			logger.info(`[luals] Downloading LuaLS ${resolvedVersion} from ${url}...`);
 			let response = null;
 			let lastErr = null;
 			for (let attempt = 1; attempt <= 3; attempt++) {
 				try {
-					const res = await fetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
-					if (res.url && !isAllowedDownloadUrl(res.url)) {
-						if (typeof res.body?.cancel === "function") try {
-							await res.body.cancel();
-						} catch (cancelErr) {}
-						logger.warn(`[luals] Redirect to untrusted URL blocked: ${res.url}`);
-						throw new LuaLSError(`Redirect to untrusted URL blocked: ${res.url}`, "ERR_LUALS_DOWNLOAD", "Download redirects must stay on allowlisted HTTPS GitHub hosts.");
-					}
-					if (res.ok && res.body) {
-						response = res;
+					const outcome = await guardedFetch(url, { signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS) });
+					if (!outcome.ok || !outcome.response) {
+						if (outcome.reason !== "network-error") {
+							const blockedMessage = `Redirect to untrusted URL blocked: ${outcome.url ?? url}`;
+							logger.warn(`[luals] ${blockedMessage}`);
+							throw new LuaLSError(blockedMessage, "ERR_LUALS_DOWNLOAD", "Download redirects must stay on allowlisted HTTPS GitHub hosts.");
+						}
+						lastErr = outcome.error ?? /* @__PURE__ */ new Error(`Failed to download ${url}`);
+					} else if (outcome.response.ok && outcome.response.body) {
+						response = outcome.response;
 						break;
+					} else {
+						const res = outcome.response;
+						await cancelResponseBody(res);
+						lastErr = /* @__PURE__ */ new Error(`Failed to download ${url}: ${res.status} ${res.statusText}`);
 					}
-					if (typeof res.body?.cancel === "function") try {
-						await res.body.cancel();
-					} catch (cancelErr) {}
-					lastErr = /* @__PURE__ */ new Error(`Failed to download ${url}: ${res.status} ${res.statusText}`);
 				} catch (err) {
 					if (err instanceof LuaLSError) throw err;
 					lastErr = err;
@@ -6245,50 +6771,76 @@ async function downloadAndPromoteLuaLS(resolvedVersion, info, destDir, binaryPat
 					throw new LuaLSError(`Archive size (${contentLength} bytes) exceeds maximum limit (${MAX_ARCHIVE_SIZE_BYTES} bytes)`, "ERR_LUALS_DOWNLOAD", "Verify the LuaLS release asset size or specify a local binary with LUALS_BIN.");
 				}
 			}
+			const declaredTotal = parseDeclaredContentLength(response);
+			const downloadStartedAt = Date.now();
+			let transferred = 0;
+			const progress = createProgressBar({
+				label: `[luals] Downloading ${info.assetName}`,
+				total: declaredTotal,
+				announce: false
+			});
 			const fileStream = fs.createWriteStream(archivePath);
 			try {
 				const streamSource = typeof Readable.fromWeb === "function" && !("pipe" in response.body) ? Readable.fromWeb(response.body) : response.body;
-				await pipeline(streamSource, limitDownloadStream, fileStream);
+				await pipeline(streamSource, limitDownloadStream, (source) => trackDownloadProgress(source, (bytes) => {
+					transferred = bytes;
+					progress.update(bytes, declaredTotal);
+				}), fileStream);
 			} catch (streamErr) {
+				progress.fail();
 				try {
 					if (fs.existsSync(archivePath)) fs.unlinkSync(archivePath);
 				} catch (unlinkErr) {}
 				if (streamErr instanceof LuaLSError) throw streamErr;
 				throw new LuaLSError(`Failed to download LuaLS from ${url}: ${streamErr instanceof Error ? streamErr.message : String(streamErr)}`, "ERR_LUALS_DOWNLOAD", "Check your network connection or specify a custom binary with LUALS_BIN.", { cause: streamErr });
 			}
+			progress.finish(`[luals] Downloaded ${info.assetName} (${formatTransferSummary(transferred, Date.now() - downloadStartedAt)})`);
 			const archiveSha256 = computeFileSha256(archivePath);
 			logger.info(`[luals] Downloaded ${info.assetName} (SHA-256 ${archiveSha256})`);
 			logger.info(`[luals] Extracting to ${destDir}...`);
-			await validateArchiveMembers(archivePath);
-			try {
-				const tarArgs = process.platform === "win32" ? [
-					"-xf",
-					path.basename(archivePath),
-					"-C",
-					tempDir
-				] : [
-					"-xf",
-					path.basename(archivePath),
-					"--no-same-owner",
-					"--no-same-permissions",
-					"-C",
-					tempDir
-				];
-				await execFileAsync$1(getTarBinary(), tarArgs, { cwd: path.dirname(archivePath) });
-			} catch (tarErr) {
-				if (process.platform === "win32" && info.assetName.endsWith(".zip")) await execFileAsync$1("powershell.exe", [
-					"-NoProfile",
-					"-Command",
-					`Expand-Archive -Path '${escapePowerShellSingleQuote(archivePath)}' -DestinationPath '${escapePowerShellSingleQuote(tempDir)}' -Force`
-				]);
-				else throw tarErr;
-			}
-			const extractedSize = getDirectorySize(tempDir);
-			if (extractedSize > 524288e3) throw new LuaLSError(`Extracted archive size (${extractedSize} bytes) exceeds maximum limit (${MAX_DECOMPRESSED_SIZE_BYTES} bytes)`, "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and ensure there is sufficient disk space.");
+			const spinner = createSpinner({
+				label: `[luals] Extracting ${info.assetName}`,
+				announce: false
+			});
+			spinner.start();
+			let extractedSize;
 			try {
-				fs.unlinkSync(archivePath);
-			} catch (err) {
-				logger.debug(`[luals] Failed to delete temporary archive ${archivePath}: ${err instanceof Error ? err.message : String(err)}`);
+				await validateArchiveMembers(archivePath);
+				try {
+					const tarArgs = process.platform === "win32" ? [
+						"-xf",
+						path.basename(archivePath),
+						"-C",
+						tempDir
+					] : [
+						"-xf",
+						path.basename(archivePath),
+						"--no-same-owner",
+						"--no-same-permissions",
+						"-C",
+						tempDir
+					];
+					await execFileAsync$1(getTarBinary(), tarArgs, { cwd: path.dirname(archivePath) });
+				} catch (tarErr) {
+					if (process.platform === "win32" && info.assetName.endsWith(".zip")) await execFileAsync$1("powershell.exe", [
+						"-NoProfile",
+						"-Command",
+						`Expand-Archive -Path '${escapePowerShellSingleQuote(archivePath)}' -DestinationPath '${escapePowerShellSingleQuote(tempDir)}' -Force`
+					]);
+					else throw tarErr;
+				}
+				spinner.updateText("[luals] Verifying extracted files");
+				extractedSize = getDirectorySize(tempDir);
+				if (extractedSize > 524288e3) throw new LuaLSError(`Extracted archive size (${extractedSize} bytes) exceeds maximum limit (${MAX_DECOMPRESSED_SIZE_BYTES} bytes)`, "ERR_LUALS_EXTRACT", "Run 'nanos-lint clean-cache' and ensure there is sufficient disk space.");
+				try {
+					fs.unlinkSync(archivePath);
+				} catch (err) {
+					logger.debug(`[luals] Failed to delete temporary archive ${archivePath}: ${err instanceof Error ? err.message : String(err)}`);
+				}
+				spinner.stop(`[luals] Extracted ${formatBytes(extractedSize)} to ${destDir}`);
+			} catch (extractErr) {
+				spinner.fail();
+				throw extractErr;
 			}
 		}
 		const tempBinaryPath = path.join(tempDir, info.binaryRelativePath);
@@ -6775,6 +7327,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) {
@@ -6787,6 +7340,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)}`);
 			}
 		}
@@ -6796,11 +7350,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);
@@ -6862,12 +7418,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);
@@ -10555,7 +11113,7 @@ 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";
 /** Reads an HTTP response body with an upper byte limit to guard against memory exhaustion. */
-async function readBoundedResponseBody(res, maxBytes, onExceeded) {
+async function readBoundedResponseBody(res, maxBytes, onExceeded, onProgress) {
 	const lengthHeader = res.headers?.get?.("content-length");
 	if (lengthHeader) {
 		const declared = parseInt(lengthHeader, 10);
@@ -10576,6 +11134,7 @@ async function readBoundedResponseBody(res, maxBytes, onExceeded) {
 				onExceeded(total, "stream");
 				return null;
 			}
+			onProgress?.(total);
 			chunks.push(buf);
 		}
 		return Buffer.concat(chunks).toString("utf-8");
@@ -10591,15 +11150,35 @@ async function readBoundedResponseBody(res, maxBytes, onExceeded) {
 	}
 	return "";
 }
+/**
+* Resolves a request through the download guard, which refuses an off-allowlist request URL,
+* an off-allowlist redirect hop and an off-allowlist final response URL, releasing the body of
+* every refused response instead of downloading it.
+*/
+async function resolveGuardedResponse(url, init) {
+	const result = await guardedFetch(url, init);
+	if (result.ok && result.response) return { res: result.response };
+	return { block: result };
+}
+/** Builds the user-facing error for a request refused by the download transport policy. */
+function downloadBlockError(result) {
+	if (result.reason === "network-error") return new AnnotationsError(`Failed to download annotations.lua: ${result.error instanceof Error ? result.error.message : String(result.error)}`, "ERR_ANNOTATIONS_DOWNLOAD", "Verify your internet connection and that GitHub raw endpoints are accessible.", { cause: result.error });
+	return new AnnotationsError(`${result.reason === "too-many-redirects" ? "Redirect chain too long" : result.reason === "missing-location" ? "Redirect without a usable target" : "Redirect blocked"}: requests must stay on allowlisted GitHub infrastructure over HTTPS (${result.url ?? "unknown URL"})`, "ERR_ANNOTATIONS_DOWNLOAD", "Verify that no proxy or DNS override redirects GitHub traffic to another host or to plaintext http://.");
+}
 /** Fetches the latest commit SHA for the annotations branch from the GitHub API. */
 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, {
+		const outcome = await resolveGuardedResponse(GITHUB_COMMITS_API, {
 			headers,
 			signal: AbortSignal.timeout(5e3)
 		});
+		if ("block" in outcome) {
+			if (outcome.block.reason !== "network-error") logger.warn(`[annotations] ${downloadBlockError(outcome.block).message}`);
+			return null;
+		}
+		const { res } = outcome;
 		if (res.ok) {
 			const rawJson = await readBoundedResponseBody(res, MAX_COMMIT_JSON_SIZE_BYTES, (bytes) => {
 				logger.warn(`GitHub commits response exceeded size limit of ${MAX_COMMIT_JSON_SIZE_BYTES} bytes (${bytes} bytes)`);
@@ -10626,16 +11205,40 @@ function getRawAnnotationsUrl(commitSha) {
 }
 /** Downloads raw annotations.lua content from GitHub raw content endpoints. */
 async function fetchRawAnnotationsContent(commitSha) {
-	const url = getRawAnnotationsUrl(commitSha);
-	const res = await fetch(url, {
+	const outcome = await resolveGuardedResponse(getRawAnnotationsUrl(commitSha), {
 		headers: { "User-Agent": "nanos-lint" },
 		signal: AbortSignal.timeout(15e3)
 	});
+	if ("block" in outcome) {
+		const blockError = downloadBlockError(outcome.block);
+		logger.warn(`[annotations] ${blockError.message}`);
+		throw blockError;
+	}
+	const { res } = outcome;
 	if (!res.ok) throw new AnnotationsError(`Failed to download annotations.lua: ${res.status} ${res.statusText}`, "ERR_ANNOTATIONS_DOWNLOAD", "Verify your internet connection and that GitHub raw endpoints are accessible.");
-	const text = await readBoundedResponseBody(res, MAX_ANNOTATIONS_SIZE_BYTES, (bytes, reason) => {
-		throw new AnnotationsError(reason === "header" ? `Annotations file size (${bytes} bytes) exceeds maximum limit (${MAX_ANNOTATIONS_SIZE_BYTES} bytes)` : `Annotations file download exceeded maximum allowed size of ${MAX_ANNOTATIONS_SIZE_BYTES} bytes`, "ERR_ANNOTATIONS_TOO_LARGE", "Specify a local annotations file via --annotations <path>.");
+	const declaredTotal = parseDeclaredContentLength(res);
+	const startedAt = Date.now();
+	let transferred = 0;
+	const commitLabel = commitSha ? ` (${commitSha.slice(0, 7)})` : "";
+	const progress = createProgressBar({
+		label: `[annotations] Downloading ${ANNOTATIONS_FILENAME}${commitLabel}`,
+		total: declaredTotal,
+		announce: false
 	});
-	if (!text || text.length < 1e3) throw new AnnotationsError("Downloaded annotations.lua appears truncated or invalid", "ERR_ANNOTATIONS_INVALID", "Retry downloading or pass a local annotations file via --annotations <path>.");
+	let text;
+	try {
+		text = await readBoundedResponseBody(res, MAX_ANNOTATIONS_SIZE_BYTES, (bytes, reason) => {
+			throw new AnnotationsError(reason === "header" ? `Annotations file size (${bytes} bytes) exceeds maximum limit (${MAX_ANNOTATIONS_SIZE_BYTES} bytes)` : `Annotations file download exceeded maximum allowed size of ${MAX_ANNOTATIONS_SIZE_BYTES} bytes`, "ERR_ANNOTATIONS_TOO_LARGE", "Specify a local annotations file via --annotations <path>.");
+		}, (bytes) => {
+			transferred = bytes;
+			progress.update(bytes, declaredTotal);
+		});
+		if (!text || text.length < 1e3) throw new AnnotationsError("Downloaded annotations.lua appears truncated or invalid", "ERR_ANNOTATIONS_INVALID", "Retry downloading or pass a local annotations file via --annotations <path>.");
+	} catch (err) {
+		progress.fail();
+		throw err;
+	}
+	progress.finish(`[annotations] Downloaded ${ANNOTATIONS_FILENAME} (${formatTransferSummary(transferred, Date.now() - startedAt)})`);
 	return text;
 }
 /**
@@ -10882,11 +11485,12 @@ function createProgram(options) {
 		"info",
 		"debug",
 		"silent"
-	]).default(DEFAULT_LOG_LEVEL)).hook("preAction", (thisCommand, actionCommand) => {
+	]).default(DEFAULT_LOG_LEVEL)).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);
-	}).exitOverride().configureOutput({
+		if (opts.progress === false) setProgressMode("off");
+	}).exitOverride().configureHelp({ showGlobalOptions: true }).configureOutput({
 		writeOut: (str) => console.log(str.trimEnd()),
 		writeErr: (str) => logger.error(str.trimEnd())
 	});
@@ -10914,6 +11518,10 @@ function createProgram(options) {
 		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,
@@ -11005,6 +11613,7 @@ function createProgram(options) {
 		}
 	};
 	const handleCacheStatus = (opts) => {
+		if (opts?.json) logger.setDiagnosticStream("stderr");
 		const report = getCacheStatus();
 		if (opts?.json) writeOutput(JSON.stringify(report, null, 2));
 		else writeOutput(formatCacheStatusPretty(report));
@@ -11046,6 +11655,8 @@ Examples:
 }
 /** Parses command-line arguments and executes the requested CLI action. */
 async function runCLI(args = process.argv.slice(2)) {
+	setProgressMode("auto");
+	logger.setDiagnosticStream("stdout");
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
 		if (!arg) continue;
@@ -11118,6 +11729,6 @@ if (isDirectExecution()) runCLI().then((code) => {
 	process.exit(1);
 });
 //#endregion
-export { ALLOWED_DOWNLOAD_DOMAINS as $, stripJsonComments as $t, formatProblemSummary as A, getPlatformInfo as At, resolvePackageDependencies as B, VALID_LUALS_DIAGNOSTIC_CODES as Bt, getCachedAnnotationsFilePath as C, inspectZipMembers as Ct, updateLastCheckedDate as D, isZipArchive as Dt, readAnnotationsMetadata as E, isGzipArchive as Et, shouldEnableColor as F, resolveLuaLSVersion as Ft, computeUnrequestedExclusions as G, getPackageRoot as Gt, runLuaLSCheck as H, getDefaultAnnotationsPath as Ht, collectRealmFiles as I, sanitizeLuaLSVersion as It, findProjectRoot as J, loadUserConfig as Jt, filterReportByTargetPaths as K, initWorkspace as Kt, planRealmCheck as L, deriveRealmAnnotationFiles as Lt, formatSeverityBadge as M, FALLBACK_LUALS_VERSION as Mt, getColors as N, fetchLatestLuaLSVersionFromGitHub as Nt, formatGitHubAnnotations as O, parseTarTvSize as Ot, pluralize as P, resolveLatestLuaLSVersion as Pt, resolveCheckTargets as Q, resolveWorkspaceConfig as Qt, runRealmAwareCheck as R, splitAnnotationsByRealm as Rt, getAnnotationsMetadataFilePath as S, getTarBinary as St, isAnnotationsValid as T, isBinaryValid as Tt, countCheckedFiles as U, getDefaultTemplatePath as Ut, resolveLuaLSBinary as V, buildWorkspaceConfig as Vt, listCheckedFiles as W, getDefinitionsDir as Wt, isFilesystemRoot as X, parseJsonc as Xt, getCanonicalPath as Y, mergeConfigs as Yt, matchesTargetPaths as Z, resolveRealmMappings as Zt, MAX_ANNOTATIONS_SIZE_BYTES as _, logger as _n, MAX_ARCHIVE_MEMBER_COUNT as _t, formatCacheStatusPretty as a, LuaLSError as an, limitDownloadStream as at, MIN_ANNOTATIONS_SIZE_BYTES as b, assertValidLuaLSBinary as bt, DOCGEN_BRANCH as c, formatBytes as cn, findExistingLuaLSDir as ct, RAW_ANNOTATIONS_URL as d, fileUriToPath as dn, getIsoWeek as dt, stripTrailingSlashes as en, DOWNLOAD_TIMEOUT_MS as et, downloadAndCacheAnnotations as f, DEFAULT_LOG_LEVEL as fn, getLuaLSMetadataPath as ft, ANNOTATIONS_FILENAME as g, isValidLogLevel as gn, writeLuaLSMetadata as gt, getRawAnnotationsUrl as h, Logger as hn, readLuaLSMetadata as ht, runCLI as i, ConfigError as in, isAllowedDownloadUrl as it, formatReport as j, DEFAULT_LUALS_VERSION as jt, formatPretty as k, validateArchiveMembers as kt, DOCGEN_REPO as l, getDirectorySize as ln, getBaseLuaLSCacheDir as lt, fetchRawAnnotationsContent as m, LOG_LEVEL_PRIORITY as mn, listCachedLuaLSVersions as mt, createProgram as n, AnnotationsError as nn, computeFileSha256 as nt, getCacheStatus as o, NanosLintError as on, LUALS_METADATA_FILENAME as ot, fetchLatestCommitId as p, LOG_LEVELS as pn, listCachedLuaLSVersionDirs as pt, findCommonAncestorDirectory as q, loadConfigFile as qt, isDirectExecution as r, CacheError as rn, downloadAndExtractLuaLS as rt, resolveAnnotations as s, cleanCache as sn, cleanupOldCachedLuaLSVersions as st, collectIgnorePatterns as t, writeTempConfig as tn, MAX_ARCHIVE_SIZE_BYTES as tt, GITHUB_COMMITS_API as u, systemPaths as un, getCacheDir as ut, MAX_COMMIT_JSON_SIZE_BYTES as v, parseLogLevel as vn, MAX_DECOMPRESSED_SIZE_BYTES as vt, getTodayDateString as w, isBinaryRunnable as wt, getAnnotationsCacheDir as x, escapePowerShellSingleQuote as xt, METADATA_FILENAME as y, MIN_DOWNLOADED_BINARY_SIZE_BYTES as yt, collectDeps as z, DEFAULT_REALM_MAPPINGS as zt };
+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 };
 
-//# sourceMappingURL=cli-Cb3wLBCr.js.map
+//# sourceMappingURL=cli-I16SeKRK.js.map