@uipath/uipath-python-bridge 0.9.1 → 1.0.2

package/dist/index.js

@@ -88,7 +88,7 @@ function processCommandArgs(args, rules) {
   }
   return {
     allowed: true,
-    args: [...args]
+    args: [...argsWithoutForce]
   };
 }
 // src/execute.ts
@@ -103,12 +103,45 @@ import {
   UIPATH_HOME_DIR
 } from "@uipath/common";
 import { getFileSystem as getFileSystem2 } from "@uipath/filesystem";
-async function buildAuthEnv() {
+var ENV_FILE_NAME = ".env";
+function isHelpCommand(args) {
+  return args.includes("--help") || args.includes("-h");
+}
+function matchesRequiredCommand(args, commands) {
+  return args[0] !== undefined && commands.includes(args[0]);
+}
+function envValueFromFile(content, name) {
+  const envLine = content.split(/\r?\n/).map((line) => line.trim()).find((line) => {
+    if (!line || line.startsWith("#")) {
+      return false;
+    }
+    const [key, ...valueParts2] = line.split("=");
+    return key.trim() === name && valueParts2.join("=").trim().length > 0;
+  });
+  if (!envLine) {
+    return null;
+  }
+  const [, ...valueParts] = envLine.split("=");
+  return valueParts.join("=").trim().replace(/^["']|["']$/g, "") || null;
+}
+async function getConfiguredEnvValue(fs, name) {
+  const processValue = process.env[name]?.trim();
+  if (processValue) {
+    return processValue;
+  }
+  const envPath = fs.path.join(fs.env.cwd(), ENV_FILE_NAME);
+  if (!await fs.exists(envPath)) {
+    return null;
+  }
+  const [readError, content] = await catchError2(fs.readFile(envPath, "utf-8"));
+  return !readError && typeof content === "string" ? envValueFromFile(content, name) : null;
+}
+async function buildAuthContext() {
   const authEnv = {};
   const [authError, status] = await catchError2(getLoginStatusAsync());
   if (authError) {
     logger2.debug(`Auth unavailable — continuing without credentials: ${authError.message}`);
-    return authEnv;
+    return { authEnv };
   }
   if (status.loginStatus === "Logged in" && status.accessToken) {
     authEnv.UIPATH_ACCESS_TOKEN = status.accessToken;
@@ -128,10 +161,16 @@ async function buildAuthEnv() {
     if (status.tenantName)
       authEnv.UIPATH_TENANT_NAME = status.tenantName;
   }
-  return authEnv;
+  return { authEnv, loginStatus: status };
 }
 function createExecuteCommand(config) {
-  const { commandPrefix, telemetryEvent, commandRules } = config;
+  const {
+    commandPrefix,
+    telemetryEvent,
+    commandRules,
+    commandPreflight,
+    requiredEnvironmentVariables = []
+  } = config;
   const executeCommand = async (rawArgs, _options) => {
     const runIndex = rawArgs.indexOf("exec");
     const actualArgs = runIndex >= 0 ? rawArgs.slice(runIndex + 1) : [];
@@ -139,9 +178,9 @@ function createExecuteCommand(config) {
     const cacheFile = fs.path.join(fs.env.homedir(), UIPATH_HOME_DIR, getCacheFileName());
     const setupHint = commandPrefix ? `Run 'uip ${commandPrefix} setup' first to configure environment.` : "Run setup first to configure environment.";
     const cache = await readCache(cacheFile);
-    if (!cache || !cache.uipathExePath) {
+    if (!cache?.uipathExePath) {
       OutputFormatter.error({
-        Result: RESULTS.Failure,
+        Result: RESULTS.ConfigError,
         Message: "Python not configured.",
         Instructions: setupHint
       });
@@ -150,7 +189,7 @@ function createExecuteCommand(config) {
     }
     if (!await fs.exists(cache.uipathExePath)) {
       OutputFormatter.error({
-        Result: RESULTS.Failure,
+        Result: RESULTS.ConfigError,
         Message: "uipath executable not found.",
         Instructions: setupHint
       });
@@ -160,20 +199,64 @@ function createExecuteCommand(config) {
     const processed = processCommandArgs(actualArgs, commandRules);
     if (!processed.allowed) {
       OutputFormatter.error({
-        Result: RESULTS.Failure,
+        Result: RESULTS.ValidationError,
         Message: processed.errorMessage || "Command disabled.",
         Instructions: "Use of --force flag is not recommended. Favor alternate command."
       });
-      processContext.exit(1);
+      processContext.exit(3);
       return;
     }
     const commandArgs = commandPrefix ? [commandPrefix, ...processed.args] : [...processed.args];
-    const authEnv = await buildAuthEnv();
+    const requiredEnv = {};
+    for (const requirement of requiredEnvironmentVariables) {
+      const applies = matchesRequiredCommand(processed.args, requirement.commands) && (!requirement.skipWhenHelp || !isHelpCommand(processed.args));
+      if (!applies) {
+        continue;
+      }
+      const value = await getConfiguredEnvValue(fs, requirement.name);
+      if (!value) {
+        OutputFormatter.error({
+          Result: RESULTS.ConfigError,
+          Message: `${requirement.name} environment variable not found.`,
+          Instructions: requirement.instructions
+        });
+        processContext.exit(1);
+        return;
+      }
+      requiredEnv[requirement.name] = value;
+    }
+    const { authEnv, loginStatus } = await buildAuthContext();
+    if (commandPreflight) {
+      const [preflightError, preflightResult] = await catchError2(Promise.resolve().then(() => commandPreflight({
+        args: commandArgs,
+        loginStatus,
+        authEnv
+      })));
+      if (preflightError) {
+        OutputFormatter.error({
+          Result: RESULTS.Failure,
+          Message: preflightError.message,
+          Instructions: "Check your credentials and configuration, then retry."
+        });
+        processContext.exit(1);
+        return;
+      }
+      if (preflightResult && !preflightResult.allowed) {
+        OutputFormatter.error({
+          Result: RESULTS.ConfigError,
+          Message: preflightResult.message || "Command preflight check failed.",
+          Instructions: preflightResult.instructions || "Update the command configuration and try again."
+        });
+        processContext.exit(preflightResult.exitCode ?? 1);
+        return;
+      }
+    }
     const proc = spawn(cache.uipathExePath, commandArgs, {
       cwd: fs.env.cwd(),
       env: {
         ...process.env,
-        ...authEnv
+        ...authEnv,
+        ...requiredEnv
       },
       stdio: "inherit"
     });
@@ -209,6 +292,7 @@ class PythonService {
   cacheFile;
   config;
   uipathExePath;
+  packageVersion;
   constructor(config) {
     const fs = getFileSystem3();
     this.config = config;
@@ -228,23 +312,39 @@ class PythonService {
     if (!force) {
       logger3.debug("Checking cache...");
       const cached = await this.loadCache();
-      if (cached && cached.uipathExePath && await fs.exists(cached.uipathExePath)) {
+      if (cached?.uipathExePath && await fs.exists(cached.uipathExePath)) {
         pythonPath = cached.pythonPath;
         version = cached.version;
         this.uipathExePath = cached.uipathExePath;
         logger3.info(`Using cached uipath executable: ${this.uipathExePath}`);
+        this.packageVersion = cached.packageVersion;
+        if (!this.packageVersion) {
+          const versionResult2 = await this.getUipathVersion(this.uipathExePath);
+          if ("error" in versionResult2) {
+            return {
+              success: false,
+              pythonPath,
+              pythonVersion: version,
+              packageInstalled: true,
+              error: versionResult2.error
+            };
+          }
+          this.packageVersion = versionResult2.version;
+        }
         await this.saveCache({
           pythonPath,
           version,
           lastValidated: new Date().toISOString(),
           packageName,
-          uipathExePath: this.uipathExePath
+          uipathExePath: this.uipathExePath,
+          packageVersion: this.packageVersion
         });
         return {
           success: true,
           pythonPath,
           pythonVersion: version,
-          packageInstalled: true
+          packageInstalled: true,
+          packageVersion: this.packageVersion
         };
       } else if (cached) {
         logger3.warn("Cached Python path no longer exists, re-detecting...");
@@ -273,18 +373,31 @@ To install the package, run:
   ${pythonPath} -m pip install ${packageName}`
       };
     }
+    const versionResult = await this.getUipathVersion(this.uipathExePath);
+    if ("error" in versionResult) {
+      return {
+        success: false,
+        pythonPath,
+        pythonVersion: version,
+        packageInstalled: true,
+        error: versionResult.error
+      };
+    }
+    this.packageVersion = versionResult.version;
     await this.saveCache({
       pythonPath,
       version,
       lastValidated: new Date().toISOString(),
       packageName,
-      uipathExePath: this.uipathExePath
+      uipathExePath: this.uipathExePath,
+      packageVersion: this.packageVersion
     });
     return {
       success: true,
       pythonPath,
       pythonVersion: version,
-      packageInstalled: true
+      packageInstalled: true,
+      packageVersion: this.packageVersion
     };
   }
   async detectPython() {
@@ -349,26 +462,17 @@ To install the package, run:
     };
   }
   async findUipathExe(fs, command, args) {
+    const metadataPath = await this.findUipathExeFromMetadata(fs, command, args);
+    if (metadataPath)
+      return metadataPath;
     const isWindows = platform() === "win32";
     const candidatePaths = [];
     const virtualEnv = process.env.VIRTUAL_ENV;
     if (virtualEnv) {
       candidatePaths.push(isWindows ? fs.path.join(virtualEnv, "Scripts", "uipath.exe") : fs.path.join(virtualEnv, "bin", "uipath"));
     }
-    const prefixArgs = [...args, "-c", "import sys; print(sys.prefix)"];
-    const prefixProc = spawn2(command, prefixArgs, {
-      stdio: ["ignore", "pipe", "pipe"]
-    });
-    const prefixChunks = [];
-    prefixProc.stdout.on("data", (chunk) => prefixChunks.push(chunk));
-    const [prefixError, prefixExitCode] = await catchError3(new Promise((resolve, reject) => {
-      prefixProc.on("exit", (code) => resolve(code ?? 1));
-      prefixProc.on("error", (error) => reject(error));
-    }));
-    if (prefixError) {
-      logger3.debug(`Failed to locate uipath executable: ${prefixError}`);
-    } else if (prefixExitCode === 0) {
-      const prefix = Buffer.concat(prefixChunks).toString("utf-8").trim();
+    const prefix = await this.getPythonPrefix(command, args);
+    if (prefix) {
       candidatePaths.push(isWindows ? fs.path.join(prefix, "Scripts", "uipath.exe") : fs.path.join(prefix, "bin", "uipath"));
     }
     for (const candidate of candidatePaths) {
@@ -378,9 +482,132 @@ To install the package, run:
         return candidate;
       }
     }
-    logger3.error(`uipath executable not found. Checked: ${candidatePaths.join(", ")}`);
+    const pathCandidates = this.getPathUipathCandidates(fs, isWindows);
+    for (const candidate of pathCandidates) {
+      logger3.debug(`Checking for uipath executable on PATH at: ${candidate}`);
+      if (await fs.exists(candidate)) {
+        logger3.info(`Found uipath executable at: ${candidate}`);
+        return candidate;
+      }
+    }
+    const checkedCandidates = [...candidatePaths, ...pathCandidates];
+    logger3.error(`uipath executable not found. Checked: ${checkedCandidates.join(", ")}`);
     return;
   }
+  async findUipathExeFromMetadata(fs, command, args) {
+    const script = `
+from importlib.metadata import distribution, PackageNotFoundError
+import sys
+try:
+    d = distribution("uipath")
+except PackageNotFoundError:
+    sys.exit(2)
+for f in d.files or []:
+    if f.name.lower() in ("uipath", "uipath.exe"):
+        print(str(f.locate()))
+        sys.exit(0)
+sys.exit(3)
+`;
+    const proc = spawn2(command, [...args, "-c", script], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    proc.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+    proc.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+    const [error, exitCode] = await catchError3(new Promise((resolve, reject) => {
+      proc.on("exit", (code) => resolve(code ?? 1));
+      proc.on("error", (err) => reject(err));
+    }));
+    if (error) {
+      logger3.debug(`Failed to locate uipath executable: ${error}`);
+      return;
+    }
+    if (exitCode !== 0) {
+      const stderr = Buffer.concat(stderrChunks).toString("utf-8").trim();
+      logger3.debug(`uipath executable metadata lookup exited with code ${exitCode}${stderr ? `: ${stderr}` : ""}`);
+      return;
+    }
+    const resolved = Buffer.concat(stdoutChunks).toString("utf-8").trim();
+    if (!resolved) {
+      logger3.debug("uipath executable metadata lookup returned empty path");
+      return;
+    }
+    if (!await fs.exists(resolved)) {
+      logger3.debug(`uipath executable path from metadata does not exist: ${resolved}`);
+      return;
+    }
+    logger3.info(`Found uipath executable at: ${resolved}`);
+    return resolved;
+  }
+  async getPythonPrefix(command, args) {
+    const proc = spawn2(command, [...args, "-c", "import sys; print(sys.prefix)"], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const stdoutChunks = [];
+    proc.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+    const [error, exitCode] = await catchError3(new Promise((resolve, reject) => {
+      proc.on("exit", (code) => resolve(code ?? 1));
+      proc.on("error", (err) => reject(err));
+    }));
+    if (error) {
+      logger3.debug(`Failed to locate uipath executable: ${error}`);
+      return;
+    }
+    if (exitCode !== 0)
+      return;
+    const prefix = Buffer.concat(stdoutChunks).toString("utf-8").trim();
+    return prefix || undefined;
+  }
+  async getUipathVersion(exePath) {
+    const proc = spawn2(exePath, ["--version"], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    const stdoutChunks = [];
+    const stderrChunks = [];
+    proc.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
+    proc.stderr.on("data", (chunk) => stderrChunks.push(chunk));
+    const [spawnError, exitCode] = await catchError3(new Promise((resolve, reject) => {
+      proc.on("exit", (code) => resolve(code ?? 1));
+      proc.on("error", (err) => reject(err));
+    }));
+    if (spawnError) {
+      return {
+        error: `Failed to run '${exePath} --version': ${spawnError.message}`
+      };
+    }
+    const stdout = Buffer.concat(stdoutChunks).toString("utf-8").trim();
+    const stderr = Buffer.concat(stderrChunks).toString("utf-8").trim();
+    if (exitCode !== 0) {
+      return {
+        error: `'${exePath} --version' exited with code ${exitCode}${stderr ? `: ${stderr}` : ""}`
+      };
+    }
+    const match = stdout.match(/uipath\s+version\s+(\S+)/i);
+    if (!match) {
+      return {
+        error: `Could not parse version from '${exePath} --version' output: ${stdout || "<empty>"}`
+      };
+    }
+    return { version: match[1] };
+  }
+  getPathUipathCandidates(fs, isWindows) {
+    const pathValue = process.env.PATH || (isWindows ? process.env.Path : undefined);
+    if (!pathValue)
+      return [];
+    const delimiter = isWindows ? ";" : ":";
+    const pathEntries = pathValue.split(delimiter).map((entry) => entry.trim().replace(/^"|"$/g, "")).filter((entry) => entry.length > 0);
+    const executableNames = isWindows ? this.getWindowsExecutableNames() : ["uipath"];
+    return pathEntries.flatMap((entry) => executableNames.map((name) => fs.path.join(entry, name)));
+  }
+  getWindowsExecutableNames() {
+    const pathExt = process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD";
+    const extensions = pathExt.split(";").map((extension) => extension.trim().toLowerCase()).filter((extension) => extension.length > 0).map((extension) => extension.startsWith(".") ? extension : `.${extension}`);
+    return [
+      "uipath",
+      ...extensions.map((extension) => `uipath${extension}`)
+    ];
+  }
   buildNotFoundError(checkedVersions, searchedCommands) {
     let msg = `No compatible Python installation found.
 
@@ -449,7 +676,7 @@ Please install one of the required Python versions:
   async saveCache(cache) {
     const fs = getFileSystem3();
     const dir = fs.path.dirname(this.cacheFile);
-    const [mkdirError] = await catchError3(fs.mkdir(dir, { recursive: true }));
+    const [mkdirError] = await catchError3(fs.mkdir(dir));
     if (mkdirError) {
       logger3.warn(`Failed to create cache directory: ${mkdirError}`);
       return;
@@ -472,7 +699,7 @@ import {
 import { getFileSystem as getFileSystem4 } from "@uipath/filesystem";
 function createSetupCommand(config) {
   return (program) => {
-    program.command("setup").description("Detect Python installation and verify package is installed").option("--force", "Force re-detection of Python even if cached", false).trackedAction(processContext2, config.telemetryEvent, async (options) => {
+    program.command("setup").description("Detect Python installation and verify package is installed").option("--force", "Force re-detection of Python even if cached", false).trackedAction(processContext2, async (options) => {
       const packageName = config.packageName || getPackageName();
       const allowedVersions = getAllowedPythonVersions();
       if (allowedVersions.length === 0) {
@@ -506,7 +733,7 @@ Searching for Python installations: ${allowedVersions}`);
         OutputFormatter2.error({
           Result: RESULTS2.Failure,
           Message: result.error || "Setup failed with no error.",
-          Instructions: result.instructions || ""
+          Instructions: result.instructions || `Install a supported Python version and the '${packageName}' tool, then re-run setup. For uv installs, run 'uv tool install ${packageName}' and ensure the uv tool directory is on PATH.`
         });
         processContext2.exit(1);
         return;
@@ -521,21 +748,22 @@ Searching for Python installations: ${allowedVersions}`);
           PackageVersion: result.packageVersion ?? "N/A"
         }
       });
+      processContext2.exit(0);
     });
   };
 }
-function createDefaultAction(config, executeCommand) {
+function createDefaultAction(_config, executeCommand) {
   return (program) => {
-    program.trackedAction(processContext2, config.defaultTelemetryEvent, async () => {
+    program.trackedAction(processContext2, async () => {
       const userArgs = program.args.length > 0 ? program.args : [];
       const extra = userArgs.length > 0 ? userArgs : ["--help"];
       await executeCommand(["_", "_", "exec", ...extra], {});
     });
   };
 }
-function createHelpCommand(config, executeCommand) {
+function createHelpCommand(_config, executeCommand) {
   return (program) => {
-    program.command("help").description("Display help for the python tool").trackedAction(processContext2, config.helpTelemetryEvent, async () => {
+    program.command("help").description("Display help for the python tool").trackedAction(processContext2, async () => {
       await executeCommand(["_", "_", "exec", "--help"], {});
     });
   };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uipath/uipath-python-bridge",
-    "version": "0.9.1",
+    "version": "1.0.2",
     "description": "Shared Python detection, caching, and CLI bridge for UiPath Python SDK tools.",
     "keywords": [
         "uip",
@@ -30,13 +30,19 @@
         "lint": "biome check .",
         "lint:fix": "biome check --write ."
     },
+    "peerDependencies": {
+        "@uipath/auth": "^1.0.0",
+        "@uipath/common": "^1.0.0",
+        "@uipath/filesystem": "^1.0.0",
+        "commander": "^14.0.3"
+    },
     "devDependencies": {
-        "@uipath/auth": "0.9.1",
-        "@uipath/common": "0.9.1",
-        "@uipath/filesystem": "0.9.1",
-        "@types/bun": "^1.3.9",
+        "@uipath/auth": "1.0.2",
+        "@uipath/common": "1.0.2",
+        "@uipath/filesystem": "1.0.2",
+        "@types/bun": "^1.3.11",
         "commander": "^14.0.3",
-        "typescript": "^5"
+        "typescript": "^6.0.2"
     },
-    "gitHead": "e8da2857e37a9495c4907cd39f47c9d6ed1a5566"
+    "gitHead": "e373bfc1657e0bd85a7dc482691f4bda590392e5"
 }