@uipath/solution-tool 1.1.0 → 1.195.0

package/dist/services/resource-refresh-service.d.ts

@@ -0,0 +1,32 @@
+/** Discriminator for {@link ResourceRefreshFailure}; library callers can ignore the tag and read `.message` / `.ok`. */
+export type ResourceRefreshFailureReason = "solution_not_found" | "not_a_solution" | "auth_failed" | "sync_failed";
+export interface ResourceRefreshOptions {
+    /** Minimum minutes before token expiration to trigger a refresh. Default `10` (matches the CLI's `--login-validity`). */
+    loginValidity?: number;
+}
+export interface ResourceRefreshSuccess {
+    ok: true;
+    /** Resources newly created (virtualized) in the solution this run. */
+    created: number;
+    /** Resources imported from Orchestrator into the solution this run. */
+    imported: number;
+    /** Bindings whose cloud key was already in the solution (no-op this run). */
+    skipped: number;
+    /** Non-fatal advisories (e.g. unresolved connections, link-before-deploy hints). */
+    warnings: string[];
+}
+export interface ResourceRefreshFailure {
+    ok: false;
+    reason: ResourceRefreshFailureReason;
+    /** Human-readable summary suitable for top-level surfacing. */
+    message: string;
+}
+export type ResourceRefreshResult = ResourceRefreshSuccess | ResourceRefreshFailure;
+/**
+ * Programmatic core of `uip solution resource refresh`: re-scans every project's
+ * `bindings_v2.json` and syncs resource declarations into the solution, importing
+ * from Orchestrator when a match exists and virtualizing the rest. Returns a tagged
+ * {@link ResourceRefreshResult}; re-throws only on unexpected errors. Mirrors
+ * `./pack` / `./publish` / `./deploy`.
+ */
+export declare function resourceRefreshAsync(solutionPath?: string, options?: ResourceRefreshOptions): Promise<ResourceRefreshResult>;

package/dist/services/solution-init-service.d.ts

@@ -0,0 +1,37 @@
+/** Which step of {@link solutionInitAsync} failed, so the CLI can map it to a stage-specific message. */
+export type SolutionInitStage = "directory" | "briefing" | "manifest";
+/** Thrown by {@link solutionInitAsync}, tagged with the failing {@link SolutionInitStage}; `message` mirrors the cause. */
+export declare class SolutionInitError extends Error {
+    readonly stage: SolutionInitStage;
+    constructor(stage: SolutionInitStage, cause: unknown);
+}
+export interface SolutionInitOptions {
+    /**
+     * AGENTS.md / CLAUDE.md content, written to both files before the `.uipx` manifest.
+     * The CLI passes its version-stamped template; library callers usually omit it.
+     */
+    briefingContent?: string;
+    /**
+     * Base dir a relative `solutionName` resolves against. Defaults to `process.cwd()`;
+     * lets library callers set a root without mutating global cwd. Ignored if `solutionName` is absolute.
+     */
+    cwd?: string;
+}
+export interface SolutionInitResult {
+    /** Absolute path to the created `.uipx` manifest. */
+    solutionFile: string;
+    /** Absolute path to the created solution directory. */
+    solutionDir: string;
+    /** Solution name without extension. */
+    solutionName: string;
+    /** Absolute path to the written AGENTS.md, when `briefingContent` was provided. */
+    agentsPath?: string;
+    /** Absolute path to the written CLAUDE.md, when `briefingContent` was provided. */
+    claudePath?: string;
+}
+/**
+ * Programmatic core of `uip solution init`: creates the solution dir, an optional
+ * AGENTS.md/CLAUDE.md briefing (before the manifest), and the `.uipx` manifest. Throws on
+ * failure; does not touch `OutputFormatter`/`processContext`.
+ */
+export declare function solutionInitAsync(solutionName: string, options?: SolutionInitOptions): Promise<SolutionInitResult>;

package/dist/services/solution-manifest.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Throw if `dir` doesn't directly contain a `.uipx` manifest. Stricter than
+ * `findSolutionFile` (which walks up to find one) — write commands should not
+ * silently mutate the wrong folder when run from an arbitrary cwd.
+ *
+ * Lives in `services/` (not `commands/project.ts`) so callers can mock the
+ * check without pulling in the full project-commands module.
+ */
+export declare function assertSolutionManifest(dir: string): Promise<void>;

package/dist/services/sync-resources-from-bindings.d.ts

@@ -0,0 +1,132 @@
+import { type IResourceBuilderServices, type ISolutionBuilder, type ResourceDefinition } from "@uipath/resource-builder-sdk";
+interface RequiredPropertyDefault {
+    property: string;
+    /** Empty placeholder value matching the property's declared type. */
+    placeholder: unknown;
+}
+interface ResolvedKindMetadata {
+    /** Subtype to pass to createVirtualResourceAsync (e.g. "StringAsset"). */
+    type?: string;
+    /** SDK's `supportsInLineCreation` — whether a virtual stub can be created. */
+    virtualizable: boolean;
+    /**
+     * Required spec properties that have no default in SDK metadata. Deploy
+     * validation rejects virtualized resources missing these (e.g. Asset.value).
+     * We fill them in-memory after `createVirtualResourceAsync` with a
+     * type-appropriate placeholder.
+     */
+    requiredDefaults: RequiredPropertyDefault[];
+}
+/**
+ * Normalize a folder path for comparisons. `.` and `solution_folder` both
+ * encode "no folder" (tenant/root scope) — collapsing them to undefined lets
+ * us compare a binding's folder against an existing resource's folder
+ * consistently regardless of which placeholder either side carries.
+ */
+export declare function normalizeFolderPath(path: string | undefined): string | undefined;
+interface SyncResult {
+    created: number;
+    imported: number;
+    skipped: number;
+    warnings: string[];
+}
+/**
+ * Reads bindings_v2.json from project paths and creates/imports matching
+ * resources in the solution using the resource-builder-sdk.
+ *
+ * @param solutionDir - Path to the solution directory
+ * @param projectPaths - Specific project paths to scan (if omitted, scans all projects in .uipx)
+ */
+export declare function syncResourcesFromBindings(solutionDir: string, projectPaths?: string[]): Promise<SyncResult>;
+/**
+ * Mirror of SDK's private `addResourceWithUniqueName`
+ * (resource-builder-sdk index.js:673): if any other resource of the same
+ * kind already carries `name` (or a `name_<N>` suffix variant), return
+ * `name_<N+1>`. Otherwise return `name` unchanged. Excludes `excludeKey`
+ * so the resource we just created doesn't collide with itself.
+ */
+export declare function uniqueNameForResource(name: string, kind: string, excludeKey: string, solution: {
+    resources: Array<{
+        key: string;
+        kind?: string;
+        name?: string;
+    }>;
+}): string;
+export interface RcsMatch {
+    key: string;
+    name: string;
+    /** Subtype as RCS reports it (e.g. `Text` for Asset). `undefined` for
+     * kinds without a subtype (Queue). Callers may need to forward this to
+     * `addOrUpdateResourceToSolutionAsync`, which rejects type-less imports
+     * for kinds that SDK metadata indexes by (kind, type). */
+    type?: string;
+    folder?: {
+        fullyQualifiedName: string;
+        folderKey: string;
+        path?: string;
+    };
+}
+/**
+ * Page through RCS for a given (kind, name) and collect every match. Returns
+ * an empty array on lookup error (logged as a warning). Callers decide what
+ * to do with 0/1/many matches.
+ */
+export declare function searchRcsResources(builder: ISolutionBuilder, kind: string, name: string): Promise<RcsMatch[]>;
+export declare function findResourceInRcs(builder: ISolutionBuilder, kind: string, name: string, folderPath?: string): Promise<RcsMatch | undefined>;
+/**
+ * Resolve a resource kind's metadata via the SDK (`kind`, optional `type`) so
+ * callers outside the bindings sync can fill required spec defaults the same
+ * way `createVirtualForBinding` does. Returns undefined if the kind isn't
+ * indexed by SDK metadata.
+ */
+export declare function resolveResourceKindMetadata(services: IResourceBuilderServices, kind: string, type?: string): Promise<ResolvedKindMetadata | undefined>;
+export interface CreateLocalResourceParams {
+    builder: ISolutionBuilder;
+    services: IResourceBuilderServices;
+    kind: string;
+    type?: string;
+    name: string;
+    folderPath?: string;
+}
+export interface CreateLocalResourceResult {
+    resource: ResourceDefinition;
+    /** Final name on the resource — may differ from input if SDK conflict suffix kicked in. */
+    finalName: string;
+}
+/**
+ * Create a virtual (local-only) resource via the SDK and rename it to `name`,
+ * mirroring the rename + spec-default flow `createVirtualForBinding` runs
+ * during refresh. Returns the freshly created `SolutionResource` after the
+ * mutation, or undefined if the SDK failed to allocate a key.
+ *
+ * Callers must:
+ *   - Persist the change (e.g. `builder.disposeAsync()` or
+ *     `context.saveAsync()`); this helper only mutates in-memory state.
+ *   - Have already done an idempotency check — this helper *always* creates,
+ *     and SDK's `addResourceWithUniqueName` will suffix the name on conflict.
+ */
+export declare function createLocalResource(params: CreateLocalResourceParams): Promise<CreateLocalResourceResult | undefined>;
+export interface UipxProject {
+    /** Project type as written in `.uipx` (e.g. "Agent", "Process"). */
+    type: string;
+    /** Design-time UUID used as `projectKey` in reconcile. */
+    id: string;
+    /** Path to the project directory (parent of `project.uiproj`). */
+    path: string;
+    /** Project name read from `project.uiproj` (`Name` field). */
+    name: string;
+}
+/**
+ * Read solution's `.uipx` and each project's `project.uiproj` to assemble the
+ * data needed for `reconcileProjectsAsync`. Without this, sync would only see
+ * resource bindings (Queue/Asset/etc.) and miss the project artefacts
+ * (process/<type>, package, app/<subType>, appVersion) the SDK generates from
+ * project templates.
+ */
+export declare function readUipxProjects(solutionDir: string): Promise<UipxProject[]>;
+/**
+ * Sync resources from bindings with logging. Non-fatal — logs warnings
+ * on failure and continues. Used by pack and upload before packaging.
+ */
+export declare function syncAndLog(solutionDir: string): Promise<void>;
+export {};

package/dist/templates/AGENTS.md

@@ -85,9 +85,13 @@ uip login --client-id <ID> --client-secret <SECRET> --tenant <TENANT>
 
 # 2. Pack the solution into a .zip. Two positional args:
 #    <solutionPath>  — solution dir (containing .uipx) or a .uis file
-#    <output-path>   — directory where the .zip is written
+#    <output-path>   — directory where the .zip is written (required unless --dry-run)
 uip solution pack . ./out
 
+# 2a. (Optional) Validate the solution against the strict deploy-time
+#     pipeline without producing a package — useful as a CI gate.
+uip solution pack . --dry-run
+
 # 3. Publish the packed .zip to Orchestrator
 uip solution publish ./out/<package>.zip
 
@@ -127,12 +131,13 @@ uip solution deploy uninstall <deployment-name>    # remove the deployment + its
 Studio Web is a separate target from the Orchestrator deploy chain — it hosts a browser-based collaborative editor for solutions. The `solution upload` command pushes the local solution there and returns a `DesignerUrl` to open the solution in a browser; this is independent of `pack` / `publish` / `deploy` and does *not* produce a runtime-deployable artifact.
 
 ```bash
-uip solution upload .                      # upload solution dir to Studio Web; returns DesignerUrl
+uip solution upload .                      # upload solution dir to Studio Web as a new solution; returns DesignerUrl
+uip solution upload . --force              # force-replace the existing Studio Web solution referenced by .uipx (destroys cloud version history)
 uip solution download <solution-id>        # round-trip a Studio Web solution back to disk
 uip solution delete <solution-id>          # remove a solution from Studio Web
 ```
 
-`upload` accepts a solution directory, a `.uipx` file, or a `.uis` file. If the solution already exists on Studio Web (matching `SolutionId` in `.uipx`), the upload overwrites; otherwise it imports as new.
+`upload` accepts a solution directory, a `.uipx` file, or a `.uis` file. It probes Studio Web for the bundled `SolutionId` first: if the cloud has no solution with that id, the upload imports as new; if a solution with that id already exists, the upload is refused unless `--force` is passed. Forcing replaces the cloud project in place and **wipes its Studio Web version history**, so use `--force` deliberately. To upload a copy as an unrelated cloud solution instead of overwriting, scaffold a fresh solution with `uip solution init` (or remove the `SolutionId` from the local `.uipx`) and re-run upload.
 
 ## Per-Project Bindings (`bindings_v2.json`)
 
@@ -192,11 +197,11 @@ The CLI talks about the same resource types Orchestrator does:
 - **Processes / Releases** — published packages bound to a folder.
 - **Triggers** & **Webhooks** — event-, time-, or queue-based job firing; outbound HTTP notifications.
 
-Resources outside a solution are managed via the `uip resource` group, which exposes per-type subgroups (`uip resource assets …`, `uip resource queues …`, `uip resource buckets …`, `uip resource bucket-files …`, `uip resource libraries …`, `uip resource queue-items …`, `uip resource triggers …`, `uip resource webhooks …`). Run `uip resource --help` for the live list. Example:
+Resources outside a solution are managed under the orchestrator tool, which exposes per-type subgroups (`uip or assets …`, `uip or queues …`, `uip or buckets …`, `uip or bucket-files …`, `uip or libraries …`, `uip or queue-items …`, `uip or triggers …`, `uip or webhooks …`). Run `uip or --help` for the live list. Example:
 
 ```bash
-uip resource assets list          # list assets in the active folder
-uip resource assets create        # create an asset (see --help)
+uip or assets list          # list assets in the active folder
+uip or assets create        # create an asset (see --help)
 ```
 
 ## Output Conventions for Agents
@@ -222,13 +227,15 @@ uip solution deploy --help       # the deploy subgroup
 uip <command> --help             # full options for any command
 ```
 
+For concept or API documentation beyond CLI usage, fetch `https://docs.uipath.com/llms.txt` for the product index, then the relevant `.md` page (e.g. `https://docs.uipath.com/orchestrator/automation-cloud/latest/api-guide/assets-requests.md`).
+
 Adjacent groups commonly used alongside solutions:
 
 | Group | Purpose |
 |---|---|
 | `uip login`, `uip login tenant` | Authenticate, switch tenants |
 | `uip or folders` | Manage Orchestrator folders |
-| `uip resource` | Manage Orchestrator resources directly (assets, queues, buckets, …) |
+| `uip or assets`, `uip or queues`, `uip or buckets`, `uip or bucket-files`, `uip or libraries`, `uip or queue-items`, `uip or triggers`, `uip or webhooks` | Manage Orchestrator resources directly |
 | `uip rpa` | RPA workflow lifecycle (compile, validate, execute, scaffold) |
 | `uip maestro` | Maestro Flow / Case / BPMN scaffolding |
 | `uip agent`, `uip codedagent` | Coded agent lifecycle |