fix(cli): survive incomplete global-cache state instead of crashing with ENOENT

[Kamirus]

Commands that regenerate a stale mops.lock — mops add, update, sync, remove — crashed with a raw Node ENOENT: no such file or directory ... mops.toml whenever the project's dependency graph contains version conflicts and the previous install was lock-driven.

Root cause: installing from a valid lock deliberately downloads only the versions that won a conflict, but regenerating a stale lock re-walks the graph and reads every declared version's manifest from the global cache — including the losers that were never downloaded. Validation (--locked) was made walk-free earlier on this line, but regeneration was not, so the first mops add after a lock-driven install opened a manifest that could not exist. The crash evaded tests because a plain no-lock mops install installs the full graph recursively, so the cache always happened to contain the losers.

The fix makes the cache self-healing at every read site instead of assuming install left the right state on disk:

• Fetch-on-miss in the graph walk (resolve-packages.ts): a registry manifest missing from the cache is downloaded before it is read; if the download fails the command reports which package could not be fetched. Uncached GitHub deps are also fetched, so their transitive deps are no longer silently dropped from resolution.
• isDepCached requires a complete entry (cache.ts): registry packages must contain mops.toml, GitHub packages must be non-empty. Leftover empty dirs from interrupted pre-staging runs (or a bad shared cache volume) are deleted and re-downloaded instead of counting as hits — this also fixes the same ENOENT at install-mops-dep.ts's post-hit manifest read.
• .mops syncing restores missing packages (sync-local-cache.ts): a resolved winner absent from the global cache is downloaded before the copy, and a real error surfaces instead of throw undefined (the old catch assumed ncp's array-of-errors shape).
• Requirements checks are non-fatal (check-requirements.ts): the advisory moc/lintoko minimum-version check falls back to the global-cache manifest and skips the package rather than crashing.

Before (second machine with a committed lock, after mops install):

$ mops add base@0.16.0
Checking integrity...
Error: ENOENT: no such file or directory, open '~/.cache/mops/packages/core@2.6.1/mops.toml'

After:

$ mops add base@0.16.0
Package installed base = "0.16.0"

Both regression tests were verified to fail with this exact ENOENT signature before the fix. They isolate the global cache via XDG_CACHE_HOME, so they don't disturb the developer's real cache.

What is unchanged

The alternative fix — having add/update/sync reinstall the full graph before regenerating the lock — is intentionally not taken: fetch-on-miss repairs exactly the gap and keeps those commands fast. Conflict-winner resolution, lock format, and --locked semantics are untouched; no command-line surface changes, so no docs updates.

🤖 Generated with Claude Code

[github-actions]

Cursor AI review

👍 APPROVE — looks safe to merge

Category	Assessment	Details
Summary	✅	Fixes ENOENT crashes when regenerating a stale lock after a lock-driven install by fetch-on-miss in resolvePackages, tightening isDepCached completeness, restoring missing packages in syncLocalCache, and soft-failing advisory checkRequirements.
Code Quality	✅	Reuses installMopsDep / installFromGithub with ignoreTransitive: true at the miss sites instead of new download helpers; changelog under ## Next matches the user-facing fix.
Consistency	✅	Error wording and silent-install options match existing install paths; no CLI flag/mops.toml surface change, so docs/skills omission is appropriate.
Security	✅	Traced downloads only through existing installMopsDep / installFromGithub (same registry/GitHub extractors); no auth, integrity-hash, or lock-format changes — checkLockFileLight early-return and winner selection in collectDeps unchanged.
Tests	✅	cli/tests/cache-resilience.test.ts isolates cache via XDG_CACHE_HOME, reproduces lock-driven winner-only cache + mops add and empty-dir miss; targeted assertions (not snapshots) fit corner-case guidance; fixture correctly keeps root core@1.0.0 over nested core@2.6.1.
Maintainability	✅	Self-healing at read/sync sites is localized; syncLocalCache catch now handles non-array rejects (throw undefined fix) without broadening behavior.

Verdict

Decision: APPROVE
Risk: Low
Reason: High-risk paths are touched, but behavior matches the already-correct complete-cache walk: winners, lock format, and --locked short-circuit are unchanged; the PR only fetches missing manifests/packages that a full install would already have populated, with focused regression coverage.

---

Generated for commit cddcf1a

[automation-sa-sre]

Automated approval: the AI review verdict for cddcf1a is APPROVE. See the "Cursor AI review" comment for details.