thoughtleaders-cli 0.8.0__tar.gz → 0.8.1__tar.gz

{thoughtleaders_cli-0.8.0 → thoughtleaders_cli-0.8.1}/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "tl-cli",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "ThoughtLeaders CLI — query sponsorship deals, channels, brands, uploads, and intelligence from the terminal",
   "author": {
     "name": "ThoughtLeaders",

{thoughtleaders_cli-0.8.0 → thoughtleaders_cli-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.8.0
+Version: 0.8.1
 Summary: ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence
 Project-URL: Homepage, https://thoughtleaders.io
 Project-URL: Repository, https://github.com/ThoughtLeaders-io/thoughtleaders-cli

{thoughtleaders_cli-0.8.0 → thoughtleaders_cli-0.8.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "thoughtleaders-cli"
-version = "0.8.0"
+version = "0.8.1"
 description = "ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence"
 readme = "README.md"
 license = "MIT"

{thoughtleaders_cli-0.8.0 → thoughtleaders_cli-0.8.1}/src/tl_cli/__init__.py

@@ -1,3 +1,3 @@
 """ThoughtLeaders CLI — query sponsorship data, channels, brands, and intelligence."""
 
-__version__ = "0.8.0"
+__version__ = "0.8.1"

{thoughtleaders_cli-0.8.0 → thoughtleaders_cli-0.8.1}/src/tl_cli/commands/db.py

@@ -4,14 +4,23 @@ import json
 import sys
 
 import typer
+from rich.console import Console
 from tl_cli._typer_utils import AlphaSortedTyperGroup
 
 from tl_cli.client.errors import ApiError, handle_api_error
 from tl_cli.client.http import get_client
 from tl_cli.output.formatter import detect_format, output, output_pricing_estimate
+from tl_cli.query_history import query_hash, record_and_check
 
 app = typer.Typer(cls=AlphaSortedTyperGroup, help="Raw read-only queries against PostgreSQL, Firebolt, or Elasticsearch (full-access only)")
 
+_err = Console(stderr=True)
+
+_NO_REPEAT_WARNING_OPTION = typer.Option(
+    False, "--no-repeat-warning",
+    help="Suppress the warning shown when the same query is re-run repeatedly (also: TL_NO_REPEAT_WARNING=1).",
+)
+
 
 def _read_query(query: str | None) -> str:
     if query is not None and query != "-":
@@ -21,6 +30,24 @@ def _read_query(query: str | None) -> str:
     return sys.stdin.read()
 
 
+def _warn_if_repeat(engine: str, query: str, pricing: bool, suppressed: bool) -> None:
+    """Nudge (on stderr) when this exact query keeps being re-run.
+
+    Detection is local and best-effort; the query always executes.
+    """
+    if suppressed:
+        return
+    count = record_and_check(query_hash(engine, query, pricing))
+    if count is None:
+        return
+    _err.print(
+        f"[yellow]Repeat query:[/yellow] this exact query has now run {count} times "
+        "in the last 5 minutes. Each run is billed and the results are unlikely to "
+        "differ — reuse the earlier output (e.g. save it with `--json > file.json`). "
+        "Pass --no-repeat-warning if the repeats are deliberate."
+    )
+
+
 def _run(path: str, body: dict, fmt: str, title: str, pricing: bool = False) -> None:
     client = get_client()
     try:
@@ -53,16 +80,23 @@ def pg_cmd(
         False, "--pricing",
         help="Estimate the query's credit cost via EXPLAIN without running it (flat 1 credit).",
     ),
+    no_repeat_warning: bool = _NO_REPEAT_WARNING_OPTION,
 ) -> None:
     """Run a raw PostgreSQL SELECT query.
 
+    Column names follow the current schema (e.g. subscribers, projected_views,
+    scheduled_date — not the older reach / impression / send_date). Run
+    `tl schema pg <table>` to see the exact columns your role can query.
+
     Examples:
-        tl db pg "SELECT id, name FROM thoughtleaders_brand LIMIT 10 OFFSET 0"
+        tl db pg "SELECT channel_name, subscribers, projected_views FROM thoughtleaders_channel ORDER BY subscribers DESC LIMIT 10"
+        tl db pg "SELECT id, scheduled_date, publish_status FROM thoughtleaders_adlink LIMIT 20"
         cat query.sql | tl db pg -
         tl db pg "SELECT * FROM thoughtleaders_channel LIMIT 100" --pricing
     """
     fmt = detect_format(json_output, csv_output, md_output, toon_output)
     sql = _read_query(query)
+    _warn_if_repeat("pg", sql, pricing, no_repeat_warning)
     body: dict = {"query": sql}
     if pricing:
         body["pricing"] = True
@@ -80,6 +114,7 @@ def fb_cmd(
         False, "--pricing",
         help="Estimate the query's credit cost without running it (flat 1 credit).",
     ),
+    no_repeat_warning: bool = _NO_REPEAT_WARNING_OPTION,
 ) -> None:
     """Run a raw Firebolt SELECT query.
 
@@ -91,6 +126,7 @@ def fb_cmd(
     """
     fmt = detect_format(json_output, csv_output, md_output, toon_output)
     sql = _read_query(query)
+    _warn_if_repeat("fb", sql, pricing, no_repeat_warning)
     body: dict = {"query": sql}
     if pricing:
         body["pricing"] = True
@@ -112,6 +148,7 @@ def es_cmd(
         False, "--highlight",
         help="Keep ES highlight fragments in each result row. Only meaningful when the query body includes a `highlight` clause; otherwise no-op.",
     ),
+    no_repeat_warning: bool = _NO_REPEAT_WARNING_OPTION,
 ) -> None:
     """Run a raw Elasticsearch search query.
 
@@ -129,6 +166,7 @@ def es_cmd(
     except json.JSONDecodeError as exc:
         raise typer.BadParameter(f"Query is not valid JSON: {exc}") from exc
 
+    _warn_if_repeat("es", raw, pricing, no_repeat_warning)
     body: dict = {"query": body_query}
     if pricing:
         body["pricing"] = True

{thoughtleaders_cli-0.8.0 → thoughtleaders_cli-0.8.1}/src/tl_cli/commands/schema.py

@@ -75,6 +75,15 @@ def _try_render_yaml_tree(content: str) -> bool:
             if fcomment:
                 line.append(f'  — {fcomment}', style='dim')
             tree.add(line)
+
+        # Curated "common traps" for this table (old → new field names, join
+        # hints), surfaced as a sub-branch so it's visible during discovery.
+        common_traps = fields.get('__common_traps')
+        if isinstance(common_traps, list) and common_traps:
+            traps_branch = tree.add(Text('common traps', style='bold red'))
+            for trap in common_traps:
+                traps_branch.add(Text(str(trap), style='dim'))
+
         console.print(tree)
         console.print()
 

thoughtleaders_cli-0.8.1/src/tl_cli/query_history.py

@@ -0,0 +1,94 @@
+"""Local repeat-query detection for `tl db` commands.
+
+Agents sometimes re-run the exact same raw query in a tight loop — losing
+the result, or polling data that will not change — and every run is billed.
+This module keeps a small local log of recent query hashes and decides when
+a repeat warning is due. Everything is best-effort by design: state lives
+in a JSON file next to the CLI config, concurrent runs may race it, and any
+I/O or parse failure resets it — a heuristic warning must never break a
+query.
+"""
+
+import hashlib
+import json
+import os
+import time
+
+from tl_cli.config import CONFIG_DIR
+
+HISTORY_FILE = CONFIG_DIR / "recent_queries.json"
+
+# A repeat is the same normalized query seen REPEAT_THRESHOLD+ times inside
+# WINDOW_S. Warnings re-arm after WARN_INTERVAL_S so a long-running loop is
+# nudged about once a minute rather than on every single run.
+WINDOW_S = 300
+REPEAT_THRESHOLD = 3
+WARN_INTERVAL_S = 60
+
+ENV_SUPPRESS = "TL_NO_REPEAT_WARNING"
+
+
+def query_hash(engine: str, query: str, pricing: bool = False) -> str:
+    """Stable digest for an (engine, query) pair.
+
+    Whitespace runs and letter case don't change what a query does, so they
+    don't change the digest. The engine and the --pricing flag do: the same
+    text against pg vs fb, or a dry-run vs a real run, are different actions.
+    """
+    normalized = " ".join(query.split()).strip().rstrip(";").lower()
+    basis = f"{engine}\x00{'pricing' if pricing else 'run'}\x00{normalized}"
+    return hashlib.sha256(basis.encode("utf-8")).hexdigest()
+
+
+def record_and_check(digest: str) -> int | None:
+    """Record one run of ``digest``; return the run count when a warning is due.
+
+    Returns None below the threshold, while a warning from the last
+    WARN_INTERVAL_S is still fresh, or when TL_NO_REPEAT_WARNING is set.
+    """
+    if os.environ.get(ENV_SUPPRESS):
+        return None
+    now = time.time()
+    state = _load()
+    entry = state.get(digest)
+    entry = entry if isinstance(entry, dict) else {}
+    runs = _recent_runs(entry, now)
+    runs.append(now)
+    warned_at = entry.get("warned_at")
+    warning_fresh = isinstance(warned_at, int | float) and now - warned_at < WARN_INTERVAL_S
+    due = len(runs) >= REPEAT_THRESHOLD and not warning_fresh
+    state[digest] = {"runs": runs, "warned_at": now if due else warned_at}
+    _save(state, now)
+    return len(runs) if due else None
+
+
+def _recent_runs(entry: dict, now: float) -> list[float]:
+    raw = entry.get("runs")
+    if not isinstance(raw, list):
+        return []
+    return [t for t in raw if isinstance(t, int | float) and now - t < WINDOW_S]
+
+
+def _load() -> dict:
+    try:
+        with open(HISTORY_FILE, encoding="utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else {}
+    except (OSError, ValueError):
+        return {}
+
+
+def _save(state: dict, now: float) -> None:
+    pruned = {}
+    for digest, entry in state.items():
+        if not isinstance(entry, dict):
+            continue
+        runs = _recent_runs(entry, now)
+        if runs:
+            pruned[digest] = {"runs": runs, "warned_at": entry.get("warned_at")}
+    try:
+        HISTORY_FILE.parent.mkdir(parents=True, exist_ok=True)
+        with open(HISTORY_FILE, "w", encoding="utf-8") as f:
+            json.dump(pruned, f)
+    except OSError:
+        pass

thoughtleaders_cli-0.8.1/tests/test_db_repeat_warning.py

@@ -0,0 +1,121 @@
+"""Tests for the local repeat-query warning (`tl db` commands)."""
+
+import json
+
+from tl_cli import query_history
+from tl_cli.commands import db
+from tl_cli.query_history import query_hash, record_and_check
+
+
+def _use_tmp_history(monkeypatch, tmp_path):
+    monkeypatch.setattr(query_history, "HISTORY_FILE", tmp_path / "recent_queries.json")
+    monkeypatch.delenv(query_history.ENV_SUPPRESS, raising=False)
+
+
+class TestQueryHash:
+    def test_whitespace_and_case_collapse(self):
+        assert query_hash("pg", "SELECT  1\n  FROM x;") == query_hash("pg", "select 1 from x")
+
+    def test_engines_do_not_collide(self):
+        assert query_hash("pg", "SELECT 1") != query_hash("fb", "SELECT 1")
+
+    def test_pricing_dry_run_is_distinct(self):
+        assert query_hash("pg", "SELECT 1") != query_hash("pg", "SELECT 1", pricing=True)
+
+    def test_different_literals_are_different_queries(self):
+        # Pagination (OFFSET 0/100/200) must never look like a repeat.
+        assert query_hash("pg", "SELECT 1 OFFSET 0") != query_hash("pg", "SELECT 1 OFFSET 100")
+
+
+class TestRecordAndCheck:
+    def test_warns_on_third_run_only(self, monkeypatch, tmp_path):
+        _use_tmp_history(monkeypatch, tmp_path)
+        digest = query_hash("pg", "SELECT 1")
+        assert record_and_check(digest) is None
+        assert record_and_check(digest) is None
+        assert record_and_check(digest) == 3
+
+    def test_warn_once_per_interval(self, monkeypatch, tmp_path):
+        _use_tmp_history(monkeypatch, tmp_path)
+        digest = query_hash("pg", "SELECT 1")
+        for _ in range(3):
+            record_and_check(digest)
+        # 4th and 5th runs arrive while the warning is still fresh.
+        assert record_and_check(digest) is None
+        assert record_and_check(digest) is None
+
+    def test_rewarns_after_interval_elapses(self, monkeypatch, tmp_path):
+        _use_tmp_history(monkeypatch, tmp_path)
+        digest = query_hash("pg", "SELECT 1")
+        now = 1_000_000.0
+        monkeypatch.setattr(query_history.time, "time", lambda: now)
+        for _ in range(4):
+            record_and_check(digest)
+        monkeypatch.setattr(
+            query_history.time, "time", lambda: now + query_history.WARN_INTERVAL_S + 1
+        )
+        assert record_and_check(digest) == 5
+
+    def test_runs_age_out_of_window(self, monkeypatch, tmp_path):
+        _use_tmp_history(monkeypatch, tmp_path)
+        digest = query_hash("pg", "SELECT 1")
+        now = 1_000_000.0
+        monkeypatch.setattr(query_history.time, "time", lambda: now)
+        record_and_check(digest)
+        record_and_check(digest)
+        monkeypatch.setattr(
+            query_history.time, "time", lambda: now + query_history.WINDOW_S + 1
+        )
+        # Both earlier runs expired: this is a fresh run 1, not run 3.
+        assert record_and_check(digest) is None
+
+    def test_env_var_suppresses(self, monkeypatch, tmp_path):
+        _use_tmp_history(monkeypatch, tmp_path)
+        monkeypatch.setenv(query_history.ENV_SUPPRESS, "1")
+        digest = query_hash("pg", "SELECT 1")
+        for _ in range(5):
+            assert record_and_check(digest) is None
+
+    def test_corrupt_state_file_is_tolerated(self, monkeypatch, tmp_path):
+        _use_tmp_history(monkeypatch, tmp_path)
+        (tmp_path / "recent_queries.json").write_text("{not json", encoding="utf-8")
+        digest = query_hash("pg", "SELECT 1")
+        assert record_and_check(digest) is None
+        # State was reset and is valid JSON again.
+        state = json.loads((tmp_path / "recent_queries.json").read_text(encoding="utf-8"))
+        assert digest in state
+
+    def test_other_hashes_pruned_when_stale(self, monkeypatch, tmp_path):
+        _use_tmp_history(monkeypatch, tmp_path)
+        now = 1_000_000.0
+        monkeypatch.setattr(query_history.time, "time", lambda: now)
+        record_and_check(query_hash("pg", "SELECT 1"))
+        monkeypatch.setattr(
+            query_history.time, "time", lambda: now + query_history.WINDOW_S + 1
+        )
+        record_and_check(query_hash("pg", "SELECT 2"))
+        state = json.loads((tmp_path / "recent_queries.json").read_text(encoding="utf-8"))
+        assert list(state) == [query_hash("pg", "SELECT 2")]
+
+
+class TestWarnIfRepeat:
+    def test_prints_warning_on_third_run(self, monkeypatch, tmp_path, capsys):
+        _use_tmp_history(monkeypatch, tmp_path)
+        for _ in range(3):
+            db._warn_if_repeat("pg", "SELECT 1", False, False)
+        err = capsys.readouterr().err
+        assert "Repeat query" in err
+        assert "3 times" in err
+        assert "--no-repeat-warning" in err
+
+    def test_flag_suppresses(self, monkeypatch, tmp_path, capsys):
+        _use_tmp_history(monkeypatch, tmp_path)
+        for _ in range(5):
+            db._warn_if_repeat("pg", "SELECT 1", False, True)
+        assert "Repeat query" not in capsys.readouterr().err
+
+    def test_silent_below_threshold(self, monkeypatch, tmp_path, capsys):
+        _use_tmp_history(monkeypatch, tmp_path)
+        db._warn_if_repeat("pg", "SELECT 1", False, False)
+        db._warn_if_repeat("pg", "SELECT 2", False, False)
+        assert "Repeat query" not in capsys.readouterr().err

{thoughtleaders_cli-0.8.0 → thoughtleaders_cli-0.8.1}/uv.lock

@@ -434,7 +434,7 @@ wheels = [
 
 [[package]]
 name = "thoughtleaders-cli"
-version = "0.7.12"
+version = "0.8.1"
 source = { editable = "." }
 dependencies = [
     { name = "authlib" },