@hasna/models 0.0.1

package/dist/paths.d.ts

@@ -0,0 +1,5 @@
+export declare function getModelsHome(): string;
+export declare function getDbPath(): string;
+export declare function getAuthConfigPath(): string;
+export declare function getCacheRoot(): string;
+export declare function getInstallRoot(): string;

package/dist/ref.d.ts

@@ -0,0 +1,6 @@
+import type { EntityKind, ProviderRef } from "./types.js";
+export declare function parseEntityKind(value: string): EntityKind;
+export declare function parseProviderRef(input: string, defaultKind?: EntityKind): ProviderRef;
+export declare function formatProviderRef(ref: ProviderRef): string;
+export declare function encodeRepoId(repoId: string): string;
+export declare function safePathSegment(value: string): string;

package/dist/storage.d.ts

@@ -0,0 +1,21 @@
+import { Database } from "bun:sqlite";
+import type { CatalogEntry, InstalledArtifact, RemoteFileEntry } from "./types.js";
+export declare class ModelsStore {
+    readonly db: Database;
+    constructor(path?: string);
+    close(): void;
+    migrate(): void;
+    upsertCatalog(entries: CatalogEntry[]): number;
+    upsertFiles(files: RemoteFileEntry[]): number;
+    recordInstall(artifact: InstalledArtifact, metadata?: Record<string, unknown>): InstalledArtifact;
+    listInstalls(): InstalledArtifact[];
+    findInstall(repoIdOrId: string): InstalledArtifact | null;
+    deleteInstall(id: string): boolean;
+    catalogStats(): {
+        catalogEntries: number;
+        remoteFiles: number;
+        installs: number;
+    };
+    topCatalog(limit?: number): CatalogEntry[];
+}
+export declare function createStore(path?: string): ModelsStore;

package/dist/storage.js

@@ -0,0 +1,255 @@
+// @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);
+}
+export {
+  createStore,
+  ModelsStore
+};

package/dist/types.d.ts

@@ -0,0 +1,89 @@
+export type ProviderId = "huggingface" | "github-release" | string;
+export type EntityKind = "model" | "dataset" | "space" | "collection" | "artifact";
+export interface ProviderRef {
+    provider: ProviderId;
+    entityKind: EntityKind;
+    repoId: string;
+    revision: string;
+}
+export interface CatalogEntry {
+    provider: ProviderId;
+    entityKind: EntityKind;
+    repoId: string;
+    revision: string;
+    canonicalUrl: string;
+    title: string;
+    author?: string | null;
+    task?: string | null;
+    libraryName?: string | null;
+    license?: string | null;
+    gated: boolean;
+    private: boolean;
+    downloads?: number | null;
+    likes?: number | null;
+    tags: string[];
+    lastModified?: string | null;
+    metadata: Record<string, unknown>;
+}
+export interface RemoteFileEntry {
+    provider: ProviderId;
+    entityKind: EntityKind;
+    repoId: string;
+    revision: string;
+    path: string;
+    size: number | null;
+    oid?: string | null;
+    lfsOid?: string | null;
+    format?: string | null;
+    downloadUrl: string;
+    metadata: Record<string, unknown>;
+}
+export interface SearchInput {
+    query?: string;
+    entityKind?: EntityKind;
+    task?: string;
+    license?: string;
+    tags?: string[];
+    limit?: number;
+    sort?: "downloads" | "likes" | "lastModified" | "createdAt" | "trendingScore";
+    direction?: "asc" | "desc";
+}
+export interface DownloadPlan {
+    ref: ProviderRef;
+    files: RemoteFileEntry[];
+    totalBytes: number | null;
+    unknownSizeFiles: string[];
+    destinationRoot: string;
+    exceedsMaxBytes: boolean;
+    maxBytes: number | null;
+}
+export interface InstalledArtifact {
+    id: string;
+    provider: ProviderId;
+    entityKind: EntityKind;
+    repoId: string;
+    revision: string;
+    installPath: string;
+    bytes: number;
+    files: string[];
+    status: "installed" | "planned" | "failed";
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AuthStatus {
+    provider: ProviderId;
+    available: boolean;
+    source: "env" | "config" | "secrets" | "none";
+    secretKey?: string;
+}
+export interface DoctorReport {
+    ok: boolean;
+    dataDir: string;
+    dbPath: string;
+    providers: AuthStatus[];
+    checks: Array<{
+        id: string;
+        status: "ok" | "warn" | "fail";
+        detail: string;
+    }>;
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare function getPackageVersion(): string;

package/docs/GOALS.md

@@ -0,0 +1,49 @@
+# Goal chain
+
+## Goal 1: CLI foundation and Hugging Face catalog
+
+Status: in progress in this repo.
+
+- Publishable Bun/TypeScript package.
+- `models` CLI with JSON contracts.
+- Hugging Face auth discovery through env, local config, and `secrets`.
+- SQLite catalog under `~/.hasna/models/models.db`.
+- Search, info, files, best-model indexing, and selected-file installs.
+- Tiny model download smoke tests.
+
+## Goal 2: Dataset-first workflows
+
+- Dataset search/info/files/install parity.
+- Safe sample/stream commands before full materialization.
+- Split-aware metadata and max-byte defaults.
+- Dataset fixture tests with tiny public datasets.
+
+## Goal 3: Runtime adapters
+
+- `ollama` detection and pull/run helpers.
+- `llama.cpp` GGUF plan/run/serve helpers.
+- `vllm` server plan for GPU machines.
+- `mlx-lm` plan for Apple Silicon.
+- Runtime compatibility reports that explain memory, disk, and command gaps.
+
+## Goal 4: Machine-aware installs
+
+- Optional `@hasna/machines/consumer` adapter.
+- CLI fallback to installed `machines`.
+- Local fallback when machines is absent.
+- `models machines preflight`, `models machines install`, and remote dry-run plans.
+
+## Goal 5: Provider expansion
+
+- GitHub release artifact provider.
+- ModelScope model/dataset provider.
+- Kaggle dataset/model provider.
+- Civitai model/version artifact provider.
+- Provider conformance fixtures so Hugging Face is not special-cased.
+
+## Goal 6: Agent and release interfaces
+
+- `models-mcp` with CLI/MCP parity manifest.
+- SDK fixtures and JSON contract snapshots.
+- Local REST/serve option if needed by dashboards.
+- Release smoke: build, test, pack, local install, tiny download, best index.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@hasna/models",
+  "version": "0.0.1",
+  "description": "CLI-first local model and dataset lifecycle tool for open-source/open-weight catalogs",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./storage": {
+      "import": "./dist/storage.js",
+      "types": "./dist/storage.d.ts"
+    }
+  },
+  "bin": {
+    "models": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "PLAN.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build src/cli/index.ts --outdir dist/cli --target bun && bun build src/index.ts src/storage.ts --outdir dist --target bun && tsc --emitDeclarationOnly --outDir dist",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "dev": "bun run src/cli/index.ts",
+    "pack:local": "bun pm pack",
+    "prepublishOnly": "bun run build && bun test"
+  },
+  "keywords": [
+    "models",
+    "huggingface",
+    "datasets",
+    "gguf",
+    "safetensors",
+    "local-ai",
+    "cli",
+    "sqlite"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/models.git"
+  },
+  "homepage": "https://github.com/hasna/models",
+  "bugs": {
+    "url": "https://github.com/hasna/models/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20.14.0",
+    "typescript": "^5.7.3"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}