@fonlan/dsh-model-parameters 0.1.7 → 0.2.0

package/lib/index.js

@@ -2,6 +2,12 @@ import z from "@deepseek-ai/schemastery";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { request } from "node:http";
+import { Agent, request as request$1 } from "node:https";
+import { isIP } from "node:net";
+import { connect } from "node:tls";
 //#region src/shared/config.ts
 /**
 * Plugin configuration and shared constants for @fonlan/dsh-model-parameters.
@@ -121,10 +127,562 @@ function readConfig(config) {
 	};
 }
 //#endregion
+//#region src/server/system-proxy.ts
+/**
+* System-proxy discovery and transport for the models.dev catalog download.
+*
+* The harness already routes plain `fetch()` through undici's global
+* dispatcher, which resolves `http_proxy` / `https_proxy` / `all_proxy` from
+* the launch environment (`@deepseek-ai/dsh-http-proxy`). That dispatcher
+* deliberately does NOT read the operating system's proxy configuration, so on
+* a machine where the user only enabled a proxy in Windows Internet Settings or
+* macOS Network settings the catalog download went direct and failed behind the
+* proxy.
+*
+* This module supplies the missing half:
+*   1. when the environment names a proxy, defer to the harness so the existing
+*      routing (including its diagnostics and loopback bypass) is unchanged;
+*   2. otherwise read the OS proxy — Windows registry `Internet Settings`,
+*      macOS `scutil --proxy` — and tunnel the download through it with Node's
+*      own https stack (CONNECT, proxy Basic auth, redirects);
+*   3. otherwise download directly.
+*
+* Deliberate limits: SOCKS proxies and PAC scripts are never evaluated (a
+* PAC-only configuration is reported and the download stays direct — set
+* `HTTP_PROXY`/`HTTPS_PROXY` instead); a bypass entry in CIDR form
+* (`10.0.0.0/8`) is not matched; proxy credentials stored in the OS credential
+* manager are not sent.
+*/
+const PROXY_ENV_NAMES = [
+	"https_proxy",
+	"HTTPS_PROXY",
+	"http_proxy",
+	"HTTP_PROXY",
+	"all_proxy",
+	"ALL_PROXY"
+];
+/** Per-user Internet Settings key WinINET (and every proxy app that toggles "system proxy") writes. */
+const WINDOWS_INTERNET_SETTINGS = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings";
+/** How long one detection probe may take. */
+const DETECT_TIMEOUT_MS = 5e3;
+/** Redirect statuses a download follows. */
+const REDIRECT_STATUSES = /* @__PURE__ */ new Set([
+	301,
+	302,
+	303,
+	307,
+	308
+]);
+const MAX_REDIRECTS = 4;
+/** The first proxy environment variable that carries a value, if any. */
+function proxyEnvironmentName(env) {
+	return PROXY_ENV_NAMES.find((name) => (env[name] ?? "").trim() !== "");
+}
+const runCommand = (command, args, timeoutMs) => new Promise((resolve, reject) => {
+	execFile(command, args, {
+		encoding: "utf8",
+		timeout: timeoutMs,
+		windowsHide: true,
+		maxBuffer: 1048576
+	}, (error, stdout, stderr) => {
+		if (error !== null) {
+			reject(/* @__PURE__ */ new Error(`${command} ${args.join(" ")} failed: ${stderr.trim() === "" ? error.message : stderr.trim()}`));
+			return;
+		}
+		resolve(stdout);
+	});
+});
+/**
+* Parse the value table `reg query <key>` prints. Value names and the
+* `REG_*` type tokens are not localized, so the same table parses under every
+* Windows display language. Binary values (the `DefaultConnectionSettings`
+* blob) are read as empty — nothing in this module consumes them.
+*/
+function parseRegistryQuery(output) {
+	const values = /* @__PURE__ */ new Map();
+	for (const line of output.split(/\r?\n/)) {
+		const match = /^\s{2,}(\S+)\s+(REG_[A-Z_]+)\s*(.*)$/.exec(line);
+		if (match === null) continue;
+		const [, name, type, raw] = match;
+		if (type === "REG_BINARY") {
+			values.set(name, "");
+			continue;
+		}
+		values.set(name, type === "REG_DWORD" ? String(Number.parseInt(raw.trim(), 16) || 0) : raw.trim());
+	}
+	return values;
+}
+/**
+* Turn the Internet Settings values into a proxy configuration.
+* `ProxyServer` is either `host:port` (both schemes) or a
+* `http=host:port;https=host:port` list.
+* @returns the configuration, or undefined when the OS names no proxy at all.
+*/
+function windowsProxyFromRegistry(values) {
+	const enabled = (values.get("ProxyEnable") ?? "0") !== "0";
+	const server = (values.get("ProxyServer") ?? "").trim();
+	const override = windowsBypassList(values.get("ProxyOverride") ?? "");
+	const autoConfig = (values.get("AutoConfigURL") ?? "").trim();
+	const diagnostics = [];
+	const config = {
+		source: "windows",
+		noProxy: override,
+		diagnostics
+	};
+	if (enabled && server !== "") {
+		if (server.includes("=")) for (const entry of server.split(";")) {
+			const separator = entry.indexOf("=");
+			if (separator === -1) continue;
+			const scheme = entry.slice(0, separator).trim().toLowerCase();
+			const hostPort = entry.slice(separator + 1).trim();
+			if (hostPort === "") continue;
+			if (scheme !== "http" && scheme !== "https") {
+				if (scheme === "socks") diagnostics.push("Windows names a SOCKS proxy, which is not supported; the catalog download stays direct");
+				continue;
+			}
+			const url = proxyUrlFromHostPort(hostPort);
+			if (url === void 0) {
+				diagnostics.push(`Windows proxy entry "${scheme}=${hostPort}" is not a usable proxy URL; ignored`);
+				continue;
+			}
+			if (scheme === "http") config.http = url;
+			else config.https = url;
+		}
+		else {
+			const url = proxyUrlFromHostPort(server);
+			if (url === void 0) diagnostics.push(`Windows proxy server "${server}" is not a usable proxy URL; the catalog download stays direct`);
+			else {
+				config.http = url;
+				config.https = url;
+			}
+		}
+	}
+	if (autoConfig !== "") diagnostics.push("Windows uses an automatic proxy configuration (PAC) script, which is not evaluated; set HTTP_PROXY/HTTPS_PROXY to route the catalog download");
+	return config.http !== void 0 || config.https !== void 0 || diagnostics.length > 0 ? config : void 0;
+}
+/** `ProxyOverride` is `;`-separated and may carry `<local>`; our matcher consumes both forms. */
+function windowsBypassList(override) {
+	return override.split(";").map((entry) => entry.trim()).filter((entry) => entry !== "").join(",");
+}
+/** macOS `scutil --proxy` prints a flat key/value dictionary with nested arrays. */
+function parseScutilProxyOutput(output) {
+	const values = /* @__PURE__ */ new Map();
+	const exceptions = [];
+	for (const line of output.split(/\r?\n/)) {
+		const match = /^\s*([^:<]+?)\s*:\s*(.+?)\s*$/.exec(line);
+		if (match === null) continue;
+		const key = match[1].trim();
+		const value = match[2].trim();
+		if (/^\d+$/.test(key)) {
+			exceptions.push(value);
+			continue;
+		}
+		values.set(key, value);
+	}
+	const flag = (key) => values.get(key) === "1" || values.get(key) === "true";
+	const port = (key, fallback) => {
+		const value = values.get(key);
+		return value !== void 0 && /^\d+$/.test(value) ? value : String(fallback);
+	};
+	const diagnostics = [];
+	const config = {
+		source: "macos",
+		noProxy: exceptions.join(","),
+		diagnostics
+	};
+	const httpHost = values.get("HTTPProxy");
+	if (flag("HTTPEnable") && httpHost !== void 0 && httpHost !== "") config.http = `${/^https?:\/\//.test(httpHost) ? "" : "http://"}${httpHost}:${port("HTTPPort", 80)}`;
+	const httpsHost = values.get("HTTPSProxy");
+	if (flag("HTTPSEnable") && httpsHost !== void 0 && httpsHost !== "") config.https = `${/^https?:\/\//.test(httpsHost) ? "" : "http://"}${httpsHost}:${port("HTTPSPort", 443)}`;
+	if (flag("ProxyAutoConfigEnable")) diagnostics.push("macOS uses an automatic proxy configuration (PAC) file, which is not evaluated; set HTTP_PROXY/HTTPS_PROXY to route the catalog download");
+	if (flag("ProxyAutoDiscoveryEnable")) diagnostics.push("macOS runs automatic proxy discovery (WPAD), which is not evaluated; set HTTP_PROXY/HTTPS_PROXY to route the catalog download");
+	if (flag("SOCKSEnable")) diagnostics.push("macOS names a SOCKS proxy, which is not supported; the catalog download stays direct for that route");
+	return config.http !== void 0 || config.https !== void 0 || diagnostics.length > 0 ? config : void 0;
+}
+async function detectWindowsProxy(run, env, timeoutMs) {
+	const systemRoot = env.SystemRoot ?? env.SYSTEMROOT;
+	const executable = systemRoot !== void 0 && existsSync(join(systemRoot, "System32", "reg.exe")) ? join(systemRoot, "System32", "reg.exe") : "reg";
+	let output;
+	try {
+		output = await run(executable, ["query", WINDOWS_INTERNET_SETTINGS], timeoutMs);
+	} catch {
+		return;
+	}
+	return windowsProxyFromRegistry(parseRegistryQuery(output));
+}
+async function detectMacProxy(run, timeoutMs) {
+	let output;
+	try {
+		output = await run("scutil", ["--proxy"], timeoutMs);
+	} catch {
+		return;
+	}
+	return parseScutilProxyOutput(output);
+}
+/**
+* Read the operating system's proxy configuration (never the environment).
+* Linux has no portable API for this; its users configure the environment,
+* which the harness routes.
+* @param options - platform, probe runner and timeout (tests pin all three).
+* @returns the detected configuration, or undefined when the OS names none.
+*/
+async function detectSystemProxy(options = {}) {
+	const platform = options.platform ?? process.platform;
+	const env = options.env ?? process.env;
+	const run = options.run ?? runCommand;
+	const timeoutMs = options.timeoutMs ?? DETECT_TIMEOUT_MS;
+	if (platform === "win32") return detectWindowsProxy(run, env, timeoutMs);
+	if (platform === "darwin") return detectMacProxy(run, timeoutMs);
+}
+/** A host this machine owns: a proxy cannot reach it, so it always goes direct. */
+function isLoopbackHost(hostname) {
+	const host = hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+	if (host === "localhost" || host.endsWith(".localhost")) return true;
+	if (host === "::1" || host === "::" || host === "0.0.0.0") return true;
+	return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+/** Split `host:port`, `[::1]:port` or a bare IPv6 literal without reading `::1` as host `:port`. */
+function splitHostPort(entry) {
+	if (entry.startsWith("[")) {
+		const close = entry.indexOf("]");
+		if (close !== -1) {
+			const rest = entry.slice(close + 1);
+			const host = entry.slice(1, close);
+			return rest.startsWith(":") ? {
+				host,
+				port: rest.slice(1)
+			} : { host };
+		}
+	}
+	const colon = entry.indexOf(":");
+	if (colon !== -1 && entry.indexOf(":", colon + 1) === -1) return {
+		host: entry.slice(0, colon),
+		port: entry.slice(colon + 1)
+	};
+	return { host: entry };
+}
+/** `*` / `?` entries appear in OS bypass lists (`10.*`, `*.corp`); CIDR does not. */
+function globMatch(pattern, host) {
+	const source = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+	return new RegExp(`^${source}$`).test(host);
+}
+/**
+* Decide whether a bypass list exempts one URL. Semantics follow the harness's
+* own matcher — an entry covers its subdomains, a leading `.`/`*.` means the
+* same, an entry may carry a `:port`, `*` bypasses everything — plus the two
+* forms OS lists add: `host*` wildcards and `<local>` (a dotless hostname).
+* Loopback is always bypassed. CIDR notation is not matched.
+*/
+function shouldBypassProxy(noProxy, url) {
+	const host = url.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+	if (isLoopbackHost(host)) return true;
+	const port = url.port !== "" ? url.port : url.protocol === "https:" ? "443" : "80";
+	for (const raw of noProxy.split(/[,\s;]+/)) {
+		const entry = raw.trim().toLowerCase();
+		if (entry === "") continue;
+		if (entry === "*") return true;
+		if (entry === "<local>") {
+			if (!host.includes(".")) return true;
+			continue;
+		}
+		const split = splitHostPort(entry);
+		if (split.port !== void 0 && split.port !== port) continue;
+		const candidate = split.host.replace(/^\*?\./, "").replace(/\.$/, "");
+		if (candidate === "") continue;
+		if (candidate.includes("*") || candidate.includes("?")) {
+			if (globMatch(candidate, host)) return true;
+			continue;
+		}
+		if (host === candidate || host.endsWith(`.${candidate}`)) return true;
+	}
+	return false;
+}
+/**
+* Decide how the catalog download for `target` is routed: defer to the harness
+* for environment proxies, tunnel a detected OS proxy, or go direct. The OS is
+* consulted only when the environment names no proxy, so an exported variable
+* keeps winning exactly as it does for the rest of the harness.
+*/
+async function resolveCatalogRoute(target, options = {}) {
+	const url = typeof target === "string" ? new URL(target) : target;
+	const env = options.env ?? process.env;
+	if (proxyEnvironmentName(env) !== void 0) return {
+		tunnel: false,
+		source: "env",
+		noProxy: (env.no_proxy ?? env.NO_PROXY ?? "").trim(),
+		diagnostics: []
+	};
+	const detected = await detectSystemProxy(options);
+	if (detected === void 0) return {
+		tunnel: false,
+		source: "none",
+		noProxy: "",
+		diagnostics: []
+	};
+	const noProxy = detected.noProxy ?? "";
+	const proxy = url.protocol === "https:" ? detected.https : detected.http;
+	const diagnostics = [...detected.diagnostics];
+	if (proxy === void 0) {
+		if ((url.protocol === "https:" ? detected.http : detected.https) !== void 0) {
+			const missing = url.protocol === "https:" ? "HTTPS" : "HTTP";
+			const present = url.protocol === "https:" ? "HTTP" : "HTTPS";
+			diagnostics.push(`${detected.source === "windows" ? "Windows" : "macOS"} configures an ${present} proxy but no ${missing} proxy; the catalog download connects directly`);
+		}
+		return {
+			tunnel: false,
+			source: detected.source,
+			noProxy,
+			diagnostics
+		};
+	}
+	if (shouldBypassProxy(noProxy, url)) return {
+		tunnel: false,
+		source: detected.source,
+		noProxy,
+		diagnostics
+	};
+	return {
+		tunnel: true,
+		proxy,
+		source: detected.source,
+		noProxy,
+		diagnostics
+	};
+}
+/** Strip any proxy credentials before the route crosses the settings API or logs. */
+function maskProxyUrl(proxy) {
+	try {
+		const url = new URL(proxy);
+		url.username = "";
+		url.password = "";
+		return `${url.protocol}//${url.host}`;
+	} catch {
+		return;
+	}
+}
+/** Describe a route for the settings page. */
+function transportOf(route) {
+	if (route.tunnel && route.proxy !== void 0) return {
+		kind: route.source === "windows" ? "windows" : route.source === "macos" ? "macos" : "env",
+		proxy: maskProxyUrl(route.proxy)
+	};
+	if (route.source === "env") return { kind: "env" };
+	return { kind: "direct" };
+}
+function describeTransport(transport) {
+	switch (transport.kind) {
+		case "env": return "environment proxy variables (routed by the harness)";
+		case "windows": return `Windows system proxy ${transport.proxy ?? ""}`.trim();
+		case "macos": return `macOS system proxy ${transport.proxy ?? ""}`.trim();
+		default: return "direct (no system proxy)";
+	}
+}
+function proxyUrlFromHostPort(value) {
+	try {
+		const parsed = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : `http://${value}`);
+		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return void 0;
+		if (parsed.hostname === "") return void 0;
+		return `${parsed.protocol}//${parsed.host}`;
+	} catch {
+		return;
+	}
+}
+function errorMessage(error) {
+	if (!(error instanceof Error)) return String(error);
+	const cause = error.cause;
+	if (cause instanceof Error && cause.message !== "" && !error.message.includes(cause.message)) return `${error.message}: ${cause.message}`;
+	return error.message;
+}
+async function fetchJsonDirect(url, timeoutMs) {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), timeoutMs);
+	try {
+		const response = await fetch(url, {
+			signal: controller.signal,
+			headers: { accept: "application/json" }
+		});
+		if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
+		return await response.json();
+	} catch (error) {
+		if (controller.signal.aborted) throw new Error(`catalog download timed out after ${timeoutMs}ms`);
+		throw new Error(errorMessage(error));
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/** A URL hostname without the brackets WHATWG puts around IPv6 literals. */
+function bareHostname(hostname) {
+	return hostname.replace(/^\[|\]$/g, "");
+}
+/** Open a CONNECT tunnel to `host:port` through the proxy, authenticating when the URL carries credentials. */
+function openProxyTunnel(proxy, host, port, timeoutMs) {
+	const authority = `${isIP(host) === 6 ? `[${host}]` : host}:${port}`;
+	const headers = { host: authority };
+	if (proxy.username !== "" || proxy.password !== "") {
+		const credentials = `${decodeURIComponent(proxy.username)}:${decodeURIComponent(proxy.password)}`;
+		headers["proxy-authorization"] = `Basic ${Buffer.from(credentials).toString("base64")}`;
+	}
+	const secureProxy = proxy.protocol === "https:";
+	const connectRequest = (secureProxy ? request$1 : request)({
+		host: bareHostname(proxy.hostname),
+		port: Number(proxy.port) || (secureProxy ? 443 : 80),
+		method: "CONNECT",
+		path: authority,
+		headers,
+		agent: false,
+		timeout: timeoutMs
+	});
+	return new Promise((resolve, reject) => {
+		connectRequest.once("connect", (response, socket, head) => {
+			if (response.statusCode !== 200) {
+				socket.destroy();
+				reject(/* @__PURE__ */ new Error(`proxy ${bareHostname(proxy.hostname)} refused CONNECT with HTTP ${response.statusCode ?? 0}`));
+				return;
+			}
+			if (head.length > 0) socket.unshift(head);
+			resolve(socket);
+		});
+		connectRequest.once("timeout", () => {
+			connectRequest.destroy(/* @__PURE__ */ new Error(`proxy CONNECT timed out after ${timeoutMs}ms`));
+		});
+		connectRequest.once("error", (error) => reject(error));
+		connectRequest.end();
+	});
+}
+/** An https agent whose every socket is a TLS session opened inside a proxy tunnel. */
+var ProxyTunnelAgent = class extends Agent {
+	proxy;
+	timeoutMs;
+	constructor(proxy, timeoutMs) {
+		super({
+			keepAlive: false,
+			maxSockets: 1
+		});
+		this.proxy = proxy;
+		this.timeoutMs = timeoutMs;
+	}
+	createConnection(options, callback) {
+		const host = typeof options.host === "string" ? options.host : "";
+		const port = Number(options.port ?? 443);
+		const servername = options.servername;
+		this.open(host, port, typeof servername === "string" ? servername : void 0).then((socket) => callback?.(null, socket), (error) => callback?.(error instanceof Error ? error : new Error(String(error)), void 0));
+	}
+	async open(host, port, servername) {
+		const raw = await openProxyTunnel(this.proxy, host, port, this.timeoutMs);
+		const sni = servername !== void 0 && isIP(servername) === 0 ? servername : isIP(host) === 0 ? host : void 0;
+		const secure = connect({
+			socket: raw,
+			servername: sni
+		});
+		await new Promise((resolve, reject) => {
+			secure.once("secureConnect", () => resolve());
+			secure.once("error", (error) => reject(error));
+		});
+		return secure;
+	}
+};
+/** One HTTPS GET through the tunnel; the whole exchange (connect included) is bounded by `timeoutMs`. */
+function requestThroughTunnel(target, proxy, timeoutMs) {
+	return new Promise((resolve, reject) => {
+		const agent = new ProxyTunnelAgent(proxy, timeoutMs);
+		let settled = false;
+		let request;
+		const finish = (error, value) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			request?.destroy();
+			agent.destroy();
+			if (error === null && value !== void 0) resolve(value);
+			else reject(error ?? /* @__PURE__ */ new Error("catalog download failed"));
+		};
+		const timer = setTimeout(() => finish(/* @__PURE__ */ new Error(`catalog download timed out after ${timeoutMs}ms`)), timeoutMs);
+		request = request$1(target, {
+			agent,
+			method: "GET",
+			headers: {
+				accept: "application/json",
+				"accept-encoding": "identity"
+			}
+		});
+		request.once("response", (response) => {
+			const chunks = [];
+			response.on("data", (chunk) => chunks.push(chunk));
+			response.once("end", () => {
+				finish(null, {
+					status: response.statusCode ?? 0,
+					statusText: response.statusMessage ?? "",
+					headers: response.headers,
+					body: Buffer.concat(chunks).toString("utf8")
+				});
+			});
+			response.once("error", (error) => finish(error));
+		});
+		request.once("error", (error) => finish(error));
+		request.end();
+	});
+}
+/**
+* Download and parse one HTTPS JSON document through an `http(s)://` proxy,
+* following redirects. Throws on a non-2xx answer, a malformed body, or a
+* transport timeout so callers keep the previously cached catalog.
+*/
+async function fetchJsonViaProxy(url, proxy, timeoutMs) {
+	let proxyUrl;
+	try {
+		proxyUrl = new URL(proxy);
+	} catch {
+		throw new Error(`proxy URL "${maskProxyUrl(proxy) ?? "invalid"}" is not a URL`);
+	}
+	if (proxyUrl.protocol !== "http:" && proxyUrl.protocol !== "https:") throw new Error(`proxy URL "${maskProxyUrl(proxy) ?? "invalid"}" uses ${proxyUrl.protocol}//, which is not supported`);
+	let current = new URL(url);
+	for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+		if (current.protocol !== "https:") throw new Error(`proxy transport supports https targets only (got ${current.protocol}//)`);
+		const response = await requestThroughTunnel(current, proxyUrl, timeoutMs);
+		if (REDIRECT_STATUSES.has(response.status)) {
+			const location = response.headers.location;
+			if (typeof location !== "string" || location === "") throw new Error(`HTTP ${response.status} redirect without a Location header`);
+			current = new URL(location, current);
+			continue;
+		}
+		if (response.status < 200 || response.status >= 300) throw new Error(`HTTP ${response.status}${response.statusText === "" ? "" : ` ${response.statusText}`}`);
+		return JSON.parse(response.body);
+	}
+	throw new Error("too many redirects while downloading the catalog");
+}
+/**
+* Download the catalog for the settings page: defer to the harness when the
+* environment names a proxy, otherwise tunnel a detected OS proxy, otherwise
+* fetch directly. Never throws for routing reasons — transport failures do
+* throw, and the caller keeps its cached copy.
+* @param options - detection overrides; production passes nothing, tests pin
+*   the platform and its OS probes.
+*/
+async function fetchJsonWithSystemProxy(url, timeoutMs, logger, options = {}) {
+	const route = await resolveCatalogRoute(url, options);
+	for (const diagnostic of route.diagnostics) logger?.warn(`model-parameters: ${diagnostic}`);
+	const transport = transportOf(route);
+	logger?.info(`model-parameters: catalog download via ${describeTransport(transport)}`);
+	try {
+		return {
+			body: route.tunnel && route.proxy !== void 0 && new URL(url).protocol === "https:" ? await fetchJsonViaProxy(url, route.proxy, timeoutMs) : await fetchJsonDirect(url, timeoutMs),
+			transport
+		};
+	} catch (error) {
+		const wrapped = error instanceof Error ? error : new Error(String(error));
+		wrapped.transport = transport;
+		throw wrapped;
+	}
+}
+//#endregion
 //#region src/server/catalog.ts
 /**
 * models.dev catalog: fetch, disk cache, lazy TTL refresh, and id matching.
 *
+* The download goes through {@link fetchJsonWithSystemProxy}, so it follows the
+* proxy environment the harness already routes (unchanged) and, when no proxy
+* variable is set, the operating system's proxy — see system-proxy.ts.
+*
 * The catalog is flattened into a list of entries keyed by provider, then
 * indexed by the last path segment of the model id (case-insensitive) so a
 * synced bare id like `qwen3.7-max` can resolve `Qwen/Qwen3.7-Max` wherever
@@ -160,16 +718,24 @@ var CatalogManager = class {
 	};
 	loaded = false;
 	inflight = null;
+	transport;
+	fetchError;
 	dir;
 	cachePath;
-	constructor(logger, dataDir) {
+	fetchJson;
+	constructor(logger, dataDir, fetchJson) {
 		this.logger = logger;
 		this.dir = dataDir ?? join(homedir(), ".dsh", "model-parameters");
 		this.cachePath = join(this.dir, "catalog.json");
+		this.fetchJson = fetchJson ?? ((url, timeoutMs) => fetchJsonWithSystemProxy(url, timeoutMs, logger));
 	}
-	/** The current snapshot (empty until the first load/fetch completes). */
+	/** The current snapshot, including the route and error of the last download attempt. */
 	snapshotOf() {
-		return this.snapshot;
+		return {
+			...this.snapshot,
+			transport: this.transport,
+			error: this.fetchError
+		};
 	}
 	/**
 	* Load the disk cache once, then fetch when stale (or `force`). A failed
@@ -189,8 +755,13 @@ var CatalogManager = class {
 			await this.inflight;
 			return true;
 		}
-		this.inflight = this.fetchAndPersist().catch((error) => {
-			this.logger.warn(`model-parameters: catalog fetch failed (${error instanceof Error ? error.message : String(error)}); using cached copy`);
+		this.inflight = this.fetchAndPersist().then(() => {
+			this.fetchError = void 0;
+		}).catch((error) => {
+			this.fetchError = error instanceof Error ? error.message : String(error);
+			const attempted = error.transport;
+			if (attempted !== void 0) this.transport = attempted;
+			this.logger.warn(`model-parameters: catalog fetch failed (${this.fetchError}); using cached copy`);
 		}).finally(() => {
 			this.inflight = null;
 		});
@@ -256,27 +827,18 @@ var CatalogManager = class {
 		}
 	}
 	async fetchAndPersist() {
-		const controller = new AbortController();
-		const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-		let response;
-		try {
-			response = await fetch(CATALOG_URL, {
-				signal: controller.signal,
-				headers: { accept: "application/json" }
-			});
-		} finally {
-			clearTimeout(timer);
-		}
-		if (!response.ok) throw new Error(`HTTP ${response.status} ${response.statusText}`);
-		const body = await response.json();
+		const { body, transport } = await this.fetchJson(CATALOG_URL, FETCH_TIMEOUT_MS);
+		if (typeof body !== "object" || body === null) throw new Error("catalog response is not a JSON object");
+		const document = body;
 		const fetchedAt = Date.now();
-		this.snapshot = this.buildSnapshot(body, fetchedAt);
+		this.snapshot = this.buildSnapshot(document, fetchedAt);
 		await mkdir(this.dir, { recursive: true });
 		const doc = {
 			fetchedAt,
-			body
+			body: document
 		};
 		await writeFile(this.cachePath, JSON.stringify(doc), "utf8");
+		this.transport = transport;
 		this.logger.info(`model-parameters: catalog refreshed from models.dev (${this.snapshot.providers} providers, ${this.snapshot.entries.length} models)`);
 	}
 	buildSnapshot(body, fetchedAt) {
@@ -666,7 +1228,9 @@ function stateOf(service) {
 			providers: snapshot.providers,
 			fetchedAt: snapshot.fetchedAt,
 			fresh: snapshot.fetchedAt > 0 && Date.now() - snapshot.fetchedAt < config.ttlDays * 24 * 60 * 60 * 1e3,
-			ttlDays: config.ttlDays
+			ttlDays: config.ttlDays,
+			transport: snapshot.transport ?? null,
+			error: snapshot.error ?? null
 		},
 		report: service.report()
 	};
@@ -686,4 +1250,4 @@ function apply(ctx, config = {}) {
 	});
 }
 //#endregion
-export { CatalogManager, Config, acceptedInputModalities, apply, identityReasoningEfforts, inject, name };
+export { CatalogManager, Config, acceptedInputModalities, apply, detectSystemProxy, fetchJsonViaProxy, fetchJsonWithSystemProxy, identityReasoningEfforts, inject, isLoopbackHost, maskProxyUrl, name, parseRegistryQuery, parseScutilProxyOutput, resolveCatalogRoute, shouldBypassProxy, transportOf, windowsProxyFromRegistry };

package/lib/types/index.d.ts

@@ -12,9 +12,12 @@
 import type { Context } from '@deepseek-ai/cordis';
 import { Config, type ModelParametersLiveConfig } from './shared/config.js';
 import { CatalogManager, acceptedInputModalities, identityReasoningEfforts, type CatalogEntry, type CatalogSnapshot } from './server/catalog.js';
+import { detectSystemProxy, fetchJsonViaProxy, fetchJsonWithSystemProxy, isLoopbackHost, maskProxyUrl, parseRegistryQuery, parseScutilProxyOutput, resolveCatalogRoute, shouldBypassProxy, transportOf, windowsProxyFromRegistry, type CatalogFetch, type CatalogFetchResult, type CatalogRoute, type CatalogTransport, type CommandRunner, type DetectOptions, type SystemProxyConfig } from './server/system-proxy.js';
 export declare const name = "@fonlan/dsh-model-parameters";
 export declare const inject: string[];
 export { Config };
 export { CatalogManager, acceptedInputModalities, identityReasoningEfforts };
 export type { CatalogEntry, CatalogSnapshot };
+export { detectSystemProxy, fetchJsonViaProxy, fetchJsonWithSystemProxy, isLoopbackHost, maskProxyUrl, parseRegistryQuery, parseScutilProxyOutput, resolveCatalogRoute, shouldBypassProxy, transportOf, windowsProxyFromRegistry, };
+export type { CatalogFetch, CatalogFetchResult, CatalogRoute, CatalogTransport, CommandRunner, DetectOptions, SystemProxyConfig, };
 export declare function apply(ctx: Context, config?: ModelParametersLiveConfig): void;