pruv 1.0.0__tar.gz

pruv-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 pruv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pruv-1.0.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: pruv
+Version: 1.0.0
+Summary: Prove what happened. Cryptographic verification for any system.
+License: MIT License
+        
+        Copyright (c) 2025 pruv
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://pruv.dev
+Project-URL: Documentation, https://docs.pruv.dev
+Project-URL: Repository, https://github.com/pruv-dev/pruv
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: xycore>=1.0.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: click>=8.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: zstandard>=0.21.0
+Dynamic: license-file
+
+# pruv
+
+Prove what happened. Cryptographic verification for any system.
+
+```bash
+pip install pruv
+```
+
+## Quick Start
+
+```python
+from pruv import xy_wrap
+
+wrapped = xy_wrap(my_agent)
+result = await wrapped.run("Fix the bug")
+print(result.receipt.hash)
+```
+
+## Features
+
+- **Scanner**: Scan any project for files, imports, env vars, frameworks, and services
+- **xy_wrap()**: Universal wrapper for any agent, function, or workflow
+- **Checkpoints**: Create snapshots, preview restore diffs, quick undo
+- **Approval Gates**: Webhook-based human approval for high-risk operations
+- **Cloud Sync**: Sync chains to api.pruv.dev
+- **CLI**: `pruv scan`, `pruv verify`, `pruv export`, `pruv undo`, `pruv upload`

pruv-1.0.0/README.md

@@ -0,0 +1,26 @@
+# pruv
+
+Prove what happened. Cryptographic verification for any system.
+
+```bash
+pip install pruv
+```
+
+## Quick Start
+
+```python
+from pruv import xy_wrap
+
+wrapped = xy_wrap(my_agent)
+result = await wrapped.run("Fix the bug")
+print(result.receipt.hash)
+```
+
+## Features
+
+- **Scanner**: Scan any project for files, imports, env vars, frameworks, and services
+- **xy_wrap()**: Universal wrapper for any agent, function, or workflow
+- **Checkpoints**: Create snapshots, preview restore diffs, quick undo
+- **Approval Gates**: Webhook-based human approval for high-risk operations
+- **Cloud Sync**: Sync chains to api.pruv.dev
+- **CLI**: `pruv scan`, `pruv verify`, `pruv export`, `pruv undo`, `pruv upload`

pruv-1.0.0/pruv/__init__.py

@@ -0,0 +1,45 @@
+"""pruv — Prove what happened. Full SDK with scanner, wrappers, checkpoints, and cloud sync."""
+
+# Re-export from xycore
+from xycore import XYEntry, XYChain, XYReceipt, ThinkingPhase
+
+# Scanner
+from .scanner import scan
+from .graph import Graph, GraphDiff
+
+# Wrapper
+from .wrap import xy_wrap, WrappedResult
+
+# Checkpoints
+from .checkpoint import Checkpoint, CheckpointManager
+
+# Approval
+from .approval import ApprovalGate
+
+# Cloud
+from .cloud import CloudClient, CloudStorage
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # xycore re-exports
+    "XYEntry",
+    "XYChain",
+    "XYReceipt",
+    "ThinkingPhase",
+    # Scanner
+    "scan",
+    "Graph",
+    "GraphDiff",
+    # Wrapper
+    "xy_wrap",
+    "WrappedResult",
+    # Checkpoints
+    "Checkpoint",
+    "CheckpointManager",
+    # Approval
+    "ApprovalGate",
+    # Cloud
+    "CloudClient",
+    "CloudStorage",
+]

pruv-1.0.0/pruv/approval/__init__.py

@@ -0,0 +1,5 @@
+"""pruv approval gate — human approval for high-risk operations."""
+
+from .gate import ApprovalGate, ApprovalRequest, ApprovalResponse
+
+__all__ = ["ApprovalGate", "ApprovalRequest", "ApprovalResponse"]

pruv-1.0.0/pruv/approval/gate.py

@@ -0,0 +1,117 @@
+"""Approval gate — webhook-based human approval for high-risk operations."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ApprovalRequest:
+    """Request sent to the approval webhook."""
+
+    chain_id: str
+    entry_index: int
+    operation: str
+    x_state: dict[str, Any] | None = None
+    proposed_y_state: dict[str, Any] | None = None
+    timestamp: float = 0.0
+
+    def __post_init__(self):
+        if self.timestamp == 0.0:
+            self.timestamp = time.time()
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "chain_id": self.chain_id,
+            "entry_index": self.entry_index,
+            "operation": self.operation,
+            "x_state": self.x_state,
+            "proposed_y_state": self.proposed_y_state,
+            "timestamp": self.timestamp,
+        }
+
+
+@dataclass
+class ApprovalResponse:
+    """Response from the approval webhook."""
+
+    status: str  # approved, denied, timeout
+    approved_by: str | None = None
+    reason: str | None = None
+
+    @property
+    def is_approved(self) -> bool:
+        return self.status == "approved"
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"status": self.status}
+        if self.approved_by:
+            d["approved_by"] = self.approved_by
+        if self.reason:
+            d["reason"] = self.reason
+        return d
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ApprovalResponse":
+        return cls(
+            status=data["status"],
+            approved_by=data.get("approved_by"),
+            reason=data.get("reason"),
+        )
+
+
+class ApprovalGate:
+    """Human approval gate via webhook for high-risk operations."""
+
+    def __init__(
+        self,
+        webhook_url: str,
+        timeout: int = 300,
+        operations: set[str] | None = None,
+        on_timeout: str = "deny",
+    ) -> None:
+        self.webhook_url = webhook_url
+        self.timeout = timeout
+        self.operations = operations or {"file.write", "deploy", "database.migrate"}
+        self.on_timeout = on_timeout
+
+    def requires_approval(self, operation: str) -> bool:
+        """Check if an operation requires approval."""
+        return operation in self.operations
+
+    async def request_approval(self, request: ApprovalRequest) -> ApprovalResponse:
+        """Send an approval request to the webhook."""
+        try:
+            import httpx
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                resp = await client.post(self.webhook_url, json=request.to_dict())
+                if resp.status_code == 200:
+                    return ApprovalResponse.from_dict(resp.json())
+                return ApprovalResponse(status="denied", reason=f"HTTP {resp.status_code}")
+        except Exception as e:
+            if self.on_timeout == "approve":
+                return ApprovalResponse(status="approved", reason="timeout-auto-approved")
+            return ApprovalResponse(status="timeout", reason=str(e))
+
+    async def gate(
+        self,
+        chain_id: str,
+        entry_index: int,
+        operation: str,
+        x_state: dict[str, Any] | None = None,
+        proposed_y_state: dict[str, Any] | None = None,
+    ) -> ApprovalResponse:
+        """Full gate check — only calls webhook if operation requires approval."""
+        if not self.requires_approval(operation):
+            return ApprovalResponse(status="approved", reason="no-approval-required")
+
+        request = ApprovalRequest(
+            chain_id=chain_id,
+            entry_index=entry_index,
+            operation=operation,
+            x_state=x_state,
+            proposed_y_state=proposed_y_state,
+        )
+        return await self.request_approval(request)

pruv-1.0.0/pruv/checkpoint/__init__.py

@@ -0,0 +1,5 @@
+"""pruv checkpoint — create snapshots, restore, quick undo."""
+
+from .manager import Checkpoint, CheckpointManager, RestorePreview
+
+__all__ = ["Checkpoint", "CheckpointManager", "RestorePreview"]

pruv-1.0.0/pruv/checkpoint/manager.py

@@ -0,0 +1,223 @@
+"""Checkpoint manager — create, restore, preview, and auto-checkpoint."""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from xycore import XYChain
+
+from ..graph import Graph, GraphDiff
+from ..scanner import scan as scan_dir
+
+# Try zstandard for compression
+_HAS_ZSTD = False
+try:
+    import zstandard
+    _HAS_ZSTD = True
+except ImportError:
+    pass
+
+
+@dataclass
+class Checkpoint:
+    """A point-in-time snapshot of chain state and optionally project files."""
+
+    id: str
+    name: str
+    chain_id: str
+    entry_index: int
+    created_at: float
+    chain_snapshot: dict[str, Any]
+    graph_snapshot: dict[str, Any] | None = None
+    file_snapshots: dict[str, str] | None = None
+    compressed: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "chain_id": self.chain_id,
+            "entry_index": self.entry_index,
+            "created_at": self.created_at,
+            "chain_snapshot": self.chain_snapshot,
+            "graph_snapshot": self.graph_snapshot,
+            "compressed": self.compressed,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Checkpoint":
+        return cls(
+            id=data["id"],
+            name=data["name"],
+            chain_id=data["chain_id"],
+            entry_index=data["entry_index"],
+            created_at=data["created_at"],
+            chain_snapshot=data["chain_snapshot"],
+            graph_snapshot=data.get("graph_snapshot"),
+            compressed=data.get("compressed", False),
+        )
+
+
+@dataclass
+class RestorePreview:
+    """Preview of what will change if a checkpoint is restored."""
+
+    checkpoint_id: str
+    checkpoint_name: str
+    current_entry_index: int
+    target_entry_index: int
+    entries_to_rollback: int
+    diff: GraphDiff | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "checkpoint_id": self.checkpoint_id,
+            "checkpoint_name": self.checkpoint_name,
+            "current_entry_index": self.current_entry_index,
+            "target_entry_index": self.target_entry_index,
+            "entries_to_rollback": self.entries_to_rollback,
+        }
+        if self.diff:
+            d["diff"] = self.diff.to_dict()
+        return d
+
+
+class CheckpointManager:
+    """Manage checkpoints for an XY chain."""
+
+    def __init__(
+        self,
+        chain: XYChain,
+        project_dir: str | Path | None = None,
+        storage_dir: str | Path = ".pruv/checkpoints",
+        compress: bool = True,
+    ) -> None:
+        self.chain = chain
+        self.project_dir = Path(project_dir) if project_dir else None
+        self.storage_dir = Path(storage_dir)
+        self.storage_dir.mkdir(parents=True, exist_ok=True)
+        self.compress = compress and _HAS_ZSTD
+        self.checkpoints: list[Checkpoint] = []
+
+        # Register auto-checkpoint callback
+        self.chain._checkpoint_callback = lambda name: self.create(name)
+
+    def create(self, name: str, include_files: bool = False) -> Checkpoint:
+        """Create a checkpoint at the current chain state."""
+        # Snapshot chain
+        chain_data = self.chain.to_dict()
+
+        # Snapshot graph
+        graph_data = None
+        file_snapshots = None
+        if self.project_dir and self.project_dir.exists():
+            graph = scan_dir(str(self.project_dir), include_contents=include_files)
+            graph_data = graph.to_dict()
+            if include_files:
+                file_snapshots = graph.file_contents
+
+        checkpoint = Checkpoint(
+            id=uuid.uuid4().hex[:12],
+            name=name,
+            chain_id=self.chain.id,
+            entry_index=self.chain.length - 1 if self.chain.length > 0 else -1,
+            created_at=time.time(),
+            chain_snapshot=chain_data,
+            graph_snapshot=graph_data,
+            file_snapshots=file_snapshots,
+            compressed=self.compress,
+        )
+
+        self.checkpoints.append(checkpoint)
+        self._save_checkpoint(checkpoint)
+        return checkpoint
+
+    def preview_restore(self, checkpoint_id: str) -> RestorePreview:
+        """Preview what will change if restoring to a checkpoint."""
+        checkpoint = self._find_checkpoint(checkpoint_id)
+        current_index = self.chain.length - 1 if self.chain.length > 0 else -1
+
+        diff = None
+        if self.project_dir and checkpoint.graph_snapshot:
+            current_graph = scan_dir(str(self.project_dir))
+            old_graph = Graph.from_dict(checkpoint.graph_snapshot)
+            diff = old_graph.diff(current_graph)
+
+        return RestorePreview(
+            checkpoint_id=checkpoint.id,
+            checkpoint_name=checkpoint.name,
+            current_entry_index=current_index,
+            target_entry_index=checkpoint.entry_index,
+            entries_to_rollback=max(0, current_index - checkpoint.entry_index),
+            diff=diff,
+        )
+
+    def restore(self, checkpoint_id: str) -> XYChain:
+        """Restore chain to a checkpoint state."""
+        checkpoint = self._find_checkpoint(checkpoint_id)
+        restored = XYChain.from_dict(checkpoint.chain_snapshot)
+        self.chain.entries = restored.entries
+        return self.chain
+
+    def quick_undo(self) -> XYChain | None:
+        """Restore to the most recent checkpoint."""
+        if not self.checkpoints:
+            return None
+        latest = self.checkpoints[-1]
+        return self.restore(latest.id)
+
+    def list_checkpoints(self) -> list[dict[str, Any]]:
+        """List all checkpoints."""
+        return [
+            {
+                "id": cp.id,
+                "name": cp.name,
+                "entry_index": cp.entry_index,
+                "created_at": cp.created_at,
+            }
+            for cp in self.checkpoints
+        ]
+
+    def _find_checkpoint(self, checkpoint_id: str) -> Checkpoint:
+        for cp in self.checkpoints:
+            if cp.id == checkpoint_id:
+                return cp
+        raise ValueError(f"Checkpoint not found: {checkpoint_id}")
+
+    def _save_checkpoint(self, checkpoint: Checkpoint) -> Path:
+        """Save checkpoint to disk."""
+        data = json.dumps(checkpoint.to_dict(), indent=2).encode("utf-8")
+        path = self.storage_dir / f"{checkpoint.id}.json"
+
+        if self.compress and _HAS_ZSTD:
+            cctx = zstandard.ZstdCompressor(level=3)
+            data = cctx.compress(data)
+            path = self.storage_dir / f"{checkpoint.id}.json.zst"
+
+        with open(path, "wb") as f:
+            f.write(data)
+
+        return path
+
+    def _load_checkpoint(self, checkpoint_id: str) -> Checkpoint:
+        """Load checkpoint from disk."""
+        # Try compressed first
+        zst_path = self.storage_dir / f"{checkpoint_id}.json.zst"
+        json_path = self.storage_dir / f"{checkpoint_id}.json"
+
+        if zst_path.exists() and _HAS_ZSTD:
+            with open(zst_path, "rb") as f:
+                dctx = zstandard.ZstdDecompressor()
+                data = dctx.decompress(f.read())
+        elif json_path.exists():
+            with open(json_path, "rb") as f:
+                data = f.read()
+        else:
+            raise FileNotFoundError(f"Checkpoint not found on disk: {checkpoint_id}")
+
+        return Checkpoint.from_dict(json.loads(data))

pruv-1.0.0/pruv/cli/__init__.py

@@ -0,0 +1,5 @@
+"""pruv CLI — command-line interface."""
+
+from .commands import cli
+
+__all__ = ["cli"]