code-context-engine 0.4.0__py3-none-any.whl

context_engine/indexer/secrets.py

@@ -0,0 +1,332 @@
+"""Secret detection at index time.
+
+Two layers:
+
+  1. **Filename-based skipping** — files whose names match well-known
+     credential patterns (.env*, *.pem, secrets.yml, …) are never read,
+     never embedded, never served. This is the cheap first line of
+     defence and catches the most common leak.
+
+  2. **Content-based redaction** — for files that DO get indexed, lines
+     containing what look like AWS keys, GitHub tokens, JWTs, etc. get
+     replaced with `[REDACTED:<reason>]` before chunking. The chunker
+     and embedder never see the secret value.
+
+Both layers are conservative on purpose — false positives (over-redaction
+of innocent code) are recoverable; false negatives (a real secret leaked
+into the vector DB) are not. When in doubt, redact.
+
+Tunable via config:
+  · indexer.redact_secrets (default: True) — master switch.
+  · indexer.secret_extra_patterns (default: []) — user-added regexes
+    for content scanning, merged with the built-in set.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+# ── Filename-level skip list ────────────────────────────────────────────────
+# Glob-style suffixes / exact names that almost always mean "credentials".
+# Match is case-insensitive against the full filename (not full path).
+
+# Exact filenames (case-insensitive). Entire file is skipped.
+_SECRET_FILENAMES = frozenset({
+    # Dotenv family (covers .env, .env.local, .env.production, etc. — see _SECRET_PREFIXES)
+    ".npmrc", ".pypirc", ".netrc",
+    # Cloud / infra
+    "credentials.json", "credentials.yaml", "credentials.yml",
+    "secrets.json", "secrets.yaml", "secrets.yml",
+    "service-account.json", "gcp-key.json",
+    "kube-config", "kubeconfig",
+    # CI / app config that frequently holds tokens
+    "auth.json",
+    # Git config can carry remote tokens
+    ".git-credentials",
+    # SSH private keys frequently sit extension-less in ~/.ssh.
+    "id_rsa", "id_dsa", "id_ecdsa", "id_ed25519", "id_xmss",
+})
+
+# Filename starts with any of these → skip (handles .env, .env.local, etc.).
+_SECRET_PREFIXES = (".env",)
+
+# File extensions whose presence is a strong signal of a key/cert. Skip outright.
+_SECRET_EXTENSIONS = frozenset({
+    ".pem", ".key", ".crt", ".cer", ".der",
+    ".p12", ".pfx",          # PKCS#12 cert bundles
+    ".jks", ".keystore",     # Java keystores
+    ".pgp", ".asc", ".gpg",  # PGP keys
+    ".kdbx",                 # KeePass
+    ".ppk",                  # PuTTY private keys
+})
+
+
+def is_secret_file(path: Path) -> bool:
+    """True if the filename alone is enough to classify as credentials.
+
+    Operates on basename only — callers don't need to pre-normalise the
+    path. Case-insensitive across the board (Windows/macOS reality).
+    """
+    name = path.name.lower()
+    if name in _SECRET_FILENAMES:
+        return True
+    if path.suffix.lower() in _SECRET_EXTENSIONS:
+        return True
+    for prefix in _SECRET_PREFIXES:
+        if name.startswith(prefix):
+            return True
+    return False
+
+
+# ── Content-level redaction ─────────────────────────────────────────────────
+# Patterns are tuples of (regex, label). Label appears in the redaction
+# placeholder so users can tell *what kind* of secret was scrubbed without
+# leaking the value itself.
+#
+# Conservative ordering: patterns earlier in the list win — specific
+# vendor formats before generic high-entropy heuristics.
+
+_CONTENT_PATTERNS: list[tuple[re.Pattern, str]] = [
+    # AWS access keys — fixed prefix + 16 base32 chars. Non-capturing
+    # group on the prefix so the whole match is the credential value
+    # (otherwise we'd only replace AKIA and leak the 16-char suffix).
+    (re.compile(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b"), "AWS_ACCESS_KEY"),
+    # AWS secret keys — 40 base64 chars after "aws_secret_access_key"-ish context.
+    (re.compile(
+        r"(?i)aws_secret_access_key\s*[:=]\s*['\"]?([A-Za-z0-9/+=]{40})['\"]?"
+    ), "AWS_SECRET_KEY"),
+    # GitHub tokens (classic + fine-grained + app + OAuth).
+    (re.compile(r"\bghp_[A-Za-z0-9]{36}\b"), "GITHUB_PAT"),
+    (re.compile(r"\bgithub_pat_[A-Za-z0-9_]{82}\b"), "GITHUB_FINE_GRAINED_PAT"),
+    (re.compile(r"\b(ghs|gho|ghu|ghr)_[A-Za-z0-9]{36}\b"), "GITHUB_OAUTH"),
+    # Slack tokens.
+    (re.compile(r"\bxox[abprs]-[A-Za-z0-9-]{10,}\b"), "SLACK_TOKEN"),
+    # Stripe live keys (test keys are deliberately not matched — they're
+    # safe to commit and matching them would over-redact every Stripe
+    # quickstart in the wild).
+    (re.compile(r"\b(sk|rk)_live_[A-Za-z0-9]{24,}\b"), "STRIPE_LIVE_KEY"),
+    # OpenAI / Anthropic API keys.
+    (re.compile(r"\bsk-[A-Za-z0-9]{20}T3BlbkFJ[A-Za-z0-9]{20}\b"), "OPENAI_KEY"),
+    (re.compile(r"\bsk-ant-(api03|admin01)-[A-Za-z0-9_\-]{93,}\b"), "ANTHROPIC_KEY"),
+    # Google API keys.
+    (re.compile(r"\bAIza[0-9A-Za-z_\-]{35}\b"), "GOOGLE_API_KEY"),
+    # Generic JWT — three base64url segments separated by dots.
+    (re.compile(r"\beyJ[A-Za-z0-9_\-]+\.eyJ[A-Za-z0-9_\-]+\.[A-Za-z0-9_\-]+\b"), "JWT"),
+    # Private key blocks (catch even if filename slipped past the skip list).
+    (re.compile(
+        r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]+?-----END [A-Z ]*PRIVATE KEY-----"
+    ), "PRIVATE_KEY_BLOCK"),
+    # Generic high-signal "looks like a secret" heuristic — variable
+    # named after a credential, assigned to a long opaque string. Skips
+    # placeholders ("xxx", "your-key-here", "<insert>") so the typical
+    # README example doesn't trigger a redaction.
+    #
+    # The keyword is matched anywhere on the line (no `^` anchor) so
+    # patterns like `config["password"] = "..."` and dict literals fire.
+    # Word boundary on the left edge keeps "ssh_password_dialog" from
+    # matching as a fake password assignment.
+    (re.compile(
+        r"(?i)\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|"
+        r"private[_-]?key|auth[_-]?token|client[_-]?secret)\b"
+        r"['\"\]\s]*[:=]\s*['\"]([^'\"\s]{16,})['\"]"
+    ), "GENERIC_CREDENTIAL"),
+]
+
+
+# Common placeholder values that should NOT be redacted even if they
+# match the generic pattern. Reduces noise in templates / README files.
+_PLACEHOLDER_VALUES = frozenset({
+    "your-api-key", "your_api_key", "your-key-here", "your_key_here",
+    "<your-key>", "<api-key>", "<your_key>", "<api_key>",
+    "xxxxxxxxxxxxxxxx", "0000000000000000",
+    "changeme", "change-me", "change_me",
+    "placeholder", "example", "sample",
+})
+
+
+_PLACEHOLDER_SUBSTRINGS = (
+    "placeholder", "example", "fake", "dummy", "sample",
+    "changeme", "change-me", "change_me", "not_real",
+    "not-real", "redacted", "<your", "<api",
+    # README phrasing variants
+    "your_key", "your-key", "your_secret", "your-secret",
+    "your_token", "your-token", "your_api", "your-api",
+    "your_password", "your-password",
+    "replace_with", "replace-with", "insert_your", "insert-your",
+)
+
+
+def _starts_with_placeholder_prefix(value: str) -> bool:
+    # Any string that opens with "your-" / "your_" / "my-" / "my_" is a
+    # tutorial-style placeholder, not a credential. README examples like
+    # "your-api-key-here" or "my_secret_value" all match.
+    for prefix in ("your-", "your_", "my-", "my_"):
+        if value.startswith(prefix):
+            return True
+    return False
+
+
+def _is_placeholder(value: str) -> bool:
+    v = value.strip("'\"<>").lower()
+    if v in _PLACEHOLDER_VALUES:
+        return True
+    # Repeated single character ("xxxxxxxxxx", "0000000000") is almost
+    # always a placeholder, never a real key.
+    if len(set(v)) <= 2:
+        return True
+    # Substring heuristic — README/docs frequently embed credential-shaped
+    # strings with telltale words. Better to over-skip these than to redact
+    # innocent documentation.
+    for needle in _PLACEHOLDER_SUBSTRINGS:
+        if needle in v:
+            return True
+    if _starts_with_placeholder_prefix(v):
+        return True
+    return False
+
+
+def redact_secrets(
+    text: str,
+    *,
+    extra_patterns: list[tuple[re.Pattern, str]] | None = None,
+) -> tuple[str, list[str]]:
+    """Replace credential-shaped substrings with `[REDACTED:LABEL]`.
+
+    Returns (redacted_text, labels) — `labels` enumerates which pattern
+    classes fired, so callers can record telemetry without leaking the
+    secret value. Empty list means the text is clean.
+
+    The redaction is line-aware for the generic-credential pattern:
+    the entire value gets replaced, but the variable name and assignment
+    syntax are preserved so chunked code still parses.
+    """
+    if not text:
+        return text, []
+    patterns = list(_CONTENT_PATTERNS)
+    if extra_patterns:
+        patterns.extend(extra_patterns)
+    out = text
+    fired: list[str] = []
+
+    for pattern, label in patterns:
+        def _sub(match: re.Match, _label: str = label) -> str:
+            # If the match has a single capture group, that's the actual
+            # credential value — preserve everything around it.
+            if match.lastindex:
+                value = match.group(match.lastindex)
+                if _is_placeholder(value):
+                    return match.group(0)
+                fired.append(_label)
+                return match.group(0).replace(value, f"[REDACTED:{_label}]")
+            full = match.group(0)
+            if _is_placeholder(full):
+                return full
+            fired.append(_label)
+            return f"[REDACTED:{_label}]"
+
+        out = pattern.sub(_sub, out)
+
+    return out, fired
+
+
+# ── PII patterns ────────────────────────────────────────────────────────────
+# Used by memory.db writes (decisions / turn summaries / code areas) so
+# personal data captured during a session doesn't end up persisted in
+# searchable form. Lighter touch than secret detection — only the most
+# unambiguous patterns. Free-form text shouldn't be aggressively scrubbed.
+
+_PII_PATTERNS: list[tuple[re.Pattern, str]] = [
+    # Email addresses — simple but effective. Matches RFC-mostly-compliant
+    # addresses; over-matches a tiny bit (won't reject quoted local-parts)
+    # but that's fine for redaction.
+    (re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b"), "EMAIL"),
+    # IPv4 — four 1-3 digit groups. Won't match localhost or 127.0.0.1
+    # specifically because those are useful in dev notes.
+    (re.compile(
+        r"\b(?!127\.0\.0\.1\b|0\.0\.0\.0\b|10\.0\.0\.1\b|192\.168\.\d+\.\d+\b)"
+        r"(?:[1-9]\d?|1\d{2}|2[0-4]\d|25[0-5])"
+        r"(?:\.(?:\d{1,3})){3}\b"
+    ), "IPV4"),
+    # Credit-card-shaped 13-19 digit runs (with optional spaces/dashes).
+    # Filtered through Luhn check to avoid false positives on order
+    # numbers, hashes, etc.
+    (re.compile(r"\b(?:\d[ -]?){13,19}\b"), "CREDIT_CARD"),
+    # US-style SSN.
+    (re.compile(r"\b\d{3}-\d{2}-\d{4}\b"), "SSN"),
+    # E.164 phone numbers (with leading +).
+    (re.compile(r"\+\d{1,3}[ -]?\(?\d{1,4}\)?[ -]?\d{3,4}[ -]?\d{3,4}\b"), "PHONE_E164"),
+]
+
+
+def _passes_luhn(digits: str) -> bool:
+    """Luhn check for credit-card validation. Skips invalid candidates so
+    we don't redact every long number. Strips non-digits first.
+    """
+    digits = re.sub(r"\D", "", digits)
+    if not (13 <= len(digits) <= 19):
+        return False
+    total = 0
+    parity = len(digits) % 2
+    for i, ch in enumerate(digits):
+        n = int(ch)
+        if i % 2 == parity:
+            n *= 2
+            if n > 9:
+                n -= 9
+        total += n
+    return total % 10 == 0
+
+
+def redact_pii(
+    text: str,
+    *,
+    extra_patterns: list[tuple[re.Pattern, str]] | None = None,
+) -> tuple[str, list[str]]:
+    """Replace common PII (emails, IPs, credit cards, SSNs, phones) with
+    `[REDACTED:LABEL]`. Same return shape as `redact_secrets`.
+
+    Lighter touch than secret detection: only the unambiguous patterns
+    fire, and credit-card candidates are Luhn-validated so order numbers
+    and SHA hashes don't get clobbered.
+    """
+    if not text:
+        return text, []
+    patterns = list(_PII_PATTERNS)
+    if extra_patterns:
+        patterns.extend(extra_patterns)
+    out = text
+    fired: list[str] = []
+
+    for pattern, label in patterns:
+        def _sub(match: re.Match, _label: str = label) -> str:
+            value = match.group(0)
+            # Credit-card pattern needs Luhn validation to avoid false
+            # positives. Other PII patterns are accepted as-is.
+            if _label == "CREDIT_CARD" and not _passes_luhn(value):
+                return value
+            fired.append(_label)
+            return f"[REDACTED:{_label}]"
+
+        out = pattern.sub(_sub, out)
+
+    return out, fired
+
+
+# ── Convenience: combined check for the indexer ────────────────────────────
+
+def scan_and_redact(
+    file_path: Path,
+    content: str,
+    *,
+    extra_patterns: list[tuple[re.Pattern, str]] | None = None,
+) -> tuple[str | None, list[str]]:
+    """Indexer-facing entrypoint.
+
+    Returns (text_or_None, labels). `text_or_None` is None when the file
+    should be skipped entirely (filename-level secret), otherwise the
+    redacted content (which equals `content` if nothing fired). `labels`
+    is the list of pattern labels that triggered.
+    """
+    if is_secret_file(file_path):
+        return None, ["SECRET_FILENAME"]
+    return redact_secrets(content, extra_patterns=extra_patterns)

context_engine/indexer/watcher.py

@@ -0,0 +1,109 @@
+"""File watcher with debouncing using watchdog.
+
+Watches a directory for file changes and triggers an async callback
+after a debounce period. Used by `cce serve` to keep the index
+up-to-date as files are saved.
+"""
+import asyncio
+import logging
+import threading
+import time
+from pathlib import Path
+
+from watchdog.observers import Observer
+from watchdog.events import FileSystemEventHandler
+
+log = logging.getLogger(__name__)
+
+
+class _DebouncedHandler(FileSystemEventHandler):
+    def __init__(self, on_change, debounce_ms, ignore_patterns, watch_dir, loop):
+        self._on_change = on_change
+        self._debounce_s = debounce_ms / 1000.0
+        self._ignore_set = set(ignore_patterns)
+        self._watch_dir = Path(watch_dir)
+        self._loop = loop
+        self._pending: dict[str, float] = {}
+        self._lock = threading.Lock()
+        self._timer: threading.Timer | None = None
+
+    def _should_ignore(self, path: str) -> bool:
+        """Check if any path component matches an ignore pattern."""
+        try:
+            rel = Path(path).relative_to(self._watch_dir)
+        except ValueError:
+            return False
+        for part in rel.parts:
+            if part in self._ignore_set:
+                return True
+            # Always skip CCE's own storage/index files
+            if part == ".cce":
+                return True
+        return False
+
+    def on_any_event(self, event):
+        if event.is_directory:
+            return
+        path = event.src_path
+        if self._should_ignore(path):
+            return
+        with self._lock:
+            self._pending[path] = time.time()
+            if self._timer:
+                self._timer.cancel()
+            self._timer = threading.Timer(self._debounce_s, self._flush)
+            self._timer.start()
+
+    def _flush(self):
+        with self._lock:
+            paths = list(self._pending.keys())
+            self._pending.clear()
+        for path in paths:
+            try:
+                asyncio.run_coroutine_threadsafe(self._on_change(path), self._loop)
+            except RuntimeError:
+                # Loop closed — shutting down
+                pass
+
+
+class FileWatcher:
+    """Watch a directory for file changes with debounced async callbacks."""
+
+    def __init__(self, watch_dir, on_change, debounce_ms=500, ignore_patterns=None):
+        self._watch_dir = watch_dir
+        self._on_change = on_change
+        self._debounce_ms = debounce_ms
+        self._ignore_patterns = ignore_patterns or []
+        self._observer = None
+        self._handler = None
+
+    def start(self, loop=None):
+        """Start watching. Pass the running asyncio loop explicitly."""
+        if loop is None:
+            try:
+                loop = asyncio.get_running_loop()
+            except RuntimeError:
+                loop = asyncio.get_event_loop()
+        self._handler = _DebouncedHandler(
+            on_change=self._on_change,
+            debounce_ms=self._debounce_ms,
+            ignore_patterns=self._ignore_patterns,
+            watch_dir=self._watch_dir,
+            loop=loop,
+        )
+        self._observer = Observer()
+        self._observer.schedule(self._handler, self._watch_dir, recursive=True)
+        self._observer.daemon = True
+        self._observer.start()
+        log.debug("Watcher started for %s", self._watch_dir)
+
+    def stop(self):
+        if self._handler:
+            with self._handler._lock:
+                if self._handler._timer:
+                    self._handler._timer.cancel()
+                    self._handler._timer = None
+        if self._observer:
+            self._observer.stop()
+            self._observer.join(timeout=2)
+            log.debug("Watcher stopped")

context_engine/integration/bootstrap.py

@@ -0,0 +1,76 @@
+"""Bootstrap context builder — generates compressed project context for session start."""
+from importlib.metadata import version as pkg_version
+
+from context_engine.models import Chunk, ConfidenceLevel
+
+_CHARS_PER_TOKEN = 4
+
+
+def _get_version() -> str:
+    try:
+        return pkg_version("code-context-engine")
+    except Exception:
+        return "unknown"
+
+
+class BootstrapBuilder:
+    def __init__(self, max_tokens: int = 10000) -> None:
+        self._max_chars = max_tokens * _CHARS_PER_TOKEN
+
+    def build(self, project_name, chunks=None, recent_commits=None,
+              active_decisions=None, working_state=None, chunk_count=0,
+              project_commands_text=None):
+        sections = []
+        ver = _get_version()
+        status_line = f"CCE v{ver} · {chunk_count} chunks indexed" if chunk_count else f"CCE v{ver} · no chunks indexed yet"
+        sections.append(f"## Project: {project_name}\n`{status_line}`")
+        sections.append(self._build_architecture(chunks or []))
+        sections.append(self._build_activity(recent_commits or []))
+        if working_state:
+            state_text = "\n".join(f"  {line}" for line in working_state)
+            sections.append(f"### Working State\n{state_text}")
+        if project_commands_text:
+            sections.append(project_commands_text)
+        if active_decisions:
+            decisions_text = "\n".join(f"- {d}" for d in active_decisions)
+            sections.append(f"### Active Context\n{decisions_text}")
+        code_section = self._build_code_context(chunks or [])
+        if code_section:
+            sections.append(code_section)
+        payload = "\n\n".join(sections)
+        if len(payload) > self._max_chars:
+            payload = payload[:self._max_chars] + "\n\n[Context truncated to fit token limit]"
+        return payload
+
+    def _build_architecture(self, chunks):
+        high_conf = [c for c in chunks if ConfidenceLevel.from_score(c.confidence_score) == ConfidenceLevel.HIGH]
+        if not high_conf:
+            return "### Architecture\nNo indexed context available yet."
+        by_file = {}
+        for chunk in high_conf:
+            by_file.setdefault(chunk.file_path, []).append(chunk)
+        lines = ["### Architecture"]
+        for file_path, file_chunks in sorted(by_file.items()):
+            lines.append(f"\n**{file_path}:**")
+            for chunk in file_chunks:
+                text = chunk.compressed_content or chunk.content[:200]
+                lines.append(f"- {text}")
+        return "\n".join(lines)
+
+    def _build_activity(self, commits):
+        if not commits:
+            return "### Recent Activity\nNo recent commits."
+        lines = ["### Recent Activity"]
+        for commit in commits[:10]:
+            lines.append(f"- {commit}")
+        return "\n".join(lines)
+
+    def _build_code_context(self, chunks):
+        medium_conf = [c for c in chunks if ConfidenceLevel.from_score(c.confidence_score) == ConfidenceLevel.MEDIUM]
+        if not medium_conf:
+            return ""
+        lines = ["### Additional Context (may need drill-down)"]
+        for chunk in medium_conf[:20]:
+            text = chunk.compressed_content or chunk.content[:150]
+            lines.append(f"- [{chunk.file_path}] {text}")
+        return "\n".join(lines)

context_engine/integration/git_context.py

@@ -0,0 +1,132 @@
+"""Git helpers for session-start context — recent commits, working state, modified files.
+
+All functions gracefully return empty results when the project is not a git
+repository, so CCE works for non-git projects too.
+"""
+import subprocess
+from pathlib import Path
+
+
+def _is_git_repo(project_dir: str) -> bool:
+    """Return True if project_dir is inside a git work tree."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--is-inside-work-tree"],
+            cwd=project_dir,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return False
+
+
+def _run_git(args: list[str], cwd: str) -> str:
+    """Run a git command and return stdout, or empty string on failure."""
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=cwd,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        return result.stdout.strip() if result.returncode == 0 else ""
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return ""
+
+
+def get_recent_commits(project_dir: str, count: int = 10) -> list[str]:
+    """Return the last N commits as short one-line strings."""
+    if not _is_git_repo(project_dir):
+        return []
+    output = _run_git(
+        ["log", "--oneline", f"-{count}"],
+        cwd=project_dir,
+    )
+    return output.splitlines() if output else []
+
+
+def get_working_state(project_dir: str) -> list[str]:
+    """Return a summary of uncommitted changes and branch info."""
+    if not _is_git_repo(project_dir):
+        return []
+
+    lines: list[str] = []
+
+    # Current branch
+    branch = _run_git(["branch", "--show-current"], cwd=project_dir)
+    if branch:
+        lines.append(f"Branch: {branch}")
+
+    # Ahead/behind relative to upstream
+    if branch:
+        tracking = _run_git(
+            ["rev-list", "--left-right", "--count", f"{branch}@{{upstream}}...HEAD"],
+            cwd=project_dir,
+        )
+        if tracking:
+            parts = tracking.split()
+            if len(parts) == 2:
+                try:
+                    behind, ahead = int(parts[0]), int(parts[1])
+                    if ahead > 0:
+                        lines.append(f"Ahead of remote by {ahead} commit(s)")
+                    if behind > 0:
+                        lines.append(f"Behind remote by {behind} commit(s)")
+                except ValueError:
+                    pass
+
+    # Staged changes
+    staged = _run_git(["diff", "--cached", "--name-status"], cwd=project_dir)
+    if staged:
+        lines.append("Staged:")
+        for line in staged.splitlines()[:10]:
+            lines.append(f"  {line}")
+
+    # Unstaged changes
+    unstaged = _run_git(["diff", "--name-status"], cwd=project_dir)
+    if unstaged:
+        lines.append("Modified (unstaged):")
+        for line in unstaged.splitlines()[:10]:
+            lines.append(f"  {line}")
+
+    # Untracked files (just count, not full list)
+    untracked = _run_git(["ls-files", "--others", "--exclude-standard"], cwd=project_dir)
+    if untracked:
+        n = len(untracked.splitlines())
+        lines.append(f"Untracked files: {n}")
+
+    return lines
+
+
+def get_recently_modified_files(project_dir: str, log_depth: int = 5) -> list[str]:
+    """Return file paths recently modified in git (last N commits + working tree)."""
+    if not _is_git_repo(project_dir):
+        return []
+
+    files: list[str] = []
+
+    # Files changed in working tree
+    wt_files = _run_git(["diff", "--name-only"], cwd=project_dir)
+    if wt_files:
+        files.extend(wt_files.splitlines())
+
+    # Files changed in recent commits
+    commit_files = _run_git(
+        ["log", f"-{log_depth}", "--pretty=format:", "--name-only"],
+        cwd=project_dir,
+    )
+    if commit_files:
+        files.extend(f for f in commit_files.splitlines() if f.strip())
+
+    # Deduplicate, preserve order, filter to existing files
+    seen: set[str] = set()
+    result: list[str] = []
+    for f in files:
+        if f not in seen:
+            seen.add(f)
+            if (Path(project_dir) / f).exists():
+                result.append(f)
+    return result[:15]