heimdall-code 0.1.0__py3-none-any.whl

heimdall/index.py

@@ -0,0 +1,435 @@
+# Copyright 2026 The Heimdall Authors
+# SPDX-License-Identifier: Apache-2.0
+"""The indexing pipeline: discover -> parse -> resolve -> store.
+
+Four passes, run once per repository. Everything a query needs is precomputed here
+so the read side stays a single SQL statement.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from concurrent.futures import ProcessPoolExecutor
+from concurrent.futures.process import BrokenProcessPool
+from pathlib import Path
+
+from .graph import Graph
+from .parse import EXT_LANG, FileParse, parse_source
+
+MAX_BYTES = 2_000_000
+SKIP_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    "node_modules",
+    "venv",
+    ".venv",
+    "__pycache__",
+    ".mypy_cache",
+    ".ruff_cache",
+    ".pytest_cache",
+    "dist",
+    "build",
+    "target",
+    ".tox",
+    ".idea",
+    ".gradle",
+    "site-packages",
+    ".next",
+    ".terraform",
+    "vendor",
+    "coverage-report",
+}
+# package roots and index files that do not contribute a module name segment
+_INDEX_STEMS = {"__init__", "index", "mod", "lib", "main"}
+_SRC_ROOTS = {"src", "lib", "app", "pkg", "internal", "source"}
+# receivers that name the enclosing class rather than another object
+SELF_NAMES = {"self", "this", "cls", "me", "Self"}
+
+
+# ---------------------------------------------------------------- pass 1: discover
+
+
+def discover(root: Path) -> list[Path]:
+    """Tracked + untracked-but-not-ignored files when git knows; a plain walk otherwise."""
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(root), "ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+            capture_output=True,
+            timeout=120,
+            check=True,
+        ).stdout
+        paths = [root / p.decode() for p in out.split(b"\0") if p]
+        # a superproject lists each submodule as one directory entry, so a repo-of-repos
+        # would index to nothing at all. --recurse-submodules only works with --cached,
+        # hence the second call rather than a flag on the first.
+        if any(p.is_dir() for p in paths):
+            out = subprocess.run(
+                ["git", "-C", str(root), "ls-files", "-z", "--cached", "--recurse-submodules"],
+                capture_output=True,
+                timeout=120,
+                check=True,
+            ).stdout
+            paths += [root / p.decode() for p in out.split(b"\0") if p]
+    except (subprocess.SubprocessError, OSError):
+        paths = []
+        for dirpath, dirnames, filenames in os.walk(root):
+            dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")]
+            paths.extend(Path(dirpath) / f for f in filenames)
+
+    keep = []
+    for p in paths:
+        if p.suffix not in EXT_LANG or any(part in SKIP_DIRS for part in p.parts):
+            continue
+        try:
+            if p.is_file() and p.stat().st_size <= MAX_BYTES:
+                keep.append(p)
+        except OSError:
+            continue
+    return sorted(set(keep))
+
+
+# ---------------------------------------------------------------- pass 2: parse
+
+
+def _parse_one(args: tuple[str, str]) -> FileParse:
+    rel, abspath = args
+    lang = EXT_LANG[Path(rel).suffix]
+    try:
+        src = Path(abspath).read_bytes()
+    except OSError as exc:
+        fp = FileParse(path=rel, lang=lang)
+        fp.error = str(exc)
+        return fp
+    return parse_source(rel, lang, src)
+
+
+def parse_all(root: Path, files: list[Path], jobs: int, log) -> list[FileParse]:
+    work = [(str(p.relative_to(root)), str(p)) for p in files]
+    if jobs == 1:
+        return [_parse_one(w) for w in work]
+    results: list[FileParse] = []
+    try:
+        with ProcessPoolExecutor(max_workers=jobs) as pool:
+            for i, fp in enumerate(pool.map(_parse_one, work, chunksize=16), 1):
+                results.append(fp)
+                if i % 200 == 0:
+                    log(f"  parsed {i}/{len(work)} files")
+    except BrokenProcessPool:
+        # a REPL, a notebook or a frozen binary: the workers cannot import __main__
+        log("  worker pool unavailable, parsing in this process")
+        return [_parse_one(w) for w in work]
+    return results
+
+
+# ---------------------------------------------------------------- pass 3: resolve
+
+
+def _module_keys(rel: str) -> list[str]:
+    """Every dotted suffix a file could be imported as, longest first."""
+    p = Path(rel)
+    dirs = list(p.parts[:-1])
+    # `main.py` is both `pkg.main` (python) and `pkg` (js/go entry point); register both,
+    # named form first so the longer, more specific import wins.
+    forms = [[*dirs, p.stem]] + ([dirs] if p.stem in _INDEX_STEMS else [])
+    keys: list[str] = []
+    for parts in forms:
+        parts = list(parts)
+        while parts and parts[0] in _SRC_ROOTS:
+            parts.pop(0)
+        keys += [".".join(parts[i:]) for i in range(len(parts))]
+    return keys
+
+
+_IMPORT_EXTS = (".js", ".ts", ".jsx", ".tsx", ".py", ".h", ".hpp", ".mjs", ".cjs")
+
+
+def _strip_ext(mod: str) -> str:
+    for ext in _IMPORT_EXTS:
+        if mod.endswith(ext):
+            return mod[: -len(ext)]
+    return mod
+
+
+def _normalize_import(mod: str) -> str:
+    mod = _strip_ext(mod.strip().strip("\"'<>"))
+    return mod.replace("::", ".").replace("/", ".").replace("\\", ".").strip(".")
+
+
+def _relative_target(from_path: str, mod: str) -> str | None:
+    """`./store` and `from ..pkg.x import y` are relative to the importing file's
+    directory. Returns a repo-relative path stem, or None if the import is absolute."""
+    mod = _strip_ext(mod.strip().strip("\"'<>"))
+    ups = len(mod) - len(mod.lstrip("."))
+    if ups == 0:
+        return None
+    rest = mod[ups:].lstrip("/").replace(".", "/")
+    base = os.path.dirname(from_path)
+    for _ in range(ups - 1):
+        base = os.path.dirname(base)
+    return os.path.normpath(os.path.join(base, rest)).replace(os.sep, "/")
+
+
+def build(root: Path, db_path: Path, jobs: int = 0, log=lambda m: None) -> dict:
+    t0 = time.time()
+    # process_cpu_count respects the affinity mask, but only exists on 3.13+
+    count = getattr(os, "process_cpu_count", os.cpu_count)
+    jobs = jobs or min(32, count() or 4)
+
+    log("pass 1/4  discovering files")
+    files = discover(root)
+    log(f"  {len(files)} source files")
+    if not files:
+        raise SystemExit(f"no supported source files under {root}")
+
+    log(f"pass 2/4  parsing ({jobs} workers)")
+    parsed = parse_all(root, files, jobs, log)
+
+    log("pass 3/4  building graph")
+    g = Graph.open(db_path)
+    # the index lives inside the repo it describes; keep it out of the repo's git status
+    (db_path.parent / ".gitignore").write_text("*\n")
+    g.db.executescript("DELETE FROM edge; DELETE FROM node; DELETE FROM meta;")
+
+    # --- folder + file nodes
+    nodes: list[dict] = []
+    folders: set[str] = set()
+    for fp in parsed:
+        d = Path(fp.path).parent
+        while str(d) not in (".", "/"):
+            folders.add(str(d))
+            d = d.parent
+    for f in sorted(folders):
+        nodes.append(
+            dict(kind="Folder", name=Path(f).name, qname=f, path=f, line=0, end_line=0, lang=None, signature="")
+        )
+    for fp in parsed:
+        nodes.append(
+            dict(
+                kind="File",
+                name=Path(fp.path).name,
+                qname=fp.path,
+                path=fp.path,
+                line=0,
+                end_line=0,
+                lang=fp.lang,
+                signature="",
+            )
+        )
+        for s in fp.symbols:
+            nodes.append(
+                dict(
+                    kind=s.kind,
+                    name=s.name,
+                    qname=s.qname,
+                    path=fp.path,
+                    line=s.line,
+                    end_line=s.end_line,
+                    lang=fp.lang,
+                    signature=s.signature,
+                )
+            )
+    g.add_nodes(nodes)
+    ids = g.ids_by_qname()
+
+    edges: list[tuple] = []
+    # --- containment
+    for f in folders:
+        parent = str(Path(f).parent)
+        if parent in ids:
+            edges.append((ids[parent], ids[f], "CONTAINS", 1.0, 0))
+    for fp in parsed:
+        parent = str(Path(fp.path).parent)
+        if parent in ids:
+            edges.append((ids[parent], ids[fp.path], "CONTAINS", 1.0, 0))
+        for s in fp.symbols:
+            src = ids.get(s.parent) if s.parent else ids.get(fp.path)
+            if src and s.qname in ids:
+                edges.append((src, ids[s.qname], "DEFINES", 1.0, s.line))
+
+    # --- imports: relative paths resolve against the importing file, absolute ones by
+    #     longest dotted suffix
+    module_index: dict[str, int] = {}
+    path_index: dict[str, int] = {}
+    for fp in parsed:
+        fid = ids[fp.path]
+        for key in _module_keys(fp.path):
+            module_index.setdefault(key, fid)
+        stem = fp.path.rsplit(".", 1)[0]
+        path_index.setdefault(stem, fid)
+        if Path(fp.path).stem in _INDEX_STEMS:
+            path_index.setdefault(str(Path(fp.path).parent), fid)
+    imported: dict[str, set[str]] = {}
+    # per file: lines of imports that landed on a file in this repo, so an `as` rename
+    # from a third-party module is not mistaken for a local symbol
+    inside: dict[str, set[int]] = {}
+    # per file, per enclosing symbol (None = module level): the files it imports
+    scoped: dict[str, dict[str | None, set[str]]] = {}
+    # per file: the receiver name a module was imported under -> that module's path,
+    # so `utils.helper()` resolves to utils.py instead of every `helper` in the repo.
+    aliases: dict[str, dict[str, str]] = {}
+    path_by_id = {fid: fp.path for fp in parsed if (fid := ids[fp.path])}
+    for fp in parsed:
+        fid = ids[fp.path]
+        seen = imported.setdefault(fp.path, set())
+        here_lines = inside.setdefault(fp.path, set())
+        alias = aliases.setdefault(fp.path, {})
+        scopes = scoped.setdefault(fp.path, {})
+        for mod, line, scope in fp.imports:
+            rel = _relative_target(fp.path, mod)
+            if rel is not None:
+                target = path_index.get(rel)
+                if target is not None and target != fid:
+                    edges.append((fid, target, "IMPORTS", 1.0, line))
+                    seen.add(path_by_id[target])
+                    here_lines.add(line)
+                    scopes.setdefault(scope, set()).add(path_by_id[target])
+                    alias[rel.rsplit("/", 1)[-1]] = path_by_id[target]
+                continue
+            key = _normalize_import(mod)
+            while key:
+                target = module_index.get(key)
+                if target is not None and target != fid:
+                    edges.append((fid, target, "IMPORTS", 1.0, line))
+                    seen.add(path_by_id[target])
+                    here_lines.add(line)
+                    scopes.setdefault(scope, set()).add(path_by_id[target])
+                    alias[key.rsplit(".", 1)[-1]] = path_by_id[target]
+                    break
+                key = key.split(".", 1)[1] if "." in key else ""
+
+    # --- name index for call/heritage resolution
+    by_name: dict[str, list[tuple[int, str, str, str, str]]] = {}
+    for fp in parsed:
+        for sym in fp.symbols:
+            if sym.kind in ("Function", "Method", "Class", "Interface") and sym.qname in ids:
+                by_name.setdefault(sym.name, []).append((ids[sym.qname], fp.path, sym.kind, sym.qname, fp.lang))
+
+    # --- heritage
+    for fp in parsed:
+        for cls_qname, base in fp.heritage:
+            src = ids.get(cls_qname)
+            if src is None:
+                continue
+            ranked = _rank(by_name.get(base, ()), fp.path, imported.get(fp.path, ()), lang=fp.lang)
+            for dst, _path, _kind, conf in ranked[:1]:
+                if dst != src:
+                    edges.append((src, dst, "EXTENDS", conf, 0))
+
+    # --- calls
+    ambiguous = 0
+    for fp in parsed:
+        fid = ids[fp.path]
+        local = imported.get(fp.path, ())
+        alias = aliases.get(fp.path, {})
+        scopes = scoped.get(fp.path, {})
+        # only renames whose import resolved inside this repo: `from asyncio import run
+        # as arun` must not turn `arun()` into a call to some local `run`
+        here_lines = inside.get(fp.path, ())
+        renames = {loc: orig for loc, orig, ln in fp.renames if ln in here_lines}
+        for caller, callee, line, receiver in fp.calls:
+            src = ids.get(caller) or fid
+            # a caller with its own imports is resolved against those, not the file's:
+            # dispatchers that import a different `execute` per function are common
+            own = scopes.get(caller)
+            here = (own | scopes.get(None, set())) if own else local
+            # `from x import y as z` -- the call says `z`, the symbol is called `y`
+            if callee not in by_name and callee in renames:
+                callee = renames[callee]
+            # `self.foo()` inside a method can only mean a sibling member of that class.
+            # ponytail: own class only -- inherited members fall through to name ranking.
+            scope: tuple[str, ...] = ()
+            scope_path = None
+            if receiver in SELF_NAMES and caller and "." in caller:
+                scope = (caller.rsplit(".", 1)[0] + ".",)
+            elif receiver:
+                scope_path = alias.get(receiver) or alias.get(renames.get(receiver, ""))
+                if scope_path is None:
+                    # `OrderTable.full_name()` -- the receiver names a class, so the
+                    # target is that class's member and not every same-named method
+                    scope = _class_scopes(by_name, renames.get(receiver, receiver), fp.path, here)
+            ranked = _rank(by_name.get(callee, ()), fp.path, here, scope, scope_path, fp.lang)
+            if not ranked:
+                continue
+            if len(ranked) > 1 and ranked[0][3] < 0.7:
+                ambiguous += 1
+            for dst, _path, _kind, conf in ranked[:5]:
+                edges.append((src, dst, "CALLS", conf, line))  # a self-edge is recursion
+
+    g.add_edges(edges)
+    log("pass 4/4  building search index")
+    g.reindex_fts()
+    g.set_meta(
+        root=str(root.resolve()),
+        files=len(files),
+        indexed_at=time.strftime("%Y-%m-%dT%H:%M:%S"),
+        parse_errors=sum(1 for fp in parsed if fp.error),
+        ambiguous_calls=ambiguous,
+        seconds=round(time.time() - t0, 2),
+    )
+    g.db.commit()
+    g.db.execute("PRAGMA optimize")
+    stats = g.stats()
+    g.close()
+    log(f"done in {stats['seconds']}s")
+    return stats
+
+
+def _class_scopes(by_name, receiver: str, from_path: str, here) -> tuple[str, ...]:
+    """qname prefixes of every class the receiver could name, nearest first.
+
+    Ambiguity in the *receiver* is not ambiguity in the *call*: Django has 236 classes
+    called `Model` and exactly one of them defines `check`, so `Model.check()` still has
+    one answer. Returning every candidate and letting the member decide is what makes
+    that work; returning None the moment the name is shared threw the receiver away.
+    """
+    cands = [c for c in by_name.get(receiver, ()) if c[2] in ("Class", "Interface")]
+    ordered = sorted(cands, key=lambda c: (c[1] != from_path, c[1] not in here))
+    return tuple(c[3] + "." for c in ordered)
+
+
+def _rank(
+    candidates,
+    from_path: str,
+    imported_paths,
+    scope: tuple[str, ...] = (),
+    scope_path: str | None = None,
+    lang: str | None = None,
+) -> list[tuple]:
+    """Score call targets: a known receiver beats same file beats imported file beats a
+    unique global name; anything else is an ambiguous name match and says so."""
+    cands = list(candidates)
+    if not cands:
+        return []
+    if lang and len({c[4] for c in cands}) > 1:  # a Go `Store` is not a Python `Store`
+        cands = [c for c in cands if c[4] == lang] or cands
+    if scope:  # receiver named a class: the target is a member of one of those classes
+        in_scope = [c for c in cands if c[3].startswith(scope)]
+        if in_scope:
+            in_scope.sort(key=lambda c: (c[1] != from_path, c[1] not in imported_paths))
+            # one class with that name defines it: certain. Several do: nearest, and say so.
+            return [(c[0], c[1], c[2], 0.99 if len(in_scope) == 1 else 0.9) for c in in_scope[:1]]
+    if scope_path:  # receiver was an imported module: the target lives in that file
+        in_module = [c for c in cands if c[1] == scope_path]
+        if in_module:
+            return [(c[0], c[1], c[2], 0.9) for c in in_module[:1]]
+    imported_paths = set(imported_paths)
+    scored = []
+    for nid, path, kind, _qname, _lang in cands:
+        if path == from_path:
+            conf = 0.95
+        elif path in imported_paths:
+            conf = 0.8
+        elif len(cands) == 1:
+            conf = 0.7
+        else:
+            # ponytail: name-only fallback. Type inference on receivers would lift these;
+            # until then they are marked low-confidence and callers can filter them out.
+            conf = 0.3
+        scored.append((nid, path, kind, conf))
+    scored.sort(key=lambda x: -x[3])
+    # evidence beats a guess: once one candidate is in this file or an imported one,
+    # the name-only matches elsewhere are noise, not a shortlist
+    return [s for s in scored if s[3] >= 0.7] if scored[0][3] >= 0.7 else scored

heimdall/install.py

@@ -0,0 +1,151 @@
+# Copyright 2026 The Heimdall Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Register heimdall with a coding agent, globally or in one repo.
+
+The config files are written here rather than shelled out to `claude mcp add` /
+`codex mcp add`, so `heimdall install codex` works on a machine that only has Claude,
+and so the whole thing is testable against a fake home directory.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+import tomllib
+from pathlib import Path
+
+
+def _skill_text() -> str:
+    """Shipped inside the wheel; read from the repo when running off a checkout."""
+    here = Path(__file__).resolve()
+    for p in (here.with_name("SKILL.md"), here.parents[1] / "skills" / "heimdall" / "SKILL.md"):
+        if p.exists():
+            return p.read_text(encoding="utf-8")
+    raise SystemExit("SKILL.md is missing from this install")
+
+
+def _ephemeral(exe: Path) -> bool:
+    """`uvx` runs out of uv's cache, which uv garbage-collects: a config pointing in
+    there rots. `uv tool install` lives under ~/.local/share and does not.
+    """
+    # the defaults stay in the list even when UV_CACHE_DIR is set: this shell's setting
+    # says nothing about where the binary being inspected was unpacked
+    caches = [Path.home() / ".cache" / "uv", Path.home() / "Library" / "Caches" / "uv"]
+    if "UV_CACHE_DIR" in os.environ:
+        caches.append(Path(os.environ["UV_CACHE_DIR"]))
+    return any(exe.is_relative_to(c) for c in caches)
+
+
+def mcp_command() -> list[str]:
+    """What the agent should spawn to get an MCP server.
+
+    The copy of heimdall running this command, if it has a durable home -- not whatever
+    `heimdall` happens to be first on *this shell's* PATH. Otherwise `uvx`, which costs a
+    resolve per start but survives.
+    """
+    name = "heimdall.exe" if sys.platform == "win32" else "heimdall"
+    exe = Path(sys.executable).with_name(name)
+    if not exe.exists():
+        exe = Path(shutil.which(name) or "/nonexistent")
+    if exe.exists() and not _ephemeral(exe.resolve()):
+        return [str(exe), "mcp"]
+    return ["uvx", "--from", "heimdall-code", "heimdall", "mcp"]
+
+
+def _write(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(text, encoding="utf-8")
+    os.replace(tmp, path)  # never leave a half-written config behind
+
+
+def _json_mcp(path: Path, cmd: list[str]) -> str:
+    data = {}
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except ValueError as exc:
+            return f"! {path}: not valid JSON ({exc}) -- left alone"
+    data.setdefault("mcpServers", {})["heimdall"] = {"command": cmd[0], "args": cmd[1:]}
+    _write(path, json.dumps(data, indent=2) + "\n")
+    return f"+ MCP server -> {path}"
+
+
+def _toml_mcp(path: Path, cmd: list[str]) -> str:
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    try:
+        existing = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        return f"! {path}: not valid TOML ({exc}) -- left alone"
+    if "heimdall" in existing.get("mcp_servers", {}):
+        return f"= MCP server already in {path}"
+    # ponytail: append-only, because the stdlib reads TOML and does not write it. An
+    # existing entry is reported rather than rewritten -- edit it or delete it by hand.
+    args = ", ".join(json.dumps(a) for a in cmd[1:])
+    section = f"[mcp_servers.heimdall]\ncommand = {json.dumps(cmd[0])}\nargs = [{args}]\n"
+    _write(path, (f"{text.rstrip()}\n\n{section}" if text.strip() else section))
+    return f"+ MCP server -> {path}"
+
+
+def _skill(path: Path) -> str:
+    _write(path, _skill_text())
+    return f"+ CLI skill  -> {path}"
+
+
+# agent -> (global mcp, project mcp, global skill dir, project skill dir). Claude reads
+# ~/.claude.json and ./.mcp.json; Codex reads ~/.codex/config.toml and, for a trusted
+# project, ./.codex/config.toml. Skills follow each tool's documented directory.
+TARGETS = {
+    "claude": (".claude.json", ".mcp.json", ".claude/skills", ".claude/skills"),
+    "codex": (".codex/config.toml", ".codex/config.toml", ".agents/skills", ".agents/skills"),
+}
+
+
+def install(
+    agent: str, *, project: bool = False, cli: bool = False, root: Path | None = None, home: Path | None = None
+) -> list[str]:
+    """Write one agent's config. Returns a line per file touched."""
+    root = (root or Path.cwd()).resolve()
+    home = home or Path.home()
+    base = root if project else home
+    out = []
+    for a in ["claude", "codex"] if agent == "all" else [agent]:
+        gm, pm, gs, ps = TARGETS[a]
+        if cli:
+            out.append(_skill(base / (ps if project else gs) / "heimdall" / "SKILL.md"))
+        else:
+            path = base / (pm if project else gm)
+            out.append((_toml_mcp if path.suffix == ".toml" else _json_mcp)(path, mcp_command()))
+    return out
+
+
+if __name__ == "__main__":  # self-check: heimdall install, against a fake home
+    import tempfile
+
+    with tempfile.TemporaryDirectory() as td:
+        h, r = Path(td) / "home", Path(td) / "repo"
+        (h / ".codex").mkdir(parents=True)
+        (h / ".codex" / "config.toml").write_text('model = "gpt-5"\n')
+        print(*install("all", home=h, root=r), sep="\n")
+        print(*install("all", project=True, home=h, root=r), sep="\n")
+        print(*install("claude", cli=True, home=h, root=r), sep="\n")
+
+        cfg = json.loads((h / ".claude.json").read_text())
+        assert cfg["mcpServers"]["heimdall"]["args"][-1] == "mcp", cfg
+        codex = tomllib.loads((h / ".codex" / "config.toml").read_text())
+        assert codex["model"] == "gpt-5", "clobbered the user's own settings"
+        assert codex["mcp_servers"]["heimdall"]["args"][-1] == "mcp", codex
+        assert json.loads((r / ".mcp.json").read_text())["mcpServers"]["heimdall"]
+        assert tomllib.loads((r / ".codex" / "config.toml").read_text())["mcp_servers"]["heimdall"]
+        assert "heimdall index" in (h / ".claude/skills/heimdall/SKILL.md").read_text()
+        # a throwaway uvx venv must not be written into a config; a uv tool install must
+        assert _ephemeral(Path.home() / ".cache/uv/environments-v2/x/bin/heimdall")
+        assert not _ephemeral(Path.home() / ".local/share/uv/tools/heimdall-code/bin/heimdall")
+        # rerunning is idempotent, and a corrupt file is reported, not overwritten
+        assert install("claude", home=h, root=r) == install("claude", home=h, root=r)
+        (h / ".claude.json").write_text("{not json")
+        assert install("claude", home=h, root=r)[0].startswith("!")
+        assert (h / ".claude.json").read_text() == "{not json"
+    print("ok", file=sys.stderr)