git-paoding 0.1.0__py3-none-any.whl

git_paoding/store/lock.py

@@ -0,0 +1,165 @@
+"""Fail-fast advisory locking for mutating session operations."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass
+from datetime import timedelta
+from pathlib import Path
+from types import TracebackType
+from typing import Any
+
+from git_paoding.core.model import (
+    ConcurrentSessionAccessError,
+    SessionLockError,
+    StaleSessionLockError,
+)
+from git_paoding.store.jsonstore import branch_key, paoding_dir
+
+DEFAULT_STALE_AFTER = timedelta(hours=1)
+
+
+@dataclass(frozen=True, slots=True)
+class LockOwner:
+    """Process identity persisted in a lock file."""
+
+    pid: int
+    created_at: float
+
+
+def _pid_is_alive(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+class SessionLock:
+    """Exclusive advisory lock scoped to one canonical branch."""
+
+    def __init__(
+        self,
+        repo: Path,
+        canonical_branch: str,
+        *,
+        stale_after: timedelta = DEFAULT_STALE_AFTER,
+        override_stale: bool = False,
+    ) -> None:
+        if stale_after.total_seconds() < 0:
+            raise ValueError("stale_after must not be negative")
+        self.repo = repo.resolve()
+        self.canonical_branch = canonical_branch
+        self.stale_after = stale_after
+        self.override_stale = override_stale
+        self.path = paoding_dir(self.repo) / "locks" / f"{branch_key(canonical_branch)}.lock"
+        self._acquired = False
+
+    def acquire(self) -> SessionLock:
+        """Acquire immediately or fail without waiting."""
+
+        if self._acquired:
+            raise SessionLockError(f"Session lock is already held by this object: {self.path}")
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        while True:
+            try:
+                descriptor = os.open(self.path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+            except FileExistsError:
+                owner = self._read_owner()
+                age = max(0.0, time.time() - owner.created_at)
+                alive = _pid_is_alive(owner.pid)
+                stale = not alive and age >= self.stale_after.total_seconds()
+                if not stale:
+                    raise ConcurrentSessionAccessError(
+                        f"Another mutating git-paoding process holds {self.path} "
+                        f"(pid={owner.pid}, age={age:.1f}s); concurrent writes fail fast."
+                    ) from None
+                if not self.override_stale:
+                    raise StaleSessionLockError(
+                        f"Stale git-paoding session lock detected at {self.path} "
+                        f"(pid={owner.pid} is not running, age={age:.1f}s). "
+                        "After verifying no mutating command is active, retry with "
+                        "override_stale=True to remove the stale lock."
+                    ) from None
+                self._remove_stale(owner)
+                continue
+
+            owner = LockOwner(pid=os.getpid(), created_at=time.time())
+            payload = json.dumps({"pid": owner.pid, "created_at": owner.created_at}) + "\n"
+            try:
+                with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+                    stream.write(payload)
+                    stream.flush()
+                    os.fsync(stream.fileno())
+            except BaseException:
+                self.path.unlink(missing_ok=True)
+                raise
+            self._acquired = True
+            return self
+
+    def release(self) -> None:
+        """Release a lock owned by this object."""
+
+        if not self._acquired:
+            return
+        try:
+            current = self._read_owner()
+            if current.pid != os.getpid():
+                raise SessionLockError(
+                    f"Refusing to release session lock {self.path}: ownership changed "
+                    f"from pid {os.getpid()} to pid {current.pid}"
+                )
+            self.path.unlink()
+        except FileNotFoundError as error:
+            raise SessionLockError(
+                f"Session lock disappeared before release: {self.path}"
+            ) from error
+        finally:
+            self._acquired = False
+
+    def _read_owner(self) -> LockOwner:
+        try:
+            payload: Any = json.loads(self.path.read_text(encoding="utf-8"))
+            if not isinstance(payload, dict):
+                raise TypeError("lock payload is not an object")
+            pid = payload["pid"]
+            created_at = payload["created_at"]
+            if isinstance(pid, bool) or not isinstance(pid, int):
+                raise TypeError("pid is not an integer")
+            if isinstance(created_at, bool) or not isinstance(created_at, (int, float)):
+                raise TypeError("created_at is not a number")
+            return LockOwner(pid=pid, created_at=float(created_at))
+        except (OSError, ValueError, TypeError, KeyError) as error:
+            raise StaleSessionLockError(
+                f"Cannot validate existing session lock {self.path}: {error}. "
+                "After verifying no mutating command is active, remove the lock manually "
+                "or retry with override_stale=True."
+            ) from error
+
+    def _remove_stale(self, expected: LockOwner) -> None:
+        current = self._read_owner()
+        if current != expected:
+            raise ConcurrentSessionAccessError(
+                f"Session lock {self.path} changed while checking staleness; retry the operation."
+            )
+        try:
+            self.path.unlink()
+        except FileNotFoundError:
+            return
+
+    def __enter__(self) -> SessionLock:
+        return self.acquire()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.release()

git_paoding-0.1.0.dist-info/METADATA

@@ -0,0 +1,351 @@
+Metadata-Version: 2.3
+Name: git-paoding
+Version: 0.1.0
+Summary: Semantic review slicing for large agent-generated changes
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic>=2
+Requires-Dist: hypothesis>=6 ; extra == 'dev'
+Requires-Dist: mypy>=1.15 ; extra == 'dev'
+Requires-Dist: pre-commit>=4 ; extra == 'dev'
+Requires-Dist: pytest>=8 ; extra == 'dev'
+Requires-Dist: pytest-cov>=6 ; extra == 'dev'
+Requires-Dist: ruff>=0.11 ; extra == 'dev'
+Requires-Python: >=3.11
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# git-paoding
+
+<!-- cspell:words paoding pipx PAODING -->
+
+Agent writes globally. Humans review locally.
+
+`git-paoding` lets a coding agent keep one coherent implementation on one
+canonical integration branch while presenting the final change as several small,
+semantic Draft GitHub pull requests. Those slice PRs are review projections:
+they help people understand one concern at a time, but they are not development
+branches or merge targets.
+
+The canonical integration PR remains authoritative. It contains the complete
+change, runs CI, receives final approval, and merges. Review feedback goes back
+into the canonical branch; a later `git-paoding publish` refreshes the
+projections without creating a branch stack to restack.
+
+The name comes from 庖丁解牛 (_Chef Ding carves the ox_): cutting along the
+natural joints.
+
+
+## Install the CLI and agent workflow
+
+`git-paoding` is designed for coding agents rather than as a human-operated UI.
+A complete installation has two parts:
+
+1. The Python package provides the deterministic `git-paoding` executable.
+2. The agent skill or plugin teaches Codex or Claude Code when and how to use it.
+
+Installing only the Python package does not make an agent discover the workflow.
+Install the CLI and one agent integration together.
+
+### Give this page to an agent
+
+You can send an agent this repository URL and the following request:
+
+```text
+Install git-paoding by following the repository README. Install the Python CLI
+and the integration for the agent you are running as, verify both, and then
+explain the workflow. Do not initialize a session, push, publish, or change any
+repository until I give you a specific review-slicing task.
+```
+
+### 1. Install the CLI
+
+`git-paoding` requires Python 3.11 or newer, Git, and
+[GitHub CLI](https://cli.github.com/) 2.45.0 or newer. GitHub operations reuse
+the account and credentials configured by `gh`; authenticate before initializing
+a session:
+
+```bash
+gh auth login
+gh auth status
+```
+
+Install the released package with one of these methods. `uv tool` or `pipx` is
+recommended because it keeps the agent-facing command isolated:
+
+```bash
+uv tool install git-paoding
+pipx install git-paoding
+python -m pip install git-paoding
+```
+
+Choose one installation method, not all three. Confirm the explicit command and
+Git's external-subcommand form resolve to the same release:
+
+```bash
+git-paoding --version
+git paoding --version
+```
+
+If the first PyPI release is not available yet, install the current GitHub
+version directly:
+
+```bash
+uv tool install "git+https://github.com/NagisaVon/git-paoding.git"
+```
+
+To install from a source checkout instead:
+
+```bash
+git clone https://github.com/NagisaVon/git-paoding.git
+cd git-paoding
+uv sync --extra dev --locked
+uv run git-paoding --help
+```
+
+### 2. Install the agent integration
+
+Choose one of the following installation methods for each agent. The bundled
+standalone skill and the marketplace plugin provide the same instructions, so
+installing both for the same agent is unnecessary.
+
+#### Option A: install the bundled standalone skill
+
+The Python distribution carries the same `SKILL.md` used by both plugins. The
+following commands copy that bundled skill into the official personal skill
+directory and work without a plugin UI:
+
+For Codex:
+
+```bash
+git-paoding agent install --target codex --scope user
+```
+
+For Claude Code:
+
+```bash
+git-paoding agent install --target claude --scope user
+```
+
+To install both, repeat `--target` in one command:
+
+```bash
+git-paoding agent install --target codex --target claude --scope user
+```
+
+Use `--scope project` to install into the current repository instead of the
+current user's global skill directory. Re-run with `--force` after upgrading if
+the installed skill was modified locally. Codex installs to
+`.agents/skills/git-paoding`; Claude Code installs to
+`.claude/skills/git-paoding` (under the home directory for user scope).
+
+Verify the skill appears in Codex with `/skills`. In Claude Code, run `/skills`
+or invoke `/git-paoding` directly. Restart the agent only if a newly created
+top-level skill directory is not detected in the current session.
+
+#### Option B: install through the plugin marketplace
+
+This repository is also a marketplace for a skill-only `git-paoding` plugin.
+The Codex and Claude Code manifests share one packaged skill, so their behavior
+does not drift.
+
+For Codex, add the GitHub marketplace:
+
+```bash
+codex plugin marketplace add NagisaVon/git-paoding
+codex plugin add git-paoding@git-paoding
+```
+
+The same plugin then appears in the Plugins Directory in the ChatGPT desktop
+app. Invoke its skill as `$git-paoding`.
+
+For Claude Code, the complete installation is available from the CLI:
+
+```bash
+claude plugin marketplace add NagisaVon/git-paoding
+claude plugin install git-paoding@git-paoding --scope user
+```
+
+Run `/reload-plugins` if Claude Code asks for it, then invoke the plugin skill as
+`/git-paoding:git-paoding`.
+
+### 3. Ask the agent to prepare review slices
+
+For Codex:
+
+```text
+$git-paoding Prepare semantic review slices for the complete committed change
+on my current branch, using origin/main as the base. Inspect and propose the
+slice assignments first. Do not push or publish until I approve the plan.
+```
+
+For the Claude Code plugin:
+
+```text
+/git-paoding:git-paoding Prepare semantic review slices for the complete
+committed change on my current branch, using origin/main as the base. Inspect
+and propose the slice assignments first. Do not push or publish until I approve
+the plan.
+```
+
+## Run a review-slicing session
+
+After installation, Codex and Claude Code follow the same operational workflow
+below. Their invocation syntax differs (`$git-paoding` in Codex and
+`/git-paoding:git-paoding` for the Claude Code plugin), but both use the same
+`git-paoding` CLI and repository state.
+
+Start from the branch that contains the complete, committed implementation. The
+base is pinned when the session is initialized; moving `origin/main` later does
+not silently move that pin.
+
+```bash
+git-paoding init --base origin/main --slice-prefix ABC-123
+git-paoding slice add storage --title "Storage boundary"
+git-paoding slice add tests --title "Storage behavior tests"
+git-paoding status --json
+```
+
+`status` is local and read-only. Exit code `2` is expected while it reports
+unassigned or ambiguous atoms. Its JSON includes each atom's ID, path, Base and
+Final ranges, owner, state, and short preview. Use `git-paoding status --full`
+when complete changed-hunk previews are useful.
+
+`--slice-prefix` is optional and defaults to `slice`. It changes only generated
+slice PR titles, such as `[ABC-123] Storage boundary`; slice IDs and generated
+refs remain stable. The integration PR title is the canonical branch name.
+
+Assign interactively by an atom ID, path, directory, glob, or Final-coordinate
+line range. Broad selectors preserve already-owned atoms unless `--force` is
+passed; explicit atom IDs may reassign their exact atom without it. Every
+selected atom is echoed as assigned or skipped:
+
+```bash
+git-paoding assign storage src/storage.py
+git-paoding assign tests tests/test_storage.py
+git-paoding status --json
+```
+
+When no action is needed, publish the review projections:
+
+```bash
+git-paoding publish
+```
+
+`publish` is idempotent. It reconciles first and stops with exit code `2` and no
+remote effects if attribution still needs attention. A clean publish pushes
+generated projection refs, creates or refreshes stable Draft slice PRs, and
+creates or updates the Draft integration PR and its slice index. Operational
+failures use exit code `1`; success uses `0`.
+
+Keep the canonical branch available on the selected Git remote before
+publishing. If it has not been pushed, obtain the change owner's approval before
+doing so:
+
+```bash
+git push -u origin HEAD
+```
+
+### Three-step agent flow
+
+The intended agent loop is:
+
+```bash
+git-paoding status --json
+git-paoding assign --batch paoding-assignments.json
+git-paoding publish
+```
+
+The batch request uses the frozen versioned contract:
+
+```json
+{
+  "contract_version": 0,
+  "assignments": {
+    "storage": ["src/storage.py"],
+    "tests": ["tests/test_storage.py"]
+  },
+  "force": false
+}
+```
+
+Batch assignment is all-or-nothing: an unknown slice, invalid selector, or
+cross-slice conflict rejects the entire request. Set the JSON `force` field to
+`true` when a batch is intentionally repartitioning already-owned atoms; do not
+combine the interactive `--force` option with `--batch`. The batch plan is an
+ordinary local input file rather than session metadata; keep it untracked or
+manage it according to the repository's own policy.
+
+For targeted review feedback, focus may provide a default owner for genuinely
+new atoms without overwriting confidently matched ownership:
+
+```bash
+git-paoding focus storage
+git-paoding status --json
+git-paoding focus --clear
+```
+
+## What reviewers should know
+
+A slice PR is a view onto one semantic part of the final integrated change.
+Different slices may touch different regions of the same file, and one slice may
+rely on code shown by another. A slice is not required to build or test by
+itself.
+
+Every slice PR is Draft and carries a
+**DO NOT MERGE — review projection only** warning because:
+
+- Its generated base and head refs are disposable projections.
+- It is not the branch where implementation work happens.
+- Its review is for comprehension, not authoritative approval.
+- Only the integration PR represents the complete change and real merge target.
+
+Use normal GitHub review features on a slice PR: read its narrative, inspect
+Files changed, and leave inline comments. After feedback, update the canonical
+branch and refresh the same slice PR. GitHub may mark comments
+outdated when their lines change; the discussion history and stable PR identity
+remain useful.
+
+## Suppress CI for slice PRs
+
+Slice projections are review units, not integration units. In consumer
+repositories, filter the `pull_request` workflow to real target branches so
+generated `paoding/.../base` refs do not start authoritative CI. For a
+repository that merges into `main`:
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+```
+
+GitHub evaluates the `pull_request.branches` filter against the PR's base
+branch. Keep the normal CI and branch-protection requirements on the integration
+PR.
+
+## Safety and recovery
+
+- Work only on the canonical integration branch. Never check out or edit
+  generated `paoding/...` branches.
+- Never merge a slice PR. Close/archive it after the integration PR merges.
+- Do not expect a slice projection to build, test, or pass CI independently.
+- Unassigned or ambiguous atoms are normal recovery states, not metadata
+  corruption. Rerun `status`, classify what remains, and publish again.
+- Slice metadata lives in the repository's common Git directory and is not
+  committed. Do not delete it as a routine reset.
+- If session metadata is lost, recreate the session and the same stable slice
+  IDs. Attribution returns as unassigned, while existing open slice PRs can be
+  adopted by their machine markers on the next clean publish.
+- New PR bodies contain only their machine-managed region; the tool does not
+  seed a narrative template. Human narrative added outside those delimiters is
+  preserved byte-for-byte on refresh.
+
+After GitHub reports the integration PR as merged, archive the generated review
+surface without merging any slice PR:
+
+```bash
+git-paoding archive
+```

git_paoding-0.1.0.dist-info/RECORD

@@ -0,0 +1,36 @@
+git_paoding/__init__.py,sha256=E7c45xo-EyUXLNUguozhSN0jiaCfCwmBAHYcwa4YyP8,514
+git_paoding/_agent_plugins/__init__.py,sha256=aY6bQaHPc46VFLH6zM8dPxhVwBlc4xntdWnoPdqmGAQ,51
+git_paoding/_agent_plugins/git-paoding/.claude-plugin/plugin.json,sha256=wXOOX81TO2LwVp9U49bKhENSETEOzjigMY7V_cfXHa8,409
+git_paoding/_agent_plugins/git-paoding/.codex-plugin/plugin.json,sha256=8qZcbSXqZomCpl6tiTmmN350WVv0jxomwYDLmgMnXHg,1032
+git_paoding/_agent_plugins/git-paoding/skills/git-paoding/SKILL.md,sha256=HXeCHfmUo3J7YmYDrZvJI6aQrdNc6fsKGxrEqGR_Lx0,7639
+git_paoding/agent_install.py,sha256=ZO6XHkzeQOzlSWMXj5qa5qUqA4lXxVU1TfdE3FsA4fs,3734
+git_paoding/api.py,sha256=ocjyM0IgJQXyWnfTqzK8YangzOyufVYJN5K_JhTKiV0,12614
+git_paoding/cli/__init__.py,sha256=0ouz55BJFQtDyuOsMAIaI-RI0vCWqZfos6OF1lDc_js,38
+git_paoding/cli/facade.py,sha256=AochEYhKAav3iiBil4fyKg0weclaxQSJf8voQkh3Azk,3578
+git_paoding/cli/main.py,sha256=wCQwyBMUH2EjaYuFkCm-gEO1wFSB8_YhWjkYxwNYbyA,9388
+git_paoding/cli/render.py,sha256=pnNzt1WItuX5CnCTxD2ssEwGBfgD4zufmwt1umxuw-4,6967
+git_paoding/core/__init__.py,sha256=vB0bvZGYzUdHNhwbziqopojz1tbNWB4h5BMNFEeYIfA,27
+git_paoding/core/diffatoms.py,sha256=MzlvrVN5dBvGHqdRescik4ToxS7WRTbYGTEO5Y4FvsU,7193
+git_paoding/core/model.py,sha256=0Vp2trstldmGcvoGqqMNuUyEMIlG5XouPsMM5rLuP70,8688
+git_paoding/core/projection.py,sha256=Ep3pv7tQYfuqGWNlEk1qhO7-iPPxDbyPmx-qjrs1ftI,12841
+git_paoding/core/publish.py,sha256=-47PWMvWF0Y5_3pPBIaEecS0jTh3JcW76TOhoIHv7tY,24277
+git_paoding/core/reconcile.py,sha256=SisqK5eSoe39pJpGRlpnWDz_34gaNsifzecBCyMYyx0,8397
+git_paoding/core/selectors.py,sha256=DELr18hNBzhqVMli9V1aGFkBQCyiutLwiX8ybCNRkXU,10239
+git_paoding/github/__init__.py,sha256=t0Y980WY5OXoAJoB12cdR9pSf-wxMhY1fS8TwXrIaYw,34
+git_paoding/github/backend.py,sha256=snDHc5pQ2l29A2d2QbmKPvUu-Ugpms0IeVUgSbofIDo,1700
+git_paoding/github/gh_cli.py,sha256=tBVmQp_SSBoKVyvM6eI7x7JxaifOII9wdVW8BM5Gt4c,11425
+git_paoding/github/lifecycle.py,sha256=HAnx4bg1QB6Uv5LvFrmyjPhMX3pKrttvLfDtWM4zoSU,3414
+git_paoding/github/prbody.py,sha256=nFSRzNmU1ZsVAt6BDf9_PhiAM1DMa6LkvlW99H5edGE,8765
+git_paoding/gitio/__init__.py,sha256=joLcPXhFt8OIX6hPB5k3hHPGN4KxLEHl3ZuXhjWTbXc,897
+git_paoding/gitio/diffparse.py,sha256=avAcZZKgooK9uHdWdGpxKKapPJoy2QIGHJ1vGxTbBcI,9078
+git_paoding/gitio/plumbing.py,sha256=SOADfV5pq-1hdum9OUxaeiRo794peZIS2k9FjzZgTMk,5520
+git_paoding/gitio/refs.py,sha256=GFApgr44r07hD7zph0N04ryVs8uR1YbVNp4yxcUBFew,4428
+git_paoding/gitio/runner.py,sha256=7zp2JXNNvT1vjXrddke6DJu7tJ3s5VuEfpr3IuKS5EY,3785
+git_paoding/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+git_paoding/store/__init__.py,sha256=ZqA3MFvJiR5MAwQqhQ8NRBiITIs_26wCoqb0z4tdOjc,249
+git_paoding/store/jsonstore.py,sha256=xS_DQTM_BlJ4mRt9QwnStMCQp9UX4owdTtQV5dsadZ0,5277
+git_paoding/store/lock.py,sha256=CuxnfZegsFr-zX5r8I_g2h53Pd4-x1KziLYEFLOnSj8,5981
+git_paoding-0.1.0.dist-info/WHEEL,sha256=ZFFp7t7R4RYQ5KYZkmiFWoQvHay7SrTmn-6ZYfoFZ3U,80
+git_paoding-0.1.0.dist-info/entry_points.txt,sha256=BY2d7F5n-uEQseTerylxaZMcUb9TeUObHB5rrJ_kvE0,59
+git_paoding-0.1.0.dist-info/METADATA,sha256=UyswhHRBlMjCWufSE9vFdVUCHwwIujy8iBpcXKEJre8,11990
+git_paoding-0.1.0.dist-info/RECORD,,

git_paoding-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.7
+Root-Is-Purelib: true
+Tag: py3-none-any

git_paoding-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+git-paoding = git_paoding.cli.main:main
+