@otto-code/brain 0.7.5

package/dist/models/dirs.js

@@ -0,0 +1,21 @@
+/**
+ * Resolves which directories to scan for models: the managed dir under
+ * `$OTTO_HOME/otto-brain/models` (where `otto brain pull` downloads to) plus the
+ * LM Studio library as an additional discovery source. The managed dir wins on id
+ * collisions so a pulled model shadows an identically-pathed LM Studio one.
+ */
+import { resolveBrainPaths } from "../config/paths.js";
+import { LMSTUDIO_MODELS_DIR } from "./scan.js";
+export function resolveModelsDirs(config, env = process.env) {
+    const paths = resolveBrainPaths(env);
+    const managed = config.modelsDir ?? paths.modelsDir;
+    return [
+        { dir: managed, origin: "managed" },
+        { dir: LMSTUDIO_MODELS_DIR, origin: "lmstudio" },
+    ];
+}
+/** The single directory new downloads are written to. */
+export function managedModelsDir(config, env = process.env) {
+    return config.modelsDir ?? resolveBrainPaths(env).modelsDir;
+}
+//# sourceMappingURL=dirs.js.map

package/dist/models/download.d.ts

@@ -0,0 +1,31 @@
+import type { CatalogModel } from "../config/schema.js";
+export interface PullProgress {
+    file: string;
+    receivedBytes: number;
+    totalBytes?: number;
+}
+export interface PullOptions {
+    model: CatalogModel;
+    destRoot: string;
+    file?: string;
+    token?: string | null;
+    onProgress?: (progress: PullProgress) => void;
+}
+/** Download the model file; returns the local path it was written to. */
+export declare function pullModel({ model, destRoot, file, token, onProgress, }: PullOptions): Promise<string>;
+export interface DownloadFilesOptions {
+    repo: string;
+    /** Repo-relative file paths (a quant's shards, plus any projector). */
+    files: string[];
+    destRoot: string;
+    token?: string | null;
+    onProgress?: (progress: PullProgress) => void;
+}
+/**
+ * Download a set of repo-relative files (a chosen quant's shards, plus the shared
+ * projector for a vision repo) under `<destRoot>/<repo>/<path>`, preserving any
+ * subdirectory. Progress accumulates across all files so a multi-shard quant
+ * reports one continuous byte count. Returns the paths actually written.
+ */
+export declare function downloadRepoFiles({ repo, files, destRoot, token, onProgress, }: DownloadFilesOptions): Promise<string[]>;
+//# sourceMappingURL=download.d.ts.map

package/dist/models/download.js

@@ -0,0 +1,105 @@
+/**
+ * Downloads a catalog model from Hugging Face into the managed models directory,
+ * so `otto brain pull` needs no external tooling. Files land under
+ * `<managedModelsDir>/<publisher>/<repo>/<file>` to mirror the LM Studio layout
+ * the scanner already understands.
+ */
+import { createWriteStream, existsSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+const HF_BASE = "https://huggingface.co";
+/** The Hugging Face resolve URL for a repo file on the main branch. */
+function resolveUrl(repo, file) {
+    return `${HF_BASE}/${repo}/resolve/main/${file}`;
+}
+/**
+ * The GGUF filename to download. Prefer an explicit override, then the catalog
+ * entry's `quantFile`, then the basename of the catalog `id` — which for the
+ * seeded catalog is `<hfRepo>/<file>.gguf`, so the id already names the file.
+ * Only if none of those yields a `.gguf` do we give up: community repos name
+ * files inconsistently, so a bare id with no gguf basename still needs --file.
+ */
+function resolveFileName(model, override) {
+    const file = override ?? model.quantFile ?? deriveFileFromId(model.id);
+    if (!file) {
+        throw new Error(`no file name for ${model.id}: add "quantFile" to the catalog entry or pass --file <name.gguf>`);
+    }
+    return file;
+}
+/** The last path segment of the id, when it is a `.gguf` file name. */
+function deriveFileFromId(id) {
+    const base = id.split("/").pop();
+    return base && base.toLowerCase().endsWith(".gguf") ? base : undefined;
+}
+function authHeaders(token) {
+    return token ? { authorization: `Bearer ${token}` } : {};
+}
+/**
+ * Stream one HF file to `destPath`, reporting bytes received. Skips (returns
+ * false) if the file already exists. Writes to a `.part` then renames so a
+ * killed download never leaves a truncated file that looks complete.
+ */
+async function streamRepoFile(url, destPath, label, token, onProgress, received) {
+    mkdirSync(path.dirname(destPath), { recursive: true });
+    if (existsSync(destPath))
+        return false;
+    const response = await fetch(url, { headers: authHeaders(token) });
+    if (!response.ok || !response.body) {
+        throw new Error(`download failed (${response.status}) for ${url}`);
+    }
+    const totalBytes = Number(response.headers.get("content-length")) || undefined;
+    const body = Readable.fromWeb(response.body);
+    body.on("data", (chunk) => {
+        received.bytes += chunk.length;
+        onProgress?.({ file: label, receivedBytes: received.bytes, totalBytes });
+    });
+    const tmp = `${destPath}.part`;
+    await pipeline(body, createWriteStream(tmp));
+    const { renameSync } = await import("node:fs");
+    renameSync(tmp, destPath);
+    return true;
+}
+/** Download the model file; returns the local path it was written to. */
+export async function pullModel({ model, destRoot, file, token, onProgress, }) {
+    const fileName = resolveFileName(model, file);
+    const repoDir = path.join(destRoot, model.hfRepo.replace(/\//g, path.sep));
+    const destPath = path.join(repoDir, fileName);
+    await streamRepoFile(resolveUrl(model.hfRepo, fileName), destPath, fileName, token, onProgress, {
+        bytes: 0,
+    });
+    return destPath;
+}
+/**
+ * Download a set of repo-relative files (a chosen quant's shards, plus the shared
+ * projector for a vision repo) under `<destRoot>/<repo>/<path>`, preserving any
+ * subdirectory. Progress accumulates across all files so a multi-shard quant
+ * reports one continuous byte count. Returns the paths actually written.
+ */
+export async function downloadRepoFiles({ repo, files, destRoot, token, onProgress, }) {
+    const rootResolved = path.resolve(destRoot);
+    const repoDir = path.join(rootResolved, repo.replace(/\//g, path.sep));
+    const received = { bytes: 0 };
+    const written = [];
+    for (const repoFile of files) {
+        // `repo` and `repoFile` come from the untrusted Hugging Face API; a crafted
+        // repo tree could list names with `..` or backslash segments that escape the
+        // models dir. Split on BOTH separators, reject traversal segments, and verify
+        // the resolved path stays under destRoot before writing.
+        const segments = repoFile.split(/[/\\]/).filter(Boolean);
+        if (segments.some((segment) => segment === "." || segment === "..")) {
+            throw new Error(`Refusing to download file with unsafe path: ${repoFile}`);
+        }
+        const destPath = path.join(repoDir, ...segments);
+        const resolved = path.resolve(destPath);
+        if (resolved !== rootResolved && !resolved.startsWith(rootResolved + path.sep)) {
+            throw new Error(`Refusing to write outside the models directory: ${repoFile}`);
+        }
+        const url = `${HF_BASE}/${repo}/resolve/main/${repoFile}`;
+        const wrote = await streamRepoFile(url, resolved, repoFile, token, onProgress, received);
+        if (wrote)
+            written.push(resolved);
+    }
+    return written;
+}
+//# sourceMappingURL=download.js.map

package/dist/models/enrich.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Reconciles scanned models back to their download-catalog entries so a model's
+ * coding metadata (useCases, tier, thinking, contextMax) survives a `pull`. The
+ * catalog carries this per entry, but once files land on disk scan.ts rebuilds a
+ * Model from filename + GGUF header alone, dropping it — this is where it is
+ * re-attached. Track B1 of the brain coding-capabilities work.
+ *
+ * The join key is the hfRepo path. download.ts writes each model to
+ * `<modelsDir>/<hfRepo>/<file>.gguf` (LM Studio mirrors the same
+ * `<publisher>/<repo>/<file>` layout), and scan.ts rebuilds `Model.id` as that
+ * same modelsDir-relative path with forward slashes. So a scanned model's id
+ * sits under its catalog entry's hfRepo directory, and that containment is the
+ * match.
+ *
+ * Total and best-effort by design: an empty catalog, a model with no match, or a
+ * repo carrying several quants all resolve without throwing. Discovery returns
+ * things unenriched on absence rather than raising — the caller decides whether
+ * absence matters.
+ */
+import type { Catalog, CatalogModel } from "../config/schema.js";
+import type { Model } from "../types.js";
+/**
+ * Find the catalog entry a scanned model belongs to, or null. A model matches
+ * when its id path sits directly under the entry's hfRepo directory. When a repo
+ * ships several quants (several catalog entries share one hfRepo), the tie is
+ * broken by exact file name first, then by matching quant, then by the most
+ * specific (longest) hfRepo.
+ */
+export declare function matchCatalogEntry(model: Model, catalog: Catalog): CatalogModel | null;
+/**
+ * Return copies of the models with catalog coding metadata attached where a match
+ * exists; models with no match (and every model when the catalog is empty) pass
+ * through untouched. Never throws.
+ */
+export declare function enrichWithCatalog(models: Model[], catalog: Catalog): Model[];
+//# sourceMappingURL=enrich.d.ts.map

package/dist/models/enrich.js

@@ -0,0 +1,68 @@
+/** Normalize a repo/id path: forward slashes, lowercased, trailing slashes trimmed. */
+function normalizePath(value) {
+    return value.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}
+/** The final path segment (file name) of a scanned model's id. */
+function basenameOf(id) {
+    const normalized = id.replace(/\\/g, "/");
+    const slash = normalized.lastIndexOf("/");
+    return slash === -1 ? normalized : normalized.slice(slash + 1);
+}
+/**
+ * Find the catalog entry a scanned model belongs to, or null. A model matches
+ * when its id path sits directly under the entry's hfRepo directory. When a repo
+ * ships several quants (several catalog entries share one hfRepo), the tie is
+ * broken by exact file name first, then by matching quant, then by the most
+ * specific (longest) hfRepo.
+ */
+export function matchCatalogEntry(model, catalog) {
+    const id = normalizePath(model.id);
+    const base = basenameOf(model.id).toLowerCase();
+    let best = null;
+    let bestScore = -1;
+    for (const entry of catalog.models) {
+        const repo = normalizePath(entry.hfRepo);
+        // The model file must live under the repo directory. The trailing slash
+        // guards against a partial segment match (repo "a/b" vs id "a/b-30b/...").
+        if (!repo || !id.startsWith(`${repo}/`))
+            continue;
+        let score = repo.length; // most-specific repo wins otherwise-equal ties
+        if (entry.quantFile && entry.quantFile.toLowerCase() === base) {
+            score += 1000000;
+        }
+        else if (entry.quant &&
+            model.quant &&
+            entry.quant.toLowerCase() === model.quant.toLowerCase()) {
+            score += 1000;
+        }
+        if (score > bestScore) {
+            bestScore = score;
+            best = entry;
+        }
+    }
+    return best;
+}
+/**
+ * Return copies of the models with catalog coding metadata attached where a match
+ * exists; models with no match (and every model when the catalog is empty) pass
+ * through untouched. Never throws.
+ */
+export function enrichWithCatalog(models, catalog) {
+    if (catalog.models.length === 0)
+        return models;
+    return models.map((model) => {
+        const entry = matchCatalogEntry(model, catalog);
+        if (!entry)
+            return model;
+        return {
+            ...model,
+            catalogId: entry.id,
+            catalogHfRepo: entry.hfRepo,
+            useCases: entry.useCases,
+            tier: entry.tier,
+            thinking: entry.thinking,
+            contextMax: entry.contextMax,
+        };
+    });
+}
+//# sourceMappingURL=enrich.js.map

package/dist/models/hf.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Hugging Face repo introspection: list the GGUF quantizations a repo offers so a
+ * user can pick which one to download (tweak Q4 <-> Q5 <-> Q6). Uses the public
+ * tree API - no SDK, no auth required for public repos - and pairs multipart
+ * shards and the shared vision projector the way the local scanner does.
+ */
+import type { BrainConfig } from "../config/schema.js";
+import type { Model } from "../types.js";
+/**
+ * The Hugging Face repo a scanned model came from: its catalog match, else the
+ * first two segments of its id (`<publisher>/<repo>/<file>`). Null when the layout
+ * does not name a repo. Shared so the TUI, the CLI, and the daemon all agree on
+ * which local models belong to a given repo.
+ */
+export declare function repoOfModel(model: Model): string | null;
+/** Resolve an HF token: env first (runtime override), then persisted config. */
+export declare function resolveHfToken(config?: BrainConfig | null, env?: NodeJS.ProcessEnv): string | null;
+/** A downloadable quantization: its label, the repo-relative file(s), total size. */
+export interface QuantOption {
+    quant: string;
+    files: string[];
+    sizeBytes: number;
+}
+/** The quants a repo offers plus its shared vision projector, if any. */
+export interface RepoQuants {
+    repo: string;
+    quants: QuantOption[];
+    mmproj: {
+        files: string[];
+        sizeBytes: number;
+    } | null;
+}
+/** One GGUF repo from a search, in a surface-agnostic shape (TUI and app share). */
+export interface ModelSearchResult {
+    repo: string;
+    author: string;
+    downloads: number;
+    likes: number;
+    updatedAt: string | null;
+    gated: boolean;
+}
+/**
+ * Search Hugging Face for GGUF model repos, most-downloaded first. Returns a
+ * normalized shape both the TUI and the Otto app can render; drill into a result
+ * with {@link listRepoQuants} to see and download its quantizations.
+ */
+export declare function searchModels(query: string, { limit, token }?: {
+    limit?: number;
+    token?: string | null;
+}): Promise<ModelSearchResult[]>;
+/**
+ * Quality order for display: higher bits-per-weight is more faithful and larger.
+ * Q2 < Q3 < ... < Q8 < F16 < F32, with K_S < K_M < K_L and _0 < _1 as tie-breaks.
+ */
+export declare function quantRank(quant: string): number;
+/**
+ * List the GGUF quantizations available in a Hugging Face repo. Model files are
+ * grouped by detected quant (shards summed); the vision projector is returned
+ * separately because one projector serves every quant in the repo.
+ */
+export declare function listRepoQuants(repo: string, token?: string | null): Promise<RepoQuants>;
+//# sourceMappingURL=hf.d.ts.map

package/dist/models/hf.js

@@ -0,0 +1,114 @@
+import { detectQuant, isProjectorFile } from "./scan.js";
+const HF_BASE = "https://huggingface.co";
+/**
+ * The Hugging Face repo a scanned model came from: its catalog match, else the
+ * first two segments of its id (`<publisher>/<repo>/<file>`). Null when the layout
+ * does not name a repo. Shared so the TUI, the CLI, and the daemon all agree on
+ * which local models belong to a given repo.
+ */
+export function repoOfModel(model) {
+    if (model.catalogHfRepo)
+        return model.catalogHfRepo;
+    const segments = model.id.split("/");
+    return segments.length >= 3 ? segments.slice(0, 2).join("/") : null;
+}
+/** Resolve an HF token: env first (runtime override), then persisted config. */
+export function resolveHfToken(config, env = process.env) {
+    return env.HF_TOKEN || env.HUGGING_FACE_HUB_TOKEN || config?.hfToken || null;
+}
+function authHeaders(token) {
+    return token ? { authorization: `Bearer ${token}` } : {};
+}
+function entryBytes(entry) {
+    return entry.size ?? entry.lfs?.size ?? 0;
+}
+/**
+ * Search Hugging Face for GGUF model repos, most-downloaded first. Returns a
+ * normalized shape both the TUI and the Otto app can render; drill into a result
+ * with {@link listRepoQuants} to see and download its quantizations.
+ */
+export async function searchModels(query, { limit = 25, token = null } = {}) {
+    const params = new URLSearchParams({
+        search: query,
+        filter: "gguf",
+        sort: "downloads",
+        direction: "-1",
+        limit: String(limit),
+    });
+    const res = await fetch(`${HF_BASE}/api/models?${params.toString()}`, {
+        headers: authHeaders(token),
+    });
+    if (!res.ok) {
+        throw new Error(`Hugging Face search failed (${res.status}) for "${query}"`);
+    }
+    const entries = (await res.json());
+    return entries.map((entry) => ({
+        repo: entry.id,
+        author: entry.author ?? entry.id.split("/")[0] ?? "",
+        downloads: entry.downloads ?? 0,
+        likes: entry.likes ?? 0,
+        updatedAt: entry.lastModified ?? null,
+        gated: Boolean(entry.gated),
+    }));
+}
+/**
+ * Quality order for display: higher bits-per-weight is more faithful and larger.
+ * Q2 < Q3 < ... < Q8 < F16 < F32, with K_S < K_M < K_L and _0 < _1 as tie-breaks.
+ */
+export function quantRank(quant) {
+    const q = quant.toUpperCase();
+    const digits = /Q(\d+)/.exec(q);
+    const base = digits ? Number(digits[1]) : /BF16|F16/.test(q) ? 16 : /F32/.test(q) ? 32 : 99;
+    const sub = /_K_S/.test(q)
+        ? 0.1
+        : /_K_M/.test(q)
+            ? 0.2
+            : /_K_L/.test(q)
+                ? 0.3
+                : /_1$/.test(q)
+                    ? 0.05
+                    : 0;
+    return base + sub;
+}
+/**
+ * List the GGUF quantizations available in a Hugging Face repo. Model files are
+ * grouped by detected quant (shards summed); the vision projector is returned
+ * separately because one projector serves every quant in the repo.
+ */
+export async function listRepoQuants(repo, token = null) {
+    const url = `${HF_BASE}/api/models/${repo}/tree/main?recursive=true`;
+    const res = await fetch(url, { headers: authHeaders(token) });
+    if (!res.ok) {
+        throw new Error(`Hugging Face listing failed (${res.status}) for ${repo}`);
+    }
+    const entries = (await res.json());
+    const ggufs = entries.filter((e) => e.type === "file" && e.path.toLowerCase().endsWith(".gguf"));
+    const basename = (p) => p.split("/").pop() ?? p;
+    const projectors = ggufs.filter((e) => isProjectorFile(basename(e.path)));
+    const modelFiles = ggufs.filter((e) => !isProjectorFile(basename(e.path)));
+    const byQuant = new Map();
+    for (const entry of modelFiles) {
+        // Skip files whose quant we cannot classify: we could not present or manage
+        // an unlabelled blob sensibly, and it is usually an F16/BF16 conversion the
+        // picker does not want to offer as a "quant".
+        const quant = detectQuant(basename(entry.path));
+        if (!quant)
+            continue;
+        const option = byQuant.get(quant) ?? { quant, files: [], sizeBytes: 0 };
+        option.files.push(entry.path);
+        option.sizeBytes += entryBytes(entry);
+        byQuant.set(quant, option);
+    }
+    // Keep shard order stable so the first file is the 00001 shard.
+    for (const option of byQuant.values())
+        option.files.sort();
+    const quants = [...byQuant.values()].sort((a, b) => quantRank(a.quant) - quantRank(b.quant));
+    // One projector serves every quant; download only the largest, matching what
+    // the scanner picks, rather than every precision the repo ships.
+    const largestProjector = projectors.reduce((best, entry) => (best === null || entryBytes(entry) > entryBytes(best) ? entry : best), null);
+    const mmproj = largestProjector
+        ? { files: [largestProjector.path], sizeBytes: entryBytes(largestProjector) }
+        : null;
+    return { repo, quants, mmproj };
+}
+//# sourceMappingURL=hf.js.map

package/dist/models/index.d.ts

@@ -0,0 +1,15 @@
+import type { BrainConfig } from "../config/schema.js";
+import type { Model } from "../types.js";
+export * from "./scan.js";
+export { pickModel } from "./pick.js";
+export { resolveModelsDirs, managedModelsDir, type ModelsDir } from "./dirs.js";
+export { pullModel, downloadRepoFiles, type PullOptions, type PullProgress, type DownloadFilesOptions, } from "./download.js";
+export { matchCatalogEntry, enrichWithCatalog } from "./enrich.js";
+export { resolveHfToken, listRepoQuants, searchModels, repoOfModel, quantRank, type QuantOption, type RepoQuants, type ModelSearchResult, } from "./hf.js";
+export { diskUsage, totalModelBytes, planDelete, deleteModelFiles, type DiskUsage, type DeletePlan, } from "./manage.js";
+export interface ScanModelsOptions {
+    withMetadata?: boolean;
+}
+/** Scan every configured models directory (managed ∪ LM Studio), de-duplicated. */
+export declare function scanModels(config: BrainConfig, env?: NodeJS.ProcessEnv, options?: ScanModelsOptions): Model[];
+//# sourceMappingURL=index.d.ts.map

package/dist/models/index.js

@@ -0,0 +1,49 @@
+/** Barrel for the models subsystem plus the config-aware union scan. */
+import { resolveBrainPaths } from "../config/paths.js";
+import { CatalogSchema } from "../config/schema.js";
+import { loadCatalog } from "../config/store.js";
+import { resolveModelsDirs } from "./dirs.js";
+import { enrichWithCatalog } from "./enrich.js";
+import { scan } from "./scan.js";
+export * from "./scan.js";
+export { pickModel } from "./pick.js";
+export { resolveModelsDirs, managedModelsDir } from "./dirs.js";
+export { pullModel, downloadRepoFiles, } from "./download.js";
+export { matchCatalogEntry, enrichWithCatalog } from "./enrich.js";
+export { resolveHfToken, listRepoQuants, searchModels, repoOfModel, quantRank, } from "./hf.js";
+export { diskUsage, totalModelBytes, planDelete, deleteModelFiles, } from "./manage.js";
+/** Scan every configured models directory (managed ∪ LM Studio), de-duplicated. */
+export function scanModels(config, env = process.env, options = {}) {
+    const dirs = resolveModelsDirs(config, env);
+    const seen = new Set();
+    const all = [];
+    for (const { dir, origin } of dirs) {
+        for (const model of scan({
+            modelsDir: dir,
+            withMetadata: options.withMetadata ?? true,
+            origin,
+        })) {
+            if (seen.has(model.modelPath))
+                continue;
+            seen.add(model.modelPath);
+            all.push(model);
+        }
+    }
+    const enriched = enrichWithCatalog(all, loadCatalogSafe(env));
+    enriched.sort((a, b) => a.displayName.localeCompare(b.displayName));
+    return enriched;
+}
+/**
+ * The download catalog for enrichment, or an empty catalog if it cannot be read.
+ * Discovery must never fail because the catalog file is missing or corrupt, so a
+ * load error degrades to no enrichment rather than throwing.
+ */
+function loadCatalogSafe(env) {
+    try {
+        return loadCatalog(resolveBrainPaths(env));
+    }
+    catch {
+        return CatalogSchema.parse({ models: [] });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/models/manage.d.ts

@@ -0,0 +1,27 @@
+import type { Model } from "../types.js";
+export interface DiskUsage {
+    freeBytes: number;
+    totalBytes: number;
+}
+/** Free and total bytes of the filesystem holding `dir`, or null if unavailable. */
+export declare function diskUsage(dir: string): Promise<DiskUsage | null>;
+/**
+ * Total bytes the given models occupy on disk, counting each projector once (a
+ * vision repo shares one projector across all its quants, so summing every
+ * model's mmprojBytes would over-count).
+ */
+export declare function totalModelBytes(models: Model[]): number;
+export interface DeletePlan {
+    files: string[];
+    bytes: number;
+    includesProjector: boolean;
+}
+/**
+ * Work out exactly which files deleting a model removes: its GGUF (all shards),
+ * and the paired projector ONLY when no other quant in the same repo directory
+ * still needs it. Never deletes a projector that a sibling quant shares.
+ */
+export declare function planDelete(model: Model): DeletePlan;
+/** Delete the files a {@link planDelete} chose, plus a now-empty repo directory. */
+export declare function deleteModelFiles(model: Model): DeletePlan;
+//# sourceMappingURL=manage.d.ts.map

package/dist/models/manage.js

@@ -0,0 +1,112 @@
+/**
+ * Local model management: disk-space accounting and safe deletion. Kept separate
+ * from discovery (scan) and download so the destructive path is easy to audit.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { statfs } from "node:fs/promises";
+// Same shard shape the scanner uses: `-00001-of-00003.gguf`.
+const MULTIPART = /-(\d{5})-of-(\d{5})\.gguf$/i;
+/** Free and total bytes of the filesystem holding `dir`, or null if unavailable. */
+export async function diskUsage(dir) {
+    try {
+        const s = await statfs(dir);
+        return { freeBytes: s.bavail * s.bsize, totalBytes: s.blocks * s.bsize };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Total bytes the given models occupy on disk, counting each projector once (a
+ * vision repo shares one projector across all its quants, so summing every
+ * model's mmprojBytes would over-count).
+ */
+export function totalModelBytes(models) {
+    const seenProjectors = new Set();
+    let bytes = 0;
+    for (const model of models) {
+        bytes += model.sizeBytes;
+        if (model.mmprojPath && !seenProjectors.has(model.mmprojPath)) {
+            seenProjectors.add(model.mmprojPath);
+            bytes += model.mmprojBytes;
+        }
+    }
+    return bytes;
+}
+/**
+ * Work out exactly which files deleting a model removes: its GGUF (all shards),
+ * and the paired projector ONLY when no other quant in the same repo directory
+ * still needs it. Never deletes a projector that a sibling quant shares.
+ */
+export function planDelete(model) {
+    const files = [];
+    let bytes = 0;
+    const add = (file) => {
+        try {
+            bytes += fs.statSync(file).size;
+            files.push(file);
+        }
+        catch {
+            /* already gone */
+        }
+    };
+    // The GGUF and its shards.
+    const shard = model.modelPath.match(MULTIPART);
+    if (shard) {
+        const base = model.modelPath.replace(MULTIPART, "");
+        const total = Number(shard[2]);
+        for (let i = 1; i <= total; i += 1) {
+            add(`${base}-${String(i).padStart(5, "0")}-of-${shard[2]}.gguf`);
+        }
+    }
+    else {
+        add(model.modelPath);
+    }
+    // The projector is shared across the repo's quants; only remove it if this was
+    // the last model GGUF in the directory.
+    let includesProjector = false;
+    if (model.mmprojPath) {
+        const dir = path.dirname(model.modelPath);
+        const doomed = new Set(files.map((f) => path.resolve(f)));
+        let othersRemain = false;
+        try {
+            for (const name of fs.readdirSync(dir)) {
+                if (!name.toLowerCase().endsWith(".gguf"))
+                    continue;
+                if (/^mmproj/i.test(name))
+                    continue;
+                if (doomed.has(path.resolve(dir, name)))
+                    continue;
+                othersRemain = true;
+                break;
+            }
+        }
+        catch {
+            othersRemain = true; // be conservative: keep the projector if unsure
+        }
+        if (!othersRemain) {
+            add(model.mmprojPath);
+            includesProjector = true;
+        }
+    }
+    return { files, bytes, includesProjector };
+}
+/** Delete the files a {@link planDelete} chose, plus a now-empty repo directory. */
+export function deleteModelFiles(model) {
+    const plan = planDelete(model);
+    for (const file of plan.files) {
+        fs.rmSync(file, { force: true });
+    }
+    // Remove the containing directory if we emptied it.
+    const dir = path.dirname(model.modelPath);
+    try {
+        if (fs.readdirSync(dir).length === 0)
+            fs.rmdirSync(dir);
+    }
+    catch {
+        /* not empty or gone */
+    }
+    return plan;
+}
+//# sourceMappingURL=manage.js.map

package/dist/models/pick.d.ts

@@ -0,0 +1,3 @@
+import type { Model } from "../types.js";
+export declare function pickModel(catalog: Model[], needle: string | undefined): Model;
+//# sourceMappingURL=pick.d.ts.map