@camstack/system 1.0.6 → 1.0.8

package/dist/model-download-service-JtVQtbb6.js

@@ -0,0 +1,752 @@
+const require_chunk = require("./chunk-Cek0wNdY.js");
+let node_http = require("node:http");
+let node_fs = require("node:fs");
+node_fs = require_chunk.__toESM(node_fs);
+let node_path = require("node:path");
+node_path = require_chunk.__toESM(node_path);
+let node_crypto = require("node:crypto");
+//#region src/http/authenticated-file-server.ts
+/**
+* Authenticated data-plane file-server — a shared host primitive for addons that
+* must serve files (media segments, scrub-frame stores, exported clips) directly
+* to browsers/players, node-direct (NOT through the hub tRPC, per the recording
+* design's "no media bytes traverse the hub").
+*
+* It bundles the three things every such server needs so addons don't re-roll
+* them: CORS (the data plane is cross-origin from the admin-ui — a native
+* `<video src>` is exempt but hls.js / WebCodecs fetch via XHR and are blocked
+* without it), HTTP `Range` (seeking / partial fetch), and a SCOPED TOKEN check.
+*
+* The token rides as the FIRST path segment (`<urlPrefix><token>/<relPath>`) so
+* a player resolving a manifest's RELATIVE child URIs carries it on every
+* sub-request automatically — no per-URI rewriting, no cookies/headers a dumb
+* player can't set. The caller supplies `verifyToken(token, relPath)`; the
+* primitive stays auth-scheme-agnostic.
+*
+* Pure helpers (`parseTokenizedUrl`, `resolveFilePath`, `contentTypeFor`,
+* `parseRangeHeader`) are exported for unit testing; `createAuthenticatedFileServer`
+* is the thin `node:http` glue.
+*/
+function corsHeaders(origin) {
+	return {
+		"access-control-allow-origin": origin,
+		"access-control-allow-methods": "GET, HEAD, OPTIONS",
+		"access-control-allow-headers": "range",
+		"access-control-expose-headers": "content-length, content-range, accept-ranges",
+		"access-control-max-age": "86400"
+	};
+}
+/**
+* Split a request URL (`<urlPrefix><token>/<relPath>`) into its token + rel
+* path. Returns null for anything outside the prefix or missing either part.
+* `relPath` is URL-decoded; a decode failure → null.
+*/
+function parseTokenizedUrl(urlPrefix, urlPath) {
+	if (!urlPath.startsWith(urlPrefix)) return null;
+	const after = urlPath.slice(urlPrefix.length);
+	const slash = after.indexOf("/");
+	if (slash <= 0) return null;
+	const token = after.slice(0, slash);
+	let rel;
+	try {
+		rel = decodeURIComponent(after.slice(slash + 1));
+	} catch {
+		return null;
+	}
+	if (rel.length === 0) return null;
+	return {
+		token,
+		rel
+	};
+}
+/**
+* Map a rel path to one candidate absolute path PER root, keeping only roots the
+* path stays within (traversal guard). The handler serves the first candidate
+* that exists. Rejects a path that escapes every root.
+*/
+function resolveFilePath(roots, rel) {
+	if (rel.length === 0) return { error: "forbidden" };
+	const candidates = [];
+	for (const rootDir of roots) {
+		const root = node_path.default.resolve(rootDir);
+		const abs = node_path.default.resolve(root, rel);
+		if (abs === root || abs.startsWith(root + node_path.default.sep)) candidates.push(abs);
+	}
+	if (candidates.length === 0) return { error: "forbidden" };
+	return { candidates };
+}
+var DEFAULT_CONTENT_TYPES = {
+	".m3u8": "application/vnd.apple.mpegurl",
+	".m4s": "video/mp4",
+	".mp4": "video/mp4",
+	".idx": "application/octet-stream",
+	".html": "text/html; charset=utf-8",
+	".js": "application/javascript; charset=utf-8",
+	".mjs": "application/javascript; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".map": "application/json; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".ico": "image/x-icon",
+	".woff2": "font/woff2",
+	".woff": "font/woff",
+	".ttf": "font/ttf"
+};
+function contentTypeFor(filePath, overrides) {
+	const ext = node_path.default.extname(filePath).toLowerCase();
+	return overrides?.[ext] ?? DEFAULT_CONTENT_TYPES[ext] ?? "application/octet-stream";
+}
+/** Parse an HTTP `Range` header against a known size. Null = serve whole file. */
+function parseRangeHeader(header, size) {
+	if (!header) return null;
+	const m = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+	if (!m) return null;
+	const [, rawStart, rawEnd] = m;
+	if (rawStart === "" && rawEnd === "") return null;
+	let start;
+	let end;
+	if (rawStart === "") {
+		const n = Number(rawEnd);
+		if (n <= 0) return null;
+		start = Math.max(0, size - n);
+		end = size - 1;
+	} else {
+		start = Number(rawStart);
+		end = rawEnd === "" ? size - 1 : Number(rawEnd);
+	}
+	if (!Number.isFinite(start) || !Number.isFinite(end) || start > end || start >= size) return null;
+	return {
+		start,
+		end: Math.min(end, size - 1)
+	};
+}
+/**
+* Start an authenticated file-server. Returns the bound port so the caller can
+* build URLs. `getRoots`/`verifyToken` are invoked per request, so they always
+* reflect the live config.
+*/
+async function createAuthenticatedFileServer(opts) {
+	const cors = corsHeaders(opts.corsOrigin ?? "*");
+	const server = (0, node_http.createServer)((req, res) => {
+		handle(opts, cors, req, res);
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(opts.port, () => resolve());
+	});
+	const addr = server.address();
+	return {
+		port: typeof addr === "object" && addr ? addr.port : opts.port,
+		close: () => new Promise((resolve) => server.close(() => resolve()))
+	};
+}
+async function handle(opts, cors, req, res) {
+	if (req.method === "OPTIONS") {
+		res.writeHead(204, cors).end();
+		return;
+	}
+	if (req.method !== "GET" && req.method !== "HEAD") {
+		res.writeHead(405, cors).end();
+		return;
+	}
+	const urlPath = (req.url ?? "").split("?")[0] ?? "";
+	const parsed = parseTokenizedUrl(opts.urlPrefix, urlPath);
+	if (!parsed) {
+		res.writeHead(403, cors).end();
+		return;
+	}
+	if (!opts.verifyToken(parsed.token, parsed.rel)) {
+		res.writeHead(401, cors).end();
+		return;
+	}
+	const resolved = resolveFilePath(opts.getRoots(), parsed.rel);
+	if ("error" in resolved) {
+		res.writeHead(403, cors).end();
+		return;
+	}
+	let absPath = null;
+	let size = 0;
+	for (const candidate of resolved.candidates) try {
+		const st = await node_fs.promises.stat(candidate);
+		if (st.isFile()) {
+			absPath = candidate;
+			size = st.size;
+			break;
+		}
+	} catch {}
+	if (absPath === null) {
+		res.writeHead(404, cors).end();
+		return;
+	}
+	const baseHeaders = {
+		...cors,
+		"content-type": contentTypeFor(absPath, opts.contentTypes),
+		"accept-ranges": "bytes",
+		"cache-control": "no-cache"
+	};
+	const range = parseRangeHeader(req.headers.range, size);
+	if (range) {
+		res.writeHead(206, {
+			...baseHeaders,
+			"content-range": `bytes ${range.start}-${range.end}/${size}`,
+			"content-length": String(range.end - range.start + 1)
+		});
+		if (req.method === "HEAD") {
+			res.end();
+			return;
+		}
+		(0, node_fs.createReadStream)(absPath, {
+			start: range.start,
+			end: range.end
+		}).pipe(res);
+		return;
+	}
+	res.writeHead(200, {
+		...baseHeaders,
+		"content-length": String(size)
+	});
+	if (req.method === "HEAD") {
+		res.end();
+		return;
+	}
+	(0, node_fs.createReadStream)(absPath).pipe(res);
+}
+//#endregion
+//#region src/http/file-data-plane.ts
+/**
+* A ready-made data-plane request handler that serves files from a set of roots
+* with HTTP `Range`, for addons whose data-plane is "stream files off disk"
+* (recording playback, scrub-frame stores, exported clips).
+*
+* This is the addon-side handler the addon hands to `ctx.dataPlane.serve({ handler })`.
+* It receives the REAL Node `req`/`res`, resolves the request path against the
+* addon's roots (traversal-guarded), and streams the file. NO token and NO CORS:
+* the hub already authenticated the caller and the data plane is same-origin
+* through the hub's port. Reuses the shared Range/content-type/traversal helpers
+* so there is one implementation across the standalone file-server and this.
+*/
+/** Build a `(req, res)` handler that serves `getRoots()` files with Range. */
+function createFileDataPlaneHandler(opts) {
+	return async (req, res) => {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			res.writeHead(405).end();
+			return;
+		}
+		const urlPath = (req.url ?? "/").split("?")[0] ?? "/";
+		let rel;
+		try {
+			rel = decodeURIComponent(urlPath.replace(/^\/+/, ""));
+		} catch {
+			res.writeHead(400).end();
+			return;
+		}
+		if (rel.length === 0) {
+			res.writeHead(404).end();
+			return;
+		}
+		const resolved = resolveFilePath(opts.getRoots(), rel);
+		if ("error" in resolved) {
+			res.writeHead(403).end();
+			return;
+		}
+		let absPath = null;
+		let size = 0;
+		for (const candidate of resolved.candidates) try {
+			const st = await node_fs.promises.stat(candidate);
+			if (st.isFile()) {
+				absPath = candidate;
+				size = st.size;
+				break;
+			}
+		} catch {}
+		if (absPath === null) {
+			res.writeHead(404).end();
+			return;
+		}
+		const baseHeaders = {
+			"content-type": contentTypeFor(absPath, opts.contentTypes),
+			"accept-ranges": "bytes",
+			"cache-control": "no-cache"
+		};
+		const range = parseRangeHeader(req.headers.range, size);
+		if (range) {
+			res.writeHead(206, {
+				...baseHeaders,
+				"content-range": `bytes ${range.start}-${range.end}/${size}`,
+				"content-length": String(range.end - range.start + 1)
+			});
+			if (req.method === "HEAD") {
+				res.end();
+				return;
+			}
+			(0, node_fs.createReadStream)(absPath, {
+				start: range.start,
+				end: range.end
+			}).pipe(res);
+			return;
+		}
+		res.writeHead(200, {
+			...baseHeaders,
+			"content-length": String(size)
+		});
+		if (req.method === "HEAD") {
+			res.end();
+			return;
+		}
+		(0, node_fs.createReadStream)(absPath).pipe(res);
+	};
+}
+//#endregion
+//#region src/download/model-downloader.ts
+/** Build fetch headers, including HF auth token for huggingface.co URLs */
+function buildHeaders(url) {
+	const headers = { "User-Agent": "CamStack/1.0" };
+	const hfToken = process.env["HF_TOKEN"] ?? process.env["HUGGING_FACE_HUB_TOKEN"];
+	if (hfToken && url.includes("huggingface.co")) headers["Authorization"] = `Bearer ${hfToken}`;
+	return headers;
+}
+/**
+* Download a single file from a URL to a destination path.
+* Uses native fetch() (Node 22+) which handles redirects natively.
+* Streams to disk with optional progress callback.
+* Returns the destination path. Skips download if file already exists.
+*/
+async function downloadFile(url, destPath, onProgress) {
+	if (node_fs.existsSync(destPath)) return destPath;
+	node_fs.mkdirSync(node_path.dirname(destPath), { recursive: true });
+	const tmpPath = destPath + ".downloading";
+	try {
+		const response = await fetch(url, {
+			redirect: "follow",
+			headers: buildHeaders(url)
+		});
+		if (!response.ok) throw new Error(`HTTP ${response.status} downloading ${url}`);
+		if (!response.body) throw new Error(`No response body from ${url}`);
+		const total = parseInt(response.headers.get("content-length") ?? "0", 10);
+		let downloaded = 0;
+		const fileStream = node_fs.createWriteStream(tmpPath);
+		const reader = response.body.getReader();
+		try {
+			for (;;) {
+				const { done, value } = await reader.read();
+				if (done || !value) break;
+				fileStream.write(value);
+				downloaded += value.length;
+				onProgress?.(downloaded, total);
+			}
+		} finally {
+			fileStream.end();
+			await new Promise((resolve, reject) => {
+				fileStream.on("finish", resolve);
+				fileStream.on("error", reject);
+			});
+		}
+		node_fs.renameSync(tmpPath, destPath);
+		return destPath;
+	} catch (err) {
+		try {
+			node_fs.unlinkSync(tmpPath);
+		} catch {}
+		throw err;
+	}
+}
+/**
+* Fetch JSON from a URL using native fetch().
+*/
+async function fetchJson(url) {
+	const response = await fetch(url, {
+		redirect: "follow",
+		headers: buildHeaders(url)
+	});
+	if (!response.ok) throw new Error(`HTTP ${response.status} fetching ${url}`);
+	return response.json();
+}
+/**
+* Download a model with fallback URLs and optional SHA256 verification.
+* Legacy API preserved for backward compatibility -- delegates to downloadFile().
+*/
+async function downloadModel(options) {
+	const { url, fallbackUrls = [], destDir, filename, expectedSha256, onProgress } = options;
+	const fname = filename ?? url.split("/").pop() ?? "model.bin";
+	const destPath = node_path.join(destDir, fname);
+	if (node_fs.existsSync(destPath)) return {
+		filePath: destPath,
+		downloadedBytes: 0,
+		fromCache: true
+	};
+	node_fs.mkdirSync(destDir, { recursive: true });
+	const urls = [url, ...fallbackUrls];
+	let lastError = null;
+	for (const tryUrl of urls) try {
+		await downloadFile(tryUrl, destPath, onProgress);
+		if (expectedSha256) {
+			const hash = await computeSha256(destPath);
+			if (hash !== expectedSha256) {
+				node_fs.unlinkSync(destPath);
+				throw new Error(`SHA256 mismatch: expected ${expectedSha256}, got ${hash}`);
+			}
+		}
+		return {
+			filePath: destPath,
+			downloadedBytes: node_fs.statSync(destPath).size,
+			fromCache: false
+		};
+	} catch (e) {
+		lastError = e;
+		if (node_fs.existsSync(destPath)) node_fs.unlinkSync(destPath);
+	}
+	throw lastError ?? /* @__PURE__ */ new Error(`Failed to download model from ${url}`);
+}
+async function computeSha256(filePath) {
+	return new Promise((resolve, reject) => {
+		const hash = (0, node_crypto.createHash)("sha256");
+		const stream = node_fs.createReadStream(filePath);
+		stream.on("data", (chunk) => hash.update(chunk));
+		stream.on("end", () => resolve(hash.digest("hex")));
+		stream.on("error", reject);
+	});
+}
+/**
+* Download every file in a HuggingFace directory bundle (e.g.,
+* `.mlpackage` / OpenVINO IR pair) atomically. `knownFiles` lists the
+* relative paths inside the directory; the function fetches each from
+* `${url}/${file}` and renames the staging directory only on full
+* success. Mirrors `ModelDownloadService.downloadDirectory` but
+* exposed as a standalone for catalog-less callers.
+*/
+async function downloadDirectory(url, destDir, knownFiles, onProgress) {
+	const match = url.match(/huggingface\.co\/([^/]+\/[^/]+)\/resolve\/main\/(.+)/);
+	if (!match) throw new Error(`Cannot parse HuggingFace URL: ${url}`);
+	const [, repo, dirPath] = match;
+	const files = (knownFiles ?? []).map((f) => ({
+		relativePath: f,
+		fileUrl: `https://huggingface.co/${repo}/resolve/main/${dirPath}/${f}`
+	}));
+	if (files.length === 0) throw new Error(`Directory bundle requires explicit \`files\` list (got none for ${url})`);
+	const tmpDir = destDir + ".downloading";
+	node_fs.rmSync(tmpDir, {
+		recursive: true,
+		force: true
+	});
+	node_fs.mkdirSync(tmpDir, { recursive: true });
+	let totalDownloaded = 0;
+	try {
+		for (const file of files) {
+			const destPath = node_path.join(tmpDir, file.relativePath);
+			node_fs.mkdirSync(node_path.dirname(destPath), { recursive: true });
+			await downloadFile(file.fileUrl, destPath, (downloaded, _total) => {
+				onProgress?.(totalDownloaded + downloaded, void 0);
+			});
+			totalDownloaded += node_fs.statSync(destPath).size;
+		}
+		node_fs.rmSync(destDir, {
+			recursive: true,
+			force: true
+		});
+		node_fs.renameSync(tmpDir, destDir);
+	} catch (err) {
+		node_fs.rmSync(tmpDir, {
+			recursive: true,
+			force: true
+		});
+		throw err;
+	}
+}
+/**
+* Resolve a `ModelCatalogEntry` against `modelsDir`: download model file
+* (or directory bundle) + extra files (labels JSON, charset dict, …),
+* skip if already on disk. Returns the local model path.
+*/
+async function ensureModel(modelsDir, entry, format, onProgress) {
+	const formatEntry = entry.formats[format];
+	if (!formatEntry) throw new Error(`Model "${entry.id}" has no ${format} format. Available: ${Object.keys(entry.formats).join(", ")}`);
+	if (entry.extraFiles) for (const extra of entry.extraFiles) await downloadFile(extra.url, node_path.join(modelsDir, extra.filename));
+	const filename = formatEntry.url.split("/").pop() ?? `${entry.id}.${format}`;
+	const modelPath = node_path.join(modelsDir, filename);
+	if (node_fs.existsSync(modelPath)) if (formatEntry.isDirectory && !node_fs.existsSync(node_path.join(modelPath, "Manifest.json"))) node_fs.rmSync(modelPath, {
+		recursive: true,
+		force: true
+	});
+	else return modelPath;
+	node_fs.mkdirSync(modelsDir, { recursive: true });
+	if (formatEntry.isDirectory) await downloadDirectory(formatEntry.url, modelPath, formatEntry.files, onProgress);
+	else await downloadFile(formatEntry.url, modelPath, (downloaded, total) => onProgress?.(downloaded, total === 0 ? void 0 : total));
+	return modelPath;
+}
+/** Compute the on-disk path for a given model + format, even when not yet downloaded. */
+function getModelFilePath(modelsDir, entry, format) {
+	const formatEntry = entry.formats[format];
+	if (!formatEntry) return null;
+	const filename = formatEntry.url.split("/").pop() ?? `${entry.id}.${format}`;
+	return node_path.join(modelsDir, filename);
+}
+/** True iff the model file (or `Manifest.json` for directory bundles) exists and is non-empty. */
+function isModelDownloaded(modelsDir, entry, format) {
+	const formatEntry = entry.formats[format];
+	if (!formatEntry) return false;
+	const modelPath = getModelFilePath(modelsDir, entry, format);
+	if (!modelPath || !node_fs.existsSync(modelPath)) return false;
+	if (formatEntry.isDirectory) return node_fs.existsSync(node_path.join(modelPath, "Manifest.json"));
+	return node_fs.statSync(modelPath).size > 0;
+}
+/** Remove the on-disk model file/directory. Returns true if something was deleted. */
+function deleteModelFromDisk(modelsDir, entry, format) {
+	const modelPath = getModelFilePath(modelsDir, entry, format);
+	if (!modelPath || !node_fs.existsSync(modelPath)) return false;
+	if (entry.formats[format]?.isDirectory) node_fs.rmSync(modelPath, {
+		recursive: true,
+		force: true
+	});
+	else node_fs.unlinkSync(modelPath);
+	return true;
+}
+//#endregion
+//#region src/download/model-download-service.ts
+/**
+* Unified model download service.
+*
+* Handles downloading model files and extra files (labels, dicts) from a
+* catalog of ModelCatalogEntry items. Supports single-file models and
+* directory bundles (e.g., .mlpackage for CoreML).
+*
+* Addons use this via `context.models.ensure(modelId, format)`.
+*/
+var ModelDownloadService = class {
+	modelsDir;
+	onProgress;
+	catalog;
+	constructor(modelsDir, catalog, onProgress) {
+		this.modelsDir = modelsDir;
+		this.onProgress = onProgress;
+		const map = /* @__PURE__ */ new Map();
+		for (const entry of catalog) map.set(entry.id, entry);
+		this.catalog = map;
+	}
+	/**
+	* Ensure a model (and its extra files) is downloaded.
+	* Returns the local filesystem path to the model file/directory.
+	*/
+	async ensure(modelId, format) {
+		const entry = this.catalog.get(modelId);
+		if (!entry) throw new Error(`ModelDownloadService: unknown model "${modelId}"`);
+		const selectedFormat = format ?? this.pickDefaultFormat(entry);
+		const formatEntry = entry.formats[selectedFormat];
+		if (!formatEntry) throw new Error(`ModelDownloadService: model "${modelId}" has no ${selectedFormat} format`);
+		await this.ensureExtraFiles(modelId);
+		const modelPath = this.modelFilePath(entry, selectedFormat);
+		if (node_fs.existsSync(modelPath)) if (formatEntry.isDirectory) if (!node_fs.existsSync(node_path.join(modelPath, "Manifest.json"))) node_fs.rmSync(modelPath, {
+			recursive: true,
+			force: true
+		});
+		else return modelPath;
+		else return modelPath;
+		node_fs.mkdirSync(this.modelsDir, { recursive: true });
+		if (formatEntry.isDirectory) await this.downloadDirectory(formatEntry.url, modelPath, formatEntry.files, modelId);
+		else await downloadFile(formatEntry.url, modelPath, this.onProgress ? (downloaded, total) => this.onProgress(modelId, downloaded, total) : void 0);
+		return modelPath;
+	}
+	/**
+	* Ensure extra files for a model are downloaded.
+	* Returns the local paths of all extra files.
+	*/
+	async ensureExtraFiles(modelId) {
+		const entry = this.catalog.get(modelId);
+		if (!entry) throw new Error(`ModelDownloadService: unknown model "${modelId}"`);
+		const extras = entry.extraFiles;
+		if (!extras || extras.length === 0) return [];
+		const paths = [];
+		for (const extra of extras) {
+			const destPath = node_path.join(this.modelsDir, extra.filename);
+			await downloadFile(extra.url, destPath);
+			paths.push(destPath);
+		}
+		return paths;
+	}
+	/** Absolute path to the shared models directory. */
+	getModelsDir() {
+		return this.modelsDir;
+	}
+	/** Check if a model file is already present on disk. */
+	isDownloaded(modelId, format) {
+		const entry = this.catalog.get(modelId);
+		if (!entry) return false;
+		const selectedFormat = format ?? this.pickDefaultFormat(entry);
+		const formatEntry = entry.formats[selectedFormat];
+		if (!formatEntry) return false;
+		const modelPath = this.modelFilePath(entry, selectedFormat);
+		if (!node_fs.existsSync(modelPath)) return false;
+		if (formatEntry.isDirectory) return node_fs.existsSync(node_path.join(modelPath, "Manifest.json"));
+		return node_fs.statSync(modelPath).size > 0;
+	}
+	/** Get the catalog entry for a model by ID. */
+	getEntry(modelId) {
+		return this.catalog.get(modelId);
+	}
+	pickDefaultFormat(entry) {
+		for (const fmt of [
+			"onnx",
+			"coreml",
+			"openvino",
+			"tflite",
+			"pt"
+		]) if (entry.formats[fmt]) return fmt;
+		const first = Object.keys(entry.formats)[0];
+		if (first) return first;
+		throw new Error(`ModelDownloadService: model "${entry.id}" has no formats`);
+	}
+	modelFilePath(entry, format) {
+		const formatEntry = entry.formats[format];
+		if (!formatEntry) throw new Error(`Model ${entry.id} has no ${format} format`);
+		const urlParts = formatEntry.url.split("/");
+		const filename = urlParts[urlParts.length - 1] ?? `${entry.id}.${format}`;
+		return node_path.join(this.modelsDir, filename);
+	}
+	/**
+	* Download a directory bundle (e.g., .mlpackage) from HuggingFace.
+	* ATOMIC: downloads to temp dir, renames only on complete success.
+	*/
+	async downloadDirectory(url, destDir, knownFiles, _modelId) {
+		const match = url.match(/huggingface\.co\/([^/]+\/[^/]+)\/resolve\/main\/(.+)/);
+		if (!match) throw new Error(`Cannot parse HuggingFace URL: ${url}`);
+		const [, repo, dirPath] = match;
+		let filesToDownload;
+		if (knownFiles && knownFiles.length > 0) filesToDownload = knownFiles.map((f) => ({
+			relativePath: f,
+			fileUrl: `https://huggingface.co/${repo}/resolve/main/${dirPath}/${f}`
+		}));
+		else {
+			const hfFiles = await this.listHfFiles(repo, dirPath);
+			if (hfFiles.length === 0) throw new Error(`No files found in HuggingFace directory: ${dirPath}`);
+			filesToDownload = hfFiles.map((f) => ({
+				relativePath: f.path.substring(dirPath.length + 1),
+				fileUrl: `https://huggingface.co/${repo}/resolve/main/${f.path}`
+			}));
+		}
+		const tmpDir = destDir + ".downloading";
+		node_fs.rmSync(tmpDir, {
+			recursive: true,
+			force: true
+		});
+		node_fs.mkdirSync(tmpDir, { recursive: true });
+		try {
+			for (const file of filesToDownload) {
+				const destPath = node_path.join(tmpDir, file.relativePath);
+				node_fs.mkdirSync(node_path.dirname(destPath), { recursive: true });
+				await downloadFile(file.fileUrl, destPath);
+			}
+			node_fs.rmSync(destDir, {
+				recursive: true,
+				force: true
+			});
+			node_fs.renameSync(tmpDir, destDir);
+		} catch (err) {
+			node_fs.rmSync(tmpDir, {
+				recursive: true,
+				force: true
+			});
+			throw err;
+		}
+	}
+	/** Recursively list all files in a HuggingFace directory via API. */
+	async listHfFiles(repo, dirPath) {
+		const entries = await fetchJson(`https://huggingface.co/api/models/${repo}/tree/main/${dirPath}`);
+		const files = [];
+		for (const entry of entries) if (entry.type === "file") files.push({
+			path: entry.path,
+			size: entry.size ?? entry.lfs?.size ?? 0
+		});
+		else if (entry.type === "directory") {
+			const subFiles = await this.listHfFiles(repo, entry.path);
+			files.push(...subFiles);
+		}
+		return files;
+	}
+};
+//#endregion
+Object.defineProperty(exports, "ModelDownloadService", {
+	enumerable: true,
+	get: function() {
+		return ModelDownloadService;
+	}
+});
+Object.defineProperty(exports, "contentTypeFor", {
+	enumerable: true,
+	get: function() {
+		return contentTypeFor;
+	}
+});
+Object.defineProperty(exports, "createAuthenticatedFileServer", {
+	enumerable: true,
+	get: function() {
+		return createAuthenticatedFileServer;
+	}
+});
+Object.defineProperty(exports, "createFileDataPlaneHandler", {
+	enumerable: true,
+	get: function() {
+		return createFileDataPlaneHandler;
+	}
+});
+Object.defineProperty(exports, "deleteModelFromDisk", {
+	enumerable: true,
+	get: function() {
+		return deleteModelFromDisk;
+	}
+});
+Object.defineProperty(exports, "downloadFile", {
+	enumerable: true,
+	get: function() {
+		return downloadFile;
+	}
+});
+Object.defineProperty(exports, "downloadModel", {
+	enumerable: true,
+	get: function() {
+		return downloadModel;
+	}
+});
+Object.defineProperty(exports, "ensureModel", {
+	enumerable: true,
+	get: function() {
+		return ensureModel;
+	}
+});
+Object.defineProperty(exports, "fetchJson", {
+	enumerable: true,
+	get: function() {
+		return fetchJson;
+	}
+});
+Object.defineProperty(exports, "getModelFilePath", {
+	enumerable: true,
+	get: function() {
+		return getModelFilePath;
+	}
+});
+Object.defineProperty(exports, "isModelDownloaded", {
+	enumerable: true,
+	get: function() {
+		return isModelDownloaded;
+	}
+});
+Object.defineProperty(exports, "parseRangeHeader", {
+	enumerable: true,
+	get: function() {
+		return parseRangeHeader;
+	}
+});
+Object.defineProperty(exports, "parseTokenizedUrl", {
+	enumerable: true,
+	get: function() {
+		return parseTokenizedUrl;
+	}
+});
+Object.defineProperty(exports, "resolveFilePath", {
+	enumerable: true,
+	get: function() {
+		return resolveFilePath;
+	}
+});