@laitszkin/apollo-toolkit 2.0.0

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

@@ -0,0 +1,380 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from urllib import error, request
+
+GITHUB_API_BASE = "https://api.github.com"
+README_ACCEPT = "application/vnd.github.raw+json"
+JSON_ACCEPT = "application/vnd.github+json"
+DEFAULT_REPRO_ZH = "尚未穩定重現；需補充更多執行期資料。"
+DEFAULT_REPRO_EN = "Not yet reliably reproducible; more runtime evidence is required."
+ISSUE_TYPE_PROBLEM = "problem"
+ISSUE_TYPE_FEATURE = "feature"
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Publish a structured GitHub issue or feature proposal. "
+            "Auth order: gh CLI login -> GitHub token -> draft only."
+        )
+    )
+    parser.add_argument("--title", required=True, help="Issue title")
+    parser.add_argument(
+        "--issue-type",
+        choices=[ISSUE_TYPE_PROBLEM, ISSUE_TYPE_FEATURE],
+        default=ISSUE_TYPE_PROBLEM,
+        help="Structured issue type to publish.",
+    )
+    parser.add_argument(
+        "--problem-description",
+        help="Issue section content: problem description",
+    )
+    parser.add_argument(
+        "--suspected-cause",
+        help="Issue section content: suspected cause",
+    )
+    parser.add_argument(
+        "--reproduction",
+        help="Issue section content: reproduction conditions (optional)",
+    )
+    parser.add_argument(
+        "--proposal",
+        help="Issue section content: feature proposal summary (optional; defaults to title)",
+    )
+    parser.add_argument(
+        "--reason",
+        help="Issue section content: why the feature is needed",
+    )
+    parser.add_argument(
+        "--suggested-architecture",
+        help="Issue section content: suggested architecture for the feature",
+    )
+    parser.add_argument(
+        "--repo",
+        help="Target repository in owner/repo format. Defaults to origin remote.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Build and print payload only, without creating an issue.",
+    )
+    return parser.parse_args()
+
+
+def validate_issue_content_args(args: argparse.Namespace) -> None:
+    if args.issue_type == ISSUE_TYPE_FEATURE:
+        if not (args.reason or "").strip():
+            raise SystemExit("Feature issues require --reason.")
+        if not (args.suggested_architecture or "").strip():
+            raise SystemExit("Feature issues require --suggested-architecture.")
+        return
+
+    if not (args.problem_description or "").strip():
+        raise SystemExit("Problem issues require --problem-description.")
+    if not (args.suspected_cause or "").strip():
+        raise SystemExit("Problem issues require --suspected-cause.")
+
+
+def run_command(args: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(args, check=False, capture_output=True, text=True)
+
+
+def has_gh_auth() -> bool:
+    if shutil.which("gh") is None:
+        return False
+    result = run_command(["gh", "auth", "status"])
+    return result.returncode == 0
+
+
+def get_token() -> str | None:
+    for key in ("GITHUB_TOKEN", "GH_TOKEN"):
+        value = os.getenv(key, "").strip()
+        if value:
+            return value
+    return None
+
+
+def resolve_repo(explicit_repo: str | None) -> str:
+    if explicit_repo:
+        return validate_repo(explicit_repo)
+
+    remote_result = run_command(["git", "remote", "get-url", "origin"])
+    if remote_result.returncode != 0:
+        raise SystemExit("Unable to resolve origin remote. Pass --repo owner/repo.")
+
+    remote = remote_result.stdout.strip()
+    match = re.search(
+        r"github\.com[:/](?P<owner>[A-Za-z0-9_.-]+)/(?P<repo>[A-Za-z0-9_.-]+?)(?:\.git)?$",
+        remote,
+    )
+    if not match:
+        raise SystemExit("Origin remote is not a GitHub repository. Pass --repo owner/repo.")
+
+    return f"{match.group('owner')}/{match.group('repo')}"
+
+
+def validate_repo(repo: str) -> str:
+    candidate = repo.strip()
+    if not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", candidate):
+        raise SystemExit("Invalid repo format. Use owner/repo.")
+    return candidate
+
+
+def github_request(
+    method: str,
+    path: str,
+    *,
+    token: str | None,
+    accept: str,
+    payload: dict | None = None,
+) -> str:
+    headers = {
+        "Accept": accept,
+        "User-Agent": "open-github-issue-skill",
+        "X-GitHub-Api-Version": "2022-11-28",
+    }
+    data = None
+
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    if payload is not None:
+        data = json.dumps(payload).encode("utf-8")
+        headers["Content-Type"] = "application/json"
+
+    req = request.Request(
+        url=f"{GITHUB_API_BASE}{path}",
+        data=data,
+        headers=headers,
+        method=method,
+    )
+
+    try:
+        with request.urlopen(req, timeout=30) as response:
+            return response.read().decode("utf-8")
+    except error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"GitHub API {exc.code} {path}: {detail}") from exc
+    except error.URLError as exc:
+        raise RuntimeError(f"GitHub API request failed for {path}: {exc.reason}") from exc
+
+
+def fetch_remote_readme(repo: str, gh_authenticated: bool, token: str | None) -> str:
+    if gh_authenticated:
+        result = run_command(
+            ["gh", "api", "-H", f"Accept: {README_ACCEPT}", f"repos/{repo}/readme"]
+        )
+        if result.returncode == 0:
+            return result.stdout
+
+    try:
+        return github_request(
+            "GET",
+            f"/repos/{repo}/readme",
+            token=token,
+            accept=README_ACCEPT,
+        )
+    except RuntimeError:
+        return ""
+
+
+def detect_issue_language(readme_content: str) -> str:
+    if not readme_content.strip():
+        return "en"
+
+    chinese_chars = len(re.findall(r"[\u4e00-\u9fff]", readme_content))
+    language_chars = len(re.findall(r"[A-Za-z\u4e00-\u9fff]", readme_content))
+
+    if chinese_chars >= 20 and chinese_chars / max(language_chars, 1) >= 0.08:
+        return "zh"
+    return "en"
+
+
+def build_issue_body(
+    *,
+    issue_type: str,
+    language: str,
+    title: str,
+    problem_description: str | None,
+    suspected_cause: str | None,
+    reproduction: str | None,
+    proposal: str | None,
+    reason: str | None,
+    suggested_architecture: str | None,
+) -> str:
+    if issue_type == ISSUE_TYPE_FEATURE:
+        proposal_text = (proposal or title).strip()
+        reason_text = (reason or "").strip()
+        architecture_text = (suggested_architecture or "").strip()
+
+        if language == "zh":
+            return (
+                "### 功能提案\n"
+                f"{proposal_text}\n\n"
+                "### 原因\n"
+                f"{reason_text}\n\n"
+                "### 建議架構\n"
+                f"{architecture_text}\n"
+            )
+
+        return (
+            "### Feature Proposal\n"
+            f"{proposal_text}\n\n"
+            "### Why This Is Needed\n"
+            f"{reason_text}\n\n"
+            "### Suggested Architecture\n"
+            f"{architecture_text}\n"
+        )
+
+    if language == "zh":
+        repro_text = (reproduction or DEFAULT_REPRO_ZH).strip()
+        return (
+            "### 問題描述\n"
+            f"{(problem_description or '').strip()}\n\n"
+            "### 推測原因\n"
+            f"{(suspected_cause or '').strip()}\n\n"
+            "### 重現條件（如有）\n"
+            f"{repro_text}\n"
+        )
+
+    repro_text = (reproduction or DEFAULT_REPRO_EN).strip()
+    return (
+        "### Problem Description\n"
+        f"{(problem_description or '').strip()}\n\n"
+        "### Suspected Cause\n"
+        f"{(suspected_cause or '').strip()}\n\n"
+        "### Reproduction Conditions (if available)\n"
+        f"{repro_text}\n"
+    )
+
+
+def create_issue_with_gh(repo: str, title: str, body: str) -> str:
+    tmp_file: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile("w", encoding="utf-8", suffix=".md", delete=False) as handle:
+            handle.write(body)
+            tmp_file = Path(handle.name)
+
+        result = run_command(
+            [
+                "gh",
+                "issue",
+                "create",
+                "--repo",
+                repo,
+                "--title",
+                title,
+                "--body-file",
+                str(tmp_file),
+            ]
+        )
+        if result.returncode != 0:
+            raise RuntimeError(result.stderr.strip() or "gh issue create failed")
+
+        url_match = re.search(r"https://github\.com/[^\s]+/issues/\d+", result.stdout)
+        return url_match.group(0) if url_match else result.stdout.strip()
+    finally:
+        if tmp_file and tmp_file.exists():
+            tmp_file.unlink()
+
+
+def create_issue_with_token(repo: str, title: str, body: str, token: str) -> str:
+    response = github_request(
+        "POST",
+        f"/repos/{repo}/issues",
+        token=token,
+        accept=JSON_ACCEPT,
+        payload={"title": title, "body": body},
+    )
+    parsed = json.loads(response)
+    issue_url = parsed.get("html_url", "")
+    if not issue_url:
+        raise RuntimeError("Issue created but response did not include html_url")
+    return issue_url
+
+
+def main() -> int:
+    args = parse_args()
+    validate_issue_content_args(args)
+
+    gh_authenticated = has_gh_auth()
+    token = get_token()
+    repo = resolve_repo(args.repo)
+
+    readme_content = fetch_remote_readme(repo, gh_authenticated, token)
+    language = detect_issue_language(readme_content)
+
+    issue_body = build_issue_body(
+        issue_type=args.issue_type,
+        language=language,
+        title=args.title,
+        problem_description=args.problem_description,
+        suspected_cause=args.suspected_cause,
+        reproduction=args.reproduction,
+        proposal=args.proposal,
+        reason=args.reason,
+        suggested_architecture=args.suggested_architecture,
+    )
+
+    mode = "draft-only"
+    issue_url = ""
+    publish_error = ""
+
+    if args.dry_run:
+        mode = "dry-run"
+    elif gh_authenticated:
+        try:
+            issue_url = create_issue_with_gh(repo, args.title, issue_body)
+            mode = "gh-cli"
+        except RuntimeError as exc:
+            if token:
+                try:
+                    issue_url = create_issue_with_token(repo, args.title, issue_body, token)
+                    mode = "github-token"
+                except RuntimeError as token_exc:
+                    publish_error = str(token_exc)
+            else:
+                publish_error = str(exc)
+    elif token:
+        try:
+            issue_url = create_issue_with_token(repo, args.title, issue_body, token)
+            mode = "github-token"
+        except RuntimeError as exc:
+            publish_error = str(exc)
+
+    output = {
+        "repo": repo,
+        "issue_type": args.issue_type,
+        "language": "zh" if language == "zh" else "en",
+        "mode": mode,
+        "issue_url": issue_url,
+        "issue_title": args.title,
+        "issue_body": issue_body,
+        "publish_error": publish_error,
+    }
+    print(json.dumps(output, ensure_ascii=False))
+
+    if mode == "draft-only":
+        if publish_error:
+            print(f"Issue publish failed. Return draft only: {publish_error}", file=sys.stderr)
+        else:
+            print(
+                "No authenticated gh CLI session and no GitHub token found. "
+                "Return draft issue body only.",
+                file=sys.stderr,
+            )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import importlib.util
+import io
+import json
+import unittest
+from argparse import Namespace
+from pathlib import Path
+from unittest.mock import patch
+
+
+SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "open_github_issue.py"
+SPEC = importlib.util.spec_from_file_location("open_github_issue", SCRIPT_PATH)
+MODULE = importlib.util.module_from_spec(SPEC)
+SPEC.loader.exec_module(MODULE)
+
+
+class OpenGitHubIssueTests(unittest.TestCase):
+    def test_validate_repo_rejects_invalid_format(self) -> None:
+        with self.assertRaises(SystemExit):
+            MODULE.validate_repo("owner-only")
+
+    def test_detect_issue_language_prefers_chinese_when_threshold_met(self) -> None:
+        readme = "這是一個中文專案說明。" * 10
+
+        self.assertEqual(MODULE.detect_issue_language(readme), "zh")
+
+    def test_detect_issue_language_defaults_to_english_for_sparse_chinese(self) -> None:
+        readme = "English README with only 少量中文 and mostly latin text." * 2
+
+        self.assertEqual(MODULE.detect_issue_language(readme), "en")
+
+    def test_build_issue_body_uses_default_reproduction_text(self) -> None:
+        zh_body = MODULE.build_issue_body(
+            issue_type=MODULE.ISSUE_TYPE_PROBLEM,
+            language="zh",
+            title="[Log] 問題",
+            problem_description="問題",
+            suspected_cause="原因",
+            reproduction=None,
+            proposal=None,
+            reason=None,
+            suggested_architecture=None,
+        )
+        en_body = MODULE.build_issue_body(
+            issue_type=MODULE.ISSUE_TYPE_PROBLEM,
+            language="en",
+            title="[Log] problem",
+            problem_description="problem",
+            suspected_cause="cause",
+            reproduction=None,
+            proposal=None,
+            reason=None,
+            suggested_architecture=None,
+        )
+
+        self.assertIn(MODULE.DEFAULT_REPRO_ZH, zh_body)
+        self.assertIn(MODULE.DEFAULT_REPRO_EN, en_body)
+
+    def test_build_issue_body_supports_feature_issue_sections(self) -> None:
+        zh_body = MODULE.build_issue_body(
+            issue_type=MODULE.ISSUE_TYPE_FEATURE,
+            language="zh",
+            title="[Feature] 匯出事故時間線",
+            problem_description=None,
+            suspected_cause=None,
+            reproduction=None,
+            proposal="新增事故時間線匯出功能",
+            reason="減少手動整理 postmortem 成本",
+            suggested_architecture="重用時間線查詢服務，新增共用匯出模組",
+        )
+        en_body = MODULE.build_issue_body(
+            issue_type=MODULE.ISSUE_TYPE_FEATURE,
+            language="en",
+            title="[Feature] Export incident timeline",
+            problem_description=None,
+            suspected_cause=None,
+            reproduction=None,
+            proposal="Allow exporting incident timelines",
+            reason="Support postmortem handoff",
+            suggested_architecture="Add shared exporters and UI action",
+        )
+
+        self.assertIn("### 功能提案", zh_body)
+        self.assertIn("### 建議架構", zh_body)
+        self.assertIn("### Feature Proposal", en_body)
+        self.assertIn("### Suggested Architecture", en_body)
+
+    def test_validate_issue_content_args_requires_feature_fields(self) -> None:
+        with self.assertRaises(SystemExit):
+            MODULE.validate_issue_content_args(
+                Namespace(
+                    issue_type=MODULE.ISSUE_TYPE_FEATURE,
+                    reason="",
+                    suggested_architecture="shared module",
+                    problem_description=None,
+                    suspected_cause=None,
+                )
+            )
+
+        with self.assertRaises(SystemExit):
+            MODULE.validate_issue_content_args(
+                Namespace(
+                    issue_type=MODULE.ISSUE_TYPE_FEATURE,
+                    reason="important now",
+                    suggested_architecture="",
+                    problem_description=None,
+                    suspected_cause=None,
+                )
+            )
+
+        MODULE.validate_issue_content_args(
+            Namespace(
+                issue_type=MODULE.ISSUE_TYPE_FEATURE,
+                reason="important now",
+                suggested_architecture="shared module",
+                problem_description=None,
+                suspected_cause=None,
+            )
+        )
+
+    def test_main_dry_run_returns_structured_json_without_publish_attempt(self) -> None:
+        args = Namespace(
+            title="[Log] sample",
+            issue_type=MODULE.ISSUE_TYPE_PROBLEM,
+            problem_description="problem",
+            suspected_cause="handler.py:12",
+            reproduction=None,
+            proposal=None,
+            reason=None,
+            suggested_architecture=None,
+            repo="owner/repo",
+            dry_run=True,
+        )
+
+        with patch.object(MODULE, "parse_args", return_value=args), patch.object(
+            MODULE, "has_gh_auth", return_value=False
+        ), patch.object(MODULE, "get_token", return_value=None), patch.object(
+            MODULE, "fetch_remote_readme", return_value="中文說明" * 20
+        ), patch.object(MODULE, "create_issue_with_gh") as create_with_gh, patch.object(
+            MODULE, "create_issue_with_token"
+        ) as create_with_token, patch("sys.stdout", new_callable=io.StringIO) as stdout:
+            code = MODULE.main()
+
+        create_with_gh.assert_not_called()
+        create_with_token.assert_not_called()
+        self.assertEqual(code, 0)
+
+        payload = json.loads(stdout.getvalue())
+        self.assertEqual(payload["mode"], "dry-run")
+        self.assertEqual(payload["issue_type"], MODULE.ISSUE_TYPE_PROBLEM)
+        self.assertEqual(payload["language"], "zh")
+        self.assertIn("### 問題描述", payload["issue_body"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/open-source-pr-workflow/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog and this project follows Semantic Versioning.
+
+## [0.1.3] - 2026-02-22
+
+### Changed
+- Switch the PR workflow default to open PRs directly without waiting for draft confirmation.
+- Show PR drafts only when the user explicitly asks to review before PR creation.
+- Align SKILL.md, README highlights, and agent default prompt with the new draft-handling behavior.
+
+## [0.1.2] - 2026-02-20
+
+### Changed
+- Update branch naming convention from `codex/feature/{feature_name}` to `codex/{change_type}/{changes}` across skill docs and agent prompt.
+- Remove the required "Dependent Skill Updates" PR-body section so PR content stays focused on the change itself.
+- Clarify that internal skill/tool workflow details should not appear in PR title/body content.
+- Align README highlights and agent default prompt with the PR-content-only rule.
+
+## [0.1.1] - 2026-02-20
+
+### Changed
+- Require running `edge-case-test-fixer` and `code-simplifier` in sequence before opening a PR when code-affecting changes exist.
+- Add a required "Dependent Skill Updates" section to PR bodies to capture outputs from both dependency skills.
+- Align agent default prompt and README highlights with the dependency-skill workflow.
+
+## [0.1.0] - 2026-02-20
+
+### Added
+- Initial open-source PR workflow skill with branch naming, fork targeting defaults, and required PR content sections.

package/open-source-pr-workflow/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LTKSunny
+
+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/open-source-pr-workflow/README.md

@@ -0,0 +1,23 @@
+# open-source-pr-workflow
+
+A Codex skill focused on preparing and opening review-ready pull requests for open-source projects.
+
+## What this repository contains
+
+- `SKILL.md`: The main workflow definition.
+- `agents/openai.yaml`: Agent integration settings.
+
+## Highlights
+
+- Enforces branch naming convention: `codex/{change_type}/{changes}`
+- Focuses on PR preparation/creation instead of feature implementation
+- Opens PRs directly by default; only shows drafts when the user explicitly asks to review first
+- Defaults forked repositories to open PRs against the upstream parent repository (unless user explicitly requests the fork)
+- Requires clear PR sections for motivation, engineering rationale, and test results
+- For code changes, requires running `discover-edge-cases`, resolving confirmed findings, then running `code-simplifier` before opening PR
+- PR content should focus only on change motivation, decisions, and validation (no internal skill/tool process notes)
+- Encourages minimal, verifiable, review-ready contributions
+
+## License
+
+Released under the MIT License. See `LICENSE` for details.