Module repl 

Interactive REPL editor, prompt, history, and completion surface. The REPL module exists to own interactive shell behavior that the ordinary CLI host should not know about.

The layering here is intentional:

• engine owns the line editor boundary, prompt rendering, history picker/completion adapters, and debug surfaces.
• dispatch owns command execution and shell-scope behavior once a line has been accepted.
• completion shapes the live command catalog into REPL-aware completion trees.
• presentation owns prompt appearance and intro/help material that is specific to interactive use.

A submitted line travels through the layers like this:

user keystrokes
      │
      ▼ [ engine ]    reedline editor, prompt, completion/history menus
      │ line accepted
      ▼ [ dispatch ]  execute command, apply shell scope and aliases
      │ ReplLineResult
      ├── Continue     → render output, show next prompt
      ├── ReplaceInput → update input buffer without printing
      ├── Restart      → [ lifecycle ] rebuild REPL state, loop again
      └── Exit         → return ReplRunResult to the caller

Embedders drive the loop with crate::repl::run_repl, configured through crate::repl::ReplRunConfig::builder. The engine, dispatch, and presentation layers are internal; only the config/result types cross the boundary.

Minimal embedder path:

use anyhow::Result;
use osp_cli::repl::{
    HistoryConfig, ReplLineResult, ReplPrompt, ReplRunConfig, run_repl,
};

let config = ReplRunConfig::builder(
    ReplPrompt::simple("osp> "),
    HistoryConfig::builder().build(),
)
.build();

let _result = run_repl(config, |line, _history| -> Result<ReplLineResult> {
    match line.trim() {
        "exit" | "quit" => Ok(ReplLineResult::Exit(0)),
        _ => Ok(ReplLineResult::Continue(String::new())),
    }
})?;

Choose crate::app instead when you want the full osp host with config loading, command dispatch, and rendering already wired together. Choose this module directly when you already own the execution callback and only want the interactive editor loop.

When debugging the REPL, first decide whether the issue is editor/runtime state, dispatch semantics, or rendering. That is usually enough to choose the right submodule.

Contract:

• this module may depend on editor/runtime adapters, completion, UI, and dispatch code
• it should not become the owner of generic command execution rules, config resolution, or non-interactive CLI parsing

Public API shape:

• primary host-facing entrypoints are crate::repl::run_repl, crate::repl::ReplRunConfig, crate::repl::HistoryConfig, and crate::repl::ReplPrompt
• debug snapshots and inspection helpers such as crate::repl::CompletionDebug and crate::repl::debug_completion stay available without becoming the default path for ordinary embedders
• host-style REPL configuration flows through concrete builders and factories such as crate::repl::ReplRunConfig::builder, crate::repl::ReplAppearance::builder, and crate::repl::HistoryConfig::builder
• guided REPL configuration follows the crate-wide naming rule: new(...) for exact constructors, builder(...) for staged configuration, with_* setters, and build() as the terminal step

Structs

CompletionDebug

Snapshot of completion/menu state for a given line and cursor position.

CompletionDebugFrame

One frame from a stepped completion-debug session.

CompletionDebugMatch

One rendered completion entry in the debug surface.

CompletionDebugOptions

Rendering and capture options for completion-debug helpers.

HighlightDebugSpan

Debug-friendly view of one highlighted span in the REPL line.

HistoryConfig

Configuration for REPL history persistence, visibility, and shell scoping.

HistoryConfigBuilder

Builder for HistoryConfig.

HistoryEntry

Visible history entry returned by listing operations after scope filtering.

HistoryShellContext

Shared shell-prefix state used to scope history to nested shell integrations.

LineProjection

Pre-processed editor input used for completion and highlighting.

ReplAppearance

Style overrides for REPL-only completion and highlighting chrome.

ReplAppearanceBuilder

Builder for ReplAppearance.

ReplPrompt

Static prompt text shown by the interactive editor.

ReplRunConfig

Editor-host configuration for one REPL run.

ReplRunConfigBuilder

Builder for ReplRunConfig.

SharedHistory

Thread-safe facade over the REPL history store.

Enums

DebugStep

Synthetic editor action used by completion-debug stepping.

ReplInputMode

Selects how aggressively the REPL should use the interactive line editor.

ReplLineResult

Outcome of executing one submitted REPL line.

ReplReloadKind

Controls how a command-triggered REPL restart should be presented.

ReplRunResult

Outcome of one run_repl session.

Functions

color_from_style_spec

Parses a REPL style string and extracts a terminal color.

debug_completion

Builds a single completion-debug snapshot for line at cursor.

debug_completion_steps

Replays a sequence of synthetic editor actions and captures each frame.

debug_highlight

Classifies a REPL line and returns serializable highlight spans for debugging tools.

debug_history_menu

Builds a single history-menu debug snapshot for line at cursor.

debug_history_menu_steps

Replays synthetic editor actions for the history menu and captures each frame.

default_pipe_verbs

Returns the default DSL verbs exposed after | in the REPL.

run_repl

Runs the interactive REPL and delegates submitted lines to execute.

Type Aliases

LineProjector

Projects a raw editor line into the view used by completion/highlighting.

PromptRightRenderer

Lazily renders the right-hand prompt for a REPL frame.