Struct Envelope 

pub struct Envelope {
    pub data: Option<Value>,
    pub pagination: Option<PaginationMeta>,
    pub metadata: Option<Metadata>,
    pub error: Option<ErrorEnvelope>,
    pub warnings: Vec<String>,
    pub next_actions: Vec<NextAction>,
    pub fix: Option<String>,
    /* private fields */
}

Top-level output envelope rendered for successful and failed commands.

Fields

data: Option<Value>

Successful command data.

pagination: Option<PaginationMeta>

Client-side pagination facts, present whenever pagination was actually applied — an effective --limit or --offset greater than zero, not merely a command that opted into with_pagination — regardless of --verbose. A default_limit of 0 (“unlimited”) with neither flag passed leaves this None even for a paginating command. Unlike metadata, this is not debugging output; a caller relies on it to know whether more data exists at all.

metadata: Option<Metadata>

Optional execution metadata, controlled by --verbose.

error: Option<ErrorEnvelope>

Structured error information for failed commands.

warnings: Vec<String>

Non-fatal warnings.

next_actions: Vec<NextAction>

Suggested follow-up actions for the caller (agent or human).

fix: Option<String>

Optional recovery guidance for failed commands.

Implementations

impl Envelope

pub fn success(data: impl Serialize, system: impl Into<String>) -> Self

Creates a success envelope from serializable data.

pub fn error( code: impl Into<String>, message: impl Into<String>, system: impl Into<String>, ) -> Self

Creates a generic error envelope.

pub fn error_detail( code: impl Into<String>, message: impl Into<String>, system: impl Into<String>, request_id: impl Into<String>, ) -> Self

Creates a structured error envelope with request id.

pub fn with_next_actions(self, actions: Vec<NextAction>) -> Self

Attaches suggested follow-up actions.

pub fn with_fix(self, fix: impl Into<String>) -> Self

Attaches recovery guidance for a failed command (no-op on success envelopes).

pub fn with_dry_run(self) -> Self

Marks the envelope as a dry-run response.

pub fn with_context( &mut self, command: &str, env: &str, identity: &str, duration: Duration, user_args: Option<Value>, effective_args: Option<Value>, )

Adds command execution context to envelope metadata.

pub fn prepare_for_render(&self, verbose: &str) -> Self

Returns a copy with metadata stripped or filtered according to --verbose.

pub fn add_warning(&mut self, message: impl Into<String>)

Appends a non-fatal warning.

Trait Implementations

impl Clone for Envelope

fn clone(&self) -> Envelope

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Envelope

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Envelope

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Envelope

fn eq(&self, other: &Envelope) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for Envelope

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Envelope