Add headless command-line support

.github/workflows/release.yml

@@ -32,14 +32,14 @@ jobs:
         uses: gradle/actions/setup-gradle@v3
 
       - name: Run Unit Tests
-        run: .\gradlew test
+        run: .\gradlew test :composeApp:jvmTest :plugin-api:jvmTest
 
       - name: Build Release Distribution
         run: .\gradlew packageDistributionForCurrentOS packageUberJarForCurrentOS packagePortableZip
         # run: .\gradlew packageReleaseDistributionForCurrentOS packageReleaseUberJarForCurrentOS packagePortableZip
 
-      - name: Publish Plugin API
-        run: .\gradlew :plugin-api:publish
+      - name: Publish Plugin API and Processor
+        run: .\gradlew :plugin-api:publish :plugin-processor:publish
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 

README.md

@@ -1,5 +1,23 @@
 This is a Kotlin Multiplatform project targeting Desktop (JVM).
 
+## Plugin-defined pages
+
+Plugins can organize capabilities into pages rendered by the host, without bundling Compose UI binaries:
+
+```kotlin
+@PluginUiPage(
+    id = "convert",
+    title = "Convert media",
+    description = "Choose an operation to begin.",
+    capabilityNames = ["Convert image", "Convert video"]
+)
+@PluginInfo(/* ... */)
+class MediaPlugin
+```
+
+Unknown capability names are ignored. The declarative contract stays usable across host UI upgrades and
+can also be interpreted by future web or command-line front ends.
+
 * [/composeApp](./composeApp/src) is for code that will be shared across your Compose Multiplatform applications.
   It contains several subfolders:
   - [commonMain](./composeApp/src/commonMain/kotlin) is for code that’s common for all targets.
@@ -22,6 +40,19 @@ in your IDE’s toolbar or run it directly from the terminal:
   .\gradlew.bat :composeApp:run
   ```
 
+### Command-line interface
+
+The desktop distribution can also run without opening a window:
+
+```shell
+plugintoolkit status
+plugintoolkit plugins list
+plugintoolkit flows list
+plugintoolkit --version
+```
+
+Use `plugintoolkit --help` for the complete command summary.
+
 ---
 
 ## Execution Engine & Concurrency (PluginToolkit)
@@ -33,4 +64,34 @@ The internal job execution engine (`FlowEngine` and `JobWorker`) enforces strict
 - **Recursion Depth Limits**: Deep subflow execution limits the stack frame depth to 50 iterations. Attempting to create an infinitely recursive subflow safely fails before hitting a JVM StackOverflow.
 - **Configurable Capabilities Policies**: Transient network execution failures in plugins automatically back off and retry up to `maxRetries` (configurable in app settings). Executions are also bound by a strict `pluginTimeoutMs` to prevent hung plugins.
 
-Learn more about [Kotlin Multiplatform](https://www.jetbrains.com/help/kotlin-multiplatform-dev/get-started.html)…
+Learn more about [Kotlin Multiplatform](https://www.jetbrains.com/help/kotlin-multiplatform-dev/get-started.html)…
+
+## Standalone plugin JARs
+
+JVM plugin modules can build a self-contained executable artifact by applying the bundled script:
+
+```kotlin
+apply(from = rootProject.file("scripts/standalone-plugin.gradle.kts"))
+```
+
+Run `./gradlew :yourPlugin:standaloneJar`, then inspect the plugin without the desktop host:
+
+```shell
+java -jar yourPlugin/build/libs/yourPlugin-version-standalone.jar --info
+```
+
+The generated JAR contains runtime dependencies, merges `META-INF/services` providers, and leaves KSP/compiler
+dependencies in the separate `plugin-processor` build-time artifact.
+
+External plugin builds need both artifacts at the same toolkit version:
+
+```kotlin
+dependencies {
+    implementation("org.wip.plugintoolkit:plugin-api:<toolkit-version>")
+    ksp("org.wip.plugintoolkit:plugin-processor:<toolkit-version>")
+}
+```
+
+> **2.0 migration:** replace any previous `ksp("org.wip.plugintoolkit:plugin-api:…")` dependency with
+> `plugin-processor`. The old coordinate no longer contains a KSP provider, so leaving it unchanged can produce
+> a successful build with no generated manifest or plugin entry point.

completeExample/build.gradle.kts

@@ -26,11 +26,13 @@ dependencies {
     implementation(libs.koin.core)
     implementation(libs.kotlinx.serialization.json)
     implementation(project(":plugin-api"))
-    ksp(project(":plugin-api"))
+    ksp(project(":plugin-processor"))
     testImplementation(libs.kotlin.test)
     testImplementation(libs.kotlinx.coroutines.test)
 }
 
 tasks.withType<ProcessResources> {
     duplicatesStrategy = DuplicatesStrategy.INCLUDE
 }
+
+apply(from = rootProject.file("scripts/standalone-plugin.gradle.kts"))

completeExample/src/main/kotlin/org/wip/complete/CompleteExamplePlugin.kt

@@ -23,6 +23,7 @@ import org.wip.plugintoolkit.api.annotations.CapabilityParam
 import org.wip.plugintoolkit.api.annotations.CapabilityResult
 import org.wip.plugintoolkit.api.annotations.PluginAction
 import org.wip.plugintoolkit.api.annotations.PluginInfo
+import org.wip.plugintoolkit.api.annotations.PluginUiPage
 import org.wip.plugintoolkit.api.annotations.PluginLoad
 import org.wip.plugintoolkit.api.annotations.PluginSetting
 import org.wip.plugintoolkit.api.annotations.PluginSetup
@@ -39,7 +40,9 @@ import java.io.File
 data class CompleteExampleSettings(
     @PluginSetting(
         description = "Public configuration value example",
-        defaultValue = "default_api_key"
+        defaultValue = "default_api_key",
+        minLength = 8,
+        semanticTypes = ["text/plain"]
     ) val apiKey: String? = "default_api_key",
 
     @PluginSetting(
@@ -117,6 +120,17 @@ enum class FeatureMode {
     description = "Complete showcase of plugin API features including settings, validation, signals, storage, file system, lifecycle hooks, and flow contexts.",
     supportedOs = [OS.WINDOWS, OS.LINUX, OS.MACOS]
 )
+@PluginUiPage(
+    id = "essentials",
+    title = "Essential capabilities",
+    description = "Common storage and file operations.",
+    capabilityNames = ["capabilityWithFileAccess", "capabilityWithDataStorage"]
+)
+@PluginUiPage(
+    id = "advanced",
+    title = "Advanced capabilities",
+    capabilityNames = ["capabilityWithPauseResume", "capabilityWithComplexObjectsAndSemanticTypes"]
+)
 class CompleteExamplePlugin(val settings: CompleteExampleSettings) {
 
     @PluginLoad

composeApp/src/commonMain/composeResources/values-it/strings.xml

@@ -1,5 +1,7 @@
 <?xml version='1.0' encoding='utf-8'?>
 <resources>
+    <string name="plugin_settings_required">Obbligatorie</string>
+    <string name="plugin_settings_optional">Facoltative</string>
     <string name="app_name">PluginToolkit</string>
     <string name="section_runner">Runner</string>
     <string name="nav_main">Dashboard</string>

composeApp/src/commonMain/composeResources/values/strings.xml

@@ -191,6 +191,8 @@
     <string name="plugin_settings_actions">Actions</string>
     <string name="plugin_settings_custom">Custom Settings</string>
     <string name="plugin_settings_global_defaults">Global Parameter Defaults</string>
+    <string name="plugin_settings_required">Required</string>
+    <string name="plugin_settings_optional">Optional</string>
     <string name="plugin_settings_capability">Capability: %1$s</string>
     <string name="settings_enum_unlock_message">Configure required settings to unlock options</string>
     <string name="settings_locked_capability">Locked capability: %1$s</string>
@@ -474,4 +476,4 @@
     <string name="repo_filter_label">Filter:</string>
     <string name="repo_sort_label">Sort:</string>
     <string name="repo_sync_all">Sync All</string>
-</resources>
+</resources>

composeApp/src/commonMain/kotlin/org/wip/plugintoolkit/features/flows/logic/FlowRepository.kt

@@ -46,92 +46,99 @@ class FlowRepository(
     }
 
     private fun getFlowPath(appDataDir: String, flowName: String): Path {
-        val safeName = flowName.replace(Regex("[\\\\/:*?\"<>|]"), "_")
-        return Path("$appDataDir/flows/$safeName.json")
+        return storedFlowPath(appDataDir, flowName)
     }
 
     fun reloadFlows() {
         scope.launch(Dispatchers.IO) {
             try {
-                val appDataDir = settingsPersistence.getSettingsDir()
-                val flowsDir = Path("$appDataDir/flows")
-
-                if (!SystemFileSystem.exists(flowsDir)) {
-                    SystemFileSystem.createDirectories(flowsDir)
-                }
-
-                // Check for legacy migration first
-                val legacyFile = Path("$appDataDir/${appConfig.FLOWS_FILE_NAME}")
-                if (SystemFileSystem.exists(legacyFile)) {
-                    try {
-                        val legacyContent = SystemFileSystem.source(legacyFile).buffered().use { it.readString() }
-                        if (legacyContent.isNotBlank()) {
-                            val loadedFlows = json.decodeFromString<List<Flow>>(legacyContent)
-                            loadedFlows.forEach { flow ->
-                                val targetFile = getFlowPath(appDataDir, flow.name)
-                                if (!SystemFileSystem.exists(targetFile)) {
-                                    val flowContent = json.encodeToString(Flow.serializer(), flow)
-                                    SystemFileSystem.sink(targetFile).buffered().use { it.writeString(flowContent) }
-                                }
-                            }
-                        }
-                        val backupFile = Path("$appDataDir/${appConfig.FLOWS_FILE_NAME}.bak")
-                        if (SystemFileSystem.exists(backupFile)) {
-                            SystemFileSystem.delete(backupFile)
-                        }
-                        SystemFileSystem.source(legacyFile).buffered().use { source ->
-                            SystemFileSystem.sink(backupFile).buffered().use { sink ->
-                                val data = source.readString()
-                                sink.writeString(data)
+                val storedFlows = loadStoredFlows(settingsPersistence, appConfig)
+                val manifests = pluginManager.installedPlugins.value.filter { it.isEnabled }
+                    .associate { it.pkg to pluginManager.getManifest(it.pkg) }
+                    .filterValues { it != null }.mapValues { it.value!! }
+                _flows.value = storedFlows.map { flow ->
+                    val updatedNodes = flow.nodes.map { node ->
+                        if (node is Node.CapabilityNode) {
+                            val currentManifest = manifests[node.pluginInfo.id]
+                            val actualCapability = currentManifest?.capabilities?.find { it.name == node.capability.name }
+                            if (currentManifest == null || actualCapability == null) {
+                                node.copy(isBroken = true)
+                            } else {
+                                node.copy(
+                                    isBroken = false,
+                                    capability = actualCapability,
+                                    pluginInfo = currentManifest.plugin
+                                )
                             }
+                        } else {
+                            node
                         }
-                        SystemFileSystem.delete(legacyFile)
-                        Logger.i { "Legacy flows.json successfully migrated and backed up" }
-                    } catch (e: Exception) {
-                        Logger.e(e) { "Migration failed" }
                     }
+                    flow.copy(nodes = updatedNodes)
                 }
+            } catch (e: Exception) {
+                Logger.e(e) { "Failed to reload flows" }
+            }
+        }
+    }
 
-                val loadedFlows = mutableListOf<Flow>()
-                val manifests = pluginManager.installedPlugins.value.filter { it.isEnabled }
-                    .associate { it.pkg to pluginManager.getManifest(it.pkg) }
-                    .filterValues { it != null }.mapValues { it.value!! }
+    companion object {
+        private val storageJson = Json {
+            prettyPrint = true
+            ignoreUnknownKeys = true
+            encodeDefaults = true
+        }
+
+        private fun storedFlowPath(appDataDir: String, flowName: String): Path {
+            val safeName = flowName.replace(Regex("[\\\\/:*?\"<>|]"), "_")
+            return Path("$appDataDir/flows/$safeName.json")
+        }
 
-                SystemFileSystem.list(flowsDir).forEach { file ->
-                    if (file.name.endsWith(".json")) {
-                        try {
-                            val content = SystemFileSystem.source(file).buffered().use { it.readString() }
-                            val flow = json.decodeFromString<Flow>(content)
-
-                            val updatedNodes = flow.nodes.map { node ->
-                                if (node is Node.CapabilityNode) {
-                                    val currentManifest = manifests[node.pluginInfo.id]
-                                    val actualCapability =
-                                        currentManifest?.capabilities?.find { it.name == node.capability.name }
-                                    if (currentManifest == null || actualCapability == null) {
-                                        node.copy(isBroken = true)
-                                    } else {
-                                        node.copy(
-                                            isBroken = false,
-                                            capability = actualCapability,
-                                            pluginInfo = currentManifest.plugin
-                                        )
-                                    }
-                                } else {
-                                    node
+        suspend fun loadStoredFlows(
+            settingsPersistence: SettingsPersistence,
+            appConfig: SystemConfig
+        ): List<Flow> = kotlinx.coroutines.withContext(Dispatchers.IO) {
+            val appDataDir = settingsPersistence.getSettingsDir()
+            val flowsDir = Path("$appDataDir/flows")
+            if (!SystemFileSystem.exists(flowsDir)) SystemFileSystem.createDirectories(flowsDir)
+
+            val legacyFile = Path("$appDataDir/${appConfig.FLOWS_FILE_NAME}")
+            if (SystemFileSystem.exists(legacyFile)) {
+                try {
+                    val legacyContent = SystemFileSystem.source(legacyFile).buffered().use { it.readString() }
+                    if (legacyContent.isNotBlank()) {
+                        storageJson.decodeFromString<List<Flow>>(legacyContent).forEach { flow ->
+                            val targetFile = storedFlowPath(appDataDir, flow.name)
+                            if (!SystemFileSystem.exists(targetFile)) {
+                                SystemFileSystem.sink(targetFile).buffered().use {
+                                    it.writeString(storageJson.encodeToString(Flow.serializer(), flow))
                                 }
                             }
-                            loadedFlows.add(flow.copy(nodes = updatedNodes))
-                        } catch (e: Exception) {
-                            Logger.e(e) { "Failed to parse flow file: ${file.name}" }
                         }
                     }
+                    val backupFile = Path("$appDataDir/${appConfig.FLOWS_FILE_NAME}.bak")
+                    if (SystemFileSystem.exists(backupFile)) SystemFileSystem.delete(backupFile)
+                    SystemFileSystem.source(legacyFile).buffered().use { source ->
+                        SystemFileSystem.sink(backupFile).buffered().use { sink -> sink.writeString(source.readString()) }
+                    }
+                    SystemFileSystem.delete(legacyFile)
+                    Logger.i { "Legacy flows.json successfully migrated and backed up" }
+                } catch (error: Exception) {
+                    Logger.e(error) { "Migration failed" }
                 }
-
-                _flows.value = loadedFlows
-            } catch (e: Exception) {
-                Logger.e(e) { "Failed to reload flows" }
             }
+
+            SystemFileSystem.list(flowsDir)
+                .filter { it.name.endsWith(".json") }
+                .mapNotNull { file ->
+                    try {
+                        val content = SystemFileSystem.source(file).buffered().use { it.readString() }
+                        storageJson.decodeFromString<Flow>(content)
+                    } catch (error: Exception) {
+                        Logger.e(error) { "Failed to parse flow file: ${file.name}" }
+                        null
+                    }
+                }
         }
     }
 

composeApp/src/commonMain/kotlin/org/wip/plugintoolkit/features/flows/logic/PathPatternResolver.kt

@@ -1,7 +1,5 @@
 package org.wip.plugintoolkit.features.flows.logic
 
-import kotlinx.io.files.Path
-
 /**
  * Utility class to evaluate and resolve autogenerated path patterns for node outputs.
  * 
@@ -79,30 +77,28 @@ object PathPatternResolver {
         // If it's empty, we can't extract modifiers like name or ext effectively
         if (pathString.isBlank()) return ""
 
-        val path = Path(pathString)
-        val isWindows = pathString.contains(":\\") || pathString.contains(":/")
+        // kotlinx.io Path follows the host OS. Parse separators as data so a Windows path can be
+        // resolved correctly by Linux/macOS CI (and vice versa).
+        val lastSeparator = maxOf(pathString.lastIndexOf('/'), pathString.lastIndexOf('\\'))
+        val name = pathString.substring(lastSeparator + 1)
 
         return when (modifier) {
             "dir" -> {
-                val parent = path.parent?.toString() ?: ""
-                val separator = if (pathString.contains("\\")) "\\" else "/"
-                val normalizedParent = parent.replace("\\", separator).replace("/", separator)
-                // Edge case handling for windows roots
-                if (isWindows && parent.isEmpty()) {
-                    pathString.substringBefore("\\").substringBefore("/") + "\\"
-                } else {
-                    normalizedParent
+                when {
+                    lastSeparator < 0 -> ""
+                    lastSeparator == 0 -> pathString.substring(0, 1)
+                    lastSeparator == 2 && pathString.getOrNull(1) == ':' ->
+                        pathString.substring(0, lastSeparator + 1)
+                    else -> pathString.substring(0, lastSeparator)
                 }
             }
 
-            "name" -> path.name
+            "name" -> name
             "nameWithoutExtension" -> {
-                val name = path.name
                 if (name.contains(".")) name.substringBeforeLast(".") else name
             }
 
             "ext" -> {
-                val name = path.name
                 if (name.contains(".")) name.substringAfterLast(".") else ""
             }