Struct CliError 

pub struct CliError {
    pub kind: ExitKind,
    pub code: &'static str,
    pub message: String,
    pub details: Option<Value>,
}

Typed CLI error that carries an exit-code kind, a stable UPPER_SNAKE_CASE code (matching EngineError::code() for engine-sourced errors), and an optional structured details payload. Wrap with anyhow::Error via .into() or map_err to propagate up to main, which renders the error through output::print_cli_error in the documented {code, message, details} shape (or memstead: ERROR [<CODE>]: <message> on the text channel).

code is non-optional, so every construction site spells the wire token — there is no Option-default-to-INTERNAL fallback that could leak INTERNAL when a callsite forgets to set it. Engine-sourced errors capture EngineError::code() via CliError::from_engine_op; setup-layer paths pin their own typed token at construction time.

details is the structured recovery payload — e.g. HashMismatch populates {"current": "<hash>"} so scripts can lift the recovery hash without re-reading the entity. The renderer surfaces it under the details key of the JSON envelope.

Fields

kind: ExitKind

code: &'static str

message: String

details: Option<Value>

Implementations

impl CliError

pub fn new( kind: ExitKind, code: &'static str, message: impl Into<String>, ) -> Self

Construct a typed CLI error with an exit-kind, wire code, and human message. Every callsite spells the code at construction time — there is no Option-default-to-INTERNAL fallback. Use INTERNAL_CODE explicitly for genuinely-systemic paths.

pub fn with_details(self, details: Value) -> Self

pub fn with_code(self, code: &'static str) -> Self

Override the wire code on an existing CliError. This helper exists for callsites that build an error in steps (e.g. setup layers that mint the error before knowing whether to retag it with a more specific code). New code should spell the final code at CliError::new construction time.

pub fn effective_code(&self) -> &'static str

Field accessor preserved as a method for backward compatibility with the previous Option<&'static str> API. Now a trivial self.code return; kept so existing call sites don’t need to flip method-call syntax to field-access syntax.

pub fn from_engine_op(e: EngineError) -> Self

Map an memstead_base::EngineError to a typed CLI error with the right exit code (NOT_FOUND → 3, HASH_MISMATCH → 4, validation errors → 5, everything else → 1) and the typed wire code from EngineError::code(). Recovery payloads (HashMismatch.current, HasIncomingRefs.referrers, WikiLinkWithoutRelation.missing, etc.) land under details so --json callers consume the same {code, message, details} envelope they get over MCP — bit-identical wire shape across surfaces is the agent contract this method delivers.

Trait Implementations

impl Debug for CliError

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

Formats the value using the given formatter.

impl Display for CliError

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

Formats the value using the given formatter.

impl Error for CliError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.