@seqera/node-red-seqera/CLAUDE.md

Node-RED nodes for interacting with the Seqera Platform API

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Node-RED extension providing custom nodes for interacting with the Seqera Platform API. Users install this package in Node-RED to build automation workflows that launch, monitor, and manage Nextflow pipelines on Seqera Platform.

**Key package details:**

-   Package name: `@seqera/node-red-seqera`
-   Published to npm and distributed via Node-RED's palette manager
-   Also available as Docker images: `ghcr.io/seqeralabs/node-red-seqera` (base) and `ghcr.io/seqeralabs/node-red-seqera-studios` (Seqera Studios)

## Development Commands

```bash
# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Linting (uses pre-commit hooks)
pre-commit run --all-files

# No build step required - Node-RED loads .js files directly
# To test locally, install in your Node-RED user directory:
cd ~/.node-red
npm install /path/to/this/repo
```

## Architecture

### Node Registration Pattern

All nodes follow a standard Node-RED registration pattern:

1. **Module export function** receives `RED` runtime object
2. **Node constructor function** receives config from editor and calls `RED.nodes.createNode(this, config)`
3. **Registration** via `RED.nodes.registerType(type, constructor, options)`
4. **HTML counterpart** (same filename but `.html`) defines editor UI, help text, and default values

### Shared Configuration: seqera-config

All Seqera nodes depend on a `seqera-config` node that stores:

-   Base URL (default: `https://api.cloud.seqera.io`)
-   API token (stored in credentials)
-   Workspace ID

This config is referenced via `node.seqeraConfig = RED.nodes.getNode(config.seqera)`.

### Shared Utilities

**[nodes/\_utils.js](nodes/_utils.js) - Core API helpers:**

-   `buildHeaders(node, extraHeaders)` - Constructs headers with Bearer token from seqera-config
-   `apiCall(node, method, url, options)` - Axios wrapper that merges auth headers, logs failures, and re-throws errors
-   `handleDatalinkAutoComplete(RED, req, res)` - HTTP endpoint handler for Data Link name autocomplete (used by datalink-list and datalink-poll nodes)

**[nodes/datalink-utils.js](nodes/datalink-utils.js) - Data Link specific utilities:**

-   `evalProp(RED, node, msg, value, type)` - Property evaluation helper supporting JSONata expressions
-   `resolveDataLink(RED, node, msg, dataLinkName, options)` - Resolves Data Link by name, returns IDs and metadata
-   `listDataLink(RED, node, msg)` - Core implementation for listing files/folders from Data Links with filtering and recursion

### Property Evaluation Pattern

Nodes use Node-RED's typedInput system allowing properties to be:

-   Static strings (`str`)
-   Message properties (`msg`)
-   JSONata expressions (`jsonata`)
-   Flow/global context
-   JSON literals

**Evaluation helper (present in most nodes):**

```javascript
const evalProp = async (p, t, msg) => {
    if (t === "jsonata") {
        const expr = RED.util.prepareJSONataExpression(p, node);
        return await new Promise((resolve, reject) => {
            RED.util.evaluateJSONataExpression(expr, msg, (err, value) => {
                if (err) return reject(err);
                resolve(value);
            });
        });
    }
    return RED.util.evaluateNodeProperty(p, t, node, msg);
};
```

Always evaluate properties inside the `node.on("input", ...)` handler so they reflect current message context.

### Message Property Passthrough

**All nodes preserve unrecognized input message properties in their output.**

This is implemented using the spread operator pattern:

```javascript
const outputMsg = {
    ...msg, // Spreads all input properties first
    payload: response.data, // Then overwrites specific properties
    workflowId: workflowId,
    // etc.
};
send(outputMsg);
```

**Key behaviors:**

-   Any custom properties on the input `msg` object (e.g., `msg._context`, `msg.customId`, `msg.correlationId`) are automatically copied to the output
-   Node-specific properties (like `payload`, `workflowId`, `datasetId`, `studioId`) are set/overwritten as documented
-   This enables flow-wide context tracking and message correlation without modifying node code
-   Works for all node types including monitor nodes with multiple outputs (all outputs receive the same passthrough properties)

**Common use cases:**

-   `msg._context` - Preserve context across multiple nodes in a flow
-   `msg.correlationId` - Track messages across parallel branches
-   `msg.userId` - Maintain user session information through workflow
-   Any custom metadata needed for flow logic or debugging

### Node Types

**[workflow-launch.js](nodes/workflow-launch.js):**

-   Launches pipelines via `/workflow/launch` endpoint
-   Can resolve launchpad names (fetches pipeline config from `/pipelines` then `/pipelines/{id}/launch`)
-   Supports two methods for providing parameters:
    -   `paramsKey` (Params JSON): A JSON object that gets merged into `launch.paramsText`
    -   `paramsArray` (Parameters list): Individual key-value pairs from editable list (highest precedence)
-   Sets custom `runName` if provided
-   Supports resuming workflows via `resumeWorkflowId`:
    -   Fetches workflow details from `/workflow/{id}` to get commitId
    -   Fetches launch config from `/workflow/{id}/launch` to get sessionId and resumeCommitId
    -   If workflow ran tasks (has commitId), sets `resume: true` and includes `revision` field
    -   If workflow was cancelled before tasks (no commitId), sets `resume: false` and omits `revision` field
-   Returns `msg.workflowId` for chaining with monitor node

**[workflow-monitor.js](nodes/workflow-monitor.js):**

-   Polls workflow status at configurable interval (default 5s)
-   Three outputs: Active (yellow), Succeeded (green), Failed (red)
-   Stops polling when workflow reaches terminal state or `keepPolling` is false
-   Status mapping: `submitted` → yellow, `running` → blue, `succeeded` → green, `failed` → red, `cancelled|unknown` → grey

**[dataset-add.js](nodes/dataset-add.js):**

-   Adds dataset via POST `/datasets` then uploads file via POST `/datasets/{id}/upload`
-   Supports CSV/TSV file types with MIME type selection
-   Uses `form-data` for multipart upload
-   Returns `msg.datasetId`

**[datalink-list.js](nodes/datalink-list.js):**

-   Lists files/folders from Data Explorer links via `/data-links` and `/data-browser`
-   Filters by prefix (applied to both files/folders) and pattern (regex, files only)
-   Supports recursion depth and max results
-   Returns `msg.payload.files` (full objects) and `msg.files` (string array of paths)

**[datalink-poll.js](nodes/datalink-poll.js):**

-   Automatically polls Data Link at configured intervals (default 15 min)
-   Parses frequency as seconds, `MM:SS`, `HH:MM:SS`, or `DD-HH:MM:SS`
-   Two outputs: "All results" (every poll) and "New results" (only new files detected)
-   Tracks seen files in node context to detect changes

**[studios-add.js](nodes/studios-add.js):**

-   Adds Seqera Studios via POST `/studios`
-   Configures container, compute environment, resources (CPU/memory/GPU)
-   Mounts Data Links specified in `mountData` array
-   Returns `msg.studioId`

**[studios-monitor.js](nodes/studios-monitor.js):**

-   Polls Studio status at configurable interval (default 5s) with units (seconds/minutes/hours)
-   Three outputs: All checks (every poll), Ready (running), Terminated (stopped/errored/buildFailed)
-   Stops polling when Studio reaches terminal state or `keepPolling` is false
-   Status mapping: `starting|building|stopping` → yellow, `running` → blue, `stopped` → green, `errored|buildFailed` → red
-   Output 1 fires every poll
-   Output 2 fires **only once** on transition to `running` (not on every poll while running) - uses state transition detection
-   Output 3 fires on termination
-   Tracks `previousStatus` to detect state transitions and prevent duplicate ready notifications

### HTTP Admin Endpoints

Several nodes register HTTP endpoints on Node-RED's admin API for editor features:

-   `GET /admin/seqera/pipelines/:nodeId` - Launchpad/pipeline autocomplete for workflow-launch
-   `GET /admin/seqera/datalinks/:nodeId` - Data Link autocomplete for datalink-list/poll
-   `GET /seqera-config/connectivity-check` - Test API token validity
-   `GET /seqera-config/workspaces` - Fetch organizations and workspaces for config UI

These endpoints handle cases where the node doesn't exist yet (during initial config) by extracting config from query params.

### Status Display Pattern

Nodes display status in the editor using:

```javascript
node.status({
    fill: "blue|yellow|green|red|grey",
    shape: "ring|dot",
    text: `status: ${formatDateTime()}`,
});
```

**Common pattern:**

-   Blue ring = in progress
-   Yellow ring = intermediate step
-   Green dot = success
-   Red dot = error
-   Grey dot = idle

### Error Handling

-   Use `node.error(message, msg)` to report errors to Node-RED
-   Use `node.warn(obj)` for non-fatal warnings (used in `apiCall` for API failures)
-   Always set status to red dot on error
-   Clear polling intervals on error (for monitor/poll nodes)

## Token Permissions

From README, minimum required roles:

-   Launch workflow: **Maintain**
-   Monitor workflow: **View**
-   Add Dataset: **Launch**
-   List/Poll Data Link Files: **Maintain**
-   Add Studio: **Maintain**

For full automation, use **Maintain** role token.

## Example Flows

Located in [examples/](examples/) directory. Available via Node-RED's Import > Examples menu. See [docs/examples/](docs/examples/) for detailed descriptions.

## File Organization

```
nodes/              - Node implementation files (.js + .html pairs)
  _utils.js         - Core API helper functions (buildHeaders, apiCall, etc.)
  datalink-utils.js - Data Link specific utilities (listDataLink, resolveDataLink)
  config.js         - Seqera configuration node
  workflow-*.js     - Workflow launch/monitor nodes
  dataset-*.js      - Dataset addition node
  datalink-*.js     - Data Link list/poll nodes
  studios-*.js      - Studio addition/monitor nodes
test/               - Mocha test files
  helper.js         - Shared test utilities and mock factories
  *_spec.js         - Test files for each node
examples/           - Example flows (.json)
docker/             - Dockerfiles and Node-RED config for containers
docs/               - Documentation and images
  examples/         - Example flow documentation
```

## Common Patterns When Adding New Nodes

1. Create paired `.js` and `.html` files in `nodes/`
2. In `.js`: export function receiving `RED`, define node constructor, register with `RED.nodes.registerType`
3. Reference `seqera-config` node via `node.seqeraConfig = RED.nodes.getNode(config.seqera)`
4. Use `apiCall` from `_utils.js` for all API requests
5. Implement `evalProp` helper for typedInput property evaluation (or import from `datalink-utils.js` for Data Link nodes)
6. Handle `node.on("input", async function(msg, send, done))` for message-triggered nodes
7. Use `node.status()` to update visual state in editor
8. Register node in [package.json](package.json) under `node-red.nodes`
9. Create corresponding HTML with `<script type="text/html" data-template-name="...">` for editor UI
10. Add tests in `test/<node-name>_spec.js` using shared helpers from `test/helper.js`