codetherapy 0.1.0__py3-none-any.whl

codetherapy/context.py

@@ -0,0 +1,119 @@
+"""Fast, voice-sized context about a project, built from files, git and session logs (no AI calls)."""
+from __future__ import annotations
+
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+from codetherapy import notes
+from codetherapy.projects import Project, file_mtime
+from codetherapy.sessions import SessionSummary, summarize
+from codetherapy.textutil import clip
+
+MAX_BRIEF = 6000
+OVERVIEW_CHARS = 1500
+TRIM_MARK = "\n(trimmed)"
+GIT_TIMEOUT_SECONDS = 5.0
+
+
+def run_git(path: Path, *args: str) -> str | None:
+    try:
+        result = subprocess.run(["git", "--no-optional-locks", "-C", str(path), *args], capture_output=True, timeout=GIT_TIMEOUT_SECONDS)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    return result.stdout.decode("utf-8", errors="replace").strip()
+
+
+def overview(path: Path) -> str:
+    for name in ("CLAUDE.md", "README.md"):
+        file = path / name
+        if file.is_file():
+            text = file.read_text(encoding="utf-8", errors="replace").strip()
+            if text:
+                return f"From {name}:\n{clip(text, OVERVIEW_CHARS)}"
+    return ""
+
+
+def git_summary(path: Path, since_days: int | None = None) -> str:
+    branch = run_git(path, "rev-parse", "--abbrev-ref", "HEAD")
+    if branch is None:
+        return ""
+    status = run_git(path, "status", "--porcelain") or ""
+    changed = sum(1 for line in status.splitlines() if line.strip())
+    state = "clean" if changed == 0 else f"{changed} uncommitted file(s)"
+    log_args = ["log", "--date=short", "--pretty=format:%h %ad %s"]
+    log_args.append(f"--since={since_days} days ago" if since_days else "-10")
+    log = run_git(path, *log_args) or "(no commits in range)"
+    return f"Branch: {branch} ({state})\nCommits:\n{log}"
+
+
+def _when(moment: datetime | None) -> str:
+    return moment.astimezone().strftime("%Y-%m-%d") if moment else "unknown date"
+
+
+def _session_line(s: SessionSummary, all_prompts: bool = False) -> str:
+    line = f"- {_when(s.ended)}: {s.title or '(untitled session)'}"
+    shown = s.prompts if all_prompts else s.prompts[:1]
+    if shown:
+        line += " — asked: " + " / ".join(f'"{p}"' for p in shown)
+    return line
+
+
+def _summaries(files: tuple[Path, ...] | list[Path]) -> list[SessionSummary]:
+    out = []
+    for file in files:
+        try:
+            out.append(summarize(file))
+        except OSError:
+            continue
+    return out
+
+
+def assemble(header: str, sections: list[tuple[str, str]], limit: int) -> str:
+    """Render markdown sections, trimming the longest bodies until the whole fits in limit."""
+
+    def render(secs: list[tuple[str, str]]) -> str:
+        return "\n\n".join([header, *(f"## {title}\n{body}" for title, body in secs)])
+
+    secs = list(sections)
+    for _ in range(2 * len(secs)):
+        overflow = len(render(secs)) - limit
+        if overflow <= 0:
+            break
+        i = max(range(len(secs)), key=lambda j: len(secs[j][1]))
+        title, body = secs[i]
+        keep = max(0, len(body) - overflow - len(TRIM_MARK))
+        secs[i] = (title, body[:keep].rstrip() + TRIM_MARK)
+    return render(secs)[:limit]
+
+
+def brief(project: Project) -> str:
+    header = f"# {project.name}\nPath: {project.path}\nLast active: {_when(project.last_active)}"
+    sections: list[tuple[str, str]] = []
+    if not project.exists:
+        header += "\nNote: the project folder no longer exists on disk; only Claude Code session history is available."
+    else:
+        if text := overview(project.path):
+            sections.append(("Overview", text))
+        if text := git_summary(project.path):
+            sections.append(("Git", text))
+    sessions = _summaries(project.session_files[:5])
+    sections.append(("Recent Claude Code sessions", "\n".join(_session_line(s) for s in sessions) or "(none)"))
+    if project.exists and (open_notes := notes.recent(project.path, 15)):
+        sections.append(("Open notes (PM_NOTES.md)", "\n".join(open_notes)))
+    return assemble(header, sections, MAX_BRIEF)
+
+
+def activity(project: Project, days: int = 7) -> str:
+    days = max(1, min(int(days), 365))
+    cutoff = datetime.now().timestamp() - days * 86400
+    recent_files = [f for f in project.session_files if file_mtime(f) >= cutoff]
+    sessions = _summaries(recent_files[:20])
+    header = f"# {project.name}: activity in the last {days} day(s)"
+    sections = [("Claude Code sessions",
+                 "\n".join(_session_line(s, all_prompts=True) for s in sessions) or "(no sessions in this window)")]
+    if project.exists and (text := git_summary(project.path, since_days=days)):
+        sections.append(("Git", text))
+    return assemble(header, sections, MAX_BRIEF)

codetherapy/deep.py

@@ -0,0 +1,93 @@
+"""Deep questions: run Claude Code headless and read-only inside the project folder."""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from codetherapy import procutil
+from codetherapy.search import HOME_FOLDER_MESSAGE, SECRET_DIRS, SECRET_PATTERNS, is_home_or_above
+from codetherapy.textutil import clip
+
+TIMEOUT_SECONDS = 90.0
+MAX_ANSWER = 4000
+TOOLS = "Read,Grep,Glob"
+# Pre-approve reads only inside the project folder ("./" resolves against cwd = the project path).
+# A bare "Read" rule would pre-approve reading any file on the PC.
+ALLOWED_TOOLS = "Read(./**),Grep(./**),Glob(./**)"
+# Belt and braces: credentials and secrets stay unreadable even if a project path sits above them,
+# and the secret files search_project skips are denied inside the project too.
+SECRET_READ_RULES = (*(f"Read(**/{pattern})" for pattern in SECRET_PATTERNS),
+                     *(f"Read(**/{folder}/**)" for folder in SECRET_DIRS))
+# Home-folder secrets, in case a project path sits above them: Claude Code's own config and history,
+# SSH keys, Windows app data, and the config of Code Therapy (the connector token), ngrok (its authtoken),
+# gh, Docker, kubectl and PyPI. Targeted folders only: ~/.config and ~/Library hold harmless files too.
+HOME_READ_RULES = ("Read(~/.claude/**)", "Read(~/.claude.json)", "Read(~/.ssh/**)", "Read(~/AppData/**)",
+                   "Read(~/.config/codetherapy/**)", "Read(~/Library/Application Support/codetherapy/**)",
+                   "Read(~/.config/ngrok/**)", "Read(~/Library/Application Support/ngrok/**)",
+                   "Read(~/.config/gh/**)", "Read(~/.docker/config.json)", "Read(~/.kube/**)", "Read(~/.pypirc)")
+DISALLOWED_TOOLS = ",".join(("Bash", "Write", "Edit", "NotebookEdit", "WebFetch", "WebSearch", "Task", "Agent",
+                             *HOME_READ_RULES, *SECRET_READ_RULES))
+# Set by Claude Code in its own terminals; a child `claude` would refuse to start as a nested session.
+NESTED_SESSION_VARS = ("CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT")
+TIMEOUT_MESSAGE = "That needs a longer look than I can do live — try asking it in Claude Code directly."
+FRAMING = (
+    "You are the project manager for this codebase, answering a question the owner asked out loud. "
+    "Investigate with your read-only tools as needed, then answer in a few plain spoken sentences: "
+    "no code blocks, no tables, no long lists.\n\nQuestion: "
+)
+
+
+def default_command() -> list[str]:
+    exe = shutil.which("claude")
+    if not exe:
+        raise FileNotFoundError("Claude Code CLI ('claude') not found on PATH")
+    return [exe]
+
+
+def build_args() -> list[str]:
+    """Flags that make the headless run read-only by construction (not just by denylist)."""
+    return ["-p",
+            "--no-session-persistence",  # a lookup isn't a session: keep it out of history and briefs
+            "--tools", TOOLS,
+            "--allowedTools", ALLOWED_TOOLS,
+            "--disallowedTools", DISALLOWED_TOOLS,
+            "--permission-mode", "dontAsk",
+            "--strict-mcp-config",
+            "--disable-slash-commands",
+            "--restricted",
+            "--output-format", "text"]
+
+
+def _run(cmd: list[str], prompt: str, cwd: Path, env: dict[str, str], timeout: float):
+    """Run cmd; on timeout kill the whole process tree so inherited pipes close. Returns (code, out, err) or None on timeout."""
+    proc = subprocess.Popen(cmd, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+                            cwd=cwd, env=env, encoding="utf-8", errors="replace", **procutil.popen_group_kwargs())
+    try:
+        out, err = proc.communicate(prompt, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        procutil.kill_tree(proc)
+        return None
+    return proc.returncode, out, err
+
+
+def ask(project_path: Path, question: str, command: list[str] | None = None,
+        timeout: float = TIMEOUT_SECONDS) -> str:
+    if not project_path.is_dir():
+        return f"I can't open that project's folder anymore ({project_path})."
+    if is_home_or_above(project_path):
+        return HOME_FOLDER_MESSAGE
+    env = {k: v for k, v in os.environ.items() if k not in NESTED_SESSION_VARS}
+    try:
+        cmd = [*(command or default_command()), *build_args()]
+        result = _run(cmd, FRAMING + question.strip(), project_path, env, timeout)
+    except OSError as exc:  # includes FileNotFoundError and PermissionError
+        return f"The deep lookup isn't available: {exc}"
+    if result is None:
+        return TIMEOUT_MESSAGE
+    code, out, err = result
+    if code != 0:
+        lines = (err or out or "").strip().splitlines()
+        return f"The deep lookup failed: {lines[-1][:300]}" if lines else "The deep lookup failed."
+    return clip(out.strip() or "The deep lookup returned no answer.", MAX_ANSWER)

codetherapy/notes.py

@@ -0,0 +1,58 @@
+"""PM_NOTES.md: the one file the server writes, read by the user's next Claude Code session."""
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from codetherapy.textutil import one_line
+
+NOTES_FILE = "PM_NOTES.md"
+HEADER = "# PM Notes\n\nDecisions, to-dos and notes captured by Code Therapy.\n\n"
+LABELS = {"decision": "DECISION", "todo": "TODO", "note": "NOTE"}
+ALIASES = {
+    "to do": "todo", "to-do": "todo", "todos": "todo", "action item": "todo",
+    "decisions": "decision", "notes": "note",
+}
+
+
+def normalize_kind(kind: str) -> str:
+    key = " ".join(kind.lower().split())
+    key = ALIASES.get(key, key)
+    if key not in LABELS:
+        raise ValueError(f"kind must be one of: decision, todo, note (got {kind!r})")
+    return key
+
+
+def record(project_path: Path, kind: str, text: str, now: datetime | None = None) -> str:
+    label = LABELS[normalize_kind(kind)]
+    body = one_line(text)
+    if not body:
+        raise ValueError("note text is empty")
+    if not project_path.is_dir():
+        raise FileNotFoundError(f"project folder not found: {project_path}")
+    stamp = (now or datetime.now()).strftime("%Y-%m-%d %H:%M")
+    line = f"- [{stamp}] **{label}:** {body}"
+    path = project_path / NOTES_FILE
+    is_new = not path.exists() or path.stat().st_size == 0
+    needs_newline = not is_new and not _ends_with_newline(path)  # hand-edited file without a final newline
+    with path.open("a", encoding="utf-8", newline="\n") as f:
+        if is_new:
+            f.write(HEADER)
+        elif needs_newline:
+            f.write("\n")
+        f.write(line + "\n")
+    return line
+
+
+def _ends_with_newline(path: Path) -> bool:
+    with path.open("rb") as f:
+        f.seek(-1, 2)
+        return f.read(1) == b"\n"
+
+
+def recent(project_path: Path, n: int = 15) -> list[str]:
+    path = project_path / NOTES_FILE
+    if not path.is_file():
+        return []
+    lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+    return [line for line in lines if line.startswith("- [")][-n:]

codetherapy/procutil.py

@@ -0,0 +1,35 @@
+"""Start child processes in their own group and kill the whole tree, so inherited pipes close."""
+from __future__ import annotations
+
+import os
+import signal
+import subprocess
+import sys
+
+
+def popen_group_kwargs() -> dict:
+    if sys.platform == "win32":
+        return {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP}
+    return {"start_new_session": True}
+
+
+def kill_tree(proc: subprocess.Popen) -> None:
+    if sys.platform != "win32":
+        try:  # always: a grandchild can outlive an already-exited leader and hold the pipes
+            os.killpg(proc.pid, signal.SIGKILL)
+        except OSError:
+            pass
+    if proc.poll() is None:
+        if sys.platform == "win32":
+            try:
+                subprocess.run(["taskkill", "/PID", str(proc.pid), "/T", "/F"], capture_output=True, timeout=10)
+            except (OSError, subprocess.TimeoutExpired):
+                pass
+        try:
+            proc.kill()
+        except OSError:
+            pass
+    try:
+        proc.communicate(timeout=5)
+    except (subprocess.TimeoutExpired, ValueError, OSError):
+        pass

codetherapy/projects.py

@@ -0,0 +1,131 @@
+"""Discover Claude Code projects from session logs and resolve spoken names to them."""
+from __future__ import annotations
+
+import difflib
+import os
+import re
+import time
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Callable
+
+from codetherapy.sessions import read_cwd
+
+SCAN_TTL_SECONDS = 60.0
+MAX_CANDIDATES = 5
+
+
+@dataclass(frozen=True)
+class Project:
+    name: str
+    path: Path
+    last_active: datetime
+    session_files: tuple[Path, ...]  # newest first
+
+    @property
+    def exists(self) -> bool:
+        return self.path.is_dir()
+
+
+@dataclass(frozen=True)
+class Resolution:
+    project: Project | None
+    candidates: tuple[Project, ...] = ()
+
+
+def file_mtime(path: Path) -> float:
+    try:
+        return path.stat().st_mtime
+    except OSError:
+        return 0.0
+
+
+def _unique_names(paths: list[Path]) -> dict[Path, str]:
+    """Folder basename, or parent/basename when two projects share a basename."""
+
+    def dupes(names: dict[Path, str]) -> set[str]:
+        seen: dict[str, int] = {}
+        for n in names.values():
+            seen[n.lower()] = seen.get(n.lower(), 0) + 1
+        return {n for n, count in seen.items() if count > 1}
+
+    names = {p: p.name or str(p) for p in paths}
+    clashing = dupes(names)
+    names = {p: (f"{p.parent.name}/{p.name}" if n.lower() in clashing and p.parent.name else n) for p, n in names.items()}
+    clashing = dupes(names)
+    return {p: (str(p) if n.lower() in clashing else n) for p, n in names.items()}
+
+
+def discover(projects_dir: Path) -> list[Project]:
+    if not projects_dir.is_dir():
+        return []
+    grouped: dict[str, tuple[Path, list[Path]]] = {}
+    for folder in projects_dir.iterdir():
+        if not folder.is_dir():
+            continue
+        files = sorted(folder.glob("*.jsonl"), key=file_mtime, reverse=True)
+        # The folder name encoding is lossy; the real path is the cwd recorded in the log.
+        cwd = next((c for c in map(read_cwd, files) if c), "")
+        if not cwd:
+            continue
+        key = os.path.normcase(os.path.normpath(cwd))
+        grouped.setdefault(key, (Path(cwd), []))[1].extend(files)
+    names = _unique_names([path for path, _ in grouped.values()])
+    projects = []
+    for path, files in grouped.values():
+        files.sort(key=file_mtime, reverse=True)
+        last_active = datetime.fromtimestamp(file_mtime(files[0])).astimezone()
+        projects.append(Project(names[path], path, last_active, tuple(files)))
+    projects.sort(key=lambda p: p.last_active, reverse=True)
+    return projects
+
+
+def _normalize(text: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "", text.lower())
+
+
+def resolve(projects: list[Project], query: str) -> Resolution:
+    q = query.strip()
+    if not q:
+        return Resolution(None, tuple(projects[:MAX_CANDIDATES]))
+    nq = _normalize(q)
+    checks: list[Callable[[Project], bool]] = [
+        lambda p: p.name == q,
+        lambda p: p.name.lower() == q.lower(),
+        lambda p: bool(nq) and _normalize(p.name) == nq,
+        lambda p: bool(nq) and nq in _normalize(p.name),
+    ]
+    for check in checks:
+        hits = [p for p in projects if check(p)]
+        if len(hits) == 1:
+            return Resolution(hits[0])
+        if hits:
+            return Resolution(None, tuple(hits[:MAX_CANDIDATES]))
+    by_norm = {_normalize(p.name): p for p in projects}
+    close = difflib.get_close_matches(nq, list(by_norm), n=MAX_CANDIDATES, cutoff=0.6)
+    if len(close) == 1:
+        return Resolution(by_norm[close[0]])
+    return Resolution(None, tuple(by_norm[c] for c in close))
+
+
+class ProjectIndex:
+    """discover() with a short cache, since tool calls arrive in bursts."""
+
+    def __init__(self, projects_dir: Path, ttl: float = SCAN_TTL_SECONDS,
+                 clock: Callable[[], float] = time.monotonic) -> None:
+        self._dir = projects_dir
+        self._ttl = ttl
+        self._clock = clock
+        self._cache: list[Project] | None = None
+        self._scanned_at = 0.0
+
+    def all(self) -> list[Project]:
+        now = self._clock()
+        if self._cache is None or now - self._scanned_at >= self._ttl:
+            self._cache = discover(self._dir)
+            self._scanned_at = now
+        return list(self._cache)
+
+    def resolve(self, query: str) -> Resolution:
+        return resolve(self.all(), query)

codetherapy/search.py

@@ -0,0 +1,163 @@
+"""Quick literal search over a project's file names and text: the fast alternative to a deep lookup."""
+from __future__ import annotations
+
+import os
+import subprocess
+import time
+from fnmatch import fnmatch
+from pathlib import Path
+
+from codetherapy.textutil import clip
+
+GIT_TIMEOUT_SECONDS = 5
+MIN_GIT_SECONDS = 0.5
+MAX_FILE_BYTES = 1024 * 1024
+BINARY_SNIFF_BYTES = 8192
+MAX_LINE = 160
+MAX_OUTPUT = 4000
+SKIP_DIRS = {".git", "node_modules", ".venv", "venv", "__pycache__", "dist", "build", ".next", ".tox",
+             ".mypy_cache", ".pytest_cache", "target", ".idea", ".vscode"}
+# Matched case-insensitively against the file name; such files are never listed or read.
+# deep.py turns the same lists into deny rules for ask_project, so the two can't drift apart.
+SECRET_PATTERNS = (".env", ".env.*", ".envrc", ".npmrc", ".netrc", ".pgpass", "*.pem", "*.key", "*.p12",
+                   "*.pfx", "*.keystore", "*.jks", "id_rsa*", "id_ed25519*", "*credentials*", "*secret*")
+SECRET_DIRS = (".ssh", ".aws", ".gnupg")
+# People often run `claude` from their home folder, which makes ~ a "project"; that's every file they own.
+HOME_FOLDER_MESSAGE = ("That project is your whole home folder, so I won't search it — "
+                       "open Claude Code in a specific project folder instead.")
+
+
+def is_home_or_above(path: Path) -> bool:
+    """True for the home folder or a folder that contains it (such as /, /Users or a drive root)."""
+    try:
+        home, target = Path.home().resolve(), path.resolve()
+    except (OSError, RuntimeError):  # RuntimeError: no home folder can be determined
+        return False
+    return target == home or target in home.parents
+
+
+def _is_secret(name: str) -> bool:
+    lowered = name.lower()
+    return any(fnmatch(lowered, pattern) for pattern in SECRET_PATTERNS)
+
+
+def _in_secret_dir(rel: str) -> bool:
+    return any(part in SECRET_DIRS for part in rel.split("/")[:-1])
+
+
+def _git_files(project_path: Path, deadline: float) -> list[str] | None:
+    timeout = min(GIT_TIMEOUT_SECONDS, max(MIN_GIT_SECONDS, deadline - time.monotonic()))
+    try:
+        result = subprocess.run(
+            ["git", "--no-optional-locks", "-C", str(project_path), "ls-files", "-z",
+             "--cached", "--others", "--exclude-standard"],
+            capture_output=True, timeout=timeout)
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    text = result.stdout.decode("utf-8", errors="replace")
+    return [name for name in text.split("\0") if name]
+
+
+def _walk_files(project_path: Path, deadline: float) -> tuple[list[str], bool]:
+    found: list[str] = []
+    for folder, dirs, files in os.walk(project_path):
+        dirs[:] = sorted(d for d in dirs if d not in SKIP_DIRS)
+        for name in sorted(files):
+            if time.monotonic() >= deadline:
+                return found, True
+            found.append((Path(folder) / name).relative_to(project_path).as_posix())
+    return found, False
+
+
+def _candidates(project_path: Path, deadline: float) -> tuple[list[str], bool]:
+    """Searchable relative paths, and whether gathering ran out of time."""
+    files = _git_files(project_path, deadline)
+    timed_out = False
+    if files is None:
+        files, timed_out = _walk_files(project_path, deadline)
+    root = project_path.resolve()
+    safe = []
+    for rel in sorted(set(files)):
+        if timed_out or time.monotonic() >= deadline:
+            return safe, True
+        if _is_secret(rel.rsplit("/", 1)[-1]) or _in_secret_dir(rel):
+            continue
+        try:
+            resolved = (project_path / rel).resolve()
+            resolved.relative_to(root)  # a symlink pointing outside the project is not ours to read
+        except (OSError, ValueError):
+            continue
+        if _is_secret(resolved.name):  # e.g. notes.txt -> .env
+            continue
+        if resolved.is_file():
+            safe.append(rel)
+    return safe, timed_out
+
+
+def _matching_lines(file: Path, needle: str):
+    """Yield (lineno, line) for text lines containing needle; nothing for big or binary files."""
+    try:
+        if file.stat().st_size > MAX_FILE_BYTES:
+            return
+        with open(file, "rb") as handle:
+            if b"\0" in handle.read(BINARY_SNIFF_BYTES):
+                return
+        text = file.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return
+    for lineno, line in enumerate(text.splitlines(), 1):
+        if needle in line.lower():
+            yield lineno, line
+
+
+def search(project_path: Path, query: str, *, max_matches: int = 20, time_budget: float = 3.0) -> str:
+    needle = query.strip().lower()
+    if not needle:
+        return "Tell me what to search for."
+    if not project_path.is_dir():
+        return f"I can't open that project's folder anymore ({project_path})."
+    if is_home_or_above(project_path):
+        return HOME_FOLDER_MESSAGE
+    deadline = time.monotonic() + time_budget
+    name = project_path.name
+    files, note_stopped = _candidates(project_path, deadline)
+    stopped = f"(search stopped after {time_budget:g}s — narrow the search)"
+
+    lines: list[str] = []
+    note = stopped if note_stopped else ""
+
+    def add(line: str) -> bool:
+        """Append a match; False (and set the note) once the cap or the clock says stop."""
+        nonlocal note
+        if len(lines) >= max_matches:
+            note = "(more matches — narrow the search)"  # only reached when one more match exists
+            return False
+        lines.append(line)
+        return True
+
+    def out_of_time() -> bool:
+        nonlocal note
+        if time.monotonic() >= deadline:
+            note = note or stopped
+        return bool(note)
+
+    for rel in files:
+        if needle in rel.lower() and (out_of_time() or not add(f"- {rel}")):
+            break
+    if not note:
+        for rel in files:
+            if out_of_time():
+                break
+            for lineno, line in _matching_lines(project_path / rel, needle):
+                if not add(f"{rel}:{lineno}: {clip(line.strip(), MAX_LINE)}"):
+                    break
+            if note:
+                break
+    if not lines and not note:
+        return f'No matches for "{query.strip()}" in {name}.'
+    body = [f'Matches for "{query.strip()}" in {name}:', *lines]
+    if note:
+        body.append(note)
+    return clip("\n".join(body), MAX_OUTPUT)