@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/vendor/skills/skills/galaxy-data-libraries/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: galaxy-data-libraries
+description: Use when data lives in a Galaxy data library rather than a history (a named library, or a folder id starting with F) -- walk folders, get dataset ids, run tools on library datasets in place, import only when needed.
+metadata:
+  surfaces: [loom]
+  # Staging in Orbit; this is where it should end up.
+  proposed_home: galaxy-skills
+user_invocable: true
+---
+
+# Galaxy Data Libraries
+
+A data library is a server-side folder tree an admin or project has published: reference data,
+challenge data, a consortium's release. The files are already on the server, often in large
+numbers, and nobody should upload or download them to use them. This skill is how to find them and
+hand them to tools without copying.
+
+## Which tool does what
+
+galaxy-ops has no library operations yet, so **listing** uses the REST API through `bash` + `curl`.
+Everything after that goes through the normal in-process tools:
+
+| Step                                    | How                                                                               |
+| --------------------------------------- | --------------------------------------------------------------------------------- |
+| List libraries, walk folders, find ids  | `curl` (below)                                                                    |
+| Run a tool on a library dataset         | `run_tool` with `{"src": "ldda", "id": ...}`                                      |
+| Bring a dataset into a history          | `curl` POST (below), then the usual history tools                                 |
+| Look at a dataset, run a workflow on it | Import it first, then `get_dataset_details` / `invoke_workflow` with `src: "hda"` |
+
+If this shell has no `bash`, stop and tell the user: they can browse the library in the Galaxy UI
+(Libraries in the top menu) and import what they need into a history, and you take it from there.
+
+## curl conventions
+
+```bash
+curl -s -H "x-api-key: $GALAXY_API_KEY" "$GALAXY_URL/api/libraries"
+```
+
+- Use `$GALAXY_URL` and `$GALAXY_API_KEY` from the environment. Never paste the key into a command,
+  the notebook or chat.
+- Public libraries also answer without the key; restricted ones need it. When a library the user
+  can see in the UI comes back missing or 403, the key is the first suspect.
+- Use `jq` to print only the fields you need; folder listings are verbose. Without `jq`, save the
+  response with `-o` and read the file with `python3`. Never pipe `curl` into `python3` (or any
+  interpreter): Orbit's command guard refuses that outright, whatever the approval mode.
+
+## Ids: the part that goes wrong
+
+| Thing                             | Looks like         | Where it comes from                               |
+| --------------------------------- | ------------------ | ------------------------------------------------- |
+| Library                           | 16 hex chars       | `GET /api/libraries` -> `id`                      |
+| Folder                            | `F` + 16 hex chars | library `root_folder_id`, or a folder item's `id` |
+| Library dataset (`ld`)            | 16 hex chars       | a file item's `id`                                |
+| Library dataset instance (`ldda`) | 16 hex chars       | a file item's `ldda_id`                           |
+
+A file in a folder listing has **two** ids. They are often equal, but they are different objects and
+can differ, so always take the one the consumer asks for:
+
+- `run_tool` inputs want the **`ldda_id`**: `{"src": "ldda", "id": "<ldda_id>"}`.
+- Importing into a history wants the **`id`** (the `ld`).
+
+The folder endpoint needs the `F`. Without it Galaxy answers "Invalid library folder ID".
+
+## Walk a library
+
+```bash
+# Libraries, with the folder to start from
+curl -s -H "x-api-key: $GALAXY_API_KEY" "$GALAXY_URL/api/libraries" \
+  | jq -r '.[] | [.id, .root_folder_id, .name] | @tsv'
+
+# The same without jq: save it, then read the file
+curl -s -H "x-api-key: $GALAXY_API_KEY" "$GALAXY_URL/api/libraries" -o libraries.json
+python3 -c 'import json; [print(l["id"], l["root_folder_id"], l["name"]) for l in json.load(open("libraries.json"))]'
+
+# One folder's contents
+curl -s -H "x-api-key: $GALAXY_API_KEY" \
+  "$GALAXY_URL/api/folders/F0123456789abcdef/contents?limit=100&offset=0"
+```
+
+The folder response is `{"metadata": {...}, "folder_contents": [...]}`:
+
+- Each item has `type` (`"folder"` or `"file"`), `name` and `id`. File items also carry `ldda_id`,
+  `file_ext`, `file_size` (human-readable), `raw_size` (bytes) and `state`.
+- `metadata.total_rows` is the true count. **The default page is only 10 items**, so a folder that
+  looks like it holds 10 files may hold hundreds. Pass `limit`, and page with `offset` until you
+  have `total_rows`.
+- `search_text=<substring>` filters by name on the server. Use it rather than paging through a
+  folder of hundreds of files to find one.
+- `metadata.full_path` gives the breadcrumb of `[folder_id, name]` pairs back to the library root.
+
+Walk only as deep as the question needs. A large library can have thousands of files, so summarise
+what you find (counts per folder, a few example names) rather than listing everything.
+
+## Use a dataset in place
+
+```text
+run_tool({
+  "toolId": "Show beginning1",
+  "historyId": "<history id>",
+  "inputs": {"input": {"src": "ldda", "id": "<ldda_id>"}, "lineNum": 10}
+})
+```
+
+Galaxy adds the library dataset to the target history as a new item, without copying the bytes,
+and the job's output lands after it. Expect one extra history item per library input. That is
+normal, not a duplicate upload.
+
+**Several library datasets into one `multiple: true` input:** wrap the list, as in
+`{"tars": {"values": [{"src": "ldda", "id": "..."}, {"src": "ldda", "id": "..."}]}}` for an input
+named `tars` (use the tool's own input name). A bare list
+of `ldda` references is rejected before any job is created, with `'LibraryDatasetDatasetAssociation'
+object has no attribute 'auto_propagated_tags'`. Bare lists of `hda` references are fine, so
+importing first also works.
+
+**Workflows:** Galaxy accepts `ldda` inputs to a workflow, but `invoke_workflow`'s input check only
+accepts `hda`/`hdca` and rejects the run. Import the dataset into the history first (below) and pass
+the resulting `hda`.
+
+## Import into a history
+
+Import when a workflow needs the dataset, when the user wants it in the history, or before
+`get_dataset_details`, which reads history datasets:
+
+```bash
+# One dataset: content is the file item's `id` (the ld), not its ldda_id
+curl -s -X POST -H "x-api-key: $GALAXY_API_KEY" -H "Content-Type: application/json" \
+  -d '{"type": "dataset", "source": "library", "content": "<ld id>"}' \
+  "$GALAXY_URL/api/histories/<history id>/contents"
+
+# A whole folder, recursively: content is the F-prefixed folder id
+curl -s -X POST -H "x-api-key: $GALAXY_API_KEY" -H "Content-Type: application/json" \
+  -d '{"type": "dataset", "source": "library_folder", "content": "F0123456789abcdef"}' \
+  "$GALAXY_URL/api/histories/<history id>/contents"
+```
+
+Check the `name` in the response matches the file you meant. A mixed-up id is not always an
+error (see Troubleshooting).
+
+An import links the existing dataset, so it is instant and its state is `ok` at once, whatever the
+size. It costs no quota or disk. It does add history items, though: importing a folder of hundreds of
+files makes a history nobody can navigate. Import the few files a step needs, and confirm with the
+user before importing a whole folder.
+
+## Large files
+
+Library datasets are often big: a 40 MB manifest, multi-gigabyte archives. Don't pull one into the
+conversation.
+
+- **Tables and manifests:** import, then `get_dataset_details` for a preview, or run Galaxy tools
+  (Select first, Cut, Filter, Count, Group) to summarise them. The summary lands in the history, and
+  that is the record.
+- **Archives and images:** run tools on them in place. Never download them locally.
+
+## Troubleshooting
+
+| Symptom                                                                             | Likely cause                                                                                                                                                                                                  |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Library missing from `/api/libraries`, or 403 on a folder                           | No key, or the user lacks access to a restricted library                                                                                                                                                      |
+| "Invalid library folder ID"                                                         | Folder id sent without its leading `F`                                                                                                                                                                        |
+| "'content' id of lda or hda is missing"                                             | Import POST without `content`                                                                                                                                                                                 |
+| An import brought in a file you never asked for                                     | A folder id was sent with `source: "library"`. Galaxy does not reject it: it drops the `F` and imports whatever dataset has that number. Use `library_folder` for folders, and check the imported item's name |
+| A folder seems to hold exactly 10 files                                             | You read only the default page; check `metadata.total_rows`                                                                                                                                                   |
+| `'LibraryDatasetDatasetAssociation' object has no attribute 'auto_propagated_tags'` | A bare list of `ldda` refs in a multiple input; wrap it as `{"values": [...]}`                                                                                                                                |
+| `invoke_workflow` rejects an `ldda` input                                           | Known limit of the input check; import first and pass the `hda`                                                                                                                                               |
+
+## Related
+
+- `galaxy-mcp-reference` (galaxy-skills) for history, tool and workflow operations in general.
+- Galaxy API source: [folder contents](https://github.com/galaxyproject/galaxy/blob/dev/lib/galaxy/webapps/galaxy/api/folder_contents.py),
+  [history import from a library](https://github.com/galaxyproject/galaxy/blob/dev/lib/galaxy/webapps/galaxy/services/history_contents.py).

package/extensions/orbit/vendor/skills/skills/galaxy-integration/README.md

@@ -0,0 +1,162 @@
+# Galaxy Integration
+
+Using Galaxy MCP, JupyterLite notebooks, and BioBlend-based scripts to interact with Galaxy instances.
+
+This is the canonical documentation for Galaxy instance integration across skills in this repository.
+
+**Agent entrypoint**: See `SKILL.md`.
+
+## Purpose
+
+Galaxy integration provides programmatic access to Galaxy instances. Useful for:
+
+- **Testing** - Validate converted tools on Galaxy instances
+- **Automation** - Streamline development workflows
+- **Validation** - Compare outputs (e.g., NF vs Galaxy)
+- **Analysis** - Write JupyterLite notebooks that interact with Galaxy datasets
+
+## Structure
+
+```
+galaxy-integration/
+├── SKILL.md                    # Router to sub-skills
+├── galaxy-integration.md       # Detailed MCP + BioBlend docs
+│
+├── jupyterlite/                # JupyterLite notebook skill
+│   ├── SKILL.md               # gxy package reference
+│   └── examples/              # Example notebooks
+│
+(mcp-reference now lives at ../galaxy-mcp-reference/)
+│   ├── SKILL.md               # Full MCP tools reference
+│   ├── history-access.md      # History/dataset access patterns
+│   └── gotchas.md             # Common pitfalls (keychain, URL slugs)
+│
+├── scripts/                    # BioBlend automation
+│   └── galaxy_tool_checker.py
+│
+└── examples/                   # Tool checking and workflow testing
+```
+
+## Key Files
+
+- **`SKILL.md`** - Router to sub-skills
+- **`jupyterlite/SKILL.md`** - gxy package for JupyterLite notebooks
+- **`../galaxy-mcp-reference/SKILL.md`** - Complete MCP tools reference
+- **`galaxy-integration.md`** - Detailed guide (MCP + BioBlend)
+- **`scripts/`** - Automation scripts (galaxy_tool_checker.py)
+- **`examples/`** - Tool checking and workflow testing examples
+
+## Usage Context
+
+MCP is primarily used in the **nf-to-galaxy** conversion workflow for:
+- Testing converted tools on local Galaxy instances
+- Uploading test data
+- Running tools and validating outputs
+- Comparing Nextflow vs Galaxy results
+
+It may also be used by other skills that need to interact with a Galaxy instance (tool discovery, workflow testing, automation).
+
+---
+
+## Quick Reference
+
+### Setup
+
+```bash
+# Install
+pip install galaxy-mcp
+
+# Configure for Claude Code
+# Add to ~/.config/claude/claude_desktop_config.json:
+{
+  "mcpServers": {
+    "galaxy-mcp": {
+      "command": "uvx",
+      "args": ["galaxy-mcp"],
+      "env": {
+        "GALAXY_URL": "http://localhost:8080",
+        "GALAXY_API_KEY": "your-key"
+      }
+    }
+  }
+}
+```
+
+---
+
+## When to Use Galaxy MCP
+
+Use Galaxy MCP when:
+- You want **interactive exploration** of a Galaxy instance (tool search, tool I/O inspection)
+- You are iterating on a workflow/tool and want **fast feedback** (create history, invoke workflow, inspect failures)
+- You are working in an agentic environment where MCP tools are available
+
+Prefer a script (e.g. BioBlend) when:
+- You need to check **many tools at once**
+- You want **repeatable automation** (CI-style checks)
+- You want **workflow validation** without interactive iteration
+
+---
+
+## Prerequisites
+
+- Galaxy instance URL (e.g. `https://usegalaxy.org/`)
+- Galaxy API key (User → Preferences → Manage API Key)
+
+**Where to find these**:
+- **Galaxy URL**: The base URL of the Galaxy server you use (for public servers this is the site URL, e.g. `https://usegalaxy.org/`, `https://usegalaxy.eu/`).
+- **API key**: In Galaxy, go to **User → Preferences → Manage API Key**.
+
+**Using the repo-wide `.env` (recommended for this repository)**:
+- From the **skills repository root**:
+
+```bash
+cp .env.example .env
+nano .env
+```
+
+- Add:
+
+```bash
+GALAXY_URL=https://usegalaxy.org/
+GALAXY_API_KEY=your_actual_api_key_here
+```
+
+The root `.env` is gitignored; do not commit API keys.
+
+Treat the API key like a password. Do not commit it to git.
+
+---
+
+## Common MCP Tools (Typical Development Loop)
+
+- **Connect**: `connect()` (or equivalent connection step depending on the client)
+- **Find tools**: `search_tools_by_name(query=...)`
+- **Inspect tool I/O**: `get_tool_details(tool_id=..., io_details=True)`
+- **Create a history**: `create_history(history_name=...)`
+- **Upload data**: `upload_file(...)`
+- **Run tools**: `run_tool(...)`
+- **Run workflows**: `invoke_workflow(workflow_id=..., inputs=..., history_id=...)`
+- **Inspect outputs**: `get_history_contents(history_id=...)`, `get_dataset_details(...)`
+
+---
+
+## Minimal Workflow Testing Pattern
+
+1. Create a new history for a clean run
+2. Upload (or reuse) small test inputs
+3. Invoke your workflow
+4. Poll history contents until jobs finish
+5. If something fails:
+    - identify the failing step/tool
+    - fix tool IDs / parameter mapping
+    - re-import workflow and retry
+
+---
+
+## Where This Is Used
+
+- **Nextflow → Galaxy conversions**: see `../../dev-skills/nf-to-galaxy/` (the conversion skill points here when MCP is needed)
+
+See the upstream project for the full API reference:
+- https://github.com/galaxyproject/galaxy-mcp

package/extensions/orbit/vendor/skills/skills/galaxy-integration/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: galaxy-integration
+description: "Use when setting up or choosing how an agent talks to a Galaxy instance -- first-time connection (server URL, API key, verifying access), then picking between Galaxy MCP for interactive work, JupyterLite notebooks for analysis against Galaxy datasets, and BioBlend scripts for batch or CI. Start here to use Galaxy when not yet connected."
+user_invocable: true
+---
+
+# Galaxy Integration Skill
+
+Use Galaxy MCP and BioBlend-based scripts to interact with a Galaxy instance for tool discovery, workflow validation, and workflow testing.
+
+## Sub-Skills
+
+Route to the appropriate sub-skill based on task:
+
+| Task | Sub-Skill | Location |
+|------|-----------|----------|
+| Write JupyterLite notebook | `jupyterlite-galaxy` | `jupyterlite/SKILL.md` |
+| MCP tools reference | `galaxy-mcp-reference` | `../galaxy-mcp-reference/SKILL.md` |
+| History/dataset access | - | `../galaxy-mcp-reference/history-access.md` |
+| Common gotchas | - | `../galaxy-mcp-reference/gotchas.md` |
+| BioBlend batch scripts | - | `scripts/galaxy_tool_checker.py` |
+| Tool checking examples | - | `examples/tool-checking.md` |
+| Workflow testing examples | - | `examples/workflow-testing.md` |
+
+## When to Use
+
+- **Query tools** installed on a Galaxy instance
+- **Inspect tool I/O** and parameters
+- **Create histories**, upload data, run tools/workflows
+- **Debug workflow/tool issues** with fast, interactive feedback
+- **Write JupyterLite notebooks** that interact with Galaxy datasets
+
+## Prerequisites
+
+### Galaxy URL
+
+The base URL of the Galaxy server:
+- `https://usegalaxy.org/`
+- `https://usegalaxy.eu/`
+- `http://localhost:8080/`
+
+### Galaxy API Key
+
+In Galaxy UI: **User -> Preferences -> Manage API Key**
+
+### Repository `.env` (recommended)
+
+```bash
+cp .env.example .env
+nano .env
+```
+
+Set:
+```bash
+GALAXY_URL=https://usegalaxy.org/
+GALAXY_API_KEY=your_actual_api_key_here
+```
+
+## When to Use MCP vs Scripts
+
+**Galaxy MCP** when:
+- Interactive exploration (find a tool, inspect exact tool IDs)
+- Debugging a workflow with fast iteration
+
+**BioBlend script** (`scripts/galaxy_tool_checker.py`) when:
+- Batch checks across many tools
+- Repeatable validation/testing as part of CI-like flow
+
+## Core MCP Workflow
+
+1. **Confirm MCP connectivity**
+   - If not connected, see `README.md` for configuration
+
+2. **Tool discovery**
+   ```
+   search_tools_by_name(query=...)
+   get_tool_details(tool_id=..., io_details=True)
+   ```
+
+3. **Workflow testing loop**
+   ```
+   create_history(history_name=...)
+   invoke_workflow(workflow_id=..., inputs=..., history_id=...)
+   get_history_contents(history_id=...)
+   # Fix and repeat
+   ```
+
+## Output Expectations
+
+When reporting MCP results:
+- Provide **full Galaxy tool ID** (ToolShed-style)
+- Include tool version
+- Note whether tool is installed vs only available in repository
+
+## References
+
+- Upstream Galaxy MCP: https://github.com/galaxyproject/galaxy-mcp
+- Repository guide: `README.md`
+- Detailed MCP docs: `galaxy-integration.md`

package/extensions/orbit/vendor/skills/skills/galaxy-integration/examples/README.md

@@ -0,0 +1,119 @@
+# Galaxy Integration Examples
+
+Practical examples for interacting with Galaxy instances using MCP and BioBlend.
+
+---
+
+## Overview
+
+These examples demonstrate **how to use Galaxy MCP and BioBlend** to interact with Galaxy instances. They are **domain-agnostic** and can be applied to any workflow or tool testing scenario.
+
+---
+
+## Examples
+
+### tool-checking.md
+
+**Purpose**: Check tool availability on a Galaxy instance
+
+**Covers**:
+- Using Galaxy MCP to search for tools
+- Using BioBlend script to validate tool lists
+- Decision matrix: when to use MCP vs BioBlend
+- Interpreting results
+
+**Use when**: You need to verify tools exist before creating/running workflows
+
+---
+
+### workflow-testing.md
+
+**Purpose**: Test and validate workflows on a Galaxy instance
+
+**Covers**:
+- Using Galaxy MCP for interactive workflow testing
+- Using BioBlend script for automated workflow validation
+- Workflow invocation and monitoring
+- Output verification
+- Decision matrix: when to use MCP vs BioBlend
+
+**Use when**: You need to test a workflow on a Galaxy instance
+
+---
+
+## When to Use These Examples
+
+### During Conversion (Nextflow → Galaxy)
+
+After converting a Nextflow workflow to Galaxy, use these examples to:
+1. Check that all required tools exist (`tool-checking.md`)
+2. Test the converted workflow (`workflow-testing.md`)
+
+**See also**: `../../../dev-skills/nf-to-galaxy/examples/` for conversion-specific scenarios
+
+### During Tool Development
+
+After creating or updating a Galaxy tool, use these examples to:
+1. Verify tool is available on target instance
+2. Test tool in a workflow context
+
+**See also**: `../../../dev-skills/tool-dev/SKILL.md`
+
+### General Workflow Testing
+
+For any Galaxy workflow testing needs:
+1. Validate workflow structure
+2. Test workflow execution
+3. Compare outputs
+
+---
+
+## Prerequisites
+
+### Galaxy MCP
+
+Interactive Galaxy client for exploration and debugging.
+
+**Setup**: See `../galaxy-integration.md` for MCP configuration
+
+**Best for**:
+- Interactive exploration
+- Debugging workflow issues
+- Real-time monitoring
+- Complex decision-making
+
+### BioBlend Script
+
+Automated Galaxy tool checker and workflow validator.
+
+**Setup**: See `../scripts/README.md` for script configuration
+
+**Best for**:
+- Automated validation
+- Batch checking
+- CI/CD integration
+- Scripted workflows
+
+---
+
+## Related Documentation
+
+- **Main guide**: `../galaxy-integration.md` - Complete Galaxy integration guide
+- **MCP setup**: `../galaxy-integration.md#setup`
+- **BioBlend script**: `../scripts/README.md` - galaxy_tool_checker.py usage
+- **Conversion examples**: `../../../dev-skills/nf-to-galaxy/examples/` - Conversion-specific scenarios
+- **Testing guide**: `../../../dev-skills/tool-dev/references/testing.md` - Planemo tool testing
+
+---
+
+## Quick Reference
+
+| Task | MCP | BioBlend Script |
+|------|-----|-----------------|
+| Check single tool | `search_tools_by_name()` | `--tool-id TOOL_ID` |
+| Check tool list | Multiple calls | `--tool-list file.txt` |
+| Validate workflow | `import_workflow()` | `--workflow file.ga` |
+| Test workflow | `invoke_workflow()` | `--workflow --test` |
+| Monitor execution | `get_invocation()` | `--wait` flag |
+| Batch operations | Manual iteration | Native support |
+| CI/CD integration | Possible but complex | Designed for it |