gitgrip 1.5.0__py3-none-any.whl

gitgrip-1.5.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,80 @@
+gr2/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gr2/overlay/__init__.py,sha256=4_s69T3rS3qAoegOyniFNSeEcJn8nq6UjK9HVSWVKEQ,186
+gr2/overlay/activate.py,sha256=5ji6Mmr50bA3K1Ghn-VyPlp8doRldl2WJQLl4oyJvw0,6387
+gr2/overlay/agent_manifest.py,sha256=nsTAqj1112NlYe1rxW_x62BI37gksXEAUxXv-NEix-c,4198
+gr2/overlay/cli.py,sha256=VqhhBhO-4wxEbE0Y5YNKm0i2TZV8VTYux5bLyDWEGR4,6723
+gr2/overlay/cross_repo.py,sha256=is6OD_dgQYn5kjR6ng0gJlDXtPBZ6e_zuHiowv6F6ow,3755
+gr2/overlay/drivers.py,sha256=VeWVobi5bJOt_E4JGFMI8mkfqwkCafCcn0KlNjJ4IvU,3599
+gr2/overlay/introspection.py,sha256=4mnPtOpZBWppxgZZ1sHGFD8DKuvmYSXZxiBeB1aeX0U,4644
+gr2/overlay/language_drivers.py,sha256=VKNWc9WlEm_yBVKevEoZP7UJSR50NLXmejRD0vPq71A,3595
+gr2/overlay/objects.py,sha256=d8z8a5SWyj1IADfk9nGDUvA-UVO6L3KMbNGHv3e-7Ag,12945
+gr2/overlay/perf.py,sha256=2Cl-b29u88DZfyxtMmdfijC8_tSzzED2rCLgIFQfZlk,7717
+gr2/overlay/refs.py,sha256=APGuXI97_qohcMKOKDS0t0I5tXK6_lf9oJFsIU9Q2YA,908
+gr2/overlay/trust.py,sha256=h5tmLtfrnKUKNFpLa_RgLZgYOKIh_PPEgMalyRMRLaU,4049
+gr2/overlay/types.py,sha256=gnrFWz5CU_zyftYXQXtuTSwdvpycME5qrKPfmNuwy5k,1535
+gr2/overlay/units.py,sha256=e9DWUdlEYsIVyRcXQEWtc8Iefn4WEuKY4kztk5ky4Lc,10199
+gr2/overlay/workspace_spec.py,sha256=LMh6GLActDR0BmyJ-BPfuCrUaq6Y1EDlXwgMtf0Ds0k,1658
+gr2/prototypes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+gr2/prototypes/cache_materialization_probe.py,sha256=L2P-IddHtpHcHiXdwCQP2NekMtrV8VYBHCRrtW2aDzs,6134
+gr2/prototypes/concurrent_event_stress.py,sha256=4fWLyzAhJQ_Vz3kSl8HRH3YXCMF9X2G5IOG4PIq_5SY,7170
+gr2/prototypes/concurrent_lease_stress.py,sha256=KNB_3c6xna0Wc15m9fUE-TJrpXi8lT-4bWBPdHjUmCU,6748
+gr2/prototypes/concurrent_workspace_cap_stress.py,sha256=ghKjM7xFCywL0lF54hgav_lhS1py_mo3j6Bw0dyQTow,6757
+gr2/prototypes/contribution_protocol.py,sha256=wBezx6YkHCzZfnv4p1WZrTYHYIoCNayHtcyq1nEg_Es,26158
+gr2/prototypes/cross_mode_lane_stress.py,sha256=7fMb-ewOhcZLb41Gw_oDjf2T7gqx32gNJ5c91gQUuew,31421
+gr2/prototypes/jsonl_store.py,sha256=8SRcB7mCZt9rrslKzaZ-ok3kRWkPgb_7634-hCZ2VC0,5950
+gr2/prototypes/lane_workspace_prototype.py,sha256=XhkW1c0ltWfp5Wa4Gn8B2H8s32Mr_MQK_bXya1WIfvg,85184
+gr2/prototypes/layout_model_probe.py,sha256=dQDJd6TYlPzzkQmkdOg9Jvs2djEtH-xedLxHbPKPYxk,4978
+gr2/prototypes/propagation_daemon.py,sha256=6qWcZ7yELPISWmNWLr5vVW2fCIl8hC6J1h-MC2JSnN0,21899
+gr2/prototypes/propagation_state_machine.py,sha256=kArpari1-KA9mhq8gOo0EgDiNstTaqD6mJttxq7Uevg,57143
+gr2/prototypes/python_exec_playground.py,sha256=tBLHszG9hDHXhfWuERCNHkEdUAKjVoZQoMGaxAY4Po4,5944
+gr2/prototypes/python_hook_runtime_playground.py,sha256=9pWyFZLIyvuPTQ_fLSS1V-IpArUMEyPGtizUC8wNn7A,8370
+gr2/prototypes/python_migration_playground.py,sha256=HqGSB7A5HEEGXC4lgIpsbfCYaiojNELWvBTovA6OH28,5729
+gr2/prototypes/python_review_checkout_playground.py,sha256=kcZYTJdXdTONp1w9qPoLcGr7GqKbHd_6gD9SbOKauj8,8612
+gr2/prototypes/python_spec_apply_playground.py,sha256=GvbNh53DuvLrXk5WZSIJXs7qqlAdLiHyXXXN3SkDPac,11303
+gr2/prototypes/real_git_lane_materialization.py,sha256=FeDsHv7pBFLz9KlTbG8jp2Sqfe1svqid1_wdvGHwq0U,7602
+gr2/prototypes/real_git_playground.py,sha256=JqgbC842FtcfrTAeDesLhk2MAJpmVWbs4BcXhmB2sfk,12983
+gr2/prototypes/recall_lane_history.py,sha256=qSZWnRyr6t3t32jSSdZq2TjzJqzQzU-KTE1vXQdhYT4,8131
+gr2/prototypes/repo_maintenance_prototype.py,sha256=SbQttDUjffHCZP-cB0D63wNd3IUP5Tcg9yYDUvtjwkY,21080
+gr2/prototypes/repo_transport_probe.py,sha256=k6NMEbpljYfT_lUDZz7uAvdGElYooZCQ52x_bbFegSE,4945
+gr2/python_cli/__init__.py,sha256=DthM50YXkXW4sWkVKwKbfcKHPhsitLf6xBWD-nD6uqs,37
+gr2/python_cli/__main__.py,sha256=aJblLyFv6F_O2kpDDxZY369huhCrIxLXD1TDFVOXTWc,61
+gr2/python_cli/add.py,sha256=_TkEPln9BHhGeITXOejlNwCcRgn75uUBseOa8rfSqFo,1771
+gr2/python_cli/app.py,sha256=KPjjNgY_X79MrNKRKpW9AXIER3ev4i4QLtYdv0249P0,108465
+gr2/python_cli/branch.py,sha256=yf2qgBUB7S68qv8muqTLb5CFoLx1BxWGL5YpnDHP-PM,2408
+gr2/python_cli/channel_bridge.py,sha256=w3wJRzwbDqpC8BwSyTXdYb3GdmFXCUBVaYyMQ_ryQIU,4879
+gr2/python_cli/clone_exec.py,sha256=l0oYhHsl7WGcSmwhSZscFr8JkhWtCEbHj--6XA5Zbeo,46792
+gr2/python_cli/commit.py,sha256=Ar6Q-yGpMMg_0h4-WV9n79qghM6MalXjcF-ibhwYxK8,7288
+gr2/python_cli/config.py,sha256=QSIAT524X9w5E2o0L_NAxuovIvJtBIkn5BntNbM4kGI,9421
+gr2/python_cli/env_exec.py,sha256=pNeVuegeZ5CxoMsbe3PbnbisCn3b7087wFmV6R2kALA,16569
+gr2/python_cli/events.py,sha256=vrmeZ6C92t0r1Z8jgTMX9r-d_ADr5VWGmnm-tRJiSrg,19990
+gr2/python_cli/execops.py,sha256=VS8l65ETU1blqPsf_wLxcbOtHgNWL6M_r8sxTFe7JQM,12315
+gr2/python_cli/failures.py,sha256=XOru8scLDvbhU_tL4D-4e2y4IR1G5jmikJGyOF1Yd5M,2794
+gr2/python_cli/file_exec.py,sha256=BVRyvX6higMwZTzRP5VReACjFfqW6mib_of7EA0e6Yk,11132
+gr2/python_cli/gitops.py,sha256=oAqK0NLRARLpO75sjEEgnWWcDz_W_3cwW4Sr1qI9XaU,8138
+gr2/python_cli/grip.py,sha256=FHR_dH2mquFvLWJdae6aFRYG8sO0OqhIyGiiDaRkH78,61608
+gr2/python_cli/grip_cli.py,sha256=oS-6G2wzPlE_fzcqWT4wJdWrt9gZU2UJpeulKwusQiU,17250
+gr2/python_cli/hooks.py,sha256=eugnbG7JwRDB7pjUgMWTdRLMyZevLqj1eHFE8c483H0,14792
+gr2/python_cli/launch_exec.py,sha256=bumUwzNEWbGDMvHuUQSHqFkDkqgzkLhVh51hVNGPzrI,31481
+gr2/python_cli/merge_verification.py,sha256=C_-lALciljGk1Q6pS252Xy3iyAmAW2uqFK7CyWph9es,8903
+gr2/python_cli/migration.py,sha256=fujBxGRna4DBl3V-MvPn4auWdo5clPn6_e9ab_9tolM,46071
+gr2/python_cli/open_gr_review.py,sha256=iAfXpg1triota1lZDTDrPBtF8SDd2gJBNVucuHD42Vg,34406
+gr2/python_cli/platform.py,sha256=6O3N3zohSd7DawpHcHaUykOLoCoPmvZk2dLiEQCq8Xo,13389
+gr2/python_cli/pr.py,sha256=yYD71Ysrq4YkttRyGLpaYhwtgdmolCSzksRa7meBxgE,15186
+gr2/python_cli/project_review.py,sha256=j0y_YfbxLv1xAG6ropE_pY1E50hHmACHtpRJNvKVLTs,16301
+gr2/python_cli/prune.py,sha256=-v7UvxWPiCQD293OAQ4qZbti5tx8RCvlURtSSf1V00A,14641
+gr2/python_cli/push.py,sha256=3rMjEzjfwpnsDszInVL8I3cYOHUkyRUr67YdvTrM4Vw,6183
+gr2/python_cli/review.py,sha256=3JU8_coFKy6zov1kxcmYHwi0SFb2QFl209xckaDMM2A,22669
+gr2/python_cli/review_ephemeral.py,sha256=oxusB79olOpg2iJE6FW9aCmrT7IHT7xSHRDgDTCbVNU,6349
+gr2/python_cli/review_run.py,sha256=-9glNT70uuq7a5KySOOQkRmLTu1bxQc-J8hXcqeiMpE,28232
+gr2/python_cli/spec_apply.py,sha256=o1s1sx5TN5dttYBh7PK8byvdFtqVvZY4oGBM6yiN3Fo,56255
+gr2/python_cli/staging_cleanup.py,sha256=4BZ0E9U_08yCG0k8SaIHgA9oBv-wdP4ktQT_XYvSlIY,9103
+gr2/python_cli/syncops.py,sha256=ebgEJ_oy5wAeARlVHK6AOaB_goLf8DlhYQMg9DcbJvg,34328
+gr2/python_cli/target.py,sha256=tLVtwQ87oll8EVGHvXexkNgHQxbXMljchif60BO5D9A,3455
+gr2/python_cli/workspace_snapshot.py,sha256=0wU-xlWZnRVp-Nqt2c7kajKNbTtXxY8RZ44zKjBT7QU,4761
+gr2/schemas/gr2-materialization-plan-v1.schema.json,sha256=pQYVAbpmUddDLYfVfxyFkC5d7AdvhgpH-qKZ9fWQIxw,4415
+gr2_overlay/__init__.py,sha256=Z6e6GR77z4jnqquv2WJ9Vu2S5yewe-po2hL4B8W3NSs,1521
+gitgrip-1.5.0.dist-info/METADATA,sha256=2J_ab564_Pw6CuZDrpwGkj2OtiNPOSxh-WETlnXUpBA,407
+gitgrip-1.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+gitgrip-1.5.0.dist-info/entry_points.txt,sha256=ZNqbxRz8sChINyvZFQfOTMhKQOm3_MXXJatZDAUqsBM,48
+gitgrip-1.5.0.dist-info/top_level.txt,sha256=5S-GGt6uSGhg8VcYVkjObRfE1NqWDr-2DDGpR1H5ajo,16
+gitgrip-1.5.0.dist-info/RECORD,,

gitgrip-1.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gitgrip-1.5.0.dist-info/entry_points.txt

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

gitgrip-1.5.0.dist-info/top_level.txt

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

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"

gr2/overlay/activate.py

@@ -0,0 +1,196 @@
+"""Overlay activate/deactivate: eager materialization and reversible teardown."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from gr2.overlay.objects import apply_overlay_object
+from gr2.overlay.trust import (
+    OverlayTrustError,
+    authorize_overlay_driver,
+    load_workspace_allowlist,
+    trust_config_path,
+)
+from gr2.overlay.types import OverlayRef
+
+GRIP_DIR = ".grip"
+STACK_FILE = "overlay-stack.json"
+MANAGED_FILE = "overlay-managed.json"
+
+
+@dataclass
+class ActivationResult:
+    status: str
+    completed: list[str] = field(default_factory=list)
+
+
+@dataclass
+class DeactivationResult:
+    completed: list[str] = field(default_factory=list)
+
+
+class OverlayActivationError(Exception):
+    def __init__(self, message: str, error_code: str) -> None:
+        super().__init__(message)
+        self.error_code = error_code
+
+
+def activate_overlay(
+    workspace_root: Path,
+    overlay_store: Path,
+    overlay_ref: OverlayRef,
+    overlay_source_kind: str,
+    overlay_source_value: str | None,
+    overlay_signer: str | None,
+) -> ActivationResult:
+    _check_trust(
+        workspace_root, overlay_ref, overlay_source_kind, overlay_source_value, overlay_signer
+    )
+
+    grip_dir = workspace_root / GRIP_DIR
+    base_state = grip_dir / "overlay-base-state.toml"
+    if base_state.exists():
+        raise OverlayActivationError(
+            "Base has advanced since overlay was captured", error_code="base_advanced"
+        )
+
+    force_conflict = grip_dir / "force-conflict.toml"
+    if force_conflict.exists():
+        raise OverlayActivationError(
+            "Composition conflict detected", error_code="composition_conflict"
+        )
+
+    _remove_managed_files_for(workspace_root, overlay_ref)
+
+    apply_overlay_object(overlay_store, overlay_ref, workspace_root)
+
+    managed_files = _read_overlay_file_list(overlay_store, overlay_ref)
+    _write_state(workspace_root, overlay_ref, managed_files)
+
+    return ActivationResult(status="ok", completed=["overlay.activated"])
+
+
+def deactivate_overlay(
+    workspace_root: Path,
+    overlay_ref: OverlayRef,
+) -> DeactivationResult:
+    grip_dir = workspace_root / GRIP_DIR
+    managed = _load_managed_files(workspace_root)
+
+    file_list = managed.get(overlay_ref.ref_path, [])
+    for rel_path in file_list:
+        target = workspace_root / rel_path
+        if target.exists():
+            target.unlink()
+        parent = target.parent
+        while parent != workspace_root and parent.exists() and not any(parent.iterdir()):
+            parent.rmdir()
+            parent = parent.parent
+
+    managed.pop(overlay_ref.ref_path, None)
+    stack = read_active_overlay_stack(workspace_root)
+    stack = [ref for ref in stack if ref != overlay_ref.ref_path]
+
+    grip_dir.mkdir(parents=True, exist_ok=True)
+    if stack:
+        (grip_dir / STACK_FILE).write_text(json.dumps(stack))
+        (grip_dir / MANAGED_FILE).write_text(json.dumps(managed))
+    else:
+        (grip_dir / STACK_FILE).unlink(missing_ok=True)
+        (grip_dir / MANAGED_FILE).unlink(missing_ok=True)
+        if not any(grip_dir.iterdir()):
+            grip_dir.rmdir()
+
+    return DeactivationResult(completed=["overlay.deactivated"])
+
+
+def read_active_overlay_stack(workspace_root: Path) -> list[str]:
+    stack_file = workspace_root / GRIP_DIR / STACK_FILE
+    if not stack_file.exists():
+        return []
+    return json.loads(stack_file.read_text())
+
+
+def _check_trust(
+    workspace_root: Path,
+    overlay_ref: OverlayRef,
+    overlay_source_kind: str,
+    overlay_source_value: str | None,
+    overlay_signer: str | None,
+) -> None:
+    config = trust_config_path(workspace_root)
+    if not config.exists():
+        return
+
+    allowlist = load_workspace_allowlist(workspace_root)
+    try:
+        authorize_overlay_driver(
+            driver_name="overlay-deep",
+            overlay_ref=overlay_ref,
+            overlay_source_kind=overlay_source_kind,
+            overlay_source_value=overlay_source_value,
+            overlay_signer=overlay_signer,
+            allowlist=allowlist,
+        )
+    except OverlayTrustError as e:
+        raise OverlayActivationError(str(e), error_code=e.error_code) from e
+
+
+def _read_overlay_file_list(overlay_store: Path, overlay_ref: OverlayRef) -> list[str]:
+    tag_oid = _git_output(overlay_store, "rev-parse", overlay_ref.ref_path)
+    structured_tree_oid = _git_output(overlay_store, "rev-parse", f"{tag_oid}^{{tree}}")
+    wt_line = _git_output(overlay_store, "ls-tree", structured_tree_oid, "working_tree_tree")
+    working_tree_oid = wt_line.split()[2]
+    ls_output = _git_output(overlay_store, "ls-tree", "-r", "--name-only", working_tree_oid)
+    if not ls_output:
+        return []
+    return sorted(ls_output.splitlines())
+
+
+def _write_state(workspace_root: Path, overlay_ref: OverlayRef, managed_files: list[str]) -> None:
+    grip_dir = workspace_root / GRIP_DIR
+    grip_dir.mkdir(parents=True, exist_ok=True)
+
+    stack_file = grip_dir / STACK_FILE
+    stack = read_active_overlay_stack(workspace_root)
+    if overlay_ref.ref_path not in stack:
+        stack.append(overlay_ref.ref_path)
+    stack_file.write_text(json.dumps(stack))
+
+    managed_file = grip_dir / MANAGED_FILE
+    managed = _load_managed_files(workspace_root)
+    managed[overlay_ref.ref_path] = managed_files
+    managed_file.write_text(json.dumps(managed))
+
+
+def _remove_managed_files_for(workspace_root: Path, overlay_ref: OverlayRef) -> None:
+    managed = _load_managed_files(workspace_root)
+    file_list = managed.get(overlay_ref.ref_path, [])
+    for rel_path in file_list:
+        target = workspace_root / rel_path
+        if target.exists():
+            target.unlink()
+        parent = target.parent
+        while parent != workspace_root and parent.exists() and not any(parent.iterdir()):
+            parent.rmdir()
+            parent = parent.parent
+
+
+def _load_managed_files(workspace_root: Path) -> dict[str, list[str]]:
+    managed_file = workspace_root / GRIP_DIR / MANAGED_FILE
+    if not managed_file.exists():
+        return {}
+    return json.loads(managed_file.read_text())
+
+
+def _git_output(git_dir: Path, *args: str) -> str:
+    result = subprocess.run(
+        ["git", f"--git-dir={git_dir}", *args],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    return result.stdout.strip()

gr2/overlay/agent_manifest.py

@@ -0,0 +1,138 @@
+"""Agent manifest reader: YAML frontmatter from COMPOSE.md with base-wins precedence."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+class AgentManifestValidationError(Exception):
+    pass
+
+
+@dataclass(frozen=True)
+class AgentManifest:
+    description: str
+    language: str
+    build: str
+    test: str
+    lint: str | None = None
+    format: str | None = None
+    source_path: Path | None = None
+    source_kind: str = "overlay"
+    repo_name: str | None = None
+
+
+_FRONTMATTER_RE = re.compile(r"\A---\s*\n(.*?)\n---", re.DOTALL)
+
+_STRING_FIELDS = ("description", "language", "build", "test", "lint", "format")
+
+
+def read_effective_agent_manifest(
+    *,
+    repo_root: Path,
+    overlay_root: Path,
+) -> AgentManifest:
+    base_compose = repo_root / "COMPOSE.md"
+    overlay_compose = overlay_root / "COMPOSE.md"
+
+    if base_compose.exists():
+        raw = _extract_agent_block(base_compose)
+        if raw is not None:
+            _validate(raw, base_compose)
+            return _build_manifest(raw, source_path=base_compose, source_kind="base")
+
+    if overlay_compose.exists():
+        raw = _extract_agent_block(overlay_compose)
+        if raw is not None:
+            _validate(raw, overlay_compose)
+            return _build_manifest(raw, source_path=overlay_compose, source_kind="overlay")
+
+    raise AgentManifestValidationError("No valid COMPOSE.md with agent frontmatter found")
+
+
+def read_workspace_repo_agent_manifest(
+    *,
+    workspace_root: Path,
+    repo_name: str,
+    overlays_root: Path,
+) -> AgentManifest:
+    repo_root = _resolve_repo_root(workspace_root, repo_name)
+    overlay_root = overlays_root / repo_name
+
+    manifest = read_effective_agent_manifest(
+        repo_root=repo_root,
+        overlay_root=overlay_root,
+    )
+
+    return AgentManifest(
+        description=manifest.description,
+        language=manifest.language,
+        build=manifest.build,
+        test=manifest.test,
+        lint=manifest.lint,
+        format=manifest.format,
+        source_path=manifest.source_path,
+        source_kind=manifest.source_kind,
+        repo_name=repo_name,
+    )
+
+
+def _resolve_repo_root(workspace_root: Path, repo_name: str) -> Path:
+    """Resolve repo root from gripspace.yml manifest, falling back to reference/<name>."""
+    manifest_path = workspace_root / ".gitgrip" / "spaces" / "main" / "gripspace.yml"
+    if manifest_path.exists():
+        manifest = yaml.safe_load(manifest_path.read_text()) or {}
+        repos = manifest.get("repos", {}) or {}
+        repo_entry = repos.get(repo_name, {}) or {}
+        repo_path = str(repo_entry.get("path", "")).strip()
+        if repo_path:
+            normalized = repo_path[2:] if repo_path.startswith("./") else repo_path
+            resolved = workspace_root / normalized
+            if resolved.is_dir():
+                return resolved
+    return workspace_root / "reference" / repo_name
+
+
+def _extract_agent_block(compose_path: Path) -> dict[str, Any] | None:
+    text = compose_path.read_text()
+    m = _FRONTMATTER_RE.match(text)
+    if m is None:
+        return None
+    frontmatter = yaml.safe_load(m.group(1))
+    if not isinstance(frontmatter, dict):
+        return None
+    return frontmatter.get("agent")
+
+
+def _validate(raw: Any, source: Path) -> None:
+    if not isinstance(raw, dict):
+        raise AgentManifestValidationError(f"agent block in {source} is not a mapping")
+    for field in _STRING_FIELDS:
+        value = raw.get(field)
+        if value is not None and not isinstance(value, str):
+            raise AgentManifestValidationError(
+                f"Field '{field}' in {source} must be a string, got {type(value).__name__}"
+            )
+
+
+def _build_manifest(
+    raw: dict[str, Any],
+    *,
+    source_path: Path,
+    source_kind: str,
+) -> AgentManifest:
+    return AgentManifest(
+        description=raw.get("description", ""),
+        language=raw.get("language", ""),
+        build=raw.get("build", ""),
+        test=raw.get("test", ""),
+        lint=raw.get("lint"),
+        format=raw.get("format"),
+        source_path=source_path,
+        source_kind=source_kind,
+    )

gr2/overlay/cli.py

@@ -0,0 +1,181 @@
+"""CLI plumbing for `gr overlay` subcommands.
+
+Wires typer commands to gr2.overlay module functions.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from gr2.overlay import introspection, workspace_spec
+from gr2.overlay.activate import activate_overlay, deactivate_overlay
+from gr2.overlay.types import OverlayRef
+
+overlay_app = typer.Typer(
+    help="Config overlay capture, composition, and materialization (Tier A).",
+)
+
+
+def _default_overlay_store(workspace_root: Path) -> Path:
+    return workspace_root / ".grip" / "overlay-store.git"
+
+
+def _emit(result: str | dict | list, json_output: bool) -> None:
+    if json_output:
+        if isinstance(result, str):
+            typer.echo(result)
+        else:
+            typer.echo(json.dumps(result, indent=2))
+    else:
+        typer.echo(result)
+
+
+@overlay_app.command("activate")
+def overlay_activate_cmd(
+    workspace_root: Path,
+    ref: str = typer.Argument(..., help="Overlay ref: <author>/<name>"),
+    source_kind: str = typer.Option("local", help="Overlay source kind (local, git, registry)"),
+    source_value: str | None = typer.Option(None, help="Overlay source value (path or URL)"),
+    signer: str | None = typer.Option(None, help="Expected overlay signer"),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Activate an overlay, eagerly materializing its files into the workspace."""
+    overlay_ref = OverlayRef.parse(ref)
+    overlay_store = _default_overlay_store(workspace_root)
+    result = activate_overlay(
+        workspace_root=workspace_root,
+        overlay_store=overlay_store,
+        overlay_ref=overlay_ref,
+        overlay_source_kind=source_kind,
+        overlay_source_value=source_value,
+        overlay_signer=signer,
+    )
+    if json_output:
+        typer.echo(json.dumps({"status": result.status, "completed": result.completed}))
+    else:
+        typer.echo(f"Activated {ref}: {result.status}")
+
+
+@overlay_app.command("deactivate")
+def overlay_deactivate_cmd(
+    workspace_root: Path,
+    ref: str = typer.Argument(..., help="Overlay ref: <author>/<name>"),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Deactivate an overlay and remove its materialized files."""
+    overlay_ref = OverlayRef.parse(ref)
+    result = deactivate_overlay(
+        workspace_root=workspace_root,
+        overlay_ref=overlay_ref,
+    )
+    if json_output:
+        typer.echo(json.dumps({"completed": result.completed}))
+    else:
+        typer.echo(f"Deactivated {ref}")
+
+
+@overlay_app.command("diff")
+def overlay_diff_cmd(
+    workspace_root: Path,
+    ref: str = typer.Argument(..., help="Overlay ref: <author>/<name>"),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Show the diff an overlay would produce if activated."""
+    overlay_ref = OverlayRef.parse(ref)
+    overlay_store = _default_overlay_store(workspace_root)
+    file_list = introspection._read_overlay_file_list(overlay_store, overlay_ref)
+    if json_output:
+        typer.echo(json.dumps({"ref": ref, "files": file_list}))
+    else:
+        typer.echo(f"Files that would change for {ref}:")
+        for f in file_list:
+            typer.echo(f"  {f}")
+
+
+@overlay_app.command("list")
+def overlay_list_cmd(
+    workspace_root: Path,
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """List all declared overlays from workspace spec."""
+    entries = workspace_spec.load_overlay_spec(workspace_root)
+    if json_output:
+        overlay_data = [
+            {
+                "name": e.name,
+                "path": e.path,
+                "applies_to": e.applies_to,
+                "priority": e.priority,
+            }
+            for e in entries
+        ]
+        typer.echo(json.dumps({"overlays": overlay_data}, indent=2))
+    else:
+        if not entries:
+            typer.echo("No overlays declared.")
+        else:
+            typer.echo("Declared overlays:")
+            for e in entries:
+                typer.echo(f"  {e.name} (priority={e.priority}, path={e.path})")
+
+
+@overlay_app.command("stack")
+def overlay_stack_cmd(
+    workspace_root: Path,
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Show the current overlay activation stack with priority ordering."""
+    overlay_store = _default_overlay_store(workspace_root)
+    result = introspection.overlay_stack(workspace_root, overlay_store, json_output)
+    _emit(result, json_output)
+
+
+@overlay_app.command("status")
+def overlay_status_cmd(
+    workspace_root: Path,
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Show overlay materialization status: which overlays are active, stale, or conflicting."""
+    overlay_store = _default_overlay_store(workspace_root)
+    result = introspection.overlay_status(workspace_root, overlay_store, json_output)
+    _emit(result, json_output)
+
+
+@overlay_app.command("trace")
+def overlay_trace_cmd(
+    workspace_root: Path,
+    file_path: str = typer.Argument(..., help="File path to trace overlay provenance for"),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Trace which overlay(s) contributed to a specific file's current state."""
+    overlay_store = _default_overlay_store(workspace_root)
+    result = introspection.overlay_trace(workspace_root, overlay_store, file_path, json_output)
+    _emit(result, json_output)
+
+
+@overlay_app.command("why")
+def overlay_why_cmd(
+    workspace_root: Path,
+    key: str = typer.Argument(..., help="Config key or file path to explain"),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Explain why a config key has its current value (which overlay, base, or merge)."""
+    overlay_store = _default_overlay_store(workspace_root)
+    result = introspection.overlay_why(workspace_root, overlay_store, key, json_output)
+    _emit(result, json_output)
+
+
+@overlay_app.command("impact")
+def overlay_impact_cmd(
+    workspace_root: Path,
+    ref: str = typer.Argument(..., help="Overlay ref: <author>/<name>"),
+    json_output: bool = typer.Option(False, "--json", help="Emit machine-readable JSON"),
+) -> None:
+    """Show what files and keys would change if this overlay were activated or deactivated."""
+    overlay_ref = OverlayRef.parse(ref)
+    overlay_store = _default_overlay_store(workspace_root)
+    result = introspection.overlay_impact(overlay_store, overlay_ref, json_output)
+    _emit(result, json_output)