@uipath/skills 1.195.0

package/skills/uipath-coded-apps/references/commands-reference.md

@@ -0,0 +1,284 @@
+# Coded App CLI Command Reference
+
+Complete reference for all `uip codedapp` subcommands.
+
+## Prerequisites
+
+- **Authentication**: Run `uip login` before using cloud commands (auth is handled by the `uip` CLI, not the codedapp tool)
+- **Installation**: `uip tools install @uipath/codedapp-tool`
+- **Command prefix**: All commands are under `uip codedapp <command>`
+
+## `uip codedapp push`
+
+Push local source code to Studio Web. Uploads the build output directory and optionally imports referenced resources.
+
+If no project ID is provided, the command **interactively prompts** to create a new Coded App project. The newly created `UIPATH_PROJECT_ID` is saved to `.env`.
+
+```bash
+uip codedapp push [project-id] [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `[project-id]` | WebApp Project ID | From `UIPATH_PROJECT_ID` env var |
+| `--build-dir <dir>` | Build output directory | `dist` |
+| `--ignore-resources` | Skip importing referenced resources | `false` |
+| `--base-url <url>` | UiPath base URL | From `.env` |
+| `--org-id <id>` | Organization ID | From `.env` |
+| `--tenant-id <id>` | Tenant ID | From `.env` |
+| `--access-token <token>` | Access token | From `.env` |
+
+**Examples:**
+
+```bash
+# Push using project ID from .env
+uip codedapp push
+
+# Push with explicit project ID
+uip codedapp push my-project-id
+
+# Push a custom build directory
+uip codedapp push my-project-id --build-dir build
+
+# Push without importing resources
+uip codedapp push --ignore-resources
+```
+
+**Auto-create project flow:**
+```
+? No project ID found. Create a new Coded App project? (Y/n)
+? Enter a name for the new Coded App: my-webapp
+✔ Created coded app project "my-webapp" with ID: abc-123-def
+  Saved UIPATH_PROJECT_ID to .env
+```
+
+**API endpoints:**
+- Push files: `POST /{org}/studio_/backend/api/Project/{projectId}/FileOperations`
+- Create project: `POST /{org}/studio_/backend/api/Solution`
+
+---
+
+## `uip codedapp pull`
+
+Pull project files from Studio Web to your local machine.
+
+```bash
+uip codedapp pull [project-id] [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `[project-id]` | WebApp Project ID | From `UIPATH_PROJECT_ID` env var |
+| `--overwrite` | Allow overwriting existing local files without prompting | `false` |
+| `--target-dir <dir>` | Local directory to write pulled files | Current directory |
+| `--base-url <url>` | UiPath base URL | From `.env` |
+| `--org-id <id>` | Organization ID | From `.env` |
+| `--tenant-id <id>` | Tenant ID | From `.env` |
+| `--access-token <token>` | Access token | From `.env` |
+
+**Examples:**
+
+```bash
+# Pull using project ID from .env
+uip codedapp pull
+
+# Pull with explicit project ID
+uip codedapp pull my-project-id
+
+# Pull to a specific directory
+uip codedapp pull my-project-id --target-dir ./my-app
+
+# Pull and overwrite without prompting
+uip codedapp pull --overwrite
+```
+
+**API endpoint:** `GET /{org}/studio_/backend/api/Project/{projectId}/FileOperations`
+
+---
+
+## `uip codedapp pack`
+
+Package the app build output into a `.nupkg` file for publishing. Generates all required UiPath metadata files and bundles them with app content.
+
+```bash
+uip codedapp pack <dist> [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `<dist>` | Path to build output directory | **Required** |
+| `-n, --name <name>` | Package name | Prompted interactively |
+| `-v, --version <version>` | Package version | `1.0.0` |
+| `-o, --output <dir>` | Output directory for `.nupkg` | `./.uipath` |
+| `-a, --author <author>` | Package author | `UiPath Developer` |
+| `--description <desc>` | Package description | Prompted |
+| `--main-file <file>` | Main entry file | `index.html` |
+| `--content-type <type>` | Content type: `webapp`, `library`, `process` | `webapp` |
+| `--dry-run` | Preview packaging without creating the file | `false` |
+| `--reuse-client` | Reuse existing clientId from uipath.json | `false` |
+| `--base-url <url>` | UiPath base URL | From `.env` |
+| `--org-id <id>` | Organization ID | From `.env` |
+| `--tenant-id <id>` | Tenant ID | From `.env` |
+| `--access-token <token>` | Access token | From `.env` |
+
+**Examples:**
+
+```bash
+# Pack the dist directory (interactive prompts for name)
+uip codedapp pack dist
+
+# Pack with explicit name and version
+uip codedapp pack dist -n my-webapp --version 2.0.0
+
+# Pack to a custom output directory
+uip codedapp pack dist -o ./packages
+
+# Preview packaging without creating the file
+uip codedapp pack dist --dry-run
+
+# Pack with all options
+uip codedapp pack dist -n my-webapp --version 1.0.0 -a "My Team" --description "Production app" --main-file app.html
+```
+
+**Output:**
+```
+Package Details:
+  Name: my-webapp
+  Version: 1.0.0
+  Type: webapp
+  Location: ./.uipath/my-webapp.1.0.0.nupkg
+```
+
+**Generated metadata files** (inside `.nupkg`):
+- `operate.json` — Runtime configuration
+- `bindings.json` / `bindings_v2.json` — Resource bindings
+- `entry-points.json` — API entry point definitions
+- `package-descriptor.json` — Package file mapping
+
+---
+
+## `uip codedapp publish`
+
+Publish a `.nupkg` to UiPath Orchestrator **and** register the coded app with the Apps service. Combines upload and registration into a single step.
+
+```bash
+uip codedapp publish [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-n, --name <name>` | Package name (non-interactive selection) | Auto-select or prompted |
+| `-v, --version <version>` | Package version (requires `--name`) | Latest |
+| `-t, --type <type>` | App type: `Web` or `Action` | `Web` |
+| `--uipath-dir <dir>` | Directory containing `.nupkg` files | `./.uipath` |
+| `--base-url <url>` | UiPath base URL | From `.env` |
+| `--org-id <id>` | Organization ID | From `.env` |
+| `--tenant-id <id>` | Tenant ID | From `.env` |
+| `--tenant-name <name>` | Tenant name (required for registration) | From `.env` |
+| `--access-token <token>` | Access token | From `.env` |
+
+**Examples:**
+
+```bash
+# Publish (auto-selects if only one .nupkg exists)
+uip codedapp publish
+
+# Publish a specific package by name
+uip codedapp publish -n my-webapp
+
+# Publish a specific version
+uip codedapp publish -n my-webapp --version 2.0.0
+
+# Publish as an Action app type
+uip codedapp publish -t Action
+
+# Publish from a custom directory
+uip codedapp publish --uipath-dir ./packages
+```
+
+**Output:**
+```
+✔ Package uploaded successfully
+✔ Coded app registered successfully
+
+Published App Details:
+  Name: my-webapp
+  Version: 1.0.0
+  System Name: my-webapp_abc123
+```
+
+**Side effect:** Creates `.uipath/app.config.json` with registration metadata.
+
+**API endpoints:**
+- Upload: `POST /{org}/{tenant}/orchestrator_/odata/Processes/UiPath.Server.Configuration.OData.UploadPackage()`
+- Register: `POST /{org}/apps_/default/api/v1/default/models/apps/codedapp/publish`
+
+---
+
+## `uip codedapp deploy`
+
+Deploy or upgrade a coded app in UiPath. Automatically detects whether to perform a fresh deployment or upgrade.
+
+- **Fresh deploy**: App has not been deployed before → deploys version 1
+- **Upgrade**: App is already deployed → upgrades to the latest published version
+
+App name is resolved from: `--name` flag → `.uipath/app.config.json` → interactive prompt.
+
+```bash
+uip codedapp deploy [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-n, --name <name>` | App name | From `.uipath/app.config.json` or prompted |
+| `-v, --version <version>` | Target a specific **published** version (different semantic from `pack`/`publish` `-v`, which is the package version) | Latest |
+| `--base-url <url>` | UiPath base URL | From `.env` |
+| `--org-id <id>` | Organization ID | From `.env` |
+| `--org-name <name>` | Organization name (used for app URL) | From `.env` |
+| `--tenant-id <id>` | Tenant ID | From `.env` |
+| `--folder-key <key>` | UiPath folder key | From `UIPATH_FOLDER_KEY` env var |
+| `--access-token <token>` | Access token | From `.env` |
+
+**Examples:**
+
+```bash
+# Deploy (uses app name from .uipath/app.config.json)
+uip codedapp deploy
+
+# Deploy with explicit app name
+uip codedapp deploy -n my-webapp
+
+# Deploy with folder key
+uip codedapp deploy -n my-webapp --folder-key my-folder-key
+```
+
+**Fresh deploy output:**
+```
+  App Name: my-webapp
+  Version: 1.0.0
+  App URL: https://cloud.uipath.com/myorg/apps_/my-webapp
+```
+
+**Upgrade output:**
+```
+  App Name: my-webapp
+  Version: 2.0.0
+  App URL: https://cloud.uipath.com/myorg/apps_/my-webapp
+```
+
+**API endpoints:**
+- New deploy: `POST /{org}/apps_/default/api/v1/default/models/{systemName}/publish/versions/1/deploy`
+- Upgrade: `POST /{org}/apps_/default/api/v1/default/models/deployed/apps/updateToLatestAppVersionBulk`
+
+---
+
+## Common Options
+
+All cloud commands accept these override options (values default to `.env` file):
+
+| Option | Description |
+|--------|-------------|
+| `--base-url <url>` | UiPath base URL |
+| `--org-id <id>` | Organization ID |
+| `--tenant-id <id>` | Tenant ID |
+| `--access-token <token>` | Access token |

package/skills/uipath-coded-apps/references/create-action-app.md

@@ -0,0 +1,344 @@
+# Create a UiPath Coded Action App
+
+Scaffold a production-ready UiPath Coded Action App — a React form component rendered inside UiPath Action Center as part of a Maestro or Agent automation workflow.
+
+## What Is a Coded Action App?
+
+When an automation creates a human task (via `CreateFormTask` or similar), the assigned action app is rendered in Action Center for the reviewer. The app:
+- Receives input data from the automation (read-only)
+- Collects output data from the reviewer (editable)
+- Submits with an outcome button (e.g., Approve, Reject)
+
+The data contract is defined in `action-schema.json`.
+
+---
+
+## Pre-flight: Collect Required Information
+
+Ask these questions **one at a time, in order**. Do not start writing files until all answers are collected.
+
+### Q1 — App name
+> "What is the name of your action app? This will be the project folder name (e.g., `loan-review-app`)."
+
+Convert to lowercase kebab-case. Store as `<app-name>`.
+
+### Q2 — Routing name
+> "What routing name should this app use in Action Center? This becomes the URL path (e.g., `loan-review`). Lowercase letters, digits, and hyphens only. 4–32 characters."
+
+Auto-convert spaces/underscores to hyphens and uppercase to lowercase. Validate the pattern and length. Confirm the final value. Store as `<routing-name>`.
+
+### Q3 — SDK services (optional)
+
+From the user's **request**, determine whether the app needs to call UiPath platform services (Data Fabric, Orchestrator, Buckets, etc.). Do **not** ask the user to pick from a list.
+
+If services are needed: read [oauth-scopes.md](oauth-scopes.md) to determine the required scopes, then proceed to Q3a.
+
+If no platform services are apparent from the request: skip to Q4. No SDK setup needed beyond `@uipath/coded-action-app`.
+
+After deducing scopes, present them to the user:
+> "Based on your request, the required OAuth scopes are: `<scopes>`. Reply ok to use these, or tell me what to change."
+
+### Q3a — Environment (only if SDK needed)
+
+Ask:
+> "Which UiPath environment are you targeting? `cloud` (production), `staging`, or `alpha`?"
+
+Map the answer to the cloud host:
+
+| Environment | Cloud Host |
+|---|---|
+| cloud | `https://cloud.uipath.com` |
+| staging | `https://staging.uipath.com` |
+| alpha | `https://alpha.uipath.com` |
+
+Store the cloud host as `<cloud-host>`. This value is used to build the redirect URI in Q3b — **do not** skip this step and default to `https://cloud.uipath.com`, or staging/alpha users will register a redirect URI that never matches at runtime.
+
+### Q3b — Client ID (only if SDK needed)
+
+Ask:
+> "Do you have an existing OAuth External Application client ID?
+> It needs these scopes: `<deduced-scopes>` and this redirect URI: `<cloud-host>/<orgName>/<tenantName>/actions_`
+>
+> - If yes, paste it
+> - If no, say **"create one"** and I'll set it up via browser automation"
+
+**If the user says "create one":** Follow [oauth-client-setup.md Step 2 (Setup B)](oauth-client-setup.md#step-2-ensure-playwright-is-available) to install Playwright into `~/.uipath-skills/playwright/`. Do **not** install into the user's app (`npm install -D playwright` adds ~300MB to devDependencies for a tool that runs once or twice).
+
+Then read [oauth-client-setup.md](oauth-client-setup.md) and follow it to create the External Application with the scopes above and redirect URI `<cloud-host>/<orgName>/<tenantName>/actions_` — pass `<cloud-host>` as `--cloud-host` to the script.
+
+Store the resulting client ID as `<client-id>`.
+
+### Q4 — Action schema
+
+Collect the data contract for this app. Ask field-by-field.
+
+#### Q4a — Input fields
+> "How many INPUT fields does this form have? (Read-only data passed in from the automation — e.g., applicant name, loan amount.) Enter 0 if none."
+
+For each input field, collect: **name** (camelCase), **type** (`string` / `number` / `integer` / `boolean` / `array` / `object`), **required** (yes/no), optional **description**, and if type is `array` the items type.
+
+#### Q4b — Output fields
+> "How many OUTPUT fields does this form have? (Fields the reviewer fills in — e.g., review notes, risk rating.) Enter 0 if none."
+
+Same sub-questions as Q4a.
+
+#### Q4c — InOut fields
+> "How many INOUT fields does this form have? (Pre-populated but editable by the reviewer.) Enter 0 if none."
+
+Same sub-questions.
+
+#### Q4d — Outcomes
+> "What are the outcome buttons for this task? Enter comma-separated names (e.g., `Approve, Reject, Escalate`)."
+
+#### Q4e — Hidden fields (optional)
+> "Are there any fields that should NOT be shown as form inputs (e.g., internal IDs passed silently)? If yes, list names comma-separated. Press Enter to skip."
+
+Hidden fields are included in `action-schema.json` and in the `FormData` interface but omitted from the JSX.
+
+#### Confirm the schema
+Show the complete `action-schema.json` to the user and ask:
+> "Does this look correct? Reply ok to generate the project, or tell me what to change."
+
+### Q5 — Form layout (optional)
+> "Describe the form's layout and style — purpose, visual arrangement, colour preferences. Press Enter for a clean default layout."
+
+---
+
+## Project Scaffolding
+
+After collecting all answers, scaffold the project. Use the file templates in [assets/templates/action-app-template.md](../assets/templates/action-app-template.md) as starting points for all generated files.
+
+```bash
+npm create vite@latest <app-name> -- --template react-ts
+cd <app-name>
+npm install @uipath/coded-action-app --@uipath:registry=https://registry.npmjs.org
+npm install
+```
+
+If SDK services are needed:
+```bash
+npm install @uipath/uipath-typescript --@uipath:registry=https://registry.npmjs.org
+```
+
+> **Why the registry flag?** Users may have `@uipath` scoped to GitHub Packages in their `.npmrc`, which requires authentication and causes a 401. The flag forces these packages to install from the public npm registry.
+
+---
+
+## Generated Files
+
+### `action-schema.json`
+
+Write to the project root. All four sections are always present — use `"properties": {}` for empty sections.
+
+```json
+{
+  "inputs": {
+    "type": "object",
+    "properties": {
+      "applicantName": { "type": "string", "required": true, "description": "Full name" },
+      "loanAmount":    { "type": "number", "required": false },
+      "documentIds":   { "type": "array",  "required": false, "items": { "type": "string" } }
+    }
+  },
+  "outputs": {
+    "type": "object",
+    "properties": {
+      "reviewerNotes": { "type": "string",  "required": false },
+      "riskScore":     { "type": "integer", "required": true }
+    }
+  },
+  "inOuts": {
+    "type": "object",
+    "properties": {}
+  },
+  "outcomes": {
+    "type": "object",
+    "properties": {
+      "Approve": { "type": "string" },
+      "Reject":  { "type": "string" }
+    }
+  }
+}
+```
+
+**TypeScript ↔ JSON schema type mapping:**
+
+| Schema type | TypeScript type | Initial value |
+|-------------|-----------------|---------------|
+| `string` | `string` | `''` |
+| `number` | `number` | `0` |
+| `integer` | `number` | `0` |
+| `boolean` | `boolean` | `false` |
+| `array` | `ItemType[]` | `[]` |
+| `object` | `Record<string, unknown>` | `{}` |
+
+---
+
+### `src/uipath.ts`
+
+Without SDK services:
+```typescript
+import { CodedActionAppService } from '@uipath/coded-action-app';
+
+export const codedActionAppService = new CodedActionAppService();
+```
+
+With SDK services:
+```typescript
+import { UiPath } from '@uipath/uipath-typescript/core';
+import { Entities } from '@uipath/uipath-typescript/entities';  // example
+import { CodedActionAppService } from '@uipath/coded-action-app';
+
+const sdk = new UiPath();
+export const codedActionAppService = new CodedActionAppService();
+export const entities = new Entities(sdk);  // example
+```
+
+---
+
+### `src/App.tsx`
+
+```typescript
+import { useState, useCallback } from 'react';
+import Form from './components/Form';
+
+function App() {
+  const [darkTheme, setDarkTheme] = useState(false);
+
+  const handleInitTheme = useCallback((isDark: boolean) => {
+    setDarkTheme(isDark);
+    document.body.className = isDark ? 'dark' : 'light';
+  }, []);
+
+  return (
+    <div className={darkTheme ? 'dark' : 'light'}>
+      <Form onInitTheme={handleInitTheme} />
+    </div>
+  );
+}
+
+export default App;
+```
+
+---
+
+### `src/components/Form.tsx`
+
+Generate based on the collected schema. Key patterns:
+
+```typescript
+import { useState, useEffect, ChangeEvent } from 'react';
+import { Theme } from '@uipath/coded-action-app';
+import { codedActionAppService } from '../uipath';
+import './Form.css';
+
+// Generate from schema — one property per field across all sections
+interface FormData {
+  applicantName: string;   // input
+  loanAmount: number;      // input
+  reviewerNotes: string;   // output
+  riskScore: number;       // output
+}
+
+const isDarkTheme = (theme: Theme) =>
+  theme === Theme.Dark || theme === Theme.DarkHighContrast;
+
+interface FormProps {
+  onInitTheme: (isDark: boolean) => void;
+}
+
+function Form({ onInitTheme }: FormProps) {
+  const [formData, setFormData] = useState<FormData>({
+    applicantName: '', loanAmount: 0,
+    reviewerNotes: '', riskScore: 0,
+  });
+  const [isReadOnly, setIsReadOnly] = useState(false);
+
+  useEffect(() => {
+    codedActionAppService.getTask().then((task) => {
+      if (task.data) setFormData(task.data as FormData);
+      setIsReadOnly(task.isReadOnly);
+      onInitTheme(isDarkTheme(task.theme));
+    });
+  }, [onInitTheme]);
+
+  const handleChange = (e: ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => {
+    if (isReadOnly) return;
+    const { name, value } = e.target;
+    const updated = { ...formData, [name]: value };
+    setFormData(updated);
+    codedActionAppService.setTaskData(updated);
+  };
+
+  // isFormValid: false when read-only OR when required output/inout fields are empty
+  const isFormValid = !isReadOnly && Boolean(formData.riskScore);
+
+  // One async handler per outcome
+  const handleApprove = async () =>
+    codedActionAppService.completeTask('Approve', formData);
+  const handleReject = async () =>
+    codedActionAppService.completeTask('Reject', formData);
+
+  return (
+    <form className="action-form">
+      {/* Input fields — always readOnly */}
+      <label>Applicant Name
+        <input readOnly value={formData.applicantName} />
+      </label>
+
+      {/* Output fields — editable unless isReadOnly */}
+      <label>Review Notes
+        <textarea
+          name="reviewerNotes"
+          value={formData.reviewerNotes}
+          onChange={handleChange}
+          readOnly={isReadOnly}
+        />
+      </label>
+
+      {/* Outcome buttons — disabled when form is invalid */}
+      <div className="actions">
+        <button type="button" onClick={handleApprove} disabled={!isFormValid}>Approve</button>
+        <button type="button" onClick={handleReject} disabled={!isFormValid}>Reject</button>
+      </div>
+    </form>
+  );
+}
+
+export default Form;
+```
+
+**Rendering rules:**
+- `inputs` fields → `readOnly` always
+- `outputs` fields → editable, `readOnly={isReadOnly}`
+- `inOuts` fields → editable, `readOnly={isReadOnly}`
+- Hidden fields (from Q4e) → omit from JSX entirely, but keep in `FormData` interface and initial state
+
+---
+
+### `vite.config.ts`
+
+`base: './'` is **always required** — the platform handles URL routing at runtime:
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  base: './',
+});
+```
+
+---
+
+## Deploy Action App
+
+```bash
+npm run build
+uip codedapp pack dist -n <app-name> -v 1.0.0
+uip codedapp publish -t Action        # -t Action is required
+uip codedapp deploy
+```
+
+See [pack-publish-deploy.md](pack-publish-deploy.md) for full deployment options.