Crate ashlar_command 

Everything is a command.

An app declares its commands once (CommandSpec) in a Registry. Menus, shortcuts, the command palette, the CLI, the control port and MCP all reach the app through one chokepoint, Registry::execute, and discover it through Dispatch::commands.

Contract (shared with ashlar-control, ashlar-mcp, ashlar-cli, ashlar-app): the items marked CONTRACT below are depended on by sibling crates being built in parallel. Change them only by adding (new fields behind #[serde(default)], new trait methods with defaults).

Re-exports

pub use keymap::Keymap;

pub use suggest::closest;

pub use suggest::did_you_mean_command;

pub use suggest::params_summary;

Modules

keymap

Which key runs which command: the commands’ default shortcuts plus the user’s overrides.

menu

The menu bar as plain, serializable data: one model for every renderer.

shortcut

Portable keyboard shortcuts.

suggest

“Did you mean …?”: the names closest to a mistyped one (a command id, a parameter key), and a one-line summary of a command’s parameters, so an error can say what to call instead.

Macros

cmd

A mutating command: cmd!(id, label, [menu…], shortcut, params, enabled, run).

query

A pure query (always enabled, not in menus, not journaled): query!(id, label, params, run).

Structs

Bound

A registry bound to one state: what control port, MCP and CLI drive through Dispatch.

CommandInfo

CONTRACT: what discovery returns for one command (palette, menus, MCP tools, CLI commands).

CommandRun

One top-level command that ran, as the chokepoint saw it: the registered id (a fixed program string, never its parameters), whether it succeeded and how long its body took.

CommandSpec

One command of host state S. Build it with cmd!/query! (the shape of existing command tables) or with CommandSpec::new and its const setters.

FuzzyMatch

A match: higher scores are better; positions are the matched char indices of the candidate (for highlighting), ascending.

Journal

The journal of a host: the mutating commands that succeeded, in order, with scrubbed params (replay, session logs, agent “what happened”). Also tracks the current nesting depth of crate::Registry::execute.

JournalEntry

One recorded command call.

Param

A typed parameter declared in a const/static command table: Param::int_in("width", 1, 16384).required().about("pixels").

ParamSpec

CONTRACT: one typed parameter.

Registry

The command table of one app. Immutable once built (a static is typical); the execution state lives in the host’s crate::Journal.

Enums

CommandError

CONTRACT: why a command failed. Hosts wrap their own errors in CommandError::Failed.

ExecError

Why a call through Registry::execute_host failed: the chokepoint refused or lost it (Command: unknown, too deeply nested, Host::before, validation, disabled, panicked), or the command body returned the host’s own error (Host, unchanged, as callers match on it).

Kind

The kind of a Param; the const counterpart of ParamKind.

ParamKind

CONTRACT: the kind of one typed parameter. Maps 1:1 onto JSON Schema.

Params

How a command documents its parameters: typed (preferred, gives JSON Schema and validation) or the legacy free-text description older command tables use (accepted, validated loosely).

Validation

Which declarations Registry::execute checks params against before Host::enabled_for (set with Registry::with_validation). Whatever the policy, Host::validate runs at the same step, and Registry::validate stays available for checking on demand.

Constants

MAX_DEPTH

Commands may run other commands up to this depth; deeper calls are refused (a command that calls itself, directly or through others, cannot overflow the stack).

Traits

Dispatch

CONTRACT: anything that can list and run commands. Implemented by Registry-backed sessions, by the control-port client (remote app) and by test doubles. Object-safe.

Host

The host state commands run on, and the hooks the chokepoint calls around every command.

Functions

accepted_params

Top-level keys accepted by a params doc; None when the doc isn’t a {…} key list (then nothing is refused).

always

The enabled predicate of a command that is always available.

fuzzy_match

Score candidate against query; None when the query’s characters do not all appear in order. An empty query matches everything with score 0.

fuzzy_rank

Match query against every candidate and return the matches, best first (ties keep the input order, so callers can pre-sort by recency or frequency).

params_schema

The JSON Schema ({"type":"object",…}) of a command’s parameters (MCP tool schemas, CLI help, inspector forms).

validate_params

Check value against a command’s declared params. Typed params: unknown keys, missing required keys, types, ranges and enum values are all checked. Legacy text params: only keys the text clearly does not mention are refused. common keys are accepted by every command; aliases ((documented, alias)) let a legacy command accept another spelling.

Type Aliases

Enabled

Enabled predicate: Err(reason) disables with a human-readable reason.

Run

Command body. Returns the host’s own error type (see Host::Error), so command tables written against an app’s Result alias port unchanged.

RunObserver

Told about every top-level command that ran (not about calls refused before running, and not about nested calls). Runs on the thread that executed the command, so it must be cheap.