plan-manager-client-dev 0.2.186__py3-none-any.whl

plan_manager_client/delivery/upload.py

@@ -0,0 +1,118 @@
+"""Path A digest-verified CA tree upload composition.
+
+Walks the materialized export tree, verifying each entry against its
+digest (DeliveryIntegrityContract, MRS concept C-007) BEFORE uploading it
+through the CA service's own client (CodeAnalysisClientDependency, MRS
+concept C-015) to its own destination path, so the delivered tree
+reproduces the export layout rather than a flat set of names, realizing
+the upload phase of PathACodeAnalysisDelivery (MRS concept C-003).
+"""
+
+from __future__ import annotations
+import hashlib
+from dataclasses import dataclass
+from typing import Literal
+from code_analysis_client.client import CodeAnalysisAsyncClient
+
+
+class DigestMismatchError(Exception):
+    """Raised when a tree entry's content does not match its digest.
+
+    Raised by :func:`verify_and_upload_tree` before any CA-side write is
+    attempted for the mismatched entry, per DeliveryIntegrityContract
+    (MRS concept C-007).
+    """
+    pass
+
+
+@dataclass(frozen=True)
+class PendingEntry:
+    """One export tree entry queued for digest-verified upload.
+
+    Attributes:
+        relative_path: The entry's POSIX path relative to the plan export
+            root, preserved unchanged end to end (for example
+            'G-001-x/T-001-y/atomic_steps/A-001-z.yaml').
+        destination_path: The resolved project-relative POSIX destination
+            path inside the CA project, already carrying relative_path's
+            position beneath the destination subdirectory.
+        content: The entry's unpacked content bytes.
+        declared_digest: The declared sha256 hex digest for content.
+        already_indexed: True selects UPDATE mode (upload); False selects
+            CREATE mode (upload_new).
+    """
+    relative_path: str
+    destination_path: str
+    content: bytes
+    declared_digest: str
+    already_indexed: bool
+
+
+@dataclass(frozen=True)
+class UploadResult:
+    """Outcome of one tree entry's digest-verified upload to the CA project."""
+    relative_path: str
+    destination_path: str
+    mode: Literal["create", "update"]
+    ca_file_id: str
+    success: bool
+
+
+async def verify_and_upload_tree(
+    ca_client: CodeAnalysisAsyncClient,
+    resolved_project_id: str,
+    pending_entries: list[PendingEntry],
+) -> list[UploadResult]:
+    """Digest-verify and upload each tree entry through the CA client.
+
+    Args:
+        ca_client: An already-connected CodeAnalysisAsyncClient instance
+            (MRS concept C-015); this function does not construct or close it.
+        resolved_project_id: The CA project_id to upload into.
+        pending_entries: Tree entries queued for upload, in tree order.
+
+    Returns:
+        One UploadResult per entry of pending_entries, in the same order.
+
+    Raises:
+        DigestMismatchError: If, for any entry, hashlib.sha256(entry.content)
+            .hexdigest() does not equal entry.declared_digest. Processing
+            stops at the first mismatch: no upload call is made for that
+            entry or any later entry.
+    """
+    result: list[UploadResult] = []
+    file_sessions = ca_client.file_sessions
+
+    for entry in pending_entries:
+        digest = hashlib.sha256(entry.content).hexdigest()
+
+        if digest != entry.declared_digest:
+            raise DigestMismatchError(
+                f"digest mismatch for {entry.relative_path!r} at {entry.destination_path!r}"
+            )
+
+        if entry.already_indexed is False:
+            ca_file_id = await file_sessions.upload_new(
+                project_id=resolved_project_id,
+                file_path=entry.destination_path,
+                content=entry.content,
+            )
+            mode = "create"
+        else:
+            ca_file_id = await file_sessions.upload(
+                file_id=entry.destination_path,
+                content=entry.content,
+            )
+            mode = "update"
+
+        result.append(
+            UploadResult(
+                relative_path=entry.relative_path,
+                destination_path=entry.destination_path,
+                mode=mode,
+                ca_file_id=str(ca_file_id),
+                success=True,
+            )
+        )
+
+    return result

plan_manager_client/dispatch.py

@@ -0,0 +1,380 @@
+"""Command dispatch mixin: thin async wrapper over the held JsonRpcClient.execute_command_unified.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from mcp_proxy_adapter.client.jsonrpc_client.exceptions import CommandSessionFailedError
+
+from plan_manager_client.authoring_diagnostics import (
+    AUTHORING_DIAGNOSTIC_COMMANDS,
+    emit as emit_authoring_diagnostic,
+    new_correlation_id,
+)
+from plan_manager_client.id_rule import InvalidIdentifierError, check_call_ids
+
+
+def _adapter_validation_error_result(status: object) -> dict[str, Any] | None:
+    """Return an adapter validation ErrorResult from a terminal job status.
+
+    ``queue_get_job_status`` has returned both the ErrorResult itself and the
+    queue-status envelope containing it across adapter transport paths.  Only
+    the documented result locations are considered; a failed job is otherwise
+    left as the adapter's ``CommandSessionFailedError``.
+    """
+    candidates: list[object] = [status]
+    if isinstance(status, dict):
+        candidates.extend((status.get("result"), status.get("data")))
+        result = status.get("result")
+        if isinstance(result, dict):
+            candidates.append(result.get("data"))
+            # A refused command run as a job keeps the ErrorResult one level deeper,
+            # at status.result.result and status.data.result.result, with
+            # command_execution true (bug ccb5f95f).
+            candidates.append(result.get("result"))
+        data = status.get("data")
+        if isinstance(data, dict):
+            data_result = data.get("result")
+            if isinstance(data_result, dict):
+                candidates.append(data_result.get("result"))
+
+    for candidate in candidates:
+        if not isinstance(candidate, dict):
+            continue
+        error = candidate.get("error")
+        if (
+            candidate.get("success") is False
+            and isinstance(error, dict)
+            and error.get("code") == -32602
+        ):
+            return candidate
+
+    # The server's pre-execution refusals (command_execution false) and "Method not
+    # found" keep a bare ``{status: "error", code, message, data}`` result at
+    # status.data.result / status.result, with no success/error keys (bug ccb5f95f).
+    if isinstance(status, dict):
+        bare_candidates: list[object] = []
+        for holder in (status.get("result"), status.get("data")):
+            bare_candidates.append(holder)
+            if isinstance(holder, dict):
+                bare_candidates.append(holder.get("result"))
+        for bare in bare_candidates:
+            if (
+                isinstance(bare, dict)
+                and bare.get("status") == "error"
+                and bare.get("code") in _BARE_REFUSAL_CODES
+                and isinstance(bare.get("message"), str)
+            ):
+                bare_data = bare.get("data")
+                return {
+                    "success": False,
+                    "error": {
+                        "code": bare["code"],
+                        "message": bare["message"],
+                        "data": bare_data if isinstance(bare_data, dict) else {},
+                    },
+                }
+
+    # A command that EXECUTED and ended with its own ErrorResult (command_execution true,
+    # job_success false) keeps that ErrorResult at status.data.result.result (bug 970e0443:
+    # ``help`` with an unknown cmdname, code -32601). The caller gets the job's own error
+    # envelope, as for a non-queued command, never a CommandSessionFailedError.
+    if isinstance(status, dict):
+        executed = status.get("data")
+        if (
+            isinstance(executed, dict)
+            and executed.get("status") == "failed"
+            and executed.get("command_execution") is True
+            and executed.get("job_success") is False
+        ):
+            executed_result = executed.get("result")
+            inner = executed_result.get("result") if isinstance(executed_result, dict) else None
+            if (
+                isinstance(inner, dict)
+                and inner.get("success") is False
+                and isinstance(inner.get("error"), dict)
+                and isinstance(inner["error"].get("code"), int)
+                and isinstance(inner["error"].get("message"), str)
+            ):
+                return inner
+
+    # A command-session failure persists the queue terminal status instead of
+    # the ErrorResult. Adapter pre-execution validation failures retain an
+    # unambiguous status discriminator and the original ValidationError message.
+    status_data = status.get("data") if isinstance(status, dict) else None
+    if not isinstance(status_data, dict):
+        return None
+    message = status_data.get("error")
+    if message is None:
+        # A ValidationError raised by a command's own ``validate_params`` inside
+        # the queue worker leaves ``error`` null; the text survives only in
+        # ``description`` / ``result.message`` behind the worker's prefix.
+        prefix = "Command execution failed: "
+        result_part = status_data.get("result")
+        for key_text in (
+            status_data.get("description"),
+            result_part.get("message") if isinstance(result_part, dict) else None,
+        ):
+            if isinstance(key_text, str) and key_text.startswith(prefix):
+                message = key_text.removeprefix(prefix)
+                break
+    if not (
+        status_data.get("status") == "failed"
+        and status_data.get("command_execution") is False
+        and status_data.get("job_success") is False
+        and isinstance(message, str)
+    ):
+        return None
+
+    missing_prefix = "Missing required parameters: "
+    if message.startswith(missing_prefix):
+        missing_parameters = [
+            parameter.strip()
+            for parameter in message.removeprefix(missing_prefix).split(",")
+            if parameter.strip()
+        ]
+        if not missing_parameters:
+            return None
+        return {
+            "success": False,
+            "error": {
+                "code": -32602,
+                "message": message,
+                "data": {"missing_parameters": missing_parameters, "violation": "missing"},
+            },
+        }
+
+    # Value messages (``must be one of`` / ``must be false when`` ...) are tried BEFORE the
+    # generic type pattern: ``[^,]+`` in the type regex also matches ``be false when hard=true (...)``.
+    value_error = re.fullmatch(
+        r"[A-Za-z_][A-Za-z0-9_]*: parameter '(?P<field>[^']+)' must (?:be one of|be >=|be <=|be at least|be at most|match pattern|be false when) .*",
+        message,
+        flags=re.S,
+    )
+    if value_error is not None:
+        return {
+            "success": False,
+            "error": {
+                "code": -32602,
+                "message": message,
+                "data": {"field": value_error.group("field"), "violation": "value"},
+            },
+        }
+
+    type_error = re.fullmatch(
+        r"[A-Za-z_][A-Za-z0-9_]*: parameter '(?P<field>[^']+)' "
+        r"must be (?P<expected>[^,]+), got (?P<got>[A-Za-z_][A-Za-z0-9_]*)",
+        message,
+    )
+    if type_error is not None:
+        return {
+            "success": False,
+            "error": {
+                "code": -32602,
+                "message": message,
+                "data": {
+                    "field": type_error.group("field"),
+                    "violation": "type",
+                    "expected": type_error.group("expected"),
+                    "got": type_error.group("got"),
+                },
+            },
+        }
+
+    # The adapter's own phase-1 texts carry their violation class; the queue keeps only
+    # the text, so restore the structured ``data`` the direct (non-queued) path returns.
+    unknown_match = re.fullmatch(r"Invalid parameters: (?P<names>.+?)\. Allowed parameters: .*", message, flags=re.S)
+    if unknown_match is not None:
+        return {
+            "success": False,
+            "error": {
+                "code": -32602,
+                "message": message,
+                "data": {
+                    "invalid_parameters": [n.strip() for n in unknown_match.group("names").split(",") if n.strip()],
+                    "violation": "unknown",
+                },
+            },
+        }
+
+    # The adapter keeps no structured code on a failed queue job: only the
+    # exception text survives.  A job that failed with ``command_execution`` False
+    # (checked above) never reached ``execute()``; the adapter turns every
+    # domain/runtime failure inside ``execute()`` into a completed ErrorResult, so
+    # an exception escaping ``Command.run()`` before that point is the
+    # parameter-validation phase (``validate_params``: unknown/missing/typed/
+    # vocabulary/UUID-format parameters).  Messages of that phase are free text
+    # (command-specific), so they cannot all be enumerated.  Queue lifecycle
+    # failures (stopped, timed out, worker crash, deleted) are NOT validation and
+    # must stay a CommandSessionFailedError.
+    lowered = message.lower()
+    if not message.startswith(_UNKNOWN_PARAMETERS_PREFIX) and any(
+        marker in lowered for marker in _NON_VALIDATION_MARKERS
+    ):
+        return None
+    return {
+        "success": False,
+        "error": {
+            "code": -32602,
+            "message": message,
+            "data": {"recovered_from": "queued_job_status", "violation": _relation_violation(lowered)},
+        },
+    }
+
+
+def _relation_violation(lowered: str) -> str:
+    """Classify a free-text ``validate_params`` relation failure into the adapter vocabulary."""
+    if "must be absent" in lowered:
+        return "unknown"
+    if " is required" in lowered or " requires " in lowered:
+        return "missing"
+    return "value"
+
+
+_BARE_REFUSAL_CODES = (-32602, -32601)
+_UNKNOWN_PARAMETERS_PREFIX = "Invalid parameters: "
+_NON_VALIDATION_MARKERS = (
+    "timed out",
+    "was stopped",
+    "was terminated",
+    "was cancelled",
+    "was canceled",
+    "job deleted",
+    "traceback",
+    "internal error",
+)
+
+
+async def _queued_validation_error_result(
+    rpc: Any, exc: CommandSessionFailedError
+) -> dict[str, Any] | None:
+    """Recover only a terminal adapter validation result from a failed session."""
+    details = getattr(exc, "details", None)
+    if not isinstance(details, dict):
+        return None
+    terminal_event = details.get("terminal_event")
+    if not isinstance(terminal_event, dict):
+        return None
+    job_id = terminal_event.get("job_id")
+    if not isinstance(job_id, str) or not job_id:
+        return None
+
+    try:
+        status = await rpc.queue_get_job_status(job_id)
+    except Exception:
+        # A status retrieval failure must not change the command failure that
+        # the adapter already classified.
+        return None
+    return _adapter_validation_error_result(status)
+
+
+class _CommandDispatchMixin:
+    """Mixin providing the single dispatch point used by every command-family mixin.
+
+    Assumes it is mixed into a class that stores a composed JsonRpcClient on the
+    instance attribute ``self._rpc`` (an instance of
+    mcp_proxy_adapter.client.jsonrpc_client.client.JsonRpcClient), which supplies
+    the coroutine:
+
+        async def execute_command_unified(
+            self,
+            command: str,
+            params: Optional[Dict[str, Any]] = None,
+            *,
+            use_cmd_endpoint: bool = False,
+            expect_queue: Optional[bool] = None,
+            auto_poll: bool = True,
+            poll_interval: float = 1.0,
+            timeout: Optional[float] = None,
+            status_hook: Optional[Callable[[Dict[str, Any]], Awaitable[None]]] = None,
+            manual_event_handling: bool = False,
+        ) -> Any
+
+    which returns {"mode": "immediate", "result": ...} for immediate commands or
+    {"mode": "queued", "job_id": ..., "status": ..., "result": ...} for commands
+    the server ran via the queue (auto_poll=True waits for completion via
+    WebSocket before returning, applying queue_get_job_status semantics). The
+    composed JsonRpcClient is held, never inherited, so no transport coroutine
+    leaks onto the public facade surface.
+    """
+
+    async def _call(self, command: str, params: dict[str, Any] | None = None) -> Any:
+        """Dispatch one plan_manager command and return its unwrapped result.
+
+        Always calls self._rpc.execute_command_unified(command, params, auto_poll=True)
+        so a queued command is auto-polled to completion (queue_get_job_status
+        semantics) before this coroutine returns. The held JsonRpcClient's
+        configured timeout is forwarded unchanged so the adapter's own terminal
+        wait remains bounded by the caller-selected budget. Returns the "result"
+        value from the unified response for both immediate and queued commands.
+        """
+        try:
+            check_call_ids(params, command)  # uuid4 discipline (block 2, D7): an invalid identifier is refused before the call is sent
+        except InvalidIdentifierError as refusal:
+            # The refusal is the command's own answer (-32602, violation value), never an exception out of the facade (0153 GI2).
+            return refusal.as_answer()
+        diagnostic = command in AUTHORING_DIAGNOSTIC_COMMANDS
+        correlation_id = new_correlation_id() if diagnostic else ""
+        if diagnostic:
+            emit_authoring_diagnostic(
+                "client.dispatch.start",
+                command=command,
+                correlation_id=correlation_id,
+                parameters=params or {},
+            )
+        try:
+            response = await self._rpc.execute_command_unified(  # type: ignore[attr-defined]
+                command,
+                params or {},
+                auto_poll=True,
+                timeout=getattr(self._rpc, "timeout", None),  # type: ignore[attr-defined]
+            )
+        except CommandSessionFailedError as exc:
+            validation_error = await _queued_validation_error_result(self._rpc, exc)
+            if validation_error is not None:
+                if diagnostic:
+                    emit_authoring_diagnostic(
+                        "client.response.error",
+                        command=command,
+                        correlation_id=correlation_id,
+                        parameters=params or {},
+                        error=validation_error,
+                    )
+                return validation_error
+            if diagnostic:
+                emit_authoring_diagnostic(
+                    "client.response.error",
+                    command=command,
+                    correlation_id=correlation_id,
+                    parameters=params or {},
+                    error=exc,
+                )
+            raise
+        result = response.get("result")
+        if diagnostic:
+            event = "client.response.error" if _is_error_result(result) else "client.response.success"
+            emit_authoring_diagnostic(
+                event,
+                command=command,
+                correlation_id=correlation_id,
+                parameters=params or {},
+                result=None if event.endswith("error") else result,
+                error=result if event.endswith("error") else None,
+            )
+        return result
+
+
+def _is_error_result(result: object) -> bool:
+    return (
+        isinstance(result, dict)
+        and result.get("success") is False
+        and isinstance(result.get("error"), dict)
+    )
+
+
+__all__ = ["_CommandDispatchMixin"]

plan_manager_client/export_fetch_chunks.py

@@ -0,0 +1,166 @@
+"""Chunked retrieval and in-memory reassembly of exported plan files (Path B).
+
+The plan_manager server serves exported files only through the export_read command, which
+returns a bounded base64 chunk of one file together with the whole file's size, its sha256
+digest, and an end-of-file marker. This module drives that command in a loop to reassemble
+each requested file byte-identically in memory. Nothing here touches the filesystem and
+nothing here verifies the digest: the reassembled buffer carries the digest the server
+declared so a later verification gate can check it before any byte is persisted.
+"""
+
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from typing import Any, Protocol, Sequence
+
+# Maximum number of DECODED bytes export_read returns in a single chunk.
+MAX_CHUNK_BYTES: int = 262144
+
+
+class ExportChunkProtocolError(RuntimeError):
+    """Raised when an export_read chunk sequence cannot be reassembled.
+
+    Covers a chunk that makes no progress before the end-of-file marker, a file whose
+    declared size or digest changes between chunks, and a reassembled length that
+    disagrees with the declared total size. It names only the plan-relative file name:
+    it never carries connection, credential, or server-side path information.
+    """
+
+    def __init__(self, filename: str, detail: str) -> None:
+        super().__init__(f"export chunk protocol error for {filename!r}: {detail}")
+        self.filename = filename
+        self.detail = detail
+
+
+class SupportsExportRead(Protocol):
+    """The single export_read call this module needs from a client facade."""
+
+    async def export_read(
+        self, plan: str, file: str, offset: int = 0, limit: int = MAX_CHUNK_BYTES
+    ) -> dict[str, Any]:
+        ...
+
+
+@dataclass(frozen=True)
+class ReassembledFile:
+    """One exported file reassembled in memory, pending digest verification.
+
+    Attributes:
+        filename: The plan-relative name of the file, exactly as requested from the server.
+        content: The fully reassembled bytes of the file, in original order.
+        declared_total_size: The whole-file size the server declared for this file.
+        declared_sha256: The whole-file hex sha256 digest the server declared for this file.
+    """
+
+    filename: str
+    content: bytes
+    declared_total_size: int
+    declared_sha256: str
+
+
+async def fetch_export_file(
+    client: SupportsExportRead,
+    plan: str,
+    file: str,
+    chunk_limit: int = MAX_CHUNK_BYTES,
+) -> ReassembledFile:
+    """Reassemble one exported file in memory by looping export_read.
+
+    Args:
+        client: An object exposing the export_read coroutine.
+        plan: The plan identifier whose export directory owns the file.
+        file: The plan-relative path of the file to retrieve.
+        chunk_limit: Maximum decoded bytes to request per chunk; must be in [1, 262144].
+
+    Returns:
+        The ReassembledFile carrying the file's bytes and the server-declared size and digest.
+
+    Raises:
+        ValueError: If chunk_limit is outside [1, 262144].
+        ExportChunkProtocolError: If the chunk sequence cannot be reassembled.
+    """
+    if chunk_limit < 1 or chunk_limit > MAX_CHUNK_BYTES:
+        raise ValueError(f"chunk_limit must be an integer in [1, {MAX_CHUNK_BYTES}]")
+
+    buffer = bytearray()
+    offset = 0
+    declared_total_size: int | None = None
+    declared_sha256: str | None = None
+
+    while True:
+        response = await client.export_read(
+            plan=plan, file=file, offset=offset, limit=chunk_limit
+        )
+        total_size = int(response["total_size"])
+        sha256 = str(response["sha256"])
+        if declared_total_size is None:
+            declared_total_size = total_size
+            declared_sha256 = sha256
+        elif total_size != declared_total_size or sha256 != declared_sha256:
+            raise ExportChunkProtocolError(
+                file, "declared size or digest changed between chunks"
+            )
+
+        chunk = base64.b64decode(response["chunk_base64"])
+        eof = bool(response["eof"])
+        if not chunk and not eof:
+            raise ExportChunkProtocolError(
+                file, "server returned an empty chunk before the end of the file"
+            )
+
+        buffer.extend(chunk)
+        offset += len(chunk)
+        if eof:
+            break
+
+    if declared_total_size is None or declared_sha256 is None:
+        raise ExportChunkProtocolError(file, "no chunk was returned")
+    if len(buffer) != declared_total_size:
+        raise ExportChunkProtocolError(
+            file, "reassembled length does not match the declared total size"
+        )
+
+    return ReassembledFile(
+        filename=file,
+        content=bytes(buffer),
+        declared_total_size=declared_total_size,
+        declared_sha256=declared_sha256,
+    )
+
+
+async def fetch_export_files(
+    client: SupportsExportRead,
+    plan: str,
+    files: Sequence[str],
+    chunk_limit: int = MAX_CHUNK_BYTES,
+) -> list[ReassembledFile]:
+    """Reassemble every named exported file, in the order given.
+
+    Args:
+        client: An object exposing the export_read coroutine.
+        plan: The plan identifier whose export directory owns the files.
+        files: The plan-relative paths of the files to retrieve.
+        chunk_limit: Maximum decoded bytes to request per chunk; must be in [1, 262144].
+
+    Returns:
+        One ReassembledFile per requested file, in the same order as files.
+
+    Raises:
+        ValueError: If chunk_limit is outside [1, 262144].
+        ExportChunkProtocolError: If any file's chunk sequence cannot be reassembled.
+    """
+    return [
+        await fetch_export_file(client, plan, file, chunk_limit=chunk_limit)
+        for file in files
+    ]
+
+
+__all__ = [
+    "MAX_CHUNK_BYTES",
+    "ExportChunkProtocolError",
+    "ReassembledFile",
+    "SupportsExportRead",
+    "fetch_export_file",
+    "fetch_export_files",
+]