@uipath/common 0.1.15 → 0.9.0

package/README.md

@@ -16,7 +16,7 @@ npm install @uipath/common
 import { OutputFormatter } from "@uipath/common";
 
 OutputFormatter.success({ Result: "Success", Code: "AssetList", Data: assets });
-OutputFormatter.error({ Result: "Failure", Message: "Not found", Instructions: "Check the ID" });
+OutputFormatter.error({ Result: RESULTS.Failure, Message: "Not found", Instructions: "Check the ID" });
 ```
 
 Supported formats: `table`, `json`, `yaml`, `plain`.
@@ -30,7 +30,7 @@ import { catchError } from "@uipath/common";
 
 const [error, result] = await catchError(api.getData());
 if (error) {
-    OutputFormatter.error({ Result: "Failure", Message: error.message, Instructions: "Retry" });
+    OutputFormatter.error({ Result: RESULTS.Failure, Message: error.message, Instructions: "Retry" });
     return;
 }
 ```
@@ -69,4 +69,4 @@ Debug output is enabled via `DEBUG` env var (Node/Bun) or `localStorage.debug` (
 
 ## License
 
-See the [root repository](https://github.com/UiPath/uipcli) for license information.
+See the [root repository](https://github.com/UiPath/cli) for license information.

package/dist/catch-error.d.ts

@@ -0,0 +1,5 @@
+type CatchErrorResult<T> = [undefined, T] | [Error, undefined];
+export declare function catchError<T>(fnOrPromise: Promise<T>): Promise<CatchErrorResult<T>>;
+export declare function catchError<T>(fnOrPromise: () => Promise<T>): Promise<CatchErrorResult<T>>;
+export declare function catchError<T>(fnOrPromise: () => T): CatchErrorResult<T>;
+export {};

package/dist/command-examples.d.ts

@@ -0,0 +1,36 @@
+import { Command } from "commander";
+/**
+ * Structured example output data, stored as objects for format-agnostic rendering.
+ * The `Code` mirrors the SuccessOutput.Code the real command would emit;
+ * `Data` holds anonymized sample records.
+ */
+export interface CommandExampleOutput {
+    Code: string;
+    Data: Record<string, unknown> | Record<string, unknown>[];
+}
+/**
+ * A single usage example for a leaf command.
+ *
+ * Displayed in the "Examples" section of `--help` output.
+ * The `Output.Data` is stored as plain objects so the help renderer
+ * can format it in whatever `--output` mode is active (table, json, yaml, plain).
+ */
+export interface CommandExample {
+    /** Short description of what this example demonstrates (optional). */
+    Description?: string;
+    /** The anonymized command invocation (e.g. "uip or machines list --limit 2"). */
+    Command: string;
+    /** Example response data the command would produce. */
+    Output: CommandExampleOutput;
+}
+/** Retrieve examples registered on a command (empty array if none). */
+export declare function getCommandExamples(cmd: Command): CommandExample[];
+declare module "commander" {
+    interface Command {
+        /**
+         * Register usage examples displayed in the "Examples" help section.
+         * Only meaningful on leaf commands (those with a `.trackedAction`).
+         */
+        examples(examples: CommandExample[]): this;
+    }
+}

package/dist/command-help.d.ts

@@ -0,0 +1,53 @@
+import { type Command, Help } from "commander";
+import { type CommandExample } from "./command-examples";
+import { type OutputFormat } from "./formatter";
+export interface CommandHelpOption {
+    Flags: string;
+    Description: string;
+    Default?: string;
+}
+export interface CommandHelpArgument {
+    Name: string;
+    Description: string;
+    Required: boolean;
+    Default?: string;
+}
+export interface CommandHelpData {
+    Command: string;
+    Description: string;
+    Usage: string;
+    Arguments: CommandHelpArgument[];
+    Options: CommandHelpOption[];
+    Examples?: CommandExample[];
+}
+/**
+ * Extract structured help metadata from a Commander Command object.
+ * Uses Commander's Help utility methods (visibleOptions, visibleArguments)
+ * to ensure consistency with the default help text.
+ */
+export declare function extractCommandHelp(cmd: Command, helper: Help): CommandHelpData;
+/**
+ * Build a string representation of a command tree rooted at `command`.
+ *
+ * Table/plain format: delegates to Commander's built-in Help.formatHelp per command.
+ * Structured formats: aggregates extractCommandHelp data into a single envelope
+ * with full command paths.
+ */
+export declare function formatHelpAll(command: Command, baseName?: string): string;
+/**
+ * Pre-scan raw argv for --output <value> before Commander parses.
+ * Falls back to the environment-aware default ("table" for TTY, "json" otherwise).
+ */
+export declare function extractFormatFromArgs(args: string[]): OutputFormat;
+/**
+ * Register --help-all on a command. When triggered, prints the full
+ * recursive help for that command's subtree and exits.
+ *
+ * Uses Commander's `on('option:help-all')` event which fires during
+ * parseOptions — before subcommand routing — so it works on container
+ * commands that have no action handler.
+ *
+ * Output and exit use Commander's own infrastructure (configureOutput,
+ * CommanderError) — the same pattern Commander uses for --version.
+ */
+export declare function registerHelpAll(command: Command): void;

package/dist/command-walker.d.ts

@@ -0,0 +1,14 @@
+import type { Command } from "commander";
+export interface CommandEntry {
+    command: Command;
+    fullName: string;
+}
+/**
+ * Recursively walks the Commander program tree and collects all actionable
+ * commands — those with an action handler, or leaf commands without subcommands.
+ *
+ * Returns raw Commander Command objects paired with their full path name
+ * (e.g. "is connectors list"). Does NOT filter or format — consumers apply
+ * their own logic on top.
+ */
+export declare function collectCommands(command: Command, parentName: string, result: CommandEntry[]): void;

package/dist/completer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Declarative shell-completion API.
+ *
+ * Tools attach a `CompletionSpec` to a Commander Option or Argument. The spec
+ * describes a real user-facing CLI command whose JSON output supplies the
+ * candidate list at TAB time. The `uip completion <shell>` generator inlines
+ * this information into the emitted completion script, so TAB completion
+ * invokes the same commands a user would run directly — no hidden dispatch,
+ * no separate process-init path.
+ *
+ * Cross-bundle detail: each tool bundles its own copy of commander, so
+ * `instanceof Option` checks fail across bundles. Specs are stored on the
+ * target via a `Symbol.for()` key, which is shared process-wide.
+ *
+ * Example:
+ *     withCompleter(option, {
+ *         command: ["uip", "solution", "packages", "list", "--output", "json", "--take", "200"],
+ *         valueSelector: "[.Data[].name] | unique | .[]",
+ *     });
+ */
+export interface CompletionSpec {
+    /**
+     * Argv of the public CLI command to invoke at TAB time. Tokens wrapped in
+     * `{name}` are substituted with the value of the option `--name` that the
+     * user has already typed (camelCase keys, matching Commander's attribute
+     * names).
+     */
+    command: string[];
+    /**
+     * `jq` filter applied to the command's stdout. Each non-empty line of the
+     * filtered output becomes a candidate value. `{name}` placeholders are
+     * substituted with `$name` (a jq variable) and bound at TAB time via
+     * `--arg name "$_req_name"`, so user-supplied values cannot escape the
+     * jq string context. `requiresOptions` must list each placeholder name.
+     * Missing `jq` or a non-zero exit silently yields no candidates (falls
+     * through to shell defaults).
+     */
+    valueSelector: string;
+    /**
+     * Option names (camelCase) that must be set on the current command before
+     * this completer is invoked. If any required option is absent, no TAB is
+     * performed — avoids useless network calls when context is incomplete.
+     */
+    requiresOptions?: string[];
+}
+/** Attach a completion spec to a Commander Option or Argument. */
+export declare function withCompleter<T extends object>(target: T, spec: CompletionSpec): T;
+export declare function getCompleter(target: object | null | undefined): CompletionSpec | undefined;

package/dist/console-guard.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Global console interception guard.
+ *
+ * Patches `console.log`, `console.info`, `console.warn`, `console.error`,
+ * and `console.debug` so that output from third-party dependencies
+ * (e.g. applicationinsights, future npm packages) is routed through the
+ * OutputSink abstraction instead of writing directly to the terminal.
+ *
+ * Install once at CLI startup, after the sink is configured:
+ *
+ *   configureLogger({ sink: new TerminalSink() });
+ *   installConsoleGuard();
+ */
+/**
+ * Install the console guard. Idempotent — calling twice is a no-op.
+ *
+ * Must be called **after** `configureLogger({ sink })` so that
+ * `getOutputSink()` resolves to the correct sink.
+ */
+export declare function installConsoleGuard(): void;
+/**
+ * Restore the original console methods. Intended for testing teardown.
+ */
+export declare function restoreConsole(): void;

package/dist/constants.d.ts

@@ -0,0 +1,18 @@
+/** Home directory for all UiPath CLI data: ~/.uipath/ */
+export declare const UIPATH_HOME_DIR = ".uipath";
+/** Auth credentials filename within home directory */
+export declare const AUTH_FILENAME = ".auth";
+/** CLI config filename */
+export declare const CONFIG_FILENAME = "config.json";
+/** Local project config filename (looked up in CWD) */
+export declare const LOCAL_CONFIG_FILENAME = "uipath.config.json";
+/** Default UiPath cloud base URL */
+export declare const DEFAULT_BASE_URL = "https://cloud.uipath.com";
+/** Default page size for paginated API list commands */
+export declare const DEFAULT_PAGE_SIZE = 50;
+/** Auth callback server timeout (5 minutes) */
+export declare const DEFAULT_AUTH_TIMEOUT_MS: number;
+/** HTTP fetch timeout (30 seconds) */
+export declare const DEFAULT_FETCH_TIMEOUT_MS = 30000;
+/** Localhost OIDC redirect URI */
+export declare const DEFAULT_REDIRECT_URI = "http://localhost:8104/oidc/login";

package/dist/env-reference.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolves a CLI argument value that may reference an environment variable.
+ * Supported syntax:
+ *   env.ENV_NAME   — e.g., env.UIPATH_CLIENT_ID
+ * Returns the value as-is if it doesn't match the pattern.
+ * Throws if the referenced env var is not set.
+ */
+export declare function resolveEnvReference(value: string): string;
+export declare function resolveEnvReference(value: undefined): undefined;
+export declare function resolveEnvReference(value: string | undefined): string | undefined;

package/dist/error-handler.d.ts

@@ -0,0 +1,52 @@
+import type { ErrorContext, FailureResultType } from "./formatter";
+/**
+ * Structured error details returned by {@link extractErrorDetails}.
+ */
+export interface ErrorDetails {
+    /** Categorised failure type suitable for OutputFormatter.error() Result field */
+    result: FailureResultType;
+    /** Human-readable error message suitable for OutputFormatter.error() */
+    message: string;
+    /** Raw details from the response body or error object for debugging */
+    details: string;
+    /** Machine-readable context for agents (HTTP status, request ID, retry-after, etc.) */
+    context?: ErrorContext;
+}
+/**
+ * Options for customising error extraction behaviour.
+ */
+export interface ExtractErrorOptions {
+    /** Custom message for HTTP 403 Forbidden errors. Uses a generic default if omitted. */
+    forbiddenMessage?: string;
+}
+/**
+ * Extract a structured error message and details from an unknown thrown value.
+ *
+ * Handles the common shapes seen across UiPath API SDKs:
+ *   - Objects with `.status` and/or `.response.status` (HTTP-like errors)
+ *   - JSON response bodies with `message`, `errorMessage`, `title`, or nested `errors`
+ *   - Standard `Error` objects
+ *   - Arbitrary values (stringified as fallback)
+ *
+ * HTTP status code handling:
+ *   - 401 → authentication prompt
+ *   - 403 → permissions message (customisable via `options.forbiddenMessage`)
+ *   - 405 → endpoint hint
+ *   - Other → `HTTP {status}: {body message}`
+ */
+export declare function extractErrorDetails(error: unknown, options?: ExtractErrorOptions): Promise<ErrorDetails>;
+/**
+ * Extract a human-readable error message from an unknown thrown value.
+ *
+ * Convenience wrapper around {@link extractErrorDetails} that returns only the
+ * message string.
+ */
+export declare function extractErrorMessage(error: unknown, options?: ExtractErrorOptions): Promise<string>;
+/**
+ * Synchronous variant of {@link extractErrorMessage}.
+ *
+ * Does NOT attempt to read response bodies (which requires async I/O).
+ * Suitable for MCP SDK errors and other contexts where errors are always
+ * plain `Error` objects.
+ */
+export declare function extractErrorMessageSync(error: unknown): string;

package/dist/error-instructions.d.ts

@@ -0,0 +1,2 @@
+export type ErrorInstructionContext = "auth" | "identity" | "input-parse" | "input-validate" | "flag-format" | "backend" | "permissions";
+export declare function instructionsFor(ctx: ErrorInstructionContext, err?: unknown): string;

package/dist/formatter.d.ts

@@ -0,0 +1,101 @@
+export type OutputFormat = "table" | "json" | "yaml" | "plain";
+export type ResultType = "Success" | "Failure" | "ConfigError" | "AuthenticationError" | "ValidationError" | "TimeoutError";
+export type FailureResultType = Exclude<ResultType, "Success">;
+/** Canonical string constants for {@link ResultType} values. */
+export declare const RESULTS: {
+    readonly Success: "Success";
+    readonly Failure: "Failure";
+    readonly ConfigError: "ConfigError";
+    readonly AuthenticationError: "AuthenticationError";
+    readonly ValidationError: "ValidationError";
+    /** Reserved — no code path emits this yet; here so the exit-code contract is stable. */
+    readonly TimeoutError: "TimeoutError";
+};
+/**
+ * Maps each {@link ResultType} to a numeric process exit code.
+ *
+ * | Code | Meaning                        |
+ * |------|--------------------------------|
+ * |  0   | Success                        |
+ * |  1   | Failure / ConfigError (generic)|
+ * |  2   | AuthenticationError            |
+ * |  3   | ValidationError                |
+ * |  4   | TimeoutError                   |
+ */
+export declare const EXIT_CODES: {
+    readonly Success: 0;
+    readonly Failure: 1;
+    readonly ConfigError: 1;
+    readonly AuthenticationError: 2;
+    readonly ValidationError: 3;
+    readonly TimeoutError: 4;
+};
+/** Widened record type that accepts interface types (which lack an implicit
+ *  index signature in TypeScript) while still representing keyed objects. */
+export type DataRecord = Record<string, unknown> | (object & Record<never, never>);
+export declare class SuccessOutput {
+    Result: "Success";
+    Code: string;
+    Data: DataRecord | DataRecord[];
+    Instructions?: string;
+    Log?: string;
+    constructor(code: string, data: DataRecord | DataRecord[]);
+}
+export interface ErrorContext {
+    httpStatus?: number;
+    errorCode?: string;
+    requestId?: string;
+    retryAfter?: number;
+}
+export declare class FailureOutput {
+    Result: FailureResultType;
+    Message: string;
+    Instructions: string;
+    Context?: ErrorContext;
+    Log?: string;
+    constructor(result: FailureResultType, message: string, instructions: string, context?: ErrorContext);
+}
+export type StructuredOutput = SuccessOutput | FailureOutput;
+/**
+ * Check whether `filter` is a syntactically valid JMESPath expression.
+ * Returns `null` when valid, otherwise the parser error.
+ *
+ * Call this at CLI startup to fail fast with a ValidationError instead of
+ * letting {@link applyFilter} throw mid-command and be reported as a generic
+ * Failure.
+ *
+ * NOTE: this is a parse-time check only. JMESPath expressions that compile
+ * successfully can still throw at evaluation time (e.g. type-coercion errors
+ * when functions receive unexpected types). Callers that need a fully
+ * closed-box guarantee must additionally wrap {@link applyFilter}.
+ */
+export declare function validateOutputFilter(filter: string): Error | null;
+/**
+ * OutputFormatter namespace for formatting and displaying output.
+ */
+export declare namespace OutputFormatter {
+    function success(data: SuccessOutput): void;
+    /**
+     * Format and display an error, then set {@link process.exitCode} to the
+     * value from {@link EXIT_CODES} for `data.Result` (falls back to 1).
+     *
+     * **Side-effect:** sets `process.exitCode` so the process exits with a
+     * non-zero status even if no explicit `process.exit()` call follows.
+     */
+    function error(data: FailureOutput): void;
+    /** Emit a list result. Always uses `Result: "Success"` — an empty list is not an error. */
+    function emitList<T extends DataRecord>(code: string, items: T[], opts?: {
+        emptyInstructions?: string;
+        warning?: string;
+    }): void;
+    /**
+     * Log an informational/progress message to stderr.
+     * Accepts a simple object (e.g., `{ Message: "..." }` or `{ Warning: "..." }`).
+     */
+    function log(data: Record<string, unknown>): void;
+    /**
+     * Format structured output to a string without writing to console.
+     * Useful when the caller needs the formatted string (e.g., Commander's formatHelp).
+     */
+    function formatToString(data: StructuredOutput): string;
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export * from "./catch-error";
+export * from "./command-examples";
+export * from "./command-help";
+export * from "./command-walker";
+export * from "./completer";
+export { installConsoleGuard, restoreConsole } from "./console-guard";
+export * from "./constants";
+export * from "./env-reference";
+export * from "./error-handler";
+export * from "./error-instructions";
+export * from "./formatter";
+export * from "./jsonpath";
+export * from "./logger";
+export * from "./option-validators";
+export * from "./output-context";
+export * from "./output-format-context";
+export * from "./output-sink";
+export * from "./polling";
+export * from "./registry";
+export * from "./screen-logger";
+export * from "./telemetry/node.js";
+export { setGlobalTelemetryProperties } from "./telemetry/node-appinsights-telemetry-provider.js";
+export * from "./telemetry/telemetry-events.js";
+export * from "./telemetry/telemetry-init.js";
+export * from "./tool-provider";
+export * from "./trackedAction.js";