diff --git a/skills/uipath-rpa/SKILL.md b/skills/uipath-rpa/SKILL.md index 3bda52c1..bebcb6e5 100644 --- a/skills/uipath-rpa/SKILL.md +++ b/skills/uipath-rpa/SKILL.md @@ -43,11 +43,11 @@ Before doing any work, check if `.claude/rules/project-context.md` exists in the - `AGENTS.md` at project root — read by UiPath Autopilot in Studio Desktop. If `AGENTS.md` already exists, look for `` / `` markers and replace only between them; if no markers exist, append the fenced block at the end 4. Then proceed with the skill workflow -## Step 0: Resolve PROJECT_DIR and Environment +## Step 0: Resolve PROJECT_DIR -Before creating or modifying anything, determine which project to work with and ensure Studio is running. See [references/environment-setup.md](references/environment-setup.md) for the full procedure. +Before creating or modifying anything, determine which project to work with. See [references/environment-setup.md](references/environment-setup.md) for the full procedure. -**Quick check:** Find `project.json` to establish `{projectRoot}`, run `uip rpa list-instances --output json` to verify Studio, and `uip rpa open-project` if needed. +**Quick check:** Find `project.json` to establish `{projectRoot}`. That's it — no Studio Desktop check needed. `uip rpa` auto-launches a headless Studio (UiPath.Studio.Helm NuGet) on first call. Studio Desktop is required only for `diff` and `focus-activity`. ## Project Type Detection @@ -86,7 +86,7 @@ For the full decision flowchart, InvokeCode extraction rules, and detailed hybri ### Common Rules (Both Modes) -1. **NEVER create a project without confirming none exists.** Follow Step 0 resolution: check explicit path, project name, running Studio instances, then CWD. Only create when confirmed no project matches AND user explicitly requests creation. +1. **NEVER create a project without confirming none exists.** Follow Step 0 resolution: check explicit path, project name, then CWD for `project.json`. Only create when confirmed no project matches AND user explicitly requests creation. 2. **ALWAYS use `uip rpa create-project`** to create new projects — never write `project.json` or scaffolding manually. 3. **ALWAYS list project analyzer rules before generating workflows, validate files as you go, AND verify the project builds before declaring done.** Three-phase validation: - **Pre-generation** (before creating or editing any workflow file — `.cs` with `[Workflow]`/`[TestCase]`, or `.xaml`): `uip rpa get-analyzer-rules --project-dir "" --output json` to list the enabled Workflow Analyzer rules. Apply every `error` and `warning` rule during authoring so generated code passes `analyze` and `build` on the first attempt. Run once at the start of the task; re-run only when project dependencies change (a newly added package can ship its own `MA-*` rules). diff --git a/skills/uipath-rpa/references/cli-reference.md b/skills/uipath-rpa/references/cli-reference.md index 66e89e0d..616311a9 100644 --- a/skills/uipath-rpa/references/cli-reference.md +++ b/skills/uipath-rpa/references/cli-reference.md @@ -4,6 +4,28 @@ CLI reference for `uip rpa` -- communicates with UiPath Studio over named pipes > **Installation is automatic.** Do NOT attempt to install `uip` manually or instruct the user to install it. +## Studio Desktop vs headless Studio (Helm) + +`uip rpa` connects to one of two flavors of Studio behind the same IPC contract: + +- **Headless Studio (Helm) — default.** Ships as a NuGet package (`UiPath.Studio.Helm.{Platform}`) and auto-launches on first use. **No Studio Desktop install needed.** First call on a cold NuGet cache may sit near-silent for 30–90 s while `dotnet restore` runs; raise `--timeout` to ≥ 180 for that call. +- **Studio Desktop.** The interactive UI. Used automatically only by commands with UI side effects. + +### Which commands need Studio Desktop + +Only these two — they do not work headless: + +| Command | Why | +|---------|-----| +| `uip rpa diff` | Opens an interactive diff window in Studio's UI | +| `uip rpa focus-activity` | Highlights an activity in Studio's active workflow designer | + +For these, run `uip rpa start-studio --project-dir ""` first if Studio Desktop is not already up. + +Everything else — `create-project`, `open-project`, `close-project`, `run-file`, `stop-execution`, `get-errors`, `build`, `get-analyzer-rules`, `find-activities`, `get-default-activity-xaml`, `get-versions`, `inspect-package`, `install-or-update-packages`, `list-data-fabric-entities`, `install-data-fabric-entities`, `search-templates`, `indicate-application`, `indicate-element`, all `uia` subcommands, all `uip is` subcommands — runs headless with no Studio Desktop required. + +To force Studio Desktop for any command, set `UIPATH_RPA_TOOL_USE_STUDIO=1`. Not recommended for the standard authoring loop. + > **This guide may not list every available command.** The CLI is self-documenting -- append `--help` at any level to progressively discover commands, subcommands, and parameters: ```bash @@ -21,8 +43,8 @@ Every `uip rpa` invocation accepts these flags: | Option | Description | Default | |--------|-------------|---------| | `--project-dir ` | Project directory to match against running Studio instances | Current working directory | -| `--studio-dir ` | Path to Studio installation directory | Auto-detected (see below) | -| `--timeout ` | Timeout in seconds for Studio resolution | `300` | +| `--studio-dir ` | Path to Studio Desktop installation (only used when Studio Desktop is in use) | Auto-detected (see below) | +| `--timeout ` | Timeout in seconds for Studio resolution (raise to ≥ 180 on a cold Helm NuGet cache) | `300` | | `--verbose` | Enable verbose/debug logging | Off | | `--output ` | Output format: `json`, `table`, `yaml`, `plain` | `table` | @@ -30,13 +52,13 @@ Every `uip rpa` invocation accepts these flags: ### STUDIO_DIR Resolution -`--studio-dir` is optional -- omit it by default and let `uip` auto-detect Studio. Only provide it explicitly if auto-detection fails, using the first match: +`--studio-dir` is **only consulted when Studio Desktop is in use** (i.e. you ran `start-studio`, called `diff`/`focus-activity`, or set `UIPATH_RPA_TOOL_USE_STUDIO=1`). Headless Studio (Helm) ignores it. When Studio Desktop is needed and auto-detection fails, the resolution waterfall is: 1. Environment variable `UIPATH_STUDIO_DIR` if set. 2. Default install: `C:\Program Files\UiPath\Studio` (or `x86` variant) if `UiPathStudio.exe` exists there. 3. Dev build: Studio source tree build output (e.g. `\Output\bin\Debug`). -> **Error `"Studio X.X.X does not have interop support"` or `"Requires Studio 26.2+"`** means the detected Studio is too old. Stop calling `uip rpa` commands and inform the user to update Studio. +> **Error `"Studio X.X.X does not have interop support"` or `"Requires Studio 26.2+"`** means the detected Studio Desktop is too old. This affects only the two Studio-only tools (`diff`, `focus-activity`) and any explicitly forced Studio runs. Inform the user to update Studio Desktop. ### PROJECT_DIR Resolution @@ -59,22 +81,24 @@ Located at `{projectRoot}/.local/docs/packages/{PackageId}/`. --- -## Commands -- Studio Management +## Commands -- Studio Desktop Management (edge cases only) + +> Skip this section unless you need to invoke `diff` or `focus-activity`. Every other command auto-launches headless Studio (Helm) when needed. ### list-instances -List running UiPath Studio instances and their IPC status. +List running Studio Desktop instances and their IPC status. Hidden diagnostic command — does **not** report the auto-launched headless Studio (Helm) instances. ```bash uip rpa list-instances --output json``` -No command-specific options. +No command-specific options. An empty `Data` array does NOT mean `uip rpa` won't work — headless Studio starts on demand. --- ### start-studio -Ensure a Studio instance is running. Resolution waterfall: +Ensure a **Studio Desktop** instance is running. Only required before invoking `diff` or `focus-activity`, or when forcing Studio Desktop with `UIPATH_RPA_TOOL_USE_STUDIO=1`. Resolution waterfall: 1. Match by `--project-dir` -- reuse if available, wait if busy 2. Use an idle instance (no project loaded) 3. Start a new instance via `--studio-dir` -- poll until available @@ -106,7 +130,7 @@ uip rpa create-project --name "" --location "" --output json`` ### open-project -Open an existing project in Studio. Only needed when explicitly loading a project that isn't already open (e.g. after `create-project`, or when switching projects). Most commands (`validate`, `run-file`) auto-resolve a Studio instance, so this is rarely required. +Open an existing project in Studio. Only needed when explicitly loading a project that isn't already open (e.g. after `create-project`, or when switching projects). Most commands (`validate`, `run-file`) auto-resolve a Studio instance and open the project automatically, so this is rarely required. ```bash uip rpa open-project --project-dir "" --output json``` @@ -476,11 +500,11 @@ When `uip` commands fail, diagnose by error category: | Error Pattern | Cause | Recovery | |---------------|-------|----------| -| `"connection refused"`, `"EPIPE"`, `"pipe not found"` | Studio IPC not available | Run `uip rpa start-studio`, then `uip rpa open-project --project-dir "..."` | -| `"timeout"`, `"ETIMEDOUT"` | Command took too long | Increase timeout: `uip rpa --timeout 600 `, or use `--skip-validation` for `get-errors` | +| `"connection refused"`, `"EPIPE"`, `"pipe not found"` | Studio IPC not available. Headless Studio (Helm): NuGet restore failed or process exited. Studio Desktop: not running. | Re-run the command — headless Studio relaunches automatically. If it persists, raise `--timeout` and check the Helm restore output for NuGet errors. Only run `uip rpa start-studio` if the failing command is `diff`/`focus-activity` or `UIPATH_RPA_TOOL_USE_STUDIO=1` is set. | +| `"timeout"`, `"ETIMEDOUT"` | Command took too long. Cold Helm NuGet restore can take 30–90 s. | Raise the timeout: `uip rpa --timeout 600 `. For `get-errors`, also try `--skip-validation`. | | `"not authenticated"`, `401`, `403` | Auth required for cloud features | Run `uip login` and re-try | | `"package not found"`, `"version not available"` | Wrong package ID or version | Verify package name via `uip rpa find-activities`; omit `version` to auto-resolve latest | -| `"project not found"`, `"no project open"` | Wrong project-dir or project not open | Verify `--project-dir` path, run `uip rpa open-project` | +| `"project not found"`, `"no project open"` | Wrong project-dir or project not open in Studio | Verify `--project-dir` path, run `uip rpa open-project` | | `"file not found"` in `get-errors` | Wrong `--file-path` (must be relative to project) | Use path relative to project root, not absolute | | `"Studio is busy"`, `"operation in progress"` | Studio is processing a previous request | Wait a few seconds and retry the command | | Any unrecognized error | Unknown | Check `--verbose` flag: `uip rpa --verbose ` for debug details, inform the user | @@ -554,7 +578,7 @@ uip rpa get-workflow-example --key "" --output json``` ### focus-activity -Focus an activity in the Studio designer view. +Focus an activity in the Studio Desktop designer view. **Requires a running Studio Desktop instance** — does not work against headless Studio. Run `uip rpa start-studio --project-dir ""` first if Studio Desktop is not already up. ```bash uip rpa focus-activity --activity-id "" --output jsonuip rpa focus-activity --output json``` diff --git a/skills/uipath-rpa/references/coded/coding-guidelines.md b/skills/uipath-rpa/references/coded/coding-guidelines.md index 39c65877..a79d97e1 100644 --- a/skills/uipath-rpa/references/coded/coding-guidelines.md +++ b/skills/uipath-rpa/references/coded/coding-guidelines.md @@ -120,7 +120,7 @@ if (system.PathExists(@"C:\Reports\report.pdf", PathType.File, out ILocalResourc - **Escape backslashes in paths** — Use `C:\\path\\file.txt` not `C:\path\file.txt` in input arguments ### Validation Loop (Critical Rule #14) -uip rpa get-errors --file-path "" --project-dir "" --studio-dir "" --output json +uip rpa get-errors --file-path "" --project-dir "" --output json @../validation-guide.md ### Error Handling @@ -197,12 +197,12 @@ C) | Issue | Cause | Fix | |-------|-------|-----| -| **"Studio X.X.X does not have interop support"** | Auto-detected Studio is too old (< 26.2) | Always pass `--studio-dir ""` pointing to the dev build | -| **No Studio instances found** | Studio is not running | Run `uip rpa start-studio --project-dir "" --studio-dir ""` | -| **Stale pipe / ENOENT** | Studio instance crashed or was closed | The tool retries automatically; if persistent, restart Studio | +| **"Studio X.X.X does not have interop support"** | Surfaces only when running against Studio Desktop and the auto-detected install is too old (< 26.2). Headless Studio is unaffected. | Pass `--studio-dir ""` pointing to a 26.2+ build, or drop the Studio Desktop override and let the command run headless | +| **No Studio instances found** | Only relevant for `diff` / `focus-activity` — they need Studio Desktop. Every other command runs headless and doesn't need a Desktop instance. | Run `uip rpa start-studio --project-dir ""` if you actually need Studio Desktop; otherwise re-run the command — headless Studio relaunches automatically | +| **Stale pipe / ENOENT** | Studio instance crashed or was closed | The tool retries automatically; if persistent, re-run the command (headless) or restart Studio Desktop | | **Workflow cannot be found** | Entrypoint not in project.json | Verify project.json entrypoint has the file listed (Process projects only — Tests and Library projects do not use `entryPoints`) | | **Service property not available** | Missing package dependency | Add required package to project.json dependencies | -| **Timeout** | Studio took too long to start | Increase timeout: `--timeout 600` | +| **Timeout** | Studio took too long to start. First headless call on a cold NuGet cache can take 30–90 s. | Increase timeout: `--timeout 600` | | **"Target name 'X' is not part of the current screen"** | Element descriptor used on wrong screen handle | Use the `UiTargetApp` handle from `Open`/`Attach` for the screen that owns the element | | **"Cannot select item. It was not found among existing items"** | `SelectItem` fails on web dropdowns | Use `TypeInto` instead of `SelectItem` for web `