trigger-tree 1.14.0__py3-none-any.whl

trigger_tree/_scripts/tt-statusline.py

@@ -0,0 +1,154 @@
+#!/usr/bin/env python3
+"""trigger-tree statusline — live doc-discovery stats for the current session.
+
+Portable (macOS/Linux), stdlib only. The dot pulses with the age of the last read or scan:
+● bright green < 90s, ◐ amber < 10min, ○ dim otherwise.
+Register in project or user settings under "statusLine" with a refreshInterval.
+"""
+
+import hashlib
+import json
+import os
+import re
+import sys
+import time
+import unicodedata
+from datetime import datetime, timezone
+
+ROOT = os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+HIST = os.path.join(ROOT, ".trigger-tree", "history.jsonl")
+BADGE = os.path.join(ROOT, ".trigger-tree", "badge.json")
+
+RESET = "\033[0m"
+FRESH = "\033[1;38;5;114m"  # bright green
+WARM = "\033[38;5;178m"  # amber
+COLD = "\033[38;5;245m"  # dim
+
+
+def terminal_safe(value):
+    """Strip terminal controls and invisible direction overrides from untrusted text."""
+    bidi_controls = "\u061c\u200e\u200f\u202a\u202b\u202c\u202d\u202e\u2066\u2067\u2068\u2069"
+    text = re.sub(r"(?:\x1b\]|\x9d).*?(?:\x07|\x1b\\|\x9c)", "", str(value), flags=re.S)
+    text = re.sub(r"(?:\x1b\[|\x9b)[0-?]*[ -/]*[@-~]", "", text)
+    text = re.sub(r"\x1b[@-_]", "", text)
+    return "".join(
+        ch
+        for ch in text
+        if unicodedata.category(ch) not in ("Cc", "Cs") and ch not in bidi_controls
+    )
+
+
+try:
+    sys.stdout.reconfigure(encoding="utf-8")  # emoji-safe on Windows consoles
+except AttributeError:  # pragma: no cover — exotic stdout replacement
+    pass
+
+
+def main():
+    try:
+        data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        data = {}
+    session = data.get("session_id")
+    if not session:
+        print("🌳 tt: no data")
+        return
+
+    files, scans, last, last_time = {}, 0, None, None
+    state_name = hashlib.sha256(str(session).encode("utf-8")).hexdigest()[:32] + ".json"
+    state_path = os.path.join(ROOT, ".trigger-tree", "sessions", state_name)
+    try:
+        state = json.loads(open(state_path, encoding="utf-8").read())
+    except (OSError, ValueError):
+        state = None
+    if state is not None:
+        files = {path: True for path in state.get("files", [])}
+        scans = int(state.get("scans", 0))
+        last = state.get("last")
+        try:
+            last_time = datetime.strptime(last["ts"], "%Y-%m-%dT%H:%M:%SZ").replace(
+                tzinfo=timezone.utc
+            )
+        except (KeyError, TypeError, ValueError):
+            last_time = None
+    elif not os.path.isfile(HIST):
+        print("🌳 tt: no data")
+        return
+    else:
+        fh = open(HIST, encoding="utf-8")
+        try:
+            scans, last, last_time = _collect_history(fh, session, files)
+        finally:
+            fh.close()
+
+    if not files and not scans:
+        print("🌳 tt: 0 docs consulted")
+        return
+
+    dirs = {os.path.dirname(p) for p in files}
+    depth = max((p.count("/") for p in files), default=0)
+    grade = mature_grade()
+    stats = f"{grade} · " if grade else ""
+    stats += f"{len(files)} files · {scans} searches · {len(dirs)} folders · depth {depth}"
+
+    age = 10**9
+    if last_time is not None:
+        age = time.time() - last_time.timestamp()
+
+    if age < 90:
+        dot, color = "●", FRESH
+    elif age < 600:
+        dot, color = "◐", WARM
+    else:
+        dot, color = "○", COLD
+
+    path = terminal_safe(last["path"]) + ("/" if last.get("t") == "scan" else "")
+    print(f"🌳 {stats} {color}{dot} {path}{RESET}")
+
+
+def mature_grade():
+    """Read the optional public-safe badge cache; measuring badges have no grade."""
+    try:
+        payload = json.loads(open(BADGE, encoding="utf-8").read())
+    except (OSError, ValueError):
+        return None
+    message = payload.get("message")
+    match = re.fullmatch(r"([A-F]) \(\d{1,3}\)", message) if isinstance(message, str) else None
+    return match.group(1) if match else None
+
+
+def _collect_history(fh, session, files):
+    scans, last, last_time = 0, None, None
+    for line in fh:
+        if f'"session":"{session}"' not in line and f'"session": "{session}"' not in line:
+            continue
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        typ = event.get("t")
+        if typ == "read":
+            files[event["path"]] = True
+        elif typ == "scan":
+            scans += 1
+        else:
+            continue
+        try:
+            event_time = datetime.strptime(event["ts"], "%Y-%m-%dT%H:%M:%SZ").replace(
+                tzinfo=timezone.utc
+            )
+        except (KeyError, ValueError):
+            event_time = None
+        if last is None or (
+            event_time is not None and (last_time is None or event_time >= last_time)
+        ):
+            last, last_time = event, event_time
+    return scans, last, last_time
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        print("🌳 tt")
+    sys.exit(0)

trigger_tree/_scripts/tt-suggestions.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Print concise, deterministic router suggestions; keep full stats off stdout."""
+
+import json
+import os
+import subprocess
+import sys
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+
+
+def router_for(path, router_coverage=None):
+    """Return a router proven to exist in stats; never invent index.md."""
+    folder = path.rsplit("/", 1)[0] if "/" in path else "(root)"
+    for item in router_coverage or []:
+        if item.get("folder") == folder:
+            return item.get("router")
+    return None
+
+
+def build_suggestions(stats):
+    suggestions = []
+    seen = set()
+
+    def add(key, text):
+        if key not in seen and len(suggestions) < 5:
+            seen.add(key)
+            suggestions.append(text)
+
+    for item in stats.get("review_candidates", []):
+        if item.get("classification") == "protected":
+            add(
+                ("protected", item["path"]),
+                f"Review, likely keep — rare-but-critical: {item['path']} — {'; '.join(item['why'])}. {item['caveat']}",
+            )
+        elif (
+            not item.get("template", False)
+            and item.get("router")
+            and not item.get("router_mentions_target", False)
+        ):
+            add(
+                ("gap", item["path"]),
+                f"Review candidate: add a link to {item['path']} in {item['router']} — both files exist and that router does not mention the target. {item['caveat']}",
+            )
+
+    # Pre-1.0 payloads lack enough repository evidence for a safe link edit.
+    for item in stats.get("untouched_detail", []) if not stats.get("review_candidates") else []:
+        if not item.get("referenced_from") and not item.get("template", False):
+            path = item["path"]
+            add(
+                ("gap", path),
+                f"Review routing for {path} — legacy telemetry shows no reads or references, but cannot verify an existing router target. Low reads can mean rare-but-critical; verify before editing.",
+            )
+
+    for coverage in stats.get("router_coverage", []):
+        router = coverage.get("router")
+        for path in coverage.get("unlisted", []):
+            add(
+                ("unlisted", path),
+                f"Review candidate: add a link to {path} in {router} — both files exist and the folder router does not mention the target.",
+            )
+
+    for folder in stats.get("folders", []):
+        name = folder["folder"]
+        if name.startswith(".claude/") or name == "(root)":
+            continue
+        if not folder.get("has_index") and folder.get("coverage", 0) < 0.5:
+            add(
+                ("folder", name),
+                f"Add a folder entry point in {name}/ (README.md, _index.md, or index.md) — {folder['touched']}/{folder['files']} files read and no existing router was found.",
+            )
+
+    for folder in stats.get("folders", []):
+        name = folder["folder"]
+        if (
+            folder.get("coverage") == 0
+            and name != "(root)"
+            and not name.startswith(".claude/")
+            and ("folder", name) not in seen
+        ):
+            add(
+                ("cold", name),
+                f"Review routing for {name}/ — none of its {folder['files']} files were read. Low reads can mean rare-but-critical; verify before archiving.",
+            )
+
+    for hunt in stats.get("search_activity", stats.get("hunting", [])):
+        if hunt.get("pattern") == "distributed":
+            add(
+                ("hunt", hunt["path"]),
+                f"Review routing for {hunt['path']} — {hunt['scans']} searches recur across {hunt['sessions']}/{hunt['total_sessions']} sessions ({hunt['tools']}); search telemetry is correlational, not proof of failed routing.",
+            )
+
+    for path in stats.get("unknown_reads", []):
+        add(
+            ("unknown", path),
+            f"Review inventory configuration for {path} — the file exists and was read, but is outside the current documentation inventory.",
+        )
+    return suggestions
+
+
+def main():
+    result = subprocess.run(
+        [sys.executable, os.path.join(SCRIPT_DIR, "tt-stats.py")],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    stats = json.loads(result.stdout)
+    totals = stats["totals"]
+    if stats["maturity"] == "cold-start":
+        print(
+            f"🌳 Not enough data yet ({totals['reads']} reads, {stats['sessions']} sessions) — suggestions need a few working sessions first."
+        )
+        return
+    print(
+        f"🌳 Suggestions — based on {totals['reads']} reads, {totals['scans']} searches, {stats['sessions']} sessions; proposes router edits only and changes nothing until you confirm."
+    )
+    suggestions = build_suggestions(stats)
+    if not suggestions:
+        print("No evidence-backed router changes found yet.")
+        return
+    for number, suggestion in enumerate(suggestions, 1):
+        print(f"{number}. {suggestion}")
+    print("Apply any of these? Reply with the numbers.")
+
+
+if __name__ == "__main__":
+    main()

trigger_tree/_scripts/tt-tips.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""Print concise, client-aware instruction-maintenance tips."""
+
+import argparse
+import os
+from pathlib import Path
+
+
+def markdown_lines(path):
+    try:
+        return len(path.read_text(encoding="utf-8").splitlines())
+    except (OSError, UnicodeError):
+        return 0
+
+
+def has_paths_frontmatter(path):
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeError):
+        return True
+    if not text.startswith("---\n"):
+        return False
+    end = text.find("\n---", 4)
+    return end >= 0 and any(line.strip().startswith("paths:") for line in text[4:end].splitlines())
+
+
+def claude_tips(root):
+    tips = [
+        "Run /memory periodically and remove stale or contradictory auto-memory entries; memory is editable context, not an enforced source of truth."
+    ]
+    instruction_files = [
+        path for path in (root / "CLAUDE.md", root / ".claude" / "CLAUDE.md") if path.is_file()
+    ]
+    if not instruction_files:
+        tips.append(
+            "Add a project CLAUDE.md with only durable commands, conventions, and architecture facts you repeatedly need to explain."
+        )
+    for path in instruction_files:
+        count = markdown_lines(path)
+        if count > 200:
+            tips.append(
+                f"Trim {path.relative_to(root)} ({count} lines): Anthropic recommends targeting under 200 lines and moving specialized guidance to scoped rules or skills."
+            )
+            break
+    rules_dir = root / ".claude" / "rules"
+    unscoped = (
+        sorted(
+            path.relative_to(root).as_posix()
+            for path in rules_dir.rglob("*.md")
+            if path.is_file() and not has_paths_frontmatter(path)
+        )
+        if rules_dir.is_dir()
+        else []
+    )
+    if unscoped:
+        examples = ", ".join(unscoped[:2])
+        suffix = " …" if len(unscoped) > 2 else ""
+        tips.append(
+            f"Review {len(unscoped)} always-loaded rule file(s) for path scoping ({examples}{suffix}); unconditional rules consume context in every session."
+        )
+    return tips[:4]
+
+
+def codex_tips(root):
+    agents = root / "AGENTS.md"
+    tips = []
+    if not agents.is_file():
+        tips.append(
+            "Add AGENTS.md with repository navigation, build/test commands, conventions, and non-obvious constraints that Codex cannot infer reliably."
+        )
+    else:
+        tips.append(
+            "Review AGENTS.md after architecture or workflow changes so persistent Codex instructions do not drift from the repository."
+        )
+        text = agents.read_text(encoding="utf-8", errors="replace").lower()
+        if not any(token in text for token in ("test", "check", "verify", "ci")):
+            tips.append(
+                "Add exact verification commands to AGENTS.md; reproducible environment and test instructions reduce avoidable agent errors."
+            )
+    tips.append(
+        "Keep agent-facing indexes and commands executable and inspectable; use trigger-tree suggestions for evidence-backed navigation gaps."
+    )
+    return tips[:4]
+
+
+def tips_for(client, root):
+    root = Path(root).resolve()
+    return claude_tips(root) if client == "claude" else codex_tips(root)
+
+
+def parse_args(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--client", required=True, choices=("claude", "codex"))
+    parser.add_argument("--project", default=os.getcwd())
+    return parser.parse_args(argv)
+
+
+def main(argv=None):
+    args = parse_args(argv)
+    tips = tips_for(args.client, args.project)
+    print(f"🌳 {args.client.title()} maintenance tips — review only; nothing was changed.")
+    for number, tip in enumerate(tips, 1):
+        print(f"{number}. {tip}")
+
+
+if __name__ == "__main__":
+    main()

trigger_tree/_scripts/tt-uninstall.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Remove trigger-tree project wiring without deleting telemetry or ignore rules."""
+
+import json
+import os
+import runpy
+
+ROOT = os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+SETUP = runpy.run_path(os.path.join(SCRIPT_DIR, "tt-setup.py"))
+assert_safe_destination = SETUP["assert_safe_destination"]
+atomic_write = SETUP["atomic_write"]
+report = SETUP["report"]
+
+
+def unregister_statusline():
+    path = os.path.join(ROOT, ".claude", "settings.json")
+    assert_safe_destination(path)
+    if not os.path.isfile(path):
+        report("skipped", ".claude/settings.json (absent)")
+        return
+    try:
+        settings = json.load(open(path, encoding="utf-8"))
+    except json.JSONDecodeError:
+        report("skipped", ".claude/settings.json (unparseable — remove statusLine manually)")
+        return
+    status = settings.get("statusLine")
+    command = status.get("command", "") if isinstance(status, dict) else ""
+    if "tt-statusline.py" not in command:
+        report("skipped", ".claude/settings.json (foreign statusLine left untouched)")
+        return
+    del settings["statusLine"]
+    atomic_write(path, json.dumps(settings, indent=2) + "\n")
+    report("updated", ".claude/settings.json (trigger-tree statusLine removed)")
+
+
+def remove_statusline_script():
+    path = os.path.join(ROOT, ".claude", "tt-statusline.py")
+    assert_safe_destination(path)
+    if not os.path.isfile(path):
+        report("skipped", ".claude/tt-statusline.py (absent)")
+        return
+    os.unlink(path)
+    report("removed", ".claude/tt-statusline.py")
+
+
+def main():
+    unregister_statusline()
+    remove_statusline_script()
+    print(
+        "kept     .trigger-tree/ telemetry and .gitignore entries; "
+        "delete them manually if you want to erase local history"
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as exc:
+        print(f"skipped  uninstall ({exc})")