@laitszkin/apollo-toolkit 2.0.0

package/resolve-review-comments/scripts/review_threads.py

@@ -0,0 +1,425 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+LIST_QUERY = """
+query($owner: String!, $name: String!, $number: Int!, $after: String) {
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      reviewThreads(first: 100, after: $after) {
+        nodes {
+          id
+          isResolved
+          isOutdated
+          path
+          line
+          startLine
+          comments(first: 20) {
+            nodes {
+              id
+              url
+              body
+              author {
+                login
+              }
+              createdAt
+              path
+              line
+              outdated
+            }
+          }
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  }
+}
+"""
+
+RESOLVE_MUTATION = """
+mutation($threadId: ID!) {
+  resolveReviewThread(input: {threadId: $threadId}) {
+    thread {
+      id
+      isResolved
+    }
+  }
+}
+"""
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="List and resolve GitHub PR review threads via gh graphql."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    list_parser = subparsers.add_parser("list", help="List review threads.")
+    add_common_args(list_parser)
+    list_parser.add_argument(
+        "--state",
+        choices=["unresolved", "resolved", "all"],
+        default="unresolved",
+        help="Thread state filter.",
+    )
+    list_parser.add_argument(
+        "--output",
+        choices=["table", "json"],
+        default="table",
+        help="Output format.",
+    )
+
+    resolve_parser = subparsers.add_parser("resolve", help="Resolve selected threads.")
+    add_common_args(resolve_parser)
+    resolve_parser.add_argument(
+        "--thread-id",
+        action="append",
+        default=[],
+        help="Thread GraphQL ID to resolve (repeatable).",
+    )
+    resolve_parser.add_argument(
+        "--thread-id-file",
+        help="Path to JSON file containing thread IDs.",
+    )
+    resolve_parser.add_argument(
+        "--all-unresolved",
+        action="store_true",
+        help="Resolve every unresolved thread in the PR.",
+    )
+    resolve_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print thread IDs without resolving.",
+    )
+
+    return parser.parse_args()
+
+
+def add_common_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--repo", help="Target repository in owner/name format.")
+    parser.add_argument("--pr", type=positive_int, help="Pull request number.")
+
+
+def positive_int(raw: str) -> int:
+    value = int(raw)
+    if value <= 0:
+        raise argparse.ArgumentTypeError("value must be a positive integer")
+    return value
+
+
+def run_gh(cmd: list[str], expect_json: bool = False) -> Any:
+    try:
+        result = subprocess.run(cmd, check=True, capture_output=True, text=True)
+    except FileNotFoundError as exc:
+        raise RuntimeError("gh CLI is not installed or not in PATH") from exc
+    except subprocess.CalledProcessError as exc:
+        stderr = exc.stderr.strip() or "gh command failed"
+        raise RuntimeError(stderr) from exc
+
+    if not expect_json:
+        return result.stdout.strip()
+
+    try:
+        return json.loads(result.stdout)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError("Failed to parse gh JSON output") from exc
+
+
+def parse_owner_repo(repo: str) -> tuple[str, str]:
+    parts = repo.split("/")
+    if len(parts) != 2 or not parts[0] or not parts[1]:
+        raise ValueError("repo must be in owner/name format")
+    return parts[0], parts[1]
+
+
+def resolve_repo(repo: str | None) -> str:
+    if repo:
+        parse_owner_repo(repo)
+        return repo
+
+    return run_gh(["gh", "repo", "view", "--json", "nameWithOwner", "--jq", ".nameWithOwner"])
+
+
+def resolve_pr_number(repo: str, pr: int | None) -> int:
+    if pr is not None:
+        return pr
+
+    value = run_gh(["gh", "pr", "view", "--repo", repo, "--json", "number", "--jq", ".number"])
+    try:
+        return int(value)
+    except ValueError as exc:
+        raise RuntimeError("Unable to infer PR number from current branch context") from exc
+
+
+def gh_graphql(query: str, variables: dict[str, Any]) -> dict[str, Any]:
+    cmd = ["gh", "api", "graphql", "-f", f"query={query}"]
+    for key, value in variables.items():
+        cmd.extend(["-F", f"{key}={json.dumps(value)}"])
+    return run_gh(cmd, expect_json=True)
+
+
+def fetch_review_threads(repo: str, pr_number: int) -> list[dict[str, Any]]:
+    owner, name = parse_owner_repo(repo)
+    threads: list[dict[str, Any]] = []
+    after: str | None = None
+
+    while True:
+        payload = gh_graphql(
+            LIST_QUERY,
+            {
+                "owner": owner,
+                "name": name,
+                "number": pr_number,
+                "after": after,
+            },
+        )
+        pr = payload["data"]["repository"]["pullRequest"]
+        if pr is None:
+            raise RuntimeError(f"PR #{pr_number} not found in {repo}")
+
+        review_threads = pr["reviewThreads"]
+        threads.extend(review_threads.get("nodes", []))
+
+        page_info = review_threads["pageInfo"]
+        if not page_info.get("hasNextPage"):
+            break
+        after = page_info.get("endCursor")
+
+    return threads
+
+
+def filter_threads(threads: list[dict[str, Any]], state: str) -> list[dict[str, Any]]:
+    if state == "all":
+        return threads
+    if state == "resolved":
+        return [item for item in threads if item.get("isResolved")]
+    return [item for item in threads if not item.get("isResolved")]
+
+
+def normalize_thread(thread: dict[str, Any]) -> dict[str, Any]:
+    comments = thread.get("comments", {}).get("nodes", [])
+    normalized_comments = [
+        {
+            "id": comment.get("id"),
+            "url": comment.get("url"),
+            "author": (comment.get("author") or {}).get("login"),
+            "body": comment.get("body", ""),
+            "created_at": comment.get("createdAt"),
+            "path": comment.get("path"),
+            "line": comment.get("line"),
+            "outdated": comment.get("outdated"),
+        }
+        for comment in comments
+    ]
+
+    return {
+        "thread_id": thread.get("id"),
+        "is_resolved": thread.get("isResolved"),
+        "is_outdated": thread.get("isOutdated"),
+        "path": thread.get("path"),
+        "line": thread.get("line"),
+        "start_line": thread.get("startLine"),
+        "comments": normalized_comments,
+    }
+
+
+def truncate(text: str, width: int) -> str:
+    if len(text) <= width:
+        return text
+    if width <= 3:
+        return text[:width]
+    return text[: width - 3] + "..."
+
+
+def preview_body(thread: dict[str, Any]) -> str:
+    comments = thread.get("comments", [])
+    if not comments:
+        return "-"
+    body = comments[0].get("body", "").replace("\n", " ").strip()
+    return truncate(body or "-", 72)
+
+
+def render_location(thread: dict[str, Any]) -> str:
+    path = thread.get("path") or "-"
+    line = thread.get("line")
+    if line is None:
+        return path
+    return f"{path}:{line}"
+
+
+def print_table(threads: list[dict[str, Any]]) -> None:
+    widths = {
+        "idx": 4,
+        "thread": 12,
+        "location": 36,
+        "author": 18,
+        "preview": 72,
+    }
+    header = (
+        f"{'#':<{widths['idx']}} "
+        f"{'THREAD_ID':<{widths['thread']}} "
+        f"{'LOCATION':<{widths['location']}} "
+        f"{'AUTHOR':<{widths['author']}} "
+        f"{'COMMENT_PREVIEW':<{widths['preview']}}"
+    )
+    print(header)
+    print("-" * len(header))
+
+    for idx, thread in enumerate(threads, start=1):
+        comments = thread.get("comments", [])
+        author = comments[0].get("author") if comments else "-"
+        row = (
+            f"{idx:<{widths['idx']}} "
+            f"{truncate(thread.get('thread_id', '-') or '-', widths['thread']):<{widths['thread']}} "
+            f"{truncate(render_location(thread), widths['location']):<{widths['location']}} "
+            f"{truncate(author or '-', widths['author']):<{widths['author']}} "
+            f"{preview_body(thread):<{widths['preview']}}"
+        )
+        print(row)
+
+
+def load_thread_ids(path: str) -> list[str]:
+    raw = Path(path).read_text(encoding="utf-8")
+    payload = json.loads(raw)
+
+    if isinstance(payload, list):
+        ids = payload
+    elif isinstance(payload, dict):
+        if "thread_ids" in payload:
+            ids = payload["thread_ids"]
+        elif "adopted_thread_ids" in payload:
+            ids = payload["adopted_thread_ids"]
+        elif "threads" in payload:
+            ids = [
+                item.get("thread_id")
+                for item in payload["threads"]
+                if isinstance(item, dict)
+            ]
+        else:
+            raise ValueError("JSON must include thread_ids, adopted_thread_ids, or threads")
+    else:
+        raise ValueError("Unsupported JSON payload for thread IDs")
+
+    output = [item for item in ids if isinstance(item, str) and item.strip()]
+    return list(dict.fromkeys(output))
+
+
+def collect_thread_ids(args: argparse.Namespace, unresolved_threads: list[dict[str, Any]]) -> list[str]:
+    ids: list[str] = []
+
+    if args.all_unresolved:
+        ids.extend([item["thread_id"] for item in unresolved_threads if item.get("thread_id")])
+
+    ids.extend(args.thread_id)
+
+    if args.thread_id_file:
+        ids.extend(load_thread_ids(args.thread_id_file))
+
+    normalized = [item for item in ids if item]
+    return list(dict.fromkeys(normalized))
+
+
+def resolve_threads(thread_ids: list[str], dry_run: bool) -> tuple[list[str], list[dict[str, str]]]:
+    resolved: list[str] = []
+    failed: list[dict[str, str]] = []
+
+    for thread_id in thread_ids:
+        if dry_run:
+            resolved.append(thread_id)
+            continue
+
+        try:
+            payload = gh_graphql(RESOLVE_MUTATION, {"threadId": thread_id})
+            thread = payload["data"]["resolveReviewThread"]["thread"]
+            if not thread or not thread.get("isResolved"):
+                raise RuntimeError("thread did not resolve")
+            resolved.append(thread_id)
+        except Exception as exc:  # pylint: disable=broad-except
+            failed.append({"thread_id": thread_id, "error": str(exc)})
+
+    return resolved, failed
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    repo = resolve_repo(args.repo)
+    pr_number = resolve_pr_number(repo, args.pr)
+
+    threads = fetch_review_threads(repo, pr_number)
+    filtered = filter_threads(threads, args.state)
+    normalized = [normalize_thread(item) for item in filtered]
+
+    result = {
+        "repo": repo,
+        "pr_number": pr_number,
+        "state": args.state,
+        "thread_count": len(normalized),
+        "threads": normalized,
+    }
+
+    if args.output == "json":
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(f"Repository: {repo}")
+        print(f"PR: #{pr_number}")
+        print(f"Threads ({args.state}): {len(normalized)}")
+        print_table(normalized)
+
+    return 0
+
+
+def cmd_resolve(args: argparse.Namespace) -> int:
+    repo = resolve_repo(args.repo)
+    pr_number = resolve_pr_number(repo, args.pr)
+
+    threads = fetch_review_threads(repo, pr_number)
+    unresolved = [normalize_thread(item) for item in filter_threads(threads, "unresolved")]
+    thread_ids = collect_thread_ids(args, unresolved)
+
+    if not thread_ids:
+        print(
+            "Error: no thread IDs selected. Use --thread-id, --thread-id-file, or --all-unresolved.",
+            file=sys.stderr,
+        )
+        return 1
+
+    resolved, failed = resolve_threads(thread_ids, args.dry_run)
+
+    summary = {
+        "repo": repo,
+        "pr_number": pr_number,
+        "requested": thread_ids,
+        "resolved": resolved,
+        "failed": failed,
+        "dry_run": args.dry_run,
+    }
+    print(json.dumps(summary, indent=2, ensure_ascii=False))
+
+    return 0 if not failed else 1
+
+
+def main() -> int:
+    args = parse_args()
+
+    try:
+        if args.command == "list":
+            return cmd_list(args)
+        if args.command == "resolve":
+            return cmd_resolve(args)
+        print(f"Unsupported command: {args.command}", file=sys.stderr)
+        return 1
+    except Exception as exc:  # pylint: disable=broad-except
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/resolve-review-comments/tests/test_review_threads.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "review_threads.py"
+SPEC = importlib.util.spec_from_file_location("review_threads", SCRIPT_PATH)
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+class ReviewThreadsTests(unittest.TestCase):
+    def test_parse_owner_repo(self) -> None:
+        self.assertEqual(MODULE.parse_owner_repo("octo/repo"), ("octo", "repo"))
+
+    def test_parse_owner_repo_rejects_invalid_format(self) -> None:
+        with self.assertRaises(ValueError):
+            MODULE.parse_owner_repo("octo")
+
+    def test_parse_owner_repo_rejects_extra_segments(self) -> None:
+        with self.assertRaises(ValueError):
+            MODULE.parse_owner_repo("octo/repo/extra")
+
+    def test_load_thread_ids_supports_multiple_shapes(self) -> None:
+        payload = {"adopted_thread_ids": ["A", "B", "A"]}
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            tmp_path = Path(tmp_dir) / "ids.json"
+            tmp_path.write_text(json.dumps(payload), encoding="utf-8")
+            ids = MODULE.load_thread_ids(str(tmp_path))
+
+        self.assertEqual(ids, ["A", "B"])
+
+    def test_collect_thread_ids_from_flags(self) -> None:
+        args = argparse.Namespace(
+            all_unresolved=True,
+            thread_id=["thread-2"],
+            thread_id_file=None,
+        )
+        unresolved = [{"thread_id": "thread-1"}, {"thread_id": "thread-2"}]
+
+        ids = MODULE.collect_thread_ids(args, unresolved)
+
+        self.assertEqual(ids, ["thread-1", "thread-2"])
+
+    def test_load_thread_ids_ignores_non_dict_thread_entries(self) -> None:
+        payload = {"threads": [{"thread_id": "A"}, "bad", 123, {"thread_id": "B"}]}
+        with tempfile.TemporaryDirectory() as tmp_dir:
+            tmp_path = Path(tmp_dir) / "ids.json"
+            tmp_path.write_text(json.dumps(payload), encoding="utf-8")
+            ids = MODULE.load_thread_ids(str(tmp_path))
+
+        self.assertEqual(ids, ["A", "B"])
+
+    def test_render_location_without_line(self) -> None:
+        self.assertEqual(MODULE.render_location({"path": "a.txt", "line": None}), "a.txt")
+
+    def test_filter_threads(self) -> None:
+        data = [
+            {"id": "a", "isResolved": True},
+            {"id": "b", "isResolved": False},
+        ]
+        self.assertEqual(len(MODULE.filter_threads(data, "resolved")), 1)
+        self.assertEqual(len(MODULE.filter_threads(data, "unresolved")), 1)
+        self.assertEqual(len(MODULE.filter_threads(data, "all")), 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/review-change-set/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lai Tsz Kin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/review-change-set/README.md

@@ -0,0 +1,55 @@
+# review-change-set
+
+`review-change-set` is a Codex skill for reviewing the active git diff like an independent reviewer.
+
+## What this skill does
+
+This skill:
+
+1. Reads the current git change set end-to-end.
+2. Rejects authorship bias, including confidence in code written earlier in the same conversation.
+3. Looks for architecture-level abstraction opportunities.
+4. Looks for code that can be simplified without changing behavior.
+5. Runs `harden-app-security` as a required adversarial cross-check for code-affecting changes.
+
+## When to use
+
+Use this skill when the task asks you to:
+
+- review the current diff before commit or PR,
+- find abstraction or modularization opportunities,
+- look for simplification or refactor candidates,
+- provide a reviewer-style second opinion on current changes.
+
+## Core principles
+
+- Read the diff first, then judge.
+- Treat recent edits as untrusted until evidence proves otherwise.
+- Prefer fewer, stronger findings over broad speculative advice.
+- Focus on architecture and simplification, not cosmetic style feedback.
+- Reuse confirmed security findings from `harden-app-security` instead of hand-waving about risk.
+
+## Example
+
+Prompt example:
+
+```text
+Review the current git diff like a skeptical reviewer.
+Find any architectural abstractions that should be extracted and any code that can be simplified.
+Do not defend the current implementation just because it was written in this conversation.
+```
+
+Expected behavior:
+
+- changed files are read before conclusions,
+- findings cite exact evidence,
+- architecture issues are prioritized over style comments,
+- security-sensitive changes are cross-checked through `harden-app-security`.
+
+## References
+
+- [`SKILL.md`](./SKILL.md) - full workflow and execution rules.
+
+## License
+
+MIT

package/review-change-set/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: review-change-set
+description: Review the current git change set from an unbiased reviewer perspective, identify architecture-level abstraction opportunities and code simplification candidates, and challenge security assumptions through harden-app-security. Use when users ask for a diff review, refactor review, abstraction review, simplification review, or a pre-commit/pre-PR second opinion on current changes.
+---
+
+# Review Change Set
+
+## Dependencies
+
+- Required: none.
+- Conditional: `harden-app-security` for code-affecting changes before finalizing review conclusions.
+- Optional: none.
+- Fallback: If the required security cross-check is unavailable for a code-affecting scope, stop and report the missing dependency.
+
+## Standards
+
+- Evidence: Read the full active diff plus the minimum dependency chain needed to understand the changed behavior.
+- Execution: Review architecture first, then simplification opportunities, then integrate confirmed security findings.
+- Quality: Judge the change set as an outsider, keep only actionable findings, and avoid inventing concerns the security pass did not confirm.
+- Output: Return review scope, architecture findings, simplification findings, security cross-check results, and residual uncertainty.
+
+## Overview
+
+Use this skill to review the active git change set as an outsider, not as the original author. The goal is to find actionable abstraction and simplification opportunities with evidence, not to defend the current implementation.
+
+## Non-negotiable Review Rules
+
+- Read the full active change set before judging any design choice.
+- Discard authorship bias completely, including changes written earlier in the same conversation by this agent.
+- Judge the diff from a reviewer perspective: the burden of proof is on the code, not on the author's intent.
+- Prefer architecture and maintainability findings over style-only feedback.
+- Recommend abstraction only when it reduces duplication, clarifies ownership, or stabilizes boundaries.
+- Recommend simplification only when it preserves behavior while reducing complexity or ambiguity.
+
+## Workflow
+
+### 1) Inspect the active git state
+
+- Run `git status -sb`, `git diff --stat`, and `git diff --cached --stat`.
+- If both staged and unstaged changes exist, review both and label which findings apply to each surface.
+- If there is no active diff, report `No active git change set to review` and stop.
+
+### 2) Build a factual baseline
+
+- Read every changed file end-to-end.
+- Read the minimum dependency chain needed to understand new helpers, moved logic, interfaces, and callers.
+- Reconstruct actual behavior from code, tests, configuration, and executable evidence only.
+- Ignore earlier planning context unless it is explicitly encoded in the repository.
+
+### 3) Review architecture first
+
+Check whether the diff introduces or preserves problems such as:
+
+- duplicated workflows that should live behind one module or helper,
+- cross-layer leakage or ownership confusion,
+- helper placement that hides domain boundaries,
+- repeated condition trees or mapping logic that should be centralized,
+- unstable interfaces or parameter shapes that should be normalized.
+
+Keep only findings that name the proposed abstraction target and explain why the current structure is weaker.
+
+### 4) Review simplification opportunities second
+
+Check whether the diff can be simplified through:
+
+- removing redundant branches, wrappers, or state,
+- flattening deeply nested control flow,
+- collapsing duplicated validation or conversion logic,
+- shrinking overly broad functions into clearer units,
+- deleting dead or no-longer-needed compatibility paths.
+
+Do not recommend refactors that merely move complexity around.
+
+### 5) Run the security cross-check
+
+- Invoke `harden-app-security` on the same code-affecting scope.
+- Integrate confirmed security findings into the final review when they materially affect the safety of the proposed structure.
+- Do not invent security concerns that the dependency did not confirm.
+
+### 6) Report only actionable review output
+
+Deliver:
+
+1. Review scope
+   - staged / unstaged coverage
+   - additional files read for context
+2. Architecture findings
+   - title
+   - evidence (`path:line`)
+   - abstraction candidate
+   - why the current design is weaker
+3. Simplification findings
+   - title
+   - evidence (`path:line`)
+   - simplification candidate
+   - expected benefit
+4. Security cross-check
+   - confirmed findings reused from `harden-app-security`
+   - reason they matter to this diff review
+5. Residual uncertainty
+   - hypotheses or follow-up checks that were not confirmed
+
+If no actionable issue is found, report `No actionable abstraction or simplification finding identified`.

package/review-change-set/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Review Change Set"
+  short_description: "Review the active git diff for abstraction and simplification opportunities"
+  default_prompt: "Use $review-change-set to read the active git change set end-to-end, discard any bias toward code written earlier in the conversation, review it like an independent reviewer for architecture-level abstraction and simplification opportunities, and run $harden-app-security as an adversarial cross-check for code-affecting changes."