pierre-storage 0.10.0__tar.gz → 0.12.0__tar.gz

{pierre_storage-0.10.0/pierre_storage.egg-info → pierre_storage-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pierre-storage
-Version: 0.10.0
+Version: 0.12.0
 Summary: Pierre Git Storage SDK for Python
 Author-email: Pierre <support@pierre.io>
 License-Expression: MIT
@@ -83,6 +83,15 @@ github_repo = await storage.create_repo(
     }
 )
 # This repository will sync with github.com/octocat/Hello-World
+
+# Create a repository by forking an existing repo
+forked_repo = await storage.create_repo(
+    id="my-fork",
+    base_repo={
+        "id": "my-template-id",
+        "ref": "main",  # optional
+    },
+)
 ```
 
 ### Finding a Repository
@@ -149,6 +158,10 @@ repo = await storage.create_repo()
 # or
 repo = await storage.find_one(id="existing-repo-id")
 
+# List repositories for the org
+repos = await storage.list_repos(limit=20)
+print(repos["repos"])
+
 # Get file content (streaming)
 response = await repo.get_file_stream(
     path="README.md",
@@ -190,6 +203,27 @@ commits = await repo.list_commits(
 )
 print(commits["commits"])
 
+# Read a git note for a commit
+note = await repo.get_note(sha="abc123...")
+print(note["note"])
+
+# Add a git note
+note_result = await repo.create_note(
+    sha="abc123...",
+    note="Release QA approved",
+    author={"name": "Release Bot", "email": "release@example.com"},
+)
+print(note_result["new_ref_sha"])
+
+# Append to a git note
+await repo.append_note(
+    sha="abc123...",
+    note="Follow-up review complete",
+)
+
+# Delete a git note
+await repo.delete_note(sha="abc123...")
+
 # Get branch diff
 branch_diff = await repo.get_branch_diff(
     branch="feature-branch",
@@ -447,6 +481,23 @@ commits = await repo.list_commits()
 3. You can then use all Pierre SDK features (diffs, commits, file access) on the synced content
 4. The provider is automatically set to `"github"` when using `base_repo`
 
+### Forking Repositories
+
+You can fork an existing repository within the same Pierre org:
+
+```python
+forked_repo = await storage.create_repo(
+    id="my-fork",
+    base_repo={
+        "id": "my-template-id",
+        "ref": "main",  # optional (branch/tag)
+        # "sha": "abc123..."  # optional commit SHA (overrides ref)
+    },
+)
+```
+
+When `default_branch` is omitted, the SDK returns `"main"`.
+
 ### Restoring Commits
 
 You can restore a repository to a previous commit:
@@ -475,7 +526,7 @@ class GitStorage:
         self,
         *,
         id: Optional[str] = None,
-        default_branch: str = "main",
+        default_branch: Optional[str] = None,  # defaults to "main"
         base_repo: Optional[BaseRepo] = None,
         ttl: Optional[int] = None,
     ) -> Repo: ...
@@ -614,6 +665,8 @@ Key types are provided via TypedDict for better IDE support:
 from pierre_storage.types import (
     GitStorageOptions,
     BaseRepo,
+    GitHubBaseRepo,
+    ForkBaseRepo,
     CommitSignature,
     CreateCommitOptions,
     ListFilesResult,
@@ -627,12 +680,19 @@ from pierre_storage.types import (
     # ... and more
 )
 
-# BaseRepo type for GitHub sync
-class BaseRepo(TypedDict, total=False):
-    provider: Literal["github"]  # Always "github"
+# BaseRepo type for GitHub sync or forks
+class GitHubBaseRepo(TypedDict, total=False):
+    provider: Literal["github"]   # Always "github"
     owner: str                    # GitHub organization or user
     name: str                     # Repository name
     default_branch: Optional[str] # Default branch (optional)
+
+class ForkBaseRepo(TypedDict, total=False):
+    id: str                       # Source repo ID
+    ref: Optional[str]            # Optional ref name
+    sha: Optional[str]            # Optional commit SHA
+
+BaseRepo = Union[GitHubBaseRepo, ForkBaseRepo]
 ```
 
 ## Webhook Validation

{pierre_storage-0.10.0 → pierre_storage-0.12.0}/README.md

@@ -47,6 +47,15 @@ github_repo = await storage.create_repo(
     }
 )
 # This repository will sync with github.com/octocat/Hello-World
+
+# Create a repository by forking an existing repo
+forked_repo = await storage.create_repo(
+    id="my-fork",
+    base_repo={
+        "id": "my-template-id",
+        "ref": "main",  # optional
+    },
+)
 ```
 
 ### Finding a Repository
@@ -113,6 +122,10 @@ repo = await storage.create_repo()
 # or
 repo = await storage.find_one(id="existing-repo-id")
 
+# List repositories for the org
+repos = await storage.list_repos(limit=20)
+print(repos["repos"])
+
 # Get file content (streaming)
 response = await repo.get_file_stream(
     path="README.md",
@@ -154,6 +167,27 @@ commits = await repo.list_commits(
 )
 print(commits["commits"])
 
+# Read a git note for a commit
+note = await repo.get_note(sha="abc123...")
+print(note["note"])
+
+# Add a git note
+note_result = await repo.create_note(
+    sha="abc123...",
+    note="Release QA approved",
+    author={"name": "Release Bot", "email": "release@example.com"},
+)
+print(note_result["new_ref_sha"])
+
+# Append to a git note
+await repo.append_note(
+    sha="abc123...",
+    note="Follow-up review complete",
+)
+
+# Delete a git note
+await repo.delete_note(sha="abc123...")
+
 # Get branch diff
 branch_diff = await repo.get_branch_diff(
     branch="feature-branch",
@@ -411,6 +445,23 @@ commits = await repo.list_commits()
 3. You can then use all Pierre SDK features (diffs, commits, file access) on the synced content
 4. The provider is automatically set to `"github"` when using `base_repo`
 
+### Forking Repositories
+
+You can fork an existing repository within the same Pierre org:
+
+```python
+forked_repo = await storage.create_repo(
+    id="my-fork",
+    base_repo={
+        "id": "my-template-id",
+        "ref": "main",  # optional (branch/tag)
+        # "sha": "abc123..."  # optional commit SHA (overrides ref)
+    },
+)
+```
+
+When `default_branch` is omitted, the SDK returns `"main"`.
+
 ### Restoring Commits
 
 You can restore a repository to a previous commit:
@@ -439,7 +490,7 @@ class GitStorage:
         self,
         *,
         id: Optional[str] = None,
-        default_branch: str = "main",
+        default_branch: Optional[str] = None,  # defaults to "main"
         base_repo: Optional[BaseRepo] = None,
         ttl: Optional[int] = None,
     ) -> Repo: ...
@@ -578,6 +629,8 @@ Key types are provided via TypedDict for better IDE support:
 from pierre_storage.types import (
     GitStorageOptions,
     BaseRepo,
+    GitHubBaseRepo,
+    ForkBaseRepo,
     CommitSignature,
     CreateCommitOptions,
     ListFilesResult,
@@ -591,12 +644,19 @@ from pierre_storage.types import (
     # ... and more
 )
 
-# BaseRepo type for GitHub sync
-class BaseRepo(TypedDict, total=False):
-    provider: Literal["github"]  # Always "github"
+# BaseRepo type for GitHub sync or forks
+class GitHubBaseRepo(TypedDict, total=False):
+    provider: Literal["github"]   # Always "github"
     owner: str                    # GitHub organization or user
     name: str                     # Repository name
     default_branch: Optional[str] # Default branch (optional)
+
+class ForkBaseRepo(TypedDict, total=False):
+    id: str                       # Source repo ID
+    ref: Optional[str]            # Optional ref name
+    sha: Optional[str]            # Optional commit SHA
+
+BaseRepo = Union[GitHubBaseRepo, ForkBaseRepo]
 ```
 
 ## Webhook Validation

{pierre_storage-0.10.0 → pierre_storage-0.12.0}/pierre_storage/__init__.py

@@ -27,8 +27,12 @@ from pierre_storage.types import (
     ListBranchesResult,
     ListCommitsResult,
     ListFilesResult,
+    ListReposResult,
+    NoteReadResult,
+    NoteWriteResult,
     RefUpdate,
     Repo,
+    RepoInfo,
     RestoreCommitResult,
 )
 from pierre_storage.version import PACKAGE_VERSION
@@ -71,7 +75,11 @@ __all__ = [
     "ListBranchesResult",
     "ListCommitsResult",
     "ListFilesResult",
+    "ListReposResult",
+    "NoteReadResult",
+    "NoteWriteResult",
     "RefUpdate",
+    "RepoInfo",
     "Repo",
     "RestoreCommitResult",
     # Webhook

{pierre_storage-0.10.0 → pierre_storage-0.12.0}/pierre_storage/client.py

@@ -1,7 +1,8 @@
 """Main client for Pierre Git Storage SDK."""
 
 import uuid
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, cast
+from urllib.parse import urlencode
 
 import httpx
 
@@ -9,9 +10,14 @@ from pierre_storage.auth import generate_jwt
 from pierre_storage.errors import ApiError
 from pierre_storage.repo import DEFAULT_TOKEN_TTL_SECONDS, RepoImpl
 from pierre_storage.types import (
+    BaseRepo,
     DeleteRepoResult,
+    ForkBaseRepo,
+    GitHubBaseRepo,
     GitStorageOptions,
+    ListReposResult,
     Repo,
+    RepoInfo,
 )
 from pierre_storage.version import get_user_agent
 
@@ -99,17 +105,18 @@ class GitStorage:
         self,
         *,
         id: Optional[str] = None,
-        default_branch: str = "main",
-        base_repo: Optional[Dict[str, Any]] = None,
+        default_branch: Optional[str] = None,
+        base_repo: Optional[BaseRepo] = None,
         ttl: Optional[int] = None,
     ) -> Repo:
         """Create a new repository.
 
         Args:
             id: Repository ID (auto-generated if not provided)
-            default_branch: Default branch name (default: "main")
-            base_repo: Optional base repository for GitHub sync
-                       (provider, owner, name, default_branch)
+            default_branch: Default branch name (default: "main" for non-forks)
+            base_repo: Optional base repository for GitHub sync or fork
+                       GitHub: owner, name, default_branch
+                       Fork: id, ref, sha
             ttl: Token TTL in seconds
 
         Returns:
@@ -126,19 +133,51 @@ class GitStorage:
         )
 
         url = f"{self.options['api_base_url']}/api/v{self.options['api_version']}/repos"
-        body: Dict[str, Any] = {"default_branch": default_branch}
+        body: Dict[str, Any] = {}
 
         # Match backend priority: base_repo.default_branch > default_branch > 'main'
-        resolved_default_branch = default_branch
+        explicit_default_branch = default_branch is not None
+        resolved_default_branch: Optional[str] = None
+
         if base_repo:
-            # Ensure provider is set to 'github' if not provided
-            base_repo_with_provider = {
-                "provider": "github",
-                **base_repo,
-            }
-            body["base_repo"] = base_repo_with_provider
-            if base_repo.get("default_branch"):
-                resolved_default_branch = base_repo["default_branch"]
+            if "id" in base_repo:
+                fork_repo = cast(ForkBaseRepo, base_repo)
+                base_repo_token = self._generate_jwt(
+                    fork_repo["id"],
+                    {"permissions": ["git:read"], "ttl": ttl},
+                )
+                base_repo_payload: Dict[str, Any] = {
+                    "provider": "code",
+                    "name": fork_repo["id"],
+                    "operation": "fork",
+                    "auth": {"token": base_repo_token},
+                }
+                if fork_repo.get("ref"):
+                    base_repo_payload["ref"] = fork_repo["ref"]
+                if fork_repo.get("sha"):
+                    base_repo_payload["sha"] = fork_repo["sha"]
+                body["base_repo"] = base_repo_payload
+                if explicit_default_branch:
+                    resolved_default_branch = default_branch
+                    body["default_branch"] = default_branch
+            else:
+                github_repo = cast(GitHubBaseRepo, base_repo)
+                # Ensure provider is set to 'github' if not provided
+                base_repo_with_provider = {
+                    "provider": "github",
+                    **github_repo,
+                }
+                body["base_repo"] = base_repo_with_provider
+                if github_repo.get("default_branch"):
+                    resolved_default_branch = github_repo["default_branch"]
+                elif explicit_default_branch:
+                    resolved_default_branch = default_branch
+                else:
+                    resolved_default_branch = "main"
+                body["default_branch"] = resolved_default_branch
+        else:
+            resolved_default_branch = default_branch if explicit_default_branch else "main"
+            body["default_branch"] = resolved_default_branch
 
         async with httpx.AsyncClient() as client:
             response = await client.post(
@@ -170,7 +209,7 @@ class GitStorage:
 
         return RepoImpl(
             repo_id,
-            resolved_default_branch,
+            resolved_default_branch or "main",
             api_base_url,
             storage_base_url,
             name,
@@ -178,6 +217,66 @@ class GitStorage:
             self._generate_jwt,
         )
 
+    async def list_repos(
+        self,
+        *,
+        cursor: Optional[str] = None,
+        limit: Optional[int] = None,
+        ttl: Optional[int] = None,
+    ) -> ListReposResult:
+        """List repositories for the organization."""
+        ttl = ttl or DEFAULT_TOKEN_TTL_SECONDS
+        jwt = self._generate_jwt(
+            "org",
+            {"permissions": ["org:read"], "ttl": ttl},
+        )
+
+        params: Dict[str, str] = {}
+        if cursor:
+            params["cursor"] = cursor
+        if limit is not None:
+            params["limit"] = str(limit)
+
+        url = f"{self.options['api_base_url']}/api/v{self.options['api_version']}/repos"
+        if params:
+            url += f"?{urlencode(params)}"
+
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                url,
+                headers={
+                    "Authorization": f"Bearer {jwt}",
+                    "Code-Storage-Agent": get_user_agent(),
+                },
+                timeout=30.0,
+            )
+
+            if not response.is_success:
+                raise ApiError(
+                    f"Failed to list repositories: {response.status_code} {response.reason_phrase}",
+                    status_code=response.status_code,
+                    response=response,
+                )
+
+            data = response.json()
+            repos: list[RepoInfo] = []
+            for repo in data.get("repos", []):
+                entry: RepoInfo = {
+                    "repo_id": repo.get("repo_id", ""),
+                    "url": repo.get("url", ""),
+                    "default_branch": repo.get("default_branch", "main"),
+                    "created_at": repo.get("created_at", ""),
+                }
+                if repo.get("base_repo"):
+                    entry["base_repo"] = repo.get("base_repo")
+                repos.append(entry)
+
+            return {
+                "repos": repos,
+                "next_cursor": data.get("next_cursor"),
+                "has_more": data.get("has_more", False),
+            }
+
     async def find_one(self, *, id: str) -> Optional[Repo]:
         """Find a repository by ID.
 

{pierre_storage-0.10.0 → pierre_storage-0.12.0}/pierre_storage/repo.py

@@ -33,6 +33,8 @@ from pierre_storage.types import (
     ListBranchesResult,
     ListCommitsResult,
     ListFilesResult,
+    NoteReadResult,
+    NoteWriteResult,
     RefUpdate,
     RestoreCommitResult,
 )
@@ -498,6 +500,122 @@ class RepoImpl:
                 "has_more": data["has_more"],
             }
 
+    async def get_note(
+        self,
+        *,
+        sha: str,
+        ttl: Optional[int] = None,
+    ) -> NoteReadResult:
+        """Read a git note."""
+        sha_clean = sha.strip()
+        if not sha_clean:
+            raise ValueError("get_note sha is required")
+
+        ttl = ttl or DEFAULT_TOKEN_TTL_SECONDS
+        jwt = self.generate_jwt(self._id, {"permissions": ["git:read"], "ttl": ttl})
+
+        url = f"{self.api_base_url}/api/v{self.api_version}/repos/notes?{urlencode({'sha': sha_clean})}"
+
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                url,
+                headers={
+                    "Authorization": f"Bearer {jwt}",
+                    "Code-Storage-Agent": get_user_agent(),
+                },
+                timeout=30.0,
+            )
+            response.raise_for_status()
+            data = response.json()
+            return {
+                "sha": data["sha"],
+                "note": data["note"],
+                "ref_sha": data["ref_sha"],
+            }
+
+    async def create_note(
+        self,
+        *,
+        sha: str,
+        note: str,
+        expected_ref_sha: Optional[str] = None,
+        author: Optional[CommitSignature] = None,
+        ttl: Optional[int] = None,
+    ) -> NoteWriteResult:
+        """Create a git note."""
+        return await self._write_note(
+            action_label="create_note",
+            action="add",
+            sha=sha,
+            note=note,
+            expected_ref_sha=expected_ref_sha,
+            author=author,
+            ttl=ttl,
+        )
+
+    async def append_note(
+        self,
+        *,
+        sha: str,
+        note: str,
+        expected_ref_sha: Optional[str] = None,
+        author: Optional[CommitSignature] = None,
+        ttl: Optional[int] = None,
+    ) -> NoteWriteResult:
+        """Append to a git note."""
+        return await self._write_note(
+            action_label="append_note",
+            action="append",
+            sha=sha,
+            note=note,
+            expected_ref_sha=expected_ref_sha,
+            author=author,
+            ttl=ttl,
+        )
+
+    async def delete_note(
+        self,
+        *,
+        sha: str,
+        expected_ref_sha: Optional[str] = None,
+        author: Optional[CommitSignature] = None,
+        ttl: Optional[int] = None,
+    ) -> NoteWriteResult:
+        """Delete a git note."""
+        sha_clean = sha.strip()
+        if not sha_clean:
+            raise ValueError("delete_note sha is required")
+
+        ttl = ttl or DEFAULT_TOKEN_TTL_SECONDS
+        jwt = self.generate_jwt(self._id, {"permissions": ["git:write"], "ttl": ttl})
+
+        payload: Dict[str, Any] = {"sha": sha_clean}
+        if expected_ref_sha and expected_ref_sha.strip():
+            payload["expected_ref_sha"] = expected_ref_sha.strip()
+        if author:
+            author_name = author.get("name", "").strip()
+            author_email = author.get("email", "").strip()
+            if not author_name or not author_email:
+                raise ValueError("delete_note author name and email are required when provided")
+            payload["author"] = {"name": author_name, "email": author_email}
+
+        url = f"{self.api_base_url}/api/v{self.api_version}/repos/notes"
+
+        async with httpx.AsyncClient() as client:
+            response = await client.request(
+                "DELETE",
+                url,
+                headers={
+                    "Authorization": f"Bearer {jwt}",
+                    "Content-Type": "application/json",
+                    "Code-Storage-Agent": get_user_agent(),
+                },
+                json=payload,
+                timeout=30.0,
+            )
+
+            return self._parse_note_write_response(response, "delete_note")
+
     async def get_branch_diff(
         self,
         *,
@@ -1046,6 +1164,123 @@ class RepoImpl:
             self.api_version,
         )
 
+    async def _write_note(
+        self,
+        *,
+        action_label: str,
+        action: str,
+        sha: str,
+        note: str,
+        expected_ref_sha: Optional[str],
+        author: Optional[CommitSignature],
+        ttl: Optional[int],
+    ) -> NoteWriteResult:
+        sha_clean = sha.strip()
+        if not sha_clean:
+            raise ValueError(f"{action_label} sha is required")
+
+        note_clean = note.strip()
+        if not note_clean:
+            raise ValueError(f"{action_label} note is required")
+
+        ttl = ttl or DEFAULT_TOKEN_TTL_SECONDS
+        jwt = self.generate_jwt(self._id, {"permissions": ["git:write"], "ttl": ttl})
+
+        payload: Dict[str, Any] = {
+            "sha": sha_clean,
+            "action": action,
+            "note": note_clean,
+        }
+        if expected_ref_sha and expected_ref_sha.strip():
+            payload["expected_ref_sha"] = expected_ref_sha.strip()
+        if author:
+            author_name = author.get("name", "").strip()
+            author_email = author.get("email", "").strip()
+            if not author_name or not author_email:
+                raise ValueError(f"{action_label} author name and email are required when provided")
+            payload["author"] = {"name": author_name, "email": author_email}
+
+        url = f"{self.api_base_url}/api/v{self.api_version}/repos/notes"
+
+        async with httpx.AsyncClient() as client:
+            response = await client.post(
+                url,
+                headers={
+                    "Authorization": f"Bearer {jwt}",
+                    "Content-Type": "application/json",
+                    "Code-Storage-Agent": get_user_agent(),
+                },
+                json=payload,
+                timeout=30.0,
+            )
+
+            return self._parse_note_write_response(response, action_label)
+
+    def _parse_note_write_response(
+        self,
+        response: httpx.Response,
+        action_label: str,
+    ) -> NoteWriteResult:
+        try:
+            payload = response.json()
+        except Exception as exc:
+            message = f"{action_label} failed with HTTP {response.status_code}"
+            if response.reason_phrase:
+                message += f" {response.reason_phrase}"
+            try:
+                body_text = response.text
+            except Exception:
+                body_text = ""
+            if body_text:
+                message += f": {body_text[:200]}"
+            raise ApiError(message, status_code=response.status_code, response=response) from exc
+
+        if isinstance(payload, dict) and "error" in payload:
+            raise ApiError(
+                str(payload.get("error")),
+                status_code=response.status_code,
+                response=response,
+            )
+
+        if not isinstance(payload, dict) or "result" not in payload:
+            message = f"{action_label} failed with HTTP {response.status_code}"
+            if response.reason_phrase:
+                message += f" {response.reason_phrase}"
+            raise ApiError(message, status_code=response.status_code, response=response)
+
+        result = payload.get("result", {})
+        note_result: NoteWriteResult = {
+            "sha": payload.get("sha", ""),
+            "target_ref": payload.get("target_ref", ""),
+            "new_ref_sha": payload.get("new_ref_sha", ""),
+            "result": {
+                "success": bool(result.get("success")),
+                "status": str(result.get("status", "")),
+            },
+        }
+
+        base_commit = payload.get("base_commit")
+        if isinstance(base_commit, str) and base_commit:
+            note_result["base_commit"] = base_commit
+        if result.get("message"):
+            note_result["result"]["message"] = result.get("message")
+
+        if not result.get("success"):
+            raise RefUpdateError(
+                result.get(
+                    "message",
+                    f"{action_label} failed with status {result.get('status')}",
+                ),
+                status=result.get("status"),
+                ref_update={
+                    "branch": payload.get("target_ref", ""),
+                    "old_sha": payload.get("base_commit", ""),
+                    "new_sha": payload.get("new_ref_sha", ""),
+                },
+            )
+
+        return note_result
+
     def _to_ref_update(self, result: Dict[str, Any]) -> RefUpdate:
         """Convert result to ref update."""
         return {

{pierre_storage-0.10.0 → pierre_storage-0.12.0}/pierre_storage/types.py

@@ -41,7 +41,7 @@ class GitStorageOptions(TypedDict, total=False):
     default_ttl: Optional[int]
 
 
-class BaseRepo(TypedDict, total=False):
+class GitHubBaseRepo(TypedDict, total=False):
     """Base repository configuration for GitHub sync."""
 
     provider: Literal["github"]  # required
@@ -50,6 +50,17 @@ class BaseRepo(TypedDict, total=False):
     default_branch: Optional[str]
 
 
+class ForkBaseRepo(TypedDict, total=False):
+    """Base repository configuration for code storage forks."""
+
+    id: str  # required
+    ref: Optional[str]
+    sha: Optional[str]
+
+
+BaseRepo = Union[GitHubBaseRepo, ForkBaseRepo]
+
+
 class DeleteRepoResult(TypedDict):
     """Result from deleting a repository."""
 
@@ -57,6 +68,33 @@ class DeleteRepoResult(TypedDict):
     message: str
 
 
+# Repository list types
+class RepoBaseInfo(TypedDict):
+    """Base repository info for listed repositories."""
+
+    provider: str
+    owner: str
+    name: str
+
+
+class RepoInfo(TypedDict, total=False):
+    """Repository info in list responses."""
+
+    repo_id: str
+    url: str
+    default_branch: str
+    created_at: str
+    base_repo: NotRequired[RepoBaseInfo]
+
+
+class ListReposResult(TypedDict):
+    """Result from listing repositories."""
+
+    repos: List[RepoInfo]
+    next_cursor: Optional[str]
+    has_more: bool
+
+
 # Removed: GetRemoteURLOptions - now uses **kwargs
 # Removed: CreateRepoOptions - now uses **kwargs
 # Removed: FindOneOptions - now uses **kwargs
@@ -127,6 +165,33 @@ class ListCommitsResult(TypedDict):
     has_more: bool
 
 
+# Git notes types
+class NoteReadResult(TypedDict):
+    """Result from reading a git note."""
+
+    sha: str
+    note: str
+    ref_sha: str
+
+
+class NoteWriteResultPayload(TypedDict):
+    """Result payload for note writes."""
+
+    success: bool
+    status: str
+    message: NotRequired[str]
+
+
+class NoteWriteResult(TypedDict):
+    """Result from writing a git note."""
+
+    sha: str
+    target_ref: str
+    base_commit: NotRequired[str]
+    new_ref_sha: str
+    result: NoteWriteResultPayload
+
+
 # Diff types
 class DiffStats(TypedDict):
     """Statistics about a diff."""
@@ -417,6 +482,50 @@ class Repo(Protocol):
         """List commits in the repository."""
         ...
 
+    async def get_note(
+        self,
+        *,
+        sha: str,
+        ttl: Optional[int] = None,
+    ) -> NoteReadResult:
+        """Read a git note."""
+        ...
+
+    async def create_note(
+        self,
+        *,
+        sha: str,
+        note: str,
+        expected_ref_sha: Optional[str] = None,
+        author: Optional["CommitSignature"] = None,
+        ttl: Optional[int] = None,
+    ) -> NoteWriteResult:
+        """Create a git note."""
+        ...
+
+    async def append_note(
+        self,
+        *,
+        sha: str,
+        note: str,
+        expected_ref_sha: Optional[str] = None,
+        author: Optional["CommitSignature"] = None,
+        ttl: Optional[int] = None,
+    ) -> NoteWriteResult:
+        """Append to a git note."""
+        ...
+
+    async def delete_note(
+        self,
+        *,
+        sha: str,
+        expected_ref_sha: Optional[str] = None,
+        author: Optional["CommitSignature"] = None,
+        ttl: Optional[int] = None,
+    ) -> NoteWriteResult:
+        """Delete a git note."""
+        ...
+
     async def get_branch_diff(
         self,
         *,

{pierre_storage-0.10.0 → pierre_storage-0.12.0/pierre_storage.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pierre-storage
-Version: 0.10.0
+Version: 0.12.0
 Summary: Pierre Git Storage SDK for Python
 Author-email: Pierre <support@pierre.io>
 License-Expression: MIT
@@ -83,6 +83,15 @@ github_repo = await storage.create_repo(
     }
 )
 # This repository will sync with github.com/octocat/Hello-World
+
+# Create a repository by forking an existing repo
+forked_repo = await storage.create_repo(
+    id="my-fork",
+    base_repo={
+        "id": "my-template-id",
+        "ref": "main",  # optional
+    },
+)
 ```
 
 ### Finding a Repository
@@ -149,6 +158,10 @@ repo = await storage.create_repo()
 # or
 repo = await storage.find_one(id="existing-repo-id")
 
+# List repositories for the org
+repos = await storage.list_repos(limit=20)
+print(repos["repos"])
+
 # Get file content (streaming)
 response = await repo.get_file_stream(
     path="README.md",
@@ -190,6 +203,27 @@ commits = await repo.list_commits(
 )
 print(commits["commits"])
 
+# Read a git note for a commit
+note = await repo.get_note(sha="abc123...")
+print(note["note"])
+
+# Add a git note
+note_result = await repo.create_note(
+    sha="abc123...",
+    note="Release QA approved",
+    author={"name": "Release Bot", "email": "release@example.com"},
+)
+print(note_result["new_ref_sha"])
+
+# Append to a git note
+await repo.append_note(
+    sha="abc123...",
+    note="Follow-up review complete",
+)
+
+# Delete a git note
+await repo.delete_note(sha="abc123...")
+
 # Get branch diff
 branch_diff = await repo.get_branch_diff(
     branch="feature-branch",
@@ -447,6 +481,23 @@ commits = await repo.list_commits()
 3. You can then use all Pierre SDK features (diffs, commits, file access) on the synced content
 4. The provider is automatically set to `"github"` when using `base_repo`
 
+### Forking Repositories
+
+You can fork an existing repository within the same Pierre org:
+
+```python
+forked_repo = await storage.create_repo(
+    id="my-fork",
+    base_repo={
+        "id": "my-template-id",
+        "ref": "main",  # optional (branch/tag)
+        # "sha": "abc123..."  # optional commit SHA (overrides ref)
+    },
+)
+```
+
+When `default_branch` is omitted, the SDK returns `"main"`.
+
 ### Restoring Commits
 
 You can restore a repository to a previous commit:
@@ -475,7 +526,7 @@ class GitStorage:
         self,
         *,
         id: Optional[str] = None,
-        default_branch: str = "main",
+        default_branch: Optional[str] = None,  # defaults to "main"
         base_repo: Optional[BaseRepo] = None,
         ttl: Optional[int] = None,
     ) -> Repo: ...
@@ -614,6 +665,8 @@ Key types are provided via TypedDict for better IDE support:
 from pierre_storage.types import (
     GitStorageOptions,
     BaseRepo,
+    GitHubBaseRepo,
+    ForkBaseRepo,
     CommitSignature,
     CreateCommitOptions,
     ListFilesResult,
@@ -627,12 +680,19 @@ from pierre_storage.types import (
     # ... and more
 )
 
-# BaseRepo type for GitHub sync
-class BaseRepo(TypedDict, total=False):
-    provider: Literal["github"]  # Always "github"
+# BaseRepo type for GitHub sync or forks
+class GitHubBaseRepo(TypedDict, total=False):
+    provider: Literal["github"]   # Always "github"
     owner: str                    # GitHub organization or user
     name: str                     # Repository name
     default_branch: Optional[str] # Default branch (optional)
+
+class ForkBaseRepo(TypedDict, total=False):
+    id: str                       # Source repo ID
+    ref: Optional[str]            # Optional ref name
+    sha: Optional[str]            # Optional commit SHA
+
+BaseRepo = Union[GitHubBaseRepo, ForkBaseRepo]
 ```
 
 ## Webhook Validation

{pierre_storage-0.10.0 → pierre_storage-0.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pierre-storage"
-version = "0.10.0"
+version = "0.12.0"
 description = "Pierre Git Storage SDK for Python"
 readme = "README.md"
 license = "MIT"

{pierre_storage-0.10.0 → pierre_storage-0.12.0}/tests/test_client.py

@@ -147,6 +147,42 @@ class TestGitStorage:
             body = call_kwargs["json"]
             assert body["base_repo"]["provider"] == "github"
 
+    @pytest.mark.asyncio
+    async def test_create_repo_with_fork_base_repo(self, git_storage_options: dict) -> None:
+        """Test creating a forked repository."""
+        storage = GitStorage(git_storage_options)
+
+        mock_post_response = MagicMock()
+        mock_post_response.status_code = 200
+        mock_post_response.is_success = True
+        mock_post_response.json.return_value = {"repo_id": "test-repo"}
+
+        with patch("httpx.AsyncClient") as mock_client:
+            client_instance = mock_client.return_value.__aenter__.return_value
+            client_instance.post = AsyncMock(return_value=mock_post_response)
+
+            repo = await storage.create_repo(
+                id="test-repo",
+                base_repo={
+                    "id": "template-repo",
+                    "ref": "develop",
+                },
+            )
+            assert repo.default_branch == "main"
+
+            call_kwargs = client_instance.post.call_args[1]
+            body = call_kwargs["json"]
+            assert "default_branch" not in body
+            assert body["base_repo"]["provider"] == "code"
+            assert body["base_repo"]["name"] == "template-repo"
+            assert body["base_repo"]["operation"] == "fork"
+            assert body["base_repo"]["ref"] == "develop"
+
+            token = body["base_repo"]["auth"]["token"]
+            payload = jwt.decode(token, options={"verify_signature": False})
+            assert payload["repo"] == "template-repo"
+            assert payload["scopes"] == ["git:read"]
+
     @pytest.mark.asyncio
     async def test_create_repo_conflict(self, git_storage_options: dict) -> None:
         """Test creating a repository that already exists."""
@@ -164,6 +200,68 @@ class TestGitStorage:
             with pytest.raises(ApiError, match="Repository already exists"):
                 await storage.create_repo(id="existing-repo")
 
+    @pytest.mark.asyncio
+    async def test_list_repos(self, git_storage_options: dict) -> None:
+        """Test listing repositories."""
+        storage = GitStorage(git_storage_options)
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "repos": [
+                {
+                    "repo_id": "repo-1",
+                    "url": "owner/repo-1",
+                    "default_branch": "main",
+                    "created_at": "2024-01-01T00:00:00Z",
+                    "base_repo": {"provider": "github", "owner": "owner", "name": "repo-1"},
+                }
+            ],
+            "next_cursor": None,
+            "has_more": False,
+        }
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_get = AsyncMock(return_value=mock_response)
+            mock_client.return_value.__aenter__.return_value.get = mock_get
+
+            result = await storage.list_repos()
+            assert result["has_more"] is False
+            assert result["repos"][0]["repo_id"] == "repo-1"
+
+            call_kwargs = mock_get.call_args[1]
+            headers = call_kwargs["headers"]
+            token = headers["Authorization"].replace("Bearer ", "")
+            payload = jwt.decode(token, options={"verify_signature": False})
+            assert payload["scopes"] == ["org:read"]
+            assert payload["repo"] == "org"
+
+    @pytest.mark.asyncio
+    async def test_list_repos_with_cursor(self, git_storage_options: dict) -> None:
+        """Test listing repositories with pagination."""
+        storage = GitStorage(git_storage_options)
+
+        mock_response = MagicMock()
+        mock_response.status_code = 200
+        mock_response.is_success = True
+        mock_response.json.return_value = {
+            "repos": [],
+            "next_cursor": "next",
+            "has_more": True,
+        }
+
+        with patch("httpx.AsyncClient") as mock_client:
+            mock_get = AsyncMock(return_value=mock_response)
+            mock_client.return_value.__aenter__.return_value.get = mock_get
+
+            await storage.list_repos(cursor="cursor-1", limit=10)
+
+            call_args = mock_get.call_args[0]
+            api_url = call_args[0]
+            assert "cursor=cursor-1" in api_url
+            assert "limit=10" in api_url
+
     @pytest.mark.asyncio
     async def test_find_one(self, git_storage_options: dict) -> None:
         """Test finding a repository."""

{pierre_storage-0.10.0 → pierre_storage-0.12.0}/tests/test_repo.py

@@ -654,6 +654,118 @@ class TestRepoCommitOperations:
             assert result["ref_update"]["old_sha"] == "old-sha"
 
 
+class TestRepoNoteOperations:
+    """Tests for git note operations."""
+
+    @pytest.mark.asyncio
+    async def test_get_note(self, git_storage_options: dict) -> None:
+        """Test reading a git note."""
+        storage = GitStorage(git_storage_options)
+
+        create_response = MagicMock()
+        create_response.status_code = 200
+        create_response.is_success = True
+        create_response.json.return_value = {"repo_id": "test-repo"}
+
+        note_response = MagicMock()
+        note_response.status_code = 200
+        note_response.is_success = True
+        note_response.raise_for_status = MagicMock()
+        note_response.json.return_value = {
+            "sha": "abc123",
+            "note": "hello notes",
+            "ref_sha": "def456",
+        }
+
+        with patch("httpx.AsyncClient") as mock_client:
+            client_instance = mock_client.return_value.__aenter__.return_value
+            client_instance.post = AsyncMock(return_value=create_response)
+            client_instance.get = AsyncMock(return_value=note_response)
+
+            repo = await storage.create_repo(id="test-repo")
+            result = await repo.get_note(sha="abc123")
+
+            assert result["sha"] == "abc123"
+            assert result["note"] == "hello notes"
+            assert result["ref_sha"] == "def456"
+
+    @pytest.mark.asyncio
+    async def test_create_append_delete_note(self, git_storage_options: dict) -> None:
+        """Test creating, appending, and deleting git notes."""
+        storage = GitStorage(git_storage_options)
+
+        create_response = MagicMock()
+        create_response.status_code = 200
+        create_response.is_success = True
+        create_response.json.return_value = {"repo_id": "test-repo"}
+
+        create_note_response = MagicMock()
+        create_note_response.status_code = 201
+        create_note_response.is_success = True
+        create_note_response.json.return_value = {
+            "sha": "abc123",
+            "target_ref": "refs/notes/commits",
+            "new_ref_sha": "def456",
+            "result": {"success": True, "status": "ok"},
+        }
+
+        append_note_response = MagicMock()
+        append_note_response.status_code = 200
+        append_note_response.is_success = True
+        append_note_response.json.return_value = {
+            "sha": "abc123",
+            "target_ref": "refs/notes/commits",
+            "new_ref_sha": "ghi789",
+            "result": {"success": True, "status": "ok"},
+        }
+
+        delete_note_response = MagicMock()
+        delete_note_response.status_code = 200
+        delete_note_response.is_success = True
+        delete_note_response.json.return_value = {
+            "sha": "abc123",
+            "target_ref": "refs/notes/commits",
+            "new_ref_sha": "ghi789",
+            "result": {"success": True, "status": "ok"},
+        }
+
+        with patch("httpx.AsyncClient") as mock_client:
+            client_instance = mock_client.return_value.__aenter__.return_value
+            client_instance.post = AsyncMock(
+                side_effect=[create_response, create_note_response, append_note_response]
+            )
+            client_instance.request = AsyncMock(return_value=delete_note_response)
+
+            repo = await storage.create_repo(id="test-repo")
+
+            create_result = await repo.create_note(sha="abc123", note="note content")
+            assert create_result["new_ref_sha"] == "def456"
+
+            append_result = await repo.append_note(sha="abc123", note="note append")
+            assert append_result["new_ref_sha"] == "ghi789"
+
+            delete_result = await repo.delete_note(sha="abc123")
+            assert delete_result["target_ref"] == "refs/notes/commits"
+
+            create_call = client_instance.post.call_args_list[1]
+            assert create_call.kwargs["json"] == {
+                "sha": "abc123",
+                "action": "add",
+                "note": "note content",
+            }
+
+            append_call = client_instance.post.call_args_list[2]
+            assert append_call.kwargs["json"] == {
+                "sha": "abc123",
+                "action": "append",
+                "note": "note append",
+            }
+
+            delete_call = client_instance.request.call_args_list[0]
+            assert delete_call.args[0] == "DELETE"
+            assert delete_call.kwargs["json"] == {"sha": "abc123"}
+
+
 class TestRepoDiffOperations:
     """Tests for diff operations."""