fix: detect hand-copied models in the cache root (#110)

[solderzzc]

Fixes #110.

Root cause

ModelStorage.scanDownloadedModels() accepted only two layouts under the cache root:

• models--org--name/snapshots/<hash>/ — the huggingface-cli cache layout, which additionally needs refs/main, a snapshots/main, or exactly one snapshot directory to resolve
• models/org/name/ — Swift Hub's materialized layout

Copying a model folder in by hand produces neither. The folder was skipped by the scan entirely, or reached isDownloaded() and failed because resolvedSnapshotDirectory() returned nil — either way it silently did not appear, with nothing logged to say why.

Changes

Accept the layouts users actually produce. In addition to the two above:

• models--org--name/ with the weights directly inside and no snapshots/ level
• org/name/ or a bare name/ folder copied straight into the cache root

Honour HF_HUB_CACHE. Only HF_HOME was read. Precedence now matches huggingface_hub: HF_HUB_CACHE (the hub directory itself), then HF_HOME/hub, then ~/.cache/huggingface/hub.

Fix snapshotDirectory(). It returned a synthesised …/snapshots/main path that does not exist for a hand-copied model. InferenceEngine.swift:370 hands that path to SSD expert streaming, so a detected-but-unresolvable model would have misconfigured the streaming reader instead of failing loudly. It now resolves through every supported layout and falls back to the hub path only when nothing exists.

Explain rejections. diagnoseUnrecognizedDirectories() reports folders that contain a config.json but did not make it into the scan, with the reason — missing weights, sharded weights with no model.safetensors.index.json, or leftover .incomplete files. ModelDownloadManager.refresh() logs these once per distinct set, so repeated refreshes stay quiet.

Rescan on view appear. refresh() ran only at init, after a download, and after a delete. A folder copied in while the app was open stayed invisible until relaunch.

Deletion safety. delete() walks the directories associated with an id, so a hand-copied path is included only when it actually exists, and an empty or "models" id can no longer resolve to the cache root or the layout wrapper. Covered by tests.

Also corrects two stale comments: the file header named ~/Library/Caches/huggingface/hub (wrong directory), and scanDownloadedModels() claimed to filter by ModelCatalog.all, which it does not do.

Tests

New tests/SwiftBuddyTests/ModelStorageLayoutTests.swift — 17 tests building real directory trees under a temporary cache root (ModelStorage.cacheRootOverride, added as a test hook): every accepted layout including sharded, the rejections that must stay rejected, the diagnostic reasons, snapshotDirectory resolution per layout, and deletion safety.

Also verified against a real 622MB model folder copied into a cache root exactly as the report describes (cp -RL <snapshot> <hub>/Qwen3.5-0.8B-oQ6): detected at the right size, config.json readable, max context length parsed, snapshotDirectory resolving to the copied folder, and no spurious diagnostics.

Full suite: 129 tests across 10 suites, 0 failures. PromptCacheTests and ModelLifecycleTests abort under swift test with Failed to load the default metallib — reproduced at HEAD without these changes, so pre-existing and environmental; suites were run individually.

What is not verified here

The fix is verified at the ModelStorage layer, not through the SwiftBuddy UI — loading a model end-to-end in a test needs the Metal library the test bundle cannot find. The reporter's exact directory layout is also still unknown; this covers the plausible shapes rather than a confirmed one, and the new diagnostics mean the next such report arrives with the reason attached.

🤖 Generated with Claude Code