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

plan_manager_client/facade_step_graph_mixin.py

@@ -0,0 +1,158 @@
+"""Step-core and graph/dependency command-family facade mixin.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class StepGraphCommandsMixin:
+    """One method per plan_manager command in the step-core and graph/dependency 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 step_get(self, **params: Any) -> Any:
+        """Return one step of a plan identified by step (its id, a uuid4), with resolved parent context."""
+        return await self._call("step_get", params)
+
+    async def step_tree(self, **params: Any) -> Any:
+        """Return a paginated page of the plan's full step tree as a flat, sorted list with statuses."""
+        return await self._call("step_tree", params)
+
+    async def step_create(self, **params: Any) -> Any:
+        """Scaffold a new step under a plan's declarative level schema."""
+        return await self._call("step_create", params)
+
+    async def step_update(self, **params: Any) -> Any:
+        """Patch level-specific fields of an existing step, re-validating touched references."""
+        return await self._call("step_update", params)
+
+    async def step_move(self, **params: Any) -> Any:
+        """Move a step to a new parent, rewriting every reference to it in one operation."""
+        return await self._call("step_move", params)
+
+    async def step_delete(self, **params: Any) -> Any:
+        """Delete a step, with a dry-run impact preview enabled by default."""
+        return await self._call("step_delete", params)
+
+    async def step_set_status(self, **params: Any) -> Any:
+        """Transition a step's status, refusing illegal transitions and the edit of a frozen step."""
+        return await self._call("step_set_status", params)
+
+    async def step_transition(self, **params: Any) -> Any:
+        """Transition one step or a scope of steps through the authoring lifecycle."""
+        return await self._call("step_transition", params)
+
+    async def step_runtime_get(self, **params: Any) -> Any:
+        """Return runtime parameters for one plan step."""
+        return await self._call("step_runtime_get", params)
+
+    async def step_runtime_report(self, **params: Any) -> Any:
+        """Merge runtime parameters for one plan step."""
+        return await self._call("step_runtime_report", params)
+
+    async def step_runtime_list(self, **params: Any) -> Any:
+        """List a paginated, artifact_path-sorted page of runtime parameters for plan steps in a scope."""
+        return await self._call("step_runtime_list", params)
+
+    async def step_list(self, **params: Any) -> Any:
+        """Return a flat, paginated listing of a plan's steps with full step fields, filterable by level, parent, status, and target_file."""
+        return await self._call("step_list", params)
+
+    async def step_search(self, **params: Any) -> Any:
+        """Search step content for an exact substring or regex, scoped to a plan or one branch."""
+        return await self._call("step_search", params)
+
+    async def files_report(self, **params: Any) -> Any:
+        """Return the target_file to writer-steps matrix for a plan scope, with ordering-conflict detection."""
+        return await self._call("files_report", params)
+
+    async def namespace_view(self, **params: Any) -> Any:
+        """Return a paginated page of one step's computed inherited namespace (ancestor-chain fields.names, optionally CA-probe seeded)."""
+        return await self._call("namespace_view", params)
+
+    async def namespace_rename_suggest(self, **params: Any) -> Any:
+        """Propose the full down-tree rename/signature-change cascade of one fields.names declaration entry; read-only."""
+        return await self._call("namespace_rename_suggest", params)
+
+    async def namespace_rename_apply(self, **params: Any) -> Any:
+        """Apply the rename/signature-change cascade atomically as one revision, or dry-run it (the default)."""
+        return await self._call("namespace_rename_apply", params)
+
+    async def hrs_prototype(self, **params: Any) -> Any:
+        """Assemble the mechanical HRS prototype of one plan: paginated per-G sections plus MRS/HRS digests, gaps seed, and the consumer-model guidance contract."""
+        return await self._call("hrs_prototype", params)
+
+    async def step_xref(self, **params: Any) -> Any:
+        """Cross-reference report over per-field content fingerprints: report where a signature/text fragment or a given step field is DEFINED versus where it is INLINED across the plan."""
+        return await self._call("step_xref", params)
+
+    async def graph_deps(self, **params: Any) -> Any:
+        """Return the dependency neighborhood (depends_on and dependents) of one step."""
+        return await self._call("graph_deps", params)
+
+    async def graph_order(self, **params: Any) -> Any:
+        """Return a paginated page of the topological execution order of a plan's steps."""
+        return await self._call("graph_order", params)
+
+    async def graph_parallel_map(self, **params: Any) -> Any:
+        """Return a paginated page of the parallel wave partition of a plan's steps by prerequisite depth."""
+        return await self._call("graph_parallel_map", params)
+
+    async def graph_impact(self, **params: Any) -> Any:
+        """Return the read-only transitive impact set of one step."""
+        return await self._call("graph_impact", params)
+
+    async def graph_dependents(self, **params: Any) -> Any:
+        """Return a paginated page of the transitive dependency-edge closure of one step."""
+        return await self._call("graph_dependents", params)
+
+    async def execution_graph(self, **params: Any) -> Any:
+        """Return a paginated page of the extended execution graph (explicit + inferred edges) of a plan's steps."""
+        return await self._call("execution_graph", params)
+
+    async def execution_dependency_suggest(self, **params: Any) -> Any:
+        """Propose depends_on additions for a plan's unambiguous inferred execution-graph edges; read-only."""
+        return await self._call("execution_dependency_suggest", params)
+
+    async def execution_dependency_apply(self, **params: Any) -> Any:
+        """Apply an execution_dependency_suggest proposal as depends_on additions, or dry-run it."""
+        return await self._call("execution_dependency_apply", params)
+
+    async def step_dependency_list(self, **params: Any) -> Any:
+        """List one step's top-level depends_on edges and the sibling steps that depend on it."""
+        return await self._call("step_dependency_list", params)
+
+    async def step_dependency_add(self, **params: Any) -> Any:
+        """Add one sibling dependency to a step's top-level depends_on; idempotent, cycle-safe, and admitted under the step mutation regime."""
+        return await self._call("step_dependency_add", params)
+
+    async def step_dependency_remove(self, **params: Any) -> Any:
+        """Remove one dependency from a step's top-level depends_on; idempotent and admitted under the step mutation regime."""
+        return await self._call("step_dependency_remove", params)
+
+    async def step_dependency_set(self, **params: Any) -> Any:
+        """Replace a step's entire top-level depends_on with a validated, deduplicated, cycle-safe sibling list."""
+        return await self._call("step_dependency_set", params)
+
+    async def step_dependency_clear(self, **params: Any) -> Any:
+        """Clear all of a step's top-level depends_on edges, admitted under the step mutation regime."""
+        return await self._call("step_dependency_clear", params)
+
+    async def step_dependency_preview(self, **params: Any) -> Any:
+        """Dry-run a batch of dependency changes and report validity, cycle risk, and the before/after execution order and parallel waves."""
+        return await self._call("step_dependency_preview", params)
+
+    async def step_dependency_apply(self, **params: Any) -> Any:
+        """Apply a batch of dependency changes as one revision, or dry-run them; all-or-nothing, cycle-safe."""
+        return await self._call("step_dependency_apply", params)
+
+
+__all__ = ["StepGraphCommandsMixin"]

plan_manager_client/id_rule.py

@@ -0,0 +1,115 @@
+"""Client-side check of the identifier rule D1 (uuid4 discipline, block 2, D7; TODO 93bc1adc-755b-461c-8f1e-20e51b3c0b25).
+
+The client is a separate wheel, so the rule is a copy of ``plan_manager.storage.id_rule``: an identifier is canonical
+8-4-4-4-12 text, version 4 (RFC 4122 variant), not nil, and has no run of eight or more '0' hex digits (hyphens ignored).
+``check_call_ids`` runs in the facade before every call: a value of a parameter named in ``UUID_PARAMETER_NAMES`` (the
+server's ``format: uuid`` parameters) that fails the rule is refused locally with the server's own answer shape
+(-32602, violation ``value``, the parameter as field, the exact value). The server stays the authority.
+
+Free-text identifiers are not in the table and are not checked: they are not uuids of this project (request, session and
+call ids, provider request ids, uuid7 evidence ids, idempotency keys, sha256 hashes, dialogue and transcript references,
+the server id of a tool). ``plan`` takes a name or an id: only a value of the id shape is checked (``ID_OR_NAME_PARAMETERS``).
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+from typing import Any
+
+_ZERO_RUN = re.compile(r"0{8}")
+_CANONICAL = re.compile(r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$")
+EXPECTED = "a valid identifier: uuid4, not nil, without a run of eight zeros"
+
+ID_OR_NAME_PARAMETERS: frozenset[str] = frozenset({"plan"})
+
+UUID_PARAMETER_NAMES: frozenset[str] = frozenset({
+    "anchor_plan", "anchor_plan_uuid", "anchor_project_id", "anchor_ref_id", "anchor_revision_uuid", "assignment_uuid",
+    "attempt_id", "binding_uuid", "bug", "bug_fix", "bug_id", "calendar_entry", "comment", "comment_uuid", "dependency_uuid",
+    "duplicate_of_uuid", "entity_id", "entity_ids", "entity_uuid", "envelope_uuid", "escalation_uuid", "from_entity_uuid",
+    "from_todo", "identifiers", "impact_uuid", "link", "linked_plan_uuid", "membership_uuid", "model_uuid",
+    "new_anchor_plan_uuid", "new_anchor_project_id", "new_anchor_ref_id", "new_anchor_revision_uuid", "new_owner_id",
+    "new_source_plan_uuid", "new_source_project_id", "new_source_ref_id", "new_source_revision_uuid", "parent_bug_uuid",
+    "policy_uuid", "profile_uuid", "project", "propagation_id", "provider_uuid", "review_uuid", "revision", "role_uuid",
+    "source_plan_uuid", "source_project_id", "source_ref", "source_ref_id", "source_revision_uuid", "supersedes_comment_uuid",
+    "target_plan_uuid", "target_project_id", "target_ref_id", "target_revision_uuid", "to_entity_uuid", "to_todo", "todo",
+    "tool_uuid", "toolset_uuid", "wish",
+})
+"""The parameters the server declares ``format: uuid`` (every command of the live catalog, generated from the schemas)."""
+
+FREE_TEXT_PARAMETERS: dict[str, frozenset[str]] = {
+    "plan_comment_set": frozenset({"comment"}),
+    "project_update": frozenset({"comment"}),
+}
+"""Per command: parameters whose NAME is in ``UUID_PARAMETER_NAMES`` for other commands but carry free text here (the
+``comment`` of plan_comment_set and project_update is prose, the ``comment`` of comment_update/comment_delete is a uuid)."""
+
+
+class InvalidIdentifierError(ValueError):
+    """A client-side refusal of an identifier value: the server's -32602 / violation value shape, before the call."""
+
+    code = -32602
+    violation = "value"
+
+    def __init__(self, field: str, value: Any, defect: str) -> None:
+        self.field = field
+        self.value = value
+        super().__init__(
+            f"parameter {field!r} must be {EXPECTED}, got {value!r} ({defect})"
+        )
+
+    def as_answer(self) -> dict[str, Any]:
+        """The server's -32602 ErrorResult for this refusal: the answer a command gives, not an exception."""
+        return {
+            "success": False,
+            "error": {
+                "code": self.code,
+                "message": str(self),
+                "data": {"field": self.field, "violation": self.violation, "expected": EXPECTED, "got": self.value},
+            },
+        }
+
+
+def id_defect(value: Any) -> str | None:
+    """Why ``value`` is not a valid identifier, or None when it is one (the rule D1 of the server)."""
+    if isinstance(value, uuid.UUID):
+        candidate = value
+    else:
+        try:
+            candidate = uuid.UUID(str(value))
+        except (AttributeError, TypeError, ValueError):
+            return f"invalid uuid: {value!r}"
+    if candidate.int == 0:
+        return f"nil uuid: {candidate}"
+    if candidate.version != 4:
+        return f"not version 4: {candidate}"
+    if _ZERO_RUN.search(candidate.hex):
+        return f"a run of eight zeros: {candidate}"
+    return None
+
+
+def _is_id_shape(value: Any) -> bool:
+    return isinstance(value, str) and _CANONICAL.match(value) is not None
+
+
+def check_call_ids(params: dict[str, Any] | None, command: str | None = None) -> None:
+    """Refuse locally every identifier value of a call that fails rule D1 (see the module docstring).
+
+    Raises InvalidIdentifierError naming the parameter and the exact value. Nothing is sent when it raises. A parameter
+    that ``FREE_TEXT_PARAMETERS`` lists for ``command`` is free text there and is never checked.
+    """
+    free_text = FREE_TEXT_PARAMETERS.get(command or "", frozenset())
+    for name, value in (params or {}).items():
+        if name in free_text:
+            continue
+        if name in UUID_PARAMETER_NAMES:
+            values = value if isinstance(value, list) else [value]
+            for item in values:
+                if isinstance(item, str):
+                    defect = id_defect(item)
+                    if defect is not None:
+                        raise InvalidIdentifierError(name, item, defect)
+        elif name in ID_OR_NAME_PARAMETERS and _is_id_shape(value):
+            defect = id_defect(value)
+            if defect is not None:
+                raise InvalidIdentifierError(name, value, defect)

plan_manager_client/info_walker.py

@@ -0,0 +1,133 @@
+"""Walk the `info` command to the end of a node, page by page (R116b info norm, client helper).
+
+`info` answers one page at a time: a page has ``has_more`` and ``next_offset``, and the content of
+the addressed node is under the key of its section. ``walk_info`` follows ``next_offset`` until
+``has_more`` is false and assembles the content. With ``follow_refs`` every oversize child that
+came back as an ``info_ref`` stub is read the same way, so the result is the full section data.
+Without a section the first page is read, and every section listed in its ``contents`` is walked.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+InfoCall = Callable[..., Awaitable[Any]]
+
+_MAX_DEPTH = 16
+_MAX_PAGES = 100_000
+
+
+def _is_stub(value: Any) -> bool:
+    return isinstance(value, dict) and "info_ref" in value and isinstance(value["info_ref"], dict)
+
+
+def _append(kind: str, acc: Any, piece: Any) -> Any:
+    if kind == "object":
+        merged = {} if acc is None else acc
+        merged.update(piece)
+        return merged
+    if kind == "array":
+        items = [] if acc is None else acc
+        items.extend(piece)
+        return items
+    if kind == "string":
+        return ("" if acc is None else acc) + piece
+    return piece
+
+
+async def _read_node(info: InfoCall, params: Dict[str, Any]) -> Any:
+    """Every page of one node, from offset 0 to next_offset null, assembled into its content."""
+    section = params["section"]
+    content: Any = None
+    offset = 0
+    pages = 0
+    while True:
+        page = await info(**params, offset=offset)
+        pages += 1
+        content = _append(page["kind"], content, page[section])
+        if not page["has_more"]:
+            return content
+        following = page["next_offset"]
+        if not isinstance(following, int) or following <= offset or pages >= _MAX_PAGES:
+            raise ValueError(
+                "info paging does not advance: offset %d, next_offset %r, page %d" % (offset, following, pages)
+            )
+        offset = following
+
+
+async def _resolve(info: InfoCall, value: Any, depth: int) -> Any:
+    """Replace every info_ref stub inside a walked value by the content it points to."""
+    if depth > _MAX_DEPTH:
+        raise ValueError("info stubs nest deeper than %d levels" % _MAX_DEPTH)
+    if _is_stub(value):
+        ref = value["info_ref"]
+        child = {key: ref[key] for key in ("section", "subsection", "path") if key in ref}
+        return await walk_info(info, follow_refs=True, _depth=depth + 1, **child)
+    if isinstance(value, dict):
+        return {key: await _resolve(info, item, depth) for key, item in value.items()}
+    if isinstance(value, list):
+        return [await _resolve(info, item, depth) for item in value]
+    return value
+
+
+async def walk_info(
+    info: InfoCall,
+    *,
+    section: Optional[str] = None,
+    subsection: Optional[str] = None,
+    path: Optional[str] = None,
+    follow_refs: bool = False,
+    _depth: int = 0,
+) -> Any:
+    """The assembled content of one `info` node, or of every section when ``section`` is None.
+
+    ``info`` is the async `info` call (the client method or any callable with the same parameters
+    that returns the unwrapped data of the answer). Pages are requested in stored order, each once.
+    """
+    if section is None:
+        first = await info()
+        walked = {}
+        for entry in first["contents"]:
+            name = entry["ref"]["section"]
+            walked[name] = await walk_info(info, section=name, follow_refs=follow_refs, _depth=_depth)
+        return walked
+    params: Dict[str, Any] = {"section": section}
+    if subsection is not None:
+        params["subsection"] = subsection
+    if path is not None:
+        params["path"] = path
+    content = await _read_node(info, params)
+    if follow_refs:
+        content = await _resolve(info, content, _depth)
+    return content
+
+
+def _page_of_envelope(raw: Any) -> Any:
+    """The bare info page of a client reply.
+
+    The client `info` method answers the command envelope {command, job_id, status, result: {success,
+    data: page}} (bug 05336ae7). The walker reads the page itself (kind, has_more, next_offset and the
+    section key), so the envelope is unwrapped here; a reply that is already a bare page passes through.
+    A failed envelope raises, never a silent empty page.
+    """
+    if isinstance(raw, dict) and isinstance(raw.get("result"), dict):
+        result = raw["result"]
+        if result.get("success") is False:
+            raise RuntimeError("info failed: %r" % (result,))
+        if "data" in result:
+            return result["data"]
+    return raw
+
+
+async def info_walk(client: Any, **params: Any) -> Any:
+    """Read one `info` node, or every section, to its end through a client's ``info`` method.
+
+    ``client`` is any object with an async ``info(**params)`` method (the PlanManagerClient). This is a
+    module function, not a facade method: the facade must expose only canonical command names.
+    Parameters are those of :func:`walk_info`: section, subsection, path and follow_refs.
+    The client reply is unwrapped to the bare page first (see :func:`_page_of_envelope`).
+    """
+    async def _info(**page_params: Any) -> Any:
+        return _page_of_envelope(await client.info(**page_params))
+
+    return await walk_info(_info, **params)

plan_manager_client/scenario_runtime.py

@@ -0,0 +1,65 @@
+"""Scenario helpers for installed public-client pipeline checks."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+from typing import Any
+
+from plan_manager_client.config import ClientConnectionConfig
+
+
+PREFIX = "live-smoke-"
+DEFAULT_PROJECT_ID = "f06b7269-cc9c-4293-886b-24984e4033ba"
+
+_CALL_TIMEOUT: float | None = None
+_CALL_WATCHDOG_GRACE_SECONDS = 15.0
+
+
+def configure_call_watchdog(timeout: float | None, *, grace_seconds: float = _CALL_WATCHDOG_GRACE_SECONDS) -> None:
+    """Configure the maximum public-client method duration for scenario calls."""
+    global _CALL_TIMEOUT
+    _CALL_TIMEOUT = None if timeout is None else float(timeout) + float(grace_seconds)
+
+
+def build_config(args: argparse.Namespace) -> ClientConnectionConfig:
+    """Build client configuration from a pipeline scenario argparse namespace."""
+    return ClientConnectionConfig.from_sources(
+        base_url=getattr(args, "base_url", None),
+        protocol=getattr(args, "protocol", None),
+        host=getattr(args, "host", None),
+        port=getattr(args, "port", None),
+        timeout=getattr(args, "timeout", None),
+        env_prefix="PLAN_MANAGER_",
+    )
+
+
+def _unwrap(raw: Any) -> tuple[bool, Any]:
+    current = raw
+    for _ in range(12):
+        if isinstance(current, dict):
+            if "status" in current and "result" in current:
+                if current.get("status") != "completed":
+                    return False, current
+                current = current.get("result")
+                continue
+            if "success" in current and isinstance(current.get("success"), bool):
+                if not current["success"]:
+                    return False, current.get("error", current)
+                return True, current.get("data", current)
+        return True, current
+    return False, {"message": "response envelope nesting exceeded", "raw": raw}
+
+
+async def call(client: Any, name: str, params: dict[str, Any] | None = None) -> tuple[bool, Any]:
+    """Call one public client method and normalize success/error envelopes."""
+    try:
+        method = getattr(client, name)
+        coroutine = method(**(params or {}))
+        raw = await asyncio.wait_for(coroutine, timeout=_CALL_TIMEOUT) if _CALL_TIMEOUT else await coroutine
+    except Exception as exc:  # noqa: BLE001 - scenario boundary.
+        return False, {"exception_type": type(exc).__name__, "message": str(exc)}
+    return _unwrap(raw)
+
+
+__all__ = ["DEFAULT_PROJECT_ID", "PREFIX", "build_config", "call", "configure_call_watchdog"]