openc3 7.2.1 → 7.4.0

data/lib/openc3/models/plugin_model.rb

@@ -19,9 +19,11 @@ require 'rubygems'
 require 'rubygems/package'
 require 'openc3'
 require 'openc3/utilities/bucket'
+require 'openc3/utilities/python_venv'
 require 'openc3/utilities/store'
 require 'openc3/config/config_parser'
 require 'openc3/models/model'
+require 'openc3/models/scope_model'
 require 'openc3/models/gem_model'
 require 'openc3/models/target_model'
 require 'openc3/models/interface_model'
@@ -185,11 +187,24 @@ module OpenC3
     # Called by the PluginsController to create the plugin
     # Because this uses ERB it must be run in a separate process from the API to
     # prevent corruption and single require problems in the current process
-    def self.install_phase2(plugin_hash, scope:, gem_file_path: nil, validate_only: false)
+    # diff_only: dry run that renders the plugin's target files and returns the
+    # list of modified files ("TARGET/path") whose live content differs from
+    # what this plugin would deploy — used to warn before an upgrade which user
+    # modifications it would supersede. Implies validate_only (no side effects).
+    def self.install_phase2(plugin_hash, scope:, gem_file_path: nil, validate_only: false, diff_only: false)
+      # diff_only implies a dry run; derive a local flag instead of mutating
+      # the validate_only parameter.
+      dry_run = validate_only || diff_only
       # Register plugin to aid in uninstall if install fails
       plugin_hash.delete("existing_plugin_txt_lines")
+      # Version History upgrade hints (threaded from the admin install through
+      # update_plugin). Extracted before the splat below because PluginModel
+      # has no such attributes. version_history_files lists modified files the
+      # user chose to take from the plugin; username attributes the upgrade.
+      upgrade_username = plugin_hash.delete("username")
+      upgrade_version_files = plugin_hash.delete("version_history_files")
       plugin_model = PluginModel.new(**(plugin_hash.transform_keys(&:to_sym)), scope: scope)
-      plugin_model.create unless validate_only
+      plugin_model.create unless dry_run
 
       temp_dir = Dir.mktmpdir
       begin
@@ -206,10 +221,11 @@ module OpenC3
         # Attempt to remove all older versions of this same plugin before install to prevent version conflicts
         # Especially on downgrades
         # Leave the same version if it already exists
-        OpenC3::GemModel.destroy_all_other_versions(File.basename(gem_file_path))
+        # Skipped for dry_run/diff_only: a dry run must not mutate gems.
+        OpenC3::GemModel.destroy_all_other_versions(File.basename(gem_file_path)) unless dry_run
 
         # Actually install the gem now (slow)
-        OpenC3::GemModel.install(gem_file_path, scope: scope) unless validate_only
+        OpenC3::GemModel.install(gem_file_path, scope: scope) unless dry_run
 
         # Extract gem contents
         gem_path = File.join(temp_dir, "gem")
@@ -224,7 +240,7 @@ module OpenC3
 
         plugin_model.minimum_cosmos_version = pkg.spec.metadata['openc3_cosmos_minimum_version']
 
-        # Process app store metadata
+        # Process OpenC3 Store metadata
         plugin_model.title = pkg.spec.metadata['openc3_store_title'] || pkg.spec.summary.strip
         plugin_model.description = pkg.spec.metadata['openc3_store_description'] || pkg.spec.description.strip
         plugin_model.licenses = pkg.spec.licenses
@@ -239,8 +255,19 @@ module OpenC3
         img_path = pkg.spec.metadata['openc3_store_image'] || 'public/store_img.png'
         img_path = nil unless File.exist?(File.join(gem_path, img_path))
         package_name = "#{pkg.spec.name}-#{pkg.spec.version}"
+        # Build the upgrade context once the gem version is known; TargetModel
+        # deploys use it either to collect a modified-file diff (diff_only) or
+        # to version modified files taken from the plugin.
+        upgrade_context = nil
+        if diff_only
+          upgrade_context = { diff_collector: [] }
+        elsif upgrade_version_files && !upgrade_version_files.empty?
+          upgrade_context = { username: upgrade_username,
+                              plugin: "#{pkg.spec.name} #{pkg.spec.version}",
+                              version_files: upgrade_version_files }
+        end
         plugin_model.img_path = File.join('gems', package_name, img_path) if img_path # convert this filesystem path to volumes mount path
-        plugin_model.update() unless validate_only
+        plugin_model.update() unless dry_run
 
         needs_dependencies = pkg.spec.runtime_dependencies.length > 0
         needs_dependencies = true if Dir.exist?(File.join(gem_path, 'lib'))
@@ -250,46 +277,51 @@ module OpenC3
         requirements_path = File.join(gem_path, 'requirements.txt')
 
         if File.exist?(pyproject_path) || File.exist?(requirements_path)
-          begin
-            pypi_url = get_setting('pypi_url', scope: scope)
-            if pypi_url
-              pypi_url += '/simple'
-            end
-          rescue => e
-            Logger.error("Failed to retrieve pypi_url: #{e.formatted}")
-          ensure
-            if pypi_url.nil?
-              # If Redis isn't running try the ENV, then simply pypi.org/simple
-              pypi_url = ENV['PYPI_URL']
-              if pypi_url
-                pypi_url += '/simple'
-              end
-              pypi_url ||= PypiUrl::DEFAULT
-            end
-          end
-          pypi_url = PypiUrl.validate(pypi_url)
+          pypi_url = resolve_pypi_url(scope: scope)
           unless validate_only
-            # Build the pip arguments as an argv array and run pipinstall without a
-            # shell. pypi_url comes from a user-writable setting, so interpolating it
-            # into a shell command line allowed OS command injection. An argv array
-            # passes each argument verbatim with no shell metacharacter interpretation.
-            pip_args = ["-i", pypi_url]
-            pip_args += ["--trusted-host", URI.parse(pypi_url).host] unless ENV['PIP_ENABLE_TRUSTED_HOST'].nil?
-            if File.exist?(pyproject_path)
-              Logger.info "Installing python packages from pyproject.toml with pypi_url=#{pypi_url}"
-              pip_args << gem_path
-            else
-              Logger.info "Installing python packages from requirements.txt with pypi_url=#{pypi_url}"
-              pip_args += ["-r", requirements_path]
+            pypi_args = build_pypi_args(pypi_url)
+
+            # Install Python dependencies into an isolated per-plugin venv when UV
+            # is available. Each plugin gets its own venv at /gems/plugin_venvs/<name>/.venv
+            # so that plugins with conflicting Python dependency versions don't interfere.
+            # If UV is unavailable or the install fails, fall back to the shared pipinstall
+            # which installs into PYTHONUSERBASE (the legacy shared environment).
+            uv_installed = ENV['OPENC3_USE_UV'] != 'false' && system('which uv > /dev/null 2>&1')
+            if uv_installed
+              plugin_venv_name = plugin_venv_name(scope: scope, plugin_name: plugin_model.name)
+              Logger.info "Installing python packages into per-plugin venv '#{plugin_venv_name}' with pypi_url=#{pypi_url}"
+              uv_args = [plugin_venv_name, gem_path] + pypi_args
+              output, status = Open3.capture2e("/openc3/bin/uvinstall", *uv_args)
+              puts output
+              if status.success?
+                # A plugin that declares openc3 itself would shadow the system
+                # library once its site-packages goes on PYTHONPATH, so drop it
+                # here rather than let the wrong client reach a running script.
+                PythonVenv.purge_reserved_packages(File.join('/gems', 'plugin_venvs', plugin_venv_name, '.venv'))
+              else
+                Logger.warn "UV per-plugin install failed, falling back to shared pipinstall"
+                uv_installed = false
+              end
             end
-            # Capture output and check exit code so failures surface as a warning
-            # rather than silently succeeding. pipinstall is non-fatal: the plugin
-            # continues to install even if Python packages fail so that non-Python
-            # functionality still works.
-            output, status = Open3.capture2e("/openc3/bin/pipinstall", *pip_args)
-            puts output
-            unless status.success?
-              Logger.warn "Python package installation failed. Plugin Python microservices may not function correctly."
+
+            unless uv_installed
+              pip_args = pypi_args.dup
+              if File.exist?(pyproject_path)
+                Logger.info "Installing python packages from pyproject.toml with pypi_url=#{pypi_url}"
+                pip_args << gem_path
+              else
+                Logger.info "Installing python packages from requirements.txt with pypi_url=#{pypi_url}"
+                pip_args += ["-r", requirements_path]
+              end
+              # Capture output and check exit code so failures surface as a warning
+              # rather than silently succeeding. pipinstall is non-fatal: the plugin
+              # continues to install even if Python packages fail so that non-Python
+              # functionality still works.
+              output, status = Open3.capture2e("/openc3/bin/pipinstall", *pip_args)
+              puts output
+              unless status.success?
+                Logger.warn "Python package installation failed. Plugin Python microservices may not function correctly."
+              end
             end
           end
           needs_dependencies = true
@@ -304,7 +336,7 @@ module OpenC3
         end
         if needs_dependencies
           plugin_model.needs_dependencies = true
-          plugin_model.update unless validate_only
+          plugin_model.update unless dry_run
         end
 
         # Temporarily add all lib folders from the gem to the end of the load path
@@ -343,8 +375,12 @@ module OpenC3
               when 'TARGET', 'INTERFACE', 'ROUTER', 'MICROSERVICE', 'TOOL', 'WIDGET', 'SCRIPT_ENGINE'
                 begin
                   if current_model
-                    current_model.create unless validate_only
-                    current_model.deploy(gem_path, erb_variables, validate_only: validate_only)
+                    current_model.create unless dry_run
+                    if current_model.is_a?(OpenC3::TargetModel)
+                      current_model.deploy(gem_path, erb_variables, validate_only: dry_run, upgrade_context: upgrade_context)
+                    else
+                      current_model.deploy(gem_path, erb_variables, validate_only: dry_run)
+                    end
                   end
                 # If something goes wrong in create, or more likely in deploy,
                 # we want to clear the current_model and try to instantiate the next
@@ -363,8 +399,12 @@ module OpenC3
               end
             end
             if current_model
-              current_model.create unless validate_only
-              current_model.deploy(gem_path, erb_variables, validate_only: validate_only)
+              current_model.create unless dry_run
+              if current_model.is_a?(OpenC3::TargetModel)
+                current_model.deploy(gem_path, erb_variables, validate_only: dry_run, upgrade_context: upgrade_context)
+              else
+                current_model.deploy(gem_path, erb_variables, validate_only: dry_run)
+              end
               current_model = nil
             end
           end
@@ -375,15 +415,26 @@ module OpenC3
         end
       rescue => e
         # Install failed - need to cleanup
-        plugin_model.destroy unless validate_only
+        plugin_model.destroy unless dry_run
         raise e
       ensure
         FileUtils.remove_entry_secure(temp_dir, true)
         tf.unlink if tf
       end
+      return upgrade_context[:diff_collector].uniq if diff_only
       return plugin_model.as_json()
     end
 
+    # Dry run: which modified files would this plugin's install supersede?
+    # Returns a list of "TARGET/path" names whose live (modified) content
+    # differs from the rendered plugin content. Read-only; no side effects.
+    def self.modified_diff(plugin_hash, scope:)
+      install_phase2(plugin_hash, scope: scope, diff_only: true)
+    rescue => e
+      Logger.warn("PluginModel.modified_diff failed: #{e.message}")
+      []
+    end
+
     def initialize(
       name:,
       variables: {},
@@ -482,6 +533,19 @@ module OpenC3
           errors << e
         end
       end
+      # Remove the per-plugin UV virtual environment directory that was created
+      # during install_phase2. This cleans up the .venv, pyproject.toml, uv.lock,
+      # and .uv_managed marker so disk space is reclaimed on plugin uninstall.
+      begin
+        plugin_venv_name = self.class.plugin_venv_name(scope: @scope, plugin_name: @name)
+        plugin_venv_path = File.join('/gems', 'plugin_venvs', plugin_venv_name)
+        if File.directory?(plugin_venv_path)
+          Logger.info("Removing per-plugin Python venv: #{plugin_venv_path}")
+          FileUtils.rm_rf(plugin_venv_path)
+        end
+      rescue Exception => e
+        errors << e
+      end
       # Raise all the errors at once
       if errors.length > 0
         message = ''
@@ -528,6 +592,103 @@ module OpenC3
       return result.sort
     end
 
+    # Resolve the PyPI URL from settings, environment, or default.
+    # Used by both install_phase2 and migrate_to_uv! to avoid duplication.
+    def self.resolve_pypi_url(scope:)
+      pypi_url = nil
+      begin
+        pypi_url = get_setting('pypi_url', scope: scope)
+        pypi_url += '/simple' if pypi_url
+      rescue => e
+        Logger.error("Failed to retrieve pypi_url: #{e.formatted}")
+      ensure
+        if pypi_url.nil?
+          pypi_url = ENV.fetch('PYPI_URL', nil)
+          pypi_url += '/simple' if pypi_url
+          pypi_url ||= PypiUrl::DEFAULT
+        end
+      end
+      PypiUrl.validate(pypi_url)
+    end
+
+    # Build the argv array for pypi index and trusted-host arguments.
+    def self.build_pypi_args(pypi_url)
+      args = ["-i", pypi_url]
+      args += ["--trusted-host", URI.parse(pypi_url).host] unless ENV['PIP_ENABLE_TRUSTED_HOST'].nil?
+      args
+    end
+
+    # Build a sanitized venv directory name from scope and plugin name.
+    # Replaces characters that are not alphanumeric, underscore, or hyphen with underscores.
+    def self.plugin_venv_name(scope:, plugin_name:)
+      "#{scope}__#{plugin_name}".tr('^a-zA-Z0-9_-', '_')
+    end
+
+    # Check if this plugin needs migration to a per-plugin UV virtual environment.
+    # Returns true if the plugin has Python dependencies but no .uv_managed marker exists.
+    def needs_uv_migration?
+      return false unless @needs_dependencies
+
+      plugin_venv_name = self.class.plugin_venv_name(scope: @scope, plugin_name: @name)
+      marker_path = File.join('/gems', 'plugin_venvs', plugin_venv_name, '.uv_managed')
+      !File.exist?(marker_path)
+    end
+
+    # Migrate this plugin from the shared Python venv to a per-plugin UV virtual environment.
+    # Non-fatal: logs a warning on failure, plugin continues using the shared venv.
+    # Returns true on success, false on failure.
+    def migrate_to_uv!(scope:)
+      plugin_venv_name = self.class.plugin_venv_name(scope: scope, plugin_name: @name)
+      marker_path = File.join('/gems', 'plugin_venvs', plugin_venv_name, '.uv_managed')
+      if File.exist?(marker_path)
+        Logger.info("Plugin '#{@name}' is already migrated to a per-plugin UV venv")
+        return true
+      end
+
+      gem_name = @name.split("__")[0]
+      gem_file_path = OpenC3::GemModel.get(gem_name)
+
+      temp_dir = Dir.mktmpdir
+      begin
+        # Extract gem contents (same pattern as install_phase2)
+        gem_path = File.join(temp_dir, "gem")
+        FileUtils.mkdir_p(gem_path)
+        pkg = Gem::Package.new(gem_file_path)
+        pkg.extract_files(gem_path)
+
+        # Check for Python dependency files
+        pyproject_path = File.join(gem_path, 'pyproject.toml')
+        requirements_path = File.join(gem_path, 'requirements.txt')
+
+        unless File.exist?(pyproject_path) || File.exist?(requirements_path)
+          Logger.info("Plugin #{@name} has no Python dependencies to migrate")
+          return true
+        end
+
+        pypi_url = self.class.resolve_pypi_url(scope: scope)
+        pypi_args = self.class.build_pypi_args(pypi_url)
+
+        # Run uvinstall for this plugin
+        plugin_venv_name = self.class.plugin_venv_name(scope: @scope, plugin_name: @name)
+        Logger.info("Migrating plugin '#{@name}' to per-plugin UV venv '#{plugin_venv_name}'")
+        uv_args = [plugin_venv_name, gem_path] + pypi_args
+        output, status = Open3.capture2e("/openc3/bin/uvinstall", *uv_args)
+        puts output
+        if status.success?
+          Logger.info("Successfully migrated plugin '#{@name}' to per-plugin UV venv")
+          return true
+        else
+          Logger.warn("UV migration failed for plugin '#{@name}'. Plugin will continue using shared venv.")
+          return false
+        end
+      rescue => e
+        Logger.warn("UV migration failed for plugin '#{@name}': #{e.message}. Plugin will continue using shared venv.")
+        return false
+      ensure
+        FileUtils.remove_entry_secure(temp_dir, true)
+      end
+    end
+
     # Remove the backing gem for an unloaded plugin so it disappears from
     # GemModel.names (and the admin Packages tab). Skips the removal if any
     # other PluginModel (any scope, any counter) still references the gem,

data/lib/openc3/models/python_package_model.rb

@@ -12,10 +12,13 @@
 # if purchased from OpenC3, Inc.
 
 require 'fileutils'
+require 'open3'
+require 'set'
 require 'openc3/utilities/process_manager'
 require 'openc3/utilities/pypi_url'
 require 'openc3/api/api'
 require 'pathname'
+require 'json'
 
 module OpenC3
   # This class acts like a Model but doesn't inherit from Model because it doesn't
@@ -26,34 +29,191 @@ module OpenC3
     extend Api
 
     DIST_INFO =  '.dist-info'
+    PLUGIN_VENVS_DIR = '/gems/plugin_venvs'       # Per-plugin isolated venvs created by uvinstall
+    SYSTEM_VENV_DIR = '/openc3/python/.venv'       # Core openc3 Python library venv (read-only)
+    DEFAULT_UV_CACHE_DIR = '/gems/uv'              # UV wheel cache, seeded from the Docker image at init
+    UPLOADS_DIR_NAME = 'uploads'                   # Subdirectory under UV cache for uploaded .whl files
+
+    # Normalize a package name to lowercase with hyphens (PEP 503 canonical form)
+    def self.normalize_pkg_name(name)
+      name.tr('_', '-').downcase
+    end
+
+    # Parse a PEP 427 wheel filename into [normalized_name, version].
+    # Handles browser-appended duplicate suffixes like "(1)" on the stem.
+    # Returns nil for non-wheel files or malformed names.
+    # Example: "numpy-2.4.6-cp312-cp312-musllinux_1_2_aarch64.whl" => ["numpy", "2.4.6"]
+    def self.parse_wheel_filename(filename)
+      # Strip browser duplicate suffixes like " (1)" before the .whl extension
+      # Two steps to avoid any space quantifier in the regex:
+      # 1. Remove "(N).whl" at end, replacing with just ".whl"
+      # 2. Clean up leftover spaces before .whl with rstrip
+      clean = filename.sub(/\(\d+\)\.whl\z/i, '.whl')
+      clean = "#{clean.chomp('.whl').rstrip}.whl" if clean.end_with?('.whl')
+      return nil unless clean.end_with?('.whl')
+
+      # PEP 427: {name}-{version}(-{build})?-{python}-{abi}-{platform}.whl
+      # We need at least name-version-python-abi-platform (5 segments)
+      stem = clean.chomp('.whl')
+      parts = stem.split('-')
+      return nil if parts.length < 5
+
+      # The version is always the second segment; everything before it is the name
+      # (some packages have hyphens in their name that become underscores in the wheel)
+      # PEP 427 guarantees: last 3 segments are python-abi-platform,
+      # optional build tag before those, then version, then name (may have multiple segments)
+      # Simplest reliable approach: version is always at index 1
+      name = normalize_pkg_name(parts[0])
+      version = parts[1]
+
+      # Sanity check: version should start with a digit
+      return nil unless version.match?(/\A\d/)
+
+      [name, version]
+    end
 
     def self.names
-      paths = Dir.glob("#{ENV['PYTHONUSERBASE']}/lib/*")
-      results = []
+      result = {}
+
+      # Collect all packages available in the UV download cache
+      # This includes system packages (seeded from the Docker image) plus
+      # any additional packages downloaded during plugin installs
+      cached = cached_packages
+      result['cached'] = cached.sort unless cached.empty?
+
+      # Collect packages from per-plugin venvs
+      if File.directory?(PLUGIN_VENVS_DIR)
+        Dir.glob("#{PLUGIN_VENVS_DIR}/*/").each do |plugin_dir|
+          plugin_name = File.basename(plugin_dir)
+          venv_dir = File.join(plugin_dir, '.venv')
+          next unless File.directory?(venv_dir)
+
+          # Always include plugin venvs even if empty so they remain visible
+          # in the Admin UI and selectable as install targets
+          packages = packages_in_venv(venv_dir)
+          result[plugin_name] = packages.sort
+        end
+      end
+
+      # Also collect packages from the shared venv for backwards compatibility
+      shared_packages = shared_venv_packages
+      result['shared'] = shared_packages.sort unless shared_packages.empty?
+
+      return result
+    end
+
+    # List packages in a specific venv by scanning dist-info directories.
+    # Returns normalized names (lowercase, hyphens) for consistent display.
+    def self.packages_in_venv(venv_dir)
+      packages = []
+      # Look for site-packages in the venv's lib directory
+      Dir.glob("#{venv_dir}/lib/*/site-packages").each do |site_packages|
+        next unless File.directory?(site_packages)
+        Pathname.new(site_packages).children.each do |child|
+          if child.directory? && File.extname(child) == DIST_INFO
+            raw_name = File.basename(child, DIST_INFO)
+            # Normalize: split name from version, normalize name, rejoin
+            match = raw_name.match(/\A(.+?)-(\d.*)/)
+            if match
+              packages << "#{normalize_pkg_name(match[1])}-#{match[2]}"
+            else
+              packages << normalize_pkg_name(raw_name)
+            end
+          end
+        end
+      end
+      packages
+    end
+
+    # List packages in the system venv (/openc3/python/.venv)
+    def self.system_venv_packages
+      packages_in_venv(SYSTEM_VENV_DIR)
+    end
+
+    # List unique packages in the UV download cache.
+    # UV cache structure: wheels-v<N>/<registry>/<package-name>/<version-pytag-abitag-platform>
+    # e.g. wheels-v6/pypi/numpy/2.4.6-cp312-cp312-musllinux_1_2_aarch64
+    # Also scans the uploads/ subdirectory for user-uploaded .whl files.
+    def self.cached_packages
+      cache_dir = ENV.fetch('UV_CACHE_DIR', DEFAULT_UV_CACHE_DIR)
+      return [] unless File.directory?(cache_dir)
+
+      packages = Set.new
+      # Glob 4 levels deep: wheels-v<N>/<registry>/<package-name>/<version-entry>
+      Dir.glob("#{cache_dir}/wheels-v*/*/*/*").each do |entry|
+        basename = File.basename(entry)
+        # Skip UV metadata sidecar files (.http, .msgpack)
+        next if basename.end_with?('.http', '.msgpack')
+
+        # Version entries start with a digit
+        match = basename.match(/\A(\d[^-]*)/)
+        next unless match
+
+        # Parent directory name is the package name
+        pkg_name = File.basename(File.dirname(entry)).tr('_', '-').downcase
+        packages.add("#{pkg_name}-#{match[1]}")
+      end
+
+      # Scan uploaded wheels stored at <cache_dir>/uploads/*.whl
+      uploads_dir = File.join(cache_dir, UPLOADS_DIR_NAME)
+      if File.directory?(uploads_dir)
+        Dir.glob("#{uploads_dir}/*.whl").each do |whl_path|
+          parsed = parse_wheel_filename(File.basename(whl_path))
+          next unless parsed
+
+          packages.add("#{parsed[0]}-#{parsed[1]}")
+        end
+      end
+
+      packages.to_a
+    end
+
+    # List packages in the shared venv (backwards compatibility)
+    def self.shared_venv_packages
+      packages = []
+      pythonuserbase = ENV.fetch('PYTHONUSERBASE', nil)
+      return packages unless pythonuserbase
+
+      paths = Dir.glob("#{pythonuserbase}/lib/*")
       paths.each do |path|
-        results.concat(Pathname.new(File.join(path, 'site-packages')).children.select { |c| c.directory? and File.extname(c) == DIST_INFO }.collect { |p| File.basename(p, DIST_INFO) })
+        site_packages = File.join(path, 'site-packages')
+        next unless File.directory?(site_packages)
+        Pathname.new(site_packages).children.each do |child|
+          if child.directory? && File.extname(child) == DIST_INFO
+            packages << File.basename(child, DIST_INFO)
+          end
+        end
       end
-      return results.sort
+      packages
     end
 
     def self.get(name)
-      path = "#{ENV['PYTHONUSERBASE']}/cache"
+      path = "#{ENV.fetch('PYTHONUSERBASE', nil)}/cache"
       FileUtils.mkdir_p(path) unless Dir.exist?(path)
       result = Pathname.new(path).children.select { |c| c.file? and File.basename(c, File.extname(c)) == name }
       if result.length > 0
         return result[0] if File.exist?(result[0])
       end
-      raise "Package #{name} not found"
+      raise "Package '#{name}' not found"
     end
 
-    def self.put(package_file_path, package_install: true, scope:)
+    def self.put(package_file_path, package_install: true, scope:, plugin: nil)
       if File.file?(package_file_path)
         package_filename = File.basename(package_file_path)
-        FileUtils.mkdir_p("#{ENV['PYTHONUSERBASE']}/cache") unless Dir.exist?("#{ENV['PYTHONUSERBASE']}/cache")
-        cache_path = "#{ENV['PYTHONUSERBASE']}/cache/#{File.basename(package_file_path)}"
+        FileUtils.mkdir_p("#{ENV.fetch('PYTHONUSERBASE')}/cache") unless Dir.exist?("#{ENV.fetch('PYTHONUSERBASE')}/cache")
+        cache_path = "#{ENV.fetch('PYTHONUSERBASE')}/cache/#{File.basename(package_file_path)}"
         FileUtils.cp(package_file_path, cache_path)
+
+        # Copy uploaded .whl files to the UV uploads directory so they appear
+        # in the "Cached" section of the Admin Packages UI
+        if package_filename.end_with?('.whl')
+          uploads_dir = File.join(ENV.fetch('UV_CACHE_DIR', DEFAULT_UV_CACHE_DIR), UPLOADS_DIR_NAME)
+          FileUtils.mkdir_p(uploads_dir)
+          FileUtils.cp(package_file_path, File.join(uploads_dir, package_filename))
+        end
+
         if package_install
-          return self.install(cache_path, scope: scope)
+          return self.install(cache_path, scope: scope, plugin: plugin)
         end
       else
         message = "Package file #{package_file_path} does not exist!"
@@ -63,7 +223,11 @@ module OpenC3
       return nil
     end
 
-    def self.install(name_or_path, scope:)
+    # Install a Python package via pipinstall. When +plugin+ is provided, the
+    # package is installed into that plugin's per-plugin venv instead of the
+    # shared PYTHONUSERBASE. This is used by the Admin Packages tab when a user
+    # selects a specific plugin venv as the install target.
+    def self.install(name_or_path, scope:, plugin: nil)
       if File.exist?(name_or_path)
         package_file_path = name_or_path
       else
@@ -80,7 +244,7 @@ module OpenC3
       ensure
         if pypi_url.nil?
           # If Redis isn't running try the ENV, then simply pypi.org/simple
-          pypi_url = ENV['PYPI_URL']
+          pypi_url = ENV.fetch('PYPI_URL', nil)
           if pypi_url
             pypi_url += '/simple'
           end
@@ -94,18 +258,50 @@ module OpenC3
       else
         pip_args = ["-i", pypi_url, "--trusted-host", URI.parse(pypi_url).host, package_file_path]
       end
-      result = OpenC3::ProcessManager.instance.spawn(["/openc3/bin/pipinstall"] + pip_args, "package_install", package_filename, Time.now + 3600.0, scope: scope)
+      spawn_env = {}
+      if plugin
+        venv_path = "#{PLUGIN_VENVS_DIR}/#{plugin}/.venv"
+        spawn_env['PIPINSTALL_VENV'] = venv_path
+      end
+      result = OpenC3::ProcessManager.instance.spawn(["/openc3/bin/pipinstall"] + pip_args, "package_install", package_filename, Time.now + 3600.0, scope: scope, env: spawn_env)
       return result.name
     end
 
-    def self.destroy(name, scope:)
+    # Uninstall a Python package. When +plugin+ is provided, the package is
+    # removed from that plugin's per-plugin venv; otherwise from the shared venv.
+    def self.destroy(name, scope:, plugin: nil)
       package_name, version = self.extract_name_and_version(name)
       Logger.info "Uninstalling package: #{name}"
       pip_args = [package_name]
-      result = OpenC3::ProcessManager.instance.spawn(["/openc3/bin/pipuninstall"] + pip_args, "package_uninstall", name, Time.now + 3600.0, scope: scope)
+      spawn_env = {}
+      if plugin
+        venv_path = "#{PLUGIN_VENVS_DIR}/#{plugin}/.venv"
+        spawn_env['PIPINSTALL_VENV'] = venv_path
+      end
+      result = OpenC3::ProcessManager.instance.spawn(["/openc3/bin/pipuninstall"] + pip_args, "package_uninstall", name, Time.now + 3600.0, scope: scope, env: spawn_env)
       return result.name
     end
 
+    # Returns a hash of plugin_name => "uv pip list" text output for each plugin venv.
+    def self.trees
+      result = {}
+
+      if File.directory?(PLUGIN_VENVS_DIR)
+        Dir.glob("#{PLUGIN_VENVS_DIR}/*/").each do |plugin_dir|
+          plugin_name = File.basename(plugin_dir)
+          venv_dir = File.join(plugin_dir, '.venv')
+          next unless File.directory?(venv_dir)
+
+          stdout, status = Open3.capture2('uv', 'pip', 'list', '--python', venv_dir)
+          if status.success? && stdout.lines.length > 2
+            result[plugin_name] = stdout.rstrip
+          end
+        end
+      end
+
+      result
+    end
+
     def self.extract_name_and_version(name)
       split_name = name.split('-')
       if split_name.length > 1