zeoel-framework 1.0.0

package/.agents/skills/zeoel/skills/graphify/global_graph.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+import json
+import hashlib
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+import networkx as nx
+from networkx.readwrite import json_graph as _jg
+
+_GLOBAL_DIR = Path.home() / ".graphify"
+_GLOBAL_GRAPH = _GLOBAL_DIR / "global-graph.json"
+_GLOBAL_MANIFEST = _GLOBAL_DIR / "global-manifest.json"
+
+
+def _load_manifest() -> dict:
+    if _GLOBAL_MANIFEST.exists():
+        try:
+            return json.loads(_GLOBAL_MANIFEST.read_text(encoding="utf-8"))
+        except Exception:
+            pass
+    return {"version": 1, "repos": {}}
+
+
+def _save_manifest(manifest: dict) -> None:
+    _GLOBAL_DIR.mkdir(parents=True, exist_ok=True)
+    _GLOBAL_MANIFEST.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+
+
+def _load_global_graph() -> nx.Graph:
+    if _GLOBAL_GRAPH.exists():
+        data = json.loads(_GLOBAL_GRAPH.read_text(encoding="utf-8"))
+        if "links" not in data and "edges" in data:
+            data = dict(data, links=data["edges"])
+        try:
+            return _jg.node_link_graph(data, edges="links")
+        except TypeError:
+            return _jg.node_link_graph(data)
+    return nx.Graph()
+
+
+def _save_global_graph(G: nx.Graph) -> None:
+    _GLOBAL_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        data = _jg.node_link_data(G, edges="links")
+    except TypeError:
+        data = _jg.node_link_data(G)
+    _GLOBAL_GRAPH.write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+def _file_hash(path: Path) -> str:
+    h = hashlib.sha256()
+    h.update(path.read_bytes())
+    return h.hexdigest()[:16]
+
+
+def global_add(source_path: Path, repo_tag: str) -> dict:
+    """Add or update a project graph in the global graph.
+
+    Returns a summary dict with keys: repo_tag, nodes_added, nodes_removed, skipped.
+    Skipped=True means the source graph hasn't changed since last add.
+    """
+    from graphify.build import prefix_graph_for_global, prune_repo_from_graph
+
+    if not source_path.exists():
+        raise FileNotFoundError(f"graph not found: {source_path}")
+
+    manifest = _load_manifest()
+    src_hash = _file_hash(source_path)
+
+    existing = manifest["repos"].get(repo_tag, {})
+    existing_path = existing.get("source_path", "")
+    if existing_path and existing_path != str(source_path.resolve()):
+        print(
+            f"[graphify global] warning: repo tag '{repo_tag}' previously pointed to "
+            f"{existing_path!r}, now updating to {str(source_path.resolve())!r}. "
+            f"Use --as <tag> to give it a different name.",
+            file=sys.stderr,
+        )
+    if existing.get("source_hash") == src_hash:
+        return {"repo_tag": repo_tag, "nodes_added": 0, "nodes_removed": 0, "skipped": True}
+
+    # Load source graph
+    data = json.loads(source_path.read_text(encoding="utf-8"))
+    if "links" not in data and "edges" in data:
+        data = dict(data, links=data["edges"])
+    try:
+        src_G = _jg.node_link_graph(data, edges="links")
+    except TypeError:
+        src_G = _jg.node_link_graph(data)
+
+    # Prefix IDs for cross-project isolation
+    prefixed = prefix_graph_for_global(src_G, repo_tag)
+
+    # Load global graph and prune stale nodes for this repo
+    G = _load_global_graph()
+    removed = prune_repo_from_graph(G, repo_tag)
+
+    # Merge external-library nodes (no source_file) by label to avoid duplication
+    external_labels = {
+        d.get("label", ""): n
+        for n, d in G.nodes(data=True)
+        if not d.get("source_file") and d.get("label")
+    }
+    nodes_to_skip = set()
+    for node, data in prefixed.nodes(data=True):
+        if not data.get("source_file") and data.get("label") in external_labels:
+            nodes_to_skip.add(node)
+
+    # Compose: add prefixed nodes (except deduplicated externals) into global graph
+    for node, data in prefixed.nodes(data=True):
+        if node not in nodes_to_skip:
+            G.add_node(node, **data)
+    for u, v, data in prefixed.edges(data=True):
+        if u not in nodes_to_skip and v not in nodes_to_skip:
+            G.add_edge(u, v, **data)
+
+    added = prefixed.number_of_nodes() - len(nodes_to_skip)
+    _save_global_graph(G)
+
+    manifest["repos"][repo_tag] = {
+        "added_at": datetime.now(timezone.utc).isoformat(),
+        "source_path": str(source_path.resolve()),
+        "node_count": added,
+        "edge_count": prefixed.number_of_edges(),
+        "source_hash": src_hash,
+    }
+    _save_manifest(manifest)
+
+    return {"repo_tag": repo_tag, "nodes_added": added, "nodes_removed": removed, "skipped": False}
+
+
+def global_remove(repo_tag: str) -> int:
+    """Remove all nodes for repo_tag from the global graph. Returns count removed."""
+    from graphify.build import prune_repo_from_graph
+
+    manifest = _load_manifest()
+    if repo_tag not in manifest["repos"]:
+        raise KeyError(f"repo '{repo_tag}' not in global graph")
+
+    G = _load_global_graph()
+    removed = prune_repo_from_graph(G, repo_tag)
+    _save_global_graph(G)
+
+    del manifest["repos"][repo_tag]
+    _save_manifest(manifest)
+    return removed
+
+
+def global_list() -> dict:
+    """Return the manifest repos dict."""
+    return _load_manifest().get("repos", {})
+
+
+def global_path() -> Path:
+    return _GLOBAL_GRAPH

package/.agents/skills/zeoel/skills/graphify/google_workspace.py

@@ -0,0 +1,223 @@
+"""Optional Google Workspace shortcut export support.
+
+Google Drive for desktop stores native Docs, Sheets, and Slides as small JSON
+shortcut files (.gdoc, .gsheet, .gslides). Those files are pointers, not the
+document content. This module exports them to Markdown sidecars via the
+googleworkspace CLI (`gws`) so Graphify can extract their actual contents.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+import urllib.parse
+from pathlib import Path
+from typing import Callable, Any
+
+
+GOOGLE_WORKSPACE_EXTENSIONS = {".gdoc", ".gsheet", ".gslides"}
+
+
+def google_workspace_enabled(value: str | None = None) -> bool:
+    """Return True when Google Workspace shortcut export is enabled."""
+    raw = value if value is not None else os.environ.get("GRAPHIFY_GOOGLE_WORKSPACE", "")
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _safe_yaml_str(value: str) -> str:
+    return value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", " ").replace("\r", " ")
+
+
+def _extract_file_id_from_url(url: str) -> str | None:
+    """Extract a Drive file ID from common Google Docs/Drive URL shapes."""
+    if not url:
+        return None
+    parsed = urllib.parse.urlparse(url)
+    query = urllib.parse.parse_qs(parsed.query)
+    if query.get("id"):
+        return query["id"][0]
+    match = re.search(r"/(?:document|spreadsheets|presentation|file)/d/([^/?#]+)", parsed.path)
+    if match:
+        return match.group(1)
+    return None
+
+
+def _extract_resource_key(url: str, data: dict[str, Any]) -> str | None:
+    for key in ("resource_key", "resourceKey"):
+        value = data.get(key)
+        if value:
+            return str(value)
+    if not url:
+        return None
+    parsed = urllib.parse.urlparse(url)
+    query = urllib.parse.parse_qs(parsed.query)
+    if query.get("resourcekey"):
+        return query["resourcekey"][0]
+    return None
+
+
+def read_google_shortcut(path: Path) -> dict[str, str | None]:
+    """Read a .gdoc/.gsheet/.gslides shortcut and return export metadata."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        raise RuntimeError(f"could not read Google Workspace shortcut {path}: {exc}") from exc
+
+    url = str(data.get("url") or "")
+    file_id = (
+        data.get("doc_id")
+        or data.get("file_id")
+        or data.get("fileId")
+        or data.get("id")
+        or _extract_file_id_from_url(url)
+    )
+    if not file_id:
+        resource_id = str(data.get("resource_id") or "")
+        if ":" in resource_id:
+            file_id = resource_id.split(":", 1)[1]
+
+    if not file_id:
+        raise RuntimeError(f"Google Workspace shortcut {path} does not include a Drive file ID")
+
+    return {
+        "file_id": str(file_id),
+        "url": url or None,
+        "resource_key": _extract_resource_key(url, data),
+        "account": str(data.get("email")) if data.get("email") else None,
+    }
+
+
+def _run_gws_export(file_id: str, mime_type: str, output: Path, resource_key: str | None = None) -> None:
+    exe = shutil.which("gws")
+    if not exe:
+        raise RuntimeError(
+            "gws is required for Google Workspace export. Install it from "
+            "https://github.com/googleworkspace/cli and run `gws auth login -s drive`."
+        )
+
+    params: dict[str, str] = {"fileId": file_id, "mimeType": mime_type}
+    # Drive resource keys are sent via X-Goog-Drive-Resource-Keys. The current
+    # gws export command has no custom-header flag, so do not pass resourceKey
+    # as an unsupported query parameter.
+    _ = resource_key
+    output = output.resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    timeout = int(os.environ.get("GRAPHIFY_GOOGLE_WORKSPACE_TIMEOUT", "120"))
+    result = subprocess.run(
+        [exe, "drive", "files", "export", "--params", json.dumps(params), "-o", output.name],
+        capture_output=True,
+        cwd=output.parent,
+        text=True,
+        timeout=timeout,
+    )
+    if result.returncode != 0:
+        stderr = (result.stderr or result.stdout or "").strip()
+        if len(stderr) > 1200:
+            stderr = stderr[:1200] + "..."
+        raise RuntimeError(f"gws export failed for {file_id}: {stderr}")
+
+
+def _sidecar_path(path: Path, out_dir: Path) -> Path:
+    name_hash = hashlib.sha256(str(path.resolve()).encode()).hexdigest()[:8]
+    return out_dir / f"{path.stem}_{name_hash}.md"
+
+
+def _with_frontmatter(path: Path, shortcut: dict[str, str | None], body: str, exported_mime_type: str) -> str:
+    source_url = shortcut.get("url") or ""
+    account = shortcut.get("account") or ""
+    account_line = ""
+    if account:
+        account_hash = hashlib.sha256(account.encode()).hexdigest()[:12]
+        account_line = f'google_account_hash: "{account_hash}"\n'
+    return (
+        "---\n"
+        f'source_file: "{_safe_yaml_str(str(path))}"\n'
+        'source_type: "google_workspace"\n'
+        f'google_file_id: "{_safe_yaml_str(shortcut["file_id"] or "")}"\n'
+        f'google_export_mime_type: "{_safe_yaml_str(exported_mime_type)}"\n'
+        f'source_url: "{_safe_yaml_str(source_url)}"\n'
+        f"{account_line}"
+        "---\n\n"
+        f"<!-- converted from Google Workspace shortcut: {path.name} -->\n\n"
+        f"{body.strip()}\n"
+    )
+
+
+def convert_google_workspace_file(
+    path: Path,
+    out_dir: Path,
+    *,
+    xlsx_to_markdown: Callable[[Path], str] | None = None,
+) -> Path | None:
+    """Export a Google Workspace shortcut to a Markdown sidecar.
+
+    Returns the converted Markdown path, or None when conversion is unsupported
+    or produced no readable content.
+    """
+    ext = path.suffix.lower()
+    if ext not in GOOGLE_WORKSPACE_EXTENSIONS:
+        return None
+
+    shortcut = read_google_shortcut(path)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    out_path = _sidecar_path(path, out_dir)
+
+    if ext == ".gdoc":
+        with tempfile.NamedTemporaryFile("w+b", suffix=".md", delete=False, dir=out_dir) as tmp:
+            tmp_path = Path(tmp.name)
+        try:
+            _run_gws_export(shortcut["file_id"] or "", "text/markdown", tmp_path, shortcut.get("resource_key"))
+            body = tmp_path.read_text(encoding="utf-8", errors="replace")
+        finally:
+            tmp_path.unlink(missing_ok=True)
+        if not body.strip():
+            return None
+        out_path.write_text(_with_frontmatter(path, shortcut, body, "text/markdown"), encoding="utf-8")
+        return out_path
+
+    if ext == ".gslides":
+        with tempfile.NamedTemporaryFile("w+b", suffix=".txt", delete=False, dir=out_dir) as tmp:
+            tmp_path = Path(tmp.name)
+        try:
+            _run_gws_export(shortcut["file_id"] or "", "text/plain", tmp_path, shortcut.get("resource_key"))
+            body = tmp_path.read_text(encoding="utf-8", errors="replace")
+        finally:
+            tmp_path.unlink(missing_ok=True)
+        if not body.strip():
+            return None
+        out_path.write_text(_with_frontmatter(path, shortcut, body, "text/plain"), encoding="utf-8")
+        return out_path
+
+    if ext == ".gsheet":
+        if xlsx_to_markdown is None:
+            raise RuntimeError("Google Sheets export requires the office extra: pip install graphifyy[office,google]")
+        with tempfile.NamedTemporaryFile("w+b", suffix=".xlsx", delete=False, dir=out_dir) as tmp:
+            tmp_path = Path(tmp.name)
+        try:
+            _run_gws_export(
+                shortcut["file_id"] or "",
+                "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+                tmp_path,
+                shortcut.get("resource_key"),
+            )
+            body = xlsx_to_markdown(tmp_path)
+        finally:
+            tmp_path.unlink(missing_ok=True)
+        if not body.strip():
+            return None
+        out_path.write_text(
+            _with_frontmatter(
+                path,
+                shortcut,
+                body,
+                "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+            ),
+            encoding="utf-8",
+        )
+        return out_path
+
+    return None

package/.agents/skills/zeoel/skills/graphify/hooks.py

@@ -0,0 +1,304 @@
+# git hook integration - install/uninstall graphify post-commit and post-checkout hooks
+from __future__ import annotations
+import configparser
+import re
+import sys
+from pathlib import Path
+
+_HOOK_MARKER = "# graphify-hook-start"
+_HOOK_MARKER_END = "# graphify-hook-end"
+_CHECKOUT_MARKER = "# graphify-checkout-hook-start"
+_CHECKOUT_MARKER_END = "# graphify-checkout-hook-end"
+
+_PYTHON_DETECT = """\
+# Detect the correct Python interpreter (handles pipx, venv, system installs)
+GRAPHIFY_BIN=$(command -v graphify 2>/dev/null)
+if [ -n "$GRAPHIFY_BIN" ]; then
+    case "$GRAPHIFY_BIN" in
+        *.exe) _SHEBANG="" ;;
+        *)     _SHEBANG=$(head -1 "$GRAPHIFY_BIN" | sed 's/^#![[:space:]]*//') ;;
+    esac
+    case "$_SHEBANG" in
+        */env\\ *) GRAPHIFY_PYTHON="${_SHEBANG#*/env }" ;;
+        *)         GRAPHIFY_PYTHON="$_SHEBANG" ;;
+    esac
+    # Allowlist: only keep characters valid in a filesystem path to prevent
+    # injection if the shebang contains shell metacharacters
+    case "$GRAPHIFY_PYTHON" in
+        *[!a-zA-Z0-9/_.@-]*) GRAPHIFY_PYTHON="" ;;
+    esac
+    if [ -n "$GRAPHIFY_PYTHON" ] && ! "$GRAPHIFY_PYTHON" -c "import graphify" 2>/dev/null; then
+        GRAPHIFY_PYTHON=""
+    fi
+fi
+# Fall back: try python3, then python (Windows has no python3 shim)
+if [ -z "$GRAPHIFY_PYTHON" ]; then
+    if command -v python3 >/dev/null 2>&1 && python3 -c "import graphify" 2>/dev/null; then
+        GRAPHIFY_PYTHON="python3"
+    elif command -v python >/dev/null 2>&1 && python -c "import graphify" 2>/dev/null; then
+        GRAPHIFY_PYTHON="python"
+    else
+        exit 0
+    fi
+fi
+"""
+
+_HOOK_SCRIPT = """\
+# graphify-hook-start
+# Auto-rebuilds the knowledge graph after each commit (code files only, no LLM needed).
+# Installed by: graphify hook install
+
+# Skip during rebase/merge/cherry-pick to avoid blocking --continue with unstaged changes
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+[ -d "$GIT_DIR/rebase-merge" ] && exit 0
+[ -d "$GIT_DIR/rebase-apply" ] && exit 0
+[ -f "$GIT_DIR/MERGE_HEAD" ] && exit 0
+[ -f "$GIT_DIR/CHERRY_PICK_HEAD" ] && exit 0
+
+CHANGED=$(git diff --name-only HEAD~1 HEAD 2>/dev/null || git diff --name-only HEAD 2>/dev/null)
+if [ -z "$CHANGED" ]; then
+    exit 0
+fi
+
+""" + _PYTHON_DETECT + """
+export GRAPHIFY_CHANGED="$CHANGED"
+
+# Run rebuild detached so git commit returns immediately.
+# Full repo rebuilds can take hours; blocking the post-commit hook stalls the shell.
+_GRAPHIFY_LOG="${HOME}/.cache/graphify-rebuild.log"
+mkdir -p "$(dirname "$_GRAPHIFY_LOG")"
+echo "[graphify hook] launching background rebuild (log: $_GRAPHIFY_LOG)"
+nohup $GRAPHIFY_PYTHON -c "
+import os, signal, sys
+from pathlib import Path
+
+changed_raw = os.environ.get('GRAPHIFY_CHANGED', '')
+changed = [Path(f.strip()) for f in changed_raw.strip().splitlines() if f.strip()]
+
+if not changed:
+    sys.exit(0)
+
+print(f'[graphify hook] {len(changed)} file(s) changed - rebuilding graph...')
+
+try:
+    from graphify.watch import _rebuild_code, _apply_resource_limits
+    _apply_resource_limits()
+    _timeout = int(os.environ.get('GRAPHIFY_REBUILD_TIMEOUT', '600'))
+    if _timeout > 0 and hasattr(signal, 'SIGALRM'):
+        signal.signal(signal.SIGALRM, lambda *_: (_ for _ in ()).throw(TimeoutError(f'graphify rebuild exceeded {_timeout}s')))
+        signal.alarm(_timeout)
+    _force = os.environ.get('GRAPHIFY_FORCE', '').lower() in ('1', 'true', 'yes')
+    _rebuild_code(Path('.'), changed_paths=changed, force=_force)
+except TimeoutError as exc:
+    print(f'[graphify hook] {exc}')
+    sys.exit(1)
+except Exception as exc:
+    print(f'[graphify hook] Rebuild failed: {exc}')
+    sys.exit(1)
+" > "$_GRAPHIFY_LOG" 2>&1 < /dev/null &
+disown 2>/dev/null || true
+# graphify-hook-end
+"""
+
+
+_CHECKOUT_SCRIPT = """\
+# graphify-checkout-hook-start
+# Auto-rebuilds the knowledge graph (code only) when switching branches.
+# Installed by: graphify hook install
+
+PREV_HEAD=$1
+NEW_HEAD=$2
+BRANCH_SWITCH=$3
+
+# Only run on branch switches, not file checkouts
+if [ "$BRANCH_SWITCH" != "1" ]; then
+    exit 0
+fi
+
+# Only run if graphify-out/ exists (graph has been built before)
+if [ ! -d "graphify-out" ]; then
+    exit 0
+fi
+
+# Skip during rebase/merge/cherry-pick
+GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
+[ -d "$GIT_DIR/rebase-merge" ] && exit 0
+[ -d "$GIT_DIR/rebase-apply" ] && exit 0
+[ -f "$GIT_DIR/MERGE_HEAD" ] && exit 0
+[ -f "$GIT_DIR/CHERRY_PICK_HEAD" ] && exit 0
+
+""" + _PYTHON_DETECT + """
+_GRAPHIFY_LOG="${HOME}/.cache/graphify-rebuild.log"
+mkdir -p "$(dirname "$_GRAPHIFY_LOG")"
+echo "[graphify] Branch switched - launching background rebuild (log: $_GRAPHIFY_LOG)"
+nohup $GRAPHIFY_PYTHON -c "
+from graphify.watch import _rebuild_code, _apply_resource_limits
+from pathlib import Path
+import os, signal, sys
+try:
+    _apply_resource_limits()
+    _timeout = int(os.environ.get('GRAPHIFY_REBUILD_TIMEOUT', '600'))
+    if _timeout > 0 and hasattr(signal, 'SIGALRM'):
+        signal.signal(signal.SIGALRM, lambda *_: (_ for _ in ()).throw(TimeoutError(f'graphify rebuild exceeded {_timeout}s')))
+        signal.alarm(_timeout)
+    _force = os.environ.get('GRAPHIFY_FORCE', '').lower() in ('1', 'true', 'yes')
+    # post-checkout: branch switch can touch arbitrary files; full rebuild path
+    # (no changed_paths) is correct here. The flock inside _rebuild_code still
+    # prevents pile-ups when commit + checkout fire back-to-back.
+    _rebuild_code(Path('.'), force=_force)
+except TimeoutError as exc:
+    print(f'[graphify] {exc}')
+    sys.exit(1)
+except Exception as exc:
+    print(f'[graphify] Rebuild failed: {exc}')
+    sys.exit(1)
+" > "$_GRAPHIFY_LOG" 2>&1 < /dev/null &
+disown 2>/dev/null || true
+# graphify-checkout-hook-end
+"""
+
+
+def _git_root(path: Path) -> Path | None:
+    """Walk up to find .git directory."""
+    current = path.resolve()
+    for parent in [current, *current.parents]:
+        if (parent / ".git").exists():
+            return parent
+    return None
+
+
+def _hooks_dir(root: Path) -> Path:
+    """Return the git hooks directory, respecting core.hooksPath if set (e.g. Husky)."""
+    try:
+        cfg = configparser.RawConfigParser()
+        cfg.read(root / ".git" / "config", encoding="utf-8")
+        # configparser lowercases option names; git's hooksPath becomes hookspath
+        custom = cfg.get("core", "hookspath", fallback="").strip()
+        if custom:
+            p = Path(custom).expanduser()
+            if not p.is_absolute():
+                p = root / p
+            # Validate the resolved path stays within the repository root
+            # to prevent supply-chain attacks via malicious core.hooksPath values
+            try:
+                p.resolve().relative_to(root.resolve())
+            except ValueError:
+                pass  # Path escapes repo root; fall through to default .git/hooks
+            else:
+                p.mkdir(parents=True, exist_ok=True)
+                return p
+    except (configparser.Error, OSError) as exc:
+        # Narrow the exception (PR747-NEW-2): a bare `except Exception: pass`
+        # was hiding tampering signals (corrupt .git/config, permission flips
+        # by another tool). Surface them on stderr instead of silently
+        # falling through to the default hooks directory.
+        print(
+            f"[graphify hooks] could not read core.hooksPath from "
+            f"{root / '.git' / 'config'}: {exc}",
+            file=sys.stderr,
+        )
+    # In a linked worktree .git is a file not a directory, so constructing
+    # root/.git/hooks directly fails. Ask git for the real hooks path instead.
+    # NOTE: do NOT pass --path-format=absolute — added in git 2.31; older git
+    # echoes it back as a literal argument, contaminating stdout and causing a
+    # phantom directory to be created (#907). git -C <root> already returns an
+    # absolute path for worktree/external-gitdir cases, and a path relative to
+    # <root> for normal repos — anchoring on root covers both.
+    import subprocess as _sp
+    try:
+        res = _sp.run(
+            ["git", "-C", str(root), "rev-parse", "--git-path", "hooks"],
+            capture_output=True, text=True,
+        )
+        raw = res.stdout.strip()
+        # A valid hooks path can never contain newlines or NUL. Their presence
+        # means git echoed an unrecognised flag back (old git behaviour).
+        if res.returncode == 0 and raw and not any(c in raw for c in ("\n", "\r", "\x00")):
+            d = (root / raw).resolve()
+            d.mkdir(parents=True, exist_ok=True)
+            return d
+    except (OSError, FileNotFoundError):
+        pass
+    d = root / ".git" / "hooks"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _install_hook(hooks_dir: Path, name: str, script: str, marker: str) -> str:
+    """Install a single git hook, appending if an existing hook is present."""
+    hook_path = hooks_dir / name
+    if hook_path.exists():
+        content = hook_path.read_text(encoding="utf-8")
+        if marker in content:
+            return f"already installed at {hook_path}"
+        hook_path.write_text(content.rstrip() + "\n\n" + script, encoding="utf-8", newline="\n")
+        return f"appended to existing {name} hook at {hook_path}"
+    hook_path.write_text("#!/bin/sh\n" + script, encoding="utf-8", newline="\n")
+    hook_path.chmod(0o755)
+    return f"installed at {hook_path}"
+
+
+def _uninstall_hook(hooks_dir: Path, name: str, marker: str, marker_end: str) -> str:
+    """Remove graphify section from a git hook using start/end markers."""
+    hook_path = hooks_dir / name
+    if not hook_path.exists():
+        return f"no {name} hook found - nothing to remove."
+    content = hook_path.read_text(encoding="utf-8")
+    if marker not in content:
+        return f"graphify hook not found in {name} - nothing to remove."
+    new_content = re.sub(
+        rf"{re.escape(marker)}.*?{re.escape(marker_end)}\n?",
+        "",
+        content,
+        flags=re.DOTALL,
+    ).strip()
+    if not new_content or new_content in ("#!/bin/bash", "#!/bin/sh"):
+        hook_path.unlink()
+        return f"removed {name} hook at {hook_path}"
+    hook_path.write_text(new_content + "\n", encoding="utf-8", newline="\n")
+    return f"graphify removed from {name} at {hook_path} (other hook content preserved)"
+
+
+def install(path: Path = Path(".")) -> str:
+    """Install graphify post-commit and post-checkout hooks in the nearest git repo."""
+    root = _git_root(path)
+    if root is None:
+        raise RuntimeError(f"No git repository found at or above {path.resolve()}")
+
+    hooks_dir = _hooks_dir(root)
+
+    commit_msg = _install_hook(hooks_dir, "post-commit", _HOOK_SCRIPT, _HOOK_MARKER)
+    checkout_msg = _install_hook(hooks_dir, "post-checkout", _CHECKOUT_SCRIPT, _CHECKOUT_MARKER)
+
+    return f"post-commit: {commit_msg}\npost-checkout: {checkout_msg}"
+
+
+def uninstall(path: Path = Path(".")) -> str:
+    """Remove graphify post-commit and post-checkout hooks."""
+    root = _git_root(path)
+    if root is None:
+        raise RuntimeError(f"No git repository found at or above {path.resolve()}")
+
+    hooks_dir = _hooks_dir(root)
+    commit_msg = _uninstall_hook(hooks_dir, "post-commit", _HOOK_MARKER, _HOOK_MARKER_END)
+    checkout_msg = _uninstall_hook(hooks_dir, "post-checkout", _CHECKOUT_MARKER, _CHECKOUT_MARKER_END)
+
+    return f"post-commit: {commit_msg}\npost-checkout: {checkout_msg}"
+
+
+def status(path: Path = Path(".")) -> str:
+    """Check if graphify hooks are installed."""
+    root = _git_root(path)
+    if root is None:
+        return "Not in a git repository."
+    hooks_dir = _hooks_dir(root)
+
+    def _check(name: str, marker: str) -> str:
+        p = hooks_dir / name
+        if not p.exists():
+            return "not installed"
+        return "installed" if marker in p.read_text(encoding="utf-8") else "not installed (hook exists but graphify not found)"
+
+    commit = _check("post-commit", _HOOK_MARKER)
+    checkout = _check("post-checkout", _CHECKOUT_MARKER)
+    return f"post-commit: {commit}\npost-checkout: {checkout}"