fastpluggy-git-tools 0.2.1__tar.gz

fastpluggy_git_tools-0.2.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,74 @@
+# 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/fastpluggy_git_tools.egg-info/PKG-INFO

@@ -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/fastpluggy_git_tools.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+fastpluggy_git_tools.egg-info/PKG-INFO
+fastpluggy_git_tools.egg-info/SOURCES.txt
+fastpluggy_git_tools.egg-info/dependency_links.txt
+fastpluggy_git_tools.egg-info/requires.txt
+fastpluggy_git_tools.egg-info/top_level.txt
+src/git_tools/__init__.py
+src/git_tools/core.py
+tests/test_git_repo.py

fastpluggy_git_tools-0.2.1/fastpluggy_git_tools.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fastpluggy_git_tools-0.2.1/fastpluggy_git_tools.egg-info/requires.txt

@@ -0,0 +1,4 @@
+
+[tests]
+pytest>=7.0
+pytest-cov>=4.0

fastpluggy_git_tools-0.2.1/fastpluggy_git_tools.egg-info/top_level.txt

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

fastpluggy_git_tools-0.2.1/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastpluggy-git-tools"
+version = "0.2.1"
+description = "Small stdlib-only managed-clone GitOps client (clone/branch/commit/push) — not a FastPluggy plugin, just a library."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "FastPluggy Team" }]
+dependencies = []   # stdlib only (subprocess git) — keep consumers dependency-light
+
+[project.optional-dependencies]
+tests = ["pytest>=7.0", "pytest-cov>=4.0"]  # CI template runs pytest --cov
+
+[tool.setuptools]
+packages = ["git_tools"]
+package-dir = { "git_tools" = "src/git_tools" }

fastpluggy_git_tools-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fastpluggy_git_tools-0.2.1/src/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"]

fastpluggy_git_tools-0.2.1/src/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

fastpluggy_git_tools-0.2.1/tests/test_git_repo.py

@@ -0,0 +1,184 @@
+"""Real-git tests against a local bare "remote" (offline, no network)."""
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from git_tools import FileChange, GitRepo
+
+
+def _git(cwd: Path, *args: str) -> str:
+    return subprocess.run(
+        ["git", "-c", "user.name=t", "-c", "user.email=t@t", *args],
+        cwd=str(cwd), capture_output=True, text=True, check=True,
+    ).stdout
+
+
+@pytest.fixture
+def remote(tmp_path: Path) -> Path:
+    """A bare repo seeded with one commit on `main` — stands in for origin."""
+    bare = tmp_path / "remote.git"
+    bare.mkdir()
+    _git(bare, "init", "--bare", "-b", "main")
+    seed = tmp_path / "seed"
+    _git(tmp_path, "clone", str(bare), str(seed))
+    (seed / "README.md").write_text("seed\n")
+    _git(seed, "checkout", "-B", "main")
+    _git(seed, "add", "README.md")
+    _git(seed, "commit", "-m", "seed")
+    _git(seed, "push", "-u", "origin", "main")
+    return bare
+
+
+def _repo(tmp_path: Path, remote: Path, **kw) -> GitRepo:
+    return GitRepo(path=tmp_path / "clone", remote_url=str(remote), branch="main", **kw)
+
+
+def test_commit_files_on_feature_branch(tmp_path, remote):
+    repo = _repo(tmp_path, remote)
+    res = repo.commit_files(
+        {"_raw/brain/x/content.md": "hello", "_raw/brain/x/meta.yml": "source: brain\n"},
+        "brain capture", branch="inbox", base="main",
+    )
+    assert res["committed"] is True and res["branch"] == "inbox"
+
+    # The bare remote now has the files on the `inbox` branch.
+    verify = tmp_path / "verify"
+    _git(tmp_path, "clone", "-b", "inbox", str(remote), str(verify))
+    assert (verify / "_raw/brain/x/content.md").read_text() == "hello"
+
+
+def test_no_change_short_circuit(tmp_path, remote):
+    repo = _repo(tmp_path, remote)
+    files = {"a.md": "same"}
+    first = repo.commit_files(files, "first", branch="inbox", base="main")
+    assert first["committed"] is True
+    again = repo.commit_files(files, "again", branch="inbox", base="main")
+    assert again["committed"] is False  # identical content → no empty commit
+
+
+def test_remove_files_deletes_subtree(tmp_path, remote):
+    repo = _repo(tmp_path, remote)
+    # Seed a subtree on `inbox`, then delete it via remove_files + commit(stage=False).
+    repo.commit_files({"myapp/a.txt": "x", "myapp/b.txt": "y"}, "add myapp",
+                      branch="inbox", base="main")
+    repo.remove_files(["myapp"])
+    res = repo.commit(["myapp"], "drop myapp", stage=False)
+    assert res["committed"] is True
+    assert not (repo.path / "myapp").exists()
+    repo.push("inbox")
+
+    # The deletion is on the remote `inbox` branch.
+    verify = tmp_path / "verify"
+    _git(tmp_path, "clone", "-b", "inbox", str(remote), str(verify))
+    assert not (verify / "myapp").exists()
+
+
+def test_remove_files_unknown_path_raises(tmp_path, remote):
+    from git_tools import GitError
+    repo = _repo(tmp_path, remote)
+    repo.clone_or_refresh()
+    with pytest.raises(GitError):
+        repo.remove_files(["does-not-exist"])  # git rm refuses an untracked path
+
+
+def test_clone_or_refresh_is_idempotent(tmp_path, remote):
+    repo = _repo(tmp_path, remote)
+    repo.clone_or_refresh()
+    assert repo.cloned and repo.status()["head"]
+    repo.clone_or_refresh()  # second call: pull-rebase, no error
+    assert repo.cloned
+
+
+def test_status_before_clone(tmp_path, remote):
+    repo = _repo(tmp_path, remote)
+    st = repo.status()
+    assert st["clone_present"] is False and st["error"]
+
+
+def test_lock_around_first_clone(tmp_path, remote):
+    """lock() must not pollute an as-yet-empty clone target: the lockfile is a
+    sibling, so clone-under-lock (the documented first-call path) works."""
+    repo = _repo(tmp_path, remote)
+    with repo.lock():
+        res = repo.commit_files({"a.md": "x"}, "first", branch="inbox", base="main")
+    assert res["committed"] is True and repo.cloned
+    # lockfile is released and lived outside the clone dir
+    assert not (repo.path / ".git-tools.lock").exists()
+    assert not (tmp_path / f".{repo.path.name}.git-tools.lock").exists()
+
+
+def test_lock_is_exclusive(tmp_path, remote):
+    repo = _repo(tmp_path, remote)
+    with repo.lock():
+        with pytest.raises(FileExistsError):
+            with repo.lock():
+                pass
+
+
+# ---------- working-tree primitives (0.2.0) --------------------------------
+
+@pytest.fixture
+def cloned(tmp_path, remote):
+    """A fresh clone of the seeded remote, ready for working-tree edits."""
+    repo = _repo(tmp_path, remote)
+    repo.clone_or_refresh()
+    return repo
+
+
+def test_move_git_mvs_and_creates_parent(cloned):
+    cloned.move("README.md", "docs/README.md")
+    assert not (cloned.path / "README.md").exists()
+    assert (cloned.path / "docs/README.md").read_text() == "seed\n"
+    # git mv stages the rename.
+    assert any(c.status == "renamed" and c.staged for c in cloned.changed_files())
+
+
+def test_changed_files_modified_unstaged(cloned):
+    (cloned.path / "README.md").write_text("changed\n")
+    changes = cloned.changed_files()
+    assert changes == [FileChange("README.md", "modified", staged=False)]
+
+
+def test_changed_files_new_and_staged_and_deleted(cloned):
+    # First land a tracked file so we can delete it later (commit it alone).
+    (cloned.path / "extra.txt").write_text("y")
+    _git(cloned.path, "add", "extra.txt")
+    _git(cloned.path, "-c", "user.name=t", "-c", "user.email=t@t", "commit", "-m", "add extra")
+
+    (cloned.path / "new.txt").write_text("x")        # untracked new file
+    (cloned.path / "README.md").write_text("v2\n")   # staged modification
+    _git(cloned.path, "add", "README.md")
+    (cloned.path / "extra.txt").unlink()             # worktree deletion, unstaged
+
+    by_path = {(c.path, c.staged): c.status for c in cloned.changed_files()}
+    assert by_path[("new.txt", False)] == "new"          # untracked -> new, unstaged
+    assert by_path[("README.md", True)] == "modified"    # staged modification
+    assert by_path[("extra.txt", False)] == "deleted"    # worktree deletion, unstaged
+
+
+def test_changed_files_scoped_to_paths(cloned):
+    (cloned.path / "in_scope.txt").write_text("a")
+    (cloned.path / "out_of_scope.txt").write_text("b")
+    paths = [c.path for c in cloned.changed_files(["in_scope.txt"])]
+    assert paths == ["in_scope.txt"]
+
+
+def test_changed_files_clean_tree_is_empty(cloned):
+    assert cloned.changed_files() == []
+
+
+def test_diff_modes(cloned):
+    (cloned.path / "README.md").write_text("worktree change\n")  # unstaged
+    (cloned.path / "staged.txt").write_text("staged content\n")
+    _git(cloned.path, "add", "staged.txt")                       # staged
+
+    worktree = cloned.diff(staged=False)
+    cached = cloned.diff(staged=True)
+    combined = cloned.diff()
+
+    assert "worktree change" in worktree and "staged content" not in worktree
+    assert "staged content" in cached and "worktree change" not in cached
+    assert "worktree change" in combined and "staged content" in combined
+    # path scoping restricts the diff
+    assert "worktree change" not in cloned.diff(["staged.txt"], staged=True)