@uipath/common 1.199.0 → 1.201.0-preview.115

package/dist/output-codecs.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Lazy loaders for the two output codecs that only some invocations need.
+ *
+ * `formatter.ts` is imported by every command in every tool, so anything it
+ * imports statically is parsed on every `uip` invocation — including
+ * `uip <tool> -h`. `js-yaml` (101 KB) is only reached by `--output yaml` and
+ * `@jmespath-community/jmespath` (68 KB) only by `--output-filter`, so both
+ * live behind `await import` here instead.
+ *
+ * The API is split in two on purpose:
+ *
+ *  - `loadOutputCodecsAsync` is awaited from the async paths that already know
+ *    what the user asked for — the CLI host right after it resolves `--output`
+ *    and `--output-filter`, and `trackedAction` before it runs a handler.
+ *  - `getYamlCodec` / `getJmespathCodec` are the synchronous accessors
+ *    `OutputFormatter` uses, because the formatter API is synchronous.
+ *
+ * Loaded modules live in cross-bundle singleton slots: each tool bundles its
+ * own copy of `@uipath/common`, so a module-level variable would be loaded by
+ * the host and then missing in the tool. See `singleton.ts`.
+ */
+/** The slice of `js-yaml` the formatter uses. */
+export interface YamlCodec {
+    dump: (data: unknown) => string;
+}
+/** The slice of `@jmespath-community/jmespath` the formatter uses. */
+export interface JmespathCodec {
+    compile: (expression: string) => unknown;
+    search: (data: never, expression: string) => unknown;
+}
+/** Which codecs an invocation needs, derived from the resolved CLI options. */
+export interface OutputCodecsNeeded {
+    /** True when the resolved output format is `yaml`. */
+    yaml?: boolean;
+    /** True when an `--output-filter` expression is present. */
+    filter?: boolean;
+}
+/**
+ * Load the codecs this invocation needs, if they are not loaded already.
+ *
+ * Safe to call repeatedly — a codec already in its slot is not re-imported.
+ * Call before any `OutputFormatter` output that could use them.
+ */
+export declare function loadOutputCodecsAsync(needed: OutputCodecsNeeded): Promise<void>;
+/**
+ * The loaded YAML codec, or `undefined` when nothing preloaded it.
+ *
+ * `undefined` means a code path produced `--output yaml` output without
+ * passing through the CLI host or `trackedAction` — a bug in that path, not a
+ * user error, so callers should throw rather than silently emit JSON.
+ */
+export declare function getYamlCodec(): YamlCodec | undefined;
+/** The loaded JMESPath codec, or `undefined` when nothing preloaded it. */
+export declare function getJmespathCodec(): JmespathCodec | undefined;
+/** Test seam — drops both codecs so a spec can assert the unloaded path. */
+export declare function resetOutputCodecs(): void;

package/dist/packager-tool-import.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Import a tool's `packager-tool` entry point and run its registration.
+ *
+ * Its own module so tests can stand in for it. The real entry points are
+ * multi-megabyte tool bundles; loading one takes seconds and blocks the event
+ * loop while it evaluates, which is far too slow for a unit test.
+ */
+/** Named export every in-repo `packager-tool` entry point must provide. */
+export declare const REGISTER_EXPORT = "registerPackagerFactories";
+/** Shape of a `packager-tool` entry point's module namespace. */
+export interface PackagerToolModule {
+    [REGISTER_EXPORT]?: () => void;
+}
+/**
+ * Import `specifier` and call its `registerPackagerFactories` export. Returns
+ * the failure instead of throwing so the caller can decide what to say.
+ *
+ * Registration is a call, not an import side effect, so a run that reaches
+ * the same factories through two tool bundles registers them once — from the
+ * one caller that is about to pack.
+ *
+ * Tools published before that change register at import and ship no export.
+ * They still work: the import above already registered them, so treat a
+ * missing export as a legacy entry point instead of a failure. Tools that live
+ * in this repo must export it — `scripts/lint-packager-tool-exports.ts` fails
+ * the build if one doesn't.
+ */
+export declare function importPackagerTool(specifier: string): Promise<Error | undefined>;

package/dist/polling/terminal-statuses.d.ts

@@ -20,7 +20,7 @@
  * isTerminalStatus("FAULTED")    // true
  * ```
  */
-export declare function isTerminalStatus(status: string): boolean;
+export declare function isTerminalStatus(status: string | null | undefined): boolean;
 /**
  * Check if a status string represents a failure state (case-insensitive).
  *
@@ -34,7 +34,7 @@ export declare function isTerminalStatus(status: string): boolean;
  * isFailureStatus("Cancelled")  // true
  * ```
  */
-export declare function isFailureStatus(status: string): boolean;
+export declare function isFailureStatus(status: string | null | undefined): boolean;
 /**
  * Check if a status string represents a successful terminal state (case-insensitive).
  *
@@ -47,4 +47,4 @@ export declare function isFailureStatus(status: string): boolean;
  * isSuccessStatus("Running")    // false
  * ```
  */
-export declare function isSuccessStatus(status: string): boolean;
+export declare function isSuccessStatus(status: string | null | undefined): boolean;

package/dist/solution-project-artifacts.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared `ensureProjectArtifacts` used by every `*-tool init` path (agent,
+ * case, codedapp, flow, maestro). Lives here so the five tools don't each
+ * carry a copy; each tool re-exports it from its own
+ * `src/services/project-artifacts.ts` shim (the browser-build
+ * `excludedImports` stub mechanism resolves only relative paths under each
+ * tool's own src tree).
+ */
+/** Options forwarded to solution-tool's `addProjectArtifactsToSolutionAsync`. */
+export interface EnsureProjectArtifactsArgs {
+    /** Absolute path to the solution directory (containing the `.uipx`). */
+    solutionDir: string;
+    /** Stable project key — must match the `Id` in `.uipx` `Projects[]`. */
+    projectId: string;
+    /** Display name for the project; typically the project folder name. */
+    projectName: string;
+    /** Project type as written to `project.uiproj` (e.g. `Flow`, `Agent`). */
+    projectType: string;
+    /** Optional SDK subType (AppV2: `"Coded"` / `"CodedAction"`). */
+    projectSubType?: string;
+}
+/**
+ * Result envelope. Structurally identical to `ProjectArtifactsResult` in
+ * `@uipath/solution-sdk/resources` — declared here too because this
+ * package sits below `solution-sdk` in the dependency graph and cannot import
+ * from it.
+ */
+export interface ProjectArtifactsResult {
+    /** True when artifact resources were generated. */
+    Created: boolean;
+    /** Error message when `Created` is `false`. */
+    Error?: string;
+}
+/**
+ * Generate the `resources/solution_folder/...` artifact-resource entries for
+ * a project that has just been registered in its parent solution's `.uipx`.
+ *
+ * The implementation is resolved at runtime from the installed
+ * `@uipath/solution-tool` (through the CLI host's tool-module provider, which
+ * installs it on demand), so the multi-megabyte resource-builder chain is
+ * never bundled into the calling tool.
+ */
+export declare function ensureProjectArtifacts(args: EnsureProjectArtifactsArgs): Promise<ProjectArtifactsResult>;

package/dist/solution-project-types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Guidance for a project type a solution cannot contain, or `null` when allowed.
+ * Lives in `@uipath/common` so `solution-tool`'s packager resolver can ask
+ * without importing the `@uipath/solution-sdk` barrel (which drags
+ * `@uipath/studioweb-sdk` in).
+ *
+ * A library registered as a project does not fail late, it deploys *wrong*: the
+ * resource builder has no library template, falls through to the default, and
+ * mints `kind: process`. Deploy then creates an Orchestrator process backed by a
+ * library package, which has no entry point. The SDK metadata agrees a library
+ * is not project-shaped: `kind: library` is `scope: Tenant`,
+ * `supportsInLineCreation: false`.
+ *
+ * Case-insensitive — `.uipx` writes PascalCase `Type`, `project.json` uses
+ * `designOptions.outputType`.
+ *
+ * Takes `unknown` because one caller (`ensurePackagerTools`) reads `Type`
+ * straight out of `.uipx` JSON, where it can be absent or not a string. Only a
+ * type positively known to be unsupported is rejected, so anything else is
+ * allowed through to the resolvers, which warn on their own.
+ */
+export declare function unsupportedSolutionProjectType(projectType: unknown): string | null;

package/dist/telemetry/index.js

@@ -86,7 +86,7 @@ var COMMAND_ATTRIBUTION = commandAttribution([
   ["agents", "build", ["uip.codedagent", "uip.agent"]],
   ["agenthub", "build", ["uip.agenthub"]],
   ["coded-apps", "build", ["uip.codedapp"]],
-  ["functions", "build", ["uip.functions"]],
+  ["functions", "build", ["uip.function", "uip.functions"]],
   ["solution", "build", ["uip.solution"]],
   ["maestro", "build", ["uip.maestro", "uip.case", "uip.flow"]],
   ["llm-observability", "troubleshoot", ["uip.traces"]],
@@ -762,14 +762,11 @@ class TelemetryService {
   }
   async trackDependencyOperation(name, type, fn, properties) {
     const parentContext = this.getCurrentContext();
-    if (!parentContext) {
-      throw new Error("trackDependencyOperation must be called within a trackRequest block.");
-    }
-    const childContext = {
+    const childContext = parentContext !== undefined ? {
       operationId: parentContext.operationId,
       parentId: parentContext.id,
       id: this.generateId()
-    };
+    } : this.createRequestContext();
     const startTime = performance.now();
     try {
       const result = await this.contextStorage.run(childContext, fn);
@@ -845,4 +842,4 @@ export {
   BrowserContextStorage
 };
 
-//# debugId=F57500BAC82BA8E664756E2164756E21
+//# debugId=E05A0A007C0249BF64756E2164756E21

package/dist/telemetry/node-appinsights-telemetry-provider.d.ts

@@ -1,6 +1,17 @@
 import type { ITelemetryProvider } from "./telemetry-provider.js";
 import { type TelemetryProperties } from "./telemetry-service.js";
 export { getGlobalTelemetryProperties, setGlobalTelemetryProperties, } from "./global-telemetry-properties.js";
+/**
+ * Envelopes still buffered in the SDK channel at exit, plus the ingestion
+ * endpoint they were headed to. The envelopes are fully formed (tags, ikey,
+ * time already baked in) — POSTing them newline-joined and gzipped to
+ * `endpointUrl` with `Content-Type: application/x-json-stream` is exactly
+ * what the SDK's own sender would have done.
+ */
+export interface PendingTelemetryEnvelopes {
+    endpointUrl: string;
+    envelopes: unknown[];
+}
 /**
  * Node.js Application Insights telemetry provider.
  * Uses the `applicationinsights` Node SDK (not the browser SDK).
@@ -67,6 +78,15 @@ export declare class NodeAppInsightsTelemetryProvider implements ITelemetryProvi
     trackRequest(name: string, duration: number, success: boolean, properties?: TelemetryProperties): Promise<void>;
     trackDependency(name: string, type: string, duration: number, success: boolean, properties?: TelemetryProperties, resultCode?: string): Promise<void>;
     flush(): Promise<void>;
+    /**
+     * Take the envelopes still buffered in the SDK channel (nothing has sent
+     * them yet), clearing the batch timer and the buffer so a later
+     * {@link shutdown} has nothing left to send or hold the event loop open
+     * with. Returns `undefined` when draining isn't possible (no client, no
+     * endpoint, or an unexpected SDK shape) — callers must then fall back to
+     * a normal in-process {@link flush}.
+     */
+    drainPendingEnvelopes(): PendingTelemetryEnvelopes | undefined;
     /**
      * Dispose the Application Insights SDK so its internal channels,
      * keep-alive sockets, and timers are closed — allowing the Node.js

package/dist/telemetry/proxy-http-agent.d.ts

@@ -0,0 +1,2 @@
+export declare function setProxyAuthHttpsAgent(agent: unknown): void;
+export declare function getProxyAuthHttpsAgent(): unknown;

package/dist/telemetry/telemetry-events.d.ts

@@ -1,4 +1,14 @@
+/**
+ * Canonical CLI event names.
+ *
+ * Every name lives under the `uip.*` namespace so a single
+ * `name startswith "uip."` filter selects all CLI telemetry — a snake_case
+ * name outside it is invisible to every downstream pipeline (STUD-80942).
+ */
 export declare const CommonTelemetryEvents: {
     readonly Error: "uip.error";
-    readonly ShipSucceeded: "ship_succeeded";
+    /** A ship (publish/deploy/upload) completed. The command that shipped is
+     * carried by the `command_name` dimension; `ship_kind`/`target` describe
+     * what was shipped where. */
+    readonly ShipSucceeded: "uip.ship.succeeded";
 };

package/dist/telemetry/telemetry-init.d.ts

@@ -41,8 +41,23 @@ export interface TelemetryInitOptions {
  */
 export declare function telemetryInit(options?: TelemetryInitOptions): Promise<void>;
 /**
- * Flush all buffered telemetry to the cloud.
- * Must be awaited before the process exits to ensure delivery.
- * Capped at FLUSH_SHUTDOWN_TIMEOUT_MS to avoid hanging on slow/unreachable endpoints.
+ * Deliver all buffered telemetry before the process exits.
+ * Must be awaited on every exit path.
+ *
+ * Normally hands the buffered envelopes to a detached sidecar process (see
+ * {@link trySidecarHandoff}) so the exit is instant. Falls back to the
+ * in-process flush — one ingestion round-trip, capped at
+ * FLUSH_SHUTDOWN_TIMEOUT_MS — when the sidecar handoff isn't available or
+ * UIPATH_TELEMETRY_SYNC_FLUSH=1 forces it.
  */
 export declare function telemetryFlushAndShutdown(): Promise<void>;
+/**
+ * Dispose the telemetry SDK without sending — buffered events are dropped
+ * on purpose. For exits where delivery is not worth a network round-trip
+ * (help/version display).
+ *
+ * Shares the memo slot with {@link telemetryFlushAndShutdown}: whichever
+ * runs first wins, so a later flush call on the same exit path awaits the
+ * already-finished shutdown instead of opening a network connection.
+ */
+export declare function telemetryShutdownWithoutFlush(): Promise<void>;

package/dist/telemetry/telemetry-service.d.ts

@@ -193,6 +193,11 @@ export interface ITelemetryService {
      * @remarks
      * Tracks this operation as a dependency in Application Insights, automatically correlated
      * to the parent request using the context from IContextStorage.
+     *
+     * With no enclosing request the dependency is emitted as a trace root (no
+     * `operation_ParentId`) rather than being dropped or throwing — a reusable
+     * unit of work stays a dependency even when the host that called it never
+     * opened a request of ours.
      */
     trackDependencyOperation<T>(name: string, type: string, fn: () => Promise<T>, properties?: TelemetryProperties): Promise<T>;
 }

package/dist/telemetry/telemetry-spool.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Hidden argv verb that makes the CLI entry point run the spool sender
+ * instead of the normal Commander pipeline. Never registered as a command —
+ * the entry point matches it on raw argv before the program is built.
+ */
+export declare const TELEMETRY_DRAIN_ARGV = "__uip-drain-telemetry";
+/**
+ * Register the script path that handles {@link TELEMETRY_DRAIN_ARGV}.
+ * Called once by the CLI entry point at startup; until it is called, the
+ * exit path keeps the in-process flush (no sidecar is ever spawned).
+ */
+export declare function setTelemetrySidecarEntry(entryPath: string): void;
+export declare function getTelemetrySidecarEntry(): string | undefined;
+/** Contents of one spool file. */
+export interface TelemetrySpoolPayload {
+    /** Full ingestion URL (`<IngestionEndpoint>/v2.1/track`). */
+    endpointUrl: string;
+    /** Fully-formed App Insights envelopes, exactly as the SDK buffered them. */
+    envelopes: unknown[];
+}
+/** A pending spool file claimed for sending (renamed to `.sending`). */
+export interface ClaimedSpoolFile {
+    /** The claimed (`.sending`) path — delete it after a successful send. */
+    claimedPath: string;
+    payload: TelemetrySpoolPayload;
+}
+/** Spool files older than this are deleted unsent — stale telemetry has no value. */
+export declare const MAX_SPOOL_AGE_MS: number;
+/** Hard cap on spool files; oldest beyond this are deleted (offline machines). */
+export declare const MAX_SPOOL_FILES = 50;
+export declare function getTelemetrySpoolDir(): string;
+/**
+ * Persist pending envelopes for the sidecar. Writes to a `.tmp` name first
+ * and renames into place so a concurrently-running sender never claims a
+ * half-written file. Returns the spool file path.
+ */
+export declare function writeTelemetrySpoolFile(payload: TelemetrySpoolPayload): Promise<string>;
+/**
+ * Claim every pending spool file for sending. Claiming renames the file to
+ * `.sending` — an atomic operation, so when two senders sweep concurrently
+ * only one wins each file and nothing is delivered twice. Files that fail
+ * the rename are skipped (another sender owns them).
+ *
+ * Bad content is split two ways on purpose: a file that cannot be READ is
+ * released for a later attempt (on Windows a concurrent handle shows up as a
+ * transient EBUSY, and deleting there would throw telemetry away for a problem
+ * that resolves itself), while a file that reads fine but does not parse or
+ * does not match the payload shape is deleted — no future sweep can make it
+ * valid, so keeping it would just burn a claim on every run until the age cap.
+ */
+export declare function claimPendingSpoolFiles(): Promise<ClaimedSpoolFile[]>;
+/**
+ * Return a claimed file to the pending pool so a future sender retries it.
+ * Best-effort: if the rename fails the file stays `.sending` and the age
+ * cap eventually removes it.
+ */
+export declare function releaseClaimedSpoolFile(claimedPath: string): Promise<void>;
+/** Delete a claimed file after its envelopes were delivered. Best-effort. */
+export declare function discardClaimedSpoolFile(claimedPath: string): Promise<void>;
+/**
+ * Enforce the spool bounds: delete any file older than
+ * {@link MAX_SPOOL_AGE_MS} — including `.sending` files orphaned by a
+ * crashed sender and `.tmp` files orphaned by a crashed writer — and keep at
+ * most {@link MAX_SPOOL_FILES} pending files, deleting the oldest beyond
+ * that. Run by the sender before claiming, so an unreachable endpoint can't
+ * grow the spool without bound.
+ */
+export declare function sweepTelemetrySpool(): Promise<void>;

package/dist/tool-module-import.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Dynamic import of another tool's library entry point (e.g.
+ * `@uipath/solution-tool/init`).
+ *
+ * Its own module so tests can stand in for it, and so the specifier stays a
+ * plain variable — bundlers then leave the `import()` to run at runtime
+ * instead of inlining the multi-megabyte target bundle into the caller.
+ */
+export declare function importToolModule(specifier: string): Promise<unknown>;

package/dist/tool-provider.d.ts

@@ -1,6 +1,38 @@
 /**
- * Cross-module bridge for packager factory resolution.
+ * Cross-module bridge for packager factory and tool-module resolution.
  */
 export type PackagerFactoryProvider = (verb: string) => Promise<void>;
 export declare function setPackagerFactoryProvider(provider: PackagerFactoryProvider): void;
-export declare function ensurePackagerFactory(verb: string): Promise<void>;
+export type ToolModuleProvider = (verb: string, moduleName: string) => Promise<unknown>;
+export declare function setToolModuleProvider(provider: ToolModuleProvider): void;
+/**
+ * Resolve another tool's library entry point (its `dist/<module>.js` subpath
+ * export) at runtime and return the module namespace.
+ *
+ * Prefers the registered provider (installed by the CLI — it can install the
+ * tool on demand and imports the entry by absolute path). With no provider —
+ * a library caller — falls back to importing `<packageName>/<moduleName>`,
+ * which resolves when the tool package is installed next to the caller.
+ *
+ * This is how one tool uses another tool's code without bundling it: the
+ * multi-megabyte implementation ships once, in the tool that owns it.
+ *
+ * @param verb - CLI tool verb that owns the module (e.g. `"solution"`).
+ * @param packageName - npm package behind that verb, used for the fallback
+ * import (e.g. `"@uipath/solution-tool"`).
+ * @param moduleName - subpath entry to load (e.g. `"init"`, `"resource"`).
+ */
+export declare function ensureToolModule(verb: string, packageName: string, moduleName: string): Promise<unknown>;
+/**
+ * Resolve the packager factory for a tool verb.
+ *
+ * Prefers the registered provider (installed by the CLI). With no provider —
+ * a library caller — falls back to the tool package's own `packager-tool`
+ * entry point: imports it and calls its `registerPackagerFactories` export.
+ *
+ * @param verb - CLI tool verb that owns the factory (e.g. `"maestro"`).
+ * @param packageName - npm package behind that verb. Drives the fallback
+ * import and is the one thing the error asks for. Omit when unknown; there is
+ * then no fallback and no package to name.
+ */
+export declare function ensurePackagerFactory(verb: string, packageName?: string): Promise<void>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@uipath/common",
   "license": "MIT",
-  "version": "1.199.0",
+  "version": "1.201.0-preview.115",
   "description": "Common infrastructure needed by uip tools.",
   "repository": {
     "type": "git",
@@ -28,6 +28,10 @@
       "types": "./dist/catch-error.d.ts",
       "default": "./dist/catch-error.js"
     },
+    "./guid": {
+      "types": "./dist/guid.d.ts",
+      "default": "./dist/guid.js"
+    },
     "./sdk-user-agent": {
       "browser": {
         "types": "./dist/sdk-user-agent.d.ts",
@@ -67,5 +71,5 @@
     "mihaigirleanu",
     "vlad-uipath"
   ],
-  "gitHead": "723e6801b77b5926ba75e75b6a756cc38b1b7adc"
+  "gitHead": "f1086b73654d7728cb71f280588b3e0c77d535fc"
 }