Utilities

Logger, notifications, extensions, and other utilities

Extensions have access to a set of utility services and helper functions for logging, resource access, UI effects, and common Kotlin patterns.

Logger

Klyx provides a full logging system with log levels, contextual information, and structured output. Access it through the plugin’s logger or the global Logger.

private val logger: Logger by plugin()

Log levels

Method	Level
logger.trace(msg)	Verbose (lowest)
logger.debug(msg)	Debug
logger.info(msg)	Info
logger.warn(msg)	Warn
logger.error(msg)	Error (highest)

logger.d("Debug message")
logger.e("Error occurred", exception = e)

LogContext

All logging calls accept an optional LogContext that provides tagged and tagged-with-plugin metadata:

val context = LogContext

logger.d("Request started", context = context)
logger.w("Slow response", context = context)

LogContext is a marker interface. KlyxPlugin implements LogContext, so logging inside a plugin method automatically uses the plugin’s name as the tag and its ID as the source. Use NoLogContext for code not associated with a plugin.

Logger extensions

The Logger service is accessed through the plugin’s dependency injection. Use the plugin() delegate or rememberLogger() in composables:

private val logger: Logger by plugin()

Structured logging

logger.d("File saved", context = LogContext) {
    keyValue("path", file.name)
    keyValue("size", file.size)
    keyValue("duration_ms", elapsed)
}

LogEntry and LogLevel

data class LogEntry(
    val timestamp: Long,
    val level: LogLevel,
    val tag: String,
    val message: String,
    val throwable: Throwable? = null,
    val sourcePluginId: String? = null
)

enum class LogLevel {
    TRACE, DEBUG, INFO, WARN, ERROR
}

rememberLogger()

A composable that remembers the Logger from the current LocalApp:

val logger: Logger = rememberLogger()

Resources

Plugin access to Android resources is through PluginContext:

private val pluginContext: PluginContext by plugin()

// Access Android Resources
val resources: Resources = pluginContext.resources
val context: Context = pluginContext.context

Resource access with withResources

The withResources composable wraps content with the plugin’s LocalContext, making resource-backed Compose APIs resolve against the plugin’s own resources:

fun registerScreens() {
    registry.register(Screen(ScreenId("my.plugin.screen")) {
        withResources {
            Icon(
                painterResource(R.drawable.plugin_icon),
                contentDescription = stringResource(R.string.plugin_icon_desc)
            )
        }
    })
}

Context receiver extensions

Extensions provide convenience functions that use Kotlin context receivers. These are available when the plugin instance is in scope.

UI effects

// Show a toast
showToast("Operation completed")
showToast(R.string.action_done)

// Show a long toast
showToastLong("This takes a while...")

// Show a snackbar with action
showSnack(
    message = "File deleted",
    actionLabel = "Undo",
    onAction = { restoreFile() }
)

// Show a failure toast
showFailureToast("Something went wrong")
showFailureToast(throwable)

Lifecycle helpers

// Get the current lifecycle owner for the plugin
val owner: PluginLifecycleOwner = currentLifecycleOwner()

// Get the plugin's context
val context: PluginContext = currentPluginContext()

// Get the plugin's context, or null if not in a plugin scope
val context: PluginContext? = currentPluginContextOrNull()

Plugin context

// Get the plugin info
val info: PluginInfo = pluginInfo
info.id            // Plugin ID string
info.name          // Human-readable name
info.version       // Version string
info.descriptor    // Full PluginDescriptor

// Access plugin resources
val res: Resources = pluginContext.resources
val ctx: Context = pluginContext.context

Toast host state

val toastHostState: ToastHostState = toastHostState

Navigator

The Navigator service handles screen navigation:

private val navigator: Navigator by plugin()

Method	Description
navigateTo(destination)	Navigate to a NavDestination
navigateTo(screenId)	Navigate to a screen by ID (extension function)
navigateBack()	Go back one screen

NavDestination

sealed class NavDestination {
    data object Home : NavDestination()
    data object Settings : NavDestination()
    data object Terminal : NavDestination()
    data class Custom(val id: ScreenId) : NavDestination()
}

SpecialScreens

Pre-defined screen IDs:

Screen	ID
SpecialScreens.Home	<klyx-home>
SpecialScreens.Settings	<klyx-settings>
SpecialScreens.Terminal	<klyx-terminal>

Example

// Navigate to a built-in screen
navigator.navigateTo(NavDestination.Settings)

// Navigate to a custom screen
navigator.navigateTo(ScreenId("myext.main"))

// Go back
navigator.navigateBack()

Klyx extensions

Additional utility extensions available across the codebase:

Human-readable size

1_500_000L.humanBytes()   // "1.5 MB"
1024.humanBytes()         // "1.0 KB"
500.humanBytes()          // "500 B"

File utilities

val isText: Boolean = isTextFile(uri, contentResolver)
val file: File = File("/path/to/dir").createDirIfMissing()

Uri extensions

val uri: Uri = "content://com.example/file".toUri()
val filename: String? = uri.getFileTitle(contentResolver)
val fileSize: Long? = uri.getFileSize(contentResolver)
val shareable: Uri = uri.shareableUri
uri.share()   // Open Android share sheet

String encoding

val decoded: String = "hello%20world".decodeEscaped()
val encoded: String = "hello world".encodeEscaped()

Collections

val immutable: ImmutableList<String> = listOf("a", "b").toImmutableList()
val immutableMap: ImmutableMap<String, Int> = mapOf("a" to 1).toImmutableMap()

Error handling

// Get a user-friendly error message from a Throwable
val message: String = throwable.extractMessage()

// Execute a block, returning null on any non-cancellation exception
val result: String? = tryOrNull { riskyOperation() }

// Find an Activity context from a Context
val activity: Activity? = context.findActivity()

Slider steps

val steps: Int = (0f..100f).sliderSteps(increment = 5f)  // 20 steps

Terminal utilities

// Base environment variables for a terminal session
val env: Map<String, String> = terminalEnv()

// PRoot-specific environment variables
val processEnv: Map<String, String> = processEnv()

// Terminal launch arguments (PRoot-based)
val args: List<String> = terminalArgs(showMotd = true)

// Native PRoot library paths
val proot: File = prootFile()
val loader: File = prootLoaderFile()

Paths

Paths.filesDir           // Internal files directory
Paths.tempDir            // Cache directory
Paths.externalFilesDir   // External storage files directory
Paths.nativeLibraryDir   // Native libraries directory
Paths.dataDir            // Application data directory
Paths.externalCacheDir   // External cache directory (nullable)
Paths.noBackupFilesDir   // No-backup files directory
Paths.codeCacheDir       // Code cache directory
Paths.externalCacheDirs  // All external cache directories
Paths.externalFilesDirs  // All external files directories

// Klyx-specific path extensions
Paths.pluginsDir            // dataDir/klyx/plugins -- installed plugins directory
Paths.installedPluginsJson  // pluginsDir/installed.json -- list of installed plugin IDs
Paths.rootFs                // dataDir/rootfs -- terminal root filesystem
Paths.home                  // filesDir/home -- terminal home directory
Paths.projects              // home/projects -- user projects directory
Paths.versionFile           // rootFs/.bootstrap-version -- bootstrap version file

Example

The following demonstrates common utility patterns in a plugin:

override suspend fun onLoad() {
    // Logging with context
    logger.d("Plugin loaded")

    // Show a toast
    showToast("Plugin ready")

    // Navigate to settings
    navigator.navigateTo(NavDestination.Settings)

    // Format a file size
    val size = 1_500_000L.humanBytes()  // "1.5 MB"

    // Check if a file is text
    val isText = isTextFile(fileUri, contentResolver)
}