angee.integrate.vcs.backend

The host-agnostic git implementation contract.

A :class:VCSBackend is a VcsBridge backend that reads a repository through the bridge child model — either a host's remote over its REST API (integrate_github.GitHubBackend) or a local working tree (:class:LocalVCSBackend) — listing repositories, walking trees, reading blobs, and resolving refs. A host backend never clones (git transport belongs to the operator); the local backend reads files directly for dev/offline inventory. VcsBridge owns the shared enumeration walk over the primitives. This module imports no models, so it breaks no import cycle.

TreeEntry

@dataclass(frozen=True)
class TreeEntry()

One entry in a repository tree at a ref.

path

Full path of the entry relative to the repository root.

type

"tree" for a directory, "blob" for a file.

name

@property
def name() -> str

Return the entry's basename.

RepoDescriptor

@dataclass(frozen=True)
class RepoDescriptor()

A repository as reported by a host's repo listing.

The shape :meth:VCSBackend.ls_repos returns and Repository reconcile upserts into rows.

name

The owner/repo path on the host.

org

The owning org/account login (used to group/sort the listing).

remote

The HTTPS remote URL the operator clones.

VCSBackend

class VCSBackend(BridgeImpl, HttpClientMixin)

Abstract REST backend for a git host, bound to one VcsBridge.

Concrete hosts implement the primitives below; VcsBridge calls into them. The constructor receives the VCS bridge child so the backend can read its credential and bridge-owned config, and reach the shared SSRF-pinned client as self.http.

ls_repos

def ls_repos(*, org: str = "") -> list[RepoDescriptor]

List repositories visible to this bridge, optionally within org.

ls_tree

def ls_tree(repository: Any,
            *,
            ref: str,
            path: str,
            recursive: bool = False) -> list[TreeEntry]

List the tree under path at ref (recursively when asked).

cat_file

def cat_file(repository: Any, *, ref: str, path: str) -> bytes

Return the bytes of one blob at ref; raise FileNotFoundError if absent.

rev_parse

def rev_parse(repository: Any, ref: str) -> str

Resolve ref to a commit oid.

verify_webhook

def verify_webhook(vcs_bridge: Any, request: Any) -> bool

Return whether an inbound webhook request is authentic for this bridge.

search_repos

def search_repos(query: str, *, org: str = "") -> list[RepoDescriptor]

Return repositories whose name matches query — the typeahead source.

get_repo

def get_repo(name: str) -> RepoDescriptor

Return one repository by its owner/repo name; raise FileNotFoundError if absent.

LocalVCSBackend

class LocalVCSBackend(VCSBackend)

Reads a repository straight from a local working tree — for dev/offline inventory.

Where a host backend reads a remote over REST, this walks the filesystem under VcsBridge.config["local_root"], so templates (or skills) committed in the local checkout are inventoried through the same VcsBridge → Source → Template flow as a hosted remote, with no network. It reads the working tree; ref is informational — there is one repo and no commit to resolve.

ls_repos

def ls_repos(*, org: str = "") -> list[RepoDescriptor]

Return the single configured local repository.

ls_tree

def ls_tree(repository: Any,
            *,
            ref: str,
            path: str,
            recursive: bool = False) -> list[TreeEntry]

Walk the working tree under path; entry paths are relative to the repo root.

Prunes _LOCAL_SKIP_DIRS — a working-tree-only concern (a REST host returns committed tree entries and has no such noise), so the filter lives here, not in the host-agnostic VcsBridge.discover walk.

cat_file

def cat_file(repository: Any, *, ref: str, path: str) -> bytes

Return one working-tree file's bytes; raise if absent or a directory.

rev_parse

def rev_parse(repository: Any, ref: str) -> str

Return ref unchanged — a local working tree resolves no commit oid.

search_repos

def search_repos(query: str, *, org: str = "") -> list[RepoDescriptor]

Return the local repository when query matches its name (typeahead).

get_repo

def get_repo(name: str) -> RepoDescriptor

Return the local repository; raise FileNotFoundError on a name mismatch.

verify_webhook

def verify_webhook(vcs_bridge: Any, request: Any) -> bool

Reject inbound webhooks: a local working tree has no host to authenticate.