[feat]. Add @codex -h help summary command

src/gitea_codex_bot/workers/dispatcher.py

@@ -4,12 +4,12 @@ import asyncio
 import logging
 from typing import Any
 
-from sqlalchemy import select
+from sqlalchemy import func, select
 from sqlalchemy.orm import Session
 
 from gitea_codex_bot.config import Settings
 from gitea_codex_bot.db import get_session_factory
-from gitea_codex_bot.models import ReviewJob
+from gitea_codex_bot.models import JobStatus, ReviewJob
 from gitea_codex_bot.services.comments import upsert_persistent_review_comment_id
 from gitea_codex_bot.services.gitea import GiteaClient
 from gitea_codex_bot.services.jobs import claim_next_job, finish_job
@@ -34,6 +34,13 @@ def _handle_non_review_command(
     job: ReviewJob,
     command: ParsedCommand,
 ) -> tuple[bool, bool, dict[str, Any] | None, str | None]:
+    if command.name == "help":
+        try:
+            message = _build_help_comment(settings, session, gitea, job)
+            gitea.post_issue_comment(job.repo, job.pr_number, message)
+            return True, True, {"summary": "Help/status summary posted."}, None
+        except Exception as exc:
+            return True, False, None, f"Failed to post help summary: {exc}"
     if command.name == "ignore":
         return True, True, {"summary": "Ignore command acknowledged. No review run executed."}, None
     if command.name == "explain":
@@ -74,6 +81,91 @@ def _handle_non_review_command(
     return False, False, None, None
 
 
+def _build_help_comment(settings: Settings, session: Session, gitea: GiteaClient, job: ReviewJob) -> str:
+    comments = gitea.list_issue_comments(job.repo, job.pr_number)
+    comment_summaries = _summarize_comments(comments, settings.gitea_bot_username)
+    latest_review = session.execute(
+        select(ReviewJob)
+        .where(
+            ReviewJob.repo == job.repo,
+            ReviewJob.pr_number == job.pr_number,
+            ReviewJob.command.in_(["review", "rerun"]),
+        )
+        .order_by(ReviewJob.id.desc())
+        .limit(1)
+    ).scalar_one_or_none()
+    pending_count = session.execute(
+        select(func.count(ReviewJob.id)).where(
+            ReviewJob.repo == job.repo,
+            ReviewJob.pr_number == job.pr_number,
+            ReviewJob.status.in_([JobStatus.queued, JobStatus.running]),
+        )
+    ).scalar_one()
+    latest_status_line = "No previous review run."
+    if latest_review is not None:
+        latest_status = latest_review.status.value if hasattr(latest_review.status, "value") else str(latest_review.status)
+        latest_summary = ""
+        if isinstance(latest_review.result_json, dict):
+            summary_raw = latest_review.result_json.get("summary")
+            if isinstance(summary_raw, str):
+                latest_summary = " ".join(summary_raw.split())
+        latest_status_line = f"Latest review command: `{latest_review.command}` status `{latest_status}`."
+        if latest_summary:
+            latest_status_line = f"{latest_status_line} Summary: {latest_summary[:180]}"
+
+    lines = [
+        "## Codex Help",
+        "",
+        "Supported commands:",
+        "- `@codex review [security|performance|tests] [--full]`",
+        "- `@codex rerun`",
+        "- `@codex explain`",
+        "- `@codex fix [--branch ...]`",
+        "- `@codex ignore`",
+        "- `@codex -h` / `@codex --help` / `@codex help`",
+        "",
+        "Status note:",
+        f"- Pending jobs on this PR: `{pending_count}`",
+        f"- Fix command enabled: `{str(settings.enable_fix_commands).lower()}`",
+        f"- {latest_status_line}",
+        "",
+        f"Discussion summary ({comment_summaries['total']} comments, human `{comment_summaries['human']}`, bot `{comment_summaries['bot']}`):",
+    ]
+    if comment_summaries["items"]:
+        lines.extend(comment_summaries["items"])
+    else:
+        lines.append("- No comments available to summarize.")
+    return "\n".join(lines).strip()
+
+
+def _summarize_comments(comments: list[dict[str, Any]], bot_username: str) -> dict[str, Any]:
+    normalized_bot = (bot_username or "").strip().lower()
+    bot_count = 0
+    summarized: list[str] = []
+    recent = comments[-8:] if comments else []
+    for row in comments:
+        user = row.get("user")
+        username = ""
+        if isinstance(user, dict):
+            username = str(user.get("username") or user.get("login") or "").strip().lower()
+        if username and username == normalized_bot:
+            bot_count += 1
+    for row in recent:
+        body_raw = str(row.get("body") or "").strip()
+        if not body_raw:
+            continue
+        one_line = " ".join(body_raw.split())
+        preview = one_line if len(one_line) <= 180 else f"{one_line[:180]}..."
+        user = row.get("user")
+        username = "unknown"
+        if isinstance(user, dict):
+            username = str(user.get("username") or user.get("login") or "unknown").strip() or "unknown"
+        summarized.append(f"- @{username}: {preview}")
+    total = len(comments)
+    human_count = max(total - bot_count, 0)
+    return {"total": total, "human": human_count, "bot": bot_count, "items": summarized}
+
+
 def _post_review_failure_comment(gitea: GiteaClient, job: ReviewJob, error_message: str) -> None:
     message = (
         "⚠️ Codex review run failed after queueing.\n\n"