creatorloop 0.1.0__py3-none-any.whl

creatorloop/setup_cli.py

@@ -0,0 +1,175 @@
+"""Add the "creatorloop" MCP server to the Claude Desktop config (keeps all other settings).
+
+Usage (from the project folder, on Windows, macOS or Linux):
+    uv run creatorloop-setup [--config PATH] [--no-restart]
+
+Claude Desktop rewrites its config from memory while it runs, so the config is only written while
+Desktop is closed: on macOS this command quits and reopens it, elsewhere it asks you to quit it first.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+import time
+from collections.abc import Mapping
+from datetime import datetime
+from pathlib import Path
+
+from creatorloop import DISCLAIMER, paths
+
+CONFIG_NAME = "claude_desktop_config.json"
+MAC_APP_BINARY = "Claude.app/Contents/MacOS/Claude$"
+QUIT_TIMEOUT_S = 30
+
+
+def config_candidates(platform: str, *, home: Path, env: Mapping[str, str]) -> list[Path]:
+    """Where Claude Desktop keeps its config on this OS, most usual location first."""
+    if platform == "win32":
+        candidates = [Path(env.get("APPDATA", home / "AppData" / "Roaming")) / "Claude" / CONFIG_NAME]
+        # Microsoft Store (MSIX) build keeps a virtualised copy of %APPDATA%
+        if local := env.get("LOCALAPPDATA"):
+            for pkg in sorted((Path(local) / "Packages").glob("Claude_*")):
+                candidates.append(pkg / "LocalCache" / "Roaming" / "Claude" / CONFIG_NAME)
+        return candidates
+    if platform == "darwin":
+        return [home / "Library" / "Application Support" / "Claude" / CONFIG_NAME]
+    return [Path(env.get("XDG_CONFIG_HOME") or home / ".config") / "Claude" / CONFIG_NAME]
+
+
+def pick_targets(candidates: list[Path]) -> list[Path]:
+    """Every config that already exists; if none does, the first (default) location."""
+    return [p for p in candidates if p.exists()] or candidates[:1]
+
+
+def find_uv() -> str | None:
+    if found := shutil.which("uv"):
+        return found
+    # Claude Desktop does not inherit the shell PATH: we need an absolute path anyway
+    exe = "uv.exe" if sys.platform == "win32" else "uv"
+    for d in (Path.home() / ".local" / "bin", Path.home() / ".cargo" / "bin", Path("/opt/homebrew/bin"), Path("/usr/local/bin")):
+        if (d / exe).exists():
+            return str(d / exe)
+    return None
+
+
+def server_entry(*, uv: str, source: Path | None) -> dict:
+    """How Claude Desktop starts the server: from this source checkout, or the published package (= uvx)."""
+    if source is not None:
+        return {"command": uv, "args": ["--directory", str(source), "run", "creatorloop"]}
+    return {"command": uv, "args": ["tool", "run", "creatorloop"]}
+
+
+def install(config_path: Path, *, entry: dict) -> Path | None:
+    """Write the server entry; return the backup path (None when the config did not exist)."""
+    backup = None
+    config: dict = {}
+    if config_path.exists():
+        raw = config_path.read_text(encoding="utf-8-sig")  # tolerate a BOM left by Windows editors
+        if raw.strip():
+            try:
+                config = json.loads(raw)
+            except json.JSONDecodeError as e:
+                sys.exit(f"{config_path} is not valid JSON ({e}). Fix it or move it away, then run again.")
+        backup = config_path.with_name(f"{config_path.name}.backup-{datetime.now():%Y%m%d-%H%M%S}")
+        shutil.copy2(config_path, backup)
+
+    servers = config.get("mcpServers") or {}
+    servers["creatorloop"] = entry
+    config["mcpServers"] = servers
+
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    # UTF-8 without BOM: Claude Desktop fails to parse a BOM-prefixed file
+    config_path.write_text(json.dumps(config, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    json.loads(config_path.read_text(encoding="utf-8"))  # validate
+    return backup
+
+
+def is_desktop_running(platform: str) -> bool:
+    if platform == "darwin":
+        cmd = ["pgrep", "-f", MAC_APP_BINARY]
+    elif platform == "win32":
+        cmd = ["tasklist", "/FI", "IMAGENAME eq Claude.exe", "/NH"]
+    else:
+        cmd = ["pgrep", "-x", "claude-desktop|Claude"]
+    try:
+        res = subprocess.run(cmd, capture_output=True, text=True, check=False)
+    except FileNotFoundError:
+        return False
+    if platform == "win32":
+        return "claude.exe" in res.stdout.lower()
+    return res.returncode == 0
+
+
+def quit_desktop(timeout: float = QUIT_TIMEOUT_S) -> bool:
+    """macOS only: the same graceful quit as Claude -> Quit; True once the process is gone."""
+    subprocess.run(["osascript", "-e", 'quit app "Claude"'], capture_output=True, check=False)
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if not is_desktop_running("darwin"):
+            return True
+        time.sleep(1)
+    return False
+
+
+def launch_desktop() -> None:
+    subprocess.run(["open", "-a", "Claude"], check=False)
+
+
+def close_desktop_if_running(platform: str, *, restart: bool) -> bool:
+    """Desktop rewrites the config from memory while running, so it must be closed first.
+
+    Returns True when we quit it and should start it again afterwards.
+    """
+    if not is_desktop_running(platform):
+        return False
+    if platform == "darwin" and restart:
+        print("Claude Desktop is running: quitting it so it does not overwrite the config...")
+        if not quit_desktop():
+            sys.exit(f"Claude Desktop did not quit within {QUIT_TIMEOUT_S} s; nothing was written. Quit it and run again.")
+        return True
+    hint = " (or run without --no-restart to let this command do it)" if platform == "darwin" else ""
+    sys.exit(
+        "Claude Desktop is running and would overwrite the config with its own copy. "
+        f"Quit it (tray / menu bar -> Quit), then run this command again{hint}."
+    )
+
+
+def main(argv: list[str] | None = None, platform: str = sys.platform) -> None:
+    ap = argparse.ArgumentParser(description=__doc__, epilog=DISCLAIMER, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--config", type=Path, help=f"path to {CONFIG_NAME} (default: auto-detect)")
+    ap.add_argument("--no-restart", action="store_true", help="macOS: do not quit and reopen a running Claude Desktop")
+    args = ap.parse_args(argv)
+
+    uv = find_uv()
+    if not uv:
+        sys.exit("uv not found. Install it first: https://docs.astral.sh/uv/getting-started/installation/")
+    targets = [args.config] if args.config else pick_targets(config_candidates(platform, home=Path.home(), env=os.environ))
+
+    source = paths.source_root()
+    entry = server_entry(uv=uv, source=source)
+
+    relaunch = close_desktop_if_running(platform, restart=not args.no_restart)
+    for path in targets:
+        backup = install(path, entry=entry)
+        if backup:
+            print(f"Backup: {backup}")
+        print(f"OK: 'creatorloop' server written to {path}")
+
+    home = paths.home_dir()
+    if env_file := paths.ensure_env_file(home):
+        print(f"Created {env_file}: fill in IG_ACCESS_TOKEN and IG_USER_ID (see README).")
+    print(f"\nrun:     {' '.join([entry['command'], *entry['args']])}\ndata:    {home}")
+    if relaunch:
+        launch_desktop()
+        print("Claude Desktop restarted: the 'creatorloop' tools appear in a new chat.")
+    else:
+        print("Start Claude Desktop: the 'creatorloop' tools appear in a new chat.")
+
+
+if __name__ == "__main__":
+    main()

creatorloop/storage.py

@@ -0,0 +1,464 @@
+"""SQLite storage: response cache, follower snapshots, hashtag quota tracking."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS cache (
+    key        TEXT PRIMARY KEY,
+    value      TEXT NOT NULL,
+    expires_at REAL NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS profile_snapshots (
+    username        TEXT NOT NULL,
+    captured_on     TEXT NOT NULL,          -- YYYY-MM-DD (UTC), one row per day
+    captured_at     TEXT NOT NULL,          -- ISO timestamp of the last update that day
+    followers_count INTEGER,
+    follows_count   INTEGER,
+    media_count     INTEGER,
+    PRIMARY KEY (username, captured_on)
+);
+
+-- v2: post metric history and competitor tracking (additive, no migration of old tables needed)
+CREATE TABLE IF NOT EXISTS media (
+    media_id     TEXT PRIMARY KEY,
+    owner        TEXT NOT NULL,             -- username, lower case
+    is_own       INTEGER NOT NULL DEFAULT 0,
+    published_at TEXT,                      -- Graph API timestamp
+    format       TEXT,
+    permalink    TEXT,
+    caption_head TEXT
+);
+
+CREATE TABLE IF NOT EXISTS media_snapshots (
+    media_id    TEXT NOT NULL,
+    captured_hr TEXT NOT NULL,              -- YYYY-MM-DDTHH (UTC), at most one row per hour
+    captured_at TEXT NOT NULL,
+    reach       INTEGER,
+    views       INTEGER,
+    likes       INTEGER,
+    comments    INTEGER,
+    saved       INTEGER,
+    shares      INTEGER,
+    follows     INTEGER,
+    PRIMARY KEY (media_id, captured_hr)
+);
+CREATE INDEX IF NOT EXISTS idx_media_owner ON media (owner);
+
+CREATE TABLE IF NOT EXISTS tracked_accounts (
+    username TEXT PRIMARY KEY,
+    added_at TEXT NOT NULL,
+    note     TEXT
+);
+
+CREATE TABLE IF NOT EXISTS publications (
+    creation_id  TEXT PRIMARY KEY,
+    folder       TEXT,
+    caption      TEXT,
+    items        INTEGER,
+    status       TEXT NOT NULL,            -- prepared | published | failed
+    media_id     TEXT,
+    permalink    TEXT,
+    error        TEXT,
+    prepared_at  TEXT NOT NULL,
+    published_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS post_reviews (
+    media_id    TEXT NOT NULL,
+    stage       TEXT NOT NULL,             -- 24h | 72h
+    reported_at TEXT NOT NULL,
+    metrics     TEXT,                      -- JSON snapshot at review time
+    PRIMARY KEY (media_id, stage)
+);
+
+CREATE TABLE IF NOT EXISTS post_queue (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    folder      TEXT NOT NULL,
+    publish_at  TEXT NOT NULL,             -- UTC ISO
+    fingerprint TEXT NOT NULL,             -- hash of caption + media approved by the user
+    media_type  TEXT,
+    caption_head TEXT,
+    status      TEXT NOT NULL,             -- queued | publishing | published | failed | missed | blocked | cancelled
+    creation_id TEXT,
+    permalink   TEXT,
+    error       TEXT,
+    approved_at TEXT NOT NULL,
+    updated_at  TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS comments_seen (
+    comment_id TEXT PRIMARY KEY,
+    media_id   TEXT,
+    seen_at    TEXT NOT NULL,
+    replied_at TEXT,
+    reply_id   TEXT
+);
+
+CREATE TABLE IF NOT EXISTS hashtag_queries (
+    hashtag         TEXT PRIMARY KEY,
+    hashtag_id      TEXT NOT NULL,
+    first_queried_at TEXT NOT NULL           -- start of the current 7-day window for this tag
+);
+"""
+
+# v3: additive column migrations (ignored when already applied)
+MIGRATIONS = ["ALTER TABLE publications ADD COLUMN media_type TEXT"]
+
+HASHTAG_LIMIT = 30
+HASHTAG_WINDOW = timedelta(days=7)
+
+
+class Storage:
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with self._conn() as conn:
+            conn.executescript(SCHEMA)
+            for ddl in MIGRATIONS:
+                try:
+                    conn.execute(ddl)
+                except sqlite3.OperationalError:  # column already exists
+                    pass
+
+    @contextmanager
+    def _conn(self) -> Iterator[sqlite3.Connection]:
+        conn = sqlite3.connect(self.path)
+        conn.row_factory = sqlite3.Row
+        try:
+            yield conn
+            conn.commit()
+        finally:
+            conn.close()
+
+    # ---- cache -------------------------------------------------------------
+
+    def cache_get(self, key: str) -> Any | None:
+        with self._conn() as conn:
+            row = conn.execute("SELECT value, expires_at FROM cache WHERE key = ?", (key,)).fetchone()
+        if row is None or row["expires_at"] < time.time():
+            return None
+        return json.loads(row["value"])
+
+    def cache_set(self, key: str, value: Any, ttl_s: int) -> None:
+        with self._conn() as conn:
+            conn.execute(
+                "INSERT OR REPLACE INTO cache (key, value, expires_at) VALUES (?, ?, ?)",
+                (key, json.dumps(value, ensure_ascii=False), time.time() + ttl_s),
+            )
+
+    def cache_clear(self, prefix: str | None = None) -> int:
+        with self._conn() as conn:
+            if prefix:
+                cur = conn.execute("DELETE FROM cache WHERE key LIKE ?", (f"{prefix}%",))
+            else:
+                cur = conn.execute("DELETE FROM cache")
+            return cur.rowcount
+
+    # ---- profile snapshots -------------------------------------------------
+
+    def save_snapshot(self, username: str, followers: int | None, follows: int | None, media: int | None) -> None:
+        now = datetime.now(UTC)
+        with self._conn() as conn:
+            conn.execute(
+                """
+                INSERT INTO profile_snapshots
+                    (username, captured_on, captured_at, followers_count, follows_count, media_count)
+                VALUES (?, ?, ?, ?, ?, ?)
+                ON CONFLICT (username, captured_on) DO UPDATE SET
+                    captured_at = excluded.captured_at,
+                    followers_count = excluded.followers_count,
+                    follows_count = excluded.follows_count,
+                    media_count = excluded.media_count
+                """,
+                (username.lower(), now.date().isoformat(), now.isoformat(timespec="seconds"), followers, follows, media),
+            )
+
+    def get_snapshots(self, username: str, days: int) -> list[dict[str, Any]]:
+        since = (datetime.now(UTC).date() - timedelta(days=days)).isoformat()
+        with self._conn() as conn:
+            rows = conn.execute(
+                """
+                SELECT captured_on, followers_count, follows_count, media_count
+                FROM profile_snapshots
+                WHERE username = ? AND captured_on >= ?
+                ORDER BY captured_on
+                """,
+                (username.lower(), since),
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    def tracked_usernames(self) -> list[str]:
+        with self._conn() as conn:
+            rows = conn.execute("SELECT DISTINCT username FROM profile_snapshots ORDER BY username").fetchall()
+        return [r["username"] for r in rows]
+
+    # ---- media history -----------------------------------------------------
+
+    def save_media_snapshots(self, owner: str, items: list[dict[str, Any]], *, is_own: bool) -> int:
+        """items: {id, timestamp, format, permalink, caption, metrics:{reach, views, likes, ...}}"""
+        now = datetime.now(UTC)
+        hour = now.strftime("%Y-%m-%dT%H")
+        stamp = now.isoformat(timespec="seconds")
+        cols = ("reach", "views", "likes", "comments", "saved", "shares", "follows")
+        with self._conn() as conn:
+            for it in items:
+                conn.execute(
+                    """
+                    INSERT INTO media (media_id, owner, is_own, published_at, format, permalink, caption_head)
+                    VALUES (?, ?, ?, ?, ?, ?, ?)
+                    ON CONFLICT (media_id) DO UPDATE SET
+                        is_own = MAX(media.is_own, excluded.is_own),
+                        format = excluded.format, permalink = excluded.permalink, caption_head = excluded.caption_head
+                    """,
+                    (
+                        it["id"],
+                        owner.lower(),
+                        int(is_own),
+                        it.get("timestamp"),
+                        it.get("format"),
+                        it.get("permalink"),
+                        (it.get("caption") or "").split("\n", 1)[0][:200],
+                    ),
+                )
+                m = it.get("metrics") or {}
+                conn.execute(
+                    f"""
+                    INSERT OR REPLACE INTO media_snapshots (media_id, captured_hr, captured_at, {", ".join(cols)})
+                    VALUES (?, ?, ?, {", ".join("?" for _ in cols)})
+                    """,
+                    (it["id"], hour, stamp, *(m.get(c) for c in cols)),
+                )
+        return len(items)
+
+    def media_history(self, media_id: str) -> dict[str, Any] | None:
+        with self._conn() as conn:
+            meta = conn.execute("SELECT * FROM media WHERE media_id = ?", (media_id,)).fetchone()
+            if meta is None:
+                return None
+            rows = conn.execute(
+                """
+                SELECT captured_at, reach, views, likes, comments, saved, shares, follows
+                FROM media_snapshots WHERE media_id = ? ORDER BY captured_at
+                """,
+                (media_id,),
+            ).fetchall()
+        return {"media": dict(meta), "snapshots": [dict(r) for r in rows]}
+
+    def owner_media_ids(self, owner: str) -> set[str]:
+        with self._conn() as conn:
+            rows = conn.execute("SELECT media_id FROM media WHERE owner = ?", (owner.lower(),)).fetchall()
+        return {r["media_id"] for r in rows}
+
+    # ---- tracked accounts --------------------------------------------------
+
+    def track(self, username: str, note: str | None = None) -> None:
+        with self._conn() as conn:
+            conn.execute(
+                """
+                INSERT INTO tracked_accounts (username, added_at, note) VALUES (?, ?, ?)
+                ON CONFLICT (username) DO UPDATE SET note = COALESCE(excluded.note, tracked_accounts.note)
+                """,
+                (username.lower(), datetime.now(UTC).isoformat(timespec="seconds"), note),
+            )
+
+    def untrack(self, username: str) -> bool:
+        with self._conn() as conn:
+            return conn.execute("DELETE FROM tracked_accounts WHERE username = ?", (username.lower(),)).rowcount > 0
+
+    def tracked(self) -> list[dict[str, Any]]:
+        with self._conn() as conn:
+            rows = conn.execute("SELECT username, added_at, note FROM tracked_accounts ORDER BY username").fetchall()
+        return [dict(r) for r in rows]
+
+    # ---- publications ------------------------------------------------------
+
+    def save_publication(
+        self, creation_id: str, folder: str, caption: str, items: int, media_type: str | None = None
+    ) -> None:
+        with self._conn() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO publications (creation_id, folder, caption, items, status, prepared_at, media_type)
+                VALUES (?, ?, ?, ?, 'prepared', ?, ?)
+                """,
+                (creation_id, folder, caption, items, datetime.now(UTC).isoformat(timespec="seconds"), media_type),
+            )
+
+    def update_publication(self, creation_id: str, **fields: Any) -> None:
+        if fields.get("status") == "published":
+            fields["published_at"] = datetime.now(UTC).isoformat(timespec="seconds")
+        cols = ", ".join(f"{k} = ?" for k in fields)
+        with self._conn() as conn:
+            conn.execute(f"UPDATE publications SET {cols} WHERE creation_id = ?", (*fields.values(), creation_id))
+
+    def get_publication(self, creation_id: str) -> dict[str, Any] | None:
+        with self._conn() as conn:
+            row = conn.execute("SELECT * FROM publications WHERE creation_id = ?", (creation_id,)).fetchone()
+        return dict(row) if row else None
+
+    def publications(self, limit: int = 20) -> list[dict[str, Any]]:
+        with self._conn() as conn:
+            rows = conn.execute(
+                "SELECT creation_id, folder, media_type, items, status, media_id, permalink, prepared_at, published_at, error "
+                "FROM publications ORDER BY prepared_at DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    # ---- publishing queue --------------------------------------------------
+
+    def queue_add(self, folder: str, publish_at: str, fingerprint: str, media_type: str, caption_head: str) -> int:
+        now = datetime.now(UTC).isoformat(timespec="seconds")
+        with self._conn() as conn:
+            cur = conn.execute(
+                "INSERT INTO post_queue (folder, publish_at, fingerprint, media_type, caption_head, status, approved_at,"
+                " updated_at) VALUES (?, ?, ?, ?, ?, 'queued', ?, ?)",
+                (folder, publish_at, fingerprint, media_type, caption_head, now, now),
+            )
+            return int(cur.lastrowid)
+
+    def queue_get(self, qid: int) -> dict[str, Any] | None:
+        with self._conn() as conn:
+            row = conn.execute("SELECT * FROM post_queue WHERE id = ?", (qid,)).fetchone()
+        return dict(row) if row else None
+
+    def queue_update(self, qid: int, **fields: Any) -> None:
+        fields["updated_at"] = datetime.now(UTC).isoformat(timespec="seconds")
+        cols = ", ".join(f"{k} = ?" for k in fields)
+        with self._conn() as conn:
+            conn.execute(f"UPDATE post_queue SET {cols} WHERE id = ?", (*fields.values(), qid))
+
+    def queue_due(self, now_iso: str) -> list[dict[str, Any]]:
+        with self._conn() as conn:
+            rows = conn.execute(
+                "SELECT * FROM post_queue WHERE status = 'queued' AND publish_at <= ? ORDER BY publish_at", (now_iso,)
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    def queue_list(self, include_done: bool = False, limit: int = 50) -> list[dict[str, Any]]:
+        where = "" if include_done else "WHERE status IN ('queued', 'publishing')"
+        with self._conn() as conn:
+            rows = conn.execute(
+                f"SELECT * FROM post_queue {where} ORDER BY publish_at DESC LIMIT ?", (limit,)
+            ).fetchall()
+        return [dict(r) for r in rows]
+
+    def queue_active_for(self, folder: str) -> dict[str, Any] | None:
+        with self._conn() as conn:
+            row = conn.execute(
+                "SELECT * FROM post_queue WHERE folder = ? AND status IN ('queued', 'publishing')", (folder,)
+            ).fetchone()
+        return dict(row) if row else None
+
+    # ---- comments ----------------------------------------------------------
+
+    def comment_seen(self, comment_id: str) -> dict[str, Any] | None:
+        with self._conn() as conn:
+            row = conn.execute("SELECT * FROM comments_seen WHERE comment_id = ?", (comment_id,)).fetchone()
+        return dict(row) if row else None
+
+    def comment_mark(self, comment_id: str, media_id: str | None, reply_id: str | None = None) -> None:
+        now = datetime.now(UTC).isoformat(timespec="seconds")
+        with self._conn() as conn:
+            conn.execute(
+                "INSERT INTO comments_seen (comment_id, media_id, seen_at) VALUES (?, ?, ?) "
+                "ON CONFLICT(comment_id) DO UPDATE SET media_id = COALESCE(excluded.media_id, media_id)",
+                (comment_id, media_id, now),
+            )
+            if reply_id:
+                conn.execute(
+                    "UPDATE comments_seen SET replied_at = ?, reply_id = ? WHERE comment_id = ?",
+                    (now, reply_id, comment_id),
+                )
+
+    # ---- post reviews ------------------------------------------------------
+
+    def review_get(self, media_id: str, stage: str) -> dict[str, Any] | None:
+        with self._conn() as conn:
+            row = conn.execute(
+                "SELECT * FROM post_reviews WHERE media_id = ? AND stage = ?", (media_id, stage)
+            ).fetchone()
+        return dict(row) if row else None
+
+    def review_save(self, media_id: str, stage: str, metrics: dict[str, Any]) -> None:
+        with self._conn() as conn:
+            conn.execute(
+                "INSERT OR REPLACE INTO post_reviews (media_id, stage, reported_at, metrics) VALUES (?, ?, ?, ?)",
+                (media_id, stage, datetime.now(UTC).isoformat(timespec="seconds"), json.dumps(metrics)),
+            )
+
+    # ---- hashtag quota -----------------------------------------------------
+
+    def _active_hashtags(self, conn: sqlite3.Connection) -> list[sqlite3.Row]:
+        cutoff = (datetime.now(UTC) - HASHTAG_WINDOW).isoformat(timespec="seconds")
+        return conn.execute(
+            "SELECT hashtag, hashtag_id, first_queried_at FROM hashtag_queries WHERE first_queried_at >= ?",
+            (cutoff,),
+        ).fetchall()
+
+    def hashtag_quota(self) -> dict[str, Any]:
+        with self._conn() as conn:
+            active = self._active_hashtags(conn)
+        used = sorted(active, key=lambda r: r["first_queried_at"])
+        return {
+            "limit": HASHTAG_LIMIT,
+            "used": len(used),
+            "remaining": max(HASHTAG_LIMIT - len(used), 0),
+            "hashtags": [
+                {
+                    "hashtag": r["hashtag"],
+                    "frees_up_at": (datetime.fromisoformat(r["first_queried_at"]) + HASHTAG_WINDOW).isoformat(
+                        timespec="minutes"
+                    ),
+                }
+                for r in used
+            ],
+            "note": "Local estimate: counts only queries made through this server.",
+        }
+
+    def plan_hashtags(self, hashtags: list[str]) -> dict[str, Any]:
+        """Dry run: which tags are free (already in their 7-day window) and which cost a new slot."""
+        quota = self.hashtag_quota()
+        active = {h["hashtag"] for h in quota["hashtags"]}
+        tags = list(dict.fromkeys(t.lstrip("#").strip().lower() for t in hashtags if t.strip("# ")))
+        free = [t for t in tags if t in active]
+        new = [t for t in tags if t not in active]
+        fits = len(new) <= quota["remaining"]
+        return {
+            "free_already_queried": [f"#{t}" for t in free],
+            "new_slots_needed": [f"#{t}" for t in new],
+            "remaining_before": quota["remaining"],
+            "remaining_after": max(quota["remaining"] - len(new), 0),
+            "fits_in_quota": fits,
+            "would_be_skipped": [f"#{t}" for t in new[quota["remaining"]:]] if not fits else [],
+            "next_slot_frees_up_at": quota["hashtags"][0]["frees_up_at"] if quota["hashtags"] else None,
+        }
+
+    def known_hashtag_id(self, hashtag: str) -> str | None:
+        """Hashtag ID if the tag is inside its current 7-day window (re-query costs no quota)."""
+        with self._conn() as conn:
+            for row in self._active_hashtags(conn):
+                if row["hashtag"] == hashtag:
+                    return row["hashtag_id"]
+        return None
+
+    def can_query_new_hashtag(self) -> bool:
+        with self._conn() as conn:
+            return len(self._active_hashtags(conn)) < HASHTAG_LIMIT
+
+    def register_hashtag(self, hashtag: str, hashtag_id: str) -> None:
+        with self._conn() as conn:
+            conn.execute(
+                "INSERT OR REPLACE INTO hashtag_queries (hashtag, hashtag_id, first_queried_at) VALUES (?, ?, ?)",
+                (hashtag, hashtag_id, datetime.now(UTC).isoformat(timespec="seconds")),
+            )