Module app 

Main host-facing entrypoints, runtime state, and session types. The app module exists to turn the library pieces into a running program.

This is the process-facing layer of the crate. It wires together CLI parsing, config loading, plugin/catalog setup, rendering, and REPL startup into the public App entrypoints. Lower-level modules like crate::config, crate::ui, and crate::repl stay reusable because this module is where the product-level orchestration happens.

Contract:

• this is allowed to depend on the rest of the crate because it is the host composition layer
• the dependency should not point the other way; lower-level modules should not import crate::app to get work done

Public API shape:

• most callers should start with App or App::builder
• embedders may inspect runtime/session state, but the preferred construction path still flows through a small number of builders and constructors here such as crate::app::AppStateBuilder
• lower-level semantic payloads live in modules like crate::guide and crate::completion; this module owns the heavier host machinery

Use this module when you want:

• the full CLI / REPL host in-process
• the same dispatch/help/completion/config behavior as osp
• a wrapper crate that injects native commands or product defaults

Skip this module and start lower if you only need:

• LDAP service execution plus DSL stages: crate::services
• rendering rows/documents: crate::ui
• pure completion trees or guide payloads: crate::completion or crate::guide

Broad-strokes host flow:

argv / REPL request
     │
     ▼ [ app ]    build host state, load config, assemble command catalog
     ▼ [ dispatch ] choose native or plugin command, run it
     ▼ [ dsl ]    apply trailing pipeline stages to command output
     ▼ [ ui ]     render text to a UiSink or process stdio

Most callers only need one of these shapes:

• App::run_from when they want a structured Result<i32>
• App::run_process when they want process-style exit code conversion
• App::with_sink or App::builder plus AppBuilder::build_with_sink when a test or outer host wants captured stdout/stderr instead of touching process stdio
• crate::services when this full host layer is more machinery than the integration needs

Downstream product-wrapper pattern:

• keep site-specific auth, policy, and integration state in the wrapper crate rather than in crate::app
• build a crate::NativeCommandRegistry for product-specific commands
• build one product-owned defaults layer under extensions.<site>.*
• inject both through App::builder, then AppBuilder::with_native_commands and AppBuilder::with_product_defaults
• expose a thin product-level run_process or builder() API on top instead of forking generic host behavior

Structs

App

Top-level application entrypoint for CLI and REPL execution.

AppBuilder

Builder for configuring an App before construction.

AppClients

Long-lived client registries shared across command execution.

AppRunner

Reusable runner that keeps an App paired with a borrowed UI sink.

AppRuntime

Runtime-scoped application state shared across commands.

AppSession

Session-scoped REPL state, caches, and prompt metadata.

AppSessionBuilder

Builder for AppSession.

AppState

Aggregate application state shared between runtime and session logic.

AppStateBuilder

Builder for AppState.

AuthState

Authorization and command-visibility state derived from configuration.

BufferedUiSink

Sink that buffers stdout and stderr for assertions and snapshot tests.

ConfigState

Holds the current resolved config plus a monotonic in-memory revision.

DebugTimingBadge

Timing badge rendered in the prompt for the most recent command.

DebugTimingState

Shared prompt-timing storage that dispatch code can update and prompt rendering can read.

LastFailure

Summary of the last failed REPL command.

LaunchContext

Startup inputs used to assemble runtime services and locate on-disk state.

ReplScopeFrame

One entered command scope inside the interactive REPL shell stack.

ReplScopeStack

Nested REPL command-scope stack used for shell-style scoped interaction.

RuntimeContext

Startup-time selection inputs that shape runtime config resolution.

StdIoUiSink

Sink that forwards output directly to the process stdio streams.

UiState

Derived presentation/runtime state for the active config snapshot.

Enums

TerminalKind

Identifies which top-level host surface is currently active.

Traits

UiSink

Terminal-facing output sink for stdout/stderr emission.

Functions

run_from

Runs the top-level CLI entrypoint from an argv-like iterator.

run_process

Runs the default application instance and returns a process exit code.

run_process_with_sink

Runs the default application instance with the provided sink.