Architecture

Package boundaries

Package	Purpose
Repl.Core	Dependency-free authoring/runtime core: routing, parsing, binding, output pipeline, CoreReplApp, IReplMap, Results.*
Repl.Defaults	DI-enabled facade (ReplApp), lifecycle orchestration, default composition profiles (UseDefaultInteractive, UseCliProfile)
Repl	Meta-package — bundles Core + Defaults + Protocol. Start here.
Repl.Protocol	Machine-readable contracts: help schemas, error contracts, minimal MCP manifest types
Repl.WebSocket	WebSocket transport for hosted sessions (ReplWebSocketSession over StreamedReplHost)
Repl.Telnet	Telnet session protocol (framing + NAWS negotiation) layered over Repl.WebSocket
Repl.Spectre	Spectre.Console integration: rich prompts, renderables, IAnsiConsole DI injection
Repl.Mcp	MCP server: UseMcpServer(), tool/resource/prompt mapping, MCP Apps, transport factory
Repl.Testing	In-memory multi-session test harness: ReplTestHost, ReplSessionHandle, typed results/events

Layering

┌────────────────────────────────────────────────────────┐
│                    Your application                     │
└──────────────┬─────────────────────────────────────────┘
               │ registers commands via
               ▼
┌──────────────────────────────────────────────────────────────────┐
│  Repl.Defaults  (ReplApp, UseDefaultInteractive, UseCliProfile)  │
│  Repl.Core      (routing, binding, output)                       │
└──────┬───────────────────────────────────────────────────────────┘
       │ dispatches to runtime channels
       ▼
┌────────────────────────────────────────────────────────────────────────────────────┐
│  Local console  │  Repl.WebSocket  │  Repl.Telnet  │  Repl.Mcp  │  Repl.Testing  │  custom…  │
└────────────────────────────────────────────────────────────────────────────────────┘

Repl.Core has no dependencies outside the .NET BCL. All integration packages depend on Core but not on each other — you pick what you need.

Execution pipeline

1. Parse — route matched, parameters bound and validated against constraints
2. Middleware — ordered pipeline of IReplMiddleware (auth, logging, tracing, etc.)
3. Dispatch — handler invoked via DI
4. Output — return value passed to the output transformer for the active channel
5. Render — formatter (text/JSON/YAML/XML/Spectre) writes to the channel’s output stream

Channel model

A channel is the transport through which a session runs. The same command graph is executed on all channels. Each channel implementation adapts input/output to its transport protocol.

Custom transports implement StreamedReplHost, which accepts any (TextReader, TextWriter) pair. The built-in Repl.WebSocket and Repl.Telnet packages are examples — SSH, named pipes, TCP sockets, or gRPC streams fit the same model.

Key abstractions

Type	Role
IReplMap	Registration interface — Map(...), Context(...), AutomationHidden(), AsResource()
IReplApp	Runtime interface — Run(args)
IReplInteractionChannel	Prompt/progress channel injected into handlers — namespace Repl.Interaction
ITerminalInfo	Session metadata (window size, ANSI capabilities) — namespace Repl.Interaction
IReplIoContext	Active I/O context (Output, Error, IsHostedSession, …)
Results	Semantic return helpers — Results.Success(msg), Results.Error(code, msg), Results.Cancelled(msg)

Source

Full architecture documentation (with diagrams): docs/architecture.md in the source repository.