feat: v2.7.0 — teams, cloud tokens, docs search, version caching

[StuMason]

Summary

Three new tools (35 → 38) plus version caching.

• teams — list, get, get_members, get_current, get_current_members. Wraps existing client methods.
• cloud_tokens — Hetzner/DigitalOcean: list, get, create, update, delete, validate. Wraps existing client methods.
• search_docs — Full-text search across Coolify documentation. Fetches coolify.io/docs/llms-full.txt on first call (943ms), indexes 1,545 chunks via MiniSearch (BM25), serves subsequent searches in ~1ms. Returns ~849 tokens for 5 results.
• Version caching — getVersion() caches result after first call, getCachedVersion() getter for diagnostics.

New dependency

• minisearch — 826KB, zero transitive deps, BM25 full-text search. The LLM handles semantic understanding; we just need good ranking.

Context budget

search_docs returns 5 results at ~849 tokens total. Each result: title, URL, description, 300-char snippet, score. No full pages dumped into context.

Test plan

• 262 unit tests passing (17 new: 15 docs-search, 2 version caching, method existence checks)
• Full smoke test against live Coolify server (beta.463) — all existing endpoints still work
• Teams: list, getCurrentTeam, getCurrentTeamMembers, getTeam(0), getTeamMembers(0) verified live
• Cloud tokens: full CRUD lifecycle tested live (create, get, validate, update, delete)
• search_docs: tested against real coolify.io docs — correct results for "docker compose env vars", "502 bad gateway", "health check configuration"
• Version caching: verified cache hit, getCachedVersion(), error-then-retry path
• Survived unplanned Coolify version bump (462 → 463) mid-session with zero issues
• Code review: fixed critical issue (loadAndIndex error recovery), added fetch timeout, defensive index check

[claude]

PR Review: v2.7.0 — teams, cloud tokens, docs search, version caching

Summary

A solid PR that adds 3 new tools (35 → 38), introduces a useful documentation search feature, and adds version caching. The implementation follows established patterns and includes comprehensive tests.

---

✅ What Looks Good

Code Quality:

• Clean separation of concerns in docs-search.ts (parsing vs. searching)
• Proper error handling with loading state reset on failure
• Version caching implementation is simple and effective
• New tools follow the consolidated action parameter pattern used elsewhere

Performance:

• 15-second fetch timeout with AbortController prevents hanging
• Docs are cached after first fetch (no repeated fetches)
• Concurrent loading requests are deduplicated via the loading promise
• Search results capped at 5 by default, keeping token usage low (~849 tokens)
• MiniSearch BM25 is efficient for full-text ranking

Testing:

• 253 lines of comprehensive tests for docs-search.ts
• Version caching tested including cache hit, getCachedVersion(), and error-then-retry scenarios
• Method existence checks added for all new client method references

Documentation:

• CHANGELOG, README, and CLAUDE.md all properly updated

---

🔍 Minor Observations (Non-blocking)

1. Version cache never expires
   The cached version persists for the lifetime of the server instance. If Coolify is upgraded during a long session, the cached version becomes stale. This is probably acceptable for diagnostics use cases, but worth noting.

2. Snippet extraction step size
   In getSnippet(), the step size of 50 characters might occasionally miss the optimal snippet position, but it's a reasonable performance tradeoff for the ~300 char window.

3. Reliance on external URL format
   The parseDocs() function relies on the specific format of coolify.io/docs/llms-full.txt. If Coolify changes this format, it would break. However, this is tested against the live docs per the PR description, and the error handling is robust.

---

🛡️ Security

• ✅ Fetch URL is hardcoded to coolify.io (not user-controlled)
• ✅ No credential exposure or injection vulnerabilities
• ✅ Cloud tokens tool properly validates required parameters before API calls

---

📊 Test Coverage

The PR adds 17 new tests with good coverage of:

• All docs parsing scenarios (frontmatter extraction, URL cleaning, chunking)
• Search functionality (ranking, limits, empty results, error handling)
• Concurrent loading deduplication
• Version caching behavior

---

Verdict

Looks good to merge! 🚀

The implementation is clean, follows existing patterns, and adds genuinely useful functionality. The search_docs tool will be particularly valuable for AI assistants needing Coolify documentation context.

---

🤖 Review by Claude Code