@openhands/extensions 0.0.1-alpha → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openhands/extensions",
-  "version": "0.0.1-alpha",
+  "version": "0.2.0",
   "description": "Public OpenHands extension catalogs for skills, plugins, integrations, and automation templates.",
   "license": "MIT",
   "type": "module",
@@ -19,15 +19,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "index.js",
-    "index.d.ts",
-    "automations",
-    "integrations",
-    "LICENSE",
-    "MIGRATION.md",
-    "README.md"
-  ],
   "exports": {
     ".": {
       "types": "./index.d.ts",
@@ -51,6 +42,9 @@
       "default": "./integrations/logos.js"
     },
     "./integrations/catalog/*.json": "./integrations/catalog/*.json",
+    "./skills/*": "./skills/*",
+    "./plugins/*": "./plugins/*",
+    "./marketplaces/*.json": "./marketplaces/*.json",
     "./package.json": "./package.json"
   }
 }

package/plugins/README.md

@@ -0,0 +1,30 @@
+# Plugins Directory
+
+This directory contains OpenHands plugins - extensions with executable code components such as hooks and advanced scripts.
+
+## What are Plugins?
+
+Plugins differ from skills in that they include executable code that can hook into OpenHands workflows:
+
+- **hooks/**: Scripts that run at specific points in the agent lifecycle
+- **scripts/**: Executable utilities that extend agent capabilities
+
+## Structure
+
+Each plugin follows the same structure as a skill but with additional executable components:
+
+```
+plugins/
+└── my-plugin/
+    ├── SKILL.md          # Plugin definition and documentation
+    ├── hooks/            # Lifecycle hooks (optional)
+    │   ├── pre-task.sh
+    │   └── post-task.sh
+    └── scripts/          # Utility scripts (optional)
+        └── helper.py
+```
+
+## Contributing
+
+See the main [README](../README.md) for contribution guidelines.
+

package/plugins/city-weather/.plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "city-weather",
+  "version": "1.0.0",
+  "description": "Get current weather, time, and precipitation forecast for any city",
+  "author": {
+    "name": "JP Shackelford",
+    "email": "jpshackelford@users.noreply.github.com"
+  },
+  "homepage": "https://github.com/jpshackelford/openhands-sample-plugins",
+  "repository": "https://github.com/jpshackelford/openhands-sample-plugins",
+  "license": "MIT",
+  "keywords": ["weather", "time", "forecast", "temperature", "precipitation"]
+}

package/plugins/city-weather/README.md

@@ -0,0 +1,145 @@
+# City Weather Plugin
+
+Get current weather, time, and precipitation forecast for any city worldwide using the free [Open-Meteo API](https://open-meteo.com/).
+
+This plugin is also useful for **testing plugin loading** in OpenHands Cloud and the Software Agent SDK.
+
+## Features
+
+- **Slash command**: `/city-weather:now <city>`
+- **Temperature** in both Fahrenheit and Celsius
+- **Current time** in the city's local timezone
+- **Precipitation forecast** for the next 4 hours
+- **No API key required** — uses the free Open-Meteo API
+
+## Usage
+
+```
+/city-weather:now New York
+/city-weather:now Tokyo
+/city-weather:now London
+```
+
+### Example Output
+
+```
+City Weather Report for Tokyo, Japan
+
+- Current Time: 2025-02-19 14:30 JST
+- Temperature: 52°F / 11°C
+- Current Precipitation: 0.0 mm
+
+Precipitation Forecast (Next 4 Hours):
+| Time  | Probability |
+|-------|-------------|
+| 15:00 | 10%         |
+| 16:00 | 15%         |
+| 17:00 | 20%         |
+| 18:00 | 25%         |
+```
+
+---
+
+## Testing Plugin Loading
+
+This plugin can be used to verify that plugin loading works correctly across different OpenHands platforms.
+
+### OpenHands Cloud (app.all-hands.dev)
+
+Test the plugin loading endpoint at [app.all-hands.dev](https://app.all-hands.dev):
+
+```bash
+curl -X POST "https://app.all-hands.dev/api/v1/app-conversations" \
+  -H "Authorization: Bearer ${API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "initial_message": {
+      "content": [{"type": "text", "text": "/city-weather:now Tokyo"}]
+    },
+    "plugins": [{
+      "source": "github:OpenHands/extensions",
+      "ref": "main",
+      "repo_path": "plugins/city-weather"
+    }]
+  }'
+```
+
+The response includes a conversation ID. Poll `/api/v1/app-conversations/search` until `sandbox_status` is `"RUNNING"`, then view at:
+
+```
+https://app.all-hands.dev/conversations/{conversation_id}
+```
+
+> **Note:** Sandbox startup typically takes 30-90 seconds.
+
+### Software Agent SDK (1.10.0+)
+
+```python
+from openhands.sdk import Agent, Conversation, LLM
+from openhands.sdk.plugin import PluginSource
+from openhands.sdk.tool import Tool
+from openhands.tools.terminal import TerminalTool
+
+llm = LLM(model="anthropic/claude-sonnet-4-20250514", api_key=SecretStr("..."))
+agent = Agent(llm=llm, tools=[Tool(name=TerminalTool.name)])
+
+conversation = Conversation(
+    agent=agent,
+    plugins=[
+        PluginSource(
+            source="github:OpenHands/extensions",
+            ref="main",
+            repo_path="plugins/city-weather"
+        )
+    ]
+)
+
+conversation.send_message("/city-weather:now Tokyo")
+conversation.run()
+```
+
+---
+
+## Plugin Structure
+
+This plugin follows the [Claude Code plugin marketplace format](https://code.claude.com/docs/en/plugin-marketplaces):
+
+```
+city-weather/
+├── .claude-plugin/
+│   └── plugin.json      # Plugin manifest
+├── commands/
+│   └── now.md           # Slash command definition
+└── README.md
+```
+
+### How It Works
+
+1. The `/city-weather:now` slash command is converted to a `KeywordTrigger` skill
+2. When triggered, the agent receives instructions to:
+   - Call the Open-Meteo Geocoding API to find city coordinates
+   - Call the Open-Meteo Weather API to fetch current conditions and forecast
+   - Format and present the results
+
+The `$ARGUMENTS` placeholder in the command captures user input (e.g., "Tokyo").
+
+---
+
+## API Reference
+
+This plugin uses two Open-Meteo endpoints:
+
+| Endpoint | Purpose |
+|----------|---------|
+| `geocoding-api.open-meteo.com/v1/search` | Convert city name to coordinates |
+| `api.open-meteo.com/v1/forecast` | Fetch weather data |
+
+Both APIs are free and require no authentication.
+
+---
+
+## Related Resources
+
+- [OpenHands SDK Plugin Documentation](https://docs.openhands.dev/sdk/guides/plugins)
+- [OpenHands Cloud](https://app.all-hands.dev)
+- [Open-Meteo API Documentation](https://open-meteo.com/en/docs)

package/plugins/city-weather/commands/now.md

@@ -0,0 +1,56 @@
+---
+allowed-tools: Bash(curl:*)
+argument-hint: <city>
+description: Get current weather, time, and precipitation forecast for a city
+---
+
+# City Weather Report
+
+Get the current time, temperature (in both Fahrenheit and Celsius), and precipitation forecast for the next 4 hours for the specified city.
+
+## Instructions
+
+1. Parse the city name from the arguments: **$ARGUMENTS**
+
+2. Use the Open-Meteo Geocoding API to find the city coordinates:
+   ```bash
+   curl -s "https://geocoding-api.open-meteo.com/v1/search?name=CITY_NAME&count=1&language=en&format=json"
+   ```
+   Replace `CITY_NAME` with the URL-encoded city name.
+
+3. Extract the latitude, longitude, and timezone from the response.
+
+4. Use the Open-Meteo Weather API to fetch current weather and hourly forecast:
+   ```bash
+   curl -s "https://api.open-meteo.com/v1/forecast?latitude=LAT&longitude=LON&current=temperature_2m,precipitation&hourly=temperature_2m,precipitation_probability&timezone=TIMEZONE&forecast_hours=4"
+   ```
+   Replace `LAT`, `LON`, and `TIMEZONE` with the values from step 3.
+
+5. Format and present the results in a clear report:
+
+   **City Weather Report for [City Name]**
+   
+   - **Current Time:** [formatted local time in the city's timezone]
+   - **Temperature:** [X]°F / [Y]°C
+   - **Current Precipitation:** [amount] mm
+   
+   **Precipitation Forecast (Next 4 Hours):**
+   | Time | Probability |
+   |------|-------------|
+   | [hour 1] | [X]% |
+   | [hour 2] | [Y]% |
+   | [hour 3] | [Z]% |
+   | [hour 4] | [W]% |
+
+## Example Usage
+
+`/city-weather:now New York`
+`/city-weather:now Tokyo`
+`/city-weather:now London`
+
+## Notes
+
+- Uses the free Open-Meteo API (no API key required)
+- Temperature is provided in both Fahrenheit and Celsius
+- Precipitation probability is shown for the next 4 hours
+- Times are displayed in the city's local timezone

package/plugins/cobol-modernization/.plugin/plugin.json

@@ -0,0 +1,19 @@
+{
+  "name": "cobol-modernization",
+  "version": "1.0.0",
+  "description": "End-to-end COBOL to Java migration workflow. Handles build setup, mainframe dependency removal, and code migration with test validation.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "cobol",
+    "java",
+    "migration",
+    "mainframe",
+    "modernization"
+  ]
+}

package/plugins/cobol-modernization/README.md

@@ -0,0 +1,201 @@
+# COBOL Modernization Plugin
+
+End-to-end COBOL to Java migration workflow using OpenHands agents. This plugin orchestrates the complete modernization process from legacy COBOL codebases to modern Java applications, handling build setup, mainframe dependency removal, and code migration with test validation.
+
+## Quick Start
+
+```bash
+export LLM_API_KEY="your-api-key"
+export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"
+
+uv run python -m lc_sdk_examples.cobol_modernization --src-path /path/to/cobol/project
+```
+
+## Features
+
+- **Multi-Phase Migration** — Structured workflow from COBOL to Java in four phases
+- **Build Environment Setup** — Configures both GnuCOBOL and Java compilation
+- **Mainframe Independence** — Removes CICS/VSAM dependencies before migration
+- **Test-Driven Migration** — Creates test fixtures from COBOL execution for Java validation
+- **Idiomatic Java Output** — Produces proper Java conventions, not literal translations
+
+## Prerequisites
+
+- GnuCOBOL compiler (`cobc`)
+- Java 11+ with Maven or Gradle
+- Python 3.13 with `uv`
+- LLM API key
+
+## Plugin Contents
+
+```
+plugins/cobol-modernization/
+├── README.md                              # This file
+├── references/                            # Reference documentation
+│   └── troubleshooting.md                 # Common issues and solutions
+└── skills/                                # Workflow phase skills
+    ├── build-setup/                       # Phase 1: Build environment
+    │   └── SKILL.md
+    ├── cobol-modernization-overview/      # Plugin overview
+    │   └── SKILL.md
+    ├── mainframe-planning/                # Phase 2: Transformation planning
+    │   └── SKILL.md
+    ├── mainfraime-removal/                # Phase 3: Mainframe dependency removal
+    │   ├── SKILL.md
+    │   └── references/
+    │       └── cics-transformation-examples.md
+    └── to-java-migration/                 # Phase 4: Java migration
+        ├── SKILL.md
+        └── references/
+            ├── cobol-to-java-example.md
+            └── datatype-mappings.md
+```
+
+## Workflow Phases
+
+### Phase 1: Build Setup
+
+Creates the foundation for the migration:
+
+- COBOL compilation environment using GnuCOBOL
+- Java project structure with Maven/Gradle and JUnit 5
+- Test fixtures with golden outputs from COBOL execution
+
+**Outputs:**
+- `build_notes.md` — Build instructions
+- `test-fixtures/` — Input/output test data
+- `test_manifest.json` — Test case mapping
+
+### Phase 2: Mainframe Planning
+
+Creates a transformation guide without modifying code:
+
+- Maps CICS/VSAM constructs to standard COBOL equivalents
+- Documents error handling replacements
+- Identifies UI operations to stub
+
+**Output:** `mainframe_dependency_removal_plan.md`
+
+### Phase 3: Mainframe Removal
+
+Applies the transformation guide:
+
+- Replaces `EXEC CICS` commands with file I/O
+- Adds `FILE STATUS` checking
+- Stubs BMS/screen operations
+
+**Verification:**
+- Code compiles with GnuCOBOL
+- Runs with test fixtures
+
+### Phase 4: Java Migration
+
+Translates to idiomatic Java:
+
+- Proper Java conventions (not literal translations)
+- JUnit tests using golden outputs
+- COBOL references in comments
+
+**Done when:**
+- All code compiles
+- All JUnit tests pass
+- No TODOs or stubs remain
+
+## Output Structure
+
+```
+your-project/
+├── .lc-sdk/
+│   ├── initial_batch_graph.json
+│   ├── fixed_batch_graph.json
+│   └── mainframe_dependency_removal_plan.md
+├── test-fixtures/
+│   ├── inputs/
+│   └── expected_outputs/
+├── test_manifest.json
+├── src/main/java/
+└── src/test/java/
+```
+
+## Usage
+
+### Running the Migration
+
+1. **Prepare your COBOL project**: Ensure all source files are accessible
+2. **Set environment variables**:
+   ```bash
+   export LLM_API_KEY="your-api-key"
+   export LLM_MODEL="anthropic/claude-3-5-sonnet-20241022"
+   ```
+3. **Run the migration**:
+   ```bash
+   uv run python -m lc_sdk_examples.cobol_modernization --src-path /path/to/cobol/project
+   ```
+4. **Review outputs**: Check generated Java code and run tests
+
+### Phase-by-Phase Execution
+
+You can also run individual phases by using the specific skill definitions:
+
+- See [skills/build-setup/SKILL.md](skills/build-setup/SKILL.md) for build setup only
+- See [skills/mainframe-planning/SKILL.md](skills/mainframe-planning/SKILL.md) for planning
+- See [skills/mainfraime-removal/SKILL.md](skills/mainfraime-removal/SKILL.md) for mainframe removal
+- See [skills/to-java-migration/SKILL.md](skills/to-java-migration/SKILL.md) for Java translation
+
+## Troubleshooting
+
+### GnuCOBOL Not Found
+
+```bash
+# Install on Debian/Ubuntu
+sudo apt-get install gnucobol
+
+# Install on macOS
+brew install gnucobol
+```
+
+### COBOL Compilation Errors
+
+1. Check that all copybooks are in the include path
+2. Verify file encoding (COBOL often uses EBCDIC)
+3. See [references/troubleshooting.md](references/troubleshooting.md) for common issues
+
+### Java Tests Failing
+
+1. Compare test outputs with golden outputs in `test-fixtures/`
+2. Check for numeric precision differences (COBOL vs Java)
+3. Verify date/time handling conversions
+
+### Mainframe Dependencies Remaining
+
+1. Review `mainframe_dependency_removal_plan.md`
+2. Check for indirect CICS calls through subroutines
+3. Verify all VSAM file accesses are converted
+
+## Supported COBOL Features
+
+- Standard COBOL-85 and COBOL-2002 syntax
+- CICS command-level programs
+- VSAM file operations
+- Common mainframe utilities (SORT, IDCAMS)
+- COPY/COPYBOOK statements
+- Nested programs and subprograms
+
+## Limitations
+
+- Does not support assembler programs called from COBOL
+- IMS/DB2 support is limited
+- Screen handling (BMS) is stubbed, not fully migrated
+- Some proprietary extensions may require manual intervention
+
+## Related Resources
+
+- **Blog Post**: [COBOL to Java Refactoring with OpenHands](https://openhands.dev/blog/20251218-cobol-to-java-refactoring) — Detailed walkthrough of the migration process
+
+## Contributing
+
+See the main [extensions repository](https://github.com/OpenHands/extensions) for contribution guidelines.
+
+## License
+
+This plugin is part of the OpenHands extensions repository. See [LICENSE](../../LICENSE) for details.

package/plugins/cobol-modernization/references/troubleshooting.md

@@ -0,0 +1,18 @@
+# Troubleshooting Guide
+
+## COBOL doesn't compile after mainframe removal
+
+- Check FILE STATUS is declared for all files
+- Ensure CLOSE statements in all code paths
+- Verify paragraph names match PERFORM statements
+
+## Java tests fail
+
+- Compare output byte-by-byte with golden files
+- Check decimal precision (use BigDecimal)
+- Verify character encoding matches COBOL
+
+## Missing functionality
+
+- Check the migration mapping for coverage gaps
+- Review `mainframe_dependency_removal_plan.md` for skipped items

package/plugins/cobol-modernization/skills/build-setup/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: build-setup
+description: Set up build environment and test fixtures for COBOL-to-Java migrations. Creates compilation infrastructure for both languages and generates golden test data.
+license: MIT
+compatibility: Requires GnuCOBOL (cobc), Java 11+, Maven or Gradle
+triggers:
+  - cobol build
+  - cobol test fixtures
+  - migration build setup
+  - gnucobol
+---
+
+Set up a build environment and create test fixtures for validating COBOL-to-Java migrations.
+
+To install GnuCOBOL, run: `./scripts/install-gnucobol.sh`
+
+## Phase 1: Build Setup
+
+### COBOL Build
+
+- Find a way to compile and run the COBOL code (e.g., GnuCOBOL)
+- Verify at least one program compiles and executes
+- Note any dependencies or setup required
+
+### Java Build
+
+- Initialize a Java project alongside the COBOL code (Maven or Gradle)
+- Set up standard directory structure: `src/main/java`, `src/test/java`
+- Include JUnit 5 as a test dependency
+- Verify the project builds (even if empty)
+
+## Phase 2: Test Fixture Generation
+
+For each major COBOL program:
+
+### Create Synthetic Test Inputs
+
+- Save to: `test-fixtures/inputs/{PROGRAM_NAME}/`
+- Create 3-5 test cases per program covering:
+  - Normal/happy path (valid, typical data)
+  - Edge cases (empty input, maximum values, boundary conditions)
+  - Error cases (invalid formats, missing required fields)
+
+### Generate Golden Outputs
+
+- Run each COBOL program with each test input
+- Save COBOL output to: `test-fixtures/expected_outputs/{PROGRAM_NAME}/`
+- These become the "golden" outputs that Java must match
+
+### Create Test Manifest
+
+Save to `test_manifest.json`:
+
+```json
+{
+  "PROGRAM1": {
+    "description": "Brief description of what this program does",
+    "test_cases": [
+      {
+        "name": "normal_invoice",
+        "input": "inputs/PROGRAM1/test_001.dat",
+        "expected": "expected_outputs/PROGRAM1/test_001.out",
+        "description": "Happy path"
+      }
+    ]
+  }
+}
+```
+
+## Deliverables
+
+1. **build_notes.md** — Build instructions for COBOL and Java
+2. **test-fixtures/** — Directory with `inputs/` and `expected_outputs/`
+3. **test_manifest.json** — JSON manifest of all test cases
+
+## Priority
+
+Focus on programs with core business logic (transactions, calculations, data processing). UI-heavy programs (menu screens, reports) are lower priority.

package/plugins/cobol-modernization/skills/build-setup/scripts/install-gnucobol.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# Install GnuCOBOL compiler for COBOL-to-Java migration projects
+
+set -euo pipefail
+
+echo "Installing GnuCOBOL..."
+
+if [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    if command -v apt-get &> /dev/null; then
+        sudo apt-get update
+        sudo apt-get install -y gnucobol
+    elif command -v yum &> /dev/null; then
+        sudo yum install -y gnucobol
+    else
+        echo "Error: Unsupported Linux package manager"
+        exit 1
+    fi
+elif [[ "$OSTYPE" == "darwin"* ]]; then
+    if command -v brew &> /dev/null; then
+        brew install gnucobol
+    else
+        echo "Error: Homebrew not found. Install from https://brew.sh"
+        exit 1
+    fi
+else
+    echo "Error: Unsupported OS: $OSTYPE"
+    exit 1
+fi
+
+echo "Verifying installation..."
+cobc --version
+echo "GnuCOBOL installed successfully!"