gitd 0.7.0__tar.gz

gitd-0.7.0/.gitignore

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

gitd-0.7.0/PKG-INFO

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: gitd
+Version: 0.7.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 :: POSIX :: Linux
+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
+```
+
+```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)` | Its commits pushed to a new branch |
+| `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 |
+
+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. Apache-2.0.

gitd-0.7.0/README.md

@@ -0,0 +1,60 @@
+# 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
+```
+
+```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)` | Its commits pushed to a new branch |
+| `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 |
+
+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. Apache-2.0.

gitd-0.7.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-0.7.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling>=1.32.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gitd"
+version = "0.7.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 :: POSIX :: Linux",
+  "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-0.7.0/src/gitd/__init__.py

@@ -0,0 +1,42 @@
+"""Client for gitd: instant, secretless git checkouts for agent sandboxes."""
+
+from .client import Gitd
+from .connection import DEFAULT_SOCKET, SOCKET_VARIABLE
+from .errors import GitdError
+from .models import (
+    Access,
+    AuditEntry,
+    Description,
+    Info,
+    Layers,
+    PendingSubmodule,
+    Probe,
+    Progress,
+    Published,
+    PublishedRepository,
+    Refusal,
+    Strategy,
+    Submodule,
+    Workspace,
+)
+
+__all__ = [
+    "DEFAULT_SOCKET",
+    "SOCKET_VARIABLE",
+    "Access",
+    "AuditEntry",
+    "Description",
+    "Gitd",
+    "GitdError",
+    "Info",
+    "Layers",
+    "PendingSubmodule",
+    "Probe",
+    "Progress",
+    "Published",
+    "PublishedRepository",
+    "Refusal",
+    "Strategy",
+    "Submodule",
+    "Workspace",
+]

gitd-0.7.0/src/gitd/client.py

@@ -0,0 +1,124 @@
+"""The gitd client."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from . import messages, methods
+from .connection import Connection, OnProgress
+from .models import AuditEntry, Description, Info, Probe, Published, Strategy, Workspace
+from .timestamps import Timestamp
+
+
+class Gitd:
+    """A gitd on its Unix socket. No call takes a credential: gitd reads and publishes with
+    the ones it keeps.
+
+        with Gitd() as gitd:
+            workspace = gitd.prepare("https://github.com/acme/web", "/var/lib/gitd/workspaces/agent-1")
+    """
+
+    def __init__(self, socket: str | None = None, *, timeout: float | None = None) -> None:
+        self.connection = Connection(socket, timeout)
+
+    def __enter__(self) -> Gitd:
+        return self
+
+    def __exit__(self, *exception: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self.connection.close()
+
+    def info(self) -> Info:
+        """Which gitd answers, and how it makes workspaces here and why."""
+        return Info.from_message(self.connection.call(methods.INFO, messages.InfoRequest()))
+
+    def probe(self, url: str) -> Probe:
+        """Whether a repository can be read with the credentials gitd keeps, and its branches."""
+        return Probe.from_message(self.connection.call(methods.PROBE, messages.ProbeRequest(url=url)))
+
+    def prepare(
+        self,
+        url: str,
+        path: str,
+        *,
+        branch: str | None = None,
+        commit: str | None = None,
+        submodules: bool = False,
+        full_history: bool = False,
+        strategy: Strategy | None = None,
+        on_progress: OnProgress | None = None,
+    ) -> Workspace:
+        """Makes a workspace of a repository at a path under gitd's roots, at a commit, a
+        branch, or the default branch. strategy is a preference: gitd falls back to copy when
+        it cannot make one that way here."""
+        if commit:
+            revision = messages.Revision(commit=commit)
+        elif branch:
+            revision = messages.Revision(branch=branch)
+        else:
+            revision = None
+        request = messages.PrepareRequest(
+            url=url,
+            path=path,
+            revision=revision,
+            with_submodules=submodules,
+            full_history=full_history,
+            strategy=Strategy.preference(strategy),
+        )
+        return Workspace.from_message(path, self.connection.follow(methods.PREPARE, request, on_progress))
+
+    def update(
+        self,
+        path: str,
+        *,
+        branch: str | None = None,
+        submodules: bool = False,
+        on_progress: OnProgress | None = None,
+    ) -> Workspace:
+        """Brings a workspace to the tip of its branch, or of the branch given."""
+        request = messages.UpdateRequest(path=path, branch=branch or "", with_submodules=submodules)
+        return Workspace.from_message(path, self.connection.follow(methods.UPDATE, request, on_progress))
+
+    def checkout(
+        self,
+        path: str,
+        commit: str,
+        *,
+        submodules: bool = False,
+        on_progress: OnProgress | None = None,
+    ) -> Workspace:
+        """Moves a workspace to a commit, as a rollback does."""
+        request = messages.CheckoutRequest(path=path, commit=commit, with_submodules=submodules)
+        return Workspace.from_message(path, self.connection.follow(methods.CHECKOUT, request, on_progress))
+
+    def describe(self, path: str) -> Description:
+        """What a workspace is on disk, without the network."""
+        response = self.connection.call(methods.DESCRIBE, messages.DescribeRequest(path=path))
+        return Description.from_message(response)
+
+    def publish(self, path: str, branch: str) -> Published:
+        """Pushes what was committed in a workspace to a new branch, with the token gitd keeps."""
+        response = self.connection.call(methods.PUBLISH, messages.PublishRequest(path=path, branch=branch))
+        return Published.from_message(response)
+
+    def remove(self, path: str) -> None:
+        """Deletes a workspace; its pool stays."""
+        self.connection.call(methods.REMOVE, messages.RemoveRequest(path=path))
+
+    def audit(
+        self,
+        *,
+        since: datetime | None = None,
+        url: str | None = None,
+        limit: int | None = None,
+    ) -> list[AuditEntry]:
+        """The audit log: every publish, done or refused, newest first; from since on, of
+        the repository at url, at most limit of them (100 by default, never more than 1000)."""
+        request: Any = messages.AuditRequest(url=url or "", limit=limit or 0)
+        if since is not None:
+            Timestamp.fill(request.since, since)
+        response = self.connection.call(methods.AUDIT, request)
+        return [AuditEntry.from_message(entry) for entry in response.entries]

gitd-0.7.0/src/gitd/connection.py

@@ -0,0 +1,71 @@
+"""The channel to gitd's Unix socket, and how a call on it is made and read."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from typing import Any
+
+import grpc
+from google.protobuf.message import Message
+
+from .errors import GitdError
+from .methods import Method
+from .models import Progress
+
+DEFAULT_SOCKET = "/run/gitd/gitd.sock"
+SOCKET_VARIABLE = "GITD_SOCKET"
+
+OnProgress = Callable[[Progress], None]
+
+
+class Connection:
+    """A channel to gitd. The socket defaults to $GITD_SOCKET, then /run/gitd/gitd.sock; the
+    timeout, in seconds, bounds every call, which gitd otherwise bounds itself."""
+
+    def __init__(self, socket: str | None, timeout: float | None) -> None:
+        self.socket = socket or os.environ.get(SOCKET_VARIABLE) or DEFAULT_SOCKET
+        self.timeout = timeout
+        self.channel = grpc.insecure_channel(f"unix:{self.socket}")
+
+    def close(self) -> None:
+        self.channel.close()
+
+    @staticmethod
+    def serialize(message: Message) -> bytes:
+        return message.SerializeToString()
+
+    def call(self, method: Method, request: Message) -> Any:
+        """Makes a call that answers once."""
+        invoke: grpc.UnaryUnaryMultiCallable[Message, Any] = self.channel.unary_unary(
+            method.path,
+            request_serializer=self.serialize,
+            response_deserializer=method.response.FromString,
+        )
+        try:
+            return invoke(request, timeout=self.timeout)
+        except grpc.RpcError as error:
+            raise GitdError.from_rpc_error(error) from None
+
+    def follow(
+        self,
+        method: Method,
+        request: Message,
+        on_progress: OnProgress | None,
+    ) -> Any:
+        """Makes a call that streams its progress, and reads it to its result."""
+        invoke: grpc.UnaryStreamMultiCallable[Message, Any] = self.channel.unary_stream(
+            method.path,
+            request_serializer=self.serialize,
+            response_deserializer=method.response.FromString,
+        )
+        try:
+            for response in invoke(request, timeout=self.timeout):
+                event = response.WhichOneof("event")
+                if event == "progress" and on_progress is not None:
+                    on_progress(Progress.from_message(response.progress))
+                elif event == "result":
+                    return response.result
+        except grpc.RpcError as error:
+            raise GitdError.from_rpc_error(error) from None
+        raise GitdError("", "gitd ended the call without a result")