Remove broken background spec fetch; use synchronous timeout

The previous 3-second-timeout-with-background-continuation design was
broken: the background thread was a daemon, so when the 3s join timeout
expired and the CLI raised, the process exited and killed the thread
before it could cache the spec. Users on slow networks would hit the
timeout on every invocation with no path forward.

Replace with a straight synchronous fetch that relies on the HTTP
client's own timeout. First call on a cold cache may take a few seconds;
every subsequent call within the TTL is served from disk. Update README
and docstring to match.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: MaorDavidzon

README.md

@@ -663,7 +663,7 @@ cycode platform projects list --page-size 100 | jq '.items[].name'
 
 - **Read-only today.** Only `GET` endpoints are exposed in this beta.
 - **Spec-driven.** Adding a new endpoint to the API surfaces it automatically the next time the cache is refreshed.
-- **No bundled spec.** The first `cycode platform` invocation after install (or after the 24h cache expires) will perform a network fetch with a 3-second timeout; if it times out, it continues fetching in the background so the next run is fast.
+- **No bundled spec.** The first `cycode platform` invocation after install (or after the 24h cache expires) performs a network fetch. On slow connections this first call may take a few seconds; subsequent calls are near-instant until the cache expires.
 - **Override the cache TTL** with `CYCODE_SPEC_CACHE_TTL=<seconds>`.
 
 

cycode/cli/apps/api/openapi_spec.py

@@ -2,7 +2,6 @@
 
 import json
 import os
-import threading
 import time
 from pathlib import Path
 from typing import Optional
@@ -20,16 +19,14 @@
 
 _OPENAPI_SPEC_PATH = '/v4/api-docs/cycode-api-swagger.json'
 
-# Short timeout for spec fetch during CLI startup to avoid blocking the regular flow.
-# If it times out, a background thread fetches the spec for the next run.
-_SPEC_FETCH_TIMEOUT_SECONDS = 3
-
 
 def get_openapi_spec(client_id: Optional[str] = None, client_secret: Optional[str] = None) -> dict:
     """Get the OpenAPI spec, using cache if fresh, otherwise fetching from API.
 
-    Uses a short timeout to avoid blocking CLI startup. If the fetch times out,
-    a background thread continues the fetch so the cache is warm for the next run.
+    The spec is only fetched when the user actually invokes `cycode platform ...`.
+    Fetch uses the HTTP client's default timeout; on a slow connection the first
+    invocation will block accordingly. Once cached, subsequent invocations within
+    the TTL are near-instant.
 
     Args:
         client_id: Optional client ID override (from CLI flags).
@@ -45,7 +42,7 @@ def get_openapi_spec(client_id: Optional[str] = None, client_secret: Optional[st
     if cached is not None:
         return cached
 
-    return _fetch_spec_with_timeout(client_id, client_secret)
+    return _fetch_and_cache_spec(client_id, client_secret)
 
 
 def _load_cached_spec() -> Optional[dict]:
@@ -84,32 +81,6 @@ def resolve_credentials(client_id: Optional[str] = None, client_secret: Optional
     return client_id, client_secret
 
 
-def _fetch_spec_with_timeout(client_id: Optional[str] = None, client_secret: Optional[str] = None) -> dict:
-    """Fetch spec with a short timeout. If it times out, fetch in background for next run."""
-    result: dict = {}
-    error: list = []
-
-    def _fetch() -> None:
-        try:
-            result['spec'] = _fetch_and_cache_spec(client_id, client_secret)
-        except Exception as e:
-            error.append(e)
-
-    thread = threading.Thread(target=_fetch, daemon=True)
-    thread.start()
-    thread.join(timeout=_SPEC_FETCH_TIMEOUT_SECONDS)
-
-    if thread.is_alive():
-        # Fetch is still running in the background - it will cache the result for next run
-        logger.debug('OpenAPI spec fetch timed out after %ds, continuing in background', _SPEC_FETCH_TIMEOUT_SECONDS)
-        raise OpenAPISpecError('OpenAPI spec fetch timed out. API commands will be available on the next run.')
-
-    if error:
-        raise error[0]
-
-    return result['spec']
-
-
 def _fetch_and_cache_spec(client_id: Optional[str] = None, client_secret: Optional[str] = None) -> dict:
     """Fetch OpenAPI spec from API and cache to disk.