smallm 0.5.0 → 0.6.0

package/README.md

@@ -10,6 +10,10 @@ Find the right small language model (SLM) for a task, based on given context.
 npm install smallm
 ```
 
+Requires Node.js 18 or newer.
+
+**Upgrading from 0.5?** v0.6.0 is a security release with a few breaking changes (no more imports from inside `dist/`, two stricter CLI flag checks, length limits on `task`/`domain`, a new default cache location). See [Upgrading from 0.5](./CHANGELOG.md#upgrading-from-05).
+
 ## Usage
 
 ```ts
@@ -53,7 +57,7 @@ await findModels({ task: "chat", contextLength: 4096, hardware: { type: "gpu", v
 await findModels({ task: "chat", contextLength: 4096, hardware: "gpu-low" }); // still works
 ```
 
-**Prerequisite for `providers: ["ollama"]`:** Ollama must be running locally (`ollama serve`, or the desktop app) and reachable at `http://localhost:11434`. If it isn't, `smallm` doesn't throw or crash the whole call — it logs a warning and simply returns no Ollama candidates, so a mixed `["huggingface", "ollama"]` query still returns your HuggingFace results.
+**Prerequisite for `providers: ["ollama"]`:** Ollama must be running locally (`ollama serve`, or the desktop app) and reachable at `http://127.0.0.1:11434` (IPv4 loopback, Ollama's default bind address). If it isn't, `smallm` doesn't throw or crash the whole call — it logs a warning and simply returns no Ollama candidates, so a mixed `["huggingface", "ollama"]` query still returns your HuggingFace results.
 
 **Important:** `HardwareSpec.vramGB` filtering uses an **estimated** footprint (~2GB VRAM per 1B params, a common fp16 rule of thumb) — not a measured or authoritative figure. It's meant to rule out obviously-too-large models, not to guarantee something fits.
 
@@ -92,7 +96,7 @@ await findModels({
 await findModels({ task: "chat", contextLength: 4096, hardware: "gpu-low" });
 ```
 
-**Ollama prerequisite:** `providers: ["ollama"]` (or including `"ollama"` in a multi-provider list) expects a local Ollama installation running at `http://localhost:11434`. If it's not running or not installed, `smallm` doesn't throw or crash the whole query — it logs a warning and simply contributes zero Ollama candidates, so a mixed `["huggingface", "ollama"]` query still returns HuggingFace results normally. Ollama itself is never installed, started, or asked to download models by this package — it only queries what's already available locally.
+**Ollama prerequisite:** `providers: ["ollama"]` (or including `"ollama"` in a multi-provider list) expects a local Ollama installation running at `http://127.0.0.1:11434`. If it's not running or not installed, `smallm` doesn't throw or crash the whole query — it logs a warning and simply contributes zero Ollama candidates, so a mixed `["huggingface", "ollama"]` query still returns HuggingFace results normally. Ollama itself is never installed, started, or asked to download models by this package — it only queries what's already available locally.
 
 **`vramGB` filtering is a heuristic, not a measured constraint.** There's no standard "how much VRAM does model X need" figure available from either provider's listing API, so `smallm` estimates it from `paramsB` using a commonly-cited rule of thumb (~2GB VRAM per 1B parameters, roughly fp16 inference). A model quantized to 4-bit would actually need much less — this estimate is conservative/pessimistic in that case. Treat `vramGB` filtering as a rough guide, not a guarantee.
 
@@ -124,16 +128,16 @@ The single public entry point. Validates the query, fetches live candidates from
 
 | Field | Type | Required | Notes |
 |---|---|---|---|
-| `task` | `"summarize" \| "classify" \| "extract" \| "chat" \| "code" \| "translate" \| string` | yes | |
+| `task` | `"summarize" \| "classify" \| "extract" \| "chat" \| "code" \| "translate" \| string` | yes | Max 512 characters |
 | `contextLength` | `number` | yes | Hard filter (tokens) |
 | `hardware` | `"cpu" \| "gpu-low" \| "gpu-high" \| { type: "cpu" \| "gpu"; vramGB?: number }` | no | String enum: required alongside `maxLatencyMs` to enforce latency filtering (v0.2). Object form (v0.4): `vramGB` enables the estimated-footprint hard filter. |
-| `domain` | `string` | no | Used in scoring, not filtering |
+| `domain` | `string` | no | Used in scoring, not filtering. Max 128 characters |
 | `maxParamsB` | `number` | no | Hard filter, e.g. `7` = "under 7B" |
 | `maxLatencyMs` | `number` | no | **v0.2:** real hard filter when a benchmark entry exists for the (model, string-enum `hardware`) pair. No entry = not enforced. |
 | `scoringMode` | `"rule" \| "embedding" \| "hybrid"` | no | **v0.3:** which scoring strategy to use. Defaults to `"rule"`. |
-| `providers` | `("huggingface" \| "ollama")[]` | no | **v0.4:** which registries to query. Defaults to `["huggingface"]`. |
+| `providers` | `("huggingface" \| "ollama")[]` | no | **v0.4:** which registries to query. Defaults to `["huggingface"]`. Duplicates are ignored. |
 | `limit` | `number` | no | Defaults to `5` |
-| `cacheOptions` | `{ dir?: string; ttlMs?: number }` | no | **v0.2:** configure the file-based cache. Defaults: OS temp dir + `/smallm-cache`, 5-minute TTL |
+| `cacheOptions` | `{ dir?: string; ttlMs?: number }` | no | **v0.2:** configure the file-based cache. Defaults: a per-user cache dir (`$XDG_CACHE_HOME/smallm`, `~/.cache/smallm`, `~/Library/Caches/smallm`, or `%LOCALAPPDATA%\smallm\cache`), 5-minute TTL. On Linux/macOS the dir must be owned by you and not world-writable. Windows UNC/network paths are rejected; ACLs of a custom Windows dir are not checked. TTLs above 7 days are clamped. If the default dir is unusable, an in-memory cache is used. Never pass untrusted input as `dir`. |
 
 ### `ModelMatch`
 
@@ -185,6 +189,8 @@ Unknown metadata (e.g. undetectable param count, no benchmark entry, unreachable
 - Ollama candidates never have a `pipeline_tag`, so the task hard filter always lets them through (same "unknown, don't exclude" rule as everywhere else) — task relevance for Ollama results relies entirely on scoring, not filtering.
 - Sub-billion-parameter models (e.g. `125M`) aren't detected by the size regex and report `paramsB: null`.
 - File-based cache only — no database engine. Cache entries are per-process-agnostic (survive restarts) but there's no cross-machine sharing.
+- **On Windows, a custom cache directory's permissions aren't checked** (Node has no ACL API). Don't point `cacheOptions.dir` / `--cache-dir` at a folder other users can write to; the default under `%LOCALAPPDATA%` is per-user. On Linux/macOS, unsafe directories are refused.
+- **Don't pass untrusted input as `cacheOptions`.** If you expose `findModels()` to end users (e.g. in a web service), build `cacheOptions` yourself rather than taking it from the request.
 
 ## CLI (v0.5, optional)
 

package/dist/cache-file.d.ts

@@ -1,23 +1,56 @@
 import { CacheOptions, HFModel } from "./types";
+/**
+ * Per-user cache directory. Deliberately NOT os.tmpdir(): on Linux/macOS
+ * that is shared and world-writable (/tmp), which let any local user
+ * pre-create the cache dir and plant poisoned entries or symlinks.
+ */
+export declare function defaultCacheDir(): string;
 /**
  * File-based TTL cache — same conceptual interface as MVP's in-memory
  * TTLCache (get/set/clear), but each entry is a JSON file on disk, so it
  * survives process restarts. No database engine, per the v0.2 guide's
  * explicit "don't introduce SQLite/Postgres/etc." rule — this is still a
  * small library, not a service.
+ *
+ * Hardening:
+ *   - the directory is re-verified before every get/set (not just once), so
+ *     a directory deleted and re-created by someone else is noticed;
+ *   - entries are written atomically (exclusive-create temp file, mode
+ *     0600, then rename — never follows a planted symlink);
+ *   - reads open with O_NOFOLLOW|O_NONBLOCK and check the open descriptor,
+ *     so a swap to a symlink/FIFO/device after the check doesn't matter,
+ *     and read at most MAX_CACHE_FILE_BYTES;
+ *   - entries whose expiry exceeds the TTL or whose value fails the
+ *     validator are discarded;
+ *   - expired files are swept periodically, with a file-count cap.
  */
 export declare class FileTTLCache<T> {
     private dir;
     private ttlMs;
-    constructor(options?: CacheOptions);
+    private isDefaultDir;
+    private validate?;
+    private lastSweep;
+    constructor(options?: CacheOptions, validate?: (value: unknown) => value is T);
+    /** Re-checks the directory; a failure makes get() miss and set() skip, never throw. */
+    private dirIsUsable;
     /** Maps a cache key to a safe filename (keys can contain arbitrary characters). */
     private filePathFor;
+    /** Reads an entry file safely, or returns undefined (and removes junk) if it isn't a small regular file. */
+    private readEntryFile;
     get(key: string): T | undefined;
+    /** Best-effort: a failed cache write never fails the caller. */
     set(key: string, value: T): void;
+    /**
+     * Removes expired entries (by mtime) and stale temp files, then trims to
+     * MAX_CACHE_FILES. Without this, an entry is only deleted if its exact key
+     * is read again, so one-off keys accumulate forever.
+     */
+    private sweep;
+    /** Removes only files this cache created (hash-named entries and leftover temp files) — never anything else in the directory. */
     clear(): void;
     private deleteFile;
 }
-/** Sets (or resets) the cache options used by fetchCandidateModelsCached. */
+/** Sets (or resets) the default cache options used when a call passes no cacheOptions. Throws if the directory is unusable. */
 export declare function configureCandidateModelsCache(options?: CacheOptions): void;
 /**
  * (v0.2) Cached wrapper around fetchCandidateModels, backed by the
@@ -32,9 +65,10 @@ export declare function fetchCandidateModelsCached(task: string): Promise<HFMode
  * requested provider's candidate list independently (keyed by
  * `${providerName}:${task}`, so HuggingFace and Ollama results for the
  * same task never collide). Not provider-specific itself — any async
- * producer of RawModel[] can use this.
+ * producer of RawModel[] can use this. Pass `options` to use a cache
+ * scoped to those options instead of the module-level default.
  */
-export declare function getOrFetchCached(key: string, fetchFn: () => Promise<HFModel[]>): Promise<HFModel[]>;
+export declare function getOrFetchCached(key: string, fetchFn: () => Promise<HFModel[]>, options?: CacheOptions): Promise<HFModel[]>;
 /** Exposed for tests that need to reset cache state between runs. */
 export declare function clearCandidateModelsCache(): void;
 //# sourceMappingURL=cache-file.d.ts.map

package/dist/cache-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache-file.d.ts","sourceRoot":"","sources":["../src/cache-file.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAWhD;;;;;;GAMG;AACH,qBAAa,YAAY,CAAC,CAAC;IACzB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,KAAK,CAAS;IAEtB,YAAY,OAAO,GAAE,YAAiB,EAIrC;IAED,mFAAmF;IACnF,OAAO,CAAC,WAAW;IAKnB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAyB9B;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAI/B;IAED,KAAK,IAAI,IAAI,CAYZ;IAED,OAAO,CAAC,UAAU;CAOnB;AAOD,6EAA6E;AAC7E,wBAAgB,6BAA6B,CAAC,OAAO,GAAE,YAAiB,GAAG,IAAI,CAE9E;AASD;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAEjF;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,GAChC,OAAO,CAAC,OAAO,EAAE,CAAC,CAQpB;AAED,qEAAqE;AACrE,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}
+{"version":3,"file":"cache-file.d.ts","sourceRoot":"","sources":["../src/cache-file.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AA+BhD;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAwBxC;AA2DD;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAY,CAAC,CAAC;IACzB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,YAAY,CAAU;IAC9B,OAAO,CAAC,QAAQ,CAAC,CAAiC;IAClD,OAAO,CAAC,SAAS,CAAK;IAEtB,YAAY,OAAO,GAAE,YAAiB,EAAE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,EAQhF;IAED,uFAAuF;IACvF,OAAO,CAAC,WAAW;IASnB,mFAAmF;IACnF,OAAO,CAAC,WAAW;IAKnB,4GAA4G;IAC5G,OAAO,CAAC,aAAa;IAqCrB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAqC9B;IAED,gEAAgE;IAChE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAgB/B;IAED;;;;OAIG;IACH,OAAO,CAAC,KAAK;IAyCb,iIAAiI;IACjI,KAAK,IAAI,IAAI,CAYZ;IAED,OAAO,CAAC,UAAU;CAOnB;AA2BD,+HAA+H;AAC/H,wBAAgB,6BAA6B,CAAC,OAAO,GAAE,YAAiB,GAAG,IAAI,CAE9E;AAiCD;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAEjF;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,EACjC,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,OAAO,EAAE,CAAC,CAgBpB;AAED,qEAAqE;AACrE,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD"}

package/dist/cache-file.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileTTLCache = void 0;
+exports.defaultCacheDir = defaultCacheDir;
 exports.configureCandidateModelsCache = configureCandidateModelsCache;
 exports.fetchCandidateModelsCached = fetchCandidateModelsCached;
 exports.getOrFetchCached = getOrFetchCached;
@@ -42,36 +43,205 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
 const crypto = __importStar(require("crypto"));
+const errors_1 = require("./errors");
 const huggingface_1 = require("./registry/huggingface");
+const validate_1 = require("./validate");
+const cache_1 = require("./cache");
 const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes — same default as MVP's in-memory cache
-const DEFAULT_DIR = path.join(os.tmpdir(), "smallm-cache");
+/** Cache files larger than this are ignored — a legit candidate list is a few KB. */
+const MAX_CACHE_FILE_BYTES = 5 * 1024 * 1024;
+/** Expired files are swept at most this often per cache instance (on set). */
+const SWEEP_INTERVAL_MS = 60 * 1000;
+/** After sweeping expired files, keep at most this many (oldest removed first). */
+const MAX_CACHE_FILES = 1000;
+/** Leftover temp files (from a crash mid-write) older than this are removed by the sweep. */
+const STALE_TEMP_MS = 60 * 1000;
+/** Only files matching these are ever read or deleted by the cache — see clear()/sweep(). */
+const CACHE_FILE_PATTERN = /^[0-9a-f]{64}\.json$/;
+const TEMP_FILE_PATTERN = /^[0-9a-f]{64}\.json\.\d+\.[0-9a-f]{16}\.tmp$/;
+/**
+ * Open flags for reading an entry: never follow a symlink (ELOOP instead)
+ * and never block on a FIFO. Both constants are POSIX-only; on Windows they
+ * are undefined and the lstat pre-check in readEntryFile() is what applies.
+ */
+const READ_FLAGS = fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0) | (fs.constants.O_NONBLOCK ?? 0);
+const isPosix = process.platform !== "win32" && typeof process.getuid === "function";
+/**
+ * Per-user cache directory. Deliberately NOT os.tmpdir(): on Linux/macOS
+ * that is shared and world-writable (/tmp), which let any local user
+ * pre-create the cache dir and plant poisoned entries or symlinks.
+ */
+function defaultCacheDir() {
+    const xdg = process.env.XDG_CACHE_HOME;
+    if (xdg && path.isAbsolute(xdg))
+        return path.join(xdg, "smallm");
+    let home = "";
+    try {
+        home = os.homedir();
+    }
+    catch {
+        // Some sandboxes have no passwd entry; fall through to the temp fallback.
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA || (home ? path.join(home, "AppData", "Local") : "");
+        if (localAppData)
+            return path.join(localAppData, "smallm", "cache");
+    }
+    else if (process.platform === "darwin" && home) {
+        return path.join(home, "Library", "Caches", "smallm");
+    }
+    else if (home) {
+        return path.join(home, ".cache", "smallm");
+    }
+    // No home directory at all (rare: some containers). Fall back to temp, but
+    // namespaced per user; ensureSafeDir() still verifies ownership.
+    const uid = typeof process.getuid === "function" ? process.getuid() : "user";
+    return path.join(os.tmpdir(), `smallm-cache-${uid}`);
+}
+function unsafeDir(reason) {
+    return new errors_1.SmallmError(`Refusing to use the cache directory: it ${reason}. Pass a different cacheOptions.dir / --cache-dir.`);
+}
+/**
+ * Creates the directory (0700) if needed and refuses one another user could
+ * tamper with. On POSIX:
+ *   - a symlink at the path itself must be owned by the current user
+ *     (blocks an attacker pre-creating the path as a link to elsewhere);
+ *   - the target must be a directory owned by the current user;
+ *   - the default directory is forced to 0700; a caller-chosen directory
+ *     must not be world-writable (group-writable is allowed so that
+ *     user-private-group setups with umask 002 keep working).
+ * Windows: the default location (%LOCALAPPDATA%) is protected by per-user
+ * ACLs. Node has no ACL API, so caller-chosen Windows paths are not checked
+ * — documented in CacheOptions.dir.
+ * Every failure is a SmallmError whose message does not include the path.
+ */
+function ensureSafeDir(dir, isDefault) {
+    try {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const linkStat = fs.lstatSync(dir);
+        if (linkStat.isSymbolicLink() && isPosix && linkStat.uid !== process.getuid()) {
+            throw unsafeDir("is a symlink owned by another user");
+        }
+        const stat = linkStat.isSymbolicLink() ? fs.statSync(dir) : linkStat;
+        if (!stat.isDirectory()) {
+            throw unsafeDir("is not a directory");
+        }
+        if (isPosix) {
+            if (stat.uid !== process.getuid()) {
+                throw unsafeDir("is owned by another user");
+            }
+            if (isDefault && (stat.mode & 0o077) !== 0) {
+                fs.chmodSync(dir, 0o700);
+            }
+            else if (!isDefault && (stat.mode & 0o002) !== 0) {
+                throw unsafeDir("is world-writable");
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof errors_1.SmallmError)
+            throw err;
+        const code = err?.code ?? "unknown error";
+        const wrapped = new errors_1.SmallmError(`Cannot use the cache directory (${code})`);
+        wrapped.cause = err;
+        throw wrapped;
+    }
+}
 /**
  * File-based TTL cache — same conceptual interface as MVP's in-memory
  * TTLCache (get/set/clear), but each entry is a JSON file on disk, so it
  * survives process restarts. No database engine, per the v0.2 guide's
  * explicit "don't introduce SQLite/Postgres/etc." rule — this is still a
  * small library, not a service.
+ *
+ * Hardening:
+ *   - the directory is re-verified before every get/set (not just once), so
+ *     a directory deleted and re-created by someone else is noticed;
+ *   - entries are written atomically (exclusive-create temp file, mode
+ *     0600, then rename — never follows a planted symlink);
+ *   - reads open with O_NOFOLLOW|O_NONBLOCK and check the open descriptor,
+ *     so a swap to a symlink/FIFO/device after the check doesn't matter,
+ *     and read at most MAX_CACHE_FILE_BYTES;
+ *   - entries whose expiry exceeds the TTL or whose value fails the
+ *     validator are discarded;
+ *   - expired files are swept periodically, with a file-count cap.
  */
 class FileTTLCache {
-    constructor(options = {}) {
-        this.dir = options.dir ?? DEFAULT_DIR;
-        this.ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
-        fs.mkdirSync(this.dir, { recursive: true });
+    constructor(options = {}, validate) {
+        this.lastSweep = 0;
+        (0, validate_1.validateCacheOptions)(options);
+        this.isDefaultDir = options.dir === undefined;
+        this.dir = path.resolve(options.dir ?? defaultCacheDir());
+        // Clamp rather than reject, so existing callers with long TTLs keep working.
+        this.ttlMs = Math.min(options.ttlMs ?? DEFAULT_TTL_MS, validate_1.MAX_CACHE_TTL_MS);
+        this.validate = validate;
+        ensureSafeDir(this.dir, this.isDefaultDir);
+    }
+    /** Re-checks the directory; a failure makes get() miss and set() skip, never throw. */
+    dirIsUsable() {
+        try {
+            ensureSafeDir(this.dir, this.isDefaultDir);
+            return true;
+        }
+        catch {
+            return false;
+        }
     }
     /** Maps a cache key to a safe filename (keys can contain arbitrary characters). */
     filePathFor(key) {
         const hash = crypto.createHash("sha256").update(key).digest("hex");
         return path.join(this.dir, `${hash}.json`);
     }
-    get(key) {
-        const filePath = this.filePathFor(key);
-        let raw;
+    /** Reads an entry file safely, or returns undefined (and removes junk) if it isn't a small regular file. */
+    readEntryFile(filePath) {
+        let linkStat;
         try {
-            raw = fs.readFileSync(filePath, "utf-8");
+            linkStat = fs.lstatSync(filePath);
         }
         catch {
-            return undefined; // file doesn't exist — not cached
+            return undefined; // not cached
+        }
+        if (!linkStat.isFile() || linkStat.size > MAX_CACHE_FILE_BYTES) {
+            this.deleteFile(filePath);
+            return undefined;
+        }
+        let fd;
+        try {
+            fd = fs.openSync(filePath, READ_FLAGS);
+        }
+        catch {
+            return undefined; // vanished, or swapped for a symlink (ELOOP)
+        }
+        try {
+            const stat = fs.fstatSync(fd);
+            if (!stat.isFile() || stat.size > MAX_CACHE_FILE_BYTES)
+                return undefined;
+            const buffer = Buffer.alloc(stat.size + 1);
+            let offset = 0;
+            while (offset < buffer.length) {
+                const n = fs.readSync(fd, buffer, offset, buffer.length - offset, null);
+                if (n === 0)
+                    break;
+                offset += n;
+            }
+            if (offset > stat.size)
+                return undefined; // grew while reading — not ours
+            return buffer.subarray(0, offset).toString("utf-8");
+        }
+        catch {
+            return undefined;
+        }
+        finally {
+            fs.closeSync(fd);
         }
+    }
+    get(key) {
+        if (!this.dirIsUsable())
+            return undefined;
+        const filePath = this.filePathFor(key);
+        const raw = this.readEntryFile(filePath);
+        if (raw === undefined)
+            return undefined;
         let entry;
         try {
             entry = JSON.parse(raw);
@@ -81,17 +251,92 @@ class FileTTLCache {
             this.deleteFile(filePath);
             return undefined;
         }
-        if (Date.now() > entry.expiresAt) {
+        if (typeof entry !== "object" || entry === null) {
             this.deleteFile(filePath);
             return undefined;
         }
-        return entry.value;
+        const { expiresAt, value } = entry;
+        const now = Date.now();
+        const valid = typeof expiresAt === "number" &&
+            Number.isFinite(expiresAt) &&
+            now <= expiresAt &&
+            // An entry claiming to live longer than our TTL wasn't written by us — reject.
+            expiresAt <= now + this.ttlMs &&
+            (this.validate ? this.validate(value) : true);
+        if (!valid) {
+            this.deleteFile(filePath);
+            return undefined;
+        }
+        return value;
     }
+    /** Best-effort: a failed cache write never fails the caller. */
     set(key, value) {
+        if (!this.dirIsUsable())
+            return;
         const filePath = this.filePathFor(key);
         const entry = { value, expiresAt: Date.now() + this.ttlMs };
-        fs.writeFileSync(filePath, JSON.stringify(entry), "utf-8");
+        const tempPath = `${filePath}.${process.pid}.${crypto.randomBytes(8).toString("hex")}.tmp`;
+        try {
+            // "wx" = O_CREAT|O_EXCL: fails if anything (including a symlink) already exists at tempPath.
+            fs.writeFileSync(tempPath, JSON.stringify(entry), { encoding: "utf-8", flag: "wx", mode: 0o600 });
+            // rename replaces the destination entry itself — a symlink there is replaced, not followed.
+            fs.renameSync(tempPath, filePath);
+        }
+        catch {
+            this.deleteFile(tempPath);
+        }
+        this.sweep();
+    }
+    /**
+     * Removes expired entries (by mtime) and stale temp files, then trims to
+     * MAX_CACHE_FILES. Without this, an entry is only deleted if its exact key
+     * is read again, so one-off keys accumulate forever.
+     */
+    sweep() {
+        const now = Date.now();
+        if (now - this.lastSweep < SWEEP_INTERVAL_MS)
+            return;
+        this.lastSweep = now;
+        let files;
+        try {
+            files = fs.readdirSync(this.dir);
+        }
+        catch {
+            return;
+        }
+        const live = [];
+        for (const file of files) {
+            const isEntry = CACHE_FILE_PATTERN.test(file);
+            const isTemp = !isEntry && TEMP_FILE_PATTERN.test(file);
+            if (!isEntry && !isTemp)
+                continue;
+            const filePath = path.join(this.dir, file);
+            let stat;
+            try {
+                stat = fs.lstatSync(filePath);
+            }
+            catch {
+                continue;
+            }
+            const age = now - stat.mtimeMs;
+            if (isTemp) {
+                if (age > STALE_TEMP_MS)
+                    this.deleteFile(filePath);
+            }
+            else if (age > this.ttlMs) {
+                this.deleteFile(filePath);
+            }
+            else {
+                live.push({ filePath, mtimeMs: stat.mtimeMs });
+            }
+        }
+        if (live.length > MAX_CACHE_FILES) {
+            live.sort((a, b) => a.mtimeMs - b.mtimeMs);
+            for (const { filePath } of live.slice(0, live.length - MAX_CACHE_FILES))
+                this.deleteFile(filePath);
+        }
     }
+    /** Removes only files this cache created (hash-named entries and leftover temp files) — never anything else in the directory. */
     clear() {
         let files;
         try {
@@ -101,7 +346,7 @@ class FileTTLCache {
             return;
         }
         for (const file of files) {
-            if (file.endsWith(".json")) {
+            if (CACHE_FILE_PATTERN.test(file) || TEMP_FILE_PATTERN.test(file)) {
                 this.deleteFile(path.join(this.dir, file));
             }
         }
@@ -116,17 +361,53 @@ class FileTTLCache {
     }
 }
 exports.FileTTLCache = FileTTLCache;
-// Module-level singleton, matching MVP's cache.ts pattern. Options are
-// applied on first use; call configureCandidateModelsCache() before the
-// first findModels() call if you need non-default dir/ttl.
+// Module-level default cache, matching MVP's cache.ts pattern. Created
+// lazily on first use; configureCandidateModelsCache() replaces it.
 let candidateModelsCache;
-/** Sets (or resets) the cache options used by fetchCandidateModelsCached. */
+/**
+ * Caches for explicit per-call cacheOptions, keyed by (dir, ttl). Per-call
+ * options never overwrite the module-level default, so one caller's
+ * options can't leak into later/concurrent calls that didn't pass any.
+ */
+const MAX_SCOPED_CACHES = 16;
+const scopedCaches = new Map();
+/**
+ * In-flight fetches keyed by cache key: concurrent identical requests share
+ * one upstream call instead of each missing the cache and fetching.
+ */
+const inflight = new Map();
+/** Sets (or resets) the default cache options used when a call passes no cacheOptions. Throws if the directory is unusable. */
 function configureCandidateModelsCache(options = {}) {
-    candidateModelsCache = new FileTTLCache(options);
+    candidateModelsCache = new FileTTLCache(options, validate_1.isRawModelArray);
 }
-function getCache() {
+function getCache(options) {
+    if (options) {
+        (0, validate_1.validateCacheOptions)(options);
+        const ttl = Math.min(options.ttlMs ?? DEFAULT_TTL_MS, validate_1.MAX_CACHE_TTL_MS);
+        const key = `${path.resolve(options.dir ?? defaultCacheDir())}\0${ttl}`;
+        let cache = scopedCaches.get(key);
+        if (!cache) {
+            // Explicitly requested directory: an unusable one is an error the caller should see.
+            cache = new FileTTLCache(options, validate_1.isRawModelArray);
+            if (scopedCaches.size >= MAX_SCOPED_CACHES) {
+                const oldest = scopedCaches.keys().next().value;
+                if (oldest !== undefined)
+                    scopedCaches.delete(oldest);
+            }
+            scopedCaches.set(key, cache);
+        }
+        return cache;
+    }
     if (!candidateModelsCache) {
-        candidateModelsCache = new FileTTLCache();
+        try {
+            candidateModelsCache = new FileTTLCache({}, validate_1.isRawModelArray);
+        }
+        catch {
+            // The default directory is unusable (e.g. pre-created by another user,
+            // read-only home). Don't fail the whole lookup over a cache: degrade to
+            // the in-memory cache for this process.
+            candidateModelsCache = new cache_1.TTLCache(DEFAULT_TTL_MS);
+        }
     }
     return candidateModelsCache;
 }
@@ -145,14 +426,22 @@ async function fetchCandidateModelsCached(task) {
  * requested provider's candidate list independently (keyed by
  * `${providerName}:${task}`, so HuggingFace and Ollama results for the
  * same task never collide). Not provider-specific itself — any async
- * producer of RawModel[] can use this.
+ * producer of RawModel[] can use this. Pass `options` to use a cache
+ * scoped to those options instead of the module-level default.
  */
-async function getOrFetchCached(key, fetchFn) {
-    const cache = getCache();
+async function getOrFetchCached(key, fetchFn, options) {
+    const cache = getCache(options);
     const cached = cache.get(key);
     if (cached)
         return cached;
-    const result = await fetchFn();
+    let pending = inflight.get(key);
+    if (!pending) {
+        pending = Promise.resolve()
+            .then(fetchFn)
+            .finally(() => inflight.delete(key));
+        inflight.set(key, pending);
+    }
+    const result = await pending;
     cache.set(key, result);
     return result;
 }

package/dist/cache-file.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache-file.js","sourceRoot":"","sources":["../src/cache-file.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,MAAY,EAAE,+BAAW;AACzB,MAAY,IAAI,iCAAa;AAC7B,MAAY,EAAE,+BAAW;AACzB,MAAY,MAAM,mCAAe;AAEjC,wDAA8D;AAE9D,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,oDAAoD;AAC1F,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,cAAc,CAAC,CAAC;AAO3D;;;;;;GAMG;AACH;IAIE,YAAY,OAAO,GAAiB,EAAE;QACpC,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC;QACtC,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,cAAc,CAAC;QAC7C,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,mFAAmF;IAC3E,WAAW,CAAC,GAAW;QAC7B,MAAM,IAAI,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,GAAG,CAAC,GAAW;QACb,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAEvC,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC,CAAC,kCAAkC;QACtD,CAAC;QAED,IAAI,KAAwB,CAAC;QAC7B,IAAI,CAAC;YACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,0EAA0E;YAC1E,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAC1B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;YAC1B,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,KAAQ;QACvB,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QACvC,MAAM,KAAK,GAAsB,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC/E,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC;IAED,KAAK;QACH,IAAI,KAAe,CAAC;QACpB,IAAI,CAAC;YACH,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;QACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;YAC7C,CAAC;QACH,CAAC;IACH,CAAC;IAEO,UAAU,CAAC,QAAgB;QACjC,IAAI,CAAC;YACH,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;QAC1B,CAAC;QAAC,MAAM,CAAC;YACP,sBAAsB;QACxB,CAAC;IACH,CAAC;CACF;;AAED,uEAAuE;AACvE,wEAAwE;AACxE,2DAA2D;AAC3D,IAAI,oBAAyD,CAAC;AAE9D,6EAA6E;AAC7E,uCAA8C,OAAO,GAAiB,EAAE;IACtE,oBAAoB,GAAG,IAAI,YAAY,CAAY,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,QAAQ;IACf,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC1B,oBAAoB,GAAG,IAAI,YAAY,EAAa,CAAC;IACvD,CAAC;IACD,OAAO,oBAAoB,CAAC;AAC9B,CAAC;AAED;;;;;;GAMG;AACI,KAAK,qCAAqC,IAAY;IAC3D,OAAO,gBAAgB,CAAC,eAAe,IAAI,EAAE,EAAE,GAAG,EAAE,CAAC,IAAA,kCAAoB,EAAC,IAAI,CAAC,CAAC,CAAC;AACnF,CAAC;AAED;;;;;;GAMG;AACI,KAAK,2BACV,GAAW,EACX,OAAiC;IAEjC,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC;IACzB,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,MAAM,GAAG,MAAM,OAAO,EAAE,CAAC;IAC/B,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACvB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,qEAAqE;AACrE;IACE,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC;AACrB,CAAC"}
+{"version":3,"file":"cache-file.js","sourceRoot":"","sources":["../src/cache-file.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -17,10 +17,14 @@ export interface ParsedCli {
     query: ModelQuery;
     json: boolean;
     showHelp: boolean;
+    /** Non-fatal notices (e.g. a flag that was overridden), printed to stderr by main(). */
+    warnings: string[];
 }
 export declare const USAGE = "Usage: smallm find [options]\n\nRequired:\n  --task <task>                Task type (chat, summarize, classify, extract, code, translate, or any custom string)\n  --context <tokens>           Required context window, in tokens\n\nOptional (map 1:1 to ModelQuery fields):\n  --max-params <billions>      Hard filter, e.g. 7 = \"under 7B\"\n  --domain <domain>            Preferred domain tag, used in scoring only\n  --hardware <cpu|gpu-low|gpu-high>   Hardware hint (original string form)\n  --hardware-type <cpu|gpu>    Hardware type (structured form \u2014 use with --hardware-vram)\n  --hardware-vram <gb>         VRAM budget in GB (structured form only)\n  --max-latency <ms>           Enforced only when benchmark data exists for the (model, hardware) pair\n  --scoring-mode <rule|embedding|hybrid>   Scoring strategy (default: rule)\n  --providers <list>           Comma-separated, e.g. huggingface,ollama (default: huggingface)\n  --limit <n>                  Max results (default: 5)\n  --cache-dir <path>           File cache directory\n  --cache-ttl <ms>             File cache TTL in ms\n\nOutput:\n  --json                       Print raw ModelMatch[] JSON instead of a table\n\nExamples:\n  npx smallm find --task summarize --context 4096\n  npx smallm find --task chat --context 8192 --max-params 7 --json\n  npx smallm find --task chat --context 4096 --providers huggingface,ollama --hardware-type gpu --hardware-vram 8\n";
 /** Pure parser: argv (already sliced past "find") -> a ModelQuery + output mode. Never touches process.exit or the network. */
 export declare function parseArgs(argv: string[]): ParsedCli;
+/** Removes control/invisible characters so text can't inject terminal escapes or visually disguise itself. */
+export declare function stripControlChars(str: string): string;
 /** Pure formatter: ModelMatch[] -> a human-readable table string. */
 export declare function formatTable(results: ModelMatch[]): string;
 /**

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAEjD;;;;;;;GAOG;AAEH,8LAA8L;AAC9L,qBAAa,aAAc,SAAQ,KAAK;aACO,QAAQ,EAAE,MAAM;IAA7D,YAAY,OAAO,EAAE,MAAM,EAAkB,QAAQ,GAAE,MAAU,EAGhE;CACF;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,eAAO,MAAM,KAAK,i6CA0BjB,CAAC;AAEF,+HAA+H;AAC/H,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAoInD;AAMD,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAmBzD;AAED;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA0C1D"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAGjD;;;;;;;GAOG;AAEH,8LAA8L;AAC9L,qBAAa,aAAc,SAAQ,KAAK;aACO,QAAQ,EAAE,MAAM;IAA7D,YAAY,OAAO,EAAE,MAAM,EAAkB,QAAQ,GAAE,MAAU,EAGhE;CACF;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;IAClB,wFAAwF;IACxF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,KAAK,i6CA0BjB,CAAC;AAEF,+HAA+H;AAC/H,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAoJnD;AAKD,8GAA8G;AAC9G,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD;AAOD,qEAAqE;AACrE,wBAAgB,WAAW,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAmBzD;AAED;;;;GAIG;AACH,wBAAsB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAkD1D"}