Gabriel Kaszewski
051d19d878
clean architecture refactor, performance, resilience, DX/UX architecture: - 13 crates with proper domain/application/infrastructure layers - domain crate: newtypes, ports (Plugin, AppLauncher), constants - kernel: pure orchestrator - shared UI state machine (k-launcher-ui-core) - merged plugin-api into domain as ports module - granular file structure (no monolithic lib.rs) - all tests extracted to tests/ directories features: - frecency boost in search results - empty query shows top frecent apps - append-only frecency log with configurable compaction - config-driven styling (all colors, sizes, debounce) - configurable terminal emulator, external plugin timeout - log rotation with max_log_files - loading indicator, descriptive placeholder text - graceful shutdown via iced::exit() + Plugin::shutdown() - --version flag, panic hook, signal handling (SIGINT/SIGTERM) - SpawnInTerminal in external plugin protocol performance: - ~1500 -> ~50 heap allocs per keystroke - reused Matcher, Pattern, char buffer across entries - Arc<str> for shared result fields - pre-filter before fuzzy matching - partial sort for top frecent IDs - cached lowercase names in entries resilience: - parking_lot (no mutex poisoning) - thiserror hierarchy (PluginError, ConfigError, AppError) - all silent error swallowing replaced with tracing::warn - config parse errors logged quality: - named constants (no magic strings/numbers) - named types (no anonymous tuples) - Rgba newtype with validation - domain newtype validation (debug_assert non-empty) - man page, LICENSE (MIT), PKGBUILD, example config - plugin development guide updated - make check (fmt + clippy + test), make dev (RUST_LOG=debug) style: format code for better readability in tests and function signatures fix: update build_entries function signature to ignore frecency parameter fix(review): bugs, arch violations, design smells P1 bugs: - unix_launcher: shell_split respects quoted args (was split_whitespace) - plugin-host: 5s timeout on external plugin search - ui: handle engine init panic, wire error state - ui-egui: read window config instead of always using defaults - plugin-url: use OpenPath action instead of SpawnProcess+xdg-open Architecture: - remove WindowConfig (mirror of WindowCfg); use WindowCfg directly - remove on_select closure from SearchResult (domain leakage) - remove LaunchAction::Custom; add Plugin::on_selected + SearchEngine::on_selected - apps: record frecency via on_selected instead of embedded closure Design smells: - frecency: extract decay_factor helper, write outside mutex - apps: remove cfg(test) cache_path hack; add new_for_test ctor - apps: stable ResultId using name+exec to prevent collision - files: stable ResultId using full path instead of index - plugin-host: remove k-launcher-os-bridge dep (WindowConfig gone) Update iced dependency in Cargo.toml to disable default features and add additional ones feat(app): enhance engine initialization with EngineHandle and update run function signature feat: production hardening (panic isolation, file logging, apps cache) - Kernel::search wraps each plugin in catch_unwind; panics are logged and return [] - init_logging() adds daily rolling file at ~/.local/share/k-launcher/logs/ - AppsPlugin caches entries to ~/.cache/k-launcher/apps.bin via bincode; stale-while-revalidate on subsequent launches - 57 tests pass refactor: remove client module and associated show command logic fix(app): format code for clarity in update function chore: update .gitignore and enhance README with compositor setup instructions chore(docs): remove unused screenshot file feature/prod-ready (#1) Reviewed-on: #1 fix(calc): remove ambiguous log alias, use ln/log2/log10 explicitly fix(calc): fix log/ln naming, cache math context, strengthen sin(pi) test feat(calc): add math functions (sqrt, sin, cos, etc.) and pi/e constants refactor(calc): rename preprocess, extend underscore test assertions feat(calc): strip underscore digit separators feat: update dependencies for improved compatibility and performance feat: add plugin-url for URL handling and open in browser functionality feat: add support for external plugins and enhance plugin management feat: add Makefile for build, run, and installation commands feat: add required features for k-launcher-egui and update dependencies feat: update README and add documentation for installation, configuration, usage, and plugin development feat: enhance configuration management and UI styling, remove unused theme module feat: add k-launcher-config crate for configuration management and integrate with existing components feat: add k-launcher-ui-egui crate for enhanced UI - Introduced a new crate `k-launcher-ui-egui` to provide a graphical user interface using eframe and egui. - Updated the workspace configuration in `Cargo.toml` to include the new crate. - Implemented the main application logic in `src/app.rs`, handling search functionality and user interactions. - Created a library entry point in `src/lib.rs` to expose the `run` function for launching the UI. - Modified the `k-launcher` crate to include a new binary target for the egui-based launcher. - Added a new main file `src/main_egui.rs` to initialize and run the egui UI with the existing kernel and launcher components. feat: implement OS bridge and enhance app launcher functionality feat: add FilesPlugin for file searching and integrate into KLauncher feat: implement frecency tracking for app usage and enhance search functionality feat: add CmdPlugin for executing terminal commands and update workspace configuration refactor: update dependencies and improve keyboard event handling in KLauncherApp refactor: simplify theme usage and enhance AppsPlugin structure feat: restructure k-launcher workspace and add core functionality - Updated Cargo.toml to include a new k-launcher crate and reorganized workspace members. - Introduced a README.md file detailing the project philosophy, architecture, and technical specifications. - Implemented a new Kernel struct in k-launcher-kernel for managing plugins and search functionality. - Created a Plugin trait for plugins to implement, allowing for asynchronous search operations. - Developed k-launcher-ui with an Iced-based UI for user interaction, including search input and result display. - Added AppsPlugin and CalcPlugin to handle application launching and basic calculations, respectively. - Established a theme module for UI styling, focusing on an Aero aesthetic. - Removed unnecessary main.rs files from plugin crates, streamlining the project structure. Initialize k-launcher project structure with multiple crates and basic configurations
169 lines
4.4 KiB
Groff
169 lines
4.4 KiB
Groff
.TH K\-LAUNCHER 1 "2026-07-24" "k-launcher 0.2.0" "User Commands"
|
|
.SH NAME
|
|
k\-launcher \- Wayland command palette launcher
|
|
.SH SYNOPSIS
|
|
.B k\-launcher
|
|
.RB [ \-\-version ]
|
|
.SH DESCRIPTION
|
|
.B k\-launcher
|
|
is a keyboard-driven application launcher for Wayland desktops. It provides
|
|
fuzzy search over installed applications, a calculator, a file browser, and
|
|
a shell command runner, all accessible from a single search bar.
|
|
.PP
|
|
Results are ranked by a combination of fuzzy match score and frecency (how
|
|
frequently and recently an application was launched). On an empty query, the
|
|
most frecent applications are displayed.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BR \-\-version ", " \-V
|
|
Print version information and exit.
|
|
.SH USAGE
|
|
.TP
|
|
.B Type text
|
|
Fuzzy-search installed applications by name or keywords.
|
|
.TP
|
|
.B > command
|
|
Run a shell command in a terminal emulator.
|
|
.TP
|
|
.B = expression
|
|
Evaluate a math expression. Supports +, \-, *, /, parentheses, and functions
|
|
such as sqrt, sin, cos, tan, ln, log2, log10, abs, ceil, floor, round.
|
|
Constants: pi, e. Result is copied to clipboard on Enter.
|
|
.TP
|
|
.B ~/path \fRor\fB /path
|
|
Browse the filesystem. Tab-like prefix matching on directory entries.
|
|
.SH KEYBOARD
|
|
.TP
|
|
.B Enter
|
|
Launch the selected result (or copy to clipboard for calculator results).
|
|
.TP
|
|
.B Escape
|
|
Close the launcher.
|
|
.TP
|
|
.B Arrow Up / Arrow Down
|
|
Navigate through results.
|
|
.SH CONFIGURATION
|
|
Configuration is stored in
|
|
.IR ~/.config/k\-launcher/config.toml .
|
|
If the file is absent, sensible defaults are used. A parse error is logged
|
|
as a warning and defaults are used.
|
|
.PP
|
|
See
|
|
.I config.example.toml
|
|
in the source repository for all available options.
|
|
.SS [window]
|
|
.TP
|
|
.BR width " (float, default: 600.0)"
|
|
Window width in pixels.
|
|
.TP
|
|
.BR height " (float, default: 400.0)"
|
|
Window height in pixels.
|
|
.TP
|
|
.BR decorations " (bool, default: false)"
|
|
Show window decorations.
|
|
.TP
|
|
.BR transparent " (bool, default: true)"
|
|
Enable window transparency.
|
|
.SS [appearance]
|
|
.TP
|
|
.BR background_rgba " (array, default: [20, 20, 30, 0.9])"
|
|
Background color as [R, G, B, A] where RGB are 0\-255 and A is 0.0\-1.0.
|
|
.TP
|
|
.BR border_rgba " (array, default: [229, 125, 33, 1.0])"
|
|
Border color.
|
|
.TP
|
|
.BR placeholder " (string)"
|
|
Search bar placeholder text.
|
|
.TP
|
|
.BR icon_size " (float, default: 24.0)"
|
|
Application icon size in pixels.
|
|
.SS [search]
|
|
.TP
|
|
.BR max_results " (integer, default: 8)"
|
|
Maximum number of results to display.
|
|
.TP
|
|
.BR debounce_ms " (integer, default: 50)"
|
|
Milliseconds to wait after last keystroke before searching.
|
|
.TP
|
|
.BR frecency_compact_threshold " (integer, default: 50)"
|
|
Number of frecency log entries before compacting to a snapshot.
|
|
.SS [plugins]
|
|
.TP
|
|
.BR calc " (bool, default: true)"
|
|
Enable the calculator plugin.
|
|
.TP
|
|
.BR cmd " (bool, default: true)"
|
|
Enable the shell command plugin.
|
|
.TP
|
|
.BR files " (bool, default: true)"
|
|
Enable the file browser plugin.
|
|
.TP
|
|
.BR apps " (bool, default: true)"
|
|
Enable the application search plugin.
|
|
.SS [[plugins.external]]
|
|
External plugins are executables that communicate via JSON over stdin/stdout.
|
|
.TP
|
|
.BR name " (string, required)"
|
|
Display name for the plugin.
|
|
.TP
|
|
.BR path " (string, required)"
|
|
Path to the plugin executable.
|
|
.TP
|
|
.BR args " (array of strings, default: [])"
|
|
Arguments to pass to the plugin.
|
|
.TP
|
|
.BR timeout_secs " (integer, default: 5)"
|
|
Search timeout in seconds per query.
|
|
.SS [logging]
|
|
.TP
|
|
.BR max_log_files " (integer, default: 7)"
|
|
Number of daily log files to keep.
|
|
.SS [terminal]
|
|
.TP
|
|
.BR cmd " (string, optional)"
|
|
Terminal emulator command for
|
|
.B > command
|
|
execution. If unset, detected from
|
|
.BR $TERM_CMD ,
|
|
.BR $TERMINAL ,
|
|
or PATH (foot, kitty, alacritty, wezterm, konsole, xterm).
|
|
.SH FILES
|
|
.TP
|
|
.I ~/.config/k\-launcher/config.toml
|
|
User configuration file.
|
|
.TP
|
|
.I ~/.local/share/k\-launcher/frecency.json
|
|
Frecency snapshot (launch history).
|
|
.TP
|
|
.I ~/.local/share/k\-launcher/frecency.log
|
|
Frecency append-only log (compacted periodically).
|
|
.TP
|
|
.I ~/.local/share/k\-launcher/logs/
|
|
Daily log files.
|
|
.TP
|
|
.I ~/.cache/k\-launcher/apps.bin
|
|
Cached desktop entry data (bincode).
|
|
.SH PLUGINS
|
|
See
|
|
.I docs/plugin\-development.md
|
|
in the source repository for the external plugin protocol and a guide to
|
|
writing built-in plugins.
|
|
.SH SIGNALS
|
|
.TP
|
|
.BR SIGINT ", " SIGTERM
|
|
Graceful shutdown. Frecency data is compacted before exit.
|
|
.SH EXIT STATUS
|
|
.TP
|
|
.B 0
|
|
Normal exit.
|
|
.TP
|
|
.B 1
|
|
Fatal error (UI initialization failure).
|
|
.SH AUTHORS
|
|
Written by Gabriel Kaszewski.
|
|
.SH LICENSE
|
|
MIT License. See LICENSE in the source repository.
|
|
.SH SEE ALSO
|
|
.BR wl\-copy (1),
|
|
.BR xdg\-open (1)
|