openc3 7.2.1 → 7.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13ecd5ed69a40943e0ceb4732af0922106d73ba3e28c7e10521e3cbcbb2728c9
-  data.tar.gz: e8a55a75e964de92cdc8fa9a27091d472437004a0775a05c894d4a16d5232677
+  metadata.gz: 3d94ef0547084256ba519d150e9e7637fe2623ad68703fb56ff43579ceb1119b
+  data.tar.gz: bb907222d40154d622e73fb8732ff2715186183f5ce097f58832839ea3621fb3
 SHA512:
-  metadata.gz: 77c7ed5bcae0862bf8d7ccdeefbc79cdc814b04501831e5de5a2b7b1d685420f731da2bb230435a1d091697156ab1d58a40cf793869da48e191b7c87ccbffea9
-  data.tar.gz: 90571e3012ae117610314df3d32d67d77a843f2de8edb2c9b51bab3335cf0618e7301a9ba0c55616acad6a2d0ca1b4634924531f657bd438c0fd490aeca6a327
+  metadata.gz: d59f2a554a6fd751533736e12088e85958e9fe8569ccc2ffde017e68c00626b39ddd7f08334e9e9f83fa47a599b8c0a803c0da248b945a7dff3f8e41a41085cc
+  data.tar.gz: 54c6fc8f881f6ccfef18dd8e37ebbe99b078e199f95738b9f6da5d24183d279252a9ee563c2be338d4f4e2cf32bb0299b4761727b40ffb5f771e354ba3877538

data/Gemfile

@@ -1,6 +1,6 @@
 # encoding: ascii-8bit
 
-source ENV['RUBYGEMS_URL'] || "https://rubygems.org"
+source "https://rubygems.org"
 
 gemspec :name => 'openc3'
 

data/bin/openc3cli

@@ -20,6 +20,7 @@
 
 require 'openc3'
 require 'openc3/bridge/bridge'
+require 'openc3/models/bridge_model'
 require 'openc3/models/gem_model'
 require 'openc3/models/migration_model'
 require 'openc3/models/plugin_model'
@@ -67,6 +68,7 @@ def print_usage
   puts "  cli load /PATH/FILENAME.gem SCOPE plugin_hash.json    # Loads a COSMOS plugin gem file"
   puts "    OPTIONS: --variables lets you pass a path to a JSON file containing your plugin's variables"
   puts "  cli list <SCOPE>                  # Lists installed plugins, SCOPE is DEFAULT if not given"
+  puts "  cli unload PLUGIN_NAME [SCOPE]    # Unload an installed COSMOS plugin"
   puts "  cli generate TYPE OPTIONS         # Generate various COSMOS entities"
   puts "    OPTIONS: --ruby or --python is required to specify the language in the generated code unless OPENC3_LANGUAGE is set"
   puts "  cli bridge CONFIG_FILENAME        # Run COSMOS host bridge"
@@ -77,6 +79,8 @@ def print_usage
   puts "  cli xtce_converter                # Convert to and from the XTCE format. Run with --help for more info."
   puts "  cli cstol_converter               # Converts CSTOL files (.prc) to COSMOS. Run with --help for more info."
   puts "  cli setpassword                   # Set the initial password from OPENC3_API_PASSWORD env var"
+  puts "  cli initsettings                  # Seed settings from OPENC3_SETTING_* env vars"
+  puts "  cli migratetouv PLUGIN_NAME SCOPE # Migrate plugin to per-plugin UV virtual environment"
   puts ""
 end
 
@@ -102,6 +106,42 @@ def check_environment
   end
 end
 
+# Report how an existing .xtce file fares against the XTCE 1.2 schema without failing
+def xtce_report_validation(filename)
+  namespace = OpenC3::XtceConverter.xtce_namespace(filename)
+  if namespace != OpenC3::XtceConverter::XTCE_1_2_NAMESPACE
+    puts "#{File.basename(filename)} declares #{namespace ? namespace : 'no XTCE namespace'}, skipping XTCE 1.2 schema validation"
+    return
+  end
+  errors = OpenC3::XtceConverter.schema_errors(filename)
+  if errors.empty?
+    puts "#{File.basename(filename)} is valid XTCE 1.2"
+  else
+    $stderr.puts "WARNING: #{filename} is not valid XTCE 1.2:"
+    errors.each { |error| $stderr.puts "  #{error}" }
+  end
+end
+
+# Validate every .xtce file written under output_dir. Returns false if any is invalid.
+def xtce_validate_exported(output_dir)
+  files = Dir.glob(File.join(output_dir, "**", "*.xtce")).sort
+  if files.empty?
+    $stderr.puts "ERROR: no .xtce files were written to #{output_dir}"
+    return false
+  end
+  valid = true
+  files.each do |filename|
+    errors = OpenC3::XtceConverter.schema_errors(filename)
+    next if errors.empty?
+
+    valid = false
+    $stderr.puts "ERROR: #{filename} is not valid XTCE 1.2:"
+    errors.each { |error| $stderr.puts "  #{error}" }
+  end
+  puts "Validated #{files.length} .xtce file(s) against the OMG XTCE 1.2 schema" if valid
+  valid
+end
+
 def xtce_converter(args)
   options = {}
   option_parser = OptionParser.new do |opts|
@@ -122,14 +162,17 @@ def xtce_converter(args)
     opts.on("-p", "--plugin PLUGIN", "Export .xtce file(s) from the plugin") do |arg|
       options[:plugin] = arg
     end
-    opts.on("-v", "--variables", "Optional variables file to pass to the plugin") do |arg|
+    opts.on("-v VARIABLES", "--variables VARIABLES", "Optional variables file to pass to the plugin") do |arg|
       options[:variables] = arg
     end
     opts.on("-r ROOT_TARGET", "--root_target ROOT_TARGET", "Optional flag to set which target is at the root of an XTCE document. If not specified, each target will be placed under a generic 'root' spacesystem") do |arg|
       options[:root_target_name] = arg
     end
-    opts.on("-t TIME_ASSOCIATION_NAME", "--time_association_name TIME_ASSOCIATION_NAME", "Optional flag to set which target is at the root of an XTCE document. If not specified, each target will be placed under a generic 'root' spacesystem") do |arg|
-      options[:time_association_name] = "PACKET_TIME"
+    opts.on("-t TIME_ASSOCIATION_NAME", "--time_association_name TIME_ASSOCIATION_NAME", "Optional telemetry item name to export as each packet's time, emitted as a TimeAssociation. If not specified, no TimeAssociation is written") do |arg|
+      options[:time_association_name] = arg
+    end
+    opts.on("--[no-]validate", "Validate .xtce files against the OMG XTCE 1.2 schema. On by default when exporting, where an invalid file fails the export. Off by default when importing, where it only reports since COSMOS also imports XTCE 1.0 / 1.1") do |arg|
+      options[:validate] = arg
     end
   end
 
@@ -149,6 +192,9 @@ def xtce_converter(args)
   OpenC3::Logger.level = OpenC3::Logger::DEBUG
 
   if options[:import] && options[:output]
+    # Reporting only. COSMOS imports XTCE 1.0 / 1.1 too, and those report errors against
+    # the 1.2 schema while importing perfectly well, so this never blocks an import.
+    xtce_report_validation(options[:import]) if options[:validate]
     packet_config = OpenC3::PacketConfig.new
     puts "Processing #{options[:import]}..."
     packet_config.process_file(options[:import], nil)
@@ -166,7 +212,14 @@ def xtce_converter(args)
       OpenC3::PluginModel.install_phase2(plugin_hash, scope: 'DEFAULT', validate_only: true,
         gem_file_path: options[:plugin])
       OpenC3::XtceConverter.combine_output_xtce(options[:output], options[:root_target_name])
-      result = 0 # bash and Windows consider 0 success
+      # Validate what we just wrote unless told not to. An exporter bug that only shows
+      # up on a particular config otherwise produces a file that looks fine here and is
+      # rejected by whatever ground system it was written for.
+      if options[:validate] == false
+        result = 0
+      else
+        result = xtce_validate_exported(options[:output]) ? 0 : ERROR_CODE
+      end # bash and Windows consider 0 success
     rescue => e
       puts "Error: #{e.message}"
       puts e.backtrace
@@ -226,7 +279,7 @@ ensure
   exit(result)
 end
 
-def update_plugin(plugin_file_path, plugin_name, variables: nil, plugin_txt_lines: nil, scope:, existing_plugin_name:, force: false)
+def update_plugin(plugin_file_path, plugin_name, variables: nil, plugin_txt_lines: nil, scope:, existing_plugin_name:, force: false, username: nil, version_history_files: nil)
   new_gem = File.basename(plugin_file_path)
   old_gem = existing_plugin_name.split("__")[0]
   puts "Updating existing plugin: #{existing_plugin_name} with #{File.basename(plugin_file_path)}"
@@ -247,6 +300,10 @@ def update_plugin(plugin_file_path, plugin_name, variables: nil, plugin_txt_line
       plugin_model.destroy
 
       plugin_hash = OpenC3::PluginModel.install_phase1(plugin_file_path, existing_variables: variables, existing_plugin_txt_lines: plugin_txt_lines, process_existing: true, scope: scope)
+      # Carry Version History upgrade hints into the regenerated hash so
+      # install_phase2 can version modified files taken from the plugin.
+      plugin_hash['username'] = username if username
+      plugin_hash['version_history_files'] = version_history_files if version_history_files
       puts "Updating plugin: #{plugin_file_path}\n#{plugin_hash}"
       plugin_hash = OpenC3::PluginModel.install_phase2(plugin_hash, scope: scope)
       OpenC3::LocalMode.update_local_plugin(plugin_file_path, plugin_hash, old_plugin_name: plugin_name, scope: scope)
@@ -410,7 +467,8 @@ def load_plugin(plugin_file_path, scope:, plugin_hash_file: nil, force: false, v
       if existing_plugin_hash
         # Upgrade or Edit
         update_plugin(plugin_file_path, plugin_hash['name'], variables: plugin_hash['variables'], scope: scope,
-          plugin_txt_lines: plugin_hash['plugin_txt_lines'], existing_plugin_name: existing_plugin_hash['name'], force: force)
+          plugin_txt_lines: plugin_hash['plugin_txt_lines'], existing_plugin_name: existing_plugin_hash['name'], force: force,
+          username: plugin_hash['username'], version_history_files: plugin_hash['version_history_files'])
       else
         # New Install
         puts "Loading new plugin: #{plugin_file_path}\n#{plugin_hash}"
@@ -447,6 +505,10 @@ def unload_plugin(plugin_name, scope:)
       # Remove the backing gem now that no PluginModel references it,
       # so it disappears from the admin Packages tab.
       OpenC3::PluginModel.cleanup_gem(plugin_name, scope: scope)
+      # Drop this plugin's Version History repo. Uninstall-only: the upgrade
+      # path (update_plugin) reuses the repo and never reaches here, so history
+      # survives version bumps. No-op in Core / when versioning is disabled.
+      OpenC3::TargetModel.destroy_script_versions(plugin_name, scope: scope)
       OpenC3::Logger.info("PluginModel destroyed: #{plugin_name}", scope: scope)
     rescue => e
       abort("Error uninstalling plugin: #{scope}: #{plugin_name}: #{e.formatted}")
@@ -1209,6 +1271,42 @@ if not ARGV[0].nil? # argument(s) given
     params = [] unless params
     run_bridge(filename, params)
 
+  when 'bridgeenroll'
+    if ARGV[1].nil? || ARGV[1] == '--help' || ARGV[1] == '-h'
+      puts "Usage: cli bridgeenroll BRIDGE_NAME APP_PUBLIC_KEY [SCOPE]"
+      puts ""
+      puts "Authorize an openc3-app control identity for a bridge (Iroh hub) and"
+      puts "print that bridge's current connection ticket. Used by openc3-app to"
+      puts "auto-enroll over the local Docker control plane: the bridge then only"
+      puts "accepts api/* control connections from the given app identity."
+      puts ""
+      puts "Arguments:"
+      puts "  BRIDGE_NAME       Name of the bridge (hub)"
+      puts "  APP_PUBLIC_KEY    openc3-app's Iroh public key (EndpointId, hex)"
+      puts "  SCOPE             Scope (optional, default: OPENC3_SCOPE or DEFAULT)"
+      puts ""
+      puts "On success the bridge ticket is printed alone on stdout."
+      exit 0
+    end
+    bridge_name = ARGV[1].to_s.upcase
+    app_public_key = ARGV[2]
+    abort("APP_PUBLIC_KEY is required (see --help)") if app_public_key.nil? || app_public_key.empty?
+    unless app_public_key.match?(/\A[0-9a-f]{64}\z/i)
+      abort("APP_PUBLIC_KEY must be exactly 64 hexadecimal characters")
+    end
+    app_public_key = app_public_key.downcase
+    scope = ARGV[3] || ENV['OPENC3_SCOPE'] || 'DEFAULT'
+    model = OpenC3::BridgeModel.get_model(name: bridge_name, scope: scope)
+    abort("Bridge '#{bridge_name}' not found in scope #{scope}. Is its bridge_microservice running?") unless model
+    if model.ticket.nil? || model.ticket.empty?
+      abort("Bridge '#{bridge_name}' has no ticket yet. Is its bridge_microservice running?")
+    end
+    old_app_public_key = model.app_public_key
+    model.app_public_key = app_public_key
+    model.update
+    # Print ONLY the ticket so openc3-app can capture it from stdout.
+    puts model.ticket
+
   when 'bridgegem'
     if ARGV[1].nil? || ARGV[1] == '--help' || ARGV[1] == '-h'
       puts "Usage: cli bridgegem GEM_NAME [PARAMS...]"
@@ -1432,6 +1530,106 @@ if not ARGV[0].nil? # argument(s) given
     # Always ensure the scriptrunner policy is in place since it is required for script execution
     client.ensure_scriptrunner_policy(ENV['OPENC3_CONFIG_BUCKET'], ENV['OPENC3_LOGS_BUCKET'])
 
+  when 'initsettings'
+    if ARGV[1] == '--help' || ARGV[1] == '-h'
+      puts "Usage: cli initsettings [--dry-run | --export]"
+      puts ""
+      puts "Seed COSMOS settings from the environment. A setting changed in the Admin"
+      puts "Console is left alone, so those edits survive a restart."
+      puts ""
+      puts "Environment:"
+      puts "  OPENC3_SETTING_<NAME>          One variable per setting, e.g."
+      puts "                                 OPENC3_SETTING_TIME_ZONE=UTC sets 'time_zone'"
+      puts "  OPENC3_SETTINGS_OVERWRITE      true to overwrite existing settings on every"
+      puts "                                 run. false/unset leaves them alone"
+      puts "  OPENC3_SETTINGS_ALLOW_UNKNOWN  true to allow setting names COSMOS doesn't"
+      puts "                                 recognize. Without it an unknown name is"
+      puts "                                 reported and skipped, so a typo can't"
+      puts "                                 silently do nothing"
+      puts "  OPENC3_SETTINGS_STRICT         true to exit non-zero when a setting is"
+      puts "                                 rejected. Off by default"
+      puts ""
+      puts "These three accept true/false (1/0 also work)."
+      puts ""
+      puts "A setting that already exists is left alone because an operator may have"
+      puts "edited it in the Admin Console. Settings written by a release before this"
+      puts "command existed carry no record of having been seeded, so they all count as"
+      puts "edited: on such an upgrade run one init with OPENC3_SETTINGS_OVERWRITE=true"
+      puts "to adopt the environment values, then turn it back off."
+      puts ""
+      puts "An unrecognized name, an invalid value, or a malformed one of the variables"
+      puts "above is reported on stdout and that one setting is skipped; init continues"
+      puts "and COSMOS uses the default. Nothing here fails init unless"
+      puts "OPENC3_SETTINGS_STRICT is set. Use --dry-run to check the same things before"
+      puts "starting COSMOS, where a non-zero exit is what you want."
+      puts ""
+      puts "Settings that can be seeded:"
+      OpenC3::SettingModel.describe_settings.each { |line| puts "  #{line}" }
+      puts ""
+      puts "Boolean settings accept true/false (1/0 also work) and are stored as real"
+      puts "booleans."
+      puts "Every other setting is stored as the text given, including the settings"
+      puts "whose text is JSON (astro, classification_banner, context_tag)."
+      puts ""
+      puts "JSON settings - shape of each blob:"
+      OpenC3::SettingModel.describe_json_settings.each do |name, example|
+        puts "  #{name}"
+        puts "    #{example}"
+      end
+      puts ""
+      puts "Rather than hand-writing one of those, configure it in Admin -> Settings"
+      puts "and run 'cli initsettings --export' to print the current values as lines"
+      puts "you can paste straight into compose.override.yaml."
+      puts ""
+      puts "Options:"
+      puts "      --dry-run     Report what would be seeded and exit without writing."
+      puts "                    Lists every problem rather than stopping at the first,"
+      puts "                    and works before Redis is up so it can be run ahead of"
+      puts "                    starting COSMOS. Exits non-zero if anything would fail,"
+      puts "                    regardless of OPENC3_SETTINGS_STRICT"
+      puts "      --export      Print the settings currently stored as compose"
+      puts "                    'environment:' lines, quoted so the JSON ones parse."
+      puts "                    Configure in Admin -> Settings, then export and paste."
+      puts "                    Reads Redis, so COSMOS must be running - unlike"
+      puts "                    --dry-run, which works while it is down"
+      puts "  -h, --help        Show this help message"
+      exit 0
+    end
+    dry_run = ARGV[1] == '--dry-run'
+    export = ARGV[1] == '--export'
+    if ARGV[1] and !dry_run and !export
+      abort "Unknown option #{ARGV[1]}. See 'cli initsettings --help'"
+    end
+    if export
+      # --export reads the stored values, so it needs a reachable Redis. Say so
+      # plainly - the raw connection error is something like
+      # "Bad file descriptor (redis://openc3-redis:6379)", which doesn't hint
+      # that the answer is to start COSMOS.
+      unless OpenC3::SettingModel.redis_available?
+        abort "Cannot reach Redis at #{ENV['OPENC3_REDIS_HOSTNAME']}:#{ENV['OPENC3_REDIS_PORT']}.\n" \
+              "--export reads the settings currently stored, so COSMOS has to be running.\n" \
+              "Start it with './openc3.sh run', or use --dry-run, which works while COSMOS is down."
+      end
+      begin
+        lines = OpenC3::SettingModel.export_lines
+      rescue => e
+        abort "Error reading settings: #{e.message}"
+      end
+      if lines.empty?
+        puts "# No settings are stored yet - configure them in Admin -> Settings first"
+      else
+        puts "# Paste under the openc3-cosmos-init service's \"environment:\" key in"
+        puts "# compose.override.yaml, keeping this indentation."
+        lines.each { |line| puts "      #{line}" }
+      end
+    else
+      begin
+        OpenC3::SettingModel.apply_defaults(dry_run: dry_run)
+      rescue => e
+        abort "Error applying default settings: #{e.message}"
+      end
+    end
+
   when 'runmigrations'
     if ARGV[1] == '--help' || ARGV[1] == '-h'
       puts "Usage: cli runmigrations"
@@ -1463,6 +1661,37 @@ if not ARGV[0].nil? # argument(s) given
   when 'migratepassword'
     migrate_password_hash()
 
+  when 'migratetouv'
+    if ARGV[1].nil? || ARGV[1] == '--help' || ARGV[1] == '-h'
+      puts "Usage: cli migratetouv PLUGIN_NAME [SCOPE]"
+      puts ""
+      puts "Migrate a plugin from the shared Python venv to a per-plugin UV virtual environment"
+      puts ""
+      puts "Arguments:"
+      puts "  PLUGIN_NAME       Name of the plugin to migrate (required)"
+      puts "  SCOPE             Scope of the plugin (optional, default: DEFAULT)"
+      puts ""
+      puts "Options:"
+      puts "  -h, --help        Show this help message"
+      exit(ARGV[1].nil? ? 1 : 0)
+    end
+    scope = ARGV[2] || 'DEFAULT'
+    check_environment()
+    begin
+      plugin_model = OpenC3::PluginModel.get_model(name: ARGV[1], scope: scope)
+      if plugin_model.nil?
+        abort("Plugin '#{ARGV[1]}' not found in scope '#{scope}'")
+      end
+      if plugin_model.migrate_to_uv!(scope: scope)
+        puts "Successfully migrated plugin '#{ARGV[1]}' to per-plugin UV venv"
+      else
+        puts "Migration failed for plugin '#{ARGV[1]}'. Check logs for details."
+        exit 1
+      end
+    rescue => e
+      abort("Error migrating plugin: #{e.formatted}")
+    end
+
   else # Unknown task
     print_usage()
     abort("Unknown task: #{ARGV[0]}")

data/bin/pipinstall

@@ -1,7 +1,8 @@
 #!/bin/sh
-uv venv "$PYTHONUSERBASE" --allow-existing
+VENV="${PIPINSTALL_VENV:-$PYTHONUSERBASE}"
+uv venv "$VENV" --allow-existing
 echo "uv pip install $@"
-uv pip install --python "$PYTHONUSERBASE" "$@"
+uv pip install --python "$VENV" "$@"
 if [ $? -eq 0 ]; then
     echo "Command succeeded"
     exit 0
@@ -27,7 +28,7 @@ if [ -d "$LAST_ARG" ] && [ -f "$LAST_ARG/pyproject.toml" ]; then
     TMPFILE=$(mktemp)
     uv pip compile ${OPTS} "${LAST_ARG}/pyproject.toml" > "$TMPFILE"
     if [ $? -eq 0 ] && [ -s "$TMPFILE" ]; then
-        uv pip install --python "$PYTHONUSERBASE" ${OPTS} -r "$TMPFILE"
+        uv pip install --python "$VENV" ${OPTS} -r "$TMPFILE"
         if [ $? -eq 0 ]; then
             echo "Dependencies installed successfully"
             rm -f "$TMPFILE"
@@ -38,7 +39,7 @@ if [ -d "$LAST_ARG" ] && [ -f "$LAST_ARG/pyproject.toml" ]; then
 fi
 
 echo "Warning: Install failed - retrying with --no-index"
-uv pip install --python "$PYTHONUSERBASE" --no-index "$@"
+uv pip install --python "$VENV" --no-index "$@"
 if [ $? -ne 0 ]; then
     echo "ERROR: uv pip install failed"
     exit 1

data/bin/pipuninstall

@@ -1,6 +1,10 @@
 #!/bin/sh
+# Uninstall a Python package from a venv. When PIPINSTALL_VENV is set (by
+# PythonPackageModel.destroy for per-plugin venvs), uninstall from that venv.
+# Otherwise fall back to the shared PYTHONUSERBASE.
+VENV="${PIPINSTALL_VENV:-$PYTHONUSERBASE}"
 echo "uv pip uninstall $@"
-uv pip uninstall --python "$PYTHONUSERBASE" "$@"
+uv pip uninstall --python "$VENV" "$@"
 if [ $? -eq 0 ]; then
     echo "Command succeeded"
 else

data/bin/uvinstall

@@ -0,0 +1,156 @@
+#!/bin/sh
+# Per-plugin UV virtual environment installer
+# Usage: uvinstall <plugin_venv_name> <gem_path> [extra uv args...]
+#
+# Creates an isolated venv at /gems/plugin_venvs/<plugin_venv_name>/.venv
+# and installs Python dependencies from the plugin's gem_path.
+#
+# Two installation paths:
+#   1. If gem_path contains uv.lock: uses `uv sync --frozen` (reproducible)
+#   2. Otherwise: falls back to `uv pip install` for requirements.txt / pyproject.toml
+#
+# Network safety: uv's own HTTP controls (connect timeout, read timeout,
+# bounded retries) make a slow or unreachable index fail fast instead of
+# hanging the plugin install (which stalls the whole deploy - the init hook
+# never completes and helm's --wait times out). These are idle/connect
+# timeouts, NOT a total-transfer cap, so a large but healthy download (e.g.
+# torch over a slow link) is never killed mid-stream as long as bytes keep
+# arriving. Both paths try OFFLINE first so a plugin whose wheels are already
+# in the seeded UV cache installs deterministically without ever touching the
+# network.
+
+PLUGIN_VENV_NAME="$1"
+GEM_PATH="$2"
+shift 2
+UV_ARGS="$@"
+
+if [ -z "$PLUGIN_VENV_NAME" ] || [ -z "$GEM_PATH" ]; then
+    echo "Usage: uvinstall <plugin_venv_name> <gem_path> [extra uv args...]"
+    exit 1
+fi
+
+# Bound uv's network behavior with uv's own HTTP knobs. Unlike a blunt
+# wall-clock cap, these fail fast on a dead/unreachable index or a stalled
+# connection WITHOUT killing a large but progressing download. All overridable.
+#   UV_HTTP_CONNECT_TIMEOUT - give up connecting to an unreachable index (s)
+#   UV_HTTP_TIMEOUT         - give up when a connection stalls mid-read (s)
+#   UV_HTTP_RETRIES         - bounded retries for transient failures
+# The values below match uv's own defaults; they are set explicitly so plugin
+# installs keep this behavior even if a future uv release changes its defaults,
+# and so an operator has a documented place to raise them for a slow index.
+export UV_HTTP_CONNECT_TIMEOUT="${UV_HTTP_CONNECT_TIMEOUT:-10}"
+export UV_HTTP_TIMEOUT="${UV_HTTP_TIMEOUT:-30}"
+export UV_HTTP_RETRIES="${UV_HTTP_RETRIES:-3}"
+
+# Run a uv command offline first (cache-only: instant, cannot hang, works in
+# air-gapped clusters) and only retry online on a cache miss. Both paths below
+# use this so a plugin whose wheels are already in the seeded UV cache never
+# touches the network.
+uv_offline_then_online() {
+    if uv "$@" --offline; then
+        return 0
+    fi
+    # Expected for any plugin whose wheels aren't in the seeded cache (a new
+    # third-party plugin, or a pin that differs from the one baked in), so this
+    # is informational, not an error - the online attempt below is the real one.
+    echo "Offline uv cache miss; retrying online"
+    uv "$@"
+}
+
+VENV_BASE="/gems/plugin_venvs/${PLUGIN_VENV_NAME}"
+VENV_DIR="${VENV_BASE}/.venv"
+
+echo "Creating per-plugin venv for '${PLUGIN_VENV_NAME}' at ${VENV_DIR}"
+mkdir -p "${VENV_BASE}"
+
+# Path 1: uv.lock present - use `uv sync --frozen` for reproducible installs
+if [ -f "${GEM_PATH}/uv.lock" ] && [ -f "${GEM_PATH}/pyproject.toml" ]; then
+    echo "Found uv.lock - using uv sync --frozen for reproducible install"
+
+    # Copy pyproject.toml and uv.lock into the venv base directory
+    cp "${GEM_PATH}/pyproject.toml" "${VENV_BASE}/pyproject.toml"
+    cp "${GEM_PATH}/uv.lock" "${VENV_BASE}/uv.lock"
+
+    # Create venv and sync dependencies
+    cd "${VENV_BASE}"
+    uv venv "${VENV_DIR}" --allow-existing
+
+    # Offline sync first, online only on a cache miss (bounded by UV_HTTP_*).
+    # --inexact keeps sync additive: without it sync makes the venv match the
+    # lock exactly and uninstalls anything else, including packages an admin
+    # uploaded into this plugin venv via PythonPackageModel.install (which uses
+    # the additive `pipinstall`).
+    uv_offline_then_online sync --frozen --inexact --no-dev --no-install-project ${UV_ARGS}
+    RESULT=$?
+
+    if [ $RESULT -eq 0 ]; then
+        echo "uv sync --frozen succeeded"
+        touch "${VENV_BASE}/.uv_managed"
+        exit 0
+    fi
+
+    echo "Warning: uv sync --frozen failed (exit code ${RESULT}), falling back to uv pip install"
+fi
+
+# Path 2: Fallback - use uv pip install for requirements.txt or pyproject.toml
+# Every install here is also offline-first (same reasoning as path 1), so an
+# unlocked plugin whose wheels happen to be cached installs without network too.
+uv venv "${VENV_DIR}" --allow-existing
+
+if [ -f "${GEM_PATH}/requirements.txt" ]; then
+    echo "Installing from requirements.txt via uv pip install"
+    uv_offline_then_online pip install --python "${VENV_DIR}" ${UV_ARGS} -r "${GEM_PATH}/requirements.txt"
+    RESULT=$?
+elif [ -f "${GEM_PATH}/pyproject.toml" ]; then
+    echo "Installing from pyproject.toml via uv pip install"
+    # --python: The Python interpreter into which packages should be installed.
+    # --project: Discover a project (i.e. pyproject.toml) in the given directory.
+    # -r: Install the packages listed in the given files.
+    uv_offline_then_online pip install --python "${VENV_DIR}" --project "${GEM_PATH}" ${UV_ARGS} -r "${GEM_PATH}/pyproject.toml"
+    RESULT=$?
+
+    # `uv pip install <path>` builds the plugin as a package before installing
+    # its dependencies, which fails for a pyproject.toml that only declares
+    # dependencies and isn't a buildable distribution (no [build-system], a
+    # missing/empty source layout, or a build backend that can't run offline).
+    # Fall back to installing the declared dependencies without building. The
+    # compile step only resolves declared deps into a pinned requirements file;
+    # the install that follows it is the one that fetches, so it gets the same
+    # offline-then-online treatment. Each compile attempt re-truncates TMPFILE
+    # so a partial offline write can never be mixed into the online result.
+    if [ $RESULT -ne 0 ]; then
+        echo "Warning: Failed to build Python package, attempting to install declared dependencies from pyproject.toml"
+        TMPFILE=$(mktemp)
+        uv pip compile --offline ${UV_ARGS} "${GEM_PATH}/pyproject.toml" > "$TMPFILE"
+        COMPILED=$?
+        if [ $COMPILED -ne 0 ] || [ ! -s "$TMPFILE" ]; then
+            echo "Offline uv pip compile missed the cache; retrying online"
+            uv pip compile ${UV_ARGS} "${GEM_PATH}/pyproject.toml" > "$TMPFILE"
+            COMPILED=$?
+        fi
+        # Both the exit status AND a non-empty file are required: uv writes its
+        # "autogenerated by uv" header before resolution runs, so a compile that
+        # fails partway still leaves a non-empty file. Installing from that would
+        # produce a venv missing dependencies and report success.
+        if [ $COMPILED -eq 0 ] && [ -s "$TMPFILE" ]; then
+            uv_offline_then_online pip install --python "${VENV_DIR}" ${UV_ARGS} -r "$TMPFILE"
+            RESULT=$?
+        fi
+        rm -f "$TMPFILE"
+    fi
+else
+    echo "ERROR: No requirements.txt, pyproject.toml, or uv.lock found in ${GEM_PATH}"
+    exit 1
+fi
+
+if [ $RESULT -eq 0 ]; then
+    echo "Python packages installed successfully"
+    touch "${VENV_BASE}/.uv_managed"
+    exit 0
+fi
+
+# No --no-index last resort here anymore: every attempt above already ran
+# cache-only first via uv_offline_then_online, so a cache-only retry at this
+# point would repeat an attempt that has already failed.
+echo "ERROR: uvinstall failed for plugin ${PLUGIN_VENV_NAME}"
+exit 1

data/data/config/command_modifiers.yaml

@@ -284,6 +284,8 @@ TEMPLATE_FILE:
     - name: Template File Path
       required: true
       description: The relative path to the template file. Filename should generally start with an underscore.
+        Absolute paths and paths containing '..' are not allowed. The file must be inside the directory
+        containing the definition file.
       values: .+
   since: 5.0.10
 RESPONSE: