@hasna/models 0.0.1

package/dist/index.js

@@ -0,0 +1,730 @@
+// @bun
+// src/storage.ts
+import { mkdirSync } from "fs";
+import { dirname } from "path";
+import { Database } from "bun:sqlite";
+
+// src/paths.ts
+import { homedir } from "os";
+import { join } from "path";
+function getModelsHome() {
+  return process.env["HASNA_MODELS_HOME"] || join(homedir(), ".hasna", "models");
+}
+function getDbPath() {
+  return process.env["HASNA_MODELS_DB"] || join(getModelsHome(), "models.db");
+}
+function getAuthConfigPath() {
+  return join(getModelsHome(), "auth.json");
+}
+function getCacheRoot() {
+  return process.env["HASNA_MODELS_CACHE"] || join(getModelsHome(), "cache");
+}
+function getInstallRoot() {
+  return process.env["HASNA_MODELS_INSTALLS"] || join(getModelsHome(), "installs");
+}
+
+// src/storage.ts
+var SCHEMA_VERSION = 1;
+
+class ModelsStore {
+  db;
+  constructor(path = getDbPath()) {
+    mkdirSync(dirname(path), { recursive: true });
+    this.db = new Database(path, { create: true });
+    this.db.run("PRAGMA busy_timeout = 5000");
+    this.db.run("PRAGMA journal_mode = WAL");
+    this.migrate();
+  }
+  close() {
+    this.db.close();
+  }
+  migrate() {
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS schema_meta (
+        key TEXT PRIMARY KEY,
+        value INTEGER NOT NULL
+      )
+    `);
+    const row = this.db.query("SELECT value FROM schema_meta WHERE key = 'schema_version' LIMIT 1").get();
+    const currentVersion = row ? Number(row.value) : 0;
+    if (currentVersion >= SCHEMA_VERSION)
+      return;
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS catalog_entries (
+        provider TEXT NOT NULL,
+        entity_kind TEXT NOT NULL,
+        repo_id TEXT NOT NULL,
+        revision TEXT NOT NULL,
+        title TEXT NOT NULL,
+        author TEXT,
+        task TEXT,
+        library_name TEXT,
+        license TEXT,
+        gated INTEGER NOT NULL,
+        private INTEGER NOT NULL,
+        downloads INTEGER,
+        likes INTEGER,
+        tags_json TEXT NOT NULL,
+        metadata_json TEXT NOT NULL,
+        canonical_url TEXT NOT NULL,
+        last_modified TEXT,
+        indexed_at TEXT NOT NULL,
+        PRIMARY KEY (provider, entity_kind, repo_id, revision)
+      )
+    `);
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS remote_files (
+        provider TEXT NOT NULL,
+        entity_kind TEXT NOT NULL,
+        repo_id TEXT NOT NULL,
+        revision TEXT NOT NULL,
+        path TEXT NOT NULL,
+        size INTEGER,
+        oid TEXT,
+        lfs_oid TEXT,
+        format TEXT,
+        download_url TEXT NOT NULL,
+        metadata_json TEXT NOT NULL,
+        indexed_at TEXT NOT NULL,
+        PRIMARY KEY (provider, entity_kind, repo_id, revision, path)
+      )
+    `);
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS installs (
+        id TEXT PRIMARY KEY,
+        provider TEXT NOT NULL,
+        entity_kind TEXT NOT NULL,
+        repo_id TEXT NOT NULL,
+        revision TEXT NOT NULL,
+        install_path TEXT NOT NULL,
+        bytes INTEGER NOT NULL,
+        files_json TEXT NOT NULL,
+        status TEXT NOT NULL,
+        runtime TEXT,
+        metadata_json TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      )
+    `);
+    this.db.run("CREATE INDEX IF NOT EXISTS idx_catalog_downloads ON catalog_entries(downloads DESC)");
+    this.db.run("CREATE INDEX IF NOT EXISTS idx_catalog_task ON catalog_entries(task)");
+    this.db.run("CREATE INDEX IF NOT EXISTS idx_files_repo ON remote_files(provider, entity_kind, repo_id)");
+    this.db.run("INSERT OR REPLACE INTO schema_meta (key, value) VALUES ('schema_version', ?)", [SCHEMA_VERSION]);
+  }
+  upsertCatalog(entries) {
+    const now = new Date().toISOString();
+    const stmt = this.db.prepare(`
+      INSERT INTO catalog_entries (
+        provider, entity_kind, repo_id, revision, title, author, task, library_name,
+        license, gated, private, downloads, likes, tags_json, metadata_json,
+        canonical_url, last_modified, indexed_at
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(provider, entity_kind, repo_id, revision) DO UPDATE SET
+        title=excluded.title,
+        author=excluded.author,
+        task=excluded.task,
+        library_name=excluded.library_name,
+        license=excluded.license,
+        gated=excluded.gated,
+        private=excluded.private,
+        downloads=excluded.downloads,
+        likes=excluded.likes,
+        tags_json=excluded.tags_json,
+        metadata_json=excluded.metadata_json,
+        canonical_url=excluded.canonical_url,
+        last_modified=excluded.last_modified,
+        indexed_at=excluded.indexed_at
+    `);
+    const tx = this.db.transaction((items) => {
+      for (const entry of items) {
+        stmt.run(entry.provider, entry.entityKind, entry.repoId, entry.revision, entry.title, entry.author ?? null, entry.task ?? null, entry.libraryName ?? null, entry.license ?? null, entry.gated ? 1 : 0, entry.private ? 1 : 0, entry.downloads ?? null, entry.likes ?? null, JSON.stringify(entry.tags), JSON.stringify(entry.metadata), entry.canonicalUrl, entry.lastModified ?? null, now);
+      }
+    });
+    tx(entries);
+    return entries.length;
+  }
+  upsertFiles(files) {
+    const now = new Date().toISOString();
+    const stmt = this.db.prepare(`
+      INSERT INTO remote_files (
+        provider, entity_kind, repo_id, revision, path, size, oid, lfs_oid,
+        format, download_url, metadata_json, indexed_at
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(provider, entity_kind, repo_id, revision, path) DO UPDATE SET
+        size=excluded.size,
+        oid=excluded.oid,
+        lfs_oid=excluded.lfs_oid,
+        format=excluded.format,
+        download_url=excluded.download_url,
+        metadata_json=excluded.metadata_json,
+        indexed_at=excluded.indexed_at
+    `);
+    const tx = this.db.transaction((items) => {
+      for (const file of items) {
+        stmt.run(file.provider, file.entityKind, file.repoId, file.revision, file.path, file.size ?? null, file.oid ?? null, file.lfsOid ?? null, file.format ?? null, file.downloadUrl, JSON.stringify(file.metadata), now);
+      }
+    });
+    tx(files);
+    return files.length;
+  }
+  recordInstall(artifact, metadata = {}) {
+    this.db.prepare(`
+      INSERT INTO installs (
+        id, provider, entity_kind, repo_id, revision, install_path, bytes,
+        files_json, status, runtime, metadata_json, created_at, updated_at
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        bytes=excluded.bytes,
+        files_json=excluded.files_json,
+        status=excluded.status,
+        runtime=excluded.runtime,
+        metadata_json=excluded.metadata_json,
+        updated_at=excluded.updated_at
+    `).run(artifact.id, artifact.provider, artifact.entityKind, artifact.repoId, artifact.revision, artifact.installPath, artifact.bytes, JSON.stringify(artifact.files), artifact.status, null, JSON.stringify(metadata), artifact.createdAt, artifact.updatedAt);
+    return artifact;
+  }
+  listInstalls() {
+    const rows = this.db.query("SELECT * FROM installs ORDER BY updated_at DESC").all();
+    return rows.map((row) => ({
+      id: String(row.id),
+      provider: String(row.provider),
+      entityKind: String(row.entity_kind),
+      repoId: String(row.repo_id),
+      revision: String(row.revision),
+      installPath: String(row.install_path),
+      bytes: Number(row.bytes),
+      files: JSON.parse(String(row.files_json)),
+      status: String(row.status),
+      createdAt: String(row.created_at),
+      updatedAt: String(row.updated_at)
+    }));
+  }
+  findInstall(repoIdOrId) {
+    const row = this.db.query("SELECT * FROM installs WHERE id = ? OR repo_id = ? ORDER BY updated_at DESC LIMIT 1").get(repoIdOrId, repoIdOrId);
+    if (!row)
+      return null;
+    return this.listInstalls().find((install) => install.id === row.id) ?? null;
+  }
+  deleteInstall(id) {
+    const result = this.db.prepare("DELETE FROM installs WHERE id = ?").run(id);
+    return result.changes > 0;
+  }
+  catalogStats() {
+    const one = (table) => {
+      const row = this.db.query(`SELECT COUNT(*) as count FROM ${table}`).get();
+      return Number(row?.count ?? 0);
+    };
+    return {
+      catalogEntries: one("catalog_entries"),
+      remoteFiles: one("remote_files"),
+      installs: one("installs")
+    };
+  }
+  topCatalog(limit = 20) {
+    const rows = this.db.query("SELECT * FROM catalog_entries ORDER BY COALESCE(downloads, 0) DESC, COALESCE(likes, 0) DESC LIMIT ?").all(limit);
+    return rows.map((row) => ({
+      provider: String(row.provider),
+      entityKind: String(row.entity_kind),
+      repoId: String(row.repo_id),
+      revision: String(row.revision),
+      canonicalUrl: String(row.canonical_url),
+      title: String(row.title),
+      author: row.author == null ? null : String(row.author),
+      task: row.task == null ? null : String(row.task),
+      libraryName: row.library_name == null ? null : String(row.library_name),
+      license: row.license == null ? null : String(row.license),
+      gated: Boolean(row.gated),
+      private: Boolean(row.private),
+      downloads: row.downloads == null ? null : Number(row.downloads),
+      likes: row.likes == null ? null : Number(row.likes),
+      tags: JSON.parse(String(row.tags_json)),
+      lastModified: row.last_modified == null ? null : String(row.last_modified),
+      metadata: JSON.parse(String(row.metadata_json))
+    }));
+  }
+}
+function createStore(path) {
+  return new ModelsStore(path);
+}
+// src/ref.ts
+var ENTITY_KINDS = new Set(["model", "dataset", "space"]);
+var PROVIDER_ALIASES = new Map([
+  ["hf", "huggingface"],
+  ["huggingface", "huggingface"]
+]);
+function parseEntityKind(value) {
+  if (ENTITY_KINDS.has(value))
+    return value;
+  throw new Error(`Unsupported entity kind: ${value}. Expected one of: ${[...ENTITY_KINDS].join(", ")}`);
+}
+function parseProviderRef(input, defaultKind = "model") {
+  const trimmed = input.trim();
+  if (!trimmed)
+    throw new Error("model or dataset ref is required");
+  let provider = "huggingface";
+  let entityKind = parseEntityKind(defaultKind);
+  let rest = trimmed;
+  const prefixMatch = rest.match(/^([a-zA-Z][a-zA-Z0-9+.-]*):(.*)$/);
+  if (prefixMatch && !prefixMatch[1].includes("/")) {
+    const alias = PROVIDER_ALIASES.get(prefixMatch[1]);
+    if (alias) {
+      provider = alias;
+      rest = prefixMatch[2];
+    } else if (["model", "dataset", "space"].includes(prefixMatch[1])) {
+      entityKind = parseEntityKind(prefixMatch[1]);
+      rest = prefixMatch[2];
+    } else {
+      throw new Error(`Unsupported provider: ${prefixMatch[1]}`);
+    }
+  }
+  if (rest.startsWith("model:")) {
+    entityKind = parseEntityKind("model");
+    rest = rest.slice("model:".length);
+  } else if (rest.startsWith("dataset:")) {
+    entityKind = parseEntityKind("dataset");
+    rest = rest.slice("dataset:".length);
+  } else if (rest.startsWith("space:")) {
+    entityKind = parseEntityKind("space");
+    rest = rest.slice("space:".length);
+  }
+  if (rest.includes(":")) {
+    throw new Error(`Unsupported ref prefix in: ${input}`);
+  }
+  let revision = "main";
+  const atIndex = rest.lastIndexOf("@");
+  if (atIndex > 0) {
+    revision = rest.slice(atIndex + 1);
+    rest = rest.slice(0, atIndex);
+    if (!revision.trim())
+      throw new Error(`Revision cannot be empty in ref: ${input}`);
+  } else if (rest.endsWith("@")) {
+    throw new Error(`Revision cannot be empty in ref: ${input}`);
+  }
+  if (!rest.includes("/")) {
+    throw new Error(`Expected a namespaced repo id such as owner/name, got ${input}`);
+  }
+  return { provider, entityKind, repoId: rest, revision };
+}
+function formatProviderRef(ref) {
+  const prefix = ref.provider === "huggingface" ? "hf" : ref.provider;
+  const kind = ref.entityKind === "model" ? "" : `${ref.entityKind}:`;
+  return `${prefix}:${kind}${ref.repoId}@${ref.revision}`;
+}
+function encodeRepoId(repoId) {
+  return repoId.split("/").map(encodeURIComponent).join("/");
+}
+function safePathSegment(value) {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "__").replace(/^_+|_+$/g, "") || "unnamed";
+}
+// src/auth.ts
+import { mkdirSync as mkdirSync2, readFileSync, writeFileSync } from "fs";
+import { dirname as dirname2 } from "path";
+import { spawnSync } from "child_process";
+var HF_ENV_KEYS = [
+  "HF_TOKEN",
+  "HUGGINGFACE_HUB_TOKEN",
+  "HUGGING_FACE_HUB_TOKEN",
+  "HUGGINGFACE_TOKEN"
+];
+var DEFAULT_HF_SECRET_KEYS = [
+  "huggingface/token",
+  "huggingface/live/token",
+  "hf/token"
+];
+var cachedResolution = null;
+function readAuthConfig() {
+  try {
+    return JSON.parse(readFileSync(getAuthConfigPath(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+function writeAuthConfig(config) {
+  const path = getAuthConfigPath();
+  mkdirSync2(dirname2(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}
+`);
+}
+function fromEnv() {
+  for (const key of HF_ENV_KEYS) {
+    const value = process.env[key]?.trim();
+    if (value)
+      return value;
+  }
+  return null;
+}
+function readSecret(key) {
+  const result = spawnSync("secrets", ["get", key], {
+    encoding: "utf8",
+    env: process.env,
+    timeout: 1e4,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (result.status !== 0)
+    return null;
+  const value = result.stdout.trim();
+  return value || null;
+}
+function secretCandidates(config) {
+  const configured = [
+    process.env["HASNA_MODELS_HF_SECRET_KEY"],
+    process.env["HF_SECRET_KEY"],
+    config.huggingface?.secretKey
+  ].filter((value) => Boolean(value?.trim()));
+  return [...new Set([...configured, ...DEFAULT_HF_SECRET_KEYS])];
+}
+function redactAuthStatus(status) {
+  const { secretKey: _secretKey, ...rest } = status;
+  return rest;
+}
+function resolveHuggingFaceToken() {
+  if (cachedResolution)
+    return cachedResolution;
+  const envToken = fromEnv();
+  if (envToken) {
+    cachedResolution = { token: envToken, status: { provider: "huggingface", available: true, source: "env" } };
+    return cachedResolution;
+  }
+  const config = readAuthConfig();
+  const configToken = config.huggingface?.token?.trim();
+  if (configToken) {
+    cachedResolution = { token: configToken, status: { provider: "huggingface", available: true, source: "config" } };
+    return cachedResolution;
+  }
+  for (const key of secretCandidates(config)) {
+    const token = readSecret(key);
+    if (token) {
+      cachedResolution = {
+        token,
+        status: {
+          provider: "huggingface",
+          available: true,
+          source: "secrets",
+          secretKey: key
+        }
+      };
+      return cachedResolution;
+    }
+  }
+  cachedResolution = { token: null, status: { provider: "huggingface", available: false, source: "none" } };
+  return cachedResolution;
+}
+function getHuggingFaceAuthStatus() {
+  return redactAuthStatus(resolveHuggingFaceToken().status);
+}
+function saveHuggingFaceSecretRef(secretKey) {
+  const config = readAuthConfig();
+  config.huggingface = { ...config.huggingface, secretKey };
+  delete config.huggingface.token;
+  writeAuthConfig(config);
+  cachedResolution = null;
+  return redactAuthStatus({ provider: "huggingface", available: Boolean(readSecret(secretKey)), source: "secrets", secretKey });
+}
+// src/huggingface.ts
+import { createWriteStream, mkdirSync as mkdirSync3, renameSync, unlinkSync } from "fs";
+import { dirname as dirname3, isAbsolute, join as join2, resolve, sep } from "path";
+import { pipeline } from "stream/promises";
+import { Readable } from "stream";
+import { randomUUID } from "crypto";
+var HF_ENDPOINT = process.env["HF_ENDPOINT"] || "https://huggingface.co";
+function apiBase() {
+  return HF_ENDPOINT.replace(/\/+$/, "");
+}
+function headers() {
+  const { token } = resolveHuggingFaceToken();
+  return token ? { Authorization: `Bearer ${token}` } : {};
+}
+async function hfJson(path, init) {
+  const response = await fetch(`${apiBase()}${path}`, {
+    ...init,
+    headers: {
+      ...headers(),
+      ...init?.headers ?? {}
+    }
+  });
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(`Hugging Face request failed ${response.status} ${response.statusText}: ${text.slice(0, 300)}`);
+  }
+  return response.json();
+}
+function apiKind(kind) {
+  if (kind === "dataset")
+    return "datasets";
+  if (kind === "space")
+    return "spaces";
+  return "models";
+}
+function canonicalUrl(kind, repoId) {
+  const base = apiBase();
+  if (kind === "dataset")
+    return `${base}/datasets/${repoId}`;
+  if (kind === "space")
+    return `${base}/spaces/${repoId}`;
+  return `${base}/${repoId}`;
+}
+function extractLicense(tags, cardData) {
+  const licenseTag = tags.find((tag) => tag.startsWith("license:"));
+  if (licenseTag)
+    return licenseTag.slice("license:".length);
+  if (cardData && typeof cardData === "object" && "license" in cardData) {
+    const raw = cardData.license;
+    if (Array.isArray(raw))
+      return raw.map(String).join(",");
+    if (typeof raw === "string")
+      return raw;
+  }
+  return null;
+}
+function detectFormat(path) {
+  const lower = path.toLowerCase();
+  if (lower.endsWith(".gguf"))
+    return "gguf";
+  if (lower.endsWith(".safetensors"))
+    return "safetensors";
+  if (lower.endsWith(".bin"))
+    return "pytorch-bin";
+  if (lower.endsWith(".onnx"))
+    return "onnx";
+  if (lower.endsWith(".h5"))
+    return "tensorflow";
+  if (lower.endsWith(".msgpack"))
+    return "flax";
+  if (lower.endsWith(".parquet"))
+    return "parquet";
+  if (lower.endsWith(".csv"))
+    return "csv";
+  if (lower.endsWith(".tsv"))
+    return "tsv";
+  if (lower.endsWith(".txt"))
+    return "text";
+  if (lower.endsWith(".arrow"))
+    return "arrow";
+  if (lower.endsWith(".jsonl"))
+    return "jsonl";
+  if (lower.endsWith(".json"))
+    return "json";
+  return null;
+}
+function safeDestinationPath(root, filePath) {
+  if (isAbsolute(filePath))
+    throw new Error(`Unsafe remote file path: ${filePath}`);
+  if (/^[a-zA-Z]:[\\/]/.test(filePath))
+    throw new Error(`Unsafe remote file path: ${filePath}`);
+  const segments = filePath.split(/[\\/]+/);
+  if (segments.some((segment) => segment === ".." || segment === "")) {
+    throw new Error(`Unsafe remote file path: ${filePath}`);
+  }
+  const resolvedRoot = resolve(root);
+  const destination = resolve(resolvedRoot, ...segments);
+  if (destination !== resolvedRoot && !destination.startsWith(`${resolvedRoot}${sep}`)) {
+    throw new Error(`Remote file path escapes install root: ${filePath}`);
+  }
+  return destination;
+}
+function normalizeEntry(raw, kind) {
+  const repoId = String(raw.id ?? raw.modelId ?? "");
+  const tags = Array.isArray(raw.tags) ? raw.tags.map(String) : [];
+  const cardData = raw.cardData;
+  return {
+    provider: "huggingface",
+    entityKind: kind,
+    repoId,
+    revision: String(raw.sha ?? "main"),
+    canonicalUrl: canonicalUrl(kind, repoId),
+    title: repoId,
+    author: typeof raw.author === "string" ? raw.author : repoId.split("/")[0],
+    task: typeof raw.pipeline_tag === "string" ? raw.pipeline_tag : null,
+    libraryName: typeof raw.library_name === "string" ? raw.library_name : null,
+    license: extractLicense(tags, cardData),
+    gated: Boolean(raw.gated),
+    private: Boolean(raw.private),
+    downloads: typeof raw.downloads === "number" ? raw.downloads : null,
+    likes: typeof raw.likes === "number" ? raw.likes : null,
+    tags,
+    lastModified: typeof raw.lastModified === "string" ? raw.lastModified : null,
+    metadata: raw
+  };
+}
+function normalizeTreeFile(raw, ref) {
+  if (raw.type && raw.type !== "file")
+    return null;
+  const path = String(raw.path ?? raw.rfilename ?? "");
+  if (!path)
+    return null;
+  const lfs = raw.lfs && typeof raw.lfs === "object" ? raw.lfs : {};
+  const size = typeof raw.size === "number" ? raw.size : typeof lfs.size === "number" ? lfs.size : null;
+  return {
+    provider: "huggingface",
+    entityKind: ref.entityKind,
+    repoId: ref.repoId,
+    revision: ref.revision,
+    path,
+    size,
+    oid: typeof raw.oid === "string" ? raw.oid : null,
+    lfsOid: typeof lfs.oid === "string" ? lfs.oid : null,
+    format: detectFormat(path),
+    downloadUrl: fileDownloadUrl(ref, path),
+    metadata: raw
+  };
+}
+function normalizeSibling(raw, ref) {
+  const path = String(raw.rfilename ?? raw.path ?? "");
+  if (!path)
+    return null;
+  return {
+    provider: "huggingface",
+    entityKind: ref.entityKind,
+    repoId: ref.repoId,
+    revision: ref.revision,
+    path,
+    size: typeof raw.size === "number" ? raw.size : null,
+    oid: typeof raw.oid === "string" ? raw.oid : null,
+    lfsOid: null,
+    format: detectFormat(path),
+    downloadUrl: fileDownloadUrl(ref, path),
+    metadata: raw
+  };
+}
+function fileDownloadUrl(ref, path) {
+  const encodedRepo = encodeRepoId(ref.repoId);
+  const encodedRevision = encodeURIComponent(ref.revision || "main");
+  const encodedPath = path.split("/").map(encodeURIComponent).join("/");
+  const prefix = ref.entityKind === "dataset" ? "datasets/" : ref.entityKind === "space" ? "spaces/" : "";
+  return `${apiBase()}/${prefix}${encodedRepo}/resolve/${encodedRevision}/${encodedPath}`;
+}
+async function searchHuggingFace(input = {}) {
+  const kind = input.entityKind ?? "model";
+  const params = new URLSearchParams;
+  if (input.query)
+    params.set("search", input.query);
+  params.set("limit", String(input.limit ?? 20));
+  params.set("full", "1");
+  params.set("sort", input.sort ?? "downloads");
+  params.set("direction", input.direction === "asc" ? "1" : "-1");
+  if (input.task)
+    params.append("filter", input.task);
+  if (input.license)
+    params.append("filter", `license:${input.license}`);
+  for (const tag of input.tags ?? [])
+    params.append("filter", tag);
+  const raw = await hfJson(`/api/${apiKind(kind)}?${params.toString()}`);
+  return raw.map((entry) => normalizeEntry(entry, kind)).filter((entry) => Boolean(entry.repoId));
+}
+async function getHuggingFaceInfo(refOrInput, defaultKind = "model") {
+  const ref = typeof refOrInput === "string" ? parseProviderRef(refOrInput, defaultKind) : refOrInput;
+  const raw = await hfJson(`/api/${apiKind(ref.entityKind)}/${encodeRepoId(ref.repoId)}`);
+  return normalizeEntry(raw, ref.entityKind);
+}
+async function listHuggingFaceFiles(refOrInput, defaultKind = "model") {
+  const ref = typeof refOrInput === "string" ? parseProviderRef(refOrInput, defaultKind) : refOrInput;
+  const treePath = `/api/${apiKind(ref.entityKind)}/${encodeRepoId(ref.repoId)}/tree/${encodeURIComponent(ref.revision)}?recursive=1&expand=1`;
+  try {
+    const raw = await hfJson(treePath);
+    return raw.map((entry) => normalizeTreeFile(entry, ref)).filter((entry) => Boolean(entry));
+  } catch {
+    const info = await hfJson(`/api/${apiKind(ref.entityKind)}/${encodeRepoId(ref.repoId)}`);
+    const siblings = Array.isArray(info.siblings) ? info.siblings : [];
+    return siblings.map((entry) => normalizeSibling(entry, ref)).filter((entry) => Boolean(entry));
+  }
+}
+function matchesFilePattern(path, pattern) {
+  const normalized = pattern.trim();
+  if (!normalized)
+    return false;
+  if (normalized === path)
+    return true;
+  if (normalized.endsWith("/"))
+    return path.startsWith(normalized);
+  if (normalized.includes("*")) {
+    const regex = new RegExp(`^${normalized.split("*").map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`);
+    return regex.test(path);
+  }
+  if (!normalized.includes("/")) {
+    return path.split("/").pop() === normalized;
+  }
+  return false;
+}
+function matchAny(path, patterns) {
+  if (patterns.length === 0)
+    return true;
+  return patterns.some((pattern) => matchesFilePattern(path, pattern));
+}
+async function createDownloadPlan(input) {
+  const include = input.include ?? [];
+  const exclude = input.exclude ?? [];
+  const files = (await listHuggingFaceFiles(input.ref)).filter((file) => include.length === 0 || matchAny(file.path, include)).filter((file) => exclude.length === 0 || !matchAny(file.path, exclude));
+  const knownBytes = files.reduce((sum, file) => sum + (file.size ?? 0), 0);
+  const unknownSizeFiles = files.filter((file) => file.size == null).map((file) => file.path);
+  const totalBytes = unknownSizeFiles.length > 0 ? null : knownBytes;
+  const maxBytes = input.maxBytes ?? null;
+  const destinationRoot = input.destinationRoot ?? join2(getInstallRoot(), input.ref.provider, input.ref.entityKind, safePathSegment(input.ref.repoId), safePathSegment(input.ref.revision));
+  return {
+    ref: input.ref,
+    files,
+    totalBytes,
+    unknownSizeFiles,
+    destinationRoot,
+    exceedsMaxBytes: maxBytes != null && totalBytes != null && totalBytes > maxBytes,
+    maxBytes
+  };
+}
+async function downloadPlannedFiles(plan) {
+  if (plan.exceedsMaxBytes) {
+    throw new Error(`Download plan exceeds max bytes: ${plan.totalBytes} > ${plan.maxBytes}`);
+  }
+  if (plan.maxBytes != null && plan.unknownSizeFiles.length > 0) {
+    throw new Error(`Download plan has unknown-size files under a byte cap: ${plan.unknownSizeFiles.join(", ")}`);
+  }
+  const downloaded = [];
+  for (const file of plan.files) {
+    const destination = safeDestinationPath(plan.destinationRoot, file.path);
+    const tempDestination = `${destination}.partial-${randomUUID()}`;
+    mkdirSync3(dirname3(destination), { recursive: true });
+    const response = await fetch(file.downloadUrl, { headers: headers(), redirect: "follow" });
+    if (!response.ok || !response.body) {
+      const text = await response.text().catch(() => "");
+      throw new Error(`Failed to download ${file.path}: ${response.status} ${response.statusText} ${text.slice(0, 200)}`);
+    }
+    try {
+      await pipeline(Readable.fromWeb(response.body), createWriteStream(tempDestination));
+      renameSync(tempDestination, destination);
+      const bytes = file.size ?? Bun.file(destination).size;
+      downloaded.push({ path: file.path, bytes, destination });
+    } catch (error) {
+      try {
+        unlinkSync(tempDestination);
+      } catch {}
+      throw error;
+    }
+  }
+  return downloaded;
+}
+export {
+  searchHuggingFace,
+  saveHuggingFaceSecretRef,
+  safePathSegment,
+  resolveHuggingFaceToken,
+  redactAuthStatus,
+  parseProviderRef,
+  parseEntityKind,
+  matchesFilePattern,
+  listHuggingFaceFiles,
+  getModelsHome,
+  getInstallRoot,
+  getHuggingFaceInfo,
+  getHuggingFaceAuthStatus,
+  getDbPath,
+  getCacheRoot,
+  getAuthConfigPath,
+  formatProviderRef,
+  fileDownloadUrl,
+  encodeRepoId,
+  downloadPlannedFiles,
+  createStore,
+  createDownloadPlan,
+  ModelsStore
+};