gra-context 0.1.0__py3-none-any.whl

gra/__main__.py

@@ -0,0 +1,3 @@
+from gra.cli import main
+
+main()

gra/adapters/symbol_graph_store.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+import json
+import sqlite3
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterable, Iterator, List, Optional
+
+from gra.core.symbol_types import Edge, Symbol
+
+# Bump when a table changes shape. The database is a cache of the codebase, so
+# an older one is emptied and rebuilt instead of migrated.
+_SCHEMA_VERSION = 4
+_TABLES = ("files", "symbols", "edges", "explanations", "embeddings")
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS files (
+    path              TEXT PRIMARY KEY,
+    content_hash      TEXT NOT NULL,
+    extractor_version INTEGER NOT NULL,
+    extract_json      TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS symbols (
+    id           TEXT PRIMARY KEY,
+    kind         TEXT NOT NULL,
+    name         TEXT NOT NULL,
+    qualname     TEXT NOT NULL,
+    path         TEXT NOT NULL,
+    start_line   INTEGER NOT NULL,
+    end_line     INTEGER NOT NULL,
+    signature    TEXT NOT NULL,
+    docstring    TEXT NOT NULL,
+    content_hash TEXT NOT NULL,
+    parent       TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS symbols_name ON symbols (name);
+CREATE INDEX IF NOT EXISTS symbols_path ON symbols (path);
+CREATE TABLE IF NOT EXISTS edges (
+    source     TEXT NOT NULL,
+    target     TEXT NOT NULL,
+    kind       TEXT NOT NULL,
+    confidence TEXT NOT NULL,
+    line       INTEGER NOT NULL,
+    PRIMARY KEY (source, target, kind)
+);
+CREATE INDEX IF NOT EXISTS edges_target ON edges (target, kind);
+-- Kept apart from symbols so rebuilding the map does not throw explanations away.
+-- An explanation is current while its content_hash matches the symbol's.
+CREATE TABLE IF NOT EXISTS explanations (
+    symbol_id    TEXT PRIMARY KEY,
+    content_hash TEXT NOT NULL,
+    model        TEXT NOT NULL,
+    prompt_version INTEGER NOT NULL,
+    summary      TEXT NOT NULL,
+    details      TEXT NOT NULL,
+    side_effects TEXT NOT NULL,
+    created_at   TEXT NOT NULL
+);
+-- The vector of a symbol's search text. Current while text_hash matches that text.
+CREATE TABLE IF NOT EXISTS embeddings (
+    symbol_id TEXT PRIMARY KEY,
+    text_hash TEXT NOT NULL,
+    model     TEXT NOT NULL,
+    vector    BLOB NOT NULL
+);
+"""
+
+_SYMBOL_COLUMNS = (
+    "id", "kind", "name", "qualname", "path", "start_line", "end_line",
+    "signature", "docstring", "content_hash", "parent",
+)
+EXPLANATION_FIELDS = ("summary", "details", "side_effects")
+
+
+class SymbolGraphStore:
+    """The symbol map of one codebase in a single SQLite file."""
+
+    def __init__(self, db_path: str | Path):
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        with self._connect() as conn:
+            if conn.execute("PRAGMA user_version").fetchone()[0] != _SCHEMA_VERSION:
+                for table in _TABLES:
+                    conn.execute(f"DROP TABLE IF EXISTS {table}")
+            conn.executescript(_SCHEMA)
+            conn.execute(f"PRAGMA user_version = {_SCHEMA_VERSION}")
+
+    @contextmanager
+    def _connect(self) -> Iterator[sqlite3.Connection]:
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        try:
+            with conn:  # one transaction: commit on success, roll back on error
+                yield conn
+        finally:
+            conn.close()
+
+    # -- files -------------------------------------------------------------
+
+    def file_states(self) -> Dict[str, tuple[str, int]]:
+        """path -> (content hash, extractor version) of every stored file."""
+        with self._connect() as conn:
+            rows = conn.execute("SELECT path, content_hash, extractor_version FROM files").fetchall()
+        return {row["path"]: (row["content_hash"], row["extractor_version"]) for row in rows}
+
+    def save_extracts(self, extracts: Iterable[Dict[str, Any]], extractor_version: int) -> None:
+        rows = [
+            (extract["path"], extract["content_hash"], extractor_version, json.dumps(extract))
+            for extract in extracts
+        ]
+        with self._connect() as conn:
+            conn.executemany("INSERT OR REPLACE INTO files VALUES (?, ?, ?, ?)", rows)
+
+    def delete_files(self, paths: Iterable[str]) -> None:
+        with self._connect() as conn:
+            conn.executemany("DELETE FROM files WHERE path = ?", [(path,) for path in paths])
+
+    def load_extracts(self) -> List[Dict[str, Any]]:
+        with self._connect() as conn:
+            rows = conn.execute("SELECT extract_json FROM files ORDER BY path").fetchall()
+        return [json.loads(row["extract_json"]) for row in rows]
+
+    # -- graph -------------------------------------------------------------
+
+    def replace_graph(self, symbols: Iterable[Symbol], edges: Iterable[Edge]) -> None:
+        """Swap in a freshly resolved map and drop explanations of symbols that no longer exist."""
+        symbol_rows = [tuple(getattr(symbol, column) for column in _SYMBOL_COLUMNS) for symbol in symbols]
+        edge_rows = [(edge.source, edge.target, edge.kind, edge.confidence, edge.line) for edge in edges]
+        with self._connect() as conn:
+            conn.execute("DELETE FROM symbols")
+            conn.execute("DELETE FROM edges")
+            conn.executemany(f"INSERT INTO symbols VALUES ({', '.join('?' * len(_SYMBOL_COLUMNS))})", symbol_rows)
+            conn.executemany("INSERT INTO edges VALUES (?, ?, ?, ?, ?)", edge_rows)
+            conn.execute("DELETE FROM explanations WHERE symbol_id NOT IN (SELECT id FROM symbols)")
+            conn.execute("DELETE FROM embeddings WHERE symbol_id NOT IN (SELECT id FROM symbols)")
+
+    def symbols(self) -> List[Symbol]:
+        with self._connect() as conn:
+            rows = conn.execute(f"SELECT {', '.join(_SYMBOL_COLUMNS)} FROM symbols ORDER BY path, start_line").fetchall()
+        return [Symbol(**dict(row)) for row in rows]
+
+    def find_symbols(self, name: str) -> List[Symbol]:
+        """Symbols whose id, qualified name or name equals `name`."""
+        with self._connect() as conn:
+            rows = conn.execute(
+                f"SELECT {', '.join(_SYMBOL_COLUMNS)} FROM symbols "
+                "WHERE id = ? OR qualname = ? OR name = ? ORDER BY path, start_line",
+                (name, name, name),
+            ).fetchall()
+        return [Symbol(**dict(row)) for row in rows]
+
+    def edges(self) -> List[Edge]:
+        with self._connect() as conn:
+            rows = conn.execute("SELECT source, target, kind, confidence, line FROM edges").fetchall()
+        return [Edge(**dict(row)) for row in rows]
+
+    def edges_from(self, symbol_id: str) -> List[Edge]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT source, target, kind, confidence, line FROM edges WHERE source = ? ORDER BY kind, target",
+                (symbol_id,),
+            ).fetchall()
+        return [Edge(**dict(row)) for row in rows]
+
+    def edges_to(self, symbol_id: str) -> List[Edge]:
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT source, target, kind, confidence, line FROM edges WHERE target = ? ORDER BY kind, source",
+                (symbol_id,),
+            ).fetchall()
+        return [Edge(**dict(row)) for row in rows]
+
+    def counts(self) -> Dict[str, Dict[str, int]]:
+        with self._connect() as conn:
+            symbols = conn.execute("SELECT kind, COUNT(*) AS n FROM symbols GROUP BY kind").fetchall()
+            edges = conn.execute(
+                "SELECT kind || ' (' || confidence || ')' AS label, COUNT(*) AS n FROM edges GROUP BY label"
+            ).fetchall()
+        return {
+            "symbols": {row["kind"]: row["n"] for row in symbols},
+            "edges": {row["label"]: row["n"] for row in edges},
+        }
+
+    # -- explanations ------------------------------------------------------
+
+    def explanations(self) -> Dict[str, Dict[str, str]]:
+        """symbol id -> explanation, current ones only."""
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT e.* FROM explanations e JOIN symbols s "
+                "ON s.id = e.symbol_id AND s.content_hash = e.content_hash"
+            ).fetchall()
+        return {row["symbol_id"]: dict(row) for row in rows}
+
+    def explanation(self, symbol_id: str) -> Optional[Dict[str, str]]:
+        return self.explanations().get(symbol_id)
+
+    def save_explanation(self, symbol: Symbol, model: str, fields: Dict[str, str], prompt_version: int = 0) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                "INSERT OR REPLACE INTO explanations VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    symbol.id,
+                    symbol.content_hash,
+                    model,
+                    prompt_version,
+                    *(str(fields.get(name, "")) for name in EXPLANATION_FIELDS),
+                    datetime.now(timezone.utc).isoformat(),
+                ),
+            )
+
+    # -- embeddings --------------------------------------------------------
+
+    def embeddings(self, model: str) -> Dict[str, tuple[str, bytes]]:
+        """symbol id -> (hash of the embedded text, vector as float32 bytes) for one embedding model."""
+        with self._connect() as conn:
+            rows = conn.execute(
+                "SELECT symbol_id, text_hash, vector FROM embeddings WHERE model = ?", (model,)
+            ).fetchall()
+        return {row["symbol_id"]: (row["text_hash"], row["vector"]) for row in rows}
+
+    def save_embeddings(self, rows: Iterable[tuple[str, str, bytes]], model: str) -> None:
+        """Store (symbol id, text hash, vector bytes) rows."""
+        with self._connect() as conn:
+            conn.executemany(
+                "INSERT OR REPLACE INTO embeddings VALUES (?, ?, ?, ?)",
+                [(symbol_id, text_hash, model, vector) for symbol_id, text_hash, vector in rows],
+            )
+
+    def reuse_explanations_from(self, other_db_path: str | Path) -> int:
+        """Copy explanations from another map for symbols whose code is identical there.
+
+        Used to take explanations back from the main map when an edit is undone,
+        so the model is not asked again. Returns how many were copied.
+        """
+        if not Path(other_db_path).is_file():
+            return 0
+        with self._connect() as conn:
+            conn.execute("ATTACH DATABASE ? AS other", (str(other_db_path),))
+            try:
+                has_table = conn.execute(
+                    "SELECT 1 FROM other.sqlite_master WHERE type = 'table' AND name = 'explanations'"
+                ).fetchone()
+                same_format = conn.execute("PRAGMA other.user_version").fetchone()[0] == _SCHEMA_VERSION
+                if not has_table or not same_format:
+                    return 0  # nothing to copy, or written by an older version of this code
+                copied = conn.execute(
+                    "INSERT OR REPLACE INTO explanations "
+                    "SELECT o.* FROM other.explanations o JOIN symbols s "
+                    "ON s.id = o.symbol_id AND s.content_hash = o.content_hash "
+                    "WHERE NOT EXISTS (SELECT 1 FROM explanations e "
+                    "WHERE e.symbol_id = o.symbol_id AND e.content_hash = o.content_hash)"
+                ).rowcount
+                conn.commit()
+                return copied
+            finally:
+                conn.execute("DETACH DATABASE other")
+
+    def copy_to(self, other_db_path: str | Path) -> None:
+        """Overwrite another database file with a consistent copy of this one."""
+        target_path = Path(other_db_path)
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        source = sqlite3.connect(self.db_path)
+        target = sqlite3.connect(target_path)
+        try:
+            source.backup(target)
+        finally:
+            target.close()
+            source.close()

gra/cli.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from gra.adapters.symbol_graph_store import EXPLANATION_FIELDS, SymbolGraphStore
+from gra.core.env import set_config_value
+from gra.core.storage_paths import code_index_dir_for, code_working_index_path_for
+from gra.pipelines.code_indexing_pipeline import IndexState, index_codebase
+from gra.pipelines.context_retrieval_pipeline import retrieve_context
+from gra.services.context_filter import ContextFilter
+from gra.services.symbol_search import SEARCH_MODES, ServiceRanker
+
+from gra.watcher import CodebaseWatcher, explanation_model_problem, install_commit_hook
+
+
+def _report(state: IndexState) -> str:
+    return json.dumps(
+        {
+            "python_files": len(state["files"]),
+            "changed": len(state["changed"]),
+            "removed": len(state["removed"]),
+            "not_valid_python_yet": state.get("skipped", []),
+            **state["counts"],
+            "explanations": state.get("explanations"),
+            "merged_into_main_map": state.get("merged", False),
+        },
+        indent=2,
+    )
+
+
+SERVER_NAME = "gra-context"
+CLAUDE_MD_LINE = (
+    "Before searching or reading files for a task, call the `get_code_context` tool to find the "
+    "code you need and understand it: where it is, what it does and how its parts connect. Then "
+    "read only the line ranges you will change. Ask again as new questions come up."
+)
+
+
+# gra setup [--api-key K]          in a codebase: save settings and register the MCP server with Claude Code
+# gra serve [--repo R]             the MCP server itself (what Claude Code runs)
+# gra install [repo]               first build with explanations, plus a git post-commit hook
+# gra watch [repo]                 keep the map current without Claude Code open
+# gra index [repo]                 update the working copy once (--explain to call the model)
+# gra commit [repo]                update the working copy and merge it into the main map
+# gra show <name> [repo]           a symbol, its explanation and its connections
+# gra query "task" ... [--repo R]  what an agent gets back for these tasks
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="gra")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    setup = commands.add_parser("setup")
+    setup.add_argument("--api-key", help="Your GRA API key, saved in ~/.config/gra/config.env.")
+    setup.add_argument("--api-url", help="The explanation service's address, if not the default.")
+    setup.add_argument("--context-filter", help='The model that leaves out noise, on GRA\'s service: "gra:default" (on with a key) or "off".')
+    setup.add_argument("--scope", choices=["local", "project"], default="local",
+                       help="local: only you in this repo. project: everyone, via .mcp.json.")
+    setup.add_argument("--claude-md", action="store_true", help="Also add a line to CLAUDE.md telling Claude to use it.")
+
+    serve = commands.add_parser("serve")
+    serve.add_argument("--repo", default=".")
+    serve.add_argument("--no-watch", action="store_true", help="Do not keep the map and explanations current.")
+
+    for name in ("install", "watch", "index", "commit"):
+        command = commands.add_parser(name)
+        command.add_argument("repo", nargs="?", default=".", help="Codebase. Defaults to the current directory.")
+        if name in ("index", "commit"):
+            command.add_argument("--explain", action="store_true", help="Explain new and changed symbols.")
+            command.add_argument("--explain-limit", type=int, default=None, help="Explain at most this many.")
+        else:
+            command.add_argument("--no-explain", action="store_true", help="Build the map only; no model calls.")
+        if name == "watch":
+            command.add_argument("--interval", type=float, default=2.0, help="Seconds between checks.")
+
+    show = commands.add_parser("show")
+    show.add_argument("name", help="Symbol id, qualified name or plain name.")
+    show.add_argument("repo", nargs="?", default=".")
+
+    query = commands.add_parser("query")
+    query.add_argument("tasks", nargs="+", help="One or more tasks, each a short sentence.")
+    query.add_argument("--repo", default=".")
+    query.add_argument("--limit", type=int, default=8, help="Symbols per task.")
+    query.add_argument("--mode", choices=SEARCH_MODES, default="both", help="How tasks are matched to symbols.")
+    query.add_argument("--no-filter", action="store_true", help="Keep what the context filter would leave out.")
+
+    args = parser.parse_args()
+
+    if args.command == "setup":
+        _setup(args)
+        return
+    if args.command == "serve":
+        from gra.mcp_server import run
+
+        run(args.repo, watch=not args.no_watch)
+        return
+    if args.command == "show":
+        _show(args.name, args.repo)
+        return
+    if args.command == "query":
+        # No watcher runs behind a one-off query, so it prepares meaning search fully itself.
+        context_filter = None if args.no_filter else ContextFilter.from_settings()
+        print(retrieve_context(args.repo, args.tasks, limit=args.limit, mode=args.mode, embed_limit=None,
+                               context_filter=context_filter, ranker=ServiceRanker.from_settings())["text"])
+        return
+
+    if args.command in ("install", "watch"):
+        explain = not args.no_explain
+        problem = explanation_model_problem() if explain else ""
+        if problem:
+            print(f"Explanations are off, building the map only. {problem}")
+            explain = False
+    else:
+        explain = args.explain
+
+    if args.command == "install":
+        print(_report(index_codebase(args.repo, explain=explain, merge=True)))
+        print(f"Map: {code_index_dir_for(args.repo)}")
+        try:
+            print(f"Commit hook: {install_commit_hook(args.repo)}")
+        except FileExistsError as exc:
+            print(f"Commit hook not installed: {exc}")
+        except subprocess.CalledProcessError:
+            print("Commit hook not installed: not a git repository.")
+    elif args.command == "watch":
+        watcher = CodebaseWatcher(args.repo, explain=explain)
+        print(_report(watcher.start()))
+        print(f"Watching {Path(args.repo).resolve()} (Ctrl+C to stop)")
+        try:
+            while True:
+                time.sleep(args.interval)
+                state = watcher.tick()
+                if state is not None:
+                    print(_report(state))
+        except KeyboardInterrupt:
+            pass
+    else:
+        state = index_codebase(
+            args.repo,
+            explain=explain,
+            explain_limit=args.explain_limit,
+            merge=args.command == "commit",
+        )
+        print(_report(state))
+
+
+def _setup(args: argparse.Namespace) -> None:
+    for name, value in (("GRA_API_KEY", args.api_key), ("GRA_API_URL", args.api_url),
+                        ("CONTEXT_FILTER", args.context_filter)):
+        if value:
+            print(f"Saved {name} in {set_config_value(name, value)}")
+    problem = explanation_model_problem()
+    if problem:
+        print(f"Explanations will be off until this is fixed: {problem}")
+
+    repo = Path.cwd()
+    server_command = [sys.executable, "-m", "gra", "serve", "--repo", str(repo)]
+    register = ["claude", "mcp", "add", SERVER_NAME, "-s", args.scope, "--", *server_command]
+    if shutil.which("claude") is None:
+        print("Claude Code was not found. Register the server yourself:\n  " + " ".join(register))
+    else:
+        result = subprocess.run(register, capture_output=True, text=True)
+        output = (result.stdout + result.stderr).strip()
+        if result.returncode == 0:
+            print(f"Registered {SERVER_NAME} with Claude Code for {repo} ({args.scope}).")
+        elif "already exists" in output:
+            print(f"{SERVER_NAME} is already registered here. To redo it: claude mcp remove {SERVER_NAME} -s {args.scope}")
+        else:
+            raise SystemExit(f"Registering with Claude Code failed:\n{output}")
+
+    if args.claude_md:
+        claude_md = repo / "CLAUDE.md"
+        existing = claude_md.read_text(encoding="utf-8") if claude_md.exists() else ""
+        if "get_code_context" not in existing:
+            claude_md.write_text(existing + ("\n" if existing and not existing.endswith("\n") else "")
+                                 + ("\n" if existing else "") + CLAUDE_MD_LINE + "\n", encoding="utf-8")
+            print(f"Added a line to {claude_md}")
+    print("Start a new Claude Code session here. The map builds in the background on its first start.")
+
+
+def _show(name: str, repo: str) -> None:
+    db_path = code_working_index_path_for(repo)
+    store = SymbolGraphStore(db_path)
+    matches = store.find_symbols(name)
+    if not matches:
+        raise SystemExit(f"No symbol named {name!r} in {db_path}")
+    for symbol in matches:
+        print(f"{symbol.kind} {symbol.id}  ({symbol.path}:{symbol.start_line}-{symbol.end_line})")
+        if symbol.signature:
+            print(f"  {symbol.signature}")
+        explanation = store.explanation(symbol.id)
+        for field in EXPLANATION_FIELDS if explanation else ():
+            if explanation[field]:
+                print(f"  {field}: {explanation[field]}")
+        for edge in store.edges_from(symbol.id):
+            print(f"  -> {edge.kind:<10} {edge.target}  [{edge.confidence}]")
+        for edge in store.edges_to(symbol.id):
+            print(f"  <- {edge.kind:<10} {edge.source}  [{edge.confidence}]")
+        print()
+
+
+if __name__ == "__main__":
+    main()

gra/core/embedding_models.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Dict, List
+
+from langchain.embeddings import init_embeddings
+from langchain_core.embeddings import Embeddings
+
+from gra.core.env import get_env_value
+
+# The model that turns text into vectors for meaning-based search, named
+# "<provider>:<model>". The default runs on this machine: no key, no per-query
+# cost, and the code never leaves it.
+DEFAULT_EMBEDDING_MODEL = "fastembed:sentence-transformers/all-MiniLM-L6-v2"
+
+_LOADED: Dict[str, Embeddings] = {}
+
+
+class FastEmbedEmbeddings(Embeddings):
+    """Small ONNX embedding models through fastembed: no PyTorch, a ~100 MB download on first use."""
+
+    def __init__(self, model: str):
+        from fastembed import TextEmbedding
+
+        self._model = TextEmbedding(model_name=model)
+
+    # Memory grows steeply with the batch: 256 texts at once ran a 4 GB machine
+    # out of memory, 16 stay well under 1 GB at about the same speed.
+    BATCH_SIZE = 16
+
+    def embed_documents(self, texts: List[str]) -> List[List[float]]:
+        return [vector.tolist() for vector in self._model.embed(texts, batch_size=self.BATCH_SIZE)]
+
+    def embed_query(self, text: str) -> List[float]:
+        # query_embed adds the prefix a model expects on questions, where it has one.
+        return next(iter(self._model.query_embed(text))).tolist()
+
+
+def embedding_model_name() -> str:
+    return get_env_value("EMBEDDING_MODEL", DEFAULT_EMBEDDING_MODEL).strip() or DEFAULT_EMBEDDING_MODEL
+
+
+def get_embedding_model(name: str) -> Embeddings:
+    """Build the embedding model once per process; a local model takes seconds to load."""
+    if name not in _LOADED:
+        provider, _, model = name.partition(":")
+        _LOADED[name] = FastEmbedEmbeddings(model) if provider == "fastembed" else init_embeddings(name)
+    return _LOADED[name]

gra/core/env.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def config_dir() -> Path:
+    """Where GRA's settings file lives: $XDG_CONFIG_HOME/gra, else ~/.config/gra."""
+    base = os.getenv("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(base) / "gra"
+
+
+def config_path() -> Path:
+    """The settings file `gra setup` writes: KEY=value lines."""
+    return config_dir() / "config.env"
+
+
+def get_env_value(
+    name: str,
+    default: str = "",
+    *,
+    env_path: str | Path | None = None,
+) -> str:
+    """A setting: the process environment first, then the settings file, then `default`."""
+    value = os.getenv(name)
+    if value is not None:
+        return value
+
+    env_path = Path(env_path) if env_path is not None else config_path()
+    if not env_path.exists():
+        return default
+
+    for raw_line in env_path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, raw_value = line.split("=", 1)
+        if key.strip() != name:
+            continue
+        return raw_value.strip().strip("'\"")
+    return default
+
+
+def set_config_value(name: str, value: str) -> Path:
+    """Write one setting into the settings file, keeping the others."""
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = path.read_text(encoding="utf-8").splitlines() if path.exists() else []
+    kept = [line for line in lines if line.split("=", 1)[0].strip() != name]
+    path.write_text("\n".join([*kept, f"{name}={value}"]) + "\n", encoding="utf-8")
+    path.chmod(0o600)  # it can hold an API key
+    return path

gra/core/file_locks.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import fcntl
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+
+@contextmanager
+def exclusive_file_lock(lock_path: str | Path) -> Iterator[None]:
+    """Hold the lock file for the duration of the block; other holders, in any process, wait."""
+    path = Path(lock_path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a+", encoding="utf-8") as handle:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)

gra/core/storage_paths.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+
+from gra.core.env import get_env_value
+
+
+# Everything GRA writes lives under one data folder, outside the codebases it indexes:
+#
+#   <DATA_ROOT>/
+#     code_index/<repo>-<id>/   symbol map of one indexed codebase: working.sqlite follows the files
+#                               as they are edited, symbols.sqlite is the map as of the last commit;
+#                               work_log.sqlite is what was done there, across sessions
+#
+# DATA_ROOT is GRA_DATA_DIR when set, else $XDG_DATA_HOME/gra, else ~/.local/share/gra.
+DATA_ROOT = Path(
+    get_env_value("GRA_DATA_DIR")
+    or Path(os.getenv("XDG_DATA_HOME") or Path.home() / ".local" / "share") / "gra"
+).expanduser()
+CODE_INDEX_DIR = DATA_ROOT / "code_index"
+
+
+def code_index_dir_for(repo_root: str | Path) -> Path:
+    """Where the symbol map of a codebase lives, keyed by the codebase's absolute path."""
+    root = Path(repo_root).resolve()
+    digest = hashlib.sha1(str(root).encode("utf-8")).hexdigest()[:8]
+    return CODE_INDEX_DIR / f"{root.name}-{digest}"
+
+
+def code_index_path_for(repo_root: str | Path) -> Path:
+    """The main map: the codebase as of the last commit."""
+    return code_index_dir_for(repo_root) / "symbols.sqlite"
+
+
+def work_log_path_for(repo_root: str | Path) -> Path:
+    """The work log: what Claude did for each task GRA answered, across sessions."""
+    return code_index_dir_for(repo_root) / "work_log.sqlite"
+
+
+def code_working_index_path_for(repo_root: str | Path) -> Path:
+    """The working copy of the map: the codebase as it is on disk right now."""
+    return code_index_dir_for(repo_root) / "working.sqlite"