owlry/CLAUDE.md

CLAUDE.md

Guidance for Claude Code (claude.ai/code) when working in this repository.

The v2 rewrite is the load-bearing context here. Read docs/RESTRUCTURE-V2.md first if you're picking the project back up — it captures every design decision (D1–D21), the phased plan, and the per-task commit log.

Project shape

Owlry is a single-binary Wayland launcher. Workspace has exactly one member:

crates/owlry/                  -- everything
├── Cargo.toml                 -- one binary + one library, features per provider
├── src/
│   ├── main.rs                -- subcommand router
│   ├── cli.rs                 -- clap definitions
│   ├── lib.rs                 -- module re-exports for integration tests
│   ├── server.rs              -- IPC daemon (bind + accept loop)
│   ├── client.rs              -- IPC client (UI mode)
│   ├── backend.rs             -- SearchBackend abstraction
│   ├── app.rs                 -- GTK4 setup
│   ├── ui/                    -- GTK widgets
│   ├── config/                -- TOML + Lua config loader; defines LoadedConfig
│   ├── lua/                   -- Lua config layer (feature: lua)
│   │   ├── api.rs             -- owlry.set / providers / tabs / provider / theme / profiles
│   │   ├── config.rs          -- LuaConfig accumulator + merge_into(Config)
│   │   ├── error.rs           -- LuaConfigError (thiserror)
│   │   ├── migrate.rs         -- TOML → owlry.lua serializer (deterministic)
│   │   ├── provider.rs        -- LuaProvider impl Provider
│   │   ├── runtime.rs         -- LuaContext (Arc<Lua>) + eval_file/snapshot
│   │   ├── util.rs            -- owlry.util.{shell, read_file, glob, env, hostname, …}
│   │   ├── validate.rs        -- ValidationReport with categorised findings
│   │   └── watcher.rs         -- notify-based hot reload (desktop-notification errors)
│   ├── data/                  -- FrecencyStore
│   ├── filter.rs              -- ProviderFilter + prefix parser
│   ├── ipc.rs                 -- Request/Response types
│   ├── paths.rs               -- XDG paths (honours $OWLRY_SOCKET)
│   ├── commands.rs            -- subcommand dispatchers (doctor / providers / config / …)
│   └── providers/             -- ALL providers
│       ├── mod.rs             -- Provider/DynamicProvider traits, ProviderManager
│       ├── application.rs     (feature: app)
│       ├── command.rs         (feature: cmd)
│       ├── calculator.rs      (feature: calc)
│       ├── converter/         (feature: conv)
│       ├── power.rs           (feature: power — pre-v2 name: sys/system)
│       ├── dmenu.rs           (feature: dmenu)
│       ├── clipboard.rs       (feature: clipboard)
│       ├── emoji.rs           (feature: emoji)
│       ├── ssh.rs             (feature: ssh)
│       ├── systemd.rs         (feature: systemd — type_id "uuctl")
│       ├── websearch.rs       (feature: websearch)
│       └── filesearch.rs      (feature: filesearch)

There is no crates/owlry-core, owlry-plugin-api, owlry-lua, or owlry-rune. They were deleted in the v2 demolition. There is no ~/.config/owlry/plugins/ discovery directory and no /usr/lib/owlry/plugins/*.so loading — every "plugin" is a feature-gated module compiled into owlry.

Build & development

# Default features (minimal — app, cmd, calc, conv, power, dmenu, systemd)
cargo build

# Full features (matches AUR build) — includes lua + every optional provider
cargo build --release --features full

# Lua-only opt-in on top of the default minimal set
cargo build --features lua

# Tests
cargo test --features full           # 350+ tests including lua + watcher + migrate
cargo test --no-default-features

# Verbose dev logging
cargo run -- --features dev-logging -- -d

# Format + lint
cargo fmt --all
cargo clippy --features full
cargo clippy --no-default-features    # must also stay silent

# Install locally (sudo)
just install-local

The lua cargo feature pulls in mlua (vendored Lua 5.4), glob (for owlry.util.glob), and notify (for hot reload). It's part of the full set; minimal builds (cargo install without flags) compile without it and the migrate-config / Lua-load paths gracefully fall back to TOML.

The daemon binary is owlry. There is no separate owlryd binary anywhere — the daemon is owlry -d (or owlry daemon). The systemd user unit is owlry.service (pre-2.0 name: owlryd.service).

Running locally without disturbing prod

For side-by-side testing against a production daemon, set $OWLRY_SOCKET:

OWLRY_SOCKET=/tmp/owlry-dev.sock target/release/owlry -d &
OWLRY_SOCKET=/tmp/owlry-dev.sock target/release/owlry -m uuctl
pkill -f 'target/release/owlry -d'

$OWLRY_SOCKET overrides $XDG_RUNTIME_DIR/owlry/owlry.sock for both the daemon (bind path) and the UI client (connect path).

CLI shape

owlry                          UI, auto mode (default)
owlry -m <mode>                UI, single-provider mode
owlry --profile <name>         UI, named profile from config
owlry -p <prompt>              custom prompt text

owlry daemon                   run the daemon (alias: -d)
owlry dmenu [-p <prompt>]      dmenu mode (reads stdin, prints selection)
owlry doctor                   config + socket + providers status
owlry providers [<id>]         list providers (or show one)
owlry config validate          parse config, report errors (1) and warnings (2)
owlry config show              print resolved effective config
owlry migrate-config [--force] TOML → owlry.lua (functional from 2.1; --force to overwrite)

The owlry plugin ... subcommand tree from 1.x is gone in 2.0. Nothing to install, manage, or run via the CLI.

Lua config layer (2.1+)

~/.config/owlry/owlry.lua is the canonical config from 2.1 onwards. config.toml remains supported but is ignored entirely when owlry.lua exists (an info log at daemon start surfaces this). The daemon spawns a notify watcher on the config dir; saves are debounced (200ms), re-evaluated in a fresh LuaContext, and hot-swapped atomically. Eval failures are kept off the live state and surfaced via both the journal and a notify-rust desktop notification with the precise mlua line/column. See docs/lua-api.md for the full API surface (owlry.set, owlry.providers, owlry.tabs, owlry.provider, owlry.theme, owlry.profiles, owlry.util.*).

Implementation notes worth keeping straight:

• LuaContext::lua: Arc<Lua> — mlua::Function references don't bump the Lua refcount, so user providers hold their own Arc<Lua> clone via LuaContext::lua_handle() to outlive the context.
• LoadedConfig (in config/mod.rs) is the resolution result that keeps the LuaContext alive past Config::load. The daemon uses this; Config::load itself drops the context after merging scalars (so it can't be used to wire user providers — only LoadedConfig).
• owlry config validate runs lua::validate::validate against the snapshot and exits 0 / 1 / 2 per docs/lua-api.md §8.

Provider model

Two traits in src/providers/mod.rs:

• Provider — static providers (apps, commands, power, bookmarks, clipboard, emoji, ssh, systemd). Populate self.items in refresh(), return &self.items from items(). Optional: prefix(), icon(), tab_label(), search_noun(), position(), priority(), submenu_actions(data), execute_action(command).
• DynamicProvider — per-keystroke providers (calculator, converter, filesearch, websearch). Generate items in query(text). No refresh/items cache.

ProviderManager::new_with_config is the canonical registration site. Each provider is gated by both a cargo feature (compile-time) and a config flag in [providers] (runtime).

Submenu protocol

A provider returns items whose command field looks like SUBMENU:<type_id>:<data>. When the user selects one, the UI parses out (plugin_id, data), sends a Request::Submenu { plugin_id, data }, and the daemon routes that to Provider::submenu_actions(data) on the matching provider. The systemd provider uses this for service start/stop/restart/enable/disable/status/journal actions.

For now the protocol is string-encoded; a typed redesign is on the roadmap.

v2 naming rules

Old (pre-v2)	New (2.0+)	Notes
owlryd binary	owlry -d	Single binary
owlryd.service / owlryd.socket	owlry.service / owlry.socket	.install hook handles upgrade
:sys / :system / "System" provider	:power / "Power" provider	:sys and :system kept as aliases
providers.system = true (config)	providers.power = true	Old key still accepted via serde alias
badge_sys (theme color)	badge_power	Old key aliased; CSS var --owlry-badge-sys still emitted for transition
Plugin("sys") type_id	Plugin("power") type_id	CLI mode parsing maps all three to power

Frecency

~/.local/share/owlry/frecency.json. Auto-saved every 5 min by the daemon; flushed on SIGTERM/SIGINT/SIGHUP. Boost weight via providers.frecency_weight (0.0 disabled, 1.0 strong).

When you need to verify behavior live

1. cargo build --release --features full
2. OWLRY_SOCKET=/tmp/owlry-dev.sock target/release/owlry -d &
3. Run smoke queries via socket OR the UI with OWLRY_SOCKET set
4. pkill -f 'target/release/owlry -d'

Don't fight the prod daemon for the default socket path during testing. The env var exists for exactly this.