@uipath/common 0.1.5 → 0.1.7

package/README.md

@@ -1,110 +1,72 @@
-# common
-
-This package is the holder for common infrastructure needed by `uip` tools.
-
-# Functionalities:
-
-## 1. Output Formatter
-
-A small utility set of functions used to format a `typescript` data object in one of the data formats supported by [uip](https://github.com/UiPath/uipcli).
-
-Currently supported data formats are:
-```
-type OutputFormat = "table" | "json" | "yaml" | "plain";
-```
-
-Functions exposed:
-
-### OutputFormatter.success
-
-- Format message and logs to `console.info`
-- Default `OutputFormat` is "table"
-
-```
-export namespace OutputFormatter {
-
-    export class SuccessOutput {
-        Result: "Success" = "Success";
-        Code: string;
-        Data: Record<string, any>[] | Record<string, any>;
-    }
-
-    export function success(
-        data: SuccessOutput,
-        format: OutputFormat = "table",
-    ): void {
-        ...
-    }
-}
-
-```
-
-### OutputFormatter.error
-
-- Format message and logs to `console.error`
-- Default `OutputFormat` is "table"
-
-```
-export namespace OutputFormatter {
-
-    export class FailureOutput {
-        Result: FailureResultType;
-        Message: string;
-        Instructions: string;
-    }
-
-    export function error(
-        data: FailureOutput,
-        format: OutputFormat = "table",
-    ): void {
-        ...
-    }
-}
-
-```
-
-### OutputFormatter.log
-
-- Format message and logs to `console.log`
-- Default `OutputFormat` is "table"
-
-```
-export namespace OutputFormatter {
-
-    export class LogOutput {
-        Message: string;
-        [key: string]: unknown;
-    }
-    
-    export function log(data: LogOutput, format: OutputFormat = "table"): void {
-        ...
-    }
-}
-```
-
-## 2. Logger
-
-A simple console wrapper that works in both Node.js/Bun and browser environments. Supports four log levels and respects a `DEBUG` flag to enable verbose output.
-
-- **Node/Bun**: reads `process.env.DEBUG`
-- **Browser**: reads `localStorage.debug` (same convention as the `debug` npm package)
-
-```ts
-import { logger, LogLevel } from "@uipath/common";
-
-logger.debug("only visible when DEBUG is set");
-logger.info("general info");
-logger.warn("warning");
-logger.error("error");
-
-// Override the level at runtime
-logger.setLevel(LogLevel.DEBUG);
-```
-
-| Method          | Level   | Node stream | Visible by default |
-|-----------------|---------|-------------|--------------------|
-| `logger.debug`  | DEBUG   | stdout      | No                 |
-| `logger.info`   | INFO    | stdout      | Yes                |
-| `logger.warn`   | WARN    | stdout      | Yes                |
-| `logger.error`  | ERROR   | stderr      | Yes                |
-
+# @uipath/common
+
+Shared infrastructure for the UiPath CLI. Provides output formatting, logging, error handling, and telemetry.
+
+## Installation
+
+```bash
+npm install @uipath/common
+```
+
+## Usage
+
+### Output Formatting
+
+```ts
+import { OutputFormatter } from "@uipath/common";
+
+OutputFormatter.success({ Result: "Success", Code: "AssetList", Data: assets });
+OutputFormatter.error({ Result: "Failure", Message: "Not found", Instructions: "Check the ID" });
+```
+
+Supported formats: `table`, `json`, `yaml`, `plain`.
+
+### Error Handling
+
+Go-style `[error, data]` tuple returns via `catchError`:
+
+```ts
+import { catchError } from "@uipath/common";
+
+const [error, result] = await catchError(api.getData());
+if (error) {
+    OutputFormatter.error({ Result: "Failure", Message: error.message, Instructions: "Retry" });
+    return;
+}
+```
+
+### Logging
+
+```ts
+import { logger, LogLevel } from "@uipath/common";
+
+logger.info("Fetching resources...");
+logger.debug("Request payload:", payload);
+
+// Override level at runtime
+logger.setLevel(LogLevel.DEBUG);
+```
+
+| Method | Level | Stream | Visible by default |
+| :--- | :--- | :--- | :--- |
+| `logger.debug` | DEBUG | stdout | No |
+| `logger.info` | INFO | stdout | Yes |
+| `logger.warn` | WARN | stdout | Yes |
+| `logger.error` | ERROR | stderr | Yes |
+
+Debug output is enabled via `DEBUG` env var (Node/Bun) or `localStorage.debug` (browser).
+
+## API
+
+| Export | Description |
+| :--- | :--- |
+| `OutputFormatter` | Structured output in table, JSON, YAML, or plain text |
+| `catchError(promise)` | Go-style error handling returning `[error, data]` tuples |
+| `logger` | Cross-platform logger with debug/info/warn/error levels |
+| `trackedAction` | Commander.js extension for automatic telemetry tracking |
+| `CommandWalker` | CLI command introspection utility |
+| `OutputSink` | Abstraction for output destinations |
+
+## License
+
+See the [root repository](https://github.com/UiPath/uipcli) for license information.

package/dist/index.js

@@ -1,20 +1,4 @@
 import { createRequire } from "node:module";
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __toESM = (mod, isNodeMode, target) => {
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: () => mod[key],
-        enumerable: true
-      });
-  return to;
-};
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/catch-error.ts
@@ -4666,26 +4650,21 @@ import { appendFileSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 
 // src/output-context.ts
-var STORAGE_KEY = Symbol.for("@uipath/common/output-storage");
-var GLOBAL_SINK_KEY = Symbol.for("@uipath/common/global-sink");
-function getSharedStorage() {
-  const g = globalThis;
-  if (!g[STORAGE_KEY]) {
-    try {
-      const { AsyncLocalStorage } = __require("node:async_hooks");
-      g[STORAGE_KEY] = new AsyncLocalStorage;
-    } catch {
-      g[STORAGE_KEY] = {
-        getStore: () => {
-          return;
-        },
-        run: (_store, fn) => fn()
-      };
-    }
+function createStorage() {
+  try {
+    const { AsyncLocalStorage } = __require("node:async_hooks");
+    return new AsyncLocalStorage;
+  } catch {
+    return {
+      getStore: () => {
+        return;
+      },
+      run: (_store, fn) => fn()
+    };
   }
-  return g[STORAGE_KEY];
 }
-var outputStorage = getSharedStorage();
+var outputStorage = createStorage();
+var globalSink;
 var CONSOLE_FALLBACK = {
   writeOut: (str2) => process.stdout.write(str2),
   writeErr: (str2) => process.stderr.write(str2),
@@ -4700,20 +4679,19 @@ function runWithSink(sink, fn) {
   return outputStorage.run(sink, fn);
 }
 function getOutputSink() {
-  const g = globalThis;
-  return outputStorage.getStore() ?? g[GLOBAL_SINK_KEY] ?? CONSOLE_FALLBACK;
+  return outputStorage.getStore() ?? globalSink ?? CONSOLE_FALLBACK;
 }
 function setGlobalSink(sink) {
-  globalThis[GLOBAL_SINK_KEY] = sink;
+  globalSink = sink;
 }
 
 // src/logger.ts
-var GLOBAL_KEY = "__uipcli_log_file_path__";
+var sharedLogFilePath = "";
 function setGlobalLogFilePath(path) {
-  globalThis[GLOBAL_KEY] = path;
+  sharedLogFilePath = path;
 }
 function getGlobalLogFilePath() {
-  return globalThis[GLOBAL_KEY] ?? "";
+  return sharedLogFilePath;
 }
 var LogLevel;
 ((LogLevel2) => {
@@ -4722,6 +4700,7 @@ var LogLevel;
   LogLevel2[LogLevel2["WARN"] = 2] = "WARN";
   LogLevel2[LogLevel2["ERROR"] = 3] = "ERROR";
 })(LogLevel ||= {});
+var DEFAULT_LOG_LEVEL = 3 /* ERROR */;
 
 class SimpleLogger {
   static instance;
@@ -4742,21 +4721,17 @@ class SimpleLogger {
   static resetInstance() {
     SimpleLogger.instance = undefined;
   }
+  static isNode = typeof process !== "undefined" && !!process.versions?.node;
   static resolveLevel() {
-    if (typeof process !== "undefined" && process.env?.UIPCLI_LOG_LEVEL) {
-      const parsed = SimpleLogger.parseLevel(process.env.UIPCLI_LOG_LEVEL);
-      if (parsed !== undefined)
-        return parsed;
-    }
-    if (typeof process !== "undefined" && process.env?.DEBUG) {
-      return 0 /* DEBUG */;
+    if (SimpleLogger.isNode) {
+      return SimpleLogger.parseLevel(process.env?.UIPCLI_LOG_LEVEL ?? "") ?? (process.env?.DEBUG ? 0 /* DEBUG */ : DEFAULT_LOG_LEVEL);
     }
     try {
       if (typeof localStorage !== "undefined" && localStorage.getItem("debug")) {
         return 0 /* DEBUG */;
       }
     } catch {}
-    return 3 /* ERROR */;
+    return DEFAULT_LOG_LEVEL;
   }
   static parseLevel(value) {
     switch (value.toLowerCase()) {
@@ -4906,19 +4881,19 @@ function configureLogger(config) {
 }
 
 // src/output-format-context.ts
-var FORMAT_KEY = Symbol.for("@uipath/common/output-format");
-var FILTER_KEY = Symbol.for("@uipath/common/output-filter");
+var currentFormat;
+var currentFilter;
 function setOutputFormat(format) {
-  globalThis[FORMAT_KEY] = format;
+  currentFormat = format;
 }
 function getOutputFormat() {
-  return globalThis[FORMAT_KEY] ?? "table";
+  return currentFormat ?? "table";
 }
 function setOutputFilter(filter) {
-  globalThis[FILTER_KEY] = filter;
+  currentFilter = filter;
 }
 function getOutputFilter() {
-  return globalThis[FILTER_KEY];
+  return currentFilter;
 }
 
 // ../../node_modules/@uipath/telemetry/dist/node.js
@@ -5182,11 +5157,15 @@ class NodeAppInsightsTelemetryProvider {
     if (!client)
       return;
     const merged = this.mergeProperties(properties);
-    logger.debug(`[AppInsights] trackEvent: ${eventName}`, merged ?? "");
-    client.trackEvent({
-      name: eventName,
-      properties: merged
-    });
+    logger.debug(`[AppInsights] trackEvent: ${eventName}`, merged ? JSON.stringify(merged) : "");
+    try {
+      client.trackEvent({
+        name: eventName,
+        properties: merged
+      });
+    } catch {
+      logger.debug(`[AppInsights] trackEvent failed for: ${eventName}`);
+    }
   }
   async trackException(error, properties) {
     const client = this.client;
@@ -5194,10 +5173,14 @@ class NodeAppInsightsTelemetryProvider {
       return;
     const merged = this.mergeProperties(properties);
     logger.debug(`[AppInsights] trackException: ${error.message}`, merged ?? "");
-    client.trackException({
-      exception: error,
-      properties: merged
-    });
+    try {
+      client.trackException({
+        exception: error,
+        properties: merged
+      });
+    } catch {
+      logger.debug(`[AppInsights] trackException failed for: ${error.message}`);
+    }
   }
   async trackRequest(name, duration, success, properties) {
     const client = this.client;
@@ -5232,26 +5215,44 @@ class NodeAppInsightsTelemetryProvider {
   }
   async flush() {
     const client = this.client;
-    if (!client)
+    if (!client) {
+      logger.warn(`[AppInsights] flush error (non-fatal): nil client`);
       return;
+    }
     logger.debug("[AppInsights] flush: sending buffered telemetry to cloud");
-    const [error] = await catchError(client.flush());
+    const [error] = await catchError(new Promise((resolve, reject) => {
+      client.flush({
+        callback: (response) => {
+          if (!response) {
+            resolve();
+            return;
+          }
+          const [parseError, parsed] = catchError(() => JSON.parse(response));
+          if (parseError || parsed?.errors && parsed.errors.length > 0) {
+            reject(new Error(response));
+          } else {
+            resolve();
+          }
+        }
+      });
+    }));
     if (error) {
       logger.warn(`[AppInsights] flush error (non-fatal): ${error.message}`);
     }
   }
   async shutdown() {
-    const client = this.client;
-    if (!client || !this.appInsightsModule)
+    if (!this.appInsightsModule) {
+      logger.warn(`[AppInsights] shutdown error (non-fatal): nil appInsightsModule`);
       return;
+    }
     const appInsights = this.appInsightsModule;
-    const [error] = await catchError((async () => {
-      await client.shutdown();
-      await appInsights.shutdownAzureMonitor();
-    })());
-    if (error) {
-      logger.warn(`[AppInsights] shutdown error (non-fatal): ${error.message}`);
+    const [err] = catchError(() => appInsights.dispose());
+    if (err) {
+      logger.warn(`[AppInsights] shutdown error (non-fatal): ${err.message}`);
     }
+    this.client = undefined;
+    this.appInsightsModule = undefined;
+    this.initialized = false;
   }
 }
 async function getOrCreateProvider(connectionString) {
@@ -5289,7 +5290,7 @@ function getOrCreateSessionId() {
   return id;
 }
 var sessionId = getOrCreateSessionId();
-var DEFAULT_AI_CONNECTION_STRING = Buffer.from("SW5zdHJ1bWVudGF0aW9uS2V5PTYwNjQ5ZGY3LTk4ZmYtNDk2My1iMWQ0LWE3MGQwMzA2MTc0ZjtJbmdlc3Rpb25FbmRwb2ludD1odHRwczovL3dlc3RldXJvcGUtNS5pbi5hcHBsaWNhdGlvbmluc2lnaHRzLmF6dXJlLmNvbS87TGl2ZUVuZHBvaW50PWh0dHBzOi8vd2VzdGV1cm9wZS5saXZlZGlhZ25vc3RpY3MubW9uaXRvci5henVyZS5jb20vO0FwcGxpY2F0aW9uSWQ9ZjlmYWNiNTctM2QxMS00Njc4LWJiOGItMDI0YmJhYmM1Y2Fl", "base64").toString("utf-8");
+var DEFAULT_AI_CONNECTION_STRING = Buffer.from("SW5zdHJ1bWVudGF0aW9uS2V5PTliZDM3NDgyLTgxMGUtNDQyYS1hYWE2LWQzOGVmNjVjNjY3NDtJbmdlc3Rpb25FbmRwb2ludD1odHRwczovL3dlc3RldXJvcGUtNS5pbi5hcHBsaWNhdGlvbmluc2lnaHRzLmF6dXJlLmNvbS87TGl2ZUVuZHBvaW50PWh0dHBzOi8vd2VzdGV1cm9wZS5saXZlZGlhZ25vc3RpY3MubW9uaXRvci5henVyZS5jb20vO0FwcGxpY2F0aW9uSWQ9MzU2OTdlZjEtOGJkMC00ZjE5LWEyN2MtZDg3Y2NhYzY2ZDJj", "base64").toString("utf-8");
 function getConnectionString() {
   return process.env.UIPATH_AI_CONNECTION_STRING || DEFAULT_AI_CONNECTION_STRING;
 }
@@ -5389,7 +5390,7 @@ async function telemetryFlushAndShutdown() {
 
 // src/telemetry-events.ts
 var CommonTelemetryEvents = {
-  Error: "Error"
+  Error: "uip.error"
 };
 
 // src/formatter.ts
@@ -5470,11 +5471,6 @@ function logOutput(data, format = "table") {
   printOutput(data, format, (msg) => sink.writeOut(`${msg}
 `));
 }
-function errorOutput(data, format = "table") {
-  const sink = getOutputSink();
-  printOutput(data, format, (msg) => sink.writeErr(`${msg}
-`));
-}
 function printTable(data, logFn = console.log, externalLogValue) {
   if (data.length === 0)
     return;
@@ -5529,7 +5525,7 @@ var OutputFormatter;
       result: data.Result,
       message: data.Message
     });
-    errorOutput(data, getOutputFormat());
+    logOutput(data, getOutputFormat());
   }
   OutputFormatter.error = error;
   function log(data) {
@@ -5616,14 +5612,14 @@ function formatHelpAll(command, baseName = "") {
 var VALID_FORMATS = ["table", "json", "yaml", "plain"];
 function extractFormatFromArgs(args) {
   for (let i2 = 0;i2 < args.length; i2++) {
-    if (args[i2] === "--format" && i2 + 1 < args.length) {
+    if (args[i2] === "--output" && i2 + 1 < args.length) {
       const value = args[i2 + 1];
       if (VALID_FORMATS.includes(value)) {
         return value;
       }
     }
-    if (args[i2]?.startsWith("--format=")) {
-      const value = args[i2].substring("--format=".length);
+    if (args[i2]?.startsWith("--output=")) {
+      const value = args[i2].substring("--output=".length);
       if (VALID_FORMATS.includes(value)) {
         return value;
       }
@@ -5639,6 +5635,16 @@ function registerHelpAll(command) {
     throw new CommanderError(0, "commander.helpDisplayed", "(outputHelp)");
   });
 }
+// src/constants.ts
+var UIPATH_HOME_DIR = ".uipath";
+var AUTH_FILENAME = ".auth";
+var CONFIG_FILENAME = "config.json";
+var LOCAL_CONFIG_FILENAME = "uipath.config.json";
+var DEFAULT_BASE_URL = "https://cloud.uipath.com";
+var DEFAULT_PAGE_SIZE = 50;
+var DEFAULT_AUTH_TIMEOUT_MS = 5 * 60 * 1000;
+var DEFAULT_FETCH_TIMEOUT_MS = 30000;
+var DEFAULT_REDIRECT_URI = "http://localhost:8104/oidc/login";
 // ../../node_modules/jsonpath-plus/dist/index-node-esm.js
 import vm from "vm";
 
@@ -7062,6 +7068,17 @@ class JsonPathError extends Error {
     this.name = "JsonPathError";
   }
 }
+// src/tool-provider.ts
+var toolProvider;
+function setToolProvider(provider) {
+  toolProvider = provider;
+}
+async function ensureToolAvailable(verb) {
+  if (!toolProvider) {
+    throw new Error(`Tool '${verb}' is required but cannot be auto-installed. ` + `Run 'uip tools install ${verb}' manually.`);
+  }
+  await toolProvider(verb);
+}
 // src/trackedAction.ts
 import { Command } from "commander";
 var processContext = {
@@ -7069,8 +7086,34 @@ var processContext = {
     process.exitCode = code;
   }
 };
-Command.prototype.trackedAction = function(context, telemetryName, fn, properties) {
+function deriveCommandPath(cmd) {
+  const parts = [];
+  let current = cmd;
+  while (current) {
+    const name = current.name();
+    if (name) {
+      parts.unshift(name);
+    }
+    current = current.parent;
+  }
+  if (parts.length > 1) {
+    parts.shift();
+  }
+  return ["uip", ...parts.filter((p) => p !== "uip")].join(".");
+}
+Command.prototype.trackedAction = function(context, fnOrName, fnOrProps, legacyProperties) {
+  const command = this;
+  let fn;
+  let properties;
+  if (typeof fnOrName === "string") {
+    fn = fnOrProps;
+    properties = legacyProperties;
+  } else {
+    fn = fnOrName;
+    properties = fnOrProps;
+  }
   return this.action(async (...args) => {
+    const telemetryName = deriveCommandPath(command);
     const props = typeof properties === "function" ? properties(...args) : properties;
     const startTime = performance.now();
     let errorMessage;
@@ -7099,6 +7142,7 @@ export {
   telemetryInit,
   telemetryFlushAndShutdown,
   telemetry,
+  setToolProvider,
   setOutputFormat,
   setOutputFilter,
   setGlobalTelemetryProperties,
@@ -7120,15 +7164,27 @@ export {
   extractFormatFromArgs,
   extractCommandHelp,
   evaluateJsonPath,
+  ensureToolAvailable,
+  deriveCommandPath,
   createTelemetryProvider,
   createAppInsightsProvider,
   configureLogger,
   collectCommands,
   catchError,
+  UIPATH_HOME_DIR,
   SuccessOutput,
   OutputFormatter,
   LogLevel,
+  LOCAL_CONFIG_FILENAME,
   JsonPathError,
   FailureOutput,
-  CommonTelemetryEvents
+  DEFAULT_REDIRECT_URI,
+  DEFAULT_PAGE_SIZE,
+  DEFAULT_LOG_LEVEL,
+  DEFAULT_FETCH_TIMEOUT_MS,
+  DEFAULT_BASE_URL,
+  DEFAULT_AUTH_TIMEOUT_MS,
+  CommonTelemetryEvents,
+  CONFIG_FILENAME,
+  AUTH_FILENAME
 };

package/package.json

@@ -1,46 +1,46 @@
 {
-  "name": "@uipath/common",
-  "version": "0.1.5",
-  "description": "Common infrastructure needed by uipcli tools.",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/UiPath/uipcli.git",
-    "directory": "packages/common"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
-  },
-  "type": "module",
-  "main": "./dist/index.js",
-  "exports": {
-    ".": "./dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "maintainers": [
-    "aoltean16",
-    "mihaigirleanu",
-    "vlad-uipath"
-  ],
-  "scripts": {
-    "build": "bun build ./src/index.ts --outdir dist --format esm --target node --external commander --external applicationinsights",
-    "lint": "biome check .",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage"
-  },
-  "dependencies": {
-    "@jmespath-community/jmespath": "^1.3.0",
-    "@uipath/telemetry": "0.0.3",
-    "js-yaml": "^4.1.0",
-    "jsonpath-plus": "^10.4.0"
-  },
-  "devDependencies": {
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^25.2.3",
-    "typescript": "^5"
-  },
-  "peerDependencies": {
-    "commander": "^14.0.3"
-  }
+    "name": "@uipath/common",
+    "version": "0.1.7",
+    "description": "Common infrastructure needed by uipcli tools.",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/UiPath/uipcli.git",
+        "directory": "packages/common"
+    },
+    "publishConfig": {
+        "registry": "https://registry.npmjs.org/"
+    },
+    "type": "module",
+    "main": "./dist/index.js",
+    "exports": {
+        ".": "./dist/index.js"
+    },
+    "files": [
+        "dist"
+    ],
+    "maintainers": [
+        "aoltean16",
+        "mihaigirleanu",
+        "vlad-uipath"
+    ],
+    "scripts": {
+        "build": "bun build ./src/index.ts --outdir dist --format esm --target node --external commander --external applicationinsights",
+        "lint": "biome check .",
+        "test": "vitest run",
+        "test:coverage": "vitest run --coverage"
+    },
+    "dependencies": {
+        "@jmespath-community/jmespath": "^1.3.0",
+        "@uipath/telemetry": "0.0.3",
+        "js-yaml": "^4.1.0",
+        "jsonpath-plus": "^10.4.0"
+    },
+    "devDependencies": {
+        "@types/js-yaml": "^4.0.9",
+        "@types/node": "^25.2.3",
+        "typescript": "^5"
+    },
+    "peerDependencies": {
+        "commander": "^14.0.3"
+    }
 }