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

plan_manager_client/__init__.py

@@ -0,0 +1,10 @@
+"""plan_manager_client: first-class client library for the plan_manager JSON-RPC API.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from plan_manager_client._version import __version__
+from plan_manager_client.info_walker import info_walk, walk_info
+
+__all__ = ["__version__", "info_walk", "walk_info"]

plan_manager_client/_version.py

@@ -0,0 +1,58 @@
+"""Resolve the client package version from the single release source."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as installed_version
+from pathlib import Path
+import configparser
+import tomllib
+
+
+_DIST_NAME = "plan-manager-client"
+# The DEV build (build.sh --dev yes) publishes the same import package under the distribution name plan-manager-client-dev.
+_DIST_NAMES = (_DIST_NAME, "plan-manager-client-dev")
+
+
+def version_from_source_tree(module_file: Path | None = None) -> str:
+    """Read the version from the repository root or, in an sdist, its frozen metadata."""
+    here = (module_file or Path(__file__)).resolve()
+    source_roots = (
+        here.parents[2] / "pyproject.toml",
+        here.parents[1] / "PKG-INFO",
+        here.parents[1] / "setup.cfg",
+    )
+    for candidate in source_roots:
+        if not candidate.is_file():
+            continue
+        if candidate.name == "pyproject.toml":
+            data = tomllib.loads(candidate.read_text(encoding="utf-8"))
+            return data["project"]["version"]
+        if candidate.name == "PKG-INFO":
+            for line in candidate.read_text(encoding="utf-8").splitlines():
+                if line.startswith("Version: "):
+                    return line.removeprefix("Version: ").strip()
+            continue
+        if candidate.name == "setup.cfg":
+            parser = configparser.ConfigParser()
+            parser.read(candidate, encoding="utf-8")
+            if parser.has_option("metadata", "version"):
+                return parser.get("metadata", "version").strip()
+    raise RuntimeError("could not resolve plan-manager-client version from source metadata")
+
+
+def resolve_version() -> str:
+    """Prefer source metadata for an editable checkout, otherwise use the installed version."""
+    if (Path(__file__).resolve().parents[2] / "pyproject.toml").is_file():
+        return version_from_source_tree()
+    for name in _DIST_NAMES:
+        try:
+            return installed_version(name)
+        except PackageNotFoundError:
+            continue
+    return version_from_source_tree()
+
+
+__version__ = resolve_version()
+
+
+__all__ = ["__version__", "resolve_version", "version_from_source_tree"]

plan_manager_client/authoring_diagnostics.py

@@ -0,0 +1,137 @@
+"""Opt-in safe diagnostics for the 14-command authoring client surface."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import json
+import logging
+from typing import Any
+from uuid import uuid4
+
+
+AUTHORING_DIAGNOSTIC_COMMANDS = frozenset(
+    {
+        "authoring_session_create",
+        "authoring_session_get",
+        "authoring_session_list",
+        "authoring_session_update",
+        "authoring_session_delete",
+        "authoring_job_start",
+        "authoring_job_status",
+        "authoring_job_resume",
+        "authoring_job_stop",
+        "authoring_job_delete",
+        "authoring_job_get",
+        "authoring_job_update",
+        "authoring_child_list",
+        "authoring_context_read",
+        "authoring_child_write",
+        "authoring_child_start",
+        "authoring_child_status",
+        "authoring_child_wait",
+        "authoring_child_answer",
+        "authoring_step_submit",
+        "authoring_escalate",
+        "plan_prompt_create",
+        "plan_prompt_get",
+        "plan_prompt_list",
+        "plan_prompt_update",
+        "plan_prompt_delete",
+        "plan_model_mapping_set",
+        "plan_model_mapping_get",
+        "authoring_usage_get",
+    }
+)
+
+_LOGGER = logging.getLogger("plan_manager_client.authoring.diagnostics")
+
+
+def new_correlation_id() -> str:
+    """Create one opaque client-side correlation ID per public dispatch."""
+    return str(uuid4())
+
+
+def emit(
+    event: str,
+    *,
+    command: str,
+    correlation_id: str,
+    parameters: object | None = None,
+    result: object | None = None,
+    error: object | None = None,
+) -> None:
+    """Emit one JSON record using only configured logging handlers and levels."""
+    if not _LOGGER.isEnabledFor(logging.INFO):
+        return
+    record: dict[str, object] = {
+        "event": event,
+        "command": command,
+        "correlation_id": correlation_id,
+    }
+    if parameters is not None:
+        record["parameter_types"] = _parameter_type_map(parameters)
+    if result is not None:
+        record["result_keys"] = _result_key_names(result)
+    if error is not None:
+        record["error"] = _error_summary(error)
+    _LOGGER.info("authoring_diagnostic=%s", json.dumps(record, sort_keys=True, separators=(",", ":")))
+
+
+def _parameter_type_map(parameters: object) -> dict[str, str]:
+    if not isinstance(parameters, Mapping):
+        return {}
+    return {
+        str(name): _value_type(value)
+        for name, value in sorted(parameters.items(), key=lambda item: str(item[0]))
+    }
+
+
+def _result_key_names(result: object) -> list[str]:
+    if not isinstance(result, Mapping):
+        return []
+    data = result.get("data")
+    if isinstance(data, Mapping):
+        return sorted(str(key) for key in data)
+    return sorted(str(key) for key in result if key not in {"error", "message"})
+
+
+def _error_summary(error: object) -> dict[str, object]:
+    payload = error
+    if isinstance(payload, Mapping) and isinstance(payload.get("error"), Mapping):
+        payload = payload["error"]
+    if isinstance(payload, Mapping):
+        code = payload.get("code")
+        data = payload.get("data", payload.get("details"))
+    else:
+        code = getattr(payload, "code", None)
+        data = getattr(payload, "data", getattr(payload, "details", None))
+    summary: dict[str, object] = {"code": code}
+    if isinstance(data, Mapping):
+        safe_data: dict[str, object] = {}
+        for key in ("field", "violation", "expected"):
+            value = data.get(key)
+            if isinstance(value, str):
+                safe_data[key] = value[:200]
+        if "got" in data:
+            safe_data["got_type"] = _value_type(data["got"])
+        elif isinstance(data.get("got_type"), str):
+            safe_data["got_type"] = data["got_type"][:80]
+        if safe_data:
+            summary["data"] = safe_data
+    return summary
+
+
+def _value_type(value: object) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "boolean"
+    if isinstance(value, str):
+        return "string"
+    if isinstance(value, (int, float)):
+        return "number"
+    if isinstance(value, Mapping):
+        return "object"
+    if isinstance(value, (list, tuple)):
+        return "array"
+    return type(value).__name__

plan_manager_client/client.py

@@ -0,0 +1,75 @@
+"""Composed full-surface facade client for the plan_manager JSON-RPC API.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp_proxy_adapter.client.jsonrpc_client.client import JsonRpcClient
+
+from plan_manager_client.dispatch import _CommandDispatchMixin
+from plan_manager_client.facade_agent_config_mixin import AgentConfigCommandsMixin
+from plan_manager_client.facade_bug_project_mixin import BugProjectCommandsMixin
+from plan_manager_client.facade_context_gate_mixin import ContextGateCommandsMixin
+from plan_manager_client.facade_entity_common_mixin import EntityCommonCommandsMixin
+from plan_manager_client.facade_hrs_file_mixin import HrsFileCommandsMixin
+from plan_manager_client.facade_plan_hrs_mixin import PlanHrsCommandsMixin
+from plan_manager_client.facade_runtime_mixin import RuntimeCommandsMixin
+from plan_manager_client.facade_step_graph_mixin import StepGraphCommandsMixin
+
+
+class PlanManagerClient(
+    _CommandDispatchMixin,
+    PlanHrsCommandsMixin,
+    HrsFileCommandsMixin,
+    StepGraphCommandsMixin,
+    ContextGateCommandsMixin,
+    EntityCommonCommandsMixin,
+    RuntimeCommandsMixin,
+    BugProjectCommandsMixin,
+    AgentConfigCommandsMixin,
+):
+    """Full command-surface facade for the plan_manager JSON-RPC API.
+
+    Composes (HOLDS, never inherits) a
+    mcp_proxy_adapter.client.jsonrpc_client.client.JsonRpcClient on the private
+    attribute ``self._rpc``, which supplies transport (http/https/mTLS), token
+    authentication, queued-job polling, and chunked file transfer with sha256
+    verification and resume. Because the transport client is held rather than
+    inherited, the network interaction is fully hidden: the public surface of
+    this class is exactly one public async method per plan_manager command,
+    contributed by the internal _call dispatch coroutine (queued-command
+    auto-polling per queue_get_job_status semantics) from _CommandDispatchMixin
+    and the seven command-family mixins, together covering every name in
+    plan_manager_client.server_api.COMMAND_NAMES. Construct directly with the
+    JsonRpcClient constructor arguments, or via
+    PlanManagerClient(**config.to_jsonrpc_kwargs()) using a
+    plan_manager_client.config.ClientConnectionConfig instance. Connections are
+    direct to the plan_manager server; this class performs no proxy call_server
+    routing.
+    """
+
+    def __init__(self, **jsonrpc_kwargs: Any) -> None:
+        """Compose the underlying JsonRpcClient from JsonRpcClient constructor kwargs.
+
+        Accepts exactly the keyword arguments of
+        mcp_proxy_adapter.client.jsonrpc_client.client.JsonRpcClient (protocol,
+        host, port, token_header, token, cert, key, ca, check_hostname,
+        timeout), so PlanManagerClient(**config.to_jsonrpc_kwargs()) from a
+        plan_manager_client.config.ClientConnectionConfig works directly. The
+        constructed client is stored on the private attribute self._rpc and is
+        never exposed as a public method, keeping the public surface exactly the
+        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/config.py

@@ -0,0 +1,320 @@
+"""Direct-connection configuration for a single plan_manager_client server.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+from typing import Any
+from typing import Optional
+from urllib.parse import urlsplit
+
+
+ENDPOINT_ENV_NAMES = {
+    "base_url": "PLAN_MANAGER_BASE_URL",
+    "protocol": "PLAN_MANAGER_PROTOCOL",
+    "host": "PLAN_MANAGER_HOST",
+    "port": "PLAN_MANAGER_PORT",
+}
+
+
+class MissingClientEndpointError(ValueError):
+    """Raised when no complete client endpoint is provided by CLI, env, or .env."""
+
+
+def _read_dotenv(path: str | Path | None) -> dict[str, str]:
+    """Read simple KEY=VALUE entries from a dotenv file without side effects."""
+    if path is None:
+        return {}
+    dotenv_path = Path(path)
+    if not dotenv_path.is_file():
+        return {}
+    values: dict[str, str] = {}
+    for raw_line in dotenv_path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        values[key.strip()] = value.strip().strip("'\"")
+    return values
+
+
+def _split_base_url(base_url: str) -> tuple[str, str, int]:
+    parts = urlsplit(base_url)
+    protocol = parts.scheme
+    host = parts.hostname
+    if not protocol or not host:
+        raise MissingClientEndpointError(
+            f"invalid PLAN_MANAGER_BASE_URL/base_url {base_url!r}: protocol and host are required"
+        )
+    port = parts.port
+    if port is None:
+        if protocol == "https":
+            port = 443
+        elif protocol == "http":
+            port = 80
+        else:
+            raise MissingClientEndpointError(
+                f"invalid PLAN_MANAGER_BASE_URL/base_url {base_url!r}: explicit port is required for protocol {protocol!r}"
+            )
+    return protocol, host, port
+
+
+def resolve_endpoint_sources(
+    *,
+    base_url: str | None = None,
+    protocol: str | None = None,
+    host: str | None = None,
+    port: int | str | None = None,
+    dotenv_path: str | Path | None = ".env",
+) -> tuple[str, str, int]:
+    """Resolve endpoint as CLI values, then environment, then dotenv.
+
+    No default endpoint is invented. A caller that supplies neither a complete
+    URL nor a complete protocol/host/port triple gets a precise configuration
+    error instead of silently targeting localhost or a fleet host.
+    """
+    dotenv = _read_dotenv(dotenv_path)
+
+    def _source(name: str, explicit: Any) -> Any:
+        if explicit not in (None, ""):
+            return explicit
+        env_name = ENDPOINT_ENV_NAMES[name]
+        env_value = os.environ.get(env_name)
+        if env_value not in (None, ""):
+            return env_value
+        return dotenv.get(env_name)
+
+    if base_url not in (None, ""):
+        return _split_base_url(str(base_url))
+
+    explicit_triple = any(value not in (None, "") for value in (protocol, host, port))
+    if explicit_triple:
+        dotenv = _read_dotenv(dotenv_path)
+
+        def _non_base_source(name: str, explicit: Any) -> Any:
+            if explicit not in (None, ""):
+                return explicit
+            env_name = ENDPOINT_ENV_NAMES[name]
+            env_value = os.environ.get(env_name)
+            if env_value not in (None, ""):
+                return env_value
+            return dotenv.get(env_name)
+
+        effective_protocol = _non_base_source("protocol", protocol)
+        effective_host = _non_base_source("host", host)
+        effective_port = _non_base_source("port", port)
+    else:
+        effective_base_url = _source("base_url", None)
+        if effective_base_url:
+            return _split_base_url(str(effective_base_url))
+        effective_protocol = _source("protocol", protocol)
+        effective_host = _source("host", host)
+        effective_port = _source("port", port)
+    missing = [
+        name for name, value in (
+            ("protocol", effective_protocol),
+            ("host", effective_host),
+            ("port", effective_port),
+        )
+        if value in (None, "")
+    ]
+    if missing:
+        raise MissingClientEndpointError(
+            "missing Plan Manager endpoint configuration: provide --base-url or "
+            "--protocol/--host/--port, or set PLAN_MANAGER_BASE_URL, or set "
+            f"{', '.join(ENDPOINT_ENV_NAMES[name] for name in missing)} in the environment/.env"
+        )
+    try:
+        parsed_port = int(effective_port)
+    except (TypeError, ValueError) as exc:
+        raise MissingClientEndpointError(f"invalid PLAN_MANAGER_PORT/port {effective_port!r}") from exc
+    return str(effective_protocol), str(effective_host), parsed_port
+
+
+@dataclass(frozen=True)
+class ClientConnectionConfig:
+    """Direct-connection parameters for one JSON-RPC server.
+
+    Mirrors, field for field, the constructor of
+    mcp_proxy_adapter.client.jsonrpc_client.client.JsonRpcClient:
+
+        def __init__(
+            self,
+            protocol: str = "http",
+            host: str = "127.0.0.1",
+            port: int = 8080,
+            token_header: Optional[str] = None,
+            token: Optional[str] = None,
+            cert: Optional[str] = None,
+            key: Optional[str] = None,
+            ca: Optional[str] = None,
+            check_hostname: bool = False,
+            timeout: Optional[float] = None,
+        ) -> None: ...
+
+    Instances are immutable. Use to_jsonrpc_kwargs() to build the keyword
+    arguments for JsonRpcClient(**kwargs) or for any other client built on the
+    same constructor shape (for example a code-analysis-client construction
+    helper), so one configuration entity serves either server.
+    """
+
+    protocol: str = "http"
+    host: str = "127.0.0.1"
+    port: int = 8080
+    token_header: Optional[str] = None
+    token: Optional[str] = None
+    cert: Optional[str] = None
+    key: Optional[str] = None
+    ca: Optional[str] = None
+    check_hostname: bool = False
+    timeout: Optional[float] = None
+
+    @classmethod
+    def from_sources(
+        cls,
+        *,
+        base_url: str | None = None,
+        protocol: str | None = None,
+        host: str | None = None,
+        port: int | str | None = None,
+        timeout: Optional[float] = None,
+        env_prefix: str = "PLANMGR_CLIENT_",
+        dotenv_path: str | Path | None = ".env",
+    ) -> "ClientConnectionConfig":
+        """Resolve endpoint config with CLI > environment > .env precedence."""
+        dotenv = _read_dotenv(dotenv_path)
+
+        def source(name: str, cli_value: Any = None) -> Any:
+            if cli_value not in (None, ""):
+                return cli_value
+            env_name = f"{env_prefix}{name}"
+            env_value = os.environ.get(env_name)
+            if env_value not in (None, ""):
+                return env_value
+            value = dotenv.get(env_name)
+            if value not in (None, ""):
+                return value
+            return None
+
+        resolved_base_url = source("BASE_URL", base_url)
+        resolved_timeout = timeout
+        if resolved_timeout is None and source("TIMEOUT") is not None:
+            resolved_timeout = float(source("TIMEOUT"))
+        if resolved_base_url:
+            return cls.from_base_url(
+                str(resolved_base_url),
+                timeout=resolved_timeout,
+                env_prefix=env_prefix,
+                dotenv_path=dotenv_path,
+            )
+        resolved_protocol = source("PROTOCOL", protocol)
+        resolved_host = source("HOST", host)
+        resolved_port = source("PORT", port)
+        missing = [
+            name
+            for name, value in (("protocol", resolved_protocol), ("host", resolved_host), ("port", resolved_port))
+            if value in (None, "")
+        ]
+        if missing:
+            joined = ", ".join(missing)
+            raise MissingClientEndpointError(f"missing required client endpoint value(s): {joined}")
+        cert = source("CERT")
+        key = source("KEY")
+        actual_protocol = str(resolved_protocol)
+        if actual_protocol == "https" and cert and key:
+            actual_protocol = "mtls"
+        return cls(
+            protocol=actual_protocol,
+            host=str(resolved_host),
+            port=int(resolved_port),
+            token_header=source("TOKEN_HEADER"),
+            token=source("TOKEN"),
+            cert=cert,
+            key=key,
+            ca=source("CA"),
+            check_hostname=False,
+            timeout=resolved_timeout,
+        )
+
+    @classmethod
+    def from_base_url(
+        cls,
+        base_url: str,
+        *,
+        timeout: Optional[float] = None,
+        env_prefix: str = "PLANMGR_CLIENT_",
+        dotenv_path: str | Path | None = ".env",
+    ) -> "ClientConnectionConfig":
+        """Build direct-connection configuration from a server base URL.
+
+        URL parsing and TLS/token environment handling live in the public
+        client package so pipeline callers do not implement transport logic.
+        """
+        dotenv = _read_dotenv(dotenv_path)
+
+        def optional(name: str) -> str | None:
+            env_name = f"{env_prefix}{name}"
+            value = os.environ.get(env_name) or dotenv.get(env_name)
+            if value:
+                return value
+            return None
+
+        parsed = urlsplit(base_url)
+        protocol = parsed.scheme or optional("PROTOCOL")
+        host = parsed.hostname or optional("HOST")
+        port = parsed.port or optional("PORT")
+        missing = [
+            name
+            for name, value in (("protocol", protocol), ("host", host), ("port", port))
+            if value in (None, "")
+        ]
+        if missing:
+            joined = ", ".join(missing)
+            raise MissingClientEndpointError(f"missing required client endpoint value(s): {joined}")
+        cert = optional("CERT")
+        key = optional("KEY")
+        if protocol == "https" and cert and key:
+            protocol = "mtls"
+        timeout_value = timeout
+        timeout_from_sources = optional("TIMEOUT")
+        if timeout_value is None and timeout_from_sources:
+            timeout_value = float(timeout_from_sources)
+        return cls(
+            protocol=str(protocol),
+            host=str(host),
+            port=int(port),
+            token_header=optional("TOKEN_HEADER"),
+            token=optional("TOKEN"),
+            cert=cert,
+            key=key,
+            ca=optional("CA"),
+            check_hostname=False,
+            timeout=timeout_value,
+        )
+
+    def to_jsonrpc_kwargs(self) -> dict[str, Any]:
+        """Return constructor kwargs for JsonRpcClient(**kwargs)."""
+        return {
+            "protocol": self.protocol,
+            "host": self.host,
+            "port": self.port,
+            "token_header": self.token_header,
+            "token": self.token,
+            "cert": self.cert,
+            "key": self.key,
+            "ca": self.ca,
+            "check_hostname": self.check_hostname,
+            "timeout": self.timeout,
+        }
+
+
+__all__ = [
+    "ClientConnectionConfig",
+    "MissingClientEndpointError",
+    "resolve_endpoint_sources",
+]

plan_manager_client/delivery/__init__.py

@@ -0,0 +1,7 @@
+"""Delivery module boundary for the plan_manager client library.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+
+This sub-package establishes the two-path delivery model (C-001) structurally: the module boundary where Path A (a code-analysis project specified; delivered by a later G-005 branch) and Path B (no project specified; delivered by a later G-004 branch) each add their own composition module, both consuming the plan_manager_client facade (client/plan_manager_client/client.py) and, for Path A, the code-analysis-client dependency. This package intentionally defines no dataclasses, function signatures, or interface contracts here: those are the design decisions of the G-004 and G-005 branches that will populate this sub-package, per the L1 ruling (decision comment 10eba9c2 resolving escalation 4f4a04bb) that this branch (G-003) must make the module boundary explicit without pre-empting their design.
+"""