trigger-tree 1.14.0__py3-none-any.whl

trigger_tree/_scripts/tt_runtime.py

@@ -0,0 +1,27 @@
+"""Shared runtime path resolution for trigger-tree hook entry points."""
+
+import os
+import subprocess
+
+
+def project_root(cwd=None):
+    """Resolve one dataset root: explicit override, git root, Claude root, then cwd."""
+    explicit = os.environ.get("TT_PROJECT_DIR")
+    if explicit:
+        return explicit
+    claude_root = os.environ.get("CLAUDE_PROJECT_DIR")
+    working = cwd or claude_root or os.getcwd()
+    try:
+        root = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=working,
+            capture_output=True,
+            text=True,
+            timeout=2,
+            check=True,
+        ).stdout.strip()
+        if root:
+            return root
+    except (OSError, subprocess.SubprocessError):
+        pass
+    return claude_root or cwd or os.getcwd()

trigger_tree/_scripts/tt_scope.py

@@ -0,0 +1,76 @@
+"""Bounded, local audit of Markdown files covered by trigger-tree's watch regex."""
+
+import os
+import re
+
+DEFAULT_LIMIT = 5000
+SKIP_DIRS = {
+    ".git",
+    ".agents",
+    ".codex",
+    ".pytest_cache",
+    ".trigger-tree",
+    "node_modules",
+    "vendor",
+    "vendors",
+    "dist",
+    "build",
+    "__pycache__",
+    "tests",
+    "worktrees",
+}
+
+
+def scan_markdown(root, watch_regex, limit=DEFAULT_LIMIT):
+    """Return visited/Markdown/watched counts without following links or walking forever."""
+    pattern = re.compile(watch_regex)
+    visited = markdown = watched = 0
+    paths = []
+    capped = False
+    for current, directories, files in os.walk(root, followlinks=False):
+        directories[:] = [
+            name for name in directories if name not in SKIP_DIRS and not name.startswith(".venv")
+        ]
+        for name in files:
+            if visited >= limit:
+                capped = True
+                return {
+                    "visited": visited,
+                    "markdown": markdown,
+                    "watched": watched,
+                    "paths": paths,
+                    "capped": capped,
+                }
+            visited += 1
+            if not name.lower().endswith((".md", ".markdown")):
+                continue
+            markdown += 1
+            relative = os.path.relpath(os.path.join(current, name), root).replace(os.sep, "/")
+            paths.append(relative)
+            watched += bool(pattern.search(relative))
+    return {
+        "visited": visited,
+        "markdown": markdown,
+        "watched": watched,
+        "paths": paths,
+        "capped": capped,
+    }
+
+
+def suggested_regex(paths):
+    """Describe only observed Markdown locations, without inventing repository intent."""
+    roots = sorted({path.split("/", 1)[0] for path in paths if "/" in path})
+    files = sorted(path for path in paths if "/" not in path)
+    parts = []
+    if roots:
+        parts.append(
+            r"^(?:" + "|".join(re.escape(name) for name in roots) + r")/.*\.(?:md|markdown)$"
+        )
+    if files:
+        parts.append(r"^(?:" + "|".join(re.escape(name) for name in files) + r")$")
+    return "|".join(parts)
+
+
+def is_poor_coverage(result):
+    total = result["markdown"]
+    return total > 0 and (result["watched"] == 0 or result["watched"] / total < 0.25)

trigger_tree/_scripts/validate_palette.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+"use strict";
+
+const value = process.argv[2] || "";
+const colors = value.split(",").map((hex) => hex.trim());
+if (colors.length < 2 || colors.some((hex) => !/^#[0-9a-f]{6}$/i.test(hex))) {
+  console.error("usage: validate_palette.js '#hex,#hex,…' --mode dark");
+  process.exit(2);
+}
+
+const rgb = (hex) => [1, 3, 5].map((at) => parseInt(hex.slice(at, at + 2), 16) / 255);
+const simulations = {
+  normal: [[1, 0, 0], [0, 1, 0], [0, 0, 1]],
+  protan: [[0.567, 0.433, 0], [0.558, 0.442, 0], [0, 0.242, 0.758]],
+  deutan: [[0.625, 0.375, 0], [0.7, 0.3, 0], [0, 0.3, 0.7]],
+  tritan: [[0.95, 0.05, 0], [0, 0.433, 0.567], [0, 0.475, 0.525]],
+};
+const transform = (color, matrix) => matrix.map((row) => row.reduce((sum, n, i) => sum + n * color[i], 0));
+const distance = (a, b) => Math.sqrt(a.reduce((sum, n, i) => sum + (n - b[i]) ** 2, 0)) * 255;
+let failed = false;
+for (let index = 1; index < colors.length; index += 1) {
+  const scores = Object.entries(simulations).map(([name, matrix]) => [name, distance(transform(rgb(colors[index - 1]), matrix), transform(rgb(colors[index]), matrix))]);
+  const minimum = Math.min(...scores.map(([, score]) => score));
+  console.log(`${colors[index - 1]} → ${colors[index]}: ${scores.map(([name, score]) => `${name} ${score.toFixed(1)}`).join(" · ")}`);
+  if (minimum < 28) failed = true;
+}
+console.log(failed ? "FAIL: adjacent step below CVD separation threshold 28" : "PASS: all adjacent steps meet CVD separation threshold 28");
+process.exitCode = failed ? 1 : 0;

trigger_tree/cli.py

@@ -0,0 +1,52 @@
+"""Standalone `tt` console entry point dispatching to the bundled scripts."""
+
+import runpy
+import sys
+from pathlib import Path
+
+SUBCOMMANDS = (
+    "doctor",
+    "log",
+    "report",
+    "setup",
+    "stats",
+    "suggestions",
+    "tips",
+    "uninstall",
+    "watch",
+)
+USAGE = f"usage: tt <{'|'.join(SUBCOMMANDS)}> [options]\n"
+
+
+def script_path(name, package_dir=None):
+    """Prefer the wheel's bundled copy; fall back to the repository layout."""
+    package_dir = Path(__file__).parent if package_dir is None else Path(package_dir)
+    packaged = package_dir / "_scripts" / f"tt-{name}.py"
+    if packaged.is_file():
+        return packaged
+    return package_dir.resolve().parent / "scripts" / f"tt-{name}.py"
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else list(argv)
+    if argv and argv[0] in ("-h", "--help"):
+        sys.stdout.write(USAGE)
+        return 0
+    if not argv or argv[0] not in SUBCOMMANDS:
+        sys.stderr.write(USAGE)
+        return 2
+    path = script_path(argv[0])
+    sys.argv = [str(path), *argv[1:]]
+    # `python3 script.py` puts the script's directory on sys.path; run_path does not.
+    directory = str(path.parent)
+    sys.path.insert(0, directory)
+    try:
+        runpy.run_path(str(path), run_name="__main__")
+    finally:
+        if directory in sys.path:
+            sys.path.remove(directory)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

trigger_tree/hooks/claude-hooks.json

@@ -0,0 +1,11 @@
+{
+  "hooks": {
+    "SessionStart": [{"hooks": [{"type": "command", "command": "python3", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py", "--client", "claude"], "timeout": 5}]}],
+    "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "python3", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py", "--client", "claude"], "timeout": 5}]}],
+    "SessionEnd": [{"hooks": [{"type": "command", "command": "python3", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py", "--client", "claude"], "timeout": 5}]}],
+    "PostToolUse": [
+      {"matcher": "Bash|Read|Glob|Grep|Skill|mcp__.*", "hooks": [{"type": "command", "command": "python3", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py", "--client", "claude"], "timeout": 5}]}
+    ],
+    "PostToolUseFailure": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "python3", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py", "--client", "claude"], "timeout": 5}]}]
+  }
+}

trigger_tree/hooks/hooks.json

@@ -0,0 +1,9 @@
+{
+  "description": "Collect local documentation-discovery telemetry without affecting Codex commands.",
+  "hooks": {
+    "SessionStart": [{"hooks": [{"type": "command", "command": "if command -v python3 >/dev/null 2>&1; then exec python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py\" --client codex; else exec python \"${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py\" --client codex; fi", "commandWindows": "py -3 \"%CLAUDE_PLUGIN_ROOT%\\scripts\\tt-codex-hook.py\" --client codex", "timeout": 5}]}],
+    "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "if command -v python3 >/dev/null 2>&1; then exec python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py\" --client codex; else exec python \"${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py\" --client codex; fi", "commandWindows": "py -3 \"%CLAUDE_PLUGIN_ROOT%\\scripts\\tt-codex-hook.py\" --client codex", "timeout": 5}]}],
+    "PostToolUse": [{"matcher": "Bash|Read|Glob|Grep|mcp__.*", "hooks": [{"type": "command", "command": "if command -v python3 >/dev/null 2>&1; then exec python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py\" --client codex; else exec python \"${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py\" --client codex; fi", "commandWindows": "py -3 \"%CLAUDE_PLUGIN_ROOT%\\scripts\\tt-codex-hook.py\" --client codex", "timeout": 5}]}],
+    "Stop": [{"hooks": [{"type": "command", "command": "if command -v python3 >/dev/null 2>&1; then exec python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py\" --client codex; else exec python \"${CLAUDE_PLUGIN_ROOT}/scripts/tt-codex-hook.py\" --client codex; fi", "commandWindows": "py -3 \"%CLAUDE_PLUGIN_ROOT%\\scripts\\tt-codex-hook.py\" --client codex", "timeout": 5}]}]
+  }
+}

trigger_tree-1.14.0.dist-info/METADATA

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: trigger-tree
+Version: 1.14.0
+Summary: See which project docs your AI coding agent actually discovers — local, zero-token documentation telemetry.
+Project-URL: Homepage, https://hedde.github.io/trigger_tree/
+Project-URL: Repository, https://github.com/Hedde/trigger_tree
+Project-URL: Changelog, https://github.com/Hedde/trigger_tree/blob/main/CHANGELOG.md
+Author: Hedde van der Heide
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,codex,docs-as-code,documentation,observability,telemetry
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# 🌳 trigger-tree
+
+> **See which project docs your AI actually discovers.**
+
+[![CI](https://github.com/Hedde/trigger_tree/actions/workflows/ci.yml/badge.svg)](https://github.com/Hedde/trigger_tree/actions/workflows/ci.yml)
+[![coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FHedde%2Ftrigger_tree%2Fbadges%2Fcoverage.json)](https://github.com/Hedde/trigger_tree/actions/workflows/ci.yml)
+[![release](https://img.shields.io/github/v/release/Hedde/trigger_tree?label=release)](https://github.com/Hedde/trigger_tree/releases/latest)
+[![PyPI](https://img.shields.io/pypi/v/trigger-tree?label=pypi)](https://pypi.org/project/trigger-tree/)
+[![platforms](https://img.shields.io/badge/platforms-macOS%20·%20Linux%20·%20Windows-lightgrey.svg)](docs/platform-support.md)
+[![docs health](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FHedde%2Ftrigger_tree%2Fbadges%2Fdocs-health.json)](docs/heat-model.md)
+
+<p align="center"><a href="https://hedde.github.io/trigger_tree/"><img src="https://raw.githubusercontent.com/Hedde/trigger_tree/main/docs/assets/dashboard.png" alt="trigger-tree mock dashboard showing documentation reads, searches, heat bars, and prompt browsing" width="900"></a></p>
+
+- Local and dependency-free: no cloud, analytics, or model tokens.
+- Separate heat, lifetime reads, searches, and untouched paths instead of guessing intent.
+- Reduce the evidence to an A–F documentation health grade when detail is unnecessary.
+
+Documentation steers an AI coding assistant toward your team’s patterns and guardrails. But **a rule that is never read protects nothing**. trigger-tree records discovery evidence so you can improve the routes without pretending a read proves understanding.
+
+## Quick start
+
+| Claude Code | Codex |
+|---|---|
+| `/plugin marketplace add Hedde/trigger_tree`<br>`/plugin install trigger-tree@trigger-tree`<br>`/reload-plugins`<br>`/tt watch demo`<br>`/tt setup` · `/tt doctor`<br>Work normally, then `/tt insights` | `codex plugin marketplace add Hedde/trigger_tree`<br>`codex plugin install trigger-tree`<br>Restart Codex<br>Ask it to run `python3 "$PLUGIN_ROOT/scripts/tt-watch.py" --demo`<br>Use the bundled trigger-tree skill for setup, doctor, and insights |
+
+The Claude `/tt` skill is explicitly user-triggered. Codex installs the equivalent skill and lifecycle hooks through its plugin marketplace.
+
+Prefer a standalone CLI — for CI, git-hook ingestion, or dashboards without a plugin?
+`pipx install trigger-tree`, then `tt doctor`, `tt watch --demo`, `tt stats`.
+
+Prompt logging defaults to a recognizable, gitignored local preview of at most 200
+characters as soon as the plugin is installed, even if setup is never run. `/tt setup`
+asks whether to keep `truncate` or switch future events to `hash` or `off`.
+
+## Who gets what?
+
+| You are… | trigger-tree gives you… |
+|---|---|
+| Senior developer | File/folder heat, search evidence, router gaps, and prompt-level browsing |
+| Tech lead | Trends, task clusters, protected-context review, and evidence-backed fixes |
+| Product owner | One honest A–F docs-health signal, provisional until measurement matures |
+
+## Commands
+
+| Command | Result |
+|---|---|
+| `/tt watch demo` | Instant synthetic dashboard; no telemetry required |
+| `/tt setup [truncate\|hash\|off]` | Wire the repo and choose prompt privacy |
+| `/tt doctor` | Check hooks, liveness, scope, privacy, and statusline wiring |
+| `/tt status` | Current heat, lifetime reads, and untouched paths |
+| `/tt watch` | Live mock-TUI dashboard with prompt browsing and sorting |
+| `/tt insights` | Deterministic analysis plus a local HTML report |
+| `/tt suggestions` | Up to five evidence-backed routing improvements |
+| `/tt badge` | Write a public-safe docs-health endpoint JSON |
+| `/tt note <text>` | Add a local timeline annotation |
+| `/tt uninstall` | Remove wiring without deleting telemetry |
+
+Search telemetry is a conservative lower bound; see [measurement boundaries](docs/heat-model.md).
+
+## How it works
+
+1. **Hooks log shell-side** to the gitignored `.trigger-tree/history.jsonl`; failures never interrupt the coding session.
+2. **A deterministic aggregator computes every metric** with Python’s standard library; the model interprets but never counts.
+3. **Discovery remains model-driven**: trigger-tree measures your routers and reads without injecting context or changing routing.
+
+## Where it fits
+
+| Category | Question answered |
+|---|---|
+| Token/trace observability (Langfuse, Arize, W&B) | What did the model call, spend, and produce? |
+| Documentation linters | Is documentation structurally or stylistically valid? |
+| trigger-tree | Which local project docs did the coding assistant actually discover? |
+
+The categories complement each other. trigger-tree does not evaluate answer quality or claim that a read caused an outcome.
+
+## Learn more
+
+[Documentation router](docs/README.md) · [Dashboard](docs/dashboard.md) · [Heat model](docs/heat-model.md) · [Configuration](docs/configuration.md) · [Privacy](docs/privacy.md) · [Glossary](docs/glossary.md) · [FAQ](docs/faq.md) · [Website](https://hedde.github.io/trigger_tree/) · [Changelog](CHANGELOG.md)
+
+MIT © Hedde van der Heide

trigger_tree-1.14.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+trigger_tree/__init__.py,sha256=P9roqhukFAVY8OPVrGOmoCmYxuPDNDodFSRrBYPT_yg,93
+trigger_tree/cli.py,sha256=3jewzuhl2KEt7HZkHrv-2Smbp155LWwH9_YoUmBXOI4,1424
+trigger_tree/_scripts/tt-codex-hook.py,sha256=8My7U_o8QXBA_fuwx--upv6vGMGtVQvaBxngiOQuIB0,3811
+trigger_tree/_scripts/tt-config.sh,sha256=h5zqS6V6pWdrb4ya54TPIi30PzLCR-ptRFEcqxp54ag,1778
+trigger_tree/_scripts/tt-doctor.py,sha256=CObjQQ5IRvZZlXWL-kn14YyauXJMAg__rBMr4sbofEQ,11007
+trigger_tree/_scripts/tt-log.py,sha256=gDDV6qseZr0KkTLoznDtiwMqfJIjf51RXJfFnOL1I0s,23560
+trigger_tree/_scripts/tt-open.sh,sha256=Ha_I3v6Tl5wgx5vfFqTq8OplvmwLAxWhNH8l98dQACE,5660
+trigger_tree/_scripts/tt-publish-badge.sh,sha256=Ks62PoEb_ADznOfRkd8PJWGqs-s6AOQksypHrxqiLzc,902
+trigger_tree/_scripts/tt-report.py,sha256=3w0qFyD9s0lABbGIvR7RQFvX5B6vIj89Yr7qFya85s8,28755
+trigger_tree/_scripts/tt-setup.py,sha256=jgcnHw8mVPfxqUXp3YUuACcucXAput9asua-n_fcMzQ,9914
+trigger_tree/_scripts/tt-shell-capture.sh,sha256=kT7S7JPT2SAdbUF-Z3yz4FKMA76ezlE7YUfQjA8m6U0,1754
+trigger_tree/_scripts/tt-stats.py,sha256=_KkFoVTqJzlxzY-tFSicu1it-Rsmt8DmGJx92FGvfyo,35035
+trigger_tree/_scripts/tt-statusline.py,sha256=dnBE4GVfJQ4bZJFlbvkxS9-2WlteAfos9gLTzn4ZmBo,4948
+trigger_tree/_scripts/tt-suggestions.py,sha256=ijgnsM-4xgngS4RePPjxMXWJCno6D3eMpiuyV-Cs2Gc,5058
+trigger_tree/_scripts/tt-tips.py,sha256=0-_w9RLFqqfuIeYS1GWcLBlIjc6mxwrE3o9U1BmYfkE,3768
+trigger_tree/_scripts/tt-uninstall.py,sha256=nu02WOTe8hx4nUCZ26OkkcGzjzSim3ZOVy2gUPX7Yfw,1984
+trigger_tree/_scripts/tt-watch.py,sha256=crTfhspjTeztOrFWgAQtzZiivlwgx8JrKT_S0SwOEYQ,41355
+trigger_tree/_scripts/tt_runtime.py,sha256=A03j0N3f2_5wfHEOyixfJc7wntSnyZlRzuJyGZZ2tgQ,807
+trigger_tree/_scripts/tt_scope.py,sha256=DcY6DH5baterI6Qa3C7M6UekErjsRGECdEtjhzoyotk,2317
+trigger_tree/_scripts/validate_palette.js,sha256=pRtwOquqLhjMdNkGzU0BF-azvWdUMn7c8Kh2ajuZ3YQ,1526
+trigger_tree/hooks/claude-hooks.json,sha256=RoHiu1sXzYmswtwaOLckpzdlcbMUT5Zx_vI7GUJnMT4,976
+trigger_tree/hooks/hooks.json,sha256=Rzgahpollpbv3GCLan7R2y5oj67jR1w7AOX3BXU-vso,1715
+trigger_tree-1.14.0.dist-info/METADATA,sha256=2tSxuFRsBRrPSb0qp0hW_5deIpYRgbOfVrWKUNyaYeQ,6425
+trigger_tree-1.14.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+trigger_tree-1.14.0.dist-info/entry_points.txt,sha256=uTp1hl7A34dKWl8jSLnGrm9HPKW_UcguKTZ6U8b0i2A,45
+trigger_tree-1.14.0.dist-info/licenses/LICENSE,sha256=IWwYShDdxsqaviOxxvmn6BEz0mLTTWVZZUgGat6khXE,1076
+trigger_tree-1.14.0.dist-info/RECORD,,

trigger_tree-1.14.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

trigger_tree-1.14.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tt = trigger_tree.cli:main

trigger_tree-1.14.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hedde van der Heide
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.