gitd-client 0.14.0__tar.gz

gitd_client-0.14.0/.gitignore

@@ -0,0 +1,3 @@
+__pycache__/
+dist/
+*.egg-info/

gitd_client-0.14.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: gitd-client
+Version: 0.14.0
+Summary: Client for gitd: instant, secretless git checkouts for agent sandboxes
+Project-URL: Homepage, https://github.com/dooservice/gitd
+Project-URL: Source, https://github.com/dooservice/gitd/tree/main/sdk/python
+License-Expression: Apache-2.0
+Keywords: ai-agents,git,grpc,sandbox,workspace
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Requires-Dist: grpcio-status>=1.84.0
+Requires-Dist: grpcio>=1.84.0
+Requires-Dist: protobuf>=7.36.2
+Description-Content-Type: text/markdown
+
+# gitd for Python
+
+A client for [gitd](https://github.com/dooservice/gitd): instant, secretless git checkouts
+for agent sandboxes. Your agents work in their own copy and publish a branch; they never
+see your token.
+
+```sh
+pip install gitd-client
+```
+
+It is imported as `gitd`. Up to 0.13.0 it was published as `gitd`; from 0.14.0 it is
+`gitd-client`, the name every gitd client has.
+
+```python
+from gitd import Gitd, GitdError
+
+with Gitd() as gitd:                      # $GITD_SOCKET, then /run/gitd/gitd.sock
+    workspace = gitd.prepare("https://github.com/acme/web", "/var/lib/gitd/workspaces/agent-1")
+    print(workspace.path, workspace.commit, workspace.strategy)
+
+    # … the agent works in workspace.path with plain git, and commits …
+
+    published = gitd.publish(workspace.path, "agents/fix-login")
+    gitd.remove(workspace.path)
+```
+
+No call takes a credential: gitd reads and publishes with the ones it keeps.
+
+| Method | What it does |
+|---|---|
+| `prepare(url, path, *, branch, commit, submodules, full_history, strategy, on_progress)` | A workspace of a repository at a path under gitd's roots |
+| `update(path, *, branch, submodules, on_progress)` | To the tip of its branch, or of the branch given |
+| `checkout(path, commit, *, submodules, on_progress)` | To a commit, as a rollback does |
+| `describe(path)` | Its repository, commit, branch, uncommitted changes and submodules |
+| `publish(path, branch, *, requested_by, pull_request, provenance, sandbox, update)` | Its commits pushed to a new branch, or with `update` an earlier publish's branch moved forward; its pull request opened or updated |
+| `remove(path)` | Deleted; its pool stays |
+| `probe(url)` | Whether it can be read, its default branch and branches |
+| `info()` | Which gitd answers, and how it makes workspaces here and why |
+| `audit(*, since, url, limit)` | Every publish, done or refused, newest first |
+
+```python
+from gitd import PullRequestOptions
+
+published = gitd.publish(
+    workspace.path, "agents/fix-login", update=True,
+    pull_request=PullRequestOptions(open=True, submodules=True, title="Fix the login", body="…"),
+)
+print(published.pull_request.url, published.pull_request.updated)
+for submodule in published.submodule_pull_requests:   # merged first, with a merge commit
+    print(submodule.path, submodule.pull_request or submodule.refused)
+```
+
+A refusal raises `GitdError`, with `reason` (`AUTH_REQUIRED`, `NOT_FOUND`, `PATH_REFUSED`,
+`BRANCH_REFUSED`, `BUSY`, …) and `said`, what git said. Decide from the reason, never from
+the message.
+
+[`examples/agent.py`](examples/agent.py) is an agent's whole round trip.
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `src/gitd/client.py` | `Gitd`, the client |
+| `src/gitd/models.py` | What gitd answers, as dataclasses |
+| `src/gitd/errors.py` | `GitdError` |
+| `src/gitd/timestamps.py` | Between the contract's timestamps and `datetime` |
+| `src/gitd/connection.py` | The channel to the socket, and how calls are made |
+| `src/gitd/methods.py` | The gitd methods called, by their gRPC path |
+| `src/gitd/messages.py` | The messages of the contract the client uses |
+| `src/gitd/contract.py` | Reads the contract at run time, with protobuf's public API |
+| `src/gitd/contract.json` | The contract, built from [`proto/gitd/v1/gitd.proto`](../../proto/gitd/v1/gitd.proto) by `make generate` |
+
+No code is generated: the client reads gitd's contract when it starts.
+
+Python 3.11 or later, on Linux, macOS and Windows. Apache-2.0.

gitd_client-0.14.0/README.md

@@ -0,0 +1,75 @@
+# gitd for Python
+
+A client for [gitd](https://github.com/dooservice/gitd): instant, secretless git checkouts
+for agent sandboxes. Your agents work in their own copy and publish a branch; they never
+see your token.
+
+```sh
+pip install gitd-client
+```
+
+It is imported as `gitd`. Up to 0.13.0 it was published as `gitd`; from 0.14.0 it is
+`gitd-client`, the name every gitd client has.
+
+```python
+from gitd import Gitd, GitdError
+
+with Gitd() as gitd:                      # $GITD_SOCKET, then /run/gitd/gitd.sock
+    workspace = gitd.prepare("https://github.com/acme/web", "/var/lib/gitd/workspaces/agent-1")
+    print(workspace.path, workspace.commit, workspace.strategy)
+
+    # … the agent works in workspace.path with plain git, and commits …
+
+    published = gitd.publish(workspace.path, "agents/fix-login")
+    gitd.remove(workspace.path)
+```
+
+No call takes a credential: gitd reads and publishes with the ones it keeps.
+
+| Method | What it does |
+|---|---|
+| `prepare(url, path, *, branch, commit, submodules, full_history, strategy, on_progress)` | A workspace of a repository at a path under gitd's roots |
+| `update(path, *, branch, submodules, on_progress)` | To the tip of its branch, or of the branch given |
+| `checkout(path, commit, *, submodules, on_progress)` | To a commit, as a rollback does |
+| `describe(path)` | Its repository, commit, branch, uncommitted changes and submodules |
+| `publish(path, branch, *, requested_by, pull_request, provenance, sandbox, update)` | Its commits pushed to a new branch, or with `update` an earlier publish's branch moved forward; its pull request opened or updated |
+| `remove(path)` | Deleted; its pool stays |
+| `probe(url)` | Whether it can be read, its default branch and branches |
+| `info()` | Which gitd answers, and how it makes workspaces here and why |
+| `audit(*, since, url, limit)` | Every publish, done or refused, newest first |
+
+```python
+from gitd import PullRequestOptions
+
+published = gitd.publish(
+    workspace.path, "agents/fix-login", update=True,
+    pull_request=PullRequestOptions(open=True, submodules=True, title="Fix the login", body="…"),
+)
+print(published.pull_request.url, published.pull_request.updated)
+for submodule in published.submodule_pull_requests:   # merged first, with a merge commit
+    print(submodule.path, submodule.pull_request or submodule.refused)
+```
+
+A refusal raises `GitdError`, with `reason` (`AUTH_REQUIRED`, `NOT_FOUND`, `PATH_REFUSED`,
+`BRANCH_REFUSED`, `BUSY`, …) and `said`, what git said. Decide from the reason, never from
+the message.
+
+[`examples/agent.py`](examples/agent.py) is an agent's whole round trip.
+
+## Layout
+
+| Path | What it is |
+|---|---|
+| `src/gitd/client.py` | `Gitd`, the client |
+| `src/gitd/models.py` | What gitd answers, as dataclasses |
+| `src/gitd/errors.py` | `GitdError` |
+| `src/gitd/timestamps.py` | Between the contract's timestamps and `datetime` |
+| `src/gitd/connection.py` | The channel to the socket, and how calls are made |
+| `src/gitd/methods.py` | The gitd methods called, by their gRPC path |
+| `src/gitd/messages.py` | The messages of the contract the client uses |
+| `src/gitd/contract.py` | Reads the contract at run time, with protobuf's public API |
+| `src/gitd/contract.json` | The contract, built from [`proto/gitd/v1/gitd.proto`](../../proto/gitd/v1/gitd.proto) by `make generate` |
+
+No code is generated: the client reads gitd's contract when it starts.
+
+Python 3.11 or later, on Linux, macOS and Windows. Apache-2.0.

gitd_client-0.14.0/examples/agent.py

@@ -0,0 +1,81 @@
+"""An agent's round trip with gitd:
+
+  1. gitd prepares a workspace of the repository, in milliseconds after the first time;
+  2. the agent works in it with plain git, and commits;
+  3. gitd publishes the commit as a new branch, with the token it keeps.
+
+The agent never holds a credential.
+
+  python examples/agent.py https://github.com/your-org/your-repo /var/lib/gitd/workspaces/agent-1
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from gitd import Gitd, GitdError, Progress, Workspace
+
+AUTHOR = ["-c", "user.name=agent", "-c", "user.email=agent@example.com"]
+BRANCH_PREFIX = "agents/example-"
+NOTE_FILE = "AGENT.md"
+
+
+class Agent:
+    """Works on one repository in its own workspace, and publishes what it commits."""
+
+    def __init__(self, gitd: Gitd, url: str, path: str) -> None:
+        self.gitd = gitd
+        self.url = url
+        self.path = path
+
+    def run(self) -> None:
+        workspace = self.prepare()
+        try:
+            self.commit_a_change(workspace)
+            self.publish(workspace)
+        finally:
+            self.gitd.remove(workspace.path)
+
+    def prepare(self) -> Workspace:
+        workspace = self.gitd.prepare(self.url, self.path, on_progress=self.show_progress)
+        print(file=sys.stderr)
+        print(f"Prepared {workspace.path} at {workspace.commit[:12]}, by {workspace.strategy.value}.")
+        return workspace
+
+    def commit_a_change(self, workspace: Workspace) -> None:
+        Path(workspace.path, NOTE_FILE).write_text("Written by an agent.\n")
+        self.git(workspace, "add", NOTE_FILE)
+        self.git(workspace, "commit", "--quiet", "--message", "An agent was here")
+        print(f"Committed {NOTE_FILE}.")
+
+    def publish(self, workspace: Workspace) -> None:
+        published = self.gitd.publish(workspace.path, f"{BRANCH_PREFIX}{int(time.time())}")
+        repository = published.repositories[0]
+        print(f"Published {published.branch} to {repository.url}: {', '.join(repository.subjects)}.")
+
+    def git(self, workspace: Workspace, *arguments: str) -> None:
+        subprocess.run(["git", *AUTHOR, *arguments], cwd=workspace.path, check=True)
+
+    def show_progress(self, progress: Progress) -> None:
+        print(f"\r{progress.phase} {progress.percent}%", end="", file=sys.stderr)
+
+
+def main(arguments: list[str]) -> int:
+    if len(arguments) != 2:
+        print("usage: python examples/agent.py <repository url> <workspace path>", file=sys.stderr)
+        return 2
+    url, path = arguments
+    with Gitd() as gitd:
+        try:
+            Agent(gitd, url, path).run()
+        except GitdError as error:
+            print(f"gitd refused: {error.reason}: {error.said}", file=sys.stderr)
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

gitd_client-0.14.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.32.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gitd-client"
+version = "0.14.0"
+description = "Client for gitd: instant, secretless git checkouts for agent sandboxes"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+keywords = ["git", "ai-agents", "sandbox", "workspace", "grpc"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Software Development :: Version Control :: Git",
+]
+dependencies = [
+  "grpcio>=1.84.0",
+  "grpcio-status>=1.84.0",
+  "protobuf>=7.36.2",
+]
+
+[project.urls]
+Homepage = "https://github.com/dooservice/gitd"
+Source = "https://github.com/dooservice/gitd/tree/main/sdk/python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gitd"]
+
+[tool.ruff]
+line-length = 110
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "N", "SIM"]

gitd_client-0.14.0/src/gitd/__init__.py

@@ -0,0 +1,88 @@
+"""Client for gitd: instant, secretless git checkouts for agent sandboxes."""
+
+from .changes import ChangedFile, ChangeKind, Changes, Diff
+from .client import Gitd
+from .comparison import Comparison, Conflict, Event, EventKind, Side
+from .connection import DEFAULT_SOCKET, SOCKET_VARIABLE
+from .endpoint_calls import Endpoint
+from .endpoint_tokens import IssuedToken, TokenInfo
+from .errors import GitdError
+from .kept_credentials import AppToCreate, Connected, CredentialKind, KeptCredential, SignIn
+from .models import (
+    Access,
+    AuditEntry,
+    ConfigurationChange,
+    Description,
+    Info,
+    Layers,
+    PendingSubmodule,
+    Probe,
+    Progress,
+    Published,
+    PublishedRepository,
+    Refusal,
+    Strategy,
+    Submodule,
+    SubmodulePullRequest,
+    Workspace,
+)
+from .publishing_settings import (
+    OpenedPullRequest,
+    Opening,
+    Preset,
+    PresetOrigin,
+    Provenance,
+    PublishSettings,
+    PullRequestOptions,
+    PullRequestSettings,
+)
+from .warm_layers import WarmLayer
+
+__all__ = [
+    "Comparison",
+    "Conflict",
+    "Event",
+    "EventKind",
+    "Side",
+    "ChangeKind",
+    "ChangedFile",
+    "Changes",
+    "Diff",
+    "AppToCreate",
+    "ConfigurationChange",
+    "Connected",
+    "CredentialKind",
+    "KeptCredential",
+    "OpenedPullRequest",
+    "Opening",
+    "Preset",
+    "PresetOrigin",
+    "Provenance",
+    "PublishSettings",
+    "PullRequestOptions",
+    "PullRequestSettings",
+    "SignIn",
+    "DEFAULT_SOCKET",
+    "SOCKET_VARIABLE",
+    "Access",
+    "AuditEntry",
+    "Description",
+    "Gitd",
+    "GitdError",
+    "Info",
+    "Layers",
+    "PendingSubmodule",
+    "Probe",
+    "Progress",
+    "Published",
+    "PublishedRepository",
+    "Refusal",
+    "Strategy",
+    "Submodule",
+    "SubmodulePullRequest",
+    "Workspace",
+    "WarmLayer",
+    "Endpoint",
+    "IssuedToken",
+    "TokenInfo",
+]

gitd_client-0.14.0/src/gitd/changes.py

@@ -0,0 +1,77 @@
+"""What was changed in a workspace, and its diff, as plain dataclasses built from the
+messages gitd answers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+from . import messages
+
+KIND_PREFIX = "KIND_"
+
+
+class ChangeKind(StrEnum):
+    """How a file changed: added, modified or deleted."""
+
+    ADDED = "added"
+    MODIFIED = "modified"
+    DELETED = "deleted"
+
+    @classmethod
+    def from_message(cls, number: int) -> ChangeKind:
+        name = messages.CHANGE_KIND.name(number).removeprefix(KIND_PREFIX).lower()
+        return cls(name) if name in {member.value for member in cls} else cls.MODIFIED
+
+
+@dataclass(frozen=True)
+class ChangedFile:
+    """A file changed, relative to the workspace, with its lines; a binary one counts none."""
+
+    path: str
+    kind: ChangeKind
+    added_lines: int
+    removed_lines: int
+    binary: bool
+
+    @classmethod
+    def from_message(cls, file: Any) -> ChangedFile:
+        return cls(
+            path=file.path,
+            kind=ChangeKind.from_message(file.kind),
+            added_lines=file.added_lines,
+            removed_lines=file.removed_lines,
+            binary=file.binary,
+        )
+
+
+@dataclass(frozen=True)
+class Changes:
+    """What was changed in a workspace since gitd put it on base, committed or not.
+    from_layer says it was read from the agent's own layer, with no git run in the workspace."""
+
+    base: str
+    from_layer: bool
+    files: list[ChangedFile] = field(default_factory=list)
+
+    @classmethod
+    def from_message(cls, response: Any) -> Changes:
+        return cls(
+            base=response.base,
+            from_layer=response.from_layer,
+            files=[ChangedFile.from_message(file) for file in response.files],
+        )
+
+
+@dataclass(frozen=True)
+class Diff:
+    """The unified diff of a workspace's changes; truncated says it was cut short."""
+
+    base: str
+    diff: str
+    truncated: bool
+
+    @classmethod
+    def from_message(cls, response: Any) -> Diff:
+        return cls(base=response.base, diff=response.diff, truncated=response.truncated)