@uipath/solution-tool 1.201.0-preview.133 → 1.202.0-preview.134

package/dist/{packager-tool-vpr77gre.js → packager-tool-x3ehbhsn.js}

@@ -29,7 +29,8 @@ class ToolsFactoryRepository {
   getProjectToolFactory(projectType) {
     const factory = this.projectFactoryMap.get(projectType);
     if (!factory) {
-      throw new Error(`No tool factory found for project type '${projectType}'`);
+      const known = [...this.projectFactoryMap.keys()].join(", ");
+      throw new Error(`Cannot pack project type '${projectType}': no packager is installed for it. ` + `Project types that can be packed: ${known || "none"}.`);
     }
     return factory;
   }
@@ -892,4 +893,4 @@ I18nManager.registerTranslations("zu", zu);
 I18nManager.setLocale("en");
 export { ToolResult, toolsFactoryRepository };
 
-//# debugId=A70248815AC3C8A364756E2164756E21
+//# debugId=EE7F0622AB4476C164756E2164756E21

package/dist/{packager-tool-yktm4v4r.js → packager-tool-xntjj1bt.js}

@@ -1,7 +1,7 @@
 import {
   catchError,
   getAuthContext
-} from "./packager-tool-bcpknnr8.js";
+} from "./packager-tool-hgx66d1p.js";
 
 // src/services/studio-web-auth-middleware.ts
 var studioWebAuthByCommand = new WeakMap;

package/dist/packager-tool.d.ts

@@ -1,9 +1,10 @@
 /**
  * Register the factories solution-tool owns: the ResourceBuilder *solution*
  * factory (essential to every pack; no CLI verb can own it) plus the project
- * factories for the types no CLI tool owns — Connector and AppV2. Project
- * wrapper tools (flow, agent, case, maestro, api-workflow, function) ship
- * their own `packager-tool` entry point and are loaded on demand.
+ * factory for Connector, the one project type no CLI tool owns — there is no
+ * `connector` verb. Every other project type is registered by the tool that
+ * owns it, through that tool's own `packager-tool` entry point, loaded on
+ * demand by `ensurePackagerTools` (AGENTS.md Hard Rule #18).
  *
  * Explicit, not a module-load side effect: `ensurePackagerTools` calls this at
  * the start of every pack / restore / cleanup, which is the only code that

package/dist/packager-tool.js

@@ -1,9 +1,9 @@
 import {
   registerPackagerFactories
-} from "./packager-tool-9vehmnke.js";
-import"./packager-tool-vpr77gre.js";
-import"./packager-tool-129wn232.js";
-import"./packager-tool-0v6na3yp.js";
+} from "./packager-tool-3hbsdwjm.js";
+import"./packager-tool-x3ehbhsn.js";
+import"./packager-tool-dfrk01gn.js";
+import"./packager-tool-1de529jm.js";
 export {
   registerPackagerFactories
 };

package/dist/publish.js

@@ -1,17 +1,14 @@
 import {
   publishSolutionAsync
-} from "./packager-tool-f7kj5fpa.js";
-import"./packager-tool-c29pg93e.js";
-import"./packager-tool-9w3k4e77.js";
-import"./packager-tool-fzwxq48d.js";
-import"./packager-tool-bcpknnr8.js";
-import"./packager-tool-9qecd4wb.js";
-import"./packager-tool-7eva0peq.js";
-import"./packager-tool-5arsyj36.js";
-import"./packager-tool-129wn232.js";
-import"./packager-tool-0v6na3yp.js";
+} from "./packager-tool-5pfxgc8z.js";
+import"./packager-tool-hc6ybtdw.js";
+import"./packager-tool-b16qemg2.js";
+import"./packager-tool-3y92zbg2.js";
+import"./packager-tool-hgx66d1p.js";
+import"./packager-tool-dfrk01gn.js";
+import"./packager-tool-1de529jm.js";
 export {
   publishSolutionAsync
 };
 
-//# debugId=DA463E68D9A9E64264756E2164756E21
+//# debugId=AD7DDE48BF35E04564756E2164756E21

package/dist/resource.js

@@ -1,16 +1,13 @@
 import {
   resourceRefreshAsync
-} from "./packager-tool-krd5v2r5.js";
-import"./packager-tool-vpr77gre.js";
-import"./packager-tool-fzwxq48d.js";
-import"./packager-tool-bcpknnr8.js";
-import"./packager-tool-9qecd4wb.js";
-import"./packager-tool-7eva0peq.js";
-import"./packager-tool-5arsyj36.js";
-import"./packager-tool-129wn232.js";
-import"./packager-tool-0v6na3yp.js";
+} from "./packager-tool-0qva0ebq.js";
+import"./packager-tool-x3ehbhsn.js";
+import"./packager-tool-3y92zbg2.js";
+import"./packager-tool-hgx66d1p.js";
+import"./packager-tool-dfrk01gn.js";
+import"./packager-tool-1de529jm.js";
 export {
   resourceRefreshAsync
 };
 
-//# debugId=EF371AE5DDFD388A64756E2164756E21
+//# debugId=54ED39ED9D918B1A64756E2164756E21

package/dist/services/activation.d.ts

@@ -1,11 +1,19 @@
 import { type PollUntilResult } from "@uipath/common";
 import type { DeploymentStatus } from "@uipath/pipelines-sdk";
-import type { DeploymentSearchItemDto2, SolutionAuthContext } from "@uipath/solution-sdk";
+import type { DeploymentSearchItemDto2, InitOverrideFunction, SolutionAuthContext } from "@uipath/solution-sdk";
 export type ActivationOptions = {
     timeoutSeconds: number;
     pollIntervalMs: number;
     /** Host-side cancellation. Falls back to `processContext.pollSignal` (CLI's Ctrl-C) when omitted. */
     signal?: AbortSignal;
+    /**
+     * `X-UIPATH-FolderKey` override for the feed the deployment lives in.
+     * Omitted for the tenant feed. Every call below resolves against the
+     * tenant feed without it, so a Personal Workspace or folder-feed
+     * deployment is answered "not found" — see
+     * {@link findDeploymentAcrossFeeds}.
+     */
+    scope?: InitOverrideFunction;
 };
 export type ActivationResult = 
 /** Pre-activate steps lookup or activate call failed. */

package/dist/services/deploy-run-service.d.ts

@@ -1,3 +1,4 @@
+import { type CliErrorCode, type RetryHint } from "@uipath/common";
 import { type FeedScope } from "./feed-resolver";
 /** Discriminator for {@link DeployFailure}; library callers can ignore the tag and read `.message`/`.instructions`. */
 export type DeployFailureReason = "auth_failed" | "folder_resolution_failed" | "config_file_not_found" | "config_file_read_failed" | "config_file_parse_failed" | "install_request_failed"
@@ -62,8 +63,21 @@ export interface DeployOptions {
     pollInterval?: number;
     /** Minimum minutes before token expiration to trigger a refresh. Default 10. */
     loginValidity?: number;
+    /**
+     * Feed / Personal Workspace deploys only: poll the new deployment to a
+     * terminal state instead of returning as soon as the install is accepted.
+     * The tenant path always polls, so this changes nothing there.
+     */
+    wait?: boolean;
     /** Skip auto-activation; leave deployment in "Inactive (Ready to activate)" state. */
     skipActivate?: boolean;
+    /**
+     * Deploy even when the package already has a deployment in the target feed.
+     * Off by default: `deploy run` always creates a *new* deployment in a *new*
+     * folder, so repeating it quietly multiplies folders (UV-15362). Callers
+     * that really do want a second, independent copy opt in here.
+     */
+    yes?: boolean;
     /** Host-side cancellation for both poll loops (e.g. VS Code's cancel button); replaces `processContext.pollSignal`. */
     signal?: AbortSignal;
 }
@@ -72,7 +86,8 @@ export interface DeploySuccess {
     /**
      * Tenant path: `"DeploymentSucceeded"` after polling reaches terminal.
      * Feed/PW path: `"DeploymentStarted"` — the AS auto-install endpoint
-     * returns at request acceptance, before terminal state is observable.
+     * returns at request acceptance, before terminal state is observable — or
+     * `"DeploymentSucceeded"` when `wait` was set and the poll got there.
      */
     status: string;
     /** Tenant only — populated from Pipelines install result. Feed/PW returns no key. */
@@ -115,6 +130,15 @@ export interface DeployFailure {
     exitCode: number;
     /** Set whenever an install was initiated (post-`pipelinesInstall` paths). */
     pipelineDeploymentId?: string;
+    /**
+     * Set whenever the failure mode is known, so the CLI does not fall back to
+     * `OutputFormatter`'s guess. The guess is wrong for a poll that timed out:
+     * the message carries no HTTP status, so it defaults to `unknown_error` /
+     * `RetryWillNotFix` while the instructions right next to it say the deploy
+     * may still be running.
+     */
+    errorCode?: CliErrorCode;
+    retry?: RetryHint;
 }
 export type DeployResult = DeploySuccess | DeployFailure;
 /**

package/dist/services/deploy-uninstall-service.d.ts

@@ -1,4 +1,11 @@
+import { type CliErrorCode, type RetryHint } from "@uipath/common";
 export type UninstallDeploymentFailureReason = "auth_failed" | "uninstall_request_failed"
+/**
+ * Orchestrator refused the uninstall because the deployment still had an
+ * operation running, and it was still running when the wait ran out —
+ * recommended exit 2, same as a poll timeout.
+ */
+ | "uninstall_blocked"
 /** Uninstall poll didn't reach a terminal state — recommended exit 2 (CI distinguishability). */
  | "poll_timeout" | "poll_failed" | "poll_aborted"
 /** Uninstall reached a terminal state but it was `FailedUninstall`. */
@@ -11,7 +18,11 @@ export interface UninstallDeploymentOptions {
     tenant?: string;
     /** Pin auth to this exact `.uipath/.auth` path. */
     envFilePath?: string;
-    /** Timeout in seconds for uninstall polling. Default 360. */
+    /**
+     * Timeout in seconds for the whole uninstall: waiting out an operation
+     * that blocks the request, then polling the uninstall to a terminal
+     * state. Default 360.
+     */
     timeout?: number;
     /** Milliseconds between uninstall status polls. Default 5000. */
     pollInterval?: number;
@@ -36,6 +47,14 @@ export interface UninstallDeploymentFailure {
     message: string;
     instructions: string;
     exitCode: number;
+    /**
+     * Set whenever the failure mode is known, so the CLI does not fall back to
+     * `OutputFormatter`'s guess. The guess is wrong for a blocked uninstall:
+     * an HTTP 400 defaults to `invalid_argument` / `RetryWillNotFix`, telling
+     * an agent never to retry a condition that clears by itself.
+     */
+    errorCode?: CliErrorCode;
+    retry?: RetryHint;
 }
 export type UninstallDeploymentResult = UninstallDeploymentSuccess | UninstallDeploymentFailure;
 /**

package/dist/services/deploy-upgrade-service.d.ts

@@ -0,0 +1,94 @@
+import type { PollFailureReason } from "@uipath/common";
+import { DeploymentOperationStatus } from "@uipath/solution-sdk";
+export type UpgradeDeploymentFailureReason = "auth_failed"
+/** Personal Workspace could not be resolved (only when `--personal-workspace`). */
+ | "personal_workspace_failed"
+/** No deployment with the given key (or not visible in the chosen scope). */
+ | "deployment_not_found"
+/** The deployment is already at the newest version and no `--version` was given. */
+ | "no_upgrade_available"
+/** The target package/version could not be resolved to a package-version key. */
+ | "package_not_found"
+/** Requested a version other than the latest, which the package search can't key. */
+ | "unsupported_version"
+/** The upgrade HTTP request failed. */
+ | "request_failed"
+/** The upgrade was queued but installing the resulting draft failed. */
+ | "install_failed"
+/** The install was accepted but did not reach a terminal state in time. */
+ | "install_timeout"
+/**
+ * The status poll itself gave up (too many consecutive errors), or was
+ * interrupted / aborted. Distinct from `install_timeout`: the deadline was
+ * never reached, so a longer `--timeout` is not the fix.
+ */
+ | PollFailureReason;
+export interface UpgradeDeploymentOptions {
+    /**
+     * Override the active tenant for auth resolution. The CLI's deprecated
+     * `--tenant` flag flows through here; library callers usually omit it.
+     */
+    tenant?: string;
+    /** Pin auth to this exact `.uipath/.auth` path. */
+    envFilePath?: string;
+    /**
+     * Version to upgrade to. Defaults to the deployment's newest available
+     * version. Only the latest published version is resolvable today (same
+     * limitation as Personal Workspace deploy).
+     */
+    version?: string;
+    /**
+     * Scope the deployment lookup and the upgrade to the caller's Personal
+     * Workspace feed. A tenant deployment is upgraded in its own root folder.
+     */
+    personalWorkspace?: boolean;
+    /** Minimum minutes before token expiration to trigger a refresh. Default 10. */
+    loginValidity?: number;
+    /**
+     * Return as soon as the install is accepted, without polling for the
+     * terminal state. The version still moves; the caller just does not wait.
+     */
+    noWait?: boolean;
+    /** Seconds to wait for the install to reach a terminal state. Default 300. */
+    timeout?: number;
+    /** Milliseconds between status polls. Default 5000. */
+    pollInterval?: number;
+}
+export interface UpgradeDeploymentSuccess {
+    ok: true;
+    deploymentName: string;
+    /** Version the deployment ran before the upgrade (null when the API omits it). */
+    fromVersion?: string | null;
+    /** Version the upgrade targets. */
+    toVersion: string;
+    /**
+     * Key of the VersionChange deployment the upgrade created. This is NOT the
+     * key that was passed in — the server makes a new record — and it is the
+     * one `deploy status`-style follow-ups must address.
+     */
+    versionChangeKey: string;
+    /** Terminal status reached, or `Draft`/`InProgress` when `noWait`. */
+    status: DeploymentOperationStatus;
+}
+export interface UpgradeDeploymentFailure {
+    ok: false;
+    reason: UpgradeDeploymentFailureReason;
+    message: string;
+    instructions: string;
+    exitCode: number;
+}
+export type UpgradeDeploymentResult = UpgradeDeploymentSuccess | UpgradeDeploymentFailure;
+/**
+ * Programmatic core of `uip solution deploy upgrade`. Moves an existing
+ * deployment to a newer package version in place — the CLI equivalent of the
+ * Orchestrator UI "Upgrade" button, so a blocked redeploy (UV-15356) can be
+ * resolved without the UI.
+ *
+ * Two server calls, because one is not enough:
+ * `POST /api/deployments/{key}/upgrade` only queues the move as a second
+ * deployment record (`VersionChange`, status `Draft`) and leaves the live
+ * version alone, then `POST /api/deployments/{draftKey}/run` installs it.
+ * Waits for the install to reach a terminal state unless `noWait` is set.
+ * Does not touch `OutputFormatter`/`processContext`.
+ */
+export declare function upgradeDeploymentAsync(deploymentKey: string, options?: UpgradeDeploymentOptions): Promise<UpgradeDeploymentResult>;

package/dist/services/deployment-feed-locator.d.ts

@@ -0,0 +1,36 @@
+import type { DeploymentSearchItemDto2, InitOverrideFunction, SolutionAuthContext } from "@uipath/solution-sdk";
+/** A deployment and the feed header every call about it needs. */
+export interface DeploymentLocation {
+    deployment: DeploymentSearchItemDto2;
+    /** `X-UIPATH-FolderKey` override; undefined for the tenant feed. */
+    scope?: InitOverrideFunction;
+}
+/** Auth-resolution knobs the feed sweep forwards to its lookups. */
+export interface DeploymentLocationOptions {
+    tenant?: string;
+    loginValidity?: number;
+    envFilePath?: string;
+}
+/**
+ * Locate a deployment and the feed it lives in.
+ *
+ * `uninstall` and `activate` take no feed flag, so they have to work this out
+ * themselves: every Pipelines call about a deployment resolves against the
+ * tenant feed unless it carries `X-UIPATH-FolderKey`, and a deployment created
+ * by `deploy run --personal-workspace` or `--feed <folder-feed>` is invisible
+ * to the tenant-scoped search, so an unscoped call is answered "not found".
+ *
+ * Tenant first — that is the default feed and the one most deployments live in,
+ * so the common case costs one request. A tenant-search transport error
+ * propagates (callers treat it as a lookup failure). Only on a tenant miss does
+ * the sweep run, and it is best-effort throughout: a feed whose search fails is
+ * skipped rather than allowed to end the sweep, since the next feed may hold
+ * the record. A tenant that exposes many folder feeds therefore pays one search
+ * per feed, but only on a path that was already going to fail.
+ */
+export declare function findDeploymentAcrossFeeds(auth: SolutionAuthContext, deploymentName: string, options: DeploymentLocationOptions): Promise<DeploymentLocation | undefined>;
+/**
+ * {@link findDeploymentAcrossFeeds} that never throws — for callers that want
+ * the feed scope when it can be had but must not fail when it cannot.
+ */
+export declare function findDeploymentAcrossFeedsBestEffort(auth: SolutionAuthContext, deploymentName: string, options: DeploymentLocationOptions): Promise<DeploymentLocation | undefined>;

package/dist/services/deployment-search.d.ts

@@ -10,20 +10,85 @@ import type { DeploymentOperationStatus, DeploymentSearchItemDto2, InitOverrideF
  */
 export declare function findDeploymentByName(auth: SolutionAuthContext, deploymentName: string, scope?: InitOverrideFunction): Promise<DeploymentSearchItemDto2 | undefined>;
 /**
- * Best-effort lookup of the deployment that blocks a redeploy of `packageName`.
- * Pages `searchSearchDeployments22` by substring like {@link findDeploymentByName},
- * then returns the first row whose `packageName` matches exactly (and, when
- * `folderPath` is given, whose `folderPath` matches too). Swallows any lookup
- * failure and returns undefined so the caller's original error always surfaces.
+ * Every deployment whose `packageName` matches exactly.
+ *
+ * Pages `searchSearchDeployments22` to exhaustion instead of stopping at the
+ * first hit, because the redeploy gate has to report *all* the deployments
+ * that already exist, not just one.
+ *
+ * Sends two filters on purpose. `packageName` is the request's own server-side
+ * filter, which keeps the result set small; `searchTerm` is the substring
+ * filter the other call sites here already rely on, so the lookup still works
+ * if the server ignores `packageName`. The client-side `===` check is what
+ * makes the answer exact either way.
+ *
+ * Statuses are deliberately unfiltered — callers decide which states matter
+ * (the gate uses {@link blocksRedeploy}; the redeploy-conflict path needs the
+ * failed/running rows the gate ignores).
+ *
+ * Throws on transport / server errors; callers decide whether to swallow.
+ */
+export declare function findDeploymentsByPackageName(auth: SolutionAuthContext, packageName: string, options?: {
+    folderPath?: string;
+    scope?: InitOverrideFunction;
+}): Promise<DeploymentSearchItemDto2[]>;
+/**
+ * Does this record represent a deployment that is really there, so a fresh
+ * `deploy run` of the same package would create a second copy of it?
+ *
+ * The status alone does not answer that — the row's `operation` is overwritten
+ * by whatever ran last, so the same status means opposite things depending on
+ * which verb produced it. Read the pair:
+ *
+ * - **Anything `InProgress`** — blocks. The deployment is there until the
+ *   operation finishes, an uninstall included.
+ * - **`Successful`** — blocks, except a successful `Uninstall`: that history
+ *   row outlives the deployment, and blocking on it would make a package
+ *   permanently undeployable after its first uninstall.
+ * - **`Draft` / `Failed` / `FailedRollback` on an `Install`** — does not block.
+ *   The deploy the user is retrying is the one that produced the record, and
+ *   our own guidance for a Draft is to fix the errors and rerun `deploy run`
+ *   (see {@link appendDraftDeploymentInstructions}). Blocking would leave the
+ *   user with nothing they are allowed to do.
+ * - **`Draft` / `Failed` / `FailedRollback` on any other operation** — blocks.
+ *   An uninstall or an upgrade that failed ran *against* a deployment that is
+ *   still there and still holds its folder; the retry verb is uninstall or
+ *   upgrade, not `deploy run`.
+ *
+ * A record we cannot classify — no `operation`, or a status outside the enum —
+ * falls open (does not block). The guard is a rail against accidental
+ * duplication, not a safety interlock.
  */
-export declare function findDeploymentByPackageName(auth: SolutionAuthContext, packageName: string, folderPath?: string, scope?: InitOverrideFunction): Promise<DeploymentSearchItemDto2 | undefined>;
+export declare function blocksRedeploy(deployment: DeploymentSearchItemDto2): boolean;
+/**
+ * How many deployments the summary names before it starts counting. Exported so
+ * callers that decorate those deployments (the redeploy gate resolves a folder
+ * per named deployment) bound their work by the same number instead of keeping
+ * a second copy of it in sync by hand.
+ */
+export declare const MAX_LISTED_DEPLOYMENTS = 5;
+/**
+ * One human-readable line naming the deployments that already exist, for the
+ * redeploy gate's error message. Long lists are cut short — a package deployed
+ * forty times should not produce forty clauses.
+ *
+ * `folderPath` on the record is the deployment's *parent* folder, so every
+ * deployment of one package under `Shared` reports `Shared` — which hides
+ * exactly what the reader needs to see. `folderByKey` maps
+ * `installedRootFolderKey` onto the real solution folder when the caller could
+ * resolve it; the parent is the fallback. `installedRootFolderName` is never
+ * used: the record echoes the *requested* name back there, so a
+ * collision-renamed deployment reads as living in a folder it does not
+ * (UV-15346).
+ */
+export declare function formatExistingDeployments(deployments: DeploymentSearchItemDto2[], folderByKey?: Map<string, string>): string;
 /**
  * Best-effort deployment lookup: returns undefined on any failure instead of
  * propagating, so callers can read the record opportunistically — without
  * masking a prior error (error paths) or blocking an otherwise-successful
  * result (success paths, e.g. reading back the resolved install folder).
  */
-export declare function findDeploymentBestEffort(auth: SolutionAuthContext, deploymentName: string): Promise<DeploymentSearchItemDto2 | undefined>;
+export declare function findDeploymentBestEffort(auth: SolutionAuthContext, deploymentName: string, scope?: InitOverrideFunction): Promise<DeploymentSearchItemDto2 | undefined>;
 /**
  * Append a hint to error instructions when the deployment in question is
  * stuck in `Draft` state — that condition has a specific remediation that
@@ -64,6 +129,22 @@ export type DeployPollRecovery = {
     operationStatus: DeploymentOperationStatus;
 };
 export declare function interpretFailedDeployPoll(deployment: DeploymentSearchItemDto2 | undefined): DeployPollRecovery | undefined;
+/**
+ * Has a freshly created deployment finished moving? Answers the question
+ * `deploy run --wait` asks on every poll.
+ *
+ * `Draft` is deliberately *not* settled here, even though
+ * {@link mapOperationStatusToPipelineStatus} maps it to `DeploymentFailed`.
+ * The two are asked about different moments. That mapper answers for a
+ * deployment whose install was already observed running, so a Draft record
+ * there means the install never completed. The `--wait` poll starts before the
+ * install does, and the pipeline parks a new deployment in `Draft` until it
+ * promotes it to `InProgress` — so reading Draft as a verdict reported a
+ * healthy Personal Workspace deploy as failed seconds after starting it. Same
+ * reasoning as the `Draft` note in {@link interpretFailedDeployPoll}: a Draft
+ * that never moves is caught by the poll timeout instead.
+ */
+export declare function isSettledDeployOperationStatus(operationStatus: DeploymentOperationStatus | undefined | null): boolean;
 /**
  * Map a search-service `DeploymentOperationStatus` onto the corresponding
  * terminal `PipelineDeploymentStatus`. Returns undefined for non-terminal

package/dist/services/pack-command-service.d.ts

@@ -18,6 +18,21 @@ export declare class PackCommandService {
      * Execute the pack command and return result (for programmatic usage and testing)
      */
     executeAsync(solutionPath: string, options: PackCommandOptions): Promise<ToolResult>;
+    /**
+     * Copy a solution directory into a fresh temp workspace so a dry run can
+     * mutate it freely. Returns `undefined` when no copy is needed (a real
+     * pack, or a `.uis` input), which leaves the caller on the original path.
+     *
+     * The copy keeps the source's basename: `createPackOptions` derives the
+     * package name from the user-supplied path, but member-project and
+     * `.uipx` lookups walk the copied tree, so the two must agree.
+     */
+    private copyDirectoryForDryRun;
+    /**
+     * Remove a dry-run copy. Best-effort: the copy lives in the OS temp dir and
+     * the user never sees the path, so failures only log at debug.
+     */
+    private discardDryRunCopy;
     /**
      * Find the member project directory that is equal to or contains the
      * resolved output path, if any. Manifest read errors are ignored here —

package/dist/services/package-metadata-rewrite.d.ts

@@ -24,11 +24,15 @@ export interface PackageMetadataRewriteResult {
  * downloaded with `packages download`) cannot re-pack it.
  *
  * Only `solutionMetadata.json` carries the solution-level name and version. The
- * project packages bundled under `files/` keep their own identities — they are
- * addressed by `resources.json` / `configurations/**` through their own
- * `<project>.<type>.<project>:<version>` keys, which are independent of the
- * solution package's name and version. So this rewrite deliberately touches one
- * entry and copies everything else through byte-for-byte.
+ * project packages bundled under `files/<projectId>/` keep their own identities:
+ * each process resource in the split `resources/**` tree names its package id in
+ * `spec.packageName` and points at the sibling `package`-kind resource by uuid
+ * (`spec.package.key`). The bundled package's version is not in the resource
+ * tree at all — it rides in the payload file name,
+ * `files/<projectId>/<packageId>.<version>.nupkg`. None of it
+ * derives from the solution package's name or version, so this rewrite
+ * deliberately touches one entry and copies everything else through
+ * byte-for-byte.
  *
  * `spec.packageVersionKey` is always regenerated. The feed honors the key from
  * the archive verbatim, so carrying the source package's key over would file the

package/dist/services/publish-service.d.ts

@@ -1,7 +1,7 @@
 import { type ErrorContext, type RetryHint } from "@uipath/common";
 import { type FeedScope } from "./feed-resolver";
 /** Discriminator for {@link PublishFailure}; library callers can ignore the tag and read `.message` / `.ok`. */
-export type PublishFailureReason = "auth_failed" | "file_not_found" | "not_a_zip" | "not_packed" | "file_read_failed" | "metadata_rewrite_failed" | "personal_workspace_resolution_failed" | "feed_resolution_failed" | "upload_failed" | "upload_rejected" | "upload_version_conflict" | "upload_network" | "poll_timeout" | "poll_failed" | "poll_aborted" | "publish_failed";
+export type PublishFailureReason = "auth_failed" | "file_not_found" | "not_a_zip" | "not_packed" | "project_package" | "file_read_failed" | "metadata_rewrite_failed" | "personal_workspace_resolution_failed" | "feed_resolution_failed" | "upload_failed" | "upload_rejected" | "upload_version_conflict" | "upload_network" | "poll_timeout" | "poll_failed" | "poll_aborted" | "publish_failed";
 export interface PublishOptions {
     /** Override the active tenant for auth resolution. The CLI's deprecated `--tenant` flag flows through here. */
     tenant?: string;
@@ -35,10 +35,10 @@ export interface PublishSuccess {
     /** Orchestrator's stable key for this exact version (uuid). Always populated. */
     packageVersionKey: string;
     /**
-     * Package name as published. Optional because PW publish enriches metadata
-     * via a follow-up `packagesGetVersion` call that can briefly 404 due to
-     * feed indexing lag — when that happens, the upload is still authoritative
-     * but the human-readable name is absent.
+     * Package name as published. Optional because a feed/PW publish enriches
+     * metadata via a follow-up, feed-scoped `packagesGetVersion` call; if that
+     * call fails the upload is still authoritative but the human-readable name
+     * is absent.
      */
     packageName?: string;
     /** Package version (semver). Optional for the same reason as `packageName`. */
@@ -79,9 +79,11 @@ export type PublishResult = PublishSuccess | PublishFailure;
  *  - **Tenant feed (default)**: `PipelinesApi.pipelinesPackageUpload` —
  *    returns a full DTO including packageName/version/state. The CI service
  *    principal is authorized for this endpoint; do not unify on the AS path.
- *  - **Personal Workspace** (`personalWorkspace: true`): `PackagesApi.packagesUpload`
- *    with `locationKey` set to the PW folder key — returns a packageVersionKey
- *    GUID only. A follow-up `packagesGetVersion` enriches metadata best-effort
- *    (can 404 on indexing lag — handled gracefully).
+ *  - **Personal Workspace or folder feed** (`personalWorkspace: true` /
+ *    `feed`): `PackagesApi.packagesUpload` with `locationKey` set to the feed's
+ *    folder key — returns a packageVersionKey GUID only. A follow-up
+ *    `packagesGetVersion` enriches metadata best-effort, and must carry the
+ *    same feed scope as the upload: unscoped, it 404s for anything outside the
+ *    tenant feed.
  */
 export declare function publishSolutionAsync(packagePath: string, options?: PublishOptions): Promise<PublishResult>;

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

@@ -0,0 +1,34 @@
+import { type CliErrorCode } from "@uipath/common";
+import type { FileSystemStats, IFileSystem } from "@uipath/filesystem";
+/**
+ * Next-step hint for a bad `<solutionPath>`. Restore, pack and cleanup accept
+ * exactly the same two shapes, so they give the same advice.
+ */
+export declare const SOLUTION_PATH_INSTRUCTIONS = "Ensure the solution path exists and points to a solution directory (containing .uipx) or a .uis file.";
+export type SolutionPathFailureKind = 
+/** `stat` threw — the path may well exist, but it could not be read. */
+"unreadable"
+/** `stat` came back empty — there is no such path. */
+ | "missing"
+/** The path is there but is neither a directory nor a `.uis` file. */
+ | "wrong-type";
+export type SolutionPathCheck = {
+    ok: true;
+    absoluteSolutionPath: string;
+    isUisFile: boolean;
+    stats: FileSystemStats;
+} | {
+    ok: false;
+    absoluteSolutionPath: string;
+    kind: SolutionPathFailureKind;
+    message: string;
+    errorCode?: CliErrorCode;
+    statError?: Error;
+};
+/**
+ * Resolve `solutionPath` and say what it is: a solution directory, a `.uis`
+ * file, or one of three ways of being unusable. Callers render a failure in
+ * their own idiom — an OutputFormatter envelope on the CLI paths, a ToolResult
+ * on the programmatic ones.
+ */
+export declare function checkSolutionPathAsync(fs: IFileSystem, solutionPath: string): Promise<SolutionPathCheck>;