docketeer-git 0.0.6__tar.gz

docketeer_git-0.0.6/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+.envrc.private
+.claude/settings.local.json
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+workspace/
+.coverage
+.loq_cache

docketeer_git-0.0.6/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: docketeer-git
+Version: 0.0.6
+Summary: Git-backed workspace backup plugin for Docketeer
+Project-URL: Homepage, https://github.com/chrisguidry/docketeer
+Project-URL: Repository, https://github.com/chrisguidry/docketeer
+Project-URL: Issues, https://github.com/chrisguidry/docketeer/issues
+Author-email: Chris Guidry <guid@omg.lol>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Archiving :: Backup
+Requires-Python: >=3.12
+Requires-Dist: docketeer
+Requires-Dist: pydocket
+Description-Content-Type: text/markdown
+
+# docketeer-git
+
+Git-backed workspace backup plugin for
+[Docketeer](https://pypi.org/project/docketeer/). Automatically commits the
+agent's workspace (`~/.docketeer/memory/`) to a local git repo on a timer, and
+optionally pushes to a remote for off-machine backup.
+
+Install `docketeer-git` alongside `docketeer` and backups start automatically.
+No agent-facing tools are added — the agent doesn't know about backups.
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `DOCKETEER_GIT_BACKUP_INTERVAL` | `PT5M` | How often to check for changes (ISO 8601 duration or seconds) |
+| `DOCKETEER_GIT_REMOTE` | _(empty)_ | Remote URL to push to. No push if unset. |
+| `DOCKETEER_GIT_BRANCH` | `main` | Branch name to use |
+| `DOCKETEER_GIT_AUTHOR_NAME` | `Docketeer` | Git author name for backup commits |
+| `DOCKETEER_GIT_AUTHOR_EMAIL` | `docketeer@localhost` | Git author email for backup commits |
+
+## How it works
+
+A periodic docket task checks the workspace for uncommitted changes every 5
+minutes (configurable). If anything changed, it stages everything and commits
+with a timestamped message. If `DOCKETEER_GIT_REMOTE` is set, it pushes after
+each commit. Push failures are logged but don't crash the agent.
+
+The git repo is initialized automatically on first run. You can browse the
+history with standard git tools (`git log`, `git diff`, etc.) in the workspace
+directory.

docketeer_git-0.0.6/README.md

@@ -0,0 +1,30 @@
+# docketeer-git
+
+Git-backed workspace backup plugin for
+[Docketeer](https://pypi.org/project/docketeer/). Automatically commits the
+agent's workspace (`~/.docketeer/memory/`) to a local git repo on a timer, and
+optionally pushes to a remote for off-machine backup.
+
+Install `docketeer-git` alongside `docketeer` and backups start automatically.
+No agent-facing tools are added — the agent doesn't know about backups.
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `DOCKETEER_GIT_BACKUP_INTERVAL` | `PT5M` | How often to check for changes (ISO 8601 duration or seconds) |
+| `DOCKETEER_GIT_REMOTE` | _(empty)_ | Remote URL to push to. No push if unset. |
+| `DOCKETEER_GIT_BRANCH` | `main` | Branch name to use |
+| `DOCKETEER_GIT_AUTHOR_NAME` | `Docketeer` | Git author name for backup commits |
+| `DOCKETEER_GIT_AUTHOR_EMAIL` | `docketeer@localhost` | Git author email for backup commits |
+
+## How it works
+
+A periodic docket task checks the workspace for uncommitted changes every 5
+minutes (configurable). If anything changed, it stages everything and commits
+with a timestamped message. If `DOCKETEER_GIT_REMOTE` is set, it pushes after
+each commit. Push failures are logged but don't crash the agent.
+
+The git repo is initialized automatically on first run. You can browse the
+history with standard git tools (`git log`, `git diff`, etc.) in the workspace
+directory.

docketeer_git-0.0.6/pyproject.toml

@@ -0,0 +1,61 @@
+[project]
+name = "docketeer-git"
+dynamic = ["version"]
+description = "Git-backed workspace backup plugin for Docketeer"
+readme = "README.md"
+authors = [
+    { name = "Chris Guidry", email = "guid@omg.lol" }
+]
+license = "MIT"
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: System :: Archiving :: Backup",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "docketeer",
+    "pydocket",
+]
+
+[project.urls]
+Homepage = "https://github.com/chrisguidry/docketeer"
+Repository = "https://github.com/chrisguidry/docketeer"
+Issues = "https://github.com/chrisguidry/docketeer/issues"
+
+[project.entry-points."docketeer.tasks"]
+git = "docketeer_git:task_collections"
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+raw-options.root = ".."
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docketeer_git"]
+
+[tool.uv.sources]
+docketeer = { workspace = true }
+
+[tool.pytest_env]
+DOCKETEER_ANTHROPIC_API_KEY = "test-key"
+DOCKETEER_DATA_DIR = "{tmp_path}"
+
+[tool.pytest.ini_options]
+minversion = "9.0"
+addopts = [
+    "--import-mode=importlib",
+    "--cov=docketeer_git",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+asyncio_mode = "auto"
+filterwarnings = [
+    "error",
+]

docketeer_git-0.0.6/src/docketeer_git/__init__.py

@@ -0,0 +1,7 @@
+from docketeer_git.backup import backup
+
+git_tasks = [backup]
+
+task_collections = ["docketeer_git:git_tasks"]
+
+__all__ = ["git_tasks", "task_collections"]

docketeer_git-0.0.6/src/docketeer_git/backup.py

@@ -0,0 +1,121 @@
+"""Git-backed workspace backup — periodic commit and optional push."""
+
+import asyncio
+import logging
+import os
+from datetime import datetime, timedelta
+from pathlib import Path
+
+from docket.dependencies import Perpetual
+
+from docketeer import environment
+from docketeer.dependencies import EnvironmentStr, WorkspacePath
+
+log = logging.getLogger(__name__)
+
+BACKUP_INTERVAL = environment.get_timedelta("GIT_BACKUP_INTERVAL", timedelta(minutes=5))
+
+DEFAULT_GITIGNORE = """\
+*.lock
+*.tmp
+*.swp
+*~
+__pycache__/
+tmp/
+"""
+
+
+async def _git(
+    cwd: Path,
+    *args: str,
+    env: dict[str, str] | None = None,
+) -> asyncio.subprocess.Process:
+    """Run a git command and return the completed process."""
+    proc = await asyncio.create_subprocess_exec(
+        "git",
+        *args,
+        cwd=cwd,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        env={**os.environ, **env} if env else None,
+    )
+    await proc.wait()
+    return proc
+
+
+async def _git_config(cwd: Path, key: str, value: str) -> None:
+    await _git(cwd, "config", key, value)
+
+
+async def _init_repo(
+    workspace: Path,
+    *,
+    branch: str,
+    remote: str,
+    author_name: str,
+    author_email: str,
+) -> None:
+    """Initialize a git repo in the workspace if one doesn't exist."""
+    await _git(workspace, "init", "-b", branch)
+    await _git_config(workspace, "user.name", author_name)
+    await _git_config(workspace, "user.email", author_email)
+
+    if remote:
+        await _git(workspace, "remote", "add", "origin", remote)
+
+    gitignore = workspace / ".gitignore"
+    if not gitignore.exists():
+        gitignore.write_text(DEFAULT_GITIGNORE)
+
+
+async def _has_changes(workspace: Path) -> bool:
+    """Check if the workspace has any uncommitted changes or untracked files."""
+    status = await _git(workspace, "status", "--porcelain")
+    assert status.stdout is not None
+    output = await status.stdout.read()
+    return bool(output.strip())
+
+
+async def backup(
+    perpetual: Perpetual = Perpetual(every=BACKUP_INTERVAL, automatic=True),
+    workspace: Path = WorkspacePath(),
+    remote: str = EnvironmentStr("GIT_REMOTE", ""),
+    branch: str = EnvironmentStr("GIT_BRANCH", "main"),
+    author_name: str = EnvironmentStr("GIT_AUTHOR_NAME", "Docketeer"),
+    author_email: str = EnvironmentStr("GIT_AUTHOR_EMAIL", "docketeer@localhost"),
+) -> None:
+    """Commit workspace changes and optionally push to a remote."""
+    if not any(workspace.iterdir()):
+        return
+
+    if not (workspace / ".git").is_dir():
+        await _init_repo(
+            workspace,
+            branch=branch,
+            remote=remote,
+            author_name=author_name,
+            author_email=author_email,
+        )
+
+    if not await _has_changes(workspace):
+        return
+
+    await _git(workspace, "add", ".")
+
+    author_env = {
+        "GIT_AUTHOR_NAME": author_name,
+        "GIT_AUTHOR_EMAIL": author_email,
+        "GIT_COMMITTER_NAME": author_name,
+        "GIT_COMMITTER_EMAIL": author_email,
+    }
+
+    timestamp = datetime.now().astimezone().strftime("%Y-%m-%d %H:%M:%S %z")
+    await _git(workspace, "commit", "-m", f"backup: {timestamp}", env=author_env)
+    log.info("Workspace backup committed: %s", timestamp)
+
+    if remote:
+        result = await _git(workspace, "push", "-u", "origin", branch)
+        if result.returncode != 0:
+            assert result.stderr is not None
+            stderr = (await result.stderr.read()).decode()
+            log.warning("Push failed: %s", stderr)

docketeer_git-0.0.6/tests/test_backup.py

@@ -0,0 +1,203 @@
+"""Tests for the git-backed workspace backup task."""
+
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from docketeer_git.backup import _git, _git_config, backup
+
+
+@pytest.fixture()
+def workspace(tmp_path: Path) -> Path:
+    ws = tmp_path / "memory"
+    ws.mkdir()
+    return ws
+
+
+def git_log(workspace: Path) -> list[str]:
+    result = subprocess.run(
+        ["git", "log", "--oneline", "--format=%s"],
+        cwd=workspace,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout.strip().splitlines()
+
+
+def git_branch(workspace: Path) -> str:
+    result = subprocess.run(
+        ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+        cwd=workspace,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return result.stdout.strip()
+
+
+async def _backup(
+    workspace: Path,
+    *,
+    remote: str = "",
+    branch: str = "main",
+    author_name: str = "Test",
+    author_email: str = "test@test",
+) -> None:
+    """Call backup() with all dependency parameters resolved for tests."""
+    await backup(
+        workspace=workspace,
+        remote=remote,
+        branch=branch,
+        author_name=author_name,
+        author_email=author_email,
+    )
+
+
+async def test_initializes_repo(workspace: Path):
+    (workspace / "test.txt").write_text("hello")
+    await _backup(workspace)
+    assert (workspace / ".git").is_dir()
+
+
+async def test_uses_configured_branch(workspace: Path):
+    (workspace / "test.txt").write_text("hello")
+    await _backup(workspace, branch="backups")
+    assert git_branch(workspace) == "backups"
+
+
+async def test_commits_changes(workspace: Path):
+    (workspace / "note.md").write_text("first")
+    await _backup(workspace)
+    commits = git_log(workspace)
+    assert len(commits) == 1
+    assert commits[0].startswith("backup: ")
+
+
+async def test_clean_workspace_no_commit(workspace: Path):
+    (workspace / "note.md").write_text("first")
+    await _backup(workspace)
+    await _backup(workspace)
+    commits = git_log(workspace)
+    assert len(commits) == 1
+
+
+async def test_multiple_changes(workspace: Path):
+    (workspace / "a.txt").write_text("one")
+    await _backup(workspace)
+    (workspace / "b.txt").write_text("two")
+    await _backup(workspace)
+    commits = git_log(workspace)
+    assert len(commits) == 2
+
+
+async def test_pushes_when_remote_configured(workspace: Path):
+    remote = workspace.parent / "remote.git"
+    subprocess.run(
+        ["git", "init", "--bare", "-b", "main", str(remote)],
+        check=True,
+        capture_output=True,
+    )
+
+    (workspace / "note.md").write_text("push me")
+    await _backup(workspace, remote=str(remote))
+
+    result = subprocess.run(
+        ["git", "log", "--oneline", "--format=%s"],
+        cwd=remote,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert "backup: " in result.stdout
+
+
+async def test_no_push_without_remote(workspace: Path):
+    (workspace / "note.md").write_text("no push")
+    await _backup(workspace)
+    assert (workspace / ".git").is_dir()
+    result = subprocess.run(
+        ["git", "remote"],
+        cwd=workspace,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert result.stdout.strip() == ""
+
+
+async def test_push_failure_logged_not_raised(
+    workspace: Path, caplog: pytest.LogCaptureFixture
+):
+    (workspace / "note.md").write_text("will fail push")
+    await _backup(workspace, remote="https://invalid.example.com/nope.git")
+
+    assert any("push failed" in r.message.lower() for r in caplog.records)
+
+
+async def test_gitignore_created(workspace: Path):
+    (workspace / "note.md").write_text("hello")
+    await _backup(workspace)
+    gitignore = workspace / ".gitignore"
+    assert gitignore.exists()
+    content = gitignore.read_text()
+    assert "*.lock" in content
+    assert "*.tmp" in content
+
+
+async def test_gitignore_not_overwritten(workspace: Path):
+    gitignore = workspace / ".gitignore"
+    gitignore.write_text("custom\n")
+    (workspace / "note.md").write_text("hello")
+    await _backup(workspace)
+    assert gitignore.read_text() == "custom\n"
+
+
+async def test_sets_author_config(workspace: Path):
+    (workspace / "note.md").write_text("hello")
+    await _backup(workspace, author_name="Nix", author_email="nix@example.com")
+
+    result = subprocess.run(
+        ["git", "log", "--format=%an <%ae>", "-1"],
+        cwd=workspace,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert result.stdout.strip() == "Nix <nix@example.com>"
+
+
+async def test_git_helper(tmp_path: Path):
+    result = await _git(tmp_path, "init")
+    assert result.returncode == 0
+
+
+async def test_git_config_helper(tmp_path: Path):
+    await _git(tmp_path, "init")
+    await _git_config(tmp_path, "user.name", "test")
+    result = subprocess.run(
+        ["git", "config", "user.name"],
+        cwd=tmp_path,
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert result.stdout.strip() == "test"
+
+
+def test_git_tasks_exported():
+    from docketeer_git import git_tasks
+
+    assert backup in git_tasks
+
+
+def test_task_collections_exported():
+    from docketeer_git import task_collections
+
+    assert "docketeer_git:git_tasks" in task_collections
+
+
+async def test_empty_workspace_no_commit(workspace: Path):
+    await _backup(workspace)
+    assert not (workspace / ".git").is_dir()