Crate execra 

Execra

Execra is a typed job runtime for external processes. You hand it a Command, it gives you back a JobHandle that you can either .await for the final Outcome or subscribe to as an event stream. Each job gets phases, progress, findings, and process-group cancellation, behind a single Runtime::spawn entry point.

Interpretation of a CLI’s output into structured events is decoupled from the runtime via the Interpreter trait; see the INTERPRETER.md file in the repository for the contract.

Quick example

use execra::{Command, Outcome, Runtime};

let rt = Runtime::new();
let outcome = rt
    .spawn(Command::new("echo").arg("hello").label("greet"))?
    .await;
assert!(matches!(outcome, Outcome::Succeeded { .. }));

Pure in-memory by default: no SQLite, no log files. Opt in to persistence with the builder:

use execra::Runtime;
let rt = Runtime::builder()
    .history("./jobs.sqlite")
    .max_concurrent(4)
    .build()?;

Feature flags

• bundled-sqlite (default) — Bundle SQLite with rusqlite. Disable to link against the system libsqlite3 instead.
• gzip (default) — Enable RawOutputPolicy::PersistGzipOnFinalize and pull in flate2. Without this feature raw logs can still be persisted uncompressed via RawOutputPolicy::Persist.
• tauri — Enable execra::tauri, the built-in Tauri plugin and AppHandle::execra() extension trait.
• interpret — Enable execra::interpret, a table-driven Interpreter toolkit (the rules! macro, RuleInterpreter, phase/notes/fallback helpers). Pulls in regex.

See RUNTIME.md and INTERPRETER.md in the repository for the design contract.

Re-exports

pub use command::Command;

pub use command::StdinMode;

pub use event::Event;

pub use event::Stream;

pub use finding::Action;

pub use finding::Finding;

pub use finding::RelatedEntity;

pub use finding::Severity;

pub use interpreter::Context;

pub use interpreter::Interpreter;

pub use interpreter::InterpreterEvent;

pub use interpreter::Line;

pub use job::Job;

pub use job::JobId;

pub use job::JobState;

pub use outcome::ExitCode;

pub use outcome::FailureReason;

pub use outcome::Outcome;

pub use phase::Phase;

pub use phase::PhaseId;

pub use progress::Progress;

pub use progress::ProgressMetric;

pub use runtime::JobHandle;

pub use runtime::JobsQuery;

pub use runtime::RawOutputPolicy;

pub use runtime::RetentionPolicy;

pub use runtime::Runtime;

pub use runtime::RuntimeBuilder;

Modules

command

event

finding

interpret

Optional toolkit for table-driven interpreters. Feature: interpret.

interpreter

The Interpreter contract. See INTERPRETER.md.

job

outcome

phase

progress

Progress values are emitted by interpreters and surfaced through Event.

runtime

Runtime surface and per-job driver.

store

SQLite persistence. Stores jobs (one row), events (JSON blob per row), and findings (denormalized for queryability). Raw OutputAppended events are intentionally not persisted to SQLite , they belong in flat files (next pass). High-volume CLIs would balloon the database otherwise.

tauri

Tauri integration. Gate-feature: tauri.

Macros

rules

Build a Vec<Rule> declaratively. Rules are separated by ;; message/label/hint arguments are &str and may interpolate captures with $1, $2, … Order matters: first match wins, so put benign/specific rules ahead of generic catch-alls.