@openhands/extensions 0.22.1 → 0.24.0

package/.github/scripts/check_issue_readiness.py

@@ -1,272 +0,0 @@
-"""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/post-readiness-comment.mjs

@@ -1,184 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Post (or update) a `ready-for-dev` readiness comment on an issue.
- *
- * Upserts by a hidden HTML marker so repeated runs update the same comment
- * instead of spamming duplicates. Uses the GITHUB_TOKEN available to the
- * workflow via the GH_TOKEN env var.
- *
- * Usage:
- *   node post-readiness-comment.mjs \
- *     --issue-number 123 \
- *     --repo OpenHands/extensions \
- *     --reasons-file /tmp/reasons.txt \
- *     --ready           # optional: post a "ready" message instead of "not ready"
- */
-
-import { readFileSync } from "node:fs";
-
-const MARKER = "<!-- issue-readiness-check -->";
-const API_ROOT = process.env.GITHUB_API_URL ?? "https://api.github.com";
-
-function parseArgs(argv) {
-  const args = {};
-  for (let i = 0; i < argv.length; i += 1) {
-    const arg = argv[i];
-    if (!arg.startsWith("--")) continue;
-    const [rawKey, inlineValue] = arg.slice(2).split("=", 2);
-    const key = rawKey.replaceAll("-", "_");
-    if (inlineValue !== undefined) {
-      args[key] = inlineValue;
-      continue;
-    }
-    const next = argv[i + 1];
-    if (next && !next.startsWith("--")) {
-      args[key] = next;
-      i += 1;
-    } else {
-      args[key] = "";
-    }
-  }
-  return args;
-}
-
-function requireValue(name, value) {
-  if (!value) throw new Error(`Missing required value: ${name}`);
-  return value;
-}
-
-async function listComments(repo, issueNumber, token) {
-  // Paginate through all comments so the marker is found even on issues
-  // with >100 comments.
-  const all = [];
-  let page = 1;
-  while (true) {
-    const url = `${API_ROOT}/repos/${repo}/issues/${issueNumber}/comments?per_page=100&page=${page}`;
-    const resp = await fetch(url, {
-      headers: {
-        Authorization: `Bearer ${token}`,
-        Accept: "application/vnd.github+json",
-        "X-GitHub-Api-Version": "2022-11-28",
-      },
-    });
-    if (!resp.ok) {
-      throw new Error(`Failed to list comments: ${resp.status} ${await resp.text()}`);
-    }
-    const batch = await resp.json();
-    all.push(...batch);
-    if (batch.length < 100) break;
-    page += 1;
-  }
-  return all;
-}
-
-async function createComment(repo, issueNumber, body, token) {
-  const url = `${API_ROOT}/repos/${repo}/issues/${issueNumber}/comments`;
-  const resp = await fetch(url, {
-    method: "POST",
-    headers: {
-      Authorization: `Bearer ${token}`,
-      Accept: "application/vnd.github+json",
-      "X-GitHub-Api-Version": "2022-11-28",
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify({ body }),
-  });
-  if (!resp.ok) {
-    throw new Error(`Failed to create comment: ${resp.status} ${await resp.text()}`);
-  }
-  return resp.json();
-}
-
-async function updateComment(repo, commentId, body, token) {
-  const url = `${API_ROOT}/repos/${repo}/issues/comments/${commentId}`;
-  const resp = await fetch(url, {
-    method: "PATCH",
-    headers: {
-      Authorization: `Bearer ${token}`,
-      Accept: "application/vnd.github+json",
-      "X-GitHub-Api-Version": "2022-11-28",
-      "Content-Type": "application/json",
-    },
-    body: JSON.stringify({ body }),
-  });
-  if (!resp.ok) {
-    throw new Error(`Failed to update comment: ${resp.status} ${await resp.text()}`);
-  }
-  return resp.json();
-}
-
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const issueNumber = requireValue("issue-number", args.issue_number);
-  const repo = requireValue("repo", args.repo);
-  const token = process.env.GH_TOKEN;
-  if (!token) throw new Error("GH_TOKEN env var is required");
-
-  const isReady = args.ready === "" || args.ready === "true";
-  const reasonsFile = args.reasons_file || args.reasons;
-  const reasons = reasonsFile
-    ? readFileSync(reasonsFile, "utf8")
-        .split("\n")
-        .map((line) => line.trim())
-        .filter(Boolean)
-    : [];
-
-  const reasonList = reasons.length
-    ? reasons.map((r) => `- ${r}`).join("\n")
-    : "- The issue does not meet the ready-for-dev criteria.";
-
-  const body = isReady
-    ? [
-        MARKER,
-        "### \u2705 `ready-for-dev` label applied",
-        "",
-        "This issue meets the readiness criteria and is ready for contribution.",
-        "A contributor can now open a PR that links this issue (`Fixes #<number>`).",
-        "",
-        "_This is an automated readiness check posted by a workflow._",
-      ].join("\n")
-    : [
-        MARKER,
-        "### \u26a0\ufe0f Not yet `ready-for-dev`",
-        "",
-        "This issue does not yet meet the readiness criteria, so the",
-        "`ready-for-dev` label has not been applied (or has been removed).",
-        "The criteria are type-specific:",
-        "",
-        "**Bug reports** (`bug` label):",
-        "- The `### Actual Behavior` section must describe reproducible steps",
-        "  and include a command such as `uv run pytest`, `pytest`, `python`,",
-        "  `pip`, `npm run`, or `node`.",
-        "- An `### Acceptance Criteria` section with at least one checklist item (`- [ ] ...`).",
-        "",
-        "**Enhancements** (`enhancement` label):",
-        "- A `### Desired Behavior` section.",
-        "- An `### Acceptance Criteria` section with at least one checklist item.",
-        "",
-        "What is missing:",
-        "",
-        reasonList,
-        "",
-        "Edit the issue to address the gaps and the `ready-for-dev` label will be",
-        "applied automatically.",
-        "",
-        "_This is an automated readiness check posted by a workflow._",
-      ].join("\n");
-
-  const comments = await listComments(repo, issueNumber, token);
-  const existing = comments.find((comment) => comment.body?.includes(MARKER));
-
-  if (existing) {
-    await updateComment(repo, existing.id, body, token);
-    console.log(`Updated readiness comment ${existing.id} on issue #${issueNumber}`);
-  } else {
-    const created = await createComment(repo, issueNumber, body, token);
-    console.log(`Created readiness comment ${created.id} on issue #${issueNumber}`);
-  }
-}
-
-main().catch((error) => {
-  console.error(error);
-  process.exit(1);
-});

package/tests/test_check_issue_readiness.py

@@ -1,135 +0,0 @@
-from __future__ import annotations
-
-import importlib.util
-import sys
-from pathlib import Path
-
-
-def _load_prod_module():
-    repo_root = Path(__file__).resolve().parents[1]
-    script_path = repo_root / ".github" / "scripts" / "check_issue_readiness.py"
-    name = "check_issue_readiness"
-    spec = importlib.util.spec_from_file_location(name, script_path)
-    assert spec and spec.loader
-    mod = importlib.util.module_from_spec(spec)
-    sys.modules[name] = mod
-    spec.loader.exec_module(mod)
-    return mod
-
-
-_prod = _load_prod_module()
-evaluate_readiness = _prod.evaluate_readiness
-extract_sections = _prod.extract_sections
-
-
-ENHANCEMENT_READY = """### Problem or Use Case
-
-The integration catalog lacks a Linear entry.
-
-### Desired Behavior
-
-`integrations/catalog/linear.json` describes the Linear MCP server so the
-catalog build picks it up.
-
-### Acceptance Criteria
-
-- [ ] `npm run build:integrations` succeeds with the new entry
-- [ ] `getIntegrationCatalogEntry("linear")` returns the Linear catalog model
-"""
-
-BUG_READY = """### Actual Behavior
-
-Running `uv run --group test pytest tests/` fails in
-`test_skills_catalog.py` with a KeyError when a skill is missing from the
-marketplace.
-
-### Acceptance Criteria
-
-- [ ] `uv run --group test pytest tests/` passes with a clear error message
-"""
-
-
-def test_extract_sections_splits_on_headings():
-    sections = extract_sections("### Alpha\n\ntext\n\n### Beta\n\nmore\n")
-    assert sections["alpha"] == "\ntext\n\n"
-    assert sections["beta"] == "\nmore\n"
-
-
-def test_enhancement_ready_passes():
-    result = evaluate_readiness(ENHANCEMENT_READY, ["enhancement"])
-    assert result.ready is True
-    assert result.reasons == []
-
-
-def test_enhancement_missing_acceptance_criteria_fails():
-    body = "### Desired Behavior\n\nSome desired change.\n"
-    result = evaluate_readiness(body, ["enhancement"])
-    assert result.ready is False
-    assert any("Acceptance Criteria" in r for r in result.reasons)
-
-
-def test_enhancement_missing_desired_behavior_fails():
-    body = ENHANCEMENT_READY.replace(
-        "### Desired Behavior\n\n"
-        "`integrations/catalog/linear.json` describes the Linear MCP server so the\n"
-        "catalog build picks it up.\n\n",
-        "",
-    )
-    result = evaluate_readiness(body, ["enhancement"])
-    assert result.ready is False
-    assert any("Desired Behavior" in r for r in result.reasons)
-
-
-def test_bug_ready_passes():
-    result = evaluate_readiness(BUG_READY, ["bug"])
-    assert result.ready is True
-    assert result.reasons == []
-
-
-def test_bug_missing_run_method_fails():
-    body = BUG_READY.replace(
-        "Running `uv run --group test pytest tests/` fails",
-        "Running the test suite fails",
-    )
-    result = evaluate_readiness(body, ["bug"])
-    assert result.ready is False
-    assert any("reproducible command" in r for r in result.reasons)
-
-
-def test_bug_npm_build_command_is_a_valid_run_method():
-    body = BUG_READY.replace(
-        "Running `uv run --group test pytest tests/` fails in\n"
-        "`test_skills_catalog.py` with a KeyError when a skill is missing from the\n"
-        "marketplace.",
-        "Running `npm run build:skills` fails with a schema error.",
-    )
-    result = evaluate_readiness(body, ["bug"])
-    assert result.ready is True
-    assert result.reasons == []
-
-
-def test_bug_acceptance_needs_checklist_item():
-    body = BUG_READY.replace(
-        "- [ ] `uv run --group test pytest tests/` passes with a clear error message",
-        "Make the test error message clearer",
-    )
-    result = evaluate_readiness(body, ["bug"])
-    assert result.ready is False
-    assert any("checklist item" in r for r in result.reasons)
-
-
-def test_no_response_field_counts_as_empty():
-    body = BUG_READY.replace(
-        "### Acceptance Criteria\n\n- [ ] `uv run --group test pytest tests/` "
-        "passes with a clear error message\n",
-        "### Acceptance Criteria\n\n_No response_\n",
-    )
-    result = evaluate_readiness(body, ["bug"])
-    assert result.ready is False
-    assert any("Acceptance Criteria" in r for r in result.reasons)
-
-
-def test_no_bug_or_enhancement_label_not_ready():
-    result = evaluate_readiness(ENHANCEMENT_READY, [])
-    assert result.ready is False
-    assert any("bug" in r and "enhancement" in r for r in result.reasons)