plan-manager-client 0.2.149__tar.gz → 0.2.151__tar.gz

{plan_manager_client-0.2.149 → plan_manager_client-0.2.151}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plan-manager-client
-Version: 0.2.149
+Version: 0.2.151
 Summary: First-class client library for the plan_manager JSON-RPC API: full command-surface facade plus export delivery module boundary.
 Requires-Python: >=3.12
 Requires-Dist: mcp-proxy-adapter==8.11.3

{plan_manager_client-0.2.149 → plan_manager_client-0.2.151}/plan_manager_client/client.py

@@ -65,6 +65,11 @@ class PlanManagerClient(
         canonical command methods.
         """
         self._rpc = JsonRpcClient(**jsonrpc_kwargs)
+        # Chain the cooperative initialisers of every mixin in the MRO (for example
+        # RuntimeCommandsMixin, which creates runtimeOverlayPart and
+        # runtimeAuthoringPart). Called without arguments: the mixins take none, and
+        # object.__init__ rejects keyword arguments.
+        super().__init__()
 
 
 __all__ = ["PlanManagerClient"]

{plan_manager_client-0.2.149 → plan_manager_client-0.2.151}/plan_manager_client/export_fetch_request.py

@@ -18,7 +18,7 @@ class SupportsExportProduction(Protocol):
     """The two calls this module needs from a client facade."""
 
     async def plan_export(
-        self, plan: str, revision: str | None = None
+        self, plan: str, revision: str | None = None, include_step_uuids: bool = False
     ) -> dict[str, Any]:
         ...
 
@@ -47,6 +47,7 @@ async def request_export_archive(
     client: SupportsExportProduction,
     plan: str,
     revision: str | None = None,
+    include_step_uuids: bool = False,
 ) -> ExportArchiveRef:
     """Produce a plan's export tree and obtain the reference to its archive.
 
@@ -60,12 +61,17 @@ async def request_export_archive(
         plan: The plan identifier whose export tree is produced and archived.
         revision: Optional revision passed to the export production call only; when None
             that call uses its own default revision selection.
+        include_step_uuids: When True the export descriptors carry step_uuid (bug 62cff4e4
+            part b); forwarded to plan_export only when True.
 
     Returns:
         The ExportArchiveRef naming exactly one archive file, with its size, declared
         whole-file digest, and packed-file count.
     """
-    await client.plan_export(plan=plan, revision=revision)
+    export_params: dict[str, Any] = {"plan": plan, "revision": revision}
+    if include_step_uuids:
+        export_params["include_step_uuids"] = True
+    await client.plan_export(**export_params)
     response = await client.export_archive(plan=plan)
     return ExportArchiveRef(
         name=str(response["archive"]),

{plan_manager_client-0.2.149 → plan_manager_client-0.2.151}/plan_manager_client/facade_context_gate_mixin.py

@@ -76,6 +76,10 @@ class ContextGateCommandsMixin:
         """Read one declared matrix namespace of a plan with its content_hash (parameters passed through; the server validates them)."""
         return await self._call("matrix_namespace_get", params)
 
+    async def matrix_case_get(self, **params: Any) -> Any:
+        """Read one matrix case of a plan by namespace and case_id; a case marked deleted is read with its mark (parameters passed through)."""
+        return await self._call("matrix_case_get", params)
+
     async def matrix_lint(self, **params: Any) -> Any:
         """Lint the matrix parts of a plan and page the defects (parameters passed through)."""
         return await self._call("matrix_lint", params)

plan_manager_client-0.2.151/plan_manager_client/facade_hrs_file_mixin.py

@@ -0,0 +1,201 @@
+"""HRS file-transfer client wrappers (import half): hrs_import_file.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+
+These two methods are client-side compositions of server commands, not
+server commands themselves; they are exempted in
+plan_manager_client.server_api.FILE_WRAPPER_NAMES.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import uuid
+from pathlib import Path
+from typing import Any, Callable
+
+
+def _require_bare_filename(filename: str) -> None:
+    """Refuse any filename that is not a single plain path component."""
+    if (
+        not filename
+        or filename in (".", "..")
+        or "/" in filename
+        or "\\" in filename
+        or os.path.basename(filename) != filename
+    ):
+        raise ValueError(f"filename must be a bare file name, got {filename!r}")
+
+
+def _require_uploadable_file(path: str) -> None:
+    """Check the local source before any request: regular, readable and non-empty."""
+    with open(path, "rb"):
+        pass
+    if os.path.getsize(path) == 0:
+        raise ValueError(f"file is empty: {path}")
+
+
+def _reply_payload(reply: Any) -> Any:
+    """Return the command outcome ({success, data|error}) of a reply.
+
+    The client's _call returns the queued-command job envelope
+    {job_id, command, result: {success, data}, status}; a bare outcome is
+    returned unchanged.
+    """
+    if isinstance(reply, dict) and isinstance(reply.get("result"), dict) and "success" in reply["result"]:
+        return reply["result"]
+    return reply
+
+
+class HrsFileCommandsMixin:
+    """Client-side wrappers that move a local file through the server transfer path.
+
+    Assumes it is mixed into a class that provides the held JSON-RPC client
+    as self._rpc (upload_file) and the coroutine
+    async def _call(self, command: str, params: dict[str, Any] | None = None) -> Any.
+    """
+
+    async def hrs_import_file(
+        self,
+        plan: str,
+        path: str,
+        *,
+        dry_run: bool = True,
+        convert: bool = False,
+        filename: str | None = None,
+        compression: str = "identity",
+        chunk_size: int | None = None,
+        on_progress: Callable[[int, int], None] | None = None,
+    ) -> Any:
+        """Upload a local HRS file, then import it with hrs_import(source=filename).
+
+        Validation (bare filename, readable non-empty file) happens before any
+        request. The uploaded file's sha256 must match the transfer receipt
+        before hrs_import is called. A server error result is returned as is.
+        """
+        if filename is None:
+            filename = f"hrs-import-{uuid.uuid4()}.md"
+        else:
+            _require_bare_filename(filename)
+        _require_uploadable_file(path)
+
+        receipt = await self._rpc.upload_file(
+            path,
+            filename=filename,
+            compression=compression,
+            chunk_size=chunk_size,
+            on_progress=on_progress,
+        )
+        saved = await self._call(
+            "export_upload_save",
+            {"transfer_id": receipt.transfer_id, "filename": filename},
+        )
+        payload = _reply_payload(saved)
+        if isinstance(payload, dict) and payload.get("success") is False:
+            return saved
+        body = payload.get("data") if isinstance(payload.get("data"), dict) else payload
+        if body.get("sha256") != receipt.checksum_value:
+            raise ValueError(
+                f"uploaded file checksum mismatch for {filename}: "
+                f"expected {receipt.checksum_value}, saved {body.get('sha256')}"
+            )
+
+        params: dict[str, Any] = {"plan": plan, "source": filename, "dry_run": dry_run}
+        if convert:
+            params["convert"] = True
+        return await self._call("hrs_import", params)
+
+
+    async def hrs_export_file(
+        self,
+        plan: str,
+        path: str,
+        *,
+        overwrite: bool = False,
+        compression: str = "identity",
+        chunk_size: int | None = None,
+        on_progress: Callable[[int, int], None] | None = None,
+    ) -> Any:
+        """Export a plan to a local file: hrs_export(target file), export_download_begin, download, sha256 check.
+
+        The export file stays on the server until the sweep timer removes it after its lifetime (no confirm
+        command). The download goes to a temporary file next to the destination; the destination is replaced
+        only by the final rename, after the sha256 of the downloaded bytes equals the export sha256. Without
+        overwrite an existing destination is refused after the verified download. A server error reply is
+        returned unchanged. A path that is empty or None is refused before any request.
+        """
+        destination = _require_destination(path)
+        _require_writable_destination(destination, overwrite)
+        exported = _reply_payload(await self._call("hrs_export", {"plan": plan, "target": "file"}))
+        if not isinstance(exported, dict) or exported.get("success") is not True:
+            return exported
+        data = exported["data"]
+        begin_params: dict[str, Any] = {"plan": plan, "file": data["file"], "compression": compression}
+        if chunk_size is not None:
+            begin_params["chunk_size"] = chunk_size
+        begun_reply = await self._call("export_download_begin", begin_params)
+        begun = _reply_payload(begun_reply)
+        if not isinstance(begun, dict) or begun.get("success") is not True:
+            return begun_reply
+        transfer_id = begun["data"]["transfer_id"]
+
+        temporary = destination.with_name(f".{destination.name}.{uuid.uuid4().hex}.part")
+        try:
+            receipt = await self._rpc.download_file(
+                transfer_id, str(temporary), chunk_size=chunk_size, on_progress=on_progress
+            )
+            if not (receipt.completed and receipt.checksum_verified):
+                raise ValueError(f"download of {data['file']} is not completed or its checksum is not verified")
+            body = temporary.read_bytes()
+            if len(body) != data["size_bytes"] or hashlib.sha256(body).hexdigest() != data["sha256"]:
+                raise ValueError(f"downloaded file does not match the export {data['file']}")
+            if destination.exists() and not overwrite:
+                raise FileExistsError(f"destination exists and overwrite is False: {destination}")
+            os.replace(temporary, destination)
+        except BaseException:
+            with_suppressed_unlink(temporary)
+            raise
+        return {
+            "plan": plan,
+            "path": str(destination),
+            "size_bytes": data["size_bytes"],
+            "sha256": data["sha256"],
+            "paragraphs": data["paragraphs"],
+            "transfer_id": transfer_id,
+            "server_file": data["file"],
+            "expires_at": data["expires_at"],
+        }
+
+
+def _require_destination(path: Any) -> Path:
+    """Return the destination path; an empty or missing path is refused before any request."""
+    if path is None or (isinstance(path, str) and not path.strip()):
+        raise ValueError("path must be a non-empty file path")
+    return Path(path)
+
+
+def _require_writable_destination(destination: Path, overwrite: bool) -> None:
+    """Refuse a destination that cannot be written, before any request: a directory, a missing parent, a read-only
+    parent, or an existing file without overwrite."""
+    if destination.is_dir():
+        raise IsADirectoryError(f"destination is a directory: {destination}")
+    parent = destination.parent
+    if not parent.is_dir():
+        raise FileNotFoundError(f"destination directory does not exist: {parent}")
+    if not os.access(parent, os.W_OK | os.X_OK):
+        raise PermissionError(f"destination directory is not writable: {parent}")
+    if destination.exists() and not overwrite:
+        raise FileExistsError(f"destination exists and overwrite is False: {destination}")
+
+
+def with_suppressed_unlink(path: Path) -> None:
+    """Remove a temporary file if it exists."""
+    try:
+        path.unlink()
+    except FileNotFoundError:
+        pass
+
+
+__all__ = ["HrsFileCommandsMixin"]

{plan_manager_client-0.2.149 → plan_manager_client-0.2.151}/plan_manager_client/facade_plan_hrs_mixin.py

@@ -102,6 +102,10 @@ class PlanHrsCommandsMixin:
         """Export the byte-identical HRS Markdown text of a plan."""
         return await self._call("hrs_export", params)
 
+    async def export_download_begin(self, **params: Any) -> Any:
+        """Open the download session of one hrs_export file of a plan (plan, file, compression, chunk_size); the server file stays until the sweep timer removes it."""
+        return await self._call("export_download_begin", params)
+
     async def export_cleanup(self, **params: Any) -> Any:
         """Purge export artifacts under the configured export root, classified per plan; dry_run defaults to true and reports what would be removed without removing it."""
         return await self._call("export_cleanup", params)
@@ -138,6 +142,10 @@ class PlanHrsCommandsMixin:
         """Split one binding HRS paragraph, addressed by label, into several binding paragraphs cut at the given offsets."""
         return await self._call("para_split", params)
 
+    async def hrs_fields_fill(self, **params: Any) -> Any:
+        """Fill the kind, title and statement of broken HRS paragraphs with one model call each (queued; the body never changes)."""
+        return await self._call("hrs_fields_fill", params)
+
     async def concept_get(self, **params: Any) -> Any:
         """Return one concept of a plan by its id."""
         return await self._call("concept_get", params)

plan_manager_client-0.2.151/plan_manager_client/facade_runtime_mixin/__init__.py

@@ -0,0 +1,11 @@
+"""Todo/runtime-link/comment and model-binding/execution/review/escalation command-family facade mixin.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from .authoring_part import RuntimeAuthoringPart
+from .facade import RuntimeCommandsMixin
+from .overlay_part import RuntimeOverlayPart
+
+__all__ = ["RuntimeCommandsMixin"]

plan_manager_client-0.2.149/plan_manager_client/facade_runtime_mixin.py → plan_manager_client-0.2.151/plan_manager_client/facade_runtime_mixin/authoring_part.py

@@ -1,194 +1,31 @@
-"""Todo/runtime-link/comment and model-binding/execution/review/escalation command-family facade mixin.
-
-Author: Vasiliy Zdanovskiy
-email: vasilyvz@gmail.com
-"""
+"""Module for split package."""
 
 from __future__ import annotations
-
 from typing import Any
 
-
-class RuntimeCommandsMixin:
+class RuntimeAuthoringPart:
     """One method per plan_manager command in the runtime work-item family.
 
     Assumes it is mixed into a class that also inherits
     plan_manager_client.dispatch._CommandDispatchMixin, which supplies the
     coroutine async def _call(self, command: str, params: dict[str, Any] | None = None) -> Any
-    used by every method below.
-    """
-
-    async def authoring_usage_get(self, step: str, include_descendants: bool) -> Any:
-        """Read persisted MACSC token usage for one planned step (its id, a uuid4) or its subtree."""
-        return await self._call("authoring_usage_get", {"step": step, "include_descendants": include_descendants})
-
-    async def todo_create(self, **params: Any) -> Any:
-        """Create a new TODO work item with a primary anchor."""
-        return await self._call("todo_create", params)
-
-    async def todo_get(self, **params: Any) -> Any:
-        """Fetch a single TODO work item by identifier."""
-        return await self._call("todo_get", params)
-
-    async def todo_list(self, **params: Any) -> Any:
-        """List TODO work items with uniform filtering and pagination."""
-        return await self._call("todo_list", params)
-
-    async def todo_update(self, **params: Any) -> Any:
-        """Update mutable fields of an existing TODO work item."""
-        return await self._call("todo_update", params)
-
-    async def todo_reanchor(self, **params: Any) -> Any:
-        """Move a TODO item's primary anchor to a new target, with an audit record."""
-        return await self._call("todo_reanchor", params)
-
-    async def todo_resolve(self, **params: Any) -> Any:
-        """Mark a TODO work item resolved."""
-        return await self._call("todo_resolve", params)
-
-    async def todo_close(self, **params: Any) -> Any:
-        """Mark a TODO work item closed."""
-        return await self._call("todo_close", params)
-
-    async def todo_reopen(self, **params: Any) -> Any:
-        """Reopen a TODO work item from a terminal state."""
-        return await self._call("todo_reopen", params)
-
-    async def todo_delete(self, **params: Any) -> Any:
-        """Delete a TODO work item: soft by default, hard=true gated by the inbound-reference integrity check, dry_run previews."""
-        return await self._call("todo_delete", params)
-
-    async def todo_link_add(self, **params: Any) -> Any:
-        """Create a typed link between two TODO work items."""
-        return await self._call("todo_link_add", params)
-
-    async def todo_link_remove(self, **params: Any) -> Any:
-        """Remove (soft-delete) a typed link between two TODO work items."""
-        return await self._call("todo_link_remove", params)
-
-    async def todo_link_get(self, **params: Any) -> Any:
-        """Read one todo link by its id (parameters passed through; the server validates them)."""
-        return await self._call("todo_link_get", params)
-
-    async def todo_link_list(self, **params: Any) -> Any:
-        """List todo links with filters and pagination (parameters passed through; the server validates them)."""
-        return await self._call("todo_link_list", params)
-
-    async def todo_link_delete(self, **params: Any) -> Any:
-        """Delete a todo link: mark by default, hard=true removes a marked link, dry_run previews (parameters passed through; the server validates them)."""
-        return await self._call("todo_link_delete", params)
-
-    async def todo_queue(self, **params: Any) -> Any:
-        """Surface a paginated page of the TODO-derived portion of the unified runtime work queue."""
-        return await self._call("todo_queue", params)
-
-    async def wish_create(self, **params: Any) -> Any:
-        """Create a new runtime wish item."""
-        return await self._call("wish_create", params)
-
-    async def wish_get(self, **params: Any) -> Any:
-        """Fetch a single runtime wish item by identifier."""
-        return await self._call("wish_get", params)
-
-    async def wish_list(self, **params: Any) -> Any:
-        """List runtime wish items with filtering and pagination."""
-        return await self._call("wish_list", params)
-
-    async def wish_update(self, **params: Any) -> Any:
-        """Update mutable fields of a runtime wish item."""
-        return await self._call("wish_update", params)
-
-    async def wish_reanchor(self, **params: Any) -> Any:
-        """Move a wish item's primary anchor to a new target, with an audit record."""
-        return await self._call("wish_reanchor", params)
+    used by every method below."""
 
-    async def wish_delete(self, **params: Any) -> Any:
-        """Delete a runtime wish item: soft by default, hard=true gated by the inbound-reference integrity check, dry_run previews."""
-        return await self._call("wish_delete", params)
+    def __init__(self, owner):
+        self._owner = owner
 
-    async def calendar_entry_create(self, **params: Any) -> Any:
-        """Create a calendar-based work entry spanning one or more calendar days."""
-        return await self._call("calendar_entry_create", params)
+    def __getattr__(self, name):
+        """Resolve names this part does not define on the owning facade."""
+        if name == "_owner":
+            raise AttributeError(name)
+        return getattr(self._owner, name)
 
-    async def calendar_entry_get(self, **params: Any) -> Any:
-        """Fetch one calendar-based work entry by identifier."""
-        return await self._call("calendar_entry_get", params)
-
-    async def calendar_entry_list(self, **params: Any) -> Any:
-        """List calendar-based work entries with filtering and pagination."""
-        return await self._call("calendar_entry_list", params)
-
-    async def calendar_entry_update(self, **params: Any) -> Any:
-        """Update mutable fields of a calendar-based work entry."""
-        return await self._call("calendar_entry_update", params)
-
-    async def calendar_entry_reanchor(self, **params: Any) -> Any:
-        """Move a calendar entry's primary anchor to a new target, with an audit record."""
-        return await self._call("calendar_entry_reanchor", params)
-
-    async def calendar_entry_delete(self, **params: Any) -> Any:
-        """Delete a calendar-based work entry: soft by default, hard=true available, dry_run previews."""
-        return await self._call("calendar_entry_delete", params)
-
-    async def runtime_link_add(self, **params: Any) -> Any:
-        """Create a typed link between two runtime records, each independently a bug or a todo."""
-        return await self._call("runtime_link_add", params)
-
-    async def runtime_link_list(self, **params: Any) -> Any:
-        """List generic runtime links, optionally filtered to one endpoint record, with uniform pagination."""
-        return await self._call("runtime_link_list", params)
-
-    async def runtime_link_remove(self, **params: Any) -> Any:
-        """Remove (soft-delete) a generic runtime link, with an optional dry-run preview."""
-        return await self._call("runtime_link_remove", params)
-
-    async def runtime_link_get(self, **params: Any) -> Any:
-        """Read one runtime link by its id (parameters passed through; the server validates them)."""
-        return await self._call("runtime_link_get", params)
-
-    async def runtime_link_delete(self, **params: Any) -> Any:
-        """Delete a runtime link: mark by default, hard=true removes a marked link, dry_run previews (parameters passed through; the server validates them)."""
-        return await self._call("runtime_link_delete", params)
-
-    async def runtime_overlay_export(self, **params: Any) -> Any:
-        """Export the runtime overlay of one plan to overlay.json in the plan export folder (parameters passed through)."""
-        return await self._call("runtime_overlay_export", params)
-
-    async def runtime_overlay_import(self, **params: Any) -> Any:
-        """Import a runtime overlay file into its plan, all or nothing; dry_run validates and counts only (parameters passed through)."""
-        return await self._call("runtime_overlay_import", params)
-
-    async def comment_add(self, **params: Any) -> Any:
-        """Create a new runtime comment attached to a comment anchor."""
-        return await self._call("comment_add", params)
-
-    async def comment_get(self, **params: Any) -> Any:
-        """Retrieve a single runtime comment by identifier."""
-        return await self._call("comment_get", params)
-
-    async def comment_list(self, **params: Any) -> Any:
-        """List runtime comments with uniform filtering and pagination."""
-        return await self._call("comment_list", params)
-
-    async def comment_supersede(self, **params: Any) -> Any:
-        """Create a new runtime comment that supersedes an existing one, preserving history."""
-        return await self._call("comment_supersede", params)
-
-    async def comment_resolve(self, **params: Any) -> Any:
-        """Mark an existing runtime comment as resolved."""
-        return await self._call("comment_resolve", params)
-
-    async def comment_update(self, **params: Any) -> Any:
-        """Change the body, kind, visibility or author of a runtime comment in place (parameters passed through; the server validates them)."""
-        return await self._call("comment_update", params)
-
-    async def comment_reanchor(self, **params: Any) -> Any:
-        """Move a runtime comment's primary anchor to a new target, with an audit record."""
-        return await self._call("comment_reanchor", params)
-
-    async def comment_delete(self, **params: Any) -> Any:
-        """Delete a runtime comment: soft by default, hard=true gated by the inbound-reference integrity check, dry_run previews."""
-        return await self._call("comment_delete", params)
+    async def authoring_usage_get(self, step: str, include_descendants: bool, plan: str | None = None) -> Any:
+        """Read persisted MACSC token usage for one planned step (its id, a uuid4, or with plan its path) or its subtree."""
+        params: dict[str, Any] = {"step": step, "include_descendants": include_descendants}
+        if plan is not None:
+            params["plan"] = plan
+        return await self._call("authoring_usage_get", params)
 
     async def model_binding_set(self, **params: Any) -> Any:
         """Create a model binding runtime-configuration record (C-009) for the given scope."""
@@ -273,9 +110,7 @@ class RuntimeCommandsMixin:
             params["orchestrator_model_id"] = orchestrator_model_id
         return await self._call("authoring_job_resume", params)
 
-    async def authoring_job_stop(
-        self, plan: str, step: str, session_id: str
-    ) -> Any:
+    async def authoring_job_stop(self, plan: str, step: str, session_id: str) -> Any:
         """Stop the authoring job of the step ``step`` (its id, a uuid4) and its active same-session descendants."""
         return await self._call(
             "authoring_job_stop",
@@ -286,9 +121,12 @@ class RuntimeCommandsMixin:
         """Delete transient context for one terminal authoring job."""
         return await self._call("authoring_job_delete", {"job_id": job_id})
 
-    async def authoring_child_list(self, step: str) -> Any:
-        """List the direct planned children of the step ``step`` (its id, a uuid4)."""
-        return await self._call("authoring_child_list", {"step": step})
+    async def authoring_child_list(self, step: str, plan: str | None = None) -> Any:
+        """List the direct planned children of the step ``step`` (its id, a uuid4, or with ``plan`` its path)."""
+        params: dict[str, Any] = {"step": step}
+        if plan is not None:
+            params["plan"] = plan
+        return await self._call("authoring_child_list", params)
 
     async def authoring_step_create(self, **params: Any) -> Any:
         return await self._call("authoring_step_create", params)
@@ -301,9 +139,7 @@ class RuntimeCommandsMixin:
 
     async def authoring_step_submit(self, step_payload: dict[str, Any]) -> Any:
         """Submit the current job's assigned-step payload."""
-        return await self._call(
-            "authoring_step_submit", {"step_payload": step_payload}
-        )
+        return await self._call("authoring_step_submit", {"step_payload": step_payload})
 
     async def authoring_escalate(self, question: str) -> Any:
         """Pause the current job with a question for its direct parent."""
@@ -425,5 +261,3 @@ class RuntimeCommandsMixin:
         """Delete an answer envelope: soft by default, hard when hard=true, dry_run previews."""
         return await self._call("answer_envelope_delete", params)
 
-
-__all__ = ["RuntimeCommandsMixin"]