thoughtleaders-cli 0.8.0__py3-none-any.whl → 0.8.1__py3-none-any.whl

{thoughtleaders_cli-0.8.0.dist-info → thoughtleaders_cli-0.8.1.dist-info}/METADATA

@@ -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.dist-info → thoughtleaders_cli-0.8.1.dist-info}/RECORD

@@ -1,10 +1,11 @@
-tl_cli/__init__.py,sha256=1LIQDuzeCXPfeG6VDqnZBiedaT4NAAxugkO_jWADk-s,112
+tl_cli/__init__.py,sha256=3cLM1cLW88E02sVZNV24Xh_GnreB0RbNrhvhwp2GlJU,112
 tl_cli/_completions.py,sha256=kOyEUqC26vbYvyXWi513WX8fF73qQLR5WWuRSe_wqyk,164
 tl_cli/_typer_utils.py,sha256=ZiZsCVmEznPvBw-dYbr3tu3zWZ0iN6kjoQmK3gMqD28,860
 tl_cli/config.py,sha256=UV_OYTXuQnAIqbi_oVCXx0hhIdZWR678RRapVv51UwQ,1859
 tl_cli/filters.py,sha256=Yjj04lONGGmtCAIYN5i6KD12mAnUKEZ7i9heeWtdj7o,2952
 tl_cli/hints.py,sha256=cT8kuDtkAZqwXkc2RV0Yg_abofK-g9UiXwTTBunX78U,1557
 tl_cli/main.py,sha256=A_8b2SQjBKATxrjO7AGC5Ab1QWlP35gGo4TWzYZtlOM,5806
+tl_cli/query_history.py,sha256=tj9AxI2ADoC8a92Oacoyuljtqc_PPzA6o2X0Adhs2N8,3336
 tl_cli/self_update.py,sha256=zLPCSzPQTHRAcTZTBBopRxAs5Bg-B7Ag_7PxfN94QOI,18800
 tl_cli/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/auth/commands.py,sha256=CkCaKFb-xUwhCeIL92EC4-odiaSpLI1bmgg5tDCrclM,7387
@@ -22,7 +23,7 @@ tl_cli/commands/bulk_import.py,sha256=d4y1k_lD52LPJcCqXxEmyHIqcIwomZgbjqs1_QxPje
 tl_cli/commands/changelog.py,sha256=D1PtDdHpawTlWqUHjKzVmv9yXLSU915UVmI3dZzEwyA,4241
 tl_cli/commands/channels.py,sha256=gs6jHaxi6WjB3D8jnJETFVvkTXpqzlWR-W4JkBeG3oY,20406
 tl_cli/commands/credits.py,sha256=2xCht2e420LmaFBKNdKoMz8GlTh31qSWSlJAnVzoZic,7308
-tl_cli/commands/db.py,sha256=PS2HxB3gxp9j-plQtqOxnWgyVTJgnjcuZSJJ_-C10uY,5453
+tl_cli/commands/db.py,sha256=JaiXLMB_ROkLS-ca6QHyMt-z2lrZlDlj6xqyralIKjQ,7209
 tl_cli/commands/deals.py,sha256=ZK9yneInsC6DXoCPS65oyLoVR0eRW1xdRlEN7oRp1pc,2174
 tl_cli/commands/describe.py,sha256=3lURv4NllM5qPeMEBbejrIxiMzsyTwpJIz211-wuGCU,12362
 tl_cli/commands/doctor.py,sha256=KUKglwhMc7B26XXy_3M0LkHu7wqfFO5T0YPHO1SH1VY,9024
@@ -30,7 +31,7 @@ tl_cli/commands/matches.py,sha256=K5o6B8FLECp7825dU4W3X8n-wuXvGJz57xpQPXeXQ-0,28
 tl_cli/commands/proposals.py,sha256=IXx9DsR7lPWRM4QvKB65t7xKNAK3H6ax9LIlIj8ydEs,2945
 tl_cli/commands/recommender.py,sha256=BZfviKAPhpZah0zaSyH5RDa23fG8QAkUnG5FDhOdi4I,21324
 tl_cli/commands/reports.py,sha256=7CL2atr0Y4XSE8U8kbuZ5-M-m3E9PKNZ0N_0Fbd_OkQ,26388
-tl_cli/commands/schema.py,sha256=GCBEE4fDatQhVasLKKr7bkGhELRZ0scYm_hUCbDYmuA,5985
+tl_cli/commands/schema.py,sha256=rmfg5pvKHa5kQi59YBIHCMzBNawmYPi2tBMcZP7Vrxw,6432
 tl_cli/commands/setup.py,sha256=ypimHsp45yYSWwTLywfYtPC2P_45X4arW0K3SFuwEXk,28398
 tl_cli/commands/snapshots.py,sha256=exlxFwMcM1BCiDTcE9dZfaSdRO-sxaTxtWzJmEoUVWI,3434
 tl_cli/commands/sponsorships.py,sha256=PdWCm9E4mrs_qlHtckMp99JmuRP94hthlqoWMi0k4tc,10471
@@ -39,7 +40,7 @@ tl_cli/commands/whoami.py,sha256=aUXwBRwh1vAGrvz8CKGfHYtEOKJCIDfwrGesKAwYZMk,786
 tl_cli/output/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 tl_cli/output/formatter.py,sha256=zWwcg4yovMXLaduxu8skpDjPVLTaGZAmwtYwjpZDg1w,22766
 tl_cli/_plugin/.claude-plugin/marketplace.json,sha256=l56PMmyjfGXNGlV30wRyOAe74B6gJNCVNCxgsBbSNxc,446
-tl_cli/_plugin/.claude-plugin/plugin.json,sha256=Ozb2Tc982THa78GZNvX3xvg62HnOH6HiwmZ-j8h5rt4,466
+tl_cli/_plugin/.claude-plugin/plugin.json,sha256=00UrTvRCuztsF2A3nu5I4KUCmjp4FswlBfBBfCEAPiQ,466
 tl_cli/_plugin/agents/tl-analyst.md,sha256=ANAQFO_Qrx2MYOOa2yTsJjhJUYJg7DQUWaHbCeL_2II,6752
 tl_cli/_plugin/agents/youtube-comment-classifier.md,sha256=S5lr_htA98FIX0su8FJ2ntiHfbdK8OB2NQKC4lTnQcw,2178
 tl_cli/_plugin/hooks/hooks.json,sha256=FSWibw1xAjA-suFV3fR8btIb2kQ82LQ08otTr-NpmFw,835
@@ -91,8 +92,8 @@ tl_cli/_plugin/skills/tl-top-partnerships/SKILL.md,sha256=jOMMr40XRnAZv-oRLeyKJT
 tl_cli/_plugin/skills/tl-top-partnerships/scripts/top_partnerships.py,sha256=OqhoyvFe1zrtrStChcam7oPYgFnSbGHC3WAgLhLIC3w,13738
 tl_cli/_plugin/skills/tl-views-guarantee/SKILL.md,sha256=IH7q1WJDWri9TWJMiga1FMGJO_GKSbWwaDS6CVNZ9c0,9270
 tl_cli/_plugin/skills/tl-views-guarantee/scripts/vg.py,sha256=Qp5poinHEqh9374anq0bLtlxj2YL6ipBicaT960-Cws,15825
-thoughtleaders_cli-0.8.0.dist-info/METADATA,sha256=woPiWi6h1T9aCyjiMOGZDDq3ckFsI0yogHLQxFrubVY,18921
-thoughtleaders_cli-0.8.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-thoughtleaders_cli-0.8.0.dist-info/entry_points.txt,sha256=umZp-1BkGkHDG0bNZXpTXrjwW0HGf9IDFN40eAWuuvg,39
-thoughtleaders_cli-0.8.0.dist-info/licenses/LICENSE,sha256=RUfdfLsn6jygiyrnnVUHt6r4IPwr2rbDm9Kixgtu8fo,1071
-thoughtleaders_cli-0.8.0.dist-info/RECORD,,
+thoughtleaders_cli-0.8.1.dist-info/METADATA,sha256=WChLIRKUDDGwu_3Gagdg_ltJywinX7vGY85KBYjEzF0,18921
+thoughtleaders_cli-0.8.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+thoughtleaders_cli-0.8.1.dist-info/entry_points.txt,sha256=umZp-1BkGkHDG0bNZXpTXrjwW0HGf9IDFN40eAWuuvg,39
+thoughtleaders_cli-0.8.1.dist-info/licenses/LICENSE,sha256=RUfdfLsn6jygiyrnnVUHt6r4IPwr2rbDm9Kixgtu8fo,1071
+thoughtleaders_cli-0.8.1.dist-info/RECORD,,

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"

tl_cli/_plugin/.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",

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

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()
 

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