@uipath/solution-tool 1.203.0-preview.212 → 1.204.0-preview.211

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

@@ -0,0 +1,119 @@
+import type { DeploymentsApi, InitOverrideFunction } from "@uipath/solution-sdk";
+/**
+ * A deployed resource the service flags `requiresConfiguration` — the reason a
+ * deployment sits in `NeedsSetupToActivate` instead of running.
+ */
+export interface PendingResource {
+    key: string;
+    name: string;
+    /** The service's resource kind: `connection`, `asset`, `process`, … */
+    kind: string;
+    /** Service-specific type — the connector key of a connection, `stringAsset` for an asset. */
+    type?: string | null;
+    /**
+     * Why it needs configuration, from the deployment's activation validation:
+     * `[CNS1072] You will need to authenticate this connection before
+     * proceeding further`. Absent when that result could not be read or names
+     * no error for the resource.
+     */
+    reason?: string;
+}
+/** The fields the state helpers read. Both deployment DTOs carry them. */
+export interface DeploymentStateRecord {
+    name: string;
+    operation?: string | null;
+    operationStatus?: string | null;
+    activationStatus?: string | null;
+    packageVersion?: string | null;
+    currentPackageVersion?: string | null;
+}
+/**
+ * A deployment name as an argument in a suggested command, for the shells the
+ * suggestion is pasted into. Single quotes only: neither PowerShell nor a
+ * POSIX shell evaluates anything inside them, so a name carrying `$(…)` or a
+ * backtick stays a name. Double quotes would not do — both shells expand
+ * `$(…)` inside them. A name with an apostrophe uses the POSIX
+ * close-and-reopen escape, `'\''`; PowerShell reads that as a parse error
+ * rather than running anything, which is the acceptable failure for a name
+ * that rare.
+ */
+export declare function quoteForShell(name: string): string;
+/**
+ * The resources a deployment still needs configured before it can be
+ * activated.
+ *
+ * `GET /api/deployments/{key}/resources` is the one place the service says
+ * *why* a deployment is not live: every row carries `requiresConfiguration`.
+ * Ask with the deployment key alone. Its `folderKey` parameter is the
+ * solution-internal folder, not the Orchestrator folder the deployment landed
+ * in, and the wrong one is a 400 (measured 2026-09-23).
+ *
+ * Best-effort: `undefined` when the read fails — or when the page cap cut the
+ * listing short, because a partial list presented as "the pending resources"
+ * would omit rows. Every caller is reporting a state that is already final,
+ * so neither turns into a failed command; the callers say the read failed.
+ */
+export declare function readPendingResourcesAsync(api: DeploymentsApi, deploymentKey: string, scope?: InitOverrideFunction): Promise<PendingResource[] | undefined>;
+/**
+ * One line naming the resources and, when known, why each needs
+ * configuration: `connection 'Outlook' (uipath-microsoft-outlook365): [CNS1072]
+ * You will need to authenticate this connection before proceeding further;
+ * asset 'Config' (stringAsset)`, cut short past ten. The type is left out
+ * when it only repeats the kind.
+ */
+export declare function formatPendingResources(resources: PendingResource[]): string;
+/**
+ * What is left before a deployment runs, read from its `activationStatus`.
+ *
+ * `OperationStatus: Successful` only says the content is in place; whether it
+ * runs is a second axis, and the two disagree exactly when an upgrade lands in
+ * `NeedsSetupToActivate` — installed, reported successful, not live
+ * (STUD-81555). Returns `undefined` for `Active`, where nothing is left, and
+ * for the states that ask nothing of the user.
+ *
+ * `pendingResources` is what {@link readPendingResourcesAsync} returned:
+ * `undefined` when the read failed, which is said rather than hidden.
+ */
+export declare function activationNextSteps(deployment: DeploymentStateRecord, pendingResources?: PendingResource[]): string[] | undefined;
+/**
+ * Append the deployment's own state to error instructions when that state is
+ * the reason the command was refused — a pending draft, or an install that is
+ * waiting for setup. The generic instructions cover neither, and the
+ * service's refusal (`4007 … cannot be activated`) names neither.
+ *
+ * A `Draft` means different things by `operation`: an Install draft is a
+ * deploy whose install never completed; an ActivationSetup draft is a setup
+ * the UI started and did not finish; a VersionChange draft is an upgrade that
+ * was queued and never installed. Branching on `operationStatus` alone sent
+ * every one of them to "fix the deploy run validation errors" (STUD-81555).
+ */
+export declare function appendDeploymentStateInstructions(instructions: string, deployment?: DeploymentStateRecord, pendingResources?: PendingResource[], feedSelector?: string): string;
+/**
+ * The state that explains why the service refused to act on a deployment:
+ * a pending draft, or an install waiting for setup. `undefined` for every
+ * other state — there the refusal has some other cause, and the caller's
+ * generic advice stands.
+ */
+export declare function explainRefusal(deployment: DeploymentStateRecord, pendingResources?: PendingResource[], feedSelector?: string): string[] | undefined;
+/**
+ * Whether the resources route has something to say about a record: an
+ * installed deployment waiting for setup, or the `ActivationSetup` draft the
+ * Orchestrator wizard leaves behind when it is started and not finished. The
+ * draft answers the route too, and `deploymentsGetByKey` reports its
+ * `activationStatus` as `None` where the search row says
+ * `NeedsSetupToActivate` (both measured 2026-09-23) — hence the operation is
+ * checked as well as the status.
+ */
+export declare function needsPendingResources(deployment: DeploymentStateRecord): boolean;
+/**
+ * What is left before a deployment runs, read from both axes. A `Draft` is a
+ * pending operation and is described as one — for an `ActivationSetup` draft
+ * together with the resources it waits for; every other record defers to
+ * {@link activationNextSteps}.
+ *
+ * `feedSelector` is the flag a generated `deploy list` needs to read the same
+ * feed the caller did (`feedSelectorFlag`); empty for the tenant feed. The
+ * `activate` and `delete` commands the texts name find their feed themselves
+ * and take none.
+ */
+export declare function deploymentNextSteps(deployment: DeploymentStateRecord, pendingResources?: PendingResource[], feedSelector?: string): string[] | undefined;

package/dist/services/feed-resolver.d.ts

@@ -1,4 +1,6 @@
+import { type CliErrorCode, type ErrorContext, type RetryHint } from "@uipath/common";
 import type { InitOverrideFunction } from "@uipath/solution-sdk";
+import type { SolutionAuthContext } from "@uipath/solution-sdk/auth";
 /** Which feed a publish/deploy/query is scoped to. */
 export type FeedKind = "tenant" | "personal" | "folder";
 export interface FeedScope {
@@ -20,6 +22,15 @@ export interface FeedScope {
  */
 export declare function folderKeyInitOverride(folderKey: string): InitOverrideFunction;
 export declare function feedScopeInitOverride(scope: FeedScope): InitOverrideFunction | undefined;
+/**
+ * The flag a generated `uip solution deploy …` command must carry to read the
+ * same feed the caller did: ` --personal-workspace`, ` --feed <folder key>`,
+ * or nothing for the tenant feed. A follow-up printed without it points an
+ * agent at the tenant feed, where a Personal Workspace record does not exist
+ * — the record it was just told about would then read as "not found".
+ * Leading space included, so callers append it to a command verbatim.
+ */
+export declare function feedSelectorFlag(scope: Pick<FeedScope, "kind" | "folderKey"> | undefined): string;
 export interface ResolveFeedScopeOptions {
     /** Target the caller's own Personal Workspace feed. */
     personalWorkspace?: boolean;
@@ -30,6 +41,26 @@ export interface ResolveFeedScopeOptions {
     envFilePath?: string;
 }
 export declare function feedResolutionFailureInstructions(options: Pick<ResolveFeedScopeOptions, "personalWorkspace" | "feed">): string;
+/** Everything an envelope needs to report a {@link resolveFeedScope} that threw. */
+export interface FeedResolutionFailure {
+    message: string;
+    instructions: string;
+    errorCode: CliErrorCode;
+    retry: RetryHint;
+    context?: ErrorContext;
+}
+/**
+ * Describe a {@link resolveFeedScope} that threw.
+ *
+ * An external app has no Personal Workspace, and the Orchestrator lookup
+ * refuses it with a generated-client error that says nothing on its own
+ * ("Response returned an error code"). So when an external app's lookup is
+ * refused — the server answered with a 4xx — the failure names the cause.
+ * Anything else keeps the error's own classification, for an external app
+ * too: a 5xx, a timeout or a network failure is an outage that another
+ * session would not fix, and must not read as `RetryWillNotFix`.
+ */
+export declare function describeFeedResolutionFailureAsync(error: unknown, options: Pick<ResolveFeedScopeOptions, "personalWorkspace" | "feed">, session: Pick<SolutionAuthContext, "accessToken" | "identity">): Promise<FeedResolutionFailure>;
 /**
  * Turn the CLI feed flags into a validated {@link FeedScope} — the single
  * choke point every feed-aware command uses.

package/dist/services/feed-session.d.ts

@@ -0,0 +1,70 @@
+import { type SessionIdentity } from "@uipath/auth";
+/** What the access token says about who is acting, as far as a feed is concerned. */
+export type FeedSessionVerdict = "user" | "application" | "unknown";
+/**
+ * Whether this session may send `X-UIPATH-FolderKey` and expect it honoured.
+ *
+ * Not an authorization decision — the server makes those — but a prediction
+ * of what the server does with the header: its authorization filter applies
+ * it on the user-token branch only, so an application token's request runs
+ * against the tenant feed and, for an install, creates or updates a
+ * deployment there under the requested name. The doc comment on
+ * `resolveSessionIdentity` is right that it must never decide *trust*; here
+ * it decides whether to make a request whose wrong outcome is a mutation of
+ * the wrong feed, and a session it cannot classify fails closed for the same
+ * reason: the cost of refusing is one `uip login`, the cost of guessing wrong
+ * is a deployment in the wrong place.
+ *
+ * The auth context's `identity` is preferred: the login status resolved it
+ * from the token's claims *and* the auth flow this CLI persisted at login
+ * (`client_credentials` marks an application even on a token whose claims
+ * say nothing), which decoding the token here again cannot know. The decode
+ * is the fallback for a context that carries none.
+ */
+export declare function classifyFeedSession(session: {
+    accessToken: string;
+    identity?: SessionIdentity;
+}): FeedSessionVerdict;
+/**
+ * The message and instructions for a refused feed-scoped request.
+ *
+ * @param action what was asked, e.g. "Deploying into a Personal Workspace"
+ * @param alternative what else the caller can do, e.g. "deploy the package to the tenant feed"
+ */
+export declare function feedSessionRefusal(verdict: Exclude<FeedSessionVerdict, "user">, action: string, alternative: string): {
+    message: string;
+    instructions: string;
+};
+/**
+ * The refusal an external app gets for a *read* of a feed other than the
+ * tenant's — `deploy list` / `deploy status` with `--feed` or
+ * `--personal-workspace` — or undefined for any other session.
+ *
+ * The server ignores `X-UIPATH-FolderKey` on client-credentials requests, so
+ * the read would answer the tenant feed's rows as if they were the selected
+ * feed's (measured on staging). Unlike a mutation, a session whose kind cannot
+ * be read is let through: the worst it gets is a wrong read, which a refusal
+ * would only trade for a broken one that worked before.
+ */
+export declare function feedReadRefusalForApplication(session: {
+    accessToken: string;
+    identity?: SessionIdentity;
+}, action: string): {
+    message: string;
+    instructions: string;
+} | undefined;
+/**
+ * A feed read refused for an external app (see
+ * {@link feedReadRefusalForApplication}), raised where the refusal is found
+ * so the command can report it as `permission_denied`.
+ */
+export declare class FeedReadRefusedError extends Error {
+    readonly refusal: {
+        message: string;
+        instructions: string;
+    };
+    constructor(refusal: {
+        message: string;
+        instructions: string;
+    });
+}

package/dist/services/folder-helper.d.ts

@@ -1,39 +1,16 @@
-/**
- * Resolve parent folder from --parent-folder-path, --parent-folder-key, or
- * --personal-workspace options.
- *
- * Returns the fully qualified folder path string the deploy endpoint expects
- * as `folderFullyQualifiedName`, or undefined if none of the three options
- * was provided.
- *
- * Mutual exclusivity is enforced at parse time by Commander via
- * `Option#conflicts()` in the calling command — see `deploy-run.ts`.
- * Personal Workspace is resolved via Orchestrator's `GetPersonalWorkspace`
- * endpoint using the current auth context — see
- * {@link resolvePersonalWorkspace} for the contract.
- */
+/** The folder's full path, or `undefined` when no folder option was given. */
 export declare function resolveParentFolder(options: {
     folderPath?: string;
     folderKey?: string;
     personalWorkspace?: boolean;
     tenant?: string;
     loginValidity?: number;
-    /** Pin folder-lookup auth to this exact `.uipath/.auth` path, forwarded to
-     *  `resolvePersonalWorkspace`/`resolveFolder` so it matches the deploy auth. */
+    /** Same `.uipath/.auth` path as the caller, so the lookup uses its auth. */
     envFilePath?: string;
 }): Promise<string | undefined>;
 /**
- * Resolve a folder to its full identity — key plus canonical FQN — from
- * --parent-folder-path or --parent-folder-key.
- *
- * Unlike {@link resolveParentFolder}, which passes a --parent-folder-path
- * through verbatim (the tenant Pipelines install takes an FQN and validates
- * server-side), this always hits the Folders API: feed deploys need the
- * location folder's *key* for the auto-install request's
- * `installationFolderKey` — the server creates the solution folder under that
- * key, so sending the wrong one silently installs in the wrong place.
- *
- * Returns `undefined` when neither option was provided.
+ * Key and full path of a folder, always read from the Folders API: feed
+ * deploys install under the key, so a wrong one installs in the wrong place.
  */
 export declare function resolveFolderInfo(options: {
     folderPath?: string;

package/dist/services/http-status.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The HTTP status an SDK error carries — from the `Response` a generated
+ * client attaches, or from the error's own `status` — and `undefined` when it
+ * carries none (a transport failure, a thrown string). Lets a caller tell the
+ * one status that means "no such record" (404) from every other failure.
+ */
+export declare function httpStatusOf(error: unknown): number | undefined;
+/** A 401/403: the server refused this login, as opposed to failing. */
+export declare function isAuthRefusal(error: unknown): boolean;

package/dist/services/incomplete-feed-sweep.d.ts

@@ -0,0 +1,77 @@
+import { type CliErrorCode, type RetryHint } from "@uipath/common";
+import type { FeedKind } from "./feed-resolver";
+/**
+ * Why a feed was not searched.
+ *
+ * - `search_failed`: the feed's own search failed.
+ * - `listing_failed`: the publish-locations listing failed, so the entry
+ *   stands for every folder feed — none of them was known, let alone searched.
+ * - `workspace_unresolved`: the listing failed and resolving the Personal
+ *   Workspace through Orchestrator failed too, so its key is unknown.
+ * - `no_key`: the listing named the feed but gave it no folder key, and a
+ *   search without one would go to the tenant feed instead.
+ */
+export type SkipReason = "search_failed" | "listing_failed" | "workspace_unresolved" | "no_key";
+/**
+ * A feed the deployment sweep could not search, and why.
+ *
+ * `tenant` appears only when the tenant search itself failed. The sweep stops
+ * there, so no other feed was searched either.
+ */
+export interface SkippedFeed {
+    kind: FeedKind;
+    reason: SkipReason;
+    /** The feed's folder key, when the sweep knew it. */
+    folderKey?: string;
+    /** The feed's name from the listing, for a `no_key` row. */
+    name?: string;
+    error: Error;
+}
+/** How an incomplete miss is reported: which feeds, how retryable, and what to do. */
+export interface IncompleteSweepReport {
+    /** Says the name was not found where the sweep could look, and names the feeds it could not. */
+    message: string;
+    errorCode: CliErrorCode;
+    retry: RetryHint;
+    /** The cause's error details, for the `Details:` tail of the instructions. */
+    details: string;
+    /** What to do about the cause: log in, fix access, or retry. */
+    nextStep: string;
+    /**
+     * The feed flags that can still look in one feed directly, in the order
+     * to suggest them; empty when none can. Each verb puts them in its own
+     * command.
+     */
+    oneFeedFlags: string[];
+}
+/**
+ * Whether a refusal from the tenant feed is one a skipped feed can explain: a
+ * 404, or a 400. `activate` and `uninstall` send only the deployment name, so
+ * their 400 is about the name or feed (`4007 … cannot be activated`, "cannot
+ * be uninstalled"). A 409 or 422 shares `invalid_argument` with that 400, but
+ * like every other class it is the request's own answer.
+ */
+export declare function isNameOrFeedRefusal(errorCode: CliErrorCode, httpStatus: number | undefined): boolean;
+/** The sentence every verb opens its instructions with; each adds its own way out. */
+export declare const INCOMPLETE_SWEEP_ADVICE = "The deployment may be in a feed that was not searched.";
+/**
+ * What the user can do about a failure of this class. The retry case names
+ * the service to wait for; the others do not depend on it.
+ */
+export declare function retryAdvice(errorCode: CliErrorCode, retry: RetryHint, service: string): string;
+/**
+ * Describe a sweep that found nothing but could not search every feed.
+ *
+ * The classification is the cause's own — a 503 stays `server_error` /
+ * `RetryLater`, a dropped connection `network_error`, a 403
+ * `permission_denied` / `RetryWillNotFix`. The cause is the first skipped
+ * feed whose failure has a known class, so a key-less row listed before a
+ * search that answered 403 does not hide the 403; with none, it is the first.
+ * Two classes are overridden, because "a feed did not answer" is not "no such
+ * deployment": a feed that answered 404 is not reported as `not_found`, and a
+ * failure with no known class does not rule a retry out. Both become
+ * `unknown_error` / `RetryLater` — except when every skipped feed is a listed
+ * row with no key: the listing answered, so a retry gets the same rows, and
+ * that is `unknown_error` / `RetryWillNotFix` with its own next step.
+ */
+export declare function reportIncompleteSweepAsync(deploymentName: string, skipped: readonly SkippedFeed[]): Promise<IncompleteSweepReport>;

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

@@ -0,0 +1,23 @@
+import { type DeploymentSearchItemDto2, type DeploymentsSearchRequest2, type InitOverrideFunction } from "@uipath/solution-sdk";
+import type { SolutionAuthContext } from "@uipath/solution-sdk/auth";
+import type { DeploymentSearchQuery } from "./deployment-search-client";
+/**
+ * The deployment search as it was before the Pipelines route:
+ * `POST /api/v3/search/deployments`. It reads user tokens only, and has no
+ * exact-name filter, so a name travels as the substring `searchTerm` and the
+ * callers keep their own exact match.
+ *
+ * @deprecated A bridge for rings that predate
+ * `POST /v1/pipelines/deployments/search` (SOL-7807), not a second path.
+ * Reached only through `searchDeploymentsPage`, and only when the server
+ * answers the Pipelines route with "no such route". Remove this file, its
+ * branch in `deployment-search-client.ts`, and the `/api/v3/search/deployments`
+ * entry the solution-sdk generator keeps for it, once the Pipelines route is on
+ * every production ring.
+ */
+export declare function searchDeploymentsLegacyV3(auth: SolutionAuthContext, query: DeploymentSearchQuery, scope?: InitOverrideFunction): Promise<{
+    count?: number;
+    values: DeploymentSearchItemDto2[];
+}>;
+/** @deprecated See {@link searchDeploymentsLegacyV3}. */
+export declare function toLegacyV3Request(query: DeploymentSearchQuery): DeploymentsSearchRequest2;

package/dist/services/packages-list-service.d.ts

@@ -1,3 +1,4 @@
+import { type CliErrorCode, type ErrorContext, type RetryHint } from "@uipath/common";
 import type { SortDirection } from "./deploy-list-service";
 /**
  * Per-package row in {@link ListPackagesSuccess.packages}. Mirrors solution-sdk's
@@ -60,6 +61,10 @@ export interface ListPackagesFailure {
     message: string;
     instructions: string;
     exitCode: number;
+    /** Set when the failure mode is known; the formatter infers one otherwise. */
+    errorCode?: CliErrorCode;
+    retry?: RetryHint;
+    context?: ErrorContext;
 }
 export type ListPackagesResult = ListPackagesSuccess | ListPackagesFailure;
 /**

package/dist/services/pipeline-deploy-poll.d.ts

@@ -0,0 +1,69 @@
+import { type PollUntilResult } from "@uipath/common";
+import type { PipelineDeploymentResult, PipelineDeploymentStatus, PipelinesApi } from "@uipath/pipelines-sdk";
+import type { InitOverrideFunction } from "@uipath/solution-sdk";
+import type { SolutionAuthContext } from "@uipath/solution-sdk/auth";
+/**
+ * Statuses at which `GET /v1/pipelines/deployments/{id}/deployment-status`
+ * stops changing. `ValidationFailed` is terminal: the pipeline validates
+ * against the target *before* it schedules the install, and a failed
+ * validation never schedules one.
+ */
+export declare const PIPELINE_TERMINAL_STATUSES: ReadonlySet<PipelineDeploymentStatus>;
+export interface PipelineDeployPollOptions {
+    /** From the `pipelinesInstall` response. */
+    pipelineDeploymentId: string;
+    /** The deployment being installed — the search-service fallback looks it up by name. */
+    deploymentName: string;
+    /**
+     * `X-UIPATH-FolderKey` override for a feed / Personal Workspace
+     * deployment; undefined for the tenant feed. Applied to the status read
+     * *and* to the search fallback — a tenant-scoped search cannot see a feed
+     * deployment, so the fallback would report "gone" without it.
+     */
+    scope?: InitOverrideFunction;
+    timeoutMs: number;
+    intervalMs: number;
+    /** Host-side cancellation (Ctrl-C, VS Code cancel). */
+    signal?: AbortSignal;
+    /** Prefix for the poll's progress log lines, e.g. `"deploy"` or `"deploy upgrade"`. */
+    logPrefix: string;
+}
+/**
+ * A terminal result the poll produced from the deployment's own record rather
+ * than the pipelines run. `synthesizedOperation` is set only on that path:
+ * the record carries the deployment's `operation` (`VersionChange` vs
+ * `ConfigurationChange`), which the pipelines DTO reports under
+ * `deploymentResult` and a synthesized result would otherwise lose.
+ */
+export type PolledPipelineResult = PipelineDeploymentResult & {
+    synthesizedOperation?: string;
+};
+/**
+ * Poll a Pipelines install to a terminal state.
+ *
+ * The pipelines service recycles its in-flight record once the run is
+ * terminal, after which the status endpoint answers 404
+ * `PipelineDeploymentNotFound`. That 404 is not an error: the persistent
+ * record lives in the search service, so the read falls back to it and
+ * synthesises a terminal result from the deployment's `operationStatus`.
+ *
+ * Which record is this run's is decided by **identity, never by name**.
+ * Every status read carries `deploymentKey`, the run's own deployment row
+ * (the run record references it from creation, and the first read happens
+ * as soon as the install is accepted), so by the time the record is recycled
+ * the poll knows exactly which row to ask for. Nothing else can pass for it:
+ * not another generation of the same name, not a concurrent run reusing it,
+ * not an uninstall's history row. Two reads answer for that key, in order:
+ * the Pipelines by-key lookup, which takes S2S and so serves the CI/CD
+ * caller this command exists for; then the Solutions search, for user
+ * sessions on a server that predates the lookup. Without a key — the record
+ * recycled before any read answered — the poll does not guess from the name:
+ * it reports the run as still in flight and lets the caller's deadline
+ * decide, which at worst is an honest timeout pointing at `deploy list`. The
+ * same holds while the record is not indexed yet or still `Draft`.
+ *
+ * Returns the raw `pollUntil` result so each command keeps its own
+ * interpretation — `deploy run` recovers activation states that `deploy
+ * upgrade` never sees.
+ */
+export declare function pollPipelineDeploymentAsync(api: PipelinesApi, auth: SolutionAuthContext, options: PipelineDeployPollOptions): Promise<PollUntilResult<PolledPipelineResult>>;

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

@@ -35,15 +35,15 @@ export interface PublishSuccess {
     /** Orchestrator's stable key for this exact version (uuid). Always populated. */
     packageVersionKey: string;
     /**
-     * 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.
+     * Package name as published. Every feed now uploads through the Pipelines
+     * endpoint, which answers with the full version DTO, so this is populated
+     * in practice; it stays optional because it is part of the published
+     * result type and callers already branch on its absence.
      */
     packageName?: string;
-    /** Package version (semver). Optional for the same reason as `packageName`. */
+    /** Package version (semver). */
     packageVersion?: string;
-    /** Terminal state when `wait: true` (`"Ready"`/`"Active"`), else the upload's immediate state. Optional for the same reason. */
+    /** Terminal state when `wait: true` (`"Ready"`/`"Active"`), else the upload's immediate state. */
     state?: string;
     /** Which feed the package landed in — drives telemetry `target`. */
     feedKind: FeedScope["kind"];
@@ -75,15 +75,13 @@ export type PublishResult = PublishSuccess | PublishFailure;
  * {@link PublishResult} for expected failures; re-throws only on unexpected
  * SDK errors. Does not touch `OutputFormatter` / `processContext`.
  *
- * Two upload paths:
- *  - **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 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.
+ * One upload path for every feed: `PipelinesApi.pipelinesPackageUpload`
+ * (`POST /v2/pipelines/packages`), with `locationKey` selecting the feed —
+ * absent for the tenant feed, the feed's folder key for a Personal Workspace
+ * or folder feed. It answers with the full version DTO, so name/version/state
+ * need no follow-up lookup, and the CI service principal is authorized for it.
+ * The Automation Solutions upload it replaces was only ever needed because the
+ * v1 Pipelines route hardcodes `locationKey: null` server-side and so cannot
+ * leave the tenant feed.
  */
 export declare function publishSolutionAsync(packagePath: string, options?: PublishOptions): Promise<PublishResult>;

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

@@ -0,0 +1,27 @@
+import { type CliErrorCode, type ErrorContext, type RetryHint } from "@uipath/common";
+import type { SolutionAuthContext } from "@uipath/solution-sdk/auth";
+/** Everything an envelope needs to report a failed Solution Search listing. */
+export interface SearchFailure {
+    message: string;
+    instructions: string;
+    errorCode: CliErrorCode;
+    retry: RetryHint;
+    context?: ErrorContext;
+}
+/**
+ * Describe a failed Solution Search listing (`packages list`, `deploy list`).
+ *
+ * The packages search accepts user tokens only, so it answers an external app
+ * with a 401. The generic 401 text says the session is missing or expired,
+ * which sends a client-credentials pipeline in a circle: logging in again
+ * mints the same kind of token. For that session the failure names the cause
+ * instead. The Pipelines deployment search `deploy list` reads accepts
+ * application tokens, so it passes `userSessionsOnly: false`: there an app's
+ * 401 is the session's own failure. Every other failure keeps the service's
+ * own message, with its HTTP status classified into `errorCode` / `retry`.
+ *
+ * @param what the rows being listed, e.g. "packages"
+ */
+export declare function describeSearchFailureAsync(error: unknown, what: string, session: Pick<SolutionAuthContext, "accessToken" | "identity">, { userSessionsOnly }: {
+    userSessionsOnly: boolean;
+}): Promise<SearchFailure>;