@uipath/flow-tool 0.1.5

package/README.md

@@ -0,0 +1,380 @@
+# @uipath/flow-tool
+
+CLI tool for managing UiPath Flow processes and jobs. This is a uip plugin that provides Flow-related commands.
+
+## Commands
+
+### `flow init`
+
+Create a new Flow project with boilerplate files.
+
+```bash
+uip flow init <projectName> [--force]
+```
+
+### `flow validate`
+
+Validate a `.flow` file against the Flow schema (Zod-based) with structural cross-field checks.
+
+```bash
+uip flow validate <flowFile>
+```
+
+### `flow pack`
+
+Pack a Flow project into a NuGet package (`.nupkg`).
+
+```bash
+uip flow pack <projectPath> <outputPath> [-n <name>] [-v <version>]
+```
+
+### Known Issues
+
+> **Solution integration with Flow projects is currently broken.**
+>
+> The `flow init`, `flow validate`, and `flow pack` commands work correctly on their own. However, when a Flow project is added to a solution via `uip solution project add` and then packed with `uip solution pack`, the resulting `.nupkg` inside the solution zip is **missing critical files** (`.bpmn`, `.flow`, `entry-points.json`, `bindings_v2.json`).
+>
+> **Root cause:** The published `@uipath/tool-flow` npm package has a non-recursive `copyFiles()` method that only copies top-level files from the project directory, silently skipping the `content/` and `flow_files/` subdirectories. The local `flow-pack-service.ts` correctly uses `copyDirectory()` for recursive copies, but the npm-published tool does not.
+>
+> **Workaround:** Use `uip flow pack` directly to produce a correct `.nupkg` for deployment.
+
+### Flow Process Commands
+
+#### `flow process list`
+
+List available Flow processes.
+
+```bash
+uip flow process list
+```
+
+#### `flow process get`
+
+Get Flow process schema and details.
+
+```bash
+uip flow process get "<process-key>" "<feed-id>"
+
+# Example
+uip flow process get "MyFlow.flow.Flow:1.0.0" "6d98ceb8-becb-46ec-80d7-df213fbec06c"
+```
+
+#### `flow process run`
+
+Run a Flow process.
+
+**Syntax:**
+
+```bash
+uip flow process run "<process-key>" "<folder-key>" [options]
+```
+
+**Arguments:**
+
+- `<process-key>` - Process package key with version (e.g., `MyFlow.flow.Flow:1.0.0`)
+- `<folder-key>` - Folder key (GUID)
+
+**Options:**
+
+- `-i, --inputs <json>` - Input parameters as JSON string or @file.json
+- `-t, --tenant <name>` - Tenant name (defaults to authenticated tenant)
+- `--release-key <key>` - Release key (GUID, from list command)
+- `--folder-id <id>` - Folder ID (from list command)
+- `--feed-id <id>` - Feed ID for package lookup (optional)
+- `--robot-ids <ids>` - Comma-separated robot IDs (optional)
+- `--validate` - Validate inputs against project schema before running
+
+**Examples:**
+
+```bash
+# Run with JSON inputs
+uip flow process run "TestFlow.flow.Flow:1.0.0" "folder-guid-here" \
+  --release-key "release-guid" \
+  --folder-id "2553016" \
+  --inputs '{"name": "John", "age": 30}'
+
+# Run with inputs from file
+uip flow process run "TestFlow.flow.Flow:1.0.0" "folder-guid-here" \
+  --release-key "release-guid" \
+  --folder-id "2553016" \
+  --inputs @inputs.json
+
+# Run with piped inputs
+echo '{"name": "John", "age": 30}' | \
+  uip flow process run "TestFlow.flow.Flow:1.0.0" "folder-guid-here" \
+  --release-key "release-guid" \
+  --folder-id "2553016"
+```
+
+### Flow Job Commands
+
+#### `flow job traces`
+
+Stream execution traces for a running job.
+
+```bash
+uip flow job traces "<job-key>" [options]
+
+# Options:
+# --poll-interval <ms>  - Polling interval in milliseconds (default: 2000)
+# --traces-service <name> - Traces service name (default: llmopstenant_)
+
+# Example
+uip flow job traces "06478292-f9cf-4234-9d1b-03f4bcd95fed"
+```
+
+#### `flow job status`
+
+Get detailed status of a Flow job.
+
+```bash
+uip flow job status "<job-key>" --folder-id "<id>" [options]
+
+# Options:
+# --detailed  - Show full response with all fields
+
+# Example
+uip flow job status "06478292-f9cf-4234-9d1b-03f4bcd95fed" --folder-id "2553016"
+```
+
+## Complete Workflow
+
+```bash
+# 1. List available processes
+uip flow process list
+
+# 2. Get process schema (to see required inputs)
+uip flow process get "MyFlow.flow.Flow:1.0.0" "feed-id-from-list"
+
+# 3. Run the process
+JOB_KEY=$(uip flow process run "MyFlow.flow.Flow:1.0.0" "folder-key" \
+  --release-key "release-key" \
+  --folder-id "2553016" \
+  --inputs '{}' 2>/dev/null)
+
+# 4. Watch execution traces
+uip flow job traces "$JOB_KEY"
+
+# 5. Check final status
+uip flow job status "$JOB_KEY" --folder-id "2553016"
+```
+
+## Output
+
+**Process list**: JSON array with process metadata
+**Process get**: JSON with entry points and schemas
+**Process run**: Job key on stdout, next steps on stderr
+**Job traces**: JSON trace events (one per line) on stdout
+**Job status**: JSON with job details (14 fields default, full with --detailed)
+
+**Exit codes:**
+
+- `0` - Success
+- `1` - Failure or error
+
+## Flow Registry Commands
+
+`flow registry` commands let you browse, search, and inspect the Flow node registry — the building blocks used inside UiPath Flow processes. Nodes include OOTB activities (`uipath.agent`, `uipath.http`, etc.) and connector nodes that call third-party APIs (Slack, Salesforce, etc.). When logged in, the registry also includes connector nodes installed in your tenant.
+
+| Command                           | Description                                                                    |
+| --------------------------------- | ------------------------------------------------------------------------------ |
+| `flow registry pull`              | Fetch and cache all available nodes from the Flow registry                     |
+| `flow registry list`              | List all locally cached nodes                                                  |
+| `flow registry search [keyword]`  | Find nodes by keyword and/or structured filters                                |
+| `flow registry get <nodeType>`    | Get full node schema; auto-enriches connector nodes with input/output fields   |
+
+---
+
+### `flow registry pull`
+
+Fetches the node registry and writes it to local cache. Subsequent commands (`list`, `search`, `get`) read from this cache.
+
+```bash
+uip flow registry pull
+uip flow registry pull --force   # bypass 30-minute cache, always refresh
+```
+
+**Output fields:**
+
+| Field         | Description                                             |
+| ------------- | ------------------------------------------------------- |
+| `NodesCount`  | Number of nodes cached                                  |
+| `FromCache`   | `true` if the cached copy was used without fetching     |
+| `AgeMinutes`  | Cache age in minutes (only when `FromCache: true`)      |
+| `Source`      | `"ootb"` (unauthenticated) or `"authenticated"` (tenant-specific) |
+| `CacheWritten` | `true` if cache was updated on this run                |
+| `Message`     | Human-readable status                                   |
+
+**Cache behaviour:**
+
+- Cache expires after 30 minutes. Expired or missing cache triggers a live fetch.
+- When not logged in, OOTB nodes are returned without updating the cache.
+- On authenticated fetch failure, falls back to OOTB nodes without updating the cache.
+
+---
+
+### `flow registry list`
+
+Lists all nodes in the local cache. If no cache exists, fetches live data first.
+
+```bash
+uip flow registry list
+```
+
+**Output fields:** `NodesCount`, `Nodes[]`
+
+---
+
+### `flow registry search`
+
+Searches for nodes by keyword and/or structured filters.
+
+```bash
+uip flow registry search slack
+uip flow registry search slack --filter "displayname:contains=send message"
+uip flow registry search --filter "category=connector"
+```
+
+**Options:**
+
+| Option            | Description                                                    |
+| ----------------- | -------------------------------------------------------------- |
+| `[keyword]`       | Searches across `nodeType`, `category`, `tags`, `display.label` |
+| `--filter <expr>` | Structured filter (see filter syntax below)                    |
+
+At least one of `keyword` or `--filter` is required.
+
+**Output fields:** `Keyword`, `Filters`, `ResultCount`, `Nodes[]`
+
+**Filter syntax:**
+
+```text
+field=value                           # equality
+field:operator=value                  # operator variant
+field1=value1,field2=value2           # AND conditions
+```
+
+| Field aliases                                    | Operators                                                       |
+| ------------------------------------------------ | --------------------------------------------------------------- |
+| `category`, `cat`                                | `equals` (default), `contains`, `startsWith`, `endsWith`, `in` |
+| `type`, `nodetype`                               |                                                                 |
+| `tags`, `tag`                                    |                                                                 |
+| `displayname`, `display_name`, `name`, `label`   |                                                                 |
+
+Examples:
+
+```bash
+# Connector nodes only
+--filter "category=connector"
+
+# Display name contains "slack"
+--filter "displayname:contains=slack"
+
+# Tagged with "ai" or "automation"
+--filter "tags:in=ai,automation"
+
+# Combined: connector AND display name contains "invite"
+--filter "category=connector,displayname:contains=invite"
+```
+
+---
+
+### `flow registry get`
+
+Returns full details for a single node, looked up by `nodeType` (case-insensitive).
+
+```bash
+uip flow registry get "uipath.agent"
+uip flow registry get "uipath.connector.slack.send-message"
+```
+
+**Output fields:** `Node` (enriched FlowNode object)
+
+**Connector enrichment:**
+
+For nodes tagged `"connector"`, `registry get` automatically calls the Integration Service API to fetch input and output field definitions and attach them to the result:
+
+- `inputDefinition.fields[]` — fields for the request body
+- `outputDefinition.fields[]` — fields returned by the action
+
+Each field contains:
+
+| Property      | Description                                                              |
+| ------------- | ------------------------------------------------------------------------ |
+| `name`        | JSON key for the request/response                                        |
+| `displayName` | Human-readable label                                                     |
+| `type`        | Data type (`string`, `boolean`, `integer`, etc.)                         |
+| `required`    | `true` if mandatory (input fields only)                                  |
+| `description` | What the field does                                                      |
+| `enum`        | Allowed values (if restricted)                                           |
+| `reference`   | Object reference metadata — field expects an ID, not a plain name        |
+| `responseOnly` | `true` on all output fields                                             |
+
+Enrichment requires login. If the IS call fails or the node is not a connector, the node is returned unchanged.
+
+---
+
+### JMESPath output filtering
+
+All commands support `--output-filter <expression>` (global option) to extract specific values from the output. The expression is a [JMESPath](https://jmespath.org/) query evaluated against the `Data` field of the JSON response, so top-level keys are the output fields listed above.
+
+```bash
+# List all nodeTypes from a search
+uip flow registry search slack --output-filter "Nodes[*].nodeType"
+
+# Get the full enriched node
+uip flow registry get "uipath.connector.slack.send-message" \
+  --output-filter "Node"
+
+# Extract only the input fields
+uip flow registry get "uipath.connector.slack.send-message" \
+  --output-filter "Node.inputDefinition.fields"
+
+# Get the node count after a pull
+uip flow registry pull --output-filter "NodesCount"
+```
+
+Combine with `--format json` to get clean JSON output:
+
+```bash
+uip flow registry get "uipath.connector.slack.send-message" \
+  --output-filter "Node.inputDefinition.fields" --format json
+```
+
+---
+
+### Registry command workflow
+
+```bash
+# 1. Pull the registry (once per session)
+uip flow registry pull
+
+# 2. Search for candidates
+uip flow registry search slack --filter "displayname:contains=send" \
+  --output-filter "Nodes[*].nodeType"
+# → uipath.connector.slack.send-message
+#   uipath.agent.resource.tool.connector.slack.send-message
+# Pick the uipath.connector.* variant for direct flow use.
+
+# 3. Inspect the full schema (with IS enrichment if logged in)
+uip flow registry get "uipath.connector.slack.send-message" --format json
+
+# 4. Extract just the input fields to build a request body
+uip flow registry get "uipath.connector.slack.send-message" \
+  --output-filter "Node.inputDefinition.fields" --format json
+```
+
+---
+
+## Development
+
+```bash
+# Build
+bun run build
+
+# Test
+bun test
+
+# Lint
+bun run lint
+```