Crate osp_cli 

osp-cli exists to keep the canonical osp product surface in one crate.

The point of this crate is not just packaging. It is the place where the product’s main concerns meet: CLI host orchestration, layered config resolution, rendering, REPL integration, completion, plugins, and the pipeline DSL. Keeping those boundaries visible in one crate makes rustdoc a real architecture map instead of a thin wrapper over several mirrored packages.

Start here depending on what you need:

• app exists to turn the lower-level pieces into a running CLI or REPL process.
• cli exists to model the public command-line grammar.
• config exists to answer what values are legal, where they came from, and what finally wins.
• completion exists to rank suggestions without depending on terminal state or editor code.
• repl exists to own the interactive shell boundary.
• dsl exists to provide the canonical document-first pipeline language.
• ui exists to lower structured output into terminal-facing text.
• plugin exists to treat external command providers as part of the same command surface.
• services and ports exist for smaller embeddable integrations that do not want the whole host stack.
• api provides test-friendly fixtures and lightweight helper adapters rather than a second full integration surface.

Architecture contracts worth keeping stable:

• lower-level modules should not depend on app
• completion stays pure and should not start doing network, plugin discovery, or terminal I/O
• ui renders structured input but should not become a config-resolver or service-execution layer
• cli describes the grammar of the program but does not execute it
• config owns precedence and legality rules so callers do not invent their own merge semantics

Public API shape:

• semantic payload modules such as guide and most of completion stay intentionally cheap to compose and inspect
• host machinery such as app::App, app::AppBuilder, and runtime state is guided through constructors/builders/accessors rather than compatibility shims or open-ended assembly
• each public concept should have one canonical home; duplicate aliases and mirrored module paths are treated as API debt

Guided construction naming:

• Type::new(...) is the exact constructor when the caller already knows the required inputs
• Type::builder(...) starts guided construction for heavier host/runtime objects and returns a concrete TypeBuilder
• builder setters use with_* and the terminal step is always build()
• Type::from_* and Type::detect() are reserved for derived/probing factories
• semantic DSLs may keep domain verbs such as arg, flag, or subcommand; the with_* rule is for guided host configuration, not for every fluent API
• avoid abstract “factory builder” layers in the public API; callers should see concrete type-named builders and factories directly

For embedders:

• use app::App or app::AppBuilder for the full CLI/REPL host
• use app::AppState::builder when you need a manual runtime/session snapshot
• use app::UiState::builder and app::LaunchContext::builder for the heavier host-building blocks
• use repl::ReplRunConfig::builder and repl::HistoryConfig::builder when embedding the REPL editor surface directly
• use guide::GuideView and completion::CompletionTreeBuilder for semantic payload generation
• use services and ports when you want narrower integrations instead of the whole host stack

The root crate module tree is the only supported code path. Older mirrored layouts have been removed so rustdoc and the source tree describe the same architecture.

Re-exports

pub use crate::app::App;

pub use crate::app::AppBuilder;

pub use crate::app::AppRunner;

pub use crate::app::run_from;

pub use crate::app::run_process;

pub use crate::core::command_policy;

Modules

api

Test-friendly API adapters and mock implementations. Small public fixtures and helpers for embedding and examples.

app

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

cli

Command-line argument types and CLI parsing helpers. The CLI module exists to define the public command-line grammar of osp.

completion

Structured command and pipe completion types. Completion exists to turn a partially typed line plus cursor position into a ranked suggestion set.

config

Layered configuration schema, loading, and resolution. Configuration exists so the app can answer three questions consistently: what keys are legal, which source wins, and what file edits are allowed.

core

Shared command, output, row, and protocol primitives. Core primitives shared across the rest of the crate.

dsl

Canonical pipeline parsing and execution. Canonical document-first pipeline DSL.

guide

Structured help/guide view models and conversions. Structured help and guide payload model.

plugin

External plugin discovery, protocol, and dispatch support. The plugin module exists so external commands can participate in osp without becoming a separate execution model everywhere else in the app.

ports

Service-layer ports used by command execution. Small service-layer ports and helpers.

repl

The REPL module exists to own interactive shell behavior that the ordinary CLI host should not know about.

services

Library-level service entrypoints built on the core ports. Small embeddable service-layer command surface.

ui

Rendering, theming, and structured output helpers. The UI module exists to turn structured output into predictable terminal text, while keeping rendering decisions separate from business logic.

Macros

row

Builds a Row from literal key/value pairs.

Structs

NativeCommandCatalogEntry

Public metadata snapshot for one registered native command.

NativeCommandContext

Runtime context passed to native command implementations.

NativeCommandRegistry

Registry of in-process native commands exposed alongside plugin commands.

Enums

NativeCommandOutcome

Result of executing a native command.

Traits

NativeCommand

Trait implemented by in-process commands registered alongside plugins.