thoughtleaders-cli 0.6.27__tar.gz → 0.6.30__tar.gz

{thoughtleaders_cli-0.6.27 → thoughtleaders_cli-0.6.30}/.claude-plugin/plugin.json

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

{thoughtleaders_cli-0.6.27 → thoughtleaders_cli-0.6.30}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: thoughtleaders-cli
-Version: 0.6.27
+Version: 0.6.30
 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.6.27 → thoughtleaders_cli-0.6.30}/pyproject.toml

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

{thoughtleaders_cli-0.6.27 → thoughtleaders_cli-0.6.30}/skills/tl-import/SKILL.md

@@ -57,14 +57,36 @@ Steps:
    - `brands` → **2** (BRANDS)
    - `articles` (uploads/videos) → **1** (CONTENT)
    - `sponsorships` (adlinks/deals) → **8** (CAMPAIGN_MANAGEMENT)
-4. **Pick default columns.** Read the matching columns reference file in the sibling `tl-report-builder` skill and use its **"always include"** defaults — do NOT duplicate the list inline here, that's where the canonical default lives:
-   - channels → `../tl-report-builder/references/columns_channels.md` (look for the "Defaults — always include" section)
+4. **Pick default columns.** Read the matching columns reference file in the sibling `tl-report-builder` skill and use its **"Defaults — always include"** section — that's where the canonical column list lives per type; do NOT restate it here. The four files:
+   - channels → `../tl-report-builder/references/columns_channels.md`
    - brands → `../tl-report-builder/references/columns_brands.md`
    - articles → `../tl-report-builder/references/columns_content.md`
    - sponsorships → `../tl-report-builder/references/columns_sponsorships.md`
 
-   Convert the column display names into the dict shape: `{"Channel": {"display": true}, "TL Channel Summary": {"display": true}, …}`.
-5. **Compose the minimal config:**
+   Convert each display name from the "Defaults — always include" list into a column entry shape **`{"display": true, "width": "default"}`** — the `width` field is required by the dashboard's column renderer; without it, columns sometimes resolve but cells render empty. Use `"wide"` for narrative columns (e.g. `TL Channel Summary`, `Channel Description`, `Topic Descriptions`); use `"narrow"` for short numeric columns (e.g. `Status`, `Country`); `"default"` everywhere else is safe.
+
+5. **Pick `dataset_structure`.** This block tells the dashboard's data plane how to query each row's cell values. **Without it the report saves but rows render empty** — see the bottom-of-section sanity check. Shape:
+
+   ```json
+   "dataset_structure": {
+     "report_type": <same as the top-level report_type>,
+     "page_size": 50,
+     "sort": "<backend_code field, optionally -prefixed for descending>"
+   }
+   ```
+
+   Per-type default sort. **Critical invariant:** the `sort` field must reference a `backend_code` whose display-name column is in the column set you emitted in step 4. The dashboard's renderer rejects sorts pointing at columns that aren't present in the report. So pick the intersection of (a) the type's "Defaults — always include" columns from `columns_<type>.md` and (b) sortable columns from `../tl-report-builder/references/sortable_columns.json`:
+
+   | report_type | entity | default `sort` | maps to (must be in column set) |
+   |---|---|---|---|
+   | 3 | channels | `-reach` | `Subscribers` (in defaults) |
+   | 2 | brands | `-doc_count` | `Mentions` (in defaults) |
+   | 1 | articles | `-publication_date` | `Date` (in defaults) |
+   | 8 | sponsorships | `-send_date` | `Scheduled Date` (in defaults) |
+
+   If the user explicitly asked for a different sort, honor that — but if their preferred sort column isn't in the type's defaults, **add that column to the column set in step 4** before emitting the config. Sort pointing at an absent column re-creates the original render-failure bug.
+
+6. **Compose the minimal config:**
 
    ```json
    {
@@ -73,12 +95,13 @@ Steps:
      "report_type": <from step 3>,
      "type": 2,
      "filterset": {},
-     "columns": <from step 4>
+     "columns": <from step 4>,
+     "dataset_structure": <from step 5>
    }
    ```
 
-   `type: 2` is DYNAMIC (the only valid campaign type for save). `filterset: {}` is intentional — no keyword/topic/demographic filters; the report's contents will come entirely from the include list bulk-import populates next.
-6. **Persist via the same primitive `tl-report-builder` uses.** Write the config dict to a temp file using your file-writing tool — **do not use shell `echo` or heredocs**, those break on titles containing apostrophes, dollar signs, backticks, etc. The whole point of `--config-file` is to bypass shell quoting entirely. Pick any temp path the agent's filesystem tool can write to (e.g. `/tmp/tl-import-container.json` on Unix, the OS temp dir on Windows).
+   `type: 2` is DYNAMIC (the only valid campaign type for save). `filterset: {}` is intentional — no keyword/topic/demographic filters; the report's contents will come entirely from the include list bulk-import populates next. **`dataset_structure` is what makes the rows render with actual values** — leave it out and the dashboard shows row numbers but blank cells.
+7. **Persist via the same primitive `tl-report-builder` uses.** Write the config dict to a temp file using your file-writing tool — **do not use shell `echo` or heredocs**, those break on titles containing apostrophes, dollar signs, backticks, etc. The whole point of `--config-file` is to bypass shell quoting entirely. Pick any temp path the agent's filesystem tool can write to (e.g. `/tmp/tl-import-container.json` on Unix, the OS temp dir on Windows).
 
    Then run:
 
@@ -88,9 +111,21 @@ Steps:
 
    With `--yes --json` the CLI emits a single JSON document on stdout containing the save response — parse it with one `json.loads()` and pull out `campaign_id` (and `report_url` for the summary). If `tl reports create` returns HTTP 400 with `Missing required field: report_title` or `…report_description`, the config is malformed — re-check step 1/2.
 
-7. **Hand off to bulk-import** using the new `campaign_id` as if the user had supplied it. Continue with "Inputs to gather" and the rest of this skill below.
+8. **Run bulk-import, capture the result — but DO NOT render the success summary yet.** Hand off to the bulk-import path with the new `campaign_id` and execute "Inputs to gather" + the bulk-import call + the JSON-envelope parse. **Stop before** rendering the per-row classification table or any "import done" message. Step 9 below must run first; only then do you render the summary. If you find yourself about to emit the success markdown straight out of the bulk-import flow, stop — you skipped step 9.
+
+9. **Post-import render check (must execute before any success summary is emitted).** The save accepts the config; the renderer can still drop columns silently (e.g. `sort` points at a column you didn't emit, or `width` is missing on entries that needed it). Run:
+
+   ```bash
+   tl reports run <campaign_id> --limit 3 --json
+   ```
+
+   - If `results` is non-empty AND each row has fields beyond just an ID → render works. Now surface the bulk-import success summary (headline + per-row classification table) plus the new report URL.
+   - If `results` is non-empty but each row is mostly null/empty fields → the config has a render bug. Surface to the user **instead of** the normal success message: *"The bulk-import succeeded but the report is rendering with empty cells. Add columns via the dashboard UI, or delete and re-run the import."* Don't hide this — the import already happened; the user needs to know they have a partially-broken report. Still include the bulk-import's `inputs` classification table so they see what landed.
+   - If `results` is unexpectedly empty (shouldn't happen post-bulk-import unless every row failed) → surface the bulk-import's `inputs` table to explain which rows failed; skip the "Created [report] and imported N" headline since N=0.
+
+   *Cost: a small report-run credit. Worth it — silently handing the user a report whose cells are blank is worse than telling them upfront.*
 
-Surface the new report URL alongside the bulk-import results in the final summary, e.g. *"Created [Q1 cohort](https://app.thoughtleaders.io/#/thoughtleaders?campaign=23859) and imported 50 channels:"* followed by the per-row table.
+Once step 9 passes, surface the new report URL alongside the bulk-import results in the final summary, e.g. *"Created [Q1 cohort](https://app.thoughtleaders.io/#/thoughtleaders?campaign=23859) and imported 50 channels:"* followed by the per-row table.
 
 ## Inputs to gather
 

{thoughtleaders_cli-0.6.27 → thoughtleaders_cli-0.6.30}/src/tl_cli/__init__.py

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

{thoughtleaders_cli-0.6.27 → thoughtleaders_cli-0.6.30}/src/tl_cli/self_update.py

@@ -23,10 +23,12 @@ from pathlib import Path
 
 from tl_cli import __version__
 
-CACHE_PATH = Path.home() / ".cache" / "tl-cli" / "version-check.json"
+CACHE_DIR = Path.home() / ".cache" / "tl-cli"
+CACHE_PATH = CACHE_DIR / "version-check.json"
 CACHE_TTL_SECONDS = 3600  # 1 hour
 LATEST_URL = "https://api.github.com/repos/ThoughtLeaders-io/thoughtleaders-cli/releases/latest"
 REQUEST_TIMEOUT = 2  # tight — the user is already waiting to see their shell prompt back
+WIN_UPGRADE_RESCHEDULE_WINDOW = 600  # 10 minutes: don't re-schedule a background upgrade we already queued
 
 
 def _detect_install_method() -> str | None:
@@ -92,17 +94,24 @@ REPO_URL = "https://github.com/ThoughtLeaders-io/thoughtleaders-cli.git"
 
 
 def _run_upgrade(method: str, latest: str) -> None:
-    """Block briefly to run the upgrade. Progress goes to stderr so piped
-    stdout stays clean.
+    """Run the upgrade. Progress goes to stderr so piped stdout stays clean.
 
     Uses `install --force` with the new tag URL. pipx/uv pin the original
     install spec including the git tag, so a plain `upgrade` re-installs
     the same version — `--force` is the only way to advance the pinned tag.
 
-    On a successful upgrade, re-syncs Claude Code and OpenCode skills if
-    their respective binaries are on PATH, so the new version's skills
-    land in ~/.claude/ and ~/.config/opencode/ without the user having
-    to remember to run `tl setup ...`.
+    On Windows the running tl.exe holds an exclusive lock on its own file,
+    so pipx/uv can never replace it in-process — every attempt fails with
+    WinError 32 and leaves ``~``-prefixed orphan dirs in site-packages
+    that wedge the next launch with ``ModuleNotFoundError: No module
+    named 'tl_cli'``. The Windows path spawns a detached helper instead
+    that waits for our PID to exit and then runs the upgrade.
+
+    On a successful upgrade (POSIX inline path, or the detached helper),
+    Claude Code and OpenCode skills are re-synced if their binaries are
+    on PATH, so the new version's skills land in ~/.claude/ and
+    ~/.config/opencode/ without the user having to remember to run
+    `tl setup ...`.
     """
     tagged_url = f"git+{REPO_URL}@v{latest}"
     cmd = {
@@ -111,14 +120,25 @@ def _run_upgrade(method: str, latest: str) -> None:
     }.get(method)
     if not cmd:
         return
+
+    if sys.platform == "win32":
+        if _spawn_detached_windows_upgrade(cmd, latest):
+            print(
+                f"[tl-cli] upgrade {__version__} → {latest} scheduled "
+                f"(runs after this command exits; log: "
+                f"{CACHE_DIR / f'upgrade-{latest}.log'})",
+                file=sys.stderr,
+            )
+            _mark_upgrade_scheduled(latest)
+        return
+
     print(
         f"[tl-cli] upgrading {__version__} → {latest} via {method}…",
         file=sys.stderr,
     )
-    # Capture output so a noisy traceback from a broken upgrader (seen on
-    # Windows pipx shims that lose track of their own module) doesn't get
-    # dumped into the user's shell — we surface it deliberately on failure
-    # alongside an actionable next-step message.
+    # Capture output so a noisy traceback from a broken upgrader doesn't
+    # get dumped into the user's shell — we surface it deliberately on
+    # failure alongside an actionable next-step message.
     try:
         result = subprocess.run(cmd, check=False, timeout=60, capture_output=True, text=True)
     except (OSError, subprocess.TimeoutExpired) as exc:
@@ -134,6 +154,146 @@ def _run_upgrade(method: str, latest: str) -> None:
     _report_upgrade_failure(method, cmd, result)
 
 
+def _spawn_detached_windows_upgrade(cmd: list[str], latest: str) -> bool:
+    """Schedule the upgrade to run after this process exits.
+
+    Writes a small .cmd helper that polls until our PID disappears and
+    then runs the upgrader. Spawned with CREATE_NO_WINDOW |
+    CREATE_BREAKAWAY_FROM_JOB so it survives this process and any
+    job-object-owned shell that launched us. Output is appended to a
+    log file under ~/.cache/tl-cli/ so the user can diagnose failures
+    after their shell prompt returns.
+
+    Returns True on successful schedule. Idempotent against repeated
+    invocations: see `_already_scheduled`.
+    """
+    import os
+
+    try:
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        print(
+            f"[tl-cli] could not create cache dir for upgrade helper: {exc}",
+            file=sys.stderr,
+        )
+        return False
+
+    log_path = CACHE_DIR / f"upgrade-{latest}.log"
+    script_path = CACHE_DIR / f"upgrade-{latest}.cmd"
+    # Per-helper temp file for tasklist output (a pipe would die; see below).
+    tmp_path = CACHE_DIR / f"upgrade-{latest}.tasklist.tmp"
+
+    parent_pid = os.getpid()
+    quoted_cmd = " ".join(f'"{a}"' for a in cmd)
+
+    # CRLF line endings + cmd.exe-safe quoting.
+    #
+    # We deliberately avoid the pipe-based idiom `tasklist | findstr`: a
+    # detached cmd.exe (CREATE_NO_WINDOW | CREATE_BREAKAWAY_FROM_JOB) has
+    # no console for the pipe sub-shells to attach to, and they exit
+    # silently the moment the helper hits a `|`. Routing through a temp
+    # file keeps every command as a plain redirected child.
+    script = (
+        "@echo off\r\n"
+        f'echo [tl-cli upgrader] waiting for parent PID {parent_pid} to exit > "{log_path}"\r\n'
+        ":wait\r\n"
+        f'tasklist /FI "PID eq {parent_pid}" /NH 2>NUL > "{tmp_path}"\r\n'
+        f'findstr /C:"{parent_pid}" "{tmp_path}" >NUL\r\n'
+        "if not errorlevel 1 (\r\n"
+        "    ping -n 2 127.0.0.1 >NUL\r\n"
+        "    goto wait\r\n"
+        ")\r\n"
+        f'del "{tmp_path}" 2>NUL\r\n'
+        f'echo [tl-cli upgrader] running: {quoted_cmd} >> "{log_path}"\r\n'
+        f'{quoted_cmd} >> "{log_path}" 2>&1\r\n'
+        "set RC=%ERRORLEVEL%\r\n"
+        f'echo [tl-cli upgrader] exit code %RC% >> "{log_path}"\r\n'
+        "if not %RC%==0 goto end\r\n"
+        "where claude >NUL 2>&1\r\n"
+        "if not errorlevel 1 (\r\n"
+        f'    echo [tl-cli upgrader] re-syncing claude skills >> "{log_path}"\r\n'
+        f'    tl setup claude --json >> "{log_path}" 2>&1\r\n'
+        ")\r\n"
+        "where opencode >NUL 2>&1\r\n"
+        "if not errorlevel 1 (\r\n"
+        f'    echo [tl-cli upgrader] re-syncing opencode skills >> "{log_path}"\r\n'
+        f'    tl setup opencode --json >> "{log_path}" 2>&1\r\n'
+        ")\r\n"
+        ":end\r\n"
+    )
+
+    try:
+        script_path.write_text(script)
+    except OSError as exc:
+        print(f"[tl-cli] could not write upgrade helper: {exc}", file=sys.stderr)
+        return False
+
+    # creationflags constants — repeated here rather than referenced from
+    # subprocess.* so this works on Python builds where the symbols are
+    # guarded behind sys.platform checks.
+    #
+    # CREATE_NO_WINDOW (not DETACHED_PROCESS): a fully-detached cmd.exe
+    # has no console for spawned child commands to inherit, which breaks
+    # piped sub-shells and a few utilities that try to query the console.
+    # CREATE_NO_WINDOW gives us "no visible window" while keeping the
+    # console subsystem available for children.
+    CREATE_NEW_PROCESS_GROUP = 0x00000200
+    CREATE_BREAKAWAY_FROM_JOB = 0x01000000
+    CREATE_NO_WINDOW = 0x08000000
+
+    try:
+        subprocess.Popen(
+            ["cmd.exe", "/c", str(script_path)],
+            creationflags=(
+                CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP | CREATE_BREAKAWAY_FROM_JOB
+            ),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            close_fds=True,
+            cwd=str(CACHE_DIR),
+        )
+    except OSError as exc:
+        print(
+            f"[tl-cli] could not schedule background upgrade: {exc}\n"
+            f"[tl-cli] upgrade manually with:\n  {quoted_cmd}",
+            file=sys.stderr,
+        )
+        return False
+    return True
+
+
+def _mark_upgrade_scheduled(latest: str) -> None:
+    """Record in the version-check cache that we've queued a background
+    upgrade for ``latest`` so subsequent invocations don't re-schedule
+    while the first helper is still pending."""
+    try:
+        cache = json.loads(CACHE_PATH.read_text())
+    except (OSError, json.JSONDecodeError):
+        cache = {}
+    cache["scheduled_at"] = time.time()
+    cache["scheduled_for"] = latest
+    try:
+        CACHE_PATH.parent.mkdir(parents=True, exist_ok=True)
+        CACHE_PATH.write_text(json.dumps(cache))
+    except OSError:
+        pass
+
+
+def _already_scheduled(latest: str) -> bool:
+    """True if we recently queued the same upgrade — caller should skip."""
+    try:
+        cache = json.loads(CACHE_PATH.read_text())
+    except (OSError, json.JSONDecodeError):
+        return False
+    if cache.get("scheduled_for") != latest:
+        return False
+    scheduled_at = cache.get("scheduled_at")
+    if not isinstance(scheduled_at, (int, float)):
+        return False
+    return time.time() - scheduled_at < WIN_UPGRADE_RESCHEDULE_WINDOW
+
+
 def _report_upgrade_failure(method: str, cmd: list[str], result: subprocess.CompletedProcess) -> None:
     """Print a user-friendly failure message after a non-zero upgrader exit.
 
@@ -215,6 +375,11 @@ def check_and_upgrade() -> None:
         except ValueError:
             return
 
+        # On Windows the upgrade is detached: don't re-queue it on every
+        # subsequent tl invocation while the first helper is still pending.
+        if sys.platform == "win32" and _already_scheduled(latest):
+            return
+
         _run_upgrade(method, latest)
     except Exception:
         # Never let a version-check bug break the user's workflow.