Lutra/crates/engine/src/command.rs
danny 184b8a3468 M1.8: command palette, global keymap, UI commands
- Engine: ui.registerCommands (validated, replaces the previous set),
  UI commands in listCommands with ui: true and labelKey, running one
  through the engine emits uiCommand {id, params}.
- Frontend: ui/src/commands/ (keymap by key code, fuzzy ranking, Pinia
  commands store with handlers, recents and error toasts), the command
  palette (Mod+Shift+P), UI commands palette.open, settings.open (Mod+,,
  disabled until M1.9b) and view.toggleProjectTree (Mod+1). The editor's
  shortcuts.ts moved into the global keymap.
- Tests: engine and control-channel tests for registration and
  uiCommand, Vitest for keymap, ranking, store, palette and App wiring.
- Docs: architecture, ui-parity, target-app-parity, gaps, roadmap,
  ROADMAP, README.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 16:59:43 +02:00

128 lines
4.2 KiB
Rust

//! The command abstraction: static metadata, the run contract and the
//! effects a command asks its host to carry out.
use serde::Serialize;
use serde_json::Value;
use crate::{EngineError, Event, State};
/// Static metadata of a command.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CommandSpec {
/// Unique id, `area.action` in camelCase, e.g. `app.about`.
pub id: &'static str,
/// Label for menus and the command palette, in English.
pub label: &'static str,
/// Menu path with `/` separators, e.g. `Help/About Lutra`.
pub menu_path: Option<&'static str>,
/// Default shortcut in Lutra notation; `Mod` is Ctrl, or Cmd on macOS.
pub default_shortcut: Option<&'static str>,
/// Documentation of the params object, `none` if the command takes none.
pub params: &'static str,
}
/// Something the engine asks its host to do after a command returns,
/// because it needs a layer the engine cannot reach (windows, the process).
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(tag = "kind", rename_all = "camelCase")]
pub enum Effect {
/// Quit the application.
Quit,
/// Show the native folder picker and run `project.open` with the chosen
/// folder. Cancelling the picker does nothing and is not an error.
PickFolder,
}
/// Result of a successful command.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct Outcome {
/// JSON result returned to the caller.
pub value: Value,
/// Effects for the host to apply, in order.
pub effects: Vec<Effect>,
/// State changes for the host to publish, oldest first. Filled by the
/// engine from the events the command queued; commands leave it empty.
pub events: Vec<Event>,
}
impl Outcome {
/// An outcome with a value and no effects.
pub fn value(value: Value) -> Self {
Self {
value,
effects: Vec::new(),
events: Vec::new(),
}
}
/// An outcome with a null value and one effect.
pub fn effect(effect: Effect) -> Self {
Self {
value: Value::Null,
effects: vec![effect],
events: Vec::new(),
}
}
}
/// A user-visible action.
///
/// Implementations are stateless; everything they change lives in [`State`].
pub trait Command: Send + Sync {
/// Static metadata.
fn spec(&self) -> &CommandSpec;
/// Whether the command can run in the given state. Defaults to always.
fn enabled(&self, _state: &State) -> bool {
true
}
/// Runs the command.
///
/// # Errors
/// Returns [`EngineError::InvalidParams`] for params that don't match
/// [`CommandSpec::params`], and [`EngineError::Failed`] when the action
/// itself fails.
fn run(&self, state: &mut State, params: Value) -> Result<Outcome, EngineError>;
}
/// Description of a command for menus, the palette, keymaps and agents.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct CommandInfo {
/// Command id.
pub id: String,
/// Label.
pub label: String,
/// Menu path, if the command is in a menu.
pub menu_path: Option<String>,
/// Default shortcut, if any.
pub default_shortcut: Option<String>,
/// Params documentation.
pub params: String,
/// Whether the command can run in the current state.
pub enabled: bool,
/// Message-catalog key of the label; set for UI commands, whose `label`
/// is the same key because the engine has no English text for them.
#[serde(skip_serializing_if = "Option::is_none")]
pub label_key: Option<String>,
/// Whether the frontend registered the command (`ui.registerCommands`)
/// and runs it; running it through the engine emits `uiCommand`.
pub ui: bool,
}
impl CommandInfo {
/// Builds the description from a spec and the current enabled state.
pub fn new(spec: &CommandSpec, enabled: bool) -> Self {
Self {
id: spec.id.to_string(),
label: spec.label.to_string(),
menu_path: spec.menu_path.map(str::to_string),
default_shortcut: spec.default_shortcut.map(str::to_string),
params: spec.params.to_string(),
enabled,
label_key: None,
ui: false,
}
}
}