fix: add backlog triage tool for managing open issues (#1459)

Closes #1459. Addresses the timmy-home backlog of 220 open issues
by providing an automated triage tool.

bin/backlog_triage.py:
- Fetches all open issues with pagination
- Categorizes: idle (60d+), stale (30d+), zombie (90d+ no comments),
  closeable (duplicate/wontfix), unassigned, urgent, backlog, bug, feature
- Generates triage report with recommendations
- Optional auto-close for clearly stale issues (90d+ idle, 0 comments)
- Dry-run mode for safety

14 tests pass.

bin/backlog_triage.py

@@ -0,0 +1,277 @@
+#!/usr/bin/env python3
+"""
+backlog_triage.py — Triage open issues in a Gitea repository.
+
+Scans open issues, categorizes by age/activity, identifies stale issues,
+and generates a triage report. Optionally auto-closes stale issues.
+
+Usage:
+    python3 bin/backlog_triage.py --repo Timmy_Foundation/the-nexus
+    python3 bin/backlog_triage.py --repo Timmy_Foundation/the-nexus --stale-days 60 --report out.json
+    python3 bin/backlog_triage.py --repo Timmy_Foundation/the-nexus --auto-close-stale --dry-run
+"""
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Optional
+
+import urllib.request
+import urllib.error
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+GITEA_URL = os.environ.get("GITEA_URL", "https://forge.alexanderwhitestone.com")
+DEFAULT_STALE_DAYS = 30
+DEFAULT_IDLE_DAYS = 60
+BATCH_SIZE = 50  # Gitea API page size
+
+
+# ---------------------------------------------------------------------------
+# API helpers
+# ---------------------------------------------------------------------------
+
+def _api(token: str, method: str, path: str, data: dict = None) -> dict:
+    """Make a Gitea API call."""
+    url = f"{GITEA_URL}/api/v1{path}"
+    headers = {"Authorization": f"token {token}", "Content-Type": "application/json"}
+    body = json.dumps(data).encode() if data else None
+    req = urllib.request.Request(url, data=body, headers=headers, method=method)
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        return json.loads(resp.read()) if resp.status != 204 else {}
+
+
+def _read_token(token: str = None) -> str:
+    """Read Gitea token from argument, env, or file."""
+    if token:
+        return token
+    token = os.environ.get("GITEA_TOKEN", "")
+    if token:
+        return token
+    token_path = Path.home() / ".config" / "gitea" / "token"
+    if token_path.exists():
+        return token_path.read_text().strip()
+    raise ValueError("No Gitea token found. Pass --token, set GITEA_TOKEN, or create ~/.config/gitea/token")
+
+
+# ---------------------------------------------------------------------------
+# Issue data model
+# ---------------------------------------------------------------------------
+
+def fetch_all_issues(token: str, repo: str, state: str = "open") -> list[dict]:
+    """Fetch all open issues with pagination."""
+    issues = []
+    page = 1
+    while True:
+        data = _api(token, "GET", f"/repos/{repo}/issues?state={state}&limit={BATCH_SIZE}&page={page}")
+        if not data:
+            break
+        issues.extend(data)
+        if len(data) < BATCH_SIZE:
+            break
+        page += 1
+    return issues
+
+
+def categorize_issue(issue: dict, now: datetime, stale_days: int, idle_days: int) -> dict:
+    """Categorize an issue by age, activity, and content."""
+    created = datetime.fromisoformat(issue["created_at"].replace("Z", "+00:00"))
+    updated = datetime.fromisoformat(issue["updated_at"].replace("Z", "+00:00"))
+    age_days = (now - created).days
+    idle_days_actual = (now - updated).days
+
+    labels = [l["name"] for l in issue.get("labels", [])]
+    assignees = [a["login"] for a in issue.get("assignees", [])]
+    comments = issue.get("comments", 0)
+
+    # Determine category
+    if idle_days_actual >= idle_days:
+        category = "idle"  # No activity for 60+ days
+    elif idle_days_actual >= stale_days:
+        category = "stale"  # No activity for 30+ days
+    elif age_days >= 90 and comments == 0:
+        category = "zombie"  # Old, never discussed
+    elif any(l in labels for l in ["duplicate", "wontfix", "invalid"]):
+        category = "closeable"
+    elif not assignees:
+        category = "unassigned"
+    elif any(l in labels for l in ["p0-critical", "p1-important"]):
+        category = "urgent"
+    elif any(l in labels for l in ["p2-backlog", "p3-low"]):
+        category = "backlog"
+    elif any(l in labels for l in ["bug"]):
+        category = "bug"
+    elif any(l in labels for l in ["enhancement", "feature"]):
+        category = "feature"
+    else:
+        category = "triage-needed"
+
+    return {
+        "number": issue["number"],
+        "title": issue["title"],
+        "category": category,
+        "age_days": age_days,
+        "idle_days": idle_days_actual,
+        "labels": labels,
+        "assignees": assignees,
+        "comments": comments,
+        "created_at": issue["created_at"],
+        "updated_at": issue["updated_at"],
+        "html_url": issue.get("html_url", ""),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Triage report
+# ---------------------------------------------------------------------------
+
+def generate_report(categorized: list[dict]) -> dict:
+    """Generate a triage summary report."""
+    by_category = {}
+    for issue in categorized:
+        cat = issue["category"]
+        by_category.setdefault(cat, []).append(issue)
+
+    # Sort each category by idle days (most idle first)
+    for cat in by_category:
+        by_category[cat].sort(key=lambda x: x["idle_days"], reverse=True)
+
+    summary = {
+        "total": len(categorized),
+        "by_category": {cat: len(issues) for cat, issues in by_category.items()},
+        "closeable_candidates": [
+            {"number": i["number"], "title": i["title"], "reason": f"idle {i['idle_days']}d, labels: {i['labels']}"}
+            for i in categorized
+            if i["category"] in ("idle", "zombie", "closeable")
+        ],
+        "stale_needing_attention": [
+            {"number": i["number"], "title": i["title"], "idle_days": i["idle_days"]}
+            for i in categorized
+            if i["category"] == "stale"
+        ],
+        "unassigned": [
+            {"number": i["number"], "title": i["title"]}
+            for i in categorized
+            if i["category"] == "unassigned"
+        ],
+        "recommendations": [],
+    }
+
+    # Generate recommendations
+    closeable = len(summary["closeable_candidates"])
+    stale = len(summary["stale_needing_attention"])
+    unassigned = len(summary["unassigned"])
+
+    if closeable > 0:
+        summary["recommendations"].append(
+            f"Close {closeable} idle/zombie/closeable issues (no activity 60+ days or labeled wontfix/duplicate)"
+        )
+    if stale > 0:
+        summary["recommendations"].append(
+            f"Review {stale} stale issues (no activity 30+ days)"
+        )
+    if unassigned > 0:
+        summary["recommendations"].append(
+            f"Assign owners to {unassigned} unassigned issues or close if no longer relevant"
+        )
+
+    summary["issues"] = categorized
+    return summary
+
+
+# ---------------------------------------------------------------------------
+# Auto-close (optional)
+# ---------------------------------------------------------------------------
+
+def auto_close_stale(token: str, repo: str, issues: list[dict], dry_run: bool = True) -> list[int]:
+    """Close idle/zombie issues that are clearly stale."""
+    closed = []
+    for issue in issues:
+        if issue["category"] not in ("idle", "zombie"):
+            continue
+        # Safety: only close if idle 90+ days AND 0 comments
+        if issue["idle_days"] < 90 or issue["comments"] > 0:
+            continue
+
+        comment = f"Auto-closed by backlog triage: no activity for {issue['idle_days']} days, 0 comments. Reopen if still relevant."
+        if not dry_run:
+            # Comment first
+            _api(token, "POST", f"/repos/{repo}/issues/{issue['number']}/comments", {"body": comment})
+            # Close
+            _api(token, "PATCH", f"/repos/{repo}/issues/{issue['number']}", {"state": "closed"})
+            print(f"  Closed #{issue['number']}: {issue['title']}")
+        else:
+            print(f"  DRY-RUN: Would close #{issue['number']}: {issue['title']} (idle {issue['idle_days']}d)")
+        closed.append(issue["number"])
+
+    return closed
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main():
+    parser = argparse.ArgumentParser(description="Backlog triage tool for Gitea repositories")
+    parser.add_argument("--repo", required=True, help="Repository (e.g. Timmy_Foundation/the-nexus)")
+    parser.add_argument("--token", default=None, help="Gitea API token")
+    parser.add_argument("--stale-days", type=int, default=DEFAULT_STALE_DAYS, help="Days without activity to be stale")
+    parser.add_argument("--idle-days", type=int, default=DEFAULT_IDLE_DAYS, help="Days without activity to be idle")
+    parser.add_argument("--report", default=None, help="Output report JSON path")
+    parser.add_argument("--auto-close-stale", action="store_true", help="Auto-close idle/zombie issues")
+    parser.add_argument("--dry-run", action="store_true", help="Don't actually close issues")
+    parser.add_argument("--summary-only", action="store_true", help="Print summary only, no issue list")
+
+    args = parser.parse_args()
+    token = _read_token(args.token)
+
+    print(f"Fetching issues from {args.repo}...")
+    issues = fetch_all_issues(token, args.repo)
+    print(f"Found {len(issues)} open issues")
+
+    now = datetime.now(timezone.utc)
+    categorized = [categorize_issue(i, now, args.stale_days, args.idle_days) for i in issues]
+
+    report = generate_report(categorized)
+
+    # Print summary
+    print(f"\n=== Triage Summary ===")
+    print(f"Total: {report['total']}")
+    for cat, count in sorted(report["by_category"].items()):
+        print(f"  {cat}: {count}")
+
+    print(f"\n=== Recommendations ===")
+    for rec in report["recommendations"]:
+        print(f"  - {rec}")
+
+    if not args.summary_only:
+        print(f"\n=== Closeable Candidates ({len(report['closeable_candidates'])}) ===")
+        for c in report["closeable_candidates"][:20]:
+            print(f"  #{c['number']}: {c['title'][:60]} [{c['reason']}]")
+
+        print(f"\n=== Stale ({len(report['stale_needing_attention'])}) ===")
+        for s in report["stale_needing_attention"][:20]:
+            print(f"  #{s['number']}: {s['title'][:60]} (idle {s['idle_days']}d)")
+
+    # Auto-close if requested
+    if args.auto_close_stale:
+        print(f"\n=== Auto-close {'(DRY RUN)' if args.dry_run else '(LIVE)'} ===")
+        closed = auto_close_stale(token, args.repo, categorized, dry_run=args.dry_run)
+        print(f"{'Would close' if args.dry_run else 'Closed'} {len(closed)} issues")
+
+    # Write report
+    if args.report:
+        with open(args.report, "w") as f:
+            json.dump(report, f, indent=2)
+        print(f"\nReport written to {args.report}")
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

tests/test_backlog_triage.py

@@ -0,0 +1,115 @@
+"""Tests for backlog_triage — issue categorization and report generation."""
+import json
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+import pytest
+import sys
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from bin.backlog_triage import categorize_issue, generate_report
+
+
+def _make_issue(number=1, title="Test", labels=None, assignees=None, comments=0,
+                days_old=10, days_idle=5):
+    now = datetime.now(timezone.utc)
+    created = now - timedelta(days=days_old)
+    updated = now - timedelta(days=days_idle)
+    return {
+        "number": number,
+        "title": title,
+        "created_at": created.isoformat().replace("+00:00", "Z"),
+        "updated_at": updated.isoformat().replace("+00:00", "Z"),
+        "labels": [{"name": l} for l in (labels or [])],
+        "assignees": [{"login": a} for a in (assignees or [])],
+        "comments": comments,
+        "html_url": f"https://example.com/{number}",
+    }
+
+
+class TestCategorizeIssue:
+    def test_idle_issue(self):
+        issue = _make_issue(days_idle=70)
+        result = categorize_issue(issue, datetime.now(timezone.utc), 30, 60)
+        assert result["category"] == "idle"
+
+    def test_stale_issue(self):
+        issue = _make_issue(days_idle=45)
+        result = categorize_issue(issue, datetime.now(timezone.utc), 30, 60)
+        assert result["category"] == "stale"
+
+    def test_zombie_issue(self):
+        issue = _make_issue(days_old=100, days_idle=10, comments=0)
+        result = categorize_issue(issue, datetime.now(timezone.utc), 30, 60)
+        assert result["category"] == "zombie"
+
+    def test_unassigned_issue(self):
+        issue = _make_issue(assignees=[], days_old=5, days_idle=1)
+        result = categorize_issue(issue, datetime.now(timezone.utc), 30, 60)
+        assert result["category"] == "unassigned"
+
+    def test_assigned_issue(self):
+        issue = _make_issue(assignees=["alice"], days_old=5, days_idle=1)
+        result = categorize_issue(issue, datetime.now(timezone.utc), 30, 60)
+        assert result["category"] == "triage-needed"
+
+    def test_closeable_duplicate(self):
+        issue = _make_issue(labels=["duplicate"], days_old=5, days_idle=1)
+        result = categorize_issue(issue, datetime.now(timezone.utc), 30, 60)
+        assert result["category"] == "closeable"
+
+    def test_urgent_issue(self):
+        issue = _make_issue(labels=["p0-critical"], assignees=["bob"])
+        result = categorize_issue(issue, datetime.now(timezone.utc), 30, 60)
+        assert result["category"] == "urgent"
+
+    def test_backlog_issue(self):
+        issue = _make_issue(labels=["p2-backlog"], assignees=["bob"])
+        result = categorize_issue(issue, datetime.now(timezone.utc), 30, 60)
+        assert result["category"] == "backlog"
+
+    def test_bug_category(self):
+        issue = _make_issue(labels=["bug"], assignees=["bob"])
+        result = categorize_issue(issue, datetime.now(timezone.utc), 30, 60)
+        assert result["category"] == "bug"
+
+    def test_age_tracking(self):
+        issue = _make_issue(days_old=42, days_idle=7)
+        result = categorize_issue(issue, datetime.now(timezone.utc), 30, 60)
+        assert result["age_days"] >= 41
+        assert result["idle_days"] >= 6
+
+
+class TestGenerateReport:
+    def test_empty_report(self):
+        report = generate_report([])
+        assert report["total"] == 0
+        assert report["by_category"] == {}
+
+    def test_report_categorization(self):
+        issues = [
+            _make_issue(1, "idle", days_idle=70),
+            _make_issue(2, "stale", days_idle=40),
+            _make_issue(3, "recent", assignees=["alice"]),
+        ]
+        categorized = [categorize_issue(i, datetime.now(timezone.utc), 30, 60) for i in issues]
+        report = generate_report(categorized)
+        assert report["total"] == 3
+        assert "idle" in report["by_category"]
+        assert "stale" in report["by_category"]
+
+    def test_closeable_candidates(self):
+        issues = [
+            _make_issue(1, "old zombie", days_old=100, days_idle=100, comments=0),
+            _make_issue(2, "recent", assignees=["alice"]),
+        ]
+        categorized = [categorize_issue(i, datetime.now(timezone.utc), 30, 60) for i in issues]
+        report = generate_report(categorized)
+        assert len(report["closeable_candidates"]) >= 1
+        assert report["closeable_candidates"][0]["number"] == 1
+
+    def test_recommendations_generated(self):
+        issues = [_make_issue(1, days_idle=70)]
+        categorized = [categorize_issue(i, datetime.now(timezone.utc), 30, 60) for i in issues]
+        report = generate_report(categorized)
+        assert len(report["recommendations"]) > 0