@openhands/extensions 0.18.0 → 0.20.0

package/.agents/skills/custom-codereview-guide.md

@@ -7,6 +7,13 @@ triggers:
 
 # Extensions Repo — Code Review Guidelines
 
+## Repository Boundaries
+
+Review whether a PR belongs in this public extensions registry. Skills, plugins, automations, and integrations belong here; Agent Server behavior and API endpoints belong in [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk), typed browser API access belongs in [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client), UI belongs in [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands), and scheduling/dispatch lifecycle behavior belongs in [`OpenHands/automation`](https://github.com/OpenHands/automation).
+
+If a PR is opened in the wrong repository, explicitly recommend that it may need to be closed and moved to the repository that owns the change rather than merged here. Apply the repository's contribution and review guidance to every PR.
+
+
 ## SDK Documentation Placement
 
 If a PR adds or modifies OpenHands SDK-specific documentation (API guides, SDK usage examples, SDK feature descriptions), flag it:

package/.github/dependabot.yml

@@ -0,0 +1,24 @@
+# Keep dependency update scheduling centralized in this repository configuration.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: ci(deps)
+
+  - package-ecosystem: npm
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: chore(deps)
+      include: scope
+
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: chore(deps)

package/.github/scripts/check_issue_readiness.py

@@ -0,0 +1,272 @@
+"""Determine whether an issue meets the `ready-for-dev` readiness criteria.
+
+The criteria are type-specific and tailored to extension contributions
+(skills, plugins, integrations, and automations):
+
+- Bug reports (labeled `bug`): the Actual Behavior section must describe a
+  reproducible run and include a supported validation command (`uv`,
+  `pytest`, `python`, `pip`, `npm`, or `node`), plus a non-empty Acceptance
+  Criteria section with at least one checklist item.
+
+- Enhancements (labeled `enhancement`): the body must contain non-empty
+  Desired Behavior and Acceptance Criteria sections, the latter with at
+  least one checklist item.
+
+GitHub issue forms render each field as an `### <Label>` (h3) heading followed
+by the field text, with empty optional fields rendered as `_No response_`. This
+parser splits the body on those headings so each criterion is checked against
+the right field rather than the whole body.
+
+Local usage:
+
+    python .github/scripts/check_issue_readiness.py --body-file /tmp/issue.md \
+        --labels bug
+    python .github/scripts/check_issue_readiness.py --event-path "$GITHUB_EVENT_PATH"
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+BUG_LABEL = "bug"
+ENHANCEMENT_LABEL = "enhancement"
+
+# Issue-form fields render as `### Label` h3 headings. Match case-insensitively
+# and tolerate trailing whitespace/colons. `^###\s+` is specific enough because
+# h1/h2 are not produced by issue forms.
+HEADING_RE = re.compile(r"(?m)^###\s+(.+?)\s*$")
+
+# `_No response_` is what GitHub writes for an empty optional form field.
+NO_RESPONSE = "_No response_"
+
+# A reproducible command must appear in the Actual Behavior section. These are
+# the commands a contributor can run in this repository: the Python test
+# tooling (`uv run pytest`, `pytest`, `python`, `pip`) and the catalog build /
+# validation tooling (`npm run build:*`, `node`).
+RUN_METHOD_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"\bpython\b", re.IGNORECASE),
+    re.compile(r"\bpytest\b", re.IGNORECASE),
+    re.compile(r"\buv\b", re.IGNORECASE),
+    re.compile(r"\bpip\b", re.IGNORECASE),
+    re.compile(r"\bnpm\b", re.IGNORECASE),
+    re.compile(r"\bnode\b", re.IGNORECASE),
+)
+
+# An Acceptance Criteria item is a markdown checklist bullet (`- [ ]` or
+# `- [x]`). We require at least one so the section is verifiable.
+CHECKLIST_ITEM_RE = re.compile(r"(?m)^\s*[-*]\s*\[[ xX]\]")
+
+
+@dataclass
+class ReadinessResult:
+    """Outcome of a readiness check."""
+
+    ready: bool
+    reasons: list[str] = field(default_factory=list)
+
+    def add(self, reason: str) -> None:
+        self.reasons.append(reason)
+        self.ready = False
+
+
+def visible_text(text: str) -> str:
+    """Return field text with HTML comments stripped and emptiness normalized."""
+    cleaned = re.sub(r"<!--[\s\S]*?-->", "", text).strip()
+    if cleaned == NO_RESPONSE:
+        return ""
+    return cleaned
+
+
+def extract_sections(body: str) -> dict[str, str]:
+    """Split the body into a {heading: text} map using `### <heading>` boundaries.
+
+    Issue forms render every field this way. Free-form issues (not created via a
+    form) may still use `###` headings; if they don't, the map is empty and the
+    caller falls back to whole-body checks.
+    """
+    matches = list(HEADING_RE.finditer(body))
+    sections: dict[str, str] = {}
+    for index, match in enumerate(matches):
+        start = match.end()
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(body)
+        sections[match.group(1).strip().lower()] = body[start:end]
+    return sections
+
+
+def find_section(sections: dict[str, str], *labels: str) -> str:
+    """Return the first matching section text by case-insensitive label."""
+    for label in labels:
+        if label in sections:
+            return sections[label]
+    return ""
+
+
+def references_run_method(text: str) -> bool:
+    return any(pattern.search(text) for pattern in RUN_METHOD_PATTERNS)
+
+
+def has_checklist_item(text: str) -> bool:
+    return bool(CHECKLIST_ITEM_RE.search(text))
+
+
+def check_bug(sections: dict[str, str]) -> ReadinessResult:
+    result = ReadinessResult(ready=True)
+
+    actual = visible_text(find_section(sections, "actual behavior", "actual"))
+    if not actual:
+        result.add(
+            "Fill in the `### Actual Behavior` section with reproducible steps "
+            "and the observed result."
+        )
+    elif not references_run_method(actual):
+        result.add(
+            "The Actual Behavior section must include a reproducible command "
+            "such as `uv run pytest`, `pytest`, `python`, `pip`, `npm run`, "
+            "or `node`."
+        )
+
+    acceptance = visible_text(
+        find_section(sections, "acceptance criteria", "acceptance")
+    )
+    if not acceptance:
+        result.add(
+            "Add an `### Acceptance Criteria` section with testable checklist items."
+        )
+    elif not has_checklist_item(acceptance):
+        result.add(
+            "The Acceptance Criteria section must contain at least one checklist item "
+            "(`- [ ] ...`)."
+        )
+
+    return result
+
+
+def check_enhancement(sections: dict[str, str]) -> ReadinessResult:
+    result = ReadinessResult(ready=True)
+
+    desired = visible_text(find_section(sections, "desired behavior", "desired"))
+    if not desired:
+        result.add(
+            "Add a `### Desired Behavior` section describing the behavior you want."
+        )
+
+    acceptance = visible_text(
+        find_section(sections, "acceptance criteria", "acceptance")
+    )
+    if not acceptance:
+        result.add(
+            "Add an `### Acceptance Criteria` section with testable checklist items."
+        )
+    elif not has_checklist_item(acceptance):
+        result.add(
+            "The Acceptance Criteria section must contain at least one checklist item "
+            "(`- [ ] ...`)."
+        )
+
+    return result
+
+
+def evaluate_readiness(body: str, labels: list[str]) -> ReadinessResult:
+    """Return the readiness result for an issue body + label set.
+
+    An issue is only a candidate when it carries the `bug` or `enhancement`
+    label. If it has neither, it is treated as not-ready-for-dev (the gate does
+    not apply a label it cannot validate).
+    """
+    label_set = {label.lower() for label in labels}
+    sections = extract_sections(body or "")
+
+    if BUG_LABEL in label_set:
+        return check_bug(sections)
+    if ENHANCEMENT_LABEL in label_set:
+        return check_enhancement(sections)
+
+    return ReadinessResult(
+        ready=False,
+        reasons=[
+            "The issue has neither the `bug` nor `enhancement` label, so its "
+            "readiness criteria cannot be evaluated. Add the appropriate label."
+        ],
+    )
+
+
+def body_and_labels_from_event(event_path: Path) -> tuple[str, list[str]]:
+    payload = json.loads(event_path.read_text())
+    issue = payload.get("issue") or payload.get("pull_request")
+    if not isinstance(issue, dict):
+        raise ValueError("GitHub event payload does not contain an issue object")
+    body = issue.get("body")
+    body = body if isinstance(body, str) else ""
+    labels = [
+        label["name"] for label in issue.get("labels", []) if isinstance(label, dict)
+    ]
+    return body, labels
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Evaluate whether an issue meets the ready-for-dev criteria."
+    )
+    parser.add_argument(
+        "--body-file", type=Path, help="Read the issue body from a file."
+    )
+    parser.add_argument(
+        "--labels",
+        help="Comma-separated issue labels (e.g. 'bug,skills').",
+        default="",
+    )
+    parser.add_argument(
+        "--event-path",
+        type=Path,
+        default=Path(os.environ["GITHUB_EVENT_PATH"])
+        if "GITHUB_EVENT_PATH" in os.environ
+        else None,
+        help="Read body and labels from a GitHub event payload.",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Emit a JSON result instead of human-readable text.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+
+    if args.body_file is not None:
+        body = args.body_file.read_text()
+        labels = [label.strip() for label in args.labels.split(",") if label.strip()]
+    elif args.event_path is not None:
+        body, labels = body_and_labels_from_event(args.event_path)
+    else:
+        raise SystemExit("Pass --body-file or set GITHUB_EVENT_PATH.")
+
+    result = evaluate_readiness(body, labels)
+
+    if args.json:
+        print(json.dumps({"ready": result.ready, "reasons": result.reasons}))
+        # In --json mode the exit code is not meaningful: the result is consumed
+        # via the printed JSON, and the workflow must run to completion for both
+        # ready and not-ready issues (label add/remove, feedback comment).
+        return 0
+
+    if result.ready:
+        print("Issue meets ready-for-dev criteria.")
+    else:
+        print("Issue does not meet ready-for-dev criteria:")
+        for reason in result.reasons:
+            print(f"  - {reason}")
+
+    return 0 if result.ready else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.github/scripts/check_pr_description.py

@@ -0,0 +1,226 @@
+"""Validate a pull request description against the repository PR template.
+
+Two gates:
+
+1. Template sections: the `## Why`, `## Summary`, and `## How to Test`
+   sections from `.github/pull_request_template.md` must be present and
+   filled in.
+
+2. Linked-issue readiness: every issue linked via a closing keyword
+   (`Fixes #123`, `Closes #123`, `Resolves #123`) or referenced in the
+   `## Issue Number` section must exist and, unless it predates the
+   `ready-for-dev` rollout, carry the `ready-for-dev` label. This blocks
+   PRs until their linked issue meets the readiness criteria.
+
+Local usage:
+
+    python .github/scripts/check_pr_description.py --body-file /tmp/pr.md
+    GITHUB_TOKEN=... python .github/scripts/check_pr_description.py \
+        --event-path "$GITHUB_EVENT_PATH"
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+
+# These are the only PR-template sections that must remain and contain content.
+REQUIRED_TEMPLATE_FIELDS: tuple[str, ...] = ("Why", "Summary", "How to Test")
+
+HTML_COMMENT_RE = re.compile(r"<!--[\s\S]*?-->")
+HEADING_RE = re.compile(r"(?m)^##\s+(.+?)\s*$")
+ISSUE_REF_RE = re.compile(r"(?i)\b(?:fix|clos|resolv)(?:e?(?:s|d)?|ing)?\s+#(\d+)")
+BARE_ISSUE_REF_RE = re.compile(r"(?<!\w)#(\d+)")
+READY_FOR_DEV_LABEL = "ready-for-dev"
+# Issues created before the `ready-for-dev` rollout are grandfathered: the
+# issue-readiness workflow only labels issues on `issues` events, so long-open
+# issues were never evaluated. Requiring the label retroactively would block
+# existing PRs linked to those issues. The cutoff is the UTC day AFTER the
+# rollout/deployment day (2026-08-24), so every issue predating deployment -
+# including ones opened earlier that same day, before the workflow existed -
+# is exempt. Issues created on or after 2026-08-25 must carry the label.
+READY_FOR_DEV_ROLLOUT_ISO = "2026-08-25"
+
+
+def visible_text(text: str) -> str:
+    """Return PR body content that should count as author-provided text."""
+    lines = []
+    for line in HTML_COMMENT_RE.sub("", text).splitlines():
+        stripped = line.strip()
+        if stripped and stripped != "-":
+            lines.append(stripped)
+    return "\n".join(lines).strip()
+
+
+def extract_sections(body: str) -> dict[str, str]:
+    matches = list(HEADING_RE.finditer(body))
+    sections: dict[str, str] = {}
+    for index, match in enumerate(matches):
+        start = match.end()
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(body)
+        sections[match.group(1).strip()] = body[start:end]
+    return sections
+
+
+def extract_linked_issue_numbers(body: str) -> list[int]:
+    numbers: list[int] = []
+    seen: set[int] = set()
+    for match in ISSUE_REF_RE.finditer(body):
+        number = int(match.group(1))
+        if number not in seen:
+            numbers.append(number)
+            seen.add(number)
+
+    sections = extract_sections(body)
+    issue_section = sections.get("Issue Number", "")
+    for match in BARE_ISSUE_REF_RE.finditer(issue_section):
+        number = int(match.group(1))
+        if number not in seen:
+            numbers.append(number)
+            seen.add(number)
+    return numbers
+
+
+def fetch_issue_details(
+    repo: str, issue_number: int, token: str
+) -> tuple[list[str], str]:
+    """Return an issue's (labels, created_at) from the GitHub API."""
+    request = urllib.request.Request(
+        f"https://api.github.com/repos/{repo}/issues/{issue_number}",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+        },
+    )
+    with urllib.request.urlopen(request, timeout=10) as response:  # noqa: S310 - trusted HTTPS API
+        issue = json.loads(response.read().decode())
+    labels = [
+        label["name"] for label in issue.get("labels", []) if isinstance(label, dict)
+    ]
+    created_at = issue.get("created_at", "")
+    return labels, created_at
+
+
+def validate_linked_issue_ready(
+    body: str, repo: str | None = None, token: str | None = None
+) -> list[str]:
+    numbers = extract_linked_issue_numbers(body)
+    if not numbers:
+        return [
+            "Link an issue in the `## Issue Number` section (e.g. `Fixes #123`). "
+            "Newly opened issues must carry the `ready-for-dev` label."
+        ]
+    if not repo or not token:
+        return []
+
+    checked: list[int] = []
+    not_ready_new: list[int] = []
+    for number in numbers:
+        try:
+            labels, created_at = fetch_issue_details(repo, number, token)
+        except urllib.error.HTTPError as exc:
+            if exc.code == 404:
+                continue
+            raise
+        checked.append(number)
+        if READY_FOR_DEV_LABEL in (label.lower() for label in labels):
+            continue
+        if created_at[:10] < READY_FOR_DEV_ROLLOUT_ISO:
+            # Predates the rollout; grandfathered to avoid retroactive blocking.
+            continue
+        not_ready_new.append(number)
+
+    if not checked:
+        refs = ", ".join(f"#{number}" for number in numbers)
+        return [f"Referenced issue(s) {refs} could not be found in this repository."]
+    if not_ready_new:
+        refs = ", ".join(f"#{number}" for number in not_ready_new)
+        return [
+            f"Linked issue(s) ({refs}) carry neither `ready-for-dev` nor a "
+            "pre-rollout creation date. Newly referenced issues must meet the "
+            "readiness criteria before a PR can be opened."
+        ]
+    return []
+
+
+def validate_pr_body(body: str) -> list[str]:
+    errors: list[str] = []
+
+    sections = extract_sections(body)
+    for section in REQUIRED_TEMPLATE_FIELDS:
+        if section not in sections:
+            errors.append(f"Keep the `## {section}` section from the PR template.")
+        elif not visible_text(sections[section]):
+            errors.append(f"Fill in the `## {section}` section of the PR template.")
+
+    return errors
+
+
+def body_from_event(event_path: Path) -> tuple[str, str | None]:
+    """Return the (pull request body, repository full name) from an event payload."""
+    payload = json.loads(event_path.read_text())
+    pull_request = payload.get("pull_request")
+    if not isinstance(pull_request, dict):
+        raise ValueError("GitHub event payload does not contain a pull_request object")
+    body = pull_request.get("body")
+    body = body if isinstance(body, str) else ""
+    repo = payload.get("repository", {}).get("full_name")
+    return body, repo if isinstance(repo, str) else None
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Validate pull request description readiness from --body-file "
+            "or a GitHub event payload."
+        )
+    )
+    parser.add_argument(
+        "--body-file", type=Path, help="Read a PR description body from a file."
+    )
+    parser.add_argument(
+        "--event-path",
+        type=Path,
+        default=Path(os.environ["GITHUB_EVENT_PATH"])
+        if "GITHUB_EVENT_PATH" in os.environ
+        else None,
+        help="Read the PR description body from a GitHub event payload.",
+    )
+    return parser.parse_args()
+
+
+def main() -> int:
+    args = parse_args()
+    if args.body_file is not None:
+        body = args.body_file.read_text()
+        repo = None
+    elif args.event_path is not None:
+        body, repo = body_from_event(args.event_path)
+    else:
+        raise SystemExit("Pass --body-file or set GITHUB_EVENT_PATH.")
+
+    errors = validate_pr_body(body)
+
+    token = os.environ.get("GITHUB_TOKEN")
+    errors.extend(validate_linked_issue_ready(body, repo, token))
+
+    for error in errors:
+        print(f"::error::{error}")
+
+    if errors:
+        print(f"PR description validation failed with {len(errors)} error(s).")
+        return 1
+
+    print("PR description validation passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())