CAMEL-23276: Add PluginRunCustomizer to JBang Plugin SPI

dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/commands/Run.java

@@ -967,8 +967,18 @@ private int run() throws Exception {
         addRuntimeSpecificDependenciesFromProperties(profileProperties);
 
         // Add plugin dependencies
+        Map<String, Plugin> activePlugins = Collections.emptyMap();
         if (!skipPlugins) {
-            Set<PluginExporter> exporters = PluginHelper.getActivePlugins(getMain(), repositories).values()
+            activePlugins = PluginHelper.getActivePlugins(getMain(), repositories);
+
+            // Let plugins customize the run environment (e.g., set config directories)
+            // before plugin exporter dependencies are added, so exporters can scan the right locations
+            for (Plugin plugin : activePlugins.values()) {
+                plugin.getRunCustomizer()
+                        .ifPresent(customizer -> customizer.beforeRun(main, Collections.unmodifiableList(files)));
+            }
+
+            Set<PluginExporter> exporters = activePlugins.values()
                     .stream()
                     .map(Plugin::getExporter)
                     .filter(Optional::isPresent)

dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/common/Plugin.java

@@ -42,4 +42,15 @@ public interface Plugin {
     default Optional<PluginExporter> getExporter() {
         return Optional.empty();
     }
+
+    /**
+     * The plugin may provide an optional run customizer that is called after the Run command has resolved file
+     * arguments and basic dependencies, but before plugin exporter dependencies are added and KameletMain.run() builds
+     * the CamelContext.
+     *
+     * @return the plugin specific run customizer implementation, otherwise empty
+     */
+    default Optional<PluginRunCustomizer> getRunCustomizer() {
+        return Optional.empty();
+    }
 }

dsl/camel-jbang/camel-jbang-core/src/main/java/org/apache/camel/dsl/jbang/core/common/PluginRunCustomizer.java

@@ -0,0 +1,40 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.dsl.jbang.core.common;
+
+import java.util.List;
+
+import org.apache.camel.main.KameletMain;
+
+/**
+ * Plugin hook that runs after the Run command has resolved file arguments and basic dependencies, but before plugin
+ * exporter dependencies are added and {@link KameletMain#run()} builds the CamelContext.
+ *
+ * This allows plugins to customize the environment (system properties, config directories, initial properties) based on
+ * the file arguments passed to the run command, so that plugin exporters can scan the right locations.
+ */
+public interface PluginRunCustomizer {
+
+    /**
+     * Called after the Run command has resolved file arguments and basic dependencies, but before plugin exporter
+     * dependencies are added and KameletMain.run() builds the CamelContext.
+     *
+     * @param main  the KameletMain instance (for adding initial properties)
+     * @param files the resolved file arguments passed to the run command (read-only)
+     */
+    void beforeRun(KameletMain main, List<String> files);
+}

dsl/camel-jbang/camel-jbang-core/src/test/java/org/apache/camel/dsl/jbang/core/common/PluginRunCustomizerTest.java

@@ -0,0 +1,73 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.camel.dsl.jbang.core.common;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+
+import org.apache.camel.dsl.jbang.core.commands.CamelJBangMain;
+import org.apache.camel.main.KameletMain;
+import org.junit.jupiter.api.Test;
+import picocli.CommandLine;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+public class PluginRunCustomizerTest {
+
+    @Test
+    public void testPluginDefaultReturnsEmpty() {
+        Plugin plugin = (commandLine, main) -> {
+            // no-op
+        };
+
+        assertTrue(plugin.getRunCustomizer().isEmpty());
+    }
+
+    @Test
+    public void testPluginWithRunCustomizer() {
+        List<String> capturedFiles = new ArrayList<>();
+        boolean[] called = { false };
+
+        PluginRunCustomizer customizer = (main, files) -> {
+            called[0] = true;
+            capturedFiles.addAll(files);
+        };
+
+        Plugin plugin = new Plugin() {
+            @Override
+            public void customize(CommandLine commandLine, CamelJBangMain main) {
+                // no-op
+            }
+
+            @Override
+            public Optional<PluginRunCustomizer> getRunCustomizer() {
+                return Optional.of(customizer);
+            }
+        };
+
+        Optional<PluginRunCustomizer> result = plugin.getRunCustomizer();
+        assertTrue(result.isPresent());
+
+        // Simulate invoking the customizer
+        List<String> testFiles = List.of("route.yaml", "beans.xml");
+        result.get().beforeRun(new KameletMain("test"), testFiles);
+
+        assertTrue(called[0]);
+        assertEquals(testFiles, capturedFiles);
+    }
+}