gitgrip 1.5.0__tar.gz

gitgrip-1.5.0/MANIFEST.in

@@ -0,0 +1,6 @@
+# VERSION is generated at build time from ../Cargo.toml; carry it into the sdist
+# so a wheel built FROM the sdist (where Cargo.toml is absent) can read it.
+include VERSION
+# The in-tree build backend must travel in the sdist, or `build_wheel` from an
+# unpacked sdist cannot find backend-path=["_build"].
+graft _build

gitgrip-1.5.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: gitgrip
+Version: 1.5.0
+Summary: gr2 overlay substrate: config-overlay capture, composition, and materialization
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.9
+Requires-Dist: tomli_w>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: toml>=0.10
+Requires-Dist: jsonschema>=4.18
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"

gitgrip-1.5.0/README.md

@@ -0,0 +1,258 @@
+# gr2 overlay substrate
+
+Config-overlay capture, composition, and materialization for gitgrip
+workspaces. Overlays are git-native objects that layer configuration
+files on top of a workspace without modifying the base branch.
+
+## What is an overlay?
+
+An overlay is a set of Tier A config files (`.toml`, `.yml`, `.json`,
+`COMPOSE.md`) captured as an annotated git tag pointing at a structured
+tree. Overlays live in `refs/overlays/<author>/<name>` and can be pushed,
+fetched, and activated across machines using standard git transport.
+
+When activated, an overlay eagerly materializes its files into the
+workspace. When deactivated, those files are removed and the workspace
+returns to its pre-overlay state.
+
+## Quick start
+
+Create your first overlay in under 3 minutes.
+
+### 1. Set up stores
+
+```python
+from pathlib import Path
+from gr2.overlay.objects import capture_overlay_object
+from gr2.overlay.activate import activate_overlay, deactivate_overlay
+from gr2.overlay.types import OverlayMeta, OverlayRef, OverlayTier, TrustLevel
+
+# Initialize a bare git repo as the overlay store
+import subprocess
+store = Path("overlay-store.git")
+subprocess.run(["git", "init", "--bare", str(store)], check=True)
+```
+
+### 2. Capture an overlay
+
+```python
+# Create source config files
+source = Path("my-overlay-source")
+source.mkdir(exist_ok=True)
+(source / "settings.toml").write_text('[ui]\ntheme = "dark"\n')
+(source / "COMPOSE.md").write_text("# My Overlay\n")
+
+# Capture into the store
+ref = OverlayRef(author="myteam", name="dark-theme")
+meta = OverlayMeta(
+    ref=ref,
+    tier=OverlayTier.A,
+    trust=TrustLevel.TRUSTED,
+    author="myteam",
+    timestamp="2026-05-01T00:00:00Z",
+)
+capture_overlay_object(store, source, meta)
+```
+
+### 3. Activate in a workspace
+
+```python
+workspace = Path("my-workspace")
+workspace.mkdir(exist_ok=True)
+
+result = activate_overlay(
+    workspace_root=workspace,
+    overlay_store=store,
+    overlay_ref=ref,
+    overlay_source_kind="path",
+    overlay_source_value="myteam/dark-theme",
+    overlay_signer=None,
+)
+
+assert (workspace / "settings.toml").read_text() == '[ui]\ntheme = "dark"\n'
+```
+
+### 4. Deactivate
+
+```python
+deactivate_overlay(workspace_root=workspace, overlay_ref=ref)
+assert not (workspace / "settings.toml").exists()
+```
+
+## Multi-machine distribution
+
+Overlays use identity-mapped refspecs for transport between stores:
+
+```python
+from gr2.overlay.refs import push_overlay_ref, fetch_overlay_ref
+
+# Machine A: push to a shared remote
+push_overlay_ref(local_store, remote_store, overlay_ref)
+
+# Machine B: fetch and activate
+fetch_overlay_ref(peer_store, remote_store, overlay_ref)
+activate_overlay(
+    workspace_root=peer_workspace,
+    overlay_store=peer_store,
+    overlay_ref=overlay_ref,
+    overlay_source_kind="path",
+    overlay_source_value="myteam/dark-theme",
+    overlay_signer=None,
+)
+```
+
+## Curated merge drivers
+
+Three drivers handle file composition when overlays interact with
+existing workspace content:
+
+| Driver | Behavior | File types |
+|--------|----------|------------|
+| `overlay-deep` | Recursive dict merge; overlay wins conflicts | `.toml`, `.yml`, `.json` |
+| `overlay-prepend` | Concatenates overlay content before base | Any text file |
+| `overlay-union` | Deduplicated line set union | Line-oriented files |
+
+Drivers are declared in `.gitattributes`:
+
+```
+*.toml merge=overlay-deep
+*.yml merge=overlay-deep
+*.json merge=overlay-deep
+COMPOSE.md merge=overlay-prepend
+```
+
+## Trust model
+
+Activation is gated by a workspace-local allowlist at
+`.grip/trust.toml`. If no trust config exists, the workspace operates
+in **open mode** (all overlays are accepted).
+
+```toml
+[[sources]]
+kind = "path"
+pattern = "myteam/*"
+trust_class = "local"
+
+[[sources]]
+kind = "path"
+pattern = "vendor/*"
+trust_class = "team"
+
+[[sources]]
+kind = "signed"
+signer = "release-bot@myorg.com"
+trust_class = "team"
+```
+
+Trust classes:
+- **local**: overlays from your own team or workspace
+- **team**: overlays from verified external sources
+
+Untrusted overlays are blocked before any files are written.
+Path traversal patterns (containing `..`) are always rejected.
+
+`.gitattributes` is treated as metadata, not authority: it declares
+which driver to use but does not bypass the trust allowlist.
+
+## Introspection
+
+Five query functions provide visibility into overlay state. Each
+supports both human-readable and machine-readable (`--json`) output:
+
+| Function | Purpose |
+|----------|---------|
+| `overlay_stack` | Active and available overlays with author metadata |
+| `overlay_status` | Active, available, and applied overlay sets |
+| `overlay_trace` | Per-file line-region attribution to overlay refs |
+| `overlay_why` | Winning merge rule and reason for a file |
+| `overlay_impact` | Files touched by an overlay (reads git objects directly) |
+
+## Performance gates
+
+The perf harness (`gr2/overlay/perf.py`) measures overlay operations
+against git baselines:
+
+| Gate | Measures | Threshold |
+|------|----------|-----------|
+| `activate_vs_git_checkout_single_file` | Activate latency vs `git checkout` | 2.0x |
+| `status_vs_git_status` | Overlay status vs `git status` | 2.0x |
+| `diff_vs_git_diff` | Overlay diff vs `git diff` | 2.0x |
+
+Gates use median-based sampling to reduce single-run noise.
+
+## WorkspaceSpec
+
+Overlays are declared in `.grip/overlays.toml`:
+
+```toml
+[[overlays]]
+name = "dark-theme"
+path = "refs/overlays/myteam/dark-theme"
+applies_to = ["*.toml", "*.yml"]
+priority = 10
+
+[[overlays]]
+name = "shared-base"
+path = "refs/overlays/team/shared-base"
+applies_to = ["*.toml"]
+priority = 0
+```
+
+Higher priority overlays take precedence during composition.
+
+## Object encoding
+
+Each overlay is stored as an annotated tag pointing at a structured
+tree with four entries:
+
+```
+<tag>
+  └── <tree>
+      ├── metadata_blob     # TOML metadata (author, tier, trust, timestamp)
+      ├── staged_index_tree  # Files from the staging area
+      ├── untracked_blobs    # Untracked file content
+      └── working_tree_tree  # Complete working tree snapshot
+```
+
+The Tier A filter captures only config files: `.toml`, `.yml`, `.json`
+by extension, plus `COMPOSE.md` by exact filename.
+
+## M1 acceptance criteria
+
+1. Capture Tier A overlay from source directory into bare git store
+2. Push overlay ref to remote store via identity-mapped refspec
+3. Fetch overlay ref on a separate store (simulating a different machine)
+4. Activate overlay: eagerly materialize all files into workspace
+5. Verify byte-for-byte content fidelity across all Tier A file types
+6. Deactivate: remove all overlay files, clean empty parent directories
+7. Verify workspace returns to pre-overlay state
+8. Trust gating: block untrusted overlays before any file writes
+9. Open mode: no trust config permits all overlays
+10. Idempotent: activate/deactivate cycles produce identical state
+
+All criteria are validated by the acceptance harness at
+`tests/test_overlay_acceptance.py`.
+
+## Module reference
+
+| Module | Purpose |
+|--------|---------|
+| `types.py` | Data types: `OverlayRef`, `OverlayMeta`, `OverlayTier`, `TrustLevel` |
+| `objects.py` | Capture and apply overlay objects (git plumbing) |
+| `refs.py` | Push and fetch overlay refs between stores |
+| `drivers.py` | Curated merge drivers (deep, prepend, union) |
+| `trust.py` | Workspace trust model and allowlist |
+| `activate.py` | Activate and deactivate overlays |
+| `introspection.py` | Query functions (stack, status, trace, why, impact) |
+| `workspace_spec.py` | `[[overlays]]` TOML schema |
+| `perf.py` | Performance gates measurement harness |
+| `cli.py` | Typer CLI stubs for `gr overlay` subcommands |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check gr2/overlay/ tests/
+ruff format --check gr2/overlay/ tests/
+```

gitgrip-1.5.0/VERSION

@@ -0,0 +1 @@
+1.5.0

gitgrip-1.5.0/_build/backend.py

@@ -0,0 +1,58 @@
+"""In-tree PEP 517 build backend: single-source the distribution version from
+the repo-root ``Cargo.toml`` so a published wheel's version says which grip it
+belongs to (never a hand-maintained 0.1.0 drifting from the Rust crate).
+
+It wraps setuptools.build_meta: before every build hook it (re)writes a
+``VERSION`` file next to pyproject.toml from ``../Cargo.toml``'s
+``[package] version``. ``[tool.setuptools.dynamic] version = {file = "VERSION"}``
+then reads it. Cargo.toml lives one level above the packaging root (gr2/), so it
+is present for a direct wheel build and for the sdist build; a wheel built FROM
+an sdist has no Cargo.toml (it is outside the packaging root), and there VERSION
+travels inside the sdist (MANIFEST.in) and is left as-is.
+
+requires-python is >=3.11, so tomllib is always stdlib — no build dependency.
+"""
+from __future__ import annotations
+
+import pathlib
+
+from setuptools import build_meta as _bm
+
+from version_from_cargo import sync_version as _sync
+
+# Re-export the hooks we do not override so the frontend finds a complete backend.
+get_requires_for_build_wheel = _bm.get_requires_for_build_wheel
+get_requires_for_build_sdist = _bm.get_requires_for_build_sdist
+get_requires_for_build_editable = _bm.get_requires_for_build_editable
+
+
+def _sync_version() -> None:
+    """Write VERSION from ../Cargo.toml (via the setuptools-free helper, so the
+    version logic is testable in a plain venv). PEP 517 runs the backend with
+    cwd = the packaging root."""
+    _sync(pathlib.Path.cwd())
+
+
+def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
+    _sync_version()
+    return _bm.build_wheel(wheel_directory, config_settings, metadata_directory)
+
+
+def build_sdist(sdist_directory, config_settings=None):
+    _sync_version()
+    return _bm.build_sdist(sdist_directory, config_settings)
+
+
+def prepare_metadata_for_build_wheel(metadata_directory, config_settings=None):
+    _sync_version()
+    return _bm.prepare_metadata_for_build_wheel(metadata_directory, config_settings)
+
+
+def build_editable(wheel_directory, config_settings=None, metadata_directory=None):
+    _sync_version()
+    return _bm.build_editable(wheel_directory, config_settings, metadata_directory)
+
+
+def prepare_metadata_for_build_editable(metadata_directory, config_settings=None):
+    _sync_version()
+    return _bm.prepare_metadata_for_build_editable(metadata_directory, config_settings)

gitgrip-1.5.0/_build/version_from_cargo.py

@@ -0,0 +1,43 @@
+"""Pure version-single-sourcing helper — no setuptools import, so it is testable
+in a plain runtime venv. The build backend (backend.py) delegates to it.
+
+Writes a VERSION file from the repo-root ``Cargo.toml``'s ``[package] version``,
+but ONLY when that Cargo.toml is grip's own crate (``[package] name`` ==
+``gitgrip``). Any other ``../Cargo.toml`` is ignored — an sdist unpacked one
+level below an unrelated Rust project must not inherit that project's version
+(measured: a foreign Cargo at 7.7.7 minted gitgrip-7.7.7 while the sdist's own
+VERSION said 1.4.0). When grip's Cargo is not reachable (a wheel built FROM an
+unpacked sdist), the VERSION that rode inside the sdist is used. Never invents a
+version, and never trusts a foreign crate's.
+"""
+from __future__ import annotations
+
+import pathlib
+import tomllib
+
+_CRATE_NAME = "gitgrip"
+
+
+def _grip_cargo_version(cargo: pathlib.Path) -> str | None:
+    """The [package] version of ``cargo`` iff it is grip's own crate, else None."""
+    if not cargo.is_file():
+        return None
+    pkg = tomllib.loads(cargo.read_text(encoding="utf-8")).get("package", {})
+    if pkg.get("name") != _CRATE_NAME:
+        return None  # a foreign Cargo.toml — do not trust its version
+    return pkg.get("version")
+
+
+def sync_version(root: pathlib.Path) -> str:
+    root = pathlib.Path(root)
+    version_file = root / "VERSION"
+    version = _grip_cargo_version(root.parent / "Cargo.toml")
+    if version is not None:
+        version_file.write_text(version + "\n", encoding="utf-8")
+        return version
+    if version_file.is_file() and version_file.read_text(encoding="utf-8").strip():
+        return version_file.read_text(encoding="utf-8").strip()
+    raise RuntimeError(
+        f"cannot single-source version at {root}: no grip Cargo.toml "
+        f"([package] name = {_CRATE_NAME!r}) above it and no populated VERSION file"
+    )

gitgrip-1.5.0/gitgrip.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: gitgrip
+Version: 1.5.0
+Summary: gr2 overlay substrate: config-overlay capture, composition, and materialization
+Requires-Python: >=3.11
+Requires-Dist: typer>=0.9
+Requires-Dist: tomli_w>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: toml>=0.10
+Requires-Dist: jsonschema>=4.18
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"

gitgrip-1.5.0/gitgrip.egg-info/SOURCES.txt

@@ -0,0 +1,199 @@
+MANIFEST.in
+README.md
+VERSION
+pyproject.toml
+_build/backend.py
+_build/version_from_cargo.py
+_build/__pycache__/backend.cpython-311.pyc
+_build/__pycache__/version_from_cargo.cpython-311.pyc
+gitgrip.egg-info/PKG-INFO
+gitgrip.egg-info/SOURCES.txt
+gitgrip.egg-info/dependency_links.txt
+gitgrip.egg-info/entry_points.txt
+gitgrip.egg-info/requires.txt
+gitgrip.egg-info/top_level.txt
+gr2/__init__.py
+gr2/overlay/__init__.py
+gr2/overlay/activate.py
+gr2/overlay/agent_manifest.py
+gr2/overlay/cli.py
+gr2/overlay/cross_repo.py
+gr2/overlay/drivers.py
+gr2/overlay/introspection.py
+gr2/overlay/language_drivers.py
+gr2/overlay/objects.py
+gr2/overlay/perf.py
+gr2/overlay/refs.py
+gr2/overlay/trust.py
+gr2/overlay/types.py
+gr2/overlay/units.py
+gr2/overlay/workspace_spec.py
+gr2/schemas/gr2-materialization-plan-v1.schema.json
+gr2_overlay/__init__.py
+prototypes/__init__.py
+prototypes/cache_materialization_probe.py
+prototypes/concurrent_event_stress.py
+prototypes/concurrent_lease_stress.py
+prototypes/concurrent_workspace_cap_stress.py
+prototypes/contribution_protocol.py
+prototypes/cross_mode_lane_stress.py
+prototypes/jsonl_store.py
+prototypes/lane_workspace_prototype.py
+prototypes/layout_model_probe.py
+prototypes/propagation_daemon.py
+prototypes/propagation_state_machine.py
+prototypes/python_exec_playground.py
+prototypes/python_hook_runtime_playground.py
+prototypes/python_migration_playground.py
+prototypes/python_review_checkout_playground.py
+prototypes/python_spec_apply_playground.py
+prototypes/real_git_lane_materialization.py
+prototypes/real_git_playground.py
+prototypes/recall_lane_history.py
+prototypes/repo_maintenance_prototype.py
+prototypes/repo_transport_probe.py
+python_cli/__init__.py
+python_cli/__main__.py
+python_cli/add.py
+python_cli/app.py
+python_cli/branch.py
+python_cli/channel_bridge.py
+python_cli/clone_exec.py
+python_cli/commit.py
+python_cli/config.py
+python_cli/env_exec.py
+python_cli/events.py
+python_cli/execops.py
+python_cli/failures.py
+python_cli/file_exec.py
+python_cli/gitops.py
+python_cli/grip.py
+python_cli/grip_cli.py
+python_cli/hooks.py
+python_cli/launch_exec.py
+python_cli/merge_verification.py
+python_cli/migration.py
+python_cli/open_gr_review.py
+python_cli/platform.py
+python_cli/pr.py
+python_cli/project_review.py
+python_cli/prune.py
+python_cli/push.py
+python_cli/review.py
+python_cli/review_ephemeral.py
+python_cli/review_run.py
+python_cli/spec_apply.py
+python_cli/staging_cleanup.py
+python_cli/syncops.py
+python_cli/target.py
+python_cli/workspace_snapshot.py
+tests/test_add.py
+tests/test_agent_manifest_overlay_source.py
+tests/test_app_event_outcomes.py
+tests/test_apply_convergence.py
+tests/test_branch.py
+tests/test_channel_bridge.py
+tests/test_clone_materialization.py
+tests/test_commit.py
+tests/test_config_base_path_guard.py
+tests/test_config_overlay.py
+tests/test_contribution_protocol.py
+tests/test_ensure_lane_checkout_reference_clone.py
+tests/test_env_materialization.py
+tests/test_event_log_integrity.py
+tests/test_event_outcome_policy.py
+tests/test_events.py
+tests/test_events_torn_line.py
+tests/test_execops.py
+tests/test_failure_event_outcome.py
+tests/test_gr2_packaging.py
+tests/test_gr2_review_receipt.py
+tests/test_grip_cli.py
+tests/test_grip_hardening.py
+tests/test_grip_object_model.py
+tests/test_grip_snapshot.py
+tests/test_hook_events.py
+tests/test_hook_hardening.py
+tests/test_jsonl_store.py
+tests/test_lane_create_fork_base_cli.py
+tests/test_lane_lease_show_json.py
+tests/test_lane_lifecycle_safety.py
+tests/test_lane_toml_serialization.py
+tests/test_launch_primitive.py
+tests/test_m2_overlay_hindsight.py
+tests/test_m2_overlay_mem0.py
+tests/test_m2_overlay_zep.py
+tests/test_materialization_plan_contract.py
+tests/test_merge_evidence.py
+tests/test_merge_parent_verification.py
+tests/test_migration.py
+tests/test_migration_overlay_compatibility.py
+tests/test_no_bare_python_cli_imports.py
+tests/test_null_current_lane_refusal.py
+tests/test_open_gr_enter.py
+tests/test_open_project_refusal_reason_cli.py
+tests/test_overlay_acceptance.py
+tests/test_overlay_activate.py
+tests/test_overlay_cli.py
+tests/test_overlay_cli_wiring.py
+tests/test_overlay_composition_merge.py
+tests/test_overlay_cross_repo_atomic_apply.py
+tests/test_overlay_cross_repo_perf_gate.py
+tests/test_overlay_cross_repo_rollback.py
+tests/test_overlay_driver_registry.py
+tests/test_overlay_introspection.py
+tests/test_overlay_multi_stack.py
+tests/test_overlay_object_encoding.py
+tests/test_overlay_perf_gates.py
+tests/test_overlay_python_driver.py
+tests/test_overlay_tier_b_encoding.py
+tests/test_overlay_tier_b_perf_gates.py
+tests/test_overlay_tier_b_repo_state.py
+tests/test_overlay_tier_b_staging_discipline.py
+tests/test_overlay_trust_model.py
+tests/test_overlay_workspace_spec.py
+tests/test_pr_events.py
+tests/test_pr_merge_method.py
+tests/test_pr_merge_partial_failure.py
+tests/test_project_file_materialization.py
+tests/test_project_review_range_reconstruction.py
+tests/test_project_review_three_repo.py
+tests/test_propagation_contribution.py
+tests/test_propagation_daemon.py
+tests/test_propagation_state_machine.py
+tests/test_prune.py
+tests/test_push.py
+tests/test_repo_status_linked_worktree.py
+tests/test_repo_status_schema_version.py
+tests/test_repo_status_symlinked_git_dir.py
+tests/test_review_bind_fork_base.py
+tests/test_review_bind_from_range.py
+tests/test_review_bind_verify.py
+tests/test_review_cli.py
+tests/test_review_close_gr.py
+tests/test_review_create_project_cli.py
+tests/test_review_ephemeral.py
+tests/test_review_open_lane.py
+tests/test_review_run.py
+tests/test_review_verify_inside.py
+tests/test_rmtree_or_refuse.py
+tests/test_snapshot_id_prefix_resolution.py
+tests/test_spec_apply_event_outcomes.py
+tests/test_sprint21_sync_platform.py
+tests/test_staging_cleanup.py
+tests/test_sync_event_outcomes.py
+tests/test_sync_fetch.py
+tests/test_target.py
+tests/test_tmux_launch_runtime.py
+tests/test_unit_abort.py
+tests/test_unit_apply.py
+tests/test_unit_apply_dry_run.py
+tests/test_unit_manifest_schema.py
+tests/test_unit_propose.py
+tests/test_unit_topological_apply.py
+tests/test_version_single_sourced.py
+tests/test_workspace_convert_clone.py
+tests/test_workspace_edit_lease_cap.py
+tests/test_workspace_identity_boundary.py
+tests/test_workspace_init_from_topology.py
+tests/test_workspace_snapshot.py

gitgrip-1.5.0/gitgrip.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

gitgrip-1.5.0/gitgrip.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gr2 = gr2.python_cli.app:main

gitgrip-1.5.0/gitgrip.egg-info/requires.txt

@@ -0,0 +1,9 @@
+typer>=0.9
+tomli_w>=1.0
+pyyaml>=6.0
+toml>=0.10
+jsonschema>=4.18
+
+[dev]
+pytest>=8.0
+ruff>=0.4

gitgrip-1.5.0/gitgrip.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+gr2
+gr2_overlay

gitgrip-1.5.0/gr2/overlay/__init__.py

@@ -0,0 +1,6 @@
+"""gr2 overlay substrate: config-overlay capture, composition, and materialization.
+
+M1 scope: Tier A only (config files), eager materialization, trust-gated.
+"""
+
+__version__ = "0.1.0"