code-analysis-client 1.0.3__tar.gz → 1.0.5__tar.gz

{code_analysis_client-1.0.3 → code_analysis_client-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-analysis-client
-Version: 1.0.3
+Version: 1.0.5
 Summary: Async JSON-RPC client for the code-analysis MCP server (mcp-proxy-adapter JsonRpcClient)
 Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
 Requires-Python: >=3.10
@@ -75,6 +75,29 @@ async with CodeAnalysisAsyncClient(host="127.0.0.1", port=15001) as client:
 
 Use `call_unified_validated` when you need queue polling. Pass `refresh_schema=True` on a single call to bypass the in-memory schema cache.
 
+## High-level facades (aligned with server 1.0.3)
+
+The client does **not** wrap CST commands (`cst_load_file`, …) or legacy file I/O
+(`universal_file_read`, `read_project_text_file`, …). Those commands are removed
+from the server registry. Use the facades below or generic `call` / `commands.*`.
+
+| Facade | Property | Server commands |
+|--------|----------|-----------------|
+| Client DB sessions + transfer | `client.file_sessions` | `session_*`, `project_file_transfer_*`, `project_file_advisory_lock_batch` |
+| Universal edit sessions | `client.universal_files` | `universal_file_open`, `edit`, `write`, `close`, `preview` |
+| Any registered command | `client.call` / `client.commands.<name>` | schema from live `help()` |
+
+Canonical command lists: `code_analysis_client.server_api` (also exported as
+`REMOVED_COMMANDS`, `CLIENT_FACADE_COMMANDS`).
+
+Sync check (in-process registry):
+
+```bash
+pytest tests/test_client_server_api_sync.py
+```
+
+Package version matches the **code-analysis** server project (currently **1.0.4**).
+
 ## Examples (this repository)
 
 Runnable scripts live under `client/examples/`. **Long-form “man page” style

{code_analysis_client-1.0.3 → code_analysis_client-1.0.5}/README.md

@@ -63,6 +63,29 @@ async with CodeAnalysisAsyncClient(host="127.0.0.1", port=15001) as client:
 
 Use `call_unified_validated` when you need queue polling. Pass `refresh_schema=True` on a single call to bypass the in-memory schema cache.
 
+## High-level facades (aligned with server 1.0.3)
+
+The client does **not** wrap CST commands (`cst_load_file`, …) or legacy file I/O
+(`universal_file_read`, `read_project_text_file`, …). Those commands are removed
+from the server registry. Use the facades below or generic `call` / `commands.*`.
+
+| Facade | Property | Server commands |
+|--------|----------|-----------------|
+| Client DB sessions + transfer | `client.file_sessions` | `session_*`, `project_file_transfer_*`, `project_file_advisory_lock_batch` |
+| Universal edit sessions | `client.universal_files` | `universal_file_open`, `edit`, `write`, `close`, `preview` |
+| Any registered command | `client.call` / `client.commands.<name>` | schema from live `help()` |
+
+Canonical command lists: `code_analysis_client.server_api` (also exported as
+`REMOVED_COMMANDS`, `CLIENT_FACADE_COMMANDS`).
+
+Sync check (in-process registry):
+
+```bash
+pytest tests/test_client_server_api_sync.py
+```
+
+Package version matches the **code-analysis** server project (currently **1.0.4**).
+
 ## Examples (this repository)
 
 Runnable scripts live under `client/examples/`. **Long-form “man page” style

{code_analysis_client-1.0.3 → code_analysis_client-1.0.5}/code_analysis_client/__init__.py

@@ -18,6 +18,14 @@ from code_analysis_client.config import (
 )
 from code_analysis_client.exceptions import ClientValidationError
 from code_analysis_client.file_session import FileSessionClient, SessionNotFoundError
+from code_analysis_client.server_api import (
+    CLIENT_FACADE_COMMANDS,
+    CST_REMOVED_COMMANDS,
+    LEGACY_REMOVED_COMMANDS,
+    REMOVED_COMMANDS,
+    UNIVERSAL_FILE_COMMANDS,
+)
+from code_analysis_client.universal_file import UniversalFileClient
 from code_analysis_client.server_schema import (
     fetch_command_schema_from_server,
     parse_schema_from_help_payload,
@@ -28,10 +36,16 @@ from code_analysis_client.validation import (
 )
 
 __all__ = [
+    "CLIENT_FACADE_COMMANDS",
+    "CST_REMOVED_COMMANDS",
     "ClientValidationError",
     "CodeAnalysisAsyncClient",
     "FileSessionClient",
+    "LEGACY_REMOVED_COMMANDS",
+    "REMOVED_COMMANDS",
     "SessionNotFoundError",
+    "UNIVERSAL_FILE_COMMANDS",
+    "UniversalFileClient",
     "ValidatedCommandsProxy",
     "adapter_settings_from_server_config",
     "adapter_settings_to_jsonrpc_kwargs",

{code_analysis_client-1.0.3 → code_analysis_client-1.0.5}/code_analysis_client/client.py

@@ -22,6 +22,7 @@ from code_analysis_client.config import (
     load_server_config,
 )
 from code_analysis_client.file_session import FileSessionClient
+from code_analysis_client.universal_file import UniversalFileClient
 from code_analysis_client.server_schema import fetch_command_schema_from_server
 from code_analysis_client.validation import (
     prepare_params_for_schema,
@@ -122,9 +123,14 @@ class CodeAnalysisAsyncClient:
 
     @property
     def file_sessions(self) -> FileSessionClient:
-        """Session-scoped download/upload and lock workflow (no CST/universal edit details)."""
+        """Session-scoped download/upload and lock workflow (``session_*``, transfer)."""
         return FileSessionClient(self)
 
+    @property
+    def universal_files(self) -> UniversalFileClient:
+        """Universal edit-session workflow (``universal_file_*`` commands)."""
+        return UniversalFileClient(self)
+
     async def get_command_schema(
         self, command: str, *, refresh: bool = False
     ) -> Dict[str, Any]:

{code_analysis_client-1.0.3 → code_analysis_client-1.0.5}/code_analysis_client/file_session.py

@@ -15,6 +15,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Any, Dict, List, Optional, Tuple, Union
 
 from code_analysis_client.exceptions import ClientValidationError
+from code_analysis_client.responses import unwrap_command_result
 
 if TYPE_CHECKING:
     from code_analysis_client.client import CodeAnalysisAsyncClient
@@ -25,24 +26,22 @@ class SessionNotFoundError(ClientValidationError):
 
 
 def _unwrap(data: Dict[str, Any]) -> Dict[str, Any]:
-    if data.get("success"):
-        inner = data.get("data")
-        return inner if isinstance(inner, dict) else data
-    code_raw = data.get("code")
-    message = data.get("message")
-    err = data.get("error")
-    if code_raw is None and isinstance(err, dict):
-        code_raw = err.get("code")
-        if message is None:
-            message = err.get("message")
-    elif code_raw is None and isinstance(err, str):
-        code_raw = err
-    code = str(code_raw or "COMMAND_FAILED")
-    if message is None:
-        message = str(data)
-    if code == "SESSION_NOT_FOUND":
-        raise SessionNotFoundError(message, field="session_id", details=data)
-    raise ClientValidationError(message, field="command", details=data)
+    return unwrap_command_result(
+        data,
+        session_not_found_type=SessionNotFoundError,
+    )
+
+
+def _extract_file_id(payload: Dict[str, Any], *, field: str = "file_id") -> str:
+    """Return non-empty ``file_id`` from a command payload or raise."""
+    fid = str(payload.get(field) or "").strip()
+    if not fid:
+        raise ClientValidationError(
+            f"{field} missing from server response",
+            field=field,
+            details=payload,
+        )
+    return fid
 
 
 class FileSessionClient:
@@ -230,7 +229,7 @@ class FileSessionClient:
         chunk_size: Optional[int] = None,
         include_backup_history: bool = False,
     ) -> Dict[str, Any]:
-        """Start a chunked download and acquire an advisory lock (``project_file_transfer_download_begin``)."""
+        """Begin chunked download; returns payload including ``file_id`` and ``transfer_id``."""
         await self.assert_session_exists(session_id)
         params: Dict[str, Any] = {
             "session_id": session_id,
@@ -246,12 +245,14 @@ class FileSessionClient:
             params["file_path"] = file_path
         if chunk_size is not None:
             params["chunk_size"] = chunk_size
-        return _unwrap(
+        payload = _unwrap(
             await self._client.call_validated(
                 "project_file_transfer_download_begin",
                 params,
             )
         )
+        _extract_file_id(payload)
+        return payload
 
     async def download_to_path(
         self,
@@ -275,7 +276,7 @@ class FileSessionClient:
         compression: str = "identity",
         lock_mode: str = "full",
     ) -> Tuple[Dict[str, Any], Any]:
-        """Download + lock in one workflow; returns (begin_payload, download_receipt)."""
+        """Download + lock; returns (begin_payload with ``file_id``, download_receipt)."""
         begin = await self.begin_download_locked(
             session_id,
             project_id=project_id,
@@ -326,7 +327,7 @@ class FileSessionClient:
         dry_run: bool = False,
         backup: bool = True,
     ) -> Dict[str, Any]:
-        """Persist uploaded buffer and release locks (``project_file_transfer_upload_save``)."""
+        """Persist uploaded buffer and release locks; response includes ``file_id``."""
         await self.assert_session_exists(session_id)
         params: Dict[str, Any] = {
             "session_id": session_id,
@@ -341,12 +342,15 @@ class FileSessionClient:
             params["file_id"] = file_id
         if file_path is not None:
             params["file_path"] = file_path
-        return _unwrap(
+        payload = _unwrap(
             await self._client.call_validated(
                 "project_file_transfer_upload_save",
                 params,
             )
         )
+        if not dry_run:
+            _extract_file_id(payload)
+        return payload
 
     async def upload_file_and_unlock(
         self,
@@ -361,7 +365,7 @@ class FileSessionClient:
         unlock_after_write: bool = True,
         backup: bool = True,
     ) -> Dict[str, Any]:
-        """Upload bytes then save to the project file and unlock."""
+        """Upload bytes, save to project file, unlock; returns save payload with ``file_id``."""
         name = filename or (Path(file_path).name if file_path else "payload.bin")
         receipt = await self.upload_bytes(
             payload,

code_analysis_client-1.0.5/code_analysis_client/responses.py

@@ -0,0 +1,45 @@
+"""Parse JSON-RPC command envelopes from code-analysis-server."""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from code_analysis_client.exceptions import ClientValidationError
+
+
+def command_error_code(data: Dict[str, Any]) -> str:
+    """Return domain or JSON-RPC error code from a failed command response."""
+    if data.get("success") is True:
+        return ""
+    top = data.get("code")
+    if top is not None and str(top).strip():
+        return str(top).strip()
+    err = data.get("error")
+    if isinstance(err, dict):
+        nested = err.get("code")
+        if nested is not None:
+            return str(nested).strip()
+    if isinstance(err, str) and err.strip():
+        return err.strip()
+    return ""
+
+
+def unwrap_command_result(
+    data: Dict[str, Any],
+    *,
+    session_not_found_type: type[ClientValidationError] | None = None,
+) -> Dict[str, Any]:
+    """Return success ``data`` dict or raise :class:`ClientValidationError`."""
+    if data.get("success"):
+        inner = data.get("data")
+        return inner if isinstance(inner, dict) else data
+    code = command_error_code(data)
+    message = data.get("message")
+    err = data.get("error")
+    if message is None and isinstance(err, dict):
+        message = err.get("message")
+    if message is None:
+        message = str(data)
+    if code == "SESSION_NOT_FOUND" and session_not_found_type is not None:
+        raise session_not_found_type(message, field="session_id", details=data)
+    raise ClientValidationError(message, field="command", details=data)

code_analysis_client-1.0.5/code_analysis_client/server_api.py

@@ -0,0 +1,113 @@
+"""
+Canonical command names for the high-level client API vs the live server registry.
+
+The generic client (:class:`CodeAnalysisAsyncClient.call`) can invoke any command
+returned by server ``help``. Facade modules (:mod:`file_session`, :mod:`universal_file`)
+must only reference commands listed here — and every name in
+:data:`CLIENT_FACADE_COMMANDS` must be registered on the server.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import Callable, FrozenSet
+
+# Removed from the public server surface — do not use in client facades or docs.
+LEGACY_REMOVED_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "universal_file_read",
+        "universal_file_save",
+        "universal_file_replace",
+        "universal_file_delete",
+        "read_project_text_file",
+        "write_project_text_lines",
+        "create_text_file",
+        "replace_file_lines",
+    }
+)
+
+# CST tree MCP workflow — modules may exist in the repo but commands are not registered.
+CST_REMOVED_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "cst_load_file",
+        "cst_save_tree",
+        "cst_modify_tree",
+        "cst_create_file",
+        "cst_find_node",
+        "cst_get_node_info",
+        "cst_get_node_by_range",
+        "cst_get_node_at_line",
+        "cst_reload_tree",
+        "cst_convert_and_save",
+        "list_cst_blocks",
+        "query_cst",
+        "get_file_lines",
+    }
+)
+
+REMOVED_COMMANDS: FrozenSet[str] = LEGACY_REMOVED_COMMANDS | CST_REMOVED_COMMANDS
+
+FILE_SESSION_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "session_create",
+        "session_delete",
+        "session_list",
+        "session_open_file",
+        "session_close_file",
+        "session_list_file_locks",
+    }
+)
+
+TRANSFER_AND_LOCK_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "project_file_transfer_download_begin",
+        "project_file_transfer_upload_save",
+        "project_file_advisory_lock_batch",
+    }
+)
+
+UNIVERSAL_FILE_COMMANDS: FrozenSet[str] = frozenset(
+    {
+        "universal_file_open",
+        "universal_file_edit",
+        "universal_file_write",
+        "universal_file_close",
+        "universal_file_preview",
+    }
+)
+
+CLIENT_FACADE_COMMANDS: FrozenSet[str] = (
+    FILE_SESSION_COMMANDS | TRANSFER_AND_LOCK_COMMANDS | UNIVERSAL_FILE_COMMANDS
+)
+
+
+def _command_registered(get_command: Callable[[str], object], name: str) -> bool:
+    try:
+        get_command(name)
+        return True
+    except KeyError:
+        return False
+
+
+def assert_facade_commands_registered(get_command: Callable[[str], object]) -> None:
+    """Raise ``KeyError`` if any facade command is missing from the server registry."""
+    missing = [
+        name
+        for name in sorted(CLIENT_FACADE_COMMANDS)
+        if not _command_registered(get_command, name)
+    ]
+    if missing:
+        raise KeyError(f"Client facade commands not registered on server: {missing}")
+
+
+def assert_removed_commands_absent(get_command: Callable[[str], object]) -> None:
+    """Raise ``AssertionError`` if a removed command is still registered."""
+    present = [
+        name
+        for name in sorted(REMOVED_COMMANDS)
+        if _command_registered(get_command, name)
+    ]
+    if present:
+        raise AssertionError(f"Removed commands still registered: {present}")

code_analysis_client-1.0.5/code_analysis_client/universal_file.py

@@ -0,0 +1,117 @@
+"""
+Universal file edit-session workflow on top of :class:`CodeAnalysisAsyncClient`.
+
+Wraps ``universal_file_open`` / ``edit`` / ``write`` / ``close`` / ``preview`` only.
+Legacy ``universal_file_read`` / ``universal_file_save`` and CST commands are not
+part of this API (see :mod:`server_api`).
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+from code_analysis_client.responses import unwrap_command_result
+
+if TYPE_CHECKING:
+    from code_analysis_client.client import CodeAnalysisAsyncClient
+
+
+class UniversalFileClient:
+    """Edit-session workflow for project files (open → edit → write → close)."""
+
+    __slots__ = ("_client",)
+
+    def __init__(self, client: CodeAnalysisAsyncClient) -> None:
+        self._client = client
+
+    async def open(
+        self,
+        project_id: str,
+        file_path: str,
+        *,
+        create: bool = False,
+        initial_content: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Start an edit session (``universal_file_open``)."""
+        params: Dict[str, Any] = {
+            "project_id": project_id,
+            "file_path": file_path,
+            "create": create,
+        }
+        if initial_content is not None:
+            params["initial_content"] = initial_content
+        return unwrap_command_result(
+            await self._client.call_validated("universal_file_open", params)
+        )
+
+    async def edit(
+        self,
+        project_id: str,
+        session_id: str,
+        operations: List[Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Apply draft mutations (``universal_file_edit``)."""
+        return unwrap_command_result(
+            await self._client.call_validated(
+                "universal_file_edit",
+                {
+                    "project_id": project_id,
+                    "session_id": session_id,
+                    "operations": operations,
+                },
+            )
+        )
+
+    async def write(
+        self,
+        project_id: str,
+        session_id: str,
+        *,
+        write_mode: str = "commit",
+    ) -> Dict[str, Any]:
+        """Persist or preview draft (``universal_file_write``)."""
+        return unwrap_command_result(
+            await self._client.call_validated(
+                "universal_file_write",
+                {
+                    "project_id": project_id,
+                    "session_id": session_id,
+                    "write_mode": write_mode,
+                },
+            )
+        )
+
+    async def close(
+        self,
+        project_id: str,
+        session_id: str,
+    ) -> Dict[str, Any]:
+        """End edit session (``universal_file_close``)."""
+        return unwrap_command_result(
+            await self._client.call_validated(
+                "universal_file_close",
+                {
+                    "project_id": project_id,
+                    "session_id": session_id,
+                },
+            )
+        )
+
+    async def preview(
+        self,
+        project_id: str,
+        file_path: str,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """Structured read-only preview (``universal_file_preview``)."""
+        params: Dict[str, Any] = {
+            "project_id": project_id,
+            "file_path": file_path,
+        }
+        params.update(kwargs)
+        return unwrap_command_result(
+            await self._client.call_validated("universal_file_preview", params)
+        )

code_analysis_client-1.0.5/code_analysis_client/version.txt

@@ -0,0 +1 @@
+1.0.5

{code_analysis_client-1.0.3 → code_analysis_client-1.0.5}/code_analysis_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-analysis-client
-Version: 1.0.3
+Version: 1.0.5
 Summary: Async JSON-RPC client for the code-analysis MCP server (mcp-proxy-adapter JsonRpcClient)
 Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
 Requires-Python: >=3.10
@@ -75,6 +75,29 @@ async with CodeAnalysisAsyncClient(host="127.0.0.1", port=15001) as client:
 
 Use `call_unified_validated` when you need queue polling. Pass `refresh_schema=True` on a single call to bypass the in-memory schema cache.
 
+## High-level facades (aligned with server 1.0.3)
+
+The client does **not** wrap CST commands (`cst_load_file`, …) or legacy file I/O
+(`universal_file_read`, `read_project_text_file`, …). Those commands are removed
+from the server registry. Use the facades below or generic `call` / `commands.*`.
+
+| Facade | Property | Server commands |
+|--------|----------|-----------------|
+| Client DB sessions + transfer | `client.file_sessions` | `session_*`, `project_file_transfer_*`, `project_file_advisory_lock_batch` |
+| Universal edit sessions | `client.universal_files` | `universal_file_open`, `edit`, `write`, `close`, `preview` |
+| Any registered command | `client.call` / `client.commands.<name>` | schema from live `help()` |
+
+Canonical command lists: `code_analysis_client.server_api` (also exported as
+`REMOVED_COMMANDS`, `CLIENT_FACADE_COMMANDS`).
+
+Sync check (in-process registry):
+
+```bash
+pytest tests/test_client_server_api_sync.py
+```
+
+Package version matches the **code-analysis** server project (currently **1.0.4**).
+
 ## Examples (this repository)
 
 Runnable scripts live under `client/examples/`. **Long-form “man page” style

{code_analysis_client-1.0.3 → code_analysis_client-1.0.5}/code_analysis_client.egg-info/SOURCES.txt

@@ -7,7 +7,10 @@ code_analysis_client/config.py
 code_analysis_client/exceptions.py
 code_analysis_client/file_session.py
 code_analysis_client/py.typed
+code_analysis_client/responses.py
+code_analysis_client/server_api.py
 code_analysis_client/server_schema.py
+code_analysis_client/universal_file.py
 code_analysis_client/validation.py
 code_analysis_client/version.txt
 code_analysis_client.egg-info/PKG-INFO

code_analysis_client-1.0.3/code_analysis_client/version.txt

@@ -1 +0,0 @@
-1.0.3