@openhands/extensions 0.0.1-alpha → 0.2.0

package/tests/test_sdk_loading.py

@@ -0,0 +1,150 @@
+"""Test that marketplaces, skills, and plugins can be loaded by the SDK."""
+
+from pathlib import Path
+
+import pytest
+from openhands.sdk.skills import Skill
+from openhands.sdk.marketplace import Marketplace, MarketplacePluginEntry
+
+
+def get_repo_root():
+    """Get the path to the repository root."""
+    return Path(__file__).parent.parent
+
+
+def get_all_skill_directories():
+    """Get all skill directory names that have a SKILL.md file."""
+    skills_dir = get_repo_root() / "skills"
+    return [
+        d for d in skills_dir.iterdir()
+        if d.is_dir() and not d.name.startswith('.') and (d / "SKILL.md").exists()
+    ]
+
+
+class TestDefaultMarketplace:
+    """Test that the default marketplace can be loaded by the SDK."""
+
+    def test_marketplace_loads_with_sdk(self):
+        """Verify the default marketplace can be loaded using SDK's Marketplace model."""
+        marketplace_path = get_repo_root() / "marketplaces" / "openhands-extensions.json"
+        
+        # Load using SDK's pydantic model
+        import json
+        with open(marketplace_path) as f:
+            data = json.load(f)
+        
+        marketplace = Marketplace.model_validate({**data, "path": str(get_repo_root())})
+        
+        assert marketplace.name == "openhands-extensions"
+        assert marketplace.owner is not None
+        assert marketplace.owner.name == "OpenHands"
+        assert len(marketplace.plugins) > 0
+
+    def test_all_plugin_entries_valid(self):
+        """Verify all plugin entries can be validated as MarketplacePluginEntry."""
+        marketplace_path = get_repo_root() / "marketplaces" / "openhands-extensions.json"
+        
+        import json
+        with open(marketplace_path) as f:
+            data = json.load(f)
+        
+        errors = []
+        for plugin_data in data.get("plugins", []):
+            try:
+                entry = MarketplacePluginEntry.model_validate(plugin_data)
+                assert entry.name, f"Plugin missing name"
+                assert entry.source, f"Plugin {entry.name} missing source"
+                assert entry.description, f"Plugin {entry.name} missing description"
+            except Exception as e:
+                errors.append(f"{plugin_data.get('name', 'unknown')}: {e}")
+        
+        assert len(errors) == 0, f"Plugin validation errors:\n" + "\n".join(errors)
+
+    def test_marketplace_source_paths_exist(self):
+        """Verify all source paths in the marketplace resolve to real directories."""
+        import json
+
+        marketplace_path = get_repo_root() / "marketplaces" / "openhands-extensions.json"
+        with open(marketplace_path) as f:
+            data = json.load(f)
+
+        root = get_repo_root()
+        missing = []
+        for entry in data["plugins"]:
+            src = entry["source"]
+            resolved = root / src
+            if not resolved.exists():
+                missing.append(f"{entry['name']}: {src} -> {resolved}")
+        assert len(missing) == 0, (
+            f"Source paths that don't exist on disk:\n" + "\n".join(missing)
+        )
+
+    def test_marketplace_includes_all_skills(self):
+        """Verify every skill directory is referenced in at least one marketplace."""
+        import json
+
+        marketplaces_dir = get_repo_root() / "marketplaces"
+        marketplace_files = sorted(marketplaces_dir.glob("*.json"))
+        assert len(marketplace_files) > 0, "No marketplace JSON files found"
+
+        # Collect sources across all marketplaces
+        all_sources = set()
+        for mp_path in marketplace_files:
+            with open(mp_path) as f:
+                data = json.load(f)
+            marketplace = Marketplace.model_validate({**data, "path": str(get_repo_root())})
+            for plugin in marketplace.plugins:
+                source = plugin.source if isinstance(plugin.source, str) else ""
+                # Normalize: strip leading "./" and resolve parent refs to get the leaf name
+                name = Path(source).name
+                all_sources.add(name)
+
+        # Get all skill directories
+        skill_dirs = {d.name for d in get_all_skill_directories()}
+
+        missing = skill_dirs - all_sources
+        assert len(missing) == 0, f"Skills not in any marketplace: {sorted(missing)}"
+
+
+class TestSkillsLoadWithSDK:
+    """Test that all skills can be loaded by the SDK."""
+
+    def test_all_skills_load_with_sdk(self):
+        """Verify all SKILL.md files can be loaded using SDK's Skill.load()."""
+        skill_dirs = get_all_skill_directories()
+        
+        errors = []
+        for skill_dir in skill_dirs:
+            skill_path = skill_dir / "SKILL.md"
+            try:
+                skill = Skill.load(skill_path, skill_base_dir=skill_dir)
+                assert skill.name, f"Skill {skill_dir.name} has no name"
+                assert skill.content, f"Skill {skill_dir.name} has no content"
+            except Exception as e:
+                errors.append(f"{skill_dir.name}: {e}")
+        
+        assert len(errors) == 0, (
+            f"Failed to load {len(errors)} skills:\n" + "\n".join(errors)
+        )
+
+    def test_skills_have_valid_metadata(self):
+        """Verify all skills have valid metadata (name, description)."""
+        skill_dirs = get_all_skill_directories()
+        
+        missing_metadata = []
+        for skill_dir in skill_dirs:
+            skill_path = skill_dir / "SKILL.md"
+            try:
+                skill = Skill.load(skill_path, skill_base_dir=skill_dir)
+                if not skill.description:
+                    missing_metadata.append(f"{skill_dir.name}: missing description")
+            except Exception:
+                pass  # Already caught in test_all_skills_load_with_sdk
+        
+        assert len(missing_metadata) == 0, (
+            f"Skills with missing metadata:\n" + "\n".join(missing_metadata)
+        )
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])

package/tests/test_skill_plugin_loading.py

@@ -0,0 +1,149 @@
+"""Test that skills listed in marketplaces can be loaded as Codex/Claude plugins.
+
+Every marketplace entry that references a ``skills/`` directory needs a
+``.plugin/plugin.json`` manifest and vendor symlinks (``.codex-plugin``,
+``.claude-plugin``) so that Codex and Claude Code can discover and load them.
+
+Regression test for: https://github.com/OpenHands/extensions/issues/201
+"""
+
+import json
+from pathlib import Path
+
+import pytest
+
+
+REPO_ROOT = Path(__file__).parent.parent
+SKILLS_DIR = REPO_ROOT / "skills"
+PLUGINS_DIR = REPO_ROOT / "plugins"
+MARKETPLACES_DIR = REPO_ROOT / "marketplaces"
+
+REQUIRED_MANIFEST_FIELDS = ["name", "description", "author", "version"]
+VENDOR_SYMLINKS = [".claude-plugin", ".codex-plugin"]
+
+
+def _all_dirs_with_plugin_manifest():
+    """Yield directories (plugins/ and skills/) that have .plugin/plugin.json."""
+    for base in [PLUGINS_DIR, SKILLS_DIR]:
+        if not base.is_dir():
+            continue
+        for entry_dir in sorted(base.iterdir()):
+            if not entry_dir.is_dir() or entry_dir.name.startswith("."):
+                continue
+            manifest = entry_dir / ".plugin" / "plugin.json"
+            if manifest.exists():
+                yield entry_dir
+
+
+def _marketplace_skill_entries():
+    """Yield (skill_name, source_path) for every marketplace entry under skills/."""
+    for mp_file in sorted(MARKETPLACES_DIR.glob("*.json")):
+        with open(mp_file) as f:
+            data = json.load(f)
+        for p in data.get("plugins", []):
+            src = p["source"]
+            if src.startswith("./skills/"):
+                yield p["name"], REPO_ROOT / src.lstrip("./")
+
+
+class TestAllMarketplaceSkillsHaveManifests:
+    """Every skill listed in a marketplace must have a plugin manifest for Codex."""
+
+    def test_all_marketplace_skills_have_plugin_json(self):
+        """Every marketplace skill entry must have .plugin/plugin.json."""
+        missing = []
+        for name, path in _marketplace_skill_entries():
+            manifest = path / ".plugin" / "plugin.json"
+            if not manifest.exists():
+                missing.append(name)
+        assert not missing, (
+            f"Skills missing .plugin/plugin.json (Codex can't load them): "
+            f"{', '.join(missing)}"
+        )
+
+    def test_all_marketplace_skills_have_vendor_symlinks(self):
+        """Every marketplace skill with a manifest must have vendor symlinks."""
+        problems = []
+        for name, path in _marketplace_skill_entries():
+            if not (path / ".plugin" / "plugin.json").exists():
+                continue
+            for vendor in VENDOR_SYMLINKS:
+                link = path / vendor
+                if not link.is_symlink():
+                    problems.append(f"{name}/{vendor}")
+        assert not problems, (
+            f"Missing vendor symlinks: {', '.join(problems)}"
+        )
+
+    def test_all_manifests_have_required_fields(self):
+        """Every skill manifest must have name, description, author, version."""
+        problems = []
+        for name, path in _marketplace_skill_entries():
+            manifest = path / ".plugin" / "plugin.json"
+            if not manifest.exists():
+                continue
+            data = json.loads(manifest.read_text())
+            for field in REQUIRED_MANIFEST_FIELDS:
+                if field not in data:
+                    problems.append(f"{name}: missing '{field}'")
+            author = data.get("author")
+            if not isinstance(author, dict):
+                problems.append(f"{name}: 'author' must be an object")
+            elif "name" not in author:
+                problems.append(f"{name}: author missing 'name'")
+        assert not problems, (
+            f"Manifest validation errors:\n" + "\n".join(problems)
+        )
+
+    def test_manifest_name_matches_directory(self):
+        """The 'name' in plugin.json must match the directory name."""
+        problems = []
+        for name, path in _marketplace_skill_entries():
+            manifest = path / ".plugin" / "plugin.json"
+            if not manifest.exists():
+                continue
+            data = json.loads(manifest.read_text())
+            if data.get("name") != path.name:
+                problems.append(f"{name}: manifest name '{data.get('name')}' != dir '{path.name}'")
+        assert not problems, (
+            f"Name mismatches:\n" + "\n".join(problems)
+        )
+
+
+class TestIteratePluginLoading:
+    """Verify the iterate skill can be loaded as a plugin (issue #201)."""
+
+    def test_iterate_loads_as_sdk_plugin(self):
+        """The iterate skill must load via Plugin.load() without error."""
+        from openhands.sdk.plugin.plugin import Plugin
+
+        plugin = Plugin.load(SKILLS_DIR / "iterate")
+        assert plugin.name == "iterate"
+        assert plugin.version == "1.0.0"
+        assert len(plugin.commands) > 0
+        command_names = {c.name for c in plugin.commands}
+        assert "iterate" in command_names
+        assert "babysit" in command_names
+        assert "verify" in command_names
+
+
+class TestVendorSymlinksForManifests:
+    """Every directory with .plugin/ must have vendor symlinks."""
+
+    @pytest.fixture(
+        params=list(_all_dirs_with_plugin_manifest()),
+        ids=lambda d: f"{d.parent.name}/{d.name}",
+    )
+    def dir_with_manifest(self, request):
+        return request.param
+
+    def test_has_vendor_symlinks(self, dir_with_manifest):
+        """Directories with .plugin/ must have .claude-plugin and .codex-plugin symlinks."""
+        for vendor in VENDOR_SYMLINKS:
+            link = dir_with_manifest / vendor
+            assert link.is_symlink(), (
+                f"{link.relative_to(REPO_ROOT)} must be a symlink to .plugin"
+            )
+            assert link.resolve() == (dir_with_manifest / ".plugin").resolve(), (
+                f"{link.relative_to(REPO_ROOT)} must point to .plugin"
+            )

package/tests/test_skills_have_readme.py

@@ -0,0 +1,66 @@
+"""Test that all skills have a README.md file in their directory."""
+
+import os
+from pathlib import Path
+
+
+def get_skills_directory():
+    """Get the path to the skills directory."""
+    # Get the directory containing this test file
+    test_dir = Path(__file__).parent
+    # Go up one level to the repo root, then into skills/
+    return test_dir.parent / "skills"
+
+
+def test_all_skills_have_readme():
+    """Verify that every skill directory contains a README.md file."""
+    skills_dir = get_skills_directory()
+    
+    # Get all subdirectories in the skills directory (excluding files)
+    skill_dirs = [
+        d for d in skills_dir.iterdir()
+        if d.is_dir() and not d.name.startswith('.')
+    ]
+    
+    assert len(skill_dirs) > 0, "No skill directories found"
+    
+    missing_readmes = []
+    for skill_dir in skill_dirs:
+        readme_path = skill_dir / "README.md"
+        if not readme_path.exists():
+            missing_readmes.append(skill_dir.name)
+    
+    assert len(missing_readmes) == 0, (
+        f"The following skills are missing README.md: {', '.join(missing_readmes)}"
+    )
+
+
+def test_readme_is_readable():
+    """Verify that README.md files are readable (symlinks resolve correctly)."""
+    skills_dir = get_skills_directory()
+    
+    skill_dirs = [
+        d for d in skills_dir.iterdir()
+        if d.is_dir() and not d.name.startswith('.')
+    ]
+    
+    unreadable_readmes = []
+    for skill_dir in skill_dirs:
+        readme_path = skill_dir / "README.md"
+        if readme_path.exists():
+            try:
+                content = readme_path.read_text()
+                if len(content) == 0:
+                    unreadable_readmes.append(f"{skill_dir.name} (empty)")
+            except Exception as e:
+                unreadable_readmes.append(f"{skill_dir.name} ({e})")
+    
+    assert len(unreadable_readmes) == 0, (
+        f"The following README.md files are unreadable: {', '.join(unreadable_readmes)}"
+    )
+
+
+if __name__ == "__main__":
+    test_all_skills_have_readme()
+    test_readme_is_readable()
+    print("All tests passed!")

package/tests/test_sync_extensions.py

@@ -0,0 +1,292 @@
+"""Tests for scripts/sync_extensions.py core functions."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "scripts"))
+from sync_extensions import (
+    CMD_MARKER,
+    CommandSpec,
+    REPO_ROOT,
+    _entry_type,
+    build_command_content,
+    collect_needed_commands,
+    generate_catalog,
+    load_marketplaces,
+    parse_frontmatter,
+    slash_triggers,
+    sync_commands,
+)
+
+
+# ── parse_frontmatter ────────────────────────────────────────────────
+
+class TestParseFrontmatter:
+    def test_basic(self):
+        text = (
+            "---\n"
+            "name: test-skill\n"
+            "description: A test skill\n"
+            "triggers:\n"
+            "  - /test\n"
+            "---\n"
+            "Body"
+        )
+        meta = parse_frontmatter(text)
+        assert meta["name"] == "test-skill"
+        assert meta["description"] == "A test skill"
+        assert meta["triggers"] == ["/test"]
+
+    def test_no_frontmatter(self):
+        assert parse_frontmatter("No frontmatter here") == {}
+
+    def test_empty_frontmatter(self):
+        meta = parse_frontmatter("---\n---\nBody")
+        assert meta.get("triggers", []) == []
+        assert "name" not in meta
+
+    def test_multiple_triggers(self):
+        text = (
+            "---\n"
+            "name: multi\n"
+            "triggers:\n"
+            "  - /foo\n"
+            "  - /bar\n"
+            "  - baz\n"
+            "---\n"
+        )
+        meta = parse_frontmatter(text)
+        assert meta["triggers"] == ["/foo", "/bar", "baz"]
+
+    def test_no_triggers_key(self):
+        text = "---\nname: no-triggers\ndescription: desc\n---\n"
+        meta = parse_frontmatter(text)
+        assert meta["triggers"] == []
+
+    def test_triggers_with_comments(self):
+        text = (
+            "---\n"
+            "triggers:\n"
+            "  - /cmd\n"
+            "  # this is a comment\n"
+            "  - /other\n"
+            "---\n"
+        )
+        meta = parse_frontmatter(text)
+        assert "/cmd" in meta["triggers"]
+        assert "/other" in meta["triggers"]
+
+    def test_folded_block_scalar_description(self):
+        text = (
+            "---\n"
+            "name: test\n"
+            "description: >\n"
+            "  This is a long\n"
+            "  description text\n"
+            "other: value\n"
+            "---\n"
+        )
+        meta = parse_frontmatter(text)
+        assert meta["description"] == "This is a long description text"
+
+    def test_unicode(self):
+        text = (
+            "---\n"
+            "name: unic\u00f6de-skill\n"
+            "description: \u00dcn\u00efc\u00f6d\u00e9 description \U0001f680\n"
+            "---\n"
+        )
+        meta = parse_frontmatter(text)
+        assert meta["name"] == "unic\u00f6de-skill"
+        assert "\U0001f680" in meta["description"]
+
+
+class TestParseFrontmatterEdgeCases:
+    """Edge-case tests ensuring graceful degradation."""
+
+    def test_malformed_yaml_missing_close(self):
+        assert parse_frontmatter("---\nname: incomplete\n") == {}
+
+    def test_invalid_yaml_returns_empty(self):
+        assert parse_frontmatter("---\n: [invalid yaml{{\n---\n") == {}
+
+    def test_colon_in_description(self):
+        text = '---\nname: test\ndescription: "key: value pair"\n---\n'
+        meta = parse_frontmatter(text)
+        assert meta["description"] == "key: value pair"
+
+    def test_quoted_values_stripped(self):
+        text = "---\nname: \"quoted-name\"\ndescription: 'single-quoted'\n---\n"
+        meta = parse_frontmatter(text)
+        assert meta["name"] == "quoted-name"
+        assert meta["description"] == "single-quoted"
+
+    def test_triggers_end_at_next_key(self):
+        text = (
+            "---\n"
+            "triggers:\n"
+            "  - /a\n"
+            "  - /b\n"
+            "name: after-triggers\n"
+            "---\n"
+        )
+        meta = parse_frontmatter(text)
+        assert meta["triggers"] == ["/a", "/b"]
+        assert meta["name"] == "after-triggers"
+
+    def test_null_trigger_skipped(self):
+        text = (
+            "---\n"
+            "triggers:\n"
+            "  - /cmd\n"
+            "  -\n"
+            "  - /other\n"
+            "---\n"
+        )
+        meta = parse_frontmatter(text)
+        assert "/cmd" in meta["triggers"]
+        assert "/other" in meta["triggers"]
+
+    def test_frontmatter_only_block(self):
+        meta = parse_frontmatter("---\nname: only\n---")
+        assert meta["name"] == "only"
+
+
+# ── slash_triggers ────────────────────────────────────────────────────
+
+class TestSlashTriggers:
+    def test_filters_slash_only(self):
+        meta = {"triggers": ["/init", "keyword", "/build"]}
+        assert slash_triggers(meta) == ["/init", "/build"]
+
+    def test_empty(self):
+        assert slash_triggers({}) == []
+        assert slash_triggers({"triggers": []}) == []
+
+
+# ── _entry_type ───────────────────────────────────────────────────────
+
+class TestEntryType:
+    def test_skills_path(self):
+        assert _entry_type("./skills/foo") == "skill"
+
+    def test_plugins_path(self):
+        assert _entry_type("./plugins/bar") == "plugin"
+
+    def test_relative_plugins(self):
+        assert _entry_type("../plugins/baz") == "plugin"
+
+    def test_relative_skills(self):
+        assert _entry_type("../skills/qux") == "skill"
+
+    def test_fallback_is_skill(self):
+        assert _entry_type("./nonexistent-xyz") == "skill"
+
+
+# ── collect_needed_commands ───────────────────────────────────────────
+
+class TestCollectNeededCommands:
+    def test_returns_command_specs(self):
+        specs = collect_needed_commands()
+        assert all(isinstance(s, CommandSpec) for s in specs)
+        assert len(specs) > 0
+
+    def test_paths_are_under_commands_dir(self):
+        for spec in collect_needed_commands():
+            assert spec.path.parent.name == "commands"
+            assert spec.path.suffix == ".md"
+
+
+# ── load_marketplaces ────────────────────────────────────────────────
+
+class TestLoadMarketplaces:
+    def test_loads_at_least_one(self):
+        mps = load_marketplaces()
+        assert len(mps) > 0
+
+    def test_marketplaces_have_required_fields(self):
+        for mp in load_marketplaces():
+            assert "plugins" in mp
+            assert "_file" in mp
+
+
+# ── generate_catalog ─────────────────────────────────────────────────
+
+class TestGenerateCatalog:
+    def test_catalog_contains_marketplace_names(self):
+        catalog = generate_catalog()
+        assert "openhands-extensions" in catalog
+
+    def test_catalog_has_table_header(self):
+        catalog = generate_catalog()
+        assert "| Name | Type | Description | Commands |" in catalog
+
+    def test_catalog_counts_are_consistent(self):
+        catalog = generate_catalog()
+        assert "marketplace(s)" in catalog
+        assert "extensions" in catalog
+
+    def test_catalog_only_has_skill_or_plugin_types(self):
+        """Every table row's Type column must be 'skill' or 'plugin'."""
+        catalog = generate_catalog()
+        types_found: list[str] = []
+        for line in catalog.splitlines():
+            # Skip non-table lines, header, and separator
+            if not line.startswith("|") or line.startswith("|---") or "Type" in line:
+                continue
+            cols = [c.strip() for c in line.split("|")]
+            # cols[0] is empty (before first |), cols[1]=Name, cols[2]=Type
+            if len(cols) >= 3:
+                types_found.append(cols[2])
+        assert len(types_found) > 0, "Expected at least one table entry"
+        invalid = [t for t in types_found if t not in ("skill", "plugin")]
+        assert not invalid, f"Found invalid types in catalog: {invalid}"
+
+
+# ── sync_commands ────────────────────────────────────────────────────
+
+class TestSyncCommands:
+    def test_check_mode_reports_no_problems_when_in_sync(self):
+        problems = sync_commands(check=True)
+        assert problems == [], f"Unexpected problems: {problems}"
+
+    def test_manually_edited_file_detected_in_check_mode(self, tmp_path, monkeypatch):
+        """A command file without the header should be flagged in --check mode."""
+        # Create a skill with a slash trigger
+        skill_dir = tmp_path / "skills" / "test-skill"
+        skill_dir.mkdir(parents=True)
+        skill_md = skill_dir / "SKILL.md"
+        skill_md.write_text(
+            "---\nname: test-skill\ndescription: Test\ntriggers:\n  - /test-cmd\n---\nBody\n"
+        )
+        # Create a manually-edited command file (no header)
+        cmd_dir = skill_dir / "commands"
+        cmd_dir.mkdir()
+        (cmd_dir / "test-cmd.md").write_text("Custom content, no header\n")
+
+        monkeypatch.setattr("sync_extensions.REPO_ROOT", tmp_path)
+        monkeypatch.setattr("sync_extensions.SKILL_DIRS", [tmp_path / "skills"])
+        monkeypatch.setattr("sync_extensions._slash_cmd_cache", {})
+
+        problems = sync_commands(check=True)
+        assert any("manually-edited" in p for p in problems)
+
+
+# ── marketplace source paths ─────────────────────────────────────────
+
+class TestMarketplaceSourcePaths:
+    def test_all_source_paths_exist(self):
+        """Every source path in every marketplace should resolve on disk."""
+        import json
+
+        for mp in load_marketplaces():
+            mp_file = mp["_file"]
+            for plugin in mp["plugins"]:
+                src = plugin.get("source", "")
+                resolved = REPO_ROOT / src.lstrip("./")
+                assert resolved.exists(), (
+                    f"{mp_file.name}: {plugin.get('name', '?')} source "
+                    f"'{src}' does not exist at {resolved}"
+                )