graphcoding 0.1.0__py3-none-any.whl

graphcoding/__init__.py

@@ -0,0 +1,6 @@
+"""GraphCoding — your repo's living knowledge graph.
+
+Query before you touch code. Design in the graph. Sync as you go.
+Drift is caught by tooling, not memory.
+"""
+__version__ = "0.1.0"

graphcoding/cli.py

@@ -0,0 +1,382 @@
+"""graphcoding — the CLI.
+
+Commands map 1:1 to the GraphCoding loop:
+
+  QUERY    query, show, status
+  DESIGN   plan, link, mark-delete
+  CODE     (your editor / your agent)
+  SYNC     sync
+  VERIFY   drift
+
+Plus lifecycle: init, scan, hooks.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+
+from . import __version__
+from .drift import blocking_count, compute_drift, format_report
+from .scan import scan_repo, trackable
+from .store import (DEFAULT_CONFIG, EDGE_TYPES, GRAPH_DIR, NODE_TYPES, Graph,
+                    Node, config_path, find_root, load_config)
+from .sync import sync as run_sync
+from . import hooks as hooks_mod
+
+
+def _root_or_die(args) -> str:
+    root = find_root(getattr(args, "root", None))
+    if not root:
+        sys.exit("no .graphcoding/ found — run `graphcoding init` at your repo root")
+    return root
+
+
+def _print_node(g: Graph, node: Node, verbose: bool = True) -> None:
+    print(f"{node.name}")
+    print(f"  type: {node.type}   status: {node.status}"
+          + (f"   language: {node.language}" if node.language else ""))
+    if node.summary:
+        print(f"  summary: {node.summary}")
+    if verbose:
+        outgoing = sorted(node.edges, key=lambda e: (e["type"], e["to"]))
+        if outgoing:
+            print("  outgoing:")
+            for e in outgoing:
+                missing = "" if e["to"] in g.nodes else "   (planned/missing)"
+                print(f"    -[{e['type']}]-> {e['to']}{missing}")
+        incoming = g.incoming(node.name)
+        if incoming:
+            print("  recorded incoming edges (blast radius — these break if you change it):")
+            for src, etype in incoming:
+                print(f"    <-[{etype}]- {src}")
+            if all(etype in ("IMPORTS", "CONTAINS") for _, etype in incoming):
+                print("    (scanner-visible edges only; runtime/cross-boundary callers"
+                      " may exist unrecorded — record with: graphcoding link <src> CALLS"
+                      f" {node.name})")
+        elif not node.name.endswith((".md", ".json")):
+            print("  recorded incoming edges: none — likely safe to change, but the"
+                  " graph only knows recorded edges; verify runtime refs once, then"
+                  " record them")
+
+
+# ---------------------------------------------------------------- commands --
+def cmd_init(args) -> None:
+    root = os.path.abspath(args.root or os.getcwd())
+    gdir = os.path.join(root, GRAPH_DIR)
+    os.makedirs(gdir, exist_ok=True)
+    cfgp = config_path(root)
+    if not os.path.exists(cfgp):
+        with open(cfgp, "w", encoding="utf-8") as f:
+            json.dump(DEFAULT_CONFIG, f, indent=2)
+            f.write("\n")
+    g = Graph.load(root)
+    g.save()
+    print(f"initialized {os.path.relpath(gdir, os.getcwd())}/ (config.json + graph.jsonl)")
+    if not args.no_scan:
+        cfg = load_config(root)
+        stats = scan_repo(root, cfg, g)
+        g.save()
+        print(f"scanned: {stats['files']} files -> {stats['added']} nodes added, "
+              f"{stats['updated']} updated")
+    if args.hooks:
+        for p in hooks_mod.install(root):
+            print(f"installed hook: {os.path.relpath(p, root)}")
+    print("next: `graphcoding status` · commit .graphcoding/ with your code")
+
+
+def cmd_scan(args) -> None:
+    root = _root_or_die(args)
+    cfg = load_config(root)
+    g = Graph.load(root)
+    stats = scan_repo(root, cfg, g)
+    g.save()
+    print(f"scanned {stats['files']} files: {stats['added']} added, "
+          f"{stats['updated']} updated — graph now {len(g.nodes)} nodes")
+
+
+def cmd_plan(args) -> None:
+    root = _root_or_die(args)
+    g = Graph.load(root)
+    node = Node(name=args.name, type=args.type, status="planned",
+                summary=args.summary or "")
+    for spec in args.edge or []:
+        try:
+            etype, target = spec.split(":", 1)
+        except ValueError:
+            sys.exit(f"bad --edge '{spec}' (want TYPE:target, e.g. IMPORTS:src/db.py)")
+        etype = etype.upper()
+        if etype not in EDGE_TYPES:
+            sys.exit(f"unknown edge type {etype} (one of {', '.join(EDGE_TYPES)})")
+        node.add_edge(target, etype)
+    existing = g.nodes.get(args.name)
+    if existing and existing.status != "planned" and not args.force:
+        sys.exit(f"{args.name} already exists with status={existing.status}; "
+                 "use --force to re-plan it")
+    if existing:
+        existing.status = "planned"
+        if args.summary:
+            existing.summary = args.summary
+        for e in node.edges:
+            existing.add_edge(e["to"], e["type"])
+    else:
+        g.nodes[node.name] = node
+    g.save()
+    print(f"planned: {args.name}" + (f" — {args.summary}" if args.summary else ""))
+
+
+def cmd_link(args) -> None:
+    root = _root_or_die(args)
+    g = Graph.load(root)
+    src = g.nodes.get(args.source)
+    if not src:
+        sys.exit(f"unknown source node {args.source} (plan or scan it first)")
+    etype = args.type.upper()
+    if etype not in EDGE_TYPES:
+        sys.exit(f"unknown edge type {etype} (one of {', '.join(EDGE_TYPES)})")
+    added = src.add_edge(args.target, etype)
+    g.save()
+    note = "" if args.target in g.nodes else "  (target not in graph yet — planned work)"
+    print(("linked" if added else "already linked")
+          + f": {args.source} -[{etype}]-> {args.target}{note}")
+
+
+def cmd_mark_delete(args) -> None:
+    root = _root_or_die(args)
+    g = Graph.load(root)
+    node = g.nodes.get(args.name)
+    if not node:
+        sys.exit(f"unknown node {args.name}")
+    incoming = g.incoming(args.name)
+    if incoming and not args.force:
+        print(f"{args.name} has {len(incoming)} incoming edge(s):")
+        for s, t in incoming:
+            print(f"  <-[{t}]- {s}")
+        sys.exit("refusing to mark for deletion — update the callers first, "
+                 "or pass --force if they are part of the same removal")
+    node.status = "to-be-deleted"
+    g.save()
+    print(f"marked to-be-deleted: {args.name} "
+          "(delete the file, then `graphcoding sync`)")
+
+
+def cmd_sync(args) -> None:
+    root = _root_or_die(args)
+    cfg = load_config(root)
+    g = Graph.load(root)
+    res = run_sync(root, cfg, g, staged=args.staged, commit=args.commit,
+                   files=args.files)
+    if not args.quiet:
+        print(f"sync: {len(res['upserted'])} upserted, {len(res['removed'])} removed")
+        for p in res["upserted"][:15]:
+            print(f"   ~ {p}")
+        for p in res["removed"][:15]:
+            print(f"   - {p}")
+        for p in res["skipped"]:
+            print(f"   ! {p} marked deleted in git but still on disk — skipped")
+        planned = g.with_status("planned")
+        if planned:
+            print(f"still planned: {len(planned)} node(s) — `graphcoding status`")
+
+
+def cmd_drift(args) -> None:
+    root = _root_or_die(args)
+    cfg = load_config(root)
+    g = Graph.load(root)
+    report = compute_drift(root, cfg, g)
+    scope = None
+    if args.staged:
+        try:
+            out = subprocess.run(["git", "-C", root, "diff", "--cached", "--name-only"],
+                                 capture_output=True, text=True, check=True).stdout
+            scope = {p for p in out.splitlines() if p.strip() and trackable(p, cfg)}
+        except (subprocess.CalledProcessError, FileNotFoundError):
+            scope = set()
+        if not scope:
+            sys.exit(0)  # nothing staged that we track
+    n = blocking_count(report, scope)
+    if not (args.quiet and n == 0):
+        print(format_report(report, scope))
+    sys.exit(1 if n else 0)
+
+
+def cmd_status(args) -> None:
+    root = _root_or_die(args)
+    cfg = load_config(root)
+    g = Graph.load(root)
+    by_status: dict[str, int] = {}
+    for n in g.nodes.values():
+        by_status[n.status] = by_status.get(n.status, 0) + 1
+    edges = sum(len(n.edges) for n in g.nodes.values())
+    print(f"graph: {len(g.nodes)} nodes, {edges} edges "
+          f"({', '.join(f'{k}={v}' for k, v in sorted(by_status.items()))})")
+    planned = g.with_status("planned")
+    if planned:
+        print(f"\nplanned — left to build ({len(planned)}):")
+        for n in planned:
+            print(f"   ? {n.name}" + (f" — {n.summary}" if n.summary else ""))
+    doomed = g.with_status("to-be-deleted")
+    if doomed:
+        print(f"\nto-be-deleted — left to remove ({len(doomed)}):")
+        for n in doomed:
+            print(f"   ! {n.name}")
+    broken = []
+    for n in g.nodes.values():
+        for e in n.edges:
+            if e["to"] not in g.nodes:
+                broken.append((n.name, e["type"], e["to"]))
+    if broken:
+        print(f"\ndangling edges — dependencies not wired yet ({len(broken)}):")
+        for s, t, d in sorted(broken)[:20]:
+            print(f"   {s} -[{t}]-> {d}")
+    rep = compute_drift(root, cfg, g)
+    n_block = blocking_count(rep)
+    print(f"\ndrift: {'NONE' if not n_block else f'{n_block} blocking — run `graphcoding drift`'}")
+
+
+def cmd_summary(args) -> None:
+    root = _root_or_die(args)
+    g = Graph.load(root)
+    node = g.nodes.get(args.name)
+    if not node:
+        sys.exit(f"unknown node {args.name} (scan or plan it first)")
+    node.summary = args.text
+    if node.status == "needs-analysis":
+        node.status = "ok"
+    g.save()
+    print(f"summary set: {args.name} — {args.text}")
+
+
+def cmd_health(args) -> None:
+    from .health import compute_health, format_health
+    root = _root_or_die(args)
+    cfg = load_config(root)
+    g = Graph.load(root)
+    print(format_health(compute_health(root, cfg, g)))
+
+
+def cmd_query(args) -> None:
+    root = _root_or_die(args)
+    g = Graph.load(root)
+    results = g.search(args.terms, limit=args.limit)
+    if not results:
+        print("no matches")
+        return
+    for score, node in results:
+        line = f"{node.name}  [{node.type}/{node.status}]"
+        if node.summary:
+            line += f" — {node.summary}"
+        print(line)
+
+
+def cmd_show(args) -> None:
+    root = _root_or_die(args)
+    g = Graph.load(root)
+    node = g.nodes.get(args.name)
+    if not node:
+        hits = g.search([args.name], limit=5)
+        if len(hits) == 1:
+            node = hits[0][1]
+        elif hits:
+            print(f"no exact node '{args.name}'; close matches:")
+            for _, n in hits:
+                print(f"   {n.name}")
+            sys.exit(1)
+        else:
+            sys.exit(f"no node named or matching '{args.name}'")
+    _print_node(g, node)
+
+
+def cmd_hooks(args) -> None:
+    root = _root_or_die(args)
+    for p in hooks_mod.install(root):
+        print(f"installed: {os.path.relpath(p, root)}")
+
+
+# ------------------------------------------------------------------ parser --
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="graphcoding",
+        description="GraphCoding — your repo's living knowledge graph. "
+                    "Query before you touch code; the graph is the design contract.")
+    p.add_argument("--version", action="version", version=f"graphcoding {__version__}")
+    p.add_argument("--root", help="repo root (default: walk up from cwd)")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("init", help="create .graphcoding/ and scan the repo")
+    s.add_argument("--no-scan", action="store_true", help="skip the initial scan")
+    s.add_argument("--hooks", action="store_true", help="also install git hooks")
+    s.set_defaults(func=cmd_init)
+
+    s = sub.add_parser("scan", help="(re)scan the whole repo into the graph")
+    s.set_defaults(func=cmd_scan)
+
+    s = sub.add_parser("plan", help="declare a node you intend to build (DESIGN)")
+    s.add_argument("name", help="repo-relative path, or path::Symbol")
+    s.add_argument("--summary", "-s", help="one line: what it will do")
+    s.add_argument("--type", "-t", default="CodeFile", choices=NODE_TYPES)
+    s.add_argument("--edge", "-e", action="append",
+                   help="TYPE:target (repeatable), e.g. -e IMPORTS:src/db.py")
+    s.add_argument("--force", action="store_true")
+    s.set_defaults(func=cmd_plan)
+
+    s = sub.add_parser("link", help="add an edge between nodes")
+    s.add_argument("source")
+    s.add_argument("type", help="|".join(EDGE_TYPES))
+    s.add_argument("target")
+    s.set_defaults(func=cmd_link)
+
+    s = sub.add_parser("mark-delete", help="mark a node's file for removal")
+    s.add_argument("name")
+    s.add_argument("--force", action="store_true",
+                   help="mark even with incoming edges")
+    s.set_defaults(func=cmd_mark_delete)
+
+    s = sub.add_parser("sync", help="reconcile the graph with changed files (SYNC)")
+    s.add_argument("--staged", action="store_true", help="sync staged changes")
+    s.add_argument("--commit", nargs="?", const="HEAD",
+                   help="sync files changed in a commit (default HEAD)")
+    s.add_argument("--files", nargs="*", help="sync explicit files")
+    s.add_argument("--quiet", action="store_true")
+    s.set_defaults(func=cmd_sync)
+
+    s = sub.add_parser("drift", help="working tree vs graph; exit 1 on drift (VERIFY)")
+    s.add_argument("--staged", action="store_true",
+                   help="only gate on files staged for commit")
+    s.add_argument("--quiet", action="store_true", help="print nothing when clean")
+    s.set_defaults(func=cmd_drift)
+
+    s = sub.add_parser("status", help="planned work, dangling edges, drift summary")
+    s.set_defaults(func=cmd_status)
+
+    s = sub.add_parser("health", help="memory quality: coverage, stale summaries, orphans")
+    s.set_defaults(func=cmd_health)
+
+    s = sub.add_parser("summary", help="set/replace a node's one-line intent")
+    s.add_argument("name")
+    s.add_argument("text")
+    s.set_defaults(func=cmd_summary)
+
+    s = sub.add_parser("query", help="search nodes by name + summary (QUERY)")
+    s.add_argument("terms", nargs="+")
+    s.add_argument("--limit", type=int, default=20)
+    s.set_defaults(func=cmd_query)
+
+    s = sub.add_parser("show", help="one node: summary, edges, blast radius (QUERY)")
+    s.add_argument("name")
+    s.set_defaults(func=cmd_show)
+
+    s = sub.add_parser("hooks", help="install pre-commit gate + post-commit sync")
+    s.set_defaults(func=cmd_hooks)
+    return p
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

graphcoding/drift.py

@@ -0,0 +1,83 @@
+"""Drift detection — compare the working tree against the graph.
+
+Four findings:
+  missing_node     file on disk with no graph node          (blocking)
+  ghost_node       graph node whose file is gone            (blocking)
+  not_deleted      marked to-be-deleted but still on disk   (blocking)
+  unbuilt_planned  planned node with no file yet            (informational —
+                   design ahead of code is the point)
+
+Exit code 1 when any blocking drift exists, so hooks and CI can gate on it.
+"""
+from __future__ import annotations
+
+import os
+
+from .scan import tracked_files
+from .store import Graph
+
+
+def compute_drift(root: str, cfg: dict, graph: Graph) -> dict:
+    disk = set(tracked_files(root, cfg))
+    file_nodes = graph.file_nodes()
+    missing = sorted(disk - set(file_nodes))
+    ghosts, unbuilt, not_deleted = [], [], []
+    for path, node in sorted(file_nodes.items()):
+        on_disk = path in disk or os.path.exists(os.path.join(root, path))
+        if node.status == "planned":
+            if not on_disk:
+                unbuilt.append(path)
+            # planned + on disk = built but not synced -> caught as stale status
+        elif node.status == "to-be-deleted":
+            if on_disk:
+                not_deleted.append(path)
+            else:
+                ghosts.append(path)  # deleted on disk, node awaiting removal
+        elif not on_disk:
+            ghosts.append(path)
+    built_not_synced = [p for p, n in sorted(file_nodes.items())
+                        if n.status == "planned"
+                        and (p in disk or os.path.exists(os.path.join(root, p)))]
+    return {
+        "disk": len(disk),
+        "nodes": len(file_nodes),
+        "missing_node": missing,
+        "ghost_node": ghosts,
+        "not_deleted": not_deleted,
+        "built_not_synced": built_not_synced,
+        "unbuilt_planned": unbuilt,
+    }
+
+
+def blocking_count(report: dict, scope: set[str] | None = None) -> int:
+    items = (report["missing_node"] + report["ghost_node"]
+             + report["not_deleted"] + report["built_not_synced"])
+    if scope is not None:
+        items = [p for p in items if p in scope]
+    return len(items)
+
+
+def format_report(report: dict, scope: set[str] | None = None) -> str:
+    def rows(key: str, mark: str) -> list[str]:
+        items = report[key]
+        if scope is not None:
+            items = [p for p in items if p in scope]
+        lines = [f"{key}: {len(items)}"]
+        lines += [f"   {mark} {p}" for p in items[:25]]
+        if len(items) > 25:
+            lines.append(f"   … and {len(items) - 25} more")
+        return lines
+
+    out = ["=== graphcoding drift report ==="]
+    out.append(f"disk tracked files: {report['disk']} | graph file nodes: {report['nodes']}")
+    out += rows("missing_node", "+")
+    out += rows("ghost_node", "-")
+    out += rows("not_deleted", "!")
+    out += rows("built_not_synced", "~")
+    out += rows("unbuilt_planned", "?")
+    n = blocking_count(report, scope)
+    out.append("")
+    out.append(f"DRIFT={'YES' if n else 'NONE'} ({n} blocking issue{'s' if n != 1 else ''})")
+    if n:
+        out.append("fix: graphcoding sync   (then re-run: graphcoding drift)")
+    return "\n".join(out)

graphcoding/health.py

@@ -0,0 +1,97 @@
+"""Memory-quality report — the decay counter.
+
+The drift gate holds the floor (structure can't rot). This module measures the
+upper floors, which CAN rot: summaries, intent edges, lifecycle hygiene.
+`graphcoding health` names what's decaying so neglect is visible long before
+it hurts. Informational — always exits 0; quality is steered, not gated.
+
+Checks:
+  * summary coverage        nodes with no summary at all
+  * stale-summary suspects  stored summary no longer matches what the file's
+                            own docstring/first-comment says (computed live —
+                            nothing extra is stored, so no graph-diff noise)
+  * needs-analysis backlog  machine-guessed summaries awaiting a mind
+  * orphans                 nodes with no edges either way — unmapped territory
+  * intent-edge richness    hand-recorded CALLS/REFERENCES/DEPENDS_ON count;
+                            the graph's irreplaceable layer
+"""
+from __future__ import annotations
+
+from .scan import scan_file
+from .store import Graph
+
+INTENT_EDGES = ("CALLS", "REFERENCES", "DEPENDS_ON", "RELATED_TO",
+                "INHERITS", "IMPLEMENTS")
+
+
+def compute_health(root: str, cfg: dict, graph: Graph) -> dict:
+    files = graph.file_nodes()
+    incoming_counts: dict[str, int] = {}
+    for n in graph.nodes.values():
+        for e in n.edges:
+            incoming_counts[e["to"]] = incoming_counts.get(e["to"], 0) + 1
+
+    no_summary, stale_suspects, needs_analysis, orphans = [], [], [], []
+    intent_edges = 0
+    for path, node in sorted(files.items()):
+        if node.status == "planned":
+            continue
+        if not node.summary:
+            no_summary.append(path)
+        else:
+            # live re-extraction; a differing fresh auto-summary means the
+            # file's self-description moved while the stored summary didn't
+            fresh, _ = scan_file(root, path, {**cfg, "scan_symbols": False})
+            if fresh.summary and fresh.summary != node.summary \
+                    and len(fresh.summary) >= len(node.summary):
+                stale_suspects.append((path, node.summary, fresh.summary))
+        if node.status == "needs-analysis":
+            needs_analysis.append(path)
+        if not node.edges and not incoming_counts.get(path):
+            orphans.append(path)
+        intent_edges += sum(1 for e in node.edges if e["type"] in INTENT_EDGES)
+
+    total = len([n for n in files.values() if n.status != "planned"])
+    return {
+        "total": total,
+        "no_summary": no_summary,
+        "stale_suspects": stale_suspects,
+        "needs_analysis": needs_analysis,
+        "orphans": orphans,
+        "intent_edges": intent_edges,
+    }
+
+
+def format_health(h: dict) -> str:
+    total = max(h["total"], 1)
+    covered = h["total"] - len(h["no_summary"])
+    out = ["=== graphcoding health — memory quality ==="]
+    out.append(f"nodes: {h['total']}   summary coverage: {covered}/{h['total']} "
+               f"({100 * covered // total}%)   hand-recorded intent edges: {h['intent_edges']}")
+
+    def block(title: str, items: list, render) -> None:
+        if not items:
+            return
+        out.append(f"\n{title} ({len(items)}):")
+        for it in items[:15]:
+            out.append(render(it))
+        if len(items) > 15:
+            out.append(f"   … and {len(items) - 15} more")
+
+    block("no summary — invisible to query and to agents", h["no_summary"],
+          lambda p: f"   · {p}")
+    block("stale-summary suspects — file's self-description moved, graph didn't",
+          h["stale_suspects"],
+          lambda s: f"   ~ {s[0]}\n     graph: {s[1][:70]}\n     file:  {s[2][:70]}")
+    block("needs-analysis — machine guesses awaiting a mind", h["needs_analysis"],
+          lambda p: f"   ? {p}")
+    block("orphans — no edges either way; unmapped or genuinely dead",
+          h["orphans"], lambda p: f"   ø {p}")
+
+    if h["intent_edges"] == 0 and h["total"] > 5:
+        out.append("\nzero hand-recorded edges: the graph is still only a scan. "
+                   "Record what no scanner sees (HTTP calls, queues, cron→table): "
+                   "graphcoding link <src> CALLS <dst>")
+    if not (h["no_summary"] or h["stale_suspects"] or h["needs_analysis"]):
+        out.append("\nmemory is healthy: every node carries current, human-grade intent.")
+    return "\n".join(out)

graphcoding/hooks.py

@@ -0,0 +1,65 @@
+"""Git hook installer — the enforcement layer.
+
+pre-commit : blocks the commit when a file being committed drifts from the
+             graph. Scoped to staged files so teammates' un-graphed WIP never
+             deadlocks your commit.
+post-commit: syncs the graph with what was just committed (belt + braces; the
+             pre-commit gate should already have forced a sync).
+
+Existing hooks are preserved: ours is appended behind a marker block.
+"""
+from __future__ import annotations
+
+import os
+import stat
+
+MARKER_BEGIN = "# >>> graphcoding hook >>>"
+MARKER_END = "# <<< graphcoding hook <<<"
+
+PRE_COMMIT = f"""{MARKER_BEGIN}
+# Block the commit if any STAGED file drifts from .graphcoding/graph.jsonl
+if command -v graphcoding >/dev/null 2>&1; then
+  graphcoding drift --staged || {{
+    echo ""
+    echo "[graphcoding] staged files drift from the graph."
+    echo "[graphcoding] run: graphcoding sync --staged && git add .graphcoding/graph.jsonl"
+    exit 1
+  }}
+fi
+{MARKER_END}"""
+
+POST_COMMIT = f"""{MARKER_BEGIN}
+# Keep the graph in step with what was just committed
+if command -v graphcoding >/dev/null 2>&1; then
+  graphcoding sync --commit HEAD --quiet || true
+fi
+{MARKER_END}"""
+
+
+def _install_one(hooks_dir: str, name: str, body: str) -> str:
+    path = os.path.join(hooks_dir, name)
+    if os.path.exists(path):
+        with open(path, encoding="utf-8") as f:
+            content = f.read()
+        if MARKER_BEGIN in content:
+            head, _, rest = content.partition(MARKER_BEGIN)
+            _, _, tail = rest.partition(MARKER_END)
+            content = head.rstrip("\n") + "\n" + body + tail
+        else:
+            content = content.rstrip("\n") + "\n\n" + body + "\n"
+    else:
+        content = "#!/bin/sh\n\n" + body + "\n"
+    with open(path, "w", encoding="utf-8") as f:
+        f.write(content)
+    os.chmod(path, os.stat(path).st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return path
+
+
+def install(root: str) -> list[str]:
+    hooks_dir = os.path.join(root, ".git", "hooks")
+    if not os.path.isdir(hooks_dir):
+        raise SystemExit("not a git repository (no .git/hooks) — run inside a git repo")
+    return [
+        _install_one(hooks_dir, "pre-commit", PRE_COMMIT),
+        _install_one(hooks_dir, "post-commit", POST_COMMIT),
+    ]