@openhands/extensions 0.0.1-alpha → 0.2.0

package/plugins/release-notes/scripts/prompt.py

@@ -0,0 +1,90 @@
+"""Prompt template for the release notes agent."""
+
+PROMPT = """Write official release notes for `{repo_name}` tag `{tag}`.
+
+Use the structured release data below as your primary source of truth. You may inspect the checked-out repository if it helps you judge significance or match release-note style, but do not ask follow-up questions.
+
+Your job is editorial, not mechanical:
+- decide which PRs are important enough to mention
+- group related PRs into a single bullet when they form one coherent feature or fix
+- for larger releases, aggressively compress the notes into a shorter set of higher-signal bullets instead of listing one bullet per PR
+- if a section would have more than 5 bullets, merge same-theme items until the section is scannable
+- omit trivial, repetitive, or low-signal changes from the final notes
+- prefer end-user impact over implementation detail
+- prioritize public APIs, user-visible capabilities, security fixes, supported integrations/models, and operational changes users directly invoke
+- treat toolkit-maintainer or contributor-facing changes as secondary unless they materially change how end users or client developers adopt, run, or integrate the project
+- changes that mostly affect CI, internal prompts, benchmarks, workflow inputs, refactors, contributor ergonomics, or toolkit implementation details should stay in the small/internal appendix unless they are unusually significant
+- use `### 📚 Documentation` only for notable docs/reference/policy updates that matter to users or client developers; public API additions still belong in `### ✨ New Features`
+- omit prompt wording, benchmark plumbing, workflow maintenance, and similar maintainer-only changes unless they materially alter observable user behavior
+- start with a short, conversational 1-2 sentence overview of the release before the categorized sections
+- if you add top-level highlight bullets, keep them to at most 3 and reserve them for the biggest user-facing changes
+- treat the suggested category as a hint, not a rule
+- when `include_internal` is false, omit internal-only work unless it is important for users
+- use imperative mood
+- keep each bullet to one line
+- every change bullet must end with explicit references for each included item
+- format PR references as `(#123) @username`; if you group multiple PRs, include each reference explicitly, for example `(#123) @alice, (#124) @bob`
+- if you mention a standalone commit instead of a PR, format it as `(abc1234) @username`
+- include every new contributor listed below in the `### 👥 New Contributors` section
+- for breaking changes, briefly note the migration path when the provided context makes it clear
+
+Return markdown only. Do not wrap the result in a code fence.
+
+Required structure:
+- `## [{tag}] - {date}`
+- a short conversational overview paragraph immediately after the title
+- optional top-level highlight bullets (maximum 3) before the categorized sections
+- `### ⚠️ Breaking Changes` when applicable
+- `### ✨ New Features` when applicable
+- `### 🐛 Bug Fixes` when applicable
+- `### 📚 Documentation` only when notable
+- `### 🏗️ Internal/Infrastructure` only when `include_internal` is true and the changes are worth mentioning
+- `### 👥 New Contributors` when there are any
+- `**Full Changelog**: {full_changelog_url}` at the end
+
+Release metadata:
+- Repository: {repo_name}
+- Current tag: {tag}
+- Previous tag: {previous_tag}
+- Release date: {date}
+- Commits in range: {commit_count}
+- Include internal section: {include_internal}
+- Output format: {output_format}
+
+Candidate changes:
+{change_candidates}
+
+New contributors:
+{new_contributors}
+
+Full changelog URL:
+{full_changelog_url}
+"""
+
+
+def format_prompt(
+    *,
+    repo_name: str,
+    tag: str,
+    previous_tag: str,
+    date: str,
+    commit_count: int,
+    include_internal: bool,
+    output_format: str,
+    full_changelog_url: str,
+    change_candidates: str,
+    new_contributors: str,
+) -> str:
+    """Format the release-notes prompt."""
+    return PROMPT.format(
+        repo_name=repo_name,
+        tag=tag,
+        previous_tag=previous_tag,
+        date=date,
+        commit_count=commit_count,
+        include_internal=str(include_internal).lower(),
+        output_format=output_format,
+        full_changelog_url=full_changelog_url,
+        change_candidates=change_candidates,
+        new_contributors=new_contributors,
+    )

package/plugins/release-notes/scripts/validate_release_notes.py

@@ -0,0 +1,328 @@
+#!/usr/bin/env python3
+"""Validate attribution coverage in generated release notes."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from dataclasses import dataclass
+
+from generate_release_notes import CATEGORIES, ReleaseNotes, generate_release_notes, get_env
+
+PR_REF_PATTERN = re.compile(r"#(\d+)\b")
+COMMIT_REF_PATTERN = re.compile(r"\(([0-9a-f]{7,40})\)")
+USER_HANDLE_PATTERN = re.compile(r"@([A-Za-z0-9][A-Za-z0-9_\-\[\]]*)")
+NEW_CONTRIBUTORS_HEADING = "### 👥 New Contributors"
+COVERAGE_HEADING = "### 🔎 Small Fixes/Internal Changes"
+REFERENCE_CATEGORY_ORDER = ["breaking", "features", "fixes", "docs", "internal", "other"]
+
+
+@dataclass
+class CoverageSummary:
+    """Summary of attribution coverage found in release notes."""
+
+    bullet_count: int
+    referenced_prs: list[int]
+    referenced_authors: list[str]
+    referenced_commits: list[str]
+    required_reference_count: int
+
+
+@dataclass
+class ValidationContext:
+    """Parsed validation context for a single release note run."""
+
+    reference_authors: dict[str, str]
+    reference_order: list[str]
+    change_section_headings: set[str]
+    expected_new_contributors: dict[str, int | None]
+
+
+class ReleaseNotesValidationError(ValueError):
+    """Raised when generated release notes violate attribution rules."""
+
+
+@dataclass
+class MentionScanResult:
+    """Collected ref/author coverage from markdown."""
+
+    covered_refs: set[str]
+    referenced_prs: set[int]
+    referenced_authors: set[str]
+    referenced_commits: set[str]
+    found_new_contributors: dict[str, int | None]
+    bullet_count: int
+    errors: list[str]
+
+
+def build_validation_context(
+    notes: ReleaseNotes, include_internal: bool = False
+) -> ValidationContext:
+    """Build the reference and section metadata used for validation."""
+    del include_internal  # Coverage should include every candidate the release may cite.
+
+    reference_authors: dict[str, str] = {}
+    reference_order: list[str] = []
+    expected_new_contributors = {
+        contributor.username: contributor.first_pr for contributor in notes.new_contributors
+    }
+    change_section_headings = {
+        f"### {CATEGORIES[category]['emoji']} {CATEGORIES[category]['title']}"
+        for category in CATEGORIES
+    }
+
+    for category in REFERENCE_CATEGORY_ORDER:
+        for change in notes.changes.get(category, []):
+            ref = f"#{change.pr_number}" if change.pr_number else change.sha[:7].lower()
+            if ref in reference_authors:
+                continue
+            reference_authors[ref] = change.author
+            reference_order.append(ref)
+
+    return ValidationContext(
+        reference_authors=reference_authors,
+        reference_order=reference_order,
+        change_section_headings=change_section_headings,
+        expected_new_contributors=expected_new_contributors,
+    )
+
+
+def _extract_explicit_references(text: str) -> list[str]:
+    refs = [f"#{match}" for match in PR_REF_PATTERN.findall(text)]
+    refs.extend(match.lower() for match in COMMIT_REF_PATTERN.findall(text))
+
+    deduped: list[str] = []
+    for ref in refs:
+        if ref not in deduped:
+            deduped.append(ref)
+    return deduped
+
+
+def _scan_reference_mentions(markdown: str, context: ValidationContext) -> MentionScanResult:
+    current_heading = ""
+    covered_refs: set[str] = set()
+    referenced_prs: set[int] = set()
+    referenced_authors: set[str] = set()
+    referenced_commits: set[str] = set()
+    found_new_contributors: dict[str, int | None] = {}
+    errors: list[str] = []
+    bullet_count = 0
+
+    for raw_line in markdown.splitlines():
+        line = raw_line.strip()
+        if line.startswith("### "):
+            current_heading = line
+            continue
+
+        if not line.startswith("- "):
+            continue
+
+        refs = _extract_explicit_references(line)
+        is_change_bullet = current_heading in context.change_section_headings
+        is_new_contributor_bullet = current_heading == NEW_CONTRIBUTORS_HEADING
+
+        if is_change_bullet:
+            bullet_count += 1
+            if not refs:
+                errors.append(f"Bullet missing explicit PR/commit references: {line}")
+                continue
+
+        if is_new_contributor_bullet:
+            usernames = USER_HANDLE_PATTERN.findall(line)
+            if len(usernames) != 1:
+                errors.append(
+                    "New contributor bullet must mention exactly one contributor handle: "
+                    f"{line}"
+                )
+            else:
+                username = usernames[0]
+                expected_first_pr = context.expected_new_contributors.get(username)
+                if username not in context.expected_new_contributors:
+                    errors.append(f"Unknown new contributor @{username}: {line}")
+                elif username in found_new_contributors:
+                    errors.append(f"Duplicate new contributor @{username}: {line}")
+                else:
+                    found_new_contributors[username] = expected_first_pr
+                    if expected_first_pr is not None and f"#{expected_first_pr}" not in refs:
+                        errors.append(
+                            f"New contributor @{username} must reference #{expected_first_pr}: {line}"
+                        )
+
+        for ref in refs:
+            author = context.reference_authors.get(ref)
+            if not author:
+                errors.append(f"Bullet references unknown PR/commit {ref}: {line}")
+                continue
+            if f"@{author}" not in line:
+                errors.append(f"Bullet mentioning {ref} is missing @{author}: {line}")
+                continue
+
+            covered_refs.add(ref)
+            referenced_authors.add(author)
+            if ref.startswith("#"):
+                referenced_prs.add(int(ref[1:]))
+            else:
+                referenced_commits.add(ref)
+
+        if is_new_contributor_bullet and not refs and context.expected_new_contributors:
+            errors.append(f"New contributor bullet missing PR reference: {line}")
+
+    return MentionScanResult(
+        covered_refs=covered_refs,
+        referenced_prs=referenced_prs,
+        referenced_authors=referenced_authors,
+        referenced_commits=referenced_commits,
+        found_new_contributors=found_new_contributors,
+        bullet_count=bullet_count,
+        errors=errors,
+    )
+
+
+def missing_references(
+    markdown: str,
+    notes: ReleaseNotes,
+    include_internal: bool = False,
+) -> list[str]:
+    """Return required refs that are not yet covered in the markdown."""
+    context = build_validation_context(notes, include_internal=include_internal)
+    scan = _scan_reference_mentions(markdown, context)
+    return [ref for ref in context.reference_order if ref not in scan.covered_refs]
+
+
+def _format_reference_token(ref: str) -> str:
+    return ref if ref.startswith("#") else f"({ref})"
+
+
+def append_reference_coverage_appendix(
+    markdown: str,
+    notes: ReleaseNotes,
+    include_internal: bool = False,
+) -> str:
+    """Append a compact appendix covering any PRs/authors omitted by the agent."""
+    context = build_validation_context(notes, include_internal=include_internal)
+    scan = _scan_reference_mentions(markdown, context)
+    missing_refs = [ref for ref in context.reference_order if ref not in scan.covered_refs]
+    if not missing_refs:
+        return markdown
+
+    refs_by_author: dict[str, list[str]] = {}
+    author_order: list[str] = []
+    for ref in missing_refs:
+        author = context.reference_authors[ref]
+        if author not in refs_by_author:
+            refs_by_author[author] = []
+            author_order.append(author)
+        refs_by_author[author].append(_format_reference_token(ref))
+
+    appendix_lines = [COVERAGE_HEADING]
+    for author in author_order:
+        appendix_lines.append(f"- @{author}: {', '.join(refs_by_author[author])}")
+
+    base_lines = markdown.rstrip().splitlines()
+    for index, line in enumerate(base_lines):
+        if line.startswith("**Full Changelog**:"):
+            combined = base_lines[:index] + [""] + appendix_lines + [""] + base_lines[index:]
+            return "\n".join(combined) + "\n"
+
+    return "\n".join(base_lines + [""] + appendix_lines + [""])
+
+
+def validate_release_notes_markdown(
+    markdown: str,
+    notes: ReleaseNotes,
+    include_internal: bool = False,
+) -> CoverageSummary:
+    """Validate that every included change lists explicit refs and authors."""
+    context = build_validation_context(notes, include_internal=include_internal)
+    scan = _scan_reference_mentions(markdown, context)
+    missing_refs = [ref for ref in context.reference_order if ref not in scan.covered_refs]
+    missing_new_contributors = [
+        username
+        for username in context.expected_new_contributors
+        if username not in scan.found_new_contributors
+    ]
+
+    errors = list(scan.errors)
+    if missing_refs:
+        errors.append(
+            "Release notes are missing PR/commit coverage for: "
+            + ", ".join(missing_refs)
+        )
+    if missing_new_contributors:
+        errors.append(
+            "Release notes are missing new contributor coverage for: "
+            + ", ".join(f"@{username}" for username in missing_new_contributors)
+        )
+
+    if errors:
+        raise ReleaseNotesValidationError("\n".join(errors))
+
+    return CoverageSummary(
+        bullet_count=scan.bullet_count,
+        referenced_prs=sorted(scan.referenced_prs),
+        referenced_authors=sorted(scan.referenced_authors),
+        referenced_commits=sorted(scan.referenced_commits),
+        required_reference_count=len(context.reference_order),
+    )
+
+
+def format_coverage_summary(summary: CoverageSummary) -> str:
+    """Render a compact multi-line validation summary for logs and evidence."""
+    prs = ", ".join(f"#{pr}" for pr in summary.referenced_prs) or "none"
+    authors = ", ".join(f"@{author}" for author in summary.referenced_authors) or "none"
+    commits = ", ".join(summary.referenced_commits) or "none"
+    return "\n".join(
+        [
+            "Release notes attribution coverage validated.",
+            f"- Change bullets checked: {summary.bullet_count}",
+            f"- Covered references: {len(summary.referenced_prs) + len(summary.referenced_commits)}/{summary.required_reference_count}",
+            f"- PRs referenced: {prs}",
+            f"- Authors referenced: {authors}",
+            f"- Standalone commits referenced: {commits}",
+        ]
+    )
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse CLI arguments."""
+    parser = argparse.ArgumentParser(
+        description="Validate PR and author attribution in generated release notes."
+    )
+    parser.add_argument(
+        "--markdown-file",
+        default="release_notes.md",
+        help="Path to the generated release notes markdown file.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    """Validate generated release notes using the same GitHub metadata inputs."""
+    args = parse_args()
+    token = get_env("GITHUB_TOKEN", required=True)
+    tag = get_env("TAG", required=True)
+    previous_tag = get_env("PREVIOUS_TAG") or None
+    include_internal = get_env("INCLUDE_INTERNAL", "false").lower() == "true"
+    repo_name = get_env("REPO_NAME", required=True)
+
+    notes = generate_release_notes(
+        tag=tag,
+        previous_tag=previous_tag,
+        repo_name=repo_name,
+        token=token,
+        include_internal=include_internal,
+    )
+
+    with open(args.markdown_file) as file:
+        markdown = file.read()
+
+    summary = validate_release_notes_markdown(
+        markdown,
+        notes,
+        include_internal=include_internal,
+    )
+    print(format_coverage_summary(summary))
+
+
+if __name__ == "__main__":
+    main()

package/plugins/release-notes/workflows/release-notes.yml

@@ -0,0 +1,76 @@
+---
+name: Generate Release Notes
+
+on:
+    # Trigger on release tags matching semver pattern
+    push:
+        tags:
+            - 'v[0-9]+.[0-9]+.[0-9]+*'
+
+    # Allow manual triggering with tag input
+    workflow_dispatch:
+        inputs:
+            tag:
+                description: 'The release tag to generate notes for'
+                required: true
+                type: string
+            previous-tag:
+                description: 'Override automatic detection of previous release tag'
+                required: false
+                type: string
+            include-internal:
+                description: 'Include internal/infrastructure changes'
+                required: false
+                type: boolean
+                default: false
+
+permissions:
+    contents: write
+
+jobs:
+    generate-release-notes:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0  # Full history for tag comparison
+
+            - name: Determine tag
+              id: get-tag
+              run: |
+                  if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+                    echo "tag=${{ github.event.inputs.tag }}" >> $GITHUB_OUTPUT
+                  else
+                    echo "tag=${{ github.ref_name }}" >> $GITHUB_OUTPUT
+                  fi
+
+            - name: Generate Release Notes
+              id: release-notes
+              uses: OpenHands/extensions/plugins/release-notes@main
+              with:
+                  tag: ${{ steps.get-tag.outputs.tag }}
+                  previous-tag: ${{ github.event.inputs.previous-tag || '' }}
+                  include-internal: ${{ github.event.inputs.include-internal || 'false' }}
+                  output-format: release
+                  llm-api-key: ${{ secrets.LLM_API_KEY }}
+                  github-token: ${{ secrets.GITHUB_TOKEN }}
+
+            - name: Display generated notes
+              run: |
+                  echo "## Release Notes for ${{ steps.get-tag.outputs.tag }}"
+                  echo ""
+                  echo "Previous tag: ${{ steps.release-notes.outputs.previous-tag }}"
+                  echo "Commits: ${{ steps.release-notes.outputs.commit-count }}"
+                  echo "Contributors: ${{ steps.release-notes.outputs.contributor-count }}"
+                  echo "New contributors: ${{ steps.release-notes.outputs.new-contributor-count }}"
+                  echo ""
+                  echo "---"
+                  cat release_notes.md
+
+            - name: Upload release notes artifact
+              uses: actions/upload-artifact@v4
+              with:
+                  name: release-notes-${{ steps.get-tag.outputs.tag }}
+                  path: release_notes.md
+                  retention-days: 30

package/plugins/vulnerability-remediation/.plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "vulnerability-remediation",
+  "version": "1.0.0",
+  "description": "Automated security vulnerability scanning and AI-powered remediation. Scans repositories, skips when no issues found, and creates PRs with fixes.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "security",
+    "vulnerability",
+    "remediation",
+    "scanning",
+    "automation"
+  ]
+}