rankrush-cli 0.1.37__py3-none-any.whl

rankrush/commands/audit.py

@@ -0,0 +1,307 @@
+"""audit — website audit commands.
+
+All commands run on the v2 queue (audit-enqueue → process-audit-queue), the
+same backend the React app uses, so CLI-triggered audits write to ``audit_runs``
+/ ``node_progress`` and are immediately visible in app.rankrush.ai's history.
+
+  run      Enqueue a bulk audit, wait for it, and print a pass/fail summary.
+           (Convenience wrapper over ``start --wait`` + a node summary.)
+  start    Enqueue a bulk or single-node audit; optionally --wait for it.
+  status   Poll an in-flight audit by run id.
+  get      Read the full audit_runs row + aggregated node results.
+  delete   Remove an audit run (admin-only).
+
+The audited site + industry come from the profile's configuration, not from
+flags. ``run`` replaces the retired verify-nodes (audit v1) sync path.
+"""
+
+import time
+
+import click
+
+from rankrush import client, edge, output
+from rankrush.errors import CliError, MalformedResponseError, NotFoundError
+from rankrush.first_run import resolve_profile_id
+from rankrush.options import profile_option
+
+# Terminal audit_runs.status values — when reached, no further polling needed.
+# Source of truth: supabase/functions/process-audit-queue/index.ts writes
+# `'completed'` and `'failed'`; `'cancelled'` comes from the watchdog migration.
+_TERMINAL_STATUSES = {"completed", "failed", "cancelled"}
+
+
+@click.group("audit")
+def audit_group():
+    """Run and inspect website audits."""
+
+
+@audit_group.command("run")
+@profile_option
+@click.option(
+    "--poll-interval",
+    type=int,
+    default=10,
+    show_default=True,
+    help="Seconds between status polls while waiting.",
+)
+@click.option(
+    "--timeout",
+    type=int,
+    default=600,
+    show_default=True,
+    help="Hard ceiling on the wait, in seconds.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def run(profile_id: str | None, business: str | None, poll_interval: int, timeout: int, as_json: bool):
+    """Run a full bulk audit and wait for it to finish.
+
+    Convenience wrapper over the v2 queue: enqueues a bulk audit
+    (audit-enqueue), polls until it reaches a terminal status, then prints a
+    node pass/fail summary. Equivalent to `audit start --wait` plus the summary.
+
+    The audited site + industry come from the profile's configuration (set them
+    in the app), not from flags — this replaces the retired verify-nodes (v1)
+    path, which took an explicit --url. Takes 30–120 seconds.
+    """
+    profile_id = resolve_profile_id(profile_id, business)
+
+    if not as_json:
+        click.echo("Running bulk audit for this profile...")
+        click.echo("This may take 30-120 seconds.")
+
+    enqueued = client.invoke_function(
+        "audit-enqueue", {"profile_id": profile_id, "mode": "bulk"}, timeout=30
+    )
+    run_id = enqueued.get("auditRunId")
+    if not run_id:
+        raise MalformedResponseError(
+            f"audit-enqueue did not return an auditRunId — got {enqueued!r}"
+        )
+    if not as_json:
+        click.echo(f"Audit enqueued: {run_id}")
+
+    _poll_until_terminal(run_id, poll_interval, timeout, as_json)
+
+    # Pull the completed run + per-node summary for the pass/fail printout.
+    # audit_runs.audit_results is the v1-compatible check array ([{passed, ...}]),
+    # so the summary matches what the old verify-nodes path printed.
+    result = edge.audit_run_get(run_id, include_nodes=True)
+    run_row = result["run"]
+    nodes = result["nodes"]
+
+    if not as_json:
+        run_status = run_row.get("status") or "completed"
+        counts = _passed_counts(run_row)
+        if counts is not None:
+            passed, total = counts
+            click.echo(f"\nAudit {run_status}: {passed}/{total} nodes passed.")
+        else:
+            click.echo(f"\nAudit {run_status}. Nodes touched: {len(nodes)}")
+            for status_name, count in result["node_counts"].items():
+                click.echo(f"  {status_name}: {count}")
+        if run_row.get("error_message"):
+            click.echo(f"Error: {run_row['error_message']}")
+
+    output.emit(result, as_json)
+
+
+# ─── v2 path: audit-enqueue → process-audit-queue ─────────────────────────────
+
+
+def _poll_until_terminal(
+    run_id: str, poll_interval: int, timeout: int, as_json: bool
+) -> dict:
+    """Poll audit_runs by id until a terminal status; return the terminal row.
+
+    Shared by `audit run` and `audit start --wait`. Echoes each status
+    transition in human mode. Raises CliError if the deadline passes first.
+    """
+    deadline = time.monotonic() + timeout
+    last_status: str | None = None
+    while True:
+        row = edge.audit_run_get(run_id)["run"]
+        status = row.get("status") or "unknown"
+
+        if not as_json and status != last_status:
+            click.echo(f"  → status: {status}")
+            last_status = status
+
+        if status in _TERMINAL_STATUSES:
+            return row
+
+        if time.monotonic() >= deadline:
+            raise CliError(
+                f"Audit {run_id} did not reach a terminal status within {timeout}s "
+                f"(last seen: {status}). Use `rankrush audit status {run_id}` to keep checking."
+            )
+
+        time.sleep(poll_interval)
+
+
+@audit_group.command("start")
+@profile_option
+@click.option(
+    "--node-id",
+    "node_id",
+    default=None,
+    help="If set, runs a single-node audit (mode=single) instead of bulk.",
+)
+@click.option(
+    "--wait",
+    is_flag=True,
+    default=False,
+    help="Block until the audit reaches a terminal status. Otherwise return the run id immediately.",
+)
+@click.option(
+    "--poll-interval",
+    type=int,
+    default=10,
+    show_default=True,
+    help="Seconds between status polls when --wait is set.",
+)
+@click.option(
+    "--timeout",
+    type=int,
+    default=600,
+    show_default=True,
+    help="Hard ceiling on --wait, in seconds. Aborts polling at this duration.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def start(
+    profile_id: str | None,
+    business: str | None,
+    node_id: str | None,
+    wait: bool,
+    poll_interval: int,
+    timeout: int,
+    as_json: bool,
+):
+    """Enqueue a v2 audit. Returns the run id; optionally waits for completion.
+
+    Unlike `audit run` (legacy v1), this path writes to ``audit_runs`` and
+    ``node_progress`` — the same tables the React frontend reads from. The
+    run becomes visible in app.rankrush.ai/audit history immediately, and
+    per-node results land in the tech tree as the worker processes them.
+    """
+    profile_id = resolve_profile_id(profile_id, business)
+
+    body: dict = {"profile_id": profile_id, "mode": "single" if node_id else "bulk"}
+    if node_id:
+        body["node_filter"] = [node_id]
+
+    result = client.invoke_function("audit-enqueue", body, timeout=30)
+    run_id = result.get("auditRunId")
+    if not run_id:
+        raise MalformedResponseError(
+            f"audit-enqueue did not return an auditRunId — got {result!r}"
+        )
+
+    if not as_json:
+        click.echo(f"Audit enqueued: {run_id}")
+        click.echo(f"Mode: {result.get('mode')}  Enqueued at: {result.get('enqueuedAt')}")
+
+    if not wait:
+        output.emit(result, as_json)
+        return
+
+    row = _poll_until_terminal(run_id, poll_interval, timeout, as_json)
+    if not as_json:
+        click.echo(
+            f"\nAudit {row.get('status')}. "
+            f"Started {row.get('started_at')} · "
+            f"Completed {row.get('completed_at')}"
+        )
+        if row.get("status") == "failed" and row.get("error_message"):
+            click.echo(f"Error: {row['error_message']}")
+    output.emit(row, as_json)
+
+
+@audit_group.command("status")
+@click.argument("run_id")
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def status(run_id: str, as_json: bool):
+    """Show the current status of a v2 audit run by id."""
+    try:
+        run = edge.audit_run_get(run_id)["run"]
+    except NotFoundError:
+        raise CliError(f"No audit run found for id {run_id!r}.")
+    # `status` is a deliberately light view - project to the lifecycle fields
+    # (no audit_results / scores), matching the old direct-table select.
+    row = {
+        k: run.get(k)
+        for k in (
+            "id", "status", "mode", "enqueued_at", "started_at", "completed_at",
+            "error_message", "website_url", "industry",
+        )
+    }
+    if not as_json:
+        click.echo(f"Run:        {row['id']}")
+        click.echo(f"Status:     {row.get('status')}")
+        click.echo(f"Mode:       {row.get('mode')}")
+        click.echo(f"Website:    {row.get('website_url')}")
+        click.echo(f"Industry:   {row.get('industry')}")
+        click.echo(f"Enqueued:   {row.get('enqueued_at')}")
+        click.echo(f"Started:    {row.get('started_at') or '—'}")
+        click.echo(f"Completed:  {row.get('completed_at') or '—'}")
+        if row.get("error_message"):
+            click.echo(f"Error:      {row['error_message']}")
+    output.emit(row, as_json)
+
+
+@audit_group.command("get")
+@click.argument("run_id")
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def get(run_id: str, as_json: bool):
+    """Fetch the audit run including audit_results + a per-node summary."""
+    try:
+        summary = edge.audit_run_get(run_id, include_nodes=True)
+    except NotFoundError:
+        raise CliError(f"No audit run found for id {run_id!r}.")
+    run = summary["run"]
+    nodes = summary["nodes"]
+
+    if not as_json:
+        click.echo(f"Run {run['id']}  status={run.get('status')}")
+        click.echo(f"Mode={run.get('mode')}  Industry={run.get('industry')}")
+        click.echo(f"Nodes touched: {len(nodes)}")
+        for status_name, count in summary["node_counts"].items():
+            click.echo(f"  {status_name}: {count}")
+        if run.get("error_message"):
+            click.echo(f"Error: {run['error_message']}")
+
+    output.emit(summary, as_json)
+
+
+@audit_group.command("delete")
+@click.argument("run_id")
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def delete(run_id: str, as_json: bool):
+    """Permanently delete an audit run and its node rows. ADMIN-ONLY.
+
+    Used to clean up one-off prospect audits so they don't pollute the
+    account's audit history. The backend enforces the `admin` app_role; a
+    non-admin key gets a 403.
+    """
+    result = client.invoke_function("delete-audit-run", {"runId": run_id}, timeout=30)
+    if not as_json:
+        deleted = result.get("deleted", {})
+        click.echo(f"Deleted audit run {deleted.get('audit_run', run_id)}")
+        if deleted.get("website_url"):
+            click.echo(f"Website:    {deleted['website_url']}")
+        click.echo(f"Node rows:  {deleted.get('node_rows', 0)}")
+    output.emit(result, as_json)
+
+
+def _passed_counts(run_row: dict) -> tuple[int, int] | None:
+    """Return (passed, total) from audit_runs.audit_results, or None if absent.
+
+    ``audit_results`` is the v1-compatible check array (``[{passed, ...}]``);
+    tolerate a ``{"results": [...]}`` wrapper too. Returns None when the column
+    is empty/missing so callers can fall back to the node_progress breakdown.
+    """
+    ar = run_row.get("audit_results")
+    checks = ar if isinstance(ar, list) else (ar.get("results") if isinstance(ar, dict) else None)
+    if not checks:
+        return None
+    passed = sum(1 for c in checks if isinstance(c, dict) and c.get("passed"))
+    return passed, len(checks)

rankrush/commands/blog.py

@@ -0,0 +1,175 @@
+"""blog — generate blog topics, draft posts, and content strategy.
+
+Commands:
+  topics generate   Generate blog topics for a profile (LLM-backed).
+  topics list       Show currently tracked blog topics for a profile.
+  post generate     Draft a full blog post from a topic (requires a CMS
+                    connection; subject to a tier daily cap).
+  strategy          Generate an overall content strategy for a profile.
+
+Each subcommand wraps a single backend surface and supports ``--json``.
+The backend authenticates ``rr_live_*`` keys via ``resolveApiKeyUserId``.
+"""
+
+import click
+
+from rankrush import client, edge, output
+from rankrush.errors import MalformedResponseError
+from rankrush.first_run import resolve_profile_id
+from rankrush.options import profile_option
+
+# Topic generation window. Backend defaults to 30 days; clamp client-side too
+# so an out-of-range value never reaches the edge function.
+_DEFAULT_DAYS = 30
+_MAX_DAYS = 180
+
+
+@click.group("blog")
+def blog_group():
+    """Generate blog topics, draft posts, and content strategy."""
+
+
+# ─── blog topics ────────────────────────────────────────────────────────────
+
+
+@blog_group.group("topics")
+def topics_group():
+    """Generate and list blog topics for a profile."""
+
+
+@topics_group.command("generate")
+@profile_option
+@click.option(
+    "--days",
+    type=int,
+    default=_DEFAULT_DAYS,
+    show_default=True,
+    help=f"Planning window in days (1-{_MAX_DAYS}). Clamped to this range.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def topics_generate(profile_id: str | None, business: str | None, days: int, as_json: bool):
+    """Generate blog topics for a profile over the next N days."""
+    profile_id = resolve_profile_id(profile_id, business)
+    days = max(1, min(days, _MAX_DAYS))
+
+    if not as_json:
+        click.echo(f"Generating blog topics ({days}-day window)...")
+
+    # invoke_function raises on any 4xx/5xx (incl. the backend's {error: ...}
+    # bodies), so a returned dict is always the 200 success payload. The
+    # success body is {generated, gapCount, calendarStart, calendarEnd,
+    # pillars, breakdown, layers, warning?} — there is no `success`/`topics` key.
+    data = client.invoke_function(
+        "generate-blog-topics",
+        {"profileId": profile_id, "days": days},
+        timeout=120,
+    )
+    if not isinstance(data, dict):
+        raise MalformedResponseError(
+            "generate-blog-topics returned an unexpected (non-object) response."
+        )
+
+    if not as_json:
+        click.echo(f"Generated {data.get('generated', 0)} topic(s).")
+        for p in data.get("pillars", []) or []:
+            name = p.get("name") if isinstance(p, dict) else p
+            click.echo(f"  · {name}")
+        if data.get("warning"):
+            click.echo(data["warning"])
+
+    output.emit(data, as_json)
+
+
+@topics_group.command("list")
+@profile_option
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def topics_list(profile_id: str | None, business: str | None, as_json: bool):
+    """List currently tracked blog topics for a profile."""
+    profile_id = resolve_profile_id(profile_id, business)
+    result = edge.blog_topics_list(profile_id)
+    rows = result["topics"]
+
+    if not as_json:
+        if not rows:
+            click.echo(
+                "No blog topics for this profile. "
+                "Run `rankrush blog topics generate` first."
+            )
+        else:
+            for r in rows:
+                stage = r.get("generation_stage") or "—"
+                when = r.get("scheduled_date") or "—"
+                click.echo(f"  · {r.get('title')}  [{stage}]  scheduled: {when}")
+
+    output.emit(result, as_json)
+
+
+# ─── blog post ──────────────────────────────────────────────────────────────
+
+
+@blog_group.group("post")
+def post_group():
+    """Draft blog posts from topics."""
+
+
+@post_group.command("generate")
+@profile_option
+@click.option("--topic-id", required=True, help="Blog topic UUID to draft a post for.")
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def post_generate(profile_id: str | None, business: str | None, topic_id: str, as_json: bool):
+    """Draft a full blog post from a topic.
+
+    Requires an existing CMS connection on the profile and is subject to a
+    per-tier daily cap. When either gate fails the backend returns an error
+    message which is surfaced cleanly via the CLI error boundary.
+    """
+    profile_id = resolve_profile_id(profile_id, business)
+
+    if not as_json:
+        click.echo(f"Drafting blog post for topic {topic_id}...")
+
+    # Business failures (connection_missing, daily_cap_reached, tier_too_low,
+    # topic_wrong_status, …) come back as HTTP 200 with {ok:false, code,
+    # message} — they do NOT trip invoke_function's status check, so gate on
+    # `ok` here and surface the backend's human message.
+    data = client.invoke_function(
+        "generate-blog-post",
+        {"profileId": profile_id, "topicId": topic_id},
+        timeout=120,
+    )
+    if not isinstance(data, dict) or not data.get("ok"):
+        msg = (
+            data.get("message") or data.get("error") or data.get("code") or "unknown"
+            if isinstance(data, dict)
+            else "unknown"
+        )
+        raise MalformedResponseError(f"generate-blog-post error: {msg}")
+
+    output.emit(data, as_json)
+
+
+# ─── blog strategy ──────────────────────────────────────────────────────────
+
+
+@blog_group.command("strategy")
+@profile_option
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def strategy(profile_id: str | None, business: str | None, as_json: bool):
+    """Generate an overall content strategy for a profile."""
+    profile_id = resolve_profile_id(profile_id, business)
+
+    if not as_json:
+        click.echo("Generating content strategy for this profile...")
+
+    # Success body is {ok:true, strategy}; non-200 errors already raise in
+    # invoke_function. Gate on `ok` defensively and surface any error message.
+    data = client.invoke_function(
+        "generate-content-strategy",
+        {"profileId": profile_id},
+        timeout=120,
+    )
+    if not isinstance(data, dict) or not data.get("ok"):
+        err = data.get("error", "unknown") if isinstance(data, dict) else "unknown"
+        raise MalformedResponseError(f"generate-content-strategy error: {err}")
+
+    output.emit(data, as_json)

rankrush/commands/buzz/drafts.py

@@ -0,0 +1,84 @@
+"""buzz drafts — list and manage draft posts.
+
+Commands:
+  list     List posts filtered by status
+  approve  Approve a draft for scheduling
+"""
+
+import click
+
+from rankrush import edge, output
+from rankrush.first_run import resolve_profile_id
+from rankrush.options import profile_option
+
+VALID_STATUSES = ("draft", "approved", "scheduled", "posted", "failed")
+
+# The exact columns the old direct-table read emitted, so `--json` is unchanged.
+_DRAFT_FIELDS = (
+    "id", "profile_id", "status", "post_type", "subreddit",
+    "draft_content", "scheduled_at", "retry_count", "created_at",
+)
+
+
+@click.group("drafts")
+def drafts_group():
+    """Manage Buzz draft posts."""
+
+
+@drafts_group.command("list")
+@profile_option
+@click.option(
+    "--status",
+    default="draft",
+    show_default=True,
+    type=click.Choice(VALID_STATUSES),
+    help="Filter by post status.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def list_drafts(profile_id: str | None, business: str | None, status: str, as_json: bool):
+    """List Buzz posts filtered by status (default: draft)."""
+    profile_id = resolve_profile_id(profile_id, business) if (profile_id or business) else None
+    engagements = edge.buzz_engagements_list(profile_id=profile_id, status=status)["engagements"]
+    rows = [{k: r.get(k) for k in _DRAFT_FIELDS} for r in engagements]
+
+    if not as_json:
+        if not rows:
+            if status == "draft":
+                click.echo(
+                    "No draft posts yet.\n"
+                    'Generate some with `rankrush buzz strategy suggest --business "<name>"`.'
+                )
+            else:
+                click.echo(
+                    f"No {status} posts yet.\n"
+                    f"List drafts instead: `rankrush buzz drafts list --status draft`."
+                )
+        else:
+            click.echo(f"Found {len(rows)} {status} post(s):")
+
+    output.emit(rows, as_json)
+
+
+@drafts_group.command("approve")
+@click.option("--id", "draft_id", required=True, help="Draft post UUID to approve.")
+@click.option(
+    "--schedule-at",
+    default=None,
+    help='ISO 8601 datetime to schedule posting (e.g. "2026-04-10T09:00:00Z"). '
+    "If omitted, the post is approved but not yet scheduled.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def approve(draft_id: str, schedule_at: str | None, as_json: bool):
+    """Approve a draft post, optionally scheduling it for a specific time.
+
+    Updates buzz_engagements.status from 'draft' → 'approved' (or 'scheduled' if
+    --schedule-at is provided). The pg_cron scheduler will pick up 'scheduled'
+    posts and publish them via the Reddit API.
+    """
+    updated = edge.buzz_draft_approve(draft_id, schedule_at=schedule_at)
+
+    if not as_json:
+        ts = f" — scheduled for {schedule_at}" if schedule_at else ""
+        click.echo(f"Draft {draft_id} approved{ts}.")
+
+    output.emit(updated, as_json)

rankrush/commands/buzz/posts.py

@@ -0,0 +1,97 @@
+"""buzz posts — inspect published posts and their performance."""
+
+import click
+from datetime import datetime, timedelta, timezone
+
+from rankrush import edge, output
+from rankrush.errors import CliError
+from rankrush.first_run import resolve_profile_id
+from rankrush.options import profile_option
+
+# The exact columns the old direct-table read emitted, so `--json` is unchanged.
+_POST_FIELDS = (
+    "id", "profile_id", "status", "post_type",
+    "subreddit", "posted_at", "retry_count", "created_at",
+)
+
+
+@click.group("posts")
+def posts_group():
+    """Inspect published Buzz posts."""
+
+
+@posts_group.command("performance")
+@profile_option
+@click.option(
+    "--since",
+    default="7d",
+    show_default=True,
+    help="Lookback window: Nd (days) or YYYY-MM-DD date.",
+)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def performance(profile_id: str | None, business: str | None, since: str, as_json: bool):
+    """Show published posts within a time window.
+
+    Queries buzz_engagements for posts with status='posted' within the lookback
+    window. Returns post metadata and basic status breakdown.
+
+    --since accepts either:
+      Nd       — last N days (e.g. 7d, 30d)
+      ISO date - from this date forward (e.g. 2026-04-01)
+    """
+    profile_id = resolve_profile_id(profile_id, business) if (profile_id or business) else None
+
+    # Parse --since
+    since_dt: datetime
+    if since.endswith("d") and since[:-1].isdigit():
+        since_dt = datetime.now(timezone.utc) - timedelta(days=int(since[:-1]))
+    else:
+        try:
+            since_dt = datetime.fromisoformat(since).replace(tzinfo=timezone.utc)
+        except ValueError as exc:
+            raise CliError(
+                f"Invalid --since value {since!r}. Use Nd (e.g. 7d) or YYYY-MM-DD."
+            ) from exc
+
+    since_iso = since_dt.isoformat()
+
+    # Read all posted engagements via the edge function; window on posted_at
+    # client-side (as before - the server-side `since` filter is created_at-based
+    # and this view is posted_at-based). Project to the old column set so the
+    # `posts` payload is byte-for-byte identical to the pre-migration output.
+    engagements = edge.buzz_engagements_list(
+        profile_id=profile_id, status="posted", limit=200
+    )["engagements"]
+
+    in_window = [
+        {k: r.get(k) for k in _POST_FIELDS}
+        for r in engagements
+        if r.get("posted_at") and r["posted_at"] >= since_iso
+    ]
+
+    # Basic aggregation
+    by_subreddit: dict[str, int] = {}
+    for r in in_window:
+        sub = r.get("subreddit") or "unknown"
+        by_subreddit[sub] = by_subreddit.get(sub, 0) + 1
+
+    result = {
+        "window": since,
+        "total_posted": len(in_window),
+        "by_subreddit": dict(sorted(by_subreddit.items(), key=lambda x: -x[1])),
+        "posts": in_window,
+    }
+
+    if not as_json:
+        if not in_window:
+            click.echo(
+                f"No posts published in the last {since}.\n"
+                "Approve a draft to schedule one: "
+                "`rankrush buzz drafts approve --id <draft-id> --schedule-at <iso-time>`."
+            )
+        else:
+            click.echo(f"Posts published in the last {since}: {len(in_window)}")
+            for sub, count in list(result["by_subreddit"].items())[:5]:
+                click.echo(f"  r/{sub}: {count}")
+
+    output.emit(result, as_json)