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

plan_manager_client/delivery/archive.py

@@ -0,0 +1,140 @@
+"""Path A verified export tree materialization from the archive.
+
+Verifies the retrieved export archive against its declared sha256 BEFORE
+unpacking anything (DeliveryIntegrityContract, MRS concept C-007), then
+unpacks the gzip-compressed tar in memory into ordered tree entries that
+preserve every original name and relative position (ExportArchive, MRS
+concept C-016). Every entry is validated before any entry is materialized,
+so a refusal leaves nothing behind. Nothing enumerates an export, so the
+archive is the only way Path A obtains a whole tree. Produces no local
+files.
+"""
+
+from __future__ import annotations
+import hashlib
+import io
+import tarfile
+from dataclasses import dataclass
+
+
+class ArchiveIntegrityError(Exception):
+    """Raised when the export archive does not match its declared sha256.
+
+    Raised by :func:`materialize_tree` before any unpacking is attempted,
+    per DeliveryIntegrityContract (MRS concept C-007). Nothing is unpacked
+    and nothing reaches any destination when this is raised.
+    """
+    pass
+
+
+class ArchiveEntryRefusedError(Exception):
+    """Raised when an archive entry is refused during validation.
+
+    Raised by :func:`materialize_tree` for an entry whose stored path is
+    absolute or contains a '..' segment, or which is neither a regular
+    file nor a directory. Per ExportArchive (MRS concept C-016) every
+    entry is validated before any entry is materialized, so a refusal
+    leaves nothing behind.
+    """
+    pass
+
+
+@dataclass(frozen=True)
+class TreeEntry:
+    """One file of the verified export tree, in memory.
+
+    Attributes:
+        relative_path: The entry's POSIX path relative to the plan export
+            root, exactly as stored in the archive (for example
+            'spec.yaml' or 'G-001-foo/T-001-bar/atomic_steps/A-001-baz.yaml').
+        content: The entry's unpacked bytes, byte-for-byte as archived.
+        sha256: The hex sha256 digest computed over content.
+    """
+    relative_path: str
+    content: bytes
+    sha256: str
+
+
+def _validate_member(member: tarfile.TarInfo) -> None:
+    """Validate one archive member, refusing it if it is unsafe.
+
+    Args:
+        member: The archive member to validate.
+
+    Raises:
+        ArchiveEntryRefusedError: If member is neither a regular file nor
+            a directory, or if member.name starts with '/' or any
+            '/'-separated segment of member.name equals '..'.
+    """
+    if not member.isfile() and not member.isdir():
+        raise ArchiveEntryRefusedError(
+            f"archive entry is neither a regular file nor a directory: {member.name!r}"
+        )
+
+    if member.name.startswith('/') or '..' in member.name.split('/'):
+        raise ArchiveEntryRefusedError(
+            f"archive entry escapes the destination: {member.name!r}"
+        )
+
+
+def materialize_tree(
+    archive_bytes: bytes,
+    declared_archive_sha256: str,
+) -> list[TreeEntry]:
+    """Verify the archive, then unpack its tree in memory.
+
+    Validation is exhaustive and precedes materialization: every member is
+    validated before any member's bytes are read, so a refusal returns
+    nothing and leaves nothing behind (ExportArchive, MRS concept C-016).
+
+    Args:
+        archive_bytes: The already-retrieved archive content, a
+            gzip-compressed tar.
+        declared_archive_sha256: The archive's declared whole-archive
+            sha256 hex digest.
+
+    Returns:
+        The tree entries in the order the archive stores them, each
+        carrying its export-root-relative path, its unpacked content, and
+        the sha256 computed over that content. Directory members are
+        skipped rather than returned.
+
+    Raises:
+        ArchiveIntegrityError: If sha256(archive_bytes) does not equal
+            declared_archive_sha256. Raised before any unpacking; nothing
+            is unpacked.
+        ArchiveEntryRefusedError: If ANY member is refused by
+            _validate_member. Raised during the validation pass, before
+            any member's bytes are read, so no entry is returned.
+    """
+    computed = hashlib.sha256(archive_bytes).hexdigest()
+
+    if computed != declared_archive_sha256:
+        raise ArchiveIntegrityError(
+            f"archive digest mismatch: expected {declared_archive_sha256}, computed {computed}"
+        )
+
+    with tarfile.open(fileobj=io.BytesIO(archive_bytes), mode="r:gz") as tar:
+        # Validation pass: exhaustive check before any materialization
+        members = tar.getmembers()
+        for member in members:
+            _validate_member(member)
+
+        # Materialization pass: extract bytes and build entries
+        result: list[TreeEntry] = []
+        for member in members:
+            if member.isdir():
+                continue
+
+            extracted_file = tar.extractfile(member)
+            content = extracted_file.read()
+            entry_digest = hashlib.sha256(content).hexdigest()
+            result.append(
+                TreeEntry(
+                    relative_path=member.name,
+                    content=content,
+                    sha256=entry_digest,
+                )
+            )
+
+        return result

plan_manager_client/delivery/atomicity.py

@@ -0,0 +1,93 @@
+"""Path A failure atomicity and partial-write outcome tracking.
+
+Assembles the delivery outcome record naming exactly which destination
+paths were written and whether a commit was made, distinguishing every
+abort point of the Path A composition, realizing DeliveryFailureAtomicity
+(MRS concept C-011). An archive-verification or archive-entry-refusal
+abort leaves nothing behind, so the record cannot express either of them
+alongside written paths.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal, Optional
+
+FailurePoint = Literal["archive_verification", "archive_entry_refused", "digest_verification", "upload", "commit"]
+# The Path A composition stage at which a delivery failed, when it failed (MRS concept C-011).
+
+
+@dataclass(frozen=True)
+class DeliveryOutcome:
+    """Outcome of one Path A delivery attempt.
+
+    Attributes:
+        written_paths: Destination paths successfully written to the CA
+            project during this attempt, in delivery order, each carrying
+            its entry's relative position beneath the destination
+            subdirectory.
+        commit_made: True when a git commit was made for this attempt.
+        commit_hash: The git commit hash, when commit_made is True;
+            otherwise None.
+        failure_point: The composition stage at which the delivery failed,
+            or None when the delivery completed successfully. A failure at
+            'archive_verification' or 'archive_entry_refused' always
+            carries an empty written_paths: the archive was rejected or
+            the whole tree was refused before any entry was materialized,
+            so nothing was written and nothing was left behind.
+    """
+
+    written_paths: list[str] = field(default_factory=list)
+    commit_made: bool = False
+    commit_hash: Optional[str] = None
+    failure_point: Optional[FailurePoint] = None
+
+
+_VALID_FAILURE_POINTS: tuple[str, ...] = ("archive_verification", "archive_entry_refused", "digest_verification", "upload", "commit")
+
+_NOTHING_WRITTEN_FAILURE_POINTS: tuple[str, ...] = ("archive_verification", "archive_entry_refused")
+# Abort points that precede every write: the archive never verified, or the whole tree was refused before any entry was materialized. Both leave nothing behind, so neither can accompany a non-empty written_paths.
+
+
+def build_delivery_outcome(
+    written_paths: list[str],
+    commit_hash: Optional[str],
+    failure_point: Optional[FailurePoint] = None,
+) -> DeliveryOutcome:
+    """Assemble a DeliveryOutcome from one Path A delivery attempt's results.
+
+    Args:
+        written_paths: Destination paths successfully written during this
+            attempt, in delivery order.
+        commit_hash: The git commit hash if a commit was made, else None.
+        failure_point: The stage at which the delivery failed, or None for
+            a fully successful delivery.
+
+    Returns:
+        A DeliveryOutcome with commit_made set to (commit_hash is not
+        None), and written_paths, commit_hash, failure_point carried
+        through unchanged (written_paths copied, not aliased).
+
+    Raises:
+        ValueError: If failure_point is not None and not one of
+            'archive_verification', 'archive_entry_refused',
+            'digest_verification', 'upload', 'commit'; or if
+            failure_point is 'archive_verification' or
+            'archive_entry_refused' while written_paths is non-empty,
+            which is an impossible outcome because both abort points
+            precede every write and leave nothing behind.
+    """
+    if failure_point is not None and failure_point not in _VALID_FAILURE_POINTS:
+        raise ValueError(f"invalid failure_point: {failure_point!r}")
+
+    if failure_point in _NOTHING_WRITTEN_FAILURE_POINTS and len(written_paths) > 0:
+        raise ValueError(f"failure_point {failure_point!r} leaves nothing behind but written_paths is non-empty: {list(written_paths)!r}")
+
+    commit_made = commit_hash is not None
+
+    return DeliveryOutcome(
+        written_paths=list(written_paths),
+        commit_made=commit_made,
+        commit_hash=commit_hash,
+        failure_point=failure_point,
+    )

plan_manager_client/delivery/commit.py

@@ -0,0 +1,113 @@
+"""Path A explicit git staging and commit composition.
+
+After the tree upload phase, explicitly stages the written destination
+paths and issues an explicit commit through the CA service's own client
+(CodeAnalysisClientDependency, MRS concept C-015), independent of the CA
+service's commit-on-write configuration, realizing the commit phase of
+PathACodeAnalysisDelivery (MRS concept C-003) and the deterministic-message
+requirement of DeliveryFailureAtomicity (MRS concept C-011).
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Optional
+from code_analysis_client.client import CodeAnalysisAsyncClient
+
+
+@dataclass(frozen=True)
+class CommitReceipt:
+    """Outcome of the explicit git staging and commit composition.
+
+    Attributes:
+        commit_hash: The git commit hash the CA client returned, or None
+            when no commit was made (empty written_paths).
+        commit_message: The deterministic commit message text used, or
+            an empty string when no commit was made.
+    """
+
+    commit_hash: Optional[str]
+    commit_message: str
+
+
+def build_commit_message(
+    plan_name: str,
+    export_revision_uuid: str,
+    per_entry_digest_set: dict[str, str],
+) -> str:
+    """Build the deterministic Path A commit message.
+
+    Args:
+        plan_name: Name of the plan being delivered.
+        export_revision_uuid: Revision uuid of the export being delivered.
+        per_entry_digest_set: Mapping of each delivered tree entry's path
+            relative to the plan export root to its sha256 hex digest.
+
+    Returns:
+        A deterministic multi-line commit message: a header line naming
+        plan_name and export_revision_uuid, followed by one line per entry
+        of per_entry_digest_set sorted by relative path ascending (str
+        order), each formatted as two spaces then
+        '{relative_path}: sha256:{digest}'. Sorting makes the message
+        reproducible across retried deliveries regardless of input dict
+        ordering.
+    """
+    header = f"plan_manager export delivery: {plan_name} (revision {export_revision_uuid})"
+    lines = [header] + [f"  {relative_path}: sha256:{digest}" for relative_path, digest in sorted(per_entry_digest_set.items())]
+    return "\n".join(lines)
+
+
+async def stage_and_commit(
+    ca_client: CodeAnalysisAsyncClient,
+    resolved_project_id: str,
+    written_paths: list[str],
+    plan_name: str,
+    export_revision_uuid: str,
+    per_entry_digest_set: dict[str, str],
+) -> CommitReceipt:
+    """Explicitly stage and commit the written Path A tree.
+
+    Args:
+        ca_client: An already-connected CodeAnalysisAsyncClient instance
+            (MRS concept C-015); this function does not construct or
+            close it.
+        resolved_project_id: The CA project_id the tree was written into.
+        written_paths: Destination paths successfully uploaded, each
+            carrying its entry's relative position beneath the destination
+            subdirectory.
+        plan_name: Name of the plan being delivered.
+        export_revision_uuid: Revision uuid of the export being delivered.
+        per_entry_digest_set: Mapping of each delivered tree entry's
+            export-root-relative path to its sha256 digest.
+
+    Returns:
+        A CommitReceipt. When written_paths is empty, CommitReceipt(None, '')
+        is returned without any CA git call. Otherwise the CA client's
+        git_add is called with resolved_project_id and written_paths, then
+        its git_commit is called with resolved_project_id and the message
+        from build_commit_message; the returned CommitReceipt carries the
+        commit hash the CA client reports and the message used.
+    """
+    if len(written_paths) == 0:
+        return CommitReceipt(commit_hash=None, commit_message="")
+
+    await ca_client.commands.git_add(project_id=resolved_project_id, paths=written_paths)
+
+    message = build_commit_message(plan_name, export_revision_uuid, per_entry_digest_set)
+
+    result = await ca_client.commands.git_commit(project_id=resolved_project_id, message=message)
+
+    def extract_commit_hash(result_obj):
+        # Try attribute access first
+        if hasattr(result_obj, 'commit_hash'):
+            return result_obj.commit_hash
+        # Try dict-like access
+        try:
+            return result_obj["commit_hash"]
+        except (TypeError, KeyError):
+            pass
+        # Fall back to str
+        return str(result_obj)
+
+    commit_hash = extract_commit_hash(result)
+
+    return CommitReceipt(commit_hash=commit_hash, commit_message=message)

plan_manager_client/delivery/destination.py

@@ -0,0 +1,140 @@
+"""Path A destination resolution: CA project binding and tree paths.
+
+Resolves the target code-analysis project identity under SHARED PROJECT
+IDENTITY (DeliveryDestinationAddressing, MRS concept C-006) and maps each
+export tree entry to its destination path inside the project's
+documentation area, preserving the entry's relative position beneath the
+destination subdirectory so the delivered tree reproduces the export
+layout (PathACodeAnalysisDelivery, MRS concept C-003).
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+class NoBoundProjectError(Exception):
+    """Raised when a Path A delivery is attempted with no bound CA project.
+
+    Raised by :func:`resolve_destination` when both ``plan_project_binding``
+    and ``project_id_override`` are ``None``: SHARED PROJECT IDENTITY (C-006)
+    requires the plan to carry a bound primary code-analysis project_id, or
+    an explicit override, before a Path A call may proceed.
+    """
+    pass
+
+
+class DestinationPathTraversalError(Exception):
+    """Raised when a resolved destination path escapes the project root.
+
+    Raised by :func:`resolve_destination` when the destination subdirectory
+    or a per-entry destination path is absolute or contains a '..' path
+    segment, per the traversal-refusal rule of DeliveryDestinationAddressing
+    (MRS concept C-006).
+    """
+    pass
+
+
+DEFAULT_DESTINATION_SUBDIRECTORY_TEMPLATE: str = "docs/plan-exports/{plan_name}/"
+# Default destination subdirectory template (MRS concept C-006); it roots the delivered tree and is formatted with plan_name when the caller supplies no override.
+
+
+@dataclass(frozen=True)
+class ResolvedDestination:
+    """Resolved CA project and per-entry destination paths for Path A.
+
+    Attributes:
+        resolved_project_id: The code-analysis project_id the delivery
+            will write into.
+        resolved_destination_subdirectory: The destination documentation
+            subdirectory rooting the delivered tree, project-relative
+            POSIX, always ending in a single trailing '/'.
+        resolved_destination_paths: Ordered per-entry project-relative
+            POSIX destination paths, one per entry of tree_relative_paths
+            in the same order, each preserving that entry's relative
+            position beneath the subdirectory.
+    """
+    resolved_project_id: str
+    resolved_destination_subdirectory: str
+    resolved_destination_paths: list[str] = field(default_factory=list)
+
+
+def _reject_traversal(path: str) -> None:
+    """Raise DestinationPathTraversalError for an unsafe POSIX path.
+
+    Args:
+        path: A POSIX path string to validate.
+
+    Raises:
+        DestinationPathTraversalError: If path starts with '/' or any
+            '/'-separated segment of path equals '..'.
+    """
+    if path.startswith('/') or '..' in path.split('/'):
+        raise DestinationPathTraversalError(f"destination path escapes the project root: {path!r}")
+
+
+def resolve_destination(
+        plan_name: str,
+        tree_relative_paths: list[str],
+        plan_project_binding: Optional[str],
+        project_id_override: Optional[str] = None,
+        destination_subdirectory_override: Optional[str] = None,
+    ) -> ResolvedDestination:
+    """Resolve the CA project and per-entry destination paths for Path A.
+
+    Args:
+        plan_name: Name of the plan being delivered; used to format the
+            default destination subdirectory when no override is supplied.
+        tree_relative_paths: The export tree entries' POSIX paths relative
+            to the plan export root, in tree order. These are nested paths
+            such as 'spec.yaml' or
+            'G-001-x/T-001-y/atomic_steps/A-001-z.yaml'; their relative
+            position is preserved into the destination.
+        plan_project_binding: The plan's bound primary code-analysis
+            project_id, or None when the plan has no bound project.
+        project_id_override: An explicit code-analysis project_id supplied
+            by the caller; takes precedence over plan_project_binding when
+            not None.
+        destination_subdirectory_override: An explicit destination
+            documentation subdirectory rooting the delivered tree; when
+            None, the default template formatted with plan_name is used.
+
+    Returns:
+        A ResolvedDestination carrying the resolved project_id, the
+        resolved destination subdirectory (normalized to end with a single
+        trailing '/'), and the per-entry destination paths in the same
+        order as tree_relative_paths.
+
+    Raises:
+        NoBoundProjectError: If both plan_project_binding and
+            project_id_override are None.
+        DestinationPathTraversalError: If the resolved destination
+            subdirectory is unsafe per _reject_traversal, or if any entry
+            of tree_relative_paths is itself unsafe per _reject_traversal,
+            or if any resolved destination path is unsafe per
+            _reject_traversal.
+    """
+    resolved_project_id = project_id_override if project_id_override is not None else plan_project_binding
+
+    if resolved_project_id is None:
+        raise NoBoundProjectError("Path A delivery requires a bound or overridden CA project_id")
+
+    subdirectory = destination_subdirectory_override if destination_subdirectory_override else DEFAULT_DESTINATION_SUBDIRECTORY_TEMPLATE.format(plan_name=plan_name)
+
+    if not subdirectory.endswith('/'):
+        subdirectory = subdirectory + '/'
+
+    _reject_traversal(subdirectory)
+
+    destination_paths = []
+    for relative_path in tree_relative_paths:
+        _reject_traversal(relative_path)
+        candidate = subdirectory + relative_path
+        _reject_traversal(candidate)
+        destination_paths.append(candidate)
+
+    return ResolvedDestination(
+        resolved_project_id=resolved_project_id,
+        resolved_destination_subdirectory=subdirectory,
+        resolved_destination_paths=destination_paths
+    )

plan_manager_client/delivery/provenance.py

@@ -0,0 +1,88 @@
+"""Path A delivery provenance recording.
+
+On a successful delivery, records a runtime comment on the exported plan
+carrying the export revision, target CA project and the subdirectory
+rooting the delivered tree, the per-entry digests keyed by relative path,
+and the commit hash, realizing DeliveryProvenanceRecord (MRS concept
+C-010).
+"""
+
+from __future__ import annotations
+from typing import Any, Protocol
+
+
+class CommentAddCapable(Protocol):
+    """Structural type for a facade exposing the plan_manager comment_add command.
+
+    Matches the verified comment_add(plan, anchor_type, anchor_plan_uuid,
+    kind, visibility, author, body, created_by) command signature without
+    depending on the concrete facade class that implements it.
+    """
+
+    async def comment_add(
+        self,
+        plan: str,
+        anchor_type: str,
+        anchor_plan_uuid: str,
+        kind: str,
+        visibility: str,
+        author: str,
+        body: str,
+        created_by: str,
+    ) -> dict[str, Any]: ...
+
+
+async def record_provenance(
+    planmgr_client: CommentAddCapable,
+    exported_plan_uuid: str,
+    plan_name: str,
+    export_revision_uuid: str,
+    resolved_project_id: str,
+    resolved_destination_subdirectory: str,
+    per_entry_digest_set: dict[str, str],
+    commit_hash: str,
+    author: str,
+) -> str:
+    """Record a successful Path A tree delivery as a runtime comment.
+
+    Args:
+        planmgr_client: An object exposing an async comment_add method
+            matching CommentAddCapable; this function does not construct
+            or close it.
+        exported_plan_uuid: UUID of the plan that was exported and
+            delivered; used as both the comment_add 'plan' and
+            'anchor_plan_uuid' arguments.
+        plan_name: Name of the plan being delivered.
+        export_revision_uuid: Revision uuid of the delivered export.
+        resolved_project_id: Target CA project_id the tree was written
+            into.
+        resolved_destination_subdirectory: The destination subdirectory
+            rooting the delivered tree inside the CA project.
+        per_entry_digest_set: Mapping of each delivered tree entry's path
+            relative to the plan export root to its sha256 digest.
+        commit_hash: Git commit hash returned by the commit composition.
+        author: Identity recorded as both 'author' and 'created_by' on the
+            comment.
+
+    Returns:
+        The 'comment_uuid' field of the comment_add response.
+    """
+    digest_text = ", ".join(
+        f"{relative_path}=sha256:{digest}"
+        for relative_path, digest in sorted(per_entry_digest_set.items())
+    )
+    body = (
+        f"Path A tree delivery: revision {export_revision_uuid} -> project {resolved_project_id}, "
+        f"tree root {resolved_destination_subdirectory}; entries: {digest_text}; commit {commit_hash}"
+    )
+    response = await planmgr_client.comment_add(
+        plan=exported_plan_uuid,
+        anchor_type="plan",
+        anchor_plan_uuid=exported_plan_uuid,
+        kind="execution_note",
+        visibility="public_summary",
+        author=author,
+        body=body,
+        created_by=author,
+    )
+    return response["comment_uuid"]