@laitszkin/apollo-toolkit 2.11.1 → 2.11.3

package/open-github-issue/scripts/open_github_issue.py

@@ -19,6 +19,18 @@ DEFAULT_REPRO_ZH = "尚未穩定重現；需補充更多執行期資料。"
 DEFAULT_REPRO_EN = "Not yet reliably reproducible; more runtime evidence is required."
 ISSUE_TYPE_PROBLEM = "problem"
 ISSUE_TYPE_FEATURE = "feature"
+ISSUE_TYPE_PERFORMANCE = "performance"
+ISSUE_TYPE_SECURITY = "security"
+ISSUE_TYPE_DOCS = "docs"
+ISSUE_TYPE_OBSERVABILITY = "observability"
+ISSUE_TYPES = [
+    ISSUE_TYPE_PROBLEM,
+    ISSUE_TYPE_FEATURE,
+    ISSUE_TYPE_PERFORMANCE,
+    ISSUE_TYPE_SECURITY,
+    ISSUE_TYPE_DOCS,
+    ISSUE_TYPE_OBSERVABILITY,
+]
 PROBLEM_BDD_MARKER_GROUPS = (
     (
         r"Expected Behavior\s*\(BDD\)",
@@ -43,7 +55,7 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--title", required=True, help="Issue title")
     parser.add_argument(
         "--issue-type",
-        choices=[ISSUE_TYPE_PROBLEM, ISSUE_TYPE_FEATURE],
+        choices=ISSUE_TYPES,
         default=ISSUE_TYPE_PROBLEM,
         help="Structured issue type to publish.",
     )
@@ -71,6 +83,27 @@ def parse_args() -> argparse.Namespace:
         "--suggested-architecture",
         help="Issue section content: suggested architecture for the feature",
     )
+    parser.add_argument(
+        "--impact",
+        help="Issue section content: concrete user, system, or business impact",
+    )
+    parser.add_argument(
+        "--evidence",
+        help="Issue section content: concrete evidence, metrics, logs, or repository facts",
+    )
+    parser.add_argument(
+        "--suggested-action",
+        help="Issue section content: suggested remediation, mitigation, or next action",
+    )
+    parser.add_argument(
+        "--severity",
+        choices=["critical", "high", "medium", "low"],
+        help="Issue section content: severity level for security-oriented issues",
+    )
+    parser.add_argument(
+        "--affected-scope",
+        help="Issue section content: affected endpoint, module, user cohort, or system surface",
+    )
     parser.add_argument(
         "--repo",
         help="Target repository in owner/repo format. Defaults to origin remote.",
@@ -91,6 +124,35 @@ def validate_issue_content_args(args: argparse.Namespace) -> None:
             raise SystemExit("Feature issues require --suggested-architecture.")
         return
 
+    if args.issue_type == ISSUE_TYPE_PERFORMANCE:
+        require_non_empty(args.problem_description, "Performance issues require --problem-description.")
+        require_non_empty(args.impact, "Performance issues require --impact.")
+        require_non_empty(args.evidence, "Performance issues require --evidence.")
+        require_non_empty(args.suggested_action, "Performance issues require --suggested-action.")
+        return
+
+    if args.issue_type == ISSUE_TYPE_SECURITY:
+        require_non_empty(args.problem_description, "Security issues require --problem-description.")
+        require_non_empty(args.affected_scope, "Security issues require --affected-scope.")
+        require_non_empty(args.impact, "Security issues require --impact.")
+        require_non_empty(args.evidence, "Security issues require --evidence.")
+        require_non_empty(args.suggested_action, "Security issues require --suggested-action.")
+        require_non_empty(args.severity, "Security issues require --severity.")
+        return
+
+    if args.issue_type == ISSUE_TYPE_DOCS:
+        require_non_empty(args.problem_description, "Docs issues require --problem-description.")
+        require_non_empty(args.evidence, "Docs issues require --evidence.")
+        require_non_empty(args.suggested_action, "Docs issues require --suggested-action.")
+        return
+
+    if args.issue_type == ISSUE_TYPE_OBSERVABILITY:
+        require_non_empty(args.problem_description, "Observability issues require --problem-description.")
+        require_non_empty(args.impact, "Observability issues require --impact.")
+        require_non_empty(args.evidence, "Observability issues require --evidence.")
+        require_non_empty(args.suggested_action, "Observability issues require --suggested-action.")
+        return
+
     if not (args.problem_description or "").strip():
         raise SystemExit("Problem issues require --problem-description.")
     if not (args.suspected_cause or "").strip():
@@ -102,6 +164,11 @@ def validate_issue_content_args(args: argparse.Namespace) -> None:
         )
 
 
+def require_non_empty(value: str | None, message: str) -> None:
+    if not (value or "").strip():
+        raise SystemExit(message)
+
+
 def has_required_problem_bdd_sections(problem_description: str) -> bool:
     normalized = problem_description.strip()
     return any(
@@ -236,6 +303,11 @@ def build_issue_body(
     proposal: str | None,
     reason: str | None,
     suggested_architecture: str | None,
+    impact: str | None = None,
+    evidence: str | None = None,
+    suggested_action: str | None = None,
+    severity: str | None = None,
+    affected_scope: str | None = None,
 ) -> str:
     if issue_type == ISSUE_TYPE_FEATURE:
         proposal_text = (proposal or title).strip()
@@ -261,6 +333,102 @@ def build_issue_body(
             f"{architecture_text}\n"
         )
 
+    if issue_type == ISSUE_TYPE_PERFORMANCE:
+        if language == "zh":
+            return (
+                "### 效能問題\n"
+                f"{(problem_description or '').strip()}\n\n"
+                "### 影響\n"
+                f"{(impact or '').strip()}\n\n"
+                "### 證據\n"
+                f"{(evidence or '').strip()}\n\n"
+                "### 建議行動\n"
+                f"{(suggested_action or '').strip()}\n"
+            )
+        return (
+            "### Performance Problem\n"
+            f"{(problem_description or '').strip()}\n\n"
+            "### Impact\n"
+            f"{(impact or '').strip()}\n\n"
+            "### Evidence\n"
+            f"{(evidence or '').strip()}\n\n"
+            "### Suggested Action\n"
+            f"{(suggested_action or '').strip()}\n"
+        )
+
+    if issue_type == ISSUE_TYPE_SECURITY:
+        if language == "zh":
+            return (
+                "### 安全風險\n"
+                f"{(problem_description or '').strip()}\n\n"
+                "### 嚴重程度\n"
+                f"{(severity or '').strip()}\n\n"
+                "### 受影響範圍\n"
+                f"{(affected_scope or '').strip()}\n\n"
+                "### 影響\n"
+                f"{(impact or '').strip()}\n\n"
+                "### 證據\n"
+                f"{(evidence or '').strip()}\n\n"
+                "### 建議緩解\n"
+                f"{(suggested_action or '').strip()}\n"
+            )
+        return (
+            "### Security Risk\n"
+            f"{(problem_description or '').strip()}\n\n"
+            "### Severity\n"
+            f"{(severity or '').strip()}\n\n"
+            "### Affected Scope\n"
+            f"{(affected_scope or '').strip()}\n\n"
+            "### Impact\n"
+            f"{(impact or '').strip()}\n\n"
+            "### Evidence\n"
+            f"{(evidence or '').strip()}\n\n"
+            "### Suggested Mitigation\n"
+            f"{(suggested_action or '').strip()}\n"
+        )
+
+    if issue_type == ISSUE_TYPE_DOCS:
+        if language == "zh":
+            return (
+                "### 文件缺口\n"
+                f"{(problem_description or '').strip()}\n\n"
+                "### 證據\n"
+                f"{(evidence or '').strip()}\n\n"
+                "### 建議更新\n"
+                f"{(suggested_action or '').strip()}\n"
+            )
+        return (
+            "### Documentation Gap\n"
+            f"{(problem_description or '').strip()}\n\n"
+            "### Evidence\n"
+            f"{(evidence or '').strip()}\n\n"
+            "### Suggested Update\n"
+            f"{(suggested_action or '').strip()}\n"
+        )
+
+    if issue_type == ISSUE_TYPE_OBSERVABILITY:
+        if language == "zh":
+            return (
+                "### 可觀測性缺口\n"
+                f"{(problem_description or '').strip()}\n\n"
+                "### 影響\n"
+                f"{(impact or '').strip()}\n\n"
+                "### 證據\n"
+                f"{(evidence or '').strip()}\n\n"
+                "### 建議儀表化\n"
+                f"{(suggested_action or '').strip()}\n"
+            )
+        return (
+            "### Observability Gap\n"
+            f"{(problem_description or '').strip()}\n\n"
+            "### Impact\n"
+            f"{(impact or '').strip()}\n\n"
+            "### Evidence\n"
+            f"{(evidence or '').strip()}\n\n"
+            "### Suggested Instrumentation\n"
+            f"{(suggested_action or '').strip()}\n"
+        )
+
     if language == "zh":
         repro_text = (reproduction or DEFAULT_REPRO_ZH).strip()
         return (
@@ -349,6 +517,11 @@ def main() -> int:
         proposal=args.proposal,
         reason=args.reason,
         suggested_architecture=args.suggested_architecture,
+        impact=args.impact,
+        evidence=args.evidence,
+        suggested_action=args.suggested_action,
+        severity=args.severity,
+        affected_scope=args.affected_scope,
     )
 
     mode = "draft-only"

package/open-github-issue/tests/test_open_github_issue.py

@@ -81,6 +81,11 @@ class OpenGitHubIssueTests(unittest.TestCase):
             proposal="Allow exporting incident timelines",
             reason="Support postmortem handoff",
             suggested_architecture="Add shared exporters and UI action",
+            impact=None,
+            evidence=None,
+            suggested_action=None,
+            severity=None,
+            affected_scope=None,
         )
 
         self.assertIn("### 功能提案", zh_body)
@@ -88,6 +93,28 @@ class OpenGitHubIssueTests(unittest.TestCase):
         self.assertIn("### Feature Proposal", en_body)
         self.assertIn("### Suggested Architecture", en_body)
 
+    def test_build_issue_body_supports_security_issue_sections(self) -> None:
+        en_body = MODULE.build_issue_body(
+            issue_type=MODULE.ISSUE_TYPE_SECURITY,
+            language="en",
+            title="[Security] Missing auth",
+            problem_description="Endpoint misses admin check",
+            suspected_cause=None,
+            reproduction=None,
+            proposal=None,
+            reason=None,
+            suggested_architecture=None,
+            impact="Sensitive export may leak",
+            evidence="Reproduced request and code path review",
+            suggested_action="Add authz and tests",
+            severity="high",
+            affected_scope="/admin/export",
+        )
+
+        self.assertIn("### Security Risk", en_body)
+        self.assertIn("### Severity", en_body)
+        self.assertIn("### Suggested Mitigation", en_body)
+
     def test_validate_issue_content_args_requires_feature_fields(self) -> None:
         with self.assertRaises(SystemExit):
             MODULE.validate_issue_content_args(
@@ -118,6 +145,43 @@ class OpenGitHubIssueTests(unittest.TestCase):
                 suggested_architecture="shared module",
                 problem_description=None,
                 suspected_cause=None,
+                impact=None,
+                evidence=None,
+                suggested_action=None,
+                severity=None,
+                affected_scope=None,
+            )
+        )
+
+    def test_validate_issue_content_args_requires_security_fields(self) -> None:
+        with self.assertRaises(SystemExit):
+            MODULE.validate_issue_content_args(
+                Namespace(
+                    issue_type=MODULE.ISSUE_TYPE_SECURITY,
+                    problem_description="auth missing",
+                    affected_scope="",
+                    impact="sensitive export may leak",
+                    evidence="reproduced",
+                    suggested_action="add authz",
+                    severity="high",
+                    reason=None,
+                    suggested_architecture=None,
+                    suspected_cause=None,
+                )
+            )
+
+        MODULE.validate_issue_content_args(
+            Namespace(
+                issue_type=MODULE.ISSUE_TYPE_SECURITY,
+                problem_description="auth missing",
+                affected_scope="/admin/export",
+                impact="sensitive export may leak",
+                evidence="reproduced",
+                suggested_action="add authz",
+                severity="high",
+                reason=None,
+                suggested_architecture=None,
+                suspected_cause=None,
             )
         )
 
@@ -130,6 +194,11 @@ class OpenGitHubIssueTests(unittest.TestCase):
                     suggested_architecture=None,
                     problem_description="Repeated timeout warnings escalated into request failures.",
                     suspected_cause="handler.py:12",
+                    impact=None,
+                    evidence=None,
+                    suggested_action=None,
+                    severity=None,
+                    affected_scope=None,
                 )
             )
 
@@ -153,6 +222,11 @@ class OpenGitHubIssueTests(unittest.TestCase):
                     "- Difference/Impact: users still receive errors.\n"
                 ),
                 suspected_cause="handler.py:12",
+                impact=None,
+                evidence=None,
+                suggested_action=None,
+                severity=None,
+                affected_scope=None,
             )
         )
 
@@ -181,6 +255,11 @@ class OpenGitHubIssueTests(unittest.TestCase):
             suggested_architecture=None,
             repo="owner/repo",
             dry_run=True,
+            impact=None,
+            evidence=None,
+            suggested_action=None,
+            severity=None,
+            affected_scope=None,
         )
 
         with patch.object(MODULE, "parse_args", return_value=args), patch.object(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laitszkin/apollo-toolkit",
-  "version": "2.11.1",
+  "version": "2.11.3",
   "description": "Apollo Toolkit npm installer for managed skill copying across Codex, OpenClaw, and Trae.",
   "license": "MIT",
   "author": "LaiTszKin",

package/read-github-issue/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: read-github-issue
+description: Read and search remote GitHub issues via GitHub CLI (`gh`). Use when users ask to list issues, filter issue candidates, inspect a specific issue with comments, or gather issue context before planning follow-up work.
+---
+
+# Read GitHub Issue
+
+## Dependencies
+
+- Required: none.
+- Conditional: none.
+- Optional: none.
+- Fallback: If `gh` is unavailable or unauthenticated, stop and report the exact blocked command instead of guessing repository state.
+
+## Standards
+
+- Evidence: Verify repository context first, then read remote issue data directly from `gh issue list` / `gh issue view` instead of paraphrasing from memory.
+- Execution: Confirm the target repo, find candidate issues with the bundled script, then inspect the chosen issue with comments and structured fields.
+- Quality: Keep the skill focused on issue discovery and retrieval only; do not embed any hardcoded fixing, branching, PR, or push workflow.
+- Output: Return candidate issues, selected issue details, comments summary, and any missing information needed before follow-up work.
+
+## Overview
+
+Use this skill to gather trustworthy GitHub issue context with `gh`: discover open or closed issues, narrow them with labels or search text, then inspect a chosen issue in detail before any separate planning or implementation workflow begins.
+
+## Prerequisites
+
+- `gh` is installed and authenticated (`gh auth status`).
+- The current directory is a git repository with the correct `origin`, or the user provides `--repo owner/name`.
+
+## Workflow
+
+### 1) Verify repository and remote context
+
+- Run `gh repo view --json nameWithOwner,isPrivate,defaultBranchRef` to confirm target repo.
+- If the user specifies another repository, always use `--repo <owner>/<repo>` in issue commands.
+
+### 2) Find candidate issues with the bundled script
+
+- Preferred command:
+
+```bash
+python3 scripts/find_issues.py --limit 50 --state open
+```
+
+- Optional filters:
+  - `--repo owner/name`
+  - `--label bug`
+  - `--search "panic in parser"`
+- If the issue target is still unclear, present top candidates and ask which issue number or URL should be inspected next.
+
+### 3) Read a specific issue in detail
+
+- Preferred command:
+
+```bash
+python3 scripts/read_issue.py 123 --comments
+```
+
+- Optional flags:
+  - `--repo owner/name`
+  - `--json`
+  - `--comments`
+- Use the returned title, body, labels, assignees, state, timestamps, and comments to summarize the issue precisely.
+
+### 4) Summarize gaps before any follow-up action
+
+- Identify missing acceptance criteria, repro details, affected components, or environment context.
+- If issue text and comments are insufficient, state exactly what is missing instead of inventing a fix plan.
+
+## Included Script
+
+### `scripts/find_issues.py`
+
+- Purpose: consistent remote issue listing via `gh issue list`.
+- Outputs a readable table by default, or JSON with `--output json`.
+- Uses only GitHub CLI so it reflects remote GitHub state.
+
+### `scripts/read_issue.py`
+
+- Purpose: deterministic issue detail retrieval via `gh issue view`.
+- Outputs either a human-readable summary or full JSON for downstream automation.
+- Can include issue comments so the agent can read the latest discussion before taking any other step.

package/read-github-issue/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Read GitHub Issue"
+  short_description: "Read and search remote GitHub issues"
+  default_prompt: "Use $read-github-issue to verify the target GitHub repository with gh, find candidate issues with the bundled issue-search script, inspect the selected issue with comments and structured fields, summarize the trustworthy issue context, and call out any missing details before any separate planning or implementation work."

package/{fix-github-issues/scripts/list_issues.py → read-github-issue/scripts/find_issues.py}

@@ -17,7 +17,7 @@ def positive_int(raw: str) -> int:
 
 def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser(
-        description="List remote GitHub issues with gh CLI and display table or JSON output."
+        description="Find remote GitHub issues with gh CLI and display table or JSON output."
     )
     parser.add_argument("--repo", help="Target repository in owner/name format.")
     parser.add_argument("--state", default="open", choices=["open", "closed", "all"])

package/read-github-issue/scripts/read_issue.py

@@ -0,0 +1,108 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+
+
+ISSUE_FIELDS = "number,title,body,state,author,labels,assignees,comments,createdAt,updatedAt,closedAt,url"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Read a remote GitHub issue with gh CLI and display summary or JSON output."
+    )
+    parser.add_argument("issue", help="Issue number or URL.")
+    parser.add_argument("--repo", help="Target repository in owner/name format.")
+    parser.add_argument(
+        "--comments",
+        action="store_true",
+        help="Keep issue comments in formatted output.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Print raw JSON output.",
+    )
+    return parser.parse_args()
+
+
+def build_command(args: argparse.Namespace) -> list[str]:
+    cmd = [
+        "gh",
+        "issue",
+        "view",
+        args.issue,
+        "--json",
+        ISSUE_FIELDS,
+    ]
+    if args.repo:
+        cmd.extend(["--repo", args.repo])
+    return cmd
+
+
+def join_names(items: list[dict], key: str) -> str:
+    values = [item.get(key, "") for item in items if item.get(key)]
+    return ", ".join(values) if values else "-"
+
+
+def print_summary(issue: dict, include_comments: bool) -> None:
+    print(f"Number: #{issue.get('number', '')}")
+    print(f"Title: {issue.get('title', '')}")
+    print(f"State: {issue.get('state', '')}")
+    print(f"URL: {issue.get('url', '')}")
+    print(f"Author: {(issue.get('author') or {}).get('login', '-')}")
+    print(f"Labels: {join_names(issue.get('labels', []), 'name')}")
+    print(f"Assignees: {join_names(issue.get('assignees', []), 'login')}")
+    print(f"Created: {issue.get('createdAt', '')}")
+    print(f"Updated: {issue.get('updatedAt', '')}")
+    print(f"Closed: {issue.get('closedAt', '') or '-'}")
+    print("")
+    print("Body:")
+    print(issue.get("body", "") or "-")
+
+    if include_comments:
+        comments = issue.get("comments", [])
+        print("")
+        print(f"Comments ({len(comments)}):")
+        if not comments:
+            print("-")
+            return
+        for comment in comments:
+            author = (comment.get("author") or {}).get("login", "-")
+            created = comment.get("createdAt", "")
+            body = comment.get("body", "") or "-"
+            print(f"- [{created}] {author}: {body}")
+
+
+def main() -> int:
+    args = parse_args()
+    cmd = build_command(args)
+
+    try:
+        result = subprocess.run(cmd, check=True, capture_output=True, text=True)
+    except FileNotFoundError:
+        print("Error: gh CLI is not installed or not in PATH.", file=sys.stderr)
+        return 1
+    except subprocess.CalledProcessError as exc:
+        print(exc.stderr.strip() or "gh issue view failed.", file=sys.stderr)
+        return exc.returncode
+
+    try:
+        issue = json.loads(result.stdout)
+    except json.JSONDecodeError:
+        print("Error: unable to parse gh output as JSON.", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(json.dumps(issue, indent=2))
+        return 0
+
+    print_summary(issue, include_comments=args.comments)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/{fix-github-issues/tests/test_list_issues.py → read-github-issue/tests/test_find_issues.py}

@@ -12,13 +12,13 @@ from pathlib import Path
 from unittest.mock import patch
 
 
-SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "list_issues.py"
-SPEC = importlib.util.spec_from_file_location("list_issues", SCRIPT_PATH)
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "find_issues.py"
+SPEC = importlib.util.spec_from_file_location("find_issues", SCRIPT_PATH)
 MODULE = importlib.util.module_from_spec(SPEC)
 SPEC.loader.exec_module(MODULE)
 
 
-class ListIssuesTests(unittest.TestCase):
+class FindIssuesTests(unittest.TestCase):
     def test_build_command_with_filters(self) -> None:
         args = Namespace(
             repo="owner/repo",