fastpluggy-git-tools 0.2.1__py3-none-any.whl

fastpluggy_git_tools-0.2.1.dist-info/METADATA

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: fastpluggy-git-tools
+Version: 0.2.1
+Summary: Small stdlib-only managed-clone GitOps client (clone/branch/commit/push) — not a FastPluggy plugin, just a library.
+Author: FastPluggy Team
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: tests
+Requires-Dist: pytest>=7.0; extra == "tests"
+Requires-Dist: pytest-cov>=4.0; extra == "tests"
+
+# git_tools
+
+[![pipeline status](https://gitlab.ggcorp.fr/open/fastpluggy/private_plugins/git_tools/badges/main/pipeline.svg)](https://gitlab.ggcorp.fr/open/fastpluggy/private_plugins/git_tools/-/pipelines)
+[![version](https://img.shields.io/badge/version-0.2.1-blue)](https://gitlab.ggcorp.fr/open/fastpluggy/private_plugins/git_tools/-/releases)
+
+A small, **stdlib-only** managed-clone GitOps client — clone / branch / commit / push for a long-lived
+working clone (typically on `/data`). **Not a FastPluggy plugin**, just a library you `pip install` and
+import.
+
+Extracted and generalized from the proven git logic in `fp-deployer/apps_repo.py` (the careful bits:
+`pull --rebase --autostash`, no-change short-circuit, **conflict-marker refusal**, identity via `-c`,
+**never force-push**), adding **clone-if-missing** and **feature-branch** support for content-repo callers
+like the brain app committing KB captures.
+
+## Why not GitPython / the GitLab API
+- **Subprocess git, no GitPython** → consumers stay dependency-light (and it matches `fp-deployer` /
+  `ecosystem_status`, which deliberately avoid the optional dep). It also lets you run the repo's *own*
+  scripts against the clone (e.g. the KB's `status.py` / `kb_checks.py`).
+- The GitLab Commits API is the clone-free alternative (what `brain/kb_capture.py` uses today); it's fine
+  for simple text commits but blind to repo state. `git_tools` is the clone-based path.
+
+## Usage
+
+```python
+from git_tools import GitRepo
+
+repo = GitRepo(
+    path="/data/kb/fp-tmp-personal",
+    remote_url="https://oauth2:<token>@gitlab.ggcorp.fr/JeJe/fp-tmp-personal.git",  # or git@… + key_path
+    branch="main",
+)
+
+# One call: clone-if-needed → feature branch off main → write → commit → push (idempotent).
+res = repo.commit_files(
+    {"_raw/brain/2026-06-12_x_42/content.md": "...", "_raw/brain/2026-06-12_x_42/meta.yml": "source: brain\n"},
+    "brain capture: x (share 42)",
+    branch="brain-app", base="main",
+)
+# -> {"sha": "abc1234", "committed": True, "branch": "brain-app"}
+```
+
+Auth: embed a token in `remote_url` for HTTPS (`https://oauth2:<token>@host/repo.git`), or pass
+`key_path=` (+ optional `known_hosts=`) for an SSH remote. Serialize concurrent writers on one shared
+clone with `with repo.lock(): ...`.
+
+## API
+`GitRepo(path, remote_url, branch, key_path, known_hosts, author_name, author_email, timeout)` with:
+`ensure_clone()` · `clone_or_refresh()` · `pull_rebase()` · `prepare_branch(branch, base)` ·
+`write_files(files)` · `remove_files(paths)` · `move(src, dest)` · `commit(paths, message, *, stage=True)` ·
+`push(branch)` · `commit_files(...)` (high-level) · `status()` · `lock()`. Working-tree inspection:
+`diff(paths=None, *, staged=None)` · `changed_files(paths=None) -> list[FileChange]`. Failures raise
+`GitError` / `Conflict` (both subclass `GitToolsError`).
+
+`changed_files` parses `git status --porcelain` into `FileChange(path, status, staged)` records — for a
+consumer that works on an *already-checked-out* repo (status/diff/move, no push), e.g. ecosystem_status'
+`wip-ia-code/` flow. (Distinct from `status()`, which probes clone liveness / HEAD.)
+
+```python
+for c in repo.changed_files(["wip-ia-code/"]):   # status --porcelain, scoped
+    print(c.path, c.status, "staged" if c.staged else "unstaged")
+print(repo.diff(["wip-ia-code/"]))               # combined worktree + cached diff
+repo.move("wip-ia-code/a.md", "wip-ia-code/plans/a.md")  # git mv
+```
+
+Delete a subtree symmetrically with the write path — `git rm` stages the removal, so commit with
+`stage=False` (re-adding a now-absent path would fail):
+
+```python
+repo.pull_rebase()
+repo.remove_files(["myapp"])             # git rm -r -- myapp
+res = repo.commit(["myapp"], "drop myapp", stage=False)
+if res["committed"]:
+    repo.push()
+```

fastpluggy_git_tools-0.2.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+git_tools/__init__.py,sha256=zuh7PjWp5xsIeoQmeu2FhDNDaxxHE_WY390HCyf-koQ,523
+git_tools/core.py,sha256=CBDPr_bMelqRYU-MeFLjUV9aFKUFhABZo9MMpzNm5Rg,13460
+fastpluggy_git_tools-0.2.1.dist-info/METADATA,sha256=DN0557POaf0UQlPhXGzbB2ElsqqHwgDkcbiKFoQQKeo,4236
+fastpluggy_git_tools-0.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fastpluggy_git_tools-0.2.1.dist-info/top_level.txt,sha256=WHcKtoU3tlieH2F6-DAU6gAruDSGuNN7upNv7cxOHnE,10
+fastpluggy_git_tools-0.2.1.dist-info/RECORD,,

fastpluggy_git_tools-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fastpluggy_git_tools-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+git_tools

git_tools/__init__.py

@@ -0,0 +1,11 @@
+"""git_tools — a small, stdlib-only managed-clone GitOps client.
+
+    from git_tools import GitRepo
+    repo = GitRepo(path="/data/kb/fp-tmp-personal",
+                   remote_url="https://oauth2:<token>@gitlab.example/grp/repo.git")
+    repo.commit_files({"_raw/brain/x/content.md": "..."},
+                      "brain capture", branch="brain-app", base="main")
+"""
+from .core import Conflict, FileChange, GitError, GitRepo, GitToolsError
+
+__all__ = ["GitRepo", "FileChange", "GitToolsError", "GitError", "Conflict"]

git_tools/core.py

@@ -0,0 +1,310 @@
+"""A small, stdlib-only GitOps client for a managed working clone.
+
+Extracted and generalized from ``fp-deployer/src/apps_repo.py`` (the proven
+pattern: ``pull --rebase --autostash`` → no-change short-circuit → conflict-
+marker refusal → identity-via-``-c`` commit → push, **never force-push**),
+adding the bits a content-repo caller (e.g. the brain app committing KB
+captures) needs that the deployer didn't: **clone-if-missing** and
+**feature-branch** support.
+
+Design: subprocess ``git`` only (no GitPython — keeps callers dependency-light;
+``ecosystem_status`` deliberately avoids the optional dep). Auth is carried by
+``remote_url`` — embed a token for HTTPS (``https://oauth2:<token>@host/repo.git``)
+or pass ``key_path`` for an SSH remote. One clone lives on disk (``/data/...``);
+serialize concurrent writers with ``lock()``.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import shlex
+import subprocess
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_BOT_NAME = "git-tools"
+_BOT_EMAIL = "git-tools@homelab"
+
+
+class GitToolsError(Exception):
+    """Base error (always surfaced to the caller)."""
+
+
+class GitError(GitToolsError):
+    """A git subprocess exited non-zero. Carries argv + stdout/stderr."""
+
+    def __init__(self, argv: list[str], returncode: int, stdout: str, stderr: str):
+        self.argv, self.returncode, self.stdout, self.stderr = argv, returncode, stdout, stderr
+        msg = stderr.strip() or stdout.strip() or f"git {shlex.join(argv)} exit {returncode}"
+        super().__init__(msg)
+
+
+class Conflict(GitError):
+    """A rebase/merge needs manual resolution (rebase aborted; never forced)."""
+
+
+# Porcelain status code -> human label (``?`` and ``C`` map to "new").
+_STATUS_LABELS = {"M": "modified", "A": "new", "D": "deleted", "R": "renamed",
+                  "?": "new", "C": "new"}
+
+
+@dataclass(frozen=True)
+class FileChange:
+    """One changed path from :meth:`GitRepo.changed_files`. A path changed in
+    both the index and the worktree yields two records (staged + unstaged)."""
+
+    path: str
+    status: str  # "modified" | "new" | "deleted" | "renamed"
+    staged: bool
+
+
+@dataclass
+class GitRepo:
+    """A long-lived working clone on disk (typically under ``/data``).
+
+    ``remote_url`` carries auth (HTTPS token or SSH); ``key_path`` is an optional
+    SSH key. ``branch`` is the default branch. Methods are subprocess-only and
+    raise :class:`GitError` (or :class:`Conflict`) on failure.
+    """
+
+    path: Path
+    remote_url: str = ""
+    branch: str = "main"
+    key_path: str = ""
+    known_hosts: str = ""
+    author_name: str = _BOT_NAME
+    author_email: str = _BOT_EMAIL
+    timeout: int = 120
+
+    def __post_init__(self) -> None:
+        self.path = Path(self.path)
+
+    # ---------- low-level ---------------------------------------------------
+    def _env(self) -> dict[str, str]:
+        env = os.environ.copy()
+        if self.key_path:  # SSH remotes: pin the key, no agent/interaction
+            opts = [f"-i {self.key_path}", "-o IdentitiesOnly=yes", "-o BatchMode=yes",
+                    "-o StrictHostKeyChecking=yes"]
+            if self.known_hosts:
+                opts.append(f"-o UserKnownHostsFile={self.known_hosts}")
+            env["GIT_SSH_COMMAND"] = "ssh " + " ".join(opts)
+        env.setdefault("GIT_TERMINAL_PROMPT", "0")  # never block on credential prompts
+        return env
+
+    def _run(self, argv: list[str], cwd: Path) -> str:
+        res = subprocess.run(  # noqa: S603 — controlled argv, never shell=True
+            argv, cwd=str(cwd), env=self._env(),
+            capture_output=True, text=True, timeout=self.timeout,
+        )
+        if res.returncode != 0:
+            raise GitError(argv, res.returncode, res.stdout, res.stderr)
+        return res.stdout
+
+    def _git(self, *args: str) -> str:
+        return self._run(["git", *args], self.path)
+
+    # ---------- clone / sync ------------------------------------------------
+    @property
+    def cloned(self) -> bool:
+        return (self.path / ".git").is_dir()
+
+    def ensure_clone(self) -> None:
+        """Clone ``remote_url`` into ``path`` if not already a working clone."""
+        if self.cloned:
+            return
+        if not self.remote_url:
+            raise GitToolsError("ensure_clone: no remote_url configured")
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._run(["git", "clone", self.remote_url, str(self.path)], self.path.parent)
+
+    def clone_or_refresh(self) -> None:
+        """Clone if missing, else ``pull --rebase --autostash`` the branch."""
+        if not self.cloned:
+            self.ensure_clone()
+            return
+        self.pull_rebase()
+
+    def pull_rebase(self, branch: str | None = None) -> None:
+        """``git pull --rebase --autostash origin <branch>``; never force.
+
+        On rebase failure, abort + raise :class:`Conflict`. A residual stash
+        after a *successful* pull means the autostash pop conflicted (markers
+        now in the worktree) — also raised as a Conflict (the apps_repo caveat).
+        """
+        br = branch or self.branch
+        try:
+            self._git("pull", "--rebase", "--autostash", "origin", br)
+        except GitError as exc:
+            try:
+                self._git("rebase", "--abort")
+            except GitError:
+                pass
+            raise Conflict(exc.argv, exc.returncode, exc.stdout,
+                           f"pull --rebase failed; manual resolution required.\n{exc.stderr}") from exc
+        if self._git("stash", "list").strip():
+            raise Conflict(("pull", "--rebase", "--autostash"), 0, "",
+                           "autostash pop conflicted — unresolved markers in the worktree.")
+
+    # ---------- branch / write / commit ------------------------------------
+    def prepare_branch(self, branch: str, base: str = "main") -> None:
+        """Check out ``branch`` for writing: track the remote branch if it
+        exists, else create it fresh off ``origin/<base>``."""
+        self._git("fetch", "origin")
+        remote_has = False
+        try:
+            self._git("rev-parse", "--verify", f"origin/{branch}")
+            remote_has = True
+        except GitError:
+            remote_has = False
+        if remote_has:
+            self._git("checkout", "-B", branch, f"origin/{branch}")
+        else:
+            self._git("checkout", "-B", branch, f"origin/{base}")
+
+    def write_files(self, files: dict[str, str]) -> None:
+        """Write ``{relpath: content}`` into the worktree (creates parent dirs)."""
+        for rel, content in files.items():
+            dest = self.path / rel
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(content)
+
+    def remove_files(self, paths: list[str]) -> None:
+        """``git rm -r`` the given paths (stages the deletion). Symmetric with
+        :meth:`write_files`; pair with ``commit(paths, msg, stage=False)`` so the
+        already-staged removal isn't re-added — ``git add`` on a now-absent path
+        would fail. The caller guards existence: ``git rm`` raises
+        :class:`GitError` on an untracked/unknown path."""
+        self._git("rm", "-r", "--", *paths)
+
+    def move(self, src: str, dest: str) -> None:
+        """``git mv src dest`` — creating the destination's parent dir first."""
+        (self.path / dest).parent.mkdir(parents=True, exist_ok=True)
+        self._git("mv", src, dest)
+
+    # ---------- working-tree inspection ------------------------------------
+    def diff(self, paths: list[str] | None = None, *, staged: bool | None = None) -> str:
+        """Unified diff of the working tree.
+
+        ``staged``: ``None`` → combined worktree + cached, ``True`` → ``--cached``
+        only, ``False`` → worktree only. ``paths`` restricts to those pathspecs.
+        """
+        targets = ["--", *paths] if paths else []
+        if staged is True:
+            return self._git("diff", "--cached", *targets)
+        if staged is False:
+            return self._git("diff", *targets)
+        parts = []
+        for extra in ([], ["--cached"]):
+            out = self._git("diff", *extra, *targets)
+            if out.strip():
+                parts.append(out)
+        return "\n".join(parts)
+
+    def changed_files(self, paths: list[str] | None = None) -> list[FileChange]:
+        """Working-tree changes via ``git status --porcelain -uall``, parsed into
+        :class:`FileChange` records. A path changed in both the index and the
+        worktree yields two records (staged + unstaged); renames report the new
+        path. ``paths`` restricts the scan.
+
+        NB: distinct from :meth:`status` — that probes *clone liveness* (HEAD /
+        clone_present); this reports *uncommitted changes*."""
+        targets = ["--", *paths] if paths else []
+        out = self._git("status", "--porcelain", "-uall", *targets)
+        changes: list[FileChange] = []
+        for line in out.splitlines():
+            if len(line) < 4:
+                continue
+            index_code, worktree_code, rawpath = line[0], line[1], line[3:]
+            if " -> " in rawpath:  # rename/copy: take the new path
+                rawpath = rawpath.split(" -> ", 1)[1]
+            if index_code not in (" ", "?"):
+                changes.append(FileChange(rawpath, _STATUS_LABELS.get(index_code, "modified"), staged=True))
+            if worktree_code != " ":
+                changes.append(FileChange(rawpath, _STATUS_LABELS.get(worktree_code, "modified"), staged=False))
+        return changes
+
+    def commit(self, paths: list[str], message: str, *, stage: bool = True) -> dict[str, object]:
+        """Stage ``paths`` and commit if anything changed. Returns
+        ``{sha, committed}``. Pass ``stage=False`` when the change is already
+        staged (e.g. a removal via :meth:`remove_files`), so it isn't re-added.
+        Refuses to commit conflict markers; identity is set via ``-c`` (never
+        mutates global git config)."""
+        if stage:
+            self._git("add", "--", *paths)
+        if not self._git("status", "--porcelain", "--", *paths).strip():
+            return {"sha": self._git("rev-parse", "--short", "HEAD").strip(), "committed": False}
+        try:
+            self._git("diff", "--check", "--cached")
+        except GitError as exc:
+            raise Conflict(exc.argv, exc.returncode, exc.stdout,
+                           "refusing to commit: staged content contains conflict markers.") from exc
+        self._git("-c", f"user.name={self.author_name}", "-c", f"user.email={self.author_email}",
+                  "commit", "-m", message)
+        return {"sha": self._git("rev-parse", "--short", "HEAD").strip(), "committed": True}
+
+    def push(self, branch: str | None = None) -> None:
+        br = branch or self.branch
+        self._git("push", "-u", "origin", br)
+
+    # ---------- high-level convenience -------------------------------------
+    def commit_files(self, files: dict[str, str], message: str, *,
+                     branch: str | None = None, base: str = "main", push: bool = True) -> dict[str, object]:
+        """Clone-if-needed → (optional feature branch) → write → commit → push.
+
+        The one-call path for a caller like the brain app: drop a set of files
+        on a (rolling) branch and open them for triage. Idempotent — identical
+        content returns ``committed: False`` without an empty commit.
+        """
+        self.ensure_clone()
+        target = branch or self.branch
+        if branch:
+            self.prepare_branch(branch, base=base)
+        else:
+            self.pull_rebase(target)
+        self.write_files(files)
+        result = self.commit(list(files), message)
+        if push and result["committed"]:
+            self.push(target)
+        result["branch"] = target
+        return result
+
+    # ---------- introspection ----------------------------------------------
+    def status(self) -> dict[str, object]:
+        """Best-effort liveness probe (never raises)."""
+        out: dict[str, object] = {
+            "path": str(self.path), "branch": self.branch,
+            "clone_present": self.cloned, "head": None, "error": None,
+        }
+        if self.cloned:
+            try:
+                out["head"] = self._git("rev-parse", "--short", "HEAD").strip()
+            except GitError as exc:
+                out["error"] = str(exc)
+        else:
+            out["error"] = f"clone missing (no .git in {self.path})"
+        return out
+
+    @contextmanager
+    def lock(self):
+        """Serialize writers on this clone via an O_EXCL lockfile.
+
+        Use around a clone→commit→push cycle when several callers share one
+        on-disk clone — including the *first* call, when ``path`` is still
+        empty. The lockfile lives in the **parent** dir (a sibling of ``path``),
+        never inside it, so it can't make ``git clone`` refuse a non-empty
+        destination. Best-effort cleanup on exit.
+        """
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        lockfile = self.path.parent / f".{self.path.name}.git-tools.lock"
+        fd = os.open(str(lockfile), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        try:
+            yield self
+        finally:
+            os.close(fd)
+            try:
+                os.unlink(str(lockfile))
+            except OSError:
+                pass