feat(hooks): add _hooks gc-pair-sync-refs command for stale ref cleanup

Author: TTTPOB

README.md

@@ -279,6 +279,11 @@ done — log files accumulate in `/tmp` and are not rotated.
 Override the log directory with `JCLI_DEBUG_LOG_DIR=/path/to/dir` if `/tmp` is
 not writable or you want the logs elsewhere.
 
+If `refs/jcli/pair-sync/*` accumulates over time, clean stale entries with:
+
+    j-cli _hooks gc-pair-sync-refs
+    j-cli _hooks gc-pair-sync-refs --dry-run
+
 ## Py:Percent Format
 
 j-cli supports the [py:percent](https://jupytext.readthedocs.io/en/latest/formats-scripts.html#the-percent-format) format — plain Python files with cell markers:

jupyter_jcli/commands/hooks_cmd.py

@@ -962,3 +962,30 @@ def _run_pre_commit_pair_sync(include_globs: tuple[str, ...]) -> None:
             f"{', '.join(updated_ipynb)}",
             file=sys.stderr,
         )
+
+
+@hooks.command("gc-pair-sync-refs")
+@click.option("--dry-run", is_flag=True, default=False, help="Report stale refs without deleting them.")
+def gc_pair_sync_refs(dry_run: bool) -> None:
+    """Delete stale sticky pair-sync refs under refs/jcli/pair-sync."""
+    from jupyter_jcli import pair_baseline
+
+    repo_root = pair_baseline._git_root(Path.cwd())
+    if repo_root is None:
+        print("gc-pair-sync-refs: not in a git repo, skipping", file=sys.stderr)
+        sys.exit(0)
+
+    refs = pair_baseline.list_all_refs(repo_root)
+    for ref_info in refs:
+        status, reason = pair_baseline._classify_ref(repo_root, ref_info)
+        rel_display = ref_info.rel_posix_path or "<unknown>"
+        if status == "keep":
+            print(f"keep\t{rel_display}\t{reason}", file=sys.stderr)
+        elif dry_run:
+            print(f"would-remove\t{rel_display}\t{reason}", file=sys.stderr)
+        else:
+            print(f"remove\t{rel_display}\t{reason}", file=sys.stderr)
+
+    removed, kept = pair_baseline.gc_stale_refs(repo_root, dry_run)
+    print(f"removed {removed}, kept {kept}", file=sys.stderr)
+    sys.exit(0)

tests/test_hooks_pair_drift.py

@@ -12,9 +12,9 @@
 import pytest
 from click.testing import CliRunner
 
-from jupyter_jcli import pair_baseline
 from jupyter_jcli.cli import main
 from jupyter_jcli.drift import DriftResult
+from jupyter_jcli import pair_baseline
 
 
 # ---------------------------------------------------------------------------
@@ -678,6 +678,67 @@ def test_pre_merge_updates_ref_so_following_post_does_not_conflict(
         assert [cell.source for cell in nb_after.cells if cell.source.strip()] == ["x = 40"]
 
 
+class TestGcPairSyncRefsCLI:
+    def test_dry_run_reports_without_deleting(self, git_repo: Path, monkeypatch: pytest.MonkeyPatch):
+        py, _ipynb = _make_pair(git_repo, ["x = 1"], ["x = 1"])
+        _git(git_repo, "add", "nb.py")
+        _git(git_repo, "commit", "-m", "init", env=_git_env(100))
+
+        monkeypatch.setenv("GIT_AUTHOR_DATE", "@150 +0000")
+        monkeypatch.setenv("GIT_COMMITTER_DATE", "@150 +0000")
+        assert pair_baseline.write_baseline(py, py.read_text(encoding="utf-8")) is True
+        py.write_text(py.read_text(encoding="utf-8").replace("x = 1", "x = 2"), encoding="utf-8")
+        _git(git_repo, "add", "nb.py")
+        _git(git_repo, "commit", "-m", "new head", env=_git_env(200))
+
+        runner = CliRunner()
+        monkeypatch.chdir(git_repo)
+        result = runner.invoke(main, ["_hooks", "gc-pair-sync-refs", "--dry-run"], catch_exceptions=False)
+
+        assert result.exit_code == 0
+        assert "would-remove" in (result.stderr or result.output)
+        assert "removed 1, kept 0" in (result.stderr or result.output)
+        refs = _git(git_repo, "for-each-ref", "refs/jcli/pair-sync/", "--format=%(refname)")
+        assert refs.stdout.strip() != ""
+
+    def test_cli_removes_orphan_ref(self, git_repo: Path, monkeypatch: pytest.MonkeyPatch):
+        _git(git_repo, "commit", "--allow-empty", "-m", "init", env=_git_env(100))
+        ghost_path = git_repo / "ghost.py"
+        monkeypatch.setenv("GIT_AUTHOR_DATE", "@150 +0000")
+        monkeypatch.setenv("GIT_COMMITTER_DATE", "@150 +0000")
+        assert pair_baseline.write_baseline(ghost_path, "# %%\nx = 1\n") is True
+
+        runner = CliRunner()
+        monkeypatch.chdir(git_repo)
+        result = runner.invoke(main, ["_hooks", "gc-pair-sync-refs"], catch_exceptions=False)
+
+        assert result.exit_code == 0
+        assert "remove" in (result.stderr or result.output)
+        refs = _git(git_repo, "for-each-ref", "refs/jcli/pair-sync/", "--format=%(refname)")
+        assert refs.stdout.strip() == ""
+
+    def test_cli_removes_stale_head_older_ref(self, git_repo: Path, monkeypatch: pytest.MonkeyPatch):
+        py, _ipynb = _make_pair(git_repo, ["x = 1"], ["x = 1"])
+        _git(git_repo, "add", "nb.py")
+        _git(git_repo, "commit", "-m", "init", env=_git_env(100))
+
+        monkeypatch.setenv("GIT_AUTHOR_DATE", "@150 +0000")
+        monkeypatch.setenv("GIT_COMMITTER_DATE", "@150 +0000")
+        assert pair_baseline.write_baseline(py, py.read_text(encoding="utf-8")) is True
+        py.write_text(py.read_text(encoding="utf-8").replace("x = 1", "x = 5"), encoding="utf-8")
+        _git(git_repo, "add", "nb.py")
+        _git(git_repo, "commit", "-m", "head newer", env=_git_env(200))
+
+        runner = CliRunner()
+        monkeypatch.chdir(git_repo)
+        result = runner.invoke(main, ["_hooks", "gc-pair-sync-refs"], catch_exceptions=False)
+
+        assert result.exit_code == 0
+        assert "removed 1, kept 0" in (result.stderr or result.output)
+        refs = _git(git_repo, "for-each-ref", "refs/jcli/pair-sync/", "--format=%(refname)")
+        assert refs.stdout.strip() == ""
+
+
 # ---------------------------------------------------------------------------
 # --debug smoke tests for pair-drift-guard-pre and pair-drift-guard-post
 # ---------------------------------------------------------------------------