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

plan_manager_client/facade_hrs_file_mixin.py

@@ -0,0 +1,206 @@
+"""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.
+
+        dry_run=true (the default) validates and reports without storing anything; convert=true converts the file
+        into structured fields by the model, after the svo paragraph split. The other hrs_import sources, document_id
+        and paragraphs, are not used by this call.
+        """
+        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 for its lifetime, by default 3600 s, and the sweep timer, which runs
+        every 300 s by default, removes it afterwards (both configurable on the server: hrs_export.file_ttl_s and
+        hrs_export.sweep_interval_s). 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/facade_plan_hrs_mixin.py

@@ -0,0 +1,200 @@
+"""Plan, export, HRS/MRS, and relation command-family facade mixin.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class PlanHrsCommandsMixin:
+    """One method per plan_manager command in the plan/export/HRS/MRS 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 plan_create(self, **params: Any) -> Any:
+        """Create a new plan aggregate with a unique name."""
+        return await self._call("plan_create", params)
+
+    async def plan_list(self, **params: Any) -> Any:
+        """List a paginated page of plans in the catalog with their bound projects; soft-deleted plans are hidden unless show_deleted is true."""
+        return await self._call("plan_list", params)
+
+    async def plan_status(self, **params: Any) -> Any:
+        """Return the dashboard for one plan: counts, gate, and scoring."""
+        return await self._call("plan_status", params)
+
+    async def plan_delete(self, **params: Any) -> Any:
+        """Delete a plan: soft by default (hidden from the catalog, reversible), or permanently with hard=true."""
+        return await self._call("plan_delete", params)
+
+    async def plan_completed_set(self, **params: Any) -> Any:
+        """Set or unset a plan's completion lock; always reachable regardless of freeze state or the current flag value."""
+        return await self._call("plan_completed_set", params)
+
+    async def plan_comment_set(self, **params: Any) -> Any:
+        """Set, replace, or clear a plan's free-form comment; always reachable regardless of freeze state or the completion lock."""
+        return await self._call("plan_comment_set", params)
+
+    async def plan_context_budget_set(self, **params: Any) -> Any:
+        """Set a plan's context budget for prompt assembly; always reachable regardless of freeze state or the completion lock."""
+        return await self._call("plan_context_budget_set", params)
+
+    async def plan_model_mapping_set(
+        self,
+        plan: str,
+        mappings: dict[str, dict[str, str] | None],
+        expected_plan_revision: str,
+    ) -> Any:
+        """Atomically replace a plan's complete G/T/A authoring-model mapping."""
+        return await self._call(
+            "plan_model_mapping_set",
+            {
+                "plan": plan,
+                "mappings": mappings,
+                "expected_plan_revision": expected_plan_revision,
+            },
+        )
+
+    async def plan_model_mapping_get(self, plan: str) -> Any:
+        """Read the plan-owned G/T/A model mapping and header revision."""
+        return await self._call("plan_model_mapping_get", {"plan": plan})
+
+    async def plan_project_attach(self, **params: Any) -> Any:
+        """Make an imported project the single project (owner) of a plan."""
+        return await self._call("plan_project_attach", params)
+
+    async def plan_export(self, **params: Any) -> Any:
+        """Export a plan to the standard file layout under the configured export root."""
+        return await self._call("plan_export", params)
+
+    async def plan_snapshot(self, **params: Any) -> Any:
+        """Export an importable snapshot of a plan's live working state."""
+        return await self._call("plan_snapshot", params)
+
+    async def plan_import(self, **params: Any) -> Any:
+        """Import a plan from a standard file layout under the configured export root."""
+        return await self._call("plan_import", params)
+
+    async def export_upload_save(self, **params: Any) -> Any:
+        """Promote a completed transfer upload session into the configured export root under a safe bare filename."""
+        return await self._call("export_upload_save", params)
+
+    async def export_read(self, **params: Any) -> Any:
+        """Read a byte range of a file under <export_root>/<plan>/ as a base64 chunk, with the whole file's size and sha256 for byte-identical reassembly and verification."""
+        return await self._call("export_read", params)
+
+    async def export_archive(self, **params: Any) -> Any:
+        """Pack the plan's export tree into a single gzip-tar archive under the fixed plan-relative name export.tar.gz; synchronous, returning plan, archive, size_bytes, sha256, and file_count."""
+        return await self._call("export_archive", params)
+
+    async def hrs_import(self, **params: Any) -> Any:
+        """Replace a plan's HRS text from a Markdown file under the configured export root or from inline source_text.
+
+        Sources, mutually exclusive: source (bare file name under the export root), source_text (inline Markdown),
+        document_id (UUID4 of a doc-store document) and paragraphs (structured paragraph items). convert=true converts
+        the source into structured fields by the model, after the svo paragraph split. dry_run=true (the default)
+        validates and reports without storing anything.
+        """
+        return await self._call("hrs_import", params)
+
+    async def hrs_export(self, **params: Any) -> Any:
+        """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)
+
+    async def para_list(self, **params: Any) -> Any:
+        """List a paginated page of a plan's HRS paragraphs: by default (view=summary) the compact items {id, broken, presentation}; view=full returns the whole record; fields_state filters."""
+        return await self._call("para_list", params)
+
+    async def para_get(self, **params: Any) -> Any:
+        """Resolve one paragraph label of a plan's HRS to its text, fields and broken state."""
+        return await self._call("para_get", params)
+
+    async def para_label_assign(self, **params: Any) -> Any:
+        """Assign fresh labels to unlabeled binding paragraphs of a plan's HRS."""
+        return await self._call("para_label_assign", params)
+
+    async def para_mark_non_binding(self, **params: Any) -> Any:
+        """Wrap or unwrap the non-binding markers around one HRS block of a plan."""
+        return await self._call("para_mark_non_binding", params)
+
+    async def para_insert(self, **params: Any) -> Any:
+        """Insert one new binding paragraph into a plan's HRS at a binding-order position."""
+        return await self._call("para_insert", params)
+
+    async def para_update(self, **params: Any) -> Any:
+        """Replace the text of one binding HRS paragraph addressed by label."""
+        return await self._call("para_update", params)
+
+    async def para_delete(self, **params: Any) -> Any:
+        """Delete one binding HRS paragraph addressed by label, shifting later paragraphs up."""
+        return await self._call("para_delete", params)
+
+    async def para_split(self, **params: Any) -> Any:
+        """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)
+
+    async def concept_list(self, **params: Any) -> Any:
+        """Return a paginated page of the concept list of a plan."""
+        return await self._call("concept_list", params)
+
+    async def concept_add(self, **params: Any) -> Any:
+        """Add a new concept to the plan MRS."""
+        return await self._call("concept_add", params)
+
+    async def concept_update(self, **params: Any) -> Any:
+        """Update fields of an existing concept."""
+        return await self._call("concept_update", params)
+
+    async def concept_remove(self, **params: Any) -> Any:
+        """Remove an existing concept from the plan MRS."""
+        return await self._call("concept_remove", params)
+
+    async def relation_list(self, **params: Any) -> Any:
+        """Return a paginated page of the relation list of a plan."""
+        return await self._call("relation_list", params)
+
+    async def relation_get(self, **params: Any) -> Any:
+        """Return one relation of a plan by its id."""
+        return await self._call("relation_get", params)
+
+    async def relation_add(self, **params: Any) -> Any:
+        """Add a new relation between two concepts."""
+        return await self._call("relation_add", params)
+
+    async def relation_update(self, **params: Any) -> Any:
+        """Update the type of an existing relation between two concepts."""
+        return await self._call("relation_update", params)
+
+    async def relation_remove(self, **params: Any) -> Any:
+        """Remove an existing relation between two concepts."""
+        return await self._call("relation_remove", params)
+
+    async def concept_coverage(self, **params: Any) -> Any:
+        """Return the steps and HRS paragraphs that justify one concept."""
+        return await self._call("concept_coverage", params)
+
+
+__all__ = ["PlanHrsCommandsMixin"]

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"]